# 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, `request.tampered`/`request.unexpected_parameter`, `bootstrap.invite_token`, 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.token.tamper` — suspicious `/token` request detected (unexpected parameters or manipulated payload).
- `authority.bootstrap.user` and `authority.bootstrap.client` — bootstrap API operations.
- `authority.bootstrap.invite.created` — operator created a bootstrap invite.
- `authority.bootstrap.invite.consumed` — invite consumed during user/client provisioning.
- `authority.bootstrap.invite.expired` — invite expired without being used.
- `authority.bootstrap.invite.rejected` — invite was rejected (invalid, mismatched provider/target, or already consumed).
- `authority.token.replay.suspected` — replay heuristics detected a token being used from a new device fingerprint.
- 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.