# Contractor Document Compliance Agent auth.md

This document defines agent authentication, registration, and discovery interfaces for the Contractor Document Compliance Agent service per the Auth.md specification.

## Agent Audience

- **Resource Server**: `https://agents.devbuildtool.com/api`
- **Application URL**: `https://agents.devbuildtool.com`
- **Issuer**: `https://auth.devbuildtool.com/`

## OAuth & OIDC Discovery Metadata

The service publishes standard OAuth and OpenID Connect discovery endpoints:

- **OAuth Protected Resource Metadata (RFC 9728)**: [/.well-known/oauth-protected-resource](https://agents.devbuildtool.com/.well-known/oauth-protected-resource)
- **OAuth Authorization Server Metadata (RFC 8414)**: [/.well-known/oauth-authorization-server](https://agents.devbuildtool.com/.well-known/oauth-authorization-server)
- **OpenID Connect Configuration**: [/.well-known/openid-configuration](https://agents.devbuildtool.com/.well-known/openid-configuration)

### Protected Resource Metadata (PRM)

```json
{
  "resource": "https://agents.devbuildtool.com/api",
  "authorization_servers": [
    "https://auth.devbuildtool.com/"
  ],
  "scopes_supported": [
    "openid",
    "profile",
    "email",
    "read:compliance",
    "write:compliance"
  ],
  "bearer_methods_supported": [
    "header"
  ],
  "resource_documentation": "https://agents.devbuildtool.com/how-it-works"
}
```

## Agent Registration & Provisioning

Agents can authenticate using OAuth 2.0 / OIDC credentials issued by Auth0 (`https://auth.devbuildtool.com/`).

### Registration URI

- `https://auth.devbuildtool.com/register`

### Agent Auth Configuration

```json
{
  "agent_auth": {
    "skill": "https://agents.devbuildtool.com/.well-known/agent-skills/contractor-compliance/SKILL.md",
    "register_uri": "https://auth.devbuildtool.com/register",
    "methods": [
      "urn:ietf:params:oauth:token-type:id-jag",
      "verified_email",
      "anonymous"
    ]
  }
}
```

## Flow Metadata & Supported Identity Types

The authorization server supports the following identity assertion and credential methods:

```json
{
  "identity_types_supported": [
    "identity_assertion",
    "anonymous"
  ],
  "identity_assertion": {
    "assertion_types_supported": [
      "urn:ietf:params:oauth:token-type:id-jag",
      "verified_email"
    ],
    "credential_types_supported": [
      "jwt",
      "token"
    ],
    "claim_uri": "https://auth.devbuildtool.com/claims",
    "revocation_uri": "https://auth.devbuildtool.com/oauth/revoke",
    "events_supported": [
      "https://schemas.openid.net/secevent/oauth/event-type/token-revocation"
    ]
  },
  "anonymous": {
    "credential_types_supported": [
      "token"
    ],
    "claim_uri": "https://auth.devbuildtool.com/anonymous"
  }
}
```

## Credential Usage

All protected API endpoints require an HTTP `Authorization` header carrying a valid Bearer JWT:

```http
Authorization: Bearer <access_token>
```

Tokens are validated at the Cloudflare edge against Auth0's published JWKS (`https://auth.devbuildtool.com/.well-known/jwks.json`).
Unauthenticated requests will receive `401 Unauthorized` with a `WWW-Authenticate` response header pointing to the Protected Resource Metadata:

```http
WWW-Authenticate: Bearer realm="api", error="invalid_token", resource_metadata="https://agents.devbuildtool.com/.well-known/oauth-protected-resource"
```