@adonis-agora/authkit-server 0.82.2 → 0.83.0

package/build/src/host/controllers/interaction_controller.js

@@ -1,5 +1,6 @@
 import '../augmentations.js';
 import { supportsLoginMethodsPreference, supportsMagicLink, supportsOtpLogin, supportsPasskeys, } from '../../accounts/account_store.js';
+import { resolveAccountRoles } from '../account_roles.js';
 import { AdminSessionsService } from '../admin_sessions_service.js';
 import { guardBotProtection, resolveEffectiveBotProtection } from '../bot_protection.js';
 import { brandFor, isFirstParty } from '../branding.js';
@@ -16,8 +17,19 @@ import { authkitOrigin } from '../origin.js';
 import { createOtpLockout, generateOtpUnlockToken, rawToDbOtpUnlockToken, resolveEffectiveOtpLockout, } from '../otp_lockout.js';
 import { resolveRuntimeSettingsOrNoop } from '../runtime_settings.js';
 import { resolveEffectiveAuthMethods, resolveEffectiveMaintenanceMode, resolveEffectiveRegistration, resolveEffectiveSessionPolicy, } from '../runtime_toggles.js';
+import { SOCIAL_PENDING_KEY, SOCIAL_PENDING_TTL_MS, } from '../social_pending.js';
 import { buildTrustedDevicePayload, isTrustedDeviceValid, TRUSTED_DEVICE_COOKIE, } from '../trusted_device.js';
 import { normalizeUserLoginMethods, resolveEffectiveUserLoginMethods, } from '../user_login_methods.js';
+/**
+ * Conta com papel administrativo (`cfg.admin.roles`, default `['ADMIN']`) — o
+ * bypass do modo manutenção. Os papéis vêm de `resolveAccountRoles`, a mesma
+ * fonte do claim (`resolveTokenRoles`, ex.: authz), não só do `globalRoles`.
+ */
+async function isAdminAccount(cfg, account) {
+    const adminRoles = cfg.admin?.roles ?? ['ADMIN'];
+    const roles = await resolveAccountRoles(cfg, account);
+    return adminRoles.some((role) => roles.includes(role));
+}
 /**
  * Chave i18n do erro de status de conta (disabled/expired) compartilhada pelos
  * fluxos passwordless (magic link, OTP, passkey).
@@ -105,8 +117,7 @@ export default class AuthInteractionController {
         if (!status.allowed)
             return fail(accountStatusErrorKey(status.reason));
         const maintenance = await resolveEffectiveMaintenanceMode(settings);
-        if (maintenance.enabled &&
-            !(cfg.admin?.roles ?? ['ADMIN']).some((role) => (account.globalRoles ?? []).includes(role))) {
+        if (maintenance.enabled && !(await isAdminAccount(cfg, account))) {
             return render(ctx, 'maintenance', {
                 uid: details.uid,
                 csrfToken: ctx.request.csrfToken,
@@ -468,9 +479,7 @@ export default class AuthInteractionController {
         // Contas admin (role em cfg.admin.roles) CONTINUAM podendo logar.
         // Contas comuns são bloqueadas com a tela de manutenção.
         if (maintenance.enabled) {
-            const adminRoles = cfg.admin?.roles ?? ['ADMIN'];
-            const accountRoles = acc.globalRoles ?? [];
-            const isAdmin = adminRoles.some((r) => accountRoles.includes(r));
+            const isAdmin = await isAdminAccount(cfg, acc);
             if (!isAdmin) {
                 return render(ctx, 'maintenance', {
                     uid: details.uid,
@@ -563,9 +572,9 @@ export default class AuthInteractionController {
             ...(used.has('webauthn') ? { passkeyAvailable: false } : {}),
         });
     }
-    async configuredMfaGate(ctx, cfg, accountId, details, primary, primaryFactorId, rememberRequested, passwordless = primary !== 'pwd') {
+    async configuredMfaGate(ctx, cfg, accountId, details, primary, primaryFactorId, rememberRequested, passwordless = primary !== 'pwd', forceRequired = false) {
         const requiredFactors = cfg.mfa?.requiredFactors ?? 2;
-        const mfaRequired = this.acrRequiresMfa(cfg, details) || cfg.mfa?.requiredFactors !== undefined;
+        const mfaRequired = forceRequired || this.acrRequiresMfa(cfg, details) || cfg.mfa?.requiredFactors !== undefined;
         const mfa = (await cfg.accountStore.getMfaState?.(accountId)) ?? { enabled: false };
         const enrolledTotp = mfa.totp ?? mfa.enabled;
         const enrolledPasskey = await this.hasPasskeys(cfg, accountId);
@@ -736,8 +745,7 @@ export default class AuthInteractionController {
             });
         }
         const maintenance = await resolveEffectiveMaintenanceMode(settings);
-        if (maintenance.enabled &&
-            !(cfg.admin?.roles ?? ['ADMIN']).some((role) => (account.globalRoles ?? []).includes(role))) {
+        if (maintenance.enabled && !(await isAdminAccount(cfg, account))) {
             return cfg.render(ctx, 'maintenance', {
                 uid: flow.uid,
                 csrfToken: ctx.request.csrfToken,
@@ -950,12 +958,12 @@ export default class AuthInteractionController {
      *  - caso geral → `challenge`, com o accountId em `MFA_PENDING_KEY` e o fator
      *    primário (`primary`) em `MFA_PRIMARY_KEY`.
      */
-    async secondFactorGate(ctx, cfg, accountId, details, primary, primaryFactorId = primary, rememberRequested, passwordless = primary !== 'pwd') {
+    async secondFactorGate(ctx, cfg, accountId, details, primary, primaryFactorId = primary, rememberRequested, passwordless = primary !== 'pwd', forceRequired = false) {
         ctx.session.forget(MFA_CUSTOM_PRIMARY_KEY);
         clearMfaFlow(ctx);
         if (cfg.mfa)
-            return this.configuredMfaGate(ctx, cfg, accountId, details, primary, primaryFactorId, rememberRequested, passwordless);
-        const mfaRequired = this.acrRequiresMfa(cfg, details);
+            return this.configuredMfaGate(ctx, cfg, accountId, details, primary, primaryFactorId, rememberRequested, passwordless, forceRequired);
+        const mfaRequired = forceRequired || this.acrRequiresMfa(cfg, details);
         const mfa = (await cfg.accountStore.getMfaState?.(accountId)) ?? { enabled: false };
         // Passkey disponível como alternativa ao TOTP se o store suporta E a conta
         // tem ao menos uma credencial registrada.
@@ -1212,6 +1220,32 @@ export default class AuthInteractionController {
      * Consome o magic link. Em sucesso finaliza o login (amr `['email']`). Token
      * inválido/expirado volta ao início do login.
      */
+    /**
+     * GET /auth/interaction/:uid/social/continue — segunda metade do login social
+     * quando a conta deve o 2º fator (ver `AuthSocialController#callback`). Lê o
+     * login pendente da sessão UMA vez, confere que é desta interaction e passa
+     * pelo mesmo `secondFactorGate` dos outros fluxos, com `fed` como fator
+     * primário no `amr`.
+     */
+    async socialContinue(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const uid = ctx.request.param('uid');
+        const pending = ctx.session.get(SOCIAL_PENDING_KEY);
+        ctx.session.forget(SOCIAL_PENDING_KEY);
+        const details = await service.interactions.details(ctx);
+        if (!pending ||
+            pending.uid !== uid ||
+            details.uid !== uid ||
+            details.prompt.name !== 'login' ||
+            Date.now() - pending.at > SOCIAL_PENDING_TTL_MS) {
+            return ctx.response.redirect(`/auth/interaction/${uid}`);
+        }
+        const gate = await this.secondFactorGate(ctx, cfg, pending.accountId, details, 'fed', 'fed', undefined, true, pending.required);
+        if (gate.kind === 'challenge')
+            return gate.response;
+        return service.interactions.completeLogin(ctx, pending.accountId, { amr: ['fed'] });
+    }
     async magicLinkConsume(ctx) {
         const service = await ctx.containerResolver.make('authkit.server');
         const cfg = service.config;

package/build/src/host/controllers/pat_introspection_controller.d.ts

@@ -14,7 +14,7 @@ export default class PatIntrospectionController {
         sub: any;
         email: any;
         name: any;
-        roles: any;
+        roles: string[];
         scopes: any;
         audience: any;
         exp: any;

package/build/src/host/controllers/pat_introspection_controller.js

@@ -1,4 +1,5 @@
 import { timingSafeEqual } from 'node:crypto';
+import { resolveAccountRoles } from '../account_roles.js';
 function bearerMatches(header, expected) {
     if (!header || !header.startsWith('Bearer '))
         return false;
@@ -47,7 +48,7 @@ export default class PatIntrospectionController {
             sub: account.id,
             email: account.email,
             name: account.name ?? null,
-            roles: account.globalRoles ?? [],
+            roles: await resolveAccountRoles(cfg, account),
             scopes: meta.scopes,
             audience: meta.audience,
             exp: meta.exp,

package/build/src/host/controllers/registration_controller.d.ts

@@ -6,6 +6,16 @@ export default class AuthRegistrationController {
     showSignup(ctx: HttpContext): Promise<any>;
     /** POST /auth/interaction/:uid/signup — cria o usuário e finaliza o login. */
     signup(ctx: HttpContext): Promise<any>;
+    /**
+     * GET /auth/interaction/:uid/signup/confirm?token= — o dono do e-mail abriu o
+     * link do cadastro passwordless. Cria a conta (e-mail já verificado: quem
+     * clicou provou a caixa de entrada) e conclui pelo fluxo de magic link, que
+     * aplica os mesmos gates do login (status, manutenção, 2º fator).
+     *
+     * Conta que já existe → o link é recusado e a pessoa volta ao login: é o que
+     * faz o link valer uma vez só, sem estado no banco.
+     */
+    signupConfirm(ctx: HttpContext): Promise<void>;
     /** GET /auth/forgot-password — tela standalone. */
     showForgot(ctx: HttpContext): Promise<any>;
     /** POST /auth/forgot-password — gera token e (dev) loga o link. Sempre responde sucesso (não vaza emails). */

package/build/src/host/controllers/registration_controller.js

@@ -1,5 +1,6 @@
 import '../augmentations.js';
 import { randomBytes } from 'node:crypto';
+import { supportsAccountDeletion, supportsMagicLink } from '../../accounts/account_store.js';
 import { PasswordPolicyError } from '../../password/password_manager.js';
 import { AdminSessionsService } from '../admin_sessions_service.js';
 import { guardBotProtection, resolveEffectiveBotProtection } from '../bot_protection.js';
@@ -10,6 +11,7 @@ import { authkitOrigin } from '../origin.js';
 import { RuntimeSettings, resolveRuntimeSettings } from '../runtime_settings.js';
 import { resolveEffectiveAuthMethods, resolveEffectiveMaintenanceMode, resolveEffectiveRegistration, } from '../runtime_toggles.js';
 import { dispatchSecurityNotice } from '../security_notice_service.js';
+import { issueSignupToken, readSignupToken } from '../signup_token.js';
 import { forgotPasswordValidator, passwordlessSignupValidator, resetPasswordValidator, signupValidator, } from '../validators.js';
 /**
  * Best-effort: returns a RuntimeSettings backed by the container DB, or a no-op
@@ -170,6 +172,13 @@ export default class AuthRegistrationController {
             password: data.password,
         });
         if (!result.ok) {
+            // A conta acabou de nascer e o login dela falhou: sem desfazer, a pessoa
+            // ficaria com um e-mail "já cadastrado" numa conta em que nunca entrou.
+            if (created && supportsAccountDeletion(accountStore)) {
+                await accountStore.deleteAccount(created.id).catch((error) => {
+                    ctx.logger.error({ err: error, accountId: created.id }, 'authkit: falha ao desfazer conta após signup sem login');
+                });
+            }
             return render(ctx, 'signup', {
                 uid: ctx.request.param('uid'),
                 csrfToken: ctx.request.csrfToken,
@@ -206,47 +215,46 @@ export default class AuthRegistrationController {
         }
     }
     /**
-     * Cadastro passwordless: valida e-mail + nome, cria a conta (senha random
-     * inutilizável) se ainda não existe, emite um magic link e o envia. Sempre
-     * responde "link enviado" (anti-enumeração), exista a conta ou não. Consumir o
-     * link finaliza o login pelo fluxo de magic link já existente (GET /magic).
+     * Cadastro passwordless: valida e-mail + nome e envia um link. Conta existente
+     * recebe um magic link de login; e-mail novo recebe o link de confirmação do
+     * cadastro (`signupConfirm`), e só então a conta é criada. Sempre responde
+     * "link enviado" (anti-enumeração), exista a conta ou não.
      */
     async #passwordlessSignup(ctx, deps) {
-        const { cfg, brand, details } = deps;
+        const { cfg, brand } = deps;
         const render = cfg.render;
         const accountStore = cfg.accountStore;
         const uid = ctx.request.param('uid');
         const data = await ctx.request.validateUsing(passwordlessSignupValidator);
-        // Cria a conta se ainda não existe. Senha random inutilizável: o login é 100%
-        // passwordless (mesmo precedente das contas criadas por identidade social).
+        const origin = authkitOrigin(cfg);
         const existing = await accountStore.findByEmail(data.email);
-        if (!existing) {
-            const created = await accountStore.create({
-                email: data.email,
-                fullName: data.fullName,
-                password: randomBytes(24).toString('hex'),
-            });
-            await cfg.audit?.record({
-                type: 'signup',
-                accountId: created.id,
-                email: data.email,
-                ip: ctx.request.ip?.() ?? null,
-                clientId: details.params.client_id ?? null,
-            });
+        if (existing) {
+            // Conta já existe: o "cadastro" vira um login por magic link.
+            // `data.email` já é a forma normalizada, a mesma do login.
+            const issued = await accountStore.issueMagicLinkToken(data.email);
+            if (issued) {
+                const magicUrl = `${origin}/auth/interaction/${uid}/magic?token=${encodeURIComponent(issued.token)}`;
+                const to = issued.account.email;
+                if (cfg.mail?.onMagicLink) {
+                    await cfg.mail.onMagicLink({ email: to, magicUrl, token: issued.token });
+                }
+                else {
+                    await sendMagicLinkEmail(ctx, { email: to, magicUrl });
+                }
+            }
         }
-        // Emite + envia o magic link (mesma construção do login por magic link).
-        // `data.email` já é a forma normalizada — a mesma sob a qual a conta foi
-        // encontrada acima ou acabou de ser criada.
-        const issued = await accountStore.issueMagicLinkToken(data.email);
-        if (issued) {
-            const origin = authkitOrigin(cfg);
-            const magicUrl = `${origin}/auth/interaction/${uid}/magic?token=${encodeURIComponent(issued.token)}`;
-            const to = issued.account.email;
+        else {
+            // Conta nova: NÃO cria aqui. O link de confirmação leva e-mail + nome num
+            // token cifrado; a conta só nasce quando o dono do e-mail o abre
+            // (`signupConfirm`). Um envio que falha não deixa conta órfã, e digitar o
+            // e-mail de outra pessoa não cria nada.
+            const token = await issueSignupToken({ email: data.email, fullName: data.fullName ?? null });
+            const magicUrl = `${origin}/auth/interaction/${uid}/signup/confirm?token=${encodeURIComponent(token)}`;
             if (cfg.mail?.onMagicLink) {
-                await cfg.mail.onMagicLink({ email: to, magicUrl, token: issued.token });
+                await cfg.mail.onMagicLink({ email: data.email, magicUrl, token, kind: 'signup' });
             }
             else {
-                await sendMagicLinkEmail(ctx, { email: to, magicUrl });
+                await sendMagicLinkEmail(ctx, { email: data.email, magicUrl });
             }
         }
         // Resposta uniforme: "enviamos um link" (não vaza existência da conta).
@@ -257,6 +265,62 @@ export default class AuthRegistrationController {
             magicLinkSent: true,
         });
     }
+    /**
+     * GET /auth/interaction/:uid/signup/confirm?token= — o dono do e-mail abriu o
+     * link do cadastro passwordless. Cria a conta (e-mail já verificado: quem
+     * clicou provou a caixa de entrada) e conclui pelo fluxo de magic link, que
+     * aplica os mesmos gates do login (status, manutenção, 2º fator).
+     *
+     * Conta que já existe → o link é recusado e a pessoa volta ao login: é o que
+     * faz o link valer uma vez só, sem estado no banco.
+     */
+    async signupConfirm(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const accountStore = cfg.accountStore;
+        const uid = ctx.request.param('uid');
+        const backToLogin = `/auth/interaction/${uid}`;
+        const token = ctx.request.qs().token ?? '';
+        if (!cfg.passwordless?.signup || !supportsMagicLink(accountStore) || !token) {
+            return ctx.response.redirect(backToLogin);
+        }
+        const runtimeSettings = await getRuntimeSettings(ctx);
+        const registrationEnabled = await resolveEffectiveRegistration(cfg.registration?.enabled ?? true, runtimeSettings);
+        if (!registrationEnabled)
+            return ctx.response.redirect(backToLogin);
+        const claim = await readSignupToken(token);
+        if (!claim)
+            return ctx.response.redirect(backToLogin);
+        if (await accountStore.findByEmail(claim.email))
+            return ctx.response.redirect(backToLogin);
+        let created;
+        try {
+            created = await accountStore.create({
+                email: claim.email,
+                fullName: claim.fullName,
+                password: randomBytes(24).toString('hex'),
+                emailVerified: true,
+            });
+        }
+        catch (error) {
+            // Dois cliques simultâneos: o segundo perde na unicidade do e-mail.
+            if (await accountStore.findByEmail(claim.email))
+                return ctx.response.redirect(backToLogin);
+            throw error;
+        }
+        const details = await service.interactions.details(ctx);
+        await cfg.audit?.record({
+            type: 'signup',
+            accountId: created.id,
+            email: claim.email,
+            ip: ctx.request.ip?.() ?? null,
+            clientId: details.params.client_id ?? null,
+        });
+        const issued = await accountStore.issueMagicLinkToken(claim.email);
+        if (!issued)
+            return ctx.response.redirect(backToLogin);
+        return ctx.response.redirect(`/auth/interaction/${uid}/magic?token=${encodeURIComponent(issued.token)}`);
+    }
     /** GET /auth/forgot-password — tela standalone. */
     async showForgot(ctx) {
         const service = await ctx.containerResolver.make('authkit.server');

package/build/src/host/controllers/social_controller.js

@@ -1,10 +1,12 @@
 import '../augmentations.js';
 import { randomUUID } from 'node:crypto';
 import { supportsLoginMethodsPreference, supportsMagicLink, supportsPasskeys, supportsProviderIdentity, } from '../../accounts/account_store.js';
+import { resolveAccountRoles } from '../account_roles.js';
 import { normalizeEmailIdentifier } from '../email_identifier.js';
 import { assertLoginAllowed } from '../login_attempt.js';
 import { resolveRuntimeSettingsOrNoop } from '../runtime_settings.js';
 import { resolveEffectiveAuthMethods } from '../runtime_toggles.js';
+import { SOCIAL_PENDING_KEY } from '../social_pending.js';
 import { resolveEffectiveUserLoginMethods, } from '../user_login_methods.js';
 const UID_SESSION_KEY = 'authkit_social_uid';
 /**
@@ -29,6 +31,31 @@ async function resolveGlobalAuthMethodsForUser(cfg, settings) {
         configOverrides: cfg.authMethods,
     });
 }
+/**
+ * Política de 2º fator do login social para esta conta (ver
+ * `AuthSocialConfig.secondFactor`). Default `'enrolled'`. Os papéis passados à
+ * função vêm de `resolveAccountRoles` (o `resolveTokenRoles` do host, ex.: authz).
+ */
+async function resolveSecondFactorPolicy(cfg, account) {
+    const policy = cfg.social?.secondFactor ?? 'enrolled';
+    if (typeof policy !== 'function')
+        return policy;
+    return await policy({
+        id: account.id,
+        email: account.email,
+        roles: await resolveAccountRoles(cfg, account),
+    });
+}
+/** true se a conta tem TOTP confirmado ou ao menos uma passkey. */
+async function hasEnrolledSecondFactor(store, accountId) {
+    const mfa = (await store.getMfaState?.(accountId)) ?? { enabled: false };
+    if (mfa.totp ?? mfa.enabled)
+        return true;
+    if (!supportsPasskeys(store))
+        return false;
+    const list = await store.listPasskeys(accountId);
+    return Array.isArray(list) && list.length > 0;
+}
 export default class AuthSocialController {
     /** GET /auth/:provider/redirect/:uid — guarda o uid e redireciona para o provider OAuth. */
     async redirect(ctx) {
@@ -70,6 +97,20 @@ export default class AuthSocialController {
         //  2. Senão, e-mail conhecido → acha por e-mail e LIGA a identidade (linking).
         //  3. Senão → cria conta nova e liga a identidade.
         let user = await store.findByProviderIdentity(provider, profile.id);
+        // E-mail que o provider declara NÃO verificado não identifica ninguém: ligar
+        // por ele entregaria a conta de quem é dono do endereço a quem só o digitou
+        // no provider. `unsupported`/ausente (provider que não informa) segue valendo.
+        const emailUnverified = profile.emailVerificationState === 'unverified';
+        if (!user && email && emailUnverified) {
+            await cfg.audit?.record({
+                type: 'login.failure',
+                email,
+                ip: ctx.request.ip?.() ?? null,
+                metadata: { stage: 'social', provider, reason: 'provider_email_unverified' },
+            });
+            ctx.session.forget(UID_SESSION_KEY);
+            return ctx.response.redirect(backToLogin);
+        }
         if (!user && email) {
             // Busca pela MESMA forma normalizada que o login usa. Uma conta gravada
             // com outra grafia não é encontrada aqui e a pessoa ganharia uma SEGUNDA
@@ -95,7 +136,8 @@ export default class AuthSocialController {
                 email,
                 password: randomUUID(),
                 fullName: profile.name ?? null,
-                emailVerified: true,
+                // Só o provider que confirma o e-mail o torna verificado aqui.
+                emailVerified: profile.emailVerificationState === 'verified',
             });
             await store.linkProviderIdentity({
                 accountId: created.id,
@@ -154,6 +196,25 @@ export default class AuthSocialController {
             }
         }
         ctx.session.forget(UID_SESSION_KEY);
+        // 2º fator: o provider provou a identidade, mas quem cadastrou TOTP/passkey
+        // aqui espera que o fator valha também neste caminho. O desafio mora no
+        // interaction controller (mesmo gate de senha/magic link/OTP), então este
+        // passo só registra o login pendente e manda o browser para lá.
+        const policy = await resolveSecondFactorPolicy(cfg, user);
+        const needsGate = policy === 'required' ||
+            (policy === 'enrolled' && (!!cfg.mfa || (await hasEnrolledSecondFactor(store, user.id))));
+        if (needsGate) {
+            if (!uid)
+                return ctx.response.redirect(backToLogin);
+            const pending = {
+                accountId: user.id,
+                uid,
+                required: policy === 'required',
+                at: Date.now(),
+            };
+            ctx.session.put(SOCIAL_PENDING_KEY, pending);
+            return ctx.response.redirect(`/auth/interaction/${uid}/social/continue`);
+        }
         // Conclui a interaction OIDC para este usuário (escreve o 303 de volta ao authorize).
         // O cookie de interaction (path '/') sobrevive ao round-trip do provider OAuth.
         await service.interactions.completeLogin(ctx, user.id);

package/build/src/host/register_auth_host.js

@@ -488,6 +488,8 @@ export function registerAuthHost(router, opts = {}) {
     router.get('/auth/otp-unlock/:token', [C.interaction, 'otpUnlock']);
     router.get('/auth/interaction/:uid/signup', [C.registration, 'showSignup']);
     withLogin(router.post('/auth/interaction/:uid/signup', [C.registration, 'signup']));
+    // Confirmação do cadastro passwordless: a conta nasce aqui, não no POST.
+    router.get('/auth/interaction/:uid/signup/confirm', [C.registration, 'signupConfirm']);
     // Recuperação de senha (standalone).
     router.get('/auth/forgot-password', [C.registration, 'showForgot']);
     withLogin(router.post('/auth/forgot-password', [C.registration, 'forgot']));
@@ -499,6 +501,8 @@ export function registerAuthHost(router, opts = {}) {
     if (social) {
         router.get('/auth/:provider/redirect/:uid', [C.social, 'redirect']);
         router.get('/auth/:provider/callback', [C.social, 'callback']);
+        // 2º fator da conta depois do provider (ver AuthSocialConfig.secondFactor).
+        router.get('/auth/interaction/:uid/social/continue', [C.interaction, 'socialContinue']);
     }
     // PAT introspection (server-to-server).
     withIntrospection(router.post('/authkit/pat/introspect', [C.patIntrospection, 'handle']));

package/build/src/host/signup_token.d.ts

@@ -0,0 +1,9 @@
+/** Mesma janela do magic link de login. */
+export declare const SIGNUP_TOKEN_TTL = "15 minutes";
+export interface SignupClaim {
+    email: string;
+    fullName: string | null;
+}
+export declare function issueSignupToken(claim: SignupClaim): Promise<string>;
+/** Claim do token, ou `null` se adulterado, de outro propósito ou vencido. */
+export declare function readSignupToken(token: string): Promise<SignupClaim | null>;

package/build/src/host/signup_token.js

@@ -0,0 +1,31 @@
+import { loadEncryptionService } from '../keys/keystore_crypto.js';
+/**
+ * Token do link de confirmação do cadastro passwordless.
+ *
+ * O cadastro não cria a conta no POST: guarda e-mail + nome num token cifrado
+ * (APP_KEY), com prazo e propósito próprios, e a conta só nasce quando o dono do
+ * e-mail abre o link. Assim um envio que falha, ou um e-mail digitado por quem
+ * não é o dono, não deixa conta para trás nem dispara `account.created`.
+ *
+ * Sem estado no banco: a unicidade vem da própria conta — se ela já existe
+ * quando o link é aberto, o link é recusado.
+ */
+const PURPOSE = 'authkit_passwordless_signup';
+/** Mesma janela do magic link de login. */
+export const SIGNUP_TOKEN_TTL = '15 minutes';
+async function encryption() {
+    return (await loadEncryptionService());
+}
+export async function issueSignupToken(claim) {
+    return (await encryption()).encrypt(claim, SIGNUP_TOKEN_TTL, PURPOSE);
+}
+/** Claim do token, ou `null` se adulterado, de outro propósito ou vencido. */
+export async function readSignupToken(token) {
+    const claim = (await encryption()).decrypt(token, PURPOSE);
+    if (!claim || typeof claim.email !== 'string' || claim.email === '')
+        return null;
+    return {
+        email: claim.email,
+        fullName: typeof claim.fullName === 'string' ? claim.fullName : null,
+    };
+}

package/build/src/host/social_pending.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Passo pendente entre o callback social e o 2º fator, compartilhado pelo
+ * `AuthSocialController` (grava) e pelo `AuthInteractionController` (consome).
+ */
+/**
+ * Login social que passou pelo provider mas ainda deve o 2º fator da conta.
+ * Lido (uma vez) por `AuthInteractionController#socialContinue`.
+ */
+export declare const SOCIAL_PENDING_KEY = "authkit_social_pending";
+/** Validade do passo pendente: o desafio do 2º fator vem logo em seguida. */
+export declare const SOCIAL_PENDING_TTL_MS: number;
+export interface SocialPendingLogin {
+    accountId: string;
+    uid: string;
+    required: boolean;
+    at: number;
+}

package/build/src/host/social_pending.js

@@ -0,0 +1,11 @@
+/**
+ * Passo pendente entre o callback social e o 2º fator, compartilhado pelo
+ * `AuthSocialController` (grava) e pelo `AuthInteractionController` (consome).
+ */
+/**
+ * Login social que passou pelo provider mas ainda deve o 2º fator da conta.
+ * Lido (uma vez) por `AuthInteractionController#socialContinue`.
+ */
+export const SOCIAL_PENDING_KEY = 'authkit_social_pending';
+/** Validade do passo pendente: o desafio do 2º fator vem logo em seguida. */
+export const SOCIAL_PENDING_TTL_MS = 5 * 60 * 1000;