@spooky-sync/core 0.0.1-canary.260 → 0.0.1-canary.262

package/src/modules/auth/index.ts

@@ -10,6 +10,32 @@ export * from './events/index';
 import { AuthEventTypes, createAuthEventSystem } from './events/index';
 import type { PersistenceClient } from '../../types';
 import { classifySyncError } from '../../utils/error-classification';
+import {
+  decodeTokenClaims,
+  impersonationFromToken,
+  sameImpersonation,
+  ImpersonationTimers,
+  ORIGIN_TOKEN_KEY,
+} from './impersonation';
+import type { ImpersonationInfo } from './impersonation';
+export * from './impersonation';
+
+/** What `fn::_00_impersonate::list_users` returns per row. */
+export interface ImpersonationCandidate {
+  id: string;
+  is_admin: boolean;
+  [field: string]: unknown;
+}
+
+/** An open session, as `fn::_00_impersonate::active` lists it. */
+export interface ActiveImpersonation {
+  session: string;
+  target: string;
+  admin: string;
+  reason: string;
+  started_at: unknown;
+  expires_at: unknown;
+}
 
 // Helper to pretty print types
 type Prettify<T> = {
@@ -36,38 +62,6 @@ 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;
 }
@@ -88,6 +82,28 @@ export class AuthService<S extends SchemaStructure> {
 
   private events = createAuthEventSystem();
 
+  /** The impersonation last announced, for change detection. */
+  private announcedImpersonation: ImpersonationInfo | null = null;
+  /** Target of an impersonation that just ended, until the client purges its
+   *  local bucket (see `consumeEndedImpersonation`). */
+  private endedImpersonationTarget: string | null = null;
+  private impersonationTimers = new ImpersonationTimers({
+    current: () => this.impersonation,
+    renew: () => this.renewImpersonation(),
+    stillActive: async () => {
+      const [row] = await this.remote.query<[unknown]>('RETURN fn::_00_impersonate::current()');
+      return row !== null && row !== undefined;
+    },
+    endedRemotely: async (reason) => {
+      this.logger.warn(
+        { reason, Category: 'sp00ky-client::AuthService::impersonation' },
+        'Impersonation ended on the server; returning to the admin session'
+      );
+      await this.stopImpersonating({ serverEnded: true });
+    },
+    isNetworkError: (error) => classifySyncError(error) === 'network',
+  });
+
   public get eventSystem() {
     return this.events;
   }
@@ -127,6 +143,160 @@ export class AuthService<S extends SchemaStructure> {
   private notifyListeners() {
     const userId = this.currentUser?.id || null;
     this.events.emit(AuthEventTypes.AuthStateChanged, userId);
+    const impersonation = this.impersonation;
+    if (!sameImpersonation(impersonation, this.announcedImpersonation)) {
+      this.announcedImpersonation = impersonation;
+      this.events.emit(AuthEventTypes.ImpersonationChanged, impersonation);
+    }
+    this.impersonationTimers.sync();
+  }
+
+  /**
+   * The impersonation the current session is, or null. Derived from the
+   * token in use, so it always describes the identity the server sees.
+   */
+  get impersonation(): ImpersonationInfo | null {
+    return this.isAuthenticated ? impersonationFromToken(this.token) : null;
+  }
+
+  /** Subscribe to impersonation changes; called immediately with the current value. */
+  subscribeImpersonation(cb: (info: ImpersonationInfo | null) => void): () => void {
+    cb(this.impersonation);
+    const id = this.events.subscribe(AuthEventTypes.ImpersonationChanged, (event) => {
+      cb(event.payload);
+    });
+    return () => {
+      this.events.unsubscribe(id);
+    };
+  }
+
+  /**
+   * Act as `targetId` (a record id such as `user:abc`). Admins only, and only
+   * when the project enabled `impersonation` in sp00ky.yml: the server refuses
+   * everything else. `reason` is recorded in the audit log.
+   *
+   * The admin's session is kept aside and restored by
+   * {@link stopImpersonating}. Local data switches to the target's bucket
+   * exactly as on a sign-in, and that bucket is removed on stop.
+   */
+  async impersonate(targetId: string, reason: string): Promise<ImpersonationInfo> {
+    if (this.impersonation) throw new Error('Already impersonating; stop first.');
+    if (!this.isAuthenticated || !this.token) throw new Error('Sign in as an admin first.');
+    const originToken = this.token;
+    const [started] = await this.remote.query<[{ token: string }]>(
+      'RETURN fn::_00_impersonate::start($target, $reason)',
+      { target: targetId, reason }
+    );
+    if (!started?.token) throw new Error('The server did not return an impersonation token.');
+
+    await this.persistenceClient.set(ORIGIN_TOKEN_KEY, originToken);
+    try {
+      await this.remote.getClient().authenticate(started.token);
+    } catch (error) {
+      // The server refused the session it just issued (for example the
+      // target is an admin, or no longer exists). Nothing changed locally
+      // yet; put the admin's token back on the transport.
+      await this.persistenceClient.remove(ORIGIN_TOKEN_KEY);
+      this.remote.setAuthToken(originToken);
+      await this.remote.getClient().authenticate(originToken).catch(() => undefined);
+      throw error;
+    }
+    await this.check(started.token);
+    // A method call, not the getter: TS narrowed the getter to null above.
+    const info = impersonationFromToken(this.isAuthenticated ? this.token : null);
+    if (!info) {
+      await this.stopImpersonating();
+      throw new Error('Impersonation could not be established.');
+    }
+    this.logger.info(
+      { target: info.target, session: info.session, Category: 'sp00ky-client::AuthService::impersonate' },
+      'Impersonation started'
+    );
+    return info;
+  }
+
+  /**
+   * Return to the admin session. Always leaves the impersonated identity,
+   * even when the server cannot be reached: the admin token is restored
+   * locally first and verified afterwards, and a rejected admin token ends in
+   * a full sign-out rather than staying on the target.
+   */
+  async stopImpersonating(opts: { serverEnded?: boolean } = {}): Promise<void> {
+    const info = this.impersonation;
+    if (!info) return;
+    this.impersonationTimers.clear();
+    if (!opts.serverEnded) {
+      try {
+        await this.remote.query('RETURN fn::_00_impersonate::stop($session)', { session: info.session });
+      } catch (error) {
+        // The token expires on its own; the local switch below is what matters.
+        this.logger.warn(
+          { error, Category: 'sp00ky-client::AuthService::stopImpersonating' },
+          'Could not end the impersonation session on the server'
+        );
+      }
+    }
+    this.endedImpersonationTarget = info.target;
+    const origin = await this.persistenceClient.get<string>(ORIGIN_TOKEN_KEY);
+    await this.persistenceClient.remove(ORIGIN_TOKEN_KEY);
+    if (!origin || impersonationFromToken(origin)) {
+      await this.signOut();
+      return;
+    }
+    const { access, userId } = decodeTokenClaims(origin);
+    if (!userId) {
+      await this.signOut();
+      return;
+    }
+    // Optimistic switch back, as a warm boot does, then verify.
+    this.token = origin;
+    this.remote.setAuthToken(origin);
+    this.currentUser = { id: userId };
+    this.access = access ?? this.defaultAccessName();
+    await this.persistenceClient.set('sp00ky_auth_token', origin);
+    this.notifyListeners();
+    await this.check(origin);
+    this.logger.info(
+      { target: info.target, Category: 'sp00ky-client::AuthService::stopImpersonating' },
+      'Impersonation stopped'
+    );
+  }
+
+  /** Re-sign the impersonation token before it expires. */
+  async renewImpersonation(): Promise<void> {
+    if (!this.impersonation) return;
+    const [renewed] = await this.remote.query<[{ token: string }]>('RETURN fn::_00_impersonate::renew()');
+    if (!renewed?.token) throw new Error('Impersonation renewal returned no token.');
+    this.remote.setAuthToken(renewed.token);
+    await this.remote.getClient().authenticate(renewed.token);
+    this.token = renewed.token;
+    await this.persistenceClient.set('sp00ky_auth_token', renewed.token);
+    this.notifyListeners();
+  }
+
+  /** Users an admin may pick from. Admin-only on the server. */
+  async searchImpersonationTargets(search: string): Promise<ImpersonationCandidate[]> {
+    const [rows] = await this.remote.query<[ImpersonationCandidate[]]>(
+      'RETURN fn::_00_impersonate::list_users($search)',
+      { search }
+    );
+    return Array.isArray(rows) ? rows : [];
+  }
+
+  /** Open impersonation sessions. Admin-only on the server. */
+  async listActiveImpersonations(): Promise<ActiveImpersonation[]> {
+    const [rows] = await this.remote.query<[ActiveImpersonation[]]>('RETURN fn::_00_impersonate::active()');
+    return Array.isArray(rows) ? rows : [];
+  }
+
+  /**
+   * The target of an impersonation that ended, once. The bucket switch calls
+   * this after leaving a bucket so it can delete that user's local data.
+   */
+  consumeEndedImpersonation(): string | null {
+    const target = this.endedImpersonationTarget;
+    this.endedImpersonationTarget = null;
+    return target;
   }
 
   /**
@@ -178,8 +348,9 @@ export class AuthService<S extends SchemaStructure> {
   async check(accessToken?: string) {
     this.isLoading = true;
 
+    let token: string | undefined;
     try {
-      const token = accessToken || (await this.persistenceClient.get<string>('sp00ky_auth_token'));
+      token = accessToken || (await this.persistenceClient.get<string>('sp00ky_auth_token')) || undefined;
 
       if (!token) {
         this.logger.debug(
@@ -236,7 +407,7 @@ export class AuthService<S extends SchemaStructure> {
             { Category: 'sp00ky-client::AuthService::check' },
             'Token valid but user not found via fallback'
           );
-          await this.signOut();
+          await this.rejectToken(token);
         }
       }
     } catch (error) {
@@ -255,7 +426,7 @@ export class AuthService<S extends SchemaStructure> {
           { error, stack: (error as Error).stack, Category: 'sp00ky-client::AuthService::check' },
           'Auth check failed'
         );
-        await this.signOut();
+        await this.rejectToken(token);
       }
     } finally {
       this.isLoading = false;
@@ -263,9 +434,42 @@ export class AuthService<S extends SchemaStructure> {
   }
 
   /**
-   * Sign out and clear session
+   * The server refused `token`. A refused impersonation token (stopped,
+   * expired, or revoked) returns to the admin session instead of signing the
+   * admin out; anything else signs out.
+   */
+  private async rejectToken(token: string | undefined): Promise<void> {
+    if (token && impersonationFromToken(token)) {
+      if (!this.impersonation || this.token !== token) {
+        // A boot or explicit check with an impersonation token that is not
+        // the session in memory yet: adopt it so stop has something to leave.
+        this.token = token;
+        this.isAuthenticated = true;
+      }
+      await this.stopImpersonating({ serverEnded: true });
+      return;
+    }
+    await this.signOut();
+  }
+
+  /**
+   * Sign out and clear session. While impersonating this ends the
+   * impersonation and signs the admin out too.
    */
   async signOut() {
+    const impersonating = this.impersonation;
+    this.impersonationTimers.clear();
+    if (impersonating) {
+      this.endedImpersonationTarget = impersonating.target;
+      try {
+        await this.remote.query('RETURN fn::_00_impersonate::stop($session)', {
+          session: impersonating.session,
+        });
+      } catch (_e) {
+        // The token expires on its own.
+      }
+    }
+    await this.persistenceClient.remove(ORIGIN_TOKEN_KEY);
     this.token = null;
     this.remote.setAuthToken(null);
     this.currentUser = null;

package/src/modules/devtools/index.ts

@@ -14,7 +14,12 @@ export interface DevToolsEvent {
 }
 
 import type { QueryState, QueryTimings } from '../../types';
-import type { AuthService } from '../auth/index';
+import type {
+  AuthService,
+  ActiveImpersonation,
+  ImpersonationCandidate,
+  ImpersonationInfo,
+} from '../auth/index';
 import { AuthEventTypes } from '../auth/events/index';
 import {
   type BackendInfo,
@@ -44,6 +49,19 @@ export interface DevToolsQuerySource {
   phaseTimings(q: QueryState): QueryTimings;
 }
 
+export type ImpersonationOp = 'status' | 'listUsers' | 'start' | 'stop';
+
+export interface ImpersonationOpResult {
+  success: boolean;
+  error?: string;
+  /** Whether the generated schema says the project enabled impersonation. */
+  enabled?: boolean;
+  isAdmin?: boolean;
+  current?: ImpersonationInfo | null;
+  active?: ActiveImpersonation[];
+  users?: ImpersonationCandidate[];
+}
+
 export class DevToolsService implements StreamUpdateReceiver {
   private eventsHistory: DevToolsEvent[] = [];
   private eventIdCounter = 0;
@@ -400,6 +418,7 @@ export class DevToolsService implements StreamUpdateReceiver {
       auth: {
         authenticated: this.authService.isAuthenticated,
         userId: this.authService.currentUser?.id,
+        impersonation: this.authService.impersonation,
       },
       version: this.version,
       versions: {
@@ -431,6 +450,51 @@ export class DevToolsService implements StreamUpdateReceiver {
     });
   }
 
+  /**
+   * The Access tab's impersonation controls. Errors come back as
+   * `{ success: false, error }` with the server's own message, so the panel
+   * can show why (not an admin, feature disabled, target is an admin).
+   */
+  public async impersonationOp(
+    op: ImpersonationOp,
+    args: Record<string, unknown>
+  ): Promise<ImpersonationOpResult> {
+    const enabled = this.schema.policy?.impersonation === true;
+    try {
+      switch (op) {
+        case 'status': {
+          const current = this.authService.impersonation;
+          const snapshot = await this.flagsAdmin.getFlags().catch(() => null);
+          const isAdmin = snapshot?.isAdmin === true;
+          const active =
+            enabled && isAdmin && !current
+              ? await this.authService.listActiveImpersonations().catch(() => [])
+              : [];
+          return this.serializeForDevTools({ success: true, enabled, isAdmin, current, active });
+        }
+        case 'listUsers':
+          return this.serializeForDevTools({
+            success: true,
+            users: await this.authService.searchImpersonationTargets(String(args.search ?? '')),
+          });
+        case 'start': {
+          const current = await this.authService.impersonate(
+            String(args.target ?? ''),
+            String(args.reason ?? '')
+          );
+          return this.serializeForDevTools({ success: true, current });
+        }
+        case 'stop':
+          await this.authService.stopImpersonating();
+          return { success: true, current: null };
+        default:
+          return { success: false, error: `Unknown impersonation op: ${String(op)}` };
+      }
+    } catch (e) {
+      return { success: false, error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+
   /**
    * Full storage diagnostics for the DevTools Storage tab. Every section is
    * gathered independently and failures land in that section's `error` field,
@@ -631,6 +695,12 @@ export class DevToolsService implements StreamUpdateReceiver {
         // are denied outright. The override methods are purely local and
         // work signed out.
         getFlags: () => this.flagsAdmin.getFlags(),
+        // ---- Impersonation (Access tab) --------------------------------
+        // Every op is authorized by SurrealDB (`fn::_00_impersonate::*` are
+        // admin-only and absent unless the project enabled the feature);
+        // nothing here grants anything.
+        impersonationOp: (op: ImpersonationOp, args?: Record<string, unknown>) =>
+          this.impersonationOp(op, args ?? {}),
         setFlagEnabled: (key: string, enabled: boolean) =>
           this.flagsAdmin.setFlagEnabled(key, enabled),
         setFlagUserVariant: (key: string, variant: string, remove: boolean, userId?: string) =>

package/src/services/database/cache-engine.ts

@@ -135,6 +135,12 @@ export interface LocalStore extends LocalCacheEngine {
    * client facade, so adding this needs no change on their side.
    */
   readonly storageHealth?: StorageHealth;
+  /**
+   * Delete a bucket's persisted store. Never the open one. OPTIONAL and
+   * best-effort: used to remove an impersonated user's data from the admin's
+   * device once the impersonation ends.
+   */
+  dropBucket?(bucketId: string): Promise<void>;
   /** Fires immediately with the current snapshot, then on every change.
    *  Returns an unsubscribe function. */
   subscribeToStorageHealth?(cb: (health: StorageHealth) => void): () => void;

package/src/services/database/local.ts

@@ -255,6 +255,13 @@ export class LocalDatabaseService extends AbstractDatabaseService {
     );
   }
 
+  /** See `LocalStore.dropBucket`. A memory store keeps nothing to delete. */
+  async dropBucket(bucketId: string): Promise<void> {
+    if (bucketId === this.bucketId) throw new Error('Cannot drop the open bucket.');
+    if ((this.getConfig().store ?? 'memory') === 'memory') return;
+    await dropLocalIndexedDbStores(this.logger, bucketStoreName(bucketId));
+  }
+
   /**
    * Open `storeUrl` on `client` with tiered recovery:
    * tier 1 retries the same store (transient idb-handle races — preserves the

package/src/services/database/sqlite-cache-engine.ts

@@ -236,6 +236,23 @@ export class SqliteCacheEngine implements LocalStore {
     throw new Error('SqliteCacheEngine has no SurrealDB client (getClient is unavailable).');
   }
 
+  /**
+   * See `LocalStore.dropBucket`. Each bucket is its own OPFS SAH pool, whose
+   * directory sqlite-wasm names `.<pool name>` (`sp00ky-<bucket>`, see
+   * sqlite-open.ts). Fails harmlessly while a worker still holds its handles.
+   */
+  async dropBucket(bucketId: string): Promise<void> {
+    if (bucketId === this.bucketId) throw new Error('Cannot drop the open bucket.');
+    const storage = typeof navigator !== 'undefined' ? navigator.storage : undefined;
+    if (!storage?.getDirectory) return;
+    const root = await storage.getDirectory();
+    try {
+      await root.removeEntry(`.sp00ky-${bucketId}`, { recursive: true });
+    } catch (error) {
+      if ((error as DOMException)?.name !== 'NotFoundError') throw error;
+    }
+  }
+
   /** LocalStore alias; SQLite has no in-flight gate, so this maps to a rebuild. */
   switchStore(bucketId: string): Promise<void> {
     return this.switchBucket(bucketId);

package/src/testing/fake-services.ts

@@ -24,7 +24,7 @@ export function fakeServiceBundle<S extends SchemaStructure>(over: Partial<Servi
     streamProcessor: { addReceiver: (r: unknown) => void receivers.push(r), checkpoint: async () => undefined, dispose: noop } as any,
     migrator: {} as any,
     crdt: { closeAll: noop, dispose: noop, open: async () => 'field', close: noop } as any,
-    auth: { subscribe: (cb: (u: string | null) => void) => (authListeners.push(cb), noop), currentUser: null, isAuthenticated: false, eventSystem: { subscribe: noop } } as any,
+    auth: { subscribe: (cb: (u: string | null) => void) => (authListeners.push(cb), noop), subscribeImpersonation: () => noop, currentUser: null, isAuthenticated: false, impersonation: null, eventSystem: { subscribe: noop } } as any,
     tabs: null,
     tabsUnsupportedReason: 'test',
     tabId: 'tab-test',