agent-comms 3.15.0 → 3.16.0

package/dist/core/connection-code.js

@@ -0,0 +1,180 @@
+/**
+ * ConnectionCode generation and redemption (agent-comms#188): bootstraps GatewayTrust between two devices that have never established a mesh connection, since GatewayTrust's own deny-by-default, pin-the-key model otherwise requires a device-id to already be known and pasted in by hand (gateway_trust). One artifact, one generation flow, one redemption flow -- never two mechanisms bolted together.
+ *
+ * `code`/`expiresAt` are the always-checked half: freshness/liveness proof that whoever redeems this was on the other end of this exact exchange, recently. `signature` is the optional half: a detached PGP signature (armored) over `${code}:${expiresAt}:${deviceId}`, checked only when present. Redemption never requires a signature -- a device with no PGP identity still generates and redeems a bare code -- but when one is present, verifying it needs the signer's own public key, supplied by the caller either as a pasted armored block or (see pgp-keyserver.ts) fetched from a keyserver by fingerprint. Either way, a caller who also supplies the fingerprint they already independently trust gets it pinned: the verified key's own computed fingerprint must equal it, or redemption fails.
+ *
+ * PGP key material is never generated, stored, or managed by this module or by agent-comms generally -- signing and verification both take key material supplied per call by the caller, exactly as invoking `gpg --sign`/`gpg --verify` directly would. Building a persisted PGP-identity subsystem (key generation, passphrase storage, revocation) is a materially larger, security-sensitive scope the settled design (agent-comms#188) never asked for; a caller who wants a code signed brings whatever real-world PGP identity they already have (git-commit signing key, personal key on a keyserver, etc.) rather than trusting agent-comms to mint and hold a new one on their behalf.
+ *
+ * Persistence (ConnectionCodeLedger, backed by identity-store.ts's connection-code ledger) is two independent halves, not a request/response pair: the generating device's own issued-code record survives a restart between generation and hand-off (identity-store.ts's own doc comment on why), while the redeeming device's own redeemed-nonce record survives a restart within the code's own short validity window, enforcing genuine single-use locally rather than merely advisory "please don't reuse this" convention. Redemption never consults the issuer's own ledger -- there is no network round-trip back to whoever generated the code, since the whole point of this bootstrap is working before any connection between the two devices exists.
+ */
+import * as openpgp from "openpgp";
+import { nanoid } from "./nanoid.js";
+import { loadConnectionCodeLedger, saveConnectionCodeLedger, } from "./identity-store.js";
+/** Nonce length: longer than nanoid's own 21-character default, since this identifier doubles as the single-use token a redemption check keys off, not merely a display id. */
+const CONNECTION_CODE_NONCE_LENGTH = 32;
+/** Minutes a generated code stays valid absent an explicit ttlMs override. */
+const DEFAULT_CONNECTION_CODE_TTL_MINUTES = 15;
+/** Seconds per minute, used to convert DEFAULT_CONNECTION_CODE_TTL_MINUTES to milliseconds. */
+const SECONDS_PER_MINUTE = 60;
+/** Milliseconds per second, used to convert DEFAULT_CONNECTION_CODE_TTL_MINUTES to milliseconds. */
+const MS_PER_SECOND = 1000;
+/** Default validity window for a generated code absent an explicit ttlMs: long enough for a human to relay it out of band (Slack, a phone call), short enough that "freshness" actually means something. */
+export const DEFAULT_CONNECTION_CODE_TTL_MS = DEFAULT_CONNECTION_CODE_TTL_MINUTES * SECONDS_PER_MINUTE * MS_PER_SECOND;
+/** Thrown by ConnectionCodeLedger.redeem for every rejection reason above -- callers branch on `reason` rather than parsing `message`. */
+export class ConnectionCodeError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "ConnectionCodeError";
+    }
+}
+/** The exact canonical message a connection code's signature is computed over -- shared by generation and redemption so both sides agree on what was actually signed. Field order and the `:` separator are fixed by this function alone; `code` and `deviceId` are both hex/base64url alphabets that never contain `:`, so the three fields can't be confused with each other under concatenation. */
+function connectionCodeMessage(candidate) {
+    return `${candidate.code}:${candidate.expiresAt}:${candidate.deviceId}`;
+}
+/** Signs `message` with `privateKeyArmored`, decrypting it with `passphrase` first if it is passphrase-protected. Returns the detached, armored PGP signature. */
+async function signConnectionCodeMessage(message, privateKeyArmored, passphrase) {
+    let privateKey = await openpgp.readPrivateKey({
+        armoredKey: privateKeyArmored,
+    });
+    if (!privateKey.isDecrypted()) {
+        privateKey = await openpgp.decryptKey(passphrase === undefined ? { privateKey } : { privateKey, passphrase });
+    }
+    const unsignedMessage = await openpgp.createMessage({ text: message });
+    // openpgp.d.ts's own sign() overloads return a conditional type keyed off T extends WebStream<Data>/NodeWebStream<Data>, which ESLint's own type-aware checking (typescript-eslint's projectService) can't resolve concretely here even though tsc itself has no trouble with it -- widening to `unknown` and narrowing with a runtime typeof check is the honest fix (Type Safety: "unknown with type narrowing"), not a cast papering over a real mismatch tsc would otherwise catch.
+    const signResult = await openpgp.sign({
+        message: unsignedMessage,
+        signingKeys: privateKey,
+        detached: true,
+    });
+    if (typeof signResult !== "string") {
+        throw new TypeError("openpgp.sign returned a stream rather than an armored string -- unexpected for a non-streaming Message input");
+    }
+    return signResult;
+}
+/** Verifies `signatureArmored` (a detached PGP signature) over `message` against `publicKeyArmored`. Never throws for an ordinary verification failure (wrong key, tampered message) -- returns `{ valid: false }` instead, reserving thrown errors for malformed input (unparsable armored text). */
+async function verifyConnectionCodeSignature(message, signatureArmored, publicKeyArmored) {
+    const publicKey = await openpgp.readKey({ armoredKey: publicKeyArmored });
+    const fingerprint = publicKey.getFingerprint();
+    const pgpMessage = await openpgp.createMessage({ text: message });
+    const signature = await openpgp.readSignature({
+        armoredSignature: signatureArmored,
+    });
+    const verificationResult = await openpgp.verify({
+        message: pgpMessage,
+        signature,
+        verificationKeys: publicKey,
+    });
+    const [sigResult] = verificationResult.signatures;
+    if (sigResult === undefined)
+        return { valid: false, fingerprint };
+    try {
+        await sigResult.verified;
+        return { valid: true, fingerprint };
+    }
+    catch {
+        return { valid: false, fingerprint };
+    }
+}
+/** Normalises a PGP fingerprint for comparison: openpgp.js's own getFingerprint() returns lowercase hex with no separators, but a human pasting one in from a keyserver page or business card may add spaces, colons, or uppercase. */
+function normalizeFingerprint(fingerprint) {
+    return fingerprint.replace(/[\s:]+/g, "").toLowerCase();
+}
+/**
+ * Generates and redeems ConnectionCode artifacts, enforcing the always-checked freshness/liveness half (expiry, single-use) and the optional PGP-signature half (checked only when a code carries one). Optionally persisted per bridge slot via identity-store.ts's connection-code ledger (see this file's own header comment for what survives a restart and why); constructed with no slot, stays in-memory only, mirroring GatewayTrust's own no-slot fallback.
+ */
+export class ConnectionCodeLedger {
+    issued = new Map();
+    redeemed = new Map();
+    slot;
+    constructor(slot) {
+        this.slot = slot;
+        if (slot !== undefined) {
+            const ledger = loadConnectionCodeLedger(slot);
+            for (const [nonce, record] of Object.entries(ledger.issued)) {
+                this.issued.set(nonce, record);
+            }
+            for (const [nonce, expiresAt] of Object.entries(ledger.redeemed)) {
+                this.redeemed.set(nonce, expiresAt);
+            }
+        }
+    }
+    /** Drops every issued or redeemed entry whose own expiresAt has already passed, so neither map accumulates forever across a long-running process or a slot that survives many restarts. */
+    prune(now) {
+        for (const [nonce, record] of this.issued) {
+            if (Date.parse(record.expiresAt) <= now)
+                this.issued.delete(nonce);
+        }
+        for (const [nonce, expiresAt] of this.redeemed) {
+            if (Date.parse(expiresAt) <= now)
+                this.redeemed.delete(nonce);
+        }
+    }
+    persist() {
+        if (this.slot !== undefined) {
+            saveConnectionCodeLedger(this.slot, {
+                issued: Object.fromEntries(this.issued),
+                redeemed: Object.fromEntries(this.redeemed),
+            });
+        }
+    }
+    /**
+     * Generates a fresh ConnectionCode vouching for deviceId, optionally signed. The nonce is single-use in the sense that redeem() below will refuse to redeem it twice; nothing prevents the caller from generating any number of independent codes for the same deviceId.
+     */
+    async generate(deviceId, options = {}) {
+        const now = options.now ?? Date.now();
+        this.prune(now);
+        const code = nanoid(CONNECTION_CODE_NONCE_LENGTH);
+        const expiresAt = new Date(now + (options.ttlMs ?? DEFAULT_CONNECTION_CODE_TTL_MS)).toISOString();
+        const signature = options.privateKeyArmored === undefined
+            ? undefined
+            : await signConnectionCodeMessage(connectionCodeMessage({ code, expiresAt, deviceId }), options.privateKeyArmored, options.passphrase);
+        const connectionCode = signature === undefined
+            ? { code, expiresAt, deviceId }
+            : { code, expiresAt, deviceId, signature };
+        const stored = signature === undefined
+            ? { expiresAt, deviceId }
+            : { expiresAt, deviceId, signature };
+        this.issued.set(code, stored);
+        this.persist();
+        return connectionCode;
+    }
+    /**
+     * Validates a candidate ConnectionCode and returns the device-id it vouches for. Always checks expiry and single-use; when the candidate carries a signature, also verifies it (requiring options.publicKeyArmored) and, when options.expectedFingerprint is given, pins the verified signing key to it. Throws ConnectionCodeError for every rejection; the caller is responsible for calling GatewayTrust.add(result.deviceId) on success -- this ledger has no dependency on GatewayTrust itself.
+     */
+    async redeem(candidate, options = {}) {
+        const now = options.now ?? Date.now();
+        this.prune(now);
+        if (Date.parse(candidate.expiresAt) <= now) {
+            throw new ConnectionCodeError("expired", `Connection code expired at ${candidate.expiresAt}`);
+        }
+        if (this.redeemed.has(candidate.code)) {
+            throw new ConnectionCodeError("already_redeemed", "Connection code has already been redeemed");
+        }
+        let fingerprint;
+        if (candidate.signature !== undefined) {
+            if (options.publicKeyArmored === undefined) {
+                throw new ConnectionCodeError("signature_required", "Connection code carries a signature but no public key was supplied to verify it against");
+            }
+            const message = connectionCodeMessage(candidate);
+            const verification = await verifyConnectionCodeSignature(message, candidate.signature, options.publicKeyArmored);
+            if (!verification.valid) {
+                throw new ConnectionCodeError("signature_invalid", "Connection code signature does not verify against the supplied public key");
+            }
+            fingerprint = verification.fingerprint;
+            if (options.expectedFingerprint !== undefined &&
+                (fingerprint === undefined ||
+                    normalizeFingerprint(fingerprint) !==
+                        normalizeFingerprint(options.expectedFingerprint))) {
+                throw new ConnectionCodeError("fingerprint_mismatch", `Signing key fingerprint ${fingerprint ?? "(unknown)"} does not match the expected fingerprint ${options.expectedFingerprint}`);
+            }
+        }
+        this.redeemed.set(candidate.code, candidate.expiresAt);
+        this.persist();
+        return fingerprint === undefined
+            ? { deviceId: candidate.deviceId }
+            : { deviceId: candidate.deviceId, fingerprint };
+    }
+}
+//# sourceMappingURL=connection-code.js.map

package/dist/core/connection-code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-code.js","sourceRoot":"","sources":["../../src/core/connection-code.ts"],"names":[],"mappings":"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"}

package/dist/core/dm-send-delegation.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Sub-delegation of a received dm:send grant to one of the recipient principal's own devices (agent-comms#187): once a remote user principal has been admitted into another user's DM-communication scope (room-lifecycle.ts's admitAgentForDm, minted with delegationsRemaining \> 0 specifically to allow this), that principal mints a CHILD dm:send token -- parent = the grant it received, bearer = its own device -- so a specific device can present durable admission on the principal's behalf, without the admitting side ever needing to know that device's own device-id in advance. Mirrors device-membership.ts's admitDevice in shape (a plain mint-and-record function, no MeshStore-equivalent orchestrator), but delegates an EXISTING grant via `parent` rather than self-issuing a fresh root-level one -- the first real use of mintCapabilityToken's parent-narrowing machinery in this codebase, every grant minted before this having been an independent root-level token.
+ *
+ * Deliberately does not touch the delegated device's own identity-store.ts slot, mirroring device-membership.ts's own "no assumption about locality" stance: getting the minted token onto that device (this process, or a different one) is left entirely to the caller.
+ */
+import { type MintVerdict } from "wire-mesh-core/domain/tokens";
+import type { IdentityPort } from "wire-mesh-core/ports/identity";
+import type { Clock } from "wire-mesh-core/ports/clock";
+import type { CapabilityToken, DeviceId } from "wire-mesh-core/generated/protocol";
+import { type UserIdentityOptions } from "./user-identity.js";
+export interface DelegateDmSendToDeviceOptions {
+    /** The principal doing the sub-delegating -- must be the same identity the parent grant's own bearer names, or mintCapabilityToken's own parent-bearer-matches-issuer narrowing check refuses the mint outright (`parent_bearer_mismatch`). */
+    userIdentity: IdentityPort;
+    /** Directory override for tests, forwarded to user-identity.ts's own issued-grant storage -- must resolve to the same user-identity.json userIdentity's own key material lives in. */
+    userIdentityOptions?: UserIdentityOptions;
+    clock: Clock;
+    tokenId: Uint8Array<ArrayBuffer>;
+    /** The grant this principal itself was admitted with (room-lifecycle.ts's admitAgentForDm, minted with delegationsRemaining \> 0) -- every one of tokens.cddl's own narrowing obligations is checked against it at mint time. */
+    parent: CapabilityToken;
+    /** The device being delegated to -- one of this principal's own devices. */
+    deviceId: DeviceId;
+    /** The remote user principal that originally admitted this identity -- the scope this delegated token must keep naming, unchanged from parent's own scope (tokens.cddl's own narrowing requires an identical "user" scope path down the whole chain). */
+    remoteUserPrincipalDeviceId: DeviceId;
+    expires: number;
+    /** How many further hops the delegated token itself permits below it -- defaults to LEAF_NOT_DELEGABLE; only worth raising for a hierarchy deeper than "principal delegates directly to a device" genuinely needs. */
+    delegationsRemaining?: number;
+}
+/**
+ * Mints deviceId's own dm:send delegation from a received grant: bearer = deviceId, parent = the grant this principal itself was admitted with, scope unchanged (still the REMOTE admitting principal's own "user" scope, never this principal's own device-id) -- mintCapabilityToken's own narrowing refuses this outright if parent's own delegationsRemaining was 0 (nothing left to sub-delegate) or if userIdentity does not match parent's own bearer. On success, records the token-id under THIS principal's own issued-grant store, keyed by deviceId's hex, so a later revocation can find it -- reuses user-identity.ts's saveIssuedDmGrant/loadIssuedDmGrant/deleteIssuedDmGrant exactly as admitAgentForDm's own root-level self-grants do, since both are simply "grants this identity has issued," keyed by bearer, regardless of whether the grant is root-level or itself a delegation.
+ */
+export declare function delegateDmSendToDevice(options: Readonly<DelegateDmSendToDeviceOptions>): Promise<MintVerdict>;
+//# sourceMappingURL=dm-send-delegation.d.ts.map

package/dist/core/dm-send-delegation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dm-send-delegation.d.ts","sourceRoot":"","sources":["../../src/core/dm-send-delegation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAEL,KAAK,WAAW,EACjB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,KAAK,EACV,eAAe,EACf,QAAQ,EACT,MAAM,mCAAmC,CAAC;AAK3C,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,oBAAoB,CAAC;AAK5B,MAAM,WAAW,6BAA6B;IAC5C,+OAA+O;IAC/O,YAAY,EAAE,YAAY,CAAC;IAC3B,sLAAsL;IACtL,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAC1C,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IACjC,iOAAiO;IACjO,MAAM,EAAE,eAAe,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,EAAE,QAAQ,CAAC;IACnB,yPAAyP;IACzP,2BAA2B,EAAE,QAAQ,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,sNAAsN;IACtN,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,QAAQ,CAAC,6BAA6B,CAAC,GAC/C,OAAO,CAAC,WAAW,CAAC,CAuBtB"}

package/dist/core/dm-send-delegation.js

@@ -0,0 +1,35 @@
+/**
+ * Sub-delegation of a received dm:send grant to one of the recipient principal's own devices (agent-comms#187): once a remote user principal has been admitted into another user's DM-communication scope (room-lifecycle.ts's admitAgentForDm, minted with delegationsRemaining \> 0 specifically to allow this), that principal mints a CHILD dm:send token -- parent = the grant it received, bearer = its own device -- so a specific device can present durable admission on the principal's behalf, without the admitting side ever needing to know that device's own device-id in advance. Mirrors device-membership.ts's admitDevice in shape (a plain mint-and-record function, no MeshStore-equivalent orchestrator), but delegates an EXISTING grant via `parent` rather than self-issuing a fresh root-level one -- the first real use of mintCapabilityToken's parent-narrowing machinery in this codebase, every grant minted before this having been an independent root-level token.
+ *
+ * Deliberately does not touch the delegated device's own identity-store.ts slot, mirroring device-membership.ts's own "no assumption about locality" stance: getting the minted token onto that device (this process, or a different one) is left entirely to the caller.
+ */
+import { mintCapabilityToken, } from "wire-mesh-core/domain/tokens";
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import { DM_SEND_CAPABILITY, DM_SEND_SCOPE_KIND, } from "./dm-token-verification.js";
+import { saveIssuedDmGrant, } from "./user-identity.js";
+/** delegationsRemaining a delegated device's own token permits below it, when the caller doesn't ask for more -- 0, matching every other non-delegable grant this codebase already mints by default (device-membership.ts's own NOT_DELEGABLE): an ordinary device is a leaf of the chain, not a further delegator. */
+const LEAF_NOT_DELEGABLE = 0;
+/**
+ * Mints deviceId's own dm:send delegation from a received grant: bearer = deviceId, parent = the grant this principal itself was admitted with, scope unchanged (still the REMOTE admitting principal's own "user" scope, never this principal's own device-id) -- mintCapabilityToken's own narrowing refuses this outright if parent's own delegationsRemaining was 0 (nothing left to sub-delegate) or if userIdentity does not match parent's own bearer. On success, records the token-id under THIS principal's own issued-grant store, keyed by deviceId's hex, so a later revocation can find it -- reuses user-identity.ts's saveIssuedDmGrant/loadIssuedDmGrant/deleteIssuedDmGrant exactly as admitAgentForDm's own root-level self-grants do, since both are simply "grants this identity has issued," keyed by bearer, regardless of whether the grant is root-level or itself a delegation.
+ */
+export async function delegateDmSendToDevice(options) {
+    const verdict = await mintCapabilityToken({
+        identity: options.userIdentity,
+        clock: options.clock,
+        tokenId: options.tokenId,
+        bearer: options.deviceId,
+        capability: DM_SEND_CAPABILITY,
+        scope: {
+            kind: DM_SEND_SCOPE_KIND,
+            path: deviceIdToHex(options.remoteUserPrincipalDeviceId),
+        },
+        expires: options.expires,
+        delegationsRemaining: options.delegationsRemaining ?? LEAF_NOT_DELEGABLE,
+        parent: options.parent,
+    });
+    if (!verdict.ok)
+        return verdict;
+    saveIssuedDmGrant(options.userIdentityOptions, deviceIdToHex(options.deviceId), options.tokenId);
+    return verdict;
+}
+//# sourceMappingURL=dm-send-delegation.js.map

package/dist/core/dm-send-delegation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dm-send-delegation.js","sourceRoot":"","sources":["../../src/core/dm-send-delegation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,mBAAmB,GAEpB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAOhE,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,iBAAiB,GAElB,MAAM,oBAAoB,CAAC;AAE5B,uTAAuT;AACvT,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAoB7B;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,OAAgD;IAEhD,MAAM,OAAO,GAAG,MAAM,mBAAmB,CAAC;QACxC,QAAQ,EAAE,OAAO,CAAC,YAAY;QAC9B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,MAAM,EAAE,OAAO,CAAC,QAAQ;QACxB,UAAU,EAAE,kBAAkB;QAC9B,KAAK,EAAE;YACL,IAAI,EAAE,kBAAkB;YACxB,IAAI,EAAE,aAAa,CAAC,OAAO,CAAC,2BAA2B,CAAC;SACzD;QACD,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,oBAAoB,EAAE,OAAO,CAAC,oBAAoB,IAAI,kBAAkB;QACxE,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CAAC;IACH,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,OAAO,CAAC;IAEhC,iBAAiB,CACf,OAAO,CAAC,mBAAmB,EAC3B,aAAa,CAAC,OAAO,CAAC,QAAQ,CAAC,EAC/B,OAAO,CAAC,OAAO,CAChB,CAAC;IACF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/core/gateway-trust.d.ts

@@ -4,27 +4,42 @@
  * Persisted per bridge slot when constructed with one (agent-comms#186), mirroring identity-store.ts's own per-slot room-token/issued-grant persistence: the trusted set is loaded from that slot's own sibling JSON file (identity-store.ts's loadGatewayTrust) on construction, and written back in full (saveGatewayTrust) after every add/remove, so trust survives a gateway restart instead of needing to be re-established every run. The in-memory Set below remains the live source of truth for isTrusted/hasAny at all times; persistence is purely load-on-construct and save-on-mutate. Constructed with no slot, this class keeps the original v1 FederationManager.trustedFingerprints precedent (retired with federation.ts, commit 4232b08): in-memory only, never touching disk. Every pre-#186 construction site (most tests, and any caller with no bridge identity slot to hand) falls into this no-slot case unchanged.
  *
  * Keyed by individual device-id, not by "one entry per remote machine": wire-mesh-core's relay-hub protocol (relay-hub.ts, gossip-frame, relay-data-frame) carries no field identifying which remote gateway connection a given directory entry or relayed request actually originated from -- only the entry/request's own device-id, which may be an ordinary local peer forwarded on a remote machine's behalf rather than that machine's own coordinator. Gating per individual device-id is therefore the finest-grained, and only wire-protocol-honest, trust boundary actually implementable without a wire-mesh-core protocol change (deliberately out of scope here, matching agent-comms#156's own "gating the hub itself is out of scope" framing) -- confirmed as the intended granularity by hub-session.ts's own pre-existing isStateMutatingMessage doc comment, which already named this exact gap as "agent-comms#156's own future deliverable" of "per-peer" admission control. An operator who wants every local peer on a remote machine reachable trusts each of that machine's device-ids individually, not just its coordinator's.
+ *
+ * Principal-keyed trust (agent-comms#187): alongside the bare-device allowlist above, an operator may also trust a user-principal device-id (user-identity.ts) directly -- the root a remote peer's own dm:send-style delegation chain can terminate at, verified the same way device-membership-verification.ts already verifies a device's own group:member chain (`verifyCapabilityToken`'s chain-walk and its `rootIssuer` output). This is purely a second, parallel allowlist: `isTrusted`/`add`/`remove`/`list` keep checking only the bare-device set, unchanged, for a peer with no principal at all -- `isTrustedFor` is the additive entrypoint a caller who has already chain-verified a token uses to decide trust from that verified bearer and chain-root pair, accepting either a directly trusted device or a bearer rooted at a trusted principal. Persisted alongside the bare-device set (agent-comms#186's own persistence, extended here per that issue's own "agent-comms#187 covers what gets stored" framing): loadGatewayTrust/saveGatewayTrust now carry both sets.
  */
 import type { IdentitySlot } from "./identity-store.js";
-/** The read-only slice of GatewayTrust every consumer of the trust boundary actually needs (WireMeshTransport, HubSession, hub-forwarding.ts) -- named so call sites that only ever read trust decisions, never mutate them, don't repeat the same `Pick<GatewayTrust, "isTrusted" | "hasAny">` inline at every field/parameter that takes one. */
-export type GatewayTrustReader = Pick<GatewayTrust, "isTrusted" | "hasAny">;
+/** The read-only slice of GatewayTrust every consumer of the trust boundary actually needs (WireMeshTransport, HubSession, hub-forwarding.ts) -- named so call sites that only ever read trust decisions, never mutate them, don't repeat the same `Pick<GatewayTrust, "isTrusted" | "hasAny" | "isTrustedPrincipal" | "isTrustedFor">` inline at every field/parameter that takes one. */
+export type GatewayTrustReader = Pick<GatewayTrust, "isTrusted" | "hasAny" | "isTrustedPrincipal" | "isTrustedFor">;
 export declare class GatewayTrust {
     private readonly trusted;
+    private readonly trustedPrincipals;
     private readonly slot;
-    /** Constructs the trust boundary, optionally bound to a bridge identity slot for persistence (agent-comms#186); see this class's own doc comment for what a slot does and doesn't change. Given a slot, immediately loads whatever device-ids were trusted before the last restart into the initial in-memory set. */
+    /** Constructs the trust boundary, optionally bound to a bridge identity slot for persistence (agent-comms#186); see this class's own doc comment for what a slot does and doesn't change. Given a slot, immediately loads whatever devices and principals were trusted before the last restart into the initial in-memory sets. */
     constructor(slot?: Readonly<IdentitySlot>);
     /** Marks a remote device-id (hex, case-insensitive) as trusted: this side will merge its gossiped directory entries, dispatch its relayed requests, and route outbound hub requests to it. Idempotent. Persists the updated set when this instance was constructed with a slot. */
     add(deviceHex: string): void;
     /** Withdraws a previously trusted device-id (hex, case-insensitive). A no-op if it was never trusted. Mirrors FederationManager.removeTrustedFingerprint's own precedent: already-merged directory entries and in-flight requests are unaffected -- this governs future traffic only. Persists the updated set when this instance was constructed with a slot. */
     remove(deviceHex: string): void;
-    /** Writes the complete current trusted set back to this instance's own slot, if it was constructed with one. A no-op for the in-memory-only (no slot) case. */
+    /** Writes the complete current trusted device and principal sets back to this instance's own slot, if it was constructed with one. A no-op for the in-memory-only (no slot) case. */
     private persist;
     /** Every currently trusted device-id, lowercase hex, in insertion order. */
     list(): string[];
     /** Whether the given device-id (hex, case-insensitive) is currently trusted. */
     isTrusted(deviceHex: string): boolean;
+    /** Marks a remote user-principal device-id (hex, case-insensitive; user-identity.ts) as trusted (agent-comms#187): a peer presenting a token whose delegation chain roots at this principal is trusted via `isTrustedFor` below, without that peer's own bare device-id ever needing individual trust. Idempotent, and entirely independent of the bare-device allowlist `add` manages. Persists the updated set when this instance was constructed with a slot. */
+    addPrincipal(deviceHex: string): void;
+    /** Withdraws a previously trusted principal (hex, case-insensitive). A no-op if it was never trusted. Governs future chain checks only, mirroring `remove`'s own already-merged-traffic-is-unaffected posture. Persists the updated set when this instance was constructed with a slot. */
+    removePrincipal(deviceHex: string): void;
+    /** Every currently trusted principal device-id, lowercase hex, in insertion order. */
+    listPrincipals(): string[];
+    /** Whether the given device-id (hex, case-insensitive) is currently trusted as a user principal. */
+    isTrustedPrincipal(deviceHex: string): boolean;
+    /**
+     * Whether a peer is trusted, given a token's own bearer and chain-root device-ids (hex, case-insensitive) a caller has already chain-verified via `verifyCapabilityToken` (the same `rootIssuer` output device-membership-verification.ts's own chain check already relies on). Passes when the bearer itself is directly trusted (the existing bare-device path, unmodified for a peer with no principal at all), OR when the chain's root is a trusted principal -- so a device sub-delegated from an admitted principal (mirroring agent-comms#161's own "principal admits its own devices" pattern) is trusted without ever being individually allowlisted. This class performs no cryptographic verification itself; the caller supplies already-verified device-ids, keeping GatewayTrust the same plain allowlist it always was.
+     */
+    isTrustedFor(bearerHex: string, rootIssuerHex: string): boolean;
     /**
-     * Whether at least one remote device is currently trusted -- the outbound gossip gate. wire-mesh-core's relay-hub broadcasts a gossiped advert to every connected hub peer with no per-recipient targeting (RelayHub.handleConnection's own "re-broadcasts each gossip frame to every other connected client"), so "advertise local agents only to allowlisted remote gateways" can only be approximated at the coarse granularity this side actually controls: don't advertise anything at all until the operator has opted in by trusting at least one remote device. Once true, an advertisement still reaches every hub-connected peer, trusted or not -- the per-device isTrusted() check above is what keeps this side from ACTING on anything an untrusted peer sends back, which is the boundary that actually matters.
+     * Whether at least one remote device or principal is currently trusted -- the outbound gossip gate. wire-mesh-core's relay-hub broadcasts a gossiped advert to every connected hub peer with no per-recipient targeting (RelayHub.handleConnection's own "re-broadcasts each gossip frame to every other connected client"), so "advertise local agents only to allowlisted remote gateways" can only be approximated at the coarse granularity this side actually controls: don't advertise anything at all until the operator has opted in by trusting at least one remote device or principal. Once true, an advertisement still reaches every hub-connected peer, trusted or not -- the per-device isTrusted()/isTrustedFor() checks above are what keep this side from ACTING on anything an untrusted peer sends back, which is the boundary that actually matters.
      */
     hasAny(): boolean;
 }

package/dist/core/gateway-trust.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway-trust.d.ts","sourceRoot":"","sources":["../../src/core/gateway-trust.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD,mVAAmV;AACnV,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,YAAY,EAAE,WAAW,GAAG,QAAQ,CAAC,CAAC;AAE5E,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqC;IAE1D,sTAAsT;gBAC1S,IAAI,CAAC,EAAE,QAAQ,CAAC,YAAY,CAAC;IASzC,mRAAmR;IACnR,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAK5B,kWAAkW;IAClW,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAK/B,+JAA+J;IAC/J,OAAO,CAAC,OAAO;IAIf,4EAA4E;IAC5E,IAAI,IAAI,MAAM,EAAE;IAIhB,gFAAgF;IAChF,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIrC;;OAEG;IACH,MAAM,IAAI,OAAO;CAGlB"}
+{"version":3,"file":"gateway-trust.d.ts","sourceRoot":"","sources":["../../src/core/gateway-trust.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD,2XAA2X;AAC3X,MAAM,MAAM,kBAAkB,GAAG,IAAI,CACnC,YAAY,EACZ,WAAW,GAAG,QAAQ,GAAG,oBAAoB,GAAG,cAAc,CAC/D,CAAC;AAEF,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAqB;IACvD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqC;IAE1D,mUAAmU;gBACvT,IAAI,CAAC,EAAE,QAAQ,CAAC,YAAY,CAAC;IAazC,mRAAmR;IACnR,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAK5B,kWAAkW;IAClW,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAK/B,qLAAqL;IACrL,OAAO,CAAC,OAAO;IAMf,4EAA4E;IAC5E,IAAI,IAAI,MAAM,EAAE;IAIhB,gFAAgF;IAChF,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIrC,ocAAoc;IACpc,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAKrC,2RAA2R;IAC3R,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAKxC,sFAAsF;IACtF,cAAc,IAAI,MAAM,EAAE;IAI1B,oGAAoG;IACpG,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAI9C;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO;IAI/D;;OAEG;IACH,MAAM,IAAI,OAAO;CAGlB"}

package/dist/core/gateway-trust.js

@@ -1,14 +1,19 @@
 import { loadGatewayTrust, saveGatewayTrust } from "./identity-store.js";
 export class GatewayTrust {
     trusted = new Set();
+    trustedPrincipals = new Set();
     slot;
-    /** Constructs the trust boundary, optionally bound to a bridge identity slot for persistence (agent-comms#186); see this class's own doc comment for what a slot does and doesn't change. Given a slot, immediately loads whatever device-ids were trusted before the last restart into the initial in-memory set. */
+    /** Constructs the trust boundary, optionally bound to a bridge identity slot for persistence (agent-comms#186); see this class's own doc comment for what a slot does and doesn't change. Given a slot, immediately loads whatever devices and principals were trusted before the last restart into the initial in-memory sets. */
     constructor(slot) {
         this.slot = slot;
         if (slot !== undefined) {
-            for (const deviceHex of loadGatewayTrust(slot)) {
+            const loaded = loadGatewayTrust(slot);
+            for (const deviceHex of loaded.devices) {
                 this.trusted.add(deviceHex);
             }
+            for (const principalHex of loaded.principals) {
+                this.trustedPrincipals.add(principalHex);
+            }
         }
     }
     /** Marks a remote device-id (hex, case-insensitive) as trusted: this side will merge its gossiped directory entries, dispatch its relayed requests, and route outbound hub requests to it. Idempotent. Persists the updated set when this instance was constructed with a slot. */
@@ -21,10 +26,11 @@ export class GatewayTrust {
         this.trusted.delete(deviceHex.toLowerCase());
         this.persist();
     }
-    /** Writes the complete current trusted set back to this instance's own slot, if it was constructed with one. A no-op for the in-memory-only (no slot) case. */
+    /** Writes the complete current trusted device and principal sets back to this instance's own slot, if it was constructed with one. A no-op for the in-memory-only (no slot) case. */
     persist() {
-        if (this.slot !== undefined)
-            saveGatewayTrust(this.slot, this.list());
+        if (this.slot !== undefined) {
+            saveGatewayTrust(this.slot, this.list(), this.listPrincipals());
+        }
     }
     /** Every currently trusted device-id, lowercase hex, in insertion order. */
     list() {
@@ -34,11 +40,35 @@ export class GatewayTrust {
     isTrusted(deviceHex) {
         return this.trusted.has(deviceHex.toLowerCase());
     }
+    /** Marks a remote user-principal device-id (hex, case-insensitive; user-identity.ts) as trusted (agent-comms#187): a peer presenting a token whose delegation chain roots at this principal is trusted via `isTrustedFor` below, without that peer's own bare device-id ever needing individual trust. Idempotent, and entirely independent of the bare-device allowlist `add` manages. Persists the updated set when this instance was constructed with a slot. */
+    addPrincipal(deviceHex) {
+        this.trustedPrincipals.add(deviceHex.toLowerCase());
+        this.persist();
+    }
+    /** Withdraws a previously trusted principal (hex, case-insensitive). A no-op if it was never trusted. Governs future chain checks only, mirroring `remove`'s own already-merged-traffic-is-unaffected posture. Persists the updated set when this instance was constructed with a slot. */
+    removePrincipal(deviceHex) {
+        this.trustedPrincipals.delete(deviceHex.toLowerCase());
+        this.persist();
+    }
+    /** Every currently trusted principal device-id, lowercase hex, in insertion order. */
+    listPrincipals() {
+        return [...this.trustedPrincipals];
+    }
+    /** Whether the given device-id (hex, case-insensitive) is currently trusted as a user principal. */
+    isTrustedPrincipal(deviceHex) {
+        return this.trustedPrincipals.has(deviceHex.toLowerCase());
+    }
+    /**
+     * Whether a peer is trusted, given a token's own bearer and chain-root device-ids (hex, case-insensitive) a caller has already chain-verified via `verifyCapabilityToken` (the same `rootIssuer` output device-membership-verification.ts's own chain check already relies on). Passes when the bearer itself is directly trusted (the existing bare-device path, unmodified for a peer with no principal at all), OR when the chain's root is a trusted principal -- so a device sub-delegated from an admitted principal (mirroring agent-comms#161's own "principal admits its own devices" pattern) is trusted without ever being individually allowlisted. This class performs no cryptographic verification itself; the caller supplies already-verified device-ids, keeping GatewayTrust the same plain allowlist it always was.
+     */
+    isTrustedFor(bearerHex, rootIssuerHex) {
+        return this.isTrusted(bearerHex) || this.isTrustedPrincipal(rootIssuerHex);
+    }
     /**
-     * Whether at least one remote device is currently trusted -- the outbound gossip gate. wire-mesh-core's relay-hub broadcasts a gossiped advert to every connected hub peer with no per-recipient targeting (RelayHub.handleConnection's own "re-broadcasts each gossip frame to every other connected client"), so "advertise local agents only to allowlisted remote gateways" can only be approximated at the coarse granularity this side actually controls: don't advertise anything at all until the operator has opted in by trusting at least one remote device. Once true, an advertisement still reaches every hub-connected peer, trusted or not -- the per-device isTrusted() check above is what keeps this side from ACTING on anything an untrusted peer sends back, which is the boundary that actually matters.
+     * Whether at least one remote device or principal is currently trusted -- the outbound gossip gate. wire-mesh-core's relay-hub broadcasts a gossiped advert to every connected hub peer with no per-recipient targeting (RelayHub.handleConnection's own "re-broadcasts each gossip frame to every other connected client"), so "advertise local agents only to allowlisted remote gateways" can only be approximated at the coarse granularity this side actually controls: don't advertise anything at all until the operator has opted in by trusting at least one remote device or principal. Once true, an advertisement still reaches every hub-connected peer, trusted or not -- the per-device isTrusted()/isTrustedFor() checks above are what keep this side from ACTING on anything an untrusted peer sends back, which is the boundary that actually matters.
      */
     hasAny() {
-        return this.trusted.size > 0;
+        return this.trusted.size > 0 || this.trustedPrincipals.size > 0;
     }
 }
 //# sourceMappingURL=gateway-trust.js.map

package/dist/core/gateway-trust.js.map

@@ -1 +1 @@
-{"version":3,"file":"gateway-trust.js","sourceRoot":"","sources":["../../src/core/gateway-trust.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAKzE,MAAM,OAAO,YAAY;IACN,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAC5B,IAAI,CAAqC;IAE1D,sTAAsT;IACtT,YAAY,IAA6B;QACvC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,KAAK,MAAM,SAAS,IAAI,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC/C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;IACH,CAAC;IAED,mRAAmR;IACnR,GAAG,CAAC,SAAiB;QACnB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;QAC1C,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAED,kWAAkW;IAClW,MAAM,CAAC,SAAiB;QACtB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;QAC7C,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAED,+JAA+J;IACvJ,OAAO;QACb,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;YAAE,gBAAgB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACxE,CAAC;IAED,4EAA4E;IAC5E,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IAED,gFAAgF;IAChF,SAAS,CAAC,SAAiB;QACzB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;IACnD,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC;IAC/B,CAAC;CACF"}
+{"version":3,"file":"gateway-trust.js","sourceRoot":"","sources":["../../src/core/gateway-trust.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAQzE,MAAM,OAAO,YAAY;IACN,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAC5B,iBAAiB,GAAG,IAAI,GAAG,EAAU,CAAC;IACtC,IAAI,CAAqC;IAE1D,mUAAmU;IACnU,YAAY,IAA6B;QACvC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;YACtC,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBACvC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC9B,CAAC;YACD,KAAK,MAAM,YAAY,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;gBAC7C,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;IACH,CAAC;IAED,mRAAmR;IACnR,GAAG,CAAC,SAAiB;QACnB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;QAC1C,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAED,kWAAkW;IAClW,MAAM,CAAC,SAAiB;QACtB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;QAC7C,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAED,qLAAqL;IAC7K,OAAO;QACb,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC5B,gBAAgB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IAED,gFAAgF;IAChF,SAAS,CAAC,SAAiB;QACzB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;IACnD,CAAC;IAED,ocAAoc;IACpc,YAAY,CAAC,SAAiB;QAC5B,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAED,2RAA2R;IAC3R,eAAe,CAAC,SAAiB;QAC/B,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;QACvD,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAED,sFAAsF;IACtF,cAAc;QACZ,OAAO,CAAC,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAAC;IACrC,CAAC;IAED,oGAAoG;IACpG,kBAAkB,CAAC,SAAiB;QAClC,OAAO,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,SAAiB,EAAE,aAAqB;QACnD,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAC;IAC7E,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,IAAI,IAAI,CAAC,iBAAiB,CAAC,IAAI,GAAG,CAAC,CAAC;IAClE,CAAC;CACF"}

package/dist/core/identity-store.d.ts

@@ -62,12 +62,36 @@ export declare function loadIssuedRoomGrant(slot: Readonly<IdentitySlot>, roomPa
 export declare function saveIssuedRoomGrant(slot: Readonly<IdentitySlot>, roomPath: string, memberDeviceHex: string, tokenId: Uint8Array): void;
 /** Removes the recorded token-id for one (roomPath, member) grant, if any -- called once a kick has revoked it, so a later re-join mints and records a genuinely fresh one rather than leaving a stale entry alongside it. A no-op if none was recorded. */
 export declare function deleteIssuedRoomGrant(slot: Readonly<IdentitySlot>, roomPath: string, memberDeviceHex: string): void;
+/** loadGatewayTrust's own return shape: every remote device-id and every remote user-principal device-id (agent-comms#187) this slot's gateway currently trusts, each lowercase hex, in insertion order. */
+export interface LoadedGatewayTrust {
+    devices: string[];
+    principals: string[];
+}
+/**
+ * The trusted devices and principals (agent-comms#187) a slot's gateway had persisted before this call, both empty if the slot has never saved a trusted set or its gateway trust file is missing or unparseable. Reads a pre-#187 file (a bare JSON array, agent-comms#186's own original format) as devices-only with no principals -- every gateway-trust file written before principal-keyed trust existed named only bare devices, so there is nothing to migrate, just an older, narrower shape to keep reading correctly.
+ */
+export declare function loadGatewayTrust(slot: Readonly<IdentitySlot>): LoadedGatewayTrust;
+/**
+ * Persists a slot's complete trusted-gateway device-id and principal-id sets (agent-comms#187 extends agent-comms#186's own original device-only persistence, per that issue's own "agent-comms#187 covers what gets stored" framing), surviving a restart the same way the identity they gate alongside does. Overwrites whatever was saved before in full: GatewayTrust always calls this with its own current list()/listPrincipals() after every add/remove/addPrincipal/removePrincipal, so there is no per-entry partial update to preserve here the way saveRoomToken preserves other rooms' tokens.
+ */
+export declare function saveGatewayTrust(slot: Readonly<IdentitySlot>, devices: readonly string[], principals: readonly string[]): void;
+/** A generated connection code's own persisted record (agent-comms#188): everything ConnectionCode carries except its own nonce, which is this record's key instead of a repeated field. */
+export interface StoredConnectionCode {
+    expiresAt: string;
+    deviceId: string;
+    signature?: string;
+}
+/** A slot's own connection-code ledger (agent-comms#188): every code this slot has generated (still outstanding, so the artifact survives a restart between generation and hand-off) and every nonce this slot has redeemed (so a restart can't reopen a single-use code to a second redemption within its own short validity window). Two independent halves of one bootstrap flow, not a request/response pair -- a generated code's own record here is never consulted by whichever remote slot later redeems it, since redemption validates the code's four self-contained fields directly rather than calling back to its issuer. */
+export interface ConnectionCodeLedgerData {
+    issued: Record<string, StoredConnectionCode>;
+    redeemed: Record<string, string>;
+}
 /**
- * Every remote device-id this slot's gateway currently trusts, lowercase hex, in insertion order. Empty if the slot has never saved a trusted set, or its gateway trust file is missing or unparseable.
+ * A slot's currently persisted connection-code ledger: every code it has issued, keyed by nonce, and every nonce it has redeemed, mapped to that code's own expiresAt (kept only so a stale entry can be pruned once its expiry has passed, the same reason issued entries carry their own expiresAt). Both halves default to empty if the slot has never saved a ledger, or its ledger file is missing or unparseable.
  */
-export declare function loadGatewayTrust(slot: Readonly<IdentitySlot>): string[];
+export declare function loadConnectionCodeLedger(slot: Readonly<IdentitySlot>): ConnectionCodeLedgerData;
 /**
- * Persists a slot's complete trusted-gateway device-id set, surviving a restart the same way the identity it gates alongside does. Overwrites whatever was saved before in full: GatewayTrust always calls this with its own current list() after every add/remove, so there is no per-device partial update to preserve here the way saveRoomToken preserves other rooms' tokens.
+ * Persists a slot's complete connection-code ledger, surviving a restart the same way the identity it bootstraps trust for does. Overwrites whatever was saved before in full: ConnectionCodeLedger always calls this with its own current issued/redeemed maps after every generate/redeem, so there is no per-code partial update to preserve here the way saveRoomToken preserves other rooms' tokens.
  */
-export declare function saveGatewayTrust(slot: Readonly<IdentitySlot>, trusted: readonly string[]): void;
+export declare function saveConnectionCodeLedger(slot: Readonly<IdentitySlot>, ledger: Readonly<ConnectionCodeLedgerData>): void;
 //# sourceMappingURL=identity-store.d.ts.map

package/dist/core/identity-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"identity-store.d.ts","sourceRoot":"","sources":["../../src/core/identity-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAQzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AA2ID,4UAA4U;AAC5U,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,CAAC,YAAY,CAAC,GAAG,MAAM,CAIhE;AAuCD;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,QAAQ,CAAC,YAAY,CAAC,GAC3B,YAAY,CAgBd;AAkDD;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,QAAQ,CAAC,YAAY,CAAC,GAC3B,MAAM,GAAG,SAAS,CAKpB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,QAAQ,CAAC,YAAY,CAAC,GAC3B,YAAY,CAId;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,CAAC,YAAY,CAAC,GAAG,IAAI,CAKtE;AAuBD;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,QAAQ,CAAC,YAAY,CAAC,GAC3B,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CASjC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC5B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,eAAe,GACrB,IAAI,CAaN;AAED,sGAAsG;AACtG,wBAAgB,eAAe,CAC7B,IAAI,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC5B,QAAQ,EAAE,MAAM,GACf,IAAI,CAUN;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,QAAQ,CAAC,YAAY,CAAC,GAC3B,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CASjC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC5B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,eAAe,GACrB,IAAI,CAaN;AAED,6JAA6J;AAC7J,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC5B,SAAS,EAAE,MAAM,GAChB,IAAI,CAUN;AAMD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC5B,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GACtB,UAAU,CAAC,WAAW,CAAC,GAAG,SAAS,CAQrC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC5B,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,UAAU,GAClB,IAAI,CAcN;AAED,4PAA4P;AAC5P,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC5B,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GACtB,IAAI,CASN;AASD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,CAAC,YAAY,CAAC,GAAG,MAAM,EAAE,CASvE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC5B,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,IAAI,CAQN"}
+{"version":3,"file":"identity-store.d.ts","sourceRoot":"","sources":["../../src/core/identity-store.ts"],"names":[],"mappings":"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"}

package/dist/core/identity-store.js

@@ -376,8 +376,11 @@ function gatewayTrustFilePath(slot) {
     const base = `gateway-trust-${slot.harness}--${slugifyCwd(slot.cwd)}`;
     return path.join(dir, `${base}.json`);
 }
+function isStringArray(value) {
+    return (Array.isArray(value) && value.every((entry) => typeof entry === "string"));
+}
 /**
- * Every remote device-id this slot's gateway currently trusts, lowercase hex, in insertion order. Empty if the slot has never saved a trusted set, or its gateway trust file is missing or unparseable.
+ * The trusted devices and principals (agent-comms#187) a slot's gateway had persisted before this call, both empty if the slot has never saved a trusted set or its gateway trust file is missing or unparseable. Reads a pre-#187 file (a bare JSON array, agent-comms#186's own original format) as devices-only with no principals -- every gateway-trust file written before principal-keyed trust existed named only bare devices, so there is nothing to migrate, just an older, narrower shape to keep reading correctly.
  */
 export function loadGatewayTrust(slot) {
     let parsed;
@@ -385,18 +388,89 @@ export function loadGatewayTrust(slot) {
         parsed = JSON.parse(fs.readFileSync(gatewayTrustFilePath(slot), "utf-8"));
     }
     catch {
-        return [];
+        return { devices: [], principals: [] };
+    }
+    if (isStringArray(parsed))
+        return { devices: parsed, principals: [] };
+    if (typeof parsed !== "object" || parsed === null) {
+        return { devices: [], principals: [] };
+    }
+    const devices = "devices" in parsed && isStringArray(parsed.devices) ? parsed.devices : [];
+    const principals = "principals" in parsed && isStringArray(parsed.principals)
+        ? parsed.principals
+        : [];
+    return { devices, principals };
+}
+/**
+ * Persists a slot's complete trusted-gateway device-id and principal-id sets (agent-comms#187 extends agent-comms#186's own original device-only persistence, per that issue's own "agent-comms#187 covers what gets stored" framing), surviving a restart the same way the identity they gate alongside does. Overwrites whatever was saved before in full: GatewayTrust always calls this with its own current list()/listPrincipals() after every add/remove/addPrincipal/removePrincipal, so there is no per-entry partial update to preserve here the way saveRoomToken preserves other rooms' tokens.
+ */
+export function saveGatewayTrust(slot, devices, principals) {
+    const { dir } = slotPaths(slot);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const stored = {
+        devices: [...devices],
+        principals: [...principals],
+    };
+    fs.writeFileSync(gatewayTrustFilePath(slot), `${JSON.stringify(stored, null, 2)}\n`, { encoding: "utf-8", mode: 0o600 });
+}
+/** A slot's own connection-code ledger lives in its own sibling JSON file, mirroring gatewayTrustFilePath's own reasoning: the ledger has no dependency on this slot's own key material, so ConnectionCodeLedger can be constructed against a slot before or independently of that slot's identity ever being loaded. */
+function connectionCodesFilePath(slot) {
+    const { dir } = slotPaths(slot);
+    const base = `connection-codes-${slot.harness}--${slugifyCwd(slot.cwd)}`;
+    return path.join(dir, `${base}.json`);
+}
+function isStoredConnectionCode(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if (!("expiresAt" in value) || !("deviceId" in value))
+        return false;
+    if (typeof value.expiresAt !== "string" || typeof value.deviceId !== "string")
+        return false;
+    if ("signature" in value && typeof value.signature !== "string")
+        return false;
+    return true;
+}
+/**
+ * A slot's currently persisted connection-code ledger: every code it has issued, keyed by nonce, and every nonce it has redeemed, mapped to that code's own expiresAt (kept only so a stale entry can be pruned once its expiry has passed, the same reason issued entries carry their own expiresAt). Both halves default to empty if the slot has never saved a ledger, or its ledger file is missing or unparseable.
+ */
+export function loadConnectionCodeLedger(slot) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(connectionCodesFilePath(slot), "utf-8"));
+    }
+    catch {
+        return { issued: {}, redeemed: {} };
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return { issued: {}, redeemed: {} };
+    const issuedRaw = "issued" in parsed &&
+        typeof parsed.issued === "object" &&
+        parsed.issued !== null
+        ? parsed.issued
+        : {};
+    const redeemedRaw = "redeemed" in parsed &&
+        typeof parsed.redeemed === "object" &&
+        parsed.redeemed !== null
+        ? parsed.redeemed
+        : {};
+    const issued = {};
+    for (const [nonce, record] of Object.entries(issuedRaw)) {
+        if (isStoredConnectionCode(record))
+            issued[nonce] = record;
+    }
+    const redeemed = {};
+    for (const [nonce, expiresAt] of Object.entries(redeemedRaw)) {
+        if (typeof expiresAt === "string")
+            redeemed[nonce] = expiresAt;
     }
-    if (!Array.isArray(parsed))
-        return [];
-    return parsed.filter((entry) => typeof entry === "string");
+    return { issued, redeemed };
 }
 /**
- * Persists a slot's complete trusted-gateway device-id set, surviving a restart the same way the identity it gates alongside does. Overwrites whatever was saved before in full: GatewayTrust always calls this with its own current list() after every add/remove, so there is no per-device partial update to preserve here the way saveRoomToken preserves other rooms' tokens.
+ * Persists a slot's complete connection-code ledger, surviving a restart the same way the identity it bootstraps trust for does. Overwrites whatever was saved before in full: ConnectionCodeLedger always calls this with its own current issued/redeemed maps after every generate/redeem, so there is no per-code partial update to preserve here the way saveRoomToken preserves other rooms' tokens.
  */
-export function saveGatewayTrust(slot, trusted) {
+export function saveConnectionCodeLedger(slot, ledger) {
     const { dir } = slotPaths(slot);
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-    fs.writeFileSync(gatewayTrustFilePath(slot), `${JSON.stringify(trusted, null, 2)}\n`, { encoding: "utf-8", mode: 0o600 });
+    fs.writeFileSync(connectionCodesFilePath(slot), `${JSON.stringify(ledger, null, 2)}\n`, { encoding: "utf-8", mode: 0o600 });
 }
 //# sourceMappingURL=identity-store.js.map