safehands-pharos 1.5.0 → 2.8.0

package/dist/lib/observability/sanitize.js

@@ -0,0 +1,228 @@
+// ─── Activity Sanitization ─────────────────────────────────────────────
+// Builds a PUBLIC, sanitized activity item from a decision/analysis request +
+// its response payload. The cardinal rule: a strict field WHITELIST — we never
+// spread a request body or response into the item. Only coarse, non-sensitive
+// derivatives are kept:
+//   • decision / riskLevel / network / chainId / readOnly / executionAvailable
+//   • a short reason summary (with any long hex redacted)
+//   • a coarse target (type + shortened address + 4-byte selector + short txHash)
+//   • evidence TYPE names only (never their values)
+// Never stored: full payloads, full addresses, full calldata, full URLs, full
+// x402 payment requests, private keys, signatures, raw signed txs, API keys,
+// secret RPC URLs, sensitive headers, wallet secrets.
+// Pure + offline. No signing/wallet/write primitives anywhere in this file.
+// ────────────────────────────────────────────────────────────────────────
+import { randomBytes } from "node:crypto";
+import { getActiveNetwork, getActiveNetworkName } from "../networks.js";
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+const TXHASH_RE = /^0x[0-9a-fA-F]{64}$/;
+// Any 0x hex run of 8+ nibbles (addresses, hashes, calldata) embedded in text.
+const LONG_HEX_RE = /0x[0-9a-fA-F]{8,}/g;
+const REASON_MAX = 160;
+/** Names of evidence blocks we may report as PRESENT (never their contents). */
+const EVIDENCE_KEYS = [
+    "ecosystemEvidence",
+    "rpcEvidence",
+    "gasEvidence",
+    "pharosEvidence",
+    "canonicalContractEvidence",
+    "tokenRegistryEvidence",
+];
+function shortenHex(value) {
+    return `${value.slice(0, 6)}…${value.slice(-4)}`;
+}
+/** `0x1234…cdef` for a valid 20-byte address, else null. */
+export function shortenAddress(value) {
+    return typeof value === "string" && ADDRESS_RE.test(value) ? shortenHex(value) : null;
+}
+/** `0x1234…cdef` for a valid 32-byte tx hash, else null. */
+export function shortenTxHash(value) {
+    return typeof value === "string" && TXHASH_RE.test(value) ? shortenHex(value) : null;
+}
+/** 4-byte selector `0x########` from calldata, else null. */
+export function selectorOf(data) {
+    if (typeof data !== "string" || !data.startsWith("0x") || data.length < 10)
+        return null;
+    return data.slice(0, 10).toLowerCase();
+}
+/** Replace any long 0x hex run with a shortened form so no full hex leaks via text. */
+export function redactLongHex(text) {
+    return text.replace(LONG_HEX_RE, (m) => shortenHex(m));
+}
+// Pull a candidate value from common request shapes (direct, or nested under the
+// agent/a2a action keys), reading ONLY whitelisted scalar fields.
+function pickNested(body, key) {
+    if (!body || typeof body !== "object")
+        return undefined;
+    const b = body;
+    if (typeof b[key] === "string")
+        return b[key];
+    for (const wrap of ["intent", "requestedAction", "action"]) {
+        const inner = b[wrap];
+        if (inner && typeof inner === "object" && typeof inner[key] === "string") {
+            return inner[key];
+        }
+    }
+    return undefined;
+}
+function pickAddress(body) {
+    return (pickNested(body, "to") ?? pickNested(body, "address") ?? pickNested(body, "spender"));
+}
+function pickData(body) {
+    return pickNested(body, "data");
+}
+function pickTxHash(body) {
+    return pickNested(body, "txHash");
+}
+function hasUrl(body) {
+    return typeof pickNested(body, "url") === "string" || typeof pickNested(body, "paymentAmountUsdc") === "string";
+}
+function hasText(body) {
+    return typeof pickNested(body, "text") === "string";
+}
+function evidenceTypesOf(payload) {
+    const found = new Set();
+    const scan = (obj) => {
+        if (!obj || typeof obj !== "object")
+            return;
+        const o = obj;
+        for (const k of EVIDENCE_KEYS)
+            if (o[k] != null)
+                found.add(k);
+    };
+    scan(payload);
+    if (payload && typeof payload === "object") {
+        const p = payload;
+        scan(p.details);
+        scan(p.evidence);
+        if (Array.isArray(p.analyzers)) {
+            for (const a of p.analyzers) {
+                scan(a);
+                if (a && typeof a === "object")
+                    scan(a.details);
+            }
+        }
+    }
+    return [...found];
+}
+function reportedTargetType(payload) {
+    if (!payload || typeof payload !== "object")
+        return null;
+    const p = payload;
+    const fromDetails = (d) => {
+        if (d && typeof d === "object") {
+            const t = d.targetType;
+            if (t === "contract" || t === "eoa")
+                return t;
+        }
+        return null;
+    };
+    if (Array.isArray(p.analyzers)) {
+        for (const a of p.analyzers) {
+            if (a && typeof a === "object") {
+                const t = fromDetails(a.details);
+                if (t)
+                    return t;
+            }
+        }
+    }
+    return fromDetails(p.details);
+}
+function deriveTargetType(body, payload) {
+    const reported = reportedTargetType(payload);
+    if (reported === "contract" || reported === "eoa")
+        return reported;
+    if (typeof pickNested(body, "address") === "string")
+        return "contract";
+    if (pickTxHash(body))
+        return "tx";
+    if (hasUrl(body))
+        return "url";
+    if (hasText(body))
+        return "text";
+    const data = pickData(body);
+    if (typeof data === "string" && data.length > 2)
+        return "contract";
+    if (pickAddress(body))
+        return "address";
+    return "none";
+}
+function str(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function firstReason(payload) {
+    if (!payload || typeof payload !== "object")
+        return "";
+    const p = payload;
+    if (typeof p.summary === "string")
+        return p.summary;
+    if (Array.isArray(p.reasons) && typeof p.reasons[0] === "string")
+        return p.reasons[0];
+    if (p.details && typeof p.details === "object") {
+        const d = p.details;
+        if (typeof d.reason === "string")
+            return d.reason;
+    }
+    return "";
+}
+/**
+ * Build a sanitized {@link ActivityItem}. Reads only whitelisted derivatives —
+ * the raw body/payload are NEVER copied into the result.
+ */
+export function toActivityItem(input) {
+    const { endpoint, callerType, requestId, body, payload } = input;
+    const p = (payload && typeof payload === "object" ? payload : {});
+    const network = str(p.network) ?? getActiveNetworkName();
+    const chainId = typeof p.chainId === "number" ? p.chainId : getActiveNetwork().chainId;
+    const checkType = endpoint.startsWith("/analyze/")
+        ? endpoint.slice("/analyze/".length)
+        : endpoint === "/guardian/check"
+            ? str(pickNested(body, "inputType")) ?? "evm"
+            : null;
+    const target = {
+        type: deriveTargetType(body, payload),
+        addressShort: shortenAddress(pickAddress(body)),
+        selector: selectorOf(pickData(body)),
+        txHashShort: shortenTxHash(pickTxHash(body) ?? payload?.txHash),
+    };
+    const access = input.access;
+    return {
+        id: randomBytes(8).toString("hex"),
+        ts: new Date().toISOString(),
+        requestId,
+        endpoint,
+        callerType,
+        accessTier: access?.callerType ?? "anonymous",
+        keyId: access?.keyId ?? null,
+        agentId: access?.agentId ?? null,
+        a2aPeerId: access?.a2aPeerId ?? null,
+        policyPreset: str(p.policyPreset),
+        network,
+        chainId,
+        checkType,
+        intentType: str(p.intent),
+        decision: str(p.decision),
+        riskLevel: str(p.riskLevel),
+        reasonSummary: redactLongHex(firstReason(payload)).slice(0, REASON_MAX),
+        evidenceTypes: evidenceTypesOf(payload),
+        readOnly: p.readOnly === false ? false : true,
+        executionAvailable: p.executionAvailable === true,
+        target,
+        preparedTransactionId: str(pickNested(body, "preparedTransactionId")),
+        preparedTransactionHashShort: shortenTxHash(pickNested(body, "preparedTransactionHash")),
+        broadcastStatus: str(p.broadcastStatus),
+        attestationStatus: str(p.attestationStatus),
+        executionStatus: str(p.executionStatus),
+    };
+}
+/** Map an endpoint path to its caller category for activity/logging. */
+export function callerTypeForEndpoint(endpoint) {
+    if (endpoint === "/agent/a2a/check")
+        return "a2a";
+    if (endpoint === "/agent/check")
+        return "agent";
+    if (endpoint === "/guardian/check" || endpoint === "/prepare/tx" || endpoint === "/wallet/prepare" || endpoint === "/broadcast/signed" || endpoint.startsWith("/analyze/"))
+        return "api";
+    return "unknown";
+}
+//# sourceMappingURL=sanitize.js.map

package/dist/lib/observability/sanitize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.js","sourceRoot":"","sources":["../../../src/lib/observability/sanitize.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,8EAA8E;AAC9E,+EAA+E;AAC/E,8EAA8E;AAC9E,wBAAwB;AACxB,+EAA+E;AAC/E,0DAA0D;AAC1D,kFAAkF;AAClF,oDAAoD;AACpD,8EAA8E;AAC9E,6EAA6E;AAC7E,sDAAsD;AACtD,4EAA4E;AAC5E,2EAA2E;AAE3E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AA0DxE,MAAM,UAAU,GAAG,qBAAqB,CAAC;AACzC,MAAM,SAAS,GAAG,qBAAqB,CAAC;AACxC,+EAA+E;AAC/E,MAAM,WAAW,GAAG,oBAAoB,CAAC;AAEzC,MAAM,UAAU,GAAG,GAAG,CAAC;AAEvB,gFAAgF;AAChF,MAAM,aAAa,GAAG;IACpB,mBAAmB;IACnB,aAAa;IACb,aAAa;IACb,gBAAgB;IAChB,2BAA2B;IAC3B,uBAAuB;CACf,CAAC;AAEX,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACnD,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACxF,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACvF,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,EAAE;QAAE,OAAO,IAAI,CAAC;IACxF,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;AACzC,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,iFAAiF;AACjF,kEAAkE;AAClE,SAAS,UAAU,CAAC,IAAa,EAAE,GAAW;IAC5C,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACxD,MAAM,CAAC,GAAG,IAA+B,CAAC;IAC1C,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC;IAC9C,KAAK,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,iBAAiB,EAAE,QAAQ,CAAC,EAAE,CAAC;QAC3D,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAQ,KAAiC,CAAC,GAAG,CAAC,KAAK,QAAQ,EAAE,CAAC;YACtG,OAAQ,KAAiC,CAAC,GAAG,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,WAAW,CAAC,IAAa;IAChC,OAAO,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,CAE/E,CAAC;AAChB,CAAC;AACD,SAAS,QAAQ,CAAC,IAAa;IAC7B,OAAO,UAAU,CAAC,IAAI,EAAE,MAAM,CAAuB,CAAC;AACxD,CAAC;AACD,SAAS,UAAU,CAAC,IAAa;IAC/B,OAAO,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAuB,CAAC;AAC1D,CAAC;AACD,SAAS,MAAM,CAAC,IAAa;IAC3B,OAAO,OAAO,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,QAAQ,IAAI,OAAO,UAAU,CAAC,IAAI,EAAE,mBAAmB,CAAC,KAAK,QAAQ,CAAC;AAClH,CAAC;AACD,SAAS,OAAO,CAAC,IAAa;IAC5B,OAAO,OAAO,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,QAAQ,CAAC;AACtD,CAAC;AAED,SAAS,eAAe,CAAC,OAAgB;IACvC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,MAAM,IAAI,GAAG,CAAC,GAAY,EAAQ,EAAE;QAClC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO;QAC5C,MAAM,CAAC,GAAG,GAA8B,CAAC;QACzC,KAAK,MAAM,CAAC,IAAI,aAAa;YAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI;gBAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAChE,CAAC,CAAC;IACF,IAAI,CAAC,OAAO,CAAC,CAAC;IACd,IAAI,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC3C,MAAM,CAAC,GAAG,OAAkC,CAAC;QAC7C,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAChB,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QACjB,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC;YAC/B,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC;gBAC5B,IAAI,CAAC,CAAC,CAAC,CAAC;gBACR,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ;oBAAE,IAAI,CAAE,CAA6B,CAAC,OAAO,CAAC,CAAC;YAC/E,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;AACpB,CAAC;AAED,SAAS,kBAAkB,CAAC,OAAgB;IAC1C,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzD,MAAM,CAAC,GAAG,OAAkC,CAAC;IAC7C,MAAM,WAAW,GAAG,CAAC,CAAU,EAAiB,EAAE;QAChD,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC/B,MAAM,CAAC,GAAI,CAA6B,CAAC,UAAU,CAAC;YACpD,IAAI,CAAC,KAAK,UAAU,IAAI,CAAC,KAAK,KAAK;gBAAE,OAAO,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IACF,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC;QAC/B,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC;YAC5B,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;gBAC/B,MAAM,CAAC,GAAG,WAAW,CAAE,CAA6B,CAAC,OAAO,CAAC,CAAC;gBAC9D,IAAI,CAAC;oBAAE,OAAO,CAAC,CAAC;YAClB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAa,EAAE,OAAgB;IACvD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC7C,IAAI,QAAQ,KAAK,UAAU,IAAI,QAAQ,KAAK,KAAK;QAAE,OAAO,QAAQ,CAAC;IACnE,IAAI,OAAO,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,KAAK,QAAQ;QAAE,OAAO,UAAU,CAAC;IACvE,IAAI,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,IAAI,MAAM,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/B,IAAI,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC;IACjC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,UAAU,CAAC;IACnE,IAAI,WAAW,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,GAAG,CAAC,KAAc;IACzB,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AACtE,CAAC;AAED,SAAS,WAAW,CAAC,OAAgB;IACnC,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACvD,MAAM,CAAC,GAAG,OAAkC,CAAC;IAC7C,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC,OAAO,CAAC;IACpD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACtF,IAAI,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC/C,MAAM,CAAC,GAAG,CAAC,CAAC,OAAkC,CAAC;QAC/C,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ;YAAE,OAAO,CAAC,CAAC,MAAM,CAAC;IACpD,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAqBD;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,KAAyB;IACtD,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IACjE,MAAM,CAAC,GAAG,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAE,OAAmC,CAAC,CAAC,CAAC,EAAE,CAG5F,CAAC;IAEF,MAAM,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC;IACzD,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,gBAAgB,EAAE,CAAC,OAAO,CAAC;IAEvF,MAAM,SAAS,GAAG,QAAQ,CAAC,UAAU,CAAC,WAAW,CAAC;QAChD,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC;QACpC,CAAC,CAAC,QAAQ,KAAK,iBAAiB;YAC9B,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,IAAI,KAAK;YAC7C,CAAC,CAAC,IAAI,CAAC;IAEX,MAAM,MAAM,GAAmB;QAC7B,IAAI,EAAE,gBAAgB,CAAC,IAAI,EAAE,OAAO,CAAC;QACrC,YAAY,EAAE,cAAc,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC/C,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACpC,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,IAAK,OAAe,EAAE,MAAM,CAAC;KACzE,CAAC;IAEF,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,OAAO;QACL,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;QAClC,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,SAAS;QACT,QAAQ;QACR,UAAU;QACV,UAAU,EAAE,MAAM,EAAE,UAAU,IAAI,WAAW;QAC7C,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,IAAI;QAC5B,OAAO,EAAE,MAAM,EAAE,OAAO,IAAI,IAAI;QAChC,SAAS,EAAE,MAAM,EAAE,SAAS,IAAI,IAAI;QACpC,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC;QACjC,OAAO;QACP,OAAO;QACP,SAAS;QACT,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;QACzB,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;QACzB,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3B,aAAa,EAAE,aAAa,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC;QACvE,aAAa,EAAE,eAAe,CAAC,OAAO,CAAC;QACvC,QAAQ,EAAE,CAAC,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI;QAC7C,kBAAkB,EAAE,CAAC,CAAC,kBAAkB,KAAK,IAAI;QACjD,MAAM;QACN,qBAAqB,EAAE,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,uBAAuB,CAAC,CAAC;QACrE,4BAA4B,EAAE,aAAa,CAAC,UAAU,CAAC,IAAI,EAAE,yBAAyB,CAAC,CAAC;QACxF,eAAe,EAAE,GAAG,CAAC,CAAC,CAAC,eAAe,CAAC;QACvC,iBAAiB,EAAE,GAAG,CAAC,CAAC,CAAC,iBAAiB,CAAC;QAC3C,eAAe,EAAE,GAAG,CAAC,CAAC,CAAC,eAAe,CAAC;KACxC,CAAC;AACJ,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,IAAI,QAAQ,KAAK,kBAAkB;QAAE,OAAO,KAAK,CAAC;IAClD,IAAI,QAAQ,KAAK,cAAc;QAAE,OAAO,OAAO,CAAC;IAChD,IAAI,QAAQ,KAAK,iBAAiB,IAAI,QAAQ,KAAK,aAAa,IAAI,QAAQ,KAAK,iBAAiB,IAAI,QAAQ,KAAK,mBAAmB,IAAI,QAAQ,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,KAAK,CAAC;IACzL,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/lib/observability/scopes.d.ts

@@ -0,0 +1,20 @@
+export type Scope = "guardian:check" | "agent:check" | "a2a:check" | "analyze:read" | "activity:read" | "metrics:read" | "prepare:tx" | "wallet:prepare" | "broadcast:signed" | "future:attest" | "future:premium";
+export declare const ALL_SCOPES: readonly Scope[];
+/** Default read bundle a bare API key receives (backward-compatible). No future:* scopes.
+ *  `prepare:tx` and `wallet:prepare` are read-only (build UNSIGNED / wallet-ready requests
+ *  only — never sign or broadcast). */
+export declare const DEFAULT_READ_SCOPES: readonly Scope[];
+/** Reserved future scopes — defined only; never granted by default; no live endpoint. */
+export declare const FUTURE_SCOPES: readonly Scope[];
+/** Endpoint path → the scope it requires (only enforced in require-key mode). */
+export declare const ENDPOINT_SCOPES: Readonly<Record<string, Scope>>;
+export declare function isScope(value: string): value is Scope;
+/** The required scope for a path, or null if the path has no scope mapping. */
+export declare function scopeForPath(path: string): Scope | null;
+export declare function hasScope(scopes: ReadonlySet<Scope> | null | undefined, scope: Scope): boolean;
+/**
+ * Parse a `scopeA|scopeB` string into a Set of known scopes. Unknown tokens are
+ * dropped (fail-closed: an unrecognized scope grants nothing).
+ */
+export declare function parseScopes(raw: string): Set<Scope>;
+//# sourceMappingURL=scopes.d.ts.map

package/dist/lib/observability/scopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../../../src/lib/observability/scopes.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,KAAK,GACb,gBAAgB,GAChB,aAAa,GACb,WAAW,GACX,cAAc,GACd,eAAe,GACf,cAAc,GACd,YAAY,GACZ,gBAAgB,GAChB,kBAAkB,GAClB,eAAe,GACf,gBAAgB,CAAC;AAErB,eAAO,MAAM,UAAU,EAAE,SAAS,KAAK,EAYtC,CAAC;AAEF;;uCAEuC;AACvC,eAAO,MAAM,mBAAmB,EAAE,SAAS,KAAK,EAS/C,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,aAAa,EAAE,SAAS,KAAK,EAAwC,CAAC;AAEnF,iFAAiF;AACjF,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAiB3D,CAAC;AAEF,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,KAAK,CAErD;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAEvD;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAE7F;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,CAOnD"}

package/dist/lib/observability/scopes.js

@@ -0,0 +1,77 @@
+// ─── API Key Scopes ──────────────────────────────────────────────
+// Scope vocabulary for the optional API-key access-control layer. Scopes are
+// identity/access-control only — never payment. `future:*` scopes are DEFINED
+// here for forward-compatibility but are NOT granted by default and have NO live
+// endpoint behind scoped API keys. Pure constants + helpers; no I/O, no secrets.
+// ────────────────────────────────────────────────────────────────────────
+export const ALL_SCOPES = [
+    "guardian:check",
+    "agent:check",
+    "a2a:check",
+    "analyze:read",
+    "activity:read",
+    "metrics:read",
+    "prepare:tx",
+    "wallet:prepare",
+    "broadcast:signed",
+    "future:attest",
+    "future:premium",
+];
+/** Default read bundle a bare API key receives (backward-compatible). No future:* scopes.
+ *  `prepare:tx` and `wallet:prepare` are read-only (build UNSIGNED / wallet-ready requests
+ *  only — never sign or broadcast). */
+export const DEFAULT_READ_SCOPES = [
+    "guardian:check",
+    "agent:check",
+    "a2a:check",
+    "analyze:read",
+    "activity:read",
+    "metrics:read",
+    "prepare:tx",
+    "wallet:prepare",
+];
+/** Reserved future scopes — defined only; never granted by default; no live endpoint. */
+export const FUTURE_SCOPES = ["future:attest", "future:premium"];
+/** Endpoint path → the scope it requires (only enforced in require-key mode). */
+export const ENDPOINT_SCOPES = {
+    "/guardian/check": "guardian:check",
+    "/prepare/tx": "prepare:tx",
+    "/wallet/prepare": "wallet:prepare",
+    "/broadcast/signed": "broadcast:signed",
+    "/agent/check": "agent:check",
+    "/agent/a2a/check": "a2a:check",
+    "/analyze/tx": "analyze:read",
+    "/analyze/contract": "analyze:read",
+    "/analyze/approval": "analyze:read",
+    "/analyze/safe": "analyze:read",
+    "/analyze/x402": "analyze:read",
+    "/activity/summary": "activity:read",
+    "/activity/recent": "activity:read",
+    "/metrics/public": "metrics:read",
+    "/infra/status": "metrics:read",
+    "/public-config": "metrics:read",
+};
+export function isScope(value) {
+    return ALL_SCOPES.includes(value);
+}
+/** The required scope for a path, or null if the path has no scope mapping. */
+export function scopeForPath(path) {
+    return ENDPOINT_SCOPES[path] ?? null;
+}
+export function hasScope(scopes, scope) {
+    return scopes != null && scopes.has(scope);
+}
+/**
+ * Parse a `scopeA|scopeB` string into a Set of known scopes. Unknown tokens are
+ * dropped (fail-closed: an unrecognized scope grants nothing).
+ */
+export function parseScopes(raw) {
+    const out = new Set();
+    for (const token of raw.split("|")) {
+        const t = token.trim();
+        if (t && isScope(t))
+            out.add(t);
+    }
+    return out;
+}
+//# sourceMappingURL=scopes.js.map

package/dist/lib/observability/scopes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.js","sourceRoot":"","sources":["../../../src/lib/observability/scopes.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,6EAA6E;AAC7E,8EAA8E;AAC9E,iFAAiF;AACjF,iFAAiF;AACjF,2EAA2E;AAe3E,MAAM,CAAC,MAAM,UAAU,GAAqB;IAC1C,gBAAgB;IAChB,aAAa;IACb,WAAW;IACX,cAAc;IACd,eAAe;IACf,cAAc;IACd,YAAY;IACZ,gBAAgB;IAChB,kBAAkB;IAClB,eAAe;IACf,gBAAgB;CACjB,CAAC;AAEF;;uCAEuC;AACvC,MAAM,CAAC,MAAM,mBAAmB,GAAqB;IACnD,gBAAgB;IAChB,aAAa;IACb,WAAW;IACX,cAAc;IACd,eAAe;IACf,cAAc;IACd,YAAY;IACZ,gBAAgB;CACjB,CAAC;AAEF,yFAAyF;AACzF,MAAM,CAAC,MAAM,aAAa,GAAqB,CAAC,eAAe,EAAE,gBAAgB,CAAC,CAAC;AAEnF,iFAAiF;AACjF,MAAM,CAAC,MAAM,eAAe,GAAoC;IAC9D,iBAAiB,EAAE,gBAAgB;IACnC,aAAa,EAAE,YAAY;IAC3B,iBAAiB,EAAE,gBAAgB;IACnC,mBAAmB,EAAE,kBAAkB;IACvC,cAAc,EAAE,aAAa;IAC7B,kBAAkB,EAAE,WAAW;IAC/B,aAAa,EAAE,cAAc;IAC7B,mBAAmB,EAAE,cAAc;IACnC,mBAAmB,EAAE,cAAc;IACnC,eAAe,EAAE,cAAc;IAC/B,eAAe,EAAE,cAAc;IAC/B,mBAAmB,EAAE,eAAe;IACpC,kBAAkB,EAAE,eAAe;IACnC,iBAAiB,EAAE,cAAc;IACjC,eAAe,EAAE,cAAc;IAC/B,gBAAgB,EAAE,cAAc;CACjC,CAAC;AAEF,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,OAAQ,UAAgC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC3D,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,eAAe,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,MAA6C,EAAE,KAAY;IAClF,OAAO,MAAM,IAAI,IAAI,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAS,CAAC;IAC7B,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/lib/okxDexApi.d.ts

@@ -0,0 +1,106 @@
+export interface OkxSwapApiResponse {
+    code: string;
+    msg?: string;
+    data: Array<{
+        routerResult?: {
+            fromTokenAmount?: string | number;
+            toTokenAmount?: string | number;
+            priceImpactPercent?: string | number;
+            estimateGasFee?: string | number;
+        };
+        tx?: {
+            to?: string;
+            data?: string;
+            value?: string | number;
+            gas?: string | number;
+            minReceiveAmount?: string | number;
+        };
+    }> | null;
+}
+/** Structurally compatible with DodoQuote for every field execute_swap reads. */
+export interface OkxQuote {
+    amountOut: string;
+    amountOutWei: string;
+    priceImpact: number;
+    gasLimit: string;
+    value: string;
+    calldata: string;
+    to: string;
+    approveAddress: string;
+    routeAvailable: boolean;
+    sourceStatus: "ok" | "no_route_available" | "auth_required" | "unavailable";
+    usedFromToken: string;
+    usedToToken: string;
+    wasSubstituted: boolean;
+    substitutionNote?: string;
+    /** Aggregator-enforced minimum output after slippage, in smallest units. */
+    minReceiveAmountWei: string;
+    rawResponse: OkxSwapApiResponse;
+}
+/**
+ * Structured "provider not configured for this chain" failure. Callers must
+ * surface this as SWAP_LIQUIDITY_NOT_CONFIGURED: a permanent configuration
+ * state, not a transient provider outage.
+ */
+export declare class OkxNotConfiguredError extends Error {
+    readonly code: "SWAP_LIQUIDITY_NOT_CONFIGURED";
+    constructor(chainId: number);
+}
+/**
+ * Structured "credentials not configured" failure raised BEFORE any network
+ * call. Lists only the missing env var NAMES, never any credential value.
+ */
+export declare class OkxCredentialsMissingError extends Error {
+    readonly code: "OKX_API_CREDENTIALS_MISSING";
+    readonly missing: string[];
+    constructor(missing: string[]);
+}
+/**
+ * Chains the OKX DEX aggregator API is treated as configured for. Defaults to
+ * Pacific Mainnet (1672) only: OKX's supported-chains docs list Pharos with
+ * chainIndex 1672, and no Pharos testnet is listed. Any other chain fails
+ * closed until an operator opts in via OKX_API_SUPPORTED_CHAIN_IDS with
+ * evidence the API supports it.
+ */
+export declare function okxApiSupportedChainIds(): number[];
+export declare function isOkxApiConfiguredForChain(chainId?: number): boolean;
+/**
+ * Computes the OK-ACCESS-SIGN header value: Base64(HMAC-SHA256(prehash, secret))
+ * with prehash = timestamp + method + requestPath (+ body for POST). The
+ * requestPath must include the query string.
+ */
+export declare function signOkxRequest(params: {
+    timestamp: string;
+    method: "GET" | "POST";
+    requestPath: string;
+    body?: string;
+    secret: string;
+}): string;
+/**
+ * Builds the v6 swap request path (endpoint + query string) in a fixed
+ * parameter order so the signed string is deterministic and testable.
+ */
+export declare function buildOkxSwapRequestPath(params: {
+    chainId: number;
+    fromTokenAddress: string;
+    toTokenAddress: string;
+    amountWei: string;
+    userWalletAddress: string;
+    slippagePercent: number;
+}): string;
+/**
+ * Fetches an executable swap quote from the OKX DEX aggregator. The returned
+ * `to`/`calldata` come from the aggregator and MUST still be contained by the
+ * caller against the OKX router allowlist; the approve address is the
+ * registry-verified OKX token-approve contract (OKX's approval model always
+ * targets that dedicated contract; the swap response itself does not carry a
+ * spender field).
+ */
+export declare function getOkxSwapQuote(params: {
+    fromToken: string;
+    toToken: string;
+    amountHuman: string;
+    walletAddress: string;
+    slippage?: number;
+}): Promise<OkxQuote>;
+//# sourceMappingURL=okxDexApi.d.ts.map

package/dist/lib/okxDexApi.d.ts.map

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