@opengeni/api-router 3.0.1 → 3.1.2

package/src/routes/subscription-account-pools.ts

@@ -0,0 +1,209 @@
+import type { XaiSubscriptionAccountMetadata } from "@opengeni/db";
+import { requireAccessGrant, type ApiRouteDeps } from "@opengeni/core";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import {
+  SubscriptionAccountRenameRequest,
+  SubscriptionAccountToggleRequest,
+  SubscriptionRotationSettingsRequest,
+} from "@opengeni/contracts";
+import { requireOrganizationCodexHuman } from "./codex";
+import { requireSameOriginBrowserMutation } from "./subscription-pool-access";
+import {
+  coreOrganizationAccount,
+  coreOrganizationAccounts,
+  coreOrganizationSettings,
+  coreWorkspaceAccounts,
+  coreWorkspaceActivate,
+  coreWorkspaceAllocator,
+  coreWorkspaceDisconnect,
+  coreWorkspaceRename,
+  coreWorkspaceSettings,
+  requireSubscriptionCoreRoute,
+  type SubscriptionPoolCore,
+} from "./subscription-pool-core";
+const allocatorBody = SubscriptionAccountToggleRequest;
+const settingsBody = SubscriptionRotationSettingsRequest;
+const renameBody = SubscriptionAccountRenameRequest;
+
+/** The legacy pool repository; only Claude still has one (until its own cutover). */
+
+/** The legacy pool account shape SuperGrok and Claude share (SuperGrok's metadata defines it). */
+export type SubscriptionPoolAccount = XaiSubscriptionAccountMetadata;
+/**
+ * The repository of a provider whose legacy runtime was deleted after its
+ * cutover: its routes serve only the core (`requireSubscriptionCoreRoute`
+ * refuses any other route first), so no legacy handler can reach these.
+ */
+
+/** Account CRUD uses one authority, allocator and wake contract for every pool. */
+export function registerSubscriptionAccountPoolRoutes(
+  app: Hono,
+  deps: ApiRouteDeps,
+  options: {
+    provider: "xai" | "claude";
+    route: "supergrok" | "claude";
+    displayName: "SuperGrok" | "Claude";
+    enabled: () => boolean;
+    accountJson: (
+      account: XaiSubscriptionAccountMetadata,
+      activeId: string | null,
+    ) => Record<string, unknown>;
+    core: SubscriptionPoolCore;
+  },
+) {
+  const core = options.core;
+  const coreContext = {
+    deps,
+    core,
+    displayName: options.displayName,
+    accountJson: options.accountJson,
+    listedAccountJson: core.listedAccountJson ?? options.accountJson,
+  };
+  /**
+   * The pool's runtime for this organization: `legacy` without a core
+   * binding; a core-only pool (no legacy repository) serves only `core`.
+   */
+  const route = (accountId: () => Promise<string>) =>
+    requireSubscriptionCoreRoute(deps, options.provider, options.displayName, accountId);
+  const workspaceRoute = (c: Context, workspaceId: string) =>
+    route(async () => (await requireAccessGrant(c, deps, workspaceId, "workspace:read")).accountId);
+  const workspacePath = `/v1/workspaces/:workspaceId/${options.route}`;
+  const organizationPath = `/v1/organizations/:organizationId/${options.route}`;
+  const requireEnabled = () => {
+    if (!options.enabled())
+      throw new HTTPException(404, {
+        message: options.displayName + " subscriptions are not enabled",
+      });
+  };
+  const organizationActor = async (c: Context, mutation = false) => {
+    requireEnabled();
+    if (mutation) requireSameOriginBrowserMutation(c, deps);
+    const organizationId = c.req.param("organizationId")!;
+    const human = await requireOrganizationCodexHuman(c, deps, organizationId);
+    return { organizationId, actorSubjectId: human.subjectId };
+  };
+
+  app.get(`${organizationPath}/accounts`, async (c) => {
+    const actor = await organizationActor(c);
+    await route(async () => actor.organizationId);
+    return await coreOrganizationAccounts(c, coreContext!, actor);
+  });
+  app.patch(`${organizationPath}/settings`, async (c) => {
+    const actor = await organizationActor(c, true);
+    const parsed = settingsBody.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) throw new HTTPException(400, { message: "rotationEnabled is required" });
+    await route(async () => actor.organizationId);
+    return await coreOrganizationSettings(c, coreContext!, actor, parsed.data.rotationEnabled);
+  });
+  const updateOrganizationAccount = async (
+    c: Context,
+    changes: {
+      activate?: boolean;
+      disconnect?: boolean;
+      label?: string | null;
+      allocatorEnabled?: boolean;
+      expectedAllocatorVersion?: number;
+    },
+  ) => {
+    const actor = await organizationActor(c, true);
+    await route(async () => actor.organizationId);
+    return await coreOrganizationAccount(
+      c,
+      coreContext!,
+      actor,
+      c.req.param("accountId")!,
+      changes.activate
+        ? { activate: true }
+        : changes.disconnect
+          ? { disconnect: true }
+          : changes.label !== undefined
+            ? { label: changes.label }
+            : {
+                allocatorEnabled: changes.allocatorEnabled!,
+                expectedAllocatorVersion: changes.expectedAllocatorVersion!,
+              },
+    );
+  };
+  app.post(`${organizationPath}/accounts/:accountId/activate`, (c) =>
+    updateOrganizationAccount(c, { activate: true }),
+  );
+  app.delete(`${organizationPath}/accounts/:accountId`, (c) =>
+    updateOrganizationAccount(c, { disconnect: true }),
+  );
+  app.patch(`${organizationPath}/accounts/:accountId`, async (c) => {
+    const parsed = renameBody.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) throw new HTTPException(400, { message: "label is invalid" });
+    return updateOrganizationAccount(c, { label: parsed.data.label || null });
+  });
+  app.patch(`${organizationPath}/accounts/:accountId/allocator`, async (c) => {
+    const parsed = allocatorBody.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success)
+      throw new HTTPException(400, { message: "enabled and expectedVersion are required" });
+    return updateOrganizationAccount(c, {
+      allocatorEnabled: parsed.data.enabled,
+      expectedAllocatorVersion: parsed.data.expectedVersion,
+    });
+  });
+
+  app.get(`${workspacePath}/accounts`, async (c) => {
+    requireEnabled();
+    const workspaceId = c.req.param("workspaceId")!;
+    await workspaceRoute(c, workspaceId);
+    return await coreWorkspaceAccounts(c, coreContext!, workspaceId);
+  });
+
+  app.post(`${workspacePath}/accounts/:accountId/activate`, async (c) => {
+    requireEnabled();
+    const workspaceId = c.req.param("workspaceId")!;
+    const credentialId = c.req.param("accountId")!;
+    await workspaceRoute(c, workspaceId);
+    return await coreWorkspaceActivate(c, coreContext!, workspaceId, credentialId);
+  });
+
+  app.patch(`${workspacePath}/settings`, async (c) => {
+    requireEnabled();
+    const workspaceId = c.req.param("workspaceId")!;
+    const parsed = settingsBody.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) throw new HTTPException(400, { message: "rotationEnabled is required" });
+    await workspaceRoute(c, workspaceId);
+    return await coreWorkspaceSettings(c, coreContext!, workspaceId, parsed.data.rotationEnabled);
+  });
+
+  app.patch(`${workspacePath}/accounts/:accountId/allocator`, async (c) => {
+    requireEnabled();
+    const workspaceId = c.req.param("workspaceId")!;
+    const credentialId = c.req.param("accountId")!;
+    await workspaceRoute(c, workspaceId);
+
+    const parsed = allocatorBody.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success)
+      throw new HTTPException(400, { message: "enabled and expectedVersion are required" });
+    return await coreWorkspaceAllocator(c, coreContext!, workspaceId, credentialId, parsed.data);
+  });
+
+  app.patch(`${workspacePath}/accounts/:accountId`, async (c) => {
+    requireEnabled();
+    const workspaceId = c.req.param("workspaceId")!;
+    const credentialId = c.req.param("accountId")!;
+    await workspaceRoute(c, workspaceId);
+
+    const parsed = renameBody.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) throw new HTTPException(400, { message: "label is invalid" });
+    return await coreWorkspaceRename(
+      c,
+      coreContext!,
+      workspaceId,
+      credentialId,
+      parsed.data.label || null,
+    );
+  });
+
+  app.delete(`${workspacePath}/accounts/:accountId`, async (c) => {
+    requireEnabled();
+    const workspaceId = c.req.param("workspaceId")!;
+    const credentialId = c.req.param("accountId")!;
+    await workspaceRoute(c, workspaceId);
+    return await coreWorkspaceDisconnect(c, coreContext!, workspaceId, credentialId);
+  });
+}

package/src/routes/subscription-core-http.ts

@@ -0,0 +1,18 @@
+// The typed HTTP answers every provider's routes on the shared subscription
+// core use (design docs/design/subscription-core-2026-10-07.md, 5.3).
+// Provider-neutral.
+import { ApiHttpError } from "../http/api-error";
+
+/** `details.reason` of the 503 a provider's route answers while its cutover row is missing or disabled. */
+export const SUBSCRIPTION_CORE_CUTOVER_DISABLED = "subscription_core_cutover_disabled";
+
+/** The public error envelope with the core reason in `details.reason`. */
+export function typedHttpError(status: 409 | 503, reason: string, message: string): ApiHttpError {
+  return new ApiHttpError(status, {
+    code: status === 503 ? "upstream_unavailable" : "conflict",
+    message,
+    retryable: status === 503,
+    outcomeUnknown: false,
+    details: { reason },
+  });
+}

package/src/routes/subscription-pool-access.ts

@@ -0,0 +1,180 @@
+import { getWorkspaceGrant, resolveNamedManagedPersonalWorkspaceGrant } from "@opengeni/db";
+import {
+  getManagedSession,
+  requireAccessGrant,
+  requireAccessGrantAuthorization,
+  externalActorContinuationForAuthorization,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import type { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { agentActingAsPersonBeforeGrantCheck, isAgentActingAsPerson } from "../http/acting-person";
+type ManagedCookieHuman = { subjectId: string };
+
+/**
+ * Where a private (scope `user`) subscription is managed. The legacy pools
+ * keep a person's private accounts in an ordinary workspace they are a member
+ * of; the shared subscription core keeps a personal connection only in its
+ * owner's own Personal workspace (D-03), so on the core the private routes
+ * answer there and nowhere else.
+ */
+export type PrivateSubscriptionPlace = "ordinary_workspace" | "personal_workspace";
+
+async function requirePrivateSubscriptionPlace(
+  deps: ApiRouteDeps,
+  place: PrivateSubscriptionPlace,
+  input: { accountId: string; workspaceId: string; subjectId: string },
+  displayName: string,
+): Promise<void> {
+  if (place === "personal_workspace") {
+    // The subject's current Personal workspace pointer with a live
+    // organization membership; another person's Personal workspace or a
+    // shared workspace never qualifies.
+    if (!(await resolveNamedManagedPersonalWorkspaceGrant(deps.db, input)))
+      throw new HTTPException(409, {
+        message: `Private ${displayName} accounts are connected and managed from your Personal workspace`,
+      });
+    return;
+  }
+  // The shared user-pool domain requires an ordinary workspace membership,
+  // not just the synthetic Personal-workspace owner grant.
+  if (!(await getWorkspaceGrant(deps.db, input.subjectId, input.workspaceId)))
+    throw new HTTPException(409, {
+      message: `Private ${displayName} accounts require membership in an ordinary workspace`,
+    });
+}
+
+export async function managedCookieHuman(
+  c: Context,
+  deps: ApiRouteDeps,
+): Promise<ManagedCookieHuman | null> {
+  if (
+    deps.settings.productAccessMode !== "managed" ||
+    !deps.managedAuth ||
+    !c.req.header("cookie") ||
+    c.req.header("authorization")
+  ) {
+    return null;
+  }
+  const session = await getManagedSession(c, deps.managedAuth, {
+    db: deps.db,
+    sessionAdapter: deps.managedAuthSessionAdapter,
+    sessionSetMode: deps.settings.managedAuthSessionSetMode,
+  });
+  return session?.user?.id ? { subjectId: `user:${session.user.id}` } : null;
+}
+
+export function requireSameOriginBrowserMutation(c: Context, deps: ApiRouteDeps): void {
+  // Built in process for an agent acting as a person: no browser credentials
+  // ride along, so there is no cross-site request to guard against.
+  if (isAgentActingAsPerson(c)) return;
+  const contentType = c.req.header("content-type")?.split(";", 1)[0]?.trim().toLowerCase();
+  if (contentType !== "application/json") {
+    throw new HTTPException(403, { message: "JSON browser request required" });
+  }
+  if (!deps.settings.publicBaseUrl) {
+    throw new HTTPException(503, {
+      message: "managed browser origin is not configured",
+    });
+  }
+  const expectedOrigin = new URL(deps.settings.publicBaseUrl).origin;
+  if (c.req.header("origin") !== expectedOrigin) {
+    throw new HTTPException(403, {
+      message: "same-origin browser request required",
+    });
+  }
+  if (c.req.header("sec-fetch-site")?.toLowerCase() !== "same-origin") {
+    throw new HTTPException(403, {
+      message: "same-origin fetch metadata required",
+    });
+  }
+}
+
+export async function requirePrivateSubscriptionHuman(
+  c: Context,
+  deps: ApiRouteDeps,
+  workspaceId: string,
+  displayName: string,
+  place: PrivateSubscriptionPlace = "ordinary_workspace",
+): Promise<{ accountId: string; subjectId: string }> {
+  if (c.req.header("authorization")) {
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "connections:write",
+    );
+    const external = externalActorContinuationForAuthorization(authorization);
+    if (
+      external &&
+      authorization.contextIntegrity &&
+      external.actor.effectiveSubjectId === authorization.grant.subjectId
+    ) {
+      const owner = {
+        accountId: authorization.grant.accountId,
+        subjectId: authorization.grant.subjectId,
+      };
+      await requirePrivateSubscriptionPlace(deps, place, { ...owner, workspaceId }, displayName);
+      return owner;
+    }
+    throw new HTTPException(403, {
+      message: `Private ${displayName} accounts require a verified owning user`,
+    });
+  }
+  const human = (await managedCookieHuman(c, deps)) ?? agentActingAsPersonBeforeGrantCheck(c);
+  if (!human) {
+    throw new HTTPException(401, {
+      message: "managed browser session required",
+    });
+  }
+  const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
+  if (grant.subjectId !== human.subjectId) {
+    throw new HTTPException(403, {
+      message: "managed browser identity mismatch",
+    });
+  }
+  const owner = { accountId: grant.accountId, subjectId: grant.subjectId };
+  await requirePrivateSubscriptionPlace(deps, place, { ...owner, workspaceId }, displayName);
+  return owner;
+}
+
+export async function requireSubscriptionScopeMutation(
+  c: Context,
+  deps: ApiRouteDeps,
+  workspaceId: string,
+  scope: "workspace" | "user" | "organization",
+  displayName: string,
+  place: PrivateSubscriptionPlace = "ordinary_workspace",
+): Promise<{ accountId: string; subjectId: string }> {
+  if (scope === "organization")
+    throw new HTTPException(409, { message: "Manage this subscription in organization settings" });
+  if (scope === "user") {
+    // Server-side external-user assertions do not use browser cookies. Ordinary
+    // bearers remain rejected by requirePrivateHuman; native CSRF is unchanged.
+    if (!c.req.header("authorization")) requireSameOriginBrowserMutation(c, deps);
+    return await requirePrivateSubscriptionHuman(c, deps, workspaceId, displayName, place);
+  }
+  const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+  return { accountId: grant.accountId, subjectId: grant.subjectId };
+}
+
+/**
+ * The mutation gate of a pool whose legacy repository is deleted (Claude,
+ * C4). The account's scope can no longer be read, so every caller gets the
+ * workspace-scope gate of `requireSubscriptionScopeMutation` (a browser
+ * request must be same-origin, and the caller needs `workspace:admin`)
+ * before the route fails closed; nothing is read or written either way.
+ * For a former private (user-scope) account this changes two outcomes: an
+ * ordinary bearer with `workspace:admin` now reaches the 503 where it got
+ * 403 (no verified owning user), and the owner without `workspace:admin` now
+ * gets 403 where it passed. C2b restores the per-scope check, including the
+ * owner's path, when the core serves these routes.
+ */
+export async function requireDeletedSubscriptionPoolMutation(
+  c: Context,
+  deps: ApiRouteDeps,
+  workspaceId: string,
+): Promise<void> {
+  if (!c.req.header("authorization")) requireSameOriginBrowserMutation(c, deps);
+  await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+}