@humwick/server 0.0.0-stage → 0.130.1

package/src/auth/password.ts

@@ -0,0 +1,142 @@
+// 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, scrypt, timingSafeEqual } from "node:crypto";
+import { createAuthIdentity, getAuthIdentity, type AuthIdentity } from "../db/auth-identities.ts";
+import { isRecord } from "@humwick/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 | Promise<boolean>;
+type PasswordIdentityLookup = (provider: string, providerSubject: string) => AuthIdentity | undefined;
+
+interface PasswordVerifyAttempt {
+  valid: boolean;
+  attemptedKdf: boolean;
+}
+
+// #1817 — scrypt is a deliberately expensive KDF (~29ms/call). The sync form (`scryptSync`) ran the
+// whole derivation on the event-loop thread, so POST /api/auth/login (unauthenticated, per the
+// pre-auth allowlist) could saturate the fleet's event loop by dialing up the request rate. Node's
+// async `scrypt` runs the work on libuv's threadpool and yields the event loop, so a flood of login
+// attempts no longer blocks unrelated requests. The login-route rate limiter (login-rate-limiter.ts)
+// then bounds the aggregate work a single client can queue.
+function scryptAsync(
+  password: string,
+  salt: Buffer,
+  keylen: number,
+  opts: { N: number; r: number; p: number },
+): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    scrypt(password, salt, keylen, opts, (err, derivedKey) => {
+      if (err) reject(err);
+      else resolve(derivedKey as Buffer);
+    });
+  });
+}
+
+/** Hash a plaintext password into a self-describing `scrypt$N$r$p$saltHex$hashHex` string. */
+export async function hashPassword(password: string): Promise<string> {
+  const salt = randomBytes(SALT_BYTES);
+  const derived = await scryptAsync(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")}`;
+}
+
+async function verifyPasswordAttempt(password: string, stored: string | null): Promise<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 = await scryptAsync(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 async function verifyPassword(password: string, stored: string | null): Promise<boolean> {
+  return (await verifyPasswordAttempt(password, stored)).valid;
+}
+
+async function verifyPasswordWithDummyFallback(password: string, stored: string | null): Promise<boolean> {
+  const result = await verifyPasswordAttempt(password, stored);
+  if (result.attemptedKdf) return result.valid;
+  await 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 async function createPasswordIdentity(input: {
+  userId: string;
+  username: string;
+  password: string;
+  metadata?: Record<string, unknown>;
+}): Promise<AuthIdentity> {
+  return createAuthIdentity({
+    userId: input.userId,
+    provider: PASSWORD_PROVIDER_ID,
+    providerSubject: input.username,
+    secretHash: await 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 async function verifyPasswordCredentials(
+  credentials: unknown,
+  opts: { lookupIdentity?: PasswordIdentityLookup; verifyStoredPassword?: PasswordVerifier } = {},
+): Promise<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 = await 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): Promise<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/role-scopes.ts

@@ -0,0 +1,15 @@
+import type { UserRole } from "@humwick/sdk";
+
+// #3567 — sessions and agent authorization share role scopes without importing each other.
+// #3567 — every signed-in human reads and writes their own per-user (tier "user") preferences.
+const OWN_PREFERENCE_SCOPES = ["agent-prefs", "notification-prefs", "display", "chat", "voice"].flatMap((ns) => [`settings:read:${ns}`, `settings:write:${ns}`]);
+const ROLE_SCOPES: Record<UserRole, readonly string[]> = {
+  admin: ["system:admin"],
+  operator: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "command:spawn", "task:read", "task:write", "teams:read", "stats:read", ...OWN_PREFERENCE_SCOPES],
+  viewer: ["agent:read", "message:read", "command:read", "task:read", "teams:read", "stats:read", ...OWN_PREFERENCE_SCOPES],
+};
+
+/** The scope set a role carries. Unknown role → empty set (fail-closed). */
+export function scopesForRole(role: UserRole | string | undefined): readonly string[] {
+  return ROLE_SCOPES[role as UserRole] ?? [];
+}

package/src/auth/session-cookie.ts

@@ -0,0 +1,35 @@
+// Browser refresh credentials have one transport and one CSRF boundary (#3567 H3).
+import { REFRESH_TTL_SECONDS } from "./session";
+
+export const SESSION_COOKIE = "relay_refresh";
+
+function browserOrigin(req: Request): string {
+  const url = new URL(req.url);
+  const host = req.headers.get("x-forwarded-host") ?? url.host;
+  const protocol = req.headers.get("x-forwarded-proto") ?? url.protocol.slice(0, -1);
+  return `${protocol}://${host}`;
+}
+
+// Unlike API CORS, cookie authentication never accepts wildcard/extra origins or a missing Origin.
+export function sessionOriginAllowed(req: Request, required = true): boolean {
+  const origin = req.headers.get("origin");
+  return origin ? origin === browserOrigin(req) : !required;
+}
+
+export function readSessionCookie(req: Request): string | undefined {
+  return req.headers.get("cookie")?.split(";").map((part) => part.trim())
+    .find((part) => part.startsWith(`${SESSION_COOKIE}=`))?.slice(SESSION_COOKIE.length + 1) || undefined;
+}
+
+export function withSessionCookie(req: Request, response: Response, token = ""): Response {
+  // The dashboard knows the public base even when a proxy strips it before forwarding (#3567).
+  const prefix = req.headers.get("x-forwarded-prefix") || "/";
+  if (URL.parse(prefix, req.url)?.pathname !== prefix || prefix.includes(";")) {
+    return Response.json({ error: "invalid forwarded prefix" }, { status: 400 });
+  }
+  const cookiePath = `${prefix.replace(/\/$/, "")}/api/auth/refresh`;
+  const secure = new URL(browserOrigin(req)).protocol === "https:" ? "; Secure" : "";
+  response.headers.set("Set-Cookie", `${SESSION_COOKIE}=${token}; Path=${cookiePath}; HttpOnly; SameSite=Strict; Max-Age=${token ? REFRESH_TTL_SECONDS : 0}${secure}`);
+  response.headers.set("Cache-Control", "no-store");
+  return response;
+}

package/src/auth/session-refresh.ts

@@ -0,0 +1,61 @@
+// Concurrent tabs on plain HTTP cannot use Web Locks. Share one rotation and briefly replay
+// its access credential without ever overwriting a newer refresh cookie (#3567).
+import { createHash } from "node:crypto";
+import { getToken, signTokenRecord } from "../token-db";
+import { revokeTokenAsync } from "../token-db-write";
+import { getUser } from "../db/users";
+import { verifyComponentToken } from "../security";
+import { mintUserSession, resolveRefreshToken, sessionUserIdOf, type MintedSession } from "./session";
+
+export const REFRESH_GRACE_MS = 20_000;
+// Only hashes and record ids are retained; signed credentials are reconstructed from live records.
+const rotations = new Map<string, {
+  expiresAt: number;
+  result: Promise<Pick<MintedSession, "accessJti" | "refreshJti"> | null>;
+}>();
+
+export async function refreshUserSession(refreshToken: string, nowMs = Date.now()) {
+  // Insertion order bounds retained metadata to the most recent grace window, without timers.
+  for (const [key, rotation] of rotations) {
+    if (rotation.expiresAt > nowMs) break;
+    rotations.delete(key);
+  }
+  const key = createHash("sha256").update(refreshToken).digest("hex");
+  let rotation = rotations.get(key);
+  const replayed = rotation !== undefined && rotation.expiresAt > nowMs;
+  if (!replayed) {
+    const resolved = resolveRefreshToken(refreshToken);
+    if (!resolved?.payload.jti) return null;
+    const jti = resolved.payload.jti;
+    rotation = {
+      expiresAt: Math.min(nowMs + REFRESH_GRACE_MS, (resolved.payload.exp ?? Infinity) * 1000),
+      result: (async () => {
+        if (!(await revokeTokenAsync(jti, "rotation"))) return null;
+        const session = mintUserSession(resolved.user, resolved.payload.constraints?.sessionId);
+        return { accessJti: session.accessJti, refreshJti: session.refreshJti };
+      })(),
+    };
+    rotations.set(key, rotation);
+  }
+  let result;
+  try { result = await rotation!.result; }
+  catch (error) { rotations.delete(key); throw error; }
+  if (!result) return null;
+  const access = getToken(result.accessJti);
+  const refresh = getToken(result.refreshJti);
+  if (!access || !refresh) return null;
+  const accessToken = signTokenRecord(access);
+  // Logout, admin revoke and suspension must also invalidate every grace replay.
+  if (!verifyComponentToken(accessToken, Math.floor(nowMs / 1000))) return null;
+  const userId = sessionUserIdOf(access);
+  const user = userId ? getUser(userId) : null;
+  if (!user || user.status !== "active") return null;
+  return {
+    user,
+    session: {
+      accessToken,
+      expiresIn: access.expiresAt! - Math.floor(nowMs / 1000),
+      refreshToken: replayed ? undefined : signTokenRecord(refresh),
+    },
+  };
+}

package/src/auth/session.test-fixture.ts

@@ -0,0 +1,10 @@
+// Test helper (#3567): act as a user the way production does, with a real signed-in session token.
+import { getUser } from "../db/users.ts";
+import { mintUserSession } from "./session.ts";
+
+/** An `authorization` header carrying a fresh access token for `userId`. An unknown id models a
+ *  session whose user no longer exists (it carries operator scopes). */
+export function sessionAuthHeader(userId: string): Record<string, string> {
+  const user = getUser(userId) ?? { id: userId, handle: userId, displayName: userId, role: "operator" as const, status: "active" as const, tenantId: "default", avatarArtifactId: null, avatarUrl: null, createdAt: 0, updatedAt: 0 };
+  return { authorization: `Bearer ${mintUserSession(user).accessToken}` };
+}

package/src/auth/session.ts

@@ -0,0 +1,107 @@
+// 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 "@humwick/sdk";
+import { randomUUID } from "node:crypto";
+import { revokeTokenAsync } from "../token-db-write.ts";
+import { createToken, liveTokenJtisForSession } from "../token-db.ts";
+import { verifyComponentToken } from "../security.ts";
+import { getUser } from "../db/users.ts";
+import { scopesForRole } from "./role-scopes";
+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";
+
+import { USER_TOKEN_ROLE } from "./admin-routes.ts";
+export { USER_TOKEN_ROLE };
+
+/** The `users.id` a human session token acts as (#3567 D4), or undefined for any other token. */
+export function sessionUserIdOf(component: Pick<ComponentToken, "role" | "sub"> | null | undefined): string | undefined {
+  if (!component || component.role !== USER_TOKEN_ROLE || !isHumanAgentId(component.sub)) return undefined;
+  return userIdFromAddress(component.sub);
+}
+
+/**
+ * The scopes a user's session carries: the role's scope set from `agent-authz.ts` (one source for
+ * what each role may do, #3567), with admins on the `admin:*` alias (→ `system:admin`).
+ */
+export function scopesForUserRole(role: UserRole): string[] {
+  return role === "admin" ? ["admin:*"] : [...scopesForRole(role)];
+}
+
+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, sessionId: string = randomUUID()): MintedSession {
+  const sub = userSinkId(user.id);
+  const constraints = { sessionId, ...(user.tenantId ? { tenantId: user.tenantId } : {}) };
+  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 };
+}
+
+/** Revoke one browser session without signing out the user's other browsers. */
+export async function revokeUserSession(component: Pick<ComponentToken, "jti" | "sub" | "role" | "constraints">): Promise<boolean> {
+  if (!sessionUserIdOf(component) || !component.jti) return false;
+  const sessionId = component.constraints?.sessionId;
+  const jtis = sessionId ? liveTokenJtisForSession(component.sub, sessionId) : [component.jti];
+  let revoked = false;
+  for (const jti of jtis) revoked = await revokeTokenAsync(jti, "admin") || revoked;
+  return revoked;
+}

package/src/authority-audit.ts

@@ -0,0 +1,56 @@
+import { hasPresentedCredential, DEFAULT_USER_ID, userSinkId } from "@humwick/sdk";
+// #3567 H6 — private denial records share the activity store, without broadcasting to SSE.
+import { isAuthorized, getIntegrationAuth } from "./security";
+import { createActivityEventAsync } from "./db/activity-async";
+import { trackRelayEvent } from "./relay-event-drain";
+import { authContextFromRequest, type AuthContext } from "./services/auth-context";
+
+export const AUTHORITY_DENIED = "Authority denied";
+/** #3605 — the private record of an admin's user-management action (and of an invite accepted). */
+export const USER_MANAGEMENT = "User management";
+
+function auditActor(ctx: AuthContext): AuthContext["actor"] {
+  return ctx.callerAgentId ? { kind: "agent", id: ctx.callerAgentId } : ctx.actor;
+}
+
+export function recordAuthorityDenial(ctx: AuthContext, target: string, action: string, reason: string): void {
+  trackRelayEvent(createActivityEventAsync({
+    kind: "state", title: AUTHORITY_DENIED,
+    metadata: { actor: auditActor(ctx), target, action, reason },
+  }), "authority.denied");
+}
+
+/** The request's audit identity: the admin token reads as the default user, no credential as anonymous. */
+function requestAuditContext(req: Request): AuthContext {
+  const ctx = authContextFromRequest(req);
+  if (ctx.actor.kind === "system") {
+    const url = new URL(req.url);
+    const presented = hasPresentedCredential(req);
+    ctx.actor = presented && isAuthorized(req)
+      ? { kind: "user", id: userSinkId(DEFAULT_USER_ID) }
+      : { kind: "user", id: "anonymous" };
+  }
+  const integration = getIntegrationAuth(req);
+  if (integration) ctx.actor = { kind: "integration", id: integration.name };
+  return ctx;
+}
+
+/**
+ * One row per action: who did it, to whom, and what changed (never a credential). `actingUserId`
+ * names the actor of a request that carries no session yet (an accepted invite).
+ */
+export function recordUserManagement(req: Request, target: string, action: string, detail: Record<string, unknown> = {}, actingUserId?: string): void {
+  const actor = actingUserId ? { kind: "user", id: userSinkId(actingUserId) } : auditActor(requestAuditContext(req));
+  trackRelayEvent(createActivityEventAsync({
+    kind: "state", title: USER_MANAGEMENT,
+    metadata: { actor, target, action, ...detail },
+  }), "user.management");
+}
+
+export function authorityDenied(req: Request, reason: string, status = 403, target?: string, action?: string): Response {
+  const url = new URL(req.url);
+  recordAuthorityDenial(requestAuditContext(req), target ?? url.pathname, action ?? `${req.method} ${url.pathname}`, reason);
+  const response = Response.json({ error: reason }, { status });
+  if (status === 401) response.headers.set("WWW-Authenticate", "Bearer");
+  return response;
+}

package/src/authz-meta-keys.ts

@@ -0,0 +1,64 @@
+// #1797 — the `agent.meta` keys that are ADDRESSING for authorization, not description.
+//
+// `policyName` and `spawnRequestId` are read as server-side identity by:
+//   - `markManagedAgentRunning` — which agent the policy's managed binding points at, and so
+//     `managedStewardBoundAgentId` → `isProvenStewardAgent` (#1623 steward provenance);
+//   - `agentBoundTaskIds` (task-authz.ts) — which Tasks an agent may read sensitive data for;
+//   - `bindSpawnedTaskToReadyAgent` — which Task a newly-ready agent claims ownership of;
+//   - `resolveCallerAgentId` (agent-ref.ts) — the live-agent scan that resolves a policy/spawn-scoped
+//     token back to an agent id;
+//   - shutdown-by-spawnRequestId (shutdown-agent.ts) — which agent a parent may reap.
+//
+// So they must never be free-text caller input. They have TWO external ingresses and BOTH must
+// enforce that — round 2 fixed only the first, and round 3 (N1) found the second still open:
+//   1. REGISTRATION (`registerAgent` → `sanitizeAuthzMeta`) — HTTP `POST /api/agents` body.meta and
+//      the bus `register` frame's payload.meta. Values not covered by the caller's SIGNED
+//      constraints are dropped.
+//   2. the bus `status` FRAME (`bus.ts` → `mergeAgentMeta`) — a shallow merge of an arbitrary
+//      caller-supplied blob onto the caller's OWN row. It bypassed (1) entirely, so any agent
+//      holding a bus socket could stamp `spawnRequestId: <a victim's>` on itself and inherit that
+//      Task's sensitive-read authority. `mergeAgentMeta` now refuses these keys outright.
+//
+// (2) is a flat refusal rather than a signed-constraints check because NO relay-internal caller of
+// `mergeAgentMeta` writes either key — they are established once, at registration, from the signed
+// grant. Anything that needs to move them goes through `upsertAgent`.
+//
+// #2033 review BLOCKER 3 — `workspace` (specifically `workspace.worktreePath`) joined this list for
+// the identical reason: `restartSpawnParamsForAgent` (restart-spawn.ts) reads
+// `agent.meta.workspace.worktreePath` as the agent's OWN prior isolated worktree and widens its
+// successor token's `cwdPrefixes` to it. Like `policyName`/`spawnRequestId`, no relay-internal
+// caller of `mergeAgentMeta` ever needs to LIVE-UPDATE it — it is established once, at registration,
+// from what the orchestrator actually resolved and told the runner at launch — so refusing it
+// outright on the bus `status` frame (the flat `withoutAuthzMetaKeys` path, which is type-agnostic
+// and so applies cleanly to this object-valued key, unlike `sanitizeAuthzMeta`'s string-comparison
+// path below) costs nothing legitimate. This closes the write side; `isolatedPolicyWorktreeCwdPrefixes`
+// (isolated-workspace-placement.ts) closes the read/USE side by validating the value is inside
+// baseDir before ever trusting it, regardless of how — or whether — it was forged.
+// #2392 review MEDIUM-2 — `approvalMode` joined this list. #2245 made the SIGNED
+// `TokenConstraints.approvalMode` an AUTHORIZATION operand (an `approvalMode:open` agent may run
+// scheduler background commands), and `agent.meta.approvalMode` is what MINTS that constraint on the
+// next generation: `restartSpawnParamsForAgent` (restart-spawn.ts, both twins) reads it and stamps it
+// into the successor runner token, and `spawn-agent.ts` reads the CALLER's copy to default a child's
+// posture. Left caller-writable, a `guarded` agent could stamp `meta.approvalMode: "open"` on itself
+// via a bus `status` frame, self-restart (reachable with `agent:write`), and its successor would hold
+// a genuinely SIGNED `approvalMode: open` — laundering forged description into real authority.
+//
+// Unlike `workspace`, this key HAS a signed comparison value, so `sanitizeAuthzMeta` can prove it
+// rather than always-strip: the registration claim must equal the caller's own signed
+// `constraints.approvalMode`. A genuine runner always agrees — the orchestrator launches the provider
+// with exactly the mode the same spawn stamped into the token (spawn-agent.ts / restart-spawn.ts /
+// managed-policy.ts / recipe-runner.ts all pass it to `issueRunnerRuntimeToken`, and interactive mints
+// carry the runner's detected mode). A claim the token cannot back is dropped, and every reader falls
+// back to `guarded` — fail-closed, in the direction that cannot escalate.
+export const AUTHZ_META_KEYS = ["policyName", "spawnRequestId", "workspace", "approvalMode"] as const;
+
+export type AuthzMetaKey = (typeof AUTHZ_META_KEYS)[number];
+
+/** Drop both authz-addressing keys from a caller-supplied meta blob. Returns the same reference
+ * when neither key is present, so the common path allocates nothing. */
+export function withoutAuthzMetaKeys(meta: Record<string, unknown>): Record<string, unknown> {
+  if (!AUTHZ_META_KEYS.some((key) => key in meta)) return meta;
+  const filtered = { ...meta };
+  for (const key of AUTHZ_META_KEYS) delete filtered[key];
+  return filtered;
+}