@opengeni/api-router 3.0.1 → 3.1.2

package/src/routes/model-account-settings.ts

@@ -0,0 +1,235 @@
+import {
+  ModelAccountSettingsOverview,
+  OrganizationModelAccountSettings,
+  UpdateOrganizationModelAccountSettingsRequest,
+  UpdateWorkspaceModelAccountSettingsRequest,
+  WorkspaceModelAccountSettings,
+} from "@opengeni/contracts";
+import { requireAccessGrant, type ApiRouteDeps } from "@opengeni/core";
+import {
+  deliverSubscriptionCoreCodexWake,
+  readOrganizationSubscriptionSettings,
+  readSubscriptionSettingsOverview,
+  readWorkspaceSubscriptionSettings,
+  SubscriptionSettingsBusyError,
+  SubscriptionSettingsForbiddenError,
+  SubscriptionSettingsInvalidError,
+  SubscriptionSettingsLockedError,
+  subscriptionSettingLockRefusal,
+  SubscriptionSettingsPersonalWorkspaceError,
+  SubscriptionSettingsVersionConflictError,
+  updateOrganizationSubscriptionSettings,
+  updateWorkspaceSubscriptionSettings,
+  type SubscriptionSettingsWake,
+} from "@opengeni/db";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+
+import { ApiHttpError } from "../http/api-error";
+import { requireOrganizationCodexHuman, requireSameOriginBrowserMutation } from "./codex";
+
+const Uuid = z.string().uuid();
+
+function parseId(value: string | undefined, what: "organization" | "workspace"): string {
+  const parsed = Uuid.safeParse(value);
+  if (!parsed.success) throw new HTTPException(404, { message: `${what} not found` });
+  return parsed.data;
+}
+
+/**
+ * 409 `setting_locked` for any write the organization's settings lock refused:
+ * these routes and every older route whose write meets the 0724 guard (for
+ * example a Codex rotation, primary or source change). Mapped centrally in
+ * the app error handler.
+ */
+export function subscriptionSettingsLockedHttpError(error: unknown): ApiHttpError | null {
+  const settings =
+    error instanceof SubscriptionSettingsLockedError
+      ? [...error.settings]
+      : subscriptionSettingLockRefusal(error);
+  if (settings === null) return null;
+  return new ApiHttpError(409, {
+    code: "conflict",
+    message: "the organization locked this setting",
+    retryable: false,
+    outcomeUnknown: false,
+    details: { reason: "setting_locked", settings },
+  });
+}
+
+/** Typed refusals to HTTP: 403, 409 (locked, Personal workspace, version), 422 or 503 (busy). */
+function refused(error: unknown): never {
+  if (error instanceof SubscriptionSettingsForbiddenError) {
+    throw new HTTPException(403, { message: error.message });
+  }
+  const locked = subscriptionSettingsLockedHttpError(error);
+  if (locked) throw locked;
+  if (error instanceof SubscriptionSettingsPersonalWorkspaceError) {
+    throw new ApiHttpError(409, {
+      code: "conflict",
+      message: error.message,
+      retryable: false,
+      outcomeUnknown: false,
+      details: { reason: "personal_workspace" },
+    });
+  }
+  if (error instanceof SubscriptionSettingsVersionConflictError) {
+    throw new ApiHttpError(409, {
+      code: "conflict",
+      message: error.message,
+      retryable: false,
+      outcomeUnknown: false,
+      details: { reason: "version_conflict", currentVersion: error.currentVersion },
+    });
+  }
+  if (error instanceof SubscriptionSettingsInvalidError) {
+    throw new HTTPException(422, { message: error.message });
+  }
+  if (error instanceof SubscriptionSettingsBusyError) {
+    // A lock change kept yielding to workspace writes; nothing was written.
+    throw new ApiHttpError(503, {
+      code: "upstream_unavailable",
+      message: error.message,
+      retryable: true,
+      outcomeUnknown: false,
+      details: { reason: "settings_busy" },
+    });
+  }
+  throw error;
+}
+
+async function wake(deps: ApiRouteDeps, value: SubscriptionSettingsWake | null): Promise<void> {
+  // Capacity waiters recheck on their own bounded timer; a lost wake only delays.
+  await deliverSubscriptionCoreCodexWake(deps.db, value).catch(() => undefined);
+}
+
+async function jsonBody(c: Context): Promise<unknown> {
+  return await c.req.json().catch(() => null);
+}
+
+/**
+ * Model-account settings (SUB-SET-01..05). Organization owners and admins
+ * read and change the organization's values and locks and read the overview
+ * of every shared workspace. Workspace members read their workspace's
+ * effective values; its administrators (and organization administrators)
+ * override what the organization has not locked. The database enforces
+ * every refusal; these routes only translate it.
+ */
+export function registerModelAccountSettingsRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const organizationPath = "/v1/organizations/:organizationId/model-account-settings";
+
+  app.get(organizationPath, async (c) => {
+    c.header("cache-control", "private, no-store");
+    const organizationId = parseId(c.req.param("organizationId"), "organization");
+    const human = await requireOrganizationCodexHuman(c, deps, organizationId);
+    try {
+      return c.json(
+        OrganizationModelAccountSettings.parse(
+          await readOrganizationSubscriptionSettings(deps.db, {
+            organizationId,
+            actorSubjectId: human.subjectId,
+          }),
+        ),
+      );
+    } catch (error) {
+      refused(error);
+    }
+  });
+
+  app.patch(organizationPath, async (c) => {
+    requireSameOriginBrowserMutation(c, deps);
+    const organizationId = parseId(c.req.param("organizationId"), "organization");
+    const human = await requireOrganizationCodexHuman(c, deps, organizationId);
+    const parsed = UpdateOrganizationModelAccountSettingsRequest.safeParse(await jsonBody(c));
+    if (!parsed.success) {
+      throw new HTTPException(422, { message: "invalid model account settings" });
+    }
+    const { expectedVersion, ...patch } = parsed.data;
+    try {
+      const result = await updateOrganizationSubscriptionSettings(deps.db, {
+        organizationId,
+        actorSubjectId: human.subjectId,
+        patch,
+        ...(expectedVersion === undefined ? {} : { expectedVersion }),
+      });
+      await wake(deps, result.wake);
+      return c.json(OrganizationModelAccountSettings.parse(result.settings));
+    } catch (error) {
+      refused(error);
+    }
+  });
+
+  app.get(`${organizationPath}/overview`, async (c) => {
+    c.header("cache-control", "private, no-store");
+    const organizationId = parseId(c.req.param("organizationId"), "organization");
+    const human = await requireOrganizationCodexHuman(c, deps, organizationId);
+    const after = c.req.query("after");
+    if (after !== undefined && !Uuid.safeParse(after).success) {
+      throw new HTTPException(422, { message: "invalid cursor" });
+    }
+    const limitText = c.req.query("limit");
+    const limit = limitText === undefined ? undefined : Number(limitText);
+    if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 500)) {
+      throw new HTTPException(422, { message: "limit must be between 1 and 500" });
+    }
+    try {
+      return c.json(
+        ModelAccountSettingsOverview.parse(
+          await readSubscriptionSettingsOverview(deps.db, {
+            organizationId,
+            actorSubjectId: human.subjectId,
+            after: after ?? null,
+            ...(limit === undefined ? {} : { limit }),
+          }),
+        ),
+      );
+    } catch (error) {
+      refused(error);
+    }
+  });
+
+  const workspacePath = "/v1/workspaces/:workspaceId/model-account-settings";
+
+  app.get(workspacePath, async (c) => {
+    c.header("cache-control", "private, no-store");
+    const workspaceId = parseId(c.req.param("workspaceId"), "workspace");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    try {
+      return c.json(
+        WorkspaceModelAccountSettings.parse(
+          await readWorkspaceSubscriptionSettings(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            subjectId: grant.subjectId,
+          }),
+        ),
+      );
+    } catch (error) {
+      refused(error);
+    }
+  });
+
+  app.patch(workspacePath, async (c) => {
+    const workspaceId = parseId(c.req.param("workspaceId"), "workspace");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const parsed = UpdateWorkspaceModelAccountSettingsRequest.safeParse(await jsonBody(c));
+    if (!parsed.success) {
+      throw new HTTPException(422, { message: "invalid model account settings" });
+    }
+    const { expectedVersion, ...patch } = parsed.data;
+    try {
+      const result = await updateWorkspaceSubscriptionSettings(deps.db, {
+        accountId: grant.accountId,
+        workspaceId,
+        subjectId: grant.subjectId,
+        patch,
+        ...(expectedVersion === undefined ? {} : { expectedVersion }),
+      });
+      await wake(deps, result.wake);
+      return c.json(WorkspaceModelAccountSettings.parse(result.settings));
+    } catch (error) {
+      refused(error);
+    }
+  });
+}

package/src/routes/model-connection-access.ts

@@ -1,9 +1,11 @@
+import { claudeProviderId, withClaudeConnectionCatalog } from "@opengeni/config";
 import {
   configuredModels,
   withCodexCatalogProvider,
   withXaiSubscriptionCatalogProvider,
   withOrganizationGatewayCatalogProvider,
   withOrganizationOpenRouterCatalogProvider,
+  withOrganizationOpperCatalogProvider,
 } from "@opengeni/config";
 import { ModelConnectionAccessPolicy, ModelConnectionAccessResponse } from "@opengeni/contracts";
 import {
@@ -12,87 +14,153 @@ import {
   type ApiRouteDeps,
 } from "@opengeni/core";
 import {
+  deliverSubscriptionCoreWake,
   getModelConnectionAccess,
+  listOrganizationAdministrationMembers,
+  nestedPostgresSqlState,
+  readSubscriptionCoreProviderModelConnectionAccess,
+  subscriptionCoreAccessChangeWake,
+  ModelConnectionAccessForbiddenError,
+  SubscriptionCoreAccessInvalidError,
+  SubscriptionCoreAccessPeopleUnlistableError,
+  SubscriptionCoreAccessPersonNotInOrganizationError,
+  ModelConnectionWorkspaceNotInOrganizationError,
   updateModelConnectionAccess,
+  updateSubscriptionCoreProviderModelConnectionAccess,
   getOrganizationAdministrationOverview,
-  getXaiSubscriptionAccountAuthoritySnapshot,
   listOrganizationModelProviderCustomModels,
-  getWorkspaceVercelAiGatewayConnectionMetadata,
-  getWorkspaceOpenRouterConnectionMetadata,
+  getWorkspaceProviderApiKeyConnectionMetadata,
   type ModelConnectionTarget,
 } from "@opengeni/db";
 import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import { z } from "zod";
 import { requireOrganizationCodexHuman, requireSameOriginBrowserMutation } from "./codex";
-import { managedCookieHuman, requireScopeMutation } from "./supergrok";
+import { codexRouteDisposition } from "./codex-core";
+import { requireSubscriptionCoreRoute } from "./subscription-pool-core";
 
-const Kind = z.enum(["codex", "supergrok", "vercel_gateway", "openrouter"]);
+const Kind = z.enum([
+  "codex",
+  "supergrok",
+  "vercel_gateway",
+  "openrouter",
+  "anthropic",
+  "claude_subscription",
+  "opper",
+]);
 function modelPrefix(target: ModelConnectionTarget) {
+  if (target.kind === "anthropic" || target.kind === "claude_subscription")
+    return (
+      claudeProviderId(target.kind, target.workspaceId === null ? "organization" : "workspace") +
+      "/"
+    );
   if (target.kind === "codex" || target.kind === "supergrok") return `${target.kind}/`;
-  return `${target.workspaceId === null ? "organization" : "workspace"}-${target.kind === "vercel_gateway" ? "gateway" : "openrouter"}/`;
+  return `${target.workspaceId === null ? "organization" : "workspace"}-${target.kind === "vercel_gateway" ? "gateway" : target.kind === "opper" ? "opper" : "openrouter"}/`;
+}
+
+/**
+ * Codex access policies follow the organization's Codex cutover row (M3 PR
+ * 3): the legacy credential row without one; the shared core connection with
+ * an enabled one (the legacy rows are frozen after 0680); a disabled row is
+ * maintenance (typed 503 from `codexRouteDisposition`). SuperGrok's follow
+ * its provider route (design 5.3, X2b): legacy without the `xai` cutover
+ * receipt, the shared core connection with it, maintenance fails closed.
+ */
+async function coreAccessDisposition(
+  deps: ApiRouteDeps,
+  kind: ModelConnectionTarget["kind"],
+  accountId: string,
+): Promise<"legacy" | "core"> {
+  if (kind === "codex") return await codexRouteDisposition(deps, accountId);
+  // SuperGrok runs only on the core: any other route fails closed.
+  if (kind === "supergrok")
+    return await requireSubscriptionCoreRoute(deps, "xai", "SuperGrok", async () => accountId);
+  if (kind === "claude_subscription")
+    return await requireSubscriptionCoreRoute(deps, "claude", "Claude", async () => accountId);
+  return "legacy";
 }
 
 export function registerModelConnectionAccessRoutes(app: Hono, deps: ApiRouteDeps) {
   for (const scope of ["organizations", "workspaces"] as const) {
     const path = `/v1/${scope}/:scopeId/model-connections/:kind/:connectionId/access`;
-    async function target(c: Context, mutate: boolean): Promise<ModelConnectionTarget> {
+    async function target(
+      c: Context,
+      mutate: boolean,
+    ): Promise<{ connection: ModelConnectionTarget; core: boolean }> {
       const kind = Kind.parse(c.req.param("kind"));
+      if (kind === "claude_subscription" && !deps.settings.claudeSubscriptionEnabled)
+        throw new HTTPException(404, { message: "Claude subscriptions are not enabled" });
       const scopeId = z.string().uuid().parse(c.req.param("scopeId"));
       let connectionId = c.req.param("connectionId")!;
-      if (kind === "codex" || kind === "supergrok")
+      if (kind === "codex" || kind === "supergrok" || kind === "claude_subscription")
         connectionId = z.string().uuid().parse(connectionId);
       if (scope === "organizations") {
         if (mutate) requireSameOriginBrowserMutation(c, deps);
         const human = await requireOrganizationCodexHuman(c, deps, scopeId);
         return {
-          kind,
-          connectionId,
-          accountId: scopeId,
-          workspaceId: null,
-          subjectId: human.subjectId,
+          connection: {
+            kind,
+            connectionId,
+            accountId: scopeId,
+            workspaceId: null,
+            subjectId: human.subjectId,
+          },
+          core: (await coreAccessDisposition(deps, kind, scopeId)) === "core",
         };
       }
       const grant = await requireAccessGrant(c, deps, scopeId, "workspace:read");
-      if (kind === "supergrok") {
-        const snapshot = await getXaiSubscriptionAccountAuthoritySnapshot(deps.db, {
-          workspaceId: scopeId,
-          subjectId: grant.subjectId,
-          credentialId: connectionId,
-        });
-        if (!snapshot) throw new HTTPException(404, { message: "Subscription not found" });
-        if (snapshot.scope === "user") {
-          const human = await managedCookieHuman(c, deps);
-          if (!human || human.subjectId !== grant.subjectId)
-            throw new HTTPException(403, {
-              message: "Subscription owner browser session required",
-            });
-        }
-        if (mutate) await requireScopeMutation(c, deps, scopeId, snapshot.scope);
-      } else if (mutate) await requireAccessGrant(c, deps, scopeId, "workspace:admin");
-      if (kind === "vercel_gateway" || kind === "openrouter") {
-        const metadata = await (
-          kind === "vercel_gateway"
-            ? getWorkspaceVercelAiGatewayConnectionMetadata
-            : getWorkspaceOpenRouterConnectionMetadata
-        )(deps.db, scopeId);
+      // On the core a SuperGrok or Claude access policy is a shared connection's, which
+      // the core editor authorizes; only the legacy pools have private rows.
+      const sharedCore =
+        (kind === "supergrok" || kind === "claude_subscription") &&
+        (await coreAccessDisposition(deps, kind, grant.accountId)) === "core";
+      if (mutate) {
+        // A core Claude change keeps the legacy same-origin browser check.
+        if (kind === "claude_subscription" && !c.req.header("authorization"))
+          requireSameOriginBrowserMutation(c, deps);
+        await requireAccessGrant(c, deps, scopeId, "workspace:admin");
+      }
+      if (
+        kind === "vercel_gateway" ||
+        kind === "openrouter" ||
+        kind === "anthropic" ||
+        kind === "opper"
+      ) {
+        const metadata = await getWorkspaceProviderApiKeyConnectionMetadata(deps.db, scopeId, kind);
         if (!metadata || (connectionId !== "current" && metadata.connectionId !== connectionId))
           throw new HTTPException(404, { message: "Connection not found" });
         connectionId = metadata.connectionId;
       }
       return {
-        kind,
-        connectionId,
-        accountId: grant.accountId,
-        workspaceId: scopeId,
-        subjectId: grant.subjectId,
+        connection: {
+          kind,
+          connectionId,
+          accountId: grant.accountId,
+          workspaceId: scopeId,
+          subjectId: grant.subjectId,
+        },
+        core:
+          kind === "supergrok" || kind === "claude_subscription"
+            ? sharedCore
+            : (await coreAccessDisposition(deps, kind, grant.accountId)) === "core",
       };
     }
     app.get(path, async (c) => {
       c.header("cache-control", "private, no-store");
-      const connection = await target(c, false);
-      const policy = await getModelConnectionAccess(deps.db, connection);
+      const { connection, core } = await target(c, false);
+      const coreAccess = core
+        ? await readSubscriptionCoreProviderModelConnectionAccess(deps.db, connection)
+        : null;
+      const policy = core
+        ? coreAccess && {
+            ...coreAccess.policy,
+            allowedPeople: coreAccess.policy.allowedPeople ?? undefined,
+          }
+        : await getModelConnectionAccess(deps.db, connection);
       if (!policy) throw new HTTPException(404, { message: "Connection not found" });
+      // Shared core connections at organization scope can be limited to people
+      // and report the workspaces that use them as their own (design 5.4).
+      const organizationCore = coreAccess !== null && connection.workspaceId === null;
       let settings =
         connection.workspaceId === null
           ? (await deps.resolveCatalogSettings()).settings
@@ -112,7 +180,21 @@ export function registerModelConnectionAccessRoutes(app: Hono, deps: ApiRouteDep
         workspaces = (await getOrganizationAdministrationOverview(deps.db, actor)).workspaces.map(
           ({ id, name }) => ({ id, name }),
         );
-        if (connection.kind === "vercel_gateway" || connection.kind === "openrouter") {
+        if (connection.kind === "anthropic" || connection.kind === "claude_subscription") {
+          const customModels = await listOrganizationModelProviderCustomModels(deps.db, {
+            organizationId: connection.accountId,
+            actorSubjectId: connection.subjectId,
+            providerKind: connection.kind,
+          });
+          settings = withClaudeConnectionCatalog(settings, {
+            [connection.kind]: { models: customModels },
+          });
+        }
+        if (
+          connection.kind === "vercel_gateway" ||
+          connection.kind === "openrouter" ||
+          connection.kind === "opper"
+        ) {
           const models = await listOrganizationModelProviderCustomModels(deps.db, {
             ...actor,
             providerKind: connection.kind,
@@ -120,9 +202,37 @@ export function registerModelConnectionAccessRoutes(app: Hono, deps: ApiRouteDep
           settings =
             connection.kind === "vercel_gateway"
               ? withOrganizationGatewayCatalogProvider(settings, models)
-              : withOrganizationOpenRouterCatalogProvider(settings, models);
+              : connection.kind === "opper"
+                ? withOrganizationOpperCatalogProvider(settings, models)
+                : withOrganizationOpenRouterCatalogProvider(settings, models);
         }
       }
+      // The people an administrator can choose, or null when the account
+      // can't be limited to people or the organization has more members than
+      // its member list shows (people are then not offered).
+      const people =
+        organizationCore && coreAccess?.peopleSupported
+          ? await listOrganizationAdministrationMembers(deps.db, {
+              organizationId: connection.accountId,
+              actorSubjectId: connection.subjectId,
+            }).then(
+              (members) =>
+                members
+                  .filter(
+                    (member) =>
+                      member.status === "active" &&
+                      member.revokedAt === null &&
+                      member.subjectId.startsWith("user:"),
+                  )
+                  .map(({ id, name, email }) => ({ id, name, email })),
+              (error: unknown) => {
+                // The member list refuses organizations above its bound
+                // (SQLSTATE 54000); people are then not offered.
+                if (nestedPostgresSqlState(error) === "54000") return null;
+                throw error;
+              },
+            )
+          : null;
       return c.json(
         ModelConnectionAccessResponse.parse({
           policy,
@@ -132,29 +242,81 @@ export function registerModelConnectionAccessRoutes(app: Hono, deps: ApiRouteDep
             .map(({ id, label }) => ({ id, label })),
           personalWorkspacesSupported:
             connection.workspaceId === null &&
-            (connection.kind === "codex" || connection.kind === "supergrok"),
+            (connection.kind === "codex" ||
+              connection.kind === "supergrok" ||
+              connection.kind === "claude_subscription"),
+          ...(organizationCore
+            ? {
+                ...(people ? { peopleSupported: true, people } : { peopleSupported: false }),
+                localWorkspaceIds: coreAccess.localWorkspaceIds,
+                managedByWorkspaceId: coreAccess.managedByWorkspaceId,
+                ...(coreAccess.personalSharingSupported ? { personalSharingSupported: true } : {}),
+              }
+            : {}),
         }),
       );
     });
     app.put(path, async (c) => {
-      const connection = await target(c, true);
+      // Access of a provider on the shared core lives there; the frozen legacy row is never written.
+      const { connection, core } = await target(c, true);
       const parsed = ModelConnectionAccessPolicy.safeParse(await c.req.json().catch(() => null));
       if (!parsed.success)
         throw new HTTPException(422, { message: "Invalid connection access policy" });
       const policy = parsed.data;
+      if (policy.sharePersonal && (!core || connection.workspaceId !== null))
+        throw new HTTPException(422, {
+          message: "Personal sharing requires the organization subscription route",
+        });
       if (policy.allowedModels?.some((id) => !id.startsWith(modelPrefix(connection))))
         throw new HTTPException(422, {
           message: "Model belongs to a different connection provider",
         });
-      if (connection.workspaceId !== null && policy.allowedWorkspaces !== null)
+      if (
+        connection.workspaceId !== null &&
+        (policy.allowedWorkspaces !== null || policy.allowedPeople != null)
+      )
         throw new HTTPException(422, {
           message: "Workspace connections cannot be assigned to other workspaces",
         });
-      const updated = await updateModelConnectionAccess(deps.db, connection, policy);
+      if (!core && policy.allowedPeople != null)
+        throw new HTTPException(422, { message: "This account cannot be limited to people" });
+      let updated;
+      try {
+        updated = core
+          ? await updateSubscriptionCoreProviderModelConnectionAccess(deps.db, connection, policy)
+          : await updateModelConnectionAccess(deps.db, connection, policy);
+      } catch (error) {
+        if (error instanceof ModelConnectionWorkspaceNotInOrganizationError)
+          throw new HTTPException(422, { message: error.message });
+        if (
+          error instanceof SubscriptionCoreAccessPersonNotInOrganizationError ||
+          error instanceof SubscriptionCoreAccessPeopleUnlistableError ||
+          error instanceof SubscriptionCoreAccessInvalidError
+        )
+          throw new HTTPException(422, { message: error.message });
+        if (error instanceof ModelConnectionAccessForbiddenError)
+          throw new HTTPException(403, { message: error.message });
+        throw error;
+      }
       if (!updated)
         throw new HTTPException(409, {
           message: "Connection access changed. Reload before saving.",
         });
+      if (core) {
+        // A wider scope or model list can make waiting work placeable.
+        try {
+          const change = subscriptionCoreAccessChangeWake(connection.kind, connection.accountId);
+          if (change)
+            await deliverSubscriptionCoreWake(
+              deps.db,
+              change.provider,
+              change.wake,
+              change.displayName,
+            );
+        } catch {
+          // Every core waiter has its own bounded recheck; a lost wake only delays.
+        }
+      }
       return c.json(updated);
     });
   }