@opengeni/api-router 0.30.3 → 1.0.0

package/src/claude-subscription-oauth.ts

@@ -0,0 +1,362 @@
+import { claudeAccountMutationFailure } from "./claude-subscription-account-conflicts";
+import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import {
+  CLAUDE_OAUTH_CLIENT_ID,
+  CLAUDE_OAUTH_REDIRECT_URL,
+  CLAUDE_OAUTH_TOKEN_URL,
+  CLAUDE_OAUTH_SCOPES,
+  ClaudeOAuthTokenResponse,
+  ClaudeSubscriptionCredential,
+  claudeAuthorizationUrl,
+} from "@opengeni/config";
+import {
+  ClaudeSubscriptionOAuthStartResponse,
+  ClaudeSubscriptionOAuthCompleteResponse,
+  ClaudeProviderAccountAuthoritySnapshotV1,
+} from "@opengeni/contracts";
+import { requireEnvironmentEncryption, type ApiRouteDeps } from "@opengeni/core";
+import {
+  consumeIntegrationOAuthPendingState,
+  decryptEnvironmentValue,
+  encryptEnvironmentValue,
+  loadIntegrationOAuthPendingState,
+  storeIntegrationOAuthPendingState,
+  withRlsContext,
+  getClaudeSubscriptionAccountAuthoritySnapshot,
+  getClaudeSubscriptionAccountMetadata,
+  listOrganizationClaudeSubscriptions,
+  upsertOrganizationClaudeSubscription,
+  upsertClaudeSubscriptionAccount,
+  setInitialActiveClaudeCredential,
+  wakeClaudeCapacityWaiters,
+} from "@opengeni/db";
+import { readResponseJsonBounded } from "@opengeni/network";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+import { prepareClaudeSubscriptionCredential } from "./claude-workspace-connection";
+import {
+  fetchClaudeSubscriptionProfile,
+  parseClaudeSubscriptionProfile,
+} from "./claude-subscription-profile";
+
+export type ClaudeOAuthScope = {
+  accountId: string;
+  workspaceId: string | null;
+  actorSubjectId: string;
+  browserSessionHash: string;
+};
+const AttemptScope = z
+  .object({
+    purpose: z.literal("claude-subscription-oauth"),
+    accountId: z.string().uuid(),
+    workspaceId: z.string().uuid().nullable(),
+    actorSubjectId: z.string().min(1),
+    browserSessionHash: z.string().min(1),
+    poolScope: z.enum(["organization", "workspace", "user"]),
+    credentialId: z.string().uuid().nullable(),
+    credentialVersion: z.number().int().nonnegative(),
+    authoritySnapshot: ClaudeProviderAccountAuthoritySnapshotV1.nullable(),
+  })
+  .strict();
+const Attempt = z.discriminatedUnion("stage", [
+  AttemptScope.extend({
+    stage: z.literal("pending"),
+    state: z.string().min(32).max(128),
+    verifier: z.string().min(32).max(128),
+  }),
+  AttemptScope.extend({ stage: z.literal("complete") }),
+]);
+const Tokens = ClaudeOAuthTokenResponse.extend({
+  refresh_token: z.string().min(1).max(16384),
+  account: z.object({ uuid: z.string().uuid() }).passthrough().optional(),
+}).passthrough();
+function same(left: string, right: string) {
+  const a = Buffer.from(left),
+    b = Buffer.from(right);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+const changed = () =>
+  new HTTPException(409, { message: "Claude account changed during sign-in. Start again." });
+async function target(deps: ApiRouteDeps, scope: ClaudeOAuthScope, credentialId: string) {
+  if (!scope.workspaceId) {
+    const pool = await listOrganizationClaudeSubscriptions(deps.db, {
+      organizationId: scope.accountId,
+      actorSubjectId: scope.actorSubjectId,
+    });
+    const account = pool.accounts.find((candidate) => candidate.id === credentialId);
+    return account
+      ? { account, authoritySnapshot: { version: 1, scope: "organization" } as const }
+      : null;
+  }
+  const input = { workspaceId: scope.workspaceId, subjectId: scope.actorSubjectId, credentialId };
+  const authoritySnapshot = await getClaudeSubscriptionAccountAuthoritySnapshot(deps.db, input);
+  if (!authoritySnapshot) return null;
+  const account = await getClaudeSubscriptionAccountMetadata(deps.db, input);
+  return account ? { account, authoritySnapshot } : null;
+}
+export async function startClaudeSubscriptionOAuth(
+  deps: ApiRouteDeps,
+  scope: ClaudeOAuthScope,
+  input: { scope?: "workspace" | "user" | undefined; reconnectAccountId?: string | undefined } = {},
+) {
+  const key = requireEnvironmentEncryption(deps.settings);
+  const poolScope = scope.workspaceId ? (input.scope ?? "workspace") : "organization";
+  const current = input.reconnectAccountId
+    ? await target(deps, scope, input.reconnectAccountId)
+    : null;
+  if (input.reconnectAccountId && (!current || current.account.scope !== poolScope))
+    throw changed();
+  const verifier = randomBytes(32).toString("base64url"),
+    state = randomBytes(32).toString("base64url");
+  const id = randomUUID(),
+    expiresAt = new Date(Date.now() + 10 * 60_000);
+  const attempt = Attempt.parse({
+    stage: "pending",
+    purpose: "claude-subscription-oauth",
+    ...scope,
+    poolScope,
+    state,
+    verifier,
+    credentialId: current?.account.id ?? null,
+    credentialVersion: current?.account.version ?? 0,
+    authoritySnapshot: current?.authoritySnapshot ?? null,
+  });
+  await storeIntegrationOAuthPendingState(deps.db, {
+    ...scope,
+    id,
+    expiresAt,
+    stateEncrypted: encryptEnvironmentValue(key, JSON.stringify(attempt)),
+  });
+  return ClaudeSubscriptionOAuthStartResponse.parse({
+    attemptId: id,
+    expiresAt: expiresAt.toISOString(),
+    authorizationUrl: claudeAuthorizationUrl({
+      state,
+      challenge: createHash("sha256").update(verifier).digest("base64url"),
+    }),
+  });
+}
+
+/** Each attempt adds one account or reconnects one exact, generation-fenced target. */
+export async function completeClaudeSubscriptionOAuth(
+  deps: ApiRouteDeps,
+  scope: ClaudeOAuthScope,
+  input: { attemptId: string; code: string },
+  reauthorize: (poolScope?: "workspace" | "user" | "organization") => Promise<void>,
+  fetchImpl: typeof fetch = globalThis.fetch,
+) {
+  const key = requireEnvironmentEncryption(deps.settings);
+  const encrypted = await loadIntegrationOAuthPendingState(deps.db, {
+    ...scope,
+    id: input.attemptId,
+  });
+  const parsed = (() => {
+    try {
+      return Attempt.safeParse(JSON.parse(decryptEnvironmentValue(key, encrypted!)));
+    } catch {
+      return { success: false as const };
+    }
+  })();
+  if (!parsed.success)
+    throw new HTTPException(410, {
+      message: "Claude sign-in expired or was already used. Start again.",
+    });
+  const attempt = parsed.data;
+  if (
+    attempt.accountId !== scope.accountId ||
+    attempt.workspaceId !== scope.workspaceId ||
+    attempt.actorSubjectId !== scope.actorSubjectId ||
+    !same(attempt.browserSessionHash, scope.browserSessionHash)
+  )
+    throw new HTTPException(403, {
+      message: "Complete Claude sign-in in the browser where you started it.",
+    });
+  await reauthorize(attempt.poolScope);
+  const current = attempt.credentialId ? await target(deps, scope, attempt.credentialId) : null;
+  if (
+    attempt.credentialId &&
+    (!current ||
+      current.account.version !== attempt.credentialVersion ||
+      current.account.scope !== attempt.poolScope ||
+      JSON.stringify(current.authoritySnapshot) !== JSON.stringify(attempt.authoritySnapshot))
+  )
+    throw changed();
+  if (attempt.stage === "complete")
+    return ClaudeSubscriptionOAuthCompleteResponse.parse({
+      connected: true,
+      accountId: attempt.credentialId,
+      scope: attempt.poolScope,
+      credentialVersion: attempt.credentialVersion,
+    });
+  const parts = input.code.trim().split("#");
+  if (parts.length !== 2 || !parts[0] || !same(parts[1]!, attempt.state))
+    throw new HTTPException(422, {
+      message: "Copy the full authorization code from the Claude page.",
+    });
+  if (
+    !(await consumeIntegrationOAuthPendingState(deps.db, {
+      ...scope,
+      id: input.attemptId,
+      stateEncrypted: encrypted!,
+    }))
+  )
+    throw new HTTPException(410, {
+      message: "Claude sign-in expired or was already used. Start again.",
+    });
+  let tokens: z.infer<typeof Tokens>;
+  try {
+    const signal = AbortSignal.timeout(30_000);
+    const response = await fetchImpl(CLAUDE_OAUTH_TOKEN_URL, {
+      method: "POST",
+      redirect: "error",
+      signal,
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        grant_type: "authorization_code",
+        client_id: CLAUDE_OAUTH_CLIENT_ID,
+        redirect_uri: CLAUDE_OAUTH_REDIRECT_URL,
+        code: parts[0],
+        code_verifier: attempt.verifier,
+        state: attempt.state,
+      }),
+    });
+    if (!response.ok) {
+      await response.body?.cancel().catch(() => undefined);
+      throw new Error("Token exchange refused");
+    }
+    tokens = Tokens.parse(
+      await readResponseJsonBounded(response, 64 * 1024, "Claude sign-in", { signal }),
+    );
+    if (!CLAUDE_OAUTH_SCOPES.every((required) => tokens.scope.split(/\s+/).includes(required)))
+      throw new Error("Required scopes missing");
+  } catch {
+    throw new HTTPException(502, {
+      message: "Claude sign-in could not be completed. Start sign-in again.",
+    });
+  }
+  const scopes = tokens.scope.split(/\s+/).filter(Boolean);
+  const direct = parseClaudeSubscriptionProfile({
+    account: tokens.account,
+    organization: tokens.organization,
+  });
+  const profile = await fetchClaudeSubscriptionProfile(tokens.access_token, scopes, fetchImpl);
+  if (tokens.account && profile && tokens.account.uuid !== profile.accountUuid)
+    throw new HTTPException(502, {
+      message: "Claude returned inconsistent account details. Start sign-in again.",
+    });
+  const accountUuid = tokens.account?.uuid ?? profile?.accountUuid ?? "";
+  if (
+    current?.account.providerAccountId &&
+    !/^(setup|oauth):/.test(current.account.providerAccountId) &&
+    current.account.providerAccountId !== accountUuid
+  )
+    throw new HTTPException(409, {
+      message:
+        "Sign in to the same Claude account to reconnect. Use Add account for a different subscription.",
+    });
+  await reauthorize(attempt.poolScope);
+  const expiresAt = new Date(Date.now() + tokens.expires_in * 1000);
+  const bundle = ClaudeSubscriptionCredential.parse({
+    ...JSON.parse(
+      prepareClaudeSubscriptionCredential(
+        deps.settings,
+        scope.workspaceId ? "workspace:" + scope.workspaceId : "organization:" + scope.accountId,
+        tokens.access_token,
+      ),
+    ),
+    identity: {
+      accountUuid,
+      deviceId: createHmac("sha256", key)
+        .update("claude-device:" + (scope.workspaceId ?? scope.accountId))
+        .digest("hex"),
+    },
+    oauth: { refreshToken: tokens.refresh_token, expiresAt: expiresAt.toISOString(), scopes },
+  });
+  const providerAccountId =
+    accountUuid || "oauth:" + createHmac("sha256", key).update(tokens.access_token).digest("hex");
+  const details = {
+    encryptionKey: key,
+    secret: bundle,
+    providerAccountId,
+    accountEmail: profile?.email ?? direct?.email ?? null,
+    planType: profile?.plan ?? direct?.plan ?? null,
+    expiresAt,
+    label: current?.account.label ?? null,
+  };
+  const saved = await withRlsContext(deps.db, scope, async (tx) => {
+    const connected = scope.workspaceId
+      ? await upsertClaudeSubscriptionAccount(tx, {
+          ...details,
+          accountId: scope.accountId,
+          workspaceId: scope.workspaceId,
+          subjectId: scope.actorSubjectId,
+          scope: attempt.poolScope as "workspace" | "user",
+          ...(attempt.credentialId
+            ? {
+                credentialId: attempt.credentialId,
+                expectedCredentialVersion: attempt.credentialVersion,
+                expectedProviderAccountId: current!.account.providerAccountId,
+                authoritySnapshot: attempt.authoritySnapshot!,
+              }
+            : {}),
+        })
+      : await upsertOrganizationClaudeSubscription(tx, {
+          ...details,
+          organizationId: scope.accountId,
+          actorSubjectId: scope.actorSubjectId,
+          ...(attempt.credentialId
+            ? {
+                credentialId: attempt.credentialId,
+                expectedCredentialVersion: attempt.credentialVersion,
+                expectedProviderAccountId: current!.account.providerAccountId,
+              }
+            : {}),
+        });
+    const authoritySnapshot =
+      "authoritySnapshot" in connected
+        ? connected.authoritySnapshot
+        : ({ version: 1, scope: "organization" } as const);
+    if (scope.workspaceId)
+      await setInitialActiveClaudeCredential(tx, {
+        accountId: scope.accountId,
+        workspaceId: scope.workspaceId,
+        subjectId: scope.actorSubjectId,
+        credentialId: connected.account.id,
+        authoritySnapshot,
+      });
+    await storeIntegrationOAuthPendingState(tx, {
+      ...scope,
+      id: input.attemptId,
+      expiresAt: new Date(Date.now() + 10 * 60_000),
+      stateEncrypted: encryptEnvironmentValue(
+        key,
+        JSON.stringify({
+          purpose: "claude-subscription-oauth",
+          ...scope,
+          stage: "complete",
+          poolScope: attempt.poolScope,
+          credentialId: connected.account.id,
+          credentialVersion: connected.account.version,
+          authoritySnapshot,
+        }),
+      ),
+    });
+    return connected.account;
+  }).catch(claudeAccountMutationFailure);
+  if (scope.workspaceId)
+    await wakeClaudeCapacityWaiters(deps.db, {
+      workspaceId: scope.workspaceId,
+      subjectId: scope.actorSubjectId,
+      authoritySnapshot:
+        attempt.poolScope === "workspace"
+          ? { version: 1, scope: "workspace" }
+          : (await target(deps, scope, saved.id))!.authoritySnapshot,
+      reason: "claude_account_connected",
+    });
+  return ClaudeSubscriptionOAuthCompleteResponse.parse({
+    connected: true,
+    accountId: saved.id,
+    scope: attempt.poolScope,
+    credentialVersion: saved.version,
+  });
+}

package/src/claude-subscription-profile.ts

@@ -0,0 +1,73 @@
+import { readResponseJsonBounded } from "@opengeni/network";
+import { z } from "zod";
+
+const Account = z
+  .object({
+    uuid: z.string().uuid(),
+    email: z.string().trim().email().max(320).optional(),
+    email_address: z.string().trim().email().max(320).optional(),
+    has_claude_max: z.boolean().optional(),
+    has_claude_pro: z.boolean().optional(),
+  })
+  .passthrough();
+const Profile = z
+  .object({
+    account: Account,
+    organization: z
+      .object({
+        organization_type: z.string().trim().min(1).max(128).optional(),
+      })
+      .passthrough()
+      .optional(),
+  })
+  .passthrough();
+
+export type ClaudeSubscriptionProfile = {
+  accountUuid: string;
+  email: string | null;
+  plan: string | null;
+};
+
+/** Only provider-reported identity; never derive email from a token or an organization name. */
+export function parseClaudeSubscriptionProfile(value: unknown): ClaudeSubscriptionProfile | null {
+  const parsed = Profile.safeParse(value);
+  if (!parsed.success) return null;
+  const { account, organization } = parsed.data;
+  return {
+    accountUuid: account.uuid,
+    email: account.email ?? account.email_address ?? null,
+    plan:
+      organization?.organization_type ??
+      (account.has_claude_max === true
+        ? "claude_max"
+        : account.has_claude_pro === true
+          ? "claude_pro"
+          : null),
+  };
+}
+
+/** Optional profile read. A profile outage must not discard a valid sign-in. */
+export async function fetchClaudeSubscriptionProfile(
+  token: string,
+  scopes: readonly string[],
+  fetchImpl: typeof fetch = globalThis.fetch,
+): Promise<ClaudeSubscriptionProfile | null> {
+  if (!scopes.includes("user:profile")) return null;
+  try {
+    const signal = AbortSignal.timeout(10_000);
+    const response = await fetchImpl("https://api.anthropic.com/api/oauth/profile", {
+      headers: { authorization: `Bearer ${token}`, accept: "application/json" },
+      redirect: "error",
+      signal,
+    });
+    if (!response.ok) {
+      await response.body?.cancel().catch(() => undefined);
+      return null;
+    }
+    return parseClaudeSubscriptionProfile(
+      await readResponseJsonBounded(response, 64 * 1024, "Claude profile", { signal }),
+    );
+  } catch {
+    return null;
+  }
+}

package/src/claude-subscription-usage.ts

@@ -0,0 +1,97 @@
+import { parseClaudeUsageResponse, type Settings } from "@opengeni/config";
+import { emptyClaudeUsage } from "@opengeni/config";
+import type { ClaudeSubscriptionUsage } from "@opengeni/contracts";
+import {
+  resolveClaudeSubscriptionCredential,
+  ClaudeSubscriptionConnectionChanged,
+  ClaudeSubscriptionRefreshUnavailable,
+  recordClaudeSubscriptionUsage,
+  type ClaudeUsageScope,
+  type Database,
+} from "@opengeni/db";
+import { readResponseJsonBounded } from "@opengeni/network";
+import { HTTPException } from "hono/http-exception";
+
+export async function requestClaudeUsage(
+  token: string,
+  fetchImpl: typeof fetch = globalThis.fetch,
+) {
+  const checkedAt = new Date().toISOString();
+  let status: ClaudeSubscriptionUsage["refreshStatus"] = "unavailable";
+  let observation: ReturnType<typeof parseClaudeUsageResponse> = null;
+  try {
+    const signal = AbortSignal.timeout(10_000);
+    const response = await fetchImpl("https://api.anthropic.com/api/oauth/usage", {
+      headers: {
+        authorization: `Bearer ${token}`,
+        "content-type": "application/json",
+        "cache-control": "no-cache",
+      },
+      redirect: "error",
+      signal,
+    });
+    if (response.ok || response.status === 403) {
+      const body = await readResponseJsonBounded<unknown>(response, 64 * 1024, "Claude usage", {
+        signal,
+      });
+      if (response.ok) {
+        observation = parseClaudeUsageResponse(body, new Date(checkedAt));
+        status = observation ? "available" : "unavailable";
+      } else {
+        const error = body && typeof body === "object" && "error" in body ? body.error : null;
+        const message =
+          error && typeof error === "object" && "message" in error ? error.message : null;
+        status =
+          typeof message === "string" &&
+          message.includes("scope requirement") &&
+          message.includes("user:profile")
+            ? "scope_required"
+            : "unavailable";
+      }
+    } else {
+      status = response.status === 401 ? "reconnect" : "unavailable";
+      await response.body?.cancel().catch(() => undefined);
+    }
+  } catch {
+    // Retain the last provider observation; never imply an unavailable quota is zero.
+  }
+
+  return { status, observation, checkedAt };
+}
+
+/** No inference calls. Inference-only setup tokens retain their response-header cache. */
+export async function refreshClaudeSubscriptionUsage(
+  db: Database,
+  settings: Settings,
+  scope: ClaudeUsageScope,
+  fetchImpl: typeof fetch = globalThis.fetch,
+) {
+  const credential = await resolveClaudeSubscriptionCredential(db, settings, scope, {
+    fetchImpl,
+  }).catch((error) => {
+    if (error instanceof ClaudeSubscriptionConnectionChanged)
+      throw new HTTPException(409, { message: error.message });
+    if (error instanceof ClaudeSubscriptionRefreshUnavailable)
+      throw new HTTPException(503, { message: error.message });
+    throw error;
+  });
+  if (!credential) return emptyClaudeUsage(null);
+  if ("reconnectRequired" in credential) return credential.usage;
+  const current = credential.usage;
+  if (
+    current.refreshStatus === "scope_required" ||
+    (current.refreshCheckedAt && Date.now() - Date.parse(current.refreshCheckedAt) < 30_000)
+  )
+    return current;
+  const { status, observation, checkedAt } = await requestClaudeUsage(credential.token, fetchImpl);
+  const result = await recordClaudeSubscriptionUsage(db, settings, scope, {
+    token: credential.token,
+    expectedConnectionId: credential.connectionId,
+    expectedCredentialVersion: credential.credentialVersion,
+    ...(observation ? { observation } : {}),
+    refresh: { status, checkedAt },
+  });
+  if (!result)
+    throw new HTTPException(409, { message: "Claude connection changed; reload usage." });
+  return result;
+}

package/src/claude-workspace-connection.ts

@@ -0,0 +1,82 @@
+import { createHmac } from "node:crypto";
+import { requireEnvironmentEncryption } from "@opengeni/core";
+import { ClaudeSubscriptionCredential, type Settings } from "@opengeni/config";
+import { HTTPException } from "hono/http-exception";
+
+/** Validate the canonical model lane before it bypasses integration acquisition. */
+export function assertClaudeWorkspaceCredential(
+  settings: Pick<Settings, "claudeSubscriptionEnabled">,
+  input: {
+    subjectId: string | null;
+    providerDomain: string;
+    kind: string;
+    metadata?: Record<string, unknown>;
+    credential: unknown;
+  },
+): void {
+  const role = input.metadata?.credentialRole;
+  if (role !== "anthropic" && role !== "claude_subscription") return;
+  if (role === "claude_subscription" && !settings.claudeSubscriptionEnabled)
+    throw new HTTPException(404, { message: "Claude subscriptions are not enabled" });
+  if (role === "claude_subscription")
+    throw new HTTPException(410, { message: "Use individual Claude subscription accounts." });
+  if (
+    input.subjectId !== null ||
+    input.providerDomain !== "api.anthropic.com" ||
+    input.kind !== "api_key"
+  )
+    throw new HTTPException(422, {
+      message: "Claude model connections must belong to this workspace",
+    });
+  const credential = input.credential;
+  const key =
+    credential && typeof credential === "object" && "apiKey" in credential
+      ? credential.apiKey
+      : null;
+  if (typeof key !== "string")
+    throw new HTTPException(422, { message: "Claude connection credential is required" });
+  if (role === "anthropic") {
+    if (!/^sk-ant-api[0-9]+-\S+$/.test(key))
+      throw new HTTPException(422, {
+        message: "Enter an Anthropic API key. Use Claude subscription for setup tokens.",
+      });
+    return;
+  }
+}
+
+/** Stable installation identity; setup tokens do not grant profile access. */
+export function prepareClaudeSubscriptionCredential(
+  settings: Settings,
+  scope: string,
+  token: string,
+  identity?: { accountUuid: string; deviceId: string },
+): string {
+  if (!settings.claudeSubscriptionEnabled)
+    throw new HTTPException(404, { message: "Claude subscriptions are not enabled" });
+  if (!/^sk-ant-oat[0-9]+-\S+$/.test(token))
+    throw new HTTPException(422, { message: "Enter the setup token from claude setup-token." });
+  return JSON.stringify(
+    ClaudeSubscriptionCredential.parse({
+      version: 1,
+      token,
+      identity: identity ?? {
+        accountUuid: "",
+        deviceId: createHmac("sha256", requireEnvironmentEncryption(settings))
+          .update("claude-device:" + scope)
+          .digest("hex"),
+      },
+    }),
+  );
+}
+
+export function prepareClaudeWorkspaceCredential(
+  settings: Settings,
+  workspaceId: string,
+  metadata: Record<string, unknown> | undefined,
+  credential: Record<string, unknown>,
+): Record<string, unknown> {
+  if (metadata?.credentialRole !== "claude_subscription") return credential;
+  if (!settings.claudeSubscriptionEnabled)
+    throw new HTTPException(404, { message: "Claude subscriptions are not enabled" });
+  throw new HTTPException(410, { message: "Use individual Claude subscription accounts." });
+}