@drakon-systems/ekho-sdk 0.6.2 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to Ekho are documented here.
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-10-12
+
+### Added
+- **`@drakon-systems/ekho-sdk/identity`**: the verifiable-identity layer (Ed25519 primitives with the frozen canonical form, the identity file with atomic save and refuse-to-mint rules, inbound verification, operator-key pin sync, outbound v2 signing), moved verbatim from the OpenClaw plugin so the plugin and the new MCP connector run the identical code. Published for both `import` (`dist/esm/identity`) and `require` (`dist/identity`). The root export is unchanged; nothing existing is removed or renamed, so this is not a breaking change.
+
 ## [0.6.2] - 2026-10-08
 
 ### Changed

package/README.md

@@ -6,6 +6,10 @@ Agent SDK for [Ekho](https://github.com/Drakon-Systems-Ltd/ekho) — the private
 
 What changed in this version: [CHANGELOG.md](./CHANGELOG.md). The changelog ships inside the published package, so a consumer can read it after `npm install` without visiting GitHub.
 
+## Identity layer
+
+`@drakon-systems/ekho-sdk/identity` is the verifiable-identity layer every TypeScript Ekho agent shares: Ed25519 primitives with the frozen canonical form, the identity file (`loadOrCreateIdentity`, `saveIdentity`: atomic owner-only writes, no re-minting unless told to), inbound verification (`verifyInbound`, `verifyBatch`), operator-key pin sync with the first-contact latch and signed revocation (`syncPinnedOperatorKeys`) and outbound v2 signing (`buildSignedSendFields`). The OpenClaw plugin and the MCP connector both run this code. It has no dependencies beyond `node:crypto`.
+
 ## Compatibility
 
 - **0.4.1 — breaking (#12).** Post to a room with `recipient: {kind: "group", id: <room id>}`. Any other recipient kind under a room `conversation_id` is now a 400.

package/dist/esm/identity/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./primitives.js";
+export * from "./verify.js";
+export * from "./store.js";
+export * from "./verification.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/identity/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/identity/index.ts"],"names":[],"mappings":"AAMA,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC"}

package/dist/esm/identity/index.js

@@ -0,0 +1,11 @@
+// `@drakon-systems/ekho-sdk/identity` — the verifiable-identity layer every
+// TypeScript Ekho agent shares: Ed25519 primitives with the frozen canonical
+// form, the identity file (atomic save, refuse-to-mint rules), inbound
+// verification, operator-key pin sync and outbound signing. Extracted from the
+// OpenClaw plugin so the MCP connector signs and verifies with the identical
+// code rather than a copy that can drift.
+export * from "./primitives.js";
+export * from "./verify.js";
+export * from "./store.js";
+export * from "./verification.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/identity/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/identity/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,6EAA6E;AAC7E,uEAAuE;AACvE,+EAA+E;AAC/E,6EAA6E;AAC7E,0CAA0C;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC"}

package/dist/esm/identity/primitives.d.ts

@@ -0,0 +1,53 @@
+/** Deterministic JSON: keys sorted, no insignificant whitespace, UTF-8. */
+export declare function canonicalize(value: unknown): string;
+export declare function b64url(bytes: Uint8Array): string;
+export declare function fromB64url(s: string): Uint8Array;
+/** base64url(sha256(pub))[:16] — stable short id for a public key. */
+export declare function keyId(publicKey: Uint8Array): string;
+export declare function sha256Hex(text: string): string;
+/** Raw base64url public key for a 32-byte Ed25519 seed. */
+export declare function publicKeyB64urlFromSeed(seed: Uint8Array): string;
+/** Sign the canonical form of `payload` with a 32-byte Ed25519 seed. */
+export declare function signCanonical(payload: unknown, seed: Uint8Array): string;
+/** Verify `sig` over the canonical form of `payload`. Never throws. */
+export declare function verifyCanonical(payload: unknown, sig: string, publicKey: Uint8Array): boolean;
+/** Structure an existing operator key signs to endorse a NEW operator key. */
+export declare function endorsementPayload(fleetId: string, newKeyId: string, newPublicKeyB64url: string): {
+    v: number;
+    t: string;
+    fleet_id: string;
+    key_id: string;
+    public_key: string;
+};
+/** Structure an operator key signs to REVOKE an operator key (#27).
+ *  Revocation mutates the trust root exactly as adoption does, so it needs the
+ *  same proof: an unsigned relay `revoked:true` flag is advisory only. */
+export declare function revocationPayload(fleetId: string, revokedKeyId: string, revokedAt: string): {
+    v: number;
+    t: string;
+    fleet_id: string;
+    key_id: string;
+    revoked_at: string;
+};
+/** Structure an operator key signs to UN-REVOKE a key (#27 / #48).
+ *  Binds the revocation being undone, issue time, and a nonce so a captured
+ *  un-revoke cannot clear a later tombstone. Never re-pins. */
+export declare function unrevokePayload(fleetId: string, revokedKeyId: string, revokedAtBeingCleared: string, issuedAt: string, nonce: string): {
+    v: number;
+    t: string;
+    fleet_id: string;
+    key_id: string;
+    revoked_at_being_cleared: string;
+    issued_at: string;
+    nonce: string;
+};
+/** Structure the operator signs to endorse an AGENT's identity key (peer trust). */
+export declare function agentKeyEndorsementPayload(fleetId: string, agentId: string, agentKeyId: string, agentPublicKeyB64url: string): {
+    v: number;
+    t: string;
+    fleet_id: string;
+    agent_id: string;
+    key_id: string;
+    public_key: string;
+};
+//# sourceMappingURL=primitives.d.ts.map

package/dist/esm/identity/primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../../src/identity/primitives.ts"],"names":[],"mappings":"AAQA,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMnD;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAEhD;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAEhD;AAsBD,sEAAsE;AACtE,wBAAgB,KAAK,CAAC,SAAS,EAAE,UAAU,GAAG,MAAM,CAEnD;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,2DAA2D;AAC3D,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAGhE;AAED,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAGxE;AAED,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,GAAG,OAAO,CAW7F;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM;;;;;;EAQ/F;AAED;;0EAE0E;AAC1E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;;;;;;EAQzF;AAED;;+DAE+D;AAC/D,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,qBAAqB,EAAE,MAAM,EAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM;;;;;;;;EAcd;AAED,oFAAoF;AACpF,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,oBAAoB,EAAE,MAAM;;;;;;;EAU7B"}

package/dist/esm/identity/primitives.js

@@ -0,0 +1,116 @@
+// Verifiable identity core shared by every TypeScript Ekho agent (OpenClaw plugin, MCP connector) — Node built-in crypto, so no
+// ESM-only dependency under NodeNext. Its canonical serialization MUST match the
+// TS relay (noble) and the Python plugin (cryptography) byte-for-byte; the frozen
+// interop vector (packages/relay/tests/fixtures/operator-identity-vector.json)
+// pins that contract.
+import crypto from "node:crypto";
+/** Deterministic JSON: keys sorted, no insignificant whitespace, UTF-8. */
+export function canonicalize(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return "[" + value.map(canonicalize).join(",") + "]";
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalize(obj[k])).join(",") + "}";
+}
+export function b64url(bytes) {
+    return Buffer.from(bytes).toString("base64url");
+}
+export function fromB64url(s) {
+    return new Uint8Array(Buffer.from(s, "base64url"));
+}
+// Standard DER prefixes for raw 32-byte Ed25519 keys.
+const PKCS8_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+const SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+function privFromSeed(seed) {
+    return crypto.createPrivateKey({
+        key: Buffer.concat([PKCS8_PREFIX, Buffer.from(seed)]),
+        format: "der",
+        type: "pkcs8",
+    });
+}
+function pubFromRaw(publicKey) {
+    return crypto.createPublicKey({
+        key: Buffer.concat([SPKI_PREFIX, Buffer.from(publicKey)]),
+        format: "der",
+        type: "spki",
+    });
+}
+/** base64url(sha256(pub))[:16] — stable short id for a public key. */
+export function keyId(publicKey) {
+    return b64url(crypto.createHash("sha256").update(Buffer.from(publicKey)).digest()).slice(0, 16);
+}
+export function sha256Hex(text) {
+    return crypto.createHash("sha256").update(Buffer.from(text, "utf8")).digest("hex");
+}
+/** Raw base64url public key for a 32-byte Ed25519 seed. */
+export function publicKeyB64urlFromSeed(seed) {
+    const jwk = crypto.createPublicKey(privFromSeed(seed)).export({ format: "jwk" });
+    return jwk.x; // JWK OKP x is already base64url-encoded raw public key
+}
+/** Sign the canonical form of `payload` with a 32-byte Ed25519 seed. */
+export function signCanonical(payload, seed) {
+    const sig = crypto.sign(null, Buffer.from(canonicalize(payload), "utf8"), privFromSeed(seed));
+    return Buffer.from(sig).toString("base64url");
+}
+/** Verify `sig` over the canonical form of `payload`. Never throws. */
+export function verifyCanonical(payload, sig, publicKey) {
+    try {
+        return crypto.verify(null, Buffer.from(canonicalize(payload), "utf8"), pubFromRaw(publicKey), Buffer.from(sig, "base64url"));
+    }
+    catch {
+        return false;
+    }
+}
+/** Structure an existing operator key signs to endorse a NEW operator key. */
+export function endorsementPayload(fleetId, newKeyId, newPublicKeyB64url) {
+    return {
+        v: 1,
+        t: "op-key-endorsement",
+        fleet_id: fleetId,
+        key_id: newKeyId,
+        public_key: newPublicKeyB64url,
+    };
+}
+/** Structure an operator key signs to REVOKE an operator key (#27).
+ *  Revocation mutates the trust root exactly as adoption does, so it needs the
+ *  same proof: an unsigned relay `revoked:true` flag is advisory only. */
+export function revocationPayload(fleetId, revokedKeyId, revokedAt) {
+    return {
+        v: 1,
+        t: "op-key-revocation",
+        fleet_id: fleetId,
+        key_id: revokedKeyId,
+        revoked_at: revokedAt,
+    };
+}
+/** Structure an operator key signs to UN-REVOKE a key (#27 / #48).
+ *  Binds the revocation being undone, issue time, and a nonce so a captured
+ *  un-revoke cannot clear a later tombstone. Never re-pins. */
+export function unrevokePayload(fleetId, revokedKeyId, revokedAtBeingCleared, issuedAt, nonce) {
+    if (!nonce) {
+        throw new Error("unrevoke nonce must be a non-empty string");
+    }
+    return {
+        v: 1,
+        t: "op-key-unrevoke",
+        fleet_id: fleetId,
+        key_id: revokedKeyId,
+        revoked_at_being_cleared: revokedAtBeingCleared,
+        issued_at: issuedAt,
+        nonce,
+    };
+}
+/** Structure the operator signs to endorse an AGENT's identity key (peer trust). */
+export function agentKeyEndorsementPayload(fleetId, agentId, agentKeyId, agentPublicKeyB64url) {
+    return {
+        v: 1,
+        t: "agent-key-endorsement",
+        fleet_id: fleetId,
+        agent_id: agentId,
+        key_id: agentKeyId,
+        public_key: agentPublicKeyB64url,
+    };
+}
+//# sourceMappingURL=primitives.js.map

package/dist/esm/identity/primitives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.js","sourceRoot":"","sources":["../../../src/identity/primitives.ts"],"names":[],"mappings":"AAAA,gIAAgI;AAChI,iFAAiF;AACjF,kFAAkF;AAClF,+EAA+E;AAC/E,sBAAsB;AAEtB,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC,2EAA2E;AAC3E,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IAC/E,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACrC,OAAO,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;AAC/F,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,KAAiB;IACtC,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC;AACrD,CAAC;AAED,sDAAsD;AACtD,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,kCAAkC,EAAE,KAAK,CAAC,CAAC;AAC5E,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,0BAA0B,EAAE,KAAK,CAAC,CAAC;AAEnE,SAAS,YAAY,CAAC,IAAgB;IACpC,OAAO,MAAM,CAAC,gBAAgB,CAAC;QAC7B,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,YAAY,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACrD,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,OAAO;KACd,CAAC,CAAC;AACL,CAAC;AAED,SAAS,UAAU,CAAC,SAAqB;IACvC,OAAO,MAAM,CAAC,eAAe,CAAC;QAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;QACzD,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,MAAM;KACb,CAAC,CAAC;AACL,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,KAAK,CAAC,SAAqB;IACzC,OAAO,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClG,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACrF,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,uBAAuB,CAAC,IAAgB;IACtD,MAAM,GAAG,GAAG,MAAM,CAAC,eAAe,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAkB,CAAC;IAClG,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,wDAAwD;AACxE,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,aAAa,CAAC,OAAgB,EAAE,IAAgB;IAC9D,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9F,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAChD,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,eAAe,CAAC,OAAgB,EAAE,GAAW,EAAE,SAAqB;IAClF,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,MAAM,CAClB,IAAI,EACJ,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,EAC1C,UAAU,CAAC,SAAS,CAAC,EACrB,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAC9B,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,QAAgB,EAAE,kBAA0B;IAC9F,OAAO;QACL,CAAC,EAAE,CAAC;QACJ,CAAC,EAAE,oBAAoB;QACvB,QAAQ,EAAE,OAAO;QACjB,MAAM,EAAE,QAAQ;QAChB,UAAU,EAAE,kBAAkB;KAC/B,CAAC;AACJ,CAAC;AAED;;0EAE0E;AAC1E,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,YAAoB,EAAE,SAAiB;IACxF,OAAO;QACL,CAAC,EAAE,CAAC;QACJ,CAAC,EAAE,mBAAmB;QACtB,QAAQ,EAAE,OAAO;QACjB,MAAM,EAAE,YAAY;QACpB,UAAU,EAAE,SAAS;KACtB,CAAC;AACJ,CAAC;AAED;;+DAE+D;AAC/D,MAAM,UAAU,eAAe,CAC7B,OAAe,EACf,YAAoB,EACpB,qBAA6B,EAC7B,QAAgB,EAChB,KAAa;IAEb,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO;QACL,CAAC,EAAE,CAAC;QACJ,CAAC,EAAE,iBAAiB;QACpB,QAAQ,EAAE,OAAO;QACjB,MAAM,EAAE,YAAY;QACpB,wBAAwB,EAAE,qBAAqB;QAC/C,SAAS,EAAE,QAAQ;QACnB,KAAK;KACN,CAAC;AACJ,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,0BAA0B,CACxC,OAAe,EACf,OAAe,EACf,UAAkB,EAClB,oBAA4B;IAE5B,OAAO;QACL,CAAC,EAAE,CAAC;QACJ,CAAC,EAAE,uBAAuB;QAC1B,QAAQ,EAAE,OAAO;QACjB,QAAQ,EAAE,OAAO;QACjB,MAAM,EAAE,UAAU;QAClB,UAAU,EAAE,oBAAoB;KACjC,CAAC;AACJ,CAAC"}

package/dist/esm/identity/store.d.ts

@@ -0,0 +1,67 @@
+export declare const IDENTITY_FILE = ".ekho-identity.json";
+/** Why a pinned operator key is trusted on THIS box (#26). Written at the moment
+ *  the gate admitted the key, so the question "why is this key trusted here?"
+ *  has an offline answer — no relay round trip, and nothing to re-ask the relay
+ *  for (which is exactly the party we don't trust). For a chain admission the
+ *  endorsement signature is kept verbatim, so the endorsement can be re-verified
+ *  from disk against the endorser's pinned public key. */
+export interface OperatorKeyAdmission {
+    admitted_by: "tofu" | "chain";
+    /** Chain only: the pinned key whose endorsement admitted this one. */
+    endorsed_by_key_id?: string;
+    /** Chain only: the endorsement signature this box actually verified. */
+    endorsement_sig?: string;
+    admitted_at: string;
+}
+/** The agent's own Ed25519 identity (private seed) + the operator keys it pins. */
+export interface EkhoIdentity {
+    seedHex: string;
+    pinnedOperatorKeys: Record<string, string>;
+    /** Set once, when the empty pin set trust-on-first-use adopted the relay's
+     *  operator keys (#5). Latched forever so a later emptied pin set can never
+     *  be re-seeded by whoever controls the relay at that moment. */
+    tofuAt?: string;
+    /** key_id -> ISO timestamp we first saw the relay report it revoked (#14).
+     *  A tombstone ledger, not a cache: unpinning a revoked key is worthless on
+     *  its own because the config seed, TOFU and endorsement chaining all re-add
+     *  it on the next wake. Every add path consults this, so revocation sticks. */
+    revokedOperatorKeys?: Record<string, string>;
+    /** key_id -> the evidence that admitted it (#26). */
+    operatorKeyAdmissions?: Record<string, OperatorKeyAdmission>;
+}
+/**
+ * Thrown instead of minting. Before 4 Oct 2026 an identity file that was
+ * present but unparseable, or absent on a box whose config already names an
+ * enrolled agent, silently produced a NEW random seed and registered it with
+ * the relay. Seven live "Jarvis" identity keys with no private half anywhere
+ * were found that way, each later endorsed by the operator in good faith. A
+ * key that exists only because a read failed is a forged identity, not a
+ * recovery; the caller must stop and say so.
+ */
+export declare class IdentityUnavailableError extends Error {
+    readonly reason: "unreadable" | "missing";
+    constructor(message: string, reason: "unreadable" | "missing");
+}
+/** Set to "1" to let an already-enrolled agent mint a brand-new identity key. */
+export declare const ALLOW_NEW_IDENTITY_ENV = "EKHO_ALLOW_NEW_IDENTITY";
+export interface LoadIdentityOptions {
+    /**
+     * Whether an ABSENT file may be answered with a freshly minted identity.
+     * Default true (first enrolment). Pass false for an agent whose config already
+     * carries enrolled credentials: its identity must already exist somewhere,
+     * so an absent file is a lost/moved file, not a new agent.
+     */
+    allowCreate?: boolean;
+}
+export declare function loadOrCreateIdentity(configDir: string, opts?: LoadIdentityOptions): EkhoIdentity;
+/** Byte-for-byte copy of an unusable state file, for forensics. Bytes, not a
+ *  decoded string: invalid UTF-8 must survive exactly (review, Case, 4 Oct). */
+export declare function preserveUnusableFile(filePath: string, raw: Buffer | undefined): string | undefined;
+/**
+ * Atomic: write a sibling temp file and rename it over the real one, so no
+ * reader (another plugin instance, a CLI run, the other runtime sharing this
+ * dir) can ever observe a truncated identity file mid-write.
+ */
+export declare function saveIdentity(configDir: string, identity: EkhoIdentity): void;
+export declare function identityPublicKey(identity: EkhoIdentity): string;
+//# sourceMappingURL=store.d.ts.map

package/dist/esm/identity/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/identity/store.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,aAAa,wBAAwB,CAAC;AAEnD;;;;;0DAK0D;AAC1D,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,sEAAsE;IACtE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C;;qEAEiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;mFAG+E;IAC/E,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,qDAAqD;IACrD,qBAAqB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CAC9D;AAED;;;;;;;;GAQG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IAG/C,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS;gBADzC,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,YAAY,GAAG,SAAS;CAK5C;AAED,iFAAiF;AACjF,eAAO,MAAM,sBAAsB,4BAA4B,CAAC;AAEhE,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,mBAAwB,GAAG,YAAY,CAoDpG;AAED;gFACgF;AAChF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CASlG;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,QAerE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAEhE"}

package/dist/esm/identity/store.js

@@ -0,0 +1,116 @@
+// The agent's own Ed25519 identity file: load, refuse-to-mint rules, atomic
+// save. Shared by every TypeScript Ekho agent; the OpenClaw plugin re-exports
+// it from its credentials module so its tests and callers are unchanged.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { publicKeyB64urlFromSeed } from "./primitives.js";
+export const IDENTITY_FILE = ".ekho-identity.json";
+/**
+ * Thrown instead of minting. Before 4 Oct 2026 an identity file that was
+ * present but unparseable, or absent on a box whose config already names an
+ * enrolled agent, silently produced a NEW random seed and registered it with
+ * the relay. Seven live "Jarvis" identity keys with no private half anywhere
+ * were found that way, each later endorsed by the operator in good faith. A
+ * key that exists only because a read failed is a forged identity, not a
+ * recovery; the caller must stop and say so.
+ */
+export class IdentityUnavailableError extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = "IdentityUnavailableError";
+    }
+}
+/** Set to "1" to let an already-enrolled agent mint a brand-new identity key. */
+export const ALLOW_NEW_IDENTITY_ENV = "EKHO_ALLOW_NEW_IDENTITY";
+export function loadOrCreateIdentity(configDir, opts = {}) {
+    const filePath = path.join(configDir, IDENTITY_FILE);
+    if (fs.existsSync(filePath)) {
+        let raw;
+        try {
+            raw = fs.readFileSync(filePath);
+            const data = JSON.parse(raw.toString("utf-8"));
+            if (data?.seedHex) {
+                // Spread the file FIRST: a field this build doesn't know about (written
+                // by a newer plugin, or by the other runtime sharing the config dir)
+                // survives the load/save round trip instead of being silently dropped.
+                return {
+                    ...data,
+                    seedHex: String(data.seedHex),
+                    pinnedOperatorKeys: data.pinnedOperatorKeys ?? {},
+                    ...(data.tofuAt ? { tofuAt: String(data.tofuAt) } : {}),
+                    ...(data.revokedOperatorKeys
+                        ? { revokedOperatorKeys: data.revokedOperatorKeys }
+                        : {}),
+                    ...(data.operatorKeyAdmissions
+                        ? { operatorKeyAdmissions: data.operatorKeyAdmissions }
+                        : {})
+                };
+            }
+        }
+        catch {
+            /* present but unusable: handled below, never regenerated over */
+        }
+        // The file is there but this build cannot use it (unreadable, not JSON,
+        // or no seed). Keep the bytes for forensics and refuse. Overwriting them
+        // with a new seed would both destroy the evidence and mint a second live
+        // identity for this agent on the relay.
+        const preserved = preserveUnusableFile(filePath, raw);
+        throw new IdentityUnavailableError(`[ekho] identity file ${filePath} is present but unusable; refusing to mint a replacement key` +
+            (preserved ? ` (bytes preserved at ${preserved})` : "") +
+            `. Restore the file from a backup, or remove it and set ${ALLOW_NEW_IDENTITY_ENV}=1 to enrol a new key on purpose.`, "unreadable");
+    }
+    if (opts.allowCreate === false) {
+        throw new IdentityUnavailableError(`[ekho] no identity file at ${filePath} but this agent is already enrolled; refusing to mint a new key. ` +
+            `Restore the file from a backup (the relay already holds this agent's key), or set ${ALLOW_NEW_IDENTITY_ENV}=1 to re-key on purpose.`, "missing");
+    }
+    const identity = {
+        seedHex: crypto.randomBytes(32).toString("hex"),
+        pinnedOperatorKeys: {}
+    };
+    saveIdentity(configDir, identity);
+    return identity;
+}
+/** Byte-for-byte copy of an unusable state file, for forensics. Bytes, not a
+ *  decoded string: invalid UTF-8 must survive exactly (review, Case, 4 Oct). */
+export function preserveUnusableFile(filePath, raw) {
+    if (raw === undefined)
+        return undefined;
+    const target = `${filePath}.unusable-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+    try {
+        fs.writeFileSync(target, raw, { mode: 0o600 });
+        return target;
+    }
+    catch {
+        return undefined; // best effort; the refusal is what matters
+    }
+}
+/**
+ * Atomic: write a sibling temp file and rename it over the real one, so no
+ * reader (another plugin instance, a CLI run, the other runtime sharing this
+ * dir) can ever observe a truncated identity file mid-write.
+ */
+export function saveIdentity(configDir, identity) {
+    fs.mkdirSync(configDir, { recursive: true });
+    const filePath = path.join(configDir, IDENTITY_FILE);
+    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmp, JSON.stringify(identity, null, 2), { mode: 0o600 });
+    try {
+        fs.renameSync(tmp, filePath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch {
+            /* nothing to clean */
+        }
+        throw err;
+    }
+}
+export function identityPublicKey(identity) {
+    return publicKeyB64urlFromSeed(new Uint8Array(Buffer.from(identity.seedHex, "hex")));
+}
+//# sourceMappingURL=store.js.map

package/dist/esm/identity/store.js.map

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

package/dist/esm/identity/verification.d.ts

@@ -0,0 +1,152 @@
+import { type RosterEntryLike, type SignedMessage, type VerifyResult } from "./verify.js";
+import { type EkhoIdentity } from "./store.js";
+export interface OperatorKeyEntryLike {
+    key_id?: string;
+    public_key?: string;
+    revoked?: boolean;
+    endorsed_by_key_id?: string | null;
+    endorsement_sig?: string | null;
+    /** #27: signature over revocationPayload(fleet, key_id, revoked_at) by a
+     *  currently pinned operator key. WITHOUT it, `revoked` is advisory only. */
+    revocation_sig?: string | null;
+    /** #27: the revocation time, inside the signed bytes (so the relay cannot
+     *  restate when a key died under a still-valid signature). */
+    revoked_at?: string | null;
+    /** #27 / #48: signature over unrevokePayload(fleet, key, revoked_at, issued_at, nonce). */
+    unrevoke_sig?: string | null;
+    unrevoke_revoked_at?: string | null;
+    unrevoke_issued_at?: string | null;
+    unrevoke_nonce?: string | null;
+}
+/** Where the sync reports trust-root decisions. Defaults to the console, because
+ *  a relay claiming a revocation it can't prove must never pass in silence. */
+export interface SyncLog {
+    info?: (...a: unknown[]) => void;
+    warn?: (...a: unknown[]) => void;
+}
+/** How many identical advisory polls to swallow before a reminder. ~5s poll
+ *  → a reminder about every 10 minutes, not 150k lines in a day and a half. */
+export declare const ADVISORY_REVOCATION_WARNING_SUMMARY_EVERY = 120;
+/** Process-local cap on identity+fleet throttle scopes. Eviction re-emits that
+ *  scope's next first-seen warning; it cannot mute a different live scope. */
+export declare const ADVISORY_REVOCATION_WARNING_MAX_SCOPES = 64;
+/** Test-only isolation for the process-local Map. Not plugin runtime API. */
+export declare function resetAdvisoryRevocationWarningStateForTests(): void;
+/** Update pinned operator keys from the inbox. Adds a new key ONLY if endorsed by
+ *  an already-pinned key; removes one ONLY on a SIGNED revocation. Returns true
+ *  if the identity changed (and so must be persisted).
+ *
+ *  Trust mutates in one direction only, and never on the relay's say-so (#27).
+ *  An unsigned `revoked: true` is a HINT: the key is skipped for new adoption
+ *  and the claim is logged, but nothing is written and nothing is unpinned.
+ *  Treating it as authoritative (the #14 regression) meant one poll from a
+ *  compromised relay could tombstone and unpin an entire fleet's trust root,
+ *  permanently — the tombstone survives restarts by design, so the damage was
+ *  not even recoverable by restarting against an honest relay.
+ *
+ *  One deliberate exception to "no relay TOFU" (#5): an identity that has never
+ *  pinned ANY key can't grow a chain — endorsements need an already-pinned root,
+ *  so verification stayed dormant forever on every agent nobody hand-configured
+ *  (the Aug 2026 silent-drop incident). First contact with an empty pin set
+ *  adopts the relay's current non-revoked keys as the trust root, exactly once
+ *  (tofuAt latches). Enrollment already trusts the relay this much — it accepts
+ *  the shared secret over the same channel. Pre-pinning via config/env skips
+ *  TOFU entirely and stays the stronger option. */
+export declare function syncPinnedOperatorKeys(identity: EkhoIdentity, operatorKeys: OperatorKeyEntryLike[], fleetId: string | null | undefined, log?: SyncLog): boolean;
+export declare function verifyBatch(messages: SignedMessage[], opts: {
+    identity: EkhoIdentity;
+    selfAgentId: string;
+    fleetId: string | null | undefined;
+    roster: RosterEntryLike[];
+    seenNonces: Set<string>;
+    now: Date;
+}): Record<string, VerifyResult | null>;
+/** How strictly peer messages must prove themselves before waking a turn (#5).
+ *  - "warn" (default): unsigned/unverifiable peers still wake, but are rendered
+ *    untrusted — the graceful relay-attested fallback, named for what it is.
+ *  - "require": a peer message wakes ONLY when signed and verified; anything
+ *    else is dead-lettered by the tick. Operator messages keep the explicit
+ *    relay-attested operator_trusted toggle as their unsigned fallback — that
+ *    flag is operator-set, not relay-implied, so "require" doesn't cut the
+ *    operator off on consoles that don't sign yet.
+ *  - "off": same wake behavior as "warn" (kept distinct for config clarity). */
+export type RequireSignedMode = "off" | "warn" | "require";
+export declare function parseRequireSignedMode(raw: string | undefined | null): RequireSignedMode;
+/** The execution-authority gate. Signed → act iff verified; signed-but-invalid →
+ *  blocked; unsigned → per requireSigned mode (see above). */
+export declare function shouldAutowake(msg: SignedMessage, verification: VerifyResult | null | undefined, operatorTrusted: boolean, peerEnabled: boolean, requireSigned?: RequireSignedMode): boolean;
+/** Sign an outbound peer message so recipients can verify it came from us.
+ *
+ *  v2 (#9) extends coverage to message_type, priority and the attachment ids —
+ *  previously a compromised relay could relabel a message (direct → alert) or
+ *  swap its attachments under a still-valid signature. Compatibility is free in
+ *  both directions: verifiers check the signature over the WHOLE canonical and
+ *  only bind the fields they know, so old verifiers accept v2 envelopes and new
+ *  verifiers enforce the extra bindings only when the envelope declares v>=2. */
+export declare function buildSignedSendFields(opts: {
+    identity: EkhoIdentity;
+    fleetId: string;
+    selfAgentId: string;
+    recipient: Record<string, unknown>;
+    conversationId: string;
+    bodyText: string;
+    nonce: string;
+    sentAt: string;
+    messageType: string;
+    priority: string;
+    attachments?: string[];
+}): {
+    agent_sig: string;
+    key_id: string;
+    sig_canonical: Record<string, unknown>;
+};
+/** A quoted snapshot of another message — a reply target (`reply_to`) or a
+ *  conversation-history / floor-tail entry. Since #43 the relay copies the
+ *  signature fields of the message it quotes onto the snapshot, so a snapshot
+ *  can be checked rather than merely inspected. Note the shape difference from
+ *  an inbox message: a snapshot carries `text` at the top level, not `body.text`. */
+export interface MsgSnapshotLike {
+    message_id?: string;
+    sender_agent_id?: string;
+    sender_kind?: "operator" | "agent";
+    text?: string;
+    message_type?: string;
+    priority?: string;
+    attachments?: string[];
+    operator_sig?: string | null;
+    agent_sig?: string | null;
+    key_id?: string | null;
+    sig_canonical?: Record<string, unknown> | null;
+}
+/** Verdict for one quoted snapshot: did its signature actually check out? */
+export type SnapshotVerifier = (snapshot: MsgSnapshotLike | null | undefined) => boolean;
+/** The fail-closed default (#20): when verification cannot run — no pinned
+ *  operator keys, no fleet id, no identity — every snapshot is UNVERIFIED.
+ *  Never "it has a signature field, so call it signed". */
+export declare const NO_SNAPSHOT_VERIFICATION: SnapshotVerifier;
+/**
+ * Build the snapshot verifier for one turn, from the same trust root the
+ * autowake path uses: this agent's pinned operator keys plus the batch roster.
+ *
+ * Runs the ordinary inbound verifier (`verifyInbound`) over a snapshot mapped
+ * into its `SignedMessage` shape — there is deliberately no second, laxer
+ * verifier for quoted text. Two consequences worth naming:
+ *
+ *  - An older relay that omits `sig_canonical` (or the v2-bound `message_type` /
+ *    `priority` / `attachments`) simply fails the checks, so its snapshots read
+ *    UNVERIFIED. That is the intended direction to fail in.
+ *  - The nonce set is fresh per turn rather than the live seen-nonce set. A
+ *    quote is by definition a re-presentation of a message that may already
+ *    have been delivered and had its nonce burned; the burn exists to stop a
+ *    replayed message WAKING a turn, and a snapshot can never wake one. The
+ *    staleness window is left at the verifier's default, so a snapshot replayed
+ *    from beyond it still reads UNVERIFIED.
+ */
+export declare function makeSnapshotVerifier(opts: {
+    identity?: EkhoIdentity | null;
+    selfAgentId: string;
+    fleetId: string | null | undefined;
+    roster: RosterEntryLike[];
+    now: Date;
+}): SnapshotVerifier;
+//# sourceMappingURL=verification.d.ts.map

package/dist/esm/identity/verification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification.d.ts","sourceRoot":"","sources":["../../../src/identity/verification.ts"],"names":[],"mappings":"AAeA,OAAO,EAAiB,KAAK,eAAe,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AACzG,OAAO,EAAqB,KAAK,YAAY,EAA6B,MAAM,YAAY,CAAC;AAE7F,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;iFAC6E;IAC7E,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;kEAC8D;IAC9D,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,2FAA2F;IAC3F,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;+EAC+E;AAC/E,MAAM,WAAW,OAAO;IACtB,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACjC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CAClC;AAwBD;+EAC+E;AAC/E,eAAO,MAAM,yCAAyC,MAAM,CAAC;AAC7D;8EAC8E;AAC9E,eAAO,MAAM,sCAAsC,KAAK,CAAC;AAazD,6EAA6E;AAC7E,wBAAgB,2CAA2C,IAAI,IAAI,CAElE;AAgPD;;;;;;;;;;;;;;;;;;;mDAmBmD;AACnD,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,YAAY,EACtB,YAAY,EAAE,oBAAoB,EAAE,EACpC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAClC,GAAG,GAAE,OAAiB,GACrB,OAAO,CA6FT;AAED,wBAAgB,WAAW,CACzB,QAAQ,EAAE,aAAa,EAAE,EACzB,IAAI,EAAE;IACJ,QAAQ,EAAE,YAAY,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACnC,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB,GAAG,EAAE,IAAI,CAAC;CACX,GACA,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC,CAoBrC;AAED;;;;;;;;gFAQgF;AAChF,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3D,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,iBAAiB,CAGxF;AAED;8DAC8D;AAC9D,wBAAgB,cAAc,CAC5B,GAAG,EAAE,aAAa,EAClB,YAAY,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,EAC7C,eAAe,EAAE,OAAO,EACxB,WAAW,EAAE,OAAO,EACpB,aAAa,GAAE,iBAA0B,GACxC,OAAO,CAgBT;AAED;;;;;;;iFAOiF;AACjF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAkBhF;AAED;;;;qFAIqF;AACrF,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAChD;AAED,6EAA6E;AAC7E,MAAM,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,KAAK,OAAO,CAAC;AAEzF;;2DAE2D;AAC3D,eAAO,MAAM,wBAAwB,EAAE,gBAA8B,CAAC;AAEtE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,QAAQ,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACnC,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,GAAG,EAAE,IAAI,CAAC;CACX,GAAG,gBAAgB,CAiCnB"}