dsh-subscriptions 0.1.0

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>;
+}

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,209 @@
+/**
+ * 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 { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+import { type ProviderId } from './store.js';
+import type { ProviderUsage } from '../providers/common.js';
+import type { CliVersion } from '../providers/npm-cli-version.js';
+import type { ExternalUsageSource, ExternalUsageStatus } from '../providers/external-usage-controller.js';
+import type { CursorAuthStatus } from '../providers/cursor-auth.js';
+/**
+ * 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", "externalStatus", "externalUsage", "cursorStatus", "cursorLogin", "cursorCancel", "cursorLogout", "cursorUsage", "cursorModels", "cursorSettings", "cursorSetSettings", "image", "video", "speed", "setSpeed", "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 {
+    /** The session's current speed tier (default `standard`). */
+    tier: SpeedTier;
+    /** Codex model ids whose catalog advertises a fast tier. */
+    fastModels: string[];
+}
+/** Speed state the RPC handler delegates to (in-memory, per session). */
+export interface SpeedController {
+    /** Current speed state: the session's tier and the fast-capable codex models. */
+    speed(sessionId: string): Promise<SpeedState>;
+    /** Set one session's speed tier. */
+    setSpeed(sessionId: string, tier: SpeedTier): 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 {
+    /** 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';
+/** 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 {
+    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 {
+    /** Current status of one provider. */
+    status(provider: ProviderId): Promise<ProviderStatus>;
+    /**
+     * 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: ProviderId, account: string, signal: AbortSignal, force?: boolean): 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 {
+}
+/** Credential-backed quota readers for model providers already in DSH. */
+export interface ExternalUsageRpcController {
+    status(): Promise<Record<ExternalUsageSource, ExternalUsageStatus>>;
+    usage(source: ExternalUsageSource, signal: AbortSignal): Promise<ProviderUsage>;
+}
+/** Cursor account actions; OAuth tokens remain in the host credential service. */
+export interface CursorRpcController {
+    status(): Promise<CursorAuthStatus>;
+    login(): Promise<{
+        authorizeUrl: string;
+    }>;
+    cancel(): Promise<void>;
+    logout(): Promise<void>;
+    usage(signal: AbortSignal): Promise<ProviderUsage>;
+    models(force: boolean, signal: AbortSignal): Promise<{
+        id: string;
+        name: string;
+    }[]>;
+    settings(force: boolean, signal: AbortSignal): Promise<unknown>;
+    setSettings(input: unknown): Promise<void>;
+}
+/**
+ * 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 modelDefaults - optional per-model default-effort state backing `modelDefaults`/`setModelDefault`.
+ */
+export declare function registerAuthRpc(ctx: Context, controller: AuthController, speed: SpeedController, modelDefaults?: ModelDefaultsController | undefined, providerSettings?: ProviderSettingsController | undefined, externalUsage?: ExternalUsageRpcController | undefined, cursor?: CursorRpcController | undefined): void;