@spooky-sync/core 0.0.1-canary.22 → 0.0.1-canary.221

package/src/modules/app-release/index.ts

@@ -0,0 +1,201 @@
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+import type { DataModule } from '../data/index';
+import type { Sp00kySync } from '../sync/index';
+import type { AuthService } from '../auth/index';
+import type { Logger } from '../../services/logger/index';
+import type { QueryTimeToLive } from '../../types';
+import { semverGt } from '../../utils/semver';
+
+// One shared LIVE query over every app's release row. `_00_app_release` is
+// world-readable (root-only writes), one row per app keyed by name — written
+// by `spky deploy` / `spky release` / the git-linked builder. A single
+// registration observes every app at once; a handle for an app with no row
+// simply reports no update. Mirrors the FeatureFlagModule design.
+const RELEASE_QUERY = 'SELECT * FROM _00_app_release';
+
+interface ReleaseRow {
+  app?: string;
+  version?: string;
+  cache_bust?: boolean | null;
+  mandatory?: boolean | null;
+  released_at?: string;
+}
+
+export interface AppReleaseSnapshot {
+  /** Latest announced version for the app, or undefined when no row exists. */
+  version: string | undefined;
+  /** Clients should clear SW/caches when reloading onto this version. */
+  cacheBust: boolean;
+  /** Clients should reload/update immediately instead of asking. */
+  mandatory: boolean;
+  releasedAt: string | undefined;
+}
+
+const EMPTY_SNAPSHOT: AppReleaseSnapshot = {
+  version: undefined,
+  cacheBust: false,
+  mandatory: false,
+  releasedAt: undefined,
+};
+
+export interface AppReleaseOptions {
+  ttl?: QueryTimeToLive;
+}
+
+export class AppReleaseHandle {
+  private latest: AppReleaseSnapshot = EMPTY_SNAPSHOT;
+  private listeners = new Set<(s: AppReleaseSnapshot) => void>();
+  private onCloseFn: (() => void) | null = null;
+  private closed = false;
+
+  constructor(public readonly app: string) {}
+
+  set(snapshot: AppReleaseSnapshot): void {
+    if (this.closed) return;
+    this.latest = snapshot;
+    for (const cb of this.listeners) cb(snapshot);
+  }
+
+  snapshot(): AppReleaseSnapshot {
+    return this.latest;
+  }
+
+  version(): string | undefined {
+    return this.latest.version;
+  }
+
+  /** True when the announced version is semver-newer than `currentVersion`. */
+  updateAvailable(currentVersion: string): boolean {
+    return semverGt(this.latest.version, currentVersion);
+  }
+
+  subscribe(cb: (s: AppReleaseSnapshot) => void): () => void {
+    this.listeners.add(cb);
+    cb(this.latest);
+    return () => {
+      this.listeners.delete(cb);
+    };
+  }
+
+  onClose(cb: () => void): void {
+    this.onCloseFn = cb;
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.listeners.clear();
+    this.onCloseFn?.();
+  }
+}
+
+export interface AppReleaseModuleDeps<S extends SchemaStructure> {
+  dataModule: DataModule<S>;
+  sync: Sp00kySync<S>;
+  auth: AuthService<S>;
+  logger: Logger;
+}
+
+export class AppReleaseModule<S extends SchemaStructure> {
+  private logger: Logger;
+  private handles = new Set<AppReleaseHandle>();
+  private authUnsubscribe: (() => void) | null = null;
+  private lastUserId: string | null = null;
+
+  private querySubscription: (() => void) | null = null;
+  private starting = false;
+  private ttl: QueryTimeToLive = '10m';
+  private snapshots = new Map<string, AppReleaseSnapshot>();
+  private loaded = false;
+
+  constructor(private deps: AppReleaseModuleDeps<S>) {
+    this.logger = deps.logger.child({ service: 'AppReleaseModule' });
+  }
+
+  init(): void {
+    if (this.authUnsubscribe) return;
+    // Auth changes re-register the shared query (a new session invalidates the
+    // old SSP plan). The table itself is world-readable, so the data is the
+    // same for every user — this is purely plumbing hygiene.
+    this.authUnsubscribe = this.deps.auth.subscribe((userId) => {
+      if (userId === this.lastUserId) return;
+      this.lastUserId = userId;
+      void this.refresh();
+    });
+  }
+
+  release(app: string, options: AppReleaseOptions = {}): AppReleaseHandle {
+    const handle = new AppReleaseHandle(app);
+    this.handles.add(handle);
+    handle.onClose(() => this.handles.delete(handle));
+    if (options.ttl) this.ttl = options.ttl;
+    if (this.loaded) {
+      handle.set(this.snapshots.get(app) ?? EMPTY_SNAPSHOT);
+    }
+    void this.ensureStarted();
+    return handle;
+  }
+
+  async closeAll(): Promise<void> {
+    this.authUnsubscribe?.();
+    this.authUnsubscribe = null;
+    this.teardownQuery();
+    for (const handle of [...this.handles]) handle.close();
+  }
+
+  private async refresh(): Promise<void> {
+    this.teardownQuery();
+    this.loaded = false;
+    this.snapshots.clear();
+    await this.ensureStarted();
+  }
+
+  private teardownQuery(): void {
+    this.querySubscription?.();
+    this.querySubscription = null;
+  }
+
+  private async ensureStarted(): Promise<void> {
+    if (this.querySubscription || this.starting || this.handles.size === 0) return;
+    this.starting = true;
+    try {
+      const hash = await this.deps.dataModule.query(
+        '_00_app_release' as any,
+        RELEASE_QUERY,
+        {},
+        this.ttl,
+      );
+      this.deps.sync.enqueueDownEvent({ type: 'register', payload: { hash } });
+      this.querySubscription = this.deps.dataModule.subscribe(
+        hash,
+        (records) => this.applyRecords(records as ReleaseRow[]),
+        { immediate: true },
+      );
+    } catch (err) {
+      this.logger.warn(
+        { err, Category: 'sp00ky-client::AppReleaseModule::register' },
+        'Failed to register app release query',
+      );
+    } finally {
+      this.starting = false;
+    }
+  }
+
+  private applyRecords(records: ReleaseRow[]): void {
+    this.snapshots.clear();
+    for (const row of records ?? []) {
+      if (row && typeof row.app === 'string' && typeof row.version === 'string') {
+        this.snapshots.set(row.app, {
+          version: row.version,
+          cacheBust: row.cache_bust === true,
+          mandatory: row.mandatory === true,
+          releasedAt: row.released_at,
+        });
+      }
+    }
+    this.loaded = true;
+    for (const handle of this.handles) {
+      handle.set(this.snapshots.get(handle.app) ?? EMPTY_SNAPSHOT);
+    }
+  }
+}

package/src/modules/auth/auth.local-first.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect, vi } from 'vitest';
+import { AuthService } from './index';
+
+// A SurrealDB record-access JWT carries the access method as `AC` and the
+// `$auth.id` record id as `ID`. Only the payload matters here - nothing in the
+// client verifies the signature, the server does.
+function jwt(claims: Record<string, unknown>): string {
+  const b64 = Buffer.from(JSON.stringify(claims)).toString('base64url');
+  return `header.${b64}.signature`;
+}
+
+const silentLogger = () =>
+  ({ debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn(), child: () => silentLogger() }) as any;
+
+function makeAuth(opts: { token?: string | null; query?: any; authenticate?: any } = {}) {
+  const store = new Map<string, unknown>();
+  if (opts.token) store.set('sp00ky_auth_token', opts.token);
+  const persistence = {
+    get: vi.fn(async (k: string) => store.get(k) ?? null),
+    set: vi.fn(async (k: string, v: unknown) => void store.set(k, v)),
+    remove: vi.fn(async (k: string) => void store.delete(k)),
+  } as any;
+  const remote = {
+    query: opts.query ?? vi.fn(async () => [[]]),
+    setAuthToken: vi.fn(),
+    getClient: () => ({
+      authenticate: opts.authenticate ?? vi.fn(async () => undefined),
+      invalidate: vi.fn(async () => undefined),
+    }),
+  } as any;
+  return { auth: new AuthService({} as any, remote, persistence, silentLogger()), remote, persistence, store };
+}
+
+describe('restoreSessionFromToken', () => {
+  it('restores the session from the cached token with NO network', async () => {
+    const { auth, remote } = makeAuth({ token: jwt({ AC: 'account', ID: 'user:abc' }) });
+
+    const userId = await auth.restoreSessionFromToken();
+
+    expect(userId).toBe('user:abc');
+    expect(auth.isAuthenticated).toBe(true);
+    expect(auth.currentUser?.id).toBe('user:abc');
+    expect(auth.access).toBe('account');
+    // The whole point: this is what makes a warm/offline boot paint.
+    expect(remote.query).not.toHaveBeenCalled();
+  });
+
+  it('notifies subscribers so query routing can be set before any registration', async () => {
+    const { auth } = makeAuth({ token: jwt({ AC: 'account', ID: 'user:abc' }) });
+    const seen: (string | null)[] = [];
+    auth.subscribe((uid) => seen.push(uid));
+
+    await auth.restoreSessionFromToken();
+
+    expect(seen).toContain('user:abc');
+  });
+
+  it('returns null when there is no token, and when the token carries no id', async () => {
+    expect(await makeAuth().auth.restoreSessionFromToken()).toBeNull();
+    const noId = makeAuth({ token: jwt({ AC: 'account' }) });
+    expect(await noId.auth.restoreSessionFromToken()).toBeNull();
+    expect(noId.auth.isAuthenticated).toBe(false);
+  });
+
+  it('survives a malformed token rather than throwing', async () => {
+    const { auth } = makeAuth({ token: 'not-a-jwt' });
+    expect(await auth.restoreSessionFromToken()).toBeNull();
+  });
+});
+
+describe('check() error handling', () => {
+  const token = jwt({ AC: 'account', ID: 'user:abc' });
+
+  it('KEEPS the cached session when the server is unreachable', async () => {
+    const { auth, persistence, store } = makeAuth({
+      token,
+      authenticate: vi.fn(async () => {
+        throw new Error('There was a problem with the underlying connection');
+      }),
+    });
+    await auth.restoreSessionFromToken();
+
+    await auth.check();
+
+    // A blip must not log the user out - that is what makes offline possible.
+    expect(auth.isAuthenticated).toBe(true);
+    expect(store.get('sp00ky_auth_token')).toBe(token);
+    expect(persistence.remove).not.toHaveBeenCalled();
+  });
+
+  it('signs out for real when the server REJECTS the token', async () => {
+    const { auth, store } = makeAuth({
+      token,
+      authenticate: vi.fn(async () => {
+        throw new Error('There was a problem with the database: Invalid token');
+      }),
+    });
+    await auth.restoreSessionFromToken();
+
+    await auth.check();
+
+    expect(auth.isAuthenticated).toBe(false);
+    expect(store.get('sp00ky_auth_token')).toBeUndefined();
+  });
+});
+
+// The transport authenticates a NEW socket from the token it was handed, not
+// from the one the app passed at construction (most apps pass none and sign in
+// later). If sign-in never reaches it, the supervisor's revive loop rebuilds a
+// socket that comes back anonymous and stays that way for the life of the page,
+// while `currentUser` — restored from local storage — keeps the UI signed in.
+// Every view registered after that carries `auth_id = ''`, so `$auth.id`
+// predicates resolve false and the user's own rows silently vanish.
+describe('auth token reaches the transport', () => {
+  it('hands the token to the transport when restoring from cache', async () => {
+    const token = jwt({ AC: 'account', ID: 'user:abc' });
+    const { auth, remote } = makeAuth({ token });
+
+    await auth.restoreSessionFromToken();
+
+    expect(remote.setAuthToken).toHaveBeenCalledWith(token);
+  });
+
+  it('hands the token to the transport on check()', async () => {
+    const token = jwt({ AC: 'account', ID: 'user:abc' });
+    const { auth, remote } = makeAuth({ token });
+
+    await auth.check();
+
+    expect(remote.setAuthToken).toHaveBeenCalledWith(token);
+  });
+
+  it('clears it on sign-out so a revived socket does not come back as the old user', async () => {
+    const { auth, remote } = makeAuth({ token: jwt({ AC: 'account', ID: 'user:abc' }) });
+    await auth.restoreSessionFromToken();
+
+    await auth.signOut();
+
+    expect(remote.setAuthToken).toHaveBeenLastCalledWith(null);
+  });
+});

package/src/modules/auth/events/index.ts

@@ -1,4 +1,5 @@
-import { createEventSystem, EventDefinition, EventSystem } from '../../../events/index';
+import type { EventDefinition, EventSystem } from '../../../events/index';
+import { createEventSystem } from '../../../events/index';
 
 export const AuthEventTypes = {
   AuthStateChanged: 'AUTH_STATE_CHANGED',

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'
     );