From d4df1e01df90410da3161af3746a764e4c2ac3ea Mon Sep 17 00:00:00 2001 From: Benjamin Admin Date: Thu, 25 Jun 2026 19:29:37 +0200 Subject: [PATCH] feat(compliance): GET /sdk/v1/compliance/obligation-status (file-backed graph) Vertical slice over the Compliance Execution Graph: obligation_id -> accepted controls -> required evidence -> status. NEVER auto-asserts fulfillment - with no evidence collection wired (MVP), a mapped obligation is "not_assessed" and every required evidence is "missing". Fail-closed: no id -> 400; unknown id -> unknown_obligation; mapped-but-no-control -> unmapped; graph not loaded -> 503. - ComplianceGraphHandlers (separate from the DB-backed ObligationsHandlers): loads Registry join keys + accepted control mappings + evidence once at start. - LoadComplianceGraph: candidate-path resolution across dev/container/test. - Data plumbing: Dockerfile now COPYs data/{control_mappings,evidence_requirements, obligations}; data/obligations/obligation_join_keys.json is a SYNCED COPY of the repo-root Registry contract (re-sync on Registry growth). - Table-driven handler test (mapped/unmapped/unknown/400 + no-fulfillment-claim). Co-Authored-By: Claude Opus 4.7 --- ai-compliance-sdk/Dockerfile | 6 + .../obligations/obligation_join_keys.json | 826 ++++++++++++++++++ .../api/handlers/compliance_graph_handlers.go | 126 +++ .../compliance_graph_handlers_test.go | 94 ++ ai-compliance-sdk/internal/app/app.go | 9 +- ai-compliance-sdk/internal/app/routes.go | 2 + .../internal/ucca/compliance_graph_loader.go | 89 ++ 7 files changed, 1151 insertions(+), 1 deletion(-) create mode 100644 ai-compliance-sdk/data/obligations/obligation_join_keys.json create mode 100644 ai-compliance-sdk/internal/api/handlers/compliance_graph_handlers.go create mode 100644 ai-compliance-sdk/internal/api/handlers/compliance_graph_handlers_test.go create mode 100644 ai-compliance-sdk/internal/ucca/compliance_graph_loader.go diff --git a/ai-compliance-sdk/Dockerfile b/ai-compliance-sdk/Dockerfile index 97a10bce..03c7384e 100644 --- a/ai-compliance-sdk/Dockerfile +++ b/ai-compliance-sdk/Dockerfile @@ -33,6 +33,12 @@ COPY migrations/ ./migrations/ # Copy policy files (YAML rules) COPY policies/ ./policies/ +# Copy Compliance Execution Graph data (file-backed: Registry join-key copy + accepted control +# mappings + evidence requirements) consumed by GET /sdk/v1/compliance/obligation-status. +COPY data/control_mappings/ ./data/control_mappings/ +COPY data/evidence_requirements/ ./data/evidence_requirements/ +COPY data/obligations/ ./data/obligations/ + # Create non-root user RUN adduser -D -u 1000 appuser USER appuser diff --git a/ai-compliance-sdk/data/obligations/obligation_join_keys.json b/ai-compliance-sdk/data/obligations/obligation_join_keys.json new file mode 100644 index 00000000..7a5d5bec --- /dev/null +++ b/ai-compliance-sdk/data/obligations/obligation_join_keys.json @@ -0,0 +1,826 @@ +{ + "schema_version": "obligation_join_keys_v1", + "contract": "obligation_id ist der stabile Join-Key. Legal Knowledge Graph haengt citation_spans an obligation_id; Compliance Execution Graph mappt control_mapping.source_norm -> obligation_id. Interim-Bruecke = citation_units. obligation_id NIE neu vergeben (re-link).", + "count": 93, + "obligation_ids": [ + { + "obligation_id": "sbom_creation", + "regulation": "CRA", + "family": "sbom", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I Part II (1)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "sbom_dependency_coverage", + "regulation": "CRA", + "family": "sbom", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Art. 3(36) i.V.m. Annex I Part II (1)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "sbom_format_standard", + "regulation": "CRA", + "family": "sbom", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I Part II (1)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "sbom_maintenance_update", + "regulation": "CRA", + "family": "sbom", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I Part II (1)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "sbom_completeness_verification", + "regulation": "CRA", + "family": "sbom", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "sbom_tooling_automation", + "regulation": "CRA", + "family": "sbom", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "IMPLEMENTATION" + }, + { + "obligation_id": "sbom_access_provision", + "regulation": "CRA", + "family": "sbom", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "sbom_authority_provision", + "regulation": "CRA", + "family": "sbom", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Art. 31 / Annex I Part II (1)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "sbom_confidentiality", + "regulation": "CRA", + "family": "sbom", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Art. 31(4)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "sbom_supply_chain_contracts", + "regulation": "CRA", + "family": "sbom", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "sbom_technical_documentation", + "regulation": "CRA", + "family": "sbom", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Art. 31 i.V.m. Annex VII" + ], + "source_role": "EVIDENCE" + }, + { + "obligation_id": "vuln_identification_inventory", + "regulation": "CRA", + "family": "vuln", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I Part II (1)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "vuln_assessment_prioritization", + "regulation": "CRA", + "family": "vuln", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I Part II (1)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "vuln_remediation_patching", + "regulation": "CRA", + "family": "vuln", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I Part II (2) & (8)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "vuln_handling_process", + "regulation": "CRA", + "family": "vuln", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Article 13(8) & Annex VII" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "coordinated_vulnerability_disclosure", + "regulation": "CRA", + "family": "vuln", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I Part II (5)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "exploited_vuln_reporting_authorities", + "regulation": "CRA", + "family": "vuln", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Article 14 & Article 16" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "vuln_info_dissemination_users", + "regulation": "CRA", + "family": "vuln", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I Part II (4) & (6)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "user_authentication_required", + "regulation": "CRA", + "family": "authentication", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I (2)(d)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "authentication_policy_documented", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "auth_exceptions_documented", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "mfa_required", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "step_up_authentication", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "privileged_op_reauth", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "strong_crypto_authentication", + "regulation": "CRA", + "family": "authentication", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I (2)(e)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "credential_lifecycle_management", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "credential_confidentiality_protection", + "regulation": "CRA", + "family": "authentication", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I (2)(e)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "password_policy", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "no_default_credentials", + "regulation": "CRA", + "family": "authentication", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I (2)(a)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "account_lockout_failed_attempts", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "server_side_validation", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "session_binding_management", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "reauth_after_inactivity", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "token_validation_lifecycle", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "mutual_authentication", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "revocation_check", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "encrypted_auth_channel", + "regulation": "CRA", + "family": "authentication", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I (2)(e)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "tls_certificate_auth", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "service_to_service_auth", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "auth_key_management", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "biometric_authentication", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "federated_auth_assertions", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "separate_authn_authz", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "remote_access_authentication", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "supplier_access_auth", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "personal_admin_accounts", + "regulation": "CRA", + "family": "authentication", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "firmware_software_authentication", + "regulation": "CRA", + "family": "authentication", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I (2)(c)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "event_logging_security_events", + "regulation": "CRA", + "family": "logging", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I Part I (2)(k)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "access_control_event_logging", + "regulation": "CRA", + "family": "logging", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I Part I (2)(k)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "audit_trail_admin_actions", + "regulation": "CRA", + "family": "logging", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I Part I (2)(k)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "log_integrity_immutability", + "regulation": "CRA", + "family": "logging", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I Part I (2)(k)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "log_access_control_protection", + "regulation": "CRA", + "family": "logging", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I Part I (2)(k)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "log_retention_archival", + "regulation": "CRA", + "family": "logging", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "centralized_log_management", + "regulation": "CRA", + "family": "logging", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "log_monitoring_alerting", + "regulation": "CRA", + "family": "logging", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I Part I (2)(k)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "log_data_minimization_privacy", + "regulation": "CRA", + "family": "logging", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "log_format_standardization", + "regulation": "CRA", + "family": "logging", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "log_timestamp_synchronization", + "regulation": "CRA", + "family": "logging", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "logging_availability_resilience", + "regulation": "CRA", + "family": "logging", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "logging_thread_safety_correctness", + "regulation": "CRA", + "family": "logging", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "IMPLEMENTATION" + }, + { + "obligation_id": "logging_library_supply_chain", + "regulation": "CRA", + "family": "logging", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "logging_config_management", + "regulation": "CRA", + "family": "logging", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "logging_governance_roles", + "regulation": "CRA", + "family": "logging", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "incident_response_logging", + "regulation": "CRA", + "family": "logging", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "log_transmission_security", + "regulation": "CRA", + "family": "logging", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "network_traffic_logging", + "regulation": "CRA", + "family": "logging", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "remote_access_control_least_privilege", + "regulation": "CRA", + "family": "remote_access", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I (1)(2)(d)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "remote_access_confidentiality_integrity", + "regulation": "CRA", + "family": "remote_access", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I (1)(2)(b)(c)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "remote_session_management", + "regulation": "CRA", + "family": "remote_access", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "remote_access_mfa", + "regulation": "CRA", + "family": "remote_access", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "remote_access_encryption", + "regulation": "CRA", + "family": "remote_access", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "reject_insecure_remote_protocols", + "regulation": "CRA", + "family": "remote_access", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "remote_access_logging_audit", + "regulation": "CRA", + "family": "remote_access", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I (1)(2)(g)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "remote_access_user_validation_ot", + "regulation": "CRA", + "family": "remote_access", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "remote_access_training", + "regulation": "CRA", + "family": "remote_access", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "remote_access_architecture_design", + "regulation": "CRA", + "family": "remote_access", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "remote_access_attack_surface_min", + "regulation": "CRA", + "family": "remote_access", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I (1)(2)(a)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "remote_access_vuln_patch_mgmt", + "regulation": "CRA", + "family": "remote_access", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I (2)(1)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "remote_access_threat_detection", + "regulation": "CRA", + "family": "remote_access", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "remote_maintenance_governance", + "regulation": "CRA", + "family": "remote_access", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "temporary_remote_access_mgmt", + "regulation": "CRA", + "family": "remote_access", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "remote_access_data_export_protection", + "regulation": "CRA", + "family": "remote_access", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "component_remote_interface_security", + "regulation": "CRA", + "family": "remote_access", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "remote_access_fallback_concept", + "regulation": "CRA", + "family": "remote_access", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "provide_security_updates", + "regulation": "CRA", + "family": "updates", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I (2)(c)", + "Art. 13" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "support_period_maintenance", + "regulation": "CRA", + "family": "updates", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Art. 13(8)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "signed_update_integrity", + "regulation": "CRA", + "family": "updates", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I (1)(3)(f)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "trusted_update_source", + "regulation": "CRA", + "family": "updates", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I (1)(3)(d)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "update_testing_validation", + "regulation": "CRA", + "family": "updates", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "update_rollback", + "regulation": "CRA", + "family": "updates", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "GUIDANCE" + }, + { + "obligation_id": "automatic_updates_optout", + "regulation": "CRA", + "family": "updates", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I (2)(c)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "update_risk_assessment", + "regulation": "CRA", + "family": "updates", + "tier": "LEGAL_MINIMUM", + "citation_units": [ + "Annex I (1)(2)" + ], + "source_role": "LEGAL_BASIS" + }, + { + "obligation_id": "secure_modification_control", + "regulation": "CRA", + "family": "updates", + "tier": "BEST_PRACTICE", + "citation_units": [], + "source_role": "IMPLEMENTATION" + } + ] +} \ No newline at end of file diff --git a/ai-compliance-sdk/internal/api/handlers/compliance_graph_handlers.go b/ai-compliance-sdk/internal/api/handlers/compliance_graph_handlers.go new file mode 100644 index 00000000..0f1d912f --- /dev/null +++ b/ai-compliance-sdk/internal/api/handlers/compliance_graph_handlers.go @@ -0,0 +1,126 @@ +package handlers + +import ( + "net/http" + "strings" + + "github.com/gin-gonic/gin" + + "github.com/breakpilot/ai-compliance-sdk/internal/ucca" +) + +// ComplianceGraphHandlers serves the read-only Compliance Execution Graph +// (Regulation -> Obligation -> Control -> Evidence) over the file-backed bridge artifacts. +// It is intentionally SEPARATE from the DB-backed ObligationsHandlers: this is the curated +// cross-session graph (Registry join keys + accepted control mappings + evidence requirements), +// loaded once at startup. Fail-closed: if the graph could not load, every request answers 503. +type ComplianceGraphHandlers struct { + joins *ucca.ObligationJoinKeys + mappings *ucca.ControlMappingSet + evidence *ucca.EvidenceRequirementSet + loadErr error +} + +// NewComplianceGraphHandlers loads the graph once. Construction never fails; a load error is +// retained and surfaced as 503 per request (matches the codebase's load-warn-continue startup). +func NewComplianceGraphHandlers() *ComplianceGraphHandlers { + joins, mappings, evidence, err := ucca.LoadComplianceGraph() + return &ComplianceGraphHandlers{joins: joins, mappings: mappings, evidence: evidence, loadErr: err} +} + +// LoadError exposes a startup load failure so the wiring can log a warning. +func (h *ComplianceGraphHandlers) LoadError() error { return h.loadErr } + +// RegisterRoutes mounts the compliance-graph routes under /compliance. +func (h *ComplianceGraphHandlers) RegisterRoutes(r *gin.RouterGroup) { + g := r.Group("/compliance") + g.GET("/obligation-status", h.ObligationStatus) +} + +type cgControlDTO struct { + Framework string `json:"framework"` + Control string `json:"control"` + MappingType string `json:"mapping_type"` + EvidenceRequired []string `json:"evidence_required"` + EvidenceStatus string `json:"evidence_status"` // missing | partial | present | none_required +} + +type cgStatusResponse struct { + ObligationID string `json:"obligation_id"` + OverallStatus string `json:"overall_status"` // unknown_obligation | unmapped | not_assessed | open | met + LegalBasis []string `json:"legal_basis,omitempty"` + CitationSpans string `json:"citation_spans"` // "pending" until the Legal-KG attaches spans + Controls []cgControlDTO `json:"controls"` + Note string `json:"note,omitempty"` +} + +// ObligationStatus answers GET /sdk/v1/compliance/obligation-status?obligation_id=... +// +// It NEVER asserts fulfillment automatically. With no evidence collection wired (MVP), a mapped +// obligation is "not_assessed" and every required evidence is "missing" — the honest picture is +// "required vs present evidence", not "a document exists". Fail-closed otherwise: +// - no obligation_id -> 400 +// - graph not loaded -> 503 +// - id not in the Registry -> 200 overall_status=unknown_obligation +// - mapped but no control yet -> 200 overall_status=unmapped +func (h *ComplianceGraphHandlers) ObligationStatus(c *gin.Context) { + if h.loadErr != nil { + c.JSON(http.StatusServiceUnavailable, gin.H{"error": "compliance graph unavailable", "detail": h.loadErr.Error()}) + return + } + obID := strings.TrimSpace(c.Query("obligation_id")) + if obID == "" { + c.JSON(http.StatusBadRequest, gin.H{"error": "obligation_id query parameter required"}) + return + } + resp := cgStatusResponse{ObligationID: obID, CitationSpans: "pending", Controls: []cgControlDTO{}} + + if h.joins.FindObligation(obID) == nil { + resp.OverallStatus = "unknown_obligation" + resp.Note = "obligation_id not in the Registry join-key contract" + c.JSON(http.StatusOK, resp) + return + } + + // MVP: hasEvidence=nil -> no collection wired -> all required evidence counts as missing. + st := ucca.AssessObligationStatus(h.joins, h.mappings, h.evidence, obID, nil) + resp.LegalBasis = st.LegalBasis + + if len(st.Controls) == 0 { + resp.OverallStatus = "unmapped" + resp.Note = "no accepted control maps to this obligation yet" + c.JSON(http.StatusOK, resp) + return + } + + for _, cs := range st.Controls { + types := make([]string, 0, len(cs.RequiredEvidence)) + for _, e := range cs.RequiredEvidence { + types = append(types, e.EvidenceType) + } + resp.Controls = append(resp.Controls, cgControlDTO{ + Framework: cs.Framework, + Control: cs.Control, + MappingType: cs.MappingType, + EvidenceRequired: types, + EvidenceStatus: cgEvidenceStatus(len(cs.RequiredEvidence), len(cs.MissingEvidence)), + }) + } + // No fulfillment claim without real evidence collection. + resp.OverallStatus = "not_assessed" + resp.Note = "evidence collection not wired (MVP) — fulfillment not asserted" + c.JSON(http.StatusOK, resp) +} + +func cgEvidenceStatus(required, missing int) string { + switch { + case required == 0: + return "none_required" + case missing == 0: + return "present" + case missing == required: + return "missing" + default: + return "partial" + } +} diff --git a/ai-compliance-sdk/internal/api/handlers/compliance_graph_handlers_test.go b/ai-compliance-sdk/internal/api/handlers/compliance_graph_handlers_test.go new file mode 100644 index 00000000..b080c0da --- /dev/null +++ b/ai-compliance-sdk/internal/api/handlers/compliance_graph_handlers_test.go @@ -0,0 +1,94 @@ +package handlers + +import ( + "encoding/json" + "net/http" + "net/http/httptest" + "testing" + + "github.com/gin-gonic/gin" +) + +func newComplianceGraphTestRouter(t *testing.T) *gin.Engine { + t.Helper() + gin.SetMode(gin.TestMode) + h := NewComplianceGraphHandlers() + if err := h.LoadError(); err != nil { + t.Fatalf("compliance graph failed to load (candidate paths): %v", err) + } + r := gin.New() + h.RegisterRoutes(r.Group("/sdk/v1")) + return r +} + +func getObligationStatus(t *testing.T, r *gin.Engine, query string) (int, cgStatusResponse) { + t.Helper() + w := httptest.NewRecorder() + req, _ := http.NewRequest(http.MethodGet, "/sdk/v1/compliance/obligation-status"+query, nil) + r.ServeHTTP(w, req) + var resp cgStatusResponse + if w.Code == http.StatusOK { + if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil { + t.Fatalf("decode body %q: %v", w.Body.String(), err) + } + } + return w.Code, resp +} + +func TestObligationStatus(t *testing.T) { + r := newComplianceGraphTestRouter(t) + + tests := []struct { + name string + query string + wantHTTP int + wantOverall string + wantControls bool // expect >=1 control + }{ + {"missing param -> 400", "", http.StatusBadRequest, "", false}, + {"unknown id -> unknown_obligation", "?obligation_id=does_not_exist", http.StatusOK, "unknown_obligation", false}, + {"mapped (OWASP V6) -> not_assessed", "?obligation_id=user_authentication_required", http.StatusOK, "not_assessed", true}, + {"in registry, no control -> unmapped", "?obligation_id=sbom_creation", http.StatusOK, "unmapped", false}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + code, resp := getObligationStatus(t, r, tt.query) + if code != tt.wantHTTP { + t.Fatalf("http %d, want %d", code, tt.wantHTTP) + } + if tt.wantHTTP != http.StatusOK { + return + } + if resp.OverallStatus != tt.wantOverall { + t.Errorf("overall_status=%q, want %q", resp.OverallStatus, tt.wantOverall) + } + if tt.wantControls && len(resp.Controls) == 0 { + t.Error("expected >=1 control") + } + if !tt.wantControls && len(resp.Controls) != 0 { + t.Errorf("expected 0 controls, got %d", len(resp.Controls)) + } + if resp.CitationSpans != "pending" { + t.Errorf("citation_spans=%q, want pending", resp.CitationSpans) + } + }) + } +} + +// The MVP must NEVER auto-assert fulfillment: with no evidence collection wired, every required +// evidence is "missing" and the overall status stays "not_assessed". +func TestObligationStatus_NoFulfillmentClaim(t *testing.T) { + r := newComplianceGraphTestRouter(t) + code, resp := getObligationStatus(t, r, "?obligation_id=user_authentication_required") + if code != http.StatusOK { + t.Fatalf("http %d", code) + } + if resp.OverallStatus == "met" || resp.OverallStatus == "erfuellt" { + t.Fatalf("MVP must not assert fulfillment, got overall_status=%q", resp.OverallStatus) + } + for _, ctl := range resp.Controls { + if len(ctl.EvidenceRequired) > 0 && ctl.EvidenceStatus != "missing" { + t.Errorf("control %s/%s evidence_status=%q, want missing (no collection wired)", ctl.Framework, ctl.Control, ctl.EvidenceStatus) + } + } +} diff --git a/ai-compliance-sdk/internal/app/app.go b/ai-compliance-sdk/internal/app/app.go index b01b3769..487664bb 100644 --- a/ai-compliance-sdk/internal/app/app.go +++ b/ai-compliance-sdk/internal/app/app.go @@ -153,6 +153,12 @@ func buildRouter(cfg *config.Config, pool *pgxpool.Pool) *gin.Engine { ragHandlers := handlers.NewRAGHandlers(corpusVersionStore) obligationsHandlers := handlers.NewObligationsHandlersWithStore(obligationsStore) + // Compliance Execution Graph (file-backed: Registry join keys + accepted control mappings + evidence) + complianceGraphHandlers := handlers.NewComplianceGraphHandlers() + if err := complianceGraphHandlers.LoadError(); err != nil { + log.Printf("WARNING: compliance graph not loaded (obligation-status -> 503): %v", err) + } + // Regulatory News allV2Regs, err := ucca.LoadAllV2Regulations() if err != nil { @@ -201,7 +207,8 @@ func buildRouter(cfg *config.Config, pool *pgxpool.Pool) *gin.Engine { uccaHandlers, escalationHandlers, obligationsHandlers, ragHandlers, roadmapHandlers, workshopHandlers, portfolioHandlers, academyHandlers, trainingHandlers, whistleblowerHandlers, iaceHandler, - gapHandler, maximizerHandlers, regulatoryNewsHandlers, useCaseHandler) + gapHandler, maximizerHandlers, regulatoryNewsHandlers, useCaseHandler, + complianceGraphHandlers) return router } diff --git a/ai-compliance-sdk/internal/app/routes.go b/ai-compliance-sdk/internal/app/routes.go index 396402bb..562f956b 100644 --- a/ai-compliance-sdk/internal/app/routes.go +++ b/ai-compliance-sdk/internal/app/routes.go @@ -30,6 +30,7 @@ func registerRoutes( maximizerHandlers *handlers.MaximizerHandlers, regulatoryNewsHandlers *handlers.RegulatoryNewsHandlers, useCaseHandler *handlers.UseCaseHandler, + complianceGraphHandlers *handlers.ComplianceGraphHandlers, ) { v1 := router.Group("/sdk/v1") { @@ -54,6 +55,7 @@ func registerRoutes( registerMaximizerRoutes(v1, maximizerHandlers) registerUseCaseRoutes(v1, useCaseHandler) v1.GET("/regulatory-news", regulatoryNewsHandlers.GetNews) + complianceGraphHandlers.RegisterRoutes(v1) } } diff --git a/ai-compliance-sdk/internal/ucca/compliance_graph_loader.go b/ai-compliance-sdk/internal/ucca/compliance_graph_loader.go new file mode 100644 index 00000000..f47978cf --- /dev/null +++ b/ai-compliance-sdk/internal/ucca/compliance_graph_loader.go @@ -0,0 +1,89 @@ +package ucca + +import ( + "fmt" + "os" + "path/filepath" + "runtime" +) + +// graphCallerRel resolves a path relative to THIS source file (build-time location), so the +// graph data is findable under `go test` (cwd = package dir) regardless of working directory. +// In a built container the source is gone, so cwd-relative candidates carry the load instead. +func graphCallerRel(rel string) string { + _, file, _, ok := runtime.Caller(0) + if !ok { + return "" + } + return filepath.Join(filepath.Dir(file), rel) +} + +// firstExisting returns the first candidate path that exists with the requested kind (dir vs +// file). Empty candidates (e.g. unset env overrides) are skipped. +func firstExisting(candidates []string, wantDir bool) string { + for _, p := range candidates { + if p == "" { + continue + } + info, err := os.Stat(p) + if err != nil || info.IsDir() != wantDir { + continue + } + return p + } + return "" +} + +// LoadComplianceGraph loads the file-backed Compliance Execution Graph: the Registry join-key +// contract (obligations/obligation_join_keys.json — owned by the Obligation session) + our +// curated, accepted control mappings + evidence requirements. Locations are resolved across +// three layouts: dev (cwd = ai-compliance-sdk/, canonical contract at ../obligations), container +// (WORKDIR /app, data/ copied in incl. a synced data/obligations/ copy) and `go test` +// (cwd = package dir, via graphCallerRel). Fail-closed: a missing/invalid source returns an +// error so the handler serves 503 — never a half-built graph. +// +// NOTE: data/obligations/obligation_join_keys.json is a SYNCED COPY of the repo-root contract +// (the canonical owner is the Obligation session). Re-sync it when the Registry grows; dev/test +// prefer the canonical repo-root path, only the container falls back to the copy. +func LoadComplianceGraph() (*ObligationJoinKeys, *ControlMappingSet, *EvidenceRequirementSet, error) { + joinPath := firstExisting([]string{ + os.Getenv("BP_OBLIGATION_JOIN_KEYS"), + "../obligations/obligation_join_keys.json", + graphCallerRel("../../../obligations/obligation_join_keys.json"), + "data/obligations/obligation_join_keys.json", + graphCallerRel("../../data/obligations/obligation_join_keys.json"), + }, false) + if joinPath == "" { + return nil, nil, nil, fmt.Errorf("obligation_join_keys.json not found in any candidate path") + } + mapDir := firstExisting([]string{ + os.Getenv("BP_CONTROL_MAPPINGS_DIR"), + "data/control_mappings", + graphCallerRel("../../data/control_mappings"), + }, true) + if mapDir == "" { + return nil, nil, nil, fmt.Errorf("control_mappings dir not found in any candidate path") + } + evDir := firstExisting([]string{ + os.Getenv("BP_EVIDENCE_DIR"), + "data/evidence_requirements", + graphCallerRel("../../data/evidence_requirements"), + }, true) + if evDir == "" { + return nil, nil, nil, fmt.Errorf("evidence_requirements dir not found in any candidate path") + } + + joins, err := LoadObligationJoinKeys(joinPath) + if err != nil { + return nil, nil, nil, fmt.Errorf("load join keys (%s): %w", joinPath, err) + } + mappings, err := LoadControlMappings(mapDir) + if err != nil { + return nil, nil, nil, fmt.Errorf("load control mappings (%s): %w", mapDir, err) + } + evidence, err := LoadEvidenceRequirements(evDir) + if err != nil { + return nil, nil, nil, fmt.Errorf("load evidence (%s): %w", evDir, err) + } + return joins, mappings, evidence, nil +}