@adonis-agora/authkit-server 0.68.4 → 0.70.0

package/build/src/host/account_api/account_mfa_api_controller.js

@@ -0,0 +1,286 @@
+/**
+ * Account Self-Service JSON API — SEGUNDO FATOR (TOTP + passkeys)
+ *
+ * Espelho JSON do `AccountMfaController`, para o host que desenha a própria
+ * tela de "segundo fator" e não pode navegar o browser no meio do fluxo.
+ *
+ * Mapa de rotas (sob o `accountGuard`; mutantes sob o CSRF do shield do host):
+ *   POST /account/api/mfa/totp/enroll       → inicia o enrolamento (sudo)
+ *   POST /account/api/mfa/totp/confirm      → confirma com o código (throttled)
+ *   POST /account/api/mfa/totp/disable      → desliga o MFA (sudo)
+ *   POST /account/api/mfa/recovery-codes    → regenera os códigos (sudo)
+ *   POST /account/api/mfa/passkeys/options  → options da cerimônia de registro
+ *   POST /account/api/mfa/passkeys/verify   → verifica o attestation (sudo)
+ *
+ * Paridade de gates com o console HTML, endpoint a endpoint:
+ *
+ *   | ação             | console HTML | aqui             |
+ *   | ---------------- | ------------ | ---------------- |
+ *   | enroll           | sudo         | sudo → 403 JSON  |
+ *   | confirm          | sem sudo     | sem sudo         |
+ *   | disable          | sudo         | sudo → 403 JSON  |
+ *   | passkey options  | sem sudo     | sem sudo         |
+ *   | passkey verify   | sudo         | sudo → 403 JSON  |
+ *   | recovery codes   | (não existe) | sudo → 403 JSON  |
+ *
+ * A única diferença é a FORMA da recusa: `requireSudo` devolve um redirect para
+ * `/account/confirm`, que numa SPA chega como uma página HTML onde ela esperava
+ * JSON. Aqui a recusa vira `403 { error: { code: 'sudo_required' } }` e a tela
+ * do host manda o usuário confirmar identidade por conta própria. Mesma
+ * política, resposta legível por máquina.
+ *
+ * `confirm` NÃO exige sudo — porque o `enroll` que criou o segredo pendente já
+ * exigiu, e pedir de novo no passo seguinte quebraria o enrolamento de quem
+ * demorou a digitar o código. É exatamente o que o console faz. O que o console
+ * não tem, e aqui existe, é o THROTTLE: o código de 6 dígitos é adivinhável, e
+ * a rota carrega o bucket de sudo (por IP) — mais apertado que o form, nunca
+ * mais frouxo.
+ *
+ * Os dois caminhos (clássico e JSON) COMPARTILHAM o slot do desafio WebAuthn
+ * (`PASSKEY_REG_CHALLENGE_KEY`), então um `options` pedido num deles pode ser
+ * finalizado pelo outro e nunca existem dois desafios vivos na mesma sessão.
+ */
+import '../augmentations.js';
+import QRCode from 'qrcode';
+import { supportsMfa, supportsPasskeys, supportsRecoveryCodeRegeneration, } from '../../accounts/account_store.js';
+import { ACCOUNT_SESSION_KEY } from '../account_session_key.js';
+import { translate } from '../i18n.js';
+import { PASSKEY_REG_CHALLENGE_KEY } from '../passkey_registration_challenge.js';
+import { resolveRuntimeSettings } from '../runtime_settings.js';
+import { dispatchSecurityNotice } from '../security_notice_service.js';
+import { isSudoSatisfied } from '../sudo_mode.js';
+/** Erro JSON padrão — mesmo envelope do `account_api_controller`. */
+function apiErr(code, message) {
+    return { error: { code, message } };
+}
+export default class AccountMfaApiController {
+    // ─── POST /account/api/mfa/totp/enroll ──────────────────────────────────
+    /**
+     * Inicia o enrolamento TOTP: segredo pendente + `otpauth://` URI + o QR já
+     * renderizado como data-URL (o console renderiza server-side; aqui a tela do
+     * host recebe pronto e decide se mostra o QR, o segredo, ou os dois).
+     */
+    async enrollTotp(ctx) {
+        const c = await this.#mfaContext(ctx);
+        if (!c)
+            return;
+        if (!(await this.#requireSudoJson(ctx)))
+            return;
+        const started = await c.store.startTotpEnrollment(c.userId);
+        if (!started) {
+            return ctx.response
+                .status(422)
+                .send(apiErr('enroll_failed', 'Could not start TOTP enrollment.'));
+        }
+        const qrDataUrl = await QRCode.toDataURL(started.otpauthUri);
+        return { secret: started.secret, otpauthUri: started.otpauthUri, qrDataUrl };
+    }
+    // ─── POST /account/api/mfa/totp/confirm ─────────────────────────────────
+    /**
+     * Confirma o enrolamento com o código do app autenticador. Sucesso ativa o
+     * MFA e devolve os recovery codes — UMA vez, como no console (lá eles vão num
+     * flash; aqui, no corpo da resposta, que é o equivalente headless).
+     */
+    async confirmTotp(ctx) {
+        const c = await this.#mfaContext(ctx);
+        if (!c)
+            return;
+        const code = String(ctx.request.input('code', '') ?? '').trim();
+        const result = await c.store.confirmTotpEnrollment(c.userId, code);
+        if (!result.ok) {
+            // NÃO regenera o segredo pendente: o usuário já escaneou o QR, e um
+            // segredo novo invalidaria o app autenticador dele. Mesma decisão do
+            // console — a tela pede outro código sobre o MESMO segredo.
+            return ctx.response
+                .status(422)
+                .send(apiErr('invalid_code', translate(c.cfg.messages, 'errors.invalid_code')));
+        }
+        await c.cfg.audit?.record({
+            type: 'mfa.enabled',
+            accountId: c.userId,
+            ip: ctx.request.ip?.() ?? null,
+            metadata: { method: 'totp' },
+        });
+        await this.#notice(ctx, c, 'mfa_enabled');
+        return { ok: true, enabled: true, recoveryCodes: result.recoveryCodes ?? [] };
+    }
+    // ─── POST /account/api/mfa/totp/disable ─────────────────────────────────
+    /** Desliga o MFA (TOTP + recovery codes). Exige sudo, como o console. */
+    async disableTotp(ctx) {
+        const c = await this.#mfaContext(ctx);
+        if (!c)
+            return;
+        if (!(await this.#requireSudoJson(ctx)))
+            return;
+        await c.store.disableMfa(c.userId);
+        await c.cfg.audit?.record({
+            type: 'mfa.disabled',
+            accountId: c.userId,
+            ip: ctx.request.ip?.() ?? null,
+        });
+        await this.#notice(ctx, c, 'mfa_disabled');
+        return { ok: true, enabled: false };
+    }
+    // ─── POST /account/api/mfa/recovery-codes ───────────────────────────────
+    /**
+     * Regenera os recovery codes de uma conta com MFA ATIVO e devolve os novos —
+     * uma única vez. Exige sudo: o resultado é um conjunto de credenciais que
+     * contorna o segundo fator, então vale o mesmo gate do `enroll`/`disable`.
+     *
+     * Capability-probed: stores que não implementam
+     * `regenerateRecoveryCodes` respondem 422 em vez de 500.
+     */
+    async regenerateRecoveryCodes(ctx) {
+        const c = await this.#mfaContext(ctx);
+        if (!c)
+            return;
+        if (!supportsRecoveryCodeRegeneration(c.store)) {
+            return ctx.response
+                .status(422)
+                .send(apiErr('capability_unsupported', 'Recovery code regeneration not supported.'));
+        }
+        if (!(await this.#requireSudoJson(ctx)))
+            return;
+        const codes = await c.store.regenerateRecoveryCodes(c.userId);
+        if (!codes) {
+            // Sem MFA ativo não há conjunto a regenerar — enrolar é o caminho.
+            return ctx.response.status(422).send(apiErr('mfa_not_enabled', 'MFA is not enabled.'));
+        }
+        await c.cfg.audit?.record({
+            type: 'mfa.recovery_codes_regenerated',
+            accountId: c.userId,
+            ip: ctx.request.ip?.() ?? null,
+        });
+        return { ok: true, recoveryCodes: codes };
+    }
+    // ─── POST /account/api/mfa/passkeys/options ─────────────────────────────
+    /**
+     * Options da cerimônia de REGISTRO de passkey, guardando o desafio na sessão.
+     * Sem sudo, igual ao endpoint clássico: quem paga o gate é o `verify`, que é
+     * onde a credencial passa a existir.
+     */
+    async passkeyRegisterOptions(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const userId = ctx.session.get(ACCOUNT_SESSION_KEY);
+        if (!supportsPasskeys(cfg.accountStore)) {
+            return ctx.response
+                .status(422)
+                .send(apiErr('capability_unsupported', translate(cfg.messages, 'errors.passkeys_unavailable')));
+        }
+        const generated = await cfg.accountStore.generatePasskeyRegistrationOptions?.(userId);
+        if (!generated) {
+            return ctx.response
+                .status(422)
+                .send(apiErr('capability_unsupported', translate(cfg.messages, 'errors.passkeys_unavailable')));
+        }
+        ctx.session.put(PASSKEY_REG_CHALLENGE_KEY, generated.challenge);
+        return generated.options;
+    }
+    // ─── POST /account/api/mfa/passkeys/verify ──────────────────────────────
+    /**
+     * Verifica o attestation contra o desafio da sessão e persiste a credencial.
+     *
+     * O endpoint clássico responde 302 numa navegação e `{ok:true}` num fetch;
+     * este responde SEMPRE JSON — inclusive na recusa de sudo, que lá é um
+     * redirect. É a diferença que faz a cerimônia caber numa SPA: o browser não
+     * pode navegar entre `startRegistration()` e a verificação.
+     */
+    async passkeyRegisterVerify(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const userId = ctx.session.get(ACCOUNT_SESSION_KEY);
+        if (!supportsPasskeys(cfg.accountStore)) {
+            return ctx.response
+                .status(422)
+                .send(apiErr('capability_unsupported', translate(cfg.messages, 'errors.passkeys_unavailable')));
+        }
+        if (!(await this.#requireSudoJson(ctx)))
+            return;
+        const challenge = ctx.session.get(PASSKEY_REG_CHALLENGE_KEY);
+        if (!challenge) {
+            return ctx.response
+                .status(400)
+                .send(apiErr('challenge_expired', translate(cfg.messages, 'errors.challenge_expired')));
+        }
+        const body = ctx.request.input('response', ctx.request.body());
+        const ok = (await cfg.accountStore.verifyPasskeyRegistration?.(userId, body, challenge)) ?? false;
+        // Queima o desafio em QUALQUER desfecho: um attestation recusado não pode
+        // ser retentado contra o mesmo challenge.
+        ctx.session.forget(PASSKEY_REG_CHALLENGE_KEY);
+        if (!ok) {
+            return ctx.response
+                .status(400)
+                .send(apiErr('invalid_response', translate(cfg.messages, 'errors.invalid_code')));
+        }
+        const ip = ctx.request.ip?.() ?? null;
+        await cfg.audit?.record({
+            type: 'mfa.enabled',
+            accountId: userId,
+            ip,
+            metadata: { method: 'webauthn' },
+        });
+        await cfg.audit?.record({ type: 'passkey.registered', accountId: userId, ip });
+        const account = await cfg.accountStore.findById(userId);
+        if (account) {
+            const ts = new Date().toISOString();
+            for (const kind of ['passkey_added', 'mfa_enabled']) {
+                await dispatchSecurityNotice(ctx, { account: { id: userId, email: account.email }, kind, ip, timestamp: ts }, cfg.mail, cfg.audit, cfg);
+            }
+        }
+        return { ok: true };
+    }
+    // ─── Internos ───────────────────────────────────────────────────────────
+    /**
+     * Resolve config + store com MFA + a conta da sessão. Quando o pré-requisito
+     * falha, JÁ RESPONDE e devolve `null`.
+     */
+    async #mfaContext(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const store = cfg.accountStore;
+        if (!supportsMfa(store)) {
+            ctx.response
+                .status(422)
+                .send(apiErr('capability_unsupported', 'MFA not supported by the account store.'));
+            return null;
+        }
+        const userId = ctx.session.get(ACCOUNT_SESSION_KEY);
+        if (!userId) {
+            ctx.response.unauthorized(apiErr('unauthorized', 'Not authenticated.'));
+            return null;
+        }
+        return { cfg, store, userId };
+    }
+    /**
+     * Gate de sudo em versão JSON. A DECISÃO é a mesmíssima do console —
+     * `isSudoSatisfied`, de onde o `requireSudo` do form também tira a dele
+     * (mesma setting, mesma janela de graça, mesma vinculação à conta, mesmo
+     * fail-safe) —, só a RECUSA muda de forma: `403 sudo_required` em vez do
+     * redirect para `/account/confirm`.
+     *
+     * Chama a decisão, e não o `requireSudo`, porque aquele ESCREVE na resposta
+     * ao recusar (`response.redirect`): sobrepor um 403 depois deixaria um
+     * `Location` pendurado numa resposta que não é redirect. Devolve `false`
+     * quando já respondeu.
+     */
+    async #requireSudoJson(ctx) {
+        const settings = await resolveRuntimeSettings(ctx);
+        if (await isSudoSatisfied(ctx, settings))
+            return true;
+        ctx.response.status(403).send(apiErr('sudo_required', 'Identity confirmation required.'));
+        return false;
+    }
+    /** Notificação de segurança best-effort (nunca derruba a operação). */
+    async #notice(ctx, c, kind) {
+        const account = await c.cfg.accountStore.findById(c.userId);
+        if (!account)
+            return;
+        await dispatchSecurityNotice(ctx, {
+            account: { id: c.userId, email: account.email },
+            kind: kind,
+            ip: ctx.request.ip?.() ?? null,
+            timestamp: new Date().toISOString(),
+        }, c.cfg.mail, c.cfg.audit, c.cfg);
+    }
+}

package/build/src/host/account_api/account_orgs_api_controller.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Account Self-Service JSON API — ESCRITA de organizações
+ *
+ * Espelho JSON dos POSTs de formulário do `AccountOrgsController`, para hosts
+ * que desenham as próprias telas de organização dentro do shell do produto e
+ * não querem mandar o usuário ao console `/account/orgs`.
+ *
+ * Mapa de rotas (todas sob o `accountGuard`; as mutantes sob o CSRF do shield
+ * do host — nenhuma delas entra em `authkitCsrfExceptions`):
+ *   POST   /account/api/orgs                                → criar org (allowSelfCreate)
+ *   POST   /account/api/orgs/deactivate                     → limpar a org ativa
+ *   POST   /account/api/orgs/invitations/:token/accept      → aceitar convite
+ *   POST   /account/api/orgs/:id/activate                   → definir org ativa
+ *   POST   /account/api/orgs/:id/leave                      → sair da org
+ *   POST   /account/api/orgs/:id/invitations                → convidar por e-mail
+ *   DELETE /account/api/orgs/:id/invitations/:invId         → revogar convite
+ *   PATCH  /account/api/orgs/:id/members/:accountId         → trocar papel
+ *   DELETE /account/api/orgs/:id/members/:accountId         → remover membro
+ *
+ * O que este controller NÃO afrouxa em relação ao formulário:
+ *
+ *   - **Escopo por conta.** O ator é sempre `session[ACCOUNT_SESSION_KEY]`;
+ *     nenhum handler aceita um id de ator vindo do corpo.
+ *   - **Papel na org.** Convidar, revogar convite, remover membro e trocar
+ *     papel exigem membership `owner`/`admin` NA ORG DO PATH — a mesma checagem
+ *     do form, que é o que impede o IDOR cross-org.
+ *   - **Escalonamento.** Só um `owner` concede o papel `owner`; um admin
+ *     tentando isso leva 403, igual ao form.
+ *   - **Catálogo de papéis.** O papel passa pelo `isRoleInCatalog` (runtime →
+ *     config → defaults), o MESMO helper puro do form e do caminho admin.
+ *
+ * O que muda de propósito: a resposta. Onde o form redireciona para
+ * `/account/orgs` (com ou sem flash), aqui sai JSON — `{ error: { code,
+ * message } }` com o status certo, para a tela do host poder reagir.
+ *
+ * Sudo: o console HTML NÃO exige sudo em nenhuma operação de org, e este
+ * espelho segue igual. Exigir aqui o que o form não exige seria divergência na
+ * outra direção — e a decisão de qual superfície é sensível pertence a uma
+ * mudança de política, não a um espelho de formato.
+ *
+ * Política EFETIVA, não o config estático. `allowSelfCreate`, o catálogo de
+ * papéis e o TTL do convite saem do MESMO módulo que o console HTML usa
+ * (`host/org_policy.ts`: setting da org → setting global → config → default da
+ * lib). Ler só o config estático daria uma superfície que diverge da outra na
+ * primeira vez que um admin mexesse na setting — e divergência entre o form e
+ * o espelho é exatamente o bug que este controller não pode ter.
+ */
+import '../augmentations.js';
+import type { HttpContext } from '@adonisjs/core/http';
+export default class AccountOrgsApiController {
+    #private;
+    /** Criar uma org. Exige `allowSelfCreate` na política efetiva. */
+    createOrg(ctx: HttpContext): Promise<void | {
+        id: string;
+        name: string;
+        slug: string;
+        logoUrl: string | null;
+        role: string;
+    }>;
+    /** Define a org ativa (cookie `authkit_active_org`). Valida membership. */
+    activateOrg(ctx: HttpContext): Promise<void | {
+        ok: boolean;
+        activeOrgId: string;
+        slug: any;
+        role: any;
+    }>;
+    /** Limpa a org ativa. Não depende de membership (só apaga o cookie). */
+    deactivateOrg(ctx: HttpContext): Promise<{
+        ok: boolean;
+        activeOrgId: null;
+    }>;
+    /** Sai da org. O store recusa o último owner (`reason: 'last_owner'`). */
+    leaveOrg(ctx: HttpContext): Promise<void | {
+        ok: boolean;
+        orgId: string;
+    }>;
+    /** Convida alguém por e-mail. Exige owner/admin; papel validado no catálogo. */
+    inviteMember(ctx: HttpContext): Promise<void | {
+        id: any;
+        organizationId: string;
+        email: any;
+        role: string;
+        expiresAt: any;
+        createdAt: any;
+    }>;
+    /** Revoga um convite pendente. Escopado por org (anti-IDOR), como o form. */
+    revokeInvitation(ctx: HttpContext): Promise<void | {
+        ok: boolean;
+        revoked: string;
+    }>;
+    /** Remove um membro. Exige owner/admin na org. */
+    removeMember(ctx: HttpContext): Promise<void | {
+        ok: boolean;
+        orgId: string;
+        accountId: string;
+    }>;
+    /**
+     * Troca o papel de um membro.
+     *
+     * Não existe equivalente member-facing em formulário (o console HTML só
+     * troca papel pelo caminho ADMIN). As regras vieram, então, da interseção
+     * das duas superfícies que já existem: o guard de owner/admin + catálogo de
+     * papéis do `invite` member-facing, e a checagem de `last_owner` do
+     * `AdminOrgsService.updateMemberRole`. Conceder `owner` continua privativo
+     * de um owner.
+     */
+    updateMemberRole(ctx: HttpContext): Promise<void | {
+        ok: boolean;
+        orgId: string;
+        accountId: string;
+        role: string;
+    }>;
+    /**
+     * Aceita um convite pelo token do e-mail.
+     *
+     * Diferente do form (montado FORA do guard para tratar o não-autenticado com
+     * um redirect para o login), esta rota vive DENTRO do `accountGuard`: uma
+     * tela SPA já está logada, e a resposta a um visitante anônimo aqui teria de
+     * ser 401 em JSON, não uma navegação.
+     */
+    acceptInvitation(ctx: HttpContext): Promise<void | {
+        ok: boolean;
+        organizationId: any;
+        role: any;
+    }>;
+}