git.stella-ops.org/docs/security/audit-events.md

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.