mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 13:41:30 +00:00
docs(arch-h1): Phase 13 Sprint 13.4 — OpenAPI auth/sessions + OIDC ops (batch 1, 13 ops)
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.
This commit is contained in:
shankar0123
@@ -41,15 +41,17 @@
|
||||
# ──────────────────────────────────────────────────────────────────────
|
||||
#
|
||||
# Current split, re-derived by the parity script's bucket-reporting
|
||||
# subcommand:
|
||||
# subcommand (post-Sprint-13.4 / 2026-05-14):
|
||||
#
|
||||
# total entries: 64
|
||||
# total entries: 51
|
||||
# wire-protocol: 36
|
||||
# rest-deferred: 28
|
||||
# rest-deferred: 15
|
||||
#
|
||||
# Burn-down plan for the rest-deferred bucket (Phase 13 Sprints 13.4-13.6):
|
||||
# Burn-down progress + remaining plan for the rest-deferred bucket:
|
||||
#
|
||||
# Sprint 13.4 → 28 - 13 = 15 (auth/sessions + auth/oidc cluster, 13 ops)
|
||||
# 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
|
||||
@@ -209,45 +211,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/sessions"
|
||||
why: "Bundle 2 Phase 5 self/admin session list. OpenAPI rep deferred to pre-2.2.0."
|
||||
category: rest-deferred
|
||||
- route: "DELETE /api/v1/auth/sessions/{id}"
|
||||
why: "Bundle 2 Phase 5 session revoke. OpenAPI rep deferred to pre-2.2.0."
|
||||
category: rest-deferred
|
||||
- route: "DELETE /api/v1/auth/sessions"
|
||||
why: "Bundle 2 audit-2026-05-10 MED-2/3 revoke-all-except-current."
|
||||
category: rest-deferred
|
||||
- route: "GET /api/v1/auth/oidc/providers"
|
||||
why: "Bundle 2 Phase 5 OIDC provider CRUD (list)."
|
||||
category: rest-deferred
|
||||
- route: "POST /api/v1/auth/oidc/providers"
|
||||
why: "Bundle 2 Phase 5 OIDC provider CRUD (create)."
|
||||
category: rest-deferred
|
||||
- route: "PUT /api/v1/auth/oidc/providers/{id}"
|
||||
why: "Bundle 2 Phase 5 OIDC provider CRUD (update)."
|
||||
category: rest-deferred
|
||||
- route: "DELETE /api/v1/auth/oidc/providers/{id}"
|
||||
why: "Bundle 2 Phase 5 OIDC provider CRUD (delete)."
|
||||
category: rest-deferred
|
||||
- route: "POST /api/v1/auth/oidc/providers/{id}/refresh"
|
||||
why: "Bundle 2 audit-2026-05-10 MED-7 JWKS hot-refresh."
|
||||
category: rest-deferred
|
||||
- route: "GET /api/v1/auth/oidc/providers/{id}/jwks-status"
|
||||
why: "Bundle 2 audit-2026-05-10 MED-7 JWKS health snapshot."
|
||||
category: rest-deferred
|
||||
- route: "POST /api/v1/auth/oidc/test"
|
||||
why: "Bundle 2 audit-2026-05-10 MED-5 dry-run discovery + JWKS + alg-downgrade check."
|
||||
category: rest-deferred
|
||||
- route: "GET /api/v1/auth/oidc/group-mappings"
|
||||
why: "Bundle 2 Phase 5 group-mapping CRUD (list)."
|
||||
category: rest-deferred
|
||||
- route: "POST /api/v1/auth/oidc/group-mappings"
|
||||
why: "Bundle 2 Phase 5 group-mapping CRUD (create)."
|
||||
category: rest-deferred
|
||||
- route: "DELETE /api/v1/auth/oidc/group-mappings/{id}"
|
||||
why: "Bundle 2 Phase 5 group-mapping CRUD (delete)."
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user