@vrtmrz/livesync-commonlib 0.1.24 → 0.1.26

package/dist/services/base/SettingService.d.ts

@@ -63,6 +63,7 @@ export declare abstract class SettingService<T extends ServiceContext = ServiceC
      */
     saveSettingData(): Promise<void>;
     private encryptRemoteConfigurationUris;
+    private hasManagedP2PProfileURI;
     private decryptRemoteConfigurationUris;
     /**
      * Event triggered before realising the settings.

package/dist/services/base/SettingService.js

@@ -5,6 +5,7 @@ import {
   LOG_LEVEL_VERBOSE,
   SALT_OF_PASSPHRASE,
   SETTING_KEY_P2P_DEVICE_NAME,
+  omitP2PRuntimeSettings,
   prepareSettingsForLoad
 } from "../../common/types.js";
 import { handlers } from "../lib/HandlerUtils.js";
@@ -143,12 +144,7 @@ class SettingService extends ServiceBase {
   async saveSettingData() {
     this.saveDeviceAndVaultName();
     const previousSettings = this._lastPersistedSettings ?? this.cloneSettings(this.settings);
-    const settings = {
-      ...this.settings,
-      remoteConfigurations: Object.fromEntries(
-        Object.entries(this.settings.remoteConfigurations || {}).map(([id, config]) => [id, { ...config }])
-      )
-    };
+    const settings = this.cloneSettings(this.settings);
     const hookResults = await this.onBeforeSaveSettingData(settings, previousSettings);
     for (const patch of hookResults) {
       if (patch instanceof Error || !patch) continue;
@@ -161,7 +157,15 @@ class SettingService extends ServiceBase {
       this.setSmallConfig(SETTING_KEY_P2P_DEVICE_NAME, settings.P2P_DevicePeerName.trim());
       settings.P2P_DevicePeerName = "";
     }
+    delete settings.P2P_managedType;
+    delete settings.P2P_managedId;
+    delete settings.P2P_managedToken;
     if (this.usedPassphrase == "" && !await this.getPassphrase(settings)) {
+      if (Object.values(settings.remoteConfigurations).some((config) => this.hasManagedP2PProfileURI(config.uri))) {
+        const message = "Failed to retrieve a passphrase for managed P2P source data. Settings were not saved.";
+        this._log(message, LOG_LEVEL_URGENT);
+        throw new Error(message);
+      }
       this._log("Failed to retrieve passphrase. data.json contains unencrypted items!", LOG_LEVEL_NOTICE);
     } else {
       if (settings.couchDB_PASSWORD != "" || settings.couchDB_URI != "" || settings.couchDB_USER != "" || settings.couchDB_DBNAME) {
@@ -218,8 +222,24 @@ class SettingService extends ServiceBase {
       if (config.isEncrypted || config.uri.trim() === "") {
         continue;
       }
-      const encryptedURI = await this.encryptConfigurationItem(config.uri, settings);
+      const managedP2PProfile = this.hasManagedP2PProfileURI(config.uri);
+      let encryptedURI;
+      try {
+        encryptedURI = await this.encryptConfigurationItem(config.uri, settings);
+      } catch (error) {
+        if (managedP2PProfile) {
+          const message = `Failed to encrypt managed P2P remote configuration '${id}'. Settings were not saved.`;
+          this._log(message, LOG_LEVEL_URGENT);
+          throw new Error(message);
+        }
+        throw error;
+      }
       if (encryptedURI === "") {
+        if (managedP2PProfile) {
+          const message = `Failed to encrypt managed P2P remote configuration '${id}'. Settings were not saved.`;
+          this._log(message, LOG_LEVEL_URGENT);
+          throw new Error(message);
+        }
         this._log(
           `Failed to encrypt remote configuration '${id}'. This entry will be saved in plain text.`,
           LOG_LEVEL_URGENT
@@ -233,6 +253,14 @@ class SettingService extends ServiceBase {
       };
     }
   }
+  hasManagedP2PProfileURI(uri) {
+    const trimmed = uri.trim();
+    if (!trimmed.startsWith("sls+p2p://")) return false;
+    const queryStart = trimmed.indexOf("?");
+    if (queryStart < 0) return false;
+    const query = trimmed.slice(queryStart + 1).split("#", 1)[0];
+    return (new URLSearchParams(query).get("managedType") ?? "").trim().length > 0;
+  }
   async decryptRemoteConfigurationUris(settings, passphrase) {
     const configs = settings.remoteConfigurations || {};
     for (const [id, config] of Object.entries(configs)) {
@@ -321,7 +349,7 @@ class SettingService extends ServiceBase {
     try {
       this.settings = await this.adjustSettings({
         ...this.settings,
-        ...partial
+        ...omitP2PRuntimeSettings(partial)
       });
     } catch (ex) {
       this._log("Error in applying external settings: ", LOG_LEVEL_URGENT);
@@ -550,7 +578,7 @@ class SettingService extends ServiceBase {
   }
   cloneSettings(settings) {
     return {
-      ...settings,
+      ...omitP2PRuntimeSettings(settings),
       remoteConfigurations: Object.fromEntries(
         Object.entries(settings.remoteConfigurations || {}).map(([id, config]) => [id, { ...config }])
       )

package/docs/conflict-resolution.md

@@ -31,13 +31,14 @@ Commonlib follows these rules:
 - compare file content byte-for-byte; a path, size, modification time, or revision generation is not proof of identity;
 - use the nearest `available` revision shared by both leaves as the base for three-way merge;
 - retain a manual conflict when the common revision or a required body is missing or compacted;
-- treat content found in any available branch of the same tree, including an ancestor of a deleted leaf, as content which has already been synchronised;
-- preserve storage content as a conflict when it is absent from all available branches; and
+- recognise an unchanged file by comparing its bytes with its exact readable file-reflection provenance;
+- save a genuine edit as a child of that recorded revision, even when a newer database winner exists;
+- deduplicate unknown-origin content against current non-deleted leaves, preserving differing content as a fresh independent root under the same document ID; and
 - never select the newest modification time as a package-level default.
 
-The history check gathers available revisions from every live branch, then compares revision bodies until it finds an exact byte match. Its boolean existence form stops at that first match because older bodies cannot change the answer. This avoids reading obsolete historical bodies whose unique chunks were collected after they stopped being reachable.
+Ordinary saving and incoming reflection share this classification. A historical byte match alone cannot distinguish an unchanged stale file from an intentional revert, and a prefix or suffix relationship does not prove which version the user edited. Unknown-origin content must not acquire an inferred parent from the current winner or its parent.
 
-This check matters after a resolution has propagated. If a receiving device still displays the deleted losing revision, that exact content is known synchronised content. The resolved winner may replace it without recreating the conflict. If the device has edited that content again, the bytes no longer match the old revision, so the storage-protection guard preserves the new edit.
+After a resolution has propagated, an exact recorded revision can still identify unchanged content below a deleted losing leaf. The resolved winner may replace those bytes under the existing reflection policy. If the recorded body is unavailable, the file follows the conservative unknown-origin path. General history-query helpers remain available for callers with separate contracts, including existing deletion and rename recovery; ordinary save and overwrite protection do not scan all historical bodies.
 
 ## Resolution classes
 
@@ -47,8 +48,10 @@ This check matters after a resolution has propagated. If a receiving device stil
 | Text or structured data has a shared available base and non-overlapping changes | Perform a conservative three-way merge.                                     |
 | One side deletes content which the other leaves unchanged                       | Preserve the deletion.                                                      |
 | One side deletes content which the other modifies                               | Retain a manual conflict.                                                   |
-| A receiving file matches any available revision in the tree                     | Apply the propagated database result.                                       |
-| A receiving file matches no available revision                                  | Preserve it as an unsynchronised conflict.                                  |
+| A receiving file matches its exact readable recorded revision                   | Apply the propagated result under the existing conflict policy.             |
+| A receiving file differs from its readable recorded revision                    | Preserve the edit as a child of that revision.                              |
+| Origin is unknown and no current non-deleted leaf matches                        | Preserve a fresh independent root for host conflict resolution.             |
+| Origin is unknown and current non-deleted leaves already contain the bytes       | Avoid duplicate storage; infer provenance only for a unique match.          |
 | A body or common ancestor is missing or compacted                               | Retain a manual conflict.                                                   |
 | Content is binary or otherwise not semantically mergeable                       | Leave the selection policy to the host; Commonlib cannot infer user intent. |
 
@@ -74,19 +77,29 @@ The compatibility implementation accepts an injected, device-local `FileReflecti
 path -> { revision, observedStorageMtime? }
 ```
 
-`revision` is the exact database revision which most recently produced the file displayed on that device. `observedStorageMtime` is the raw modification time observed after reflection. It is neither rounded nor compared across devices, and it is diagnostic only: revision identity never comes from a timestamp, path, size, or content hash.
+`revision` is the exact database revision most recently saved from or reflected in this device's storage. It identifies the base for subsequent local edits, rather than certifying that the current file still contains those bytes. `observedStorageMtime` is the raw modification time of the saved snapshot or the file observed after reflection. It is neither rounded nor compared across devices, and it is diagnostic only: revision identity never comes from a timestamp, path, size, or content hash.
 
 The record is updated only after a successful database-to-storage reflection or storage-to-database write. A plain read does not change provenance. A record remains authoritative when a user edits the displayed file to bytes which happen to equal another branch; content equality must not silently change the branch being extended.
 
+File-handler saves and reflections share a lock for the same Metadata document, held from snapshot acquisition through provenance recording. Different documents can proceed concurrently. An ordinary save keeps one captured body and its recorded base through the database write; a later local edit is processed as a subsequent change, without rereading the file to certify that it remained unchanged. The handler acquires the lock before loading a file body from storage. Rename operations acquire both document locks in a consistent order, and internal calls reuse the caller's lock rather than acquiring it again. Host conflict-check hooks run after the locks are released, allowing a hook to await another file-handler operation on the same document. Host queues may count document-lock waiters against their concurrency limits, so a burst for one document can temporarily delay unrelated files.
+
+These locks order Commonlib file-handler operations; they do not stop user edits, external filesystem writes, or database replication. Incoming overwrite and deletion protection therefore still checks current storage. Restored storage events also retain bounded rechecks because they finish before the file watcher starts and cannot depend on a subsequent change notification.
+
 User-directed reconciliation may select any exact current live revision, including a conflict leaf rather than the deterministic winner. `dbToStorageWithSpecificRev()` rechecks that the selected revision is still live before reflecting its content. `storeFileToDBWithBaseRevision()` performs the same live check before storing current storage content as a child of that revision. If the content already matches the selected non-deleted revision, it records that revision directly without creating a child. A host can set `createIfDifferent` to `false` when it intends only to record an exact content match; differing content then fails instead of changing the revision tree. A host may also create a logical deletion on an explicitly selected branch with `deleteRevisionFromDB()` after performing its own current-live-revision check. This leaves storage unchanged and clears device-local provenance only when that record names the deleted revision.
 
 `storeWithBaseRevision()` is the force-write primitive for deliberately preserving a branch below an exact revision, including a revision which is no longer a leaf. It must not be used when an operation means 'advance this revision only if it is still current'. For that compare-and-store boundary, `storeWithLiveBaseRevision()` uses PouchDB's ordinary revision check and returns `false` if the supplied base has already been advanced. Any current revision-tree leaf is eligible, including a non-winning conflict leaf or a logical-deletion leaf. The caller must refresh its state after refusal rather than silently falling back to the deterministic winner.
 
+`storeIndependentRevision()` explicitly preserves unknown-origin content through `putDBEntryAsIndependentRoot()`. Passing an undefined base to `storeWithBaseRevision()` retains its existing latest-revision behaviour and does not create an independent root. `findLiveContentRevisions()` compares only current non-deleted leaves using locally available chunks. Additional provenance comparisons also use local-only retrieval, so they do not introduce remote chunk requests or delivery waits; a missing body leads to preservation rather than an inferred base.
+
 A successful non-deleted reconciliation records the exact selected or newly created revision as provenance. Applying a logical deletion removes the storage item and its provenance record. Deletion provenance is not retained indefinitely: an absent storage item and a current logical-deletion winner already agree and need no further reconciliation.
 
 Hosts may construct the namespaced store handle during service composition, before its backing database is open. Store operations begin only after the host's storage lifecycle is ready. They fail rather than wait when that lifecycle contract is violated, because an implicit readiness wait could hang after failed initialisation or wait on its own initialisation handler. Database reset is a transient unavailable boundary; the host must avoid file processing during it and reconstruct derived provenance after reopening.
 
-When a record is absent, the implementation reconstructs it only if the current storage bytes match exactly one available revision body. No match, or more than one match, leaves the branch identity unknown.
+For ordinary saving and incoming reflection, an absent or unreadable recorded base permits reconstruction only from exactly one matching current non-deleted leaf. Multiple matches avoid duplicate storage without guessing branch identity. No current match creates a fresh independent root, even when an ancestor has the same bytes. Deletion and rename retain their existing provenance-recovery contracts.
+
+An unchanged stale file is not saved below the winner. When the database has advanced without a conflict, the existing database-to-storage path reflects it; a conflict instead remains subject to the host's reflection and resolution policy. Independent roots retain the file's modification time and use the existing Metadata/Chunks format, with fresh revision identifiers and reusable chunks. They have no shared ancestor with unrelated existing branches, including after replication. This does not disable a host's explicit newer-file option.
+
+Saving and reflection revalidate captured file content and provenance across asynchronous work. Restored saves reconcile changed storage directly, because host file watchers may not yet be registered. Retries are bounded; a file which keeps changing causes the operation to fail rather than report an uncompleted save as successful. These checks do not make external filesystem edits atomic with a host write: the storage contract has no conditional write operation covering that final interval.
 
 ## Operations while a conflict exists
 
@@ -99,7 +112,7 @@ With a proven displayed revision:
 
 When edit provenance cannot be reconstructed, the new bytes are preserved as another manual-resolution branch instead of being attached silently to the deterministic winner. A deletion has no remaining file body from which to reconstruct provenance, so an unproven deletion preserves every live branch and requests conflict review. A cross-path rename with an unproven source keeps the newly stored target and preserves every source branch for review.
 
-If chunks needed to reconstruct the winning body are missing, the document metadata and revision tree may still identify the exact winning revision and its parent. In that case, an edited storage file is preserved as a sibling branch from the shared parent without treating the unavailable body as trusted content. A generation-one revision has no parent from which a sibling can be created. If the parent or revision metadata is unavailable, Commonlib refuses the write and requests conflict review rather than inventing a base revision. A host may offer a separately confirmed exact-revision discard: logical deletion needs the revision metadata, not its chunks, and a confirmed replacement can then be stored. This is a recovery decision and must not be performed automatically.
+If the recorded base cannot be read, an ordinary save preserves differing storage bytes on an independent root without guessing the winner's parent. This also works when the existing winner is generation one or has unavailable chunks. Existing unreadable branches remain available for repair. A host may separately offer confirmed exact-revision discard; it must not infer permission for discard from a failed read.
 
 These fallbacks favour recoverability. They may temporarily leave a duplicate target or a still-visible source conflict, but they do not discard a branch whose relationship to the user's operation cannot be proved.
 
@@ -145,19 +158,19 @@ For a cross-path rename, such as `draft.md` to `published.md`, Commonlib stores
 
 ### Reconstructing provenance after local state is unavailable
 
-Suppose a local-database reset removed the device-local record, but the storage file still has exactly the bytes held by `C2`. If `C2` is the only available revision with those bytes, Commonlib reconstructs `C2` as the displayed base and an edit extends it normally.
+Suppose a local-database reset removed the device-local record, but the storage file still has exactly the bytes held by current non-deleted leaf `C2`. If `C2` is the only matching current leaf, ordinary saving or reflection can reconstruct `C2` as the displayed base and a later edit extends it normally. An unchanged-time scan alone does not guarantee reconstruction.
 
-If both `C1` and `C2` contain the same bytes, or neither available body matches, content cannot identify the displayed branch. An edit is preserved as another manual-resolution branch. A deletion preserves both existing branches, and a cross-path rename preserves the source branches after storing the target. These outcomes may require user review, but they do not guess that the deterministic winner was displayed.
+If both current leaves contain the same bytes, ordinary saving avoids duplicate storage without selecting either as provenance. If neither contains the storage bytes, those bytes are preserved on an independent root. An unproven deletion preserves both existing branches, and a cross-path rename preserves unproven source branches after storing the target. These outcomes may require user review, but they do not guess that the deterministic winner was displayed.
 
 ### Receiving a resolution while showing the losing branch
 
-Device A may resolve the conflict while Device B still displays the bytes from `C2`. When the resolved tree reaches Device B, the all-branch history check recognises those bytes below the deleted losing leaf. Device B can apply the resolution without recreating the conflict. If Device B edited the file after displaying `C2`, its bytes no longer match the historical revision and the overwrite guard preserves that new local edit instead.
+Device A may resolve the conflict while Device B still displays the bytes from recorded revision `C2`. When the resolved tree reaches Device B, the exact recorded body identifies those bytes as unchanged, even below the deleted losing leaf. Device B can apply the resolution without recreating the conflict. If Device B edited the file after displaying `C2`, its bytes differ from that recorded body and the overwrite guard preserves the edit, including an intentional revert to some other historical content.
 
 ### Starting and resetting the provenance store
 
 A host may create the namespaced provenance handle while composing services. It then opens the backing key-value database in its sequential settings lifecycle before enabling scans, storage watchers, or replication. If opening fails, start-up stops; a provenance operation is not held waiting for a readiness state which may never arrive.
 
-During a local-database reset, the store is temporarily unavailable. A racing lookup fails promptly and is treated as unknown provenance, selecting the conservative behaviours above. Once the database has reopened, a later scan can reconstruct uniquely identifiable records from exact revision bodies.
+During a local-database reset, the store is temporarily unavailable. A racing lookup fails promptly and is treated as unknown provenance, selecting the conservative behaviours above. Once the database has reopened, saving or reflection can reconstruct a record from a unique matching current non-deleted leaf.
 
 ## Unsafe shortcuts
 
@@ -167,11 +180,11 @@ Do not:
 - select a winner from modification time unless the host exposes and the user selects that destructive policy;
 - assume the PouchDB winner is the content currently displayed in storage;
 - replace a recorded displayed revision merely because current bytes match another branch;
-- recreate a conflict from a byte-identical deleted losing revision after a remote resolution;
+- infer that a file is unchanged from historical byte equality without its exact provenance;
 - discard storage content because history lookup failed;
 - infer revision identity from path, size, modification time, or hash without the revision identifier; or
 - automatically merge overlapping text changes or unrelated binary contents.
 
 ## Verification ownership
 
-Commonlib unit tests build real in-memory PouchDB trees and inject provenance fakes at the file-handler boundary. They cover unequal branch lengths, nearest shared ancestry, deterministic selection from multiple live leaves, reconstruction of a later manual pair after an earlier sensible merge, content retained below a deleted losing leaf, recorded and reconstructed branch identity, ambiguous content, conflict-time editing, missing-body preservation from available parent metadata, refusal to invent a parent for a generation-one revision, exact logical deletion and replacement of an unreadable generation-one live leaf, case-only rename, cross-path rename, and safe unproven fallbacks. A maintained host should additionally verify its composition: persistent device-local provenance, real file events, replication of the resulting revision trees, and dialogue policy.
+Commonlib unit tests build real in-memory PouchDB trees and inject provenance fakes at the file-handler boundary. They cover revision ancestry, conservative merge, content preservation, independent roots, repeated events, and the separate explicit reconciliation, deletion, and rename contracts. A maintained host should additionally verify persistent device-local provenance, real file events, restart processing, replication of the resulting revision trees, and dialogue policy. Package-level tests do not establish mobile lifecycle behaviour or the original reporter's environment.

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

@@ -14,7 +14,7 @@ The consumer contract in `test/contracts/serviceContext.ts` checks shared result
 
 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.
 
-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 from a deleted losing branch remains recognisable after resolution, and conflict-time operations retain the exact displayed branch or preserve every branch when that identity cannot be proved. 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. A local edit remains a readable sibling branch when the winning body is unavailable but its exact revision and parent metadata remain, a generation-one revision without a parent is left unresolved, and a separately confirmed exact deletion of that unreadable live leaf permits a replacement to be stored without reading the missing chunk. 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.
+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.
 
 Commonlib's chunk-reachability tests use real PouchDB revision trees. They verify that an ordinary superseded revision releases its unique chunks, a chunk shared by current files remains reachable, live conflict branches and their nearest available shared ancestor remain protected, and losing-branch ancestry becomes eligible after resolution. They also replicate a collected chunk deletion to another PouchDB database and verify that writing the same content can recreate and replicate the content-addressed chunk. Self-hosted LiveSync owns the CouchDB-specific Garbage Collection V3 workflow, including device checks, confirmation, deletion, push-only replication, and remote compaction.
 
@@ -70,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/package.json

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