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

package/AGENTS.md

@@ -33,7 +33,7 @@ re-materialized from state, never patched in place.
 
 ## Key exports (`src/index.ts`)
 
-- `Sp00kyClient<S>` — main class. Methods: `init()`, `create(id, payload)`, `update(table, id, payload, options?)`, `delete(table, id)`, `query(table, opts?)`, `preload(query, { signal? })`, `run(backend, route, payload)`, `bucket(name)`, `remoteQuery(sql, vars?)`, `useRemote(fn)`, `authenticate(token)`, `auth.signOut()`. Traffic indicators: `pendingMutationCount` / `subscribeToPendingMutations(cb)` (outbox depth), `fetchingQueryCount` / `subscribeToFetchActivity(cb)`. Failed-writes tray: `failedMutationCount`, `subscribeToFailedMutations(cb)`, `listFailedMutations()`, `retryFailedMutation(id)`, `discardFailedMutation(id)`.
+- `Sp00kyClient<S>` — main class. Methods: `init()`, `create(id, payload)`, `update(table, id, payload, options?)`, `delete(table, id)`, `query(table, opts?)`, `preload(query, { signal? })`, `run(backend, route, payload)`, `bucket(name)`, `remoteQuery(sql, vars?)`, `useRemote(fn)`, `authenticate(token)`, `auth.signOut()`. Admin impersonation (`impersonation.enabled` in sp00ky.yml, admins only, server-enforced): `auth.impersonate(targetId, reason)`, `auth.stopImpersonating()`, `auth.impersonation`, `auth.subscribeImpersonation(cb)`, `auth.searchImpersonationTargets(search)`; while active the client injects a warning bar with a Stop button (see `/docs/client/impersonation`). Traffic indicators: `pendingMutationCount` / `subscribeToPendingMutations(cb)` (outbox depth), `fetchingQueryCount` / `subscribeToFetchActivity(cb)`. Failed-writes tray: `failedMutationCount`, `subscribeToFailedMutations(cb)`, `listFailedMutations()`, `retryFailedMutation(id)`, `discardFailedMutation(id)`.
 - `FailedMutation` — a row of the `_00_failed_mutations` tray (`mutationType`, `recordId`, `data`, `beforeRecord`, `error`, `revert`).
 - `BucketHandle` — file storage handle (`put`, `get`, `delete`, `exists`), plus the cache-aware `read`, `url`, `pin`/`unpin`, `evict`, `prefetch`. `get` is always remote; `read`/`url` go through the blob cache.
 - `services/blobs/` — durable cache for bucket bytes: OPFS holds the files, `_00_blob` holds a manifest that reconcile rebuilds from disk (so a wiped local store costs metadata, not the offline cache). Nothing expires on a timer; eviction is LRU under a byte budget only, skipping pinned and on-screen entries. Config: `blobCache` in `types.ts`.

package/dist/index.d.ts

@@ -674,17 +674,120 @@ declare class StreamProcessorService {
   private normalizeValue;
 }
 //#endregion
+//#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/events/index.d.ts
 declare const AuthEventTypes: {
   readonly AuthStateChanged: "AUTH_STATE_CHANGED";
+  readonly ImpersonationChanged: "IMPERSONATION_CHANGED";
 };
 type AuthEventTypeMap = {
   [AuthEventTypes.AuthStateChanged]: EventDefinition<typeof AuthEventTypes.AuthStateChanged, string | null>;
+  [AuthEventTypes.ImpersonationChanged]: EventDefinition<typeof AuthEventTypes.ImpersonationChanged, ImpersonationInfo | null>;
 };
 type AuthEventSystem = EventSystem<AuthEventTypeMap>;
 declare function createAuthEventSystem(): AuthEventSystem;
 //#endregion
 //#region src/modules/auth/index.d.ts
+/** What `fn::_00_impersonate::list_users` returns per row. */
+interface ImpersonationCandidate {
+  id: string;
+  is_admin: boolean;
+  [field: string]: unknown;
+}
+/** An open session, as `fn::_00_impersonate::active` lists it. */
+interface ActiveImpersonation {
+  session: string;
+  target: string;
+  admin: string;
+  reason: string;
+  started_at: unknown;
+  expires_at: unknown;
+}
 type Prettify<T> = { [K in keyof T]: T[K] } & {};
 type MapColumnType<T extends ColumnSchema> = T['optional'] extends true ? TypeNameToTypeMap[T['type']] | undefined : TypeNameToTypeMap[T['type']];
 type ExtractAccessParams<S extends SchemaStructure, Name extends keyof S['access'], Method extends 'signIn' | 'signup'> = S['access'] extends undefined ? never : S['access'][Name] extends AccessDefinition ? Prettify<{ [K in keyof S['access'][Name][Method]['params']]: MapColumnType<S['access'][Name][Method]['params'][K]> }> : never;
@@ -705,6 +808,12 @@ declare class AuthService<S extends SchemaStructure> {
   access: string | null;
   isLoading: boolean;
   private events;
+  /** The impersonation last announced, for change detection. */
+  private announcedImpersonation;
+  /** Target of an impersonation that just ended, until the client purges its
+   *  local bucket (see `consumeEndedImpersonation`). */
+  private endedImpersonationTarget;
+  private impersonationTimers;
   get eventSystem(): AuthEventSystem;
   constructor(schema: S, remote: RemoteDatabaseService, persistenceClient: PersistenceClient, logger: Logger$1);
   init(): Promise<void>;
@@ -715,6 +824,43 @@ declare class AuthService<S extends SchemaStructure> {
    */
   subscribe(cb: (userId: string | null) => void): () => void;
   private notifyListeners;
+  /**
+   * 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;
+  /** Subscribe to impersonation changes; called immediately with the current value. */
+  subscribeImpersonation(cb: (info: ImpersonationInfo | null) => void): () => void;
+  /**
+   * 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.
+   */
+  impersonate(targetId: string, reason: string): Promise<ImpersonationInfo>;
+  /**
+   * 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.
+   */
+  stopImpersonating(opts?: {
+    serverEnded?: boolean;
+  }): Promise<void>;
+  /** Re-sign the impersonation token before it expires. */
+  renewImpersonation(): Promise<void>;
+  /** Users an admin may pick from. Admin-only on the server. */
+  searchImpersonationTargets(search: string): Promise<ImpersonationCandidate[]>;
+  /** Open impersonation sessions. Admin-only on the server. */
+  listActiveImpersonations(): Promise<ActiveImpersonation[]>;
+  /**
+   * 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;
   /**
    * Restore a session from the locally cached JWT, with NO network.
    *
@@ -738,7 +884,14 @@ declare class AuthService<S extends SchemaStructure> {
    */
   check(accessToken?: string): Promise<void>;
   /**
-   * 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 rejectToken;
+  /**
+   * Sign out and clear session. While impersonating this ends the
+   * impersonation and signs the admin out too.
    */
   signOut(): Promise<void>;
   private setSession;
@@ -1403,6 +1556,7 @@ 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>;
@@ -1419,6 +1573,7 @@ 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;
@@ -2250,6 +2405,8 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   private readonly runtime;
   private readonly featureFlags;
   private readonly appReleases;
+  /** Teardown for subscriptions the client itself owns. */
+  private readonly disposers;
   private readonly devTools;
   private hub;
   private forwarder;
@@ -2376,4 +2533,4 @@ declare function textToHtml(text: string): string;
  */
 
 //#endregion
-export { AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BLURHASH_IMAGE_EXTENSIONS, type BlobCacheStats, type BlobEntry, type BlobKey, type BlobReadOptions, type BlobUrlLease, type BlurhashEncodeOptions, type BlurhashSetting, BucketHandle, BucketPutOptions, BucketPutResult, CURSOR_COLORS, ConnectionState, CrdtField, CrdtManager, DEFAULT_LOCAL_OP_TIMEOUT_MS, DebounceOptions, EventSubscriptionOptions, type FailedMutationRow as FailedMutation, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagOverride, type FeatureFlagSnapshot, InlineRow, Level, LocalOpTimeoutError, MATERIALIZATION_SAMPLE_WINDOW, MembershipOutcome, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryAuthorityCallback, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, ReconnectConfig, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, ServerViewMeta, Sp00kyClient, Sp00kyClientDeps, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, blurhashSidecarPath, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, decode as decodeBlurhash, encode as encodeBlurhash, encodeImageToBlurhash, fileToUint8Array, isBlurhashValid, isImagePath, semverGt, textToHtml };
+export { ActiveImpersonation, AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BLURHASH_IMAGE_EXTENSIONS, type BlobCacheStats, type BlobEntry, type BlobKey, type BlobReadOptions, type BlobUrlLease, type BlurhashEncodeOptions, type BlurhashSetting, BucketHandle, BucketPutOptions, BucketPutResult, CURSOR_COLORS, ConnectionState, CrdtField, CrdtManager, DEFAULT_LOCAL_OP_TIMEOUT_MS, DebounceOptions, EventSubscriptionOptions, type FailedMutationRow as FailedMutation, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagOverride, type FeatureFlagSnapshot, IMPERSONATION_ACCESS, ImpersonationCandidate, ImpersonationInfo, ImpersonationTimerHost, ImpersonationTimers, InlineRow, Level, LocalOpTimeoutError, MATERIALIZATION_SAMPLE_WINDOW, MembershipOutcome, MutationCallback, MutationEvent, MutationEventType, ORIGIN_TOKEN_KEY, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryAuthorityCallback, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, ReconnectConfig, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, SESSION_POLL_MS, ServerViewMeta, Sp00kyClient, Sp00kyClientDeps, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, TokenClaims, UpdateOptions, blurhashSidecarPath, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, decode as decodeBlurhash, decodeTokenClaims, encode as encodeBlurhash, encodeImageToBlurhash, fileToUint8Array, impersonationFromToken, isBlurhashValid, isImagePath, renewDelayMs, sameImpersonation, semverGt, textToHtml };