@mangoc/dsh-sub2api-sync 0.0.0-stage → 0.2.0

package/lib/routes.d.ts

@@ -0,0 +1,256 @@
+/**
+ * HTTP routes between the settings card (browser half) and this plugin's
+ * host half, registered on the harness web server.
+ *
+ * rev.4 split: configuration reads/writes ride the platform's
+ * `configForms`/settings seam — the old whole-section `/config` route is
+ * gone. These routes carry only **actions, secrets, and state projection**:
+ * login (password/2FA), panel group/key listing, paste/clear of a
+ * relay key, sync, model discovery, and the status snapshot.
+ *
+ * Requests are restricted to trusted local origins — the same
+ * `trustedRequest` posture the community plugins use — with one explicit
+ * escape hatch (`allowRemoteActions`, §11): when the user opts in, peers
+ * from private-network ranges are accepted too. Secrets never ride these
+ * responses: a relay key is written once via `POST /key`, a panel token
+ * never leaves the credentials store, and `/group-keys` answers metadata
+ * only. The webserver rejects duplicate (kind, path) registrations, so each
+ * path dispatches by method inside one handler.
+ *
+ * @module sub2api-sync/routes
+ */
+import type { IncomingMessage } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+import type { SyncReport } from './engin./engine.jsrt type { IconPayload } from './icon../icon.jsrt type { AuthKind } from './panel./panel.jsrt type { CallbackLang } from './oauth./oauth.jsThe hand-back page's locale from the callback request's Accept-Language:
+ * the first tag decides (`en*` → en, anything else → zh — matching the
+ * browser's preference order without full q-value negotiation). */
+export declare function callbackLangOf(acceptLanguage: string | undefined): CallbackLang;
+export declare const ROUTES: {
+    readonly sync: "/plugins/dsh-sub2api-sync/sync";
+    readonly status: "/plugins/dsh-sub2api-sync/status";
+    readonly login: "/plugins/dsh-sub2api-sync/login";
+    readonly login2fa: "/plugins/dsh-sub2api-sync/login/2fa";
+    readonly logout: "/plugins/dsh-sub2api-sync/logout";
+    readonly groups: "/plugins/dsh-sub2api-sync/groups";
+    readonly keys: "/plugins/dsh-sub2api-sync/keys";
+    readonly icon: "/plugins/dsh-sub2api-sync/icon";
+    readonly site: "/plugins/dsh-sub2api-sync/site";
+    readonly account: "/plugins/dsh-sub2api-sync/account";
+    readonly resetSync: "/plugins/dsh-sub2api-sync/reset-sync";
+    readonly removeKey: "/plugins/dsh-sub2api-sync/remove-key";
+    readonly oauthStart: "/plugins/dsh-sub2api-sync/oauth/start";
+    readonly oauthProbe: "/plugins/dsh-sub2api-sync/oauth/probe";
+    readonly oauthCallback: "/plugins/dsh-sub2api-sync/oauth/callback";
+    readonly oauthStatus: "/plugins/dsh-sub2api-sync/oauth/status";
+    readonly oauthCancel: "/plugins/dsh-sub2api-sync/oauth/cancel";
+};
+/** One relay key as the keys card renders it (metadata only, no plaintext). */
+export interface PanelKeyMeta {
+    id: number;
+    name: string;
+    groupId: number;
+    status?: string;
+}
+/** `GET /keys` — one page of the aggregated key list (newest first). */
+export interface KeysResponse {
+    ok: true;
+    keys: PanelKeyMeta[];
+    total: number;
+    pages: number;
+}
+/** One dep-provided key list page (host seam between client and panel). */
+export interface KeysListPage {
+    keys: PanelKeyMeta[];
+    total: number;
+    pages: number;
+}
+/** `POST /keys` — create one relay key (name defaults to the group name). */
+export interface CreateKeyResponse {
+    ok: true;
+    key: PanelKeyMeta;
+}
+/** Auth snapshot the card renders its account block from. */
+export interface AuthView {
+    signedIn: boolean;
+    kind: AuthKind;
+    email?: string;
+}
+export interface StatusRoute {
+    route: string;
+    displayName?: string;
+    api?: string;
+    models: number;
+    modelsPreview: string[];
+    /** The panel key id behind this route (from the engine's route→id map);
+     * absent for routes synced before the map existed. */
+    keyId?: number;
+}
+export interface StatusResponse {
+    ok: true;
+    auth: AuthView;
+    instance: string;
+    syncRunning: boolean;
+    routes: StatusRoute[];
+    lastReport?: SyncReport;
+    /** Wall-clock ms of the last accepted sync (client renders it relatively). */
+    lastReportAt?: number;
+}
+export interface GroupsView {
+    id: number;
+    name: string;
+    platform: string;
+    status?: string;
+    rateMultiplier?: number;
+    isExclusive?: boolean;
+    claudeCodeOnly?: boolean;
+}
+export interface GroupsResponse {
+    ok: true;
+    groups: GroupsView[];
+}
+/** `POST /reset-sync` — purge the plugin's sync state (instance switch). */
+export interface ResetSyncResponse {
+    ok: true;
+}
+/** `POST /remove-key` — remove one key's synced provider (report entry button). */
+export interface RemoveKeyResponse {
+    ok: true;
+}
+/** `GET /site` — the instance's configured site name (undefined when unknown). */
+export interface SiteResponse {
+    ok: true;
+    name?: string;
+}
+/** `GET /account` — the signed-in panel account's identity (header rendering). */
+export interface AccountResponse {
+    ok: true;
+    /** The account's set username, when one exists. */
+    username?: string;
+    /** The account's email (raw — the card masks it before display). */
+    email?: string;
+    /** The account's balance in USD (header pill; absent when not numeric). */
+    balance?: number;
+    /** The upstream failure reason when the profile could not be fetched
+     * (the header is cosmetic and falls back, but the cause must be visible). */
+    error?: string;
+}
+export interface LoginResponse {
+    ok: true;
+    kind: 'ok' | '2fa';
+    requires2FA?: boolean;
+}
+/** `GET /oauth/probe?address=…` — whether the instance publishes OAuth
+ * discovery metadata (the sign-in dialog auto-selects its channel from it). */
+export interface OAuthProbeResponse {
+    ok: true;
+    supported: boolean;
+}
+export interface SyncResponse {
+    ok: true;
+    report: SyncReport;
+}
+/** `POST /oauth/start` — one authorization attempt, opened in a new tab. */
+export interface OAuthStartResponse {
+    ok: true;
+    attemptId: string;
+    authorizeUrl: string;
+}
+/** `GET /oauth/status?attempt=<id>` — dialog poll for the web channel. */
+export interface OAuthAttemptStatusResponse {
+    ok: true;
+    attempt: {
+        phase: 'pending' | 'completed' | 'failed';
+        error?: string;
+    } | undefined;
+    auth: AuthView;
+}
+/** `POST /oauth/cancel` — drop a pending attempt. */
+export interface OAuthCancelResponse {
+    ok: true;
+}
+/**
+ * Accept only trusted peers: a loopback peer that is not a cross-site
+ * request and whose Origin (when present) matches the Host. With
+ * `allowRemote` (the user's cross-device escape hatch, §11) private-network
+ * peers are accepted under the same origin rules — public peers never are.
+ */
+export declare function trustedRequest(req: IncomingMessage, allowRemote?: boolean): boolean;
+export interface RouteDeps {
+    /** Instance address as configured (echoed to the card for the header). */
+    instance(): string;
+    /** Current auth snapshot (credential-derived; email rides the config). */
+    authState(): Promise<AuthView>;
+    /** Password login; stores email/password and the token pair on success. */
+    login(email: string, password: string | undefined): Promise<LoginResponse>;
+    /** Complete the pending 2FA login. */
+    login2FA(code: string): Promise<void>;
+    /** Drop panel tokens. */
+    logout(): Promise<void>;
+    /** Live panel groups as the panel reports them (the card's checked state
+     * rides the config's `selectedKeys`, not this response). */
+    listGroups(): Promise<GroupsView[]>;
+    /** Run one sync; the implementation serializes and records the report. */
+    sync(keyIds?: number[]): Promise<SyncReport>;
+    lastReport(): SyncReport | undefined;
+    lastReportAt(): number | undefined;
+    /** One page of the panel's keys (newest first; page is 1-based). */
+    listKeys(page: number, pageSize: number): Promise<KeysListPage>;
+    /** Create one relay key (name defaults to the group name upstream of this seam). */
+    createKey(input: {
+        groupId: number;
+        name: string;
+    }): Promise<PanelKeyMeta>;
+    /** The instance's icon bytes (declared `<link rel=icon>` → /favicon.ico), or undefined. */
+    icon(): Promise<IconPayload | undefined>;
+    /** The instance's configured site name (parsed from its HTML title), or undefined. */
+    siteName(): Promise<string | undefined>;
+    /** The signed-in panel account's identity (username/email/balance), or undefined when unavailable. */
+    account(): Promise<{
+        username?: string;
+        email?: string;
+        balance?: number;
+    } | undefined>;
+    /**
+     * Purge this plugin's sync state: remove every owned provider route and
+     * its relay-key credential, plus (when `previousBaseURL` is given) the
+     * old instance's unreachable panel secrets. The card calls it on instance
+     * switch; logout and auth-loss purge inside the host.
+     */
+    resetSync(previousBaseURL?: string): Promise<void>;
+    /**
+     * Remove one key's synced provider: the route derived from the current
+     * instance + `keyId` leaves the llm-pi-ai section and its relay-key
+     * credential is dropped. Local state only — no panel calls, and the
+     * selection drop happens card-side so the next sync cannot resurrect it.
+     */
+    removeSyncedKey(keyId: number): Promise<void>;
+    isSyncRunning(): boolean;
+    /** Owned routes currently registered in the llm-pi-ai section. */
+    ownedRoutes(): StatusRoute[];
+    /** Whether the cross-device escape hatch is on (Config, default false). */
+    allowRemote(): boolean;
+    /** Begin one OAuth authorization attempt bound to this harness origin. */
+    oauthStart(callbackOrigin: string): Promise<{
+        attemptId: string;
+        authorizeUrl: string;
+    }>;
+    /** Whether the given instance address publishes OAuth discovery metadata
+     * (host-side fetch — the browser cannot probe cross-origin). */
+    oauthProbe(address: string): Promise<boolean>;
+    /** Consume the provider's browser redirect: match state, exchange the code.
+     * `lang` is the callback request's Accept-Language locale for the page. */
+    oauthCallback(query: URLSearchParams, lang: CallbackLang): Promise<{
+        html: string;
+    }>;
+    /** Project one attempt's phase plus the current auth snapshot. */
+    oauthStatus(attemptId: string | undefined): Promise<OAuthAttemptStatusResponse>;
+    /** Drop a pending attempt (user cancelled the dialog). */
+    oauthCancel(attemptId: string): Promise<void>;
+}
+/** Register all card routes on the web server (no-op without one). */
+export declare function registerRoutes(ctx: Context, deps: RouteDeps): void;
+/**
+ * Assemble the `ownedRoutes` view for the status endpoint from the live
+ * `llm-pi-ai` section value (same-process caller, no redaction).
+ */
+export declare function describeOwnedRoutes(section: unknown): StatusRoute[];

package/lib/types.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Shared vocabulary of the sub2api sync plugin: platforms, wire protocols,
+ * route/credential naming, service interfaces, and the ownership boundary
+ * this plugin enforces inside `llm-pi-ai.providers`.
+ *
+ * rev.5: routes are opaque — `sub2api-<10-hex>` derived from SHA-256 over
+ * (instance baseURL, panel key id). The panel's sequential key id never
+ * appears in route or credential names, so a shared config screenshot cannot
+ * reveal how many keys the site has handed out. Legacy `sub2api-<digits>`
+ * routes stay recognized (owned + cleaned up) so existing deployments
+ * migrate on the next sync; the plaintext credential gains a legacy-ref
+ * fallback read for the same reason.
+ *
+ * @module sub2api-sync/types
+ */
+/** Platforms sub2api assigns to groups (verified: `backend/internal/domain/constants.go`; live instance 2026-09-30). */
+export declare const PLATFORMS: readonly ["anthropic", "openai", "gemini", "antigravity", "grok", "kimi", "zhipu", "deepseek", "composite"];
+export type Sub2apiPlatform = (typeof PLATFORMS)[number];
+/** Human labels for the group types, matching the platform picker's wording. */
+export declare const PLATFORM_LABELS: Record<Sub2apiPlatform, string>;
+/** The display label for a group type; unknown values pass through raw so a
+ * future sub2api platform still shows something truthful. */
+export declare function platformLabel(platform: string): string;
+/**
+ * The default provider-name template (rev.4 decision). Lives here — not in
+ * `config.ts` — so the browser half can value-import it without pulling the
+ * schemastery-backed schema (the client bundle must only request baseline
+ * externals; see test/client-bundle.test.ts).
+ */
+export declare const DEFAULT_PROVIDER_NAME_TEMPLATE = "{siteName}({keyName})";
+/**
+ * Wire protocols llm-pi-ai can speak; must stay inside its
+ * `supportedProtocols()` set or the write is refused with `settings-rejected`.
+ */
+export declare const API_PROTOCOLS: readonly ["openai-completions", "openai-responses", "anthropic-messages"];
+export type ApiProtocol = (typeof API_PROTOCOLS)[number];
+/** Route prefix this plugin owns inside `llm-pi-ai.providers`. */
+export declare const ROUTE_PREFIX = "sub2api-";
+/**
+ * Ownership boundary: only `sub2api-<10-hex>` (rev.5 opaque slug) and the
+ * legacy `sub2api-<digits>` routes belong to this plugin. Anything else —
+ * including the community plugin's `sub2api-openai` style routes — stays out
+ * of this plugin's write and cleanup set.
+ */
+export declare function isOwnedRoute(route: string): boolean;
+/**
+ * FIPS 180-4 SHA-256 over UTF-8 input, pure JS so both the host half and the
+ * browser bundle can use it without pulling `node:crypto`. Only used for
+ * non-secret route slugs; tests pin the standard vectors.
+ */
+export declare function sha256Hex(input: string): string;
+/** Route slug for one relay key: SHA-256 over (instance, key id), truncated. */
+export declare function keyRouteSlug(baseURL: string, keyId: number): string;
+/**
+ * The llm-pi-ai route name for one selected relay key. The slug is derived
+ * from the instance address and the panel key id — stable across syncs and
+ * key renames, collision-free across instances, and it carries no hint about
+ * the panel's sequential key numbering.
+ */
+export declare function routeForKey(baseURL: string, keyId: number): string;
+/** The route's suffix (slug or legacy digits), when the shape is owned. */
+export declare function suffixOfRoute(route: string): string | undefined;
+/** The panel key id encoded in a LEGACY digit route, when the shape matches. */
+export declare function legacyKeyIdOfRoute(route: string): number | undefined;
+/**
+ * FNV-1a 32-bit string hash. Used to derive per-instance credential
+ * reference suffixes (tokens/password are secrets of one panel instance;
+ * hashing the baseURL keeps refs stable yet instance-scoped).
+ */
+export declare function hashString(input: string): number;
+/** Normalized instance key the credential suffixes derive from. */
+export declare function instanceKey(baseURL: string): string;
+/** Panel access-token credential reference for one instance. */
+export declare function panelTokenRef(baseURL: string): string;
+/** Panel refresh-token credential reference for one instance. */
+export declare function panelRefreshRef(baseURL: string): string;
+/** Panel password credential reference for one instance (Mode A, C3). */
+export declare function panelPasswordRef(baseURL: string): string;
+/** OAuth access-token credential reference for one instance (C2). */
+export declare function oauthTokenRef(baseURL: string): string;
+/** OAuth refresh-token credential reference for one instance (C2). */
+export declare function oauthRefreshRef(baseURL: string): string;
+/**
+ * Credential reference carrying one route's relay key. Derived from the
+ * route suffix, so the lifecycle follows the route exactly: removal unsets
+ * it without needing the panel key id. New routes hash-scope the ref per
+ * instance; legacy digit routes keep their historical ref shape.
+ */
+export declare function routeKeyRef(route: string): string;
+/**
+ * Legacy per-key-id credential reference (pre-rev.5). Kept as a READ
+ * fallback during migration: deployments that stored plaintext under
+ * `DSH_SUB2API_KEY_<id>` keep syncing without re-entering the key. Never
+ * written anymore; only unset when the matching legacy route is removed.
+ */
+export declare function legacyKeyRef(keyId: number): string;
+/**
+ * Parse a user/config-supplied group id: decimal digits within the safe
+ * integer range. Group ids are int64 at the sub2api side; anything beyond
+ * `Number.MAX_SAFE_INTEGER` fails loudly instead of being silently mangled.
+ */
+export declare function parseGroupId(input: unknown): number | undefined;
+/** Minimal structural view of the settings service the engine needs. */
+export interface SettingsLike {
+    describe(options?: {
+        redactSecrets?: boolean;
+    }): Array<{
+        ns: string;
+        revision: number;
+        value?: unknown;
+    }>;
+    mutate(ns: string, ops: SettingsPathOp[], expectedRevision?: number): Promise<void>;
+}
+/** One settings path operation (shared by llm-pi-ai writes and own-ns writes). */
+export type SettingsPathOp = {
+    op: 'set';
+    path: string[];
+    value: unknown;
+} | {
+    op: 'unset';
+    path: string[];
+};
+/** Minimal structural view of the credentials service the engine needs. */
+export interface CredentialsLike {
+    resolve(ref: string): Promise<{
+        value: string;
+    } | undefined>;
+    set(ref: string, value: string): Promise<void>;
+    unset(ref: string): Promise<void>;
+}
+/**
+ * The settings service's concurrent-writer error shape (`code` or `name`).
+ * One predicate for every conflict surface: the shared mutate helper below,
+ * the engine's plan loop, and the route layer's 409 projection.
+ */
+export declare function isSettingsConflict(error: unknown): boolean;
+/**
+ * Conflict-retried write into one settings namespace: build the ops, read
+ * the namespace's live revision, mutate, and on a concurrent-writer conflict
+ * rebuild + retry (bounded — 3 attempts total, matching the engine's policy).
+ *
+ * `buildOps` runs per attempt so a retry can recompute the plan against the
+ * just-re-read state; it may close over outer holders to surface the final
+ * ops/actions (the engine does exactly that for its sync report). An empty
+ * ops list skips the wire round trip entirely — but the namespace must still
+ * exist (the same loud failure the engine's revision read used to produce).
+ */
+export declare function mutateWithRetry(settings: SettingsLike, ns: string, buildOps: () => SettingsPathOp[] | Promise<SettingsPathOp[]>, options?: {
+    missingError?: string;
+    attempts?: number;
+}): Promise<void>;

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Sub2API Sync",
+    "description": "Sync one sub2api instance's groups, keys, and models into dsh-llm-pi-ai provider routes: panel-driven login (PAT / password / OAuth) first, one group one provider."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Sub2API 同步",
+    "description": "把一个 sub2api 实例的分组、key 与模型同步为 dsh-llm-pi-ai 供应商路由：先连接面板（PAT / 密码 / OAuth），一个分组一个供应商。"
+  }
+}

package/package.json

@@ -1,6 +1,127 @@
 {
   "name": "@mangoc/dsh-sub2api-sync",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Sync one sub2api instance's groups, keys, and models into dsh-llm-pi-ai provider routes: panel-driven login (password / OAuth) first, one group one provider.",
+  "version": "0.2.0",
+  "license": "MIT",
+  "author": "Shuai-S",
+  "homepage": "https://github.com/Shuai-S/dsh-sub2api-sync#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Shuai-S/dsh-sub2api-sync.git",
+    "directory": "packages/llm/sub2api-sync"
+  },
+  "bugs": "https://github.com/Shuai-S/dsh-sub2api-sync/issues",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "sub2api",
+    "provider-sync",
+    "llm"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": "./lib/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "files": [
+    "lib",
+    "data",
+    "locale",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ],
+      "platform": "web"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.4"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-client-locale": ">=0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": ">=0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.2.0-rc.2",
+    "@deepseek-ai/dsh-credentials": "*",
+    "@deepseek-ai/dsh-host-webserver": "*",
+    "@deepseek-ai/dsh-settings": "*",
+    "react": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-locale": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-primitives": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-settings": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-credentials": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-host-webserver": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-settings": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings-models": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-credentials": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-settings": "0.2.0-rc.2",
+    "@types/node": "^22.20.0",
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "tsdown": "^0.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsdown && node scripts/wrap-client.mjs",
+    "pack:all": "node scripts/pack-all.mjs",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.client.json",
+    "test": "vitest run",
+    "models:refresh": "node scripts/fetch-models-dev.mjs",
+    "check": "pnpm typecheck && pnpm test && pnpm build"
+  }
 }