# auth.md

You are an agent. This document describes how to discover and use Drunk Monk Studios' public
HTTP surfaces, and how humans register optional accounts. It is the Auth.md skill for
this origin.

## Audience

- **Public site API agents:** call the read-only [Site API](https://drunkmonkstudios.com/site-api) without creating
  an account or presenting credentials.
- **Human account holders:** optional email and password accounts for admin and signed-in
  browser features. Sign-in and create-account links are **not** shown in the public site
  chrome. Only scanners and people who already know `/signup` /
  `/login` reach those UIs.

Drunk Monk Studios browser games (Hex Path, Snap Judgments / Stereotypes) run anonymously in the
browser. They are not an OAuth-protected agent API.

**Hard rules for agents**

- Do **not** `POST` to `/agent/auth`, `/agent/identity`, or any invented registration
  API on this origin. Passive scans must use only the public discovery documents below.
- Do **not** scrape, fill, or automate `/signup` or `/login`.
  Those pages are human-attended browser UIs with anti-abuse controls. Automating them is
  abuse, not Auth.md registration.
- Prefer anonymous Site API access. Optional accounts exist for humans (admins), not for
  minting agent credentials.

## Step 1 — Discover

### 1a. Protected Resource Metadata

```http
GET /.well-known/oauth-protected-resource
```

Document URL: https://drunkmonkstudios.com/.well-known/oauth-protected-resource

Required fields:

- `resource` — canonical URL of this site (`https://drunkmonkstudios.com`)
- `authorization_servers` — `["https://drunkmonkstudios.com"]`
- `scopes_supported` — `["site:read"]` for the public Site API
- `bearer_methods_supported` — `["header"]` when a bearer credential is used

### 1b. Authorization Server metadata

```http
GET /.well-known/oauth-authorization-server
```

Document URL: https://drunkmonkstudios.com/.well-known/oauth-authorization-server

Read `issuer` (must be `https://drunkmonkstudios.com`) and the `agent_auth` block:

- `skill` — this document (https://drunkmonkstudios.com/auth.md)
- `register_uri` — primary registration surface (https://drunkmonkstudios.com/signup)
- `identity_types_supported` — `anonymous` and `identity_assertion` (verified email)

## Step 2 — Pick a method

1. **You only need the public Site API** → [anonymous](#anonymous). No credentials.
2. **A human needs an optional Drunk Monk Studios account** → [verified email](#verified-email).
3. **ID-JAG / WorkOS agent identity exchange** → not supported on this origin. Do not call
   `/agent/identity`, `/oauth2/token`, or similar endpoints here.

## Step 3 — Register

### anonymous

No registration request is required for `site:read`.

1. Call `https://drunkmonkstudios.com/api/site` (and related Site API paths) with `GET` or `HEAD`.
2. Do not send an `Authorization` header.
3. Do not `POST` to agent registration endpoints; this origin does not create agent
   accounts for anonymous Site API access.

If a human later wants an optional account, use `https://drunkmonkstudios.com/signup` (`claim_uri` /
`register_uri` in Authorization Server metadata).

Credential type: `none`.

### verified email

Optional human accounts use email and password. There is no agent-callable registration
endpoint and no token exchange for this method.

1. Direct a **human** to `https://drunkmonkstudios.com/signup` (`register_uri` / `claim_uri`). Do not open
   that URL yourself as an automated client beyond a single discovery mention.
2. The human submits email, password (at least six characters), and an optional display
   name through the signup UI. Supabase Auth stores the account when configured. The form
   rejects scripted/fast submits and traps honeypot fields.
3. After email confirmation (when enabled), the human signs in at `https://drunkmonkstudios.com/login`.

Assertion type: `verified_email`. Credential type: `password`.

Do not invent password credentials. Do not scrape, brute-force, or automate the signup or
sign-in forms. Do not create accounts in bulk.

## Step 4 — Claim ceremony

This origin does not run a device-code or agent claim ceremony
(`claim_ceremony_supported` is `false`). Optional account binding happens only through
the human signup UI at `https://drunkmonkstudios.com/signup`.

## Step 5 — Credentials and token exchange

This origin does **not** issue OAuth access tokens for agents.

- `grant_types_supported` is empty in Authorization Server metadata.
- There is no `token_endpoint` and no JWT-bearer exchange.
- The public Site API authorizes `site:read` without a bearer token.

If you receive a `401` from another Drunk Monk Studios dependency (for example Supabase), follow
that service's own discovery documents. Do not assume this origin's Auth.md covers it.

## Step 6 — Use the Site API

```http
GET /api/site
Accept: application/json
```

Example entry point: https://drunkmonkstudios.com/api/site

Use `GET` or `HEAD` only. Other methods receive `405 Method Not Allowed`. Full
operation list: https://drunkmonkstudios.com/site-api and https://drunkmonkstudios.com/api/site/openapi.json.

When a browser session exists after human login, the web app may send Supabase session
credentials to online multiplayer backends. That path is for the first-party client, not
for third-party agents.

## Errors

| Situation | Expected behavior |
| --- | --- |
| `POST` / `PUT` / `PATCH` / `DELETE` on Site API paths | `405` with `Allow: GET, HEAD` |
| Missing Auth.md or well-known documents | Should not happen on this origin; refetch absolute URLs above |
| Agent calls `/agent/identity` or `/oauth2/token` here | Not offered; treat as unsupported |
| Signup when Supabase is not configured | Human UI reports that auth is unavailable |

## Revocation

- **Anonymous Site API access:** nothing to revoke; stop calling the API.
- **Human accounts:** humans sign out in the app or contact support. This origin does not
  publish `revocation_endpoint` or agent revocation events.

## Links

- Site API docs: https://drunkmonkstudios.com/site-api
- Protected Resource Metadata: https://drunkmonkstudios.com/.well-known/oauth-protected-resource
- Authorization Server metadata: https://drunkmonkstudios.com/.well-known/oauth-authorization-server
- Terms: https://drunkmonkstudios.com/terms
- Privacy: https://drunkmonkstudios.com/privacy
