# CrimeSpot auth.md — AI Agent Authentication & Registration

> **Specification**: [Auth.md Agent Registration Protocol](https://agentauthprotocol.com) & [OAuth 2.0 Protected Resource Metadata (RFC 9728)](https://www.rfc-editor.org/rfc/rfc9728)  
> **Resource**: `https://crimespotbd.org`  
> **Audience**: Autonomous AI agents, LLM assistants, Model Context Protocol (MCP) servers, and civic observation bots.

CrimeSpot allows autonomous AI agents to discover, register, claim, and authenticate with civic safety APIs using standard OAuth 2.0/2.1 bearer tokens.

---

## 1. Quick Discovery Metadata

- **OAuth Protected Resource Metadata (PRM)**: [`/.well-known/oauth-protected-resource`](https://crimespotbd.org/.well-known/oauth-protected-resource)
- **OAuth Authorization Server Metadata**: [`/.well-known/oauth-authorization-server`](https://crimespotbd.org/.well-known/oauth-authorization-server)
- **RFC 9727 API Catalog**: [`/.well-known/api-catalog`](https://crimespotbd.org/.well-known/api-catalog)
- **OpenAPI 3.1 Specification**: [`/api/v1/openapi.json`](https://crimespotbd.org/api/v1/openapi.json)
- **API Status & Health**: [`/api/health`](https://crimespotbd.org/api/health)

---

## 2. Agent Registration & Provisioning Endpoints

Autonomous agents can programmatically obtain credentials without browser interaction through the following endpoints:

| Endpoint                                     | Method | Purpose                                                                         |
| -------------------------------------------- | ------ | ------------------------------------------------------------------------------- |
| `https://crimespotbd.org/api/agent/register` | `POST` | Dynamic agent registration for anonymous, verified email, or ID-JAG assertions. |
| `https://crimespotbd.org/api/agent/claim`    | `POST` | Claim an anonymous agent session or complete verified email OTP challenge.      |
| `https://crimespotbd.org/api/agent/revoke`   | `POST` | Revoke active agent credentials or token sessions.                              |

---

## 3. Supported Authentication Methods

### Method A: Anonymous Agent Access (`anonymous`)

Autonomous tools reading public incident feeds, platform statistics, and area risk ratings can register anonymously:

1. Agent sends a registration request:
    ```http
    POST /api/agent/register HTTP/1.1
    Host: crimespotbd.org
    Content-Type: application/json

    {
      "identity_type": "anonymous",
      "agent_name": "MyCivicAgent/1.0"
    }
    ```
2. Server responds with a scoped, short-lived Bearer token:
    ```json
    {
        "access_token": "cs_anon_...",
        "token_type": "Bearer",
        "expires_in": 86400,
        "scope": "incidents:read stats:read"
    }
    ```

### Method B: Verified Email Claim (`verified_email`)

Agents acting on behalf of a citizen or community organization can claim identity via email verification:

1. Agent initiates registration:
    ```http
    POST /api/agent/register HTTP/1.1
    Host: crimespotbd.org
    Content-Type: application/json

    {
      "identity_type": "verified_email",
      "email": "agent-operator@example.com"
    }
    ```
2. The operator receives a claim code, and the agent completes the claim:
    ```http
    POST /api/agent/claim HTTP/1.1
    Host: crimespotbd.org
    Content-Type: application/json

    {
      "claim_id": "clm_...",
      "code": "123456"
    }
    ```

### Method C: Identity Assertion JWT Authorization Grant (`urn:ietf:params:oauth:token-type:id-jag`)

Enterprise agents and autonomous platforms with an existing OpenID Connect Identity Provider (IdP) can exchange identity assertion tokens (ID-JAG):

1. The agent exchanges an ID-JAG token at the token endpoint:
    ```http
    POST /oauth/token HTTP/1.1
    Host: crimespotbd.org
    Content-Type: application/x-www-form-urlencoded

    grant_type=urn:ietf:params:oauth:grant-type:token-exchange
    &subject_token=<ID_JAG_TOKEN>
    &subject_token_type=urn:ietf:params:oauth:token-type:id-jag
    &requested_token_type=urn:ietf:params:oauth:token-type:access_token
    &scope=incidents:read incidents:write
    ```

---

## 4. Scopes & Permissions

- `incidents:read`: Read geocoded incident reports, map markers, and verification details.
- `incidents:write`: Submit citizen incident reports for community moderation.
- `stats:read`: Access hourly crime distributions, district analytics, and category metrics.

---

## 5. Credential Usage & Revocation

Present acquired tokens in the HTTP `Authorization` request header:

```http
GET /api/v1/incidents HTTP/1.1
Host: crimespotbd.org
Authorization: Bearer <access_token>
```

To revoke active credentials, submit the token to the revocation endpoint:

```http
POST /api/agent/revoke HTTP/1.1
Host: crimespotbd.org
Content-Type: application/json

{
  "token": "<access_token>",
  "token_type_hint": "access_token"
}
```