@uuaid/pillar 0.2.0-alpha.10 → 0.2.0-alpha.12

package/bin/pillar-responder.mjs

@@ -38,11 +38,16 @@ import { argv, exit } from "node:process";
 import { spawn } from "node:child_process";
 import { Keychain } from "../src/identity/keychain.mjs";
 import { Pillar } from "../src/pillar.mjs";
+import { loadTrustPolicy, evaluateTrust, POLICIES } from "../src/identity/trust.mjs";
+import { loadFleetAddressBook } from "../src/address-book.mjs";
 
 const DEFAULT_REPLY = "pillar-responder: request acked — owner will respond through the normal channel";
+const STRANGER_REPLY = "pillar-responder: request received. This responder runs its command hook only for enrolled senders; ask the operator to `pillar trust allow` your uuaid.";
 const MAX_REPLY_BYTES = 8192;
 const HOOK_TIMEOUT_MS = 60_000;
 const REPLAY_WINDOW_MS = 24 * 3600_000;
+const SENDER_REPLIES_PER_HOUR = 30; // amplification cap: max hook/reply cycles per sender
+const RATE_WINDOW_MS = 3600_000;
 
 function parseArgs(argv) {
   const args = { _: [] };
@@ -162,6 +167,26 @@ if (!carriers.length && !enableLibp2p) {
 
 const replyText = args["reply-text"] ?? rcfg.replyText ?? DEFAULT_REPLY;
 const hookCmd = args.command ?? rcfg.command ?? null;
+// Trust gate. Default policy for the COMMAND HOOK is "directory": strangers
+// still get ack + a fixed reply (universality preserved — first contact
+// works), but attacker-controlled JSON only reaches the hook process from
+// senders the operator knows. --hook-policy open restores old behavior.
+const trust = loadTrustPolicy(home);
+const hookPolicy = args["hook-policy"] ?? rcfg.hookPolicy ?? "directory";
+if (!POLICIES.includes(hookPolicy)) {
+  console.error(`--hook-policy must be one of ${POLICIES.join("|")}`);
+  exit(2);
+}
+const senderRate = new Map(); // sender uuaid -> [ms timestamps]
+function senderAllowed(sender) {
+  const now = Date.now();
+  let arr = senderRate.get(sender);
+  if (!arr) { arr = []; senderRate.set(sender, arr); }
+  while (arr.length && now - arr[0] > RATE_WINDOW_MS) arr.shift();
+  if (arr.length >= SENDER_REPLIES_PER_HOUR) return false;
+  arr.push(now);
+  return true;
+}
 const hookTimeoutMs = Number(args["timeout-ms"] ?? rcfg.timeoutMs ?? HOOK_TIMEOUT_MS);
 const hookMaxBytes = Number(args["max-reply-bytes"] ?? MAX_REPLY_BYTES);
 const fwd = args["forward-to"] || rcfg.forwardTo?.uuaid
@@ -187,10 +212,14 @@ const p = new Pillar({
 
 await p.start();
 
+// Address book feeds the "directory" hook policy (known senders = fleet.json).
+const abCount = loadFleetAddressBook(join(home, "fleet.json"), p);
+
 console.log(`pillar-responder up — ${p.uuaid}`);
 console.log(`  pubkey:    ${p.publicKeyHex}`);
 console.log(`  carriers:  ${carriers.length ? carriers.join(", ") : "(none — libp2p only)"}`);
 console.log(`  reply:     ${hookCmd ? `hook ${hookCmd}` : "builtin text"}`);
+if (hookCmd) console.log(`  hook gate: policy=${hookPolicy}, known senders=${abCount}, cap=${SENDER_REPLIES_PER_HOUR}/h per sender`);
 if (fwd) console.log(`  forwardTo: ${fwd.uuaid}`);
 
 // Replay journaled-but-unfinished requests first (at-least-once).
@@ -215,7 +244,21 @@ p.onEnvelope(async (env) => {
     const thread = env.payload?.thread ?? env.id;
     let status = "ok";
     let text = replyText;
-    if (hookCmd) {
+    // Amplification cap: over-budget senders get ack only, no reply/hook.
+    if (!senderAllowed(env.sender)) {
+      await p.send({ recipient: env.sender, recipientPublicKey: senderKey, kind: "ack", payload: { inReplyTo: env.id } });
+      journalDone(home, env.id, { text: "(rate-capped: ack only)", status: "capped" });
+      console.log(`  ${env.sender.slice(-8)} request ${env.id.slice(0, 16)}… → ack only (rate cap)`);
+      return;
+    }
+    // Hook gate: strangers get the fixed reply, never the command hook.
+    const gate = evaluateTrust({ ...trust, policy: hookPolicy }, env.sender, new Set(p.addressBook?.keys() ?? []));
+    if (gate.reason === "blocked") {
+      journalDone(home, env.id, { text: "(blocked sender: dropped)", status: "blocked" });
+      console.log(`  ${env.sender.slice(-8)} request ${env.id.slice(0, 16)}… → dropped (blocked)`);
+      return;
+    }
+    if (hookCmd && gate.deliver) {
       const r = await runHook(hookCmd, {
         id: env.id,
         sender: env.sender,
@@ -229,6 +272,8 @@ p.onEnvelope(async (env) => {
         status = "error";
         text = r.reason;
       }
+    } else if (hookCmd && !gate.deliver) {
+      text = STRANGER_REPLY; // stranger: fixed reply, hook never sees the payload
     }
     await p.send({ recipient: env.sender, recipientPublicKey: senderKey, kind: "ack", payload: { inReplyTo: env.id } });
     const replyPayload = { thread, inReplyTo: env.id, status, text };

package/bin/pillar.mjs

@@ -9,6 +9,8 @@
  *   pillar recv  [--home ~/.pillar] [--follow]   listen for envelopes and print them
  *   pillar inbox [--home ~/.pillar] [--unread] [--notify CMD] [--mark-read]
  *                                                one-shot: pull pending mail, print, exit
+ *   pillar trust [set|allow|block|unlist|quarantine]   recipient consent policy
+ *   pillar tier  [issue|install|verify]          signed volume/size tier grants
  *   pillar peers                                 list currently connected peers
  *
  * All commands respect --home to point at an alternate pillar directory,
@@ -21,6 +23,7 @@ import { argv, exit } from "node:process";
 import { Keychain } from "../src/identity/keychain.mjs";
 import { Pillar } from "../src/pillar.mjs";
 import { loadFleetAddressBook } from "../src/address-book.mjs";
+import { loadTrustPolicy, POLICIES } from "../src/identity/trust.mjs";
 
 function parseArgs(argv) {
   const args = { _: [] };
@@ -60,6 +63,19 @@ function loadPillar(args) {
   const carriers = args.carrier
     ? [args.carrier]
     : (process.env.PILLAR_CARRIERS ? process.env.PILLAR_CARRIERS.split(",") : (cfg.carriers ?? []));
+  // Trust gate: --policy overrides trust.json's policy for this invocation.
+  const trust = loadTrustPolicy(home);
+  if (args.policy) {
+    if (!POLICIES.includes(args.policy)) {
+      console.error(`--policy must be one of ${POLICIES.join("|")}`);
+      exit(2);
+    }
+    trust.policy = args.policy;
+  }
+  // Tier grant: <home>/tier-grant.json (issued via `pillar tier issue`) is
+  // attached to carrier delivers — raises budgets at carriers trusting the issuer.
+  const tgPath = join(home, "tier-grant.json");
+  const tierGrant = existsSync(tgPath) ? JSON.parse(readFileSync(tgPath, "utf-8")) : null;
   return new Pillar({
     keychain: kc,
     mailboxPath: mbPath,
@@ -69,6 +85,8 @@ function loadPillar(args) {
     dhtClientMode: cfg.dhtClientMode ?? true,
     carriers,
     enableLibp2p: !(args["carrier-only"] || cfg.carrierOnly === true),
+    trust,
+    tierGrant,
   });
 }
 
@@ -414,6 +432,9 @@ async function cmdInbox(args) {
   const fresh = [];
   p.onEnvelope((env) => { fresh.push(env); });
   await p.start();
+  // Address book BEFORE the drain: the trust "directory" policy needs known
+  // senders loaded, or every fresh envelope counts as a stranger.
+  loadFleetAddressBook(fleetPath(args), p);
   const pulled = await p.drainCarrierInbox();
   for (const env of fresh) {
     console.log(JSON.stringify({ new: true, id: env.id, from: env.sender, kind: env.kind, at: env.createdAt, payload: env.payload }));
@@ -430,7 +451,8 @@ async function cmdInbox(args) {
       console.log(JSON.stringify({ new: false, id: env.id, from: env.sender, kind: env.kind, at: env.createdAt, payload }));
     }
   }
-  console.log(`inbox: ${pulled} new, ${backlog.length} older unread${args.unread ? "" : " (--unread to print)"}`);
+  const qCount = (p.mailbox.inboxQuarantined?.(500) ?? []).length;
+  console.log(`inbox: ${fresh.length} new, ${backlog.length} older unread${args.unread ? "" : " (--unread to print)"}${qCount ? `, ${qCount} quarantined (pillar trust quarantine)` : ""}`);
   if (args["mark-read"]) {
     for (const env of fresh) p.mailbox.markInboxRead?.(env.id);
     if (args.unread) for (const row of backlog) p.mailbox.markInboxRead?.(row.envelope_id);
@@ -449,6 +471,144 @@ async function cmdInbox(args) {
   exit(0);
 }
 
+async function cmdTrust(args) {
+  // pillar trust                          show policy + lists + quarantine count
+  // pillar trust set <open|directory|allowlist>
+  // pillar trust allow|block <uuaid>      add to list (removes from the other)
+  // pillar trust unlist <uuaid>           remove from both lists
+  // pillar trust quarantine [--release ID]  list quarantined mail / release one
+  const home = homePath(args);
+  const tPath = join(home, "trust.json");
+  const t = loadTrustPolicy(home);
+  const sub = args._[1];
+  const save = () => writeFileSync(tPath, JSON.stringify({ policy: t.policy, allow: t.allow, block: t.block }, null, 2));
+  if (!sub) {
+    console.log(`policy: ${t.policy}${t.exists ? "" : " (no trust.json — default)"}`);
+    console.log(`allow (${t.allow.length}):`); for (const u of t.allow) console.log(`  ${u}`);
+    console.log(`block (${t.block.length}):`); for (const u of t.block) console.log(`  ${u}`);
+    const { Mailbox } = await import("../src/mailbox/mailbox.mjs");
+    const mb = new Mailbox(join(home, "mailbox.db"));
+    const q = mb.inboxQuarantined(500);
+    console.log(`quarantined: ${q.length} (pillar trust quarantine to list)`);
+    mb.close();
+    return;
+  }
+  if (sub === "set") {
+    const pol = args._[2];
+    if (!POLICIES.includes(pol)) { console.error(`usage: pillar trust set <${POLICIES.join("|")}>`); exit(2); }
+    t.policy = pol; save();
+    console.log(`policy: ${pol} (${tPath})`);
+    return;
+  }
+  if (sub === "allow" || sub === "block") {
+    const u = args._[2];
+    if (!u?.startsWith("uuaid:")) { console.error(`usage: pillar trust ${sub} <uuaid:...>`); exit(2); }
+    t.allow = t.allow.filter(x => x !== u);
+    t.block = t.block.filter(x => x !== u);
+    t[sub === "allow" ? "allow" : "block"].push(u);
+    save();
+    console.log(`${sub}: ${u}`);
+    return;
+  }
+  if (sub === "unlist") {
+    const u = args._[2];
+    t.allow = t.allow.filter(x => x !== u);
+    t.block = t.block.filter(x => x !== u);
+    save();
+    console.log(`unlisted: ${u}`);
+    return;
+  }
+  if (sub === "quarantine") {
+    const { Mailbox } = await import("../src/mailbox/mailbox.mjs");
+    const mb = new Mailbox(join(home, "mailbox.db"));
+    if (args.release) {
+      mb.db.prepare("update inbox set quarantined = null where envelope_id = ?").run(args.release);
+      console.log(`released: ${args.release} (now visible to pillar inbox --unread)`);
+      mb.close();
+      return;
+    }
+    for (const row of mb.inboxQuarantined(500)) {
+      console.log(JSON.stringify({ id: row.envelope_id, from: row.sender, reason: row.quarantined, at: row.received_at }));
+    }
+    mb.close();
+    return;
+  }
+  console.error("usage: pillar trust [set <policy>|allow <uuaid>|block <uuaid>|unlist <uuaid>|quarantine [--release ID]]");
+  exit(2);
+}
+
+async function cmdTier(args) {
+  // pillar tier                                    show installed grant
+  // pillar tier issue <uuaid> <tier> [--expires ISO] [--rate N] [--max-body N] [--out FILE]
+  //                                                sign a grant with THIS home's key (issuer)
+  // pillar tier install <grant.json>               install a received grant into this home
+  // pillar tier verify <grant.json> --issuer HEX   verify signature/expiry locally
+  const { makeTierGrant, verifyTierGrant, grantFingerprint, TIER_DEFAULTS } =
+    await import("../src/identity/tier.mjs");
+  const home = homePath(args);
+  const sub = args._[1];
+  if (!sub) {
+    const tgPath = join(home, "tier-grant.json");
+    if (!existsSync(tgPath)) { console.log("no tier grant installed (community tier)"); return; }
+    const g = JSON.parse(readFileSync(tgPath, "utf-8"));
+    console.log(`tier: ${g.tier}  rate: ${g.envelopesPerMin}/min  maxBody: ${g.maxBodyBytes}B`);
+    console.log(`subject: ${g.uuaid}`);
+    console.log(`issuer:  ${g.issuer}`);
+    console.log(`expires: ${g.expires}  fingerprint: ${grantFingerprint(g)}`);
+    return;
+  }
+  if (sub === "issue") {
+    const [, , uuaid, tier] = args._;
+    if (!uuaid || !TIER_DEFAULTS[tier]) {
+      console.error(`usage: pillar tier issue <uuaid:...> <${Object.keys(TIER_DEFAULTS).join("|")}> [--expires ISO] [--rate N] [--max-body BYTES] [--out FILE]`);
+      exit(2);
+    }
+    const kc = new Keychain(join(home, "keychain.json"));
+    kc.load({ passphrase: process.env.PILLAR_PASSPHRASE ?? "" });
+    const expires = args.expires ?? new Date(Date.now() + 365 * 86400_000).toISOString();
+    const grant = makeTierGrant(kc, {
+      uuaid, tier, expires,
+      envelopesPerMin: args.rate ? Number(args.rate) : undefined,
+      maxBodyBytes: args["max-body"] ? Number(args["max-body"]) : undefined,
+    });
+    const out = typeof args.out === "string" ? args.out : `tier-grant-${grantFingerprint(grant)}.json`;
+    writeFileSync(out, JSON.stringify(grant, null, 2));
+    console.log(`issued ${tier} grant for ${uuaid}`);
+    console.log(`  rate ${grant.envelopesPerMin}/min, maxBody ${grant.maxBodyBytes}B, expires ${expires}`);
+    console.log(`  issuer ${grant.issuer}`);
+    console.log(`  -> ${out} (send to the grantee; they run: pillar tier install ${out})`);
+    return;
+  }
+  if (sub === "install") {
+    const file = args._[2];
+    if (!file || !existsSync(file)) { console.error("usage: pillar tier install <grant.json>"); exit(2); }
+    const g = JSON.parse(readFileSync(file, "utf-8"));
+    const kc = new Keychain(join(home, "keychain.json"));
+    kc.load({ passphrase: process.env.PILLAR_PASSPHRASE ?? "" });
+    if (g.uuaid !== kc._identity.uuaid) {
+      console.error(`grant subject ${g.uuaid} != this home's identity ${kc._identity.uuaid}`);
+      exit(1);
+    }
+    const v = verifyTierGrant(g, [g.issuer]); // structural check (sig by named issuer, expiry, ceilings)
+    if (!v.ok) { console.error(`grant invalid: ${v.reason}`); exit(1); }
+    writeFileSync(join(home, "tier-grant.json"), JSON.stringify(g, null, 2));
+    console.log(`installed ${g.tier} grant (fingerprint ${grantFingerprint(g)}) — sent with every carrier deliver`);
+    console.log(`note: budgets rise only at carriers that trust issuer ${g.issuer.slice(0, 16)}…`);
+    return;
+  }
+  if (sub === "verify") {
+    const file = args._[2];
+    const issuer = args.issuer;
+    if (!file || !existsSync(file) || !issuer) { console.error("usage: pillar tier verify <grant.json> --issuer HEX"); exit(2); }
+    const g = JSON.parse(readFileSync(file, "utf-8"));
+    const v = verifyTierGrant(g, [String(issuer)]);
+    console.log(v.ok ? `VALID: ${g.tier} for ${g.uuaid} until ${g.expires}` : `INVALID: ${v.reason}`);
+    exit(v.ok ? 0 : 1);
+  }
+  console.error("usage: pillar tier [issue|install|verify]");
+  exit(2);
+}
+
 async function cmdPeers(args) {
   const p = loadPillar(args);
   await p.start();
@@ -469,9 +629,11 @@ async function main() {
     case "groups": return cmdGroups(args);
     case "recv":  return cmdRecv(args);
     case "inbox": return cmdInbox(args);
+    case "trust": return cmdTrust(args);
+    case "tier":  return cmdTier(args);
     case "peers": return cmdPeers(args);
     default:
-      console.error(`usage: pillar <init|id|send|send-group|groups|recv|inbox|peers> [--home DIR]`);
+      console.error(`usage: pillar <init|id|send|send-group|groups|recv|inbox|trust|tier|peers> [--home DIR]`);
       exit(2);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uuaid/pillar",
-  "version": "0.2.0-alpha.10",
+  "version": "0.2.0-alpha.12",
   "description": "Pillar (Protocol for Inter-agent Linked Ledger And Relay) — the secure delivery layer of UACP, the Universal Agent Communication Protocol. UACP = UUAID (identity) + Envelope (signed, encrypted container) + Pillar (relay, mailbox, routing, store-and-forward). IAASO-3050 reference implementation: one command to mint an identity and join the network.",
   "license": "Apache-2.0",
   "type": "module",
@@ -10,10 +10,18 @@
     "pillar-carrier": "bin/carrier.mjs",
     "pillar-ask": "bin/pillar-ask.mjs",
     "pillar-responder": "bin/pillar-responder.mjs",
-    "pillar-seed": "bin/pillar-seed.mjs"
+    "pillar-seed": "bin/pillar-seed.mjs",
+    "pillar-escrow": "bin/pillar-escrow.mjs"
   },
   "exports": {
-    ".": "./src/index.mjs"
+    ".":               "./src/index.mjs",
+    "./keychain":      "./src/identity/keychain.mjs",
+    "./jcs":           "./src/identity/jcs.mjs",
+    "./tier":          "./src/identity/tier.mjs",
+    "./envelope":      "./src/net/envelope.mjs",
+    "./e2e":           "./src/crypto/e2e.mjs",
+    "./carrier-client":"./src/net/carrier-client.mjs",
+    "./package.json":  "./package.json"
   },
   "files": [
     "src",
@@ -33,6 +41,8 @@
   },
   "dependencies": {
     "@chainsafe/libp2p-noise": "^17.0.0",
+    "@noble/curves": "^2.3.0",
+    "@noble/hashes": "^2.3.0",
     "@chainsafe/libp2p-yamux": "^8.0.1",
     "@libp2p/autonat": "^3.0.26",
     "@libp2p/bootstrap": "^12.0.29",

package/src/escrow/box.mjs

@@ -0,0 +1,43 @@
+/**
+ * Content box — symmetric AES-256-GCM under the escrowed 32-byte content
+ * key K.  The seller seals the deliverable with K and sends the box directly
+ * to the buyer; the escrow holds only K (and the sha256 of the plaintext, in
+ * the signed terms) — it never sees the payload.  The buyer can only open
+ * the box after K is released, and the GCM tag makes any tamper or wrong key
+ * fail loudly.
+ */
+import { randomBytes, createCipheriv, createDecipheriv, createHash } from "node:crypto";
+
+export const BOX_ALG = "aes-256-gcm";
+
+export function sealBox(key32, plaintext) {
+  if (!Buffer.isBuffer(key32) || key32.length !== 32) throw new Error("sealBox: key must be 32 bytes");
+  const iv = randomBytes(12);
+  const c = createCipheriv(BOX_ALG, key32, iv);
+  const ct = Buffer.concat([c.update(plaintext), c.final()]);
+  return {
+    alg: BOX_ALG,
+    iv: iv.toString("hex"),
+    ct: Buffer.concat([ct, c.getAuthTag()]).toString("hex"), // tag appended to ct
+  };
+}
+
+/** Throws on wrong key, tamper, or malformed box — never returns garbage. */
+export function openBox(key32, box) {
+  if (!Buffer.isBuffer(key32) || key32.length !== 32) throw new Error("openBox: key must be 32 bytes");
+  if (!box || box.alg !== BOX_ALG || typeof box.iv !== "string" || typeof box.ct !== "string") {
+    throw new Error("openBox: bad box");
+  }
+  const iv = Buffer.from(box.iv, "hex");
+  const buf = Buffer.from(box.ct, "hex");
+  if (iv.length !== 12 || buf.length < 16) throw new Error("openBox: bad lengths");
+  const ct = buf.subarray(0, buf.length - 16);
+  const tag = buf.subarray(buf.length - 16);
+  const d = createDecipheriv(BOX_ALG, key32, iv);
+  d.setAuthTag(tag);
+  return Buffer.concat([d.update(ct), d.final()]);
+}
+
+export function sha256Hex(buf) {
+  return createHash("sha256").update(buf).digest("hex");
+}