feat(auth): require staff KYC clearance on elevated endpoints

[TaprootFreak]

What

Access to endpoints gated on Admin, Debug, Compliance, Support or RealUnit now
additionally requires an identified natural person behind the calling account:
kycLevel >= 50 and a non-blank verifiedName. The role alone is no longer sufficient.

How

The check lives in RoleGuard, so it covers all 235 elevated gates at once.

It is a property of the endpoint, not of the caller: it applies only when every entry role
of a gate is elevated. A gate that also admits UserRole.USER stays an ordinary endpoint that a
staff member happens to reach through the role hierarchy, so ordinary customer functionality is
unaffected.

Data path, mirroring the existing JWT denylists:

• StaffKycClearanceService derives the cleared account ids from the DB every minute
• ProcessService primes an in-memory Set from the resulting staffKycClearance setting
• RoleGuard reads it synchronously — no DB lookup per request

Because the clearance is read from live data rather than the token, revoking a staff member's KYC
takes effect on already-issued tokens within one refresh interval — no re-login, no JWT secret
rotation.

The allowlist is deliberately fail-closed, unlike the denylists it mirrors: an empty or
not-yet-primed Set denies every elevated endpoint. A DB or cron outage must never silently
re-open admin access. ProcessService.onModuleInit therefore awaits the first prime before HTTP
starts, and a failing resync keeps the last known Set rather than clearing it.

staffKycClearance is derived data, so it is listed in SystemManagedSettings and rejected by
SettingService.set. Without that, the generic PUT /setting/:key route would let a cleared admin
write uncleared accounts into the allowlist, live until the next sync overwrote it. The sync path
writes through setObj and is unaffected — blocking it would freeze the allowlist.

Blank names

The verifiedName condition is filtered in SQL. Postgres' bare TRIM() strips ASCII space only,
unlike JS trim(), so a name consisting of a tab or a non-breaking space would otherwise clear an
account carrying no identification. The predicate uses BTRIM with the character set trim() strips,
spelled out explicitly rather than left to [[:space:]], whose meaning depends on the database locale.

A mocked repository never executes raw SQL, so staff-kyc-clearance.pg.spec.ts runs the predicate
against a real Postgres and pins it to the semantics it replaced: every blank variant is excluded,
padded real names are kept, and the outcome is asserted to equal the JS filter on every input. The
blank fixtures are derived from the JS runtime rather than from the constant under test, so removing
a character from that constant turns the suite red. It follows the existing MIGRATION_TEST_PG
pattern and runs in CI against the throwaway Postgres service.

Bypass paths closed

Three privilege checks live in business logic rather than behind a gate, on routes that are
not role-gated (OptionalJwtAuthGuard). Without these the requirement would be trivially
bypassable — an account losing /admin would keep:

• downloads of protected KYC files (KycService.getFileByUid)
• ownership-independent access to any customer's transaction history (HistoryAccessService)
• posting official support replies (SupportIssueController.createSupportMessage)

All three now use the new hasStaffAccess helper. Privilege checks behind already-gated
endpoints (the isAdmin distinctions in the support note services) are deliberately left
unchanged — the gate has already run by then.

Scope notes

• BankingBot and Custody are not staff entry roles and stay ungated, so a staff caller reaching
  those endpoints through the role hierarchy is not KYC-gated. Out of scope here; happy to extend.
• U+200B is deliberately absent from the blank-character set: trim() does not strip it either, so
  including it would make the predicate stricter than the check it replaced. Whether a name made of
  invisible characters counts as identification is a question about how verifiedName is written.

Tests

• 100% coverage (statements, branches, functions, lines) on the three files deciding elevated
  access, enforced by a dedicated CI step (test:staff-gate:cov) following the existing Frick
  coverage gate — including the full-compilation transform, so phantom branches from
  transpile-only decorator-metadata emit cannot skew the gate
• A real-Postgres suite for the blank-name predicate (see above)
• Existing suites for the three business-logic call sites extended with the uncleared cases

Before merging

This changes access for existing staff accounts on deploy: any account not meeting the requirement
loses every elevated endpoint, including the admin endpoints used to correct KYC data. Please
confirm the staff account data is in the expected state first — recovering afterwards means a
direct DB correction (the setting is sync-derived and will be overwritten) or a rollback. There is
also a short window after boot, until the first sync runs, in which no account is cleared.

[TaprootFreak]

Six review passes were needed before both independent reviews came back clean. What changed along the way:

Correctness of the blank-name filter. Moving the verifiedName condition into SQL introduced a
regression: Postgres' bare TRIM() strips ASCII space only, while the JS trim() it replaced also
strips tabs, newlines and Unicode spaces. A name consisting of a single tab would have cleared an
account carrying no identification. Fixed with an explicit BTRIM character set, and covered by a
suite that runs the predicate against a real Postgres and pins it to the semantics it replaced —
verified to turn red if a character is dropped from that set.

A manual override on the allowlist. The generic PUT /setting/:key route accepted
staffKycClearance, which contradicted this branch's own documentation and would have let a cleared
admin write uncleared accounts into the allowlist, live until the next sync overwrote it. Sync-owned
settings are now rejected in SettingService.set, so every caller is covered rather than only the
HTTP route.

Smaller items. Import ordering, a stale class reference in a comment, argument pinning in the
setting test after the controller test was folded into the service test, and a note recording why
U+200B is deliberately absent from the blank-character set.

CI is green on the final commit, including the dedicated coverage gate (100% on the three files that
decide elevated access) and the Postgres suite.

Note on CI history: the last commit did not trigger the PR workflow automatically, so the pipeline was
started manually for that commit — the run covers the same SHA.

[TaprootFreak]

Correction to the CI note above: the branch has since been rebased onto the current develop, so the
commit that needed a manually started pipeline no longer exists. All checks now run normally on the
current head and are green, including the coverage ratchet that arrived with the new base.