@opengeni/api-router 3.0.1 → 3.1.2

package/src/routes/supergrok.ts

@@ -1,69 +1,55 @@
+import { registerSubscriptionAccountPoolRoutes } from "./subscription-account-pools";
+import {
+  coreConnectRefused,
+  deliverPoolCoreWake,
+  requireSubscriptionCoreRoute,
+  type SubscriptionPoolCore,
+} from "./subscription-pool-core";
+import {
+  managedCookieHuman,
+  requireSameOriginBrowserMutation,
+  requireSubscriptionScopeMutation,
+} from "./subscription-pool-access";
+export { managedCookieHuman } from "./subscription-pool-access";
 import { requireOrganizationCodexHuman } from "./codex";
 import {
-  listOrganizationXaiSubscriptions,
-  upsertOrganizationXaiSubscription,
-  updateOrganizationXaiSubscription,
-  updateOrganizationXaiRotation,
+  connectSubscriptionCoreXaiConnection,
+  getSubscriptionCoreXaiOrganizationProjection,
+  getSubscriptionCoreXaiWorkspaceProjection,
+  SUBSCRIPTION_CORE_XAI,
+  encryptEnvironmentValue,
+  decryptEnvironmentValue,
+  type XaiSubscriptionAccountMetadata,
 } from "@opengeni/db";
 import {
   configuredModels,
   environmentsEncryptionKeyBytes,
   withXaiSubscriptionCatalogProvider,
 } from "@opengeni/config";
-import {
-  WORKSPACE_XAI_PROVIDER_ACCOUNT_AUTHORITY_SNAPSHOT_V1,
-  type XaiProviderAccountAuthoritySnapshotV1,
-} from "@opengeni/contracts";
-import {
-  disconnectXaiSubscriptionCredentialAndRepick,
-  ensureXaiRotationSettings,
-  getXaiRotationSettings,
-  getXaiSubscriptionAccountAuthoritySnapshot,
-  listXaiSubscriptionAccountsMetadata,
-  materializeXaiCredentialForRun,
-  refreshXaiSubscriptionCredentialSerialized,
-  renameXaiSubscriptionAccount,
-  resolveXaiProviderAccountAuthoritySnapshotForAcceptance,
-  setActiveXaiCredential,
-  setInitialActiveXaiCredential,
-  updateXaiAllocatorEligibility,
-  updateXaiRotationSettings,
-  upsertXaiSubscriptionCredential,
-  wakeXaiCapacityWaiters,
-  encryptEnvironmentValue,
-  decryptEnvironmentValue,
-  getWorkspaceGrant,
-  type XaiSubscriptionAccountMetadata,
-} from "@opengeni/db";
+import { SubscriptionConnectPollRequest, SupergrokConnectStartRequest } from "@opengeni/contracts";
 import { createSignedState, readSignedState } from "@opengeni/github";
 import {
-  getManagedSession,
   requireAccessGrant,
   requireAccessGrantAuthorization,
   externalActorContinuationForAuthorization,
   type ApiRouteDeps,
 } from "@opengeni/core";
 import {
-  XAI_CLIENT_VERSION,
   XaiSubscriptionError,
-  fetchXaiSubscriptionModels,
   pollXaiDeviceCode,
-  refreshXaiToken,
   requestXaiDeviceCode,
   xaiAccessTokenExpiry,
   xaiIdentityFromDeviceTokens,
   type XaiFetch,
-  type XaiProxyAuthContext,
 } from "@opengeni/xai-subscription";
 import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
-import * as z from "zod/v4";
 import { projectClientModel } from "../model-catalog";
+import { readXaiCoreStatus } from "../xai-subscription-core";
 import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
 import { requireConnectOwnerAuthority } from "../integrations/connect-authority";
-
-type XaiAuthoritySnapshot = XaiProviderAccountAuthoritySnapshotV1;
-type ManagedCookieHuman = { subjectId: string };
+import { databaseUnavailableHttpError } from "../http/api-error";
+import { requirePrivateSubscriptionHuman } from "./subscription-pool-access";
 
 type SuperGrokConnectState = {
   externalContinuationEncrypted?: string;
@@ -76,59 +62,20 @@ type SuperGrokConnectState = {
   iat: number;
 };
 
-const connectStartBody = z.object({
-  scope: z.enum(["workspace", "user"]).default("workspace"),
-});
-const connectPollBody = z.object({ state: z.string().min(1).max(16_384) });
-const allocatorBody = z.object({
-  enabled: z.boolean(),
-  expectedVersion: z.number().int().positive(),
-});
-const settingsBody = z.object({ rotationEnabled: z.boolean() });
-const renameBody = z.object({ label: z.string().trim().max(200).nullable() });
-
-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;
-}
+const connectStartBody = SupergrokConnectStartRequest;
 
-function requireSameOriginBrowserMutation(c: Context, deps: ApiRouteDeps): void {
-  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",
-    });
-  }
-}
+/**
+ * SuperGrok on the shared subscription core (provider id `xai`), its only
+ * runtime: the legacy pool runtime was deleted after the SuperGrok cutover.
+ */
+const SUPERGROK_CORE: SubscriptionPoolCore = {
+  binding: SUBSCRIPTION_CORE_XAI,
+  workspaceProjection: getSubscriptionCoreXaiWorkspaceProjection,
+  organizationProjection: getSubscriptionCoreXaiOrganizationProjection,
+};
+const supergrokRoute = (deps: ApiRouteDeps, accountId: () => Promise<string>) =>
+  requireSubscriptionCoreRoute(deps, "xai", "SuperGrok", accountId);
+const connectPollBody = SubscriptionConnectPollRequest;
 
 function requireEnabled(deps: ApiRouteDeps): void {
   if (!deps.settings.supergrokSubscriptionEnabled) {
@@ -138,100 +85,43 @@ function requireEnabled(deps: ApiRouteDeps): void {
   }
 }
 
-async function requirePrivateHuman(
-  c: Context,
-  deps: ApiRouteDeps,
-  workspaceId: string,
-): 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
-    ) {
-      // The existing xAI user-pool domain requires an ordinary workspace
-      // membership, not just the synthetic Personal-workspace owner grant.
-      if (!(await getWorkspaceGrant(deps.db, authorization.grant.subjectId, workspaceId)))
-        throw new HTTPException(409, {
-          message: "Private SuperGrok accounts require membership in an ordinary workspace",
-        });
-      return { accountId: authorization.grant.accountId, subjectId: authorization.grant.subjectId };
-    }
-    throw new HTTPException(403, {
-      message: "Private SuperGrok accounts require a verified owning user",
-    });
-  }
-  const human = await managedCookieHuman(c, deps);
-  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",
-    });
-  }
-  if (!(await getWorkspaceGrant(deps.db, grant.subjectId, workspaceId)))
-    throw new HTTPException(409, {
-      message: "Private SuperGrok accounts require membership in an ordinary workspace",
-    });
-  return { accountId: grant.accountId, subjectId: grant.subjectId };
-}
-
-export async function requireScopeMutation(
+/**
+ * The legacy scope check; on the shared core a private (`user`) account is
+ * managed only from its owner's Personal workspace.
+ */
+export const requireScopeMutation = (
   c: Context,
   deps: ApiRouteDeps,
   workspaceId: string,
   scope: "workspace" | "user" | "organization",
-): 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 requirePrivateHuman(c, deps, workspaceId);
-  }
-  const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
-  return { accountId: grant.accountId, subjectId: grant.subjectId };
-}
-
-async function resolveReadAuthority(
-  c: Context,
-  deps: ApiRouteDeps,
-  workspaceId: string,
-): Promise<{
-  accountId: string;
-  subjectId: string;
-  snapshot: XaiAuthoritySnapshot;
-}> {
-  const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
-  const snapshot = await resolveXaiProviderAccountAuthoritySnapshotForAcceptance(deps.db, {
+  runtime: "legacy" | "core" = "legacy",
+) =>
+  requireSubscriptionScopeMutation(
+    c,
+    deps,
     workspaceId,
-    subjectId: grant.subjectId,
-  });
-  if (snapshot.scope !== "user") {
-    return { accountId: grant.accountId, subjectId: grant.subjectId, snapshot };
-  }
-  const human = await requirePrivateHuman(c, deps, workspaceId);
-  if (human.subjectId !== grant.subjectId) {
-    throw new HTTPException(403, {
-      message: "managed browser identity mismatch",
-    });
-  }
-  return { accountId: human.accountId, subjectId: human.subjectId, snapshot };
-}
+    scope,
+    "SuperGrok",
+    runtime === "core" ? "personal_workspace" : "ordinary_workspace",
+  );
+
+/**
+ * The runtime serving a workspace route. With the receipt the switch row is
+ * read for the caller's organization, which a workspace grant names first,
+ * so an unauthenticated caller learns nothing about it.
+ */
+const workspaceRuntime = (c: Context, deps: ApiRouteDeps, workspaceId: string) =>
+  supergrokRoute(
+    deps,
+    async () => (await requireAccessGrant(c, deps, workspaceId, "workspace:read")).accountId,
+  );
 
 function xaiHttpError(error: unknown, fallback: string): HTTPException {
+  // A connect poll can lose its database connection after provider login or
+  // persistence. Preserve retryability and unknown mutation outcome instead
+  // of misclassifying the outage as a provider 502.
+  const databaseError = databaseUnavailableHttpError(error, "POST");
+  if (databaseError) return databaseError;
   if (error instanceof HTTPException) return error;
   if (error instanceof XaiSubscriptionError) {
     const status =
@@ -271,119 +161,62 @@ function accountJson(row: XaiSubscriptionAccountMetadata, activeCredentialId: st
   };
 }
 
-async function materializedAuthContext(
+/**
+ * Persist a finished SuperGrok device sign-in on the shared core: a personal
+ * connection for a `user` scope (only in the person's Personal workspace),
+ * else a shared one through the neutral writer. Returns the connection id.
+ */
+async function coreSuperGrokConnected(
+  c: Context,
   deps: ApiRouteDeps,
   input: {
     accountId: string;
-    workspaceId: string;
+    workspaceId: string | null;
     subjectId: string;
-    credentialId: string;
-    authoritySnapshot: XaiAuthoritySnapshot;
+    personal?: boolean;
+    encryptionKey: Uint8Array;
+    tokens: { accessToken: string; refreshToken?: string | null; expiresInSeconds: number };
+    identity: ReturnType<typeof xaiIdentityFromDeviceTokens>;
   },
-): Promise<{
-  context: XaiProxyAuthContext;
-  account: XaiSubscriptionAccountMetadata;
-}> {
-  const encryptionKey = environmentsEncryptionKeyBytes(deps.settings);
-  if (!encryptionKey) {
-    throw new HTTPException(500, {
-      message: "OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY is not configured",
-    });
-  }
-  let credential = await materializeXaiCredentialForRun(deps.db, {
-    ...input,
-    encryptionKey,
-  });
-  const tokenSnapshot = () => {
-    if (!credential.secret.accessToken || !credential.providerAccountId) {
-      throw new XaiSubscriptionError(
-        "relogin_required",
-        "The SuperGrok connection is missing an access token or verified identity",
-      );
-    }
-    return {
-      accessToken: credential.secret.accessToken,
-      userId: credential.providerAccountId,
-    };
-  };
-  return {
-    account: credential,
-    context: {
-      clientVersion: XAI_CLIENT_VERSION,
-      getToken: async () => tokenSnapshot(),
-      refresh: async () => {
-        const observedAccessToken = credential.secret.accessToken;
-        const observedRefreshToken = credential.secret.refreshToken;
-        if (!observedRefreshToken) {
-          throw new XaiSubscriptionError(
-            "relogin_required",
-            "The SuperGrok connection cannot be refreshed",
-          );
-        }
-        const result = await refreshXaiSubscriptionCredentialSerialized(deps.db, {
-          accountId: input.accountId,
-          workspaceId: input.workspaceId,
-          subjectId: input.subjectId,
-          credentialId: input.credentialId,
-          authoritySnapshot: input.authoritySnapshot,
-          encryptionKey,
-          observedAccessToken,
-          observedRefreshToken,
-          refresh: async (current) => {
-            const refreshToken = current.secret.refreshToken;
-            if (!refreshToken) {
-              throw new XaiSubscriptionError(
-                "relogin_required",
-                "The SuperGrok connection cannot be refreshed",
-              );
-            }
-            const tokens = await refreshXaiToken(refreshToken, {
-              fetch: (deps.xaiFetch ?? fetch) as XaiFetch,
-            });
-            return {
-              secret: {
-                version: 1,
-                accessToken: tokens.accessToken,
-                refreshToken: tokens.refreshToken,
-              },
-              expiresAt:
-                xaiAccessTokenExpiry(tokens.accessToken) ??
-                new Date(Date.now() + tokens.expiresInSeconds * 1_000),
-            };
-          },
-        });
-        credential = result.credential;
-        return tokenSnapshot();
-      },
+): Promise<string> {
+  const result = await connectSubscriptionCoreXaiConnection(deps.db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    subjectId: input.subjectId,
+    ...(input.personal ? { personal: true } : {}),
+    encryptionKey: input.encryptionKey,
+    tokens: {
+      accessToken: input.tokens.accessToken,
+      refreshToken: input.tokens.refreshToken || null,
     },
-  };
-}
-
-async function authorityForAccountMutation(
-  c: Context,
-  deps: ApiRouteDeps,
-  workspaceId: string,
-  credentialId: string,
-): Promise<{
-  accountId: string;
-  subjectId: string;
-  snapshot: XaiAuthoritySnapshot;
-}> {
-  const readGrant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
-  const snapshot = await getXaiSubscriptionAccountAuthoritySnapshot(deps.db, {
-    workspaceId,
-    subjectId: readGrant.subjectId,
-    credentialId,
+    identitySubject: input.identity.subject,
+    accountEmail: input.identity.email,
+    label: input.identity.name ?? input.identity.email ?? input.identity.subject,
+    expiresAt:
+      xaiAccessTokenExpiry(input.tokens.accessToken) ??
+      new Date(Date.now() + input.tokens.expiresInSeconds * 1_000),
+    connectedBySubjectId: (await managedCookieHuman(c, deps))?.subjectId ?? null,
   });
-  if (!snapshot) throw new HTTPException(404, { message: "SuperGrok account not found" });
-  const mutation = await requireScopeMutation(c, deps, workspaceId, snapshot.scope);
-  return { ...mutation, snapshot };
+  if (result.kind === "refused")
+    throw coreConnectRefused(result.reason, "SuperGrok", input.personal === true);
+  await deliverPoolCoreWake(deps, SUPERGROK_CORE, result.wake);
+  return result.id;
 }
 
 export function registerSuperGrokRoutes(app: Hono, deps: ApiRouteDeps): void {
+  registerSubscriptionAccountPoolRoutes(app, deps, {
+    provider: "xai",
+    route: "supergrok",
+    displayName: "SuperGrok",
+    enabled: () => deps.settings.supergrokSubscriptionEnabled,
+    accountJson,
+    core: SUPERGROK_CORE,
+  });
   const { db } = deps;
 
   const organizationPath = "/v1/organizations/:organizationId/supergrok";
+  // Device sign-in (start/poll) accepts an agent acting as an admin: the agent
+  // relays the short code, and the person still approves at xAI themselves.
   const organizationActor = async (c: Context, mutation = false) => {
     requireEnabled(deps);
     if (mutation) requireSameOriginBrowserMutation(c, deps);
@@ -391,24 +224,10 @@ export function registerSuperGrokRoutes(app: Hono, deps: ApiRouteDeps): void {
     const human = await requireOrganizationCodexHuman(c, deps, organizationId);
     return { organizationId, actorSubjectId: human.subjectId };
   };
-  app.get(`${organizationPath}/accounts`, async (c) => {
-    const actor = await organizationActor(c);
-    const { accounts, rotation } = await listOrganizationXaiSubscriptions(db, actor);
-    const activeAccountId = rotation?.activeCredentialId ?? null;
-    return c.json({
-      accounts: accounts.map((account) => accountJson(account, activeAccountId)),
-      activeAccountId,
-      source: "organization",
-      organizationId: actor.organizationId,
-      settings: {
-        rotationEnabled: rotation?.rotationEnabled ?? false,
-        rotationStrategy: "sharded",
-        activeCredentialId: activeAccountId,
-      },
-    });
-  });
   app.post(`${organizationPath}/connect/start`, async (c) => {
     const actor = await organizationActor(c, true);
+    // A sign-in that could not be saved is never started (maintenance fails closed).
+    await supergrokRoute(deps, async () => actor.organizationId);
     try {
       const start = await requestXaiDeviceCode({ fetch: (deps.xaiFetch ?? fetch) as XaiFetch });
       const expiresAt = Math.floor(Date.now() / 1000) + start.expiresInSeconds;
@@ -429,6 +248,7 @@ export function registerSuperGrokRoutes(app: Hono, deps: ApiRouteDeps): void {
   });
   app.post(`${organizationPath}/connect/poll`, async (c) => {
     const actor = await organizationActor(c, true);
+    await supergrokRoute(deps, async () => actor.organizationId);
     const parsed = connectPollBody.safeParse(await c.req.json().catch(() => null));
     if (!parsed.success) throw new HTTPException(400, { message: "SuperGrok state is required" });
     const state = readSignedState(parsed.data.state, deps.githubStateSecret) as {
@@ -459,94 +279,38 @@ export function registerSuperGrokRoutes(app: Hono, deps: ApiRouteDeps): void {
       const encryptionKey = environmentsEncryptionKeyBytes(deps.settings);
       if (!encryptionKey)
         throw new HTTPException(500, { message: "Connection encryption is not configured" });
-      const connected = await upsertOrganizationXaiSubscription(db, {
-        ...actor,
+      const id = await coreSuperGrokConnected(c, deps, {
+        accountId: actor.organizationId,
+        workspaceId: null,
+        subjectId: actor.actorSubjectId,
         encryptionKey,
-        secret: {
-          version: 1,
-          accessToken: poll.tokens.accessToken,
-          refreshToken: poll.tokens.refreshToken,
-        },
-        providerAccountId: identity.subject,
-        label: identity.name ?? identity.email ?? identity.subject,
-        accountEmail: identity.email,
-        expiresAt:
-          xaiAccessTokenExpiry(poll.tokens.accessToken) ??
-          new Date(Date.now() + poll.tokens.expiresInSeconds * 1000),
+        tokens: poll.tokens,
+        identity,
+      });
+      const { activeCredentialId } = await getSubscriptionCoreXaiOrganizationProjection(db, {
+        organizationId: actor.organizationId,
+        subjectId: actor.actorSubjectId,
       });
       return c.json({
         status: "connected",
-        accountId: connected.account.id,
+        accountId: id,
         scope: "organization",
-        isActive: connected.isActive,
+        isActive: activeCredentialId === id,
         email: identity.email,
       });
     } catch (error) {
       throw xaiHttpError(error, "SuperGrok device login failed");
     }
   });
-  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" });
-    const rotation = await updateOrganizationXaiRotation(db, { ...actor, ...parsed.data });
-    return c.json({
-      rotationEnabled: rotation.rotationEnabled,
-      rotationStrategy: "sharded",
-      activeCredentialId: rotation.activeCredentialId,
-    });
-  });
-  const updateOrganizationAccount = async (
-    c: Context,
-    changes: Omit<
-      Parameters<typeof updateOrganizationXaiSubscription>[1],
-      "organizationId" | "actorSubjectId" | "credentialId"
-    >,
-  ) => {
-    const actor = await organizationActor(c, true);
-    try {
-      const result = await updateOrganizationXaiSubscription(db, {
-        ...actor,
-        credentialId: c.req.param("accountId")!,
-        ...changes,
-      });
-      if (!result) throw new HTTPException(404, { message: "SuperGrok account not found" });
-      return c.json(result);
-    } catch (error) {
-      if (error instanceof HTTPException) throw error;
-      throw new HTTPException(409, {
-        message:
-          error instanceof Error ? error.message : "SuperGrok subscription could not be updated",
-      });
-    }
-  };
-  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.post("/v1/workspaces/:workspaceId/supergrok/connect/start", async (c) => {
     requireEnabled(deps);
     const workspaceId = c.req.param("workspaceId");
     const parsed = connectStartBody.safeParse(await c.req.json().catch(() => ({})));
     if (!parsed.success) throw new HTTPException(400, { message: "invalid SuperGrok scope" });
-    const authority = await requireScopeMutation(c, deps, workspaceId, parsed.data.scope);
+    // On the core a private account is connected only from the person's own
+    // Personal workspace: refused here, before the xAI sign-in, elsewhere.
+    const runtime = await workspaceRuntime(c, deps, workspaceId);
+    const authority = await requireScopeMutation(c, deps, workspaceId, parsed.data.scope, runtime);
     const authorization = await requireAccessGrantAuthorization(
       c,
       deps,
@@ -613,7 +377,8 @@ export function registerSuperGrokRoutes(app: Hono, deps: ApiRouteDeps): void {
         message: "SuperGrok connect state is invalid or expired",
       });
     }
-    const authority = await requireScopeMutation(c, deps, workspaceId, state.scope);
+    const runtime = await workspaceRuntime(c, deps, workspaceId);
+    const authority = await requireScopeMutation(c, deps, workspaceId, state.scope, runtime);
     if (authority.subjectId !== state.subjectId) {
       throw new HTTPException(403, {
         message: "SuperGrok connect identity changed",
@@ -660,7 +425,7 @@ export function registerSuperGrokRoutes(app: Hono, deps: ApiRouteDeps): void {
       const identity = xaiIdentityFromDeviceTokens(poll.tokens);
       phase = "credential_persist";
       await requireOrigin();
-      const liveAuthority = await requireScopeMutation(c, deps, workspaceId, state.scope);
+      const liveAuthority = await requireScopeMutation(c, deps, workspaceId, state.scope, runtime);
       if (
         liveAuthority.accountId !== authority.accountId ||
         liveAuthority.subjectId !== authority.subjectId
@@ -672,51 +437,25 @@ export function registerSuperGrokRoutes(app: Hono, deps: ApiRouteDeps): void {
           message: "OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY is not configured",
         });
       }
-      const upserted = await upsertXaiSubscriptionCredential(deps.db, {
+      const id = await coreSuperGrokConnected(c, deps, {
         accountId: authority.accountId,
         workspaceId,
         subjectId: authority.subjectId,
-        scope: state.scope,
+        personal: state.scope === "user",
         encryptionKey,
-        secret: {
-          version: 1,
-          accessToken: poll.tokens.accessToken,
-          refreshToken: poll.tokens.refreshToken,
-        },
-        providerAccountId: identity.subject,
-        label: identity.name ?? identity.email ?? identity.subject,
-        accountEmail: identity.email,
-        expiresAt:
-          xaiAccessTokenExpiry(poll.tokens.accessToken) ??
-          new Date(Date.now() + poll.tokens.expiresInSeconds * 1_000),
+        tokens: poll.tokens,
+        identity,
       });
-      const rotation = await ensureXaiRotationSettings(deps.db, {
+      const { activeCredentialId } = await getSubscriptionCoreXaiWorkspaceProjection(deps.db, {
         accountId: authority.accountId,
         workspaceId,
-        subjectId: authority.subjectId,
-        authoritySnapshot: upserted.authoritySnapshot,
-      });
-      let isActive = rotation.activeCredentialId === upserted.account.id;
-      if (!isActive && rotation.activeCredentialId === null) {
-        isActive = await setInitialActiveXaiCredential(deps.db, {
-          accountId: authority.accountId,
-          workspaceId,
-          subjectId: authority.subjectId,
-          authoritySnapshot: upserted.authoritySnapshot,
-          credentialId: upserted.account.id,
-        });
-      }
-      await wakeXaiCapacityWaiters(deps.db, {
-        workspaceId,
-        subjectId: authority.subjectId,
-        authoritySnapshot: upserted.authoritySnapshot,
-        reason: "xai_credential_connected",
+        viewerSubjectId: authority.subjectId,
       });
       return c.json({
         status: "connected" as const,
-        accountId: upserted.account.id,
+        accountId: id,
         scope: state.scope,
-        isActive,
+        isActive: activeCredentialId === id,
         email: identity.email,
       });
     } catch (error) {
@@ -742,265 +481,45 @@ export function registerSuperGrokRoutes(app: Hono, deps: ApiRouteDeps): void {
     }
   });
 
-  app.get("/v1/workspaces/:workspaceId/supergrok/accounts", async (c) => {
-    requireEnabled(deps);
-    const workspaceId = c.req.param("workspaceId");
-    const authority = await resolveReadAuthority(c, deps, workspaceId);
-    const [accounts, settings] = await Promise.all([
-      listXaiSubscriptionAccountsMetadata(deps.db, {
-        workspaceId,
-        subjectId: authority.subjectId,
-      }),
-      getXaiRotationSettings(deps.db, {
-        workspaceId,
-        subjectId: authority.subjectId,
-        authoritySnapshot: authority.snapshot,
-      }),
-    ]);
-    const activeCredentialId = settings?.activeCredentialId ?? null;
-    return c.json({
-      source: authority.snapshot.scope,
-      organizationId: authority.accountId,
-      accounts: accounts
-        .filter((account) =>
-          authority.snapshot.scope === "organization"
-            ? account.scope === "organization"
-            : account.scope !== "organization",
-        )
-        .map((account) => accountJson(account, activeCredentialId)),
-      activeAccountId: activeCredentialId,
-      settings: {
-        rotationEnabled: settings?.rotationEnabled ?? true,
-        rotationStrategy: "sharded" as const,
-        activeCredentialId,
-      },
-    });
-  });
-
   app.get("/v1/workspaces/:workspaceId/supergrok/status", async (c) => {
     requireEnabled(deps);
     const workspaceId = c.req.param("workspaceId");
-    const authority = await resolveReadAuthority(c, deps, workspaceId);
-    const [accounts, settings] = await Promise.all([
-      listXaiSubscriptionAccountsMetadata(deps.db, {
-        workspaceId,
-        subjectId: authority.subjectId,
-      }),
-      getXaiRotationSettings(deps.db, {
-        workspaceId,
-        subjectId: authority.subjectId,
-        authoritySnapshot: authority.snapshot,
-      }),
-    ]);
-    const active = accounts.find((account) => account.id === settings?.activeCredentialId) ?? null;
-    if (!active || !settings?.activeCredentialId) {
-      return c.json({
-        connected: accounts.length > 0,
-        valid: false,
-        accountCount: accounts.length,
-      });
-    }
-    let valid = false;
-    try {
-      const auth = await materializedAuthContext(deps, {
-        accountId: authority.accountId,
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const supergrokModels = async () =>
+      configuredModels(
+        withXaiSubscriptionCatalogProvider((await deps.resolveCatalogSettings()).settings),
+      )
+        .filter(
+          (model) =>
+            model.credentialSource.kind === "connected_subscription" &&
+            model.credentialSource.provider === "xai",
+        )
+        .map(projectClientModel);
+    return c.json(
+      await readXaiCoreStatus(deps, {
+        accountId: grant.accountId,
         workspaceId,
-        subjectId: authority.subjectId,
-        credentialId: active.id,
-        authoritySnapshot: authority.snapshot,
-      });
-      await fetchXaiSubscriptionModels({
-        context: auth.context,
+        subjectId: grant.subjectId,
+        models: supergrokModels,
+        // Only the verified owner in their Personal workspace may make a
+        // live personal-account usage request; other viewers get stored status.
+        ownerVerified: async () => {
+          try {
+            const owner = await requirePrivateSubscriptionHuman(
+              c,
+              deps,
+              workspaceId,
+              "SuperGrok",
+              "personal_workspace",
+            );
+            return owner.accountId === grant.accountId && owner.subjectId === grant.subjectId;
+          } catch (error) {
+            if (error instanceof HTTPException) return false;
+            throw error;
+          }
+        },
         ...(deps.xaiFetch ? { fetch: deps.xaiFetch } : {}),
-      });
-      valid = true;
-    } catch {
-      valid = false;
-    }
-    const catalogSettings = valid ? (await deps.resolveCatalogSettings()).settings : null;
-    const catalog = catalogSettings
-      ? configuredModels(withXaiSubscriptionCatalogProvider(catalogSettings))
-          .filter(
-            (model) =>
-              model.credentialSource.kind === "connected_subscription" &&
-              model.credentialSource.provider === "xai",
-          )
-          .map(projectClientModel)
-      : [];
-    return c.json({
-      connected: true,
-      valid,
-      accountCount: accounts.length,
-      models: catalog,
-      activeAccount: {
-        id: active.id,
-        label: active.label,
-        subject: active.providerAccountId,
-        scope: active.scope,
-      },
-    });
-  });
-
-  app.post("/v1/workspaces/:workspaceId/supergrok/accounts/:accountId/activate", async (c) => {
-    requireEnabled(deps);
-    const workspaceId = c.req.param("workspaceId");
-    const credentialId = c.req.param("accountId");
-    const authority = await authorityForAccountMutation(c, deps, workspaceId, credentialId);
-    const activated = await setActiveXaiCredential(deps.db, {
-      accountId: authority.accountId,
-      workspaceId,
-      subjectId: authority.subjectId,
-      authoritySnapshot: authority.snapshot,
-      credentialId,
-    });
-    if (!activated)
-      throw new HTTPException(409, {
-        message: "SuperGrok account requires relogin",
-      });
-    await wakeXaiCapacityWaiters(deps.db, {
-      workspaceId,
-      subjectId: authority.subjectId,
-      authoritySnapshot: authority.snapshot,
-      reason: "xai_active_credential_changed",
-    });
-    return c.json({ activated: true, accountId: credentialId });
-  });
-
-  app.patch("/v1/workspaces/:workspaceId/supergrok/settings", async (c) => {
-    requireEnabled(deps);
-    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" });
-    const readAuthority = await resolveReadAuthority(c, deps, workspaceId);
-    const authority = await requireScopeMutation(
-      c,
-      deps,
-      workspaceId,
-      readAuthority.snapshot.scope,
+      }),
     );
-    const current = await ensureXaiRotationSettings(deps.db, {
-      accountId: authority.accountId,
-      workspaceId,
-      subjectId: authority.subjectId,
-      authoritySnapshot: readAuthority.snapshot,
-    });
-    const updated = await updateXaiRotationSettings(deps.db, {
-      workspaceId,
-      subjectId: authority.subjectId,
-      authoritySnapshot: readAuthority.snapshot,
-      expectedVersion: current.version,
-      rotationEnabled: parsed.data.rotationEnabled,
-    }).catch(() => null);
-    if (!updated) throw new HTTPException(409, { message: "SuperGrok settings changed" });
-    await wakeXaiCapacityWaiters(deps.db, {
-      workspaceId,
-      subjectId: authority.subjectId,
-      authoritySnapshot: readAuthority.snapshot,
-      reason: "xai_rotation_settings_changed",
-    });
-    return c.json({
-      rotationEnabled: updated.rotationEnabled,
-      rotationStrategy: "sharded" as const,
-      activeCredentialId: updated.activeCredentialId,
-    });
-  });
-
-  app.patch("/v1/workspaces/:workspaceId/supergrok/accounts/:accountId/allocator", async (c) => {
-    requireEnabled(deps);
-    const workspaceId = c.req.param("workspaceId");
-    const credentialId = c.req.param("accountId");
-    const authority = await authorityForAccountMutation(c, deps, workspaceId, credentialId);
-    const parsed = allocatorBody.safeParse(await c.req.json().catch(() => null));
-    if (!parsed.success) {
-      throw new HTTPException(400, {
-        message: "enabled and expectedVersion are required",
-      });
-    }
-    const result = await updateXaiAllocatorEligibility(deps.db, {
-      workspaceId,
-      subjectId: authority.subjectId,
-      credentialId,
-      enabled: parsed.data.enabled,
-      expectedVersion: parsed.data.expectedVersion,
-    });
-    if (result.kind === "not_found") {
-      throw new HTTPException(404, {
-        message: "SuperGrok account not found",
-      });
-    }
-    const response = {
-      allocatorEnabled: result.allocatorEnabled,
-      allocatorVersion: result.allocatorVersion,
-      allocatorUpdatedAt: result.allocatorUpdatedAt?.toISOString() ?? null,
-      changed: result.kind === "updated",
-    };
-    if (result.kind === "updated") {
-      await wakeXaiCapacityWaiters(deps.db, {
-        workspaceId,
-        subjectId: authority.subjectId,
-        authoritySnapshot: authority.snapshot,
-        reason: "xai_allocator_eligibility_changed",
-      });
-    }
-    return result.kind === "conflict" ? c.json(response, 409) : c.json(response);
-  });
-
-  app.patch("/v1/workspaces/:workspaceId/supergrok/accounts/:accountId", async (c) => {
-    requireEnabled(deps);
-    const workspaceId = c.req.param("workspaceId");
-    const credentialId = c.req.param("accountId");
-    const authority = await authorityForAccountMutation(c, deps, workspaceId, credentialId);
-    const parsed = renameBody.safeParse(await c.req.json().catch(() => null));
-    if (!parsed.success) throw new HTTPException(400, { message: "label is invalid" });
-    const account = await renameXaiSubscriptionAccount(deps.db, {
-      workspaceId,
-      subjectId: authority.subjectId,
-      credentialId,
-      label: parsed.data.label || null,
-    });
-    if (!account)
-      throw new HTTPException(404, {
-        message: "SuperGrok account not found",
-      });
-    const settings = await getXaiRotationSettings(deps.db, {
-      workspaceId,
-      subjectId: authority.subjectId,
-      authoritySnapshot: authority.snapshot,
-    });
-    return c.json(accountJson(account, settings?.activeCredentialId ?? null));
-  });
-
-  app.delete("/v1/workspaces/:workspaceId/supergrok/accounts/:accountId", async (c) => {
-    requireEnabled(deps);
-    const workspaceId = c.req.param("workspaceId");
-    const credentialId = c.req.param("accountId");
-    const authority = await authorityForAccountMutation(c, deps, workspaceId, credentialId);
-    if (authority.snapshot.scope === "user") {
-      await wakeXaiCapacityWaiters(deps.db, {
-        workspaceId,
-        subjectId: authority.subjectId,
-        authoritySnapshot: authority.snapshot,
-        reason: "xai_credential_disconnecting",
-      });
-    }
-    const result = await disconnectXaiSubscriptionCredentialAndRepick(deps.db, {
-      accountId: authority.accountId,
-      workspaceId,
-      subjectId: authority.subjectId,
-      credentialId,
-      authoritySnapshot: authority.snapshot,
-    });
-    if (result.disconnected && authority.snapshot.scope === "workspace") {
-      await wakeXaiCapacityWaiters(deps.db, {
-        workspaceId,
-        subjectId: authority.subjectId,
-        authoritySnapshot: WORKSPACE_XAI_PROVIDER_ACCOUNT_AUTHORITY_SNAPSHOT_V1,
-        reason: "xai_credential_disconnected",
-      });
-    }
-    return c.json({
-      disconnected: result.disconnected,
-      newActiveId: result.newActiveCredentialId,
-    });
   });
 }