safehands-pharos 1.5.0 → 2.6.0

package/dist/lib/observability/apiKey.js

@@ -0,0 +1,141 @@
+// ─── API Key Foundation (optional, access-control only) ────────────────
+// Optional identity / rate-limit / access-control foundation. NOT a payment
+// mechanism — paid endpoints use x402 gating (api/x402Gate.ts, env-gated via
+// X402_PAY_TO + X402_FACILITATOR_URL). The public read API stays OPEN by default.
+//
+// Behavior:
+//   • SAFEHANDS_API_KEYS unset/empty  ⇒ open; anonymous allowed everywhere.
+//   • Keys are hashed (sha256) at load; raw keys are never stored or returned.
+//     A request references its key only by `keyId` (hash prefix) in logs/activity.
+//   • SAFEHANDS_REQUIRE_API_KEY=true (only meaningful when keys are configured)
+//     gates the non-public endpoints; truly public endpoints stay open.
+//   • Supplying an INVALID key is always an error (401), anywhere except /health.
+// Pure + offline. No signing/wallet/write primitives.
+// ────────────────────────────────────────────────────────────────────────
+import { createHash, timingSafeEqual } from "node:crypto";
+import { DEFAULT_READ_SCOPES, parseScopes, scopeForPath, hasScope } from "./scopes.js";
+/**
+ * Endpoints that remain open even when SAFEHANDS_REQUIRE_API_KEY=true.
+ * The `/paid/*` bundle entrypoints are listed so PUBLIC x402 users/agents reach them
+ * without an API key — payment (x402), not an API key, gates those routes. (An explicitly
+ * INVALID key is still rejected everywhere except /health.)
+ */
+export const ALWAYS_OPEN_PATHS = new Set([
+    "/health",
+    "/demo",
+    "/infra/status",
+    "/public-config",
+    "/activity/summary",
+    "/activity/recent",
+    "/metrics/public",
+    "/paid/assess-risk",
+    "/paid/check-token-security",
+    "/paid/simulate-transaction",
+    "/paid/token-price",
+    "/paid/pool-info",
+    "/paid/swap-route",
+    "/paid/risk-report",
+]);
+function sha256hex(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+export function loadApiKeyConfig(env = process.env) {
+    const entries = (env.SAFEHANDS_API_KEYS ?? "")
+        .split(",")
+        .map((e) => e.trim())
+        .filter(Boolean);
+    const hashes = new Map();
+    const scopes = new Map();
+    for (const entry of entries) {
+        // Backward-compatible scoped format: `rawKey` or `rawKey#scopeA|scopeB`.
+        // Split on the FIRST `#` only; a bare key (no `#`) gets the default read bundle.
+        const hashIdx = entry.indexOf("#");
+        const rawKey = (hashIdx >= 0 ? entry.slice(0, hashIdx) : entry).trim();
+        if (!rawKey)
+            continue;
+        const scopeStr = hashIdx >= 0 ? entry.slice(hashIdx + 1) : null;
+        const hash = sha256hex(rawKey);
+        const keyId = hash.slice(0, 8);
+        hashes.set(keyId, hash);
+        scopes.set(keyId, scopeStr !== null ? parseScopes(scopeStr) : new Set(DEFAULT_READ_SCOPES));
+    }
+    const configured = hashes.size > 0;
+    return {
+        configured,
+        required: env.SAFEHANDS_REQUIRE_API_KEY === "true" && configured,
+        publicReadEnabled: env.SAFEHANDS_PUBLIC_READ_ENABLED !== "false",
+        hashes,
+        scopes,
+    };
+}
+/** Extract a presented key from `X-Api-Key` or `Authorization: Bearer <key>`. */
+export function extractApiKey(headers) {
+    const x = headers["x-api-key"];
+    const xVal = Array.isArray(x) ? x[0] : x;
+    if (typeof xVal === "string" && xVal.trim().length > 0)
+        return xVal.trim();
+    const auth = headers["authorization"];
+    const authVal = Array.isArray(auth) ? auth[0] : auth;
+    if (typeof authVal === "string") {
+        const m = /^Bearer\s+(.+)$/i.exec(authVal.trim());
+        if (m && m[1].trim().length > 0)
+            return m[1].trim();
+    }
+    return null;
+}
+function timingSafeHexEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    try {
+        return timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve a request's API-key status. Never returns the raw key. `anonymous`
+ * when none presented; `valid` (+keyId) on match; `invalid` otherwise.
+ */
+export function resolveApiKey(headers, cfg) {
+    const provided = extractApiKey(headers);
+    if (!provided)
+        return { status: "anonymous", keyId: null, scopes: null };
+    const hash = sha256hex(provided);
+    const keyId = hash.slice(0, 8);
+    const expected = cfg.hashes.get(keyId);
+    if (expected && timingSafeHexEqual(expected, hash)) {
+        return { status: "valid", keyId, scopes: cfg.scopes.get(keyId) ?? new Set() };
+    }
+    return { status: "invalid", keyId: null, scopes: null };
+}
+/**
+ * Pure access decision for a path given the resolved key + config.
+ *  • /health is always open (Railway healthcheck).
+ *  • An explicitly INVALID key is rejected everywhere else.
+ *  • ALWAYS_OPEN paths are open even when keys are required.
+ *  • When `required`, a valid key is necessary, and the key must carry the
+ *    endpoint's scope. Scope is only enforced in require-key mode; when the public
+ *    read API is open (default), scopes are recorded as identity, never gates.
+ *    (A valid resolution with `scopes` omitted skips the scope check — the live
+ *    `resolveApiKey` always populates scopes for valid keys.)
+ */
+export function evaluateAccess(path, resolution, cfg) {
+    if (path === "/health")
+        return { allow: true, code: null };
+    if (resolution.status === "invalid")
+        return { allow: false, code: "INVALID_API_KEY" };
+    if (ALWAYS_OPEN_PATHS.has(path))
+        return { allow: true, code: null };
+    if (cfg.required && resolution.status !== "valid") {
+        return { allow: false, code: "API_KEY_REQUIRED" };
+    }
+    if (cfg.required && resolution.status === "valid" && resolution.scopes) {
+        const needed = scopeForPath(path);
+        if (needed && !hasScope(resolution.scopes, needed)) {
+            return { allow: false, code: "INSUFFICIENT_SCOPE" };
+        }
+    }
+    return { allow: true, code: null };
+}
+//# sourceMappingURL=apiKey.js.map

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

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

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

@@ -0,0 +1,30 @@
+export interface RequestLogEntry {
+    ts: string;
+    level: "info" | "warn";
+    event: "request";
+    requestId: string;
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+    callerType?: string | null;
+    decision?: string | null;
+    rateLimited?: boolean;
+    /** keyId (hash prefix) only — NEVER the raw API key. */
+    apiKeyId?: string | null;
+}
+export interface LoggingConfig {
+    enabled: boolean;
+    format: "json";
+}
+/** Pure: shape a log entry into a single JSON line (no trailing newline). */
+export declare function formatRequestLog(entry: RequestLogEntry): string;
+type Sink = (line: string) => void;
+/**
+ * Emit a request log line. Never throws (logging must not affect request
+ * handling). Disabled via config so tests/dev can silence output. `sink` is
+ * injectable for tests.
+ */
+export declare function logRequest(entry: RequestLogEntry, config?: LoggingConfig, sink?: Sink): void;
+export {};
+//# sourceMappingURL=logger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/lib/observability/logger.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAE/D;AAED,KAAK,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAMnC;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,eAAe,EACtB,MAAM,GAAE,aAAiD,EACzD,IAAI,GAAE,IAAkB,GACvB,IAAI,CAON"}

package/dist/lib/observability/logger.js

@@ -0,0 +1,30 @@
+// ─── Structured Request Logger ─────────────────────────────────────────
+// One JSON line per request to stdout (Railway captures stdout). Whitelisted
+// fields ONLY — never bodies, headers, query strings, client IP, API keys,
+// private keys, full RPC URLs, or raw signed transactions. `formatRequestLog`
+// is pure (returns the line); `logRequest` is the thin, never-throw emitter
+// (mirrors the discipline of lib/auditLog.ts). No signing/wallet primitives.
+// ────────────────────────────────────────────────────────────────────────
+/** Pure: shape a log entry into a single JSON line (no trailing newline). */
+export function formatRequestLog(entry) {
+    return JSON.stringify(entry);
+}
+const defaultSink = (line) => {
+    process.stdout.write(line + "\n");
+};
+/**
+ * Emit a request log line. Never throws (logging must not affect request
+ * handling). Disabled via config so tests/dev can silence output. `sink` is
+ * injectable for tests.
+ */
+export function logRequest(entry, config = { enabled: true, format: "json" }, sink = defaultSink) {
+    if (!config.enabled)
+        return;
+    try {
+        sink(formatRequestLog(entry));
+    }
+    catch {
+        // swallow — logging must never break the response path
+    }
+}
+//# sourceMappingURL=logger.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../../src/lib/observability/logger.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,4EAA4E;AAC5E,6EAA6E;AAC7E,2EAA2E;AAuB3E,6EAA6E;AAC7E,MAAM,UAAU,gBAAgB,CAAC,KAAsB;IACrD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAID,MAAM,WAAW,GAAS,CAAC,IAAI,EAAE,EAAE;IACjC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;AACpC,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,KAAsB,EACtB,SAAwB,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,EACzD,OAAa,WAAW;IAExB,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO;IAC5B,IAAI,CAAC;QACH,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,uDAAuD;IACzD,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,33 @@
+export type QuotaTier = "anonymous" | "api-key" | "agent" | "a2a";
+export declare const QUOTA_TIERS: readonly QuotaTier[];
+export interface QuotaConfig {
+    enabled: boolean;
+    windowMs: number;
+    /** Max requests per window, per tier. */
+    max: Record<QuotaTier, number>;
+}
+export interface QuotaState {
+    tier: QuotaTier;
+    limit: number;
+    remaining: number;
+    limited: boolean;
+    /** Unix seconds at which the current window resets. */
+    resetAtSec: number;
+    /** Seconds until reset (for Retry-After). */
+    retryAfterSec: number;
+}
+/** Map an access-context callerType to a quota tier (fail-safe to anonymous). */
+export declare function tierForCaller(callerType: string): QuotaTier;
+export declare class QuotaLimiter {
+    private cfg;
+    private buckets;
+    constructor(cfg: QuotaConfig);
+    /** Reconfigure + clear state (used at server start / tests). */
+    configure(cfg: QuotaConfig): void;
+    /**
+     * Count one request against the (tier, identifier) bucket and return the
+     * resulting state. `identifier` MUST be a trusted value (keyId or IP).
+     */
+    consume(tier: QuotaTier, identifier: string, now?: number): QuotaState;
+}
+//# sourceMappingURL=quota.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"quota.d.ts","sourceRoot":"","sources":["../../../src/lib/observability/quota.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,CAAC;AAElE,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAA6C,CAAC;AAE1F,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,GAAG,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAE3D;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,GAAG,CAAc;IACzB,OAAO,CAAC,OAAO,CAAyD;gBAE5D,GAAG,EAAE,WAAW;IAI5B,gEAAgE;IAChE,SAAS,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI;IAKjC;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,UAAU;CAkBnF"}

package/dist/lib/observability/quota.js

@@ -0,0 +1,49 @@
+// ─── Tiered In-Memory Quota ──────────────────────────────────────
+// Generalizes the base in-memory rate limiter into per-caller-tier quota.
+// No Redis, no DB, no external dependency — a bounded in-memory bucket Map.
+//
+// Buckets are keyed by a TRUSTED identifier only: `key:<keyId>` for a valid API
+// key, else the client IP. Untrusted body identity (agentId/a2aPeerId) is NEVER
+// a quota key — it is gameable. The tier (anonymous | api-key | agent | a2a)
+// selects the limit. Pure logic + state; no signing/wallet/write primitives.
+// ────────────────────────────────────────────────────────────────────────
+export const QUOTA_TIERS = ["anonymous", "api-key", "agent", "a2a"];
+/** Map an access-context callerType to a quota tier (fail-safe to anonymous). */
+export function tierForCaller(callerType) {
+    return QUOTA_TIERS.includes(callerType) ? callerType : "anonymous";
+}
+export class QuotaLimiter {
+    cfg;
+    buckets = new Map();
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    /** Reconfigure + clear state (used at server start / tests). */
+    configure(cfg) {
+        this.cfg = cfg;
+        this.buckets.clear();
+    }
+    /**
+     * Count one request against the (tier, identifier) bucket and return the
+     * resulting state. `identifier` MUST be a trusted value (keyId or IP).
+     */
+    consume(tier, identifier, now = Date.now()) {
+        const limit = this.cfg.max[tier] ?? this.cfg.max.anonymous;
+        const bucketKey = `${tier}:${identifier}`;
+        let bucket = this.buckets.get(bucketKey);
+        if (!bucket || bucket.resetAt <= now) {
+            bucket = { count: 0, resetAt: now + this.cfg.windowMs };
+            this.buckets.set(bucketKey, bucket);
+        }
+        bucket.count += 1;
+        return {
+            tier,
+            limit,
+            remaining: Math.max(0, limit - bucket.count),
+            limited: bucket.count > limit,
+            resetAtSec: Math.ceil(bucket.resetAt / 1000),
+            retryAfterSec: Math.max(0, Math.ceil((bucket.resetAt - now) / 1000)),
+        };
+    }
+}
+//# sourceMappingURL=quota.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"quota.js","sourceRoot":"","sources":["../../../src/lib/observability/quota.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,0EAA0E;AAC1E,4EAA4E;AAC5E,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,6EAA6E;AAC7E,6EAA6E;AAC7E,2EAA2E;AAI3E,MAAM,CAAC,MAAM,WAAW,GAAyB,CAAC,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;AAoB1F,iFAAiF;AACjF,MAAM,UAAU,aAAa,CAAC,UAAkB;IAC9C,OAAQ,WAAiC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAE,UAAwB,CAAC,CAAC,CAAC,WAAW,CAAC;AAC3G,CAAC;AAED,MAAM,OAAO,YAAY;IACf,GAAG,CAAc;IACjB,OAAO,GAAG,IAAI,GAAG,EAA8C,CAAC;IAExE,YAAY,GAAgB;QAC1B,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED,gEAAgE;IAChE,SAAS,CAAC,GAAgB;QACxB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,IAAe,EAAE,UAAkB,EAAE,MAAc,IAAI,CAAC,GAAG,EAAE;QACnE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC;QAC3D,MAAM,SAAS,GAAG,GAAG,IAAI,IAAI,UAAU,EAAE,CAAC;QAC1C,IAAI,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACzC,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,OAAO,IAAI,GAAG,EAAE,CAAC;YACrC,MAAM,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YACxD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;QACD,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC;QAClB,OAAO;YACL,IAAI;YACJ,KAAK;YACL,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;YAC5C,OAAO,EAAE,MAAM,CAAC,KAAK,GAAG,KAAK;YAC7B,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;YAC5C,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;SACrE,CAAC;IACJ,CAAC;CACF"}

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

@@ -0,0 +1,8 @@
+export declare function isValidRequestId(value: unknown): value is string;
+/**
+ * Resolve a request id from an inbound header value. Honors a safe
+ * `X-Request-Id` if present; otherwise mints a new UUID. Array header values
+ * (duplicate headers) take the first entry.
+ */
+export declare function resolveRequestId(header?: string | string[] | null): string;
+//# sourceMappingURL=requestId.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"requestId.d.ts","sourceRoot":"","sources":["../../../src/lib/observability/requestId.ts"],"names":[],"mappings":"AAYA,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,GAAG,MAAM,CAI1E"}

package/dist/lib/observability/requestId.js

@@ -0,0 +1,24 @@
+// ─── Request ID ────────────────────────────────────────────────────────
+// Correlation id for logs + activity. Accepts a caller-supplied `X-Request-Id`
+// only when it matches a strict, safe charset (defends against header/log
+// injection); otherwise generates a fresh UUID. Pure + deterministic given its
+// input (aside from the random fallback). No secrets, no I/O.
+// ────────────────────────────────────────────────────────────────────────
+import { randomUUID } from "node:crypto";
+/** Safe inbound request-id: short, printable, no whitespace/control chars. */
+const REQUEST_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+export function isValidRequestId(value) {
+    return typeof value === "string" && REQUEST_ID_RE.test(value);
+}
+/**
+ * Resolve a request id from an inbound header value. Honors a safe
+ * `X-Request-Id` if present; otherwise mints a new UUID. Array header values
+ * (duplicate headers) take the first entry.
+ */
+export function resolveRequestId(header) {
+    const raw = Array.isArray(header) ? header[0] : header;
+    if (isValidRequestId(raw))
+        return raw;
+    return randomUUID();
+}
+//# sourceMappingURL=requestId.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"requestId.js","sourceRoot":"","sources":["../../../src/lib/observability/requestId.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,+EAA+E;AAC/E,0EAA0E;AAC1E,+EAA+E;AAC/E,8DAA8D;AAC9D,2EAA2E;AAE3E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,8EAA8E;AAC9E,MAAM,aAAa,GAAG,0BAA0B,CAAC;AAEjD,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAiC;IAChE,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACvD,IAAI,gBAAgB,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IACtC,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC"}

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

@@ -0,0 +1,77 @@
+export type CallerType = "api" | "agent" | "a2a" | "unknown";
+export type TargetType = "contract" | "eoa" | "address" | "url" | "text" | "tx" | "unknown" | "none";
+export interface ActivityTarget {
+    type: TargetType;
+    /** Shortened address `0x1234…cdef` (never the full address). */
+    addressShort: string | null;
+    /** 4-byte function selector `0x########` (never full calldata). */
+    selector: string | null;
+    /** Shortened tx hash `0x1234…cdef` (never the full hash). */
+    txHashShort: string | null;
+}
+export interface ActivityItem {
+    id: string;
+    ts: string;
+    requestId: string;
+    endpoint: string;
+    /** Endpoint class (api | agent | a2a | unknown) — drives metrics totals. */
+    callerType: CallerType;
+    /** Access tier (anonymous | api-key | agent | a2a) — caller identity. */
+    accessTier: string;
+    /** keyId (hash prefix) for a valid key — never the raw key. */
+    keyId: string | null;
+    /** Sanitized, untrusted, display-only identity. */
+    agentId: string | null;
+    a2aPeerId: string | null;
+    /** Applied policy preset — agent decisions only; null otherwise. */
+    policyPreset: string | null;
+    network: string;
+    chainId: number;
+    checkType: string | null;
+    intentType: string | null;
+    decision: string | null;
+    riskLevel: string | null;
+    reasonSummary: string;
+    evidenceTypes: string[];
+    readOnly: boolean;
+    executionAvailable: boolean;
+    target: ActivityTarget;
+    preparedTransactionId?: string | null;
+    preparedTransactionHashShort?: string | null;
+    broadcastStatus?: string | null;
+    attestationStatus?: string | null;
+    executionStatus?: string | null;
+}
+/** `0x1234…cdef` for a valid 20-byte address, else null. */
+export declare function shortenAddress(value: unknown): string | null;
+/** `0x1234…cdef` for a valid 32-byte tx hash, else null. */
+export declare function shortenTxHash(value: unknown): string | null;
+/** 4-byte selector `0x########` from calldata, else null. */
+export declare function selectorOf(data: unknown): string | null;
+/** Replace any long 0x hex run with a shortened form so no full hex leaks via text. */
+export declare function redactLongHex(text: string): string;
+export interface BuildActivityInput {
+    endpoint: string;
+    callerType: CallerType;
+    requestId: string;
+    durationMs?: number;
+    body: unknown;
+    payload: unknown;
+    /** Sanitized caller identity. Optional so offline builders can omit it. */
+    access?: AccessContextLike;
+}
+/** The whitelisted identity subset of AccessContext that activity may store. */
+export interface AccessContextLike {
+    callerType: string;
+    keyId: string | null;
+    agentId: string | null;
+    a2aPeerId: string | null;
+}
+/**
+ * Build a sanitized {@link ActivityItem}. Reads only whitelisted derivatives —
+ * the raw body/payload are NEVER copied into the result.
+ */
+export declare function toActivityItem(input: BuildActivityInput): ActivityItem;
+/** Map an endpoint path to its caller category for activity/logging. */
+export declare function callerTypeForEndpoint(endpoint: string): CallerType;
+//# sourceMappingURL=sanitize.d.ts.map

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

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