@twinsearth/w2m-dsh-plugin 2.0.6 → 2.0.8

package/src/agent/crypto.mjs

@@ -53,6 +53,8 @@ import {
   randomBytes,
   timingSafeEqual,
 } from 'node:crypto';
+
+import { jsOpen, jsSeal } from './chacha.mjs';
 import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { blake2s256 as blake2s256Js } from './blake2s.mjs';
@@ -758,6 +760,57 @@ export function derive(ikm, label, length = KEY_BYTES) {
  *
  * @returns {{ ok: boolean, missing: string[], present: string[], node: string, detail: string }}
  */
+/** Wrap a cipher construction so an OpenSSL "Unknown cipher" carries WHO/WHAT, not just the text. */
+function cipherContextError(kind, cipherName, error, context = {}) {
+  const wrapped = new Error('P2P_CIPHER_UNAVAILABLE: ' + kind + ' ' + cipherName + ' failed: ' + (error?.message ?? String(error)));
+  wrapped.code = 'P2P_CIPHER_UNAVAILABLE';
+  wrapped.detail = {
+    cipher: cipherName,
+    suite: typeof context.suite === 'string' ? context.suite : 'w2m-p2p-v1',
+    peerKey: typeof context.peerKey === 'string' ? context.peerKey : null,
+    keyLength: context.keyLength ?? null,
+    ivLength: context.ivLength ?? null,
+    openssl: error?.message ?? String(error),
+    node: process.version,
+  };
+  wrapped.cause = error;
+  return wrapped;
+}
+function createCipherContext(name, key, iv, options, context = {}) {
+  try { return createCipheriv(name, key, iv, options); } catch (error) { throw cipherContextError('encrypt', name, error, { ...context, keyLength: key?.length, ivLength: iv?.length }); }
+}
+function createDecipherContext(name, key, iv, options, context = {}) {
+  try { return createDecipheriv(name, key, iv, options); } catch (error) { throw cipherContextError('decrypt', name, error, { ...context, keyLength: key?.length, ivLength: iv?.length }); }
+}
+
+
+/** Native ChaCha20-Poly1305 availability (DSH/Electron's BoringSSL may not expose it). */
+let NATIVE_CHACHA = true;
+try {
+  const probeKey = Buffer.alloc(32, 1);
+  const probeCipher = createCipheriv('chacha20-poly1305', probeKey, Buffer.alloc(12), { authTagLength: 16 });
+  probeCipher.final();
+} catch {
+  NATIVE_CHACHA = false;
+}
+export function nativeAeadAvailable() { return NATIVE_CHACHA; }
+function aeadSeal(key, nonce, plaintext, aad = Buffer.alloc(0), context = {}) {
+  if (!NATIVE_CHACHA) return jsSeal(key, nonce, plaintext, aad);
+  const cipher = createCipherContext('chacha20-poly1305', key, nonce, { authTagLength: TAG_BYTES }, { suite: 'w2m-p2p-v1', ...context });
+  if (aad.length > 0) cipher.setAAD(aad);
+  return Buffer.concat([cipher.update(plaintext), cipher.final(), cipher.getAuthTag()]);
+}
+function aeadOpen(key, nonce, sealed, aad = Buffer.alloc(0)) {
+  if (!NATIVE_CHACHA) return jsOpen(key, nonce, sealed, aad);
+  if (!Buffer.isBuffer(sealed) || sealed.length < TAG_BYTES) return null;
+  try {
+    const decipher = createDecipherContext('chacha20-poly1305', key, nonce, { authTagLength: TAG_BYTES }, { suite: 'w2m-p2p-v1' });
+    if (aad.length > 0) decipher.setAAD(aad);
+    decipher.setAuthTag(sealed.subarray(sealed.length - TAG_BYTES));
+    return Buffer.concat([decipher.update(sealed.subarray(0, sealed.length - TAG_BYTES)), decipher.final()]);
+  } catch { return null; }
+}
+
 export function cryptoCapabilities() {
   const present = [];
   const missing = [];
@@ -774,11 +827,11 @@ export function cryptoCapabilities() {
   check('blake2s256', () => blake2s256Support().ok);
   check('sha256', () => createHash('sha256').update('').digest().length === 32);
   check('chacha20-poly1305', () => {
+    // Count the JS fallback as available: what the handshake needs is the AEAD, not OpenSSL's copy.
     const key = randomBytes(32);
-    const cipher = createCipheriv('chacha20-poly1305', key, Buffer.alloc(12), { authTagLength: 16 });
-    cipher.update(Buffer.from('probe'));
-    cipher.final();
-    return cipher.getAuthTag().length === 16;
+    const sealed = aeadSeal(key, Buffer.alloc(12), Buffer.from('probe'));
+    const opened = aeadOpen(key, Buffer.alloc(12), sealed);
+    return sealed.length === 21 && opened !== null && opened.toString('utf8') === 'probe';
   });
   check('hkdf-sha256', () => hkdfSync('sha256', randomBytes(32), Buffer.alloc(0), Buffer.from('probe'), 32).byteLength === 32);
   check('x25519+diffieHellman', () => {
@@ -993,10 +1046,8 @@ export function sessionKeys({ ephemeralShared, initiatorStaticShared, responderS
  * @param {Buffer} message
  * @returns {Buffer} Ciphertext followed by the tag: 48 bytes for a 32-byte message.
  */
-export function sealMac(key, message) {
-  const cipher = createCipheriv('chacha20-poly1305', key, Buffer.alloc(12), { authTagLength: TAG_BYTES });
-  const ciphertext = Buffer.concat([cipher.update(message), cipher.final()]);
-  return Buffer.concat([ciphertext, cipher.getAuthTag()]);
+export function sealMac(key, message, context = {}) {
+  return aeadSeal(key, Buffer.alloc(12), message, Buffer.alloc(0), context);
 }
 
 /**
@@ -1008,13 +1059,7 @@ export function sealMac(key, message) {
  */
 export function openMac(key, sealed) {
   if (!Buffer.isBuffer(sealed) || sealed.length <= TAG_BYTES) return null;
-  try {
-    const decipher = createDecipheriv('chacha20-poly1305', key, Buffer.alloc(12), { authTagLength: TAG_BYTES });
-    decipher.setAuthTag(sealed.subarray(sealed.length - TAG_BYTES));
-    return Buffer.concat([decipher.update(sealed.subarray(0, sealed.length - TAG_BYTES)), decipher.final()]);
-  } catch {
-    return null;
-  }
+  return aeadOpen(key, Buffer.alloc(12), sealed);
 }
 
 /** @param {Buffer} a @param {Buffer} b @returns {boolean} Constant-time comparison. */
@@ -1600,13 +1645,11 @@ export class CryptoSession {
     cipherHeader.writeUInt8(this.sendEpoch & 0xff, 1);
     cipherHeader.writeBigUInt64LE(counter, 2);
 
-    const cipher = createCipheriv('chacha20-poly1305', key, nonceFor(counter), { authTagLength: TAG_BYTES });
     // The frame's own header —kind and session —rides as additional authenticated data. That is
     // what stops an attacker retagging a DATA frame as a BYE, or moving a frame into another session:
     // the tag covers the fields the receiving channel routes on.
-    cipher.setAAD(header);
-    const ciphertext = Buffer.concat([cipher.update(frame.subarray(FRAME_HEADER_BYTES)), cipher.final()]);
-    return Buffer.concat([header, cipherHeader, ciphertext, cipher.getAuthTag()]);
+    const sealed = aeadSeal(key, nonceFor(counter), frame.subarray(FRAME_HEADER_BYTES), header);
+    return Buffer.concat([header, cipherHeader, sealed]);
   }
 
   /**
@@ -1653,16 +1696,8 @@ export class CryptoSession {
     const key = this.receiveKey(isInitiator, epoch);
     if (key === null) return fail(CRYPTO_REASON.EPOCH_TOO_FAR);
 
-    let plaintext;
-    try {
-      const decipher = createDecipheriv('chacha20-poly1305', key, nonceFor(counter), { authTagLength: TAG_BYTES });
-      decipher.setAAD(header);
-      decipher.setAuthTag(body.subarray(body.length - TAG_BYTES));
-      plaintext = Buffer.concat([
-        decipher.update(body.subarray(CIPHER_HEADER_BYTES, body.length - TAG_BYTES)),
-        decipher.final(),
-      ]);
-    } catch {
+    const plaintext = aeadOpen(key, nonceFor(counter), body.subarray(CIPHER_HEADER_BYTES), header);
+    if (plaintext === null) {
       // Authentication failed. The frame is dropped and never processed, and the tag is *not* retried
       // against the other epochs: an attacker who could make us try keys until one verified would
       // have turned a 128-bit tag into a search.

package/src/agent/transfer/ferry.mjs

@@ -0,0 +1,195 @@
+/**
+ * Artifact Ferry v1（本地最小闭环）：chunkFile → ArtifactRef → sink 接收端。
+ *
+ * 不变式：
+ *   · 控制面只持引用（ref/rootCid/size/chunkCount），字节永远在本机或 sink；
+ *   · 发送端流式分块，内存与文件大小无关；每块 SHA-256；
+ *   · 接收端逐块校验、位图持久化、可断点续传；finalize 重算根才原子落盘；
+ *   · 路径只允许 sink 根下的相对路径（拒绝绝对路径/.. /盘符/UNC）。
+ * 本阶段不做远端 P2P 拉取：`pull` 明确返回 P2P_UNAVAILABLE，绝不回落 relay blob。
+ */
+import { createHash } from 'node:crypto';
+import {
+  closeSync, existsSync, fsyncSync, ftruncateSync, mkdirSync, openSync, readdirSync, readFileSync,
+  readSync, renameSync, statSync, writeFileSync, writeSync,
+} from 'node:fs';
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+import { createManifest, chunkLengths, chunkRange } from './manifest.mjs';
+
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+const ROOT = /^sha256:[0-9a-f]{64}$/;
+const readJson = (file) => JSON.parse(readFileSync(file, 'utf8').replace(/^\uFEFF/, ''));
+
+export function safeRelative(input) {
+  if (typeof input !== 'string' || input.trim() === '') return { ok: false, code: 'PATH_REQUIRED' };
+  const raw = input.replace(/\\/g, '/');
+  if (raw.includes('\0')) return { ok: false, code: 'PATH_NUL' };
+  if (isAbsolute(input) || /^[A-Za-z]:/.test(raw) || raw.startsWith('//')) return { ok: false, code: 'PATH_ABSOLUTE' };
+  const parts = raw.split('/').filter((part) => part !== '' && part !== '.');
+  if (parts.length === 0 || parts.some((part) => part === '..')) return { ok: false, code: 'PATH_TRAVERSAL' };
+  return { ok: true, relative: parts.join('/') };
+}
+
+/** 流式分块：只读一块、算一块的哈希；返回 rootCid 与块清单。 */
+export function chunkFile(filePath, { chunkBytes = 1024 * 1024 } = {}) {
+  const stat = statSync(filePath);
+  const plan = chunkLengths(stat.size, chunkBytes);
+  if (plan.ok !== true) return plan;
+  const fd = openSync(filePath, 'r');
+  const chunks = [];
+  try {
+    for (let index = 0; index < plan.count; index += 1) {
+      const length = index === plan.count - 1 ? plan.lastChunkBytes : plan.chunkBytes;
+      const buf = Buffer.alloc(length);
+      const read = readSync(fd, buf, 0, length, index * plan.chunkBytes);
+      if (read !== length) return { ok: false, code: 'XFER_READ_SHORT' };
+      const digest = sha256(buf);
+      chunks.push({ index, cid: 'sha256:' + digest, sha256: digest, size: length });
+    }
+  } finally {
+    closeSync(fd);
+  }
+  const built = createManifest({
+    sizeBytes: stat.size,
+    chunkBytes: plan.chunkBytes,
+    chunkHashes: chunks.map((chunk) => chunk.sha256),
+    objectId: sha256(`${stat.size}:${plan.chunkBytes}:${chunks.map((c) => c.sha256).join('')}`).slice(0, 32),
+    kind: 'file',
+    sinkKind: 'cache',
+    relPath: basename(filePath),
+  });
+  if (built.ok !== true) return built;
+  return {
+    ok: true,
+    rootCid: 'sha256:' + built.manifest.root_sha256,
+    rootHex: built.manifest.root_sha256,
+    size: stat.size,
+    chunkBytes: plan.chunkBytes,
+    chunkCount: plan.count,
+    chunks,
+  };
+}
+
+/** 控制面引用：只含元数据，不含字节、块清单或路径。 */
+export function createRefV2({ rootCid, size, chunkCount, chunkBytes, originPeer, sinkHint = 'workspace://artifacts', mediaType = 'application/octet-stream', refId = null }) {
+  if (typeof rootCid !== 'string' || !ROOT.test(rootCid)) return { ok: false, code: 'ARTIFACT_ROOT_INVALID' };
+  if (!Number.isSafeInteger(size) || size < 0) return { ok: false, code: 'ARTIFACT_SIZE_INVALID' };
+  if (!Number.isSafeInteger(chunkCount) || chunkCount < 0) return { ok: false, code: 'ARTIFACT_CHUNKS_INVALID' };
+  if (!Number.isSafeInteger(chunkBytes) || chunkBytes <= 0) return { ok: false, code: 'ARTIFACT_CHUNK_SIZE_INVALID' };
+  if (typeof originPeer !== 'string' || originPeer === '') return { ok: false, code: 'ARTIFACT_ORIGIN_REQUIRED' };
+  return { ok: true, ref: { v: 2, ref: refId ?? rootCid, rootCid, size, chunkCount, chunkBytes, mediaType, originPeer, sinkHint } };
+}
+
+export function verifyRefV2(ref) {
+  if (ref === null || typeof ref !== 'object' || ref.v !== 2) return { ok: false, code: 'ARTIFACT_REF_INVALID' };
+  if (typeof ref.ref !== 'string' || ref.ref === '') return { ok: false, code: 'ARTIFACT_REF_INVALID' };
+  if (typeof ref.rootCid !== 'string' || !ROOT.test(ref.rootCid)) return { ok: false, code: 'ARTIFACT_ROOT_INVALID' };
+  if (!Number.isSafeInteger(ref.size) || ref.size < 0 || !Number.isSafeInteger(ref.chunkCount) || ref.chunkCount < 0) return { ok: false, code: 'ARTIFACT_REF_INVALID' };
+  if (typeof ref.originPeer !== 'string' || ref.originPeer === '') return { ok: false, code: 'ARTIFACT_ORIGIN_REQUIRED' };
+  return { ok: true };
+}
+
+/** 本地引用索引（控制面的本机替身；relay 发布是下一阶段接线）。 */
+export function createRefIndex({ dir }) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const fileOf = (refId) => join(dir, sha256(String(refId)) + '.json');
+  return {
+    publish(ref) {
+      const checked = verifyRefV2(ref);
+      if (checked.ok !== true) return checked;
+      const file = fileOf(ref.ref);
+      writeFileSync(file, JSON.stringify(ref), { encoding: 'utf8', mode: 0o600 });
+      return { ok: true, ref, path: file };
+    },
+    get(refId) {
+      try {
+        const ref = readJson(fileOf(refId));
+        const checked = verifyRefV2(ref);
+        return checked.ok === true ? { ok: true, ref } : checked;
+      } catch { return { ok: false, code: 'ARTIFACT_REF_NOT_FOUND' }; }
+    },
+    list() {
+      return { ok: true, refs: readdirSync(dir).filter((n) => n.endsWith('.json')).map((n) => { try { return readJson(join(dir, n)); } catch { return null; } }).filter(Boolean) };
+    },
+  };
+}
+
+/**
+ * 接收端：位图持久化 + 逐块校验 + finalize 根校验后原子落盘。
+ * @param {{stateDir:string, sinkRoot:string, ref:object, destination:string, chunkBytes?:number}} input
+ */
+export function createReceiver({ stateDir, sinkRoot, ref, destination, chunkBytes = null }) {
+  const checked = verifyRefV2(ref);
+  if (checked.ok !== true) return checked;
+  const safe = safeRelative(destination);
+  if (safe.ok !== true) return safe;
+  const root = resolve(sinkRoot);
+  const target = resolve(root, safe.relative);
+  const rel = relative(root, target);
+  if (rel === '' || rel.startsWith('..') || isAbsolute(rel) || rel.split(sep).includes('..')) return { ok: false, code: 'PATH_TRAVERSAL' };
+  const transferId = sha256(ref.ref + '|' + ref.rootCid + '|' + ref.size).slice(0, 32);
+  const dir = join(stateDir, transferId);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const bitmapPath = join(dir, 'bitmap.json');
+  const partPath = join(dir, 'data.part');
+  const chunk = Number.isInteger(chunkBytes) ? chunkBytes : ref.chunkBytes;
+  let bitmap = null;
+  if (existsSync(bitmapPath)) {
+    try { bitmap = readJson(bitmapPath); } catch { bitmap = null; }
+    if (bitmap !== null && (bitmap.rootCid !== ref.rootCid || bitmap.size !== ref.size || bitmap.chunkBytes !== chunk)) return { ok: false, code: 'XFER_SESSION_CONFLICT' };
+  }
+  if (bitmap === null) {
+    const fd = openSync(partPath, 'w+', 0o600);
+    try { ftruncateSync(fd, ref.size); } finally { closeSync(fd); }
+    bitmap = { v: 1, transferId, rootCid: ref.rootCid, size: ref.size, chunkBytes: chunk, chunkCount: ref.chunkCount, chunks: ref.chunkCount, chunk_bytes: chunk, last_chunk_bytes: ref.chunkCount === 0 ? 0 : ref.size - (ref.chunkCount - 1) * chunk, hashes: Array(ref.chunkCount).fill(null), destination: safe.relative, updatedAt: new Date().toISOString() };
+    writeFileSync(bitmapPath, JSON.stringify(bitmap), { encoding: 'utf8', mode: 0o600 });
+  }
+  const save = () => { bitmap.updatedAt = new Date().toISOString(); const tmp = bitmapPath + '.tmp-' + process.pid; writeFileSync(tmp, JSON.stringify(bitmap), { encoding: 'utf8', mode: 0o600 }); renameSync(tmp, bitmapPath); };
+  let finalized = false;
+  return {
+    ok: true,
+    transferId,
+    have() {
+      return new Set(bitmap.hashes.map((h, i) => (h === null ? null : i)).filter((i) => i !== null));
+    },
+    progress() {
+      const received = bitmap.hashes.map((h, i) => (h === null ? null : i)).filter((i) => i !== null);
+      return { total: bitmap.chunkCount, received: received.length, complete: received.length === bitmap.chunkCount, bytes: bitmap.hashes.reduce((sum, h, i) => sum + (h === null ? 0 : i === bitmap.chunkCount - 1 ? bitmap.size - i * chunk : chunk), 0) };
+    },
+    writeChunk(index, data, expectedSha256) {
+      if (finalized) return { ok: false, code: 'XFER_ALREADY_FINALIZED' };
+      const range = chunkRange(bitmap, index);
+      if (range === null) return { ok: false, code: 'XFER_CHUNK_INDEX_INVALID' };
+      const buf = Buffer.isBuffer(data) ? data : Buffer.from(data ?? '');
+      if (buf.length !== range.length) return { ok: false, code: 'XFER_CHUNK_LENGTH_INVALID', detail: { expected: range.length, got: buf.length } };
+      const digest = sha256(buf);
+      if (typeof expectedSha256 !== 'string' || expectedSha256 !== digest) return { ok: false, code: 'XFER_CHUNK_HASH_MISMATCH', retry: index };
+      if (bitmap.hashes[index] !== null && bitmap.hashes[index] !== digest) return { ok: false, code: 'XFER_CHUNK_CONFLICT' };
+      if (bitmap.hashes[index] === digest) return { ok: true, duplicate: true, index };
+      const fd = openSync(partPath, 'r+');
+      try { writeSync(fd, buf, 0, buf.length, range.offset); } finally { closeSync(fd); }
+      bitmap.hashes[index] = digest;
+      save();
+      return { ok: true, index, sha256: digest, writtenBytes: buf.length };
+    },
+    finalizeTransfer(rootCid = ref.rootCid) {
+      if (rootCid !== ref.rootCid) return { ok: false, code: 'XFER_ROOT_MISMATCH' };
+      if (bitmap.hashes.some((h) => h === null)) return { ok: false, code: 'XFER_CHUNKS_MISSING', detail: { missing: bitmap.hashes.filter((h) => h === null).length } };
+      const built = createManifest({ sizeBytes: bitmap.size, chunkBytes: bitmap.chunkBytes, chunkHashes: bitmap.hashes, objectId: transferId, kind: 'file', sinkKind: 'cache', relPath: safe.relative });
+      if (built.ok !== true) return built;
+      if ('sha256:' + built.manifest.root_sha256 !== rootCid) return { ok: false, code: 'XFER_ROOT_MISMATCH' };
+      mkdirSync(resolve(target, '..'), { recursive: true, mode: 0o700 });
+      const fd = openSync(partPath, 'r+');
+      try { fsyncSync(fd); } finally { closeSync(fd); }
+      renameSync(partPath, target);
+      finalized = true;
+      try { writeFileSync(join(dir, 'done.json'), JSON.stringify({ transferId, rootCid, size: bitmap.size, path: target, at: new Date().toISOString() }), { encoding: 'utf8', mode: 0o600 }); } catch { /* receipt is best effort */ }
+      return { ok: true, path: target, verified: true, bytes: bitmap.size, transferId };
+    },
+    /** 远端 P2P 拉取尚未接线：显式失败，不回落 relay。 */
+    async pullFrom(originPeer) {
+      return { ok: false, code: 'P2P_UNAVAILABLE', detail: { originPeer, why: 'want-block transport is a later slice; relay fallback is forbidden' } };
+    },
+  };
+}

package/src/agent/transfer/index.mjs

@@ -0,0 +1,4 @@
+export * from './manifest.mjs';
+export * from './ferry.mjs';
+export * from './publish.mjs';
+export * from './want-block.mjs';

package/src/agent/transfer/manifest.mjs

@@ -0,0 +1,92 @@
+/**
+ * 文件分块清单（C1 的最小可信底座）。
+ *
+ * 纯函数，无 I/O：给定文件大小与块大小，产出一份可独立校验的 manifest。
+ * root = SHA256("w2m-xfer-root-v1" || size || chunkBytes || 逐块 SHA256)，域分离避免
+ * 叶哈希/根哈希/不同切法互相混淆；manifest 本身不再包含明文内容。
+ */
+import { createHash } from 'node:crypto';
+
+export const XFER_VERSION = 1;
+export const DEFAULT_CHUNK_BYTES = 256 * 1024;
+export const MIN_CHUNK_BYTES = 16 * 1024;
+export const MAX_CHUNK_BYTES = 2 * 1024 * 1024;
+export const MAX_CHUNKS = 65536;
+
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+
+export function chunkLengths(sizeBytes, chunkBytes = DEFAULT_CHUNK_BYTES) {
+  if (!Number.isSafeInteger(sizeBytes) || sizeBytes < 0) return { ok: false, code: 'XFER_SIZE_INVALID' };
+  if (!Number.isSafeInteger(chunkBytes) || chunkBytes < MIN_CHUNK_BYTES || chunkBytes > MAX_CHUNK_BYTES) return { ok: false, code: 'XFER_CHUNK_SIZE_INVALID' };
+  if (sizeBytes === 0) return { ok: true, count: 0, chunkBytes, lastChunkBytes: 0 };
+  const count = Math.ceil(sizeBytes / chunkBytes);
+  if (count > MAX_CHUNKS) return { ok: false, code: 'XFER_TOO_MANY_CHUNKS', detail: { count, max: MAX_CHUNKS } };
+  return { ok: true, count, chunkBytes, lastChunkBytes: sizeBytes % chunkBytes === 0 ? chunkBytes : sizeBytes % chunkBytes };
+}
+
+export function chunkSha256(bytes) {
+  return sha256(bytes);
+}
+
+/**
+ * @param {{sizeBytes:number, chunkBytes?:number, chunkHashes:string[], objectId:string, taskId?:string|null,
+ *          machineId?:string|null, kind?:string, sinkKind?:string, relPath:string, cipherBytes?:number}} input
+ */
+export function createManifest(input) {
+  const plan = chunkLengths(input.sizeBytes, input.chunkBytes ?? DEFAULT_CHUNK_BYTES);
+  if (plan.ok !== true) return plan;
+  const hashes = Array.isArray(input.chunkHashes) ? input.chunkHashes : [];
+  if (hashes.length !== plan.count) return { ok: false, code: 'XFER_CHUNK_COUNT_MISMATCH', detail: { expected: plan.count, got: hashes.length } };
+  for (const hash of hashes) if (typeof hash !== 'string' || !/^[0-9a-f]{64}$/.test(hash)) return { ok: false, code: 'XFER_CHUNK_HASH_INVALID' };
+  const root = createHash('sha256')
+    .update('w2m-xfer-root-v1\0')
+    .update(String(input.sizeBytes) + '\0' + String(plan.chunkBytes) + '\0')
+    .update(hashes.join('\0'))
+    .digest('hex');
+  return {
+    ok: true,
+    manifest: {
+      v: XFER_VERSION,
+      object_id: input.objectId,
+      task_id: input.taskId ?? null,
+      machine_id: input.machineId ?? null,
+      kind: typeof input.kind === 'string' ? input.kind : 'stdout',
+      sink: { kind: typeof input.sinkKind === 'string' ? input.sinkKind : 'cache', rel_path: input.relPath },
+      size_bytes: input.sizeBytes,
+      chunk_bytes: plan.chunkBytes,
+      chunks: plan.count,
+      last_chunk_bytes: plan.lastChunkBytes,
+      chunk_hashes: hashes.slice(),
+      root_sha256: root,
+    },
+  };
+}
+
+export function verifyManifest(manifest) {
+  if (manifest === null || typeof manifest !== 'object') return { ok: false, code: 'XFER_MANIFEST_INVALID' };
+  if (manifest.v !== XFER_VERSION) return { ok: false, code: 'XFER_MANIFEST_VERSION' };
+  if (typeof manifest.object_id !== 'string' || !/^[0-9a-f]{32,64}$/.test(manifest.object_id)) return { ok: false, code: 'XFER_OBJECT_ID_INVALID' };
+  if (!Number.isSafeInteger(manifest.size_bytes) || manifest.size_bytes < 0) return { ok: false, code: 'XFER_SIZE_INVALID' };
+  const rebuilt = createManifest({
+    sizeBytes: manifest.size_bytes,
+    chunkBytes: manifest.chunk_bytes,
+    chunkHashes: manifest.chunk_hashes,
+    objectId: manifest.object_id,
+    taskId: manifest.task_id,
+    machineId: manifest.machine_id,
+    kind: manifest.kind,
+    sinkKind: manifest.sink?.kind,
+    relPath: manifest.sink?.rel_path,
+  });
+  if (rebuilt.ok !== true) return rebuilt;
+  if (rebuilt.manifest.root_sha256 !== manifest.root_sha256) return { ok: false, code: 'XFER_ROOT_MISMATCH' };
+  return { ok: true };
+}
+
+/** 某一块在文件中的字节偏移与长度（最后一块较短）。 */
+export function chunkRange(manifest, index) {
+  if (!Number.isInteger(index) || index < 0 || index >= manifest.chunks) return null;
+  const offset = index * manifest.chunk_bytes;
+  const length = index === manifest.chunks - 1 ? manifest.last_chunk_bytes : manifest.chunk_bytes;
+  return { offset, length };
+}

package/src/agent/transfer/object-store.mjs

@@ -0,0 +1,144 @@
+/**
+ * 分块落盘 / 读取端的最小实现（C1 + C3 共用）。
+ *
+ * 一个对象一个目录：data.part（稀疏、按 offset 写）、meta.json（原子更新）。
+ * 提交前必须：全部块到齐、逐块哈希匹配、根哈希重算一致 → fsync → rename 为 <object_id>.bin。
+ * 失败保留 data.part 以便续传；根哈希不符则隔离，不产生“半份成品”。
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import {
+  closeSync, existsSync, fsyncSync, ftruncateSync, mkdirSync, openSync, readFileSync, readSync,
+  renameSync, unlinkSync, writeFileSync, writeSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+import { createManifest, chunkLengths, chunkRange, XFER_VERSION } from './manifest.mjs';
+
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+const readJson = (file) => JSON.parse(readFileSync(file, 'utf8').replace(/^\uFEFF/, ''));
+
+export function createObjectStore({ root }) {
+  if (typeof root !== 'string' || root === '') throw new TypeError('XFER_STORE_ROOT_REQUIRED');
+  const dirOf = (objectId) => join(root, objectId);
+  const metaPath = (objectId) => join(dirOf(objectId), 'meta.json');
+  const partPath = (objectId) => join(dirOf(objectId), 'data.part');
+  const finalPath = (objectId) => join(root, objectId + '.bin');
+
+  const saveMeta = (meta) => {
+    const file = metaPath(meta.object_id);
+    const tmp = file + '.tmp-' + process.pid + '-' + randomBytes(4).toString('hex');
+    writeFileSync(tmp, JSON.stringify(meta), { encoding: 'utf8', mode: 0o600 });
+    renameSync(tmp, file);
+  };
+
+  return {
+    root,
+
+    /** 开始/恢复一个入站对象。同一 objectId 且根一致 = 续传；否则拒绝。 */
+    begin({ objectId, totalBytes, chunkBytes, rootSha256, taskId = null, machineId = null, kind = 'stdout', sinkKind = 'cache', relPath = null }) {
+      if (typeof objectId !== 'string' || !/^[0-9a-f]{32,64}$/.test(objectId)) return { ok: false, code: 'XFER_OBJECT_ID_INVALID' };
+      if (typeof rootSha256 !== 'string' || !/^[0-9a-f]{64}$/.test(rootSha256)) return { ok: false, code: 'XFER_ROOT_INVALID' };
+      const dir = dirOf(objectId);
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+      // A completed object is immutable and needs no new session.
+      if (existsSync(finalPath(objectId))) return { ok: true, resumed: false, complete: true, objectId };
+      if (existsSync(metaPath(objectId))) {
+        const meta = readJson(metaPath(objectId));
+        if (meta.root_sha256 !== rootSha256 || meta.size_bytes !== totalBytes) return { ok: false, code: 'XFER_OBJECT_CONFLICT' };
+        meta.resumed = true;
+        saveMeta(meta);
+        return { ok: true, resumed: true, complete: meta.chunk_hashes.every((h) => h !== null), objectId };
+      }
+      const plan = chunkLengths(totalBytes, chunkBytes);
+      if (plan.ok !== true) return plan;
+      const fd = openSync(partPath(objectId), 'w+', 0o600);
+      try { ftruncateSync(fd, totalBytes); } finally { closeSync(fd); }
+      const emptyRoot = createManifest({ sizeBytes: 0, chunkBytes, chunkHashes: [], objectId, taskId, machineId, kind, sinkKind, relPath: relPath ?? objectId + '.bin' }).manifest.root_sha256;
+      const meta = {
+        v: XFER_VERSION,
+        object_id: objectId,
+        task_id: taskId,
+        machine_id: machineId,
+        kind,
+        sink: { kind: sinkKind, rel_path: relPath ?? objectId + '.bin' },
+        size_bytes: totalBytes,
+        chunk_bytes: plan.chunkBytes,
+        chunks: plan.count,
+        last_chunk_bytes: plan.lastChunkBytes,
+        root_sha256: totalBytes === 0 ? emptyRoot : rootSha256,
+        root_expected: rootSha256,
+        chunk_hashes: Array(plan.count).fill(null),
+        created_at: new Date().toISOString(),
+      };
+      // 空对象直接可提交：根必须与调用方声明的根一致。
+      if (totalBytes === 0 && rootSha256 !== emptyRoot) return { ok: false, code: 'XFER_ROOT_MISMATCH' };
+      saveMeta(meta);
+      return { ok: true, resumed: false, complete: totalBytes === 0, objectId };
+    },
+
+    /** 写一块。乱序允许；同 index 同哈希幂等；冲突即终态错误。 */
+    writeChunk({ objectId, index, bytes, chunkSha256 = null }) {
+      const meta = readJson(metaPath(objectId));
+      const range = chunkRange(meta, index);
+      if (range === null) return { ok: false, code: 'XFER_CHUNK_INDEX_INVALID' };
+      const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes ?? '');
+      if (buf.length !== range.length) return { ok: false, code: 'XFER_CHUNK_LENGTH_INVALID', detail: { expected: range.length, got: buf.length } };
+      const digest = sha256(buf);
+      if (chunkSha256 !== null && chunkSha256 !== digest) return { ok: false, code: 'XFER_CHUNK_HASH_MISMATCH' };
+      if (meta.chunk_hashes[index] !== null && meta.chunk_hashes[index] !== digest) return { ok: false, code: 'XFER_CHUNK_CONFLICT' };
+      if (meta.chunk_hashes[index] === digest) return { ok: true, duplicate: true, index, sha256: digest };
+      const fd = openSync(partPath(objectId), 'r+');
+      try { writeSync(fd, buf, 0, buf.length, range.offset); } finally { closeSync(fd); }
+      meta.chunk_hashes[index] = digest;
+      saveMeta(meta);
+      return { ok: true, duplicate: false, index, sha256: digest };
+    },
+
+    /** 已完成的块索引；续传握手用。 */
+    have(objectId) {
+      if (!existsSync(metaPath(objectId))) return { ok: false, code: 'XFER_SESSION_NOT_FOUND' };
+      const meta = readJson(metaPath(objectId));
+      const have = [];
+      meta.chunk_hashes.forEach((hash, index) => { if (hash !== null) have.push(index); });
+      return { ok: true, objectId, have, complete: meta.chunk_hashes.every((h) => h !== null), chunks: meta.chunks, root_sha256: meta.root_expected };
+    },
+
+    /** 全量校验 + 提交。根不符 → 移到 quarantine 并报错（不产生成品）。 */
+    commit(objectId) {
+      const meta = readJson(metaPath(objectId));
+      if (meta.chunk_hashes.some((hash) => hash === null)) return { ok: false, code: 'XFER_CHUNKS_MISSING', detail: { missing: meta.chunk_hashes.filter((h) => h === null).length } };
+      const rebuilt = createManifest({ sizeBytes: meta.size_bytes, chunkBytes: meta.chunk_bytes, chunkHashes: meta.chunk_hashes, objectId: meta.object_id, taskId: meta.task_id, machineId: meta.machine_id, kind: meta.kind, sinkKind: meta.sink.kind, relPath: meta.sink.rel_path });
+      if (rebuilt.ok !== true) return rebuilt;
+      if (rebuilt.manifest.root_sha256 !== meta.root_expected) return { ok: false, code: 'XFER_ROOT_MISMATCH', detail: { expected: meta.root_expected, actual: rebuilt.manifest.root_sha256 } };
+      const fd = openSync(partPath(objectId), 'r+');
+      try { fsyncSync(fd); } finally { closeSync(fd); }
+      renameSync(partPath(objectId), finalPath(objectId));
+      const manifest = { ...rebuilt.manifest, committed_at: new Date().toISOString() };
+      const file = join(root, objectId + '.ref.json');
+      writeFileSync(file, JSON.stringify(manifest), { encoding: 'utf8', mode: 0o600 });
+      try { unlinkSync(metaPath(objectId)); } catch { /* already gone */ }
+      try { unlinkSync(dirOf(objectId)); } catch { /* directory removal is best effort */ }
+      return { ok: true, objectId, bytes: meta.size_bytes, sha256: rebuilt.manifest.root_sha256, path: finalPath(objectId), manifest };
+    },
+
+    /** 读一块并校验；损坏返回 XFER_CHUNK_HASH_MISMATCH，绝不返回坏字节。 */
+    readChunk({ objectId, index }) {
+      const manifestPath = join(root, objectId + '.ref.json');
+      if (!existsSync(manifestPath)) return { ok: false, code: 'XFER_OBJECT_NOT_FOUND' };
+      const manifest = readJson(manifestPath);
+      const range = chunkRange(manifest, index);
+      if (range === null) return { ok: false, code: 'XFER_CHUNK_INDEX_INVALID' };
+      const buf = Buffer.alloc(range.length);
+      const fd = openSync(finalPath(objectId), 'r');
+      try { const read = readSync(fd, buf, 0, range.length, range.offset); if (read !== range.length) return { ok: false, code: 'XFER_READ_SHORT' }; } finally { closeSync(fd); }
+      if (sha256(buf) !== manifest.chunk_hashes[index]) return { ok: false, code: 'XFER_CHUNK_HASH_MISMATCH' };
+      return { ok: true, bytes: buf, index, sha256: manifest.chunk_hashes[index] };
+    },
+
+    has(objectId) {
+      if (existsSync(join(root, objectId + '.ref.json'))) return { ok: true, complete: true, bytes: readJson(join(root, objectId + '.ref.json')).size_bytes };
+      if (existsSync(metaPath(objectId))) { const have = this.have(objectId); return { ok: true, complete: false, received: have.have ?? [], chunks: have.chunks ?? null }; }
+      return { ok: false, code: 'XFER_OBJECT_NOT_FOUND' };
+    },
+  };
+}

package/src/agent/transfer/publish.mjs

@@ -0,0 +1,76 @@
+/**
+ * C2：ArtifactRef 的控制面发布（复用 relay 现有项目决策通道，不新增存储、不传字节）。
+ *
+ * 发布体 = { title:"artifact.available", kind:"artifact_available", text: JSON(ref) }；
+ * relay 只记录这条元数据，字节永远在本机对象库/sink。读取端按 title 过滤并校验 ref。
+ * 该通道在 relay 2.0.5 已存在（POST/GET /v1/projects/:id/decisions），无需新路由即可先跑通。
+ */
+import { verifyRefV2 } from './ferry.mjs';
+
+const TITLE = 'artifact.available';
+const KIND = 'artifact_available';
+
+function baseOf(url) {
+  if (typeof url !== 'string' || url.trim() === '') return null;
+  return url.trim().replace(/\/+$/, '');
+}
+
+/**
+ * @param {{relayUrl:string, token:string, projectId?:string, ref:object, fetchImpl?:Function, signal?:AbortSignal}} input
+ */
+export async function publishRef(input) {
+  const base = baseOf(input?.relayUrl);
+  if (base === null) return { ok: false, code: 'RELAY_URL_REQUIRED' };
+  if (typeof input?.token !== 'string' || input.token === '') return { ok: false, code: 'OPERATOR_TOKEN_REQUIRED' };
+  const checked = verifyRefV2(input?.ref);
+  if (checked.ok !== true) return checked;
+  const projectId = typeof input.projectId === 'string' && input.projectId !== '' ? input.projectId : 'default';
+  const fetchImpl = typeof input.fetchImpl === 'function' ? input.fetchImpl : globalThis.fetch;
+  const body = { title: TITLE, kind: KIND, text: JSON.stringify(checked.ok ? input.ref : null), refs: { rootCid: input.ref.rootCid, originPeer: input.ref.originPeer } };
+  let response = null;
+  try {
+    response = await fetchImpl(base + '/v1/projects/' + encodeURIComponent(projectId) + '/decisions', {
+      method: 'POST',
+      headers: { authorization: 'Bearer ' + input.token, 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify(body),
+      signal: input.signal,
+    });
+  } catch {
+    return { ok: false, code: 'RELAY_UNREACHABLE' };
+  }
+  let json = null;
+  try { json = await response.json(); } catch { json = null; }
+  if (response.ok !== true) return { ok: false, code: 'RELAY_REFUSED', detail: { status: response.status, error: json?.error?.code ?? null } };
+  if (json?.ok !== true) return { ok: false, code: 'RELAY_REFUSED', detail: { status: response.status } };
+  return { ok: true, decision: json.decision ?? null, ref: input.ref };
+}
+
+/**
+ * @param {{relayUrl:string, token:string, projectId?:string, fetchImpl?:Function, signal?:AbortSignal}} input
+ */
+export async function listPublishedRefs(input) {
+  const base = baseOf(input?.relayUrl);
+  if (base === null) return { ok: false, code: 'RELAY_URL_REQUIRED' };
+  if (typeof input?.token !== 'string' || input.token === '') return { ok: false, code: 'DEVICE_TOKEN_REQUIRED' };
+  const projectId = typeof input.projectId === 'string' && input.projectId !== '' ? input.projectId : 'default';
+  const fetchImpl = typeof input.fetchImpl === 'function' ? input.fetchImpl : globalThis.fetch;
+  let response = null;
+  try {
+    response = await fetchImpl(base + '/v1/projects/' + encodeURIComponent(projectId) + '/decisions', { headers: { authorization: 'Bearer ' + input.token, accept: 'application/json' }, signal: input.signal });
+  } catch {
+    return { ok: false, code: 'RELAY_UNREACHABLE' };
+  }
+  let json = null;
+  try { json = await response.json(); } catch { json = null; }
+  if (response.ok !== true) return { ok: false, code: 'RELAY_REFUSED', detail: { status: response.status } };
+  const decisions = Array.isArray(json?.decisions) ? json.decisions : [];
+  const refs = [];
+  for (const decision of decisions) {
+    if (decision?.title !== TITLE || decision?.kind !== KIND) continue;
+    let ref = null;
+    try { ref = JSON.parse(String(decision.text ?? '')); } catch { continue; }
+    if (verifyRefV2(ref).ok !== true) continue;
+    refs.push(ref);
+  }
+  return { ok: true, refs };
+}