@glance-apps/sync 1.6.1 → 1.8.0

package/CHANGELOG.md

@@ -7,6 +7,139 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glance-apps/sync",
-  "version": "1.6.1",
+  "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/index.js

@@ -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/vaultClient.js

@@ -15,6 +15,16 @@
 //   GET    /salt/:accountId                      fetch the account root-key salt
 //   PUT    /salt/:accountId                      register a salt (first-write-wins)
 //
+// Auth models (vault Phase 1.4b — the client half of per-account credentials):
+// a vault runs in one of two modes, discoverable unauthenticated via
+// fetchVaultHealth. In "shared" mode every device presents the instance-wide
+// device token as the Bearer value. In "per-account" mode each device first
+// exchanges the admin-configured bootstrap secret for its own credential at
+// POST /enroll (enrollVaultDevice below) and presents THAT as the Bearer
+// value — the wire shape of every scoped call is identical in both modes, so
+// createVaultClient is mode-agnostic: callers pass the shared token or the
+// per-device credential as vaultToken and nothing else changes.
+//
 // Salts cross the wire as base64 in a { salt } field. The client converts to and
 // from Uint8Array at the boundary so callers always deal in bytes.
 
@@ -29,23 +39,138 @@ class VaultError extends Error {
   }
 }
 
+// Shared by createVaultClient and the standalone pre-credential helpers below.
+const resolveFetch = (fetchImpl, context) => {
+  const doFetch = fetchImpl || globalThis.fetch;
+  if (typeof doFetch !== 'function') {
+    throw new Error(`${context}: no fetch implementation available`);
+  }
+  return doFetch;
+};
+
+const requireBaseUrl = (vaultUrl, context) => {
+  if (typeof vaultUrl !== 'string' || vaultUrl.trim() === '') {
+    throw new Error(`${context}: vaultUrl is required`);
+  }
+  return vaultUrl.replace(/\/+$/, '');
+};
+
+/**
+ * Fetches the vault's public health document. Unauthenticated — /healthz is
+ * the one endpoint that never requires a token, in either auth mode, so this
+ * is safe to call before the user has pasted anything.
+ *
+ * `authMode` is normalized to 'shared' when the field is absent: servers that
+ * predate it are all shared-token servers, so a client can branch on
+ * `health.authMode === 'per-account'` against any server version.
+ *
+ * @param {object} config
+ * @param {string} config.vaultUrl - base URL of the GLANCEvault server
+ * @param {Function} [config.fetchImpl] - fetch implementation (defaults to global fetch)
+ * @returns {Promise<{ status: string, version: string, schemaVersion: number, authMode: 'shared'|'per-account' }>}
+ */
+export async function fetchVaultHealth({ vaultUrl, fetchImpl } = {}) {
+  const base = requireBaseUrl(vaultUrl, 'fetchVaultHealth');
+  const doFetch = resolveFetch(fetchImpl, 'fetchVaultHealth');
+  const res = await doFetch(`${base}/healthz`, { method: 'GET', headers: {} });
+  if (!res.ok) {
+    throw new VaultError(`health check failed: ${res.status}`, res.status);
+  }
+  const body = await res.json();
+  return {
+    ...body,
+    authMode: typeof body.authMode === 'string' ? body.authMode : 'shared',
+  };
+}
+
+/**
+ * Enrolls this device with a per-account vault: exchanges the admin-configured
+ * bootstrap secret for the device's own credential (POST /enroll). The secret
+ * rides in the request body, never the query string (query strings appear in
+ * proxy logs), and no Authorization header is sent — the secret IS this
+ * route's authentication.
+ *
+ * The returned `credential` appears in the response ONCE and is never
+ * retrievable again (the server stores only a hash). Callers must persist it
+ * and then DISCARD the bootstrap secret: nothing ever asks for the secret
+ * again, and a device that loses its credential simply re-enrolls — every
+ * successful call mints a fresh credential. Pass the credential as
+ * `vaultToken` to createVaultClient / the DB engine; the wire shape of scoped
+ * calls is unchanged.
+ *
+ * Typed failures:
+ *  - `ENROLLMENT_REJECTED` (401): the server did not accept the secret.
+ *  - `ENROLLMENT_UNSUPPORTED` (404): the server does not offer enrollment —
+ *    it runs shared auth mode (the route is registration-gated off) or
+ *    predates per-account auth. Check fetchVaultHealth().authMode first to
+ *    distinguish this up front.
+ *  - `VAULT_ERROR` with `status` for any other non-2xx response.
+ *
+ * @param {object} config
+ * @param {string} config.vaultUrl - base URL of the GLANCEvault server
+ * @param {string} config.enrollmentSecret - the admin-configured bootstrap secret
+ * @param {string} config.accountId - account to bind the credential to
+ * @param {string} config.deviceId - stable identifier for this device
+ * @param {Function} [config.fetchImpl] - fetch implementation (defaults to global fetch)
+ * @returns {Promise<{ credentialId: string, credential: string, accountId: string, deviceId: string, createdAt: string }>}
+ */
+export async function enrollVaultDevice({ vaultUrl, enrollmentSecret, accountId, deviceId, fetchImpl } = {}) {
+  const base = requireBaseUrl(vaultUrl, 'enrollVaultDevice');
+  const doFetch = resolveFetch(fetchImpl, 'enrollVaultDevice');
+
+  // Fail typed and off the wire on missing fields, like requireAccountId: the
+  // server rejects them with a 400 anyway, but a client-side throw is clearer
+  // and never puts a malformed enrollment on the network. Values are sent
+  // byte-exact — validation only rejects missing/whitespace-only input, it
+  // never trims what goes on the wire (matching the server's semantics).
+  const requireField = (value, name, code) => {
+    if (typeof value !== 'string' || value.trim() === '') {
+      const err = new Error(`enrollVaultDevice: ${name} is required but was missing or empty.`);
+      err.code = code;
+      throw err;
+    }
+  };
+  requireField(enrollmentSecret, 'enrollmentSecret', 'ENROLLMENT_SECRET_REQUIRED');
+  requireField(accountId, 'accountId', 'ACCOUNT_ID_REQUIRED');
+  requireField(deviceId, 'deviceId', 'DEVICE_ID_REQUIRED');
+
+  const res = await doFetch(`${base}/enroll`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ enrollmentSecret, accountId, deviceId }),
+  });
+
+  if (res.status === 401) {
+    const err = new VaultError('enroll failed: enrollment secret rejected', 401);
+    err.code = 'ENROLLMENT_REJECTED';
+    throw err;
+  }
+  if (res.status === 404) {
+    // Express's default 404: the /enroll route is only registered in
+    // per-account mode, so this server cannot enroll anyone.
+    const err = new VaultError('enroll failed: this server does not offer enrollment (shared auth mode?)', 404);
+    err.code = 'ENROLLMENT_UNSUPPORTED';
+    throw err;
+  }
+  if (!res.ok) {
+    throw new VaultError(`enroll failed: ${res.status}`, res.status);
+  }
+  return res.json();
+}
+
 /**
  * Creates a vault client bound to a server URL and token.
  *
  * @param {object} config
  * @param {string} config.vaultUrl   - base URL of the GLANCEvault server
- * @param {string} config.vaultToken - Bearer token
+ * @param {string} config.vaultToken - Bearer token: the shared device token
+ *   (shared mode) or this device's enrolled credential (per-account mode)
  * @param {Function} [config.fetchImpl] - fetch implementation (defaults to global fetch)
  */
 export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
-  if (!vaultUrl)   throw new Error('createVaultClient: vaultUrl is required');
+  const base = requireBaseUrl(vaultUrl, 'createVaultClient');
   if (!vaultToken) throw new Error('createVaultClient: vaultToken is required');
-  const doFetch = fetchImpl || globalThis.fetch;
-  if (typeof doFetch !== 'function') {
-    throw new Error('createVaultClient: no fetch implementation available');
-  }
-
-  const base = vaultUrl.replace(/\/+$/, '');
+  const doFetch = resolveFetch(fetchImpl, 'createVaultClient');
   const authHeaders = (extra = {}) => ({
     Authorization: `Bearer ${vaultToken}`,
     ...extra,
@@ -66,9 +191,33 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
     return res;
   };
 
+  // Error-body inspection is BEST-EFFORT and deliberately narrow. The server
+  // made the 401 body wording the only signal separating shared mode's
+  // "invalid device token" (server misconfigured / wrong token) from
+  // per-account mode's "invalid credential" (this device must re-enroll —
+  // a Phase 2.2 recovery flow; nothing in this package re-enrolls). Only that
+  // exact wording upgrades the code to CREDENTIAL_INVALID; a missing,
+  // non-JSON, or unrecognized body degrades to the generic VAULT_ERROR, so
+  // the client's correctness never depends on server wording.
+  const errorFromResponse = async (res, context) => {
+    let bodyError = null;
+    try {
+      const body = await res.json();
+      if (body && typeof body.error === 'string') bodyError = body.error;
+    } catch {
+      // Empty or non-JSON error body: keep the generic classification.
+    }
+    if (res.status === 401 && bodyError === 'invalid credential') {
+      const err = new VaultError(`${context} failed: 401 — the server rejected this device's credential`, 401);
+      err.code = 'CREDENTIAL_INVALID';
+      return err;
+    }
+    return new VaultError(`${context} failed: ${res.status}`, res.status);
+  };
+
   const jsonOrThrow = async (res, context) => {
     if (!res.ok) {
-      throw new VaultError(`${context} failed: ${res.status}`, res.status);
+      throw await errorFromResponse(res, context);
     }
     return res.json();
   };

package/src/vaultConnect.js

@@ -0,0 +1,391 @@
+// The packaged vault connect flow (vault Phase 1.4b).
+//
+// This is the front door for building a DB sync engine against a GLANCEvault
+// server without the app implementing auth-mode discovery, enrollment,
+// credential persistence, or bootstrap-secret discard itself. The app hands
+// over whatever it has — the shared device token, a bootstrap secret, or
+// nothing beyond a previously connected state — and gets a working engine
+// back:
+//
+//   1. DISCOVER  GET /healthz (unauthenticated) → 'shared' | 'per-account'.
+//                A missing authMode field means shared (every server that
+//                predates the field is a shared-token server), so version
+//                skew is an ordinary case, not an error.
+//   2. BRANCH    shared      → use config.vaultToken, exactly as before 1.4b.
+//                per-account → use the persisted credential; enroll with the
+//                bootstrap secret only when no credential is stored yet.
+//   3. ENROLL    POST /enroll, then persist the credential DURABLY before
+//                treating enrollment as complete (enrollment is
+//                non-idempotent — every call mints a server row).
+//   4. BUILD     createDbSyncEngine with the resolved Bearer value.
+//
+// SECRET LIFETIME: the bootstrap secret exists inside this module only as the
+// `enrollmentSecret` binding for the duration of one connectVaultSyncEngine
+// call. It is sent in the enroll request body and nowhere else: never written
+// to any storage, never placed on the engine config, never logged, never
+// retained. When the call returns, the package holds no reference. (The app
+// still owns the copy it passed in — dropping that is the app's one remaining
+// obligation.)
+//
+// NO AUTOMATIC RE-ENROLLMENT, on any path. Once a credential is stored for
+// this (server, account), this flow always uses it and never enrolls again —
+// even when the credential has been rejected and the engine is halted
+// (CREDENTIAL_INVALID). Re-enrolling on failure would mint a credential row
+// per attempt and would let a revoked device silently re-admit itself, which
+// is exactly what revocation (vault Phase 2.1) must be able to prevent.
+// Recovery from a rejected credential is Phase 2.2.
+
+import { fetchVaultHealth, enrollVaultDevice } from './vaultClient.js';
+import {
+  createDbSyncEngine,
+  getOrCreateDeviceId,
+  vaultCredentialKey,
+  credentialHaltKey,
+} from './dbEngine.js';
+
+const typedError = (message, code) => {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+};
+
+// Storage canary: prove the credential slot is writable BEFORE minting.
+// Enrollment is non-idempotent, so if device storage cannot hold the
+// credential we must find out before the server creates a row, not after.
+// (A crash between mint and persist can still orphan one row; since 2.1 the
+// next successful enrollment with the same (accountId, deviceId) supersedes
+// it, so even that is no longer a live orphan. Broken storage must still not
+// orphan one per attempt.)
+const ensureCredentialSlotWritable = (key, context) => {
+  // The slot's prior contents are RESTORED, not discarded: during recovery
+  // the slot holds the stale record, and a failed enrollment after the canary
+  // must leave that record exactly as it was (a failed recovery leaves the
+  // device halted with its state intact, never ambiguous).
+  const prior = localStorage.getItem(key);
+  const canary = JSON.stringify({ canary: true });
+  try {
+    localStorage.setItem(key, canary);
+    if (localStorage.getItem(key) !== canary) throw new Error('read-back mismatch');
+    if (prior === null) localStorage.removeItem(key);
+    else localStorage.setItem(key, prior);
+  } catch {
+    throw typedError(
+      `${context}: device storage cannot persist a credential; refusing to enroll.`,
+      'CREDENTIAL_PERSIST_FAILED'
+    );
+  }
+};
+
+// Persist durably, then read back and verify, BEFORE enrollment is treated as
+// complete. Overwrites whatever was in the slot — the credential slot holds
+// exactly one record, so a stale credential never survives alongside a new
+// one. Only the credential and its metadata are written — never the secret.
+const persistCredentialRecord = (key, record, context) => {
+  try {
+    localStorage.setItem(key, JSON.stringify(record));
+    const readBack = JSON.parse(localStorage.getItem(key));
+    if (!readBack || readBack.credential !== record.credential) throw new Error('read-back mismatch');
+  } catch {
+    throw typedError(
+      `${context}: enrolled but could not persist the credential; not treating enrollment as complete.`,
+      'CREDENTIAL_PERSIST_FAILED'
+    );
+  }
+};
+
+// Byte-exact everywhere: validation only rejects missing/whitespace-only
+// values, it never trims or normalizes what is stored or sent. Whitespace-
+// distinct account ids are distinct live accounts on the server.
+const requireString = (value, name, code) => {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw typedError(`connectVaultSyncEngine: ${name} is required but was missing or empty.`, code);
+  }
+};
+
+/**
+ * Discovers the server's auth mode, resolves the Bearer value for this device
+ * (enrolling if the server is per-account and no credential is stored yet),
+ * and returns a ready sync engine.
+ *
+ * Config is DbSyncEngineConfig plus:
+ * @param {string} [config.enrollmentSecret] - bootstrap secret for first-time
+ *   enrollment against a per-account server. Ignored (and not needed) once a
+ *   credential is stored. See SECRET LIFETIME above.
+ * @param {string} [config.vaultToken] - the shared device token. Required
+ *   when the server runs shared mode; ignored against a per-account server
+ *   (the shared token authenticates nothing there).
+ *
+ * Typed failures:
+ *  - VAULT_TOKEN_REQUIRED: server is shared-mode and no vaultToken was given.
+ *  - ENROLLMENT_SECRET_REQUIRED: server is per-account, no credential is
+ *    stored, and no enrollmentSecret was given.
+ *  - CREDENTIAL_PERSIST_FAILED: device storage rejected the credential write.
+ *    When storage is detectably broken this is raised BEFORE enrolling, so a
+ *    client with broken storage does not mint a credential row per launch.
+ *  - VAULT_UNREACHABLE: discovery failed and there is no stored credential
+ *    and no vaultToken to fall back on.
+ *  - Plus everything enrollVaultDevice can throw (ENROLLMENT_REJECTED, ...).
+ *
+ * @returns {Promise<{ engine: object, authMode: 'shared'|'per-account'|null,
+ *   enrolled: boolean, deviceId: string }>}
+ *   authMode is null when discovery failed and the flow fell back to the last
+ *   known state; `enrolled` is true only when this call minted a credential.
+ */
+export async function connectVaultSyncEngine(config = {}) {
+  // The secret is destructured OFF the config here so the object handed to
+  // createDbSyncEngine below can never carry it.
+  const { enrollmentSecret, ...engineConfig } = config;
+  const { storageKeyPrefix, vaultUrl, vaultToken, accountId, fetchImpl } = engineConfig;
+
+  requireString(storageKeyPrefix, 'storageKeyPrefix', 'STORAGE_KEY_PREFIX_REQUIRED');
+  requireString(vaultUrl, 'vaultUrl', 'VAULT_URL_REQUIRED');
+  requireString(accountId, 'accountId', 'ACCOUNT_ID_REQUIRED');
+
+  // Same normalization the vault client applies to every request URL, so the
+  // stored credential's server binding survives a trailing-slash difference.
+  const base = vaultUrl.replace(/\/+$/, '');
+  const deviceId = engineConfig.deviceId || getOrCreateDeviceId(storageKeyPrefix);
+  const KEY_CREDENTIAL = vaultCredentialKey(storageKeyPrefix);
+
+  // A stored credential is only usable for the exact (server, account) it was
+  // minted for: the server binds it to an account and 403s any other claim.
+  const readStoredCredential = () => {
+    const raw = localStorage.getItem(KEY_CREDENTIAL);
+    if (!raw) return null;
+    try {
+      const rec = JSON.parse(raw);
+      return rec && rec.credential && rec.vaultUrl === base && rec.accountId === accountId ? rec : null;
+    } catch {
+      return null;
+    }
+  };
+
+  // 1. Discover. Failure (unreachable, non-JSON, non-2xx) is not fatal here:
+  // an offline launch must behave exactly as pre-1.4b — build the engine from
+  // whatever auth state exists and let the first sync surface any error.
+  let authMode = null;
+  try {
+    const health = await fetchVaultHealth({ vaultUrl: base, fetchImpl });
+    // Only the two known modes are acted on; a future unknown mode string
+    // falls through to the last-known-state path rather than being guessed at.
+    if (health.authMode === 'shared' || health.authMode === 'per-account') {
+      authMode = health.authMode;
+    }
+  } catch {
+    authMode = null;
+  }
+
+  const stored = readStoredCredential();
+  let token;
+  let enrolled = false;
+
+  if (authMode === 'per-account') {
+    if (stored) {
+      token = stored.credential;
+    } else {
+      // First contact with a per-account server: enrollment needs the secret.
+      // The shared token is deliberately NOT a fallback — it authenticates
+      // nothing on this server and sending it just produces a confusing 401.
+      if (typeof enrollmentSecret !== 'string' || enrollmentSecret.trim() === '') {
+        throw typedError(
+          'connectVaultSyncEngine: this server requires per-device enrollment and no credential is stored — pass enrollmentSecret.',
+          'ENROLLMENT_SECRET_REQUIRED'
+        );
+      }
+
+      ensureCredentialSlotWritable(KEY_CREDENTIAL, 'connectVaultSyncEngine');
+
+      const enrollment = await enrollVaultDevice({
+        vaultUrl: base,
+        enrollmentSecret,
+        accountId,
+        deviceId,
+        fetchImpl,
+      });
+
+      persistCredentialRecord(KEY_CREDENTIAL, {
+        credentialId: enrollment.credentialId,
+        credential: enrollment.credential,
+        accountId,
+        deviceId,
+        vaultUrl: base,
+        createdAt: enrollment.createdAt,
+      }, 'connectVaultSyncEngine');
+
+      token = enrollment.credential;
+      enrolled = true;
+    }
+  } else if (authMode === 'shared') {
+    // The default path, unchanged from today. A stored credential from an
+    // earlier per-account life of this server is ignored (never sent to a
+    // shared-mode server) but kept in storage in case the operator switches
+    // back.
+    if (typeof vaultToken !== 'string' || vaultToken.trim() === '') {
+      throw typedError(
+        'connectVaultSyncEngine: this server uses a shared device token — pass vaultToken.',
+        'VAULT_TOKEN_REQUIRED'
+      );
+    }
+    token = vaultToken;
+  } else {
+    // Discovery failed: fall back to the last known auth state, which is
+    // byte-for-byte the pre-1.4b behavior for existing installs (build with
+    // the token you have; the first sync surfaces any real problem).
+    token = stored ? stored.credential : vaultToken;
+    if (typeof token !== 'string' || token.trim() === '') {
+      throw typedError(
+        `connectVaultSyncEngine: could not reach ${base}/healthz and no stored credential or vaultToken exists to fall back on.`,
+        'VAULT_UNREACHABLE'
+      );
+    }
+  }
+
+  const engine = createDbSyncEngine({ ...engineConfig, deviceId, vaultToken: token });
+  return { engine, authMode, enrolled, deviceId };
+}
+
+/**
+ * The exit from the credential halt (Phase 2.2): USER-INITIATED re-enrollment
+ * with the bootstrap secret, against a per-account server. Call this only
+ * from a deliberate UI action in which the user supplied the secret — never
+ * from a startup path, a retry path, or an error handler. Two structural
+ * guards enforce that: the package holds no secret (recovery cannot run
+ * without one being supplied fresh), and the call REFUSES unless the device
+ * is actually halted, so it cannot be wired in as an on-demand rotator.
+ *
+ * Order of operations — each failure leaves the device HALTED, never
+ * ambiguous, and the halt is cleared only after a verified success:
+ *   1. halt gate           (NOT_HALTED if the device isn't halted)
+ *   2. deviceId resolution (stale record's deviceId is ground truth — see below)
+ *   3. mode guard          (per-account only; NO fallback: VAULT_UNREACHABLE /
+ *                           RECOVERY_UNSUPPORTED leave everything untouched)
+ *   4. storage canary      (CREDENTIAL_PERSIST_FAILED before minting)
+ *   5. enroll              (ENROLLMENT_REJECTED etc. leave the halt + stale
+ *                           record intact)
+ *   6. persist + verify    (overwrites the stale record — it does not survive
+ *                           recovery; CREDENTIAL_PERSIST_FAILED leaves the
+ *                           halt intact)
+ *   7. clear the halt      (the LAST state change)
+ *   8. build a fresh engine
+ *
+ * DEVICE IDENTITY: the stale record's deviceId wins. Recovery's defining
+ * property is rotation — the server (Phase 2.1) revokes every still-active
+ * predecessor for the same byte-exact (accountId, deviceId) inside the
+ * enrollment transaction — and rotation only lands if we enroll under the
+ * identity the dead credential is actually bound to, for which the stored
+ * record is ground truth. An explicit config.deviceId that DIFFERS from the
+ * record is a conflict surfaced as DEVICE_ID_CONFLICT, not resolved
+ * silently: either choice would orphan something (a live predecessor or the
+ * device's cursor), so the caller decides. With no readable record, the
+ * explicit config value, then the persisted package-owned id, fill in.
+ *
+ * The engine returned is FRESH — the old engine's client closes over the
+ * dead credential and must be discarded by the app. If a stale reference
+ * survives anyway, its next 401 finds the stored record differs from its
+ * bearer and it goes inert in memory instead of re-halting the device (see
+ * isBearerSuperseded in dbEngine.js).
+ *
+ * SECRET LIFETIME: identical to connectVaultSyncEngine — the secret exists
+ * as this call's argument, rides once in the enroll request body, and is
+ * never stored, logged, placed on the engine config, or retained.
+ *
+ * @returns {Promise<{ engine: object, authMode: 'per-account',
+ *   enrolled: true, deviceId: string }>} — same shape as
+ *   connectVaultSyncEngine, so apps can swap their engine reference uniformly.
+ */
+export async function recoverVaultSyncEngine(config = {}) {
+  const { enrollmentSecret, ...engineConfig } = config;
+  const { storageKeyPrefix, vaultUrl, accountId, fetchImpl } = engineConfig;
+
+  requireString(storageKeyPrefix, 'storageKeyPrefix', 'STORAGE_KEY_PREFIX_REQUIRED');
+  requireString(vaultUrl, 'vaultUrl', 'VAULT_URL_REQUIRED');
+  requireString(accountId, 'accountId', 'ACCOUNT_ID_REQUIRED');
+  if (typeof enrollmentSecret !== 'string' || enrollmentSecret.trim() === '') {
+    throw typedError(
+      'recoverVaultSyncEngine: recovery requires the bootstrap secret to be supplied (it is never stored).',
+      'ENROLLMENT_SECRET_REQUIRED'
+    );
+  }
+
+  const base = vaultUrl.replace(/\/+$/, '');
+  const KEY_CREDENTIAL = vaultCredentialKey(storageKeyPrefix);
+  const KEY_HALT = credentialHaltKey(storageKeyPrefix);
+
+  // 1. Halt gate. Recovery is the exit from the halt and nothing else; a
+  // device that isn't halted has nothing to recover from, and refusing here
+  // is what makes "no routine code path can re-enroll" structural.
+  if (localStorage.getItem(KEY_HALT) === null) {
+    throw typedError(
+      'recoverVaultSyncEngine: this device is not credential-halted; recovery only runs from the halted state.',
+      'NOT_HALTED'
+    );
+  }
+
+  // 2. Device identity, from the stale record when one is readable.
+  let staleRecord = null;
+  try {
+    const raw = localStorage.getItem(KEY_CREDENTIAL);
+    staleRecord = raw ? JSON.parse(raw) : null;
+  } catch {
+    staleRecord = null;
+  }
+  const recordDeviceId =
+    staleRecord && typeof staleRecord.deviceId === 'string' && staleRecord.deviceId !== ''
+      ? staleRecord.deviceId
+      : null;
+  if (recordDeviceId && typeof engineConfig.deviceId === 'string' && engineConfig.deviceId !== recordDeviceId) {
+    throw typedError(
+      `recoverVaultSyncEngine: config.deviceId ("${engineConfig.deviceId}") differs from the deviceId the stale credential is bound to ("${recordDeviceId}"). Enrolling under either would orphan the other's credential or cursor — resolve the conflict explicitly.`,
+      'DEVICE_ID_CONFLICT'
+    );
+  }
+  const deviceId = recordDeviceId || engineConfig.deviceId || getOrCreateDeviceId(storageKeyPrefix);
+
+  // 3. Mode guard. Unlike connect, recovery NEVER falls back on discovery
+  // failure — it exists only to enroll, and enrolling blind could hit a
+  // shared-mode server. Shared mode has no credentials and therefore no
+  // recovery; this refusal is what keeps it structurally unreachable.
+  let health;
+  try {
+    health = await fetchVaultHealth({ vaultUrl: base, fetchImpl });
+  } catch {
+    throw typedError(
+      `recoverVaultSyncEngine: could not reach ${base}/healthz; the device stays halted.`,
+      'VAULT_UNREACHABLE'
+    );
+  }
+  if (health.authMode !== 'per-account') {
+    throw typedError(
+      `recoverVaultSyncEngine: this server reports auth mode "${health.authMode}", not per-account — there is no credential to recover; the device stays halted.`,
+      'RECOVERY_UNSUPPORTED'
+    );
+  }
+
+  // 4-6. Canary, enroll (the rotation: same byte-exact accountId + deviceId
+  // revokes every still-active predecessor server-side), persist + verify.
+  ensureCredentialSlotWritable(KEY_CREDENTIAL, 'recoverVaultSyncEngine');
+
+  const enrollment = await enrollVaultDevice({
+    vaultUrl: base,
+    enrollmentSecret,
+    accountId,
+    deviceId,
+    fetchImpl,
+  });
+
+  persistCredentialRecord(KEY_CREDENTIAL, {
+    credentialId: enrollment.credentialId,
+    credential: enrollment.credential,
+    accountId,
+    deviceId,
+    vaultUrl: base,
+    createdAt: enrollment.createdAt,
+  }, 'recoverVaultSyncEngine');
+
+  // 7. Clear the halt — the last state change, after verified persistence.
+  localStorage.removeItem(KEY_HALT);
+
+  // 8. Fresh engine on the new credential.
+  const engine = createDbSyncEngine({ ...engineConfig, deviceId, vaultToken: enrollment.credential });
+  return { engine, authMode: 'per-account', enrolled: true, deviceId };
+}

package/types/index.d.ts

@@ -27,7 +27,12 @@ export type SyncErrorCode =
   | 'VERIFIER_UNSUPPORTED'
   // DB transport: a row-scoped call (incl. the key verifier) was made before the
   // accountId was populated — retryable once the account id is available.
-  | 'ACCOUNT_ID_REQUIRED';
+  | 'ACCOUNT_ID_REQUIRED'
+  // DB transport, per-account auth: the server rejected this device's
+  // credential (401 "invalid credential"). Surfaced with isHardStop === true;
+  // the engine persists a halt and stops retrying. Recovery (re-enrollment)
+  // is Phase 2.2 — nothing in this version clears the halt.
+  | 'CREDENTIAL_INVALID';
 
 export type SyncStatus = 'idle' | 'uploading' | 'downloading' | 'success' | 'error';
 
@@ -421,10 +426,53 @@ export interface VaultClient {
 
 export function createVaultClient(config: {
   vaultUrl: string;
+  /** Shared device token, or the device's enrolled credential in per-account mode. */
   vaultToken: string;
   fetchImpl?: typeof fetch;
 }): VaultClient;
 
+// Per-account auth (vault Phase 1.4b).
+
+/** Which trust model a GLANCEvault server runs. Discoverable via fetchVaultHealth. */
+export type VaultAuthMode = 'shared' | 'per-account';
+
+export interface VaultHealth {
+  status: string;
+  version: string;
+  schemaVersion: number;
+  /** Normalized to 'shared' when the server predates the field. */
+  authMode: VaultAuthMode;
+}
+
+/** Unauthenticated GET /healthz. Safe to call before any token exists. */
+export function fetchVaultHealth(config: {
+  vaultUrl: string;
+  fetchImpl?: typeof fetch;
+}): Promise<VaultHealth>;
+
+export interface VaultEnrollment {
+  credentialId: string;
+  /** Returned once, never retrievable again. Persist it, then discard the bootstrap secret. */
+  credential: string;
+  accountId: string;
+  deviceId: string;
+  createdAt: string;
+}
+
+/**
+ * POST /enroll — exchanges the bootstrap secret for this device's own credential.
+ * Rejects with err.code 'ENROLLMENT_REJECTED' (401, secret not accepted),
+ * 'ENROLLMENT_UNSUPPORTED' (404, server runs shared mode or predates enrollment),
+ * or 'VAULT_ERROR' with err.status for other failures.
+ */
+export function enrollVaultDevice(config: {
+  vaultUrl: string;
+  enrollmentSecret: string;
+  accountId: string;
+  deviceId: string;
+  fetchImpl?: typeof fetch;
+}): Promise<VaultEnrollment>;
+
 export interface DbSyncEngineConfig {
   // Identity / local state
   storageKeyPrefix: string;
@@ -510,7 +558,74 @@ export interface DbSyncEngine {
   isKeyVerified(): boolean;
   hasEncryptionReady(): boolean;
 
+  /** True while the persisted credential-rejected stop is set (CREDENTIAL_INVALID). */
+  isCredentialHalted(): boolean;
+  /** The persisted stop record, or null. Cleared only by recoverVaultSyncEngine after a verified successful re-enrollment. */
+  getCredentialHalt(): { message: string; at: string } | null;
+  /** True once this instance proved its bearer was superseded by recovery and went inert (in-memory only). */
+  isSuperseded(): boolean;
+  /** The resolved stable device identity this engine runs as. */
+  deviceId: string;
+
   vault: VaultClient;
 }
 
 export function createDbSyncEngine(config: DbSyncEngineConfig): DbSyncEngine;
+
+/**
+ * Package-owned stable device identifier: generated once (crypto.randomUUID)
+ * and persisted under `{prefix}-device-id`. Used for both the device cursor
+ * and per-account enrollment. An explicit config.deviceId overrides it.
+ */
+export function getOrCreateDeviceId(storageKeyPrefix: string): string;
+
+/**
+ * The packaged vault connect flow: discovers the server's auth mode, resolves
+ * the Bearer value (enrolling with the bootstrap secret when the server is
+ * per-account and no credential is stored yet), persists the credential under
+ * `{prefix}-vault-credential`, and returns a ready engine. The bootstrap
+ * secret is never written to storage, never logged, and never retained past
+ * the call. No path re-enrolls automatically once a credential is stored.
+ *
+ * Typed failures: VAULT_TOKEN_REQUIRED, ENROLLMENT_SECRET_REQUIRED,
+ * CREDENTIAL_PERSIST_FAILED, VAULT_UNREACHABLE, plus enrollVaultDevice's
+ * ENROLLMENT_REJECTED / ENROLLMENT_UNSUPPORTED.
+ */
+export function connectVaultSyncEngine(
+  config: Omit<DbSyncEngineConfig, 'vaultToken'> & {
+    vaultToken?: string;
+    enrollmentSecret?: string;
+  }
+): Promise<{
+  engine: DbSyncEngine;
+  /** null when discovery failed and the flow fell back to the last known auth state. */
+  authMode: VaultAuthMode | null;
+  /** True only when this call minted a credential. */
+  enrolled: boolean;
+  deviceId: string;
+}>;
+
+/**
+ * The exit from the credential halt (Phase 2.2): USER-INITIATED re-enrollment
+ * with the bootstrap secret. Refuses unless the device is halted (NOT_HALTED)
+ * and unless the server runs per-account auth (RECOVERY_UNSUPPORTED /
+ * VAULT_UNREACHABLE — recovery never falls back on discovery failure). The
+ * stale record's deviceId is used for enrollment so the server (2.1) revokes
+ * every still-active predecessor; an explicit config.deviceId differing from
+ * it is DEVICE_ID_CONFLICT. Order: canary -> enroll -> persist + verify
+ * (overwriting the stale record) -> clear the halt LAST -> fresh engine.
+ * Every failure leaves the device halted with its state intact. The secret is
+ * confined to the call, exactly as in connectVaultSyncEngine. Call only from
+ * a deliberate user action; no code path in this package invokes it.
+ */
+export function recoverVaultSyncEngine(
+  config: Omit<DbSyncEngineConfig, 'vaultToken'> & {
+    vaultToken?: string;
+    enrollmentSecret: string;
+  }
+): Promise<{
+  engine: DbSyncEngine;
+  authMode: 'per-account';
+  enrolled: true;
+  deviceId: string;
+}>;