@prism-ing/wallet 0.1.0

package/SPEC.md

@@ -0,0 +1,192 @@
+# @prism-ing/wallet — Specification
+
+**Version:** 0.2.0
+**Status:** Release Candidate
+**Last Updated:** April 2026
+
+## Purpose
+
+@prism-ing/wallet is a production-grade, framework-agnostic wallet SDK that provides self-custodial wallet functionality across EVM and Solana chains. It integrates:
+
+- **iOS Secure Enclave** for hardware-backed key security with biometric authentication
+- **OWS (Open Wallet Standard)** for Node.js software signing with encrypted persistence
+- **OneBalance** for ERC-4337 account abstraction and cross-chain execution
+- **ZeroDev Kernel v3.1** for EVM social recovery and on-chain session key enforcement
+- **Squads V4** for Solana multisig-based key recovery
+
+Any application — mobile, web, CLI, agent — can install this package and get best-in-class wallet functionality in under 50 lines of integration code.
+
+## Design Decisions
+
+### No Seed Phrases
+
+The wallet never generates, stores, or exports mnemonic phrases to users. Keys are created via the Secure Enclave (iOS) or OWS software signing (Node/browser) and are non-exportable through the SDK's API. Recovery is handled via social recovery (ZeroDev guardians + Squads co-signers), not by re-deriving keys from a seed.
+
+### Signer Injection Pattern
+
+Router packages (`@prism-ing/evm-router`, `@prism-ing/sol-router`) accept any object conforming to the `PrismSigner` interface. They never import `@prism-ing/wallet` directly. This means external applications can use routers with their own signing solution.
+
+### Result Types Over Exceptions
+
+All fallible operations return `Result<T, WalletError>` instead of throwing. This makes failure explicit in the type system and eliminates the need for try/catch in consumer code. The only place exceptions are caught is in `fromPromise()`, which wraps third-party calls at the boundary.
+
+### Counterfactual Accounts
+
+OneBalance accounts are initialized counterfactually — no on-chain transaction is needed to create an account. The address is deterministic from the signer's public key. Funds can be received at the address before any on-chain deployment.
+
+### Backend Injection (No Direct SDK Dependencies)
+
+ZeroDev and Squads operations are injected via bridge interfaces (`ZeroDevSessionBackendConfig`, `SquadsNativeBridge`). This keeps `@prism-ing/wallet` free of transitive dependencies on `@zerodev/sdk` and `@sqds/multisig` — consumers provide their own integration, and the wallet SDK handles orchestration and policy mapping.
+
+## Private Key Security Model
+
+### iOS Secure Enclave Backend
+
+- Keys (secp256k1 for EVM, ed25519 for Solana) are generated and encrypted by the Secure Enclave's hardware P-256 key
+- Encrypted keys are stored in the iOS Keychain, tagged by wallet identifier
+- Every signing operation requires biometric authentication (Face ID / Touch ID) via `LocalAuthentication`
+- After biometric success, the encrypted key is decrypted in-process for signing, then discarded
+- The `OWSKeyPair` type stores only the Keychain tag and derived addresses, never private key material
+- The Secure Enclave does not natively support secp256k1 — it provides encryption/decryption for key-at-rest protection, not direct signing
+
+### Node.js OWS Backend
+
+- BIP-39 mnemonic generates secp256k1 + ed25519 keys
+- Keys are encrypted at rest with scrypt + AES-256-GCM at `~/.ows/`
+- Same wallet name = same keys across sessions (deterministic from mnemonic)
+- Two auth modes: passphrase (owner) or API key (agent, policy-gated)
+- Keys are held in-memory during the process lifetime
+
+### Node.js Software Backend
+
+- Random key generation via `@noble/hashes` CSPRNG
+- Keys held in-memory Map only — no persistence, no encryption
+- Intended for testing and development only
+- Production deployments should use OWS or Secure Enclave
+
+### Security Assumptions
+
+1. **The runtime environment is trusted.** Private keys are decrypted in-process for signing. A compromised Node.js process or jailbroken iOS device could extract key material. Session keys and on-chain enforcement mitigate this.
+
+2. **OneBalance is a trusted co-signer.** Quote generation, settlement, and account abstraction depend on OneBalance availability and correctness. Client-side quote verification provides defense-in-depth but cannot independently verify settlement.
+
+3. **Recovery backends are correctly implemented.** The wallet SDK orchestrates recovery but delegates on-chain operations to injected backends. A buggy `EvmRecoveryBackend` or `SquadsNativeBridge` could fail to rotate signers correctly.
+
+4. **Time-based security relies on system clocks.** Recovery challenge time windows and session key expiration use `Date.now()`. A significantly skewed clock could extend or shorten these windows.
+
+## Session Keys
+
+Session keys are ephemeral, policy-scoped signers that wrap the root `PrismSigner`. They limit what an agent or automated process can do without holding unrestricted root signing authority.
+
+### Policy Dimensions
+
+| Dimension | Field | Effect |
+|-----------|-------|--------|
+| Time | `expiresAt` | Session becomes inactive after this Unix timestamp |
+| Assets | `allowedAssets` | Only these OneBalance asset IDs can be operated on |
+| Per-op amount | `maxAmountPerOp` | Single operation cannot exceed this amount |
+| Cumulative amount | `maxTotalAmount` | Total spend across all operations is capped |
+| Recipients | `allowedRecipients` | Only these addresses can be destinations |
+| Chains | `allowedChains` | Only these chain IDs are permitted |
+
+### Enforcement Architecture
+
+**Layer 1: Client-side (always active)**
+The session signer checks policy before every `signMessage`, `signTypedData`, and `signTransaction`. Violations throw immediately, preventing the signature from being produced.
+
+**Layer 2: On-chain (optional, via ZeroDev)**
+When a `SessionKeyBackend` is provided, policies are mapped to ZeroDev Kernel v3.1 permission validators using `mapSessionPolicyToZeroDev()`. The smart contract enforces the same constraints on-chain.
+
+**Policy mapping to ZeroDev:**
+- `expiresAt` → `toTimestampPolicy({ validUntil })` — on-chain expiration
+- `allowedAssets` → `toCallPolicy({ permissions })` — ERC-20 `transfer()` function selector + contract address restrictions
+- `maxAmountPerOp` → `ParamCondition.LESS_THAN_OR_EQUAL` on transfer amount parameter
+- `allowedRecipients` → `ParamCondition.ONE_OF` on transfer recipient parameter
+- A `toGasPolicy` (default 0.1 ETH) is always included — prevents gas drain
+- A `toRateLimitPolicy` is included when amount caps are set (100 ops/hour)
+- CallPolicyVersion V0.0.4 is used by default (fixes ERC-4337 storage access violation for Alchemy bundler compatibility)
+
+**Security consideration:** Client-side spend tracking (`totalSpent`) resets when the process restarts. For agents that may restart, rely on on-chain enforcement via ZeroDev rather than client-side cumulative caps.
+
+## Social Recovery
+
+### Architecture
+
+Recovery rotates the smart contract's authorized signer. The original key becomes useless. Funds never move.
+
+**EVM (ZeroDev Kernel v3.1):**
+- Guardian registered via `EvmRecoveryBackend.addGuardian()`
+- Rotation: `rotateValidator(oldSigner, newSigner, guardianProof)` calls `removeValidator(old)` + `addValidator(new)` on the Kernel contract
+
+**Solana (Squads V4):**
+- Guardian registered via `SolanaRecoveryBackend.addMember()` as a Voter member
+- Rotation: `rotateMember(oldSigner, newSigner, guardianProof)` creates a config transaction with `AddMember(new, fullPermissions)` + `RemoveMember(old)`
+- `configAuthority: null` — all changes go through proposal/approval/execute flow
+- `AddMember` before `RemoveMember` in the same transaction prevents zero-member state
+- Threshold auto-increments when adding guardians (configurable)
+
+### Recovery Challenge (Anti-Replay)
+
+```
+challenge = keccak256(
+  "prism-recovery-v1"    // Domain tag
+  || currentSigner       // Being rotated away
+  || newSigner           // Being rotated to
+  || floor(now / 300000) // 5-minute time window
+)
+```
+
+Properties:
+- A proof for A → B cannot replay for A → C (different `newSigner`)
+- A proof expires within 5 minutes (time-bounded)
+- A proof for wallet X cannot be used on wallet Y (different `currentSigner`)
+- The domain tag prevents cross-protocol replay
+
+### Guardian Security
+
+- Passkey guardians derive an EVM address from the WebAuthn public key via `keccak256`
+- Device guardians are registered on both EVM (via ZeroDev) and Solana (via Squads)
+- Contact guardians are registered on EVM only (requires `EvmRecoveryBackend`)
+- Guardian proofs are obtained via passkey signing or provided out-of-band
+
+## Quote Verification
+
+Before signing any OneBalance quote, `executeCrossChain` performs 6 client-side checks:
+
+1. **Expiration** — `expirationTimestamp` vs current time
+2. **Tamper-proof signature** — OneBalance's `tamperProofSignature` field is present and non-empty
+3. **Origin asset** — Quote's origin asset matches the requested `fromAsset`
+4. **Origin amount** — Within configurable slippage tolerance (default 1%)
+5. **Destination asset** — Quote's destination matches the requested `toAsset`
+6. **EVM sender** — All `userOp.sender` fields match the wallet's `accountAddress`
+
+This prevents blind-signing attacks where a compromised or man-in-the-middle API could alter the EIP-712 payload to transfer funds to an attacker's address.
+
+## Network Resilience
+
+The OneBalance HTTP client includes:
+- Exponential backoff with jitter (3 retries, base delay 1s → 2s → 4s + random jitter)
+- Retries only on: timeouts (AbortError), network errors (TypeError), and 5xx server errors
+- No retry on 4xx client errors (bad request, auth failure, validation)
+- Configurable via `maxRetries` and `baseDelayMs` in `OneBalanceHttpConfig`
+
+## Error Codes
+
+| Code | Retryable | User-Facing | Description |
+|------|-----------|-------------|-------------|
+| `ENCLAVE_UNAVAILABLE` | No | No | Secure Enclave not available on this platform |
+| `ONEBALANCE_TIMEOUT` | Yes | No | OneBalance API did not respond in time |
+| `ONEBALANCE_API_ERROR` | Yes | No | OneBalance API returned an error |
+| `RECOVERY_GUARDIAN_INVALID` | No | Yes | Invalid guardian address |
+| `SIGNING_REJECTED` | No | Yes | User rejected signing (biometric fail / cancel) |
+| `ACCOUNT_NOT_INITIALIZED` | No | No | Operation on uninitialized account |
+| `INSUFFICIENT_BALANCE` | No | Yes | Not enough balance for operation |
+| `KEY_NOT_FOUND` | No | No | Requested key pair not found in signing backend |
+| `VALIDATION_ERROR` | No | Yes | Input failed Zod validation |
+| `SESSION_KEY_EXPIRED` | No | No | Session key has expired or been revoked |
+| `SESSION_KEY_POLICY_VIOLATION` | No | Yes | Operation violates session key policy |
+| `QUOTE_VERIFICATION_FAILED` | No | No | OneBalance quote failed integrity verification |
+
+## Upgrade Policy
+
+Breaking changes require a major version bump and a changeset entry. The `PrismSigner` interface is considered frozen after v1.0 — any changes to it are treated as a critical breaking change across the entire monorepo.

package/dist/backends/squads-recovery-backend.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Squads V4 Solana recovery backend.
+ *
+ * @remarks
+ * Implements {@link SolanaRecoveryBackend} using Squads V4 multisig
+ * operations for guardian-based key recovery on Solana.
+ *
+ * Architecture:
+ * - Wallet's Solana signer is a member of a Squads V4 multisig
+ * - Guardians are added as additional members with Voter permissions
+ * - Recovery rotates the signer: AddMember(new) + RemoveMember(old)
+ * - All changes go through config transactions (proposal → approval → execution)
+ * - No `configAuthority` — all changes require guardian approval
+ *
+ * Key design decisions:
+ * - **AddMember before RemoveMember** — actions execute in order, preventing
+ *   a moment with zero members
+ * - **Auto-increment threshold** — adding a guardian increases the approval
+ *   threshold, requiring more guardian consensus
+ * - **Config transactions invalidate active transactions** — expected during
+ *   recovery (Squads V4 behavior)
+ *
+ * @packageDocumentation
+ */
+import type { SolanaRecoveryBackend } from '../types.js';
+import type { SquadsRecoveryBackendConfig } from './squads-types.js';
+/**
+ * Create a Squads V4 Solana recovery backend.
+ *
+ * @remarks
+ * The backend delegates all Squads SDK operations to the injected
+ * {@link SquadsNativeBridge}. This keeps `@prism-ing/wallet` free of a
+ * direct `@sqds/multisig` dependency.
+ *
+ * @example
+ * ```ts
+ * import * as multisig from '@sqds/multisig';
+ *
+ * const bridge: SquadsNativeBridge = {
+ *   async executeConfigTransaction(actions) {
+ *     // Create config tx, proposal, approve, execute
+ *     const txIndex = await getNextTransactionIndex(multisigPda);
+ *     await multisig.rpc.configTransactionCreate({ multisigPda, transactionIndex: txIndex, creator, actions });
+ *     await multisig.rpc.proposalCreate({ multisigPda, transactionIndex: txIndex, creator });
+ *     await multisig.rpc.proposalApprove({ multisigPda, transactionIndex: txIndex, member: guardian });
+ *     return await multisig.rpc.configTransactionExecute({ multisigPda, transactionIndex: txIndex, member: guardian });
+ *   },
+ *   async getThreshold() { ... },
+ *   async getMemberCount() { ... },
+ * };
+ *
+ * const backend = createSquadsRecoveryBackend({ bridge });
+ * ```
+ *
+ * @param config - Squads backend configuration with bridge functions.
+ * @returns A {@link SolanaRecoveryBackend} for guardian-based Solana recovery.
+ */
+export declare function createSquadsRecoveryBackend(config: SquadsRecoveryBackendConfig): SolanaRecoveryBackend;
+//# sourceMappingURL=squads-recovery-backend.d.ts.map

package/dist/backends/squads-recovery-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"squads-recovery-backend.d.ts","sourceRoot":"","sources":["../../src/backends/squads-recovery-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EACV,2BAA2B,EAG5B,MAAM,mBAAmB,CAAC;AAO3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,2BAA2B,GAClC,qBAAqB,CAsDvB"}

package/dist/backends/squads-recovery-backend.js

@@ -0,0 +1,81 @@
+import { FULL_PERMISSIONS, VOTER_PERMISSIONS } from './squads-types.js';
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a Squads V4 Solana recovery backend.
+ *
+ * @remarks
+ * The backend delegates all Squads SDK operations to the injected
+ * {@link SquadsNativeBridge}. This keeps `@prism-ing/wallet` free of a
+ * direct `@sqds/multisig` dependency.
+ *
+ * @example
+ * ```ts
+ * import * as multisig from '@sqds/multisig';
+ *
+ * const bridge: SquadsNativeBridge = {
+ *   async executeConfigTransaction(actions) {
+ *     // Create config tx, proposal, approve, execute
+ *     const txIndex = await getNextTransactionIndex(multisigPda);
+ *     await multisig.rpc.configTransactionCreate({ multisigPda, transactionIndex: txIndex, creator, actions });
+ *     await multisig.rpc.proposalCreate({ multisigPda, transactionIndex: txIndex, creator });
+ *     await multisig.rpc.proposalApprove({ multisigPda, transactionIndex: txIndex, member: guardian });
+ *     return await multisig.rpc.configTransactionExecute({ multisigPda, transactionIndex: txIndex, member: guardian });
+ *   },
+ *   async getThreshold() { ... },
+ *   async getMemberCount() { ... },
+ * };
+ *
+ * const backend = createSquadsRecoveryBackend({ bridge });
+ * ```
+ *
+ * @param config - Squads backend configuration with bridge functions.
+ * @returns A {@link SolanaRecoveryBackend} for guardian-based Solana recovery.
+ */
+export function createSquadsRecoveryBackend(config) {
+    const bridge = config.bridge;
+    const autoIncrement = config.autoIncrementThreshold !== false;
+    const backend = {
+        async addMember(solanaAddress) {
+            const actions = [
+                {
+                    __kind: 'AddMember',
+                    newMember: {
+                        key: solanaAddress,
+                        permissions: VOTER_PERMISSIONS,
+                    },
+                },
+            ];
+            // Auto-increment threshold when adding a guardian
+            if (autoIncrement) {
+                const currentThreshold = await bridge.getThreshold();
+                actions.push({
+                    __kind: 'ChangeThreshold',
+                    newThreshold: currentThreshold + 1,
+                });
+            }
+            return bridge.executeConfigTransaction(actions);
+        },
+        async rotateMember(oldSigner, newSigner, _guardianProof) {
+            // AddMember first, then RemoveMember — ensures the multisig
+            // never has zero members during the rotation
+            const actions = [
+                {
+                    __kind: 'AddMember',
+                    newMember: {
+                        key: newSigner,
+                        permissions: FULL_PERMISSIONS,
+                    },
+                },
+                {
+                    __kind: 'RemoveMember',
+                    oldMember: oldSigner,
+                },
+            ];
+            return bridge.executeConfigTransaction(actions);
+        },
+    };
+    return backend;
+}
+//# sourceMappingURL=squads-recovery-backend.js.map

package/dist/backends/squads-recovery-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"squads-recovery-backend.js","sourceRoot":"","sources":["../../src/backends/squads-recovery-backend.ts"],"names":[],"mappings":"AA8BA,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAExE,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,2BAA2B,CACzC,MAAmC;IAEnC,MAAM,MAAM,GAAuB,MAAM,CAAC,MAAM,CAAC;IACjD,MAAM,aAAa,GAAG,MAAM,CAAC,sBAAsB,KAAK,KAAK,CAAC;IAE9D,MAAM,OAAO,GAA0B;QACrC,KAAK,CAAC,SAAS,CAAC,aAAqB;YACnC,MAAM,OAAO,GAAyB;gBACpC;oBACE,MAAM,EAAE,WAAW;oBACnB,SAAS,EAAE;wBACT,GAAG,EAAE,aAAa;wBAClB,WAAW,EAAE,iBAAiB;qBAC/B;iBACF;aACF,CAAC;YAEF,kDAAkD;YAClD,IAAI,aAAa,EAAE,CAAC;gBAClB,MAAM,gBAAgB,GAAG,MAAM,MAAM,CAAC,YAAY,EAAE,CAAC;gBACrD,OAAO,CAAC,IAAI,CAAC;oBACX,MAAM,EAAE,iBAAiB;oBACzB,YAAY,EAAE,gBAAgB,GAAG,CAAC;iBACnC,CAAC,CAAC;YACL,CAAC;YAED,OAAO,MAAM,CAAC,wBAAwB,CAAC,OAAO,CAAC,CAAC;QAClD,CAAC;QAED,KAAK,CAAC,YAAY,CAChB,SAAiB,EACjB,SAAiB,EACjB,cAA0B;YAE1B,4DAA4D;YAC5D,6CAA6C;YAC7C,MAAM,OAAO,GAAyB;gBACpC;oBACE,MAAM,EAAE,WAAW;oBACnB,SAAS,EAAE;wBACT,GAAG,EAAE,SAAS;wBACd,WAAW,EAAE,gBAAgB;qBAC9B;iBACF;gBACD;oBACE,MAAM,EAAE,cAAc;oBACtB,SAAS,EAAE,SAAS;iBACrB;aACF,CAAC;YAEF,OAAO,MAAM,CAAC,wBAAwB,CAAC,OAAO,CAAC,CAAC;QAClD,CAAC;KACF,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/backends/squads-types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Types for the Squads V4 Solana recovery backend.
+ *
+ * @remarks
+ * These types model the Squads V4 multisig operations needed for
+ * key recovery: member management and config transaction execution.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Squads V4 member permissions.
+ *
+ * @remarks
+ * Maps to `Permissions` from `@sqds/multisig`. Members can have
+ * any combination of Proposer, Voter, and Executor roles.
+ */
+export interface SquadsMemberPermissions {
+    readonly proposer: boolean;
+    readonly voter: boolean;
+    readonly executor: boolean;
+}
+/** All permissions enabled. */
+export declare const FULL_PERMISSIONS: SquadsMemberPermissions;
+/** Voter-only permissions (for guardians). */
+export declare const VOTER_PERMISSIONS: SquadsMemberPermissions;
+/**
+ * Config actions for Squads V4 config transactions.
+ *
+ * @remarks
+ * Config transactions modify the multisig's configuration (members,
+ * threshold, time lock). They go through the full proposal flow:
+ * create → approve → execute.
+ */
+export type SquadsConfigAction = {
+    readonly __kind: 'AddMember';
+    readonly newMember: {
+        readonly key: string;
+        readonly permissions: SquadsMemberPermissions;
+    };
+} | {
+    readonly __kind: 'RemoveMember';
+    readonly oldMember: string;
+} | {
+    readonly __kind: 'ChangeThreshold';
+    readonly newThreshold: number;
+};
+/**
+ * Native bridge to the Squads V4 SDK.
+ *
+ * @remarks
+ * Consumers implement this by wrapping `@sqds/multisig` operations.
+ * This keeps `@prism-ing/wallet` free of a direct Squads dependency.
+ */
+export interface SquadsNativeBridge {
+    /** Execute a full config transaction: create → propose → approve → execute. */
+    executeConfigTransaction(actions: readonly SquadsConfigAction[]): Promise<string>;
+    /** Get the current multisig threshold. */
+    getThreshold(): Promise<number>;
+    /** Get the current member count. */
+    getMemberCount(): Promise<number>;
+}
+/**
+ * Configuration for the Squads V4 recovery backend.
+ */
+export interface SquadsRecoveryBackendConfig {
+    /** The Squads native bridge for executing multisig operations. */
+    readonly bridge: SquadsNativeBridge;
+    /**
+     * Whether to auto-increment threshold when adding guardians.
+     * Defaults to `true` — adding a guardian increases the threshold by 1.
+     */
+    readonly autoIncrementThreshold?: boolean;
+}
+//# sourceMappingURL=squads-types.d.ts.map

package/dist/backends/squads-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"squads-types.d.ts","sourceRoot":"","sources":["../../src/backends/squads-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,+BAA+B;AAC/B,eAAO,MAAM,gBAAgB,EAAE,uBAIrB,CAAC;AAEX,8CAA8C;AAC9C,eAAO,MAAM,iBAAiB,EAAE,uBAItB,CAAC;AAEX;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,uBAAuB,CAAA;KAAE,CAAA;CAAE,GAC7H;IAAE,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,wBAAwB,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAElF,0CAA0C;IAC1C,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAEhC,oCAAoC;IACpC,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IAEpC;;;OAGG;IACH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAC3C"}

package/dist/backends/squads-types.js

@@ -0,0 +1,22 @@
+/**
+ * Types for the Squads V4 Solana recovery backend.
+ *
+ * @remarks
+ * These types model the Squads V4 multisig operations needed for
+ * key recovery: member management and config transaction execution.
+ *
+ * @packageDocumentation
+ */
+/** All permissions enabled. */
+export const FULL_PERMISSIONS = {
+    proposer: true,
+    voter: true,
+    executor: true,
+};
+/** Voter-only permissions (for guardians). */
+export const VOTER_PERMISSIONS = {
+    proposer: false,
+    voter: true,
+    executor: false,
+};
+//# sourceMappingURL=squads-types.js.map

package/dist/backends/squads-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"squads-types.js","sourceRoot":"","sources":["../../src/backends/squads-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAeH,+BAA+B;AAC/B,MAAM,CAAC,MAAM,gBAAgB,GAA4B;IACvD,QAAQ,EAAE,IAAI;IACd,KAAK,EAAE,IAAI;IACX,QAAQ,EAAE,IAAI;CACN,CAAC;AAEX,8CAA8C;AAC9C,MAAM,CAAC,MAAM,iBAAiB,GAA4B;IACxD,QAAQ,EAAE,KAAK;IACf,KAAK,EAAE,IAAI;IACX,QAAQ,EAAE,KAAK;CACP,CAAC"}

package/dist/backends/zerodev-policy-mapper.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Maps Prism session key policies to ZeroDev on-chain policy representations.
+ *
+ * @remarks
+ * This module is the bridge between Prism's {@link SessionKeyPolicy} (agent-friendly,
+ * asset-centric) and ZeroDev's on-chain permission system (contract-centric,
+ * function-selector based). The mapped policies are then registered on-chain
+ * via the ZeroDev SDK.
+ *
+ * Policy mapping follows ZeroDev best practices:
+ * - Always include a timestamp policy (every session must expire)
+ * - Always include a gas policy (prevent gas budget drain)
+ * - Use CallPolicyVersion V0.0.4 (Alchemy bundler compatible)
+ * - Map asset whitelists to ERC-20 transfer call restrictions
+ * - Map recipient whitelists to `ONE_OF` parameter conditions
+ * - Map amount caps to `LESS_THAN_OR_EQUAL` parameter conditions
+ *
+ * @internal
+ */
+import type { Address } from '../result.js';
+import type { SessionKeyPolicy } from '../types.js';
+import type { ZeroDevPolicy, CallPolicyVersion } from './zerodev-types.js';
+/**
+ * Map a Prism {@link SessionKeyPolicy} to ZeroDev on-chain policies.
+ *
+ * @param policy - The Prism session key policy to map.
+ * @param options - Optional overrides for gas budget and call policy version.
+ * @returns An array of ZeroDev policies ready for on-chain registration.
+ */
+export declare function mapSessionPolicyToZeroDev(policy: SessionKeyPolicy, options?: {
+    readonly gasBudgetWei?: bigint;
+    readonly callPolicyVersion?: CallPolicyVersion;
+}): readonly ZeroDevPolicy[];
+/**
+ * Resolve a OneBalance asset identifier to a contract address.
+ *
+ * @param asset - OneBalance asset ID (e.g., `'ob:usdc'`).
+ * @returns The contract address, or undefined if unknown.
+ */
+export declare function resolveAssetToContract(asset: string): Address | undefined;
+//# sourceMappingURL=zerodev-policy-mapper.d.ts.map

package/dist/backends/zerodev-policy-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zerodev-policy-mapper.d.ts","sourceRoot":"","sources":["../../src/backends/zerodev-policy-mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EACV,aAAa,EAGb,iBAAiB,EAClB,MAAM,oBAAoB,CAAC;AAsC5B;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,gBAAgB,EACxB,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CAChD,GACA,SAAS,aAAa,EAAE,CAwC1B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAEzE"}

package/dist/backends/zerodev-policy-mapper.js

@@ -0,0 +1,127 @@
+import { RECOMMENDED_CALL_POLICY_VERSION } from './zerodev-types.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default gas budget: 0.1 ETH in wei. */
+const DEFAULT_GAS_BUDGET_WEI = 100000000000000000n;
+/**
+ * ERC-20 transfer function selector: `transfer(address,uint256)`.
+ * keccak256("transfer(address,uint256)") = 0xa9059cbb...
+ */
+const ERC20_TRANSFER_SELECTOR = '0xa9059cbb';
+/**
+ * Well-known OneBalance asset identifiers mapped to contract addresses.
+ *
+ * @remarks
+ * OneBalance uses `ob:` prefixed asset IDs. This map resolves them to
+ * the canonical ERC-20 contract addresses on supported chains.
+ * The zero address is used as a wildcard — the actual per-chain address
+ * is resolved by OneBalance at quote time. This restricts the function
+ * selector while allowing OneBalance to handle chain-specific routing.
+ */
+const ASSET_CONTRACT_MAP = {
+    'ob:usdc': '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+    'ob:usdt': '0xdAC17F958D2ee523a2206206994597C13D831ec7',
+    'ob:dai': '0x6B175474E89094C44Da98b954EedeAC495271d0F',
+    'ob:weth': '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
+    'ob:wbtc': '0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599',
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Map a Prism {@link SessionKeyPolicy} to ZeroDev on-chain policies.
+ *
+ * @param policy - The Prism session key policy to map.
+ * @param options - Optional overrides for gas budget and call policy version.
+ * @returns An array of ZeroDev policies ready for on-chain registration.
+ */
+export function mapSessionPolicyToZeroDev(policy, options) {
+    const policies = [];
+    // 1. Timestamp policy — every session key MUST expire
+    policies.push({
+        type: 'timestamp',
+        validAfter: 0,
+        validUntil: policy.expiresAt,
+    });
+    // 2. Gas policy — prevent session key from draining gas budget
+    policies.push({
+        type: 'gas',
+        maxGasAllowedWei: options?.gasBudgetWei ?? DEFAULT_GAS_BUDGET_WEI,
+    });
+    // 3. Rate limit policy — if maxAmountPerOp implies operational limits
+    //    Use a sensible default: 100 operations per hour
+    if (policy.maxAmountPerOp !== undefined) {
+        policies.push({
+            type: 'rate_limit',
+            count: 100,
+            interval: 3600,
+        });
+    }
+    // 4. Call policy — map asset/recipient/amount restrictions to contract calls
+    const callPermissions = buildCallPermissions(policy, options?.callPolicyVersion ?? RECOMMENDED_CALL_POLICY_VERSION);
+    if (callPermissions.length > 0) {
+        policies.push({
+            type: 'call',
+            version: options?.callPolicyVersion ?? RECOMMENDED_CALL_POLICY_VERSION,
+            permissions: callPermissions,
+        });
+    }
+    return policies;
+}
+/**
+ * Resolve a OneBalance asset identifier to a contract address.
+ *
+ * @param asset - OneBalance asset ID (e.g., `'ob:usdc'`).
+ * @returns The contract address, or undefined if unknown.
+ */
+export function resolveAssetToContract(asset) {
+    return ASSET_CONTRACT_MAP[asset.toLowerCase()];
+}
+// ---------------------------------------------------------------------------
+// Internal Helpers
+// ---------------------------------------------------------------------------
+function buildCallPermissions(policy, _version) {
+    const permissions = [];
+    const assets = policy.allowedAssets ?? [];
+    // If no asset restrictions, no call policy needed
+    // (the timestamp + gas policies still protect)
+    if (assets.length === 0 && (policy.allowedRecipients === undefined || policy.allowedRecipients.length === 0)) {
+        return permissions;
+    }
+    // Build a permission entry for each allowed asset
+    for (const asset of assets) {
+        const contractAddress = resolveAssetToContract(asset);
+        if (contractAddress === undefined)
+            continue;
+        const args = [];
+        // Restrict recipients (first arg of transfer: address to)
+        if (policy.allowedRecipients !== undefined && policy.allowedRecipients.length > 0) {
+            // ONE_OF condition: recipient must be in the allowed list
+            // Encode each address as a 32-byte ABI-encoded value
+            for (const recipient of policy.allowedRecipients) {
+                args.push({
+                    condition: 'ONE_OF',
+                    offset: 0, // First parameter (address to)
+                    value: recipient,
+                });
+            }
+        }
+        // Restrict amount (second arg of transfer: uint256 amount)
+        if (policy.maxAmountPerOp !== undefined) {
+            args.push({
+                condition: 'LESS_THAN_OR_EQUAL',
+                offset: 32, // Second parameter (uint256 amount), 32 bytes after first
+                value: policy.maxAmountPerOp,
+            });
+        }
+        permissions.push({
+            target: contractAddress,
+            functionSelector: ERC20_TRANSFER_SELECTOR,
+            valueLimit: 0n, // No native ETH value for ERC-20 transfers
+            args,
+        });
+    }
+    return permissions;
+}
+//# sourceMappingURL=zerodev-policy-mapper.js.map

package/dist/backends/zerodev-policy-mapper.js.map

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