dsh-plugin-subscription-oauth 0.2.1 → 0.3.0

package/lib/index.js

@@ -21,15 +21,16 @@ import { createAntigravityProvider } from './providers/antigravity.js';
 import { createGrokProvider } from './providers/grok.js';
 import { createKimiProvider } from './providers/kimi-provider.js';
 import { createGlmProvider } from './providers/glm-provider.js';
+import { createArkProvider } from './providers/ark-provider.js';
 import { ModelPreferences } from './settings.js';
 /** Plugin id; also the name every effect label and log line is prefixed with. */
 export const name = 'dsh-plugin-subscription-oauth';
 /** The provider routes need the LLM runtime; everything else is optional. */
 export const inject = ['llm'];
 /** Every route key this plugin accepts in configuration. */
-export const PROVIDER_IDS = ['kimi', 'grok', 'antigravity', 'glm'];
+export const PROVIDER_IDS = ['kimi', 'grok', 'antigravity', 'glm', 'ark'];
 /** The routes this build can actually register. */
-export const IMPLEMENTED_PROVIDER_IDS = ['kimi', 'grok', 'antigravity', 'glm'];
+export const IMPLEMENTED_PROVIDER_IDS = ['kimi', 'grok', 'antigravity', 'glm', 'ark'];
 /** Configuration schema, with the config file's own defaults applied. */
 export const Config = z.object({
     providers: z.array(z.union([...PROVIDER_IDS])).default([...IMPLEMENTED_PROVIDER_IDS]),
@@ -123,6 +124,18 @@ export function apply(ctx, config = {}) {
                     fetchFn: proxiedFetch,
                 }));
                 break;
+            case 'ark':
+                routes.push(createArkProvider({
+                    credentialFile,
+                    discovery: config.discovery ?? true,
+                    streamIdleTimeoutMs,
+                    preferences,
+                    resolveAttachments: () => ctx.get('attachments'),
+                    onCatalogChanged: () => { reannounce('ark'); },
+                    onWarn,
+                    fetchFn: proxiedFetch,
+                }));
+                break;
             default:
                 // A configured route with no module yet must not silently disappear.
                 onWarn(`provider ${id} is configured but not implemented in this build`);

package/lib/providers/ark-provider.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The `ark` provider route's wiring: ZCode-style SSO sign-in, the control plane that
+ * mints the plan's API key, the model catalog, and the Settings card facts.
+ *
+ * Ark splits its API in two, and the route has to satisfy both:
+ *
+ * - the **data plane** (`ark.cn-beijing.volces.com`) serves the models and accepts
+ *   only an ordinary **API key** as a plain bearer — it refuses STS credentials
+ *   outright;
+ * - the **control plane** (`ark.cn-beijing.volcengineapi.com`) is signed with the
+ *   temporary **STS** credentials the SSO token response carries, and is where the
+ *   plan's API key and its allowance come from.
+ *
+ * So a sign-in produces both: the key for requests, the STS set for quota.
+ *
+ * @module dsh-plugin-subscription-oauth/providers/ark-provider
+ */
+import type { ProviderRoute } from '../auth/registry.js';
+import type { ModelPreferences } from '../settings.js';
+import type { FetchFn } from '../http.js';
+import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
+/** Everything the Ark route needs from the plugin configuration. */
+export interface ArkProviderOptions {
+    credentialFile: string;
+    apiBase?: string;
+    discovery: boolean;
+    streamIdleTimeoutMs: number;
+    defaultModel?: string;
+    extraModels?: readonly string[];
+    preferences: ModelPreferences;
+    resolveAttachments?: () => AttachmentStore | undefined;
+    onCatalogChanged?: () => void;
+    onWarn?: (message: string) => void;
+    fetchFn?: FetchFn;
+}
+/**
+ * Build the `ark` route.
+ *
+ * @param options - resolved endpoints, paths, and shared services.
+ * @returns the route, ready to register and to serve over RPC.
+ */
+export declare function createArkProvider(options: ArkProviderOptions): ProviderRoute;

package/lib/providers/ark-provider.js

@@ -0,0 +1,166 @@
+/**
+ * The `ark` provider route's wiring: ZCode-style SSO sign-in, the control plane that
+ * mints the plan's API key, the model catalog, and the Settings card facts.
+ *
+ * Ark splits its API in two, and the route has to satisfy both:
+ *
+ * - the **data plane** (`ark.cn-beijing.volces.com`) serves the models and accepts
+ *   only an ordinary **API key** as a plain bearer — it refuses STS credentials
+ *   outright;
+ * - the **control plane** (`ark.cn-beijing.volcengineapi.com`) is signed with the
+ *   temporary **STS** credentials the SSO token response carries, and is where the
+ *   plan's API key and its allowance come from.
+ *
+ * So a sign-in produces both: the key for requests, the STS set for quota.
+ *
+ * @module dsh-plugin-subscription-oauth/providers/ark-provider
+ */
+import { REAUTH_REQUIRED, ProviderError } from '../errors.js';
+import { TokenStore } from '../auth/store.js';
+import { TokenManager } from '../auth/tokens.js';
+import { LoopbackFlow } from '../auth/pkce-flow.js';
+import { ARK_CALLBACK_PATH, ARK_CALLBACK_PORTS, buildArkAuthorizeUrl, exchangeArkCode, refreshArkToken } from '../auth/ark-flow.js';
+import { createArkApiKey, listArkApiKeys, readArkApiKey } from '../auth/ark-control.js';
+import { ARK_API_BASE, ARK_CODE_URL, ARK_CONTEXT_WINDOW, ARK_DEFAULT_MODEL, ARK_PROVIDER_ID, ARK_PROVIDER_NAME, ArkAdapter, parseArkSession, readArkUsage, } from './ark.js';
+import { ProviderController } from '../auth/provider-controller.js';
+import { proxiedFetch } from '../http.js';
+/** The name the minted key is created under, so it is recognisable in the console. */
+const MINTED_KEY_NAME = 'dsh-plugin-subscription-oauth';
+/**
+ * Build the `ark` route.
+ *
+ * @param options - resolved endpoints, paths, and shared services.
+ * @returns the route, ready to register and to serve over RPC.
+ */
+export function createArkProvider(options) {
+    const fetchFn = options.fetchFn ?? proxiedFetch;
+    const apiBase = options.apiBase ?? ARK_API_BASE;
+    const store = new TokenStore(options.credentialFile, ARK_PROVIDER_ID, parseArkSession);
+    /**
+     * Turn a completed sign-in into a usable session.
+     *
+     * The API key is the credential the data plane takes, and the STS set is what
+     * mints it. An account that already holds a key this plugin created reuses it
+     * rather than piling up one per sign-in.
+     */
+    const toSession = async (tokens) => {
+        const sts = tokens.sts;
+        if (sts === undefined) {
+            throw new ProviderError('Ark sign-in returned no STS credentials, so the plan API key cannot be obtained', REAUTH_REQUIRED);
+        }
+        const existing = await listArkApiKeys({ credentials: sts, fetchFn })
+            .then((keys) => keys.find((key) => key.name === MINTED_KEY_NAME))
+            .catch((error) => {
+            options.onWarn?.(`Ark could not list existing keys (${error instanceof Error ? error.message : String(error)})`);
+            return undefined;
+        });
+        const id = existing?.id ?? await createArkApiKey({ credentials: sts, fetchFn, name: MINTED_KEY_NAME });
+        const apiKey = await readArkApiKey({ credentials: sts, fetchFn, id });
+        return {
+            accessToken: apiKey,
+            apiKey,
+            sts,
+            idToken: tokens.idToken,
+            expiresAt: tokens.expiresAt,
+            apiBase,
+            ...tokens.refreshToken === undefined ? {} : { refreshToken: tokens.refreshToken },
+        };
+    };
+    const flow = new LoopbackFlow(ARK_PROVIDER_ID, {
+        ports: ARK_CALLBACK_PORTS,
+        callbackPath: ARK_CALLBACK_PATH,
+        buildAuthorizeUrl: ({ redirectUri, state, pkce }) => buildArkAuthorizeUrl({ redirectUri, state, pkce }),
+        exchange: async ({ code, redirectUri, pkce, signal }) => toSession(await exchangeArkCode({ fetchFn, code, redirectUri, pkce, signal })),
+    });
+    const tokens = new TokenManager({
+        store,
+        displayName: ARK_PROVIDER_NAME,
+        // The identity token lives fifteen minutes, so a session has to renew to stay
+        // usable; the refresh grant returns a fresh id token and a fresh STS set.
+        preemptMs: 5 * 60 * 1000,
+        refresh: async (session) => {
+            const refreshToken = session.refreshToken;
+            if (refreshToken === undefined) {
+                throw new ProviderError(`${ARK_PROVIDER_NAME} account has no refresh token; sign in again`, REAUTH_REQUIRED);
+            }
+            const renewed = await refreshArkToken({ fetchFn, refreshToken });
+            // The API key outlives the identity token, so a renewal only has to carry the
+            // new STS set forward for the quota; the key itself is unchanged.
+            return {
+                accessToken: session.apiKey,
+                apiKey: session.apiKey,
+                expiresAt: renewed.expiresAt,
+                ...renewed.sts === undefined ? {} : { sts: renewed.sts },
+                ...renewed.refreshToken === undefined ? {} : { refreshToken: renewed.refreshToken },
+            };
+        },
+    });
+    const adapter = new ArkAdapter({
+        apiBase,
+        discovery: options.discovery,
+        streamIdleTimeoutMs: options.streamIdleTimeoutMs,
+        tokens,
+        ...options.onWarn === undefined ? {} : { onWarn: options.onWarn },
+        ...options.resolveAttachments === undefined ? {} : { resolveAttachments: options.resolveAttachments },
+        hiddenModels: () => options.preferences.hiddenIds(ARK_PROVIDER_ID),
+        userModels: () => options.preferences.extraIds(ARK_PROVIDER_ID),
+        ...options.extraModels === undefined ? {} : { extraModels: options.extraModels },
+        fetchFn,
+    });
+    const spec = {
+        id: ARK_PROVIDER_ID,
+        displayName: ARK_PROVIDER_NAME,
+        codeUrl: ARK_CODE_URL,
+        credentialFile: options.credentialFile,
+        discovery: options.discovery,
+        defaultModel: options.defaultModel ?? ARK_DEFAULT_MODEL,
+        catalog: () => adapter.catalogEntries(),
+        catalogOwn: () => adapter.ownCatalogEntries(),
+        fallbackContextWindow: ARK_CONTEXT_WINDOW,
+        discover: (apiKey) => adapter.fetchCatalog(apiKey),
+        // The allowance is read with the STS credentials, not the data-plane key.
+        usage: async () => {
+            const held = await tokens.session();
+            const sts = held?.session.sts;
+            if (sts === undefined)
+                return { windows: [] };
+            return await readArkUsage({ credentials: sts, fetchFn });
+        },
+        details: () => [
+            { key: 'apiBase', value: apiBase },
+            { key: 'controlPlane', value: 'https://ark.cn-beijing.volcengineapi.com' },
+            { key: 'credentialFile', value: options.credentialFile },
+        ],
+        applyDiscovery: (ids) => { adapter.discover(ids); },
+    };
+    const controller = new ProviderController({
+        spec,
+        store,
+        tokens,
+        flow,
+        preferences: options.preferences,
+        ...options.onCatalogChanged === undefined ? {} : { onCatalogChanged: options.onCatalogChanged },
+        ...options.onWarn === undefined ? {} : { onWarn: options.onWarn },
+    });
+    // An explicit façade, not a spread: a spread would copy own properties and drop
+    // the class prototype, leaving every method undefined.
+    return {
+        id: controller.id,
+        displayName: controller.displayName,
+        credentialFile: controller.credentialFile,
+        adapter,
+        status: () => controller.status(),
+        login: (account) => controller.login(account),
+        cancel: () => controller.cancel(),
+        logout: (account) => controller.logout(account),
+        setDefault: (account) => controller.setDefault(account),
+        refresh: (account) => controller.refresh(account),
+        discover: (force) => controller.discover(force),
+        setModelVisible: (id, visible) => controller.setModelVisible(id, visible),
+        setModelOrder: (ids) => controller.setModelOrder(ids),
+        addModel: (id) => controller.addModel(id),
+        removeModel: (id) => controller.removeModel(id),
+        usage: (force) => controller.usage(force),
+        reload: () => controller.reload(),
+    };
+}

package/lib/providers/ark.d.ts

@@ -0,0 +1,154 @@
+/**
+ * The `ark` route: Volcengine Ark's Coding Plan over the OpenAI Responses wire.
+ *
+ * Everything in this module is pinned to what the endpoints themselves said:
+ *
+ * - `POST /api/coding/v3/responses` exists and wants a credential (401).
+ * - It accepts a **bearer Ark API key** and nothing else. An SSO identity token in
+ *   the same header is refused with `403 Unsupported zti authentication method`,
+ *   and an AK/SK signature with `403 Unsupported aksk authentication method`, while
+ *   a UUID-shaped key is looked up (`401 The API key doesn't exist`) and a
+ *   malformed one is told so (`401 The API key format is incorrect`). So the
+ *   credential is a UUID key, sent as a plain bearer — no request signing.
+ * - `/api/coding/v3` is documented by the official CLI as "OpenTOP + CodingPlan
+ *   API", and the catalogue below is the plan's roster.
+ *
+ * @module dsh-plugin-subscription-oauth/providers/ark
+ */
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { SessionBase } from '../auth/store.js';
+import type { TokenManager } from '../auth/tokens.js';
+import type { ArkStsCredentials } from '../auth/ark-control.js';
+import type { FetchFn } from '../http.js';
+import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
+import type { CatalogEntry } from './catalog.js';
+import type { UsageRead } from './usage.js';
+/** Provider route this module serves. */
+export declare const ARK_PROVIDER_ID = "ark";
+/** Display name for the picker group and the Settings card. */
+export declare const ARK_PROVIDER_NAME = "Volcengine Ark";
+/** Page a user opens to manage the plan. */
+export declare const ARK_CODE_URL = "https://console.volcengine.com/ark/region:ark+cn-beijing/overview";
+/** Coding-plan base; the Responses endpoint is `<base>/responses`. */
+export declare const ARK_API_BASE = "https://ark.cn-beijing.volces.com/api/coding/v3";
+/** Origin the account-level endpoints hang off. */
+export declare const ARK_ORIGIN = "https://ark.cn-beijing.volces.com";
+/** Path appended to the API base for a streaming request. */
+export declare const ARK_RESPONSES_PATH = "/responses";
+/** Model the picker preselects: the plan's own alias for its coding model. */
+export declare const ARK_DEFAULT_MODEL = "ark-code-latest";
+/**
+ * Context capacity advertised for the plan's models.
+ *
+ * The Coding Plan is a curated, text-first roster and states no window per model;
+ * discovery refines this where the endpoint reports one.
+ */
+export declare const ARK_CONTEXT_WINDOW = 262144;
+/** Output budget used when the caller sets no cap. */
+export declare const ARK_DEFAULT_MAX_TOKENS = 32000;
+/** The plan's model roster, as the reference registry records it. */
+export declare const ARK_MODELS: readonly CatalogEntry[];
+/** One signed-in Ark account. */
+export interface ArkSession extends SessionBase {
+    /**
+     * The plan's API key.
+     *
+     * The data plane takes this as a plain bearer; the SSO identity token authorises
+     * the control plane that mints it, so the key — not the identity token — is what
+     * every model request carries.
+     */
+    apiKey: string;
+    /**
+     * Temporary STS credentials, used to sign control-plane calls.
+     *
+     * The SSO endpoint returns these in its `access_token`, which is where the plan
+     * allowance is read from; without them the route still serves models but states
+     * no quota.
+     */
+    sts?: ArkStsCredentials;
+    /** Identity token the key was minted under, for the control plane. */
+    idToken?: string;
+    /** API base recorded at login time (diagnostics only). */
+    apiBase?: string;
+}
+/**
+ * Coerce one decoded credential entry into an Ark session.
+ *
+ * @param value - decoded JSON value for one account.
+ * @returns the session, or undefined when required fields are missing.
+ */
+export declare function parseArkSession(value: unknown): ArkSession | undefined;
+/** Everything the adapter needs from the route. */
+export interface ArkAdapterOptions {
+    apiBase: string;
+    discovery: boolean;
+    streamIdleTimeoutMs: number;
+    tokens: TokenManager<ArkSession>;
+    hiddenModels?: () => Promise<ReadonlySet<string>> | ReadonlySet<string>;
+    userModels?: () => Promise<readonly string[]> | readonly string[];
+    extraModels?: readonly string[];
+    resolveAttachments?: () => AttachmentStore | undefined;
+    onWarn?: (message: string) => void;
+    onCredentialRejected?: (account: string) => void;
+    fetchFn?: FetchFn;
+}
+/** The adapter behind the `ark` route. */
+export declare class ArkAdapter extends LlmAdapter {
+    private readonly options;
+    private live;
+    constructor(options: ArkAdapterOptions);
+    providerInfo(provider: string): LlmProviderInfo;
+    providerRetryPolicy(): undefined;
+    listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
+    resolveModel(_provider: string, model: string): Promise<LlmResolvedModelInfo>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    /** Translate an auth failure into the message a user can act on. */
+    private refreshHint;
+    private catalog;
+    private shippedCatalog;
+    private addedEntries;
+    private hidden;
+    /** Adopt the endpoint's live catalog. */
+    discover(ids: readonly string[]): void;
+    /**
+     * Read the plan's live model list.
+     *
+     * The Coding Plan answers the OpenAI models shape on its own base; an endpoint
+     * that does not serve it leaves the shipped roster in place.
+     */
+    fetchCatalog(apiKey: string, signal?: AbortSignal): Promise<readonly string[] | undefined>;
+    /** Send one streaming request over the Responses wire. */
+    private request;
+    /** Resolve image blocks through the attachment service, when it is present. */
+    private imageResolver;
+    /** The catalog the controller publishes without hand-added ids. */
+    ownCatalogEntries(): readonly CatalogEntry[];
+    /** The catalog the controller publishes. */
+    catalogEntries(): readonly CatalogEntry[];
+}
+/**
+ * Read the plan's allowance.
+ *
+ * Two allowances exist, and both live on the **control plane** — a different host
+ * from the data plane, reached with the STS AK/SK the SSO identity was exchanged
+ * for (see `auth/ark-control.ts`) rather than with the plan API key:
+ *
+ * - the **subscription** periods (`GetCodingPlanUsage` → `coding_usage.periods[]`,
+ *   each `{ label, used, total, percent, reset_at }`), which an account without a
+ *   plan answers as `Status: Reclaimed`;
+ * - the **free inference allowance** per model (`ListModelChargeItems` →
+ *   `InferenceFreeUsage { Consumed, Total }`), which exists with no subscription.
+ *
+ * The free allowance is what a plan-less account actually has, so it is reported
+ * even when the subscription is absent — otherwise the card would say "no quota"
+ * while the account still had tokens to spend.
+ *
+ * @param input - the signed control-plane client.
+ * @returns the windows the service stated, subscription first.
+ */
+export declare function readArkUsage(input: {
+    credentials: ArkStsCredentials;
+    fetchFn: FetchFn;
+    signal?: AbortSignal;
+}): Promise<UsageRead>;