@opengeni/api-router 3.0.1 → 3.1.2

package/src/routes/claude-core-usage.ts

@@ -0,0 +1,147 @@
+// Claude usage routes on the shared subscription core (design 5.3, Claude
+// track C2a, EP-N24 and EP-S13). The usage routes read the organization's
+// Claude provider route once after authentication: missing or disabled
+// receipts answer a typed 503; `core` projects the connection's quota in the legacy
+// `ClaudeSubscriptionUsage` shape. Paths, auth checks and cache headers are
+// the legacy ones. A refresh reads live: a shared connection of the
+// workspace's pool through the core connection seam, the caller's own
+// personal connection in their own Personal workspace through the owner-only
+// seam, and an organization-pool connection on the organization route
+// through the administrator seam (design 5.3, C2c).
+import type { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+import type { ClaudeSubscriptionUsage } from "@opengeni/contracts";
+import type { ApiRouteDeps } from "@opengeni/core";
+import {
+  deliverSubscriptionCoreProviderWake,
+  projectSubscriptionCoreClaudeUsage,
+  readSubscriptionCoreClaudeOrganizationUsageRow,
+  readSubscriptionCoreClaudeWorkspaceUsageTarget,
+  readSubscriptionCoreProviderRouteForWorkspace,
+  refreshSubscriptionCoreClaudeOrganizationUsage,
+  refreshSubscriptionCoreClaudeWorkspaceUsage,
+} from "@opengeni/db";
+import { ApiHttpError } from "../http/api-error";
+import { SUBSCRIPTION_CORE_CUTOVER_DISABLED } from "./codex-core";
+import {
+  requirePrivateSubscriptionHuman,
+  requireSubscriptionScopeMutation,
+} from "./subscription-pool-access";
+
+/** An authenticated usage caller whose organization serves Claude from the core. */
+export type CoreClaudeUsageCaller = {
+  core: true;
+  accountId: string;
+  /** Null on the organization path. */
+  workspaceId: string | null;
+  subjectId: string;
+  /** The route's account id: a canonical connection id or a cutover alias. */
+  accountIdParam: string;
+};
+
+/**
+ * Require Claude's core route for an authenticated usage caller. Missing or
+ * disabled receipts fail closed with the typed 503 the Codex routes use.
+ */
+export async function claudeUsageRoute(
+  deps: ApiRouteDeps,
+  accountId: string,
+  workspaceId: string | null,
+): Promise<"core"> {
+  const route = await readSubscriptionCoreProviderRouteForWorkspace(deps.db, {
+    accountId,
+    workspaceId,
+    provider: "claude",
+  });
+  if (route !== "core") {
+    throw new ApiHttpError(503, {
+      code: "upstream_unavailable",
+      message: "Claude subscriptions are paused for maintenance in this organization",
+      retryable: true,
+      outcomeUnknown: false,
+      details: { reason: SUBSCRIPTION_CORE_CUTOVER_DISABLED },
+    });
+  }
+  return route;
+}
+
+/**
+ * Wake the Claude core waiters after a reading that ended a stored
+ * exhaustion. The reading already committed; a failed wake hint never fails
+ * the read (every core waiter has its own recheck).
+ */
+async function wakeAfterRecovery(
+  deps: ApiRouteDeps,
+  accountId: string,
+  result: { usage: ClaudeSubscriptionUsage; recovered: boolean },
+): Promise<ClaudeSubscriptionUsage> {
+  if (result.recovered) {
+    await deliverSubscriptionCoreProviderWake(deps.db, "claude", {
+      accountId,
+      reason: "usage_recovered",
+    }).catch(() => undefined);
+  }
+  return result.usage;
+}
+
+/** GET or POST refresh of one Claude account's usage on the core. */
+export async function coreClaudeUsage(
+  c: Context,
+  deps: ApiRouteDeps,
+  caller: CoreClaudeUsageCaller,
+  mutation: boolean,
+): Promise<ClaudeSubscriptionUsage> {
+  if (caller.workspaceId === null) {
+    const row = await readSubscriptionCoreClaudeOrganizationUsageRow(deps.db, {
+      organizationId: caller.accountId,
+      subjectId: caller.subjectId,
+      accountIdParam: caller.accountIdParam,
+    });
+    if (!row) throw new HTTPException(404, { message: "Claude account not found" });
+    if (!mutation) return projectSubscriptionCoreClaudeUsage(row);
+    return await wakeAfterRecovery(
+      deps,
+      caller.accountId,
+      await refreshSubscriptionCoreClaudeOrganizationUsage(
+        deps.db,
+        deps.settings,
+        { organizationId: caller.accountId, subjectId: caller.subjectId, row },
+        deps.claudeFetch ? { fetchImpl: deps.claudeFetch } : {},
+      ),
+    );
+  }
+  const workspaceId = caller.workspaceId;
+  const target = await readSubscriptionCoreClaudeWorkspaceUsageTarget(deps.db, {
+    accountId: caller.accountId,
+    workspaceId,
+    subjectId: caller.subjectId,
+    accountIdParam: caller.accountIdParam,
+  });
+  if (!target) throw new HTTPException(404, { message: "Claude account not found" });
+  // The legacy authority checks, by the scope the connection maps to. A
+  // personal connection lives only in its owner's own Personal workspace on
+  // the core (D-03), so its verified owner is checked there, never through
+  // the legacy ordinary-workspace membership rule (which no Personal
+  // workspace passes).
+  if (target.scope === "user")
+    await requirePrivateSubscriptionHuman(c, deps, workspaceId, "Claude", "personal_workspace");
+  if (!mutation) return projectSubscriptionCoreClaudeUsage(target.row);
+  await requireSubscriptionScopeMutation(
+    c,
+    deps,
+    workspaceId,
+    target.scope,
+    "Claude",
+    "personal_workspace",
+  );
+  return await wakeAfterRecovery(
+    deps,
+    caller.accountId,
+    await refreshSubscriptionCoreClaudeWorkspaceUsage(
+      deps.db,
+      deps.settings,
+      { accountId: caller.accountId, workspaceId, subjectId: caller.subjectId, target },
+      deps.claudeFetch ? { fetchImpl: deps.claudeFetch } : {},
+    ),
+  );
+}

package/src/routes/claude-subscription-accounts.ts

@@ -0,0 +1,233 @@
+import { createHmac } from "node:crypto";
+import { z } from "zod";
+import { requireEnvironmentEncryption } from "@opengeni/core";
+import { ClaudeSubscriptionCredential } from "@opengeni/config";
+import type { ClaudeSubscriptionAccountMetadata } from "@opengeni/db";
+
+import { prepareClaudeSubscriptionCredential } from "../claude-workspace-connection";
+import { requireAccessGrant } from "@opengeni/core";
+import { ClaudeSubscriptionUsage, ClaudeSubscriptionSetupTokenRequest } from "@opengeni/contracts";
+
+import { requireOrganizationCodexHuman } from "./codex";
+import {
+  requireSameOriginBrowserMutation,
+  requireSubscriptionScopeMutation,
+} from "./subscription-pool-access";
+
+import { HTTPException } from "hono/http-exception";
+import type { Context } from "hono";
+
+import type { ApiRouteDeps } from "@opengeni/core";
+import type { Hono } from "hono";
+import { offerClaudeDefaultModels } from "../claude-default-models";
+import { registerSubscriptionAccountPoolRoutes } from "./subscription-account-pools";
+import { claudeUsageRoute, coreClaudeUsage, type CoreClaudeUsageCaller } from "./claude-core-usage";
+import {
+  claudeCoreAccount,
+  claudeCoreRoute,
+  claudePoolCore,
+  connectClaudeCore,
+  requireClaudeCorePersonalWorkspace,
+} from "../claude-subscription-core";
+import { deliverPoolCoreWake } from "./subscription-pool-core";
+import { managedCookieHuman } from "./subscription-pool-access";
+
+function accountJson(account: ClaudeSubscriptionAccountMetadata, activeId: string | null) {
+  return {
+    id: account.id,
+    scope: account.scope,
+    subject: account.providerAccountId ?? account.id,
+    email: account.accountEmail,
+    label: account.label,
+    plan: account.planType,
+    status: account.status,
+    active: account.id === activeId,
+    version: account.version,
+    expiresAt: account.expiresAt?.toISOString() ?? null,
+    lastRefreshAt: account.lastRefreshAt?.toISOString() ?? null,
+    lastError: account.lastError,
+    allocatorEnabled: account.allocatorEnabled,
+    allocatorVersion: account.allocatorVersion,
+    allocatorUpdatedAt: account.allocatorUpdatedAt?.toISOString() ?? null,
+  };
+}
+
+const CLAUDE_CORE = claudePoolCore(accountJson);
+const SETUP_TOKEN_CHANGED = "Claude account changed. Reload it before replacing the token.";
+
+export function registerClaudeSubscriptionAccountRoutes(app: Hono, deps: ApiRouteDeps) {
+  registerSubscriptionAccountPoolRoutes(app, deps, {
+    provider: "claude",
+    route: "claude",
+    displayName: "Claude",
+    enabled: () => deps.settings.claudeSubscriptionEnabled,
+    accountJson,
+    core: CLAUDE_CORE,
+  });
+  async function usageAuthority(
+    c: Context,
+    organization: boolean,
+    mutation: boolean,
+  ): Promise<CoreClaudeUsageCaller> {
+    c.header("cache-control", "private, no-store");
+    if (!deps.settings.claudeSubscriptionEnabled)
+      throw new HTTPException(404, { message: "Claude subscriptions are not enabled" });
+    const credentialId = z.string().uuid().safeParse(c.req.param("accountId"));
+    if (!credentialId.success)
+      throw new HTTPException(400, { message: "Invalid Claude account ID" });
+    if (mutation && !c.req.header("authorization")) requireSameOriginBrowserMutation(c, deps);
+    if (organization) {
+      const accountId = c.req.param("organizationId")!;
+      const human = await requireOrganizationCodexHuman(c, deps, accountId);
+      await claudeUsageRoute(deps, accountId, null);
+      return {
+        core: true,
+        accountId,
+        workspaceId: null,
+        subjectId: human.subjectId,
+        accountIdParam: credentialId.data,
+      };
+    }
+    const workspaceId = c.req.param("workspaceId")!;
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    await claudeUsageRoute(deps, grant.accountId, workspaceId);
+    return {
+      core: true,
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId: grant.subjectId,
+      accountIdParam: credentialId.data,
+    };
+  }
+  for (const organization of [false, true]) {
+    const path = organization
+      ? "/v1/organizations/:organizationId/claude/accounts/:accountId/usage"
+      : "/v1/workspaces/:workspaceId/claude/accounts/:accountId/usage";
+    app.get(path, async (c) => {
+      const authority = await usageAuthority(c, organization, false);
+      return c.json(
+        ClaudeSubscriptionUsage.parse(await coreClaudeUsage(c, deps, authority, false)),
+      );
+    });
+    app.post(path + "/refresh", async (c) => {
+      const authority = await usageAuthority(c, organization, true);
+      return c.json(ClaudeSubscriptionUsage.parse(await coreClaudeUsage(c, deps, authority, true)));
+    });
+  }
+
+  const setupRequest = ClaudeSubscriptionSetupTokenRequest;
+  for (const organization of [false, true]) {
+    const path = organization
+      ? "/v1/organizations/:organizationId/claude/accounts/setup-token"
+      : "/v1/workspaces/:workspaceId/claude/accounts/setup-token";
+    app.post(path, async (c) => {
+      c.header("cache-control", "private, no-store");
+      if (!deps.settings.claudeSubscriptionEnabled)
+        throw new HTTPException(404, { message: "Claude subscriptions are not enabled" });
+      requireSameOriginBrowserMutation(c, deps);
+      const parsed = setupRequest.safeParse(await c.req.json().catch(() => null));
+      if (!parsed.success || (organization && parsed.data.scope !== "workspace"))
+        throw new HTTPException(422, { message: "Enter the Claude setup token." });
+      const actor = organization
+        ? {
+            organizationId: c.req.param("organizationId")!,
+            ...(await requireOrganizationCodexHuman(c, deps, c.req.param("organizationId")!)),
+          }
+        : null;
+      const workspaceId = organization ? null : c.req.param("workspaceId")!;
+      // The runtime first (one receipt read), so a private account on the
+      // core is authorized in the owner's Personal workspace, where the core
+      // keeps it, and refused (403) anywhere else. The read grant naming the
+      // organization is taken only once a receipt exists (the callback), so
+      // legacy authorizes exactly as before.
+      const read: { grant?: Awaited<ReturnType<typeof requireAccessGrant>> } = {};
+      await claudeCoreRoute(deps, async () => {
+        if (actor) return actor.organizationId;
+        read.grant = await requireAccessGrant(c, deps, workspaceId!, "workspace:read");
+        return read.grant.accountId;
+      });
+      if (workspaceId && parsed.data.scope === "user") {
+        if (!read.grant) throw new Error("core Claude route without its read grant");
+        await requireClaudeCorePersonalWorkspace(deps, {
+          accountId: read.grant.accountId,
+          workspaceId,
+          subjectId: read.grant.subjectId,
+        });
+      }
+      const authority = workspaceId
+        ? await requireSubscriptionScopeMutation(
+            c,
+            deps,
+            workspaceId,
+            parsed.data.scope,
+            "Claude",
+            "personal_workspace",
+          )
+        : null;
+      const accountId = actor?.organizationId ?? authority!.accountId;
+      const subjectId = actor?.subjectId ?? authority!.subjectId;
+      const encryptionKey = requireEnvironmentEncryption(deps.settings);
+      const reconnectId = parsed.data.reconnectAccountId;
+
+      const scope = workspaceId ? parsed.data.scope : "organization";
+      const personal = scope === "user";
+      const target = reconnectId
+        ? await claudeCoreAccount(deps, { accountId, workspaceId, subjectId }, reconnectId)
+        : null;
+      if (
+        reconnectId &&
+        (!target ||
+          target.version !== parsed.data.expectedCredentialVersion ||
+          target.scope !== scope)
+      )
+        throw new HTTPException(409, { message: SETUP_TOKEN_CHANGED });
+      const connected = await connectClaudeCore(
+        deps.db,
+        {
+          accountId,
+          workspaceId,
+          subjectId,
+          ...(personal ? { personal: true } : {}),
+          encryptionKey,
+          credential: ClaudeSubscriptionCredential.parse(
+            JSON.parse(
+              prepareClaudeSubscriptionCredential(
+                deps.settings,
+                workspaceId ? "workspace:" + workspaceId : "organization:" + accountId,
+                parsed.data.token,
+              ),
+            ),
+          ),
+          providerAccountId:
+            "setup:" + createHmac("sha256", encryptionKey).update(parsed.data.token).digest("hex"),
+          accountEmail: null,
+          planType: null,
+          label: target?.label ?? parsed.data.label ?? "Claude subscription",
+          connectedBySubjectId: (await managedCookieHuman(c, deps))?.subjectId ?? null,
+          ...(target
+            ? {
+                reconnectTarget: {
+                  connectionId: target.id,
+                  expectedVersion: target.version,
+                  providerAccountId: target.providerAccountId,
+                },
+              }
+            : {}),
+        },
+        SETUP_TOKEN_CHANGED,
+      );
+      await deliverPoolCoreWake(deps, CLAUDE_CORE, connected.wake);
+      await offerClaudeDefaultModels(deps, {
+        ...(workspaceId ? { accountId, workspaceId } : { organizationId: accountId }),
+        actorSubjectId: subjectId,
+        providerKind: "claude_subscription",
+      });
+      return c.json({
+        connected: true,
+        accountId: connected.id,
+        credentialVersion: connected.version,
+        scope,
+      });
+    });
+  }
+}

package/src/routes/claude-subscription-oauth.ts

@@ -0,0 +1,175 @@
+import { requireSubscriptionScopeMutation } from "./subscription-pool-access";
+import {
+  ClaudeSubscriptionOAuthCompleteRequest,
+  ClaudeSubscriptionOAuthStartRequest,
+} from "@opengeni/contracts";
+import { requireAccessGrant, requireFreshAccessGrant, type ApiRouteDeps } from "@opengeni/core";
+import { type Context, type Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+import { hashCodexBrowserSession } from "../codex-redemption-security";
+import { isConfiguredDeploymentKeyRequest } from "../http/auth";
+import {
+  startClaudeSubscriptionOAuth,
+  completeClaudeSubscriptionOAuth,
+  type ClaudeOAuthScope,
+} from "../claude-subscription-oauth";
+import {
+  managedCookieHuman,
+  requireOrganizationCodexHuman,
+  requireSameOriginBrowserMutation,
+} from "./codex";
+import { claudeCoreRoute, requireClaudeCorePersonalWorkspace } from "../claude-subscription-core";
+
+export function registerClaudeSubscriptionOAuthRoutes(
+  app: Hono,
+  deps: ApiRouteDeps,
+  fetchImpl: typeof fetch = globalThis.fetch,
+) {
+  async function scope(
+    c: Context,
+    organization: boolean,
+    fresh = false,
+  ): Promise<ClaudeOAuthScope> {
+    c.header("cache-control", "private, no-store");
+    if (!deps.settings.claudeSubscriptionEnabled)
+      throw new HTTPException(404, {
+        message: "Claude subscriptions are not enabled",
+      });
+    // A key-only deployment has no Opengeni sign-in, so its operator connects
+    // Claude with the deployment key itself (console or API).
+    const deploymentKey = !organization && isConfiguredDeploymentKeyRequest(c, deps.settings);
+    if (!deploymentKey) requireSameOriginBrowserMutation(c, deps);
+    const id = z
+      .string()
+      .uuid()
+      .safeParse(c.req.param(organization ? "organizationId" : "workspaceId"));
+    if (!id.success) throw new HTTPException(404, { message: "Scope not found" });
+    if (organization) {
+      const human = await requireOrganizationCodexHuman(c, deps, id.data, {
+        providerConsent: true,
+      });
+      return {
+        accountId: id.data,
+        workspaceId: null,
+        actorSubjectId: human.subjectId,
+        browserSessionHash: human.browserSessionHash,
+      };
+    }
+    const grant = await (fresh ? requireFreshAccessGrant : requireAccessGrant)(
+      c,
+      deps,
+      id.data,
+      "connections:write",
+    );
+    const human = await managedCookieHuman(c, deps);
+    if (human && human.subjectId === grant.subjectId)
+      return {
+        accountId: grant.accountId,
+        workspaceId: id.data,
+        actorSubjectId: human.subjectId,
+        browserSessionHash: human.browserSessionHash,
+      };
+    if (deploymentKey && grant.principalKind === "configured_key" && grant.subjectId)
+      return {
+        accountId: grant.accountId,
+        workspaceId: id.data,
+        actorSubjectId: grant.subjectId,
+        browserSessionHash: await hashCodexBrowserSession("configured:" + grant.subjectId),
+      };
+    if (
+      deps.settings.productAccessMode === "local" &&
+      grant.subjectId &&
+      !c.req.header("authorization")
+    )
+      return {
+        accountId: grant.accountId,
+        workspaceId: id.data,
+        actorSubjectId: grant.subjectId,
+        browserSessionHash: await hashCodexBrowserSession("local:" + grant.subjectId),
+      };
+    throw new HTTPException(401, {
+      message: "Sign in to Opengeni to connect Claude.",
+    });
+  }
+  /**
+   * Require the Claude cutover receipt at start and completion alike.
+   */
+  async function oauthCore(c: Context, inputScope: ClaudeOAuthScope) {
+    await claudeCoreRoute(deps, async () => inputScope.accountId);
+    return { connectedBySubjectId: (await managedCookieHuman(c, deps))?.subjectId ?? null };
+  }
+  for (const organization of [false, true]) {
+    const path = organization
+      ? "/v1/organizations/:organizationId/model-providers/claude_subscription/oauth"
+      : "/v1/workspaces/:workspaceId/model-providers/claude_subscription/oauth";
+    app.post(`${path}/start`, async (c) => {
+      const inputScope = await scope(c, organization);
+      const payload = ClaudeSubscriptionOAuthStartRequest.safeParse(
+        await c.req.json().catch(() => null),
+      );
+      if (!payload.success || (organization && payload.data.scope !== "workspace"))
+        throw new HTTPException(422, { message: "Choose where to connect this Claude account." });
+      // The runtime first: on the core a private account is authorized in
+      // the owner's Personal workspace and refused (403) anywhere else,
+      // before any Claude sign-in.
+      const core = await oauthCore(c, inputScope);
+      if (payload.data.scope === "user")
+        await requireClaudeCorePersonalWorkspace(deps, {
+          accountId: inputScope.accountId,
+          workspaceId: inputScope.workspaceId,
+          subjectId: inputScope.actorSubjectId,
+        });
+      if (!organization)
+        await requireSubscriptionScopeMutation(
+          c,
+          deps,
+          inputScope.workspaceId!,
+          payload.data.scope,
+          "Claude",
+          "personal_workspace",
+        );
+      return c.json(await startClaudeSubscriptionOAuth(deps, inputScope, payload.data, core));
+    });
+    app.post(`${path}/complete`, async (c) => {
+      const inputScope = await scope(c, organization);
+      const payload = ClaudeSubscriptionOAuthCompleteRequest.safeParse(
+        await c.req.json().catch(() => null),
+      );
+      if (!payload.success)
+        throw new HTTPException(422, {
+          message: "Enter the authorization code from Claude.",
+        });
+      const core = await oauthCore(c, inputScope);
+      return c.json(
+        await completeClaudeSubscriptionOAuth(
+          deps,
+          inputScope,
+          payload.data,
+          async (poolScope) => {
+            if (!organization)
+              await requireSubscriptionScopeMutation(
+                c,
+                deps,
+                inputScope.workspaceId!,
+                poolScope ?? "workspace",
+                "Claude",
+                "personal_workspace",
+              );
+            const fresh = await scope(c, organization, true);
+            if (
+              fresh.accountId !== inputScope.accountId ||
+              fresh.actorSubjectId !== inputScope.actorSubjectId ||
+              fresh.browserSessionHash !== inputScope.browserSessionHash
+            )
+              throw new HTTPException(403, {
+                message: "Your access changed during Claude sign-in. Start again.",
+              });
+          },
+          fetchImpl,
+          core,
+        ),
+      );
+    });
+  }
+}