wisp/IMPLEMENTATION.md

wisp — implementation notes

Design-stage document. Nothing here is built yet; this is the spec to build against, not a description of existing code.

Threat model

• The server operator can be assumed hostile-but-honest: they might try to read stored files, but the design should make that cryptographically impossible, not just policy-forbidden.
• The server can see: upload/download timing, file size (ciphertext length), IP addresses of uploader/downloader, and that a given blob id was retrieved. It cannot see: filename, file contents, or the encryption key.
• Not defended against: a malicious recipient who screenshots or re-uploads the file elsewhere after decrypting it. Nothing can defend against that — it's out of scope, same as it is for flit.
• Not defended against: a network observer between sender and the person they share the link with (e.g. if the link is sent over an insecure channel). The link itself is the credential; treat it like a password.

Crypto scheme

• Client generates a random symmetric key (32 bytes, libsodium crypto_secretbox or crypto_aead_xchacha20poly1305_ietf — same primitives already used across flit/waste-go, no new crypto library to vet).
• File is encrypted client-side before any network request. For files larger than a single-shot encrypt is comfortable with in a browser tab (say, >50MB), chunk into fixed-size blocks, each sealed independently with a per-chunk nonce derived from a chunk index — avoids holding the whole plaintext or ciphertext in memory at once. (flit already solved streamed chunked transfer over DataChannels; the chunking logic is reusable even though the transport here is HTTP upload, not WebRTC.)
• The key is placed in the URL fragment: https://wisp.example/d/<blob-id>#k=<key-b64>. Fragments are never sent to the server in an HTTP request — this is the same trick Firefox Send and PrivateBin used, and it's the load-bearing property that makes "server never sees plaintext, ever" actually true rather than just a policy.
• blob-id is a random, unguessable identifier (128-bit, base62), separate from the key. Knowing the id alone (e.g. from server logs) does not grant access to the file — you need the fragment too, which never reaches the server.

Storage

• Ciphertext blobs on local disk, one file per upload, named by blob-id.

• Metadata in SQLite (matches the npm-statuspage/general project convention — small, file-based, no separate DB server to run):

  CREATE TABLE drops (
    id            TEXT PRIMARY KEY,       -- blob-id, 128-bit base62
    size_bytes    INTEGER NOT NULL,
    created_at    INTEGER NOT NULL,       -- unix seconds
    expires_at    INTEGER NOT NULL,       -- created_at + TTL
    downloaded_at INTEGER,                -- set once, on confirmed decrypt
    burned        INTEGER NOT NULL DEFAULT 0  -- 1 once deleted
  );
  

• No filename, no content-type, nothing plaintext-adjacent stored server side. If the client wants to preserve a filename across the transfer, it goes inside the encrypted payload (e.g. a small JSON header before the file bytes, encrypted along with everything else), not in the database.

The deletion race — why "delete on first byte served" is wrong

The naive version: server deletes the blob as soon as the download request starts (or completes, from the server's own point of view). Two failure modes:

1. Network drops mid-download. The recipient's connection dies at 80%. The server already considers the file "served" and deletes it. The recipient has an unrecoverable partial file and no way to retry — the link is now dead. This is the exact bug that made Firefox Send frustrating in practice.
2. Decrypt fails client-side (corrupted download, browser crash mid- decrypt, wrong key from a mistyped/truncated link). Same outcome: file is gone from the server, but the recipient never actually got it.

The fix: the server serves the blob but does not delete it yet. The client decrypts and verifies (the AEAD tag on the ciphertext gives you integrity for free — if decrypt succeeds, the bytes are correct). Only on successful decrypt does the client send a short authenticated "confirm" request back to the server:

POST /api/drops/<blob-id>/confirm
Authorization: Bearer <confirm-token>   -- returned alongside the download, single-use

The confirm-token is issued at download time, tied to that specific download attempt, and single-use — so a network observer who sees the download request can't independently trigger deletion without also having successfully completed (or at least intercepted) the actual file transfer. On confirm, the server deletes the blob and disk file, sets burned = 1.

If confirm never arrives (dropped connection, closed tab, whatever), the blob stays available for retry — the recipient can just reload the link and try again — right up until the TTL backstop expires it anyway. This trades "guaranteed single-view" for "no silent unrecoverable failures," which is the right tradeoff: the TTL already bounds how long a never-confirmed file survives, so the failure mode of "someone could technically re-download before confirming" is bounded in time and no worse than a slightly-too-generous TTL.

TTL and cleanup

• Default TTL: configurable, a few days seems reasonable for "someone else needs to get around to opening this."
• A cron/interval job (same pattern as npm-statuspage's scheduled checks) sweeps drops where expires_at < now AND burned = 0, deletes the disk file, marks burned.
• Rows are kept after burning (not hard-deleted from SQLite) for basic abuse/debugging visibility, pruned separately on a much longer schedule.

API surface (sketch)

POST   /api/drops                 -- multipart or raw body upload; returns { id, ttl }
GET    /api/drops/:id              -- streams ciphertext; issues a confirm-token
POST   /api/drops/:id/confirm      -- single-use, triggers deletion

No auth on upload initially (matches flit/waste-go's "no accounts" ethos), but needs abuse guardrails since — unlike flit — this one actually costs disk space per upload:

• Max file size cap (needs a number; start conservative, e.g. a few hundred MB, revisit based on actual use).
• Per-IP rate limit on uploads.
• Maybe: require the uploader to have a known waste-go/flit identity (Ed25519 pubkey signs the upload request) to unlock a larger size limit or bypass rate limits — reuses identity infra that already exists rather than building new auth. Optional, not required for v1.

Open questions

• Exact TTL default and max file size — pick numbers once there's a rough sense of real usage, not before.
• Whether to support multi-recipient (same link retrievable by N people before burning) — v1 should be strictly single-retrieval; multi-retrieval is a distinct feature with different deletion semantics, not a variant.
• Whether filename/content-type belongs inside the encrypted envelope (current lean: yes) or should be a separate unencrypted-but-harmless field — leaning toward "inside," since even a filename can leak information the sender didn't intend to share with the server operator.