docs: replace api-gateway specs with authenticator + gateway PRD/DESIGN (nginx+auth step 01)

[cyberantonz]

Part of EPIC #1583 (nginx + authorization), step 01 of 11. Docs only -- no code changes.

Closes #1584.

What

• Deleted the entire docs/components/backend/api-gateway/ spec tree (umbrella PRD/DESIGN, bff/, router/), per the decision document: the custom Rust Router is commodity work nginx does better; the BFF half survives as a standalone authenticator service.
• Added docs/components/backend/authenticator/PRD.md + DESIGN.md -- the authenticator gear:
  • opaque __Host-sid cookie as a rotating credential; stable session_id (UUIDv7) as the session identity; gateway JWT minted at login, linked 1:1 to the session, reissued ahead of expiry (guaranteed 60 s travel margin)
  • claim contract: sub = person_id, tenants[] (only tenant authority), roles (default ["user"]), sid, iss/aud/iat/exp/jti -- supersedes DD-ROUTER-05
  • /internal/authz exchange contract incl. Cache-Control: max-age = min(authz_cache_max_age, jwt_exp - now - 60 s), non-200 = no-store
  • Redis schema under the new asm: prefix (authenticator session management): token mapping with grace-TTL rotation (no swap keys, no RENAME), linked JWT, indexes, idp_refresh_due schedule
  • background IdP token refresh: fail-open on transport, fail-closed on invalid_grant (all linked sessions die); offline_access requirement + no_refresh_token_policy
  • service tokens: POST /internal/token, RFC 7523 assertions, gitops-reviewable registry, sub = service:<name>
  • two listeners + network scopes; "network position is never authentication"
  • bootstrap: guardrailed empty-table first-admin + INSTALLER as production path
  • gear anatomy: #[toolkit::gear], OperationBuilder, CanonicalError/RFC 9457, authenticator-sdk, SecurityContext claim alignment
  • EdDSA vs ES256 recorded as open, resolved in step 04
• Added docs/components/backend/gateway/DESIGN.md -- the nginx (OpenResty) edge: ingress-orthogonal topology, route configurator (salvaged routes.yaml schema minus websocket_max_lifetime_seconds), generated location hygiene block, subrequest contract, Lua exchange cache / UUIDv7 correlation ids / RFC 9457 error shaping, failure table, reload procedure.
• Updated parent specs (backend/specs/PRD.md + DESIGN.md): token-handler authentication model, architecture diagram + routing through the gateway, authenticator + gateway components, first-login and analytics-query sequences.
• Updated cypilot/config/artifacts.toml: removed the four deleted artifacts, registered the three new ones.

Salvage (per step instructions)

routes.yaml schema (router DESIGN 3.8), OIDC code+PKCE + session-fixation guard, logout incl. back-channel + jti replay guard, CSRF, cookie attributes; DD-ROUTER-03/09/10 and DD-BFF-01/02/03/09 carried over; DD-ROUTER-05 and the "no IdP refresh in v1" carve-out recorded as superseded.

Validation

• cfs toc -- all touched artifacts up to date ("unchanged")
• cfs check-language -- no violations
• cfs validate --local-only reports "No artifacts found in registry" for this repo -- pre-existing cypilot issue, reproducible on untouched artifacts from main (e.g. analytics/DESIGN.md); the registry TOML parses fine (150 artifacts)
• manual where-used sweep: no dangling cpt-insightspec-* references to removed IDs anywhere in docs/

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Introduced proposed Authenticator Service concepts and a nginx edge gateway design for session-based browser authentication and per-request cookie-to-JWT exchange.
• Documentation
  • Added Authenticator and Gateway design/PRD documentation.
  • Updated backend specs to reflect the new authentication flow and gateway JWT verification expectations.
• Chores
  • Updated the backend artifacts registry to reference the new authenticator and gateway documentation.
  • Removed outdated API gateway BFF/router design and PRD documents.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR replaces API Gateway documentation with Authenticator Service and nginx Gateway documents, updates backend specs to the new session-to-JWT auth flow, and repoints the artifact registry to the new document locations.

Changes

Backend auth architecture documentation overhaul

Layer / File(s)	Summary
Authenticator Service PRD and DESIGN docs/components/backend/authenticator/PRD.md, docs/components/backend/authenticator/DESIGN.md	Adds the Authenticator Service PRD and design, covering session identity, cookie rotation, gateway JWT exchange, Redis state, JWKS, logout, refresh, and design decisions.
Gateway (nginx edge) DESIGN docs/components/backend/gateway/DESIGN.md	Adds the nginx edge gateway design, including route generation, auth_request exchange, request/header shaping, failure handling, deployment, observability, and ADRs.
Backend specs PRD/DESIGN updates docs/components/backend/specs/PRD.md, docs/components/backend/specs/DESIGN.md	Updates the parent backend specs to describe the Authenticator/nginx gateway architecture, revised diagrams, routing ownership, and authentication behavior.
Artifacts registry update .cf-studio/config/artifacts.toml	Repoints the artifact registry from API Gateway/BFF/Router docs to the new Authenticator and Gateway documents.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related issues

• PLATFORM 1: EPIC: nginx + authorization — replace the API Gateway with nginx auth_request + authenticator gear #1583: Matches the broader nginx + authenticator replacement of the old API Gateway described by these doc updates.
• nginx+auth 09 — destroy the old api-gateway service + wiring #1592: Tracks the same API-gateway doc removal and replacement with Authenticator and gateway specs.

Suggested reviewers: ktursunov

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the docs-only replacement of api-gateway specs with authenticator and gateway documentation.
Linked Issues check	✅ Passed	The PR matches #1584 by removing api-gateway docs, adding authenticator and gateway specs, and updating parent backend docs.
Out of Scope Changes check	✅ Passed	The changes stay within the requested docs-only scope and align with the auth and gateway documentation migration.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/components/backend/authenticator/PRD.md`:
- Around line 621-623: The Login section heading in the PRD markdown is skipping
a level and should be aligned with the surrounding section structure. Update the
`Login` heading in the relevant markdown block from `####` to `###` so it
matches the `##` parent section and keeps the TOC/anchors consistent.

In `@docs/components/backend/gateway/DESIGN.md`:
- Around line 81-85: The gateway readiness is currently coupled to the
authenticator dependency, which can cause transient auth outages to mark the
gateway unready. Update the readiness behavior described in the gateway design
so the gateway probe stays local and independent, and move the authenticator
check into a separate health check or dependency probe; use the existing gateway
deployment/readiness description and the authenticator `/ready` reference to
locate the affected text.
- Around line 268-271: The gateway cache behavior needs to account for token
rotation because the cache key is the raw session-token cookie value, which can
keep authorizing a retired cookie until the TTL expires. Update the DESIGN.md
guidance around the cache TTL/cache key and revocation staleness to add a
refresh/rotation invalidation strategy or a versioned cache key tied to the
authenticator’s token rotation, and tighten the TTL coupling so stale cookies
cannot remain valid for the full cache window.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 64691ff6-71e5-4ed7-99b0-9dfbffeee1a0

📥 Commits

Reviewing files that changed from the base of the PR and between 7289fa7 and 921081e.

📒 Files selected for processing (12)

• .cf-studio/config/artifacts.toml
• docs/components/backend/api-gateway/DESIGN.md
• docs/components/backend/api-gateway/PRD.md
• docs/components/backend/api-gateway/bff/DESIGN.md
• docs/components/backend/api-gateway/bff/PRD.md
• docs/components/backend/api-gateway/router/DESIGN.md
• docs/components/backend/api-gateway/router/PRD.md
• docs/components/backend/authenticator/DESIGN.md
• docs/components/backend/authenticator/PRD.md
• docs/components/backend/gateway/DESIGN.md
• docs/components/backend/specs/DESIGN.md
• docs/components/backend/specs/PRD.md

💤 Files with no reviewable changes (6)

• docs/components/backend/api-gateway/bff/PRD.md
• docs/components/backend/api-gateway/bff/DESIGN.md
• docs/components/backend/api-gateway/DESIGN.md
• docs/components/backend/api-gateway/router/PRD.md
• docs/components/backend/api-gateway/PRD.md
• docs/components/backend/api-gateway/router/DESIGN.md

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/components/backend/gateway/DESIGN.md (1)

391-402: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Clarify the cache key wording.

Lines 392 and 398-400 describe two different cache keys: the raw session-token cookie value vs. a stable session_id. That makes the rotation/staleness contract ambiguous for implementers. Please align the wording so the document states one model consistently.

♻️ Suggested wording fix

- The cached artifact is the session-linked JWT (keyed by the stable session_id, not the token);
+ The cached artifact is the session-linked JWT, but the cache key remains the raw session-token cookie value;

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/components/backend/gateway/DESIGN.md` around lines 391 - 402, The cache
key description is inconsistent: one place says the key is the raw session-token
cookie value, while the rotation section says the cached JWT is keyed by stable
session_id, which makes the contract ambiguous. Update the wording in DESIGN.md
so the cache key model is stated consistently across the cache TTL/key table and
the “Cookie rotation and the cache” section, using the same symbol/term
throughout (for example, the authenticator’s session-token cookie value or the
stable session_id, but not both).

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@docs/components/backend/gateway/DESIGN.md`:
- Around line 391-402: The cache key description is inconsistent: one place says
the key is the raw session-token cookie value, while the rotation section says
the cached JWT is keyed by stable session_id, which makes the contract
ambiguous. Update the wording in DESIGN.md so the cache key model is stated
consistently across the cache TTL/key table and the “Cookie rotation and the
cache” section, using the same symbol/term throughout (for example, the
authenticator’s session-token cookie value or the stable session_id, but not
both).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 75a7fee5-ea92-4ab4-a62f-e40e637106fb

📥 Commits

Reviewing files that changed from the base of the PR and between d6ed3aa and f362ed5.

📒 Files selected for processing (2)

• docs/components/backend/authenticator/PRD.md
• docs/components/backend/gateway/DESIGN.md

✅ Files skipped from review due to trivial changes (1)

• docs/components/backend/authenticator/PRD.md