mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 15:01:32 +00:00
docs(arch-h1): Phase 13 Sprint 13.6 — OpenAPI batch 3 final 7 ops; rest-deferred bucket reaches 0
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.
This commit is contained in:
shankar0123
@@ -41,13 +41,13 @@
|
||||
# ──────────────────────────────────────────────────────────────────────
|
||||
#
|
||||
# Current split, re-derived by the parity script's bucket-reporting
|
||||
# subcommand (post-Sprint-13.5 / 2026-05-14):
|
||||
# subcommand (post-Sprint-13.6 / 2026-05-14):
|
||||
#
|
||||
# total entries: 43
|
||||
# total entries: 36
|
||||
# wire-protocol: 36
|
||||
# rest-deferred: 7
|
||||
# rest-deferred: 0 ← THE FLOOR — ARCH-H1 substantive close
|
||||
#
|
||||
# Burn-down progress + remaining plan for the rest-deferred bucket:
|
||||
# Burn-down progress:
|
||||
#
|
||||
# Sprint 13.4 SHIPPED — 28 - 13 = 15 (auth/sessions cluster 3 ops +
|
||||
# auth/oidc CRUD + JWKS + test + refresh
|
||||
@@ -55,13 +55,15 @@
|
||||
# Sprint 13.5 SHIPPED — 15 - 8 = 7 (auth/breakglass admin 4 ops +
|
||||
# auth/users 3 ops + auth/runtime-config
|
||||
# 1 op, 8 ops total)
|
||||
# Sprint 13.6 → 7 - 7 = 0 (audit/export + demo-residual + 3
|
||||
# OIDC browser flows + auth/logout +
|
||||
# auth/breakglass/login, 7 ops)
|
||||
# Sprint 13.6 SHIPPED — 7 - 7 = 0 (audit/export 1 op + demo-
|
||||
# residual/cleanup 1 op + auth/logout 1 op +
|
||||
# auth/breakglass/login 1 op + 3 OIDC
|
||||
# browser-flow endpoints, 7 ops total)
|
||||
#
|
||||
# Sprint 13.7 then tightens the parity-script's rest-deferred floor
|
||||
# Sprint 13.7 next 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.
|
||||
# new REST route MUST land with an OpenAPI op or fail CI — no escape
|
||||
# hatch via `category: rest-deferred`.
|
||||
#
|
||||
# Each authored OpenAPI op needs request/response schemas (not
|
||||
# placeholders) so the generated client at web/orval.config.ts emits
|
||||
@@ -197,24 +199,3 @@ documented_exceptions:
|
||||
# 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: "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
|
||||
|
||||
Reference in New Issue
Block a user