@dsh-plus/access-gate 0.1.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@dsh-plus/access-gate",
+  "version": "0.1.0",
+  "description": "dsh-plus service+ui plugin: dsh web 全量访问围栏——本机直连永久放行，远程按白名单 IP（XFF 还原）或 token（登录页 + cookie）放行",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-api-remotes"
+      ],
+      "platform": "web"
+    }
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.8",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-home-paths": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "3.18.1",
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/A-G-guy/dsh-plus.git",
+    "directory": "packages/access-gate"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}

package/src/client/card.tsx

@@ -0,0 +1,432 @@
+/**
+ * 「访问控制」配置卡片：注册进 settings.plugin.item 插槽（官方插件配置页）。
+ * 交互对齐官方卡片：折叠/展开、staged draft、未保存标记、保存/放弃。
+ * 配置读写走官方 settingsScope 传输（scope.ts）：value 为 schema 解析后的
+ * 脱敏视图（token 不出现，tokenConfigured 经 describe 的 secrets 探测），
+ * 保存经 settings.update 深合并（空 token 剔除 = 保持不变）。
+ * 卡片顶部「当前页面诊断」读 /dsh-plus/gate/status（本页放行原因/客户端 IP）。
+ * @module access-gate/client/card
+ */
+import { type ReactElement, useEffect, useMemo, useState, useSyncExternalStore } from 'react'
+
+import { SETTINGS_NS } from '../ns.ts'
+import type { Scope, SettingsApi } from './scope.ts'
+
+export interface CardProps {
+  t(key: string): string
+  scope: Scope
+  api: SettingsApi
+}
+
+/** settings 命名空间的脱敏解析值（token 被脱敏剥除）。 */
+export interface ConfigValue {
+  enabled: boolean
+  allowedIps: string[]
+  trustForwardedFor: boolean
+  cookieMaxAgeHours: number
+  loginFailLimit: number
+  loginCooldownMs: number
+}
+
+interface Draft {
+  enabled: boolean
+  token: string
+  allowedIpsText: string
+  trustForwardedFor: boolean
+  cookieMaxAgeHours: string
+  loginFailLimit: string
+  loginCooldownMs: string
+}
+
+interface Status {
+  kind: 'idle' | 'ok' | 'error'
+  text: string
+}
+
+interface Diag {
+  enabled: boolean
+  verdict: string
+  clientIp: string | null
+  reason: string | null
+  invalidEntries: string[]
+  tokenConfigured: boolean
+  allowedCount: number
+}
+
+const IDLE_STATUS: Status = { kind: 'idle', text: '' }
+
+function draftFromValue(value: ConfigValue): Draft {
+  return {
+    enabled: value.enabled,
+    token: '',
+    allowedIpsText: value.allowedIps.join('\n'),
+    trustForwardedFor: value.trustForwardedFor,
+    cookieMaxAgeHours: String(value.cookieMaxAgeHours),
+    loginFailLimit: String(value.loginFailLimit),
+    loginCooldownMs: String(value.loginCooldownMs),
+  }
+}
+
+function isPositiveInt(text: string): boolean {
+  return /^[0-9]+$/.test(text) && Number(text) > 0
+}
+
+function toPatch(draft: Draft): Record<string, unknown> {
+  return {
+    enabled: draft.enabled,
+    allowedIps: draft.allowedIpsText
+      .split('\n')
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0),
+    trustForwardedFor: draft.trustForwardedFor,
+    cookieMaxAgeHours: Number(draft.cookieMaxAgeHours),
+    loginFailLimit: Number(draft.loginFailLimit),
+    loginCooldownMs: Number(draft.loginCooldownMs),
+  }
+}
+
+/** reason 枚举 → 文案 key。 */
+const REASON_KEYS: Record<string, string> = {
+  local: 'diagLocal',
+  'allowed-ip': 'diagAllowedIp',
+  token: 'diagToken',
+}
+
+function verdictLabel(t: (key: string) => string, diag: Diag): string {
+  if (!diag.enabled) return t('diagOff')
+  if (diag.verdict === 'pass') return t('diagPass')
+  if (diag.verdict === 'login') return t('diagLogin')
+  return t('diagBlock')
+}
+
+export function AccessGateCard(props: CardProps): ReactElement | null {
+  const { t, scope, api } = props
+  const snapshot = useSyncExternalStore(
+    (listener: () => void) => scope.subscribe(listener),
+    () => scope.getSnapshot(),
+  )
+  const value = snapshot.value as ConfigValue | undefined
+  const [open, setOpen] = useState(false)
+  const [draft, setDraft] = useState<Draft | null>(null)
+  const [tokenConfigured, setTokenConfigured] = useState(false)
+  const [diag, setDiag] = useState<Diag | null>(null)
+  const [saving, setSaving] = useState(false)
+  const [status, setStatus] = useState<Status>(IDLE_STATUS)
+
+  // 首次拿到解析值后播种草稿；后续 Host 更新不覆盖在途编辑（与官方 staged 表单一致）。
+  useEffect(() => {
+    if (value === undefined || draft !== null) return
+    setDraft(draftFromValue(value))
+  }, [value, draft])
+
+  // tokenConfigured 探测：经 describe 的 secrets 列表判断。
+  // biome-ignore lint/correctness/useExhaustiveDependencies: snapshot 变化（保存后 revision 推进）时刻意重探 secrets 状态
+  useEffect(() => {
+    let alive = true
+    api
+      .describe({})
+      .then((response) => {
+        if (!alive || !response.result.ok) return
+        const view = response.result.value?.namespaces.find((ns) => ns.ns === SETTINGS_NS)
+        setTokenConfigured(
+          view?.secrets.some((secret) => secret.path.join('.') === 'token' && secret.set) ?? false,
+        )
+      })
+      .catch(() => {})
+    return () => {
+      alive = false
+    }
+  }, [api, snapshot])
+
+  // 本页诊断：读围栏状态端点（配置保存后 snapshot 推进时重读）。
+  // biome-ignore lint/correctness/useExhaustiveDependencies: 配置保存后刻意重取诊断
+  useEffect(() => {
+    let alive = true
+    fetch('/dsh-plus/gate/status')
+      .then((res) => (res.ok ? res.json() : null))
+      .then((body: Diag | null) => {
+        if (alive && body !== null) setDiag(body)
+      })
+      .catch(() => {})
+    return () => {
+      alive = false
+    }
+  }, [snapshot])
+
+  const failClosed = useMemo(
+    () => value?.enabled === true && value.allowedIps.length === 0 && !tokenConfigured,
+    [value, tokenConfigured],
+  )
+  const dirty = useMemo(
+    () =>
+      value !== undefined &&
+      draft !== null &&
+      JSON.stringify(toPatch(draft)) !== JSON.stringify(toPatch(draftFromValue(value))),
+    [value, draft],
+  )
+  const invalid = useMemo(
+    () =>
+      draft !== null &&
+      (!isPositiveInt(draft.cookieMaxAgeHours) ||
+        !isPositiveInt(draft.loginFailLimit) ||
+        !isPositiveInt(draft.loginCooldownMs)),
+    [draft],
+  )
+
+  if (value === undefined || draft === null) {
+    return (
+      <li className="dag-card">
+        <p className="dag-readOnly">{t('loading')}</p>
+      </li>
+    )
+  }
+  const edit = <K extends keyof Draft>(key: K, editValue: Draft[K]): void => {
+    setDraft({ ...draft, [key]: editValue })
+    setStatus(IDLE_STATUS)
+  }
+  const onSave = (): void => {
+    setSaving(true)
+    const patch = toPatch(draft)
+    if (draft.token !== '') patch.token = draft.token
+    const revision = scope.getSnapshot().revision
+    api
+      .update({
+        ns: SETTINGS_NS,
+        patch,
+        ...(revision !== undefined ? { expectedRevision: revision } : {}),
+      })
+      .then(async (response) => {
+        if (!response.result.ok) {
+          throw new Error(response.result.error?.message ?? t('saveFailed'))
+        }
+        await scope.load()
+        const next = scope.getSnapshot().value as ConfigValue | undefined
+        if (next !== undefined) setDraft(draftFromValue(next))
+        setStatus(IDLE_STATUS)
+      })
+      .catch((error: unknown) => {
+        const message = error instanceof Error ? error.message : String(error)
+        setStatus({ kind: 'error', text: `${t('saveFailed')}${message}` })
+      })
+      .finally(() => setSaving(false))
+  }
+
+  const disabled = !snapshot.writable
+  return (
+    <li className={`dag-card${open ? ' dag-cardOpen' : ''}`}>
+      <button
+        type="button"
+        className="dag-header"
+        aria-expanded={open}
+        aria-label={`${t(open ? 'collapse' : 'expand')}: ${t('title')}`}
+        onClick={() => setOpen(!open)}
+      >
+        <span className="dag-headText">
+          <span className="dag-name">{t('title')}</span>
+          <span className="dag-description">{t('description')}</span>
+        </span>
+        {dirty ? <span className="dag-pending">{t('unsaved')}</span> : null}
+        <span className={`dag-chevron${open ? ' dag-chevronOpen' : ''}`}>▾</span>
+      </button>
+      {open ? (
+        <div className="dag-body">
+          {disabled ? (
+            <p className="dag-readOnly" role="status">
+              {t('readOnly')}
+            </p>
+          ) : null}
+          {failClosed ? <p className="dag-warn">{t('warnFailClosed')}</p> : null}
+          <div className="dag-field">
+            <div className="dag-head">
+              <label className="dag-label" htmlFor="dag-enabled">
+                {t('enabled')}
+              </label>
+            </div>
+            <div className="dag-checkRow">
+              <input
+                id="dag-enabled"
+                type="checkbox"
+                checked={draft.enabled}
+                disabled={disabled}
+                onChange={(event) => edit('enabled', event.target.checked)}
+              />
+              <label htmlFor="dag-enabled">{t('enabledHint')}</label>
+            </div>
+          </div>
+          <div className="dag-field">
+            <div className="dag-head">
+              <label className="dag-label" htmlFor="dag-token">
+                {t('token')}
+              </label>
+              <span className={`dag-badge ${tokenConfigured ? 'dag-badgeSet' : 'dag-badgeUnset'}`}>
+                {t(tokenConfigured ? 'tokenSet' : 'tokenUnset')}
+              </span>
+            </div>
+            <input
+              id="dag-token"
+              className="dag-input"
+              type="password"
+              autoComplete="off"
+              value={draft.token}
+              disabled={disabled}
+              onChange={(event) => edit('token', event.target.value)}
+            />
+            <p className="dag-hint">{t('tokenHint')}</p>
+          </div>
+          <div className="dag-field">
+            <div className="dag-head">
+              <label className="dag-label" htmlFor="dag-allowed">
+                {t('allowedIps')}
+              </label>
+            </div>
+            <textarea
+              id="dag-allowed"
+              className="dag-textarea"
+              rows={Math.min(8, Math.max(3, draft.allowedIpsText.split('\n').length))}
+              value={draft.allowedIpsText}
+              disabled={disabled}
+              onChange={(event) => edit('allowedIpsText', event.target.value)}
+            />
+            <p className="dag-hint">{t('allowedIpsHint')}</p>
+          </div>
+          <div className="dag-field">
+            <div className="dag-head">
+              <label className="dag-label" htmlFor="dag-xff">
+                {t('trustForwardedFor')}
+              </label>
+            </div>
+            <div className="dag-checkRow">
+              <input
+                id="dag-xff"
+                type="checkbox"
+                checked={draft.trustForwardedFor}
+                disabled={disabled}
+                onChange={(event) => edit('trustForwardedFor', event.target.checked)}
+              />
+              <label htmlFor="dag-xff">{t('trustForwardedForHint')}</label>
+            </div>
+          </div>
+          <div className="dag-field">
+            <div className="dag-head">
+              <label className="dag-label" htmlFor="dag-cookie">
+                {t('cookieMaxAgeHours')}
+              </label>
+            </div>
+            <input
+              id="dag-cookie"
+              className={`dag-input${isPositiveInt(draft.cookieMaxAgeHours) ? '' : ' dag-inputInvalid'}`}
+              type="text"
+              inputMode="numeric"
+              value={draft.cookieMaxAgeHours}
+              disabled={disabled}
+              aria-invalid={!isPositiveInt(draft.cookieMaxAgeHours) || undefined}
+              onChange={(event) => edit('cookieMaxAgeHours', event.target.value)}
+            />
+            <p className={isPositiveInt(draft.cookieMaxAgeHours) ? 'dag-hint' : 'dag-invalid'}>
+              {isPositiveInt(draft.cookieMaxAgeHours)
+                ? t('cookieMaxAgeHoursHint')
+                : t('invalidNumber')}
+            </p>
+          </div>
+          <div className="dag-field">
+            <div className="dag-head">
+              <label className="dag-label" htmlFor="dag-faillimit">
+                {t('loginFailLimit')}
+              </label>
+            </div>
+            <input
+              id="dag-faillimit"
+              className={`dag-input${isPositiveInt(draft.loginFailLimit) ? '' : ' dag-inputInvalid'}`}
+              type="text"
+              inputMode="numeric"
+              value={draft.loginFailLimit}
+              disabled={disabled}
+              aria-invalid={!isPositiveInt(draft.loginFailLimit) || undefined}
+              onChange={(event) => edit('loginFailLimit', event.target.value)}
+            />
+            <p className={isPositiveInt(draft.loginFailLimit) ? 'dag-hint' : 'dag-invalid'}>
+              {isPositiveInt(draft.loginFailLimit) ? t('loginFailLimitHint') : t('invalidNumber')}
+            </p>
+          </div>
+          <div className="dag-field">
+            <div className="dag-head">
+              <label className="dag-label" htmlFor="dag-cooldown">
+                {t('loginCooldownMs')}
+              </label>
+            </div>
+            <input
+              id="dag-cooldown"
+              className={`dag-input${isPositiveInt(draft.loginCooldownMs) ? '' : ' dag-inputInvalid'}`}
+              type="text"
+              inputMode="numeric"
+              value={draft.loginCooldownMs}
+              disabled={disabled}
+              aria-invalid={!isPositiveInt(draft.loginCooldownMs) || undefined}
+              onChange={(event) => edit('loginCooldownMs', event.target.value)}
+            />
+            <p className={isPositiveInt(draft.loginCooldownMs) ? 'dag-hint' : 'dag-invalid'}>
+              {isPositiveInt(draft.loginCooldownMs) ? t('loginCooldownMsHint') : t('invalidNumber')}
+            </p>
+          </div>
+          {diag !== null ? (
+            <div className={`dag-diag${diag.invalidEntries.length > 0 ? ' dag-diagWarn' : ''}`}>
+              <p className="dag-diagTitle">{t('diagTitle')}</p>
+              <div className="dag-diagRow">
+                <span className="dag-diagKey">{t('diagVerdict')}</span>
+                <span className="dag-diagVal">{verdictLabel(t, diag)}</span>
+              </div>
+              <div className="dag-diagRow">
+                <span className="dag-diagKey">{t('diagClientIp')}</span>
+                <span className="dag-diagVal">{diag.clientIp ?? '—'}</span>
+              </div>
+              <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) : '—'}
+                </span>
+              </div>
+              {diag.invalidEntries.length > 0 ? (
+                <div className="dag-diagRow">
+                  <span className="dag-diagKey">!</span>
+                  <span className="dag-diagVal">
+                    {t('diagInvalid')}
+                    {diag.invalidEntries.join('、')}
+                  </span>
+                </div>
+              ) : null}
+            </div>
+          ) : null}
+          <div className="dag-footer">
+            {status.kind !== 'idle' ? (
+              <p
+                className={`dag-status${status.kind === 'error' ? ' dag-statusError' : ''}`}
+                role="status"
+              >
+                {status.text}
+              </p>
+            ) : null}
+            <button
+              type="button"
+              className="dag-btn dag-btnGhost"
+              disabled={!dirty || saving}
+              onClick={() => {
+                setDraft(draftFromValue(value))
+                setStatus(IDLE_STATUS)
+              }}
+            >
+              {t('discard')}
+            </button>
+            <button
+              type="button"
+              className="dag-btn dag-btnPrimary"
+              disabled={!dirty || invalid || saving || disabled}
+              onClick={onSave}
+            >
+              {t(saving ? 'saving' : 'save')}
+            </button>
+          </div>
+        </div>
+      ) : null}
+    </li>
+  )
+}

package/src/client/client.ts

@@ -0,0 +1,156 @@
+/**
+ * 浏览器半入口：注册 locale 字典 + 向 settings.plugin.item 插槽注册「访问控制」卡片。
+ * 构建产物为 window.__ModuleLoader__.load({id, factory}) 形式的 CJS factory
+ * （包装见 tsdown.config.ts）；样式沿用官方 data-plugin-css 约定，HMR 据此卸载。
+ *
+ * 类型说明：浏览器半只用到 slots/locale/connection/remote 的很窄一面，
+ * 此处以最小本地接口声明（见 ./scope.ts），避免为构建期类型引入整条官方
+ * client 依赖树；运行时契约以官方 dsh-client-ui-settings-plugins 的
+ * settings.plugin.item 插槽与 dsh-client-connection 的 settings RPC 面为准。
+ * rc7 起该插槽为 keyed 槽位：key 必须是卡片编辑的 settings 命名空间
+ * （即服务端 settingsNamespace() 注册的同一字面量，见 ../ns.ts），
+ * 官方配置页按此 key 与 Host 已注册命名空间配对分发。
+ * 配置读写经官方 settings RPC 直连（rc7 起第三方命名空间全量开放；
+ * 不复用 settingsScope 服务——非 loopback 页面下它无数据，见 scope.ts）。
+ * @module @dsh-plus/access-gate/client
+ */
+import type { Context } from '@deepseek-ai/cordis'
+
+import { SETTINGS_NS } from '../ns.ts'
+import { AccessGateCard } from './card.tsx'
+import { en, NS, zh } from './i18n.ts'
+import type { Scope, ScopeSnapshot, SettingsApi } from './scope.ts'
+import { injectStyle } from './styles.ts'
+
+export const name = 'dsh-plus-access-gate'
+
+/** 浏览器半需要的 cordis 服务 key（loader 据此注入；package.json 的 dsh.client.inject 管包加载顺序）。 */
+export const inject = ['slots', 'locale', 'connection', 'remote'] 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 {
+  $on(event: string, listener: (payload?: unknown) => void): () => void
+}
+
+interface ConnectionLike {
+  api: { settings: SettingsApi }
+}
+
+interface ClientContext {
+  slots: SlotsLike
+  locale: LocaleLike
+  get(key: 'connection'): ConnectionLike
+  get(key: 'remote'): RemoteLike
+  on(event: string, listener: () => void): () => void
+  effect(execute: () => () => void, label?: string): unknown
+}
+
+/**
+ * api 直连实现的命名空间 scope（官方配置页 tab 同款模式）。
+ * 读：describe 取命名空间视图（脱敏 value/revision + 顶层 writable）；
+ * 刷新：remote `settings/document-updated`（按命名空间过滤）与
+ * `connection/reset`；generation 防旧读覆盖新发布。任何页面 origin
+ * （loopback 或 tailnet 信任域名）下行为一致。
+ */
+function createApiScope(api: SettingsApi, ns: string, c: ClientContext): Scope {
+  let state: ScopeSnapshot = {
+    status: 'loading',
+    value: undefined,
+    revision: undefined,
+    writable: false,
+  }
+  const listeners = new Set<() => void>()
+  let generation = 0
+  const publish = (next: ScopeSnapshot): void => {
+    state = next
+    for (const listener of [...listeners]) listener()
+  }
+  const load = async (): Promise<void> => {
+    const gen = ++generation
+    let response: Awaited<ReturnType<SettingsApi['describe']>>
+    try {
+      response = await api.describe({})
+    } catch {
+      return
+    }
+    if (gen !== generation || !response.result.ok) return
+    const writable = response.result.value?.writable ?? false
+    const view = response.result.value?.namespaces.find((candidate) => candidate.ns === ns)
+    if (view === undefined) {
+      publish({
+        status: 'unavailable',
+        value: undefined,
+        revision: undefined,
+        writable,
+      })
+      return
+    }
+    publish({
+      status: 'ready',
+      value: view.value,
+      revision: view.revision,
+      writable,
+    })
+  }
+  const refresh = (namespace?: unknown): void => {
+    if (namespace !== undefined && namespace !== ns) return
+    void load()
+  }
+  const disposers = [
+    c.get('remote').$on('settings/document-updated', refresh),
+    c.on('connection/reset', () => {
+      void load()
+    }),
+  ]
+  c.effect(
+    () => () => {
+      for (const dispose of disposers) dispose()
+    },
+    'access-gate: settings scope',
+  )
+  void load()
+  return {
+    getSnapshot: () => state,
+    subscribe: (listener: () => void) => {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    load,
+  }
+}
+
+export function apply(ctx: Context): void {
+  const c = ctx as unknown as ClientContext
+  const tag = injectStyle()
+  c.effect(
+    () => () => {
+      tag?.remove()
+    },
+    'access-gate: style',
+  )
+  c.effect(() => c.locale.register(NS, { zh, en }), 'access-gate: locale')
+  const api = c.get('connection').api.settings
+  const scope = createApiScope(api, SETTINGS_NS, c)
+  c.slots.inject('settings.plugin.item', () =>
+    c.slots.register(
+      {
+        name: 'settings.plugin.item',
+        key: SETTINGS_NS,
+        locale: NS,
+        inject: () => ({ t: c.locale.bind(NS), scope, api }),
+      },
+      AccessGateCard,
+    ),
+  )
+}