@danceiny/gotry 0.0.1-rc.9 → 0.2.0-rc.27

package/ts/src/session-link/session-link.ts

@@ -0,0 +1,275 @@
+/**
+ * Session link token 签发/校验(issue #580,Phase E;研究决策见
+ * docs/research/karpo-deck-web-research.md §3 Phase E——one-tap 深链回本地
+ * session,不碰写路径,WriteGate 保持 sealed;消费端注册是 M4 激活)。
+ *
+ * HMAC-SHA256 over base64url(payload-json),签名为 base64url。
+ * Token 形如 `${body}.${sig}`(body = base64url(JSON.stringify(payload)))。
+ *
+ * 与 share-token(Phase C)的差异(刻意,非偶然):
+ *   - **schema 闭集到未知键拒绝**:verify 对 payload 里出现 schema 之外的键
+ *     直接 link_invalid——session link 是「de-identified by construction」面,
+ *     链接只携带引用(link_id/session_ref/wish_id)不携带事实/记忆,闭集
+ *     schema 让这句承诺变成可测试字面真(share token 允许附加键,因为 share
+ *     manifest 本身就需要开放扩展;两者威胁模型不同,不共享校验器);
+ *   - **action 词位闭集 = WriteGate 链接层结构性封死**:`plan_it` | `open`,
+ *     词位里不存在 book/pay/confirm——任何写动词连构造都构造不出来
+ *     (sign 层抛错,不只是 verify 层拒绝);
+ *   - **plan_it ⇔ wish_id 成对**:`plan_it` 必须带非空 wish_id(防「规划
+ *     空 wish」退化),`open` 必须不带(防通用打开链接夹带定向意图);
+ *   - **session_ref 路径护栏**:不透明引用,拒绝含 `/` `\` `..` NUL——
+ *     「不写共享状态」的链接层版:链接永远无法命名 state 路径;
+ *   - 失败闭集只有 2 类(`link_invalid` | `link_expired`)——session link
+ *     无 channel/adapter/consent 维度,不需要 share 的 8 类;
+ *   - token 不进 URL:scheme/宿主是消费端渲染期选择(`formatSessionLink`),
+ *     链接产物跨消费端可移植,签名载荷不含宿主细节。
+ *
+ * 硬化清单与 share-token 同源:恰一个点、timingSafeEqual(先长度)、
+ * ttl 非负整数上限 2^31-1(防 expiresMs 溢出 Infinity 永不过期)、
+ * 时间注入(测试不依赖 wall clock)、secret 缺省且 NODE_ENV=production
+ * 时 fail-closed(绝不静默用仓库里公开的 dev 常量签生产链接)——刻意抛错
+ * 保留在签发面(resolve/sign);verify 面把同样的配置错误收敛为 link_invalid,
+ * 不让异常越出「永不抛错」的校验边界。注入时钟本身失效(getTime 非有限值
+ * 或回调抛错)→ fail-closed link_invalid:NaN 与 expiresMs 比较恒 false,
+ * 曾把过期链接静默判成有效——无效时间上不产生任何接受。verify 期 secret
+ * 为非字符串运行期键(数字/对象/Symbol 等 JS 畸形输入)同样收敛 link_invalid,
+ * HMAC 计算本身也在守卫内——任何调用方/配置输入都无法越出「永不抛错」边界。
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto'
+
+/** 行动闭集:`plan_it`(回 session 继续规划某条 wish)| `open`(通用打开)。
+ *  **词位即安全边界**——新增行动先 review;book/pay/confirm 等写动词
+ *  永不入集(WriteGate sealed 在链接层的结构性表达)。 */
+export const SESSION_LINK_ACTIONS = ['plan_it', 'open'] as const
+export type SessionLinkAction = (typeof SESSION_LINK_ACTIONS)[number]
+
+/** 失败闭集(2 类;session link 无 channel/adapter/consent 维度) */
+export type SessionLinkFailure = 'link_invalid' | 'link_expired'
+
+export type SessionLinkVerifyResult =
+  | { ok: true; payload: SessionLinkPayload }
+  | { ok: false; reason: SessionLinkFailure }
+
+/** payload 闭集 schema(**恰好这 6 个键**;verify 对未知键拒绝——
+ *  de-identified by construction 的可测试形式:链接只携带引用,不携带事实) */
+export interface SessionLinkPayload {
+  /** 调用方给的幂等 id(非空字符串) */
+  link_id: string
+  /** 不透明 session 引用(非路径;护栏见 isSafeSessionRef) */
+  session_ref: string
+  /** 行动(闭集;写动词不在词位) */
+  action: SessionLinkAction
+  /** plan_it 时必填非空;open 时必须缺省(成对校验) */
+  wish_id?: string
+  /** 签发时刻(ISO;Date.parse 必须有限) */
+  created_at: string
+  /** 有效秒数:非负整数,上限 SESSION_LINK_TTL_MAX_SECONDS */
+  ttl_seconds: number
+}
+
+/** 显式 dev 默认 secret——生产环境必须由 `SESSION_LINK_HMAC_SECRET` env 覆盖 */
+export const DEFAULT_DEV_SESSION_LINK_SECRET = 'gotry-session-link-dev-secret-DO-NOT-USE-IN-PROD'
+
+/** ttl 上界(秒):2^31-1,防 created_at + ttl*1000 溢出 Number 上限 */
+export const SESSION_LINK_TTL_MAX_SECONDS = 2_147_483_647
+
+/** payload schema 的键闭集(verify 用:未知键 → link_invalid) */
+const PAYLOAD_KEYS = ['link_id', 'session_ref', 'action', 'wish_id', 'created_at', 'ttl_seconds'] as const
+
+/** 获取运行期 secret:env 优先;production 缺 env 时 fail-closed */
+export function resolveSessionLinkSecret(env: NodeJS.ProcessEnv = process.env): string {
+  const s = env.SESSION_LINK_HMAC_SECRET
+  if (typeof s === 'string' && s.length > 0) return s
+  if (env.NODE_ENV === 'production') {
+    throw new Error('SESSION_LINK_HMAC_SECRET 未设置且 NODE_ENV=production:拒绝回落公开的 dev 默认 secret(fail-closed;任何读到仓库的人都能伪造 session link)')
+  }
+  return DEFAULT_DEV_SESSION_LINK_SECRET
+}
+
+/** session_ref 路径护栏:不透明引用——含路径分隔/上跳/NUL 即拒(链接永远无法命名 state 路径) */
+function isSafeSessionRef(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0 && value.length <= 128
+    && !value.includes('/') && !value.includes('\\') && !value.includes('..')
+    && !value.includes('\0')
+}
+
+/** 签发:payload 校验(闭集 action / plan_it⇔wish_id 成对 / session_ref 护栏 / ttl 上界)
+ *  不过期检查由 verify 做(签名时刻的时钟是消费端的)。非法 payload 抛错——
+ *  构造层把坏链接挡在签名之前,不是等到校验才发现。 */
+export function signSessionLink(
+  payload: SessionLinkPayload,
+  secret: string = resolveSessionLinkSecret(),
+): string {
+  if (typeof payload !== 'object' || payload === null) {
+    throw new Error(`signSessionLink:payload 必须是对象(实测 ${String(payload)})`)
+  }
+  if (typeof payload.link_id !== 'string' || payload.link_id.length === 0) {
+    throw new Error('signSessionLink:link_id 必须是非空字符串')
+  }
+  if (!isSafeSessionRef(payload.session_ref)) {
+    throw new Error(`signSessionLink:session_ref 必须是不含路径分隔符的不透明引用(实测 ${String(payload.session_ref)})`)
+  }
+  if (!SESSION_LINK_ACTIONS.includes(payload.action)) {
+    throw new Error(`signSessionLink:action 不在闭集(实测 ${String(payload.action)};允许:${SESSION_LINK_ACTIONS.join(' / ')})。写动词(book/pay/confirm)永不入集——WriteGate 在链接层结构性封死`)
+  }
+  // plan_it ⇔ wish_id 成对(双向:plan_it 必须有目标;open 必须不夹带定向意图)
+  if (payload.action === 'plan_it' && (typeof payload.wish_id !== 'string' || payload.wish_id.length === 0)) {
+    throw new Error('signSessionLink:action=plan_it 必须携带非空 wish_id(否则「规划」无对象,是退化链接)')
+  }
+  if (payload.action === 'open' && payload.wish_id !== undefined) {
+    throw new Error('signSessionLink:action=open 必须不携带 wish_id(通用打开链接夹带定向意图 = 混淆行动语义)')
+  }
+  if (typeof payload.created_at !== 'string' || payload.created_at.length === 0 || !Number.isFinite(Date.parse(payload.created_at))) {
+    throw new Error('signSessionLink:created_at 必须是可解析的 ISO 时间字符串')
+  }
+  if (typeof payload.ttl_seconds !== 'number' || !Number.isInteger(payload.ttl_seconds)
+    || payload.ttl_seconds < 0 || payload.ttl_seconds > SESSION_LINK_TTL_MAX_SECONDS) {
+    throw new Error(`signSessionLink:ttl_seconds 必须为 0..${SESSION_LINK_TTL_MAX_SECONDS} 的整数(实测 ${String(payload.ttl_seconds)})`)
+  }
+  // 序列化前剥掉 undefined 键(wish_id 缺省时),保证 body 可复现
+  const clean: Record<string, unknown> = {}
+  const raw = payload as unknown as Record<string, unknown>
+  for (const k of PAYLOAD_KEYS) {
+    const v = raw[k]
+    if (v !== undefined) clean[k] = v
+  }
+  const body = Buffer.from(JSON.stringify(clean), 'utf-8').toString('base64url')
+  const sig = createHmac('sha256', secret).update(body).digest('base64url')
+  return `${body}.${sig}`
+}
+
+/** 校验:secret 解析(守卫体)→ 格式(恰一个点)→ HMAC 等值(timingSafeEqual)
+ *  → schema 闭集(未知键拒绝)→ 字段形态 → plan_it⇔wish_id 成对 → session_ref
+ *  护栏 → 过期(注入时钟失效 = link_invalid)。**永不抛错**:production 缺 env
+ *  secret 与失效时钟都是操作面错误,收敛进 link_invalid(消费端拿到 link_invalid
+ *  只能 fail-closed 不打开任何 session),刻意的配置/签发异常只保留在 resolve/sign 侧。 */
+export function verifySessionLink(
+  token: string,
+  secret?: string,
+  now: () => Date = () => new Date(),
+): SessionLinkVerifyResult {
+  // 运行期 secret 解析放进守卫体:production 缺 env 的配置错在验证面 fail-closed
+  // 为 link_invalid,不抛错(若静默回落公开 dev 常量,伪造链接将被放行);
+  // 非字符串运行期键(数字/对象/Symbol 等 JS 畸形调用方输入)同样收敛
+  // link_invalid——createHmac 对它们会抛 TypeError,绝不让异常越出本函数
+  let hmacSecret: string
+  try {
+    const resolved = secret === undefined ? resolveSessionLinkSecret() : secret
+    if (typeof resolved !== 'string') return { ok: false, reason: 'link_invalid' }
+    hmacSecret = resolved
+  } catch {
+    return { ok: false, reason: 'link_invalid' }
+  }
+  if (typeof token !== 'string' || token.length === 0) return { ok: false, reason: 'link_invalid' }
+  const dot = token.indexOf('.')
+  // 恰一个点:多点(base64url 解码器会静默吞非法字符)与无点都拒绝
+  if (dot <= 0 || dot === token.length - 1) return { ok: false, reason: 'link_invalid' }
+  if (token.indexOf('.', dot + 1) !== -1) return { ok: false, reason: 'link_invalid' }
+  const body = token.slice(0, dot)
+  const sig = token.slice(dot + 1)
+
+  // HMAC 等值比较(先长度,再 timingSafeEqual;Buffer-vs-Buffer);加密计算
+  // 本身也在守卫内——任何运行期键异常收敛 link_invalid,绝不外泄异常
+  let expected: Buffer
+  try {
+    expected = createHmac('sha256', hmacSecret).update(body).digest()
+  } catch {
+    return { ok: false, reason: 'link_invalid' }
+  }
+  let actual: Buffer
+  try {
+    actual = Buffer.from(sig, 'base64url')
+  } catch {
+    return { ok: false, reason: 'link_invalid' }
+  }
+  if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
+    return { ok: false, reason: 'link_invalid' }
+  }
+
+  // 解析 payload
+  let payload: Record<string, unknown>
+  try {
+    const json = Buffer.from(body, 'base64url').toString('utf-8')
+    payload = JSON.parse(json)
+  } catch {
+    return { ok: false, reason: 'link_invalid' }
+  }
+  if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+    return { ok: false, reason: 'link_invalid' }
+  }
+  // schema 闭集:未知键拒绝(de-identified by construction 的可测试形式)
+  for (const key of Object.keys(payload)) {
+    if (!(PAYLOAD_KEYS as readonly string[]).includes(key)) return { ok: false, reason: 'link_invalid' }
+  }
+  // 字段形态
+  if (typeof payload.link_id !== 'string' || payload.link_id.length === 0
+    || !isSafeSessionRef(payload.session_ref)
+    || typeof payload.action !== 'string' || !SESSION_LINK_ACTIONS.includes(payload.action as SessionLinkAction)
+    || typeof payload.created_at !== 'string' || payload.created_at.length === 0) {
+    return { ok: false, reason: 'link_invalid' }
+  }
+  // plan_it ⇔ wish_id 成对(与 sign 同规则,双向)
+  if (payload.action === 'plan_it' && (typeof payload.wish_id !== 'string' || payload.wish_id.length === 0)) {
+    return { ok: false, reason: 'link_invalid' }
+  }
+  if (payload.action === 'open' && payload.wish_id !== undefined) {
+    return { ok: false, reason: 'link_invalid' }
+  }
+  // ttl:非负整数且不溢出(防 created_at + ttl*1000 = Infinity 永不过期)
+  const ttl = payload.ttl_seconds
+  if (typeof ttl !== 'number' || !Number.isInteger(ttl) || ttl < 0 || ttl > SESSION_LINK_TTL_MAX_SECONDS) {
+    return { ok: false, reason: 'link_invalid' }
+  }
+  const createdMs = Date.parse(payload.created_at)
+  if (!Number.isFinite(createdMs)) return { ok: false, reason: 'link_invalid' }
+  const expiresMs = createdMs + ttl * 1000
+  if (!Number.isFinite(expiresMs)) return { ok: false, reason: 'link_invalid' }
+  // 注入时钟失效(抛错/非有限值)fail-closed 为 link_invalid——
+  // NaN 与 expiresMs 比较恒 false,失效时钟不得让任何链接通过
+  let nowMs: number
+  try {
+    nowMs = now().getTime()
+  } catch {
+    return { ok: false, reason: 'link_invalid' }
+  }
+  if (!Number.isFinite(nowMs)) return { ok: false, reason: 'link_invalid' }
+  if (nowMs > expiresMs) return { ok: false, reason: 'link_expired' }
+
+  return { ok: true, payload: payload as unknown as SessionLinkPayload }
+}
+
+/** 默认深链 base(scheme handler 注册是 M4 激活;消费端可传自己的 base) */
+export const DEFAULT_SESSION_LINK_BASE = 'gotry://session'
+
+/** 渲染期拼 URL:`${base}/${token}`——token 不进 URL 的签名,宿主是消费端选择 */
+export function formatSessionLink(token: string, base: string = DEFAULT_SESSION_LINK_BASE): string {
+  if (typeof token !== 'string' || token.length === 0) {
+    throw new Error('formatSessionLink:token 必须是非空字符串')
+  }
+  if (typeof base !== 'string' || base.length === 0 || base.endsWith('/')) {
+    throw new Error(`formatSessionLink:base 必须是非空字符串且不以 '/' 结尾(实测 ${String(base)})`)
+  }
+  if (base.includes('?') || base.includes('#')) {
+    throw new Error('formatSessionLink:base 不得含 query/hash(产出即 parseSessionLink 拒绝的形态,锋利边角)')
+  }
+  return `${base}/${token}`
+}
+
+/** 从 URL 严格反解 token:路径最后一段,且段本身须呈 `body.sig` 形态(恰
+ *  一个非空 body、非空 sig;段内多点由 verify 终裁——本函数只保证不把一个
+ *  裸 base(`gotry://session`)的最后一段误当 token)。**拒绝 query/hash**——
+ *  拼接歧义(如 `?x=../../etc`)一律 fail-closed;形态不符返回 null(消费端
+ *  不打开)。 */
+export function parseSessionLink(url: string): string | null {
+  if (typeof url !== 'string' || url.length === 0) return null
+  const q = url.indexOf('?')
+  const h = url.indexOf('#')
+  if (q !== -1 || h !== -1) return null
+  const segments = url.split('/').filter(s => s.length > 0)
+  const token = segments[segments.length - 1]
+  if (segments.length < 2 || token === undefined || token.length === 0) return null
+  const dot = token.indexOf('.')
+  if (dot <= 0 || dot === token.length - 1) return null
+  return token
+}

package/ts/src/share/adapters.ts

@@ -0,0 +1,93 @@
+/**
+ * Share outbound adapter 契约层(issue #573,Phase C 切片;研究决策见
+ * docs/research/karpo-deck-web-research.md 决策 §3 Phase C;自检 review 修复见 PR #574 评论)。
+ *
+ * 设计契约:**所有 outbound 外发必经同意卡 + 签名 token**,且必经这个接口。
+ * 4 个内置适配器(iMessage / SMS / Slack / webhook)只实现契约形状、**不接
+ * 真实 SDK、不发网络**——统一返回 `{ delivered: false, reason: 'not_activated' }`,
+ * 由 share-deck.ts 主流程在 M4 阶段才决定哪些 adapter 真正激活。
+ *
+ * 三条硬纪律(继承自单页入口 + deck 入口):
+ *   1. payload 是**显式结构**(token 绑定 target/body)——调用方不传 raw HTML,
+ *      只传路径(产物可被 list/read 单独审计);
+ *   2. token 校验(含 target 绑定)由 share-deck 在选 adapter 之前完成——未通过
+ *      校验的 adapter.send 永远不会被调用;
+ *   3. adapter.send 返回 `delivered:false` 或抛错都算合法完成(抛错被主流程
+ *      收敛为 `adapter_error`);调用方据此决定 UI 反馈与重试策略。
+ */
+
+export type ShareChannel = 'imessage' | 'sms' | 'slack' | 'webhook'
+
+export interface SharePayload {
+  /** 签名后的 share token(由 share-token.ts 签发,payload 绑定 target) */
+  token: string
+  /** 通道与地址(channel 与 adapter 表一对一;address 含义由各 adapter 解释) */
+  target: { channel: ShareChannel; address: string }
+  /** 产物引用——adapter 据此拿到 deck / manifest / qr 的实际路径 */
+  body: { html_path?: string; manifest_path?: string; qr_path?: string; note?: string }
+}
+
+/** 失败原因闭集——任何 adapter / share-deck 返回的拒绝都必须落进这个集合(便于 UI 与
+ * 审计分桶);扩展前先 review(扩展 = 增加通道语义;不是字符串自由枚举) */
+export type ShareFailureReason =
+  | 'not_activated'         // adapter 存在但未激活(M4 才接)
+  | 'unknown_channel'        // target.channel 不在 ADAPTERS 表内(含原型键/非自有键)
+  | 'consent_required'       // consent state = 'ask' 但未发卡
+  | 'consent_revoked'        // consent 曾被拒绝/撤回/卡 id 不匹配
+  | 'share_consent_off'      // 总开关关
+  | 'token_invalid'          // token 签名/tampered/target 绑定不匹配/格式/字段
+  | 'token_expired'          // token 过了 ttl
+  | 'adapter_error'          // adapter.send 抛错(主流程收敛,绝不外泄异常)
+
+export type ShareResult =
+  | { delivered: true; adapter_id: ShareChannel; sent_at: string }
+  | { delivered: false; reason: ShareFailureReason }
+
+export interface ShareAdapter {
+  readonly id: ShareChannel
+  send(payload: SharePayload): Promise<ShareResult>
+}
+
+// ---- 4 个 stub 适配器(issue #573 Phase C):契约形状 + no-op;不接 SDK、不发网络 ----
+
+export const iMessageAdapter: ShareAdapter = {
+  id: 'imessage',
+  send: async () => ({ delivered: false, reason: 'not_activated' as const }),
+}
+
+export const smsAdapter: ShareAdapter = {
+  id: 'sms',
+  send: async () => ({ delivered: false, reason: 'not_activated' as const }),
+}
+
+export const slackAdapter: ShareAdapter = {
+  id: 'slack',
+  send: async () => ({ delivered: false, reason: 'not_activated' as const }),
+}
+
+export const webhookAdapter: ShareAdapter = {
+  id: 'webhook',
+  send: async () => ({ delivered: false, reason: 'not_activated' as const }),
+}
+
+/** 通道 → adapter 表(主流程 share-deck 用此表分发)。
+ *  运行时 Object.freeze(设计文档「冻结 record」的字面兑现——编译期 Readonly 只挡 TS)。
+ *  扩通道须同时扩 ShareChannel 联合与这个表;SHARE_CHANNELS 由表键派生(单一事实源)。 */
+export const ADAPTERS: Readonly<Record<ShareChannel, ShareAdapter>> = Object.freeze({
+  imessage: iMessageAdapter,
+  sms: smsAdapter,
+  slack: slackAdapter,
+  webhook: webhookAdapter,
+})
+
+/** 通道闭集:从 ADAPTERS 键派生(自检 review:手列第二份清单必然漂移) */
+export const SHARE_CHANNELS: readonly ShareChannel[] = Object.freeze(
+  Object.keys(ADAPTERS) as ShareChannel[],
+)
+
+/** 自有键判定:分发守卫用它挡原型键('__proto__'/'constructor'/'toString' 经
+ *  Record 索引会命中 Object.prototype 继承成员,直接 lookup 会拿到真值绕过
+ *  unknown_channel 检查然后 adapter.send undefined 崩溃)。 */
+export function hasAdapterChannel(table: Readonly<Record<string, unknown>>, channel: unknown): boolean {
+  return typeof channel === 'string' && Object.prototype.hasOwnProperty.call(table, channel)
+}

package/ts/src/share/share-consent.ts

@@ -0,0 +1,105 @@
+/**
+ * Share consent state machine(issue #573,Phase C 切片;自检 review 修复见 PR #574)。
+ *
+ * 模式:`mode: 'ask' | 'allow' | 'off'` 三态总开关 + 每 share_id 一次性同意卡。
+ * 借鉴 `session-consent.ts` 的「一次一卡 + 拒绝即撤回 + 总开关 off」范式,
+ * 但与 session 授权**完全独立**(不合并——session 是「我能不能读你的浏览器」,
+ * share 是「我能不能替你外发到第三方」,两类授权的语义与撤销粒度都不同)。
+ *
+ * 三条硬纪律:
+ *   1. **默认 deny**:off 一律拒;ask/allow 下该 share_id 无存活卡 → consent_required;
+ *   2. **拒绝即撤回**:card_id 进 revoked 后,该卡即死;调用方出示的 card_id 必须
+ *      本身存活(在哪张卡上匹配就以哪张为准——不是「第一张活卡」);
+ *   3. **状态纯函数**:grant/revoke/setMode 返回新 state,不原地改;grant 幂等
+ *      (同 share 已有存活卡则复用该卡,不再追加——防多卡漂移破坏撤销全量性)。
+ */
+
+import { randomUUID } from 'node:crypto'
+
+export type ShareConsentMode = 'ask' | 'allow' | 'off'
+
+export interface ShareConsentCard {
+  card_id: string
+  share_id: string
+  granted_at: string  // ISO
+}
+
+export interface ShareConsentState {
+  mode: ShareConsentMode
+  /** append-only,granted 过的卡 */
+  granted: ShareConsentCard[]
+  /** 已撤销的 card_id(可能与 granted 重叠——grant 后被 revoke 即同时存在) */
+  revoked: string[]
+}
+
+export type ShareConsentCheckResult =
+  | { ok: true }
+  | { ok: false; reason: 'share_consent_off' | 'consent_required' | 'consent_revoked' }
+
+export function defaultShareConsentState(): ShareConsentState {
+  return { mode: 'ask', granted: [], revoked: [] }
+}
+
+/** 校验:off 一律拒;该 share_id 无任何卡 → consent_required(从未发卡);
+ *  有卡但全部被撤 → consent_revoked(曾发卡已撤);调用方出示 card_id 时,
+ *  该卡必须属于此 share 且自身未撤销(按卡匹配,不按第一张活卡——防多卡下
+ *  合法卡被误判 revoked、被撤卡被其它活卡顶替)。 */
+export function checkShareConsent(state: ShareConsentState, share_id: string, card_id?: string): ShareConsentCheckResult {
+  if (state.mode === 'off') return { ok: false, reason: 'share_consent_off' }
+  // 边界守卫:畸形持久化 state(字段非数组)fail closed 视为空——绝不抛错
+  const grantedList = Array.isArray(state?.granted) ? state.granted : []
+  const revokedList = Array.isArray(state?.revoked) ? state.revoked : []
+  const allForShare = grantedList.filter(c => c.share_id === share_id)
+  if (allForShare.length === 0) {
+    return { ok: false, reason: 'consent_required' }
+  }
+  if (card_id !== undefined) {
+    const given = allForShare.find(c => c.card_id === card_id)
+    if (!given || revokedList.includes(card_id)) {
+      return { ok: false, reason: 'consent_revoked' }
+    }
+    return { ok: true }
+  }
+  const anyLive = allForShare.some(c => !revokedList.includes(c.card_id))
+  if (!anyLive) {
+    return { ok: false, reason: 'consent_revoked' }
+  }
+  return { ok: true }
+}
+
+/** 发卡:幂等——同 share_id 已有存活卡则复用(不再追加,防多卡漂移);
+ *  否则追加新卡。返回 state 与卡本身(调用方持有 card_id 用于后续校验)。 */
+export function grantShareConsent(
+  state: ShareConsentState,
+  share_id: string,
+  now: () => Date = () => new Date(),
+  randomCardId: () => string = defaultCardId,
+): { state: ShareConsentState; card: ShareConsentCard } {
+  const existing = state.granted.find(c => c.share_id === share_id && !state.revoked.includes(c.card_id))
+  if (existing) return { state, card: existing }
+  const card: ShareConsentCard = {
+    card_id: randomCardId(),
+    share_id,
+    granted_at: now().toISOString(),
+  }
+  return {
+    state: { mode: state.mode, granted: [...state.granted, card], revoked: state.revoked },
+    card,
+  }
+}
+
+/** 撤回:把 card_id 加入 revoked(幂等——重复 revoke 不变) */
+export function revokeShareConsent(state: ShareConsentState, card_id: string): ShareConsentState {
+  if (state.revoked.includes(card_id)) return state
+  return { mode: state.mode, granted: state.granted, revoked: [...state.revoked, card_id] }
+}
+
+/** 切总开关:返回新 state(不原地改) */
+export function setShareConsentMode(state: ShareConsentState, mode: ShareConsentMode): ShareConsentState {
+  return { mode, granted: state.granted, revoked: state.revoked }
+}
+
+/** 默认 card_id 生成器(测试可注入);Node 原生 crypto.randomUUID */
+export function defaultCardId(): string {
+  return randomUUID()
+}

package/ts/src/share/share-deck.ts

@@ -0,0 +1,85 @@
+/**
+ * Share deck 主入口(issue #573,Phase C 切片;自检 review 修复见 PR #574):
+ * 对外发起一次 share 动作的契约编排。
+ *
+ * 流程(每步都 fail closed,无副作用):
+ *   1. verifyShareToken(token, secret) → 失败返回 reason
+ *   2. tokenTargetMatches(payload.target) → 目的地与签名不符返回 token_invalid
+ *   3. checkShareConsent(state, share_id, deps.card_id?) → 失败返回 reason
+ *   4. 分发守卫(hasAdapterChannel:自有键判定,挡原型键)→ unknown_channel
+ *   5. adapter.send(payload) **在 try/catch 内** → 抛错收敛为 adapter_error
+ *
+ * 设计要点:
+ *   - 纯异步编排,无 IO / 无网络 / 不写 state(consent state 由调用方持有);
+ *   - secret + state + now + card_id + adapters 全部依赖注入,测试可全离线确定性;
+ *   - **永不抛错**:任何 adapter 异常都被收敛为 ShareResult(契约出口唯一);
+ *   - **不挂 dsh 工具面**(留给 M4);Phase C 只交付契约 + stub + 流程。
+ */
+
+import {
+  ADAPTERS,
+  hasAdapterChannel,
+  type ShareAdapter,
+  type ShareChannel,
+  type SharePayload,
+  type ShareResult,
+} from './adapters.ts'
+import { tokenTargetMatches, verifyShareToken } from './share-token.ts'
+import { checkShareConsent, type ShareConsentState } from './share-consent.ts'
+
+export interface ShareDeckDeps {
+  /** HMAC secret(由调用方经 share-token.resolveShareSecret 解析) */
+  secret: string
+  /** consent state(由调用方持有 + 持久化;本模块不读不写) */
+  state: ShareConsentState
+  /** 时间注入(测试用) */
+  now?: () => Date
+  /** 可选:调用方持有的同意卡 id(二次校验——出示的卡必须属于该 share 且未撤销) */
+  card_id?: string
+  /** 可选:适配器表注入(测试/M4 用;缺省走冻结的 ADAPTERS) */
+  adapters?: Readonly<Record<ShareChannel, ShareAdapter>>
+}
+
+/** 公开的 payload 形状(不含 token —— token 单独传) */
+export type ShareDeckRequest = Omit<SharePayload, 'token'>
+
+export async function shareDeck(token: string, payload: ShareDeckRequest, deps: ShareDeckDeps): Promise<ShareResult> {
+  // 1. token 校验(签名/格式/ttl/过期)
+  const tokenCheck = verifyShareToken(token, deps.secret, deps.now)
+  if (!tokenCheck.ok) {
+    return { delivered: false, reason: tokenCheck.reason }
+  }
+
+  // 2. 目的地绑定:token 签发时的 target 必须与本次请求完全一致(防换收件人重放)
+  if (!tokenTargetMatches(tokenCheck.payload, payload.target)) {
+    return { delivered: false, reason: 'token_invalid' }
+  }
+  const shareId = tokenCheck.payload.share_id
+
+  // 3. consent 校验(share_id + 调用方出示的可选 card_id 二次校验)
+  const consent = checkShareConsent(deps.state, shareId, deps.card_id)
+  if (!consent.ok) {
+    return { delivered: false, reason: consent.reason }
+  }
+
+  // 4. 分发守卫:自有键判定(原型键 '__proto__'/'constructor' 等经 Record 索引会
+  //    命中继承成员,直接 lookup 拿到真值后 adapter.send undefined 会崩——先挡)
+  const table = deps.adapters ?? ADAPTERS
+  const channel = payload.target.channel
+  if (!hasAdapterChannel(table, channel)) {
+    return { delivered: false, reason: 'unknown_channel' }
+  }
+  const adapter = (table as Readonly<Record<string, ShareAdapter>>)[channel as string]
+
+  // 5. adapter.send 在 try/catch 内:任何异常收敛为 adapter_error,绝不外泄
+  const fullPayload: SharePayload = { token, target: payload.target, body: payload.body }
+  const sentAt = (deps.now ?? (() => new Date()))().toISOString()
+  let result: ShareResult
+  try {
+    result = await adapter.send(fullPayload)
+  } catch {
+    return { delivered: false, reason: 'adapter_error' }
+  }
+  if (result.delivered) return { ...result, sent_at: result.sent_at ?? sentAt }
+  return { delivered: false, reason: result.reason }
+}