@syncular/client 0.1.3 → 0.2.0

package/src/encryption.ts

@@ -0,0 +1,123 @@
+/**
+ * Client-side encryption wiring (SPEC.md §5.11).
+ *
+ * The wire-boundary seam: encrypt configured columns when the outbox encodes
+ * a commit for send, decrypt them when a COMMIT/segment applies. The local
+ * SQLite mirror stays plaintext; the row codec (§2.4) is untouched — it only
+ * ever sees a `bytes` value for an encrypted column. This module is the
+ * bridge between the positional `RowValue[]` and the `@syncular/core` §5.11
+ * envelope primitives.
+ */
+import {
+  type DeclaredType,
+  DecryptError,
+  decryptValue,
+  encryptValue,
+  type NonceSource,
+  type PlainValue,
+  type RowColumn,
+  type RowValue,
+} from '@syncular/core';
+import type { CompiledClientTable } from './schema';
+
+/**
+ * App-supplied key material and selection. `keyProvider` maps a key-id to its
+ * 32-byte key; `keyIdFor` names the key for a given write (default:
+ * per-table, `keyId = table`). Keys travel as raw bytes — the app owns key
+ * storage, rotation, and distribution (§5.11; the docs give the synced
+ * wrapped-keys recipe).
+ */
+export interface EncryptionConfig {
+  /** `keyId → 32-byte key`, or `undefined` if unknown (decrypt fails loud). */
+  readonly keyProvider: (keyId: string) => Uint8Array | undefined;
+  /** Choose the key-id for an encrypt. Default: per-table (`table`). */
+  readonly keyIdFor?: (table: string, rowId: string) => string;
+  /**
+   * Nonce source (§5.11). Production omits this (secure RNG). ONLY the crypto
+   * golden-vector generator injects a fixed nonce — never a production path.
+   */
+  readonly nonceSource?: NonceSource;
+}
+
+function declaredTypeOf(column: RowColumn): DeclaredType {
+  // An encrypted column always carries declaredType (typegen guarantees it;
+  // §5.11). Fall back to the wire type defensively.
+  return (column.declaredType ?? column.type) as DeclaredType;
+}
+
+/**
+ * Encrypt the encrypted columns of a positional row value array in place-safe
+ * fashion (returns a new array). Called at the outbox encode-at-send seam
+ * (§6.1) BEFORE the row codec serializes: an encrypted column's plaintext
+ * value becomes the §5.11 ciphertext-envelope `bytes`. NULLs pass through
+ * unencrypted (§5.11).
+ */
+export async function encryptRowValues(
+  config: EncryptionConfig,
+  table: CompiledClientTable,
+  rowId: string,
+  values: readonly RowValue[],
+): Promise<RowValue[]> {
+  if (!table.hasEncryptedColumns) return values.slice();
+  const keyIdFor = config.keyIdFor ?? ((t: string) => t);
+  const out = values.slice();
+  for (let i = 0; i < table.columns.length; i++) {
+    const column = table.columns[i];
+    if (column === undefined || !column.encrypted) continue;
+    const value = out[i];
+    if (value === null || value === undefined) continue; // NULL stays NULL
+    const keyId = keyIdFor(table.name, rowId);
+    const key = config.keyProvider(keyId);
+    if (key === undefined) {
+      throw new DecryptError(
+        `no encryption key for keyId ${JSON.stringify(keyId)} (table ${table.name})`,
+      );
+    }
+    out[i] = await encryptValue(
+      declaredTypeOf(column),
+      value as PlainValue,
+      keyId,
+      key,
+      config.nonceSource,
+    );
+  }
+  return out;
+}
+
+/**
+ * Decrypt the encrypted columns of a decoded positional row value array
+ * (returns a new array). Called at the apply seam (§4.5 COMMIT, §5.6 rows
+ * segment) AFTER the row codec decodes: an encrypted column's ciphertext
+ * envelope `bytes` becomes its plaintext declared-type value for the local
+ * mirror. A wrong/missing key or malformed envelope throws
+ * {@link DecryptError} (`client.decrypt_failed`, §5.11).
+ */
+export async function decryptRowValues(
+  config: EncryptionConfig,
+  table: CompiledClientTable,
+  values: readonly RowValue[],
+): Promise<RowValue[]> {
+  if (!table.hasEncryptedColumns) return values.slice();
+  const out = values.slice();
+  for (let i = 0; i < table.columns.length; i++) {
+    const column = table.columns[i];
+    if (column === undefined || !column.encrypted) continue;
+    const value = out[i];
+    if (value === null || value === undefined) continue;
+    if (!(value instanceof Uint8Array)) {
+      throw new DecryptError(
+        `encrypted column ${column.name} decoded to a non-bytes value`,
+      );
+    }
+    out[i] = deserializeGuard(
+      await decryptValue(declaredTypeOf(column), value, config.keyProvider),
+    );
+  }
+  return out;
+}
+
+// decryptValue already returns a PlainValue; RowValue is a superset, so this
+// is just the type widening (kept explicit for clarity at the seam).
+function deserializeGuard(value: PlainValue): RowValue {
+  return value;
+}

package/src/errors.ts

@@ -1,269 +1,15 @@
-import { SYNCULAR_ERROR_DEFINITIONS } from '@syncular/core';
-import type {
-  SyncularErrorCategory,
-  SyncularErrorCode,
-  SyncularErrorRecommendedAction,
-} from './types';
-
-export interface SyncularErrorEnvelope {
-  code: SyncularErrorCode;
-  message: string;
-  category: SyncularErrorCategory;
-  retryable: boolean;
-  recommendedAction: SyncularErrorRecommendedAction;
-  details?: Record<string, unknown>;
-}
-
-export class SyncularClientError extends Error {
-  readonly code: SyncularErrorCode;
-  readonly category: SyncularErrorCategory;
+/**
+ * Client-side errors. Protocol codes come from the SPEC.md §10 catalog;
+ * the client never invents wire codes, it surfaces them.
+ */
+export class ClientSyncError extends Error {
+  override readonly name = 'ClientSyncError';
+  readonly code: string;
   readonly retryable: boolean;
-  readonly recommendedAction: SyncularErrorRecommendedAction;
-  readonly details: Record<string, unknown> | undefined;
-
-  constructor(envelope: SyncularErrorEnvelope, options?: ErrorOptions) {
-    super(envelope.message, options);
-    this.name = 'SyncularClientError';
-    this.code = envelope.code;
-    this.category = envelope.category;
-    this.retryable = envelope.retryable;
-    this.recommendedAction = envelope.recommendedAction;
-    this.details = envelope.details;
-  }
-}
-
-export function toSyncularClientError(error: unknown): Error {
-  if (error instanceof SyncularClientError) return error;
-  const message = syncularErrorMessage(error);
-  const details = syncularErrorDetails(error);
-  const classification = classifySyncularError(error, message, details);
-  if (!classification) {
-    return error instanceof Error ? error : new Error(message);
-  }
-  return new SyncularClientError(
-    {
-      ...classification,
-      message,
-      ...(details ? { details } : {}),
-    },
-    error instanceof Error ? { cause: error } : undefined
-  );
-}
-
-export function syncularErrorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
 
-export function syncularErrorDetails(
-  error: unknown
-): Record<string, unknown> | undefined {
-  if (error instanceof SyncularClientError) return error.details;
-  if (!(error instanceof Error)) return undefined;
-  const serverError = syncularServerErrorFromMessage(error.message);
-  const details: Record<string, unknown> = {
-    ...(httpStatusFromMessage(error.message) ?? {}),
-    ...(serverError
-      ? {
-          serverErrorCode: serverError.code,
-          serverErrorCategory: serverError.category,
-          serverRetryable: serverError.retryable,
-          serverRecommendedAction: serverError.recommendedAction,
-        }
-      : {}),
-    ...(serverError?.details ? { serverDetails: serverError.details } : {}),
-    ...(error.message.includes('full snapshot resync required')
-      ? { resyncRequired: true }
-      : {}),
-    ...(syncularKindFromError(error)
-      ? { syncularKind: syncularKindFromError(error) }
-      : {}),
-    ...(syncularDebugFromError(error)
-      ? { syncularDebug: syncularDebugFromError(error) }
-      : {}),
-  };
-  return Object.keys(details).length > 0 ? details : undefined;
-}
-
-export function classifySyncularError(
-  error: unknown,
-  message = syncularErrorMessage(error),
-  details: Record<string, unknown> | undefined = syncularErrorDetails(error)
-): Omit<SyncularErrorEnvelope, 'message' | 'details'> | null {
-  const serverError = syncularServerErrorFromMessage(message);
-  if (serverError) {
-    return {
-      code: serverError.code,
-      category: serverError.category,
-      retryable: serverError.retryable,
-      recommendedAction: serverError.recommendedAction,
-    };
-  }
-
-  const status =
-    details &&
-    'status' in details &&
-    (details.status === 401 || details.status === 403)
-      ? details.status
-      : httpStatusFromMessage(message)?.status;
-  if (status === 401) {
-    return {
-      code: 'sync.auth_required',
-      category: 'auth-required',
-      retryable: true,
-      recommendedAction: 'refreshAuth',
-    };
-  }
-  if (status === 403) {
-    return {
-      code: 'sync.forbidden',
-      category: 'forbidden',
-      retryable: false,
-      recommendedAction: 'checkPermissions',
-    };
+  constructor(code: string, message: string, retryable = false) {
+    super(message);
+    this.code = code;
+    this.retryable = retryable;
   }
-
-  const syncularKind =
-    details && typeof details.syncularKind === 'string'
-      ? details.syncularKind
-      : syncularKindFromError(error);
-  const debug =
-    details && typeof details.syncularDebug === 'string'
-      ? details.syncularDebug
-      : syncularDebugFromError(error);
-  const haystack = `${message}\n${debug ?? ''}`;
-
-  if (/\boffline\b|network is unreachable/i.test(haystack)) {
-    return {
-      code: 'sync.offline',
-      category: 'offline',
-      retryable: true,
-      recommendedAction: 'retryLater',
-    };
-  }
-
-  if (syncularKind === 'Schema' || /\bschema version\b/i.test(haystack)) {
-    return {
-      code: 'sync.schema_mismatch',
-      category: 'schema-mismatch',
-      retryable: false,
-      recommendedAction: 'regenerateClient',
-    };
-  }
-
-  if (
-    syncularKind === 'Protocol' &&
-    /(hash mismatch|sha256 mismatch|byte length mismatch|manifest .*mismatch|integrity|chain root|commit root|verified root)/i.test(
-      haystack
-    )
-  ) {
-    return {
-      code: 'sync.integrity_rejected',
-      category: 'integrity-rejected',
-      retryable: false,
-      recommendedAction: 'forceResync',
-    };
-  }
-
-  return null;
-}
-
-export function isSyncularOfflineError(error: unknown): boolean {
-  if (error instanceof SyncularClientError) {
-    return error.code === 'sync.offline' || error.category === 'offline';
-  }
-  if (error && typeof error === 'object') {
-    const record = error as Record<string, unknown>;
-    if (record.code === 'sync.offline' || record.category === 'offline') {
-      return true;
-    }
-  }
-  const classification = classifySyncularError(error);
-  return (
-    classification?.code === 'sync.offline' ||
-    classification?.category === 'offline'
-  );
-}
-
-export function syncularErrorStatus(error: unknown): 401 | 403 | undefined {
-  const details =
-    error instanceof SyncularClientError ? error.details : undefined;
-  if (
-    details &&
-    'status' in details &&
-    (details.status === 401 || details.status === 403)
-  ) {
-    return details.status;
-  }
-  return httpStatusFromMessage(syncularErrorMessage(error))?.status;
-}
-
-function httpStatusFromMessage(
-  message: string
-): { status: 401 | 403 } | undefined {
-  const match = /\bHTTP (401|403)\b/.exec(message);
-  if (!match) return undefined;
-  return { status: match[1] === '401' ? 401 : 403 };
-}
-
-function syncularKindFromError(error: unknown): string | undefined {
-  return error instanceof Error &&
-    typeof (error as Error & { syncularKind?: unknown }).syncularKind ===
-      'string'
-    ? (error as Error & { syncularKind: string }).syncularKind
-    : undefined;
-}
-
-function syncularDebugFromError(error: unknown): string | undefined {
-  return error instanceof Error &&
-    typeof (error as Error & { syncularDebug?: unknown }).syncularDebug ===
-      'string'
-    ? (error as Error & { syncularDebug: string }).syncularDebug
-    : undefined;
-}
-
-function syncularServerErrorFromMessage(
-  message: string
-): Omit<SyncularErrorEnvelope, 'message'> | null {
-  const match = /\bHTTP \d{3}\b: (\{.*\})\s*$/s.exec(message);
-  if (!match) return null;
-
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(match[1] ?? '');
-  } catch {
-    return null;
-  }
-  if (!parsed || typeof parsed !== 'object') return null;
-
-  const record = parsed as Record<string, unknown>;
-  const rawCode =
-    typeof record.code === 'string'
-      ? record.code
-      : typeof record.error === 'string'
-        ? record.error
-        : null;
-  if (!rawCode || !(rawCode in SYNCULAR_ERROR_DEFINITIONS)) return null;
-
-  const definition =
-    SYNCULAR_ERROR_DEFINITIONS[
-      rawCode as keyof typeof SYNCULAR_ERROR_DEFINITIONS
-    ];
-  return {
-    code: rawCode as SyncularErrorCode,
-    category:
-      typeof record.category === 'string'
-        ? (record.category as SyncularErrorCategory)
-        : definition.category,
-    retryable:
-      typeof record.retryable === 'boolean'
-        ? record.retryable
-        : definition.retryable,
-    recommendedAction:
-      typeof record.recommendedAction === 'string'
-        ? (record.recommendedAction as SyncularErrorRecommendedAction)
-        : definition.recommendedAction,
-    ...(record.details && typeof record.details === 'object'
-      ? { details: record.details as Record<string, unknown> }
-      : {}),
-  };
 }

package/src/http.ts

@@ -0,0 +1,254 @@
+/**
+ * Browser transport bindings (§1.1, §5.4/§5.5, §8.1): fetch-based sync
+ * transport, segment download with signed-URL preference and direct-serve
+ * fallback, and a WebSocket realtime connector. Core tests never use these
+ * (the loopback doctrine); B6 exercises them in a real browser.
+ */
+import type { BlobTransport } from './blob';
+import { SSP2_CONTENT_TYPE } from './content-type';
+import { ClientSyncError } from './errors';
+import type {
+  RealtimeConnector,
+  SegmentDownloader,
+  SyncTransport,
+} from './transport';
+
+async function throwHttpError(response: Response): Promise<never> {
+  let code = 'sync.transport_failed';
+  let message = `HTTP ${response.status}`;
+  let retryable = response.status >= 500 || response.status === 429;
+  try {
+    const body = (await response.json()) as {
+      code?: string;
+      message?: string;
+      retryable?: boolean;
+    };
+    if (typeof body.code === 'string') code = body.code;
+    if (typeof body.message === 'string') message = body.message;
+    if (typeof body.retryable === 'boolean') retryable = body.retryable;
+  } catch {
+    // non-JSON error body — keep the HTTP-status defaults
+  }
+  throw new ClientSyncError(code, message, retryable);
+}
+
+export interface HttpTransportOptions {
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly fetch?: typeof fetch;
+}
+
+/** POST `<mount>/sync` with SSP2 bodies (§1.1). */
+export function httpSyncTransport(
+  syncUrl: string,
+  options?: HttpTransportOptions,
+): SyncTransport {
+  const doFetch = options?.fetch ?? fetch;
+  return async (request) => {
+    const response = await doFetch(syncUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': SSP2_CONTENT_TYPE,
+        ...options?.headers,
+      },
+      body: request.slice().buffer as ArrayBuffer,
+    });
+    if (!response.ok) await throwHttpError(response);
+    return new Uint8Array(await response.arrayBuffer());
+  };
+}
+
+/**
+ * §5.5 direct endpoint with the `X-Syncular-Scopes` re-authorization
+ * header, plus the §5.4 `fetchUrl` capability (advertises accept bit 3).
+ * `fetchUrl` sends NO headers at all — the signed URL is the entire
+ * grant, and host auth must never leak to CDN/object hosts (§5.4).
+ * Resolution (which path a descriptor takes, expiry, no fall-through)
+ * lives in the client core, not here.
+ */
+export function httpSegmentDownloader(
+  segmentsBaseUrl: string,
+  options?: HttpTransportOptions,
+): SegmentDownloader {
+  const doFetch = options?.fetch ?? fetch;
+  const direct = async (request: {
+    readonly segmentId: string;
+    readonly requestedScopesJson: string;
+  }) => {
+    const response = await doFetch(
+      `${segmentsBaseUrl}/${encodeURIComponent(request.segmentId)}`,
+      {
+        headers: {
+          'X-Syncular-Scopes': request.requestedScopesJson,
+          ...options?.headers,
+        },
+      },
+    );
+    if (!response.ok) await throwHttpError(response);
+    return new Uint8Array(await response.arrayBuffer());
+  };
+  const fetchUrl = async (url: string) => {
+    // Deliberately headerless: the URL is the bearer grant (§5.4).
+    const response = await doFetch(url);
+    if (!response.ok) {
+      throw new ClientSyncError(
+        'sync.transport_failed',
+        `signed-URL fetch failed with HTTP ${response.status} (§5.4: descriptor invalidated, re-pull to recover)`,
+        true,
+      );
+    }
+    return new Uint8Array(await response.arrayBuffer());
+  };
+  return Object.assign(direct, { fetchUrl });
+}
+
+/**
+ * §5.9.3/§5.9.5 blob transport: host-authenticated `PUT`/`GET
+ * <mount>/blobs/{blobId}`. Both carry normal host auth (the blob id is not
+ * a capability — the server re-authorizes downloads against referencing
+ * rows). Content-address verification is the client core's job (§5.9.7).
+ */
+export function httpBlobTransport(
+  blobsBaseUrl: string,
+  options?: HttpTransportOptions,
+): BlobTransport {
+  const doFetch = options?.fetch ?? fetch;
+  const blobUrl = (blobId: string) =>
+    `${blobsBaseUrl}/${encodeURIComponent(blobId)}`;
+  return {
+    upload: async (blobId, bytes, mediaType) => {
+      const response = await doFetch(blobUrl(blobId), {
+        method: 'PUT',
+        headers: {
+          'Content-Type': mediaType ?? 'application/octet-stream',
+          ...options?.headers,
+        },
+        body: bytes.slice().buffer as ArrayBuffer,
+      });
+      if (!response.ok) await throwHttpError(response);
+    },
+    download: async (blobId) => {
+      const response = await doFetch(blobUrl(blobId), {
+        headers: { ...options?.headers },
+      });
+      if (!response.ok) await throwHttpError(response);
+      // §5.9.5 always-issue: a JSON body with `url` means presigned delivery;
+      // an octet-stream body is inline bytes.
+      const contentType = response.headers.get('content-type') ?? '';
+      if (contentType.includes('application/json')) {
+        const body = (await response.json()) as {
+          url?: string;
+          urlExpiresAtMs?: number;
+        };
+        if (typeof body.url === 'string') {
+          return {
+            kind: 'url',
+            url: body.url,
+            ...(typeof body.urlExpiresAtMs === 'number'
+              ? { urlExpiresAtMs: body.urlExpiresAtMs }
+              : {}),
+          };
+        }
+      }
+      return {
+        kind: 'bytes',
+        bytes: new Uint8Array(await response.arrayBuffer()),
+      };
+    },
+    // §5.9.5: bare GET of the signed URL — no host auth (the URL is the grant).
+    fetchUrl: async (url) => {
+      const response = await doFetch(url);
+      if (!response.ok) {
+        throw new ClientSyncError(
+          'sync.transport_failed',
+          `blob signed-URL fetch failed with HTTP ${response.status} (§5.9.5: re-request to recover)`,
+          true,
+        );
+      }
+      return new Uint8Array(await response.arrayBuffer());
+    },
+    // §5.9.3: presigned-upload grant.
+    uploadGrant: async (blobId, byteLength, mediaType) => {
+      const response = await doFetch(`${blobUrl(blobId)}/upload-grant`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...options?.headers,
+        },
+        body: JSON.stringify({
+          byteLength,
+          ...(mediaType !== undefined ? { mediaType } : {}),
+        }),
+      });
+      if (!response.ok) await throwHttpError(response);
+      const body = (await response.json()) as {
+        url?: string;
+        urlExpiresAtMs?: number;
+        present?: boolean;
+      };
+      if (typeof body.url === 'string') {
+        return {
+          kind: 'url',
+          url: body.url,
+          ...(typeof body.urlExpiresAtMs === 'number'
+            ? { urlExpiresAtMs: body.urlExpiresAtMs }
+            : {}),
+        };
+      }
+      if (body.present === true) return { kind: 'present' };
+      return { kind: 'none' };
+    },
+    // §5.9.3: direct-to-storage PUT — no host auth (the URL is the grant).
+    uploadToUrl: async (url, bytes, mediaType) => {
+      const response = await doFetch(url, {
+        method: 'PUT',
+        headers: {
+          'Content-Type': mediaType ?? 'application/octet-stream',
+        },
+        body: bytes.slice().buffer as ArrayBuffer,
+      });
+      if (!response.ok) {
+        throw new ClientSyncError(
+          'sync.transport_failed',
+          `blob presigned PUT failed with HTTP ${response.status} (§5.9.3: re-request a grant or stream direct)`,
+          true,
+        );
+      }
+    },
+  };
+}
+
+/** WebSocket realtime connector (§8.1): text = control, binary = deltas. */
+export function webSocketRealtimeConnector(
+  realtimeUrl: string,
+): RealtimeConnector {
+  return (handlers) =>
+    new Promise((resolve, reject) => {
+      const socket = new WebSocket(realtimeUrl);
+      socket.binaryType = 'arraybuffer';
+      socket.onopen = () => {
+        resolve({
+          send: (text) => socket.send(text),
+          sendBytes: (bytes) => {
+            socket.send(bytes.slice().buffer as ArrayBuffer);
+          },
+          close: () => socket.close(),
+        });
+      };
+      socket.onmessage = (event) => {
+        if (typeof event.data === 'string') handlers.onText(event.data);
+        else handlers.onBinary(new Uint8Array(event.data as ArrayBuffer));
+      };
+      socket.onerror = () => {
+        reject(
+          new ClientSyncError(
+            'sync.transport_failed',
+            'realtime socket failed to connect',
+            true,
+          ),
+        );
+      };
+      socket.onclose = () => {
+        handlers.onClose?.();
+      };
+    });
+}