@binary1702/auth 0.2.5 → 0.4.0

package/dist/core/db.js

@@ -1,105 +1,485 @@
 // ─────────────────────────────────────────────────────────────
-// Storage. One table, owned by this package.
+// Storage. Tables owned by this package, created by migrations.
 //
-//   auth_users (id, email, password_hash, created_at, session_epoch)
+//   auth_migrations (id, applied_at)   which steps have run
+//   users, orgs, members, tokens       see each migration step below
 //
 // session_epoch: every session token carries the value it was signed
 // under, and is only good while they match (see core/session.ts).
 // +1 revokes every session of that user; deleting the row revokes
 // them too, since there is nothing left to match.
 //
-// ensureSchema() is idempotent and memoized per process, so route
-// handlers can call it on every request for free after the first.
+// Every function takes the store as its last argument and defaults
+// to the real database, so handler logic can run against a fake in
+// tests. ensureSchema() applies pending migrations once per process
+// and never re-runs a completed one.
 // ─────────────────────────────────────────────────────────────
 import { neon } from "@neondatabase/serverless";
 import { getDatabaseUrl, TABLE } from "./config.js";
-let _sql = null;
-function sql() {
-    return (_sql ??= neon(getDatabaseUrl()));
-}
-let _schema = null;
-export function ensureSchema() {
-    return (_schema ??= (async () => {
-        await sql() `
-      CREATE TABLE IF NOT EXISTS auth_users (
+let _db = null;
+/** The real store, created once per process from DATABASE_URL. */
+export function db() {
+    if (_db)
+        return _db;
+    const sql = neon(getDatabaseUrl());
+    return (_db = {
+        query: (text, params = []) => sql.query(text, params),
+        transaction: async (statements) => {
+            await sql.transaction(statements.map((s) => sql.query(s.text, s.params ?? [])));
+        },
+    });
+}
+async function runAll(store, statements) {
+    if (store.transaction)
+        return store.transaction(statements);
+    for (const s of statements)
+        await store.query(s.text, s.params);
+}
+/**
+ * Ordered, append-only. Never edit a step that has shipped: add a new
+ * one. Step 1 is the 0.2.5 schema exactly, so an existing install
+ * applies it as a no-op through IF NOT EXISTS.
+ */
+export const MIGRATIONS = [
+    {
+        id: 1,
+        name: "users",
+        statements: [
+            `CREATE TABLE IF NOT EXISTS users (
         id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
         email         TEXT NOT NULL UNIQUE,
         password_hash TEXT NOT NULL,
-        created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
-      )
-    `;
-        // Added in 0.2.5: installs from before get it on their next start
-        await sql() `
-      ALTER TABLE auth_users ADD COLUMN IF NOT EXISTS session_epoch INT NOT NULL DEFAULT 0
-    `;
-    })().catch((err) => {
-        _schema = null; // let the next call retry
+        created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+        session_epoch INT NOT NULL DEFAULT 0
+      )`,
+            // Installs from before 0.2.5 have the table without this column
+            `ALTER TABLE users ADD COLUMN IF NOT EXISTS session_epoch INT NOT NULL DEFAULT 0`,
+        ],
+    },
+    {
+        id: 2,
+        name: "tokens",
+        statements: [
+            // One-time tokens: only the SHA-256 of the token is stored (see core/tokens.ts)
+            `CREATE TABLE IF NOT EXISTS tokens (
+        id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        user_id    UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+        kind       TEXT NOT NULL,
+        token_hash TEXT NOT NULL UNIQUE,
+        expires_at TIMESTAMPTZ NOT NULL,
+        used_at    TIMESTAMPTZ,
+        meta       JSONB NOT NULL DEFAULT '{}'::jsonb,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+      )`,
+            `CREATE INDEX IF NOT EXISTS tokens_user_kind ON tokens (user_id, kind)`,
+        ],
+    },
+    {
+        id: 3,
+        name: "email_verified",
+        statements: [
+            // NULL until the user follows the link we emailed (see core/verify.ts).
+            // Existing users stay NULL; nothing changes for them unless
+            // AUTH_REQUIRE_VERIFIED is turned on.
+            `ALTER TABLE users ADD COLUMN IF NOT EXISTS email_verified_at TIMESTAMPTZ`,
+        ],
+    },
+    {
+        id: 4,
+        name: "organizations",
+        statements: [
+            // A user belongs to organizations through members, with one
+            // role per membership. The session carries one "active" org:
+            // active_org_id when still a member, else the earliest membership.
+            // See core/org.ts.
+            `CREATE TABLE IF NOT EXISTS orgs (
+        id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        name       TEXT NOT NULL,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+      )`,
+            `CREATE TABLE IF NOT EXISTS members (
+        org_id     UUID NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
+        user_id    UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+        role       TEXT NOT NULL DEFAULT 'member',
+        created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+        PRIMARY KEY (org_id, user_id)
+      )`,
+            `CREATE INDEX IF NOT EXISTS members_user ON members (user_id, created_at)`,
+            `ALTER TABLE users ADD COLUMN IF NOT EXISTS active_org_id UUID REFERENCES orgs(id) ON DELETE SET NULL`,
+        ],
+    },
+    {
+        id: 5,
+        name: "drop_auth_prefix",
+        statements: [
+            // Installs from before this step have auth_users, auth_orgs, …; a
+            // fresh install created the new names in steps 1-4 and these do nothing.
+            `ALTER TABLE IF EXISTS auth_users RENAME TO users`,
+            `ALTER TABLE IF EXISTS auth_orgs RENAME TO orgs`,
+            `ALTER TABLE IF EXISTS auth_members RENAME TO members`,
+            `ALTER TABLE IF EXISTS auth_tokens RENAME TO tokens`,
+            `ALTER INDEX IF EXISTS auth_tokens_user_kind RENAME TO tokens_user_kind`,
+            `ALTER INDEX IF EXISTS auth_members_user RENAME TO members_user`,
+        ],
+    },
+    {
+        id: 6,
+        name: "rate_limits",
+        statements: [
+            // One row per bucket ("signin:email:ben@x.y"): how many hits in the
+            // current window and when the window resets. See core/rate.ts.
+            `CREATE TABLE IF NOT EXISTS rate_limits (
+        bucket   TEXT PRIMARY KEY,
+        count    INT NOT NULL,
+        reset_at TIMESTAMPTZ NOT NULL
+      )`,
+        ],
+    },
+    {
+        id: 7,
+        name: "email_lower",
+        statements: [
+            // Emails have always been lowercased on the way in; make the
+            // database say so too, whatever writes to it. Two rows differing
+            // only in case would make this step fail with a clear message.
+            `UPDATE users SET email = LOWER(email) WHERE email <> LOWER(email)`,
+            `CREATE UNIQUE INDEX IF NOT EXISTS users_email_lower ON users (LOWER(email))`,
+        ],
+    },
+    {
+        id: 8,
+        name: "roles",
+        statements: [
+            // What a role may do, as saved on /auth/admin. b17_auth.yaml is the
+            // starting point; a row here wins. scope '' = every organization,
+            // an organization's id = that organization only.
+            `CREATE TABLE IF NOT EXISTS roles (
+        scope       TEXT NOT NULL DEFAULT '',
+        name        TEXT NOT NULL,
+        permissions TEXT[] NOT NULL,
+        updated_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+        PRIMARY KEY (scope, name)
+      )`,
+        ],
+    },
+];
+/**
+ * The package's tables have plain names (users, orgs, members, tokens).
+ * A database that already holds a `users` table of its own would be
+ * silently shared by CREATE TABLE IF NOT EXISTS, so a fresh install
+ * checks first. Pure: decides from what the store reports.
+ */
+export function foreignUsersTable(columns) {
+    return columns.length > 0 && !columns.includes("session_epoch");
+}
+export const FOREIGN_USERS_TABLE = "This database already has a `users` table that is not this package's. Point DATABASE_URL at a database (or Postgres schema) of its own.";
+/** The steps still to run, in order. Pure. */
+export function pendingSteps(applied, steps = MIGRATIONS) {
+    const done = new Set(applied);
+    return [...steps].filter((m) => !done.has(m.id)).sort((a, b) => a.id - b.id);
+}
+/** Everything a pending step needs to run, including recording that it ran. Pure. */
+export function migrationStatements(steps) {
+    return steps.flatMap((m) => [
+        ...m.statements.map((text) => ({ text })),
+        { text: `INSERT INTO auth_migrations (id) VALUES ($1)`, params: [m.id] },
+    ]);
+}
+const ready = new WeakMap();
+/**
+ * Apply pending migrations. Memoized per store and per process, so
+ * route handlers can call it on every request for free after the first.
+ * A failure clears the memo so the next call retries.
+ */
+export function ensureSchema(store = db()) {
+    const cached = ready.get(store);
+    if (cached)
+        return cached;
+    const run = migrate(store).catch((err) => {
+        ready.delete(store);
         throw err;
-    }));
+    });
+    ready.set(store, run);
+    return run;
+}
+async function appliedIds(store) {
+    return (await store.query(`SELECT id FROM auth_migrations`)).map((r) => Number(r.id));
 }
-export async function findUser(email) {
-    await ensureSchema();
-    const rows = (await sql() `
-    SELECT id, email, password_hash, session_epoch AS epoch FROM auth_users WHERE email = ${email}
-  `);
+async function migrate(store) {
+    await store.query(`CREATE TABLE IF NOT EXISTS auth_migrations (
+      id         INT PRIMARY KEY,
+      applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+    )`);
+    const pending = pendingSteps(await appliedIds(store));
+    if (pending.length === 0)
+        return;
+    if (pending[0].id === 1) {
+        // A fresh install: make sure we are not about to adopt somebody else's users table
+        const cols = await store.query(`SELECT column_name FROM information_schema.columns WHERE table_schema = current_schema() AND table_name = 'users'`);
+        if (foreignUsersTable(cols.map((c) => c.column_name)))
+            throw new Error(FOREIGN_USERS_TABLE);
+    }
+    try {
+        await runAll(store, migrationStatements(pending));
+    }
+    catch (err) {
+        // Two processes starting at once both see the same pending steps;
+        // the second one's INSERT hits the primary key and its transaction
+        // rolls back. If the first finished the job, that is fine.
+        if (pendingSteps(await appliedIds(store)).length === 0)
+            return;
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`auth migration ${pending[0].id} (${pending[0].name}) failed: ${msg}`);
+    }
+}
+/** Emails are stored lowercase, so lookups are case-insensitive. */
+const norm = (email) => email.trim().toLowerCase();
+const USER_COLUMNS = `id, email, password_hash, session_epoch AS epoch, email_verified_at AS verified_at`;
+export async function findUser(email, store = db()) {
+    await ensureSchema(store);
+    const rows = await store.query(`SELECT ${USER_COLUMNS} FROM users WHERE email = $1`, [norm(email)]);
     return rows[0] ?? null;
 }
-export async function createUser(email, passwordHash) {
-    await ensureSchema();
-    const [row] = (await sql() `
-    INSERT INTO auth_users (email, password_hash)
-    VALUES (${email}, ${passwordHash})
-    RETURNING id, email, session_epoch AS epoch
-  `);
-    return row;
+/** Two sign-ups raced on one email and the second lost: the handler answers 409. */
+export class DuplicateUserError extends Error {
+    constructor(email) {
+        super(`A user with the email ${email} already exists`);
+        this.name = "DuplicateUserError";
+    }
+}
+/** Postgres's unique_violation */
+export const isUniqueViolation = (err) => err?.code === "23505";
+export async function createUser(email, passwordHash, opts = {}, store = db()) {
+    await ensureSchema(store);
+    let row;
+    try {
+        ;
+        [row] = await store.query(`INSERT INTO users (email, password_hash, email_verified_at)
+       VALUES ($1, $2, CASE WHEN $3 THEN now() ELSE NULL END)
+       RETURNING id, email, session_epoch AS epoch, email_verified_at AS verified_at`, [norm(email), passwordHash, Boolean(opts.verified)]);
+    }
+    catch (err) {
+        if (isUniqueViolation(err))
+            throw new DuplicateUserError(norm(email));
+        throw err;
+    }
+    return { id: row.id, email: row.email, epoch: row.epoch, verified: row.verified_at !== null };
+}
+/** Replace a hash with one made under stronger parameters. No epoch bump: nothing about the session changes. */
+export async function rehashPassword(id, passwordHash, store = db()) {
+    if (!UUID.test(id))
+        return;
+    await ensureSchema(store);
+    await store.query(`UPDATE users SET password_hash = $2 WHERE id = $1`, [id, passwordHash]);
 }
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-/** The user's current session_epoch, or null if the user is gone */
-export async function sessionEpoch(id) {
+export async function userState(id, store = db()) {
     // A non-UUID would make Postgres throw on the cast; it can't be a user
     if (!UUID.test(id))
         return null;
-    await ensureSchema();
-    const rows = (await sql() `
-    SELECT session_epoch FROM auth_users WHERE id = ${id}
-  `);
-    return rows[0]?.session_epoch ?? null;
+    await ensureSchema(store);
+    const rows = await store.query(`SELECT session_epoch, email_verified_at FROM users WHERE id = $1`, [id]);
+    const row = rows[0];
+    return row ? { epoch: row.session_epoch, verified: row.email_verified_at !== null } : null;
+}
+/** The user's current session_epoch, or null if the user is gone */
+export async function sessionEpoch(id, store = db()) {
+    return (await userState(id, store))?.epoch ?? null;
+}
+export async function sessionRow(id, store = db()) {
+    if (!UUID.test(id))
+        return null;
+    await ensureSchema(store);
+    const rows = await store.query(`SELECT u.id, u.email, u.session_epoch, u.email_verified_at, o.id AS org_id, o.name AS org_name, m.role,
+            ro.permissions AS stored_org, ra.permissions AS stored_all
+     FROM users u
+     LEFT JOIN members m
+       ON m.user_id = u.id
+      AND m.org_id = COALESCE(
+        (SELECT a.org_id FROM members a WHERE a.user_id = u.id AND a.org_id = u.active_org_id),
+        (SELECT f.org_id FROM members f WHERE f.user_id = u.id ORDER BY f.created_at, f.org_id LIMIT 1)
+      )
+     LEFT JOIN orgs o ON o.id = m.org_id
+     LEFT JOIN roles ro ON ro.scope = o.id::text AND ro.name = m.role
+     LEFT JOIN roles ra ON ra.scope = '' AND ra.name = m.role
+     WHERE u.id = $1`, [id]);
+    const r = rows[0];
+    if (!r)
+        return null;
+    return {
+        id: r.id,
+        email: r.email,
+        epoch: r.session_epoch,
+        verified: r.email_verified_at !== null,
+        org_id: r.org_id,
+        org_name: r.org_name,
+        role: r.role,
+        stored_org: r.stored_org ?? null,
+        stored_all: r.stored_all ?? null,
+    };
+}
+/** Every saved role, all scopes. */
+export async function storedRoles(store = db()) {
+    await ensureSchema(store);
+    return store.query(`SELECT scope, name, permissions, updated_at FROM roles ORDER BY scope, name`);
+}
+/** Save what a role may do: for every organization (scope "") or one (its id). Replaces the previous list. */
+export async function setRolePermissions(scope, name, permissions, store = db()) {
+    await ensureSchema(store);
+    await store.query(`INSERT INTO roles (scope, name, permissions, updated_at) VALUES ($1, $2, $3, now())
+     ON CONFLICT (scope, name) DO UPDATE SET permissions = EXCLUDED.permissions, updated_at = now()`, [scope, name, permissions]);
+}
+/** Forget an organization's own rule for a role: it follows the rule for every organization again. False if there was none. */
+export async function resetRole(scope, name, store = db()) {
+    await ensureSchema(store);
+    const rows = await store.query(`DELETE FROM roles WHERE scope = $1 AND name = $2 RETURNING name`, [scope, name]);
+    return rows.length > 0;
+}
+/**
+ * The starting point, written once: every role from b17_auth.yaml `roles:`
+ * that has no row for every organization yet. A role the admin page has
+ * already saved is never touched. Returns the names written.
+ */
+export async function seedRoles(defaults, store = db()) {
+    await ensureSchema(store);
+    const written = [];
+    for (const [name, permissions] of Object.entries(defaults)) {
+        const rows = await store.query(`INSERT INTO roles (scope, name, permissions) VALUES ('', $1, $2) ON CONFLICT (scope, name) DO NOTHING RETURNING name`, [name, permissions]);
+        if (rows.length)
+            written.push(name);
+    }
+    return written;
+}
+/** The user's role in one organization, or null when they are not a member. */
+export async function memberRole(userId, orgId, store = db()) {
+    if (!UUID.test(userId) || !UUID.test(orgId))
+        return null;
+    await ensureSchema(store);
+    const rows = await store.query(`SELECT role FROM members WHERE user_id = $1 AND org_id = $2`, [userId, orgId]);
+    return rows[0]?.role ?? null;
+}
+export async function createOrg(name, store = db()) {
+    await ensureSchema(store);
+    const [row] = await store.query(`INSERT INTO orgs (name) VALUES ($1) RETURNING id, name, created_at`, [name.trim()]);
+    return row;
+}
+/** By id (UUID) or exact name. Null if there is no such organization. */
+export async function findOrg(idOrName, store = db()) {
+    await ensureSchema(store);
+    const rows = UUID.test(idOrName)
+        ? await store.query(`SELECT id, name, created_at FROM orgs WHERE id = $1`, [idOrName])
+        : await store.query(`SELECT id, name, created_at FROM orgs WHERE name = $1 ORDER BY created_at LIMIT 1`, [idOrName.trim()]);
+    return rows[0] ?? null;
+}
+export async function listOrgs(store = db()) {
+    await ensureSchema(store);
+    return store.query(`SELECT o.id, o.name, o.created_at, COUNT(m.user_id)::int AS members
+     FROM orgs o LEFT JOIN members m ON m.org_id = o.id
+     GROUP BY o.id ORDER BY o.created_at`);
+}
+/** Add or update a membership. Becomes the user's active org if they had none. */
+export async function addMember(orgId, userId, role, store = db()) {
+    await ensureSchema(store);
+    await store.query(`INSERT INTO members (org_id, user_id, role) VALUES ($1, $2, $3)
+     ON CONFLICT (org_id, user_id) DO UPDATE SET role = EXCLUDED.role`, [orgId, userId, role]);
+    await store.query(`UPDATE users SET active_org_id = $2 WHERE id = $1 AND active_org_id IS NULL`, [userId, orgId]);
+}
+export async function removeMember(orgId, userId, store = db()) {
+    await ensureSchema(store);
+    const rows = await store.query(`DELETE FROM members WHERE org_id = $1 AND user_id = $2 RETURNING user_id`, [orgId, userId]);
+    return rows.length > 0;
+}
+export async function removeOrg(orgId, store = db()) {
+    if (!UUID.test(orgId))
+        return false;
+    await ensureSchema(store);
+    const rows = await store.query(`DELETE FROM orgs WHERE id = $1 RETURNING id`, [orgId]);
+    return rows.length > 0;
+}
+/** Every user with their memberships, one query. */
+export async function adminUsers(store = db()) {
+    await ensureSchema(store);
+    const rows = await store.query(`SELECT u.id, u.email, u.created_at, (u.email_verified_at IS NOT NULL) AS verified,
+            COALESCE(json_agg(json_build_object('org_id', o.id, 'org', o.name, 'role', m.role) ORDER BY m.created_at)
+                     FILTER (WHERE o.id IS NOT NULL), '[]'::json) AS memberships
+     FROM users u
+     LEFT JOIN members m ON m.user_id = u.id
+     LEFT JOIN orgs o ON o.id = m.org_id
+     GROUP BY u.id ORDER BY u.created_at`);
+    return rows.map((r) => ({ ...r, memberships: typeof r.memberships === "string" ? JSON.parse(r.memberships) : r.memberships }));
+}
+/** Every organization with its members, one query. */
+export async function adminOrgs(store = db()) {
+    await ensureSchema(store);
+    const rows = await store.query(`SELECT o.id, o.name, o.created_at,
+            COALESCE(json_agg(json_build_object('user_id', u.id, 'email', u.email, 'role', m.role) ORDER BY m.created_at)
+                     FILTER (WHERE u.id IS NOT NULL), '[]'::json) AS members
+     FROM orgs o
+     LEFT JOIN members m ON m.org_id = o.id
+     LEFT JOIN users u ON u.id = m.user_id
+     GROUP BY o.id ORDER BY o.created_at`);
+    return rows.map((r) => ({ ...r, members: typeof r.members === "string" ? JSON.parse(r.members) : r.members }));
+}
+/** Switch the user's active organization. False unless they are a member of it: the client's choice is checked, never trusted. */
+export async function setActiveOrg(userId, orgId, store = db()) {
+    if (!UUID.test(userId) || !UUID.test(orgId))
+        return false;
+    await ensureSchema(store);
+    const rows = await store.query(`UPDATE users SET active_org_id = $2
+     WHERE id = $1 AND EXISTS (SELECT 1 FROM members WHERE user_id = $1 AND org_id = $2)
+     RETURNING id`, [userId, orgId]);
+    return rows.length > 0;
+}
+/** Record that the user followed the verification link. Idempotent. Null if the user is gone. */
+export async function markVerified(id, store = db()) {
+    if (!UUID.test(id))
+        return null;
+    await ensureSchema(store);
+    const rows = await store.query(`UPDATE users SET email_verified_at = COALESCE(email_verified_at, now()) WHERE id = $1 RETURNING id, email`, [id]);
+    return rows[0] ?? null;
 }
 /** Revoke every session of this user. False if there is no such user. */
-export async function revokeSessions(email) {
-    await ensureSchema();
-    const rows = (await sql() `
-    UPDATE auth_users SET session_epoch = session_epoch + 1 WHERE email = ${email} RETURNING id
-  `);
+export async function revokeSessions(email, store = db()) {
+    await ensureSchema(store);
+    const rows = await store.query(`UPDATE users SET session_epoch = session_epoch + 1 WHERE email = $1 RETURNING id`, [norm(email)]);
     return rows.length > 0;
 }
 /** Delete the user. Their sessions die with the row. False if none. */
-export async function removeUser(email) {
-    await ensureSchema();
-    const rows = (await sql() `
-    DELETE FROM auth_users WHERE email = ${email} RETURNING id
-  `);
+export async function removeUser(email, store = db()) {
+    await ensureSchema(store);
+    const rows = await store.query(`DELETE FROM users WHERE email = $1 RETURNING id`, [norm(email)]);
     return rows.length > 0;
 }
-export async function countUsers() {
-    await ensureSchema();
-    const [row] = (await sql() `SELECT COUNT(*)::int AS n FROM auth_users`);
-    return row.n;
+export async function countUsers(store = db()) {
+    await ensureSchema(store);
+    const [row] = await store.query(`SELECT COUNT(*)::int AS n FROM users`);
+    return Number(row.n);
 }
-export async function listUsers() {
-    await ensureSchema();
-    return (await sql() `
-    SELECT id, email, created_at FROM auth_users ORDER BY created_at
-  `);
+export async function listUsers(store = db()) {
+    await ensureSchema(store);
+    return store.query(`SELECT id, email, created_at FROM users ORDER BY created_at`);
 }
 /** Change a password. Also revokes every session, old password's included. */
-export async function setPassword(email, passwordHash) {
-    await ensureSchema();
-    const rows = (await sql() `
-    UPDATE auth_users
-    SET password_hash = ${passwordHash}, session_epoch = session_epoch + 1
-    WHERE email = ${email} RETURNING id
-  `);
+export async function setPassword(email, passwordHash, store = db()) {
+    await ensureSchema(store);
+    const rows = await store.query(`UPDATE users
+     SET password_hash = $2, session_epoch = session_epoch + 1
+     WHERE email = $1 RETURNING id`, [norm(email), passwordHash]);
     return rows.length > 0;
 }
+/**
+ * Same, by id, for a reset link. Also marks the email verified: following
+ * the link proved the address. Returns the user with the new epoch so the
+ * caller can sign them in; null if the user is gone.
+ */
+export async function setPasswordById(id, passwordHash, store = db()) {
+    if (!UUID.test(id))
+        return null;
+    await ensureSchema(store);
+    const rows = await store.query(`UPDATE users
+     SET password_hash = $2, session_epoch = session_epoch + 1,
+         email_verified_at = COALESCE(email_verified_at, now())
+     WHERE id = $1 RETURNING id, email, session_epoch AS epoch`, [id, passwordHash]);
+    return rows[0] ?? null;
+}
 export { TABLE };

package/dist/core/email.d.ts

@@ -0,0 +1,49 @@
+import { type EmailOptions } from "./options.ts";
+export type EmailMessage = {
+    to: string;
+    subject: string;
+    text: string;
+    html?: string;
+};
+/** What sendEmail needs: the email options plus whether this is production */
+export type EmailConfig = EmailOptions & {
+    production: boolean;
+};
+export type Transport = "gmail" | "resend" | "console" | "none";
+export declare const RESEND_URL = "https://api.resend.com/emails";
+export declare const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
+export declare const GMAIL_SEND_URL = "https://gmail.googleapis.com/gmail/v1/users/me/messages/send";
+export declare const GMAIL_SCOPE = "https://www.googleapis.com/auth/gmail.send";
+export declare const EMAIL_NOT_CONFIGURED = "Email is not configured. In b17_auth.yaml set email.gmail (user + clientEmail + privateKey) or email.resend (apiKey) + email.from (run: npx @binary1702/auth).";
+/** Which way a message goes. Gmail wins when both are configured. Pure. */
+export declare function emailTransport(cfg: EmailConfig): Transport;
+/** RFC 2047 for a header that may hold non-ASCII (a subject with an accent) */
+export declare function encodeHeader(value: string): string;
+/**
+ * A From/To value as the header needs it. `Name <addr>` keeps the name
+ * quoted when it holds characters that mean something in a header
+ * (parentheses, commas, colons, …) and RFC 2047-encoded when it is not
+ * ASCII. A bare address passes through. Pure.
+ */
+export declare function formatAddress(value: string): string;
+/** The request Resend expects. Pure. */
+export declare function resendRequest(msg: EmailMessage, cfg: EmailConfig): {
+    url: string;
+    init: RequestInit;
+};
+/** The raw RFC 2822 message Gmail wants, base64url-encoded. Pure. */
+export declare function gmailRaw(msg: EmailMessage, from: string, replyTo?: string): string;
+type Gmail = NonNullable<EmailOptions["gmail"]>;
+/** The service account's email and PEM key (client_email and private_key in the JSON Google hands out) */
+export declare function serviceAccount(gmail: Gmail): {
+    email: string;
+    key: string;
+};
+/** The signed assertion for a service account acting as the mailbox user (domain-wide delegation). */
+export declare function serviceAccountAssertion(gmail: Gmail, now?: Date): Promise<string>;
+/** The token request body, either grant. */
+export declare function gmailTokenRequest(gmail: Gmail): Promise<URLSearchParams>;
+/** Forget cached tokens (tests, or after rotating credentials). */
+export declare function resetGmailTokens(): void;
+export declare function sendEmail(msg: EmailMessage, cfg?: EmailConfig, fetchFn?: typeof fetch, log?: (line: string) => void): Promise<void>;
+export {};