safehands-pharos 1.4.0 → 2.6.0

package/dist/lib/observability/activityStore.js

@@ -0,0 +1,149 @@
+// ─── Activity Store ────────────────────────────────────────────────────
+// In-memory, fixed-capacity ring buffer of sanitized activity items, plus
+// O(1) cumulative counters for the public summary/metrics endpoints. No DB, no
+// external service, no file I/O. Bounded memory by construction. Per-process /
+// per-instance (documented): on multi-instance deployments each instance keeps
+// its own window — acceptable for a public, illustrative activity feed.
+// ────────────────────────────────────────────────────────────────────────
+const DEFAULT_CAPACITY = 500;
+const MIN_CAPACITY = 10;
+const MAX_CAPACITY = 5000;
+function emptyDecisions() {
+    return { ALLOW: 0, BLOCK: 0, REQUIRE_CONFIRMATION: 0, PREPARE_ONLY: 0, NONE: 0 };
+}
+function emptyRisks() {
+    return { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0, UNKNOWN: 0 };
+}
+function emptyCallers() {
+    return { api: 0, agent: 0, a2a: 0, unknown: 0 };
+}
+function emptyAccessTiers() {
+    return { anonymous: 0, "api-key": 0, agent: 0, a2a: 0 };
+}
+function clampCapacity(n) {
+    if (!Number.isFinite(n))
+        return DEFAULT_CAPACITY;
+    return Math.min(MAX_CAPACITY, Math.max(MIN_CAPACITY, Math.floor(n)));
+}
+export class ActivityStore {
+    capacity;
+    buf;
+    head = 0; // next write slot
+    size = 0;
+    startedAtMs = Date.now();
+    lastActivityAt = null;
+    recorded = 0;
+    rateLimited = 0;
+    rateLimitedByTier = emptyAccessTiers();
+    byCaller = emptyCallers();
+    byAccessTier = emptyAccessTiers();
+    byDecision = emptyDecisions();
+    byRisk = emptyRisks();
+    byEndpoint = {};
+    byPolicyPreset = {};
+    constructor(capacity = DEFAULT_CAPACITY) {
+        this.capacity = clampCapacity(capacity);
+        this.buf = new Array(this.capacity);
+    }
+    /** Resize/reset the ring (used at server start from env). Clears all state. */
+    configure(capacity) {
+        this.capacity = clampCapacity(capacity);
+        this.reset();
+    }
+    /** Clear the buffer + counters (tests + reconfigure). */
+    reset() {
+        this.buf = new Array(this.capacity);
+        this.head = 0;
+        this.size = 0;
+        this.startedAtMs = Date.now();
+        this.lastActivityAt = null;
+        this.recorded = 0;
+        this.rateLimited = 0;
+        this.rateLimitedByTier = emptyAccessTiers();
+        this.byCaller = emptyCallers();
+        this.byAccessTier = emptyAccessTiers();
+        this.byDecision = emptyDecisions();
+        this.byRisk = emptyRisks();
+        this.byEndpoint = {};
+        this.byPolicyPreset = {};
+    }
+    record(item) {
+        this.buf[this.head] = item;
+        this.head = (this.head + 1) % this.capacity;
+        if (this.size < this.capacity)
+            this.size++;
+        this.recorded++;
+        this.lastActivityAt = item.ts;
+        this.byCaller[item.callerType] = (this.byCaller[item.callerType] ?? 0) + 1;
+        const tier = (item.accessTier ?? "anonymous");
+        if (tier in this.byAccessTier)
+            this.byAccessTier[tier]++;
+        else
+            this.byAccessTier.anonymous++;
+        const dKey = (item.decision ?? "NONE");
+        if (dKey in this.byDecision)
+            this.byDecision[dKey]++;
+        else
+            this.byDecision.NONE++;
+        const rKey = (item.riskLevel ?? "UNKNOWN");
+        if (rKey in this.byRisk)
+            this.byRisk[rKey]++;
+        else
+            this.byRisk.UNKNOWN++;
+        this.byEndpoint[item.endpoint] = (this.byEndpoint[item.endpoint] ?? 0) + 1;
+        const preset = item.policyPreset ?? "none";
+        this.byPolicyPreset[preset] = (this.byPolicyPreset[preset] ?? 0) + 1;
+    }
+    /** Count a rate-limited (429) request that never reached a handler. */
+    recordRateLimited(tier) {
+        this.rateLimited++;
+        if (tier && tier in this.rateLimitedByTier)
+            this.rateLimitedByTier[tier]++;
+    }
+    /** Newest-first slice of the most recent items (sanitized copies). */
+    recent(limit) {
+        const n = Math.min(Math.max(0, Math.floor(limit)), this.size);
+        const out = [];
+        for (let i = 0; i < n; i++) {
+            const idx = (this.head - 1 - i + this.capacity * 2) % this.capacity;
+            const item = this.buf[idx];
+            if (item)
+                out.push(item);
+        }
+        return out;
+    }
+    summary() {
+        return {
+            window: { capacity: this.capacity, size: this.size },
+            totals: {
+                recorded: this.recorded,
+                rateLimited: this.rateLimited,
+                byCaller: { ...this.byCaller },
+                byAccessTier: { ...this.byAccessTier },
+                byDecision: { ...this.byDecision },
+                byRisk: { ...this.byRisk },
+                byEndpoint: { ...this.byEndpoint },
+                byPolicyPreset: { ...this.byPolicyPreset },
+            },
+            lastActivityAt: this.lastActivityAt,
+        };
+    }
+    metrics() {
+        return {
+            uptimeSeconds: Math.floor((Date.now() - this.startedAtMs) / 1000),
+            totalChecks: this.byCaller.api,
+            totalAgentChecks: this.byCaller.agent,
+            totalA2AChecks: this.byCaller.a2a,
+            totalBlocked: this.byDecision.BLOCK,
+            totalRequireConfirmation: this.byDecision.REQUIRE_CONFIRMATION,
+            totalPrepareOnly: this.byDecision.PREPARE_ONLY,
+            totalAllowed: this.byDecision.ALLOW,
+            totalRateLimited: this.rateLimited,
+            rateLimitedByTier: { ...this.rateLimitedByTier },
+            ring: { capacity: this.capacity, size: this.size },
+        };
+    }
+}
+/** Process-wide singleton used by the server + activity routes. */
+export const activityStore = new ActivityStore();
+//# sourceMappingURL=activityStore.js.map

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

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

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

@@ -0,0 +1,55 @@
+import { type Scope } from "./scopes.js";
+export interface ApiKeyConfig {
+    /** At least one key configured via SAFEHANDS_API_KEYS. */
+    configured: boolean;
+    /** Gate non-public endpoints (only when configured). */
+    required: boolean;
+    /** Public read API open by default (SAFEHANDS_PUBLIC_READ_ENABLED !== "false"). */
+    publicReadEnabled: boolean;
+    /** keyId (hash prefix) → full sha256 hex. Never the raw key. */
+    hashes: Map<string, string>;
+    /** keyId → granted scopes. Bare keys receive the default read bundle. */
+    scopes: Map<string, Set<Scope>>;
+}
+export type ApiKeyStatus = "anonymous" | "valid" | "invalid";
+export interface ApiKeyResolution {
+    status: ApiKeyStatus;
+    keyId: string | null;
+    /** Granted scopes for a valid key (null when anonymous/invalid). */
+    scopes: Set<Scope> | null;
+}
+type Env = Record<string, string | undefined>;
+type Headers = Record<string, string | string[] | undefined>;
+/**
+ * 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 declare const ALWAYS_OPEN_PATHS: Set<string>;
+export declare function loadApiKeyConfig(env?: Env): ApiKeyConfig;
+/** Extract a presented key from `X-Api-Key` or `Authorization: Bearer <key>`. */
+export declare function extractApiKey(headers: Headers): string | null;
+/**
+ * Resolve a request's API-key status. Never returns the raw key. `anonymous`
+ * when none presented; `valid` (+keyId) on match; `invalid` otherwise.
+ */
+export declare function resolveApiKey(headers: Headers, cfg: ApiKeyConfig): ApiKeyResolution;
+export interface AccessDecision {
+    allow: boolean;
+    code: string | 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 declare function evaluateAccess(path: string, resolution: ApiKeyResolution, cfg: ApiKeyConfig): AccessDecision;
+export {};
+//# sourceMappingURL=apiKey.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"apiKey.d.ts","sourceRoot":"","sources":["../../../src/lib/observability/apiKey.ts"],"names":[],"mappings":"AAgBA,OAAO,EAA4D,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAEnG,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,UAAU,EAAE,OAAO,CAAC;IACpB,wDAAwD;IACxD,QAAQ,EAAE,OAAO,CAAC;IAClB,mFAAmF;IACnF,iBAAiB,EAAE,OAAO,CAAC;IAC3B,gEAAgE;IAChE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,yEAAyE;IACzE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;CACjC;AAED,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,OAAO,GAAG,SAAS,CAAC;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,oEAAoE;IACpE,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;CAC3B;AAED,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAC9C,KAAK,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,aAe5B,CAAC;AAMH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,GAAiB,GAAG,YAAY,CA2BrE;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAY7D;AAWD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,YAAY,GAAG,gBAAgB,CAUnF;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,gBAAgB,EAC5B,GAAG,EAAE,YAAY,GAChB,cAAc,CAchB"}

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"}