@cleocode/core 2026.6.13 → 2026.6.14

package/dist/llm/oauth/pkce.js

@@ -75,6 +75,53 @@ export function buildAuthorizationUrl(params) {
     }
     return url.toString();
 }
+// ---------------------------------------------------------------------------
+// Authorization-response input parsing
+// ---------------------------------------------------------------------------
+/**
+ * Parse a user-pasted authorization response into `{ code, state }`.
+ *
+ * Accepts every form a provider's callback page can hand the user
+ * (mirrors pi-ai's `parseAuthorizationInput`):
+ * - a full redirect URL — `https://…/callback?code=…&state=…`
+ * - the `code#state` pair Anthropic's hosted callback page displays
+ * - a bare query string — `code=…&state=…`
+ * - a bare authorization code
+ *
+ * Callers MUST validate a returned `state` against the authorize-time state
+ * (CSRF check, RFC 6749 §10.12) before exchanging the code.
+ *
+ * @param input - Raw pasted text from the user.
+ * @returns Extracted `code` and `state` (either may be `undefined`).
+ * @task T11958
+ */
+export function parseAuthorizationInput(input) {
+    const value = input.trim();
+    if (!value)
+        return {};
+    try {
+        const url = new URL(value);
+        return {
+            code: url.searchParams.get('code') ?? undefined,
+            state: url.searchParams.get('state') ?? undefined,
+        };
+    }
+    catch {
+        // not a URL — fall through to the bare forms
+    }
+    if (value.includes('#')) {
+        const [code, state] = value.split('#', 2);
+        return { code: code || undefined, state: state || undefined };
+    }
+    if (value.includes('code=')) {
+        const params = new URLSearchParams(value);
+        return {
+            code: params.get('code') ?? undefined,
+            state: params.get('state') ?? undefined,
+        };
+    }
+    return { code: value };
+}
 /**
  * Exchange an authorization code + PKCE verifier for access and refresh tokens.
  *
@@ -87,24 +134,21 @@ export function buildAuthorizationUrl(params) {
  * @task T9302
  */
 export async function exchangePkceCode(params) {
-    const body = new URLSearchParams({
+    const fields = {
         grant_type: 'authorization_code',
         client_id: params.clientId,
         code: params.code,
         code_verifier: params.codeVerifier,
         redirect_uri: params.redirectUri,
-    });
-    const resp = await globalThis.fetch(params.tokenEndpoint, {
-        method: 'POST',
-        headers: {
-            'Content-Type': 'application/x-www-form-urlencoded',
-            Accept: 'application/json',
-            ...params.extraHeaders,
-        },
-        body: body.toString(),
-    });
+    };
+    // Anthropic (json) requires the authorize-time state echoed in the exchange;
+    // form-encoded RFC endpoints do not define it on the token request.
+    if (params.bodyFormat === 'json' && params.state) {
+        fields['state'] = params.state;
+    }
+    const resp = await postTokenRequest(params.tokenEndpoint, fields, params);
     if (!resp.ok) {
-        const detail = await extractErrorDetail(resp);
+        const detail = await extractOAuthErrorDetail(resp);
         throw new Error(`PKCE code exchange failed for provider '${params.provider}': HTTP ${resp.status}${detail}`);
     }
     return parseTokenResponse(params.provider, await resp.json());
@@ -122,22 +166,14 @@ export async function exchangePkceCode(params) {
  * @task T9302
  */
 export async function refreshPkceToken(params) {
-    const body = new URLSearchParams({
+    const fields = {
         grant_type: 'refresh_token',
         client_id: params.clientId,
         refresh_token: params.refreshToken,
-    });
-    const resp = await globalThis.fetch(params.tokenEndpoint, {
-        method: 'POST',
-        headers: {
-            'Content-Type': 'application/x-www-form-urlencoded',
-            Accept: 'application/json',
-            ...params.extraHeaders,
-        },
-        body: body.toString(),
-    });
+    };
+    const resp = await postTokenRequest(params.tokenEndpoint, fields, params);
     if (!resp.ok) {
-        const detail = await extractErrorDetail(resp);
+        const detail = await extractOAuthErrorDetail(resp);
         throw new Error(`PKCE token refresh failed for provider '${params.provider}': HTTP ${resp.status}${detail}`);
     }
     return parseTokenResponse(params.provider, await resp.json());
@@ -145,6 +181,28 @@ export async function refreshPkceToken(params) {
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
+/**
+ * POST a token-endpoint request (code exchange or refresh grant).
+ *
+ * Single home for the body-encoding split shared by {@link exchangePkceCode}
+ * and {@link refreshPkceToken}: `'form'` (RFC 6749 default,
+ * `application/x-www-form-urlencoded`) vs `'json'` (Anthropic's non-RFC
+ * `application/json` token endpoint). See
+ * `ProviderOAuthConfig.tokenBodyFormat`.
+ *
+ * @internal
+ */
+function postTokenRequest(tokenEndpoint, fields, opts) {
+    return globalThis.fetch(tokenEndpoint, {
+        method: 'POST',
+        headers: {
+            'Content-Type': opts.bodyFormat === 'json' ? 'application/json' : 'application/x-www-form-urlencoded',
+            Accept: 'application/json',
+            ...opts.extraHeaders,
+        },
+        body: opts.bodyFormat === 'json' ? JSON.stringify(fields) : new URLSearchParams(fields).toString(),
+    });
+}
 /**
  * base64url-encode a byte array (RFC 4648 §5, no padding).
  *
@@ -180,12 +238,20 @@ function parseTokenResponse(provider, data) {
     };
 }
 /**
- * Extract a human-readable error detail string from a non-OK HTTP response.
+ * Extract a human-readable error detail string from a non-OK OAuth HTTP
+ * response.
+ *
+ * The single shared extractor for every OAuth surface in the LLM layer
+ * (`pkce.ts`, `google-pkce.ts`, `device-code.ts`) — local copies drifted and
+ * re-introduced the `[object Object]` masking of DHQ-075 (T11958).
  *
  * Strategy:
  * 1. Clone the response so the body stream is not consumed by the primary
  *    error path (callers may need the body for further inspection).
  * 2. Parse as JSON; use `error_description` or `error` fields (RFC 6749 §5.2).
+ *    When the field is an object (Anthropic nests
+ *    `{"error": {"type", "message"}}`), extract `message`/`type` — never
+ *    `String(object)`.
  * 3. Fall back to the raw text body when JSON parsing fails (e.g. HTML pages
  *    returned by a WAF or a misconfigured reverse proxy). Truncate at 512 chars
  *    so a multi-kilobyte HTML page does not flood the error message.
@@ -194,16 +260,27 @@ function parseTokenResponse(provider, data) {
  * This ensures the caller never sees `[object Object]` in the thrown message
  * and always surfaces the actual HTTP response body for debugging.
  *
- * @internal
+ * @task T11958
  */
-async function extractErrorDetail(resp) {
+export async function extractOAuthErrorDetail(resp) {
     // Clone before reading so the caller's Response is not drained.
     const clone = resp.clone();
     try {
         const body = (await clone.json());
         const desc = body['error_description'] ?? body['error'];
-        if (desc)
-            return ` — ${String(desc)}`;
+        if (typeof desc === 'string' && desc)
+            return ` — ${desc}`;
+        // Anthropic nests the detail: {"error": {"type": "...", "message": "..."}}.
+        // `String(object)` here is what produced the undebuggable
+        // "[object Object]" of DHQ-075 — extract message/type, else stringify.
+        if (desc !== null && typeof desc === 'object') {
+            const d = desc;
+            const message = typeof d['message'] === 'string' ? d['message'] : undefined;
+            const type = typeof d['type'] === 'string' ? d['type'] : undefined;
+            if (message)
+                return ` — ${type ? `${type}: ` : ''}${message}`;
+            return ` — ${JSON.stringify(desc).slice(0, 512)}`;
+        }
         // JSON parsed but had no recognized field: fall through to raw-text path.
         const text = JSON.stringify(body);
         return ` — ${text.slice(0, 512)}`;

package/dist/llm/oauth/pkce.js.map

@@ -1 +1 @@
-{"version":3,"file":"pkce.js","sourceRoot":"","sources":["../../../src/llm/oauth/pkce.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pkce.js","sourceRoot":"","sources":["../../../src/llm/oauth/pkce.ts"],"names":[],"mappings":"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"}

package/dist/llm/onboarding/front-door.d.ts

@@ -0,0 +1,146 @@
+/**
+ * `runFrontDoorLogin` — the shared onboarding front-door orchestrator (T11725 · M3).
+ *
+ * This is the ONE function every front-door entry point (`cleo login`,
+ * `cleo auth login`, `cleo llm login`) dispatches to. It owns the small amount
+ * of orchestration that sits ABOVE the 3-step onboarding engine
+ * ({@link runOnboardingLogin}):
+ *
+ *   1. **resolve provider** — alias → canonical via {@link getProviderProfile}.
+ *   2. **resolve auth method** — caller-supplied, else inferred from the
+ *      provider profile (OAuth when the profile advertises an `oauth` config,
+ *      else `api_key`).
+ *   3. **acquire the credential secret**:
+ *        - `api_key` → the caller passes the raw key in {@link FrontDoorLoginOptions.token}.
+ *        - `oauth`   → the caller's injected {@link OAuthTokenAcquirer} runs the
+ *          interactive browser / device-code dance and RETURNS the token. The
+ *          interactive step lives in the CLI (so this module stays
+ *          non-interactive and unit-testable); the acquirer is a seam, not a hard
+ *          dependency.
+ *   4. **run the engine** — hand the acquired token to {@link runOnboardingLogin},
+ *      which performs connect → select → bind → validate and returns the typed,
+ *      secret-free {@link OnboardingResult} envelope.
+ *
+ * ## Why a core orchestrator (and not CLI glue)
+ *
+ * Keeping this in `@cleocode/core` means the CLI handlers for all three entry
+ * points are THIN — they parse flags, build a {@link ReadlineWizardIO}, supply
+ * the OAuth acquirer, and call THIS function. No entry point re-implements the
+ * picker, the auth-method inference, or the engine call (AC2: no duplicated
+ * handler logic). Studio / the future API surface reuse the same orchestrator.
+ *
+ * ## Security
+ *
+ * The returned {@link OnboardingResult} carries NO secret fields (inherited from
+ * the engine contract). The raw token flows only from the acquirer into the
+ * engine's connect step; it is never logged or surfaced on the envelope.
+ *
+ * @module llm/onboarding/front-door
+ * @task T11725
+ * @epic T11671 (E6-ONBOARDING-FRONT-DOOR)
+ */
+import type { OnboardingAuthMode, OnboardingResult, ProviderProfile, RoleName } from '@cleocode/contracts';
+import { type OnboardingDeps, type OnboardingLoginOptions } from './login-engine.js';
+/**
+ * Outcome of an interactive OAuth acquisition. The acquirer performs the
+ * browser / device-code exchange and lands the credential in the pool itself
+ * (reusing the existing, battle-tested `cleo llm login` flow), then returns the
+ * non-secret metadata the front door surfaces. Because the credential is
+ * already stored, the engine's connect step is told to skip its own write
+ * (`credentialAlreadyStored`) so the OAuth token is persisted exactly once.
+ *
+ * @task T11725
+ */
+export interface AcquiredOAuthToken {
+    /** The credential label the acquirer stored the OAuth credential under. */
+    readonly label: string;
+    /** Seconds until the access token expires (surfaced in the summary), if known. */
+    readonly expiresIn?: number;
+}
+/**
+ * Injectable seam that performs the interactive OAuth flow for a provider AND
+ * lands the resulting credential in the pool, returning its non-secret label +
+ * metadata.
+ *
+ * The CLI front-door handler supplies the real implementation (wrapping the
+ * existing PKCE / device-code browser dance in `cleo llm login`). Unit tests
+ * pass a stub that records the call and returns a fixed label so the
+ * orchestrator is exercised without a live browser.
+ *
+ * @param provider - Canonical provider name (alias already resolved).
+ * @returns The stored credential label + non-secret metadata.
+ * @task T11725
+ */
+export type OAuthTokenAcquirer = (provider: string) => Promise<AcquiredOAuthToken>;
+/**
+ * Options for {@link runFrontDoorLogin}.
+ *
+ * @task T11725
+ */
+export interface FrontDoorLoginOptions {
+    /**
+     * Explicit auth method. When omitted it is inferred from the resolved
+     * provider profile: `oauth` when the profile advertises an `oauth` config,
+     * else `api_key`.
+     */
+    authMode?: OnboardingAuthMode;
+    /**
+     * Pre-supplied credential secret for the `api_key` path (the raw API key).
+     * Ignored on the `oauth` path — that token comes from the acquirer.
+     */
+    token?: string;
+    /** Human-readable label stored alongside the credential. */
+    label?: string;
+    /** Explicit model id to bind; defaults to the latest catalog model. */
+    model?: string;
+    /** Bind to a specific role instead of the global default. */
+    role?: RoleName;
+    /** Project root threaded through the engine's validate step. */
+    projectRoot?: string;
+}
+/**
+ * Injectable accessors for {@link runFrontDoorLogin}.
+ *
+ * Defaults to the real core accessors; tests override individual members to
+ * drive the orchestrator without a live provider registry / engine.
+ *
+ * @task T11725
+ */
+export interface FrontDoorDeps {
+    /** Resolve a provider profile by name/alias (alias → canonical). */
+    getProviderProfile: (name: string) => Promise<ProviderProfile | undefined>;
+    /** The 3-step onboarding engine. */
+    runOnboardingLogin: (provider: string, opts?: OnboardingLoginOptions, deps?: OnboardingDeps) => Promise<OnboardingResult>;
+}
+/**
+ * Resolve the auth method for a provider profile: caller override wins, else
+ * `oauth` when the profile advertises an OAuth config, else `api_key`.
+ *
+ * @param profile - The resolved provider profile.
+ * @param override - Optional explicit auth mode from the caller.
+ * @returns The effective {@link OnboardingAuthMode}.
+ * @task T11725
+ */
+export declare function resolveAuthMode(profile: ProviderProfile, override?: OnboardingAuthMode): OnboardingAuthMode;
+/**
+ * Run the shared onboarding front-door flow for a provider (T11725 · M3).
+ *
+ * Resolves the provider + auth method, acquires the credential secret (raw API
+ * key from `opts.token`, or via the injected {@link OAuthTokenAcquirer} for the
+ * OAuth path), then delegates the heavy lifting to {@link runOnboardingLogin}.
+ *
+ * Mirrors the engine's never-throw-on-expected-failure contract: an unknown
+ * provider or a missing api-key secret returns a failed {@link OnboardingResult}
+ * envelope rather than throwing. The OAuth acquirer's own errors DO propagate —
+ * an aborted browser flow is a hard, caller-visible failure.
+ *
+ * @param provider     - Provider name or alias (e.g. `'anthropic'`, `'codex'`).
+ * @param opts         - {@link FrontDoorLoginOptions}.
+ * @param acquireOAuth - Interactive OAuth token acquirer (the CLI's browser flow).
+ *   Only invoked on the `oauth` path; may be omitted when the flow is `api_key`.
+ * @param deps         - Injectable accessor seam; defaults to real core accessors.
+ * @returns The typed onboarding result envelope.
+ * @task T11725
+ */
+export declare function runFrontDoorLogin(provider: string, opts?: FrontDoorLoginOptions, acquireOAuth?: OAuthTokenAcquirer, deps?: FrontDoorDeps): Promise<OnboardingResult>;
+//# sourceMappingURL=front-door.d.ts.map

package/dist/llm/onboarding/front-door.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"front-door.d.ts","sourceRoot":"","sources":["../../../src/llm/onboarding/front-door.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,QAAQ,EACT,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAE5B,MAAM,mBAAmB,CAAC;AAM3B;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAMnF;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,kBAAkB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAAC;IAC3E,oCAAoC;IACpC,kBAAkB,EAAE,CAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,sBAAsB,EAC7B,IAAI,CAAC,EAAE,cAAc,KAClB,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAChC;AAkBD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,eAAe,EACxB,QAAQ,CAAC,EAAE,kBAAkB,GAC5B,kBAAkB,CAGpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,qBAA0B,EAChC,YAAY,CAAC,EAAE,kBAAkB,EACjC,IAAI,GAAE,aAAsC,GAC3C,OAAO,CAAC,gBAAgB,CAAC,CA0C3B"}

package/dist/llm/onboarding/front-door.js

@@ -0,0 +1,153 @@
+/**
+ * `runFrontDoorLogin` — the shared onboarding front-door orchestrator (T11725 · M3).
+ *
+ * This is the ONE function every front-door entry point (`cleo login`,
+ * `cleo auth login`, `cleo llm login`) dispatches to. It owns the small amount
+ * of orchestration that sits ABOVE the 3-step onboarding engine
+ * ({@link runOnboardingLogin}):
+ *
+ *   1. **resolve provider** — alias → canonical via {@link getProviderProfile}.
+ *   2. **resolve auth method** — caller-supplied, else inferred from the
+ *      provider profile (OAuth when the profile advertises an `oauth` config,
+ *      else `api_key`).
+ *   3. **acquire the credential secret**:
+ *        - `api_key` → the caller passes the raw key in {@link FrontDoorLoginOptions.token}.
+ *        - `oauth`   → the caller's injected {@link OAuthTokenAcquirer} runs the
+ *          interactive browser / device-code dance and RETURNS the token. The
+ *          interactive step lives in the CLI (so this module stays
+ *          non-interactive and unit-testable); the acquirer is a seam, not a hard
+ *          dependency.
+ *   4. **run the engine** — hand the acquired token to {@link runOnboardingLogin},
+ *      which performs connect → select → bind → validate and returns the typed,
+ *      secret-free {@link OnboardingResult} envelope.
+ *
+ * ## Why a core orchestrator (and not CLI glue)
+ *
+ * Keeping this in `@cleocode/core` means the CLI handlers for all three entry
+ * points are THIN — they parse flags, build a {@link ReadlineWizardIO}, supply
+ * the OAuth acquirer, and call THIS function. No entry point re-implements the
+ * picker, the auth-method inference, or the engine call (AC2: no duplicated
+ * handler logic). Studio / the future API surface reuse the same orchestrator.
+ *
+ * ## Security
+ *
+ * The returned {@link OnboardingResult} carries NO secret fields (inherited from
+ * the engine contract). The raw token flows only from the acquirer into the
+ * engine's connect step; it is never logged or surfaced on the envelope.
+ *
+ * @module llm/onboarding/front-door
+ * @task T11725
+ * @epic T11671 (E6-ONBOARDING-FRONT-DOOR)
+ */
+import { getProviderProfile } from '../provider-registry/index.js';
+import { runOnboardingLogin, } from './login-engine.js';
+/**
+ * The default front-door dependency set — the real, merged core accessors.
+ *
+ * @internal
+ */
+function defaultFrontDoorDeps() {
+    return {
+        getProviderProfile,
+        runOnboardingLogin: (provider, opts, deps) => runOnboardingLogin(provider, opts, deps),
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the auth method for a provider profile: caller override wins, else
+ * `oauth` when the profile advertises an OAuth config, else `api_key`.
+ *
+ * @param profile - The resolved provider profile.
+ * @param override - Optional explicit auth mode from the caller.
+ * @returns The effective {@link OnboardingAuthMode}.
+ * @task T11725
+ */
+export function resolveAuthMode(profile, override) {
+    if (override)
+        return override;
+    return profile.oauth ? 'oauth' : 'api_key';
+}
+/**
+ * Run the shared onboarding front-door flow for a provider (T11725 · M3).
+ *
+ * Resolves the provider + auth method, acquires the credential secret (raw API
+ * key from `opts.token`, or via the injected {@link OAuthTokenAcquirer} for the
+ * OAuth path), then delegates the heavy lifting to {@link runOnboardingLogin}.
+ *
+ * Mirrors the engine's never-throw-on-expected-failure contract: an unknown
+ * provider or a missing api-key secret returns a failed {@link OnboardingResult}
+ * envelope rather than throwing. The OAuth acquirer's own errors DO propagate —
+ * an aborted browser flow is a hard, caller-visible failure.
+ *
+ * @param provider     - Provider name or alias (e.g. `'anthropic'`, `'codex'`).
+ * @param opts         - {@link FrontDoorLoginOptions}.
+ * @param acquireOAuth - Interactive OAuth token acquirer (the CLI's browser flow).
+ *   Only invoked on the `oauth` path; may be omitted when the flow is `api_key`.
+ * @param deps         - Injectable accessor seam; defaults to real core accessors.
+ * @returns The typed onboarding result envelope.
+ * @task T11725
+ */
+export async function runFrontDoorLogin(provider, opts = {}, acquireOAuth, deps = defaultFrontDoorDeps()) {
+    // --- Resolve provider (alias → canonical) -------------------------------
+    const profile = await deps.getProviderProfile(provider);
+    if (!profile) {
+        // Defer the canonical "unknown provider" envelope to the engine so the
+        // failure shape is produced in exactly one place (DRY).
+        return deps.runOnboardingLogin(provider, buildEngineOptions(opts, opts.token, false));
+    }
+    const canonicalProvider = profile.name;
+    // --- Resolve auth method ------------------------------------------------
+    const authMode = resolveAuthMode(profile, opts.authMode);
+    // --- Acquire the credential ---------------------------------------------
+    // api_key: the raw key is already in `opts.token` — the engine's connect step
+    //          performs the single write.
+    // oauth:   the acquirer runs the interactive browser flow AND stores the
+    //          credential, so the engine connect step skips its own write.
+    let token = opts.token;
+    let credentialAlreadyStored = false;
+    let label = opts.label;
+    if (authMode === 'oauth') {
+        if (!acquireOAuth) {
+            throw new Error(`OAuth login for '${canonicalProvider}' requires an interactive token acquirer. ` +
+                'This entry point cannot complete an OAuth flow non-interactively — ' +
+                `supply an API key with --api-key/--token, or run on a terminal.`);
+        }
+        const acquired = await acquireOAuth(canonicalProvider);
+        credentialAlreadyStored = true;
+        // Prefer the acquirer-reported label so the engine binds to the credential
+        // the OAuth flow actually stored.
+        label = label ?? acquired.label;
+        token = undefined;
+    }
+    // --- Run the engine (connect → select → bind → validate) ----------------
+    return deps.runOnboardingLogin(canonicalProvider, buildEngineOptions({ ...opts, authMode, label }, token, credentialAlreadyStored));
+}
+/**
+ * Map the front-door options + resolved token to the engine's option shape.
+ *
+ * Centralised so the unknown-provider deferral path and the happy path build
+ * identical engine options.
+ *
+ * @internal
+ */
+function buildEngineOptions(opts, token, credentialAlreadyStored) {
+    const engineOpts = {};
+    if (token !== undefined)
+        engineOpts.token = token;
+    if (opts.authMode !== undefined)
+        engineOpts.authMode = opts.authMode;
+    if (opts.label !== undefined)
+        engineOpts.label = opts.label;
+    if (opts.model !== undefined)
+        engineOpts.model = opts.model;
+    if (opts.role !== undefined)
+        engineOpts.role = opts.role;
+    if (opts.projectRoot !== undefined)
+        engineOpts.projectRoot = opts.projectRoot;
+    if (credentialAlreadyStored)
+        engineOpts.credentialAlreadyStored = true;
+    return engineOpts;
+}
+//# sourceMappingURL=front-door.js.map

package/dist/llm/onboarding/front-door.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"front-door.js","sourceRoot":"","sources":["../../../src/llm/onboarding/front-door.ts"],"names":[],"mappings":"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"}