up

docs/notifications/channels.md

@@ -0,0 +1,51 @@
+# Notification Channels
+
+> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
+
+Last updated: 2025-11-25 (Docs Tasks Md.V · DOCS-NOTIFY-40-001)
+
+## Supported channel types
+- **Slack / Teams**: webhook-based with optional slash-command ack URLs.
+- **Email (SMTP/SMTPS)**: relay-only; secrets provided via `secretRef` in Authority.
+- **Generic webhook**: signed (HMAC-SHA256) payloads with replay protection and allowlisted hosts.
+- **Pager duty-style escalation webhooks**: same contract as generic webhooks but with escalation metadata.
+- **Console in-app**: stored delivery rendered in UI; always enabled for each tenant.
+
+## Channel resource schema (Notify API)
+```json
+{
+  "id": "uuid",
+  "tenant": "string",
+  "type": "slack|teams|email|webhook|pager|console",
+  "endpoint": "https://..." ,
+  "secretRef": "authority://secrets/notify/slack-hook", // optional per type
+  "labels": { "env": "prod", "team": "sre" },
+  "throttle": { "windowSeconds": 60, "max": 10 },
+  "quietHours": { "from": "22:00", "to": "06:00", "timezone": "UTC" },
+  "enabled": true,
+  "createdUtc": "2025-11-25T00:00:00Z"
+}
+```
+- **Determinism**: channel ids are UUIDv5 seeded by `(tenant, type, endpoint)` when created via manifests; server generates new IDs for ad-hoc API calls.
+- **Validation**: endpoints must be on the allowlist; secretRef must exist in Authority; quiet hours use 24h clock UTC.
+
+## Connector rules
+- No secrets are stored in Notify DB; only `secretRef` is persisted.
+- Per-tenant allowlists control outbound hostnames/ports; defaults block public internet in air-gapped kits.
+- Payload signing:
+  - Slack/Teams: bearer secret in URL (indirect via secretRef) plus optional HMAC header `X-Stella-Signature` for mirror validation.
+  - Webhook/Pager: HMAC `X-Stella-Signature` (hex) over body with nonce + timestamp; receivers must enforce 5‑minute skew.
+
+## Offline posture
+- Offline kits ship default channel manifests under `out/offline/notify/channels/*.json` with placeholder endpoints.
+- Operators must replace endpoints and secretRefs before deploy; validation rejects placeholder values.
+
+## Observability
+- Emit `notify.channel.delivery` counter with tags: `channel_type`, `tenant`, `status` (success/fail/throttled/quiet_hours), `rule_id`.
+- Store delivery attempt hashes in the delivery ledger; duplicate payloads are de-duplicated per `(channel, bodyHash)` for 24h.
+
+## Safety checklist
+- [ ] Endpoint on allowlist and TLS valid.
+- [ ] `secretRef` exists in Authority and scoped to tenant.
+- [ ] Quiet hours configured for non-critical alerts; throttles set for bursty rules.
+- [ ] HMAC signing verified in downstream system (webhook/pager).