# Auth.md

## Autenticação para agentes — daniloschettini.com.br

Este documento descreve como agentes de IA devem acessar as capabilities
públicas deste domínio. Ele é gerado a partir do registro central de
capabilities: nada listado aqui é aspiracional.

## Capacidades públicas (sem autenticação)

Todas as rotas abaixo são **read-only**, respondem `GET`, aceitam CORS
`*` e não expõem dados pessoais, pedidos, pagamentos nem segredos.

- **site-information** — `/api/agent/site`
  Dados públicos do site (nome, idioma, autor, contato público) em JSON read-only.
- **product-information** — `/api/agent/product`
  Ficha pública do livro: nome, descrição, preço, moeda, formas de pagamento e URL de checkout humano.
- **site-navigation** — `/api/agent/navigation`
  Mapa das seções e páginas públicas do site.
- **openapi** — `/openapi.json`
  Descrição OpenAPI 3.1 das APIs agênticas públicas.
- **api-catalog** — `/.well-known/api-catalog`
  Catálogo de APIs em formato Linkset (RFC 9727 / RFC 9264).
- **ard** — `/.well-known/ai-catalog.json`
  Manifest de Agentic Resource Discovery com recursos e consultas representativas.
- **agent-skills** — `/.well-known/agent-skills/index.json`
  Índice de Agent Skills com SKILL.md reais e SHA-256 calculado em tempo de execução.
- **webmcp**
  Ferramentas WebMCP read-only registradas no navegador via navigator.modelContext, quando suportado.
- **mcp** — `/api/agent/mcp`
  Servidor MCP (JSON-RPC 2.0 sobre HTTP) com ferramentas read-only de informação pública.
- **web-bot-auth** — `/.well-known/http-message-signatures-directory`
  Verificação de assinatura de requisições de bots (HTTP Message Signatures) com diretório de chaves públicas.
- **x402** — `/api/agent/premium-resource`
  Pagamento máquina-a-máquina via protocolo x402 para recursos premium de API.
- **ucp** — `/.well-known/ucp`
  Universal Commerce Protocol — descoberta de catálogo e handoff para o checkout humano. Não confirma pagamento.
- **acp** — `/.well-known/acp.json`
  Agentic Commerce Protocol — descoberta de produto e início de checkout por handoff. Não confirma pagamento.

Nenhuma credencial é necessária. Requisições educadas (cache com
`If-None-Match`, respeito ao `Cache-Control`) são apreciadas; há
rate limit por IP nos endpoints de API.

## Capacidades autenticadas

- **oauth** — `/.well-known/oauth-protected-resource`
  Autenticação de agentes via OAuth 2.0 / OIDC delegada a um provedor externo.

## Capacidades implementadas porém ainda não ativas

O código existe e está versionado, mas a capability depende de
configuração externa e por isso **não é anunciada** em nenhum manifest,
nem responde publicamente:

- **mpp** — Provedor MPP não configurado (MPP_PROVIDER_URL ausente).

## agent_auth

Bloco `agent_auth` legível por máquina (mesmos valores publicados em
`/.well-known/oauth-authorization-server`):

```json
{
  "agent_auth": {
    "version": "1.0",
    "skill": "https://daniloschettini.com.br/auth.md",
    "documentation_uri": "https://daniloschettini.com.br/auth.md",
    "register_uri": "https://daniloschettini.com.br/api/agent/auth/register",
    "claim_uri": "https://daniloschettini.com.br/api/agent/auth/claim",
    "registration_type": "anonymous_agent_registration",
    "registration_spec": "https://github.com/workos/auth.md",
    "identity_types_supported": [
      "anonymous",
      "delegated_user"
    ],
    "anonymous": {
      "register_uri": "https://daniloschettini.com.br/api/agent/auth/register",
      "claim_uri": "https://daniloschettini.com.br/api/agent/auth/claim",
      "credential_types_supported": [
        "agent_credential",
        "identity_assertion_jwt"
      ],
      "assertion_types_supported": [
        "anonymous_agent_assertion"
      ],
      "audience": "https://daniloschettini.com.br/api/agent",
      "expires_in": 3600
    },
    "identity_assertion": {
      "assertion_types_supported": [
        "anonymous_agent_assertion"
      ],
      "claim_uri": "https://daniloschettini.com.br/api/agent/auth/claim",
      "signing_alg_values_supported": [
        "HS256"
      ],
      "audience": "https://daniloschettini.com.br/api/agent"
    },
    "credential_types_supported": [
      "agent_credential",
      "identity_assertion_jwt",
      "oauth2_authorization_code_pkce"
    ],
    "registration_methods": [
      {
        "name": "anonymous_agent_registration",
        "identity_type": "anonymous",
        "register_uri": "https://daniloschettini.com.br/api/agent/auth/register",
        "register_method": "POST",
        "claim_uri": "https://daniloschettini.com.br/api/agent/auth/claim",
        "claim_method": "POST",
        "credential_type": "identity_assertion_jwt",
        "credential_use": "Envie a assertion em \"Authorization: Bearer <assertion>\" nas chamadas a https://daniloschettini.com.br/api/agent. Os recursos read-only permanecem públicos; a assertion apenas identifica o agente.",
        "request_example": {
          "client_name": "meu-agente/1.0"
        },
        "scopes_supported": [
          "agent:read"
        ]
      },
      {
        "name": "delegated_user_oauth",
        "identity_type": "delegated_user",
        "register_uri": "https://fyrcbdiqohshskfaapbl.supabase.co/auth/v1/oauth/clients/register",
        "register_method": "POST",
        "registration_spec": "https://www.rfc-editor.org/rfc/rfc7591",
        "credential_type": "oauth2_authorization_code_pkce",
        "authorization_endpoint": "https://fyrcbdiqohshskfaapbl.supabase.co/auth/v1/oauth/authorize",
        "token_endpoint": "https://fyrcbdiqohshskfaapbl.supabase.co/auth/v1/oauth/token",
        "jwks_uri": "https://fyrcbdiqohshskfaapbl.supabase.co/auth/v1/.well-known/jwks.json",
        "consent_uri": "https://daniloschettini.com.br/.lovable/oauth/consent",
        "scopes_supported": [
          "openid",
          "profile",
          "email",
          "offline_access"
        ],
        "credential_use": "Access token OAuth 2.1 (PKCE S256) enviado em \"Authorization: Bearer <token>\"."
      }
    ],
    "events_supported": [],
    "revocation_uri": null,
    "delegated_authorization_server": "https://fyrcbdiqohshskfaapbl.supabase.co/auth/v1"
  }
}
```

## Registro de agentes (agent registration)

### Fluxo anônimo implementado neste domínio (recomendado para agentes)

1. `POST https://daniloschettini.com.br/api/agent/auth/register` com `{"client_name":"meu-agente/1.0"}`
   → devolve `client_id` e `registration_credential` (assinada, validade de 1h).
2. `POST https://daniloschettini.com.br/api/agent/auth/claim` com `{"registration_credential":"..."}`
   → devolve uma **identity assertion** (JWT HS256, `aud: https://daniloschettini.com.br/api/agent`, validade de 1h).
3. Envie `Authorization: Bearer <assertion>` nas chamadas a `/api/agent`.

Credencial adulterada ou expirada é rejeitada com `401`. O fluxo é anônimo:
não cria conta humana, não acessa pedidos, pagamentos, Asaas nem checkout,
e a assertion não desbloqueia nenhum dado privado.

### Fluxo delegado por usuário (OAuth 2.1 / OIDC)

Agentes que precisam de um token delegado de usuário devem se registrar
dinamicamente no Authorization Server deste domínio:

- **Metadados do Authorization Server:** `https://daniloschettini.com.br/.well-known/oauth-authorization-server` (RFC 8414)
- **Metadados OIDC:** `https://daniloschettini.com.br/.well-known/openid-configuration`
- **Metadados do Protected Resource:** `https://daniloschettini.com.br/.well-known/oauth-protected-resource` (RFC 9728)
- **register_uri:** ver `registration_endpoint` / `agent_auth.register_uri` nos documentos acima (Dynamic Client Registration, RFC 7591)
- **Tipo de identidade:** `delegated_user` (o agente age em nome de uma pessoa autenticada)
- **Tipo de credencial:** `oauth2_authorization_code_pkce` (PKCE S256 obrigatório; `client_secret` opcional)
- **Escopos:** `openid`, `profile`, `email`, `offline_access`
- **Tela de consentimento:** `https://daniloschettini.com.br/.lovable/oauth/consent`
- **Revogação:** revogue o refresh token no `token_endpoint` do issuer; não há endpoint proprietário.

Fluxo resumido:

1. `POST` no `register_uri` com `client_name` e `redirect_uris` → recebe `client_id`.
2. Redirecione a pessoa para o `authorization_endpoint` com PKCE.
3. A pessoa autentica e aprova na tela de consentimento acima.
4. Troque o `code` no `token_endpoint` por access token + refresh token.
5. Envie o token em `Authorization: Bearer …` nas chamadas a `/api/agent`.

Importante: os endpoints `/api/agent/*` são **públicos e read-only**. O token
identifica o agente/usuário, mas **não** desbloqueia dados pessoais, pedidos,
pagamentos ou operações administrativas — esses recursos não são expostos.

## Compras

A camada agêntica é **informativa**. Nenhum agente pode concluir uma
compra: o pagamento é feito por uma pessoa no checkout do provedor
financeiro, e a confirmação de compra só ocorre mediante confirmação real
do pagamento.

## Contato

Problemas com esta camada: https://daniloschettini.com.br (canal público de contato na página inicial).