feat(policy)!: deny-by-default proxy with central exclusion list

[AlonzoRicardo]

Problem

The engine governed a fixed 22-method list. A wallet method absent from it reached the signer with no evaluation and no error — the policy silently did not apply. For a policy engine that is the worst available failure mode: the guardrail looks installed and isn't.

The audit quantifies it. 28 write methods across three packages were invisible to the engine: 12 on Spark (payLightningInvoice, paySparkInvoice, claimDeposit, createLightningInvoice, …), 14 on the Safe multisig account (executeTx, addOwner, changeThreshold, …), 2 on Aave (setUserEMode, setUseReserveAsCollateral).

Change

Coverage is inverted. The proxy wraps every callable on the account and its prototype chain, and consults an exclusion set — DEFAULT_POLICY_EXCLUSIONS ∪ options.policyExclusions, resolved once at construction. Unknown methods are governed, so the worst case is a loud PolicyViolationError instead of an unpoliced transfer.

Phase 1: the audit is the deliverable

docs/policy-exclusions-audit.md, Sections A–E. Two findings change the result, so please read the doc rather than just the list.

1. The brief's enumeration command silently under-samples the org. It specifies:

gh api /users/tetherto/repos --paginate --jq '.[].name'

That returns public repos only — 113 total, 47 wdk-*. The org endpoint returns 128 / 58. The 11 missing repos include four private packages with real protocol surface, among them wdk-protocol-multisig-safe, which contributes 16 writes and 19 reads and is the most write-dense account class in the org. Auditing from the public list would have shipped a default list missing 8 reads and left those 16 writes unexamined. The doc records the correct command; anyone re-running this must use it.

2. A get* prefix carries no information about whether a method mutates. Three Spark methods are named get* and create remote state:

• getSingleUseDepositAddress — "Generates a single-use deposit address"
• getStaticDepositAddress — "generating one if it does not already exist"
• and the trap: getStaticDepositAddress (singular) is a WRITE while getStaticDepositAddresses (plural) is a READ — one character apart, opposite classifications

All three stay governed. Any name-shaped heuristic for building this list would have put at least the first two into the defaults and reintroduced the exact bug this PR fixes.

No classification collisions. Every name appearing in more than one package classifies identically everywhere; the widely-shared ones (withdraw, dispose, getAddress, getTransfers, proposeMessage, swap/bridge) were each checked individually. So no legitimate read had to be withheld on collision grounds.

One deviation from the brief, flagged. Its Section E example lists cleanupConnections as consumer-append, while its own Step 1.3 rule lists it as a LIFECYCLE candidate for the defaults. Those contradict. I followed Step 1.3 — the normative rule: closing connections moves no value and gates nothing an attacker benefits from, while governing it would make finally { await account.cleanupConnections() } throw on any account without a matching ALLOW rule.

Resulting list: 73 entries, source in constants.js matches Section D exactly.

Two consequences the brief didn't call out

wdk-core's own additions to the account had to be excluded. _registerProtocols installs registerProtocol and six get*Protocol getters before the policy proxy wraps the account. Under deny-by-default the proxy sees them like any other callable, so without exclusion account.getSwapProtocol('velora') is denied and protocol access breaks entirely. toReadOnlyAccount is worse than that: the engine calls it to build the condition context, so governing it deadlocks evaluation against itself. All eight are in the default list, called out in Section D.

The rule schema had to be loosened. operation was validated against the OPERATIONS enum. With OPERATIONS deleted and any method governable, a rule for payLightningInvoice would have failed registration while the engine denied every call to it — the feature would ship unusable. operation is now any non-empty string, and PolicyOperation is string. This touches validation, not evaluator or rule semantics, so it stays inside the stated non-goals — but it is a public type widening and worth a look.

The upside: a typo'd operation name used to be a registration error. Now it registers, never fires, and the real method stays governed — so a typo fails safe instead of opening a hole. There's a test for exactly that.

Public API

import WDK, { DEFAULT_POLICY_EXCLUSIONS } from '@tetherto/wdk'

const wdk = new WDK(SEED, { policyExclusions: ['syncWalletBalance'] })
wdk.getPolicyExclusions()  // frozen readonly string[] — defaults ∪ yours

Append-only, flat, matched globally by method name. Non-string entries throw PolicyConfigurationError at construction. Unknown names are accepted so an exclusion can precede the wallet release that introduces the method.

registerPolicy now rejects a rule that names an excluded method. { operation: 'getTransfers', action: 'DENY' } used to register cleanly and could never fire — the proxy never wraps an excluded method, so the rule was unreachable. That is the same fail-open class this PR exists to remove, relocated to the exclusion side, so it throws at registration instead. The wildcard stays exempt: * means "every governed operation", which is by definition the set that excludes these names. Unknown and misspelled names are still accepted — those fail safe, because the real method stays governed.

Tests

178 passing, standard clean. A method coverage block plus targeted regressions.

Coverage: governed non-excluded method denies; DEFAULT_POLICY_EXCLUSIONS member executes untouched; consumer exclusion executes untouched; duplicate across both lists resolves once; empty and omitted both equal the defaults; non-string entries rejected; unknown name accepted; getPolicyExclusions() frozen and non-mutating; no-policies short-circuit; inherited method governed; accessor not intercepted; excluded-method rule rejected (single and inside an array); wildcard not treated as excluded; protocol method outside the old verb list governed and mirrored in simulate; governed sync method returns a promise; own accessor shadowing a prototype method not invoked at wrap time; two engines with different exclusion sets resolving the same class differently.

Three worth singling out:

• The accessor test asserts the getter is never invoked, not merely that it isn't wrapped. Classification reads property descriptors, so a getter with side effects is never triggered by wrapping. The test counts reads and asserts 0 after wrap, 1 after an explicit read.
• The short-circuit test asserts proxy identity (account.sendTransaction === rawAccount.sendTransaction) rather than spying on evaluate. If no proxy exists the engine cannot be reached at all — a stronger claim than "evaluate wasn't called".
• Resolved-set sizes are hardcoded (73 / 74) rather than derived from DEFAULT_POLICY_EXCLUSIONS.length. Deriving them would let a test pass while someone silently deleted entries from the audited list.

Three pre-existing tests were migrated off the inclusion model: two unknown-operation rejection tests now assert empty-string rejection and that payLightningInvoice registers and fires, and the signMessage/signHash test inverts to assert the typo now fails safe.

Notes

• .d.ts hand-maintained; every declaration diffed against main and traced to an intended source change. The two known deviations in types/src/wdk.d.ts are preserved.
• DEFAULT_POLICY_EXCLUSIONS is frozen because it ships publicly — in-place mutation would widen the exclusion set for every engine built afterwards in the process.
• The inherited half of the prototype walk is memoised per (engine, prototype); own members are still collected fresh per instance, because the WDK installs registerProtocol and the protocol getters directly onto each account and they must keep shadowing inherited ones. 20k getLendingProtocol calls: 47ms → 19ms.
• No statics on wallet classes, no per-wallet keys, no derivation from the readonly hierarchy, no ungovernedBehavior switch, no wildcards in the exclusion list, no removal API, no companion wallet PRs, no evaluator changes, no error-message changes (that's feat(policy): hint at catch-all pattern in no-match PolicyViolationError #80).
• No version bump — release branches do that.
• Branched off main. Overlaps feat(policy): hint at catch-all pattern in no-match PolicyViolationError #80 in constants.js, README.md, AGENTS.md and the test file; expect conflicts whichever lands second and ping me for the rebase.

Deliverables

• Phase 1: docs/policy-exclusions-audit.md committed, Sections A–E filled in
• Section A lists every tetherto/wdk-* repo — 58, via the org endpoint, not the brief's 47
• Section B classifies every public method on every account/protocol class
• Section C reports collisions — none, plus three recorded traps
• Section D contains the proposed list (73 entries), sorted
• Section E contains the consumer-append snippet (Spark only)
• Phase 2: source list matches Section D exactly
• All acceptance criteria met; 178 tests pass; lint clean
• .d.ts hand-updated, not regenerated in place
• No inline // comments added to method bodies