Autenticação

Não existe senha. A identidade é o e-mail (AD-005). Toda entrada termina do mesmo jeito: um access JWT no corpo da resposta e um refresh token num cookie httpOnly.

Entrar por e-mailCopy Anchor Link

1. POST /auth/otp/request com email e delivery:

   • "code": seis dígitos pra digitar (pensado pro celular);
   • "link": um magic link pra clicar (pensado pro desktop).

   Campos opcionais: displayName (só usado se o e-mail ainda não tem conta) e audience (platform, o padrão, ou backoffice). Responde 202, exista a conta ou não. E-mail desconhecido vira conta nova. As únicas recusas são um endereço que não recebe e-mail (422 EMAIL_DOMAIN_INVALID) e pedidos demais (429 RATE_LIMITED).

2. POST /auth/otp/verify com { email, code } ou { token } (o ?token= do link). Responde 200 com { accessToken, expiresAtMs } e grava o cookie de refresh.

Regras do desafio (login_challenges):

O magic link aponta pra MAGIC_LINK_URL?token=…, uma página do app que faz o POST em /auth/otp/verify. O backend nunca recebe o token por GET, então o prefetch de clientes de e-mail não queima o link (AD-005).

Por que o verify recusouCopy Anchor Link

O verify responde 401 com um código que diz o motivo, sem revelar se o e-mail tem conta:

EXPIRED e USED só aparecem pra quem mandou o segredo de verdade, ou seja, pra quem tem acesso ao e-mail.

Pedir um link novo a partir de um mortoCopy Anchor Link

POST /auth/otp/resend com { linkToken } (o ?token= do link vencido ou usado). Quem decide pra onde vai o link novo é o token, nunca um endereço digitado. Sempre 202 com { emailMasked } (por exemplo an•••@example.com). emailMasked: null quer dizer que o token não é nosso ou tem mais de OTP_RESEND_MAX_AGE_HOURS (padrão 168), e então nada é enviado. O resend anula código ou link ainda vivo e zera as tentativas erradas.

Login, verify e resend têm limite de taxa (429 RATE_LIMITED). Veja Limites de taxa.

Entrar com Google ou AppleCopy Anchor Link

• POST /auth/providers/{provider}/login, com provider igual a google ou apple e corpo { idToken, displayName? }. O ID token é conferido contra as chaves do provedor. Um e-mail verificado que já tem conta é vinculado a ela, e um desconhecido cria conta. A Apple não manda o nome no token, então o app envia displayName no primeiro login.
• POST /auth/providers/{provider}/link (com Bearer) vincula o provedor a quem já está logado.
• Respostas: 401 se o token não confere ou o e-mail não é verificado, 503 se o provedor não está configurado (GOOGLE_CLIENT_IDS / APPLE_CLIENT_IDS vazios).

Tokens e sessõesCopy Anchor Link

O Path=/ é de propósito: o app pode falar com a API por um prefixo de proxy, e um cookie preso em /auth nunca seria enviado (backend/src/http/cookies.ts).

Renovar e sairCopy Anchor Link

• POST /auth/refresh: troca o cookie por um access JWT novo (200, mesmo formato do verify). O refresh token não é rotacionado, só ganha last_seen_at. Se o cookie está morto, responde 401 e apaga o cookie.
• POST /auth/logout: revoga a sessão e apaga o cookie. Sempre 204.
• GET /auth/session: confere o Bearer e devolve o usuário, os provedores vinculados (methods.providers) e deletionScheduledFor.
• DELETE /admin/users/{uid}/sessions: um operador com escrita encerra todas as sessões de alguém.

O backofficeCopy Anchor Link

O app e o backoffice falam com a mesma API, no mesmo host. Por isso o cliente vem num header próprio:

Quem entra no painel é decidido por platform_members (AD-018), não por users.role. Papéis: owner, admin e viewer. PLATFORM_ADMINS só cria o primeiro owner. Se a pessoa perde o vínculo, a sessão de backoffice morre no próximo refresh.

Proteger uma rotaCopy Anchor Link

async function api(path: string, init: RequestInit = {}, token?: string) {
  const call = (t?: string) =>
    fetch(`https://api.superdinda.com${path}`, {
      ...init,
      credentials: "include", // manda o cookie de refresh
      headers: { ...init.headers, ...(t && { authorization: `Bearer ${t}` }) },
    });
  let res = await call(token);
  if (res.status === 401 && !path.startsWith("/auth/")) {
    const refreshed = await fetch("https://api.superdinda.com/auth/refresh", {
      method: "POST",
      credentials: "include",
    }).then((r) => r.json());
    if (refreshed.success) res = await call(refreshed.data.accessToken);
  }
  return res.json(); // { success, data } ou { success, error }
}

FontesCopy Anchor Link

• backend/src/http/routes/auth/*.route.ts, backend/src/http/routes/auth/schemas.ts
• backend/src/domains/auth/crypto/jwt.ts, crypto/otp.ts, entities/challenge.entity.ts, entities/session.entity.ts
• backend/src/domains/auth/use-cases/request-otp.ts, verify-otp.ts, open-session.ts, refresh-session.ts, authenticate.ts, login-with-provider.ts
• backend/src/http/cookies.ts, backend/src/core/clients.ts, backend/src/http/app.ts
• backend/src/http/middleware/auth.ts, account.ts, seat.ts, operator.ts
• backend/src/domains/auth/use-cases/code-lock.ts, resend-link.ts, backend/src/domains/auth/errors.ts
• backend/src/domains/operators/use-cases/membership.ts, backend/src/config/env.ts, backend/.env.example
• Notas da frente k-otp (k-otp-api.md)
• AD-005, AD-016, AD-018