feat: add Phase 1 local transaction policy engine

[AlonzoRicardo]

Summary

Phase 1 of the Local Transaction Policies engine, per the PRD. Policies are plain JS objects registered against the WDK instance; the engine wraps every write-facing operation on a wallet account (and on protocol getters) so DENY rules throw PolicyViolationError before the underlying method runs and ALLOW rules pass through untouched.

What's in the engine

• Three-group evaluation (account → wallet → project) with DENY-wins and account-level override_broader_scope to grant explicit exceptions for treasury wallets, etc.
• Conditions are user-supplied functions, sync or async, with full access to a frozen context { operation, chain, account: <readOnly>, params, args }. Stateful policies are supported in Phase 1 via closures over user-owned state.
• Per-condition timeout (default 30s, configurable via RegisterPolicyOptions.conditionTimeoutMs) so a stuck async condition cannot hang the wallet pipeline. On timeout the condition is treated the same as a throw.
• Fail-closed DENY: a throwing or timing-out DENY condition is treated as matched, so an attacker cannot bypass a DENY by causing its backing service to fail. ALLOW rules retain fail-open-as-no-match.
• account.simulate.<method>(...) mirror runs evaluation without execution and returns { decision, policy_id, matched_rule, reason, trace }.
• Nested-call escape via AsyncLocalStorage (per-async-chain), so concurrent calls evaluate independently while nested calls within one chain skip re-evaluation. node:async_hooks is loaded lazily so importing @tetherto/wdk/bare does not fail at link time on runtimes that don't expose AsyncLocalStorage; the error only surfaces if a policy is actually registered.
• Registration validation throws PolicyConfigurationError synchronously on unknown ops, missing fields, contradictory configuration, and unknown chain bindings — no soft-mode.
• 17 supported operations + wildcard: sendTransaction, transfer, approve, signMessage, signHash, signTypedData, signAuthorization, delegate, revokeDelegation, swap, bridge, supply, withdraw, borrow, repay, buy, sell, *.

Public API additions

In index.js:

• PolicyViolationError, PolicyConfigurationError (classes).
• Typedefs: Policy, PolicyRule, PolicyCondition, PolicyContext, PolicyAction, PolicyScope, PolicyOperation, SimulationResult, SimulationTraceEntry, RegisterPolicyOptions.
• Re-export of IWalletAccountReadOnly from @tetherto/wdk-wallet so condition functions can be typed without a direct parent dep.

In WDK:

• New chainable method registerPolicy(chain?, policies, options?) (overloaded — chain string/array first, or policies first).
• New private hook _applyPolicies slotted into getAccount and getAccountByPath between protocol registration and the return.
• dispose([chains]) and dispose() clear policy bindings per-chain or globally.

Phase 2 / 3 forward-compat

• state and onSuccess fields on PolicyRule and RegisterPolicyOptions are accepted at registration and ignored at runtime — reserved for Phase 2 (engine-managed state + post-execution hooks). state is deep-cloned at registration so callers cannot mutate engine state post-registration.
• Conditions are functions in Phase 1; widening the validator + evaluator to also accept Phase 3 DSL objects is purely additive (no breaking change for existing function-form policies).
• Phase 4 portal is external tooling that produces/consumes the same Policy shape — no SDK changes needed there.

A dedicated forward-compat audit confirmed no Phase 1 design choice forces a breaking change in any later phase.

Test plan

• npm test — 95/95 passing (38 existing + 57 new in tests/wdk-manager-policy.test.js)
• npm run lint — clean (Standard style)
• npm run build:types — clean type generation
• All new tests go through the public WDK API only (no internal-module imports per WDK testing standards)
• End-to-end smoke pass through stub wallets: project DENY blocks; account override beats project DENY; simulate doesn't execute; concurrent calls evaluate independently; nested calls escape correctly; protocol getters wrap write methods only; multi-chain registration; dispose semantics; condition timeout fires; throwing DENY fails closed
• All assertions use concrete values (no toBeInstanceOf/type checks); error catches unpack name, policyId, ruleName, reason, message; simulate results assert decision, policy_id, matched_rule, reason, trace

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1213565140531088

[claudiovb]

Policy Engine Review — Phase 1

Solid architecture. Three-group evaluation semantics, DENY-wins, AsyncLocalStorage concurrency isolation, TOCTOU protection, and simulate mirror are all correct. 87/87 tests pass, lint clean, types clean. A 20-scenario E2E dogfood suite against real WalletManager/WalletAccount/SwapProtocol/BridgeProtocol subclasses passes end-to-end.

Findings

ID	Severity	Title
C-1	Critical	bare-async-hooks missing AsyncLocalStorage it breaks WDK import on Bare
H-1	High	No timeout on async conditions a never-resolving Promise hangs forever
H-2	High	Shallow policy clone the rule.state shared by reference after registration
H-3	High	Throwing DENY condition bypassed when a matching ALLOW exists

All four are tested with reproduction gists in the inline comments.

Informational

• I-1: structuredClone fallback to raw value for non-cloneable args (policy-context.js:52) which is the only way to go I think, worth documenting though.
• I-2: No policy introspection API for listing registered policies or inspecting governed operations at runtime this would be really valuable for agentic tooling, worth considering for Phase 2.
• I-3: PR description says "80/80 passing (31 existing + 49 new)" the actual count is 87 (38 + 49).
• I-4: PR description says "Symbol-keyed flag" for nested-call escape but code uses AsyncLocalStorage since commit 7567876.

JSDoc, style, and types review to follow.

[claudiovb]

Policy bypass in the proxy's get trap leaks the raw account via registerProtocol

The account-level get trap intercepts enforcedMethods, enforcedGetters, and simulate, then falls through to Reflect.get + .bind(target) for everything else. That's correct for ordinary reads, but account.registerProtocol is special: pre-existing code in wdk-manager.js (_registerProtocols) installs it directly on the raw account and the closure returns that raw account reference. So proxy.registerProtocol(...) hands the caller back the raw account, and every subsequent write on it skips policy evaluation.

The chained form is the dangerous one: account.registerProtocol(...).getXProtocol(...).x(...) is the protocol-attachment pattern this PR's own AGENTS.md and README suggest.

Reproduction

Save as repro.mjs at repo root, run with node repro.mjs:

import WDK from './index.js'
import WalletManager from '@tetherto/wdk-wallet'
import { BridgeProtocol } from '@tetherto/wdk-wallet/protocols'

class M extends WalletManager {
  async getAccount () {
    return {
      path: "0'/0/0",
      keyPair: { publicKey: new Uint8Array(32), privateKey: new Uint8Array(32) },
      sendTransaction: async () => ({ hash: '0xH' }),
      toReadOnlyAccount: async () => ({ getAddress: async () => '0x', getBalance: async () => 0n }),
      dispose () {}
    }
  }
}

const wdk = new WDK('abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about')
wdk.registerWallet('eth', M)
wdk.registerPolicy({
  id: 'deny', name: 'deny', scope: 'project',
  rules: [{ name: 'r', operation: 'sendTransaction', action: 'DENY', conditions: [] }]
})

const proxy = await wdk.getAccount('eth', 0)

class B extends BridgeProtocol {}
const returned = proxy.registerProtocol('br', B, {})

console.log('returned === proxy?', returned === proxy)
await proxy.sendTransaction({}).then(() => console.log('via proxy:    NO THROW'))
  .catch(e => console.log('via proxy:   ', e.constructor.name))
await returned.sendTransaction({}).then(() => console.log('via returned: NO THROW the policy is bypassed'))
  .catch(e => console.log('via returned:', e.constructor.name))

Output:

returned === proxy? false
via proxy:    PolicyViolationError
via returned: NO THROW the policy is bypassed

returned === proxy -> false is the structural bypass, the caller is no longer holding the policy-enforced proxy. The NO THROW line is the consequence: the rule blocks sendTransaction through the proxy but not through the leaked reference.

Suggested fix (lands in this get trap)

let proxyHandle
const handler = {
  get (target, prop) {
    if (enforcedMethods.has(prop)) return enforcedMethods.get(prop)
    if (enforcedGetters.has(prop)) return enforcedGetters.get(prop)
    if (prop === 'simulate') return simulate

    if (prop === 'registerProtocol' && typeof target.registerProtocol === 'function') {
      const fn = target.registerProtocol.bind(target)
      return (...args) => { fn(...args); return proxyHandle }
    }

    const value = Reflect.get(target, prop, target)
    if (typeof value === 'function') return value.bind(target)
    return value
  }
}
proxyHandle = new Proxy(account, handler)
return proxyHandle

I didn't test extensively the fix but in basic cases seems like a functional starting point.

Optional doc nit: the JSDoc above this trap (and AGENTS.md "Policy Engine") says "The original account is never mutated." That's true of the policy engine itself, but _registerProtocols does install registerProtocol / getXProtocol on the raw account before the proxy is built. Worth softening to "The policy engine itself does not mutate the account" once the bypass above is closed.

[claudiovb]

Membrane gap: the protocol._account leaks the raw account ( up for discussion)

wrapProtocolInProxy's get trap returns whatever Reflect.get produces for non-method properties. Every upstream protocol in @tetherto/wdk-wallet stores the raw account on this._account:

node_modules/@tetherto/wdk-wallet/src/protocols/swap-protocol.js:108:    this._account = account
node_modules/@tetherto/wdk-wallet/src/protocols/bridge-protocol.js:92:    this._account = account
node_modules/@tetherto/wdk-wallet/src/protocols/fiat-protocol.js:230:    this._account = account
node_modules/@tetherto/wdk-wallet/src/protocols/lending-protocol.js:182:    this._account = account

So proxy.getBridgeProtocol(label)._account reaches the underlying account through the policy-enforced proxy, and the engine never sees subsequent calls on it. The _ prefix says "private," but JavaScript doesn't enforce it.

Reproduction

Save as repro.mjs at repo root, run with node repro.mjs:

import WDK from './index.js'
import WalletManager from '@tetherto/wdk-wallet'
import { BridgeProtocol } from '@tetherto/wdk-wallet/protocols'

class M extends WalletManager {
  async getAccount () {
    return {
      path: "0'/0/0",
      keyPair: { publicKey: new Uint8Array(32), privateKey: new Uint8Array(32) },
      sendTransaction: async () => ({ hash: '0xH' }),
      toReadOnlyAccount: async () => ({ getAddress: async () => '0x', getBalance: async () => 0n }),
      dispose () {}
    }
  }
}
class B extends BridgeProtocol {}

const wdk = new WDK('abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about')
wdk.registerWallet('eth', M)
wdk.registerProtocol('eth', 'br', B, {})
wdk.registerPolicy({
  id: 'deny', name: 'deny', scope: 'project',
  rules: [{ name: 'r', operation: 'sendTransaction', action: 'DENY', conditions: [] }]
})

const proxy = await wdk.getAccount('eth', 0)
const bridge = proxy.getBridgeProtocol('br')

console.log('bridge._account === proxy?', bridge._account === proxy)
await proxy.sendTransaction({}).then(() => console.log('via proxy:           NO THROW'))
  .catch(e => console.log('via proxy:          ', e.constructor.name))
await bridge._account.sendTransaction({}).then(() => console.log('via bridge._account: NO THROW the policy is bypassed'))
  .catch(e => console.log('via bridge._account:', e.constructor.name))

Output:

bridge._account === proxy? false
via proxy:           PolicyViolationError
via bridge._account: NO THROW the policy is bypassed

Two options

1. Accept + document. Add a security note to AGENTS.md / README.md: "Policies enforce the surface of the proxy returned by getAccount / getAccountByPath. Reaching for protocol._account or other underscore-prefixed fields bypasses enforcement; 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."

2. Implement a membrane. A WeakMap<rawAccount, proxyAccount> consulted inside this get trap before returning:

   const value = Reflect.get(target, prop, target)
   if (value === ctx.account) return ctx.accountProxy
   if (typeof value === 'function') return value.bind(target)
   return value

   For the swap to fire on every protocol getter we also need to drop the if (opsToWrap.length === 0) continue guard at lines 91-94 so protocols are always wrapped, otherwise proxy.getBridgeProtocol(label) falls through and returns the raw protocol when no protocol-method policy exists. With both changes in place the base reproduction above flips to PolicyViolationError (verified locally, full suite still 133/133).

   Two caveats came up while testing this combination:

   • Cost. Every proxy.getXProtocol(label) call now allocates a Proxy, even when no policy targets that protocol's methods. Cheap individually but it's a hot path we weren't paying for before.
   • Same class of gap remains via nested calls. If a user defines a B extends BridgeProtocol whose bridge(opts) does this._account.sendTransaction({ ... }), calling bridge.bridge(opts) still bypasses the sendTransaction policy even with option 2 applied. Reason: inside bridge.bridge, this is bound to the raw protocol, this._account is the raw account, no proxy is in the call chain. This is the same nested escape the JSDoc on createPolicyEnforcedAccount already documents as intentional. Closing it would mean replacing this._account at protocol construction time with the proxy account, which crosses the @tetherto/wdk-wallet boundary. But as I understand it this bridge call should not be affected by sendTransaction policies so behaviour is correct, just flagging it now because if that assumption is wrong it will be an issue in the future.

Recommendation

I'd lean toward option 1 for Phase 1. Closing the _account direct read alone gives a false sense of safety if sendTransaction protection is expected to apply to bridge.bridge() calls too. And even if it isn't, _account isn't supposed to be used by consumers anyway (hence the _); JS doesn't enforce that convention, but a # private field upstream would, which is a wdk-wallet change and a separate discussion.

Accept + document for Phase 1, track the WeakMap membrane plus the nested-call story as Phase 2 if it proves necessary. The current design's biggest win is Bare/JSC portability; WeakMap works on Bare's runtime (I verified locally), I haven't tested it on JSC-backed Bare specifically.

[claudiovb]

Stale JSDoc reference to wallet scope

Wallet scope was removed in 7889bc3. This JSDoc still mentions it:

"…short-circuits both wallet- and project-scope evaluation."

Should read:

"…short-circuits project-scope evaluation."

[claudiovb]

Cosmetic: simulate[getterName] = () => { ... } takes zero args, but the real account.getXProtocol(label) takes one. JS silently swallows the label, so proxy.simulate.getBridgeProtocol('myLabel') and proxy.simulate.getBridgeProtocol() behave identically. Not a bug today since simulation is label-agnostic, but accepting the label arg for surface parity would avoid future confusion if Phase 2 ever makes simulation label-aware.

[Davi0kProgramsThings]

It's not really necessary to document internal properties. Also, avoid terms that make sense only in the scope of our company and team e.g., phase 1.

[Davi0kProgramsThings]

There's no real reason to freeze these objects since they are not accessible by external code.

[Davi0kProgramsThings]

You can replace all references to OPERATIONS_SET with OPERATIONS and get rid of this constant. We never really need the operation list to be a set.

[Davi0kProgramsThings]

Feel free to document internal components, but if you choose to do it you should do it properly i.e., document all internal components and not only some of them, use proper types and provide meaningful descriptions for all functions, arguments and return values.

[Davi0kProgramsThings]

Never use object, implement a proper type definition instead. Use brackets to mark optional arguments instead of * | undefined, and provide a meaningful description of the argument.

[Davi0kProgramsThings]

The error class description should not state when the error is thrown. Also, listing available fields in the description is quite useless since their documentation is already part of the specification of the class.

[Davi0kProgramsThings]

Missing description for the constructor.

[Davi0kProgramsThings]

Instead of using three positional arguments, use a single object:

Suggested change

	/**
	* @param {string} policyId - The id of the policy that produced the verdict.
	* @param {string} ruleName - The name of the matching rule.
	* @param {string} reason - A human-readable explanation.
	*/
	constructor (policyId, ruleName, reason) {
	/**
	* @param {Object} error - The error.
	* @param {string} error.policyId - The id of the policy that produced the verdict.
	* @param {string} error.ruleName - The name of the matching rule.
	* @param {string} error.reason - A human-readable explanation.
	*/
	constructor ({ policyId, ruleName, reason }) {

[Davi0kProgramsThings]

These properties should have private visibility and be accessible through a public getter method. Make sure to include a meaningful description in their documentation.

[Davi0kProgramsThings]

By using zod, you could infer all these types from the JSON or zod schema. This is extremely useful since it centralizes typing, validation and normalization in a single source file.
https://zod.dev/basics?id=inferring-types#inferring-types

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	zod@​4.4.3

View full report