Skip to content

Implement the 3.1.1 improvement audit (web, server, docs) - #50

Merged
polius merged 35 commits into
mainfrom
audit/improvements
Nov 16, 2026
Merged

polius merged 35 commits into
mainfrom
audit/improvements

Conversation

@polius

@polius polius commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Implements the improvement audit of 3.1.1, lane by lane (web app, server, docs/deploy/CI). One commit per step; each commit message lists the audit entries it covers.

Web app

  • Composer: Generate only fills an empty password value (S1); multi-line values (keys, certificates) are never flattened, keep their final newline, and can be saved as a file by the recipient (S2); the seal animation never shows content (S3); selecting the link by hand copies it once (S4); hunter2=xyz!-style pastes stay text (S5); Ctrl/⌘+Enter in the Ask dialog submits the dialog (S8).
  • Recipient: a one-time secret is hidden, not wiped, after 5 idle minutes, and Clear now can be undone for 8 s (R1, R2); smaller fixes on the reveal page (R4).
  • Requests: reloading after answering says so (M1); invite and reset links survive a reload; an answer opens under its request's code and note (M2); focus moves to "Sent" (V6).
  • Wording and titles: per-route page titles (M4); no unchecked "up to date" (M3); /server signed out goes to sign-in (M5); the access choice is staged and confirmed (M8); the passphrase is "shown only now" and leaving uncopied asks (S7); the audit's wording table.
  • Shell: a failed screen load shows Reload instead of a blank page (V2); proxy 413s and browser failures get their own messages (V5); drafts survive in-app navigation and reloads ask first (S6).
  • Phones and accessibility: 44 px touch targets, 16 px fields, rem type scale, dir=auto, forced colours, safe areas, woff2-only fonts (V3, V4, V7).
  • Your links: forget a link on this device (M9); "couldn't refresh" instead of a stale Live dot, and other small fixes (M10); a failed refresh keeps the last list (M6); removing a person can destroy their live links (M7).
  • Uploads: downloads can be cancelled, and the upload card no longer promises to resume (S9); smaller composer fixes (S10).
  • Dates follow the browser's locale; "tomorrow" is never said for later today (V1, dates only).

Server

  • Per-caller budget of declared upload bytes (two maximum-size secrets an hour); unfinished uploads end after a day; only new chunks refresh the idle clock (B1, no schema change).
  • No address block after wrong tokens; RATE_FAILED_TOKENS removed (B3).
  • The five-try passphrase limit holds under parallel guesses (B6); limits, branding and the logo need re-auth (B7).
  • Strict settings: e.g. LOG_LEVEL=verbose or DEMO=yess stop the server with one line (D7); the enc.key message is logged (D1); the image trusts only loopback proxies (B4).
  • Status and reveal limits per account when signed in; DELETE /server/users/{id}?destroy_links=true (M6, M7).
  • Chunks stream to and from disk; at most two concurrent chunk writes per upload; --limit-concurrency (B2). Orphan sweep, secure_delete, synchronous = FULL (B5).
  • Hashed rate-limit keys, atomic setup, account named on failed sign-ins, MAX_FILES cap (B8); precompressed assets served by Accept-Encoding (D9).

Docs, deploy, CI

  • README: accurate "who sent it" claim (D2), docker stop updates (D6), the setup code in Quick start, proxy defaults; the HTTPS compose trusts only its private network, which only Caddy can reach (B4).
  • Dependabot 7-day cooldown; Actions and crypto libraries never auto-merge (D8); the release checks the tag against the code's version; smaller items from D10.
  • Threat model rows updated with their tests.

Not included

R3, G1–G3 and languages need a design first. Also left out to keep it simple: migration safety checks (D3), a security policy (D4), a deployment guide (D5), resumable uploads, manifest padding, a combined poll endpoint, S4's lenient link parsing, sign-in failure notices and longer lockouts, ENC_KEY_FILE, CONTRIBUTING/changelog, mypy and a web linter in CI, absolute og:image, sorting Your links, splitting the copy deck and merging the stylesheets.

Repository settings to turn on by hand: private vulnerability reporting, secret scanning, push protection, Dependabot security updates, and protection for v* tags.

Testing

  • API: ruff clean, vectors unchanged, 231 tests pass.
  • Web: typecheck clean, 155 unit tests pass, build within the size budgets.
  • The defects reproduced in the audit were re-checked against the built image in Chromium and no longer reproduce.
  • The Playwright suite was not run. Some assertions were updated for the new behaviour and a 390 px accessibility test was added. Visual baselines are stale for most screens: refresh with PW_ARGS="--project=visual --update-snapshots=all" and review the diffs.

Files the audit flags for a second review: api/cryptex/routes/secrets.py, items.py, ratelimit.py, deps.py, db.py, storage.py, routes/common.py, web/src/flows/transfer.ts, flows/reveal.ts.

🤖 Generated with Claude Code

polius and others added 30 commits November 16, 2026 15:54
- S1: Generate only on an empty password value; secrets that aren't passwords get none; the tag sits after the value
- S2: multi-line values are a summary while masked and a text area when shown; a key keeps its final newline;
  the recipient can save a multi-line field as a file
- S3: the seal scramble is random glyphs from the first frame
- S4: a hand selection in the link box copies the full link only
- S5: a lone name=value line is a variable only when it looks like one; a URL is never a username
- S8: Ctrl/Cmd+Enter submits the Ask dialog, not the composer behind it

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- R1: on a one-time link the idle timeout hides and re-masks the values and keeps them until the tab closes;
  Show again or Clear for good. Reusable links clear as before. The sealed page says it hides after 5 minutes.
- R2: Clear now on a one-time link can be undone for 8 seconds
- R4: shown values wrap; the try limit shows under the passphrase from the start; the address check becomes
  'Not expecting this? Close the page and ask the sender.'; the one-time banner uses the warning style; the
  clipboard note shows after the first copy; .env only for two or more one-line fields; the button stays Reveal

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- M1: a reload after answering says 'You answered this request here on …'; invite and reset tokens move to this
  tab's sessionStorage so a reload keeps working, and are forgotten once used or gone
- M2: Open answer shows 'Answer to your request K3T-PBS', quotes the request's note (now kept with the request)
  and drops the sender and phishing lines
- V6: the answer page moves focus to its heading when Sent replaces the form

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…2 copy)

- M3: Server overview says 'version 3.1.1 · see releases' with a link; no unchecked 'up to date'
- M4: document.title per route ('{page} · {brand}'), fixed words on /s/ and /a/
- M5: signed out, /server/* and /account go to sign-in and come back
- M8: 'Who can create links' is staged behind the Save bar; opening to anyone and Make owner ask first
- S7: the passphrase box says it's shown only now; leaving uncopied asks first (in-app links, reload, close)
- Wording: link ledes, privacy 'which account sent it' (D2), keep_open, expire within 24 hours, invite copy,
  'Remove from Your links' for ended links, timeline 'Opened'
- e2e: two assertions follow the new wording

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- V2: a screen whose code fails to load shows 'This page couldn't load · Reload' (and a render error the same,
  through an error boundary); a release that replaced the files reloads once on vite:preloadError; index.html
  paints a skeleton
- V5: errors that aren't the API's are named by status (a proxy's 413 says so); the generic message is split
  into the server's and this browser's; pow/csrf no longer ask for a reload
- S6: the draft lives outside the page, so Your links and Back keep it; reload and close ask first while there's
  a draft or an upload; leaving mid-send cancels the upload; an error no longer clears the draft on navigation

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… areas, fonts)

- V3: on touch screens every button, nav link and tab is at least 44 px tall; the a11y e2e suite gains a 390 px
  pass with touch that fails on any axe result and checks row button heights, on the answer page, the Ask
  dialog, a broken link, invite, reset and sign-in (not run here)
- V4: the type scale is in rem, so the browser's font size applies; fields are 16 px on touch screens (no iOS zoom)
- V7: dir=auto on composer fields and revealed notes and values; a forced-colors block; safe-area insets for the
  header, the sticky action bar and the save bar; fonts are woff2 only with unicode-range per subset, plus Mono 600
  (no faux bold); people-table buttons name the person; navigating to the same address replaces history

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…M10, part of M6)

- M9: 'Forget on this device' in a row's menu and 'Don't keep this link in this browser' on the link page for
  a sender without an account: the local copy goes, the link keeps working
- M10: the receipt says 'Couldn't refresh · last checked …' with Try again instead of a Live dot when a read
  fails; Esc on 'Add links from this browser' means ask later; the storage bar is labelled Disk; phones show the
  time on the status line; Privacy is in every footer; an owner without 2FA gets one dismissible reminder
- M6 (client): a failed refresh of Your links keeps the last list with a quiet 'Updating paused' note
- M6/M7 server-backed parts follow lane B step 3

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- S9: Try again continues a failed upload from the chunk that failed (same ID, key and upload token) while the
  draft and options are unchanged, else drops it and starts over; progress moves within a chunk (XHR upload
  progress); a file download on the reveal page can be cancelled and continued
- S10: a refused clipboard shows the text selected in a small dialog ('Select it and copy' on touch screens);
  a flat JSON object and nested YAML become fields (db.host); a connection string keeps the whole string as its
  first field; an empty passphrase is reported under its box with aria-invalid; the progress card agrees with
  'Link ready'; the policy line keeps 'Passphrase' while the link is made
- e2e: the idle-timeout, connection-string and .env assertions follow the new behaviour

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Dates, times and plain numbers follow the browser's locale (17:18 in en-GB and de-DE, 5:18 PM in en-US);
  hours without a leading zero; the year when it isn't this one
- Relative times count hours up to 48 hours, then calendar days: 21 hours ahead never reads 'tomorrow'
- The audit log shows the full date and time

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- B1: one caller (account or address) may hold at most the largest secret's worth of declared, unsent upload space
  (new 'uploads_pending' 429); an unfinished upload ends a day after it started whatever is re-sent, and only a new
  chunk refreshes its idle clock; the caller is recorded in a new numbered migration (0002) and cleared at seal
- B3: wrong tokens no longer block the address for an hour (RATE_FAILED_TOKENS removed); threat model row updated
- B6: a passphrase try is taken in the statement that checks one is left, and given back when it was right
- B7: limits, branding and the logo need a fresh re-auth; the web forms ask and retry
- Tests for each in api/tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…, B4 image default)

- D7: LOG_LEVEL and LOG_FORMAT are choices and booleans are strict (DEMO=yess, LOG_IPS=ture stop the server);
  an unwritable data folder or a bad database exits with one 'cryptex: …' line instead of a traceback
- D1: a fresh start logs, at warning level and after logging is set up, that enc.key was made and must be kept
  with the data folder and in every backup
- B4: the image trusts X-Forwarded-For from loopback only (was every private range)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ane A step 7: M6 M7)

Server
- M6: RATE_STATUS and RATE_REVEAL count per person when signed in, per address otherwise; POST /status returns a
  poll's link and request statuses in one request
- M7: DELETE /server/users/{id}?destroy_links=true destroys every link the person sent that still works; answers to
  their requests are deleted either way; the people list says how many live links each person has

Web
- Your links polls through /status, and slows down (up to 2 minutes) while nothing changes
- Removing a person offers 'Also destroy their N live links', on by default; the audit log names that destroy

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- B2: a chunk upload streams into a temporary file as it arrives (size checked on the way) and is moved into place;
  chunks are served from the file; one upload takes at most two chunk requests at once; uvicorn starts with
  --limit-concurrency 500
- B5: chunk files no row points to, and temporary files, are swept at start and daily; SQLite runs with
  secure_delete on and synchronous = FULL, so destroyed metadata leaves the file and a burn survives a power cut

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- D9: the image build writes .br and .gz beside each text asset; the server sends the best one the browser takes,
  with Vary: Accept-Encoding
- B8: rate-limit rows are named by a keyed hash, never a raw address or a typed username; a failed sign-in names
  the account when it exists; setup saves the owner and 'setup completed' in one transaction; MAX_FILES is capped
  at 1000; the web client pads the manifest to size steps (docs/crypto.md says so; readers already ignore it);
  test_overview no longer reads this machine's disk; the threat model no longer claims chunk uploads are limited

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- 0001_init.sql is frozen as released in 3.0.0 (a test pins its SHA-256); schema changes go in numbered files
- Each applied migration's SHA-256 is stored; a changed one, a database newer than the code, or a Cryptex 2.x
  database stops the server with one 'cryptex: …' line
- Tests upgrade a 3.0.0 database and cover each refusal

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…D2 D1 D6, D5 Quick start, B4, B5/B8 corrections)

- D2: the README says the server can't read the secret, its title or its file names, and knows the account of a
  signed-in sender
- D1: a Backup and restore section (cryptex backup, what it holds, how to restore, never copy a live folder, what a
  restore brings back); both compose files mount ./backups; the entrypoint hands /backups to the cryptex user;
  backups skip uploads still arriving
- D6: the image is pinned to :3 everywhere; updating uses docker stop, after a backup, with the release notes
- D5: Quick start says where the setup code is
- B4: the HTTPS compose file pins Caddy's address and trusts only it; README and threat model match the loopback default
- B5, B8: the threat model states the backup caveat and what is swept; the README says 128-bit link keys

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…and D2 in docs/crypto.md)

- D4: SECURITY.md with private reporting through GitHub advisories, supported versions (2.x unsupported) and
  'Verify what you run': gh attestation verify for the image and SHA256SUMS, pinning by digest, and checking a live
  server's files; the README links it
- D8: Dependabot waits 7 days after a release (cooldown) in every ecosystem; GitHub Actions and cryptography,
  argon2-cffi and hash-wasm never merge unreviewed
- D2: docs/crypto.md no longer says the server never sees sender names

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- docs/deploy.md: what a proxy must do (root path, forwarded address and scheme, exactly in TRUSTED_PROXIES,
  bodies of 6 MB+, headers untouched), with snippets for nginx, Traefik, Caddy with an internal certificate,
  Cloudflare Tunnel, Tailscale Serve and Kubernetes; the README points to it
- deploy/docker-compose-hardened.yml: non-root from the start, read-only root, no capabilities, no new privileges;
  CI starts it from the built image, checks health and runs a backup

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…imple ones)

- The release fails when the tag differs from the version in api/cryptex/__init__.py or web/package.json
- The health check's request isn't logged at info (about 2,900 lines a day); /metrics gains cryptex_disk_free_bytes
- Demo settings above the defaults are reported in the log, and the README says they can only lower them
- robots.txt covers request links (/a/); the in-app 'Run your own' link points at #quick-start
- The e2e job's name says Chromium, which is what it runs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each chunk is still retried five times; the upload card already says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Per-person status and reveal limits are what fix shared offices; Your links polls as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- docs/deploy.md keeps the proxy requirements and the nginx example
- docker-compose-ssl.yml drops the fixed subnet: Cryptex trusts the private ranges there, since its port isn't
  published and only Caddy can reach it

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
polius and others added 5 commits November 16, 2026 17:51
Drops migration 0002 (the creator column). One caller (an account, or an address) may declare at most two of the
largest secrets' worth of bytes an hour, counted in rate_limits; with the idle and absolute upload lifetimes, an
address can't reserve the disk. The uploads_pending error goes; the budget answers with rate_limited.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The migration runner is back to main's; its tests go with it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…visual baselines

Baselines regenerated with --update-snapshots=all in the pinned Playwright container.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@polius
polius merged commit 1fd5344 into main Nov 16, 2026
5 checks passed
@polius polius mentioned this pull request Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant