@glance-apps/sync 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -7,6 +7,179 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.8.0] - 2026-07-31
+
+### Added
+
+- **Recovery from a halted credential (GLANCEvault Phase 2.2).** The 1.7.0
+  credential halt was built with no exit; this release adds the one exit:
+  **`recoverVaultSyncEngine(config)`**, user-initiated re-enrollment with the
+  bootstrap secret. Since server Phase 2.1, enrolling the same byte-exact
+  `(accountId, deviceId)` revokes every still-active predecessor credential
+  in the same transaction, so recovery is a rotation — the dead credential is
+  superseded, not accumulated alongside.
+  - **Halt-gated, structurally.** The call refuses with `NOT_HALTED` unless
+    the device is credential-halted, so it cannot be wired into a startup or
+    retry path as an on-demand rotator. Combined with the package holding no
+    secret (one must be supplied fresh, and it is confined to the call
+    exactly as in `connectVaultSyncEngine` — never stored, logged, or
+    retained), user initiation is structural, not procedural. **No code path
+    recovers automatically**, including transport failures, startup, or a
+    halt discovered at launch.
+  - **Per-account only, no fallback.** Unlike connect, recovery never falls
+    back on discovery failure: an unreachable `/healthz` is
+    `VAULT_UNREACHABLE` and a non-per-account mode is
+    `RECOVERY_UNSUPPORTED`; both leave the device halted and untouched.
+    Shared mode has no credentials, no halt, and no reachable recovery path.
+  - **Order of operations**, each failure leaving the device halted rather
+    than ambiguous: halt gate → deviceId resolution → mode guard → storage
+    canary (now restores the slot's prior contents, so a failed recovery
+    keeps the stale record byte-identical) → enroll → persist + read-back
+    verify (overwriting the stale record — it does not survive recovery) →
+    **clear the halt last** → return a fresh engine. The old engine's client
+    closes over the dead credential; apps must swap to the returned engine.
+  - **deviceId: the stale record's value wins.** Rotation only lands if
+    enrollment uses the identity the dead credential is bound to, and the
+    stored record is ground truth for that. An explicit `config.deviceId`
+    that differs is surfaced as `DEVICE_ID_CONFLICT`, never resolved
+    silently (either choice orphans a credential or a cursor). With no
+    readable record: explicit value, else the persisted package-owned id.
+    Never minted fresh.
+- **Halt-set identity rule** (the stale-engine hazard fix). The halt key is
+  shared by every engine instance on a device, so an old instance still
+  holding the superseded credential could previously re-halt the device
+  after recovery. Now, on `CREDENTIAL_INVALID`, the engine halts **unless**
+  the stored credential record exists, is readable, and holds a *different*
+  credential than the engine's bearer — definitive proof the instance was
+  superseded. **The rule fails toward halting**: a missing or unreadable
+  record still halts (the naive "no record → no halt" would retry a dead
+  credential forever, exactly what the halt exists to prevent). A superseded
+  instance goes **inert in memory** instead — surfaced once via
+  `onError('CREDENTIAL_INVALID', isHardStop true)`, then silent, zero
+  network, never touching the shared halt key — killing both the bricking
+  and the pointless server load. New state query: `isSuperseded()`.
+- The 1.4b minted-but-lost-persistence residual is now self-healing: a
+  credential minted and then lost to a persistence failure is superseded by
+  the next successful enrollment for the same `(accountId, deviceId)`.
+
+## [1.7.0] - 2026-07-31
+
+### Added
+
+- **Per-account vault auth, client half (GLANCEvault Phase 1.4b).** A
+  GLANCEvault server can run `authMode: 'per-account'`, where each device
+  authenticates with its own enrolled credential instead of the instance-wide
+  shared device token. The package owns the whole client-side flow — apps hand
+  it a bootstrap secret (or the shared token) and get a working engine back,
+  without implementing discovery, branching, credential persistence, or
+  secret discard themselves. Shared mode remains the default path and is
+  byte-for-byte unchanged.
+  - **`connectVaultSyncEngine(config)`** — the packaged connect flow.
+    Discovers the server's auth mode from `/healthz`, then branches:
+    `shared` → builds the engine from `config.vaultToken` exactly as before;
+    `per-account` → uses the credential persisted under
+    `{prefix}-vault-credential`, enrolling with `config.enrollmentSecret`
+    only when no credential is stored for this exact (server, account). The
+    credential is persisted durably (write + read-back verify) **before**
+    enrollment is treated as complete, and a storage canary runs **before**
+    minting so broken storage cannot orphan one server row per launch. The
+    bootstrap secret is never written to storage, never logged, never placed
+    on the engine config, and not retained past the call. **No code path
+    re-enrolls automatically** — once a credential is stored it is always
+    reused, even after rejection (recovery is Phase 2.2), so revocation
+    (vault Phase 2.1) cannot be silently undone by a client loop. Discovery
+    failure (server unreachable, unexpected body) falls back to the last
+    known auth state — stored credential, else `vaultToken` — which is
+    exactly the pre-1.4b behavior for existing installs; an unrecognized
+    future mode string does the same rather than guessing. A `/healthz`
+    without `authMode` (a pre-1.4a server) is ordinary shared mode, not an
+    error. Typed failures: `VAULT_TOKEN_REQUIRED`,
+    `ENROLLMENT_SECRET_REQUIRED`, `CREDENTIAL_PERSIST_FAILED`,
+    `VAULT_UNREACHABLE`, plus the enrollment errors below.
+  - **`getOrCreateDeviceId(storageKeyPrefix)`** — the package now owns the
+    stable device identity: generated once (`crypto.randomUUID`, with a
+    `getRandomValues` fallback for old WebViews) and persisted under
+    `{prefix}-device-id`; used for both the device cursor and enrollment. An
+    explicit `config.deviceId` still wins. This also fixes a latent bug: the
+    engine's device-cursor update silently no-oped (`{updated:false}`) when
+    no `deviceId` was configured, so such installs never reported cursors —
+    on upgrade they get a generated id and start reporting for the first
+    time (server-side effect: a `devices` row appears and tombstone GC gains
+    an accurate cursor; pure improvement, no data risk).
+  - **Substrate exports** (used by the flow, available standalone):
+    `fetchVaultHealth({ vaultUrl, fetchImpl? })` — unauthenticated
+    `GET /healthz`, `authMode` normalized to `'shared'` when the server
+    predates the field; and `enrollVaultDevice({ vaultUrl, enrollmentSecret,
+    accountId, deviceId, fetchImpl? })` — `POST /enroll`, secret in the body
+    only, values sent byte-exact, typed `ENROLLMENT_REJECTED` (401) /
+    `ENROLLMENT_UNSUPPORTED` (404, shared-mode server) failures, and
+    `*_REQUIRED` codes thrown before touching the wire on missing fields.
+  - **`CREDENTIAL_INVALID` and the credential halt.** `createVaultClient`
+    now reads error bodies best-effort: a 401 whose body says
+    `invalid credential` (the server's chosen signal for "this device must
+    re-enroll") surfaces as code `CREDENTIAL_INVALID`; a missing, non-JSON,
+    or unrecognized body degrades to the generic `VAULT_ERROR`, so client
+    correctness never depends on server wording. On `CREDENTIAL_INVALID` the
+    DB engine persists a stop under `{prefix}-db-sync-credential-halt`,
+    surfaces `onError(message, 'CREDENTIAL_INVALID', /* isHardStop */ true)`,
+    and makes **no further network calls** — across restarts. Nothing in
+    this version clears the halt (that is Phase 2.2's recovery flow);
+    `isCredentialHalted()` / `getCredentialHalt()` expose the state.
+    Shared-mode 401s (`invalid device token`) keep today's retryable
+    behavior. The key verifier passes `CREDENTIAL_INVALID` through instead
+    of relabeling it `VERIFIER_UNSUPPORTED`, so `allowUnverified` can never
+    wave a rejected device through.
+  - `createVaultClient` is otherwise unchanged on the wire; `vaultToken`
+    accepts either the shared device token or an enrolled credential — the
+    credential IS the Bearer token.
+
+### Security notes
+
+- The persisted credential lives in localStorage, exactly as exposed as the
+  shared device token and the file tier's provider passwords are today:
+  parity, not a regression. Secure-storage migration is explicitly out of
+  scope for this phase.
+
+## [1.6.1] - 2026-07-19
+
+### Fixed
+
+- **File engine: persistent PRECONDITION_FAILED (412) sync loop on servers
+  that mangle ETags** (lastGLANCE issue #232). The optimistic-concurrency
+  cycle (GET capturing an ETag, merge, PUT with If-Match) can never converge
+  against a server whose GET responses carry a mangled validator: Apache
+  mod_deflate rewrites the ETag on gzip-encoded responses to `"xyz-gzip"`
+  (Android's HttpURLConnection silently requests gzip, so native apps always
+  hit this on Apache-fronted servers such as standard Nextcloud installs), and
+  nginx's gzip filter downgrades strong ETags to weak (`W/"xyz"`), which
+  If-Match's strong comparison rejects. Either way every PUT 412s, the
+  single conditional retry fetches another mangled ETag and 412s again, and
+  sync wedges until the user hand-deletes the sync file from the server. Two
+  complementary fixes:
+  - **ETag normalization at capture time.** A new exported pure helper,
+    `normalizeEtag(raw)`, strips the weak-validator prefix (`W/"abc"` becomes
+    `"abc"`) and the known content-coding suffixes Apache appends inside the
+    quotes (`"abc-gzip"` / `"abc-br"` become `"abc"`), preserving surrounding
+    quotes and passing null/undefined through. `parseDownloadResponse` now
+    normalizes every ETag it captures, so If-Match round-trips the entity's
+    real validator. Clean ETags are unchanged, so servers that never mangle
+    see identical behavior.
+  - **Termination guarantee: a second consecutive 412 falls back to an
+    unconditional upload.** If the conditional retry after a 412 itself fails
+    with PRECONDITION_FAILED (any other error keeps the existing
+    backoff-and-surface behavior), the engine runs one final
+    download-merge-upload cycle whose PUT omits If-Match entirely
+    (last-writer-wins). The uploaded payload is the merge of local state with
+    the remote fetched milliseconds earlier in the same cycle, so the
+    lost-update window is tiny - far safer than a permanently wedged sync
+    that pushes users toward deleting the sync file. If the fallback cycle
+    itself fails, the error is surfaced exactly as the old retry-failure path
+    did (exponential backoff, `onError`, status `'error'`).
+
+### Added
+
+- `normalizeEtag(raw)` exported from the package root for reuse by apps.
+
 ## [1.6.0] - 2026-07-10
 
 ### Fixed
@@ -374,7 +547,8 @@ entire sync infrastructure can be shared across the GLANCE app family.
 - TypeScript declarations in `types/index.d.ts`.
 - WebDAV CORS proxy handler in `api/webdav-proxy.js`.
 
-[Unreleased]: https://github.com/glance-apps/glance-sync/compare/v1.6.0...HEAD
+[Unreleased]: https://github.com/glance-apps/glance-sync/compare/v1.6.1...HEAD
+[1.6.1]: https://github.com/glance-apps/glance-sync/compare/v1.6.0...v1.6.1
 [1.6.0]: https://github.com/glance-apps/glance-sync/compare/v1.5.3...v1.6.0
 [1.5.3]: https://github.com/glance-apps/glance-sync/compare/v1.5.2...v1.5.3
 [1.5.2]: https://github.com/glance-apps/glance-sync/compare/v1.5.1...v1.5.2

package/README.md

@@ -156,6 +156,7 @@ Pass `encryptionEnabled: true` in the sync config object stored via `engine.setC
 |--------|-------------|
 | `webdavFetch(config)` | Creates a transport-selecting WebDAV fetcher. Prefers Android HTTP bridge → Electron proxy → CORS proxy, in that order. |
 | `createProviders(config)` | Creates cloud sync provider objects (`nextcloud`, `koofr`, `webdav`). |
+| `normalizeEtag(raw)` | Normalizes a raw ETag header value for If-Match use: strips a weak-validator prefix (`W/"abc"` → `"abc"`) and the content-coding suffixes some servers append inside the quotes (`"abc-gzip"` / `"abc-br"` → `"abc"`). Quotes are preserved; `null`/`undefined` pass through unchanged. |
 
 ### Auto-backup
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glance-apps/sync",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "license": "MIT",
   "type": "module",
   "main": "src/index.js",

package/src/dbEngine.js

@@ -36,6 +36,46 @@ const ts = (v) => {
   return Number.isNaN(t) ? 0 : t;
 };
 
+// randomUUID is missing in some non-secure-context WebViews; getRandomValues
+// is everywhere the rest of this package's crypto already runs.
+const randomUUID = () => {
+  if (typeof globalThis.crypto?.randomUUID === 'function') return globalThis.crypto.randomUUID();
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+};
+
+/**
+ * The package-owned stable device identifier (vault Phase 1.4b). Generated
+ * once per storageKeyPrefix and persisted under `{prefix}-device-id`; used
+ * for both the device cursor and per-account enrollment, so the identity a
+ * credential is bound to is the same one the server's tombstone-GC cursor
+ * tracks. An explicit config.deviceId still wins for callers that already
+ * manage their own.
+ *
+ * Existing installs that never passed a deviceId get one generated on first
+ * launch of this version — which also means their device cursor starts
+ * updating for the first time (updateDeviceCursor previously no-oped
+ * silently without a deviceId).
+ */
+export const getOrCreateDeviceId = (storageKeyPrefix) => {
+  if (!storageKeyPrefix) throw new Error('getOrCreateDeviceId: storageKeyPrefix is required');
+  const key = `${storageKeyPrefix}-device-id`;
+  let id = localStorage.getItem(key);
+  if (!id) {
+    id = randomUUID();
+    localStorage.setItem(key, id);
+  }
+  return id;
+};
+
+// Storage keys shared between this engine and the connect/recovery flow in
+// vaultConnect.js. Defined once here so the two modules cannot drift.
+export const vaultCredentialKey = (storageKeyPrefix) => `${storageKeyPrefix}-vault-credential`;
+export const credentialHaltKey = (storageKeyPrefix) => `${storageKeyPrefix}-db-sync-credential-halt`;
+
 /**
  * Creates the database sync engine.
  *
@@ -46,7 +86,7 @@ const ts = (v) => {
  * @param {string}  config.vaultUrl
  * @param {string}  config.vaultToken
  * @param {string}  config.accountId
- * @param {string} [config.deviceId]
+ * @param {string} [config.deviceId]        - stable device identity; defaults to the persisted package-owned id (getOrCreateDeviceId)
  * @param {string}  config.cryptoDBName     - device storage name for the root key
  * @param {Function|null} [config.nativeGetSyncKey]
  * @param {Function|null} [config.nativeStoreSyncKey]
@@ -61,7 +101,7 @@ const ts = (v) => {
  *
  * Event callbacks (optional):
  * @param {Function} [config.onStatusChange]
- * @param {Function} [config.onError]      - (message, code, isHardStop) called with code 'KEY_MISMATCH' on a wrong key, or 'VERIFIER_UNSUPPORTED' when the server can't host the verifier
+ * @param {Function} [config.onError]      - (message, code, isHardStop) called with code 'KEY_MISMATCH' on a wrong key, 'VERIFIER_UNSUPPORTED' when the server can't host the verifier, or 'CREDENTIAL_INVALID' (isHardStop true) when the server rejects this device's credential — the cycle then halts until Phase 2.2 recovery exists
  * @param {Function} [config.onRowsSkipped] - (count, entityIds) called when a cycle skipped undecryptable rows
  * @param {boolean}  [config.allowUnverified=false] - operator escape hatch: downgrade VERIFIER_UNSUPPORTED to a logged warning and proceed (unsafe; off by default)
  */
@@ -104,6 +144,9 @@ export const createDbSyncEngine = (config) => {
   if (typeof applyRemoteDelete !== 'function') throw new Error('createDbSyncEngine: applyRemoteDelete is required');
 
   const app = vaultApp || appId;
+  // Package-owned device identity: an explicit config.deviceId wins, else the
+  // persisted per-prefix id (generated on first use).
+  const resolvedDeviceId = deviceId || getOrCreateDeviceId(storageKeyPrefix);
   const lastModifiedOf = typeof getEntityLastModified === 'function'
     ? getEntityLastModified
     : (entity) => entity && entity.lastModified;
@@ -135,9 +178,25 @@ export const createDbSyncEngine = (config) => {
   // on pull so one bad row cannot wedge the cycle, and re-attempted each cycle
   // so a row recovers if the correct key later becomes available.
   const KEY_QUARANTINE = `${storageKeyPrefix}-db-sync-quarantine`;
+  // KEY_CRED_HALT persists the credential-rejected stop state (vault Phase
+  // 1.4b), as { message, at }. Once the server has said 401 "invalid
+  // credential", retrying is pure hammering — the only way out is
+  // user-initiated re-enrollment (recoverVaultSyncEngine, Phase 2.2), which
+  // is the ONLY code that clears this key, and only after a verified
+  // successful enrollment. Shared-mode auth failures (401 "invalid device
+  // token") do NOT set it — those are operator config problems that a config
+  // fix resolves, so they keep the ordinary retry behavior.
+  const KEY_CRED_HALT = credentialHaltKey(storageKeyPrefix);
+  const KEY_CREDENTIAL = vaultCredentialKey(storageKeyPrefix);
 
   // ── In-memory guards ──────────────────────────────────────────────────────
   let syncing = false;
+  // Set when this instance's bearer is proven superseded (see
+  // isBearerSuperseded): the instance goes inert IN MEMORY ONLY — it never
+  // touches the shared halt key, and it stops generating network traffic. A
+  // stale reference the app forgot after recovery dies quietly instead of
+  // hammering the server with a dead credential.
+  let supersededInert = false;
   // Per-session cache: once the derived root key is proven against the account's
   // existing data (Part A), we never re-verify for the life of this engine.
   let verified = false;
@@ -219,6 +278,46 @@ export const createDbSyncEngine = (config) => {
     writeQuarantine(getQuarantine().filter((q) => q.entityId !== entityId));
   };
 
+  // Credential-rejected stop state. Read/written only here; deliberately no
+  // clear function on the engine (recovery is Phase 2.2).
+  const getCredentialHalt = () => {
+    const raw = localStorage.getItem(KEY_CRED_HALT);
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  };
+  const setCredentialHalt = (message) => {
+    localStorage.setItem(KEY_CRED_HALT, JSON.stringify({ message, at: new Date().toISOString() }));
+  };
+
+  // The halt-set identity rule (Phase 2.2). The halt key is shared by every
+  // engine instance on this device, so a STALE instance — one still holding a
+  // credential that recovery has since replaced — must not be able to re-set
+  // the halt and brick the recovered engine. A superseded bearer is provable:
+  // the stored credential record exists, is readable, and holds a DIFFERENT
+  // credential than this engine speaks.
+  //
+  // THE RULE FAILS TOWARD HALTING, deliberately: halt when the record is
+  // missing or unreadable, or when it matches this engine's bearer. Skip the
+  // halt ONLY on that provable-superseded case. The naive simplification
+  // ("no record -> no halt") would leave an engine with a dead credential and
+  // a wiped record retrying forever — exactly what the halt exists to
+  // prevent. Do not simplify this condition.
+  const isBearerSuperseded = () => {
+    if (typeof vaultToken !== 'string' || vaultToken === '') return false;
+    const raw = localStorage.getItem(KEY_CREDENTIAL);
+    if (!raw) return false;
+    try {
+      const rec = JSON.parse(raw);
+      return !!(rec && typeof rec.credential === 'string' && rec.credential !== vaultToken);
+    } catch {
+      return false;
+    }
+  };
+
   // markDirty: called by the app on every local write (and at creation time for
   // insert-only types). Idempotent and synchronous so it can run inside the
   // app's own write path.
@@ -253,9 +352,14 @@ export const createDbSyncEngine = (config) => {
   // typed, retryable code instead of being mislabeled "update your server".
   const isClientNotReady = (err) =>
     err && (err.code === 'ACCOUNT_ID_REQUIRED' || err.code === 'PASSPHRASE_REQUIRED');
+  // Likewise a rejected credential (401 "invalid credential") is an auth
+  // outcome, not a capability one: pass it through so the cycle's halt
+  // handling sees it — and so allowUnverified can never wave a revoked
+  // device through.
+  const isPassThrough = (err) => isClientNotReady(err) || (err && err.code === 'CREDENTIAL_INVALID');
 
   const verifierUnsupported = (cause) => {
-    if (isClientNotReady(cause)) throw cause;
+    if (isPassThrough(cause)) throw cause;
     if (allowUnverified) {
       // eslint-disable-next-line no-console
       console.warn(`[${appId}] db sync proceeding UNVERIFIED: the server cannot host the key verifier (${KEYCHECK_ENTITY_ID}).`, cause);
@@ -564,11 +668,10 @@ export const createDbSyncEngine = (config) => {
   // progress is the conservative value for server-side tombstone GC, since it
   // never lets the server reclaim a tombstone this device has not yet seen.
   const updateDeviceCursor = async () => {
-    if (!deviceId) return { updated: false };
     try {
       return await vault.device(app, {
         accountId,
-        deviceId,
+        deviceId: resolvedDeviceId,
         lastSeenSeq: getHighWaterMark(),
       });
     } catch (err) {
@@ -582,6 +685,22 @@ export const createDbSyncEngine = (config) => {
   const dbSyncCycle = async () => {
     const cfg = getConfig();
     if (cfg && cfg.enabled === false) return;
+    // A superseded stale instance is dead silently: no network, and no
+    // onError either — its failure was surfaced once when detected, and
+    // re-surfacing would fight the recovered engine's own status/error
+    // signals through the app's shared callbacks.
+    if (supersededInert) {
+      return { applied: 0, skipped: 0, skippedEntityIds: [], superseded: true };
+    }
+    // Standing credential-rejected stop: no network calls at all. The state is
+    // re-surfaced on every attempted cycle so a UI constructed after the halt
+    // (e.g. next app launch) still learns about it through its own onError.
+    const halt = getCredentialHalt();
+    if (halt) {
+      onError?.(halt.message, 'CREDENTIAL_INVALID', true);
+      onStatusChange?.('error');
+      return { applied: 0, skipped: 0, skippedEntityIds: [], halted: true };
+    }
     if (syncing) return;
     syncing = true;
     onStatusChange?.('uploading');
@@ -607,7 +726,28 @@ export const createDbSyncEngine = (config) => {
       // eslint-disable-next-line no-console
       console.error(`[${appId}] db sync cycle error:`, err);
       const code = err && err.code ? err.code : 'NETWORK_ERROR';
-      onError?.(err?.message || String(err), code, false);
+      if (code === 'CREDENTIAL_INVALID') {
+        // The server rejected this engine's credential. Under NO circumstances
+        // does the engine re-enroll here: enrollment is non-idempotent, so an
+        // automatic retry would mint a server row per failure and would let a
+        // revoked device silently re-admit itself. Recovery is user-initiated
+        // only (recoverVaultSyncEngine).
+        if (isBearerSuperseded()) {
+          // This instance was replaced by recovery and the app kept a stale
+          // reference. Go inert in memory — surfaced once, then silent — and
+          // leave the shared halt key alone so the recovered engine keeps
+          // syncing.
+          supersededInert = true;
+          onError?.(err?.message || String(err), 'CREDENTIAL_INVALID', true);
+        } else {
+          // Persist the stop so no future cycle retries (a rejected
+          // credential never heals by retry) and surface it as a hard stop.
+          setCredentialHalt(err?.message || String(err));
+          onError?.(err?.message || String(err), 'CREDENTIAL_INVALID', true);
+        }
+      } else {
+        onError?.(err?.message || String(err), code, false);
+      }
       onStatusChange?.('error');
       return { applied: 0, skipped: 0, skippedEntityIds: [] };
     } finally {
@@ -650,6 +790,14 @@ export const createDbSyncEngine = (config) => {
     isSyncing:        () => syncing,
     isKeyVerified:    () => verified,
     hasEncryptionReady: hasDbRootKey,
+    // Credential-rejected stop state. Cleared only by recoverVaultSyncEngine
+    // after a verified successful re-enrollment — never by the engine.
+    isCredentialHalted: () => getCredentialHalt() !== null,
+    getCredentialHalt,
+    // True once this instance proved its bearer was superseded by recovery
+    // and went inert (in-memory only; a fresh instance is unaffected).
+    isSuperseded: () => supersededInert,
+    deviceId: resolvedDeviceId,
 
     // Sub-modules
     vault,

package/src/engine.js

@@ -314,7 +314,9 @@ export const createSyncEngine = (config) => {
 
     // Inner helper: download, merge, apply, upload (if anything changed).
     // Returns true if a reload was triggered (caller should bail).
-    const doCycle = async (overrideEtag) => {
+    // skipIfMatch forces an unconditional upload (no If-Match) — the
+    // last-writer-wins fallback used after two consecutive 412s.
+    const doCycle = async (overrideEtag, { skipIfMatch = false } = {}) => {
       const downloaded = await provider.download(cfg);
       if (!downloaded) {
         // Empty remote — seed it with local state.
@@ -365,7 +367,7 @@ export const createSyncEngine = (config) => {
         await upload({
           prebuiltPayload: mergedPayload,
           skipLockCheck: true,
-          etag: etag || overrideEtag || null,
+          etag: skipIfMatch ? null : (etag || overrideEtag || null),
         });
 
         if (localChanged) {
@@ -425,6 +427,7 @@ export const createSyncEngine = (config) => {
         // jitter (1–3 s) to reduce collision probability, then retry once.
         const jitterMs = 1000 + Math.random() * 2000;
         await new Promise(r => setTimeout(r, jitterMs));
+        let finalErr = null;
         try {
           await doCycle(null);
           downloadErrorCount = 0;
@@ -432,12 +435,35 @@ export const createSyncEngine = (config) => {
         } catch (retryErr) {
           // eslint-disable-next-line no-console
           console.error(`[${appId}] cloud sync retry after 412 failed:`, retryErr);
+          if (classifyError(retryErr).code === 'PRECONDITION_FAILED') {
+            // Two consecutive 412s with fresh ETags is not a write race — it's
+            // a server whose ETags can't round-trip through If-Match (e.g. a
+            // proxy mangling them in a way normalizeEtag doesn't cover), and a
+            // conditional retry can never succeed. Run one last cycle whose
+            // upload omits If-Match (last-writer-wins). The payload is the
+            // merge of local state with the remote fetched milliseconds
+            // earlier in the same cycle, so the lost-update window is tiny —
+            // far safer than a permanently wedged sync.
+            try {
+              await doCycle(null, { skipIfMatch: true });
+              downloadErrorCount = 0;
+              downloadBackoffUntil = 0;
+            } catch (fallbackErr) {
+              // eslint-disable-next-line no-console
+              console.error(`[${appId}] cloud sync unconditional fallback after 412 failed:`, fallbackErr);
+              finalErr = fallbackErr;
+            }
+          } else {
+            finalErr = retryErr;
+          }
+        }
+        if (finalErr) {
           // Apply the same exponential backoff used for other transient errors so
           // the engine backs off rather than hammering the server every poll cycle.
           downloadErrorCount += 1;
           const ms = Math.min(30 * Math.pow(2, downloadErrorCount - 1), MAX_DOWNLOAD_BACKOFF_S) * 1000;
           downloadBackoffUntil = Date.now() + ms;
-          onError?.(formatErrorMessage(classifyError(retryErr)), classifyError(retryErr).code, false);
+          onError?.(formatErrorMessage(classifyError(finalErr)), classifyError(finalErr).code, false);
           onStatusChange?.('error');
           scheduleAutoRevert('error', ERROR_HOLD_MS);
         }

package/src/index.js

@@ -24,7 +24,7 @@ export {
 
 // webdavFetch and createProviders are internal to the engine (Step 6) but
 // exported here so shims can wire them before the engine exists.
-export { webdavFetch, createProviders } from './providers.js';
+export { webdavFetch, createProviders, normalizeEtag } from './providers.js';
 
 export {
   createAutoBackupDB,
@@ -40,8 +40,21 @@ export {
 } from './engine.js';
 
 // Phase 3: database transport (selected via transportMode: 'database').
-export { createDbSyncEngine } from './dbEngine.js';
-export { createVaultClient } from './vaultClient.js';
+export { createDbSyncEngine, getOrCreateDeviceId } from './dbEngine.js';
+export {
+  createVaultClient,
+  // Per-account auth substrate (vault Phase 1.4b): unauthenticated auth-mode
+  // discovery and the bootstrap-secret -> per-device-credential exchange.
+  fetchVaultHealth,
+  enrollVaultDevice,
+} from './vaultClient.js';
+// The packaged connect flow: discover -> branch -> enroll if needed ->
+// persist credential -> build engine. Apps hand it a secret or token and get
+// a working engine back; the bootstrap secret never touches storage.
+// recoverVaultSyncEngine (Phase 2.2) is the halt-gated, user-initiated exit
+// from a rejected credential: re-enrollment that rotates the dead credential
+// away server-side.
+export { connectVaultSyncEngine, recoverVaultSyncEngine } from './vaultConnect.js';
 export {
   setupDbRootKey,
   initDbRootKey,

package/src/providers.js

@@ -89,6 +89,39 @@ export const webdavFetch = (config) => async (method, targetUrl, authHeaders, bo
   });
 };
 
+// ---------------------------------------------------------------------------
+// ETag normalization
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalizes an ETag as captured from a GET response so it can be echoed back
+ * in If-Match. Proxies and content-encoding filters mangle ETags in ways that
+ * make the stored entity's validator unreachable:
+ *   - Apache mod_deflate/mod_brotli append `-gzip`/`-br` inside the quotes
+ *     (`"abc"` becomes `"abc-gzip"` on gzip-encoded responses).
+ *   - nginx's gzip filter downgrades strong ETags to weak (`W/"abc"`), and
+ *     If-Match requires strong comparison.
+ * Either way, a PUT with the mangled value 412s forever. Stripping the weak
+ * prefix and the known coding suffixes recovers the entity's real validator.
+ *
+ * Surrounding quotes are preserved; null/undefined pass through unchanged.
+ *
+ * @param {string|null|undefined} raw - raw ETag header value
+ * @returns {string|null|undefined} normalized ETag
+ */
+export function normalizeEtag(raw) {
+  if (raw == null) return raw;
+  let etag = raw;
+  if (etag.startsWith('W/')) etag = etag.slice(2);
+  if (etag.length >= 2 && etag.startsWith('"') && etag.endsWith('"')) {
+    const inner = etag.slice(1, -1).replace(/-(gzip|br)$/, '');
+    etag = `"${inner}"`;
+  } else {
+    etag = etag.replace(/-(gzip|br)$/, '');
+  }
+  return etag;
+}
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -96,7 +129,7 @@ export const webdavFetch = (config) => async (method, targetUrl, authHeaders, bo
 async function parseDownloadResponse(res, engineConfig) {
   const parsed = await res.json();
   const payload = isEncryptedEnvelope(parsed) ? await decryptData(parsed, engineConfig) : parsed;
-  const etag = res.headers.get('etag') || null;
+  const etag = normalizeEtag(res.headers.get('etag')) || null;
   return { payload, etag };
 }