mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 13:51:36 +00:00
domain, migrations: IntermediateCA type + intermediate_cas + Issuer.HierarchyMode
Rank 8 of the 2026-05-03 deep-research deliverable, commit 1 of 5
(cowork/rank-8-intermediate-ca-hierarchy-prompt.md). Closes the multi-
level CA hierarchy gap for FedRAMP boundary-CA, financial-services
policy-CA, and OT network-CA deployments where regulator-mandated
certificate-policy separation requires multiple layers (root → policy
→ issuing).
This commit lands ONLY the foundation — schema, types, repository
interface, postgres implementation. No service / connector / handler
wiring yet. The 5-commit chain is bisectable: this commit can ship
with no operator-visible behavior change until commits 2-5 wire the
service layer + the local-connector tree-mode + admin API + GUI tree
view + operator runbook. The default value for issuers.hierarchy_mode
is 'single' so every existing operator's behavior is byte-identical
post-migration.
Existing scaffolding REUSED (not redefined):
- internal/crypto/signer.Driver seam — every IntermediateCA carries
a key_driver_id pointing at the signer.Driver instance that owns
its private key. Defense in depth: NEVER persist key bytes in a
row. FileDriver is the production default; future PKCS11Driver /
CloudKMSDriver close the disk-exposure leg via the same seam.
- issuers.id row — the new intermediate_cas FK references it.
Files added:
internal/domain/intermediate_ca.go — IntermediateCA type,
IntermediateCAState
closed enum (active /
retiring / retired),
IsValidIntermediateCAState
+ IsTerminal helpers,
NameConstraint struct
(RFC 5280 §4.2.1.10
permitted+excluded
subtree subset
semantics for service-
layer enforcement),
HierarchyModeSingle /
HierarchyModeTree
constants.
internal/repository/postgres/intermediate_ca.go — IntermediateCARepository
impl: Create (ica-<slug>
ID gen, JSONB +
nullable-column round-
trip, lib/pq 23505 →
ErrAlreadyExists),
Get, ListByIssuer,
ListChildren,
UpdateState,
GetActiveRoot,
WalkAncestry (recursive
CTE — single SQL
round-trip, O(depth)
rows, leaf-first
ordering).
migrations/000028_intermediate_ca_hierarchy.{up,down}.sql
— idempotent schema.
issuers.hierarchy_mode
VARCHAR(20) DEFAULT
'single'. New
intermediate_cas table
with FKs to
issuers / self
(parent_ca_id) +
CHECK constraints
(closed-enum state,
not_after >
not_before, no self-
parent) + 6 indexes
(partial-unique
active root per
issuer, partial-
unique name per
issuer, owning
issuer, parent,
state, expiring).
Files modified:
internal/domain/connector.go — adds Issuer.HierarchyMode field
with full doc comment + JSON tag.
Empty string ≡ single mode for
back-compat.
internal/repository/interfaces.go — adds IntermediateCARepository
interface (7 methods).
Verified locally:
gofmt: clean.
go vet ./internal/domain/... ./internal/repository/...: exit 0.
go build ./internal/domain/... ./internal/repository/...: exit 0.
Out of scope for this commit (lands in commits 2-5):
- service/intermediate_ca.go (CreateRoot / CreateChild / Retire /
LoadHierarchy / AssembleChain + RFC 5280 §4.2.1.9 path-len +
§4.2.1.10 NameConstraints subset enforcement + 9 service tests).
- local connector rewrite + byte-equivalence pin
(TestLocal_HierarchyMode_SingleVsTree_ByteIdentical — the load-
bearing backwards-compat refusal-to-ship test).
- 4 admin-gated handler endpoints + OpenAPI extension + handler tests.
- web/src/pages/IssuerHierarchyPage.tsx.
- docs/intermediate-ca-hierarchy.md sysadmin runbook + connectors.md
row + WORKSPACE-ROADMAP follow-ons.
Reference: cowork/rank-8-intermediate-ca-hierarchy-prompt.md.
This commit is contained in:
shankar0123
@@ -16,8 +16,20 @@ type Issuer struct {
|
||||
LastTestedAt *time.Time `json:"last_tested_at,omitempty"`
|
||||
TestStatus string `json:"test_status,omitempty"`
|
||||
Source string `json:"source,omitempty"`
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
UpdatedAt time.Time `json:"updated_at"`
|
||||
|
||||
// HierarchyMode picks the per-issuer CA-hierarchy posture for the
|
||||
// local issuer adapter. "single" (default, pre-Rank-8 historical)
|
||||
// loads a pre-signed cert+key from disk via local.Config.CACertPath
|
||||
// / local.Config.CAKeyPath. "tree" activates first-class N-level
|
||||
// hierarchy management via the intermediate_cas table; chain
|
||||
// assembly walks parent_ca_id from the issuing leaf-CA up to the
|
||||
// root at issuance time. Empty string ≡ HierarchyModeSingle for
|
||||
// back-compat byte-identical behavior on unmigrated rows. Backed
|
||||
// by issuers.hierarchy_mode added in migration 000028.
|
||||
HierarchyMode string `json:"hierarchy_mode,omitempty"`
|
||||
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
UpdatedAt time.Time `json:"updated_at"`
|
||||
}
|
||||
|
||||
// DeploymentTarget represents a target system where certificates are deployed.
|
||||
|
||||
@@ -0,0 +1,115 @@
|
||||
package domain
|
||||
|
||||
import "time"
|
||||
|
||||
// IntermediateCA represents a non-root CA in a multi-level hierarchy.
|
||||
// One row per certificate (root, policy, issuing) — the parent_ca_id
|
||||
// FK to itself encodes the tree shape; the owning_issuer_id FK groups
|
||||
// every CA under one Issuer config row.
|
||||
//
|
||||
// Lifecycle:
|
||||
//
|
||||
// created (CreateRoot or CreateChild)
|
||||
// │
|
||||
// ▼
|
||||
// active (issuing certs)
|
||||
// │
|
||||
// ▼
|
||||
// retiring (drain — children still active; this CA stops issuing
|
||||
// NEW children but existing children continue)
|
||||
// │
|
||||
// ▼
|
||||
// retired (terminal — no issuance, OCSP responder
|
||||
// keeps responding for already-issued leaves until expiry)
|
||||
//
|
||||
// Closes the multi-level CA hierarchy gap for FedRAMP boundary-CA,
|
||||
// financial-services policy-CA, and OT network-CA deployments where
|
||||
// regulator-mandated certificate-policy separation requires multiple
|
||||
// layers (root → policy → issuing).
|
||||
//
|
||||
// Defense in depth: NEVER persist the CA private key bytes in this
|
||||
// row. KeyDriverID is a reference (filesystem path / KMS key ID /
|
||||
// HSM slot) to the signer.Driver instance that owns the key. A SQL-
|
||||
// injection or row-leak surface must NEVER expose key bytes; only
|
||||
// the reference can leak.
|
||||
type IntermediateCA struct {
|
||||
ID string `json:"id"` // ica-<slug>
|
||||
OwningIssuerID string `json:"owning_issuer_id"` // FK issuers.id
|
||||
ParentCAID *string `json:"parent_ca_id,omitempty"` // nil for root, FK to self otherwise
|
||||
Name string `json:"name"` // operator-supplied label
|
||||
Subject string `json:"subject"` // distinguished name (CN + O + OU + ...)
|
||||
State IntermediateCAState `json:"state"` // active / retiring / retired
|
||||
CertPEM string `json:"cert_pem"` // this CA's cert (PEM)
|
||||
KeyDriverID string `json:"key_driver_id"` // signer.Driver instance ID
|
||||
NotBefore time.Time `json:"not_before"`
|
||||
NotAfter time.Time `json:"not_after"`
|
||||
PathLenConstraint *int `json:"path_len_constraint,omitempty"` // RFC 5280 §4.2.1.9; nil = no constraint
|
||||
NameConstraints []NameConstraint `json:"name_constraints,omitempty"` // RFC 5280 §4.2.1.10
|
||||
OCSPResponderURL string `json:"ocsp_responder_url,omitempty"` // AIA stamping for issued leaves
|
||||
Metadata map[string]string `json:"metadata,omitempty"` // policy_id, compliance_tier, owner_team
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
UpdatedAt time.Time `json:"updated_at"`
|
||||
}
|
||||
|
||||
// IntermediateCAState is the closed enum of CA-row lifecycle states.
|
||||
type IntermediateCAState string
|
||||
|
||||
const (
|
||||
// IntermediateCAStateActive is the issuing state — the CA can sign
|
||||
// new children + new leaves under it.
|
||||
IntermediateCAStateActive IntermediateCAState = "active"
|
||||
|
||||
// IntermediateCAStateRetiring is the drain state — no new children;
|
||||
// existing children keep issuing until they themselves retire.
|
||||
IntermediateCAStateRetiring IntermediateCAState = "retiring"
|
||||
|
||||
// IntermediateCAStateRetired is the terminal state — no issuance
|
||||
// at all; OCSP responder keeps responding for already-issued leaves
|
||||
// until natural expiry.
|
||||
IntermediateCAStateRetired IntermediateCAState = "retired"
|
||||
)
|
||||
|
||||
// IsValidIntermediateCAState reports whether s is a closed-enum value.
|
||||
func IsValidIntermediateCAState(s IntermediateCAState) bool {
|
||||
switch s {
|
||||
case IntermediateCAStateActive, IntermediateCAStateRetiring, IntermediateCAStateRetired:
|
||||
return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// IsTerminal reports whether s is the immutable terminal state.
|
||||
func (s IntermediateCAState) IsTerminal() bool {
|
||||
return s == IntermediateCAStateRetired
|
||||
}
|
||||
|
||||
// NameConstraint encodes RFC 5280 §4.2.1.10 — Permitted + Excluded
|
||||
// subtrees. Critical extension when set on the CA cert; the local
|
||||
// adapter renders this onto the CA's cert at CreateChild time. The
|
||||
// service layer enforces subset semantics: a child's permitted set
|
||||
// MUST be a subset of the parent's permitted set + the child's
|
||||
// excluded set MUST be a superset of the parent's excluded set.
|
||||
type NameConstraint struct {
|
||||
Permitted []string `json:"permitted,omitempty"` // e.g., "example.com" → all DNS subtrees ending in example.com
|
||||
Excluded []string `json:"excluded,omitempty"`
|
||||
}
|
||||
|
||||
// HierarchyMode picks the per-issuer CA-hierarchy posture, stored on
|
||||
// the Issuer row. Three values are possible (the database default is
|
||||
// "single" — back-compat byte-identical for unmigrated rows):
|
||||
//
|
||||
// - HierarchyModeSingle (default, pre-Rank-8 historical) — sub-CA
|
||||
// mode loads a pre-signed cert+key from disk via local.Config.
|
||||
// CACertPath / local.Config.CAKeyPath. Existing operators upgrade
|
||||
// with no behavior change.
|
||||
// - HierarchyModeTree — the issuer's CAs are managed via the
|
||||
// intermediate_cas table; chain assembly walks the parent_ca_id
|
||||
// FK from the issuing leaf-CA up to the root + attaches the
|
||||
// assembled chain to every IssuanceResult.
|
||||
//
|
||||
// The local connector reads this from the Issuer row at issue time;
|
||||
// empty string is treated as HierarchyModeSingle.
|
||||
const (
|
||||
HierarchyModeSingle = "single"
|
||||
HierarchyModeTree = "tree"
|
||||
)
|
||||
Reference in New Issue
Block a user