@adonis-agora/authkit-server 0.45.0 → 0.46.0

package/build/src/host/sudo/index.js

@@ -0,0 +1,41 @@
+import { password } from './methods/password.js';
+import { passkey } from './methods/passkey.js';
+import { oidcStepUp } from './methods/oidc_step_up.js';
+import { magicLink } from './methods/magic_link.js';
+/**
+ * Métodos de confirmação de identidade (sudo mode), no mesmo padrão de factory
+ * usado em `stores.*` e `retrievers.*` das libs irmãs.
+ *
+ * A lista vai em DOIS lugares, e eles precisam casar:
+ *
+ * - `config/authkit.ts` → `sudo.methods` decide o que a TELA oferece e o que os
+ *   handlers ACEITAM;
+ * - `registerAuthHost(router, { sudoMethods })` decide o que tem ROTA montada.
+ *
+ * São dois porque a montagem de rotas acontece antes de o config (lazy)
+ * resolver — mesma razão de `social`/`admin`/`rateLimit`. Divergiram, a tela
+ * loga um aviso de flag-drift e o endpoint faltante dá 404.
+ *
+ * SEM `config.sudo.methods` não há como divergir: a tela cai na própria lista
+ * montada por `registerAuthHost`, a mesma que os handlers aceitam.
+ *
+ * ```ts
+ * defineConfig({
+ *   sudo: {
+ *     methods: [
+ *       sudoMethods.oidcStepUp({ url: '/auth/step-up' }),
+ *       sudoMethods.magicLink(),
+ *       sudoMethods.passkey(),
+ *       sudoMethods.password(),
+ *     ],
+ *   },
+ * })
+ * ```
+ */
+export const sudoMethods = { password, passkey, oidcStepUp, magicLink };
+/**
+ * Montagem do `SudoContext` a partir do `HttpContext`. Reexportado aqui por
+ * simetria com `sudoMethods` e os tipos: quem escreve um método (ou a rota de
+ * callback do `oidcStepUp`) precisa dos três.
+ */
+export { sudoContextFrom } from './runtime.js';

package/build/src/host/sudo/methods/magic_link.d.ts

@@ -0,0 +1,43 @@
+import type { SudoContext, SudoMethod } from '../types.js';
+/** Token de sudo pendente, guardado na sessão que o pediu. */
+export declare const SUDO_LINK_SESSION_KEY = "authkit_sudo_link";
+/** Mesma janela dos magic links de login. */
+export declare const SUDO_LINK_TTL_MS: number;
+/**
+ * Emite um token de sudo e guarda o HASH na sessão que pediu.
+ *
+ * O TOKEN É PRÓPRIO, DE ESCOPO SUDO — nunca o token de login
+ * (`issueMagicLinkToken`/`consumeMagicLinkToken` do `AccountStore`). Aquele é
+ * credencial de AUTENTICAÇÃO: reusá-lo faria de um link de sudo vazado uma
+ * sessão completa.
+ *
+ * | propriedade | valor | razão |
+ * |---|---|---|
+ * | geração | `randomBytes(32)` hex | entropia de credencial |
+ * | armazenamento | HASH na sessão que pediu | não guarda o segredo em claro |
+ * | escopo | só marca sudo | nunca autentica |
+ * | validade | 5 min | mesma janela dos magic links de login |
+ * | uso | único (apagado no consumo) | replay |
+ * | navegador | só o mesmo (vive na sessão) | step-up é reprova de QUEM ESTÁ ALI |
+ * | conta | vinculado ao `accountId` emissor | sessão sobrevive à troca de conta |
+ *
+ * O "só mesmo navegador" é propriedade desejada aqui, diferente do magic link
+ * de login, onde é limitação conhecida.
+ *
+ * Exportada (em vez de membro `__` do método) para ser testável sem furar a
+ * API pública do `SudoMethod`.
+ */
+export declare function issueSudoLinkToken(c: SudoContext): string;
+/**
+ * Consome o token: single-use, vinculado à conta emissora, expira em 5 min,
+ * comparação em tempo constante.
+ */
+export declare function verifySudoLinkToken(c: SudoContext, token: string): boolean;
+/**
+ * Confirmação por link enviado ao e-mail da conta.
+ *
+ * Depende do hook `mail.onSudoLink`, DISTINTO de `mail.onMagicLink` justamente
+ * para que o host não confunda um link que autentica com um que só concede
+ * sudo a quem já está logado. Sem o hook, o método fica indisponível.
+ */
+export declare function magicLink(): SudoMethod;

package/build/src/host/sudo/methods/magic_link.js

@@ -0,0 +1,174 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { translate } from '../../i18n.js';
+import { isSudoMethodEnabled } from '../runtime.js';
+/** Token de sudo pendente, guardado na sessão que o pediu. */
+export const SUDO_LINK_SESSION_KEY = 'authkit_sudo_link';
+/** Mesma janela dos magic links de login. */
+export const SUDO_LINK_TTL_MS = 5 * 60 * 1000;
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+/**
+ * Emite um token de sudo e guarda o HASH na sessão que pediu.
+ *
+ * O TOKEN É PRÓPRIO, DE ESCOPO SUDO — nunca o token de login
+ * (`issueMagicLinkToken`/`consumeMagicLinkToken` do `AccountStore`). Aquele é
+ * credencial de AUTENTICAÇÃO: reusá-lo faria de um link de sudo vazado uma
+ * sessão completa.
+ *
+ * | propriedade | valor | razão |
+ * |---|---|---|
+ * | geração | `randomBytes(32)` hex | entropia de credencial |
+ * | armazenamento | HASH na sessão que pediu | não guarda o segredo em claro |
+ * | escopo | só marca sudo | nunca autentica |
+ * | validade | 5 min | mesma janela dos magic links de login |
+ * | uso | único (apagado no consumo) | replay |
+ * | navegador | só o mesmo (vive na sessão) | step-up é reprova de QUEM ESTÁ ALI |
+ * | conta | vinculado ao `accountId` emissor | sessão sobrevive à troca de conta |
+ *
+ * O "só mesmo navegador" é propriedade desejada aqui, diferente do magic link
+ * de login, onde é limitação conhecida.
+ *
+ * Exportada (em vez de membro `__` do método) para ser testável sem furar a
+ * API pública do `SudoMethod`.
+ */
+export function issueSudoLinkToken(c) {
+    const token = randomBytes(32).toString('hex');
+    const pending = {
+        hash: sha256(token),
+        expiresAt: Date.now() + SUDO_LINK_TTL_MS,
+        accountId: c.accountId,
+    };
+    c.ctx.session.put(SUDO_LINK_SESSION_KEY, pending);
+    return token;
+}
+/**
+ * Consome o token: single-use, vinculado à conta emissora, expira em 5 min,
+ * comparação em tempo constante.
+ */
+export function verifySudoLinkToken(c, token) {
+    const pending = c.ctx.session.get(SUDO_LINK_SESSION_KEY);
+    // GUARD DE FORMA, antes de qualquer uso dos campos. A sessão é um saco de
+    // JSON: um valor com outra forma (versão antiga do pacote, host que escreveu
+    // na chave, store corrompido) tinha duas consequências ruins —
+    //   1. `Buffer.from(undefined, 'hex')` → TypeError → 500;
+    //   2. `Date.now() > undefined` é `false` → FAIL-OPEN: o token nunca expira.
+    // Forma errada é recusa, não exceção e muito menos passe livre.
+    if (typeof pending?.hash !== 'string' ||
+        typeof pending?.expiresAt !== 'number' ||
+        typeof pending?.accountId !== 'string') {
+        // Lixo na chave não pode ficar lá bloqueando/confundindo a próxima emissão.
+        c.ctx.session.forget(SUDO_LINK_SESSION_KEY);
+        return false;
+    }
+    // Single-use: some na primeira tentativa, certa ou errada.
+    c.ctx.session.forget(SUDO_LINK_SESSION_KEY);
+    // VINCULAÇÃO À CONTA: quem consome tem de ser quem pediu. A sessão sobrevive
+    // à troca de conta (o `regenerate()` do logout MIGRA os dados), então "está
+    // pendente nesta sessão" não implica "é desta conta". Ver `PendingLink.accountId`.
+    if (pending.accountId !== c.accountId)
+        return false;
+    if (Date.now() > pending.expiresAt)
+        return false;
+    const a = Buffer.from(sha256(token), 'hex');
+    const b = Buffer.from(pending.hash, 'hex');
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/**
+ * Origem absoluta desta requisição, ou `null` se o request não a expõe.
+ *
+ * O link vai por E-MAIL: um caminho relativo (`/account/confirm/...`) não é
+ * clicável fora do navegador. É a mesma montagem do `onMagicLink` de login
+ * (interaction_controller.ts:706). O `null` é fallback defensivo — se o host
+ * usar um request sem `protocol()`/`host()`, cai para o caminho relativo em vez
+ * de mandar `undefined://undefined/...`.
+ */
+function requestOrigin(ctx) {
+    const protocol = ctx?.request?.protocol?.();
+    const host = ctx?.request?.host?.();
+    return protocol && host ? `${protocol}://${host}` : null;
+}
+/**
+ * Confirmação por link enviado ao e-mail da conta.
+ *
+ * Depende do hook `mail.onSudoLink`, DISTINTO de `mail.onMagicLink` justamente
+ * para que o host não confunda um link que autentica com um que só concede
+ * sudo a quem já está logado. Sem o hook, o método fica indisponível.
+ */
+export function magicLink() {
+    return {
+        id: 'magic-link',
+        async isAvailable(c) {
+            if (!c.account?.email)
+                return false;
+            return typeof c.cfg?.mail?.onSudoLink === 'function';
+        },
+        async describe() {
+            return {
+                labelKey: 'account.confirm.method.magic_link',
+                kind: 'action',
+                endpoint: '/account/confirm/magic-link',
+            };
+        },
+        register(router, h) {
+            router.post('/account/confirm/magic-link', async (ctx) => {
+                const c = await h.contextFrom(ctx);
+                // ANTES de qualquer coisa: o host desligou este método? A rota é montada
+                // incondicionalmente, então só o handler faz `config.sudo.methods` valer.
+                // Responde `fail` (o mesmo redirect+flash de um erro comum) em vez de
+                // 404 para não vazar a config do host.
+                if (!isSudoMethodEnabled(c.cfg, 'magic-link'))
+                    return h.fail(c, 'account.confirm.error');
+                // `c.account` é nullable (sessão viva de conta apagada → findById null)
+                // e sem e-mail não há para onde mandar o link.
+                if (!c.account?.email)
+                    return h.fail(c, 'account.confirm.error');
+                // Checado ANTES de emitir: um token emitido sem ninguém para entregá-lo
+                // é lixo na sessão, e a `isAvailable` já prometeu que sem hook o método
+                // não existe.
+                const onSudoLink = c.cfg?.mail?.onSudoLink;
+                if (typeof onSudoLink !== 'function')
+                    return h.fail(c, 'account.confirm.error');
+                const qs = c.returnTo ? `?return_to=${encodeURIComponent(c.returnTo)}` : '';
+                const token = issueSudoLinkToken(c);
+                const path = `/account/confirm/magic-link/${token}${qs}`;
+                const origin = requestOrigin(ctx);
+                try {
+                    await onSudoLink({ email: c.account.email, sudoUrl: origin ? `${origin}${path}` : path });
+                }
+                catch {
+                    // O envio falhou: apaga o pendente. Não é risco de segurança (o
+                    // segredo não chegou a lugar nenhum), mas deixá-lo lá invalidaria
+                    // silenciosamente um token anterior ainda válido do usuário.
+                    c.ctx.session.forget(SUDO_LINK_SESSION_KEY);
+                    return h.fail(c, 'account.confirm.error');
+                }
+                // TRADUZIDO, não a chave crua: o `fail()` do runtime flasha
+                // `translate(...)` em `confirmError`, e a tela leria dois formatos
+                // diferentes se este aqui mandasse a chave.
+                ctx.session.flash('confirmNotice', translate(c.cfg.messages, 'account.confirm.magic_link_sent'));
+                return ctx.response.redirect(`/account/confirm${qs}`);
+            });
+            router.get('/account/confirm/magic-link/:token', async (ctx) => {
+                const c = await h.contextFrom(ctx);
+                if (!isSudoMethodEnabled(c.cfg, 'magic-link'))
+                    return h.fail(c, 'account.confirm.error');
+                // Sem conta resolvida não há a quem conceder sudo. O token vive na
+                // sessão, mas quem o consome precisa continuar sendo uma conta viva.
+                //
+                // NÃO INVERTA ESTA ORDEM. O `!c.account` vem ANTES do
+                // `verifySudoLinkToken` de propósito: o `verify` é DESTRUTIVO (queima o
+                // pendente na primeira tentativa, certa ou errada), e scanners
+                // corporativos de e-mail — Safe Links do Microsoft 365, proxies de
+                // antivírus — fazem prefetch da URL SEM o cookie de sessão. Nesse
+                // prefetch não há conta resolvida: com esta ordem ele é recusado antes
+                // de tocar no pendente, e o link continua válido para o usuário. Trocar
+                // as duas linhas faria todo link chegar já consumido.
+                if (!c.account)
+                    return h.fail(c, 'account.confirm.error');
+                const token = ctx.params?.token;
+                if (!token || !verifySudoLinkToken(c, token))
+                    return h.fail(c, 'account.confirm.error');
+                return h.completeSudo(c, 'magic-link');
+            });
+        },
+    };
+}

package/build/src/host/sudo/methods/oidc_step_up.d.ts

@@ -0,0 +1,68 @@
+import type { SudoMethod } from '../types.js';
+export interface OidcStepUpOptions {
+    /** Rota do HOST que inicia a reautenticação. Ex.: '/auth/step-up'. */
+    url: string;
+}
+/**
+ * Confirmação por reautenticação OIDC (step-up), o mecanismo padrão do próprio
+ * protocolo para provar identidade recente (`prompt=login` / `max_age`).
+ *
+ * SEMPRE disponível: é o único método que não exige nada previamente
+ * cadastrado, e por isso é o que quebra o deadlock de hosts passwordless —
+ * onde o usuário não tem senha e cadastrar passkey também exigiria sudo.
+ *
+ * NÃO registra rotas: o fluxo sai do pacote. Quem chama `completeSudo` é o
+ * host, no seu callback, DEPOIS de validar o grant.
+ *
+ * Fluxo esperado do host:
+ *
+ * ```
+ * POST /account/security/export
+ *   requireSudo() → sem marca → redirect para /account/confirm
+ * GET  /account/confirm
+ *   lista os métodos disponíveis; este aparece como 'redirect' e leva o
+ *   usuário para a URL abaixo
+ * GET  /auth/step-up
+ *   grava flag de step-up NA SESSÃO; inicia Authorization Code + PKCE
+ *   com prompt=login
+ * GET  /auth/callback
+ *   valida state/PKCE/nonce; consome a flag; chama completeSudo()
+ * ```
+ *
+ * Quatro regras que o host PRECISA seguir:
+ *
+ * 1. A flag de step-up vive NA SESSÃO, nunca na querystring. Se trafegasse
+ *    pela URL, qualquer um forjaria um callback que concede sudo.
+ * 2. `completeSudo` só DEPOIS da validação completa do grant. É o
+ *    `prompt=login` que garante que o provider forçou reautenticação, em vez
+ *    de reaproveitar a sessão existente.
+ * 3. A flag é CONSUMIDA (lida e apagada) logo no início do callback, antes de
+ *    qualquer ramo que possa falhar — não só no caminho de sucesso. Se ela
+ *    sobreviver a um callback que deu errado, o próximo login comum daquele
+ *    usuário será interpretado como step-up e concederá sudo sem que ninguém
+ *    tenha pedido reautenticação. Trate-a como token de uso único.
+ * 4. A flag CARREGA O `accountId` de quem iniciou o step-up, e o callback
+ *    RECUSA quando esse id não bate com a conta logada no momento do retorno.
+ *    Um booleano solto (`session.put('step_up', true)`) NÃO serve.
+ *
+ *    O porquê: a sessão sobrevive à troca de usuário. O `regenerate()` do
+ *    `@adonisjs/session`, que o logout chama, troca o ID do cookie mas MIGRA
+ *    os dados — ele não os descarta. Então, num navegador compartilhado, A
+ *    inicia o step-up, abandona no provider e faz logout; B loga na mesma
+ *    máquina; a flag booleana de A ainda está lá, e o primeiro callback que
+ *    chegar promove B a sudo sem que B jamais tenha reautenticado. A regra 3
+ *    (uso único) não cobre isso: ela limita a flag a UM uso, não a UMA conta,
+ *    e esse único uso pode muito bem ser o da conta errada.
+ *
+ *    Na prática: grave `{ accountId, ... }` em vez de `true`, e no callback
+ *    consuma a flag (regra 3) e compare `flag.accountId` com a conta da
+ *    sessão ANTES de chamar `completeSudo`. Divergiu, recuse — não é o
+ *    usuário que pediu a reautenticação. Ausência de flag também é recusa:
+ *    tolerar `undefined` devolve o mesmo furo por outro caminho.
+ *
+ *    Esta é a única barreira possível aqui: quem grava a flag é o HOST, no
+ *    seu `/auth/step-up`, e o pacote nunca a vê — não há como o AuthKit
+ *    impor a vinculação por você. O equivalente interno (challenge de passkey
+ *    e pendente do magic link) é vinculado à conta emissora pelo pacote.
+ */
+export declare function oidcStepUp(opts: OidcStepUpOptions): SudoMethod;

package/build/src/host/sudo/methods/oidc_step_up.js

@@ -0,0 +1,78 @@
+/**
+ * Confirmação por reautenticação OIDC (step-up), o mecanismo padrão do próprio
+ * protocolo para provar identidade recente (`prompt=login` / `max_age`).
+ *
+ * SEMPRE disponível: é o único método que não exige nada previamente
+ * cadastrado, e por isso é o que quebra o deadlock de hosts passwordless —
+ * onde o usuário não tem senha e cadastrar passkey também exigiria sudo.
+ *
+ * NÃO registra rotas: o fluxo sai do pacote. Quem chama `completeSudo` é o
+ * host, no seu callback, DEPOIS de validar o grant.
+ *
+ * Fluxo esperado do host:
+ *
+ * ```
+ * POST /account/security/export
+ *   requireSudo() → sem marca → redirect para /account/confirm
+ * GET  /account/confirm
+ *   lista os métodos disponíveis; este aparece como 'redirect' e leva o
+ *   usuário para a URL abaixo
+ * GET  /auth/step-up
+ *   grava flag de step-up NA SESSÃO; inicia Authorization Code + PKCE
+ *   com prompt=login
+ * GET  /auth/callback
+ *   valida state/PKCE/nonce; consome a flag; chama completeSudo()
+ * ```
+ *
+ * Quatro regras que o host PRECISA seguir:
+ *
+ * 1. A flag de step-up vive NA SESSÃO, nunca na querystring. Se trafegasse
+ *    pela URL, qualquer um forjaria um callback que concede sudo.
+ * 2. `completeSudo` só DEPOIS da validação completa do grant. É o
+ *    `prompt=login` que garante que o provider forçou reautenticação, em vez
+ *    de reaproveitar a sessão existente.
+ * 3. A flag é CONSUMIDA (lida e apagada) logo no início do callback, antes de
+ *    qualquer ramo que possa falhar — não só no caminho de sucesso. Se ela
+ *    sobreviver a um callback que deu errado, o próximo login comum daquele
+ *    usuário será interpretado como step-up e concederá sudo sem que ninguém
+ *    tenha pedido reautenticação. Trate-a como token de uso único.
+ * 4. A flag CARREGA O `accountId` de quem iniciou o step-up, e o callback
+ *    RECUSA quando esse id não bate com a conta logada no momento do retorno.
+ *    Um booleano solto (`session.put('step_up', true)`) NÃO serve.
+ *
+ *    O porquê: a sessão sobrevive à troca de usuário. O `regenerate()` do
+ *    `@adonisjs/session`, que o logout chama, troca o ID do cookie mas MIGRA
+ *    os dados — ele não os descarta. Então, num navegador compartilhado, A
+ *    inicia o step-up, abandona no provider e faz logout; B loga na mesma
+ *    máquina; a flag booleana de A ainda está lá, e o primeiro callback que
+ *    chegar promove B a sudo sem que B jamais tenha reautenticado. A regra 3
+ *    (uso único) não cobre isso: ela limita a flag a UM uso, não a UMA conta,
+ *    e esse único uso pode muito bem ser o da conta errada.
+ *
+ *    Na prática: grave `{ accountId, ... }` em vez de `true`, e no callback
+ *    consuma a flag (regra 3) e compare `flag.accountId` com a conta da
+ *    sessão ANTES de chamar `completeSudo`. Divergiu, recuse — não é o
+ *    usuário que pediu a reautenticação. Ausência de flag também é recusa:
+ *    tolerar `undefined` devolve o mesmo furo por outro caminho.
+ *
+ *    Esta é a única barreira possível aqui: quem grava a flag é o HOST, no
+ *    seu `/auth/step-up`, e o pacote nunca a vê — não há como o AuthKit
+ *    impor a vinculação por você. O equivalente interno (challenge de passkey
+ *    e pendente do magic link) é vinculado à conta emissora pelo pacote.
+ */
+export function oidcStepUp(opts) {
+    return {
+        id: 'oidc-step-up',
+        async isAvailable() {
+            return true;
+        },
+        async describe(c) {
+            const qs = c.returnTo ? `?return_to=${encodeURIComponent(c.returnTo)}` : '';
+            return {
+                labelKey: 'account.confirm.method.oidc_step_up',
+                kind: 'redirect',
+                endpoint: `${opts.url}${qs}`,
+            };
+        },
+    };
+}

package/build/src/host/sudo/methods/passkey.d.ts

@@ -0,0 +1,28 @@
+import type { SudoMethod } from '../types.js';
+/** Chave de sessão do challenge — preservada do controller original. */
+export declare const CONFIRM_PASSKEY_CHALLENGE_KEY = "authkit_confirm_passkey_challenge";
+/**
+ * Conta que PEDIU o challenge acima.
+ *
+ * Mesma exposição do magic link de sudo: a sessão sobrevive à troca de conta —
+ * o `regenerate()` do logout só troca o id do cookie e MIGRA os dados. Num
+ * navegador compartilhado, A pede o challenge, faz logout, B loga, e o
+ * challenge de A continua lá; sem esta vinculação a assertion de A seria
+ * verificada CONTRA A CONTA DE B (relevante sobretudo em `AccountStore`
+ * discoverable/usernameless, que resolve a credencial pelo `rawId`).
+ *
+ * Chave SEPARADA de propósito: o valor de `CONFIRM_PASSKEY_CHALLENGE_KEY` é
+ * uma string e isso é contratual (pinado em
+ * `tests/host/account_confirm_controller.spec.ts`), então a vinculação é
+ * aditiva em vez de mudar a forma do valor pinado.
+ */
+export declare const CONFIRM_PASSKEY_CHALLENGE_ACCOUNT_KEY = "authkit_confirm_passkey_challenge_account";
+/**
+ * Confirmação por passkey (WebAuthn).
+ *
+ * URLs LEGADAS preservadas: `/account/confirm/passkey/options` e
+ * `/account/confirm/passkey`. Hosts externos e telas customizadas (fora deste
+ * pacote) dependem desses paths — trocá-los quebraria essas integrações sem
+ * que o pacote tenha como saber ou migrar por elas.
+ */
+export declare function passkey(): SudoMethod;

package/build/src/host/sudo/methods/passkey.js

@@ -0,0 +1,139 @@
+import { supportsPasskeys } from '../../../accounts/account_store.js';
+import { translate } from '../../i18n.js';
+import { isSudoMethodEnabled } from '../runtime.js';
+/** Chave de sessão do challenge — preservada do controller original. */
+export const CONFIRM_PASSKEY_CHALLENGE_KEY = 'authkit_confirm_passkey_challenge';
+/**
+ * Conta que PEDIU o challenge acima.
+ *
+ * Mesma exposição do magic link de sudo: a sessão sobrevive à troca de conta —
+ * o `regenerate()` do logout só troca o id do cookie e MIGRA os dados. Num
+ * navegador compartilhado, A pede o challenge, faz logout, B loga, e o
+ * challenge de A continua lá; sem esta vinculação a assertion de A seria
+ * verificada CONTRA A CONTA DE B (relevante sobretudo em `AccountStore`
+ * discoverable/usernameless, que resolve a credencial pelo `rawId`).
+ *
+ * Chave SEPARADA de propósito: o valor de `CONFIRM_PASSKEY_CHALLENGE_KEY` é
+ * uma string e isso é contratual (pinado em
+ * `tests/host/account_confirm_controller.spec.ts`), então a vinculação é
+ * aditiva em vez de mudar a forma do valor pinado.
+ */
+export const CONFIRM_PASSKEY_CHALLENGE_ACCOUNT_KEY = 'authkit_confirm_passkey_challenge_account';
+/**
+ * Confirmação por passkey (WebAuthn).
+ *
+ * URLs LEGADAS preservadas: `/account/confirm/passkey/options` e
+ * `/account/confirm/passkey`. Hosts externos e telas customizadas (fora deste
+ * pacote) dependem desses paths — trocá-los quebraria essas integrações sem
+ * que o pacote tenha como saber ou migrar por elas.
+ */
+export function passkey() {
+    return {
+        id: 'passkey',
+        async isAvailable(c) {
+            if (!supportsPasskeys(c.cfg.accountStore))
+                return false;
+            const list = await c.cfg.accountStore.listPasskeys(c.accountId);
+            return list.length > 0;
+        },
+        async describe() {
+            return {
+                labelKey: 'account.confirm.method.passkey',
+                // 'webauthn', NÃO 'action': o navegador precisa assinar o challenge
+                // (`navigator.credentials.get`) ANTES do POST. Um form de submit direto
+                // manda `response` vazio e o handler abaixo recusa sempre. O kind é o
+                // que faz a tela rodar o handshake — e o endpoint de options ela deriva
+                // daqui (`${endpoint}/options`), sem conhecer o id 'passkey'.
+                kind: 'webauthn',
+                endpoint: '/account/confirm/passkey',
+            };
+        },
+        register(router, h) {
+            router.post('/account/confirm/passkey/options', async (ctx) => {
+                const c = await h.contextFrom(ctx);
+                // i18n: mesma chave usada pelo controller original — hosts com catálogo
+                // customizado (ex.: pt-BR) não podem perder a mensagem localizada aqui.
+                // Reusada nas TRÊS recusas abaixo de propósito: "método desligado",
+                // "conta inexistente" e "sem passkey" ficam indistinguíveis para o
+                // chamador.
+                const deny = () => ctx.response.notFound({ message: translate(c.cfg.messages, 'errors.no_passkey_registered') });
+                // ANTES de qualquer coisa: o host desligou este método? A rota é montada
+                // incondicionalmente, então só o handler faz `config.sudo.methods` valer.
+                if (!isSudoMethodEnabled(c.cfg, 'passkey'))
+                    return deny();
+                // Sem conta resolvida não há a quem emitir challenge. Aqui NÃO usamos
+                // `h.fail` (que redireciona) porque este endpoint é XHR e devolve JSON —
+                // um 302 para HTML quebraria o cliente. 404 em vez de 401 porque o 401
+                // afirmaria "você não está autenticado", informação a mais que o
+                // endpoint não precisa dar e incoerente com o resto do console, onde a
+                // ausência de sessão é tratada por redirect no `accountGuard`; o 404 é
+                // literalmente a resposta que este mesmo handler já dá quando não há
+                // passkey, então os casos não se distinguem.
+                if (!c.account)
+                    return deny();
+                const generated = await c.cfg.accountStore.generatePasskeyAuthenticationOptions?.(c.accountId);
+                if (!generated)
+                    return deny();
+                ctx.session.put(CONFIRM_PASSKEY_CHALLENGE_KEY, generated.challenge);
+                // Vinculação à conta emissora — ver CONFIRM_PASSKEY_CHALLENGE_ACCOUNT_KEY.
+                ctx.session.put(CONFIRM_PASSKEY_CHALLENGE_ACCOUNT_KEY, c.accountId);
+                return generated.options;
+            });
+            router.post('/account/confirm/passkey', async (ctx) => {
+                const c = await h.contextFrom(ctx);
+                // Método desligado pelo host → mesma resposta de uma assertion inválida
+                // (redirect + flash), para não vazar a config.
+                if (!isSudoMethodEnabled(c.cfg, 'passkey'))
+                    return h.fail(c, 'account.confirm.passkey_error');
+                // A conta PRECISA existir. Sem esta linha, as únicas barreiras seriam o
+                // challenge na sessão e `verifyPasskeyAuthentication(c.accountId, ...)`:
+                // um `AccountStore` que resolva a credencial pelo `rawId` (fluxo
+                // discoverable/usernameless, comum em WebAuthn) aceitaria uma assertion
+                // com `accountId: undefined` e chegaria a `completeSudo` sem conta.
+                if (!c.account)
+                    return h.fail(c, 'account.confirm.passkey_error');
+                // Apaga challenge E vinculação juntos: são um par, e meio par na sessão
+                // é o começo de um estado que ninguém sabe interpretar depois.
+                const clearChallenge = () => {
+                    ctx.session.forget(CONFIRM_PASSKEY_CHALLENGE_KEY);
+                    ctx.session.forget(CONFIRM_PASSKEY_CHALLENGE_ACCOUNT_KEY);
+                };
+                const challenge = ctx.session.get(CONFIRM_PASSKEY_CHALLENGE_KEY);
+                if (!challenge) {
+                    clearChallenge();
+                    return h.fail(c, 'account.confirm.passkey_error');
+                }
+                // VINCULAÇÃO À CONTA: quem consome o challenge tem de ser quem o pediu.
+                // "Está pendente nesta sessão" NÃO implica "é desta conta" — a sessão
+                // sobrevive ao logout+login de outra conta no mesmo navegador.
+                //
+                // ESTRITO (fail-closed): challenge SEM vinculação também é recusado. O
+                // emissor deste pacote sempre grava o par, então um challenge solto na
+                // sessão só pode vir de uma sessão anterior (outra versão do pacote, ou
+                // escrita por fora) — e é exatamente essa a forma que o atacante do
+                // navegador compartilhado consegue deixar para trás. Aceitar `undefined`
+                // seria fail-open: bastaria apagar a vinculação para anular a barreira.
+                const boundTo = ctx.session.get(CONFIRM_PASSKEY_CHALLENGE_ACCOUNT_KEY);
+                if (boundTo === undefined || boundTo !== c.accountId) {
+                    clearChallenge();
+                    return h.fail(c, 'account.confirm.passkey_error');
+                }
+                const raw = ctx.request.input('response');
+                let parsed = null;
+                try {
+                    parsed = raw ? JSON.parse(raw) : null;
+                }
+                catch {
+                    parsed = null;
+                }
+                const ok = parsed
+                    ? ((await c.cfg.accountStore.verifyPasskeyAuthentication?.(c.accountId, parsed, challenge)) ?? false)
+                    : false;
+                clearChallenge();
+                if (!ok)
+                    return h.fail(c, 'account.confirm.passkey_error');
+                return h.completeSudo(c, 'passkey');
+            });
+        },
+    };
+}

package/build/src/host/sudo/methods/password.d.ts

@@ -0,0 +1,19 @@
+import type { SudoMethod } from '../types.js';
+/**
+ * Confirmação por senha — o método histórico.
+ *
+ * URL LEGADA: registra `POST /account/confirm` (não `/account/confirm/password`)
+ * porque hosts externos e telas customizadas (fora deste pacote) dependem
+ * desse path histórico — trocá-lo quebraria essas integrações sem que o
+ * pacote tenha como saber ou migrar por elas. É também a razão de `register`
+ * receber o router cru em vez de o runtime montar por convenção a partir do
+ * `id`.
+ *
+ * LIMITAÇÃO CONHECIDA de `isAvailable`: ele responde "a conta tem hash?", não
+ * "o usuário conhece a senha?". Host que cria contas passwordless gravando um
+ * hash aleatório para satisfazer uma coluna NOT NULL verá este método como
+ * disponível e mostrará um campo que ninguém consegue preencher. De dentro do
+ * pacote, hash aleatório e hash real são indistinguíveis; a correção é do host
+ * (coluna nullable) ou basta omitir `password()` da lista de `methods`.
+ */
+export declare function password(): SudoMethod;