Skip to content

docs(audit): update audit-event docs for 0.27 emission changes#27

Merged
rrrodzilla merged 1 commit into
mainfrom
docs/audit-events-update
May 28, 2026
Merged

docs(audit): update audit-event docs for 0.27 emission changes#27
rrrodzilla merged 1 commit into
mainfrom
docs/audit-events-update

Conversation

@rrrodzilla

Copy link
Copy Markdown
Contributor

Summary

Documentation update for the audit-event work landed/queued in #14, #21, #22, #23, #25. Four doc pages affected.

audit/page.md

  • "Auth Events (Automatic)" table rewritten. The middleware now emits six distinct kinds (was three), with correct severities and a note that AuthTokenRevoked carries jti metadata.
  • Migration callout added directly below the table: `AuthLoginFailed` is no longer middleware-emitted. Reserved for app login handlers.
  • "Event Kinds" reference table: `AuthLoginFailed` description clarified ("emit from app login handlers; the middleware no longer emits this"); `AuthTokenMissing` and `AuthTokenInvalid` rows added.
  • Syslog example (line ~256) and OTLP example (line ~300): severity for `AuthLoginSuccess` updated from `Informational` to `Notice` to match the fix(audit): align AccountExpired/Deleted severities; bump AuthLoginSuccess to Notice #23 alignment.

cedar-auth/page.md

  • New "Audit Integration" section. Documents the automatic `AuthPermissionDenied` emission on `Decision::Deny` (HTTP and gRPC), what fields are captured, and how to suppress via `audit_auth_events: false`.

rate-limiting/page.md

  • New "Audit Integration" section. Documents the automatic `HttpRequestDenied` emission on `Error::RateLimitExceeded`, what fields are captured, and the anomaly-detection use case.

token-auth/page.md

  • New "Audit Emission" section. The token-auth doc previously made no mention of audit emission; this section enumerates the four middleware-emitted kinds, calls out the `jti` correlation field, and explains the `AuthLoginFailed` migration with a pointer to the audit docs.

Out of scope

  • A consolidated 0.27 migration guide (release notes prose, not a doc page). The breaking-ish changes here — severity moves, `AuthLoginFailed` removal from middleware, `AccountUpdated`→`AuthPasswordChanged` for password change — are real for downstream SIEM rules. The migration story belongs in a release-notes file (not under `docs/`) and is tracked separately.

Test plan

  • All four files re-read after edits to confirm placement, heading levels, and formatting are consistent with surrounding content.
  • No emoji, no rewording of unrelated prose.
  • Visual rendering check by Markdoc (no markdoc.config.js changes; the new tables and sections use standard markdown that already renders in the existing pages).

Reflects the audit-event work that landed in #14, #21, #22 and is
queued in #23, #25:

- audit/page.md: rewrite the "Auth Events (Automatic)" table to match
  the new emission set (AuthLoginSuccess at Notice; AuthTokenMissing /
  AuthTokenInvalid added; AuthTokenRevoked notes jti metadata;
  AuthPermissionDenied and HttpRequestDenied added); update the
  syslog and OTLP example severities to Notice; expand the "Event
  Kinds" reference table; add a migration callout for AuthLoginFailed.
- cedar-auth/page.md: add "Audit Integration" section describing
  automatic AuthPermissionDenied emission on Decision::Deny.
- rate-limiting/page.md: add "Audit Integration" section describing
  automatic HttpRequestDenied emission on RateLimitExceeded.
- token-auth/page.md: add "Audit Emission" section covering the four
  middleware-emitted kinds, the jti correlation field, and the
  AuthLoginFailed migration.

Refs #13 #15 #16 #18 #19
@rrrodzilla rrrodzilla merged commit b375da8 into main May 28, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant