cartethyia 2.7.9 → 2.8.0

package/src/providers/operations/provider-credential-service.ts

@@ -6,7 +6,7 @@ import { providerAccounts, providerOauthStates } from "../../persistence/schema"
 import { decryptCredentialToString } from "../../security/crypto";
 import { GatewayError } from "../../protocol/gateway-error";
 import type { OAuthRefreshService, OAuthTokenRefresher } from "../authentication/oauth-refresh-service";
-import { CredentialResolver, type CredentialAlternative } from "../provider-credential-resolver";
+import { CredentialResolver, type CredentialAlternative } from "../provider-credentials";
 import { parseProviderId, type CredentialKind } from "../provider-contracts";
 import type { ResolvedCredential } from "../provider-contracts";
 import { refreshLeadMs } from "./oauth-refresh-lead";
@@ -145,19 +145,59 @@ export interface AccountWithFreshness {
   readonly dueAt: number | undefined;
 }
 
+/** Columns every account+OAuth-state reader selects; narrower readers pick from it. */
+export interface AccountWithOauthStateRow {
+  readonly id: string;
+  readonly providerId: string;
+  readonly credentialKind: CredentialKind;
+  readonly credentialCiphertext: Buffer | null;
+  readonly refreshCiphertext: Buffer | null;
+  readonly authState: unknown;
+  readonly clientSecretCiphertext: Buffer | null;
+  readonly staticToken: boolean;
+}
+
+/** Which optional columns a reader wants on top of the shared base. */
+export interface LoadAccountWithOauthStateOptions {
+  /** Select `status` from providerAccounts. */
+  readonly includeStatus?: boolean;
+  /** Select `expiresAt` from providerOauthStates. */
+  readonly includeExpiry?: boolean;
+  /** Also compute the skew-adjusted OAuth due time (see `loadAccountWithFreshness`). */
+  readonly includeDueAt?: boolean;
+  /** Refresh lead override for the `dueAt` skew; defaults to `refreshLeadMs(providerId)`. */
+  readonly skewMs?: number;
+}
+
+/** One loaded account row plus whatever optional columns were requested. */
+export interface LoadedAccountWithOauthState {
+  readonly id: string;
+  readonly providerId: string;
+  readonly credentialKind: CredentialKind;
+  readonly credentialCiphertext: Buffer | null;
+  readonly refreshCiphertext: Buffer | null;
+  readonly authState: unknown;
+  readonly clientSecretCiphertext: Buffer | null;
+  readonly staticToken: boolean;
+  readonly status?: string;
+  readonly expiresAt?: Date | null;
+  readonly dueAt?: number;
+}
+
 /**
- * Loads an account and its optional OAuth state in one query.
+ * Shared account+OAuth-state loader behind every status/health reader.
  *
- * `dueAt` is the OAuth expiry minus the provider's refresh lead
- * (`refreshLeadMs(providerId)`), so a token becomes due at the point that
- * provider re-mints its own (Claude ~4h, Codex ~5 days, Antigravity ~5 min).
- * Non-OAuth accounts and accounts without OAuth state have no due time.
+ * Builds the same `select(...).from(providerAccounts)` with the conditional
+ * `leftJoin` on `providerOauthStates` (the memory/Postgres dialect guard), so
+ * a schema or dialect change is fixed once instead of in four copies. The
+ * `dueAt` skew logic lives here too; `loadAccountWithFreshness` is a thin
+ * wrapper that returns it beside the row.
  */
-export async function loadAccountWithFreshness(
+export async function loadAccountWithOauthState(
   db: CartethyiaDatabase,
   accountId: string,
-  skewMs?: number,
-): Promise<AccountWithFreshness | undefined> {
+  options: LoadAccountWithOauthStateOptions = {},
+): Promise<LoadedAccountWithOauthState | undefined> {
   const selectBuilder = db
     .select({
       id: providerAccounts.id,
@@ -167,8 +207,11 @@ export async function loadAccountWithFreshness(
       refreshCiphertext: providerOauthStates.refreshCiphertext,
       authState: providerAccounts.authState,
       clientSecretCiphertext: providerOauthStates.clientSecretCiphertext,
-      expiresAt: providerOauthStates.expiresAt,
       staticToken: providerAccounts.staticToken,
+      ...(options.includeStatus === true ? { status: providerAccounts.status } : {}),
+      ...(options.includeExpiry === true || options.includeDueAt === true
+        ? { expiresAt: providerOauthStates.expiresAt }
+        : {}),
     })
     .from(providerAccounts);
   const query = "leftJoin" in selectBuilder
@@ -180,35 +223,62 @@ export async function loadAccountWithFreshness(
   const rows = await query.where(eq(providerAccounts.id, accountId)).limit(1);
   const row = rows[0];
   if (!row) return undefined;
-  const lead = skewMs ?? refreshLeadMs(row.providerId);
+  if (options.includeDueAt !== true) return row;
+  const lead = options.skewMs ?? refreshLeadMs(row.providerId);
   // A refresh-capable OAuth account with no stored expiry is unknown-liveness:
-  // we have no evidence the access token still works. The old rule left
-  // `dueAt` undefined for these, so `resolveCredentialForAccount` skipped the
-  // refresh branch and dispatch sent the pasted token as-is. For a token that
-  // had already expired on another installation (a 9router/Omniroute import
-  // carrying `accessToken` + `refreshToken` + a past `expiresAt` that was
-  // dropped by validation, a hand-pasted OAuth bundle with no expiry field,
-  // or an upstream that stopped minting expiries) that produced the exact
-  // "re-authenticate" refusal the refresh grant exists to prevent. Marking the
-  // token due immediately refreshes it on first use; the sweep handles the
-  // normal case where `expires_at` is populated.
+  // we have no evidence the access token still works. Marking the token due
+  // immediately refreshes it on first use; the sweep handles the normal case
+  // where `expires_at` is populated.
   const hasRefreshGrant = row.refreshCiphertext != null;
   const kindOauth = row.credentialKind === "oauth";
   const unknownExpiryButRefreshable =
     kindOauth && !row.staticToken && hasRefreshGrant && row.expiresAt == null;
+  // A static token is never "due": it is used as issued and there is no
+  // refresh to run, so the dispatch path must not treat it as stale.
+  const dueAt =
+    row.staticToken
+      ? undefined
+      : row.expiresAt != null
+        ? row.expiresAt.getTime() - lead
+        : unknownExpiryButRefreshable
+          ? 0
+          : undefined;
   return {
-    row,
-    // A static token is never "due": it is used as issued and there is no
-    // refresh to run, so the dispatch path must not treat it as stale.
-    dueAt:
-      row.staticToken
-        ? undefined
-        : row.expiresAt != null
-          ? row.expiresAt.getTime() - lead
-          : unknownExpiryButRefreshable
-            ? 0
-            : undefined,
+    ...row,
+    ...(dueAt === undefined ? {} : { dueAt }),
+  };
+}
+
+/**
+ * Loads an account and its optional OAuth state in one query.
+ *
+ * `dueAt` is the OAuth expiry minus the provider's refresh lead
+ * (`refreshLeadMs(providerId)`), so a token becomes due at the point that
+ * provider re-mints its own (Claude ~4h, Codex ~5 days, Antigravity ~5 min).
+ * Non-OAuth accounts and accounts without OAuth state have no due time.
+ */
+export async function loadAccountWithFreshness(
+  db: CartethyiaDatabase,
+  accountId: string,
+  skewMs?: number,
+): Promise<AccountWithFreshness | undefined> {
+  const loaded = await loadAccountWithOauthState(db, accountId, {
+    includeDueAt: true,
+    ...(skewMs === undefined ? {} : { skewMs }),
+  });
+  if (!loaded) return undefined;
+  const row: AccountWithFreshnessRow = {
+    id: loaded.id,
+    providerId: loaded.providerId,
+    credentialKind: loaded.credentialKind,
+    credentialCiphertext: loaded.credentialCiphertext,
+    refreshCiphertext: loaded.refreshCiphertext,
+    authState: loaded.authState,
+    clientSecretCiphertext: loaded.clientSecretCiphertext,
+    expiresAt: loaded.expiresAt ?? null,
+    staticToken: loaded.staticToken,
   };
+  return { row, dueAt: loaded.dueAt };
 }
 
 /** OAuth refresh collaborators, injected by the composition root. */

package/src/providers/operations/provider-rules/github.ts

@@ -0,0 +1,48 @@
+import type {
+  AccountErrorRule,
+} from "../account-error-classification";
+
+/**
+ * Checks whether an upstream body indicates Copilot is not licensed.
+ * Copilot answers 401 for a bad credential and 403 for a
+ * license/entitlement refusal, so forbidden/unauthorized on this surface
+ * is the same verdict.
+ */
+export function copilotNotLicensed(lower: string): boolean {
+  return (
+    lower.includes("not licensed") ||
+    lower.includes("forbidden") ||
+    lower.includes("unauthorized") ||
+    lower.includes("license")
+  );
+}
+
+export const githubRules: readonly AccountErrorRule[] = [
+  {
+    // GitHub Copilot answers a license/entitlement refusal with 403 and
+    // "not licensed to use Copilot" / "forbidden" / "unauthorized". That is a
+    // verdict on the account: the subscription cannot serve this credential,
+    // and no amount of waiting or refreshing changes it. Cooldown cycling
+    // (auth_invalidated + 5m backoff) kept a dead account in rotation where a
+    // client's retry budget burned sibling accounts — the same failure the
+    // buddy ban exists to prevent. Disable immediately. Must run before
+    // `credential-rejected`, which would claim the bare 403 as a refreshable
+    // auth rejection.
+    name: "github-copilot-not-licensed",
+    match: (s) =>
+      s.origin === "upstream" &&
+      s.providerId === "github" &&
+      copilotNotLicensed(s.lower),
+    decide: (s) =>
+      s.result(
+        "policy_blocked_banned",
+        "disabled",
+        0,
+        null,
+        s.reason("GitHub Copilot account not licensed"),
+        // A license refusal is evidence about the account even at provider
+        // scope, for the same reason a named revocation or a buddy ban is.
+        true,
+      ),
+  },
+];

package/src/providers/operations/provider-rules/grok.ts

@@ -0,0 +1,33 @@
+import type { AccountErrorSignals } from "../account-error-classification";
+
+/**
+ * xAI Grok Build's free tier resets on a rolling 24-hour window, so its
+ * exhaustion is a full-day quota cooldown — never the generic 1h fallback,
+ * which let the account re-enter rotation inside the window.
+ */
+export const GROK_QUOTA_COOLDOWN_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Detects whether a quota failure belongs to Grok's free tier or spending limit.
+ */
+export function isGrokFreeTierExhaustion(s: AccountErrorSignals): boolean {
+  if (s.providerId !== undefined && s.providerId !== "grok") {
+    // If providerId is known and not grok, only match if the providerCode is explicitly grok subscription
+    if (!s.providerCode.startsWith("subscription:")) return false;
+  }
+  return (
+    s.providerCode === "subscription:free-usage-exhausted" ||
+    s.providerCode.startsWith("subscription:") ||
+    s.providerCode.includes("spending") ||
+    s.providerCode.includes("credits") ||
+    s.lower.includes("free-usage") ||
+    s.lower.includes("free usage") ||
+    s.lower.includes("included free usage") ||
+    s.lower.includes("rolling 24-hour") ||
+    s.lower.includes("rolling 24 hour") ||
+    s.lower.includes("spending limit") ||
+    s.lower.includes("out of credits") ||
+    s.lower.includes("run out of credits") ||
+    s.lower.includes("need a grok subscription")
+  );
+}

package/src/providers/operations/provider-rules/inception.ts

@@ -0,0 +1,49 @@
+import type {
+  AccountErrorRule,
+} from "../account-error-classification";
+
+/**
+ * Inception's per-minute limit window (1 minute).
+ *
+ * Inception's Free tier throttles per minute (1 000 requests / 1M input
+ * tokens / 100K output tokens) and the window resets every minute. The generic
+ * 15-minute rate-limit fallback would park a healthy key long after the window
+ * refilled; 1 minute is the provider's own cadence, hardcoded because it is a
+ * fact about the upstream, not a deployment knob.
+ */
+export const INCEPTION_RATE_LIMIT_COOLDOWN_MS = 60_000;
+
+export const inceptionRules: readonly AccountErrorRule[] = [
+  {
+    // Inception's Free tier throttles per minute (1 000 requests / 1M input
+    // tokens / 100K output tokens) and the window resets every minute. A
+    // generic 429 would cool the account for the 15-minute default, leaving a
+    // healthy key parked long after the window refilled — the source of
+    // "limitasiya lumayan keras". This arm must run before `rate-limit`: it
+    // matches the same signals and shortens the window to 1 minute so routing
+    // moves to the next account and the flagged one returns almost at once.
+    name: "inception-per-minute-limit",
+    match: (s) =>
+      s.origin === "upstream" &&
+      s.providerId === "inception" &&
+      (s.statusCode === 429 ||
+        s.providerCode === "rate_limit_reached" ||
+        s.providerCode === "rate_limit_exceeded" ||
+        s.lower.includes("rate_limit") ||
+        s.lower.includes("rate limit") ||
+        s.lower.includes("too many requests") ||
+        s.lower.includes("tokens per minute") ||
+        s.lower.includes("input token")),
+    decide: (s) => {
+      const cooldownMs = s.statedCooldownMs ?? INCEPTION_RATE_LIMIT_COOLDOWN_MS;
+      return s.result(
+        "rate_limit_transient",
+        "cooldown",
+        cooldownMs,
+        new Date(Date.now() + cooldownMs),
+        s.reason("Inception per-minute input-token limit"),
+        s.origin === "upstream",
+      );
+    },
+  },
+];

package/src/providers/operations/provider-rules/index.ts

@@ -0,0 +1,32 @@
+export {
+  TRAE_REGION_COOLDOWN_MS,
+  TRAE_QUOTA_COOLDOWN_MS,
+  traeRules,
+} from "./trae";
+
+export {
+  QODER_QUOTA_COOLDOWN_MS,
+  qoderPlanGatedRule,
+  qoderModelQuotaRule,
+  qoderRules,
+} from "./qoder";
+
+export {
+  githubRules,
+  copilotNotLicensed,
+} from "./github";
+
+export {
+  INCEPTION_RATE_LIMIT_COOLDOWN_MS,
+  inceptionRules,
+} from "./inception";
+
+export {
+  PERCH_TURN_RATE_LIMIT_COOLDOWN_MS,
+  perchRules,
+} from "./perch";
+
+export {
+  GROK_QUOTA_COOLDOWN_MS,
+  isGrokFreeTierExhaustion,
+} from "./grok";

package/src/providers/operations/provider-rules/perch.ts

@@ -0,0 +1,37 @@
+import type {
+  AccountErrorRule,
+} from "../account-error-classification";
+
+/**
+ * Perch's `turn_rate_limited` window. The upstream does not state a reset and
+ * answers the same on every ticket mint while the window is exhausted, so a
+ * day matches the practical cadence and stops the redial loop.
+ */
+export const PERCH_TURN_RATE_LIMIT_COOLDOWN_MS = 24 * 60 * 60 * 1000;
+
+export const perchRules: readonly AccountErrorRule[] = [
+  {
+    // Perch's `turn_rate_limited` is a per-turn API window, not a per-request
+    // 429: the account keeps answering but every call mints another ticket
+    // into the same exhausted window. The stated remedy ("contact us for
+    // direct API access") implies the window is long — park the account for a
+    // day so routing picks a sibling instead of hammering the same key.
+    name: "perch-turn-rate-limit",
+    match: (s) =>
+      s.origin === "upstream" &&
+      s.providerId === "perch" &&
+      (s.providerCode === "turn_rate_limited" ||
+        (s.statusCode === 429 && s.lower.includes("turn rate"))),
+    decide: (s) => {
+      const cooldownMs = s.statedCooldownMs ?? PERCH_TURN_RATE_LIMIT_COOLDOWN_MS;
+      return s.result(
+        "rate_limit_transient",
+        "cooldown",
+        cooldownMs,
+        new Date(Date.now() + cooldownMs),
+        s.reason("Perch turn rate limit"),
+        s.origin === "upstream",
+      );
+    },
+  },
+];

package/src/providers/operations/provider-rules/qoder.ts

@@ -0,0 +1,70 @@
+import type {
+  AccountErrorRule,
+  AccountErrorSignals,
+} from "../account-error-classification";
+import { unsupportedModelCooldownMs } from "../account-error-classification";
+
+/**
+ * Qoder's quota verdicts (`110` billing-daily-count, pricing-url refusals)
+ * are per-model: one model's spend cap does not drain another. A day matches
+ * the daily billing window the provider names.
+ */
+export const QODER_QUOTA_COOLDOWN_MS = 24 * 60 * 60 * 1000;
+
+function isQoder(signals: AccountErrorSignals): boolean {
+  return signals.providerId === "qoder" || signals.providerId === "qodercn";
+}
+
+/**
+ * Qoder's code-112 pricing refusal (`{"code":"112","message":"{\"pricingUrl\":...}"}`)
+ * is a "this model is not included in this account's plan, buy more" verdict
+ * for one pair — the account keeps serving its other models. The probe path
+ * does not always carry the code in its evidence (only the message does), so
+ * the match keys on the provider id plus the pricing-page wording as well.
+ * It must run before `quota-exhausted`, which would park the whole account.
+ */
+export const qoderPlanGatedRule: AccountErrorRule = {
+  name: "qoder-plan-gated",
+  match: (s) =>
+    isQoder(s) &&
+    (s.providerCode === "112" || s.lower.includes("pricingurl")),
+  decide: (s) => {
+    const cooldownMs = unsupportedModelCooldownMs(s.modelBlockHits);
+    return s.result(
+      "model_unreachable",
+      "cooldown",
+      cooldownMs,
+      new Date(Date.now() + cooldownMs),
+      s.reason("Model not included in this account's plan"),
+      s.origin === "upstream" && s.modelId !== undefined,
+      true,
+    );
+  },
+};
+
+/**
+ * Qoder's quota verdicts — `110` "Billing daily count exceeded" — are per-model:
+ * one model's spend cap does not drain another. Scoping them to the model keeps
+ * the account serving its other models. Must run before `quota-exhausted`, which
+ * parks the whole account.
+ */
+export const qoderModelQuotaRule: AccountErrorRule = {
+  name: "qoder-model-quota",
+  match: (s) => isQoder(s) && s.quotaSignal,
+  decide: (s) => {
+    const cooldownMs = s.statedCooldownMs ?? QODER_QUOTA_COOLDOWN_MS;
+    return s.result(
+      "model_unreachable",
+      "cooldown",
+      cooldownMs,
+      new Date(Date.now() + cooldownMs),
+      s.reason("Qoder quota exhausted for this model"),
+      s.origin === "upstream" && s.modelId !== undefined,
+    );
+  },
+};
+
+export const qoderRules: readonly AccountErrorRule[] = [
+  qoderPlanGatedRule,
+  qoderModelQuotaRule,
+];

package/src/providers/operations/provider-rules/trae.ts

@@ -0,0 +1,81 @@
+import type {
+  AccountErrorRule,
+  AccountErrorSignals,
+} from "../account-error-classification";
+
+/**
+ * Trae answers `4013 "AI service is not available in the current region now."`
+ * when the upstream does not serve the account's region. A day because the
+ * verdict is durable: it reproduces on every request until the region opens,
+ * and the account must not be re-dialled every thirty seconds for the whole
+ * window.
+ */
+export const TRAE_REGION_COOLDOWN_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Trae's free-tier quota (`4008` / "exceeded the quota") resets daily, so its
+ * exhaustion is a full-day model backoff — never the generic 1h fallback,
+ * which let the account re-enter rotation inside the window.
+ */
+export const TRAE_QUOTA_COOLDOWN_MS = 24 * 60 * 60 * 1000;
+
+function isTrae(signals: AccountErrorSignals): boolean {
+  return signals.providerId === "trae" || signals.providerId === "traecn";
+}
+
+export const traeRules: readonly AccountErrorRule[] = [
+  {
+    // Trae answers `4013 "AI service is not available in the current region
+    // now."` when the upstream does not serve the account's region. That is a
+    // durable verdict on the account, not a transient transport fault: it
+    // reproduces on every request until the region opens, so it must cool hard
+    // for a day rather than be re-dialled every thirty seconds. Must run
+    // before `transport-fault`, which would read the 502 as a short
+    // `server_error`.
+    name: "trae-region-unavailable",
+    match: (s) =>
+      isTrae(s) &&
+      (s.providerCode === "4013" || s.lower.includes("not available in the current region")),
+    decide: (s) => {
+      const cooldownMs = TRAE_REGION_COOLDOWN_MS;
+      return s.result(
+        "quota_exhausted",
+        "cooldown",
+        cooldownMs,
+        new Date(Date.now() + cooldownMs),
+        s.reason("Trae service unavailable in the current region"),
+        // Account-scoped provider evidence still has to reach the writer: a
+        // stream frame carries no credential detail, so `canMutate` is false
+        // and without this the account stays in rotation to reproduce the
+        // refusal for the whole window the region is closed for.
+        true,
+      );
+    },
+  },
+  {
+    // Trae's free-tier quota (`4008` / "exceeded the quota") resets daily.
+    // Treating it like the generic quota cooldown (1h account-wide fallback)
+    // let the account re-enter rotation inside the window and reproduce the
+    // refusal every few minutes — the "cooldown not holding" report. The
+    // verdict is a full-day backoff on *any* model (the account's quota is
+    // spent, so every model on it shares the wall). Scoped to the model so
+    // the account is not disabled wholesale; the 1-day window means a model
+    // stays parked for the day instead of flapping. Must run before
+    // `quota-exhausted`, which would apply the generic shorter fallback.
+    name: "trae-quota-exhausted",
+    match: (s) =>
+      isTrae(s) &&
+      (s.providerCode === "4008" || s.lower.includes("have exceeded the quota")),
+    decide: (s) => {
+      const cooldownMs = s.statedCooldownMs ?? TRAE_QUOTA_COOLDOWN_MS;
+      return s.result(
+        "model_unreachable",
+        "cooldown",
+        cooldownMs,
+        new Date(Date.now() + cooldownMs),
+        s.reason("Trae quota exhausted for this model"),
+        s.origin === "upstream" && s.modelId !== undefined,
+      );
+    },
+  },
+];

package/src/providers/provider-contracts.ts

@@ -8,7 +8,9 @@ import { BUNDLED_PROVIDER_METADATA, type BundledProviderId } from "./provider-me
 import type { ValidatedOutboundHttp2Bidi } from "../network/http2-bidi";
 
 /** Closed union of every shipped provider ID. */
-export const BUNDLED_PROVIDER_IDS = BUNDLED_PROVIDER_METADATA.map((definition) => definition.id) as readonly BundledProviderId[];
+export const BUNDLED_PROVIDER_IDS: ReadonlySet<BundledProviderId> = new Set(
+  BUNDLED_PROVIDER_METADATA.map((definition) => definition.id),
+);
 
 /** Normalized builtin or validated custom provider identifier. */
 declare const customProviderIdBrand: unique symbol;
@@ -451,7 +453,7 @@ function normalizeProviderSlug(id: string): string {
 /** Returns true for one of Cartethyia's reserved builtin IDs, case-insensitively. */
 export function isBundledProviderId(value: string): value is BundledProviderId {
   const normalized = value.trim().toLowerCase();
-  return (BUNDLED_PROVIDER_IDS as readonly string[]).includes(normalized);
+  return BUNDLED_PROVIDER_IDS.has(normalized as BundledProviderId);
 }
 
 /** Normalizes a provider identifier before persistence or registry lookup. */

package/src/providers/{provider-credential-resolver.ts → provider-credentials.ts}

@@ -1,10 +1,47 @@
-// Control-plane credential selection: picks the first usable upstream
-// credential alternative in operator order.
+/**
+ * Provider credential envelope and resolution handling.
+ *
+ * Strips token envelopes so adapters never emit `Bearer Bearer`, and resolves
+ * ordered upstream credential alternatives for the control plane.
+ */
 
 import { GatewayError } from "../protocol/gateway-error";
-import { unwrapProviderToken } from "./provider-credential-envelope";
 import type { CredentialKind, ProviderId, ResolvedCredential } from "./provider-contracts";
 
+/** Envelope labels a stored credential may carry. */
+export type TokenEnvelope = "bearer" | "oauth" | "provider";
+
+const ENVELOPE_PREFIXES: Record<TokenEnvelope, string> = {
+  bearer: "Bearer ",
+  oauth: "OAuth ",
+  provider: "provider:",
+};
+
+/**
+ * Removes one explicitly identified envelope so adapters never emit
+ * `Bearer Bearer`. The bearer branch strips case-insensitively with
+ * surrounding-whitespace normalization; oauth/provider envelopes keep their
+ * exact byte slices. Input without the identified envelope passes through
+ * untouched.
+ */
+export function unwrapProviderToken(
+  value: string | Uint8Array,
+  envelope?: TokenEnvelope,
+): Uint8Array {
+  const bytes = typeof value === "string" ? new TextEncoder().encode(value) : value;
+  const text = new TextDecoder().decode(bytes);
+  if (envelope === "bearer") {
+    const trimmed = text.trim();
+    const match = /^bearer\s+(.+)$/is.exec(trimmed);
+    return new TextEncoder().encode((match?.[1] ?? trimmed).trim());
+  }
+  const prefix = envelope === undefined ? undefined : ENVELOPE_PREFIXES[envelope];
+  if (prefix !== undefined && text.toLowerCase().startsWith(prefix.toLowerCase())) {
+    return new TextEncoder().encode(text.slice(prefix.length));
+  }
+  return new Uint8Array(bytes);
+}
+
 /** One control-plane credential alternative, ordered by operator preference. */
 export interface CredentialAlternative {
   readonly provider_id: ProviderId;