@mangoc/dsh-sub2api-sync 0.2.8 → 0.3.0

package/lib/index.js

@@ -190,6 +190,7 @@ function panelRefreshRef(baseURL) {
 function panelPasswordRef(baseURL) {
 	return `DSH_SUB2API_PASSWORD_${hashString(instanceKey(baseURL))}`;
 }
+const NATIVE_PANEL_PASSWORD_REF = "DSH_SUB2API_PANEL_PASSWORD";
 function oauthTokenRef(baseURL) {
 	return `DSH_SUB2API_OAUTH_TOKEN_${hashString(instanceKey(baseURL))}`;
 }
@@ -376,14 +377,30 @@ const apiProtocolSchema = z.union([
 	z.const("openai-responses"),
 	z.const("anthropic-messages")
 ]);
+/**
+* dsh-Go native settings: a fixed-ref credential slot for the panel
+* password (the official dsh-media shape). The `credential-ref` role marks
+* the binding — the App reads it, shows 已设置/未设置 and writes the secret
+* through its credentials transaction; the `secret` sentinel refuses any
+* value on the ordinary config write path, so a password can never land in
+* the profile document. Empty default keeps the form write a no-op.
+*/
+const secretSentinel = z.transform(z.any(), (value) => {
+	if (value !== "") throw new Error("面板密码只能通过凭据服务写入（本字段仅作占位）。");
+	return "";
+}, true).default("").role("secret");
+const panelCredentialSlot = z.object({
+	credentialRef: z.const(NATIVE_PANEL_PASSWORD_REF).default(NATIVE_PANEL_PASSWORD_REF).role("credential-ref"),
+	password: secretSentinel.description("面板密码（写入凭据库，手机原生设置可填） / Panel password (stored in the credential store)")
+}).description("面板密码凭据（免输登录用，与网页卡共用） / Panel password credential").collapse();
 const Config = z.object({
-	baseURL: z.string().volatile(),
-	email: z.string().volatile(),
-	providerNameTemplate: z.string().default(DEFAULT_PROVIDER_NAME_TEMPLATE).volatile(),
-	selectedKeys: z.array(z.number().step(1)).default([]).volatile(),
-	modelListOverrides: z.dict(z.array(z.string())).default({}).volatile(),
-	protocolOverrides: z.dict(apiProtocolSchema).default({}).volatile(),
-	routeKeyIds: z.dict(z.number().step(1)).default({}).volatile(),
+	baseURL: z.string().description("sub2api 实例地址（含或不含 /v1） / Instance URL (with or without /v1)").volatile(),
+	email: z.string().description("面板账号邮箱（密码登录用） / Panel account email (password login)").volatile(),
+	providerNameTemplate: z.string().default(DEFAULT_PROVIDER_NAME_TEMPLATE).description("供应商显示名模板，须含 {keyName} 或 {siteName} / Provider display-name template (must keep {keyName} or {siteName})").volatile(),
+	selectedKeys: z.array(z.number().step(1)).default([]).description("待同步的中转 key 列表（网页卡勾选写入） / Relay keys selected for sync (card-managed)").collapse().volatile(),
+	modelListOverrides: z.dict(z.array(z.string())).default({}).description("分组手动模型列表（/v1/models 不可用时） / Manual model lists when /v1/models is unavailable").collapse().volatile(),
+	protocolOverrides: z.dict(apiProtocolSchema).default({}).description("分组线协议覆盖 / Per-group wire-protocol override").collapse().volatile(),
+	routeKeyIds: z.dict(z.number().step(1)).default({}).description("（引擎维护，请勿手改）路由 → 面板 key id 映射 / Engine-maintained route→keyId map — do not edit").hidden(true).volatile(),
 	compatTemplate: z.object({
 		compat: z.dict(z.any()),
 		reasoningEfforts: z.union([z.const(false), z.dict(z.union([z.string(), z.const(null)]))]),
@@ -396,12 +413,12 @@ const Config = z.object({
 			z.const("xhigh"),
 			z.const("max")
 		])
-	}).volatile(),
-	enrichModelMeta: z.boolean().default(true).volatile(),
-	keyQuota: z.number().volatile(),
-	keyExpiresInDays: z.number().step(1).volatile(),
-	deleteOrphanKeys: z.boolean().default(false).volatile(),
-	syncIntervalMs: z.number().step(1).volatile(),
+	}).description("同步模型继承的兼容模板 / Per-model template inherited by synced models").collapse().volatile(),
+	enrichModelMeta: z.boolean().default(true).description("models.dev 元数据增强（显示名/上下文窗口） / models.dev metadata enrichment").volatile(),
+	keyQuota: z.number().description("新建 key 的额度（USD，可选） / Optional quota (USD) for created keys").volatile(),
+	keyExpiresInDays: z.number().step(1).description("新建 key 的有效天数（可选） / Optional expiry in days for created keys").volatile(),
+	deleteOrphanKeys: z.boolean().default(false).description("移除路由时同时吊销面板 key / Also revoke the panel key when removing a route").volatile(),
+	syncIntervalMs: z.number().step(1).description("定时同步间隔 ms（删除字段即关闭，下限 60000） / Scheduled resync interval ms (unset = off; floor 60000)").volatile(),
 	retryPolicy: z.object({
 		mode: z.union([z.const("normal"), z.const("always")]),
 		maxRetries: z.number().step(1),
@@ -411,10 +428,11 @@ const Config = z.object({
 			maxDelayMs: z.number(),
 			jitterRatio: z.number()
 		})
-	}).volatile(),
-	defaultContextWindow: z.number().step(1).volatile(),
-	defaultMaxTokens: z.number().step(1).volatile(),
-	allowRemoteActions: z.boolean().default(false).volatile()
+	}).description("同步路由的重试策略覆盖（缺省继承内置宽容策略） / Retry-policy overrides (defaults to the built-in lenient policy)").collapse().volatile(),
+	defaultContextWindow: z.number().step(1).description("元数据无法匹配时的默认上下文窗口 / Default context window when enrichment cannot match").volatile(),
+	defaultMaxTokens: z.number().step(1).description("元数据无法匹配时的默认最大输出 / Default max output tokens when enrichment cannot match").volatile(),
+	allowRemoteActions: z.boolean().default(false).description("允许局域网内其他设备操作面板（默认关；开启后同一局域网的设备可修改模型路由与登录信息，仅限可信内网） / Let other devices on your local network operate the panel (default off — they could change model routes and sign-in details; trusted networks only)").volatile(),
+	panelCredential: panelCredentialSlot.volatile()
 });
 /** Unwrap one live cell into its current snapshot; plain values pass through. */
 function unwrap$1(field) {
@@ -820,7 +838,7 @@ var Sub2apiSyncError = class extends Error {
 		this.name = "Sub2apiSyncError";
 	}
 };
-function messageOf(error) {
+function messageOf$1(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 /** Order-insensitive JSON comparison — profiles are plain JSON values. */
@@ -966,7 +984,7 @@ var Sub2apiSyncEngine = class {
 					route,
 					keyId: key.id,
 					action: "failed",
-					error: messageOf(error)
+					error: messageOf$1(error)
 				});
 			}
 		}
@@ -994,13 +1012,13 @@ var Sub2apiSyncEngine = class {
 			try {
 				await this.credentials.unset(routeKeyRef(route));
 			} catch (error) {
-				warnings.push(`key ${route} 的凭据清理失败：${messageOf(error)}`);
+				warnings.push(`key ${route} 的凭据清理失败：${messageOf$1(error)}`);
 			}
 			const keyId = keyIdByRoute.get(route) ?? legacyKeyIdOfRoute(route);
 			if (config.deleteOrphanKeys === true && keyId !== undefined) try {
 				await this.gateway.use((panel, token) => panel.deleteKey(token, keyId));
 			} catch (error) {
-				warnings.push(`key ${route} 的远端撤销失败：${messageOf(error)}`);
+				warnings.push(`key ${route} 的远端撤销失败：${messageOf$1(error)}`);
 			}
 		}
 		try {
@@ -1055,7 +1073,7 @@ var Sub2apiSyncEngine = class {
 			plaintext = !usable(revealed.key) ? undefined : revealed.key;
 			if (plaintext === undefined) revealFailure = "reveal 未返回可用明文";
 		} catch (error) {
-			revealFailure = messageOf(error);
+			revealFailure = messageOf$1(error);
 		}
 		if (!usable(plaintext)) {
 			const revealNote = revealFailure !== undefined ? `；reveal 接口也失败：${revealFailure}` : "";
@@ -1065,19 +1083,23 @@ var Sub2apiSyncEngine = class {
 		try {
 			models = await this.discoverModels(config, group.id, instance, plaintext);
 		} catch (error) {
-			if (source !== "stored" && source !== "legacy" || !/HTTP 401(?![0-9])/.test(messageOf(error))) throw error;
+			if (source !== "stored" && source !== "legacy" || !/HTTP 401(?![0-9])/.test(messageOf$1(error))) throw error;
 			await this.credentials.unset(ref).catch(() => undefined);
 			if (ref !== legacyKeyRef(key.id)) await this.credentials.unset(legacyKeyRef(key.id)).catch(() => undefined);
 			let revealed;
 			try {
 				revealed = (await this.gateway.use((panel, token) => panel.revealKey(token, key.id)))?.key;
 			} catch (revealError) {
-				throw new Sub2apiSyncError(`${messageOf(error)}；本地存底已作废，但 reveal 也失败：${messageOf(revealError)}——请在面板删除这把 key 后用插件「创建 key」重建`);
+				throw new Sub2apiSyncError(`${messageOf$1(error)}；本地存底已作废，但 reveal 也失败：${messageOf$1(revealError)}——请在面板删除这把 key 后用插件「创建 key」重建`);
 			}
-			if (revealed === undefined || revealed.length === 0 || revealed.includes("****")) throw new Sub2apiSyncError(`${messageOf(error)}；本地存底已作废，但 reveal 未返回明文——请在面板删除这把 key 后用插件「创建 key」重建`);
+			if (revealed === undefined || revealed.length === 0 || revealed.includes("****")) throw new Sub2apiSyncError(`${messageOf$1(error)}；本地存底已作废，但 reveal 未返回明文——请在面板删除这把 key 后用插件「创建 key」重建`);
 			plaintext = revealed;
 			models = await this.discoverModels(config, group.id, instance, plaintext);
 		}
+		if (models.length === 0) {
+			const groupLabel = group.name.length > 0 ? `${group.name}（#${group.id}）` : `#${group.id}`;
+			throw new Sub2apiSyncError(`key #${key.id}（${key.name}）经网关 /v1/models 发现到 0 个模型（分组 ${groupLabel}）——中转站没有向这把 key 暴露任何模型；请在中转站确认该分组的模型配置与这把 key 的权限，或在卡片用「模型清单覆盖」显式指定模型。这把 key 已跳过，其余 key 照常同步`);
+		}
 		if (this.credentials.resolve !== undefined) {
 			const stored = await this.credentials.resolve(ref);
 			if (stored?.value !== plaintext) await this.credentials.set(ref, plaintext);
@@ -1132,7 +1154,7 @@ var Sub2apiSyncEngine = class {
 			});
 			return await client.listModels(relayKey);
 		} catch (error) {
-			throw new Sub2apiSyncError(`分组 ${groupId} 模型发现失败：${messageOf(error)}；且未配置 modelListOverrides 兜底`);
+			throw new Sub2apiSyncError(`分组 ${groupId} 模型发现失败：${messageOf$1(error)}；且未配置 modelListOverrides 兜底`);
 		}
 	}
 	readCurrentProviders() {
@@ -1382,6 +1404,10 @@ function absoluteHttpUrl(value) {
 		return undefined;
 	}
 }
+/** The provider issuer path under the instance root; the sub2api provider
+* issues `issuer = {instance}/api/v1/oauth` (no trailing slash). Every
+* discovery URL below is derived from this value, never guessed. */
+const PROVIDER_ISSUER_PATH = "/api/v1/oauth";
 async function discoverOAuthEndpoints(instance, fetchImpl = globalThis.fetch, now = Date.now()) {
 	const key = instance.trim().replace(/\/+$/, "").toLowerCase();
 	const cached = discoveryCache.get(key);
@@ -1390,20 +1416,44 @@ async function discoverOAuthEndpoints(instance, fetchImpl = globalThis.fetch, no
 		throw new OAuthError("discovery_failed", "sub2api OAuth 发现失败（此前已失败，稍后重试）");
 	}
 	const base = instance.trim().replace(/\/+$/, "");
-	const candidates = [`${base}/.well-known/oauth-authorization-server`, `${base}/api/v1/oauth/.well-known`];
+	const expectedIssuer = `${base}${PROVIDER_ISSUER_PATH}`;
+	const candidates = [
+		{
+			url: `${base}/.well-known/oauth-authorization-server${PROVIDER_ISSUER_PATH}`,
+			requireIssuerField: true
+		},
+		{
+			url: `${base}/.well-known/oauth-authorization-server`,
+			requireIssuerField: false
+		},
+		{
+			url: `${expectedIssuer}/.well-known`,
+			requireIssuerField: false
+		}
+	];
 	let endpoints;
 	let lastError = "";
 	for (const candidate of candidates) try {
-		const response = await fetchImpl(candidate, { headers: { accept: "application/json" } });
+		const response = await fetchImpl(candidate.url, { headers: { accept: "application/json" } });
 		if (!response.ok) {
-			lastError = `HTTP ${response.status} at ${candidate}`;
+			lastError = `HTTP ${response.status} at ${candidate.url}`;
 			continue;
 		}
 		const payload = await response.json();
+		const documentIssuer = typeof payload.issuer === "string" ? payload.issuer : undefined;
+		if (documentIssuer === undefined) {
+			if (candidate.requireIssuerField) {
+				lastError = `metadata at ${candidate.url} omits the required issuer field`;
+				continue;
+			}
+		} else if (documentIssuer !== expectedIssuer) {
+			lastError = `issuer mismatch at ${candidate.url}: ${documentIssuer} (expected ${expectedIssuer})`;
+			continue;
+		}
 		const authorizationEndpoint = absoluteHttpUrl(payload.authorization_endpoint);
 		const tokenEndpoint = absoluteHttpUrl(payload.token_endpoint);
 		if (authorizationEndpoint === undefined || tokenEndpoint === undefined) {
-			lastError = `incomplete metadata at ${candidate}`;
+			lastError = `incomplete metadata at ${candidate.url}`;
 			continue;
 		}
 		const revocationEndpoint = absoluteHttpUrl(payload.revocation_endpoint);
@@ -1414,7 +1464,7 @@ async function discoverOAuthEndpoints(instance, fetchImpl = globalThis.fetch, no
 		};
 		break;
 	} catch (error) {
-		lastError = `${candidate}: ${error instanceof Error ? error.message : String(error)}`;
+		lastError = `${candidate.url}: ${error instanceof Error ? error.message : String(error)}`;
 	}
 	discoveryCache.set(key, {
 		endpoints,
@@ -2168,6 +2218,252 @@ else await this.credentials.unset(this.refreshRef());
 	}
 };
 
+//#endregion
+//#region src/dshgo.ts
+const ZH = {
+	signedInPrefix: "已登录",
+	signedOut: "未登录：在设置里填写实例地址与邮箱，凭据槽写入面板密码",
+	noEmail: "请先在设置里填写面板邮箱",
+	loginAction: "登录面板",
+	logoutAction: "退出登录",
+	syncAction: "立即同步",
+	syncing: "同步中",
+	idle: "空闲",
+	instanceLabel: "实例",
+	stateLabel: "状态",
+	routesLabel: "路由数",
+	lastSyncLabel: "上次同步",
+	never: "尚未同步",
+	loginStarted: "正在登录…",
+	logoutStarted: "正在退出…",
+	twoFaHint: "该账号开启了两步验证：请在网页版设置卡完成第二因子",
+	hint: "勾选 key、两步验证与逐路由移除请在网页版设置卡操作",
+	justNow: "刚刚",
+	minutesAgo: (n) => n + " 分钟前",
+	hoursAgo: (n) => n + " 小时前",
+	daysAgo: (n) => n + " 天前"
+};
+const EN = {
+	signedInPrefix: "Signed in",
+	signedOut: "Signed out: fill the instance URL and email in settings, write the panel password into the credential slot",
+	noEmail: "Fill the panel email in settings first",
+	loginAction: "Sign in",
+	logoutAction: "Sign out",
+	syncAction: "Sync now",
+	syncing: "Syncing",
+	idle: "Idle",
+	instanceLabel: "Instance",
+	stateLabel: "State",
+	routesLabel: "Routes",
+	lastSyncLabel: "Last sync",
+	never: "Never",
+	loginStarted: "Signing in…",
+	logoutStarted: "Signing out…",
+	twoFaHint: "Two-factor is enabled: finish the second factor in the web settings card",
+	hint: "Key selection, two-factor and per-route removal live in the web settings card",
+	justNow: "just now",
+	minutesAgo: (n) => n + " min ago",
+	hoursAgo: (n) => n + " h ago",
+	daysAgo: (n) => n + " d ago"
+};
+const textOf = (locale) => typeof locale === "string" && locale.toLowerCase().startsWith("en") ? EN : ZH;
+function messageOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function relativeTime(at, t) {
+	const elapsed = Date.now() - at;
+	if (elapsed < 6e4) return t.justNow;
+	if (elapsed < 36e5) return t.minutesAgo(Math.floor(elapsed / 6e4));
+	if (elapsed < 864e5) return t.hoursAgo(Math.floor(elapsed / 36e5));
+	return t.daysAgo(Math.floor(elapsed / 864e5));
+}
+function registerDshGo(ctx, deps, hooks) {
+	ctx.inject(["dshGo"], (host) => {
+		const dshGo = host.dshGo;
+		if (dshGo === undefined) return;
+		/** Transient feedback from background actions; cleared by the next success. */
+		let lastError;
+		let hint;
+		let activeLocale = "zh-CN";
+		const buildData = async () => {
+			const t = textOf(activeLocale);
+			let signedIn = false;
+			let email;
+			try {
+				const auth = await deps.authState();
+				signedIn = auth.signedIn;
+				email = auth.email;
+			} catch {
+				signedIn = false;
+			}
+			const routes = deps.ownedRoutes();
+			const lastSyncAt = deps.lastReportAt();
+			const statusLine = lastError !== undefined ? {
+				text: lastError,
+				tone: "bad"
+			} : hint !== undefined ? {
+				text: hint,
+				tone: "info"
+			} : signedIn ? {
+				text: t.signedInPrefix + (email !== undefined && email.length > 0 ? " · " + email : ""),
+				tone: "good"
+			} : {
+				text: t.signedOut,
+				tone: "warn"
+			};
+			return {
+				statusText: statusLine.text,
+				statusTone: statusLine.tone,
+				signedIn,
+				instance: deps.instance(),
+				stateText: deps.isSyncRunning() ? t.syncing : signedIn ? t.idle : t.signedOut,
+				routeCount: routes.length,
+				lastSyncText: lastSyncAt === undefined ? t.never : relativeTime(lastSyncAt, t),
+				routes: routes.map((route) => ({
+					title: route.displayName ?? route.route,
+					...route.api !== undefined ? { subtitle: route.api } : {},
+					trailing: String(route.models)
+				})),
+				actions: signedIn ? [{
+					label: t.syncAction,
+					style: "primary",
+					action: "sync"
+				}, {
+					label: t.logoutAction,
+					action: "logout"
+				}] : [{
+					label: t.loginAction,
+					style: "primary",
+					action: "login"
+				}]
+			};
+		};
+		/** Broadcast one fresh model to every live data/strip source. */
+		const sinks = new Set();
+		const publish = (data) => {
+			for (const sink of [...sinks]) sink(data);
+		};
+		const schedule = () => {
+			void buildData().then(publish).catch(() => undefined);
+		};
+		/** Emit now, on every settle, and on a bounded tick until cancelled. */
+		const watch = (sink) => {
+			sinks.add(sink);
+			schedule();
+			const timer = setInterval(schedule, 15e3);
+			return () => {
+				sinks.delete(sink);
+				clearInterval(timer);
+			};
+		};
+		const noteError = (cause) => {
+			lastError = messageOf(cause);
+			schedule();
+		};
+		dshGo.panel("sync-status", {
+			view: (_scope, caps) => {
+				const t = textOf(caps?.locale);
+				return {
+					type: "stack",
+					children: [
+						{
+							type: "callout",
+							text: { $: "data.statusText" },
+							tone: { $: "data.statusTone" }
+						},
+						{
+							type: "row",
+							children: [{
+								type: "metric",
+								label: t.routesLabel,
+								value: { $: "data.routeCount" },
+								tone: "info"
+							}, {
+								type: "metric",
+								label: t.lastSyncLabel,
+								value: { $: "data.lastSyncText" },
+								tone: "info"
+							}]
+						},
+						{
+							type: "keyValue",
+							items: [[t.instanceLabel, { $: "data.instance" }], [t.stateLabel, { $: "data.stateText" }]]
+						},
+						{
+							type: "list",
+							items: { $: "data.routes" }
+						},
+						{
+							type: "actions",
+							items: { $: "data.actions" }
+						},
+						{
+							type: "text",
+							tone: "muted",
+							text: t.hint
+						}
+					]
+				};
+			},
+			data: (_scope, emit, caps) => {
+				activeLocale = caps?.locale ?? activeLocale;
+				let alive = true;
+				const cancel = watch((data) => {
+					if (alive) emit(data);
+				});
+				return () => {
+					alive = false;
+					cancel();
+				};
+			},
+			actions: {
+				sync: () => {
+					const t = textOf(activeLocale);
+					if (deps.isSyncRunning()) return { toast: t.syncing + "…" };
+					lastError = undefined;
+					void deps.sync().then(schedule).catch(noteError);
+					return { toast: t.syncAction + " · " + t.syncing + "…" };
+				},
+				login: () => {
+					const t = textOf(activeLocale);
+					const email = hooks.email()?.trim() ?? "";
+					if (email.length === 0) return { toast: t.noEmail };
+					hint = undefined;
+					lastError = undefined;
+					void deps.login(email, undefined).then((response) => {
+						hint = response.kind === "2fa" ? t.twoFaHint : undefined;
+						schedule();
+					}).catch(noteError);
+					return { toast: t.loginStarted };
+				},
+				logout: () => {
+					const t = textOf(activeLocale);
+					lastError = undefined;
+					void deps.logout().then(schedule).catch(noteError);
+					return { toast: t.logoutStarted };
+				}
+			}
+		});
+		dshGo.strip("sync-strip", (_scope, emit, caps) => {
+			activeLocale = caps?.locale ?? activeLocale;
+			let alive = true;
+			const cancel = watch((data) => {
+				if (!alive) return;
+				const t = textOf(activeLocale);
+				emit({
+					text: data.signedIn ? data.routeCount + " · " + data.lastSyncText : "Sub2API · " + t.signedOut,
+					icon: "chart",
+					...data.statusTone === "bad" ? { tone: "bad" } : {}
+				});
+			});
+			return () => {
+				alive = false;
+				cancel();
+			};
+		});
+	});
+}
+
 //#endregion
 //#region src/routes.ts
 function callbackLangOf(acceptLanguage) {
@@ -2717,7 +3013,7 @@ function apply(ctx, config) {
 		authState: () => gateway.authState(source().email),
 		login: async (email, password) => {
 			const typed = password !== undefined && password.length > 0 ? password : undefined;
-			let pwd = typed ?? (await credentials.resolve(panelPasswordRef(instance())))?.value;
+			let pwd = typed ?? (await credentials.resolve(panelPasswordRef(instance())))?.value ?? (await credentials.resolve(NATIVE_PANEL_PASSWORD_REF))?.value;
 			if (pwd === undefined || pwd.length === 0) throw new Error("请输入面板密码（首次登录后密码会保存到凭据存储，之后可免输入）");
 			await mutateOwn([{
 				op: "set",
@@ -2926,6 +3222,7 @@ function apply(ctx, config) {
 		}
 	};
 	registerRoutes(ctx, deps);
+	registerDshGo(ctx, deps, { email: () => source().email });
 	let timer;
 	let armedFor;
 	const disarm = () => {

package/lib/oauth.d.ts

@@ -2,9 +2,12 @@
  * 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;
+ * - endpoint discovery per RFC 8414: the metadata URL is derived by inserting
+ *   `/.well-known/oauth-authorization-server` between the host and the
+ *   provider issuer path (§3), the document's `issuer` field must match the
+ *   expected provider issuer exactly (§3.3), and the deployed host-root
+ *   registration plus the `/api/v1/oauth/.well-known` compatibility alias
+ *   serve as gated fallbacks — 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
@@ -35,9 +38,15 @@ export interface OAuthEndpoints {
     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.
+ * Resolve the provider metadata per RFC 8414. The strict §3 location (the
+ * metadata URL derived from the provider issuer) is tried first and must echo
+ * the expected issuer (§3.3 — issuer field required); the deployed host-root
+ * registration and the versioned compatibility alias follow as gated
+ * fallbacks. Issuer validation is what keeps a complete document served by a
+ * *different* authorization server (e.g. the upstream MCP issuer at the host
+ * root after route B) from being adopted just because it parses. A failed or
+ * incomplete hunt 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. */

package/lib/types.d.ts

@@ -76,6 +76,13 @@ export declare function panelTokenRef(baseURL: string): string;
 export declare function panelRefreshRef(baseURL: string): string;
 /** Panel password credential reference for one instance (Mode A, C3). */
 export declare function panelPasswordRef(baseURL: string): string;
+/**
+ * Fixed credential slot behind the dsh-Go native settings page: a password
+ * set on the phone lands here. The per-instance ref above remains the
+ * gateway's own storage for proven-good passwords; login resolution reads
+ * the instance ref first and this slot as the final fallback.
+ */
+export declare const NATIVE_PANEL_PASSWORD_REF: "DSH_SUB2API_PANEL_PASSWORD";
 /** 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). */

package/locale/en.json

@@ -1,6 +1,7 @@
 {
   "meta": {
     "title": "Sub2API Sync",
-    "description": "Sync one sub2api instance's groups, keys, and models into dsh-llm-pi-ai provider routes: panel-driven login (password / OAuth), one relay key one provider."
+    "description": "Sync a sub2api instance's groups, keys, and models into dsh provider routes: pick relay keys on the panel, one key becomes one provider, models usable on the next request. Naming, protocol mapping, and scheduled resync are tuned on the plugin page. Requires a reachable sub2api instance and panel account.",
+    "detail": "docs/DETAIL.md"
   }
 }

package/locale/zh.json

@@ -1,6 +1,7 @@
 {
   "meta": {
     "title": "Sub2API 同步",
-    "description": "把一个 sub2api 实例的分组、key 与模型同步为 dsh-llm-pi-ai 供应商路由：面板登录（密码 / OAuth），一把 key 一个供应商。"
+    "description": "把 sub2api 实例的分组、密钥与模型同步为 dsh 的供应商路由：在面板里勾选 relay key，一把 key 生成一个供应商，模型下一请求即可用。供应商命名、协议映射与定时同步都可在插件页调整。使用前需要一个可访问的 sub2api 实例和面板账号。",
+    "detail": "docs/DETAIL.zh.md"
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mangoc/dsh-sub2api-sync",
-  "description": "Sync one sub2api instance's groups, keys, and models into dsh-llm-pi-ai provider routes: panel-driven login (password / OAuth), one relay key one provider.",
-  "version": "0.2.8",
+  "description": "Sync one sub2api instance's groups, keys, and models into dsh-llm-pi-ai provider routes: panel-driven login (password / OAuth), one provider per relay key.",
+  "version": "0.3.0",
   "license": "MIT",
   "author": "Shuai-S",
   "homepage": "https://github.com/Shuai-S/dsh-sub2api-sync#readme",
@@ -39,6 +39,8 @@
     "lib",
     "data",
     "locale",
+    "docs",
+    "icon.svg",
     "cordis.patch.yml",
     "README.md",
     "README.zh.md"
@@ -58,6 +60,37 @@
       "platform": "web"
     }
   },
+  "dshGo": {
+    "v": 1,
+    "title": {
+      "zh": "Sub2API 同步",
+      "en": "Sub2API Sync"
+    },
+    "icon": "chart",
+    "contributes": {
+      "composer.strip": [
+        {
+          "id": "sync-strip",
+          "icon": "chart",
+          "panel": "sync-status"
+        }
+      ],
+      "panels": [
+        {
+          "id": "sync-status",
+          "title": {
+            "zh": "同步状态",
+            "en": "Sync status"
+          },
+          "icon": "chart",
+          "placement": [
+            "session.tab",
+            "features"
+          ]
+        }
+      ]
+    }
+  },
   "dependencies": {
     "@deepseek-ai/dsh-credentials": "0.2.0-rc.2",
     "@deepseek-ai/schemastery": "^3.18.4"
@@ -112,6 +145,7 @@
     "typescript": "^5.7.0",
     "vitest": "^3.2.4"
   },
+  "icon": "./icon.svg",
   "scripts": {
     "build": "tsdown && node scripts/wrap-client.mjs",
     "pack:all": "node scripts/pack-all.mjs",