@abraca/dabra 1.9.1 → 2.0.0

package/src/AbracadabraClient.ts

@@ -7,22 +7,51 @@ import type {
 	PermissionEntry,
 	EffectivePermissionsResponse,
 	HealthStatus,
+	ReadyzStatus,
 	ServerInfo,
 	InviteRow,
-	SpaceMeta,
 	SnapshotMeta,
 	SnapshotData,
 	SnapshotCreateResult,
 	SnapshotRestoreResult,
 	SnapshotForkResult,
+	DocSearchHit,
+	AuditLogEntry,
+	AuditQueryOpts,
+	AuditVerifyResult,
 } from "./types.ts";
+import { Kind, SERVER_ROOT_ID } from "./types.ts";
 import type { DocEncryptionInfo } from "./types.ts";
 import type { DocumentCache } from "./DocumentCache.ts";
+import { deriveDmDocId } from "./IdentityDoc.ts";
 
 function fromBase64(b64: string): Uint8Array {
 	return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
 }
 
+/**
+ * Reason classifications surfaced to `onAuthFailed`. Consumers can decide
+ * whether to silently re-register the keypair (`user_not_found`) or
+ * surface a hard block (`account_revoked`, `forbidden`).
+ */
+export type AuthFailureReason =
+	| "user_not_found"
+	| "account_revoked"
+	| "forbidden"
+	| "unauthorized";
+
+export interface AuthFailureContext {
+	/** HTTP status code from the failed request. */
+	status: number;
+	/** Server-provided error message verbatim. */
+	message: string;
+	/** Best-guess classification from the message text. */
+	reason: AuthFailureReason;
+	/** Method + path of the failed request, useful for debugging. */
+	method: string;
+	path: string;
+}
+
 export interface AbracadabraClientConfig {
 	/** Server base URL (http or https). WebSocket URL is derived automatically. */
 	url: string;
@@ -41,6 +70,19 @@ export interface AbracadabraClientConfig {
 	 * cache entries automatically.
 	 */
 	cache?: DocumentCache;
+	/**
+	 * Called whenever a REST call returns 401/403 with a recoverable reason
+	 * (typically "user not found" — server's DB was wiped or repointed).
+	 * Consumers wire this to their reauth path (in cou-sh: `_reauthFn`)
+	 * so silently-failing background fetches still trigger key re-registration
+	 * without waiting for the next WS action to surface the problem.
+	 *
+	 * The callback runs OUT-OF-BAND of the failing request — the original
+	 * Promise still rejects so callers handle their own error path.
+	 * Long-running auth handlers should debounce or short-circuit duplicate
+	 * concurrent invocations.
+	 */
+	onAuthFailed?: (ctx: AuthFailureContext) => void;
 }
 
 export class AbracadabraClient {
@@ -50,6 +92,7 @@ export class AbracadabraClient {
 	private readonly storageKey: string;
 	private readonly _fetch: typeof globalThis.fetch;
 	readonly cache: DocumentCache | null;
+	private readonly _onAuthFailed: ((ctx: AuthFailureContext) => void) | null;
 
 	constructor(config: AbracadabraClientConfig) {
 		this.baseUrl = config.url.replace(/\/+$/, "");
@@ -57,6 +100,7 @@ export class AbracadabraClient {
 		this.storageKey = config.storageKey ?? "abracadabra:auth";
 		this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
 		this.cache = config.cache ?? null;
+		this._onAuthFailed = config.onAuthFailed ?? null;
 
 		// Load token: explicit > persisted > null
 		this._token = config.token ?? this.loadPersistedToken() ?? null;
@@ -344,11 +388,133 @@ export class AbracadabraClient {
 		}));
 	}
 
-	/** Clear token from memory and storage. */
+	/**
+	 * Clear token from memory and storage. Local-only; does NOT notify the
+	 * server. Use {@link logoutServer} or {@link logoutAll} when you also
+	 * want the JWT to land in the server's revocation cache.
+	 */
 	logout(): void {
 		this.token = null;
 	}
 
+	/**
+	 * Revoke the current JWT server-side and clear local state. Adds the
+	 * token's `jti` to the server's revocation cache so subsequent requests
+	 * with this token return 401, even if the JWT signature still verifies
+	 * and `exp` hasn't passed. Safe to call when no token is set — degrades
+	 * to a local clear.
+	 *
+	 * Network errors are swallowed (the local state is always cleared) so
+	 * a sign-out flow can't get stuck on a flaky connection. The endpoint
+	 * itself is idempotent.
+	 */
+	async logoutServer(): Promise<void> {
+		if (this._token) {
+			try {
+				await this.request("POST", "/auth/logout");
+			} catch {
+				// best-effort — local clear must always happen
+			}
+		}
+		this.token = null;
+	}
+
+	/**
+	 * Bump the user's `tokens_invalid_before` watermark, revoking every
+	 * outstanding JWT for this user — every device, every browser, every
+	 * pending background tab. The current token is required (this is the
+	 * user's "I am who I say I am" assertion). After the call returns,
+	 * future authenticated requests with any pre-existing token return 401.
+	 */
+	async logoutAll(): Promise<void> {
+		await this.request("POST", "/auth/logout-all");
+		this.token = null;
+	}
+
+	// ── Email verification ──────────────────────────────────────────────────
+
+	/**
+	 * Request an email verification message be sent to the current user's
+	 * registered email address. Requires authentication. Server enforces a
+	 * per-user rate limit (1/min, 10/day). Returns 404 if email
+	 * verification is disabled in `[auth.email_verification]`.
+	 */
+	async requestEmailVerification(): Promise<void> {
+		await this.request("POST", "/auth/verify-email/request", { body: {} });
+	}
+
+	/**
+	 * Confirm an email verification token (typically opened from a link in
+	 * the verification email). On success the server sets
+	 * `users.email_verified_at`. No auth required — the token itself is
+	 * the proof.
+	 */
+	async confirmEmailVerification(token: string): Promise<void> {
+		await this.request("POST", "/auth/verify-email/confirm", {
+			body: { token },
+			auth: false,
+		});
+	}
+
+	// ── Password lifecycle ──────────────────────────────────────────────────
+
+	/**
+	 * Initiate a password reset for a user identified by username or
+	 * email. The server always returns 202 to avoid leaking whether the
+	 * identifier exists; a real reset email is only sent if the lookup
+	 * matched. Heavily rate-limited per-identifier and per-IP.
+	 */
+	async requestPasswordReset(opts: { identifier: string }): Promise<void> {
+		await this.request("POST", "/auth/password-reset/request", {
+			body: opts,
+			auth: false,
+		});
+	}
+
+	/**
+	 * Complete a password reset using the token from the reset email.
+	 * On success the user's password is updated and every existing JWT for
+	 * the account is invalidated (the `tokens_invalid_before` watermark
+	 * bumps). The caller is NOT auto-logged-in — call {@link login} after.
+	 */
+	async confirmPasswordReset(opts: { token: string; newPassword: string }): Promise<void> {
+		await this.request("POST", "/auth/password-reset/confirm", {
+			body: { token: opts.token, newPassword: opts.newPassword },
+			auth: false,
+		});
+	}
+
+	/**
+	 * Change the current user's password. Requires the current password —
+	 * a stolen JWT alone can't pivot to "I now own this account forever"
+	 * because the lockout counter (shared with `/auth/login`) trips after
+	 * a few wrong tries. The endpoint also bumps `tokens_invalid_before`,
+	 * so other sessions are forced to re-auth.
+	 */
+	async changePassword(opts: { currentPassword: string; newPassword: string }): Promise<void> {
+		await this.request("POST", "/auth/password-change", {
+			body: { currentPassword: opts.currentPassword, newPassword: opts.newPassword },
+		});
+	}
+
+	/**
+	 * Add a password to an account that doesn't have one yet — for example,
+	 * a key-based soft identity opting into a recovery credential. Requires
+	 * the caller to be authenticated. The server checks
+	 * `users.password_hash IS NULL` and returns 409 if a password is already
+	 * set — use {@link changePassword} in that case.
+	 *
+	 * Setting a password does not bump `tokens_invalid_before`: it adds an
+	 * orthogonal credential rather than rotating an existing one. Other
+	 * devices keep their sessions; this just unlocks the password-login
+	 * code path for future logins on new devices.
+	 */
+	async setPassword(newPassword: string): Promise<void> {
+		await this.request("POST", "/auth/set-password", {
+			body: { newPassword },
+		});
+	}
+
 	// ── User ─────────────────────────────────────────────────────────────────
 
 	/** Get the current user's profile. */
@@ -397,24 +563,81 @@ export class AbracadabraClient {
 		}
 	}
 
-	/** List immediate child documents. */
-	async listChildren(docId: string): Promise<string[]> {
+	/**
+	 * Restore a soft-deleted document (and its descendants). Requires the
+	 * same `manage` permission as {@link deleteDoc}, and works even when
+	 * the doc currently has `deleted_at` set — the cascade resolver walks
+	 * the ancestor chain regardless of soft-delete state. Returns the
+	 * number of restored rows in the audit log; the SDK call returns
+	 * `void` because the wire response is 204.
+	 */
+	async restoreDoc(docId: string): Promise<void> {
+		await this.request("POST", `/docs/${encodeURIComponent(docId)}/restore`);
 		if (this.cache) {
-			const cached = await this.cache.getChildren(docId);
-			if (cached) return cached;
+			await this.cache.invalidateDoc(docId).catch(() => null);
 		}
-		const res = await this.request<{ children: string[] }>(
+	}
+
+	/**
+	 * Full-text search over document labels via `GET /docs/search`. The
+	 * server filters each candidate hit through the cascade resolver, so
+	 * results only include docs the caller can read at viewer or above.
+	 * Anonymous callers are permitted but only see public docs.
+	 *
+	 * `limit` is clamped to `[1, 50]` server-side; the default is 20.
+	 * Hits arrive in best-first order. `snippet` is HTML with `<mark>`
+	 * markers around matched tokens — sanitize before injecting.
+	 */
+	async searchDocs(query: string, opts?: { limit?: number }): Promise<DocSearchHit[]> {
+		const params = new URLSearchParams({ q: query });
+		if (opts?.limit != null) params.set("limit", String(opts.limit));
+		const res = await this.request<{ results: DocSearchHit[] }>(
 			"GET",
-			`/docs/${encodeURIComponent(docId)}/children`,
+			`/docs/search?${params.toString()}`,
 		);
-		if (this.cache) {
-			await this.cache.setChildren(docId, res.children).catch(() => null);
+		return res.results;
+	}
+
+	/**
+	 * List the direct children of a document, returning full metadata. Pass
+	 * no argument to list the children of the server root — what the
+	 * dashboard renders as the Spaces sidebar.
+	 *
+	 * The cache (when configured) stores the bare `id[]` topology used by
+	 * recursive tree walks; callers that need it can read `meta.id` from
+	 * the returned metas.
+	 */
+	async listChildren(parentId?: string): Promise<DocumentMeta[]> {
+		const path = parentId
+			? `/docs/${encodeURIComponent(parentId)}/children`
+			: "/docs?root=true";
+		const res = await this.request<{ documents: DocumentMeta[]; children?: string[] }>(
+			"GET",
+			path,
+		);
+		if (this.cache && parentId && res.children) {
+			await this.cache.setChildren(parentId, res.children).catch(() => null);
 		}
-		return res.children;
+		return res.documents;
 	}
 
-	/** Create a child document under a parent (requires write permission). */
-	async createChild(docId: string, opts?: { child_id?: string; doc_type?: string; label?: string }): Promise<DocumentMeta> {
+	/**
+	 * Create a child document under a parent (requires write permission).
+	 *
+	 * `kind` is the well-known tag (`Kind.Channel`, `Kind.Page`, etc.); the
+	 * server stores it in `documents.kind` but does not enforce semantics.
+	 * `description` is freeform metadata.
+	 */
+	async createChild(
+		docId: string,
+		opts?: {
+			child_id?: string;
+			doc_type?: string;
+			label?: string;
+			kind?: string;
+			description?: string;
+		},
+	): Promise<DocumentMeta> {
 		return this.request<DocumentMeta>(
 			"POST",
 			`/docs/${encodeURIComponent(docId)}/children`,
@@ -587,17 +810,6 @@ export class AbracadabraClient {
 
 	// ── Document Access & Discovery ──────────────────────────────────────────
 
-	/** List root documents (replaces listSpaces for new code). */
-	async listRootDocuments(): Promise<DocumentMeta[]> {
-		const res = await this.request<{ documents: DocumentMeta[] }>("GET", "/docs?root=true");
-		return res.documents;
-	}
-
-	/** Get the hub document, or null if none is configured. */
-	async getHubDocument(): Promise<DocumentMeta | null> {
-		return this.requestOrNull<DocumentMeta>("GET", "/docs/hub");
-	}
-
 	/** Set the public_access level for a document. Pass null to inherit from parent. */
 	async setDocumentAccess(docId: string, publicAccess: string | null): Promise<void> {
 		await this.request("PATCH", `/docs/${encodeURIComponent(docId)}/access`, {
@@ -610,71 +822,153 @@ export class AbracadabraClient {
 		return this.request("GET", `/docs/${encodeURIComponent(docId)}/access`);
 	}
 
-	/** Update document metadata (label, description, is_hub). Requires manage permission. */
+	/** Update document metadata (label, description, kind). Requires manage permission. */
 	async updateDocumentMeta(
 		docId: string,
-		opts: { label?: string; description?: string | null; is_hub?: boolean },
+		opts: { label?: string | null; description?: string | null; kind?: string | null },
 	): Promise<void> {
 		await this.request("PATCH", `/docs/${encodeURIComponent(docId)}`, { body: opts });
 	}
 
-	// ── Spaces (deprecated — use document-based methods) ─────────────────────
+	// ── Spaces ───────────────────────────────────────────────────────────────
+	//
+	// "Spaces" are direct children of the server root with `kind: "space"`.
+	// They live in the regular `documents` table — there's no dedicated
+	// spaces resource on the server anymore. These helpers keep the familiar
+	// names so callers don't have to think about the underlying tree.
 
 	/**
-	 * List spaces visible to the caller. No auth required for public spaces.
-	 * @deprecated Use {@link listRootDocuments} instead.
+	 * List Spaces visible to the caller — top-level docs (children of the
+	 * server root) tagged with `kind: "space"`. Authenticated users see
+	 * spaces resolving to any role; anonymous users see public ones.
 	 */
-	async listSpaces(): Promise<SpaceMeta[]> {
-		const res = await this.request<{ spaces: SpaceMeta[] }>("GET", "/spaces", { auth: false });
-		return res.spaces;
+	async listSpaces(): Promise<DocumentMeta[]> {
+		const docs = await this.listChildren();
+		return docs.filter((d) => d.kind === Kind.Space);
 	}
 
 	/**
-	 * Get a single space by ID.
-	 * @deprecated Use {@link getDoc} instead.
+	 * Create a new top-level Space. Equivalent to a `POST /docs` with
+	 * `kind: "space"` plus the supplied metadata in one round trip.
+	 *
+	 * `visibility: "public"` sets `public_access = "observer"` (anonymous
+	 * read, no awareness or writes). `"private"` (the default) leaves
+	 * `public_access` unset so only explicit grants apply.
 	 */
-	async getSpace(spaceId: string): Promise<SpaceMeta> {
-		return this.request<SpaceMeta>("GET", `/spaces/${encodeURIComponent(spaceId)}`, { auth: false });
+	async createSpace(opts: {
+		name: string;
+		description?: string;
+		visibility?: "public" | "private";
+		id?: string;
+	}): Promise<DocumentMeta> {
+		const public_access = opts.visibility === "public" ? "observer" : "none";
+		return this.request<DocumentMeta>("POST", "/docs", {
+			body: {
+				id: opts.id,
+				label: opts.name,
+				description: opts.description,
+				kind: Kind.Space,
+				public_access,
+			},
+		});
 	}
 
 	/**
-	 * Get the hub space, or null if none is configured.
-	 * @deprecated Use {@link getHubDocument} instead.
+	 * Update a Space's metadata. `visibility` flips `public_access` between
+	 * `"observer"` (public) and `"none"` (private). To leave visibility
+	 * untouched, omit it. Pass any property as `null` to clear it.
 	 */
-	async getHubSpace(): Promise<SpaceMeta | null> {
-		return this.requestOrNull<SpaceMeta>("GET", "/spaces/hub", { auth: false });
+	async updateSpace(
+		docId: string,
+		opts: { name?: string | null; description?: string | null; visibility?: "public" | "private" },
+	): Promise<void> {
+		const meta: { label?: string | null; description?: string | null } = {};
+		if (opts.name !== undefined) meta.label = opts.name;
+		if (opts.description !== undefined) meta.description = opts.description;
+		if (Object.keys(meta).length > 0) {
+			await this.updateDocumentMeta(docId, meta);
+		}
+		if (opts.visibility !== undefined) {
+			await this.setDocumentAccess(docId, opts.visibility === "public" ? "observer" : "none");
+		}
 	}
 
-	/**
-	 * Create a new space (auth required).
-	 * @deprecated Use {@link createDoc} + {@link updateDocumentMeta} instead.
-	 */
-	async createSpace(opts: {
-		name: string;
-		description?: string;
-		visibility?: SpaceMeta["visibility"];
-		id?: string;
-	}): Promise<SpaceMeta> {
-		return this.request<SpaceMeta>("POST", "/spaces", { body: opts });
+	/** Delete a Space (and every doc nested under it). Requires manage permission. */
+	async deleteSpace(docId: string): Promise<void> {
+		await this.deleteDoc(docId);
 	}
 
 	/**
-	 * Update an existing space (Owner or admin required).
-	 * @deprecated Use {@link updateDocumentMeta} + {@link setDocumentAccess} instead.
+	 * Look up the DM doc between the calling user and `otherUserPk`, or
+	 * create it if none exists. The doc id is deterministically derived from
+	 * the sorted pubkey pair (see {@link deriveDmDocId}) so both sides
+	 * compute the same target — race-tolerant by construction. The created
+	 * doc has `kind = "dm"`, `public_access = "none"`, and explicit Editor
+	 * permissions for both participants.
+	 *
+	 * The cascade resolver enforces that no other user can read the DM,
+	 * because:
+	 *   - `public_access = "none"` blocks anonymous + falls through to the
+	 *     server-wide `[access].authenticated` floor for everyone else;
+	 *   - the explicit Editor rows only exist for the two participants, so
+	 *     non-participants get only the (capped) authenticated floor;
+	 *   - the doc lives at server root, so there's no ancestor that could
+	 *     leak via a higher cascade grant.
+	 *
+	 * Note: when `[access].authenticated >= "viewer"` is set server-wide,
+	 * non-participants would still be able to *read* the DM via the
+	 * authenticated floor. That's the documented "private docs need
+	 * authenticated=none" caveat from REDESIGN.md §9 — operators wanting
+	 * sealed DMs configure the server accordingly.
+	 *
+	 * @param otherUserPk Base64url-encoded Ed25519 public key of the other party.
+	 * @returns The DM doc's id (existing or newly created).
 	 */
-	async updateSpace(
-		spaceId: string,
-		opts: Partial<Pick<SpaceMeta, "name" | "description" | "visibility" | "is_hub">>,
-	): Promise<SpaceMeta> {
-		return this.request<SpaceMeta>("PATCH", `/spaces/${encodeURIComponent(spaceId)}`, { body: opts });
+	async findOrCreateDmDoc(otherUserPk: string): Promise<string> {
+		const me = await this.getMe();
+		if (!me.publicKey) {
+			throw new Error("findOrCreateDmDoc: caller has no public key");
+		}
+		const dmId = deriveDmDocId(me.publicKey, otherUserPk);
+		// Try to fetch the doc first — if it exists, we're done.
+		try {
+			const existing = await this.getDoc(dmId);
+			if (existing && existing.kind === Kind.Dm) {
+				return dmId;
+			}
+		} catch {
+			// 404 is the expected miss; any other error we let bubble up
+			// from createDoc below.
+		}
+		// Race-tolerant create: both clients hashing the same pubkey pair
+		// generate the same id, so whoever loses the create gets Conflict
+		// and the catch reuses the id.
+		try {
+			await this.request<DocumentMeta>("POST", "/docs", {
+				body: {
+					id: dmId,
+					kind: Kind.Dm,
+					public_access: "none",
+				},
+			});
+		} catch (err: any) {
+			// Conflict means the other side already created it; reuse.
+			const status = err?.status ?? err?.response?.status;
+			if (status !== 409) throw err;
+		}
+		// Idempotent permission grants (server upserts on (doc_id, user_id)).
+		await this.setPermission(dmId, { user_id: me.publicKey, role: "editor" });
+		await this.setPermission(dmId, { user_id: otherUserPk, role: "editor" });
+		return dmId;
 	}
 
 	/**
-	 * Delete a space and its root document (Owner or admin required).
-	 * @deprecated Use {@link deleteDoc} instead.
+	 * The reserved server root document id. Convenience accessor for the
+	 * client; identical to {@link SERVER_ROOT_ID}. Use this as the parent for
+	 * top-level docs / Spaces.
 	 */
-	async deleteSpace(spaceId: string): Promise<void> {
-		await this.request("DELETE", `/spaces/${encodeURIComponent(spaceId)}`);
+	get rootDocId(): string {
+		return SERVER_ROOT_ID;
 	}
 
 	// ── Admin ───────────────────────────────────────────────────────────────
@@ -704,6 +998,111 @@ export class AbracadabraClient {
 		return this.request("POST", "/admin/storage/repair");
 	}
 
+	/**
+	 * Clear the lockout state on a user account: zeroes the failed-login
+	 * counter and `locked_until`. Requires elevated role (Admin or
+	 * Service). The action is recorded in the audit log under
+	 * `admin.user_unlock`.
+	 */
+	async adminUnlockUser(userId: string): Promise<void> {
+		await this.request("POST", `/admin/users/${encodeURIComponent(userId)}/unlock`);
+	}
+
+	/**
+	 * Page through the audit log. Filters AND-combine; `limit` defaults to
+	 * 100 server-side. Requires elevated role.
+	 */
+	async adminAuditList(opts?: AuditQueryOpts): Promise<AuditLogEntry[]> {
+		const params = new URLSearchParams();
+		if (opts?.event_type) params.set("event_type", opts.event_type);
+		if (opts?.actor_user_id) params.set("actor_user_id", opts.actor_user_id);
+		if (opts?.target_type) params.set("target_type", opts.target_type);
+		if (opts?.target_id) params.set("target_id", opts.target_id);
+		if (opts?.since_ts != null) params.set("since_ts", String(opts.since_ts));
+		if (opts?.until_ts != null) params.set("until_ts", String(opts.until_ts));
+		if (opts?.limit != null) params.set("limit", String(opts.limit));
+		if (opts?.offset != null) params.set("offset", String(opts.offset));
+		const qs = params.toString();
+		const res = await this.request<{ items: AuditLogEntry[] }>(
+			"GET",
+			`/admin/audit${qs ? `?${qs}` : ""}`,
+		);
+		return res.items;
+	}
+
+	/**
+	 * Stream the audit log as NDJSON (one JSON object per line) for SIEM
+	 * ingestion. Filters mirror {@link adminAuditList} minus `limit`/`offset`.
+	 * The server pages internally so memory usage is bounded; this method
+	 * buffers the full response into a string and is therefore best for
+	 * moderate exports — large dumps should consume `/admin/audit/export`
+	 * directly with a streaming HTTP client.
+	 */
+	async adminAuditExport(opts?: Omit<AuditQueryOpts, "limit" | "offset">): Promise<string> {
+		const params = new URLSearchParams();
+		if (opts?.event_type) params.set("event_type", opts.event_type);
+		if (opts?.actor_user_id) params.set("actor_user_id", opts.actor_user_id);
+		if (opts?.target_type) params.set("target_type", opts.target_type);
+		if (opts?.target_id) params.set("target_id", opts.target_id);
+		if (opts?.since_ts != null) params.set("since_ts", String(opts.since_ts));
+		if (opts?.until_ts != null) params.set("until_ts", String(opts.until_ts));
+		const qs = params.toString();
+		const headers: Record<string, string> = {};
+		if (this._token) headers["Authorization"] = `Bearer ${this._token}`;
+		const res = await this._fetch(
+			`${this.baseUrl}/admin/audit/export${qs ? `?${qs}` : ""}`,
+			{ method: "GET", headers },
+		);
+		if (!res.ok) throw await this.toError(res, "GET", "/admin/audit/export");
+		return res.text();
+	}
+
+	/**
+	 * Verify the integrity of the audit-log hash chain. Returns the result
+	 * unchanged: `status: "ok"` when the chain is intact, `status: "broken"`
+	 * with a `break` payload identifying the first divergent row when
+	 * tampering is detected. Wraps `GET /admin/audit/verify`. Requires
+	 * elevated role.
+	 *
+	 * Note: the server returns HTTP 409 on a broken chain — this method
+	 * special-cases the 409 status and returns the body as a successful
+	 * result rather than throwing, because "broken" is a valid answer
+	 * from the verifier, not an error.
+	 */
+	async adminAuditVerify(): Promise<AuditVerifyResult> {
+		const headers: Record<string, string> = {};
+		if (this._token) headers["Authorization"] = `Bearer ${this._token}`;
+		const res = await this._fetch(`${this.baseUrl}/admin/audit/verify`, {
+			method: "GET",
+			headers,
+		});
+		if (res.status === 200 || res.status === 409) {
+			return res.json() as Promise<AuditVerifyResult>;
+		}
+		throw await this.toError(res, "GET", "/admin/audit/verify");
+	}
+
+	/**
+	 * Download a tar archive of the schema-meaningful tables (users,
+	 * documents, permissions, invites, optionally audit log). Requires
+	 * elevated role. The server gzips the response when the client sends
+	 * `Accept-Encoding: gzip` — `fetch` handles that transparently, so
+	 * the returned Blob is the raw tar bytes.
+	 */
+	async adminBackupDump(opts?: { includeAudit?: boolean }): Promise<Blob> {
+		const params = new URLSearchParams();
+		if (opts?.includeAudit) params.set("include_audit", "true");
+		const qs = params.toString();
+		const headers: Record<string, string> = {};
+		if (this._token) headers["Authorization"] = `Bearer ${this._token}`;
+		const res = await this._fetch(
+			`${this.baseUrl}/admin/backup/dump${qs ? `?${qs}` : ""}`,
+			{ method: "GET", headers },
+		);
+		if (!res.ok) throw await this.toError(res, "GET", "/admin/backup/dump");
+		return res.blob();
+	}
+
 	// ── Snapshots ────────────────────────────────────────────────────────────
 
 	/** List snapshot metadata for a document. */
@@ -718,10 +1117,17 @@ export class AbracadabraClient {
 		return res.snapshots;
 	}
 
-	/** Fetch a single snapshot including its base64-encoded data blob. */
-	async getSnapshot(docId: string, version: number): Promise<SnapshotData> {
+	/** Fetch a single snapshot including its base64-encoded data blob.
+	 *  Pass `{ include: "files" }` to also receive the joined upload list
+	 *  (each `fileBlock` / `coverUploadId` resolved against `uploads`). */
+	async getSnapshot(
+		docId: string,
+		version: number,
+		opts?: { include?: "files" | string },
+	): Promise<SnapshotData> {
+		const qs = opts?.include ? `?include=${encodeURIComponent(opts.include)}` : "";
 		return this.request<SnapshotData>(
-			"GET", `/docs/${encodeURIComponent(docId)}/snapshots/${version}`,
+			"GET", `/docs/${encodeURIComponent(docId)}/snapshots/${version}${qs}`,
 		);
 	}
 
@@ -762,7 +1168,25 @@ export class AbracadabraClient {
 	}
 
 	/**
-	 * Fetch server metadata including the optional `index_doc_id` entry point.
+	 * Readiness probe — pings the database. Returns 200 with
+	 * `status: "ready"` only when the server can serve traffic, 503 with
+	 * `status: "unready"` otherwise (load balancers / Kubernetes probes
+	 * use the status code; the body is informational).
+	 *
+	 * The 503 case is special-cased here: instead of throwing, the method
+	 * returns the unready body so callers can react to the state without
+	 * try/catch boilerplate.
+	 */
+	async readyz(): Promise<ReadyzStatus> {
+		const res = await this._fetch(`${this.baseUrl}/readyz`, { method: "GET" });
+		if (res.status === 200 || res.status === 503) {
+			return res.json() as Promise<ReadyzStatus>;
+		}
+		throw await this.toError(res, "GET", "/readyz");
+	}
+
+	/**
+	 * Fetch server metadata including `root_doc_id` and the `[access]` policy.
 	 * No auth required.
 	 */
 	async serverInfo(): Promise<ServerInfo> {
@@ -848,6 +1272,32 @@ export class AbracadabraClient {
 		const prefix = method && path ? `${method} ${path}: ` : "";
 		const err = new Error(`${prefix}${message} (${res.status})`);
 		(err as any).status = res.status;
+		// Surface 401/403 to the auth-failed handler so consumers can trigger
+		// reauth without waiting for the next WS action. Fire-and-forget —
+		// the original Promise still rejects so callers handle their own
+		// error path. Wrap in setTimeout(0) so the callback runs out-of-band
+		// of the current request's microtask queue.
+		if ((res.status === 401 || res.status === 403) && this._onAuthFailed) {
+			const lower = message.toLowerCase();
+			let reason: AuthFailureReason = res.status === 401 ? "unauthorized" : "forbidden";
+			if (/user not found|user_not_found|public key not registered|no such user/.test(lower)) {
+				reason = "user_not_found";
+			} else if (/account revoked|user account revoked/.test(lower)) {
+				reason = "account_revoked";
+			} else if (/forbidden|insufficient permissions/.test(lower)) {
+				reason = "forbidden";
+			}
+			const ctx: AuthFailureContext = {
+				status: res.status,
+				message,
+				reason,
+				method: method ?? "",
+				path: path ?? "",
+			};
+			try {
+				setTimeout(() => { try { this._onAuthFailed!(ctx); } catch { /* swallow */ } }, 0);
+			} catch { /* setTimeout unavailable in some sandboxes — drop the signal */ }
+		}
 		return err;
 	}