@glance-apps/sync 1.6.1 → 1.10.0

package/types/index.d.ts

@@ -27,7 +27,20 @@ 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'
+  // DB transport: the server rejected a write because the account is over a
+  // configured quota (413 storage-shaped / 429 volume-shaped, Phase 3.2).
+  // ALWAYS isHardStop === false — a quota condition clears when the operator
+  // raises the limit or reclaim runs, with NO client action, so the engine
+  // never halts on it. The parsed descriptor rides on the engine's
+  // getQuotaState(); the engine suppresses further writes for a bounded,
+  // self-resuming window while the pull keeps running.
+  | 'QUOTA_EXCEEDED';
 
 export type SyncStatus = 'idle' | 'uploading' | 'downloading' | 'success' | 'error';
 
@@ -421,10 +434,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;
@@ -471,6 +527,74 @@ export interface DbSyncResult {
   applied: number;
   skipped: number;
   skippedEntityIds: string[];
+  /** True when the push threw but the pull still ran (Phase 3.3 partial function). */
+  pushFailed?: boolean;
+  /** True when the push was skipped because its backoff window is open. */
+  pushSkipped?: boolean;
+  /** The push error's code when pushFailed/pushSkipped — the pull's own result is still reported above. */
+  pushErrorCode?: SyncErrorCode | string;
+  /** True when the pull threw but the cursor report still ran. */
+  pullFailed?: boolean;
+  /** True when the pull was skipped because its backoff window is open. */
+  pullSkipped?: boolean;
+  /** The pull error's code when pullFailed/pullSkipped. */
+  pullErrorCode?: SyncErrorCode | string;
+  /** The standing over-quota descriptor, when one applies. */
+  quota?: QuotaState | null;
+  /** True when the cycle no-opped because the credential halt is set. */
+  halted?: boolean;
+  /** True when the cycle no-opped because this instance's credential was superseded. */
+  superseded?: boolean;
+}
+
+/**
+ * Over-quota state (Phase 3.3). IN MEMORY ONLY — this describes server-side
+ * state that changes without the client (an operator raises a limit, reclaim
+ * runs, intents expire), so it is never persisted and there is nothing to
+ * clear: it lifts by itself when a write succeeds again.
+ *
+ * `quota` is the server's dimension string, passed through verbatim — the
+ * known values are 'storage' | 'rows' | 'intents' | 'concurrent-uploads', but
+ * a newer server may add dimensions, so treat an unrecognised one generically
+ * rather than assuming it cannot happen. The numbers are bytes for 'storage'
+ * and counts otherwise, and render "X of Y used" directly; they are null only
+ * in the defensive case where a rejection was typed without a full body.
+ */
+/**
+ * One backoff window. The DB engine keeps two (push and pull) and enforces
+ * them itself; both are IN MEMORY ONLY, like the file tier's, so a restart
+ * clears them — a relaunch is a user saying "try now", and a persisting
+ * failure re-opens the window immediately.
+ *
+ * A window only ever DELAYS: the next cycle after `until` probes again, with
+ * no user action and no restart. Failures that must not be delayed at all
+ * (PASSPHRASE_REQUIRED / ACCOUNT_ID_REQUIRED, which clear the moment the app
+ * supplies the value) and failures owned by another state (CREDENTIAL_INVALID,
+ * which halts) never open one.
+ */
+export interface BackoffWindow {
+  /** Epoch ms; the direction is skipped while this is in the future. 0 when clear. */
+  until: number;
+  /** Consecutive failures driving the escalation (30s doubling; 15 min push cap, 5 min pull cap). */
+  strikes: number;
+  /** 'quota' (keeps surfacing its descriptor), 'auth' (flat hour on a 401), 'transport' (quiet after one signal). */
+  reason: 'quota' | 'auth' | 'transport' | null;
+  /** The typed error code that opened the window. */
+  code: SyncErrorCode | string | null;
+  /** ISO timestamp of the most recent failure. */
+  since: string | null;
+}
+
+export interface QuotaState {
+  quota: string;
+  limit: number | null;
+  used: number | null;
+  requested: number | null;
+  message: string;
+  /** ISO timestamp of the most recent rejection. */
+  since: string;
+  /** ISO timestamp after which the engine probes again, on its own. */
+  retryAt: string;
 }
 
 /** A row quarantined after failing to decrypt under the (verified) account key. */
@@ -510,7 +634,93 @@ 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 standing over-quota descriptor, or null. In-memory only; never a hard stop; nothing to clear. */
+  getQuotaState(): QuotaState | null;
+  /** True while the bounded over-quota window is open (writes skipped, pulls continue). */
+  isQuotaSuppressed(): boolean;
+
+  /**
+   * Epoch ms before which the push/pull will not be attempted, or 0. Same
+   * getter names and meaning as the file engine's, so one scheduler can treat
+   * both tiers identically — but unlike the file tier, the DB engine also
+   * ENFORCES these itself, so honouring them is an optimisation, not a duty.
+   */
+  getUploadBackoffUntil(): number;
+  getDownloadBackoffUntil(): number;
+  /**
+   * The full backoff picture. `reason` distinguishes a one-hour auth window
+   * from a thirty-second transport one without inferring from the timestamp's
+   * magnitude, which is what an app needs to tell a user why and for how long.
+   */
+  getBackoffState(): { push: BackoffWindow; pull: BackoffWindow };
+  /** 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;
+}>;