gsadmin/certctl
1
0
Fork 0
mirror of https://github.com/shankar0123/certctl.git synced 2026-06-07 21:01:31 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
30940108808ec7a8d9b483e0a7dfefdb8cd9c89e
certctl/api/openapi-handler-exceptions.yaml
T
shankar0123 3c81531398 ci: OpenAPI parity reconciliation + codegen scaffolding (Phase 5 — ARCH-H1 / ARCH-M6) 
Phase 5 reconciliation: the audit's headline framing 'ARCH-H1 = 62-route
OpenAPI gap' was a measurement scoping error. Every one of the 209
unique router routes is already accounted for — 154 in api/openapi.yaml,
55 in api/openapi-handler-exceptions.yaml. The existing
openapi-handler-parity.sh CI guard already enforces this and passes
clean today. The audit subtracted operation-count from route-count
without accounting for the documented exceptions YAML.

Where real work remains (and what this PR does about it)
=========================================================

Of the 64 documented exceptions, 35 are legitimate wire-protocol
carve-outs that MUST stay (SCEP RFC 8894 × 8 entries, ACME RFC 8555
default + per-profile × 27 entries — they're protocol contracts, not
REST resources). The remaining 29 are REST-shaped routes whose
OpenAPI ops were deferred during their original Bundle 2 /
audit-2026-05-10 / 2026-05-11 work:

  - auth/sessions (3)
  - auth/oidc admin (9)
  - auth/breakglass admin (4)
  - auth/users mgmt (3)
  - auth/runtime-config (1)
  - auth/demo-residual/cleanup (1)
  - audit/export (1)
  - auth/logout (1)
  - auth/breakglass/login (1)
  - auth/oidc {login,callback,bcl} (3)
  - oidc/providers/{id}/jwks-status (1)
  - + 2 other auth-flow routes

Burn-down plan in 3 sprints (documented in
api/openapi-handler-exceptions.yaml header):
  Sprint A: Cluster 1 — sessions + oidc admin (12 ops)
  Sprint B: Cluster 2 — breakglass + users + runtime-config (8 ops)
  Sprint C: Cluster 3 — audit/export + auth flows (9 ops)

This PR does NOT author the 29 OpenAPI ops; each needs request/
response schemas, not placeholders, and the design work is too
large for one PR. The reconciliation here is documentation + a CI
guard that will fail any future schema-drift, plus the scaffolding
needed for sub-phase 5b.

Sub-phase 5b: codegen scaffolding
==================================

Adds the orval scaffolding without running npm install (sandbox
disk-full; first 'npm install' + 'npm run generate' happens on the
operator's workstation):

  - web/orval.config.ts — codegen config emits react-query hooks
    from api/openapi.yaml into web/src/api/generated/
  - web/package.json — adds orval@^7.0.0 devDep + 'generate' npm script
  - web/CODEGEN.md — operator-facing migration doc:
    first-time setup, per-consumer migration pattern, burn-down plan,
    CI-guard rules
  - scripts/ci-guards/openapi-codegen-drift.sh — blocks the build
    when api/openapi.yaml changes but web/src/api/generated/ wasn't
    regenerated alongside. Currently no-op (the directory doesn't
    exist yet); activates from the first 'npm run generate' run.

The legacy web/src/api/client.ts stays in tree per the phase prompt's
'do not delete in same PR as codegen' rule. Consumers migrate one
page at a time as their OpenAPI ops land; client.ts deletion is a
SEPARATE follow-up PR after the last consumer migrates.

Updates to existing guard + exceptions YAML
============================================

  - scripts/ci-guards/openapi-handler-parity.sh header rewritten
    with the Phase 5 reconciliation numbers (220/158/64/0) and the
    wire-protocol vs REST-deferred classification.
  - api/openapi-handler-exceptions.yaml header rewritten with the
    35/29 split + the 3-sprint burn-down plan. Each exception entry
    is unchanged; the header now documents which entries are
    permanent (wire-protocol) vs temporary (REST-deferred).

Sandbox limitations + operator follow-up
=========================================

  - 'npm install' was NOT run from the sandbox (sessions volume
    99%-full, 142 MB free). The operator runs 'cd web && npm install'
    on their workstation; this lands orval@^7.0.0 in node_modules,
    then 'cd web && npm run generate' produces the initial
    web/src/api/generated/ tree.
  - First per-consumer migration (suggested: web/src/pages/AuthSettings
    or one of the operator-decision pages) lands in a follow-up PR
    after npm install completes.
  - The 29-op OpenAPI burn-down is a 2-sprint effort tracked under
    ARCH-H1 in cowork/certctl-architecture-diligence-audit.html.

All CI guards (openapi-handler-parity, openapi-codegen-drift, plus
every existing guard) verified clean by running each individually.

Closes:
  - cowork/certctl-architecture-diligence-audit.html#fix-ARCH-H1
    (reconciliation: gap is 0 with exceptions accounted for; burn-down
    plan documented for follow-up sprints)
  - cowork/certctl-architecture-diligence-audit.html#fix-ARCH-M6
    (codegen scaffolding shipped; client.ts deletion follows in a
    subsequent PR after consumers migrate)
2026-05-13 20:24:20 +00:00

178 lines
10 KiB
YAML
Raw Blame History

# Routes registered in internal/api/router/router.go that are intentionally
# NOT in api/openapi.yaml. Each entry needs a one-line `why:` justification.
# Adding a new entry requires PR-time review.
#
# OpenAPI-shaped REST endpoints belong in api/openapi.yaml, NOT here.
# This list is for protocol-shaped (SCEP wire endpoints) and operational
# (health, metrics, pprof) routes only.
#
# Per ci-pipeline-cleanup bundle Phase 9 / frozen decision 0.11.
#
# Phase 5 reconciliation (2026-05-13, architecture diligence audit
# ARCH-H1): of the 64 entries below, 35 are legitimate wire-protocol
# carve-outs (SCEP RFC 8894 = 8 entries, ACME RFC 8555 default + per-
# profile = 27 entries) that MUST stay. The remaining 29 are REST-
# shaped routes whose OpenAPI ops were deferred during their original
# Bundle 2 / audit-2026-05-10 / 2026-05-11 work. Burn-down plan:
#
# Sprint A (per-cluster, ~7-8 ops each):
# Cluster 1: auth/sessions + auth/oidc (12 ops)
# Cluster 2: auth/breakglass + auth/users + auth/runtime-config (8 ops)
# Cluster 3: audit/export + demo-residual/cleanup + auth/logout +
# auth/breakglass/login + auth/oidc/{login,callback,bcl} (9 ops)
#
# Each authored OpenAPI op needs request/response schemas (not
# placeholders) so the generated client at web/orval.config.ts emits
# typed signatures. When an op lands, delete the corresponding entry
# below + bump the openapi-handler-parity.sh expected counts.
documented_exceptions:
- route: "GET /scep"
why: "SCEP wire-protocol endpoint per RFC 8894 §3.1; serves CA certs via GetCACert/GetCACaps query params, NOT a REST resource."
- route: "POST /scep"
why: "SCEP wire-protocol endpoint per RFC 8894 §3.1; receives PKCSReq / RenewalReq PKIMessages, NOT a REST resource."
- route: "GET /scep/"
why: "SCEP wire-protocol endpoint with trailing-slash variant; ChromeOS clients send the trailing-slash form."
- route: "POST /scep/"
why: "SCEP wire-protocol endpoint with trailing-slash variant; ChromeOS clients send the trailing-slash form."
- route: "GET /scep-mtls"
why: "SCEP-mTLS sibling endpoint per ci-pipeline-cleanup-prerequisite EST RFC 7030 hardening Phase 6.5; same wire-protocol semantics, mutually-authenticated TLS variant."
- route: "POST /scep-mtls"
why: "SCEP-mTLS sibling endpoint, POST variant."
- route: "GET /scep-mtls/"
why: "SCEP-mTLS sibling endpoint, trailing-slash variant."
- route: "POST /scep-mtls/"
why: "SCEP-mTLS sibling endpoint, trailing-slash POST variant."
# ACME server (RFC 8555 + RFC 9773 ARI) — wire-protocol surface.
# Like SCEP/EST, ACME is a JWS-signed-JSON wire protocol whose
# semantics are dictated by the RFC, not by an OpenAPI schema.
# Documenting every endpoint in openapi.yaml would duplicate
# RFC 8555 §7.1 + §7.2 + §7.3 with no information gain. The
# canonical operator-facing reference is docs/acme-server.md.
# Phases 2-4 will extend this list as new-order, finalize, authz,
# challenge, cert, key-change, revoke-cert, renewal-info routes land.
- route: "GET /acme/profile/{id}/directory"
why: "ACME server RFC 8555 §7.1.1 directory; documented in docs/acme-server.md."
- route: "HEAD /acme/profile/{id}/new-nonce"
why: "ACME server RFC 8555 §7.2 new-nonce; documented in docs/acme-server.md."
- route: "GET /acme/profile/{id}/new-nonce"
why: "ACME server RFC 8555 §7.2 new-nonce GET form; documented in docs/acme-server.md."
- route: "POST /acme/profile/{id}/new-account"
why: "ACME server RFC 8555 §7.3 new-account (JWS jwk); documented in docs/acme-server.md."
- route: "POST /acme/profile/{id}/account/{acc_id}"
why: "ACME server RFC 8555 §7.3.2 + §7.3.6 (JWS kid) account update + deactivation; documented in docs/acme-server.md."
- route: "GET /acme/directory"
why: "ACME server default-profile shorthand; mirrors per-profile when CERTCTL_ACME_SERVER_DEFAULT_PROFILE_ID is set."
- route: "HEAD /acme/new-nonce"
why: "ACME server default-profile shorthand for new-nonce HEAD."
- route: "GET /acme/new-nonce"
why: "ACME server default-profile shorthand for new-nonce GET."
- route: "POST /acme/new-account"
why: "ACME server default-profile shorthand for new-account."
- route: "POST /acme/account/{acc_id}"
why: "ACME server default-profile shorthand for account update + deactivation."
# Phase 2 — orders + finalize + authz + cert.
- route: "POST /acme/profile/{id}/new-order"
why: "ACME server RFC 8555 §7.4 new-order; documented in docs/acme-server.md."
- route: "POST /acme/profile/{id}/order/{ord_id}"
why: "ACME server RFC 8555 §7.4 order POST-as-GET; documented in docs/acme-server.md."
- route: "POST /acme/profile/{id}/order/{ord_id}/finalize"
why: "ACME server RFC 8555 §7.4 finalize; documented in docs/acme-server.md."
- route: "POST /acme/profile/{id}/authz/{authz_id}"
why: "ACME server RFC 8555 §7.5 authz POST-as-GET; documented in docs/acme-server.md."
- route: "POST /acme/profile/{id}/challenge/{chall_id}"
why: "ACME server RFC 8555 §7.5.1 challenge response; dispatches to Phase 3 validator pool."
- route: "POST /acme/profile/{id}/cert/{cert_id}"
why: "ACME server RFC 8555 §7.4.2 cert download; documented in docs/acme-server.md."
- route: "POST /acme/new-order"
why: "Phase 2 default-profile shorthand for new-order."
- route: "POST /acme/order/{ord_id}"
why: "Phase 2 default-profile shorthand for order POST-as-GET."
- route: "POST /acme/order/{ord_id}/finalize"
why: "Phase 2 default-profile shorthand for finalize."
- route: "POST /acme/authz/{authz_id}"
why: "Phase 2 default-profile shorthand for authz POST-as-GET."
- route: "POST /acme/challenge/{chall_id}"
why: "Phase 3 default-profile shorthand for challenge response."
- route: "POST /acme/cert/{cert_id}"
why: "Phase 2 default-profile shorthand for cert download."
- route: "POST /acme/profile/{id}/key-change"
why: "ACME server RFC 8555 §7.3.5 doubly-signed key rollover; documented in docs/acme-server.md."
- route: "POST /acme/profile/{id}/revoke-cert"
why: "ACME server RFC 8555 §7.6 revoke-cert (kid OR cert-key auth); documented in docs/acme-server.md."
- route: "GET /acme/profile/{id}/renewal-info/{cert_id}"
why: "ACME server RFC 9773 ACME Renewal Information (unauthenticated GET); documented in docs/acme-server.md."
- route: "POST /acme/key-change"
why: "Phase 4 default-profile shorthand for key rollover."
- route: "POST /acme/revoke-cert"
why: "Phase 4 default-profile shorthand for revoke-cert."
- route: "GET /acme/renewal-info/{cert_id}"
why: "Phase 4 default-profile shorthand for ARI."
# =============================================================================
# Auth Bundle 2 + audit-2026-05-10/11 fix bundle — REST endpoints not yet
# represented in api/openapi.yaml. These are operator-facing REST endpoints
# (not protocol-shaped); the OpenAPI surface is scheduled to land pre-v2.2.0
# alongside the GUI E2E coverage push. Documented here so the parity guard
# stays green for the v2.1.0 release tag. Threat model + handler contracts
# live in docs/operator/{rbac.md,auth-threat-model.md,oidc-runbooks/*}.
# =============================================================================
- route: "GET /auth/oidc/login"
why: "Bundle 2 Phase 5 OIDC login redirect; user-facing 302 with state cookie. OpenAPI rep deferred to pre-2.2.0."
- route: "GET /auth/oidc/callback"
why: "Bundle 2 Phase 5 OIDC callback handler; RFC 9700 §4.7.1 + RFC 9207. OpenAPI rep deferred to pre-2.2.0."
- route: "POST /auth/logout"
why: "Bundle 2 Phase 5 cookie + CSRF revoker. OpenAPI rep deferred to pre-2.2.0."
- route: "POST /auth/breakglass/login"
why: "Bundle 2 Phase 7.5 public break-glass login (auth-bypass, 404 when disabled). OpenAPI rep deferred to pre-2.2.0."
- route: "POST /auth/oidc/back-channel-logout"
why: "Bundle 2 Phase 5 RFC OIDC Back-Channel Logout 1.0 endpoint. OpenAPI rep deferred to pre-2.2.0."
- route: "GET /api/v1/auth/sessions"
why: "Bundle 2 Phase 5 self/admin session list. OpenAPI rep deferred to pre-2.2.0."
- route: "DELETE /api/v1/auth/sessions/{id}"
why: "Bundle 2 Phase 5 session revoke. OpenAPI rep deferred to pre-2.2.0."
- route: "DELETE /api/v1/auth/sessions"
why: "Bundle 2 audit-2026-05-10 MED-2/3 revoke-all-except-current."
- route: "GET /api/v1/auth/oidc/providers"
why: "Bundle 2 Phase 5 OIDC provider CRUD (list)."
- route: "POST /api/v1/auth/oidc/providers"
why: "Bundle 2 Phase 5 OIDC provider CRUD (create)."
- route: "PUT /api/v1/auth/oidc/providers/{id}"
why: "Bundle 2 Phase 5 OIDC provider CRUD (update)."
- route: "DELETE /api/v1/auth/oidc/providers/{id}"
why: "Bundle 2 Phase 5 OIDC provider CRUD (delete)."
- route: "POST /api/v1/auth/oidc/providers/{id}/refresh"
why: "Bundle 2 audit-2026-05-10 MED-7 JWKS hot-refresh."
- route: "GET /api/v1/auth/oidc/providers/{id}/jwks-status"
why: "Bundle 2 audit-2026-05-10 MED-7 JWKS health snapshot."
- route: "POST /api/v1/auth/oidc/test"
why: "Bundle 2 audit-2026-05-10 MED-5 dry-run discovery + JWKS + alg-downgrade check."
- route: "GET /api/v1/auth/oidc/group-mappings"
why: "Bundle 2 Phase 5 group-mapping CRUD (list)."
- route: "POST /api/v1/auth/oidc/group-mappings"
why: "Bundle 2 Phase 5 group-mapping CRUD (create)."
- route: "DELETE /api/v1/auth/oidc/group-mappings/{id}"
why: "Bundle 2 Phase 5 group-mapping CRUD (delete)."
- route: "GET /api/v1/auth/breakglass/credentials"
why: "Bundle 2 Phase 7.5 admin break-glass list (404 when disabled; password hash never on wire)."
- route: "POST /api/v1/auth/breakglass/credentials"
why: "Bundle 2 Phase 7.5 admin break-glass set/rotate password."
- route: "POST /api/v1/auth/breakglass/credentials/{actor_id}/unlock"
why: "Bundle 2 Phase 7.5 admin break-glass unlock after lockout."
- route: "DELETE /api/v1/auth/breakglass/credentials/{actor_id}"
why: "Bundle 2 Phase 7.5 admin break-glass credential delete."
- route: "GET /api/v1/auth/users"
why: "Bundle 2 audit-2026-05-10 MED-11 users page."
- route: "DELETE /api/v1/auth/users/{id}"
why: "Bundle 2 audit-2026-05-10 MED-11 user deactivate."
- route: "POST /api/v1/auth/users/{id}/reactivate"
why: "Bundle 2 audit-2026-05-10 MED-11 user reactivate."
- route: "GET /api/v1/auth/runtime-config"
why: "Bundle 2 audit-2026-05-10 MED-12 effective auth-runtime-config (read-only)."
- route: "POST /api/v1/auth/demo-residual/cleanup"
why: "Audit 2026-05-11 A-8 demo-mode residual-grants cleanup endpoint."
- route: "GET /api/v1/audit/export"
why: "Bundle 1 Phase 8 streaming NDJSON audit export."
Reference in New Issue View Git Blame Copy Permalink