Large hardening pass: explicit migrations, schema diagnostics, admin warnings, error UX

Author: wilhel1812

db/migrations/2026-03-12_schema_alignment.sql

@@ -0,0 +1,30 @@
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE IF NOT EXISTS deleted_users (
+  id TEXT PRIMARY KEY,
+  deleted_at TEXT NOT NULL,
+  deleted_by_user_id TEXT
+);
+
+ALTER TABLE users ADD COLUMN username TEXT;
+ALTER TABLE users ADD COLUMN email TEXT;
+ALTER TABLE users ADD COLUMN bio TEXT;
+ALTER TABLE users ADD COLUMN access_request_note TEXT;
+ALTER TABLE users ADD COLUMN idp_email TEXT;
+ALTER TABLE users ADD COLUMN idp_email_verified INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE users ADD COLUMN avatar_url TEXT;
+ALTER TABLE users ADD COLUMN is_admin INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE users ADD COLUMN is_approved INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE users ADD COLUMN approved_at TEXT;
+ALTER TABLE users ADD COLUMN approved_by_user_id TEXT;
+ALTER TABLE users ADD COLUMN updated_at TEXT;
+
+ALTER TABLE sites ADD COLUMN created_by_user_id TEXT;
+ALTER TABLE sites ADD COLUMN last_edited_by_user_id TEXT;
+ALTER TABLE sites ADD COLUMN created_at TEXT;
+ALTER TABLE sites ADD COLUMN last_edited_at TEXT;
+
+ALTER TABLE simulations ADD COLUMN created_by_user_id TEXT;
+ALTER TABLE simulations ADD COLUMN last_edited_by_user_id TEXT;
+ALTER TABLE simulations ADD COLUMN created_at TEXT;
+ALTER TABLE simulations ADD COLUMN last_edited_at TEXT;

db/schema.sql

@@ -17,6 +17,12 @@ CREATE TABLE IF NOT EXISTS users (
   updated_at TEXT
 );
 
+CREATE TABLE IF NOT EXISTS deleted_users (
+  id TEXT PRIMARY KEY,
+  deleted_at TEXT NOT NULL,
+  deleted_by_user_id TEXT
+);
+
 CREATE TABLE IF NOT EXISTS sites (
   id TEXT PRIMARY KEY,
   owner_user_id TEXT NOT NULL,

docs/BACKLOG.md

@@ -41,8 +41,9 @@ State: stabilization pass (no net-new product features unless explicitly approve
 
 ### Data and storage safety
 - [ ] Replace avatar data URLs in D1 with object storage flow (R2) + thumbnails
-- [ ] Remove runtime schema migration from request path
+- [x] Remove runtime schema migration from request path
 - [ ] Add migration/version status visibility in admin tools
+- Progress: admin schema diagnostics endpoint + warnings added in User Settings.
 - [ ] Add import/export/backup health indicators and stronger restore UX
 
 ### Admin tooling
@@ -67,7 +68,7 @@ State: stabilization pass (no net-new product features unless explicitly approve
 
 ### Security and access hardening
 - [ ] Productize Access policy templates in-app docs and setup checklist
-- [ ] Add admin warning surfaces for unsafe auth/access configuration
+- [x] Add admin warning surfaces for unsafe auth/access configuration
 
 ## Hardening execution paths (agreed, no further discussion required now)
 - [ ] Runtime migrations

docs/cloudflare-auth-setup.md

@@ -22,6 +22,12 @@ Copy the returned `database_id` into `wrangler.toml`.
 npx wrangler d1 execute linksim --file ./db/schema.sql
 ```
 
+For upgrades from older deployments, apply migrations explicitly (runtime auto-migrations are disabled):
+
+```bash
+npx wrangler d1 execute linksim --file ./db/migrations/2026-03-12_schema_alignment.sql
+```
+
 ## 3) Configure Cloudflare Access (GitHub + OTP)
 
 In Cloudflare Zero Trust:
@@ -77,6 +83,7 @@ Deploy from this repo. Pages Functions under `functions/api/*` deploy automatica
 - Access protects app URL (unauth users blocked/challenged)
 - Sign in via GitHub (or OTP fallback)
 - Open User Settings and confirm user status
+- For admins: check `/api/schema-diagnostics` and `/api/auth-diagnostics`
 - Trigger `Sync From Cloud`
 - Create/edit site/simulation and confirm cloud sync status updates
 

functions/_lib/auth.test.ts

@@ -24,6 +24,12 @@ describe("auth inspection", () => {
 });
 
 describe("verifyAuth", () => {
+  it("returns null without auth signals when dev fallback is disabled", async () => {
+    const request = new Request("https://example.test/api/me");
+    const auth = await verifyAuth(request, makeEnv({ ALLOW_INSECURE_DEV_AUTH: "false" }));
+    expect(auth).toBeNull();
+  });
+
   it("accepts header-based auth when user headers are present", async () => {
     const request = new Request("https://example.test/api/me", {
       headers: {

functions/_lib/db.ts

@@ -123,6 +123,67 @@ const registrationMode = (env: Env): "open" | "approval_required" => {
   return value === "open" ? "open" : "approval_required";
 };
 
+const REQUIRED_COLUMNS: Record<string, string[]> = {
+  users: [
+    "id",
+    "username",
+    "email",
+    "bio",
+    "access_request_note",
+    "idp_email",
+    "idp_email_verified",
+    "avatar_url",
+    "is_admin",
+    "is_approved",
+    "approved_at",
+    "approved_by_user_id",
+    "created_at",
+    "updated_at",
+  ],
+  sites: [
+    "id",
+    "owner_user_id",
+    "created_by_user_id",
+    "last_edited_by_user_id",
+    "created_at",
+    "last_edited_at",
+    "name",
+    "visibility",
+    "payload_json",
+    "updated_at",
+  ],
+  simulations: [
+    "id",
+    "owner_user_id",
+    "created_by_user_id",
+    "last_edited_by_user_id",
+    "created_at",
+    "last_edited_at",
+    "name",
+    "visibility",
+    "payload_json",
+    "updated_at",
+  ],
+  deleted_users: ["id", "deleted_at", "deleted_by_user_id"],
+  site_roles: ["site_id", "user_id", "role", "created_at"],
+  simulation_roles: ["simulation_id", "user_id", "role", "created_at"],
+  resource_changes: ["id", "resource_kind", "resource_id", "action", "actor_user_id", "changed_at", "note"],
+};
+
+export const getSchemaDiagnostics = async (env: Env): Promise<{
+  ok: boolean;
+  missing: Array<{ table: string; columns: string[] }>;
+}> => {
+  const missing: Array<{ table: string; columns: string[] }> = [];
+  for (const [table, required] of Object.entries(REQUIRED_COLUMNS)) {
+    const pragma = await env.DB.prepare(`PRAGMA table_info(${table})`).all<{ name: string }>();
+    const existing = new Set(pragma.results.map((col) => col.name));
+    const missingColumns = required.filter((col) => !existing.has(col));
+    if (missingColumns.length) missing.push({ table, columns: missingColumns });
+  }
+  return { ok: missing.length === 0, missing };
+};
+
 const ensureSchema = async (env: Env): Promise<void> => {
   if (!schemaReady) {
     schemaReady = (async () => {
@@ -224,47 +285,12 @@ const ensureSchema = async (env: Env): Promise<void> => {
         env.DB.prepare("CREATE INDEX IF NOT EXISTS idx_resource_changes_lookup ON resource_changes(resource_kind, resource_id, changed_at DESC)"),
       ]);
 
-      const userColumns = await env.DB.prepare("PRAGMA table_info(users)").all<{ name: string }>();
-      const userNames = new Set(userColumns.results.map((col) => col.name));
-      for (const query of [
-        !userNames.has("username") ? "ALTER TABLE users ADD COLUMN username TEXT" : "",
-        !userNames.has("email") ? "ALTER TABLE users ADD COLUMN email TEXT" : "",
-        !userNames.has("bio") ? "ALTER TABLE users ADD COLUMN bio TEXT" : "",
-        !userNames.has("access_request_note") ? "ALTER TABLE users ADD COLUMN access_request_note TEXT" : "",
-        !userNames.has("idp_email") ? "ALTER TABLE users ADD COLUMN idp_email TEXT" : "",
-        !userNames.has("idp_email_verified")
-          ? "ALTER TABLE users ADD COLUMN idp_email_verified INTEGER NOT NULL DEFAULT 0"
-          : "",
-        !userNames.has("avatar_url") ? "ALTER TABLE users ADD COLUMN avatar_url TEXT" : "",
-        !userNames.has("is_admin") ? "ALTER TABLE users ADD COLUMN is_admin INTEGER NOT NULL DEFAULT 0" : "",
-        !userNames.has("is_approved") ? "ALTER TABLE users ADD COLUMN is_approved INTEGER NOT NULL DEFAULT 0" : "",
-        !userNames.has("approved_at") ? "ALTER TABLE users ADD COLUMN approved_at TEXT" : "",
-        !userNames.has("approved_by_user_id") ? "ALTER TABLE users ADD COLUMN approved_by_user_id TEXT" : "",
-        !userNames.has("updated_at") ? "ALTER TABLE users ADD COLUMN updated_at TEXT" : "",
-      ]) {
-        if (query) await env.DB.prepare(query).run();
-      }
-
-      const siteColumns = await env.DB.prepare("PRAGMA table_info(sites)").all<{ name: string }>();
-      const siteNames = new Set(siteColumns.results.map((col) => col.name));
-      for (const query of [
-        !siteNames.has("created_by_user_id") ? "ALTER TABLE sites ADD COLUMN created_by_user_id TEXT" : "",
-        !siteNames.has("last_edited_by_user_id") ? "ALTER TABLE sites ADD COLUMN last_edited_by_user_id TEXT" : "",
-        !siteNames.has("created_at") ? "ALTER TABLE sites ADD COLUMN created_at TEXT" : "",
-        !siteNames.has("last_edited_at") ? "ALTER TABLE sites ADD COLUMN last_edited_at TEXT" : "",
-      ]) {
-        if (query) await env.DB.prepare(query).run();
-      }
-
-      const simColumns = await env.DB.prepare("PRAGMA table_info(simulations)").all<{ name: string }>();
-      const simNames = new Set(simColumns.results.map((col) => col.name));
-      for (const query of [
-        !simNames.has("created_by_user_id") ? "ALTER TABLE simulations ADD COLUMN created_by_user_id TEXT" : "",
-        !simNames.has("last_edited_by_user_id") ? "ALTER TABLE simulations ADD COLUMN last_edited_by_user_id TEXT" : "",
-        !simNames.has("created_at") ? "ALTER TABLE simulations ADD COLUMN created_at TEXT" : "",
-        !simNames.has("last_edited_at") ? "ALTER TABLE simulations ADD COLUMN last_edited_at TEXT" : "",
-      ]) {
-        if (query) await env.DB.prepare(query).run();
+      const diagnostics = await getSchemaDiagnostics(env);
+      if (!diagnostics.ok) {
+        const summary = diagnostics.missing
+          .map((entry) => `${entry.table}: ${entry.columns.join(",")}`)
+          .join(" | ");
+        throw new Error(`Schema out of date. Run D1 migrations. Missing: ${summary}`);
       }
     })();
   }

functions/_lib/http.test.ts

@@ -3,6 +3,7 @@ import { normalizeApiErrorMessage, statusFromErrorMessage } from "./http";
 
 describe("http error normalization", () => {
   it("maps known auth/access errors to stable statuses", () => {
+    expect(statusFromErrorMessage("Schema out of date")).toBe(503);
     expect(statusFromErrorMessage("Session revoked by admin")).toBe(401);
     expect(statusFromErrorMessage("Unauthorized")).toBe(401);
     expect(statusFromErrorMessage("Account pending approval")).toBe(403);

functions/_lib/http.ts

@@ -52,6 +52,7 @@ export const normalizeApiErrorMessage = (message: string): string => {
 
 export const statusFromErrorMessage = (message: string, fallback = 500): number => {
   const lower = message.toLowerCase();
+  if (lower.includes("schema out of date")) return 503;
   if (lower.includes("session revoked by admin")) return 401;
   if (lower.includes("unauthorized")) return 401;
   if (lower.includes("pending approval")) return 403;

functions/api/auth-diagnostics.ts

@@ -1,20 +1,30 @@
 import { verifyAuth, inspectAuthRequest } from "../_lib/auth";
-import { assertUserAccess, ensureUser, fetchUserProfile } from "../_lib/db";
+import { ensureUser, fetchUserProfile } from "../_lib/db";
 import { errorResponse, handleOptions, json, withCors } from "../_lib/http";
 import type { Env } from "../_lib/types";
 
 export const onRequestOptions: PagesFunction<Env> = async ({ request }) => handleOptions(request);
 
+const isBootstrapAdmin = (env: Env, userId: string): boolean =>
+  (env.ADMIN_USER_IDS ?? "")
+    .split(",")
+    .map((value) => value.trim().toLowerCase())
+    .filter(Boolean)
+    .includes(userId.toLowerCase());
+
 export const onRequestGet: PagesFunction<Env> = async ({ request, env }) => {
   try {
     const auth = await verifyAuth(request, env);
     if (!auth) return withCors(request, json({ error: "Unauthorized" }, { status: 401 }));
-
-    await ensureUser(env, auth.userId, auth.tokenPayload);
-    await assertUserAccess(env, auth.userId);
-    const me = await fetchUserProfile(env, auth.userId);
-    if (!me) return withCors(request, json({ error: "Unauthorized" }, { status: 401 }));
-    if (!me.isAdmin) return withCors(request, json({ error: "Forbidden" }, { status: 403 }));
+    let allowed = isBootstrapAdmin(env, auth.userId);
+    try {
+      await ensureUser(env, auth.userId, auth.tokenPayload);
+      const me = await fetchUserProfile(env, auth.userId);
+      if (me?.isAdmin) allowed = true;
+    } catch {
+      // If schema is out of date, allow bootstrap admins to inspect diagnostics.
+    }
+    if (!allowed) return withCors(request, json({ error: "Forbidden" }, { status: 403 }));
 
     const claims = auth.tokenPayload;
     return withCors(

functions/api/schema-diagnostics.ts

@@ -0,0 +1,35 @@
+import { verifyAuth } from "../_lib/auth";
+import { ensureUser, fetchUserProfile, getSchemaDiagnostics } from "../_lib/db";
+import { errorResponse, handleOptions, json, withCors } from "../_lib/http";
+import type { Env } from "../_lib/types";
+
+export const onRequestOptions: PagesFunction<Env> = async ({ request }) => handleOptions(request);
+
+const isBootstrapAdmin = (env: Env, userId: string): boolean =>
+  (env.ADMIN_USER_IDS ?? "")
+    .split(",")
+    .map((value) => value.trim().toLowerCase())
+    .filter(Boolean)
+    .includes(userId.toLowerCase());
+
+export const onRequestGet: PagesFunction<Env> = async ({ request, env }) => {
+  try {
+    const auth = await verifyAuth(request, env);
+    if (!auth) return withCors(request, json({ error: "Unauthorized" }, { status: 401 }));
+
+    let allowed = isBootstrapAdmin(env, auth.userId);
+    try {
+      await ensureUser(env, auth.userId, auth.tokenPayload);
+      const me = await fetchUserProfile(env, auth.userId);
+      if (me?.isAdmin) allowed = true;
+    } catch {
+      // If schema is out of date, allow bootstrap admins to inspect diagnostics.
+    }
+    if (!allowed) return withCors(request, json({ error: "Forbidden" }, { status: 403 }));
+
+    const diagnostics = await getSchemaDiagnostics(env);
+    return withCors(request, json({ schema: diagnostics }));
+  } catch (error) {
+    return errorResponse(request, error, 500);
+  }
+};