feat(openapi): add customer-facing API documentation build

[gustavosbarreto]

What

Split the OpenAPI into two builds from one source: the full spec (the internal
source of truth for frontend client generation and dev-mode response
validation) and a filtered, customer-facing documentation build that exposes
only the namespace-scoped, API-key usable surface.

Why

The published OpenAPI was a single spec that exposed every route to customers
(admin, internal, billing, auth, MFA, account management), most of which a
customer cannot call with an API key. It also carried a "NOT STABLE"
disclaimer, a stale contact address, and copy that repeated the namespace
scope on every operation.

Changes

• Customer build: a drop-non-customer Redocly decorator
  (plugins/customer-filter.js) keeps only operations that accept the
  api-key scheme and are namespace-scoped. It drops /admin and /internal
  paths, operations without api-key, and x-internal overrides; strips the
  jwt scheme so the docs are api-key only; and prunes edition/meta tags and
  empty groups. Wired as *-customer API entries in redocly.yaml, published
  on release by openapi-cd.yml. The full spec consumed by the frontend
  codegen and the dev validator keeps its full scope.
• Redocly upgrade: @redocly/cli 1.0.0-beta.100 to 2.31.5 (the beta
  had no decorators). Fixed the nullable-type-sibling errors the newer
  linter caught.
• Edition composition: cloud and enterprise are siblings over a shared
  base, not a linear chain. Fixed the broken $ref: cloud#/paths nesting in
  the enterprise spec (it was dropping the shared routes), removed SAML from
  cloud (enterprise only) and billing from enterprise (cloud only), and added
  the admin surface to cloud (the cloud build registers it).
• Spec vs Go alignment: dropped api-key from operations the Go handlers
  block or that require an owner-only permission (billing, namespace delete,
  the user-token mint, the internal offline route); they were advertising an
  auth method that can never succeed.
• Internal session route: the session authentication update was documented
  as a public POST /api/sessions/{uid}. Moved it to
  PATCH /internal/sessions/{uid} to match the real internal UpdateSession
  route.
• Content: a customer-focused home page (auth, base URL, namespace scope
  stated once, pagination, errors), x-displayName on tags ("SSH Public
  Keys", "Firewall Rules", and so on), and rewritten operation
  summaries/descriptions that drop the per-operation namespace redundancy and
  fix grammar. Removed the unused, redundant GET /api/users/security.
• Preview: /openapi/customer.html renders the filtered build locally;
  /openapi/ keeps the full spec.

Follow-ups tracked separately: #6390 (block API keys on account-level routes)
and #6391 (remove GET /api/users/security from the Go API).

[github-actions]

Claude finished @gustavosbarreto's task in 2m 21s —— View job

---

Code Review Complete

Reviewed 72 files across code quality, security, testing, Go/JS patterns, and architecture. 1 inline issue posted (critical: 1).

The overall design — splitting the OpenAPI into full and customer-filtered builds via a Redocly decorator — is clean and well-implemented. The customer-filter.js plugin logic is correct, the security: [] and api-key removal changes align with the Go handler behavior, and the edition composition restructuring (enterprise referencing community instead of cloud) properly separates cloud-only and enterprise-only routes.

The one critical issue is that ui-react/Dockerfile's spec-bundler stage will break because it copies openapi/redocly.yaml (which now declares a plugin) without also copying the openapi/plugins/ directory. See the inline comment for the fix.

---

To request another review round, comment /review.

[gustavosbarreto]

/review

[github-actions]

Code Review

• Gathered PR context
• Reviewing with 5 specialized agents
• Posting feedback

[gustavosbarreto]

/review

[github-actions]

Claude finished @gustavosbarreto's task in 11m 8s —— View job

---

Code Review Complete

Reviewed 75 files across code quality, security, testing, Go/JS patterns, and architecture. 1 inline issue posted (medium: 1).

The overall design is clean and well-implemented. The customer-filter.js decorator logic is correct — the path-prefix check, api-key scheme filtering, x-internal override, empty-path pruning, and unused-tag cleanup all work as intended against the actual spec files. The security: [] additions (MFA, healthcheck, accept-invite) correctly reflect that those routes authenticate via other mechanisms (MFA token, email signature, or none). The api-key removal from billing/auth/namespace-delete/offline routes aligns with Go handler behavior. The session route move from POST /api/sessions/{uid} to PATCH /internal/sessions/{uid} matches the actual UpdateSession implementation in pkg/api/internalclient/session.go. The enterprise $ref change from cloud-openapi.yaml#/paths to community-openapi.yaml#/paths correctly separates edition-specific surfaces. The previous Dockerfile issue (missing COPY openapi/plugins and version bump) was addressed in c23d3a1.

The one medium-severity finding is that CI does not exercise the new customer-filter plugin or the per-edition specs — see the inline comment for details and a suggested smoke-test step.

---

To request another review round, comment /review.

[gustavosbarreto]

/review

[github-actions]

Claude finished @gustavosbarreto's task in 2m 28s —— View job

---

Code Review Complete

Reviewed 75 files across code quality, security, testing, Go/JS patterns, and architecture — no issues found.

The design is clean and well-implemented. The customer-filter.js decorator logic correctly gates on three conditions (path prefix, api-key scheme, x-internal flag) and the filtering, tag pruning, and JWT stripping all work as intended. The security: [] additions (healthcheck, MFA, accept-invite) correctly reflect routes that authenticate via other mechanisms. The api-key additions to SSH public key write operations match the Go handlers (no BlockAPIKey middleware on those routes). The api-key removals from billing, auth, namespace-delete, and offline routes align with Go handler behavior (BlockAPIKey or owner-only permissions). The enterprise $ref change from cloud-openapi.yaml#/paths to community-openapi.yaml#/paths correctly separates edition surfaces, matching the AddSharedRoutes/AddCloudOnlyRoutes/AddEnterpriseOnlyRoutes split in the Go code. The session route spec change (POST /api/sessions/{uid} → PATCH /internal/sessions/{uid}) matches the existing Go implementation (internalAPI.PATCH at routes.go:111). Both issues from prior review rounds (Dockerfile missing plugins/ copy, CI not exercising customer specs) were addressed in subsequent commits.

---

To request another review round, comment /review.