ADR 0017 — Layered BFF: one route table, route classes, read models

• Status: Accepted (plan bff-layered, 2026-10-24).
• Refines: ADR 0006 (API clients), ADR 0015 (kernel routes), ADR 0016 (/events).
• Extended by: ADR 0018 (node pool, node identity).
• Plan: plans/bff-layered/ (architecture 01-architecture.md, auth surface 04-auth-surface.md, naming 10-naming.md).
• Security evidence: findings/bff-security/re-review.md (SHIP-WITH-FIXES), plans/bff-layered/security-fold.md.

Context

• The old forwarder relayed browser headers to ddx-api. Every new route needed a security review of what the browser could smuggle through.
• The RSC server client read headers() for forwarding, so a browser user-agent and sec-fetch-* reached ddx-api (the tripwire BROWSER_HEADERS_UPSTREAM now warns on that).
• Org data (active org, members, permission checks) came from the better-auth organization plugin (/auth/organization/*), outside AccessPolicy, projection and audit.
• Hand-written controllers (media, ai, threads, notifications, settings, webhooks) lacked RBAC, projection or audit.

Decision

Two layered pipelines joined by ONE typed route table (packages/ddx-contracts/src/bff-routes.ts). The browser talks only to ddx-web app/api/v1/**. ddx-web server code (RSC, DAL, Route Handlers) talks only to ddx-api, always with Authorization: Bearer <jwt>.

Rejected: a generic header pass-through proxy. It relays browser identity and makes every route a security review.

Route classes

The table is data. Kernel entity rows derive from the descriptor list, so a new descriptor gets json-read and json-mutation rows with no BFF code.

ddx-web layers (ddx-web/src/lib/bff/<layer>/, request order)

Route table (routes/) → same-origin gate (origin/: non-GET/HEAD needs own Origin, else 403 CSRF_ORIGIN; no CORS; OPTIONS answered by the BFF) → rate limit (rate/, fixed window per session and class, 429 + Retry-After) → header allow-list (headers/, per class) → node pool and bridge (bridge/, pool/, ADR 0018) → identity (session/: cached ddx_api_jwt, single-flight mint at /auth/token, refresh at exp − 30 s) → context (x-request-id, x-locale) → transport (forward.server.ts: no-store, redirect:'manual', class deadline) → response relay (drop hop-by-hop and set-cookie except auth-browser) → error map (errors/: house envelope {statusCode,message,code,requestId}) → cache revalidation (cache/). lib/api/forward.server.ts and lib/api/server.ts stay thin adapters; the server client sends an EMPTY inbound header set.

ddx-api layers (existing chain, gaps filled)

Controller → CredentialGuard → ClientThrottlerGuard → OrgContextGuard → OrgSlugGuard → RolesGuard → EntityAccessGuard + AccessPolicy → service → ProjectionService → ProofChainService audit → TenantPrismaService. New: ETag / If-Match 412 interceptor, PUT :id, HEAD, ?disposition=attachment, ApiAuthzHeaderInterceptor (x-ddx-authz), request-log tripwire.

Read models replace the organization plugin

/auth/organization/* is set-active only. A non-member slug returns 404 (no existence oracle).

Browser auth allow-list

Browser may call only: sign-in/email, sign-up/email, sign-out, get-session, request-password-reset, reset-password, verify-email, magic-link/*, email-otp/*, organization/set-active. Everything else under /auth/* is 404 in the route table AND in ddx-api AuthController. Only /auth/token carries a cookie (session cookie names only).

Consequences

• Adding a route is a route-table row, not a security review.
• Invariants 33-37 in context/_invariants.md bind the layers; gate ./ddx-manage.sh bff-layers.
• Open items from the re-review (S1 TOFU key pin, S3, S8, S11, INFO-3) are tracked in findings/bff-security/re-review.md.

Last reconciled: 2026-10-24 · plan bff-layered task 016

• ddx-documentation — dudoxx-web-boot

adr/

• ADR 0001 — Scaffold route: dudoxx-sandbox-creator with 163XX overrides
• ADR 0002 — Auth: better-auth 1.7 in ddx-api
• ADR 0003 — Route shape: org slug, role, [entity]/[id], ?view=
• ADR 0004 — Database split: one Postgres 18 instance, six databases
• ADR 0005 — Frameworks and the approved dependency table
• ADR 0006 — API clients come from one factory
• ADR 0007 — Typed service container (DI / IoC)
• ADR 0008 — Singleton scope: what may live at module level
• ADR 0009 — One variant API for every inventory component
• ADR 0010 — Media path: presigned URLs from ddx-api after the org check
• ADR 0011 — Media proxy: MinIO only through ddx-api
• ADR 0012 — Density names: compact | cosy | large
• ADR 0013 — Platform super-admin acts as org-admin of the target org
• ADR 0014 — Unified settings: one registry, three tiers, one resolve in ddx-api
• ADR 0015 — Entity kernel: one descriptor, one access seam, one projection, one proof chain
• ADR 0016 — SSE Bus: Redis Streams log, Redis pub/sub fan-out, BullMQ outbound queue
• ADR 0017 — Layered BFF: one route table, route classes, read models
• ADR 0018 — Cluster node registry, node identity, hot plug
• ADR 0019 — Tenant branding: settings keys, vendored palettes, public platform read
• Debug overlay

deploy/

• Deploy runbook — dudoxx-web-boot
• Entity kernel — guide
• Feature map — what each role can do
• Component inventory
• Naming constitution — dudoxx-web-boot
• Observability — one log layout, one key set
• Pattern reference — P1-P23 and groups A-K
• Port map — dudoxx-web-boot

research/

• RQ1 — Which release is "latest", and does it differ from the canon?
• RQ10 — SSE through the Next.js BFF route handler (desk half)
• RQ11 — Dev latency baseline: cold compile per route + next-server RSS
• RQ2 — Route group or dynamic org slug?
• RQ3 — better-auth 1.7 vs Auth.js v5: feature matrix
• RQ4 — Separate databases or separate schemas?
• RQ5 — Which frameworks beyond shadcn earn a place?
• RQ6 — How do DI, IoC and Singleton behave across RSC, client bundles and NestJS?
• RQ7 — Which data uses the server cache, which uses TanStack Query, how is each invalidated?
• RQ8 — Media path: presigned URLs vs streaming through the BFF
• Template triage — create-nextjs code in ddx-web
• Settings — guide
• Local setup — dudoxx-web-boot
• Shell tree — SiteShell and PortalShell
• SSE event catalog
• Version pins — dudoxx-web-boot