mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 15:01:32 +00:00
shankar0123
952682ebec
Phase 13 Sprint 13.4 closure (architecture diligence audit ARCH-H1):
authors OpenAPI operations for the auth/sessions cluster (3) +
auth/oidc CRUD + JWKS + test + refresh cluster (10), drives the
`rest-deferred` exception bucket from 28 → 15.
OpenAPI-only sprint: zero Go changes. Every schema field-by-field
mirrors the projection types in the Phase 9 Sprint 11 sibling-file
handlers (auth_session_oidc_{sessions,crud}.go) + the JWKS-status
surface in auth_users.go + the dry-run discovery result in
internal/auth/oidc/test_discovery.go.
13 new operations
=================
Sessions cluster (3 ops):
GET /api/v1/auth/sessions listAuthSessions
DELETE /api/v1/auth/sessions revokeAuthSessionsExceptCurrent
DELETE /api/v1/auth/sessions/{id} revokeAuthSession
OIDC provider CRUD + JWKS + test + refresh (7 ops):
GET /api/v1/auth/oidc/providers listOIDCProviders
POST /api/v1/auth/oidc/providers createOIDCProvider
PUT /api/v1/auth/oidc/providers/{id} updateOIDCProvider
DELETE /api/v1/auth/oidc/providers/{id} deleteOIDCProvider
GET /api/v1/auth/oidc/providers/{id}/jwks-status getOIDCProviderJWKSStatus
POST /api/v1/auth/oidc/providers/{id}/refresh refreshOIDCProvider
POST /api/v1/auth/oidc/test testOIDCProvider
OIDC group-mapping CRUD (3 ops):
GET /api/v1/auth/oidc/group-mappings listOIDCGroupMappings
POST /api/v1/auth/oidc/group-mappings addOIDCGroupMapping
DELETE /api/v1/auth/oidc/group-mappings/{id} removeOIDCGroupMapping
8 new schemas (components/schemas)
==================================
AuthSession — mirrors sessionResponse (10 fields).
OIDCProviderResponse — mirrors oidcProviderResponse (15 fields).
OIDCProviderRequest — mirrors oidcProviderRequest (12 fields,
client_secret marked password).
OIDCTestRequest — mirrors the inline struct in TestProvider
(4 fields).
OIDCTestDiscoveryResult — mirrors oidc.TestDiscoveryResult
(11 fields).
OIDCJWKSStatusSnapshot — mirrors oidc.JWKSStatusSnapshot (7
fields).
OIDCGroupMappingResponse — mirrors groupMappingResponse (6 fields).
OIDCGroupMappingRequest — mirrors groupMappingRequest (3 fields,
tenant_id deliberately excluded — derived
from caller).
Every schema field's JSON tag, type, required-ness, and (where
applicable) description grounded against the Go source byte-for-byte.
Pointer types in Go that the handler marshals via `omitempty` are
modelled as optional fields in the YAML (not present in the
`required` list).
RBAC permissions documented per-operation in the description (matched
against rbacGate wraps in internal/api/router/router.go lines 516-540):
auth.session.list, auth.session.list.all, auth.session.revoke,
auth.oidc.list, auth.oidc.create, auth.oidc.edit, auth.oidc.delete.
New tags
========
Added `Sessions` and `OIDC` to the `tags:` list with cross-references
to the handler file paths. Existing operations stay on existing tags;
the new ones declare the new tags.
Exception YAML + baseline
=========================
13 entries removed from api/openapi-handler-exceptions.yaml. The
post-cut shape:
total entries: 51 (was 64)
wire-protocol: 36 (unchanged — never burn down)
rest-deferred: 15 (was 28)
Baseline file bumped 28 → 15. The Sprint 13.1 monotonic-decrease
guard now pins `rest-deferred ≤ 15`. Sprints 13.5 + 13.6 walk it down
to zero (15 → 7 → 0).
YAML header narrative updated to reflect Sprint 13.4 status:
"Sprint 13.4 SHIPPED — 28 - 13 = 15".
Receipts (all from the live tree)
=================================
$ grep -cE '^\s+operationId:' api/openapi.yaml
171 (was 158 + 13)
$ bash scripts/ci-guards/openapi-handler-parity.sh
Router routes: 220
OpenAPI operations: 171
Documented exceptions: 51
wire-protocol: 36
rest-deferred: 15
openapi-handler-parity: clean.
$ bash scripts/ci-guards/openapi-rest-deferred-monotonic.sh
openapi-rest-deferred-monotonic: clean — rest-deferred = 15,
baseline = 15.
$ cat api/openapi-handler-exceptions-baseline.txt
15
$ python3 -c "import yaml; spec=yaml.safe_load(open('api/openapi.yaml')); ..."
paths: 126, operations: 171
components.schemas: 67
sprint-13.4 schemas missing: (none)
OpenAPI lint: clean.
$ gofmt -l . → clean
$ go vet ./internal/api/handler/... ./cmd/server/... → clean
Sprint 13.5 next (auth/breakglass + auth/users + auth/runtime-config,
8 ops; rest-deferred 15 → 7). Same OpenAPI-only authoring pattern; no
Go changes.
Refs: ARCH-H1 batch 1 closure.
244 lines
13 KiB
YAML
244 lines
13 KiB
YAML
# Routes registered in internal/api/router/router.go that are intentionally
|
|
# NOT in api/openapi.yaml. Each entry needs a one-line `why:` justification
|
|
# AND a required `category:` field (added in Phase 13 Sprint 13.1,
|
|
# 2026-05-14, architecture diligence audit ARCH-H1).
|
|
#
|
|
# 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/ACME/EST wire endpoints) and
|
|
# operational (health, metrics, pprof) routes only.
|
|
#
|
|
# Per ci-pipeline-cleanup bundle Phase 9 / frozen decision 0.11.
|
|
#
|
|
# ──────────────────────────────────────────────────────────────────────
|
|
# The two-bucket contract (Phase 13 Sprint 13.1)
|
|
# ──────────────────────────────────────────────────────────────────────
|
|
#
|
|
# category: wire-protocol
|
|
# The route's wire shape is dictated by an IETF RFC (SCEP RFC 8894,
|
|
# ACME RFC 8555, ACME ARI RFC 9773, EST RFC 7030) or it's a
|
|
# sibling/shorthand variant of such a route (same wire semantics,
|
|
# different cosmetic path — e.g. trailing-slash forms, default-
|
|
# profile shorthands). Documenting these as REST operations in
|
|
# openapi.yaml would duplicate the RFC with no information gain;
|
|
# the canonical operator references live in docs/acme-server.md +
|
|
# docs/operator/scep.md + docs/operator/est.md. These entries
|
|
# NEVER burn down — they're protocol contracts, not gaps.
|
|
#
|
|
# category: rest-deferred
|
|
# The route is REST-shaped (resource CRUD, JSON request/response,
|
|
# RBAC-gated) but its OpenAPI operation was deferred when the
|
|
# handler shipped. These MUST monotonically decrease to zero.
|
|
# Phase 13 Sprints 13.4-13.6 author the OpenAPI ops + delete the
|
|
# corresponding exception entries; the
|
|
# openapi-rest-deferred-monotonic.sh CI guard fails any PR that
|
|
# grows the rest-deferred bucket vs the checked-in baseline at
|
|
# api/openapi-handler-exceptions-baseline.txt.
|
|
#
|
|
# ──────────────────────────────────────────────────────────────────────
|
|
# Phase 13 Sprint 13.1 categorization (2026-05-14)
|
|
# ──────────────────────────────────────────────────────────────────────
|
|
#
|
|
# Current split, re-derived by the parity script's bucket-reporting
|
|
# subcommand (post-Sprint-13.4 / 2026-05-14):
|
|
#
|
|
# total entries: 51
|
|
# wire-protocol: 36
|
|
# rest-deferred: 15
|
|
#
|
|
# Burn-down progress + remaining plan for the rest-deferred bucket:
|
|
#
|
|
# Sprint 13.4 SHIPPED — 28 - 13 = 15 (auth/sessions cluster 3 ops +
|
|
# auth/oidc CRUD + JWKS + test + refresh
|
|
# + group-mappings cluster, 10 ops)
|
|
# Sprint 13.5 → 15 - 8 = 7 (auth/breakglass + auth/users +
|
|
# auth/runtime-config, 8 ops)
|
|
# Sprint 13.6 → 7 - 7 = 0 (audit/export + demo-residual + 3
|
|
# OIDC browser flows + auth/logout +
|
|
# auth/breakglass/login, 7 ops)
|
|
#
|
|
# Sprint 13.7 then tightens the parity-script's rest-deferred floor
|
|
# from monotonic-decrease to a hard zero-exact pin. After that, any
|
|
# new REST route MUST land with an OpenAPI op or fail CI.
|
|
#
|
|
# 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 api/openapi-handler-exceptions-baseline.txt downward.
|
|
|
|
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."
|
|
category: wire-protocol
|
|
- route: "POST /scep"
|
|
why: "SCEP wire-protocol endpoint per RFC 8894 §3.1; receives PKCSReq / RenewalReq PKIMessages, NOT a REST resource."
|
|
category: wire-protocol
|
|
- route: "GET /scep/"
|
|
why: "SCEP wire-protocol endpoint with trailing-slash variant; ChromeOS clients send the trailing-slash form."
|
|
category: wire-protocol
|
|
- route: "POST /scep/"
|
|
why: "SCEP wire-protocol endpoint with trailing-slash variant; ChromeOS clients send the trailing-slash form."
|
|
category: wire-protocol
|
|
- 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."
|
|
category: wire-protocol
|
|
- route: "POST /scep-mtls"
|
|
why: "SCEP-mTLS sibling endpoint, POST variant."
|
|
category: wire-protocol
|
|
- route: "GET /scep-mtls/"
|
|
why: "SCEP-mTLS sibling endpoint, trailing-slash variant."
|
|
category: wire-protocol
|
|
- route: "POST /scep-mtls/"
|
|
why: "SCEP-mTLS sibling endpoint, trailing-slash POST variant."
|
|
category: wire-protocol
|
|
|
|
# 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."
|
|
category: wire-protocol
|
|
- route: "HEAD /acme/profile/{id}/new-nonce"
|
|
why: "ACME server RFC 8555 §7.2 new-nonce; documented in docs/acme-server.md."
|
|
category: wire-protocol
|
|
- route: "GET /acme/profile/{id}/new-nonce"
|
|
why: "ACME server RFC 8555 §7.2 new-nonce GET form; documented in docs/acme-server.md."
|
|
category: wire-protocol
|
|
- route: "POST /acme/profile/{id}/new-account"
|
|
why: "ACME server RFC 8555 §7.3 new-account (JWS jwk); documented in docs/acme-server.md."
|
|
category: wire-protocol
|
|
- 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."
|
|
category: wire-protocol
|
|
- route: "GET /acme/directory"
|
|
why: "ACME server default-profile shorthand; mirrors per-profile when CERTCTL_ACME_SERVER_DEFAULT_PROFILE_ID is set."
|
|
category: wire-protocol
|
|
- route: "HEAD /acme/new-nonce"
|
|
why: "ACME server default-profile shorthand for new-nonce HEAD."
|
|
category: wire-protocol
|
|
- route: "GET /acme/new-nonce"
|
|
why: "ACME server default-profile shorthand for new-nonce GET."
|
|
category: wire-protocol
|
|
- route: "POST /acme/new-account"
|
|
why: "ACME server default-profile shorthand for new-account."
|
|
category: wire-protocol
|
|
- route: "POST /acme/account/{acc_id}"
|
|
why: "ACME server default-profile shorthand for account update + deactivation."
|
|
category: wire-protocol
|
|
|
|
# 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."
|
|
category: wire-protocol
|
|
- 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."
|
|
category: wire-protocol
|
|
- route: "POST /acme/profile/{id}/order/{ord_id}/finalize"
|
|
why: "ACME server RFC 8555 §7.4 finalize; documented in docs/acme-server.md."
|
|
category: wire-protocol
|
|
- 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."
|
|
category: wire-protocol
|
|
- route: "POST /acme/profile/{id}/challenge/{chall_id}"
|
|
why: "ACME server RFC 8555 §7.5.1 challenge response; dispatches to Phase 3 validator pool."
|
|
category: wire-protocol
|
|
- route: "POST /acme/profile/{id}/cert/{cert_id}"
|
|
why: "ACME server RFC 8555 §7.4.2 cert download; documented in docs/acme-server.md."
|
|
category: wire-protocol
|
|
- route: "POST /acme/new-order"
|
|
why: "Phase 2 default-profile shorthand for new-order."
|
|
category: wire-protocol
|
|
- route: "POST /acme/order/{ord_id}"
|
|
why: "Phase 2 default-profile shorthand for order POST-as-GET."
|
|
category: wire-protocol
|
|
- route: "POST /acme/order/{ord_id}/finalize"
|
|
why: "Phase 2 default-profile shorthand for finalize."
|
|
category: wire-protocol
|
|
- route: "POST /acme/authz/{authz_id}"
|
|
why: "Phase 2 default-profile shorthand for authz POST-as-GET."
|
|
category: wire-protocol
|
|
- route: "POST /acme/challenge/{chall_id}"
|
|
why: "Phase 3 default-profile shorthand for challenge response."
|
|
category: wire-protocol
|
|
- route: "POST /acme/cert/{cert_id}"
|
|
why: "Phase 2 default-profile shorthand for cert download."
|
|
category: wire-protocol
|
|
- 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."
|
|
category: wire-protocol
|
|
- 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."
|
|
category: wire-protocol
|
|
- 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."
|
|
category: wire-protocol
|
|
- route: "POST /acme/key-change"
|
|
why: "Phase 4 default-profile shorthand for key rollover."
|
|
category: wire-protocol
|
|
- route: "POST /acme/revoke-cert"
|
|
why: "Phase 4 default-profile shorthand for revoke-cert."
|
|
category: wire-protocol
|
|
- route: "GET /acme/renewal-info/{cert_id}"
|
|
why: "Phase 4 default-profile shorthand for ARI."
|
|
category: wire-protocol
|
|
|
|
# =============================================================================
|
|
# 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."
|
|
category: rest-deferred
|
|
- 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."
|
|
category: rest-deferred
|
|
- route: "POST /auth/logout"
|
|
why: "Bundle 2 Phase 5 cookie + CSRF revoker. OpenAPI rep deferred to pre-2.2.0."
|
|
category: rest-deferred
|
|
- 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."
|
|
category: rest-deferred
|
|
- 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."
|
|
category: rest-deferred
|
|
- 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)."
|
|
category: rest-deferred
|
|
- route: "POST /api/v1/auth/breakglass/credentials"
|
|
why: "Bundle 2 Phase 7.5 admin break-glass set/rotate password."
|
|
category: rest-deferred
|
|
- route: "POST /api/v1/auth/breakglass/credentials/{actor_id}/unlock"
|
|
why: "Bundle 2 Phase 7.5 admin break-glass unlock after lockout."
|
|
category: rest-deferred
|
|
- route: "DELETE /api/v1/auth/breakglass/credentials/{actor_id}"
|
|
why: "Bundle 2 Phase 7.5 admin break-glass credential delete."
|
|
category: rest-deferred
|
|
- route: "GET /api/v1/auth/users"
|
|
why: "Bundle 2 audit-2026-05-10 MED-11 users page."
|
|
category: rest-deferred
|
|
- route: "DELETE /api/v1/auth/users/{id}"
|
|
why: "Bundle 2 audit-2026-05-10 MED-11 user deactivate."
|
|
category: rest-deferred
|
|
- route: "POST /api/v1/auth/users/{id}/reactivate"
|
|
why: "Bundle 2 audit-2026-05-10 MED-11 user reactivate."
|
|
category: rest-deferred
|
|
- route: "GET /api/v1/auth/runtime-config"
|
|
why: "Bundle 2 audit-2026-05-10 MED-12 effective auth-runtime-config (read-only)."
|
|
category: rest-deferred
|
|
- route: "POST /api/v1/auth/demo-residual/cleanup"
|
|
why: "Audit 2026-05-11 A-8 demo-mode residual-grants cleanup endpoint."
|
|
category: rest-deferred
|
|
- route: "GET /api/v1/audit/export"
|
|
why: "Bundle 1 Phase 8 streaming NDJSON audit export."
|
|
category: rest-deferred
|