reploid 0.0.0-stage → 0.1.1

package/packages/reploid/src/artifacts/custody/runtime.js

@@ -0,0 +1,404 @@
+/** Reusable artifact custody behavior. The host supplies policy, protocol and execution ports. */
+export { createCustodyExchange } from './exchange.js';
+export function createCustodyContracts(ports) {
+  const { hashDopplerEvidence, validateExecutablePack, executablePacksMatch, sha256Hex, signCanonical, verifyCanonicalSignature } = ports;
+  for (const name of ["hashDopplerEvidence","validateExecutablePack","executablePacksMatch","sha256Hex","signCanonical","verifyCanonicalSignature"]) {
+    if (ports[name] === undefined) throw new TypeError('Missing createCustodyContracts port: ' + name);
+  }
+/**
+ * Peer-only dependency transport for Doppler's artifactStore port.
+ * authorization is an authenticated requester/control-plane input, never a peer advert.
+ * Its indexDigest pins chunk commitments to the exact Pack closure. Doppler still
+ * owns Pack signature verification, final artifact verification, and verified caching.
+ */
+
+
+
+const PREFIX = 'reploid.pool.pack-custody';
+const digest = (value) => /^sha256:[0-9a-f]{64}$/.test(value);
+const positive = (value) => Number.isSafeInteger(value) && value > 0;
+const clone = (value) => structuredClone(value);
+const assert = (condition, message) => { if (!condition) throw new Error(`Pack custody: ${message}`); };
+const unsigned = ({ signature, ...body }) => body;
+const sign = async (body, key) => ({ ...body, signature: await signCanonical(body, key, { domain: body.schema }) });
+const verify = async (message, key, schema) => {
+  assert(message?.schema === schema, 'unexpected message schema');
+  assert(await verifyCanonicalSignature(unsigned(message), key, message.signature, { domain: schema }), 'invalid signature');
+};
+
+async function context(authorization, index) {
+  const grant = clone(authorization);
+  const manifest = clone(index);
+  const artifactSet = grant?.schema === `${PREFIX}-authorization/v2`;
+  assert(artifactSet || grant?.schema === `${PREFIX}-authorization/v1`, 'authorization is required');
+  if (artifactSet) {
+    assert(grant.artifactSet?.schema === 'reploid.pool.artifact-set/v1' && digest(grant.artifactSet.identity)
+      && Array.isArray(grant.artifactSet.artifacts) && grant.artifactSet.artifacts.length > 0
+      && grant.pack === undefined && grant.envelopeArtifact === undefined, 'exact artifact set required');
+  } else {
+    const validation = validateExecutablePack(grant.pack);
+    assert(validation.ok, validation.reasons.join('; '));
+    assert(await hashDopplerEvidence(grant.pack.artifacts) === grant.pack.artifactClosureDigest, 'closure mismatch');
+  }
+  assert(positive(grant.attempt) && typeof grant.transferId === 'string' && grant.transferId, 'transfer identity required');
+  assert(Number.isSafeInteger(grant.expiresAt), 'expiry required');
+  assert(grant.requester?.peerId && grant.requester.publicKey, 'requester identity required');
+  assert(Array.isArray(grant.suppliers) && grant.suppliers.length, 'authorized suppliers required');
+  const peers = new Map();
+  for (const peer of grant.suppliers) {
+    assert(peer.peerId && peer.publicKey && !peers.has(peer.peerId), 'invalid or duplicate supplier');
+    peers.set(peer.peerId, peer.publicKey);
+  }
+  for (const field of ['maxArtifactBytes', 'maxChunkBytes', 'maxTransferBytes', 'requestTimeoutMs']) {
+    assert(positive(grant.limits?.[field]), `explicit ${field} required`);
+  }
+  assert(grant.limits.requestTimeoutMs <= 2147483647, 'request timeout out of range');
+  assert(digest(grant.indexDigest) && await hashDopplerEvidence(manifest) === grant.indexDigest, 'unauthorized chunk index');
+  if (artifactSet) assert(manifest.schema === `${PREFIX}-index/v2`
+    && manifest.artifactSetIdentity === grant.artifactSet.identity, 'index artifact set mismatch');
+  else assert(manifest.schema === `${PREFIX}-index/v1`
+    && manifest.envelopeDigest === grant.pack.envelopeDigest
+    && manifest.artifactClosureDigest === grant.pack.artifactClosureDigest, 'index Pack mismatch');
+  const declaredArtifacts = [...(artifactSet ? grant.artifactSet.artifacts : grant.pack.artifacts)];
+  if (grant.envelopeArtifact !== undefined) {
+    const envelope = grant.envelopeArtifact;
+    assert(envelope?.role === 'pack-envelope' && typeof envelope.artifactId === 'string' && envelope.artifactId
+      && typeof envelope.path === 'string' && envelope.path && digest(envelope.hash) && positive(envelope.sizeBytes)
+      && !declaredArtifacts.some((artifact) => artifact.artifactId === envelope.artifactId), 'invalid authorized Pack envelope');
+    declaredArtifacts.push(envelope);
+  }
+  assert(Array.isArray(manifest.artifacts) && manifest.artifacts.length === declaredArtifacts.length, 'index does not close Pack');
+  const artifacts = new Map();
+  for (const artifact of declaredArtifacts) {
+    assert(typeof artifact.artifactId === 'string' && artifact.artifactId.length > 0 && !artifacts.has(artifact.artifactId)
+      && typeof artifact.path === 'string' && artifact.path.length > 0 && typeof artifact.role === 'string'
+      && digest(artifact.hash) && positive(artifact.sizeBytes), 'invalid or duplicate artifact identity');
+    const entry = manifest.artifacts.find((item) => item.artifactId === artifact.artifactId);
+    assert(entry && entry.hash === artifact.hash && entry.sizeBytes === artifact.sizeBytes, 'index artifact mismatch');
+    assert(artifact.sizeBytes <= grant.limits.maxArtifactBytes && Array.isArray(entry.chunks), 'artifact limit or chunks invalid');
+    let offset = 0;
+    for (const [index, chunk] of entry.chunks.entries()) {
+      assert(chunk.index === index && chunk.offset === offset && positive(chunk.sizeBytes)
+        && chunk.sizeBytes <= grant.limits.maxChunkBytes && digest(chunk.hash), 'invalid chunk geometry or commitment');
+      offset += chunk.sizeBytes;
+      assert(Number.isSafeInteger(offset) && offset <= artifact.sizeBytes, 'chunk range outside artifact');
+    }
+    assert(offset === artifact.sizeBytes, 'incomplete chunk index');
+    artifacts.set(artifact.artifactId, { artifact, chunks: entry.chunks });
+  }
+  return { grant, peers, artifacts, authorizationHash: await hashDopplerEvidence(grant) };
+}
+
+function checkInventory(inventory, ctx, now) {
+  assert(inventory.authorizationHash === ctx.authorizationHash && ctx.peers.has(inventory.peerId), 'unauthorized inventory');
+  assert(Number.isSafeInteger(inventory.expiresAt) && inventory.expiresAt > now
+    && inventory.expiresAt <= ctx.grant.expiresAt, 'expired inventory');
+  assert(positive(inventory.maxBytes) && inventory.maxBytes <= ctx.grant.limits.maxTransferBytes, 'inventory byte limit invalid');
+  assert(Array.isArray(inventory.artifacts), 'inventory artifacts required');
+  const ids = new Set();
+  for (const entry of inventory.artifacts) {
+    const declared = ctx.artifacts.get(entry.artifactId);
+    assert(declared && !ids.has(entry.artifactId) && Array.isArray(entry.chunkIndexes), 'inventory artifact invalid');
+    ids.add(entry.artifactId);
+    assert(new Set(entry.chunkIndexes).size === entry.chunkIndexes.length
+      && entry.chunkIndexes.every((index) => Number.isSafeInteger(index) && index >= 0 && declared.chunks[index]), 'inventory chunks invalid');
+  }
+}
+
+function checkRequest(request, ctx, inventory, now) {
+  checkInventory(inventory, ctx, now);
+  const grant = ctx.grant;
+  assert(request.authorizationHash === ctx.authorizationHash && request.transferId === grant.transferId
+    && request.attempt === grant.attempt && request.requesterPeerId === grant.requester.peerId
+    && request.supplierPeerId === inventory.peerId && typeof request.nonce === 'string' && request.nonce, 'request binding mismatch');
+  const chunk = ctx.artifacts.get(request.artifactId)?.chunks[request.chunkIndex];
+  assert(chunk && Number.isSafeInteger(request.chunkIndex) && chunk.offset === request.offset
+    && chunk.sizeBytes === request.sizeBytes, 'request range mismatch');
+  assert(inventory.artifacts.some((entry) => entry.artifactId === request.artifactId
+    && entry.chunkIndexes.includes(request.chunkIndex)), 'chunk not advertised');
+  return chunk;
+}
+
+async function createPeerPackSupplier({ authorization, index, peerId, privateKey, inventory, readChunk, now = Date.now }) {
+  const inventorySnapshot = clone(inventory);
+  const ctx = await context(authorization, index);
+  assert(typeof readChunk === 'function', 'readChunk port required');
+  const advert = { ...inventorySnapshot, schema: `${PREFIX}-inventory/v1`, authorizationHash: ctx.authorizationHash, peerId };
+  checkInventory(advert, ctx, now());
+  const signedInventory = await sign(advert, privateKey);
+  await verify(signedInventory, ctx.peers.get(peerId), advert.schema);
+  let reservedBytes = 0;
+  let closed = false;
+  return {
+    inventory: clone(signedInventory),
+    close() { closed = true; },
+    async serve(message) {
+      const request = clone(message);
+      assert(!closed, 'supplier closed');
+      const chunk = checkRequest(request, ctx, advert, now());
+      await verify(request, ctx.grant.requester.publicKey, `${PREFIX}-request/v1`);
+      assert(!closed, 'supplier closed');
+      checkRequest(request, ctx, advert, now());
+      assert(reservedBytes + chunk.sizeBytes <= advert.maxBytes, 'supplier byte budget exhausted');
+      reservedBytes += chunk.sizeBytes;
+      const source = await readChunk(request.artifactId, clone(chunk));
+      assert(source instanceof Uint8Array && source.byteLength === chunk.sizeBytes, 'supplier chunk size mismatch');
+      const bytes = Uint8Array.from(source);
+      const bytesHash = await sha256Hex(bytes);
+      assert(bytesHash === chunk.hash, 'supplier chunk integrity mismatch');
+      const body = await sign({ schema: `${PREFIX}-response/v1`, authorizationHash: ctx.authorizationHash,
+        peerId, requestHash: await hashDopplerEvidence(unsigned(request)), bytesHash }, privateKey);
+      assert(!closed, 'supplier closed');
+      checkRequest(request, ctx, advert, now());
+      return { message: body, bytes };
+    }
+  };
+}
+
+// A deadline is enforced here even when a transport ignores its AbortSignal.
+async function boundedTransfer(requestChunk, peerId, request, signal, timeoutMs) {
+  const controller = new AbortController();
+  let timer;
+  let abort;
+  try {
+    return await new Promise((resolve, reject) => {
+      abort = () => { controller.abort(); reject(new Error('Pack custody: transfer cancelled')); };
+      signal.addEventListener('abort', abort, { once: true });
+      if (signal.aborted) return abort();
+      timer = setTimeout(() => { controller.abort(); reject(new Error('Pack custody: supplier timeout')); }, timeoutMs);
+      Promise.resolve().then(() => {
+        assert(!controller.signal.aborted, 'transfer cancelled');
+        // The transport must enforce this bound while receiving/framing bytes.
+        return requestChunk(peerId, request, { signal: controller.signal, maxBytes: request.sizeBytes });
+      }).then(resolve, reject);
+    });
+  } finally {
+    clearTimeout(timer);
+    signal.removeEventListener('abort', abort);
+    controller.abort();
+  }
+}
+
+async function createPeerPackArtifactStore({ authorization, index, inventories, requesterPrivateKey, requestChunk, now = Date.now, signal, checkpoints = null, maxConcurrentChunks = 1 }) {
+  const adverts = clone(inventories);
+  const ctx = await context(authorization, index);
+  assert(typeof requestChunk === 'function', 'peer transport required');
+  assert(positive(maxConcurrentChunks) && maxConcurrentChunks <= (ctx.grant.limits.maxConcurrentChunks ?? 1), 'chunk concurrency exceeds authorization');
+  if (checkpoints) assert(['getChunk', 'putChunk', 'deleteChunk'].every((name) => typeof checkpoints[name] === 'function'), 'checkpoint ports required');
+  assert(Array.isArray(adverts), 'inventories required');
+  const seen = new Set();
+  for (const advert of adverts) {
+    checkInventory(advert, ctx, now());
+    assert(!seen.has(advert.peerId), 'duplicate supplier inventory');
+    seen.add(advert.peerId);
+    await verify(advert, ctx.peers.get(advert.peerId), `${PREFIX}-inventory/v1`);
+  }
+  const controller = new AbortController();
+  const cancel = () => controller.abort();
+  signal?.addEventListener('abort', cancel, { once: true });
+  if (signal?.aborted) cancel();
+  const active = () => {
+    assert(!controller.signal.aborted, 'store closed or cancelled');
+    assert(ctx.grant.expiresAt > now(), 'authorization expired');
+    assert(receivedBytes <= ctx.grant.limits.maxTransferBytes, 'received byte budget exceeded');
+  };
+  const attempts = [];
+  const completed = [];
+  const peerBytes = new Map();
+  let reservedBytes = 0;
+  let receivedBytes = 0;
+  let verificationBytes = 0;
+  const startedAt = now();
+  let cacheBytes = 0;
+  let corruptCacheBytes = 0;
+  let persistedBytes = 0;
+  let evictedBytes = 0;
+  let duplicateBytes = 0;
+  let inFlightBytes = 0;
+  let peakInFlightBytes = 0;
+  let peakArtifactBytes = 0;
+  let firstArtifactAt = null;
+  const receivedHashes = new Set();
+  const pending = new Map();
+  // Only one artifact allocation at a time; its chunks use the authorized fanout.
+  let tail = Promise.resolve();
+  async function acquire(input) {
+    active();
+    const entry = ctx.artifacts.get(input?.artifactId);
+    assert(entry && executablePacksMatch(entry.artifact, input), 'artifact outside authorized closure');
+    const output = new Uint8Array(entry.artifact.sizeBytes);
+    peakArtifactBytes = Math.max(peakArtifactBytes, output.length);
+    const acquisition = new AbortController();
+    const cancelAcquisition = () => acquisition.abort();
+    controller.signal.addEventListener('abort', cancelAcquisition, { once: true });
+    const current = () => { active(); assert(!acquisition.signal.aborted, 'artifact acquisition cancelled'); };
+    async function acquireChunk(chunk) {
+      current();
+      if (checkpoints) {
+        const restored = await checkpoints.getChunk(clone(chunk), { signal: acquisition.signal });
+        current();
+        if (restored !== null) {
+          assert(restored instanceof Uint8Array, 'checkpoint returned invalid bytes');
+          const cached = restored.slice();
+          verificationBytes += cached.byteLength;
+          if (cached instanceof Uint8Array && cached.byteLength === chunk.sizeBytes && await sha256Hex(cached) === chunk.hash) {
+            current();
+            output.set(cached, chunk.offset);
+            cacheBytes += cached.byteLength;
+            return;
+          }
+          corruptCacheBytes += cached.byteLength;
+          await checkpoints.deleteChunk(clone(chunk), { signal: acquisition.signal });
+          current();
+        }
+      }
+      const suppliers = adverts.filter((advert) => advert.artifacts.some((item) => item.artifactId === input.artifactId
+        && item.chunkIndexes.includes(chunk.index)));
+      let received = false;
+      let tried = 0;
+      let undelivered = 0;
+      for (const advert of suppliers) {
+        current();
+        if (advert.expiresAt <= now() || (peerBytes.get(advert.peerId) || 0) + chunk.sizeBytes > advert.maxBytes) continue;
+        assert(reservedBytes + chunk.sizeBytes <= ctx.grant.limits.maxTransferBytes, 'transfer byte budget exhausted');
+        reservedBytes += chunk.sizeBytes;
+        peerBytes.set(advert.peerId, (peerBytes.get(advert.peerId) || 0) + chunk.sizeBytes);
+        const observation = { peerId: advert.peerId, artifactId: input.artifactId, chunkIndex: chunk.index,
+          reservedBytes: chunk.sizeBytes, receivedBytes: 0, status: 'pending', requestHash: null };
+        attempts.push(observation);
+        tried += 1;
+        let delivered = false;
+        try {
+          const request = await sign({ schema: `${PREFIX}-request/v1`, authorizationHash: ctx.authorizationHash,
+            transferId: ctx.grant.transferId, attempt: ctx.grant.attempt, requesterPeerId: ctx.grant.requester.peerId,
+            supplierPeerId: advert.peerId, artifactId: input.artifactId, chunkIndex: chunk.index,
+            offset: chunk.offset, sizeBytes: chunk.sizeBytes, nonce: crypto.randomUUID() }, requesterPrivateKey);
+          observation.requestHash = await hashDopplerEvidence(unsigned(request));
+          observation.request = clone(request);
+          active();
+          checkInventory(advert, ctx, now());
+          current();
+          inFlightBytes += chunk.sizeBytes;
+          peakInFlightBytes = Math.max(peakInFlightBytes, inFlightBytes);
+          let response;
+          try {
+            response = await boundedTransfer(requestChunk, advert.peerId, request, acquisition.signal,
+              Math.min(ctx.grant.limits.requestTimeoutMs, advert.expiresAt - now(), ctx.grant.expiresAt - now()));
+          } finally { inFlightBytes -= chunk.sizeBytes; }
+          delivered = true;
+          observation.receivedBytes = response?.bytes instanceof Uint8Array ? response.bytes.byteLength : 0;
+          receivedBytes += observation.receivedBytes;
+          assert(response?.bytes instanceof Uint8Array && response.bytes.byteLength === chunk.sizeBytes, 'response size mismatch');
+          const bytes = Uint8Array.from(response.bytes);
+          const message = clone(response.message);
+          observation.response = message;
+          active();
+          checkInventory(advert, ctx, now());
+          await verify(message, ctx.peers.get(advert.peerId), `${PREFIX}-response/v1`);
+          assert(message.authorizationHash === ctx.authorizationHash && message.peerId === advert.peerId
+            && message.requestHash === observation.requestHash && message.bytesHash === chunk.hash, 'response binding mismatch');
+          verificationBytes += bytes.byteLength;
+          observation.observedBytesHash = await sha256Hex(bytes);
+          assert(observation.observedBytesHash === chunk.hash, 'chunk integrity mismatch');
+          active();
+          checkInventory(advert, ctx, now());
+          current();
+          if (receivedHashes.has(chunk.hash)) duplicateBytes += bytes.length;
+          receivedHashes.add(chunk.hash);
+          if (checkpoints) {
+            // Storage failures are visible; verified output remains usable and does
+            // not trigger an unnecessary download from another supplier.
+            try {
+              const saved = await checkpoints.putChunk(clone(chunk), bytes.slice(), { signal: acquisition.signal });
+              persistedBytes += bytes.length;
+              evictedBytes += saved?.evictedBytes || 0;
+            } catch (error) { observation.checkpointError = String(error.message || error); }
+            current();
+          }
+          output.set(bytes, chunk.offset);
+          observation.status = 'accepted';
+          received = true;
+          break;
+        } catch (error) {
+          observation.status = 'rejected';
+          observation.error = String(error.message || error);
+          if (!delivered) undelivered += 1;
+          current();
+        }
+      }
+      if (!received) {
+        const error = new Error(`Pack custody: no authorized supplier completed ${input.artifactId} chunk ${chunk.index}`);
+        // No supplier delivered bytes (a stall, a disconnect or a refusal), so nothing invalid
+        // arrived and a later grant may resume from the verified checkpoints.
+        if (tried > 0 && undelivered === tried) error.code = 'CUSTODY_SUPPLIER_UNAVAILABLE';
+        throw error;
+      }
+    }
+    let nextChunk = 0;
+    let failure = null;
+    try {
+      await Promise.all(Array.from({ length: Math.min(maxConcurrentChunks, entry.chunks.length) }, async () => {
+        try {
+          while (nextChunk < entry.chunks.length) {
+            current();
+            const chunk = entry.chunks[nextChunk++];
+            await acquireChunk(chunk);
+          }
+        } catch (error) { failure ||= error; acquisition.abort(); }
+      }));
+      if (failure) throw failure;
+      current();
+    } finally {
+      controller.signal.removeEventListener('abort', cancelAcquisition);
+      acquisition.abort();
+    }
+    verificationBytes += output.byteLength;
+    assert(await sha256Hex(output) === entry.artifact.hash, 'reconstructed artifact integrity mismatch');
+    active();
+    firstArtifactAt ??= now();
+    if (!completed.some((item) => item.artifactId === input.artifactId)) {
+      completed.push({ artifactId: input.artifactId, hash: entry.artifact.hash, sizeBytes: output.byteLength });
+    }
+    return output;
+  }
+  return {
+    readEnvelope() {
+      assert(ctx.grant.envelopeArtifact, 'no Pack envelope authorized');
+      return this.readArtifact(ctx.grant.envelopeArtifact);
+    },
+    readArtifact(artifact) {
+      const snapshot = clone(artifact);
+      const key = JSON.stringify(snapshot);
+      if (pending.has(key)) return pending.get(key).then((bytes) => bytes.slice());
+      const task = tail.then(() => acquire(snapshot));
+      pending.set(key, task);
+      tail = task.catch(() => {}).finally(() => pending.delete(key));
+      return task.then((bytes) => bytes.slice());
+    },
+    close() { cancel(); signal?.removeEventListener('abort', cancel); },
+    getReceipt() {
+      return clone({ schema: `${PREFIX}-receipt/v1`, authorizationHash: ctx.authorizationHash,
+        transferId: ctx.grant.transferId, attempt: ctx.grant.attempt,
+        ...(ctx.grant.artifactSet ? { artifactSetIdentity: ctx.grant.artifactSet.identity }
+          : { envelopeDigest: ctx.grant.pack.envelopeDigest, artifactClosureDigest: ctx.grant.pack.artifactClosureDigest }),
+        indexDigest: ctx.grant.indexDigest,
+        source: cacheBytes > 0 ? (receivedBytes > 0 ? 'cache-and-peer' : 'cache') : 'peer',
+        reservedBytes, receivedBytes, verificationBytes, attempts, completed,
+        inventories: adverts,
+        cacheBytes, corruptCacheBytes, persistedBytes, evictedBytes, duplicateBytes,
+        maxConcurrentChunks, peakInFlightBytes, peakArtifactBytes,
+        firstArtifactMs: firstArtifactAt === null ? null : firstArtifactAt - startedAt,
+        elapsedMs: now() - startedAt,
+        // Retained payload accounting is not a measurement of the browser's heap.
+        browserHeapBytes: null,
+        // Transport framing, interrupted partial bytes, and relay traffic require
+        // measurements from the transport owner. Never report unknown costs as zero.
+        wireBytes: null, relayBytes: null, interruptedBytes: null });
+    }
+  };
+}
+
+  return Object.freeze({ createPeerPackSupplier, createPeerPackArtifactStore });
+}
+
+export { createPieceAcquisition } from './piece-acquisition.js';

package/packages/reploid/src/artifacts/custody/supply-budget.js

@@ -0,0 +1,19 @@
+/** Shared record validation; hosts provide the atomic durable transaction. */
+export function custodyBudgetError(code, message, cause) {
+  return Object.assign(new Error(message, { cause }), { code: 'CUSTODY_BUDGET_' + code });
+}
+export function reserveCustodyBudget(record, bytes, maxBytes, purpose = 'supply') {
+  if (!['supply', 'acquisition'].includes(purpose)) throw custodyBudgetError('INVALID', 'Unknown transfer allowance purpose');
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0 || !Number.isSafeInteger(bytes) || bytes < 0) {
+    throw custodyBudgetError('INVALID', 'Invalid file contribution allowance');
+  }
+  if (!record) throw custodyBudgetError('MISSING', 'File contribution ledger missing; previous allowance cannot be inferred');
+  if (record.schema !== `reploid.custody-${purpose}-budget/v1` || !Number.isSafeInteger(record.maxBytes)
+    || record.maxBytes <= 0 || !Number.isSafeInteger(record.reservedBytes)
+    || record.reservedBytes < 0 || record.reservedBytes > record.maxBytes) {
+    throw custodyBudgetError('CORRUPT', 'File contribution ledger is corrupt');
+  }
+  if (record.maxBytes !== maxBytes) throw custodyBudgetError('POLICY', 'File contribution allowance changed; renewal is not authorized');
+  if (bytes > maxBytes - record.reservedBytes) throw custodyBudgetError('LIMIT', 'File contribution allowance exhausted');
+  return { ...record, reservedBytes: record.reservedBytes + bytes };
+}

package/packages/reploid/src/artifacts/custody-certificate.js

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview Custody-key certificates.
+ *
+ * Custody signing keys are created fresh for each host process, so a
+ * delivery receipt or challenge answer signed with one names no device. The
+ * device's persistent participant identity signs a short-lived certificate
+ * over the process's custody public key and the custody peer id it uses in
+ * grants. A verifier holding the device registration can then attribute the
+ * key: certificate, then device, then account. Uncertified keys stay
+ * unattributable. WebCrypto only, so any host can sign.
+ */
+
+import { importPublicKey } from './signatures.js';
+import { participantIdFor, signAsParticipant, verifyParticipantSignature } from './participant-proofs.js';
+
+export const CUSTODY_CERTIFICATE_SCHEMA = 'reploid.custody-key-certificate/v1';
+
+/** The lifetime a native host signs; each verifier enforces its own explicit maximum. */
+export const CUSTODY_CERTIFICATE_LIFETIME_MS = 60 * 60_000;
+
+const BODY_KEYS = Object.freeze(['schema', 'certificateId', 'participantId', 'custodyPeerId', 'custodyPublicKey', 'issuedAt', 'expiresAt']);
+const CERTIFICATE_KEYS = Object.freeze([...BODY_KEYS, 'signature'].sort());
+const ID = /^[A-Za-z0-9][A-Za-z0-9_.:@+-]{0,159}$/;
+const toMs = (value) => (typeof value === 'string' ? Date.parse(value) : Number.NaN);
+
+export const custodyCertificateBody = (certificate) => Object.fromEntries(BODY_KEYS.map((key) => [key, certificate[key]]));
+
+/** Sign a certificate for `custodyPublicKey` (base64 SPKI) with the participant identity bundle. */
+export async function createCustodyKeyCertificate({
+  identity, custodyPeerId, custodyPublicKey, issuedAtMs, lifetimeMs, certificateId = `cert_${crypto.randomUUID()}`
+}) {
+  const participantId = await participantIdFor(identity?.publicJwk);
+  if (!identity?.privateJwk || identity.peerId !== participantId) throw new TypeError('A valid persistent participant identity is required');
+  if (!ID.test(String(custodyPeerId)) || typeof custodyPublicKey !== 'string') throw new TypeError('custodyPeerId and custodyPublicKey are required');
+  if (!Number.isSafeInteger(issuedAtMs) || !Number.isSafeInteger(lifetimeMs) || lifetimeMs <= 0) throw new TypeError('issuedAtMs and a positive lifetimeMs are required');
+  const body = {
+    schema: CUSTODY_CERTIFICATE_SCHEMA,
+    certificateId,
+    participantId,
+    custodyPeerId,
+    custodyPublicKey,
+    issuedAt: new Date(issuedAtMs).toISOString(),
+    expiresAt: new Date(issuedAtMs + lifetimeMs).toISOString()
+  };
+  return { ...body, signature: await signAsParticipant(identity, CUSTODY_CERTIFICATE_SCHEMA, body) };
+}
+
+/** Lifetime and validity-window problems at `atMs`; the signature is not checked. */
+export function certificateWindowProblems({ issuedAt, expiresAt }, { atMs, maxLifetimeMs, maxClockSkewMs }) {
+  const issued = toMs(issuedAt);
+  const expires = toMs(expiresAt);
+  const problems = [];
+  if (!(expires - issued <= maxLifetimeMs)) problems.push('certificate_lifetime_exceeded');
+  if (!(atMs >= issued - maxClockSkewMs)) problems.push('certificate_not_yet_valid');
+  if (!(atMs < expires)) problems.push('certificate_expired');
+  return problems;
+}
+
+/**
+ * Problems with `certificate` as a statement by the participant key
+ * `publicJwk` covering time `atMs`; an empty list means valid. Malformed
+ * certificates return one problem without checking further.
+ */
+export async function checkCustodyKeyCertificate(certificate, { publicJwk, atMs, maxLifetimeMs, maxClockSkewMs }) {
+  if (!certificate || typeof certificate !== 'object' || Array.isArray(certificate)
+    || Object.keys(certificate).sort().join('\u0000') !== CERTIFICATE_KEYS.join('\u0000')) return ['certificate_malformed'];
+  const { schema, certificateId, participantId, custodyPeerId, custodyPublicKey, issuedAt, expiresAt, signature } = certificate;
+  const issued = toMs(issuedAt);
+  const expires = toMs(expiresAt);
+  if (schema !== CUSTODY_CERTIFICATE_SCHEMA || !ID.test(String(certificateId)) || !ID.test(String(custodyPeerId))
+    || typeof participantId !== 'string' || typeof custodyPublicKey !== 'string' || custodyPublicKey.length > 512
+    || !Number.isFinite(issued) || !Number.isFinite(expires) || expires <= issued) return ['certificate_malformed'];
+  try {
+    await importPublicKey(custodyPublicKey);
+  } catch {
+    return ['certificate_malformed'];
+  }
+  const problems = certificateWindowProblems(certificate, { atMs, maxLifetimeMs, maxClockSkewMs });
+  if (participantId !== await participantIdFor(publicJwk)) {
+    problems.push('certificate_participant_mismatch');
+  } else if (!await verifyParticipantSignature(publicJwk, CUSTODY_CERTIFICATE_SCHEMA, custodyCertificateBody(certificate), signature)) {
+    problems.push('certificate_signature_invalid');
+  }
+  return problems;
+}
+
+/**
+ * Host side: certify the process's custody key with the persistent identity,
+ * reusing the current certificate until half its lifetime remains.
+ * `onIssue(certificate)` observes each newly signed certificate.
+ */
+export function createCustodyKeyCertifier({
+  identity, lifetimeMs = CUSTODY_CERTIFICATE_LIFETIME_MS, now = () => Date.now(), onIssue = () => {}
+}) {
+  let current = null;
+  let queue = Promise.resolve();
+  const fresh = ({ custodyPeerId, custodyPublicKey }) => current !== null
+    && current.custodyPeerId === custodyPeerId && current.custodyPublicKey === custodyPublicKey
+    && toMs(current.expiresAt) - now() > lifetimeMs / 2;
+  return Object.freeze({
+    certify(key) {
+      if (fresh(key)) return Promise.resolve(current);
+      const run = queue.then(async () => {
+        if (fresh(key)) return current;
+        current = await createCustodyKeyCertificate({ identity, ...key, issuedAtMs: now(), lifetimeMs });
+        onIssue(current);
+        return current;
+      });
+      queue = run.catch(() => {});
+      return run;
+    }
+  });
+}
+
+export default {
+  CUSTODY_CERTIFICATE_SCHEMA,
+  CUSTODY_CERTIFICATE_LIFETIME_MS,
+  custodyCertificateBody,
+  createCustodyKeyCertificate,
+  certificateWindowProblems,
+  checkCustodyKeyCertificate,
+  createCustodyKeyCertifier
+};

package/packages/reploid/src/artifacts/delivery-attestation.js

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview Custody delivery attestations.
+ *
+ * After a verified acquisition, the acquirer signs the exact custody receipt
+ * with the custody key its grant names. The statement says the bytes arrived
+ * and verified; supplier-held records cannot say that. A verifier attributes
+ * the custody key to a participant only through that participant's custody
+ * certificate, so an uncertified host's attestation names no one and hosts
+ * without an identity sign none. `hash` is the evidence digest the custody
+ * records use (canonical JSON, sha256), supplied by the caller so signer and
+ * verifier share one function. WebCrypto only.
+ */
+
+import { sha256Hex, signCanonical } from './signatures.js';
+
+export const DELIVERY_ATTESTATION_SCHEMA = 'reploid.custody-delivery-attestation/v1';
+
+/** The statement an acquirer signs over one completed receipt. */
+export async function deliveryAttestationBody({ receipt, attestedAt, hash }) {
+  return {
+    schema: DELIVERY_ATTESTATION_SCHEMA,
+    authorizationHash: receipt.authorizationHash,
+    transferId: receipt.transferId,
+    receiptDigest: await hash(receipt),
+    completed: receipt.completed,
+    attestedAt
+  };
+}
+
+/** Sign the attestation with the acquirer's custody private key (ECDSA P-256 CryptoKey). */
+export async function signDeliveryAttestation({ receipt, attestedAt, privateKey, hash }) {
+  const body = await deliveryAttestationBody({ receipt, attestedAt, hash });
+  return { ...body, signature: await signCanonical(body, privateKey, { domain: DELIVERY_ATTESTATION_SCHEMA }) };
+}
+
+/** One identifier per delivered artifact of one grant; the supplier derives it from its own grant. */
+export async function deliveryEvidenceId({ authorizationHash, artifactId }) {
+  return `dlv_${(await sha256Hex(`${authorizationHash}|${artifactId}`)).slice(7, 39)}`;
+}
+
+/**
+ * The delivery evidence a certified acquirer submits for one artifact of a
+ * requester record from the custody exchange; null without an attestation.
+ */
+export function deliveryEvidenceFromRecord(record, artifactId = record?.authorization?.artifactSet?.artifacts?.[0]?.artifactId) {
+  if (record?.role !== 'requester' || !record.attestation || !record.certificates?.requester || typeof artifactId !== 'string') return null;
+  return structuredClone({
+    artifactId,
+    authorization: record.authorization,
+    index: record.index,
+    receipt: record.receipt,
+    attestation: record.attestation,
+    supplierCertificate: record.certificates.supplier,
+    acquirerCertificate: record.certificates.requester
+  });
+}
+
+export default {
+  DELIVERY_ATTESTATION_SCHEMA,
+  deliveryAttestationBody,
+  signDeliveryAttestation,
+  deliveryEvidenceId,
+  deliveryEvidenceFromRecord
+};

package/packages/reploid/src/artifacts/generation-terminal.js

@@ -0,0 +1,36 @@
+/** Provider-signed cleanup evidence. It carries no invented token measurements. */
+import { canonicalize } from './canonical-json.js';
+import { createPeerIdFromPublicJwk, importSigningKey, importVerificationKey, getIdentitySignAlgorithm,
+  encodeBytes, toBase64Url, fromBase64Url } from './identity.js';
+
+const digest = value => typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value);
+const text = value => typeof value === 'string' && value.length > 0 && value.length <= 512;
+const assert = (ok, message) => { if (!ok) throw Error(message); };
+function payload(value) {
+  assert(value?.schema === 'reploid.generation-terminal/v1' && ['cancelled', 'failed'].includes(value.status)
+    && value.cleanup === 'settled' && value.usage === null && ['requestId', 'provider', 'consumer', 'model'].every(key => text(value[key]))
+    && digest(value.modelIdentity) && digest(value.inputDigest) && Array.isArray(value.adapterIdentities)
+    && value.adapterIdentities.length <= 1 && value.adapterIdentities.every(digest)
+    && Number.isSafeInteger(value.timestamp) && value.timestamp > 0, 'Invalid generation terminal evidence');
+  return { schema: value.schema, requestId: value.requestId, provider: value.provider, consumer: value.consumer,
+    model: value.model, modelIdentity: value.modelIdentity, adapterIdentities: [...value.adapterIdentities],
+    inputDigest: value.inputDigest, status: value.status, cleanup: value.cleanup, usage: null, timestamp: value.timestamp };
+}
+const bytes = value => encodeBytes(canonicalize(payload(value)));
+export async function signGenerationTerminal(binding, status, identity) {
+  const value = payload({ ...structuredClone(binding), schema: 'reploid.generation-terminal/v1', status,
+    cleanup: 'settled', usage: null, timestamp: Date.now() });
+  assert(value.provider === identity.peerId, 'Terminal signer differs from provider');
+  return { ...value, publicJwk: identity.publicJwk, signature: toBase64Url(await crypto.subtle.sign(
+    getIdentitySignAlgorithm(identity), await importSigningKey(identity), bytes(value))) };
+}
+export async function verifyGenerationTerminal(value, binding) {
+  try {
+    const canonical = payload(value);
+    if (await createPeerIdFromPublicJwk(value.publicJwk) !== canonical.provider
+      || ['requestId', 'provider', 'consumer', 'model', 'modelIdentity', 'adapterIdentities', 'inputDigest']
+        .some(key => canonicalize(canonical[key]) !== canonicalize(binding[key]))) return false;
+    return await crypto.subtle.verify(getIdentitySignAlgorithm(value.publicJwk), await importVerificationKey(value.publicJwk),
+      fromBase64Url(value.signature), bytes(canonical));
+  } catch { return false; }
+}