stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
cf5b72974f923126944f4dcd47e85864ebb31a3b
git.stella-ops.org/docs/features/unchecked/libraries/policy-lock-generator.md

2.4 KiB
Raw Blame History

Policy Lock Generator (Verdict Reproducibility)

Module

__Libraries

Status

IMPLEMENTED

Description

Generates deterministic policy lock files that pin the exact policy rules, versions, and evaluation parameters used to produce a verdict. Ensures verdicts can be reproduced identically by capturing the full policy context alongside the CGS hash.

Implementation Details

  • PolicyLockGenerator: src/__Libraries/StellaOps.Verdict/PolicyLockGenerator.cs -- implements IPolicyLockGenerator; GenerateAsync(policyId) creates PolicyLock with SchemaVersion "1.0", auto-generated PolicyVersion from ID + timestamp, rule hashes dict, EngineVersion "1.0.0"; GenerateForVersionAsync(policyId, version) pins specific version; ValidateAsync(policyLock) checks SchemaVersion, PolicyVersion, EngineVersion, non-empty RuleHashes, future timestamp detection (5min tolerance), hash format validation ("sha256:" + 64 hex chars); ComputeRuleHash uses SHA256 of canonical JSON {definition, version} with prefix "sha256:"; uses injected TimeProvider for deterministic timestamps
  • IPolicyLockGenerator: src/__Libraries/StellaOps.Verdict/IPolicyLockGenerator.cs -- interface: GenerateAsync, GenerateForVersionAsync, ValidateAsync
  • PolicyLock: record with SchemaVersion, PolicyVersion, RuleHashes (IReadOnlyDictionary<string, string>), EngineVersion, GeneratedAt
  • PolicyLockValidation: record with IsValid, ErrorMessage, MismatchedRules
  • VerdictBuilderService: src/__Libraries/StellaOps.Verdict/VerdictBuilderService.cs -- integrates with PolicyLockGenerator
  • VerdictServiceCollectionExtensions: src/__Libraries/StellaOps.Verdict/VerdictServiceCollectionExtensions.cs -- DI registration
  • Source: SPRINT_20251229_001_001_BE_cgs_infrastructure.md

E2E Test Plan

  • Verify GenerateAsync creates PolicyLock with non-empty RuleHashes dictionary
  • Test ComputeRuleHash produces deterministic SHA-256 hash in "sha256:{hex}" format
  • Verify ValidateAsync detects missing required fields (SchemaVersion, PolicyVersion, EngineVersion)
  • Test future timestamp detection (GeneratedAt > now + 5 minutes fails validation)
  • Verify ValidateAsync catches invalid hash format (non-hex, wrong length)
  • Test GenerateForVersionAsync pins exact version string in PolicyLock
  • Verify same policy input produces identical PolicyLock (deterministic)
  • Test TimeProvider injection enables deterministic timestamp generation in tests