@prism-ing/wallet 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# @prism-ing/wallet
+
+## Unreleased
+
+### Minor Changes
+
+- **Session keys**: `createSessionKeyManager()` creates policy-scoped ephemeral signers for agents. Policies constrain time, assets, amounts, recipients, and chains. Optional `SessionKeyBackend` for on-chain enforcement via ZeroDev permission validators.
+- **Quote verification**: `executeCrossChain()` now verifies OneBalance quotes before signing — checks expiration, asset/amount match, sender integrity, and tamper-proof signature. Configurable via `accountAddress` and `skipVerification` params.
+- **Dynamic recovery challenge**: Recovery proofs are now bound to the specific signer rotation (current + new address) and a 5-minute time window, preventing replay attacks. Replaces the previous static challenge.
+- New error codes: `SESSION_KEY_EXPIRED`, `SESSION_KEY_POLICY_VIOLATION`, `QUOTE_VERIFICATION_FAILED`.
+- New exports: `createSessionKeyManager`, `validateSessionOperation`, `verifyQuoteIntegrity`, `verifyEvmOperation`, `buildRecoveryChallenge`.
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial public release: OWS signing (Node.js software signer), OneBalance account abstraction, cross-chain execution, social recovery via guardian rotation.
+
+## 0.0.1
+
+- Initial implementation: OWS Node.js software signer, OneBalance account abstraction, recovery manager

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prism
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,596 @@
+# @prism-ing/wallet
+
+Self-custodial smart contract wallet SDK. Hardware-backed key security via iOS Secure Enclave, cross-chain execution via OneBalance Resource Locks, social recovery via ZeroDev (EVM) and Squads V4 (Solana). Built for agents, trading apps, and mobile wallets.
+
+## Install
+
+```bash
+pnpm add @prism-ing/wallet
+```
+
+Optional peer dependencies (install only what you need):
+
+```bash
+pnpm add @zerodev/sdk    # On-chain session key enforcement
+pnpm add @sqds/multisig  # Solana social recovery
+pnpm add viem            # EVM utilities
+```
+
+## Quickstart
+
+```ts
+import { createProductionWallet } from '@prism-ing/wallet';
+
+const result = await createProductionWallet({
+  signer: { walletName: 'my-agent' },
+  oneBalanceApiKey: process.env.ONEBALANCE_API_KEY,
+});
+
+if (!result.ok) {
+  console.error(result.error.code);
+  process.exit(1);
+}
+
+const wallet = result.value;
+console.log('EVM address:', wallet.evmAddress);
+console.log('Solana address:', wallet.solanaAddress);
+
+const balance = await wallet.getBalance();
+console.log(`Balance: $${balance.totalUsd}`);
+```
+
+Same wallet name = same keys = same addresses, every time. Keys persist encrypted at `~/.ows/`.
+
+## Architecture
+
+Three systems compose to give you a persistent, cross-chain, recoverable wallet:
+
+```
+Signing Backends (platform-specific key management)
+  ├── iOS Secure Enclave: keys encrypted by hardware P-256 key, biometric-gated
+  ├── OWS (Node.js): secp256k1 + ed25519 from BIP-39, encrypted at ~/.ows/
+  └── Node Software: in-memory signing via @noble/curves (dev/testing)
+
+OneBalance (Account Abstraction + Cross-Chain)
+  ├── ERC-4337 counterfactual smart account from signer's public key
+  ├── Deterministic address: same signer = same smart account
+  ├── Resource Locks: instant cross-chain execution without source chain finality
+  └── Aggregated balance across all supported chains
+
+Smart Contract Wallet (the actual "wallet")
+  ├── Signer key authorizes operations, but is NOT the wallet itself
+  ├── Funds live in the smart contract, not controlled by the raw key
+  ├── Signer can be rotated without moving funds (recovery)
+  └── On-chain policy enforcement via ZeroDev permission validators
+```
+
+**Key insight:** The signer key is not the wallet. It authorizes operations on a smart contract. If compromised, guardians can rotate it out without moving funds. This separation is fundamental to every security property.
+
+## Private Key Management
+
+### Security Model by Platform
+
+| Property | Node.js (Agent) | iOS (Mobile) |
+|----------|-----------------|--------------|
+| Key storage | Encrypted at `~/.ows/` (AES-256-GCM, scrypt KDF) | Encrypted by Secure Enclave P-256 key, stored in iOS Keychain |
+| Auth | Passphrase or API key | Biometric (Face ID / Touch ID) |
+| Key isolation | In-process only, never serialized | Decrypted in-process only after biometric, never serialized |
+| EVM signing | Software secp256k1 | Software secp256k1, biometric-gated |
+| Solana signing | Software ed25519 | Software ed25519, biometric-gated |
+| Seed phrases | None exposed. OWS encrypts mnemonic internally. | None. Keys are non-exportable. |
+
+### Security Assumptions
+
+1. **Private keys never leave the device in plaintext.** On iOS, keys are encrypted by the Secure Enclave's hardware P-256 key and stored in the Keychain. On Node.js, keys are encrypted with scrypt + AES-256-GCM.
+
+2. **Signing requires authentication.** On iOS, every signing operation triggers Face ID / Touch ID via the `SecureEnclaveNativeBridge`. On Node.js, the OWS vault requires a passphrase or API key to decrypt.
+
+3. **No key material in `OWSKeyPair`.** The `OWSKeyPair` type contains only addresses and a platform identifier. On iOS, it stores a Keychain tag referencing the encrypted key, not the key itself.
+
+4. **The Secure Enclave does not support secp256k1 natively.** iOS uses the Secure Enclave's P-256 key to encrypt/decrypt secp256k1 and ed25519 private keys. Signing happens in-process after biometric-gated decryption, not inside the enclave chip.
+
+5. **OneBalance is a trusted co-signer.** Cross-chain execution relies on OneBalance for quote generation and settlement. The SDK mitigates this trust with [client-side quote verification](#quote-verification) but cannot independently route transactions.
+
+### Agent Mode
+
+```ts
+// First run: creates wallet, encrypts keys at ~/.ows/
+// Every subsequent run: loads same wallet, same addresses
+const result = await createProductionWallet({
+  signer: { walletName: 'trading-agent' },
+  oneBalanceApiKey: process.env.ONEBALANCE_API_KEY,
+});
+```
+
+With passphrase protection:
+```ts
+const result = await createProductionWallet({
+  signer: {
+    walletName: 'treasury',
+    passphrase: process.env.WALLET_PASSPHRASE,
+  },
+  oneBalanceApiKey: process.env.ONEBALANCE_API_KEY,
+});
+```
+
+With OWS agent API key (policy-gated signing):
+```ts
+const result = await createProductionWallet({
+  signer: {
+    walletName: 'treasury',
+    apiKey: 'ows_key_a1b2c3d4...',
+  },
+  oneBalanceApiKey: process.env.ONEBALANCE_API_KEY,
+});
+```
+
+### iOS Mobile App
+
+```ts
+import { createProductionWallet } from '@prism-ing/wallet';
+import { SecureEnclaveModule } from './native/SecureEnclaveModule';
+
+const result = await createProductionWallet(
+  {
+    signer: { walletName: 'user' },
+    oneBalanceApiKey: config.oneBalanceApiKey,
+  },
+  {
+    nativeBridge: SecureEnclaveModule,          // React Native native module
+    biometricPrompt: 'Authorize this trade',    // Face ID / Touch ID text
+    recoveryBackends: { evm: evmBackend, solana: solanaBackend },
+  },
+);
+```
+
+On iOS, `createProductionWallet` detects the platform and auto-selects the Secure Enclave backend when `nativeBridge` is provided. The rest of the stack (OneBalance, cross-chain, recovery) works identically.
+
+### Custom Signer (bring your own keys)
+
+Routers and the wallet factory accept any `PrismSigner`. No dependency on `@prism-ing/wallet` for signing:
+
+```ts
+import type { PrismSigner } from '@prism-ing/wallet';
+
+const mySigner: PrismSigner = {
+  evmAddress: myAddress,
+  solanaAddress: mySolanaAddress,
+  signMessage: (msg) => mySigningLib.sign(msg),
+  signTypedData: (payload) => mySigningLib.signTypedData(payload),
+  signTransaction: (tx) => mySigningLib.signSolana(tx),
+};
+```
+
+## Session Keys
+
+Session keys are ephemeral, policy-scoped signers for agents and automated processes. They wrap the root `PrismSigner` and enforce constraints on every signing operation. If a session key is compromised, the blast radius is bounded by its policy.
+
+### How Session Keys Improve Security
+
+Without session keys, an agent holds the root signer and can sign anything: any amount, any token, any chain, any recipient. A compromised agent means total loss.
+
+With session keys, the agent holds a scoped signer that the SDK restricts before every signing operation:
+
+```
+Root Signer (full authority)
+  └── Session Key (policy-restricted)
+        ├── Can only trade USDC
+        ├── Max $1,000 per operation
+        ├── Max $5,000 total
+        ├── Only on Base and Arbitrum
+        ├── Only to whitelisted addresses
+        └── Expires in 1 hour
+```
+
+**Two enforcement layers:**
+
+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.
+
+2. **On-chain (optional, via ZeroDev):** When a `SessionKeyBackend` is provided, policies are also registered as ZeroDev Kernel v3.1 permission validators. Even if a compromised client bypasses the JS check, the UserOp reverts on-chain.
+
+### Basic Usage
+
+```ts
+import { createSessionKeyManager, validateSessionOperation } from '@prism-ing/wallet';
+
+const manager = createSessionKeyManager(wallet.signer);
+
+const session = manager.createSessionKey({
+  expiresAt: Math.floor(Date.now() / 1000) + 3600,  // 1 hour
+  allowedAssets: ['ob:usdc'],                         // USDC only
+  maxAmountPerOp: '1000000000',                       // 1,000 USDC max per swap
+  maxTotalAmount: '5000000000',                       // 5,000 USDC cumulative cap
+  allowedChains: [8453, 42161],                       // Base + Arbitrum only
+  allowedRecipients: ['0xabc...'],                    // Restrict destinations
+});
+
+// Pre-validate before execution (optional, fail-fast)
+const violation = validateSessionOperation(session, {
+  asset: 'ob:usdc',
+  amount: '500000000',
+  chainId: 8453,
+});
+if (violation !== undefined) {
+  console.error('Policy violation:', violation.code);
+  return;
+}
+
+// Use the session signer — policy enforced on every sign call
+const result = await executeCrossChain(
+  oneBalanceClient,
+  session.signer,   // <-- scoped signer, not root
+  { fromAsset: 'ob:usdc', toAsset: 'ob:eth', amount: '500000000' },
+  accounts,
+);
+
+// Revoke when the task is complete
+manager.revokeSessionKey(session.sessionId);
+```
+
+### Policy Dimensions
+
+| Dimension | Field | Effect |
+|-----------|-------|--------|
+| Time | `expiresAt` | Session expires after this Unix timestamp (required) |
+| Assets | `allowedAssets` | Only these OneBalance asset IDs can be operated on |
+| Per-op amount | `maxAmountPerOp` | Single operation cannot exceed this (smallest unit) |
+| Cumulative | `maxTotalAmount` | Total spend across all operations is capped |
+| Recipients | `allowedRecipients` | Only these addresses can be destinations |
+| Chains | `allowedChains` | Only these chain IDs are permitted |
+
+### On-Chain Enforcement (ZeroDev)
+
+For production agent deployments, client-side enforcement alone is not sufficient. A compromised process could bypass the JS policy checks. On-chain enforcement ensures the smart contract itself rejects unauthorized operations.
+
+```ts
+import { createZeroDevSessionBackend, createSessionKeyManager } from '@prism-ing/wallet';
+
+// Create the ZeroDev backend with your own SDK integration
+const sessionBackend = createZeroDevSessionBackend({
+  registerOnChain: async (sessionAddress, policies) => {
+    // policies is ZeroDevPolicy[] — mapped from SessionKeyPolicy
+    // Each policy has a discriminated `type` field:
+    //   'timestamp' → validAfter/validUntil
+    //   'call'      → contract/function/argument restrictions
+    //   'gas'       → max gas spend per session
+    //   'rate_limit' → operations per interval
+    //
+    // Use @zerodev/permissions to register:
+    //   1. toECDSASigner({ signer: sessionPrivateKey })
+    //   2. toTimestampPolicy/toCallPolicy/toGasPolicy/toRateLimitPolicy
+    //   3. toPermissionValidator(client, { signer, policies, entryPoint, kernelVersion })
+    //   4. toInitConfig(validator) for pre-installed permissions
+    return txHash;
+  },
+  revokeOnChain: async (sessionAddress) => {
+    // Remove the permission validator from the Kernel account
+    return txHash;
+  },
+  defaultGasBudgetWei: 100_000_000_000_000_000n,  // 0.1 ETH
+  callPolicyVersion: '0.0.4',  // Alchemy bundler compatible
+});
+
+// Session keys are now enforced client-side AND on-chain
+const manager = createSessionKeyManager(wallet.signer, sessionBackend);
+```
+
+**Policy mapping details:**
+
+The SDK automatically maps `SessionKeyPolicy` to ZeroDev on-chain policies:
+
+- `expiresAt` maps to a **timestamp policy** with `validUntil`
+- `allowedAssets` maps to a **call policy** restricting ERC-20 `transfer()` calls to known token contracts
+- `maxAmountPerOp` maps to a `LESS_THAN_OR_EQUAL` parameter condition on the transfer amount
+- `allowedRecipients` maps to `ONE_OF` parameter conditions on the transfer recipient
+- A **gas policy** (default 0.1 ETH) is always included to prevent gas drain
+- A **rate limit policy** is included when amount caps are set (100 ops/hour)
+
+Use `mapSessionPolicyToZeroDev(policy)` directly if you need to inspect or customize the mapped policies before registration.
+
+## Social Recovery
+
+Recovery rotates the smart contract's authorized signer without moving funds. The original key becomes useless. This works because the signer is not the wallet — it's an authorization key for a smart contract that holds the funds.
+
+### How Recovery Works
+
+```
+Device Lost / Key Compromised
+  ↓
+Generate new keys (new device, new OWS wallet, or new Secure Enclave key)
+  ↓
+Guardian authorizes rotation (passkey, second device, or trusted contact)
+  ↓
+EVM: ZeroDev removeValidator(old) + addValidator(new) on Kernel contract
+Solana: Squads AddMember(new) + RemoveMember(old) on multisig
+  ↓
+Same wallet address, same funds, new authorized signer
+```
+
+### Guardian Types
+
+| Guardian | How It Works | Best For |
+|----------|-------------|----------|
+| Passkey (iCloud Keychain) | WebAuthn credential signs recovery challenge | Single-device users |
+| Device | Second device's signing key authorizes rotation | Multi-device users |
+| Contact | Trusted contact's EVM address authorizes rotation | High-security setups |
+
+### Setting Up Recovery
+
+```ts
+const recovery = wallet.recover();
+
+// Register a passkey guardian (iCloud Keychain)
+const passkey = await recovery.setupPasskey();
+
+// Add a second device as guardian
+await recovery.addDeviceGuardian(deviceEvmAddress, deviceSolanaAddress);
+
+// Add a trusted contact
+await recovery.addContactGuardian(contactEvmAddress);
+```
+
+### Performing Recovery
+
+```ts
+// On a new device, with new keys:
+const newWallet = await createProductionWallet({
+  signer: { walletName: 'recovered-wallet' },
+  oneBalanceApiKey: process.env.ONEBALANCE_API_KEY,
+});
+
+const recovery = oldWalletRecoveryManager;
+const recoveryTx = await recovery.initiateRecovery(newWallet.value.signer);
+// Smart contract's authorized signer now points to newWallet.signer
+```
+
+### EVM Recovery (ZeroDev)
+
+The EVM recovery backend rotates the Kernel v3.1 smart account's authorized validator:
+
+```ts
+import type { EvmRecoveryBackend } from '@prism-ing/wallet';
+
+const evmBackend: EvmRecoveryBackend = {
+  async addGuardian(guardianAddress) {
+    // Register guardian on ZeroDev social recovery module
+  },
+  async rotateValidator(oldSigner, newSigner, guardianProof) {
+    // ZeroDev: removeValidator(old) + addValidator(new)
+    return txHash;
+  },
+};
+```
+
+### Solana Recovery (Squads V4)
+
+The Squads backend manages multisig membership for Solana key recovery:
+
+```ts
+import { createSquadsRecoveryBackend } from '@prism-ing/wallet';
+
+const solanaBackend = createSquadsRecoveryBackend({
+  bridge: {
+    async executeConfigTransaction(actions) {
+      // Wraps @sqds/multisig: create config tx → propose → approve → execute
+      // Actions: AddMember, RemoveMember, ChangeThreshold
+      return txSignature;
+    },
+    async getThreshold() { return currentThreshold; },
+    async getMemberCount() { return currentMemberCount; },
+  },
+  autoIncrementThreshold: true,  // Adding a guardian increases threshold
+});
+```
+
+**Key design decisions:**
+
+- `configAuthority: null` — all changes go through the proposal flow (no admin override)
+- `AddMember` executes before `RemoveMember` in the same config transaction, preventing a zero-member state
+- Threshold auto-increments when adding guardians, requiring more consensus for future rotations
+- Guardians get Voter-only permissions; the wallet signer gets full permissions
+
+### Recovery Security
+
+Recovery challenges are dynamic and bound to the specific rotation:
+
+```
+challenge = keccak256(
+  "prism-recovery-v1"    // Domain tag (prevents cross-protocol replay)
+  || currentSigner       // The signer being rotated away
+  || newSigner           // The signer being rotated to
+  || timeWindow          // 5-minute quantized timestamp
+)
+```
+
+This means:
+- A proof for A to B cannot be replayed for A to C (different `newSigner`)
+- A captured proof expires within 5 minutes (time-bounded)
+- A proof for wallet X cannot be used on wallet Y (different `currentSigner`)
+
+Use `buildRecoveryChallenge(currentSigner, newSigner)` for custom recovery flows.
+
+## Quote Verification
+
+`executeCrossChain` automatically verifies OneBalance quotes before signing. This prevents blind-signing attacks where a compromised or man-in-the-middle API could present malicious EIP-712 payloads.
+
+**Checks performed automatically:**
+
+1. Quote has not expired
+2. OneBalance tamper-proof signature is present
+3. Origin asset matches the requested `fromAsset`
+4. Origin amount is within 1% of the requested amount (configurable)
+5. Destination asset matches the requested `toAsset`
+6. EVM operation `userOp.sender` matches `accountAddress` (when provided)
+
+```ts
+const result = await executeCrossChain(client, signer, {
+  fromAsset: 'ob:usdc',
+  toAsset: 'ob:eth',
+  amount: '1000000',
+  accountAddress: wallet.evmAddress,  // enables sender verification
+});
+
+if (!result.ok && result.error.code === 'QUOTE_VERIFICATION_FAILED') {
+  console.error('Quote integrity failed:', result.error.reason);
+}
+```
+
+**Manual verification** (for custom flows):
+
+```ts
+import { verifyQuoteIntegrity, verifyEvmOperation } from '@prism-ing/wallet';
+
+const error = verifyQuoteIntegrity(quote, {
+  fromAsset: 'ob:usdc',
+  toAsset: 'ob:eth',
+  amount: '1000000',
+  accountAddress: '0x1234...',
+  maxOriginSlippageFraction: 0.005,  // 0.5% tolerance (default 1%)
+});
+```
+
+## Cross-Chain Execution
+
+```ts
+import { executeCrossChain } from '@prism-ing/wallet';
+
+const result = await executeCrossChain(
+  oneBalanceClient,
+  wallet.signer,
+  {
+    fromAsset: 'ob:usdc',
+    toAsset: 'ob:eth',
+    amount: '1000000',
+    slippageTolerance: 50,
+    accountAddress: wallet.evmAddress,
+  },
+  accounts,
+);
+
+if (result.ok) {
+  console.log('Quote ID:', result.value.quoteId);
+
+  // Poll execution status
+  const status = await wallet.getTransactionStatus(result.value.quoteId);
+  console.log('Status:', status.status);  // 'submitted' | 'confirmed' | 'failed'
+}
+```
+
+## API Reference
+
+### `createProductionWallet(config, options?)`
+
+Creates a wallet with platform-appropriate signing + OneBalance. Returns `Result<WalletAccount, WalletError>`.
+
+```ts
+interface WalletConfig {
+  signer: SignerConfig;
+  oneBalanceApiKey: string;
+  accountType?: 'kernel-v3.1-ecdsa';
+  chains?: number[];
+  recovery?: RecoveryConfig;
+}
+
+interface ProductionWalletOptions {
+  nativeBridge?: SecureEnclaveNativeBridge;  // iOS Secure Enclave
+  keyTag?: string;                           // iOS Keychain tag
+  biometricPrompt?: string;                  // Face ID / Touch ID text
+  recoveryBackends?: RecoveryBackends;       // Guardian backends
+}
+```
+
+### `WalletAccount`
+
+```ts
+interface WalletAccount {
+  signer: PrismSigner;
+  evmAddress: Address;
+  solanaAddress: string;
+  getBalance(): Promise<UnifiedBalance>;
+  deposit(params: DepositParams): Promise<TxResult>;
+  getTransactionStatus(quoteId: string): Promise<TxResult>;
+  recover(): RecoveryManager;
+}
+```
+
+### `PrismSigner`
+
+The core signing interface. Routers depend on this, not on `@prism-ing/wallet`.
+
+```ts
+interface PrismSigner {
+  signMessage(message: Hex): Promise<Hex>;
+  signTypedData(payload: TypedDataPayload): Promise<Hex>;
+  signTransaction<T>(tx: T): Promise<T>;
+  readonly evmAddress: Address;
+  readonly solanaAddress: string;
+}
+```
+
+### Error Handling
+
+All operations return `Result<T, WalletError>` instead of throwing:
+
+```ts
+const result = await createProductionWallet(config);
+
+if (!result.ok) {
+  if (isRetryableError(result.error)) {
+    // ONEBALANCE_TIMEOUT, ONEBALANCE_API_ERROR — safe to retry
+  }
+  if (isUserFacingError(result.error)) {
+    // SIGNING_REJECTED, INSUFFICIENT_BALANCE — show to user
+  }
+  return;
+}
+```
+
+| 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 |
+
+## Defense-in-Depth Layers
+
+```
+Layer 1: Key Storage
+  iOS: Secure Enclave encryption + biometric gate
+  Node: OWS scrypt + AES-256-GCM encrypted vault
+
+Layer 2: Session Key Policies
+  Client-side: JS enforcement before every signature
+  On-chain: ZeroDev permission validators (UserOp reverts if violated)
+
+Layer 3: Quote Verification
+  6-point client-side integrity check before signing any OneBalance quote
+
+Layer 4: Recovery Challenges
+  Dynamic keccak256 challenges bound to signer pair + 5-minute time window
+
+Layer 5: Smart Contract Validation
+  ERC-4337 smart account validates all operations on-chain
+  ZeroDev Kernel v3.1 enforces session key policies at contract level
+
+Layer 6: Network Resilience
+  Exponential backoff with jitter on OneBalance API (3 retries)
+  Only retries on timeouts, network errors, and 5xx responses
+```
+
+## Documentation
+
+- [SPEC.md](./SPEC.md) — Design decisions, security model, error codes
+- [CHANGELOG.md](./CHANGELOG.md) — Version history
+
+## License
+
+MIT