@shaferllc/keel 0.80.0 → 0.81.1

package/dist/accounts/accounts.config.stub

@@ -0,0 +1,50 @@
+import { env } from "@shaferllc/keel/core";
+
+/**
+ * Accounts configuration — password reset, email verification, two-factor.
+ * Published with `keel vendor:publish --tag accounts-config`.
+ */
+export default {
+  // The users table. Accounts adds four columns to it and touches nothing else.
+  userTable: "users",
+
+  // The JSON endpoints (POST /auth/login, /auth/password/forgot, …).
+  // Turn them off to call the flow functions from your own controllers instead.
+  routes: { enabled: true, prefix: "auth" },
+
+  passwordReset: {
+    expiresIn: "60m",
+    // Where the emailed link points. `:token` is replaced.
+    url: "/reset-password?token=:token",
+  },
+
+  verification: {
+    expiresIn: "24h",
+    url: "/verify-email?token=:token",
+  },
+
+  twoFactor: {
+    // The name shown in the user's authenticator app.
+    issuer: env("APP_NAME", "Keel"),
+
+    // Periods of clock drift tolerated either side of now. 1 = ±30s, which is
+    // what a phone with a slightly wrong clock needs. Raising it widens the
+    // window an attacker gets to guess in.
+    window: 1,
+
+    // How long the gap between "password accepted" and "code entered" stays open.
+    // This is the window in which a stolen password alone is enough — keep it short.
+    challengeExpiresIn: "5m",
+
+    recoveryCodes: 8,
+  },
+
+  // Throttling on the credential endpoints. A six-digit code inside a 30-second
+  // window is guessable without this, and forgot-password is an email cannon
+  // pointed at whoever the caller names.
+  rateLimit: { max: 5, window: 60 },
+
+  mail: {
+    from: env("MAIL_FROM", undefined),
+  },
+};

package/dist/accounts/config.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Accounts configuration. Defaults live here and are merged under
+ * `config("accounts")` by the provider; an app overrides any of them in
+ * `config/accounts.ts` (publish it with `keel vendor:publish --tag accounts-config`).
+ */
+export interface AccountsConfig {
+    /** The users table. Parameterized so accounts doesn't dictate your schema. */
+    userTable: string;
+    /** Mount the JSON endpoints. Off if you'd rather call the functions yourself. */
+    routes: {
+        enabled: boolean;
+        prefix: string;
+    };
+    passwordReset: {
+        expiresIn: string;
+        /** Where the emailed link points. `:token` is replaced. */
+        url: string;
+    };
+    verification: {
+        expiresIn: string;
+        url: string;
+    };
+    twoFactor: {
+        issuer: string;
+        /** Periods of clock drift to tolerate either side of now. */
+        window: number;
+        /** How long the post-password, pre-code window stays open. */
+        challengeExpiresIn: string;
+        recoveryCodes: number;
+    };
+    /**
+     * Throttling for the credential endpoints. Six digits inside a 30-second window
+     * is trivially brute-forced without this, and password reset is a free email
+     * cannon pointed at whoever you name.
+     */
+    rateLimit: {
+        max: number;
+        window: number;
+    };
+    mail: {
+        from?: string;
+    };
+}
+export declare const defaultConfig: AccountsConfig;
+/** Read the effective accounts config off the application, filling any gaps. */
+export declare function resolveConfig(): AccountsConfig;

package/dist/accounts/config.js

@@ -0,0 +1,39 @@
+/**
+ * Accounts configuration. Defaults live here and are merged under
+ * `config("accounts")` by the provider; an app overrides any of them in
+ * `config/accounts.ts` (publish it with `keel vendor:publish --tag accounts-config`).
+ */
+import { config } from "../core/helpers.js";
+export const defaultConfig = {
+    userTable: "users",
+    routes: { enabled: true, prefix: "auth" },
+    passwordReset: {
+        expiresIn: "60m",
+        url: "/reset-password?token=:token",
+    },
+    verification: {
+        expiresIn: "24h",
+        url: "/verify-email?token=:token",
+    },
+    twoFactor: {
+        issuer: "Keel",
+        window: 1,
+        challengeExpiresIn: "5m",
+        recoveryCodes: 8,
+    },
+    rateLimit: { max: 5, window: 60 },
+    mail: {},
+};
+/** Read the effective accounts config off the application, filling any gaps. */
+export function resolveConfig() {
+    const raw = config("accounts", {});
+    return {
+        userTable: raw.userTable ?? defaultConfig.userTable,
+        routes: { ...defaultConfig.routes, ...raw.routes },
+        passwordReset: { ...defaultConfig.passwordReset, ...raw.passwordReset },
+        verification: { ...defaultConfig.verification, ...raw.verification },
+        twoFactor: { ...defaultConfig.twoFactor, ...raw.twoFactor },
+        rateLimit: { ...defaultConfig.rateLimit, ...raw.rateLimit },
+        mail: { ...defaultConfig.mail, ...raw.mail },
+    };
+}

package/dist/accounts/flows.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The account flows. Controllers call these; the views stay yours.
+ *
+ * Everything security-critical lives here rather than in a template, because a
+ * password-reset flow copy-pasted into five starter kits is four copies that
+ * quietly rot. Templates render forms and call these six functions.
+ */
+import { type AccountUser } from "./store.js";
+export type LoginResult = {
+    status: "ok";
+    user: AccountUser;
+}
+/** Password was right; nothing is logged in yet. Send `challenge` back with a code. */
+ | {
+    status: "two-factor";
+    challenge: string;
+} | {
+    status: "failed";
+};
+/**
+ * Check a password. On success with 2FA on, this returns a **challenge, not a
+ * session** — the caller logs nobody in until `completeTwoFactor()` succeeds.
+ *
+ * A wrong email and a wrong password are the same answer, and both do the same
+ * amount of work: hashing a dummy password when the user doesn't exist keeps the
+ * response time from telling an attacker which emails are real.
+ */
+export declare function attempt(email: string, password: string): Promise<LoginResult>;
+/**
+ * Finish a 2FA login with either an authenticator code or a recovery code.
+ * Returns the user only if the challenge is still valid *and* the code checks out.
+ */
+export declare function completeTwoFactor(challenge: string, code: string): Promise<AccountUser | null>;
+/**
+ * Email a reset link — **or quietly do nothing**, if that address has no account.
+ *
+ * This never reveals whether the email exists. "No account with that address" is a
+ * free account-enumeration oracle, and the endpoint is unauthenticated, so anyone
+ * can ask it about anyone. The caller gets the same answer either way.
+ */
+export declare function requestPasswordReset(email: string): Promise<void>;
+/**
+ * Spend a reset token. Returns false if it's expired, forged, or already used —
+ * "already used" falls out of the token being bound to the old password hash, so
+ * the same link cannot set a password twice.
+ */
+export declare function resetPassword(token: string, password: string): Promise<boolean>;
+export declare function sendVerificationEmail(user: AccountUser): Promise<void>;
+/** Mark the address proven. Idempotent — clicking the link twice is not an error. */
+export declare function verifyEmail(token: string): Promise<AccountUser | null>;

package/dist/accounts/flows.js

@@ -0,0 +1,133 @@
+/**
+ * The account flows. Controllers call these; the views stay yours.
+ *
+ * Everything security-critical lives here rather than in a template, because a
+ * password-reset flow copy-pasted into five starter kits is four copies that
+ * quietly rot. Templates render forms and call these six functions.
+ */
+import { hash } from "../core/crypto.js";
+import { config } from "../core/helpers.js";
+import { mail } from "../core/mail.js";
+import { resolveConfig } from "./config.js";
+import { accountStore } from "./store.js";
+import { emailVerificationToken, passwordResetToken, twoFactorChallenge, verifyEmailToken, verifyPasswordResetToken, verifyTwoFactorChallenge, } from "./tokens.js";
+import { hasTwoFactor, redeemRecoveryCode, verifyTwoFactorCode } from "./two-factor.js";
+/**
+ * Check a password. On success with 2FA on, this returns a **challenge, not a
+ * session** — the caller logs nobody in until `completeTwoFactor()` succeeds.
+ *
+ * A wrong email and a wrong password are the same answer, and both do the same
+ * amount of work: hashing a dummy password when the user doesn't exist keeps the
+ * response time from telling an attacker which emails are real.
+ */
+export async function attempt(email, password) {
+    const config = resolveConfig();
+    const user = await accountStore().findByEmail(email);
+    // `hash.dummy` when there's no user, so a missing account costs the same PBKDF2
+    // as a wrong password. A fast "no such user" is a free enumeration oracle.
+    // `user &&` guards the dummy from ever authenticating anyone.
+    const ok = await hash.verify(user?.password ?? hash.dummy, password);
+    if (!ok || !user)
+        return { status: "failed" };
+    if (hasTwoFactor(user)) {
+        return {
+            status: "two-factor",
+            challenge: await twoFactorChallenge(user, config.twoFactor.challengeExpiresIn),
+        };
+    }
+    return { status: "ok", user };
+}
+/**
+ * Finish a 2FA login with either an authenticator code or a recovery code.
+ * Returns the user only if the challenge is still valid *and* the code checks out.
+ */
+export async function completeTwoFactor(challenge, code) {
+    const config = resolveConfig();
+    const store = accountStore();
+    const user = await verifyTwoFactorChallenge(challenge, (id) => store.findById(id));
+    if (!user)
+        return null;
+    // A recovery code has a dash and is longer; a TOTP code is six digits. Try the
+    // authenticator first — it's what almost everyone uses.
+    if (await verifyTwoFactorCode(user, code, { window: config.twoFactor.window }))
+        return user;
+    if (await redeemRecoveryCode(user, code))
+        return user;
+    return null;
+}
+/* ------------------------------ password reset ---------------------------- */
+/**
+ * Email a reset link — **or quietly do nothing**, if that address has no account.
+ *
+ * This never reveals whether the email exists. "No account with that address" is a
+ * free account-enumeration oracle, and the endpoint is unauthenticated, so anyone
+ * can ask it about anyone. The caller gets the same answer either way.
+ */
+export async function requestPasswordReset(email) {
+    const config = resolveConfig();
+    const user = await accountStore().findByEmail(email);
+    if (!user)
+        return;
+    const token = await passwordResetToken(user, config.passwordReset.expiresIn);
+    const link = absolute(config.passwordReset.url.replace(":token", encodeURIComponent(token)));
+    const message = mail()
+        .to(user.email)
+        .subject("Reset your password")
+        .html(`<p>Someone asked to reset your password.</p>` +
+        `<p><a href="${link}">Choose a new password</a></p>` +
+        `<p>The link expires in ${config.passwordReset.expiresIn}. If this wasn't you, ignore it — nothing has changed.</p>`);
+    if (config.mail.from)
+        message.from(config.mail.from);
+    await message.send();
+}
+/**
+ * Spend a reset token. Returns false if it's expired, forged, or already used —
+ * "already used" falls out of the token being bound to the old password hash, so
+ * the same link cannot set a password twice.
+ */
+export async function resetPassword(token, password) {
+    const store = accountStore();
+    const user = await verifyPasswordResetToken(token, (id) => store.findById(id));
+    if (!user)
+        return false;
+    await store.update(user.id, { password: await hash.make(password) });
+    return true;
+}
+/* --------------------------- email verification --------------------------- */
+export async function sendVerificationEmail(user) {
+    const config = resolveConfig();
+    const token = await emailVerificationToken(user, config.verification.expiresIn);
+    const link = absolute(config.verification.url.replace(":token", encodeURIComponent(token)));
+    const message = mail()
+        .to(user.email)
+        .subject("Confirm your email address")
+        .html(`<p>Confirm your address to finish setting up your account.</p>
+           <p><a href="${link}">Confirm ${user.email}</a></p>`);
+    if (config.mail.from)
+        message.from(config.mail.from);
+    await message.send();
+}
+/** Mark the address proven. Idempotent — clicking the link twice is not an error. */
+export async function verifyEmail(token) {
+    const store = accountStore();
+    const user = await verifyEmailToken(token, (id) => store.findById(id));
+    if (!user)
+        return null;
+    if (!user.email_verified_at) {
+        await store.update(user.id, { email_verified_at: new Date().toISOString() });
+    }
+    return user;
+}
+/* --------------------------------- helpers -------------------------------- */
+/**
+ * Leave absolute URLs alone; make relative ones absolute against `app.url`.
+ *
+ * Read through `config()`, not `process.env` — this module has to run on Workers,
+ * where there is no `process`.
+ */
+function absolute(url) {
+    if (/^https?:\/\//i.test(url))
+        return url;
+    const base = config("app.url", "http://localhost:3000").replace(/\/$/, "");
+    return `${base}${url.startsWith("/") ? "" : "/"}${url}`;
+}

package/dist/accounts/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Keel Accounts — public surface, imported from `@shaferllc/keel/accounts`.
+ *
+ *   import { AccountsServiceProvider, attempt } from "@shaferllc/keel/accounts";
+ *
+ * Password reset, email verification, and two-factor: the flows every app with a
+ * login needs, built on the primitives already in core (`hash`, `encryption` with
+ * purpose + expiry, `mail`, `rate-limit`). They live here, tested once, instead of
+ * being copy-pasted into every starter kit — four copies of a security flow are
+ * four copies that quietly rot.
+ *
+ * Views stay yours. These are functions and JSON endpoints; your controllers
+ * render the forms.
+ */
+export { AccountsServiceProvider } from "./provider.js";
+export { attempt, completeTwoFactor, requestPasswordReset, resetPassword, sendVerificationEmail, verifyEmail, } from "./flows.js";
+export type { LoginResult } from "./flows.js";
+export { confirmTwoFactor, disableTwoFactor, enableTwoFactor, hasTwoFactor, recoveryCodesRemaining, redeemRecoveryCode, regenerateRecoveryCodes, verifyTwoFactorCode, } from "./two-factor.js";
+export type { TwoFactorOptions, TwoFactorSetup } from "./two-factor.js";
+export { base32Decode, base32Encode, generateSecret, otpauthUri, totp, verifyTotp, } from "./totp.js";
+export type { OtpauthOptions, TotpOptions, VerifyOptions } from "./totp.js";
+export { emailVerificationToken, passwordResetToken, twoFactorChallenge, verifyEmailToken, verifyPasswordResetToken, verifyTwoFactorChallenge, PURPOSE, } from "./tokens.js";
+export { accountStore, setAccountStore, tableStore } from "./store.js";
+export type { AccountStore, AccountUser } from "./store.js";
+export { registerAccountsRoutes } from "./routes.js";
+export { accountsMigration } from "./migration.js";
+export { defaultConfig, resolveConfig } from "./config.js";
+export type { AccountsConfig } from "./config.js";

package/dist/accounts/index.js

@@ -0,0 +1,23 @@
+/**
+ * Keel Accounts — public surface, imported from `@shaferllc/keel/accounts`.
+ *
+ *   import { AccountsServiceProvider, attempt } from "@shaferllc/keel/accounts";
+ *
+ * Password reset, email verification, and two-factor: the flows every app with a
+ * login needs, built on the primitives already in core (`hash`, `encryption` with
+ * purpose + expiry, `mail`, `rate-limit`). They live here, tested once, instead of
+ * being copy-pasted into every starter kit — four copies of a security flow are
+ * four copies that quietly rot.
+ *
+ * Views stay yours. These are functions and JSON endpoints; your controllers
+ * render the forms.
+ */
+export { AccountsServiceProvider } from "./provider.js";
+export { attempt, completeTwoFactor, requestPasswordReset, resetPassword, sendVerificationEmail, verifyEmail, } from "./flows.js";
+export { confirmTwoFactor, disableTwoFactor, enableTwoFactor, hasTwoFactor, recoveryCodesRemaining, redeemRecoveryCode, regenerateRecoveryCodes, verifyTwoFactorCode, } from "./two-factor.js";
+export { base32Decode, base32Encode, generateSecret, otpauthUri, totp, verifyTotp, } from "./totp.js";
+export { emailVerificationToken, passwordResetToken, twoFactorChallenge, verifyEmailToken, verifyPasswordResetToken, verifyTwoFactorChallenge, PURPOSE, } from "./tokens.js";
+export { accountStore, setAccountStore, tableStore } from "./store.js";
+export { registerAccountsRoutes } from "./routes.js";
+export { accountsMigration } from "./migration.js";
+export { defaultConfig, resolveConfig } from "./config.js";

package/dist/accounts/migration.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The accounts schema — four columns on the users table, and no tokens table.
+ *
+ * There is deliberately no `password_resets` table. Reset and verification tokens
+ * carry their own purpose and expiry inside the ciphertext (see tokens.ts), so
+ * there is nothing to insert, nothing to look up, and nothing to garbage-collect —
+ * and no window where a forgotten cleanup job leaves a live token in a row.
+ *
+ * Columns are added with `schema.raw()` because the builder has no `alterTable`,
+ * and the SQL is kept to the intersection sqlite, mysql, and postgres all accept —
+ * the same approach as `billingMigration`.
+ */
+import type { Migration } from "../core/migrations.js";
+export declare function accountsMigration(userTable?: string): Migration;

package/dist/accounts/migration.js

@@ -0,0 +1,39 @@
+/**
+ * The accounts schema — four columns on the users table, and no tokens table.
+ *
+ * There is deliberately no `password_resets` table. Reset and verification tokens
+ * carry their own purpose and expiry inside the ciphertext (see tokens.ts), so
+ * there is nothing to insert, nothing to look up, and nothing to garbage-collect —
+ * and no window where a forgotten cleanup job leaves a live token in a row.
+ *
+ * Columns are added with `schema.raw()` because the builder has no `alterTable`,
+ * and the SQL is kept to the intersection sqlite, mysql, and postgres all accept —
+ * the same approach as `billingMigration`.
+ */
+const COLUMNS = [
+    "email_verified_at TIMESTAMP",
+    // Encrypted at rest: a database leak must not hand over everyone's second factor.
+    "two_factor_secret TEXT",
+    // Hashed, single-use, JSON — then encrypted, same reasoning.
+    "two_factor_recovery_codes TEXT",
+    // Null until a working code proves the user can actually generate one.
+    "two_factor_confirmed_at TIMESTAMP",
+];
+export function accountsMigration(userTable = "users") {
+    return {
+        name: "accounts_00_add_account_columns",
+        async up(schema) {
+            for (const column of COLUMNS) {
+                await schema.raw(`ALTER TABLE ${userTable} ADD COLUMN ${column}`);
+            }
+        },
+        async down(schema) {
+            for (const column of COLUMNS) {
+                const name = column.split(" ")[0];
+                // sqlite couldn't drop columns until 3.35; a failed drop shouldn't wedge
+                // a rollback of everything else.
+                await schema.raw(`ALTER TABLE ${userTable} DROP COLUMN ${name}`).catch(() => { });
+            }
+        },
+    };
+}

package/dist/accounts/provider.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Accounts — password reset, email verification, and two-factor, shipped as a Keel
+ * package. One line in `bootstrap/providers.ts` turns it on:
+ *
+ *   app.register(AccountsServiceProvider)
+ *
+ * `register()` merges config, installs the store, and contributes the migration.
+ * `boot()` mounts the JSON endpoints (unless you've turned them off and would
+ * rather call the flow functions from your own controllers).
+ */
+import { PackageProvider } from "../core/package.js";
+export declare class AccountsServiceProvider extends PackageProvider {
+    readonly name = "accounts";
+    private config;
+    register(): void;
+    boot(): void;
+    shutdown(): void;
+}

package/dist/accounts/provider.js

@@ -0,0 +1,37 @@
+/**
+ * Accounts — password reset, email verification, and two-factor, shipped as a Keel
+ * package. One line in `bootstrap/providers.ts` turns it on:
+ *
+ *   app.register(AccountsServiceProvider)
+ *
+ * `register()` merges config, installs the store, and contributes the migration.
+ * `boot()` mounts the JSON endpoints (unless you've turned them off and would
+ * rather call the flow functions from your own controllers).
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { PackageProvider } from "../core/package.js";
+import { defaultConfig, resolveConfig } from "./config.js";
+import { accountsMigration } from "./migration.js";
+import { registerAccountsRoutes } from "./routes.js";
+import { setAccountStore, tableStore } from "./store.js";
+const here = dirname(fileURLToPath(import.meta.url));
+export class AccountsServiceProvider extends PackageProvider {
+    name = "accounts";
+    config;
+    register() {
+        this.mergeConfig("accounts", defaultConfig);
+        this.config = resolveConfig();
+        setAccountStore(tableStore(this.config.userTable));
+        this.migrations([accountsMigration(this.config.userTable)]);
+        this.publishes({ [join(here, "accounts.config.stub")]: "config/accounts.ts" }, "accounts-config");
+    }
+    boot() {
+        if (!this.config.routes.enabled)
+            return;
+        this.routes((r) => registerAccountsRoutes(r, this.config));
+    }
+    shutdown() {
+        setAccountStore(undefined);
+    }
+}

package/dist/accounts/routes.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The accounts HTTP surface — JSON endpoints, no views.
+ *
+ * Core cannot render your login page and shouldn't try: views are the app's, and
+ * this module has to run on Workers. So these endpoints do the security-critical
+ * part and return JSON; a full-stack template wraps them in controllers that
+ * render forms, and an API template mounts them as-is.
+ *
+ * Every endpoint here is unauthenticated and touches credentials, so the whole
+ * group is rate-limited. Without it, password reset is an email cannon you point
+ * at whoever you name, and a six-digit 2FA code is guessable in an afternoon.
+ */
+import type { Router } from "../core/http/router.js";
+import type { AccountsConfig } from "./config.js";
+export declare function registerAccountsRoutes(r: Router, config: AccountsConfig): void;

package/dist/accounts/routes.js

@@ -0,0 +1,116 @@
+/**
+ * The accounts HTTP surface — JSON endpoints, no views.
+ *
+ * Core cannot render your login page and shouldn't try: views are the app's, and
+ * this module has to run on Workers. So these endpoints do the security-critical
+ * part and return JSON; a full-stack template wraps them in controllers that
+ * render forms, and an API template mounts them as-is.
+ *
+ * Every endpoint here is unauthenticated and touches credentials, so the whole
+ * group is rate-limited. Without it, password reset is an email cannon you point
+ * at whoever you name, and a six-digit 2FA code is guessable in an afternoon.
+ */
+import { rateLimiter } from "../core/rate-limit.js";
+import { attempt, completeTwoFactor, requestPasswordReset, resetPassword, sendVerificationEmail, verifyEmail, } from "./flows.js";
+export function registerAccountsRoutes(r, config) {
+    const base = "/" + config.routes.prefix.replace(/^\/|\/$/g, "");
+    const limit = rateLimiter({ max: config.rateLimit.max, window: config.rateLimit.window });
+    /* ---------------------------------- login --------------------------------- */
+    r.post(`${base}/login`, async (c) => {
+        const { email, password } = await body(c);
+        if (!email || !password)
+            return c.json({ error: "Email and password are required." }, 422);
+        const result = await attempt(email, password);
+        if (result.status === "failed") {
+            // One message for a wrong email and a wrong password. Anything more specific
+            // tells an attacker which addresses have accounts.
+            return c.json({ error: "Those credentials don't match." }, 401);
+        }
+        if (result.status === "two-factor") {
+            // Note what this is NOT: a session. Nothing is logged in yet.
+            return c.json({ twoFactor: true, challenge: result.challenge }, 200);
+        }
+        return c.json({ user: publicUser(result.user) }, 200);
+    })
+        .middleware(limit)
+        .name("accounts.login");
+    r.post(`${base}/two-factor`, async (c) => {
+        const { challenge, code } = await body(c);
+        if (!challenge || !code)
+            return c.json({ error: "A challenge and a code are required." }, 422);
+        const user = await completeTwoFactor(challenge, code);
+        if (!user)
+            return c.json({ error: "That code isn't valid." }, 401);
+        return c.json({ user: publicUser(user) }, 200);
+    })
+        .middleware(limit)
+        .name("accounts.two-factor");
+    /* ------------------------------ password reset ---------------------------- */
+    r.post(`${base}/password/forgot`, async (c) => {
+        const { email } = await body(c);
+        if (!email)
+            return c.json({ error: "An email is required." }, 422);
+        await requestPasswordReset(email);
+        // 202 whether or not that address has an account. The response must not be an
+        // oracle for which emails are registered.
+        return c.json({ status: "If that address has an account, a link is on its way." }, 202);
+    })
+        .middleware(limit)
+        .name("accounts.password.forgot");
+    r.post(`${base}/password/reset`, async (c) => {
+        const { token, password } = await body(c);
+        if (!token || !password)
+            return c.json({ error: "A token and a password are required." }, 422);
+        const ok = await resetPassword(token, password);
+        if (!ok)
+            return c.json({ error: "That reset link is invalid or has expired." }, 422);
+        return c.json({ status: "Your password has been reset." }, 200);
+    })
+        .middleware(limit)
+        .name("accounts.password.reset");
+    /* --------------------------- email verification --------------------------- */
+    r.post(`${base}/email/verify`, async (c) => {
+        const { token } = await body(c);
+        if (!token)
+            return c.json({ error: "A token is required." }, 422);
+        const user = await verifyEmail(token);
+        if (!user)
+            return c.json({ error: "That link is invalid or has expired." }, 422);
+        return c.json({ status: "Your email is confirmed.", user: publicUser(user) }, 200);
+    })
+        .middleware(limit)
+        .name("accounts.email.verify");
+    r.post(`${base}/email/resend`, async (c) => {
+        const { email } = await body(c);
+        if (!email)
+            return c.json({ error: "An email is required." }, 422);
+        const { accountStore } = await import("./store.js");
+        const user = await accountStore().findByEmail(email);
+        // Same reasoning as forgot-password: don't confirm whether the account exists.
+        if (user && !user.email_verified_at)
+            await sendVerificationEmail(user);
+        return c.json({ status: "If that address needs confirming, a link is on its way." }, 202);
+    })
+        .middleware(limit)
+        .name("accounts.email.resend");
+}
+/* --------------------------------- helpers -------------------------------- */
+async function body(c) {
+    try {
+        return (await c.req.json());
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * What's safe to hand back. Explicitly allow-listed rather than deleting the
+ * secrets — a deny-list means the next column someone adds leaks by default.
+ */
+function publicUser(user) {
+    return {
+        id: user.id,
+        email: user.email,
+        emailVerified: Boolean(user.email_verified_at),
+    };
+}

package/dist/accounts/store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Where accounts reads and writes users.
+ *
+ * The module refuses to assume you use a `Model` — it talks to a table through
+ * the query builder, exactly like `billing` parameterizes its billable table. If
+ * your users live somewhere else entirely (an auth service, a legacy schema),
+ * replace the whole thing:
+ *
+ *   setAccountStore({ findById, findByEmail, update });
+ */
+import { type Row } from "../core/database.js";
+/** The columns accounts needs. Everything else on your users table is untouched. */
+export interface AccountUser extends Row {
+    id: string | number;
+    email: string;
+    /** The hashed password. Never the plaintext. */
+    password?: string | null;
+    email_verified_at?: string | null;
+    /** The TOTP secret, encrypted at rest. */
+    two_factor_secret?: string | null;
+    /** Hashed, single-use recovery codes, as a JSON array. */
+    two_factor_recovery_codes?: string | null;
+    two_factor_confirmed_at?: string | null;
+}
+export interface AccountStore {
+    findById(id: string | number): Promise<AccountUser | null>;
+    findByEmail(email: string): Promise<AccountUser | null>;
+    update(id: string | number, values: Row): Promise<void>;
+}
+/** The default store: a table, through the query builder. */
+export declare function tableStore(table: string): AccountStore;
+export declare function setAccountStore(next: AccountStore | undefined): void;
+export declare function accountStore(): AccountStore;