@abraca/dabra 2.0.9 → 2.3.0

package/src/TokenManager.ts

@@ -0,0 +1,329 @@
+import EventEmitter from "./EventEmitter.ts";
+import type { AbracadabraClient } from "./AbracadabraClient.ts";
+
+/**
+ * On-disk shape of a device session. The server returns these values from
+ * `POST /auth/device-session`; persistence keeps them across reloads so a
+ * warm boot can mint a fresh JWT without re-prompting for the passkey.
+ */
+export interface DeviceSessionRecord {
+	sessionId: string;
+	sessionToken: string;
+	/** Unix seconds — matches what the server returns. */
+	expiresAt: number;
+}
+
+export interface DeviceSessionStorage {
+	load(): DeviceSessionRecord | null;
+	save(record: DeviceSessionRecord): void;
+	clear(): void;
+}
+
+const DEFAULT_STORAGE_KEY = "abracadabra:device-session";
+
+/** localStorage-backed storage; safe in SSR/Node (no-ops without localStorage). */
+export class LocalStorageDeviceSessionStorage implements DeviceSessionStorage {
+	constructor(private readonly key: string = DEFAULT_STORAGE_KEY) {}
+
+	load(): DeviceSessionRecord | null {
+		try {
+			const raw = localStorage.getItem(this.key);
+			if (!raw) return null;
+			const parsed = JSON.parse(raw) as DeviceSessionRecord;
+			if (
+				typeof parsed?.sessionId === "string" &&
+				typeof parsed?.sessionToken === "string" &&
+				typeof parsed?.expiresAt === "number"
+			) {
+				return parsed;
+			}
+			return null;
+		} catch {
+			return null;
+		}
+	}
+
+	save(record: DeviceSessionRecord): void {
+		try {
+			localStorage.setItem(this.key, JSON.stringify(record));
+		} catch {
+			/* localStorage unavailable */
+		}
+	}
+
+	clear(): void {
+		try {
+			localStorage.removeItem(this.key);
+		} catch {
+			/* localStorage unavailable */
+		}
+	}
+}
+
+export interface TokenManagerOptions {
+	client: AbracadabraClient;
+	/**
+	 * Where the device session record lives. Defaults to a localStorage
+	 * adapter under "abracadabra:device-session".
+	 */
+	storage?: DeviceSessionStorage;
+	/**
+	 * Refresh the JWT this many milliseconds before its `exp`. Defaults to
+	 * 5 minutes — well clear of clock skew without burning a refresh per
+	 * minute. Refreshes are also dedup'd via in-flight promise.
+	 */
+	refreshLeadMs?: number;
+	/**
+	 * Hook `document.visibilitychange` and `window.online` to opportunistically
+	 * refresh when the tab/network resumes. Default true. The proactive
+	 * `setTimeout` doesn't fire reliably while the tab is hidden or the
+	 * laptop is asleep, which is the actual breakage path being addressed —
+	 * the resume hook is what makes the system self-heal after a long sleep.
+	 */
+	installResumeHandlers?: boolean;
+}
+
+/**
+ * Manages the lifetime of the short-lived JWT against a long-lived device
+ * session token.
+ *
+ * Flow:
+ *  - Bootstrap: if a stored device session exists, exchange it for a fresh
+ *    JWT immediately (`bootstrap()`). Otherwise the consumer must run a
+ *    full crypto-auth handshake and then call `attachSession(record)` once
+ *    the server returns a device-session token.
+ *  - Steady state: `getValidToken()` returns the JWT, refreshing if the
+ *    JWT is within `refreshLeadMs` of expiry. Concurrent callers share one
+ *    in-flight refresh.
+ *  - Background: a proactive timer fires `refreshLeadMs` before `exp`.
+ *    `visibilitychange` and `online` events trigger an opportunistic
+ *    refresh in case the timer was suppressed (hidden tab, sleeping
+ *    laptop). The combination is what restores the WS without a reload.
+ *  - Failure: refresh errors with status 401/403 mean the device session
+ *    itself is dead (revoked or 30 d expired). The record is cleared and
+ *    `session-expired` fires so the consumer can prompt re-auth. Other
+ *    errors (network) are transparent — the existing JWT is returned and
+ *    the caller's normal retry loop covers it.
+ */
+export class TokenManager extends EventEmitter {
+	private readonly client: AbracadabraClient;
+	private readonly storage: DeviceSessionStorage;
+	private readonly refreshLeadMs: number;
+	private session: DeviceSessionRecord | null;
+	private refreshing: Promise<string> | null = null;
+	private proactiveTimer: ReturnType<typeof setTimeout> | null = null;
+	private resumeHandlersInstalled = false;
+	private boundOnResume: (() => void) | null = null;
+	private disposed = false;
+
+	constructor(options: TokenManagerOptions) {
+		super();
+		this.client = options.client;
+		this.storage = options.storage ?? new LocalStorageDeviceSessionStorage();
+		this.refreshLeadMs = options.refreshLeadMs ?? 5 * 60 * 1000;
+		this.session = this.storage.load();
+		if (options.installResumeHandlers !== false) {
+			this.installResumeHandlers();
+		}
+		// Schedule a refresh against the JWT the client may already be
+		// holding (loaded from persistAuth localStorage) so warm boots
+		// without an explicit bootstrap() still benefit from proactive
+		// refresh on the existing token.
+		this.scheduleProactiveRefresh();
+	}
+
+	get hasSession(): boolean {
+		return this.session !== null;
+	}
+
+	get currentSession(): DeviceSessionRecord | null {
+		return this.session;
+	}
+
+	/**
+	 * Persist a freshly-issued device session and exchange it immediately
+	 * for a JWT. Call this once after a successful crypto-auth login when
+	 * the server returns a device-session token.
+	 */
+	async attachSession(record: DeviceSessionRecord): Promise<string> {
+		this.session = record;
+		this.storage.save(record);
+		const jwt = await this.runRefresh();
+		return jwt;
+	}
+
+	/**
+	 * Drop the local device session (no server call). Use after a logout
+	 * or when `session-expired` fires. To revoke server-side as well, call
+	 * `client.revokeDeviceSession(sessionId)` first.
+	 */
+	clearSession(): void {
+		this.session = null;
+		this.storage.clear();
+		if (this.proactiveTimer) {
+			clearTimeout(this.proactiveTimer);
+			this.proactiveTimer = null;
+		}
+	}
+
+	/**
+	 * Return a valid JWT, refreshing if it is missing or within
+	 * `refreshLeadMs` of expiry. Safe to call concurrently — one
+	 * refresh is in flight at a time.
+	 *
+	 * Transient refresh errors (network) fall back to the cached JWT so
+	 * the WS auth attempt can still proceed; the server will reject and
+	 * the next reconnect tries again. Only 401/403 from the refresh
+	 * endpoint surfaces as a thrown error here, since those mean the
+	 * device session itself is dead.
+	 */
+	async getValidToken(): Promise<string> {
+		if (this.refreshing) return this.refreshing;
+		const current = this.client.token;
+		if (current && this.tokenIsFresh(current)) return current;
+		if (!this.session) return current ?? "";
+		try {
+			return await this.runRefresh();
+		} catch (err) {
+			const status = (err as { status?: number })?.status;
+			if (status === 401 || status === 403) throw err;
+			// Transient — let the caller use the stale token; the server
+			// will reject and the WS reconnect loop will retry the refresh.
+			return current ?? "";
+		}
+	}
+
+	/**
+	 * If a stored device session exists, exchange it for a fresh JWT now.
+	 * Returns the JWT (or null if there is no session to bootstrap from).
+	 * Throws on 401/403 — the stored session is invalid and the caller
+	 * should fall through to a full crypto-auth flow.
+	 */
+	async bootstrap(): Promise<string | null> {
+		if (!this.session) return null;
+		try {
+			return await this.runRefresh();
+		} catch (err) {
+			const status = (err as { status?: number })?.status;
+			if (status === 401 || status === 403) throw err;
+			// Transient — caller decides what to do (e.g. fall back to
+			// passkey login or proceed offline).
+			return null;
+		}
+	}
+
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		if (this.proactiveTimer) {
+			clearTimeout(this.proactiveTimer);
+			this.proactiveTimer = null;
+		}
+		if (this.boundOnResume) {
+			try {
+				if (typeof document !== "undefined") {
+					document.removeEventListener("visibilitychange", this.boundOnResume);
+				}
+				if (typeof window !== "undefined") {
+					window.removeEventListener("online", this.boundOnResume);
+				}
+			} catch { /* environment without listener APIs */ }
+			this.boundOnResume = null;
+		}
+		this.removeAllListeners();
+	}
+
+	// ── internals ───────────────────────────────────────────────────────────
+
+	private runRefresh(): Promise<string> {
+		if (this.refreshing) return this.refreshing;
+		if (!this.session) return Promise.reject(new Error("No device session"));
+		const sessionToken = this.session.sessionToken;
+		this.refreshing = (async () => {
+			try {
+				const jwt = await this.client.refreshWithDeviceSession(sessionToken);
+				this.scheduleProactiveRefresh();
+				this.emit("refresh", jwt);
+				return jwt;
+			} catch (err) {
+				const status = (err as { status?: number })?.status;
+				if (status === 401 || status === 403) {
+					const message = (err as Error)?.message ?? "device session rejected";
+					this.clearSession();
+					this.emit("session-expired", { status, message });
+				}
+				throw err;
+			} finally {
+				this.refreshing = null;
+			}
+		})();
+		return this.refreshing;
+	}
+
+	private tokenIsFresh(jwt: string): boolean {
+		const exp = this.parseExp(jwt);
+		if (exp == null) return false;
+		return exp * 1000 - Date.now() > this.refreshLeadMs;
+	}
+
+	private parseExp(jwt: string): number | null {
+		try {
+			const [, payload] = jwt.split(".");
+			if (!payload) return null;
+			const { exp } = JSON.parse(atob(payload));
+			return typeof exp === "number" ? exp : null;
+		} catch {
+			return null;
+		}
+	}
+
+	private scheduleProactiveRefresh(): void {
+		if (this.proactiveTimer) {
+			clearTimeout(this.proactiveTimer);
+			this.proactiveTimer = null;
+		}
+		if (!this.session || this.disposed) return;
+		const jwt = this.client.token;
+		const exp = jwt ? this.parseExp(jwt) : null;
+		if (exp == null) {
+			// No JWT yet — defer; whoever calls getValidToken() / bootstrap()
+			// will reschedule once a JWT lands.
+			return;
+		}
+		// Floor at 30 s so a near-expired token doesn't trigger a busy
+		// refresh-then-immediately-refresh-again loop on clock skew.
+		const delay = Math.max(30_000, exp * 1000 - Date.now() - this.refreshLeadMs);
+		this.proactiveTimer = setTimeout(() => {
+			this.runRefresh().catch(() => {
+				// 401/403 already surfaced via session-expired event;
+				// transient errors are no-ops — the resume handler or the
+				// next getValidToken() call will retry.
+			});
+		}, delay);
+	}
+
+	private installResumeHandlers(): void {
+		if (this.resumeHandlersInstalled) return;
+		if (typeof document === "undefined" && typeof window === "undefined") return;
+		const onResume = () => {
+			if (this.disposed) return;
+			if (typeof document !== "undefined" && document.visibilityState === "hidden") return;
+			if (!this.session) return;
+			const jwt = this.client.token;
+			if (jwt && this.tokenIsFresh(jwt)) return;
+			this.runRefresh().catch(() => {
+				/* same swallow as above */
+			});
+		};
+		this.boundOnResume = onResume;
+		try {
+			if (typeof document !== "undefined") {
+				document.addEventListener("visibilitychange", onResume);
+			}
+			if (typeof window !== "undefined") {
+				window.addEventListener("online", onResume);
+			}
+			this.resumeHandlersInstalled = true;
+		} catch { /* environment without listener APIs */ }
+	}
+}

package/src/TreeManager.ts

@@ -15,6 +15,11 @@ import type {
 import { resolvePageType } from "./DocTypes.ts";
 import { toPlain, normalizeRootId } from "./DocUtils.ts";
 import type { DocumentManager } from "./DocumentManager.ts";
+import {
+	projectTreeEntry,
+	type SchemaRegistryLike,
+	type TypedTreeEntry,
+} from "./SchemaTypes.ts";
 
 export class TreeManager {
 	constructor(private dm: DocumentManager) {}
@@ -120,6 +125,28 @@ export class TreeManager {
 			});
 	}
 
+	/**
+	 * Schema-typed lookup. Returns a `TypedTreeEntry<TMap, N>` when the
+	 * entry's `type` matches `expectedType`, else `null`. Pure projection
+	 * over the existing untyped tree — no schema validation is performed
+	 * here (the entry's data is whatever was last synced; meta correctness
+	 * is the writer's responsibility, optionally enforced via
+	 * `MetaManager.setSchema`).
+	 *
+	 * Rule 4 alignment: when the entry's type doesn't match, returns null
+	 * rather than throwing — callers branch on the result.
+	 */
+	getTyped<
+		TMap extends Record<string, unknown>,
+		N extends keyof TMap & string,
+	>(
+		_schema: SchemaRegistryLike<TMap>,
+		expectedType: N,
+		docId: string,
+	): TypedTreeEntry<TMap, N> | null {
+		return projectTreeEntry<TMap, N>(this.get(docId), expectedType);
+	}
+
 	/** Find a single entry by ID. */
 	get(docId: string): TreeEntry | null {
 		const treeMap = this.dm.getTreeMap();

package/src/index.ts

@@ -3,6 +3,15 @@ export * from "./AbracadabraWS.ts";
 export * from "./types.ts";
 export * from "./AbracadabraProvider.ts";
 export * from "./AbracadabraClient.ts";
+export {
+	TokenManager,
+	LocalStorageDeviceSessionStorage,
+} from "./TokenManager.ts";
+export type {
+	TokenManagerOptions,
+	DeviceSessionRecord,
+	DeviceSessionStorage,
+} from "./TokenManager.ts";
 export * from "./OfflineStore.ts";
 export * from "./auth.ts";
 export * from "./CloseEvents.ts";
@@ -38,6 +47,16 @@ export type {
 export { DeviceRegistrationService } from "./DeviceRegistrationService.ts";
 export { ChatClient } from "./ChatClient.ts";
 export { RpcClient, RpcError, RPC_PREFIX } from "./RpcClient.ts";
+export { QueryClient, QueryError, QUERY_PREFIX } from "./QueryClient.ts";
+export type {
+	QueryKind,
+	QueryFrame,
+	QuerySpec,
+	QuerySubscriptionHandlers,
+	QuerySubscriptionHandle,
+	QueryTransport,
+	DocumentMetaWire,
+} from "./QueryClient.ts";
 export type {
 	RpcKind,
 	RpcFrame,
@@ -111,8 +130,19 @@ export type { DocumentManagerConfig } from "./DocumentManager.ts";
 export { TreeManager } from "./TreeManager.ts";
 export { ContentManager } from "./ContentManager.ts";
 export type { DocumentContent } from "./ContentManager.ts";
-export { MetaManager } from "./MetaManager.ts";
-export type { DocumentMetaInfo } from "./MetaManager.ts";
+export { MetaManager, MetaValidationError } from "./MetaManager.ts";
+export type {
+	DocumentMetaInfo,
+	SchemaValidatorLike,
+} from "./MetaManager.ts";
+export { TypedDocTypeMismatchError } from "./SchemaTypes.ts";
+export type {
+	SchemaRegistryLike,
+	SchemaDocTypeName,
+	SchemaMetaOf,
+	TypedTreeEntry,
+	TypedDocsClient,
+} from "./SchemaTypes.ts";
 export * from "./DocTypes.ts";
 export { waitForSync, withTimeout, normalizeRootId, toPlain } from "./DocUtils.ts";
 export {