@uuaid/pillar 0.2.0-alpha.13 → 0.2.0-alpha.17

package/src/pillar.mjs

@@ -19,10 +19,14 @@ import { CID } from "multiformats/cid";
 import * as raw from "multiformats/codecs/raw";
 import { sha256 } from "multiformats/hashes/sha2";
 import { createTransport, PILLAR_PROTOCOL, uuaidToDhtKey, peerIdFromEd25519Hex } from "./net/transport.mjs";
-import { seal, open, decrypt, envelopeSha, ENVELOPE_VERSION } from "./net/envelope.mjs";
+import { seal, open, decrypt, envelopeSha, mkEnvelopeId, ENVELOPE_VERSION } from "./net/envelope.mjs";
 import { Mailbox } from "./mailbox/mailbox.mjs";
 import { CarrierClient } from "./net/carrier-client.mjs";
 import { Observability } from "./observability.mjs";
+import {
+  BLOB_KIND, MAX_INLINE_BODY_BYTES, BlobError, BlobSizeError, envelopeBodyBytes, preflightBodyBytes,
+  prepareBlobSend, fetchAndDecryptBlob, prepareBrokerBlobSend, fetchBrokerBlob,
+} from "./blob/blob.mjs";
 
 const VALUE_STORE_PREFIX = "/uuaid/1.0";
 
@@ -41,6 +45,10 @@ export class Pillar {
     trust = null, // { policy, allow, block } from loadTrustPolicy(); null = open
     tierGrant = null, // signed grant object (tier.mjs) sent with carrier delivers
     metrics = null, // Observability instance; a default is created internally
+    blobStore = null, // BlobStore (src/blob/store.mjs) for the blob transport
+    blobBroker = null, // challenge broker for blob reserve/finalize/redeem
+    blobClient = null, // PillarBlobHttpClient for the production S3 broker path
+    senderKeyCheck = null, // registry-active gate: (uuaid, pubkeyHex) => status
   }) {
     if (!keychain?._identity) throw new Error("Pillar: keychain must be loaded before construction");
     this.keychain = keychain;
@@ -58,6 +66,12 @@ export class Pillar {
     this.node = null;
     this.trust = trust;
     this.metrics = metrics ?? new Observability();
+    this.blobStore = blobStore;
+    this.blobBroker = blobBroker;
+    this.blobClient = blobClient;
+    this.blobTier = tierGrant?.tier ?? "community";
+    this.blobMaxBodyBytes = Number.isInteger(tierGrant?.maxBodyBytes) ? tierGrant.maxBodyBytes : null;
+    this.senderKeyCheck = senderKeyCheck;
     this._envelopeHandlers = new Set();
     this._openStreams = new Map(); // peerIdString -> pushable
   }
@@ -240,7 +254,7 @@ export class Pillar {
    * fleet deployment we bypass DHT via the address book which is populated
    * once at fleet-up time.
    */
-  async send({ recipient, recipientPublicKey, kind = "message", payload = {}, resolveTimeoutMs = 5000 }) {
+  async send({ recipient, recipientPublicKey, kind = "message", payload = {}, envelopeId = null, resolveTimeoutMs = 5000 }) {
     if (!this.node && !this.carrierClient) {
       this.metrics.inc("send.error.not-started");
       throw new Error("pillar not started");
@@ -265,7 +279,12 @@ export class Pillar {
       throw new Error(`send: no public key known for ${recipient} — encryption is mandatory; register the peer (address book / fleet.json) or pass recipientPublicKey`);
     }
 
-    const envelope = seal(this.keychain, { recipient, recipientPublicKey: pubkey, kind, payload });
+    const envelope = seal(this.keychain, { recipient, recipientPublicKey: pubkey, kind, payload, id: envelopeId ?? undefined });
+    const hardCap = preflightBodyBytes(envelopeBodyBytes(envelope), { maxBodyBytes: MAX_INLINE_BODY_BYTES });
+    if (!hardCap.ok) {
+      this.metrics.inc("send.error.direct-cap");
+      throw new BlobSizeError(`envelope ${hardCap.bytes}B exceeds the ${MAX_INLINE_BODY_BYTES}B hard cap`, { size: hardCap.bytes, max: MAX_INLINE_BODY_BYTES });
+    }
     const persisted = this.mailbox.appendOutbound(envelope);
 
     // 1. Address book path: direct libp2p dial (lowest latency, no third party).
@@ -343,6 +362,66 @@ export class Pillar {
     return { group, results };
   }
 
+  /**
+   * Blob send — the oversized-payload path.  Explicit flow (blob.mjs header):
+   * broker reserve -> local AES-256-GCM encrypt (fresh DEK + nonce, AAD bound
+   * to this envelope) -> store upload -> broker finalize -> seal a kind
+   * "blob-ref" envelope carrying the signed ref (DEK inside the sealed
+   * payload, never in metadata) -> deliver.
+   *
+   * Preflight is exact: the placeholder-free body is measured against the
+   * tier inline limit and the 2 MiB direct hard cap BEFORE any store or
+   * broker call.  The envelope id is generated first so the GCM AAD can bind
+   * the ciphertext to it.
+   */
+  async sendBlob({ recipient, recipientPublicKey, kind = BLOB_KIND, data, ttlMs, resolveTimeoutMs = 5000 }) {
+    if (!this.blobClient && !this.blobStore) throw new BlobError("no-store", "sendBlob: configure blobClient or blobStore on the Pillar");
+    const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    // Reserve an envelope id so the blob ciphertext is AAD-bound to it.
+    const envelopeId = mkEnvelopeId();
+    const placeholder = { blobRef: { v: 1, envelopeId } };
+    // Seal a disposable probe before any broker/S3 side effect. Besides sizing,
+    // this enforces recipient UUAID ↔ public-key binding up front.
+    const probe = seal(this.keychain, { recipient, recipientPublicKey, kind, payload: placeholder, id: envelopeId });
+    const pf = preflightBodyBytes(envelopeBodyBytes(probe), { tier: this.blobTier, maxBodyBytes: this.blobMaxBodyBytes });
+    if (!pf.ok) {
+      this.metrics.inc(`sendBlob.preflight.${pf.source}`);
+      throw new BlobError("blob-too-large", `sendBlob: placeholder body ${pf.bytes}B exceeds ${pf.source} limit ${pf.limit}B`);
+    }
+    const prepared = this.blobClient
+      ? await prepareBrokerBlobSend(this.keychain, { data: buf, envelopeId, recipient, ttlMs, client: this.blobClient })
+      : await prepareBlobSend(this.keychain, {
+        data: buf, envelopeId, recipient, ttlMs,
+        store: this.blobStore, broker: this.blobBroker,
+      });
+    const r = await this.send({
+      recipient, recipientPublicKey, kind,
+      payload: { blobRef: prepared.ref }, envelopeId, resolveTimeoutMs,
+    });
+    this.metrics.inc("sendBlob.ok");
+    return { ...r, blob: { object: prepared.object, hash: prepared.hash, size: prepared.size, metadata: prepared.metadata } };
+  }
+
+  /**
+   * Redeem a blob-ref from an inbound payload — fetch + hash-check +
+   * single-use broker redemption + AES-256-GCM decrypt with the ref's DEK.
+   * The registry-active sender key gate runs BEFORE the broker redemption
+   * burns.  Returns { data, object, hash, size }.
+   */
+  async receiveBlob(payload, { envelopeId = null, now = Date.now() } = {}) {
+    const ref = payload?.blobRef;
+    if (!ref) throw new BlobError("blob-ref-invalid", "receiveBlob: payload carries no blobRef");
+    if (!this.blobClient && !this.blobStore) throw new BlobError("no-store", "receiveBlob: configure blobClient or blobStore on the Pillar");
+    const r = this.blobClient
+      ? await fetchBrokerBlob({ ref, envelopeId, recipient: this.uuaid, now, client: this.blobClient })
+      : await fetchAndDecryptBlob({
+        ref, store: this.blobStore, envelopeId, now,
+        broker: this.blobBroker, senderKeyCheck: this.senderKeyCheck,
+      });
+    this.metrics.inc("receiveBlob.ok");
+    return r;
+  }
+
   /**
    * Start pulling our inbox from every configured carrier.  Received envelopes
    * flow through the same verification + mailbox + handler pipeline as
@@ -400,6 +479,10 @@ export class Pillar {
   }
 
   async _deliverToPeer(envelope, peerIdStr, multiaddrStr) {
+    const bytes = envelopeBodyBytes(envelope);
+    if (bytes > MAX_INLINE_BODY_BYTES) {
+      throw new BlobSizeError(`direct envelope ${bytes}B exceeds the ${MAX_INLINE_BODY_BYTES}B hard cap`, { size: bytes, max: MAX_INLINE_BODY_BYTES });
+    }
     const { peerIdFromString } = await import("@libp2p/peer-id");
     const { multiaddr } = await import("@multiformats/multiaddr");
     const peerId = peerIdFromString(peerIdStr);
@@ -444,6 +527,10 @@ export class Pillar {
     const pubkey = recipientPublicKey ?? this.addressBook?.get(recipient)?.publicKey;
     if (!pubkey) throw new Error(`sendDirect: no public key for ${recipient} — encryption is mandatory`);
     const envelope = seal(this.keychain, { recipient, recipientPublicKey: pubkey, kind, payload });
+    const bytes = envelopeBodyBytes(envelope);
+    if (bytes > MAX_INLINE_BODY_BYTES) {
+      throw new BlobSizeError(`direct envelope ${bytes}B exceeds the ${MAX_INLINE_BODY_BYTES}B hard cap`, { size: bytes, max: MAX_INLINE_BODY_BYTES });
+    }
     this.mailbox.appendOutbound(envelope);
     const { peerIdFromString } = await import("@libp2p/peer-id");
     const { multiaddr } = await import("@multiformats/multiaddr");
@@ -465,8 +552,14 @@ export class Pillar {
   async _handleStream(stream, connection) {
     try {
       let buf = "";
+      let receivedBytes = 0;
       for await (const chunk of stream) {
         const bytes = chunk?.subarray ? chunk.subarray() : chunk;
+        receivedBytes += bytes.byteLength ?? bytes.length;
+        if (receivedBytes > MAX_INLINE_BODY_BYTES + 1) {
+          this.metrics.inc("received.rejected.direct-cap");
+          throw new BlobSizeError(`incoming direct envelope exceeds the ${MAX_INLINE_BODY_BYTES}B hard cap`, { size: receivedBytes, max: MAX_INLINE_BODY_BYTES });
+        }
         buf += u8ToString(bytes);
         const newlineIdx = buf.indexOf("\n");
         if (newlineIdx < 0) continue;