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

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.262",
   "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.262",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.262",
     "@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,273 @@
+import type { ImpersonationInfo } from './impersonation';
+
+/** Height of the warning layer the page is shifted down by. Also published as
+ *  the CSS variable `--sp00ky-impersonation-banner-height` on `<html>` (`0px`
+ *  when hidden), so an app can offset its own fixed header. */
+export const BANNER_HEIGHT_PX = 44;
+
+/** Radius of the page's new top corners. */
+const PAGE_RADIUS_PX = 14;
+
+const HOST_TAG = 'sp00ky-impersonation-banner';
+
+/** Hazard stripes: the warning layer, and the `<html>` backdrop the page's
+ *  rounded corners reveal. */
+const STRIPES = 'repeating-linear-gradient(45deg, #f2b600 0 14px, #1c1403 14px 28px)';
+
+/** Keeps only the area OUTSIDE a corner's curve, so the nub is striped and
+ *  everything inside the curve stays the app's own. `center` is the curve's
+ *  centre inside the corner square. */
+function cornerMask(center: string): string {
+  return `radial-gradient(circle ${PAGE_RADIUS_PX}px at ${center}, transparent 0 ${PAGE_RADIUS_PX}px, #000 ${PAGE_RADIUS_PX}px)`;
+}
+
+// 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;
+}
+.layer {
+  position: fixed; inset: 0 0 auto 0; z-index: 2147483646; pointer-events: none;
+  height: ${BANNER_HEIGHT_PX}px; background: ${STRIPES};
+}
+/* The page's rounded top corners, drawn over whatever the app puts there.
+   The body element's own border-radius rounds its background, but a fixed app
+   header is not clipped by it, so each corner is also painted here: a striped
+   square masked down to the nub OUTSIDE the corner's curve, so the app's own
+   colour still shows inside it. */
+.corners {
+  position: fixed; left: 0; right: 0; top: ${BANNER_HEIGHT_PX}px;
+  height: ${PAGE_RADIUS_PX}px; z-index: 2147483646; pointer-events: none;
+}
+.corner {
+  position: absolute; top: 0; width: ${PAGE_RADIUS_PX}px; height: ${PAGE_RADIUS_PX}px;
+  background: ${STRIPES};
+}
+.corner.left {
+  left: 0;
+  -webkit-mask: ${cornerMask('100% 100%')};
+  mask: ${cornerMask('100% 100%')};
+}
+.corner.right {
+  right: 0;
+  -webkit-mask: ${cornerMask('0% 100%')};
+  mask: ${cornerMask('0% 100%')};
+}
+.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: 10px;
+  padding: 0 12px; box-sizing: border-box;
+  font: 600 13px/1 system-ui, -apple-system, "Segoe UI", sans-serif;
+}
+.pill {
+  display: flex; align-items: center; gap: 8px; min-width: 0; max-width: 100%;
+  padding: 6px 10px; border-radius: 999px;
+  background: rgba(14, 11, 2, .88); color: #fde68a;
+  box-shadow: 0 1px 6px rgba(0, 0, 0, .45);
+}
+.sign { flex: none; font-size: 14px; line-height: 1; }
+.text { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0; }
+.text b { color: #fff; font-weight: 800; }
+button {
+  flex: none; cursor: pointer; border: 0; border-radius: 999px;
+  background: #fde68a; color: #1c1403;
+  font: 800 12px/1 system-ui, sans-serif; padding: 7px 12px;
+  box-shadow: 0 1px 6px rgba(0, 0, 0, .45);
+}
+button:hover { background: #fff; }
+button:disabled { opacity: .6; cursor: progress; }
+@media (max-width: 520px) {
+  .bar { gap: 6px; padding: 0 8px; }
+  .pill { padding: 5px 8px; }
+}
+`;
+
+/**
+ * The "you are impersonating" warning.
+ *
+ * Drawn as a layer the page sits on top of: hazard stripes fill the top of the
+ * viewport, the page is pushed down by the bar's height and its new top
+ * corners are rounded, so the stripes show through around them. The bar itself
+ * lives in a closed shadow root, so app styles cannot hide or restyle it; the
+ * page-shifting styles are set inline and `!important` on `<html>` / `<body>`
+ * (nothing in a stylesheet outranks that), and the previous inline styles are
+ * restored on unmount.
+ *
+ * Every piece of text goes through `textContent`.
+ */
+export class ImpersonationBanner {
+  private host: HTMLElement | null = null;
+  private text: HTMLElement | null = null;
+  /** `style` attributes as the page had them before the shift. */
+  private saved: { html: string | null; body: string | null } | 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') return;
+    if (this.saved) {
+      restoreStyle(document.documentElement, this.saved.html);
+      restoreStyle(document.body, this.saved.body);
+      this.saved = null;
+    }
+    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;
+
+    // The striped ground the bar's text sits on: fixed, so it stays put while
+    // the page scrolls underneath. Never takes a click.
+    const layer = document.createElement('div');
+    layer.className = 'layer';
+    layer.setAttribute('aria-hidden', 'true');
+    const corners = document.createElement('div');
+    corners.className = 'corners';
+    corners.setAttribute('aria-hidden', 'true');
+    for (const side of ['left', 'right']) {
+      const corner = document.createElement('div');
+      corner.className = `corner ${side}`;
+      corners.append(corner);
+    }
+
+    const bar = document.createElement('div');
+    bar.className = 'bar';
+    bar.setAttribute('role', 'alert');
+    const pill = document.createElement('div');
+    pill.className = 'pill';
+    const sign = document.createElement('span');
+    sign.className = 'sign';
+    sign.textContent = '⚠';
+    const text = document.createElement('span');
+    text.className = 'text';
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.textContent = 'Stop';
+    button.addEventListener('click', () => {
+      button.disabled = true;
+      this.onStop().finally(() => {
+        button.disabled = false;
+      });
+    });
+    pill.append(sign, text);
+    bar.append(pill, button);
+    root.append(style, layer, corners, bar);
+    // Hosted on `<html>`, not `<body>`: the page shift clips `<body>` to the
+    // rounded top, and a bar inside it would be clipped away with everything
+    // else.
+    document.documentElement.appendChild(host);
+
+    this.shiftPage();
+    this.host = host;
+    this.text = text;
+  }
+
+  /**
+   * Push the page below the warning and round its new top edge.
+   *
+   * `<html>` carries the stripes as its background, because that is what the
+   * page's rounded corners reveal. `<body>` therefore has to be painted
+   * opaque: most apps colour it themselves, but a transparent one would let
+   * the stripes through behind the whole page, so its resolved colour is
+   * computed first and pinned.
+   */
+  private shiftPage(): void {
+    const root = document.documentElement;
+    const body = document.body;
+    if (!root || !body) return;
+    this.saved = { html: root.getAttribute('style'), body: body.getAttribute('style') };
+
+    const surface = resolveSurface(root, body);
+    root.style.setProperty('--sp00ky-impersonation-banner-height', `${BANNER_HEIGHT_PX}px`);
+    root.style.setProperty('background-image', STRIPES, 'important');
+    root.style.setProperty('padding-top', `${BANNER_HEIGHT_PX}px`, 'important');
+    root.style.setProperty('box-sizing', 'border-box', 'important');
+
+    body.style.setProperty('background-color', surface, 'important');
+    body.style.setProperty(
+      'border-radius',
+      `${PAGE_RADIUS_PX}px ${PAGE_RADIUS_PX}px 0 0`,
+      'important'
+    );
+    // Clips the app's own content — a fixed header included — to the rounded
+    // top, which is what makes the page read as a sheet over the stripes.
+    body.style.setProperty(
+      'clip-path',
+      `inset(0 round ${PAGE_RADIUS_PX}px ${PAGE_RADIUS_PX}px 0 0)`,
+      'important'
+    );
+    body.style.setProperty('box-shadow', '0 -6px 18px rgba(0, 0, 0, .35)', 'important');
+    // An app sized to `100vh` would otherwise overflow by the bar's height and
+    // put a scrollbar on a page that had none.
+    body.style.setProperty('min-height', `calc(100vh - ${BANNER_HEIGHT_PX}px)`, 'important');
+  }
+}
+
+/** Put an element's inline styles back exactly as they were. */
+function restoreStyle(el: HTMLElement | null, saved: string | null): void {
+  if (!el) return;
+  if (saved === null) el.removeAttribute('style');
+  else el.setAttribute('style', saved);
+}
+
+/**
+ * The colour to paint `<body>` with while the stripes sit behind it: whatever
+ * the page already paints (body first, then html), and failing that the canvas
+ * colour for the viewer's colour scheme.
+ */
+function resolveSurface(root: HTMLElement, body: HTMLElement): string {
+  for (const el of [body, root]) {
+    const color = getComputedStyle(el).backgroundColor;
+    if (color && !isTransparent(color)) return color;
+  }
+  const dark =
+    typeof matchMedia === 'function' && matchMedia('(prefers-color-scheme: dark)').matches;
+  return dark ? '#111111' : '#ffffff';
+}
+
+function isTransparent(color: string): boolean {
+  if (color === 'transparent') return true;
+  const parts = color.match(/[\d.]+/g);
+  return !!parts && parts.length === 4 && Number(parts[3]) === 0;
+}
+
+function bold(value: string): HTMLElement {
+  const b = document.createElement('b');
+  b.textContent = value;
+  return b;
+}