@linxin666/dsh-client-ui-task-board 0.3.6 → 0.3.9

package/src/protocol.ts

@@ -1,8 +1,15 @@
 import type { TaskUpdatePatch } from './core/use-cases/task-update.ts'
-import { isTaskPermission, isTaskStatus, type NewTaskInput, type TaskRecord, type TaskStatus } from './core/tasks.ts'
+import { isTaskPermission, isTaskStatus, type NewTaskInput, type TaskPermission, type TaskRecord, type TaskStatus } from './core/tasks.ts'
 import { parseLedger } from './core/store.ts'
+import { sanitizeFreezeSnapshot, type FreezeSnapshot } from './core/freeze-snapshot.ts'
+import { sanitizeHandover, type TaskHandoverInput } from './core/handover.ts'
 
-export const TASK_BOARD_SCHEMA_VERSION = 2 as const
+/** Freeze payload carried by create/update actions after the gate (redacted in place). */
+type FreezePayload = FreezeSnapshot & { redacted?: boolean; frozenBy?: string }
+
+export const TASK_BOARD_SCHEMA_VERSION = 3 as const
+/** Ledger documents written before v3; loaded once and migrated on startup. */
+export const TASK_BOARD_LEGACY_SCHEMA_VERSION = 2 as const
 export const TASK_BOARD_API_PREFIX = '/api/task-board'
 
 export type PowerPhase = 'disabled' | 'idle' | 'acquiring' | 'active' | 'error' | 'unsupported'
@@ -31,6 +38,8 @@ export interface TaskBoardSnapshot {
   tasks: TaskRecord[]
   scheduler: TaskBoardSchedulerSnapshot
   power: TaskBoardPowerSnapshot
+  /** Session-default permission the confirmation gate compares against. */
+  sessionDefaultPermission?: TaskPermission
 }
 
 /** SSE event frame: revision/scheduler/power only, never the task list. */
@@ -51,10 +60,17 @@ export type TaskBoardAction =
   | { kind: 'set-schedule'; taskId: string; patch: { enabled?: boolean; cron?: string } }
   | { kind: 'run'; taskId: string }
   | { kind: 'rerun'; taskId: string }
+  | { kind: 'confirm-permission'; taskId: string }
 
 export interface TaskBoardActionEnvelope {
   requestId: string
   action: TaskBoardAction
+  /**
+   * Session id of the DSH session issuing the action, for the execution audit
+   * trail (issue #6). Client-asserted, not a trust boundary; parsed only as a
+   * bounded non-empty string and recorded on opened executions / freeze stamps.
+   */
+  initiator?: string
 }
 
 function record(value: unknown): Record<string, unknown> | undefined {
@@ -98,6 +114,9 @@ function validImportedKnownFields(value: Record<string, unknown>): boolean {
       if (typeof execution.startedAt !== 'number' || !Number.isFinite(execution.startedAt)) return false
       if (!optionalFiniteNumber(execution.endedAt) || !optionalString(execution.error)) return false
       if (execution.result !== undefined && !['succeeded', 'failed', 'cancelled'].includes(String(execution.result))) return false
+      if (execution.initiatedBy !== undefined && typeof execution.initiatedBy !== 'string') return false
+      if (execution.frozenBy !== undefined && typeof execution.frozenBy !== 'string') return false
+      if (execution.frozenAt !== undefined && typeof execution.frozenAt !== 'number') return false
     }
   }
   return true
@@ -123,6 +142,9 @@ function importedTask(value: unknown): TaskRecord | undefined {
       endedAt: execution.endedAt,
       result: execution.result,
       error: execution.error,
+      ...(execution.initiatedBy === undefined ? {} : { initiatedBy: execution.initiatedBy }),
+      ...(execution.frozenAt === undefined ? {} : { frozenAt: execution.frozenAt }),
+      ...(execution.frozenBy === undefined ? {} : { frozenBy: execution.frozenBy }),
     })),
     ...(task.schedule === undefined ? {} : {
       schedule: {
@@ -136,15 +158,47 @@ function importedTask(value: unknown): TaskRecord | undefined {
     ...(task.mode === undefined ? {} : { mode: task.mode }),
     ...(task.permission === undefined ? {} : { permission: task.permission }),
     ...(task.archivedAt === undefined ? {} : { archivedAt: task.archivedAt }),
+    ...(task.freeze === undefined ? {} : { freeze: task.freeze }),
+    ...(task.handover === undefined ? {} : { handover: task.handover }),
+    // 安全门（对抗场景 b）：import 不是人工确认动作，确认戳一律剥除——
+    // 高于会话默认权限的绑定经 import 进入后必须重新武装 confirm-permission 门。
+  }
+}
+
+/**
+ * Gate a freeze payload from the wire: same T2 security gates as the parser
+ * (slash-command taint rejects, sensitive patterns redact in place, 8 KiB
+ * per-field cap). Returns the sanitized payload, or undefined when rejected.
+ */
+function freezePayload(value: unknown): FreezePayload | undefined {
+  const result = sanitizeFreezeSnapshot(value, ['redacted', 'frozenBy'])
+  if (!result.ok) return undefined
+  const frozenBy = result.extras.frozenBy
+  if (frozenBy !== undefined && (typeof frozenBy !== 'string' || frozenBy === '')) return undefined
+  return {
+    ...result.snapshot,
+    ...(result.redacted || result.extras.redacted === true ? { redacted: true } : {}),
+    ...(frozenBy === undefined ? {} : { frozenBy }),
   }
 }
 
+/**
+ * Gate a handover bundle from the wire: exact keys, bounded string targets,
+ * a known permission, and a bounded references list. Returns the sanitized
+ * bundle, or undefined when rejected.
+ */
+function handoverPayload(value: unknown): TaskHandoverInput | undefined {
+  return sanitizeHandover(value)
+}
+
 function createInput(value: unknown): value is NewTaskInput {
   const input = record(value)
-  if (input === undefined || !exactKeys(input, ['title', 'description', 'prompt', 'workspaceId', 'mode', 'permission', 'schedule'])) return false
+  if (input === undefined || !exactKeys(input, ['title', 'description', 'prompt', 'workspaceId', 'mode', 'permission', 'schedule', 'freeze', 'handover'])) return false
   if (typeof input.title !== 'string' || typeof input.description !== 'string' || typeof input.prompt !== 'string') return false
   if (!optionalString(input.workspaceId) || !optionalString(input.mode)) return false
   if (input.permission !== undefined && !isTaskPermission(input.permission)) return false
+  if (input.freeze !== undefined && freezePayload(input.freeze) === undefined) return false
+  if (input.handover !== undefined && handoverPayload(input.handover) === undefined) return false
   if (input.schedule !== undefined) {
     const schedule = record(input.schedule)
     if (schedule === undefined || !exactKeys(schedule, ['enabled', 'cron'])) return false
@@ -155,11 +209,15 @@ function createInput(value: unknown): value is NewTaskInput {
 
 function updatePatch(value: unknown): boolean {
   const patch = record(value)
-  if (patch === undefined || !exactKeys(patch, ['title', 'description', 'prompt', 'workspaceId', 'mode', 'permission'])) return false
+  if (patch === undefined || !exactKeys(patch, ['title', 'description', 'prompt', 'workspaceId', 'mode', 'permission', 'freeze', 'handover'])) return false
   for (const key of ['title', 'description', 'prompt', 'workspaceId', 'mode'] as const) {
     if (!optionalString(patch[key])) return false
   }
-  return patch.permission === undefined || isTaskPermission(patch.permission)
+  if (patch.permission !== undefined && !isTaskPermission(patch.permission)) return false
+  // null clears the snapshot; an object must pass the freeze gate.
+  if (patch.freeze !== undefined && patch.freeze !== null && freezePayload(patch.freeze) === undefined) return false
+  // Same convention for the handover bundle.
+  return patch.handover === undefined || patch.handover === null || handoverPayload(patch.handover) !== undefined
 }
 
 function schedulePatch(value: unknown): boolean {
@@ -171,9 +229,24 @@ function schedulePatch(value: unknown): boolean {
 }
 
 export function parseActionEnvelope(value: unknown): TaskBoardActionEnvelope | undefined {
+  const parsed = parseEnvelopeAction(value)
+  if (parsed === undefined) return undefined
+  // Attach the audit-only initiator stamp (already validated above) to every accepted action.
+  const initiator = initiatorOf(value)
+  return initiator === undefined ? parsed : { ...parsed, initiator }
+}
+
+function initiatorOf(value: unknown): string | undefined {
+  const envelope = record(value)
+  const id = envelope?.initiator
+  return typeof id === 'string' && id.trim() !== '' && id.length <= 256 ? id : undefined
+}
+
+function parseEnvelopeAction(value: unknown): TaskBoardActionEnvelope | undefined {
   const envelope = record(value)
-  if (envelope === undefined || !exactKeys(envelope, ['requestId', 'action'])) return undefined
+  if (envelope === undefined || !exactKeys(envelope, ['requestId', 'action', 'initiator'])) return undefined
   if (typeof envelope.requestId !== 'string' || envelope.requestId.trim() === '' || envelope.requestId.length > 256) return undefined
+  if (envelope.initiator !== undefined && initiatorOf(value) === undefined) return undefined
   const action = record(envelope.action)
   if (action === undefined || typeof action.kind !== 'string') return undefined
   const taskId = typeof action.taskId === 'string' && action.taskId !== '' ? action.taskId : undefined
@@ -187,16 +260,26 @@ export function parseActionEnvelope(value: unknown): TaskBoardActionEnvelope | u
           ? { requestId: envelope.requestId, action: { kind: 'import', sourceId: action.sourceId, tasks } }
           : undefined
       }
-    case 'create':
+    case 'create': {
       if (!exactKeys(action, ['kind', 'id', 'input'])) return undefined
-      return typeof action.id === 'string' && action.id !== '' && createInput(action.input)
-        ? { requestId: envelope.requestId, action: action as unknown as Extract<TaskBoardAction, { kind: 'create' }> }
-        : undefined
-    case 'update':
+      if (typeof action.id !== 'string' || action.id === '' || !createInput(action.input)) return undefined
+      const input = action.input as NewTaskInput
+      const freeze = input.freeze === undefined ? undefined : freezePayload(input.freeze)
+      const handover = input.handover === undefined ? undefined : handoverPayload(input.handover)
+      const sanitized = freeze === undefined && handover === undefined ? input : { ...input, ...(freeze === undefined ? {} : { freeze }), ...(handover === undefined ? {} : { handover }) }
+      return { requestId: envelope.requestId, action: { kind: 'create', id: action.id as string, input: sanitized } }
+    }
+    case 'update': {
       if (!exactKeys(action, ['kind', 'taskId', 'patch'])) return undefined
-      return taskId !== undefined && updatePatch(action.patch)
-        ? { requestId: envelope.requestId, action: action as unknown as Extract<TaskBoardAction, { kind: 'update' }> }
-        : undefined
+      if (taskId === undefined || !updatePatch(action.patch)) return undefined
+      const patch = action.patch as TaskUpdatePatch
+      const freeze = patch.freeze === undefined || patch.freeze === null ? patch.freeze : freezePayload(patch.freeze)
+      const handover = patch.handover === undefined || patch.handover === null ? patch.handover : handoverPayload(patch.handover)
+      const sanitized = ('freeze' in patch && freeze !== patch.freeze) || ('handover' in patch && handover !== patch.handover)
+        ? { ...patch, ...(freeze === patch.freeze ? {} : { freeze }), ...(handover === patch.handover ? {} : { handover }) }
+        : patch
+      return { requestId: envelope.requestId, action: { kind: 'update', taskId, patch: sanitized } }
+    }
     case 'set-schedule':
       if (!exactKeys(action, ['kind', 'taskId', 'patch'])) return undefined
       return taskId !== undefined && schedulePatch(action.patch)
@@ -207,6 +290,7 @@ export function parseActionEnvelope(value: unknown): TaskBoardActionEnvelope | u
       return taskId !== undefined && isTaskStatus(action.status)
         ? { requestId: envelope.requestId, action: action as unknown as Extract<TaskBoardAction, { kind: 'move' }> }
         : undefined
+    case 'confirm-permission':
     case 'delete':
     case 'archive':
     case 'restore':