@opengeni/api-router 2.6.4 → 2.10.0-canary.0

package/src/app.ts

@@ -18,6 +18,8 @@ import {
   resolveWorkspaceMemoryPromptMode,
   VOICE_INPUT_ACCEPTED_MIME_TYPES,
   TRANSCRIPTION_RECORDING_PROVIDER_SEGMENT_SECONDS,
+  ToolGatewayApprovalRequest,
+  ToolGatewayCallRequest,
   type AccessGrant,
   type ErrorCode,
 } from "@opengeni/contracts";
@@ -41,7 +43,6 @@ import {
   reapManagedAuthIsolatedSessions,
   reapExpiredManagedAuthSessionSets,
   rlsContextForWorkspace,
-  withSessionRlsActorContext,
 } from "@opengeni/db";
 import { requireSessionEventDurableFanoutCapability } from "@opengeni/events";
 import { githubAppBotIdentityWarnings } from "@opengeni/github";
@@ -63,9 +64,11 @@ import {
   ManagedAuthActorLeaseOutcomeUnknownError,
   hasPermission,
   requireAccessGrant,
-  requireLiveAgentAttemptAuthorization,
+  requireAccessGrantAuthorization,
   requirePermission,
   releaseManagedAuthRequestActorLease,
+  resolveCatalogSettings,
+  resolveWorkspaceCatalogSettings,
   validateManagedAuthRequestActorLease,
   requireSessionAuthorization,
   SessionAuthorizationDeniedError,
@@ -94,13 +97,33 @@ import {
   runManagedAuthProvider,
 } from "./auth/managed-auth-attempt-context";
 import { createManagedEmailTransport } from "./auth/managed-email";
-import { assertManagedEmailTransportMetadata } from "./auth/organization-user-setup";
+import {
+  assertManagedEmailTransportMetadata,
+  assertOrganizationUserSetupQueryTransportConfigured,
+} from "./auth/organization-user-setup";
 import { createApiSandboxClient, makeResumeBoxById } from "./sandbox/access";
 import { requireLimit } from "@opengeni/core";
 import { buildOpenGeniMcpServer } from "./mcp/server";
+import {
+  buildWorkspaceToolGatewayMcpServer,
+  approveWorkspaceToolGatewayCall,
+  callWorkspaceToolGateway,
+  grantUsesAttemptScopedMcp,
+  prepareMcpOAuthWorkspaceToolGateway,
+  prepareWorkspaceToolGateway,
+  workspaceToolGatewayDeclarations,
+} from "./workspace-tool-gateway";
+import {
+  isMcpOAuthResourcePath,
+  mcpOAuthAuthenticateHeader,
+  mcpOAuthBearerToken,
+  registerMcpOAuthRoutes,
+  resolveMcpOAuthRouteAccess,
+} from "./mcp-oauth";
 import {
   CodemodeAuthorityError,
   CodemodeCatalogNotReadyError,
+  CodemodeCatalogStaleError,
   isCodemodeGrant,
   readCodemodeOperation,
   requireActiveCodemodeCatalog,
@@ -113,9 +136,11 @@ import {
 } from "@opengeni/runtime/sandbox";
 import { requireAccessKey } from "./http/auth";
 import { allowedCorsOrigin } from "./http/cors";
+import { withAccessGrantSessionRlsContext } from "./access-grant-rls";
 import { registerCapabilityRoutes } from "./routes/capabilities";
 import { registerCatalogAssetRoutes } from "./routes/catalog-assets";
 import { registerCodexRoutes } from "./routes/codex";
+import { registerOrganizationModelProviderRoutes } from "./routes/organization-model-providers";
 import { registerSuperGrokRoutes } from "./routes/supergrok";
 import { registerConnectionRoutes } from "./routes/connections";
 import { registerDocumentRoutes } from "./routes/documents";
@@ -222,10 +247,27 @@ export function createApp(deps: AppDependencies): Hono {
   return createAppComposition(deps).app;
 }
 
+export async function resolveWorkspaceMcpRouteDeps(
+  routeDeps: ApiRouteDeps,
+  grant: AccessGrant,
+): Promise<ApiRouteDeps> {
+  const catalogSourceSettings = routeDeps.catalogSourceSettings ?? routeDeps.settings;
+  const resolvedCatalog = await resolveWorkspaceCatalogSettings(
+    routeDeps.db,
+    catalogSourceSettings,
+    {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+    },
+  );
+  return { ...routeDeps, catalogSourceSettings, settings: resolvedCatalog.settings };
+}
+
 export function createAppComposition(deps: AppDependencies): {
   app: Hono;
   routeDeps: ApiRouteDeps;
 } {
+  assertOrganizationUserSetupQueryTransportConfigured(deps.settings);
   // The request-scoped workspace control-prefix budget is validated once by
   // @opengeni/config at boot; install it for every request-scoped db command
   // (Send/Steer/control/queue/settings/delete) built by this app.
@@ -358,6 +400,7 @@ export function createAppComposition(deps: AppDependencies): {
       : deps.transcriptionSegmenter;
   const routeDeps: ApiRouteDeps = {
     ...deps,
+    resolveCatalogSettings: () => resolveCatalogSettings(deps.db, deps.settings),
     observability,
     githubStateSecret:
       deps.githubStateSecret ?? deps.settings.githubAppManifestStateSecret ?? crypto.randomUUID(),
@@ -383,6 +426,18 @@ export function createAppComposition(deps: AppDependencies): {
     await next();
   });
 
+  app.use("*", async (c, next) => {
+    const oauthToken = mcpOAuthBearerToken(c.req.raw);
+    if (
+      oauthToken &&
+      (!deps.settings.mcpOauthEnabled || !isMcpOAuthResourcePath(new URL(c.req.url).pathname))
+    ) {
+      c.header("www-authenticate", 'Bearer error="invalid_token"');
+      return c.json({ error: "invalid_token" }, 401);
+    }
+    await next();
+  });
+
   const corsHeaders = {
     allowHeaders: [
       "Accept",
@@ -403,6 +458,21 @@ export function createAppComposition(deps: AppDependencies): {
       "X-OpenGeni-Actor-Epoch",
       "X-OpenGeni-Actor-State",
       "X-OpenGeni-Correlation-Id",
+      "X-OpenGeni-Covered-First",
+      "X-OpenGeni-Covered-Last",
+      "X-OpenGeni-Event-Direction",
+      "X-OpenGeni-Event-Mode",
+      "X-OpenGeni-Event-Result",
+      "X-OpenGeni-Event-Result-Mode",
+      "X-OpenGeni-Forensic-Exact",
+      "X-OpenGeni-Has-More",
+      "X-OpenGeni-Next-After",
+      "X-OpenGeni-Next-Before",
+      "X-OpenGeni-Page-Bytes",
+      "X-OpenGeni-Page-Max-Bytes",
+      "X-OpenGeni-Page-Truncated",
+      "X-OpenGeni-Payload-Mode",
+      "X-OpenGeni-Truncated-By",
     ],
   };
   const publicApiCors = cors({
@@ -764,12 +834,16 @@ export function createAppComposition(deps: AppDependencies): {
     }),
   );
 
+  registerMcpOAuthRoutes(app, routeDeps);
+
   app.get("/v1/config/client", async (c) => {
     c.header("cache-control", "no-store");
-    const codexCatalogSettings = deps.settings.codexSubscriptionEnabled
-      ? withCodexCatalogProvider(deps.settings)
-      : deps.settings;
-    const catalogSettings = deps.settings.supergrokSubscriptionEnabled
+    const resolvedCatalog = await resolveCatalogSettings(deps.db, deps.settings);
+    const baseCatalogSettings = resolvedCatalog.settings;
+    const codexCatalogSettings = baseCatalogSettings.codexSubscriptionEnabled
+      ? withCodexCatalogProvider(baseCatalogSettings)
+      : baseCatalogSettings;
+    const catalogSettings = baseCatalogSettings.supergrokSubscriptionEnabled
       ? withXaiSubscriptionCatalogProvider(codexCatalogSettings)
       : codexCatalogSettings;
     return c.json(
@@ -861,7 +935,54 @@ export function createAppComposition(deps: AppDependencies): {
       }
       throw error;
     }
-    const grant = await requireMcpAccessGrant(c, routeDeps, workspaceId);
+    let oauthAccess: Awaited<ReturnType<typeof resolveMcpOAuthRouteAccess>>;
+    try {
+      oauthAccess = await resolveMcpOAuthRouteAccess(routeDeps, c.req.raw, workspaceId);
+    } catch (error) {
+      if (error instanceof HTTPException && error.status === 401) {
+        c.header(
+          "www-authenticate",
+          mcpOAuthAuthenticateHeader(routeDeps, new URL(c.req.url).pathname),
+        );
+      }
+      throw error;
+    }
+    if (oauthAccess) {
+      return await withAccessGrantSessionRlsContext(routeDeps, oauthAccess.grant, async () => {
+        const prepared = await prepareMcpOAuthWorkspaceToolGateway(
+          routeDeps,
+          oauthAccess.grant,
+          oauthAccess.allowedToolIdentities,
+        );
+        const transport = new WebStandardStreamableHTTPServerTransport({
+          enableJsonResponse: true,
+        });
+        const mcp = buildWorkspaceToolGatewayMcpServer(
+          prepared,
+          oauthAccess.grant,
+          routeDeps.observability,
+        );
+        try {
+          await mcp.connect(transport);
+          return await handleMcpRequestWithClientAbort(transport, boundedRequest, c.req.raw.signal);
+        } finally {
+          await Promise.allSettled([mcp.close(), prepared.close()]);
+        }
+      });
+    }
+    let authorization: Awaited<ReturnType<typeof requireMcpAccessGrantAuthorization>>;
+    try {
+      authorization = await requireMcpAccessGrantAuthorization(c, routeDeps, workspaceId);
+    } catch (error) {
+      if (deps.settings.mcpOauthEnabled && error instanceof HTTPException && error.status === 401) {
+        c.header(
+          "www-authenticate",
+          mcpOAuthAuthenticateHeader(routeDeps, new URL(c.req.url).pathname),
+        );
+      }
+      throw error;
+    }
+    const grant = authorization.grant;
     return await withAccessGrantSessionRlsContext(routeDeps, grant, async () => {
       const boundSessionId = grant.metadata?.sessionId;
       if (typeof boundSessionId === "string") {
@@ -889,7 +1010,18 @@ export function createAppComposition(deps: AppDependencies): {
       const transport = new WebStandardStreamableHTTPServerTransport({
         enableJsonResponse: true,
       });
-      const mcp = buildOpenGeniMcpServer(routeDeps, grant, {
+      if (!grantUsesAttemptScopedMcp(grant)) {
+        const prepared = await prepareWorkspaceToolGateway(routeDeps, authorization);
+        const mcp = buildWorkspaceToolGatewayMcpServer(prepared, grant, routeDeps.observability);
+        try {
+          await mcp.connect(transport);
+          return await handleMcpRequestWithClientAbort(transport, boundedRequest, c.req.raw.signal);
+        } finally {
+          await Promise.allSettled([mcp.close(), prepared.close()]);
+        }
+      }
+      const mcpDeps = await resolveWorkspaceMcpRouteDeps(routeDeps, grant);
+      const mcp = buildOpenGeniMcpServer(mcpDeps, grant, {
         requestOrigin: new URL(c.req.url).origin,
         workspaceMemoryEnabled,
         workspaceMemoryPromptMode,
@@ -901,6 +1033,100 @@ export function createAppComposition(deps: AppDependencies): {
     });
   });
 
+  app.get("/v1/workspaces/:workspaceId/tools/catalog", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      routeDeps,
+      workspaceId,
+      "workspace:read",
+    );
+    const prepared = await prepareWorkspaceToolGateway(routeDeps, authorization);
+    try {
+      c.header("cache-control", "no-store");
+      return c.json(prepared.toolGatewayCatalog);
+    } finally {
+      await prepared.close();
+    }
+  });
+
+  app.post("/v1/workspaces/:workspaceId/tools/calls", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      routeDeps,
+      workspaceId,
+      "workspace:read",
+    );
+    const grant = authorization.grant;
+    const parsed = ToolGatewayCallRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: "Invalid tool gateway call" });
+    }
+    const prepared = await prepareWorkspaceToolGateway(routeDeps, authorization);
+    try {
+      return c.json(
+        await callWorkspaceToolGateway(
+          prepared,
+          grant,
+          parsed.data,
+          routeDeps.db,
+          undefined,
+          routeDeps.observability,
+        ),
+      );
+    } finally {
+      await prepared.close();
+    }
+  });
+
+  app.post("/v1/workspaces/:workspaceId/tools/approvals", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      routeDeps,
+      workspaceId,
+      "workspace:read",
+    );
+    const parsed = ToolGatewayApprovalRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: "Invalid tool gateway approval" });
+    }
+    const prepared = await prepareWorkspaceToolGateway(routeDeps, authorization);
+    try {
+      return c.json(
+        await approveWorkspaceToolGatewayCall(
+          prepared,
+          authorization.grant,
+          routeDeps.db,
+          parsed.data,
+          undefined,
+          routeDeps.observability,
+        ),
+        201,
+      );
+    } finally {
+      await prepared.close();
+    }
+  });
+
+  app.get("/v1/workspaces/:workspaceId/tools/declarations", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      routeDeps,
+      workspaceId,
+      "workspace:read",
+    );
+    const prepared = await prepareWorkspaceToolGateway(routeDeps, authorization);
+    try {
+      c.header("cache-control", "no-store");
+      return c.json(workspaceToolGatewayDeclarations(prepared));
+    } finally {
+      await prepared.close();
+    }
+  });
+
   app.get("/v1/workspaces/:workspaceId/codemode/catalog", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, routeDeps, workspaceId);
@@ -996,6 +1222,7 @@ export function createAppComposition(deps: AppDependencies): {
   registerSessionRoutes(app, routeDeps);
   registerScheduledTaskRoutes(app, routeDeps);
   registerCodexRoutes(app, routeDeps);
+  registerOrganizationModelProviderRoutes(app, routeDeps);
   registerSuperGrokRoutes(app, routeDeps);
   registerTranscriptionRoutes(app, routeDeps);
   registerEditableArtifactRoutes(app, routeDeps);
@@ -1093,7 +1320,11 @@ const publicWorkspaceBrowserRoutePatterns = [
 ] as const;
 
 export function workspaceActorContextExempt(method: string, pathname: string): boolean {
-  if (/^\/v1\/workspaces\/[^/]+\/mcp$/.test(pathname)) return true;
+  // The account-scoped provisioning route shares the workspace collection prefix.
+  // Hono's trailing wildcard also matches it, but "external" is not a workspace UUID;
+  // the route performs its own organization API-key authorization.
+  if (method === "PUT" && pathname === "/v1/workspaces/external") return true;
+  if (/^\/v1\/workspaces\/[^/]+\/mcp(?:\/(?:docs|files))?$/.test(pathname)) return true;
   if (
     method === "GET" &&
     publicWorkspaceBrowserRoutePatterns.some((route) => route.test(pathname))
@@ -1122,46 +1353,15 @@ async function validateCodexAccountTarget(request: Request): Promise<void> {
   }
 }
 
-async function withAccessGrantSessionRlsContext<T>(
-  deps: ApiRouteDeps,
-  grant: AccessGrant,
-  fn: () => Promise<T>,
-): Promise<T> {
-  if (grant.principalKind !== "agent_attempt") {
-    return await withSessionRlsActorContext({ subjectId: grant.subjectId }, fn);
-  }
-  const callerSessionId = grant.metadata?.sessionId;
-  if (typeof callerSessionId !== "string") {
-    throw new HTTPException(403, { message: "agent attempt authority is invalid" });
-  }
-  try {
-    const actor = await requireLiveAgentAttemptAuthorization(deps.db, grant, callerSessionId);
-    return await withSessionRlsActorContext(
-      {
-        subjectId: actor.subjectId,
-        initiatingHumanSubjectId: actor.initiatingHumanSubjectId,
-      },
-      fn,
-    );
-  } catch (error) {
-    if (error instanceof SessionAuthorizationDeniedError) {
-      throw new HTTPException(403, {
-        message: "agent attempt authority is invalid",
-        cause: error,
-      });
-    }
-    throw error;
-  }
-}
-
-async function requireMcpAccessGrant(
+async function requireMcpAccessGrantAuthorization(
   c: Parameters<typeof requireAccessGrant>[0],
   deps: ApiRouteDeps,
   workspaceId: string,
-): Promise<AccessGrant> {
-  const grant = await requireAccessGrant(c, deps, workspaceId);
+): Promise<Awaited<ReturnType<typeof requireAccessGrantAuthorization>>> {
+  const authorization = await requireAccessGrantAuthorization(c, deps, workspaceId);
+  const grant = authorization.grant;
   if (hasPermission(grant.permissions, "workspace:read")) {
-    return grant;
+    return authorization;
   }
   if (isCodemodeGrant(grant)) {
     requirePermission(grant, "workspace:read");
@@ -1171,10 +1371,10 @@ async function requireMcpAccessGrant(
   // authorization seam runs immediately after this gate, and tool registration
   // still exposes only capabilities permitted by the delegated grant.
   if (grant.metadata?.delegated === true && typeof grant.metadata.sessionId === "string") {
-    return grant;
+    return authorization;
   }
   requirePermission(grant, "workspace:read");
-  return grant;
+  return authorization;
 }
 
 function clientAuthConfig(settings: AppDependencies["settings"]) {
@@ -1231,6 +1431,15 @@ function codemodeHttpError(error: unknown): HTTPException {
       details: { code: error.code },
     });
   }
+  if (error instanceof CodemodeCatalogStaleError) {
+    return new ApiHttpError(409, {
+      code: "conflict",
+      message: error.message,
+      retryable: true,
+      outcomeUnknown: false,
+      details: { code: error.code },
+    });
+  }
   if (error instanceof CodemodeAuthorityError) {
     return new ApiHttpError(error.reason === "invalid_grant" ? 403 : 409, {
       code: error.reason === "invalid_grant" ? "forbidden" : "conflict",
@@ -1379,11 +1588,14 @@ type ReadinessCheckResult = { ok: boolean; error?: string };
 function readinessChecks(deps: AppDependencies): ReadinessChecks {
   const configuredNatsCheck = deps.readinessChecks?.nats;
   return {
-    db:
-      deps.readinessChecks?.db ??
-      (async () => {
+    db: async () => {
+      if (deps.readinessChecks?.db) {
+        await deps.readinessChecks.db();
+      } else {
         await deps.db.execute(dbSql`select 1`);
-      }),
+      }
+      await resolveCatalogSettings(deps.db, deps.settings);
+    },
     nats: async () => {
       requireSessionEventDurableFanoutCapability(deps.bus);
       if (configuredNatsCheck) {
@@ -1458,6 +1670,20 @@ const routeLabelPatterns: Array<{
   pattern: RegExp;
   label: string | ((match: RegExpMatchArray) => string);
 }> = [
+  {
+    pattern: /^\/\.well-known\/oauth-authorization-server$/,
+    label: "/.well-known/oauth-authorization-server",
+  },
+  {
+    pattern:
+      /^\/\.well-known\/oauth-protected-resource\/v1\/workspaces\/[^/]+\/mcp(?:\/(docs|files))?$/,
+    label: (match) =>
+      `/.well-known/oauth-protected-resource/v1/workspaces/:workspaceId/mcp${match[1] ? `/${match[1]}` : ""}`,
+  },
+  {
+    pattern: /^\/oauth\/(register|authorize|token)$/,
+    label: (match) => `/oauth/${match[1]}`,
+  },
   { pattern: /^\/healthz$/, label: "/healthz" },
   { pattern: /^\/readyz$/, label: "/readyz" },
   { pattern: /^\/traffic-readyz$/, label: "/traffic-readyz" },
@@ -1543,6 +1769,22 @@ const routeLabelPatterns: Array<{
     pattern: /^\/v1\/workspaces\/[^/]+\/mcp\/files$/,
     label: "/v1/workspaces/:workspaceId/mcp/files",
   },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/tools\/catalog$/,
+    label: "/v1/workspaces/:workspaceId/tools/catalog",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/tools\/calls$/,
+    label: "/v1/workspaces/:workspaceId/tools/calls",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/tools\/approvals$/,
+    label: "/v1/workspaces/:workspaceId/tools/approvals",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/tools\/declarations$/,
+    label: "/v1/workspaces/:workspaceId/tools/declarations",
+  },
   {
     pattern: /^\/v1\/workspaces\/[^/]+\/default-rig$/,
     label: "/v1/workspaces/:workspaceId/default-rig",
@@ -2307,5 +2549,6 @@ export function isApiContractProtectedMutation(method: string, pathname: string)
   ) {
     return false;
   }
-  return !pathname.split("/").includes("mcp");
+  const segments = pathname.split("/");
+  return !segments.includes("mcp") && !segments.includes("codemode");
 }

package/src/auth/organization-user-setup.ts

@@ -2,6 +2,7 @@ import type { Settings } from "@opengeni/config";
 import type { ManagedEmailTransport } from "@opengeni/core";
 
 const encoder = new TextEncoder();
+export type OrganizationUserSetupEmailTokenTransport = "fragment" | "query";
 
 /**
  * Prove that the stable invited-user setup bearer can be constructed before an
@@ -13,11 +14,30 @@ export function assertOrganizationUserSetupDeliveryConfigured(
   settings: Settings,
   transport: ManagedEmailTransport,
 ): void {
+  assertOrganizationUserSetupQueryTransportConfigured(settings);
   requiredSetupSecret(settings);
   requiredPublicBaseUrl(settings);
   assertManagedEmailTransportMetadata(transport);
 }
 
+/** Enforce the query-bearing edge proof for env and embedded settings alike. */
+export function assertOrganizationUserSetupQueryTransportConfigured(
+  settings: Pick<
+    Settings,
+    | "organizationUserSetupEmailTokenTransport"
+    | "organizationUserSetupQueryEdgeSanitizationConfirmed"
+  >,
+): void {
+  if (
+    settings.organizationUserSetupEmailTokenTransport === "query" &&
+    !settings.organizationUserSetupQueryEdgeSanitizationConfirmed
+  ) {
+    throw new Error(
+      "OPENGENI_ORGANIZATION_USER_SETUP_QUERY_EDGE_SANITIZATION_CONFIRMED=true is required when OPENGENI_ORGANIZATION_USER_SETUP_EMAIL_TOKEN_TRANSPORT=query",
+    );
+  }
+}
+
 /** Reject an invalid embedded-provider contract before any durable boundary. */
 export function assertManagedEmailTransportMetadata(transport: ManagedEmailTransport): void {
   if (
@@ -42,7 +62,11 @@ export function assertManagedEmailTransportMetadata(transport: ManagedEmailTrans
 
 export async function deriveOrganizationUserSetupToken(
   settings: Settings,
-  input: { invitationId: string; deliveryId: string },
+  input: {
+    invitationId: string;
+    deliveryId: string;
+    transport?: OrganizationUserSetupEmailTokenTransport;
+  },
 ): Promise<{ token: string; digest: string; url: string }> {
   const secret = requiredSetupSecret(settings);
   const key = await crypto.subtle.importKey(
@@ -62,7 +86,15 @@ export async function deriveOrganizationUserSetupToken(
   const token = base64Url(new Uint8Array(signature));
   const digest = await sha256Hex(token);
   const url = new URL("/setup-account", requiredPublicBaseUrl(settings));
-  url.hash = new URLSearchParams({ token }).toString();
+  if ((input.transport ?? settings.organizationUserSetupEmailTokenTransport) === "query") {
+    // Email security gateways routinely wrap links and may discard URL
+    // fragments. Enable this only after the compatibility web rollout; the
+    // browser's first executable head bootstrap scrubs query authority without
+    // redirecting or allowing a query-bearing subresource Referer.
+    url.searchParams.set("token", token);
+  } else {
+    url.hash = new URLSearchParams({ token }).toString();
+  }
   return { token, digest, url: url.toString() };
 }
 
@@ -107,9 +139,9 @@ export function renderOrganizationUserSetupEmail(input: OrganizationUserSetupEma
   return {
     from: input.senderEmail,
     to: input.recipientEmail,
-    subject: `Join ${input.organizationName} on OpenGeni`,
-    text: `${greeting}\n\nYou have been invited to ${input.organizationName} as ${role}.\n\n${workspaceSummary}\n\nThis invitation grants only the organization role and shared workspace access listed above. It never shares anyone's Personal workspace.\n\nSet up your account: ${input.setupUrl}\n\nIf you already have an OpenGeni account, sign in and accept the invitation instead.`,
-    html: `<p>${escapeHtml(greeting)}</p><p>You have been invited to <strong>${escapeHtml(input.organizationName)}</strong> as ${escapeHtml(role)}.</p>${workspaceHtml}<p>This invitation grants only the organization role and shared workspace access listed above. It never shares anyone's Personal workspace.</p><p><a href="${escapeHtml(input.setupUrl)}">Set up your account</a></p><p>If you already have an OpenGeni account, sign in and accept the invitation instead.</p>`,
+    subject: `You're invited to join ${input.organizationName} on OpenGeni`,
+    text: `${greeting}\n\nYou've been invited to join ${input.organizationName} on OpenGeni as ${role}.\n\n${workspaceSummary}\n\nThis invitation grants only the organization role and shared workspace access listed above. It never shares anyone's Personal workspace.\n\nAccept invitation to ${input.organizationName}: ${input.setupUrl}\n\nYou'll sign in or create an account before joining. Already use OpenGeni? Open this invitation and choose Sign in as ${input.recipientEmail}. OpenGeni will show the invitation immediately after you sign in.`,
+    html: `<p>${escapeHtml(greeting)}</p><p>You've been invited to join <strong>${escapeHtml(input.organizationName)}</strong> on OpenGeni as ${escapeHtml(role)}.</p>${workspaceHtml}<p>This invitation grants only the organization role and shared workspace access listed above. It never shares anyone's Personal workspace.</p><p><a href="${escapeHtml(input.setupUrl)}">Accept invitation to ${escapeHtml(input.organizationName)}</a></p><p>You'll sign in or create an account before joining. Already use OpenGeni? Open this invitation and choose <strong>Sign in as ${escapeHtml(input.recipientEmail)}</strong>. OpenGeni will show the invitation immediately after you sign in.</p>`,
   };
 }
 
@@ -134,6 +166,64 @@ export async function organizationUserSetupPayloadDigest(input: {
   );
 }
 
+export async function resolveOrganizationUserSetupDeliveryEmail(
+  settings: Settings,
+  input: {
+    invitationId: string;
+    deliveryId: string;
+    senderEmail: string;
+    recipientEmail: string;
+    recipientName: string | null;
+    organizationName: string;
+    organizationRole: "owner" | "admin" | "member";
+    sharedWorkspaceAccess: OrganizationUserSetupEmailSnapshot["sharedWorkspaceAccess"];
+    providerIdempotencyScope: string;
+    frozenTransport: OrganizationUserSetupEmailTokenTransport | null;
+    frozenPayloadDigest: string | null;
+  },
+): Promise<{
+  transport: OrganizationUserSetupEmailTokenTransport;
+  token: string;
+  tokenDigest: string;
+  payloadDigest: string;
+  message: ReturnType<typeof renderOrganizationUserSetupEmail>;
+}> {
+  const candidates: OrganizationUserSetupEmailTokenTransport[] = input.frozenTransport
+    ? [input.frozenTransport]
+    : input.frozenPayloadDigest
+      ? ["fragment", "query"]
+      : [settings.organizationUserSetupEmailTokenTransport];
+  for (const transport of candidates) {
+    const setup = await deriveOrganizationUserSetupToken(settings, {
+      invitationId: input.invitationId,
+      deliveryId: input.deliveryId,
+      transport,
+    });
+    const message = renderOrganizationUserSetupEmail({
+      senderEmail: input.senderEmail,
+      recipientEmail: input.recipientEmail,
+      recipientName: input.recipientName,
+      organizationName: input.organizationName,
+      organizationRole: input.organizationRole,
+      sharedWorkspaceAccess: input.sharedWorkspaceAccess,
+      setupUrl: setup.url,
+    });
+    const payloadDigest = await organizationUserSetupPayloadDigest({
+      ...message,
+      providerIdempotencyScope: input.providerIdempotencyScope,
+    });
+    if (input.frozenPayloadDigest && payloadDigest !== input.frozenPayloadDigest) continue;
+    return {
+      transport,
+      token: setup.token,
+      tokenDigest: setup.digest,
+      payloadDigest,
+      message,
+    };
+  }
+  throw new Error("Organization setup delivery transport does not match its frozen payload");
+}
+
 export async function organizationUserSetupRequestFingerprint(
   settings: Settings,
   input: { tokenDigest: string; name: string; password: string },