@data-club/ai-hub-server 0.0.1

package/dist/routes/auth.js

@@ -0,0 +1,422 @@
+/**
+ * `/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";
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  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 = async (req, ctx) => {
+    let body;
+    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 = { ...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 = protectedRoute({ allowPasswordChangeToken: true }, async (req, ctx, auth) => {
+    let raw;
+    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 = 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 = 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 = protectedRoute({}, async (req, ctx, auth) => {
+    let raw;
+    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() {
+    return new Date().toISOString();
+}
+/** Extracts a string for logging from any thrown value. */
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=auth.js.map

package/dist/routes/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/routes/auth.ts"],"names":[],"mappings":"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"}

package/dist/routes/chat.d.ts

@@ -0,0 +1,97 @@
+/**
+ * `/chat/*` — SSE chat, resumption, cancel (§6.3.2).
+ *
+ * Three endpoints:
+ *
+ * - `POST /chat` — body `{ session_id, user_message, effort?, idempotency_key? }`.
+ *   Streams events per §9. Owner-scoped: the caller must own the
+ *   referenced session.
+ * - `GET  /chat/:turn_id/events?from_seq=N` — resumption: replays
+ *   persisted events with `seq > N`, then live-attaches if the turn is
+ *   still active.
+ * - `POST /chat/:turn_id/cancel` — aborts an in-flight turn. Idempotent
+ *   when the turn already terminated.
+ *
+ * The runner (`state/turnRunner.ts`) owns the actual state machine; this
+ * file is the HTTP/SSE shell. The runner publishes events to a live
+ * channel + persists them; the `POST /chat` writer subscribes to the
+ * same channel and ships bytes to the client. The runner's `onEvent`
+ * callback can write directly; this file uses
+ * `subscribeToTurn` because it shares the same plumbing the resumption
+ * endpoint uses.
+ *
+ * @see SPECIFICATIONS.md §6.3.2 — chat (SSE)
+ * @see SPECIFICATIONS.md §6.6 — server-authoritative state
+ * @see SPECIFICATIONS.md §6.9 — cancellation
+ */
+import { turnEvent } from "../db/schema.js";
+import type { RouteHandler } from "../handlers/types.js";
+import { replayPersistedEvents } from "../state/turnRunner.js";
+/**
+ * `POST /chat` — opens an SSE stream for the new turn.
+ *
+ * Owner-scoped: returns 404 for sessions not owned by the caller. The
+ * `power_user`+ "all-sessions overview" is a different surface.
+ *
+ * The handler returns a `Response` whose body is a `ReadableStream`. The
+ * runner runs in the background, posts events to the registry's live
+ * channel, and the stream subscriber writes them out as `event:`/`data:`
+ * pairs. The runner returns after the stream's terminal event is
+ * persisted; the writer closes the stream shortly after.
+ *
+ * @see SPECIFICATIONS.md §6.3.2
+ * @see SPECIFICATIONS.md §9 — wire protocol
+ */
+export declare const handlePostChat: RouteHandler;
+/**
+ * `GET /chat/:turn_id/events?from_seq=N` — resumption.
+ *
+ * Two-phase:
+ *
+ * 1. Replay persisted `turn_event` rows with `seq > N`, in order.
+ * 2. If the turn is still live, attach to the in-memory broadcaster so
+ *    new events stream through. If the turn is terminal, the response
+ *    closes after the replay.
+ *
+ * Owner-scoped: the caller must own the parent session (the admin
+ * "sessions overview" doesn't go through this endpoint — that's a
+ * separate JSON read).
+ *
+ * @see SPECIFICATIONS.md §6.3.2 — resumption
+ */
+export declare const handleGetChatEvents: RouteHandler;
+/**
+ * `POST /chat/:turn_id/cancel` — aborts an in-flight turn authoritatively.
+ *
+ * Owner-scoped via the parent session. Idempotent — calling it on a
+ * terminal turn returns the same envelope as the first call (no error,
+ * the existing status is reported as `already_terminal`).
+ *
+ * Two cancellation paths fire here, in order:
+ *
+ * 1. **Letta-side cancel** — `client.agents.messages.cancel({ run_ids })`.
+ *    This is the load-bearing one: it tells Letta to stop the run
+ *    server-side and roll back the in-progress step from the
+ *    conversation history (completed steps survive). **Without this,
+ *    aborting only our SDK call's HTTP connection does nothing** —
+ *    Letta keeps generating, persists the full output, and the user's
+ *    refresh reveals it. Empirically verified.
+ *
+ * 2. **Local registry cancel** — `requestTurnCancellation(turnId)`. Fires
+ *    our runner's AbortSignal so the in-process for-await loop exits
+ *    cleanly + emits `stream_end{reason:"cancelled"}`. Also serves as
+ *    the fallback when (1) fails (network blip, Letta-side error, run
+ *    already terminal): the client still gets a clean terminal event.
+ *
+ * Race-free ordering: we fire (1) first so Letta has begun winding the
+ * run down by the time (2) fires; the few final events Letta delivers
+ * during that window flow through the runner's stream naturally before
+ * the abort lands.
+ *
+ * @see SPECIFICATIONS.md §6.3.2
+ * @see SPECIFICATIONS.md §6.9 — cancellation
+ */
+export declare const handlePostChatCancel: RouteHandler;
+export { replayPersistedEvents };
+export { turnEvent };
+//# sourceMappingURL=chat.d.ts.map

package/dist/routes/chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../src/routes/chat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAQH,OAAO,EAAkC,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAQ5E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAEL,qBAAqB,EAGtB,MAAM,wBAAwB,CAAC;AAmChC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,EAAE,YAgN5B,CAAC;AAMF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,mBAAmB,EAAE,YA0GjC,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,oBAAoB,EAAE,YAqDlC,CAAC;AAQF,OAAO,EAAE,qBAAqB,EAAE,CAAC;AAEjC,OAAO,EAAE,SAAS,EAAE,CAAC"}