Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

6.0 KB
Raw Blame
/**
 * CompositeCredentialProvider — tries a primary credential source, falls back
 * to a secondary one.
 *
 * Used for OAuth-or-API-key providers (Codex, Kimi): the OAuth half is primary,
 * the API-key half is the fallback. A `fallbackSignal` lets the primary opt into
 * a fallback by throwing a sentinel error message (Kimi throws
 * "OAuth_FALLBACK_TO_API_KEY" when its login is rejected). The composite falls
 * through only when its fallback half is available, and otherwise rethrows the
 * sentinel's `cause` — the primary's own terminal error.
 */

import type {
  CredentialProvider,
  ReadinessResult,
  RequestAuth,
  RequestAuthContext,
} from "./types.js";

/**
 * One half's readiness, whether or not it implements the tri-state.
 *
 * A half that does not is not wrong, only less informative: its `false` means
 * "absent", which is the answer the whole layer gave before.
 *
 * A half that THROWS is deliberately NOT caught here. The old `isAvailable` was
 * `primary || fallback`, so a throwing half aborted the whole composite and the
 * authority's catch turned it into `false`. Catching it here instead would let
 * the fallback answer for a primary that blew up — better-looking, and a real
 * routing change: a provider that reported unavailable would start reporting
 * available. The throw propagates, the authority reports `failed`, and `failed`
 * projects to `false` — the same boolean, with the reason now attached.
 */
async function readinessOf(
  provider: CredentialProvider,
  opts?: { allowOpPrompt?: boolean }
): Promise<ReadinessResult> {
  if (provider.describeReadiness) {
    return (await provider.describeReadiness(opts)) ?? { readiness: "absent" };
  }
  return { readiness: (await provider.isAvailable(opts)) ? "present" : "absent" };
}

export interface CompositeOptions {
  /**
   * If set, a primary `getRequestAuth()` that throws an error whose message
   * exactly equals this string falls through to the fallback. Any other error
   * is rethrown.
   */
  fallbackSignal?: string;
}

export class CompositeCredentialProvider implements CredentialProvider {
  readonly catalogName: string;
  private readonly primary: CredentialProvider;
  private readonly fallback: CredentialProvider;
  private readonly opts: CompositeOptions;

  constructor(
    catalogName: string,
    primary: CredentialProvider,
    fallback: CredentialProvider,
    opts: CompositeOptions = {}
  ) {
    this.catalogName = catalogName;
    this.primary = primary;
    this.fallback = fallback;
    this.opts = opts;
  }

  /**
   * Readiness for the pair, keeping a half's `failed` instead of flattening it.
   *
   * This method is not optional decoration. The fallback half is normally an
   * `ApiKeyCredentialProvider`, which is the ONLY place the keychain and
   * 1Password are consulted — so without forwarding, a denied handshake for
   * `kimi` or `openai-codex` would be reported by this composite as a clean
   * `absent`, and the tri-state would be dead on arrival for exactly the
   * subscription providers it exists to protect.
   *
   * `present` short-circuits on the primary, matching the old `||` exactly: a
   * broken fallback store is never consulted, and never downgrades a provider
   * whose OAuth credential already answered. `failed` beats `absent` because a
   * store that could not be asked has not established absence.
   */
  async describeReadiness(opts?: { allowOpPrompt?: boolean }): Promise<ReadinessResult> {
    const primary = await readinessOf(this.primary, opts);
    if (primary.readiness === "present") return primary;
    const fallback = await readinessOf(this.fallback, opts);
    if (fallback.readiness === "present") return fallback;
    if (fallback.readiness === "failed") return fallback;
    if (primary.readiness === "failed") return primary;
    return { readiness: "absent" };
  }

  /** Unchanged contract: the `=== "present"` projection of the above. */
  async isAvailable(opts?: { allowOpPrompt?: boolean }): Promise<boolean> {
    return (await this.describeReadiness(opts)).readiness === "present";
  }

  invalidate(): void {
    this.primary.invalidate?.();
    this.fallback.invalidate?.();
  }

  /**
   * Both arms return an artifact; NEITHER returns null.
   *
   * This is the fact consumers get wrong. The fallback below is normally an
   * `ApiKeyCredentialProvider`, whose `getRequestAuth` always returns an object —
   * `{headers:{Authorization:"Bearer …"}}` with a key, `{headers:{}}` without one.
   * So a caller that treats "I got something back" as "the primary signed" is
   * wrong on every fallback request. The only way this method throws is a primary
   * that is AVAILABLE and then fails with something other than `fallbackSignal`.
   *
   * The artifact is returned VERBATIM from whichever half produced it, so its
   * `arm` marker survives — that marker, not the return being non-null, is how a
   * caller learns which credential won.
   */
  async getRequestAuth(ctx: RequestAuthContext): Promise<RequestAuth> {
    if (await this.primary.isAvailable({ allowOpPrompt: ctx.allowOpPrompt })) {
      try {
        return await this.primary.getRequestAuth(ctx);
      } catch (e: any) {
        const signal = this.opts.fallbackSignal;
        if (signal && String(e?.message) === signal) {
          // Fall through ONLY to a fallback that has a credential of its own:
          // the api-key half always returns an artifact, so falling through
          // without asking sent an empty key (`x-api-key: ""`) and lost the
          // primary's message. With no key, the signal's cause (the primary's
          // own terminal error) is what the caller gets.
          if (await this.fallback.isAvailable({ allowOpPrompt: ctx.allowOpPrompt })) {
            return this.fallback.getRequestAuth(ctx);
          }
          throw e?.cause ?? e;
        }
        throw e;
      }
    }
    return this.fallback.getRequestAuth(ctx);
  }

  async login(): Promise<void> {
    await this.primary.login?.();
  }

  async logout(): Promise<void> {
    await this.primary.logout?.();
  }
}