@vrtmrz/livesync-commonlib 0.1.23 → 0.1.25

package/docs/development.md

@@ -134,15 +134,15 @@ Keep [the maintained-host evidence](proven-in-use.md) aligned with the downstrea
 
 ## Integration tests
 
-The integration suite owns Commonlib's direct CouchDB and S3-compatible storage checks. Run it with managed, disposable CouchDB and MinIO containers:
+The integration suite owns Commonlib's direct CouchDB and S3-compatible storage checks. Run it with managed, disposable CouchDB and RustFS containers:
 
 ```bash
 npm run test:integration:managed
 ```
 
-This command requires Docker Compose, creates only test credentials and data, and removes the containers and their volumes after the run. It is the same entry point used by package CI.
+This command requires Docker Compose, creates only test credentials and data, and removes the containers and their volumes after the run. It is the same entry point used by package CI. The RustFS server and client images are pinned by digest; the Compose services retain the names `minio` and `minio-init`.
 
-To test services that are already running, use `npm run test:integration`. The runner accepts `hostname`, `username`, and `password` for CouchDB, and `minioEndpoint`, `accessKey`, `secretKey`, and `bucketName` for S3-compatible storage. Without overrides, it uses the endpoints and test credentials from the managed Compose environment. The selected MinIO bucket must already exist when services are not managed by the runner.
+To test services that are already running, use `npm run test:integration`. The runner accepts `hostname`, `username`, and `password` for CouchDB, and `minioEndpoint`, `accessKey`, `secretKey`, and `bucketName` for S3-compatible storage. Without overrides, it uses the endpoints and test credentials from the managed Compose environment. The selected S3-compatible bucket must already exist when services are not managed by the runner.
 
 ## Messages and translation
 

package/docs/p2p-transport-lifecycle.md

@@ -1,7 +1,7 @@
 ---
-date: 2026-08-28
-commonlib-version: "0.1.20"
-self-hosted-livesync-version: "1.0.21"
+date: 2026-09-16
+commonlib-version: "0.1.25-dev.turn-credentials.6"
+self-hosted-livesync-version: "1.0.28"
 status: unreleased
 ---
 
@@ -173,6 +173,87 @@ Do not close the raw values returned by `room.getPeers()`. Both closing them bef
 
 Commonlib consequently does not expose a forced physical-disconnection command. Such an operation requires a future Trystero API which removes and destroys peers through its shared-peer manager, followed by proof that immediate reconnection remains possible.
 
+## Optional host preparation
+
+The `/p2p` entry exposes the optional `prepareP2PSettings(settings, signal)`
+hook through `P2PReplicatorFeatureOptions` and `P2PServiceOptions`. The hook
+receives the requested settings snapshot before a new room is created. It may
+return `P2P_iceServers` and `P2P_iceServersExpiresAt`; the latter is an absolute
+Unix time in milliseconds. Commonlib copies only those two runtime values onto
+its own connection snapshot, so changes to room identity or other static
+settings in the returned object cannot rewrite the requested binding.
+
+```ts
+useP2PReplicatorFeature(core, openReplicationUiFactory, openRebuildUiFactory, {
+    prepareP2PSettings: async (settings, signal) => ({
+        ...settings,
+        ...(await prepareHostIceSettings(settings, signal)),
+    }),
+});
+```
+
+The hook is called for every new room when supplied, including manual profiles;
+a manual host branch can return the settings unchanged. A consumer which omits
+the hook retains existing manual TURN behaviour. A non-empty
+`P2P_managedType` explicitly requests host preparation and fails safely when
+the hook is absent or does not return usable TURN settings. Provider choice,
+HTTP requests, response validation, timeouts within the provider call, and
+credential-safe error detail belong to the host. Commonlib checks only that a
+managed result has a TURN route and a finite expiry beyond the 30-second room
+establishment margin.
+
+A host can also return a non-empty ICE override without selecting a managed
+provider. This supports ordinary STUN-only or TURN settings, and does not
+require an expiry. When the host supplies an expiry, Commonlib applies the same
+30-second establishment margin. A runtime override used with relay-only routing
+must contain a TURN route; Commonlib rejects it rather than silently changing
+the route policy. The host remains responsible for validating the individual
+ICE server values.
+
+`P2PRoomSessionOwner` retains prepared settings only in the active room's
+immutable connection snapshot. Matching requested settings and usable runtime
+credentials retain that room. An expiry inside the margin causes the next
+reconciliation to retire the room, prepare another snapshot, and open its
+replacement. Explicit reconnect always prepares again. Disconnect, settings
+changes, and suspension abort or invalidate pending preparation; a late result
+cannot publish an obsolete room. Preparation and room opening both have bounded
+owner waits.
+
+There is no periodic renewal, per-peer preparation, provider retry engine, or
+update of a live `RTCPeerConnection`. Internal Trystero reconnection within an
+existing room does not recheck expiry. A host can use the existing
+disconnect/connect flow when a long-lived room needs fresh credentials.
+Trystero retains ownership of physical peers and its offer pool.
+
+Room retirement may cancel a transfer. The next replication attempt uses the
+existing database checkpoint and revision comparison, retaining saved Metadata
+and Chunks. This is document-level continuation; a partial network message may
+be resent. An unfinished automatic baseline remains eligible under the existing
+peer policy, while an interrupted manual operation requires another request.
+
+Managed profiles use the ordinary `sls+p2p://` URI query fields
+`managedType`, `managedId`, and `token`. Commonlib preserves the corresponding
+`P2P_managedType`, `P2P_managedId`, and `P2P_managedToken` scalar projections
+when it parses, serialises, or activates a profile. Provider names and the
+meaning of identifiers and tokens remain host-defined.
+
+The token is persisted only inside the selected P2P profile URI, using the
+existing whole-profile encryption. General settings saves omit the three
+duplicate top-level projections and never synthesise a profile from flat
+fields. Explicit profile operations own URI updates. Flat-settings migration
+creates and selects `legacy-p2p` once, including when CouchDB remains the main
+remote. An encryption failure refuses to replace a managed profile with
+plaintext data.
+
+Encrypted Setup sharing and plain QR sharing already include
+`remoteConfigurations`, so they carry managed settings through the profile
+without new compact fields. Storage, Setup, QR, configuration exchange, and
+external-import boundaries omit `P2P_iceServers` and
+`P2P_iceServersExpiresAt`. Setup, QR, and configuration exchange also omit the
+duplicate top-level provider projections. Runtime credentials therefore do not
+become a later connection override. Hosts must redact tokens, issued
+credentials, and provider responses from logs and reports.
+
 ## Verification
 
 Maintain all five boundaries when this lifecycle changes:
@@ -182,7 +263,8 @@ Maintain all five boundaries when this lifecycle changes:
 - target-aware automation tests must prove bounded delayed advertisement discovery, non-interactive acceptance outcomes, explicit partial and blocked results, baseline de-duplication across AutoSync and configured targets, cancellation of delayed AutoStart after suspension, and a finite demand beside an AutoStart-held room;
 - Commonlib rebuild tests must prove that first-device P2P initialisation does not reset a remote database and that an additional-device P2P Fetch performs one explicit peer-selection pass before resuming reflection;
 - the Self-hosted LiveSync Compose P2P lifecycle test must replace a current replicator, rediscover the same real peer, perform bidirectional RPC, and verify transferred content from a separate process;
-- the Self-hosted LiveSync real-Obsidian P2P Setup URI workflow must generate the second-device URI on the first device, accept both peer directions visibly, and verify a two-way note round-trip; and
+- the Self-hosted LiveSync real-Obsidian P2P Setup URI workflow must generate the second-device URI on the first device, accept both peer directions visibly, and verify a two-way note round-trip;
+- prepared-settings tests must prove managed TURN and expiry requirements, an unmanaged STUN-only override without expiry, relay-only rejection without TURN, immutable requested values, cancellation, expiry replacement, and late-result fencing; and
 - the relay-disconnect test must observe the original WebSocket reach `CLOSED`, remain closed while reconnection is paused, and be replaced after reconnection resumes.
 
 The corresponding product decision and rejected alternatives are recorded in Self-hosted LiveSync's P2P room and transport lifecycle ADR.

package/docs/proven-in-use.md

@@ -24,6 +24,8 @@ Commonlib's injected remote-service tests verify that an owning operation can ab
 
 Commonlib's remote-preference result contract distinguishes available synchronisation settings, a remote which has not stored those settings yet, a failed read, and a remote type which does not support central preferences. Focused CouchDB and Object Storage tests cover absent milestone data separately from transport failures, while Self-hosted LiveSync owns the initialisation choices, cancellation policy, and user-facing explanation.
 
+The focused `/settings` entry also supplies the immutable tweak assessment used by central compatibility checks and host-owned mismatch resolution. Commonlib preserves the exact assessment from a failed CouchDB or Object Storage attempt in its recovery hint, derives directional setting changes and reconstruction impact from one rule table, and keeps P2P's warning policy separate from central rejection. Self-hosted LiveSync consumes the supplied assessment for its two resolution interfaces, compatible chunk-setting auto-acceptance, and Red Flag Fetch setting adoption. The host remains responsible for user choice, settings persistence, Fetch or Rebuild execution, and verifying that the active publication and settings still match before applying a choice.
+
 Commonlib's full offline scanner distinguishes completed, deliberately skipped, and failed storage/database pairs. Before pair construction, it withholds Metadata whose actual document ID disagrees with its recorded path, without reflection, deletion, or last-seen side effects. A consistently addressed entry for the same logical path continues through the established path-based flow; only a path without such an entry also withholds storage processing. The read-only actual-ID Inspector and separately invoked one-entry repair retain ambiguous states for review, revalidate an exact source revision, verify a target-first copy, and preserve the source on failure. Snapshot-restoration tests additionally verify that restored inclusions use current storage content, stale deletions are suppressed, rename halves are admitted from their current path states, and an inspection failure does not become evidence of absence. The following full scan remains the final reconciliation step.
 
 The strict aggregate remains the default for Fast Setup, Fetch, Rebuild, direct scans, and CLI mirror or daemon paths. Self-hosted LiveSync opts only ordinary Obsidian start-up into continuing after individual pair failures. Commonlib returns the distinct `completed-with-file-failures` result, retains each failed result and retry state, records each affected path at verbose level, and leaves any user-facing notice to the host. Focused Commonlib tests cover the default and an explicitly continuing scan; downstream type checks, unit tests, and builds exercise the exact packed implementation and host call. Android-specific storage behaviour remains real-device and reporter-environment evidence rather than a Commonlib guarantee.
@@ -68,6 +70,36 @@ The Obsidian plug-in, CLI, WebApp, and WebPeer compose P2P ownership through `us
 
 Commonlib's focused P2P compatibility tests establish legacy defaulting, bounded outgoing message sizes, connection-string and QR-setting round trips, application of the configured bound across its Trystero server and client surfaces, relay-only ICE mapping when a valid TURN URL is present, and replacement of a serving transport when an effective compatibility value changes. They do not prove that a particular network path requires a smaller preset or that a configured TURN service can allocate a relay. Self-hosted LiveSync owns profile selection, user-facing controls, and real-Obsidian composition; device- and network-specific connectivity remains downstream or reporter-environment evidence.
 
+The optional P2P settings-preparation hook lets a host supply connection-only
+ICE servers without adding provider logic to Commonlib. Focused Commonlib tests
+cover immutable requested settings, provider-scalar identity, room reuse before
+expiry, replacement inside the 30-second expiry margin, explicit reconnect,
+bounded preparation, cancellation, late-result fencing, manual compatibility,
+an unmanaged STUN-only override without provider metadata or expiry,
+relay-only rejection without TURN, relay-only mapping with TURN, and omission
+of runtime credentials from persistence and sharing. Profile tests cover the
+`managedType`, `managedId`, and `token` URI fields, one-profile flat migration,
+activation, whole-profile encryption, and failure without plaintext
+replacement.
+
+Self-hosted LiveSync supplies the Cloudflare HTTP function, response validation,
+provider selection, settings UI, and host hook. Mocked HTTP and injected-room
+tests establish those boundaries without calling Cloudflare. On 16 September
+2026, two isolated Obsidian 1.12.7 instances on one Linux host exercised the
+exact `0.1.25-dev.turn-credentials.6` package. Both acquired real Cloudflare
+credentials and selected relay candidates, and a note reached the receiving
+Vault. Explicit disconnection and reconnection issued fresh credentials,
+selected relay candidates at both endpoints again, and allowed a second note
+to reach the other Vault. A separate real-Obsidian check with dummy credentials
+verified encrypted profile persistence and restoration after restart, with
+issued ICE credentials excluded from saved settings.
+
+Natural TTL expiry, interruption during a replication batch, mobile lifecycle,
+mixed manual and managed peers, and different-network connectivity retain
+separate downstream runtime validation requirements. The live-provider check
+establishes issuance and explicit reconnection for the tested package; it does
+not establish those additional behaviours or the eventual published artefact.
+
 Focused room-session and RPC tests additionally establish that a manual stop delivers cancellation to every concurrent finite replication while leaving the room reusable, that session retirement rejects new work and awaits admitted work before leaving, and that caller cancellation reaches a cancellation-aware incoming RPC handler. The replication-shim tests establish cancellation at safe batch boundaries and preserve the checkpoint for an atomic database write which has already settled. Self-hosted LiveSync composes the provider stop capability into its manual command; physical transport interruption and operating-system process termination remain host and runtime boundaries rather than rollback guarantees.
 
 This is evidence that the current package boundary can be consumed without the Obsidian host, but it is not yet a recommended standalone Commonlib client factory. The high-level lifecycle, readiness, error, and disposal contract remains future package work after Self-hosted LiveSync 1.0 rather than a gate for that release.

package/docs/settings-lifecycle.md

@@ -72,6 +72,25 @@ Two other values deliberately remain unset until their owning lifecycle supplies
 
 The standard Commonlib `SettingService` performs this preparation automatically. Hosts which use that service can inspect `getSettingsMigrationState()` after `loadSettings()` instead of calling the function themselves.
 
+## Assessing synchronisation tweaks
+
+Use `assessTweakCompatibility(current, preferred)` from the focused `/settings` entry when comparing the synchronisation settings advertised by two sides. The result contains immutable, whitelisted snapshots, one entry for each compared setting, and directional `adoptPreferred` and `adoptCurrent` change sets. Each entry keeps the raw value and key-presence state separately from the effective value.
+
+```ts
+import { assessTweakCompatibility } from "@vrtmrz/livesync-commonlib/settings";
+
+const assessment = assessTweakCompatibility(localTweaks, remoteTweaks);
+if (assessment.alignment === "mismatched") {
+    host.requestTweakResolution(assessment);
+}
+```
+
+An absent or `undefined` `handleFilenameCaseSensitive` value has the established effective value `false`. It is therefore equal to an explicit `false` value, while an explicit `true` value is mismatched. The historical defaults in `TweakValuesDefault` receive the same treatment. A missing value without a proven historical default is reported as `unadvertised` and does not by itself make `alignment` mismatched. Explicit `false`, `0`, and empty-string values remain advertised values.
+
+The transition change sets never contain `undefined`. They can fill a missing target from an advertised source, and can use a proven effective default when that changes the target's effective value. Each transition reports `none`, `recommended`, or `required` reconstruction impact and identifies the settings which contribute that impact. Commonlib does not apply the transition, save settings, start Fetch or Rebuild, or grant permission to retry an operation.
+
+`representationDiffers` reports raw value or key-presence differences among the compared settings. The maintained P2P transport uses this to preserve its warning for representational differences while continuing replication after ordinary tweak differences; passphrase authentication remains a separate rejection check.
+
 ## Review and downgrade boundary
 
 A migration may report `requiresSyncReview` when automatic synchronisation should wait for a human decision. Commonlib reports that requirement but does not disable synchronisation settings, persist an acknowledgement, display a dialogue, or decide whether replication may proceed. Those are host-local responsibilities because one device must not acknowledge a safety review for another device through synchronised settings.
@@ -82,6 +101,6 @@ The settings schema version is independent of the package version and of any rem
 
 ## Tests owned by Commonlib
 
-The settings lifecycle unit tests cover blank stores, representative legacy choices, migration idempotence, legacy file-name case normalisation, legacy review state, future-schema downgrade protection, and the distinction between new-Vault recommendations and stored-setting fallbacks. The packed-package test imports the focused `/settings` entry from a clean consumer and checks its declarations and runtime exports.
+The settings lifecycle unit tests cover blank stores, representative legacy choices, migration idempotence, legacy file-name case normalisation, legacy review state, future-schema downgrade protection, and the distinction between new-Vault recommendations and stored-setting fallbacks. Tweak-assessment tests cover effective defaults, unadvertised values, directional change sets, reconstruction impact, raw representation differences, immutable snapshots, and document-ID case behaviour. The packed-package test imports the focused `/settings` entry from a clean consumer and checks its declarations and runtime exports.
 
 Hosts remain responsible for testing when setup is classified as new, how local review acknowledgement is stored, how replication is gated, and how their settings interface presents the result.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "types": "./dist/index.d.ts",