@abraca/dabra 2.0.0 → 2.0.2

package/dist/index.d.ts

@@ -748,6 +748,32 @@ declare class AbracadabraClient {
   adminBackupDump(opts?: {
     includeAudit?: boolean;
   }): Promise<Blob>;
+  /**
+   * List every registered config field with current value + origin
+   * (`default` / `env` / `global_override` / `route_override`). Requires
+   * elevated role.
+   */
+  adminConfigList(): Promise<AdminConfigField[]>;
+  /** Read a single config field by dotted path (e.g. `"access.authenticated"`). */
+  adminConfigGet(path: string): Promise<AdminConfigField>;
+  /**
+   * Set a runtime override on a config field. The field must be marked
+   * `runtime_mutable = true` in the registry; immutable fields return a
+   * schema error. Persists to the `settings_overrides` table.
+   */
+  adminConfigSet(path: string, value: unknown): Promise<AdminConfigField>;
+  /**
+   * Clear a runtime override and revert the field to its env/TOML/default
+   * base value. Returns `true` when an override was actually removed.
+   */
+  adminConfigUnset(path: string): Promise<boolean>;
+  /**
+   * Diagnostic dump of every `ABRA_*` env var the running process saw at
+   * boot, mapped to its config path. Use this to debug
+   * "I set this in `.env` but the server reports a different value".
+   * Secrets are redacted (`value: null`, `redacted: true`).
+   */
+  adminConfigEnvSnapshot(): Promise<EnvSnapshotResponse>;
   /** List snapshot metadata for a document. */
   listSnapshots(docId: string, opts?: {
     limit?: number;
@@ -1697,6 +1723,64 @@ interface AuditVerifyResult {
     reason: string;
   };
 }
+/**
+ * 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).
+ */
+type AdminConfigOriginKind = "default" | "env" | "global_override" | "route_override";
+/** One entry returned by `GET /admin/config` and `GET /admin/config/fields/:path`. */
+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`.
+ */
+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.
+ */
+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.
+ */
+interface EnvSnapshotResponse {
+  items: EnvSnapshotItem[];
+  extensions: EnvSnapshotExtension[];
+  unknown: string[];
+}
 /** Response of `GET /readyz`. HTTP 200 when ready, 503 when not. */
 interface ReadyzStatus {
   status: "ready" | "unready";
@@ -4465,4 +4549,4 @@ declare function normalizeRootId(id: string | null | undefined, rootDocId: strin
  */
 declare function toPlain(val: unknown): unknown;
 //#endregion
-export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AuditLogEntry, AuditQueryOpts, AuditVerifyResult, AuthFailureContext, AuthFailureReason, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, ChannelKeyResolver, type ChatChannel, ChatClient, type ChatClientTransport, type MarkReadInput as ChatMarkReadInput, type ChatMessage, type ChatReadCursor, type ChatReadReceipt, type ChatTypingEvent, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, ContentManager, type CreateNotificationInput, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, type DeleteMessageInput, DevicePairingChannel, type DevicePairingConfig, DeviceRegistrationService, type DeviceServerStatus, type DeviceTier, type DocEncryptionInfo, DocKeyManager, DocSearchHit, type DocSyncState, type DocumentBlock, DocumentCache, type DocumentCacheOptions, type DocumentContent, DocumentManager, type DocumentManagerConfig, DocumentMeta, type DocumentMetaInfo, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, type EditMessageInput, EffectivePermissionEntry, EffectivePermissionsResponse, EffectiveRole, EncryptedChatClient, EncryptedYMap, EncryptedYText, type FetchInboxInput, type FetchNotificationsInput, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, type FoldedMessage, Forbidden, GEO_TYPE_META_SCHEMAS, type GetChatHistoryInput, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, type IdentityDeviceEntry, type IdentityDocConfiguration, IdentityDocProvider, type IdentityProfile, type IdentityServerEntry, type IdentitySpaceEntry, type InboxEntry, type MarkReadInput$1 as InboxMarkReadInput, InviteRow, KEY_EXCHANGE_CHANNEL, Kind, ManualSignaling, type ManualSignalingBlob, type MessageRecord, MessageTooBig, MessageType, MetaFieldType, MetaManager, type NotificationReadUpdate, type NotificationRecord, NotificationsClient, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, PAGE_TYPES, PageMeta, PageTypeInfo, PageTypeMetaField, type PairingRequest, type PairingResult, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, RPC_PREFIX, ReadyzStatus, ResetConnection, type RpcCallHandle, type RpcCallOptions, RpcClient, RpcError, type RpcErrorCode, type RpcErrorPayload, type RpcFrame, type RpcHandler, type RpcHandlerContext, type RpcKind, type RpcTarget, type RpcTransport, SERVER_ROOT_ID, SearchIndex, SearchResult, type SendChatMessageInput, type SendMessageInput, type SendMessageResult, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SnapshotCreateResult, SnapshotData, SnapshotFileEntry, SnapshotForkResult, SnapshotMeta, SnapshotRestoreResult, StatesArray, SubdocMessage, SubdocRegisteredEvent, TYPE_ALIASES, TreeEntry, TreeManager, TreeNode, TreeSearchResult, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserMetaField, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, wordlist as bip39Wordlist, buildBlockquoteElement, buildBlocksFromMarkdown, buildBulletListElement, buildCodeBlockElement, buildHeadingElement, buildHorizontalRuleElement, buildOrderedListElement, buildParagraphElement, buildTaskListElement, decryptChatContent, decryptField, deriveIdentityDocId, deriveSeedWrappingKey, encryptChatContent, encryptField, filenameToLabel, foldRecords, generateMnemonic, isEncryptedContent, makeEncryptedYMap, makeEncryptedYText, mnemonicToEd25519Seed, mnemonicToKeyPair, normalizeRootId, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onCompactedParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onServerErrorParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, parseFrontmatter, populateYDocFromMarkdown, readAuthMessage, readBlocksFromFragment, recordFromYAny, resolvePageType, toPlain, unwrapSeed, validateMnemonic, waitForSync, withTimeout, wrapSeed, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest, yjsToMarkdown };
+export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AdminConfigField, AdminConfigOriginKind, AuditLogEntry, AuditQueryOpts, AuditVerifyResult, AuthFailureContext, AuthFailureReason, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, ChannelKeyResolver, type ChatChannel, ChatClient, type ChatClientTransport, type MarkReadInput as ChatMarkReadInput, type ChatMessage, type ChatReadCursor, type ChatReadReceipt, type ChatTypingEvent, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, ContentManager, type CreateNotificationInput, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, type DeleteMessageInput, DevicePairingChannel, type DevicePairingConfig, DeviceRegistrationService, type DeviceServerStatus, type DeviceTier, type DocEncryptionInfo, DocKeyManager, DocSearchHit, type DocSyncState, type DocumentBlock, DocumentCache, type DocumentCacheOptions, type DocumentContent, DocumentManager, type DocumentManagerConfig, DocumentMeta, type DocumentMetaInfo, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, type EditMessageInput, EffectivePermissionEntry, EffectivePermissionsResponse, EffectiveRole, EncryptedChatClient, EncryptedYMap, EncryptedYText, EnvSnapshotExtension, EnvSnapshotItem, EnvSnapshotResponse, type FetchInboxInput, type FetchNotificationsInput, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, type FoldedMessage, Forbidden, GEO_TYPE_META_SCHEMAS, type GetChatHistoryInput, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, type IdentityDeviceEntry, type IdentityDocConfiguration, IdentityDocProvider, type IdentityProfile, type IdentityServerEntry, type IdentitySpaceEntry, type InboxEntry, type MarkReadInput$1 as InboxMarkReadInput, InviteRow, KEY_EXCHANGE_CHANNEL, Kind, ManualSignaling, type ManualSignalingBlob, type MessageRecord, MessageTooBig, MessageType, MetaFieldType, MetaManager, type NotificationReadUpdate, type NotificationRecord, NotificationsClient, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, PAGE_TYPES, PageMeta, PageTypeInfo, PageTypeMetaField, type PairingRequest, type PairingResult, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, RPC_PREFIX, ReadyzStatus, ResetConnection, type RpcCallHandle, type RpcCallOptions, RpcClient, RpcError, type RpcErrorCode, type RpcErrorPayload, type RpcFrame, type RpcHandler, type RpcHandlerContext, type RpcKind, type RpcTarget, type RpcTransport, SERVER_ROOT_ID, SearchIndex, SearchResult, type SendChatMessageInput, type SendMessageInput, type SendMessageResult, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SnapshotCreateResult, SnapshotData, SnapshotFileEntry, SnapshotForkResult, SnapshotMeta, SnapshotRestoreResult, StatesArray, SubdocMessage, SubdocRegisteredEvent, TYPE_ALIASES, TreeEntry, TreeManager, TreeNode, TreeSearchResult, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserMetaField, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, wordlist as bip39Wordlist, buildBlockquoteElement, buildBlocksFromMarkdown, buildBulletListElement, buildCodeBlockElement, buildHeadingElement, buildHorizontalRuleElement, buildOrderedListElement, buildParagraphElement, buildTaskListElement, decryptChatContent, decryptField, deriveIdentityDocId, deriveSeedWrappingKey, encryptChatContent, encryptField, filenameToLabel, foldRecords, generateMnemonic, isEncryptedContent, makeEncryptedYMap, makeEncryptedYText, mnemonicToEd25519Seed, mnemonicToKeyPair, normalizeRootId, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onCompactedParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onServerErrorParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, parseFrontmatter, populateYDocFromMarkdown, readAuthMessage, readBlocksFromFragment, recordFromYAny, resolvePageType, toPlain, unwrapSeed, validateMnemonic, waitForSync, withTimeout, wrapSeed, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest, yjsToMarkdown };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",

package/src/AbracadabraBaseProvider.ts

@@ -611,6 +611,25 @@ export class AbracadabraBaseProvider extends EventEmitter {
   permissionDeniedHandler(reason: string) {
     this.emit("authenticationFailed", { reason });
     this.isAuthenticated = false;
+
+    // Stop the reconnect loop on a permanent denial. Without this the WS
+    // closes after every server-side rejection, AbracadabraWS schedules a
+    // retry, the new connection sends the same Subscribe → server denies
+    // again, ad infinitum (CPU/log/network spam, page looks "broken" to
+    // the user). The dominant cases:
+    //   * "document not found" — entry-doc-id pinned to something that
+    //     doesn't exist on this server
+    //   * "permission denied" — operator never granted the user access
+    // Both are config issues; retrying won't fix them. We only stop the
+    // socket when this provider OWNS it (`manageSocket`); shared sockets
+    // (e.g. multiplexed child providers) leave the parent's lifecycle
+    // alone and just give up on this doc.
+    if (this.manageSocket) {
+      try {
+        this.configuration.websocketProvider.disconnect();
+      }
+      catch { /* WS may already be torn down — best effort */ }
+    }
   }
 
   authenticatedHandler(scope: string) {

package/src/AbracadabraClient.ts

@@ -19,6 +19,8 @@ import type {
 	AuditLogEntry,
 	AuditQueryOpts,
 	AuditVerifyResult,
+	AdminConfigField,
+	EnvSnapshotResponse,
 } from "./types.ts";
 import { Kind, SERVER_ROOT_ID } from "./types.ts";
 import type { DocEncryptionInfo } from "./types.ts";
@@ -1103,6 +1105,60 @@ export class AbracadabraClient {
 		return res.blob();
 	}
 
+	// ── Admin: runtime config store ──────────────────────────────────────────
+
+	/**
+	 * List every registered config field with current value + origin
+	 * (`default` / `env` / `global_override` / `route_override`). Requires
+	 * elevated role.
+	 */
+	async adminConfigList(): Promise<AdminConfigField[]> {
+		const res = await this.request<{ items: AdminConfigField[] }>(
+			"GET", "/admin/config",
+		);
+		return res.items;
+	}
+
+	/** Read a single config field by dotted path (e.g. `"access.authenticated"`). */
+	async adminConfigGet(path: string): Promise<AdminConfigField> {
+		return this.request<AdminConfigField>(
+			"GET", `/admin/config/fields/${encodeURIComponent(path)}`,
+		);
+	}
+
+	/**
+	 * Set a runtime override on a config field. The field must be marked
+	 * `runtime_mutable = true` in the registry; immutable fields return a
+	 * schema error. Persists to the `settings_overrides` table.
+	 */
+	async adminConfigSet(path: string, value: unknown): Promise<AdminConfigField> {
+		return this.request<AdminConfigField>(
+			"PUT", `/admin/config/fields/${encodeURIComponent(path)}`,
+			{ body: { value } },
+		);
+	}
+
+	/**
+	 * Clear a runtime override and revert the field to its env/TOML/default
+	 * base value. Returns `true` when an override was actually removed.
+	 */
+	async adminConfigUnset(path: string): Promise<boolean> {
+		const res = await this.request<{ existed: boolean }>(
+			"DELETE", `/admin/config/fields/${encodeURIComponent(path)}`,
+		);
+		return res.existed;
+	}
+
+	/**
+	 * Diagnostic dump of every `ABRA_*` env var the running process saw at
+	 * boot, mapped to its config path. Use this to debug
+	 * "I set this in `.env` but the server reports a different value".
+	 * Secrets are redacted (`value: null`, `redacted: true`).
+	 */
+	async adminConfigEnvSnapshot(): Promise<EnvSnapshotResponse> {
+		return this.request<EnvSnapshotResponse>("GET", "/admin/config/env-snapshot");
+	}
+
 	// ── Snapshots ────────────────────────────────────────────────────────────
 
 	/** List snapshot metadata for a document. */

package/src/AbracadabraWS.ts

@@ -188,7 +188,7 @@ export class AbracadabraWS extends EventEmitter {
 
     this.configuration.WebSocketPolyfill = configuration.WebSocketPolyfill
       ? configuration.WebSocketPolyfill
-      : WebSocket;
+      : (globalThis as { WebSocket?: typeof WebSocket }).WebSocket;
 
     this.on("open", this.configuration.onOpen);
     this.on("open", this.onOpen.bind(this));

package/src/types.ts

@@ -456,6 +456,75 @@ export interface AuditVerifyResult {
   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. */