safehands-pharos 1.4.0 → 2.6.0

package/dist/lib/validation.js

@@ -0,0 +1,62 @@
+// ─── Shared Validation Helpers ─────────────────────────────────────────
+// Reusable validators for amount, address, and field presence.
+// Used by preflight, handlers, and smoke tests.
+// ────────────────────────────────────────────────────────────────────────
+import { isAddress } from "viem";
+export function isValidPositiveAmount(value) {
+    if (value === null || value === undefined)
+        return false;
+    const str = String(value).trim();
+    if (str === "")
+        return false;
+    const n = Number(str);
+    return Number.isFinite(n) && n > 0;
+}
+export function validatePositiveAmount(value, fieldName) {
+    if (value === null || value === undefined) {
+        return `${fieldName} is required and must be a positive number.`;
+    }
+    const str = String(value).trim();
+    if (str === "")
+        return `${fieldName} must not be empty.`;
+    const n = Number(str);
+    if (!Number.isFinite(n))
+        return `${fieldName} must be a valid finite number (got "${str}").`;
+    if (n <= 0)
+        return `${fieldName} must be positive (got ${n}).`;
+    return null;
+}
+export function validateAddress(value, fieldName) {
+    if (value === null || value === undefined || value === "") {
+        return `${fieldName} is required.`;
+    }
+    const str = String(value).trim();
+    if (!isAddress(str))
+        return `${fieldName} is not a valid EVM address (got "${str}").`;
+    return null;
+}
+export function validateNonZeroAddress(value, fieldName) {
+    const addrError = validateAddress(value, fieldName);
+    if (addrError)
+        return addrError;
+    if (String(value).trim().toLowerCase() === "0x0000000000000000000000000000000000000000") {
+        return `${fieldName} must not be the zero address.`;
+    }
+    return null;
+}
+const KNOWN_TOKEN_SYMBOLS = new Set(["PROS", "USDC", "USDT", "WBTC", "WETH", "WPROS", "CIRCLE_USDC"]);
+export function validateTokenIdentifier(value, fieldName) {
+    if (value === null || value === undefined || value === "") {
+        return `${fieldName} is required.`;
+    }
+    const str = String(value).trim();
+    if (KNOWN_TOKEN_SYMBOLS.has(str.toUpperCase()))
+        return null;
+    if (isAddress(str))
+        return null;
+    return `${fieldName} must be a known token symbol (PROS, USDC, USDT, etc.) or a valid EVM address (got "${str}").`;
+}
+export function collectErrors(errors) {
+    return errors.filter((e) => e !== null);
+}
+//# sourceMappingURL=validation.js.map

package/dist/lib/validation.js.map

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

package/dist/lib/wallet/index.d.ts

@@ -1,38 +1,34 @@
-export interface StoredWallet {
-    agentId: string;
-    address: string;
-    encryptedKey: string;
-    environment: "atlantic-testnet";
-    chainId: 688689;
-    isMainnet: false;
-    createdAt: string;
-}
-export interface WalletStoreInterface {
-    get(agentId: string): Promise<StoredWallet | null>;
-    set(agentId: string, wallet: StoredWallet): Promise<void>;
-    has(agentId: string): Promise<boolean>;
-}
-/**
- * Encrypts a private key with AES-256-GCM.
- * Output format: <iv(12B)><tag(16B)><ciphertext> as hex string (no 0x prefix).
- */
-export declare function encryptKey(privateKey: string, encryptionKey: string): string;
-/**
- * Decrypts a private key. Handles both:
- * - New AES-256-GCM format (pure hex, no 0x prefix)
- * - Legacy XOR format (starts with "0x") — transparently supported for migration
- */
-export declare function decryptKey(encrypted: string, encryptionKey: string): string;
-/** @deprecated Use encryptKey / decryptKey. Kept for callers that haven't migrated yet. */
-export declare function obfuscateKey(privateKey: string, encryptionKey: string): string;
-/** @deprecated Use decryptKey. */
-export declare function deobfuscateKey(obfuscated: string, encryptionKey: string): string;
-/**
- * Returns the effective encryption key.
- * - Persistent store: WALLET_ENCRYPTION_KEY must be set (wallets won't survive restarts otherwise).
- * - In-memory store: falls back to a random per-process key.
- */
-export declare function getEffectiveEncryptionKey(): string;
-export declare function usesPersistentWalletStore(): boolean;
-export declare const walletStore: WalletStoreInterface;
+export interface StoredWallet {
+    agentId: string;
+    address: string;
+    encryptedKey: string;
+    environment: "pacific-mainnet" | "pacific-mainnet";
+    chainId: 1672 | 688689;
+    isMainnet: boolean;
+    createdAt: string;
+}
+export interface WalletStoreInterface {
+    get(agentId: string): Promise<StoredWallet | null>;
+    set(agentId: string, wallet: StoredWallet): Promise<void>;
+    has(agentId: string): Promise<boolean>;
+}
+/**
+ * Encrypts a private key with AES-256-GCM under a scrypt-derived key.
+ * Output: "sh2:" + hex(salt(16) || iv(12) || tag(16) || ciphertext).
+ */
+export declare function encryptKey(privateKey: string, encryptionKey: string): string;
+/**
+ * Decrypts a private key. Supports the current "sh2:" scrypt format and the
+ * legacy pure-hex SHA-256 AES-256-GCM format (read-only, for migration). The
+ * removed XOR path ("0x"-prefixed) is rejected — those wallets must be recreated.
+ */
+export declare function decryptKey(encrypted: string, encryptionKey: string): string;
+/**
+ * Returns the effective encryption key.
+ * - Persistent store: WALLET_ENCRYPTION_KEY must be set (wallets won't survive restarts otherwise).
+ * - In-memory store: falls back to a random per-process key.
+ */
+export declare function getEffectiveEncryptionKey(): string;
+export declare function usesPersistentWalletStore(): boolean;
+export declare const walletStore: WalletStoreInterface;
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/wallet/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/wallet/index.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,kBAAkB,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,KAAK,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IACnD,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxC;AA4DD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAQ5E;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAc3E;AAcD,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED,kCAAkC;AAClC,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAEhF;AAOD;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAYD,wBAAgB,yBAAyB,IAAI,OAAO,CAEnD;AAED,eAAO,MAAM,WAAW,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/wallet/index.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,iBAAiB,GAAG,iBAAiB,CAAC;IACnD,OAAO,EAAE,IAAI,GAAG,MAAM,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IACnD,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxC;AA6ED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAS5E;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CA+B3E;AAOD;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAYD,wBAAgB,yBAAyB,IAAI,OAAO,CAEnD;AAED,eAAO,MAAM,WAAW,sBAAsB,CAAC"}

package/dist/lib/wallet/index.js

@@ -1,129 +1,142 @@
-// ─── WalletStore ────────────────────────────────────────────────────────
-// Abstraction for storing managed testnet agent wallets.
-// Private keys are AES-256-GCM encrypted before storage.
-// Legacy XOR-obfuscated keys (starting with "0x") are transparently migrated
-// on first read. NOT mainnet-grade KMS — testnet only.
-// ────────────────────────────────────────────────────────────────────────
-import { readFileSync, writeFileSync, renameSync, existsSync } from "fs";
-import { randomBytes, createCipheriv, createDecipheriv, createHash } from "node:crypto";
-// ─── In-Memory Store (tests + default) ─────────────────────────────────
-class InMemoryWalletStore {
-    store = new Map();
-    async get(agentId) {
-        return this.store.get(agentId) ?? null;
-    }
-    async set(agentId, wallet) {
-        this.store.set(agentId, wallet);
-    }
-    async has(agentId) {
-        return this.store.has(agentId);
-    }
-}
-// ─── File Store (local dev) ─────────────────────────────────────────────
-class FileWalletStore {
-    path;
-    data = {};
-    constructor(path) {
-        this.path = path;
-        if (existsSync(path)) {
-            try {
-                this.data = JSON.parse(readFileSync(path, "utf-8"));
-            }
-            catch {
-                this.data = {};
-            }
-        }
-    }
-    async get(agentId) {
-        return this.data[agentId] ?? null;
-    }
-    async set(agentId, wallet) {
-        this.data[agentId] = wallet;
-        // Atomic write: write to .tmp then rename to avoid corruption on crash
-        const tmpPath = `${this.path}.tmp`;
-        writeFileSync(tmpPath, JSON.stringify(this.data, null, 2), "utf-8");
-        renameSync(tmpPath, this.path);
-    }
-    async has(agentId) {
-        return agentId in this.data;
-    }
-}
-// ─── AES-256-GCM Encryption ────────────────────────────────────────────
-function deriveKey(encryptionKey) {
-    return createHash("sha256").update(encryptionKey).digest();
-}
-/**
- * Encrypts a private key with AES-256-GCM.
- * Output format: <iv(12B)><tag(16B)><ciphertext> as hex string (no 0x prefix).
- */
-export function encryptKey(privateKey, encryptionKey) {
-    const key = deriveKey(encryptionKey);
-    const iv = randomBytes(12);
-    const cipher = createCipheriv("aes-256-gcm", key, iv);
-    const plain = Buffer.from(privateKey.replace(/^0x/, ""), "hex");
-    const encrypted = Buffer.concat([cipher.update(plain), cipher.final()]);
-    const tag = cipher.getAuthTag();
-    return Buffer.concat([iv, tag, encrypted]).toString("hex");
-}
-/**
- * Decrypts a private key. Handles both:
- * - New AES-256-GCM format (pure hex, no 0x prefix)
- * - Legacy XOR format (starts with "0x") — transparently supported for migration
- */
-export function decryptKey(encrypted, encryptionKey) {
-    if (encrypted.startsWith("0x")) {
-        // Legacy XOR path — symmetric, same operation
-        return _xorObfuscate(encrypted, encryptionKey);
-    }
-    const key = deriveKey(encryptionKey);
-    const data = Buffer.from(encrypted, "hex");
-    const iv = data.subarray(0, 12);
-    const tag = data.subarray(12, 28);
-    const ciphertext = data.subarray(28);
-    const decipher = createDecipheriv("aes-256-gcm", key, iv);
-    decipher.setAuthTag(tag);
-    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
-    return "0x" + decrypted.toString("hex");
-}
-// ─── Legacy XOR helpers (kept for migration read path only) ────────────
-function _xorObfuscate(privateKey, encryptionKey) {
-    const keyBytes = Buffer.from(encryptionKey.padEnd(32, "0").slice(0, 32));
-    const pkBytes = Buffer.from(privateKey.replace("0x", ""), "hex");
-    const result = Buffer.alloc(pkBytes.length);
-    for (let i = 0; i < pkBytes.length; i++) {
-        result[i] = pkBytes[i] ^ keyBytes[i % keyBytes.length];
-    }
-    return "0x" + result.toString("hex");
-}
-/** @deprecated Use encryptKey / decryptKey. Kept for callers that haven't migrated yet. */
-export function obfuscateKey(privateKey, encryptionKey) {
-    return _xorObfuscate(privateKey, encryptionKey);
-}
-/** @deprecated Use decryptKey. */
-export function deobfuscateKey(obfuscated, encryptionKey) {
-    return _xorObfuscate(obfuscated, encryptionKey);
-}
-// ─── Encryption key resolution ─────────────────────────────────────────
-// Random per-process fallback key — never hardcoded, never reused across restarts
-const IN_MEMORY_FALLBACK_KEY = randomBytes(32).toString("hex");
-/**
- * Returns the effective encryption key.
- * - Persistent store: WALLET_ENCRYPTION_KEY must be set (wallets won't survive restarts otherwise).
- * - In-memory store: falls back to a random per-process key.
- */
-export function getEffectiveEncryptionKey() {
-    return process.env.WALLET_ENCRYPTION_KEY || IN_MEMORY_FALLBACK_KEY;
-}
-// ─── Factory ────────────────────────────────────────────────────────────
-function createWalletStore() {
-    const storePath = process.env.WALLET_STORE_PATH;
-    if (storePath) {
-        return new FileWalletStore(storePath);
-    }
-    return new InMemoryWalletStore();
-}
-export function usesPersistentWalletStore() {
-    return Boolean(process.env.WALLET_STORE_PATH);
-}
-export const walletStore = createWalletStore();
+// ─── WalletStore ────────────────────────────────────────────────────────
+// Abstraction for storing managed agent wallets (Pharos Pacific Mainnet).
+// Private keys are AES-256-GCM encrypted under a memory-hard scrypt KDF before
+// storage (versioned "sh2:" format). Pre-scrypt AES records (SHA-256-derived key)
+// are still read for migration. The old XOR-obfuscation path is REMOVED — it was
+// not encryption. Local AES-256-GCM is NOT KMS/HSM-grade — use a DEDICATED,
+// low-value operator wallet for managed execution, never a primary wallet.
+// ────────────────────────────────────────────────────────────────────────
+import { readFileSync, writeFileSync, renameSync, existsSync } from "fs";
+import { randomBytes, createCipheriv, createDecipheriv, createHash, scryptSync } from "node:crypto";
+// ─── In-Memory Store (tests + default) ─────────────────────────────────
+class InMemoryWalletStore {
+    store = new Map();
+    async get(agentId) {
+        return this.store.get(agentId) ?? null;
+    }
+    async set(agentId, wallet) {
+        this.store.set(agentId, wallet);
+    }
+    async has(agentId) {
+        return this.store.has(agentId);
+    }
+}
+// ─── File Store (local dev) ─────────────────────────────────────────────
+class FileWalletStore {
+    path;
+    data = {};
+    constructor(path) {
+        this.path = path;
+        if (existsSync(path)) {
+            try {
+                this.data = JSON.parse(readFileSync(path, "utf-8"));
+            }
+            catch {
+                this.data = {};
+            }
+        }
+    }
+    async get(agentId) {
+        return this.data[agentId] ?? null;
+    }
+    async set(agentId, wallet) {
+        this.data[agentId] = wallet;
+        // Atomic write: write to .tmp then rename to avoid corruption on crash
+        const tmpPath = `${this.path}.tmp`;
+        writeFileSync(tmpPath, JSON.stringify(this.data, null, 2), "utf-8");
+        renameSync(tmpPath, this.path);
+    }
+    async has(agentId) {
+        return agentId in this.data;
+    }
+}
+// ─── AES-256-GCM Encryption (scrypt KDF) ───────────────────────────────
+// New wallets derive the AES key with a memory-hard scrypt KDF and a per-record
+// random salt, so a leaked WALLET_ENCRYPTION_KEY is far costlier to brute-force
+// than the old single-pass SHA-256 derivation. Ciphertext is versioned:
+//   "sh2:" + hex(salt[16] || iv[12] || tag[16] || ciphertext)  ← current (scrypt)
+//   <pure-hex>   iv[12] || tag[16] || ciphertext               ← legacy read-only
+//                (SHA-256-derived key; still decryptable for migration)
+// The old XOR path ("0x"-prefixed) is REMOVED — it was obfuscation, not encryption.
+const SCRYPT_VERSION_PREFIX = "sh2:";
+const SCRYPT_SALT_BYTES = 16;
+// N=16384,r=8,p=1 → ~16 MB, ~10-30 ms per derivation (once per managed signer resolve).
+const SCRYPT_PARAMS = { N: 16384, r: 8, p: 1, maxmem: 64 * 1024 * 1024 };
+function deriveKeyScrypt(encryptionKey, salt) {
+    return scryptSync(encryptionKey, salt, 32, SCRYPT_PARAMS);
+}
+/** Legacy single-pass SHA-256 KDF — read-only, for decrypting pre-scrypt wallets. */
+function deriveKeyLegacySha256(encryptionKey) {
+    return createHash("sha256").update(encryptionKey).digest();
+}
+/**
+ * Encrypts a private key with AES-256-GCM under a scrypt-derived key.
+ * Output: "sh2:" + hex(salt(16) || iv(12) || tag(16) || ciphertext).
+ */
+export function encryptKey(privateKey, encryptionKey) {
+    const salt = randomBytes(SCRYPT_SALT_BYTES);
+    const key = deriveKeyScrypt(encryptionKey, salt);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const plain = Buffer.from(privateKey.replace(/^0x/, ""), "hex");
+    const encrypted = Buffer.concat([cipher.update(plain), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return SCRYPT_VERSION_PREFIX + Buffer.concat([salt, iv, tag, encrypted]).toString("hex");
+}
+/**
+ * Decrypts a private key. Supports the current "sh2:" scrypt format and the
+ * legacy pure-hex SHA-256 AES-256-GCM format (read-only, for migration). The
+ * removed XOR path ("0x"-prefixed) is rejected — those wallets must be recreated.
+ */
+export function decryptKey(encrypted, encryptionKey) {
+    if (encrypted.startsWith("0x")) {
+        throw new Error("Legacy XOR-obfuscated wallet is no longer supported (it was not real encryption). " +
+            "Re-create the managed wallet so it is stored under AES-256-GCM + scrypt.");
+    }
+    if (encrypted.startsWith(SCRYPT_VERSION_PREFIX)) {
+        const data = Buffer.from(encrypted.slice(SCRYPT_VERSION_PREFIX.length), "hex");
+        const salt = data.subarray(0, SCRYPT_SALT_BYTES);
+        const iv = data.subarray(SCRYPT_SALT_BYTES, SCRYPT_SALT_BYTES + 12);
+        const tag = data.subarray(SCRYPT_SALT_BYTES + 12, SCRYPT_SALT_BYTES + 28);
+        const ciphertext = data.subarray(SCRYPT_SALT_BYTES + 28);
+        const key = deriveKeyScrypt(encryptionKey, salt);
+        const decipher = createDecipheriv("aes-256-gcm", key, iv);
+        decipher.setAuthTag(tag);
+        const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return "0x" + decrypted.toString("hex");
+    }
+    // Legacy pure-hex AES-256-GCM (SHA-256-derived key) — decrypt for migration only.
+    const data = Buffer.from(encrypted, "hex");
+    const key = deriveKeyLegacySha256(encryptionKey);
+    const iv = data.subarray(0, 12);
+    const tag = data.subarray(12, 28);
+    const ciphertext = data.subarray(28);
+    const decipher = createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(tag);
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return "0x" + decrypted.toString("hex");
+}
+// ─── Encryption key resolution ─────────────────────────────────────────
+// Random per-process fallback key — never hardcoded, never reused across restarts
+const IN_MEMORY_FALLBACK_KEY = randomBytes(32).toString("hex");
+/**
+ * Returns the effective encryption key.
+ * - Persistent store: WALLET_ENCRYPTION_KEY must be set (wallets won't survive restarts otherwise).
+ * - In-memory store: falls back to a random per-process key.
+ */
+export function getEffectiveEncryptionKey() {
+    return process.env.WALLET_ENCRYPTION_KEY || IN_MEMORY_FALLBACK_KEY;
+}
+// ─── Factory ────────────────────────────────────────────────────────────
+function createWalletStore() {
+    const storePath = process.env.WALLET_STORE_PATH;
+    if (storePath) {
+        return new FileWalletStore(storePath);
+    }
+    return new InMemoryWalletStore();
+}
+export function usesPersistentWalletStore() {
+    return Boolean(process.env.WALLET_STORE_PATH);
+}
+export const walletStore = createWalletStore();
 //# sourceMappingURL=index.js.map

package/dist/lib/wallet/index.js.map

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

package/dist/lib/x402ReplayStore.d.ts

@@ -0,0 +1,6 @@
+export interface ReplayRecordResult {
+    allowed: boolean;
+    backend: "upstash" | "file";
+}
+export declare function checkAndRecordX402Replay(paymentHeader: string, windowMs: number): Promise<ReplayRecordResult>;
+//# sourceMappingURL=x402ReplayStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"x402ReplayStore.d.ts","sourceRoot":"","sources":["../../src/lib/x402ReplayStore.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,SAAS,GAAG,MAAM,CAAC;CAC7B;AA0DD,wBAAsB,wBAAwB,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAUnH"}

package/dist/lib/x402ReplayStore.js

@@ -0,0 +1,79 @@
+// ─── x402 Replay Store ─────────────────────────────────────────────────
+// Durable replay protection. Uses Upstash Redis REST when configured, falling
+// back to an atomic local JSON file so a Single-Instance Production Deployment does
+// not lose replay state on process restart.
+// ────────────────────────────────────────────────────────────────────────
+import { createHash } from "crypto";
+import { fetchWithTimeoutAndRetry } from "./http.js";
+import { readJsonFile, stateFile, writeJsonFileAtomic } from "./persistentJsonStore.js";
+const FILE_PATH = stateFile("x402_replay.json", "SAFEHANDS_X402_REPLAY_STORE_PATH");
+function replayKey(paymentHeader) {
+    return `x402:${createHash("sha256").update(paymentHeader).digest("hex")}`;
+}
+async function upstashCommand(args) {
+    const url = process.env.UPSTASH_REDIS_REST_URL || process.env.SAFEHANDS_REDIS_REST_URL;
+    const token = process.env.UPSTASH_REDIS_REST_TOKEN || process.env.SAFEHANDS_REDIS_REST_TOKEN;
+    if (!url || !token)
+        throw new Error("Upstash Redis REST is not configured");
+    // The URL is operator-controlled env, so it goes through the SSRF-safe layer.
+    // A failed call falls back to the file store (or throws when
+    // SAFEHANDS_X402_REPLAY_REDIS_REQUIRED=true), so the retry budget stays small.
+    const res = await fetchWithTimeoutAndRetry(url, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(args),
+        timeoutMs: 5_000,
+        retries: 1,
+    });
+    if (!res.ok)
+        throw new Error(`Upstash Redis REST returned ${res.status}`);
+    const body = await res.json();
+    if (body.error)
+        throw new Error(body.error);
+    return body.result;
+}
+async function checkAndRecordUpstash(paymentHeader, windowMs) {
+    const key = replayKey(paymentHeader);
+    const exists = await upstashCommand(["GET", key]);
+    if (exists !== null && exists !== undefined)
+        return { allowed: false, backend: "upstash" };
+    const ttlSeconds = Math.max(1, Math.ceil(windowMs / 1000));
+    const setResult = await upstashCommand(["SET", key, String(Date.now()), "EX", String(ttlSeconds), "NX"]);
+    if (setResult === null)
+        return { allowed: false, backend: "upstash" };
+    return { allowed: true, backend: "upstash" };
+}
+function checkAndRecordFile(paymentHeader, windowMs) {
+    const now = Date.now();
+    const key = replayKey(paymentHeader);
+    const state = readJsonFile(FILE_PATH, { seen: {} });
+    for (const [k, ts] of Object.entries(state.seen)) {
+        if (now - ts >= windowMs)
+            delete state.seen[k];
+    }
+    const previous = state.seen[key];
+    if (previous !== undefined && now - previous < windowMs) {
+        writeJsonFileAtomic(FILE_PATH, state);
+        return { allowed: false, backend: "file" };
+    }
+    state.seen[key] = now;
+    writeJsonFileAtomic(FILE_PATH, state);
+    return { allowed: true, backend: "file" };
+}
+export async function checkAndRecordX402Replay(paymentHeader, windowMs) {
+    const hasUpstash = Boolean((process.env.UPSTASH_REDIS_REST_URL || process.env.SAFEHANDS_REDIS_REST_URL) && (process.env.UPSTASH_REDIS_REST_TOKEN || process.env.SAFEHANDS_REDIS_REST_TOKEN));
+    if (hasUpstash) {
+        try {
+            return await checkAndRecordUpstash(paymentHeader, windowMs);
+        }
+        catch (err) {
+            if (process.env.SAFEHANDS_X402_REPLAY_REDIS_REQUIRED === "true")
+                throw err;
+        }
+    }
+    return checkAndRecordFile(paymentHeader, windowMs);
+}
+//# sourceMappingURL=x402ReplayStore.js.map

package/dist/lib/x402ReplayStore.js.map

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

package/dist/sdk.d.ts

@@ -0,0 +1,14 @@
+export { evaluateActionPolicy, explainPolicyResult, isUnlimitedApprovalAmount, parseTokenAmountToUnits, } from "./lib/policy/actionPolicyEngine.js";
+export type { ActionPolicyInput, ActionPolicyResult, PolicyDecision, PolicyRiskLevel, PolicyCheck, SafeHandsActionType, } from "./lib/policy/actionPolicyEngine.js";
+export { enforceWriteDecision } from "./lib/policy/writeExecutionGate.js";
+export type { EnforceWriteDecisionOptions } from "./lib/policy/writeExecutionGate.js";
+export { assessRisk } from "./lib/riskEngine.js";
+export type { RiskAssessment, RiskInput, RiskBreakdown, RiskLevel, RiskRecommendation, } from "./lib/riskEngine.js";
+export { evaluateTokenSecurityGate } from "./tools/checkTokenSecurity.js";
+export type { TokenSecurityGateResult, TokenSecurityVerdict } from "./tools/checkTokenSecurity.js";
+export { ok, fail, errorMessage } from "./lib/toolResponse.js";
+export type { ToolResponse, ToolSuccess, ToolFailure, ToolError } from "./lib/toolResponse.js";
+export { getCapabilityFlags, getActiveNetworkConfig, getGates, isReadOnlyMode, isExecutionAvailable, writeToolsEnabled, } from "./lib/config.js";
+export type { CapabilityFlags, SafetyGates, ActiveNetworkConfig } from "./lib/config.js";
+export { CHAIN_ID, PHAROS_ENVIRONMENT, IS_MAINNET } from "./lib/constants.js";
+//# sourceMappingURL=sdk.d.ts.map

package/dist/sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../src/sdk.ts"],"names":[],"mappings":"AAYA,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,oCAAoC,CAAC;AAC5C,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,WAAW,EACX,mBAAmB,GACpB,MAAM,oCAAoC,CAAC;AAG5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC1E,YAAY,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AAGtF,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,YAAY,EACV,cAAc,EACd,SAAS,EACT,aAAa,EACb,SAAS,EACT,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAC1E,YAAY,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAGnG,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC/D,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAG/F,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,QAAQ,EACR,cAAc,EACd,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAGzF,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/sdk.js

@@ -0,0 +1,25 @@
+// ─── SafeHands SDK — programmatic entrypoint ───────────────────────────────
+// Side-effect-free barrel for embedding SafeHands' deterministic policy/risk
+// engine in your own code. Importing this module NEVER starts the MCP server and
+// NEVER reads a wallet/key — that behaviour lives only in the `safehands` CLI bin
+// (dist/index.js). package.json `main`/`types`/`exports` point HERE so that
+//   import { evaluateActionPolicy } from "safehands-pharos"
+// resolves to real, callable exports (previously it resolved to the MCP bootstrap,
+// which has no named exports and would have started a stdio server on import).
+// ───────────────────────────────────────────────────────────────────────────
+// Deterministic action-policy engine — ALLOW / BLOCK / REQUIRE_CONFIRMATION /
+// REQUIRE_FUNDING / REQUIRE_TOKEN_REVIEW before any agent action.
+export { evaluateActionPolicy, explainPolicyResult, isUnlimitedApprovalAmount, parseTokenAmountToUnits, } from "./lib/policy/actionPolicyEngine.js";
+// Write-execution gate — halts a direct write tool on ANY non-ALLOW decision.
+export { enforceWriteDecision } from "./lib/policy/writeExecutionGate.js";
+// 5-dimension risk engine (liquidity / slippage / counterparty / balance / market).
+export { assessRisk } from "./lib/riskEngine.js";
+// Token-security (GoPlus) fail-closed gate used on the execute path.
+export { evaluateTokenSecurityGate } from "./tools/checkTokenSecurity.js";
+// Structured tool-response envelope shared by every SafeHands surface.
+export { ok, fail, errorMessage } from "./lib/toolResponse.js";
+// Honest capability flags + network / safety-gate posture (read-only by default).
+export { getCapabilityFlags, getActiveNetworkConfig, getGates, isReadOnlyMode, isExecutionAvailable, writeToolsEnabled, } from "./lib/config.js";
+// Network identity constants (Pharos Pacific Mainnet, chain 1672).
+export { CHAIN_ID, PHAROS_ENVIRONMENT, IS_MAINNET } from "./lib/constants.js";
+//# sourceMappingURL=sdk.js.map

package/dist/sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.js","sourceRoot":"","sources":["../src/sdk.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,6EAA6E;AAC7E,iFAAiF;AACjF,kFAAkF;AAClF,4EAA4E;AAC5E,4DAA4D;AAC5D,mFAAmF;AACnF,+EAA+E;AAC/E,8EAA8E;AAE9E,8EAA8E;AAC9E,kEAAkE;AAClE,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,oCAAoC,CAAC;AAU5C,8EAA8E;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAG1E,oFAAoF;AACpF,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AASjD,qEAAqE;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAG1E,uEAAuE;AACvE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAG/D,kFAAkF;AAClF,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,QAAQ,EACR,cAAc,EACd,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAGzB,mEAAmE;AACnE,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}