@uuaid/agent-commons 0.0.0 → 0.2.0-alpha.4

package/src/vendor/pillar/groups.mjs

@@ -0,0 +1,175 @@
+/**
+ * Group threads — the `pillar-group` v1 app convention (INTERACTION-CONVENTION.md
+ * "group chats"), as the mobile app and chat-web already speak it.
+ *
+ * There is still no group key and no wire change: a group message is one
+ * ordinary 1:1 envelope per member, and the group rides INSIDE each sealed
+ * payload as `_group`. What this adds over the old `{ name, members }` tag is
+ * what makes it a thread rather than a fan-out:
+ *
+ *   id      stable `grp-<16 hex>`, so every member files it under one group
+ *   msgId   `gm-…`, identical across the fan-out copies of one message
+ *   op      message | create | rename | add | leave (roster changes travel
+ *           as ordinary group messages)
+ *   keys    optional sealing hints, binding-checked on receipt, so members
+ *           can reply to the whole group without a prior contact exchange
+ *
+ * Every member keeps its own roster (mailbox `groups` table) and applies the
+ * same rules: only a current member may rename or add, nobody can remove
+ * anyone but themselves, and a group a non-contact drops you into is a
+ * pending invitation until you accept it.
+ */
+import { randomBytes } from "node:crypto";
+import { localIdFromKey } from "./identity/keychain.mjs";
+
+export const GROUP_TAG_KEY = "_group";
+export const GROUP_TAG_V = 1;
+export const GROUP_OPS = Object.freeze(["message", "create", "rename", "add", "leave"]);
+export const MAX_GROUP_MEMBERS = 256;
+export const MAX_GROUP_NAME = 100;
+
+const GROUP_ID_RE = /^grp-[a-z0-9][a-z0-9-]{3,63}$/i;
+const UUAID_RE = /^uuaid:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9][a-z0-9-]*$/i;
+const PUBKEY_RE = /^[0-9a-f]{64}$/i;
+
+export function isGroupId(id) {
+  return typeof id === "string" && GROUP_ID_RE.test(id);
+}
+
+export function newGroupId() {
+  return `grp-${randomBytes(8).toString("hex")}`;
+}
+
+export function newGroupMsgId() {
+  return `gm-${Date.now().toString(36)}-${randomBytes(6).toString("hex")}`;
+}
+
+/** The key really owns the uuaid (the same check seal() makes). */
+export function keyBindsUuaid(uuaid, publicKeyHex) {
+  if (typeof uuaid !== "string" || typeof publicKeyHex !== "string" || !PUBKEY_RE.test(publicKeyHex)) return false;
+  try { return localIdFromKey(Buffer.from(publicKeyHex, "hex")) === uuaid.split(":")[3]; }
+  catch { return false; }
+}
+
+function djb2(s) {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) >>> 0;
+  return h;
+}
+
+/**
+ * A local id for an id-less tag (an older pillar that sent only
+ * `{ name, members }`). Same derivation as the mobile app, so the same
+ * conversation groups the same way there and here. Never an authority.
+ */
+export function deriveGroupId(name, members) {
+  const canon = `${String(name).trim().toLowerCase()}|${[...members].sort().join(",")}`;
+  const a = djb2(canon).toString(16).padStart(8, "0");
+  const b = djb2(canon.split("").reverse().join("")).toString(16).padStart(8, "0");
+  return `grp-ref-${a}${b}`;
+}
+
+/** Deduplicated, validated member list, order kept. */
+export function normalizeMembers(members) {
+  const out = [];
+  const seen = new Set();
+  for (const m of Array.isArray(members) ? members : []) {
+    if (typeof m !== "string" || !UUAID_RE.test(m) || seen.has(m)) continue;
+    seen.add(m);
+    out.push(m);
+    if (out.length >= MAX_GROUP_MEMBERS) break; // fan-out amplification guard
+  }
+  return out;
+}
+
+/** Parse a `_group` tag out of a decrypted payload; null when absent or unusable. */
+export function extractGroupTag(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  const g = payload[GROUP_TAG_KEY];
+  if (!g || typeof g !== "object" || Array.isArray(g)) return null;
+  const name = typeof g.name === "string" ? g.name.trim().slice(0, MAX_GROUP_NAME) : "";
+  const members = normalizeMembers(g.members);
+  if (!members.length) return null;
+  const derivedId = !isGroupId(g.id);
+  const id = derivedId ? deriveGroupId(name || "group", members) : g.id;
+  let keys;
+  if (g.keys && typeof g.keys === "object" && !Array.isArray(g.keys)) {
+    for (const [u, pk] of Object.entries(g.keys)) {
+      if (UUAID_RE.test(u) && typeof pk === "string" && PUBKEY_RE.test(pk)) (keys ??= {})[u] = pk.toLowerCase();
+    }
+  }
+  const msgId = typeof g.msgId === "string" && g.msgId.length > 0 && g.msgId.length <= 64 ? g.msgId : null;
+  const op = typeof g.op === "string" && GROUP_OPS.includes(g.op) ? g.op : "message";
+  return { v: typeof g.v === "number" ? g.v : GROUP_TAG_V, id, name: name || "Group", members, keys, msgId, op, derivedId };
+}
+
+/** The `_group` tag for an outbound payload. */
+export function buildGroupTag(group, { msgId, keys, op = "message" }) {
+  const tag = { v: GROUP_TAG_V, id: group.id, name: group.name, members: [...group.members], msgId };
+  if (keys && Object.keys(keys).length) tag.keys = keys;
+  if (op && op !== "message") tag.op = op;
+  return tag;
+}
+
+/**
+ * Fold an inbound tag into the local roster (mailbox `groups`). Returns the
+ * group as stored, or null when the tag changed nothing we keep.
+ *
+ *   unknown group -> join it; pending when the sender is not a contact. A
+ *                    wire id (not derived here) needs the SENDER on its own
+ *                    roster: the first tag seen for an id sets the roster, so
+ *                    a stranger must not be able to seed it, and after that
+ *                    the real members would be the strangers
+ *   known group   -> only a current MEMBER may change it: `leave` drops the
+ *                    sender, `create`/`rename` set the name, every op unions
+ *                    new members in; a re-`add` naming us clears our `left`
+ *   key hints     -> kept per group, only when the key derives its uuaid;
+ *                    they let us SEAL to a member, and never make anyone a
+ *                    trusted sender (the address book and trust.json do that)
+ */
+export function absorbGroupTag(mailbox, tag, { sender, self, text = "", fromContact = false }) {
+  const hints = {};
+  for (const [u, pk] of Object.entries(tag.keys ?? {})) {
+    if (u !== self && keyBindsUuaid(u, pk)) hints[u] = pk;
+  }
+  const existing = mailbox.getGroup(tag.id);
+  if (!existing) {
+    if (!tag.derivedId && !tag.members.includes(sender)) return null;
+    const members = tag.members.includes(self) ? tag.members : [...tag.members, self];
+    return mailbox.putGroup({
+      id: tag.id, name: tag.name, members, keys: hints, createdBy: sender, pending: !fromContact,
+    });
+  }
+  if (!existing.members.includes(sender)) return existing; // strangers cannot touch our roster
+  const keys = { ...hints, ...existing.keys }; // first key wins
+  if (tag.op === "leave") {
+    return mailbox.putGroup({ ...existing, keys, members: existing.members.filter((m) => m !== sender) });
+  }
+  const members = [...existing.members];
+  for (const m of tag.members) if (!members.includes(m) && members.length < MAX_GROUP_MEMBERS) members.push(m);
+  const addedUs = tag.op === "add" && String(text).split(",").map((x) => x.trim()).includes(self);
+  return mailbox.putGroup({
+    ...existing,
+    keys,
+    members,
+    name: tag.op === "rename" || tag.op === "create" ? tag.name : existing.name,
+    left: existing.left && !addedUs,
+  });
+}
+
+/**
+ * Resolve a group by exact id, else by unique case-insensitive name.
+ * Throws with the candidates listed when the name is ambiguous or unknown.
+ */
+export function findGroup(mailbox, ref) {
+  const byId = mailbox.getGroup(ref);
+  if (byId) return byId;
+  const all = mailbox.listGroups();
+  const hits = all.filter((g) => g.name.toLowerCase() === String(ref).toLowerCase());
+  if (hits.length === 1) return hits[0];
+  const e = new Error(hits.length
+    ? `group name "${ref}" is ambiguous: ${hits.map((g) => g.id).join(", ")} — use the id`
+    : `no group "${ref}" in this home${all.length ? ` (known: ${all.map((g) => `${g.name} ${g.id}`).join("; ")})` : ""} — list them with: pillar groups`);
+  e.code = hits.length ? "group-ambiguous" : "group-unknown";
+  throw e;
+}

package/src/vendor/pillar/identity/jcs.mjs

@@ -0,0 +1,34 @@
+/**
+ * RFC 8785 JCS canonicalization.  Same implementation as the pillar-core reference,
+ * kept independent so the pillar-node package has no upward dependency.
+ *
+ * Numbers: integers only (safe for the wire we design; enforce it).  Floats
+ * throw because deterministic ECMA-262 number serialization requires more code
+ * than we want in a reference impl and this package's message payloads never
+ * legitimately contain non-integer numbers.
+ */
+export function jcs(value) {
+  return _ser(value);
+}
+
+function _ser(v) {
+  if (v === null) return "null";
+  if (v === true) return "true";
+  if (v === false) return "false";
+  if (typeof v === "string") return JSON.stringify(v);
+  if (typeof v === "number") {
+    if (!Number.isFinite(v)) throw new Error("JCS: NaN/Infinity not permitted");
+    if (Number.isInteger(v)) return String(v);
+    throw new Error("JCS: non-integer numbers not permitted; use string decimal encoding");
+  }
+  if (typeof v === "bigint") return v.toString();
+  if (Array.isArray(v)) return "[" + v.map(_ser).join(",") + "]";
+  if (typeof v === "object") {
+    // RFC 8785 §3.2.3: keys sort by their UTF-16 code units, which is exactly
+    // JavaScript's default string order. (Comparing UTF-16LE *bytes* is not: it
+    // puts "Ā" (U+0100) before "a", and disagreed with @uuaid/pillar-client.)
+    const keys = Object.keys(v).sort(); // @rule jcs.code-unit-order
+    return "{" + keys.map(k => JSON.stringify(k) + ":" + _ser(v[k])).join(",") + "}";
+  }
+  throw new Error("JCS: unsupported type " + typeof v);
+}

package/src/vendor/pillar/identity/keychain.mjs

@@ -0,0 +1,241 @@
+/**
+ * Keychain — persistent identity for a pillar peer.
+ *
+ * Every agent has exactly one identity: an Ed25519 keypair.  The private key
+ * is stored encrypted at rest with a password derived from the OS keyring
+ * (Windows Credential Manager / macOS Keychain / GNOME libsecret) if
+ * available, or a user-supplied passphrase otherwise.
+ *
+ * The keychain is deliberately simple: one keypair, one UUAID, one file.
+ * Rotation is a new keypair + a new signed profile in the DHT.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomBytes, createHash, generateKeyPairSync, sign, verify, createPublicKey, createPrivateKey, hkdfSync, createCipheriv, createDecipheriv } from "node:crypto";
+import { ed25519 } from "@noble/curves/ed25519.js";
+
+const KEYCHAIN_VERSION = 1;
+
+/**
+ * RFC 8032 / FIPS 186-5 rule for an Ed25519 public key: the canonical encoding
+ * of a point that is not of small order and lies in the prime-order subgroup.
+ *
+ * OpenSSL's Ed25519 verify (node `crypto.verify`) does not check this: it uses
+ * the non-cofactored equation, and 5 of the 8 small-order points verify as
+ * keys. With the identity point as the key, R = identity and S = 0 verifies on
+ * every message, so anyone could forge a signature "from" that key's uuaid
+ * (found 2026-10-06). The same rule as `isStrictEd25519PublicKey` in
+ * @uuaid/pillar-client.
+ *
+ * The answer depends on the key alone, so it is cached (bounded).
+ */
+const STRICT_KEY_CACHE_MAX = 4096;
+const strictKeyCache = new Map();
+
+export function isStrictEd25519PublicKey(publicKeyHex) {
+  if (typeof publicKeyHex !== "string" || !/^[0-9a-f]{64}$/i.test(publicKeyHex)) return false;
+  const hex = publicKeyHex.toLowerCase();
+  const cached = strictKeyCache.get(hex);
+  if (cached !== undefined) return cached;
+  let ok = false;
+  try {
+    const point = ed25519.Point.fromHex(hex, false);
+    ok = point.toHex() === hex && !point.isSmallOrder() && point.isTorsionFree();
+  } catch (_e) {
+    ok = false;
+  }
+  if (strictKeyCache.size >= STRICT_KEY_CACHE_MAX) strictKeyCache.delete(strictKeyCache.keys().next().value);
+  strictKeyCache.set(hex, ok);
+  return ok;
+}
+
+/**
+ * Derive a stable, publishable local id from a raw Ed25519 public key.  This
+ * makes the UUAID self-authenticating: given the UUAID, anyone can
+ * independently check that the public key hashes to the expected local-id.
+ *
+ * Public because consumers verifying a UUAID against a public key need it
+ * without reaching into `Keychain._localIdFromKey`.
+ */
+export function localIdFromKey(rawPub) {
+  const h = createHash("sha256").update(rawPub).digest();
+  // First 16 bytes -> UUID-style dash format for readability.
+  const b = h.slice(0, 16);
+  const hex = Buffer.from(b).toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+/** Registry namespaces cannot be asserted by possession of a key alone. */
+export const SELF_CERTIFYING_NAMESPACES = Object.freeze(["foundation", "pillar", "agentnet"]);
+
+/**
+ * The namespace `pillar init` mints a NEW agent identity in when no --namespace is given.
+ * Expand before contract (owner order 2026-10-24; Uuaid-Codex review K1): 2.2.0 makes every
+ * verifier accept foundation, pillar and agentnet but still mints `foundation`, because a
+ * `pillar:` identity cannot read its inbox on a pre-2.2.0 carrier. 2.2.1 flips this to
+ * `pillar` once the carrier fleet, the main relay and the blob brokers run 2.2.x/1.2.0.
+ * Existing keychains keep the UUAID they were saved with. `Keychain.generate`'s own default
+ * stays `foundation` for library callers; CLI mint sites pass `mintNamespace(...)` instead.
+ */
+export const NEW_IDENTITY_NAMESPACE = "foundation";
+
+/**
+ * Carrier-infrastructure identities (pillar-seed, pillar-directory, pillar-escrow) stay in
+ * `foundation`: they are spoken to by third-party seeds and DHT peers on any version, and
+ * the owner's rule covers the identities people create, not the fleet's service keys
+ * (Uuaid-Codex review K2).
+ */
+export const SERVICE_IDENTITY_NAMESPACE = "foundation";
+
+/** The namespace to mint in: `requested` if it is self-certifying, else NEW_IDENTITY_NAMESPACE. Throws on any other namespace. */
+export function mintNamespace(requested) {
+  if (requested === undefined || requested === null) return NEW_IDENTITY_NAMESPACE;
+  if (typeof requested !== "string" || !SELF_CERTIFYING_NAMESPACES.includes(requested)) {
+    throw new Error(`namespace must be one of ${SELF_CERTIFYING_NAMESPACES.join(", ")} (a key alone cannot claim ${String(requested)})`);
+  }
+  return requested;
+}
+
+/** Rebuild the complete key-derived identity; minting still defaults to foundation. */
+export function keyDerivedUuaidFor(publicKeyHex, { namespace = "foundation", objectType = "agent" } = {}) {
+  if (!SELF_CERTIFYING_NAMESPACES.includes(namespace)
+    || typeof objectType !== "string" || !/^[a-z0-9-]+$/.test(objectType)
+    || typeof publicKeyHex !== "string" || !/^[0-9a-f]{64}$/i.test(publicKeyHex)) return null;
+  return `uuaid:${namespace}:${objectType}:${localIdFromKey(Buffer.from(publicKeyHex, "hex"))}`;
+}
+
+/** Compare the full identity, optionally constraining a path's existing object type. */
+export function keyDerivesUuaid(publicKeyHex, uuaid, objectType = null) {
+  if (typeof uuaid !== "string") return false;
+  const parts = uuaid.split(":");
+  if (parts.length !== 4 || parts[0] !== "uuaid" || (objectType !== null && parts[2] !== objectType)) return false;
+  const expected = keyDerivedUuaidFor(publicKeyHex, { namespace: parts[1], objectType: parts[2] });
+  return expected !== null && uuaid === expected;
+}
+
+export class Keychain {
+  constructor(path) {
+    this.path = path;
+    this._identity = null; // { uuaid, publicKeyHex, privateKey (KeyObject), createdAt }
+  }
+
+  exists() {
+    return existsSync(this.path);
+  }
+
+  /**
+   * Generate a fresh identity.  Never overwrites.
+   *
+   * uuaidNamespace: default "foundation" (the genesis namespace) for library
+   * callers. The Pillar CLIs pass mintNamespace(...) explicitly, so a new CLI
+   * identity is `pillar` unless the operator asks for agentnet or foundation.
+   * objectType: default "agent"; overridable to "service" etc.
+   * localId: default random UUIDv4-like; caller may supply.
+   */
+  static generate({ uuaidNamespace = "foundation", objectType = "agent", localId = null } = {}) {
+    const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+    const pubDer = publicKey.export({ type: "spki", format: "der" });
+    const rawPub = pubDer.slice(pubDer.length - 32);
+    const localIdActual = localId ?? Keychain._localIdFromKey(rawPub);
+    const uuaid = `uuaid:${uuaidNamespace}:${objectType}:${localIdActual}`;
+    return {
+      uuaid,
+      publicKey,
+      privateKey,
+      publicKeyHex: Buffer.from(rawPub).toString("hex"),
+      createdAt: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Derive the local-id from a raw Ed25519 public key.
+   *
+   * Kept on the class for the call sites that already reach for it; the
+   * implementation is the module-level `localIdFromKey`, which is the public
+   * export.
+   */
+  static localIdFromKey = localIdFromKey;
+
+  /** @deprecated Alias kept for compatibility — use `localIdFromKey`. */
+  static _localIdFromKey = localIdFromKey;
+
+  /**
+   * Load an identity from disk.
+   */
+  load({ passphrase } = {}) {
+    if (!this.exists()) throw new Error("keychain not initialized; run `pillar init` first");
+    const blob = JSON.parse(readFileSync(this.path, "utf-8"));
+    if (blob.version !== KEYCHAIN_VERSION) throw new Error(`unsupported keychain version ${blob.version}`);
+    const salt = Buffer.from(blob.salt, "hex");
+    const key = hkdfSync("sha256", Buffer.from(passphrase ?? "", "utf-8"), salt, "uuaid-pillar-keychain-v1", 32);
+    const iv = Buffer.from(blob.iv, "hex");
+    const ct = Buffer.from(blob.ciphertext, "base64");
+    const tag = Buffer.from(blob.tag, "hex");
+    const decipher = createDecipheriv("aes-256-gcm", Buffer.from(key), iv);
+    decipher.setAuthTag(tag);
+    const plain = Buffer.concat([decipher.update(ct), decipher.final()]);
+    const seed = plain; // 32-byte raw ed25519 seed
+    const pkcs8Prefix = Buffer.from("302e020100300506032b657004220420", "hex");
+    const privateKey = createPrivateKey({ key: Buffer.concat([pkcs8Prefix, seed]), format: "der", type: "pkcs8" });
+    const publicKey = createPublicKey(privateKey);
+    const pubDer = publicKey.export({ type: "spki", format: "der" });
+    const rawPub = pubDer.slice(pubDer.length - 32);
+    const publicKeyHex = Buffer.from(rawPub).toString("hex");
+    // Sanity: derived UUAID must match stored UUAID.
+    const derivedLocalId = Keychain._localIdFromKey(rawPub);
+    const parts = blob.uuaid.split(":");
+    if (parts.length < 4 || parts[3] !== derivedLocalId) {
+      throw new Error("keychain integrity failure: UUAID does not match keypair");
+    }
+    this._identity = { uuaid: blob.uuaid, publicKey, privateKey, publicKeyHex, createdAt: blob.createdAt };
+    return this._identity;
+  }
+
+  /**
+   * Save identity to disk, encrypted with the passphrase.
+   */
+  save(identity, { passphrase } = {}) {
+    const seedDer = identity.privateKey.export({ type: "pkcs8", format: "der" });
+    const seed = seedDer.slice(seedDer.length - 32);
+    const salt = randomBytes(16);
+    const key = hkdfSync("sha256", Buffer.from(passphrase ?? "", "utf-8"), salt, "uuaid-pillar-keychain-v1", 32);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", Buffer.from(key), iv);
+    const ct = Buffer.concat([cipher.update(seed), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const blob = {
+      version: KEYCHAIN_VERSION,
+      uuaid: identity.uuaid,
+      createdAt: identity.createdAt,
+      salt: salt.toString("hex"),
+      iv: iv.toString("hex"),
+      ciphertext: ct.toString("base64"),
+      tag: tag.toString("hex"),
+      // Public material is stored in the clear so `pillar profile` doesn't need a passphrase.
+      publicKeyHex: identity.publicKeyHex,
+    };
+    mkdirSync(dirname(this.path), { recursive: true });
+    writeFileSync(this.path, JSON.stringify(blob, null, 2));
+    chmodSync(this.path, 0o600);
+    this._identity = identity;
+  }
+
+  publicView() {
+    if (!this.exists()) return null;
+    const blob = JSON.parse(readFileSync(this.path, "utf-8"));
+    return { uuaid: blob.uuaid, publicKeyHex: blob.publicKeyHex, createdAt: blob.createdAt };
+  }
+
+  sign(data) {
+    if (!this._identity) throw new Error("identity not loaded");
+    return sign(null, Buffer.isBuffer(data) ? data : Buffer.from(data, "utf-8"), this._identity.privateKey);
+  }
+
+  static verifyDetached(publicKeyHex, data, signatureBytes) {
+    if (!isStrictEd25519PublicKey(publicKeyHex)) return false; // @rule keychain.strict-key
+    const spkiPrefix = Buffer.from("302a300506032b6570032100", "hex");
+    const der = Buffer.concat([spkiPrefix, Buffer.from(publicKeyHex, "hex")]);
+    const pub = createPublicKey({ key: der, format: "der", type: "spki" });
+    return verify(null, Buffer.isBuffer(data) ? data : Buffer.from(data, "utf-8"), pub, signatureBytes);
+  }
+}

package/src/vendor/pillar/identity/tier.mjs

@@ -0,0 +1,130 @@
+/**
+ * Tier grants — carrier-side volume/size flexibility for qualified identities.
+ *
+ * Foundations, orgs, and enterprise supporters that pass the UUAID
+ * qualification process receive a SIGNED TIER GRANT: a portable JSON object,
+ * Ed25519-signed by a trusted issuer (the UUAID Foundation identity, or any
+ * issuer a carrier operator chooses to trust).  Carriers verify the signature
+ * and expiry locally — no registry lookup, no account, consistent with the
+ * self-authenticating design.  The wire API is unchanged: a grant only
+ * raises the holder's rate/size budgets at carriers that trust the issuer.
+ *
+ * Qualification has two routes. The original is off-wire: the foundation's
+ * review process decides WHO gets a grant. The second is earned on-wire —
+ * operators who keep a public seed alive are promoted by the seed registry
+ * (net/seed-registry.mjs) and issued a grant automatically, no review. This
+ * module only makes grants unforgeable and portable; it does not care which
+ * route produced one.
+ *
+ * Grant shape (JCS-signed over every field except `sig`):
+ *   { v: 1, uuaid, tier, envelopesPerMin, maxBodyBytes, expires, issuer, sig }
+ *   ...plus optional { priority: true, seedTier, seedUrl } on earned grants.
+ *
+ * `priority` is the wire half of priority delivery: a carrier that trusts the
+ * issuer admits the holder from a reserved lane when it is otherwise shedding
+ * load. It is inside the signed body, so it cannot be added to a grant after
+ * issue. Older carriers that predate the field verify such a grant unchanged
+ * (JCS covers whatever keys are present) and simply ignore the privilege.
+ */
+import { createHash } from "node:crypto";
+import { jcs } from "./jcs.mjs";
+import { Keychain } from "./keychain.mjs";
+
+/** Tier ladder. community = the unauthenticated default (F2 hardening values).
+ *
+ *  Greek-order names (Doric, Ionic, Corinthian) are ALIASES for the lower
+ *  three rungs of the canonical ladder. They were added 2026-09-19 so that
+ *  grants may carry a feature-tier name — Doric = pillar core only,
+ *  Ionic = + plinth mix hops, Corinthian = + full optional stack — while
+ *  the carrier still enforces a single budget table. A grant with
+ *  `tier: "Doric"` and a grant with `tier: "community"` resolve to the same
+ *  rate/size budget; carriers verify by `TIER_DEFAULTS[grant.tier]` and
+ *  never see the difference.
+ *
+ *  Aliasing is additive — the canonical five names still work, no carrier
+ *  upgrade required. Enterprise and foundation keep their original names
+ *  (no alias needed; they are not feature-presence markers).
+ *
+ *  Adding a new alias is a one-line change here: spread the budget object
+ *  under the new key. No other file needs to know.
+ */
+const _CANONICAL_TIERS = {
+  community:  { envelopesPerMin: 120,  maxBodyBytes: 512 * 1024 },
+  supporter:  { envelopesPerMin: 300,  maxBodyBytes: 1024 * 1024 },
+  org:        { envelopesPerMin: 600,  maxBodyBytes: 2 * 1024 * 1024 },
+  enterprise: { envelopesPerMin: 1200, maxBodyBytes: 2 * 1024 * 1024 },
+  foundation: { envelopesPerMin: 3000, maxBodyBytes: 2 * 1024 * 1024 },
+};
+
+export const TIER_DEFAULTS = {
+  ..._CANONICAL_TIERS,
+  Doric:      _CANONICAL_TIERS.community,    // alias of community
+  Ionic:      _CANONICAL_TIERS.supporter,    // alias of supporter
+  Corinthian: _CANONICAL_TIERS.org,          // alias of org
+};
+
+/** Hard ceiling any grant can reach — also the carrier's raw-body stream cap. */
+export const ABSOLUTE_MAX_BODY = 2 * 1024 * 1024;
+export const ABSOLUTE_MAX_RATE = 6000;
+
+function signable(grant) {
+  const { sig, ...rest } = grant;
+  return jcs(rest);
+}
+
+/**
+ * Issue a grant, signed by the loaded keychain (the issuer identity).
+ * Rates/sizes default from the tier ladder; explicit overrides are clamped
+ * to the absolute ceilings.
+ */
+export function makeTierGrant(keychain, { uuaid, tier, envelopesPerMin, maxBodyBytes, expires, priority, seedTier, seedUrl }) {
+  if (!TIER_DEFAULTS[tier]) throw new Error(`unknown tier "${tier}" (${Object.keys(TIER_DEFAULTS).join("|")})`);
+  if (!uuaid?.startsWith("uuaid:")) throw new Error("grant subject must be a uuaid:...");
+  if (!expires || !Number.isFinite(Date.parse(expires))) throw new Error("expires must be an ISO date");
+  const grant = {
+    v: 1,
+    uuaid,
+    tier,
+    envelopesPerMin: Math.min(envelopesPerMin ?? TIER_DEFAULTS[tier].envelopesPerMin, ABSOLUTE_MAX_RATE),
+    maxBodyBytes: Math.min(maxBodyBytes ?? TIER_DEFAULTS[tier].maxBodyBytes, ABSOLUTE_MAX_BODY),
+    expires,
+    issuer: keychain._identity.publicKeyHex,
+    // Optional fields are omitted rather than set false/null so that a plain
+    // grant's signed body stays byte-identical to what pre-priority issuers
+    // produced.
+    ...(priority ? { priority: true } : {}),
+    ...(seedTier ? { seedTier } : {}),
+    ...(seedUrl ? { seedUrl } : {}),
+  };
+  grant.sig = keychain.sign(Buffer.from(signable(grant), "utf-8")).toString("hex");
+  return grant;
+}
+
+/**
+ * Verify a grant against a set of trusted issuer pubkeys (hex).
+ * Returns { ok: true, grant } or { ok: false, reason }.
+ */
+export function verifyTierGrant(grant, trustedIssuers, now = Date.now()) {
+  if (grant?.v !== 1) return { ok: false, reason: "bad-version" };
+  if (!TIER_DEFAULTS[grant.tier]) return { ok: false, reason: "unknown-tier" };
+  if (!trustedIssuers?.includes(grant.issuer)) return { ok: false, reason: "untrusted-issuer" };
+  const exp = Date.parse(grant.expires);
+  if (!Number.isFinite(exp) || exp < now) return { ok: false, reason: "expired" };
+  if (!(grant.envelopesPerMin <= ABSOLUTE_MAX_RATE) || !(grant.maxBodyBytes <= ABSOLUTE_MAX_BODY)) {
+    return { ok: false, reason: "over-ceiling" };
+  }
+  // Fail closed on a malformed privilege: `priority` is either absent or the
+  // boolean true. Anything else (a truthy string, 1, an object) is a grant we
+  // do not understand, and understanding it wrongly grants a reserved lane.
+  if ("priority" in grant && grant.priority !== true) return { ok: false, reason: "bad-priority" };
+  let verified = false;
+  try {
+    verified = Keychain.verifyDetached(grant.issuer, Buffer.from(signable(grant), "utf-8"), Buffer.from(grant.sig, "hex"));
+  } catch (_e) { return { ok: false, reason: "verify-threw" }; }
+  if (!verified) return { ok: false, reason: "bad-signature" };
+  return { ok: true, grant };
+}
+
+export function grantFingerprint(grant) {
+  return createHash("sha256").update(signable(grant)).digest("hex").slice(0, 16);
+}