@vrtmrz/livesync-commonlib 0.1.31 → 0.1.33

package/docs/proven-in-use.md

@@ -16,12 +16,22 @@ The unreleased 0.1.30 packed candidate adds encryption of Hidden File Sync and C
 
 Additional real-CouchDB integration tests exercise Fast Fetch admission before local reset, generation 12 acceptance, and generation 13 retrieval with plaintext and encrypted internal Metadata together. A real-Obsidian migration scenario enables the preference through the settings UI without Rebuild, verifies that unchanged Metadata retains its original revision while rewritten entries are encrypted with stable IDs, and checks a second device's mismatch rejection and restoration after alignment. After turning the preference OFF, Fast Fetch still retrieves both representations and their Chunks with matching content; the remote feature declaration remains. These checks use the local packed candidate with LiveSync 1.0.32.
 
+Optional independent ID derivation uses a saved secret for encrypted Chunk IDs and obfuscated document IDs. The unreleased Chunk update replaces the algorithm from `0.1.32`, published with the `next` tag, while retaining `idDerivationVersion: 1`, recovery codes, and settings. It hashes exact Chunk text with xxHash64 before HMAC-SHA-256 with a separate Chunk key. Preparation is shared per manager and current key; tests cover concurrent use, key changes, E2EE suspension, teardown, and retry after failure. Document IDs and agreement proofs retain their existing HMAC messages. Chunk collision resistance is bounded by the 64-bit prehash.
+
+The updated Commonlib passes its complete Unit suite, type check, and isolated packed-package consumer checks. Real CouchDB and Object Storage Integration tests cover matching keys, direct-access rejection before control-document changes, Journal agreement, and differing Chunk keys when paths remain visible. LiveSync 1.0.32's Unit suite and build checks pass with the local packed candidate. Real Obsidian two-Vault checks cover matching-key synchronisation, incompatible document key rejection, and differing Chunk keys with visible paths. Its Review Harness exercises the actual calculation and copied report. Measurements use desktop Obsidian; native mobile timing and a complete Rebuild remain unmeasured for this construction.
+
+The focused `/hashing` entry exposes the same `HashManager` used by database writes. Package checks exercise its types, a fixed ID vector through the installed Node module, and browser bundling. The Review Harness consumes that entry without importing the package's internal files. Earlier real-Obsidian onboarding, encrypted Journal upload, and CLI P2P Setup URI checks used the predecessor full-content-HMAC construction; they establish those integration paths but do not measure the updated algorithm. The local candidate is prepared as `0.1.33` for the `next` tag; registry publication remains separate from this evidence.
+
+Regression tests also preserve each device's ID version and key through ordinary Tweak alignment, reject incompatible document ID modes separately from adoptable tweaks, and complete legacy P2P configuration imports without inheriting the receiving device's key. Direct-access admission checks cover both a different saved key and a legacy caller against keyed document IDs.
+
 The plug-in extends the neutral `ServiceContext` with Obsidian-owned capabilities in `src/modules/services/ObsidianServiceContext.ts`. One context instance carries the LiveSync-owned translator and event hub through the Service Hub rather than placing those dependencies in Commonlib globals. Commonlib supplies its typed English fallback when another host omits the translator.
 
 The consumer contract in `test/contracts/serviceContext.ts` checks shared result semantics and exact context identity across the composed services. The real-Obsidian suite documented in `test/e2e-obsidian/README.md` then covers plug-in loading, representative Svelte dialogue mounts, Vault reflection, CouchDB and Object Storage synchronisation, a two-device P2P Setup URI round-trip, two-Vault behaviour, and other Obsidian-owned boundaries.
 
 Commonlib supplies the two sleep preferences and preserves them through Setup URI encoding. Self-hosted LiveSync applies those values once at its injected bounded-activity runner, so remote operations and downloaded-document application share the same host-owned Wake Lock policy. Focused downstream tests cover the platform preference table and both activity categories; operating-system suspend behaviour remains real-platform integration evidence rather than a Commonlib guarantee.
 
+The focused [Setup URI sharing API](setup-uri.md) adds a fixed time window for new Ephemeral exports while leaving Persistent exports in the existing format. Commonlib unit tests cover window boundaries, encrypted round trips, and old-reader compatibility for Persistent URIs. The Obsidian generation dialogue, CLI import, browser generators, and real-runtime behaviour remain downstream responsibilities; package-level coverage alone does not establish those host interactions.
+
 Commonlib's real-PouchDB and injected-boundary unit tests prove that conservative merge uses the nearest revision actually shared by both conflict leaves, multiple remaining leaves are selected in a deterministic order, each completed pair is reconstructed from the committed tree, storage content with exact provenance remains recognisable below a deleted losing branch after resolution, and ordinary file saves preserve edits below their recorded base or on an independent root when the base cannot be read. Incoming reflection uses the same classification. Current non-deleted leaf matches prevent duplicate preservation without using historical byte equality as proof of an unchanged file. Conflict-time deletion and rename retain their separate displayed-branch contracts. They also verify that a boolean history check stops after its first exact content match without reading an older unavailable revision, while revision enumeration still returns every match. Unknown-origin local content remains readable on a fresh independent root when the winning body is unavailable, including when the existing winner is generation one. A separately confirmed exact deletion of an unreadable current leaf remains an explicit repair operation. Exact reconciliation tests cover reflecting a selected live leaf, storing Vault content as its child, recording a matching leaf without creating a revision, clearing matching provenance after exact branch deletion, and refusing to record a stale revision or a revision whose content differs. Separate live-base tests advance a selected conflict leaf or logical-deletion leaf through PouchDB's ordinary revision check, retain the other live leaf, and reject reuse of a stale base. Self-hosted LiveSync supplies the host composition, persistent device-local provenance, and the per-revision repair interface. Its optional two-Vault scopes cover post-resolution propagation and edit, logical deletion, case-only rename, and cross-path rename while conflicts remain active. The conflict-operation scope passes in real Obsidian against the exact locally packed Commonlib artefact, including replicated parent revisions and preservation of the other live branches. Its Document History scenario restores readable historical bytes as a new live successor and reflects that exact revision to the Vault.
 
 The equal-time scan test uses real in-memory PouchDB to verify that a missing record is established from unchanged current content before a newer revision arrives. It also verifies that existing provenance is retained and equal-time local edits remain protected as conflicts. Focused handler tests cover failures and changes during verification. Self-hosted LiveSync owns the persistent store and real-Obsidian restart check; these Commonlib tests do not exercise Windows file events or remote CouchDB timing.
@@ -42,6 +52,8 @@ The strict aggregate remains the default for Fast Setup, Fetch, Rebuild, direct
 
 Commonlib's local-database lifecycle tests distinguish the settings-selected database from the active wrapper. They verify replacement before a changed-suffix reset, fail-closed cleanup after rejected physical preparation, application readiness after the requested scan and completion hooks, verbose diagnostics for rejected preparation stages, and the prevention of rebuilt events and later remote mutation after a failed local reset. Replication readiness tests verify that a descriptive application-initialisation diagnostic replaces the former bare diagnostic. Self-hosted LiveSync owns settings persistence, setup flags, user-facing notices, recovery dialogue, and real-Obsidian rebuild confirmation; those host results remain downstream evidence rather than Commonlib guarantees.
 
+Commonlib's lifecycle tests verify that `markIsReady()` emits `EVENT_APPLICATION_READY` on the service context's event channel once per transition to readiness, after the flag is set, and that clearing readiness emits nothing. On 27th September 2026, a local packed candidate passed LiveSync 1.0.32's type check and replication unit tests together with a result processor which continues held replication results from that event, and a temporary downstream test showed documents restored during a real `prepareDatabaseForUse()` run held until readiness and applied immediately afterwards. Behaviour in a real Obsidian Vault remains downstream runtime evidence.
+
 The focused `/replication` entry defines the provider capability, configuration identity, same-kind reconciliation, interaction authority, and truthful outcome contracts used when a host composes replication. A host selects its fixed provider subset and registers each definition during composition; an omitted role remains an explicit unsupported result rather than falling back to another provider. Commonlib serialises active replacement, rejects a candidate whose configuration changes before publication, and provides a transition-aware context acquisition boundary. The entry does not own user dialogue, P2P room policy, or selection of unknown providers.
 
 The same entry distinguishes a central provider whose host prepares the Security Seed from one which prepares it within each transfer. Object Storage uses the latter: Journal reads fresh synchronisation parameters before compatibility checks, shares that result with its checkpoint epoch and encryption work, and releases it when the transfer settles. CouchDB retains host preparation. Focused Commonlib tests cover read reuse, later refresh, unavailable storage, and checkpoint reset; the maintained plug-in's provider tests and packed-package checks cover the declared readiness. Behaviour on the reporter's Android device remains a downstream runtime check.

package/docs/releasing.md

@@ -33,7 +33,7 @@ Before publication, run the downstream workflow against an exact Self-hosted Liv
 
 ## Preparing a release
 
-Choose the version explicitly. Use a prerelease such as `0.1.0-rc.0` when registry installation must be validated before the first stable version. Package-proof versions are local artefacts and cannot be staged.
+Choose the version explicitly. Prefer a `-next.N` prerelease, such as `0.1.32-next.0`, when registry installation must be validated before the stable version. Reserve `-rc.N` for an explicitly chosen release candidate. Package-proof versions are local artefacts and cannot be staged.
 
 Prepare both stable releases and pre-releases on a reviewed pull request based on `main`. A pre-release may be staged from the exact reviewed pull-request branch commit so that the registry artefact can be validated in Self-hosted LiveSync before the Commonlib change is merged. A stable release must be staged only after its exact reviewed release commit is present on `main`.
 

package/docs/setup-uri.md

@@ -0,0 +1,58 @@
+# Setup URI sharing
+
+The focused `@vrtmrz/livesync-commonlib/setup-uri` entry encodes and decodes
+encrypted Setup URIs. A Setup URI carries settings and remote credentials;
+share its URI and passphrase separately.
+
+`encodeTimeBoundSetupURI` offers two generation modes. `ephemeral` is the
+default. It binds the URI to the current seven-day UTC window, anchored at the
+Unix epoch, and returns the exclusive end of that window as `usableUntil` in
+Unix milliseconds. This is a fixed window, so a newly generated URI may have
+less than seven days remaining. Show the returned instant in the user's time
+zone when presenting the URI.
+
+`persistent` returns `usableUntil: null` and delegates to the original
+`encodeSettingsToSetupURI` algorithm with the entered passphrase. A reader
+which already supports that original encryption format can open it. Both modes
+have the same URI structure and carry no visible mode or timestamp field.
+
+```ts
+import {
+    encodeTimeBoundSetupURI,
+    decodeSettingsFromSetupURI,
+    getTimeBoundSetupURIUsableUntil,
+    isTimeBoundSetupURIUsableNow,
+} from '@vrtmrz/livesync-commonlib/setup-uri';
+
+const endShownBeforeGeneration = getTimeBoundSetupURIUsableUntil();
+const generated = await encodeTimeBoundSetupURI(settings, enteredPassphrase, {
+    mode: 'ephemeral',
+    removeProperties: ['pluginSyncExtendedSetting'],
+    skipDefaultValue: true,
+});
+
+const importedSettings = await decodeSettingsFromSetupURI(generated.uri.trim(), enteredPassphrase);
+const canStillCopy = isTimeBoundSetupURIUsableNow(generated.usableUntil);
+const endWasAccurate = generated.usableUntil === endShownBeforeGeneration;
+```
+
+The decoder automatically tries the current Ephemeral window and the entered
+passphrase. Previous and future windows are not searched. Existing Setup URIs
+remain readable. An Ephemeral URI cannot be opened through the unchanged old
+decoder with the entered passphrase.
+
+The receiving device supplies the clock. Someone who knows the passphrase
+can reproduce historical time factors or alter that clock. Opening a URI does
+not revoke credentials already imported, and Ephemeral does not mean one-time
+use. An unsuccessful opening attempt cannot reliably distinguish an incorrect
+passphrase, damaged ciphertext, or a different time window.
+
+The encoder checks that its Ephemeral window has not changed during encryption.
+`getTimeBoundSetupURIUsableUntil` lets a host show the exact end before a user
+selects the mode. Compare that value with the generated `usableUntil` and
+present the new end if the window changed during selection. A host may also use
+`isTimeBoundSetupURIUsableNow` before showing or copying an open result; it
+checks both edges of the selected window, including a clock moved backwards to
+an earlier window. An already open copy dialogue can otherwise retain a URI
+after its window ends, but the reader will reject that URI. The selected export
+mode is an interaction choice; it is not a synchronised Vault setting.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -47,6 +47,11 @@
       "import": "./dist/context.js",
       "default": "./dist/context.js"
     },
+    "./hashing": {
+      "types": "./dist/hashing.d.ts",
+      "import": "./dist/hashing.js",
+      "default": "./dist/hashing.js"
+    },
     "./node": {
       "types": "./dist/platform/node/index.d.ts",
       "import": "./dist/platform/node/index.js",
@@ -77,6 +82,11 @@
       "import": "./dist/settings.js",
       "default": "./dist/settings.js"
     },
+    "./setup-uri": {
+      "types": "./dist/setupUri.d.ts",
+      "import": "./dist/setupUri.js",
+      "default": "./dist/setupUri.js"
+    },
     "./compat/API/processSetting": {
       "types": "./dist/API/processSetting.d.ts",
       "import": "./dist/API/processSetting.js",
@@ -633,6 +643,9 @@
       "context": [
         "dist/context.d.ts"
       ],
+      "hashing": [
+        "dist/hashing.d.ts"
+      ],
       "node": [
         "dist/platform/node/index.d.ts"
       ],
@@ -651,6 +664,9 @@
       "settings": [
         "dist/settings.d.ts"
       ],
+      "setup-uri": [
+        "dist/setupUri.d.ts"
+      ],
       "compat/API/processSetting": [
         "dist/API/processSetting.d.ts"
       ],