@opengeni/api-router 0.23.1 → 0.26.1

package/src/app.ts

@@ -7,6 +7,7 @@ import {
 } from "@opengeni/config";
 import {
   ClientConfig,
+  CodemodeCallRequest,
   ErrorEnvelope,
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION,
@@ -23,7 +24,17 @@ import {
   indexDocumentNow,
   type DocumentServices,
 } from "@opengeni/documents";
-import { dbSql, getWorkspace, rlsContextForWorkspace } from "@opengeni/db";
+import {
+  CodemodeCallBudgetExceededError,
+  CodemodeOperationConflictError,
+  CodemodeOperationNotExecutableError,
+  CodemodePayloadTooLargeError,
+  CodemodeToolApprovalRequiredError,
+  CodemodeToolNotInCatalogError,
+  dbSql,
+  getWorkspace,
+  rlsContextForWorkspace,
+} from "@opengeni/db";
 import { createObservability } from "@opengeni/observability";
 import { createObjectStorage } from "@opengeni/storage";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
@@ -48,9 +59,16 @@ import { createManagedAuth } from "./auth/managed-auth";
 import { createApiSandboxClient, makeResumeBoxById } from "./sandbox/access";
 import { requireLimit } from "@opengeni/core";
 import { buildOpenGeniMcpServer } from "./mcp/server";
-import { isToolspaceGrant, prepareToolspaceMcpSurface } from "./mcp/toolspace";
+import {
+  CodemodeAuthorityError,
+  isCodemodeGrant,
+  readCodemodeOperation,
+  requireActiveCodemodeCatalog,
+  submitAndDispatchCodemodeCall,
+} from "./codemode";
 import { boundedMcpRequest, McpPayloadTooLargeError } from "@opengeni/runtime/mcp-network";
 import { requireAccessKey } from "./http/auth";
+import { allowedCorsOrigin } from "./http/cors";
 import { registerCapabilityRoutes } from "./routes/capabilities";
 import { registerCatalogAssetRoutes } from "./routes/catalog-assets";
 import { registerCodexRoutes } from "./routes/codex";
@@ -58,29 +76,42 @@ import { registerConnectionRoutes } from "./routes/connections";
 import { registerDocumentRoutes } from "./routes/documents";
 import { registerEnrollmentRoutes } from "./routes/enrollments";
 import { registerMachineRoutes } from "./routes/machines";
+import { registerMemorySlackPublicationRoutes } from "./routes/memory-slack-publications";
 import { registerEnvironmentRoutes } from "./routes/environments";
 import { registerFileRoutes } from "./routes/files";
 import { registerApiKeyRoutes } from "./routes/api-keys";
 import { registerBillingRoutes } from "./routes/billing";
+import { registerBrowserIdentityRoutes } from "./routes/browser-identities";
+import { registerBrowserSessionRoutes } from "./routes/browser-sessions";
+import { registerComputerSessionRoutes } from "./routes/computer-sessions";
 import { registerGitHubRoutes } from "./routes/github";
 import { registerInstallRoutes } from "./routes/install";
+import { registerApiIntegrationRoutes } from "./routes/api-integrations";
+import { registerIntegrationFeatureRoutes } from "./routes/integration-features";
 import { registerPackRoutes } from "./routes/packs";
+import { registerPluginRoutes } from "./routes/plugins";
+import { registerSkillRoutes } from "./routes/skills";
 import { registerRigRoutes } from "./routes/rigs";
 import { registerScheduledTaskRoutes } from "./routes/scheduled-tasks";
 import { registerSessionRoutes } from "./routes/sessions";
 import { registerSocialRoutes } from "./routes/social";
 import { registerWorkspaceRoutes } from "./routes/workspaces";
 import { registerWorkspaceInstructionPolicyRoutes } from "./routes/workspace-instruction-policies";
+import { registerCompanyProfileRoutes } from "./routes/company-profile";
 import { registerWorkspaceStateRoutes } from "./routes/workspace-state";
 import { registerWorkspaceArtifactRoutes } from "./routes/workspace-artifacts";
 import { registerPreferenceRegistryRoutes } from "./routes/preference-registry";
 import { registerInsightsRoutes } from "./routes/insights";
 import { registerTranscriptionRoutes } from "./routes/transcriptions";
+import { registerEditableArtifactRoutes } from "./routes/editable-artifacts";
+import { registerVideoGenerationRoutes } from "./routes/video-generation";
 import { projectClientModel } from "./model-catalog";
 import { createTranscriptionService } from "./transcription/service";
 import { createFfmpegTranscriptionSegmenter } from "./transcription/segmenter";
 import { registerSlackInteractionRoutes } from "./integrations/slack-interactions";
 
+export { allowedCorsOrigin } from "./http/cors";
+
 export type {
   ApiRouteDeps,
   AppDependencies,
@@ -249,12 +280,18 @@ export function createAppComposition(deps: AppDependencies): {
       "Accept",
       "Authorization",
       "Content-Type",
+      "Range",
       "X-OpenGeni-Access-Key",
       "X-OpenGeni-Api-Contract",
       "X-OpenGeni-Correlation-Id",
       "X-OpenGeni-Subject",
     ],
-    exposeHeaders: ["X-OpenGeni-Api-Contract", "X-OpenGeni-Correlation-Id"],
+    exposeHeaders: [
+      "Accept-Ranges",
+      "Content-Range",
+      "X-OpenGeni-Api-Contract",
+      "X-OpenGeni-Correlation-Id",
+    ],
   };
   const publicApiCors = cors({
     ...corsHeaders,
@@ -499,17 +536,13 @@ export function createAppComposition(deps: AppDependencies): {
       throw error;
     }
     const grant = await requireMcpAccessGrant(c, routeDeps, workspaceId);
-    const toolspaceGrant = isToolspaceGrant(routeDeps.settings, grant);
     const boundSessionId = grant.metadata?.sessionId;
-    if (toolspaceGrant || typeof boundSessionId === "string") {
-      if (typeof boundSessionId !== "string") {
-        throw new HTTPException(404, { message: "session not found" });
-      }
+    if (typeof boundSessionId === "string") {
       try {
         await requireSessionAuthorization(routeDeps, grant, {
           sessionId: boundSessionId,
-          operation: toolspaceGrant ? "session.toolspace.call" : "session.first_party_mcp.call",
-          surface: toolspaceGrant ? "toolspace" : "first_party_mcp",
+          operation: "session.first_party_mcp.call",
+          surface: "first_party_mcp",
         });
       } catch (error) {
         if (error instanceof SessionAuthorizationDeniedError) {
@@ -523,22 +556,6 @@ export function createAppComposition(deps: AppDependencies): {
         throw error;
       }
     }
-    let toolspace: Awaited<ReturnType<typeof prepareToolspaceMcpSurface>> = null;
-    if (toolspaceGrant) {
-      try {
-        toolspace = await prepareToolspaceMcpSurface({
-          deps: routeDeps,
-          grant,
-        });
-      } catch (error) {
-        if (error instanceof McpPayloadTooLargeError) {
-          throw new HTTPException(413, {
-            message: "MCP tool list exceeds the safety limit",
-          });
-        }
-        throw error;
-      }
-    }
     const workspace = await getWorkspace(routeDeps.db, workspaceId);
     const workspaceMemoryEnabled = resolveWorkspaceMemoryEnabled(workspace?.settings);
     const transport = new WebStandardStreamableHTTPServerTransport({
@@ -546,42 +563,101 @@ export function createAppComposition(deps: AppDependencies): {
     });
     const mcp = buildOpenGeniMcpServer(routeDeps, grant, {
       requestOrigin: new URL(c.req.url).origin,
-      toolspace,
       workspaceMemoryEnabled,
     });
+    await mcp.connect(transport);
+    return await transport.handleRequest(boundedRequest);
+  });
+
+  app.get("/v1/workspaces/:workspaceId/codemode/catalog", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, routeDeps, workspaceId);
+    if (!isCodemodeGrant(grant)) {
+      throw new HTTPException(403, { message: "Codemode access denied" });
+    }
+    try {
+      return c.json((await requireActiveCodemodeCatalog(routeDeps, grant)).catalog);
+    } catch (error) {
+      throw codemodeHttpError(error);
+    }
+  });
+
+  app.post("/v1/workspaces/:workspaceId/codemode/calls", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, routeDeps, workspaceId);
+    if (!isCodemodeGrant(grant)) {
+      throw new HTTPException(403, { message: "Codemode access denied" });
+    }
+    const parsed = CodemodeCallRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: "Invalid Codemode call" });
+    }
+    try {
+      const submission = await submitAndDispatchCodemodeCall(routeDeps, grant, parsed.data);
+      const terminal = ["completed", "failed", "outcome_unknown", "cancelled"].includes(
+        submission.operation.state,
+      );
+      return c.json(submission, terminal ? 200 : 202);
+    } catch (error) {
+      throw codemodeHttpError(error);
+    }
+  });
+
+  app.get("/v1/workspaces/:workspaceId/codemode/calls/:operationId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, routeDeps, workspaceId);
+    if (!isCodemodeGrant(grant)) {
+      throw new HTTPException(403, { message: "Codemode access denied" });
+    }
     try {
-      await mcp.connect(transport);
-      return await transport.handleRequest(boundedRequest);
-    } finally {
-      await toolspace?.close().catch(() => undefined);
+      const operation = await readCodemodeOperation(routeDeps, grant, c.req.param("operationId"));
+      if (!operation)
+        throw new HTTPException(404, {
+          message: "Codemode operation not found",
+        });
+      return c.json(operation);
+    } catch (error) {
+      if (error instanceof HTTPException) throw error;
+      throw codemodeHttpError(error);
     }
   });
 
   registerFileRoutes(app, routeDeps);
   registerApiKeyRoutes(app, routeDeps);
   registerBillingRoutes(app, routeDeps);
+  registerBrowserIdentityRoutes(app, routeDeps);
+  registerBrowserSessionRoutes(app, routeDeps);
+  registerComputerSessionRoutes(app, routeDeps);
   registerDocumentRoutes(app, routeDeps);
   registerGitHubRoutes(app, routeDeps);
   registerInstallRoutes(app, routeDeps);
   registerWorkspaceRoutes(app, routeDeps);
   registerInsightsRoutes(app, routeDeps);
   registerWorkspaceInstructionPolicyRoutes(app, routeDeps);
+  registerCompanyProfileRoutes(app, routeDeps);
   registerWorkspaceStateRoutes(app, routeDeps);
+  registerMemorySlackPublicationRoutes(app, routeDeps);
   registerWorkspaceArtifactRoutes(app, routeDeps);
   registerPreferenceRegistryRoutes(app, routeDeps);
   registerSocialRoutes(app, routeDeps);
   registerConnectionRoutes(app, routeDeps);
   registerCapabilityRoutes(app, routeDeps);
+  registerApiIntegrationRoutes(app, routeDeps);
+  registerIntegrationFeatureRoutes(app, routeDeps);
   registerCatalogAssetRoutes(app, routeDeps);
   registerEnrollmentRoutes(app, routeDeps);
   registerMachineRoutes(app, routeDeps);
   registerEnvironmentRoutes(app, routeDeps);
   registerRigRoutes(app, routeDeps);
   registerPackRoutes(app, routeDeps);
+  registerPluginRoutes(app, routeDeps);
+  registerSkillRoutes(app, routeDeps);
   registerSessionRoutes(app, routeDeps);
   registerScheduledTaskRoutes(app, routeDeps);
   registerCodexRoutes(app, routeDeps);
   registerTranscriptionRoutes(app, routeDeps);
+  registerEditableArtifactRoutes(app, routeDeps);
+  registerVideoGenerationRoutes(app, routeDeps);
   registerSlackInteractionRoutes(app, routeDeps);
 
   app.notFound((c) => {
@@ -653,8 +729,8 @@ async function requireMcpAccessGrant(
   if (hasPermission(grant.permissions, "workspace:read")) {
     return grant;
   }
-  if (isToolspaceGrant(deps.settings, grant)) {
-    return grant;
+  if (isCodemodeGrant(grant)) {
+    requirePermission(grant, "workspace:read");
   }
   // A worker-signed session-bound grant is allowed to reach the transport
   // without inheriting broad workspace read access. The exact session
@@ -687,6 +763,48 @@ function clientAuthConfig(settings: AppDependencies["settings"]) {
   return { mode: "none" as const };
 }
 
+function codemodeHttpError(error: unknown): HTTPException {
+  if (error instanceof SessionAuthorizationDeniedError) {
+    return new HTTPException(404, {
+      message: "session not found",
+      cause: error,
+    });
+  }
+  if (error instanceof SessionAuthorizationUnavailableError) {
+    return new HTTPException(503, {
+      message: "session authorization is unavailable",
+      cause: error,
+    });
+  }
+  if (
+    error instanceof CodemodeAuthorityError ||
+    error instanceof CodemodeOperationNotExecutableError
+  ) {
+    return new HTTPException(409, { message: error.message, cause: error });
+  }
+  if (error instanceof CodemodeOperationConflictError) {
+    return new HTTPException(409, { message: error.message, cause: error });
+  }
+  if (error instanceof CodemodeCallBudgetExceededError) {
+    return new HTTPException(429, { message: error.message, cause: error });
+  }
+  if (error instanceof CodemodeToolNotInCatalogError) {
+    return new HTTPException(404, { message: error.message, cause: error });
+  }
+  if (error instanceof CodemodeToolApprovalRequiredError) {
+    return new HTTPException(409, { message: error.message, cause: error });
+  }
+  if (error instanceof CodemodePayloadTooLargeError) {
+    return new HTTPException(413, { message: error.message, cause: error });
+  }
+  return error instanceof HTTPException
+    ? error
+    : new HTTPException(500, {
+        message: "Codemode request failed",
+        cause: error,
+      });
+}
+
 function clientAnalyticsConfig(settings: AppDependencies["settings"]) {
   if (!settings.analyticsEnabled) {
     return { consentRequired: true, providers: {} };
@@ -721,10 +839,6 @@ function structuredServicesHint(backend: string): {
   return { fileSystem: hasBox, git: hasBox, terminalEvents: hasBox };
 }
 
-export function allowedCorsOrigin(pattern: string, origin: string): boolean {
-  return new RegExp(`^(?:${pattern})$`).test(origin);
-}
-
 function codexCompactionV2ProviderLockedError(
   error: unknown,
 ): CodexCompactionV2ProviderLockedError | null {
@@ -945,6 +1059,23 @@ const routeLabelPatterns: Array<{ pattern: RegExp; label: string }> = [
     pattern: /^\/v1\/workspaces\/[^/]+\/inference-control$/,
     label: "/v1/workspaces/:workspaceId/inference-control",
   },
+  {
+    pattern:
+      /^\/v1\/workspaces\/[^/]+\/sessions\/[^/]+\/fs\/(list|list-batch|read|write|delete|move|mkdir)$/,
+    label: "/v1/workspaces/:workspaceId/sessions/:id/fs/:operation",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/sessions\/[^/]+\/git\/(status|diff|read-batch|log|show)$/,
+    label: "/v1/workspaces/:workspaceId/sessions/:id/git/:operation",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/sessions\/[^/]+\/terminal\/(exec|pty)$/,
+    label: "/v1/workspaces/:workspaceId/sessions/:id/terminal/:operation",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/sessions\/[^/]+\/terminal\/pty\/(write|resize|close)$/,
+    label: "/v1/workspaces/:workspaceId/sessions/:id/terminal/pty/:action",
+  },
   {
     pattern: /^\/v1\/workspaces\/[^/]+\/sessions\/[^/]+\/events\/stream$/,
     label: "/v1/workspaces/:workspaceId/sessions/:id/events/stream",
@@ -1141,6 +1272,80 @@ const routeLabelPatterns: Array<{ pattern: RegExp; label: string }> = [
     pattern: /^\/v1\/workspaces\/[^/]+\/capabilities\/[^/]+\/disable$/,
     label: "/v1/workspaces/:workspaceId/capabilities/:id/disable",
   },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/integrations\/preview$/,
+    label: "/v1/workspaces/:workspaceId/integrations/preview",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/integrations\/install$/,
+    label: "/v1/workspaces/:workspaceId/integrations/install",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/integrations\/presets$/,
+    label: "/v1/workspaces/:workspaceId/integrations/presets",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/integrations\/[^/]+\/instances\/[^/]+\/uninstall-preview$/,
+    label:
+      "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/uninstall-preview",
+  },
+  {
+    pattern:
+      /^\/v1\/workspaces\/[^/]+\/integrations\/[^/]+\/instances\/[^/]+\/features\/[^/]+\/browse$/,
+    label:
+      "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/features/:featureKey/browse",
+  },
+  {
+    pattern:
+      /^\/v1\/workspaces\/[^/]+\/integrations\/[^/]+\/instances\/[^/]+\/features\/[^/]+\/source$/,
+    label:
+      "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/features/:featureKey/source",
+  },
+  {
+    pattern:
+      /^\/v1\/workspaces\/[^/]+\/integrations\/[^/]+\/instances\/[^/]+\/features\/[^/]+\/pause$/,
+    label:
+      "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/features/:featureKey/pause",
+  },
+  {
+    pattern:
+      /^\/v1\/workspaces\/[^/]+\/integrations\/[^/]+\/instances\/[^/]+\/features\/[^/]+\/resume$/,
+    label:
+      "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/features/:featureKey/resume",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/integrations\/[^/]+\/instances\/[^/]+\/features\/[^/]+$/,
+    label:
+      "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/features/:featureKey",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/integrations\/[^/]+\/instances\/[^/]+\/features$/,
+    label: "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/features",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/integrations\/[^/]+\/instances\/[^/]+$/,
+    label: "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/integrations$/,
+    label: "/v1/workspaces/:workspaceId/integrations",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/skills\/preview$/,
+    label: "/v1/workspaces/:workspaceId/skills/preview",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/skills\/install$/,
+    label: "/v1/workspaces/:workspaceId/skills/install",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/skills\/[^/]+\/uninstall-preview$/,
+    label: "/v1/workspaces/:workspaceId/skills/:id/uninstall-preview",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/skills\/[^/]+$/,
+    label: "/v1/workspaces/:workspaceId/skills/:id",
+  },
   {
     pattern: /^\/v1\/workspaces\/[^/]+\/environments$/,
     label: "/v1/workspaces/:workspaceId/environments",
@@ -1173,6 +1378,26 @@ const routeLabelPatterns: Array<{ pattern: RegExp; label: string }> = [
     pattern: /^\/v1\/workspaces\/[^/]+\/packs\/[^/]+$/,
     label: "/v1/workspaces/:workspaceId/packs/:id",
   },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/plugins\/preview$/,
+    label: "/v1/workspaces/:workspaceId/plugins/preview",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/plugins$/,
+    label: "/v1/workspaces/:workspaceId/plugins",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/plugins\/install$/,
+    label: "/v1/workspaces/:workspaceId/plugins/install",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/plugins\/[^/]+\/uninstall-preview$/,
+    label: "/v1/workspaces/:workspaceId/plugins/:pluginKey/uninstall-preview",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/plugins\/[^/]+$/,
+    label: "/v1/workspaces/:workspaceId/plugins/:pluginKey",
+  },
   {
     pattern: /^\/v1\/workspaces\/[^/]+\/social\/connections$/,
     label: "/v1/workspaces/:workspaceId/social/connections",
@@ -1189,6 +1414,10 @@ const routeLabelPatterns: Array<{ pattern: RegExp; label: string }> = [
     pattern: /^\/v1\/workspaces\/[^/]+\/connections\/oauth\/start$/,
     label: "/v1/workspaces/:workspaceId/connections/oauth/start",
   },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/integrations\/oauth\/start$/,
+    label: "/v1/workspaces/:workspaceId/integrations/oauth/start",
+  },
   {
     pattern: /^\/v1\/workspaces\/[^/]+\/connections\/slack-bot\/install$/,
     label: "/v1/workspaces/:workspaceId/connections/slack-bot/install",
@@ -1202,6 +1431,14 @@ const routeLabelPatterns: Array<{ pattern: RegExp; label: string }> = [
     pattern: /^\/v1\/integrations\/oauth\/callback$/,
     label: "/v1/integrations/oauth/callback",
   },
+  {
+    pattern: /^\/v1\/integrations\/provider-oauth\/callback$/,
+    label: "/v1/integrations/provider-oauth/callback",
+  },
+  {
+    pattern: /^\/v1\/integrations\/google-drive\/callback$/,
+    label: "/v1/integrations/google-drive/callback",
+  },
   {
     pattern: /^\/v1\/integrations\/oauth\/client-metadata\.json$/,
     label: "/v1/integrations/oauth/client-metadata.json",

package/src/browser-controller-authority.ts

@@ -0,0 +1,137 @@
+import { createHmac } from "node:crypto";
+import type { InteractionPlacement } from "@opengeni/contracts";
+
+type BrowserControllerAuthorityScope = {
+  rootSecret: string;
+  accountId: string;
+  workspaceId: string;
+  placement: InteractionPlacement;
+  placementInstanceId: string;
+};
+
+type BrowserSessionAuthorityScope = BrowserControllerAuthorityScope & {
+  browserSessionId: string;
+  controllerGeneration: string;
+  tokenGeneration: number;
+};
+
+type ComputerSessionAuthorityScope = BrowserControllerAuthorityScope & {
+  computerSessionId: string;
+  controllerGeneration: string;
+  tokenGeneration: number;
+};
+
+/** Stable placement-admin authority. This token is installed owner-only inside
+ * the exact placement and is never persisted or returned by the public API. */
+export function deriveBrowserControllerAdminToken(scope: BrowserControllerAuthorityScope): string {
+  return derive(scope.rootSecret, "placement-admin.v1", [
+    scope.accountId,
+    scope.workspaceId,
+    placementKey(scope.placement),
+    scope.placementInstanceId,
+  ]);
+}
+
+/** Deterministic controller credentials. The durable generations are the only
+ * stored authority; plaintext tokens can be reconstructed only by API replicas
+ * holding the deployment HMAC root. */
+export function deriveBrowserSessionControllerTokens(scope: BrowserSessionAuthorityScope): {
+  controlToken: string;
+  viewToken: string;
+} {
+  const fields = [
+    scope.accountId,
+    scope.workspaceId,
+    placementKey(scope.placement),
+    scope.placementInstanceId,
+    scope.browserSessionId,
+    scope.controllerGeneration,
+    scope.tokenGeneration,
+  ] as const;
+  return {
+    controlToken: derive(scope.rootSecret, "session-control.v1", fields),
+    viewToken: derive(scope.rootSecret, "session-view.v1", fields),
+  };
+}
+
+export function deriveBrowserViewGrantToken(
+  scope: BrowserSessionAuthorityScope & { grantId: string; expiresAt: string },
+): string {
+  return derive(scope.rootSecret, "frame-view-grant.v1", [
+    scope.accountId,
+    scope.workspaceId,
+    placementKey(scope.placement),
+    scope.placementInstanceId,
+    scope.browserSessionId,
+    scope.controllerGeneration,
+    scope.tokenGeneration,
+    scope.grantId,
+    scope.expiresAt,
+  ]);
+}
+
+/** ComputerSession credentials share the placement controller root while using
+ * resource-specific domains. Browser and computer authority cannot collide. */
+export function deriveComputerSessionControllerTokens(scope: ComputerSessionAuthorityScope): {
+  controlToken: string;
+  viewToken: string;
+} {
+  const fields = [
+    scope.accountId,
+    scope.workspaceId,
+    placementKey(scope.placement),
+    scope.placementInstanceId,
+    scope.computerSessionId,
+    scope.controllerGeneration,
+    scope.tokenGeneration,
+  ] as const;
+  return {
+    controlToken: derive(scope.rootSecret, "computer-session-control.v1", fields),
+    viewToken: derive(scope.rootSecret, "computer-session-view.v1", fields),
+  };
+}
+
+export function deriveComputerViewGrantToken(
+  scope: ComputerSessionAuthorityScope & { grantId: string; expiresAt: string },
+): string {
+  return derive(scope.rootSecret, "computer-frame-view-grant.v1", [
+    scope.accountId,
+    scope.workspaceId,
+    placementKey(scope.placement),
+    scope.placementInstanceId,
+    scope.computerSessionId,
+    scope.controllerGeneration,
+    scope.tokenGeneration,
+    scope.grantId,
+    scope.expiresAt,
+  ]);
+}
+
+function derive(rootSecret: string, domain: string, fields: readonly (string | number)[]): string {
+  if (!rootSecret) throw new Error("browser controller authority root is unavailable");
+  const hmac = createHmac("sha256", rootSecret);
+  hmac.update("opengeni.browser-controller-authority\0", "utf8");
+  writeField(hmac, domain);
+  for (const field of fields) writeField(hmac, String(field));
+  return `ogb.${hmac.digest("base64url")}`;
+}
+
+function writeField(hmac: ReturnType<typeof createHmac>, value: string): void {
+  const bytes = Buffer.from(value, "utf8");
+  hmac.update(String(bytes.byteLength), "utf8");
+  hmac.update(":", "utf8");
+  hmac.update(bytes);
+}
+
+function placementKey(placement: InteractionPlacement): string {
+  switch (placement.kind) {
+    case "sandbox_group":
+      return `sandbox_group:${placement.sandboxGroupId}`;
+    case "connected_machine":
+      return `connected_machine:${placement.sandboxId}`;
+    case "attached_device":
+      return `attached_device:${placement.deviceId}`;
+    case "external_provider":
+      return `external_provider:${placement.providerId}:${placement.placementId}`;
+  }
+}