@adonis-agora/authkit-server 0.45.0 → 0.46.0

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

@@ -0,0 +1,93 @@
+import { isSudoMethodEnabled } from '../runtime.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 function password() {
+    return {
+        id: 'password',
+        /**
+         * Fallback conservador herdado de `isPasswordless` (o original em
+         * `account_confirm_controller.ts`): sem informação, assumimos que a conta
+         * TEM senha.
+         *
+         * `__getRawRow` não faz parte do contrato público de `AccountStore` — é um
+         * escape hatch interno do store Lucid (mesmo cast usado em outros pontos do
+         * pacote, ex.: account_security_controller.ts). Um `AccountStore` do SPI
+         * (o público-alvo deste método) não é obrigado a implementá-lo. Se
+         * tratássemos "não sei" como indisponível, um store customizado sem esse
+         * escape hatch perderia o método `password` mesmo com `verifyCredentials`
+         * funcionando — e, sem passkey também, o usuário fica sem nenhum método e
+         * travado fora do sudo mode. Por isso os três casos abaixo:
+         *
+         * - `__getRawRow` ausente (`undefined`) → disponível (não sabemos, não escondemos).
+         * - Presente e devolve hash não-vazio → disponível.
+         * - Presente e devolve hash vazio/nulo (ou linha nula) → indisponível (sabemos que não há senha).
+         * - Lança exceção → disponível (mesmo espírito conservador: não sabemos).
+         *
+         * Esconder o método é sempre pior que mostrá-lo: uma opção visível que
+         * falha é recuperável (o usuário tenta e escolhe outra); uma opção
+         * escondida não é nem descobrível.
+         */
+        async isAvailable(c) {
+            const getRawRow = c.cfg.accountStore.__getRawRow;
+            if (typeof getRawRow !== 'function')
+                return true;
+            try {
+                const row = await getRawRow.call(c.cfg.accountStore, c.accountId);
+                // Store expõe a função e respondeu (linha nula ou hash vazio/nulo): sabemos
+                // que não há senha → indisponível.
+                return Boolean(row?.password);
+            }
+            catch {
+                return true;
+            }
+        },
+        async describe() {
+            return {
+                labelKey: 'account.confirm.method.password',
+                kind: 'form',
+                endpoint: '/account/confirm',
+                fields: [
+                    { name: 'password', type: 'password', labelKey: 'account.confirm.password_label' },
+                ],
+            };
+        },
+        register(router, h) {
+            router.post('/account/confirm', async (ctx) => {
+                const c = await h.contextFrom(ctx);
+                // ANTES de qualquer verificação: o host desligou este método?
+                // A rota é montada incondicionalmente (decisão de tempo de registro),
+                // então `config.sudo.methods` só desabilita de fato se o handler
+                // recusar. Responde `fail` — o mesmo redirect+flash de uma senha
+                // errada — em vez de 404: assim a resposta não distingue "método
+                // desligado" de "senha incorreta" e não vaza a config do host.
+                if (!isSudoMethodEnabled(c.cfg, 'password'))
+                    return h.fail(c, 'account.confirm.error');
+                const { password: submitted } = ctx.request.only(['password']);
+                // `c.account` é nullable (sessão viva de conta apagada → findById null)
+                // e `email` pode vir vazio de um store customizado; sem e-mail não há
+                // como verificar credenciais.
+                if (!submitted || !c.account || !c.account.email)
+                    return h.fail(c, 'account.confirm.error');
+                const ok = await c.cfg.accountStore.verifyCredentials(c.account.email, submitted);
+                if (!ok)
+                    return h.fail(c, 'account.confirm.error');
+                return h.completeSudo(c, 'password');
+            });
+        },
+    };
+}

package/build/src/host/sudo/runtime.d.ts

@@ -0,0 +1,141 @@
+import type { HttpContext, Router } from '@adonisjs/core/http';
+import type { ResolvedServerConfig } from '../../define_config.js';
+import type { SudoContext, SudoMethod, SudoRouteHelpers } from './types.js';
+/** Último método usado com sucesso — só ordena a tela, não restringe nada. */
+export declare const LAST_METHOD_SESSION_KEY = "authkit_sudo_last_method";
+/**
+ * Monta o `SudoContext` a partir do `HttpContext`.
+ *
+ * Mora AQUI, e não no controller, porque é o construtor canônico do contexto
+ * que `completeSudo`/`fail` recebem e que todo `SudoMethod` usa — é runtime do
+ * SPI, não detalhe da tela. Enquanto morava em `controllers/`, o barrel do SPI
+ * reexportava de lá só para esconder isso, e o ciclo
+ * `runtime → controller → runtime` era o que obrigava `configuredSudoMethods` a
+ * viver longe de `isSudoMethodEnabled` — origem do drift entre os dois lados.
+ */
+export declare function sudoContextFrom(ctx: HttpContext): Promise<SudoContext>;
+/**
+ * Registra a lista montada. Chamado UMA vez por `registerAuthHost`, e
+ * SUBSTITUI (não acumula): registrar o host de novo é redefinir o que existe,
+ * não somar ao que existia.
+ */
+export declare function setMountedSudoMethods(methods: SudoMethod[]): void;
+/** Um método com este id teve rotas montadas? Usado só para avisar de drift. */
+export declare function isSudoMethodMounted(methodId: string): boolean;
+/**
+ * Lista de métodos que o host configurou EXPLICITAMENTE, ou `null` quando ele
+ * não configurou nada (ausente ou vazio → "não restringi").
+ *
+ * Ponto ÚNICO de leitura de `config.sudo.methods`. Existe aqui (e não no
+ * controller) porque quem precisa dela são os dois lados — a tela, que decide o
+ * que OFERECER, e os handlers dos métodos, que decidem o que ACEITAR — e o
+ * controller já importa os métodos built-in, o que tornaria a dependência
+ * circular se os métodos importassem de volta o controller.
+ */
+export declare function explicitSudoMethods(cfg: ResolvedServerConfig): SudoMethod[] | null;
+/**
+ * O método `methodId` está habilitado para ESTE host?
+ *
+ * Toda rota registrada por um `SudoMethod` DEVE começar por aqui. Sem essa
+ * checagem, `config.sudo.methods` só esconderia o método da tela: o endpoint
+ * continuaria vivo e concedendo sudo — uma config que aparenta restringir e não
+ * restringe é pior que nenhuma config.
+ *
+ * Sem configuração explícita nada foi restringido: vale o que tem rota montada.
+ * Isso é deliberado — a lista de defaults não é a fonte de verdade do que está
+ * montado, e tratá-la como tal derrubaria um método customizado do host.
+ */
+export declare function isSudoMethodEnabled(cfg: ResolvedServerConfig, methodId: string): boolean;
+/**
+ * Lista efetiva de métodos da TELA — o irmão de `isSudoMethodEnabled`, e por
+ * isso mora coladinho nele.
+ *
+ * Sem config explícita cai na lista MONTADA, exatamente a mesma resposta que
+ * `isSudoMethodEnabled` dá do lado dos handlers ("vale o que tem rota"). Antes
+ * caía numa lista de defaults hardcoded, e os dois lados divergiam de verdade:
+ * um host que fizesse só
+ *
+ * ```ts
+ * registerAuthHost(router, { sudoMethods: [sudoMethods.magicLink()] })
+ * ```
+ *
+ * montava só magic-link, mas a tela oferecia password + passkey (ambos 404) e
+ * NÃO oferecia magic-link, que funcionava. Caindo na lista montada, o drift
+ * fica estruturalmente impossível no caso sem config: é literalmente a mesma
+ * lista. O aviso de flag-drift do controller passa a valer só para o caso que
+ * sobra — config explícita divergindo do que foi montado.
+ */
+export declare function configuredSudoMethods(cfg: ResolvedServerConfig): SudoMethod[];
+/**
+ * Envelopa o router entregue a `method.register` para que TODO handler que ele
+ * registrar seja barrado quando `config.sudo.methods` não incluir o método.
+ *
+ * POR QUE NO PONTO DE REGISTRO, e não dentro de cada handler: a barreira é a
+ * diferença entre uma config que restringe e uma que só esconde a opção da tela
+ * enquanto o endpoint segue concedendo sudo (falha Critical). Deixá-la a cargo
+ * de quem escreve o método significa que o PRIMEIRO método que esquecer a
+ * chamada reabre a falha — e nada detecta. Aqui a garantia é estrutural: o
+ * método não tem como registrar uma rota desguardada, porque não é ele quem
+ * segura o router.
+ *
+ * Os built-in CONTINUAM checando por dentro, e isso não é redundância inútil:
+ * cada um recusa na forma que o seu endpoint exige (o `passkey/options` é XHR e
+ * devolve JSON 404; um 302 para HTML quebraria o cliente). Este envelope é o
+ * piso genérico — recusa com `fail`, o mesmo redirect+flash de um erro comum,
+ * que não distingue "método desligado" de "credencial errada" e portanto não
+ * vaza a config do host.
+ *
+ * O QUE NÃO CABE NA BARREIRA É RECUSADO, não tolerado: um handler que não seja
+ * função (tupla `[Controller, 'metodo']`) e os atalhos `resource()`/
+ * `shallowResource()` lançam no ponto de registro. Ver
+ * `ROUTER_CONTROLLER_SHORTCUTS` e o `assertWrappableHandler` abaixo.
+ * (`on()` continua passando: ele registra redirect/render estático, sem handler
+ * que possa alcançar `completeSudo`.)
+ *
+ * CUSTO: resolve o config do container antes do handler. Não usa
+ * `contextFrom` no caminho feliz de propósito — aquilo faz `findById`, e pagar
+ * uma leitura de conta a mais em toda rota de sudo para uma checagem que só lê
+ * a config seria desperdício. O contexto completo só é montado para recusar.
+ */
+export declare function guardSudoRoutes(router: Router, methodId: string, h: SudoRouteHelpers, 
+/**
+ * Aplica o throttle do host a CADA rota que o método registrar (no-op quando
+ * o rate-limit está desligado). É `registerAuthHost` quem passa isto, porque
+ * é lá que os throttles existem — e é aqui que a rota nasce.
+ *
+ * O throttle que chega aqui é o do bucket de SUDO, não o de login. Mesmos
+ * limites, contagem separada: login mede um anônimo adivinhando credenciais,
+ * sudo mede um usuário JÁ autenticado reprovando a própria identidade.
+ * Compartilhando o bucket, quem erra a senha no `/account/confirm` gastava o
+ * orçamento de login do próprio IP — e um ataque de credencial no login
+ * trancava a confirmação de quem está legitimamente logado atrás do mesmo
+ * NAT. Ver `ResolvedRateLimitConfig.sudo`.
+ *
+ * Fica no wrapper, e não no contrato de `SudoRouteHelpers`, porque throttle
+ * não é decisão do método: um método que pudesse pedir throttle poderia
+ * também NÃO pedir, e o `POST` que emite o magic link de sudo — que dispara
+ * um e-mail por chamada — voltaria a ficar sem nenhum. Aqui a cobertura é da
+ * mesma natureza da barreira de `config.sudo.methods`: estrutural, sem
+ * depender de quem escreve o método lembrar de nada.
+ */
+applyThrottle?: (route: unknown) => void): Router;
+/**
+ * ÚNICO ponto do pacote que concede sudo. Nenhum `SudoMethod` chama
+ * `markSudo` diretamente: o método decide se verificou, o runtime concede,
+ * audita e redireciona.
+ */
+export declare function completeSudo(c: SudoContext, methodId: string): Promise<unknown>;
+/**
+ * Falha de confirmação: flash + volta pro /account/confirm preservando o
+ * destino. Substitui a coreografia que estava duplicada cinco vezes no
+ * controller.
+ */
+export declare function fail(c: SudoContext, messageKey: string): Promise<unknown>;
+/**
+ * Filtra os métodos disponíveis para esta conta e promove o último usado.
+ *
+ * `isAvailable` que lança NÃO derruba a tela: um método quebrado não pode
+ * trancar o usuário fora dos outros — mesmo espírito do FAIL-SAFE de
+ * `requireSudo`.
+ */
+export declare function resolveAvailableMethods(c: SudoContext, methods: SudoMethod[]): Promise<SudoMethod[]>;

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

@@ -0,0 +1,327 @@
+import { markSudo } from '../sudo_mode.js';
+import { accountHome } from '../account_home.js';
+import { translate } from '../i18n.js';
+import { ACCOUNT_SESSION_KEY } from '../middleware/account_auth.js';
+import { validateReturnTo } from '../controllers/account_session_controller.js';
+/** Último método usado com sucesso — só ordena a tela, não restringe nada. */
+export const LAST_METHOD_SESSION_KEY = 'authkit_sudo_last_method';
+/**
+ * Monta o `SudoContext` a partir do `HttpContext`.
+ *
+ * Mora AQUI, e não no controller, porque é o construtor canônico do contexto
+ * que `completeSudo`/`fail` recebem e que todo `SudoMethod` usa — é runtime do
+ * SPI, não detalhe da tela. Enquanto morava em `controllers/`, o barrel do SPI
+ * reexportava de lá só para esconder isso, e o ciclo
+ * `runtime → controller → runtime` era o que obrigava `configuredSudoMethods` a
+ * viver longe de `isSudoMethodEnabled` — origem do drift entre os dois lados.
+ */
+export async function sudoContextFrom(ctx) {
+    const service = await ctx.containerResolver.make('authkit.server');
+    const cfg = service.config;
+    const accountId = ctx.session.get(ACCOUNT_SESSION_KEY);
+    const account = await cfg.accountStore.findById(accountId);
+    // PRECEDÊNCIA do return_to. Num GET a query string é a única fonte real. Num
+    // POST o alvo do redirect vem do campo hidden do form: deixar a query string
+    // vencer permitiria a um link `?return_to=...` sequestrar o destino de um form
+    // que o usuário já preencheu — e seria uma mudança silenciosa de um alvo de
+    // redirect em relação ao comportamento histórico (`request.input`, que no
+    // Adonis já dá precedência ao corpo). `validateReturnTo` roda nos dois casos.
+    const fromBody = ctx.request.input?.('return_to');
+    const fromQuery = ctx.request.qs?.()?.return_to;
+    const isPost = String(ctx.request.method?.() ?? '').toUpperCase() === 'POST';
+    const raw = isPost ? (fromBody ?? fromQuery) : (fromQuery ?? fromBody);
+    return { ctx, cfg, accountId, account, returnTo: validateReturnTo(raw) };
+}
+/**
+ * Métodos cujas rotas FORAM montadas por `registerAuthHost`, na ordem em que
+ * ele as montou. Guarda os OBJETOS, não só os ids, porque esta lista é também
+ * a lista efetiva da TELA quando o host não configura `config.sudo.methods` —
+ * ver `configuredSudoMethods`.
+ */
+const mountedSudoMethods = [];
+/**
+ * Registra a lista montada. Chamado UMA vez por `registerAuthHost`, e
+ * SUBSTITUI (não acumula): registrar o host de novo é redefinir o que existe,
+ * não somar ao que existia.
+ */
+export function setMountedSudoMethods(methods) {
+    mountedSudoMethods.splice(0, mountedSudoMethods.length, ...methods);
+}
+/** Um método com este id teve rotas montadas? Usado só para avisar de drift. */
+export function isSudoMethodMounted(methodId) {
+    return mountedSudoMethods.some((m) => m?.id === methodId);
+}
+/**
+ * Lista de métodos que o host configurou EXPLICITAMENTE, ou `null` quando ele
+ * não configurou nada (ausente ou vazio → "não restringi").
+ *
+ * Ponto ÚNICO de leitura de `config.sudo.methods`. Existe aqui (e não no
+ * controller) porque quem precisa dela são os dois lados — a tela, que decide o
+ * que OFERECER, e os handlers dos métodos, que decidem o que ACEITAR — e o
+ * controller já importa os métodos built-in, o que tornaria a dependência
+ * circular se os métodos importassem de volta o controller.
+ */
+export function explicitSudoMethods(cfg) {
+    const configured = cfg?.sudo?.methods;
+    return Array.isArray(configured) && configured.length ? configured : null;
+}
+/**
+ * O método `methodId` está habilitado para ESTE host?
+ *
+ * Toda rota registrada por um `SudoMethod` DEVE começar por aqui. Sem essa
+ * checagem, `config.sudo.methods` só esconderia o método da tela: o endpoint
+ * continuaria vivo e concedendo sudo — uma config que aparenta restringir e não
+ * restringe é pior que nenhuma config.
+ *
+ * Sem configuração explícita nada foi restringido: vale o que tem rota montada.
+ * Isso é deliberado — a lista de defaults não é a fonte de verdade do que está
+ * montado, e tratá-la como tal derrubaria um método customizado do host.
+ */
+export function isSudoMethodEnabled(cfg, methodId) {
+    const explicit = explicitSudoMethods(cfg);
+    if (explicit === null)
+        return true;
+    return explicit.some((m) => m?.id === methodId);
+}
+/**
+ * Lista efetiva de métodos da TELA — o irmão de `isSudoMethodEnabled`, e por
+ * isso mora coladinho nele.
+ *
+ * Sem config explícita cai na lista MONTADA, exatamente a mesma resposta que
+ * `isSudoMethodEnabled` dá do lado dos handlers ("vale o que tem rota"). Antes
+ * caía numa lista de defaults hardcoded, e os dois lados divergiam de verdade:
+ * um host que fizesse só
+ *
+ * ```ts
+ * registerAuthHost(router, { sudoMethods: [sudoMethods.magicLink()] })
+ * ```
+ *
+ * montava só magic-link, mas a tela oferecia password + passkey (ambos 404) e
+ * NÃO oferecia magic-link, que funcionava. Caindo na lista montada, o drift
+ * fica estruturalmente impossível no caso sem config: é literalmente a mesma
+ * lista. O aviso de flag-drift do controller passa a valer só para o caso que
+ * sobra — config explícita divergindo do que foi montado.
+ */
+export function configuredSudoMethods(cfg) {
+    return explicitSudoMethods(cfg) ?? mountedSudoMethods;
+}
+/**
+ * Verbos HTTP com a forma `(pattern, handler, ...)` — o handler é o SEGUNDO
+ * argumento.
+ *
+ * `route` NÃO entra aqui: sua assinatura é `(pattern, methods, handler)`, com o
+ * handler no TERCEIRO argumento, e por isso tem tratamento próprio no Proxy.
+ * Deixá-lo de fora da barreira seria um bypass silencioso — `router.route()`
+ * registra rota igual a qualquer verbo.
+ */
+const ROUTER_VERBS = ['get', 'post', 'put', 'patch', 'delete', 'any'];
+/**
+ * Atalhos do `Router` que registram rotas SEM receber um handler-função: eles
+ * expandem um CONTROLLER em N rotas por convenção. Não há função para embrulhar
+ * — a barreira não tem por onde entrar —, então são recusados no boot.
+ *
+ * Ver `assertWrappableHandler` para o porquê de recusar em vez de deixar passar.
+ */
+const ROUTER_CONTROLLER_SHORTCUTS = ['resource', 'shallowResource'];
+/**
+ * Envelopa o router entregue a `method.register` para que TODO handler que ele
+ * registrar seja barrado quando `config.sudo.methods` não incluir o método.
+ *
+ * POR QUE NO PONTO DE REGISTRO, e não dentro de cada handler: a barreira é a
+ * diferença entre uma config que restringe e uma que só esconde a opção da tela
+ * enquanto o endpoint segue concedendo sudo (falha Critical). Deixá-la a cargo
+ * de quem escreve o método significa que o PRIMEIRO método que esquecer a
+ * chamada reabre a falha — e nada detecta. Aqui a garantia é estrutural: o
+ * método não tem como registrar uma rota desguardada, porque não é ele quem
+ * segura o router.
+ *
+ * Os built-in CONTINUAM checando por dentro, e isso não é redundância inútil:
+ * cada um recusa na forma que o seu endpoint exige (o `passkey/options` é XHR e
+ * devolve JSON 404; um 302 para HTML quebraria o cliente). Este envelope é o
+ * piso genérico — recusa com `fail`, o mesmo redirect+flash de um erro comum,
+ * que não distingue "método desligado" de "credencial errada" e portanto não
+ * vaza a config do host.
+ *
+ * O QUE NÃO CABE NA BARREIRA É RECUSADO, não tolerado: um handler que não seja
+ * função (tupla `[Controller, 'metodo']`) e os atalhos `resource()`/
+ * `shallowResource()` lançam no ponto de registro. Ver
+ * `ROUTER_CONTROLLER_SHORTCUTS` e o `assertWrappableHandler` abaixo.
+ * (`on()` continua passando: ele registra redirect/render estático, sem handler
+ * que possa alcançar `completeSudo`.)
+ *
+ * CUSTO: resolve o config do container antes do handler. Não usa
+ * `contextFrom` no caminho feliz de propósito — aquilo faz `findById`, e pagar
+ * uma leitura de conta a mais em toda rota de sudo para uma checagem que só lê
+ * a config seria desperdício. O contexto completo só é montado para recusar.
+ */
+export function guardSudoRoutes(router, methodId, h, 
+/**
+ * Aplica o throttle do host a CADA rota que o método registrar (no-op quando
+ * o rate-limit está desligado). É `registerAuthHost` quem passa isto, porque
+ * é lá que os throttles existem — e é aqui que a rota nasce.
+ *
+ * O throttle que chega aqui é o do bucket de SUDO, não o de login. Mesmos
+ * limites, contagem separada: login mede um anônimo adivinhando credenciais,
+ * sudo mede um usuário JÁ autenticado reprovando a própria identidade.
+ * Compartilhando o bucket, quem erra a senha no `/account/confirm` gastava o
+ * orçamento de login do próprio IP — e um ataque de credencial no login
+ * trancava a confirmação de quem está legitimamente logado atrás do mesmo
+ * NAT. Ver `ResolvedRateLimitConfig.sudo`.
+ *
+ * Fica no wrapper, e não no contrato de `SudoRouteHelpers`, porque throttle
+ * não é decisão do método: um método que pudesse pedir throttle poderia
+ * também NÃO pedir, e o `POST` que emite o magic link de sudo — que dispara
+ * um e-mail por chamada — voltaria a ficar sem nenhum. Aqui a cobertura é da
+ * mesma natureza da barreira de `config.sudo.methods`: estrutural, sem
+ * depender de quem escreve o método lembrar de nada.
+ */
+applyThrottle) {
+    const wrap = (handler) => async (ctx) => {
+        const service = await ctx.containerResolver.make('authkit.server');
+        if (isSudoMethodEnabled(service.config, methodId))
+            return handler(ctx);
+        const c = await h.contextFrom(ctx);
+        return h.fail(c, 'account.confirm.error');
+    };
+    /**
+     * A barreira só sabe embrulhar handler-FUNÇÃO. Qualquer outra forma
+     * (`[Controller, 'method']`, string `'Controller.method'`) registra uma rota
+     * que `config.sudo.methods` não desabilita e que alcança o `completeSudo`
+     * público — um bypass silencioso, no exato ponto onde a barreira devia ser
+     * estrutural.
+     *
+     * Por isso LANÇA, em vez de deixar passar. Antes o argumento era "nenhum
+     * built-in registra assim" — mas isso é propriedade dos built-in, não da
+     * barreira, e o público-alvo do SPI é justamente quem não é built-in.
+     *
+     * É boot-time e é alto: o host descobre no primeiro `node ace serve`, não em
+     * produção com uma rota de sudo desguardada. A saída é registrar um wrapper
+     * de uma linha (`(ctx) => new Ctrl().metodo(ctx)`), que passa pela barreira.
+     */
+    const assertWrappableHandler = (verb, pattern, handler) => {
+        if (typeof handler === 'function')
+            return handler;
+        throw new Error(`authkit: o método de sudo "${methodId}" registrou "${verb} ${pattern}" com um handler ` +
+            `que não é função (${handler === undefined ? 'undefined' : typeof handler}). ` +
+            'Métodos de sudo precisam registrar handler-função para receber a barreira de ' +
+            '`config.sudo.methods` — uma tupla `[Controller, \'metodo\']` registraria uma rota que ' +
+            'a config não desabilita e que alcança `completeSudo`. Envolva o controller numa ' +
+            "função: `router.post(pattern, (ctx) => new Controller().metodo(ctx))`.");
+    };
+    const wrapIfFn = (verb, pattern, handler) => wrap(assertWrappableHandler(verb, pattern, handler));
+    return new Proxy(router, {
+        // `receiver` é DELIBERADAMENTE `target`, não o Proxy: o `Router` do Adonis é
+        // uma classe com campos privados (`#app`, `#globalMatchers`, `#pushToRoutes`),
+        // e ler/chamar um membro com `this` apontando para o Proxy lança
+        // `TypeError: Cannot read private member #app`.
+        get(target, prop) {
+            const original = Reflect.get(target, prop, target);
+            if (typeof original !== 'function')
+                return original;
+            // Throttle na rota recém-criada. O `Route` real é preservado e devolvido,
+            // então `.as()`/`.use()` seguem encadeando do lado de fora.
+            const throttled = (route) => {
+                applyThrottle?.(route);
+                return route;
+            };
+            // `route(pattern, methods, handler)` — handler no TERCEIRO argumento.
+            if (prop === 'route') {
+                return (pattern, methods, handler, ...rest) => throttled(original.call(target, pattern, methods, wrapIfFn('route', pattern, handler), ...rest));
+            }
+            if (ROUTER_VERBS.includes(prop)) {
+                return (pattern, handler, ...rest) => throttled(original.call(target, pattern, wrapIfFn(String(prop).toUpperCase(), pattern, handler), ...rest));
+            }
+            // `resource()`/`shallowResource()` expandem um controller em N rotas por
+            // convenção: não passa handler-função por lugar nenhum, e a barreira não
+            // teria o que embrulhar. Recusa no boot pela mesma razão da tupla — deixar
+            // passar seria registrar rotas de sudo que `config.sudo.methods` não
+            // desabilita.
+            if (ROUTER_CONTROLLER_SHORTCUTS.includes(prop)) {
+                return (pattern) => {
+                    throw new Error(`authkit: o método de sudo "${methodId}" chamou router.${String(prop)}("${pattern}"), ` +
+                        'que registra rotas a partir de um controller e portanto não pode receber a ' +
+                        'barreira de `config.sudo.methods`. Registre as rotas do método uma a uma, com ' +
+                        'handler-função.');
+                };
+            }
+            // Todo o RESTO da API do `Router` (`group`, `on`, `where`, `use`, ...)
+            // segue funcionando, ligado ao router real. Sem o
+            // `bind`, um `router.group(() => ...)` — uso perfeitamente legítimo do
+            // tipo `Router` que `SudoMethod.register` declara receber — rodaria com
+            // `this === Proxy` e explodiria no boot da aplicação.
+            //
+            // `original.call(target, ...)` nos verbos e o `bind` aqui preservam o
+            // RETORNO real (`Route`/`RouteGroup`), então `.as()`/`.use()`/
+            // `.middleware()`/`.prefix()` continuam encadeando normalmente.
+            return original.bind(target);
+        },
+    });
+}
+/**
+ * ÚNICO ponto do pacote que concede sudo. Nenhum `SudoMethod` chama
+ * `markSudo` diretamente: o método decide se verificou, o runtime concede,
+ * audita e redireciona.
+ */
+export async function completeSudo(c, methodId) {
+    // SEGUNDA barreira estrutural, irmã de `guardSudoRoutes`: aquela cobre
+    // "o método está habilitado?", esta cobre "a conta existe?".
+    //
+    // `sudoContextFrom` deixa `account: null` quando `findById` não acha nada —
+    // sessão viva de conta apagada ou anonimizada. Cada built-in já checa por
+    // dentro, mas depender disso é a mesma falha que `guardSudoRoutes` existe
+    // para eliminar do outro lado: o PRIMEIRO método desatento que fizer
+    // `contextFrom` → `completeSudo` concederia sudo sobre uma conta que não
+    // existe mais, e nada detectaria. A garantia tem de estar aqui, no único
+    // ponto de concessão.
+    // Falsy, não `=== null`: um contexto montado à mão que simplesmente omita
+    // `account` não pode escapar da barreira por um detalhe de forma.
+    if (!c.account)
+        return fail(c, 'account.confirm.error');
+    markSudo(c.ctx);
+    c.ctx.session.put(LAST_METHOD_SESSION_KEY, methodId);
+    await c.cfg.audit?.record({
+        type: 'sudo.confirmed',
+        accountId: c.accountId,
+        ip: c.ctx.request.ip?.() ?? null,
+        metadata: { method: methodId },
+    });
+    return c.ctx.response.redirect(c.returnTo ?? accountHome(c.cfg));
+}
+/**
+ * Falha de confirmação: flash + volta pro /account/confirm preservando o
+ * destino. Substitui a coreografia que estava duplicada cinco vezes no
+ * controller.
+ */
+export async function fail(c, messageKey) {
+    c.ctx.session.flash('confirmError', translate(c.cfg.messages, messageKey));
+    const qs = c.returnTo ? `?return_to=${encodeURIComponent(c.returnTo)}` : '';
+    return c.ctx.response.redirect(`/account/confirm${qs}`);
+}
+/**
+ * Filtra os métodos disponíveis para esta conta e promove o último usado.
+ *
+ * `isAvailable` que lança NÃO derruba a tela: um método quebrado não pode
+ * trancar o usuário fora dos outros — mesmo espírito do FAIL-SAFE de
+ * `requireSudo`.
+ */
+export async function resolveAvailableMethods(c, methods) {
+    const checked = await Promise.all(methods.map(async (m) => {
+        try {
+            return (await m.isAvailable(c)) ? m : null;
+        }
+        catch (error) {
+            // Fail-safe: um `isAvailable` quebrado não pode trancar o usuário fora
+            // dos outros métodos — mas precisa deixar rastro, senão um typo vira
+            // um método que some da tela em produção sem ninguém saber por quê.
+            // `?.` defensivo: em teste, `fakeSudoContext` pode não ter logger.
+            c.ctx.logger?.warn({ method: m.id, err: error }, `authkit: isAvailable() do método de sudo "${m.id}" lançou — método omitido da lista`);
+            return null;
+        }
+    }));
+    const available = checked.filter((m) => m !== null);
+    const last = c.ctx.session.get(LAST_METHOD_SESSION_KEY);
+    if (!last)
+        return available;
+    const preferred = available.filter((m) => m.id === last);
+    return preferred.length ? [...preferred, ...available.filter((m) => m.id !== last)] : available;
+}

package/build/src/host/sudo/types.d.ts

@@ -0,0 +1,93 @@
+import type { HttpContext, Router } from '@adonisjs/core/http';
+import type { ResolvedServerConfig } from '../../define_config.js';
+/** Contexto entregue a todo método de sudo. */
+export interface SudoContext {
+    ctx: HttpContext;
+    /**
+     * Conta logada no console — carregada com `accountStore.findById`.
+     *
+     * PODE ser null. O comentário original dizia "nunca null: o accountGuard já
+     * rodou", mas o `accountGuard` (register_auth_host.ts:91) só verifica que a
+     * CHAVE de sessão existe; ele nunca carrega a conta. Sessão viva de conta
+     * apagada/anonimizada → `findById` devolve null. Todo método deve tratar.
+     *
+     * `email` é `string` (não `string | null`) porque é o que o `AccountStore`
+     * de fato garante: `findById` devolve `AuthAccount`, cujo `email: string`
+     * (accounts/account_store.ts:4). A nulidade real está no objeto, não no campo.
+     */
+    account: {
+        id: string;
+        email: string;
+    } | null;
+    accountId: string;
+    /** Config resolvida do authkit (accountStore, messages, audit, mail...). */
+    cfg: ResolvedServerConfig;
+    /** Destino pós-confirmação, já validado — só caminhos internos. */
+    returnTo: string | null;
+}
+/** Como a tela deve renderizar o passo deste método. */
+export interface SudoMethodDescriptor {
+    /** Chave i18n do rótulo. Ex.: 'account.confirm.method.magic_link'. */
+    labelKey: string;
+    /**
+     * 'form'     — a tela renderiza `fields` e dá POST em `endpoint`.
+     * 'action'   — a tela dá POST em `endpoint` sem input.
+     * 'redirect' — a tela manda o usuário para `endpoint` (fluxo externo).
+     * 'webauthn' — a tela precisa RODAR o handshake WebAuthn antes de postar:
+     *              pede as options em `${endpoint}/options`, chama
+     *              `navigator.credentials.get` (via `@simplewebauthn/browser`) e
+     *              posta a assertion serializada no campo `response` de
+     *              `endpoint`.
+     *
+     * `'webauthn'` existe como KIND próprio, e não como um caso especial do id
+     * `passkey`, justamente para a tela não voltar a conhecer método nenhum pelo
+     * nome: o endpoint de options é DERIVADO do descritor. Qualquer método do SPI
+     * que implemente o mesmo par `POST <endpoint>/options` + `POST <endpoint>`
+     * ganha a tela embutida de graça.
+     *
+     * Um método `'webauthn'` NÃO é utilizável sem JavaScript. Renderizá-lo como
+     * um form de submit direto manda `response` vazio e o handler recusa sempre —
+     * foi exatamente essa a regressão que motivou este kind.
+     */
+    kind: 'form' | 'action' | 'redirect' | 'webauthn';
+    endpoint: string;
+    fields?: Array<{
+        name: string;
+        type: 'password' | 'text';
+        labelKey: string;
+    }>;
+}
+/** Helpers que o runtime entrega às rotas de um método. */
+export interface SudoRouteHelpers {
+    /** Monta o SudoContext a partir do HttpContext (resolve config, conta, returnTo). */
+    contextFrom(ctx: HttpContext): Promise<SudoContext>;
+    /** ÚNICO ponto de concessão de sudo no pacote. */
+    completeSudo(c: SudoContext, methodId: string): Promise<unknown>;
+    /** Flash de erro + volta pro /account/confirm preservando return_to. */
+    fail(c: SudoContext, messageKey: string): Promise<unknown>;
+}
+/**
+ * Método de confirmação de identidade (sudo mode).
+ *
+ * REGRA CENTRAL: um método NUNCA chama `markSudo`. Ele decide apenas SE
+ * verificou; conceder é do runtime, via `completeSudo`. `markSudo` é a
+ * concessão de privilégio — espalhá-la por N métodos multiplicaria por N as
+ * chances de alguém conceder sem ter verificado.
+ */
+export interface SudoMethod {
+    /** Estável. Vai no audit (`metadata.method`) e na preferência lembrada. */
+    readonly id: string;
+    /** Disponível para ESTA conta? Ex.: passkey só se houver passkey cadastrada. */
+    isAvailable(c: SudoContext): Promise<boolean>;
+    /** O que a tela mostra para este método. */
+    describe(c: SudoContext): Promise<SudoMethodDescriptor>;
+    /**
+     * Endpoints próprios. Opcional: métodos puramente 'redirect' (oidcStepUp)
+     * não registram nada, porque o fluxo sai do pacote.
+     *
+     * Recebe o router cru (não monta por convenção a partir do `id`) porque
+     * `password` e `passkey` precisam manter URLs legadas que uma convenção
+     * não comportaria.
+     */
+    register?(router: Router, h: SudoRouteHelpers): void;
+}

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

@@ -0,0 +1 @@
+export {};