Hardening batch: auth observability, diagnostics endpoint, unified API errors, backend tests

Author: wilhel1812

config/vitest.config.ts

@@ -3,7 +3,7 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   test: {
     environment: "node",
-    include: ["../src/**/*.test.ts"],
+    include: ["src/**/*.test.ts", "functions/**/*.test.ts"],
     coverage: {
       provider: "v8",
       reporter: ["text", "html"],

docs/BACKLOG.md

@@ -22,6 +22,8 @@ State: stabilization pass (no net-new product features unless explicitly approve
 - [ ] Instead of showing actions on the users in the admin panel, show a simple list of users and make open the profile popover when clicking the names. This should be the same popover that appears anywhere else. Admin gets extra moderation buttons.
 - [ ] Access request note should be a one time thing for the users. Admins should still be able to see it even after approval, but it shouldn't be an editable field.
 - [ ] What does the reject button currently do?
+- [ ] Show profile pictures to other users when you click open the user popover. Also show a small one next to any user name in the UI
+- [ ] User should be able to select if 
 
 ## Active stabilization backlog
 
@@ -33,8 +35,9 @@ State: stabilization pass (no net-new product features unless explicitly approve
 - [x] Clarify pending-account UX text and flow end-to-end
 - [ ] Restrict sign-ups and approval transitions with explicit lifecycle states
 - [ ] Add dedicated auth/permission tests for critical flows
+- Progress: baseline tests added for auth source resolution and error mapping; endpoint permission matrix still pending.
 - [ ] Add dedicated identity reconciliation tests + audit logging coverage
-- [ ] Add observability for Cloudflare Access auth header/JWT variants
+- [x] Add observability for Cloudflare Access auth header/JWT variants
 
 ### Data and storage safety
 - [ ] Replace avatar data URLs in D1 with object storage flow (R2) + thumbnails
@@ -54,6 +57,7 @@ State: stabilization pass (no net-new product features unless explicitly approve
 - [ ] Clean sidebar information density and progressive disclosure
 - [ ] Unify labels/buttons across libraries and managers
 - [ ] Standardize error messages across endpoints and UI surfaces
+- Progress: backend endpoints now use centralized error normalization and status mapping; UI surface pass still pending.
 
 ### Simulation quality clarity
 - [ ] Improve explanatory info for FSPL / TwoRay / ITM and defaults
@@ -73,10 +77,10 @@ State: stabilization pass (no net-new product features unless explicitly approve
 - Path: add API integration tests for self-role block, pending-user lock, approval/revocation, admin-only mutations, cross-user denial, and delete safeguards.
 - [ ] Identity reconciliation hardening
 - Path: define deterministic merge/link matrix (idp subject, verified email, legacy local email), add immutable audit events for link/merge decisions, and test every branch.
-- [ ] Cloudflare Access auth observability
+- [x] Cloudflare Access auth observability
 - Path: add structured auth logs with reason codes for 401/403, include parsed identity source and header/JWT shape, and expose admin diagnostics endpoint/view.
 
 ## Next batch plan
-1. Pending-account UX clarity pass + wording consistency pass.
-2. Notification center expansion (history, filtering, moderation handoff).
+1. Auth/permission endpoint matrix tests (admin/user/pending/revoked/deleted sessions).
+2. Runtime migration extraction from request path into explicit migration step.
 3. Admin utilities scope draft replacing manual SQL operations.

functions/_lib/auth.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { inspectAuthRequest, verifyAuth } from "./auth";
+import type { Env } from "./types";
+
+const makeEnv = (overrides?: Partial<Env>): Env =>
+  ({
+    DB: {} as D1Database,
+    ...overrides,
+  }) as Env;
+
+describe("auth inspection", () => {
+  it("detects available Cloudflare auth headers", () => {
+    const request = new Request("https://example.test/api/me", {
+      headers: {
+        "Cf-Access-Authenticated-User-Email": "user@example.com",
+        "Cf-Access-Authenticated-User-Id": "sub-123",
+      },
+    });
+    const inspected = inspectAuthRequest(request);
+    expect(inspected.hasEmailHeader).toBe(true);
+    expect(inspected.hasUserIdHeader).toBe(true);
+    expect(inspected.hasJwtAssertion).toBe(false);
+  });
+});
+
+describe("verifyAuth", () => {
+  it("accepts header-based auth when user headers are present", async () => {
+    const request = new Request("https://example.test/api/me", {
+      headers: {
+        "Cf-Access-Authenticated-User-Email": "user@example.com",
+      },
+    });
+    const auth = await verifyAuth(request, makeEnv());
+    expect(auth?.userId).toBe("user@example.com");
+    expect(auth?.source).toBe("headers");
+  });
+
+  it("falls back to insecure dev auth when enabled", async () => {
+    const request = new Request("https://example.test/api/me");
+    const auth = await verifyAuth(
+      request,
+      makeEnv({ ALLOW_INSECURE_DEV_AUTH: "true", DEV_AUTH_USER_ID: "local-dev" }),
+    );
+    expect(auth?.userId).toBe("local-dev");
+    expect(auth?.source).toBe("dev");
+  });
+});

functions/_lib/auth.ts

@@ -66,6 +66,37 @@ const readHeaderUserName = (request: Request): string => {
   return name.trim();
 };
 
+export const inspectAuthRequest = (request: Request) => {
+  const jwt =
+    request.headers.get("cf-access-jwt-assertion") ??
+    request.headers.get("Cf-Access-Jwt-Assertion") ??
+    "";
+  const email =
+    request.headers.get("cf-access-authenticated-user-email") ??
+    request.headers.get("Cf-Access-Authenticated-User-Email") ??
+    "";
+  const userId =
+    request.headers.get("cf-access-authenticated-user-id") ??
+    request.headers.get("Cf-Access-Authenticated-User-Id") ??
+    "";
+  const userName =
+    request.headers.get("cf-access-authenticated-user-name") ??
+    request.headers.get("Cf-Access-Authenticated-User-Name") ??
+    "";
+  return {
+    hasJwtAssertion: Boolean(jwt.trim()),
+    hasEmailHeader: Boolean(email.trim()),
+    hasUserIdHeader: Boolean(userId.trim()),
+    hasUserNameHeader: Boolean(userName.trim()),
+  };
+};
+
+const emitAuthLog = (env: Env, payload: Record<string, unknown>) => {
+  const enabled = (env.AUTH_OBSERVABILITY ?? "true").trim().toLowerCase();
+  if (enabled === "false" || enabled === "0" || enabled === "off") return;
+  console.info(JSON.stringify({ event: "auth", ...payload }));
+};
+
 const verifyCloudflareAccessJwt = async (
   token: string,
   request: Request,
@@ -111,6 +142,7 @@ const verifyCloudflareAccessJwt = async (
       email: typeof lastPayload.email === "string" && lastPayload.email.trim() ? lastPayload.email : readHeaderEmail(request),
       name: typeof lastPayload.name === "string" && lastPayload.name.trim() ? lastPayload.name : readHeaderUserName(request),
     },
+    source: "jwt",
   };
 };
 
@@ -123,6 +155,7 @@ const verifyByHeadersOnly = (request: Request): AuthContext | null => {
       email: readHeaderEmail(request),
       name: readHeaderUserName(request),
     },
+    source: "headers",
   };
 };
 
@@ -133,10 +166,12 @@ const allowInsecureDevAuth = (env: Env): AuthContext | null => {
   return {
     userId,
     tokenPayload: { devAuth: true },
+    source: "dev",
   };
 };
 
 export const verifyAuth = async (request: Request, env: Env): Promise<AuthContext | null> => {
+  const authSignals = inspectAuthRequest(request);
   try {
     const token =
       request.headers.get("cf-access-jwt-assertion") ??
@@ -145,13 +180,27 @@ export const verifyAuth = async (request: Request, env: Env): Promise<AuthContex
 
     if (token.trim()) {
       const jwtVerified = await verifyCloudflareAccessJwt(token.trim(), request, env);
-      if (jwtVerified) return jwtVerified;
+      if (jwtVerified) {
+        emitAuthLog(env, { result: "ok", source: jwtVerified.source, ...authSignals });
+        return jwtVerified;
+      }
+      emitAuthLog(env, { result: "fail", reason: "jwt_verify_failed", ...authSignals });
     }
 
     const byHeader = verifyByHeadersOnly(request);
-    if (byHeader) return byHeader;
+    if (byHeader) {
+      emitAuthLog(env, { result: "ok", source: byHeader.source, ...authSignals });
+      return byHeader;
+    }
   } catch {
+    emitAuthLog(env, { result: "fail", reason: "auth_exception", ...authSignals });
     // Fail closed to header/dev fallback instead of surfacing auth internals as 500.
   }
-  return allowInsecureDevAuth(env);
+  const dev = allowInsecureDevAuth(env);
+  if (dev) {
+    emitAuthLog(env, { result: "ok", source: dev.source, ...authSignals });
+    return dev;
+  }
+  emitAuthLog(env, { result: "fail", reason: "no_auth_context", ...authSignals });
+  return null;
 };

functions/_lib/http.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { normalizeApiErrorMessage, statusFromErrorMessage } from "./http";
+
+describe("http error normalization", () => {
+  it("maps known auth/access errors to stable statuses", () => {
+    expect(statusFromErrorMessage("Session revoked by admin")).toBe(401);
+    expect(statusFromErrorMessage("Unauthorized")).toBe(401);
+    expect(statusFromErrorMessage("Account pending approval")).toBe(403);
+    expect(statusFromErrorMessage("Forbidden")).toBe(403);
+    expect(statusFromErrorMessage("User not found")).toBe(404);
+    expect(statusFromErrorMessage("Name is required")).toBe(400);
+  });
+
+  it("normalizes common messages", () => {
+    expect(normalizeApiErrorMessage("Unauthorized token")).toBe("Unauthorized.");
+    expect(normalizeApiErrorMessage("pending approval for account")).toBe("Account pending approval.");
+    expect(normalizeApiErrorMessage("")).toBe("Request failed.");
+  });
+});

functions/_lib/http.ts

@@ -36,3 +36,40 @@ export const handleOptions = (request: Request): Response =>
     status: 204,
     headers: corsHeaders(request),
   });
+
+export const normalizeApiErrorMessage = (message: string): string => {
+  const lower = message.toLowerCase();
+  if (lower.includes("session revoked by admin")) return "Session revoked by admin.";
+  if (lower.includes("pending approval")) return "Account pending approval.";
+  if (lower.includes("unauthorized")) return "Unauthorized.";
+  if (lower.includes("forbidden")) return "Forbidden.";
+  if (lower.includes("not found")) return "Not found.";
+  if (lower.includes("required") || lower.includes("must be valid") || lower.includes("missing ")) {
+    return message;
+  }
+  return message || "Request failed.";
+};
+
+export const statusFromErrorMessage = (message: string, fallback = 500): number => {
+  const lower = message.toLowerCase();
+  if (lower.includes("session revoked by admin")) return 401;
+  if (lower.includes("unauthorized")) return 401;
+  if (lower.includes("pending approval")) return 403;
+  if (lower.includes("forbidden")) return 403;
+  if (lower.includes("not found")) return 404;
+  if (lower.includes("required") || lower.includes("must be valid") || lower.includes("invalid")) return 400;
+  return fallback;
+};
+
+export const errorResponse = (request: Request, error: unknown, fallback = 500): Response => {
+  const message = error instanceof Error ? error.message : String(error);
+  return withCors(
+    request,
+    json(
+      {
+        error: normalizeApiErrorMessage(message),
+      },
+      { status: statusFromErrorMessage(message, fallback) },
+    ),
+  );
+};

functions/_lib/types.ts

@@ -23,6 +23,7 @@ export type Env = {
   DB: D1Database;
   ACCESS_TEAM_DOMAIN?: string;
   ACCESS_AUD?: string;
+  AUTH_OBSERVABILITY?: string;
   ALLOW_INSECURE_DEV_AUTH?: string;
   DEV_AUTH_USER_ID?: string;
   ADMIN_USER_IDS?: string;
@@ -32,4 +33,5 @@ export type Env = {
 export type AuthContext = {
   userId: string;
   tokenPayload: Record<string, unknown>;
+  source?: "jwt" | "headers" | "dev";
 };

functions/api/auth-diagnostics.ts

@@ -0,0 +1,47 @@
+import { verifyAuth, inspectAuthRequest } from "../_lib/auth";
+import { assertUserAccess, 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);
+
+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 }));
+
+    const claims = auth.tokenPayload;
+    return withCors(
+      request,
+      json({
+        auth: {
+          source: auth.source ?? "unknown",
+          userId: auth.userId,
+          signals: inspectAuthRequest(request),
+          claims: {
+            iss: typeof claims.iss === "string" ? claims.iss : null,
+            sub: typeof claims.sub === "string" ? claims.sub : null,
+            email: typeof claims.email === "string" ? claims.email : null,
+            name: typeof claims.name === "string" ? claims.name : null,
+            iat: typeof claims.iat === "number" ? claims.iat : null,
+            exp: typeof claims.exp === "number" ? claims.exp : null,
+          },
+          config: {
+            accessAudConfigured: Boolean((env.ACCESS_AUD ?? "").trim()),
+            accessTeamDomainConfigured: Boolean((env.ACCESS_TEAM_DOMAIN ?? "").trim()),
+            insecureDevAuthEnabled: (env.ALLOW_INSECURE_DEV_AUTH ?? "").trim().toLowerCase() === "true",
+            authObservabilityEnabled: (env.AUTH_OBSERVABILITY ?? "true").trim().toLowerCase() !== "false",
+          },
+        },
+      }),
+    );
+  } catch (error) {
+    return errorResponse(request, error, 500);
+  }
+};

functions/api/changes.ts

@@ -1,6 +1,6 @@
 import { verifyAuth } from "../_lib/auth";
 import { assertUserAccess, ensureUser, fetchResourceChanges } from "../_lib/db";
-import { handleOptions, json, withCors } from "../_lib/http";
+import { errorResponse, handleOptions, json, withCors } from "../_lib/http";
 import type { Env } from "../_lib/types";
 
 export const onRequestOptions: PagesFunction<Env> = async ({ request }) => handleOptions(request);
@@ -25,8 +25,6 @@ export const onRequestGet: PagesFunction<Env> = async ({ request, env }) => {
     const changes = await fetchResourceChanges(env, kind, resourceId);
     return withCors(request, json({ changes }));
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const status = message.includes("pending approval") || message.includes("removed by admin") ? 403 : 500;
-    return withCors(request, json({ error: message }, { status }));
+    return errorResponse(request, error, 500);
   }
 };

functions/api/library.ts

@@ -1,6 +1,6 @@
 import { verifyAuth } from "../_lib/auth";
 import { assertUserAccess, ensureUser, fetchLibraryForUser, upsertLibrarySnapshot } from "../_lib/db";
-import { handleOptions, json, withCors } from "../_lib/http";
+import { errorResponse, handleOptions, json, withCors } from "../_lib/http";
 import type { CloudResourceRecord, Env, LibrarySnapshotPayload } from "../_lib/types";
 
 const normalizeArray = (value: unknown): CloudResourceRecord[] => (Array.isArray(value) ? (value as CloudResourceRecord[]) : []);
@@ -22,9 +22,7 @@ export const onRequestGet: PagesFunction<Env> = async ({ request, env }) => {
       }),
     );
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const status = message.includes("pending approval") || message.includes("removed by admin") ? 403 : 500;
-    return withCors(request, json({ error: message }, { status }));
+    return errorResponse(request, error, 500);
   }
 };
 
@@ -52,11 +50,6 @@ export const onRequestPut: PagesFunction<Env> = async ({ request, env }) => {
       }),
     );
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const status =
-      message.includes("pending approval") || message.includes("removed by admin")
-        ? 403
-        : 400;
-    return withCors(request, json({ error: message }, { status }));
+    return errorResponse(request, error, 400);
   }
 };