dsh-plugin-subscription-usage 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 V1ki
+Copyright (c) 2026 Parth Patel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# dsh-plugin-subscription-usage
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A DeepSeek Harness plugin that uses your ChatGPT (Codex), Claude, Grok, GitHub Copilot and Google Antigravity subscriptions as LLM providers, and shows how fast you are using each limit.
+
+It replaces `dsh-plugin-subscriptions`. Both register the `codex` adapter, so enabling both fails with `DUPLICATE_ADAPTER`. Disable the other one first.
+
+## What you get
+
+- **Models page.** Each subscription is a provider row where you sign in, manage accounts, choose models and enable tools.
+- **Usage page.** Settings, Usage shows each limit with a pace forecast: how much is used, when it resets, and whether you will run out first. You can switch between Left and Used, turn pace warnings on or off, and pin providers to the composer.
+- **Composer gauge.** The current model's provider, plus any you pinned, shows under the composer.
+- **API key usage.** Z.ai, Ollama Cloud and Kimi Code usage is read with an API key you paste on the Usage page. These providers are usage-only. The plugin does not route requests to them.
+
+## Install
+
+```bash
+dsh plugin install dsh-plugin-subscription-usage
+```
+
+Restart DSH, then open Settings, Models.
+
+## Privacy
+
+- OAuth sessions are stored in `~/.dsh/plugins/subscriptions/auth.json`.
+- API keys are stored in `~/.dsh/plugins/subscriptions/usage-keys.json`.
+- Both files are readable only by you. Keys are sent only to the provider's own host and never to the browser page, which sees the last four characters.
+
+## Limits
+
+- Copilot, Z.ai, Ollama Cloud and Kimi Code usage comes from endpoints the vendors do not document. They can change without notice, and the card then shows "Usage unavailable".
+- A plain Moonshot key does not work for Kimi Code usage.
+
+## Credits
+
+Built on [V1ki/dsh-plugin-subscriptions](https://github.com/V1ki/dsh-plugin-subscriptions) (MIT). The sign-in, provider, pool and translation code under `src/auth`, `src/providers`, `src/translate` and `src/tools` comes from it. The Usage page, key providers and the Models UI are new.
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# Mounts the Host half when this bundle is installed into a profile. The
+# Client half is discovered from `dsh.client` in package.json.
+- insert:
+    - id: subscription-models
+      name: dsh-plugin-subscription-usage

package/icon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect width="64" height="64" rx="14" fill="#1f2a44"/>
+  <rect x="12" y="20" width="40" height="7" rx="3.5" fill="#33405e"/>
+  <rect x="12" y="20" width="26" height="7" rx="3.5" fill="#22c55e"/>
+  <rect x="31" y="16" width="3" height="15" rx="1.5" fill="#f9fafb"/>
+  <rect x="12" y="37" width="40" height="7" rx="3.5" fill="#33405e"/>
+  <rect x="12" y="37" width="32" height="7" rx="3.5" fill="#f59e0b"/>
+  <rect x="25" y="33" width="3" height="15" rx="1.5" fill="#f9fafb"/>
+</svg>

package/lib/auth/claude-code-creds.d.ts

@@ -0,0 +1,23 @@
+import type { ClaudeSession } from './store.js';
+/** Read the current Claude Code session from its source of truth: macOS Keychain, falling back to the credentials file. */
+export declare function readClaudeCodeCredentials(): ClaudeSession | undefined;
+/**
+ * Write a refreshed session back to Claude Code's own credential store, so
+ * the `claude` CLI and any other consumer of the same account see the token
+ * we just rotated. A stale-blob mismatch (something else rotated it first)
+ * is a no-op — the caller already has that other rotation via readClaudeCodeCredentials.
+ * @param next - the freshly refreshed session to persist.
+ * @param expectedPriorAccessToken - the access token this refresh started from.
+ * @returns whether the write-back succeeded.
+ */
+export declare function writeBackClaudeCodeCredentials(next: ClaudeSession, expectedPriorAccessToken: string): boolean;
+/**
+ * Refresh a Claude session, first checking whether Claude Code's own store
+ * already holds a fresher token (rotated by the `claude` CLI or another
+ * consumer) before hitting the OAuth endpoint ourselves — and writing our own
+ * refresh back to that store so every consumer of the account stays synced.
+ * @param session - the session TokenManager wants refreshed.
+ * @param doRefresh - the actual OAuth refresh-token grant (network call).
+ * @returns the freshest available session.
+ */
+export declare function refreshClaudeSynced(session: ClaudeSession, doRefresh: (session: ClaudeSession) => Promise<ClaudeSession>): Promise<ClaudeSession>;

package/lib/auth/claude-code-creds.js

@@ -0,0 +1,172 @@
+import { execFileSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+const PRIMARY_SERVICE = 'Claude Code-credentials';
+const DEFAULT_SCOPES = 'user:profile user:inference user:sessions:claude_code user:mcp_servers';
+function toSession(data) {
+    // Empty-string tokens (seen from a corrupted Keychain item left by a Claude
+    // Code logout) pass the typeof gate but are useless and would poison the
+    // auth store — a single such entry fails every provider's status read.
+    if (typeof data.accessToken !== 'string' || data.accessToken.length === 0
+        || typeof data.refreshToken !== 'string' || data.refreshToken.length === 0
+        || typeof data.expiresAt !== 'number' || !Number.isFinite(data.expiresAt)) {
+        return undefined;
+    }
+    const scopes = Array.isArray(data.scopes) ? data.scopes.join(' ') : typeof data.scopes === 'string' ? data.scopes : DEFAULT_SCOPES;
+    return {
+        accessToken: data.accessToken,
+        refreshToken: data.refreshToken,
+        expiresAt: Math.trunc(data.expiresAt),
+        scopes,
+        ...typeof data.emailAddress === 'string' ? { emailAddress: data.emailAddress } : {},
+        ...typeof data.subscriptionType === 'string' ? { subscriptionType: data.subscriptionType } : {},
+    };
+}
+function parseBlob(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    return toSession(parsed.claudeAiOauth ?? parsed);
+}
+function credentialsFilePath() {
+    return join(process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), '.claude'), '.credentials.json');
+}
+function readKeychainRaw() {
+    try {
+        return execFileSync('/usr/bin/security', ['find-generic-password', '-s', PRIMARY_SERVICE, '-w'], {
+            timeout: 3000,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function readFileRaw() {
+    try {
+        return readFileSync(credentialsFilePath(), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read the current Claude Code session from its source of truth: macOS Keychain, falling back to the credentials file. */
+export function readClaudeCodeCredentials() {
+    if (process.platform === 'darwin') {
+        const raw = readKeychainRaw();
+        const session = raw !== undefined ? parseBlob(raw) : undefined;
+        if (session)
+            return session;
+    }
+    const raw = readFileRaw();
+    return raw !== undefined ? parseBlob(raw) : undefined;
+}
+function blobMatches(raw, expectedAccessToken) {
+    return parseBlob(raw)?.accessToken === expectedAccessToken;
+}
+function getKeychainAccountName() {
+    try {
+        const output = execFileSync('/usr/bin/security', ['find-generic-password', '-s', PRIMARY_SERVICE], {
+            timeout: 2000,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return /"acct"<blob>="([^"]*)"/.exec(output)?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Merge fresh tokens into an existing raw blob, preserving unrelated fields. */
+function mergeIntoBlob(existingRaw, next) {
+    let parsed;
+    try {
+        parsed = JSON.parse(existingRaw);
+    }
+    catch {
+        return undefined;
+    }
+    const target = (parsed.claudeAiOauth ?? parsed);
+    target.accessToken = next.accessToken;
+    target.refreshToken = next.refreshToken;
+    target.expiresAt = next.expiresAt;
+    return JSON.stringify(parsed);
+}
+/**
+ * Write a refreshed session back to Claude Code's own credential store, so
+ * the `claude` CLI and any other consumer of the same account see the token
+ * we just rotated. A stale-blob mismatch (something else rotated it first)
+ * is a no-op — the caller already has that other rotation via readClaudeCodeCredentials.
+ * @param next - the freshly refreshed session to persist.
+ * @param expectedPriorAccessToken - the access token this refresh started from.
+ * @returns whether the write-back succeeded.
+ */
+export function writeBackClaudeCodeCredentials(next, expectedPriorAccessToken) {
+    if (process.platform === 'darwin') {
+        const raw = readKeychainRaw();
+        if (raw === undefined || !blobMatches(raw, expectedPriorAccessToken))
+            return false;
+        const updated = mergeIntoBlob(raw, next);
+        if (updated === undefined)
+            return false;
+        const account = getKeychainAccountName() ?? PRIMARY_SERVICE;
+        try {
+            execFileSync('/usr/bin/security', ['add-generic-password', '-s', PRIMARY_SERVICE, '-a', account, '-w', updated, '-U'], {
+                timeout: 2000,
+                stdio: 'ignore',
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    const path = credentialsFilePath();
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    if (!blobMatches(raw, expectedPriorAccessToken))
+        return false;
+    const updated = mergeIntoBlob(raw, next);
+    if (updated === undefined)
+        return false;
+    try {
+        const dir = dirname(path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        writeFileSync(path, updated, { encoding: 'utf8', mode: 0o600 });
+        chmodSync(path, 0o600);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Refresh a Claude session, first checking whether Claude Code's own store
+ * already holds a fresher token (rotated by the `claude` CLI or another
+ * consumer) before hitting the OAuth endpoint ourselves — and writing our own
+ * refresh back to that store so every consumer of the account stays synced.
+ * @param session - the session TokenManager wants refreshed.
+ * @param doRefresh - the actual OAuth refresh-token grant (network call).
+ * @returns the freshest available session.
+ */
+export async function refreshClaudeSynced(session, doRefresh) {
+    const fromSource = readClaudeCodeCredentials();
+    const base = fromSource !== undefined && fromSource.accessToken !== session.accessToken ? fromSource : session;
+    if (base.expiresAt > Date.now() + 60_000)
+        return base;
+    const next = await doRefresh(base);
+    writeBackClaudeCodeCredentials(next, base.accessToken);
+    return next;
+}

package/lib/auth/device-flow.d.ts

@@ -0,0 +1,55 @@
+/** Static per-provider device-flow facts. */
+export interface DeviceFlowSpec {
+    /** OAuth App / GitHub App client id the device code is requested for. */
+    clientId: string;
+    /** Scope string requested at device-code time. */
+    scope: string;
+    /** Device-code endpoint (e.g. `https://github.com/login/device/code`). */
+    deviceCodeUrl: string;
+    /** Token polling endpoint (e.g. `https://github.com/login/oauth/access_token`). */
+    tokenUrl: string;
+    /** Fetch implementation (injectable for tests). */
+    fetchFn?: typeof fetch;
+}
+/** One in-flight device-flow login attempt. */
+export interface DeviceAttempt {
+    /** URL the user opens to authorize (e.g. `https://github.com/login/device`). */
+    readonly verificationUrl: string;
+    /** Short code the user types at the verification URL. */
+    readonly userCode: string;
+    /**
+     * Poll until GitHub releases the access token.
+     * @returns the GitHub OAuth access token; rejects on timeout, denial, or cancel.
+     */
+    waitToken(): Promise<string>;
+    /** Abort the attempt; `waitToken` rejects with a cancellation error. */
+    cancel(): void;
+}
+/**
+ * Own the set of in-flight device-flow attempts, keyed by provider. One
+ * attempt per provider at a time; an attempt removes itself when it settles.
+ */
+export declare class DeviceFlowManager {
+    private attempts;
+    /**
+     * Whether a device-flow attempt is running for one provider.
+     * @param provider - the provider route.
+     * @returns true while an attempt is polling.
+     */
+    isBusy(provider: string): boolean;
+    /**
+     * The pending attempt for one provider, when any.
+     * @param provider - the provider route.
+     * @returns the in-flight attempt, or `undefined`.
+     */
+    pending(provider: string): DeviceAttempt | undefined;
+    /**
+     * Start a device-flow attempt: request a device code, then poll the token
+     * endpoint in the background of `waitToken`.
+     * @param provider - the provider route (one attempt at a time).
+     * @param spec - static flow facts for this provider.
+     * @returns the live attempt; its `waitToken()` settles the login.
+     * @throws when an attempt is already running or the device-code request fails.
+     */
+    start(provider: string, spec: DeviceFlowSpec): Promise<DeviceAttempt>;
+}

package/lib/auth/device-flow.js

@@ -0,0 +1,177 @@
+/**
+ * GitHub OAuth device-authorization flow (RFC 8628) for providers that cannot
+ * use the loopback redirect engine: no redirect URI, no PKCE, no client
+ * secret. The user opens a verification URL and types a short code while the
+ * plugin polls the token endpoint until GitHub releases the access token.
+ * The management model (one attempt per provider, `isBusy`/`pending`/`cancel`)
+ * mirrors {@link OAuthFlowManager} so the auth controller can treat both
+ * engines uniformly.
+ */
+import { proxiedFetch } from '../http.js';
+/** Default poll interval when the device-code response omits one. */
+const DEFAULT_INTERVAL_SEC = 5;
+/** Default device-code lifetime when the response omits one (GitHub: 15 minutes). */
+const DEFAULT_EXPIRES_IN_SEC = 900;
+/** Sleep for `ms`, rejecting early when the signal aborts. */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason instanceof Error ? signal.reason : new Error('aborted'));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        timer.unref();
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason instanceof Error ? signal.reason : new Error('aborted'));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * Own the set of in-flight device-flow attempts, keyed by provider. One
+ * attempt per provider at a time; an attempt removes itself when it settles.
+ */
+export class DeviceFlowManager {
+    attempts = new Map();
+    /**
+     * Whether a device-flow attempt is running for one provider.
+     * @param provider - the provider route.
+     * @returns true while an attempt is polling.
+     */
+    isBusy(provider) {
+        return this.attempts.has(provider);
+    }
+    /**
+     * The pending attempt for one provider, when any.
+     * @param provider - the provider route.
+     * @returns the in-flight attempt, or `undefined`.
+     */
+    pending(provider) {
+        return this.attempts.get(provider);
+    }
+    /**
+     * Start a device-flow attempt: request a device code, then poll the token
+     * endpoint in the background of `waitToken`.
+     * @param provider - the provider route (one attempt at a time).
+     * @param spec - static flow facts for this provider.
+     * @returns the live attempt; its `waitToken()` settles the login.
+     * @throws when an attempt is already running or the device-code request fails.
+     */
+    async start(provider, spec) {
+        if (this.attempts.has(provider)) {
+            throw new Error(`a ${provider} login attempt is already in progress`);
+        }
+        const fetchFn = spec.fetchFn ?? proxiedFetch;
+        const response = await fetchFn(spec.deviceCodeUrl, {
+            method: 'POST',
+            headers: {
+                'accept': 'application/json',
+                'content-type': 'application/x-www-form-urlencoded',
+            },
+            body: new URLSearchParams({ client_id: spec.clientId, scope: spec.scope }).toString(),
+        });
+        if (!response.ok) {
+            throw new Error(`${provider} device-code request failed (HTTP ${String(response.status)})`);
+        }
+        const wire = await response.json();
+        if (typeof wire.device_code !== 'string' || wire.device_code.length === 0
+            || typeof wire.user_code !== 'string' || wire.user_code.length === 0
+            || typeof wire.verification_uri !== 'string' || wire.verification_uri.length === 0) {
+            throw new Error(`${provider} device-code response is missing device_code/user_code/verification_uri`);
+        }
+        const intervalSec = typeof wire.interval === 'number' && wire.interval > 0
+            ? wire.interval
+            : DEFAULT_INTERVAL_SEC;
+        const expiresInSec = typeof wire.expires_in === 'number' && wire.expires_in > 0
+            ? wire.expires_in
+            : DEFAULT_EXPIRES_IN_SEC;
+        const controller = new AbortController();
+        let resolveToken;
+        let rejectToken;
+        const tokenPromise = new Promise((resolve, reject) => {
+            resolveToken = resolve;
+            rejectToken = reject;
+        });
+        // The promise settles exactly once, from the poll loop below; an unhandled
+        // rejection must not surface if nobody awaited waitToken after a cancel.
+        tokenPromise.catch(() => undefined);
+        const settle = (error, token) => {
+            // Identity check: a late settle from a stale attempt (its poll loop or a
+            // cancel arriving after it already settled) must not kill a NEW attempt
+            // the user started for the same provider.
+            if (this.attempts.get(provider) !== attempt)
+                return;
+            this.attempts.delete(provider);
+            if (error !== undefined)
+                rejectToken(error);
+            else if (token !== undefined)
+                resolveToken(token);
+        };
+        const poll = async () => {
+            let intervalMs = intervalSec * 1000;
+            const deadline = Date.now() + expiresInSec * 1000;
+            while (true) {
+                await sleep(intervalMs, controller.signal);
+                if (Date.now() >= deadline) {
+                    settle(new Error(`login timed out after ${String(Math.round(expiresInSec))}s`));
+                    return;
+                }
+                const pollResponse = await fetchFn(spec.tokenUrl, {
+                    method: 'POST',
+                    headers: {
+                        'accept': 'application/json',
+                        'content-type': 'application/x-www-form-urlencoded',
+                    },
+                    body: new URLSearchParams({
+                        client_id: spec.clientId,
+                        device_code: wire.device_code,
+                        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+                    }).toString(),
+                    signal: controller.signal,
+                });
+                const result = await pollResponse.json();
+                if (typeof result.access_token === 'string' && result.access_token.length > 0) {
+                    settle(undefined, result.access_token);
+                    return;
+                }
+                switch (result.error) {
+                    case 'authorization_pending':
+                        break;
+                    case 'slow_down':
+                        // RFC 8628 §3.5: add five seconds to the poll interval.
+                        intervalMs += 5000;
+                        break;
+                    case 'access_denied':
+                        settle(new Error('login declined on the GitHub authorization page'));
+                        return;
+                    case 'expired_token':
+                        settle(new Error('the device code expired before authorization completed'));
+                        return;
+                    default:
+                        settle(new Error(`${provider} device-flow polling failed: ${result.error_description ?? result.error ?? `HTTP ${String(pollResponse.status)}`}`));
+                        return;
+                }
+            }
+        };
+        const attempt = {
+            verificationUrl: wire.verification_uri,
+            userCode: wire.user_code,
+            waitToken: () => tokenPromise,
+            cancel: () => {
+                controller.abort(new Error('login cancelled'));
+                settle(new Error('login cancelled'));
+            },
+        };
+        this.attempts.set(provider, attempt);
+        void poll().catch((error) => {
+            // Aborts land here from sleep/fetch; everything else is a transport or
+            // parse failure worth surfacing as the login failure.
+            settle(error instanceof Error ? error : new Error(String(error)));
+        });
+        return attempt;
+    }
+}

package/lib/auth/jwt.d.ts

@@ -0,0 +1,10 @@
+/** Minimal JWT payload decoding for claims extraction (no signature verification). */
+/**
+ * Decode a JWT payload without verifying the signature. Used only to read
+ * account claims from `id_token`s issued over the provider's own TLS channel
+ * during a code exchange we initiated — never to authorize anything.
+ * @param token - the compact JWT string.
+ * @returns the parsed payload object, or `undefined` when the token is not a
+ *   well-formed JWT with a JSON object payload.
+ */
+export declare function decodeJwtPayload(token: string): Record<string, unknown> | undefined;

package/lib/auth/jwt.js

@@ -0,0 +1,25 @@
+/** Minimal JWT payload decoding for claims extraction (no signature verification). */
+/**
+ * Decode a JWT payload without verifying the signature. Used only to read
+ * account claims from `id_token`s issued over the provider's own TLS channel
+ * during a code exchange we initiated — never to authorize anything.
+ * @param token - the compact JWT string.
+ * @returns the parsed payload object, or `undefined` when the token is not a
+ *   well-formed JWT with a JSON object payload.
+ */
+export function decodeJwtPayload(token) {
+    const parts = token.split('.');
+    if (parts.length < 2)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+    }
+    catch {
+        // Malformed base64url or non-JSON payload: the token is unusable for claims.
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return undefined;
+    return parsed;
+}

package/lib/auth/oauth-flow.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Generic OAuth authorization-code flow engine: one temporary loopback HTTP
+ * server per login attempt receives the provider's redirect, validates
+ * `state`, and yields the authorization `code`. A pasted callback URL or bare
+ * code can substitute for the browser redirect (`manual`), and the user can
+ * abort (`cancel`). At most one attempt per provider runs at a time.
+ */
+import { type PkcePair } from './pkce.js';
+/** Default attempt lifetime: three minutes for the user to complete login. */
+export declare const DEFAULT_FLOW_TIMEOUT_MS = 180000;
+/** Where the temporary callback server listens; port 0 asks the OS for an ephemeral port. */
+export interface ListenSpec {
+    host: string;
+    /** Tried in order; the first free port wins (covers the codex 1455→1457 fallback). */
+    ports: readonly number[];
+}
+/** Inputs an authorize-URL builder may need for one attempt. */
+export interface AuthorizeInput {
+    /** Loopback redirect URI pointing at the temporary server. */
+    redirectUri: string;
+    state: string;
+    pkce: PkcePair;
+    /** Random hex nonce; only providers that require one use it. */
+    nonce: string;
+}
+/** Static per-provider flow facts. */
+export interface FlowSpec {
+    /** Path the provider redirects to on the loopback server. */
+    callbackPath: string;
+    listen: ListenSpec;
+    timeoutMs?: number;
+    /**
+     * Build the provider authorize URL for one attempt.
+     * @param input - redirect URI, state, PKCE pair, and nonce minted for this attempt.
+     * @returns the URL the user's browser should open.
+     */
+    buildAuthorizeUrl(input: AuthorizeInput): string;
+}
+/** One in-flight login attempt. */
+export interface OAuthAttempt {
+    /** URL to open in the user's browser. */
+    readonly authorizeUrl: string;
+    /** Redirect URI registered for this attempt (echoed at the token exchange). */
+    readonly redirectUri: string;
+    /** PKCE pair minted for this attempt. */
+    readonly pkce: PkcePair;
+    /** State parameter minted for this attempt (some providers echo it at exchange). */
+    readonly state: string;
+    /**
+     * Wait for the authorization code from the browser callback or `manual`.
+     * @returns the authorization code; rejects on timeout, provider error, or cancel.
+     */
+    waitCode(): Promise<string>;
+    /**
+     * Feed a pasted full callback URL (code + state extracted and validated) or
+     * a bare authorization code (state cannot be checked) into this attempt.
+     * @param input - the pasted text.
+     * @throws when the input carries no code or a mismatched state.
+     */
+    manual(input: string): void;
+    /** Abort the attempt and close its callback server. */
+    cancel(): void;
+}
+/**
+ * Own the set of in-flight login attempts, keyed by provider. One attempt per
+ * provider at a time; an attempt removes itself when it settles.
+ */
+export declare class OAuthFlowManager {
+    private attempts;
+    /**
+     * Whether a login attempt is running for one provider.
+     * @param provider - the provider route.
+     * @returns true while an attempt is waiting for its code.
+     */
+    isBusy(provider: string): boolean;
+    /**
+     * The pending attempt for one provider, when any.
+     * @param provider - the provider route.
+     * @returns the in-flight attempt, or `undefined`.
+     */
+    pending(provider: string): OAuthAttempt | undefined;
+    /**
+     * Start a login attempt: mint PKCE/state, open the loopback callback
+     * server, and build the authorize URL.
+     * @param provider - the provider route (one attempt at a time).
+     * @param spec - static flow facts for this provider.
+     * @returns the live attempt; its `waitCode()` settles the login.
+     * @throws when an attempt is already running or no callback port is free.
+     */
+    start(provider: string, spec: FlowSpec): Promise<OAuthAttempt>;
+}