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

package/lib/auth/oauth-flow.js

@@ -0,0 +1,227 @@
+/**
+ * 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 { createServer } from 'node:http';
+import { createPkce, randomHex, randomToken } from './pkce.js';
+/** Default attempt lifetime: three minutes for the user to complete login. */
+export const DEFAULT_FLOW_TIMEOUT_MS = 180_000;
+const SUCCESS_PAGE = '<!doctype html><html><head><meta charset="utf-8"><title>Login successful</title></head>'
+    + '<body style="font-family:sans-serif"><h1>Login successful</h1>'
+    + '<p>You can close this tab and return to DeepSeek Harness.</p></body></html>';
+function failurePage(detail) {
+    return '<!doctype html><html><head><meta charset="utf-8"><title>Login failed</title></head>'
+        + `<body style="font-family:sans-serif"><h1>Login failed</h1><p>${detail.replace(/[<>&]/g, '')}</p></body></html>`;
+}
+/**
+ * Loopback addresses one listen host covers. `localhost` resolves to ::1 or
+ * 127.0.0.1 depending on the client, and Node binds exactly one of them per
+ * listen call — a browser picking the other family gets connection-refused
+ * and the login times out, so both families must serve the callback.
+ */
+function listenHosts(host) {
+    return host === 'localhost' ? ['127.0.0.1', '::1'] : [host];
+}
+/** True when the address family does not exist on this machine (safe to skip), unlike a taken port. */
+function familyUnavailable(error) {
+    const code = error.code;
+    return code === 'EADDRNOTAVAIL' || code === 'EPROTONOSUPPORT';
+}
+/**
+ * Listen on the first port of the spec free on every loopback family;
+ * rejects when every port fails. Ephemeral ports (0) are retried so each
+ * family can be re-bound onto the first family's assigned port.
+ */
+async function listen(handler, spec) {
+    const hosts = listenHosts(spec.host);
+    const candidates = spec.ports.flatMap(port => (port === 0 ? [0, 0, 0] : [port]));
+    let lastError;
+    for (const candidate of candidates) {
+        const servers = [];
+        let port = candidate;
+        let unusable = false;
+        for (const host of hosts) {
+            const server = createServer(handler);
+            try {
+                await new Promise((resolve, reject) => {
+                    const onError = (error) => reject(error);
+                    server.once('error', onError);
+                    server.listen(port, host, () => {
+                        server.removeListener('error', onError);
+                        resolve();
+                    });
+                });
+                const address = server.address();
+                if (address === null)
+                    throw new Error(`callback server on ${host}:${port} has no address`);
+                if (port === 0)
+                    port = address.port;
+                servers.push(server);
+            }
+            catch (error) {
+                server.close();
+                if (familyUnavailable(error))
+                    continue;
+                lastError = error;
+                unusable = true;
+                break;
+            }
+        }
+        if (unusable || servers.length === 0) {
+            for (const server of servers)
+                server.close();
+            continue;
+        }
+        return { servers, port };
+    }
+    throw lastError instanceof Error
+        ? lastError
+        : new Error(`callback server could not listen on ${spec.host} (ports ${spec.ports.join(', ')})`);
+}
+/**
+ * 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 class OAuthFlowManager {
+    attempts = new Map();
+    /**
+     * 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) {
+        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 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.
+     */
+    async start(provider, spec) {
+        if (this.attempts.has(provider)) {
+            throw new Error(`a ${provider} login attempt is already in progress`);
+        }
+        const input = {
+            redirectUri: '',
+            state: randomToken(32),
+            pkce: createPkce(),
+            nonce: randomHex(8),
+        };
+        const timeoutMs = spec.timeoutMs ?? DEFAULT_FLOW_TIMEOUT_MS;
+        let resolveCode;
+        let rejectCode;
+        const codePromise = new Promise((resolve, reject) => {
+            resolveCode = resolve;
+            rejectCode = reject;
+        });
+        let settled = false;
+        let timer;
+        let servers = [];
+        const handler = (request, response) => {
+            const url = new URL(request.url ?? '/', 'http://localhost');
+            if (url.pathname !== spec.callbackPath) {
+                response.writeHead(404, { 'content-type': 'text/plain' });
+                response.end('not found');
+                return;
+            }
+            const errorDescription = url.searchParams.get('error_description') ?? url.searchParams.get('error');
+            if (errorDescription !== null) {
+                response.writeHead(200, { 'content-type': 'text/html' });
+                response.end(failurePage(errorDescription));
+                settle(new Error(`authorization failed: ${errorDescription}`));
+                return;
+            }
+            if (url.searchParams.get('state') !== input.state) {
+                // A stray or replayed redirect must not kill the real attempt.
+                response.writeHead(400, { 'content-type': 'text/plain' });
+                response.end('state mismatch');
+                return;
+            }
+            const code = url.searchParams.get('code');
+            if (code === null || code.length === 0) {
+                response.writeHead(400, { 'content-type': 'text/plain' });
+                response.end('missing authorization code');
+                return;
+            }
+            response.writeHead(200, { 'content-type': 'text/html' });
+            response.end(SUCCESS_PAGE);
+            settle(undefined, code);
+        };
+        const settle = (error, code) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            for (const server of servers) {
+                server.close();
+                server.closeAllConnections();
+            }
+            this.attempts.delete(provider);
+            if (error !== undefined)
+                rejectCode(error);
+            else if (code !== undefined)
+                resolveCode(code);
+        };
+        const bound = await listen(handler, spec.listen);
+        servers = bound.servers;
+        input.redirectUri = `http://${spec.listen.host}:${bound.port}${spec.callbackPath}`;
+        timer = setTimeout(() => {
+            settle(new Error(`login timed out after ${Math.round(timeoutMs / 1000)}s`));
+        }, timeoutMs);
+        timer.unref();
+        const attempt = {
+            authorizeUrl: spec.buildAuthorizeUrl(input),
+            redirectUri: input.redirectUri,
+            pkce: input.pkce,
+            state: input.state,
+            waitCode: () => codePromise,
+            manual(rawInput) {
+                if (settled)
+                    throw new Error(`the ${provider} login attempt already finished`);
+                const trimmed = rawInput.trim();
+                let code;
+                let pastedState;
+                if (/^https?:\/\//i.test(trimmed)) {
+                    const url = new URL(trimmed);
+                    code = url.searchParams.get('code') ?? undefined;
+                    pastedState = url.searchParams.get('state') ?? undefined;
+                }
+                else if (trimmed.includes('code=')) {
+                    const params = new URLSearchParams(trimmed);
+                    code = params.get('code') ?? undefined;
+                    pastedState = params.get('state') ?? undefined;
+                }
+                else if (trimmed.length > 0 && !/\s/.test(trimmed)) {
+                    code = trimmed;
+                }
+                if (code === undefined || code.length === 0) {
+                    throw new Error('no authorization code found in the pasted input');
+                }
+                if (pastedState !== undefined && pastedState !== input.state) {
+                    throw new Error('state mismatch: the pasted URL belongs to a different login attempt');
+                }
+                settle(undefined, code);
+            },
+            cancel() {
+                settle(new Error('login cancelled'));
+            },
+        };
+        this.attempts.set(provider, attempt);
+        return attempt;
+    }
+}

package/lib/auth/pkce.d.ts

@@ -0,0 +1,31 @@
+/** PKCE (RFC 7636) and random-token helpers for the OAuth login flows. */
+/** One PKCE verifier/challenge pair; the verifier stays local until the token exchange. */
+export interface PkcePair {
+    /** High-entropy secret sent as `code_verifier` at the token endpoint. */
+    verifier: string;
+    /** S256 digest of the verifier, sent as `code_challenge` at the authorize endpoint. */
+    challenge: string;
+}
+/**
+ * Base64url-encode without padding.
+ * @param buffer - raw bytes.
+ * @returns the RFC 4648 §5 encoding.
+ */
+export declare function base64url(buffer: Buffer): string;
+/**
+ * Mint a fresh PKCE pair (32-byte verifier, S256 challenge).
+ * @returns the pair for one authorization attempt.
+ */
+export declare function createPkce(): PkcePair;
+/**
+ * Mint a URL-safe random token (default 16 bytes) for OAuth `state`.
+ * @param bytes - entropy length.
+ * @returns base64url-encoded random bytes.
+ */
+export declare function randomToken(bytes?: number): string;
+/**
+ * Mint lowercase-hex random bytes (for Grok's `nonce` parameter).
+ * @param bytes - entropy length; the hex string is twice as long.
+ * @returns hex-encoded random bytes.
+ */
+export declare function randomHex(bytes?: number): string;

package/lib/auth/pkce.js

@@ -0,0 +1,35 @@
+/** PKCE (RFC 7636) and random-token helpers for the OAuth login flows. */
+import { createHash, randomBytes } from 'node:crypto';
+/**
+ * Base64url-encode without padding.
+ * @param buffer - raw bytes.
+ * @returns the RFC 4648 §5 encoding.
+ */
+export function base64url(buffer) {
+    return buffer.toString('base64url');
+}
+/**
+ * Mint a fresh PKCE pair (32-byte verifier, S256 challenge).
+ * @returns the pair for one authorization attempt.
+ */
+export function createPkce() {
+    const verifier = base64url(randomBytes(32));
+    const challenge = base64url(createHash('sha256').update(verifier).digest());
+    return { verifier, challenge };
+}
+/**
+ * Mint a URL-safe random token (default 16 bytes) for OAuth `state`.
+ * @param bytes - entropy length.
+ * @returns base64url-encoded random bytes.
+ */
+export function randomToken(bytes = 32) {
+    return base64url(randomBytes(bytes));
+}
+/**
+ * Mint lowercase-hex random bytes (for Grok's `nonce` parameter).
+ * @param bytes - entropy length; the hex string is twice as long.
+ * @returns hex-encoded random bytes.
+ */
+export function randomHex(bytes = 8) {
+    return randomBytes(bytes).toString('hex');
+}

package/lib/auth/rpc.d.ts

@@ -0,0 +1,233 @@
+/**
+ * The `subscriptions-auth` host RPC endpoints the web Settings page drives.
+ * They are mounted as exact POST Fetch routes on the shared `/api` channel
+ * (`/api/subscriptions-auth.<endpoint>`) and registered only when a host
+ * `connection` service exists (the web profile); headless compositions load
+ * the plugin without it. All business outcomes are returned as RpcResult
+ * values; handlers never throw.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { RpcResult } from '../compat.js';
+import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+import { type ProviderId } from './store.js';
+import type { ProviderUsage } from '../providers/common.js';
+import type { UsageReadReason } from '../usage/service.js';
+import type { KeyProviderId, KeyProviderView, UsageProviderId } from '../usage-providers/index.js';
+import type { ProxyConfigView, ProxyDraft, ProxyInput, ProxyTestResult } from '../http.js';
+import type { CliVersion } from '../providers/npm-cli-version.js';
+/** Internal endpoint dispatcher used after the host authenticates an exact Fetch route. */
+export type SubscriptionsRpcHandler = (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<RpcResult<unknown>>;
+/**
+ * Endpoint-name prefix under the shared `/api` channel: endpoint `status`
+ * is served at `/api/subscriptions-auth.status`. The browser half calls
+ * `rpc.call('/api', 'subscriptions-auth.status', payload)`.
+ */
+export declare const SUBSCRIPTIONS_AUTH_PREFIX = "subscriptions-auth.";
+/**
+ * Every endpoint {@link dispatch} answers; each gets one exact Fetch route.
+ * Kept in one place so the route table and the switch cannot drift apart.
+ */
+export declare const SUBSCRIPTIONS_AUTH_ENDPOINTS: readonly ["providerSettings", "setProviderSettings", "status", "login", "manual", "cancel", "logout", "setDefault", "usage", "image", "video", "prepareReset", "consumeReset", "speed", "setSpeed", "proxyGet", "proxySet", "proxyTest", "keysSet", "keysRemove", "modelDefaults", "setModelDefault"];
+/** Decoded image bytes returned by the `image` endpoint. */
+export interface ImageBytesResult {
+    mediaType: string;
+    dataBase64: string;
+}
+/** Decoded video bytes returned by the `video` endpoint. */
+export interface VideoBytesResult {
+    mediaType: string;
+    dataBase64: string;
+}
+/** One session's speed choice: standard routing or the fast (priority) tier. */
+export type SpeedTier = 'standard' | 'fast';
+/** `speed` endpoint value: the session's choice plus the visibility list. */
+export interface SpeedState {
+    /** Explicit session speed, or the subagent's model default when supplied. */
+    tier: SpeedTier;
+    /** Codex model ids whose catalog advertises a fast tier. */
+    fastModels: string[];
+}
+/** Session overrides plus persisted subagent model defaults. */
+export interface SpeedController {
+    /** Pass the current Codex model to resolve a subagent's default speed. */
+    speed(sessionId: string, model?: string): Promise<SpeedState>;
+    /** Set the session override and remember it for this model across restarts when supplied. */
+    setSpeed(sessionId: string, tier: SpeedTier, model?: string): Promise<void>;
+}
+/** One logged-in account, as rendered by the Settings page. */
+export interface AccountStatus {
+    /** Stable account key (store identity). */
+    key: string;
+    /** Display identity (email / login), when known. */
+    account?: string;
+    /** Epoch milliseconds at which the stored access token expires. */
+    expiresAt?: number;
+    /** Plan name the session carries (codex planType / claude subscriptionType), when known. */
+    plan?: string;
+    /** Whether direct (non-pool) routes serve this account. */
+    isDefault: boolean;
+}
+/** Login state of one provider, as rendered by the Settings page. */
+export interface ProviderStatus {
+    /** Short name for compact surfaces; attached by the status RPC. */
+    shortName?: string;
+    /** Whether the provider reports usage at all; attached by the status RPC. */
+    metered?: boolean;
+    /** The account that served this session's latest request, else the provider's latest. */
+    servingAccount?: string;
+    /** Model count of the saved catalog. */
+    catalogSize?: number;
+    /** Saved picker visibility, attached by the status RPC from local preferences. */
+    visibleModels?: string[];
+    displayName?: string;
+    /** Whether a login attempt is currently waiting for its code. */
+    busy: boolean;
+    /** Logged-in accounts, default first. */
+    accounts: AccountStatus[];
+    /** The last login error, shown until the next success. */
+    detail?: string;
+    /** The CLI version this route presents (Codex, Claude), and where it came from. */
+    clientVersion?: CliVersion;
+}
+/** How a Claude login should acquire credentials (other providers ignore it). */
+export type LoginMethod = 'oauth' | 'keychain';
+/** Proxy config operations behind the `proxyGet/proxySet/proxyTest` endpoints. */
+export interface ProxyConfigController {
+    /** Current proxy configuration (secrets omitted). */
+    get(): Promise<ProxyConfigView>;
+    /** Validate, persist, and apply one config. */
+    set(input: ProxyInput): Promise<ProxyConfigView>;
+    /** Probe one destination through the draft (unsaved) or stored proxy. */
+    test(payload: {
+        url?: string;
+        proxy?: ProxyDraft;
+    }): Promise<ProxyTestResult>;
+}
+/** One model's default-effort picker state, as rendered by the Settings page. */
+export interface ModelDefaultView {
+    /** Wire model id. */
+    id: string;
+    /** Human-readable display name. */
+    name: string;
+    /** Advertised effort levels, in catalog order (empty when the model has no reasoning). */
+    efforts: {
+        id: string;
+        name: string;
+    }[];
+    /** The user-configured default effort, when set. */
+    configured?: string;
+}
+/** One provider's default-effort picker state. */
+export interface ModelDefaultsCatalog {
+    /** The subscription provider route. */
+    provider: ProviderId;
+    /** Models the picker can configure, in catalog order. */
+    models: ModelDefaultView[];
+}
+/** Per-account catalog returned by providerSettings, including providers without usage APIs. */
+export interface ProviderAccountCatalog {
+    key: string;
+    /** Original identity; the editable alias lives in settings.accounts[key].alias. */
+    label: string;
+    models: {
+        id: string;
+        name: string;
+    }[];
+    unavailable?: boolean;
+}
+/** Provider and account preference operations behind providerSettings/setProviderSettings. */
+export interface ProviderSettingsController {
+    /** Local preferences only: status must not fetch a model catalog. */
+    displayName?(provider: ProviderId): string | undefined;
+    /** Local picker selection, without triggering model discovery. */
+    visibleModels?(provider: ProviderId): string[] | undefined;
+    /** Model count of the saved catalog, read from disk without discovery. */
+    catalogSize?(provider: ProviderId): Promise<number | undefined>;
+    get(provider: ProviderId, force: boolean): Promise<unknown>;
+    set(provider: ProviderId, settings: unknown): Promise<void>;
+}
+export interface ModelDefaultsController {
+    /** Per-provider picker state for the Settings page. */
+    catalog(force?: boolean): Promise<ModelDefaultsCatalog[]>;
+    /** Set one model's configured default effort; undefined clears the override. */
+    set(provider: ProviderId, model: string, effort: string | undefined): Promise<void>;
+}
+/** Provider-agnostic auth operations the RPC handler delegates to. */
+export interface AuthController {
+    prepareReset?(account: string, signal: AbortSignal): Promise<unknown>;
+    consumeReset?(account: string, ticket: string, signal: AbortSignal): Promise<void>;
+    /** Current status of one provider. */
+    status(provider: ProviderId, sessionId?: string): Promise<ProviderStatus>;
+    /** Bumped on every usage or serving-account change, so clients know to re-read. */
+    usageRevision?(): number;
+    /** Whether this provider has a usage endpoint in this composition. */
+    hasUsage?(provider: ProviderId): boolean;
+    /** Key providers (Z.ai, Ollama Cloud, Kimi Code) with whether a key is stored. */
+    keyProviders?(): Promise<KeyProviderView[]>;
+    /** Check a key with one usage read, then store it. */
+    setKey?(id: KeyProviderId, key: string): Promise<void>;
+    removeKey?(id: KeyProviderId): Promise<void>;
+    /**
+     * Start a background login attempt.
+     * @param provider - the provider route.
+     * @param method - Claude only: force the OAuth browser flow or the Claude
+     *   Code credential import; omitted keeps the auto behavior (import when
+     *   available, else OAuth).
+     * @returns the authorize URL for the user's browser; device-flow providers
+     *   (copilot) also return the `userCode` the user types at that URL.
+     * @throws when an attempt is already running for this provider.
+     */
+    login(provider: ProviderId, method?: LoginMethod): Promise<{
+        authorizeUrl: string;
+        userCode?: string;
+    }>;
+    /**
+     * Feed a pasted callback URL or bare code into the pending attempt.
+     * @throws when no attempt is pending or the input is unusable.
+     */
+    manual(provider: ProviderId, input: string): Promise<void>;
+    /** Abort the pending attempt; a no-op when none is pending. */
+    cancel(provider: ProviderId): Promise<void>;
+    /** Delete one account's stored session. */
+    logout(provider: ProviderId, account: string): Promise<void>;
+    /** Pin the account direct (non-pool) routes serve. */
+    setDefault(provider: ProviderId, account: string): Promise<void>;
+    /**
+     * Current subscription usage of one account.
+     * @param signal - caller cancellation from the RPC transport.
+     * @param force - bypass a fresh cached snapshot for an honest re-check
+     *   (the manual Refresh button); a live failure cooldown still applies.
+     * @returns `{ supported: false }` when the provider has no usage endpoint.
+     * @throws when logged out or the usage lookup fails.
+     */
+    usage(provider: UsageProviderId, account: string, signal: AbortSignal, force?: boolean, reason?: UsageReadReason): Promise<ProviderUsage>;
+    /**
+     * Read one image attachment's bytes for inline display.
+     * @param ref - the full durable reference (`readImage` verifies against it).
+     * @param signal - caller cancellation from the RPC transport.
+     * @returns the media type and base64-encoded bytes.
+     * @throws when no attachment service is mounted or the read fails.
+     */
+    readImage(ref: ImageAttachmentRef, signal: AbortSignal): Promise<ImageBytesResult>;
+    /**
+     * Read one generated video's bytes for inline playback.
+     * @param name - bare MP4 file name inside the plugin's videos directory
+     *   (validated against {@link VIDEO_NAME_PATTERN}; never a path).
+     * @param signal - caller cancellation from the RPC transport.
+     * @returns the media type and base64-encoded bytes.
+     * @throws when the file does not exist or cannot be read.
+     */
+    readVideo(name: string, signal: AbortSignal): Promise<VideoBytesResult>;
+}
+/** Payload carried no usable provider id — an RPC client bug, not a server failure. */
+export declare class BadRequest extends Error {
+}
+/**
+ * Register the `/subscriptions-auth` RPC channel when a host connection exists.
+ * @param ctx - the plugin context (headless profiles have no `connection`).
+ * @param controller - the auth operations backing the endpoints.
+ * @param speed - the per-session speed-tier state backing the Speed toggle.
+ * @param proxy - optional proxy-config controller backing `proxyGet`/`proxySet`/`proxyTest`.
+ * @param modelDefaults - optional per-model default-effort state backing `modelDefaults`/`setModelDefault`.
+ */
+export declare function registerAuthRpc(ctx: Context, controller: AuthController, speed: SpeedController, proxy?: ProxyConfigController | undefined, modelDefaults?: ModelDefaultsController | undefined, providerSettings?: ProviderSettingsController | undefined): void;