@mandujs/core 0.21.0 → 0.22.0

package/src/auth/__tests__/password.test.ts

@@ -0,0 +1,122 @@
+/**
+ * @mandujs/core/auth/password tests
+ *
+ * These tests exercise real argon2id and bcrypt hashing through `Bun.password`.
+ * They are CPU-bound (~50-200ms per hash op on laptop hardware); the suite
+ * uses the minimum cost parameters Bun accepts whenever the test does not
+ * care about actual KDF strength. Total runtime ~2-5s is expected.
+ */
+
+import { describe, it, expect } from "bun:test";
+import { hashPassword, verifyPassword } from "../password";
+
+// Argon2 hashes start with "$argon2id$", "$argon2d$", or "$argon2i$".
+const ARGON2ID_PREFIX = "$argon2id$";
+// bcrypt hashes use $2a$/$2b$/$2y$ prefixes; Bun emits $2b$.
+const BCRYPT_PREFIX_RE = /^\$2[aby]\$/;
+
+// Minimum argon2 cost params — keep tests fast without changing behavior.
+const FAST_ARGON2 = {
+  algorithm: "argon2id",
+  memoryCost: 4,
+  timeCost: 2,
+} as const;
+
+describe("@mandujs/core/auth/password — hashPassword", () => {
+  it("produces an argon2id hash by default", async () => {
+    const h = await hashPassword("hunter2", FAST_ARGON2);
+    expect(h.startsWith(ARGON2ID_PREFIX)).toBe(true);
+  });
+
+  it("produces a bcrypt hash when algorithm=bcrypt is requested", async () => {
+    const h = await hashPassword("hunter2", { algorithm: "bcrypt", cost: 4 });
+    expect(h).toMatch(BCRYPT_PREFIX_RE);
+  });
+
+  it("throws on empty plaintext", async () => {
+    await expect(hashPassword("", FAST_ARGON2)).rejects.toThrow(
+      /non-empty string/,
+    );
+  });
+
+  it("throws when bcrypt input exceeds 72 bytes", async () => {
+    // 73 ASCII bytes (each char = 1 UTF-8 byte).
+    const tooLong = "a".repeat(73);
+    await expect(
+      hashPassword(tooLong, { algorithm: "bcrypt", cost: 4 }),
+    ).rejects.toThrow(/72-byte limit/);
+  });
+
+  it("accepts >72-byte input when using argon2id (bcrypt-only limit)", async () => {
+    const longButFine = "a".repeat(100);
+    const h = await hashPassword(longButFine, FAST_ARGON2);
+    expect(h.startsWith(ARGON2ID_PREFIX)).toBe(true);
+  });
+
+  it("counts UTF-8 bytes (not code points) when enforcing the bcrypt limit", async () => {
+    // "é" is 2 bytes in UTF-8 — 40 of them = 80 bytes, over the 72 limit.
+    const multibyte = "é".repeat(40);
+    await expect(
+      hashPassword(multibyte, { algorithm: "bcrypt", cost: 4 }),
+    ).rejects.toThrow(/72-byte limit/);
+  });
+
+  it("honors non-default argon2 timeCost via option pass-through", async () => {
+    // Bun embeds the cost parameters in the hash string:
+    //   $argon2id$v=19$m=<memoryCost>,t=<timeCost>,p=1$<salt>$<hash>
+    // We assert the timeCost is preserved end-to-end.
+    const h = await hashPassword("same-password", {
+      algorithm: "argon2id",
+      memoryCost: 4,
+      timeCost: 3,
+    });
+    expect(h).toMatch(/\$argon2id\$v=\d+\$m=4,t=3,p=\d+\$/);
+  });
+});
+
+describe("@mandujs/core/auth/password — verifyPassword", () => {
+  it("returns true for a matching argon2id roundtrip", async () => {
+    const h = await hashPassword("correct-horse-battery-staple", FAST_ARGON2);
+    const ok = await verifyPassword("correct-horse-battery-staple", h);
+    expect(ok).toBe(true);
+  });
+
+  it("returns true for a matching bcrypt roundtrip", async () => {
+    const h = await hashPassword("correct-horse-battery-staple", {
+      algorithm: "bcrypt",
+      cost: 4,
+    });
+    const ok = await verifyPassword("correct-horse-battery-staple", h);
+    expect(ok).toBe(true);
+  });
+
+  it("returns false for wrong plaintext", async () => {
+    const h = await hashPassword("correct", FAST_ARGON2);
+    expect(await verifyPassword("incorrect", h)).toBe(false);
+  });
+
+  it("returns false for a tampered hash (one char mutated)", async () => {
+    const h = await hashPassword("correct", FAST_ARGON2);
+    // Flip the last character of the base64 hash segment.
+    const last = h.charAt(h.length - 1);
+    const replacement = last === "A" ? "B" : "A";
+    const tampered = h.slice(0, -1) + replacement;
+    expect(tampered).not.toBe(h);
+    expect(await verifyPassword("correct", tampered)).toBe(false);
+  });
+
+  it("returns false (never throws) for a malformed hash string", async () => {
+    // Bun.password.verify throws on unparseable hashes; our wrapper collapses
+    // every failure mode to `false` so login handlers stay branchless.
+    expect(await verifyPassword("anything", "not-a-hash")).toBe(false);
+  });
+
+  it("returns false for empty plaintext", async () => {
+    const h = await hashPassword("correct", FAST_ARGON2);
+    expect(await verifyPassword("", h)).toBe(false);
+  });
+
+  it("returns false for empty hash", async () => {
+    expect(await verifyPassword("correct", "")).toBe(false);
+  });
+});

package/src/auth/__tests__/reset.test.ts

@@ -0,0 +1,296 @@
+/**
+ * @mandujs/core/auth/reset — flow tests.
+ *
+ * Cover `createPasswordReset` end-to-end: mint + send via in-memory email,
+ * consume + onReset via `hashPassword`. The KDF hot path is CPU-bound —
+ * we pass minimal argon2id cost parameters everywhere to keep wall-clock
+ * time short.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
+
+import { createMemoryEmailSender, type MemoryEmailSender } from "../../email";
+import { verifyPassword } from "../password";
+import { createAuthTokenStore, type AuthTokenStore } from "../tokens";
+import { createPasswordReset } from "../reset";
+
+// ─── Gate on Bun.SQL + CryptoHasher + Bun.password ──────────────────────────
+
+const hasBun = (() => {
+  const g = globalThis as unknown as {
+    Bun?: { SQL?: unknown; CryptoHasher?: unknown; password?: unknown };
+  };
+  return (
+    typeof g.Bun?.SQL === "function" &&
+    typeof g.Bun?.CryptoHasher === "function" &&
+    g.Bun?.password !== undefined
+  );
+})();
+const describeIfBun = hasBun ? describe : describe.skip;
+
+// ─── Fixtures ───────────────────────────────────────────────────────────────
+
+const SECRET = "reset-flow-test-secret-32-bytes-or-more!!";
+const URL_TEMPLATE = "https://app.example.com/reset?token={token}";
+const FROM = "noreply@example.com";
+const ARGON2ID_PREFIX = "$argon2id$";
+const FAST_ARGON2 = { algorithm: "argon2id", memoryCost: 4, timeCost: 2 } as const;
+
+interface Fixture {
+  store: AuthTokenStore;
+  sender: MemoryEmailSender;
+  onResetCalls: Array<{ userId: string; newHash: string }>;
+}
+
+function makeFixture(): Fixture {
+  return {
+    store: createAuthTokenStore({
+      secret: SECRET,
+      dbPath: ":memory:",
+      gcSchedule: false,
+    }),
+    sender: createMemoryEmailSender(),
+    onResetCalls: [],
+  };
+}
+
+describeIfBun("@mandujs/core/auth/reset — createPasswordReset", () => {
+  let fx: Fixture;
+
+  beforeEach(() => {
+    fx = makeFixture();
+  });
+
+  afterEach(async () => {
+    await fx.store.close();
+  });
+
+  it("send() mints a reset token and dispatches an email with the link", async () => {
+    const renderEmail = mock(({ url }: { url: string }) => ({
+      subject: "Reset your password",
+      html: `<a href="${url}">reset</a>`,
+    }));
+    const reset = createPasswordReset({
+      store: fx.store,
+      sender: fx.sender,
+      fromAddress: FROM,
+      resetUrlTemplate: URL_TEMPLATE,
+      renderEmail,
+      passwordOptions: FAST_ARGON2,
+      onReset: async (args) => {
+        fx.onResetCalls.push(args);
+      },
+    });
+
+    await reset.send("u-1", "alice@example.com");
+    expect(fx.sender.sent).toHaveLength(1);
+    const msg = fx.sender.sent[0]!;
+    expect(msg.from).toBe(FROM);
+    expect(msg.to).toBe("alice@example.com");
+    expect(msg.subject).toBe("Reset your password");
+    expect(msg.html).toContain("https://app.example.com/reset?token=");
+  });
+
+  it("consume(validToken, newPassword) returns { userId } and calls onReset with an argon2id hash", async () => {
+    const reset = createPasswordReset({
+      store: fx.store,
+      sender: fx.sender,
+      fromAddress: FROM,
+      resetUrlTemplate: URL_TEMPLATE,
+      renderEmail: ({ url }) => ({ subject: "R", html: `<a href="${url}">r</a>` }),
+      passwordOptions: FAST_ARGON2,
+      onReset: async (args) => {
+        fx.onResetCalls.push(args);
+      },
+    });
+
+    await reset.send("u-2", "bob@example.com");
+    const token = extractTokenFromUrl(fx.sender.sent[0]!.html!)!;
+
+    const result = await reset.consume(token, "newPass123");
+    expect(result).toEqual({ userId: "u-2" });
+    expect(fx.onResetCalls).toHaveLength(1);
+    expect(fx.onResetCalls[0]!.userId).toBe("u-2");
+    expect(fx.onResetCalls[0]!.newHash.startsWith(ARGON2ID_PREFIX)).toBe(true);
+  });
+
+  it("empty newPassword throws TypeError without consuming the token", async () => {
+    const reset = createPasswordReset({
+      store: fx.store,
+      sender: fx.sender,
+      fromAddress: FROM,
+      resetUrlTemplate: URL_TEMPLATE,
+      renderEmail: ({ url }) => ({ subject: "R", html: `<a href="${url}">r</a>` }),
+      passwordOptions: FAST_ARGON2,
+      onReset: async () => {},
+    });
+
+    await reset.send("u-3", "carol@example.com");
+    const token = extractTokenFromUrl(fx.sender.sent[0]!.html!)!;
+
+    await expect(reset.consume(token, "")).rejects.toThrow(/non-empty/);
+    // Token was NOT consumed — a real call still works.
+    const ok = await reset.consume(token, "validPass123");
+    expect(ok).toEqual({ userId: "u-3" });
+  });
+
+  it("onReset receives the hash, not the plaintext password", async () => {
+    let captured: { userId: string; newHash: string } | null = null;
+    const reset = createPasswordReset({
+      store: fx.store,
+      sender: fx.sender,
+      fromAddress: FROM,
+      resetUrlTemplate: URL_TEMPLATE,
+      renderEmail: ({ url }) => ({ subject: "R", html: `<a href="${url}">r</a>` }),
+      passwordOptions: FAST_ARGON2,
+      onReset: async (args) => {
+        captured = args;
+      },
+    });
+    await reset.send("u-4", "dave@example.com");
+    const token = extractTokenFromUrl(fx.sender.sent[0]!.html!)!;
+
+    const plaintext = "totally-secret-password";
+    await reset.consume(token, plaintext);
+
+    expect(captured).not.toBeNull();
+    const hash = captured!.newHash;
+    // The plaintext must NEVER appear in the hash payload.
+    expect(hash).not.toContain(plaintext);
+    // verifyPassword round-trips correctly against the hash.
+    expect(await verifyPassword(plaintext, hash)).toBe(true);
+    expect(await verifyPassword("wrong-password", hash)).toBe(false);
+  });
+
+  it("reusing a consumed token returns null and onReset fires exactly once", async () => {
+    const reset = createPasswordReset({
+      store: fx.store,
+      sender: fx.sender,
+      fromAddress: FROM,
+      resetUrlTemplate: URL_TEMPLATE,
+      renderEmail: ({ url }) => ({ subject: "R", html: `<a href="${url}">r</a>` }),
+      passwordOptions: FAST_ARGON2,
+      onReset: async (args) => {
+        fx.onResetCalls.push(args);
+      },
+    });
+    await reset.send("u-5", "eve@example.com");
+    const token = extractTokenFromUrl(fx.sender.sent[0]!.html!)!;
+
+    const first = await reset.consume(token, "first-pass");
+    expect(first).not.toBeNull();
+    const second = await reset.consume(token, "second-pass");
+    expect(second).toBeNull();
+    expect(fx.onResetCalls).toHaveLength(1);
+  });
+
+  it("reset does NOT auto-login — we don't touch sessions", async () => {
+    // This test guards the contract: the returned shape is `{ userId }`
+    // only — there are no cookie side-effects, no session helpers called.
+    // We construct the flow with NO session storage at all and expect
+    // consume() to still succeed.
+    const reset = createPasswordReset({
+      store: fx.store,
+      sender: fx.sender,
+      fromAddress: FROM,
+      resetUrlTemplate: URL_TEMPLATE,
+      renderEmail: ({ url }) => ({ subject: "R", html: `<a href="${url}">r</a>` }),
+      passwordOptions: FAST_ARGON2,
+      onReset: async () => {},
+    });
+    await reset.send("u-6", "frank@example.com");
+    const token = extractTokenFromUrl(fx.sender.sent[0]!.html!)!;
+
+    const result = await reset.consume(token, "fresh-pass");
+    expect(result).toEqual({ userId: "u-6" });
+    // Contract: ReturnType<consume> is never {userId, cookie, session, …}.
+    // The runtime shape must match — if a future refactor adds fields we
+    // need to revisit the doc + this guard.
+    expect(Object.keys(result!).sort()).toEqual(["userId"]);
+  });
+
+  it("hashPassword is invoked with the raw plaintext (argon2id default)", async () => {
+    // Black-box: the only way to observe "hashPassword was called with
+    // this plaintext" without reaching past the module boundary is to
+    // verify the emitted hash authenticates the plaintext.
+    let newHash: string | null = null;
+    const reset = createPasswordReset({
+      store: fx.store,
+      sender: fx.sender,
+      fromAddress: FROM,
+      resetUrlTemplate: URL_TEMPLATE,
+      renderEmail: ({ url }) => ({ subject: "R", html: `<a href="${url}">r</a>` }),
+      passwordOptions: FAST_ARGON2,
+      onReset: async (args) => {
+        newHash = args.newHash;
+      },
+    });
+    await reset.send("u-7", "grace@example.com");
+    const token = extractTokenFromUrl(fx.sender.sent[0]!.html!)!;
+    await reset.consume(token, "plaintext-checked");
+
+    expect(newHash).not.toBeNull();
+    expect(newHash!.startsWith(ARGON2ID_PREFIX)).toBe(true);
+    expect(await verifyPassword("plaintext-checked", newHash!)).toBe(true);
+  });
+
+  it("bcrypt's 72-byte limit: hashPassword error propagates (token is already spent)", async () => {
+    const reset = createPasswordReset({
+      store: fx.store,
+      sender: fx.sender,
+      fromAddress: FROM,
+      resetUrlTemplate: URL_TEMPLATE,
+      renderEmail: ({ url }) => ({ subject: "R", html: `<a href="${url}">r</a>` }),
+      // Force bcrypt so the 72-byte guard in hashPassword fires.
+      passwordOptions: { algorithm: "bcrypt", cost: 4 },
+      onReset: async () => {
+        throw new Error("onReset should not be invoked when hashPassword throws");
+      },
+    });
+    await reset.send("u-8", "heidi@example.com");
+    const token = extractTokenFromUrl(fx.sender.sent[0]!.html!)!;
+
+    const tooLong = "a".repeat(100); // 100 UTF-8 bytes, over the 72 limit.
+    await expect(reset.consume(token, tooLong)).rejects.toThrow(/72-byte limit/);
+    // Token IS consumed by the time hashPassword throws — a retry returns null.
+    const retry = await reset.consume(token, "shortPass");
+    expect(retry).toBeNull();
+  });
+
+  it("resetUrlTemplate without {token} throws at create time", () => {
+    expect(() =>
+      createPasswordReset({
+        store: fx.store,
+        sender: fx.sender,
+        fromAddress: FROM,
+        resetUrlTemplate: "https://app.example.com/reset?nope=1",
+        renderEmail: () => ({ subject: "r", html: "<p>r</p>" }),
+        passwordOptions: FAST_ARGON2,
+        onReset: async () => {},
+      }),
+    ).toThrow(/\{token\}/);
+  });
+
+  it("empty fromAddress throws at create time", () => {
+    expect(() =>
+      createPasswordReset({
+        store: fx.store,
+        sender: fx.sender,
+        fromAddress: "",
+        resetUrlTemplate: URL_TEMPLATE,
+        renderEmail: () => ({ subject: "r", html: "<p>r</p>" }),
+        passwordOptions: FAST_ARGON2,
+        onReset: async () => {},
+      }),
+    ).toThrow(/fromAddress/);
+  });
+});
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function extractTokenFromUrl(html: string): string | null {
+  const hrefMatch = /href="([^"]+)"/.exec(html);
+  const url = hrefMatch ? hrefMatch[1]! : html;
+  const tokenMatch = /[?&]token=([^&"\s]+)/.exec(url);
+  return tokenMatch ? tokenMatch[1]! : null;
+}

package/src/auth/__tests__/tokens.test.ts

@@ -0,0 +1,274 @@
+/**
+ * @mandujs/core/auth/tokens — store tests.
+ *
+ * Each case builds a fresh `:memory:` store (gated on Bun.SQL availability)
+ * with `gcSchedule: false` so no real cron fires during tests. Closed in
+ * `afterEach`.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+
+import {
+  createAuthTokenStore,
+  type AuthTokenStore,
+  type TokenRecord,
+} from "../tokens";
+
+// ─── Gate on Bun.SQL + Bun.CryptoHasher ─────────────────────────────────────
+
+const hasBunSql = (() => {
+  const g = globalThis as unknown as {
+    Bun?: { SQL?: unknown; CryptoHasher?: unknown };
+  };
+  return typeof g.Bun?.SQL === "function" && typeof g.Bun?.CryptoHasher === "function";
+})();
+const describeIfBun = hasBunSql ? describe : describe.skip;
+
+// ─── Fixtures ───────────────────────────────────────────────────────────────
+
+const SECRET = "tokens-test-secret-at-least-32-bytes-long!";
+
+describeIfBun("@mandujs/core/auth/tokens — createAuthTokenStore", () => {
+  let store: AuthTokenStore;
+
+  beforeEach(() => {
+    store = createAuthTokenStore({
+      secret: SECRET,
+      dbPath: ":memory:",
+      gcSchedule: false,
+    });
+  });
+
+  afterEach(async () => {
+    await store.close();
+  });
+
+  it("mint → consume roundtrip returns the record with userId + purpose", async () => {
+    const { token, record } = await store.mint("verify-email", "u-1", {
+      email: "a@b.com",
+    });
+    expect(token).toContain(".");
+    expect(record.userId).toBe("u-1");
+    expect(record.purpose).toBe("verify-email");
+    expect(record.consumedAt).toBeNull();
+    expect(record.tokenHash).toMatch(/^[0-9a-f]{64}$/);
+
+    const consumed = await store.consume("verify-email", token);
+    expect(consumed).not.toBeNull();
+    expect(consumed!.userId).toBe("u-1");
+    expect(consumed!.id).toBe(record.id);
+    expect(consumed!.consumedAt).toBeTypeOf("number");
+    expect(consumed!.consumedAt).not.toBeNull();
+  });
+
+  it("consuming twice: second call returns null (single-use)", async () => {
+    const { token } = await store.mint("verify-email", "u-2", { email: "a@b.com" });
+    const first = await store.consume("verify-email", token);
+    expect(first).not.toBeNull();
+    const second = await store.consume("verify-email", token);
+    expect(second).toBeNull();
+  });
+
+  it("expired token returns null", async () => {
+    // Zero TTL means expires_at == now at insert. The insert completes at
+    // T, and consume() reads `now > T` → treated as expired. We sleep a
+    // few ms to be defensive against same-millisecond flakiness.
+    const shortLived = createAuthTokenStore({
+      secret: SECRET,
+      dbPath: ":memory:",
+      gcSchedule: false,
+      ttlSecondsByPurpose: { "verify-email": 0 },
+    });
+    try {
+      const { token } = await shortLived.mint("verify-email", "u-3");
+      await new Promise((r) => setTimeout(r, 5));
+      const result = await shortLived.consume("verify-email", token);
+      expect(result).toBeNull();
+    } finally {
+      await shortLived.close();
+    }
+  });
+
+  it("tampered nonce returns null (hash mismatch)", async () => {
+    const { token } = await store.mint("verify-email", "u-4");
+    const [id, nonce] = token.split(".");
+    // Flip one character in the nonce. Keep length the same to exercise
+    // the byte-wise hash compare (length mismatch would short-circuit).
+    const flipped = (nonce!.charAt(0) === "A" ? "B" : "A") + nonce!.slice(1);
+    const tampered = `${id}.${flipped}`;
+    const result = await store.consume("verify-email", tampered);
+    expect(result).toBeNull();
+  });
+
+  it("tampered id (pointing to real row) still returns null — hash mismatch", async () => {
+    const { token: a } = await store.mint("verify-email", "u-5a");
+    const { token: b } = await store.mint("verify-email", "u-5b");
+    const aNonce = a.split(".")[1]!;
+    const bId = b.split(".")[0]!;
+    // Forged token: use B's id with A's nonce. B's stored hash was
+    // computed against B's nonce, so the compare fails.
+    const forged = `${bId}.${aNonce}`;
+    const result = await store.consume("verify-email", forged);
+    expect(result).toBeNull();
+
+    // Sanity: the real B token still consumes cleanly afterwards. The
+    // forged attempt did NOT mark B as consumed.
+    const real = await store.consume("verify-email", b);
+    expect(real).not.toBeNull();
+  });
+
+  it("wrong purpose returns null (purpose binds to the hash)", async () => {
+    const { token } = await store.mint("verify-email", "u-6");
+    const result = await store.consume("reset-password", token);
+    expect(result).toBeNull();
+
+    // Real purpose still works — wrong-purpose attempt did NOT mark it
+    // consumed.
+    const real = await store.consume("verify-email", token);
+    expect(real).not.toBeNull();
+  });
+
+  it("unknown id returns null without touching other rows", async () => {
+    const { token } = await store.mint("verify-email", "u-7");
+    // Use a random UUID as the id so the row simply doesn't exist.
+    const fakeId = crypto.randomUUID();
+    const nonce = token.split(".")[1]!;
+    const bogus = `${fakeId}.${nonce}`;
+    const result = await store.consume("verify-email", bogus);
+    expect(result).toBeNull();
+
+    // Real token still usable.
+    const real = await store.consume("verify-email", token);
+    expect(real).not.toBeNull();
+  });
+
+  it("gcNow() sweeps expired + consumed rows and returns the count", async () => {
+    // Consume one row to create a "consumed" candidate.
+    const { token: consumedToken } = await store.mint("verify-email", "u-8a");
+    await store.consume("verify-email", consumedToken);
+
+    // Build a short-lived entry via a second store on the same (in-memory)
+    // semantics — we can't share a :memory: DB across handles, so mint
+    // into a different short-TTL store to prove the delete query works.
+    const expiring = createAuthTokenStore({
+      secret: SECRET,
+      dbPath: ":memory:",
+      gcSchedule: false,
+      ttlSecondsByPurpose: { "verify-email": 0 },
+    });
+    try {
+      await expiring.mint("verify-email", "u-8b");
+      await expiring.mint("verify-email", "u-8c");
+      await new Promise((r) => setTimeout(r, 5));
+      const deleted = await expiring.gcNow();
+      expect(deleted).toBe(2);
+      // Second sweep is a no-op.
+      expect(await expiring.gcNow()).toBe(0);
+    } finally {
+      await expiring.close();
+    }
+
+    // The original store has exactly one row (consumed); gcNow removes it.
+    const cleaned = await store.gcNow();
+    expect(cleaned).toBe(1);
+  });
+
+  it("meta round-trips as JSON for verify-email tokens", async () => {
+    const { token, record: minted } = await store.mint("verify-email", "u-9", {
+      email: "alice@example.com",
+      signupSource: "marketing-page",
+    });
+    expect(minted.meta?.email).toBe("alice@example.com");
+
+    const consumed = await store.consume("verify-email", token);
+    expect(consumed).not.toBeNull();
+    expect(consumed!.meta?.email).toBe("alice@example.com");
+    expect(consumed!.meta?.signupSource).toBe("marketing-page");
+  });
+
+  it("sequential consumes serialise through the UPDATE predicate — only the first wins", async () => {
+    // True wall-clock concurrency is not expressible against a single
+    // SQLite connection (Bun.SQL surfaces "cannot start a transaction
+    // within a transaction" when two callers share the handle). The
+    // atomicity guarantee we actually care about is observable
+    // sequentially: consume #2 must see `consumed_at IS NOT NULL` from
+    // consume #1's committed transaction and return null.
+    //
+    // The defense-in-depth `UPDATE … WHERE consumed_at IS NULL` predicate
+    // is what guards against a hypothetical interleaving if multiple
+    // writer connections ever land in the future (e.g., Postgres).
+    const { token } = await store.mint("verify-email", "u-10");
+    const a = await store.consume("verify-email", token);
+    const b = await store.consume("verify-email", token);
+    const successes: TokenRecord[] = [];
+    if (a) successes.push(a);
+    if (b) successes.push(b);
+    expect(successes).toHaveLength(1);
+    expect(a!.consumedAt).not.toBeNull();
+  });
+
+  it("malformed token (no dot) returns null without throwing", async () => {
+    // Exercise the `parseToken` no-dot path, the empty-string path, and
+    // the multi-dot path — all must collapse to null.
+    const nodot = await store.consume("verify-email", "not-a-token");
+    expect(nodot).toBeNull();
+
+    const empty = await store.consume("verify-email", "");
+    expect(empty).toBeNull();
+
+    const multiDot = await store.consume("verify-email", "a.b.c");
+    expect(multiDot).toBeNull();
+
+    const leadingDot = await store.consume("verify-email", ".nonce");
+    expect(leadingDot).toBeNull();
+
+    const trailingDot = await store.consume("verify-email", "id.");
+    expect(trailingDot).toBeNull();
+  });
+
+  it("close() then mint/consume/gcNow rejects with a clear error", async () => {
+    const tempStore = createAuthTokenStore({
+      secret: SECRET,
+      dbPath: ":memory:",
+      gcSchedule: false,
+    });
+    // Populate one row so gcNow has something to scan.
+    await tempStore.mint("verify-email", "u-11");
+    await tempStore.close();
+
+    await expect(tempStore.mint("verify-email", "u-12")).rejects.toThrow(
+      /store is closed/,
+    );
+    await expect(tempStore.consume("verify-email", "x.y")).rejects.toThrow(
+      /store is closed/,
+    );
+    await expect(tempStore.gcNow()).rejects.toThrow(/store is closed/);
+    // close() is idempotent.
+    await expect(tempStore.close()).resolves.toBeUndefined();
+  });
+
+  it("empty secret is rejected synchronously at construction", () => {
+    expect(() =>
+      createAuthTokenStore({ secret: "", dbPath: ":memory:", gcSchedule: false }),
+    ).toThrow(/secret/);
+  });
+
+  it("invalid table name is rejected synchronously at construction", () => {
+    expect(() =>
+      createAuthTokenStore({
+        secret: SECRET,
+        dbPath: ":memory:",
+        table: "bad-name; DROP TABLE users",
+        gcSchedule: false,
+      }),
+    ).toThrow(/table name/);
+  });
+
+  it("reset-password token consumed at the wrong purpose returns null", async () => {
+    const { token } = await store.mint("reset-password", "u-13");
+    const wrongPurpose = await store.consume("verify-email", token);
+    expect(wrongPurpose).toBeNull();
+    const rightPurpose = await store.consume("reset-password", token);
+    expect(rightPurpose).not.toBeNull();
+  });
+});