feat: continue restart plan

Author: gustavotoyota

new-deepnotes/PLAN_PROGRESS.md

@@ -31,6 +31,15 @@ Living checklist for the greenfield work described in [docs/RESTART_PLAN.md](../
 
 ## Phase 3 checklist (REST + Drizzle)
 
+### Test coverage (Phase 3 account surface)
+
+- [x] **Rate limit:** failed login counters (`login-rate-limit.test.ts`).
+- [x] **Email crypto:** `encryptUserEmail` / `decryptUserEmail` + `hashUserEmail` (legacy parity cases).
+- [x] **Email change mailer:** `sendEmailChangeVerificationEmail` (dev skip, missing API key, Resend errors/success via mocked `fetch`).
+- [x] **HTTP contracts:** OpenAPI path presence; Zod for `userEmailChange*`, password change byte fields (`schemas/users.test.ts`).
+- [x] **Worker smoke:** `503` when env/DB not configured for `/api/users/me/email-change` (+ confirm), alongside other session routes.
+- [ ] **DB integration:** register → email-change request/confirm (or password change) against **template DB** with real `perform*` + minimal fixtures.
+
 ### Sessions + account (current)
 
 - [x] Document **sessions** REST paths + request schemas in OpenAPI; demo + `users/me` contracts updated.
@@ -102,6 +111,18 @@ Cross-cutting work so the new SPA does not repeat **legacy `apps/client`** patte
 - [ ] **Contract tests** for the fetch wrapper (MSW or recorded OpenAPI fixtures)—optional until multiple features consume the API.
 - [ ] **E2E smoke** (Playwright recommended): login or session refresh with **httpOnly cookies** against **local compose** or **Cloudflare preview**—add CI job when stable enough (can start `manual`/`workflow_dispatch` if cost is a concern).
 
+#### Automated tests — package matrix (maintenance)
+
+| Package / app | Role | What runs today | Gaps (highest value next) |
+|---------------|------|------------------|---------------------------|
+| **`@deepnotes/db`** | Drizzle + migrations | `template-db.test.ts`: clone template DB, smoke SQL | More assertions on FKs / critical columns after schema grows |
+| **`@deepnotes/session`** | Auth, account, crypto orchestration | `login-rate-limit.test.ts` (Redis port in memory); **`encrypt-user-email.test.ts`** (round-trip, case exceptions, tamper); **`email-hash.test.ts`** (stability, secret sensitivity, exceptions); **`send-email-change-code.test.ts`** (SEND_EMAILS=false no fetch, missing key **503**, Resend **502**/OK) | **Integration:** `performUserRegister`, login, password/email change against **template DB** + mocked Redis; JWT cookie helpers |
+| **`@deepnotes/api`** | Zod + OpenAPI | `openapi.test.ts` (health + route registry); **`schemas/users.test.ts`** (email/password change bodies, 6-digit code) | Schemas for sessions + remaining routes; optional **snapshot** of OpenAPI fragment for drift |
+| **`@deepnotes/api-worker`** | Hono on Worker | `index.test.ts`: health, OpenAPI JSON, **503** when secrets/DB not bound (incl. email-change paths) | **200-path tests** with test `SessionEnv` + Hyperdrive stub + template DB (heavier CI job) |
+| **`@deepnotes/web`** | SPA | `app.test.ts` (mount `App.vue`) | Auth UI + API client as in §5.8 |
+
+**Principle:** keep **fast unit tests** on pure crypto, Zod, and mail/HTTP branches; add **Postgres-backed** flows incrementally (same template pattern as `@deepnotes/db`) so Phase 3 routes do not regress silently.
+
 ### Progress vs legacy (reference only)
 
 | Legacy (`apps/client`) | New (`new-deepnotes/apps/web`) |
@@ -119,7 +140,7 @@ Cross-cutting work so the new SPA does not repeat **legacy `apps/client`** patte
 - [ ] Cold API dev start under **2 s** (no `inspect-brk` by default) — validate on a typical laptop.
 - [ ] Collab + realtime: at least one integration test each (Redis + deps).
 - [x] SQL-heavy paths: real Postgres tests; prefer **template DB** cloning (§5.7) — `@deepnotes/db` template test.
-- [ ] Auth, crypto, Stripe: automated coverage beyond smoke; **no** generic repository layer (§5.0).
+- [ ] Auth, crypto, Stripe: automated coverage beyond smoke; **no** generic repository layer (§5.0). **Progress:** crypto email path (`encrypt-user-email`, `email-hash`), Resend branch behavior, and **user** Zod bodies are covered in Vitest; session **perform\*** flows still need DB integration tests.
 - [x] No tRPC / superjson / RevenueCat / key-rotation in **this** tree (keep absent); product sign-off for IAP/Stripe when billing ships.
 - [x] Client: zero undocumented forks, or a short owned exception list — see [docs/CLIENT_FORKS.md](./docs/CLIENT_FORKS.md).
 - [ ] Cloudflare: deploy runbook; Hyperdrive + Postgres + Redis proven in staging; collab/realtime topology chosen and load-tested.
@@ -138,6 +159,7 @@ Use this when resuming: **(done)** account HTTP surface through email change inc
 
 | Date | Change |
 |------|--------|
+| 2026-04-26 | **Tests:** `@deepnotes/session` — `encrypt-user-email.test.ts`, `email-hash.test.ts`, `send-email-change-code.test.ts`; `@deepnotes/api` — `schemas/users.test.ts`; api-worker — email-change routes in `503` matrix; PLAN_PROGRESS — package test matrix + Phase 3 test checklist. |
 | 2026-04-26 | Phase 3: **email change** — `POST /api/users/me/email-change` + `…/confirm` (`change-user-email.ts`, `decryptUserEmail`, `send-email-change-code`); `userEmailChange*Request` schemas, OpenAPI, Hono; TRPC_REST_MAP; PLAN_PROGRESS detail + suggested Phase 3 order. |
 | 2026-04-26 | Phase 3: **`POST /api/users/me/password`** — `performUserPasswordChange` (`change-user-password.ts`): old password verify, demo **403**, new keyrings + PHC, invalidate all `sessions`, clear cookies **204**; `userPasswordChangeRequestSchema`, OpenAPI + worker; export **`byteB64`** from `@deepnotes/api`; TRPC_REST_MAP rows for change-password; PLAN_PROGRESS Phase 3 account section expanded. |
 | 2026-04-26 | Phase 2 + §5.8: `@deepnotes/web` — Vitest + happy-dom + `@vue/test-utils`, `vite.config` from `vitest/config`, `src/app.test.ts`; Phase 3: `DELETE /api/users/me` + `performUserAccountDelete` (ownership guard, Drizzle tx, clear cookies); `userAccountDeleteRequestSchema` + OpenAPI; api-worker route; TRPC_REST_MAP note on delete body / Stripe hook. |

new-deepnotes/apps/api-worker/src/index.test.ts

@@ -32,6 +32,8 @@ describe("api-worker", () => {
     ["DELETE", "/api/users/me"],
     ["POST", "/api/users"],
     ["POST", "/api/users/email-verification/resend"],
+    ["POST", "/api/users/me/email-change"],
+    ["POST", "/api/users/me/email-change/confirm"],
   ] as const)("returns 503 for %s %s when auth env is not configured", async (method, path) => {
     const res = await app.request(`http://test${path}`, { method });
     expect(res.status).toBe(503);

new-deepnotes/packages/api/src/schemas/users.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  userEmailChangeConfirmRequestSchema,
+  userEmailChangeRequestSchema,
+  userPasswordChangeRequestSchema,
+} from "./users.js";
+
+const oneByteB64 = Buffer.from([0xab]).toString("base64");
+
+describe("user request schemas (REST body validation)", () => {
+  it("userEmailChangeRequestSchema accepts byte fields and email", () => {
+    const parsed = userEmailChangeRequestSchema.parse({
+      oldLoginHash: oneByteB64,
+      newEmail: "new@example.com",
+    });
+    expect(parsed.oldLoginHash).toEqual(new Uint8Array([0xab]));
+    expect(parsed.newEmail).toBe("new@example.com");
+  });
+
+  it("userEmailChangeConfirmRequestSchema requires six-digit code", () => {
+    const body = {
+      oldLoginHash: oneByteB64,
+      emailVerificationCode: "042069",
+      newLoginHash: Buffer.from([1]).toString("base64"),
+      userEncryptedPrivateKeyring: Buffer.from([2]).toString("base64"),
+      userEncryptedSymmetricKeyring: Buffer.from([3]).toString("base64"),
+    };
+    const ok = userEmailChangeConfirmRequestSchema.parse(body);
+    expect(ok.emailVerificationCode).toBe("042069");
+    expect(() =>
+      userEmailChangeConfirmRequestSchema.parse({
+        ...body,
+        emailVerificationCode: "12345",
+      }),
+    ).toThrow();
+  });
+
+  it("userPasswordChangeRequestSchema decodes all byte fields", () => {
+    const a = Buffer.from("aa", "utf8").toString("base64");
+    const b = Buffer.from("bb", "utf8").toString("base64");
+    const c = Buffer.from("cc", "utf8").toString("base64");
+    const d = Buffer.from("dd", "utf8").toString("base64");
+    const p = userPasswordChangeRequestSchema.parse({
+      oldLoginHash: a,
+      newLoginHash: b,
+      userEncryptedPrivateKeyring: c,
+      userEncryptedSymmetricKeyring: d,
+    });
+    expect(new TextDecoder().decode(p.oldLoginHash)).toBe("aa");
+    expect(new TextDecoder().decode(p.newLoginHash)).toBe("bb");
+  });
+});

new-deepnotes/packages/session/src/email-hash.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+
+import { hashUserEmail } from "./email-hash.js";
+
+describe("hashUserEmail", () => {
+  it("is stable for the same normalized email and secret", async () => {
+    const secret = "test-email-hmac-secret";
+    const exceptions = "";
+    const a = await hashUserEmail("MixEd@Case.com", secret, exceptions);
+    const b = await hashUserEmail("mixed@case.com", secret, exceptions);
+    expect(Buffer.from(a).equals(Buffer.from(b))).toBe(true);
+  });
+
+  it("differs when the secret differs", async () => {
+    const exceptions = "";
+    const h1 = await hashUserEmail("same@x.co", "secret-a", exceptions);
+    const h2 = await hashUserEmail("same@x.co", "secret-b", exceptions);
+    expect(Buffer.from(h1).equals(Buffer.from(h2))).toBe(false);
+  });
+
+  it("respects case-sensitivity exceptions like encryptUserEmail", async () => {
+    const secret = "s";
+    const ex = "Special@X.co";
+    const hPreserve = await hashUserEmail("Special@X.co", secret, ex);
+    const hLower = await hashUserEmail("special@x.co", secret, ex);
+    expect(Buffer.from(hPreserve).equals(Buffer.from(hLower))).toBe(false);
+  });
+});

new-deepnotes/packages/session/src/encrypt-user-email.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it, beforeAll } from "vitest";
+
+import { ensureSodiumReady } from "./crypto/session-crypto.js";
+import { decryptUserEmail, encryptUserEmail } from "./encrypt-user-email.js";
+
+/** 32-byte XChaCha key as standard base64 */
+const TEST_KEY_B64 = Buffer.alloc(32, 9).toString("base64");
+
+describe("encryptUserEmail / decryptUserEmail", () => {
+  beforeAll(async () => {
+    await ensureSodiumReady();
+  });
+
+  it("round-trips and lowercases by default", () => {
+    const email = "User@Example.COM";
+    const ct = encryptUserEmail(email, TEST_KEY_B64, "");
+    const out = decryptUserEmail(ct, TEST_KEY_B64, "");
+    expect(out).toBe("user@example.com");
+  });
+
+  it("preserves casing for addresses in EMAIL_CASE_SENSITIVITY_EXCEPTIONS", () => {
+    const email = "PreserveCase@X.org";
+    const exceptions = "PreserveCase@X.org";
+    const ct = encryptUserEmail(email, TEST_KEY_B64, exceptions);
+    const out = decryptUserEmail(ct, TEST_KEY_B64, exceptions);
+    expect(out).toBe("PreserveCase@X.org");
+  });
+
+  it("rejects tampered ciphertext", () => {
+    const ct = encryptUserEmail("a@b.co", TEST_KEY_B64, "");
+    const tampered = new Uint8Array(ct);
+    tampered[0] = (tampered[0] ?? 0) ^ 0xff;
+    expect(() => decryptUserEmail(tampered, TEST_KEY_B64, "")).toThrow();
+  });
+});

new-deepnotes/packages/session/src/send-email-change-code.test.ts

@@ -0,0 +1,108 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type { SessionEnv } from "./env.js";
+import { sendEmailChangeVerificationEmail } from "./send-email-change-code.js";
+
+function minimalEnv(
+  overrides: Partial<Pick<SessionEnv, "SEND_EMAILS" | "RESEND_API_KEY">>,
+): SessionEnv {
+  return {
+    ACCESS_SECRET: "a",
+    REFRESH_SECRET: "b",
+    USER_EMAIL_SECRET: "c",
+    USER_EMAIL_ENCRYPTION_KEY: Buffer.alloc(32, 1).toString("base64"),
+    USER_REHASHED_LOGIN_HASH_ENCRYPTION_KEY: Buffer.alloc(32, 2).toString(
+      "base64",
+    ),
+    USER_AUTHENTICATOR_SECRET_ENCRYPTION_KEY: Buffer.alloc(32, 3).toString(
+      "base64",
+    ),
+    USER_RECOVERY_CODES_ENCRYPTION_KEY: Buffer.alloc(32, 4).toString("base64"),
+    ...overrides,
+  };
+}
+
+describe("sendEmailChangeVerificationEmail", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("no-ops when SEND_EMAILS is false (no Resend, no fetch)", async () => {
+    const fetchSpy = vi.spyOn(globalThis, "fetch");
+    await sendEmailChangeVerificationEmail({
+      env: minimalEnv({ SEND_EMAILS: "false" }),
+      toEmail: "u@x.co",
+      emailVerificationCode: "123456",
+    });
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("throws 503 when outbound email is enabled but RESEND_API_KEY is missing", async () => {
+    await expect(
+      sendEmailChangeVerificationEmail({
+        env: minimalEnv({ SEND_EMAILS: "true", RESEND_API_KEY: undefined }),
+        toEmail: "u@x.co",
+        emailVerificationCode: "000000",
+      }),
+    ).rejects.toMatchObject({
+      name: "SessionError",
+      status: 503,
+      code: "SERVICE_UNAVAILABLE",
+    });
+  });
+
+  it("throws 503 when RESEND_API_KEY is whitespace only", async () => {
+    await expect(
+      sendEmailChangeVerificationEmail({
+        env: minimalEnv({
+          SEND_EMAILS: "true",
+          RESEND_API_KEY: "   \t",
+        }),
+        toEmail: "u@x.co",
+        emailVerificationCode: "000000",
+      }),
+    ).rejects.toMatchObject({ status: 503 });
+  });
+
+  it("throws 502 when Resend returns non-OK", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response("bad", { status: 422 }),
+    );
+    await expect(
+      sendEmailChangeVerificationEmail({
+        env: minimalEnv({
+          SEND_EMAILS: "true",
+          RESEND_API_KEY: "re_test",
+        }),
+        toEmail: "u@x.co",
+        emailVerificationCode: "654321",
+      }),
+    ).rejects.toMatchObject({
+      status: 502,
+      code: "EMAIL_SEND_FAILED",
+    });
+  });
+
+  it("resolves when Resend returns OK", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("", { status: 200 }));
+    await expect(
+      sendEmailChangeVerificationEmail({
+        env: minimalEnv({
+          SEND_EMAILS: "true",
+          RESEND_API_KEY: "re_ok",
+        }),
+        toEmail: "user@example.com",
+        emailVerificationCode: "111222",
+      }),
+    ).resolves.toBeUndefined();
+    expect(fetch).toHaveBeenCalledWith(
+      "https://api.resend.com/emails",
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({
+          Authorization: "Bearer re_ok",
+        }),
+      }),
+    );
+  });
+});