@dsh-plus/access-gate 0.3.5 → 0.3.7

package/lib/client.js

@@ -133,7 +133,10 @@ window.__ModuleLoader__.load({
 			confirm: "Confirm",
 			cancel: "Cancel"
 		};
-		/** own 覆盖同键合并（返回新对象，入参不可变）。 */
+		/**
+		* own 覆盖同键合并（返回新对象，入参不可变）。
+		* 返回类型保留两侧键集合，调用方据此派生 DictKey。
+		*/
 		function mergeDict(base, own) {
 			return {
 				...base,
@@ -369,12 +372,17 @@ ${extra}
 				autoLoginTrustedIps: draft.autoLoginTrustedIps
 			};
 		}
-		/** reason 枚举 → 文案 key。 */
+		/** reason 枚举 → 文案 key（未知 reason 原样展示服务端文本，不当作文案键）。 */
 		const REASON_KEYS = {
 			local: "diagLocal",
 			cookie: "diagCookie",
 			"trusted-ip": "diagTrustedIp"
 		};
+		/** reason → 展示文本：已知枚举走本地化，未知回落服务端原串。 */
+		function reasonText(t, reason) {
+			const key = REASON_KEYS[reason];
+			return key === void 0 ? reason : t(key);
+		}
 		function verdictLabel(t, diag) {
 			if (!diag.enabled) return t("diagOff");
 			if (diag.verdict === "pass") return t("diagPass");
@@ -554,7 +562,7 @@ ${extra}
 									children: t("diagReason")
 								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 									className: "dag-diagVal",
-									children: diag.reason !== null ? t(REASON_KEYS[diag.reason] ?? diag.reason) : "—"
+									children: diag.reason !== null ? reasonText(t, diag.reason) : "—"
 								})]
 							}),
 							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {

package/lib/index.d.ts

@@ -16,7 +16,7 @@ type AccessGateConfig = Schemastery.TypeT<typeof Config>;
 //#endregion
 //#region src/index.d.ts
 declare const name = "dsh-plus-access-gate";
-declare const inject: readonly ["webServer", "connection"];
+declare const inject: readonly ['webServer', 'connection'];
 declare module '@deepseek-ai/cordis' {
   interface Context {
     accessGate: AccessGateService;

package/lib/index.js

@@ -726,7 +726,7 @@ function installGateInterceptor(ctx, server, deps) {
 		wrapped.clear();
 	} });
 	const undo = () => {
-		for (let i = restores.length - 1; i >= 0; i -= 1) restores[i].undo();
+		for (const restore of [...restores].reverse()) restore.undo();
 	};
 	return undo;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-plus/access-gate",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "dsh-plus service+ui plugin: dsh web 全量访问围栏——与官方 browser-auth 合并：官方 cookie 为唯一凭据，可选 IP 附加围栏，未认证导航渲染 token 输入页（PWA 可恢复），loopback 管理通道",
   "type": "module",
   "main": "lib/index.js",
@@ -31,7 +31,7 @@
     }
   },
   "dependencies": {
-    "@dsh-plus/shared": "0.1.14"
+    "@dsh-plus/shared": "0.1.16"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",

package/src/client/card.tsx

@@ -21,9 +21,10 @@ import {
   type Scope,
 } from '@dsh-plus/shared/client'
 import { type ReactElement, useEffect, useMemo, useState, useSyncExternalStore } from 'react'
+import type { DictKey, Translate } from './i18n.ts'
 
 export interface CardProps {
-  t(key: string): string
+  t: Translate
   scope: Scope
   api: NamespaceSettingsApi
 }
@@ -77,14 +78,20 @@ function toPatch(draft: Draft): Record<string, unknown> {
   }
 }
 
-/** reason 枚举 → 文案 key。 */
-const REASON_KEYS: Record<string, string> = {
+/** reason 枚举 → 文案 key（未知 reason 原样展示服务端文本，不当作文案键）。 */
+const REASON_KEYS: Record<string, DictKey | undefined> = {
   local: 'diagLocal',
   cookie: 'diagCookie',
   'trusted-ip': 'diagTrustedIp',
 }
 
-function verdictLabel(t: (key: string) => string, diag: Diag): string {
+/** reason → 展示文本：已知枚举走本地化，未知回落服务端原串。 */
+function reasonText(t: Translate, reason: string): string {
+  const key = REASON_KEYS[reason]
+  return key === undefined ? reason : t(key)
+}
+
+function verdictLabel(t: Translate, diag: Diag): string {
   if (!diag.enabled) return t('diagOff')
   if (diag.verdict === 'pass') return t('diagPass')
   if (diag.verdict === 'token-page') return t('diagTokenPage')
@@ -251,7 +258,7 @@ export function AccessGateCard(props: CardProps): ReactElement | null {
           <div className="dag-diagRow">
             <span className="dag-diagKey">{t('diagReason')}</span>
             <span className="dag-diagVal">
-              {diag.reason !== null ? t(REASON_KEYS[diag.reason] ?? diag.reason) : '—'}
+              {diag.reason !== null ? reasonText(t, diag.reason) : '—'}
             </span>
           </div>
           <div className="dag-diagRow">

package/src/client/client.ts

@@ -16,11 +16,11 @@ import type { Context } from '@deepseek-ai/cordis'
 import {
   createNamespaceApi,
   createSettingsScope,
-  type SettingsRemoteFace,
+  type PluginClientContext,
 } from '@dsh-plus/shared/client'
 import { SETTINGS_NS } from '../ns.ts'
 import { AccessGateCard } from './card.tsx'
-import { en, NS, zh } from './i18n.ts'
+import { type DictKey, en, NS, zh } from './i18n.ts'
 import { injectStyle } from './styles.ts'
 
 export const name = 'dsh-plus-access-gate'
@@ -28,28 +28,8 @@ export const name = 'dsh-plus-access-gate'
 /** 浏览器半需要的 cordis 服务 key（loader 据此注入；package.json 的 dsh.client.inject 管包加载顺序）。 */
 export const inject = ['slots', 'locale', 'remote', 'remote.settings'] as const
 
-interface SlotsLike {
-  inject(key: string, callback: () => unknown): unknown
-  register(options: Record<string, unknown>, component: unknown): () => void
-}
-
-interface LocaleLike {
-  register(ns: string, dict: { zh: Record<string, string>; en: Record<string, string> }): () => void
-  bind(ns: string): (key: string) => string
-}
-
-interface RemoteLike {
-  settings: SettingsRemoteFace
-  $on(event: string, listener: (payload?: unknown) => void): () => void
-}
-
-interface ClientContext {
-  slots: SlotsLike
-  locale: LocaleLike
-  get(key: 'remote'): RemoteLike
-  on(event: string, listener: () => void): () => void
-  effect(execute: () => () => void, label?: string): unknown
-}
+/** 宿主窄面收编在 @dsh-plus/shared/client；TKey 传入本包 DictKey 使键名受检。 */
+type ClientContext = PluginClientContext<DictKey>
 
 export function apply(ctx: Context): void {
   const c = ctx as unknown as ClientContext

package/src/client/i18n.ts

@@ -42,7 +42,7 @@ const ownZh = {
   diagAutoLoginNoSecret: '不可用（签名密钥读取失败，已降级）',
   diagOff: '围栏未启用',
   diagInvalid: '白名单存在无法解析的条目：',
-}
+} as const
 
 const ownEn = {
   title: 'Access Control',
@@ -80,7 +80,13 @@ const ownEn = {
   diagAutoLoginNoSecret: 'unavailable (signing secret unreadable, degraded)',
   diagOff: 'gate disabled',
   diagInvalid: 'Allowlist entries that failed to parse:',
-}
+} as const
 
-export const zh: Record<string, string> = mergeDict(commonZh, ownZh)
-export const en: Record<string, string> = mergeDict(commonEn, ownEn)
+export type DictKey = keyof typeof commonZh | keyof typeof ownZh
+
+/** 卡片/面板共用的翻译函数类型（slot 注入的 bind 结果按此消费）。 */
+export type Translate = (key: DictKey) => string
+
+// 标注为 Record<DictKey, string>：en 缺任一键即编译期报错（中英强制对齐）。
+export const zh: Record<DictKey, string> = mergeDict(commonZh, ownZh)
+export const en: Record<DictKey, string> = mergeDict(commonEn, ownEn)

package/src/cookie.ts

@@ -74,11 +74,29 @@ function validSignature(value: string, secret: Buffer): boolean {
   return actual.byteLength === expected.byteLength && timingSafeEqual(actual, expected)
 }
 
+/** cookie 载荷的三字段（官方 encodeCookie 的键集；version 由形状守卫单判）。 */
+interface CookiePayload {
+  authority: string
+  issuedAt: number
+  expiresAt: number
+}
+
+/**
+ * 载荷形状守卫（类型谓词）：version 必须等于 PAYLOAD_VERSION，三字段类型正确。
+ * 逐字段 `in` + typeof 收窄取代裸断言——JSON.parse 回来的是 unknown，
+ * 只有守卫通过后才允许按 CookiePayload 访问。
+ */
+function isCookiePayload(value: unknown): value is CookiePayload {
+  if (typeof value !== 'object' || value === null) return false
+  if (!('version' in value) || value.version !== PAYLOAD_VERSION) return false
+  if (!('authority' in value) || typeof value.authority !== 'string') return false
+  if (!('issuedAt' in value) || typeof value.issuedAt !== 'number') return false
+  if (!('expiresAt' in value) || typeof value.expiresAt !== 'number') return false
+  return Number.isSafeInteger(value.issuedAt) && Number.isSafeInteger(value.expiresAt)
+}
+
 /** 解码 cookie 载荷（返回 null = 值损坏/签名不符/字段缺失，语义与官方一致）。 */
-export function decodeCookiePayload(
-  value: string,
-  secret: Buffer,
-): { authority: string; issuedAt: number; expiresAt: number } | null {
+export function decodeCookiePayload(value: string, secret: Buffer): CookiePayload | null {
   if (!validSignature(value, secret)) return null
   const body = value.split('.')[1]
   if (body === undefined) return null
@@ -88,22 +106,8 @@ export function decodeCookiePayload(
   } catch {
     return null
   }
-  if (
-    typeof decoded !== 'object' ||
-    decoded === null ||
-    !('version' in decoded) ||
-    (decoded as { version?: unknown }).version !== PAYLOAD_VERSION ||
-    typeof (decoded as { authority?: unknown }).authority !== 'string' ||
-    !Number.isSafeInteger((decoded as { issuedAt?: unknown }).issuedAt) ||
-    !Number.isSafeInteger((decoded as { expiresAt?: unknown }).expiresAt)
-  ) {
-    return null
-  }
-  const { authority, issuedAt, expiresAt } = decoded as {
-    authority: string
-    issuedAt: number
-    expiresAt: number
-  }
+  if (!isCookiePayload(decoded)) return null
+  const { authority, issuedAt, expiresAt } = decoded
   const now = Date.now()
   if (issuedAt > now || expiresAt <= now || expiresAt <= issuedAt) return null
   if (expiresAt - issuedAt > COOKIE_MAX_AGE_MS) return null

package/src/decision.ts

@@ -29,12 +29,18 @@ export type GateVerdict =
 /** 判定输出。 */
 export interface GateDecision {
   verdict: GateVerdict
-  /** 还原出的客户端 IP（有 XFF 或非 loopback 直连时存在）。 */
-  clientIp?: string
+  /**
+   * 还原出的客户端 IP（有 XFF 或非 loopback 直连时存在）。
+   *
+   * 三个可选字段并上 `| undefined`：构造处用条件表达式直接给值
+   * （如 `const invalidEntries = ... ? x : undefined`），而消费方一律按
+   * 「缺席或 undefined 等价」处理（routes.ts 用 `?? []` 兜底）。
+   */
+  clientIp?: string | undefined
   /** 放行原因（诊断/日志用）：local / cookie / trusted-ip。 */
-  reason?: 'local' | 'cookie' | 'trusted-ip'
+  reason?: 'local' | 'cookie' | 'trusted-ip' | undefined
   /** 无效白名单条目（卡片诊断用，判定时忽略它们）。 */
-  invalidEntries?: string[]
+  invalidEntries?: string[] | undefined
 }
 
 /** 判定输入的请求事实（headers 小写键，node:http 原生形态）。 */
@@ -42,7 +48,9 @@ export interface GateRequest {
   readonly url: string
   readonly method: string
   readonly headers: Record<string, unknown>
-  readonly remoteAddress?: string
+  // 并上 undefined：来源是 `req.socket?.remoteAddress`（socket 可能缺席），
+  // 消费方 isLoopbackAddress 本就接受 string | undefined。
+  readonly remoteAddress?: string | undefined
 }
 
 /** 取 XFF 最左条目（serve 单跳覆盖语义下即真实客户端 IP）。 */

package/src/interceptor.ts

@@ -41,7 +41,9 @@ type UpgradeRoute = { path: string; handler: UpgradeHandler }
 export interface GateWebServer {
   match(pathname: string): unknown
   upgrades: Map<string, UpgradeRoute>
-  fallback?: HttpHandler
+  // 并上 undefined：本插件需在卸载时把 fallback 还原为「原本就没有」的状态
+  // （`server.fallback = originalFallback`，其值可能为 undefined）。
+  fallback?: HttpHandler | undefined
   registerFallback(handler: HttpHandler): unknown
   registerUpgrade(route: UpgradeRoute): unknown
   [key: string]: unknown
@@ -293,7 +295,8 @@ export function installGateInterceptor(
   })
 
   const undo = (): void => {
-    for (let i = restores.length - 1; i >= 0; i -= 1) restores[i].undo()
+    // 逆序还原（后装先撤）；forEach 直接取项，免去索引访问的 undefined 分支。
+    for (const restore of [...restores].reverse()) restore.undo()
   }
   void ctx
   return undo