agent-relay-server 0.83.1 → 0.84.0

package/src/auth/password.ts

@@ -0,0 +1,122 @@
+// Password authentication provider (#389). The only built-in provider in Phase 1. Secrets are
+// hashed with scrypt (node:crypto — no dependency) and compared with `timingSafeEqual`, the same
+// constant-time primitive the token layer uses. The hash is stored in `auth_identities.secret_hash`
+// keyed by (provider="password", provider_subject=<username>).
+import { randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
+import { createAuthIdentity, getAuthIdentity, type AuthIdentity } from "../db/auth-identities.ts";
+import { isRecord } from "agent-relay-sdk";
+import type { AuthProvider, AuthVerifyResult } from "./provider.ts";
+
+/** The provider id stored in `auth_identities.provider` and sent in a login request's `provider`. */
+export const PASSWORD_PROVIDER_ID = "password";
+
+// scrypt cost parameters. N=2^14 keeps 128*N*r ≈ 16MB under node's 32MB default maxmem; r=8/p=1 are
+// the standard interactive-login settings. keylen 64. Encoded into the hash string so a future cost
+// bump stays verifiable against existing hashes.
+const SCRYPT_N = 16384;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+const KEYLEN = 64;
+const SALT_BYTES = 16;
+export const DUMMY_PASSWORD_HASH =
+  `scrypt$${SCRYPT_N}$${SCRYPT_R}$${SCRYPT_P}$${"00".repeat(SALT_BYTES)}$${"00".repeat(KEYLEN)}`;
+
+type PasswordVerifier = (password: string, stored: string | null) => boolean;
+type PasswordIdentityLookup = (provider: string, providerSubject: string) => AuthIdentity | undefined;
+
+interface PasswordVerifyAttempt {
+  valid: boolean;
+  attemptedKdf: boolean;
+}
+
+/** Hash a plaintext password into a self-describing `scrypt$N$r$p$saltHex$hashHex` string. */
+export function hashPassword(password: string): string {
+  const salt = randomBytes(SALT_BYTES);
+  const derived = scryptSync(password, salt, KEYLEN, { N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P });
+  return `scrypt$${SCRYPT_N}$${SCRYPT_R}$${SCRYPT_P}$${salt.toString("hex")}$${derived.toString("hex")}`;
+}
+
+function verifyPasswordAttempt(password: string, stored: string | null): PasswordVerifyAttempt {
+  if (!stored) return { valid: false, attemptedKdf: false };
+  const parts = stored.split("$");
+  if (parts.length !== 6 || parts[0] !== "scrypt") return { valid: false, attemptedKdf: false };
+  const [, nRaw, rRaw, pRaw, saltHex, hashHex] = parts as [string, string, string, string, string, string];
+  const N = Number(nRaw);
+  const r = Number(rRaw);
+  const p = Number(pRaw);
+  if (!Number.isInteger(N) || !Number.isInteger(r) || !Number.isInteger(p)) return { valid: false, attemptedKdf: false };
+  const expected = Buffer.from(hashHex, "hex");
+  if (expected.length <= 0) return { valid: false, attemptedKdf: false };
+  let derived: Buffer;
+  try {
+    derived = scryptSync(password, Buffer.from(saltHex, "hex"), expected.length, { N, r, p });
+  } catch {
+    return { valid: false, attemptedKdf: false };
+  }
+  return { valid: derived.length === expected.length && timingSafeEqual(derived, expected), attemptedKdf: true };
+}
+
+/** Constant-time verify a plaintext password against a stored `scrypt$...` hash. */
+export function verifyPassword(password: string, stored: string | null): boolean {
+  return verifyPasswordAttempt(password, stored).valid;
+}
+
+function verifyPasswordWithDummyFallback(password: string, stored: string | null): boolean {
+  const result = verifyPasswordAttempt(password, stored);
+  if (result.attemptedKdf) return result.valid;
+  verifyPasswordAttempt(password, DUMMY_PASSWORD_HASH);
+  return false;
+}
+
+/**
+ * Link a password login to a user (admin pre-link / first-user bootstrap). Hashes the password and
+ * inserts an `auth_identities` row. `username` is the `provider_subject` the user logs in with.
+ */
+export function createPasswordIdentity(input: {
+  userId: string;
+  username: string;
+  password: string;
+  metadata?: Record<string, unknown>;
+}): AuthIdentity {
+  return createAuthIdentity({
+    userId: input.userId,
+    provider: PASSWORD_PROVIDER_ID,
+    providerSubject: input.username,
+    secretHash: hashPassword(input.password),
+    metadata: input.metadata,
+  });
+}
+
+/** Parse `{ username, password }` from a login request body. */
+function readCredentials(credentials: unknown): { username: string; password: string } | null {
+  if (!isRecord(credentials)) return null;
+  const username = credentials.username ?? credentials.handle ?? credentials.email;
+  const password = credentials.password;
+  if (typeof username !== "string" || !username || typeof password !== "string" || !password) return null;
+  return { username, password };
+}
+
+export function verifyPasswordCredentials(
+  credentials: unknown,
+  opts: { lookupIdentity?: PasswordIdentityLookup; verifyStoredPassword?: PasswordVerifier } = {},
+): AuthVerifyResult | null {
+  const creds = readCredentials(credentials);
+  if (!creds) return null;
+  const lookupIdentity = opts.lookupIdentity ?? getAuthIdentity;
+  const verifyStoredPassword = opts.verifyStoredPassword ?? verifyPasswordWithDummyFallback;
+  const identity = lookupIdentity(PASSWORD_PROVIDER_ID, creds.username);
+  const passwordMatches = verifyStoredPassword(creds.password, identity?.secretHash ?? DUMMY_PASSWORD_HASH);
+  if (!identity || !passwordMatches) return null;
+  return { providerSubject: creds.username };
+}
+
+export const passwordAuthProvider: AuthProvider = {
+  id: PASSWORD_PROVIDER_ID,
+  displayName: "Password",
+  flow: "password",
+  verify(credentials: unknown): AuthVerifyResult | null {
+    // Unknown username, malformed stored hash, and wrong password all pay one scrypt verification
+    // before returning null, so login failure timing does not identify linked accounts.
+    return verifyPasswordCredentials(credentials);
+  },
+};

package/src/auth/provider.ts

@@ -0,0 +1,60 @@
+// Pluggable authentication providers (#389). An AuthProvider turns a login request into a
+// `providerSubject` — the stable external identifier (a username, an OAuth `sub`, an email) that
+// `auth_identities` maps onto a `users.id`. The login route is provider-agnostic: it resolves the
+// provider, calls `verify()`, then looks the returned subject up in `auth_identities`. Adding a
+// provider (GitHub OAuth in Phase 2, magic-link, …) is a `register()` call plus rows — no schema
+// change, no route change (the pluggability guarantee #389 must hold).
+//
+// In-process registry. The registry knows ONLY the interface — concrete providers register
+// themselves via the composition root (src/auth/index.ts), which keeps this module free of any
+// dependency on a concrete provider (no registry ↔ plugin cycle).
+
+/** How a provider proves identity — drives the login UI and which fields `verify()` reads. */
+export type AuthProviderFlow = "password" | "oauth" | "magic-link";
+
+/** Result of a successful `verify()`: the external subject to resolve against `auth_identities`. */
+export interface AuthVerifyResult {
+  providerSubject: string;
+  /** Optional provider-supplied profile bits (display name, email) for first-link/auto-provision. */
+  profile?: Record<string, unknown>;
+}
+
+export interface AuthProvider {
+  /** Stable id; the `auth_identities.provider` value and the `provider` field a login request sends. */
+  id: string;
+  /** Human label for the login UI. */
+  displayName: string;
+  flow: AuthProviderFlow;
+  /**
+   * Begin an interactive (redirect) flow — returns where to send the user (e.g. an OAuth authorize
+   * URL). Optional: password is single-step and omits it. Phase 2 (GitHub OAuth) implements it.
+   */
+  begin?(req: Request): Promise<{ redirectUrl: string } | null> | ({ redirectUrl: string } | null);
+  /**
+   * Verify the presented credentials and return the authenticated subject, or null on failure.
+   * MUST be constant-ish on failure (no "unknown user" vs "bad password" distinction leaking to
+   * the caller — both return null). The route maps a non-null subject to a user.
+   */
+  verify(credentials: unknown): Promise<AuthVerifyResult | null> | (AuthVerifyResult | null);
+}
+
+const registry = new Map<string, AuthProvider>();
+
+/** Register (or replace) a provider. Idempotent by id — re-registering overrides, which is how
+ * tests install a throwaway provider to prove pluggability. */
+export function registerAuthProvider(provider: AuthProvider): void {
+  registry.set(provider.id, provider);
+}
+
+/** Remove a provider by id (test teardown / runtime disable). Returns true if one was removed. */
+export function unregisterAuthProvider(id: string): boolean {
+  return registry.delete(id);
+}
+
+export function getAuthProvider(id: string): AuthProvider | undefined {
+  return registry.get(id);
+}
+
+export function listAuthProviders(): AuthProvider[] {
+  return [...registry.values()];
+}

package/src/auth/session.ts

@@ -0,0 +1,92 @@
+// Human session tokens (#389). A session is a component token minted via the existing `createToken`
+// — the `tokens` table IS the session store, so `verifyComponentToken` already enforces expiry and
+// revocation, and "sign out everywhere" is just revoking every token for a `sub`. The session token
+// reuses ONLY the signing primitive: it carries a new `sub` namespace (`user:<id>`) and a new
+// `role` ("user"), so no machine-token path branches on it.
+import { userSinkId, userIdFromAddress, isHumanAgentId, type User, type UserRole } from "agent-relay-sdk";
+import { createToken } from "../token-db.ts";
+import { verifyComponentToken } from "../security.ts";
+import { getUser } from "../db/users.ts";
+import type { ComponentToken } from "../types.ts";
+
+/** Access token lifetime (~1h) — short, because refresh re-mints it silently. */
+export const ACCESS_TTL_SECONDS = 60 * 60;
+/** Refresh token lifetime (~30d) — the dashboard re-mints the access token until this expires. */
+export const REFRESH_TTL_SECONDS = 30 * 24 * 60 * 60;
+/** Marker scope carried ONLY by refresh tokens. It matches no route's required scope, so a refresh
+ * token can never act as an access token; the refresh route validates it explicitly. */
+export const REFRESH_SCOPE = "auth:refresh";
+
+/** The `role` stamped on a human session token. New namespace — no machine path branches on it. */
+export const USER_TOKEN_ROLE = "user";
+
+/**
+ * Map a user role to the scopes its session carries. STOPGAP for #392 (real RBAC): admins get full
+ * access via the `admin:*` alias (→ `system:admin`, which `hasScope` short-circuits everywhere), and
+ * everyone else gets a read-only baseline. When #392 lands the per-role scope matrix, replace this
+ * one function — every session inherits the new policy with no other change.
+ */
+export function scopesForUserRole(role: UserRole): string[] {
+  if (role === "admin") return ["admin:*"];
+  if (role === "operator") return ["agent:read", "agent:write", "message:read", "message:send", "task:read", "task:write"];
+  return ["agent:read", "message:read", "task:read"];
+}
+
+export interface MintedSession {
+  accessToken: string;
+  refreshToken: string;
+  accessJti: string;
+  refreshJti: string;
+  expiresIn: number;
+}
+
+/**
+ * Mint an access + refresh token pair for a logged-in user. `constraints.tenantId` carries the
+ * SaaS seam (identity-only — enforces nothing). Both tokens share the `user:<id>` sub so a single
+ * "sign out everywhere" revoke (by sub) kills the whole session family.
+ */
+export function mintUserSession(user: User): MintedSession {
+  const sub = userSinkId(user.id);
+  const constraints = user.tenantId ? { tenantId: user.tenantId } : undefined;
+  const access = createToken({
+    sub,
+    role: USER_TOKEN_ROLE,
+    scope: scopesForUserRole(user.role),
+    constraints,
+    ttlSeconds: ACCESS_TTL_SECONDS,
+    createdBy: `auth:login:${user.id}`,
+  });
+  const refresh = createToken({
+    sub,
+    role: USER_TOKEN_ROLE,
+    scope: [REFRESH_SCOPE],
+    constraints,
+    ttlSeconds: REFRESH_TTL_SECONDS,
+    createdBy: `auth:refresh:${user.id}`,
+  });
+  return {
+    accessToken: access.token,
+    refreshToken: refresh.token,
+    accessJti: access.record.jti,
+    refreshJti: refresh.record.jti,
+    expiresIn: ACCESS_TTL_SECONDS,
+  };
+}
+
+/**
+ * Validate a refresh token and resolve it to its live user. Returns null unless the token verifies
+ * (signature + unexpired + unrevoked, via `verifyComponentToken`), carries the refresh scope, names
+ * a human `sub`, and that user still exists and is active. The caller mints a fresh session for the
+ * user.
+ */
+export function resolveRefreshToken(token: string): { user: User; payload: ComponentToken } | null {
+  const payload = verifyComponentToken(token);
+  if (!payload) return null;
+  if (!payload.scope.includes(REFRESH_SCOPE)) return null;
+  if (!isHumanAgentId(payload.sub)) return null;
+  const userId = userIdFromAddress(payload.sub);
+  if (!userId) return null;
+  const user = getUser(userId);
+  if (!user || user.status !== "active") return null;
+  return { user, payload };
+}

package/src/db/auth-identities.ts

@@ -0,0 +1,119 @@
+// Pluggable authentication identities (#389 auth & sessions). Maps an external login —
+// a (provider, provider_subject) pair such as ("password", "admin") or ("github", "12345") —
+// onto a relational `users.id`. The login flow authenticates a provider_subject, looks it up
+// here, and mints a session token for the resolved user. Provider-agnostic by construction:
+// `secret_hash` is nullable so an OAuth/magic-link identity is just a row with no stored secret —
+// a new provider needs ZERO schema change (the #389 pluggability guarantee).
+//
+// DDL home (single owner; the barrel re-exports, never inlines DDL). Wired into applyMigrations
+// right after seedDefaultUser(), mirroring the idempotent ensureUsersSchema() pattern.
+import { randomUUID } from "node:crypto";
+import { getDb } from "./connection.ts";
+
+export interface AuthIdentity {
+  id: string;
+  userId: string;
+  provider: string;
+  providerSubject: string;
+  /** Opaque provider-managed secret material (e.g. a scrypt password hash). Null for secretless
+   * providers (OAuth, magic-link) whose proof lives with the upstream provider, not here. */
+  secretHash: string | null;
+  metadata: Record<string, unknown>;
+  createdAt: number;
+}
+
+interface AuthIdentityRow {
+  id: string;
+  user_id: string;
+  provider: string;
+  provider_subject: string;
+  secret_hash: string | null;
+  metadata: string | null;
+  created_at: number;
+}
+
+/**
+ * Single DDL home for `auth_identities` (#389). Idempotent (CREATE TABLE IF NOT EXISTS), so it is
+ * safe on every boot/migration — an old single-user DB gains the table on upgrade, with zero rows,
+ * and the god-token break-glass keeps working without any identity present. `UNIQUE(provider,
+ * provider_subject)` makes a login subject resolve to exactly one identity; `user_id` cascades on
+ * user delete so removing a human drops their logins.
+ */
+export function ensureAuthIdentitiesSchema(): void {
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS auth_identities (
+      id TEXT PRIMARY KEY,
+      user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+      provider TEXT NOT NULL,
+      provider_subject TEXT NOT NULL,
+      secret_hash TEXT,
+      metadata TEXT NOT NULL DEFAULT '{}',
+      created_at INTEGER NOT NULL,
+      UNIQUE(provider, provider_subject)
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_auth_identities_user ON auth_identities(user_id)");
+}
+
+function rowToIdentity(row: AuthIdentityRow): AuthIdentity {
+  return {
+    id: row.id,
+    userId: row.user_id,
+    provider: row.provider,
+    providerSubject: row.provider_subject,
+    secretHash: row.secret_hash,
+    metadata: row.metadata ? (JSON.parse(row.metadata) as Record<string, unknown>) : {},
+    createdAt: row.created_at,
+  };
+}
+
+/** Resolve a login subject to its identity, or undefined if no such (provider, subject) exists. */
+export function getAuthIdentity(provider: string, providerSubject: string): AuthIdentity | undefined {
+  const row = getDb()
+    .query("SELECT * FROM auth_identities WHERE provider = ? AND provider_subject = ?")
+    .get(provider, providerSubject) as AuthIdentityRow | null;
+  return row ? rowToIdentity(row) : undefined;
+}
+
+/** All identities linked to a user — used by account UIs and "unlink provider" flows. */
+export function listAuthIdentitiesForUser(userId: string): AuthIdentity[] {
+  const rows = getDb()
+    .query("SELECT * FROM auth_identities WHERE user_id = ? ORDER BY created_at")
+    .all(userId) as AuthIdentityRow[];
+  return rows.map(rowToIdentity);
+}
+
+/**
+ * Link a login to a user. `secretHash` is null for secretless providers. Throws on a duplicate
+ * (provider, provider_subject) — the caller surfaces it as a 409/validation error.
+ */
+export function createAuthIdentity(input: {
+  userId: string;
+  provider: string;
+  providerSubject: string;
+  secretHash?: string | null;
+  metadata?: Record<string, unknown>;
+}): AuthIdentity {
+  const id = randomUUID();
+  const now = Date.now();
+  getDb()
+    .query(
+      `INSERT INTO auth_identities (id, user_id, provider, provider_subject, secret_hash, metadata, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    )
+    .run(
+      id,
+      input.userId,
+      input.provider,
+      input.providerSubject,
+      input.secretHash ?? null,
+      JSON.stringify(input.metadata ?? {}),
+      now,
+    );
+  return getAuthIdentity(input.provider, input.providerSubject)!;
+}
+
+/** Remove an identity by id. Returns true if a row was deleted. */
+export function deleteAuthIdentity(id: string): boolean {
+  return getDb().query("DELETE FROM auth_identities WHERE id = ?").run(id).changes > 0;
+}

package/src/db/index.ts

@@ -17,6 +17,7 @@ export * from "./delivery.ts";
 export * from "./message-reads.ts";
 export * from "./inbox.ts";
 export * from "./users.ts";
+export * from "./auth-identities.ts";
 export * from "./agent-ownership.ts";
 export * from "./drive-leases.ts";
 export * from "./activity.ts";

package/src/db/migrations.ts

@@ -16,6 +16,7 @@ import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_ME
 import { matchAgents } from "../agent-ref";
 import { getDb } from "./connection.ts";
 import { ensureUsersSchema, seedDefaultUser } from "./users.ts";
+import { ensureAuthIdentitiesSchema } from "./auth-identities.ts";
 import { ensureAgentOwnershipSchema, seedDefaultAgentOwnership } from "./agent-ownership.ts";
 import { ensureDriveLeaseSchema } from "./drive-leases.ts";
 import { ensureContinuationArchiveSearchSchema } from "./continuation-archives.ts";
@@ -800,6 +801,11 @@ export function applyMigrations(): void {
   ensureUsersSchema();
   seedDefaultUser();
 
+  // Pluggable login identities (#389): the (provider, provider_subject) → users.id map behind real
+  // login + sessions. Ensured right after the user seed (FK → users) and idempotent — an old
+  // single-user DB gains it empty, and the god-token break-glass keeps working with zero rows.
+  ensureAuthIdentitiesSchema();
+
   // Agent ownership/visibility table (#392). FK-references both agents and users, so it ensures
   // AFTER both exist. The backfill (seedDefaultAgentOwnership) runs below, once the built-in
   // agents are in, so they can be excluded from ownership.

package/src/index.ts

@@ -268,7 +268,12 @@ export function createFetchHandler(
     const matched = matchRoute(req.method, url.pathname);
     if (matched) {
       const publicPaths = ["/api/spec", "/api/docs", "/api/health"];
-      if (!publicPaths.includes(url.pathname)) {
+      // Pre-auth allowlist (#389): the auth endpoints must be reachable unauthenticated — they ARE
+      // the way a session is obtained. Each handler self-authenticates (login verifies credentials,
+      // refresh validates the refresh token, logout revokes the presented token). Everything else
+      // still flows through the component-token gate below.
+      const publicAuthPaths = ["/api/auth/providers", "/api/auth/login", "/api/auth/refresh", "/api/auth/logout"];
+      if (!publicPaths.includes(url.pathname) && !publicAuthPaths.includes(url.pathname)) {
         const integrationAuth = getIntegrationAuth(req);
         const componentAuth = getComponentAuth(req);
         const handlerOwnsScopedAuth = url.pathname === "/api/tokens/me" ||

package/src/routes/_shared.ts

@@ -5,7 +5,7 @@ import { ValidationError, createActivityEvent, createCallbackDelivery, finishCal
 import { cleanEpoch, cleanString, optionalEnum } from "../validation";
 import { emitActivityEvent, emitMessageQueued, emitNewMessage } from "../sse";
 import { emitRelayEvent } from "../events";
-import { canonicalHumanAgentId, DEFAULT_USER_ID, errMessage, isRecord, userSinkId } from "agent-relay-sdk";
+import { canonicalHumanAgentId, DEFAULT_USER_ID, errMessage, isHumanAgentId, isRecord, userIdFromAddress, userSinkId } from "agent-relay-sdk";
 import { authorizeAgentForUser, visibleAgentIdsForUser, type AgentAction } from "../agent-authz";
 import { generateSpawnRequestId } from "../spawn-command";
 import { getComponentAuth, getIntegrationAuth, isAuthorized, isRequestAuthorizedFor } from "../security";
@@ -58,13 +58,51 @@ export function authAuditMetadata(req: Request): Record<string, unknown> {
       },
     };
   }
-  return hasPresentedCredential(req) ? { auth: { type: "root" } } : {};
+  if (!hasPresentedCredential(req)) return {};
+  // Root (god-token) credential: stamp the seeded-admin identity it now carries (#389 break-glass),
+  // so the audit trail records *who* acted instead of an anonymous root.
+  const acting = resolveActingUser(req);
+  return acting
+    ? { auth: { type: "root", userId: acting.userId, source: acting.source } }
+    : { auth: { type: "root" } };
 }
 
 export function isRootCredentialRequest(req: Request): boolean {
   return hasPresentedCredential(req) && isAuthorized(req) && !getComponentAuth(req) && !getIntegrationAuth(req);
 }
 
+/**
+ * Which human is acting, and how their request was authenticated (#389). The single bridge from a
+ * request to a `users.id`:
+ * - a human session token (component token whose `sub` is a `user:<id>` address) → that user, via
+ *   the SDK resolver (never a hand-rolled namespace) — `source: "session"`;
+ * - the raw god-token / root credential (`isRootCredentialRequest`) → the seeded admin
+ *   `DEFAULT_USER_ID` with `source: "break-glass"`. This is what gives the env token an *identity*
+ *   instead of the anonymous "server" it carried before, while it KEEPS bypassing scope checks
+ *   unchanged (the gate in src/index.ts is untouched). Works with zero `auth_identities` rows, so
+ *   it is simultaneously the break-glass path and the first-user bootstrap.
+ *
+ * Returns null for a machine component/integration token (no human is acting).
+ */
+export type ActingUserSource = "session" | "break-glass";
+
+export interface ActingUser {
+  userId: string;
+  source: ActingUserSource;
+}
+
+export function resolveActingUser(req: Request): ActingUser | null {
+  const component = getComponentAuth(req);
+  if (component && isHumanAgentId(component.sub)) {
+    const userId = userIdFromAddress(component.sub);
+    if (userId) return { userId, source: "session" };
+  }
+  if (isRootCredentialRequest(req)) {
+    return { userId: DEFAULT_USER_ID, source: "break-glass" };
+  }
+  return null;
+}
+
 function sanitizeAttribution(raw: unknown): string | undefined {
   if (typeof raw !== "string") return undefined;
   // eslint-disable-next-line no-control-regex

package/src/routes/auth.ts

@@ -0,0 +1,107 @@
+// Authentication & session routes (#389). These four paths sit on a pre-auth PUBLIC ALLOWLIST
+// (src/index.ts) so they are reachable unauthenticated — each handler owns its own auth: login
+// verifies credentials, refresh validates the refresh token, logout revokes the presented session.
+// Everything else on the relay still flows through the existing component-token gate.
+import { isRecord, type User } from "agent-relay-sdk";
+import { error, json, parseBody, type Handler } from "./_shared";
+import { getAuthProvider, listAuthProviders, mintUserSession, resolveRefreshToken } from "../auth";
+import { getAuthIdentity, getUser } from "../db";
+import { revokeToken } from "../token-db.ts";
+import { getComponentAuth } from "../security";
+
+/** Public projection of a user for login/refresh responses — never leaks internal-only columns. */
+function userView(user: User): Record<string, unknown> {
+  return {
+    id: user.id,
+    handle: user.handle,
+    displayName: user.displayName,
+    role: user.role,
+    tenantId: user.tenantId,
+    avatarUrl: user.avatarUrl,
+  };
+}
+
+function sessionResponse(user: User): Response {
+  const session = mintUserSession(user);
+  return json({
+    tokenType: "Bearer",
+    accessToken: session.accessToken,
+    refreshToken: session.refreshToken,
+    expiresIn: session.expiresIn,
+    user: userView(user),
+  });
+}
+
+/** GET /api/auth/providers — the login screen reads this to render available login methods. */
+export const getAuthProvidersRoute: Handler = () =>
+  json({
+    providers: listAuthProviders().map((provider) => ({
+      id: provider.id,
+      displayName: provider.displayName,
+      flow: provider.flow,
+    })),
+  });
+
+/**
+ * POST /api/auth/login — body `{ provider, ...credentials }`. Resolves the provider, verifies the
+ * credentials to a `providerSubject`, maps it through `auth_identities` to a user, and mints a
+ * session. Every failure returns the same generic 401 (no provider/user/credential enumeration).
+ */
+export const postAuthLoginRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  if (!isRecord(parsed.body)) return error("login body required", 400);
+  const providerId = parsed.body.provider;
+  if (typeof providerId !== "string" || !providerId) return error("provider required", 400);
+
+  const provider = getAuthProvider(providerId);
+  if (!provider) return error("invalid credentials", 401);
+
+  const result = await provider.verify(parsed.body);
+  if (!result) return error("invalid credentials", 401);
+
+  const identity = getAuthIdentity(provider.id, result.providerSubject);
+  if (!identity) return error("invalid credentials", 401);
+
+  const user = getUser(identity.userId);
+  if (!user || user.status !== "active") return error("invalid credentials", 401);
+
+  return sessionResponse(user);
+};
+
+/**
+ * POST /api/auth/refresh — body `{ refreshToken }`. Validates the refresh token and mints a fresh
+ * session, rotating the refresh token: the consumed one is revoked so a captured refresh token is
+ * single-use. Returns the same generic 401 on any invalid/expired/revoked token.
+ */
+export const postAuthRefreshRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  if (!isRecord(parsed.body)) return error("refresh body required", 400);
+  const refreshToken = parsed.body.refreshToken;
+  if (typeof refreshToken !== "string" || !refreshToken) return error("refreshToken required", 400);
+
+  const resolved = resolveRefreshToken(refreshToken);
+  if (!resolved) return error("invalid refresh token", 401);
+
+  const response = sessionResponse(resolved.user);
+  // Rotate: revoke the consumed refresh token so it can't be replayed (the fresh pair supersedes it).
+  if (resolved.payload.jti) revokeToken(resolved.payload.jti, "rotation");
+  return response;
+};
+
+/**
+ * POST /api/auth/logout — revokes the presented session token and, if supplied, its refresh token.
+ * Idempotent: revoking an already-revoked or absent token is a no-op. Always returns 204.
+ */
+export const postAuthLogoutRoute: Handler = async (req) => {
+  const component = getComponentAuth(req);
+  if (component?.jti) revokeToken(component.jti, "admin");
+
+  const parsed = await parseBody<unknown>(req);
+  if (parsed.ok && isRecord(parsed.body) && typeof parsed.body.refreshToken === "string") {
+    const resolved = resolveRefreshToken(parsed.body.refreshToken);
+    if (resolved?.payload.jti) revokeToken(resolved.payload.jti, "admin");
+  }
+  return new Response(null, { status: 204 });
+};

package/src/routes/index.ts

@@ -18,6 +18,7 @@ import { deleteSpawnPolicyRoute, getSpawnPoliciesHealth, getSpawnPoliciesRoute,
 import { deleteTokenProfileRoute, getTokenById, getTokenMe, getTokenProfiles, getTokens, patchTokenProfile, postIntegrationRuntimeToken, postInteractiveRunnerRuntimeToken, postMcpRuntimeToken, postOrchestratorRunnerToken, postRuntimeTokenRenew, postToken, postTokenProfile, postTokenRevoke } from "./tokens";
 import { deleteWorkspaceById, getWorkspaceById, getWorkspaceDiagnostics, getWorkspaceDiff, getWorkspaceGitState, getWorkspaceMergePreview, getWorkspaceOrphans, getWorkspaceRecoveryBranches, getWorkspaceStewards, getWorkspaces, postWorkspaceAction, postWorkspaceCleanupStale, postWorkspaceOrphanReclaim, postWorkspaceRecoveryBranchDiscard } from "./workspaces";
 import { error, type Handler } from "./_shared";
+import { getAuthProvidersRoute, postAuthLoginRoute, postAuthLogoutRoute, postAuthRefreshRoute } from "./auth";
 import { getActivityEvents, postActivityEvent } from "./activity";
 import { getAnalyticsRoute, getHealthRoute, getMaintenanceJobs, getStatsRoute, postMaintenanceJobRun, postSystemReap } from "./stats";
 import { getApiDocs, getApiSpec } from "./spec";
@@ -69,6 +70,13 @@ function route(method: string, path: string, handler: Handler): Route {
 }
 
 const routes: Route[] = [
+  // Auth & sessions (#389). On the pre-auth public allowlist (src/index.ts) — each handler owns
+  // its own auth (login verifies credentials, refresh validates the refresh token, logout revokes).
+  route("GET", "/api/auth/providers", getAuthProvidersRoute),
+  route("POST", "/api/auth/login", postAuthLoginRoute),
+  route("POST", "/api/auth/refresh", postAuthRefreshRoute),
+  route("POST", "/api/auth/logout", postAuthLogoutRoute),
+
   route("POST", "/api/artifacts", postArtifact),
   route("GET", "/api/artifacts", getArtifacts),
   route("GET", "/api/artifacts/:id/content", getArtifactContent),

package/src/routes/tokens.ts

@@ -1,7 +1,7 @@
 // Auto-split from routes.ts (#299). Domain: tokens.
-import { SPAWN_PROVIDERS, isRecord } from "agent-relay-sdk";
+import { SPAWN_PROVIDERS, isRecord, userSinkId } from "agent-relay-sdk";
 import { ValidationError, getOrchestrator, upsertIntegrationRegistry } from "../db";
-import { auditEvent, authAuditMetadata, authorizeRoute, error, isRootCredentialRequest, json, parseBody, type Handler } from "./_shared";
+import { auditEvent, authAuditMetadata, authorizeRoute, error, isRootCredentialRequest, json, parseBody, resolveActingUser, type Handler } from "./_shared";
 import { cleanString, cleanStringArray, cleanTokenConstraints, optionalEnum } from "../validation";
 import { createToken, deleteTokenProfile, getToken, getTokenProfile, listTokenProfiles, listTokens, renewToken, revokeToken, updateTokenProfile, upsertTokenProfile } from "../token-db";
 import { getComponentAuth, getIntegrationAuth, isAuthorized } from "../security";
@@ -36,6 +36,12 @@ export const getTokenMe: Handler = (req) => {
   }
 
   if (isAuthorized(req)) {
+    // Root (god-token) now carries the seeded-admin identity (#389): report *who* is acting
+    // (break-glass → user:default) instead of the anonymous "server" it showed before.
+    const acting = resolveActingUser(req);
+    if (acting) {
+      return json({ actor: userSinkId(acting.userId), userId: acting.userId, source: acting.source, kind: "server", scopes: ["*"] });
+    }
     return json({ actor: "server", kind: "server", scopes: ["*"] });
   }
   return error("unauthorized", 401);

package/src/security.ts

@@ -539,7 +539,7 @@ function isTokenConstraints(value: unknown): value is TokenConstraints {
   for (const [key, item] of Object.entries(record)) {
     if (["terminalAttach", "logsRead", "canDelegate"].includes(key)) {
       if (typeof item !== "boolean") return false;
-    } else if (key === "cwd" || key === "spawnedBy" || key === "teamId" || key === "projectId") {
+    } else if (key === "cwd" || key === "spawnedBy" || key === "teamId" || key === "projectId" || key === "tenantId") {
       if (typeof item !== "string") return false;
     } else if (key === "maxSpawnedAgents") {
       if (typeof item !== "number") return false;