Аутентификация

Registro (4 Etapas)

O registro requer verificacao de e-mail, uma senha e um nome de exibicao:

Etapa 1: Enviar Codigo de Verificacao

POST /auth/send-code

{
  "email": "user@example.com",
  "scene": "register",
  "turnstile_token": "..."
}

Etapa 2: Registrar

POST /auth/register

{
  "email": "user@example.com",
  "code": "123456",
  "account_password": "your-password",
  "display_name": "Your Name",
  "device_locale": "en-US"
}

Retorna access token e refresh token (como cookie HttpOnly).

Etapa 3: Cliente Gera Chaves

Apos o registro, o cliente:

Gera um par de chaves X25519
Deriva uma chave de criptografia: Argon2id(protection_password, random_salt)
Criptografa a chave privada: AES-GCM(derived_key, private_key)

Etapa 4: Upload do Backup de Chave

POST /keys/backup

{
  "backup_a": "base64-encrypted-private-key",
  "argon2_salt": "base64-salt",
  "public_key": "base64-public-key",
  "device_id": "device-uuid"
}

Tres metodos de login sao suportados:

POST /auth/login

{
  "email": "user@example.com",
  "account_password": "your-password",
  "turnstile_token": "..."
}

Bloqueio: Apos 5 tentativas falhas, a conta e bloqueada por 15 minutos. Retorna 423 ACCOUNT_LOCKED com retry_after em segundos.

POST /auth/send-code
{ "email": "user@example.com", "scene": "login", "turnstile_token": "..." }

POST /auth/login-code
{ "email": "user@example.com", "code": "123456" }

Passkey substitui a senha da conta na etapa de autenticacao. A senha de protecao (para descriptografia de chave) ainda e necessaria em novos dispositivos.

POST /auth/passkey/begin     # Retorna challenge (endpoint publico)
POST /auth/passkey/complete   # Verifica assinatura, emite tokens (endpoint publico)

Login com Passkey usa WebAuthn Conditional UI — sem botao explicito na tela de login. O prompt do sistema Passkey aparece automaticamente em dispositivos suportados.

Renovacao de Token

Access tokens expiram em 5 minutos. Use o refresh token para obter um novo par:

POST /auth/refresh

O refresh token e armazenado como um cookie HttpOnly com estes atributos:

Set-Cookie: refresh_token=...; HttpOnly; Secure; SameSite=Strict; Path=/auth; Max-Age=2592000

Redefinicao de Senha

A redefinicao da senha da conta nao afeta as chaves de criptografia:

POST /auth/send-code
{ "email": "user@example.com", "scene": "reset", "turnstile_token": "..." }

POST /auth/reset-password
{ "email": "user@example.com", "code": "123456", "new_account_password": "new-password" }

Autenticacao de Agente

Agentes usam tokens de longa duracao em vez de JWT:

Authorization: Bearer hsk_your-agent-token

O formato do token e hsk_ + 40 caracteres base62. O servidor armazena o hash bcrypt.

Auth WebSocket

Para conexoes WebSocket, o token e enviado no primeiro frame (nunca na URL):

{ "type": "auth", "token": "hsk_...", "agent_id": "your-agent-id" }

O servidor responde com { "type": "auth.ok" } ou { "type": "auth.error", "reason": "..." }.

Regeneracao de Token

POST /agents/:id/token/regenerate
{ "emergency": false }

Modo	Token Antigo	Chave Publica Antiga
Normal (`emergency: false`)	Valido por 7 dias	Valida por 7 dias
Emergencia (`emergency: true`)	Revogado imediatamente	Revogada imediatamente

Proximos Passos

Endpoints REST — Listagem completa de endpoints
Visao Geral da API — URL base e formato
Codigos de Erro — Codigos de erro de auth