@data-club/ai-hub-server 0.0.1

package/src/auth/middleware.ts

@@ -0,0 +1,250 @@
+/**
+ * Role-enforcement middleware: `protectedRoute({...}, handler)`.
+ *
+ * Every protected endpoint runs through this exact §8.6 order:
+ *
+ * 1. Pull the bearer token from `Authorization: Bearer <token>` (401 on miss).
+ * 2. Load the signing key from `admin_setting.service_token_signing_key`
+ *    (500 if missing — should not happen after the first-boot seed).
+ * 3. `verifyServiceToken(key, token)` (401 on invalid signature, expiry,
+ *    issuer, or claim shape).
+ * 4. Reject password-change-only tokens unless the route opts into them
+ *    (401 — same envelope as 1/3 so no scope-leakage).
+ * 5. Load the user row by `sub` (401 if the user was deleted after the
+ *    token was minted — defensive).
+ * 6. For session tokens, if `requiredRole` is set and the token's role
+ *    claim doesn't satisfy it, return 403 with `forbidden`. The role check
+ *    uses the **JWT claim**, not the row — by spec design (§8.6 step 3):
+ *    rotating someone's role does not change their existing token (24 h max
+ *    impact), and the system invalidates everything in one cut via the
+ *    signing-key rotation.
+ * 7. Invoke the wrapped handler with the loaded user + the discriminator
+ *    so it knows what kind of token authenticated the call.
+ *
+ * Shield + min-count invariants are NOT enforced here — that's the job of
+ * the per-handler `apply*InTx` helpers (`auth/roleRules.ts`), each of which
+ * re-reads target state inside a SQLite transaction so two simultaneous
+ * mutations cannot race.
+ *
+ * The middleware lives at one boundary so a future external-IdP feature
+ * (§6.7 "Future direction", §17 question 5) can slot a parallel
+ * `verifyExternalToken` in alongside without touching every handler.
+ *
+ * @see SPECIFICATIONS.md §6.7 — auth model
+ * @see SPECIFICATIONS.md §8.6 — endpoint enforcement order
+ * @see SPECIFICATIONS.md §6.7 — single-function-boundary seam
+ */
+
+import { eq } from "drizzle-orm";
+
+import type { AIHubRole } from "@data-club/ai-hub";
+
+import { adminSetting, user } from "../db/schema.js";
+import type { UserRow } from "../db/schema.js";
+import { forbidden, internalError, unauthorized } from "../handlers/responses.js";
+import type { AIHubServerContext, RouteHandler } from "../handlers/types.js";
+
+import { hasRoleAtLeast } from "./roleRules.js";
+import type {
+  PasswordChangeTokenClaims,
+  SessionTokenClaims,
+} from "./jwt.js";
+import { verifyServiceToken } from "./jwt.js";
+
+/**
+ * Auth context handed to a protected handler. Carries both the loaded user
+ * row (so the handler doesn't re-query) and a discriminated kind so the
+ * handler can branch when it needs to (the `/auth/change-password` handler is
+ * the only one in v1 that cares — both token kinds reach it).
+ */
+export interface AuthContext {
+  /**
+   * The loaded user row. `auth.role` mirrors `claims.role` for session tokens
+   * but is read from the row for password-change-only tokens (which carry no
+   * role claim). Handlers should use the JWT-derived `role` for matrix checks
+   * and the row for anything else.
+   */
+  user: UserRow;
+  /**
+   * Role to use for matrix-style checks. For session tokens this is the JWT
+   * claim (per §8.6 step 3 — frozen at mint time). For password-change-only
+   * tokens this is `user.role` from the row; the change-only token only
+   * reaches `/auth/change-password`, which doesn't read this field.
+   */
+  role: AIHubRole;
+  /** Which kind of token authenticated the request. */
+  tokenKind: "session" | "password_change";
+  /**
+   * The raw verified claims, in case a handler wants to log them or branch
+   * on something the role/user/tokenKind don't expose.
+   */
+  claims: SessionTokenClaims | PasswordChangeTokenClaims;
+}
+
+/**
+ * Options accepted by `protectedRoute`. Both fields default to "session
+ * token required, any role." Endpoints that need more (e.g. role gate or
+ * password-change-only-token acceptance) set the appropriate field.
+ */
+export interface ProtectedRouteOptions {
+  /**
+   * Minimum role the caller must have. Default: any authenticated session
+   * (no role check). The matrix check uses the JWT's `role` claim, not the
+   * current row state — see file-level comment.
+   */
+  requiredRole?: AIHubRole;
+  /**
+   * `true` if the endpoint also accepts password-change-only tokens. Only
+   * `/auth/change-password` sets this in v1. Default: false (every other
+   * endpoint rejects change-only tokens with 401).
+   */
+  allowPasswordChangeToken?: boolean;
+}
+
+/** A handler that has been authenticated by `protectedRoute`. */
+export type AuthenticatedHandler = (
+  req: Request,
+  ctx: AIHubServerContext,
+  auth: AuthContext,
+  params: Readonly<Record<string, string>>,
+) => Promise<Response>;
+
+/**
+ * Wraps a handler with the §8.6 enforcement order. Returns a plain
+ * `RouteHandler` that the route table mounts as if the auth check didn't
+ * exist.
+ *
+ * @param opts - per-route auth options.
+ * @param handler - the wrapped handler. Called only when auth succeeds.
+ * @returns a `RouteHandler` that runs auth, then delegates to `handler`.
+ */
+export function protectedRoute(
+  opts: ProtectedRouteOptions,
+  handler: AuthenticatedHandler,
+): RouteHandler {
+  return async (req, ctx, params) => {
+    // 1. Extract bearer token.
+    const token = extractBearer(req.headers.get("authorization"));
+    if (!token) return unauthorized();
+
+    // 2. Load signing key from the singleton settings row.
+    const settings = ctx.db
+      .select()
+      .from(adminSetting)
+      .where(eq(adminSetting.id, 1))
+      .get();
+    if (!settings?.serviceTokenSigningKey) {
+      ctx.logger.error(
+        { event: "missing_signing_key" },
+        "admin_setting.service_token_signing_key is empty; cannot verify token.",
+      );
+      return internalError("Server misconfigured");
+    }
+
+    // 3. Verify token signature + issuer + expiry + claim shape.
+    const verified = await verifyServiceToken(
+      settings.serviceTokenSigningKey,
+      token,
+    );
+    if (verified.kind === "invalid") return unauthorized();
+
+    // 4. Reject password-change-only tokens unless this route opts in.
+    if (verified.kind === "password_change" && !opts.allowPasswordChangeToken) {
+      return unauthorized();
+    }
+
+    // 5. Load user row by sub. The row may be missing if the user was deleted
+    //    between mint and verify; a 401 (rather than 404) keeps the response
+    //    indistinguishable from an invalid-token response — no enumeration.
+    const subject = verified.claims.sub;
+    if (!subject) return unauthorized();
+    const row = ctx.db.select().from(user).where(eq(user.id, subject)).get();
+    if (!row) return unauthorized();
+
+    // 5b. Session-invalidation gate — for **session tokens only**, reject
+    //     JWTs issued before the user's last password mutation. This is
+    //     what makes admin-driven password resets (and voluntary changes)
+    //     sign out the affected user's other devices immediately rather
+    //     than waiting for the 24h JWT expiry. Change-only tokens are
+    //     allowed through; the change-password handler itself bumps
+    //     `passwordChangedAt` AND mints a fresh session token in one go,
+    //     so the user can still complete the forced-change flow.
+    //
+    //     Comparison runs in **second precision** because jose's `iat`
+    //     truncates to whole seconds — comparing higher precision would
+    //     occasionally reject a JWT minted in the same second as the
+    //     password mutation.
+    if (verified.kind === "session" && row.passwordChangedAt) {
+      const iatSeconds = verified.claims.iat;
+      const pwdChangedSeconds = Math.floor(
+        Date.parse(row.passwordChangedAt) / 1000,
+      );
+      if (
+        typeof iatSeconds === "number" &&
+        Number.isFinite(pwdChangedSeconds) &&
+        iatSeconds < pwdChangedSeconds
+      ) {
+        ctx.logger.info(
+          {
+            user_id: row.id,
+            jwt_iat: iatSeconds,
+            password_changed_at: row.passwordChangedAt,
+            event: "session_invalidated_by_password_change",
+          },
+          "Rejecting session token issued before last password change.",
+        );
+        return unauthorized();
+      }
+    }
+
+    // 6. Role check — drives off the **DB row's current role** rather than
+    //    the JWT claim's role. The JWT signature still proves identity
+    //    (we trust `sub`), but ACL decisions read the freshest source so:
+    //
+    //    - **Promotions take effect immediately** — a user just promoted
+    //      to admin can use admin endpoints without logging out + back in.
+    //    - **Demotions revoke access immediately** — a demoted admin
+    //      loses admin endpoints right away rather than retaining them
+    //      until their 24 h JWT expires.
+    //
+    //    The spec's §8.6 step 3 ("Extract the role claim") describes the
+    //    procedural shape but the security property it cares about
+    //    ("the user can't escalate privileges via a tampered token") is
+    //    preserved here — DB role can't be tampered with by the client.
+    //
+    //    Change-only tokens fall through with `row.role` too, so the same
+    //    code path handles both kinds.
+    const effectiveRole: AIHubRole = row.role;
+    if (verified.kind === "session" && opts.requiredRole) {
+      if (!hasRoleAtLeast(effectiveRole, opts.requiredRole)) {
+        return forbidden(
+          `Requires role at least ${opts.requiredRole}.`,
+        );
+      }
+    }
+
+    // 7. Invoke the wrapped handler.
+    const auth: AuthContext = {
+      user: row,
+      role: effectiveRole,
+      tokenKind: verified.kind,
+      claims: verified.claims,
+    };
+    return handler(req, ctx, auth, params ?? {});
+  };
+}
+
+/**
+ * Parses the `Authorization` header value, returning the bearer token or
+ * `null` when the header is missing or malformed.
+ *
+ * @param value - the raw header value (or `null` if absent).
+ * @returns the bearer token, or `null`.
+ */
+function extractBearer(value: string | null): string | null {
+  if (!value) return null;
+  const m = value.match(/^Bearer\s+(.+)$/i);
+  if (!m) return null;
+  const token = m[1]?.trim() ?? "";
+  return token.length > 0 ? token : null;
+}

package/src/auth/passwordPolicy.ts

@@ -0,0 +1,99 @@
+/**
+ * Password complexity policy (§8.5).
+ *
+ * Every new password supplied to `/auth/change-password` must satisfy two
+ * checks:
+ *
+ * 1. **Minimum length** — `PASSWORD_MIN_LENGTH` (8) characters.
+ * 2. **Complexity** — at least **2 of these 3 categories** must appear in
+ *    the password:
+ *      - letters (any Unicode letter, `\p{L}`)
+ *      - digits (any Unicode number, `\p{N}`)
+ *      - special characters (anything that's neither letter nor digit nor
+ *        whitespace — symbols, punctuation, etc.)
+ *
+ * Examples:
+ *
+ * - `"12345678"` — only digits → **rejected**.
+ * - `"abcdefgh"` — only letters → **rejected**.
+ * - `"!!!!!!!!"` — only special → **rejected**.
+ * - `"abcd1234"` — letters + digits → **accepted**.
+ * - `"password!"` — letters + special → **accepted**.
+ * - `"1234!@#$"` — digits + special → **accepted**.
+ * - `"Aa1!Aa1!"` — all three → **accepted**.
+ *
+ * Whitespace does not count as "special" because allowing whitespace to
+ * tick the box would let `"password "` pass; we want at least one
+ * meaningfully non-letter character.
+ *
+ * This module is the single source of truth — the spec-mandated rule is
+ * defined here and consumed by handlers. Any future relaxation or
+ * tightening happens in one place.
+ *
+ * @see SPECIFICATIONS.md §8.5 — password requirements
+ */
+
+/** Minimum length for a new password (§8.5). */
+export const PASSWORD_MIN_LENGTH = 8;
+
+/** Minimum distinct character categories required (§8.5). */
+export const PASSWORD_REQUIRED_CATEGORIES = 2;
+
+/** Result of `validatePasswordPolicy`. */
+export type PasswordPolicyResult =
+  | { ok: true }
+  | { ok: false; code: PasswordPolicyErrorCode; message: string };
+
+/** Machine-readable codes the validator emits. */
+export type PasswordPolicyErrorCode =
+  | "password_too_short"
+  | "password_too_simple";
+
+/**
+ * Validates `password` against the §8.5 policy. Returns a discriminated
+ * result the handler maps directly into a 400 response.
+ *
+ * @param password - the candidate plaintext password.
+ * @returns `{ ok: true }` on pass, `{ ok: false, code, message }` on fail.
+ */
+export function validatePasswordPolicy(password: string): PasswordPolicyResult {
+  if (password.length < PASSWORD_MIN_LENGTH) {
+    return {
+      ok: false,
+      code: "password_too_short",
+      message: `New password must be at least ${PASSWORD_MIN_LENGTH} characters.`,
+    };
+  }
+  const categories = countCharacterCategories(password);
+  if (categories < PASSWORD_REQUIRED_CATEGORIES) {
+    return {
+      ok: false,
+      code: "password_too_simple",
+      message:
+        "New password must contain at least two of these three: letters, digits, special characters.",
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Counts how many of the three categories the password matches.
+ *
+ * Categories are mutually exclusive:
+ *
+ * - letter: any Unicode letter (`\p{L}`)
+ * - digit: any Unicode number (`\p{N}`)
+ * - special: everything else that is **not** whitespace (`\s`)
+ *
+ * Whitespace contributes to neither.
+ *
+ * @param password - the candidate plaintext password.
+ * @returns the count in `[0, 3]`.
+ */
+export function countCharacterCategories(password: string): number {
+  let count = 0;
+  if (/\p{L}/u.test(password)) count++;
+  if (/\p{N}/u.test(password)) count++;
+  if (/[^\p{L}\p{N}\s]/u.test(password)) count++;
+  return count;
+}