# Auth.md

This service supports autonomous agentic registration, user authorization, and OAuth 2.0 / OIDC authentication via the **Auth.md** protocol.

- **Resource Server**: `https://curadate.com`
- **Authorization Server**: `https://curadate.com`
- **Protected Resource Metadata**: `/.well-known/oauth-protected-resource` (RFC 9728)
- **Authorization Server Metadata**: `/.well-known/oauth-authorization-server` (RFC 8414)
- **OpenID Connect Discovery**: `/.well-known/openid-configuration`
- **Scopes Catalog & ABAC Matrix**: `/api/oauth/scopes`
- **Specification**: Auth.md v1.2 / RFC 8414 / RFC 7591 / RFC 9396 / RFC 9449 / RFC 9126 / RFC 8628 / RFC 9421 / RFC 9728

---

# Auth.md: Agent Registration & Authentication Specification

Welcome to the **Curadate Authentication, OAuth 2.0, OpenID Connect & Dynamic Agent Registration** specification (`Auth.md`). This document provides machine-readable and human-readable guidance for AI agents, autonomous bots, web crawlers, and third-party partner applications to discover, register, authenticate, and interact with the Curadate Dating Platform.

---

## Step 1 — Discover

Agents, headless clients, and OAuth clients can discover authorization server capabilities, resource metadata, and available endpoints through well-known metadata files or challenge headers.

### Discovery Endpoints

| Protocol / Standard | Endpoint | Content-Type |
|---|---|---|
| **Auth Specification** | `/auth.md` | `text/markdown` |
| **OAuth 2.0 Protected Resource Metadata (RFC 9728)** | `/.well-known/oauth-protected-resource` | `application/json` |
| **OAuth Protected Resource JSON** | `/.well-known/oauth-protected-resource.json` | `application/json` |
| **OAuth 2.0 Auth Server Metadata (RFC 8414)** | `/.well-known/oauth-authorization-server` | `application/json` |
| **OpenID Connect Discovery 1.0** | `/.well-known/openid-configuration` | `application/json` |
| **OAuth 2.0 Scopes Catalog** | `/api/oauth/scopes` | `application/json` |
| **Client Authentication Methods** | `/api/oauth/client-auth-methods` | `application/json` |
| **Combined OAuth Metadata Catalog** | `/api/oauth/metadata` | `application/json` |
| **API Catalog (RFC 9727 / RFC 9264)** | `/.well-known/api-catalog` | `application/linkset+json` |
| **Agentic Resource Discovery (ARD)** | `/.well-known/ard.json` | `application/json` |
| **Agent Tools Manifest** | `/.well-known/agent.json` | `application/json` |
| **Web Bot Key Set (JWKS)** | `/.well-known/jwks.json` | `application/json` |
| **DNS-AID Manifest** | `/.well-known/dns-aid.json` | `application/json` |
| **Security Disclosure (RFC 9116)** | `/.well-known/security.txt` | `text/plain` |
| **API Rate Limits Spec** | `/api/rate-limits/spec` | `application/json` |

### OAuth 2.0 Protected Resource Metadata (RFC 9728)

When an unauthenticated request hits a protected resource (e.g. `GET /api/matches`), the server returns an HTTP `401 Unauthorized` with an RFC 9728 `WWW-Authenticate` challenge header:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="curadate",
  resource_metadata="https://curadate.com/.well-known/oauth-protected-resource",
  scope="dating.matches"
Link: <https://curadate.com/.well-known/oauth-protected-resource>; rel="oauth-protected-resource"
```

The protected resource document at `/.well-known/oauth-protected-resource` returns:

```json
{
  "resource": "https://curadate.com",
  "authorization_servers": [
    "https://curadate.com",
    "https://accounts.google.com"
  ],
  "scopes_supported": [
    "openid", "profile", "email", "offline_access",
    "dating.read", "dating.write", "dating.like", "dating.matches", "dating.profile", "dating.location",
    "agent.match", "agent.chat", "agent.icebreaker", "agent.delegate", "ai.intent", "ai.compatibility",
    "mcp.tools",
    "messages.read", "messages.write", "media.upload", "media.voice_intro",
    "calls.initiate", "calls.participate",
    "presence.status",
    "safety.report", "history.export",
    "admin.audit", "admin.metrics",
    "partner.federate"
  ],
  "bearer_methods_supported": [
    "header"
  ],
  "resource_documentation": "https://curadate.com/auth.md",
  "dpop_signing_alg_values_supported": [
    "ES256", "RS256", "EdDSA"
  ]
}
```

---

## Step 2 — Auth.md Agent Registration & Protocol Flows

Curadate supports autonomous agentic onboarding and OAuth 2.0 / OIDC authentication via the **Auth.md** protocol.

### Agent Auth Block (`agent_auth`)

Advertised at `/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource`:

```json
{
  "skill": "https://curadate.com/auth.md",
  "register_uri": "https://curadate.com/api/oauth/register",
  "identity_endpoint": "https://curadate.com/api/oauth/register",
  "claim_endpoint": "https://curadate.com/api/oauth/claims",
  "claim_uri": "https://curadate.com/api/oauth/claims",
  "revocation_uri": "https://curadate.com/api/oauth/revoke",
  "identity_types_supported": ["anonymous", "identity_assertion", "agent", "service", "user_delegated"],
  "identity_assertion": {
    "assertion_types_supported": [
      "urn:ietf:params:oauth:token-type:id-jag",
      "verified_email"
    ],
    "credential_types_supported": [
      "bearer_token",
      "http_message_signature",
      "client_secret",
      "private_key_jwt"
    ]
  },
  "anonymous": {
    "credential_types_supported": [
      "bearer_token",
      "client_secret"
    ]
  },
  "events_supported": [
    "revocation",
    "token_revoked"
  ]
}
```

### Supported Flow Metadata

1. **ID-JAG (Identity Assertion for JSON Agentic Grants)**
   - `identity_types_supported`: `["identity_assertion"]`
   - `identity_assertion.assertion_types_supported`: `["urn:ietf:params:oauth:token-type:id-jag"]`
   - `credential_types_supported`: `["bearer_token", "http_message_signature", "client_secret", "private_key_jwt"]`
   - Revocation: `revocation_uri: https://curadate.com/api/oauth/revoke`, `events_supported: ["token_revoked"]`

2. **Verified Email Assertion**
   - `identity_types_supported`: `["identity_assertion"]`
   - `identity_assertion.assertion_types_supported`: `["verified_email"]`
   - `credential_types_supported`: `["bearer_token", "client_secret"]`
   - `claim_uri`: `https://curadate.com/api/oauth/claims`

3. **Anonymous Agent Registration**
   - `identity_types_supported`: `["anonymous"]`
   - `anonymous.credential_types_supported`: `["bearer_token", "client_secret"]`
   - `claim_uri`: `https://curadate.com/api/oauth/claims`

---

## Step 3 — Pick an Authentication & Grant Method

Curadate supports multiple client profiles and authorization grant types tailored for human users, mobile apps, autonomous AI agents, and server-to-server microservices.

### Supported Grant Types (`grant_types_supported`)

1. **Authorization Code with PKCE (RFC 7636 / RFC 6749)**
   - *Use Case*: Single-Page Apps (SPA), mobile applications, and interactive user consent.
   - *Endpoint*: `GET /oauth/authorize` & `POST /oauth/token`
   - *Code Challenge Method*: `S256` mandatory for public clients.

2. **Client Credentials (RFC 6749)**
   - *Use Case*: Autonomous AI agents, background matchmaking bots, server-to-server microservices.
   - *Endpoint*: `POST /oauth/token`
   - *Client Authentication*: `client_secret_basic`, `client_secret_post`, `private_key_jwt` (RFC 7523).

3. **Rich Authorization Requests (RAR - RFC 9396)**
   - *Use Case*: Granular envelope authorization for matchmaking delegation (min compatibility thresholds, agent turn ceilings, sandboxing).
   - *Parameter*: `authorization_details` array in authorize/token requests.

4. **Pushed Authorization Requests (PAR - RFC 9126)**
   - *Use Case*: High-security back-channel authorization parameter registration yielding short-lived `request_uri` pointers.
   - *Endpoint*: `POST /api/oauth/par`

5. **Device Authorization Grant (RFC 8628)**
   - *Use Case*: Headless agents, CLI tools, smart displays, and IoT devices with out-of-band user verification.
   - *Endpoint*: `POST /api/oauth/device` (User Code: `CURA-XXXX`)

6. **Demonstrating Proof-of-Possession (DPoP - RFC 9449)**
   - *Use Case*: Cryptographic key-binding of access tokens to prevent token theft and replay attacks.
   - *Header*: `DPoP: <jwt_proof>`

7. **HTTP Message Signatures & WebBotAuth (RFC 9421)**
   - *Use Case*: Autonomous AI crawlers and bots declaring bot identity verified via JWKS public keys.
   - *Endpoint*: `GET /api/bot-auth` & `/.well-known/web-bot-auth.json`

---

## Step 3 — Dynamic Client Registration (RFC 7591)

Autonomous agents and third-party clients can register dynamically without prior manual provisioning.

### Registration Endpoint: `POST /api/oauth/register`

#### Request Payload:
```json
{
  "client_name": "Autonomous Matchmaker Bot v2",
  "redirect_uris": [
    "https://agent-client.example.com/oauth/callback"
  ],
  "grant_types": [
    "authorization_code",
    "client_credentials",
    "refresh_token"
  ],
  "response_types": [
    "code"
  ],
  "token_endpoint_auth_method": "client_secret_post",
  "scope": "openid profile dating.read dating.matches agent.match ai.compatibility mcp.tools",
  "contacts": [
    "dev-agent@curadate.com"
  ],
  "dpop_bound_access_tokens": true,
  "software_id": "com.curadate.agent.matchmaker",
  "software_version": "2.4.0"
}
```

#### Registration Response (`201 Created`):
```json
{
  "client_id": "cura_client_a98b7c6d5e",
  "client_secret": "cura_sec_f1e2d3c4b5a6",
  "client_secret_expires_at": 0,
  "client_id_issued_at": 1772345600,
  "client_name": "Autonomous Matchmaker Bot v2",
  "redirect_uris": [
    "https://agent-client.example.com/oauth/callback"
  ],
  "grant_types": [
    "authorization_code",
    "client_credentials",
    "refresh_token"
  ],
  "response_types": [
    "code"
  ],
  "token_endpoint_auth_method": "client_secret_post",
  "scope": "openid profile dating.read dating.matches agent.match ai.compatibility mcp.tools",
  "registration_client_uri": "https://curadate.com/api/oauth/register/cura_client_a98b7c6d5e",
  "registration_access_token": "cura_reg_98f7e6d5c4b3a2"
}
```

---

## Step 4 — Authorization Code & Token Exchange

### Authorization Request with PKCE
```http
GET /oauth/authorize?
  response_type=code&
  client_id=cura_client_a98b7c6d5e&
  redirect_uri=https%3A%2F%2Fagent-client.example.com%2Foauth%2Fcallback&
  scope=openid%20profile%20dating.read%20dating.matches%20agent.match&
  state=xyzState123&
  code_challenge=E9Mel-dB5aZ96kLG2091_QXFrqvmtpkcwS953STG0VQ&
  code_challenge_method=S256 HTTP/1.1
Host: curadate.com
```

### Token Exchange Request
```http
POST /oauth/token HTTP/1.1
Host: curadate.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=cura_code_4f89a2c1&
redirect_uri=https%3A%2F%2Fagent-client.example.com%2Foauth%2Fcallback&
client_id=cura_client_a98b7c6d5e&
client_secret=cura_sec_f1e2d3c4b5a6&
code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
```

### Token Response (`200 OK`)
```json
{
  "access_token": "cura_at_98a7c2e1f4b5d6a7b8c9d0e1",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "cura_rt_5e4d3c2b1a0f9e8d7c6b5a4",
  "scope": "openid profile dating.read dating.matches agent.match",
  "id_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCI..."
}
```

---

## Step 5 — Rich Authorization Requests (RAR - RFC 9396)

For high-trust autonomous dating agent operations, Curadate implements **RFC 9396 Rich Authorization Requests**. Clients can specify authorization constraints inside an `authorization_details` object:

```json
[
  {
    "type": "dating_matchmaking_action",
    "actions": ["like", "evaluate_compatibility", "draft_icebreaker"],
    "min_compatibility_score": 85,
    "max_agent_turns": 5,
    "delegation_mode": "supervised_confirmation",
    "mcp_sandbox_tier": "sandbox"
  }
]
```

---

## Step 6 — Token Introspection & Revocation

### Token Introspection (RFC 7662)
```http
POST /api/oauth/introspect HTTP/1.1
Host: curadate.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Y3VyYV9jbGllbnRfYTk4YjdjNmQ1ZTpjdXJhX3NlY19mMWUyZDNjNGI1YTY=

token=cura_at_98a7c2e1f4b5d6a7b8c9d0e1
```

#### Response:
```json
{
  "active": true,
  "scope": "openid profile dating.read dating.matches agent.match",
  "client_id": "cura_client_a98b7c6d5e",
  "sub": "usr_998124a7",
  "exp": 1772349200,
  "iat": 1772345600,
  "iss": "https://curadate.com",
  "token_type": "Bearer"
}
```

### Token Revocation (RFC 7009)
```http
POST /api/oauth/revoke HTTP/1.1
Host: curadate.com
Content-Type: application/x-www-form-urlencoded

token=cura_at_98a7c2e1f4b5d6a7b8c9d0e1&
token_type_hint=access_token
```

---

## Step 7 — Complete OAuth Scopes Catalog (29 Scopes)

Curadate Dating enforces strict Attribute-Based Access Control (ABAC) across 10 functional scope categories:

### 1. Identity & OpenID Connect Scopes
| Scope | Risk Level | Target Routes | Description |
|---|---|---|---|
| `openid` | Low | `/api/oauth/userinfo` | OIDC Subject Identifier (sub) & token issuance. |
| `profile` | Low | `/api/oauth/userinfo`, `/api/profile` | Read standard user display profile, bio, intent, and lifestyle attributes. |
| `email` | Medium | `/api/oauth/userinfo` | Read verified user email address. |
| `offline_access` | Medium | `/oauth/token` | Issue refresh token for background offline execution. |

### 2. Dating & Profiles Scopes
| Scope | Risk Level | Target Routes | Description |
|---|---|---|---|
| `dating.read` | Low | `/api/profiles`, `/api/profiles/:id` | Browse candidate profiles, public prompts, and relationship intents. |
| `dating.write` | Medium | `/api/profile`, `/api/profile/prompts` | Update own dating bio, lifestyle values, and relationship dealbreakers. |
| `dating.like` | Medium | `/api/matches/like`, `/api/sparks/send` | Dispatch likes, super-likes, and intentional spark comments. |
| `dating.matches` | Medium | `/api/matches`, `/api/matches/:id` | Query active mutual match pairings and compatibility scores. |
| `dating.profile` | Medium | `/api/profile` | Full management of profile stories, prompt galleries, and questionnaires. |
| `dating.location` | Low | `/api/location/nearby` | Read/update geographic search radius and proximity calculations. |

### 3. AI & Autonomous Agent Scopes
| Scope | Risk Level | Target Routes | Description |
|---|---|---|---|
| `agent.match` | Medium | `/api/agent/matchmake` | Autonomous background agent matchmaking and candidate ranking. |
| `agent.chat` | High | `/api/agent/chat-assist` | AI-assisted message drafting and conversation mediation. |
| `agent.icebreaker` | Low | `/api/agent/icebreakers` | Synthesize Gemini-powered personalized icebreaker prompts. |
| `agent.delegate` | High | `/api/agent/delegate` | Autonomous agent delegation under RFC 9396 RAR constraints. |
| `ai.intent` | Low | `/api/ai/intent-score` | Cryptographic intent scoring and lifestyle pledge verification. |
| `ai.compatibility` | Low | `/api/ai/compatibility-radar` | Multi-axis compatibility radar vector synthesis. |

### 4. Model Context Protocol (MCP) Scopes
| Scope | Risk Level | Target Routes | Description |
|---|---|---|---|
| `mcp.tools` | Medium | `/api/mcp/execute`, `/api/mcp/tools` | Execute certified MCP JSON-RPC tools inside candidate sandboxes. |

### 5. Messaging & Media Scopes
| Scope | Risk Level | Target Routes | Description |
|---|---|---|---|
| `messages.read` | High | `/api/messages/:matchId` | Decrypt and read end-to-end encrypted chat histories. |
| `messages.write` | High | `/api/messages/send` | Dispatch encrypted messages and date coordination proposals. |
| `media.upload` | Medium | `/api/media/upload` | Upload profile imagery, verification selfies, and prompt photos. |
| `media.voice_intro` | Medium | `/api/voice/intros`, `/api/voice/upload` | Record and stream ambient acoustic voice introductions. |

### 6. Audio & Video Calls Scopes
| Scope | Risk Level | Target Routes | Description |
|---|---|---|---|
| `calls.initiate` | High | `/api/calls/initiate` | Start structured 5-minute WebRTC grace-period speed introductions. |
| `calls.participate` | High | `/api/calls/join`, `/api/calls/signal` | Join incoming WebRTC sessions and exchange DTLS/SRTP SDP packets. |

### 7. Presence & Signals Scopes
| Scope | Risk Level | Target Routes | Description |
|---|---|---|---|
| `presence.status` | Low | `/api/presence`, `/api/presence/heartbeat` | Real-time active status, typing signals, and online presence. |

### 8. Safety & Privacy Scopes
| Scope | Risk Level | Target Routes | Description |
|---|---|---|---|
| `safety.report` | Medium | `/api/safety/report`, `/api/safety/block` | Submit urgent safety flags, user reports, and account blocks. |
| `history.export` | High | `/api/export/data`, `/api/export/matches` | Export full GDPR Article 20 / CCPA cryptographic personal data archives. |

### 9. Admin & Telemetry Scopes
| Scope | Risk Level | Target Routes | Description |
|---|---|---|---|
| `admin.audit` | High | `/api/admin/audit-logs` | Query immutable ABAC authorization logs and token audit trails. |
| `admin.metrics` | Medium | `/api/metrics` | Read system performance, OAuth grant rates, and rate limit metrics. |

### 10. Partner Federation Scopes
| Scope | Risk Level | Target Routes | Description |
|---|---|---|---|
| `partner.federate` | High | `/api/federation/query` | Cross-network compatibility evaluation with certified partner graphs. |

---

## Step 8 — Model Context Protocol (MCP) Integration

Curadate exposes Model Context Protocol (MCP) JSON-RPC tools for autonomous agents operating via Claude Desktop, Cursor, and IDE extensions:

### MCP Tool Endpoints
- **Tool Discovery**: `GET /api/mcp/tools`
- **Tool Execution**: `POST /api/mcp/execute`
- **Server-Sent Events Stream**: `GET /api/mcp/sse`

#### Sample MCP Tool Request:
```json
{
  "jsonrpc": "2.0",
  "id": "mcp_req_01",
  "method": "tools/call",
  "params": {
    "name": "evaluate_profile_compatibility",
    "arguments": {
      "candidate_id": "usr_cand_44",
      "required_axes": ["values", "lifestyle", "communication"]
    }
  }
}
```

---

## Step 9 — Developer Support & Security Contacts

- **Security & Vulnerability Disclosure**: `security@curadate.com` / `/.well-known/security.txt`
- **OAuth & Auth Discovery Specs**: `https://curadate.com/auth.md`
- **RFC 9116 Policy Document**: `https://curadate.com/security.md`
- **IETF Rate Limits Documentation**: `https://curadate.com/rate-limits.md`