@abloatai/ablo 0.7.0 → 0.9.0

package/dist/sync/NetworkProbe.js

@@ -6,12 +6,15 @@
  * After laptop sleep/wake, it may report true before WiFi/DNS are functional.
  *
  * This module provides an authenticated probe against the sync server to verify
- * real connectivity + session validity in a single round-trip. The probe hits
- * `/api/auth/check`, which runs the SAME auth middleware as the WebSocket
- * upgrade path:
- *   204 No Content → reachable, session cookie valid
- *   401/403        → reachable, session expired or invalid
- *   network fail   → unreachable
+ * real connectivity + credential validity in a single round-trip. The probe
+ * hits `/api/auth/check`, which runs the SAME auth middleware as the WebSocket
+ * upgrade path, and classifies the response into a single {@link ProbeOutcome}
+ * via the closed recovery taxonomy ({@link classifyRecovery}):
+ *   204 No Content                         → `reachable`        (credential valid)
+ *   401 `apikey_expired` (ephemeral key)   → `credential_stale` (re-mint & retry, NO sign-out)
+ *   401 `session_expired` / bare 401       → `session_expired`  (sign out)
+ *   401/403 credential-type/config/perm    → `auth_blocked`     (stop, no loop, no sign-out)
+ *   network fail / offline                 → `unreachable`
  *
  * This closes a real gap: the browser's WebSocket API hides HTTP status from
  * the handshake, so a 401 on the WS upgrade surfaces only as `close code
@@ -21,8 +24,39 @@
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine
  */
+import { z } from 'zod';
 import { getContext } from '../context.js';
-import { SyncSessionError } from '../errors.js';
+import { classifyRecovery } from '../errors.js';
+import { withAuthHeaders } from '../auth/credentialSource.js';
+/**
+ * The closed set of probe outcomes — one value carrying both reachability and
+ * credential disposition, so the {@link ConnectionManager} branches on a single
+ * exhaustive discriminant instead of reconstructing intent from a trio of
+ * booleans. Mirrors the {@link RecoveryClass} taxonomy at the connectivity tier.
+ */
+export const PROBE_OUTCOMES = [
+    /** Server reachable and the access credential is currently valid. */
+    'reachable',
+    /** Could not reach the server (offline / DNS / TLS / timeout). */
+    'unreachable',
+    /** Reachable, but the long-lived login is gone → terminal, sign out. */
+    'session_expired',
+    /** Reachable, but the ephemeral access key (`ek_`/`rk_`) expired → silently
+     *  re-mint a fresh key from the still-valid login and retry. NOT a sign-out. */
+    'credential_stale',
+    /** Reachable, but the credential TYPE/config was rejected (wrong key kind,
+     *  untrusted issuer, no org, a 403) → stop; neither reconnecting nor re-auth
+     *  helps. Distinct from a sign-out. */
+    'auth_blocked',
+];
+/** Zod enum derived from {@link PROBE_OUTCOMES}. */
+export const probeOutcomeSchema = z.enum(PROBE_OUTCOMES);
+/** Result of a network probe: a single {@link ProbeOutcome} plus round-trip
+ *  latency (null when the probe never completed). */
+export const probeResultSchema = z.object({
+    outcome: probeOutcomeSchema,
+    latencyMs: z.number().nullable(),
+});
 const PROBE_TIMEOUT_MS = 4000;
 /**
  * Derive the probe URL from a sync-server base URL. Accepts `ws://`,
@@ -46,11 +80,14 @@ function resolveProbeUrl(baseUrl) {
  * Returns reachability AND session status in a single call, so the
  * ConnectionStore can make the right state transition without guessing.
  *
- * @param baseUrl The sync-server base URL (HTTP or WS scheme accepted).
- *                If omitted, falls back to `NEXT_PUBLIC_GO_SERVER_URL` →
- *                `http://localhost:8080` for backwards compatibility.
+ * @param input The sync-server base URL (HTTP or WS scheme accepted), or an
+ *              options bag with `authToken`. A bare string is still accepted
+ *              for backwards compatibility.
  */
-export async function probeNetwork(baseUrl) {
+export async function probeNetwork(input) {
+    const baseUrl = typeof input === 'string' ? input : input?.baseUrl;
+    const getAuthToken = typeof input === 'string' ? undefined : input?.getAuthToken;
+    const authToken = typeof input === 'string' ? undefined : input?.authToken;
     const url = resolveProbeUrl(baseUrl);
     // Fast-fail: if navigator.onLine is false, skip the probe entirely.
     // This is the ONE case where navigator.onLine is reliable (MDN: "false
@@ -58,29 +95,90 @@ export async function probeNetwork(baseUrl) {
     // because Node 22+ exposes `navigator` with `onLine === undefined`,
     // and `!undefined === true` would short-circuit the probe server-side.
     if (typeof navigator !== 'undefined' && navigator.onLine === false) {
-        return { reachable: false, sessionValid: null, latencyMs: null };
+        return { outcome: 'unreachable', latencyMs: null };
     }
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
     const start = performance.now();
     try {
+        const headers = withAuthHeaders(getAuthToken, { 'Cache-Control': 'no-cache' }, authToken);
         const response = await fetch(url, {
             method: 'HEAD',
-            credentials: 'include', // Send cookies for session check
             signal: controller.signal,
             // Cache-bust to avoid stale responses
-            headers: { 'Cache-Control': 'no-cache' },
+            headers,
         });
         const latencyMs = Math.round(performance.now() - start);
-        if (SyncSessionError.isSessionErrorResponse(response.status)) {
-            // Server reachable but session expired/invalid
-            getContext().logger.info('[NetworkProbe] Server reachable, session expired', {
-                status: response.status,
+        // The probe is a HEAD (no body), but the sync-server sets `X-Auth-Failure:
+        // <code>` on every auth rejection. Route the code through the closed
+        // recovery taxonomy so each failure mode gets its correct outcome — the
+        // whole reason this taxonomy exists: an expired ephemeral key
+        // (`access_credential_expiry`) must re-mint, NOT sign the user out the way
+        // a genuine login expiry (`session_expiry`) does, and NOT wedge the way a
+        // credential-type/config rejection (`auth_blocked`) does.
+        const authFailure = response.headers.get('x-auth-failure');
+        if (authFailure) {
+            const recovery = classifyRecovery(authFailure);
+            switch (recovery) {
+                case 'session_expiry':
+                    getContext().logger.info('[NetworkProbe] Server reachable, login expired', {
+                        status: response.status,
+                        code: authFailure,
+                        latencyMs,
+                    });
+                    return { outcome: 'session_expired', latencyMs };
+                case 'access_credential_expiry':
+                    getContext().logger.info('[NetworkProbe] Server reachable, access key stale — will re-mint', {
+                        status: response.status,
+                        code: authFailure,
+                        latencyMs,
+                    });
+                    return { outcome: 'credential_stale', latencyMs };
+                case 'auth_blocked':
+                case 'permission':
+                case 'none':
+                    // A non-expiry auth rejection — wrong credential type/config, a 403,
+                    // or an auth-tagged code this SDK doesn't recognise. Re-auth re-mints
+                    // the same rejected credential and retrying won't help, so STOP
+                    // rather than reconnect-loop or sign the user out.
+                    getContext().logger.warn('[NetworkProbe] Reachable but auth-blocked (non-retryable, non-expiry)', {
+                        status: response.status,
+                        code: authFailure,
+                        recovery,
+                        latencyMs,
+                    });
+                    return { outcome: 'auth_blocked', latencyMs };
+                case 'transient':
+                    // Retryable auth-tagged response — connectivity is proven; fall
+                    // through to `reachable` and let the normal retry path handle it.
+                    break;
+                default: {
+                    const _exhaustive = recovery;
+                    void _exhaustive;
+                }
+            }
+        }
+        else if (response.status === 401) {
+            // Bare 401 with no READABLE structured code. This is AMBIGUOUS and must
+            // NOT sign the user out on its own — two common causes are both
+            // recoverable, and only one is a real logout:
+            //   1. The server DID send `X-Auth-Failure: apikey_expired`, but it's a
+            //      custom header on a cross-origin response and the server didn't list
+            //      it in `Access-Control-Expose-Headers`, so the browser stripped it to
+            //      null (the network-change logout bug). The access key just needs a
+            //      re-mint.
+            //   2. A genuinely expired access key on a non-Ablo proxy / cookie path.
+            // So route to `credential_stale`: the FSM attempts a re-mint, and the ONLY
+            // way to actually sign out is the re-mint resolving `null` (login truly
+            // gone). If no refresher is wired, the bounded attempt counter falls
+            // through to `auth_blocked` (stop) — still never a spurious logout. This
+            // upholds the invariant: null is the only terminal path, never a bare 401.
+            getContext().logger.info('[NetworkProbe] Server reachable, bare 401 — re-mint (not sign-out)', {
                 latencyMs,
             });
-            return { reachable: true, sessionValid: false, latencyMs };
+            return { outcome: 'credential_stale', latencyMs };
         }
-        // 2xx (including 204) means reachable + session valid.
+        // 2xx (including 204) means reachable + credential valid.
         // 3xx/4xx (non-auth) still prove connectivity even though the probe
         // expected 204; log a warning so misconfigurations surface instead of
         // silently passing.
@@ -92,12 +190,12 @@ export async function probeNetwork(baseUrl) {
             });
         }
         else {
-            getContext().logger.debug('[NetworkProbe] Server reachable, session valid', {
+            getContext().logger.debug('[NetworkProbe] Server reachable, credential valid', {
                 status: response.status,
                 latencyMs,
             });
         }
-        return { reachable: true, sessionValid: true, latencyMs };
+        return { outcome: 'reachable', latencyMs };
     }
     catch (error) {
         clearTimeout(timeout);
@@ -105,7 +203,7 @@ export async function probeNetwork(baseUrl) {
         getContext().logger.info('[NetworkProbe] Probe failed', {
             reason: isAbort ? 'timeout' : error.message,
         });
-        return { reachable: false, sessionValid: null, latencyMs: null };
+        return { outcome: 'unreachable', latencyMs: null };
     }
     finally {
         clearTimeout(timeout);

package/dist/sync/SyncWebSocket.d.ts

@@ -8,40 +8,18 @@
  * - Automatic reconnection with exponential backoff
  */
 import { EventEmitter } from 'events';
-/** JSON model data from the sync engine — may arrive as a pre-parsed object or a JSON string. */
-type SyncDeltaPayload = Record<string, unknown> | string | null;
-export interface SyncDelta {
-    id: number;
-    /**
-     * Delta action type — full Linear-compatible vocabulary.
-     *
-     * Core CRUD:
-     *   I — Insert
-     *   U — Update
-     *   D — Delete (hard)
-     *   A — Archive (soft delete)
-     *   V — Unarchive (reVive)
-     *
-     * Permission / access control:
-     *   C — Covering: client gained permission to see an existing entity
-     *       (treated as insert by the client — see handleCovering path).
-     *   G — GroupAdded: recipient was added to a sync group. Paired with
-     *       subsequent 'C' deltas for each newly-visible entity.
-     *   S — GroupRemoved: recipient lost access to a sync group. Client
-     *       purges affected entities from its local store.
-     */
-    actionType: 'I' | 'U' | 'D' | 'A' | 'V' | 'C' | 'G' | 'S';
-    modelName: string;
-    modelId: string;
-    data: SyncDeltaPayload;
-    previousData?: SyncDeltaPayload;
-    metadata?: SyncDeltaPayload;
-    syncGroups: string[];
-    createdBy?: string;
-    transactionId?: string;
-    clientMutationId?: string;
-    createdAt: string;
-}
+import type { MutationOperation } from '../interfaces/index.js';
+import type { ClientSyncDelta } from '../schema/sync-delta-wire.js';
+import { type AuthTokenGetter } from '../auth/credentialSource.js';
+/**
+ * The wire delta the client receives. Derived from the canonical
+ * `clientSyncDeltaSchema` (`@abloatai/ablo/schema`) via `z.infer` so the
+ * SDK and the sync-server share ONE contract instead of two hand-maintained
+ * interfaces. The action vocabulary (`I`/`U`/`D`/`A`/`V`/`C`/`G`/`S`) and the
+ * client-only extras (`metadata`, `clientMutationId`, deprecated flat
+ * `createdBy`) live in that schema; see its doc for the full field reference.
+ */
+export type SyncDelta = ClientSyncDelta;
 /**
  * Payload for legacy actionType 'G' deltas emitted by EmitGroupChange.
  * Carries both added and removed groups in one delta, forces full re-bootstrap.
@@ -121,6 +99,15 @@ export interface SyncWebSocketOptions {
      * the Biscuit→opaque-key migration.)
      */
     capabilityToken?: string;
+    /**
+     * Shared credential getter. When provided, WebSocket URL auth reads this
+     * instead of a copied `capabilityToken`, so reconnects use refreshed tokens
+     * from the SDK's single auth source.
+     */
+    /** Shared SDK auth getter. Preferred internal name. */
+    getAuthToken?: AuthTokenGetter;
+    /** @deprecated Use `getAuthToken`. Kept for direct low-level callers. */
+    getCapabilityToken?: AuthTokenGetter;
 }
 /**
  * Bootstrap hint from server indicating full or partial bootstrap is needed.
@@ -271,7 +258,7 @@ export interface CoreSyncEventMap {
     /**
      * Per-entity wait-queue snapshot: `{ target, queue: Intent[] }` with each
      * entry `status: 'queued'` + `position`. Broadcast to entity peers on every
-     * queue mutation — powers the reactive `ablo.<model>.queue(id)` read.
+     * queue mutation — powers the reactive `ablo.<model>.claim.queue({ id })` read.
      */
     intent_queue: [Record<string, unknown>];
     intent_acquired: [Record<string, unknown>];
@@ -422,6 +409,16 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * Send message to server
      */
     send(message: any): void;
+    /**
+     * Project the SDK's `MutationOperation[]` onto the canonical wire
+     * `CommitMessage`. This is the single serialize boundary between the SDK op
+     * type (loose `type: string`, plus an SDK-internal `options` the server never
+     * reads) and the strict wire contract. The per-field map gives compile-time
+     * drift detection (a `CommitOperation` shape change breaks here) and the lone
+     * `as` narrows the validated op `type` to the wire union — the only
+     * loosening, localized to this boundary.
+     */
+    private buildCommitFrame;
     /**
      * Send a `commit` mutation request over the existing WebSocket and
      * resolve when the server's `mutation_result` frame comes back with
@@ -441,24 +438,7 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * NOT auto-retry here — the caller's TransactionQueue owns retry +
      * offline replay semantics and the SDK shouldn't duplicate that logic.
      */
-    sendCommit(operations: ReadonlyArray<{
-        type: string;
-        model: string;
-        id: string;
-        input?: Record<string, unknown>;
-        /**
-         * Per-op client transaction id. The server stamps this onto
-         * `sync_deltas.transaction_id` so the originating client
-         * recognizes the broadcast as an echo of its own optimistic
-         * mutation (echo detection in `SyncClient.applyDeltaBatchToPool`).
-         * Distinct from the batch-level `clientTxId` argument below
-         * (which keys `mutation_log` for retry idempotency). See
-         * `apps/sync-server/docs/OPTIMISTIC_RECONCILIATION.md`.
-         */
-        transactionId?: string;
-        readAt?: number | null;
-        onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
-    }>, clientTxId: string, timeoutMs?: number, causedByTaskId?: string | null): Promise<{
+    sendCommit(operations: ReadonlyArray<MutationOperation>, clientTxId: string, timeoutMs?: number, causedByTaskId?: string | null): Promise<{
         lastSyncId: number;
     }>;
     /**
@@ -469,15 +449,7 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * eventual `mutation_result` frame is intentionally ignored by this
      * instance because no pending resolver is registered.
      */
-    sendCommitQueued(operations: ReadonlyArray<{
-        type: string;
-        model: string;
-        id: string;
-        input?: Record<string, unknown>;
-        transactionId?: string;
-        readAt?: number | null;
-        onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
-    }>, clientTxId: string, causedByTaskId?: string | null): void;
+    sendCommitQueued(operations: ReadonlyArray<MutationOperation>, clientTxId: string, causedByTaskId?: string | null): void;
     /**
      * Activate a participant claim on this connection. Multiplexed
      * subscription pattern (Phoenix Channels / Pusher) — the same
@@ -514,15 +486,19 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      */
     sendRelease(claimId: string): void;
     /**
-     * Replace the capability token used for authentication. The new
-     * value is read by the next URL-build (i.e., next connect / reconnect
-     * cycle). The currently-open WS is NOT torn down — servers keep
-     * connections alive past cap expiry until they decide to close, and
-     * a forced reconnect would interrupt in-flight deltas. The cap-mint
-     * scheduler in `Ablo.ts` calls this on each successful refresh so
-     * reconnects after server-initiated close pick up the fresh token.
+     * Compatibility setter for direct SyncWebSocket users. The SDK-owned
+     * `Ablo()` path passes `getAuthToken`, so reconnect URL auth reads the
+     * shared credential source instead of this copied value.
      */
     setCapabilityToken(token: string): void;
+    getAuthToken(): string | undefined;
+    /**
+     * Return the credential that will be used by the next WebSocket upgrade.
+     * ConnectionManager reads this for HTTP auth probes so visibility/network
+     * checks authenticate the same way reconnects do.
+     */
+    getCapabilityToken(): string | undefined;
+    private resolveAuthToken;
     /**
      * Send spreadsheet selection presence
      */
@@ -692,4 +668,3 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      */
     private handlePresenceUpdate;
 }
-export {};