dsh-plugin-subscriptions 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+# dsh-plugin-subscriptions
+
+English | [中文](README.zh.md)
+
+Use your **ChatGPT (Codex)**, **Claude**, and **Grok (X Premium)** subscriptions as LLM providers in [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — no API keys. Login happens in the dsh web UI (Settings → Subscriptions); tokens live at `~/.dsh/plugins/subscriptions/auth.json` (mode 0600) and refresh automatically.
+
+## Providers
+
+| Route    | Subscription      | Models |
+|----------|-------------------|--------|
+| `codex`  | ChatGPT Plus/Pro  | live catalog from `chatgpt.com/backend-api/codex/models` |
+| `claude` | Claude Pro/Max    | claude-opus-4-5, claude-sonnet-4-5, claude-haiku-4-5 |
+| `grok`   | X Premium (xAI)   | live catalog from `api.x.ai/v1/models` (chat models only) |
+
+Only logged-in providers appear in the session model picker; the lists above refresh on login/logout. Vision-capable models declare `['text', 'image']` input modalities, and image content is translated to each provider's wire format.
+
+Also included, registered when the matching provider is enabled:
+
+- **`x_search`** tool (Grok) — xAI's hosted X search, returning `{ answer, citations }`.
+- **`image_generate`** tool (ChatGPT) — `gpt-image-2` via the Codex backend; PNGs are saved under `~/.dsh/plugins/subscriptions/images/` and the paths returned.
+
+## Install
+
+With the `dsh` CLI available:
+
+```sh
+dsh plugin --profile web add github:V1ki/dsh-plugin-subscriptions
+```
+
+pnpm will ask you to allow this package's build script on first install (git installs fetch sources, not built artifacts); add the printed key to the profile's `pnpm-workspace.yaml`:
+
+```yaml
+allowBuilds:
+  dsh-plugin-subscriptions: true
+```
+
+and re-run the `add`. Only grant this to packages you trust — it runs the package's code at install time.
+
+From a local checkout instead:
+
+```sh
+git clone https://github.com/V1ki/dsh-plugin-subscriptions.git
+cd dsh-plugin-subscriptions && pnpm install && pnpm build
+dsh plugin --profile web add ./dsh-plugin-subscriptions
+```
+
+Headless-only usage without installing into a profile (log in via the web UI first — the token file is shared):
+
+```sh
+dsh --profile headless --patch <checkout>/overlay.yml "your task"
+```
+
+## Use
+
+1. `dsh web`, open the printed URL.
+2. Settings → **Subscriptions**: click **Log in** on a provider and authorize in the opened tab. If the browser flow can't complete (headless host), expand the manual fallback and paste the callback URL or code.
+3. In any session, open the model picker (`/model`) and choose a model under **ChatGPT (Codex)** / **Claude (Subscription)** / **Grok (Subscription)**.
+
+Not logged in? The provider stays out of the picker, and requests fail with `MISSING_CREDENTIAL` pointing at the Settings page; nothing else breaks.
+
+## Config
+
+```yaml
+- id: llm-subscriptions
+  name: dsh-plugin-subscriptions
+  config:
+    providers: [codex, claude]        # subset; default all three
+    streamIdleTimeoutMs: 300000
+    models:                            # override the discovered/built-in catalogs
+      codex:
+        - { id: gpt-5.6-sol, name: GPT-5.6 Sol, contextWindow: 272000, inputModalities: [text, image] }
+```
+
+## Develop
+
+```sh
+pnpm install   # devDependencies link into a local deepseek-harness checkout — edit the paths first
+pnpm build     # tsc (lib/) + tsdown (lib/client.js browser bundle)
+pnpm test      # node --test over compiled unit specs
+```
+
+`prepare` (used by git installs) runs `tsdown.prepare.config.ts`: a self-contained bundle build of both faces with all `@deepseek-ai/*` specifiers external — they resolve from the dsh installation at runtime, so this package never carries a second cordis copy.
+
+After `pnpm build`, restart `dsh web` to pick up changes.
+
+## Layout
+
+- `src/index.ts` — plugin entry: config schema, adapter registration, auth-change re-announce, RPC wiring
+- `src/auth/` — PKCE/JWT helpers, token store, OAuth flow engine (temp loopback callback server), `/subscriptions-auth` RPC channel
+- `src/providers/` — per-provider OAuth constants/exchange/refresh + `LlmAdapter`s
+- `src/translate/` — dsh `Message[]` ⟷ OpenAI Responses / Anthropic Messages wire formats, SSE → `StreamChunk`
+- `src/tools/` — `x_search` and `image_generate`
+- `src/client/` — the Settings → Subscriptions page (browser half, zh/en, theme-token aware)

package/README.zh.md

@@ -0,0 +1,93 @@
+# dsh-plugin-subscriptions
+
+[English](README.md) | 中文
+
+把你的 **ChatGPT(Codex)**、**Claude**、**Grok(X Premium)**订阅当作 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 LLM provider 使用 —— 不需要 API key。登录在 dsh web 界面完成(设置 → 订阅);token 保存在 `~/.dsh/plugins/subscriptions/auth.json`(权限 0600),过期自动刷新。
+
+## Provider 一览
+
+| 路由     | 订阅             | 模型 |
+|----------|------------------|------|
+| `codex`  | ChatGPT Plus/Pro | 从 `chatgpt.com/backend-api/codex/models` 实时获取 |
+| `claude` | Claude Pro/Max   | claude-opus-4-5、claude-sonnet-4-5、claude-haiku-4-5 |
+| `grok`   | X Premium (xAI)  | 从 `api.x.ai/v1/models` 实时获取(仅对话模型) |
+
+只有已登录的 provider 才会出现在会话模型选择器里;登录/退出后列表自动刷新。支持视觉的模型会声明 `['text', 'image']` 输入模态,图片内容会被翻译成各 provider 的 wire 格式。
+
+随 provider 启用自动注册的工具:
+
+- **`x_search`**(Grok)—— xAI 托管的 X 搜索,返回 `{ answer, citations }`。
+- **`image_generate`**(ChatGPT)—— 经 Codex 后端调用 `gpt-image-2`;生成的 PNG 保存到 `~/.dsh/plugins/subscriptions/images/` 并返回路径。
+
+## 安装
+
+本机已有 `dsh` CLI 时:
+
+```sh
+dsh plugin --profile web add github:V1ki/dsh-plugin-subscriptions
+```
+
+首次安装 pnpm 会要求允许该包的构建脚本(git 安装拉取的是源码而非构建产物);把打印出的包名加进 profile 的 `pnpm-workspace.yaml`:
+
+```yaml
+allowBuilds:
+  dsh-plugin-subscriptions: true
+```
+
+然后重新执行 `add`。该授权会在安装时执行包的代码,只授给你信任的来源。
+
+本地检出安装:
+
+```sh
+git clone https://github.com/V1ki/dsh-plugin-subscriptions.git
+cd dsh-plugin-subscriptions && pnpm install && pnpm build
+dsh plugin --profile web add ./dsh-plugin-subscriptions
+```
+
+不装进 profile 的 headless 用法(先在 web 界面登录过 —— token 文件是共享的):
+
+```sh
+dsh --profile headless --patch <检出目录>/overlay.yml "你的任务"
+```
+
+## 使用
+
+1. `dsh web`,打开打印的 URL。
+2. **设置 → 订阅**:点对应 provider 的「登录」,在打开的标签页里授权。无浏览器环境下可展开手动兜底,粘贴回调 URL 或授权码。
+3. 在任意会话里打开模型选择器(`/model`),选择 **ChatGPT (Codex)** / **Claude (Subscription)** / **Grok (Subscription)** 下的模型。
+
+未登录时:该 provider 不出现在选择器里;直接请求会报 `MISSING_CREDENTIAL` 并提示去设置页登录,不影响其他功能。
+
+## 配置
+
+```yaml
+- id: llm-subscriptions
+  name: dsh-plugin-subscriptions
+  config:
+    providers: [codex, claude]        # 子集;默认三个全启用
+    streamIdleTimeoutMs: 300000
+    models:                            # 覆盖实时发现/内置目录
+      codex:
+        - { id: gpt-5.6-sol, name: GPT-5.6 Sol, contextWindow: 272000, inputModalities: [text, image] }
+```
+
+## 开发
+
+```sh
+pnpm install   # devDependencies 用 link: 指向本地 deepseek-harness 检出 —— 先改成你的路径
+pnpm build     # tsc(lib/)+ tsdown(lib/client.js 浏览器 bundle)
+pnpm test      # 编译后跑 node --test 单测
+```
+
+`prepare`(git 安装时触发)执行 `tsdown.prepare.config.ts`:自包含打包两个面,所有 `@deepseek-ai/*` 依赖外部化 —— 运行时从 dsh 安装解析,保证不会引入第二份 cordis。
+
+改了代码后 `pnpm build` 并重启 `dsh web` 生效。
+
+## 目录结构
+
+- `src/index.ts` —— 插件入口:配置 schema、adapter 注册、登录态变更通告、RPC 接线
+- `src/auth/` —— PKCE/JWT 工具、token 存储、OAuth 流程引擎(临时本地回调服务)、`/subscriptions-auth` RPC 通道
+- `src/providers/` —— 各 provider 的 OAuth 常量/换发/刷新 + `LlmAdapter` 实现
+- `src/translate/` —— dsh `Message[]` 与 OpenAI Responses / Anthropic Messages 格式互转,SSE → `StreamChunk`
+- `src/tools/` —— `x_search` 与 `image_generate`
+- `src/client/` —— 设置 → 订阅页面(浏览器面,中英文,跟随明暗主题)

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-plugin-subscriptions` (or a local
+# checkout / git URL), 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-plugin-subscriptions

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

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(16),
+            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 = 16) {
+    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,51 @@
+/**
+ * The `/subscriptions-auth` host RPC channel the web Settings page drives. The
+ * channel is 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 ProviderId } from './store.js';
+/** The RPC channel this plugin registers on the host connection. */
+export declare const SUBSCRIPTIONS_AUTH_CHANNEL = "/subscriptions-auth";
+/** Login state of one provider, as rendered by the Settings page. */
+export interface ProviderStatus {
+    /** Whether a session exists in the store. */
+    loggedIn: boolean;
+    /** Whether a login attempt is currently waiting for its code. */
+    busy: boolean;
+    /** Epoch milliseconds at which the stored access token expires. */
+    expiresAt?: number;
+    /** Account email or account id, when known. */
+    account?: string;
+    /** Subscription detail (plan) or the last login error. */
+    detail?: string;
+}
+/** 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.
+     * @returns the authorize URL for the user's browser.
+     * @throws when an attempt is already running for this provider.
+     */
+    login(provider: ProviderId): Promise<{
+        authorizeUrl: 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 the stored session. */
+    logout(provider: ProviderId): 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.
+ */
+export declare function registerAuthRpc(ctx: Context, controller: AuthController): void;