git.stella-ops.org/docs/scanner-core-contracts.md

Scanner Core Contracts

The Scanner Core library provides shared contracts, observability helpers, and security utilities consumed by Scanner.WebService, Scanner.Worker, analyzers, and tooling. These primitives guarantee deterministic identifiers, timestamps, and log context for all scanning flows.

DTOs

• ScanJob & ScanJobStatus – canonical job metadata (image reference/digest, tenant, correlation ID, timestamps, failure details). Constructors normalise timestamps to UTC microsecond precision and canonicalise image digests. Round-trips with JsonSerializerDefaults.Web using ScannerJsonOptions.
• ScanProgressEvent & ScanStage/ScanProgressEventKind – stage-level progress surface for queue/stream consumers. Includes deterministic sequence numbers, optional progress percentage, attributes, and attached ScannerError.
• ScannerError & ScannerErrorCode – shared error taxonomy spanning queue, analyzers, storage, exporters, and signing. Carries severity, retryability, structured details, and microsecond-precision timestamps.
• ScanJobId – strongly-typed identifier rendered as Guid (lowercase N format) with deterministic parsing.

Deterministic helpers

• ScannerIdentifiers – derives ScanJobId, correlation IDs, and SHA-256 hashes from normalised inputs (image reference/digest, tenant, salt). Ensures case-insensitive stability and reproducible metric keys.
• ScannerTimestamps – trims to microsecond precision, provides ISO-8601 (yyyy-MM-ddTHH:mm:ss.ffffffZ) rendering, and parsing helpers.
• ScannerJsonOptions – standard JSON options (web defaults, camel-case enums) shared by services/tests.

Observability primitives

• ScannerDiagnostics – global ActivitySource/Meter for scanner components. StartActivity seeds deterministic tags (job_id, stage, component, correlation_id).
• ScannerMetricNames – centralises metric prefixes (stellaops.scanner.*) and deterministic job/event tag builders.
• ScannerCorrelationContext & ScannerCorrelationContextAccessor – ambient correlation propagation via AsyncLocal for log scopes, metrics, and diagnostics.
• ScannerLogExtensions – ILogger scopes for jobs/progress events with automatic correlation context push, minimal allocations, and consistent structured fields.

Security utilities

• AuthorityTokenSource – caches short-lived OpToks per audience+scope using deterministic keys and refresh skew (default 30 s). Integrates with StellaOps.Auth.Client.
• DpopProofValidator – validates DPoP proofs (alg allowlist, htm/htu, nonce, replay window, signature) backed by pluggable IDpopReplayCache. Ships with InMemoryDpopReplayCache for restart-only deployments.
• RestartOnlyPluginGuard – enforces restart-time plug-in registration (deterministic path normalisation; throws if new plug-ins added post-seal).
• ServiceCollectionExtensions.AddScannerAuthorityCore – DI helper wiring Authority client, OpTok source, DPoP validation, replay cache, and plug-in guard.

Testing guarantees

Unit tests (StellaOps.Scanner.Core.Tests) assert:

• DTO JSON round-trips are stable and deterministic.
• Identifier/hash helpers ignore case and emit lowercase hex.
• Timestamp normalisation retains UTC semantics.
• Log scopes push/pop correlation context predictably.
• Authority token caching honours refresh skew and invalidation.
• DPoP validator accepts valid proofs, rejects nonce mismatch/replay, and enforces signature validation.
• Restart-only plug-in guard blocks runtime additions post-seal.