domain, migrations: ApprovalRequest type + issuance_approval_requests + RequiresApproval

Rank 7 of the 2026-05-03 Infisical deep-research deliverable, commit 1 of 4 (cowork/rank-7-approval-workflow-primitive-prompt.md). The four-commit chain ships the issuance approval-workflow primitive (request → human review → CA call) closing the two-person integrity / four-eyes principle procurement gap for PCI-DSS Level 1, FedRAMP Moderate / High, SOC 2 Type II, and HIPAA-regulated PHI deployments. This commit lands ONLY the foundation — schema, types, repository interface, postgres implementation. No service / handler wiring yet. The four-commit shape is bisectable: the schema can land in production behind a flag (via the default RequiresApproval=false on every existing profile) without any operator-visible behavior change until commits 2-4 wire the surrounding workflow. Existing scaffolding REUSED (not redefined here): - JobStatusAwaitingApproval enum value (internal/domain/job.go). - JobRepository.ListTimedOutAwaitingJobs (postgres reaper query). - Config.Scheduler.AwaitingApprovalTimeout (env-mapped via CERTCTL_JOB_AWAITING_APPROVAL_TIMEOUT, default 168h = 7 days). - Scheduler.SetAwaitingApprovalTimeout wiring. Files added: internal/domain/approval.go - ApprovalRequest type, ApprovalState closed enum (pending/approved/rejected/ expired), IsValidApprovalState + IsTerminal helpers, outcome const block + bypass-actor sentinel. internal/repository/postgres/approval.go - ApprovalRepository implementation: Create (ar-<slug> ID gen + JSONB metadata round-trip + lib/pq 23505 → ErrAlreadyExists translation), Get, GetByJobID, List (paginated with state / cert / requester filters), UpdateState (pending→terminal transitions only, with already-terminal disambiguation), ExpireStale (bulk reaper, decided_by='system-reaper'). migrations/000027_approval_workflow.{up,down}.sql - Idempotent IF NOT EXISTS / IF EXISTS. Adds certificate_profiles.requires_approval BOOLEAN NOT NULL DEFAULT false, issuance_approval_requests table with FK to managed_certificates / jobs / certificate_profiles, four indexes (state, certificate, pending-age, partial-unique pending-per-job), and the approval_decision_consistency CHECK constraint enforcing decided_by/decided_at must be non-null for terminal states. Files modified: internal/domain/profile.go - Adds CertificateProfile.RequiresApproval bool field with full doc comment + JSON tag. Defaults to false (back-compat — every existing profile keeps the unattended renewal path). internal/repository/interfaces.go - Adds ApprovalRepository interface (6 methods) + ApprovalFilter struct. internal/repository/errors.go - Adds ErrAlreadyExists sentinel for postgres SQLSTATE 23505 (unique-constraint violations from the partial-unique pending-per-job index, plus the "already terminal" state- transition signal). Mirrors the existing ErrNotFound + ErrForeignKeyConstraint shape. Verified: 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-4): - service/approval.go (RequestApproval / Approve / Reject / ListPending / ExpireStale + same-actor RBAC + bypass mode + audit + metrics). - service/approval_metrics.go (decisions counter + pending-age histogram). - 8 service-level table-driven tests including the load-bearing TestApproval_Approve_RejectsSameActor two-person integrity pin. - api/handler/approval.go (5 endpoints + RBAC integration). - api/openapi.yaml (5 new operationIds). - Integration into CertificateService.TriggerRenewal + RenewalService.CheckExpiringCertificates + Scheduler.ReapTimedOutJobs. - cmd/server/main.go wiring. - Config.Approval.BypassEnabled + CERTCTL_APPROVAL_BYPASS env var. - docs/connectors.md CertificateProfile config-table row. - docs/approval-workflow.md operator playbook + compliance control mapping. Reference: cowork/infisical-deep-research-results.md Part 5 Rank 7. Acquisition prompt: cowork/rank-7-approval-workflow-primitive-prompt.md.
2026-06-09 18:00:05 +00:00 · 2026-05-04 00:55:17 +00:00
parent 9c80894c3c
commit b4d1ad1c97
7 changed files with 579 additions and 0 deletions
@@ -27,6 +27,19 @@ import (
 // rather than substring-match.
 var ErrNotFound = errors.New("repository: row not found")

+// ErrAlreadyExists is the canonical sentinel for postgres unique-
+// constraint (SQLSTATE 23505) violations bubbling up from an INSERT
+// (or partial-unique INSERT, like Rank 7's idx_approval_pending_per_job
+// which enforces "at most one pending approval per job"). Handlers
+// that surface a 409 Conflict should
+// `errors.Is(err, repository.ErrAlreadyExists)`.
+//
+// The repo also reuses ErrAlreadyExists for "row is already terminal"
+// state-transition attempts (e.g., Approve called on an already-
+// approved request) — semantically the same "you're trying to create
+// a state that already exists" failure mode.
+var ErrAlreadyExists = errors.New("repository: row already exists")
+
 // ErrForeignKeyConstraint is the canonical sentinel for PostgreSQL
 // FK / RESTRICT violations bubbling up from a DELETE or UPDATE.
 // Handlers that surface a 409 Conflict should
@@ -713,3 +713,60 @@ type HealthCheckFilter struct {
 	// PerPage is the number of results per page.
 	PerPage int
 }
+
+// ApprovalRepository defines operations for managing issuance approval requests.
+// Rank 7 of the 2026-05-03 Infisical deep-research deliverable — closes the
+// two-person integrity / four-eyes principle procurement gap for PCI-DSS
+// Level 1, FedRAMP Moderate / High, SOC 2 Type II, HIPAA-regulated PHI.
+//
+// Lifecycle: Create inserts a row at state=pending; UpdateState transitions
+// to one of (approved, rejected, expired) with the decider identity +
+// timestamp + optional note; ExpireStale is the bulk reaper called from
+// the scheduler. Once terminal, rows are immutable via the
+// approval_decision_consistency CHECK constraint at the schema layer.
+type ApprovalRepository interface {
+	// Create inserts a new ApprovalRequest at state=pending. Returns
+	// ErrAlreadyExists if a pending request already exists for the
+	// job_id (the partial-unique index enforces at most one pending
+	// per job).
+	Create(ctx context.Context, req *domain.ApprovalRequest) error
+
+	// Get returns the request by ID or ErrNotFound.
+	Get(ctx context.Context, id string) (*domain.ApprovalRequest, error)
+
+	// GetByJobID returns the most-recently-created request for the
+	// given job_id, regardless of state. Used by the renewal entry
+	// point to detect "is there already a pending approval for this
+	// job?" and avoid creating a duplicate.
+	GetByJobID(ctx context.Context, jobID string) (*domain.ApprovalRequest, error)
+
+	// List returns approval requests filtered by ApprovalFilter.
+	// Supports paginated dashboard queries.
+	List(ctx context.Context, filter *ApprovalFilter) ([]*domain.ApprovalRequest, error)
+
+	// UpdateState transitions a row from state=pending to one of
+	// (approved, rejected, expired). Returns ErrNotFound if the ID
+	// does not exist; returns the schema's CHECK-violation as a
+	// repository error if the row is already terminal.
+	UpdateState(ctx context.Context, id string, state domain.ApprovalState,
+		decidedBy string, decidedAt time.Time, note string) error
+
+	// ExpireStale transitions every row with state=pending and
+	// created_at <= before to state=expired. Returns the number of
+	// rows transitioned. Called from the scheduler reaper loop.
+	ExpireStale(ctx context.Context, before time.Time) (int, error)
+}
+
+// ApprovalFilter filters approval-request queries.
+type ApprovalFilter struct {
+	// State filters by lifecycle state (pending, approved, rejected, expired).
+	State string
+	// CertificateID filters by managed certificate ID.
+	CertificateID string
+	// RequestedBy filters to requests created by the given actor.
+	RequestedBy string
+	// Page is the page number (1-indexed).
+	Page int
+	// PerPage is the number of results per page.
+	PerPage int
+}
@@ -0,0 +1,309 @@
+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"
+)
+
+// ApprovalRepository is the postgres implementation of
+// repository.ApprovalRepository. Rank 7 of the 2026-05-03 Infisical
+// deep-research deliverable.
+type ApprovalRepository struct {
+	db *sql.DB
+}
+
+// NewApprovalRepository constructs an ApprovalRepository against the
+// given *sql.DB. The schema is defined by migration
+// 000027_approval_workflow.up.sql.
+func NewApprovalRepository(db *sql.DB) *ApprovalRepository {
+	return &ApprovalRepository{db: db}
+}
+
+// Create inserts a new ApprovalRequest at state=pending. Generates the
+// ar-<slug> ID if req.ID is empty. Returns
+// repository.ErrAlreadyExists if the partial-unique index
+// (idx_approval_pending_per_job) trips — i.e., a pending request
+// already exists for the given job_id.
+func (r *ApprovalRepository) Create(ctx context.Context, req *domain.ApprovalRequest) error {
+	if req.ID == "" {
+		req.ID = "ar-" + uuid.NewString()
+	}
+	if req.State == "" {
+		req.State = domain.ApprovalStatePending
+	}
+	if !domain.IsValidApprovalState(req.State) {
+		return fmt.Errorf("invalid approval state %q", req.State)
+	}
+	now := time.Now().UTC()
+	if req.CreatedAt.IsZero() {
+		req.CreatedAt = now
+	}
+	if req.UpdatedAt.IsZero() {
+		req.UpdatedAt = now
+	}
+
+	metadataJSON, err := json.Marshal(req.Metadata)
+	if err != nil {
+		return fmt.Errorf("marshal approval metadata: %w", err)
+	}
+	if len(metadataJSON) == 0 || string(metadataJSON) == "null" {
+		metadataJSON = []byte("{}")
+	}
+
+	const q = `
+		INSERT INTO issuance_approval_requests
+			(id, certificate_id, job_id, profile_id, requested_by,
+			 state, decided_by, decided_at, decision_note, metadata,
+			 created_at, updated_at)
+		VALUES
+			($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
+	`
+
+	_, err = r.db.ExecContext(ctx, q,
+		req.ID, req.CertificateID, req.JobID, req.ProfileID, req.RequestedBy,
+		string(req.State), req.DecidedBy, req.DecidedAt, req.DecisionNote, metadataJSON,
+		req.CreatedAt, req.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 approval request: %w", err)
+	}
+	return nil
+}
+
+// Get returns the request by ID or repository.ErrNotFound.
+func (r *ApprovalRepository) Get(ctx context.Context, id string) (*domain.ApprovalRequest, error) {
+	const q = `
+		SELECT id, certificate_id, job_id, profile_id, requested_by,
+		       state, decided_by, decided_at, decision_note, metadata,
+		       created_at, updated_at
+		FROM   issuance_approval_requests
+		WHERE  id = $1
+	`
+	row := r.db.QueryRowContext(ctx, q, id)
+	return scanApprovalRow(row)
+}
+
+// GetByJobID returns the most-recently-created request for the given
+// job_id, regardless of state.
+func (r *ApprovalRepository) GetByJobID(ctx context.Context, jobID string) (*domain.ApprovalRequest, error) {
+	const q = `
+		SELECT id, certificate_id, job_id, profile_id, requested_by,
+		       state, decided_by, decided_at, decision_note, metadata,
+		       created_at, updated_at
+		FROM   issuance_approval_requests
+		WHERE  job_id = $1
+		ORDER  BY created_at DESC
+		LIMIT  1
+	`
+	row := r.db.QueryRowContext(ctx, q, jobID)
+	return scanApprovalRow(row)
+}
+
+// List returns approval requests filtered by repository.ApprovalFilter.
+// Supports paginated dashboard queries.
+func (r *ApprovalRepository) List(ctx context.Context, filter *repository.ApprovalFilter) ([]*domain.ApprovalRequest, error) {
+	if filter == nil {
+		filter = &repository.ApprovalFilter{}
+	}
+	page := filter.Page
+	if page < 1 {
+		page = 1
+	}
+	perPage := filter.PerPage
+	if perPage < 1 || perPage > 500 {
+		perPage = 50
+	}
+
+	q := `
+		SELECT id, certificate_id, job_id, profile_id, requested_by,
+		       state, decided_by, decided_at, decision_note, metadata,
+		       created_at, updated_at
+		FROM   issuance_approval_requests
+		WHERE  1 = 1
+	`
+	args := []interface{}{}
+	idx := 1
+	if filter.State != "" {
+		q += fmt.Sprintf(" AND state = $%d", idx)
+		args = append(args, filter.State)
+		idx++
+	}
+	if filter.CertificateID != "" {
+		q += fmt.Sprintf(" AND certificate_id = $%d", idx)
+		args = append(args, filter.CertificateID)
+		idx++
+	}
+	if filter.RequestedBy != "" {
+		q += fmt.Sprintf(" AND requested_by = $%d", idx)
+		args = append(args, filter.RequestedBy)
+		idx++
+	}
+	q += fmt.Sprintf(" ORDER BY created_at DESC LIMIT $%d OFFSET $%d", idx, idx+1)
+	args = append(args, perPage, (page-1)*perPage)
+
+	rows, err := r.db.QueryContext(ctx, q, args...)
+	if err != nil {
+		return nil, fmt.Errorf("list approval requests: %w", err)
+	}
+	defer rows.Close()
+
+	var out []*domain.ApprovalRequest
+	for rows.Next() {
+		req, err := scanApprovalRow(rows)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, req)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("iterate approval rows: %w", err)
+	}
+	return out, nil
+}
+
+// UpdateState transitions a row from state=pending to a terminal state.
+// Returns repository.ErrNotFound if the ID does not exist.
+//
+// The schema's approval_decision_consistency CHECK constraint enforces
+// that decided_by + decided_at MUST be non-null for terminal states,
+// so a same-state update on an already-decided row returns a
+// constraint-violation error from postgres.
+func (r *ApprovalRepository) UpdateState(ctx context.Context, id string, state domain.ApprovalState,
+	decidedBy string, decidedAt time.Time, note string) error {
+	if !domain.IsValidApprovalState(state) {
+		return fmt.Errorf("invalid approval state %q", state)
+	}
+	if !state.IsTerminal() {
+		return fmt.Errorf("UpdateState only accepts terminal states; got %q", state)
+	}
+
+	var notePtr *string
+	if note != "" {
+		notePtr = &note
+	}
+
+	const q = `
+		UPDATE issuance_approval_requests
+		SET    state         = $2,
+		       decided_by    = $3,
+		       decided_at    = $4,
+		       decision_note = $5,
+		       updated_at    = NOW()
+		WHERE  id = $1
+		  AND  state = 'pending'
+	`
+	res, err := r.db.ExecContext(ctx, q, id, string(state), decidedBy, decidedAt, notePtr)
+	if err != nil {
+		return fmt.Errorf("update approval state: %w", err)
+	}
+	n, err := res.RowsAffected()
+	if err != nil {
+		return fmt.Errorf("update approval rows affected: %w", err)
+	}
+	if n == 0 {
+		// Either the ID does not exist, or the row is already terminal.
+		// Disambiguate via a follow-up Get.
+		existing, getErr := r.Get(ctx, id)
+		if getErr != nil {
+			return getErr // ErrNotFound or scan error
+		}
+		if existing.State.IsTerminal() {
+			return repository.ErrAlreadyExists // signals "already decided"
+		}
+		return repository.ErrNotFound
+	}
+	return nil
+}
+
+// ExpireStale transitions every row with state=pending and created_at <=
+// before to state=expired. Returns the number of rows transitioned.
+//
+// The decided_at is stamped with time.Now() rather than `before` so
+// audit dashboards see the actual reaper-firing wall-clock, not the
+// reaper's deadline-cutoff input. The decided_by is set to a sentinel
+// "system-reaper" so SELECT FROM audit_events WHERE actor matches both
+// human-decided and reaper-decided rows for compliance review.
+func (r *ApprovalRepository) ExpireStale(ctx context.Context, before time.Time) (int, error) {
+	const q = `
+		UPDATE issuance_approval_requests
+		SET    state         = 'expired',
+		       decided_by    = 'system-reaper',
+		       decided_at    = NOW(),
+		       decision_note = 'auto-expired by scheduler reaper at CERTCTL_JOB_AWAITING_APPROVAL_TIMEOUT',
+		       updated_at    = NOW()
+		WHERE  state = 'pending'
+		  AND  created_at <= $1
+	`
+	res, err := r.db.ExecContext(ctx, q, before)
+	if err != nil {
+		return 0, fmt.Errorf("expire stale approvals: %w", err)
+	}
+	n, err := res.RowsAffected()
+	if err != nil {
+		return 0, fmt.Errorf("expire stale rows affected: %w", err)
+	}
+	return int(n), nil
+}
+
+// scanApprovalRow scans a single row into a *domain.ApprovalRequest.
+// Used by Get / GetByJobID (sql.Row) + List (*sql.Rows) — accepts the
+// rowScanner interface. JSONB metadata is unmarshaled defensively.
+type rowScanner interface {
+	Scan(dest ...interface{}) error
+}
+
+func scanApprovalRow(row rowScanner) (*domain.ApprovalRequest, error) {
+	var (
+		req          domain.ApprovalRequest
+		stateStr     string
+		decidedBy    sql.NullString
+		decidedAt    sql.NullTime
+		decisionNote sql.NullString
+		metadataJSON []byte
+	)
+	err := row.Scan(
+		&req.ID, &req.CertificateID, &req.JobID, &req.ProfileID, &req.RequestedBy,
+		&stateStr, &decidedBy, &decidedAt, &decisionNote, &metadataJSON,
+		&req.CreatedAt, &req.UpdatedAt,
+	)
+	if err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			return nil, repository.ErrNotFound
+		}
+		return nil, fmt.Errorf("scan approval row: %w", err)
+	}
+
+	req.State = domain.ApprovalState(stateStr)
+	if decidedBy.Valid {
+		s := decidedBy.String
+		req.DecidedBy = &s
+	}
+	if decidedAt.Valid {
+		t := decidedAt.Time
+		req.DecidedAt = &t
+	}
+	if decisionNote.Valid {
+		s := decisionNote.String
+		req.DecisionNote = &s
+	}
+	if len(metadataJSON) > 0 {
+		if err := json.Unmarshal(metadataJSON, &req.Metadata); err != nil {
+			return nil, fmt.Errorf("unmarshal approval metadata: %w", err)
+		}
+	}
+	return &req, nil
+}