@opengeni/api-router 0.30.3 → 1.0.0

package/src/auth/signup-funnel-metrics.ts

@@ -0,0 +1,164 @@
+import {
+  SIGNUP_ACQUISITION_SOURCES,
+  signupAcquisitionSource,
+  type SignupAcquisitionSource,
+} from "@opengeni/contracts";
+import type { Observability } from "@opengeni/observability";
+import { getOAuthState } from "better-auth/api";
+
+import {
+  currentManagedAuthProviderId,
+  shouldDiscardCurrentManagedAuthProviderSession,
+} from "./managed-auth-attempt-context";
+
+/**
+ * Content-free sign-up funnel counters. Every label is a closed set: no user,
+ * email, organization, workspace, or campaign value ever becomes a label.
+ */
+export const AUTH_FUNNEL_EVENTS = ["sign_up", "email_verified", "sign_in"] as const;
+export type AuthFunnelEvent = (typeof AUTH_FUNNEL_EVENTS)[number];
+export const AUTH_FUNNEL_METHODS = ["email", "google", "github", "other"] as const;
+export type AuthFunnelMethod = (typeof AUTH_FUNNEL_METHODS)[number];
+export const ORGANIZATION_SETUP_OUTCOMES = ["created", "failed"] as const;
+export type OrganizationSetupOutcome = (typeof ORGANIZATION_SETUP_OUTCOMES)[number];
+
+const AUTH_EVENTS_METRIC = {
+  name: "opengeni_auth_events_total",
+  help: "Managed authentication funnel events (sign-up, email verification, sign-in) by closed method.",
+} as const;
+const ORGANIZATION_SETUP_METRIC = {
+  name: "opengeni_organization_setup_total",
+  help: "Self-service post-sign-in organization setup outcomes.",
+} as const;
+const SIGNUP_ACQUISITION_METRIC = {
+  name: "opengeni_signup_acquisition_total",
+  help: "New managed users by normalized first-touch acquisition source.",
+} as const;
+
+/** The only observability surface funnel telemetry uses. */
+export type SignupFunnelObservability = Pick<Observability, "incrementCounter">;
+
+/** Better Auth request-body / OAuth-state key that carries first-touch attribution. */
+export const SIGNUP_ATTRIBUTION_AUTH_FIELD = "opengeniAttribution";
+
+export type SignupFunnelMetrics = {
+  /** A managed auth user was created (Better Auth `user.create.after`). */
+  recordSignUp(authContext: unknown): Promise<void>;
+  /** A managed user verified their email address. */
+  recordEmailVerified(): void;
+  /**
+   * A provider session was created that is not an internally discarded one.
+   * In the legacy session-set mode this includes the session the first
+   * successful email-verification click creates: that is the new user's first
+   * sign-in, so it is counted rather than folded into `email_verified`.
+   */
+  recordSignIn(): void;
+};
+
+export function authFunnelMethod(providerId: string | null | undefined): AuthFunnelMethod {
+  if (providerId === "credential") return "email";
+  if (providerId === "google" || providerId === "github") return providerId;
+  return "other";
+}
+
+/**
+ * Publish every closed series at zero so dashboards and alerts can tell a quiet
+ * funnel from missing instrumentation. Never throws: a metric-registry failure
+ * must not stop managed auth (and with it API startup) from composing.
+ */
+export function registerSignupFunnelMetricBaselines(
+  observability: SignupFunnelObservability,
+): void {
+  const baseline = (
+    metric: { name: string; help: string },
+    labels: Record<string, string>,
+  ): void => {
+    try {
+      observability.incrementCounter({ ...metric, labels, amount: 0 });
+    } catch {
+      // Telemetry only; the series appears on its first real increment.
+    }
+  };
+  for (const event of AUTH_FUNNEL_EVENTS) {
+    for (const method of AUTH_FUNNEL_METHODS) baseline(AUTH_EVENTS_METRIC, { event, method });
+  }
+  for (const outcome of ORGANIZATION_SETUP_OUTCOMES) {
+    baseline(ORGANIZATION_SETUP_METRIC, { outcome });
+  }
+  for (const source of SIGNUP_ACQUISITION_SOURCES) baseline(SIGNUP_ACQUISITION_METRIC, { source });
+}
+
+export function createSignupFunnelMetrics(
+  observability: SignupFunnelObservability,
+): SignupFunnelMetrics {
+  registerSignupFunnelMetricBaselines(observability);
+  const authEvent = (event: AuthFunnelEvent, method: AuthFunnelMethod) => {
+    observability.incrementCounter({ ...AUTH_EVENTS_METRIC, labels: { event, method } });
+  };
+  return {
+    recordSignUp: async (authContext) => {
+      try {
+        authEvent("sign_up", authFunnelMethod(currentManagedAuthProviderId()));
+        const source: SignupAcquisitionSource = signupAcquisitionSource(
+          await signupAttributionFromAuthContext(authContext),
+        );
+        observability.incrementCounter({ ...SIGNUP_ACQUISITION_METRIC, labels: { source } });
+      } catch {
+        // Funnel telemetry must never fail account creation.
+      }
+    },
+    recordEmailVerified: () => {
+      try {
+        authEvent("email_verified", "email");
+      } catch {
+        /* Telemetry only. */
+      }
+    },
+    recordSignIn: () => {
+      try {
+        // Session-set mode discards the provider session of a non-callback
+        // Better Auth call; the product transaction then creates the real one.
+        if (shouldDiscardCurrentManagedAuthProviderSession()) return;
+        authEvent("sign_in", authFunnelMethod(currentManagedAuthProviderId()));
+      } catch {
+        /* Telemetry only. */
+      }
+    },
+  };
+}
+
+/** Count one self-service organization setup request outcome. */
+export function recordOrganizationSetupOutcome(
+  observability: SignupFunnelObservability | undefined,
+  outcome: OrganizationSetupOutcome,
+): void {
+  try {
+    observability?.incrementCounter({ ...ORGANIZATION_SETUP_METRIC, labels: { outcome } });
+  } catch {
+    // Telemetry must never change the setup response.
+  }
+}
+
+/**
+ * Read untrusted first-touch attribution from the Better Auth endpoint that is
+ * creating the user: the email sign-up body, or the server-side OAuth state
+ * (`additionalData`) that the social start stored for its callback.
+ */
+export async function signupAttributionFromAuthContext(authContext: unknown): Promise<unknown> {
+  const body =
+    authContext && typeof authContext === "object"
+      ? (authContext as { body?: unknown }).body
+      : undefined;
+  if (body && typeof body === "object" && SIGNUP_ATTRIBUTION_AUTH_FIELD in body) {
+    return (body as Record<string, unknown>)[SIGNUP_ATTRIBUTION_AUTH_FIELD];
+  }
+  try {
+    const state: unknown = await getOAuthState();
+    if (state && typeof state === "object" && SIGNUP_ATTRIBUTION_AUTH_FIELD in state) {
+      return (state as Record<string, unknown>)[SIGNUP_ATTRIBUTION_AUTH_FIELD];
+    }
+  } catch {
+    // Not inside a Better Auth OAuth callback.
+  }
+  return undefined;
+}

package/src/browser-controller-authority.ts

@@ -1,186 +1 @@
-import { createHmac } from "node:crypto";
-import type {
-  InteractionPlacement,
-  NetworkRouteConfiguration,
-  NetworkRouteConsistency,
-} from "@opengeni/contracts";
-
-type BrowserControllerAuthorityScope = {
-  rootSecret: string;
-  accountId: string;
-  workspaceId: string;
-  placement: InteractionPlacement;
-  placementInstanceId: string;
-};
-
-type BrowserSessionAuthorityScope = BrowserControllerAuthorityScope & {
-  browserSessionId: string;
-  controllerGeneration: string;
-  tokenGeneration: number;
-};
-
-type ComputerSessionAuthorityScope = BrowserControllerAuthorityScope & {
-  computerSessionId: string;
-  controllerGeneration: string;
-  tokenGeneration: number;
-};
-
-/** Stable placement-admin authority. This token is installed owner-only inside
- * the exact placement and is never persisted or returned by the public API. */
-export function deriveBrowserControllerAdminToken(scope: BrowserControllerAuthorityScope): string {
-  return derive(scope.rootSecret, "placement-admin.v1", [
-    scope.accountId,
-    scope.workspaceId,
-    placementKey(scope.placement),
-    scope.placementInstanceId,
-  ]);
-}
-
-/** Deterministic controller credentials. The durable generations are the only
- * stored authority; plaintext tokens can be reconstructed only by API replicas
- * holding the deployment HMAC root. */
-export function deriveBrowserSessionControllerTokens(scope: BrowserSessionAuthorityScope): {
-  controlToken: string;
-  viewToken: string;
-} {
-  const fields = [
-    scope.accountId,
-    scope.workspaceId,
-    placementKey(scope.placement),
-    scope.placementInstanceId,
-    scope.browserSessionId,
-    scope.controllerGeneration,
-    scope.tokenGeneration,
-  ] as const;
-  return {
-    controlToken: derive(scope.rootSecret, "session-control.v1", fields),
-    viewToken: derive(scope.rootSecret, "session-view.v1", fields),
-  };
-}
-
-/** Secret-safe durable identity for one exact route launch. The digest binds
- * the route snapshot and proxy credential without making a password-verifier
- * hash available to database readers. */
-export function deriveBrowserNetworkRouteAuthorityDigest(scope: {
-  rootSecret: string;
-  accountId: string;
-  workspaceId: string;
-  browserSessionId: string;
-  routeId: string;
-  routeVersion: number;
-  credentialVersion: number | null;
-  configuration: NetworkRouteConfiguration;
-  consistency: NetworkRouteConsistency;
-  proxyCredential: { username: string; password: string } | null;
-}): string {
-  return derive(scope.rootSecret, "network-route-launch.v1", [
-    scope.accountId,
-    scope.workspaceId,
-    scope.browserSessionId,
-    scope.routeId,
-    scope.routeVersion,
-    scope.credentialVersion ?? "none",
-    canonicalJson(scope.configuration),
-    canonicalJson(scope.consistency),
-    scope.proxyCredential?.username ?? "none",
-    scope.proxyCredential?.password ?? "none",
-  ]).replace(/^ogb\./u, "ogr.");
-}
-
-export function deriveBrowserViewGrantToken(
-  scope: BrowserSessionAuthorityScope & { grantId: string; expiresAt: string },
-): string {
-  return derive(scope.rootSecret, "frame-view-grant.v1", [
-    scope.accountId,
-    scope.workspaceId,
-    placementKey(scope.placement),
-    scope.placementInstanceId,
-    scope.browserSessionId,
-    scope.controllerGeneration,
-    scope.tokenGeneration,
-    scope.grantId,
-    scope.expiresAt,
-  ]);
-}
-
-/** ComputerSession credentials share the placement controller root while using
- * resource-specific domains. Browser and computer authority cannot collide. */
-export function deriveComputerSessionControllerTokens(scope: ComputerSessionAuthorityScope): {
-  controlToken: string;
-  viewToken: string;
-} {
-  const fields = [
-    scope.accountId,
-    scope.workspaceId,
-    placementKey(scope.placement),
-    scope.placementInstanceId,
-    scope.computerSessionId,
-    scope.controllerGeneration,
-    scope.tokenGeneration,
-  ] as const;
-  return {
-    controlToken: derive(scope.rootSecret, "computer-session-control.v1", fields),
-    viewToken: derive(scope.rootSecret, "computer-session-view.v1", fields),
-  };
-}
-
-export function deriveComputerViewGrantToken(
-  scope: ComputerSessionAuthorityScope & { grantId: string; expiresAt: string },
-): string {
-  return derive(scope.rootSecret, "computer-frame-view-grant.v1", [
-    scope.accountId,
-    scope.workspaceId,
-    placementKey(scope.placement),
-    scope.placementInstanceId,
-    scope.computerSessionId,
-    scope.controllerGeneration,
-    scope.tokenGeneration,
-    scope.grantId,
-    scope.expiresAt,
-  ]);
-}
-
-function derive(rootSecret: string, domain: string, fields: readonly (string | number)[]): string {
-  if (!rootSecret) throw new Error("browser controller authority root is unavailable");
-  const hmac = createHmac("sha256", rootSecret);
-  hmac.update("opengeni.browser-controller-authority\0", "utf8");
-  writeField(hmac, domain);
-  for (const field of fields) writeField(hmac, String(field));
-  return `ogb.${hmac.digest("base64url")}`;
-}
-
-function writeField(hmac: ReturnType<typeof createHmac>, value: string): void {
-  const bytes = Buffer.from(value, "utf8");
-  hmac.update(String(bytes.byteLength), "utf8");
-  hmac.update(":", "utf8");
-  hmac.update(bytes);
-}
-
-function canonicalJson(value: unknown): string {
-  return JSON.stringify(canonicalJsonValue(value));
-}
-
-function canonicalJsonValue(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(canonicalJsonValue);
-  if (value && typeof value === "object") {
-    return Object.fromEntries(
-      Object.entries(value as Record<string, unknown>)
-        .sort(([left], [right]) => left.localeCompare(right))
-        .map(([key, entry]) => [key, canonicalJsonValue(entry)]),
-    );
-  }
-  return value;
-}
-
-function placementKey(placement: InteractionPlacement): string {
-  switch (placement.kind) {
-    case "sandbox_group":
-      return `sandbox_group:${placement.sandboxGroupId}`;
-    case "connected_machine":
-      return `connected_machine:${placement.sandboxId}`;
-    case "attached_device":
-      return `attached_device:${placement.deviceId}`;
-    case "external_provider":
-      return `external_provider:${placement.providerId}:${placement.placementId}`;
-  }
-}
+export * from "@opengeni/interaction/browser-controller-authority";

package/src/browser-ephemeral.ts

@@ -0,0 +1,39 @@
+import { createHmac } from "node:crypto";
+import type { BrowserSession, CreateBrowserSessionRequest } from "@opengeni/contracts";
+import { BrowserControlUnsupportedError } from "@opengeni/runtime/sandbox";
+
+export function assertEphemeralBrowserCreateEnabled(
+  request: CreateBrowserSessionRequest,
+  enabled: boolean,
+): void {
+  if (request.storageMode === "ephemeral_context" && !enabled) {
+    throw new BrowserControlUnsupportedError(
+      "Ephemeral Chromium contexts are disabled by the operator",
+    );
+  }
+}
+
+/** Only persisted session identity and server-resolved physical placement enter
+ * this private controller partition. Public callers never supply a pool key. */
+export function ephemeralBrowserPartition(
+  session: BrowserSession,
+  placementInstanceId: string,
+  rootSecret: string,
+): string {
+  if (session.placement.kind !== "sandbox_group")
+    throw new BrowserControlUnsupportedError(
+      "Ephemeral contexts require a managed sandbox placement",
+    );
+  return createHmac("sha256", rootSecret)
+    .update(
+      JSON.stringify({
+        version: "ephemeral-chromium-headless-default-egress-v1",
+        accountId: session.accountId,
+        workspaceId: session.workspaceId,
+        ownerSubjectId: session.createdBySubjectId,
+        sandboxGroupId: session.placement.sandboxGroupId,
+        placementInstanceId,
+      }),
+    )
+    .digest("hex");
+}

package/src/browser-state-authority.ts

@@ -1,236 +1 @@
-import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes } from "node:crypto";
-import { BROWSER_PROFILE_ARTIFACT_FORMAT } from "@opengeni/contracts";
-
-const ROOT_KEY_BYTES = 32;
-const DATA_KEY_BYTES = 32;
-const IV_BYTES = 12;
-const TAG_BYTES = 16;
-const WRAPPED_PREFIX = "ogbk1";
-const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
-const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
-
-export type BrowserStateOperationScope = {
-  accountId: string;
-  workspaceId: string;
-  browserSessionId: string;
-  operationId: string;
-  objectKey: string;
-};
-
-export type BrowserStateArtifactScope = {
-  accountId: string;
-  workspaceId: string;
-  objectKey: string;
-  artifactDigest: string;
-  contentDigest: string;
-};
-
-/** Deterministic only within one idempotent publication operation. This lets a
- * control-plane retry present browserd with exactly the same secret authority
- * without storing a plaintext key or placing it in an operation row. */
-export function deriveBrowserStateDataKey(
-  rootKey: Uint8Array,
-  scopeInput: BrowserStateOperationScope,
-): Buffer {
-  const scope = operationScope(scopeInput);
-  return createHmac("sha256", root(rootKey))
-    .update("opengeni.browser-state.data-key.v1\0", "utf8")
-    .update(canonicalJson(scope), "utf8")
-    .digest();
-}
-
-/** Associated data for the encrypted profile object. It is reproducible from
- * durable non-secret artifact authority during restore. */
-export function browserStateArtifactAad(
-  scopeInput: Pick<BrowserStateArtifactScope, "accountId" | "workspaceId" | "objectKey">,
-): Buffer {
-  const scope = baseArtifactScope(scopeInput);
-  return Buffer.from(`opengeni.browser-state.artifact-aad.v1\0${canonicalJson(scope)}`, "utf8");
-}
-
-/** Wrap a 32-byte artifact data key under the operator-held root key. The
- * ciphertext is bound to workspace, object, and both integrity digests. */
-export function wrapBrowserStateDataKey(
-  rootKey: Uint8Array,
-  dataKeyInput: Uint8Array,
-  scopeInput: BrowserStateArtifactScope,
-): string {
-  const dataKey = exactKey(dataKeyInput, "browser state data key");
-  const scope = artifactScope(scopeInput);
-  const iv = randomBytes(IV_BYTES);
-  const wrappingKey = browserStateWrappingKey(rootKey, scope);
-  try {
-    const cipher = createCipheriv("aes-256-gcm", wrappingKey, iv);
-    cipher.setAAD(wrapAad(scope));
-    const ciphertext = Buffer.concat([cipher.update(dataKey), cipher.final()]);
-    const payload = Buffer.concat([ciphertext, cipher.getAuthTag()]);
-    return `${WRAPPED_PREFIX}:${iv.toString("base64")}:${payload.toString("base64")}`;
-  } finally {
-    wrappingKey.fill(0);
-  }
-}
-
-export function unwrapBrowserStateDataKey(
-  rootKey: Uint8Array,
-  wrapped: string,
-  scopeInput: BrowserStateArtifactScope,
-): Buffer {
-  const scope = artifactScope(scopeInput);
-  const parts = wrapped.split(":");
-  if (parts.length !== 3 || parts[0] !== WRAPPED_PREFIX) {
-    throw new Error("browser state data-key envelope is unsupported");
-  }
-  const iv = canonicalBase64(parts[1]!, IV_BYTES, "browser state data-key envelope");
-  const payload = canonicalBase64(
-    parts[2]!,
-    DATA_KEY_BYTES + TAG_BYTES,
-    "browser state data-key envelope",
-  );
-  const ciphertext = payload.subarray(0, DATA_KEY_BYTES);
-  const tag = payload.subarray(DATA_KEY_BYTES);
-  const wrappingKey = browserStateWrappingKey(rootKey, scope);
-  try {
-    const decipher = createDecipheriv("aes-256-gcm", wrappingKey, iv);
-    decipher.setAAD(wrapAad(scope));
-    decipher.setAuthTag(tag);
-    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
-  } catch {
-    throw new Error("browser state data-key decryption failed");
-  } finally {
-    wrappingKey.fill(0);
-  }
-}
-
-export function browserStateObjectKey(workspaceIdInput: string, operationIdInput: string): string {
-  const workspaceId = uuid(workspaceIdInput, "workspace id");
-  const operationId = uuid(operationIdInput, "browser state operation id");
-  return `workspaces/${workspaceId}/browser-state/revisions/${operationId}/chromium-profile.ogbs`;
-}
-
-export function browserStateManifestDigest(manifest: unknown): string {
-  return createHash("sha256").update(canonicalJson(manifest), "utf8").digest("hex");
-}
-
-function operationScope(input: BrowserStateOperationScope) {
-  const base = baseArtifactScope(input);
-  return {
-    ...base,
-    browserSessionId: uuid(input.browserSessionId, "browser session id"),
-    operationId: uuid(input.operationId, "browser state operation id"),
-  };
-}
-
-function artifactScope(input: BrowserStateArtifactScope) {
-  return {
-    ...baseArtifactScope(input),
-    artifactDigest: sha256(input.artifactDigest, "browser state artifact digest"),
-    contentDigest: sha256(input.contentDigest, "browser state content digest"),
-  };
-}
-
-function baseArtifactScope(
-  input: Pick<BrowserStateArtifactScope, "accountId" | "workspaceId" | "objectKey">,
-) {
-  const workspaceId = uuid(input.workspaceId, "workspace id");
-  const objectKey = browserStateObjectKeyValue(input.objectKey, workspaceId);
-  return {
-    version: 1,
-    accountId: uuid(input.accountId, "account id"),
-    workspaceId,
-    objectKey,
-    format: BROWSER_PROFILE_ARTIFACT_FORMAT,
-  };
-}
-
-function wrapAad(scope: ReturnType<typeof artifactScope>): Buffer {
-  return Buffer.from(`opengeni.browser-state.data-key-wrap.v1\0${canonicalJson(scope)}`, "utf8");
-}
-
-function browserStateWrappingKey(
-  rootKey: Uint8Array,
-  scope: ReturnType<typeof artifactScope>,
-): Buffer {
-  return createHmac("sha256", root(rootKey))
-    .update("opengeni.browser-state.wrapping-key.v1\0", "utf8")
-    .update(canonicalJson(scope), "utf8")
-    .digest();
-}
-
-function browserStateObjectKeyValue(value: string, workspaceId: string): string {
-  if (
-    typeof value !== "string" ||
-    Buffer.byteLength(value) > 2_048 ||
-    !new RegExp(
-      `^workspaces/${workspaceId}/browser-state/[A-Za-z0-9._=-]+(?:/[A-Za-z0-9._=-]+)*$`,
-      "u",
-    ).test(value)
-  ) {
-    throw new Error("browser state object key is invalid");
-  }
-  return value;
-}
-
-function root(value: Uint8Array): Buffer {
-  return exactKey(value, "browser state root key");
-}
-
-function exactKey(value: Uint8Array, label: string): Buffer {
-  if (!(value instanceof Uint8Array) || value.byteLength !== ROOT_KEY_BYTES) {
-    throw new Error(`${label} must be exactly ${ROOT_KEY_BYTES} bytes`);
-  }
-  return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
-}
-
-function uuid(value: string, label: string): string {
-  if (typeof value !== "string" || !UUID_PATTERN.test(value)) {
-    throw new Error(`${label} must be a UUID`);
-  }
-  return value.toLowerCase();
-}
-
-function sha256(value: string, label: string): string {
-  if (typeof value !== "string" || !SHA256_PATTERN.test(value)) {
-    throw new Error(`${label} is invalid`);
-  }
-  return value;
-}
-
-function canonicalBase64(value: string, length: number, label: string): Buffer {
-  if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(value)) {
-    throw new Error(`${label} is unsupported`);
-  }
-  const decoded = Buffer.from(value, "base64");
-  if (decoded.byteLength !== length || decoded.toString("base64") !== value) {
-    decoded.fill(0);
-    throw new Error(`${label} is unsupported`);
-  }
-  return decoded;
-}
-
-function canonicalJson(value: unknown): string {
-  return JSON.stringify(canonicalValue(value));
-}
-
-function canonicalValue(value: unknown): unknown {
-  if (
-    value === null ||
-    typeof value === "string" ||
-    typeof value === "boolean" ||
-    (typeof value === "number" && Number.isFinite(value))
-  ) {
-    return value;
-  }
-  if (Array.isArray(value)) return value.map(canonicalValue);
-  if (typeof value === "object") {
-    const input = value as Record<string, unknown>;
-    const output: Record<string, unknown> = {};
-    for (const key of Object.keys(input).sort()) {
-      if (input[key] === undefined) {
-        throw new Error("canonical JSON cannot contain undefined");
-      }
-      output[key] = canonicalValue(input[key]);
-    }
-    return output;
-  }
-  throw new Error("value cannot be represented as canonical JSON");
-}
+export * from "@opengeni/interaction/browser-state-authority";

package/src/claude-subscription-account-conflicts.ts

@@ -0,0 +1,12 @@
+import { nestedPostgresSqlState, SubscriptionAccountChangedError } from "@opengeni/db";
+import { HTTPException } from "hono/http-exception";
+
+export function claudeAccountMutationFailure(error: unknown): never {
+  if (error instanceof SubscriptionAccountChangedError)
+    throw new HTTPException(409, { message: error.message });
+  if (nestedPostgresSqlState(error) === "23505")
+    throw new HTTPException(409, {
+      message: "This Claude subscription is already connected to this pool.",
+    });
+  throw error;
+}

package/src/claude-subscription-account-usage.ts

@@ -0,0 +1,48 @@
+import { environmentsEncryptionKeyBytes, type Settings } from "@opengeni/config";
+import {
+  resolveClaudeAccountCredential,
+  recordClaudeAccountUsage,
+  ClaudeSubscriptionConnectionChanged,
+  ClaudeSubscriptionRefreshUnavailable,
+  type ClaudeAccountUsageAuthority,
+  type Database,
+} from "@opengeni/db";
+import { HTTPException } from "hono/http-exception";
+import { requestClaudeUsage } from "./claude-subscription-usage";
+
+/** Profile quota requests never run inference and never select a different account. */
+export async function refreshClaudeAccountUsage(
+  db: Database,
+  settings: Settings,
+  authority: ClaudeAccountUsageAuthority,
+  fetchImpl: typeof fetch = globalThis.fetch,
+) {
+  const credential = await resolveClaudeAccountCredential(db, settings, authority, {
+    fetchImpl,
+  }).catch((error) => {
+    if (error instanceof ClaudeSubscriptionRefreshUnavailable)
+      throw new HTTPException(503, { message: error.message, cause: error });
+    throw error;
+  });
+  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 result = credential.secret.oauth?.scopes.includes("user:profile")
+    ? await requestClaudeUsage(credential.secret.token, fetchImpl)
+    : { status: "scope_required" as const, observation: null, checkedAt: new Date().toISOString() };
+  const encryptionKey = environmentsEncryptionKeyBytes(settings);
+  if (!encryptionKey) throw new Error("Claude credential encryption is unavailable");
+  const usage = await recordClaudeAccountUsage(db, authority, {
+    encryptionKey,
+    token: credential.secret.token,
+    expectedCredentialVersion: credential.version,
+    ...(result.observation ? { observation: result.observation } : {}),
+    refresh: { status: result.status, checkedAt: result.checkedAt },
+  });
+  if (!usage) throw new ClaudeSubscriptionConnectionChanged();
+  return usage;
+}