# Debug bundles and capture windows

A debug bundle is a diagnostic copy for one recorded sign-in. It contains the recorded validator invocations, timeline, failing invariant and a summary of the current configured IdP metadata. Historical attempts without invocation evidence explicitly report `checks_available: false`; timeline stages are not validation checks.

Management operations require a current human member with environment-write access. Hosted portal operations require an authorized IT session for the connection's organization and its permitted connection scope. API keys and staff credentials do not grant this protected access.

## Capture a bounded window

Use POST, GET and DELETE on `/v1/connections/{conn}/debug_capture` to start, inspect and end a window. The setup portal offers the same capture to the organization's IT admin.

A window lasts at most one hour and admits at most 20 captures at its fixed origin. Read `captured` as **captured N of 20**, not as a count of all sign-in attempts. Sign-ins served by other regions, diagnostic outages or unavailable capture capacity are omitted. Diagnostic capture never changes the sign-in outcome. An uncertain reservation can consume capacity without becoming a completed capture.

Opening, closing and completed admissions are audited without captured values. Ending a window persists its disable state even if the diagnostic cache is unavailable.

## Create and read a bundle

POST `/v1/debug_bundles` with the scoped `sign_in` identifier. GET `/v1/debug_bundles/{bundle}` reads metadata; GET `/v1/debug_bundles/{bundle}/content` reads the document.

Optional SAML response and assertion diagnostics come only from independently verified tests or eligible capture-window admissions. They may be unavailable even when the sign-in has a timeline. Custom-attribute preview data is never reused. OIDC tokens and claim bodies are not included.

Redaction masks NameID, email and attribute values, preserves approved names and types and genuine signature/digest text, and replaces certificates with SHA-256 fingerprints. Metadata endpoint summaries omit credentials, paths, queries and fragments. Redaction changes XML: the copy is not a cryptographically valid signed SAML message and must not be replayed.

## Retention and sharing

Encrypted objects retain data for at most 7 days on Free and Pro, 30 days on Business, and a configured maximum of 90 days on Enterprise. Source lifetime begins at capture. Creating a bundle or share cannot extend that lifetime. Physical expiry cleanup requires the retention worker to run.

POST `/v1/debug_bundles/{bundle}/share_links` or its portal equivalent to mint a bearer link. It expires within 15 minutes or at the object's earlier expiry. Anyone holding it can open the fixed `/debug_bundle_share` proxy while valid; treat it as a secret and avoid putting it in logs or tickets with broader access.

Each open is audited. The proxy serves content directly without a presigned redirect and uses `no-store`, `noindex, nofollow` and `no-referrer` response protections, including refusals. These headers do not prevent a recipient from saving or forwarding the content.
