obsidian-livesync/docs/design_docs/time_bound_setup_uri.md

date, commonlib-version, feasibility-probe-version, self-hosted-livesync-version, status

date	commonlib-version	feasibility-probe-version	self-hosted-livesync-version	status
2026-09-28	0.1.33	0.1.27	1.0.32	implementing

Time-bound Setup URIs

Purpose and status

Offer two modes when generating a Setup URI:

• Ephemeral, selected by default, derives an effective passphrase from the entered passphrase and the current fixed time window.
• Persistent uses the entered passphrase and the existing URI format unchanged. It also serves as the compatibility mode for older readers.

The generation mode choice shows the exact time until which an Ephemeral URI can be opened through the ordinary reader. Import still requires only the URI and the entered passphrase. Neither the mode nor a timestamp is stored in the URI.

The design is technically feasible with the existing encryption primitives. An executable protocol probe passes 22 cases against Commonlib 0.1.27 and octagonal-wheels 0.1.54. The implementation was first published as Commonlib 0.1.32 on the npm next tag. LiveSync now pins Commonlib 0.1.33 from that tag in its npm dependency and independent Deno tool imports. A mobile performance bound remains outstanding.

This document records the proposed key derivation and integration contract. The companion probe demonstrates them without changing an application entry point.

Scope

The first version offers Ephemeral and Persistent only. Ephemeral uses one fixed seven-day window shared by every implementation. Arbitrary start dates, custom end dates, selectable window lengths, and rolling seven-day lifetimes are outside this version.

Keep the current settings filtering, remote profiles, main and P2P selections, and short/full export variants. Time binding affects opening the exported settings; it does not alter Vault encryption, remote credentials, replication, or settings already imported by another device.

The existing settingsQR format and QR aggregator are separate sharing paths. They remain outside this design and must not be presented as time-bound.

Time window

Use Unix milliseconds and the following protocol constants:

windowMilliseconds = 604800000
windowNumber = floor(nowMilliseconds / windowMilliseconds)
windowStart = windowNumber * windowMilliseconds
usableUntil = (windowNumber + 1) * windowMilliseconds

The anchor is the Unix epoch, 1970-01-01T00:00:00Z. Consequently, boundaries fall on Thursdays at 00:00 UTC. This is a protocol convention, independent of the device's locale, time zone, daylight-saving rules, and calendar week. The anchor and window length are part of the derivation profile. Changing them requires an explicit compatibility design; there is no visible version field from which an importer can discover a different time condition.

For example, a URI generated at 2026-09-28T12:00:00Z belongs to the window [2026-09-24T00:00:00Z, 2026-10-01T00:00:00Z). Ordinary import rejects it at the end instant. Generating it one second before that instant leaves one second of availability. The UI must not describe this as seven days from generation.

Use safe, non-negative integer timestamps without 32-bit coercion. The reader tries only its current window. There is no previous-window allowance, future-window search, modulo wraparound, or grace period. Devices whose clocks fall on different sides of a boundary can disagree; local date formatting does not affect the calculation.

Passphrase derivation and encryption

The time factor follows the counter construction used by TOTP, RFC 6238 section 4.2. This is a time-bound encryption format, not a TOTP authentication protocol: there is no six-digit code, trusted validation server, or single-use state.

Reuse Commonlib's current encryptString and decryptString path. It uses octagonal-wheels' salted PBKDF2/HKDF and AES-GCM implementation. Persistent passes the entered passphrase directly to that path. Only Ephemeral applies a full-length transformation:

if mode == "persistent":
    effectivePassphrase = enteredPassphrase
else:
    hmacKey = SHA-256(UTF-8(enteredPassphrase))
    context = JSON.stringify([
        "livesync/setup-uri",
        "tb1",
        "ephemeral",
        windowNumber
    ])
    effectivePassphrase = lowercaseHex(HMAC-SHA-256(hmacKey, UTF-8(context)))
encryptedSettings = encryptString(preparedSettingsJSON, effectivePassphrase)

The mode strings are exactly ephemeral and persistent. JSON encoding, field order, lowercase hexadecimal, and the domain/profile strings are part of the proposed Ephemeral derivation. tb1 is an internal derivation identifier; it is not a URI prefix or stored field. Persistent applies no new transformation.

The initial SHA-256 provides a fixed-length HMAC key, including for an empty low-level input. It does not replace password stretching: the existing encryption function still performs PBKDF2. Do not trim or normalise the entered passphrase within this transformation. Existing host requirements for a non-empty passphrase remain in force; this design adds no new password policy.

At the assessed dependency versions, the encryption path uses PBKDF2-SHA-256 with 310,000 iterations, HKDF-SHA-256, and AES-256-GCM with a 128-bit tag. Its %$ payload includes the material needed for decryption. The PBKDF2 salt may be reused within a session; the IV and HKDF salt are generated for each encryption. Retain these existing semantics rather than claiming a new per-URI PBKDF2 salt or introducing another encryption implementation.

For the synthetic passphrase test-passphrase, fixed derivation vectors are:

context: ["livesync/setup-uri","tb1","ephemeral",1234]
effectivePassphrase: b39361c51f0b7bd835554db1dffbc9a540fb30789aa62bf53e39e07d1073013b

mode: persistent
effectivePassphrase: test-passphrase

The probe checks the Ephemeral Web Crypto output against a value calculated separately through Node's SHA-256 and HMAC interface, and checks that Persistent retains the exact input. Encryption remains randomised; these vectors specify the effective passphrase, not the complete URI.

This composition needs Commonlib changes but no new cryptographic dependency or remote service. The prototype verifies interoperability with the existing encryption path; it is not an independent cryptographic audit.

URI format and decoding

Keep the existing URI prefix and encrypted representation without a new marker:

obsidian://setuplivesync?settings=<encodeURIComponent(encryptedSettings)>

Both modes use the existing %$ encrypted representation. There is no mode flag, timestamp, window number, duration, derivation-version marker, or separate query parameter. For identical prepared settings, both modes have the same binary layout and ciphertext length. Percent-encoded text length may vary with the random ciphertext; equal URI text length is not a requirement.

Persistent delegates to the existing encoder with the entered passphrase and the same settings-filtering options. A new marker or a transformed Persistent passphrase would defeat older readers. Ephemeral uses the same external format to preserve mode hiding. The protocol handler continues to reconstruct the URI from the existing settings query value.

For a %$ payload, including an existing URI made before this feature, the updated decoder:

1. validates the envelope and captures the current window;
2. derives the Ephemeral candidate for that window and takes the entered passphrase unchanged as the Persistent candidate;
3. attempts authenticated decryption with both candidates, without returning early after the first success;
4. checks the current window again before returning an Ephemeral result; and
5. returns settings only if exactly one candidate is accepted.

Keep expected candidate failures internal. Two failed candidates produce one generic opening failure. A wrong passphrase, an out-of-window Ephemeral URI, and damaged authenticated ciphertext do not receive different user messages. There is no information from which to report a definite historical end time for an unreadable URI.

The raw-passphrase attempt is an intentional part of the two-candidate reader. An Ephemeral URI from another window still fails both candidates with the entered passphrase; this attempt does not remove its time condition. There is no plaintext recovery, time-window search, or additional key fallback.

Older encryption representations other than %$ retain their existing legacy-only decoder and passphrase handling. Unsupported prefixes remain unsupported. Malformed %$ payloads fail authentication with both candidates. Bound time-bound candidate work to two attempts; the existing decoder continues to own any historical encryption-format compatibility trials.

Because the derivation profile is not stored, an older reader cannot identify an Ephemeral URI and give an upgrade-specific error. It reports a decryption failure. A future change to the Ephemeral profile must define its bounded candidate policy explicitly; the reader must not infer arbitrary profiles or scan them without a limit.

Two trials make the amount of cryptographic work predictable, but do not constitute a constant-time implementation. This design does not claim to hide the mode from a caller who can instrument the decoder and knows the passphrase.

Generation and import interaction

Keep the existing passphrase prompt. After it, use the existing confirmation dialogue to choose Time-bound (the Ephemeral encoder mode) or Compatible (the Persistent encoder mode). Select Time-bound by default, show its exact absolute end in the device's local time zone with its time-zone name or UTC offset, and explain that this is the end of a fixed UTC window rather than seven days from generation. Compatible has no time condition and remains readable by older clients. No synchronised setting or permanent Vault preference is needed.

Commonlib exposes the current window end for this pre-generation choice. Compare it with the usableUntil returned alongside the generated URI. If the window changed during selection or encryption, show a fresh choice with the new end before opening the existing copy dialogue. Persistent generation does not consult the clock and returns null for usableUntil.

The existing copy dialogue does not monitor the clock. If it stays open across the boundary, it can still display and copy a URI whose window has ended; the reader will reject that URI. The end time was shown at the mode choice. The copy dialogue does not claim a rolling week or silently switch to Compatible.

Import requires no mode selector or date input. Recheck the window at the end of decryption so that an Ephemeral operation crossing the boundary does not return settings. Once settings have been returned successfully, subsequent confirmation, setup, and synchronisation do not remain time-bound: the URI has already been opened. This is an import boundary, not remote revocation.

Security and privacy boundary

The hidden mode is an external-format property. A passive holder of the URI does not receive an explicit time condition or Persistent marker. Randomised encryption and the unchanged prepared settings representation avoid adding a mode-dependent field or length difference.

The clock and reader are controlled by the receiving device. Anyone with the correct passphrase can reproduce historical candidates, modify the reader, or change the supplied clock. Including Persistent adds one possible candidate; it does not make a small calendar search cryptographically hard. Time binding adds no independent secret and is not a substitute for a strong Setup URI passphrase.

The same URI can be opened repeatedly within its window. A replayed clock earlier than generation, but inside that same window, also derives the same key. Successfully copied settings and remote credentials remain usable after the window ends, subject to their own remote policies.

No URI, entered or effective passphrase, derived key, decrypted settings, or candidate-specific authentication result should enter ordinary logs or reports. The generation screen necessarily reveals the selected mode and end time to its user; hiding information in the URI does not hide that screen or a separately shared message.

Ownership and compatibility

Commonlib owns preparation of exported settings, the time-window calculation, passphrase derivation, format parsing, and dual-candidate decoding. Make these changes in the Commonlib repository. LiveSync must consume a validated packed artefact and then an exact reviewed package version, following the Commonlib dependency workflow.

Preserve the existing positional encoder API. Its third and fourth arguments already mean properties to remove and whether to omit default values. Add a separate encoder, provisionally encodeTimeBoundSetupURI, with an options object containing the mode and the existing export options. Its result is:

type TimeBoundSetupURIResult = {
    uri: string;
    usableUntil: number | null;
};

The new encoder defaults to Ephemeral. Preserve the old encoder's legacy behaviour for callers which have not migrated. Extend decodeSettingsFromSetupURI to try both candidates for %$ while retaining its settings return contract and historical format handling. Persistent generation through the new API delegates to the old encoder. Time injection belongs in internal test seams, not an import option exposed to users.

Surface	Required work
Obsidian generation	Reuse the passphrase and copy dialogues, add a mode choice with the exact current window end, and use the new encoder for all three copy variants and the copy event. Preserve each variant's export filters.
Obsidian import	Consume the updated decoder and retain one authentication failure message. The existing prefix check indicates URI shape, not successful authentication.
Protocol handler	Keep the existing settings reconstruction; test encoded delimiters for both modes.
CLI setup	Consume the updated decoder and leave settings unchanged after any rejection.
WebPeer generator	Choose a mode explicitly and return availability to its result UI; keep Ephemeral as the default.
Setup utility	Add an explicit mode input, default to Ephemeral, and return/print the end time. Persistent is an explicit choice for durable provisioning output.
Setup utility package facade	Update its independent Commonlib pin and associated lockfiles; updating the root npm dependency alone is insufficient.

The Fly.io wrapper delegates to the setup utility and should inherit the same contract. All maintained generators must migrate explicitly before this feature is described as the default across applications. Non-interactive automation which needs a durable URI must select Persistent.

WebPeer hides an Ephemeral URI and disables its copy and additional-device actions after the window ends. Its connection monitor remains available for a device that imported the URI before the end; opening the URI does not expire the imported P2P credentials.

URI	Updated reader	Reader without time-bound support
Legacy	Existing behaviour, without a time condition	Existing behaviour
New Ephemeral	Opens in the current window with the correct passphrase	Rejected
New Persistent	Opens with the correct passphrase	Existing behaviour

The assessed, unchanged Commonlib 0.1.27 decoder opens Persistent with the entered passphrase and rejects Ephemeral with that same passphrase. Persistent compatibility means compatibility with readers which already support the ordinary generated %$ representation; it does not add that representation to still older readers. Historical supported versions and their settings schemas still need compatibility fixtures before rollout.

Keep the original raw-passphrase behaviour of existing URIs. They are indistinguishable from newly generated Persistent URIs to the updated reader. The previous marked-envelope sketch rejected an added Persistent compatibility case with Unsupported encryption format. The same synthetic settings and entered passphrase now open through the unchanged decoder, while separate tests retain old-reader rejection of Ephemeral and rejection outside its window.

Feasibility evidence and validation

The executable design probe uses Web Crypto for the proposed transformation and the actual Commonlib encoder/decoder for settings filtering and encryption. It is an isolated specification exercise; it is not imported by an application or registered in the production test suite.

Run it after installing the dependency versions assessed by this document:

NODE_OPTIONS=--max-old-space-size=512 node docs/design_docs/time_bound_setup_uri.probe.mjs

Alternatively, pass the directory of an unpacked Commonlib 0.1.27 package as the first argument. Its module resolution must supply octagonal-wheels 0.1.54 and the remaining declared dependencies. The probe verifies the Commonlib version before running; it does not install or download packages.

The assessment used Node.js 24.18.0 and registry artefacts for Commonlib 0.1.27 and octagonal-wheels 0.1.54, verified against the lockfile's SHA-512 values. All 22 cases passed:

• fixed Ephemeral derivation checked through Web Crypto and Node HMAC, and an unchanged Persistent passphrase;
• current-window success, previous/later-window rejection, and exact end;
• Persistent across distant timestamps and both candidate attempts on success;
• wrong-passphrase rejection and a shared external format;
• stable end-time metadata and randomised repeated encryption;
• legacy import, old-reader acceptance of Persistent, and old-reader rejection of Ephemeral;
• unsupported-prefix, malformed-ciphertext, and ciphertext-tampering rejection;
• Persistent generation without reading the clock;
• protocol query decoding/re-encoding;
• generation and import crossing a boundary;
• equivalent timestamps expressed with different UTC offsets;
• Unicode, whitespace, empty low-level passphrase input, and distinct Ephemeral and raw-passphrase candidates;
• the deliberate limitation that clock rollback reproduces an old key.

This demonstrates the proposed mechanism and baseline interoperability, not completed application support, formal mode indistinguishability, or a mobile latency bound. The present encryption API may perform two PBKDF2 derivations on a cold import. Do not infer production performance from this small probe, whose operations can reuse the dependency's in-memory key cache.

Implementation validation must cover Commonlib unit and packed-package tests, plus shared fixed-input protocol vectors across consumers. Add targeted LiveSync tests for the generation metadata, cancellation, a window change during mode selection, encoded deep links, and rejected imports without settings writes. Extend CLI, WebPeer, and Deno setup-tool round trips, including their Persistent selection.

Then run the required LiveSync checks, unit suite, and production build, one broad process at a time with NODE_OPTIONS=--max-old-space-size=3072 and bounded test workers. Use the existing focused real-Obsidian Setup URI workflow for copy/paste, deep-link import, cancellation, and successful setup. Verify selection-boundary handling with an injected test clock and mobile behaviour on a supported runtime; do not change the host's system clock. No remote database service is needed for the protocol tests themselves.

There is no identified blocker in the Time-bound URI protocol. The Commonlib candidate based on 0.1.31 passed its type, unit, boundary, release-process, and packed-package gates before the 0.1.32 release. A clean npm ci against the published 0.1.32 artefact and the frozen Deno tool lock resolve the same registry integrity. LiveSync passes its source checks, production build, and 1,034 unit tests on a local stack with PR #1222. The two CLI installer tests need a runner which permits child processes; both pass under normal process permissions. The Deno setup-tool suite, CLI setup and file-operation contract, and WebPeer browser tests passed before stacking.

Focused real-Obsidian generation checks pass on desktop and emulated mobile, including the displayed Time-bound end, Compatible output, and mobile touch targets. A two-device CouchDB workflow now passes on the local stack: the provisioning tool creates a generation 12 database, the first device generates a Time-bound Setup URI after declaring its required generation 13 feature, and the second device imports it. An ordinary note completes a round trip, and a hidden snippet synchronises. The separate real-Obsidian tests for live remote feature changes, internal Metadata migration, and a percent-prefixed E2EE passphrase also pass with published Commonlib 0.1.32. Unit and protocol tests cover window boundaries and preserve the existing distinction between an empty passphrase and cancellation. The WebPeer browser test confirms that its monitor remains available after the URI window ends for a device which has already imported the URI.

The current Commonlib 0.1.33 integration includes the merged host changes from PR #1222 and PR #1225. npm 10 and normal clean installations preserve the lockfile; source checks, the production build, 1,064 unit tests, and ten Deno setup-tool tests pass. Both URI modes preserve ID recovery and explicit legacy ID selection.

Real Obsidian tests cover independent ID keys through Time-bound, Compatible, and QR setup, encrypted local persistence, natural restarts of both devices, and bidirectional note transfers with stable document and Chunk IDs. Incorrect passphrases and past-window URIs leave runtime and persisted settings unchanged. The past clock belongs to an isolated fixture worker, not Obsidian or the host. CouchDB tests also cover a custom ID source and recovery code, rejection of incompatible document keys before remote writes, and the Doctor's decline, reminder, dismissal, and later acceptance paths. The detailed commands and the remaining published-artefact and physical-device checks are recorded in the real Obsidian test guide.

Compatible preserves the URI encryption format; each receiving client must still support the shared settings and the remote's declared features. The host compatibility checks from PR #1222 remain necessary. These results do not establish a mobile performance bound. The first implementation changes only primary-language resources; translation changes require separate scope.