@dsh-plus/access-gate 0.1.3 → 0.2.0

package/src/client/card.tsx

@@ -1,11 +1,14 @@
 /**
  * 「访问控制」配置卡片：注册进 settings.plugin.item 插槽（官方插件配置页）。
  * 外壳与基础控件走 @dsh-plus/shared/client 套件（CardChrome/TextField/CheckRow），
- * 本文件保留业务字段（token/白名单 textarea/诊断面板）与保存逻辑。
- * 配置读写走官方 settingsScope 传输：value 为 schema 解析后的脱敏视图
- * （token 不出现，tokenConfigured 经 describe 的 secrets 探测），
- * 保存经 settings.update 深合并（空 token 剔除 = 保持不变）。
- * 卡片顶部「当前页面诊断」读 /dsh-plus/gate/status（本页放行原因/客户端 IP）。
+ * 本文件保留业务字段（白名单 textarea/诊断面板）与保存逻辑。
+ * 配置读写走官方 settingsScope 传输：value 为 schema 解析后的视图，
+ * 保存经 settings.update 深合并。
+ * 卡片顶部「当前页面诊断」读 /dsh-plus/gate/status（本页放行原因/客户端 IP/
+ * 官方 cookie 状态）。
+ *
+ * 与官方认证合并后：访问凭据由官方 browser-auth 持有（30 天 cookie），
+ * 卡片不再管理令牌；allowedIps 仅为可选附加 IP 围栏。
  * @module access-gate/client/card
  */
 
@@ -14,37 +17,28 @@ import {
   type CardStatusState,
   CheckRow,
   IDLE_STATUS,
+  type NamespaceSettingsApi,
   type Scope,
-  type SettingsApi,
-  TextField,
 } from '@dsh-plus/shared/client'
 import { type ReactElement, useEffect, useMemo, useState, useSyncExternalStore } from 'react'
-import { SETTINGS_NS } from '../ns.ts'
 
 export interface CardProps {
   t(key: string): string
   scope: Scope
-  api: SettingsApi
+  api: NamespaceSettingsApi
 }
 
-/** settings 命名空间的脱敏解析值（token 被脱敏剥除）。 */
+/** settings 命名空间的解析值。 */
 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 Diag {
@@ -52,27 +46,20 @@ interface Diag {
   verdict: string
   clientIp: string | null
   reason: string | null
+  officialAuthed: boolean
+  ipFenceActive: boolean
   invalidEntries: string[]
-  tokenConfigured: boolean
   allowedCount: number
 }
 
 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,
@@ -81,23 +68,19 @@ function toPatch(draft: Draft): Record<string, unknown> {
       .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',
+  cookie: 'diagCookie',
 }
 
 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')
+  if (diag.verdict === 'token-page') return t('diagTokenPage')
   return t('diagBlock')
 }
 
@@ -110,7 +93,6 @@ export function AccessGateCard(props: CardProps): ReactElement | null {
   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<CardStatusState>(IDLE_STATUS)
@@ -121,25 +103,6 @@ export function AccessGateCard(props: CardProps): ReactElement | null {
     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(() => {
@@ -155,10 +118,6 @@ export function AccessGateCard(props: CardProps): ReactElement | null {
     }
   }, [snapshot])
 
-  const failClosed = useMemo(
-    () => value?.enabled === true && value.allowedIps.length === 0 && !tokenConfigured,
-    [value, tokenConfigured],
-  )
   const dirty = useMemo(
     () =>
       value !== undefined &&
@@ -166,14 +125,6 @@ export function AccessGateCard(props: CardProps): ReactElement | 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 (
@@ -189,18 +140,10 @@ export function AccessGateCard(props: CardProps): ReactElement | null {
   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'))
-        }
+      .update(patch, revision)
+      .then(async () => {
         await scope.load()
         const next = scope.getSnapshot().value as ConfigValue | undefined
         if (next !== undefined) setDraft(draftFromValue(next))
@@ -240,12 +183,12 @@ export function AccessGateCard(props: CardProps): ReactElement | null {
           key: 'save',
           label: t(saving ? 'saving' : 'save'),
           variant: 'primary',
-          disabled: !dirty || invalid || saving || disabled,
+          disabled: !dirty || saving || disabled,
           onClick: onSave,
         },
       ]}
     >
-      {failClosed ? <p className="dag-warn">{t('warnFailClosed')}</p> : null}
+      <p className="dag-hint">{t('mergedHint')}</p>
       <CheckRow
         prefix="dag"
         id="dag-enabled"
@@ -254,17 +197,6 @@ export function AccessGateCard(props: CardProps): ReactElement | null {
         disabled={disabled}
         onEdit={(v) => edit('enabled', v)}
       />
-      <TextField
-        prefix="dag"
-        id="dag-token"
-        label={t('token')}
-        hint={t('tokenHint')}
-        value={draft.token}
-        password
-        disabled={disabled}
-        badge={{ text: t(tokenConfigured ? 'tokenSet' : 'tokenUnset'), set: tokenConfigured }}
-        onEdit={(v) => edit('token', v)}
-      />
       <div className="dag-field">
         <div className="dag-head">
           <label className="dag-label" htmlFor="dag-allowed">
@@ -289,42 +221,6 @@ export function AccessGateCard(props: CardProps): ReactElement | null {
         disabled={disabled}
         onEdit={(v) => edit('trustForwardedFor', v)}
       />
-      <TextField
-        prefix="dag"
-        id="dag-cookie"
-        label={t('cookieMaxAgeHours')}
-        hint={t('cookieMaxAgeHoursHint')}
-        value={draft.cookieMaxAgeHours}
-        numeric
-        disabled={disabled}
-        invalid={!isPositiveInt(draft.cookieMaxAgeHours)}
-        invalidLabel={t('invalidNumber')}
-        onEdit={(v) => edit('cookieMaxAgeHours', v)}
-      />
-      <TextField
-        prefix="dag"
-        id="dag-faillimit"
-        label={t('loginFailLimit')}
-        hint={t('loginFailLimitHint')}
-        value={draft.loginFailLimit}
-        numeric
-        disabled={disabled}
-        invalid={!isPositiveInt(draft.loginFailLimit)}
-        invalidLabel={t('invalidNumber')}
-        onEdit={(v) => edit('loginFailLimit', v)}
-      />
-      <TextField
-        prefix="dag"
-        id="dag-cooldown"
-        label={t('loginCooldownMs')}
-        hint={t('loginCooldownMsHint')}
-        value={draft.loginCooldownMs}
-        numeric
-        disabled={disabled}
-        invalid={!isPositiveInt(draft.loginCooldownMs)}
-        invalidLabel={t('invalidNumber')}
-        onEdit={(v) => edit('loginCooldownMs', v)}
-      />
       {diag !== null ? (
         <div className={`dag-diag${diag.invalidEntries.length > 0 ? ' dag-diagWarn' : ''}`}>
           <p className="dag-diagTitle">{t('diagTitle')}</p>
@@ -342,6 +238,12 @@ export function AccessGateCard(props: CardProps): ReactElement | null {
               {diag.reason !== null ? t(REASON_KEYS[diag.reason] ?? diag.reason) : '—'}
             </span>
           </div>
+          <div className="dag-diagRow">
+            <span className="dag-diagKey">{t('diagOfficial')}</span>
+            <span className="dag-diagVal">
+              {diag.officialAuthed ? t('diagOfficialYes') : t('diagOfficialNo')}
+            </span>
+          </div>
           {diag.invalidEntries.length > 0 ? (
             <div className="dag-diagRow">
               <span className="dag-diagKey">!</span>

package/src/client/client.ts

@@ -3,17 +3,21 @@
  * 构建产物为 window.__ModuleLoader__.load({id, factory}) 形式的 CJS factory
  * （包装见 tsdown.config.ts）；样式沿用官方 data-plugin-css 约定，HMR 据此卸载。
  *
- * 类型说明：浏览器半只用到 slots/locale/connection/remote 的很窄一面，
+ * 类型说明：浏览器半只用到 slots/locale/remote 的很窄一面，
  * scope 与基础控件走 @dsh-plus/shared/client 套件（收编自本插件原实现）。
- * rc7 起该插槽为 keyed 槽位：key 必须是卡片编辑的 settings 命名空间
+ * 该插槽为 keyed 槽位：key 必须是卡片编辑的 settings 命名空间
  * （即服务端 settingsNamespace() 注册的同一字面量，见 ../ns.ts），
  * 官方配置页按此 key 与 Host 已注册命名空间配对分发。
- * 配置读写经官方 settings RPC 直连（rc7 起第三方命名空间全量开放；
- * 不复用 settingsScope 服务——非 loopback 页面下它无数据）。
+ * 配置读写经 ctx.remote.settings 直连（0.1.2-alpha.1 起 connection.api.settings
+ * 已移除；不复用 settingsScope 服务——非 loopback 页面下它固定 memory 模式无数据）。
  * @module @dsh-plus/access-gate/client
  */
 import type { Context } from '@deepseek-ai/cordis'
-import { createApiScope } from '@dsh-plus/shared/client'
+import {
+  createNamespaceApi,
+  createSettingsScope,
+  type SettingsRemoteFace,
+} from '@dsh-plus/shared/client'
 import { SETTINGS_NS } from '../ns.ts'
 import { AccessGateCard } from './card.tsx'
 import { en, NS, zh } from './i18n.ts'
@@ -22,7 +26,7 @@ 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
+export const inject = ['slots', 'locale', 'remote', 'remote.settings'] as const
 
 interface SlotsLike {
   inject(key: string, callback: () => unknown): unknown
@@ -35,17 +39,13 @@ interface LocaleLike {
 }
 
 interface RemoteLike {
+  settings: SettingsRemoteFace
   $on(event: string, listener: (payload?: unknown) => void): () => void
 }
 
-interface ConnectionLike {
-  api: { settings: Parameters<typeof createApiScope>[0] }
-}
-
 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
@@ -61,8 +61,8 @@ export function apply(ctx: Context): void {
     '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, 'access-gate: settings scope')
+  const scope = createSettingsScope(c, SETTINGS_NS, 'access-gate: settings scope')
+  const api = createNamespaceApi(c.get('remote').settings, SETTINGS_NS)
   c.slots.inject('settings.plugin.item', () =>
     c.slots.register(
       {

package/src/client/i18n.ts

@@ -9,77 +9,63 @@ export const NS = 'dsh-plus-access-gate'
 
 const ownZh = {
   title: '访问控制',
-  description: 'Web 访问围栏：本机直连放行；远程按白名单 IP 或访问令牌放行，其余拦截到登录页。',
+  description:
+    'Web 访问围栏：与官方登录合并——官方 cookie 为唯一凭据；未认证导航显示启动令牌输入页（PWA 内可用）；可选 IP 附加围栏。',
   enabled: '启用访问围栏',
-  enabledHint: '关闭即完全旁路（等价插件缺席）；启用后远程流量需命中白名单或令牌。',
-  token: '访问令牌',
-  tokenHint: '留空表示保持已存令牌不变；清空并保存需先输入既有令牌确认。',
-  tokenSet: '已配置',
-  tokenUnset: '未配置',
-  allowedIps: '放行 IP 白名单',
+  enabledHint: '关闭即完全旁路（等价插件缺席）；启用后未认证流量被拦截到令牌输入页或拒绝。',
+  mergedHint:
+    '登录凭据由官方认证持有（启动令牌换 30 天 cookie）。获取当前令牌：服务器执行 dshctl url，或本机访问 /dsh-plus/gate/launch-url。',
+  allowedIps: '附加 IP 围栏白名单',
   allowedIpsHint:
-    '每行一个：精确 IP 或 CIDR（IPv4/IPv6 皆可），如 100.86.108.55 或 fd7a:115c:a1e0::/48。',
+    '每行一个：精确 IP 或 CIDR（IPv4/IPv6 皆可）。非空时仅白名单来源可通行与登录；留空 = 不限制来源 IP（仅官方登录保护）。',
   trustForwardedFor: '信任 x-forwarded-for 还原客户端 IP',
   trustForwardedForHint:
     '仅当入口代理强制覆盖该头时开启（tailscale serve 满足）；直连暴露场景必须关闭。',
-  cookieMaxAgeHours: '登录有效期（小时）',
-  cookieMaxAgeHoursHint: '令牌登录后 cookie 的有效期。',
-  loginFailLimit: '登录失败阈值',
-  loginFailLimitHint: '每个 IP 在冷却窗口内允许的失败次数，超出进入冷却。',
-  loginCooldownMs: '登录冷却（毫秒）',
-  loginCooldownMsHint: '失败达到阈值后的冷却时长。',
   diagTitle: '当前页面诊断',
   diagVerdict: '本页判定',
   diagClientIp: '客户端 IP',
   diagReason: '放行原因',
   diagLocal: '本机直连',
-  diagAllowedIp: '白名单 IP',
-  diagToken: '令牌',
+  diagCookie: '官方 cookie',
+  diagOfficial: '官方登录状态',
+  diagOfficialYes: '已登录',
+  diagOfficialNo: '未登录',
   diagPass: '放行',
   diagBlock: '拦截',
-  diagLogin: '登录页',
+  diagTokenPage: '令牌输入页',
   diagOff: '围栏未启用',
   diagInvalid: '白名单存在无法解析的条目：',
-  warnFailClosed: '警告：已启用但令牌与白名单均为空——所有远程访问将被拒绝（含本页之外的设备）。',
 }
 
 const ownEn = {
   title: 'Access Control',
   description:
-    'Web access gate: loopback passes; remote traffic needs an allowlisted IP or the token, others hit the login page.',
+    'Web access gate merged with official auth: the official cookie is the sole credential; unauthenticated navigations get a launch-token page (works inside the PWA); optional IP fence.',
   enabled: 'Enable access gate',
   enabledHint:
-    'Off means full bypass (as if absent); on, remote traffic must match the allowlist or the token.',
-  token: 'Access token',
-  tokenHint: 'Leave blank to keep the stored token; clearing requires typing the current one.',
-  tokenSet: 'Set',
-  tokenUnset: 'Not set',
-  allowedIps: 'Allowed IP allowlist',
+    'Off means full bypass (as if absent); on, unauthenticated traffic hits the token page or is refused.',
+  mergedHint:
+    'Credentials are owned by official auth (launch token exchange, 30-day cookie). Get the current token: run dshctl url on the server, or visit /dsh-plus/gate/launch-url locally.',
+  allowedIps: 'Additional IP fence allowlist',
   allowedIpsHint:
-    'One per line: exact IP or CIDR (IPv4/IPv6), e.g. 100.86.108.55 or fd7a:115c:a1e0::/48.',
+    'One per line: exact IP or CIDR (IPv4/IPv6). When non-empty only listed sources may pass or log in; empty = no IP restriction (official login only).',
   trustForwardedFor: 'Trust x-forwarded-for for client IP',
   trustForwardedForHint:
     'Enable only when the entry proxy overwrites that header (tailscale serve does); must be off for direct exposure.',
-  cookieMaxAgeHours: 'Login validity (hours)',
-  cookieMaxAgeHoursHint: 'Cookie lifetime after a token login.',
-  loginFailLimit: 'Login failure limit',
-  loginFailLimitHint: 'Failures per IP within the cooldown window before throttling.',
-  loginCooldownMs: 'Login cooldown (ms)',
-  loginCooldownMsHint: 'Cooldown duration after reaching the limit.',
   diagTitle: 'This page',
   diagVerdict: 'Verdict',
   diagClientIp: 'Client IP',
   diagReason: 'Reason',
   diagLocal: 'loopback',
-  diagAllowedIp: 'allowlisted IP',
-  diagToken: 'token',
+  diagCookie: 'official cookie',
+  diagOfficial: 'Official login',
+  diagOfficialYes: 'authenticated',
+  diagOfficialNo: 'not authenticated',
   diagPass: 'pass',
   diagBlock: 'blocked',
-  diagLogin: 'login page',
+  diagTokenPage: 'token page',
   diagOff: 'gate disabled',
   diagInvalid: 'Allowlist entries that failed to parse:',
-  warnFailClosed:
-    'Warning: enabled with no token and an empty allowlist — all remote access will be refused.',
 }
 
 export const zh: Record<string, string> = mergeDict(commonZh, ownZh)

package/src/config.ts

@@ -2,7 +2,12 @@
  * 配置单一事实源：cordis 行级 Config（组合默认值，dev/prod patch 层可覆盖）
  * 与 settings namespace（用户层，经 dsh-settings-file 持久化到 $DSH_HOME/settings.yaml）
  * 共用同一 schemastery schema（notify-email 同款约定）。
- * token 标记 secret 角色：任何读取通道不得回传明文。
+ *
+ * 与官方认证合并后：访问凭据唯一化为官方 browser-auth cookie（dsh-auth-*，
+ * 由 client-connection 的 ?token= 启动令牌交换签发），本插件不再持有自有
+ * token/cookie；allowedIps 降级为可选的附加 IP 围栏。
+ * 旧配置中的 token/cookieMaxAgeHours/loginFailLimit/loginCooldownMs 键由
+ * schemastery 透传忽略，不阻断加载（已实测验证）。
  * @module access-gate/config
  */
 import { settingsNamespace } from '@deepseek-ai/dsh-settings'
@@ -18,14 +23,11 @@ export const Config = z.object({
     .boolean()
     .description('访问围栏总开关（false = 一切放行，等价插件缺席）')
     .default(false),
-  token: z
-    .string()
-    .role('secret')
-    .description('访问令牌；空字符串 = token 通道关闭。经登录页输入后以 HttpOnly cookie 持有')
-    .default(''),
   allowedIps: z
     .array(z.string())
-    .description('放行 IP 白名单：精确 IP 或 CIDR（IPv4/IPv6 皆可）')
+    .description(
+      '附加 IP 围栏：非空时仅白名单条目（精确 IP 或 CIDR，IPv4/IPv6 皆可）可通行与登录；空 = 不限制来源 IP（仅官方登录保护）',
+    )
     .default([]),
   trustForwardedFor: z
     .boolean()
@@ -33,16 +35,6 @@ export const Config = z.object({
       '是否信任 x-forwarded-for 还原真实客户端 IP（仅当入口代理强制覆盖该头时开启；tailscale serve 满足）',
     )
     .default(true),
-  cookieMaxAgeHours: z
-    .natural()
-    .max(24 * 365)
-    .description('登录 cookie 有效期（小时）')
-    .default(720),
-  loginFailLimit: z
-    .natural()
-    .description('登录失败节流阈值（每 IP 冷却窗口内允许的失败次数）')
-    .default(10),
-  loginCooldownMs: z.natural().description('登录失败节流冷却毫秒数').default(60000),
 })
 
 export type AccessGateConfig = Schemastery.TypeT<typeof Config>
@@ -50,12 +42,6 @@ export type AccessGateConfig = Schemastery.TypeT<typeof Config>
 /** 判定所需的最小配置视图（测试与决策函数共用窄面）。 */
 export interface GatePolicy {
   readonly enabled: boolean
-  readonly token: string
   readonly allowedIps: readonly string[]
   readonly trustForwardedFor: boolean
 }
-
-/** 远程放行通道是否全部关闭（enabled 且无 token 且白名单空 = 拒绝一切远程）。 */
-export function isFailClosed(policy: GatePolicy): boolean {
-  return policy.enabled && policy.token === '' && policy.allowedIps.length === 0
-}

package/src/decision.ts

@@ -4,33 +4,34 @@
  * 信任模型（决策记录详见 docs/README.md）：
  * - dsh web 仅绑 127.0.0.1，远程流量必经 tailscale serve → dsh-proxy 两跳，
  *   serve 会**覆盖**（而非追加）x-forwarded-for，客户端无法伪造；
- * - 能直发 loopback 或伪造 XFF 的只有本机进程——与 dsh 官方 /api 围栏的
- *   loopback 信任边界一致，本机直连视为可信管理通道；
+ * - 能直发 loopback 或伪造 XFF 的只有本机进程——本机直连视为可信管理通道；
  * - 因此 XFF 存在且 trustForwardedFor=true 时取最左条目为真实客户端 IP。
  *
- * token 比较使用 sha256 摘要 + timingSafeEqual 常时比较。
+ * 与官方认证合并后的判定语义：
+ * - 访问凭据唯一化为官方 browser-auth cookie——`officialAuthed` 由调用方
+ *   委托 `connection.requestRejection()` 得出，本模块不感知 cookie 细节；
+ * - `allowedIps` 为可选附加围栏：非空时来源 IP 不命中即拒（纵深防御），
+ *   空则不限制来源 IP（仅官方登录保护）；
+ * - 未认证的浏览器导航 → token 输入页（粘贴启动令牌走官方交换，PWA 同路径）；
+ *   未认证的非导航请求 → 403。
  * @module access-gate/decision
  */
-import { createHash, timingSafeEqual } from 'node:crypto'
-
 import type { GatePolicy } from './config.ts'
 import { isLoopbackAddress, parseAllowEntry, parseIp } from './ip.ts'
 
-export const GATE_COOKIE = 'dsh_gate'
-
 /** 围栏判定结果。 */
 export type GateVerdict =
-  | 'pass' /** 放行（本机直连 / 白名单 IP / 有效 token） */
-  | 'block' /** 拒绝：API / WebSocket 等非导航请求 → 403 */
-  | 'login' /** 拒绝：浏览器导航请求 → 登录页 */
+  | 'pass' /** 放行（本机直连 / 官方 cookie 有效） */
+  | 'block' /** 拒绝：非导航请求或 IP 围栏拦截 → 403 */
+  | 'token-page' /** 拒绝：浏览器导航请求 → token 输入页 */
 
 /** 判定输出。 */
 export interface GateDecision {
   verdict: GateVerdict
   /** 还原出的客户端 IP（有 XFF 或非 loopback 直连时存在）。 */
   clientIp?: string
-  /** 放行原因（诊断/日志用）：local / allowed-ip / token。 */
-  reason?: 'local' | 'allowed-ip' | 'token'
+  /** 放行原因（诊断/日志用）：local / cookie。 */
+  reason?: 'local' | 'cookie'
   /** 无效白名单条目（卡片诊断用，判定时忽略它们）。 */
   invalidEntries?: string[]
 }
@@ -43,29 +44,6 @@ export interface GateRequest {
   readonly remoteAddress?: string
 }
 
-/** sha256 摘要为定长 32 字节，常时比较的前提。 */
-function tokenMatches(candidate: string, expected: string): boolean {
-  if (candidate === '' || expected === '') return false
-  const a = createHash('sha256').update(candidate).digest()
-  const b = createHash('sha256').update(expected).digest()
-  return timingSafeEqual(a, b)
-}
-
-/** 从 cookie 头解析指定名字的值（手写最小解析，零依赖）。 */
-export function readCookie(headers: Record<string, unknown>, name: string): string | undefined {
-  const raw = headers.cookie
-  if (typeof raw !== 'string') return undefined
-  for (const part of raw.split(';')) {
-    const eq = part.indexOf('=')
-    if (eq === -1) continue
-    if (part.slice(0, eq).trim() === name) {
-      const value = part.slice(eq + 1).trim()
-      return value === '' ? undefined : value
-    }
-  }
-  return undefined
-}
-
 /** 取 XFF 最左条目（serve 单跳覆盖语义下即真实客户端 IP）。 */
 function forwardedIp(headers: Record<string, unknown>): string | undefined {
   const raw = headers['x-forwarded-for']
@@ -74,7 +52,7 @@ function forwardedIp(headers: Record<string, unknown>): string | undefined {
   return first === '' ? undefined : first
 }
 
-/** 浏览器导航请求判定：GET + accept 含 text/html（需要返回登录页而非 403）。 */
+/** 浏览器导航请求判定：GET + accept 含 text/html（需要返回 token 输入页而非 403）。 */
 export function isNavigationRequest(req: GateRequest): boolean {
   if (req.method !== 'GET' && req.method !== 'HEAD') return false
   const accept = req.headers.accept
@@ -97,41 +75,55 @@ export function compileAllowlist(entries: readonly string[]): CompiledAllowlist
 }
 
 /**
- * 围栏判定（纯函数，除 token 哈希外无任何副作用与 IO）。
+ * 围栏判定（纯函数，无任何副作用与 IO）。
  * 逻辑次序：豁免路径由调用方前置处理；enabled=false 直通；确定有效来源
  * （受信 XFF 优先，否则 remoteAddress）；来源为 loopback 直连 → 放行；
- * 否则按白名单/token 判定；无来源 → fail-closed。
+ * 白名单非空时作附加 IP 围栏，不命中即拒；官方 cookie 有效 → 放行；
+ * 否则导航 → token 输入页，非导航 → 403；无来源 → fail-closed。
  *
  * loopback 语义：XFF 被信任时，存在 XFF 即代表请求经代理（serve→proxy→dsh
  * 全链 loopback，真实客户端只在 XFF 里）——remoteAddress 是 loopback 也不
  * 放行，必须按 XFF 判定；XFF 不被信任时，来源就是 remoteAddress，
  * loopback 即本机直连 → 放行（防锁死兜底优先）。
+ *
+ * @param officialAuthed - 官方 browser-auth cookie 校验结果（调用方委托
+ *   connection.requestRejection() 得出；含官方 Host 信任围栏，403 情形
+ *   视同未认证）。
  */
-export function decideGate(req: GateRequest, policy: GatePolicy): GateDecision {
+export function decideGate(
+  req: GateRequest,
+  policy: GatePolicy,
+  officialAuthed: boolean,
+): GateDecision {
   if (!policy.enabled) return { verdict: 'pass', reason: 'local' }
 
   const forwarded = forwardedIp(req.headers)
   const trustedForwarded = policy.trustForwardedFor ? forwarded : undefined
   const clientIpText = trustedForwarded ?? req.remoteAddress
   if (clientIpText === undefined) {
-    return { verdict: 'block', reason: undefined }
+    return { verdict: 'block' }
   }
   if (trustedForwarded === undefined && isLoopbackAddress(req.remoteAddress)) {
     return { verdict: 'pass', reason: 'local' }
   }
 
   const allowlist = compileAllowlist(policy.allowedIps)
-  const clientIp = parseIp(clientIpText)
-  const allowedByIp = clientIp !== null && allowlist.match(clientIp)
-  const cookieToken = readCookie(req.headers, GATE_COOKIE)
-  const allowedByToken = cookieToken !== undefined && tokenMatches(cookieToken, policy.token)
+  const invalidEntries = allowlist.invalid.length > 0 ? allowlist.invalid : undefined
+
+  // 附加 IP 围栏：白名单非空时，来源不命中即拒（含持有效官方 cookie 者）。
+  if (policy.allowedIps.length > 0) {
+    const clientIp = parseIp(clientIpText)
+    if (clientIp === null || !allowlist.match(clientIp)) {
+      return { verdict: 'block', clientIp: clientIpText, invalidEntries }
+    }
+  }
 
-  const decision: GateDecision = {
-    verdict: allowedByIp || allowedByToken ? 'pass' : isNavigationRequest(req) ? 'login' : 'block',
+  if (officialAuthed) {
+    return { verdict: 'pass', reason: 'cookie', clientIp: clientIpText, invalidEntries }
+  }
+  return {
+    verdict: isNavigationRequest(req) ? 'token-page' : 'block',
     clientIp: clientIpText,
+    invalidEntries,
   }
-  if (allowedByToken) decision.reason = 'token'
-  else if (allowedByIp) decision.reason = 'allowed-ip'
-  if (allowlist.invalid.length > 0) decision.invalidEntries = allowlist.invalid
-  return decision
 }