gsadmin/certctl
1
0
Fork 0
mirror of https://github.com/shankar0123/certctl.git synced 2026-06-07 13:51:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

domain, migrations: IntermediateCA type + intermediate_cas + Issuer.HierarchyMode

Browse Source 
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
2026-05-04 01:53:56 +00:00
parent 31e50d987f
commit 66d2af36a7
6 changed files with 531 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
internal/repository/interfaces.go
+22
View File
@@ -770,3 +770,25 @@ type ApprovalFilter struct {
// PerPage is the number of results per page.
PerPage int
}
// IntermediateCARepository defines operations for managing first-class
// CA hierarchies (Rank 8). Every non-root CA is a row, parent_ca_id
// encodes the tree, WalkAncestry returns the leaf-to-root chain via
// a recursive CTE.
//
// Defense in depth: NEVER persist CA private key bytes. The
// implementation stores key_driver_id (a signer.Driver reference) only.
type IntermediateCARepository interface {
Create(ctx context.Context, ca *domain.IntermediateCA) error
Get(ctx context.Context, id string) (*domain.IntermediateCA, error)
ListByIssuer(ctx context.Context, issuerID string) ([]*domain.IntermediateCA, error)
ListChildren(ctx context.Context, parentCAID string) ([]*domain.IntermediateCA, error)
UpdateState(ctx context.Context, id string, state domain.IntermediateCAState) error
GetActiveRoot(ctx context.Context, issuerID string) (*domain.IntermediateCA, error)
// WalkAncestry returns the chain from leafID up to (and including)
// the root via a postgres recursive CTE. The slice is ordered
// leaf-first; caller verifies the last element has parent_ca_id
// IS NULL (i.e., it's a root). Returns ErrNotFound if leafID does
// not exist.
WalkAncestry(ctx context.Context, leafID string) ([]*domain.IntermediateCA, error)
}
internal/repository/postgres/intermediate_ca.go
+297
View File
@@ -0,0 +1,297 @@
package postgres
import (
"context"
"database/sql"
"encoding/json"
"errors"
"fmt"
"time"
"github.com/google/uuid"
"github.com/lib/pq"
"github.com/certctl-io/certctl/internal/domain"
"github.com/certctl-io/certctl/internal/repository"
)
// IntermediateCARepository is the postgres implementation of
// repository.IntermediateCARepository. Rank 8 first-class CA
// hierarchy.
type IntermediateCARepository struct {
db *sql.DB
}
// NewIntermediateCARepository constructs an IntermediateCARepository
// against the given *sql.DB. Schema defined by migration
// 000028_intermediate_ca_hierarchy.up.sql.
func NewIntermediateCARepository(db *sql.DB) *IntermediateCARepository {
return &IntermediateCARepository{db: db}
}
// Create inserts a new IntermediateCA row.
func (r *IntermediateCARepository) Create(ctx context.Context, ca *domain.IntermediateCA) error {
if ca.ID == "" {
ca.ID = "ica-" + uuid.NewString()
}
if ca.State == "" {
ca.State = domain.IntermediateCAStateActive
}
if !domain.IsValidIntermediateCAState(ca.State) {
return fmt.Errorf("invalid intermediate CA state %q", ca.State)
}
now := time.Now().UTC()
if ca.CreatedAt.IsZero() {
ca.CreatedAt = now
}
if ca.UpdatedAt.IsZero() {
ca.UpdatedAt = now
}
nameConstraintsJSON, err := json.Marshal(ca.NameConstraints)
if err != nil {
return fmt.Errorf("marshal name_constraints: %w", err)
}
if len(nameConstraintsJSON) == 0 || string(nameConstraintsJSON) == "null" {
nameConstraintsJSON = []byte("[]")
}
metadataJSON, err := json.Marshal(ca.Metadata)
if err != nil {
return fmt.Errorf("marshal metadata: %w", err)
}
if len(metadataJSON) == 0 || string(metadataJSON) == "null" {
metadataJSON = []byte("{}")
}
const q = `
INSERT INTO intermediate_cas
(id, owning_issuer_id, parent_ca_id, name, subject, state,
cert_pem, key_driver_id, not_before, not_after,
path_len_constraint, name_constraints, ocsp_responder_url,
metadata, created_at, updated_at)
VALUES
($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16)
`
_, err = r.db.ExecContext(ctx, q,
ca.ID, ca.OwningIssuerID, ca.ParentCAID, ca.Name, ca.Subject, string(ca.State),
ca.CertPEM, ca.KeyDriverID, ca.NotBefore, ca.NotAfter,
ca.PathLenConstraint, nameConstraintsJSON, nullIfEmpty(ca.OCSPResponderURL),
metadataJSON, ca.CreatedAt, ca.UpdatedAt,
)
if err != nil {
var pqErr *pq.Error
if errors.As(err, &pqErr) && pqErr.Code == "23505" { // unique_violation
return repository.ErrAlreadyExists
}
return fmt.Errorf("insert intermediate CA: %w", err)
}
return nil
}
// Get returns the row by ID or repository.ErrNotFound.
func (r *IntermediateCARepository) Get(ctx context.Context, id string) (*domain.IntermediateCA, error) {
const q = `
SELECT id, owning_issuer_id, parent_ca_id, name, subject, state,
cert_pem, key_driver_id, not_before, not_after,
path_len_constraint, name_constraints, ocsp_responder_url,
metadata, created_at, updated_at
FROM intermediate_cas
WHERE id = $1
`
row := r.db.QueryRowContext(ctx, q, id)
return scanIntermediateCARow(row)
}
// ListByIssuer returns every CA row for an issuer.
func (r *IntermediateCARepository) ListByIssuer(ctx context.Context, issuerID string) ([]*domain.IntermediateCA, error) {
const q = `
SELECT id, owning_issuer_id, parent_ca_id, name, subject, state,
cert_pem, key_driver_id, not_before, not_after,
path_len_constraint, name_constraints, ocsp_responder_url,
metadata, created_at, updated_at
FROM intermediate_cas
WHERE owning_issuer_id = $1
ORDER BY created_at ASC
`
rows, err := r.db.QueryContext(ctx, q, issuerID)
if err != nil {
return nil, fmt.Errorf("list intermediate CAs: %w", err)
}
defer rows.Close()
return scanIntermediateCARows(rows)
}
// ListChildren returns direct children of the given CA.
func (r *IntermediateCARepository) ListChildren(ctx context.Context, parentCAID string) ([]*domain.IntermediateCA, error) {
const q = `
SELECT id, owning_issuer_id, parent_ca_id, name, subject, state,
cert_pem, key_driver_id, not_before, not_after,
path_len_constraint, name_constraints, ocsp_responder_url,
metadata, created_at, updated_at
FROM intermediate_cas
WHERE parent_ca_id = $1
ORDER BY created_at ASC
`
rows, err := r.db.QueryContext(ctx, q, parentCAID)
if err != nil {
return nil, fmt.Errorf("list children: %w", err)
}
defer rows.Close()
return scanIntermediateCARows(rows)
}
// UpdateState transitions a row's lifecycle state.
func (r *IntermediateCARepository) UpdateState(ctx context.Context, id string, state domain.IntermediateCAState) error {
if !domain.IsValidIntermediateCAState(state) {
return fmt.Errorf("invalid state %q", state)
}
const q = `
UPDATE intermediate_cas
SET state = $2, updated_at = NOW()
WHERE id = $1
`
res, err := r.db.ExecContext(ctx, q, id, string(state))
if err != nil {
return fmt.Errorf("update state: %w", err)
}
n, err := res.RowsAffected()
if err != nil {
return fmt.Errorf("rows affected: %w", err)
}
if n == 0 {
return repository.ErrNotFound
}
return nil
}
// GetActiveRoot returns the active root CA for an issuer.
func (r *IntermediateCARepository) GetActiveRoot(ctx context.Context, issuerID string) (*domain.IntermediateCA, error) {
const q = `
SELECT id, owning_issuer_id, parent_ca_id, name, subject, state,
cert_pem, key_driver_id, not_before, not_after,
path_len_constraint, name_constraints, ocsp_responder_url,
metadata, created_at, updated_at
FROM intermediate_cas
WHERE owning_issuer_id = $1
AND parent_ca_id IS NULL
AND state = 'active'
LIMIT 1
`
row := r.db.QueryRowContext(ctx, q, issuerID)
return scanIntermediateCARow(row)
}
// WalkAncestry returns leaf-to-root chain via recursive CTE. Single
// SQL round-trip, O(depth) rows.
func (r *IntermediateCARepository) WalkAncestry(ctx context.Context, leafID string) ([]*domain.IntermediateCA, error) {
const q = `
WITH RECURSIVE ancestry AS (
SELECT id, owning_issuer_id, parent_ca_id, name, subject, state,
cert_pem, key_driver_id, not_before, not_after,
path_len_constraint, name_constraints, ocsp_responder_url,
metadata, created_at, updated_at, 0 AS depth
FROM intermediate_cas
WHERE id = $1
UNION ALL
SELECT i.id, i.owning_issuer_id, i.parent_ca_id, i.name, i.subject, i.state,
i.cert_pem, i.key_driver_id, i.not_before, i.not_after,
i.path_len_constraint, i.name_constraints, i.ocsp_responder_url,
i.metadata, i.created_at, i.updated_at, a.depth + 1
FROM intermediate_cas i
JOIN ancestry a ON i.id = a.parent_ca_id
)
SELECT id, owning_issuer_id, parent_ca_id, name, subject, state,
cert_pem, key_driver_id, not_before, not_after,
path_len_constraint, name_constraints, ocsp_responder_url,
metadata, created_at, updated_at
FROM ancestry
ORDER BY depth ASC
`
rows, err := r.db.QueryContext(ctx, q, leafID)
if err != nil {
return nil, fmt.Errorf("walk ancestry: %w", err)
}
defer rows.Close()
out, err := scanIntermediateCARows(rows)
if err != nil {
return nil, err
}
if len(out) == 0 {
return nil, repository.ErrNotFound
}
return out, nil
}
// scanIntermediateCARow scans a single row.
func scanIntermediateCARow(row rowScanner) (*domain.IntermediateCA, error) {
var (
ca domain.IntermediateCA
stateStr string
parentCAID sql.NullString
pathLenConstraint sql.NullInt64
ocspResponderURL sql.NullString
nameConstraintsJSON []byte
metadataJSON []byte
)
err := row.Scan(
&ca.ID, &ca.OwningIssuerID, &parentCAID, &ca.Name, &ca.Subject, &stateStr,
&ca.CertPEM, &ca.KeyDriverID, &ca.NotBefore, &ca.NotAfter,
&pathLenConstraint, &nameConstraintsJSON, &ocspResponderURL,
&metadataJSON, &ca.CreatedAt, &ca.UpdatedAt,
)
if err != nil {
if errors.Is(err, sql.ErrNoRows) {
return nil, repository.ErrNotFound
}
return nil, fmt.Errorf("scan intermediate CA: %w", err)
}
ca.State = domain.IntermediateCAState(stateStr)
if parentCAID.Valid {
s := parentCAID.String
ca.ParentCAID = &s
}
if pathLenConstraint.Valid {
v := int(pathLenConstraint.Int64)
ca.PathLenConstraint = &v
}
if ocspResponderURL.Valid {
ca.OCSPResponderURL = ocspResponderURL.String
}
if len(nameConstraintsJSON) > 0 {
if err := json.Unmarshal(nameConstraintsJSON, &ca.NameConstraints); err != nil {
return nil, fmt.Errorf("unmarshal name_constraints: %w", err)
}
}
if len(metadataJSON) > 0 {
if err := json.Unmarshal(metadataJSON, &ca.Metadata); err != nil {
return nil, fmt.Errorf("unmarshal metadata: %w", err)
}
}
return &ca, nil
}
func scanIntermediateCARows(rows *sql.Rows) ([]*domain.IntermediateCA, error) {
var out []*domain.IntermediateCA
for rows.Next() {
ca, err := scanIntermediateCARow(rows)
if err != nil {
return nil, err
}
out = append(out, ca)
}
if err := rows.Err(); err != nil {
return nil, fmt.Errorf("iterate rows: %w", err)
}
return out, nil
}
// nullIfEmpty returns sql.NullString — Valid=false when s is empty so
// the column is written as SQL NULL rather than empty string.
func nullIfEmpty(s string) sql.NullString {
if s == "" {
return sql.NullString{}
}
return sql.NullString{String: s, Valid: true}
}