From 884e33d43461ac71f823e0e923c4470af5cc7ebb Mon Sep 17 00:00:00 2001 From: Chris Roadfeldt Date: Tue, 16 Jun 2026 16:43:30 -0500 Subject: [PATCH 1/2] architecture: governance enforcement Policy profiles, accreditation monitor, registry enforcement, contribution pipeline. Signed-off-by: Chris Roadfeldt Signed-off-by: croadfeldt --- .../accreditation-monitor.md | 607 ++++++++ .../contribution-pipeline.md | 454 ++++++ .../governance-enforcement/policy-profiles.md | 1324 +++++++++++++++++ .../registry-enforcement.md | 387 +++++ 4 files changed, 2772 insertions(+) create mode 100644 architecture/governance-enforcement/accreditation-monitor.md create mode 100644 architecture/governance-enforcement/contribution-pipeline.md create mode 100644 architecture/governance-enforcement/policy-profiles.md create mode 100644 architecture/governance-enforcement/registry-enforcement.md diff --git a/architecture/governance-enforcement/accreditation-monitor.md b/architecture/governance-enforcement/accreditation-monitor.md new file mode 100644 index 0000000..875f97c --- /dev/null +++ b/architecture/governance-enforcement/accreditation-monitor.md @@ -0,0 +1,607 @@ +--- +Document Status: 📋 Draft — Ready for Implementation Feedback +Document Type: Capability Specification +Maps to: udlm/governance/accreditation-and-authorization-matrix.md +--- + +# DCM Data Model — Accreditation Monitor + +> **Implements contracts defined in UDLM**: +> [udlm/governance/accreditation-and-authorization-matrix.md](https://github.com/croadfeldt/udlm/blob/main/governance/accreditation-and-authorization-matrix.md). +> UDLM defines the accreditation entity, the authorization matrix, and the +> validity model. DCM operationalizes continuous external verification of +> accreditation status against authoritative sources. + +**Document Status:** 📋 Draft — Ready for Implementation Feedback +**Document Type:** Capability Specification +**Related Documents:** [Accreditation and Authorization Matrix](https://github.com/croadfeldt/udlm/blob/main/governance/accreditation-and-authorization-matrix.md) | [Information Providers](https://github.com/croadfeldt/udlm/blob/main/contracts/information-providers.md) | [Advanced Information Providers](https://github.com/croadfeldt/udlm/blob/main/contracts/information-providers-advanced.md) | [Standards Catalog](https://github.com/croadfeldt/udlm/blob/main/reference/standards-catalog.md) | [Scoring Model](../convergence-engine/scoring.md) | [Event Catalog](https://github.com/croadfeldt/udlm/blob/main/contracts/event-catalog.md) | [Governance Matrix](https://github.com/croadfeldt/udlm/blob/main/governance/governance-matrix.md) + +> **AEP Alignment:** API endpoints follow [AEP](https://aep.dev) conventions. +> Custom methods use colon syntax. Async operations return `Operation` resources. +> See `schemas/openapi/dcm-admin-api.yaml` for the normative admin API specification. + +--- + +## 1. Purpose + +The Accreditation Monitor is a DCM **Information Provider** that continuously verifies the status of registered accreditations against authoritative external sources — compliance registries, certificate authority portals, and contract management systems. It answers the question DCM's existing accreditation lifecycle model cannot answer alone: + +> *"Is this accreditation still valid according to the issuing authority — not just according to the expiry date we were told?"* + +An accreditation can become invalid before its declared `expires_at` date: FedRAMP authorizations can be revoked mid-cycle, ISO 27001 certificates can be suspended by the certification body, CMMC certifications can be downgraded. Without external monitoring, DCM would continue treating a provider as accredited until the date it was told to check — which may be 12 months away. + +The Accreditation Monitor closes this gap by polling authoritative external registries on a configurable schedule and surfacing discrepancies to DCM's existing accreditation lifecycle model. + +--- + +## 2. What Can Be Automated — Framework by Framework + +Automation depth varies significantly by framework. The Accreditation Monitor implements four verification tiers: + +### Tier 1 — Full External Verification (public registry API) + +DCM can query the authoritative registry directly. Status changes are detected without any manual intervention. + +| Framework | Authoritative Source | What Is Verified | +|-----------|---------------------|-----------------| +| **FedRAMP Moderate/High/LI-SaaS** | [marketplace.fedramp.gov/api](https://marketplace.fedramp.gov) | Authorization status (Authorized / In Process / Revoked), impact level, authorization date, annual assessment currency | +| **StateRAMP** | [stateramp.org](https://stateramp.org) | Authorization status, status changes | +| **CMMC 2.0** | [cyberab.org/catalog](https://cyberab.org/catalog) | Certification level (1/2/3), certification status, expiry date | +| **IAF / ISO 27001** | [iaf.nu CertSearch](https://iaf.nu) | Certificate status (valid/suspended/withdrawn), expiry date, scope, issuing CB identity | + +**Required field at registration:** `external_registry_id` — the provider's identifier in the external registry (FedRAMP ID, CMMC certification number, ISO certificate number). + +### Tier 2 — Document Currency Verification + +DCM cannot query a central registry, but it can verify that the stored evidence document is current relative to the framework's required renewal cycle. + +| Framework | Verification Method | Currency Check | +|-----------|---------------------|---------------| +| **SOC 2 Type I / Type II** | Document metadata extraction from `audit_report_ref` | Report period end date must be within 12 months (configurable); examines PDF metadata or report header | +| **PCI DSS** | QSA authorization check + AoC date | Verifies the issuing QSA firm is currently listed as authorized at PCI SSC; verifies stored AoC covers current period | +| **ISO 27001** (when CB portal is unavailable) | Certificate document date + P3Y renewal cycle | Falls back to document-based verification if IAF CertSearch is unreachable | + +### Tier 3 — Contract Lifecycle Integration + +No external registry exists. Verification is driven by events from contract management systems. + +| Framework | Integration Mechanism | What Triggers Verification | +|-----------|----------------------|--------------------------| +| **HIPAA BAA** | Contract management webhook (DocuSign, Ironclad, Agiloft, custom) | BAA signed, amended, terminated, or approaching renewal | +| **DoD IL2/IL4/IL5/IL6** | Manual submission + webhook on DISA action letter | Authorization letter received, amended, or revoked | +| **Custom / Sovereign** | Manual submission + optional webhook | Platform admin triggers; or custom webhook from issuing authority | + +### Tier 4 — Expiry-Only Monitoring (no external verification available) + +No external API, no document currency check, no contract integration. DCM monitors only the declared `expires_at` date. + +| Framework | What Is Monitored | +|-----------|-----------------| +| **HIPAA BAA** (if no contract system) | Declared BAA expiry date | +| **Internal / first_party accreditations** | Declared validity period | +| **Self-declared** | Declared validity period | + +--- + +## 3. Accreditation Record Additions + +The existing accreditation record (doc 26 Section 3.3) is extended with three new fields to support automated monitoring: + +```yaml +accreditation: + # ... existing fields unchanged ... + + # NEW — Verification model + verification: + tier: external_registry | document_currency | contract_webhook | expiry_only + # ── Tier 1 specific ── + registry_api: + provider: fedramp | stateramp | cmmc_ab | iaf_certsearch | custom + lookup_key: # e.g., FedRAMP ID "FR2024-0042" + poll_interval: P1D # how often to check + last_checked_at: + last_result: confirmed_active | status_changed | registry_unavailable | not_found + + # ── Tier 2 specific ── + document_check: + document_url: + max_age: P365D # how old the document can be + date_extraction_method: pdf_metadata | report_header_parse | manual + last_checked_at: + last_document_date: + + # ── Tier 3 specific ── + contract_webhook: + contract_system: docusign | ironclad | agiloft | custom + contract_id: + webhook_url: + last_event_at: + + # ── Shared ── + stale_after: P7D # how long before last_checked_at = stale + stale_action: warn | suspend | escalate # what to do when stale + verification_failure_count: 0 # consecutive failures; triggers escalation + verification_failure_threshold: 3 +``` + +The `last_verified_at` field on the existing accreditation record (doc 26) is updated by the Accreditation Monitor on each successful verification. It remains the canonical "last confirmed active" timestamp used by the Governance Matrix and Scoring Model. + +--- + +## 4. Accreditation Monitor as an Information Provider + +The Accreditation Monitor registers with DCM as an Information Provider with `information_type: accreditation_verification`. It is a separately deployable component — it does not require changes to the DCM control plane and can be upgraded independently. + +```yaml +accreditation_monitor_registration: + provider_type: information_provider + information_type: accreditation_verification + display_name: "DCM Accreditation Monitor" + version: "1.0.0" + + # What it monitors + supported_tiers: + - external_registry + - document_currency + - contract_webhook + - expiry_only + + supported_registries: + - fedramp + - stateramp + - cmmc_ab + - iaf_certsearch + - pci_ssc_qsa # QSA verification only + + supported_contract_systems: + - docusign + - ironclad + - custom_webhook + + # How it communicates results back to DCM + push_events: true + event_types: + - accreditation.verified # periodic confirmation: still active + - accreditation.status_changed # external registry shows different status + - accreditation.registry_mismatch # external status != DCM recorded status + - accreditation.verification_stale # last_checked_at exceeds stale_after threshold + - accreditation.expiry_approaching # approaching expires_at (supplement to existing) + - accreditation.document_expired # document_check: document older than max_age + - accreditation.contract_event # contract_webhook: BAA signed/amended/terminated + + health_check: + endpoint: /health + interval: PT5M +``` + +--- + +## 5. Verification Flows + +### 5.1 Tier 1 — FedRAMP External Registry Verification + +``` +Accreditation Monitor poll cycle (default: P1D): + │ + ▼ For each active Tier 1 accreditation: + │ Load accreditation record + │ Extract: framework, external_registry_id, last known status + │ + ▼ Query external registry: + │ FedRAMP: GET marketplace.fedramp.gov/api/products?id={external_registry_id} + │ CMMC: GET cyberab.org/api/certifications?cert_number={external_registry_id} + │ IAF: GET iaf.nu/certsearch?cert={external_registry_id} + │ + ├── Registry returns: status = Authorized, impact_level = High + │ Matches DCM record → no action + │ Update: last_checked_at, last_result: confirmed_active + │ Fire: accreditation.verified (urgency: low) + │ + ├── Registry returns: status = In Process (was Authorized) + │ Status changed → MISMATCH + │ Fire: accreditation.status_changed (urgency: high) + │ Payload: {from: authorized, to: in_process, external_source: fedramp_marketplace} + │ DCM action: accreditation status → pending_review + │ Platform Admin notified — human must review and decide: suspend or retain + │ + ├── Registry returns: status = Revoked + │ Fire: accreditation.status_changed (urgency: critical) + │ DCM action: accreditation status → revoked immediately + │ Accreditation Gap triggered for all affected providers + │ Recovery Policy evaluated + │ + ├── Registry returns: 404 / not_found + │ May indicate ID change or deregistration + │ Fire: accreditation.registry_mismatch (urgency: high) + │ Increment verification_failure_count + │ Platform Admin notified to verify external_registry_id is correct + │ + └── Registry unreachable (timeout, 5xx) + Update: last_result: registry_unavailable + Increment verification_failure_count + If count >= verification_failure_threshold: + Fire: accreditation.verification_stale (urgency: medium) + Do NOT change accreditation status on registry failure alone + (conservative: prefer false negative over false positive revocation) +``` + +### 5.2 Tier 2 — Document Currency Verification (SOC 2, PCI DSS AoC) + +``` +Verification cycle (default: P7D): + │ + ▼ Fetch document from certificate_ref or audit_report_ref URL + │ + ├── PDF: extract creation_date from PDF metadata + │ or parse report header for "Report Date: YYYY-MM-DD" + │ + ├── HTML report: parse structured date field + │ + └── Fallback: flag for manual review if date cannot be extracted + + ▼ Compare document date to max_age threshold (default P365D): + │ + ├── Within threshold → update last_checked_at, last_document_date + │ Fire: accreditation.verified (urgency: low) + │ + └── Beyond threshold → Fire: accreditation.document_expired (urgency: high) + Platform Admin notified: new report needed + Accreditation status → pending_renewal +``` + +### 5.3 Tier 3 — Contract Webhook (HIPAA BAA, DoD IL) + +``` +Contract management system fires webhook to DCM: + POST /api/v1/admin/accreditations/{uuid}/contract-event + + Payload: + { + "contract_id": "", + "event_type": "signed | amended | terminated | renewal_due | renewed", + "effective_date": "", + "details": { ... contract-system-specific fields ... } + } + + DCM processes: + ├── signed → accreditation status: active (if was pending) + ├── amended → accreditation status: pending_review; Platform Admin notified + ├── terminated → accreditation status: revoked; Accreditation Gap triggered + ├── renewal_due → notification to Compliance Team (urgency: medium) + └── renewed → accreditation status: active; expires_at updated; last_verified_at updated +``` + +### 5.4 Stale Verification Handling + +Regardless of tier, when `last_checked_at` is older than `stale_after`: + +``` +stale_action: warn → Fire: accreditation.verification_stale (urgency: low) + No change to accreditation status + +stale_action: suspend → Fire: accreditation.verification_stale (urgency: high) + Accreditation status → suspended + Accreditation Gap triggered (gap_type: suspended) + Platform Admin must manually verify and reactivate + +stale_action: escalate → Fire: accreditation.verification_stale (urgency: critical) + Escalation chain notified (Compliance Team + Platform Admin) + No automatic status change + If not resolved within escalation_window: → suspend +``` + +`stale_action` defaults by profile: `warn` for dev/standard, `suspend` for prod, `escalate` for fsi/sovereign. + +--- + +## 6. New Event Types (additions to doc 33) + +These events are added to the event catalog as domain `accreditation.*`: + +| Event Type | Urgency | Description | Key Payload Fields | +|-----------|---------|-------------|-------------------| +| `accreditation.verified` | low | Periodic external confirmation — accreditation still active | accreditation_uuid, framework, registry, checked_at | +| `accreditation.status_changed` | high or critical | External registry shows a different status than DCM records | accreditation_uuid, framework, from_status, to_status, external_source | +| `accreditation.registry_mismatch` | high | External registry cannot find the accreditation by its external_registry_id | accreditation_uuid, external_registry_id, registry, failure_detail | +| `accreditation.verification_stale` | varies | last_checked_at exceeds stale_after threshold | accreditation_uuid, last_checked_at, stale_after, stale_action_taken | +| `accreditation.document_expired` | high | Evidence document older than max_age threshold | accreditation_uuid, framework, document_url, document_date, max_age | +| `accreditation.contract_event` | varies | Contract management webhook received | accreditation_uuid, contract_event_type, contract_id, effective_date | +| `accreditation.expiry_approaching` | medium | Approaching expires_at within renewal_warning_before (supplement to existing TTL-based check) | accreditation_uuid, expires_at, days_remaining | + +--- + +## 7. Accreditation Record Additions to doc 26 + +The following fields are added to the accreditation record structure in doc 26 Section 3.3. +These are non-breaking additions — existing records without these fields default to `tier: expiry_only`. + +```yaml +# Additions to existing accreditation record (doc 26 Section 3.3) + + verification: + tier: external_registry | document_currency | contract_webhook | expiry_only + + # For external_registry tier: + registry_api: + provider: fedramp | stateramp | cmmc_ab | iaf_certsearch | pci_ssc_qsa | custom + lookup_key: # value to use as query key in registry + poll_interval: P1D # ISO 8601 duration; how often Monitor checks + last_checked_at: + last_result: confirmed_active | status_changed | registry_unavailable | not_found | pending + + # For document_currency tier: + document_check: + document_url: # usually same as certificate_ref or audit_report_ref + max_age: P365D # maximum acceptable document age + date_extraction_method: pdf_metadata | report_header_parse | manual + last_checked_at: + last_document_date: + + # For contract_webhook tier: + contract_webhook: + contract_system: docusign | ironclad | agiloft | custom + contract_id: # ID in the contract management system + webhook_configured: true | false + last_event_at: + + # Shared across all tiers: + stale_after: P7D # max acceptable gap between verifications + stale_action: warn | suspend | escalate + verification_failure_count: 0 + verification_failure_threshold: 3 +``` + +--- + +## 8. Impact on Scoring Model (doc 29) + +The Scoring Model's Signal 5 (Provider Accreditation Richness, doc 29 Section 4.5) is +enhanced with a verification currency dimension. An accreditation that has been externally +verified recently is worth more than one that has only ever been manually submitted. + +```yaml +# Addition to accreditation_weights in doc 29: +verification_multipliers: + # Applied to each accreditation's weight based on verification currency + external_registry_verified_within_P1D: 1.0 # full weight + external_registry_verified_within_P7D: 0.9 # slight discount + document_verified_within_P30D: 0.85 + contract_webhook_active: 0.9 + expiry_only_no_external_check: 0.7 # meaningful discount + verification_stale: 0.4 # significant discount + verification_failed_threshold_reached: 0.1 # near-zero weight +``` + +This means a provider with a FedRAMP High accreditation that was externally verified +yesterday scores higher in placement tie-breaking than a provider with the same +accreditation whose verification check has been stale for 30 days. + +--- + +## 9. Admin API Additions + +``` +# List all accreditations with their current verification status +GET /api/v1/admin/accreditations + ?verification_status=stale|failed|confirmed|pending + &framework=fedramp_high|iso_27001|... + &subject_uuid={provider_uuid} + page_size=50&page_token=... + +# Trigger immediate re-verification of a specific accreditation +POST /api/v1/admin/accreditations/{accreditation_uuid}:verify + +Response 200 — returns Operation: + { + "name": "/api/v1/operations/{uuid}", + "done": false, + "metadata": { + "stage": "VERIFICATION_INITIATED", + "accreditation_uuid": "{uuid}", + "verification_tier": "external_registry" + } + } + +# Register a contract webhook endpoint for a BAA or DoD IL accreditation +POST /api/v1/admin/accreditations/{accreditation_uuid}:configure-webhook + { + "contract_system": "docusign", + "contract_id": "abc-def-123", + "webhook_secret": "" + } + +# Inbound webhook endpoint (called by contract management systems) +POST /api/v1/admin/accreditations/{accreditation_uuid}/contract-event + Authorization: Bearer + { + "contract_event_type": "terminated", + "effective_date": "2026-04-01", + "contract_id": "abc-def-123", + "details": {} + } +``` + +--- + +## 10. Deployment and Configuration + +The Accreditation Monitor is deployed as a standalone container alongside the DCM control plane. It requires: + +- Network access to external registries (FedRAMP, CMMC AB, IAF CertSearch, PCI SSC) +- Network access to the DCM API Gateway (to push accreditation events) +- Access to `certificate_ref` and `audit_report_ref` document URLs (for Tier 2 checks) +- Inbound webhook endpoint (for Tier 3 contract system integrations) + +**Air-gapped / sovereign deployments:** For deployments without external internet access, the Accreditation Monitor operates in Tier 4 (expiry-only) mode by default for all frameworks. Tier 2 checks can still work if documents are stored on internal object storage (certificate_ref points to an internal URL). Tier 3 contract webhooks work if the contract management system is internal. Tier 1 registry checks are disabled — a manual verification workflow applies instead, with platform admins periodically updating `last_verified_at` after out-of-band confirmation. + +```yaml +accreditation_monitor_config: + # Per-registry enable/disable + registries: + fedramp: + enabled: true + poll_interval: P1D + timeout: PT30S + cmmc_ab: + enabled: true + poll_interval: P7D + iaf_certsearch: + enabled: true + poll_interval: P7D + stateramp: + enabled: false # enable if state/local gov providers present + + # Document currency checks + document_checks: + enabled: true + default_max_age: P365D + extraction_timeout: PT60S + + # Air-gapped mode + air_gapped_mode: false + air_gapped_fallback: expiry_only | manual_workflow + + # Global escalation + global_stale_after: P7D + global_failure_threshold: 3 + escalation_contact: + service_provider_uuid: + urgency: critical +``` + +--- + +## 11. System Policies + +| Policy | Rule | +|--------|------| +| `ACM-001` | The Accreditation Monitor is the authoritative source for `last_verified_at` on accreditation records. Platform admins may update it manually only when the Monitor is unavailable or in air-gapped mode — all manual updates require a justification reason stored in the audit trail. | +| `ACM-002` | An accreditation status change detected by the Monitor (external registry reports different status than DCM) does not automatically revoke the accreditation. It fires `accreditation.status_changed` and sets status to `pending_review`. A platform admin must confirm the change. The exception: if the external status is `Revoked` or `Terminated`, DCM immediately sets accreditation status to `revoked` without waiting for admin confirmation. | +| `ACM-003` | Verification failure (registry unreachable, document inaccessible) does not revoke an accreditation. The Monitor increments `verification_failure_count`. At `verification_failure_threshold`, it fires `accreditation.verification_stale` and applies `stale_action`. Failure itself does not constitute a gap — only confirmed negative status does. | +| `ACM-004` | Accreditations in `sovereign` and `fsi` profiles must have `verification.tier` declared at a level of `document_currency` or above. `expiry_only` is not permitted for sovereign/fsi accreditations unless `air_gapped_mode: true` is explicitly configured. | +| `ACM-005` | The `verification_multipliers` in the Scoring Model (Signal 5) apply to all accreditations, including those submitted before the Accreditation Monitor was deployed. Legacy accreditations with no `last_checked_at` are treated as `verification_stale` and weighted at the stale multiplier (0.4) until the Monitor performs its first check. | +| `ACM-006` | Inbound contract webhooks (Tier 3) must authenticate using a provider callback credential issued at accreditation configuration time. Unauthenticated webhook calls are rejected with `401 Unauthorized` and generate an audit record. | +| `ACM-007` | All verification events (`accreditation.*`) are written to the Audit Store regardless of outcome. There are no silent verifications — every check, success or failure, has an audit record. | +| `ACM-008` | In air-gapped mode, the Monitor operates in Tier 4 for registries it cannot reach. It does not repeatedly attempt unreachable external registries. After `air_gapped_retry_interval` (default P30D), it retries once to detect if network access has been restored. | + +--- + +## 12. Relationship to Existing Architecture + +### doc 26 — Accreditation and Authorization Matrix +The Accreditation Monitor extends but does not replace the accreditation lifecycle model in doc 26. The existing `proposed → active → expired/revoked` lifecycle is preserved. The Monitor adds automated transitions into `pending_review` and `pending_renewal` states, and provides the data that drives the existing `ACCREDITATION_GAP` logic. + +### doc 27 — Governance Matrix +The Governance Matrix already evaluates accreditation status as part of Check 3 of the five-check boundary model. The Monitor improves the quality of that check: instead of relying solely on the declared `expires_at` date, the Governance Matrix now has access to externally verified current status via `last_verified_at` and `last_result`. + +### doc 29 — Scoring Model +The `verification_multipliers` addition to Signal 5 (Provider Accreditation Richness) means placement decisions can prefer providers whose accreditations have been recently externally verified over those relying on self-declared or stale verifications. This is a conservative, progressive enhancement — it does not block placement, only refines tie-breaking. + +### doc 33 — Event Catalog +Seven new `accreditation.*` events are added (Section 6 of this document). These follow the same envelope and urgency model as all other DCM events. + +### doc 40 — Standards Catalog +The Accreditation Monitor is the operational implementation of the standards catalog's compliance framework entries. The standards catalog says *what* DCM recognizes; the Accreditation Monitor says *how* DCM verifies that recognition is still current. + +--- + +*Document maintained by the DCM Project. For questions or contributions see [GitHub](https://github.com/dcm-project).* + +--- + +## 13. Accreditation Governance Enforcement + +> **Implements contracts defined in UDLM**: +> [udlm/governance/accreditation-and-authorization-matrix.md](https://github.com/croadfeldt/udlm/blob/main/governance/accreditation-and-authorization-matrix.md). +> UDLM defines the accreditation model, lifecycle, and authorization matrix. +> This section operationalizes the governance enforcement DCM applies on +> top of the Accreditation Monitor. + +### 13.1 Accreditation gap response + +When a required accreditation becomes missing, expired, or revoked, DCM +enters an Accreditation Gap state for the affected provider: + +```yaml +accreditation_gap_record: + uuid: + provider_uuid: + required_framework: hipaa + required_for: [phi data fields in active requests] + gap_type: missing | expired | revoked | suspended | verification_stale + detected_at: + severity: critical # accreditation gaps are always high or critical + affected_entity_uuids: [] # entities currently hosted at this provider + policy_response: + # Default: NOTIFY_AND_WAIT for fsi/sovereign; ESCALATE for standard/prod +``` + +The Recovery Policy evaluation runs through the standard +[`../convergence-engine/recovery-and-retry.md`](../convergence-engine/recovery-and-retry.md) +mechanism — accreditation gaps are first-class recovery triggers. + +### 13.2 Authorization evaluation at runtime + +The Governance Matrix evaluator (see +[`../convergence-engine/policy-evaluation.md`](../convergence-engine/policy-evaluation.md)) +consults Accreditation Monitor data on every outbound interaction. The +matrix evaluator: + +1. Resolves required accreditation from the data axis (e.g., PHI requires + HIPAA BAA) +2. Queries the target's active accreditations via the Accreditation Monitor +3. Verifies the accreditation is current and not suspended (via + `last_verified_at` and `last_result`) +4. Returns ALLOW / DENY / STRIP_FIELD per the matrix rule + +The Accreditation Monitor's verification currency (Section 8) feeds into +matrix evaluation: an accreditation with stale verification produces a +weaker effective trust than one externally verified yesterday. + +### 13.3 DCM deployment accreditation + +DCM deployments themselves can carry accreditations (a FedRAMP-authorized +DCM deployment, for example). DCM enforces: + +- `subject_type: dcm_deployment` accreditations registered as standard + accreditation artifacts +- Federation peer DCMs verify each other's deployment accreditation before + accepting federation messages (see + [`../runtime-features/federation-runtime.md`](../runtime-features/federation-runtime.md)) +- Accreditation Monitor verifies deployment accreditations on the same + schedule as provider accreditations + +### 13.4 Profile-governed accreditation constraints + +```yaml +accreditation_profile_config: + minimal: + verification_tier_minimum: expiry_only + air_gapped_fallback: expiry_only + stale_action_default: warn + + dev: + verification_tier_minimum: expiry_only + stale_action_default: warn + + standard: + verification_tier_minimum: document_currency + stale_action_default: warn + + prod: + verification_tier_minimum: document_currency + stale_action_default: escalate + + fsi: + verification_tier_minimum: external_registry + # ACM-004: expiry_only NOT permitted unless air_gapped_mode: true + stale_action_default: suspend + + sovereign: + verification_tier_minimum: external_registry + stale_action_default: suspend +``` + +These are enforced at accreditation registration: an accreditation with +`tier: expiry_only` in `fsi`/`sovereign` profile is rejected unless +`air_gapped_mode: true` is explicitly configured (`ACM-004`). diff --git a/architecture/governance-enforcement/contribution-pipeline.md b/architecture/governance-enforcement/contribution-pipeline.md new file mode 100644 index 0000000..c827fb3 --- /dev/null +++ b/architecture/governance-enforcement/contribution-pipeline.md @@ -0,0 +1,454 @@ +--- +Document Status: ✅ Stable — DCM implementation +Document Type: Architecture Reference — Contribution Pipeline +Established: 2026-05-26 +Maps to: udlm/governance/federated-contribution-model.md +--- + +# Contribution Pipeline + +> **Implements contracts defined in UDLM**: +> [udlm/governance/federated-contribution-model.md](https://github.com/croadfeldt/udlm/blob/main/governance/federated-contribution-model.md). +> UDLM defines the four contributor types (Platform Admin, Consumer/Tenant, +> Service Provider, Peer DCM), the contribution artifact types, the +> universal contribution pipeline, and what each contributor type may +> contribute (the wire-level contract that defines who may write what). DCM +> operationalizes the contribution store structure, the review queue and +> approval workflow (GitOps PR mechanics), the pipeline orchestration, +> consumer/provider/federation contribution enforcement. + +> **DCM-specific choice:** DCM uses GitOps PR workflow as its specific +> contribution transport. A peer DCM realization could use a different +> review channel (an internal review API, a custom UI, etc.) and still +> conform to the UDLM contributor + artifact contract. + +--- + +## 1. Contribution store structure + +All contributed artifacts are stored in the GitOps store with contributor +attribution. DCM uses this directory structure: + +``` +dcm-policy-store/ + system/ # Platform admin authored; DCM built-in + compliance/ + governance/ + orchestration/ + platform/ # Platform admin authored; deployment-specific + security/ + operations/ + tenant/ + / # Consumer/Tenant authored + gatekeeper/ + transformation/ + groups/ + provider/ + / # Provider authored + layers/ + policies/ + federated/ + / # Peer DCM contributed + registry/ + policy-templates/ + +dcm-registry/ + core/ # DCM project maintained + community/ # Community contributed (via community DCM) + / + organization/ # Organization contributed + / +``` + +### 1.1 Contributor attribution + +Every artifact in the store includes a `contributed_by` block in artifact +metadata: + +```yaml +artifact_metadata: + uuid: + handle: "tenant/payments/gatekeeper/cost-ceiling" + version: "1.0.0" + status: active + contributed_by: + contributor_type: consumer # platform_admin | consumer | service_provider | peer_dcm + actor_uuid: + tenant_uuid: # for consumer contributions + provider_uuid: # for provider contributions + peer_dcm_uuid: # for federation contributions + contribution_method: api # api | flow_gui | git_pr | federation_push + pr_url: "https://..." # if submitted via PR + reviewed_by: [] + reviewed_at: +``` + +`contributed_by` is immutable (`FCM-001`); set at creation, never modified. + +--- + +## 2. Review queue and approval workflow (GitOps PR mechanics) + +### 2.1 The universal contribution pipeline + +``` +Contributor authors an artifact + │ via one of three contribution surfaces: + ├── Flow GUI Canvas / Policy Authoring Interface + ├── Direct API: POST /api/v1/contribute/{artifact_type} + └── Git PR directly to target repository + ▼ Artifact submitted → status: developing (local only) + ▼ Contributor submits for review → status: proposed + │ For policies: shadow mode activates automatically + │ For other artifacts: staged in proposed state + ▼ Governance Matrix evaluates the contribution: + │ Is this contributor permitted to contribute this artifact type? + │ Is the artifact in the correct domain for this contributor? + │ Does the artifact pass structural validation? + │ DENY → rejected with reason; no further processing + ▼ Review flow (per profile + artifact type): + │ auto: artifact activates immediately + │ reviewed: one platform admin or designated reviewer approves + │ verified: two independent reviewers approve + │ authorized: N members of declared authority group record decisions + ▼ On approval → status: active + │ For policies: shadow mode results reviewed; full enforcement begins + │ For registry entries: available in registry + │ For catalog items: visible in service catalog (per RBAC) + ▼ Lifecycle managed by contributor (deprecate, retire) + Subject to platform admin override at any time +``` + +### 2.2 GitOps PR mechanics + +For Git-PR contributions: + +1. Contributor opens PR against the relevant repository (policy store, + registry, layers) +2. PR template enforces required metadata: contributor type, target domain, + review type, justification +3. CI runs automated validation (schema, structural, dependency resolution, + breaking change detector) +4. DCM's GitOps Adapter watches for PRs; on PR open, posts a Governance + Matrix evaluation result as a status check +5. If matrix DENY: PR blocked; comment explains why +6. If matrix ALLOW (or ALLOW_WITH_CONDITIONS): review continues via the + normal Git platform workflow (reviewer assignment, comments, approval) +7. On approval and CI green: PR merges; artifact transitions to `proposed` +8. Shadow validation period runs (per `shadow_review_period`) +9. After shadow period, artifact transitions to `active` + +### 2.3 Direct API contribution + +For API contributions (`POST /api/v1/contribute/{artifact_type}`): + +1. Request body includes the artifact YAML/JSON + contribution metadata +2. DCM Contribution Service runs structural validation +3. Governance Matrix evaluates; DENY returns 403 with rule_uuid +4. On ALLOW: artifact written to the contribution store with status + `proposed`; shadow mode activates if policy +5. If `review_type: auto` per active profile: artifact transitions to + `active` immediately +6. Otherwise: review pipeline kicks off (notification to required reviewers, + PR URL returned for tracking) + +Response includes: +- `contribution_uuid` +- `status` +- `review_required` +- `review_type` +- `reviewer_group` +- `pr_url` (if PR-based review applies) +- `shadow_results_url` (for policies) + +--- + +## 3. Pipeline orchestration + +The Contribution Service orchestrates the pipeline: + +| Stage | DCM service | +|---|---| +| Submission | API Gateway → Contribution Service | +| Validation | Contribution Service (structural) + Policy Manager (Governance Matrix) | +| Storage | GitOps Adapter (PR creation) OR Policy Store DB write | +| Notification | Notification Router (notifies reviewers per active profile) | +| Review tracking | Approval Manager (tracks decisions, quorum, deadline) | +| Shadow mode | Policy Manager (evaluates new policy in shadow against live traffic) | +| Activation | Policy Manager (transitions status, recompiles rule set, emits `policy.activated`) | + +Every stage emits an event to `pipeline_events`; downstream services +subscribe via `LISTEN/NOTIFY`. + +--- + +## 4. Consumer contribution enforcement + +DCM enforces consumer contribution scope at submission time. A consumer +submitting a policy with `domain: tenant` must belong to that Tenant; the +Governance Matrix evaluator checks this and rejects domain scope violations. + +```yaml +# DCM ships this rule pre-activated +governance_matrix_rule: + handle: "system/matrix/consumer-policy-scope" + enforcement: hard + match: + subject.type: consumer + data.artifact_type: policy + data.domain: [system, platform] # consumer attempting non-tenant domain + decision: DENY + reason: "Consumers may only contribute tenant-domain policies" +``` + +### 4.1 Consumer contribution API + +``` +POST /api/v1/contribute/policy +Authorization: Bearer +X-DCM-Tenant: +{ + "policy_type": "gatekeeper", + "handle": "tenant/payments/gatekeeper/cost-ceiling", + "domain": "tenant", + "concern_type": "operational", + "enforcement": "soft", + "match": {...}, + "output": {...}, + "shadow_mode": true, + "commit_message": "Add monthly cost ceiling GateKeeper for Payments Tenant" +} + +Response 202: +{ + "contribution_uuid": "", + "policy_handle": "tenant/payments/gatekeeper/cost-ceiling", + "status": "proposed", + "shadow_mode": true, + "review_required": true, + "review_type": "reviewed", + "reviewer_group": "platform-admins", + "pr_url": "https://git.corp.example.com/dcm-policies/pulls/145", + "shadow_results_url": "/flow/api/v1/shadow/" +} +``` + +--- + +## 5. Provider contribution integration + +Providers contribute Resource Type Specs, Provider Catalog Items, Service +Layers, and provider-specific policies. DCM enforces: + +- Only the resource types declared at registration (`subject.declared_resource_types`) +- Catalog Items only for resource types the provider offers +- Service Layers only for resource types the provider offers +- Provider-domain policies only + +```yaml +# DCM ships this rule pre-activated +governance_matrix_rule: + handle: "system/matrix/provider-spec-scope" + enforcement: hard + match: + subject.type: service_provider + data.artifact_type: resource_type_spec + data.resource_type_fqn: + not_in: subject.declared_resource_types + decision: DENY + reason: "Providers may only contribute Resource Type Specs for resource types they offer" +``` + +### 5.1 Provider contribution API + +``` +POST /api/v1/provider/contribute/resource-type-spec +Authorization: mTLS + provider credential + +{ + "resource_type_fqn": "Storage.DistributedVolume", + "tier": "organization", + "version": "1.0.0", + "schema": {...}, + "portability_class": "provider_specific", + "commit_message": "Publish DistributedVolume resource type v1.0.0" +} +``` + +The submission is authenticated per +[`../credentials-and-auth/provider-callback.md`](../credentials-and-auth/provider-callback.md). + +--- + +## 6. Federation contribution synchronization + +Federation peers contribute artifacts subject to their federation trust +posture: + +| Peer trust posture | Review requirement | Artifact types permitted | +|---|---|---| +| `verified` | reviewed (standard+); auto (dev) | Registry entries, policy templates, service layers | +| `vouched` | reviewed always | Registry entries, service layers only | +| `provisional` | `authorized` tier approval | Registry entries only (no policies) | + +### 6.1 Federation contribution flow + +``` +Peer DCM publishes a contribution bundle: + Content: resource type specs, policy templates, or layers + Transport: federation tunnel (mTLS, signed, scoped credential) + Metadata: contributing_dcm_uuid, trust_posture, artifact_list + +Receiving DCM evaluates: + 1. Governance Matrix: is this peer permitted to contribute this artifact type? + 2. Signature verification: bundle signed by peer's private key? + 3. Structural validation: artifacts conform to DCM schemas? + 4. Domain scope check: artifacts within peer's permitted domain? + +On validation pass: + Artifacts enter proposed status in receiving DCM's policy/registry store + Review flow per receiving DCM's profile + peer trust posture + +On approval: + Artifacts become active in receiving DCM + Source attribution: contributed_by.dcm_uuid, contributed_by.trust_posture +``` + +### 6.2 Hub-spoke policy distribution + +In Hub-Spoke federation, Regional DCMs may subscribe to the Hub's policy +distribution feed: + +```yaml +hub_policy_distribution: + hub_dcm_uuid: + distribution_type: push # Hub pushes on policy change + auto_approve_from_hub: # profile-governed + minimal: true + dev: true + standard: true + prod: false # reviewed required even from verified Hub + fsi: false # verified required + sovereign: false # authorized approval required + policy_handles_subscribed: + - "system/compliance/hipaa/*" + - "system/governance/drift-remediation" +``` + +**Regional DCM always reviews before activating.** Hub cannot force-activate +policies on Regional DCMs. + +--- + +## 7. Artifact lifecycle across contributors + +### 7.1 Ownership and transfer + +Every artifact is owned by its contributor at creation. Transfer: + +- Consumer-authored policies transfer to a new Tenant admin when original + actor departs +- Provider-contributed catalog items remain owned by the provider registration +- Federation-contributed artifacts are owned by the contributing peer DCM + +Ownership transfer requires receiving owner's explicit acceptance. + +### 7.2 Platform admin override + +Platform admins can override any contributor's artifact lifecycle at any +time: + +- Suspend an active consumer-authored policy causing harm +- Retire a provider-contributed resource type spec no longer safe +- Reject a proposed federation contribution without public reason (security + discretion) + +Override actions are always audited with overriding admin's actor UUID and +reason (`FCM-005`). + +### 7.3 Deprecation and sunset + +Contributors deprecate their own artifacts: + +1. Notification to all consumers of the artifact +2. Sunset period declared (minimum P30D standard; P90D for prod/fsi/sovereign) +3. During sunset: new use warned; existing resources unaffected +4. After sunset: new use blocked +5. Platform admin confirms final retirement + +### 7.4 Orphaned artifacts + +When a contributor's access is revoked: + +- Active artifacts remain active — orphaned artifacts do not auto-deactivate +- Platform admin notified: "Artifact X has no active owner" +- Platform admin assigns new owner or explicitly retires +- Auto-retire-on-orphan is configurable per profile (`FCM-006`; enabled in + `sovereign`) + +--- + +## 8. Profile-governed contribution defaults + +```yaml +contribution_policy: + minimal: + consumer_policy_auto_approve: true + provider_spec_auto_approve: true + federation_contribution_auto_approve: true + shadow_mode_default: true # security: shadow always on + + dev: + consumer_policy_auto_approve: true + provider_spec_auto_approve: true + federation_contribution_auto_approve: false + shadow_mode_default: true + + standard: + consumer_policy_auto_approve: false + provider_spec_auto_approve: false + federation_contribution_auto_approve: false + shadow_mode_default: true + shadow_review_period: P7D + + prod: + consumer_policy_auto_approve: false + consumer_governance_matrix_requires: verified + provider_spec_requires: reviewed + federation_contribution_requires: reviewed + shadow_mode_default: true + shadow_review_period: P14D + + fsi: + consumer_policy_requires: verified + consumer_governance_matrix_requires: verified + provider_spec_requires: verified + federation_contribution_requires: verified + shadow_mode_default: true + shadow_review_period: P30D + min_shadow_divergence_review: true + + sovereign: + consumer_policy_requires: authorized + provider_spec_requires: authorized + federation_contribution_requires: authorized + shadow_mode_default: true + shadow_review_period: P30D + min_shadow_divergence_review: true + auto_retire_orphaned_artifacts: true +``` + +--- + +## 9. Policy IDs (DCM realization) + +| Policy | Rule | +|---|---| +| `FCM-001-DCM` | DCM records `contributed_by` in artifact_metadata at creation; immutable | +| `FCM-002-DCM` | DCM enforces contributor permissions via Governance Matrix at submission; domain scope violations are hard DENY | +| `FCM-003-DCM` | DCM routes all contributions through the GitOps PR model unless profile grants auto-approval | +| `FCM-004-DCM` | DCM enters new policies in proposed (shadow) status by default; shadow results available before shadow_review_period expires | +| `FCM-005-DCM` | DCM permits platform admin override of any contributor's artifact lifecycle; override is audited | +| `FCM-006-DCM` | DCM does not auto-deactivate orphaned artifacts; platform admin assigns new owner or retires; sovereign profile auto-retires | +| `FCM-007-DCM` | DCM scopes federation contributions by peer trust posture: verified → reviewed (standard+); vouched → reviewed always; provisional → authorized | +| `FCM-008-DCM` | DCM enforces absolute contributor-tier scope limits; consumer-authored tenant-domain policies cannot affect system/platform domain regardless of declared match conditions | diff --git a/architecture/governance-enforcement/policy-profiles.md b/architecture/governance-enforcement/policy-profiles.md new file mode 100644 index 0000000..225f8b7 --- /dev/null +++ b/architecture/governance-enforcement/policy-profiles.md @@ -0,0 +1,1324 @@ +--- +Document Status: ✅ Complete +Document Type: Architecture Reference — Policy Organization +Maps to: udlm/observability/universal-groups.md +--- + +# DCM Data Model — Policy Organization: Groups, Profiles, and External Policy Evaluators + +> **Implements contracts defined in UDLM**: +> [udlm/observability/universal-groups.md](https://github.com/croadfeldt/udlm/blob/main/observability/universal-groups.md). +> UDLM defines the Universal Group Model — composable, cross-type group +> membership and the profile/collection grouping contract. DCM operationalizes +> Policy Groups (`group_class: policy_collection`) and Policy Profiles +> (`group_class: policy_profile`) as concrete expressions of that model, plus +> the external policy evaluator integration. + +> **Universal Group Model:** Policy Groups (`group_class: policy_collection`) and Policy Profiles (`group_class: policy_profile`) are expressions of the [Universal Group Model](https://github.com/croadfeldt/udlm/blob/main/observability/universal-groups.md). The structures defined in this document remain authoritative for policy-specific behavior; the universal model adds composability, cross-type membership, and the ability to include policy groups within composite groups. + +**Document Status:** ✅ Complete +**Related Documents:** [Scoring Model](../convergence-engine/scoring.md) | [Context and Purpose](https://github.com/croadfeldt/udlm/blob/main/foundations/context-and-purpose.md) | [Data Layers and Assembly](https://github.com/croadfeldt/udlm/blob/main/foundations/layering-and-versioning.md) | [Entity Relationships](https://github.com/croadfeldt/udlm/blob/main/entities/entity-relationships.md) | [data stores](https://github.com/croadfeldt/udlm/blob/main/contracts/storage-providers.md) + +> **Foundation Document Reference** +> +> This document is a detailed reference for a specific domain of the DCM architecture. +> The three foundational abstractions — Data, Provider, and Policy — are defined in +> [foundations.md](https://github.com/croadfeldt/udlm/blob/main/foundations/foundations.md). All concepts in this document map to one or +> more of those three abstractions. +> See also: [Provider Contract](https://github.com/croadfeldt/udlm/blob/main/contracts/provider-contract.md) | [Policy Contract](https://github.com/croadfeldt/udlm/blob/main/contracts/policy-contract.md) +> +> **This document maps to: DATA + POLICY** +> +> Data: Policy Group and Profile artifacts. Policy: concern types and composition + + + +--- + +> **Standards and Compliance Reference:** See [Standards and Compliance Catalog](https://github.com/croadfeldt/udlm/blob/main/reference/standards-catalog.md) for the complete mapping of compliance frameworks (HIPAA, PCI DSS, FedRAMP, NIST SP 800-53, GDPR, DoD IL4) to DCM profiles and system requirements. + +## 1. Purpose + +DCM's Policy Engine is powerful — but power without usability is a barrier to adoption. This document defines the **policy organization model**: the structures that make DCM easy to configure correctly for any use case, from a home lab evaluation to a sovereign financial services deployment. + +Three concepts work together: + +- **Policy Groups** — cohesive collections of policies addressing a single identifiable concern (a technology, a compliance standard, a sovereignty requirement, a business process) +- **Policy Profiles** — complete DCM configurations for a specific use case, composed of Policy Groups +- **External Policy Evaluators** — external authoritative sources that supply policies directly into DCM, extending the provider model to its fifth type + +The relationship is compositional: + +``` +Policy Profile — complete use-case configuration + │ composed of + ▼ +Policy Groups — single-concern policy collections + │ composed of + ▼ +Policies — individual Transformation / Validation / GateKeeper rules + │ optionally sourced from + ▼ +External Policy Evaluators — external authoritative policy sources +``` + +--- + +## 1a. Design Priority Order in Policy Profiles + +Profiles implement the DCM design priority order (see [Foundational Abstractions](https://github.com/croadfeldt/udlm/blob/main/foundations/foundations.md)): + +1. **Security:** Profile defaults implement security correctly. Lower profiles have less strict enforcement — not absent security. +2. **Ease of use:** Profile defaults minimize configuration burden. `standard` profile should work for most deployments without customization. +3. **Extensibility:** Profiles compose with compliance domain overlays. Organizations add compliance requirements additively without rewriting base configuration. +4. **Fit for purpose:** Every profile must support the complete DCM lifecycle. + +**The `minimal` profile is not "security optional"** — it is the security model with minimal operational overhead. All security properties are present; thresholds and automation levels are relaxed. + +--- + +## 1b. Policy Authorship — Federated Contribution Model + +Policies in DCM are not exclusively authored by platform admins. The DCM federated contribution model enables all actor types to author policies within their permitted domain scope: + +- **Platform admins** — all domains, all policy types +- **Consumers / Tenant admins** — tenant domain policies (GateKeeper, Transformation, Recovery, Lifecycle, Orchestration Flow, Governance Matrix rules scoped to their Tenant) +- **Service Providers** — provider-domain GateKeeper and Validation policies for their resource types +- **Peer DCM instances** — policy templates contributed through verified federation relationships + +This is not a special case — it is the standard GitOps PR model applied to all contributor types. Consumer-authored policies go through the same lifecycle (developing → proposed → active) with appropriate review requirements per the active profile. See [Federated Contribution Model](https://github.com/croadfeldt/udlm/blob/main/governance/federated-contribution-model.md) for the complete specification. + +--- + +## 2. Policy Groups +## 1a. Two-Dimensional Profile Model + + +### 1a.0 Profile — One Posture, Multiple Compliance Domains + +**A DCM deployment runs exactly one Deployment Posture and zero or more Compliance Domain Groups simultaneously.** This is the complete profile model. No new concept is needed. + +``` +Active DCM Governance = one Deployment Posture + [zero or more Compliance Domains] + +Examples: + prod + hipaa ← healthcare production + prod + hipaa + gdpr ← EU healthcare production + sovereign + fedramp-high + dod-il5 ← classified federal + standard ← general enterprise, no compliance overlay + dev + hipaa ← healthcare development (hipaa policies active, + but operational cost reduced by dev posture) +``` + +**Deployment Postures are mutually exclusive** — you cannot be both `prod` and `dev`. One posture governs the operational characteristics of the entire DCM deployment. + +**Compliance domains are additive** — HIPAA + FSI is valid and common. Each compliance domain group adds its own set of policies and constraints on top of the posture. They do not conflict with each other at the domain level (they govern different aspects of data handling); they may produce policy conflicts at the field level, which are resolved through the standard policy conflict resolution process. + +**The dev posture and compliance domains** — applying `dev` posture to a HIPAA-scoped deployment does not remove HIPAA obligations. It relaxes the *operational cost* of meeting them: less redundancy, shorter retention windows where permitted, advisory enforcement where HIPAA allows flexibility. The HIPAA compliance domain group remains active and its mandatory controls remain enforced. + +**Modules vs Profiles** — DCM uses both concepts with distinct meanings: +- A **Profile** is a governance configuration: it declares how DCM behaves and what operational and compliance requirements apply. +- A **Module** is a capability extension: it adds new functions to DCM (e.g., a HIPAA record validator, a custom resource type). Modules are not profiles and do not configure DCM behavior — they extend what DCM can do. + + +### 1a.1 The Gap in the Original Model + +The original six profiles (minimal → sovereign) are organized around **deployment posture** — how strict, how redundant, how governed. But organizations need compliance governance that is orthogonal to posture. A healthcare organization needs HIPAA controls regardless of whether they deploy at `standard` or `sovereign` posture. A payment processor needs PCI-DSS regardless of their redundancy profile. + +The new model makes compliance a first-class dimension that composes with posture: + +``` +Complete Profile = Deployment Posture Group + Compliance Domain Group(s) +``` + +### 1a.2 Dimension 1 — Deployment Posture Groups + +Posture groups govern how the DCM infrastructure itself behaves — redundancy, enforcement strictness, audit retention, tenancy model, cross-tenant defaults. These are the vertical axis from least to most governed. + +| Group Handle | Posture | Key Behaviors | +|-------------|---------|--------------| +| `system/group/posture-minimal` | Minimal | Advisory only; single instance; no redundancy | +| `system/group/posture-dev` | Development | Warn-not-block; basic logging; ephemeral defaults | +| `system/group/posture-standard` | Standard | Full enforcement; 3-replica; explicit cross-tenant | +| `system/group/posture-prod` | Production | Full enforcement + SLA; geo-replicated; cost governance | +| `system/group/posture-hardened` | Enterprise Hardened | 5-replica; 7-year audit; hard tenancy; dual approval | +| `system/group/posture-sovereign` | Sovereign | Air-gap; deny_all cross-tenant; 10-year audit; signed bundles | + +### 1a.3 Dimension 2 — Compliance Domain Groups + +Compliance domain groups govern what data handling, audit, and control requirements apply to resources managed by DCM. Multiple compliance domains can apply simultaneously. + +| Group Handle | Domain | Key Controls | +|-------------|--------|-------------| +| `system/group/compliance-fsi` | Financial Services | Basel III, SOX, Dodd-Frank financial controls | +| `system/group/compliance-pci-dss` | Payment Card | PCI-DSS v4 — payment card industry | +| `system/group/compliance-hipaa` | Healthcare | HIPAA/HITECH PHI handling and audit | +| `system/group/compliance-fedramp-moderate` | US Federal Moderate | FedRAMP Moderate — NIST 800-53 Moderate baseline | +| `system/group/compliance-fedramp-high` | US Federal High | FedRAMP High — NIST 800-53 High baseline | +| `system/group/compliance-dod-il2` | DoD IL2 | Public/unclassified defense data | +| `system/group/compliance-dod-il4` | DoD IL4 | Controlled Unclassified Information (CUI) | +| `system/group/compliance-dod-il5` | DoD IL5 | National Security Systems non-classified | +| `system/group/compliance-dod-il6` | DoD IL6 | Classified — maximum sovereign posture | +| `system/group/compliance-government` | Government General | General government/public sector controls | +| `system/group/compliance-gdpr` | EU Data Protection | GDPR data residency and rights | +| `system/group/compliance-iso27001` | ISO 27001 | Information security management | +| `system/group/compliance-nist-800-53` | NIST 800-53 | NIST security control framework | +| `system/group/compliance-soc2` | SOC 2 | Service organization controls | +| `system/group/compliance-nerc-cip` | Critical Infrastructure | Energy/utilities NERC CIP | +| `system/group/compliance-sovereign` | Sovereign/Classified | Sovereign deployment, air-gap, classified | + +### 1a.4 Compliance Domain Group Contents + +#### `system/group/compliance-hipaa` + +HIPAA/HITECH controls for Protected Health Information (PHI): +- PHI field classification enforcement (fields containing PHI must be tagged `phi: true`) +- PHI access control (only roles with `phi_authorized: true` may access PHI-tagged fields) +- Audit retention: P6Y minimum (HIPAA requires 6 years from creation or last use) +- Encryption at rest: AES-256 required for all PHI storage +- Transmission security: TLS 1.3 minimum for PHI in transit +- Breach notification workflow: sovereignty_violation_record triggers HIPAA breach assessment +- Business Associate Agreement (BAA) tracking: providers handling PHI must declare `baa_in_place: true` in sovereignty_declaration +- Right to Access: consumer data export capability required for PHI entities +- Minimum Necessary standard: data_request_spec on Mode 4 providers limited to minimum PHI fields + +#### `system/group/compliance-government` + +General government and public sector controls: +- Data classification mandatory on all resources (classification_level field required) +- Cross-boundary controls: data cannot cross classification levels without explicit policy +- Audit retention: P10Y minimum +- Air-gap capability required for Sensitive compartments +- Actor authentication must declare clearance level in external_identity claims +- All provider sovereignty_declarations must declare government_access_risk + +#### `system/group/compliance-fedramp-moderate` + +FedRAMP Moderate authorization controls: +- NIST 800-53 Rev 5 Moderate baseline implemented as policy group +- FedRAMP-authorized provider preference injected as placement constraint +- Continuous monitoring: drift detection mandatory; P24H maximum drift resolution window +- Incident response: webhook required for security events (audit.chain_break, drift.escalated) +- POA&M tracking: `poam_status` field in status_metadata on all policy artifacts +- Boundary protection: explicit ingress/egress control documentation + +#### `system/group/compliance-dod-il4` + +DoD Impact Level 4 — Controlled Unclassified Information: +- Inherits compliance-fedramp-moderate +- CUI handling markers on all data fields containing controlled information +- Sovereign posture within US jurisdiction boundary +- Provider sovereignty_declaration must exclude foreign sub-processors +- CMMC Level 2 cyber hygiene controls + +#### `system/group/compliance-sovereign` + +Sovereign and classified deployment controls: +- All data must remain within declared sovereignty boundary +- Air-gap capability: provider air_gap_capable: true required +- Signed bundle import only — no live registry connectivity +- deny_all cross-tenant cross-boundary data flows +- Hardware security module (HSM) required for key management +- Audit records: 10-year retention; cryptographic signing required + +### 1a.5 Profile Composition Model + +The six built-in profiles become explicit posture+compliance compositions: + +```yaml +system/profile/minimal: + policy_groups: [system/group/posture-minimal] + +system/profile/dev: + extends: system/profile/minimal + policy_groups: [system/group/posture-dev] + +system/profile/standard: + extends: system/profile/dev + policy_groups: [system/group/posture-standard] + +system/profile/prod: + extends: system/profile/standard + policy_groups: [system/group/posture-prod] + +system/profile/fsi: + extends: system/profile/prod + policy_groups: + - system/group/posture-hardened + - system/group/compliance-fsi + - system/group/compliance-pci-dss + - system/group/compliance-iso27001 + +system/profile/sovereign: + extends: system/profile/fsi + policy_groups: + - system/group/posture-sovereign + - system/group/compliance-sovereign +``` + +### 1a.6 DCM Built-In Extended Profiles + +In addition to the six core profiles, DCM ships extended profiles for common compliance domains: + +```yaml +system/profile/hipaa-prod: + extends: system/profile/prod + policy_groups: + - system/group/compliance-hipaa + - system/group/compliance-iso27001 + description: "Production infrastructure with HIPAA/HITECH compliance" + +system/profile/hipaa-sovereign: + extends: system/profile/sovereign + policy_groups: + - system/group/compliance-hipaa + description: "Sovereign deployment with HIPAA/HITECH compliance — highest healthcare posture" + +system/profile/fedramp-moderate: + extends: system/profile/prod + policy_groups: + - system/group/compliance-fedramp-moderate + - system/group/compliance-nist-800-53 + description: "FedRAMP Moderate authorized deployment" + +system/profile/fedramp-high: + extends: system/profile/sovereign + policy_groups: + - system/group/compliance-fedramp-high + - system/group/compliance-nist-800-53 + description: "FedRAMP High authorized deployment" + +system/profile/government: + extends: system/profile/prod + policy_groups: + - system/group/compliance-government + - system/group/compliance-nist-800-53 + description: "General government and public sector deployment" + +system/profile/dod-il4: + extends: system/profile/sovereign + policy_groups: + - system/group/compliance-dod-il4 + - system/group/compliance-fedramp-high + - system/group/compliance-nist-800-53 + description: "DoD Impact Level 4 — Controlled Unclassified Information" + +system/profile/dod-il5: + extends: system/profile/dod-il4 + policy_groups: + - system/group/compliance-dod-il5 + description: "DoD Impact Level 5 — National Security Systems non-classified" + +system/profile/dod-il6: + extends: system/profile/dod-il5 + policy_groups: + - system/group/compliance-dod-il6 + - system/group/compliance-sovereign + description: "DoD Impact Level 6 — Classified" +``` + +### 1a.7 Organization Custom Profiles — Composition Examples + +```yaml +# Healthcare with federal cloud authorization +org/profile/hipaa-fedramp: + extends: system/profile/fedramp-moderate + policy_groups: + - system/group/compliance-hipaa + description: "Healthcare workloads on FedRAMP Moderate platform" + +# Multi-compliance financial + healthcare +org/profile/fsi-hipaa: + extends: system/profile/fsi + policy_groups: + - system/group/compliance-hipaa + description: "FSI-grade deployment for organizations managing both financial and health data" + +# Tenant-level compliance override — platform is standard; this Tenant is PCI-scoped +# (declared in tenant_config — not profile) +tenant_compliance_overlay: + active_profile: system/profile/standard # platform posture + compliance_groups: + - system/group/compliance-pci-dss # this Tenant handles payment cards + - system/group/compliance-hipaa # this Tenant also handles PHI + # Other Tenants on same platform have standard posture, no compliance overlay +``` + +### 1a.8 Compliance at Tenant Level + +Compliance domain groups may apply at Tenant level — different Tenants on the same DCM deployment can have different compliance domains: + +```yaml +tenant_config: + active_profile: system/profile/prod # posture from platform + compliance_groups: + - system/group/compliance-hipaa # this Tenant handles PHI + - system/group/compliance-pci-dss # this Tenant processes payments +``` + +This is the critical capability: **one DCM deployment, multiple compliance postures per Tenant**. A hospital system can run a single DCM with: clinical Tenants (HIPAA), billing Tenants (HIPAA + PCI-DSS), and administrative Tenants (standard) — all on the same platform profile. + +### 1a.9 System Policies — Profile Composition + +| Policy | Rule | +|--------|------| +| `PROF-001` | Profiles compose a Deployment Posture Group with zero or more Compliance Domain Groups. Posture groups govern DCM infrastructure behavior. Compliance domain groups govern data handling, audit, and control requirements. | +| `PROF-002` | Compliance Domain Groups may be applied at platform level (all Tenants) or Tenant level (specific Tenants). Tenant-level compliance groups are additive — they do not replace platform-level groups. | +| `PROF-003` | DCM ships built-in Compliance Domain Groups for: FSI, PCI-DSS, HIPAA/HITECH, FedRAMP Moderate, FedRAMP High, DoD IL2-IL6, Government, GDPR, ISO 27001, NIST 800-53, SOC2, NERC-CIP, and Sovereign/Classified. Organizations extend these groups or compose them into custom profiles. | +| `PROF-004` | The `implementation_posture` concern_type Policy Groups (provenance model, auth simplicity, deployment complexity) are independent of compliance domain — organizations select their implementation posture separately from their compliance requirements. | + +--- + + +### 2.1 Definition + +A **Policy Group** is a versioned, cohesive collection of policies that together address a **single identifiable concern**. The group is the unit of reuse — activate a group to enable a concern, not individual policies. + +```yaml +policy_group: + artifact_metadata: + uuid: + handle: "system/group/pci-dss" + version: "1.2.0" + status: active + owned_by: + display_name: "DCM Project Team" + notification_endpoint: + + name: "PCI-DSS v4" + description: > + Policy group implementing PCI-DSS v4 controls relevant to + DCM-managed infrastructure. Enforces encryption standards, + network segmentation, access control, and audit requirements + for resources in PCI scope. + + concern_type: compliance + concern_tags: [pci-dss, financial, encryption, network-segmentation] + extends: null # or another group handle — inherits all parent policies + + # Source — locally authored or from a External Policy Evaluator + source: + type: + provider_uuid: + provider_group_reference: + on_provider_update: + # proposed: provider updates require local review before activation + # active: provider updates activate immediately (trusted providers only) + + # Constituent policies + policies: + - policy_uuid: + handle: "system/gatekeeper/pci-encryption-aes256" + description: "Enforce AES-256 on all PCI-scoped storage" + placement_phase: pre + - policy_uuid: + handle: "system/validation/pci-network-segmentation" + description: "Validate network segment isolation for PCI resources" + placement_phase: pre + - policy_uuid: + handle: "system/transformation/pci-classification-inject" + description: "Auto-inject PCI classification on scoped resources" + placement_phase: pre + - policy_uuid: + handle: "system/gatekeeper/pci-audit-retention" + description: "Enforce 10-year audit retention for PCI evidence" + placement_phase: pre + + # Activation scope — surgical application within a profile + activation_scope: + resource_types: [] # empty = all resource types + tenant_tags: [pci-scope] # only Tenants tagged pci-scope + regions: [] # empty = all regions + + # Conflict declarations + conflicts_with: + - group_handle: "system/group/dev-defaults" + reason: "PCI requires blocking enforcement; dev-defaults uses warn-only" + resolution: this_group_wins +``` + +### 2.2 Concern Types + +| Type | Description | Examples | +|------|-------------|---------| +| `technology` | Policies specific to a technology or provider | kubevirt, openstack, kubernetes, vmware | +| `compliance` | Regulatory or standards compliance | pci-dss, iso-27001, nist-800-53, fedramp | +| `sovereignty` | Data residency, jurisdictional, air-gap | gdpr-eu, air-gap, data-residency-uk | +| `business` | Business process, cost, lifecycle governance | cost-governance, ephemeral-resources, chargeback | +| `operational` | Operational posture, defaults, SLAs | dev-defaults, hard-tenancy, sla-enforcement | +| `security` | Security controls and posture | data-classification, zero-trust, encryption-baseline | +| `implementation_posture` | Implementation complexity vs capability trade-offs | provenance-full-inline, provenance-deduplicated, single-instance-deployment, advisory-policies-only | + +### 2.3 Group Inheritance + +A Policy Group may extend another group — inheriting all its policies and overriding or adding to them: + +```yaml +policy_group: + handle: "org/group/pci-dss-extended" + extends: "system/group/pci-dss" + # Inherits all system/group/pci-dss policies + # Additional policies added below are on top of the parent + policies: + - policy_uuid: + handle: "org/gatekeeper/our-pci-additional-control" +``` + +### 2.4 DCM Built-In Policy Groups + +DCM ships the following policy groups as part of its standard distribution: + +| Handle | Concern | Description | +|--------|---------|-------------| +| `system/group/core-minimal` | operational | Absolute minimum — UUID requirements, basic well-formedness | +| `system/group/dev-defaults` | operational | Warn-not-block, 90-day TTL defaults, single-auth cross-tenant | +| `system/group/ephemeral-resources` | business | TTL enforcement, auto-expiry, short-lived resource defaults | +| `system/group/audit-basic` | operational | Basic audit logging, 90-day retention | +| `system/group/audit-compliance` | compliance | Compliance-grade audit, configurable retention | +| `system/group/data-classification` | security | Data classification tagging and handling rules | +| `system/group/cost-governance` | business | Budget enforcement, cost attribution, TTL governance | +| `system/group/sla-enforcement` | operational | SLA tracking, availability commitments | +| `system/group/hard-tenancy` | operational | Full tenant isolation, deny_all cross-tenant default | +| `system/group/explicit-cross-tenant` | operational | Explicit cross-tenant authorization requirement (XTA-001 through XTA-005) | +| `system/group/zero-trust` | security | Zero-trust network and identity enforcement | +| `system/group/encryption-baseline` | security | AES-256 minimum, TLS 1.3, key rotation | +| `system/group/pci-dss` | compliance | PCI-DSS v4 controls | +| `system/group/gdpr-eu` | sovereignty | GDPR data residency and handling | +| `system/group/nist-800-53` | compliance | NIST 800-53 control implementation | +| `system/group/iso-27001` | compliance | ISO 27001 controls | +| `system/group/fedramp-moderate` | compliance | FedRAMP Moderate baseline | +| `system/group/air-gap` | sovereignty | Air-gapped deployment constraints | +| `system/group/fsi-audit` | compliance | Financial services audit retention (7-year minimum) | +| `system/group/lifecycle-ttl-enforcement` | operational | Lifecycle time constraint enforcement (LTC-001 through LTC-004) | +| `system/group/kubevirt` | technology | KubeVirt provider-specific policies | +| `system/group/openstack` | technology | OpenStack provider-specific policies | +| `system/group/vmware` | technology | VMware provider-specific policies | +| `system/group/provenance-full-inline` | implementation_posture | Model A — all provenance inline on entity records; simplest; highest storage cost | +| `system/group/provenance-deduplicated` | implementation_posture | Model B — content-addressed deduplication; recommended; 95-99% storage reduction; lossless | +| `system/group/provenance-tiered-archive` | implementation_posture | Model C — hot/warm/cold tiers; balances cost and access speed | +| `system/group/provenance-deduplicated-tiered` | implementation_posture | Model B+C — maximum efficiency for very large-scale deployments | + +--- + +## 3. Policy Profiles + +### 3.1 Definition + +A **Policy Profile** is a named, versioned, curated composition of Policy Groups that together configure DCM for a specific use case. Activating a profile is the primary configuration mechanism — most deployments should activate a profile and then add organization-specific groups on top rather than configuring policies individually. + +```yaml +policy_profile: + artifact_metadata: + uuid: + handle: "system/profile/fsi" + version: "1.0.0" + status: active + owned_by: + display_name: "DCM Project Team" + + name: "FSI Production" + description: > + Policy profile for Financial Services production deployments. + Enforces hard tenancy, regulatory-grade audit retention, + full sovereignty controls, and explicit cross-tenant authorization. + + target_use_case: fsi_production + extends: "system/profile/prod" # inherits all prod groups + overrides + + enforcement_summary: + tenancy: hard_tenancy_required + audit_retention_years: 7 + sovereignty: full + cross_tenant_default: explicit_only + policy_enforcement: blocking + immutable_fields: [sovereignty_zone, classification_level, audit_retention] + policy_version_pinning: permitted_with_elevation + + policy_groups: + - group_handle: "system/group/fsi-audit" + - group_handle: "system/group/pci-dss" + - group_handle: "system/group/gdpr-eu" + - group_handle: "system/group/hard-tenancy" + - group_handle: "system/group/explicit-cross-tenant" + - group_handle: "system/group/encryption-baseline" +``` + +### 3.2 DCM Built-In Profiles + +DCM ships six profiles covering the spectrum from minimal to sovereign: + +#### `system/profile/minimal` — Home Lab / Evaluation + +```yaml +handle: "system/profile/minimal" +name: "Minimal" +extends: null +description: > + Minimal configuration for home lab, local testing, and evaluation. + Most controls advisory only. Single Tenant auto-created on first use. + No audit requirements. No sovereignty enforcement. + +enforcement_summary: + tenancy: optional + audit_retention: none + sovereignty: none + cross_tenant_default: allow_all + policy_enforcement: advisory # policies warn but do not block + time_constraints: optional + +auto_tenant: + enabled: true + default_tenant_handle: "default" + # TEN-001 satisfied silently — no explicit Tenant declaration required + +policy_groups: + - group_handle: "system/group/core-minimal" +``` + +#### `system/profile/dev` — Development Environments + +```yaml +handle: "system/profile/dev" +name: "Development" +extends: "system/profile/minimal" +description: > + Development environment profile. Tenancy recommended but not blocking. + Basic logging. Ephemeral resource defaults. Warn-not-block enforcement. + +enforcement_summary: + tenancy: recommended + audit_retention: basic + sovereignty: none + cross_tenant_default: operational_only + policy_enforcement: warn_only + default_ttl: P90D # dev resources default to 90-day TTL + +policy_groups: + - group_handle: "system/group/dev-defaults" + - group_handle: "system/group/ephemeral-resources" + - group_handle: "system/group/audit-basic" +``` + +#### `system/profile/standard` — General Enterprise Production + +```yaml +handle: "system/profile/standard" +name: "Standard" +extends: "system/profile/dev" +description: > + General enterprise production profile. Full policy enforcement. + Tenancy required. Explicit cross-tenant authorization. Basic + data classification. Compliance-grade audit. + +enforcement_summary: + tenancy: required + audit_retention: compliance_grade + sovereignty: configurable + cross_tenant_default: explicit_only + policy_enforcement: blocking + +policy_groups: + - group_handle: "system/group/data-classification" + - group_handle: "system/group/audit-compliance" + - group_handle: "system/group/explicit-cross-tenant" + - group_handle: "system/group/encryption-baseline" +``` + +#### `system/profile/prod` — Production with SLA Requirements + +```yaml +handle: "system/profile/prod" +name: "Production" +extends: "system/profile/standard" +description: > + Production profile with SLA enforcement, cost governance, and + full lifecycle constraint enforcement. + +enforcement_summary: + tenancy: required + audit_retention: compliance_grade + sovereignty: configurable + cross_tenant_default: explicit_only + policy_enforcement: blocking + +policy_groups: + - group_handle: "system/group/cost-governance" + - group_handle: "system/group/sla-enforcement" + - group_handle: "system/group/lifecycle-ttl-enforcement" +``` + +#### `system/profile/fsi` — Financial Services Production + +```yaml +handle: "system/profile/fsi" +name: "FSI Production" +extends: "system/profile/prod" +description: > + Financial services production. Hard tenancy. 7-year audit retention. + Full sovereignty enforcement. PCI-DSS and GDPR compliance. + +enforcement_summary: + tenancy: hard_tenancy_required + audit_retention_years: 7 + sovereignty: full + cross_tenant_default: explicit_only + policy_enforcement: blocking + +policy_groups: + - group_handle: "system/group/fsi-audit" + - group_handle: "system/group/pci-dss" + - group_handle: "system/group/gdpr-eu" + - group_handle: "system/group/hard-tenancy" +``` + +#### `system/profile/sovereign` — Air-Gapped / Sovereign Deployments + +```yaml +handle: "system/profile/sovereign" +name: "Sovereign" +extends: "system/profile/fsi" +description: > + Maximum control profile for air-gapped, sovereign, and highest-security + deployments. Complete tenant isolation. Zero external dependencies. + Maximum audit and sovereignty enforcement. + +enforcement_summary: + tenancy: hard_tenancy_required + audit_retention_years: 10 + sovereignty: maximum + cross_tenant_default: deny_all + policy_enforcement: blocking + immutable_ceiling_on_all_sovereignty_fields: true + +policy_groups: + - group_handle: "system/group/air-gap" + - group_handle: "system/group/zero-trust" +``` + +### 3.3 Profile Inheritance Chain + +``` +system/profile/sovereign + extends: system/profile/fsi + extends: system/profile/prod + extends: system/profile/standard + extends: system/profile/dev + extends: system/profile/minimal + extends: null (base) +``` + +Each level adds groups without replacing parent groups. An organization extending a DCM profile only needs to declare what differs: + +```yaml +# Organization custom profile +org/profile/my-prod: + extends: system/profile/prod + policy_groups: + - group_handle: "org/group/our-naming-conventions" + - group_handle: "org/group/our-cost-centers" + - group_handle: "system/group/iso-27001" # add a DCM compliance group +``` + +### 3.4 Profile Activation + +Profiles activate at three levels — more specific takes precedence: + +```yaml +# DCM installation default +installation_config: + default_profile: "system/profile/minimal" + +# Platform-level (applies to all Tenants) +platform_config: + active_profile: "system/profile/prod" + minimum_tenant_profile: "system/profile/dev" # Tenants cannot go below this + maximum_tenant_profile: null # null = no ceiling + +# Tenant-level override +tenant_config: + active_profile: "system/profile/fsi" # must be >= minimum_tenant_profile +``` + +**A Tenant cannot activate a profile less restrictive than the platform minimum.** A sovereign deployment can set `minimum_tenant_profile: system/profile/sovereign` — no Tenant can drop below that level. + +### 3.5 Profile Conflict Resolution + +When a profile is activated, DCM runs conflict detection across all constituent group policies — same ingestion conflict detection that layers use. Conflicts must be resolved before a profile is marked `active`. + +Conflict resolution order: +1. **Explicit `conflicts_with` declarations** on groups — use declared resolution rule +2. **Priority schema** — higher numeric priority wins +3. **Domain authority** — `system` beats `platform` beats `tenant` +4. **Unresolved** — profile activation fails with detailed conflict report + +### 3.6 Profile Shadow Validation + +When a profile is in `proposed` status, all its constituent policies run in shadow mode — the same proposed policy shadow execution model. The Validation Dashboard shows the aggregate impact across all policies in the profile before activation. This enables safe preview of what a profile upgrade would do to an existing deployment. + +--- + +## 4. Policy Evaluation Modes + +DCM supports two policy evaluation modes. The distinction is whether DCM or an external system performs the evaluation — not how policies are delivered to the evaluator. + +### 4.1 Internal Mode — DCM Evaluates + +In Internal mode, the Policy Manager evaluates all policies using its embedded OPA engine. Policies can arrive through any delivery mechanism: + +| Delivery | Description | +|----------|-------------| +| **API / GitOps** | Policies stored in DCM's database, managed via API or Git ingress adapter | +| **OPA Bundle** | Standard OPA bundle protocol — point OPA at a bundle server URL | +| **External Schema** | Policies in non-Rego format (e.g., XACML, custom JSON) naturalized to Rego by DCM before evaluation | + +All three delivery mechanisms result in the same thing: Rego policies evaluated by OPA against the request payload. Where OPA runs (embedded Go library, sidecar container, or remote OPA instance) is a deployment topology decision — not a mode distinction. + +**Policy registration:** +```yaml +policy: + handle: "vm-size-limits" + policy_type: gatekeeper + delivery: + mode: push # or: pull, opa_bundle, external_schema + source_url: "https://git.corp/policies" # for pull/bundle modes + format: rego # or: xacml, custom_json (naturalized to rego) + activation: active # or: proposed (shadow mode) + trust_level: trusted # trusted, verified, untrusted +``` + +**Trust levels (Internal mode):** +- `trusted` — GateKeeper authority (can deny requests) +- `verified` — Transformation and Validation authority only +- `untrusted` — advisory only (shadow mode enforcement) + +### 4.2 External Mode — External Provider Evaluates + +In External mode, DCM sends evaluation context to an external endpoint. The external system evaluates and/or enriches the data, and returns a structured result. DCM does not see the policy logic — it trusts the results within scoped bounds. + +**External evaluation can:** +- **Evaluate** — return pass/fail, score, or recommendation +- **Enrich** — inject additional fields into the payload (risk scores, compliance citations, cost predictions, organizational context) +- **Both** — combined decision + enrichment in a single response + +**Registration:** +```yaml +policy: + handle: "compliance-scanner" + policy_type: validation + delivery: + mode: external # External mode + endpoint: "https://compliance.corp/api/evaluate" + auth: mtls + data_request_spec: # data minimization — only declared fields sent + fields: [resource_type, sovereignty_zone, data_classification, tenant_uuid] + on_unavailable: gatekeep # fail-closed — unknown is not safe + trust_level: verified # minimum verified for enrichment +``` + +### 4.3 External Mode Governance (BBQ-001 through BBQ-009) + +External evaluation introduces governance concerns that Internal mode does not: + +| ID | Requirement | +|----|-------------| +| BBQ-001 | Data sovereignty check before any query is sent to an external endpoint | +| BBQ-002 | Data minimization — only fields declared in `data_request_spec` are sent | +| BBQ-003 | If the external endpoint is outside the entity's sovereignty zone, the query is blocked unless explicitly authorized | +| BBQ-004 | Full audit record per query-response cycle, including `audit_token` for cross-system correlation | +| BBQ-005 | Default failure behavior is `gatekeep` — if the external system is unavailable, the request is denied (fail-closed) | +| BBQ-006 | Cached results must include the original query timestamp and validity period in provenance | +| BBQ-007 | Fields injected by external enrichment carry standard field-level provenance: `source_type: external_external_policy_evaluator`, `source_uuid`, and `audit_token` | +| BBQ-008 | The override control model applies to enrichment-injected fields — a GateKeeper policy may restrict or refuse external enrichment on specific fields | +| BBQ-009 | External enrichment requires minimum `verified` trust level; GateKeeper authority requires `trusted` with dual-approval elevation | + +### 4.4 Policy Sources and Policy Groups + +Policies from any source (Internal or External) participate in the same Policy Group mechanism. A Policy Group composes multiple policies into a named, versioned, reviewable unit with explicit conflict declarations: + +```yaml +policy_group: + handle: "pci-dss-v4-controls" + policies: + - ref: "card-data-encryption" # Internal — Rego policy in DCM + - ref: "network-segmentation-check" # Internal — OPA bundle + - ref: "compliance-scanner" # External — calls external endpoint + activation_scope: + resource_types: ["*"] + tenant_tags: ["pci"] +``` + +### 4.5 Policy Health and Lifecycle + +- **Internal policies:** Health is determined by OPA engine health. If OPA is unavailable, all Internal policies are degraded. +- **External policies:** Health is determined by endpoint availability. Each external endpoint has a health check (HTTP GET to a declared health URL). Unhealthy external policies trigger their `on_unavailable` behavior (default: `gatekeep`). +- **Deprecation:** Policies follow the `active → deprecated → retired` lifecycle. Deprecated policies fire with a warning in the audit trail. Retired policies are no longer evaluated. + +--- + +## 5. Lifecycle Time Constraints + +### 5.1 Concept + +Lifecycle time constraints declare **when a resource should cease to exist or trigger a lifecycle action**. They are a first-class field on any resource entity — not metadata, not a tag, but a governed field that follows the standard data model precedence and override control. + +### 5.2 Constraint Types + +| Type | Format | Description | +|------|--------|-------------| +| `ttl` | ISO 8601 duration (e.g., `P14D`) | Relative — expires N time after the reference point | +| `expires_at` | ISO 8601 timestamp | Absolute — expires at a specific calendar date/time | + +When both are declared, the **earliest expiry wins** (LTC-004). + +### 5.3 Data Model + +```yaml +lifecycle_constraints: + ttl: + duration: P14D # ISO 8601 duration — 14 days + reference_point: realization_timestamp # created_at | realization_timestamp | last_modified + on_expiry: + metadata: + override: allow # standard override control applies + basis_for_value: "Consumer declared ephemeral — 14-day lab resource" + + expires_at: + timestamp: "2026-06-30T23:59:59Z" + on_expiry: notify + metadata: + override: immutable + locked_by_policy_uuid: + basis_for_value: "Project deadline — resource must not persist beyond Q2" + + # Enforcement behavior + enforcement: + warn_before_expiry: P1D # warn 1 day before expiry + warn_notification_endpoint: + grace_period: PT1H # 1 hour grace after expiry before action + on_grace_period_expiry: +``` + +### 5.4 Precedence + +Lifecycle time constraints follow the standard data model precedence chain: + +``` +Base Layer default (lowest — e.g., "no TTL by default") + ↓ +Core Layer (e.g., "all dev environment resources: TTL 90 days") + ↓ +Service Layer (e.g., "ephemeral compute: TTL 7 days") + ↓ +Request Layer (consumer declared TTL) + ↓ +Transformation Policy (enrich TTL from business context) + ↓ +GateKeeper Policy (highest — may lock TTL as immutable) +``` + +A consumer can declare `ttl: P14D` in their request. A GateKeeper policy can override this to `P7D` and lock it immutable if organizational policy mandates shorter maximum lifetimes. A Core Layer can set default TTLs for resource classes. The provenance chain records every modification. + +### 5.5 Expiry Enforcement + +The **Lifecycle Constraint Enforcer** is a DCM control plane component that: +- Monitors all realized entities against their declared lifecycle constraints +- Fires the configured `on_expiry` action when a constraint is reached +- Records the enforcement action in provenance and the Audit Store +- Emits expiry warnings `warn_before_expiry` duration before the deadline + +Expiry enforcement is a DCM concern — not a provider concern. The provider does not need to know about or implement TTL logic. + +### 5.6 System Policies + +| Policy | Rule | +|--------|------| +| `LTC-001` | Lifecycle time constraints follow standard data model precedence — layers, request, policies | +| `LTC-002` | GateKeeper policies may lock lifecycle constraints as `override: immutable` or `immutable_ceiling: absolute` | +| `LTC-003` | Expiry enforcement is a DCM control plane function — not a provider concern | +| `LTC-004` | When multiple time constraints exist on an entity, the earliest expiry wins | +| `LTC-005` | Expired entities that fail to execute their `on_expiry` action enter `PENDING_EXPIRY_ACTION` state and trigger an escalation | + +--- + +## 6. Cross-Tenancy Authorization Model + +### 6.1 Default Stance — Closed + +Cross-tenant information sharing is **closed by default**. No cross-tenant relationship of any nature is permitted unless explicitly authorized. This applies to both operational dependencies and informational relationships. + +The hard tenancy spectrum: + +| Setting | Meaning | +|---------|---------| +| `deny_all` | No cross-tenant relationships of any nature | +| `explicit_only` | All cross-tenant must be explicitly authorized (DEFAULT) | +| `operational_permitted` | Operational cross-tenant permitted; informational requires explicit auth | +| `allow_all` | All cross-tenant permitted — requires justification; not available in sovereign profile | + +The default shifts from the Q59 model's `operational_only` to `explicit_only`. Informational sharing is no longer implicitly open — every informational cross-tenant relationship requires an explicit authorization record. + +### 6.2 Cross-Tenant Authorization Record + +```yaml +cross_tenant_authorization: + artifact_metadata: + uuid: + handle: "tenant-a/auth/shared-network-read" + version: "1.0.0" + status: active + owned_by: + display_name: "Infrastructure Tenant Admin" + + # WHO + authorized_consumer_tenant_uuid: + authorized_actor_constraint: + roles: [service_account, automation] # null = any actor in the tenant + specific_uuids: [] # specific actor UUIDs if needed + + # WHAT + resource_entity_uuid: + resource_type_uuid: + permitted_fields: + - field: network_segment + - field: vlan_id + # empty list = all fields permitted + permitted_relationship_natures: [informational, operational] + + # WHEN + valid_from: + expires_at: + + # WHERE + permitted_in_regions: [eu-west, eu-central] # null = any region + sovereignty_constraints: + must_honor_consuming_tenant_sovereignty: true + must_honor_owning_tenant_sovereignty: true + + # GOVERNANCE + authorized_by_policy_uuid: + authorization_level: + # Hierarchy: field_specific > resource_specific > tenant_global + # More specific = higher precedence +``` + +### 6.3 Authorization Hierarchy + +More specific authorizations take precedence over broader ones: + +``` +field_specific ← highest precedence — only these exact fields on this entity + │ +resource_specific ← this entity — all permitted fields + │ +tenant_global ← all entities in this Tenant — broadest +``` + +If a tenant-global policy says "allow informational sharing with Tenant B" but a resource-specific policy says "this resource is not shareable with anyone," the resource-specific policy wins. + +### 6.4 System Policies — Cross-Tenancy + +| Policy | Rule | +|--------|------| +| `XTA-001` | Cross-tenant information sharing is closed by default — explicit authorization required | +| `XTA-002` | Cross-tenant authorizations must specify who, what, when, and where | +| `XTA-003` | More specific authorizations take precedence: field_specific > resource_specific > tenant_global | +| `XTA-004` | All cross-tenant authorization decisions are policy-driven and DCM-enforced | +| `XTA-005` | Sovereignty constraints declared by either Tenant must be honored by all cross-tenant relationships | + +--- + +## 7. Rehydration Tenancy Controls + +### 7.1 Tenancy and Sovereignty Are Always Current + +Tenancy controls, sovereignty directives, and cross-tenant authorizations are **always evaluated against current policies during rehydration**. They cannot be pinned to historical versions. + +```yaml +rehydration: + re_evaluate: true/false # governs placement + policy_version: current/pinned # governs resource configuration policies + # The following are ALWAYS current — cannot be pinned: + tenancy_controls: always_current + sovereignty_controls: always_current + cross_tenant_authorizations: always_current +``` + +### 7.2 Rehydration Tenancy Conflict + +When rehydration produces a tenancy or sovereignty constraint that conflicts with an existing cross-tenant allocation: + +```yaml +rehydration_tenancy_conflict_record: + rehydration_request_uuid: + entity_uuid: + conflict_type: cross_tenant_authorization_conflict + original_authorization_uuid: + current_policy_violation: + policy_uuid: + violation: "Consuming Tenant no longer has authorization for this allocation" + action_taken: paused + entity_state: PENDING_REVIEW + notifications_sent: + - entity_owner + - owning_tenant_admin + - consuming_tenant_admin + - platform_admin + resolution_options: + - re_authorize + - release + - escalate + policy_override_available: true +``` + +### 7.3 System Policies — Rehydration + +| Policy | Rule | +|--------|------| +| `RHY-001` | Tenancy, sovereignty, and cross-tenant authorizations always use current policies during rehydration | +| `RHY-002` | Rehydration that conflicts with current tenancy/sovereignty pauses and enters PENDING_REVIEW | +| `RHY-003` | A paused rehydration allocation is not automatically released — requires explicit resolution | +| `RHY-004` | A policy may declare automatic resolution behavior for rehydration tenancy conflicts | + +--- + +## 8. Open Questions + +| # | Question | Impact | Status | +|---|----------|--------|--------| +| 1 | Should organizations be able to submit custom profiles and groups back to the DCM project registry? | Community | ✅ Resolved — community submissions via PR-based workflow; Tier 2; documented use case + deployment reference + test results + named maintainer (PROF-005) | +| 2 | Should there be a certified profile program — profiles that have been validated against specific regulatory frameworks? | Compliance | ✅ Resolved — certified profile program with third-party certification metadata; certified profiles promoted to Tier 1; applies to artifact not deployment (PROF-006) | +| 3 | Should External Policy Evaluator trust elevation require a formal approval workflow in DCM UI or is out-of-band approval sufficient? | Security | ✅ Resolved — formal approval workflow; profile-governed approvers (1 standard → 3 sovereign); P7D shadow period; POLICY_PROVIDER_ELEVATED audit (PROF-007) | +| 4 | Should the default TTL for dev profile resources be configurable at the platform level or only at the group level? | Configuration | ✅ Resolved — overridable at platform domain layer; per-resource-type TTL overrides; on_expiry action configurable (PROF-008) | +| 5 | How does External Policy Evaluator delivery interact with air-gapped deployments — pull from internal mirror? | Sovereignty | ✅ Resolved — signed bundle model identical to registry; Mode 4 in sovereign restricted to within-boundary endpoints (PROF-009) | + +--- + +## 9. Related Concepts + +- **Policy Engine** — executes the policies organized by groups and profiles +- **Policy Layers** — the assembly process step where policies execute +- **Artifact Metadata** — universal metadata on all policy artifacts +- **Five Artifact Statuses** — developing → proposed → active → deprecated → retired +- **Shadow Execution** — proposed policies and profiles run in shadow mode for validation +- **Override Control** — policies set override control on fields; immutable_ceiling: absolute for non-negotiables +- **Ingestion Model** — policy profile requirements may gate brownfield promotion +- **Four States** — rehydration tenancy controls govern how historical states are replayed + + +## 8. Policy Profile Gap Resolutions + +### 8.1 Community Profile and Group Submissions (Q1) + +Organizations may submit custom profiles and policy groups to the DCM community registry following the same PR-based proposal workflow as Resource Types. Community contributions live in Tier 2 (Verified Community). + +```yaml +community_profile_submission: + profile: + handle: "community/profile/hipaa-openstack" + extends: system/profile/hipaa-prod + description: "HIPAA production profile for OpenStack deployments" + policy_groups: + - system/group/compliance-hipaa + - community/group/openstack-security-baseline + contributed_by: "Healthcare IT Community Group" + tested_with: [OpenStack 2024.1, DCM 1.0] + required_for_submission: + - documented_use_case + - at_least_one_real_deployment_reference + - test_results_against_reference_implementation + - named_maintainer +``` + +Community profiles carry the same lifecycle as Resource Types — shadow validation before active, deprecation policies, sunset periods. Organizations adopt them directly or extend them further. + +### 8.2 Certified Profile Program (Q2) + +DCM supports a certified profile program where profiles carry formal third-party certification metadata against compliance frameworks. Certified profiles are promoted to Tier 1 (DCM Core). + +```yaml +profile_certification: + certifications: + - framework: HIPAA + certifying_body: "Coalfire Systems" + certification_date: "2025-11-01" + expires_at: "2027-11-01" + certification_scope: "PHI data lifecycle management via DCM" + certificate_ref: + vault_credential_ref: + path: "dcm/registry/certifications/hipaa-prod-2025" +``` + +**Important:** Profile certification applies to the profile artifact only — it does not certify the deploying organization's compliance posture. A certified profile is evidence that the profile implements the required controls; it is not a compliance certification of any specific deployment. + +### 8.3 External Policy Evaluator Trust Elevation Approval (Q3) + +External Policy Evaluator trust elevation (increasing the mode level) requires a formal approval workflow. Approval requirements are profile-governed. + +```yaml +external_evaluation_trust_elevation: + elevation_request: + from_mode: 1 + to_mode: 3 + justification: "Need OPA Rego for complex placement constraints" + + approval_requirements: + standard: + approvers: [platform_admin] + min_approvers: 1 + prod: + approvers: [platform_admin, security_owner] + min_approvers: 2 + fsi: + approvers: [platform_admin, security_owner, compliance_officer] + min_approvers: 2 + verified_required: true + sovereign: + approvers: [platform_admin, security_owner, compliance_officer] + min_approvers: 3 + requires_change_control_ticket: true + + shadow_period_after_elevation: P7D # elevated mode runs in shadow before active + audit_record: POLICY_PROVIDER_ELEVATED +``` + +The P7D shadow period catches unintended consequences before elevated outputs become binding on production requests. + +### 8.4 Dev Profile Resource TTL Configurability (Q4) + +The default TTL for dev profile resources is declared in the system domain layer and overridable at the platform domain level. + +```yaml +layer: + handle: "platform/dev-profile/resource-ttl-override" + domain: platform + fields: + dev_profile_resource_ttl: + default_ttl: P30D # platform override: 30d instead of system default P7D + max_ttl: P90D # consumers cannot declare TTL > 90 days in dev + on_expiry: notify # notify (consumers can extend) vs destroy + per_resource_type_overrides: + Compute.VirtualMachine: P7D + Storage.Block: P14D + DNS.Record: P3D +``` + +### 8.5 Air-Gapped External Policy Evaluator Delivery (Q5) + +External Policy Evaluator delivery in air-gapped deployments uses signed bundles — same model as the registry bundle system. + +```yaml +external_evaluation_airgap: + delivery_mode: signed_bundle + bundle_contents: + - provider_registration_yaml + - policy_artifacts_zip + - mode_specific_package: + mode_3: opa_rego_bundle # OPA Rego files + data + mode_4: endpoint_config # endpoint declaration (must be within boundary) + signing_key_ref: + expires_at: +``` + +**Mode 4 sovereign constraint:** In sovereign profiles, Mode 4 External Policy Evaluators may only call endpoints within the sovereignty boundary. External AI service calls are blocked by the BBQ-001 sovereignty check before any Mode 4 query. + +### 8.6 System Policies — Policy Profile Gaps + +| Policy | Rule | +|--------|------| +| `PROF-005` | Organizations may submit custom profiles and policy groups to the DCM community registry via the same PR-based proposal workflow as Resource Types. Community contributions live in Tier 2. Submissions require documented use case, at least one production deployment reference, test results, and a named maintainer. | +| `PROF-006` | DCM supports a certified profile program where profiles carry formal third-party certification metadata. Certified profiles are promoted to Tier 1. Profile certification applies to the artifact only — it does not certify the deploying organization's compliance posture. | +| `PROF-007` | External Policy Evaluator trust elevation requires a formal approval workflow (standard: 1 platform admin; prod: platform admin + security owner; fsi/sovereign: dual approval + compliance officer). Elevated providers run in shadow mode for P7D before activation. All elevations produce a POLICY_PROVIDER_ELEVATED audit record. | +| `PROF-008` | The default TTL for dev profile resources is declared in the system domain layer and overridable at the platform domain level. Per-resource-type TTL overrides are supported. The on_expiry action is configurable. | +| `PROF-009` | External Policy Evaluator delivery in air-gapped deployments uses signed bundles identical to the registry bundle model. Mode 4 providers in sovereign profiles may only call endpoints within the sovereignty boundary. | + + + +--- + +## 9. Recovery Posture Policy Groups + +### 9.1 recovery_posture as a Concern Type + +`recovery_posture` is a Policy Group concern_type that governs how DCM responds to provisioning failures, timeouts, and ambiguous states. It is the fifth concern type alongside security, compliance, operational, and implementation posture. + +Recovery posture groups contain Recovery Policies — a formal DCM policy type that maps trigger conditions (DISPATCH_TIMEOUT, PARTIAL_REALIZATION, etc.) to response actions (DRIFT_RECONCILE, DISCARD_AND_REQUEUE, NOTIFY_AND_WAIT, etc.). + +See [Operational Models](https://github.com/croadfeldt/udlm/blob/main/lifecycle/operational-models.md) Section 5 for the complete Recovery Policy model, trigger vocabulary, and action vocabulary. + +### 9.2 Four Built-in Recovery Posture Groups + +| Group Handle | Posture | Appropriate For | +|-------------|---------|----------------| +| `system/group/recovery-automated-reconciliation` | Let drift detection converge on correct state | Dev, standard environments | +| `system/group/recovery-discard-and-requeue` | Clean up and restart on any ambiguity | Consistency-critical environments | +| `system/group/recovery-notify-and-wait` | Always notify human; never act automatically | FSI, sovereign, regulated environments | +| `system/group/recovery-aggressive-retry` | Retry everything before giving up | High-transient-failure environments | + +### 9.3 Profile Binding Defaults + +| Profile | Default Recovery Posture | +|---------|------------------------| +| `minimal` | recovery-automated-reconciliation | +| `dev` | recovery-automated-reconciliation | +| `standard` | recovery-automated-reconciliation | +| `prod` | recovery-notify-and-wait | +| `fsi` | recovery-notify-and-wait | +| `sovereign` | recovery-notify-and-wait | + +### 9.4 Override Hierarchy + +Organizations override recovery posture at Tenant or resource-type level without changing the deployment profile: + +```yaml +# Tenant override — all resources in this Tenant use discard-and-requeue +tenant_config: + recovery_profile_override: recovery-discard-and-requeue + +# Resource-type override — VMs get aggressive retry regardless of Tenant/profile +resource_type_recovery_override: + resource_type: Compute.VirtualMachine + recovery_profile: recovery-aggressive-retry +``` + +Resource-type override wins over Tenant override wins over profile default. + + + +--- + +## 10. Zero Trust Posture Policy Groups + +### 10.1 zero_trust_posture as a Concern Type + +`zero_trust_posture` is the sixth Policy Group concern type. It governs authentication requirements, credential lifetime, revocation check frequency, and hardware attestation requirements for all DCM interactions. + +See [Accreditation and Authorization Matrix](https://github.com/croadfeldt/udlm/blob/main/governance/accreditation-and-authorization-matrix.md) Section 5 for the complete zero trust model. + +### 10.2 Four Zero Trust Posture Levels + +| Posture | Boundary | Internal | Hardware | Profile Default | +|---------|---------|----------|----------|----------------| +| `none` | Perimeter model | Trusted | Not required | minimal | +| `boundary` | Zero trust at external boundaries | Service mesh | Not required | dev, standard | +| `full` | Zero trust everywhere | Per-call auth | Not required | prod, fsi | +| `hardware_attested` | Zero trust everywhere | Per-call auth | Required (TPM/HSM) | sovereign | + +### 10.3 Credential Lifetime Defaults + +| Profile | Max credential lifetime | +|---------|------------------------| +| minimal | PT8H | +| dev | PT4H | +| standard | PT1H | +| prod | PT30M | +| fsi | PT15M | +| sovereign | PT15M + hardware attestation | + +### 10.4 Hard Data Boundary Constraints + +The sovereign profile enforces a hard constraint via the Data/Capability Authorization Matrix: **data classified as `sovereign` or `classified` never crosses any interaction boundary**. This constraint is declared with `hard_constraint: true` in the federation boundary matrix and cannot be overridden by any policy, profile, or operator action. It is enforced at the matrix level, not the policy level. + + +--- + +*Document maintained by the DCM Project. For questions or contributions see [GitHub](https://github.com/dcm-project).* diff --git a/architecture/governance-enforcement/registry-enforcement.md b/architecture/governance-enforcement/registry-enforcement.md new file mode 100644 index 0000000..78ce1b9 --- /dev/null +++ b/architecture/governance-enforcement/registry-enforcement.md @@ -0,0 +1,387 @@ +--- +Document Status: ✅ Stable — DCM implementation +Document Type: Architecture Reference — Registry Enforcement +Established: 2026-05-26 +Maps to: udlm/governance/registry-governance.md +--- + +# Registry Enforcement + +> **Implements contracts defined in UDLM**: +> [udlm/governance/registry-governance.md](https://github.com/croadfeldt/udlm/blob/main/governance/registry-governance.md). +> UDLM defines the three-tier registry model (Core, Verified Community, +> Organization), the proposal/review/publication workflow, the versioning +> and deprecation lifecycle contract, and the Resource Type Registry +> extension contract. DCM operationalizes the enforcement: provider selection +> tie-breaking, artifact lifecycle management, and the review queue and +> approval workflow. + +--- + +## 1. Registry governance enforcement + +DCM enforces the three-tier registry workflow through the Registry Manager +service: + +- **Tier 1 (DCM Core)** — write access restricted to DCM Project maintainer + identities; PRs against the DCM core registry repository require 2 + maintainer approvals + automated validation gates + shadow validation + period +- **Tier 2 (Verified Community)** — write access scoped to named community + maintainers per artifact; PRs require maintainer + DCM oversight approval +- **Tier 3 (Organization)** — write access scoped to the deploying + organization's contributors per the Contribution Pipeline (see + [`contribution-pipeline.md`](contribution-pipeline.md)) + +### 1.1 Validation gates (must all pass before review) + +The Registry Manager runs these gates on every PR before review begins: + +1. **Schema validator** — artifact conforms to the declared type schema +2. **FQN conflict check** — no conflict with existing active entries +3. **Dependency resolution** — all declared dependencies resolve +4. **Breaking change detector** (if version > 1.0.0) — detects field + removals, type changes, semantic shifts +5. **Test case coverage** — at least one valid example payload + +A PR that fails any gate is blocked from entering review until resolved. + +### 1.2 Review period enforcement + +Per UDLM Section 3.2, DCM enforces minimum review periods by change type +through the PR pipeline: + +| Change type | Min review | Shadow validation | Approvers | +|---|---|---|---| +| New Tier 1 type | 14 days | 14 days | 2 DCM maintainers | +| New Tier 2 type | 7 days | 7 days | 1 DCM maintainer + named tier maintainer | +| Minor version (non-breaking) | 7 days | 7 days | 1 DCM maintainer | +| Revision (config data only) | 3 days | 3 days | 1 DCM maintainer (or auto if CI passes) | +| Breaking change (major) | 21 days | 21 days | 2 DCM maintainers + community comment period | +| Deprecation | 30 days | N/A | 2 DCM maintainers + affected provider notification | +| Emergency (security) | Waived | 7 days minimum | 2 DCM maintainers + immediate notification | + +The Registry Manager rejects merge attempts that violate the minimum review +period. + +--- + +## 2. Provider selection tie-breaking + +UDLM defines the registry as the source of provider definitions. DCM uses +the registry data plus runtime metrics for placement tie-breaking. When the +Placement Manager has multiple viable candidates that satisfy all +constraints equally, DCM applies this hierarchy deterministically: + +``` +Priority Factor Condition +──────── ───────────────────── ───────────────────────────────────────── +1 Policy preference A Transformation policy injected a + preference_score or preferred_provider_uuid + +2 Provider priority Numeric priority on provider registration + Higher value = preferred (default: 50) + +3 Tenant affinity Tenant's Policy Group declares preferred + providers for specific resource types + +4 Cost analysis Cost Analysis component has current data + AND cost is determinable for candidates + Prefer lower total cost (CapEx + OpEx) + SKIP if cost data absent or incomparable + +5 Least loaded Current utilization from reserve_query + If utilization differs > 10%: prefer less loaded + SKIP if utilization data unavailable + +6 Consistent hash SHA-256(request_uuid + resource_type + + sorted_candidate_uuids) + Deterministic — same request always resolves + to same provider in a stable cluster + Never round-robin +``` + +### 2.1 Cost analysis integration + +Cost analysis ranks above operational load because cost is a business +decision. When cost data is available and comparable: + +- **CapEx:** provider infrastructure cost allocation per resource type +- **OpEx:** operational overhead, licensing, support costs per resource unit +- **Comparability:** same currency and time period; if not comparable + (different currencies, missing data), skip to step 5 + +Cost data sourced from the Cost Analysis control plane component. If Cost +Analysis is not deployed or has no current data, the step is skipped +without blocking placement. + +```yaml +placement_cost_evaluation: + enabled: true # false if Cost Analysis unavailable + data_freshness_max: PT1H # reject cost data older than 1 hour + comparison_threshold: 0.05 # 5% cost difference to trigger preference + cost_components: + - capex_allocation_per_unit + - opex_per_unit_per_hour + - licensing_per_unit +``` + +### 2.2 Provider priority declaration + +```yaml +provider_registration: + provider_priority: 100 # default 50; higher = preferred when equal + cost_metadata: + capex_allocation_per_unit: 12.50 # USD per VM-month + opex_per_unit_per_hour: 0.08 + currency: USD + last_updated: +``` + +Provider cost metadata may be declared statically or sourced dynamically +from Cost Analysis (`REG-011`); hybrid mode uses Cost Analysis when +available and falls back to static. + +--- + +## 3. Artifact lifecycle management + +DCM enforces the deprecation lifecycle per UDLM contracts (REG-DP-001 +through REG-DP-007). The Registry Manager handles: + +### 3.1 Default deprecation lifecycle policies + +```yaml +deprecation_lifecycle_policies: + REG-DP-001: { value: P30D, override: allow } # notification period + REG-DP-002: # sunset by tier + tier_1: P12M + tier_2: P6M + tier_3: organization_governed + profile_locks: { fsi: immutable, sovereign: immutable } + REG-DP-003: { value: P90D, override: allow } # migration window + REG-DP-004: { requirement: required_in_deprecation_notice, override: allow } + REG-DP-005: { value: reject, override: not_permitted } # retirement behavior + REG-DP-006: { value: deprecated_runtime_state, override: allow } + REG-DP-007: { value: P30D, override: not_permitted } # emergency floor +``` + +### 3.2 Deprecation flow + +``` +Resource Type in active status + ▼ Deprecation proposal (PR + 30 day review) +Status: deprecated + │ Notifications to: + │ - All registered providers implementing this type + │ - All organizations with active realizations + │ - All webhook subscriptions to registry events + ▼ Sunset period (P12M Tier 1 / P6M Tier 2) + │ During sunset: + │ - New requests: succeed with deprecation warning + │ - Existing realizations: unaffected + │ - Drift detection: continues + │ - Provider implementations: remain valid + ▼ Retirement (status: retired) + │ Existing realizations → DEPRECATED_RUNTIME state + │ New requests → rejected (REG-DP-005) + ▼ Migration window (P90D) + │ Organizations migrate realizations to successor type + │ DEPRECATED_RUNTIME entities can be decommissioned or migrated + ▼ Post-migration window + DEPRECATED_RUNTIME entities remain operational but unsupported + Drift detection: continues but remediation is manual +``` + +### 3.3 Override defaults + +Organizations override via standard policy priority: + +```yaml +policy: + domain: platform + priority: 600.0.0 + type: gatekeeper + rule: > + If registry.deprecation.tier == tier_2 + THEN override: sunset_period = P12M +``` + +`fsi`/`sovereign` profiles lock REG-DP-002 as immutable. + +--- + +## 4. Review queue and approval workflow + +The Registry Manager exposes a review queue: + +``` +GET /api/v1/admin/registry/review-queue + ?tier=1|2|3 + &change_type=new|minor|breaking|deprecation + &assigned_to= + &status=pending_validation|pending_review|pending_shadow|ready_to_merge +``` + +### 4.1 Reviewer workflow + +1. Reviewer picks an item from queue +2. Inspects the PR diff, schema validation results, test cases, breaking + change detector output +3. Records decision via `POST /api/v1/admin/registry/{pr_id}:vote` +4. On final approval: Registry Manager merges PR; artifact transitions to + `proposed` (shadow validation period) +5. After shadow validation period without critical issues: transitions to + `active`; available in registry feed + +### 4.2 Auto-approval for low-risk changes + +Per profile, certain change types may auto-approve if CI gates pass: + +- Revision (config-only change): auto if CI passes in `minimal`/`dev` + profiles +- Minor version of existing type: auto with maintainer sign-off in `dev` +- Major versions and new Tier 1: always require human review regardless of + profile + +--- + +## 5. Resource Type Registry — Information Provider sub-type + +The Resource Type Registry is a specialized sub-type of Information Provider +(`provider_type: registry`). DCM treats it like any registered Information +Provider with extra capabilities: + +```yaml +internal_registry_registration: + provider_type: registry + registry_url: https://registry.corp.example.com + tier_1_source: https://registry.dcm-project.github.io + tier_2_sources: + - https://registry.dcm-project.github.io + - https://registry.partner-org.example.com + + sync: + schedule: "0 2 * * *" + on_sync_failure: alert | use_cached | block_new_requests + cache_ttl: P7D + + offline_mode: false + signed_bundle_import: false + bundle_signing_key_ref: + service_provider_uuid: + secret_path: "dcm/registry/bundle-verification-key" + + sovereignty_filter: + enabled: true + permitted_jurisdictions: [eu-west, eu-central] + + vendor_allowlist: + enabled: false + permitted_vendors: [dcm-project, vmware, redhat, hashicorp] +``` + +Sync is event-driven via `LISTEN/NOTIFY`; the Registry Sync worker pulls +upstream on the configured schedule and applies the federated registry +model (organization mirror + air-gapped bundle import). + +### 5.1 Air-gapped signed bundle + +``` +Online workstation (with registry access) + Pull registry delta since last sync + Sign with organization private key (via Credential Management Service) + Package: registry-update-YYYY-MM-DD.bundle + + ▼ Transfer via approved secure channel + +Air-gapped DCM deployment + Verify signature against organization public key + Import bundle → update local registry + Emit: registry.sync_completed audit event +``` + +--- + +## 6. Registry policy enforcement + +The Resource Type Registry is policy-governed. DCM enforces: + +| Policy target | Example rule | +|---|---| +| `registry_sync` | If resource_type.jurisdiction_compatibility NOT CONTAINS tenant.sovereignty_zone → reject_activation | +| `registry_activation` | If resource_type.publisher NOT IN approved_vendor_list → gatekeep: require_manual_approval | +| `registry_bundle_import` | If bundle.signature_valid == false → reject: unsigned bundles not permitted | +| `registry_sync` (prod) | If active_profile == prod AND resource_type.version_delta.type == major → gatekeep: major version upgrades require manual approval | +| `registry_sync` (audit) | Always inject: sync_audit.required = true, sync_audit.reviewer = platform_admin | + +### 6.1 Profile-appropriate registry policy groups + +DCM ships built-in registry policy groups, activated automatically per +profile: + +| Group | Profile | Behaviors | +|---|---|---| +| `system/group/registry-minimal` | minimal | Advisory; pull everything; no restrictions | +| `system/group/registry-dev` | dev | Warn on unverified sources; no vendor restrictions | +| `system/group/registry-standard` | standard | Block unverified; Tier 1+2 only; sovereignty filter | +| `system/group/registry-prod` | prod | Strict version pinning; approved vendor list; major version manual | +| `system/group/registry-fsi` | fsi | Exact version pinning; immutable sunset; dual approval | +| `system/group/registry-sovereign` | sovereign | Signed bundles only; offline; no external connectivity | + +--- + +## 7. Version policy enforcement + +DCM enforces version constraints strictly — never silently resolves to a +different version than declared: + +```yaml +resource_type_version_constraint: + resource_type: Compute.VirtualMachine + version_policy: exact | compatible | latest_minor | latest + pinned_version: "1.2.3" # required if version_policy: exact +``` + +**DCM never automatically upgrades across major versions** regardless of +`version_policy`. Moving from v1.x to v2.x always requires explicit +consumer action. + +| Profile | Default version policy | +|---|---| +| minimal | latest | +| dev | compatible | +| standard | compatible | +| prod | compatible | +| fsi | exact | +| sovereign | exact | + +--- + +## 8. Resource Type Authority enforcement + +DCM enforces the Resource Type Authority model: + +- The PR submitter becomes the Resource Type Authority unless `owned_by` is + declared otherwise +- The authority is the required approver for all future version PRs +- No new version of a spec activates without the authority's approval +- Authority transfer requires a formal transfer PR + +The Registry Manager refuses to merge a version PR without the declared +authority's approval (or successor designated by formal transfer). + +--- + +## 9. Policy IDs (DCM realization) + +| Policy | Rule | +|---|---| +| `REG-001-DCM` | DCM enforces PR-based GitOps proposals with automated validation gates that all pass before review | +| `REG-002-DCM` | DCM enforces minimum review periods and mandatory shadow validation in `proposed` status before promotion to `active` | +| `REG-003-DCM` | DCM applies deprecation lifecycle policies REG-DP-001 through REG-DP-007; overridable except where locked by profile | +| `REG-004-DCM` | DCM enforces version constraints strictly; never automatically upgrades across major versions | +| `REG-005-DCM` | DCM applies the placement tie-breaking hierarchy: policy preference → provider priority → tenant affinity → cost analysis → least loaded → consistent hash | +| `REG-006-DCM` | DCM supports federated registry with signed bundle import for air-gapped/sovereign deployments | +| `REG-007-DCM` | DCM activates profile-appropriate registry policy groups by default; organizations may extend or replace | +| `REG-011-DCM` | DCM supports static, Cost Analysis, or hybrid provider cost metadata sources; placement uses freshest available | From e8d42e53cad70d4015389c478fa1f98c6ddc67e8 Mon Sep 17 00:00:00 2001 From: Chris Roadfeldt Date: Sun, 28 Jun 2026 18:23:48 -0500 Subject: [PATCH 2/2] rename: GateKeeper policy -> Gating Policy (avoid OPA Gatekeeper collision) Sync from upstream croadfeldt/dcm. GateKeeper policy type -> Gating Policy (action gatekeep -> gate, op gatekeeping -> gating, enum gatekeeper -> gating). OPA Gatekeeper / Gatekeeper ConstraintTemplate references preserved. Files: architecture/governance-enforcement/contribution-pipeline.md architecture/governance-enforcement/policy-profiles.md architecture/governance-enforcement/registry-enforcement.md Co-Authored-By: Claude Opus 4.8 Signed-off-by: croadfeldt --- .../contribution-pipeline.md | 12 +++---- .../governance-enforcement/policy-profiles.md | 32 +++++++++---------- .../registry-enforcement.md | 6 ++-- 3 files changed, 25 insertions(+), 25 deletions(-) diff --git a/architecture/governance-enforcement/contribution-pipeline.md b/architecture/governance-enforcement/contribution-pipeline.md index c827fb3..a8deeea 100644 --- a/architecture/governance-enforcement/contribution-pipeline.md +++ b/architecture/governance-enforcement/contribution-pipeline.md @@ -40,7 +40,7 @@ dcm-policy-store/ operations/ tenant/ / # Consumer/Tenant authored - gatekeeper/ + gating/ transformation/ groups/ provider/ @@ -68,7 +68,7 @@ metadata: ```yaml artifact_metadata: uuid: - handle: "tenant/payments/gatekeeper/cost-ceiling" + handle: "tenant/payments/gating/cost-ceiling" version: "1.0.0" status: active contributed_by: @@ -208,21 +208,21 @@ POST /api/v1/contribute/policy Authorization: Bearer X-DCM-Tenant: { - "policy_type": "gatekeeper", - "handle": "tenant/payments/gatekeeper/cost-ceiling", + "policy_type": "gating", + "handle": "tenant/payments/gating/cost-ceiling", "domain": "tenant", "concern_type": "operational", "enforcement": "soft", "match": {...}, "output": {...}, "shadow_mode": true, - "commit_message": "Add monthly cost ceiling GateKeeper for Payments Tenant" + "commit_message": "Add monthly cost ceiling Gating Policy for Payments Tenant" } Response 202: { "contribution_uuid": "", - "policy_handle": "tenant/payments/gatekeeper/cost-ceiling", + "policy_handle": "tenant/payments/gating/cost-ceiling", "status": "proposed", "shadow_mode": true, "review_required": true, diff --git a/architecture/governance-enforcement/policy-profiles.md b/architecture/governance-enforcement/policy-profiles.md index 225f8b7..4da31ad 100644 --- a/architecture/governance-enforcement/policy-profiles.md +++ b/architecture/governance-enforcement/policy-profiles.md @@ -56,7 +56,7 @@ Policy Profile — complete use-case configuration Policy Groups — single-concern policy collections │ composed of ▼ -Policies — individual Transformation / Validation / GateKeeper rules +Policies — individual Transformation / Validation / Gating Policy rules │ optionally sourced from ▼ External Policy Evaluators — external authoritative policy sources @@ -82,8 +82,8 @@ Profiles implement the DCM design priority order (see [Foundational Abstractions Policies in DCM are not exclusively authored by platform admins. The DCM federated contribution model enables all actor types to author policies within their permitted domain scope: - **Platform admins** — all domains, all policy types -- **Consumers / Tenant admins** — tenant domain policies (GateKeeper, Transformation, Recovery, Lifecycle, Orchestration Flow, Governance Matrix rules scoped to their Tenant) -- **Service Providers** — provider-domain GateKeeper and Validation policies for their resource types +- **Consumers / Tenant admins** — tenant domain policies (Gating Policy, Transformation, Recovery, Lifecycle, Orchestration Flow, Governance Matrix rules scoped to their Tenant) +- **Service Providers** — provider-domain Gating Policy and Validation policies for their resource types - **Peer DCM instances** — policy templates contributed through verified federation relationships This is not a special case — it is the standard GitOps PR model applied to all contributor types. Consumer-authored policies go through the same lifecycle (developing → proposed → active) with appropriate review requirements per the active profile. See [Federated Contribution Model](https://github.com/croadfeldt/udlm/blob/main/governance/federated-contribution-model.md) for the complete specification. @@ -408,7 +408,7 @@ policy_group: # Constituent policies policies: - policy_uuid: - handle: "system/gatekeeper/pci-encryption-aes256" + handle: "system/gating/pci-encryption-aes256" description: "Enforce AES-256 on all PCI-scoped storage" placement_phase: pre - policy_uuid: @@ -420,7 +420,7 @@ policy_group: description: "Auto-inject PCI classification on scoped resources" placement_phase: pre - policy_uuid: - handle: "system/gatekeeper/pci-audit-retention" + handle: "system/gating/pci-audit-retention" description: "Enforce 10-year audit retention for PCI evidence" placement_phase: pre @@ -461,7 +461,7 @@ policy_group: # Additional policies added below are on top of the parent policies: - policy_uuid: - handle: "org/gatekeeper/our-pci-additional-control" + handle: "org/gating/our-pci-additional-control" ``` ### 2.4 DCM Built-In Policy Groups @@ -777,7 +777,7 @@ All three delivery mechanisms result in the same thing: Rego policies evaluated ```yaml policy: handle: "vm-size-limits" - policy_type: gatekeeper + policy_type: gating delivery: mode: push # or: pull, opa_bundle, external_schema source_url: "https://git.corp/policies" # for pull/bundle modes @@ -787,7 +787,7 @@ policy: ``` **Trust levels (Internal mode):** -- `trusted` — GateKeeper authority (can deny requests) +- `trusted` — Gating Policy authority (can deny requests) - `verified` — Transformation and Validation authority only - `untrusted` — advisory only (shadow mode enforcement) @@ -811,7 +811,7 @@ policy: auth: mtls data_request_spec: # data minimization — only declared fields sent fields: [resource_type, sovereignty_zone, data_classification, tenant_uuid] - on_unavailable: gatekeep # fail-closed — unknown is not safe + on_unavailable: gate # fail-closed — unknown is not safe trust_level: verified # minimum verified for enrichment ``` @@ -825,11 +825,11 @@ External evaluation introduces governance concerns that Internal mode does not: | BBQ-002 | Data minimization — only fields declared in `data_request_spec` are sent | | BBQ-003 | If the external endpoint is outside the entity's sovereignty zone, the query is blocked unless explicitly authorized | | BBQ-004 | Full audit record per query-response cycle, including `audit_token` for cross-system correlation | -| BBQ-005 | Default failure behavior is `gatekeep` — if the external system is unavailable, the request is denied (fail-closed) | +| BBQ-005 | Default failure behavior is `gate` — if the external system is unavailable, the request is denied (fail-closed) | | BBQ-006 | Cached results must include the original query timestamp and validity period in provenance | | BBQ-007 | Fields injected by external enrichment carry standard field-level provenance: `source_type: external_external_policy_evaluator`, `source_uuid`, and `audit_token` | -| BBQ-008 | The override control model applies to enrichment-injected fields — a GateKeeper policy may restrict or refuse external enrichment on specific fields | -| BBQ-009 | External enrichment requires minimum `verified` trust level; GateKeeper authority requires `trusted` with dual-approval elevation | +| BBQ-008 | The override control model applies to enrichment-injected fields — a Gating policy may restrict or refuse external enrichment on specific fields | +| BBQ-009 | External enrichment requires minimum `verified` trust level; Gating Policy authority requires `trusted` with dual-approval elevation | ### 4.4 Policy Sources and Policy Groups @@ -850,7 +850,7 @@ policy_group: ### 4.5 Policy Health and Lifecycle - **Internal policies:** Health is determined by OPA engine health. If OPA is unavailable, all Internal policies are degraded. -- **External policies:** Health is determined by endpoint availability. Each external endpoint has a health check (HTTP GET to a declared health URL). Unhealthy external policies trigger their `on_unavailable` behavior (default: `gatekeep`). +- **External policies:** Health is determined by endpoint availability. Each external endpoint has a health check (HTTP GET to a declared health URL). Unhealthy external policies trigger their `on_unavailable` behavior (default: `gate`). - **Deprecation:** Policies follow the `active → deprecated → retired` lifecycle. Deprecated policies fire with a warning in the audit trail. Retired policies are no longer evaluated. --- @@ -913,10 +913,10 @@ Request Layer (consumer declared TTL) ↓ Transformation Policy (enrich TTL from business context) ↓ -GateKeeper Policy (highest — may lock TTL as immutable) +Gating Policy (highest — may lock TTL as immutable) ``` -A consumer can declare `ttl: P14D` in their request. A GateKeeper policy can override this to `P7D` and lock it immutable if organizational policy mandates shorter maximum lifetimes. A Core Layer can set default TTLs for resource classes. The provenance chain records every modification. +A consumer can declare `ttl: P14D` in their request. A Gating policy can override this to `P7D` and lock it immutable if organizational policy mandates shorter maximum lifetimes. A Core Layer can set default TTLs for resource classes. The provenance chain records every modification. ### 5.5 Expiry Enforcement @@ -933,7 +933,7 @@ Expiry enforcement is a DCM concern — not a provider concern. The provider doe | Policy | Rule | |--------|------| | `LTC-001` | Lifecycle time constraints follow standard data model precedence — layers, request, policies | -| `LTC-002` | GateKeeper policies may lock lifecycle constraints as `override: immutable` or `immutable_ceiling: absolute` | +| `LTC-002` | Gating policies may lock lifecycle constraints as `override: immutable` or `immutable_ceiling: absolute` | | `LTC-003` | Expiry enforcement is a DCM control plane function — not a provider concern | | `LTC-004` | When multiple time constraints exist on an entity, the earliest expiry wins | | `LTC-005` | Expired entities that fail to execute their `on_expiry` action enter `PENDING_EXPIRY_ACTION` state and trigger an escalation | diff --git a/architecture/governance-enforcement/registry-enforcement.md b/architecture/governance-enforcement/registry-enforcement.md index 78ce1b9..91427e2 100644 --- a/architecture/governance-enforcement/registry-enforcement.md +++ b/architecture/governance-enforcement/registry-enforcement.md @@ -201,7 +201,7 @@ Organizations override via standard policy priority: policy: domain: platform priority: 600.0.0 - type: gatekeeper + type: gating rule: > If registry.deprecation.tier == tier_2 THEN override: sunset_period = P12M @@ -310,9 +310,9 @@ The Resource Type Registry is policy-governed. DCM enforces: | Policy target | Example rule | |---|---| | `registry_sync` | If resource_type.jurisdiction_compatibility NOT CONTAINS tenant.sovereignty_zone → reject_activation | -| `registry_activation` | If resource_type.publisher NOT IN approved_vendor_list → gatekeep: require_manual_approval | +| `registry_activation` | If resource_type.publisher NOT IN approved_vendor_list → gate: require_manual_approval | | `registry_bundle_import` | If bundle.signature_valid == false → reject: unsigned bundles not permitted | -| `registry_sync` (prod) | If active_profile == prod AND resource_type.version_delta.type == major → gatekeep: major version upgrades require manual approval | +| `registry_sync` (prod) | If active_profile == prod AND resource_type.version_delta.type == major → gate: major version upgrades require manual approval | | `registry_sync` (audit) | Always inject: sync_audit.required = true, sync_audit.reviewer = platform_admin | ### 6.1 Profile-appropriate registry policy groups