@spooky-sync/core 0.0.1-canary.29 → 0.0.1-canary.291

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,209 @@
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+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?.();
+  }
+}
+
+/** The slice of the query engine this module drives: register a live query
+ *  locally, ask for its remote registration, subscribe to its rows. */
+export interface LiveQueryPort {
+  query(table: string, surql: string, params: Record<string, unknown>, ttl: QueryTimeToLive): Promise<string>;
+  subscribe(hash: string, cb: (records: Record<string, any>[]) => void, options?: { immediate?: boolean }): () => void;
+}
+export interface RemoteRegisterPort {
+  enqueueDownEvent(event: { type: 'register'; payload: { hash: string } }): void;
+}
+
+export interface AppReleaseModuleDeps<S extends SchemaStructure> {
+  dataModule: LiveQueryPort;
+  sync: RemoteRegisterPort;
+  auth: Pick<AuthService<S>, 'subscribe'>;
+  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,7 +1,10 @@
-import { createEventSystem, EventDefinition, EventSystem } from '../../../events/index';
+import type { EventDefinition, EventSystem } from '../../../events/index';
+import { createEventSystem } from '../../../events/index';
+import type { ImpersonationInfo } from '../impersonation';
 
 export const AuthEventTypes = {
   AuthStateChanged: 'AUTH_STATE_CHANGED',
+  ImpersonationChanged: 'IMPERSONATION_CHANGED',
 } as const;
 
 export type AuthEventTypeMap = {
@@ -9,10 +12,14 @@ export type AuthEventTypeMap = {
     typeof AuthEventTypes.AuthStateChanged,
     string | null
   >;
+  [AuthEventTypes.ImpersonationChanged]: EventDefinition<
+    typeof AuthEventTypes.ImpersonationChanged,
+    ImpersonationInfo | null
+  >;
 };
 
 export type AuthEventSystem = EventSystem<AuthEventTypeMap>;
 
 export function createAuthEventSystem(): AuthEventSystem {
-  return createEventSystem([AuthEventTypes.AuthStateChanged]);
+  return createEventSystem([AuthEventTypes.AuthStateChanged, AuthEventTypes.ImpersonationChanged]);
 }