@spooky-sync/core 0.0.1-canary.25 → 0.0.1-canary.255

package/src/modules/auth/index.ts

@@ -1,17 +1,15 @@
-import { RemoteDatabaseService } from '../../services/database/remote';
-import { LocalDatabaseService } from '../../services/database/local';
-import { DataModule } from '../data/index';
-import {
+import type { RemoteDatabaseService } from '../../services/database/remote';
+import type {
   SchemaStructure,
   AccessDefinition,
   ColumnSchema,
   TypeNameToTypeMap,
 } from '@spooky-sync/query-builder';
-import { Logger } from '../../services/logger/index';
-import { encodeRecordId } from '../../utils/index';
+import type { Logger } from '../../services/logger/index';
 export * from './events/index';
 import { AuthEventTypes, createAuthEventSystem } from './events/index';
-import { PersistenceClient } from '../../types';
+import type { PersistenceClient } from '../../types';
+import { classifySyncError } from '../../utils/error-classification';
 
 // Helper to pretty print types
 type Prettify<T> = {
@@ -38,11 +36,54 @@ type ExtractAccessParams<
       }>
     : never;
 
+/**
+ * Read the claims of a SurrealDB record-access JWT WITHOUT verifying it. The
+ * server still enforces the token on every request; this is only so the client
+ * can act on what it already holds before a round trip completes.
+ *
+ * `AC` is the access-method name — the in-browser SSP needs it to resolve
+ * `$access` in table permission predicates (mirrors the session's `$access`
+ * that the server's `fn::query::register` reads). `ID` is the `$auth.id` record
+ * id, which is what lets a warm boot restore a session locally.
+ *
+ * Returns nulls on any malformed input.
+ */
+function decodeTokenClaims(token: string): { access: string | null; userId: string | null } {
+  try {
+    const payload = token.split('.')[1];
+    if (!payload) return { access: null, userId: null };
+    let b64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+    b64 += '='.repeat((4 - (b64.length % 4)) % 4);
+    const json =
+      typeof atob === 'function' ? atob(b64) : Buffer.from(b64, 'base64').toString('binary');
+    const claims = JSON.parse(json) as Record<string, unknown>;
+    const ac = claims.AC ?? claims.ac;
+    const id = claims.ID ?? claims.id;
+    return {
+      access: typeof ac === 'string' ? ac : null,
+      userId: typeof id === 'string' ? id : null,
+    };
+  } catch {
+    return { access: null, userId: null };
+  }
+}
+
+function decodeAccessFromToken(token: string): string | null {
+  return decodeTokenClaims(token).access;
+}
+
 export class AuthService<S extends SchemaStructure> {
   // State
   public token: string | null = null;
   public currentUser: any | null = null;
   public isAuthenticated: boolean = false;
+  /**
+   * The record-access method name for the current session (e.g. `"account"`),
+   * derived from the token's `AC` claim. Consumed by the in-browser SSP's
+   * permission injection so `$access`-gated table predicates resolve locally,
+   * mirroring the server's `$access`. Null when logged out.
+   */
+  public access: string | null = null;
   public isLoading: boolean = true;
 
   private events = createAuthEventSystem();
@@ -88,6 +129,49 @@ export class AuthService<S extends SchemaStructure> {
     this.events.emit(AuthEventTypes.AuthStateChanged, userId);
   }
 
+  /**
+   * Restore a session from the locally cached JWT, with NO network.
+   *
+   * This is what makes a warm boot paint instantly and what makes an offline
+   * boot possible at all: the token is in local storage, and it already carries
+   * both the access method and the `$auth.id` record id. Everything the client
+   * needs to route queries (`setCurrentUserId`) and to satisfy `$auth`-gated
+   * permission predicates in the in-browser SSP (`setSessionAuth`) is therefore
+   * available before a socket exists.
+   *
+   * The session is OPTIMISTIC: the token is unverified here. `check()` runs
+   * afterwards in the background and downgrades to a real sign-out if the
+   * server rejects it. Nothing is trusted that the server has not also seen -
+   * the local store only ever holds rows the server previously sent.
+   *
+   * Returns the restored user id, or null when there is no usable token.
+   */
+  async restoreSessionFromToken(): Promise<string | null> {
+    const token = await this.persistenceClient.get<string>('sp00ky_auth_token');
+    if (!token) return null;
+    const { access, userId } = decodeTokenClaims(token);
+    if (!userId) return null;
+
+    this.token = token;
+    // Hand it to the transport too, so a socket rebuilt from scratch later
+    // (the supervisor's revive loop) comes back authenticated. Without this the
+    // page kept reporting this user while its session was anonymous, and every
+    // view registered afterwards was stamped with an empty identity.
+    this.remote.setAuthToken(token);
+    // Only the id: the full row is not in the token. It lands from the local
+    // cache when the app's own `user` query paints, and is replaced wholesale
+    // by `check()` once the server answers.
+    this.currentUser = { id: userId };
+    this.isAuthenticated = true;
+    this.access = access ?? this.defaultAccessName();
+    this.notifyListeners();
+    this.logger.debug(
+      { userId, Category: 'sp00ky-client::AuthService::restoreSessionFromToken' },
+      'Session restored optimistically from cached token'
+    );
+    return userId;
+  }
+
   /**
    * Check for existing session and validate
    */
@@ -95,11 +179,11 @@ export class AuthService<S extends SchemaStructure> {
     this.isLoading = true;
 
     try {
-      const token = accessToken || (await this.persistenceClient.get<string>('spooky_auth_token'));
+      const token = accessToken || (await this.persistenceClient.get<string>('sp00ky_auth_token'));
 
       if (!token) {
         this.logger.debug(
-          { Category: 'spooky-client::AuthService::check' },
+          { Category: 'sp00ky-client::AuthService::check' },
           'No token found in storage or arguments'
         );
         this.isLoading = false;
@@ -108,7 +192,10 @@ export class AuthService<S extends SchemaStructure> {
         return;
       }
 
-      // Authenticate with the token
+      // Authenticate with the token, and record it for future connects so a
+      // socket rebuilt from scratch reproduces this identity (see
+      // `RemoteDatabaseService.setAuthToken`).
+      this.remote.setAuthToken(token);
       await this.remote.getClient().authenticate(token);
 
       // Verify the session by fetching the full user record using $auth.id
@@ -119,13 +206,13 @@ export class AuthService<S extends SchemaStructure> {
 
       if (user && user.id) {
         this.logger.info(
-          { user, Category: 'spooky-client::AuthService::check' },
+          { user, Category: 'sp00ky-client::AuthService::check' },
           'Auth check complete (via $auth.id)'
         );
         await this.setSession(token, user);
       } else {
         this.logger.warn(
-          { Category: 'spooky-client::AuthService::check' },
+          { Category: 'sp00ky-client::AuthService::check' },
           '$auth.id empty, attempting manual user fetch'
         );
 
@@ -140,24 +227,36 @@ export class AuthService<S extends SchemaStructure> {
 
         if (manualUser && manualUser.id) {
           this.logger.info(
-            { user: manualUser, Category: 'spooky-client::AuthService::check' },
+            { user: manualUser, Category: 'sp00ky-client::AuthService::check' },
             'Auth check complete (via manual fetch)'
           );
           await this.setSession(token, manualUser);
         } else {
           this.logger.warn(
-            { Category: 'spooky-client::AuthService::check' },
+            { Category: 'sp00ky-client::AuthService::check' },
             'Token valid but user not found via fallback'
           );
           await this.signOut();
         }
       }
     } catch (error) {
-      this.logger.error(
-        { error, stack: (error as Error).stack, Category: 'spooky-client::AuthService::check' },
-        'Auth check failed'
-      );
-      await this.signOut();
+      // A REACHABILITY failure is not a rejected token. This catch used to call
+      // signOut() unconditionally, which deletes `sp00ky_auth_token` - so a
+      // blip on boot silently logged the user out, and an offline boot could
+      // never stay signed in. Only an application error (the server answered,
+      // and the answer was "no") ends the session.
+      if (classifySyncError(error) === 'network') {
+        this.logger.warn(
+          { error, Category: 'sp00ky-client::AuthService::check' },
+          'Auth check unreachable; keeping the cached session and retrying later'
+        );
+      } else {
+        this.logger.error(
+          { error, stack: (error as Error).stack, Category: 'sp00ky-client::AuthService::check' },
+          'Auth check failed'
+        );
+        await this.signOut();
+      }
     } finally {
       this.isLoading = false;
     }
@@ -168,14 +267,16 @@ export class AuthService<S extends SchemaStructure> {
    */
   async signOut() {
     this.token = null;
+    this.remote.setAuthToken(null);
     this.currentUser = null;
     this.isAuthenticated = false;
+    this.access = null;
 
-    await this.persistenceClient.remove('spooky_auth_token');
+    await this.persistenceClient.remove('sp00ky_auth_token');
 
     try {
       await this.remote.getClient().invalidate();
-    } catch (e) {
+    } catch (_e) {
       // Ignore invalidation errors
     }
 
@@ -184,12 +285,24 @@ export class AuthService<S extends SchemaStructure> {
 
   private async setSession(token: string, user: any) {
     this.token = token;
+    this.remote.setAuthToken(token);
     this.currentUser = user;
     this.isAuthenticated = true;
-    await this.persistenceClient.set('spooky_auth_token', token);
+    // Resolve the access-method name (e.g. "account") for in-browser SSP
+    // permission injection. Prefer the token's `AC` claim; fall back to the
+    // schema's sole record-access method if the claim is absent.
+    this.access = decodeAccessFromToken(token) ?? this.defaultAccessName();
+    await this.persistenceClient.set('sp00ky_auth_token', token);
     this.notifyListeners();
   }
 
+  /** Fallback when the token carries no `AC` claim: if the schema defines
+   *  exactly one record-access method, assume the session used it. */
+  private defaultAccessName(): string | null {
+    const names = Object.keys(this.schema.access ?? {});
+    return names.length === 1 ? names[0] : null;
+  }
+
   async signUp<Name extends keyof S['access'] & string>(
     accessName: Name,
     params: ExtractAccessParams<S, Name, 'signup'>
@@ -212,7 +325,7 @@ export class AuthService<S extends SchemaStructure> {
     }
 
     this.logger.info(
-      { accessName, runtimeParams, Category: 'spooky-client::AuthService::signUp' },
+      { accessName, runtimeParams, Category: 'sp00ky-client::AuthService::signUp' },
       'Attempting signup'
     );
 
@@ -222,7 +335,7 @@ export class AuthService<S extends SchemaStructure> {
     });
 
     this.logger.info(
-      { Category: 'spooky-client::AuthService::signUp' },
+      { Category: 'sp00ky-client::AuthService::signUp' },
       'Signup successful, token received'
     );
 
@@ -253,7 +366,7 @@ export class AuthService<S extends SchemaStructure> {
     }
 
     this.logger.info(
-      { accessName, Category: 'spooky-client::AuthService::signIn' },
+      { accessName, Category: 'sp00ky-client::AuthService::signIn' },
       'Attempting signin'
     );
 

package/src/modules/crdt/crdt-field.ts

@@ -0,0 +1,294 @@
+import type { LoroDoc } from 'loro-crdt';
+import type { LocalStore, RemoteDatabaseService } from '../../services/database/index';
+import type { Logger } from '../../services/logger/index';
+import { parseRecordIdString } from '../../utils/index';
+
+// ==================== CURSOR UTILITIES ====================
+
+export const CURSOR_COLORS = [
+  '#3b82f6', '#ef4444', '#22c55e', '#f59e0b',
+  '#8b5cf6', '#ec4899', '#14b8a6', '#f97316',
+];
+
+export function cursorColorFromName(name: string): string {
+  let hash = 0;
+  for (let i = 0; i < name.length; i++) {
+    hash = ((hash << 5) - hash + name.charCodeAt(i)) | 0;
+  }
+  return CURSOR_COLORS[Math.abs(hash) % CURSOR_COLORS.length];
+}
+
+// ==================== CRDT FIELD ====================
+
+export class CrdtField {
+  private doc: LoroDoc;
+  private pushTimer: ReturnType<typeof setTimeout> | null = null;
+  private local: LocalStore | null = null;
+  private remote: RemoteDatabaseService | null = null;
+  private recordId: string | null = null;
+  private sessionId: string = '';
+  private unsubscribe: (() => void) | null = null;
+  private lastPushTime = 0;
+  private lastCursorPushTime = 0;
+  private loadedFromCrdt = false;
+  private pushRetryCount = 0;
+  private logger: Logger | null;
+  private cursorsEnabled: boolean;
+  /** Remote-push debounce. Local writes happen immediately on every Loro
+   *  update; the remote UPSERT is coalesced over this window. Configured
+   *  via `Sp00kyConfig.crdtDebounceMs`, default 500. */
+  private remoteDebounceMs: number = 500;
+
+  private _onCursorUpdate: ((data: Uint8Array) => void) | null = null;
+  private pendingCursorUpdate: Uint8Array | null = null;
+
+  /** Callback set by the editor to receive remote cursor updates.
+   *  Any cursor data that arrived before this callback was set will be replayed. */
+  set onCursorUpdate(cb: ((data: Uint8Array) => void) | null) {
+    this._onCursorUpdate = cb;
+    if (cb && this.pendingCursorUpdate) {
+      try { cb(this.pendingCursorUpdate); } catch (e) {
+        this.logger?.warn(
+          { error: e, Category: 'sp00ky-client::CrdtField::onCursorUpdate' },
+          'Failed to replay pending cursor update'
+        );
+      }
+      this.pendingCursorUpdate = null;
+    }
+  }
+
+  get onCursorUpdate() { return this._onCursorUpdate; }
+
+  /**
+   * @param LoroDocClass the `LoroDoc` constructor, injected by the caller after
+   *   awaiting {@link loadLoro} — keeps `loro-crdt` out of this module's static
+   *   import graph so it only ships to apps that use CRDT fields.
+   */
+  constructor(
+    private fieldName: string,
+    cursorsEnabled: boolean,
+    LoroDocClass: typeof LoroDoc,
+    initialState?: Uint8Array,
+    logger?: Logger | null,
+  ) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(fieldName)) {
+      throw new Error(
+        `CrdtField: refusing unsafe field identifier '${fieldName}' — must match [a-zA-Z_][a-zA-Z0-9_]*`
+      );
+    }
+    this.logger = logger ?? null;
+    this.cursorsEnabled = cursorsEnabled;
+    this.doc = new LoroDocClass();
+    if (initialState && initialState.length > 0) {
+      // Tolerance: catch bad-snapshot data (corrupt blob, stale legacy
+      // value left over from a pre-`bytes` migration) so the editor still
+      // mounts. Without this guard the rejection bubbles through
+      // `useCrdtField` → permanent fallback `<p>`, with no cursor.
+      try {
+        this.doc.import(initialState);
+        this.loadedFromCrdt = true;
+      } catch (e) {
+        this.logger?.warn(
+          {
+            error: e,
+            fieldName,
+            Category: 'sp00ky-client::CrdtField::constructor',
+          },
+          'Initial CRDT state is not a valid LoroDoc snapshot — starting empty and will seed from fallback text'
+        );
+      }
+    }
+  }
+
+  getDoc(): LoroDoc { return this.doc; }
+
+  /** Whether the LoroDoc was loaded from saved CRDT state */
+  hasContent(): boolean {
+    return this.loadedFromCrdt;
+  }
+
+  startSync(
+    local: LocalStore,
+    remote: RemoteDatabaseService,
+    recordId: string,
+    sessionId: string,
+    debounceMs: number,
+  ): void {
+    this.local = local;
+    this.remote = remote;
+    this.recordId = recordId;
+    this.sessionId = sessionId;
+    this.remoteDebounceMs = debounceMs;
+    // Every local Loro update writes the snapshot to the local cache
+    // *immediately* (so reload/offline see the latest text), then
+    // schedules a debounced push to remote. The local UPSERT is cheap —
+    // it's an in-memory SurrealKV write — but errors are swallowed so a
+    // bad write never blocks user input.
+    this.unsubscribe = this.doc.subscribeLocalUpdates(() => {
+      void this.persistLocal();
+      this.scheduleRemotePush();
+    });
+  }
+
+  /**
+   * Stop syncing this field. Flushes one final remote push by default so the
+   * last keystrokes aren't lost. Pass `{ flush: false }` on a bucket switch —
+   * the remote session already belongs to the NEXT user, and pushing this
+   * (previous user's) snapshot under it would clobber the record remotely.
+   */
+  stopSync(options: { flush?: boolean } = {}): void {
+    const flush = options.flush ?? true;
+    if (this.unsubscribe) { this.unsubscribe(); this.unsubscribe = null; }
+    if (this.pushTimer) { clearTimeout(this.pushTimer); this.pushTimer = null; }
+    if (flush && this.remote && this.recordId) { void this.pushToRemote(); }
+  }
+
+  importRemote(state: Uint8Array): void {
+    // Echo suppression: skip imports within `remoteDebounceMs + 200` of
+    // our own push. The +200 guards against round-trip jitter where our
+    // own write echoes back from the LIVE feed before the debounce
+    // window closes.
+    if (Date.now() - this.lastPushTime < this.remoteDebounceMs + 200) return;
+    try {
+      this.doc.import(state);
+      // Persist the merged snapshot locally so the next reload/offline
+      // open sees the freshest converged state without waiting for the
+      // LIVE feed.
+      void this.persistLocal();
+    } catch (e) {
+      this.logger?.warn(
+        { error: e, Category: 'sp00ky-client::CrdtField::importRemote' },
+        'Failed to import remote CRDT state'
+      );
+    }
+  }
+
+  exportSnapshot(): Uint8Array {
+    return this.doc.export({ mode: 'snapshot' });
+  }
+
+  /** Push this session's cursor blob into the parent row at
+   *  `<field>.cursors[$sid]`. No-op when cursors aren't enabled on this
+   *  field — the editor still calls this method optimistically, but
+   *  without `@cursor` on the schema there's nowhere to store the blob.
+   *  The UPDATE itself fires the parent table's LIVE feed, so other
+   *  browsers receive the cursor change without a separate `_00_rv` bump. */
+  async pushCursorState(encoded: Uint8Array): Promise<void> {
+    if (!this.remote || !this.recordId) return;
+    if (!this.cursorsEnabled) return;
+    this.lastCursorPushTime = Date.now();
+    try {
+      const state = encodeBase64(encoded);
+      await this.remote.query(
+        `UPDATE $id SET ${this.fieldName}.cursors[$sid] = $state RETURN NONE;`,
+        {
+          id: parseRecordIdString(this.recordId),
+          sid: this.sessionId,
+          state,
+        }
+      );
+    } catch (e) {
+      this.logger?.warn(
+        { error: e, Category: 'sp00ky-client::CrdtField::pushCursorState' },
+        'Failed to push cursor state'
+      );
+    }
+  }
+
+  /** Import remote cursor state (called by CrdtManager from LIVE SELECT) */
+  importRemoteCursor(base64State: string): void {
+    if (Date.now() - this.lastCursorPushTime < 300) return; // echo suppression
+    try {
+      const data = decodeBase64(base64State);
+      if (this._onCursorUpdate) {
+        this._onCursorUpdate(data);
+      } else {
+        // Only keep the latest cursor state — older positions are useless
+        this.pendingCursorUpdate = data;
+      }
+    } catch (e) {
+      this.logger?.warn(
+        { error: e, Category: 'sp00ky-client::CrdtField::importRemoteCursor' },
+        'Failed to apply remote cursor data'
+      );
+    }
+  }
+
+  private scheduleRemotePush(): void {
+    if (this.pushTimer) clearTimeout(this.pushTimer);
+    this.pushTimer = setTimeout(() => void this.pushToRemote(), this.remoteDebounceMs);
+  }
+
+  /** SET path inside a parent row for the current snapshot. `@crdt`-only
+   *  fields hold the snapshot directly (`<field>`); `@crdt @cursor`
+   *  fields hold a `{ state, cursors }` object so the snapshot lives at
+   *  `<field>.state` next to per-session cursor blobs. */
+  private statePath(): string {
+    return this.cursorsEnabled ? `${this.fieldName}.state` : this.fieldName;
+  }
+
+  /** Mirror the LoroDoc snapshot into the parent row locally. Runs on
+   *  every local update and every remote import so reloads (online or
+   *  offline) see the freshest content immediately. Failures are
+   *  swallowed — a stale local write must never block user input. */
+  private async persistLocal(): Promise<void> {
+    if (!this.local || !this.recordId) return;
+    try {
+      await this.local.query(
+        `UPDATE $id SET ${this.statePath()} = $state RETURN NONE;`,
+        { id: parseRecordIdString(this.recordId), state: this.exportSnapshot() }
+      );
+    } catch (e) {
+      this.logger?.debug(
+        { error: e, Category: 'sp00ky-client::CrdtField::persistLocal' },
+        'Local CRDT persist failed (best-effort)'
+      );
+    }
+  }
+
+  private async pushToRemote(): Promise<void> {
+    if (!this.remote || !this.recordId) return;
+    this.lastPushTime = Date.now();
+    try {
+      // The UPDATE on the parent fires the parent table's LIVE feed,
+      // so cross-browser receivers see this change directly in the LIVE
+      // payload — no separate `_00_rv` bump or sidecar UPSERT.
+      await this.remote.query(
+        `UPDATE $id SET ${this.statePath()} = $state RETURN NONE;`,
+        { id: parseRecordIdString(this.recordId), state: this.exportSnapshot() }
+      );
+      this.pushRetryCount = 0;
+    } catch (e) {
+      this.logger?.warn(
+        { error: e, Category: 'sp00ky-client::CrdtField::pushToRemote' },
+        'Failed to push CRDT state to remote'
+      );
+      // Bounded retry. Offline first-loads will exhaust this and stop
+      // hammering; the next user keystroke (or the next time a remote
+      // event lands once we're back online) will kick off another push.
+      if (this.pushRetryCount < 2) {
+        this.pushRetryCount++;
+        this.scheduleRemotePush();
+      }
+    }
+  }
+}
+
+export function decodeBase64(b64: string): Uint8Array {
+  if (typeof atob === 'function') {
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return bytes;
+  }
+  return new Uint8Array(Buffer.from(b64, 'base64'));
+}
+
+export function encodeBase64(bytes: Uint8Array): string {
+  if (typeof btoa === 'function') {
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+    return btoa(binary);
+  }
+  return Buffer.from(bytes).toString('base64');
+}