safehands-pharos 1.5.0 → 2.6.0

package/dist/lib/networks.d.ts

@@ -0,0 +1,48 @@
+export type NetworkName = "pacific-mainnet" | "atlantic-testnet";
+export interface PharosNetwork {
+    name: NetworkName;
+    label: string;
+    chainId: number;
+    nativeToken: string;
+    /** Public, key-free default RPC endpoint. */
+    defaultRpcUrl: string;
+    explorerUrl: string;
+    socialScanUrl?: string;
+    isMainnet: boolean;
+    /** Read-only SafeHands checks are always allowed. */
+    readOnlyChecks: boolean;
+    /** Whether execution/write/payment is permitted on this network at all. */
+    executionAllowed: boolean;
+}
+/** Mainnet-first default. */
+export declare const DEFAULT_NETWORK_NAME: NetworkName;
+export declare const NETWORKS: Record<NetworkName, PharosNetwork>;
+export declare function isNetworkName(value: string | undefined): value is NetworkName;
+/** Resolve the active network name from SAFEHANDS_NETWORK (default mainnet-first). */
+export declare function getActiveNetworkName(): NetworkName;
+export declare function getActiveNetwork(): PharosNetwork;
+export declare function getNetworkByChainId(chainId: number): PharosNetwork | undefined;
+/**
+ * Resolve the RPC URL for a network. Priority:
+ *   1. Network-specific override env var
+ *   2. Optional provider env vars (ZAN > Alchemy > Nirvana) — mainnet only
+ *   3. The public, key-free default RPC
+ * Premium/keyed URLs are NEVER hardcoded — they are only ever read from env.
+ */
+export declare function resolveRpcUrl(network: PharosNetwork): string;
+export type RpcProviderName = "zan" | "alchemy" | "nirvana" | "custom" | "pharos-public";
+/**
+ * Redacted RPC provider descriptor — the provider NAME and whether it came from
+ * env, but NEVER the URL or API key. Safe to expose in /public-config and
+ * /infra/status. The provider name is inferred from which env var is set (an
+ * explicit PHAROS_RPC_PROVIDER label wins for custom URLs).
+ */
+export interface RpcProviderDescriptor {
+    name: RpcProviderName;
+    configuredViaEnv: boolean;
+    usingPublicDefault: boolean;
+}
+export declare function resolveRpcProvider(network: PharosNetwork): RpcProviderDescriptor;
+/** Build the explorer transaction-link base (e.g. https://www.pharosscan.xyz/tx/). */
+export declare function explorerTxBase(network: PharosNetwork): string;
+//# sourceMappingURL=networks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"networks.d.ts","sourceRoot":"","sources":["../../src/lib/networks.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAEjE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,qDAAqD;IACrD,cAAc,EAAE,OAAO,CAAC;IACxB,2EAA2E;IAC3E,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,6BAA6B;AAC7B,eAAO,MAAM,oBAAoB,EAAE,WAA+B,CAAC;AAEnE,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,WAAW,EAAE,aAAa,CA8BvD,CAAC;AAEF,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,KAAK,IAAI,WAAW,CAE7E;AAED,sFAAsF;AACtF,wBAAgB,oBAAoB,IAAI,WAAW,CAGlD;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAE9E;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAc5D;AAED,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,eAAe,CAAC;AAEzF;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,eAAe,CAAC;IACtB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,qBAAqB,CAgBhF;AAED,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAG7D"}

package/dist/lib/networks.js

@@ -0,0 +1,103 @@
+// ─── SafeHands Network Registry ────────────────────────────────────────
+// Mainnet-first: Pharos Pacific Mainnet is the DEFAULT active network for
+// read-only SafeHands checks. Atlantic Testnet remains available via the
+// SAFEHANDS_NETWORK env var for demo, compatibility, contract testing, and
+// x402 testing.
+//
+// Read-only by default. No private keys and no premium/keyed RPC URLs are
+// hardcoded here — optional provider URLs (ZAN/Alchemy/Nirvana) are read from
+// the environment only.
+// ────────────────────────────────────────────────────────────────────────
+/** Mainnet-first default. */
+export const DEFAULT_NETWORK_NAME = "pacific-mainnet";
+export const NETWORKS = {
+    "pacific-mainnet": {
+        name: "pacific-mainnet",
+        label: "Pharos Pacific Mainnet",
+        chainId: 1672,
+        nativeToken: "PROS",
+        defaultRpcUrl: "https://rpc.pharos.xyz",
+        explorerUrl: "https://www.pharosscan.xyz",
+        socialScanUrl: "https://pharos.socialscan.io",
+        isMainnet: true,
+        readOnlyChecks: true,
+        // Execution at the network level targets Pacific Mainnet (all-mainnet), but
+        // every write stays gated by WRITE_TOOLS_ENABLED + MANAGED_WALLET_ENABLED
+        // (both default false) — a hosted deployment is read-only by default.
+        executionAllowed: true,
+    },
+    "atlantic-testnet": {
+        name: "atlantic-testnet",
+        label: "Pharos Atlantic Testnet",
+        chainId: 688689,
+        nativeToken: "PROS",
+        defaultRpcUrl: "https://atlantic.dplabs-internal.com/",
+        explorerUrl: "https://atlantic.pharosscan.xyz/",
+        socialScanUrl: "https://pharos.socialscan.io",
+        isMainnet: false,
+        readOnlyChecks: true,
+        // No mainnet execution — SafeHands is all-mainnet. Atlantic remains for
+        // read-only checks / compatibility only.
+        executionAllowed: false,
+    },
+};
+export function isNetworkName(value) {
+    return value === "pacific-mainnet" || value === "atlantic-testnet";
+}
+/** Resolve the active network name from SAFEHANDS_NETWORK (default mainnet-first). */
+export function getActiveNetworkName() {
+    const raw = process.env.SAFEHANDS_NETWORK;
+    return isNetworkName(raw) ? raw : DEFAULT_NETWORK_NAME;
+}
+export function getActiveNetwork() {
+    return NETWORKS[getActiveNetworkName()];
+}
+export function getNetworkByChainId(chainId) {
+    return Object.values(NETWORKS).find((n) => n.chainId === chainId);
+}
+/**
+ * Resolve the RPC URL for a network. Priority:
+ *   1. Network-specific override env var
+ *   2. Optional provider env vars (ZAN > Alchemy > Nirvana) — mainnet only
+ *   3. The public, key-free default RPC
+ * Premium/keyed URLs are NEVER hardcoded — they are only ever read from env.
+ */
+export function resolveRpcUrl(network) {
+    if (network.name === "pacific-mainnet") {
+        return (process.env.PHAROS_MAINNET_RPC_URL ||
+            process.env.PHAROS_PACIFIC_RPC_URL ||
+            process.env.PHAROS_RPC_URL ||
+            process.env.ZAN_PHAROS_MAINNET_RPC_URL ||
+            process.env.PHAROS_ZAN_RPC_URL ||
+            process.env.ALCHEMY_PHAROS_MAINNET_RPC_URL ||
+            process.env.NIRVANA_PHAROS_MAINNET_RPC_URL ||
+            network.defaultRpcUrl);
+    }
+    return process.env.PHAROS_ATLANTIC_RPC_URL || network.defaultRpcUrl;
+}
+export function resolveRpcProvider(network) {
+    const explicit = process.env.PHAROS_RPC_PROVIDER?.trim().toLowerCase();
+    const labelled = (fallback) => explicit === "zan" || explicit === "alchemy" || explicit === "nirvana" || explicit === "custom" || explicit === "pharos-public"
+        ? explicit
+        : fallback;
+    if (network.name === "pacific-mainnet") {
+        if (process.env.PHAROS_MAINNET_RPC_URL || process.env.PHAROS_PACIFIC_RPC_URL || process.env.PHAROS_RPC_URL)
+            return { name: labelled("custom"), configuredViaEnv: true, usingPublicDefault: false };
+        if (process.env.ZAN_PHAROS_MAINNET_RPC_URL || process.env.PHAROS_ZAN_RPC_URL)
+            return { name: "zan", configuredViaEnv: true, usingPublicDefault: false };
+        if (process.env.ALCHEMY_PHAROS_MAINNET_RPC_URL)
+            return { name: "alchemy", configuredViaEnv: true, usingPublicDefault: false };
+        if (process.env.NIRVANA_PHAROS_MAINNET_RPC_URL)
+            return { name: "nirvana", configuredViaEnv: true, usingPublicDefault: false };
+        return { name: "pharos-public", configuredViaEnv: false, usingPublicDefault: true };
+    }
+    if (process.env.PHAROS_ATLANTIC_RPC_URL)
+        return { name: labelled("custom"), configuredViaEnv: true, usingPublicDefault: false };
+    return { name: "pharos-public", configuredViaEnv: false, usingPublicDefault: true };
+}
+/** Build the explorer transaction-link base (e.g. https://www.pharosscan.xyz/tx/). */
+export function explorerTxBase(network) {
+    const base = network.explorerUrl.replace(/\/+$/, "");
+    return `${base}/tx/`;
+}
+//# sourceMappingURL=networks.js.map

package/dist/lib/networks.js.map

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

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

@@ -0,0 +1,29 @@
+import type { ApiKeyResolution } from "./apiKey.js";
+import type { Scope } from "./scopes.js";
+export type CallerType = "anonymous" | "api-key" | "agent" | "a2a";
+export interface AccessContext {
+    callerType: CallerType;
+    /** keyId (hash prefix) for a valid key — never the raw key. */
+    keyId: string | null;
+    /** Granted scopes for a valid key (empty for anonymous). */
+    scopes: Scope[];
+    /** Sanitized, untrusted, display-only. */
+    agentId: string | null;
+    a2aPeerId: string | null;
+    requestId: string | null;
+}
+/** Validate + normalize an untrusted id; returns null if missing/malformed. */
+export declare function sanitizeId(value: unknown): string | null;
+/** Derive the access tier from the endpoint + key status. */
+export declare function callerTypeFor(path: string, resolution: ApiKeyResolution): CallerType;
+/**
+ * Build the sanitized access context. Reads only whitelisted identity fields —
+ * raw key/headers/IP/payload are never copied in.
+ */
+export declare function buildAccessContext(args: {
+    path: string;
+    resolution: ApiKeyResolution;
+    body: unknown;
+    requestId?: string | null;
+}): AccessContext;
+//# sourceMappingURL=accessContext.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"accessContext.d.ts","sourceRoot":"","sources":["../../../src/lib/observability/accessContext.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,CAAC;AAEnE,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,UAAU,CAAC;IACvB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,4DAA4D;IAC5D,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAKD,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAIxD;AAOD,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,GAAG,UAAU,CAKpF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,gBAAgB,CAAC;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,GAAG,aAAa,CAUhB"}

package/dist/lib/observability/accessContext.js

@@ -0,0 +1,50 @@
+// ─── Access Context ──────────────────────────────────────────────
+// Builds a SANITIZED, secret-free caller identity for a request. It carries the
+// access tier (callerType), the keyId (hash prefix) + granted scopes for a valid
+// key, and length/charset-capped agentId/a2aPeerId pulled from the request body.
+//
+// NEVER captured: raw API keys, Authorization/other headers, client IP, or raw
+// payloads. agentId/a2aPeerId are UNTRUSTED display-only identity (validated +
+// dropped if malformed) — they are not used for any security decision. Pure +
+// offline; no signing/wallet/write primitives.
+// ────────────────────────────────────────────────────────────────────────
+/** Safe identity charset: short, printable, no whitespace/control chars. */
+const ID_RE = /^[A-Za-z0-9._:-]{1,64}$/;
+/** Validate + normalize an untrusted id; returns null if missing/malformed. */
+export function sanitizeId(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return ID_RE.test(trimmed) ? trimmed : null;
+}
+function bodyString(body, key) {
+    if (!body || typeof body !== "object")
+        return undefined;
+    return body[key];
+}
+/** Derive the access tier from the endpoint + key status. */
+export function callerTypeFor(path, resolution) {
+    if (path === "/agent/a2a/check")
+        return "a2a";
+    if (path === "/agent/check")
+        return "agent";
+    if (resolution.status === "valid")
+        return "api-key";
+    return "anonymous";
+}
+/**
+ * Build the sanitized access context. Reads only whitelisted identity fields —
+ * raw key/headers/IP/payload are never copied in.
+ */
+export function buildAccessContext(args) {
+    const { path, resolution, body } = args;
+    return {
+        callerType: callerTypeFor(path, resolution),
+        keyId: resolution.status === "valid" ? resolution.keyId : null,
+        scopes: resolution.scopes ? [...resolution.scopes] : [],
+        agentId: sanitizeId(bodyString(body, "agentId")),
+        a2aPeerId: sanitizeId(bodyString(body, "callerAgent") ?? bodyString(body, "a2aPeerId")),
+        requestId: typeof args.requestId === "string" ? args.requestId : null,
+    };
+}
+//# sourceMappingURL=accessContext.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"accessContext.js","sourceRoot":"","sources":["../../../src/lib/observability/accessContext.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,gFAAgF;AAChF,iFAAiF;AACjF,iFAAiF;AACjF,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,8EAA8E;AAC9E,+CAA+C;AAC/C,2EAA2E;AAmB3E,4EAA4E;AAC5E,MAAM,KAAK,GAAG,yBAAyB,CAAC;AAExC,+EAA+E;AAC/E,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,OAAO,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9C,CAAC;AAED,SAAS,UAAU,CAAC,IAAa,EAAE,GAAW;IAC5C,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACxD,OAAQ,IAAgC,CAAC,GAAG,CAAC,CAAC;AAChD,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,UAA4B;IACtE,IAAI,IAAI,KAAK,kBAAkB;QAAE,OAAO,KAAK,CAAC;IAC9C,IAAI,IAAI,KAAK,cAAc;QAAE,OAAO,OAAO,CAAC;IAC5C,IAAI,UAAU,CAAC,MAAM,KAAK,OAAO;QAAE,OAAO,SAAS,CAAC;IACpD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAKlC;IACC,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;IACxC,OAAO;QACL,UAAU,EAAE,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC;QAC3C,KAAK,EAAE,UAAU,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI;QAC9D,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE;QACvD,OAAO,EAAE,UAAU,CAAC,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAChD,SAAS,EAAE,UAAU,CAAC,UAAU,CAAC,IAAI,EAAE,aAAa,CAAC,IAAI,UAAU,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QACvF,SAAS,EAAE,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;KACtE,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,70 @@
+import type { ActivityItem, CallerType } from "./sanitize.js";
+type DecisionKey = "ALLOW" | "BLOCK" | "REQUIRE_CONFIRMATION" | "PREPARE_ONLY" | "NONE";
+type RiskKey = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "UNKNOWN";
+type AccessTierKey = "anonymous" | "api-key" | "agent" | "a2a";
+export interface ActivitySummary {
+    window: {
+        capacity: number;
+        size: number;
+    };
+    totals: {
+        recorded: number;
+        rateLimited: number;
+        byCaller: Record<CallerType, number>;
+        byAccessTier: Record<AccessTierKey, number>;
+        byDecision: Record<DecisionKey, number>;
+        byRisk: Record<RiskKey, number>;
+        byEndpoint: Record<string, number>;
+        byPolicyPreset: Record<string, number>;
+    };
+    lastActivityAt: string | null;
+}
+export interface ActivityMetrics {
+    uptimeSeconds: number;
+    totalChecks: number;
+    totalAgentChecks: number;
+    totalA2AChecks: number;
+    totalBlocked: number;
+    totalRequireConfirmation: number;
+    totalPrepareOnly: number;
+    totalAllowed: number;
+    totalRateLimited: number;
+    rateLimitedByTier: Record<AccessTierKey, number>;
+    ring: {
+        capacity: number;
+        size: number;
+    };
+}
+export declare class ActivityStore {
+    private capacity;
+    private buf;
+    private head;
+    private size;
+    private startedAtMs;
+    private lastActivityAt;
+    private recorded;
+    private rateLimited;
+    private rateLimitedByTier;
+    private byCaller;
+    private byAccessTier;
+    private byDecision;
+    private byRisk;
+    private byEndpoint;
+    private byPolicyPreset;
+    constructor(capacity?: number);
+    /** Resize/reset the ring (used at server start from env). Clears all state. */
+    configure(capacity: number): void;
+    /** Clear the buffer + counters (tests + reconfigure). */
+    reset(): void;
+    record(item: ActivityItem): void;
+    /** Count a rate-limited (429) request that never reached a handler. */
+    recordRateLimited(tier?: string): void;
+    /** Newest-first slice of the most recent items (sanitized copies). */
+    recent(limit: number): ActivityItem[];
+    summary(): ActivitySummary;
+    metrics(): ActivityMetrics;
+}
+/** Process-wide singleton used by the server + activity routes. */
+export declare const activityStore: ActivityStore;
+export {};
+//# sourceMappingURL=activityStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"activityStore.d.ts","sourceRoot":"","sources":["../../../src/lib/observability/activityStore.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAM9D,KAAK,WAAW,GAAG,OAAO,GAAG,OAAO,GAAG,sBAAsB,GAAG,cAAc,GAAG,MAAM,CAAC;AACxF,KAAK,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;AAYlE,KAAK,aAAa,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,CAAC;AAK/D,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,MAAM,EAAE;QACN,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QACrC,YAAY,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;QAC5C,UAAU,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QACxC,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAChC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACnC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACxC,CAAC;IACF,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,wBAAwB,EAAE,MAAM,CAAC;IACjC,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IACjD,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1C;AAOD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,GAAG,CAA+B;IAC1C,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,cAAc,CAAuB;IAE7C,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,iBAAiB,CAAsB;IAC/C,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,YAAY,CAAsB;IAC1C,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,UAAU,CAA8B;IAChD,OAAO,CAAC,cAAc,CAA8B;gBAExC,QAAQ,GAAE,MAAyB;IAK/C,+EAA+E;IAC/E,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAKjC,yDAAyD;IACzD,KAAK,IAAI,IAAI;IAiBb,MAAM,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAsBhC,uEAAuE;IACvE,iBAAiB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAKtC,sEAAsE;IACtE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE;IAWrC,OAAO,IAAI,eAAe;IAiB1B,OAAO,IAAI,eAAe;CAe3B;AAED,mEAAmE;AACnE,eAAO,MAAM,aAAa,eAAsB,CAAC"}

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