dsh-subscriptions 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 V1ki
+
+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

@@ -0,0 +1,129 @@
+# DSH Subscription Hub
+
+Bring your AI subscriptions into
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH). One
+plugin adds their models to the native picker and puts account controls and
+reported quota in **Settings → Subscriptions**.
+
+## What it adds
+
+- **Six subscription model sources:** Connect ChatGPT/Codex, Claude, Grok,
+  GitHub Copilot, Google Antigravity, or Cursor and choose their models in
+  DSH's picker. These routes use account sign-in, without provider API keys.
+- **Account and model control:** Refresh catalogs and choose visible models.
+  For Codex, Claude, Grok, Copilot, and Antigravity, manage multiple accounts
+  and same-provider pools. Pools can use available quota to select an account
+  and fail over before a reply starts. See [account management](docs/account-management.md).
+- **Quota while you work:** See reported usage windows and reset times on
+  provider cards and in an optional session-footer pill. The same view reads
+  OpenCode Go and Kimi Code usage through keys already configured in
+  **Settings → Models**. Their model routes remain built into DSH. GitHub
+  Copilot has no usage endpoint.
+- **Provider tools:** Use Codex web search, Grok X search, ChatGPT or Grok
+  image generation and editing, and Grok video generation when the matching
+  provider is enabled.
+
+## Install
+
+Current source is tested with DSH `0.1.7-rc.2`, `0.2.0-rc.1`, and
+`0.2.0-rc.2`. The package's peers admit `>=0.1.7-rc.2 <0.3.0-0`: untested
+versions inside that range install but are unsupported, and versions outside
+it need an explicit `dsh plugin allow-version` exemption. See
+[docs/compatibility.md](docs/compatibility.md)
+for the support window and [docs/testing.md](docs/testing.md) for the test
+layers. With `dsh` available, install the plugin into the web profile from
+npm:
+
+```sh
+dsh plugin --profile web add dsh-subscriptions
+```
+
+Or from GitHub source:
+
+```sh
+dsh plugin --profile web add github:goodboys-ai/dsh-subscription-hub
+```
+
+Git installs run this package's `prepare` script to build the host and browser
+bundles. If a Git install stops with `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`
+(DSH `0.1.7-rc.2` does this by default), add this package to the web
+profile's `pnpm-workspace.yaml` (`~/.dsh/profiles/web/` unless `DSH_HOME` is
+set) and repeat the command:
+
+```yaml
+allowBuilds:
+  'dsh-subscriptions': true
+```
+
+(If a previous Git install used the old scoped name, replace its
+`allowBuilds` key with the one above.)
+
+Restart `dsh web` after installation. Open **Settings → Subscriptions** to
+connect providers, manage accounts and model lists, and inspect available
+quota. The session footer quota pill can be shown or hidden there for the
+current browser. OpenCode Go and Kimi Code cards show usage when their API
+keys are configured in **Settings → Models**.
+
+To update an installation, run the same `dsh plugin --profile web add` command again and restart `dsh web`.
+
+Without a version suffix, the npm command installs the `latest` dist-tag and
+the GitHub command installs the current default branch at install time. Pin
+a release by appending `@<version>` to the npm spec or the tag to the GitHub
+spec (`#vX.Y.Z`); see the
+[release policy](docs/compatibility.md#plugin-versioning).
+
+## Verification and limits
+
+CI builds, tests, and boots a packed tarball on both supported DSH versions;
+it does not run the GitHub source install's `prepare` step. Offline
+provider tests check recorded API responses, so a passing CI run cannot prove
+that a provider still accepts live sign-in or model requests. See
+[testing](docs/testing.md) for the checks and their limits.
+
+- **ChatGPT/Codex, Claude, Grok, GitHub Copilot, and Google Antigravity:**
+  The port includes the tool-message and icon fixes tracked in
+  [upstream issue #117](https://github.com/V1ki/dsh-plugin-subscriptions/issues/117).
+  A manual check in an isolated `0.1.7-rc.2` web profile found the client
+  bundle served and the auth and usage-status RPCs answering. Live sign-in
+  and model requests on the supported DSH lines remain to be checked.
+- **Cursor:** Browser sign-in and live model discovery were verified in an
+  isolated `0.1.7-rc.2` profile. A successful live model request remains to be
+  verified. Its transport comes from
+  [orrinzeng/dsh-cursor-subscription](https://github.com/orrinzeng/dsh-cursor-subscription)
+  and uses an undocumented Cursor protocol; see the
+  [source note](docs/cursor-origin.md).
+- **OpenCode Go and Kimi Code:** Live usage responses were verified. Their API
+  keys stay on the DSH host; the browser receives configured status and quota
+  windows, not the keys.
+
+Cursor uses one connected account and a live model catalog. Its model
+visibility selection persists under the DSH home directory, and automatic
+display follows newly discovered models. It ships no fallback model list and
+does not import the local `cursor-agent` credential cache. Individual usage
+comes from Cursor dashboard endpoints; the documented Admin API covers team
+usage.
+
+The plugin follows DSH network settings. Its former proxy configuration and
+UI have been retired; an old plugin proxy config file is ignored.
+
+## Development
+
+```sh
+pnpm install --frozen-lockfile
+pnpm build
+pnpm test
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the PR workflow, test boundaries,
+and isolated DSH checks.
+
+The tests and checks (unit and integration tests, the host-export and host
+contract checks, the boot smoke, and the host E2E) are documented in [docs/testing.md](docs/testing.md); the DSH
+support window and release process in
+[docs/compatibility.md](docs/compatibility.md).
+
+The package is published to npm as `dsh-subscriptions`, starting with the first release under the new name (GitHub source installation remains supported). The `cordis.patch.yml` bundle entry and browser module ID use the same package name. Earlier releases were published as `@goodboys-ai/dsh-subscription-hub`; that name will be deprecated in favor of `dsh-subscriptions`. If the old scoped package is installed, remove it before adding the new one — installing both registers the same adapters twice and breaks plugin load.
+
+## Origins
+
+This project started from [V1ki/dsh-plugin-subscriptions](https://github.com/V1ki/dsh-plugin-subscriptions) at `090d964` under its MIT license and now includes upstream `0.9.5` (`75a8346`). The upstream English and Chinese READMEs are kept in [`docs/upstream-README.md`](docs/upstream-README.md) and [`docs/upstream-README.zh.md`](docs/upstream-README.zh.md).

package/cordis.patch.yml

@@ -0,0 +1,12 @@
+# Bundle self-activation patch: when this package is installed into a profile
+# via `dsh plugin --profile web add dsh-subscriptions`
+# (or a local checkout), this patch mounts the plugin's node half. The client
+# half (Settings > Subscriptions page) is discovered automatically from the
+# `dsh.client` declaration in package.json.
+#
+# Headless usage without installing into the profile (node half only; log in
+# from a web profile first, the token file is shared):
+#   pnpm dsh --profile headless --patch <this-checkout>/overlay.yml "task"
+- insert:
+    - id: llm-subscriptions
+      name: 'dsh-subscriptions'

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 { hostFetch } 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 ?? hostFetch;
+        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;
+}