Audit and observability

Audit events answer who did what, to which resource, when, and with what result. Application logs explain how the system behaved. These are separate records even if early infrastructure stores them through related services.

Audit event contract

Each append-only event records:

• event ID and UTC time;
• actor identity;
• action;
• target type and opaque target ID;
• result;
• request or correlation ID; and
• safe structured details.

Required event families include authentication success and failure, session revocation, identity and role changes, group and Root Folder changes, metadata-definition changes, upload initiation/completion/failure, version creation, metadata revisions, archive/restore, grant changes, query, download, exceptional administrator content access, and authorization denial.

The scoped CLI-token boundary appends safe token.use and token.revoke outcomes for authenticated use, expiry, revocation, scope denial, deactivation or membership denial, invalid hashes, confirmed revocation, and already-invalid logout. Events contain an opaque token-row identifier when one exists, safe subject and organization identifiers, and the validated correlation ID. They never contain the bearer token or its hash.

Secret boundaries

Audit details and application logs must exclude passwords, session tokens, refresh credentials, storage credentials, signing material, and file bytes. User-provided metadata must be handled as potentially sensitive structured data rather than copied indiscriminately into logs.

Implemented device-authorization boundary

The internal device authorization flow separates database accountability from service-boundary operational security evidence:

• The append-only database audit records valid device creation and database-owned terminal outcomes, including approval or denial, token issuance, invalid, expired, replayed, rate-limited, and ineligible results.
• A safe-correlated malformed, oversized, or extra-field request to a known unauthenticated device-create or device-token POST enters the global abuse-accounting boundary before structural validation. The route invokes the rejection RPC so the terminal result has bounded database audit and a correlated safe response. These routes remain an internal handshake, not a public product API.
• An unsafe supplied correlation ID fails before database accounting or audit. It is never normalized into an attacker-controlled audit value.
• Global-limit evidence is bounded and deduplicated. Ordinary authorization_pending and slow_down polls remain quiet. Every abuse-accounting counter (OTP start/verify, device create/poll) is a global-only ceiling, keyed by a fixed scope rather than caller identity or origin -- there is no trusted per-IP binding, since no caller-supplied network-origin header is treated as authoritative for rate-limiting decisions.
• Origin-validation, missing-session, and invalid or upstream-rejected browser-session failures produce safe structured service-boundary operational security evidence. They do not create anonymous database audit rows because the request did not reach an attributable database decision.
• Unknown paths and unsupported methods are routing failures, not authentication transactions, and do not create authentication audit records.

Neither record type contains a device code, user code, token or token hash, raw fingerprint, provider credential, or hostile correlation value.

Correlation

A validated correlation ID joins records only across boundaries the operation actually crosses. A networked CLI request can join CLI output, service evidence, SQL work, and a database audit event when those records exist. Route-rejected safe-correlated device requests retain the same ID in their bounded rejection evidence. Browser decision failures retain it in service-boundary evidence when database authorization did not run.

Local CLI validation, poll exhaustion, local expiry, and protected-persistence failures still return a safe correlation ID to the operator, but a pre-network failure has no server or database audit record. Local expiry retains the most recent poll correlation, and persistence failure after token issuance retains the token-response correlation. A correlation ID supports lookup; it does not imply that every layer produced a record.

Immutability

Audit immutability is a database guarantee, not just application convention: every audit table carries a BEFORE UPDATE/BEFORE DELETE trigger that unconditionally rejects mutation for every role, including service_role. tv admin audit list/admin_audit_list may filter and page events; nothing can edit or remove them. See Trust boundaries and Security and authorization for the redaction allowlist every event's details field passes through before it is ever written.

Operational readiness

Retention, access-control, alerting, and backup/restore are Supabase-managed-project concerns today — see Current state for what that single-data-plane concentration means in practice, and Reconciliation for the one operator-facing recovery procedure this repository implements directly.