# auth.md

How an AI agent authenticates with Dark Blue.

This site is a marketing site, and nearly all of it is open: every page, and every
tool on the MCP server at `https://www.dark.blue/api/mcp`, can be read with no
credential at all. Authentication exists here for the one thing that is not open,
and for the demonstration of the flow itself.

## What is behind the token

`GET https://www.dark.blue/api/agent/easter-egg`, and the `find_easter_egg` tool on the MCP
server. Both return the same thing: a message, and the identity of whoever the
token was issued to. It is an easter egg. Nothing here is sensitive, and no part of
this document is a claim that it is.

## agent_auth

The same block is published in the authorization server metadata at
https://www.dark.blue/.well-known/oauth-authorization-server, and is repeated here so this
document stands on its own:

```json
{
  "agent_auth": {
    "skill": "https://www.dark.blue/auth.md",
    "register_uri": "https://www.dark.blue/api/oauth/register",
    "authorization_uri": "https://www.dark.blue/oauth/authorize",
    "token_uri": "https://www.dark.blue/api/oauth/token",
    "jwks_uri": "https://www.dark.blue/.well-known/jwks.json",
    "identity_types_supported": [
      "anonymous"
    ],
    "credential_types_supported": [
      "oauth2_access_token"
    ],
    "registration_methods_supported": [
      "dynamic_client_registration"
    ],
    "handoff_redirect_uri": "https://www.dark.blue/oauth/handoff",
    "grant_types_supported": [
      "authorization_code"
    ],
    "code_challenge_methods_supported": [
      "S256"
    ],
    "scopes_supported": [
      "openid",
      "profile",
      "easter-egg"
    ],
    "resources_supported": [
      "https://www.dark.blue",
      "https://www.dark.blue/api/mcp"
    ]
  }
}
```

There is no revocation_uri and no claim_uri, because this server has neither. See
step 6.

## 1. Discover

The authorization server is described at:

```
https://www.dark.blue/.well-known/oauth-authorization-server
https://www.dark.blue/.well-known/openid-configuration
```

The protected resources are described at:

```
https://www.dark.blue/.well-known/oauth-protected-resource
https://www.dark.blue/.well-known/oauth-protected-resource/api/mcp
```

The first of those is this origin's HTTP API; the second is the MCP server.

A request to a protected endpoint without a valid token answers `401` with a
`WWW-Authenticate` header naming the metadata document for that resource, so the
chain can be entered from any protected URL without reading this file first.

## 2. Register

Registration is open and needs no prior relationship. There is no approval step and
no waiting: POST your client metadata (RFC 7591) and the response carries a
`client_id` you can use immediately.

```http
POST https://www.dark.blue/api/oauth/register
Content-Type: application/json
```

with the body:

```json
{
  "client_name": "Your agent",
  "redirect_uris": ["https://your-agent.example/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

Register the redirect URI you can actually receive a code on. If you have nowhere
to receive one, register `https://www.dark.blue/oauth/handoff` and read step 4 —
this site will hold the code for you.

The `client_id` you get back is a signed document containing the metadata you
registered. There is no client secret and none is accepted: clients here are
public, and PKCE is what proves a token request came from the client that started
the flow. Keep the `client_id` — re-registering is harmless, but pointless.

## 3. Claim

There is no separate claim ceremony. This server accepts one identity type,
`anonymous`: an agent brings no assertion of its own and instead borrows the
session of a human who signs in during the next step. No ID-JAG assertion, no
service credential, and no email verification is involved.

## 4. Exchange

Standard authorization code with PKCE (RFC 7636), which is required — an
authorization request without `code_challenge_method=S256` is refused.

Send the human to:

```
https://www.dark.blue/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REGISTERED_REDIRECT_URI
  &code_challenge=BASE64URL_SHA256_OF_YOUR_VERIFIER
  &code_challenge_method=S256
  &scope=openid%20easter-egg
  &resource=https%3A%2F%2Fwww.dark.blue%2Fapi%2Fmcp
  &state=YOUR_STATE
```

They enter the site's access password, and the code comes back on your
`redirect_uri` — which is the step that most often goes wrong. Pick whichever of
these three describes you.

**Your client already speaks OAuth.** If you can add an MCP server, add
`https://www.dark.blue/api/mcp`
as one and let the client run this flow: it will open the page, catch the redirect
and store the token, and none of the rest of this section is your problem.

**You can listen on a port.** Register `http://localhost:PORT/callback` and
**start listening before you send the human anywhere**. An agent that registers a
loopback URI and never binds it turns the redirect into a failed page load, and the
human into a courier — which works, but only because they read the code out of
their address bar for you.

**You cannot receive a redirect at all.** Register
`https://www.dark.blue/oauth/handoff`. The code lands on a page on this site that
explains what happened and shows the human one line to paste back to you, formatted
as a query string so you can read it with a URL parser rather than by hand:

```
code=THE_CODE&state=YOUR_STATE
```

Ask for that paste in one message, and wait for it before doing anything else.

Either way the code is good for 5 minutes:
long enough for a person to copy it, not long enough to leave lying around.

Exchange it at `https://www.dark.blue/api/oauth/token`:

```
grant_type=authorization_code
&code=THE_CODE
&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
&client_id=YOUR_CLIENT_ID
&code_verifier=YOUR_VERIFIER
&resource=https%3A%2F%2Fwww.dark.blue%2Fapi%2Fmcp
```

`resource` (RFC 8707) names which of the two resources above the token is for,
and lands in the token's `aud`. Omit it and you get a token for the MCP server,
which `/api/agent/easter-egg` accepts as well — so a client that does not
implement resource indicators still works. Request `openid` and an ID token
comes back alongside the access token; `https://www.dark.blue/api/oauth/userinfo` returns
the same claims.

## 5. Use

Bearer token in the `Authorization` header — the only method supported:

```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

Access tokens last 24 hours. Signatures verify against
`https://www.dark.blue/.well-known/jwks.json` (ES256).

## 6. Revoke

There is no revocation endpoint, and this is the one place where cheap and correct
part company. Tokens are self-contained and are trusted until they expire; the only
way to invalidate one early is to rotate the signing key, which invalidates every
token at once. That is an acceptable trade for an easter egg and would not be for
anything else.
