# auth.md

This file is for an agent that wants to read https://apologetics.wiki or to suggest a change.

## Audience

Anyone can register an OAuth client and sign in. Signing in is not authorship. A new account is a suggester. A contributor is a reviewed author, granted by an admin after the account is reviewed. An admin is set manually. An account is active or suspended.

## Registration

Agent registration is dynamic client registration, then a verified-email sign-in. `agent_auth` on `/.well-known/oauth-authorization-server` and `/.well-known/openid-configuration` is:

```json
{
  "skill": "https://apologetics.wiki/auth.md",
  "register_uri": "https://apologetics.wiki/oauth/register",
  "identity_types_supported": [
    "identity_assertion"
  ],
  "identity_assertion": {
    "assertion_types_supported": [
      "verified_email"
    ],
    "credential_types_supported": [
      "oauth_access_token"
    ],
    "claim_uri": "https://apologetics.wiki/oauth/authorize"
  }
}
```

`register_uri` accepts an OAuth client. Use PKCE S256. Redirect URIs may be https, http on a loopback host (127.0.0.1, localhost, or ::1, any port), or `cursor://`, `vscode://`, `vscode-insiders://`, and `claude://`. Other private schemes, fragments, userinfo, and non-loopback http are refused.

The method is `identity_assertion`. `assertion_types_supported` is `verified_email`. GitHub is the preferred sign-in, because the login helps us vet people. An emailed one-time code is the fallback. The code lasts about 10 minutes, works once, and is stored hashed. The response is the same for every address.

`identity_assertion` carries `credential_types_supported` (`oauth_access_token`) and `claim_uri`, the page where that person signs in.

## Scopes

- `read` — public pages. Read tools also work with no token.
- `suggest` — submit a suggestion or a draft article. Nothing is published from this scope.
- `offline_access` — a refresh token.

## Credential use

Send the access token as `Authorization: Bearer`. Tokens are opaque. The JSON Web Key Set at `https://apologetics.wiki/.well-known/jwks.json` is empty on purpose. Access tokens last one hour. Refresh tokens last 30 days. Unused dynamically registered clients expire after 30 days.

A tool that needs `suggest` answers HTTP 401 with `WWW-Authenticate: Bearer realm="apologetics.wiki"` and the protected-resource metadata URL when the token is missing. A token without `suggest` answers HTTP 403 `insufficient_scope`.

## Roles and the review queue

Every suggestion is stored under the account (display name, and the GitHub login when there is one) with status pending. A contributor is flagged `trusted_author` and has a higher daily cap. The flag does not publish the page. An admin can mark a queue row accepted, rejected, needs changes, or published. Published is a queue status. The site changes only when a human edits the repository.

## Rate limits

- **Anonymous reads (tools/list, read tools, public JSON):** 60 per minute per IP
- **Signed-in MCP calls:** 120 per minute per account
- **Suggestion submits:** 5 per minute per account; 20 per day for a suggester; 60 per day for a contributor; 500 per day for the whole site
- **OAuth client registration:** 10 per minute per IP; 30 per day per IP; 300 per day for the whole site
- **Email code requests:** 5 per minute per IP; 3 per 15 minutes per address; 10 per day per address; 200 outbound messages per day
- **Code verification:** 20 per minute per IP; 5 attempts per code
- **Token endpoint:** 30 per minute per IP
- **GitHub callback:** 10 per minute per IP
- **MCP request body:** 128 KB
- **OAuth request body:** 16 KB
- **JSON-RPC batch:** 10 calls