Auth strategy assessment: Couch /_session vs in-house JWT

[PeterBaker0]

Summary

Critical assessment of Couch GET /_session identity resolution vs in-house JWT, measured with the ACL perf harness under PROFILE=true.

Clarification

There is no ACL TTL — document ACL is changes-fed. The 5s knob is SESSION_CACHE_TTL_MS (principal / session-response cache). Defaults already use 5s.

Measured results (sticky Bearer JWT clients)

Variant	overall ops/s	HTTP auth ms/req	auth share	Δ overall vs 5s
Couch session TTL=0	245.7	1.966	26%	-14.5%
Couch session TTL=1s	277.6	0.028	0.5%	-3.4%
Couch session TTL=5s (keep-as-is)	287.3	0.019	0.3%	baseline
Couch session TTL=30s	292.2	0.019	0.3%	+1.7%
Hybrid Bearer local JWT + 5s	284.4	0.016	0.3%	-1.0%
Local JWT-only + 5s	280.0	0.018	0.3%	-2.5%
Local JWT-only, no cache	258.9	0.717	11%	-9.9%

Upstream Couch remains ~55–75% of HTTP mean duration; auth is noise once the 5s principal cache is warm.

Verdict

• Keep Couch /_session + 5s cache for mixed Basic/Cookie/JWT — already removes almost all session tax vs TTL=0.
• Hybrid (JWT_LOCAL_VERIFY=true with session still on) is the right upgrade for JWT-heavy apps; ops/s ≈ keep-as-is, but Bearer skips /_session even at TTL=0.
• JWT-only only if you drop Basic/Cookie and accept JWT exp as revocation (role changes in _users won’t apply until re-mint).
• 30s TTL is not worth the wider demotion lag under sticky load.
• In-house JWT does not create a stronger trust domain — Couch still validates the same keys on the upstream hop.

Full write-up: docs/auth-strategy-assessment.md. Re-run: pnpm test:perf:auth.

Code

• Hybrid Bearer fast-path when both session resolve and JWT_LOCAL_VERIFY are on
• Local JWT principals join the same LRU+TTL cache
• pnpm test:perf:auth + report assembler; PERF_ADMIN_JWT for Bearer-only admin setup

Test plan

• pnpm test (unit, 209)
• pnpm lint / pnpm typecheck
• pnpm test:perf:auth (7 variants; tables in assessment doc)