Audit events

How Authsome records security events using an SQLite-backed storage model.

Authsome keeps an append-only event log for sensitive actions. In the current release, it writes audit events to an SQLite-backed storage managed by the local daemon, moving away from the old flat-file audit.log.

Overview

The Audit log tracks:

• External AuditEvents: Outbound HTTP calls an agent makes through the proxy to a third-party API (for example, api.github.com).
• Internal AuditEvents: Credential lifecycle operations (login, logout, token refresh, revocation) and auth flow steps.

The Server is the Source of Truth: The local Authsome daemon acts as the central source of truth. All proxy instances (sidecars) ship their events asynchronously to the daemon via the POST /audit/events endpoint. The proxy itself does not write to local files.

Event Schema

Every AuditEvent requires two actor fields:

• identity: The cryptographic agent Handle making the request.
• principal_id: The human or team Principal that owns the Vault.

Common fields included:

Field	Description
timestamp	ISO-8601 UTC timestamp of the event.
event	The event type (provider.login, provider.login_failed, provider.refresh_failed, provider.revoked, identity.claimed, etc.)
provider	The external provider involved (e.g., github, openai).
connection	The named connection used.
identity	The Identity Handle making the call.
principal_id	The PrincipalId resolved by the server.

Dashboard and Admin Access

Authsome includes an Admin Audit Dashboard, served natively by the daemon (at /audit).

• Principals with the admin role can view all events across the deployment.
• Principals with the user role may only view events relevant to their own PrincipalId.

Reading the Log

You can view the audit events directly from the CLI or query the daemon:

authsome log              # Print recent audit events
authsome log --json       # Output JSON format

Privacy and Secrets

What the log contains:

• Timestamps for every significant action.
• Provider and connection names.
• Event types, identity handles, and principal IDs.
• Outcome metadata (like status: "failure" on failed logins).

What the log does NOT contain:

• Access tokens, refresh tokens, API keys, client_secrets, or any other secret values.
• Decrypted credential records.
• Request payloads passed through the proxy.

If you ever find a secret in the audit output, that is a bug. Report it through Responsible disclosure.