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

package/dist/index.js

@@ -760,9 +760,12 @@ function createEventSystem(eventTypes) {
 
 //#endregion
 //#region src/modules/auth/events/index.ts
-const AuthEventTypes = { AuthStateChanged: "AUTH_STATE_CHANGED" };
+const AuthEventTypes = {
+	AuthStateChanged: "AUTH_STATE_CHANGED",
+	ImpersonationChanged: "IMPERSONATION_CHANGED"
+};
 function createAuthEventSystem() {
-	return createEventSystem([AuthEventTypes.AuthStateChanged]);
+	return createEventSystem([AuthEventTypes.AuthStateChanged, AuthEventTypes.ImpersonationChanged]);
 }
 
 //#endregion
@@ -1073,8 +1076,8 @@ function selfAllowlistedVariant(flag, userId) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.260";
-const WASM_VERSION = "0.0.1-canary.260";
+const CORE_VERSION = "0.0.1-canary.261";
+const WASM_VERSION = "0.0.1-canary.261";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -1307,7 +1310,8 @@ var DevToolsService = class DevToolsService {
 			activeQueries: Object.fromEntries(this.getActiveQueries()),
 			auth: {
 				authenticated: this.authService.isAuthenticated,
-				userId: this.authService.currentUser?.id
+				userId: this.authService.currentUser?.id,
+				impersonation: this.authService.impersonation
 			},
 			version: this.version,
 			versions: {
@@ -1332,6 +1336,56 @@ var DevToolsService = class DevToolsService {
 		});
 	}
 	/**
+	* 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).
+	*/
+	async impersonationOp(op, args) {
+		const enabled = this.schema.policy?.impersonation === true;
+		try {
+			switch (op) {
+				case "status": {
+					const current = this.authService.impersonation;
+					const isAdmin = (await this.flagsAdmin.getFlags().catch(() => null))?.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,
 	* so one broken source (a mid-switch worker, a browser without OPFS) never
@@ -1477,6 +1531,7 @@ var DevToolsService = class DevToolsService {
 					});
 				},
 				getFlags: () => this.flagsAdmin.getFlags(),
+				impersonationOp: (op, args) => this.impersonationOp(op, args ?? {}),
 				setFlagEnabled: (key, enabled) => this.flagsAdmin.setFlagEnabled(key, enabled),
 				setFlagUserVariant: (key, variant, remove, userId) => this.flagsAdmin.setFlagUserVariant(key, variant, remove, userId),
 				setLocalFlagOverride: (key, variant, payload) => this.flagsAdmin.setLocalFlagOverride(key, variant, payload),
@@ -5492,6 +5547,7 @@ function* bucketSwitch(env, target, release = null, opts = { clearBlobsOnSignOut
 	} finally {
 		gate();
 	}
+	yield* dropImpersonatedBucket(current);
 	const token = yield fx.service("auth.token");
 	if (token) try {
 		yield fx.service("persistence.set", "sp00ky_auth_token", token);
@@ -5510,6 +5566,28 @@ function* bucketSwitch(env, target, release = null, opts = { clearBlobsOnSignOut
 	yield fx.dispatch({ type: "PollTick" });
 	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.
+*/
+function* dropImpersonatedBucket(left) {
+	const ended = yield fx.service("auth.consumeEndedImpersonation");
+	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. */
 function* rebindQueries() {
 	const [entries, sessionId] = yield fx.state.read((s) => [[...s.queries.values()], s.sessionId]);
@@ -6437,6 +6515,12 @@ var LocalDatabaseService = class extends AbstractDatabaseService {
 			Category: "sp00ky-client::LocalDatabaseService::switchStore"
 		}, "Switched local store bucket");
 	}
+	/** See `LocalStore.dropBucket`. A memory store keeps nothing to delete. */
+	async dropBucket(bucketId) {
+		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
@@ -8079,6 +8163,22 @@ var SqliteCacheEngine = class {
 	getClient() {
 		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) {
+		if (bucketId === this.bucketId) throw new Error("Cannot drop the open bucket.");
+		const storage = typeof navigator !== "undefined" ? navigator.storage : void 0;
+		if (!storage?.getDirectory) return;
+		const root = await storage.getDirectory();
+		try {
+			await root.removeEntry(`.sp00ky-${bucketId}`, { recursive: true });
+		} catch (error) {
+			if (error?.name !== "NotFoundError") throw error;
+		}
+	}
 	/** LocalStore alias; SQLite has no in-flight gate, so this maps to a rebuild. */
 	switchStore(bucketId) {
 		return this.switchBucket(bucketId);
@@ -9688,43 +9788,150 @@ function selectPredicateFromBody(body) {
 }
 
 //#endregion
-//#region src/modules/auth/index.ts
+//#region src/modules/auth/impersonation.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. */
+const IMPERSONATION_ACCESS = "_00_impersonate";
+/** Persistence key holding the admin's own token while impersonating. */
+const ORIGIN_TOKEN_KEY = "sp00ky_auth_token_origin";
+/** How often an active impersonation re-checks its session on the server. */
+const SESSION_POLL_MS = 6e4;
 /**
 * 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) {
+	const none = {
+		access: null,
+		userId: null,
+		exp: null,
+		impersonation: null
+	};
 	try {
 		const payload = token.split(".")[1];
-		if (!payload) return {
-			access: null,
-			userId: null
-		};
+		if (!payload) return none;
 		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);
 		const ac = claims.AC ?? claims.ac;
 		const id = claims.ID ?? claims.id;
+		const access = typeof ac === "string" ? ac : null;
+		const session = claims.spky_imp;
+		const admin = claims.spky_admin;
 		return {
-			access: typeof ac === "string" ? ac : null,
-			userId: typeof id === "string" ? id : null
+			access,
+			userId: typeof id === "string" ? id : null,
+			exp: typeof claims.exp === "number" ? claims.exp : null,
+			impersonation: access === IMPERSONATION_ACCESS && typeof session === "string" && typeof admin === "string" ? {
+				session,
+				admin
+			} : null
 		};
 	} catch {
-		return {
-			access: null,
-			userId: null
-		};
+		return none;
 	}
 }
+/** The impersonation a token represents, or null for a regular session. */
+function impersonationFromToken(token) {
+	if (!token) return null;
+	const claims = decodeTokenClaims(token);
+	if (!claims.impersonation || !claims.userId) return null;
+	return {
+		session: claims.impersonation.session,
+		admin: claims.impersonation.admin,
+		target: claims.userId,
+		tokenExpiresAt: claims.exp === null ? null : /* @__PURE__ */ new Date(claims.exp * 1e3)
+	};
+}
+/** Same impersonation, for change detection (renewals only move the expiry). */
+function sameImpersonation(a, b) {
+	if (a === null || b === null) return a === b;
+	return a.session === b.session && a.target === b.target && a.admin === b.admin;
+}
+/**
+* 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.
+*/
+function renewDelayMs(expSecs, nowMs) {
+	const remaining = expSecs * 1e3 - nowMs;
+	if (remaining <= 5e3) return 0;
+	return Math.max(5e3, Math.floor(remaining * .8));
+}
+/**
+* The two timers an active impersonation needs. `sync()` is called whenever
+* the auth state changes and arms or clears them to match.
+*/
+var ImpersonationTimers = class {
+	renewTimer = null;
+	pollTimer = null;
+	armedFor = null;
+	constructor(host) {
+		this.host = host;
+	}
+	sync() {
+		const info = this.host.current();
+		if (!info) {
+			this.clear();
+			return;
+		}
+		const key = `${info.session}@${info.tokenExpiresAt?.getTime() ?? "none"}`;
+		if (key === this.armedFor) return;
+		this.clear();
+		this.armedFor = key;
+		if (info.tokenExpiresAt) {
+			const delay = renewDelayMs(info.tokenExpiresAt.getTime() / 1e3, Date.now());
+			this.renewTimer = setTimeout(() => void this.renew(), delay);
+		}
+		this.pollTimer = setInterval(() => void this.poll(), SESSION_POLL_MS);
+	}
+	clear() {
+		if (this.renewTimer) clearTimeout(this.renewTimer);
+		if (this.pollTimer) clearInterval(this.pollTimer);
+		this.renewTimer = null;
+		this.pollTimer = null;
+		this.armedFor = null;
+	}
+	async renew() {
+		this.renewTimer = null;
+		try {
+			await this.host.renew();
+		} catch (error) {
+			if (this.host.isNetworkError(error)) {
+				this.renewTimer = setTimeout(() => void this.renew(), 1e4);
+				return;
+			}
+			await this.host.endedRemotely("renew refused");
+		}
+	}
+	async poll() {
+		try {
+			if (!await this.host.stillActive()) await this.host.endedRemotely("session ended");
+		} catch (error) {
+			if (!this.host.isNetworkError(error)) await this.host.endedRemotely("session check refused");
+		}
+	}
+};
+
+//#endregion
+//#region src/modules/auth/index.ts
 function decodeAccessFromToken(token) {
 	return decodeTokenClaims(token).access;
 }
@@ -9741,6 +9948,27 @@ var AuthService = class {
 	access = null;
 	isLoading = true;
 	events = createAuthEventSystem();
+	/** The impersonation last announced, for change detection. */
+	announcedImpersonation = null;
+	/** Target of an impersonation that just ended, until the client purges its
+	*  local bucket (see `consumeEndedImpersonation`). */
+	endedImpersonationTarget = null;
+	impersonationTimers = new ImpersonationTimers({
+		current: () => this.impersonation,
+		renew: () => this.renewImpersonation(),
+		stillActive: async () => {
+			const [row] = await this.remote.query("RETURN fn::_00_impersonate::current()");
+			return row !== null && row !== void 0;
+		},
+		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"
+	});
 	get eventSystem() {
 		return this.events;
 	}
@@ -9772,6 +10000,141 @@ var AuthService = class {
 	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() {
+		return this.isAuthenticated ? impersonationFromToken(this.token) : null;
+	}
+	/** Subscribe to impersonation changes; called immediately with the current value. */
+	subscribeImpersonation(cb) {
+		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, reason) {
+		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("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) {
+			await this.persistenceClient.remove(ORIGIN_TOKEN_KEY);
+			this.remote.setAuthToken(originToken);
+			await this.remote.getClient().authenticate(originToken).catch(() => void 0);
+			throw error;
+		}
+		await this.check(started.token);
+		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 = {}) {
+		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) {
+			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(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;
+		}
+		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() {
+		if (!this.impersonation) return;
+		const [renewed] = await this.remote.query("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) {
+		const [rows] = await this.remote.query("RETURN fn::_00_impersonate::list_users($search)", { search });
+		return Array.isArray(rows) ? rows : [];
+	}
+	/** Open impersonation sessions. Admin-only on the server. */
+	async listActiveImpersonations() {
+		const [rows] = await this.remote.query("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() {
+		const target = this.endedImpersonationTarget;
+		this.endedImpersonationTarget = null;
+		return target;
 	}
 	/**
 	* Restore a session from the locally cached JWT, with NO network.
@@ -9812,8 +10175,9 @@ var AuthService = class {
 	*/
 	async check(accessToken) {
 		this.isLoading = true;
+		let token;
 		try {
-			const token = accessToken || await this.persistenceClient.get("sp00ky_auth_token");
+			token = accessToken || await this.persistenceClient.get("sp00ky_auth_token") || void 0;
 			if (!token) {
 				this.logger.debug({ Category: "sp00ky-client::AuthService::check" }, "No token found in storage or arguments");
 				this.isLoading = false;
@@ -9845,7 +10209,7 @@ var AuthService = class {
 					await this.setSession(token, manualUser);
 				} else {
 					this.logger.warn({ Category: "sp00ky-client::AuthService::check" }, "Token valid but user not found via fallback");
-					await this.signOut();
+					await this.rejectToken(token);
 				}
 			}
 		} catch (error) {
@@ -9859,16 +10223,42 @@ var AuthService = class {
 					stack: error.stack,
 					Category: "sp00ky-client::AuthService::check"
 				}, "Auth check failed");
-				await this.signOut();
+				await this.rejectToken(token);
 			}
 		} finally {
 			this.isLoading = false;
 		}
 	}
 	/**
-	* 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.
+	*/
+	async rejectToken(token) {
+		if (token && impersonationFromToken(token)) {
+			if (!this.impersonation || this.token !== token) {
+				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) {}
+		}
+		await this.persistenceClient.remove(ORIGIN_TOKEN_KEY);
 		this.token = null;
 		this.remote.setAuthToken(null);
 		this.currentUser = null;
@@ -12635,7 +13025,7 @@ function createTabsCoordinator(config, s, host) {
 	return new TabsCoordinator({
 		tabId: s.tabId,
 		fingerprint: computeTabsFingerprint({
-			coreVersion: "0.0.1-canary.260",
+			coreVersion: "0.0.1-canary.261",
 			schemaHash: hash53(config.schemaSurql),
 			endpoint: config.database.endpoint ?? "",
 			namespace: config.database.namespace,
@@ -12774,6 +13164,9 @@ function createAdapters(config, s, host, lateModules) {
 		"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));
@@ -12809,6 +13202,7 @@ function createAdapters(config, s, host, lateModules) {
 		"auth.access": () => s.auth.access,
 		"auth.token": () => s.auth.token,
 		"auth.currentUser": () => s.auth.currentUser ?? null,
+		"auth.consumeEndedImpersonation": () => s.auth.consumeEndedImpersonation(),
 		"remote.connect": () => s.remote.connect(),
 		"remote.releaseViews": (ids) => {
 			const list = ids.map((id) => String(id)).filter((id) => /^_00_query:[0-9a-f]{64}$/.test(id)).join(", ");
@@ -12900,6 +13294,102 @@ function createAdapters(config, s, host, lateModules) {
 	};
 }
 
+//#endregion
+//#region src/modules/auth/impersonation-banner.ts
+/** 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. */
+const BANNER_HEIGHT_PX = 36;
+const HOST_TAG = "sp00ky-impersonation-banner";
+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`.
+*/
+var ImpersonationBanner = class ImpersonationBanner {
+	host = null;
+	text = null;
+	constructor(onStop) {
+		this.onStop = onStop;
+	}
+	static supported() {
+		return typeof document !== "undefined" && typeof document.createElement === "function";
+	}
+	update(info) {
+		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() {
+		this.host?.remove();
+		this.host = this.text = null;
+		if (typeof document !== "undefined") document.documentElement?.style.setProperty("--sp00ky-impersonation-banner-height", "0px");
+	}
+	mount() {
+		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) {
+	const b = document.createElement("b");
+	b.textContent = value;
+	return b;
+}
+
 //#endregion
 //#region src/client/sp00ky-client.ts
 const UNKNOWN_STORAGE_HEALTH = Object.freeze({
@@ -12919,6 +13409,8 @@ var Sp00kyClient = class {
 	runtime;
 	featureFlags;
 	appReleases;
+	/** Teardown for subscriptions the client itself owns. */
+	disposers = [];
 	devTools;
 	hub = null;
 	forwarder = null;
@@ -13029,6 +13521,8 @@ var Sp00kyClient = class {
 			type: "AuthFlip",
 			userId
 		}));
+		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;
@@ -13078,6 +13572,7 @@ var Sp00kyClient = class {
 	async close() {
 		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();
@@ -13313,4 +13808,4 @@ var Sp00kyClient = class {
 };
 
 //#endregion
-export { AppReleaseHandle, AppReleaseModule, AuthEventTypes, AuthService, BLURHASH_IMAGE_EXTENSIONS, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DEFAULT_LOCAL_OP_TIMEOUT_MS, FeatureFlagHandle, FeatureFlagModule, LocalOpTimeoutError, MATERIALIZATION_SAMPLE_WINDOW, Sp00kyClient, blurhashSidecarPath, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, decode as decodeBlurhash, encode as encodeBlurhash, encodeImageToBlurhash, fileToUint8Array, isBlurhashValid, isImagePath, semverGt, textToHtml };
+export { AppReleaseHandle, AppReleaseModule, AuthEventTypes, AuthService, BLURHASH_IMAGE_EXTENSIONS, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, DEFAULT_LOCAL_OP_TIMEOUT_MS, FeatureFlagHandle, FeatureFlagModule, IMPERSONATION_ACCESS, ImpersonationTimers, LocalOpTimeoutError, MATERIALIZATION_SAMPLE_WINDOW, ORIGIN_TOKEN_KEY, SESSION_POLL_MS, Sp00kyClient, blurhashSidecarPath, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, decode as decodeBlurhash, decodeTokenClaims, encode as encodeBlurhash, encodeImageToBlurhash, fileToUint8Array, impersonationFromToken, isBlurhashValid, isImagePath, renewDelayMs, sameImpersonation, semverGt, textToHtml };