# auth.md — autenticação de agentes em Zig

Este documento descreve como um agente automatizado se autentica para agir em nome de um
usuário em https://zig.tickets, e o que ele **não** consegue fazer sozinho.

## Público

Agentes que agem em nome de uma pessoa que já tem (ou vai criar) conta neste marketplace.
Não há identidade de agente: toda ação autenticada acontece com a credencial do usuário.

## O que existe hoje

| Recurso | Situação |
| --- | --- |
| Bearer token de usuário | Sim — `POST https://ticket-api.zig.tickets/auth/token` |
| Renovação de token | Sim — `POST https://ticket-api.zig.tickets/auth/refresh` |
| Revogação de token | Sim — `DELETE https://ticket-api.zig.tickets/auth/revoke` |
| Registro dinâmico de cliente (RFC 7591) | Não |
| Credencial de máquina para agentes | Não |
| Authorization Code / PKCE | Não |
| Escopos OAuth | Não — o token carrega o acesso do próprio usuário |
| JWKS público | Não |

## Emissão de token

```http
POST https://ticket-api.zig.tickets/auth/token
Content-Type: application/json
X-Origin: https://zig.tickets

{
  "email": "<e-mail do usuário>",
  "password": "<senha do usuário>",
  "g-recaptcha-response": "<token de reCAPTCHA>"
}
```

Resposta:

```json
{ "type": "bearer", "token": "<token>", "expires_at": "<ISO 8601>" }
```

Use o token em `Authorization: Bearer <token>`.

### A barreira do reCAPTCHA

`POST /auth/token` é protegido por reCAPTCHA. O token do desafio só é obtido em um
navegador real, por uma pessoa. **Um agente headless não emite token sozinho.** Quando a
verificação em duas etapas está habilitada, há ainda um código enviado ao usuário.

Consequência prática: o agente deve entregar o usuário ao site para autenticar, e nunca
pedir senha, código de 2FA ou token de sessão no chat.

## Segmentação por marca

A API atende várias marcas no mesmo host. Envie `X-Origin: https://zig.tickets` em toda chamada
para operar no contexto de Zig.

## Metadados relacionados

- Protected Resource Metadata (RFC 9728): https://zig.tickets/.well-known/oauth-protected-resource
- Authorization Server Metadata (RFC 8414): https://zig.tickets/.well-known/oauth-authorization-server
- Catálogo de APIs (RFC 9727): https://zig.tickets/.well-known/api-catalog
- OpenAPI da API pública: https://zig.tickets/.well-known/openapi.json

O emissor declarado é `https://zig.tickets`.

## agent_auth

```yaml
agent_auth:
  skill: https://zig.tickets/.well-known/agent-skills/manage-tickets/SKILL.md
  register_uri: https://ticket-api.zig.tickets/users
  automated_registration_supported: false
  identity_types_supported:
    - delegated_user
  credential_types_supported:
    - bearer_token
  registration_methods:
    - type: human_in_the_loop
      description: >-
        Cadastro criado pela própria pessoa no site, com reCAPTCHA. O agente não registra
        conta em nome do usuário.
      uri: https://zig.tickets
  token_endpoint: https://ticket-api.zig.tickets/auth/token
  revocation_endpoint: https://ticket-api.zig.tickets/auth/revoke
```

Ressalva honesta sobre o bloco acima: nenhum dos fluxos de identidade previstos na
especificação do auth.md (ID-JAG `identity_assertion`, `verified_email`, `anonymous`)
está implementado. `delegated_user` descreve o que de fato acontece — o agente opera com a
credencial do usuário. `register_uri` aponta para o endpoint de provisionamento de conta,
que é protegido por reCAPTCHA e **não deve ser chamado por scanner ou agente**: criar conta
dispara e-mail e gera cadastro real.

## Limites de uso

- Não contorne reCAPTCHA, fila virtual (Queue-it) ou limite de compra por CPF.
- Não armazene credenciais do usuário.
- Revogue o token (`DELETE /auth/revoke`) ao encerrar a sessão do usuário.
- Endpoints de leitura pública não precisam de token: prefira-os sempre que a tarefa for
  apenas consultar eventos.