Audit Logs

Audit Logs in AuditAuth are governance-grade records.

They are designed for:

• Accountability
• Traceability
• Security review
• Operational transparency

Audit logs are not analytics events.

They are immutable security records.

Append-Only Model

Audit logs are effectively append-only.

Current implementation:

• Only create operations are performed.
• No update flows exist.
• No delete flows exist (outside TTL expiration).

After creation, entries are not modified.

This preserves integrity.

Event Generation

Audit logs are generated via:

• Explicit service calls
• Interceptor-based side effects (e.g. authentication flows)

Authentication flows use an interceptor pattern:

• Core logic executes.
• Audit entry is emitted as side-effect.
• Audit persistence occurs asynchronously (best-effort).

Failure to persist an audit entry does not block the primary operation.

This favors system availability over strict transactional coupling.

Event Structure

Audit logs store structured summaries, not raw payloads.

Typical fields include:

• action
• email
• success
• reason
• application
• account
• createdAt
• expires_at

Audit logs intentionally avoid storing:

• Full request bodies
• Raw tokens
• Full identity objects

They store structured event-level data.

Identity Awareness

Audit logs are identity-aware.

They contain PII:

• email

They are scoped by:

• application
• account

Audit logs provide traceability at the identity boundary.

Retention Enforcement

Retention is plan-driven.

Each audit log entry contains:

• expires_at

A TTL index on expires_at ensures:

• Physical deletion when expired
• No logical filtering-only behavior
• Predictable storage boundaries

Deletion is handled by MongoDB TTL monitor.

No custom cleanup worker exists.

Plan-Based Control

Audit logging behavior is controlled by plan configuration:

• auditlog.retention_days
• auditlog.can_download

Plan determines:

• How long logs are retained
• Whether download/export is available

Retention is applied at ingestion time.

Historical expires_at values are not recalculated when plan changes.

Download Capability

Some plans allow audit log download.

UI-level enforcement controls:

• Access to download functionality

Backend-level enforcement for export is minimal in current Beta.

Future versions may strengthen enforcement at API layer.

Lifecycle Coverage

Audit logs capture:

• Authentication events
• Portal access events
• MFA configuration changes

They do not systematically log:

• All administrative lifecycle transitions
• All plan enforcement decisions
• All enforcement failures

Coverage is focused on identity actions.

Consistency Model

Audit persistence is:

• Asynchronous
• Best-effort
• Not part of the primary transaction

This means:

• Rare edge cases may exist where core action succeeds but audit log fails.
• System availability is prioritized.

This is acceptable for Beta.

Future versions may introduce stricter coupling or retry mechanisms.

Storage Model

Audit logs are stored in a dedicated collection.

Data isolation is logical:

• Scoped by application

There is no physical partitioning per application.

Indexing is minimal beyond TTL enforcement.

Security Characteristics

Audit logs provide:

• Immutable event trail
• Identity-scoped traceability
• Plan-aware retention
• Physical TTL deletion

They do not provide:

• WORM storage guarantees
• Cryptographic log signing
• Tamper-evident audit chains

These features may be introduced in future releases.

Architectural Position

Audit logs are:

• Governance-oriented
• Identity-aware
• Plan-bound
• TTL-enforced
• Append-only

They are not designed to replace SIEM systems.

They provide structured traceability within the identity boundary.

Next Step

To understand how analytics-grade data flows through the system, continue with:

• Metrics Pipeline