@spooky-sync/core 0.0.1-canary.263 → 0.0.1-canary.265

package/dist/types.d.ts

@@ -1,6 +1,141 @@
 import { QueryPlan, QueryPlan as QueryPlan$1, RecordId, SchemaStructure, WhereNode } from "@spooky-sync/query-builder";
 import { Level as Level$1, LoggerOptions } from "pino";
 
+//#region src/modules/auth/impersonation.d.ts
+
+/**
+ * Admin impersonation, client side.
+ *
+ * The server does the enforcing (see `impersonation_remote.surql` in the CLI):
+ * an admin calls `fn::_00_impersonate::start`, receives a token for the
+ * `_00_impersonate` access method, and authenticates with it, so `$auth.id` is
+ * the target user. Everything here is state and timers around that:
+ *
+ * - the admin's own token is kept under {@link ORIGIN_TOKEN_KEY} so Stop (and a
+ *   reload in between) can return to it;
+ * - the impersonation state is derived from the token's claims, never stored
+ *   separately, so it cannot disagree with the session actually in use;
+ * - the token is re-signed before it expires, and the session is polled so a
+ *   stop or revocation made elsewhere reaches an open WebSocket quickly.
+ */
+/** Access method impersonation tokens are issued for. */
+declare const IMPERSONATION_ACCESS = "_00_impersonate";
+/** Persistence key holding the admin's own token while impersonating. */
+declare const ORIGIN_TOKEN_KEY = "sp00ky_auth_token_origin";
+/** How often an active impersonation re-checks its session on the server. */
+declare const SESSION_POLL_MS = 60000;
+interface ImpersonationInfo {
+  /** `_00_impersonation:<id>` the session is bound to. */
+  session: string;
+  /** Record id being impersonated. */
+  target: string;
+  /** Record id of the admin. */
+  admin: string;
+  /** When the current token expires (it is renewed before then). */
+  tokenExpiresAt: Date | null;
+}
+interface TokenClaims {
+  access: string | null;
+  userId: string | null;
+  exp: number | null;
+  impersonation: {
+    session: string;
+    admin: string;
+  } | null;
+}
+/**
+ * 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.
+ *
+ * Returns nulls on any malformed input.
+ */
+declare function decodeTokenClaims(token: string): TokenClaims;
+/** The impersonation a token represents, or null for a regular session. */
+declare function impersonationFromToken(token: string | null): ImpersonationInfo | null;
+/** Same impersonation, for change detection (renewals only move the expiry). */
+declare function sameImpersonation(a: ImpersonationInfo | null, b: ImpersonationInfo | null): boolean;
+/**
+ * When to renew a token expiring at `expSecs`: at 80% of its remaining life,
+ * never sooner than 5s from now, and immediately once it is inside that.
+ */
+declare function renewDelayMs(expSecs: number, nowMs: number): number;
+interface ImpersonationTimerHost {
+  /** Current impersonation, or null. */
+  current(): ImpersonationInfo | null;
+  /** Re-sign the token. Rejects when the session has ended. */
+  renew(): Promise<void>;
+  /** Whether the server still considers the session live. */
+  stillActive(): Promise<boolean>;
+  /** Leave the impersonation because the server ended it. */
+  endedRemotely(reason: string): Promise<void>;
+  /** Whether a failure was a reachability problem (retry) rather than an answer. */
+  isNetworkError(error: unknown): boolean;
+}
+/**
+ * The two timers an active impersonation needs. `sync()` is called whenever
+ * the auth state changes and arms or clears them to match.
+ */
+declare class ImpersonationTimers {
+  private host;
+  private renewTimer;
+  private pollTimer;
+  private armedFor;
+  constructor(host: ImpersonationTimerHost);
+  sync(): void;
+  clear(): void;
+  private renew;
+  private poll;
+}
+//#endregion
+//#region src/modules/auth/impersonation-banner.d.ts
+/**
+ * Restyling of the built-in banner. Every field is optional; anything unset
+ * keeps the default. Colours are plain CSS values, so a project can pass its
+ * own tokens (`var(--brand-warning)`) as long as they resolve at the document
+ * level.
+ */
+interface ImpersonationBannerTheme {
+  /** Height of the warning bar above the page. */
+  heightPx?: number;
+  /** Gutter left, right and below the page. `0` frames only from the top. */
+  insetPx?: number;
+  /** Radius of the framed page's corners. `0` squares them off. */
+  radiusPx?: number;
+  /** The backdrop behind the page. Any CSS `background` value. */
+  background?: string;
+  /** Colour of the warning text on the backdrop. */
+  text?: string;
+  /** Background of the Stop button. */
+  accent?: string;
+  /** Text colour of the Stop button. */
+  accentText?: string;
+  /** Label for the Stop button. Defaults to `Stop`. */
+  stopLabel?: string;
+  /** The warning sentence. Defaults to `Impersonating <target> as <admin>`.
+   *  Wrap a run in `**` to emphasise it; the result is text, never markup. */
+  label?: (info: ImpersonationInfo) => string;
+  /** Keep the bar but leave the page's own layout completely alone. The CSS
+   *  variable is still published, so the app can do its own offset. */
+  noPageShift?: boolean;
+}
+interface ImpersonationBannerConfig {
+  /**
+   * - `'default'` renders the built-in banner.
+   * - `'custom'` leaves the page alone so the app can render its own from
+   *   `useImpersonation()` / `auth.subscribeImpersonation`. Acknowledge it
+   *   with `client.acknowledgeImpersonationBanner()` while it is on screen;
+   *   if nothing acknowledges within {@link CUSTOM_BANNER_GRACE_MS}, the
+   *   built-in banner appears, on the assumption that the custom one failed
+   *   to render rather than that nobody should be warned.
+   * - `'none'` renders nothing, ever. The app takes over responsibility for
+   *   telling whoever is looking at the page that it is not their session.
+   */
+  mode?: 'default' | 'custom' | 'none';
+  /** Restyle the built-in banner (also used if `custom` falls back). */
+  theme?: ImpersonationBannerTheme;
+}
+//#endregion
 //#region src/events/index.d.ts
 /**
  * Utility type to define the payload structure of an event.
@@ -643,6 +778,17 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    * flag is `true`. Defaults to `false`.
    */
   allowRawRemote?: boolean;
+  /**
+   * How the "you are impersonating" warning is shown while an admin acts as
+   * another user. The built-in one (hazard stripes at the top, the page
+   * shifted down onto them) needs no configuration; this is for restyling it,
+   * or replacing it with the app's own.
+   *
+   * See `ImpersonationBannerConfig`. Replacing it does not mean "no warning":
+   * if the app has not acknowledged its own banner shortly after impersonation
+   * starts, the built-in one appears anyway.
+   */
+  impersonationBanner?: ImpersonationBannerConfig;
   /**
    * Surface sustained sync failures as a "degraded" health status that the app
    * can observe via `subscribeToSyncHealth` (or the client-solid
@@ -1103,4 +1249,4 @@ interface DebounceOptions {
   delay?: number;
 }
 //#endregion
-export { RunOptions as A, SyncHealthStatus as B, QueryTimeToLive as C, RecordVersionArray as D, ReconnectConfig as E, StorageHealth as F, DatabaseEventTypes as G, UpdateOptions as H, StorageHealthStatus as I, EventSystem as J, SealedQuery as K, StoreType as L, Sp00kyConfig as M, Sp00kyQueryResult as N, RecordVersionDiff as O, Sp00kyQueryResultPromise as P, SyncHealth as R, QueryStatusCallback as S, QueryUpdateCallback as T, LocalStore as U, TimingPhase as V, DatabaseEventSystem as W, QueryConfig as _, Level$1 as a, QueryState as b, MutationCallback as c, PersistenceClient as d, PhaseStat as f, QueryAuthorityCallback as g, PreloadRefresh as h, InlineRow as i, ServerViewMeta as j, RegistrationTimings as k, MutationEvent as l, PreloadOptions as m, DebounceOptions as n, MATERIALIZATION_SAMPLE_WINDOW as o, PinoTransmit as p, EventDefinition as q, EventSubscriptionOptions as r, MembershipOutcome as s, ConnectionState as t, MutationEventType as u, QueryConfigRecord as v, QueryTimings as w, QueryStatus as x, QueryHash as y, SyncHealthConfig as z };
+export { ORIGIN_TOKEN_KEY as $, RunOptions as A, SyncHealthStatus as B, QueryTimeToLive as C, RecordVersionArray as D, ReconnectConfig as E, StorageHealth as F, DatabaseEventTypes as G, UpdateOptions as H, StorageHealthStatus as I, EventSystem as J, SealedQuery as K, StoreType as L, Sp00kyConfig as M, Sp00kyQueryResult as N, RecordVersionDiff as O, Sp00kyQueryResultPromise as P, ImpersonationTimers as Q, SyncHealth as R, QueryStatusCallback as S, QueryUpdateCallback as T, LocalStore as U, TimingPhase as V, DatabaseEventSystem as W, ImpersonationInfo as X, IMPERSONATION_ACCESS as Y, ImpersonationTimerHost as Z, QueryConfig as _, Level$1 as a, sameImpersonation as at, QueryState as b, MutationCallback as c, PersistenceClient as d, SESSION_POLL_MS as et, PhaseStat as f, QueryAuthorityCallback as g, PreloadRefresh as h, InlineRow as i, renewDelayMs as it, ServerViewMeta as j, RegistrationTimings as k, MutationEvent as l, PreloadOptions as m, DebounceOptions as n, decodeTokenClaims as nt, MATERIALIZATION_SAMPLE_WINDOW as o, PinoTransmit as p, EventDefinition as q, EventSubscriptionOptions as r, impersonationFromToken as rt, MembershipOutcome as s, ConnectionState as t, TokenClaims as tt, MutationEventType as u, QueryConfigRecord as v, QueryTimings as w, QueryStatus as x, QueryHash as y, SyncHealthConfig as z };

package/package.json

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

package/src/client/sp00ky-client.ts

@@ -81,6 +81,8 @@ export class Sp00kyClient<S extends SchemaStructure> {
   private readonly appReleases: AppReleaseModule<S>;
   /** Teardown for subscriptions the client itself owns. */
   private readonly disposers: Array<() => void> = [];
+  /** Assigned in `wireAdapters`, which the constructor always runs. */
+  private impersonationBanner!: ImpersonationBanner;
   private readonly devTools: DevToolsService;
   private hub: LeaderSyncHub | null = null;
   private forwarder: SyncForwarder | null = null;
@@ -177,10 +179,18 @@ 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());
+    // Whoever is looking at the page should be able to tell, and leave. The
+    // app can restyle this, replace it (`mode: 'custom'`, with a fallback if
+    // its own never renders) or take the job over entirely (`mode: 'none'`).
+    this.impersonationBanner = new ImpersonationBanner(
+      () => s.auth.stopImpersonating(),
+      this.config.impersonationBanner
+    );
+    const banner = this.impersonationBanner;
+    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 };
@@ -468,6 +478,17 @@ export class Sp00kyClient<S extends SchemaStructure> {
     return this.services.remote.query<T>(sql, vars);
   }
 
+  /**
+   * Tell the client that the app's own impersonation banner is on screen.
+   * Only meaningful with `impersonationBanner: { mode: 'custom' }`, where it
+   * cancels the fallback that would otherwise show the built-in banner. Call
+   * it while the custom banner is rendered (the Solid `useImpersonation`
+   * hook does it for you with `rendersBanner: true`).
+   */
+  acknowledgeImpersonationBanner(): void {
+    this.impersonationBanner.acknowledge();
+  }
+
   feature(key: string, options?: FeatureFlagOptions): FeatureFlagHandle {
     return this.featureFlags.feature(key, options);
   }