@glance-apps/sync 1.6.0 → 1.8.0

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';
 
@@ -266,6 +271,14 @@ export interface CloudSyncProvider {
 export function webdavFetch(config: SyncEngineConfig): WebdavFetch;
 export function createProviders(config: SyncEngineConfig): Record<string, CloudSyncProvider>;
 
+/**
+ * Normalizes a raw ETag header value for use in If-Match: strips a weak-
+ * validator prefix (`W/"abc"` -> `"abc"`) and the content-coding suffixes
+ * Apache mod_deflate/mod_brotli append inside the quotes (`"abc-gzip"` /
+ * `"abc-br"` -> `"abc"`). Quotes are preserved; null/undefined pass through.
+ */
+export function normalizeEtag(raw: string | null | undefined): string | null | undefined;
+
 // ---------------------------------------------------------------------------
 // Sync engine
 // ---------------------------------------------------------------------------
@@ -413,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;
@@ -502,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;
+}>;