up

docs/security/audit-events.md

@@ -0,0 +1,47 @@
+# StellaOps Authority Audit Events
+
+StellaOps Authority emits structured audit records for every credential flow and bootstrap operation. The goal is to provide deterministic, privacy-aware telemetry that can be persisted offline and replayed for incident response without leaking credentials.
+
+## Contract
+
+Audit events share the `StellaOps.Cryptography.Audit.AuthEventRecord` contract. Key fields:
+
+- `EventType` — canonical identifier such as `authority.password.grant`, `authority.client_credentials.grant`, or `authority.bootstrap.user`.
+- `OccurredAt` — UTC timestamp captured at emission time.
+- `CorrelationId` — stable identifier propagated across logs and persistence.
+- `Outcome` — `Success`, `Failure`, `LockedOut`, `RateLimited`, or `Error`.
+- `Reason` — optional failure or policy message.
+- `Subject` — `AuthEventSubject` carrying subject identifier, username, display name, and optional realm metadata. All subject fields are tagged as PII.
+- `Client` — `AuthEventClient` with client identifier, display name, and originating provider/plugin.
+- `Scopes` — granted or requested OAuth scopes (sorted before emission).
+- `Network` — `AuthEventNetwork` with remote address, forwarded headers, and user agent string (all treated as PII).
+- `Properties` — additional `AuthEventProperty` entries for context-specific details (lockout durations, policy decisions, retries, etc.).
+
+## Data Classifications
+
+Every string value uses `ClassifiedString` to assign a data classification:
+
+- `None` — public or operational metadata (event type, outcome).
+- `Personal` — personally identifiable information (PII) such as subject identifiers, usernames, remote IP addresses, and user agents.
+- `Sensitive` — secrets or derived credentials (client secrets, retry tokens). Avoid storing raw credentials; emit only hashed or summarised data when the classification is `Sensitive`.
+
+Downstream log sinks and persistence layers can inspect classifications to redact or separate PII before export.
+
+## Event Naming
+
+Event names follow dotted notation:
+
+- `authority.password.grant` — password grant handled by OpenIddict.
+- `authority.client_credentials.grant` — client credential grant handling.
+- `authority.bootstrap.user` and `authority.bootstrap.client` — bootstrap API operations.
+- Future additions should preserve the `authority.<surface>.<action>` pattern to keep filtering deterministic.
+
+## Persistence
+
+The Authority host converts audit records into `AuthorityLoginAttemptDocument` rows for MongoDB persistence. Documents must:
+
+- Preserve `CorrelationId`, `SubjectId`, `ClientId`, `Plugin`, `Outcome`, `Reason`, and `OccurredAt`.
+- Store remote address in `remoteAddress` only after classification as PII.
+- Include summary booleans such as `Successful` to accelerate lockout policy checks.
+
+When exporting to external SIEMs, honour the `ClassifiedString.Classification` tag to avoid shipping PII into restricted environments.