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

package/dist/types.d.ts

@@ -299,6 +299,12 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.260",
+  "version": "0.0.1-canary.261",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -63,8 +63,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.260",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.260",
+    "@spooky-sync/query-builder": "0.0.1-canary.261",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.261",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "blurhash": "^2.0.5",

package/src/boot/bucket-switch.saga.test.ts

@@ -5,7 +5,7 @@ import { fakeServices } from '../testing/services';
 import { buildEntry, buildOutboxItem, buildState } from '../testing/build';
 import * as R from '../state/reducers';
 import { defaultEnv } from '../query/env';
-import { bucketSwitch, rebindQueries } from './bucket-switch.saga';
+import { bucketSwitch, dropImpersonatedBucket, rebindQueries } from './bucket-switch.saga';
 
 const env = defaultEnv({ tables: [] } as any);
 const base = (over: Partial<ReturnType<typeof buildState>> = {}) => ({ ...buildState(), pendingBucket: 'u2', bucketId: 'u1', ...over });
@@ -57,6 +57,7 @@ describe('bucketSwitch', () => {
       'auth.sessionAuthId',
       'auth.access',
       'ssp.setSessionAuth',
+      'auth.consumeEndedImpersonation',
       'auth.token',
       'persistence.set',
     ]);
@@ -128,6 +129,34 @@ describe('bucketSwitch', () => {
   });
 });
 
+describe('dropImpersonatedBucket', () => {
+  it('drops the bucket it just left when that was the impersonated user', async () => {
+    const svc = fakeServices({ 'auth.consumeEndedImpersonation': () => 'user:bob' });
+    await runPure(dropImpersonatedBucket('bob'), { state: buildState(), handlers: { service: svc.handler } });
+    expect(svc.calls).toEqual([
+      ['auth.consumeEndedImpersonation', []],
+      ['local.dropBucket', ['bob']],
+    ]);
+  });
+  it('leaves every other bucket alone', async () => {
+    for (const [ended, left] of [[null, 'bob'], ['user:bob', 'alice'], ['user:bob', 'anon']] as const) {
+      const svc = fakeServices({ 'auth.consumeEndedImpersonation': () => ended });
+      await runPure(dropImpersonatedBucket(left), { state: buildState(), handlers: { service: svc.handler } });
+      expect(svc.names()).toEqual(['auth.consumeEndedImpersonation']);
+    }
+  });
+  it('logs a failed delete instead of failing the switch', async () => {
+    const svc = fakeServices({
+      'auth.consumeEndedImpersonation': () => 'user:bob',
+      'local.dropBucket': async () => {
+        throw new Error('handles still open');
+      },
+    });
+    const out = await runPure(dropImpersonatedBucket('bob'), { state: buildState(), handlers: { service: svc.handler } });
+    expect(out.emitted.filter((e) => e.type === 'log')).toHaveLength(1);
+  });
+});
+
 describe('rebindQueries', () => {
   it('re-seeds from the new store, rebuilds the local view (tolerating failures), emits authority flips', async () => {
     const s = R.compose(

package/src/boot/bucket-switch.saga.ts

@@ -5,7 +5,7 @@ import { fx } from '../kernel/effects';
 import type { ClientState, QueryEntry } from '../state/client-state';
 import { seedLifecycle, isAuthoritative } from '../state/lifecycle';
 import * as R from '../state/reducers';
-import { ANON_USER_ID } from '../modules/ref-tables';
+import { ANON_USER_ID, bucketIdForUser } from '../modules/ref-tables';
 import type { SagaEnv } from '../query/env';
 import { queryHashInput } from '../query/hash';
 import { isResolvedBefore, parseViewRow } from '../query/membership';
@@ -62,6 +62,7 @@ export function* bucketSwitch(env: SagaEnv, target: string, release: (() => void
   } finally {
     gate();
   }
+  yield* dropImpersonatedBucket(current);
   const token = (yield fx.service('auth.token')) as string | null;
   if (token) {
     try {
@@ -82,6 +83,21 @@ export function* bucketSwitch(env: SagaEnv, target: string, release: (() => void
   yield fx.dispatch({ type: 'Drain' });
 }
 
+/**
+ * An impersonation just ended and this switch left its bucket: delete that
+ * user's local data from the admin's device. Best-effort; a failure only
+ * leaves rows the server already let this admin read.
+ */
+export function* dropImpersonatedBucket(left: string): Saga<void> {
+  const ended = (yield fx.service('auth.consumeEndedImpersonation')) as string | null;
+  if (!ended || left === ANON_USER_ID || bucketIdForUser(ended) !== left) return;
+  try {
+    yield fx.service('local.dropBucket', left);
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'warn', message: 'could not delete the impersonated bucket', data: { bucket: left, error } });
+  }
+}
+
 /** Re-seed every active query from the new store and rebuild its SSP view. */
 export function* rebindQueries(): Saga<void> {
   const [entries, sessionId] = (yield fx.state.read((s) => [[...s.queries.values()], s.sessionId])) as [QueryEntry[], string | null];

package/src/client/services.ts

@@ -249,6 +249,9 @@ export function createAdapters<S extends SchemaStructure>(config: Sp00kyConfig<S
     'local.beginSwitch': () => s.local.beginSwitch(),
     'local.currentBucketId': () => s.local.currentBucketId,
     'local.usesSurqlSchema': () => s.local.usesSurqlSchema,
+    'local.dropBucket': async (bucketId) => {
+      await s.local.dropBucket?.(bucketId);
+    },
     'migrator.provision': () => s.migrator.provision(config.schemaSurql),
     'blobs.start': async (bucketId) => {
       s.blobs.setMaxBytes(await resolveBlobBudget(config.blobCache?.maxBytes));
@@ -278,6 +281,7 @@ export function createAdapters<S extends SchemaStructure>(config: Sp00kyConfig<S
     'auth.access': () => s.auth.access,
     'auth.token': () => s.auth.token,
     'auth.currentUser': () => (s.auth.currentUser as Record<string, unknown> | null) ?? null,
+    'auth.consumeEndedImpersonation': () => s.auth.consumeEndedImpersonation(),
     'remote.connect': () => s.remote.connect(),
     'remote.releaseViews': (ids) => {
       const list = ids

package/src/client/sp00ky-client.ts

@@ -54,6 +54,7 @@ import { DEGRADE_AFTER_FAILURES, OUTBOX_BATCH_SIZE, PUSH_TIMEOUT_MS } from '../k
 import { Runtime } from './runtime';
 import { createAdapters, createServices, createTabsCoordinator, type ServiceHost, type Services } from './services';
 import { BucketHandle } from './bucket-handle';
+import { ImpersonationBanner } from '../modules/auth/impersonation-banner';
 import type { LeaderSyncHub, SyncForwarder } from '../services/tabs/coordinator';
 
 const UNKNOWN_STORAGE_HEALTH: StorageHealth = Object.freeze({ status: 'unknown', fallback: false });
@@ -78,6 +79,8 @@ export class Sp00kyClient<S extends SchemaStructure> {
   private readonly runtime: Runtime;
   private readonly featureFlags: FeatureFlagModule<S>;
   private readonly appReleases: AppReleaseModule<S>;
+  /** Teardown for subscriptions the client itself owns. */
+  private readonly disposers: Array<() => void> = [];
   private readonly devTools: DevToolsService;
   private hub: LeaderSyncHub | null = null;
   private forwarder: SyncForwarder | null = null;
@@ -174,6 +177,10 @@ export class Sp00kyClient<S extends SchemaStructure> {
     s.streamProcessor.addReceiver(receiver);
     s.connectionSupervisor.subscribe((state) => void this.runtime.dispatch({ type: 'ConnectionChanged', state }));
     s.auth.subscribe((userId) => void this.runtime.dispatch({ type: 'AuthFlip', userId }));
+    // The impersonation banner is not optional: whoever is looking at the page
+    // must be able to tell, and leave, whatever the app renders.
+    const banner = new ImpersonationBanner(() => s.auth.stopImpersonating());
+    this.disposers.push(s.auth.subscribeImpersonation((info) => banner.update(info)), () => banner.unmount());
     this.runtime.on('tabs:broadcast', (e) => {
       if (e.type !== 'tabs:broadcast') return;
       const msg = e.message as { type: string; records?: unknown[]; mutationId?: string };
@@ -224,6 +231,7 @@ export class Sp00kyClient<S extends SchemaStructure> {
   async close(): Promise<void> {
     const s = this.services;
     s.connectionSupervisor.dispose();
+    for (const dispose of this.disposers.splice(0)) dispose();
     this.runtime.dispose();
     await this.featureFlags.closeAll();
     await this.appReleases.closeAll();

package/src/kernel/effects.ts

@@ -75,6 +75,7 @@ export interface ServiceCalls {
   'local.beginSwitch': () => () => void;
   'local.currentBucketId': () => string;
   'local.usesSurqlSchema': () => boolean;
+  'local.dropBucket': (bucketId: string) => Promise<void>;
   'migrator.provision': () => Promise<void>;
   'blobs.start': (bucketId: string) => Promise<void>;
   'blobs.setNamespace': (bucketId: string) => Promise<void>;
@@ -91,6 +92,7 @@ export interface ServiceCalls {
   'auth.access': () => string | null;
   'auth.token': () => string | null;
   'auth.currentUser': () => Record<string, unknown> | null;
+  'auth.consumeEndedImpersonation': () => string | null;
   'remote.connect': () => Promise<void>;
   'remote.releaseViews': (ids: unknown[]) => void;
   'supervisor.start': () => void;

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

@@ -1,8 +1,10 @@
 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 = {
@@ -10,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]);
 }

package/src/modules/auth/impersonation-banner.ts

@@ -0,0 +1,112 @@
+import type { ImpersonationInfo } from './impersonation';
+
+/** Height the banner occupies. Also published as the CSS variable
+ *  `--sp00ky-impersonation-banner-height` on `<html>` (`0px` when hidden), so
+ *  an app can offset fixed headers. */
+export const BANNER_HEIGHT_PX = 36;
+
+const HOST_TAG = 'sp00ky-impersonation-banner';
+
+// The shadow root keeps app CSS away from the bar, but the host element itself
+// is in the page and matches the page's selectors (`div { display: none }`).
+// An `!important` rule on `:host` wins over the page's own `!important`
+// (inner tree context), which keeps the host rendered whatever the app says.
+const STYLE = `
+:host {
+  all: initial !important;
+  display: block !important;
+  visibility: visible !important;
+  opacity: 1 !important;
+  position: static !important;
+  transform: none !important;
+  clip-path: none !important;
+}
+.bar {
+  position: fixed; inset: 0 0 auto 0; height: ${BANNER_HEIGHT_PX}px; z-index: 2147483647;
+  display: flex; align-items: center; justify-content: center; gap: 12px; padding: 0 12px;
+  box-sizing: border-box; background: #b91c1c; color: #fff;
+  font: 600 13px/1 system-ui, -apple-system, "Segoe UI", sans-serif;
+  box-shadow: 0 1px 4px rgba(0,0,0,.35);
+}
+.text { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0; }
+.text b { font-weight: 800; }
+button {
+  flex: none; cursor: pointer; border: 1px solid rgba(255,255,255,.8); border-radius: 6px;
+  background: #fff; color: #b91c1c; font: 700 12px/1 system-ui, sans-serif; padding: 6px 12px;
+}
+button:disabled { opacity: .6; cursor: progress; }
+`;
+
+/**
+ * The "you are impersonating" bar. Mounted by the client whenever the session
+ * is an impersonation, in its own closed shadow root so app styles cannot hide
+ * or restyle it. Every piece of text goes through `textContent`.
+ */
+export class ImpersonationBanner {
+  private host: HTMLElement | null = null;
+  private text: HTMLElement | null = null;
+
+  constructor(private onStop: () => Promise<void>) {}
+
+  static supported(): boolean {
+    return typeof document !== 'undefined' && typeof document.createElement === 'function';
+  }
+
+  update(info: ImpersonationInfo | null): void {
+    if (!ImpersonationBanner.supported()) return;
+    if (!info) {
+      this.unmount();
+      return;
+    }
+    this.mount();
+    const text = this.text!;
+    text.replaceChildren(
+      document.createTextNode('Impersonating '),
+      bold(info.target),
+      document.createTextNode(` as ${info.admin}`)
+    );
+    text.title = `Impersonating ${info.target} as ${info.admin}. Every write is audited.`;
+  }
+
+  unmount(): void {
+    this.host?.remove();
+    this.host = this.text = null;
+    if (typeof document !== 'undefined') {
+      document.documentElement?.style.setProperty('--sp00ky-impersonation-banner-height', '0px');
+    }
+  }
+
+  private mount(): void {
+    if (this.host?.isConnected) return;
+    const host = document.createElement(HOST_TAG);
+    const root = host.attachShadow({ mode: 'closed' });
+    const style = document.createElement('style');
+    style.textContent = STYLE;
+    const bar = document.createElement('div');
+    bar.className = 'bar';
+    bar.setAttribute('role', 'alert');
+    const text = document.createElement('span');
+    text.className = 'text';
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.textContent = 'Stop impersonating';
+    button.addEventListener('click', () => {
+      button.disabled = true;
+      this.onStop().finally(() => {
+        button.disabled = false;
+      });
+    });
+    bar.append(text, button);
+    root.append(style, bar);
+    (document.body ?? document.documentElement).appendChild(host);
+    document.documentElement.style.setProperty('--sp00ky-impersonation-banner-height', `${BANNER_HEIGHT_PX}px`);
+    this.host = host;
+    this.text = text;
+  }
+}
+
+function bold(value: string): HTMLElement {
+  const b = document.createElement('b');
+  b.textContent = value;
+  return b;
+}

package/src/modules/auth/impersonation.test.ts

@@ -0,0 +1,282 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { AuthService } from './index';
+import {
+  decodeTokenClaims,
+  impersonationFromToken,
+  ImpersonationTimers,
+  ORIGIN_TOKEN_KEY,
+  renewDelayMs,
+  SESSION_POLL_MS,
+} from './impersonation';
+
+function jwt(claims: Record<string, unknown>): string {
+  const b64 = Buffer.from(JSON.stringify(claims)).toString('base64url');
+  return `header.${b64}.signature`;
+}
+
+const ADMIN = jwt({ AC: 'account', ID: 'user:alice', exp: 9_999_999_999 });
+const impToken = (n = 1, extra: Record<string, unknown> = {}) =>
+  jwt({
+    AC: '_00_impersonate',
+    ID: 'user:bob',
+    exp: Math.floor(Date.now() / 1000) + 900,
+    spky_imp: '_00_impersonation:s1',
+    spky_admin: 'user:alice',
+    n,
+    ...extra,
+  });
+
+const silentLogger = () =>
+  ({ debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn(), child: () => silentLogger() }) as any;
+
+/**
+ * A fake server: tracks which token the socket is authenticated with, and
+ * answers the handful of statements the auth flow sends. `ended` simulates a
+ * stop or revocation made elsewhere.
+ */
+function makeServer(opts: { refuse?: Set<string>; unreachable?: boolean } = {}) {
+  const state = { socketToken: null as string | null, ended: false, stops: [] as unknown[], renews: 0 };
+  const idFor = (token: string | null) => (token ? decodeTokenClaims(token).userId : null);
+  const query = vi.fn(async (sql: string, vars?: Record<string, unknown>) => {
+    if (opts.unreachable && sql.includes('fn::_00_impersonate::stop')) {
+      throw new Error('There was a problem with the underlying connection');
+    }
+    if (sql.includes('fn::_00_impersonate::start')) return [{ token: impToken(), session: '_00_impersonation:s1' }];
+    if (sql.includes('fn::_00_impersonate::renew')) {
+      if (state.ended) throw new Error('Impersonation session has ended.');
+      state.renews++;
+      return [{ token: impToken(state.renews + 1) }];
+    }
+    if (sql.includes('fn::_00_impersonate::current')) return [state.ended ? null : { session: '_00_impersonation:s1' }];
+    if (sql.includes('fn::_00_impersonate::stop')) {
+      state.stops.push(vars?.session);
+      state.ended = true;
+      return [null];
+    }
+    if (sql.includes('fn::_00_impersonate::list_users')) return [[{ id: 'user:bob', is_admin: false }]];
+    if (sql.includes('$auth.id')) return [[{ id: idFor(state.socketToken) }]];
+    throw new Error(`unexpected statement ${sql}`);
+  });
+  const authenticate = vi.fn(async (token: string) => {
+    if (opts.refuse?.has(token) || (state.ended && decodeTokenClaims(token).impersonation)) {
+      throw new Error('Impersonation session is no longer valid.');
+    }
+    state.socketToken = token;
+  });
+  return { state, query, authenticate };
+}
+
+function makeAuth(server: ReturnType<typeof makeServer>, stored: Record<string, string> = {}) {
+  const store = new Map<string, unknown>(Object.entries(stored));
+  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: server.query,
+    setAuthToken: vi.fn(),
+    getClient: () => ({ authenticate: server.authenticate, invalidate: vi.fn(async () => undefined) }),
+  } as any;
+  const auth = new AuthService({} as any, remote, persistence, silentLogger());
+  return { auth, store, remote };
+}
+
+async function signedInAdmin(server = makeServer()) {
+  const ctx = makeAuth(server);
+  await ctx.auth.check(ADMIN);
+  return { ...ctx, server };
+}
+
+beforeEach(() => {
+  vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval'] });
+});
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('token claims', () => {
+  it('recognises only impersonation tokens', () => {
+    expect(impersonationFromToken(ADMIN)).toBeNull();
+    expect(impersonationFromToken(null)).toBeNull();
+    expect(impersonationFromToken('garbage')).toBeNull();
+    // A regular token cannot pose as one by carrying the claim.
+    expect(impersonationFromToken(jwt({ AC: 'account', ID: 'user:x', spky_imp: 's', spky_admin: 'a' }))).toBeNull();
+    const info = impersonationFromToken(impToken());
+    expect(info).toMatchObject({ session: '_00_impersonation:s1', target: 'user:bob', admin: 'user:alice' });
+    expect(info?.tokenExpiresAt).toBeInstanceOf(Date);
+  });
+
+  it('renews at 80% of the remaining life, never later than expiry', () => {
+    expect(renewDelayMs(1_000, 0)).toBe(800_000);
+    expect(renewDelayMs(10, 0)).toBe(8_000);
+    expect(renewDelayMs(4, 0)).toBe(0);
+    expect(renewDelayMs(1, 5_000)).toBe(0);
+  });
+});
+
+describe('impersonate / stopImpersonating', () => {
+  it('switches the session to the target and keeps the admin token aside', async () => {
+    const { auth, store, server } = await signedInAdmin();
+    const changes: (string | null)[] = [];
+    auth.subscribeImpersonation((i) => changes.push(i?.target ?? null));
+
+    const info = await auth.impersonate('user:bob', 'support ticket');
+
+    expect(info.target).toBe('user:bob');
+    expect(auth.currentUser.id).toBe('user:bob');
+    expect(auth.access).toBe('_00_impersonate');
+    expect(store.get(ORIGIN_TOKEN_KEY)).toBe(ADMIN);
+    expect(server.state.socketToken).toBe(auth.token);
+    expect(changes).toEqual([null, 'user:bob']);
+  });
+
+  it('refuses to nest', async () => {
+    const { auth } = await signedInAdmin();
+    await auth.impersonate('user:bob', 'support ticket');
+    await expect(auth.impersonate('user:carol', 'again')).rejects.toThrow('Already impersonating');
+  });
+
+  it('stays the admin when the server refuses the issued token', async () => {
+    const server = makeServer();
+    const refused = impToken();
+    server.query.mockImplementationOnce(async () => [{ token: refused }]);
+    server.authenticate.mockImplementation(async (token: string) => {
+      if (token === refused) throw new Error('Impersonation session is no longer valid.');
+      server.state.socketToken = token;
+    });
+    const { auth, store } = await signedInAdmin(server);
+
+    await expect(auth.impersonate('user:carol', 'support ticket')).rejects.toThrow('no longer valid');
+    expect(auth.currentUser.id).toBe('user:alice');
+    expect(auth.impersonation).toBeNull();
+    expect(store.has(ORIGIN_TOKEN_KEY)).toBe(false);
+    expect(server.state.socketToken).toBe(ADMIN);
+  });
+
+  it('stop ends the server session and returns to the admin', async () => {
+    const { auth, store, server } = await signedInAdmin();
+    await auth.impersonate('user:bob', 'support ticket');
+
+    await auth.stopImpersonating();
+
+    expect(server.state.stops).toEqual(['_00_impersonation:s1']);
+    expect(auth.currentUser.id).toBe('user:alice');
+    expect(auth.token).toBe(ADMIN);
+    expect(auth.impersonation).toBeNull();
+    expect(store.get('sp00ky_auth_token')).toBe(ADMIN);
+    expect(store.has(ORIGIN_TOKEN_KEY)).toBe(false);
+    expect(auth.consumeEndedImpersonation()).toBe('user:bob');
+    expect(auth.consumeEndedImpersonation()).toBeNull();
+  });
+
+  it('stop still leaves the target when the server is unreachable', async () => {
+    const { auth } = await signedInAdmin(makeServer({ unreachable: true }));
+    await auth.impersonate('user:bob', 'support ticket');
+
+    await auth.stopImpersonating();
+
+    expect(auth.currentUser.id).toBe('user:alice');
+    expect(auth.impersonation).toBeNull();
+  });
+
+  it('signs out entirely when the admin token is refused on the way back', async () => {
+    const server = makeServer({ refuse: new Set([ADMIN]) });
+    const { auth, store } = makeAuth(server, {
+      sp00ky_auth_token: impToken(),
+      [ORIGIN_TOKEN_KEY]: ADMIN,
+    });
+    await auth.check();
+    expect(auth.impersonation?.target).toBe('user:bob');
+
+    await auth.stopImpersonating();
+
+    expect(auth.isAuthenticated).toBe(false);
+    expect(auth.currentUser).toBeNull();
+    expect(store.has('sp00ky_auth_token')).toBe(false);
+  });
+
+  it('a revoked impersonation token at boot returns to the admin instead of signing out', async () => {
+    const server = makeServer();
+    server.state.ended = true;
+    const { auth } = makeAuth(server, { sp00ky_auth_token: impToken(), [ORIGIN_TOKEN_KEY]: ADMIN });
+
+    await auth.check();
+
+    expect(auth.isAuthenticated).toBe(true);
+    expect(auth.currentUser.id).toBe('user:alice');
+  });
+
+  it('an impersonation token with no admin token behind it signs out', async () => {
+    const server = makeServer();
+    server.state.ended = true;
+    const { auth } = makeAuth(server, { sp00ky_auth_token: impToken() });
+
+    await auth.check();
+
+    expect(auth.isAuthenticated).toBe(false);
+  });
+
+  it('signOut while impersonating ends the session and forgets the admin token', async () => {
+    const { auth, store, server } = await signedInAdmin();
+    await auth.impersonate('user:bob', 'support ticket');
+
+    await auth.signOut();
+
+    expect(server.state.stops).toEqual(['_00_impersonation:s1']);
+    expect(auth.isAuthenticated).toBe(false);
+    expect(store.has(ORIGIN_TOKEN_KEY)).toBe(false);
+    expect(store.has('sp00ky_auth_token')).toBe(false);
+  });
+
+  it('search goes through the admin-only function', async () => {
+    const { auth } = await signedInAdmin();
+    expect(await auth.searchImpersonationTargets('bo')).toEqual([{ id: 'user:bob', is_admin: false }]);
+  });
+});
+
+describe('timers', () => {
+  it('renews the token before it expires', async () => {
+    const { auth, server } = await signedInAdmin();
+    await auth.impersonate('user:bob', 'support ticket');
+    const first = auth.token;
+
+    await vi.advanceTimersByTimeAsync(800 * 1000);
+
+    expect(server.state.renews).toBe(1);
+    expect(auth.token).not.toBe(first);
+    expect(server.state.socketToken).toBe(auth.token);
+    expect(auth.impersonation?.target).toBe('user:bob');
+  });
+
+  it('a session ended elsewhere drops the client back to the admin within a poll', async () => {
+    const { auth, server } = await signedInAdmin();
+    await auth.impersonate('user:bob', 'support ticket');
+    server.state.ended = true;
+
+    await vi.advanceTimersByTimeAsync(SESSION_POLL_MS);
+
+    expect(auth.currentUser.id).toBe('user:alice');
+    expect(auth.impersonation).toBeNull();
+  });
+
+  it('keeps going through network failures on the poll', async () => {
+    let calls = 0;
+    const host = {
+      current: () => ({ session: 's', target: 't', admin: 'a', tokenExpiresAt: null }),
+      renew: vi.fn(),
+      stillActive: vi.fn(async () => {
+        calls++;
+        throw new Error('There was a problem with the underlying connection');
+      }),
+      endedRemotely: vi.fn(),
+      isNetworkError: () => true,
+    };
+    const timers = new ImpersonationTimers(host);
+    timers.sync();
+    await vi.advanceTimersByTimeAsync(SESSION_POLL_MS * 2);
+    expect(calls).toBe(2);
+    expect(host.endedRemotely).not.toHaveBeenCalled();
+    timers.clear();
+  });
+});