600f3a7a3c
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
Console CI / console-ci (push) Has been cancelled
Export Center CI / export-ci (push) Has been cancelled
- Added graph.inspect.v1 documentation outlining payload structure and determinism rules. - Created JSON schema for graph.inspect.v1 to enforce payload validation. - Defined mapping rules for graph relationships, advisories, and VEX statements. feat(notifications): establish remediation blueprint for gaps NR1-NR10 - Documented requirements, evidence, and tests for Notifier runtime. - Specified deliverables and next steps for addressing identified gaps. docs(notifications): organize operations and schemas documentation - Created README files for operations, schemas, and security notes to clarify deliverables and policies. feat(advisory): implement PostgreSQL caching for Link-Not-Merge linksets - Created database schema for advisory linkset cache. - Developed repository for managing advisory linkset cache operations. - Added tests to ensure correct functionality of the AdvisoryLinksetCacheRepository.
6.1 KiB
6.1 KiB
Notify Gaps NR1–NR10 — Remediation Blueprint (source: docs/product-advisories/31-Nov-2025 FINDINGS.md)
Scope
Close NR1–NR10 by defining contracts, evidence, and deterministic test hooks for the Notifier runtime (service + worker + offline kit). This doc is the detailed layer referenced by sprint SPRINT_0171_0001_0001_notifier_i and NOTIFY-GAPS-171-014.
Gap requirements, evidence, and tests
| ID | Requirement | Evidence to publish | Deterministic tests/fixtures |
|---|---|---|---|
| NR1 | Versioned JSON Schemas for event envelopes, rules, templates, channels, receipts, and webhooks; DSSE-signed catalog with canonical hash recipe (BLAKE3-256 over normalized JSON). | docs/notifications/schemas/notify-schemas-catalog.json + .dsse.json; docs/notifications/schemas/inputs.lock capturing digests and canonicalization flags. |
Golden canonicalization harness under tests/notifications/Schemas/SchemaCanonicalizationTests.cs using frozen inputs + hash assertions. |
| NR2 | Tenant scoping + approvals for high-impact rules (escalations, PII, cross-tenant fan-out). Every API and receipt carries tenant_id; RBAC/approvals enforced. |
RBAC/approval matrix (docs/notifications/security/tenant-approvals.md) listing actions × roles × required approvals. |
API contract tests in StellaOps.Notifier.Tests/TenantScopeTests.cs plus integration fixtures with mixed-tenant payloads (should reject). |
| NR3 | Deterministic rendering/localization: stable merge-field ordering, UTC ISO-8601 timestamps, locale whitelist, hashed previews recorded in ledger. | Rendering fixture pack docs/notifications/fixtures/rendering/*.json; hash ledger samples docs/notifications/fixtures/rendering/index.ndjson with BLAKE3 digests. |
StellaOps.Notifier.Tests/RenderingDeterminismTests.cs compares golden bodies/subjects across locales/timezones; seeds fixed RNG/time. |
| NR4 | Quotas/backpressure/DLQ: per-tenant/channel quotas, burst budgets, enqueue gating, DLQ schema with redrive + idempotent keys; metrics/alerts for backlog/DLQ growth. | Quota policy docs/notifications/operations/quotas.md; DLQ schema docs/notifications/schemas/dlq-notify.schema.json. |
Worker tests StellaOps.Notifier.Tests/BackpressureAndDlqTests.cs validating quota enforcement, DLQ insertion, redrive idempotency. |
| NR5 | Retry & idempotency: canonical delivery_id (UUIDv7) + dedupe key (event×rule×channel); bounded exponential backoff with jitter; idempotent connectors; ignore out-of-order acks. |
Retry matrix docs/notifications/operations/retries.md; connector idempotency checklist. |
StellaOps.Notifier.Tests/RetryPolicyTests.cs + connector harness fixtures demonstrating dedupe across duplicate events. |
| NR6 | Webhook/ack security: HMAC or mTLS/DPoP required; signed ack URLs/tokens with nonce, expiry, audience, single-use; per-tenant allowlists for domains/paths. | Security policy docs/notifications/security/webhook-ack-hardening.md; sample signed-ack token format + validation steps. |
Negative-path tests StellaOps.Notifier.Tests/WebhookSecurityTests.cs covering wrong HMAC, replayed nonce, expired token, disallowed domain. |
| NR7 | Redaction & PII limits: classify template fields; redact secrets/PII in storage/logs; hash sensitive values; size/field allowlists; previews/logs default to redacted variant. | Redaction catalog docs/notifications/security/redaction-catalog.md; sample redacted payloads docs/notifications/fixtures/redaction/*.json. |
StellaOps.Notifier.Tests/RedactionTests.cs asserting stored/preview payloads match redacted expectations. |
| NR8 | Observability SLO alerts: SLOs for delivery latency/success/backlog/DLQ age; standard metrics names; dashboards/alerts/runbooks; traces include tenant/rule/channel IDs with sampling rules. | Dashboard JSON docs/notifications/operations/dashboards/notify-slo.json; alert rules docs/notifications/operations/alerts/notify-slo-alerts.yaml; runbook link. |
StellaOps.Notifier.Tests/ObservabilityContractsTests.cs verifying metric names/labels; trace exemplar fixture docs/notifications/fixtures/traces/sample-trace.json. |
| NR9 | Offline notify-kit with DSSE: bundle schemas, rules/templates, connector configs, verify script, hash list, time-anchor hook; deterministic packaging flags; tenant/env scoping; DSSE-signed manifest. | Manifest offline/notifier/notify-kit.manifest.json, DSSE offline/notifier/notify-kit.manifest.dsse.json, hash list offline/notifier/artifact-hashes.json, verify script offline/notifier/verify_notify_kit.sh. |
Determinism check tests/offline/NotifyKitDeterminismTests.sh (shell) verifying hash list, DSSE, scope enforcement, packaging flags. |
| NR10 | Mandatory simulations & evidence before activation: dry-run against frozen fixtures; DSSE-signed simulation results attached to approvals; regression tests per high-impact rule/template change. | Simulation report docs/notifications/simulations/<rule-id>-report.json + DSSE; approval evidence log docs/notifications/simulations/index.ndjson. |
StellaOps.Notifier.Tests/SimulationGateTests.cs enforcing simulation requirement and evidence linkage before active=true. |
Delivery + governance hooks
- Add the above evidence paths to the NOTIFY-GAPS-171-014 task in
docs/implplan/SPRINT_0171_0001_0001_notifier_i.mdand mirror status insrc/Notifier/StellaOps.Notifier/TASKS.md. - When artifacts land, append TRX/fixture links in the sprint Execution Log and reference this doc under Decisions & Risks.
- Offline kit artefacts must mirror mirror/offline packaging rules (deterministic flags, time-anchor hook, PQ dual-sign toggle) already used by Mirror/Offline sprints.
Next steps
- Generate initial schema catalog (
notify-schemas-catalog.json) with rule/template/channel/webhook/receipt definitions and run canonicalization harness. - Produce redaction catalog, quotas policy, retry matrix, and security hardening docs referenced above.
- Add golden fixtures/tests outlined above and wire CI filters to run determinism + security suites for Notify.
- Build notify-kit manifest + DSSE and publish
verify_notify_kit.shaligned with offline bundle policies.