Private log artifacts

Chalupa stores log metadata, transfer state, stable artifact references, and short-lived redacted excerpts in Neon. Complete compressed log bytes never pass through Chalupa or Neon: the droplet uploads each chunk directly to a short-lived file.cheap upload URL, then asks Chalupa to commit the receipt.

Trust boundary

The signed launched event registers the owner-selected session policy from chalupa.yml. Chalupa converts expiresAfterMinutes into an absolute deployment deadline and snapshots the log quotas when the first log session is created. Later plan requests cannot add services, extend expiry, increase chunk size, or increase the total byte budget. A deployment accepts at most eight client-selected source sessions. All of them share one maxTotalBytes budget and one 256-chunk ceiling, enforced under a PostgreSQL deployment-row lock. Concurrent restarts therefore cannot multiply the configured allowance.

The droplet receives only the Chalupa HMAC ingest key and individual upload grants. It never receives a Vercel Blob token, a file.cheap service credential, a Neon connection string, or a DigitalOcean write credential. Chalupa uses its Vercel workload identity when it calls the private file.cheap plan and commit APIs.

The administrator console also uses Chalupa as a capability broker for complete log downloads. The browser submits only the environment slug, Chalupa chunk ID, and stable file.cheap artifact ID. Chalupa resolves the committed chunk again from Neon and never trusts an artifact URI supplied by the browser. It then uses the request's Vercel OIDC workload token to request one exact download grant from file.cheap. That OIDC identity is authorized only for committed chalupa.log-chunk artifacts with Chalupa's native log schema.

Protocol

1. POST /api/ingest/logs/plans reserves the next contiguous sequence and returns 201 with a short-lived direct PUT grant. An exact already committed retry returns 200 without a capability.
2. The producer uploads application/zstd bytes directly to that URL.
3. POST /api/ingest/logs/commits verifies file.cheap's committed digest, length, media type, artifact identity, and state.
4. Chalupa exposes an ArtifactRefV1 only after the remote commit succeeds.
5. POST /api/ingest/logs/finalize archives a session after every reserved chunk is committed.
6. An authenticated POST /api/logs/downloads revalidates the committed chunk, file.cheap artifact reference, SHA-256 digest, length, media type, producer, artifact ID, retention boundary, and exact Vercel private Blob object path before returning a 303 to the short-lived signed GET.

All three Chalupa requests use the existing bounded HMAC contract. Plans are idempotent by deployment, source session, and sequence. Streams are stdout, stderr, or combined. Chalupa stores the exact immutable file.cheap plan request, including its retention timestamp, before requesting a transfer capability. Every renewal therefore reuses identical bytes instead of deriving a new timestamp after a restart.

If an upload response is lost, file.cheap returns either a renewed 201 plan or the already committed artifact as a capability-free 200 replay. Chalupa persists that replay directly. A no-overwrite PUT conflict proceeds only to commit, where file.cheap performs the bounded digest and length verification; the conflict alone never creates an artifact reference. If commit succeeded remotely but its response was lost, the original receipt remains valid for reconciliation while the committed artifact is retained.

The collector also persists one finalization timestamp and its durable truncated decision before sending the final request. If the response is lost, every retry uses that exact body and therefore the same finalization fingerprint. chalupa down stops collection, retries deferred spool delivery and finalization within one bounded deadline, and confirms the collector's durable state instead of treating a successful systemctl stop as proof that the session was archived. Terminal validation errors fail closed; temporary control-plane failures honor the bounded retry delay.

An exact reserved chunk can finish after the deployment deadline or after retention archives its Chalupa session. This recovery path reuses the original fingerprint, byte quota, artifact identity, and immutable plan; it cannot admit a new sequence or alter existing bytes. A producer may acknowledge finalization after that recovery completes, while the session remains marked as retention-archived and truncated.

Retention and teardown

Two independent clocks govern how long log data stays reachable, and they do not agree, which has confused an operator in production before:

1. Redacted excerpts, fixed at 24 hours. The bounded text preview Chalupa stores in Neon for the console's live view is deleted 24 hours after the session, regardless of session.logs.retentionDays. This value is not configurable.
2. Committed chunks, session.logs.retentionDays. The complete compressed bytes committed to file.cheap follow the deployment's configured retention window (7 days by default, 1–30 configurable in chalupa.yml). See chalupa.yml reference.

A session older than 24 hours but within its retentionDays window is exactly this state: the console's excerpt view shows nothing for it, while the complete chunk bytes remain downloadable through POST /api/logs/downloads. Do not read a missing excerpt as evidence that the underlying artifact is gone.

The private console polls a bounded view every five seconds and supports service and stream filters. It clearly marks archived or truncated sessions. Stale or expired collecting sessions are archived, but unresolved receipts and immutable plans remain server-side so an ambiguous remote commit can be reconciled. Expired signed upload URLs are cleared from Chalupa without clearing the receipt. A later abandonment process must first reconcile the exact plan with file.cheap; it cannot infer remote state from a local clock.

The signed download URL is never persisted in Neon, returned as JSON, placed in React state, rendered as a stable URI, or written to application logs. The redirect is no-store and uses Referrer-Policy: no-referrer; complete bytes flow directly from private Blob storage to the authenticated administrator's browser and never pass through Chalupa. Cookie-authenticated form submissions must carry exact same-origin browser provenance. The signed grant cannot outlive the artifact's own retention timestamp.

file.cheap owns blob retention and deletion. Destroying a droplet does not erase committed artifacts, and a Vercel function cannot destroy the local Pulumi state. An operator must still run the documented chalupa down workflow. Compute destruction remains best effort with respect to the final SSH flush: if the collector cannot confirm finalization before the deadline, Chalupa prints a warning and preserves every already committed artifact. Retention later archives a stale collecting session, but the warning should be investigated before relying on the final chunk.