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

package/INTERACTION-CONVENTION.md

@@ -14,6 +14,30 @@ pure JSON envelopes; any client that can HTTPS + Ed25519-seal can speak it.
 | `ack`     | receipt for any envelope; echoes the id being acked    |
 | `message` | fire-and-forget (default kind, unchanged)              |
 
+### Reserved prefixes
+
+| prefix   | owner                  | status                                |
+|----------|------------------------|---------------------------------------|
+| `esig:*` | esig-suite (Esig-Lead) | reserved by convention — NOT enforced |
+
+`kind` is unvalidated on every path: `seal()` takes `body.kind ?? "message"`
+with no enum, allowlist or regex; `open()` never inspects it; the carrier's
+`_handlePost()` validates version, signature and alg, but never `kind`. A
+reserved prefix is therefore a naming convention between lanes, **not an access
+control** — any enrolled agent can emit `esig:sealed`.
+
+What `kind` does give you: it sits inside the signed canonical body, and
+`open()` binds the sender key to `sender`, so a kind is unforgeable *as another
+sender* — it is authentic as "this sender asserted this kind." What it does not
+give you: any authorization value. An `esig:*` envelope from an unrelated uuaid
+is a well-formed envelope with a misleading label; every authorization decision
+MUST rest on the sealed payload's own signature, never on `kind`.
+
+Per rule 5 below, `kind` is cleartext to the carrier, so `esig:sign-request`
+discloses "uuaid X asked uuaid Y to sign something, at time T" to every relay.
+Lanes running signature workflows SHOULD use an opaque routing kind (`esig:m`)
+and put the real verb inside the sealed payload.
+
 ## Payload fields (all optional unless stated)
 
 - `text` — human/agent-readable body

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uuaid/pillar",
-  "version": "0.2.0-alpha.12",
+  "version": "0.2.0-alpha.13",
   "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",

package/src/identity/keychain.mjs

@@ -15,6 +15,22 @@ import { randomBytes, createHash, generateKeyPairSync, sign, verify, createPubli
 
 const KEYCHAIN_VERSION = 1;
 
+/**
+ * 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)}`;
+}
+
 export class Keychain {
   constructor(path) {
     this.path = path;
@@ -48,16 +64,17 @@ export class Keychain {
     };
   }
 
-  static _localIdFromKey(rawPub) {
-    // Derive a stable, publishable local id from the 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.
-    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)}`;
-  }
+  /**
+   * 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.

package/src/index.mjs

@@ -7,7 +7,7 @@
  * Entry point.  Not intended for import in browsers today — browser build
  * lives at @uuaid/pillar-browser (later).
  */
-export { Keychain } from "./identity/keychain.mjs";
+export { Keychain, localIdFromKey } from "./identity/keychain.mjs";
 export { jcs } from "./identity/jcs.mjs";
 export { seal, open, decrypt, envelopeSha, keychainSeed, ENVELOPE_VERSION, E2E_ALG } from "./net/envelope.mjs";
 export { sealPayload, openPayload, edPubToX25519, edSeedToX25519 } from "./crypto/e2e.mjs";