Emit domain events in OCSF-aligned schema

[rsharath]

Summary

Add an audit event emitter that publishes ZeroID's domain events (identity lifecycle, credential issuance/revocation, attestation, signals) using the Open Cybersecurity Schema Framework (OCSF) field names and category taxonomy, alongside the existing zerolog operational logs.

Motivation

CoSAI Appendix E: "Organizations SHOULD map these to established schemas (OCSF, CEF). Agentic-specific fields such as delegation_path, attestation_state, and correlation_id SHOULD be placed in extension fields until formal support is adopted."

OCSF is backed by Splunk, AWS, IBM, Cisco, and CrowdStrike and is the de facto schema for SIEM ingestion. Enterprise buyers look for OCSF alignment as a "ready for our SOC" signal. ZeroID currently emits zerolog JSON with local field names, i.e., correct data, wrong shape for most SIEM pipelines.

Design approach

Keep the existing zerolog operational logs as-is (request start/complete, warnings, etc.). Add a separate audit event channel specifically for security-relevant domain events. Deployers can ship the audit channel to their SIEM without drowning in request chatter.

Event mapping

ZeroID event	OCSF class	activity_id
credential.issued	Authentication (3002)	1 (Logon)
credential.revoked	Authentication (3002)	2 (Logoff)
credential.introspected	Authentication (3002)	6 (Verify)
identity.created	Entity Management (3006)	1 (Create)
identity.updated	Entity Management (3006)	2 (Update)
identity.deactivated	Entity Management (3006)	3 (Delete)
attestation.passed	Authentication (3002)	6 (Verify), with status_code: success
attestation.failed	Authentication (3002)	6 (Verify), with status_code: failure
signal.ingested	Detection Finding (2004)	per signal severity
auth_code.consumed	Authentication (3002)	1 (Logon)
auth_code.replay_detected	Detection Finding (2004)	1 (Create), high severity
refresh_token.reuse_detected	Detection Finding (2004)	1 (Create), high severity

Minimum initial scope: map these ZeroID events to OCSF classes: OCSF common fields populated per event: time, actor.user.uid, actor.user.type, src_endpoint, metadata.product, severity_id, status_id, type_uid.

Agentic-specific fields placed in OCSF extensions:

• delegation_path (array of WIMSE URIs from the act chain)
• attestation_state
• correlation_id (once issue devops: Update README.md #6 lands; until then, emit what's available)
• identity_type, sub_type, trust_level, risk_tier, capability_tier

Proposed change

- New package internal/audit/ with:
- Event struct matching OCSF common fields + ZeroID extension namespace.
- Emitter interface; default impl writes to zerolog with a channel: "audit" marker.
- Per-event builders: NewCredentialIssued(...), NewIdentityCreated(...), etc.
- Hooks at existing event sites:
- credentialSvc.IssueCredential → emit credential.issued.
- credentialSvc.RevokeCredential → emit credential.revoked.
- oauthSvc.Introspect → emit credential.introspected.
- identitySvc.Create/Update/Deactivate → emit identity..
- attestationSvc.Verify → emit attestation..
- signalSvc.Ingest → emit signal.ingested.
- Auth code replay path → emit auth_code.replay_detected.
- Refresh token reuse detection → emit refresh_token.reuse_detected.
- AuditEmitter hook on Server struct so deployers can swap the default emitter (e.g., to Kafka, direct
OCSF/HTTPS).

• Documented mapping table in docs/audit-events.md.

Out of scope

• Log shipping infrastructure. Deployers wire the zerolog output to their SIEM.
• CEF support. OCSF is strictly better for modern SOCs; CEF is a follow-up if customer demand appears.
• Transforming operational logs (request start/complete, debug, warning). Those stay in their current shape.

Compatibility notes

• Additive. Nothing removed. Existing logs are still emitted exactly as they are today.
• The new audit channel is a new line per event, and deployers opt in by filtering for channel=audit.
• Extension fields prefixed with zeroid. to avoid OCSF namespace pollution.

Acceptance Criteria

• All events in the mapping table above are emitted with correct type_uid, activity_id, and common fields.
• Audit events identifiable via stable marker (channel: "audit" or similar).
• AuditEmitter hook on Server lets deployers swap the default emitter.
• docs/audit-events.md documents every event, its OCSF class, and the ZeroID extension fields.
• Integration test verifies OCSF shape for at least credential.issued and refresh_token.reuse_detected.
• CoSAI Appendix E cited in the docs.

Logs / References

https://github.com/cosai-oasis/ws4-secure-design-agentic-systems/blob/main/agentic-identity-and-access-control.md