Merge pull request #55 from tetherto/feat/local-transaction-policies-phase-1

feat: add Phase 1 local transaction policy engine

Author: jonathunne

.gitignore

@@ -1,2 +1,4 @@
 node_modules
 coverage
+.scripts
+.agents

AGENTS.md

@@ -44,6 +44,20 @@ Source code must be strictly typed using JSDoc comments to support the `build:ty
 
 ## Repository Specifics
 - **Domain:** Core Orchestrator.
-- **Role:** Central entry point for the WDK. Manages lifecycle of multiple wallet instances and protocols.
-- **Key Pattern:** Dependency Injection (registerWallet, registerProtocol).
-- **Architecture:** `WDK` class manages a collection of `WalletManager` instances.
+- **Role:** Central entry point for the WDK. Manages lifecycle of multiple wallet instances, protocols, and transaction policies.
+- **Key Pattern:** Dependency Injection (registerWallet, registerProtocol, registerPolicy).
+- **Architecture:** `WDK` class manages a collection of `WalletManager` instances and a `PolicyEngine` that intercepts write-facing operations on every account returned from `getAccount` / `getAccountByPath`.
+
+## Policy Engine
+- Source lives under `src/policy/`. Public surface is the `PolicyViolationError` and `PolicyConfigurationError` classes plus the `Policy*` / `SimulationResult` typedefs re-exported from `index.js`. Everything else under `src/policy/` is internal.
+- The engine wraps account write methods and protocol getters at `getAccount` time. When any policy applies to an account ("governed"), the proxy wraps **every** method in `OPERATIONS` that exists on the underlying account — not just the ones referenced by registered rules. Combined with the default-deny evaluator (below) this closes sibling-method bypasses (e.g. a "cap transfer" policy cannot be sidestepped by `sendTransaction({ to: token, data: ERC-20-transfer-calldata })`, `approve` to an attacker, off-chain Permit via `signTypedData`, or ERC-7702 `delegate`).
+- **Default-deny on governed accounts.** `policy-evaluator.evaluate()` returns BLOCK with `reason: 'no-applicable-rule'` whenever an operation reaches it and no rule addresses that operation. To opt into permissive semantics on a specific account, register a wildcard ALLOW baseline (`operation: '*', action: 'ALLOW'`) and layer specific DENYs on top. Accounts with no registered policies are not governed and skip the proxy entirely (zero cost).
+- **Operation name = canonical IWalletAccount method name.** The engine wraps `account[op]` by string lookup, so every entry in `OPERATIONS` (`src/policy/constants.js`) must match the exact method name on `@tetherto/wdk-wallet`'s base `IWalletAccount` or a registered protocol class. A divergence silently no-ops the policy (registers fine, never fires) — which is worse than a hard error. When adding a new wallet method that emits a signature or moves value (e.g., `signTransaction`, `sign`), add it to `OPERATIONS` and the `PolicyOperation` typedef. Conversely, do not add aspirational entries that no wallet implements; the schema accepts them, but they produce silently-broken policies.
+- Two scopes only: `project` (with optional wallet restriction declared via the policy's `wallet` field) and `account` (with required `wallet` field and a per-account `accounts` list of paths and/or integer indexes). The `wallet` value is the same string passed to `registerWallet` — an opaque consumer-chosen key, not a blockchain identifier. `wallet` accepts a single string or a non-empty array of strings; omitting it on a project-scope policy applies it across every registered wallet. DENY wins across scopes; account-scope `ALLOW` rules can short-circuit project-scope DENYs via `override_broader_scope: true`.
+- Index-form `accounts` entries match the index passed to `wdk.getAccount(wallet, index)`. They do not match accounts retrieved via `getAccountByPath` because the wallet manager has no synchronous path → index resolver. Path-form entries match either retrieval style.
+- Nested-call escape works via a `Proxy` (see `src/policy/policy-account-proxy.js`), not an async-context marker. The engine returns a Proxy that exposes enforced versions of write methods; the proxy's `get` trap binds non-enforced methods to the underlying account, so internal `this.method()` calls and protocol code that holds a direct reference to the account naturally bypass enforcement. The policy engine itself does not mutate the account (the WDK's `_registerProtocols` step does install `registerProtocol` / `getXProtocol` helpers before the proxy is built — separate, pre-existing concern). The same code path runs on every JavaScript runtime that supports `Proxy` — no `AsyncLocalStorage`, no runtime detection, no Bare-specific fallback.
+- Enforcement applies to the **surface of the proxy** only. Underscore-prefixed fields (e.g. `protocol._account`) reach the raw account and bypass enforcement by design — they are private by convention and not part of the supported surface. The same is true for protocol methods that internally call account operations via their stored `this._account` (e.g. `bridge.bridge(...)` calling `this._account.sendTransaction(...)`); this is the documented nested-call escape.
+- `proxy.registerProtocol(...)` is special: the underlying helper returns the raw account, so the `get` trap rewrites the return value to be the proxy itself. Without this rewrite, `proxy.registerProtocol(...).sendTransaction(...)` would skip enforcement.
+- Each condition is raced against `conditionTimeoutMs` (default 30s, settable via `RegisterPolicyOptions`). A condition that throws or times out is fail-closed for DENY rules (treated as matched → block) and fail-open-as-no-match for ALLOW rules.
+- Conditions are user-supplied functions in Phase 1. The engine accepts `state` and `onSuccess` rule fields for Phase 2 (engine-managed state + post-execution hooks) but ignores them at runtime; `state` is deep-cloned at registration so callers can't mutate engine state post-registration.
+- Tests live in `tests/wdk-policy.test.js` and exercise the engine exclusively through the public WDK API.

README.md

@@ -57,9 +57,74 @@ wdk.dispose()
 - **Multi-Chain Operations**: Coordinate balances, fee lookups, and transaction flows across registered chains
 - **Protocol Registration Support**: Attach swap, bridge, lending, fiat, and swidge protocols to registered blockchains
 - **Middleware Hooks**: Intercept account derivation with custom middleware
+- **Transaction Policies**: Local policy engine that intercepts write-facing operations and enforces user-defined ALLOW/DENY rules at project (global or wallet-bound) and account scopes — with simulation, nested-call handling, and structured `PolicyViolationError`s
 - **Seed Utilities**: Generate and validate BIP-39 seed phrases
 - **Selective Disposal**: Dispose specific registered wallets or clear the full WDK instance
 
+## Transaction Policies
+
+Register policies on a `WDK` instance to gate write-facing operations on every wallet account. Each registered rule can `ALLOW` or `DENY` an attempted operation based on a condition function; matching `DENY`s throw a `PolicyViolationError` before the underlying method runs.
+
+```javascript
+import WDK, { PolicyViolationError } from '@tetherto/wdk'
+import WalletManagerEvm from '@tetherto/wdk-wallet-evm'
+
+const wdk = new WDK(seedPhrase)
+  .registerWallet('ethereum', WalletManagerEvm, { provider: '...' })
+  .registerPolicy({
+    id: 'value-cap',
+    name: 'Cap value at 1 ETH',
+    scope: 'project',
+    rules: [{
+      name: 'allow-under-1-eth',
+      operation: 'sendTransaction',
+      action: 'ALLOW',
+      conditions: [({ params }) => BigInt(params.value) <= 10n ** 18n]
+    }]
+  })
+
+const account = await wdk.getAccount('ethereum', 0)
+
+try {
+  await account.sendTransaction({ to: '0x…', value: 5n * 10n ** 18n })
+} catch (err) {
+  if (err instanceof PolicyViolationError) {
+    console.log(err.policyId, err.ruleName, err.reason)
+  }
+}
+
+// Run the same evaluation without executing the transaction.
+const result = await account.simulate.sendTransaction({ to: '0x…', value: 1n })
+// → { decision: 'ALLOW' | 'DENY', policy_id, matched_rule, reason, trace }
+```
+
+Policies have two scopes — `project` and `account`. A project-scope policy applies globally by default, or only to the wallets named in its `wallet` field (`wallet: 'ethereum'` or `wallet: ['ethereum', 'ton']`). The `wallet` value is the same string passed to `registerWallet`. It might be a chain name like `"ethereum"`, but it could equally be `"treasury-cold"` or any label the consumer chose; the engine treats it as an opaque key. An account-scope policy must declare a `wallet` and targets specific accounts within it, identified by either derivation path (`accounts: ["0'/0/0"]`) or integer index (`accounts: [0, 1]`) — index entries match accounts retrieved via `wdk.getAccount(wallet, index)`; path entries match either retrieval style. Evaluation is narrowest-first with `DENY` winning across scopes. Account-scope `ALLOW` rules can opt into `override_broader_scope: true` to short-circuit broader policies for explicit exceptions (e.g., treasury accounts). Conditions can be sync or async and may carry user-owned state via closures. Templates (`@tetherto/wdk-policy-templates`) and a portal UI for editing policies are coming in later phases.
+
+### Default-deny semantics
+
+The engine is **default-deny on governed accounts**. As soon as any policy applies to an account, the engine wraps every method in `OPERATIONS` (the set of write-facing and signing primitives — `sendTransaction`, `signTransaction`, `transfer`, `approve`, `sign`, `signTypedData`, `signAuthorization`, `delegate`, `revokeDelegation`, and protocol methods like `swap`, `bridge`, `swidge`, etc.) on that account. Any call to a wrapped method whose operation is not addressed by an `ALLOW` rule throws `PolicyViolationError` with `reason: 'no-applicable-rule'`.
+
+This is intentional: a "cap transfer at $100" policy must not be sidesteppable by `sendTransaction({ to: token, data: <ERC-20 transfer calldata> })`, `approve(spender, MAX)`, an off-chain `signTypedData` Permit, or an ERC-7702 `delegate` to an attacker contract. The engine closes those bypasses by treating any unaddressed money-movement op on a governed account as DENY.
+
+If you want permissive semantics on a specific account (allow anything that isn't explicitly denied), register a wildcard ALLOW rule as a baseline and layer specific DENYs on top:
+
+```javascript
+wdk.registerPolicy({
+  id: 'permissive-baseline',
+  scope: 'project',
+  rules: [
+    { name: 'allow-all', operation: '*', action: 'ALLOW', conditions: [] },
+    { name: 'block-bad', operation: 'sendTransaction', action: 'DENY', conditions: [({ params }) => isSanctioned(params.to)] }
+  ]
+})
+```
+
+Accounts that have **no** registered policies are not governed — the proxy is not applied, and method calls go straight to the underlying account at zero cost.
+
+The engine wraps accounts through an ES `Proxy` so internal SDK code that uses `this.method()` naturally bypasses enforcement — nested-call escape (e.g. `bridge` internally calling `sendTransaction`) works without any async-context tracking. The same code path runs on every JavaScript runtime that supports `Proxy`, including Bare.
+
+Policy enforcement applies to the **surface of the proxy** returned by `getAccount` / `getAccountByPath`. Reaching for underscore-prefixed fields (e.g. `protocol._account`) bypasses enforcement by design — treat them as private. The same applies to account-level operations invoked from inside a protocol's own methods (e.g. `bridge.bridge(...)` internally calling `this._account.sendTransaction(...)`), which is the documented nested-call escape; it lets protocols use the account they were constructed with without re-entering the engine on every internal step.
+
 ## Compatibility
 
 - **WDK Wallet Modules** including EVM, Solana, TON, TRON, and Bitcoin integrations

index.js

@@ -15,9 +15,22 @@
 'use strict'
 
 /** @typedef {import('./src/wdk.js').IWalletAccount} IWalletAccount */
+/** @typedef {import('@tetherto/wdk-wallet').IWalletAccountReadOnly} IWalletAccountReadOnly */
 /** @typedef {import('./src/wdk.js').FeeRates} FeeRates */
 /** @typedef {import('./src/wdk.js').MiddlewareFunction} MiddlewareFunction */
 
 /** @typedef {import('./src/wallet-account-with-protocols.js').IWalletAccountWithProtocols} IWalletAccountWithProtocols */
 
+/** @typedef {import('./src/policy/index.js').Policy} Policy */
+/** @typedef {import('./src/policy/index.js').PolicyRule} PolicyRule */
+/** @typedef {import('./src/policy/index.js').PolicyCondition} PolicyCondition */
+/** @typedef {import('./src/policy/index.js').PolicyContext} PolicyContext */
+/** @typedef {import('./src/policy/index.js').PolicyAction} PolicyAction */
+/** @typedef {import('./src/policy/index.js').PolicyScope} PolicyScope */
+/** @typedef {import('./src/policy/index.js').PolicyOperation} PolicyOperation */
+/** @typedef {import('./src/policy/index.js').SimulationResult} SimulationResult */
+/** @typedef {import('./src/policy/index.js').SimulationTraceEntry} SimulationTraceEntry */
+/** @typedef {import('./src/policy/index.js').RegisterPolicyOptions} RegisterPolicyOptions */
+
 export { default } from './src/wdk.js'
+export { PolicyViolationError, PolicyConfigurationError } from './src/policy/index.js'

package-lock.json

@@ -24,7 +24,8 @@
   },
   "dependencies": {
     "@tetherto/wdk-wallet": "^1.0.0-beta.9",
-    "bare-node-runtime": "^1.4.0"
+    "bare-node-runtime": "^1.4.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "cross-env": "7.0.3",

package.json

@@ -0,0 +1,54 @@
+// Copyright 2024 Tether Operations Limited
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict'
+
+// Every entry must be the exact method name on `@tetherto/wdk-wallet`'s
+// IWalletAccount or an installed protocol class. The engine wraps methods by
+// looking them up on the account by name — a mismatch silently no-ops, which
+// is worse than a hard error. Audit upstream wallets before adding/removing.
+export const OPERATIONS = [
+  'sendTransaction',
+  'signTransaction',
+  'transfer',
+  'approve',
+  'sign',
+  'signTypedData',
+  'signAuthorization',
+  'delegate',
+  'revokeDelegation',
+  'swap',
+  'bridge',
+  'supply',
+  'withdraw',
+  'borrow',
+  'repay',
+  'buy',
+  'sell',
+  'swidge'
+]
+
+export const WILDCARD = '*'
+
+export const SCOPES = ['project', 'account']
+
+export const ACTIONS = ['ALLOW', 'DENY']
+
+export const PROTOCOL_METHODS = {
+  swap: ['swap'],
+  bridge: ['bridge'],
+  lending: ['supply', 'withdraw', 'borrow', 'repay'],
+  fiat: ['buy', 'sell'],
+  swidge: ['swidge']
+}

src/policy/constants.js

@@ -0,0 +1,37 @@
+// Copyright 2024 Tether Operations Limited
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict'
+
+/**
+ * Public surface of the policy engine sub-module.
+ *
+ * Re-exports the runtime classes (errors) and the public typedefs that
+ * consumers need to type their policies, conditions, and simulation results.
+ * Internal modules (registry, evaluator, validators, wrapper, context,
+ * constants) are not re-exported here — they're implementation details.
+ */
+
+/** @typedef {import('./policy-engine.js').Policy} Policy */
+/** @typedef {import('./policy-engine.js').PolicyRule} PolicyRule */
+/** @typedef {import('./policy-engine.js').PolicyCondition} PolicyCondition */
+/** @typedef {import('./policy-engine.js').PolicyContext} PolicyContext */
+/** @typedef {import('./policy-engine.js').PolicyAction} PolicyAction */
+/** @typedef {import('./policy-engine.js').PolicyScope} PolicyScope */
+/** @typedef {import('./policy-engine.js').PolicyOperation} PolicyOperation */
+/** @typedef {import('./policy-engine.js').SimulationResult} SimulationResult */
+/** @typedef {import('./policy-engine.js').SimulationTraceEntry} SimulationTraceEntry */
+/** @typedef {import('./policy-engine.js').RegisterPolicyOptions} RegisterPolicyOptions */
+
+export { default as PolicyViolationError, PolicyConfigurationError } from './policy-error.js'