feat(upload): status endpoint for cross-refresh resume

[rubenhensen]

Background

#145 added idempotent retry of the most recently committed chunk: a client whose chunk-PUT response was lost can replay the same chunk with the previous token and the server returns the cached response without re-writing or double-counting. This unblocked transparent in-session retry in postguard-js (encryption4all/postguard-js#47).

What's still missing is cross-refresh / cross-process resume. Today, if the user reloads the page, navigates away and back, or the browser tab crashes mid-upload, all in-flight state is lost on the client even though the server's last_chunk cache and the on-disk file are still intact (assuming the session hasn't been evicted past its idle TTL).

#117 and #136 both flagged this. @dobby-coder's audit at #136 (comment) sketched two designs; we picked idempotent retry for #145. This issue tracks the second one.

Proposed design

A new authenticated GET endpoint that returns the current upload state so a client can rehydrate after losing its in-memory state:

GET /fileupload/{uuid}/status
Authorization: Bearer <recovery_token>

200 OK
{
  \"uploaded\": <bytes>,
  \"cryptify_token\": \"<current rolling token>\",
  \"prev_token\": \"<previous rolling token, may be null if no chunk committed yet>\",
  \"prev_uploaded\": <byte offset of last committed chunk, may be null>
}

• recovery_token is issued at upload_init time alongside the first cryptifytoken, returned in a separate response field (e.g. recovery_token). The client stores it in IndexedDB along with the upload UUID.
• The client uses prev_token + prev_uploaded to feed the existing idempotent-retry path on the very next chunk PUT, so the server's rolling-token chain stays intact even if the browser missed the response.
• 404 (with the structured upload_session_not_found body from feat(upload): structured 404 body + configurable session TTL #144) when the session has been evicted or never existed.

Why this needs Phase 2 first

Cross-refresh resume only makes sense if the upload session itself survives a server restart. Today FileState is in-memory only (#116), so a Procolix redeploy or pod crash already wipes the session regardless of whether the client could remember the UUID. This issue should be picked up after the Postgres-backed sessions land (#116, #134) — otherwise we're shipping client recovery for a server that can't actually recover.

Out of scope for this issue

• The client-side IndexedDB persistence and rehydrate-on-reload flow in postguard-js — tracked separately at encryption4all/postguard-js#X (filed alongside this).
• Resumable downloads — also tracked separately in postguard-js (cryptify's FileServer already supports Range, so it's a pure SDK concern).

Acceptance criteria

• GET /fileupload/{uuid}/status returns the schema above for live sessions
• Endpoint requires the recovery_token issued at init; missing/invalid → 401
• Evicted/unknown session → 404 with upload_session_not_found body (matches feat(upload): structured 404 body + configurable session TTL #144)
• upload_init response includes the recovery_token (additive — old clients ignore it)
• Documented in `api-description.yaml`
• Unit tests cover hit / 401 / 404 / state-after-N-chunks cases

Refs

• Major version bump tracking (askama 0.15, reqwest 0.13, sha2 0.11, rand 0.10, strum 0.28, pg-core 0.5) #117 (postguard-website)
• Upload and download sessions are not robust #136 (this repo, design discussion)
• feat(upload): idempotent retry of the last committed chunk #145 (this repo, idempotent retry — the in-session counterpart)
• Upload session state is not persisted; server restart causes 404 on chunk PUT and orphaned files on disk #116, Persist quota usage to SQLite (config field usage_db is currently unused) #134 (this repo, blocking work)

[rubenhensen]

/dobby please review this design proposal — does the status-endpoint shape make sense, and is anything missing for the cross-refresh resume flow to work end-to-end once Phase 2 lands?

[dobby-coder]

The bot has seen the request! This agent will read the proposal carefully, cross-check against #145, #144, #136, and the Phase 2 work in #116/#134, and then post a proper review on whether the status-endpoint shape holds up and whether anything is missing for the cross-refresh resume flow. Off to dig in!

[dobby-coder]

Review of the status-endpoint design

Overall this is the right shape: the rolling-token chain is the only piece of session state the client genuinely can't reconstruct, so an authenticated read of (uploaded, cryptify_token, prev_token, prev_uploaded) is the minimum needed to feed the existing #145 idempotent-retry path on the next PUT. The coupling to Phase 2 (#116/#134) is correct — without persisted sessions the endpoint is theatre.

Below are the gaps I'd want closed before this is implementation-ready. None block the overall direction.

Auth & info-leak

1. Avoid Authorization: Bearer for the recovery token. upload_init already uses Authorization: Bearer PG-… for tier-escalation API keys. A different route (/status) makes accidental collision unlikely in practice, but reusing Bearer makes it easier to misroute the wrong token from the client. Suggest a dedicated header (e.g. X-Recovery-Token) — narrower contract, no chance of a future middleware seeing a PG-… key on /status.
2. Constant-time comparison. Spell out in the AC that the recovery-token check uses constant-time equality (subtle::ConstantTimeEq or similar). 32 bytes from rand::random is fine for the value itself.
3. 401 before 404, and the same 404 body for "evicted" vs "never existed". As written, "missing/invalid → 401" and "evicted/unknown → 404" can be combined to probe for live UUIDs by sending any token: 404 means the UUID was real. Pin the order: validate token format/presence first → 401; then look up → on miss return 404 with upload_session_not_found regardless of whether the UUID was ever real. This matches the expired_or_unknown reason from feat(upload): structured 404 body + configurable session TTL #144.

Missing fields in the response

4. Idle-timeout reset on successful GET. feat(upload): structured 404 body + configurable session TTL #144 made the TTL configurable (default 3600s) and fix(store): extend upload session deadline on each chunk PUT #132 added Store::touch() per chunk. A refresh-and-resume flow can easily eat several minutes (user re-picks the file, IndexedDB rehydrate, re-derive keys), so a successful /status should touch the entry — otherwise rehydrate succeeds, then the very next chunk PUT 404s because the session aged out between the two calls. Add this to AC.
5. File-binding signal. After a refresh the client has to re-attach the local file (re-pick or pull from a transient handle). Today nothing on the server proves the bytes already uploaded came from the same file the user is now resuming with — a wrong file silently uploads garbage and only fails at finalize (Unsealer attribute mismatch), wasting bandwidth proportional to how far the original upload got. Two options worth considering:
   • Echo a total_size if it was known at init (it isn't today — InitBody has no size — so this would require an additive init field).
   • Echo the rolling token alone, which the client can verify by recomputing SHA256(prev_token || local_file[prev_uploaded - chunk_size .. prev_uploaded]) over the last chunk before sending the next one. This actually works with the current prev_token/prev_uploaded pair if the client is willing to do a one-time local check at resume time. Worth calling out in the SDK-side issue rather than the cryptify AC.
6. Naming nit. prev_uploaded is a byte offset, not a count. prev_offset reads better and avoids confusion with uploaded (which is a count). Trivial.

Phase-2 coupling

7. Persist recovery_token in the Phase 2 schema. This needs to be explicit on Upload session state is not persisted; server restart causes 404 on chunk PUT and orphaned files on disk #116/Persist quota usage to SQLite (config field usage_db is currently unused) #134, not just here — if it lands as an extra field on in-memory FileState only, it'll be quietly dropped by the persistence work and the cross-restart goal silently fails. Suggest cross-linking with a one-line note in Upload session state is not persisted; server restart causes 404 on chunk PUT and orphaned files on disk #116's schema section.
8. Concurrency model is unspecified. Two tabs/devices that both rehydrate the same UUID will both call /status, both get the same prev_token, and race. The last_chunk replay check from feat(upload): idempotent retry of the last committed chunk #145 absorbs duplicate retries cleanly, but as soon as one tab moves to chunk N+1 the other sees a 4xx on its own N+1. That's acceptable behaviour but should be documented as "single-active-resumer" — or, if you want strictness, issue a fresh recovery_token on each /status call and invalidate the previous one (lease semantics). I'd vote for the documented-only path; lease semantics are a lot of mechanism for a niche case.

CORS / wire mechanics

9. Allowed request headers. Whichever header carries the recovery token needs to be in allowed_headers of the cors fairing — currently cryptifytoken is exposed as a response header. Easy to miss; worth adding a CORS smoke test to the AC.
10. Response content-type / camelCase. Existing handlers return JSON with snake_case fields (upload_session_not_found, used_bytes). The proposal already uses snake_case — fine, but make sure api-description.yaml matches and the postguard-js side doesn't expect camelCase (the InitBody request side is camelCase, which is the inconsistency, not the response side).

Suggested AC additions

• Recovery-token comparison is constant-time.
• Successful /status calls Store::touch(uuid) to reset the idle TTL.
• Validation order: missing/malformed token → 401, valid token + no session → 404 with upload_session_not_found.
• Recovery-token field is included in the Phase 2 persisted-session schema (cross-link to Upload session state is not persisted; server restart causes 404 on chunk PUT and orphaned files on disk #116/Persist quota usage to SQLite (config field usage_db is currently unused) #134).
• Behaviour when two clients resume the same UUID is documented in api-description.yaml (single-active-resumer).
• CORS allowed_headers includes the recovery-token header; smoke test for a browser preflight.

What works as-is

• Returning cryptify_token (current rolling token) plus prev_token/prev_uploaded is exactly what the feat(upload): idempotent retry of the last committed chunk #145 replay matcher needs; no extra response_token field is required because the server's current cryptify_token is the previous chunk's response_token.
• Nullable prev_token/prev_uploaded for the "no chunks yet" case is correct — client just resumes from offset 0 with the init token.
• Additive recovery_token on upload_init is wire-compatible with old clients.
• Gating the work on Phase 2 is the right call; without it this endpoint ships a recovery story for a server that can't actually recover, and that gap will surface as a confusing UX (rehydrate works → next chunk 404s after the next deploy) rather than a clean error.