@adonis-agora/authkit-server 0.34.0

package/build/src/password/password_manager.d.ts

@@ -0,0 +1,163 @@
+import { type PasswordPolicyViolation, type ResolvedPasswordConfig } from './policy.js';
+import { type PwnedLogger, type FetchLike } from './pwned.js';
+/**
+ * Verificador de hashes legados (de OUTROS sistemas). Chamado quando a
+ * verificação nativa do hasher do Adonis falha OU não reconhece o formato do
+ * hash (ex.: bcrypt PHP `$2y$`, Django `pbkdf2_sha256$`, MD5, etc.).
+ *
+ * Retorno:
+ *  - `true`  → a senha confere (o store então re-hasheia com o hasher atual);
+ *  - `false` → a senha NÃO confere;
+ *  - `null`  → este verifier não trata esse formato (deixa o login falhar).
+ *
+ * @example
+ * // bcrypt vindo do PHP usa o prefixo `$2y$`; o hasher bcrypt do Node entende
+ * // `$2b$`. A conversão é só trocar o prefixo (mesmo algoritmo):
+ * const legacyVerifier = async (hashed, plain) => {
+ *   if (!hashed.startsWith('$2y$')) return null // não é meu formato
+ *   const normalized = '$2b$' + hashed.slice(4)
+ *   return bcrypt.compare(plain, normalized) // true | false
+ * }
+ */
+export type LegacyPasswordVerifier = (hashedPassword: string, plainPassword: string) => Promise<boolean | null>;
+/**
+ * Config de senha aceita pelo store (entrada do host).
+ *
+ * Política de complexidade e checagem de vazamento são gerenciadas em runtime
+ * via setting `password_policy` no admin console ou Admin API.
+ * Aqui ficam apenas os parâmetros de infra/código.
+ */
+export interface PasswordConfigInput {
+    /**
+     * Verificador de hashes legados de outros sistemas. Acionado quando a
+     * verificação nativa falha. Veja {@link LegacyPasswordVerifier}.
+     */
+    legacyVerifier?: LegacyPasswordVerifier;
+    /**
+     * Pepper de infra (segredo de boot). HMAC-SHA256 da senha ANTES do hasher
+     * seguindo OWASP (defense-in-depth: DB comprometido sem o pepper = hashes
+     * inúteis).
+     *
+     * - `string`  → pepper corrente.
+     * - `string[]` → rotação: o PRIMEIRO é o corrente (hash); TODOS são tentados
+     *   no verify. Se confere com um pepper antigo → lazy re-hash com o corrente.
+     * - Ausente → comportamento original (sem HMAC, back-compat total).
+     *
+     * IMPORTANTE: Contas existentes podem ter hash SEM pepper — o verify tenta
+     * com cada pepper E sem pepper (legacy); em sucesso re-hasheia com o corrente.
+     *
+     * @example
+     * // config/authkit.ts
+     * password: { pepper: env.get('PASSWORD_PEPPER') }
+     *
+     * @example
+     * // Rotação: novo pepper primeiro, antigos no array.
+     * password: { pepper: [env.get('PEPPER_V2'), env.get('PEPPER_V1')] }
+     */
+    pepper?: string | string[];
+    /**
+     * Timeout em ms para a checagem de vazamento HIBP (HaveIBeenPwned). Infra.
+     * Default: 2000 ms. A checagem é habilitada/desabilitada via runtime setting
+     * `password_policy.checkPwned` no admin console.
+     */
+    pwnedTimeoutMs?: number;
+}
+/** Erro de política/vazamento de senha — carrega a chave i18n + params. */
+export declare class PasswordPolicyError extends Error {
+    readonly key: PasswordPolicyViolation | 'password.pwned' | 'password.reused' | 'password.common';
+    readonly params?: Record<string, string | number> | undefined;
+    constructor(key: PasswordPolicyViolation | 'password.pwned' | 'password.reused' | 'password.common', params?: Record<string, string | number> | undefined);
+}
+/**
+ * Aplica o pepper à senha em claro via HMAC-SHA256, retornando um hex-digest
+ * que será entregue ao hasher como se fosse a senha. Sem pepper → retorna a
+ * senha inalterada (back-compat total).
+ */
+export declare function applyPepper(plain: string, pepper: string): string;
+/**
+ * Resolve o array de peppers a tentar no verify, incluindo o sentinel "sem
+ * pepper" (cadeia vazia) para back-compat com hashes antigos sem pepper.
+ *
+ * @returns [corrente, ...antigos, ''] — string vazia = tentar sem HMAC (legacy).
+ */
+export declare function resolvePeppers(pepper: string | string[] | undefined): string[];
+/**
+ * Aplica o pepper corrente à senha em claro. O pepper corrente é SEMPRE o
+ * primeiro do array (ou a string direta). Sem pepper → retorna a senha.
+ */
+export declare function applyCurrentPepper(plain: string, pepper: string | string[] | undefined): string;
+/**
+ * Resultado de uma verificação de senha pelo manager. `rehash` indica que a
+ * senha confere mas o hash armazenado deve ser re-gerado (formato legado OU
+ * parâmetros do hasher desatualizados) — o chamador (store) persiste o novo hash
+ * best-effort.
+ */
+export interface PasswordVerifyResult {
+    ok: boolean;
+    rehash: boolean;
+}
+/**
+ * Concentra a lógica de senha do store: validação de política + vazamento (ao
+ * DEFINIR uma senha) e verificação com lazy rehash + legacy verifier (ao
+ * AUTENTICAR). A política usa lib defaults — a runtime setting `password_policy`
+ * é a única fonte de customização (via `assertAcceptable` com override).
+ */
+export declare class PasswordManager {
+    readonly config: ResolvedPasswordConfig;
+    private readonly legacyVerifier?;
+    private readonly logger?;
+    private readonly fetchImpl?;
+    /** Pepper configurado (secret de boot). Pode ser string ou array para rotação. */
+    readonly pepper: string | string[] | undefined;
+    /** Timeout em ms para a checagem de vazamento HIBP. */
+    readonly pwnedTimeoutMs: number;
+    constructor(input?: PasswordConfigInput, deps?: {
+        logger?: PwnedLogger;
+        fetchImpl?: FetchLike;
+    });
+    /** Há um verificador de hash legado configurado? */
+    hasLegacyVerifier(): boolean;
+    /**
+     * Aplica o pepper corrente à senha em claro antes do hash. Sem pepper →
+     * retorna a senha inalterada (back-compat total).
+     */
+    applyCurrentPepper(plain: string): string;
+    /**
+     * Valida uma senha NOVA: política primeiro (barata, local), depois vazamento
+     * (rede, opcional, fail-safe). Lança {@link PasswordPolicyError} na 1ª falha.
+     *
+     * @param policyOverride - Política resolvida em runtime (via setting `password_policy`).
+     *   Quando fornecida, sobrescreve os defaults da lib para esta chamada.
+     */
+    assertAcceptable(plainPassword: string, policyOverride?: {
+        minLength?: number;
+        requireUppercase?: boolean;
+        requireLowercase?: boolean;
+        requireNumbers?: boolean;
+        requireSymbols?: boolean;
+        checkPwned?: boolean;
+        blockCommon?: boolean;
+    }): Promise<void>;
+    /**
+     * Verifica `plainPassword` contra o `hashedPassword` armazenado, com suporte
+     * a pepper.
+     *
+     * Sequência:
+     *  1. Para cada pepper possível (corrente + antigos + sem pepper para legacy):
+     *     a. `nativeVerify(hashed, peppered(plain))`. Se OK → checa `needsRehash`
+     *        e devolve `{ ok: true, rehash }`. rehash=true quando pepper não é o
+     *        corrente (re-hash com o corrente transparente).
+     *  2. Se nenhum pepper funcionou com native, tenta o `legacyVerifier` com
+     *     `applyCurrentPepper(plain)` (e também sem pepper, para import de sistemas
+     *     legados antes de pepperar).
+     *     `true` → `{ ok: true, rehash: true }`;
+     *     `false`/`null` → `{ ok: false, rehash: false }`.
+     *
+     * `nativeVerify`/`needsRehash` são injetados pelo store (vêm do model Lucid),
+     * mantendo este manager desacoplado do Lucid.
+     */
+    verify(hashedPassword: string, plainPassword: string, hooks: {
+        nativeVerify: (hashed: string, plain: string) => Promise<boolean>;
+        needsRehash: (hashed: string) => boolean;
+    }): Promise<PasswordVerifyResult>;
+}

package/build/src/password/password_manager.js

@@ -0,0 +1,191 @@
+import { createHmac } from 'node:crypto';
+import { checkPasswordPolicy, policyViolationParams, resolvePasswordConfig, DEFAULT_PWNED_TIMEOUT_MS, } from './policy.js';
+import { isPasswordPwned } from './pwned.js';
+import { isCommonPassword } from './common_passwords.js';
+/** Erro de política/vazamento de senha — carrega a chave i18n + params. */
+export class PasswordPolicyError extends Error {
+    key;
+    params;
+    constructor(key, params) {
+        super(key);
+        this.key = key;
+        this.params = params;
+        this.name = 'PasswordPolicyError';
+    }
+}
+// ---------------------------------------------------------------------------
+// Pepper helpers (OWASP pattern: HMAC-SHA256 before hashing)
+// ---------------------------------------------------------------------------
+/**
+ * Aplica o pepper à senha em claro via HMAC-SHA256, retornando um hex-digest
+ * que será entregue ao hasher como se fosse a senha. Sem pepper → retorna a
+ * senha inalterada (back-compat total).
+ */
+export function applyPepper(plain, pepper) {
+    return createHmac('sha256', pepper).update(plain).digest('hex');
+}
+/**
+ * Resolve o array de peppers a tentar no verify, incluindo o sentinel "sem
+ * pepper" (cadeia vazia) para back-compat com hashes antigos sem pepper.
+ *
+ * @returns [corrente, ...antigos, ''] — string vazia = tentar sem HMAC (legacy).
+ */
+export function resolvePeppers(pepper) {
+    if (!pepper)
+        return [''];
+    const arr = Array.isArray(pepper) ? pepper : [pepper];
+    // Inclui string vazia no final para tentar sem pepper (legacy back-compat).
+    return [...arr, ''];
+}
+/**
+ * Aplica o pepper corrente à senha em claro. O pepper corrente é SEMPRE o
+ * primeiro do array (ou a string direta). Sem pepper → retorna a senha.
+ */
+export function applyCurrentPepper(plain, pepper) {
+    if (!pepper)
+        return plain;
+    const current = Array.isArray(pepper) ? pepper[0] : pepper;
+    if (!current)
+        return plain;
+    return applyPepper(plain, current);
+}
+/**
+ * Concentra a lógica de senha do store: validação de política + vazamento (ao
+ * DEFINIR uma senha) e verificação com lazy rehash + legacy verifier (ao
+ * AUTENTICAR). A política usa lib defaults — a runtime setting `password_policy`
+ * é a única fonte de customização (via `assertAcceptable` com override).
+ */
+export class PasswordManager {
+    config;
+    legacyVerifier;
+    logger;
+    fetchImpl;
+    /** Pepper configurado (secret de boot). Pode ser string ou array para rotação. */
+    pepper;
+    /** Timeout em ms para a checagem de vazamento HIBP. */
+    pwnedTimeoutMs;
+    constructor(input = {}, deps = {}) {
+        // Lib defaults: minLength=8, sem complexidade, sem checkPwned (setting-driven).
+        this.config = resolvePasswordConfig({});
+        this.legacyVerifier = input.legacyVerifier;
+        this.logger = deps.logger;
+        this.fetchImpl = deps.fetchImpl;
+        this.pepper = input.pepper;
+        this.pwnedTimeoutMs = input.pwnedTimeoutMs ?? DEFAULT_PWNED_TIMEOUT_MS;
+    }
+    /** Há um verificador de hash legado configurado? */
+    hasLegacyVerifier() {
+        return typeof this.legacyVerifier === 'function';
+    }
+    /**
+     * Aplica o pepper corrente à senha em claro antes do hash. Sem pepper →
+     * retorna a senha inalterada (back-compat total).
+     */
+    applyCurrentPepper(plain) {
+        return applyCurrentPepper(plain, this.pepper);
+    }
+    /**
+     * Valida uma senha NOVA: política primeiro (barata, local), depois vazamento
+     * (rede, opcional, fail-safe). Lança {@link PasswordPolicyError} na 1ª falha.
+     *
+     * @param policyOverride - Política resolvida em runtime (via setting `password_policy`).
+     *   Quando fornecida, sobrescreve os defaults da lib para esta chamada.
+     */
+    async assertAcceptable(plainPassword, policyOverride) {
+        const effectivePolicy = policyOverride
+            ? {
+                minLength: policyOverride.minLength ?? this.config.policy.minLength,
+                requireUppercase: policyOverride.requireUppercase ?? this.config.policy.requireUppercase,
+                requireLowercase: policyOverride.requireLowercase ?? this.config.policy.requireLowercase,
+                requireNumbers: policyOverride.requireNumbers ?? this.config.policy.requireNumbers,
+                requireSymbols: policyOverride.requireSymbols ?? this.config.policy.requireSymbols,
+            }
+            : this.config.policy;
+        const violation = checkPasswordPolicy(plainPassword, effectivePolicy);
+        if (violation) {
+            throw new PasswordPolicyError(violation, policyViolationParams(violation, effectivePolicy));
+        }
+        // Checagem offline de senhas comuns (case-insensitive, ANTES do HIBP).
+        // Default: blockCommon=true. Somente pula se explicitamente desligado.
+        const blockCommon = policyOverride?.blockCommon !== false;
+        if (blockCommon && isCommonPassword(plainPassword)) {
+            throw new PasswordPolicyError('password.common');
+        }
+        if (policyOverride?.checkPwned) {
+            const pwned = await isPasswordPwned(plainPassword, {
+                timeoutMs: this.pwnedTimeoutMs,
+                logger: this.logger,
+                fetchImpl: this.fetchImpl,
+            });
+            if (pwned)
+                throw new PasswordPolicyError('password.pwned');
+        }
+    }
+    /**
+     * Verifica `plainPassword` contra o `hashedPassword` armazenado, com suporte
+     * a pepper.
+     *
+     * Sequência:
+     *  1. Para cada pepper possível (corrente + antigos + sem pepper para legacy):
+     *     a. `nativeVerify(hashed, peppered(plain))`. Se OK → checa `needsRehash`
+     *        e devolve `{ ok: true, rehash }`. rehash=true quando pepper não é o
+     *        corrente (re-hash com o corrente transparente).
+     *  2. Se nenhum pepper funcionou com native, tenta o `legacyVerifier` com
+     *     `applyCurrentPepper(plain)` (e também sem pepper, para import de sistemas
+     *     legados antes de pepperar).
+     *     `true` → `{ ok: true, rehash: true }`;
+     *     `false`/`null` → `{ ok: false, rehash: false }`.
+     *
+     * `nativeVerify`/`needsRehash` são injetados pelo store (vêm do model Lucid),
+     * mantendo este manager desacoplado do Lucid.
+     */
+    async verify(hashedPassword, plainPassword, hooks) {
+        const peppers = resolvePeppers(this.pepper);
+        const currentPepper = Array.isArray(this.pepper) ? this.pepper[0] : (this.pepper ?? '');
+        for (let i = 0; i < peppers.length; i++) {
+            const p = peppers[i];
+            const peppered = p ? applyPepper(plainPassword, p) : plainPassword;
+            let nativeOk = false;
+            try {
+                nativeOk = await hooks.nativeVerify(hashedPassword, peppered);
+            }
+            catch {
+                nativeOk = false;
+            }
+            if (nativeOk) {
+                // Se este não é o pepper corrente → re-hash obrigatório com o corrente.
+                const isCurrentPepper = (p === currentPepper) || (!p && !this.pepper);
+                let rehash = isCurrentPepper ? false : true;
+                if (!rehash) {
+                    try {
+                        rehash = hooks.needsRehash(hashedPassword);
+                    }
+                    catch {
+                        rehash = false;
+                    }
+                }
+                return { ok: true, rehash };
+            }
+        }
+        // Nenhum pepper funcionou com nativeVerify → tenta legacyVerifier.
+        if (this.legacyVerifier) {
+            // Tenta com o pepper corrente E sem pepper (para hashes de sistemas legados
+            // que ainda não tinham pepper).
+            const tryCandidates = this.pepper
+                ? [applyCurrentPepper(plainPassword, this.pepper), plainPassword]
+                : [plainPassword];
+            for (const candidate of tryCandidates) {
+                let legacy = null;
+                try {
+                    legacy = await this.legacyVerifier(hashedPassword, candidate);
+                }
+                catch {
+                    legacy = null;
+                }
+                if (legacy === true)
+                    return { ok: true, rehash: true };
+            }
+        }
+        return { ok: false, rehash: false };
+    }
+}

package/build/src/password/policy.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Política de senha (shapes + checagens puras). Testável em isolamento.
+ * A política ativa é gerenciada via runtime setting `password_policy` em
+ * `auth_settings` (admin console / Admin API). Os defaults da lib ficam aqui.
+ */
+/**
+ * Regras de complexidade de senha (shape interno — alinhado com o shape
+ * da runtime setting `password_policy` em `auth_settings`).
+ */
+export interface PasswordPolicyInput {
+    /** Comprimento mínimo. Default: 8. */
+    minLength?: number;
+    /** Exige ao menos uma letra maiúscula. Default: false. */
+    requireUppercase?: boolean;
+    /** Exige ao menos uma letra minúscula. Default: false. */
+    requireLowercase?: boolean;
+    /** Exige ao menos um dígito. Default: false. */
+    requireNumbers?: boolean;
+    /** Exige ao menos um símbolo (não alfanumérico). Default: false. */
+    requireSymbols?: boolean;
+}
+/** Política resolvida (todos os campos presentes). */
+export interface ResolvedPasswordPolicy {
+    minLength: number;
+    requireUppercase: boolean;
+    requireLowercase: boolean;
+    requireNumbers: boolean;
+    requireSymbols: boolean;
+}
+/**
+ * Checagem contra vazamentos (HaveIBeenPwned Range API, k-anonymity). Quando
+ * `true`, usa os defaults; um objeto permite ajustar o timeout. FAIL-SAFE: erro
+ * de rede/timeout/5xx NÃO bloqueia a senha (loga warning e permite).
+ */
+export type CheckPwnedInput = boolean | {
+    timeoutMs?: number;
+};
+/** Config de senha resolvida, carregada pelo store/controllers. */
+export interface ResolvedPasswordConfig {
+    policy: ResolvedPasswordPolicy;
+    checkPwned: {
+        enabled: boolean;
+        timeoutMs: number;
+    };
+}
+export declare const DEFAULT_PWNED_TIMEOUT_MS = 2000;
+/**
+ * Chave i18n da regra de política violada (estável — os catálogos en/pt-BR
+ * carregam todas). `password.pwned` é a mensagem do vazamento.
+ */
+export type PasswordPolicyViolation = 'password.policy.min_length' | 'password.policy.uppercase' | 'password.policy.lowercase' | 'password.policy.numbers' | 'password.policy.symbols';
+export declare function resolvePasswordPolicy(input?: PasswordPolicyInput): ResolvedPasswordPolicy;
+export declare function resolveCheckPwned(input?: CheckPwnedInput): {
+    enabled: boolean;
+    timeoutMs: number;
+};
+export declare function resolvePasswordConfig(input?: {
+    policy?: PasswordPolicyInput;
+    checkPwned?: CheckPwnedInput;
+}): ResolvedPasswordConfig;
+/**
+ * Aplica a política a uma senha em claro. Devolve a PRIMEIRA violação (chave
+ * i18n) ou `null` se a senha passa. Ordem estável: comprimento → maiúscula →
+ * minúscula → dígito → símbolo.
+ */
+export declare function checkPasswordPolicy(password: string, policy: ResolvedPasswordPolicy): PasswordPolicyViolation | null;
+/**
+ * Parâmetros para interpolar a mensagem i18n da violação (ex.: `{min}` no
+ * comprimento mínimo). Devolve `undefined` para regras sem parâmetro.
+ */
+export declare function policyViolationParams(violation: PasswordPolicyViolation, policy: ResolvedPasswordPolicy): Record<string, string | number> | undefined;

package/build/src/password/policy.js

@@ -0,0 +1,55 @@
+/**
+ * Política de senha (shapes + checagens puras). Testável em isolamento.
+ * A política ativa é gerenciada via runtime setting `password_policy` em
+ * `auth_settings` (admin console / Admin API). Os defaults da lib ficam aqui.
+ */
+export const DEFAULT_PWNED_TIMEOUT_MS = 2000;
+export function resolvePasswordPolicy(input) {
+    return {
+        minLength: input?.minLength ?? 8,
+        requireUppercase: input?.requireUppercase ?? false,
+        requireLowercase: input?.requireLowercase ?? false,
+        requireNumbers: input?.requireNumbers ?? false,
+        requireSymbols: input?.requireSymbols ?? false,
+    };
+}
+export function resolveCheckPwned(input) {
+    if (!input)
+        return { enabled: false, timeoutMs: DEFAULT_PWNED_TIMEOUT_MS };
+    if (input === true)
+        return { enabled: true, timeoutMs: DEFAULT_PWNED_TIMEOUT_MS };
+    return { enabled: true, timeoutMs: input.timeoutMs ?? DEFAULT_PWNED_TIMEOUT_MS };
+}
+export function resolvePasswordConfig(input) {
+    return {
+        policy: resolvePasswordPolicy(input?.policy),
+        checkPwned: resolveCheckPwned(input?.checkPwned),
+    };
+}
+/**
+ * Aplica a política a uma senha em claro. Devolve a PRIMEIRA violação (chave
+ * i18n) ou `null` se a senha passa. Ordem estável: comprimento → maiúscula →
+ * minúscula → dígito → símbolo.
+ */
+export function checkPasswordPolicy(password, policy) {
+    if (password.length < policy.minLength)
+        return 'password.policy.min_length';
+    if (policy.requireUppercase && !/[A-Z]/.test(password))
+        return 'password.policy.uppercase';
+    if (policy.requireLowercase && !/[a-z]/.test(password))
+        return 'password.policy.lowercase';
+    if (policy.requireNumbers && !/[0-9]/.test(password))
+        return 'password.policy.numbers';
+    if (policy.requireSymbols && !/[^A-Za-z0-9]/.test(password))
+        return 'password.policy.symbols';
+    return null;
+}
+/**
+ * Parâmetros para interpolar a mensagem i18n da violação (ex.: `{min}` no
+ * comprimento mínimo). Devolve `undefined` para regras sem parâmetro.
+ */
+export function policyViolationParams(violation, policy) {
+    if (violation === 'password.policy.min_length')
+        return { min: policy.minLength };
+    return undefined;
+}

package/build/src/password/pwned.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Checagem de senha vazada via HaveIBeenPwned Pwned Passwords (Range API), com
+ * k-anonymity: NUNCA enviamos a senha nem o hash completo — só os 5 primeiros
+ * hex chars do SHA-1, e procuramos o sufixo localmente na resposta.
+ *
+ * FAIL-SAFE por design: qualquer erro (rede, timeout, 5xx, parsing) resulta em
+ * "não vazada" (permite a senha) e loga um warning. A indisponibilidade do
+ * serviço externo NUNCA deve bloquear o usuário de definir uma senha.
+ */
+/** Logger mínimo (subconjunto do logger do AdonisJS). */
+export interface PwnedLogger {
+    warn(obj: unknown, msg?: string): void;
+}
+/**
+ * Cliente HTTP injetável (fetch nativo por default). Existe para testes: permite
+ * simular hit/miss/erro/timeout SEM rede. A assinatura espelha o `fetch` global.
+ */
+export type FetchLike = (url: string, init?: {
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+/** Injeta um fetch fake para testes. `undefined` restaura o fetch nativo. */
+export declare function __setFetchForTests(impl: FetchLike | undefined): void;
+/**
+ * Retorna `true` se a senha aparece na base do HIBP, `false` caso contrário OU
+ * em qualquer falha (fail-safe). `timeoutMs` aborta a request.
+ */
+export declare function isPasswordPwned(password: string, options?: {
+    timeoutMs: number;
+    logger?: PwnedLogger;
+    fetchImpl?: FetchLike;
+}): Promise<boolean>;

package/build/src/password/pwned.js

@@ -0,0 +1,52 @@
+import { createHash } from 'node:crypto';
+let fetchImpl;
+/** Injeta um fetch fake para testes. `undefined` restaura o fetch nativo. */
+export function __setFetchForTests(impl) {
+    fetchImpl = impl;
+}
+function getFetch() {
+    if (fetchImpl)
+        return fetchImpl;
+    return globalThis.fetch;
+}
+const HIBP_RANGE_URL = 'https://api.pwnedpasswords.com/range/';
+/**
+ * Retorna `true` se a senha aparece na base do HIBP, `false` caso contrário OU
+ * em qualquer falha (fail-safe). `timeoutMs` aborta a request.
+ */
+export async function isPasswordPwned(password, options = {
+    timeoutMs: 2000,
+}) {
+    const sha1 = createHash('sha1').update(password, 'utf8').digest('hex').toUpperCase();
+    const prefix = sha1.slice(0, 5);
+    const suffix = sha1.slice(5);
+    const doFetch = options.fetchImpl ?? getFetch();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+    try {
+        const res = await doFetch(`${HIBP_RANGE_URL}${prefix}`, {
+            signal: controller.signal,
+            // Add-Padding obscurece o tamanho da resposta (k-anonymity reforçado).
+            headers: { 'Add-Padding': 'true' },
+        });
+        if (!res.ok) {
+            options.logger?.warn({ status: res.status }, 'authkit: HIBP range API returned a non-OK status — skipping pwned check (fail-safe).');
+            return false;
+        }
+        const body = await res.text();
+        // Cada linha: "<SUFIXO>:<count>". Linhas de padding têm count 0 — ignoradas.
+        for (const line of body.split('\n')) {
+            const [candidate, countStr] = line.trim().split(':');
+            if (candidate === suffix && Number(countStr) > 0)
+                return true;
+        }
+        return false;
+    }
+    catch (error) {
+        options.logger?.warn({ err: error }, 'authkit: HIBP range API request failed (network/timeout) — skipping pwned check (fail-safe).');
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/build/src/pat/lucid_pat_store.d.ts

@@ -0,0 +1,6 @@
+import type { PatStore } from './pat_store.js';
+/**
+ * Implementação default do {@link PatStore} sobre um model Lucid composto de
+ * `withPersonalAccessToken()`. A coluna DB `user_id` é mapeada de `accountId`.
+ */
+export declare function lucidPatStore(Model: any): PatStore;

package/build/src/pat/lucid_pat_store.js

@@ -0,0 +1,62 @@
+import { DateTime } from 'luxon';
+import { generatePatToken, hashPatToken } from './pat_tokens.js';
+/**
+ * Implementação default do {@link PatStore} sobre um model Lucid composto de
+ * `withPersonalAccessToken()`. A coluna DB `user_id` é mapeada de `accountId`.
+ */
+export function lucidPatStore(Model) {
+    const toRecord = (row) => ({
+        id: row.id,
+        name: row.name,
+        scopes: row.scopes ?? [],
+        audience: row.audience ?? null,
+        createdAt: row.createdAt ? row.createdAt.toISO() : '',
+        lastUsedAt: row.lastUsedAt ? row.lastUsedAt.toISO() : null,
+        expiresAt: row.expiresAt ? row.expiresAt.toISO() : null,
+    });
+    return {
+        async issue(input) {
+            const token = generatePatToken();
+            const row = await Model.create({
+                userId: input.accountId,
+                name: input.name,
+                tokenHash: hashPatToken(token),
+                scopes: input.scopes ?? [],
+                audience: input.audience ?? null,
+                expiresAt: input.expiresInDays
+                    ? DateTime.now().plus({ days: input.expiresInDays })
+                    : null,
+            });
+            return { token, pat: toRecord(row) };
+        },
+        async listForAccount(accountId) {
+            const rows = await Model.query()
+                .where('user_id', accountId)
+                .orderBy('created_at', 'desc');
+            return rows.map(toRecord);
+        },
+        async revoke(accountId, id) {
+            const row = await Model.query().where('id', id).where('user_id', accountId).first();
+            if (!row)
+                return false;
+            await row.delete();
+            return true;
+        },
+        async findActiveByToken(token) {
+            const hash = hashPatToken(token);
+            const row = await Model.query().where('token_hash', hash).first();
+            if (!row)
+                return null;
+            if (row.expiresAt && row.expiresAt < DateTime.now())
+                return null;
+            row.lastUsedAt = DateTime.now();
+            await row.save();
+            return {
+                accountId: row.userId,
+                scopes: row.scopes ?? [],
+                audience: row.audience ?? null,
+                exp: row.expiresAt ? Math.floor(row.expiresAt.toSeconds()) : null,
+            };
+        },
+    };
+}

package/build/src/pat/pat_store.d.ts

@@ -0,0 +1,31 @@
+/** DTO seguro do PAT — sem o hash do token. */
+export interface PatRecord {
+    id: string;
+    name: string;
+    scopes: string[];
+    audience: string | null;
+    createdAt: string;
+    lastUsedAt: string | null;
+    expiresAt: string | null;
+}
+export interface IssuePatInput {
+    accountId: string;
+    name: string;
+    scopes?: string[];
+    audience?: string | null;
+    expiresInDays?: number | null;
+}
+export interface PatStore {
+    issue(input: IssuePatInput): Promise<{
+        token: string;
+        pat: PatRecord;
+    }>;
+    listForAccount(accountId: string): Promise<PatRecord[]>;
+    revoke(accountId: string, id: string): Promise<boolean>;
+    findActiveByToken(token: string): Promise<{
+        accountId: string;
+        scopes: string[];
+        audience: string | null;
+        exp: number | null;
+    } | null>;
+}

package/build/src/pat/pat_store.js

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

package/build/src/pat/pat_tokens.d.ts

@@ -0,0 +1,4 @@
+/** Gera um Personal Access Token opaco no formato `pat_<base64url>`. */
+export declare function generatePatToken(): string;
+/** SHA-256 (hex) do token — é o que se persiste; o token cru nunca é guardado. */
+export declare function hashPatToken(token: string): string;