up

docs/security/aoc-invariants.md

@@ -0,0 +1,29 @@
+# Aggregation-Only Contract (AOC) Invariants
+
+Last updated: 2025-11-25 (DOCS-ATTEST-75-002)
+
+## Core invariants (all components)
+- **Tenant isolation**: Every API call requires `X-Stella-Tenant`; storage and caches are keyed by tenant.
+- **Append-only inputs**: Evidence, advisories, and attestations are stored immutably; no in-place edits.
+- **Determinism**: Sorting and pagination are stable; timestamps are UTC ISO-8601; hashes are lowercase hex.
+- **No consensus**: Components enforce validation/verification only; no severity or policy decisions inside AOC services.
+- **Offline-first**: All external data (feeds, keys, checkpoints) must be supplied via bundled inputs; no live fetches when sealed.
+
+## Attestor-specific invariants
+- **Trust roots**: Verification keys are loaded exclusively from the bundled trust store; network key discovery is disabled in sealed mode.
+- **DSSE only**: Inputs must be DSSE envelopes; detached signatures are rejected with a deterministic error code.
+- **Transparency optional, explicit**: If a mirrored checkpoint is provided, inclusion proof is validated; otherwise results record `transparency=skipped` without failing the request.
+- **Rationale trail**: Each verification emits a rationale list (e.g., `key.match`, `transparency.included`, `transparency.skipped`) so results are replayable.
+- **Immutability**: Verified statements and rationale are recorded append-only in the delivery/verification ledger; retries must not overwrite prior entries.
+
+## Guardrails for implementers
+- Never permit unsigned or partially signed payloads to proceed past parsing.
+- Reject any outbound HTTP/S fetch during verification when `Attestor__Offline__Enabled=true`.
+- Keep secret material out of logs; log statement digests and key ids only.
+- Round numeric scores/weights only at the presentation boundary; internal math stays high-precision.
+
+## Audit checklist
+- [ ] Tenant header enforced on every endpoint.
+- [ ] Trust bundle hash matches the signed manifest on disk.
+- [ ] Transparency verification results are captured per request.
+- [ ] Ledger entries are append-only and carry rationale + trace ids.

docs/security/notifications-hardening.md

@@ -0,0 +1,37 @@
+# Notifications Hardening Guide
+
+Last updated: 2025-11-25 (Docs Tasks Md.V · DOCS-NOTIFY-40-001)
+
+## Threat model
+- Tenant data isolation breaches (cross-tenant deliveries).
+- Channel compromise (webhook leaks, OAuth token theft).
+- Message tampering or replay.
+- Flooding / notification storms.
+
+## Controls
+- **Tenant isolation**: every rule/channel/template includes `tenant`; APIs enforce `X-Stella-Tenant`. Mongo collections are filtered by tenant with indexes on `(tenant, id)`.
+- **Secrets**: channels reference Authority `secretRef`; secrets never stored in Notify DB. Rotate via Authority and `:refresh-secret`.
+- **Outbound allowlist**: restrict hosts/ports per tenant; defaults block public internet in air-gapped kits.
+- **Signing**: webhook deliveries include `X-Stella-Signature` HMAC-SHA256 over body+nonce; receivers must reject stale timestamps (>5m) and verify signature.
+- **Replay protection**: delivery ledger de-dupes on `(channel, bodyHash)` for 24h; escalation tokens are single-use DSSE-signed.
+- **Rate limits/throttles**: per-rule and per-channel throttles; quiet hours for non-critical traffic.
+- **Templates sandboxed**: no file/network access; helpers are pure and deterministic.
+- **Logging/PII**: payloads redacted based on rule labels; logs avoid full body, store hashes instead.
+- **Audit**: all admin actions (create/update/delete channel or rule) logged with actor, trace id, and diff.
+
+## Deployment checklist
+- [ ] Authority scopes `notify.viewer|operator|admin` configured; service accounts least-privilege.
+- [ ] HTTPS everywhere; TLS 1.2+; HSTS on WebService front-door.
+- [ ] Redis protected by auth and network policy; Mongo TLS + auth enabled.
+- [ ] Outbound allowlists defined per environment; no wildcard `*`.
+- [ ] Webhook receivers validate signatures and enforce host/IP allowlists.
+
+## Incident playbook (channel compromise)
+1) Disable affected channel via `PATCH /channels/{id}` (`enabled=false`).
+2) Rotate secret in Authority; refresh channel secret.
+3) Search ledger for deliveries to compromised endpoint and notify tenants if required.
+4) Re-enable with new endpoint/secret after validation.
+
+## Offline/air-gap notes
+- Ship channel manifests and secrets via sealed bundles; keep hash manifest with signed checksum.
+- Disable any channel type not supported in the enclave (e.g., external Slack) and use in-app or file-drop channels instead.

docs/security/secrets-handling.md

@@ -0,0 +1,20 @@
+# Secrets Handling (Orchestrator additions)
+
+Last updated: 2025-11-25
+
+## Principles
+- Secrets are stored in Authority and referenced via `secretRef`; services never persist raw secrets.
+- No secrets in logs, traces, metrics, crash dumps, or health endpoints.
+- Offline/air-gap: secrets are delivered through sealed bundles and loaded at startup only.
+
+## Orchestrator-specific rules (DOCS-ORCH-34-002)
+- Plugin steps receive secrets via `secretRef`; workers fetch at step start and keep in-memory only for the step scope.
+- Secrets are not written to the run ledger, artifacts, or NDJSON exports; only `secretRef` identifiers may appear.
+- Network egress is deny-by-default; allowlists must reference `secretRef`-protected credentials when needed.
+- Cancellation and retries must not log or surface secret material; redaction applies to all error paths.
+
+## Audit checklist
+- [ ] Every plugin configuration uses `secretRef`, not inline values.
+- [ ] Logs/traces verified to contain no secret payloads (redaction tests).
+- [ ] Run ledger verified to store hashes/refs only.
+- [ ] Secret refresh/rotation tested (Authority + worker reload).