feat: continue restart plan

Author: gustavotoyota

new-deepnotes/PLAN_PROGRESS.md

@@ -13,7 +13,7 @@ Living checklist for the greenfield work described in [docs/RESTART_PLAN.md](../
 | **0** — OpenAPI + Drizzle inventory | **Done** | tRPC→REST/WS map: [docs/TRPC_REST_MAP.md](./docs/TRPC_REST_MAP.md). Drizzle + migration `0000_legacy_baseline` match `postgres-init.sql` core tables. Auth/CORS/forks: [docs/AUTH_AND_CORS.md](./docs/AUTH_AND_CORS.md), [docs/CLIENT_FORKS.md](./docs/CLIENT_FORKS.md). |
 | **1** — Legacy repo hygiene | **Optional / n/a** | Parallel track only if still editing the old monorepo. |
 | **2** — Repo bootstrap | **Mostly done** | Template DB integration test + CI `DATABASE_ADMIN_URL`; deploy doc: [docs/DEPLOY_CLOUDFLARE.md](./docs/DEPLOY_CLOUDFLARE.md). Optional: Wrangler deploy job. **Gap:** `apps/web` tests still no-op—see Phase 2 checklist + [Frontend / UI track](#frontend--ui-track). |
-| **3** — REST + Drizzle features | **In progress** | `POST /api/sessions/login|refresh|logout` + **`POST /api/sessions/demo`** + **`GET /api/users/me`** + **`POST /api/users`** (registration) via `@deepnotes/session`. Optional **Upstash** (`UPSTASH_REDIS_REST_*`) for failed-login limits; **`SEND_EMAILS=false`** auto-verifies new users (no mailer yet). Next: email verification resend/confirm REST, pages/groups CRUD, Stripe. |
+| **3** — REST + Drizzle features | **In progress** | Auth + registration + **email resend/confirm** (Resend) below; optional **Upstash** for login rate limits. **Next (Phase 3):** pages/groups CRUD, realtime/collab, **Stripe** webhook, then Phase 2 gap (**real `apps/web` tests** in parallel is OK). |
 | **4** — Client MVP | **Not started** | Auth → list → page → Yjs → groups; crypto/libs port as needed. **Parallel:** SPA structure, OpenAPI client, Vitest+DOM in CI, small E2E smoke—see [Frontend / UI track](#frontend--ui-track) (not deferred to “when MVP is done”). |
 | **5** — Cutover | **Not started** | Canary, redirect, retire `/trpc` when safe. |
 
@@ -31,14 +31,25 @@ Living checklist for the greenfield work described in [docs/RESTART_PLAN.md](../
 
 ## Phase 3 checklist (REST + Drizzle)
 
+### Sessions + account (current)
+
 - [x] Document **sessions** REST paths + request schemas in OpenAPI; demo + `users/me` contracts updated.
 - [x] Implement **sessions.login** / refresh / logout against Drizzle + legacy crypto semantics (JWT via `jose`; optional **Redis** failed-login limits when Upstash env is set).
 - [x] Implement **sessions.start-demo** (`POST /api/sessions/demo`) + **Redis** for failed-login when Upstash env is set.
 - [x] **JWT + httpOnly cookies** (`accessToken`, `refreshToken`, `loggedIn`) matching [docs/AUTH_AND_CORS.md](./docs/AUTH_AND_CORS.md).
 - [x] **`GET /api/users/me`** (minimal summary from `accessToken` cookie).
-- [x] **Users** `POST /api/users` registration (crypto payload aligned with demo; conflict / unverified parity; optional `SEND_EMAILS=false` auto-verify).
-- [ ] **Users** email verification resend/confirm (`POST /api/users/me/email-verification/*`) + remaining TRPC_REST_MAP slices as needed.
-- [ ] Pages/groups CRUD, realtime/collab, Stripe webhook (no RevenueCat).
+- [x] **Users** `POST /api/users` registration (crypto payload aligned with demo; conflict / unverified parity; `SEND_EMAILS=false` auto-verifies; when mail is on, `RESEND_API_KEY` required and registration email is sent after commit).
+- [x] **Users — email verification**
+  - [x] `POST /api/users/email-verification/resend` — public, `{ "email" }` (legacy `resendVerificationEmail`); 204 / 400 / 404 / 409 / 502 / 503; [docs/TRPC_REST_MAP.md](./docs/TRPC_REST_MAP.md) updated (paths are **not** under `/me/`; legacy was never cookie-based).
+  - [x] `POST /api/users/email-verification/confirm` — public, `{ "emailVerificationCode" }` (nanoid, legacy `verifyEmail`); 204 / 400; DB update copies `encrypted_new_email` → `encrypted_email`.
+  - [x] `sendRegistrationEmail` + optional **`RESEND_API_KEY`**, optional **`PUBLIC_APP_URL`** in `SessionEnv` / [template.env](./template.env); duplicate unverified registration re-sends via same helper (401 “New email sent”).
+
+### Not started (Phase 3 remainder)
+
+- [ ] **Account (remaining tRPC):** `POST /api/users/me/email-change` (+ confirm), 2FA enable/load/disable/recovery routes from [docs/TRPC_REST_MAP.md](./docs/TRPC_REST_MAP.md), `DELETE /api/users/me`, password change (see map + legacy WS).
+- [ ] **Pages** (user prefs + CRUD) and **groups** CRUD / privacy / passwords per map.
+- [ ] **Realtime / collab** (new or adapted protocols; no key rotation).
+- [ ] **Stripe:** `POST /api/webhooks/stripe`, checkout/portal (no RevenueCat).
 
 ---
 
@@ -111,6 +122,7 @@ Cross-cutting work so the new SPA does not repeat **legacy `apps/client`** patte
 
 | Date | Change |
 |------|--------|
+| 2026-04-26 | Phase 3: email verification `POST /api/users/email-verification/resend` and `…/confirm`; `performResendEmailVerification` / `performConfirmEmailVerification`; Resend in `sendRegistrationEmail`; `RESEND_API_KEY` + `PUBLIC_APP_URL`; first mail on register + re-send on duplicate unverified; OpenAPI 502 on register if provider fails; `c.env?.HYPERDRIVE` on confirm for Vitest. |
 | 2026-04-26 | Phase 3: **`POST /api/users`** (`performUserRegister`), `encryptUserRehashedLoginHash`, `addHours`, OpenAPI 201/400/401/409; optional **`SEND_EMAILS`** on session env (auto-verify when `false`); group password on register still rejected (same as demo). |
 | 2026-04-26 | Phase 3: `POST /api/sessions/demo` (`performSessionStartDemo`), `GET /api/users/me`, Redis failed-login limits (`SessionRedisPort` + optional Upstash), `USER_EMAIL_ENCRYPTION_KEY` on `SessionEnv`; OpenAPI 200/400 for demo, 429 for login, `userMeResponseSchema`; Vitest `login-rate-limit.test.ts`. |
 | 2026-04-26 | Docs: [docs/RESTART_PLAN.md](../docs/RESTART_PLAN.md) §3.5 legacy frontend pain points, §5.8 frontend testing/CI, phased updates; this file: **Frontend / UI track** + Phase 2/4 notes on real web tests. |

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

@@ -29,6 +29,7 @@ describe("api-worker", () => {
     ["POST", "/api/sessions/demo"],
     ["GET", "/api/users/me"],
     ["POST", "/api/users"],
+    ["POST", "/api/users/email-verification/resend"],
   ] 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);
@@ -37,4 +38,18 @@ describe("api-worker", () => {
     });
   });
 
+  it("returns 503 for POST /api/users/email-verification/confirm when hyperdrive is not bound", async () => {
+    const res = await app.request(
+      "http://test/api/users/email-verification/confirm",
+      {
+        method: "POST",
+        body: JSON.stringify({ emailVerificationCode: "a".repeat(21) }),
+        headers: { "Content-Type": "application/json" },
+      },
+    );
+    expect(res.status).toBe(503);
+    await expect(res.json()).resolves.toMatchObject({
+      code: "SERVICE_UNAVAILABLE",
+    });
+  });
 });

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

@@ -1,4 +1,6 @@
 import {
+  emailVerificationConfirmRequestSchema,
+  emailVerificationResendRequestSchema,
   getOpenApiDocument,
   healthResponseSchema,
   sessionDemoRequestSchema,
@@ -366,4 +368,110 @@ app.get("/api/users/me", async (c) => {
   }
 });
 
+app.post("/api/users/email-verification/resend", async (c) => {
+  const sessionEnv = getSessionEnv(c.env);
+  if (sessionEnv == null) {
+    return c.json(serviceUnavailableBody, 503);
+  }
+  const hyper = c.env.HYPERDRIVE;
+  if (hyper == null) {
+    return c.json(
+      {
+        code: "SERVICE_UNAVAILABLE" as const,
+        message: "HYPERDRIVE binding is not configured.",
+      },
+      503,
+    );
+  }
+
+  let bodyJson: unknown;
+  try {
+    bodyJson = await c.req.json();
+  } catch {
+    return c.json({ code: "BAD_REQUEST", message: "Expected JSON body." }, 400);
+  }
+
+  const parsed = emailVerificationResendRequestSchema.safeParse(bodyJson);
+  if (!parsed.success) {
+    return c.json(
+      {
+        code: "VALIDATION_ERROR",
+        message: parsed.error.flatten().formErrors.join("; "),
+      },
+      400,
+    );
+  }
+
+  const db = getDbForConnectionString(hyper.connectionString);
+  try {
+    const { performResendEmailVerification } = await import(
+      "@deepnotes/session"
+    );
+    await performResendEmailVerification({
+      db,
+      env: sessionEnv,
+      email: parsed.data.email,
+    });
+    return c.body(null, 204);
+  } catch (e) {
+    const { SessionError } = await import("@deepnotes/session");
+    if (e instanceof SessionError) {
+      return c.json(
+        { code: e.code, message: e.message },
+        e.status as ContentfulStatusCode,
+      );
+    }
+    throw e;
+  }
+});
+
+app.post("/api/users/email-verification/confirm", async (c) => {
+  const hyper = c.env?.HYPERDRIVE;
+  if (hyper == null) {
+    return c.json(
+      {
+        code: "SERVICE_UNAVAILABLE" as const,
+        message: "HYPERDRIVE binding is not configured.",
+      },
+      503,
+    );
+  }
+
+  let bodyJson: unknown;
+  try {
+    bodyJson = await c.req.json();
+  } catch {
+    return c.json({ code: "BAD_REQUEST", message: "Expected JSON body." }, 400);
+  }
+
+  const parsed = emailVerificationConfirmRequestSchema.safeParse(bodyJson);
+  if (!parsed.success) {
+    return c.json(
+      {
+        code: "VALIDATION_ERROR",
+        message: parsed.error.flatten().formErrors.join("; "),
+      },
+      400,
+    );
+  }
+
+  const db = getDbForConnectionString(hyper.connectionString);
+  try {
+    const { performConfirmEmailVerification } = await import(
+      "@deepnotes/session"
+    );
+    await performConfirmEmailVerification({ db, body: parsed.data });
+    return c.body(null, 204);
+  } catch (e) {
+    const { SessionError } = await import("@deepnotes/session");
+    if (e instanceof SessionError) {
+      return c.json(
+        { code: e.code, message: e.message },
+        e.status as ContentfulStatusCode,
+      );
+    }
+    throw e;
+  }
+});
+
 export default app;

new-deepnotes/apps/api-worker/src/session-env.ts

@@ -13,6 +13,10 @@ export type WorkerSessionBindings = {
   EMAIL_CASE_SENSITIVITY_EXCEPTIONS?: string;
   /** When `"false"`, new registrations are email-verified without sending mail (local/CI). */
   SEND_EMAILS?: string;
+  /** Resend.com API key; required when `SEND_EMAILS` is not `false` and email is sent. */
+  RESEND_API_KEY?: string;
+  /** Optional; default `https://deepnotes.app` for verification links. */
+  PUBLIC_APP_URL?: string;
   /** Optional; when set with token, failed-login rate limits use Upstash REST Redis. */
   UPSTASH_REDIS_REST_URL?: string;
   UPSTASH_REDIS_REST_TOKEN?: string;
@@ -56,5 +60,7 @@ export function getSessionEnv(
     COOKIE_DOMAIN: env.COOKIE_DOMAIN,
     EMAIL_CASE_SENSITIVITY_EXCEPTIONS: env.EMAIL_CASE_SENSITIVITY_EXCEPTIONS,
     SEND_EMAILS: env.SEND_EMAILS,
+    RESEND_API_KEY: env.RESEND_API_KEY,
+    PUBLIC_APP_URL: env.PUBLIC_APP_URL,
   };
 }

new-deepnotes/docs/TRPC_REST_MAP.md

@@ -16,8 +16,8 @@ Working checklist for Phase 0 of [docs/RESTART_PLAN.md](../../docs/RESTART_PLAN.
 | Legacy procedure | Proposed REST / notes |
 |------------------|----------------------|
 | `users.account.register` | `POST /api/users` |
-| `users.account.resendVerificationEmail` | `POST /api/users/me/email-verification/resend` |
-| `users.account.verifyEmail` | `POST /api/users/me/email-verification/confirm` |
+| `users.account.resendVerificationEmail` | `POST /api/users/email-verification/resend` (public; body `{ "email" }` — matches legacy, not an authenticated “me” call) |
+| `users.account.verifyEmail` | `POST /api/users/email-verification/confirm` (public; body `{ "emailVerificationCode" }`, nanoid) |
 | `users.account.emailChange.request` | `POST /api/users/me/email-change` |
 | `users.account.twoFactorAuth.enable.request` | `POST /api/users/me/2fa/enable/request` |
 | `users.account.twoFactorAuth.enable.finish` | `POST /api/users/me/2fa/enable/finish` |

new-deepnotes/packages/api/src/index.ts

@@ -23,6 +23,8 @@ export {
   type UserRegisterRequest,
 } from "./schemas/sessions.js";
 export {
+  emailVerificationConfirmRequestSchema,
+  emailVerificationResendRequestSchema,
   userMeResponseSchema,
   userRegisterResponseSchema,
   type UserMeResponse,

new-deepnotes/packages/api/src/openapi.test.ts

@@ -16,5 +16,11 @@ describe("getOpenApiDocument", () => {
     expect(doc.paths?.["/api/sessions/demo"]?.post).toBeDefined();
     expect(doc.paths?.["/api/users/me"]?.get).toBeDefined();
     expect(doc.paths?.["/api/users"]?.post).toBeDefined();
+    expect(
+      doc.paths?.["/api/users/email-verification/resend"]?.post,
+    ).toBeDefined();
+    expect(
+      doc.paths?.["/api/users/email-verification/confirm"]?.post,
+    ).toBeDefined();
   });
 });

new-deepnotes/packages/api/src/openapi.ts

@@ -17,6 +17,8 @@ import {
   userRegisterRequestSchema,
 } from "./schemas/sessions.js";
 import {
+  emailVerificationConfirmRequestSchema,
+  emailVerificationResendRequestSchema,
   userMeResponseSchema,
   userRegisterResponseSchema,
 } from "./schemas/users.js";
@@ -60,6 +62,15 @@ const sessionConflict409 = {
   },
 } as const;
 
+const sessionNotFound404 = {
+  description: "Resource not found.",
+  content: {
+    "application/json": {
+      schema: sessionErrorResponseSchema,
+    },
+  },
+} as const;
+
 registry.registerPath({
   method: "get",
   path: "/api/health",
@@ -141,6 +152,14 @@ registry.registerPath({
     },
     401: sessionUnauthorized401,
     409: sessionConflict409,
+    502: {
+      description: "Email send failed (e.g. Resend API error after user row was created; rare).",
+      content: {
+        "application/json": {
+          schema: sessionErrorResponseSchema,
+        },
+      },
+    },
     503: sessionServiceUnavailable503,
   },
 });
@@ -165,6 +184,76 @@ registry.registerPath({
   },
 });
 
+registry.registerPath({
+  method: "post",
+  path: "/api/users/email-verification/resend",
+  summary: "Resend email verification (public, by email)",
+  description:
+    "Replaces legacy `users.account.resendVerificationEmail`. Uses Resend when `SEND_EMAILS` is not `false`.",
+  request: {
+    body: {
+      content: {
+        "application/json": {
+          schema: emailVerificationResendRequestSchema,
+        },
+      },
+    },
+  },
+  responses: {
+    204: {
+      description: "Email sent (or accepted by provider).",
+    },
+    400: {
+      description: "Validation error or outbound email disabled for this environment.",
+      content: {
+        "application/json": {
+          schema: sessionErrorResponseSchema,
+        },
+      },
+    },
+    404: sessionNotFound404,
+    409: sessionConflict409,
+    502: {
+      description: "Email provider (Resend) request failed.",
+      content: {
+        "application/json": {
+          schema: sessionErrorResponseSchema,
+        },
+      },
+    },
+    503: sessionServiceUnavailable503,
+  },
+});
+
+registry.registerPath({
+  method: "post",
+  path: "/api/users/email-verification/confirm",
+  summary: "Confirm email with nanoid code",
+  description: "Replaces legacy `users.account.verifyEmail` (public).",
+  request: {
+    body: {
+      content: {
+        "application/json": {
+          schema: emailVerificationConfirmRequestSchema,
+        },
+      },
+    },
+  },
+  responses: {
+    204: {
+      description: "Email verified; account updated.",
+    },
+    400: {
+      description: "Invalid or expired code.",
+      content: {
+        "application/json": {
+          schema: sessionErrorResponseSchema,
+        },
+      },
+    },
+  },
+});
+
 registry.registerPath({
   method: "post",
   path: "/api/sessions/refresh",

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

@@ -22,3 +22,20 @@ export const userRegisterResponseSchema = z
   .openapi("UserRegisterResponse");
 
 export type UserRegisterResponse = z.infer<typeof userRegisterResponseSchema>;
+
+const nanoidVerificationCode = z
+  .string()
+  .min(1)
+  .regex(/^[A-Za-z0-9_-]{21}$/, "expected nanoid verification code");
+
+export const emailVerificationResendRequestSchema = z
+  .object({
+    email: z.string().email(),
+  })
+  .openapi("EmailVerificationResendRequest");
+
+export const emailVerificationConfirmRequestSchema = z
+  .object({
+    emailVerificationCode: nanoidVerificationCode,
+  })
+  .openapi("EmailVerificationConfirmRequest");