mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 15:51:30 +00:00
docs(arch-h1): Phase 13 Sprint 13.5 — OpenAPI breakglass + users + runtime-config ops (batch 2, 8 ops)
Phase 13 Sprint 13.5 closure (architecture diligence audit ARCH-H1):
authors OpenAPI operations for the auth/breakglass admin cluster
(4) + auth/users cluster (3) + auth/runtime-config (1), drives the
`rest-deferred` exception bucket from 15 → 7.
OpenAPI-only sprint: zero Go changes. Every schema field-by-field
mirrors the projection types in
internal/api/handler/auth_breakglass.go +
internal/api/handler/auth_users.go.
8 new operations
================
Break-glass admin cluster (4 ops, all gated `auth.breakglass.admin`):
GET /api/v1/auth/breakglass/credentials listBreakglassCredentials
POST /api/v1/auth/breakglass/credentials setBreakglassPassword
DELETE /api/v1/auth/breakglass/credentials/{actor_id} removeBreakglassCredential
POST /api/v1/auth/breakglass/credentials/{actor_id}/unlock unlockBreakglassCredential
Users cluster (3 ops):
GET /api/v1/auth/users listAuthUsers (auth.user.read)
DELETE /api/v1/auth/users/{id} deactivateAuthUser (auth.user.deactivate)
POST /api/v1/auth/users/{id}/reactivate reactivateAuthUser (auth.user.deactivate)
Runtime-config read (1 op):
GET /api/v1/auth/runtime-config getAuthRuntimeConfig (auth.role.assign)
5 new schemas (components/schemas)
==================================
BreakglassCredentialResponse — mirrors breakglassCredentialResponse
(6 fields). Password hash NEVER
serialized.
BreakglassCredentialListResponse — mirrors listBreakglassCredentialsResponse
({"credentials": [...]}).
BreakglassSetPasswordRequest — mirrors breakglassSetPasswordRequest
(actor_id + password; password marked
`format: password`).
BreakglassSetPasswordResponse — mirrors the inline response shape
returned by SetPassword (actor_id +
created_at).
AuthUser — mirrors userResponse (9 fields,
including pointer-based
deactivated_at marked nullable).
Every schema field's JSON tag, type, required-ness, and (where
applicable) nullability grounded against the live Go source. The
`tenant_id` field surfaces on AuthUser (the handler emits it) but
does NOT appear on the breakglass schemas (the breakglass surface
is tenant-implicit — derived from caller context, not request body).
Surface-invisibility property
=============================
Each break-glass admin endpoint returns 404 when
`CERTCTL_BREAKGLASS_ENABLED=false` so an attacker probing the admin
surface gets the same signal as probing the login endpoint
(consistent with Audit 2026-05-10 CRIT-4 closure). Documented in the
per-op description so client implementations don't surprise on the
404 path.
Self-deactivate guard
=====================
`DELETE /api/v1/auth/users/{id}` returns 409 (not 403) when the
caller is deactivating their own account — Audit 2026-05-11 A-2
foot-gun closure. Break-glass remains the documented recovery path.
The 409 is documented in the per-op responses block.
Exception YAML + baseline
=========================
8 entries removed from api/openapi-handler-exceptions.yaml. Post-cut
shape:
total entries: 43 (was 51)
wire-protocol: 36 (unchanged)
rest-deferred: 7 (was 15)
Baseline file bumped 15 → 7. The Sprint 13.1 monotonic-decrease
guard now pins `rest-deferred ≤ 7`. Sprint 13.6 walks it to zero
(7 → 0).
YAML header narrative updated: "Sprint 13.5 SHIPPED — 15 - 8 = 7".
Receipts (all from the live tree)
=================================
$ grep -cE '^\s+operationId:' api/openapi.yaml
179 (was 171 + 8)
$ bash scripts/ci-guards/openapi-handler-parity.sh
Router routes: 220
OpenAPI operations: 179
Documented exceptions: 43
wire-protocol: 36
rest-deferred: 7
openapi-handler-parity: clean.
$ bash scripts/ci-guards/openapi-rest-deferred-monotonic.sh
openapi-rest-deferred-monotonic: clean — rest-deferred = 7,
baseline = 7.
$ cat api/openapi-handler-exceptions-baseline.txt
7
$ python3 -c "import yaml; ..."
paths: 133, operations: 179, schemas: 72
sprint-13.5 schemas missing: (none)
OpenAPI lint: clean.
$ gofmt -l . → clean
$ go vet ./internal/api/handler/... ./cmd/server/... → clean
Sprint 13.6 next (audit/export + demo-residual + 3 OIDC browser
flows + auth/logout + auth/breakglass/login = 7 ops; rest-deferred
7 → 0 — the zero-floor commit that completes ARCH-H1's substantive
burn-down). Same OpenAPI-only pattern; the OIDC browser-flow
endpoints in 13.6 model redirect-only operations (302 + Location
header, empty body) per OAS 3.1 conventions.
Refs: ARCH-H1 batch 2 closure.
This commit is contained in:
shankar0123
@@ -41,19 +41,20 @@
|
||||
# ──────────────────────────────────────────────────────────────────────
|
||||
#
|
||||
# Current split, re-derived by the parity script's bucket-reporting
|
||||
# subcommand (post-Sprint-13.4 / 2026-05-14):
|
||||
# subcommand (post-Sprint-13.5 / 2026-05-14):
|
||||
#
|
||||
# total entries: 51
|
||||
# total entries: 43
|
||||
# wire-protocol: 36
|
||||
# rest-deferred: 15
|
||||
# rest-deferred: 7
|
||||
#
|
||||
# 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.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)
|
||||
@@ -211,30 +212,6 @@ documented_exceptions:
|
||||
- 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
|
||||
|
||||
Reference in New Issue
Block a user