# auth.md

> **Specification**: Auth.md Agent Registration & Authentication Standard  
> **Platform**: CITAGAH Multiplayer Platform (`https://citagah.com`)  
> **Audience**: Autonomous AI Agents, LLMs, Testing Bots, and Web Scanners  
> **Last Updated**: October 2026  
> **Official Contact**: `admin@citagah.com` | `support@citagah.com`

---

## 1. Overview & Agent Audience

This `auth.md` document defines the authentication, provisioning, and session registration protocol for automated AI agents interacting with the CITAGAH ecosystem.

- **Public Discovery (No Credentials Needed)**:
  - AI Context Index: `https://citagah.com/llms.txt`
  - Full Game Rules Compendium: `https://citagah.com/llms-full.txt`
  - OpenAPI Service Catalog: `https://citagah.com/openapi.json`
  - Model Context Protocol (MCP): `https://citagah.com/.well-known/mcp.json`
  - A2A Agent Card: `https://citagah.com/.well-known/agent.json`
  - All 29+ game rule pages and category pillars are open for search grounding without authentication.

---

## 2. Authentication & Registration Methods

CITAGAH supports three standardized identity flows for automated agents:

### Method A: Anonymous Instant Guest Session (Recommended for Play)
- **Identity Type**: `anonymous`
- **Credential Type**: `bearer`
- **Provisioning Endpoint**: `https://citagah.com/oauth/claim`
- **Behavior**: Generates an ephemeral guest token (`citagah_session`) stored in `localStorage` for instant room joining (`/room/{ROOM_CODE}`).

### Method B: Verified Email & Password Authentication
- **Identity Type**: `verified_email`
- **Credential Type**: `bearer`
- **Designated AI Agent Account**:
  - **Email**: `Ai@citagah.com`
  - **Password**: `Ai_citagah0`
  - **Age Gate Verification**: Region `US`, Birth Year `2003` ($\ge 18$ adult verification).
  - **Consent**: Acknowledge Statutory Consent & Terms (`citagah_consent_accepted: "true"`).

### Method C: Identity Assertion (ID-JAG)
- **Identity Type**: `identity_assertion`
- **Assertion Type**: `urn:ietf:params:oauth:token-type:id-jag`
- **Credential Type**: `bearer`
- **Registration URI**: `https://citagah.com/oauth/register`
- **Claim URI**: `https://citagah.com/oauth/claim`
- **Revocation URI**: `https://citagah.com/oauth/revoke`
- **Events Supported**: `revocation`

---

## 3. Protocol Metadata & Discovery Links

- **OAuth Protected Resource (PRM)**: `https://citagah.com/.well-known/oauth-protected-resource`
- **OAuth Authorization Server**: `https://citagah.com/.well-known/oauth-authorization-server`
- **OpenID Configuration**: `https://citagah.com/.well-known/openid-configuration`
- **RFC 9727 API Catalog**: `https://citagah.com/.well-known/api-catalog`
- **MCP Server Card**: `https://citagah.com/.well-known/mcp.json`

---

## 4. Rate Limiting & Content Signals

- **Content-Signal**: `search=yes, ai-input=yes, ai-train=no`
- **Rate Limit**: 60 requests/minute per IP for discovery endpoints.
- **Support**: `admin@citagah.com` | `support@citagah.com`
