f98cea3bcf
- Introduced AuthorityAdvisoryAiOptions and related classes for managing advisory AI configurations, including remote inference options and tenant-specific settings. - Added AuthorityApiLifecycleOptions to control API lifecycle settings, including legacy OAuth endpoint configurations. - Implemented validation and normalization methods for both advisory AI and API lifecycle options to ensure proper configuration. - Created AuthorityNotificationsOptions and its related classes for managing notification settings, including ack tokens, webhooks, and escalation options. - Developed IssuerDirectoryClient and related models for interacting with the issuer directory service, including caching mechanisms and HTTP client configurations. - Added support for dependency injection through ServiceCollectionExtensions for the Issuer Directory Client. - Updated project file to include necessary package references for the new Issuer Directory Client library.
5.6 KiB
5.6 KiB
Notifications Overview
Imposed rule: Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
Notifications Studio turns raw platform events into concise, tenant-scoped alerts that reach the right responders without overwhelming them. The service is sovereign/offline-first, follows the Aggregation-Only Contract (AOC), and produces deterministic outputs so the same configuration yields identical deliveries across environments.
1. Mission & value
- Reduce noise. Only materially new or high-impact changes reach chat, email, or webhooks thanks to rule filters, throttles, and digest windows.
- Explainable results. Every delivery is traceable back to a rule, action, and event payload stored in the delivery ledger; operators can audit what fired and why.
- Safe by default. Secrets remain in external stores, templates are sandboxed, quiet hours and throttles prevent storms, and idempotency guarantees protect downstream systems.
- Offline-aligned. All configuration, templates, and plug-ins ship with Offline Kits; no external SaaS is required to send notifications.
2. Core capabilities
| Capability | What it does | Key docs |
|---|---|---|
| Rules engine | Declarative matchers for event kinds, severities, namespaces, VEX context, KEV flags, and more. | notifications/rules.md |
| Channel catalog | Slack, Teams, Email, Webhook connectors loaded via restart-time plug-ins; metadata stored without secrets. | notifications/architecture.md |
| Templates | Locale-aware, deterministic rendering via safe helpers; channel defaults plus tenant-specific overrides. | notifications/templates.md |
| Digests | Coalesce bursts into periodic summaries with deterministic IDs and audit trails. | notifications/digests.md |
| Delivery ledger | Tracks rendered payload hashes, attempts, throttles, and outcomes for every action. | modules/notify/architecture.md |
| Ack tokens | DSSE-signed acknowledgement tokens with webhook allowlists and escalation guardrails enforced by Authority. | modules/notify/architecture.md |
3. How it fits into Stella Ops
- Producers emit events. Scanner, Scheduler, VEX Lens, Attestor, and Zastava publish canonical envelopes (
NotifyEvent) onto the internal bus. - Notify.Worker evaluates rules. For each tenant, the worker applies match filters, VEX gates, throttles, and digest policies before rendering the action.
- Connectors deliver. Channel plug-ins send the rendered payload to Slack/Teams/Email/Webhook targets and report back attempts and outcomes.
- Consumers investigate. Operators pivot from message links into Console dashboards, SBOM views, or policy overlays with correlation IDs preserved.
The Notify WebService fronts worker state with REST APIs used by the UI and CLI. Tenants authenticate via StellaOps Authority scopes notify.viewer, notify.operator, and (for escalated actions) notify.admin. All operations require the tenant header (X-StellaOps-Tenant) to preserve sovereignty boundaries.
4. Operating model
| Area | Guidance |
|---|---|
| Tenancy | Each rule, channel, template, and delivery belongs to exactly one tenant. Cross-tenant sharing is intentionally unsupported. |
| Determinism | Configuration persistence normalises strings and sorts collections. Template rendering produces identical bodyHash values when inputs match. |
| Scaling | Workers scale horizontally; per-tenant rule snapshots are cached and refreshed from Mongo change streams. Redis (or equivalent) guards throttles and locks. |
| Offline | Offline Kits include plug-ins, default templates, and seed rules. Operators can edit YAML/JSON manifests before air-gapped deployment. |
| Security | Channel secrets use indirection (secretRef), Authority-protected OAuth clients secure API access, and delivery payloads are redacted before storage where required. |
5. Getting started (first 30 minutes)
| Step | Goal | Reference |
|---|---|---|
| 1 | Deploy Notify WebService + Worker with Mongo and Redis | modules/notify/architecture.md |
| 2 | Register OAuth clients/scopes in Authority | etc/authority.yaml.sample |
| 3 | Install channel plug-ins and capture secret references | plugins/notify |
| 4 | Create a tenant rule and test preview | POST /channels/{id}/test |
| 5 | Inspect deliveries and digests | /api/v1/notify/deliveries, /api/v1/notify/digests |
6. Alignment with implementation work
| Backlog item | Impact on docs | Status |
|---|---|---|
NOTIFY-SVC-38-001..004 |
Foundational correlation, throttling, simulation hooks. | In progress – align behaviour once services publish beta APIs. |
NOTIFY-SVC-39-001..004 |
Adds correlation engine, digest generator, simulation API, quiet hours. | Pending – revisit rule/digest sections when these tasks merge. |
Action: coordinate with the Notifications Service Guild when NOTIFY-SVC-39-001..004 land to validate payload fields, quiet-hours semantics, and any new connector metadata that should be documented here and in the channel-specific guides.
Imposed rule reminder: Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.