git.stella-ops.org/docs/modules/policy/notifications.md

Policy Notification Contract · Risk Profile Lifecycle and Threshold Changes

Purpose

• Provide a stable payload/transport contract for notifying downstream systems when risk profiles are created, updated, activated/deactivated, or when scoring thresholds change.
• Unblocks POLICY-RISK-69-001 by supplying the “notifications contract” referenced in sprint planning.

Event Types

• policy.profile.created — new profile draft created.
• policy.profile.activated — profile version activated for a tenant/scope.
• policy.profile.deactivated — profile version retired or superseded.
• policy.profile.threshold_changed — risk thresholds updated (any level).
• policy.profile.override_added / override_removed — override lifecycle changes.
• policy.profile.simulation_ready — simulation results available for consumption.

Transport

• Primary: Notifications service topic notifications.policy.profiles (tenant-scoped).
• Alt: Webhook delivery using POST with X-Stella-Tenant and HMAC-SHA256 signature header X-Stella-Signature (hex digest over body with shared secret).
• Idempotency: event_id is a UUIDv7; consumers must de-duplicate.

Payload Schema (JSON)

{
  "event_id": "018f9a2e-8f7d-7fbb-9db4-9f9a3d9c4caa",
  "event_type": "policy.profile.threshold_changed",
  "emitted_at": "2025-12-07T12:00:00Z",
  "tenant_id": "tenant-123",
  "profile_id": "risk-profile-core",
  "profile_version": "3.2.0",
  "change_reason": "Updated high/critical thresholds per policy board decision",
  "actor": {
    "type": "user",
    "id": "alice@example.com"
  },
  "thresholds": {
    "info": 0.1,
    "low": 0.25,
    "medium": 0.5,
    "high": 0.75,
    "critical": 0.9
  },
  "effective_scope": {
    "tenants": ["tenant-123"],
    "projects": ["proj-a", "proj-b"],
    "purl_patterns": ["pkg:npm/*"],
    "cpe_patterns": ["cpe:2.3:*:vendor:*:product:*:*:*:*:*:*:*"],
    "tags": ["prod", "pci"]
  },
  "hash": {
    "algorithm": "sha256",
    "value": "b6c1d6c618a01f9fef6db7e6d86e3c57b1a2cc77ce88a7b7d8e8ac4c28e0a1df"
  },
  "links": {
    "profile_url": "https://policy.example.com/api/risk/profiles/risk-profile-core",
    "diff_url": "https://policy.example.com/api/risk/profiles/risk-profile-core/diff?from=3.1.0&to=3.2.0",
    "simulation_url": "https://policy.example.com/api/risk/simulations/results/018f9a2e-8f7d-7fbb-9db4-9f9a3d9c4caa"
  },
  "trace": {
    "trace_id": "4f2d1b7c6a9846a5b9a72f4c3ed1f2c1",
    "span_id": "9c4caa8f7d7fbb9d"
  }
}

Validation Rules

• emitted_at is UTC ISO-8601; ordering is deterministic by (emitted_at, event_id).
• tenant_id is required; projects optional but recommended for multi-project scopes.
• hash.value MUST be the SHA-256 of the serialized risk profile bundle that triggered the event.
• links.* SHOULD point to the canonical Policy Engine endpoints; omit if not reachable in air-gap.
• Webhook delivery MUST include X-Stella-Signature = hex(HMAC_SHA256(shared_secret, raw_body)).

CLI Consumption (sample output)

Example consumption for downstream automation (captured from policy notify tail):

$ stella policy notify tail --topic notifications.policy.profiles --tenant tenant-123 --limit 1
event_id: 018f9a2e-8f7d-7fbb-9db4-9f9a3d9c4caa
event_type: policy.profile.threshold_changed
profile_id: risk-profile-core@3.2.0
thresholds: info=0.10 low=0.25 medium=0.50 high=0.75 critical=0.90
scope.tenants: tenant-123
scope.projects: proj-a, proj-b
hash.sha256: b6c1d6c618a01f9fef6db7e6d86e3c57b1a2cc77ce88a7b7d8e8ac4c28e0a1df
links.profile_url: https://policy.example.com/api/risk/profiles/risk-profile-core

Versioning

• Version 1.0 frozen with this document; additive fields require minor version bump (event_schema_version header optional, default 1.0).
• Breaking changes require new event types or topic.