feat(custody): let an owner's own grant narrow their access level

[TaprootFreak]

What this changes

An access level on a custody account now decides two things it did not decide before.

The owner's own grant sets their level. The owner always received WRITE, and the authorisation actually granted on the account was never consulted. An active grant an owner holds on their own account now decides it. Without such a grant nothing changes — the owner keeps full disposal, which is every account in production today.

An owner may re-level their own grant. Previously no API path led to a narrowed state at all: self-grants are refused and the owner's grant row could not be modified. An owner can now limit themselves to inspection and take the mandate back. Revoking that row stays refused — it would leave the account without an owner row and make the level unrecordable.

Rights may be taken away while an account is held, not handed out. Grant management no longer depends on account status — otherwise blocking one account would strand the grants on it, and since a narrowing blocks the owner's whole Safe, a single block would freeze everything they hold with no way back. Issuing a new grant and raising a stranger from inspection to acting are refused on a held account, though: both widen someone's authority, which is what a hold is meant to prevent. Withdrawing and lowering stay open.

Order creation now consults the level. It never did. Orders run under the custody role and reach the Safe on their own, so an owner limited to inspection could still trade; hiding buttons in a frontend would have been decoration, because the API accepted the order regardless. createOrder and confirmOrder now refuse when an own account is limited to inspection.

Why

A signed authorisation can reserve acting for one person while the account holder only inspects. Today that arrangement cannot be expressed: whoever owns the account may act, whatever the mandate says.

Design notes

• Orders address a whole Safe, not a single account — balances and orders carry no account today. Any own account narrowed to READ therefore blocks acting: the order could touch exactly those holdings. Fail closed rather than guess which account an order belongs to. This falls away once holdings carry an account.
• Nobody can lock themselves out. Managing grants stays tied to ownership, not to the level (requireOwner), so a narrowed owner can hand the mandate back at any time.
• Reading is unaffected. A narrowing withdraws acting, not sight — the holdings are the owner's either way, so the multi-account refusal in resolveOwnerAccountId still rightly skips the owner.
• Deactivated history stays out of authorisation. Only active: true grants count, unchanged.
• Legacy accounts are untouched. The legacy path returns before any of this.

Tests

Neither service had a test suite. This adds both — 40 cases:

• owner without a grant keeps WRITE (the regression guard)
• owner with an active READ grant is refused WRITE, allowed READ; with WRITE keeps WRITE
• an inactive grant never narrows anything — deactivated history must not take part
• a READ grant on a foreign account does not block acting in one's own Safe
• a grant on a non-active account does not count
• re-levelling an owner's own grant works in both directions; revoking it is refused; revoking a stranger's grant works
• non-owners are refused on both updateAccess and revokeAccess
• the account list reports the narrowed level, filters inactive/foreign/non-active rows, and never lists an own account twice
• the owner can lift a narrowing on a blocked account — one block must not freeze their whole Safe
• on a blocked account, a stranger's level may be lowered but not raised, and no new grant may be issued — the refusal comes before the address is resolved, so the response cannot reveal whether a mail address is registered
• a blocked account stays restricted — blocking must not be a way to shed a narrowing
• order creation and confirmation refuse when acting is narrowed, pass the account holder's identity rather than either JWT id, and turn a stranger away on ownership before the narrowing check — so nobody can learn from the response whether an account is restricted

Verification

npx jest src/subdomains/core/custody --silent
  Test Suites: 3 passed, 3 total
  Tests:       45 passed, 45 total

npm run type-check      → clean
npx prettier --check    → clean

Verified against a running instance in both directions, not only in CI:

POST /custody/order  (owner limited to inspection)
  → 403 "This Safe is limited to inspection, acting is not permitted"

POST /custody/order  (mandate restored, same request)
  → 201 {"orderId":65,"status":"Created", …}

The app was started with the change in place to confirm dependency injection resolves — CustodyOrderService gained a constructor dependency, and that layer has hidden a defect from static checks before.

[github-actions]

❌ ESLint: 1 errors, 2 warnings

[TaprootFreak]

Seven review passes were needed to reach zero findings. Each fix exposed the next edge, so most of the passes found something the previous fix had opened:

1. The narrowing was unreachable. Self-grants are refused and the owner's grant row could not be modified, so no API path led to the state the change reacts to. Re-levelling one's own grant is now allowed; revoking it stays refused.
2. Order creation never consulted the access level. It runs under a different role and reaches the Safe on its own, so an owner limited to inspection could still trade. Hiding buttons in a client would have been decoration.
3. Blocking an account shed the restriction. The acting check only looked at active accounts — so a hold lifted the very limit that mattered most. The status filter is gone.
4. …which stranded the grants on a blocked account. Grant management still required an active account, so an owner could never lift a narrowing placed there — and since a narrowing blocks their whole Safe, one block would have frozen everything they hold. Grant management now depends on ownership alone.
5. …which let rights be handed out during a hold. Issuing a new grant, and raising a stranger from inspection to acting, both widen authority and take effect the moment the account is released. Both are refused now; withdrawing and lowering stay open.
6. Smaller: an exception type that did not match six comparable places in the codebase, an unused import, a ternary where the codebase uses ??, and four comments that had gone stale as the code moved under them.

Beyond CI, the behaviour was verified against a running instance in both directions — with the narrowing in place an order is refused, and with the mandate restored the identical request succeeds. Accounts without a narrowing grant, which is every account in production today, are unaffected.

Neither CustodyAccountService nor CustodyOrderService had a test suite before; both do now, 40 cases.