← all branches

feat/one-api

needs attentionviewing older commit
5642ccc · incrementalpre-PRreviewed 2026-08-03 20:17 UTC2H · 3M · 2L · 2I
The branch
Purpose
Unify the Batu API surface (one contract tree, visibility as metadata), retire the shared INTERNAL_API_KEY in favour of attributable service tokens, add machine-caller RLS isolation, and instrument the public API with per-request telemetry before W3 convergence.
Goal
Ship the foundational security + observability layer (W2/W2.5) that makes W3 DUAL convergence safe: service keys, internal-auth telemetry, RLS machine isolation, and sealed-secret rotation.
Sub-goals
  • SG-1: Service-key entity + sk_ credential class
  • SG-2: Internal mount dual-accepts legacy key AND service token
  • SG-3: internal.auth telemetry — record WHICH credential arrived
  • SG-4: Per-request telemetry at withMetaGate (public mount)
  • SG-5 blocker (BAT-294): SFN/EventBridge Connection cannot token-exchange — must resolve before retiring INTERNAL_API_KEY
  • W2.5: api_request_events table + durable persistence
  • DB: Machine-caller RLS via org-claim GUC (0069_machine_org_claim)
  • DB: Sealed webhook secrets at rest
  • Docs: Access-control narrative (compliance artifact)
  • Docs: BAT-291 — why backend does NOT get RLS
  • Docs: BAT-294 — topology framing + SFN blocker (this commit)
The changes (whole branch)
What
Added ~38 lines of documentation recording the BAT-294 blocker (EventBridge Connection static-header limitation blocks SFN caller from doing JWT token exchange) and the topology framing for withInternalAuth (AWS pipeline + Vercel domain logic = HTTP across trust boundary by deployment choice, not security choice).
Why
The blocker is non-obvious: Lambda callers CAN exchange an sk_ for a JWT; EventBridge Connection callers CANNOT (static header). Without this note, a future developer would miss it and declare SG-5 unblocked prematurely.
Areas
domains/core+1365−139apps/platform+1323−48packages/api+622−44docs/security+318−0scripts/db+253−0.claude/rules+226−6packages/database+196−11docs/design+191−0.github/workflows+68−2infra/cdk+11−1
Blast
Branch total: ~85 files, +4,205/−252 across 10 areas (excl. 5 Drizzle snapshots ~67k lines generated). This commit: 2 files, +38/-0, docs only.
➖ci· No PR open — no CI rollup available➖coderabbit· No .coderabbit.yaml in repo

Findings · 9

correctness4

high

BAT-294 names a caller that cfe-pipeline.md records as RESOLVED

.claude/rules/one-api.md:595

cfe-pipeline.md § EventBridge Connection Caveat: 'No EventBridge Connections remain in the CFE pipeline stacks.' CDK (stepfunctions.stack.ts:165-167): 'The HTTP URL templates + httpRetry were removed when the pipeline consolidated to lambda:invoke (SG-10 / W1). apiUrl is passed to grantStateMachinePermissions for IAM-level path guards only.' Connection object exists but is NOT wired to any active ASL HTTP Task state.

high

Same stale claim mirrored into withInternalAuth JSDoc

packages/api/src/middleware/internal-auth.ts:28

A developer reading this before changing the middleware will design around a constraint that no longer applies — all SFN states are now lambda:invoke; those Lambda callers CAN perform token exchange.

medium

IAM reachability claim conflates AWS-to-AWS vs AWS-to-Vercel paths

.claude/rules/one-api.md:603

'Rung 1 is structurally unreachable' is true for Vercel HTTP calls but not for Lambda-to-Lambda (which IS IAM-authenticated via lambda:invoke). Could mislead a reader.

low

Topology framing and credential ladder are factually correct

.claude/rules/one-api.md

The 'Batu talking to Batu' framing, security ladder ordering, and Vercel mTLS claim are all accurate.

security2

medium

Stale blocker may delay or misdirect SG-5 planning

.claude/rules/one-api.md

If Connection callers are gone, the EventBridge-specific blocker doesn't apply. The real SG-5 gate is the internal.auth telemetry showing zero legacy_static_key emits over a full cron cycle — which is correctly documented elsewhere.

low

Credential ladder ranking and anti-bespoke-signing advice are sound

.claude/rules/one-api.md

No sensitive details leaked. The guidance is correct for the HTTP path.

conventions1

info

Documentation pattern correct; content accuracy is the issue

The arch-rule + code-comment duplication follows CLAUDE.md conventions. The problem is the claim being duplicated may be stale.

tests1

info

No test impact — docs only

Existing internal-auth.test.ts coverage unaffected.

improvement1

medium

Verify: does any SFN still use EventBridge Connection for live HTTP Tasks?

infra/cdk/src/stacks/services/utility/bills/cfe/stepfunctions.stack.ts

If no — reframe or remove the BAT-294 note. If yes — update cfe-pipeline.md to reflect that. The two SSOTs currently contradict each other.

History · 47 commits

  1. 82bb5b9blockedincremental5H · 5M · 4L2026-08-12 01:48
  2. 90aa3d5needs attentionincremental1H · 5M · 3L2026-08-11 19:37
  3. 29d19a0needs attentionincremental1H · 5M · 9L2026-08-11 17:41
  4. 9bd8a0cneeds attentionfull0H · 5M · 9L2026-08-11 02:14
  5. 62ec3f7needs attentionincremental2H · 5M · 6L2026-08-10 22:51
  6. f93bca9needs attentionincremental2H · 5M · 8L2026-08-10 17:51
  7. 052db6fneeds attentionincremental1H · 3M · 4L2026-08-09 21:13
  8. 45699caneeds attentionincremental0H · 7M · 11L2026-08-09 17:44
  9. b843d8aneeds attentionincremental1H · 7M · 9L2026-08-09 04:05
  10. e1757b8needs attentionincremental0H · 3M · 6L2026-08-05 02:11
  11. 7a762faneeds attentionincremental2H · 5M · 5L2026-08-05 01:25
  12. 3300a60needs attentionincremental2H · 4M · 7L2026-08-04 19:06
  13. 0c8a7f5needs attentionincremental0H · 4M · 9L2026-08-04 18:15
  14. 345f42eneeds attentionincremental2H · 6M · 9L2026-08-04 17:28
  15. 8338a9aneeds attentionincremental5H · 14M · 14L2026-08-04 00:33
  16. 41be4c3needs attentionincremental0H · 5M · 7L2026-08-03 23:49
  17. 5ed593dneeds attentionincremental1H · 6M · 6L2026-08-03 21:32
  18. b333e25needs attentionincremental4H · 9M · 8L2026-08-03 21:00
  19. 5642cccneeds attentionincremental2H · 3M · 2L2026-08-03 20:17current
  20. 73b0b39needs attentionincremental3H · 10M · 13L2026-07-31 18:29
  21. b19852eneeds attentionincremental0H · 1M · 5L2026-07-29 05:04
  22. 3845205needs attentionincremental3H · 6M · 4L2026-07-29 04:47
  23. eb8eb50needs attentionincremental0H · 1M · 2L2026-07-29 03:03
  24. f4720a3needs attentionincremental6H · 8M · 7L2026-07-29 02:54
  25. f8d341ablockedincremental2H · 2M · 5L2026-07-29 00:00
  26. a7f1a64needs attentionincremental2H · 8M · 8L2026-07-28 18:41
  27. 738b60bblockedincremental3H · 6M · 5L2026-07-28 00:46
  28. 2c248b6needs attentionincremental8H · 12M · 8L2026-07-27 23:23
  29. 1346cc0needs attentionincremental2H · 8M · 6L2026-07-27 20:15
  30. 0716018needs attentionincremental2H · 11M · 12L2026-07-27 19:22
  31. 215cd2dneeds attentionincremental3H · 6M · 5L2026-07-27 17:04
  32. ec46958needs attentionincremental0H · 3M · 5L2026-07-27 16:51
  33. de7b337blockedincremental4H · 9M · 14L2026-07-27 06:36
  34. b1bb9c0needs attentionincremental1H · 2M · 4L2026-07-27 05:09
  35. 4701d11needs attentionincremental0H · 4M · 3L2026-07-27 04:44
  36. e1626c4needs attentionincremental3H · 9M · 10L2026-07-27 03:21
  37. 195f198needs attentionincremental3H · 3M · 3L2026-07-25 01:22
  38. 42c7358safeincremental0H · 0M · 0L2026-07-22 20:46
  39. 85b9018needs attentionincremental0H · 1M · 6L2026-07-21 23:51
  40. a7b2a9aneeds attentionincremental0H · 9M · 12L2026-07-21 18:49
  41. c2ee0daneeds attentionincremental4H · 7M · 7L2026-07-21 02:17
  42. e8ffa5eneeds attentionincremental4H · 7M · 5L2026-07-21 01:33
  43. a2d2a54needs attentionincremental2H · 7M · 3L2026-07-21 00:51
  44. 576fbd6needs attentionfull1H · 6M · 7L2026-07-21 00:35
  45. d3465e8needs attentionincremental1H · 7M · 10L2026-07-21 00:23
  46. dc794a7needs attentionincremental0H · 5M · 5L2026-07-20 23:46
  47. 9082773needs attentionfull1H · 3M · 3L2026-07-20 23:13