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

package/src/net/carrier-server.mjs

@@ -18,14 +18,33 @@
  *       x-pillar-pubkey: <ed25519 pubkey hex>
  *       x-pillar-ts:     <unix ms>  (rejected if clock skew > 5 min)
  *       x-pillar-sig:    hex(sign("GET /v1/inbox/<uuaid>?since=<seq>" + "\n" + ts))
+ *       x-pillar-delegation: (optional) JSON delegation document letting a
+ *         delegate key read <uuaid>'s inbox; must be signed by <uuaid> and
+ *         cover kind "inbox" (or "*")
  *     - carrier derives UUAID from pubkey; must equal <uuaid>  (self-authenticating,
- *       zero registration)
+ *       zero registration) unless a valid inbox delegation is presented
  *     - long-polls up to `wait` seconds (max 30)
  *     -> 200 { envelopes: [{seq, envelope}], now }
  *
  *   GET /v1/health
  *     -> 200 { ok, uptime, stored }
  *
+ *   GET /v1/seed-info
+ *     -> 200 { v, url, uuaid, publicKey, startedAt, firstSeen, stats, now, sig }
+ *     Present only when the server was constructed with a keychain + publicUrl
+ *     (i.e. it is running as a public seed, not a private relay). The
+ *     signature binds this URL to the operator's key, which is what the seed
+ *     registry checks at enrollment before listing the URL as a seed.
+ *
+ * PRIORITY ADMISSION
+ *
+ * Load shedding is not uniform. A sender presenting a valid tier grant with
+ * `priority: true` — issued to durable seed operators by the seed registry —
+ * is admitted from reserved headroom that community traffic cannot touch:
+ * the last slice of the store, its own per-IP budget, and reserved long-poll
+ * slots. Under no load the two lanes are indistinguishable; the privilege
+ * only becomes visible at the moment the carrier starts saying no.
+ *
  * Durability: SQLite (WAL).  Envelopes are retained until TTL (default 14 days).
  * The carrier CANNOT read payloads it relays beyond what the envelope exposes,
  * and CANNOT forge envelopes (no keys).  It can only: deliver, delay, or drop —
@@ -36,12 +55,15 @@ import { createHash } from "node:crypto";
 import Database from "better-sqlite3";
 import { open as openEnvelope } from "./envelope.mjs";
 import { Keychain } from "../identity/keychain.mjs";
+import { jcs } from "../identity/jcs.mjs";
 import { verifyTierGrant } from "../identity/tier.mjs";
+import { verifyDelegationDoc, delegationCoversKind } from "./delegation.mjs";
 
 const MAX_WAIT_S = 30;
 const MAX_BODY = 512 * 1024; // 512 KiB per envelope (community tier)
 const MAX_BODY_STREAM = 2 * 1024 * 1024 + 8192; // absolute read cap: max tier body + grant/header slack
 const MAX_SKEW_MS = 5 * 60 * 1000;
+const MAX_DELEGATION_HEADER = 8192; // x-pillar-delegation size cap (bytes)
 // Hardening (RedTeam F2/F3):
 const MAX_ENVELOPE_AGE_MS = 24 * 3600_000; // F3: ingest freshness — reject skewed createdAt
 const RATE_WINDOW_MS = 60_000;             // F2: sliding window for all rate limits
@@ -51,9 +73,16 @@ const MAX_INVALID_PER_MIN = 60;            // F2: per client-IP budget for rejec
 const MAX_CONCURRENT_WAITS = 64;           // F2: inbox long-poll concurrency cap
 const MAX_DB_BYTES = 256 * 1024 * 1024;    // F2: SQLite size backpressure (503 when full)
 const RATE_MAP_HARD_CAP = 10_000;          // F2: bound memory under key spray
+// Priority lanes. Each is a RESERVE carved out of an existing cap, never an
+// increase of it: community traffic sheds earlier so that priority traffic
+// still fits inside the same absolute ceiling. A carrier with no trusted tier
+// issuers configured never resolves a priority grant, so these are inert.
+const COMMUNITY_DB_BYTES = Math.floor(MAX_DB_BYTES * 0.85);   // last 15% of the store is reserved
+const COMMUNITY_CONCURRENT_WAITS = 48;                        // of MAX_CONCURRENT_WAITS
+const MAX_PRIORITY_GOOD_PER_MIN = 600;                        // priority senders bill to their own per-IP bucket
 
 export class CarrierServer {
-  constructor({ dbPath = "carrier.db", ttlDays = 14, cryptoInventory, trustedTierIssuers = [] } = {}) {
+  constructor({ dbPath = "carrier.db", ttlDays = 14, cryptoInventory, trustedTierIssuers = [], keychain = null, publicUrl = null } = {}) {
     this.db = new Database(dbPath);
     this.db.pragma("journal_mode = WAL");
     this.db.exec(`
@@ -67,7 +96,16 @@ export class CarrierServer {
         created_at  text not null default (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
       );
       create index if not exists idx_envelopes_recipient on envelopes(recipient, seq);
+      -- Lifetime service counters. Kept OUTSIDE the envelopes table because
+      -- vacuum() deletes envelopes at TTL, and a seed's service history must
+      -- survive its own garbage collection.
+      create table if not exists seed_stats (
+        k text primary key,
+        v text not null
+      );
     `);
+    this.db.prepare("insert or ignore into seed_stats (k, v) values ('first_seen', ?)")
+      .run(new Date().toISOString());
     this.ttlDays = ttlDays;
     this.cryptoInventory = cryptoInventory ?? { ed25519: "active" };
     this.startedAt = Date.now();
@@ -79,6 +117,54 @@ export class CarrierServer {
     // sender gets community-tier budgets (pre-tier behavior, default).
     this.trustedTierIssuers = trustedTierIssuers;
     this._grantCache = new Map(); // sender uuaid -> { grant, cachedAt }
+    // Seed identity. Optional: a private relay runs without one and simply
+    // does not expose /v1/seed-info.
+    this.keychain = keychain;
+    this.publicUrl = publicUrl ? String(publicUrl).replace(/\/+$/, "") : null;
+  }
+
+  /** Read a lifetime counter. */
+  _stat(k, fallback = 0) {
+    const row = this.db.prepare("select v from seed_stats where k = ?").get(k);
+    if (row === undefined) return fallback;
+    const n = Number(row.v);
+    return Number.isFinite(n) ? n : row.v;
+  }
+
+  /** Bump a lifetime counter by n (creating it at 0 first). */
+  _bump(k, n = 1) {
+    this.db.prepare(
+      "insert into seed_stats (k, v) values (?, ?) on conflict(k) do update set v = cast(cast(v as integer) + ? as text)"
+    ).run(k, String(n), n);
+  }
+
+  /**
+   * The signed service claim served at /v1/seed-info.
+   *
+   * These counters are the seed's OWN account of its work and are therefore
+   * not evidence: an operator can inflate them freely. The registry records
+   * them for display and promotes strictly on what it observes itself (see
+   * net/seed-tier.mjs). What the signature does prove is the thing enrollment
+   * actually needs — that whoever controls this URL also controls this key.
+   */
+  seedInfo() {
+    if (!this.keychain?._identity || !this.publicUrl) return null;
+    const doc = {
+      v: 1,
+      url: this.publicUrl,
+      uuaid: this.keychain._identity.uuaid,
+      publicKey: this.keychain._identity.publicKeyHex,
+      startedAt: new Date(this.startedAt).toISOString(),
+      firstSeen: this.db.prepare("select v from seed_stats where k = 'first_seen'").get()?.v ?? null,
+      stats: {
+        relayed: this._stat("relayed"),
+        served: this._stat("served"),
+        stored: this.db.prepare("select count(*) as n from envelopes").get().n,
+      },
+      now: new Date().toISOString(),
+    };
+    doc.sig = this.keychain.sign(Buffer.from(jcs(doc), "utf-8")).toString("hex");
+    return doc;
   }
 
   /**
@@ -89,7 +175,7 @@ export class CarrierServer {
    * cannot break plain delivery.
    */
   _resolveTier(req, sender) {
-    const fallback = { tier: "community", envelopesPerMin: MAX_ENVELOPES_PER_MIN, maxBodyBytes: MAX_BODY };
+    const fallback = { tier: "community", envelopesPerMin: MAX_ENVELOPES_PER_MIN, maxBodyBytes: MAX_BODY, priority: false };
     if (!this.trustedTierIssuers.length) return fallback;
     const hdr = req?.headers?.["x-pillar-tier-grant"];
     if (!hdr) return fallback;
@@ -101,7 +187,16 @@ export class CarrierServer {
     if (cached && cached.sig === grant.sig && Date.now() - cached.at < 60_000) return cached.resolved;
     const v = verifyTierGrant(grant, this.trustedTierIssuers);
     const resolved = v.ok
-      ? { tier: grant.tier, envelopesPerMin: grant.envelopesPerMin, maxBodyBytes: grant.maxBodyBytes }
+      ? {
+          tier: grant.tier,
+          envelopesPerMin: grant.envelopesPerMin,
+          maxBodyBytes: grant.maxBodyBytes,
+          // Only a grant the issuer actually signed as priority opens the
+          // reserved lane. verifyTierGrant has already rejected any grant
+          // whose `priority` is present but not exactly true.
+          priority: grant.priority === true,
+          seedTier: grant.seedTier ?? null,
+        }
       : fallback;
     if (this._grantCache.size > 4096) this._grantCache.clear(); // bounded
     this._grantCache.set(sender, { sig: grant.sig, at: Date.now(), resolved });
@@ -175,7 +270,7 @@ export class CarrierServer {
       if (!this._rateAllow(`bad:${ip}`, MAX_INVALID_PER_MIN)) {
         return { code: 429, body: { accepted: false, reason: "rate-limited" } };
       }
-      return { code: 400, body: { accepted: false, reason: verdict.reason } };
+      return { code: verdict.code ?? 400, body: { accepted: false, reason: verdict.reason } };
     }
     if (typeof envelope.recipient !== "string" || !envelope.recipient.startsWith("uuaid:")) {
       return { code: 400, body: { accepted: false, reason: "bad-recipient" } };
@@ -191,7 +286,12 @@ export class CarrierServer {
     }
     // F2: per-client budget on ACCEPTED sends — closes the unlimited
     // fresh-keypair spray (each new key gets a fresh sender budget).
-    if (!this._rateAllow(`g:${ip}`, MAX_GOOD_PER_MIN)) {
+    // Priority senders bill to a SEPARATE bucket: the point of the lane is
+    // that a noisy neighbour behind the same egress IP (or NAT, or CI
+    // runner) cannot consume the budget a durable seed operator earned.
+    const ipKey = tier.priority ? `p:${ip}` : `g:${ip}`;
+    const ipLimit = tier.priority ? MAX_PRIORITY_GOOD_PER_MIN : MAX_GOOD_PER_MIN;
+    if (!this._rateAllow(ipKey, ipLimit)) {
       return { code: 429, body: { accepted: false, reason: "rate-limited" } };
     }
     // F3: freshness — reject envelopes whose createdAt is missing or skewed
@@ -201,10 +301,13 @@ export class CarrierServer {
       return { code: 400, body: { accepted: false, reason: "stale-envelope" } };
     }
     // F2: backpressure — refuse ingest when the store is near-full instead of
-    // failing at disk-full mid-write.
+    // failing at disk-full mid-write. Community traffic sheds at 85% so the
+    // remaining slice stays available to priority senders; the absolute cap
+    // is identical for both, so the reserve cannot push the store past it.
     const pages = this.db.pragma("page_count", { simple: true });
     const pageBytes = this.db.pragma("page_size", { simple: true });
-    if (pages * pageBytes > MAX_DB_BYTES) {
+    const storeCap = tier.priority ? MAX_DB_BYTES : COMMUNITY_DB_BYTES;
+    if (pages * pageBytes > storeCap) {
       return { code: 503, body: { accepted: false, reason: "carrier-full" } };
     }
     const sha = createHash("sha256").update(JSON.stringify(envelope)).digest("hex");
@@ -212,6 +315,7 @@ export class CarrierServer {
       const r = this.db.prepare(
         "insert into envelopes (envelope_id, recipient, sender, sha, body) values (?,?,?,?,?)"
       ).run(envelope.id, envelope.recipient, envelope.sender, sha, JSON.stringify(envelope));
+      this._bump("relayed");
       return { code: 202, body: { accepted: true, seq: Number(r.lastInsertRowid), sha } };
     } catch (e) {
       if (/UNIQUE constraint/.test(e.message)) {
@@ -236,7 +340,17 @@ export class CarrierServer {
     // Self-authenticating: UUAID must derive from the presented pubkey.
     const localId = Keychain._localIdFromKey(Buffer.from(pubkey, "hex"));
     const derived = `uuaid:foundation:agent:${localId}`;
-    if (derived !== uuaid) return { ok: false, reason: "uuaid-pubkey-mismatch" };
+    if (derived !== uuaid) {
+      // A delegate key may read the principal's inbox only by presenting the
+      // principal-signed delegation document that names it.  Without the
+      // header this stays the legacy mismatch.
+      const raw = req.headers["x-pillar-delegation"];
+      if (raw === undefined) return { ok: false, reason: "uuaid-pubkey-mismatch" };
+      const delegated = this._verifyInboxDelegation(raw, uuaid, pubkey);
+      if (!delegated.ok) return delegated;
+    }
+    // Either the principal's own key or an authorized delegate key: in both
+    // cases it must have signed THIS request.
     const message = Buffer.from(`${sincePath}\n${ts}`, "utf-8");
     let verified = false;
     try { verified = Keychain.verifyDetached(pubkey, message, Buffer.from(sig, "hex")); }
@@ -245,6 +359,37 @@ export class CarrierServer {
     return { ok: true };
   }
 
+  /**
+   * Authorize a delegate to poll `uuaid`'s inbox from an `x-pillar-delegation`
+   * header.  Fails closed on every error and never logs the document.
+   *
+   * Reasons (all surface as HTTP 401):
+   *   delegation-too-large            header exceeds MAX_DELEGATION_HEADER
+   *   delegation-unparseable          not a string / not JSON
+   *   delegation-invalid:<reason>     verifyDelegationDoc verdict (expired,
+   *                                   bad-signature, *-uuaid-binding, ...)
+   *   delegation-principal-mismatch   doc principal is not the path uuaid
+   *   delegation-delegate-key-mismatch  doc names a different delegate key
+   *   delegation-inbox-denied         kinds cover neither "inbox" nor "*"
+   */
+  _verifyInboxDelegation(raw, uuaid, pubkey) {
+    if (typeof raw !== "string") return { ok: false, reason: "delegation-unparseable" };
+    if (Buffer.byteLength(raw, "utf-8") > MAX_DELEGATION_HEADER) {
+      return { ok: false, reason: "delegation-too-large" };
+    }
+    let doc;
+    try { doc = JSON.parse(raw); }
+    catch (_e) { return { ok: false, reason: "delegation-unparseable" }; }
+    const verdict = verifyDelegationDoc(doc);
+    if (!verdict.ok) return { ok: false, reason: `delegation-invalid:${verdict.reason}` };
+    if (doc.principal !== uuaid) return { ok: false, reason: "delegation-principal-mismatch" };
+    if (doc.delegatePublicKey.toLowerCase() !== pubkey.toLowerCase()) {
+      return { ok: false, reason: "delegation-delegate-key-mismatch" };
+    }
+    if (!delegationCoversKind(doc, "inbox")) return { ok: false, reason: "delegation-inbox-denied" };
+    return { ok: true };
+  }
+
   async _handleInbox(req, res, uuaid, url) {
     const since = Number(url.searchParams.get("since") ?? 0);
     const wait = Math.min(Number(url.searchParams.get("wait") ?? 0), MAX_WAIT_S);
@@ -253,8 +398,13 @@ export class CarrierServer {
     if (!auth.ok) return this._json(res, 401, { error: auth.reason });
 
     // F2: cap concurrent long-polls so sleeping connections cannot pin the
-    // event loop / fd table.
-    if (wait > 0 && this.activeWaits >= MAX_CONCURRENT_WAITS) {
+    // event loop / fd table. The grant is resolved against the PRINCIPAL
+    // whose inbox this is (the path uuaid), not the key that signed — a
+    // delegate polling for a priority principal inherits the reserved slots,
+    // which is the same authority it already has to read the mail.
+    const tier = this._resolveTier(req, uuaid);
+    const waitCap = tier.priority ? MAX_CONCURRENT_WAITS : COMMUNITY_CONCURRENT_WAITS;
+    if (wait > 0 && this.activeWaits >= waitCap) {
       return this._json(res, 503, { error: "busy" });
     }
     if (wait > 0) this.activeWaits++;
@@ -275,6 +425,7 @@ export class CarrierServer {
         await new Promise(r => setTimeout(r, 400));
         rows = fetchRows();
       }
+      if (rows.length) this._bump("served", rows.length);
       this._json(res, 200, {
         envelopes: rows.map(r => ({ seq: r.seq, envelope: JSON.parse(r.body) })),
         now: Date.now(),
@@ -302,6 +453,13 @@ export class CarrierServer {
           if (!uuaid.startsWith("uuaid:")) return this._json(res, 404, { error: "not-found" });
           return await this._handleInbox(req, res, uuaid, url);
         }
+        if (req.method === "GET" && url.pathname === "/v1/seed-info") {
+          const info = this.seedInfo();
+          // A relay with no seed identity is not a seed and must not look
+          // like one to the registry.
+          if (!info) return this._json(res, 404, { error: "not-a-seed" });
+          return this._json(res, 200, info);
+        }
         if (req.method === "GET" && url.pathname === "/v1/health") {
           const stored = this.db.prepare("select count(*) as n from envelopes").get().n;
           return this._json(res, 200, { ok: true, uptimeMs: Date.now() - this.startedAt, stored });

package/src/net/delegation.mjs

@@ -0,0 +1,152 @@
+/**
+ * Device/persona delegation — UACP/1.0 protocol extension (carrier side).
+ *
+ * A long-lived "persona" UUAID (the principal) authorizes a short-lived
+ * device identity (the delegate) to act on its behalf for specific envelope
+ * kinds and a bounded time window.  The persona signs a JCS-canonical
+ * delegation document; the device embeds that document in the envelope's
+ * `delegation` field and signs the whole envelope with ITS OWN key.
+ *
+ *   delegation = {
+ *     version:   "uuaid-delegation/1",
+ *     id:        "del-...",
+ *     principal: persona uuaid,   principalPublicKey: hex,
+ *     delegate:  device  uuaid,   delegatePublicKey:  hex,
+ *     kinds:     ["*"] or ["request","reply",...],
+ *     notBefore, notAfter: ISO 8601,
+ *     signature: { alg: "ed25519", publicKey, signature },
+ *   }
+ *   signature = ed25519(JCS(delegation minus .signature), principalSeed)
+ *
+ * Wire-compatible with @uuaid/pillar-client's delegation.ts (mintDelegation /
+ * verifyDelegation / sealWithDelegation / verifyDelegatedEnvelope): same
+ * document shape, same JCS canonicalization, same rejection reason strings,
+ * so a carrier and a pillar-client peer reach the same verdict on the same
+ * bytes.
+ *
+ * Envelope acceptance rules (envelope.mjs open() branches here when the
+ * optional `delegation` field is present; absent -> legacy behavior,
+ * unchanged):
+ *   (a) envelope transport signature valid under the DELEGATE's pubkey and
+ *       transportSignature.keyId === delegate uuaid;
+ *   (b) delegation document signature valid under the PRINCIPAL's pubkey,
+ *       principal === envelope.sender, delegate === signing key's uuaid;
+ *   (c) local-id binding for BOTH identities:
+ *       sha256(pubkey)[:16] (UUID-dash formatted) === uuaid local-id;
+ *   (d) now within [notBefore, notAfter];
+ *   (e) envelope.kind covered by the delegation `kinds` allowlist
+ *       ("*" covers everything), and not a capability-only name such as
+ *       "inbox" — those are poll capabilities, never deliverable kinds, and
+ *       are refused even under "*" (see CAPABILITY_ONLY_KINDS).
+ * All five must pass; any failure rejects with
+ * `delegation-invalid:<reason>` (HTTP 403 at the carrier).
+ *
+ * Storage/mailbox attribution is unchanged: the envelope's `sender` IS the
+ * principal, so carriers key mailboxes, rate limits, and audits to the
+ * principal UUAID exactly as before.
+ */
+import { jcs } from "../identity/jcs.mjs";
+import { Keychain } from "../identity/keychain.mjs";
+
+export const DELEGATION_VERSION = "uuaid-delegation/1";
+
+/**
+ * Extract the local-id of a UUAID with pillar-client parseUuaid semantics:
+ * exactly four colon-separated segments with the "uuaid" prefix.
+ * Returns null for anything else (never throws).
+ */
+export function uuaidLocalId(uuaid) {
+  if (typeof uuaid !== "string") return null;
+  const parts = uuaid.split(":");
+  if (parts.length !== 4 || parts[0] !== "uuaid") return null;
+  return parts[3];
+}
+
+/** Self-authenticating identity check: sha256(pubkey)[:16] === uuaid local-id. */
+export function uuaidBindingOk(uuaid, publicKeyHex) {
+  const localId = uuaidLocalId(uuaid);
+  if (localId === null) return false;
+  if (typeof publicKeyHex !== "string" || !/^[0-9a-f]{64}$/i.test(publicKeyHex)) return false;
+  return Keychain.localIdFromKey(Buffer.from(publicKeyHex, "hex")) === localId;
+}
+
+/**
+ * Verify a delegation document on its own: shape, identity bindings, time
+ * window, and the principal's signature over JCS(doc minus .signature).
+ *
+ * Reason strings intentionally mirror @uuaid/pillar-client verifyDelegation
+ * so tooling sees identical diagnostics on both implementations.
+ *
+ * Returns { ok: true } or { ok: false, reason }.
+ */
+export function verifyDelegationDoc(d, now = new Date()) {
+  if (!d || typeof d !== "object" || Array.isArray(d)) return { ok: false, reason: "not-object" };
+  if (d.version !== DELEGATION_VERSION) return { ok: false, reason: `bad-version:${d.version}` };
+  if (!/^[0-9a-f]{64}$/i.test(d.principalPublicKey ?? "")) return { ok: false, reason: "bad-principal-pubkey" };
+  if (!/^[0-9a-f]{64}$/i.test(d.delegatePublicKey ?? "")) return { ok: false, reason: "bad-delegate-pubkey" };
+  if (!uuaidBindingOk(d.principal, d.principalPublicKey)) {
+    return { ok: false, reason: "principal-uuaid-binding" };
+  }
+  if (!uuaidBindingOk(d.delegate, d.delegatePublicKey)) {
+    return { ok: false, reason: "delegate-uuaid-binding" };
+  }
+  if (!Array.isArray(d.kinds) || d.kinds.length === 0 || d.kinds.some(k => typeof k !== "string")) {
+    return { ok: false, reason: "bad-kinds" };
+  }
+  const nb = Date.parse(d.notBefore);
+  const na = Date.parse(d.notAfter);
+  if (Number.isNaN(nb) || Number.isNaN(na)) return { ok: false, reason: "bad-time" };
+  if (na <= nb) return { ok: false, reason: "empty-window" };
+  const t = now instanceof Date ? now.getTime() : Number(now);
+  if (t < nb) return { ok: false, reason: "not-yet-valid" };
+  if (t > na) return { ok: false, reason: "expired" };
+
+  const sig = d.signature;
+  if (!sig || sig.alg !== "ed25519" || sig.publicKey !== d.principalPublicKey) {
+    return { ok: false, reason: "bad-signature-shape" };
+  }
+  if (typeof sig.signature !== "string" || !/^[0-9a-f]{128}$/i.test(sig.signature)) {
+    return { ok: false, reason: "bad-signature-shape" };
+  }
+  // The signature covers JCS of everything except .signature.
+  const { signature: _drop, ...unsigned } = d;
+  let canonical;
+  try { canonical = jcs(unsigned); } catch (_e) { return { ok: false, reason: "bad-canonical" }; }
+  let okSig = false;
+  try {
+    okSig = Keychain.verifyDetached(sig.publicKey, Buffer.from(canonical, "utf-8"), Buffer.from(sig.signature, "hex"));
+  } catch (_e) {
+    return { ok: false, reason: "verify-threw" };
+  }
+  if (!okSig) return { ok: false, reason: "bad-signature" };
+  return { ok: true };
+}
+
+/**
+ * Names that may appear in a delegation's `kinds` as CAPABILITIES but are not
+ * envelope kinds, and so must never be deliverable.
+ *
+ * `kinds` is a single namespace answering two different questions: "may this
+ * delegate SEND envelopes of kind K" (envelope.mjs) and "may this delegate
+ * POLL the principal's inbox" (carrier-server.mjs, capability "inbox"). The
+ * overlap means a token minted read-only as `kinds: ["inbox"]` also satisfies
+ * the send check for an envelope whose `kind` is literally "inbox" — verified
+ * against a live alpha.15 carrier, which returned 202 for exactly that forgery
+ * while correctly returning 403 kind-not-covered for message/request/reply.
+ *
+ * Nothing consumes `kind: "inbox"`, so this is latent rather than live. It
+ * stops being latent the moment a read-only poll token is issued to anyone,
+ * which is what the push relay is being rebuilt to use.
+ *
+ * Enforced on the send path in envelope.mjs. Deliberately NOT enforced inside
+ * delegationCoversKind: that helper serves both questions, and the capability
+ * lookup in carrier-server.mjs depends on "inbox" matching there.
+ */
+export const CAPABILITY_ONLY_KINDS = new Set(["inbox"]);
+
+/** Does this delegation cover envelopes of `kind`?  "*" covers all. */
+export function delegationCoversKind(d, kind) {
+  if (!Array.isArray(d?.kinds)) return false;
+  if (d.kinds.includes("*")) return true;
+  return d.kinds.includes(kind);
+}

package/src/net/envelope.mjs

@@ -30,6 +30,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { jcs } from "../identity/jcs.mjs";
 import { Keychain } from "../identity/keychain.mjs";
 import { sealPayload, openPayload, E2E_ALG } from "../crypto/e2e.mjs";
+import { verifyDelegationDoc, delegationCoversKind, CAPABILITY_ONLY_KINDS } from "./delegation.mjs";
 
 export const ENVELOPE_VERSION = "uuaid-pillar-envelope/2";
 export { E2E_ALG };
@@ -92,6 +93,11 @@ export function seal(keychain, body) {
  * Verify an envelope's transport signature and structure.  Does NOT decrypt.
  * Anyone (carriers, relays, auditors) can call this.
  * Returns { ok: true } or { ok: false, reason }.
+ *
+ * DELEGATED ENVELOPES (UACP/1.0 ext): when the optional `delegation` field is
+ * present, the self-authenticating-sender rule is replaced by the delegation
+ * chain — see openDelegated() below and src/net/delegation.mjs.  When the
+ * field is ABSENT the checks below are byte-for-byte the legacy behavior.
  */
 export function open(envelope, { cryptoInventory } = {}) {
   if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) return { ok: false, reason: "not-object" };
@@ -101,6 +107,9 @@ export function open(envelope, { cryptoInventory } = {}) {
   if (cryptoInventory && cryptoInventory[sig.alg] !== "active") {
     return { ok: false, reason: `alg-not-active:${sig.alg}` };
   }
+  if (envelope.delegation !== undefined) {
+    return openDelegated(envelope, { cryptoInventory });
+  }
   if (sig.keyId !== envelope.sender) return { ok: false, reason: "keyId-sender-mismatch" };
   if (typeof sig.publicKey !== "string" || !/^[0-9a-f]{64}$/i.test(sig.publicKey)) return { ok: false, reason: "bad-publicKey" };
   if (typeof sig.signature !== "string" || !/^[0-9a-f]{128}$/i.test(sig.signature)) return { ok: false, reason: "bad-signature-encoding" };
@@ -136,6 +145,78 @@ export function open(envelope, { cryptoInventory } = {}) {
   return { ok: true };
 }
 
+/**
+ * Delegated path of open() — UACP/1.0 extension.  Invoked when the envelope
+ * carries a `delegation` document; the legacy self-authenticating-sender rule
+ * is REPLACED by the five delegation checks (see delegation.mjs):
+ *
+ *   (a) envelope signature valid under the DELEGATE's key,
+ *       transportSignature.keyId === delegation.delegate;
+ *   (b) delegation document signature valid under the PRINCIPAL's key,
+ *       delegation.principal === envelope.sender,
+ *       delegation.delegate === the signing key's uuaid;
+ *   (c) local-id binding for BOTH identities (inside verifyDelegationDoc);
+ *   (d) now within [notBefore, notAfter] (inside verifyDelegationDoc);
+ *   (e) envelope.kind covered by delegation.kinds.
+ *
+ * Fail-open is not an option: any failure rejects with
+ * { ok: false, reason: "delegation-invalid:<reason>", code: 403 }.  Pure
+ * wire-format failures (enc block, hex encodings) keep the legacy reasons and
+ * 400 status — they are not delegation verdicts.
+ *
+ * The `delegation` field is part of the SIGNED body (sealed inside the
+ * canonicalization by the delegate), so a carrier cannot strip or swap it
+ * without breaking the envelope signature.
+ */
+function openDelegated(envelope, { cryptoInventory } = {}) {
+  const reject = (reason) => ({ ok: false, reason: `delegation-invalid:${reason}`, code: 403 });
+  const sig = envelope.transportSignature;
+  if (typeof sig.publicKey !== "string" || !/^[0-9a-f]{64}$/i.test(sig.publicKey)) return { ok: false, reason: "bad-publicKey" };
+  if (typeof sig.signature !== "string" || !/^[0-9a-f]{128}$/i.test(sig.signature)) return { ok: false, reason: "bad-signature-encoding" };
+  // Structural checks on the encryption block — same rules as the legacy path.
+  const enc = envelope.enc;
+  if (!enc || typeof enc !== "object") return { ok: false, reason: "missing-enc" };
+  if (enc.alg !== E2E_ALG) return { ok: false, reason: `enc-alg-not-supported:${enc.alg}` };
+  if (cryptoInventory && cryptoInventory[enc.alg] && cryptoInventory[enc.alg] !== "active") {
+    return { ok: false, reason: `enc-alg-not-active:${enc.alg}` };
+  }
+  if (typeof enc.epk !== "string" || !/^[0-9a-f]{64}$/i.test(enc.epk)) return { ok: false, reason: "bad-epk" };
+  if (typeof enc.iv !== "string" || !/^[0-9a-f]{24}$/i.test(enc.iv)) return { ok: false, reason: "bad-iv" };
+  if (typeof enc.ct !== "string" || !/^[0-9a-f]{32,}$/i.test(enc.ct)) return { ok: false, reason: "bad-ct" };
+
+  const d = envelope.delegation;
+  // (b-i) + (c) + (d): the delegation document itself — shape, both local-id
+  // bindings, time window, and the principal's signature over it.
+  const dv = verifyDelegationDoc(d);
+  if (!dv.ok) return reject(dv.reason);
+  // (b-ii) the persona this envelope acts as must be the delegation principal.
+  if (d.principal !== envelope.sender) return reject("sender-not-principal");
+  // (b-iii) the actual signer must be the named delegate, key and all.
+  if (sig.keyId !== d.delegate) return reject("signer-not-delegate");
+  if (sig.publicKey !== d.delegatePublicKey) return reject("signer-key-mismatch");
+  // (e) the delegation must cover this envelope kind.
+  //
+  // A capability name is checked FIRST and unconditionally — including under
+  // kinds:["*"] — because these names are not envelope kinds at all. Without
+  // this, a read-only kinds:["inbox"] poll token doubles as authority to send
+  // envelopes of kind "inbox" as the principal. See CAPABILITY_ONLY_KINDS.
+  if (CAPABILITY_ONLY_KINDS.has(envelope.kind)) return reject("kind-reserved-capability");
+  if (!delegationCoversKind(d, envelope.kind)) return reject("kind-not-covered");
+  // (a) the envelope signature under the delegate key, over the canonical
+  // body INCLUDING the delegation field (exactly what the delegate signed).
+  const { transportSignature: _sig, ...withoutSig } = envelope;
+  let canonical;
+  try { canonical = jcs(withoutSig); } catch (_e) { return { ok: false, reason: "bad-canonical" }; }
+  let okSig;
+  try {
+    okSig = Keychain.verifyDetached(sig.publicKey, Buffer.from(canonical, "utf-8"), Buffer.from(sig.signature, "hex"));
+  } catch (_e) {
+    return { ok: false, reason: "verify-threw" };
+  }
+  if (!okSig) return reject("bad-envelope-signature");
+  return { ok: true, delegated: true, actingFor: d.principal };
+}
+
 /**
  * Decrypt an envelope's payload.  Only the recipient can do this.
  * keychain must be the recipient's loaded keychain.