@vrtmrz/livesync-commonlib 0.1.24 → 0.1.25

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

@@ -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.25",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "types": "./dist/index.d.ts",