feat: Implement console session management with tenant and profile handling
- Add ConsoleSessionStore for managing console session state including tenants, profile, and token information. - Create OperatorContextService to manage operator context for orchestrator actions. - Implement OperatorMetadataInterceptor to enrich HTTP requests with operator context metadata. - Develop ConsoleProfileComponent to display user profile and session details, including tenant information and access tokens. - Add corresponding HTML and SCSS for ConsoleProfileComponent to enhance UI presentation. - Write unit tests for ConsoleProfileComponent to ensure correct rendering and functionality.
This commit is contained in:
118
docs/notifications/architecture.md
Normal file
118
docs/notifications/architecture.md
Normal file
@@ -0,0 +1,118 @@
|
||||
# Notifications Architecture
|
||||
|
||||
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
|
||||
|
||||
This dossier distils the Notify architecture into implementation-ready guidance for service owners, SREs, and integrators. It complements the high-level overview by detailing process boundaries, persistence models, and extensibility points.
|
||||
|
||||
---
|
||||
|
||||
## 1. Runtime shape
|
||||
|
||||
```
|
||||
┌──────────────────┐
|
||||
│ Authority (OpTok)│
|
||||
└───────┬──────────┘
|
||||
│
|
||||
┌───────▼──────────┐ ┌───────────────┐
|
||||
│ Notify.WebService│◀──────▶│ MongoDB │
|
||||
Tenant API│ REST + gRPC WIP │ │ rules/channels│
|
||||
└───────▲──────────┘ │ deliveries │
|
||||
│ │ digests │
|
||||
Internal bus │ └───────────────┘
|
||||
(NATS/Redis/etc) │
|
||||
│
|
||||
┌─────────▼─────────┐ ┌───────────────┐
|
||||
│ Notify.Worker │◀────▶│ Redis / Cache │
|
||||
│ rule eval + render│ │ throttles/locks│
|
||||
└─────────▲─────────┘ └───────▲───────┘
|
||||
│ │
|
||||
│ │
|
||||
┌──────┴──────┐ ┌─────────┴────────┐
|
||||
│ Connectors │──────▶│ Slack/Teams/... │
|
||||
│ (plug-ins) │ │ External targets │
|
||||
└─────────────┘ └──────────────────┘
|
||||
```
|
||||
|
||||
- **WebService** hosts REST endpoints (`/channels`, `/rules`, `/templates`, `/deliveries`, `/digests`, `/stats`) and handles schema normalisation, validation, and Authority enforcement.
|
||||
- **Worker** subscribes to the platform event bus, evaluates rules per tenant, applies throttles/digests, renders payloads, writes ledger entries, and invokes connectors.
|
||||
- **Plug-ins** live under `plugins/notify/` and are loaded deterministically at service start (`orderedPlugins` list). Each implements connector contracts and optional health/test-preview providers.
|
||||
|
||||
Both services share options via `notify.yaml` (see `etc/notify.yaml.sample`). For dev/test scenarios, an in-memory repository exists but production requires Mongo + Redis/NATS for durability and coordination.
|
||||
|
||||
---
|
||||
|
||||
## 2. Event ingestion and rule evaluation
|
||||
|
||||
1. **Subscription.** Workers attach to the internal bus (Redis Streams or NATS JetStream). Each partition key is `tenantId|scope.digest|event.kind` to preserve order for a given artefact.
|
||||
2. **Normalisation.** Incoming events are hydrated into `NotifyEvent` envelopes. Payload JSON is normalised (sorted object keys) to preserve determinism and enable hashing.
|
||||
3. **Rule snapshot.** Per-tenant rule sets are cached in memory. Change streams from Mongo trigger snapshot refreshes without restart.
|
||||
4. **Match pipeline.**
|
||||
- Tenant check (`rule.tenantId` vs. event tenant).
|
||||
- Kind/namespace/repository/digest filters.
|
||||
- Severity and KEV gating based on event deltas.
|
||||
- VEX gating using `NotifyRuleMatchVex`.
|
||||
- Action iteration with throttle/digest decisions.
|
||||
5. **Idempotency.** Each action computes `hash(ruleId|actionId|event.kind|scope.digest|delta.hash|dayBucket)`; matches within throttle TTL record `status=Throttled` and stop.
|
||||
6. **Dispatch.** If digest is `instant`, the renderer immediately processes the action. Otherwise the event is appended to the digest window for later flush.
|
||||
|
||||
Failures during evaluation are logged with correlation IDs and surfaced through `/stats` and worker metrics (`notify_rule_eval_failures_total`, `notify_digest_flush_errors_total`).
|
||||
|
||||
---
|
||||
|
||||
## 3. Rendering & connectors
|
||||
|
||||
- **Template resolution.** The renderer picks the template in this order: action template → channel default template → locale fallback → built-in minimal template. Locale negotiation reduces `en-US` to `en-us`.
|
||||
- **Helpers & partials.** Exposed helpers mirror the list in [`notifications/templates.md`](templates.md#3-variables-helpers-and-context). Plug-ins may register additional helpers but must remain deterministic and side-effect free.
|
||||
- **Rendering output.** `NotifyDeliveryRendered` captures:
|
||||
- `channelType`, `format`, `locale`
|
||||
- `title`, `body`, optional `summary`, `textBody`
|
||||
- `target` (redacted where necessary)
|
||||
- `attachments[]` (safe URLs or references)
|
||||
- `bodyHash` (lowercase SHA-256) for audit parity
|
||||
- **Connector contract.** Connectors implement `INotifyConnector` (send + health) and can implement `INotifyChannelTestProvider` for `/channels/{id}/test`. All plugs are single-tenant aware; secrets are pulled via references at send time and never persisted in Mongo.
|
||||
- **Retries.** Workers track attempts with exponential jitter. On permanent failure, deliveries are marked `Failed` with `statusReason`, and optional DLQ fan-out is slated for Sprint 40.
|
||||
|
||||
---
|
||||
|
||||
## 4. Persistence model
|
||||
|
||||
| Collection | Purpose | Key fields & indexes |
|
||||
|------------|---------|----------------------|
|
||||
| `rules` | Tenant rule definitions. | `_id`, `tenantId`, `enabled`; index on `{tenantId, enabled}`. |
|
||||
| `channels` | Channel metadata + config references. | `_id`, `tenantId`, `type`; index on `{tenantId, type}`. |
|
||||
| `templates` | Locale-specific render bodies. | `_id`, `tenantId`, `channelType`, `key`; index on `{tenantId, channelType, key}`. |
|
||||
| `deliveries` | Ledger of rendered notifications. | `_id`, `tenantId`, `sentAt`; compound index on `{tenantId, sentAt:-1}` for history queries. |
|
||||
| `digests` | Open digest windows per action. | `_id` (`tenantId:actionKey:window`), `status`; index on `{tenantId, actionKey}`. |
|
||||
| `throttles` | Short-lived throttle tokens (Mongo or Redis). | Key format `idem:<hash>` with TTL aligned to throttle duration. |
|
||||
|
||||
Documents are stored using the canonical JSON serializer (`NotifyCanonicalJsonSerializer`) to preserve property ordering and casing. Schema migration helpers upgrade stored documents when new versions ship.
|
||||
|
||||
---
|
||||
|
||||
## 5. Deployment & configuration
|
||||
|
||||
- **Configuration sources.** YAML files feed typed options (`NotifyMongoOptions`, `NotifyWorkerOptions`, etc.). Environment variables can override connection strings and rate limits for production.
|
||||
- **Authority integration.** Two OAuth clients (`notify-web`, `notify-web-dev`) with scopes `notify.read` and `notify.admin` are required. Authority enforcement can be disabled for air-gapped dev use by providing `developmentSigningKey`.
|
||||
- **Plug-in management.** `plugins.baseDirectory` and `orderedPlugins` guarantee deterministic loading. Offline Kits copy the plug-in tree verbatim; operations must keep the order aligned across environments.
|
||||
- **Observability.** Workers expose structured logs (`ruleId`, `actionId`, `eventId`, `throttleKey`). Metrics include:
|
||||
- `notify_rule_matches_total{tenant,eventKind}`
|
||||
- `notify_delivery_attempts_total{channelType,status}`
|
||||
- `notify_digest_open_windows{window}`
|
||||
- Optional OpenTelemetry traces for rule evaluation and connector round-trips.
|
||||
- **Scaling levers.** Increase worker replicas to cope with bus throughput; adjust `worker.prefetchCount` for Redis Streams or `ackWait` for NATS JetStream. WebService remains stateless and scales horizontally behind the gateway.
|
||||
|
||||
---
|
||||
|
||||
## 6. Roadmap alignment
|
||||
|
||||
| Backlog | Architectural note |
|
||||
|---------|--------------------|
|
||||
| `NOTIFY-SVC-38-001` | Standardise event envelope publication (idempotency keys) – ensure bus bindings use the documented key format. |
|
||||
| `NOTIFY-SVC-38-002..004` | Introduce simulation endpoints and throttle dashboards – expect additional `/internal/notify/simulate` routes and metrics; update once merged. |
|
||||
| `NOTIFY-SVC-39-001..004` | Correlation engine, digests generator, simulation API, quiet hours – anticipate new Mongo documents (`quietHours`, correlation caches) and connector metadata (quiet mode hints). Review this guide when implementations land. |
|
||||
|
||||
Action: schedule a documentation sync with the Notifications Service Guild immediately after `NOTIFY-SVC-39-001..004` merge to confirm schema adjustments (e.g., correlation edge storage, quiet hour calendars) and add any new persistence or API details here.
|
||||
|
||||
---
|
||||
|
||||
> **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.
|
||||
92
docs/notifications/digests.md
Normal file
92
docs/notifications/digests.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# Notifications Digests
|
||||
|
||||
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
|
||||
|
||||
Digests coalesce multiple matching events into a single notification when rules request batched delivery. They protect responders from alert storms while preserving a deterministic record of every input.
|
||||
|
||||
---
|
||||
|
||||
## 1. Digest lifecycle
|
||||
|
||||
1. **Window selection.** Rule actions opt into a digest cadence by setting `actions[].digest` (`instant`, `5m`, `15m`, `1h`, `1d`). `instant` skips digest logic entirely.
|
||||
2. **Aggregation.** When an event matches, the worker appends it to the open digest window (`tenantId + actionId + window`). Events include the canonical scope, delta counts, and references.
|
||||
3. **Flush.** When the window expires or hits the worker’s safety cap (configurable), the worker renders a digest template and emits a single delivery with status `Digested`.
|
||||
4. **Audit.** The delivery ledger links back to the digest document so operators can inspect individual items and the aggregated summary.
|
||||
|
||||
---
|
||||
|
||||
## 2. Storage model
|
||||
|
||||
Digest state lives in Mongo (`digests` collection) and mirrors the schema described in [ARCHITECTURE_NOTIFY.md](../ARCHITECTURE_NOTIFY.md#7-data-model-mongo):
|
||||
|
||||
```json
|
||||
{
|
||||
"_id": "tenant-dev:act-email-compliance:1h",
|
||||
"tenantId": "tenant-dev",
|
||||
"actionKey": "act-email-compliance",
|
||||
"window": "1h",
|
||||
"openedAt": "2025-10-24T08:00:00Z",
|
||||
"status": "open",
|
||||
"items": [
|
||||
{
|
||||
"eventId": "00000000-0000-0000-0000-000000000001",
|
||||
"scope": {
|
||||
"namespace": "prod-payments",
|
||||
"repo": "ghcr.io/acme/api",
|
||||
"digest": "sha256:…"
|
||||
},
|
||||
"delta": {
|
||||
"newCritical": 1,
|
||||
"kev": 1
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- `status` reflects whether the window is currently collecting (`open`) or has been completed (`closed`). Future revisions may introduce `flushing` for in-progress operations.
|
||||
- `items[].delta` captures aggregated counts for reporting (e.g., new critical findings, KEV, quieted).
|
||||
- Workers use optimistic concurrency on the document ID to avoid duplicate flushes across replicas.
|
||||
|
||||
---
|
||||
|
||||
## 3. Rendering and templates
|
||||
|
||||
- Digest deliveries use the same template engine as instant notifications. Templates receive an additional `digest` object with `window`, `openedAt`, `itemCount`, and `items` (findings grouped by namespace/repository when available).
|
||||
- Provide digest-specific templates (e.g., `tmpl-digest-hourly`) so the body can enumerate top offenders, summarise totals, and link to detailed dashboards.
|
||||
- When no template is specified, Notify falls back to channel defaults that emphasise summary counts and redirect to Console for detail.
|
||||
|
||||
---
|
||||
|
||||
## 4. API surface
|
||||
|
||||
| Endpoint | Description | Notes |
|
||||
|----------|-------------|-------|
|
||||
| `POST /digests` | Issues administrative commands (e.g., force flush, reopen) for a specific action/window. | Request body specifies the command target; requires `notify.admin`. |
|
||||
| `GET /digests/{actionKey}` | Returns the currently open window (if any) for the referenced action. | Supports operators/CLI inspecting pending digests; requires `notify.read`. |
|
||||
| `DELETE /digests/{actionKey}` | Drops the open window without notifying (emergency stop). | Emits an audit record; use sparingly. |
|
||||
|
||||
All routes honour the tenant header and reuse the standard Notify rate limits.
|
||||
|
||||
---
|
||||
|
||||
## 5. Worker behaviour and safety nets
|
||||
|
||||
- **Idempotency.** Flush operations generate a deterministic digest delivery ID (`digest:<tenant>:<actionId>:<window>:<openedAt>`). Retries reuse the same ID.
|
||||
- **Throttles.** Digest generation respects action throttles; setting an aggressive throttle together with a digest window may result in deliberate skips (logged as `Throttled` in the delivery ledger).
|
||||
- **Quiet hours.** Future sprint work (`NOTIFY-SVC-39-004`) integrates quiet-hour calendars. When enabled, flush timers pause during quiet windows and resume afterwards.
|
||||
- **Back-pressure.** When the window reaches the configured item cap before the timer, the worker flushes early and starts a new window immediately.
|
||||
- **Crash resilience.** Workers rebuild in-flight windows from Mongo on startup; partially flushed windows remain closed after success or reopened if the flush fails.
|
||||
|
||||
---
|
||||
|
||||
## 6. Operator guidance
|
||||
|
||||
- Choose hourly digests for high-volume compliance events; daily digests suit executive reporting.
|
||||
- Pair digests with incident-focused instant rules so critical items surface immediately while less urgent noise is summarised.
|
||||
- Monitor `/stats` output for `openDigestCount` to ensure windows are flushing; spikes may indicate downstream connector failures.
|
||||
- When testing new digest templates, open a small (`5m`) window, trigger sample events, then call `POST /digests/{actionId}/flush` to validate rendering before moving to longer cadences.
|
||||
|
||||
---
|
||||
|
||||
> **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.
|
||||
76
docs/notifications/overview.md
Normal file
76
docs/notifications/overview.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# 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`](rules.md) |
|
||||
| Channel catalog | Slack, Teams, Email, Webhook connectors loaded via restart-time plug-ins; metadata stored without secrets. | [`notifications/architecture.md`](architecture.md) |
|
||||
| Templates | Locale-aware, deterministic rendering via safe helpers; channel defaults plus tenant-specific overrides. | [`notifications/templates.md`](templates.md) |
|
||||
| Digests | Coalesce bursts into periodic summaries with deterministic IDs and audit trails. | [`notifications/digests.md`](digests.md) |
|
||||
| Delivery ledger | Tracks rendered payload hashes, attempts, throttles, and outcomes for every action. | [`ARCHITECTURE_NOTIFY.md`](../ARCHITECTURE_NOTIFY.md#7-data-model-mongo) |
|
||||
|
||||
---
|
||||
|
||||
## 3. How it fits into Stella Ops
|
||||
|
||||
1. **Producers emit events.** Scanner, Scheduler, VEX Lens, Attestor, and Zastava publish canonical envelopes (`NotifyEvent`) onto the internal bus.
|
||||
2. **Notify.Worker evaluates rules.** For each tenant, the worker applies match filters, VEX gates, throttles, and digest policies before rendering the action.
|
||||
3. **Connectors deliver.** Channel plug-ins send the rendered payload to Slack/Teams/Email/Webhook targets and report back attempts and outcomes.
|
||||
4. **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.read` and `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 | [`ARCHITECTURE_NOTIFY.md`](../ARCHITECTURE_NOTIFY.md#1-runtime-shape--projects) |
|
||||
| 2 | Register OAuth clients/scopes in Authority | [`etc/authority.yaml.sample`](../etc/authority.yaml.sample) |
|
||||
| 3 | Install channel plug-ins and capture secret references | [`plugins/notify`](../../plugins) |
|
||||
| 4 | Create a tenant rule and test preview | [`POST /channels/{id}/test`](../ARCHITECTURE_NOTIFY.md#8-external-apis-webservice) |
|
||||
| 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.
|
||||
62
docs/notifications/pack-approvals-integration.md
Normal file
62
docs/notifications/pack-approvals-integration.md
Normal file
@@ -0,0 +1,62 @@
|
||||
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
|
||||
|
||||
# Pack Approval Notification Integration — Requirements
|
||||
|
||||
## Overview
|
||||
|
||||
Task Runner now produces pack plans with explicit approval and policy-gate metadata. The Notifications service must ingest those events, persist their state, and fan out actionable alerts (approvals requested, policy holds, resumptions). This document captures the requirements for the first Notifications sprint dedicated to the Task Runner bridge.
|
||||
|
||||
Deliverables feed Sprint 37 tasks (`NOTIFY-SVC-37-00x`) and unblock Task Runner sprint 43 (`TASKRUN-43-001`).
|
||||
|
||||
## Functional Requirements
|
||||
|
||||
### 1. Approval Event Contract
|
||||
- Define a canonical schema for **PackApprovalRequested** and **PackApprovalUpdated** events.
|
||||
- Fields must include `runId`, `approvalId`, tenant context, plan hash, required grants, step identifiers, message template, and resume callback metadata.
|
||||
- Provide an OpenAPI fragment and x-go/x-cs models for Task Runner and CLI compatibility.
|
||||
- Document error/acknowledgement semantics (success, retryable failure, validation failure).
|
||||
|
||||
### 2. Ingestion & Persistence
|
||||
- Expose a secure Notifications API endpoint (`POST /notifications/pack-approvals`) receiving Task Runner events.
|
||||
- Validate scope (`Packs.Approve`, `Notifier.Events:Write`) and tenant match.
|
||||
- Persist approval state transitions in Mongo (`notifications.pack_approvals`) with indexes on run/approval/tenant.
|
||||
- Store outbound notification audit records with correlation IDs to support Task Runner resume flow.
|
||||
|
||||
### 3. Notification Routing
|
||||
- Derive recipients from new rule predicates (`event.kind == "pack.approval"`).
|
||||
- Render approval templates (email + webhook JSON) including plan metadata and approval links (resume token).
|
||||
- Emit policy gate notifications as “hold” incidents with context (parameters, messages).
|
||||
- Support localization fallback and redaction of secrets (never ship approval tokens unencrypted).
|
||||
|
||||
### 4. Resume & Ack Handshake
|
||||
- Provide an approval ack endpoint (`POST /notifications/pack-approvals/{runId}/{approvalId}/ack`) that records decision metadata and forwards to Task Runner resume hook (HTTP callback + message bus placeholder).
|
||||
- Return structured responses with resume token / status for CLI integration.
|
||||
- Ensure idempotent updates (dedupe by runId + approvalId + decisionHash).
|
||||
|
||||
### 5. Observability & Security
|
||||
- Emit metrics for approval notifications queued/sent, outstanding approvals, and acknowledgement latency.
|
||||
- Log audit trail events (`pack.approval.requested`, `pack.approval.acknowledged`, `pack.policy.hold`).
|
||||
- Enforce HMAC or mTLS for Task Runner -> Notifier ingestion; support configurable IP allowlist.
|
||||
- Provide chaos-test plan for notification failure modes (channel outage, storage failure).
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
- Deterministic processing: identical approval events lead to identical outbound notifications (idempotent).
|
||||
- Timeouts: ingestion endpoint must respond < 500 ms under nominal load.
|
||||
- Retry strategy: Task Runner expects 5xx/429 for transient errors; document backoff guidance.
|
||||
- Data retention: approval records retained 90 days, purge job tracked under ops runbook.
|
||||
|
||||
## Sprint 37 Task Mapping
|
||||
|
||||
| Task ID | Scope |
|
||||
| --- | --- |
|
||||
| **NOTIFY-SVC-37-001** | Author this contract doc, OpenAPI fragment, and schema references. Coordinate with Task Runner/Authority guilds. |
|
||||
| **NOTIFY-SVC-37-002** | Implement secure ingestion endpoint, Mongo persistence, and audit hooks. Provide integration tests with sample events. |
|
||||
| **NOTIFY-SVC-37-003** | Build approval/policy notification templates, routing rules, and channel dispatch (email + webhook). |
|
||||
| **NOTIFY-SVC-37-004** | Ship acknowledgement endpoint + Task Runner callback client, resume token handling, and metrics/dashboards. |
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. Who owns approval resume callback (Task Runner Worker vs Orchestrator)? Resolve before NOTIFY-SVC-37-004.
|
||||
2. Should approvals generate incidents in existing incident schema or dedicated collection? Decision impacts Mongo design.
|
||||
3. Authority scopes for approval ingestion/ack — reuse `Packs.Approve` or introduce `Packs.Approve:notify`? Coordinate with Authority team.
|
||||
147
docs/notifications/rules.md
Normal file
147
docs/notifications/rules.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# Notifications Rules
|
||||
|
||||
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
|
||||
|
||||
Rules decide which platform events deserve a notification, how aggressively they should be throttled, and which channels/actions should run. They are tenant-scoped contracts that guarantee deterministic routing across Notify.Worker replicas.
|
||||
|
||||
---
|
||||
|
||||
## 1. Rule lifecycle
|
||||
|
||||
1. **Authoring.** Operators create or update rules through the Notify WebService (`POST /rules`, `PATCH /rules/{id}`) or UI. Payloads are normalised to the current `NotifyRule` schema version.
|
||||
2. **Evaluation.** Notify.Worker evaluates enabled rules per incoming event. Tenancy is enforced first, followed by match filters, VEX gates, throttles, and digest handling.
|
||||
3. **Delivery.** Matching actions are enqueued with an idempotency key to prevent storm loops. Throttle rejections and digest coalescing are recorded in the delivery ledger.
|
||||
4. **Audit.** Every change carries `createdBy`/`updatedBy` plus timestamps; the delivery ledger references `ruleId`/`actionId` for traceability.
|
||||
|
||||
---
|
||||
|
||||
## 2. Rule schema reference
|
||||
|
||||
| Field | Type | Notes |
|
||||
|-------|------|-------|
|
||||
| `ruleId` | string | Stable identifier; clients may provide UUID/slug. |
|
||||
| `tenantId` | string | Must match the tenant header supplied when the rule is created. |
|
||||
| `name` | string | Display label shown in UI and audits. |
|
||||
| `description` | string? | Optional operator-facing note. |
|
||||
| `enabled` | bool | Disabled rules remain stored but skipped during evaluation. |
|
||||
| `labels` | map<string,string> | Sorted, trimmed key/value tags supporting filtering. |
|
||||
| `metadata` | map<string,string> | Reserved for automation; stored verbatim (sorted). |
|
||||
| `match` | [`NotifyRuleMatch`](#3-match-filters) | Declarative filters applied before actions execute. |
|
||||
| `actions[]` | [`NotifyRuleAction`](#4-actions-throttles-and-digests) | Ordered set of channel dispatchers; minimum one. |
|
||||
| `createdBy`/`createdAt` | string?, instant | Populated automatically when omitted. |
|
||||
| `updatedBy`/`updatedAt` | string?, instant | Defaults to creation values when unspecified. |
|
||||
| `schemaVersion` | string | Auto-upgraded during persistence; use for migrations. |
|
||||
|
||||
Rules are immutable snapshots; updates produce a full document write so workers observing change streams can refresh caches deterministically.
|
||||
|
||||
---
|
||||
|
||||
## 3. Match filters
|
||||
|
||||
`NotifyRuleMatch` narrows which events trigger the rule. All string collections are trimmed, deduplicated, and sorted to guarantee deterministic evaluation.
|
||||
|
||||
| Field | Type | Behaviour |
|
||||
|-------|------|-----------|
|
||||
| `eventKinds[]` | string | Lower-cased; supports any canonical Notify event (`scanner.report.ready`, `scheduler.rescan.delta`, `zastava.admission`, etc.). Empty list matches all kinds. |
|
||||
| `namespaces[]` | string | Exact match against `event.scope.namespace`. Supports glob-style filters via upstream enrichment (planned). |
|
||||
| `repositories[]` | string | Matches `event.scope.repo`. |
|
||||
| `digests[]` | string | Lower-cased; matches `event.scope.digest`. |
|
||||
| `labels[]` | string | Matches event attributes or delta labels (`kev`, `critical`, `license`, …). |
|
||||
| `componentPurls[]` | string | Matches component identifiers inside the event payload when provided. |
|
||||
| `minSeverity` | string? | Lower-cased severity gate (e.g., `medium`, `high`, `critical`). Evaluated on new findings inside event deltas; events lacking severity bypass this gate unless set. |
|
||||
| `verdicts[]` | string | Accepts scan/report verdicts (`fail`, `warn`, `block`, `escalate`, `deny`). |
|
||||
| `kevOnly` | bool? | When `true`, only KEV-tagged findings fire. |
|
||||
| `vex` | object | Additional gating aligned with VEX consensus; see below. |
|
||||
|
||||
### 3.1 VEX gates
|
||||
|
||||
`NotifyRuleMatchVex` offers fine-grained control when VEX findings accompany events:
|
||||
|
||||
| Field | Default | Effect |
|
||||
|-------|---------|--------|
|
||||
| `includeAcceptedJustifications` | `true` | Include findings marked `not_affected`/`acceptable` in consensus. |
|
||||
| `includeRejectedJustifications` | `false` | Surface findings the consensus rejected. |
|
||||
| `includeUnknownJustifications` | `false` | Allow findings without explicit justification. |
|
||||
| `justificationKinds[]` | `[]` | Optional allow-list of justification codes (e.g., `exploit_observed`, `component_not_present`). |
|
||||
|
||||
If the VEX block filters out every applicable finding, the rule is treated as a non-match and no actions run.
|
||||
|
||||
---
|
||||
|
||||
## 4. Actions, throttles, and digests
|
||||
|
||||
Each rule requires at least one action. Actions are deduplicated and sorted by `actionId`, so prefer deterministic identifiers.
|
||||
|
||||
| Field | Type | Notes |
|
||||
|-------|------|-------|
|
||||
| `actionId` | string | Stable identifier unique within the rule. |
|
||||
| `channel` | string | Reference to a channel (`channelId`) configured in `/channels`. |
|
||||
| `template` | string? | Template key to use for rendering; falls back to channel default when omitted. |
|
||||
| `digest` | string? | Digest window key (`instant`, `5m`, `15m`, `1h`, `1d`). `instant` bypasses coalescing. |
|
||||
| `throttle` | ISO8601 duration? | Optional throttle TTL (`PT300S`, `PT1H`). Prevents duplicate deliveries when the same idempotency hash appears before expiry. |
|
||||
| `locale` | string? | BCP-47 tag (stored lower-case). Template lookup falls back to channel locale then `en-us`. |
|
||||
| `enabled` | bool | Disabled actions skip rendering but remain stored. |
|
||||
| `metadata` | map<string,string> | Connector-specific hints (priority, layout, etc.). |
|
||||
|
||||
### 4.1 Evaluation order
|
||||
|
||||
1. Verify channel exists and is enabled; disabled channels mark the delivery as `Dropped`.
|
||||
2. Apply throttle idempotency key: `hash(ruleId|actionId|event.kind|scope.digest|delta.hash|dayBucket)`. Hits are logged as `Throttled`.
|
||||
3. If the action defines a digest window other than `instant`, append the event to the open window and defer delivery until flush.
|
||||
4. When delivery proceeds, the renderer resolves the template, locale, and metadata before invoking the connector.
|
||||
|
||||
---
|
||||
|
||||
## 5. Example rule payload
|
||||
|
||||
```json
|
||||
{
|
||||
"ruleId": "rule-critical-soc",
|
||||
"tenantId": "tenant-dev",
|
||||
"name": "Critical scanner verdicts",
|
||||
"description": "Route KEV-tagged critical findings to SOC Slack with zero delay.",
|
||||
"enabled": true,
|
||||
"match": {
|
||||
"eventKinds": ["scanner.report.ready"],
|
||||
"labels": ["kev", "critical"],
|
||||
"minSeverity": "critical",
|
||||
"verdicts": ["fail", "block"],
|
||||
"kevOnly": true
|
||||
},
|
||||
"actions": [
|
||||
{
|
||||
"actionId": "act-slack-critical",
|
||||
"channel": "chn-slack-soc",
|
||||
"template": "tmpl-critical",
|
||||
"digest": "instant",
|
||||
"throttle": "PT300S",
|
||||
"locale": "en-us",
|
||||
"metadata": {
|
||||
"priority": "p1"
|
||||
}
|
||||
}
|
||||
],
|
||||
"labels": {
|
||||
"owner": "soc"
|
||||
},
|
||||
"metadata": {
|
||||
"revision": "12"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Dry-run calls (`POST /rules/{id}/test`) accept the same structure along with a sample Notify event payload to exercise match logic without invoking connectors.
|
||||
|
||||
---
|
||||
|
||||
## 6. Operational guidance
|
||||
|
||||
- Keep rule scopes narrow (namespace/repository) before relying on severity gates; this minimises noise and improves digest summarisation.
|
||||
- Always configure a throttle window for instant actions to protect against repeated upstream retries.
|
||||
- Use rule labels to organise dashboards and access control (e.g., `owner:soc`, `env:prod`).
|
||||
- Prefer tenant-specific rule IDs so Offline Kit exports remain deterministic across environments.
|
||||
- If a rule depends on derived metadata (e.g., policy verdict tags), list those dependencies in the rule description for audit readiness.
|
||||
|
||||
---
|
||||
|
||||
> **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.
|
||||
130
docs/notifications/templates.md
Normal file
130
docs/notifications/templates.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# Notifications Templates
|
||||
|
||||
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
|
||||
|
||||
Templates shape the payload rendered for each channel when a rule action fires. They are deterministic, locale-aware artefacts stored alongside rules so Notify.Worker replicas can render identical messages regardless of environment.
|
||||
|
||||
---
|
||||
|
||||
## 1. Template lifecycle
|
||||
|
||||
1. **Authoring.** Operators create templates via the API (`POST /templates`) or UI. Each template binds to a channel type (`Slack`, `Teams`, `Email`, `Webhook`, `Custom`) and a locale.
|
||||
2. **Reference.** Rule actions opt in by referencing the template key (`actions[].template`). Channel defaults apply when no template is specified.
|
||||
3. **Rendering.** During delivery, the worker resolves the template (locale fallbacks included), executes it using the safe Handlebars-style engine, and passes the rendered payload plus metadata to the connector.
|
||||
4. **Audit.** Rendered payloads stored in the delivery ledger include the `templateId` so operators can trace which text was used.
|
||||
|
||||
---
|
||||
|
||||
## 2. Template schema reference
|
||||
|
||||
| Field | Type | Notes |
|
||||
|-------|------|-------|
|
||||
| `templateId` | string | Stable identifier (UUID/slug). |
|
||||
| `tenantId` | string | Must match the tenant header in API calls. |
|
||||
| `channelType` | [`NotifyChannelType`](../ARCHITECTURE_NOTIFY.md#5-channels--connectors-plug-ins) | Determines connector payload envelope. |
|
||||
| `key` | string | Human-readable key referenced by rules (`tmpl-critical`). |
|
||||
| `locale` | string | BCP-47 tag, stored lower-case (`en-us`, `bg-bg`). |
|
||||
| `body` | string | Template body; rendered strictly without executing arbitrary code. |
|
||||
| `renderMode` | enum | `Markdown`, `Html`, `AdaptiveCard`, `PlainText`, or `Json`. Guides connector sanitisation. |
|
||||
| `format` | enum | `Slack`, `Teams`, `Email`, `Webhook`, or `Json`. Signals delivery payload structure. |
|
||||
| `description` | string? | Optional operator note. |
|
||||
| `metadata` | map<string,string> | Sorted map for automation (layout hints, fallback text). |
|
||||
| `createdBy`/`createdAt` | string?, instant | Auto-populated. |
|
||||
| `updatedBy`/`updatedAt` | string?, instant | Auto-populated. |
|
||||
| `schemaVersion` | string | Auto-upgraded on persistence. |
|
||||
|
||||
Templates are normalised: string fields trimmed, locale lower-cased, metadata sorted to preserve determinism.
|
||||
|
||||
---
|
||||
|
||||
## 3. Variables, helpers, and context
|
||||
|
||||
Templates receive a structured context derived from the Notify event, rule match, and rendering metadata.
|
||||
|
||||
| Path | Description |
|
||||
|------|-------------|
|
||||
| `event.*` | Canonical event envelope (`kind`, `tenant`, `ts`, `actor`). |
|
||||
| `event.scope.*` | Namespace, repository, digest, image, component identifiers, labels, attributes. |
|
||||
| `payload.*` | Raw event payload (e.g., `payload.verdict`, `payload.delta.*`, `payload.links.*`). |
|
||||
| `rule.*` | Rule descriptor (`ruleId`, `name`, `labels`, `metadata`). |
|
||||
| `action.*` | Action descriptor (`actionId`, `channel`, `digest`, `throttle`, `metadata`). |
|
||||
| `policy.*` | Policy metadata when supplied (`revisionId`, `name`). |
|
||||
| `topFindings[]` | Top-N findings summarised for convenience (vulnerability ID, severity, reachability). |
|
||||
| `digest.*` | When rendering digest flushes: `window`, `openedAt`, `itemCount`. |
|
||||
|
||||
Built-in helpers mirror the architecture dossier:
|
||||
|
||||
| Helper | Usage |
|
||||
|--------|-------|
|
||||
| `severity_icon severity` | Returns emoji/text badge representing severity. |
|
||||
| `link text url` | Produces channel-safe hyperlink. |
|
||||
| `pluralize count "finding"` | Adds plural suffix when `count != 1`. |
|
||||
| `truncate text maxLength` | Cuts strings while preserving determinism. |
|
||||
| `code text` | Formats inline code (Markdown/HTML aware). |
|
||||
|
||||
Connectors may expose additional helpers via partials, but must remain deterministic and side-effect free.
|
||||
|
||||
---
|
||||
|
||||
## 4. Sample templates
|
||||
|
||||
### 4.1 Slack (Markdown + block kit)
|
||||
|
||||
```hbs
|
||||
{{#*inline "findingLine"}}
|
||||
- {{severity_icon severity}} {{vulnId}} ({{severity}}) in `{{component}}`
|
||||
{{/inline}}
|
||||
|
||||
*:rotating_light: {{payload.summary.total}} findings {{#if payload.delta.newCritical}}(new critical: {{payload.delta.newCritical}}){{/if}}*
|
||||
|
||||
{{#if topFindings.length}}
|
||||
Top findings:
|
||||
{{#each topFindings}}{{> findingLine}}{{/each}}
|
||||
{{/if}}
|
||||
|
||||
{{link "Open report in Console" payload.links.ui}}
|
||||
```
|
||||
|
||||
### 4.2 Email (HTML + text alternative)
|
||||
|
||||
```hbs
|
||||
<h2>{{payload.verdict}} for {{event.scope.repo}}</h2>
|
||||
<p>{{payload.summary.total}} findings ({{payload.summary.blocked}} blocked, {{payload.summary.warned}} warned)</p>
|
||||
<table>
|
||||
<thead><tr><th>Finding</th><th>Severity</th><th>Package</th></tr></thead>
|
||||
<tbody>
|
||||
{{#each topFindings}}
|
||||
<tr>
|
||||
<td>{{this.vulnId}}</td>
|
||||
<td>{{this.severity}}</td>
|
||||
<td>{{this.component}}</td>
|
||||
</tr>
|
||||
{{/each}}
|
||||
</tbody>
|
||||
</table>
|
||||
<p>{{link "View full analysis" payload.links.ui}}</p>
|
||||
```
|
||||
|
||||
When delivering via email, connectors automatically attach a plain-text alternative derived from the rendered content to preserve accessibility.
|
||||
|
||||
---
|
||||
|
||||
## 5. Preview and validation
|
||||
|
||||
- `POST /channels/{id}/test` accepts an optional `templateId` and sample payload to produce a rendered preview without dispatching the event. Results include channel type, target, title/summary, locale, body hash, and connector metadata.
|
||||
- UI previews rely on the same API and highlight connector fallbacks (e.g., Teams adaptive card vs. text fallback).
|
||||
- Offline Kit scenarios can call `/internal/notify/templates/normalize` to ensure bundled templates match the canonical schema before packaging.
|
||||
|
||||
---
|
||||
|
||||
## 6. Best practices
|
||||
|
||||
- Keep channel-specific limits in mind (Slack block/character quotas, Teams adaptive card size, email line length). Lean on digests to summarise long lists.
|
||||
- Provide locale-specific versions for high-volume tenants; Notify selects the closest locale, falling back to `en-us`.
|
||||
- Store connector-specific hints (`metadata.layout`, `metadata.emoji`) in template metadata rather than rules when they affect rendering.
|
||||
- Version template bodies through metadata (e.g., `metadata.revision: "2025-10-28"`) so tenants can track changes over time.
|
||||
- Run test previews whenever introducing new helpers to confirm body hashes remain stable across environments.
|
||||
|
||||
---
|
||||
|
||||
> **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.
|
||||
Reference in New Issue
Block a user