@opengeni/api-router 0.2.0

package/src/routes/social.ts

@@ -0,0 +1,119 @@
+import {
+  CreateSocialConnectionRequest,
+  CreateSocialPostRequest,
+} from "@opengeni/contracts";
+import {
+  createSocialConnection,
+  createSocialPost,
+  listSocialConnections,
+  listSocialPosts,
+} from "@opengeni/db";
+import type { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+import { requireAccessGrant } from "@opengeni/core";
+import type { ApiRouteDeps } from "@opengeni/core";
+import { boundedLimit } from "../http/common";
+
+export function registerSocialRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const { db } = deps;
+
+  app.get("/v1/workspaces/:workspaceId/social/connections", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    return c.json(await listSocialConnections(db, workspaceId, boundedLimit(c.req.query("limit"))));
+  });
+
+  app.post("/v1/workspaces/:workspaceId/social/connections", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const payload = CreateSocialConnectionRequest.parse(await c.req.json());
+    try {
+      return c.json(await createSocialConnection(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        provider: payload.provider,
+        accountHandle: payload.accountHandle,
+        accountName: payload.accountName ?? null,
+        externalAccountId: payload.externalAccountId ?? null,
+        status: payload.status,
+        scopes: payload.scopes,
+        credentialRef: payload.credentialRef ?? null,
+        tokenMetadata: payload.tokenMetadata,
+        metadata: payload.metadata,
+      }), 201);
+    } catch (error) {
+      throw socialHttpException(error);
+    }
+  });
+
+  app.get("/v1/workspaces/:workspaceId/social/posts", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const since = parseSince(c.req.query("since"));
+    const connectionIds = parseConnectionIds(c.req.query("connectionIds") ?? c.req.query("connectionId"));
+    return c.json(await listSocialPosts(db, {
+      workspaceId,
+      ...(connectionIds?.length ? { connectionIds } : {}),
+      ...(since ? { since } : {}),
+      limit: boundedLimit(c.req.query("limit")),
+    }));
+  });
+
+  app.post("/v1/workspaces/:workspaceId/social/posts", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const payload = CreateSocialPostRequest.parse(await c.req.json());
+    try {
+      return c.json(await createSocialPost(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        connectionId: payload.connectionId,
+        externalPostId: payload.externalPostId ?? null,
+        url: payload.url ?? null,
+        authorHandle: payload.authorHandle ?? null,
+        text: payload.text,
+        publishedAt: new Date(payload.publishedAt),
+        metrics: payload.metrics,
+        raw: payload.raw,
+      }), 201);
+    } catch (error) {
+      throw socialHttpException(error);
+    }
+  });
+}
+
+function parseSince(raw: string | undefined): Date | undefined {
+  if (!raw) {
+    return undefined;
+  }
+  const since = new Date(raw);
+  if (Number.isNaN(since.getTime())) {
+    throw new HTTPException(422, { message: "since must be an ISO date-time" });
+  }
+  return since;
+}
+
+function parseConnectionIds(raw: string | undefined): string[] | undefined {
+  if (!raw) {
+    return undefined;
+  }
+  const values = raw.split(",").map((value) => value.trim()).filter(Boolean);
+  const parsed = z.array(z.string().uuid()).safeParse(values);
+  if (!parsed.success) {
+    throw new HTTPException(422, { message: "connectionIds must be a comma-separated list of UUIDs" });
+  }
+  const ids = parsed.data;
+  return [...new Set(ids)];
+}
+
+function socialHttpException(error: unknown): HTTPException {
+  const message = error instanceof Error ? error.message : String(error);
+  if (message.includes("not found")) {
+    return new HTTPException(404, { message });
+  }
+  if (message.includes("duplicate key")) {
+    return new HTTPException(409, { message: "social connection or post already exists" });
+  }
+  return new HTTPException(500, { message });
+}

package/src/routes/workspaces.ts

@@ -0,0 +1,206 @@
+import {
+  AddWorkspaceMemberRequest,
+  CreateWorkspaceRequest,
+  ListWorkspaceMembersResponse,
+  UpdateWorkspaceMemberRequest,
+  UpdateWorkspaceRequest,
+  Workspace,
+  WorkspaceMember,
+  type AccessContext,
+  type Permission,
+} from "@opengeni/contracts";
+import {
+  allWorkspacePermissions,
+  countActiveSessionsForWorkspace,
+  countWorkspacesForAccount,
+  createWorkspace,
+  deleteWorkspace,
+  getManagedUserByEmail,
+  grantWorkspaceAccess,
+  listScheduledTasks,
+  listWorkspaceMembers,
+  listWorkspacesForSubject,
+  removeWorkspaceMember,
+  requireWorkspace,
+  updateWorkspace,
+} from "@opengeni/db";
+import type { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { hasPermission, requireAccessContext, requireAccessGrant } from "@opengeni/core";
+import { requireLimit } from "@opengeni/core";
+import type { ApiRouteDeps } from "@opengeni/core";
+import { assertWorkspaceDeletable, assertWorkspaceMemberRemovable, resolveMemberSubjectId } from "@opengeni/core";
+
+export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
+  app.get("/v1/access/me", async (c) => {
+    return c.json(await requireAccessContext(c, deps));
+  });
+
+  app.get("/v1/workspaces", async (c) => {
+    const context = await requireAccessContext(c, deps);
+    const readableWorkspaceIds = [...new Set(context.workspaceGrants
+      .filter((grant) => hasPermission(grant.permissions, "workspace:read"))
+      .map((grant) => grant.workspaceId))];
+    if (readableWorkspaceIds.length > 0) {
+      const workspaces = await Promise.all(readableWorkspaceIds.map((workspaceId) => requireWorkspace(deps.db, workspaceId)));
+      return c.json(workspaces.map((workspace) => Workspace.parse(workspace)));
+    }
+    return c.json((await listWorkspacesForSubject(deps.db, context.subjectId)).map((workspace) => Workspace.parse(workspace)));
+  });
+
+  app.post("/v1/workspaces", async (c) => {
+    const context = await requireAccessContext(c, deps);
+    const payload = CreateWorkspaceRequest.parse(await c.req.json());
+    const accountId = payload.accountId ?? context.defaultAccountId;
+    if (!accountId) {
+      throw new HTTPException(409, { message: "account selection is required" });
+    }
+    requireAccountPermission(context, accountId, "workspace:create");
+    await requireLimit(deps, { accountId, action: "workspace:create", quantity: 1 });
+    const workspace = await createWorkspace(deps.db, {
+      accountId,
+      name: payload.name.trim(),
+      slug: payload.slug?.trim() || null,
+      externalSource: payload.externalSource ?? null,
+      externalId: payload.externalId ?? null,
+      ...(payload.agentInstructions !== undefined ? { agentInstructions: normalizeAgentInstructions(payload.agentInstructions) } : {}),
+    });
+    await grantWorkspaceAccess(deps.db, {
+      accountId,
+      workspaceId: workspace.id,
+      subjectId: context.subjectId,
+      role: "owner",
+      permissions: allWorkspacePermissions,
+      ...(context.subjectLabel ? { subjectLabel: context.subjectLabel } : {}),
+    });
+    return c.json(Workspace.parse(workspace), 201);
+  });
+
+  app.get("/v1/workspaces/:workspaceId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    return c.json(Workspace.parse(await requireWorkspace(deps.db, workspaceId)));
+  });
+
+  app.patch("/v1/workspaces/:workspaceId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const payload = UpdateWorkspaceRequest.parse(await c.req.json());
+    const workspace = await updateWorkspace(deps.db, workspaceId, {
+      ...(payload.name !== undefined ? { name: payload.name.trim() } : {}),
+      ...(payload.slug !== undefined ? { slug: payload.slug?.trim() || null } : {}),
+      ...(payload.agentInstructions !== undefined ? { agentInstructions: normalizeAgentInstructions(payload.agentInstructions) } : {}),
+    });
+    return c.json(Workspace.parse(workspace));
+  });
+
+  app.delete("/v1/workspaces/:workspaceId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    // Refuse before any external/DB mutation: never delete the account's only
+    // workspace, and never delete while a session could still be running in
+    // Temporal (there is no clean per-session terminate to call, so deleting
+    // the row would orphan the workflow — the operator must stop them first).
+    const [workspaceCountForAccount, activeSessionCount] = await Promise.all([
+      countWorkspacesForAccount(deps.db, grant.accountId),
+      countActiveSessionsForWorkspace(deps.db, workspaceId),
+    ]);
+    assertWorkspaceDeletable({ workspaceCountForAccount, activeSessionCount });
+    // Clean external Temporal state the FK cascade can't reach: every scheduled
+    // task's schedule (best-effort, mirroring the scheduled-task delete path).
+    const tasks = await listScheduledTasks(deps.db, workspaceId, 1000);
+    await Promise.all(tasks.map((task) =>
+      deps.workflowClient.deleteScheduledTaskSchedule({ temporalScheduleId: task.temporalScheduleId }).catch(() => undefined),
+    ));
+    await deleteWorkspace(deps.db, workspaceId);
+    return c.body(null, 204);
+  });
+
+  // --- Members ("People with access") ---------------------------------------
+
+  app.get("/v1/workspaces/:workspaceId/members", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const members = await listWorkspaceMembers(deps.db, workspaceId);
+    return c.json(ListWorkspaceMembersResponse.parse({ members }));
+  });
+
+  app.post("/v1/workspaces/:workspaceId/members", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "members:manage");
+    const payload = AddWorkspaceMemberRequest.parse(await c.req.json());
+    const email = payload.email.trim();
+    // Email invites for not-yet-registered users are deferred: an unknown email
+    // resolves to null, which resolveMemberSubjectId turns into a 404.
+    const subjectId = resolveMemberSubjectId(await getManagedUserByEmail(deps.db, email));
+    await grantWorkspaceAccess(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId,
+      subjectLabel: email,
+      ...(payload.role !== undefined ? { role: payload.role } : {}),
+      permissions: payload.permissions,
+    });
+    const members = await listWorkspaceMembers(deps.db, workspaceId);
+    const member = members.find((candidate) => candidate.subjectId === subjectId);
+    if (!member) {
+      throw new HTTPException(500, { message: "failed to add member" });
+    }
+    return c.json(WorkspaceMember.parse(member), 201);
+  });
+
+  app.patch("/v1/workspaces/:workspaceId/members/:subjectId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "members:manage");
+    const subjectId = decodeURIComponent(c.req.param("subjectId"));
+    const payload = UpdateWorkspaceMemberRequest.parse(await c.req.json());
+    const existing = await listWorkspaceMembers(deps.db, workspaceId);
+    const current = existing.find((member) => member.subjectId === subjectId);
+    if (!current) {
+      throw new HTTPException(404, { message: "member not found" });
+    }
+    await grantWorkspaceAccess(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId,
+      ...(current.subjectLabel ? { subjectLabel: current.subjectLabel } : {}),
+      role: payload.role ?? current.role,
+      permissions: payload.permissions,
+    });
+    const members = await listWorkspaceMembers(deps.db, workspaceId);
+    const member = members.find((candidate) => candidate.subjectId === subjectId);
+    if (!member) {
+      throw new HTTPException(500, { message: "failed to update member" });
+    }
+    return c.json(WorkspaceMember.parse(member));
+  });
+
+  app.delete("/v1/workspaces/:workspaceId/members/:subjectId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "members:manage");
+    const subjectId = decodeURIComponent(c.req.param("subjectId"));
+    const members = await listWorkspaceMembers(deps.db, workspaceId);
+    // Never remove yourself, and never remove the last administering member.
+    assertWorkspaceMemberRemovable({ members, subjectId, callerSubjectId: grant.subjectId });
+    await removeWorkspaceMember(deps.db, workspaceId, subjectId);
+    return c.body(null, 204);
+  });
+}
+
+// A persona override that is null or trims to empty collapses to null (use the
+// deployment default). Otherwise the template is stored verbatim so the runtime
+// can substitute the non-bypassable CORE at its {{core}} marker.
+function normalizeAgentInstructions(value: string | null): string | null {
+  if (value === null) {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function requireAccountPermission(context: AccessContext, accountId: string, permission: Permission): void {
+  const grant = context.accountGrants.find((candidate) => candidate.accountId === accountId);
+  if (!grant || (!grant.permissions.includes(permission) && !grant.permissions.includes("account:admin"))) {
+    throw new HTTPException(403, { message: `missing permission: ${permission}` });
+  }
+}

package/src/sandbox/access.ts

@@ -0,0 +1,89 @@
+// apps/api/src/sandbox/access.ts — the API-tier sandbox access seam.
+//
+// This is the foundation of the API-DIRECT control plane
+// (docs/design/sandbox-surfacing): the apps/api process constructs its OWN
+// sandbox client and resumes boxes by id IN-PROCESS, so non-turn ops (viewer
+// attach, FS/git reads, tunnel URL mint) never touch Temporal or a worker.
+//
+// IMPORT DISCIPLINE (enforced by apps/api/test/sandbox-access-import-guard.test.ts):
+//   apps/api accesses sandbox construction/resume symbols ONLY via the
+//   agent-loop-free leaf `@opengeni/runtime/sandbox` — NEVER the bare
+//   `@opengeni/runtime` barrel (which pulls the @openai/agents agent loop into
+//   the API process). This file is the single chokepoint for that import.
+import { createSandboxClient } from "@opengeni/runtime/sandbox";
+import type { Settings } from "@opengeni/config";
+
+// The structural shapes the API needs from a provider sandbox client now live in
+// @opengeni/core (`sandbox-types.ts`) — `dependencies.ts` (also in core)
+// references them as the `sandboxClient` / `resumeBoxById` provider seams, so
+// core is their single owner. We re-export them from here so existing apps/api
+// importers (and the `@opengeni/runtime/sandbox` value implementation below)
+// keep the same import site. (Mirrors @openai/agents/sandbox's SandboxClient
+// without importing the agent-loop barrel.)
+export type {
+  ApiSandboxSession,
+  ApiSandboxClient,
+  ResumeBoxByIdInput,
+  ResumedSandboxSession,
+} from "@opengeni/core";
+import type {
+  ApiSandboxClient,
+  ApiSandboxSession,
+  ResumeBoxByIdInput,
+  ResumedSandboxSession,
+} from "@opengeni/core";
+
+export class SandboxResumeError extends Error {
+  constructor(message: string, readonly cause?: unknown) {
+    super(message);
+    this.name = "SandboxResumeError";
+  }
+}
+
+/**
+ * Construct the API process's own sandbox client from settings, agent-loop-free.
+ * Returns undefined when `sandboxBackend=none` (no box to touch). The Modal
+ * token + app name are read from settings (already parsed by getSettings and
+ * present in the API runtime env), so the client can resume Modal boxes by id.
+ */
+export function createApiSandboxClient(settings: Settings): ApiSandboxClient | undefined {
+  const client = createSandboxClient(settings) as ApiSandboxClient | undefined;
+  return client;
+}
+
+/**
+ * Build the `resumeBoxById` helper bound to the API's sandbox client. Given a
+ * backend + a serialized resume_state envelope, it resumes the box and returns
+ * a live session for one in-process op. The caller drives exec/readFile and then
+ * drops the handle (resume → use → drop); it does NOT own the box.
+ */
+export function makeResumeBoxById(client: ApiSandboxClient | undefined): (input: ResumeBoxByIdInput) => Promise<ResumedSandboxSession> {
+  return async ({ backend, resumeState }: ResumeBoxByIdInput): Promise<ResumedSandboxSession> => {
+    if (!client) {
+      throw new SandboxResumeError(
+        "The API sandbox client is not configured (sandboxBackend=none); cannot resume a box by id.",
+      );
+    }
+    if (client.backendId !== backend) {
+      throw new SandboxResumeError(
+        `Resume backend "${backend}" does not match the API sandbox client backend "${client.backendId}"; a cross-backend resume_state envelope cannot be deserialized.`,
+      );
+    }
+    if (!client.deserializeSessionState || !client.resume) {
+      throw new SandboxResumeError(
+        `The configured sandbox backend "${client.backendId}" does not support resume-by-id (no deserializeSessionState/resume).`,
+      );
+    }
+    let session: ApiSandboxSession;
+    try {
+      const state = await client.deserializeSessionState(resumeState);
+      session = await client.resume(state);
+    } catch (error) {
+      throw new SandboxResumeError(
+        `Failed to resume sandbox box by id on backend "${backend}": ${error instanceof Error ? error.message : String(error)}`,
+        error,
+      );
+    }
+    return session;
+  };
+}

package/src/sandbox/auth-callout.ts

@@ -0,0 +1,178 @@
+// apps/api/src/sandbox/auth-callout.ts — the NATS AUTH-CALLOUT responder (the
+// bring-your-own-compute M-AUTH tenancy boundary; dossier §10.1 NATS Accounts per
+// workspace + §17 the isolation smoke + §19 the NATS-Accounts-misconfig leak risk).
+//
+// THE BOUNDARY THIS CLOSES: an external agent connects to NATS presenting its
+// `oge_` enrollment bearer as the connect auth-token. nats-server (configured with
+// `auth_callout`) issues an authorization request on $SYS.REQ.USER.AUTH. THIS
+// responder:
+//   1. decodes the authorization request (the `user_nkey` the response must scope
+//      to, the `server_id` for the response `aud`, and the presented `auth_token`);
+//   2. VALIDATES the bearer with verifyEnrollmentBearer (HMAC, via
+//      resolveEnrollmentSigningSecret) — an invalid/expired/forged bearer is denied;
+//   3. confirms the enrollment is still ACTIVE in the DB (a revoked machine is
+//      denied even with a still-unexpired bearer);
+//   4. signs a NATS user JWT granting pub/sub ONLY `agent.<ws>.>` + `_INBOX.>`
+//      (deny-all-else by an allow-list) and returns it inside a signed
+//      authorization-response JWT.
+//
+// That per-subject scope is the per-workspace ISOLATION: workspace A's agent is
+// cryptographically incapable of pub/sub on `agent.B.>`. nats-server enforces the
+// signed permission set; the boundary does not rely on subject naming alone (the M4
+// transport test proved the CODE constructs scoped subjects; THIS proves the SERVER
+// refuses cross-workspace access).
+//
+// SECURITY (§18): the bearer value + the account signing seed are NEVER logged. A
+// validation failure → a DENIAL response (the server refuses the connection); a
+// responder error → the request is left UNANSWERED (fail-closed; the server denies
+// on its callout timeout). The bearer's `exp` caps the minted credential's life so a
+// revoked/expired enrollment cannot outlive its bearer.
+
+import { resolveEnrollmentSigningSecret, type NatsCalloutConfig, type Settings } from "@opengeni/config";
+import { verifyEnrollmentBearer } from "@opengeni/contracts";
+import { getEnrollment, type Database } from "@opengeni/db";
+import {
+  createResponderConnection,
+  decodeAuthRequest,
+  mintAuthResponse,
+  mintUserJwt,
+  workspaceAgentPermissions,
+  type ResponderConnection,
+} from "@opengeni/events";
+import type { Observability } from "@opengeni/observability";
+
+/** The NATS subject nats-server publishes authorization requests on (ADR-26). */
+export const AUTH_CALLOUT_SUBJECT = "$SYS.REQ.USER.AUTH";
+
+export interface AuthCalloutDeps {
+  db: Database;
+  settings: Settings;
+  callout: NatsCalloutConfig;
+  observability?: Observability;
+}
+
+/**
+ * The pure validate→scoped-JWT decision, isolated from the NATS transport so it is
+ * unit-testable. Given the raw authorization-request JWT bytes, returns the signed
+ * authorization-response JWT bytes to reply with — a GRANT (embedding a scoped user
+ * JWT) on success, a DENIAL (carrying `nats.error`, no user JWT) otherwise. NEVER
+ * throws on a bad/invalid request: every failure becomes a signed denial (the
+ * server then refuses the connection cleanly).
+ */
+export async function handleAuthorizationRequest(
+  deps: AuthCalloutDeps,
+  requestBytes: Uint8Array,
+): Promise<Uint8Array> {
+  const requestJwt = Buffer.from(requestBytes).toString("utf8");
+  const decoded = decodeAuthRequest(requestJwt);
+  if (!decoded) {
+    // A malformed request we cannot even read the user_nkey/server_id from — there
+    // is nothing to scope a response to. Leave it for the server's timeout by
+    // throwing (the transport leaves it unanswered, fail-closed).
+    deps.observability?.warn?.("auth-callout: undecodable authorization request", {});
+    throw new Error("undecodable authorization request");
+  }
+
+  const deny = (reason: string): Uint8Array => {
+    // A SIGNED denial: the server reads `nats.error` and refuses the connection.
+    const response = mintAuthResponse({
+      userPublicKey: decoded.userNkey,
+      serverId: decoded.serverId,
+      accountSeed: deps.callout.accountSeed,
+      error: reason,
+    });
+    return Buffer.from(response, "utf8");
+  };
+
+  const bearer = decoded.authToken;
+  if (!bearer) {
+    return deny("missing enrollment bearer");
+  }
+
+  const secret = resolveEnrollmentSigningSecret(deps.settings);
+  if (!secret) {
+    // The credential plane is off for this deployment — deny rather than mint an
+    // unscoped credential. (The responder should not even be running in this case,
+    // but fail-closed regardless.)
+    return deny("enrollment credential plane disabled");
+  }
+
+  const claims = await verifyEnrollmentBearer(secret, bearer);
+  if (!claims) {
+    // Invalid signature / malformed / expired bearer. NEVER log the bearer value.
+    deps.observability?.warn?.("auth-callout: rejected an invalid enrollment bearer", {});
+    return deny("invalid or expired enrollment bearer");
+  }
+
+  // Confirm the enrollment is still ACTIVE — a revoked machine is denied even with a
+  // still-unexpired bearer (the revoke path flips status; this re-checks at connect).
+  const enrollment = await getEnrollment(deps.db, claims.workspaceId, claims.enrollmentId);
+  if (!enrollment || enrollment.status !== "active") {
+    deps.observability?.warn?.("auth-callout: denied a revoked or unknown enrollment", {
+      workspaceId: claims.workspaceId,
+      agentId: claims.agentId,
+    });
+    return deny("enrollment is not active");
+  }
+
+  // Belt-and-braces: the bearer's agentId/enrollmentId must match the row we found.
+  // (verifyEnrollmentBearer already binds them; this guards a future schema where
+  // agentId != enrollmentId.)
+  if (enrollment.id !== claims.enrollmentId) {
+    return deny("enrollment identity mismatch");
+  }
+
+  // GRANT: a user JWT scoped to ONLY this workspace's agent subtree + the reply
+  // inbox. This allow-list IS the per-workspace isolation boundary.
+  const permissions = workspaceAgentPermissions(claims.workspaceId);
+  const userJwt = mintUserJwt({
+    userPublicKey: decoded.userNkey,
+    accountSeed: deps.callout.accountSeed,
+    name: claims.agentId,
+    permissions,
+    // Server-config-mode placement: the embedded user JWT's `aud` is the account
+    // the user binds to (the configured `auth_callout.account`). All agents +
+    // the privileged control plane share this account so subjects route; the
+    // per-workspace isolation is carried by the subject permissions above.
+    audienceAccount: deps.callout.accountName,
+    // Tie the credential's life to the bearer's remaining life: a revoked/expired
+    // enrollment cannot outlive its bearer at the NATS layer either.
+    expiresAtSeconds: claims.exp,
+  });
+  const response = mintAuthResponse({
+    userPublicKey: decoded.userNkey,
+    serverId: decoded.serverId,
+    accountSeed: deps.callout.accountSeed,
+    userJwt,
+  });
+  deps.observability?.info?.("auth-callout: granted a workspace-scoped NATS credential", {
+    workspaceId: claims.workspaceId,
+    agentId: claims.agentId,
+  });
+  return Buffer.from(response, "utf8");
+}
+
+/**
+ * Start the auth-callout responder: open a SEPARATE NATS connection authenticated
+ * as the callout `auth_users` user, subscribe $SYS.REQ.USER.AUTH, and answer every
+ * authorization request via {@link handleAuthorizationRequest}. Returns a handle
+ * whose `close()` drains the connection. Gated by the caller (sandboxSelfhostedEnabled
+ * + a resolvable callout config); a deployment without the callout plane never starts
+ * it.
+ */
+export async function startAuthCalloutResponder(
+  deps: AuthCalloutDeps,
+  natsUrl: string,
+): Promise<ResponderConnection> {
+  const connection = await createResponderConnection(
+    natsUrl,
+    { kind: "user-password", user: deps.callout.user, pass: deps.callout.password },
+    AUTH_CALLOUT_SUBJECT,
+    (bytes) => handleAuthorizationRequest(deps, bytes),
+    { name: "opengeni-auth-callout" },
+  );
+  deps.observability?.info?.("OpenGeni NATS auth-callout responder started", {
+    subject: AUTH_CALLOUT_SUBJECT,
+  });
+  return connection;
+}