Every choice, on the record.

The problem

Most “protected” galleries still host the original at a guessable URL. One directory listing, backup file, or misconfigured static route hands over the master — every other layer is then decoration.

We chose

Originals should sit in a directory the web server never serves. The middleware resolves real paths, rejects symlinks that escape, and throws at startup if a masters directory overlaps any public directory declared to Archx; undeclared host mounts remain the operator’s responsibility. The preflight audit mirrors the same rule (a v1.21 red-team find: the audit once said “ok” where startup refused).

Alternatives rejected

• Signed URLs to public files — the file is still fetchable by anyone who obtains or guesses the URL class; revocation is per-URL theatre.
• Obscure filenames — secrecy by entropy of a path leaks via logs, referrers, and screenshots.

Pros

• Whole classes of static-file bugs become irrelevant.
• One auditable read path for every byte that leaves.

Cons / costs

• Requires a server component (or the offline asset builder) — pure static hosting of originals is out.
• Deployments must think about filesystem layout once.

The problem

If full-resolution pixels reach the browser “for fast zoom”, extraction gets full resolution too. Client-side downscaling is a polite request, not a boundary.

We chose

The global maxWidthCap and optional authorize maximum constrain each viewer’s requested width; maxWidthFraction < 1 additionally caps it relative to the master. The server renders the resulting signed width (optionally snapped to canonical buckets), and the token binds that width. If a fraction cap falls below the supported 64 px minimum, mint or redemption is denied rather than rounding the cap up. Smuggling a bigger w at redeem time changes nothing.

Alternatives rejected

• Full-res + CSS scaling — the extracted copy is print-ready.
• Deep-zoom tile streaming (IIIF-style) — excellent pattern, documented as the escalation path, but a much larger surface; deferred deliberately.

Pros

• With maxWidthFraction < 1, even a perfect reconstruction stays below native width.
• Smaller payloads; two-stage derivative caching keeps it cheap.

Cons / costs

• No infinite pinch-zoom into print detail (the viewer offers a lens within the derivative).
• Preview-only width policy is a real product decision the host must make; the default fraction of 1 allows native-width pixels when other caps permit.

The problem

Vendors routinely call pixel shuffling “encryption”. A permutation can be attacked with jigsaw solvers and known-plaintext edges; overselling it leaves buyers with a false threat model.

We chose

Two separately-named layers: a key-seeded tile permutation + mirrors (obfuscation that adds friction to casual tools and raw network inspection), and optional AES-256-GCM over the encoded derivative (authenticated wire confidentiality against parties without the key; the authorized browser receives that key). Docs state plainly which is which.

Alternatives rejected

• Scramble-only marketed as encryption — dishonest and weaker against solvers.
• Encryption-only — protects the wire, but an authorized browser still receives clear pixels; it does not stop in-page extraction or screenshots.

Pros

• Each layer is evaluated against the right attacker.
• Operators can trade CPU for secrecy explicitly.

Cons / costs

• Two mechanisms to configure and explain.
• AES path needs key handling in the client loader.

The problem

With a 32-bit seed, an attacker who captures one scrambled payload can enumerate every seed, unscramble, and score the results — recovering the permutation without the key. Measured: feasible on a laptop.

We chose

New payloads default to plan v2 (128-bit state, warm-up rounds). v1 remains byte-for-byte for decoding legacy assets; no public entry point emits it unless explicitly requested. Try the real algorithm:

Alternatives rejected

• Silently change v1 derivation — orphans every previously built asset.
• Bigger grid instead of bigger seed — permutation size was never the weak point; seed entropy was.

Pros

• Removes the direct 32-bit seed-enumeration weakness; v2 remains deterministic obfuscation, not cryptographic confidentiality.
• Zero migration for existing assets.

Cons / costs

• Two derivations to maintain and test forever (accepted: formats are forever).

The problem

Black padding (v0) identified every edge tile and its flip. Edge replication duplicated rows exactly. Reflection left a palindromic seam (row-diff MAD ≈0.6 vs ≈17 natural). A shifted wrap broke the palindrome but re-phased rows and left a luminance cliff — each generation was measured, then broken by a better statistic.

We chose

One keyed toroidal offset for the whole strip (texture stays coherent), chosen by keyed best-match search; each pad pixel DC-shifted by the ±16px local box-mean delta (no seam cliff), feathered toward the true edge, plus block-constant non-zero keyed noise so pads never equal the edge on flats.

Alternatives rejected

• Black / replicate / reflect / naive wrap — each broken by a named measurement, above.
• Crop-to-grid — throws away delivered pixels; display must stay whole.

Pros

• Strip statistics now resemble ordinary texture continuation.
• Unpredictable without the key; irrelevant with it.

Cons / costs

• The most intricate 200 lines in the scramble path; display never shows them (cropped before presentation), but they must stay bit-frozen.

The problem

General JWT stacks bring algorithm negotiation, remote key fetching, and claim liberalism — the exact surface behind “alg:none”, kid-confusion, and claim-smuggling bugs. This system needs one narrow thing: “viewer V may fetch image I at width W, once, soon.”

We chose

A fixed HMAC construction, a frozen claim allowlist (unknown keys refuse), strict types, TTL and clock-skew windows, and a one-time claim store keyed canonically. v1.21 added canonical-encoding rejection after the red team showed base64url slack bits let four strings carry one MAC. Single-secret verification authenticates before parsing.

Alternatives rejected

• Off-the-shelf JWT — larger parser/alg surface for zero needed features.
• Opaque session ids only — loses stateless width/image binding and forces a lookup per request.

Pros

• Tiny, auditable verifier; timing-safe compare; replay is denied while the spend record is retained; under pressure, evict mode can reopen a narrow window, while strict mode refuses new redemptions.
• Key rotation via keyring kid without alg games.

Cons / costs

• Not interoperable with JWT tooling (by design).
• We own the verifier’s correctness — hence the fuzz battery.

The problem

An attacker who can force churn (many cheap mints) can push legitimate claims out of a bounded store — converting a memory bound into a replay vulnerability, silently.

We chose

Explicit saturation: 'evict' | 'strict'. Library default is evict (availability), the hardened production preset is strict (refuse new redemptions rather than forget a spend). Sizing rule: maxEntries ≥ peak redemptions/sec × TTL × margin.

Alternatives rejected

• Unbounded store — trades a replay bug for an OOM kill switch anyone can press.
• Silent eviction (the industry default) — the failure mode exists but is undocumented and unmeasured.

Pros

• The trade-off is named, configurable, and auditable in config review.
• Strict mode makes saturation a loud 429/503, not a quiet replay.

Cons / costs

• Operators must actually size the store (the widget below helps).
• Strict mode can refuse real users under attack — that is the point, but it is a real cost.

The problem

Bearer tokens leak via logs, screenshots of DevTools, and shared links. One-time use narrows the window but a fast thief can spend first.

We chose

Two strengths: UA binding (friction, trivially spoofable by the thief who copies headers too — labelled as such) and proof-of-possession: the page holds a non-extractable P-256 key; the token carries its JWK thumbprint (jkt); redemption needs a fresh signed proof bound to method, URL, token hash, and a one-time jti.

Alternatives rejected

• IP binding — breaks mobile/NAT users, trivially shared by co-located thieves.
• Cookies-only — the loader is cross-origin friendly; cookies reintroduce CSRF considerations.

Pros

• Stolen token + no private key = 403, even inside the TTL.
• Proof replay itself is one-time-use.

Cons / costs

• Needs WebCrypto in the page; more moving parts; required mode refuses keyless clients outright.
• Script already running in the victim page can still ask the page to sign — stated in the docs, not hidden.

The problem

The most dangerous default in access-control code is the permissive one reached by omission: a forgotten callback, a typo’d option, an exception path that falls through to “serve”.

We chose

Fail-closed server configuration: missing both authorization and an explicit anonymous mode is a startup error; authorize results are normalized strictly (garbage shapes ⇒ deny or clamp, never widen); unknown server-option keys are rejected so allowdOrigins can’t silently no-op; the config audit mirrors every startup refusal it can check statically.

Alternatives rejected

• Permissive demo default — demos become production; the incident writes itself.
• Warnings instead of throws — nobody reads warnings at 2 a.m. during a deploy.

Pros

• Misconfiguration fails loudly at boot, in CI, before traffic.

Cons / costs

• First-run friction: you must write one authorize function (examples provided).

The problem

An <img src> is a public handle: save-as, drag-out, DevTools “open in new tab”, extension harvesters. Blocking context menus stops none of those and annoys paying users.

We chose

Canvas2D/WebGL presentation of reassembled tiles; origin-tainted or black readback for toDataURL/captureStream paths where the platform allows; decoy responses for known extraction probes; print paths degraded. Every guard is an individual flag so sites choose their own friction.

Alternatives rejected

• Right-click blockers as the headline — theatre (see Overview §01).
• EME/DRM — real output protection exists there, but licensing, per-browser CDM deals, and no support for still-image workflows put it outside an open-source JS library. Named honestly as the “choose something else” path.

Pros

• There is no direct image-file handle; authenticated scraping still depends on the host’s mint policy and quotas.
• Pixel-exact 1:1 display is preserved (MAD 0 in browser tests).

Cons / costs

• Screenshots by privileged tooling still work — degraded and attributable, never “prevented”.
• Canvas breaks some a11y/save workflows; hosts keep alt-text duties (documented).

The problem

Any static framebuffer can be captured in one shot. If the complete image never exists in a single presented frame, single captures degrade — and cross-frame averaging fights deliberate pattern choices.

We chose

GPU-shader or pre-rendered alternating frames, configurable pattern (strip/pixel/block), subset size, and target rate (60 Hz default). Fully disable-able; quality impact is measured, not asserted.

Alternatives rejected

• Animated watermark overlays only — composited over a complete static frame; capture then inpaint.
• Always-on interlace — photosensitive users and some displays suffer; hence flags + reduced-motion respect.

Pros

• Single-shot screenshots arrive degraded by construction.
• Cheap: shader mask or two pre-renders, no per-frame CPU.

Cons / costs

• Determined multi-frame capture + averaging partially recovers; camera photos of the screen integrate like the eye does. Both stated plainly.

The problem

A leak arrives cropped, resized, re-compressed, screenshotted, sometimes mirrored. The watermark must be findable blind (no original), keyed (only the owner can read/forge), and cheap enough to embed per-viewer at request time in JavaScript.

We chose

Cell-based spread spectrum with keyed polarity/segment signs, texture-adaptive amplitude (flat cells gentle, textured cells stronger), repetition coding (v1–v3) or BCH (v4, D-13). Detection integrates cell evidence over a luma integral image and searches geometry.

Alternatives rejected

• Neural marks (SynthID/StegaStamp class) — better PSNR (~40 dB class), but need trained encoder/decoder networks; not feasible in a dependency-free JS library, and regeneration attacks kill them too (measured in the literature at ~0–13% decode).
• LSB steganography — dies at the first JPEG re-save.
• DCT-QIM with JND masking — a real path to ~38–41 dB, but it is new embedding physics (a future layout version), not a patch to shipped marks.

Pros

• Runs anywhere JS runs; opt-in embedding adds CPU work that varies with image size and configuration.
• Survives the fixed transform matrix shown below; this is not a screenshot/camera-capture or arbitrary-edit guarantee.

Cons / costs

• 28.6 dB-class distortion on the robust profile is visible under pixel-peeping — the price of the envelope, printed here rather than hidden.
• Diffusion regeneration and 1-bit binarization remain outside the envelope.

The problem

Repetition coding wastes capacity: to fix k erasures you repeat everything. Literature (Frontiers in Physics 2026 ECC comparison) puts BCH + repetition concatenation at the top for watermark extraction robustness, with deterministic correction at low bit reliability.

We chose

Shortened BCH(188,64) over the unchanged v3 cell layout (48-bit fingerprint + keyed MAC-16 inside the codeword), gentler amplitude curve paid for by the coding gain. Layouts 1–3 byte-frozen; v4 is steganography.layoutVersion: 4.

Alternatives rejected

• Make v4 the default anyway — the flip bar (“≥ v3 in every class, better PSNR, FP 0”) was written before measuring; v4 trails by one robust-mode case (0.7-scale photo crops inside a 20 s auto-layout budget). Moving goalposts after results is how benchmarks become marketing.
• LDPC — wants soft LLRs and longer blocks; a 188-bit channel with hard cell votes favours BCH.

Pros

• Guaranteed radius 2e+s ≤ 36; erasure recovery measured at 70/188 bits erased.
• Better PSNR in every class; standard-mode recovery identical (63/99).

Cons / costs

• Needs a v1.20+ detector; slightly behind on small-crop photos under tight time budgets.

The problem

Powerful solvers try thousands of candidate codewords. Against a CRC — or a loose error cap — some noise candidate eventually “validates”, manufacturing a fingerprint from an unmarked image. We measured this happening (a wrong MAC-valid fingerprint at a loose cap) during development.

We chose

MAC-16 inside every codeword version, mismatch caps at 0.30×(observed−64) (≈7σ from noise solves), hard clamp 0.34, agreement/evidence tiers. Legacy CRC codewords remain readable only behind an explicit compatibility flag.

Alternatives rejected

• CRC tags — unkeyed: anyone can forge, noise can pass.
• Wider caps for more recoveries — buys true positives with false accusations; the exchange rate is unacceptable.

Pros

• 0/369 wrong-key positives in the recorded sweep (one-sided 95% upper bound ≈0.81%; not a zero-risk guarantee).
• Forgery requires the stego key, not just the algorithm.

Cons / costs

• Some genuinely-marked but heavily damaged copies correctly return “not found” instead of a guess. That is the intended asymmetry.

The problem

Ground-truth capture on a failing crop: 69 erasures + 13 errors, ~4 of them inside whatever basis you solve from. No single classical algorithm covers that inside a 20-second multi-layout budget.

We chose

Berlekamp-Massey first (fast, guaranteed radius), ML erasure solve (any 64 independent clean bits), OSD-1/2 reprocessing, inline information-set decoding on coherent candidates, then deep ISD over the three best distinct-geometry failures stashed during the search — including one bounded pass when the clock runs out. All randomness input-seeded and deterministic.

Alternatives rejected

• Unbounded inline search — every unmarked suspect would pay seconds of ISD; screening latency explodes (measured).
• Single best-candidate retry — the max-evidence candidate turned out to be the worst ISD case (an error sat inside its top-24 reliability ranks); hence top-3 distinct geometries.

Pros

• Crop recovery that bounded-distance decoding cannot express, inside fixed budgets.
• Unmarked images exit via cheap screens (430 ms at 2400px).

Cons / costs

• The most intricate code in the repo; gate calibration is content-scale dependent and pinned by the bench corpus.

The problem

Attribution in the real world is an investigation: marks get cropped, buyers collude by averaging copies, suspects arrive recompressed by platforms. One signal, however strong, will sometimes be absent — and overstating weak signals is how innocent people get accused.

We chose

Layered, independently-failing evidence: pHash near-duplicate matching, block-sign correlation against a reference, and a collusion assay that ranks candidate recipients by z-score for human review, backed by an issuance log and signed ownership tokens.

Alternatives rejected

• Claiming collusion-proof decoding — Tardos’ bound needs ≈2,180 symbols for c=4 at ε=1e-6; the channel carries 96 bits. Blind collusion-proofing is mathematically out of reach here, so we rank instead of accuse.
• Single-signal verdicts — pHash alone is spoofable; forensic blocks alone are weak.

Pros

• Graceful degradation: absent mark ≠ absent evidence.
• Each layer’s strength is documented in its own terms.

Cons / costs

• Operators must run an actual investigation workflow (we ship the guide, not a magic button).

The problem

Image parsers are a historic CVE farm, and naive multi-pass processing (decode → encode → decode) multiplies both risk and seconds. A 60,000×60,000 IHDR claim should cost a header check, not 14 GB.

We chose

Sharp (peer dependency, operator-patched), chained operations, two-stage derivative construction (cacheable clean base → per-viewer finish), orientation baked only when present, output-pixel budgets that include scramble padding, and controlled error mapping for malformed input.

Alternatives rejected

• Pure-JS codecs (Jimp class) — ~14–40× slower, full-frame heap pressure.
• ImageMagick shell-outs — process-spawn attack surface + full in-memory frames.

Pros

• Streaming keeps RAM flat; budgets make DoS arithmetic boring.
• A recorded 2-vCPU demo-master run measured the 960px catalog q88/effort-2 derivative at ≈46 ms; cold time varies by host, source, format, and cache state. The warm path is cache + tokens.

Cons / costs

• Native dependency to keep patched (documented; audit in CI).
• Full-res 24 MP scrambled encodes are encoder-bound (~13 s mozjpeg) — sizing guidance, not magic.

The problem

“Just use a Map” is how a token endpoint becomes a memory-exhaustion service. Slow-trickle bodies pin handlers; 2,000-item batches pin CPUs; distinct-ID floods pin trackers.

We chose

Capacity-capped structures with interval cleanup (no per-request scans), /64+/48 IPv6 limiter tiers (rotation-resistant), deadline-bounded body reads, batch item caps, slow-callback timeouts, and a distinct-image scrape quota with deny/challenge actions.

Alternatives rejected

• Rely on the host framework’s limits — varies by deployment; the library must be safe behind a bare node:http server (our demo is one).
• Per-IP only rate keys — IPv6 rotation walks straight through (measured; hence tiers).

Pros

• Worst-case memory/connections are arithmetic, not vibes.
• Quotas bound collection and origin work; tune them to the deployment and use shared state when scaling.

Cons / costs

• More knobs; multi-instance deployments should use the Redis store for shared truth (shipped, contract-tested against real Redis in CI).

The problem

Supply-chain risk scales with dependency count, and “supports Node 20” claims often quietly exclude the test tooling. Puppeteer 25 needs Node ≥22.12; Puppeteer 24 would have kept 20 but dragged advisories our CI rejects.

We chose

Measure it, then write it down: pin Puppeteer 24 was evaluated and rejected on its audit chain (basic-ftp/extract-zip). CI encodes the split honestly — library suites on Node 20 and 22, browser suite on 22; .nvmrc says 22 for contributors.

Alternatives rejected

• Lower the audit gate — the gate caught a real same-day advisory during the v1.21 ship run.
• Bundle a crypto/base64 library — platform primitives suffice; every dep is a future advisory.

Pros

• npm audit on the shipped artifact is an empty tree by construction.
• Version claims match what CI actually runs.

Cons / costs

• Contributors on Node 20 can’t run the browser suite locally (CI still covers them).

The problem

Floating-point reassociation, encoder-flag drift, and cache-sharing “improvements” silently change pixels or payloads — invalidating issued marks, cached derivatives, and every prior benchmark.

We chose

Every performance change ships with before/after hash probes over odd sizes and unaligned buffers, exact-arithmetic justifications (integer-exact, order-preserved, or permutation-only), and isolated median timings. New physics ships as a new format version (D-13), never as a silent change.

Alternatives rejected

• “Visually identical” as the bar — watermark decoders read bits, not vibes.
• Benchmark-only validation — end-to-end benches swing ±40% with machine load; hashes don’t.

Pros

• Upgrades are safe for issued assets; regressions are caught by diff, not by users.

Cons / costs

• Some textbook optimizations (separable filters, encoder tweaks) are off-limits; wins must be structural, which is slower to find.

The problem

Displayed pixels cannot be made un-copyable (the analog hole is physics). Tools that promise otherwise train buyers to under-invest in the layers that work — access control, resolution policy, attribution, and response.

We chose

Every claim in the README/site maps to a shipped, runnable measurement; limits get their own page (Threat model) including when to choose EME DRM, C2PA provenance, or neural watermarking services instead. The 0BSD license removes permission friction for a tool whose job is protecting other people’s work.

Alternatives rejected

• Marketing-first claims — they benchmark well in sales decks and fail in incident reports.
• Copyleft (GPL) — would keep the code out of the commercial galleries that need it most.
• Claiming C2PA — provenance is not protection; the 2.4 spec’s conformance program is young and we do not sign manifests. Named, not implied.

Pros

• Operators size their expectations and their other defenses correctly.
• Zero license friction for adoption, forks, and audits.

Cons / costs

• “We can’t stop screenshots” loses some sales to vendors who lie about it. Accepted.