mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 12:31:29 +00:00
Unify API auth + RFC-compliant CRL/OCSP (M-002 + M-003 + M-006, auto-closes M-001)
Closes the remaining P1 gaps from coverage-gap-audit.md (M-001/M-002/M-003/M-006)
on top of the C-001/C-002 ownership + agent-FK contract fixes landed in
a53a4b8. The work lands as a single commit spanning server, docs, tests,
and the React client.
M-002 — Named API keys with per-key actor propagation
* Migration 000014 adds the 'api_keys' table (id, name, hash,
principal, role, created_at, last_used_at, disabled_at) so every
credential carries an identifiable principal instead of the
opaque 'anonymous'/'api-key' sentinel.
* Auth middleware now rotates through configured keys, performs
constant-time hash comparison, stamps 'last_used_at', and emits
an actor struct via contextWithActor(). The audit middleware,
bulk-revocation handler, approval handlers, and MCP tool layer
now read the principal off the context and persist it on every
audit_events row.
* Regression coverage:
- internal/api/middleware/audit_test.go — actor propagation,
principal redaction for disabled keys, anonymous fallback for
unauthenticated endpoints.
- internal/api/handler/bulk_revocation_handler_test.go,
job_handler_test.go — principal-on-audit assertions.
M-003 — Authorization gates (Phase B)
* Approval handler rejects self-approval / self-rejection with 403
when the actor principal equals the job's requested_by field.
* Bulk revocation is gated behind the 'admin' role; operators and
viewers receive 403.
* Regression coverage:
- internal/service/job_test.go — TestApproveJob_NotSelf,
TestRejectJob_NotSelf.
- internal/api/handler/bulk_revocation_handler_test.go —
TestBulkRevoke_RequiresAdmin, TestBulkRevoke_AdminSucceeds.
M-006 — RFC-compliant CRL/OCSP on the unauthenticated .well-known mux
* Per RFC 8615, relying parties cannot reasonably be asked to
authenticate against the issuing certctl instance to retrieve
revocation material. CRL and OCSP move off the authenticated
'/api/v1/crl*' and '/api/v1/ocsp/*' paths onto:
GET /.well-known/pki/crl/{issuer_id}
Content-Type: application/pkix-crl (RFC 5280 §5)
GET /.well-known/pki/ocsp/{issuer_id}/{serial}
Content-Type: application/ocsp-response (RFC 6960)
* Non-standard JSON CRL shape is removed; only DER is served.
* Short-lived certificate exemption (profile TTL < 1h → skip
CRL/OCSP) is preserved; the response simply omits the serial.
* Routes are registered on the unauthenticated 'finalHandler' mux
in cmd/server/main.go alongside EST ('/.well-known/est/*') and
SCEP ('/scep'). Legacy authenticated paths return 404.
* Regression coverage:
- internal/api/handler/certificate_handler_test.go — content
type, DER parseability, 404 for unknown issuer.
- internal/api/handler/adversarial_path_test.go — unauthenticated
access asserted for CRL, OCSP, EST, SCEP.
- internal/api/router/router_test.go — route-table assertion
that '.well-known/pki/*', '.well-known/est/*', and '/scep' are
mounted on the unauthenticated branch.
M-001 — Auto-closed by M-002
EST and SCEP were already registered on the unauthenticated
'finalHandler' mux; the router comment at
internal/api/router/router.go:247 now matches reality. The
adversarial-path tests above lock the behavior in.
Verification (all gates green):
* go vet ./... — clean
* go build ./... — ok
* go test -short ./... (55+ packages) — all pass
* web/ : npm test (225 Vitest tests) — all pass
* web/ : npx tsc --noEmit — clean
* grep sweep for '/api/v1/(crl|ocsp)' — 13 surviving hits,
all intentional M-006 tombstone/relocation comments.
Documentation:
* coverage-gap-audit.md — status flips M-001/M-002/M-003/M-006 →
Fixed, with per-finding resolution paragraphs citing regression
test IDs. (Audit file lives outside this repo; see cowork root.)
* CLAUDE.md Project Status line updated with the auth-unification
closure note.
* docs/features.md, docs/architecture.md, docs/quickstart.md,
docs/concepts.md, docs/connectors.md, docs/test-env.md,
docs/testing-guide.md, docs/compliance-*.md, docs/demo-advanced.md
— refreshed for the new '.well-known/pki/*' namespace and named
API keys.
* api/openapi.yaml — documents the new unauthenticated endpoints
and removes the legacy '/api/v1/crl*' + '/api/v1/ocsp/*' paths.
.gitignore: adds '/.gocache/' and '/.gomodcache/' for the session-
scoped Go caches so they never enter the tree.
This commit is contained in:
+32
-45
@@ -29,7 +29,11 @@ tags:
|
||||
- name: Certificates
|
||||
description: Certificate lifecycle — CRUD, versions, renewal, deployment, revocation
|
||||
- name: CRL & OCSP
|
||||
description: Certificate revocation list and OCSP responder
|
||||
description: |
|
||||
Certificate revocation list (RFC 5280) and OCSP responder (RFC 6960).
|
||||
Served unauthenticated under `/.well-known/pki/*` (RFC 8615) so
|
||||
relying parties can retrieve revocation status without a certctl
|
||||
API key.
|
||||
- name: Issuers
|
||||
description: CA issuer connector management (Local CA, ACME, step-ca)
|
||||
- name: Targets
|
||||
@@ -493,50 +497,28 @@ paths:
|
||||
"500":
|
||||
$ref: "#/components/responses/InternalError"
|
||||
|
||||
# ─── CRL & OCSP ─────────────────────────────────────────────────────
|
||||
/api/v1/crl:
|
||||
# ─── PKI (CRL & OCSP, RFC 5280 / 6960 / 8615) ──────────────────────
|
||||
#
|
||||
# Relying parties (browsers, OpenSSL clients, OCSP stapling sidecars,
|
||||
# mTLS clients) cannot present a certctl Bearer token, so these two
|
||||
# endpoints are unauthenticated and live under the RFC 8615
|
||||
# `.well-known` namespace. They were previously mounted at
|
||||
# /api/v1/crl/{issuer_id} and /api/v1/ocsp/{issuer_id}/{serial}; those
|
||||
# paths were removed in M-006.
|
||||
#
|
||||
# The non-standard JSON CRL endpoint (GET /api/v1/crl) was also
|
||||
# removed — RFC 5280 defines only the DER wire format.
|
||||
/.well-known/pki/crl/{issuer_id}:
|
||||
get:
|
||||
tags: [CRL & OCSP]
|
||||
summary: Get JSON CRL
|
||||
description: Returns all revoked certificates in JSON format.
|
||||
operationId: getCRL
|
||||
responses:
|
||||
"200":
|
||||
description: JSON CRL
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
version:
|
||||
type: integer
|
||||
example: 1
|
||||
entries:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
serial_number:
|
||||
type: string
|
||||
revocation_date:
|
||||
type: string
|
||||
format: date-time
|
||||
revocation_reason:
|
||||
type: string
|
||||
total:
|
||||
type: integer
|
||||
generated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
"500":
|
||||
$ref: "#/components/responses/InternalError"
|
||||
|
||||
/api/v1/crl/{issuer_id}:
|
||||
get:
|
||||
tags: [CRL & OCSP]
|
||||
summary: Get DER-encoded X.509 CRL
|
||||
description: Returns a proper DER-encoded CRL signed by the issuing CA. 24-hour validity.
|
||||
summary: Get DER-encoded X.509 CRL (RFC 5280)
|
||||
description: |
|
||||
Returns a DER-encoded CRL signed by the issuing CA (RFC 5280 §5),
|
||||
served unauthenticated per RFC 8615 `.well-known` semantics so
|
||||
relying parties can retrieve it without a certctl API key.
|
||||
Validity is 24 hours.
|
||||
operationId: getDERCRL
|
||||
security: []
|
||||
parameters:
|
||||
- name: issuer_id
|
||||
in: path
|
||||
@@ -560,12 +542,17 @@ paths:
|
||||
"501":
|
||||
description: Issuer does not support CRL generation
|
||||
|
||||
/api/v1/ocsp/{issuer_id}/{serial}:
|
||||
/.well-known/pki/ocsp/{issuer_id}/{serial}:
|
||||
get:
|
||||
tags: [CRL & OCSP]
|
||||
summary: OCSP responder
|
||||
description: Returns signed OCSP response (good/revoked/unknown) for the given serial number.
|
||||
summary: OCSP responder (RFC 6960)
|
||||
description: |
|
||||
Returns a signed OCSP response (good/revoked/unknown) for the
|
||||
given serial number per RFC 6960 §2.1, served unauthenticated
|
||||
per RFC 8615 so relying parties and OCSP stapling sidecars can
|
||||
query revocation status without a certctl API key.
|
||||
operationId: handleOCSP
|
||||
security: []
|
||||
parameters:
|
||||
- name: issuer_id
|
||||
in: path
|
||||
|
||||
Reference in New Issue
Block a user