@data-club/ai-hub-server 0.0.1

package/src/routes/admin/users.ts

@@ -0,0 +1,455 @@
+/**
+ * `/admin/users/*` — admin + super_admin user management.
+ *
+ * Five endpoints:
+ *
+ * - `GET    /admin/users` — list every user in the deployment.
+ * - `POST   /admin/users` — create a user; the server generates a 16-char
+ *   alphanumeric password, hashes it, and returns the **plaintext exactly
+ *   once** in the response. The caller delivers it to the user out-of-band.
+ *   Sets `is_initial_password = true` so the user is forced to change on
+ *   first login (§8.5).
+ * - `PATCH  /admin/users/:id/role` — change a user's role. Uses
+ *   `applyUserRoleChangeInTx` so the shield + min-count rules are enforced
+ *   inside the transaction (no race possible).
+ * - `POST   /admin/users/:id/reset-password` — regenerate a 16-char password
+ *   for an existing user. Same return-once semantics; sets the initial-
+ *   password flag back to true. Uses `assertPasswordResetInTx` to validate
+ *   the shield + min-count rules, then performs the async Argon2 hash + write
+ *   outside the transaction (better-sqlite3 transactions are synchronous so
+ *   an Argon2 hash cannot live inside one). The narrow window between assert
+ *   and write is documented in the helper's JSDoc and is acceptable in v1.
+ * - `DELETE /admin/users/:id` — hard-delete the user. Uses
+ *   `applyUserDeletionInTx`; cascades to `session` via the FK.
+ *
+ * **Admin shield + min-count rules** are enforced by the helpers in
+ * `auth/roleRules.ts`; the handlers here just translate the helper's
+ * `TxResult` into a Response.
+ *
+ * **Admin cannot create / promote to `super_admin`.** The role enum on the
+ * POST body is filtered by caller role (admins see user / power_user /
+ * admin; super_admin sees all four). This mirrors the [05-admin-users.md]
+ * sketch's "Create User" modal.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — admin users endpoints
+ * @see SPECIFICATIONS.md §8.1 — shield + min-count rules
+ * @see SPECIFICATIONS.md §8.5 — password reset semantics
+ * @see ui-sketches/05-admin-users.md
+ */
+
+import { randomBytes, randomUUID } from "node:crypto";
+
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+
+import type { AIHubRole } from "@data-club/ai-hub";
+
+import { hashPassword } from "../../auth/argon2.js";
+import { protectedRoute } from "../../auth/middleware.js";
+import {
+  applyUserDeletionInTx,
+  applyUserRoleChangeInTx,
+  assertPasswordResetInTx,
+} from "../../auth/roleRules.js";
+import { user } from "../../db/schema.js";
+import type { UserRow } from "../../db/schema.js";
+import {
+  conflictError,
+  errorResponse,
+  forbidden,
+  jsonResponse,
+  notFound,
+  validationError,
+} from "../../handlers/responses.js";
+import type { RouteHandler } from "../../handlers/types.js";
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Helpers                                                                   */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Wire-format view of a `user` row for admin listings. Excludes
+ * `password_hash` and `identity_source` (server-internal — §6.3.4).
+ *
+ * @param row - the DB row.
+ * @returns the JSON-safe response shape.
+ */
+function adminUserView(row: UserRow): Record<string, unknown> {
+  return {
+    id: row.id,
+    username: row.username,
+    display_name: row.displayName ?? null,
+    role: row.role,
+    is_initial_password: row.isInitialPassword,
+    theme_preference: row.themePreference ?? null,
+    created_at: row.createdAt,
+    updated_at: row.updatedAt,
+  };
+}
+
+/** ISO-8601 timestamp with millisecond precision. */
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+/**
+ * Generates a 16-character alphanumeric password ([A-Za-z0-9]).
+ *
+ * Uses rejection sampling against the 62-char alphabet — every char is drawn
+ * uniformly via `randomBytes`, masked to 6 bits, then discarded if the value
+ * lands in the unused `[62, 64)` range. Average overhead is ~3%.
+ *
+ * The generated password trivially satisfies the §8.5 complexity policy
+ * (letters + digits = 2 categories), so no extra validation is needed before
+ * hashing. The 16-char length is also above the §8.5 8-char minimum.
+ *
+ * @returns a fresh 16-char alphanumeric password.
+ */
+function generatePassword(): string {
+  const alphabet =
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  const out: string[] = [];
+  while (out.length < 16) {
+    const bytes = randomBytes(32);
+    for (const b of bytes) {
+      const v = b & 0b00111111;
+      if (v < alphabet.length) {
+        out.push(alphabet[v] as string);
+        if (out.length === 16) break;
+      }
+    }
+  }
+  return out.join("");
+}
+
+/**
+ * Returns `true` if the caller's role is allowed to create / promote a user
+ * to `targetRole`. Admins cannot touch `super_admin`; super-admins can do
+ * anything.
+ *
+ * @param caller - caller role.
+ * @param targetRole - the requested role for the new (or promoted) user.
+ * @returns `true` if the operation is permitted.
+ */
+function callerCanGrantRole(caller: AIHubRole, targetRole: AIHubRole): boolean {
+  if (caller === "super_admin") return true;
+  if (caller === "admin") return targetRole !== "super_admin";
+  return false;
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  GET /admin/users                                                          */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `GET /admin/users` — list every user in the deployment.
+ *
+ * `admin` and `super_admin` only; gated by `protectedRoute({ requiredRole: "admin" })`.
+ * Sorted alphabetically by username for stable rendering in the admin table.
+ *
+ * @see SPECIFICATIONS.md §6.3.4
+ * @see ui-sketches/05-admin-users.md
+ */
+export const handleListUsers: RouteHandler = protectedRoute(
+  { requiredRole: "admin" },
+  async (_req, ctx) => {
+    const rows = ctx.db.select().from(user).all();
+    // Sort client-side for a stable order regardless of insert order.
+    rows.sort((a, b) => a.username.localeCompare(b.username));
+    return jsonResponse(200, { users: rows.map(adminUserView) });
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  POST /admin/users                                                         */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Body for `POST /admin/users`. `role` defaults to `user` per §6.3.4. */
+const createUserSchema = z
+  .object({
+    username: z.string().min(1).max(255),
+    display_name: z.string().min(1).max(255).nullish(),
+    role: z
+      .enum(["user", "power_user", "admin", "super_admin"])
+      .optional(),
+  })
+  .strict();
+
+/**
+ * `POST /admin/users` — create a new user with a server-generated password.
+ *
+ * The 16-char alphanumeric plaintext is returned **exactly once** in the
+ * response (`{ user, generated_password }`); the caller (admin) is expected
+ * to deliver it out-of-band per §8.5. The plaintext never appears in logs
+ * (pino's redaction policy plus we never log the field).
+ *
+ * Caller-role gates:
+ *
+ * - `admin` can create role `user` / `power_user` / `admin`.
+ * - `super_admin` can additionally create `super_admin`.
+ *
+ * On username collision returns 409 `username_taken` (not 400) — the request
+ * itself was well-formed; the conflict is with existing data.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 / §8.5
+ * @see ui-sketches/05-admin-users.md
+ */
+export const handleCreateUser: RouteHandler = protectedRoute(
+  { requiredRole: "admin" },
+  async (req, ctx, auth) => {
+    let raw: unknown;
+    try {
+      raw = await req.json();
+    } catch {
+      return validationError("Request body must be valid JSON.");
+    }
+    const parsed = createUserSchema.safeParse(raw);
+    if (!parsed.success) {
+      return validationError(parsed.error.issues[0]?.message ?? "Invalid request body.");
+    }
+    const body = parsed.data;
+    const role: AIHubRole = body.role ?? "user";
+    if (!callerCanGrantRole(auth.role, role)) {
+      return forbidden(
+        `Caller role ${auth.role} cannot create a user with role ${role}.`,
+      );
+    }
+
+    const existing = ctx.db
+      .select({ id: user.id })
+      .from(user)
+      .where(eq(user.username, body.username))
+      .get();
+    if (existing) {
+      return conflictError("username_taken", "Username is already in use.");
+    }
+
+    const plaintext = generatePassword();
+    const passwordHash = await hashPassword(plaintext);
+    const id = randomUUID();
+    try {
+      ctx.db
+        .insert(user)
+        .values({
+          id,
+          username: body.username,
+          displayName: body.display_name ?? null,
+          passwordHash,
+          identitySource: "local",
+          isInitialPassword: true,
+          role,
+        })
+        .run();
+    } catch (err) {
+      // Race against another simultaneous create with the same username.
+      const message = err instanceof Error ? err.message : String(err);
+      if (message.includes("UNIQUE")) {
+        return conflictError("username_taken", "Username is already in use.");
+      }
+      throw err;
+    }
+
+    const row = ctx.db.select().from(user).where(eq(user.id, id)).get();
+    if (!row) throw new Error("Just-inserted user vanished.");
+
+    ctx.logger.info(
+      {
+        actor_id: auth.user.id,
+        new_user_id: row.id,
+        new_role: row.role,
+        event: "admin_user_created",
+      },
+      "Admin created a new user.",
+    );
+
+    return jsonResponse(201, {
+      user: adminUserView(row),
+      generated_password: plaintext,
+    });
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  PATCH /admin/users/:id/role                                                */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Body for `PATCH /admin/users/:id/role`. */
+const patchRoleSchema = z
+  .object({
+    role: z.enum(["user", "power_user", "admin", "super_admin"]),
+  })
+  .strict();
+
+/**
+ * `PATCH /admin/users/:id/role` — change a user's role.
+ *
+ * Delegates the shield + min-count check to `applyUserRoleChangeInTx`, which
+ * re-reads the target row + super-admin count inside one transaction so a
+ * concurrent demote cannot bypass the invariants.
+ *
+ * Additional caller-role gate on top of the helper: an `admin` cannot grant
+ * the `super_admin` role on a target they could otherwise mutate (e.g.
+ * promoting a `power_user → super_admin`) — only super-admins can.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 / §8.1
+ */
+export const handlePatchUserRole: RouteHandler = protectedRoute(
+  { requiredRole: "admin" },
+  async (req, ctx, auth, params) => {
+    const id = params.id;
+    if (!id) return notFound();
+    let raw: unknown;
+    try {
+      raw = await req.json();
+    } catch {
+      return validationError("Request body must be valid JSON.");
+    }
+    const parsed = patchRoleSchema.safeParse(raw);
+    if (!parsed.success) {
+      return validationError(parsed.error.issues[0]?.message ?? "Invalid request body.");
+    }
+    const newRole: AIHubRole = parsed.data.role;
+    if (!callerCanGrantRole(auth.role, newRole)) {
+      return forbidden(
+        `Caller role ${auth.role} cannot promote a user to ${newRole}.`,
+      );
+    }
+
+    const result = applyUserRoleChangeInTx(
+      ctx.db,
+      { id: auth.user.id, role: auth.role },
+      id,
+      newRole,
+    );
+    if (!result.ok) {
+      return errorResponse(result.status, result.code, result.message);
+    }
+
+    ctx.logger.info(
+      {
+        actor_id: auth.user.id,
+        target_id: id,
+        new_role: newRole,
+        event: "admin_role_changed",
+      },
+      "Admin changed a user's role.",
+    );
+
+    return jsonResponse(200, { user: adminUserView(result.data.updated) });
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  POST /admin/users/:id/reset-password                                      */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `POST /admin/users/:id/reset-password` — regenerate the user's password.
+ *
+ * Uses `assertPasswordResetInTx` to validate shield + min-count inside a
+ * transaction, then performs the async Argon2 hash + UPDATE *outside* the
+ * transaction (better-sqlite3 transactions are synchronous). The narrow
+ * window between assertion and write is acceptable in v1 — a concurrent
+ * role-mutation could in theory bypass the rule, but the worst-case is a
+ * single password reset on a user the admin shouldn't have been able to
+ * touch; the admin already had to authenticate and the new password is
+ * displayed only to them. Mitigation if this ever bites: re-verify the
+ * caller's role hasn't dropped between assertion and write.
+ *
+ * Returns `{ generated_password }` exactly once. Sets `is_initial_password =
+ * true` so the user is forced to change on their next login.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 / §8.5
+ * @see ui-sketches/05-admin-users.md
+ */
+export const handleResetUserPassword: RouteHandler = protectedRoute(
+  { requiredRole: "admin" },
+  async (_req, ctx, auth, params) => {
+    const id = params.id;
+    if (!id) return notFound();
+
+    const result = assertPasswordResetInTx(
+      ctx.db,
+      { id: auth.user.id, role: auth.role },
+      id,
+    );
+    if (!result.ok) {
+      return errorResponse(result.status, result.code, result.message);
+    }
+
+    const plaintext = generatePassword();
+    const newHash = await hashPassword(plaintext);
+    const now = nowIso();
+    ctx.db
+      .update(user)
+      .set({
+        passwordHash: newHash,
+        isInitialPassword: true,
+        // Bumping `passwordChangedAt` invalidates the target's existing
+        // session JWTs (the middleware compares `iat` against this column)
+        // — the user is signed out from every device the next time their
+        // browser fires a protected request. Step 11 bugfix per the
+        // SPECIFICATIONS.md §8.5 password-reset semantics.
+        passwordChangedAt: now,
+        updatedAt: now,
+      })
+      .where(eq(user.id, id))
+      .run();
+
+    ctx.logger.info(
+      {
+        actor_id: auth.user.id,
+        target_id: id,
+        event: "admin_password_reset",
+      },
+      "Admin reset a user's password.",
+    );
+
+    return jsonResponse(200, { generated_password: plaintext });
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  DELETE /admin/users/:id                                                   */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `DELETE /admin/users/:id` — hard-delete the user.
+ *
+ * Uses `applyUserDeletionInTx`; the FK on `session.user_id` cascades, so
+ * deleting a user removes all their sessions atomically. The shield + min-
+ * count invariants apply (an admin cannot delete another admin or super
+ * admin; nobody can delete the only super admin).
+ *
+ * @see SPECIFICATIONS.md §6.3.4 / §8.1
+ */
+export const handleDeleteUser: RouteHandler = protectedRoute(
+  { requiredRole: "admin" },
+  async (_req, ctx, auth, params) => {
+    const id = params.id;
+    if (!id) return notFound();
+    if (id === auth.user.id) {
+      // Defensive: even though min-count would catch the only-super_admin
+      // self-delete, we block all self-deletes outright as a usability
+      // safeguard (deleting yourself logs you out and could brick the UI).
+      return forbidden("Cannot delete your own account.");
+    }
+    const result = applyUserDeletionInTx(
+      ctx.db,
+      { id: auth.user.id, role: auth.role },
+      id,
+    );
+    if (!result.ok) {
+      return errorResponse(result.status, result.code, result.message);
+    }
+    ctx.logger.info(
+      {
+        actor_id: auth.user.id,
+        target_id: id,
+        event: "admin_user_deleted",
+      },
+      "Admin deleted a user.",
+    );
+    return jsonResponse(200, { deleted: { id } });
+  },
+);

package/src/routes/agents.ts

@@ -0,0 +1,66 @@
+/**
+ * User-facing `/agents` — the catalog the agents picker reads.
+ *
+ * Returns **non-archived** ai-hub agents only; each entry carries a
+ * `session_count` computed against the *caller's* non-archived sessions for
+ * that agent (one round-trip populates the "(N of your sessions)" subtitles
+ * on the picker — see [03-chat.md](../../../../docs/ui-sketches/03-chat.md)).
+ *
+ * The underlying Letta `agent_id` is **not** exposed here — it's an admin-only
+ * concern (`/admin/agents` returns it for editors).
+ *
+ * @see SPECIFICATIONS.md §6.3.3 — Agents (catalog)
+ */
+
+import { and, asc, eq, sql } from "drizzle-orm";
+
+import { protectedRoute } from "../auth/middleware.js";
+import { agent, session } from "../db/schema.js";
+import { jsonResponse } from "../handlers/responses.js";
+import type { RouteHandler } from "../handlers/types.js";
+
+/**
+ * `GET /agents` — every authenticated session.
+ *
+ * Returns `{ agents: [{ id, display_name, session_count }, ...] }`. Sorted by
+ * `display_name` for stable picker ordering. Excludes archived agents
+ * server-side so the user-facing picker stays focused on the working set.
+ *
+ * The `session_count` is **caller-scoped** — counted via a left-join filtered
+ * to `(session.user_id = caller.id AND session.is_archived = false)` so each
+ * user sees their own count, never another user's.
+ *
+ * @see SPECIFICATIONS.md §6.3.3 — Agents (catalog)
+ * @see ui-sketches/03-chat.md — agents picker
+ */
+export const handleListAgents: RouteHandler = protectedRoute({}, async (_req, ctx, auth) => {
+  const rows = ctx.db
+    .select({
+      id: agent.id,
+      displayName: agent.displayName,
+      // Count caller's non-archived sessions against this agent. The
+      // double-condition LEFT JOIN keeps agents with 0 sessions in the result.
+      sessionCount: sql<number>`COUNT(${session.id})`.as("session_count"),
+    })
+    .from(agent)
+    .leftJoin(
+      session,
+      and(
+        eq(session.agentId, agent.id),
+        eq(session.userId, auth.user.id),
+        eq(session.isArchived, false),
+      ),
+    )
+    .where(eq(agent.isArchived, false))
+    .groupBy(agent.id)
+    .orderBy(asc(agent.displayName))
+    .all();
+
+  return jsonResponse(200, {
+    agents: rows.map((r) => ({
+      id: r.id,
+      display_name: r.displayName,
+      session_count: Number(r.sessionCount),
+    })),
+  });
+});