# auth.md

Welcome to the agent registration and authentication specification for the Sean Raynon Non-Profit Initiative supporting the Calabrian Children's Foundation.

## Agent Audience

This specification is designed for autonomous AI agents, LLM evaluators, automated philanthropy bots, and web agents acting on behalf of donors, foundations, or technical volunteers.

## Discovery Metadata

This service publishes RFC-compliant discovery metadata:
- **Protected Resource Metadata (PRM)**: \`https://seanraynon.org/.well-known/oauth-protected-resource\`
- **OAuth Authorization Server Metadata**: \`https://seanraynon.org/.well-known/oauth-authorization-server\`
- **OpenID Connect Configuration**: \`https://seanraynon.org/.well-known/openid-configuration\`
- **Resource Identifier**: \`https://seanraynon.org\`
- **Authorization Server Issuer**: \`https://seanraynon.org\`
- **Scopes Supported**: \`read:campaign\`, \`write:pledge\`
- **Bearer Methods Supported**: \`header\`

## Supported Registration Methods

1. **Identity Assertion (ID-JAG)**
   - Type: \`identity_assertion\`
   - Assertion Types: \`urn:ietf:params:oauth:token-type:id-jag\`, \`verified_email\`
   - Credential Types: \`bearer_token\`
   - Registration URI: \`https://seanraynon.org/api/agent/register\`
   - Identity Endpoint: \`https://seanraynon.org/api/agent/identity\`
   - Claim URI: \`https://seanraynon.org/api/agent/claim\`

2. **Anonymous Registration with Claim Ceremony**
   - Type: \`anonymous\`
   - Credential Types: \`bearer_token\`
   - Registration URI: \`https://seanraynon.org/api/agent/register\`
   - Claim URI: \`https://seanraynon.org/api/agent/claim\`

## Standalone Registration Flow

### Step 1: Agent Registration Request

To register an agent session or submit donation pledges autonomously, POST to the registration endpoint:

\`\`\`http
POST /api/agent/register HTTP/1.1
Host: seanraynon.org
Content-Type: application/json

{
  "type": "anonymous",
  "client_name": "MyPhilanthropyAgent",
  "contact_email": "donor@example.org"
}
\`\`\`

Or with Identity Assertion:

\`\`\`http
POST /api/agent/register HTTP/1.1
Host: seanraynon.org
Content-Type: application/json

{
  "type": "identity_assertion",
  "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
  "assertion": "<id_jag_jwt>"
}
\`\`\`

### Step 2: Service Response

The service responds with credential tokens and a claim URI:

\`\`\`json
{
  "access_token": "sr_agent_token_sample",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:campaign write:pledge",
  "claim_uri": "https://seanraynon.org/api/agent/claim",
  "revocation_uri": "https://seanraynon.org/api/oauth/revoke"
}
\`\`\`

### Step 3: Authenticated Requests

Include the bearer token in the HTTP Authorization header:

\`\`\`http
GET /api/campaign HTTP/1.1
Host: seanraynon.org
Authorization: Bearer <access_token>
\`\`\`

### Step 4: Token Revocation

Tokens can be revoked at any time:

\`\`\`http
POST /api/oauth/revoke HTTP/1.1
Host: seanraynon.org
Content-Type: application/x-www-form-urlencoded

token=<access_token>&token_type_hint=access_token
\`\`\`

## Direct Human Contact

- **Founder**: Sean Raynon
- **Email**: iam@seanraynon.com
- **Phone**: +1 (575) 495-3504
- **Partner**: Calabrian Children's Foundation, Cagayan de Oro City