safehands-pharos 1.4.0 → 2.6.0

package/dist/lib/managedExecution.d.ts

@@ -0,0 +1,19 @@
+import { type SignerResult, type SignerPurpose } from "./signer/index.js";
+import { type ToolFailure } from "./toolResponse.js";
+export interface ManagedExecutionReady {
+    signer: SignerResult;
+}
+export declare function isManagedExecutionFailure(r: ManagedExecutionReady | ToolFailure): r is ToolFailure;
+/**
+ * Resolves a signer that is cleared for managed/mainnet execution, or returns
+ * a structured ToolFailure describing exactly which gate failed.
+ *
+ * Failure codes:
+ *  - WRITE_TOOLS_DISABLED      writes are off by default
+ *  - NO_SIGNER_AVAILABLE / INVALID_PRIVATE_KEY / WALLET_ENCRYPTION_KEY_REQUIRED
+ *  - REQUIRE_AUTHORIZATION     managed wallet not authorized in SafeHandsRegistry
+ */
+export declare function requireManagedExecutionReady(toolName: string, agentId?: string, options?: {
+    purpose?: SignerPurpose;
+}): Promise<ManagedExecutionReady | ToolFailure>;
+//# sourceMappingURL=managedExecution.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"managedExecution.d.ts","sourceRoot":"","sources":["../../src/lib/managedExecution.ts"],"names":[],"mappings":"AAgBA,OAAO,EAA8B,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEtG,OAAO,EAAQ,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAI3D,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,wBAAgB,yBAAyB,CACvC,CAAC,EAAE,qBAAqB,GAAG,WAAW,GACrC,CAAC,IAAI,WAAW,CAElB;AAED;;;;;;;;GAQG;AACH,wBAAsB,4BAA4B,CAChD,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,aAAa,CAAA;CAAO,GACxC,OAAO,CAAC,qBAAqB,GAAG,WAAW,CAAC,CAiD9C"}

package/dist/lib/managedExecution.js

@@ -0,0 +1,64 @@
+// ─── Managed Execution Gate ────────────────────────────────────────────
+// Centralized safety gate shared by every write/payment tool so that direct
+// calls (send_payment, execute_swap, approve_token, x402_pay_and_fetch,
+// publish_risk_score) are exactly as safe as going through
+// safehands_safe_execute.
+//
+// Safety hierarchy enforced here:
+//   1. WRITE_TOOLS_ENABLED must be true.
+//   2. A signer must be available.
+//   3. For managed-mainnet signers, the wallet must be authorized in
+//      SafeHandsRegistry (when REQUIRE_AUTHORIZED_AGENT_FOR_WRITE is on).
+//
+// Funding and per-agent policy are evaluated by each tool after this gate
+// (funding via balance checks, policy via evaluateActionPolicy with agentId).
+// ────────────────────────────────────────────────────────────────────────
+import { getSigner, isSignerFailure } from "./signer/index.js";
+import { checkManagedWalletAuthorization } from "./safeHandsRegistry.js";
+import { fail } from "./toolResponse.js";
+import { REQUIRE_AUTHORIZED_AGENT_FOR_WRITE } from "./constants.js";
+import { getActiveNetwork } from "./networks.js";
+export function isManagedExecutionFailure(r) {
+    return "success" in r && r.success === false;
+}
+/**
+ * Resolves a signer that is cleared for managed/mainnet execution, or returns
+ * a structured ToolFailure describing exactly which gate failed.
+ *
+ * Failure codes:
+ *  - WRITE_TOOLS_DISABLED      writes are off by default
+ *  - NO_SIGNER_AVAILABLE / INVALID_PRIVATE_KEY / WALLET_ENCRYPTION_KEY_REQUIRED
+ *  - REQUIRE_AUTHORIZATION     managed wallet not authorized in SafeHandsRegistry
+ */
+export async function requireManagedExecutionReady(toolName, agentId, options = {}) {
+    // 1. Write tools must be explicitly enabled.
+    if (process.env.WRITE_TOOLS_ENABLED !== "true") {
+        return fail("WRITE_TOOLS_DISABLED", `${toolName} is disabled by default. Set WRITE_TOOLS_ENABLED=true only for trusted mainnet execution.`, false, toolName);
+    }
+    // 1b. The active network must permit execution (executionAllowed). NOTE: Pharos
+    //     Pacific Mainnet has executionAllowed=true — this gate does NOT block mainnet.
+    //     The real safety margin on mainnet is WRITE_TOOLS_ENABLED (checked above) + an
+    //     available signer + registry authorization (below), NOT this network flag.
+    const activeNetwork = getActiveNetwork();
+    if (!activeNetwork.executionAllowed) {
+        return fail("EXECUTION_DISABLED_ON_NETWORK", `${activeNetwork.label} is read-only in SafeHands: execution/write/payment is disabled on this network. ` +
+            `Set SAFEHANDS_NETWORK=pacific-mainnet for advanced self-hosted mainnet execution.`, false, toolName);
+    }
+    // 2. A signer must be available.
+    const signer = await getSigner(agentId, options);
+    if (isSignerFailure(signer)) {
+        return fail(signer.error.code, signer.error.message, false, toolName);
+    }
+    // 3. Managed-mainnet wallets must be authorized in SafeHandsRegistry.
+    if (signer.mode === "managed-mainnet" && REQUIRE_AUTHORIZED_AGENT_FOR_WRITE) {
+        const authCheck = await checkManagedWalletAuthorization(signer.address);
+        if (!authCheck.authorized) {
+            return fail("REQUIRE_AUTHORIZATION", authCheck.errorMessage ||
+                `Managed wallet ${signer.address} is not authorized in SafeHandsRegistry. ` +
+                    `The contract owner must call setAuthorizedAgent(${signer.address}, true), ` +
+                    `or enable AUTO_AUTHORIZE_AGENT_WALLET=true with RISK_REGISTRY_OWNER_PRIVATE_KEY.`, false, toolName);
+        }
+    }
+    return { signer };
+}
+//# sourceMappingURL=managedExecution.js.map

package/dist/lib/managedExecution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"managedExecution.js","sourceRoot":"","sources":["../../src/lib/managedExecution.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,0BAA0B;AAC1B,EAAE;AACF,kCAAkC;AAClC,yCAAyC;AACzC,mCAAmC;AACnC,qEAAqE;AACrE,0EAA0E;AAC1E,EAAE;AACF,0EAA0E;AAC1E,8EAA8E;AAC9E,2EAA2E;AAE3E,OAAO,EAAE,SAAS,EAAE,eAAe,EAAyC,MAAM,mBAAmB,CAAC;AACtG,OAAO,EAAE,+BAA+B,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAE,IAAI,EAAoB,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,kCAAkC,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAMjD,MAAM,UAAU,yBAAyB,CACvC,CAAsC;IAEtC,OAAO,SAAS,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,KAAK,KAAK,CAAC;AAC/C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,QAAgB,EAChB,OAAgB,EAChB,UAAuC,EAAE;IAEzC,6CAA6C;IAC7C,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,KAAK,MAAM,EAAE,CAAC;QAC/C,OAAO,IAAI,CACT,sBAAsB,EACtB,GAAG,QAAQ,2FAA2F,EACtG,KAAK,EACL,QAAQ,CACT,CAAC;IACJ,CAAC;IAED,gFAAgF;IAChF,oFAAoF;IACpF,oFAAoF;IACpF,gFAAgF;IAChF,MAAM,aAAa,GAAG,gBAAgB,EAAE,CAAC;IACzC,IAAI,CAAC,aAAa,CAAC,gBAAgB,EAAE,CAAC;QACpC,OAAO,IAAI,CACT,+BAA+B,EAC/B,GAAG,aAAa,CAAC,KAAK,mFAAmF;YACvG,mFAAmF,EACrF,KAAK,EACL,QAAQ,CACT,CAAC;IACJ,CAAC;IAED,iCAAiC;IACjC,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACjD,IAAI,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IACxE,CAAC;IAED,sEAAsE;IACtE,IAAI,MAAM,CAAC,IAAI,KAAK,iBAAiB,IAAI,kCAAkC,EAAE,CAAC;QAC5E,MAAM,SAAS,GAAG,MAAM,+BAA+B,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACxE,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC;YAC1B,OAAO,IAAI,CACT,uBAAuB,EACvB,SAAS,CAAC,YAAY;gBACpB,kBAAkB,MAAM,CAAC,OAAO,2CAA2C;oBACzE,mDAAmD,MAAM,CAAC,OAAO,WAAW;oBAC5E,kFAAkF,EACtF,KAAK,EACL,QAAQ,CACT,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,CAAC;AACpB,CAAC"}

package/dist/lib/merkleBatcher.d.ts

@@ -0,0 +1,23 @@
+import { MerkleTree } from "merkletreejs";
+export interface RiskRecordInput {
+    target: string;
+    actionHash: string;
+    score: number;
+    level: number;
+    recommendation: number;
+    policyVersionHash: string;
+    evidenceHash: string;
+    expiresAt: bigint;
+}
+export declare function queueRiskRecord(record: RiskRecordInput): void;
+export declare function getPendingRecords(): RiskRecordInput[];
+export declare function clearPendingRecords(): void;
+/**
+ * Compute the Merkle leaf for a single risk record. This is the canonical leaf
+ * encoding — both the writer (buildMerkleTree) and any reader (inclusion proof
+ * verification) MUST derive leaves through here so they can never drift from the
+ * on-chain SafeHandsRegistry.verifyRiskRecord double-keccak scheme.
+ */
+export declare function computeRiskLeaf(record: RiskRecordInput): `0x${string}`;
+export declare function buildMerkleTree(records: RiskRecordInput[]): MerkleTree;
+//# sourceMappingURL=merkleBatcher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"merkleBatcher.d.ts","sourceRoot":"","sources":["../../src/lib/merkleBatcher.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,QAoBtD;AAED,wBAAgB,iBAAiB,IAAI,eAAe,EAAE,CASrD;AAED,wBAAgB,mBAAmB,SAIlC;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,KAAK,MAAM,EAAE,CAatE;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,UAAU,CAGtE"}

package/dist/lib/merkleBatcher.js

@@ -0,0 +1,62 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import path from "path";
+import { keccak256, encodeAbiParameters, parseAbiParameters } from "viem";
+import { MerkleTree } from "merkletreejs";
+const BATCH_FILE = process.env.SAFEHANDS_RISK_QUEUE_PATH || path.join(process.env.SAFEHANDS_STATE_DIR || process.env.STATE_DIR || ".safehands", "pending_risks.json");
+export function queueRiskRecord(record) {
+    let pending = [];
+    if (existsSync(BATCH_FILE)) {
+        try {
+            pending = JSON.parse(readFileSync(BATCH_FILE, "utf-8"), (k, v) => (typeof v === "string" && /^\d+n$/.test(v) ? BigInt(v.slice(0, -1)) : v));
+        }
+        catch (e) {
+            console.warn("Failed to parse pending_risks.json, starting fresh.");
+        }
+    }
+    pending.push(record);
+    const dir = path.dirname(BATCH_FILE);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(BATCH_FILE, JSON.stringify(pending, (k, v) => (typeof v === "bigint" ? v.toString() + "n" : v), 2));
+}
+export function getPendingRecords() {
+    if (!existsSync(BATCH_FILE))
+        return [];
+    try {
+        return JSON.parse(readFileSync(BATCH_FILE, "utf-8"), (k, v) => (typeof v === "string" && /^\d+n$/.test(v) ? BigInt(v.slice(0, -1)) : v));
+    }
+    catch (e) {
+        return [];
+    }
+}
+export function clearPendingRecords() {
+    if (existsSync(BATCH_FILE)) {
+        writeFileSync(BATCH_FILE, "[]");
+    }
+}
+const LEAF_ABI = parseAbiParameters("address, bytes32, uint8, uint8, uint8, bytes32, bytes32, uint64");
+/**
+ * Compute the Merkle leaf for a single risk record. This is the canonical leaf
+ * encoding — both the writer (buildMerkleTree) and any reader (inclusion proof
+ * verification) MUST derive leaves through here so they can never drift from the
+ * on-chain SafeHandsRegistry.verifyRiskRecord double-keccak scheme.
+ */
+export function computeRiskLeaf(record) {
+    const leafData = encodeAbiParameters(LEAF_ABI, [
+        record.target,
+        record.actionHash,
+        record.score,
+        record.level,
+        record.recommendation,
+        record.policyVersionHash,
+        record.evidenceHash,
+        record.expiresAt
+    ]);
+    // Double keccak256 to match the Smart Contract.
+    return keccak256(keccak256(leafData));
+}
+export function buildMerkleTree(records) {
+    const leaves = records.map(computeRiskLeaf);
+    return new MerkleTree(leaves, keccak256, { sortPairs: true });
+}
+//# sourceMappingURL=merkleBatcher.js.map

package/dist/lib/merkleBatcher.js.map

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

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