Feat/siam audit events

[esune]

First attempt at logging information usable by SIAM platforms, when needed.

Logger is on by default, can be turned of using an environment variable or by updating the log level configuration.

Currently these events are being logged:

Event	Category	Description	Key Fields
auth_session_initiated	Session lifecycle	An OIDC authorization request created a new auth session.	session_id, client_id, ver_config_id, client_ip_hash, user_agent_family, requested_schemas, requested_attributes_count, requested_predicates_count
proof_request_created	Proof request flow	A proof request was built and is ready for scanning.	session_id, ver_config_id, proof_name, requested_schemas, expected_issuers
qr_scanned	Proof request flow	The QR code was scanned or the deep link was invoked by a wallet.	session_id, scan_method (qr_code / deep_link), client_ip_hash, user_agent_family
proof_verified	Proof request flow	Proof presentation was successfully verified.	session_id, ver_config_id, outcome=verified, credential_schemas, issuer_dids, credential_count, revocation_checked, duration_ms
proof_verification_failed	Proof request flow	Proof verification failed.	session_id, ver_config_id, outcome=failed, failure_category, duration_ms
session_abandoned	Session termination	The user abandoned or declined the proof request.	session_id, ver_config_id, outcome=abandoned, phase, duration_ms
session_expired	Session termination	The session expired before the proof flow completed.	session_id, ver_config_id, outcome=expired, phase, timeout_seconds
token_issued	Token flow	An OIDC ID token was successfully issued to the relying party.	session_id, client_id, ver_config_id, claims_count, duration_ms
webhook_received	Security / monitoring	An ACA-Py agent webhook was received.	webhook_topic, webhook_state, webhook_role
invalid_client_request	Security / monitoring	A client request failed validation (unknown client, bad params).	client_id, error_type, client_ip_hash

[Copilot]

Pull request overview

This PR introduces a privacy-preserving SIAM (Security Information and Analytics Management) audit logging system for the VC-AuthN OIDC controller. The implementation adds structured event logging at key points in the authentication and verification flow while maintaining strict privacy guarantees—no PII, credential values, or subject identifiers are ever logged. The feature is enabled by default but can be disabled via environment variable or log level configuration.

Changes:

• Added new audit logging module (api/core/siam_audit.py) with privacy-preserving event tracking for session lifecycle, proof verification, token issuance, and security events
• Integrated audit calls across routers (oidc.py, presentation_request.py, acapy_handler.py) to capture key workflow events with metadata-only logging
• Updated configuration and documentation to explain audit events, feature flags, and privacy guarantees

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
oidc-controller/api/core/siam_audit.py	New audit logging module with privacy-safe helper functions and event emitters for 10 different audit event types
oidc-controller/api/routers/oidc.py	Added audit calls for auth session initiation, proof request creation, and token issuance; improved import ordering
oidc-controller/api/routers/presentation_request.py	Added audit calls for QR code and deep link scanning events; reorganized imports
oidc-controller/api/routers/acapy_handler.py	Added audit calls for webhook receipt, proof verification (success/failure), and session termination; added schema/issuer extraction functions; improved privacy by moving full webhook body logging to debug level
oidc-controller/api/logconf.json	Configured siam.audit logger with INFO level and separate handler
docs/ConfigurationGuide.md	Comprehensive documentation of SIAM audit events, configuration options, privacy guarantees, and control mechanisms
oidc-controller/api/routers/tests/test_acapy_handler.py	Updated test fixture to include ver_config_id field; reorganized imports alphabetically

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coveralls]

Pull Request Test Coverage Report for Build 22197536649

Details

• 154 of 170 (90.59%) changed or added relevant lines in 4 files are covered.
• 4 unchanged lines in 2 files lost coverage.
• Overall coverage increased (+0.1%) to 88.915%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
oidc-controller/api/routers/oidc.py	5	9	55.56%
oidc-controller/api/routers/acapy_handler.py	60	65	92.31%
oidc-controller/api/routers/presentation_request.py	3	10	30.0%

Files with Coverage Reduction	New Missed Lines	%
oidc-controller/api/routers/acapy_handler.py	1	92.07%
oidc-controller/api/routers/presentation_request.py	3	36.96%

Totals
Change from base Build 21917061381:	0.1%
Covered Lines:	2230
Relevant Lines:	2508

---

💛 - Coveralls

[Gavinok]

Just a few clarifications and nits.

[loneil]

@esune is there a spec for what data/fields/events/etc any auditors or security is wanting from this? Or is what is being extracted our choice?
I think it looks good as a set of events, just curious if we're being asked for specifics?

[esune]

@esune is there a spec for what data/fields/events/etc any auditors or security is wanting from this? Or is what is being extracted our choice? I think it looks good as a set of events, just curious if we're being asked for specifics?

No spec, as far as I understand data related to IP addressed (even hashed as we do here) and events (type/start/end) is the bare minimum. We're really just looking to surface things for now and possibly gather more feedback and input once it is being used (that's my take at least).