feat(share): add optional password protection for document links

[MerciHanrim]

Problem

A share link carries the whole document in the URL fragment: nodes, edges, labels, saved frames and any imported spreadsheet rows. Anyone who gets the link text can open it. The link text does not stay with the recipient only: it remains in the sender's and the recipient's browser history with the full fragment even though the app clears the address bar, and it sits in the clipboard and in whatever chat or mail carried it.

There is no way today to send a link that is useless to someone who finds it later.

Proposal

Share offers two choices:

• Plain link stays the default and behaves as today.
• Protect with a password encrypts the document before it goes into the link.

This is a separate issue from #297 and depends on it and on #296 (see Dependencies). Implementation needs its own approval; this issue records the contract.

Contract

Creating

• The plain link is the default. Choosing protection is an explicit action.
• A protected link holds only the ciphertext, a random salt and a random IV, under a fixed format prefix. The password, the key and the iteration count are never in the link.
• Loop Studio does not store or transmit the password or the key. The UI does not say "not stored anywhere": a browser or a password manager may offer to save a password, and the product does not hide that.
• The dialog tells the sender to send the password through a different channel than the link.
• The dialog says a lost password cannot be recovered: there is no server and no reset.
• The plain link shows a notice that the document data is in the URL and stays in browser history.
• The outbound size cap applies to the protected payload exactly as it does to a plain one: over the cap is a hard reject, never a truncation.

Opening

• The recipient must enter the password before anything from the shared document is drawn. Nothing derived from the ciphertext (a title, a node count) is shown before that.
• A wrong password, a failed authentication and a damaged ciphertext produce exactly the same error and exactly the same console output.
• A failed or cancelled open leaves the current document and any run in progress untouched, as today.
• After a successful open the existing rules apply: replace confirmation unless the session is the untouched sample, one load, no auto-run.
• Whether the decrypted document is kept in browser storage follows feat(storage): add temporary sessions and shared-browser privacy controls #297: a personal session stores it by the existing policy; a temporary session never persists the decrypted plaintext.

What it does not claim

• It cannot hide the length of the ciphertext or the fact that a link was used.
• It is only as strong as the password. The ciphertext, salt and IV stay in browser history and chat logs, so guesses can be tried offline with no limit on attempts. The UI says so.
• It is not sign-in and not access control. Anyone with the link and the password can open, edit and re-share the document as a plain link.

Decisions

1. Prefix and spec. A protected link is #p1=… under a new spec, loop-share-protected/1. Builds that predate it treat p1= as a foreign fragment and leave it in the address bar, so the link can be opened again after the app updates. loop-share/1 stays frozen; the data it really carries is recorded as an erratum (see Implementation gates).
2. Method. AES-256-GCM with a 16-byte random salt, a 12-byte random IV and a 128-bit authentication tag. The key is derived with PBKDF2-HMAC-SHA-256 at 600,000 iterations. The iteration count is fixed by the p1 format and never read from the link. Web Crypto only; no cryptographic code is written or bundled here. The salt and the IV are always generated with crypto.getRandomValues. The AES key derived by PBKDF2 is created as a non-extractable CryptoKey and is never exported. References: W3C Web Cryptography, OWASP Password Storage.
3. Password rules. 12 to 128 characters. Input is normalised to NFC. Leading and trailing whitespace is not trimmed; it is part of the password. Creating a link has a confirmation field and a show / hide control. Pasting and password managers are not blocked. The dialog suggests a long sentence or several words.
4. Removing the fragment. As soon as the format is confirmed to be p1 and the ciphertext has been copied into memory, the fragment is removed from the address bar. During cancel, failure and retry the ciphertext is held in memory only. After a reload the original link has to be opened again.
5. A broken structure. What can be checked before any cryptographic operation (minimum length for salt, IV and tag) is checked first. A link that is plainly broken shows the general error without asking for a password. A wrong password, a failed authentication and a damaged ciphertext are indistinguishable.
6. Retries. No fixed limit and no lock-out. One operation runs at a time and the button is disabled while it runs. The wording states that offline guessing cannot be prevented.
7. No Web Crypto. When creating, the protection choice is disabled and the reason is shown. When opening a protected link, the app says a supported current browser and HTTPS are required, and in this case the fragment is not removed, so the link can be opened again elsewhere.
8. Password managers. The contract is the sentence in bold above, not "not stored anywhere". The input attributes are set for the creating and the opening purpose and verified in real browsers; the HTML standard offers autofill hints but does not promise control over a save offer. Reference: WHATWG HTML.
9. Order relative to feat(storage): add temporary sessions and shared-browser privacy controls #297. Protected sharing ships only after the feat(storage): add temporary sessions and shared-browser privacy controls #297 main implementation.
10. Opening order. Fixed, below.
11. Authenticated data. The fixed format identifier of loop-share-protected/1 and the payload header are bound as AES-GCM additional authenticated data. Re-labelling a link as another version or algorithm fails authentication. The salt and IV are in the link; the password, the key and the iteration count are not.
12. Desktop and mobile. Encryption and link assembly are not implemented once per surface. One shared encode / decode module and one shared dialog contract; desktop and mobile differ only in the entry point.

Opening order (fixed)

1. the feat(storage): add temporary sessions and shared-browser privacy controls #297 gate
2. p1 structure check
3. ciphertext copied into memory, fragment removed from the address bar
4. password prompt
5. key derivation
6. decrypt and authenticate
7. bounded inflate
8. parse and validate
9. replace confirmation
10. exactly one load
11. the guided tour, after that

Creating runs the other way: serialize, compress, encrypt, base64url. Compression comes before encryption because ciphertext does not compress, and the existing decompression-bomb cap still applies after decryption.

What was measured (read-only, main 3f07c11, Chrome 154, throwaway profiles)

Question	Finding
Web Crypto on a secure origin and on the portable file:// build	available on both; AES-GCM round trip succeeds
Size added by salt, IV and tag	44 bytes, about 59 characters of payload
Largest bundled template as a plain link	6,322 of the 8,192-character cap; about 6,381 protected
PBKDF2-HMAC-SHA-256, 600,000 iterations, one desktop	80 to 88 ms
Wrong password, flipped bit, truncated ciphertext, wrong IV	the same OperationError with no message
Data shorter than the tag	OperationError with a different message, so the message must never be shown or logged
Today's build opening a g2= fragment	the fragment is stripped, a console warning only, nothing visible
Today's build opening a fragment with an unknown non-g prefix	left in the address bar untouched

Dependencies

• feat(storage): add temporary sessions and shared-browser privacy controls #297. Ships only after its main implementation: the gate comes first in the opening order, and the storage rule for the decrypted document is defined there.
• feat(help): in-product What's new - release notes, the versioning rule and the Help menu #296. User-facing, so the PR carries a version bump and a release-note entry.

Implementation gates

• A phone measurement of PBKDF2-HMAC-SHA-256 at 600,000 iterations, before implementation starts.
• The password inputs verified in real browsers for what a browser or password manager offers to save.
• An erratum for loop-share/1 that lists what a plain link really carries: saved frames and imported data are in it today, and the frozen text names only nodes, edges and the run config. The frozen document itself is not rewritten.
• Source text in Korean and English is written first; the other sixteen locales follow, and a missing translation fails the build.

Verification

• Round trip in each build flavour (web, PWA, portable), and a link made in one opened in the others.
• Wrong password, one flipped character, a truncated link, a link with a swapped salt or IV: one identical error, identical console output, the current document and run untouched.
• A link too short to hold salt, IV and tag: the general error, with no password prompt.
• A link re-labelled with another format identifier fails authentication.
• The protected payload obeys the outbound cap and the bounded inflate.
• Nothing from the shared document is in the DOM before a correct password: checked in the accessibility tree, not by screenshot.
• The password and the key are absent from browser storage, from the link, and from the history entry. The ciphertext, salt and IV do remain in the history entry, and the test states that rather than hiding it.
• In a temporary session (feat(storage): add temporary sessions and shared-browser privacy controls #297) the decrypted plaintext is not persisted.
• Without Web Crypto: the choice is disabled with its reason when creating; opening shows the requirement and leaves the fragment in place.
• An older build leaves #p1=… in the address bar, and the same link opens after the update.
• A plain link made by this build still opens in the previous build, and a plain link from the previous build opens here.
• Keyboard and screen-reader path through both dialogs, forced colours, right-to-left.

Out of scope

• Any server: accounts, password reset, link expiry, revocation.
• Encrypting what is kept in browser storage.
• Hiding the ciphertext length or that a link exists.

Not measured

• Browsers other than Chrome 154.
• KDF time on a phone (an implementation gate above).
• Whether a browser offers to save the password.
• Behaviour on a non-secure origin; the absence of Web Crypto there is taken from the standard, not from a measurement.

[MerciHanrim]

Phone measurement of PBKDF2-HMAC-SHA-256 at 600,000 iterations: done on one iPhone 15 Pro; Android is not measured yet. This was the first implementation gate in the issue body.

Method. A single page calls crypto.subtle.deriveKey with PBKDF2-HMAC-SHA-256 and a 16-byte salt, producing a non-extractable AES-GCM 256 key, the same call the p1 format will use. It runs 5 times at each of 100,000, 310,000, 600,000 and 1,000,000 iterations, then times AES-GCM on 6,400 bytes, about the size of the largest bundled template. It runs in a secure context, so Web Crypto was available in every run. During each derivation the page also records the longest gap between animation frames.

Result at 600,000 iterations, median of 5 (range), on an iPhone 15 Pro.

• Normal mode, Safari: 85 ms (84 to 86).
• Normal mode, Chrome for iOS: 85 ms (85 to 86).
• Low Power Mode, Safari: 149 ms (148 to 151).
• Low Power Mode, Chrome for iOS: 151 ms (150 to 155).
• At 1,000,000 iterations the medians were 139 to 140 ms in normal mode and 248 to 250 ms in Low Power Mode.
• The longest frame gap during derivation was 17 ms in normal mode and 34 to 50 ms in Low Power Mode, so the page was not blocked in either mode.
• AES-GCM on 6,400 bytes took 1 to 2 ms to encrypt and 0 ms to decrypt, which is negligible next to the key derivation.
• For reference, the same page on the desktop used for earlier measurements gave 57 to 88 ms at 600,000 iterations.

What this does not show.

• Chrome for iOS runs on WebKit, so the two browsers are one engine on one device, not two independent samples.
• No Android device has been measured, and no low-end or older phone.
• The reported OS version and the exact charging state for each run are being confirmed from the device settings; the browser's user-agent strings disagree with each other, so they are not used.
• Normal-mode runs were taken first and Low Power Mode runs second; an immediate warm re-run was not measured.

Decisions recorded.

• 600,000 iterations is adopted as the candidate and as the security floor: it is the current OWASP figure for PBKDF2-HMAC-SHA-256. That guidance is written for password storage, and it is used here as a conservative baseline for a link that can be attacked offline.
• 1,000,000 iterations is not adopted: no low-end Android data exists to justify it.
• The count is fixed and recorded in the format. There is no per-device calibration, because the device that creates a link is not the device that opens it, and a count raised for a fast sender could lock out a slow recipient.
• An Android check is wanted once: Chrome, 600,000 iterations only, normal and battery saver modes, 5 runs each, with median, maximum and longest frame gap, the exact device model and Android version, and the charging and battery saver state. An older mid-range or low-end phone is more useful than a current flagship.
• Pass criteria for that check: a median up to 500 ms passes; 500 ms to 1 s passes only with a visible in-progress state while encrypting and opening; above 1 s, the iteration count is not lowered and the progress, cancel and error behaviour is reviewed first; a longest frame gap above 100 ms means checking whether the derivation can run in a Worker.
• If no Android device can be found, this does not block the issue: the implementation proceeds at 600,000 iterations and the missing low-end Android check is stated in the report before merge.

This comment records measurements and decisions only. Implementation has not started.

[MerciHanrim]

Implementation gate closed: PBKDF2-HMAC-SHA-256 at 600,000 iterations is confirmed from measurements on an iPhone and an Android phone. This replaces the earlier comment on this issue that listed the iPhone numbers and Android as not yet measured.

Method. One page calls crypto.subtle.deriveKey with PBKDF2-HMAC-SHA-256 and a 16-byte salt, producing a non-extractable AES-GCM 256 key, the same call the p1 format will use. It runs 5 times at each of 100,000, 310,000, 600,000 and 1,000,000 iterations, times AES-GCM on 6,400 bytes (about the size of the largest bundled template), and records the longest gap between animation frames during each derivation. Every run was in a secure context with Web Crypto available.

Result at 600,000 iterations, median of 5 (range).

• iPhone 15 Pro, Safari, normal mode: 85 ms (84 to 86).
• iPhone 15 Pro, Chrome for iOS, normal mode: 85 ms (85 to 86).
• iPhone 15 Pro, Safari, Low Power Mode: 149 ms (148 to 151).
• iPhone 15 Pro, Chrome for iOS, Low Power Mode: 151 ms (150 to 155).
• Nothing Phone (1), Chrome 154, Android 15, normal mode: 101 ms (100 to 105).
• Nothing Phone (1), Chrome 154, Android 15, battery saver: 119 ms (119 to 131).
• The longest frame gap during derivation was 17 ms in normal mode on both phones, 34 to 50 ms in Low Power Mode on the iPhone and 17 ms in battery saver on the Android phone, so no screen freeze was observed in any run.
• At 1,000,000 iterations the medians were 139 to 140 ms on the iPhone and 166 ms on the Android phone in normal mode, and 248 to 250 ms and 196 ms in the saver modes.
• AES-GCM on 6,400 bytes took 0 to 2 ms to encrypt and decrypt, which is negligible next to the key derivation.
• For reference, the same page on the desktop used for earlier measurements gave 57 to 88 ms.

Limits of this evidence.

• The Nothing Phone (1) is one mid-range Android phone, about four years old. This is not a low-end device check and is not described as one.
• The power-saving runs are identified by the file names given when the results were saved, not by anything in the data. The Android battery saver run was a warm run, the second or later run on the same page, and it was taken about three minutes before the normal run, so the two Android conditions are not strictly comparable.
• Chrome for iOS runs on WebKit, so the two iPhone browsers are one engine on one device, not two independent samples.
• Older and lower-end phones and non-Chromium browsers on Android were not measured.
• The exact iOS version and the charging and Low Power Mode state of the iPhone normal-mode runs are unconfirmed; the browser reports conflicting version strings, so none is used. Android reports 15.0.0 and neither Android run was charging.

Decisions recorded.

• 600,000 iterations is adopted, and it matches the current OWASP figure for PBKDF2-HMAC-SHA-256. That guidance is written for password storage and is used here as a conservative baseline for a link that can be attacked offline.
• The count is fixed and recorded in the format. A count above 600,000 and per-device calibration are not adopted, because the device that creates a link is not the device that opens it, and a count raised for a fast sender could lock out a slow recipient.
• No further low-end device measurement is required.
• The dialog shows a visible in-progress state while encrypting and while opening a link, although no screen freeze was seen in these measurements.

This comment records measurements and decisions only. Implementation has not started; the pre-implementation security accounting comes first.

[MerciHanrim]

Pre-implementation security accounting is done, its fourteen open questions are decided, and the one blocking measurement passed. Implementation starts as v0.17.0.

Blocking measurement: the Cloudflare Web Analytics beacon does not transmit the URL fragment. The beacon runs at page load, while a share link's fragment is still in the address bar, so what it reports had to be measured before anything else.

• Method: the deployment's own hash origin, a throwaway browser context per case with no cookies, no storage and service workers blocked; the only request allowed to another origin was the beacon script itself; every reporting request was captured and stopped before it left, in the page and again at the network layer, so nothing was transmitted. A fake marker was used in place of a document, once as #g1=… and once as #p1=….
• Observed: six reporting requests in total (at load, after the storage gate was answered and the app started, and when the page was hidden). In every one the reported location was the origin and path only, including the requests made while the fragment was still in the address bar. The marker, the payload, g1=, p1= and an encoded # prefix appear in none of them.
• The beacon's source agrees: before reporting an address it clears hash and search.
• Limits: a real page unload cannot be read back from the page, so the hide case was observed through dispatched visibilitychange and pagehide events, which is the path the beacon flushes on. One earlier run of the probe stopped on a wrong selector after fetching the beacon script and before writing a result, so the script was fetched from the network twice in all, not once. The measurement is of the beacon version served on 2026-10-04 (2026.9.1); a later version is not covered.
• Consequence: the plain-link disclosure "Nothing is uploaded to a server" stands for the fragment. The beacon does report the page address without the fragment, timings, and a CSS selector for the largest painted element.

Decisions.

#	Question	Decision
1	Byte layout	No header byte. The payload is base64url of a 16-byte salt, a 12-byte IV, the ciphertext and the 16-byte tag, in that order; the p1 prefix is the protocol header and the additional authenticated data is the UTF-8 string loop-share-protected/1
2	Fragment handling	A broken p1 link shows a visible error and the fragment is removed. An unknown p<n> keeps its fragment and shows an update notice
3	Content failure after authentication	A general error, different from the wrong-password error, with no retry
4	Length bounds	The payload is checked to be 60 to 8,192 characters before any password is asked for
5	Password length	Counted in code points after NFC normalisation: 12 to 128 when creating, 1 to 128 when opening. Leading and trailing whitespace is part of the password and is not trimmed
6	Input after a failure	Kept and selected, so it can be retyped or corrected
7	Personal session notice	The opening dialog says that the opened document is kept in this browser
8	Password manager check	On the pull request preview: a throwaway Chrome profile, iPhone Safari and Android Chrome, never with a real password
9	Beacon measurement	Done, above
10	Over the size cap while protecting	An inline error inside the dialog
11	Release	v0.17.0, dated on the day it merges
12	Specification	A new SEMANTICS-P.md; the factual errors of the frozen loop-share/1 document go in a separate SEMANTICS-U-ERRATA.md
13	Crypto call check	A check:share-crypto static check is added
14	Known-answer tests	Compared in both directions with an independent Node implementation; no random-source injection point in product code

Additional contract.

• Creating uses autocomplete="new-password" and opening uses autocomplete="current-password"; what a browser or password manager actually offers is observed on the preview.
• The password is never put in the URL, storage, a store, the clipboard or a log.
• The AES key is non-extractable, with encrypt usage only when creating and decrypt only when opening.
• A valid p1 payload is copied into memory right after the structure check and removed from the address.
• A status line and a guard against double submission are present during key derivation.
• The plain g1 format and its behaviour do not change.
• One pull request, shipped atomically, with staged commits.

Measured for the accounting (main 3796589, v0.16.0).

• The shipped build leaves #p1=…, #p1 and #p2=… in the address bar with no console output, so a build that predates this feature never consumes a protected link. Its storage gate does not yet recognise a p1 link as a waiting share link; that is part of this work.
• Every bundled template in every shipped language fits the 8,192-character cap as a protected link. The largest is the MMO progression template in Thai: 7,000 characters plain and 7,059 protected. With the pure JavaScript compressor used where CompressionStream is missing, the largest is 7,983. A template grows by up to about 11 percent across languages.
• The layout above produces identical bytes from Node's crypto and from Web Crypto, each opens the other's output, and the overhead is 44 bytes.
• A wrong password, different authenticated data, a changed salt, IV or ciphertext bit and a one-byte truncation all fail with the same error and the same message; data shorter than the tag fails with a different message, so the browser's message is never shown or logged.

Not verified: what a password manager offers, Web Crypto on file:// outside Chrome, a real screen reader, and low-end Android devices.

[MerciHanrim]

Shipped in #315 (938aae3, the squash of the approved head 5ee4272), version 0.17.0, release date 2026-10-04. The merge is the production deploy. Production serves the same index.html, entry bundle and app chunk as the 938aae3 deployment, and the app chunk embeds v0.17.0 · build 938aae3, the format identifier loop-share-protected/1 and the 0.17.0 release note.

What shipped. The share dialog has one more choice, Protect with a password, unticked by default; a plain link is created and opened as before. A protected link is #p1= plus base64url of salt, IV, ciphertext and tag: the zlib-deflated Graph JSON under AES-256-GCM with a key from PBKDF2-HMAC-SHA-256 at 600,000 iterations, the format identifier bound as additional authenticated data, Web Crypto only. Opening checks the structure before any password is asked for, removes the fragment once the sealed bytes are in memory, and draws nothing of the shared diagram before a correct password. The contract is docs/specs/SEMANTICS-P.md; what a plain link really carries is recorded in docs/specs/SEMANTICS-U-ERRATA.md. The phone's share result sheet also gained a Copy button.

CI. At the approved head 5ee4272: 1,869 end-to-end tests, the five shards an exact partition of the listing, none failed, none retried, the same 7 conditional skips, plus checks, the production bundle, the PWA bundle and the Cloudflare preview, all on the first attempt. On main after the merge every job passed on the first attempt of the run; one test, playback-visual.spec.ts "travel · L0 elision" in the phone project, failed its first attempt because the toolbar was not visible within 8 seconds and passed on the retry. The same tree had passed that test on its first attempt in the pull request run, and the test does not touch share links.

Verified on the production deployment's own hash origin, each item in a throwaway profile, with every request to another origin blocked.

• A plain link is made, opens in another profile, and its fragment is removed.
• A protected link is made with the link, not the password, on the clipboard; it opens with the password; the fragment is gone before the password is asked for.
• Before the password, the shared diagram's labels are neither on the page nor in storage.
• A wrong password and a link with one altered character give the same text and the same console line; the current diagram stays, and what was typed stays selected.
• A broken link shows a notice with no password field and loses its fragment; a link of an unknown version shows a notice and keeps it.
• Over the size cap while protecting is said inside the dialog, with no alert and no link.
• A personal session keeps the opened diagram in browser storage. Behind the storage gate, a temporary session opens the link and leaves no storage key at all.
• The password is in no URL, storage value, cookie, console line or clipboard write.
• On a phone-sized screen the result sheet's button copies the same link again after the clipboard was overwritten.

Measured before implementation. Key derivation takes 85 ms on an iPhone 15 Pro (149 to 151 ms in Low Power Mode) and 101 ms on a Nothing Phone (1) (119 ms in battery saver). The Cloudflare Web Analytics beacon does not transmit the URL fragment. Every bundled template in every shipped language fits the size cap as a protected link. The build before this one leaves #p1=… in the address bar untouched.

Real browsers, with throwaway passwords and no offer accepted. Desktop Chrome 154 with a throwaway profile shows its save-password icon in the address bar after a link is created, no popup, and saves nothing by itself. On an iPhone 15 Pro in Safari an offer appeared and creating and opening worked. On a Nothing Phone (1) in Chrome no offer was reported and creating and opening worked. iPhone Safari refuses the automatic copy that follows key derivation; the sheet says so and its Copy button copies the link.

Limits.

• Which kind of offer iPhone Safari made was not recorded, and a signed-in Chrome profile, other password managers and a second opening on the phones were not observed.
• The guard that keeps an Enter inside an input-method composition from submitting is pinned by tests that dispatch the composition events by hand; no real input method was tested.
• Web Crypto on file:// outside Chromium, a real screen reader and a low-end phone were not tested.
• The sixteen translations other than English and Korean were written in this change and have had no native review.
• On iPhone Safari the link is not copied automatically after a password is set; one press of the button is needed. Keeping the link after the result sheet is closed was left out of scope.
• It cannot hide the length of the ciphertext or that a link was used, and the link is only as strong as its password: the ciphertext, salt and IV stay in browser history and chat logs, so guessing offline has no limit.