@spooky-sync/core 0.0.1-canary.16 → 0.0.1-canary.161

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

@@ -0,0 +1,125 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { AppReleaseModule } from './index';
+
+// Mirrors the FeatureFlagModule test rig: the DataModule mock captures the
+// single subscribe callback so tests can push live results, and counts
+// query() calls to assert the query is SHARED across apps.
+function makeDeps() {
+  let subCb: ((records: unknown[]) => void) | null = null;
+  const calls: Array<{ sql: string; params: unknown }> = [];
+  let authCb: ((userId: string | null) => void) | null = null;
+
+  const dataModule = {
+    query: async (_table: string, sql: string, params: unknown) => {
+      calls.push({ sql, params });
+      return `hash:${calls.length}`;
+    },
+    subscribe: (_hash: string, cb: (records: unknown[]) => void) => {
+      subCb = cb;
+      return () => {
+        subCb = null;
+      };
+    },
+  };
+  const sync = { enqueueDownEvent: () => {} };
+  const auth = {
+    subscribe: (cb: (userId: string | null) => void) => {
+      authCb = cb;
+      return () => {
+        authCb = null;
+      };
+    },
+  };
+  const logger = { child: () => ({ warn: () => {} }) };
+
+  const deps = { dataModule, sync, auth, logger } as any;
+  return {
+    deps,
+    calls,
+    push: (records: unknown[]) => subCb?.(records),
+    setUser: (id: string | null) => authCb?.(id),
+    hasSub: () => subCb !== null,
+  };
+}
+
+const tick = () => new Promise((r) => setTimeout(r, 0));
+
+describe('AppReleaseModule', () => {
+  let env: ReturnType<typeof makeDeps>;
+  let mod: AppReleaseModule<any>;
+
+  beforeEach(() => {
+    env = makeDeps();
+    mod = new AppReleaseModule(env.deps);
+  });
+
+  it('registers ONE shared, unfiltered query for many apps', async () => {
+    mod.release('web');
+    mod.release('admin');
+    await tick();
+
+    expect(env.calls.length).toBe(1);
+    expect(env.calls[0].sql).not.toContain('WHERE');
+    expect(env.calls[0].sql).toContain('FROM _00_app_release');
+  });
+
+  it('fans the shared result out to each handle by app', async () => {
+    const web = mod.release('web');
+    const missing = mod.release('missing');
+    await tick();
+
+    env.push([{ app: 'web', version: '1.2.0', cache_bust: true, mandatory: null }]);
+
+    expect(web.version()).toBe('1.2.0');
+    expect(web.snapshot().cacheBust).toBe(true);
+    expect(web.snapshot().mandatory).toBe(false);
+    expect(missing.version()).toBeUndefined();
+    expect(missing.updateAvailable('1.0.0')).toBe(false);
+  });
+
+  it('updateAvailable compares semver against the running build', async () => {
+    const web = mod.release('web');
+    await tick();
+
+    env.push([{ app: 'web', version: '1.2.0' }]);
+    expect(web.updateAvailable('1.1.9')).toBe(true);
+    expect(web.updateAvailable('1.2.0')).toBe(false);
+    expect(web.updateAvailable('1.3.0')).toBe(false);
+    expect(web.updateAvailable('garbage')).toBe(false);
+  });
+
+  it('observes row updates live without re-registering', async () => {
+    const web = mod.release('web');
+    await tick();
+
+    env.push([{ app: 'web', version: '1.0.0' }]);
+    expect(web.updateAvailable('1.0.0')).toBe(false);
+
+    env.push([{ app: 'web', version: '1.0.1', mandatory: true }]);
+    expect(web.updateAvailable('1.0.0')).toBe(true);
+    expect(web.snapshot().mandatory).toBe(true);
+
+    expect(env.calls.length).toBe(1);
+  });
+
+  it('seeds a late-created handle from the already-loaded snapshot', async () => {
+    mod.release('web');
+    await tick();
+    env.push([{ app: 'web', version: '2.0.0' }]);
+
+    const late = mod.release('web');
+    expect(late.version()).toBe('2.0.0');
+  });
+
+  it('re-registers on user change', async () => {
+    mod.init();
+    const web = mod.release('web');
+    await tick();
+    env.push([{ app: 'web', version: '1.0.0' }]);
+    expect(web.version()).toBe('1.0.0');
+
+    env.setUser('user:other');
+    await tick();
+    expect(env.hasSub()).toBe(true); // re-registered under the new session
+  });
+});

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/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,14 @@
-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';
 
 // Helper to pretty print types
 type Prettify<T> = {
@@ -38,11 +35,41 @@ type ExtractAccessParams<
       }>
     : never;
 
+/**
+ * Read the `AC` (access-method name) claim from a SurrealDB record-access
+ * JWT without verifying it — we only need the claim, the server enforces the
+ * token. Returns null on any malformed input. The in-browser SSP needs this
+ * to resolve `$access` in table permission predicates (mirrors the session's
+ * `$access` that the server's `fn::query::register` reads).
+ */
+function decodeAccessFromToken(token: string): string | null {
+  try {
+    const payload = token.split('.')[1];
+    if (!payload) return 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;
+    return typeof ac === 'string' ? ac : null;
+  } catch {
+    return null;
+  }
+}
+
 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();
@@ -95,11 +122,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;
@@ -119,13 +146,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,13 +167,13 @@ 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();
@@ -154,7 +181,7 @@ export class AuthService<S extends SchemaStructure> {
       }
     } catch (error) {
       this.logger.error(
-        { error, stack: (error as Error).stack, Category: 'spooky-client::AuthService::check' },
+        { error, stack: (error as Error).stack, Category: 'sp00ky-client::AuthService::check' },
         'Auth check failed'
       );
       await this.signOut();
@@ -170,12 +197,13 @@ export class AuthService<S extends SchemaStructure> {
     this.token = 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
     }
 
@@ -186,10 +214,21 @@ export class AuthService<S extends SchemaStructure> {
     this.token = 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 +251,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 +261,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 +292,7 @@ export class AuthService<S extends SchemaStructure> {
     }
 
     this.logger.info(
-      { accessName, Category: 'spooky-client::AuthService::signIn' },
+      { accessName, Category: 'sp00ky-client::AuthService::signIn' },
       'Attempting signin'
     );