dsh-sub2api-sync 0.0.0-stage → 0.1.0

package/lib/oauth.d.ts

@@ -0,0 +1,128 @@
+/**
+ * OAuth 2.1 Authorization Code + PKCE (S256) client for the sub2api provider.
+ *
+ * Implements the plugin-side half of the 2026-10-01 design:
+ * - endpoint discovery from `/.well-known/oauth-authorization-server`
+ *   (RFC 8414) with the `/api/v1/oauth/.well-known` compatibility alias as
+ *   the fallback — discovery failure means OAuth is unavailable;
+ * - PKCE: 64-char base64url verifier, S256 challenge only (never `plain`);
+ * - one-shot authorization attempts: `state` is single-use and expires with
+ *   the attempt, the verifier never leaves the host process, and the final
+ *   token exchange always re-submits the exact redirect_uri + verifier;
+ * - loopback-only redirect derivation: the receiver is this harness's
+   * webserver, so the origin must be 127.0.0.1 / [::1] (RFC 8252 §7.3 —
+ *   the port may vary, the path is the plugin's fixed callback route).
+ *
+ * @module sub2api-sync/oauth
+ */
+/** The public desktop client the sub2api provider seeds for this plugin. */
+export declare const OAUTH_CLIENT_ID = "dsh-sub2api-sync";
+/** The callback path this plugin registers on the harness webserver. */
+export declare const OAUTH_CALLBACK_PATH = "/plugins/dsh-sub2api-sync/oauth/callback";
+/** An authorization attempt lives exactly this long, state included. */
+export declare const OAUTH_ATTEMPT_TTL_MS: number;
+/** Scopes the plugin requests; `keys:revoke` only when orphan revocation is on. */
+export declare function oauthScopesFor(deleteOrphanKeys: boolean | undefined): string;
+/** Failure with the provider's OAuth error code attached (when present). */
+export declare class OAuthError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** The provider endpoints the plugin talks to (discovered, never hardcoded). */
+export interface OAuthEndpoints {
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    revocationEndpoint?: string;
+}
+/**
+ * Resolve the provider metadata: the standard RFC 8414 location first, the
+ * versioned compatibility alias second. A failed or incomplete document is a
+ * loud failure — the caller hides the OAuth channel instead of guessing URLs.
+ */
+export declare function discoverOAuthEndpoints(instance: string, fetchImpl?: typeof fetch, now?: number): Promise<OAuthEndpoints>;
+/** Test seam: drop the process-wide discovery cache. */
+export declare function resetDiscoveryCache(): void;
+/** One PKCE pair: base64url verifier (64 chars, RFC 7636 charset subset) + S256 challenge. */
+export declare function createPkcePair(): Promise<{
+    verifier: string;
+    challenge: string;
+}>;
+/** The exact loopback redirect URI for this harness session, or a loud reason. */
+export declare function loopbackCallbackOrigin(origin: string): string;
+export declare function buildAuthorizeUrl(endpoints: OAuthEndpoints, input: {
+    redirectUri: string;
+    scope: string;
+    state: string;
+    challenge: string;
+}): string;
+export interface OAuthTokenPair {
+    accessToken: string;
+    refreshToken?: string;
+    expiresIn?: number;
+    scope?: string;
+}
+/** Exchange the one-time code: verifier + exact redirect_uri ride again. */
+export declare function exchangeAuthorizationCode(endpoints: OAuthEndpoints, input: {
+    code: string;
+    redirectUri: string;
+    verifier: string;
+}, fetchImpl?: typeof fetch): Promise<OAuthTokenPair>;
+/** Rotating refresh: the provider answers a fresh access+refresh pair. */
+export declare function refreshAccessToken(endpoints: OAuthEndpoints, refreshToken: string, fetchImpl?: typeof fetch): Promise<OAuthTokenPair>;
+/** RFC 7009 revocation; best-effort by contract — failures resolve normally. */
+export declare function revokeToken(endpoints: OAuthEndpoints, token: string, fetchImpl?: typeof fetch): Promise<void>;
+export type OAuthAttemptPhase = 'pending' | 'completed' | 'failed';
+export interface OAuthAttempt {
+    id: string;
+    state: string;
+    verifier: string;
+    redirectUri: string;
+    scope: string;
+    phase: OAuthAttemptPhase;
+    error?: string;
+    createdAt: number;
+}
+/**
+ * Host-side attempt registry: `state` is the single-use binding between the
+ * browser redirect and the locally held verifier. An attempt is consumed
+ * exactly once — by its state — and expires with the TTL.
+ */
+export declare class OAuthAttemptStore {
+    private readonly ttlMs;
+    private readonly attempts;
+    private readonly byState;
+    constructor(ttlMs?: number);
+    create(input: {
+        verifier: string;
+        redirectUri: string;
+        scope: string;
+    }, now?: number): OAuthAttempt;
+    private expired;
+    /**
+     * Take the attempt for one browser redirect — single-use: the `state`
+     * binding is consumed by this call, so a replayed redirect finds nothing.
+     * The attempt itself stays in the registry for status polls by id until
+     * it settles or expires.
+     */
+    takeByState(state: string, now?: number): OAuthAttempt | undefined;
+    /** Mark a consumed attempt terminal (keeps it readable for status polls). */
+    settle(id: string, phase: 'completed' | 'failed', error?: string): void;
+    /** Read-only projection for the dialog's poll; unknown id → undefined. */
+    peek(id: string, now?: number): {
+        phase: OAuthAttemptPhase;
+        error?: string;
+    } | undefined;
+    cancel(id: string): boolean;
+    private drop;
+}
+/** Browser language for the hand-back page: the callback request's
+ * Accept-Language picks one locale; fixed UI copy renders in that language
+ * only (never the bilingual `zh · en` compound). */
+export type CallbackLang = 'zh' | 'en';
+/** Small HTML hand-back page for the browser redirect (§11.9 of the design).
+ * The success variant also attempts to pull the desktop app forward: DSH
+ * registers `dsh://` as an OS protocol and its shell focuses the primary
+ * window on `dsh://open`. The auto-attempt rides a hidden iframe (fails
+ * silently when the scheme is not registered, e.g. plain web UI), and an
+ * explicit button keeps a user-gesture fallback. */
+export declare function callbackPageHtml(outcome: 'success' | 'failure', message: string, lang?: CallbackLang): string;

package/lib/panel.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Panel (控制台) API client and credential gateway for one sub2api instance.
+ *
+ * Shapes verified against a live instance (2026-09-30, NexaRelay):
+ * - envelope `{code, message, data}` on success; errors carry code/message;
+ * - `GET /keys` answers a paginated envelope whose items embed the relay-key
+ *   **plaintext** and the nested group object;
+ * - `GET /groups/available` answers `data` as a **bare array** (not paginated)
+ *   with `platform` on every element — Mode A reads the platform directly.
+ *
+ * Reading discipline: take the known fields, ignore the rest (the deployment
+ * is a fork whose DTO is a superset of upstream).
+ *
+ * @module sub2api-sync/panel
+ */
+import type { CredentialsLike } from './types../types.jst { panelPasswordRef } from './types../types.jst { type OAuthEndpoints, type OAuthTokenPair } from './oauth../oauth.jsoud panel failure with the HTTP status and envelope message attached. */
+export declare class PanelError extends Error {
+    readonly status: number;
+    readonly code?: unknown;
+    constructor(status: number, message: string, code?: unknown);
+}
+/** One panel group as the plugin consumes it (tolerant subset). */
+export interface PanelGroup {
+    id: number;
+    name: string;
+    description?: string;
+    platform: string;
+    rateMultiplier?: number;
+    status?: string;
+    isExclusive?: boolean;
+    claudeCodeOnly?: boolean;
+}
+/** One panel relay key (plaintext present only when the API returns it). */
+export interface PanelKey {
+    id: number;
+    name: string;
+    groupId: number;
+    status?: string;
+    /** Plaintext relay key; absent when the panel masked it. */
+    key?: string;
+    quota?: number;
+    expiresAt?: string;
+}
+/** The signed-in account's panel identity (card header rendering). */
+export interface PanelProfile {
+    /** The account's set username, when one exists. */
+    username?: string;
+    /** The account's email (raw — the caller masks it before display). */
+    email?: string;
+    /** The account's balance in USD (profile `balance`; absent when not numeric). */
+    balance?: number;
+}
+/** One page of the panel's native key listing. */
+export interface PanelKeyPage {
+    items: PanelKey[];
+    total: number;
+    pages: number;
+}
+export type LoginOutcome = {
+    kind: 'ok';
+    accessToken: string;
+    refreshToken?: string;
+} | {
+    kind: '2fa';
+    tempToken: string;
+} | {
+    kind: 'captcha';
+    message: string;
+};
+export interface PanelClientOptions {
+    baseURL: string;
+    fetchImpl?: typeof fetch;
+}
+/** Raw panel HTTP client; every authed method takes the access token explicitly. */
+export declare class PanelClient {
+    readonly baseURL: string;
+    private readonly fetchImpl;
+    constructor(options: PanelClientOptions);
+    private call;
+    /** Password login; classifies 2FA and captcha outcomes. */
+    login(email: string, password: string): Promise<LoginOutcome>;
+    /** Second factor for the pending login. */
+    login2FA(tempToken: string, totpCode: string): Promise<{
+        accessToken: string;
+        refreshToken?: string;
+    }>;
+    /** Exchange a refresh token for a fresh pair. */
+    refresh(refreshToken: string): Promise<{
+        accessToken: string;
+        refreshToken?: string;
+    }>;
+    /** Groups the account can bind; `data` is a bare array. */
+    listAvailableGroups(token: string): Promise<PanelGroup[]>;
+    /**
+     * One page of the panel's native key listing (newest first upstream:
+     * `sort_by=created_at&sort_order=desc`, mirroring the console call shape).
+     * Callers that need every key walk `pages` themselves.
+     */
+    listKeys(token: string, options?: {
+        groupId?: number;
+        page?: number;
+        pageSize?: number;
+        sortBy?: string;
+        sortOrder?: string;
+    }): Promise<PanelKeyPage>;
+    /** Create one relay key. */
+    createKey(token: string, input: {
+        name: string;
+        groupId: number;
+        quota?: number;
+        expiresinDays?: number;
+    }): Promise<PanelKey>;
+    /** Revoke one relay key. */
+    deleteKey(token: string, id: number): Promise<void>;
+    /**
+     * Controlled plaintext reveal for one client-owned relay key (OAuth only):
+     * the regular OAuth list/get answers are masked, this endpoint is the
+     * documented exception — same ownership checks server-side, audited.
+     */
+    revealKey(token: string, id: number): Promise<PanelKey>;
+    /**
+     * The signed-in account's panel identity via the OAuth userinfo endpoint
+     * (`GET /auth/me`, scope `profile` — the plugin always requests it). The
+     * richer `/user/profile` sits OUTSIDE the OAuth token's path whitelist
+     * (`requiredOAuthScope`: only /auth/me, /groups/*, /keys/*) and answers
+     * 403 INSUFFICIENT_SCOPE for OAuth sessions. Fields: username, email,
+     * balance — all optional.
+     */
+    getProfile(token: string): Promise<PanelProfile>;
+    /** OAuth token exchange against the discovered provider (host-side only). */
+    oauthTokenExchange(endpoints: OAuthEndpoints, input: {
+        code: string;
+        redirectUri: string;
+        verifier: string;
+    }): Promise<OAuthTokenPair>;
+    /** OAuth discovery passthrough for route handlers that need endpoints. */
+    discoverOAuth(): Promise<OAuthEndpoints>;
+}
+export type AuthKind = 'none' | 'panel' | 'oauth';
+export interface AuthState {
+    signedIn: boolean;
+    kind: AuthKind;
+    email?: string;
+}
+/**
+ * Credential-backed gateway over {@link PanelClient}: stores login
+ * tokens, classifies the auth kind, and wraps authed calls with a
+ * single-flight 401 → refresh → retry.
+ */
+export declare class PanelGateway {
+    private readonly baseURLSource;
+    private readonly credentials;
+    private readonly fetchImpl?;
+    private pending2FA?;
+    private refreshInFlight?;
+    private oauthRefreshInFlight?;
+    constructor(options: {
+        baseURL: string | (() => string);
+        credentials: CredentialsLike;
+        fetchImpl?: typeof fetch;
+        onAuthLost?: () => void;
+    });
+    /**
+     * Fired when the panel session is definitively gone — no refresh token, or
+     * the refresh call itself was refused. Never on network failures. The host
+     * hooks this to purge the site's sync state (logout/expiry policy).
+     */
+    private readonly onAuthLost?;
+    /** The instance address, re-read per call so a baseURL edit takes effect. */
+    private get baseURL();
+    private client;
+    private tokenRef;
+    private refreshRef;
+    private oauthAccessRef;
+    private oauthRefresh;
+    /** Current auth state; email rides the caller's config, not credentials. */
+    authState(email?: string): Promise<AuthState>;
+    /** Password login; stores the pair and the password for silent re-login. */
+    login(email: string, password: string): Promise<LoginOutcome>;
+    /** Complete the pending 2FA login. */
+    login2FA(code: string): Promise<void>;
+    /** Sign out: revoke OAuth tokens server-side when present, then drop both channels' secrets. */
+    logout(): Promise<void>;
+    /**
+     * Run one authed panel call. Tokens resolve per channel — OAuth access
+     * token first, then the panel JWT — and a 401 triggers a single-flight
+     * refresh (channel-appropriate) and exactly one retry before failing loud.
+     */
+    use<T>(fn: (panel: PanelClient, token: string) => Promise<T>): Promise<T>;
+    /** Store the pair from a completed browser authorization (C2). */
+    storeOAuthTokens(pair: OAuthTokenPair): Promise<void>;
+    /** Revoke OAuth tokens at the provider (best effort) and drop the stored secrets. */
+    oauthSignOut(): Promise<void>;
+    /** Single-flight OAuth refresh (rotating); concurrent 401s share one wire call. */
+    private refreshOAuthSingleFlight;
+    private refreshOAuth;
+    /** Single-flight refresh; concurrent 401s share one wire call. */
+    private refreshSingleFlight;
+    private doRefresh;
+    private storeTokens;
+}
+/** Convenience export: the password credential ref for one instance. */
+export { panelPasswordRef };

package/lib/protocols.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Platform → wire-protocol mapping and provider-profile construction.
+ *
+ * The mapping follows the sub2api gateway source (verified:
+ * `routes/gateway.go`, `isOpenAIResponsesCompatibleGatewayPlatform`): the
+ * five OpenAI-family platforms are forwarded through the gateway's OpenAI
+ * Responses path natively, anthropic through Messages, and the remaining
+ * platforms only exist behind gateway bridging — chat/completions there.
+ * Speaking the gateway's native path avoids its chat/completions ↔ native
+ * conversion, which drops or misaligns parallel tool calls.
+ *
+ * @module sub2api-sync/protocols
+ */
+import type { ApiProtocol } from './type./types.js One model entry inside an llm-pi-ai provider profile. */
+export interface ProviderProfileModel {
+    id: string;
+    name?: string;
+    contextWindow?: number;
+    maxTokens?: number;
+    input?: Array<'text' | 'image'>;
+    reasoningEfforts?: false | Record<string, string | null>;
+    compat?: Record<string, unknown>;
+}
+export interface PiAiRetryPolicy {
+    mode: 'normal' | 'always';
+    maxRetries?: number;
+    retryableCodes?: string[];
+    backoff?: {
+        initialDelayMs?: number;
+        maxDelayMs?: number;
+        jitterRatio?: number;
+    };
+}
+/** One provider route inside the `llm-pi-ai` settings section. */
+export interface PiAiProviderProfile {
+    apiKeyEnv?: string;
+    displayName?: string;
+    api?: ApiProtocol;
+    baseURL?: string;
+    models?: ProviderProfileModel[];
+    defaultContextWindow?: number;
+    defaultMaxTokens?: number;
+    defaultInput?: Array<'text' | 'image'>;
+    retryPolicy?: PiAiRetryPolicy;
+    /** Provider-level default reasoning effort (pi-ai `reasoning`). */
+    reasoning?: ThinkingLevel;
+}
+/**
+ * Lenient retry policy for proxied upstreams: sub2api sits in front of
+ * provider subscriptions that enforce their own HTTP 429 windows, and
+ * llm-pi-ai's default normal policy (2 retries / 10s) cannot outlast them.
+ */
+export declare const SUB2API_RETRY_POLICY: Required<PiAiRetryPolicy>;
+/**
+ * Guess one sub2api platform from discovered model ids. The gateway never
+ * answers a relay key with the group platform, but model families map
+ * cleanly: one consistent family names its platform, a mix of families is
+ * the signature of a composite group. Returns `undefined` when nothing
+ * matches — the caller keeps the manual choice authoritative.
+ */
+export declare function guessPlatformFromModels(modelIds: readonly string[]): string | undefined;
+/**
+ * Map one sub2api platform to the wire protocol the gateway serves on its
+ * native path. Returns `undefined` for platforms outside the known set —
+ * callers fail the group loudly instead of guessing.
+ */
+export declare function protocolForPlatform(platform: string): ApiProtocol | undefined;
+/**
+ * Render the provider displayName from the relay key's name. The template is
+ * a Config field (C5: must contain `{keyName}`); callers that receive an
+ * invalid template still get a sane name instead of a broken one.
+ */
+export declare function renderProviderName(template: string | undefined, keyName: string, siteName?: string): string;
+/**
+ * Derive the profile baseURL for one protocol. OpenAI-family SDKs append
+ * their endpoint to a `/v1`-rooted URL; the Anthropic SDK treats the URL as
+ * a bare host and appends `/v1/messages` itself, so a `/v1` root there would
+ * produce `/v1/v1/messages` (404).
+ */
+export declare function baseURLForProtocol(instance: string, protocol: ApiProtocol): string;
+/** pi-ai thinking levels a provider-level default effort may name. */
+export declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+/** Per-model template inherited by every synced model entry (Config field). */
+export interface ModelTemplate {
+    compat?: Record<string, unknown>;
+    reasoningEfforts?: false | Record<string, string | null>;
+    /**
+     * Provider-level default reasoning effort (pi-ai profile `reasoning`): the
+     * effort preselected for every synced model and sent when the user has not
+     * picked one. models.dev publishes no default-effort data, so this is the
+     * user's explicit choice rather than catalog-derived.
+     */
+    reasoning?: ThinkingLevel;
+}
+/** One discovered model with its enrichment facts (from the models.dev index). */
+export interface ProfileModelInput {
+    id: string;
+    /** Display name for selectors (models.dev `name`); absent keeps the id. */
+    name?: string;
+    contextWindow?: number;
+    maxTokens?: number;
+    imageInput?: boolean;
+    /** Per-model auto-filled effort map (models.dev `reasoning_options`). */
+    reasoningEfforts?: Record<string, string | null>;
+}
+export interface ProfileInput {
+    groupId: number;
+    /** Rendered provider display name (`renderProviderName` over the key name). */
+    displayName: string;
+    protocol: ApiProtocol;
+    /** sub2api instance address, with or without a trailing `/v1`. */
+    instance: string;
+    models: readonly ProfileModelInput[];
+    apiKeyEnv: string;
+    template?: ModelTemplate;
+}
+/** Build one hand-declared llm-pi-ai provider profile for a group. */
+export declare function buildProviderProfile(input: ProfileInput): PiAiProviderProfile;