@abraca/dabra 1.9.1 → 2.0.1

package/src/types.ts

@@ -183,20 +183,68 @@ export interface UserProfile {
   role: string;
   /** Account-level Ed25519 public key (base64url). Canonical user identity. */
   publicKey: string | null;
+  /**
+   * Whether the user has a password set. `false` for key-based soft
+   * identities until they opt in via {@link AbracadabraClient.setPassword}.
+   * Drives the UI's "Set password" vs "Change password" branching.
+   */
+  hasPassword?: boolean;
 }
 
 export interface DocumentMeta {
   id: string;
   parent_id: string | null;
+  /**
+   * Renderer hint — `"kanban"`, `"checklist"`, `"outline"`, `"graph"`,
+   * `"sheet"`, `"mindmap"`, `"doc"`, etc. Drives the dashboard's choice of
+   * Vue component for this doc. Orthogonal to {@link kind}.
+   */
   doc_type?: string | null;
   label?: string | null;
   description?: string | null;
   public_access?: string | null;
   owner_id?: string | null;
-  is_hub?: boolean;
+  /**
+   * Structural role hint — `"server"` for the reserved server-root doc,
+   * `"space"` for top-level workspace containers, `null`/absent otherwise.
+   * Distinct from {@link doc_type}: a Space (`kind: "space"`) can contain
+   * many Kanban boards (each `doc_type: "kanban"`).
+   */
+  kind?: string | null;
   updated_at?: number | null;
 }
 
+/**
+ * Well-known structural roles for the {@link DocumentMeta.kind} field. These
+ * are conventions only — the server treats `kind` as an opaque string. Use
+ * these constants instead of string literals to avoid typos.
+ */
+export const Kind = {
+  /** The reserved server root document. There is exactly one per server. */
+  Server: "server",
+  /** A top-level workspace container — what the dashboard calls a "Space". */
+  Space: "space",
+  /** A regular content page rendered by the editor. */
+  Page: "page",
+  /** A group chat container under a Space. */
+  Channel: "channel",
+  /** A direct-message container at the server root with two-member permissions. */
+  Dm: "dm",
+  /** A child of channel/dm holding the messages Y.Array. */
+  ChannelPeriod: "channel-period",
+  /** A per-user inbox doc holding inbox entries; child of server root. */
+  Inbox: "inbox",
+} as const;
+export type Kind = typeof Kind[keyof typeof Kind];
+
+/**
+ * Hardcoded UUID of the reserved server root document. Every doc in the tree
+ * chains up to this row, so a permission grant on this doc cascades into
+ * every descendant. Mirrors the constant in the Rust crate
+ * (`crate::types::SERVER_ROOT_ID_STR`).
+ */
+export const SERVER_ROOT_ID = "00000000-0000-0000-0000-000000000000";
+
 export interface UploadMeta {
   id: string;
   doc_id: string;
@@ -250,10 +298,30 @@ export interface SnapshotMeta {
   label?: string | null;
   created_by?: string | null;
   created_at: number;
+  /** Number of uploads referenced by this snapshot's CRDT state.
+   *  Always 0 on servers older than the `snapshot_files` migration, or for
+   *  snapshots created before that migration ran (until the operator runs
+   *  `POST /admin/snapshots/backfill-refs`). */
+  file_count?: number;
+  /** Signed byte delta vs. the previous-version snapshot for this doc.
+   *  `null` for the first snapshot of a doc (or when the previous version
+   *  has been pruned). Lets the UI render `+12 KB` / `−3 KB`. */
+  delta_bytes?: number | null;
+}
+
+export interface SnapshotFileEntry {
+  id: string;
+  doc_id: string;
+  filename: string;
+  mime_type?: string | null;
+  size?: number | null;
 }
 
 export interface SnapshotData extends SnapshotMeta {
   data: string;
+  /** Populated only when fetched with `?include=files`. Each entry is an
+   *  upload referenced by this snapshot's CRDT state. */
+  files?: SnapshotFileEntry[];
 }
 
 export interface SnapshotCreateResult {
@@ -285,10 +353,23 @@ export interface ServerInfo {
   version?: string;
   /** Hocuspocus wire protocol version (currently 2). */
   protocol_version?: number;
-  /** Entry-point document ID advertised by the server, if configured. */
-  index_doc_id?: string;
-  /** Default role assigned to users without explicit permissions. */
-  default_role?: string;
+  /**
+   * The reserved server root document id. Every doc in the tree chains up
+   * to this row; granting Admin here cascades to every doc. Hardcoded by
+   * the server — clients can also use {@link SERVER_ROOT_ID} directly.
+   */
+  root_doc_id?: string;
+  /**
+   * Server-wide access policy. Drives client-side decisions like "show the
+   * sign-up CTA?" (anonymous mode) or "warn before publishing?" (anonymous
+   * grants).
+   */
+  access?: {
+    /** `"none"` rejects unauthenticated requests; `"observer"` allows public read. */
+    anonymous?: "none" | "observer";
+    /** Server-wide floor for authed users with no explicit grant. */
+    authenticated?: "none" | "observer" | "viewer" | "editor";
+  };
   /** Enabled auth methods (e.g. ["crypto", "jwt"]). */
   auth_methods?: string[];
   /** Whether open registration is enabled. */
@@ -297,6 +378,13 @@ export interface ServerInfo {
   invite_only?: boolean;
   /** Server encryption configuration. */
   encryption?: { default_mode?: string; minimum_mode?: string };
+  /**
+   * Ed25519 public key (base64url, no padding) the server uses to sign every
+   * accepted `messages:*` record (`server_sig`). Clients can verify message
+   * placement / ordering by checking each record's `server_sig` against this
+   * key over the canonical `{ msg_id, period_id, ts, client_sig }` payload.
+   */
+  messages_signer_pubkey?: string;
 }
 
 // ── Search ───────────────────────────────────────────────────────────────────
@@ -307,21 +395,152 @@ export interface SearchResult {
   score: number;
 }
 
-// ── Spaces ───────────────────────────────────────────────────────────────────
+/**
+ * A single hit returned by the server's full-text search endpoint
+ * (`GET /docs/search`). Distinct from {@link SearchResult}, which is the
+ * client-side trigram index in `SearchIndex.ts`.
+ *
+ * `snippet` is server-rendered HTML with `<mark>` wrappers around the
+ * matched tokens — safe to inject after standard sanitization. `rank` is
+ * a backend-specific score (SQLite bm25 vs Postgres ts_rank); the only
+ * guarantee is that hits arrive in best-first order.
+ */
+export interface DocSearchHit {
+  doc_id: string;
+  parent_id: string | null;
+  label: string | null;
+  kind: string | null;
+  /** HTML-safe snippet with `<mark>` markers around the matched tokens. */
+  snippet: string;
+  rank: number;
+}
 
-export interface SpaceMeta {
+// ── Audit log (admin) ────────────────────────────────────────────────────────
+
+/**
+ * A single row from `GET /admin/audit`. Mirrors the server's audit log
+ * row format (see `audit::AuditLogRow`). `metadata` is the parsed JSON
+ * object the server stored, or `null` if the row had no metadata. Each
+ * row carries an internal `prev_hash` / `row_hash` chain that admins
+ * verify with {@link AuditVerifyResult}.
+ */
+export interface AuditLogEntry {
   id: string;
-  doc_id: string;
-  name: string;
-  description: string | null;
-  visibility: "public" | "private" | "invite";
-  is_hub: boolean;
-  owner_id: string | null;
-  created_at: number;
-  updated_at: number;
-  public_access?: string | null;
+  ts: number;
+  event_type: string;
+  actor_user_id: string | null;
+  actor_ip: string | null;
+  request_id: string | null;
+  target_type: string | null;
+  target_id: string | null;
+  metadata: Record<string, unknown> | null;
+  outcome: string;
+}
+
+/** Filters for `GET /admin/audit`. All optional and AND-combined. */
+export interface AuditQueryOpts {
+  event_type?: string;
+  actor_user_id?: string;
+  target_type?: string;
+  target_id?: string;
+  since_ts?: number;
+  until_ts?: number;
+  limit?: number;
+  offset?: number;
+}
+
+/** Response of `GET /admin/audit/verify`. `status: "broken"` carries `break`. */
+export interface AuditVerifyResult {
+  status: "ok" | "broken";
+  message?: string;
+  break?: { rows_checked: number; row_id: string; reason: string };
 }
 
+// ── Admin: runtime config store ───────────────────────────────────────────────
+
+/**
+ * Where the current value of a config field came from.
+ *
+ *   * `default` — compiled-in default; nobody touched it.
+ *   * `env` — set at startup by an `ABRA_*` env var.
+ *   * `global_override` — admin runtime override via `/admin/config`.
+ *   * `route_override` — per-route override (Phase 3).
+ */
+export type AdminConfigOriginKind =
+  | "default"
+  | "env"
+  | "global_override"
+  | "route_override";
+
+/** One entry returned by `GET /admin/config` and `GET /admin/config/fields/:path`. */
+export interface AdminConfigField {
+  path: string;
+  section: string;
+  description: string;
+  env_var: string;
+  runtime_mutable: boolean;
+  value: unknown;
+  origin_kind: AdminConfigOriginKind;
+  /** Provenance — present only when origin_kind is a `*_override`. */
+  set_at?: number;
+  set_by?: string;
+  route?: string;
+}
+
+/**
+ * One row from `GET /admin/config/env-snapshot.items[]`. Reports whether
+ * each registry-known `ABRA_*` env var was set in the running process at
+ * boot, with secrets reported as `value: null` and `redacted: true`.
+ */
+export interface EnvSnapshotItem {
+  env_var: string;
+  path: string;
+  section: string;
+  present: boolean;
+  /** Verbatim env value, or `null` for redacted (secrets) or unset. */
+  value: string | null;
+  redacted: boolean;
+}
+
+/**
+ * One row from `GET /admin/config/env-snapshot.extensions[]`. Extension
+ * overrides (`ABRA_EXT_<name>_<field>`) sit outside the registry and are
+ * reported by name with values inline.
+ */
+export interface EnvSnapshotExtension {
+  env_var: string;
+  value: string;
+}
+
+/**
+ * `GET /admin/config/env-snapshot` response.
+ *
+ * `unknown` lists `ABRA_*` env vars present in the process that don't map
+ * to any registered field — i.e. typos. Operators that see their tweak
+ * land here instead of in `items` know they misspelled the var.
+ */
+export interface EnvSnapshotResponse {
+  items: EnvSnapshotItem[];
+  extensions: EnvSnapshotExtension[];
+  unknown: string[];
+}
+
+// ── Readiness ────────────────────────────────────────────────────────────────
+
+/** Response of `GET /readyz`. HTTP 200 when ready, 503 when not. */
+export interface ReadyzStatus {
+  status: "ready" | "unready";
+  version: string;
+  checks: { database: "ok" | "error" };
+}
+
+// ── Spaces ───────────────────────────────────────────────────────────────────
+//
+// Spaces are documents whose `parent_id` is the server root and whose `kind`
+// is `"space"`. Listing them is `client.listSpaces()`; they come back as
+// regular `DocumentMeta` objects. Visibility is encoded in `public_access`:
+// `null` (or `"none"`) = private, `"observer"` = public read-only.
+
 // ── Invites ──────────────────────────────────────────────────────────────────
 
 export interface InviteRow {

package/src/webrtc/AbracadabraWebRTC.ts

@@ -527,7 +527,7 @@ export class AbracadabraWebRTC extends EventEmitter {
 				pendingKeyExchangeChannel = channel;
 				return;
 			}
-			channel.send(e2ee.getKeyExchangeMessage());
+			channel.send(e2ee.getKeyExchangeMessage() as unknown as ArrayBuffer);
 		});
 
 		this.resolveE2ee().then(async (identity) => {
@@ -541,7 +541,7 @@ export class AbracadabraWebRTC extends EventEmitter {
 
 			// Drain buffered key-exchange channel open
 			if (pendingKeyExchangeChannel) {
-				pendingKeyExchangeChannel.send(e2ee.getKeyExchangeMessage());
+				pendingKeyExchangeChannel.send(e2ee.getKeyExchangeMessage() as unknown as ArrayBuffer);
 			}
 			// Drain buffered messages
 			for (const msg of pendingMessages) {

package/src/webrtc/DataChannelRouter.ts

@@ -100,9 +100,9 @@ export class DataChannelRouter extends EventEmitter {
 
 		if (this.encryptor?.isEstablished && !this.plaintextChannels.has(name)) {
 			const encrypted = await this.encryptor.encrypt(data);
-			channel.send(encrypted);
+			channel.send(encrypted as unknown as ArrayBuffer);
 		} else {
-			channel.send(data);
+			channel.send(data as unknown as ArrayBuffer);
 		}
 		return true;
 	}

package/src/webrtc/E2EEChannel.ts

@@ -98,7 +98,7 @@ export class E2EEChannel extends EventEmitter {
 
 		this.sessionKey = await crypto.subtle.importKey(
 			"raw",
-			keyBytes,
+			keyBytes as BufferSource,
 			{ name: "AES-GCM" },
 			false,
 			["encrypt", "decrypt"],
@@ -130,9 +130,9 @@ export class E2EEChannel extends EventEmitter {
 		const nonce = crypto.getRandomValues(new Uint8Array(NONCE_BYTES));
 		const ciphertext = new Uint8Array(
 			await crypto.subtle.encrypt(
-				{ name: "AES-GCM", iv: nonce },
+				{ name: "AES-GCM", iv: nonce as BufferSource },
 				this.sessionKey,
-				plaintext,
+				plaintext as BufferSource,
 			),
 		);
 

package/src/webrtc/FileTransferChannel.ts

@@ -45,6 +45,13 @@ export class FileTransferHandle extends EventEmitter {
 	_setStatus(s: FileTransferStatus): void {
 		this.status = s;
 	}
+
+	/** @internal — public alias for the protected emit so the parent
+	 * `FileTransferChannel` (a different class instance) can dispatch events
+	 * on this handle. Protected access is by-class, not by-hierarchy. */
+	_emit(event: string, ...args: unknown[]): void {
+		this.emit(event, ...args);
+	}
 }
 
 interface ReceiveState {
@@ -102,7 +109,7 @@ export class FileTransferChannel extends EventEmitter {
 		const channel = this.router.getChannel(CHANNEL_NAMES.FILE_TRANSFER);
 		if (!channel || channel.readyState !== "open") {
 			handle._setStatus("error");
-			handle.emit("error", new Error("File transfer channel not open"));
+			handle._emit("error", new Error("File transfer channel not open"));
 			return handle;
 		}
 
@@ -174,7 +181,7 @@ export class FileTransferChannel extends EventEmitter {
 		channel.send(completeMsg);
 
 		handle._setStatus("complete");
-		handle.emit("complete");
+		handle._emit("complete");
 
 		return handle;
 	}