mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 15:11:29 +00:00
shankar0123
29cb13e7a2
Phase 13 Sprint 13.6 — the FINAL ARCH-H1 OpenAPI authoring batch.
Closes the substantive burn-down: rest-deferred bucket reaches 0;
every REST-shaped router route is now authored into openapi.yaml.
Documented exceptions are exclusively wire-protocol contracts (SCEP
RFC 8894, ACME RFC 8555, ACME ARI RFC 9773, EST RFC 7030).
Sprint 13.7 next (closure / audit-HTML flip) tightens this commit's
floor: the rest-deferred bucket pin in
openapi-rest-deferred-monotonic.sh changes from
"monotonic-decrease vs baseline" to "hard zero-exact" so a future
PR adding a REST route MUST author its OpenAPI op or fail CI — the
`category: rest-deferred` escape hatch closes for good.
7 new operations (the final batch)
==================================
One-off REST endpoints (4 ops):
GET /api/v1/audit/export exportAudit (audit.export — NDJSON stream)
POST /api/v1/auth/demo-residual/cleanup cleanupDemoResidualGrants (auth.role.assign; 503 in demo mode)
POST /auth/logout logoutCurrentSession (auth-exempt; cookie checked inside)
POST /auth/breakglass/login breakglassLogin (auth-bypass; 404 when disabled; rate-limited)
OIDC browser-flow endpoints (3 ops, modeled as 302+Location-header
redirects per OAS 3.1 — `responses.302` + `headers.Location` +
description noting the server-initiated redirect contract; empty
content block; consumers must follow the redirect for the flow to
complete):
GET /auth/oidc/login oidcLoginInitiate (auth-exempt; 302 → IdP authz URL + pre-login cookie)
GET /auth/oidc/callback oidcLoginCallback (auth-exempt; 302 → postLoginURL on success / 302 → /login?error=oidc_failed&reason=<cat> on failure)
POST /auth/oidc/back-channel-logout oidcBackChannelLogout (auth via IdP-signed logout_token; 200 + Cache-Control: no-store on success; uniform 400 per spec §2.6 on failure)
The 4 one-off REST endpoints model standard JSON contracts. The 3
OIDC browser-flow endpoints DELIBERATELY model the 302-with-Location
contract because that's the live wire shape — modeling them as
200-with-JSON would lie about reality (and break any generated
client that assumes a JSON response body). Each `headers.Location`
is documented with the actual redirect target shape (provider authz
URL / postLoginURL / /login?error=oidc_failed&reason=<category>).
Audit/export NDJSON streaming
=============================
The audit/export response is `application/x-ndjson` — one JSON-
encoded AuditEvent per line, NOT a single JSON document. Documented
explicitly so generated clients know to parse line-by-line. Schema
references the existing #/components/schemas/AuditEvent (already
defined as part of the audit-events surface).
Range cap + per-record cap + filter shape all documented in the
parameters block (90-day max window, 1..100000 limit, category enum
of cert_lifecycle/auth/config).
2 new schemas (components/schemas)
==================================
DemoResidualCleanupResponse — mirrors demoResidualCleanupResponse
({removed: int64}).
BreakglassLoginRequest — mirrors breakglassLoginRequest
(actor_id + password; password
marked `format: password`).
Pre-existing AuditEvent + BreakglassLoginRequest-adjacent schemas
(Sprint 13.4 + 13.5) are referenced via $ref without duplication.
Exception YAML + baseline + zero-floor pin
==========================================
7 entries removed from api/openapi-handler-exceptions.yaml. Post-cut
shape:
total entries: 36
wire-protocol: 36 (unchanged — these never burn down)
rest-deferred: 0 ← THE FLOOR
Baseline file bumped 7 → 0. The Sprint 13.1 monotonic-decrease
guard now pins `rest-deferred ≤ 0` — equivalent to "the bucket
must stay empty." Sprint 13.7 will additionally tighten the
parity-script's missing-category check so the bucket can't be
re-grown via the `category:` typo escape hatch either.
YAML header narrative updated: "Sprint 13.6 SHIPPED — 7 - 7 = 0".
ARCH-H1 substantive close achieved at the bucket-math level.
Receipts (all from the live tree)
=================================
$ grep -cE '^\s+operationId:' api/openapi.yaml
186 (was 179 + 7)
$ bash scripts/ci-guards/openapi-handler-parity.sh
Router routes: 220
OpenAPI operations: 186
Documented exceptions: 36
wire-protocol: 36
rest-deferred: 0
openapi-handler-parity: clean.
$ bash scripts/ci-guards/openapi-rest-deferred-monotonic.sh
openapi-rest-deferred-monotonic: clean — rest-deferred = 0,
baseline = 0.
$ cat api/openapi-handler-exceptions-baseline.txt
0
$ python3 -c "import yaml; ..."
paths: 140, operations: 186, schemas: 74
sprint-13.6 schemas missing: (none)
OpenAPI lint: clean.
$ gofmt -l . → clean
$ go vet ./internal/api/handler/... ./cmd/server/... → clean
ARCH-H1 final tally (across Sprints 13.1 + 13.4 + 13.5 + 13.6)
==============================================================
Sprint 13.1: structural categorization — split 64 exceptions into
36 wire-protocol + 28 rest-deferred; added parity-
script bucket reporting + monotonic-decrease guard +
baseline file. ARCH-H1's structural close.
Sprint 13.4: 13 OpenAPI ops + 13 exception deletions + baseline
28 → 15. Auth/sessions + OIDC CRUD/JWKS/test/refresh
+ group-mappings clusters.
Sprint 13.5: 8 OpenAPI ops + 8 exception deletions + baseline
15 → 7. Auth/breakglass + auth/users +
auth/runtime-config clusters.
Sprint 13.6 (this commit): 7 OpenAPI ops + 7 exception deletions
+ baseline 7 → 0. Audit/export + demo-residual +
auth/logout + auth/breakglass/login + 3 OIDC browser
flows. ARCH-H1's substantive close.
Cumulative: 28 OpenAPI ops authored, 28 exception entries deleted,
rest-deferred bucket drained from 28 → 0. The OpenAPI surface
exactly matches every REST-shaped router route.
Sprint 13.7 closes the audit HTML flip + tightens this commit's
monotonic-decrease floor to a zero-exact pin so the burn-down is
locked.
Refs: ARCH-H1 substantive close — final batch.
266 KiB
266 KiB