@twinsearth/w2m-dsh-plugin 1.9.0 → 1.9.3

package/src/relay/guarded-dispatch.mjs

@@ -0,0 +1,43 @@
+/**
+ * Commit 1 的可测试接线层：把红线守卫包在现有 handler 外层。
+ * server.mjs 只需 `const handle = createGuardedDispatch({ handle: rawHandle })` 即可接入，
+ * 无需把守卫散落到各路由内部。
+ */
+import { guardResultEnvelope, guardTaskBody } from './redline-guard.mjs';
+import { blobRefusal } from './p0-projection.mjs';
+
+const BLOB_PREFIXES = ['/v1/fleet/blob-sessions', '/v1/fleet/blobs', '/v1/fleet/blob-latest'];
+
+function refusal(status, body) {
+  return { status, body, headers: { 'cache-control': 'no-store' } };
+}
+
+/**
+ * @param {{handle: Function}} options
+ * @returns {Function} (request) => {status, body, headers}；request: {method, path, body}
+ */
+export function createGuardedDispatch({ handle }) {
+  if (typeof handle !== 'function') throw new Error('HANDLE_REQUIRED');
+  return function guarded(request) {
+    const method = String(request?.method ?? 'GET').toUpperCase();
+    const path = String(request?.path ?? '/');
+
+    for (const prefix of BLOB_PREFIXES) {
+      if (path === prefix || path.startsWith(prefix + '/') || path.startsWith(prefix + '?')) {
+        const refusalResult = blobRefusal(method);
+        return refusal(refusalResult.status, refusalResult.body);
+      }
+    }
+
+    if (method === 'POST' && path === '/v1/task') {
+      const guard = guardTaskBody(request?.body);
+      if (guard.ok !== true) return refusal(guard.status, guard.body);
+    }
+    if (method === 'POST' && path === '/v1/result') {
+      const guard = guardResultEnvelope(request?.body);
+      if (guard.ok !== true) return refusal(guard.status, guard.body);
+    }
+
+    return handle(request);
+  };
+}

package/src/relay/p0-projection.mjs

@@ -0,0 +1,94 @@
+/**
+ * relay P0 投影：写入磁盘/ledger/报表前的唯一投影点。
+ * V5/V6/V7：去 stdout/stderr 头尾、argv→hash、路径→count+hash。
+ * V8：报表去 stdout_head，blob_sha256 恒 null。
+ * V12：blob 端点统一拒绝。
+ */
+import { createHash } from 'node:crypto';
+
+const sha256 = (text) => createHash('sha256').update(text, 'utf8').digest('hex');
+const CONTENT_FIELDS = ['stdout_head', 'stdout_tail', 'stderr_head', 'stderr_tail', 'command_argv', 'pipeline_hash_material'];
+
+function projectPaths(list) {
+  if (!Array.isArray(list)) return { count: 0, paths_sha256: sha256('') };
+  const normalized = list.map((entry) => String(entry).replace(/\\/g, '/')).sort();
+  return { count: normalized.length, paths_sha256: sha256(normalized.join('\n')) };
+}
+
+/**
+ * 投影结果信封（原地副本，不改入参）。
+ * @returns {{projected: object, dropped: string[], argv_hash: string|null}}
+ */
+export function projectResultEnvelope(envelope) {
+  if (envelope === null || typeof envelope !== 'object') return { projected: envelope, dropped: [], argv_hash: null };
+  const projected = JSON.parse(JSON.stringify(envelope));
+  const dropped = [];
+  let argvHash = null;
+  for (const field of CONTENT_FIELDS) {
+    if (field in projected) {
+      if (field === 'command_argv') argvHash = sha256(JSON.stringify(projected[field]));
+      delete projected[field];
+      dropped.push(field);
+    }
+  }
+  if (argvHash !== null) projected.command_argv_sha256 = argvHash;
+  if ('blob_sha256' in projected) { projected.blob_sha256 = null; dropped.push('blob_sha256'); }
+  if ('output_mode' in projected) { delete projected.output_mode; dropped.push('output_mode'); }
+  if (projected.workspace !== null && typeof projected.workspace === 'object') {
+    if ('patch_sha256' in projected.workspace) projected.workspace.patch_sha256 = null;
+    if ('changed_files' in projected.workspace) {
+      projected.workspace.files = projectPaths(projected.workspace.changed_files);
+      delete projected.workspace.changed_files;
+      dropped.push('workspace.changed_files');
+    }
+  }
+  if ('changed_files' in projected) {
+    projected.files = projectPaths(projected.changed_files);
+    delete projected.changed_files;
+    dropped.push('changed_files');
+  }
+  // V7：其余本地派生路径字段同样只保留 count + paths_sha256
+  for (const field of ['untracked', 'untracked_files', 'diff_numstat', 'renames', 'deleted_files', 'deleted']) {
+    if (field in projected) {
+      projected[field + '_paths'] = projectPaths(Array.isArray(projected[field]) ? projected[field] : []);
+      delete projected[field];
+      dropped.push(field);
+    }
+  }
+  return { projected, dropped, argv_hash: argvHash };
+}
+
+/** 投影 ledger 行（result.stored 等）：只保留元数据。 */
+export function projectLedgerLine(line) {
+  let record;
+  try { record = JSON.parse(line); } catch { return { changed: false, line }; }
+  const target = record?.result ?? record?.envelope;
+  if (target === null || typeof target !== 'object') return { changed: false, line };
+  const { projected, dropped } = projectResultEnvelope(target);
+  if (dropped.length === 0) return { changed: false, line };
+  if (record.result !== undefined) record.result = projected; else record.envelope = projected;
+  record.projection = { dropped, at: new Date().toISOString() };
+  return { changed: true, line: JSON.stringify(record) };
+}
+
+/** V8：报表聚合投影。 */
+export function stripReportAggregate(aggregate) {
+  if (aggregate === null || typeof aggregate !== 'object') return aggregate;
+  const out = JSON.parse(JSON.stringify(aggregate));
+  const machines = Array.isArray(out.machines) ? out.machines : [];
+  for (const machine of machines) {
+    if ('stdout_head' in machine) delete machine.stdout_head;
+    if ('blob_sha256' in machine) machine.blob_sha256 = null;
+  }
+  if ('stdout_head' in out) delete out.stdout_head;
+  if ('blob_sha256' in out) out.blob_sha256 = null;
+  return out;
+}
+
+/** V12：blob 端点统一拒绝。 */
+export function blobRefusal(method) {
+  return {
+    status: 403,
+    body: { ok: false, code: 'DATA_PLANE_REFUSED', detail: { method, reason: 'relay never stores data-plane objects' } },
+  };
+}

package/src/relay/redline-guard.mjs

@@ -0,0 +1,72 @@
+/**
+ * relay 红线守卫（relay 专用；字段表唯一来源 util/redline-core）。
+ * C7：深层递归扫描 + 16KiB 语义上限 + 协议错误形状（protocol_version/error.code）。
+ */
+import { FORBIDDEN_DATA_KEYS } from '../util/redline-core.mjs';
+
+export const MAX_CONTROL_BYTES = 16 * 1024;
+const PROTOCOL_VERSION = 1;
+
+const MESSAGES = {
+  DATA_PLANE_FORBIDDEN: 'the payload carries data-plane content; relay stores metadata only',
+  CONTROL_TOO_LARGE: 'the control message exceeds the 16 KiB limit',
+  BAD_REQUEST: 'the request body is not a JSON object',
+};
+
+function refuse(status, code, detail = {}) {
+  return {
+    status,
+    body: {
+      protocol_version: PROTOCOL_VERSION,
+      ok: false,
+      code,
+      reason: code,
+      detail,
+      error: { code, message: MESSAGES[code] ?? code, detail },
+    },
+  };
+}
+
+function scan(value, path, hits) {
+  if (value === null || typeof value !== 'object') return;
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => scan(entry, path + '[' + index + ']', hits));
+    return;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    const keyPath = path === '' ? key : path + '.' + key;
+    if (FORBIDDEN_DATA_KEYS.includes(key.toLowerCase())) hits.push(keyPath);
+    scan(child, keyPath, hits);
+  }
+}
+
+export function guardTaskBody(body) {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) return refuse(400, 'BAD_REQUEST');
+  const bytes = Buffer.byteLength(JSON.stringify(body), 'utf8');
+  if (bytes > MAX_CONTROL_BYTES) return refuse(413, 'CONTROL_TOO_LARGE', { bytes, limit_bytes: MAX_CONTROL_BYTES });
+  const hits = [];
+  scan(body, '', hits);
+  if (hits.length > 0) return refuse(422, 'DATA_PLANE_FORBIDDEN', { fields: hits.filter((hit) => !hit.includes('.')), paths: hits.slice(0, 8) });
+  return { ok: true };
+}
+
+export function guardResultEnvelope(envelope) {
+  if (envelope === null || typeof envelope !== 'object' || Array.isArray(envelope)) return refuse(400, 'BAD_REQUEST');
+  const explicit = ['stdout_head', 'stdout_tail', 'stderr_head', 'stderr_tail', 'command_argv', 'blob_sha256', 'output_mode'].filter((key) => key in envelope);
+  const hits = [];
+  scan(envelope, '', hits);
+  if (explicit.length > 0 || hits.length > 0) return refuse(422, 'DATA_PLANE_FORBIDDEN', { fields: [...explicit, ...hits.filter((hit) => !hit.includes('.'))], paths: hits.slice(0, 8) });
+  return { ok: true };
+}
+
+export function guardBlobRoute(method) {
+  return {
+    status: 403,
+    body: {
+      protocol_version: PROTOCOL_VERSION,
+      ok: false,
+      code: 'DATA_PLANE_REFUSED',
+      error: { code: 'DATA_PLANE_REFUSED', message: 'relay never stores data-plane objects', detail: { method } },
+    },
+  };
+}

package/src/relay/scrub.mjs

@@ -0,0 +1,91 @@
+/**
+ * relay 状态清理（P0）：旧 blob 清除 + ledger 内容投影重建。
+ * 只处理已落盘的数据，不联网；dry-run 先报清单，apply 先备份再原子替换。
+ */
+import {
+  copyFileSync, existsSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync,
+} from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+
+export const LEDGER_CONTENT_FIELDS = ['stdout_head', 'stdout_tail', 'stderr_head', 'stderr_tail', 'command_argv', 'pipeline_hash_material', 'changed_files'];
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+
+function projectLedgerLine(line) {
+  let record;
+  try { record = JSON.parse(line); } catch { return { changed: false, line }; }
+  const result = record?.result ?? record?.envelope ?? null;
+  if (result === null || typeof result !== 'object') return { changed: false, line };
+  let changed = false;
+  for (const field of LEDGER_CONTENT_FIELDS) {
+    if (field in result) { delete result[field]; changed = true; }
+  }
+  if ('patch_sha256' in result) { result.patch_sha256 = null; changed = true; }
+  if ('workspace' in result && typeof result.workspace === 'object' && result.workspace !== null) {
+    if ('changed_files' in result.workspace) { delete result.workspace.changed_files; changed = true; }
+    if ('patch_sha256' in result.workspace) { result.workspace.patch_sha256 = null; changed = true; }
+  }
+  return { changed, line: changed ? JSON.stringify(record) : line };
+}
+
+/** 清理 ledger：默认 dry-run；apply 时备份 .bak-<ts> 后原子替换。 */
+export function scrubLedger(ledgerPath, { dryRun = true, now = Date.now() } = {}) {
+  if (!existsSync(ledgerPath)) return { ok: true, exists: false, changed: 0, lines: 0, backup: null };
+  const text = readFileSync(ledgerPath, 'utf8');
+  const lines = text.split('\n').filter((line) => line.trim() !== '');
+  let changed = 0;
+  const rewritten = lines.map((line) => {
+    const projected = projectLedgerLine(line);
+    if (projected.changed) changed += 1;
+    return projected.line;
+  });
+  if (dryRun || changed === 0) return { ok: true, exists: true, changed, lines: lines.length, backup: null, dryRun };
+  const backup = ledgerPath + '.bak-' + now;
+  copyFileSync(ledgerPath, backup);
+  const tmp = ledgerPath + '.tmp-' + process.pid;
+  writeFileSync(tmp, rewritten.join('\n') + '\n', 'utf8');
+  renameSync(tmp, ledgerPath);
+  return { ok: true, exists: true, changed, lines: lines.length, backup, dryRun: false };
+}
+
+/** 清点/删除 relay blob 目录（内容寻址文件）。 */
+export function scrubBlobs(blobDir, { dryRun = true, now = Date.now() } = {}) {
+  if (!existsSync(blobDir)) return { ok: true, exists: false, files: [], bytes: 0, deleted: 0, manifest: null };
+  const files = [];
+  let bytes = 0;
+  for (const name of readdirSync(blobDir)) {
+    const path = join(blobDir, name);
+    if (!statSync(path).isFile()) continue;
+    files.push(name);
+    bytes += statSync(path).size;
+  }
+  const manifest = {
+    at: new Date(now).toISOString(),
+    files: files.map((name) => ({ name, sha256: sha256(readFileSync(join(blobDir, name))) })),
+  };
+  if (dryRun) return { ok: true, exists: true, files, bytes, deleted: 0, manifest, dryRun };
+  for (const name of files) unlinkSync(join(blobDir, name));
+  return { ok: true, exists: true, files, bytes, deleted: files.length, manifest, dryRun: false };
+}
+
+/** 验收：扫描目录中是否仍存在内容字段/数据面 marker。 */
+export function scanForContent(rootDir, markers = []) {
+  const hits = [];
+  const walk = (dir) => {
+    for (const name of readdirSync(dir)) {
+      const path = join(dir, name);
+      const stat = statSync(path);
+      if (stat.isDirectory()) { walk(path); continue; }
+      if (stat.size > 32 * 1024 * 1024) continue;
+      const text = readFileSync(path, 'utf8');
+      for (const field of LEDGER_CONTENT_FIELDS) {
+        if (text.includes('"' + field + '"')) hits.push({ file: path, marker: field });
+      }
+      for (const marker of markers) {
+        if (marker !== '' && text.includes(marker)) hits.push({ file: path, marker });
+      }
+    }
+  };
+  if (existsSync(rootDir)) walk(rootDir);
+  return { ok: hits.length === 0, hits };
+}

package/src/relay/server.mjs

@@ -1,3 +1,5 @@
+import { guardBlobRoute } from './redline-guard.mjs';
+import { guardResultEnvelope, guardTaskBody } from './redline-guard.mjs';
 /**
  * W2M Rabbit relay — node:http / node:https server.
  *
@@ -695,6 +697,13 @@ export class RelayServer {
       });
     }
     const path = normalizePath(stripped);
+    // B3/V12：basePath 剥离与 URL 规范化之后立即拒绝数据面 blob 路由，
+    // 覆盖 `..`、`%2e%2e`、basePath 前缀等变形；在读取 body 之前返回。
+    if (path === '/v1/fleet/blob-sessions' || path.startsWith('/v1/fleet/blob-sessions/')
+        || path === '/v1/fleet/blob-latest' || path.startsWith('/v1/fleet/blobs')) {
+      const refusal = guardBlobRoute(method);
+      return sendJson(res, refusal.status, refusal.body);
+    }
     const signedPath = `${stripped}${url.search}`;
 
     // v0.3.0 §9: read the body ONCE, before routing. An HMAC covers the exact
@@ -785,6 +794,10 @@ export class RelayServer {
       this.enforceSignature(req, { method, signedPath, body: rawBody });
       const body = takeJson();
       if (principal.machine_id && !body.created_by) body.created_by = principal.machine_id;
+      const taskGuard = guardTaskBody(body);
+      if (taskGuard.ok !== true) {
+        return sendJson(res, taskGuard.status, taskGuard.body);
+      }
       const result = this.state.createTask(body);
       return sendJson(res, 200, result);
     }
@@ -1210,7 +1223,14 @@ export class RelayServer {
     }
     if (method === 'POST' && path === '/v1/result') {
       const body = takeJson();
-      const result = this.state.submitResult(body);
+      // B1 方案 A：window 模式接收旧信封（含 argv/head）并投影后存储；enforce 才硬拒。
+    if (String(process.env.W2M_DATA_PLANE_GUARD ?? 'window') === 'enforce') {
+      const resultGuard = guardResultEnvelope(body);
+      if (resultGuard.ok !== true) {
+        return sendJson(res, resultGuard.status, resultGuard.body);
+      }
+    }
+    const result = this.state.submitResult(body);
       const { _instanceKey, ...clean } = result;
       return sendJson(res, 200, clean);
     }

package/src/relay/state.mjs

@@ -1,3 +1,4 @@
+import { projectResultEnvelope } from './p0-projection.mjs';
 /**
  * W2M Rabbit relay — in-memory state machine.
  *
@@ -3155,8 +3156,12 @@ export class RabbitState {
       envelopeShaOk = sha256Hex(jcs(rest)) === envelope.envelope_sha256;
     }
 
+    // B2/V5/V6/V7：先校验（上面已完成），再投影后存储；原信封哈希单独保留用于审计。
+    const { projected, dropped } = projectResultEnvelope(envelope);
     const record = {
-      envelope,
+      envelope: projected,
+      envelope_sha256_received: typeof envelope.envelope_sha256 === 'string' ? envelope.envelope_sha256 : null,
+      ...(dropped.length > 0 ? { projection: { dropped } } : {}),
       machine_id: machineId,
       dedupe_key: dedupeKey,
       attempt,

package/src/util/data-plane.mjs

@@ -0,0 +1,180 @@
+/**
+ * S0 — 数据面端口（DataPlaneSink）。P0 止血的地基。
+ *
+ * 红线（2026-10-27 冻结）：
+ *  · 用户数据只允许去用户自己选择的第三方（GitHub / 局域网 Git / SSH 云盘等）；
+ *  · 我们的 Relay 只承载类型化元数据（指令/状态/hash/size/count/Ref ≤4KiB）；
+ *  · 任何 push/fetch 目标解析后指向 relay → 一律拒绝；
+ *  · 无 sink 时统一返回 ARTIFACT_NOT_DELIVERED，绝不回退 relay。
+ *
+ * 本模块无 I/O：只做 Ref 校验、sink 目标判定与端口分发。真实适配器（git/ssh/dir）
+ * 与 NullSink 由调用方注入，这样单测不碰网络与磁盘。
+ */
+
+export const REF_MAX_BYTES = 4096;
+export const REF_FIELDS = Object.freeze([
+  'v', 'sink', 'locator', 'kind', 'task_id', 'machine_id',
+  'plain', 'cipher', 'enc', 'zip', 'sig',
+]);
+export const REF_KINDS = Object.freeze(['stdout', 'stderr', 'patch', 'memory', 'artifact', 'reduce-input']);
+export const SINK_KINDS = Object.freeze(['github', 'lan-git', 'ssh', 'dir']);
+export const REF_HEX = /^[0-9a-f]{64}$/;
+
+const DATA_FIELDS = new Set([
+  'data', 'content', 'contents', 'patch', 'patch_text', 'stdout', 'stderr',
+  'text', 'blob', 'base64', 'body', 'raw',
+]);
+
+function utf8Bytes(value) {
+  return Buffer.byteLength(typeof value === 'string' ? value : JSON.stringify(value), 'utf8');
+}
+
+function parseHost(endpoint) {
+  if (typeof endpoint !== 'string' || endpoint.trim() === '') return null;
+  const scpLike = /^[^@\s]+@([^:\s]+):/.exec(endpoint.trim());
+  if (scpLike !== null) return { host: scpLike[1].toLowerCase(), port: '', href: endpoint, scheme: 'ssh' };
+  try {
+    const url = new URL(endpoint);
+    return { host: url.hostname.toLowerCase(), port: url.port, href: url.href, scheme: url.protocol.replace(':', '') };
+  } catch {
+    return null;
+  }
+}
+
+function isPrivateOrLocal(host) {
+  return /^10\./.test(host)
+    || /^192\.168\./.test(host)
+    || /^172\.(1[6-9]|2\d|3[01])\./.test(host)
+    || host === 'localhost'
+    || host.endsWith('.local')
+    || /^\[fd[0-9a-f]{2}:/i.test(host)
+    || /^\[fe80:/i.test(host);
+}
+
+/**
+ * 判断一个数据面目标是否获准（只做字符串/URL 级判定；DNS 解析后校验由适配器负责）。
+ * @returns {{ok: true, sink: string} | {ok: false, code: string, detail: object}}
+ */
+export function assertDataPlaneTarget({ endpoint, relayBase }) {
+  const target = parseHost(endpoint);
+  if (target === null) return { ok: false, code: 'DATA_PLANE_ENDPOINT_INVALID', detail: {} };
+  if (typeof relayBase === 'string' && relayBase !== '') {
+    const relay = parseHost(relayBase);
+    if (relay !== null && target.host === relay.host) {
+      return { ok: false, code: 'DATA_PLANE_POINTS_AT_RELAY', detail: { endpoint, relay: relay.host } };
+    }
+  }
+  if (target.host === 'github.com' || target.host.endsWith('.github.com')) {
+    return { ok: true, sink: 'github' };
+  }
+  if (target.scheme === 'ssh' || target.scheme === 'git') {
+    return { ok: true, sink: isPrivateOrLocal(target.host) ? 'lan-git' : 'ssh' };
+  }
+  if (target.scheme === 'http' || target.scheme === 'https') {
+    if (isPrivateOrLocal(target.host)) return { ok: true, sink: 'lan-git' };
+    return { ok: false, code: 'DATA_PLANE_SCHEME_FORBIDDEN', detail: { scheme: target.scheme, host: target.host } };
+  }
+  return { ok: false, code: 'DATA_PLANE_SCHEME_FORBIDDEN', detail: { scheme: target.scheme } };
+}
+
+function scanForContent(value, path, hits) {
+  if (value === null || typeof value !== 'object') return;
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => scanForContent(entry, path + '[' + index + ']', hits));
+    return;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    const keyPath = path === '' ? key : path + '.' + key;
+    if (DATA_FIELDS.has(key.toLowerCase())) hits.push(keyPath);
+    scanForContent(child, keyPath, hits);
+  }
+}
+
+/**
+ * 校验进入控制面的 Ref：纯元数据、≤4KiB、无内容字段、哈希形状正确。
+ * @returns {{ok: true} | {ok: false, code: string, detail: object}}
+ */
+export function inspectRef(ref) {
+  if (ref === null || typeof ref !== 'object' || Array.isArray(ref)) {
+    return { ok: false, code: 'REF_NOT_OBJECT', detail: {} };
+  }
+  const bytes = utf8Bytes(ref);
+  if (bytes > REF_MAX_BYTES) {
+    return { ok: false, code: 'REF_TOO_LARGE', detail: { bytes, limit_bytes: REF_MAX_BYTES } };
+  }
+  const hits = [];
+  scanForContent(ref, '', hits);
+  if (hits.length > 0) return { ok: false, code: 'DATA_PLANE_FORBIDDEN', detail: { paths: hits.slice(0, 8) } };
+  const unknown = Object.keys(ref).filter((key) => !REF_FIELDS.includes(key));
+  if (unknown.length > 0) {
+    return { ok: false, code: 'REF_FIELD_UNKNOWN', detail: { unknown, allowed: REF_FIELDS.slice() } };
+  }
+  if (ref.v !== 1) return { ok: false, code: 'REF_VERSION', detail: { expected: 1, got: ref.v ?? null } };
+  if (!SINK_KINDS.includes(ref.sink)) {
+    return { ok: false, code: 'REF_SINK_UNKNOWN', detail: { allowed: SINK_KINDS.slice(), got: ref.sink ?? null } };
+  }
+  if (!REF_KINDS.includes(ref.kind)) {
+    return { ok: false, code: 'REF_KIND_UNKNOWN', detail: { allowed: REF_KINDS.slice(), got: ref.kind ?? null } };
+  }
+  if (typeof ref.locator !== 'string' || ref.locator.trim() === '' || ref.locator.length > 512) {
+    return { ok: false, code: 'REF_LOCATOR_INVALID', detail: {} };
+  }
+  if (ref.plain !== undefined) {
+    if (typeof ref.plain !== 'object' || !REF_HEX.test(String(ref.plain.sha256 ?? ''))) {
+      return { ok: false, code: 'REF_PLAIN_INVALID', detail: {} };
+    }
+  }
+  if (ref.cipher !== undefined) {
+    if (typeof ref.cipher !== 'object' || !REF_HEX.test(String(ref.cipher.sha256 ?? ''))) {
+      return { ok: false, code: 'REF_CIPHER_INVALID', detail: {} };
+    }
+  }
+  return { ok: true };
+}
+
+/**
+ * NullSink：永不上传，统一降级码。用于"无数据面"的合规默认值。
+ */
+export function createNullSink() {
+  return {
+    kind: 'null',
+    async pushObject() {
+      return { ok: false, code: 'ARTIFACT_NOT_DELIVERED', detail: { reason: 'no data plane sink configured' } };
+    },
+    async fetchObject() {
+      return { ok: false, code: 'ARTIFACT_NOT_DELIVERED', detail: { reason: 'no data plane sink configured' } };
+    },
+  };
+}
+
+/**
+ * 端口分发：调用方注入 sinks（github/lan-git/ssh/dir），未命中一律 NullSink。
+ * @param {{sinks?: Record<string, object>, relayBase?: string}} [options]
+ */
+export function createDataPlane(options = {}) {
+  const sinks = options.sinks ?? {};
+  const relayBase = options.relayBase ?? '';
+  function pick(endpoint) {
+    const target = assertDataPlaneTarget({ endpoint, relayBase });
+    if (target.ok !== true) return { ok: false, result: target };
+    const sink = sinks[target.sink];
+    if (sink === undefined) return { ok: true, sink: createNullSink() };
+    return { ok: true, sink };
+  }
+  return {
+    async pushObject({ endpoint, ref, ...rest }) {
+      const refCheck = inspectRef(ref);
+      if (refCheck.ok !== true) return refCheck;
+      const chosen = pick(endpoint);
+      if (chosen.ok !== true) return chosen.result;
+      return chosen.sink.pushObject({ ref, ...rest });
+    },
+    async fetchObject({ endpoint, ref, ...rest }) {
+      const refCheck = inspectRef(ref);
+      if (refCheck.ok !== true) return refCheck;
+      const chosen = pick(endpoint);
+      if (chosen.ok !== true) return chosen.result;
+      return chosen.sink.fetchObject({ ref, ...rest });
+    },
+  };
+}