# auth.md

> Machine-readable agent registration, discovery, and authorization specification for The Permanent Record (opreturn.xyz).
> Public immutable Bitcoin blockchain index. Unauthenticated anonymous access is supported.

## Agent registration

The Permanent Record indexes public, immutable Bitcoin blockchain data.
- **Agent Audience**: Autonomous AI agents, LLM tool executors, indexers, and automated scrapers.
- **Read Access**: Completely anonymous and unauthenticated. AI agents can query all public APIs (/api/messages, /api/collections, /api/chat, /mcp) without registration or API keys.
- **Rate Limits**: Governed by Cloudflare edge protection with high-availability SWR caching. Standard User-Agent identifiers receive maximum throughput.
- **Write Actions**: Rate-limited and anti-spam protected using a client-mined 16-bit Proof-of-Work nonce (sha256(id:nonce) having 16 leading zero bits). No KYC or centralized account required.

Both roles live on one host. The resource server is https://opreturn.xyz and the authorization server is https://opreturn.xyz.

## Discovery

Read these two documents in this order:

- Fetch https://opreturn.xyz/.well-known/oauth-protected-resource and read resource, resource_name, authorization_servers, scopes_supported, bearer_methods_supported, and agent_auth.
- Fetch https://opreturn.xyz/.well-known/oauth-authorization-server and read the agent_auth block: skill, register_uri, claim_uri, revocation_uri, identity_types_supported, anonymous.credential_types_supported, and identity_assertion.assertion_types_supported.

There is no WWW-Authenticate challenge. Every resource is public and answers anonymous requests directly. OAuth metadata is published so agents can register or claim identities without guessing.

## Scopes

- read:messages — Read immutable Bitcoin OP_RETURN messages, mempool feeds, and broadcasts.
- read:collections — Read curated Bitcoin address collections and multi-party chat feeds.

## Endpoints

- Registration Endpoint: https://opreturn.xyz/oauth/register
- Token Endpoint: https://opreturn.xyz/oauth/token
- Claim URI: https://opreturn.xyz/oauth/claim
- Revocation URI: https://opreturn.xyz/oauth/revoke

## Supported identity types

### 1. Anonymous Access (Recommended)
- Identity Type: anonymous
- Credential Types Supported: bearer_token, api_key
- Registration URI: https://opreturn.xyz/oauth/register
- Claim URI: https://opreturn.xyz/oauth/claim
- Scopes: read:messages, read:collections

### 2. ID-JAG Identity Assertion
- Identity Type: identity_assertion
- Assertion Types Supported: urn:ietf:params:oauth:token-type:id-jag
- Credential Types Supported: bearer_token, api_key
- Registration URI: https://opreturn.xyz/oauth/register
- Revocation URI: https://opreturn.xyz/oauth/revoke

### 3. Verified Email Assertion
- Identity Type: identity_assertion
- Assertion Types Supported: verified_email
- Credential Types Supported: bearer_token, api_key
- Registration URI: https://opreturn.xyz/oauth/register
- Claim URI: https://opreturn.xyz/oauth/claim

## Standalone registration flow

Agents can register anonymously or assert identity via standard HTTP requests:

```http
POST /oauth/register HTTP/1.1
Host: opreturn.xyz
Content-Type: application/json

{
  "client_name": "Autonomous Agent",
  "grant_types": ["anonymous"],
  "identity_type": "anonymous"
}
```

Response:
```json
{
  "client_id": "anonymous-agent",
  "access_token": "opreturn_anonymous_read_token",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "read:messages read:collections"
}
```

To claim ownership of an identifier or verify operator correspondence:
```http
POST /oauth/claim HTTP/1.1
Host: opreturn.xyz
Authorization: Bearer <token>
Content-Type: application/json

{
  "claim_type": "verified_email",
  "email": "agent@example.com"
}
```

To revoke issued agent credentials:
```http
POST /oauth/revoke HTTP/1.1
Host: opreturn.xyz
Content-Type: application/json

{
  "token": "<token>"
}
```

## Credential usage

For unauthenticated operations, simply execute standard HTTP GET requests. For authenticated sessions, pass the bearer token via the standard Authorization header:

```http
GET /api/messages HTTP/1.1
Host: opreturn.xyz
Authorization: Bearer <token>
Accept: application/json
```