@adonis-agora/authkit-server 0.54.0 → 0.55.1

package/build/index.d.ts

@@ -55,7 +55,9 @@ export { resolveMessages, translate, DEFAULT_MESSAGES, PT_BR_MESSAGES, BUILTIN_M
 export type { I18nConfig, AuthMessages } from './src/host/i18n.js';
 export type { AuthHostRenderer, AuthSocialConfig } from './src/define_config.js';
 export { registerAuthHost } from './src/host/register_auth_host.js';
-export type { AuthHostOptions } from './src/host/register_auth_host.js';
+export type { AuthHostOptions, AuthHostRouteMap, AccountScreensOptions, } from './src/host/register_auth_host.js';
+export type { PolicyRouteOption } from './src/host/config_locks.js';
+export { POLICY_ROUTE_OPTIONS } from './src/host/config_locks.js';
 export { getAdminPrefix, setAdminPrefix, normalizeAdminPrefix, getAdminApiPrefix, setAdminApiPrefix, normalizeAdminApiPrefix, } from './src/host/admin_prefix.js';
 /**
  * Helpers de path do console de conta (`/account/*`). Um host que precisa casar
@@ -125,7 +127,7 @@ export { SETTING_KEYS, resolveEffectiveRegistration, resolveEffectiveRequireVeri
 export type { SettingKey, RegistrationSetting, RequireVerifiedEmailSetting, MaintenanceModeSetting, ResolvedMaintenanceMode, AuthMethodsSetting, ResolvedAuthMethods, AuthMethodsCapabilities, AuthMethodsConfigOverride, } from './src/host/runtime_toggles.js';
 export { resolveRegistration } from './src/define_config.js';
 export type { RegistrationConfigInput, ResolvedRegistrationConfig, } from './src/define_config.js';
-export { getAccountId, hasAccountSession, consoleLoginUrl, } from './src/host/console_session.js';
+export { getAccountId, realAccountId, hasAccountSession, consoleLoginUrl, } from './src/host/console_session.js';
 export { ACCOUNT_SESSION_KEY } from './src/host/middleware/account_auth.js';
 export { rememberAccessToken, startImpersonation, impersonationState, stopImpersonation, } from './src/host/impersonation_session.js';
 export type { StartImpersonationParams, ImpersonationState, } from './src/host/impersonation_session.js';

package/build/index.js

@@ -33,6 +33,7 @@ export { edgeRenderer } from './src/host/renderers/edge_renderer.js';
 export { brandFor, isFirstParty } from './src/host/branding.js';
 export { resolveMessages, translate, DEFAULT_MESSAGES, PT_BR_MESSAGES, BUILTIN_MESSAGES, DEFAULT_LOCALE, } from './src/host/i18n.js';
 export { registerAuthHost } from './src/host/register_auth_host.js';
+export { POLICY_ROUTE_OPTIONS } from './src/host/config_locks.js';
 export { getAdminPrefix, setAdminPrefix, normalizeAdminPrefix, getAdminApiPrefix, setAdminApiPrefix, normalizeAdminApiPrefix, } from './src/host/admin_prefix.js';
 /**
  * Helpers de path do console de conta (`/account/*`). Um host que precisa casar
@@ -85,7 +86,7 @@ export { resolveEffectiveBotProtection } from './src/host/bot_protection.js';
 // Runtime toggles (registration, require_verified_email, maintenance_mode).
 export { SETTING_KEYS, resolveEffectiveRegistration, resolveEffectiveRequireVerifiedEmail, resolveEffectiveMaintenanceMode, resolveEffectiveAuthMethods, configLockedAuthMethods, } from './src/host/runtime_toggles.js';
 export { resolveRegistration } from './src/define_config.js';
-export { getAccountId, hasAccountSession, consoleLoginUrl, } from './src/host/console_session.js';
+export { getAccountId, realAccountId, hasAccountSession, consoleLoginUrl, } from './src/host/console_session.js';
 export { ACCOUNT_SESSION_KEY } from './src/host/middleware/account_auth.js';
 // Session impersonation — RP-side glue that routes through the IdP's RFC 8693
 // token-exchange (the IdP validates the admin role + audits). See

package/build/providers/authkit_server_provider.js

@@ -37,11 +37,13 @@ export default class AuthkitServerProvider {
         // Config locks: trava as settings definidas explicitamente no defineConfig
         // (config vence em runtime; a UI/Admin API não pode alterá-las). Fail-safe:
         // qualquer erro → sem locks (comportamento legado).
+        let resolvedConfig = null;
         try {
             const value = this.app.config.get('authkit');
             if (value) {
                 const config = (await configProvider.resolve(this.app, value));
                 if (config) {
+                    resolvedConfig = config;
                     if (config.lockedSettingKeys?.length) {
                         const { setLockedSettingKeys } = await import('../src/host/config_locks.js');
                         setLockedSettingKeys(config.lockedSettingKeys);
@@ -55,6 +57,13 @@ export default class AuthkitServerProvider {
                         rateLimit: config.rateLimit,
                         adminEnabled: config.admin.enabled,
                         adminApiEnabled: config.adminApi.enabled,
+                        // `config.sudo.methods` passa a decidir também o que é MONTADO — sem
+                        // isto o host teria de repetir a lista no `registerAuthHost`, e as
+                        // duas divergiriam (tela oferecendo endpoint que dá 404).
+                        sudoMethods: config.sudo?.methods,
+                        // Defaults estruturais de `config.routes` (o argumento ainda vence).
+                        routes: typeof config.routes === 'object' ? config.routes : undefined,
+                        lockedRouteOptions: config.lockedRouteOptions,
                     });
                 }
             }
@@ -62,6 +71,15 @@ export default class AuthkitServerProvider {
         catch {
             /* sem locks / sem stash → registerAuthHost cai em opts/defaults */
         }
+        // Auto-montagem das rotas (`config.routes`). FORA do try/catch fail-safe
+        // acima de propósito: "as rotas não subiram" não pode degradar em silêncio —
+        // seria um app inteiro em 404 sem nenhuma pista. Chama a MESMA função
+        // exportada que o `start/routes.ts` chamaria; não há segunda implementação.
+        if (resolvedConfig?.routes) {
+            const router = await this.app.container.make('router');
+            const { autoMountAuthHost } = await import('../src/host/register_auth_host.js');
+            autoMountAuthHost(router);
+        }
         // Registra o disco "authkit" no edge.js para que os templates sejam referenciados
         // como `authkit::login`, `authkit::account/tokens`, etc.
         // Resolve o diretório das views tanto em produção (provider compilado em

package/build/src/accounts/lucid_account_store.d.ts

@@ -4,6 +4,35 @@ import type { FetchLike, PwnedLogger } from '../password/pwned.js';
 import type { AccountStore } from './account_store.js';
 import { type AccountSecretEncrypter, type WebauthnCeremonies } from './lucid_store/shared.js';
 export type { AccountSecretEncrypter, WebauthnCeremonies };
+/**
+ * TTLs dos tokens de verificação de e-mail / troca de e-mail (plan 009).
+ *
+ * Segue o mesmo padrão input/resolved/`resolveX` usado em `define_config.ts`
+ * (ex.: `resolveOrganizations`) — mas vive AQUI, não lá: `defineConfig` não
+ * constrói o `accountStore` (o host já o entrega pronto, via
+ * `config.accountStore`, tipicamente construído por `lucidAccountStore`/
+ * `lucidStores` ANTES de chamar `defineConfig`), então não há caminho para um
+ * valor resolvido em `define_config.ts` alcançar `buildCore` sem alterar a
+ * assinatura dos métodos do `AccountStore` e todos os controllers que os
+ * chamam (como acontece com `invitationTtlHours`/`createOrgInvitation`, que
+ * recebe o TTL por parâmetro em cada chamada) — fora do escopo desta mudança.
+ * O ponto real de wiring é aqui, na construção do store.
+ */
+export interface EmailTokensConfigInput {
+    /** TTL do token de verificação de e-mail (cadastro). Default: 24h. */
+    verificationTtlHours?: number;
+    /**
+     * TTL do token de troca de e-mail (self-service). Default: 1h — mesma
+     * janela do reset de senha, porque reescreve o identificador de recovery
+     * da conta.
+     */
+    changeTtlHours?: number;
+}
+export interface ResolvedEmailTokensConfig {
+    verificationTtlHours: number;
+    changeTtlHours: number;
+}
+export declare function resolveEmailTokens(input?: EmailTokensConfigInput): ResolvedEmailTokensConfig;
 /**
  * Serviço de encryption do app (APP_KEY), carregado LAZY via import dinâmico.
  *
@@ -117,6 +146,12 @@ export interface LucidAccountStoreOptions {
         MemberModel: any;
         InvitationModel: any;
     };
+    /**
+     * TTLs dos tokens de verificação de e-mail / troca de e-mail. Ver
+     * {@link EmailTokensConfigInput}. Ausente → 24h / 1h (defaults de
+     * `resolveEmailTokens`).
+     */
+    emailTokens?: EmailTokensConfigInput;
 }
 /**
  * Implementação default do {@link AccountStore} sobre um model Lucid composto

package/build/src/accounts/lucid_account_store.js

@@ -8,6 +8,12 @@ import { buildProviderIdentity } from './lucid_store/provider_identity.js';
 import { hasTable, } from './lucid_store/shared.js';
 import { buildDeletion, buildEmailVerificationStatus, buildProfile, buildStatus, hasColumn, } from './lucid_store/status_profile.js';
 import { buildWebauthn } from './lucid_store/webauthn.js';
+export function resolveEmailTokens(input) {
+    return {
+        verificationTtlHours: input?.verificationTtlHours ?? 24,
+        changeTtlHours: input?.changeTtlHours ?? 1,
+    };
+}
 let encSvc;
 let encLoading;
 /** Resolve quando o `loadEncryption()` corrente terminar (sucesso OU falha). */
@@ -116,6 +122,7 @@ export function appKeyEncrypter() {
 export function lucidAccountStore(Model, options = {}) {
     const mfaIssuer = options.mfaIssuer ?? 'AuthKit';
     const recoveryCodeCount = options.recoveryCodeCount ?? 8;
+    const emailTokens = resolveEmailTokens(options.emailTokens);
     // Default seguro: encripta o TOTP com APP_KEY. `false` desliga (plaintext).
     const encrypter = options.encrypter === false ? undefined : (options.encrypter ?? appKeyEncrypter());
     const ProviderIdentityModel = options.providerIdentityModel;
@@ -145,6 +152,8 @@ export function lucidAccountStore(Model, options = {}) {
         recoveryCodeCount,
         passwords,
         audit: options.audit,
+        emailVerificationTtlHours: emailTokens.verificationTtlHours,
+        emailChangeTtlHours: emailTokens.changeTtlHours,
         // Encripta o segredo antes de persistir (no-op sem encrypter).
         sealSecret: (secret) => (encrypter ? encrypter.encrypt(secret) : secret),
         // Decripta o segredo armazenado; retorna null em falha/adulteração (no-op sem encrypter).

package/build/src/accounts/lucid_store/core.js

@@ -3,7 +3,21 @@ import { Scrypt } from '@adonisjs/core/hash/drivers/scrypt';
 import { DateTime } from 'luxon';
 import { OTP_LOGIN_PREFIX, decodeOtpToken, encodeOtpToken, evaluateLoginOtp, generateOtpCode, hashLoginOtp, linkTokenFromOtpUrl, } from '../../host/otp_login.js';
 import { hasColumn } from './status_profile.js';
-/** Prefixo do token de troca de e-mail (reaproveita a coluna emailVerificationToken). */
+import { generateExpiringHashedToken, generateHashedToken, parseExpiringTokenExp, rawToDbToken, rawToExpiringDbToken, sha256Hex, } from './token_hash.js';
+/**
+ * Prefixo do token de troca de e-mail (reaproveita a coluna emailVerificationToken).
+ *
+ * Formato ARMAZENADO (plan 009): `ec:<b64email>:<exp>:sha256(<random>)` — o
+ * e-mail continua em base64url (inalterado, plan 007 não mexeu nisso), mas
+ * agora carrega uma deadline (`exp`, epoch ms) e o `random` vai HASHEADO em
+ * repouso (antes ia em claro). Ver a análise de segurança do `exp` embutido
+ * em `token_hash.ts` (`rawToExpiringDbToken`/`parseExpiringTokenExp`).
+ *
+ * Limite prático: com um e-mail codificado em base64url, o valor cabe em
+ * VARCHAR(255) para e-mails de até ~129 bytes (`3 + b64(129) + 1 + 13 + 1 +
+ * 64 = 254`); acima disso o valor gravado excederia a coluna. Nenhum e-mail
+ * real chega perto disso — é uma folga generosa, não um limite apertado.
+ */
 const EMAIL_CHANGE_PREFIX = 'ec:';
 /** Prefixo do magic link (reaproveita as colunas de reset de senha). */
 const MAGIC_LINK_PREFIX = 'ml:';
@@ -125,8 +139,11 @@ export function buildCore(ctx) {
             const row = await Model.query().where('email', email).first();
             if (!row)
                 return null;
-            const token = randomBytes(32).toString('hex');
-            row.passwordResetToken = token;
+            // Token BRUTO devolvido ao chamador (vai pro e-mail); só o HASH (sha256 da
+            // parte aleatória) é persistido — um dump da tabela não rende um token
+            // usável (mesmo padrão de host/otp_lockout.ts).
+            const { raw: token, dbValue } = generateHashedToken();
+            row.passwordResetToken = dbValue;
             row.passwordResetExpiresAt = DateTime.now().plus({ hours: 1 });
             await row.save();
             return { token, account: toAccount(row) };
@@ -134,9 +151,10 @@ export function buildCore(ctx) {
         async consumePasswordResetToken(token, newPassword) {
             // Magic links (`ml:` e `ml2:` com OTP) NÃO são tokens de reset de senha —
             // só o fluxo de consumeMagicLinkToken pode consumi-los (não trocam senha).
+            // Checagem de prefixo acontece ANTES do hash, sobre o token BRUTO recebido.
             if (token.startsWith(MAGIC_LINK_PREFIX) || token.startsWith(OTP_LOGIN_PREFIX))
                 return false;
-            const row = await Model.query().where('passwordResetToken', token).first();
+            const row = await Model.query().where('passwordResetToken', rawToDbToken('', token)).first();
             if (!row)
                 return false;
             if (!row.passwordResetExpiresAt || row.passwordResetExpiresAt < DateTime.now())
@@ -161,8 +179,11 @@ export function buildCore(ctx) {
                 return null;
             // Token `ml:<random>` nas colunas de reset (sem migração); o prefixo o
             // distingue de um token de reset de senha. Curta duração (15 min).
-            const token = `${MAGIC_LINK_PREFIX}${randomBytes(32).toString('hex')}`;
-            row.passwordResetToken = token;
+            // O prefixo fica em CLARO no valor persistido — só a parte aleatória é
+            // hasheada — porque os guards de discriminação de fluxo leem esse prefixo
+            // direto do valor armazenado (ver consumePasswordResetToken/consumeMagicLinkToken).
+            const { raw: token, dbValue } = generateHashedToken(MAGIC_LINK_PREFIX);
+            row.passwordResetToken = dbValue;
             row.passwordResetExpiresAt = DateTime.now().plus({ minutes: 15 });
             await row.save();
             return { token, account: toAccount(row) };
@@ -178,8 +199,13 @@ export function buildCore(ctx) {
                 const linkToken = linkTokenFromOtpUrl(token);
                 if (!linkToken)
                     return null;
+                // O slot armazena o HASH do link-token (não o valor bruto da URL); o
+                // padrão do LIKE precisa ser construído sobre o hash. `sha256Hex` sempre
+                // devolve hex minúsculo — sem metacaractere de LIKE, então isso não
+                // reabre a guarda de LIKE-injection que `linkTokenFromOtpUrl` já fecha.
+                const linkTokenHash = sha256Hex(linkToken);
                 const row = await Model.query()
-                    .where('passwordResetToken', 'like', `${OTP_LOGIN_PREFIX}${linkToken}:%`)
+                    .where('passwordResetToken', 'like', `${OTP_LOGIN_PREFIX}${linkTokenHash}:%`)
                     .first();
                 if (!row)
                     return null;
@@ -192,7 +218,9 @@ export function buildCore(ctx) {
             }
             if (!token.startsWith(MAGIC_LINK_PREFIX))
                 return null;
-            const row = await Model.query().where('passwordResetToken', token).first();
+            const row = await Model.query()
+                .where('passwordResetToken', rawToDbToken(MAGIC_LINK_PREFIX, token))
+                .first();
             if (!row)
                 return null;
             if (!row.passwordResetExpiresAt || row.passwordResetExpiresAt < DateTime.now())
@@ -208,12 +236,20 @@ export function buildCore(ctx) {
             const row = await Model.query().where('email', email).first();
             if (!row)
                 return null;
+            // `linkToken` BRUTO vai só na URL; o slot armazena o HASH dele (NÃO o
+            // valor bruto) — `codeHash` já é sha256(uid:code) e NÃO é re-hasheado aqui.
             const linkToken = randomBytes(32).toString('hex');
+            const linkTokenHash = sha256Hex(linkToken);
             const code = generateOtpCode(opts.digits);
             const codeHash = hashLoginOtp(uid, code);
             const codeExpMs = DateTime.now().plus({ minutes: opts.ttlMinutes }).toMillis();
             // Slot `ml2:` — código + link juntos, contador em 0. Ver host/otp_login.ts.
-            row.passwordResetToken = encodeOtpToken({ linkToken, codeHash, codeExpMs, attempts: 0 });
+            row.passwordResetToken = encodeOtpToken({
+                linkToken: linkTokenHash,
+                codeHash,
+                codeExpMs,
+                attempts: 0,
+            });
             // O LINK herda a validade padrão do magic link (15 min); o CÓDIGO carrega o
             // próprio `codeExpMs` (mais curto) embutido no slot.
             row.passwordResetExpiresAt = DateTime.now().plus({ minutes: 15 });
@@ -285,8 +321,15 @@ export function buildCore(ctx) {
             const row = await Model.query().where('email', email).first();
             if (!row)
                 return null;
-            const token = randomBytes(32).toString('hex');
-            row.emailVerificationToken = token;
+            // Token `<exp>:<random>` (sem prefixo — mesma coluna de sempre); só o
+            // HASH da parte aleatória é persistido, e o `exp` (deadline, epoch ms)
+            // vai em CLARO dentro do valor gravado. Ver a análise de segurança em
+            // `token_hash.ts` (generateExpiringHashedToken): o `exp` só é confiável
+            // DEPOIS que a igualdade de hash bater — é essa igualdade que prova que
+            // ele não foi adulterado pelo cliente.
+            const expiresAt = DateTime.now().plus({ hours: ctx.emailVerificationTtlHours ?? 24 });
+            const { raw: token, dbValue } = generateExpiringHashedToken('', expiresAt);
+            row.emailVerificationToken = dbValue;
             await row.save();
             return { token, account: toAccount(row) };
         },
@@ -297,9 +340,20 @@ export function buildCore(ctx) {
             // fluxo de confirmEmailChange pode consumi-los.
             if (token.startsWith(EMAIL_CHANGE_PREFIX))
                 return false;
-            const row = await Model.query().where('emailVerificationToken', token).first();
+            const dbValue = rawToExpiringDbToken('', token);
+            const row = await Model.query().where('emailVerificationToken', dbValue).first();
             if (!row)
                 return false;
+            // O `exp` só é lido AGORA, depois que a busca por `dbValue` já achou uma
+            // linha — esse match prova que este `exp` é o mesmo gravado no issue,
+            // não um valor que o cliente escreveu na hora. `null` (ausente/não-
+            // parseável — inclusive tokens gravados por uma versão anterior desta
+            // lib, sem `exp` nenhum) conta como EXPIRADO (fail-closed), mirando o
+            // mesmo formato de `!row.passwordResetExpiresAt || ... < DateTime.now()`
+            // usado no reset de senha.
+            const exp = parseExpiringTokenExp('', token);
+            if (exp === null || exp < DateTime.now().toMillis())
+                return false;
             row.emailVerifiedAt = DateTime.now();
             row.emailVerificationToken = null;
             await row.save();
@@ -361,13 +415,19 @@ export function buildCore(ctx) {
             const taken = await Model.query().where('email', newEmail).first();
             if (taken && taken.id !== row.id)
                 return null;
-            // Token = `ec:<base64url(newEmail)>:<random>`. Reaproveita a coluna
+            // Token = `ec:<base64url(newEmail)>:<exp>:<random>`. Reaproveita a coluna
             // emailVerificationToken (sem migração nova); o prefixo `ec:` distingue do
             // token de verificação de cadastro. O e-mail viaja codificado no próprio
-            // token, então não precisamos de coluna extra para o "pending email".
+            // token (sem coluna extra para o "pending email"); o `exp` (deadline,
+            // epoch ms) também viaja em CLARO no token — ver a análise de segurança
+            // em `token_hash.ts` (generateExpiringHashedToken/rawToExpiringDbToken):
+            // só a parte `random` é hasheada, e é a igualdade sobre a string INTEIRA
+            // (prefixo + e-mail + exp + hash) que impede o cliente de adulterar o
+            // `exp` sem invalidar o próprio token.
             const encodedEmail = Buffer.from(newEmail, 'utf8').toString('base64url');
-            const token = `${EMAIL_CHANGE_PREFIX}${encodedEmail}:${randomBytes(24).toString('hex')}`;
-            row.emailVerificationToken = token;
+            const expiresAt = DateTime.now().plus({ hours: ctx.emailChangeTtlHours ?? 1 });
+            const { raw: token, dbValue } = generateExpiringHashedToken(`${EMAIL_CHANGE_PREFIX}${encodedEmail}:`, expiresAt);
+            row.emailVerificationToken = dbValue;
             await row.save();
             return { token, account: toAccount(row), newEmail };
         },
@@ -375,8 +435,9 @@ export function buildCore(ctx) {
             if (!token || !token.startsWith(EMAIL_CHANGE_PREFIX))
                 return { ok: false };
             const parts = token.split(':');
-            // Forma esperada: ['ec', '<b64email>', '<random>']
-            if (parts.length !== 3)
+            // Forma esperada (plan 009): ['ec', '<b64email>', '<exp>', '<random>'] —
+            // 4 partes (era 3 antes de embutir o `exp`).
+            if (parts.length !== 4)
                 return { ok: false };
             let newEmail;
             try {
@@ -387,9 +448,17 @@ export function buildCore(ctx) {
             }
             if (!newEmail)
                 return { ok: false };
-            const row = await Model.query().where('emailVerificationToken', token).first();
+            const prefix = `${EMAIL_CHANGE_PREFIX}${parts[1]}:`;
+            const dbValue = rawToExpiringDbToken(prefix, token);
+            const row = await Model.query().where('emailVerificationToken', dbValue).first();
             if (!row)
                 return { ok: false };
+            // O `exp` só é lido DEPOIS do match acima (mesmo raciocínio de
+            // consumeEmailVerificationToken) — `null` (ausente/não-parseável) conta
+            // como EXPIRADO, fail-closed.
+            const exp = parseExpiringTokenExp(prefix, token);
+            if (exp === null || exp < DateTime.now().toMillis())
+                return { ok: false };
             // Defesa contra corrida: o e-mail pode ter sido tomado entre o pedido e a
             // confirmação por outra conta.
             const taken = await Model.query().where('email', newEmail).first();

package/build/src/accounts/lucid_store/shared.d.ts

@@ -58,6 +58,20 @@ export interface LucidStoreContext {
      * pela verificação de histórico de senhas.
      */
     nativeVerifyHash?: (hash: string, plain: string) => Promise<boolean>;
+    /**
+     * TTL (em horas) do token de verificação de e-mail (cadastro). Default: 24h
+     * (aplicado em `buildCore` quando ausente). Ver `resolveEmailTokens` em
+     * `lucid_account_store.ts` — não vem de `define_config.ts` porque o
+     * `defineConfig` não constrói o `accountStore` (o host já o entrega pronto
+     * via `config.accountStore`); o valor precisa chegar aqui na construção.
+     */
+    emailVerificationTtlHours?: number;
+    /**
+     * TTL (em horas) do token de troca de e-mail (self-service). Default: 1h —
+     * mesma janela do reset de senha, porque reescreve o identificador de
+     * recovery da conta. Ver nota de `emailVerificationTtlHours`.
+     */
+    emailChangeTtlHours?: number;
 }
 export declare const sha256: (value: string) => string;
 /** Recovery code legível: 10 chars hex em duas metades (ex.: a1b2c-3d4e5). */

package/build/src/accounts/lucid_store/token_hash.d.ts

@@ -0,0 +1,79 @@
+import type { DateTime } from 'luxon';
+/**
+ * Hashing dos tokens armazenados nas colunas `passwordResetToken` /
+ * `emailVerificationToken` (reset de senha, magic link, magic link com OTP).
+ *
+ * Mesmo padrão de `host/otp_lockout.ts` (`generateOtpUnlockToken` /
+ * `rawToDbOtpUnlockToken`): hasheia SÓ a parte aleatória do token — o prefixo
+ * (`ml:`, `ml2:`, etc., ou nenhum, no caso do reset) fica em texto claro no
+ * valor gravado, porque os guards de discriminação de fluxo (ex.:
+ * `consumePasswordResetToken` recusando `ml:`/`ml2:`; `consumeMagicLinkToken`
+ * recusando o que não é `ml:`) leem esse prefixo direto do valor armazenado —
+ * hashear a string inteira (prefixo incluso) tornaria essa leitura impossível.
+ *
+ * Motivo de existir como módulo próprio (em vez de reusar `otp_lockout.ts`):
+ * aquele arquivo já está correto e é o EXEMPLAR, não o alvo — mantê-lo intocado
+ * evita qualquer risco de regressão nele por este changeset.
+ */
+/** sha256 hex de uma string. */
+export declare function sha256Hex(value: string): string;
+/**
+ * Gera um token `prefix + <64 hex aleatórios>` e devolve tanto o valor BRUTO
+ * (vai para o e-mail/URL) quanto o valor a persistir no DB
+ * (`prefix + sha256(<parte aleatória>)`).
+ *
+ * `prefix` pode ser vazio (caso do reset de senha, que não tem prefixo).
+ */
+export declare function generateHashedToken(prefix?: string): {
+    raw: string;
+    dbValue: string;
+};
+/**
+ * Converte um token BRUTO recebido (com o `prefix` esperado) no valor de DB
+ * correspondente (`prefix + sha256(<parte aleatória>)`), para lookup por
+ * igualdade. Não valida o prefixo — o chamador já deve ter confirmado
+ * `raw.startsWith(prefix)` antes de chegar aqui (guards de discriminação).
+ */
+export declare function rawToDbToken(prefix: string, raw: string): string;
+/**
+ * Gera um token expirável `<prefix><exp>:<random>` e devolve tanto o BRUTO
+ * (vai pro e-mail/URL) quanto o valor de DB (`<prefix><exp>:sha256(<random>)`).
+ *
+ * `prefix` pode incluir estrutura própria (ex.: `ec:<b64email>:` na troca de
+ * e-mail) — é só um prefixo literal, igual em `generateHashedToken`. `expiresAt`
+ * é a deadline; é serializada como epoch ms (`toMillis()`) dentro do próprio
+ * token — ver o comentário do bloco acima para a análise de segurança.
+ */
+export declare function generateExpiringHashedToken(prefix: string, expiresAt: DateTime): {
+    raw: string;
+    dbValue: string;
+};
+/**
+ * Reconstrói o valor de DB (`<prefix><exp>:sha256(<random>)`) a partir de um
+ * token BRUTO recebido, para lookup por igualdade — mesmo padrão de
+ * `rawToDbToken`, mas preservando o segmento `<exp>` em claro (ele faz parte
+ * da string comparada; não é hasheado). Usa o `exp` EXATAMENTE como veio no
+ * token recebido (mesmo que adulterado/ilegível) — é a comparação por
+ * igualdade no banco que decide se ele é válido, não este helper.
+ *
+ * Se o token não tiver o separador esperado, devolve um valor que não pode
+ * bater com nada gerado por `generateExpiringHashedToken` (fail-closed: a
+ * query simplesmente não encontra linha).
+ */
+export declare function rawToExpiringDbToken(prefix: string, raw: string): string;
+/**
+ * Extrai o `exp` (epoch ms) de um token BRUTO recebido, sem consultar o banco.
+ *
+ * ⚠️ O valor devolvido só deve ser CONSULTADO pelo chamador depois que a busca
+ * por `rawToExpiringDbToken` já tiver encontrado uma linha — é esse match que
+ * prova que este `exp` é o mesmo que foi gravado no `issue*`, não um valor que
+ * o cliente inventou. Ler o `exp` antes do match (ou usá-lo quando a busca não
+ * achou linha nenhuma) não prova nada.
+ *
+ * Devolve `null` quando o segmento `exp` está ausente (sem separador) OU não é
+ * uma sequência de dígitos — o chamador DEVE tratar `null` como EXPIRADO
+ * (fail-closed), nunca como "sem prazo". Isso cobre tanto tokens adulterados
+ * quanto tokens gravados por uma versão anterior desta lib (sem `exp`
+ * nenhum).
+ */
+export declare function parseExpiringTokenExp(prefix: string, raw: string): number | null;

package/build/src/accounts/lucid_store/token_hash.js

@@ -0,0 +1,145 @@
+import { createHash, randomBytes } from 'node:crypto';
+/**
+ * Hashing dos tokens armazenados nas colunas `passwordResetToken` /
+ * `emailVerificationToken` (reset de senha, magic link, magic link com OTP).
+ *
+ * Mesmo padrão de `host/otp_lockout.ts` (`generateOtpUnlockToken` /
+ * `rawToDbOtpUnlockToken`): hasheia SÓ a parte aleatória do token — o prefixo
+ * (`ml:`, `ml2:`, etc., ou nenhum, no caso do reset) fica em texto claro no
+ * valor gravado, porque os guards de discriminação de fluxo (ex.:
+ * `consumePasswordResetToken` recusando `ml:`/`ml2:`; `consumeMagicLinkToken`
+ * recusando o que não é `ml:`) leem esse prefixo direto do valor armazenado —
+ * hashear a string inteira (prefixo incluso) tornaria essa leitura impossível.
+ *
+ * Motivo de existir como módulo próprio (em vez de reusar `otp_lockout.ts`):
+ * aquele arquivo já está correto e é o EXEMPLAR, não o alvo — mantê-lo intocado
+ * evita qualquer risco de regressão nele por este changeset.
+ */
+/** sha256 hex de uma string. */
+export function sha256Hex(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+/**
+ * Gera um token `prefix + <64 hex aleatórios>` e devolve tanto o valor BRUTO
+ * (vai para o e-mail/URL) quanto o valor a persistir no DB
+ * (`prefix + sha256(<parte aleatória>)`).
+ *
+ * `prefix` pode ser vazio (caso do reset de senha, que não tem prefixo).
+ */
+export function generateHashedToken(prefix = '') {
+    const random = randomBytes(32).toString('hex');
+    return { raw: `${prefix}${random}`, dbValue: `${prefix}${sha256Hex(random)}` };
+}
+/**
+ * Converte um token BRUTO recebido (com o `prefix` esperado) no valor de DB
+ * correspondente (`prefix + sha256(<parte aleatória>)`), para lookup por
+ * igualdade. Não valida o prefixo — o chamador já deve ter confirmado
+ * `raw.startsWith(prefix)` antes de chegar aqui (guards de discriminação).
+ */
+export function rawToDbToken(prefix, raw) {
+    const random = raw.startsWith(prefix) ? raw.slice(prefix.length) : raw;
+    return `${prefix}${sha256Hex(random)}`;
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Variante EXPIRÁVEL (plan 009): `emailVerificationToken` (verificação de
+// cadastro, sem prefixo) e `ec:` (troca de e-mail) embutem uma deadline
+// (`exp`, epoch ms) dentro do PRÓPRIO token — não numa coluna separada.
+//
+// Por quê: esta lib não é dona da tabela `users` (ver header de
+// `src/schema/ensure.ts`), então não pode adicionar uma coluna
+// `emailVerificationExpiresAt` como o reset de senha tem. A alternativa óbvia
+// — embutir o `exp` no valor que o cliente devolve — parecia insegura antes de
+// 007: um valor sob controle do cliente poderia ter o `exp` adulterado.
+//
+// 007 fechou essa brecha ao fazer o LOOKUP reconstruir o valor de DB a partir
+// do token bruto recebido e buscar por IGUALDADE (em vez de ler a linha
+// primeiro e comparar depois). Isso vale integralmente aqui: o `exp` fica em
+// CLARO dentro do valor gravado (`prefix<exp>:sha256(<random>)`), mas ele faz
+// parte da STRING inteira que é comparada por igualdade na query. Se o
+// cliente reescrever o `exp` no token que devolve, a reconstrução
+// (`prefix<expAdulterado>:sha256(<random>)`) produz uma string DIFERENTE da
+// que está gravada — a query não encontra NENHUMA linha, e o token é
+// simplesmente rejeitado.
+//
+// Ou seja: o MATCH em si (achar a linha) já prova que o `exp` que acabou de
+// ser lido é exatamente o mesmo que foi gerado no `issue*` — nenhuma
+// assinatura/HMAC separada é necessária. É só DEPOIS desse match que o `exp`
+// pode ser avaliado contra o relógio com confiança. NÃO SIMPLIFIQUE isso lendo
+// o `exp` do token ANTES do match, nem tratando um `exp` ausente/inválido como
+// "sem prazo" — as duas coisas reabririam a adulteração que este desenho
+// fecha (ver testes de mutação no plano 009).
+//
+// Este raciocínio SÓ é válido enquanto o token continuar hasheado em repouso
+// (a parte `random` do valor). Se algum dia alguém reverter o hashing, o `exp`
+// embutido volta a ficar sob controle total do cliente.
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Gera um token expirável `<prefix><exp>:<random>` e devolve tanto o BRUTO
+ * (vai pro e-mail/URL) quanto o valor de DB (`<prefix><exp>:sha256(<random>)`).
+ *
+ * `prefix` pode incluir estrutura própria (ex.: `ec:<b64email>:` na troca de
+ * e-mail) — é só um prefixo literal, igual em `generateHashedToken`. `expiresAt`
+ * é a deadline; é serializada como epoch ms (`toMillis()`) dentro do próprio
+ * token — ver o comentário do bloco acima para a análise de segurança.
+ */
+export function generateExpiringHashedToken(prefix, expiresAt) {
+    const exp = expiresAt.toMillis();
+    const random = randomBytes(24).toString('hex');
+    return {
+        raw: `${prefix}${exp}:${random}`,
+        dbValue: `${prefix}${exp}:${sha256Hex(random)}`,
+    };
+}
+/**
+ * Separa `<exp>:<random>` de um token BRUTO `<prefix><exp>:<random>` (depois de
+ * remover o `prefix`). `null` se não há `:` após o prefixo (token mal formado —
+ * nem `exp` nem `random` são extraíveis).
+ */
+function splitExpiringRaw(prefix, raw) {
+    const rest = raw.startsWith(prefix) ? raw.slice(prefix.length) : raw;
+    const sepIdx = rest.indexOf(':');
+    if (sepIdx === -1)
+        return null;
+    return { expPart: rest.slice(0, sepIdx), random: rest.slice(sepIdx + 1) };
+}
+/**
+ * Reconstrói o valor de DB (`<prefix><exp>:sha256(<random>)`) a partir de um
+ * token BRUTO recebido, para lookup por igualdade — mesmo padrão de
+ * `rawToDbToken`, mas preservando o segmento `<exp>` em claro (ele faz parte
+ * da string comparada; não é hasheado). Usa o `exp` EXATAMENTE como veio no
+ * token recebido (mesmo que adulterado/ilegível) — é a comparação por
+ * igualdade no banco que decide se ele é válido, não este helper.
+ *
+ * Se o token não tiver o separador esperado, devolve um valor que não pode
+ * bater com nada gerado por `generateExpiringHashedToken` (fail-closed: a
+ * query simplesmente não encontra linha).
+ */
+export function rawToExpiringDbToken(prefix, raw) {
+    const parts = splitExpiringRaw(prefix, raw);
+    if (!parts) {
+        const rest = raw.startsWith(prefix) ? raw.slice(prefix.length) : raw;
+        return `${prefix}${sha256Hex(rest)}`;
+    }
+    return `${prefix}${parts.expPart}:${sha256Hex(parts.random)}`;
+}
+/**
+ * Extrai o `exp` (epoch ms) de um token BRUTO recebido, sem consultar o banco.
+ *
+ * ⚠️ O valor devolvido só deve ser CONSULTADO pelo chamador depois que a busca
+ * por `rawToExpiringDbToken` já tiver encontrado uma linha — é esse match que
+ * prova que este `exp` é o mesmo que foi gravado no `issue*`, não um valor que
+ * o cliente inventou. Ler o `exp` antes do match (ou usá-lo quando a busca não
+ * achou linha nenhuma) não prova nada.
+ *
+ * Devolve `null` quando o segmento `exp` está ausente (sem separador) OU não é
+ * uma sequência de dígitos — o chamador DEVE tratar `null` como EXPIRADO
+ * (fail-closed), nunca como "sem prazo". Isso cobre tanto tokens adulterados
+ * quanto tokens gravados por uma versão anterior desta lib (sem `exp`
+ * nenhum).
+ */
+export function parseExpiringTokenExp(prefix, raw) {
+    const parts = splitExpiringRaw(prefix, raw);
+    if (!parts)
+        return null;
+    return /^\d+$/.test(parts.expPart) ? Number(parts.expPart) : null;
+}