@data-club/ai-hub-server 0.0.1

package/src/routes/auth.ts

@@ -0,0 +1,513 @@
+/**
+ * `/auth/*` route handlers.
+ *
+ * Step 3 ships the full surface:
+ *
+ * - `POST /auth/login` (Step 2) — public.
+ * - `POST /auth/change-password` — accepts session OR password-change-only
+ *   tokens. Voluntary path requires `current_password`; forced path doesn't
+ *   (the change-only token IS the auth). Enforces the §8.5 password policy
+ *   (length + complexity).
+ * - `POST /auth/logout` — server-side no-op in v1 (the React client just
+ *   discards the token).
+ * - `GET /auth/me` — returns the `{ user, deployment }` envelope per §6.3.4.
+ * - `PATCH /auth/me/preferences` — updates `user.theme_preference` (rejects
+ *   with 409 when the deployment-wide switcher is off).
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — auth endpoints
+ * @see SPECIFICATIONS.md §7.6 — theme resolution
+ * @see SPECIFICATIONS.md §8.5 — Argon2id password verification + complexity
+ */
+
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+
+import {
+  hashPassword,
+  needsRehash,
+  verifyPassword,
+} from "../auth/argon2.js";
+import {
+  mintPasswordChangeToken,
+  mintSessionToken,
+} from "../auth/jwt.js";
+import { protectedRoute } from "../auth/middleware.js";
+import { validatePasswordPolicy } from "../auth/passwordPolicy.js";
+import {
+  buildAuthContext,
+  buildDeploymentView,
+  buildUserView,
+} from "../auth/userView.js";
+import { adminSetting, user } from "../db/schema.js";
+import {
+  conflictError,
+  internalError,
+  jsonResponse,
+  unauthorized,
+  validationError,
+} from "../handlers/responses.js";
+import type { RouteHandler } from "../handlers/types.js";
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  POST /auth/login                                                          */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Login request body shape. Wire is snake_case (§6.3.4). */
+const loginSchema = z
+  .object({
+    username: z.string().min(1).max(255),
+    password: z.string().min(1).max(1024),
+  })
+  .strict();
+
+/**
+ * `POST /auth/login` — Argon2id-verifies username + password, mints either
+ * a session JWT or a 5-minute password-change-only JWT depending on the
+ * user's `is_initial_password` flag.
+ *
+ * **Generic 401 on every failure path** — wrong username, wrong password,
+ * NULL `password_hash` (the future-IdP seam test), or any malformed body.
+ * No enumeration leakage (§13.1, §8.6).
+ *
+ * On success returns `{ token, must_change_password, user, deployment }`.
+ * When `must_change_password = true`, the `deployment` block is omitted
+ * entirely (the change-only token doesn't grant deployment access) and
+ * `user.role` is omitted (the change-only token carries no role claim) —
+ * the client re-fetches `/auth/me` after the change-password handshake.
+ *
+ * Hash-upgrade-on-login (§8.5): if the stored hash was produced with weaker
+ * params than the current `ARGON2_PARAMS` baseline, we rehash and write
+ * back. Best-effort — a write failure does not fail the login.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — `POST /auth/login`
+ * @see SPECIFICATIONS.md §8.5 — auth + hash upgrade
+ */
+export const handleLogin: RouteHandler = async (req, ctx) => {
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    // Malformed JSON — return a generic 401, not a 400. The endpoint should
+    // not distinguish "bad shape" from "wrong credentials" to clients.
+    return unauthorized();
+  }
+  const parsed = loginSchema.safeParse(body);
+  if (!parsed.success) return unauthorized();
+  const { username, password } = parsed.data;
+
+  const row = ctx.db.select().from(user).where(eq(user.username, username)).get();
+  if (!row || !row.passwordHash) {
+    // Either the user doesn't exist or it's an externally-authenticated row
+    // (NULL `password_hash` — §6.7 future-IdP seam). Same generic 401.
+    return unauthorized();
+  }
+
+  const ok = await verifyPassword(row.passwordHash, password);
+  if (!ok) {
+    ctx.logger.info(
+      { username, event: "login_failed" },
+      "Login attempt failed: invalid credentials.",
+    );
+    return unauthorized();
+  }
+
+  // Hash-upgrade-on-login (§8.5). Best-effort — never fail a login because
+  // the rehash itself failed.
+  if (needsRehash(row.passwordHash)) {
+    try {
+      const upgraded = await hashPassword(password);
+      ctx.db
+        .update(user)
+        .set({
+          passwordHash: upgraded,
+          updatedAt: nowIso(),
+        })
+        .where(eq(user.id, row.id))
+        .run();
+      ctx.logger.info(
+        { user_id: row.id, event: "password_hash_upgraded" },
+        "Upgraded stored password hash to current parameters.",
+      );
+    } catch (err) {
+      ctx.logger.warn(
+        { user_id: row.id, err: errMessage(err) },
+        "Hash-upgrade write failed; login still proceeds.",
+      );
+    }
+  }
+
+  const settings = ctx.db
+    .select()
+    .from(adminSetting)
+    .where(eq(adminSetting.id, 1))
+    .get();
+  const signingKey = settings?.serviceTokenSigningKey;
+  if (!signingKey) {
+    // Should not happen — the seed creates the row on first boot.
+    ctx.logger.error(
+      { event: "missing_signing_key" },
+      "admin_setting.service_token_signing_key is empty; cannot mint tokens.",
+    );
+    return internalError("Server misconfigured");
+  }
+
+  const must = row.isInitialPassword;
+  const token = must
+    ? await mintPasswordChangeToken(signingKey, { id: row.id })
+    : await mintSessionToken(signingKey, {
+        id: row.id,
+        username: row.username,
+        role: row.role,
+      });
+
+  ctx.logger.info(
+    {
+      user_id: row.id,
+      username: row.username,
+      role: row.role,
+      must_change_password: must,
+      event: "login_success",
+    },
+    "Login succeeded.",
+  );
+
+  // Per §6.3.4: on `must_change_password = true`:
+  //   - `user.role` is omitted (the change-only token carries no role claim).
+  //   - The `deployment` block is omitted entirely (no deployment access via
+  //     the change-only token).
+  // The client re-fetches /auth/me after the change-password handshake.
+  if (must) {
+    const minimalUser = buildUserView(row);
+    const userWithoutRole: Record<string, unknown> = { ...minimalUser };
+    delete userWithoutRole.role;
+    return jsonResponse(200, {
+      token,
+      must_change_password: true,
+      user: userWithoutRole,
+    });
+  }
+
+  const context = buildAuthContext(row, settings ?? null);
+  return jsonResponse(200, {
+    token,
+    must_change_password: false,
+    user: context.user,
+    deployment: context.deployment,
+  });
+};
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  POST /auth/change-password                                                */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Body for change-password. `current_password` required only on voluntary path. */
+const changePasswordSchema = z
+  .object({
+    current_password: z.string().min(1).max(1024).optional(),
+    new_password: z.string().min(1).max(1024),
+  })
+  .strict();
+
+/**
+ * `POST /auth/change-password` — two distinct flows on one endpoint:
+ *
+ * - **Voluntary (session token):** caller supplies `current_password`; the
+ *   server Argon2id-verifies it, then hashes + writes the new password. Does
+ *   not touch `is_initial_password`. Returns a fresh session token (with the
+ *   caller's current role).
+ * - **Forced (password-change-only token):** caller does not supply
+ *   `current_password` (the change-only token already proves a successful
+ *   prior login). The server hashes + writes the new password, clears
+ *   `is_initial_password`, and returns a fresh session token. The client
+ *   transitions to the normal chat at this point.
+ *
+ * Server-side validation: the new password must satisfy the §8.5 policy —
+ * at least 8 characters AND at least two of {letters, digits, special
+ * characters}. Length-only passwords (e.g. `"12345678"`) are rejected with
+ * 400 `password_too_simple`.
+ *
+ * Mismatched current password → 401 `unauthorized` with a "current
+ * password"-mentioning message. Voluntary path with no `current_password`
+ * is rejected as a validation error (the field IS required when the caller
+ * authenticated with a session token). Forced path with a `current_password`
+ * is rejected too — that signals client confusion.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — `POST /auth/change-password`
+ * @see SPECIFICATIONS.md §8.5 — change flows + password policy
+ */
+export const handleChangePassword: RouteHandler = protectedRoute(
+  { allowPasswordChangeToken: true },
+  async (req, ctx, auth) => {
+    let raw: unknown;
+    try {
+      raw = await req.json();
+    } catch {
+      return validationError("Request body must be valid JSON.");
+    }
+    const parsed = changePasswordSchema.safeParse(raw);
+    if (!parsed.success) {
+      return validationError("Invalid request body.");
+    }
+    const body = parsed.data;
+
+    const policy = validatePasswordPolicy(body.new_password);
+    if (!policy.ok) {
+      return validationError(policy.message, policy.code);
+    }
+
+    if (auth.tokenKind === "session") {
+      // Voluntary path — current_password required.
+      const current = body.current_password;
+      if (!current) {
+        return validationError(
+          "current_password is required for the voluntary change-password flow.",
+          "current_password_required",
+        );
+      }
+      if (!auth.user.passwordHash) {
+        // The auth middleware already rejected NULL-password-hash users, but
+        // belt-and-braces here — if we somehow reached this line, log + 401.
+        ctx.logger.error(
+          { user_id: auth.user.id, event: "change_password_no_hash" },
+          "Reached change-password with a NULL password_hash on the user row.",
+        );
+        return unauthorized();
+      }
+      const ok = await verifyPassword(auth.user.passwordHash, current);
+      if (!ok) {
+        ctx.logger.info(
+          { user_id: auth.user.id, event: "change_password_wrong_current" },
+          "Change-password rejected: current password incorrect.",
+        );
+        return unauthorized("Current password is incorrect.");
+      }
+    } else {
+      // Forced path — current_password not accepted (would confuse callers).
+      if (body.current_password !== undefined) {
+        return validationError(
+          "current_password must not be supplied with a password-change-only token.",
+          "current_password_not_allowed",
+        );
+      }
+    }
+
+    // Hash + write the new password. Forced path also clears the flag.
+    // Bumping `passwordChangedAt` invalidates other sessions the user
+    // may have open (multi-device sign-out on password change) — see
+    // the middleware's iat-vs-passwordChangedAt gate.
+    const newHash = await hashPassword(body.new_password);
+    const clearInitialFlag = auth.tokenKind === "password_change";
+    const now = nowIso();
+    ctx.db
+      .update(user)
+      .set({
+        passwordHash: newHash,
+        isInitialPassword: clearInitialFlag ? false : auth.user.isInitialPassword,
+        passwordChangedAt: now,
+        updatedAt: now,
+      })
+      .where(eq(user.id, auth.user.id))
+      .run();
+
+    // Re-read for the role + theme bits (and to mint a session token with
+    // the freshest row state — Step 4's role-change endpoint can demote a
+    // user between login and change-password, in theory).
+    const freshRow = ctx.db.select().from(user).where(eq(user.id, auth.user.id)).get();
+    if (!freshRow) {
+      // Should not happen.
+      return internalError();
+    }
+
+    const settings = ctx.db
+      .select()
+      .from(adminSetting)
+      .where(eq(adminSetting.id, 1))
+      .get();
+    const signingKey = settings?.serviceTokenSigningKey;
+    if (!signingKey) {
+      ctx.logger.error(
+        { event: "missing_signing_key" },
+        "Cannot mint session token after password change — signing key empty.",
+      );
+      return internalError("Server misconfigured");
+    }
+
+    const sessionToken = await mintSessionToken(signingKey, {
+      id: freshRow.id,
+      username: freshRow.username,
+      role: freshRow.role,
+    });
+
+    ctx.logger.info(
+      {
+        user_id: freshRow.id,
+        username: freshRow.username,
+        role: freshRow.role,
+        token_kind: auth.tokenKind,
+        cleared_initial: clearInitialFlag,
+        event: "password_changed",
+      },
+      "Password changed successfully.",
+    );
+
+    return jsonResponse(200, { token: sessionToken });
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  POST /auth/logout                                                         */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `POST /auth/logout` — server-side no-op in v1.
+ *
+ * Per §6.3.4 and SPECIFICATIONS.md's "Implementer's call" note: v1's
+ * simplest implementation is for the client to discard its token; we don't
+ * maintain a blacklist. A future minor may add token revocation if a
+ * concrete threat model demands it. Returns 200 with a minimal body so the
+ * client has something to act on.
+ *
+ * Still routes through the protected middleware so an anonymous caller gets
+ * a 401 — that signals to the client that its token was already invalid (in
+ * which case it should already be on the login screen).
+ *
+ * @see SPECIFICATIONS.md §6.3.4
+ */
+export const handleLogout: RouteHandler = protectedRoute({}, async () => {
+  return jsonResponse(200, { status: "ok" });
+});
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  GET /auth/me                                                              */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `GET /auth/me` — returns the `{ user, deployment }` envelope.
+ *
+ * `deployment.letta_ade_url` is included only for callers with role >=
+ * `power_user` (handled inside `buildDeploymentView`); `user`-role callers
+ * don't even see the field exists — by design (§6.3.4).
+ *
+ * The resolved theme is computed client-side from
+ * `user.theme_preference + deployment.{theme_default, theme_switcher_enabled}`
+ * per §7.6 — the server does not pre-compute it.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — `GET /auth/me`
+ * @see SPECIFICATIONS.md §7.6 — theme resolution
+ */
+export const handleMe: RouteHandler = protectedRoute({}, async (_req, ctx, auth) => {
+  const settings = ctx.db
+    .select()
+    .from(adminSetting)
+    .where(eq(adminSetting.id, 1))
+    .get();
+  const context = buildAuthContext(auth.user, settings ?? null);
+  return jsonResponse(200, {
+    user: context.user,
+    deployment: context.deployment,
+  });
+});
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  PATCH /auth/me/preferences                                                */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Preferences body. Only `theme` is supported in v1. Strict — extras rejected. */
+const preferencesSchema = z
+  .object({
+    theme: z.enum(["light", "dark"]).optional(),
+  })
+  .strict();
+
+/**
+ * `PATCH /auth/me/preferences` — updates per-user preferences.
+ *
+ * Body: `{ theme?: "light" | "dark" }`. Empty body is a 200 no-op (returns
+ * the current `{ user, deployment }` envelope unchanged) — by an explicit
+ * decision recorded in the Step-3 prompt. Unknown keys → 400 (§13.4).
+ *
+ * Returns 409 `theme_switcher_disabled` when the deployment-wide
+ * `admin_setting.theme_switcher_enabled = false`: per §7.6 the user's
+ * stored preference is ignored while the switcher is off, and accepting a
+ * write in that state would be silently swallowed. We surface the
+ * configuration mismatch rather than pretend the write applied.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — `PATCH /auth/me/preferences`
+ * @see SPECIFICATIONS.md §7.6 — theme resolution
+ */
+export const handleMePreferences: RouteHandler = protectedRoute(
+  {},
+  async (req, ctx, auth) => {
+    let raw: unknown;
+    try {
+      raw = await req.json();
+    } catch {
+      return validationError("Request body must be valid JSON.");
+    }
+    const parsed = preferencesSchema.safeParse(raw);
+    if (!parsed.success) {
+      return validationError("Invalid request body.");
+    }
+    const body = parsed.data;
+
+    if (body.theme !== undefined) {
+      const settings = ctx.db
+        .select()
+        .from(adminSetting)
+        .where(eq(adminSetting.id, 1))
+        .get();
+      if (settings && !settings.themeSwitcherEnabled) {
+        return conflictError(
+          "theme_switcher_disabled",
+          "Theme switcher is disabled by the deployment administrator.",
+        );
+      }
+      ctx.db
+        .update(user)
+        .set({
+          themePreference: body.theme,
+          updatedAt: nowIso(),
+        })
+        .where(eq(user.id, auth.user.id))
+        .run();
+      ctx.logger.info(
+        {
+          user_id: auth.user.id,
+          theme: body.theme,
+          event: "theme_preference_updated",
+        },
+        "User theme preference updated.",
+      );
+    }
+
+    const freshRow = ctx.db
+      .select()
+      .from(user)
+      .where(eq(user.id, auth.user.id))
+      .get();
+    if (!freshRow) return internalError();
+    const settings = ctx.db
+      .select()
+      .from(adminSetting)
+      .where(eq(adminSetting.id, 1))
+      .get();
+    return jsonResponse(200, {
+      user: buildUserView(freshRow),
+      deployment: buildDeploymentView(settings ?? null, freshRow.role),
+    });
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Helpers                                                                   */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Returns the current ISO-8601 timestamp with millisecond precision. */
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+/** Extracts a string for logging from any thrown value. */
+function errMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}