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

package/ts/src/share/share-token.ts

@@ -0,0 +1,166 @@
+/**
+ * Share token 签发/校验(issue #573,Phase C 切片;自检 review 修复见 PR #574)。
+ *
+ * HMAC-SHA256 over base64url(payload-json),签名为 base64url。
+ * Token 形如 `${body}.${sig}`(body = base64url(JSON.stringify(payload)))。
+ *
+ * 设计要点:
+ *   - 纯函数 + 时间注入(测试不依赖 wall clock);
+ *   - payload 绑定 share_id / created_at(ISO)/ ttl_seconds / **target(channel+address)**——
+ *     目的地进签名,防止「合法 token 换个收件人重放」(自检 review 发现的绑定缺口);
+ *   - 格式契约**恰一个点**:`indexOf === lastIndexOf('.')`,多点/尾随垃圾拒绝;
+ *   - ttl 契约:非负整数、上限 2^31-1 秒(防 expiresMs 溢出 Infinity 永不过期);
+ *   - 校验使用 timingSafeEqual(先长度比对)防时序侧信道;
+ *   - secret 默认从 `SHARE_HMAC_SECRET` env 取;缺省且 NODE_ENV=production 时
+ *     **fail-closed**(绝不静默用仓库里公开的 dev 常量签生产 token)——刻意抛错
+ *     保留在签发面(resolve/sign);verify 面把同样的配置错误收敛为 `token_invalid`,
+ *     非字符串运行期键(数字/对象/Symbol 等 JS 畸形输入)同样收敛,HMAC 计算
+ *     本身也在守卫内——任何调用方/配置输入都无法越出「永不抛错」的校验边界;
+ *   - 注入时钟本身失效(getTime 非有限值或回调抛错)→ fail-closed `token_invalid`:
+ *     `NaN > expiresMs` 恒 false,曾把过期 token 静默判成有效——无效时间上
+ *     不产生任何接受;
+ *   - 篡改/过期/格式错三类失败都走 ShareFailureReason 同一闭集。
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto'
+
+import type { ShareChannel, ShareFailureReason } from './adapters.ts'
+
+export interface ShareTokenTarget {
+  channel: ShareChannel
+  address: string
+}
+
+export interface ShareTokenPayload {
+  share_id: string
+  created_at: string
+  ttl_seconds: number
+  /** 目的地绑定:token 只对签发时的 target 有效,换收件人即 token_invalid */
+  target: ShareTokenTarget
+}
+
+export type ShareTokenVerifyResult =
+  | { ok: true; payload: ShareTokenPayload }
+  | { ok: false; reason: ShareFailureReason }
+
+/** 显式 dev 默认 secret——生产环境必须由 `SHARE_HMAC_SECRET` env 覆盖 */
+export const DEFAULT_DEV_SHARE_SECRET = 'gotry-share-dev-secret-DO-NOT-USE-IN-PROD'
+
+/** ttl 上界(秒):2^31-1,防 created_at + ttl*1000 溢出 Number 上限 */
+export const SHARE_TOKEN_TTL_MAX_SECONDS = 2_147_483_647
+
+/** 获取运行期 secret:env 优先;production 缺 env 时 fail-closed(dev 常量签生产 token = 任何人可伪造) */
+export function resolveShareSecret(env: NodeJS.ProcessEnv = process.env): string {
+  const s = env.SHARE_HMAC_SECRET
+  if (typeof s === 'string' && s.length > 0) return s
+  if (env.NODE_ENV === 'production') {
+    throw new Error('SHARE_HMAC_SECRET 未设置且 NODE_ENV=production:拒绝回落公开的 dev 默认 secret(fail-closed;任何读到仓库的人都能伪造 token)')
+  }
+  return DEFAULT_DEV_SHARE_SECRET
+}
+
+/** 签名:payload → base64url(JSON) + '.' + base64url(HMAC-SHA256(body, secret)) */
+export function signShareToken(payload: ShareTokenPayload, secret: string = resolveShareSecret()): string {
+  const body = Buffer.from(JSON.stringify(payload), 'utf-8').toString('base64url')
+  const sig = createHmac('sha256', secret).update(body).digest('base64url')
+  return `${body}.${sig}`
+}
+
+function isTokenTarget(value: unknown): value is ShareTokenTarget {
+  if (typeof value !== 'object' || value === null) return false
+  const t = value as Record<string, unknown>
+  return typeof t.channel === 'string' && t.channel.length > 0
+    && typeof t.address === 'string'
+}
+
+/** 校验:secret 解析(守卫体)→ 格式(恰一个点)→ HMAC 等值(timingSafeEqual)
+ *  → payload 形态 → 过期(注入时钟失效 = token_invalid)。**永不抛错**:
+ *  production 缺 env secret 与失效时钟都是操作面错误,收敛进 token_invalid,
+ *  刻意的配置/签发异常只保留在 resolve/sign 侧。 */
+export function verifyShareToken(
+  token: string,
+  secret?: string,
+  now: () => Date = () => new Date(),
+): ShareTokenVerifyResult {
+  // 运行期 secret 解析放进守卫体:production 缺 env 的配置错在验证面 fail-closed
+  // 为 token_invalid,不抛错(若静默回落公开 dev 常量,伪造 token 将被放行);
+  // 非字符串运行期键(数字/对象/Symbol 等 JS 畸形调用方输入)同样收敛
+  // token_invalid——createHmac 对它们会抛 TypeError,绝不让异常越出本函数
+  let hmacSecret: string
+  try {
+    const resolved = secret === undefined ? resolveShareSecret() : secret
+    if (typeof resolved !== 'string') return { ok: false, reason: 'token_invalid' }
+    hmacSecret = resolved
+  } catch {
+    return { ok: false, reason: 'token_invalid' }
+  }
+  if (typeof token !== 'string' || token.length === 0) return { ok: false, reason: 'token_invalid' }
+  const dot = token.indexOf('.')
+  // 恰一个点:多点(base64url 解码器会静默吞非法字符)与无点都拒绝
+  if (dot <= 0 || dot === token.length - 1) return { ok: false, reason: 'token_invalid' }
+  if (token.indexOf('.', dot + 1) !== -1) return { ok: false, reason: 'token_invalid' }
+  const body = token.slice(0, dot)
+  const sig = token.slice(dot + 1)
+
+  // HMAC 等值比较(先长度,再 timingSafeEqual;Buffer-vs-Buffer);加密计算
+  // 本身也在守卫内——任何运行期键异常收敛 token_invalid,绝不外泄异常
+  let expected: Buffer
+  try {
+    expected = createHmac('sha256', hmacSecret).update(body).digest()
+  } catch {
+    return { ok: false, reason: 'token_invalid' }
+  }
+  let actual: Buffer
+  try {
+    actual = Buffer.from(sig, 'base64url')
+  } catch {
+    return { ok: false, reason: 'token_invalid' }
+  }
+  if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
+    return { ok: false, reason: 'token_invalid' }
+  }
+
+  // 解析 payload
+  let payload: ShareTokenPayload
+  try {
+    const json = Buffer.from(body, 'base64url').toString('utf-8')
+    payload = JSON.parse(json)
+  } catch {
+    return { ok: false, reason: 'token_invalid' }
+  }
+  if (typeof payload !== 'object' || payload === null
+    || typeof payload.share_id !== 'string' || payload.share_id.length === 0
+    || typeof payload.created_at !== 'string' || payload.created_at.length === 0
+    || !isTokenTarget(payload.target)) {
+    return { ok: false, reason: 'token_invalid' }
+  }
+  // ttl:非负整数且不溢出(防 created_at + ttl*1000 = Infinity 永不过期)
+  if (typeof payload.ttl_seconds !== 'number'
+    || !Number.isInteger(payload.ttl_seconds)
+    || payload.ttl_seconds < 0
+    || payload.ttl_seconds > SHARE_TOKEN_TTL_MAX_SECONDS) {
+    return { ok: false, reason: 'token_invalid' }
+  }
+
+  // 过期检查:注入时钟失效(抛错/非有限值)fail-closed 为 token_invalid——
+  // NaN 与 expiresMs 比较恒 false,失效时钟不得让任何 token 通过
+  const createdMs = Date.parse(payload.created_at)
+  if (!Number.isFinite(createdMs)) return { ok: false, reason: 'token_invalid' }
+  const expiresMs = createdMs + payload.ttl_seconds * 1000
+  if (!Number.isFinite(expiresMs)) return { ok: false, reason: 'token_invalid' }
+  let nowMs: number
+  try {
+    nowMs = now().getTime()
+  } catch {
+    return { ok: false, reason: 'token_invalid' }
+  }
+  if (!Number.isFinite(nowMs)) return { ok: false, reason: 'token_invalid' }
+  if (nowMs > expiresMs) return { ok: false, reason: 'token_expired' }
+
+  return { ok: true, payload }
+}
+
+/** target 绑定比对:token payload 的 target 必须与请求的 target 完全一致(通道+地址逐字段) */
+export function tokenTargetMatches(payload: ShareTokenPayload, target: { channel: unknown; address: unknown }): boolean {
+  return payload.target.channel === target.channel && payload.target.address === target.address
+}

package/ts/src/slot-spec.ts

@@ -0,0 +1,172 @@
+/**
+ * 槽位→日期解析层(D-10 切片 A):把 travel_slot_extraction.v1 的逐字时间表达
+ * 在代码层换算为绝对日期——「tool-owned dates」的执行面。
+ *
+ * ADR-12 复审结论(2026-08-27,D-10 赎回触发):设计成立,但解析范围必须**有界**——
+ * 只解析锚点卡词表内的表达(今天/明天/后天/大后天/本周X/下周X/下下周X/下个月初|中旬|下旬)
+ * 与绝对表达(ISO/点分/中文月日,parseAbsoluteDate)+ 槽位约定后缀「+N」;
+ * 词表外(近期/这阵子/next Monday/英文月名…)一律 unresolved 逐字保留,
+ * 不做开放式中文相对日期解析(ADR-12 被拒备选:维护黑洞)。
+ *
+ * 本层是纯函数:不碰求解器、不改入参;工具查询/spec 一致性闸的接线属后续切片。
+ */
+
+import { parseAbsoluteDate, ymd, type TimeAnchor } from './time-anchor.ts'
+import type { TravelSlotExtraction } from './travel-slots.ts'
+
+export type SlotDateKind = 'absolute' | 'card' | 'unresolved'
+
+export interface SlotDateResolution {
+  /** 用户原话(逐字) */
+  raw: string
+  /** 换算结果 YYYY-MM-DD;unresolved 时 null */
+  date: string | null
+  kind: SlotDateKind
+}
+
+const WEEKDAY_ZH: Record<string, number> = { 日: 0, 一: 1, 二: 2, 三: 3, 四: 4, 五: 5, 六: 6 }
+
+function addDaysYmd(today: string, n: number): string {
+  const [y, m, d] = today.split('-').map(Number)
+  return ymd(new Date(y, m - 1, d + n))
+}
+
+/** 「下周五+3」「8.20+2天」后缀:base + N 天(槽位规则 5/6 的拼接约定) */
+function splitPlusSuffix(expr: string): { base: string; plusDays: number } {
+  const m = expr.match(/^(.*?)\+(\d+)天?$/)
+  if (m && m[1]) return { base: m[1], plusDays: Number(m[2]) }
+  return { base: expr, plusDays: 0 }
+}
+
+/** 锚点卡近邻日词表(今天/明天/后天/大后天)→ 相对今天的偏移天数;词表外 null */
+function neighborDayOffset(expr: string): number | null {
+  if (expr === '今天') return 0
+  if (expr === '明天') return 1
+  if (expr === '后天') return 2
+  if (expr === '大后天') return 3
+  return null
+}
+
+/** 锚点卡词表周表达(本周X/下周X/下下周X)→ 相对今天的偏移天数;词表外 null。周一分界,与锚点卡一致 */
+function weekdayOffsetDays(expr: string, today: string): number | null {
+  const m = expr.match(/^(本|下|下下)周([日一二三四五六])$/)
+  if (!m || !m[2]) return null
+  const target = WEEKDAY_ZH[m[2]]
+  if (target === undefined) return null
+  const [y, mm, d] = today.split('-').map(Number)
+  const todayMonOffset = (new Date(y, mm - 1, d).getDay() + 6) % 7
+  const targetMonOffset = (target + 6) % 7
+  const weekShift = m[1] === '本' ? 0 : m[1] === '下' ? 7 : 14
+  return weekShift + targetMonOffset - todayMonOffset
+}
+
+/** 锚点卡月分段词表(下个月初/中旬/下旬)→ 该分段首日;词表外 null(保守取首日,宁可早不可晚) */
+function monthFragmentDate(expr: string, today: string): string | null {
+  if (!['下个月初', '下个月中旬', '下个月下旬'].includes(expr)) return null
+  const [y, m] = today.split('-').map(Number)
+  const day = expr === '下个月初' ? 1 : expr === '下个月中旬' ? 11 : 21
+  return ymd(new Date(y, m, day))
+}
+
+/**
+ * 逐字时间表达 → 绝对日期。顺序:绝对表达 → 「+N」后缀拆解 → 锚点卡词表 → unresolved。
+ * kind 告知下游证据等级:absolute/card 可直接用于工具查询;unresolved 必须原文透传给人/模型。
+ */
+export function resolveSlotDate(expr: string, anchor: TimeAnchor): SlotDateResolution {
+  const raw = expr.trim()
+  const year = Number(anchor.today.slice(0, 4))
+
+  const absolute = parseAbsoluteDate(raw, year)
+  if (absolute) return { raw, date: absolute, kind: 'absolute' }
+
+  const { base, plusDays } = splitPlusSuffix(raw)
+  const baseAbs = parseAbsoluteDate(base, year)
+  if (baseAbs) return { raw, date: addDaysYmd(baseAbs, plusDays), kind: 'absolute' }
+
+  const month = monthFragmentDate(base, anchor.today)
+  if (month) return { raw, date: addDaysYmd(month, plusDays), kind: 'card' }
+
+  const neighbor = neighborDayOffset(base)
+  if (neighbor !== null) return { raw, date: addDaysYmd(anchor.today, neighbor + plusDays), kind: 'card' }
+
+  const offset = weekdayOffsetDays(base, anchor.today)
+  if (offset !== null) return { raw, date: addDaysYmd(anchor.today, offset + plusDays), kind: 'card' }
+
+  return { raw, date: null, kind: 'unresolved' }
+}
+
+/** 各域的日期槽位字段(解析覆盖面:主日期 + 回程/退房) */
+const DATE_FIELDS: Record<string, string[]> = {
+  requisition: ['start_date', 'end_date'],
+  flight: ['departure_date', 'return_date'],
+  hotel: ['check_in_date', 'check_out_date'],
+}
+
+export interface ResolvedSlots {
+  requisition?: { start_date?: SlotDateResolution; end_date?: SlotDateResolution }
+  flight?: { departure_date?: SlotDateResolution; return_date?: SlotDateResolution }
+  hotel?: { check_in_date?: SlotDateResolution; check_out_date?: SlotDateResolution }
+  /** 词表外表达清单(field = "<domain>.<field>"),逐字保留等下游(人/模型)裁决 */
+  unresolved: Array<{ field: string; raw: string }>
+}
+
+/** 整张抽取的日期解析(纯函数,不改入参):只处理日期槽位,目的地/偏好等不在此层 */
+export function resolveSlots(ext: TravelSlotExtraction, anchor: TimeAnchor): ResolvedSlots {
+  const out: ResolvedSlots = { unresolved: [] }
+  for (const domain of ext.domains) {
+    const slots = ext.slots[domain] as Record<string, unknown> | undefined
+    if (!slots) continue
+    for (const field of DATE_FIELDS[domain] ?? []) {
+      const value = slots[field]
+      if (typeof value !== 'string') continue
+      const res = resolveSlotDate(value, anchor)
+      const bucket = (out[domain as keyof Omit<ResolvedSlots, 'unresolved'>] ??= {}) as Record<string, SlotDateResolution>
+      bucket[field] = res
+      if (res.kind === 'unresolved') out.unresolved.push({ field: `${domain}.${field}`, raw: res.raw })
+    }
+  }
+  return out
+}
+
+export interface SpecDateMismatch {
+  /** spec 侧位置,如 segments[0].date */
+  specAt: string
+  field: string
+  specDate: string
+  slotDate: string
+}
+
+/**
+ * spec ↔ 槽位日期一致性闸(ADR-10 翻译≠造数的执行面):LLM 产出的 JourneySpecTS 日期
+ * 与代码层换算的槽位日期逐项比对,分歧即返回 mismatch(供渲染 red-flag/追问),不静默采信。
+ *
+ * 范围边界(2026-08-28 巡检修正):槽位 v1 只有 trip 级主日期(start/departure/check-in),
+ * **只校验恰好一个带日期段的 spec**;多段行程的逐段日期没有槽位真值可比(不比,不造假阳性
+ * ——金标准六段行程曾被全段误判分歧,求解被永久拦截)。spec 无日期或槽位 unresolved 不参与。
+ */
+export function specDateMismatches(
+  spec: { segments?: Array<{ date?: string }> },
+  resolved: ResolvedSlots,
+): SpecDateMismatch[] {
+  const mismatches: SpecDateMismatch[] = []
+  const primary: Array<{ field: string; res?: SlotDateResolution }> = [
+    { field: 'requisition.start_date', res: resolved.requisition?.start_date },
+    { field: 'flight.departure_date', res: resolved.flight?.departure_date },
+    { field: 'hotel.check_in_date', res: resolved.hotel?.check_in_date },
+  ]
+  const dated = primary.filter((p): p is { field: string; res: SlotDateResolution } => p.res?.date != null)
+  if (dated.length === 0) return mismatches
+  const datedSegs = (spec.segments ?? []).filter(s => typeof s.date === 'string' && s.date)
+  if (datedSegs.length !== 1) return mismatches // 多段(或零段)无逐段真值,闸不判
+  const seg = datedSegs[0]!
+  const slotDates = new Set(dated.map(s => s.res.date as string))
+  if (!slotDates.has(seg.date as string)) {
+    mismatches.push({
+      specAt: `segments[${(spec.segments ?? []).indexOf(seg)}].date`,
+      field: dated.map(s => s.field).join('|'),
+      specDate: seg.date as string,
+      slotDate: [...slotDates].join('|'),
+    })
+  }
+  return mismatches
+}