@sovereignbase/explorer 0.0.0-alpha.1 → 0.0.0-alpha.2

package/dist/class.js

@@ -0,0 +1,759 @@
+/*
+ * Copyright 2026 Sovereignbase
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { deleteObject, loadObject, storeObject } from "@sovereignbase/storage";
+import { afterIdleFor, isRecord } from "@sovereignbase/utils";
+import { Bytes } from "@sovereignbase/bytecodec";
+import { readableUserAgent } from "@sovereignbase/dom-utils";
+import { deriveDeviceEntropy } from "@sovereignbase/hardware-bound";
+import { Cryptographic } from "@sovereignbase/cryptosuite";
+import { Sequenced } from "@sovereignbase/sequenced";
+// src/.errors/class.ts
+/**
+* An Explorer error with a stable, machine-readable code and an optional cause.
+*
+* The message is prefixed with the library name. Use {@link code} rather than
+* parsing the message when handling a particular failure.
+*/
+var ExplorerError = class extends Error {
+	/** The machine-readable category of the failure. */
+	code;
+	/**
+	* Creates an error whose name is `ExplorerError`.
+	*
+	* @param code The category of the failure.
+	* @param message The detail to prefix with the library name; defaults to `code`.
+	* @param options Error options, including the original `cause`.
+	*/
+	constructor(code, message, options) {
+		super(`{@sovereignbase/explorer} ${message ?? code}`, options);
+		this.code = code;
+		this.name = "ExplorerError";
+	}
+};
+// src/.errors/unkown.ts
+/**
+* Preserves an existing library error or wraps an unexpected failure once.
+* @param cause The value thrown by the failed operation.
+* @param operation The operation name to include in the error message.
+* @returns The original library error, or an `UNKNOWN_ERROR` retaining `cause`.
+*/
+function unknownError(cause, operation) {
+	return cause instanceof ExplorerError ? cause : new ExplorerError("UNKNOWN_ERROR", `${operation} failed.`, { cause });
+}
+// src/CredentialEntries/class.ts
+/**
+* Maintains the database's credential entries.
+*
+* Entries are identified by credential ID and synchronized through
+* a sequenced array. Changes are persisted as encrypted snapshots.
+*/
+var CredentialEntries = class {
+	id;
+	cipherKey;
+	sessionCredentialID;
+	state;
+	deltaBuffer = new Array();
+	eventTarget;
+	/**
+	* Creates a credential entries list.
+	*
+	* @param id The identifier of the persisted entries object.
+	* @param cipherKey The key used to encrypt the entries object.
+	* @param sessionCredentialID The credential ID of the current session.
+	* @param actorID The actor identifier used by the sequenced array.
+	* @param trustedSnapshot An optional snapshot used to initialize the state.
+	*/
+	constructor(id, cipherKey, sessionCredentialID, actorID, trustedSnapshot) {
+		this.id = id;
+		this.cipherKey = cipherKey;
+		this.sessionCredentialID = sessionCredentialID;
+		try {
+			this.state = new Sequenced.Array(actorID, trustedSnapshot);
+			const debouncedDispatch = afterIdleFor(250, () => {
+				Explorer.dispatchEvent("delta", ["credentialEntries", this.deltaBuffer.splice(0)]);
+			});
+			this.state.addEventListener("delta", ({ detail }) => {
+				this.deltaBuffer.push(...detail);
+				debouncedDispatch();
+			});
+			const debouncedSave = afterIdleFor(250, async (snapshot) => {
+				await Explorer.storeObjectByID(this.id, snapshot, this.cipherKey);
+			});
+			this.state.addEventListener("snapshot", ({ detail }) => {
+				debouncedSave(detail);
+			});
+			this.state.addEventListener("change", ({ detail }) => {
+				this.dispatchEvent("change", detail);
+			});
+			const seen = /* @__PURE__ */ new Set();
+			const duplicates = [];
+			for (let index = 0; index < this.state.length; index++) {
+				const entry = this.state.at(index);
+				if (!entry) continue;
+				if (seen.has(entry.id)) duplicates.push(index);
+				else seen.add(entry.id);
+			}
+			for (let index = duplicates.length - 1; index >= 0; index--) this.state.delete(duplicates[index]);
+			if (duplicates.length > 0 || this.deltaBuffer.length > 0) this.state.snapshot();
+		} catch (cause) {
+			throw unknownError(cause, "CredentialEntries.constructor()");
+		}
+	}
+	/**
+	* Creates or updates a credential entry.
+	*
+	* Updates the credential's last-used timestamp and the corresponding
+	* user agent's last-seen timestamp. Existing properties are preserved
+	* unless replacements are provided.
+	*
+	* @param credentialEvent The credential properties to apply.
+	* @throws {ExplorerError} If the event is invalid or setup properties are missing.
+	*/
+	record(credentialEvent) {
+		try {
+			if (!credentialEvent || typeof credentialEvent !== "object") throw new ExplorerError("INVALID_CREDENTIAL_EVENT", "A credential event must be an object.");
+			const { id, timestamp, userAgent, name, entropy, storage } = credentialEvent;
+			if (typeof id !== "string" || typeof timestamp !== "number" || !Number.isFinite(timestamp) || typeof userAgent !== "string") throw new ExplorerError("INVALID_CREDENTIAL_EVENT", "A credential event requires an ID, a finite timestamp, and a user agent.");
+			let existing;
+			for (let index = this.state.length - 1; index >= 0; index--) {
+				const entry = this.state.at(index);
+				if (entry?.id === id) {
+					existing = entry;
+					break;
+				}
+			}
+			if (!existing && (typeof name !== "string" || !(entropy instanceof Uint8Array) || typeof storage !== "string")) throw new ExplorerError("MISSING_CREDENTIAL_SETUP_PROPERTIES", "A new credential requires a name, entropy, and binding storage.");
+			const userAgents = existing?.userAgents.map((agent) => ({ ...agent })) ?? [];
+			const agent = userAgents.find((agent) => agent.name === userAgent);
+			if (agent) agent.lastSeen = Math.max(agent.lastSeen, timestamp);
+			else userAgents.push({
+				name: userAgent,
+				lastSeen: timestamp
+			});
+			const entry = {
+				id,
+				name: name ?? existing.name,
+				entropy: entropy ?? existing.entropy,
+				storage: storage ?? existing.storage,
+				lastUsed: Math.max(existing?.lastUsed ?? timestamp, timestamp),
+				userAgents
+			};
+			for (let index = this.state.length - 1; index >= 0; index--) if (this.state.at(index)?.id === id) this.state.delete(index);
+			this.state.unshift(entry);
+			this.state.snapshot();
+		} catch (cause) {
+			throw unknownError(cause, "CredentialEntries.record()");
+		}
+	}
+	/**
+	* Revokes a credential by deleting its persisted data and list entries.
+	*
+	* The list remains unchanged if deletion of the persisted credential fails.
+	*
+	* @param credentialID The identifier of the credential to revoke.
+	*/
+	async revoke(credentialID) {
+		try {
+			let exists = false;
+			for (let index = this.state.length - 1; index >= 0; index--) {
+				if (this.state.at(index)?.id !== credentialID) continue;
+				exists = true;
+				break;
+			}
+			if (!exists) return;
+			await Explorer.deleteObjectByID(credentialID);
+			for (let index = this.state.length - 1; index >= 0; index--) if (this.state.at(index)?.id === credentialID) this.state.delete(index);
+			this.state.snapshot();
+		} catch (cause) {
+			throw unknownError(cause, "CredentialEntries.revoke()");
+		}
+	}
+	/**
+	* Returns the credential entries ordered by most recent use.
+	*
+	* Entries with equal timestamps are ordered by identifier.
+	*/
+	list() {
+		try {
+			return this.state.slice().sort((a, b) => b.lastUsed - a.lastUsed || a.id.localeCompare(b.id));
+		} catch (cause) {
+			throw unknownError(cause, "CredentialEntries.list()");
+		}
+	}
+	/**
+	* Applies a sequenced delta to the credential entries list.
+	*
+	* @param delta The delta to apply.
+	*/
+	apply(delta) {
+		try {
+			this.state.apply(delta);
+			this.state.snapshot();
+		} catch (cause) {
+			throw unknownError(cause, "CredentialEntries.apply()");
+		}
+	}
+	/**
+	* Merges a snapshot into the credential entries list.
+	*
+	* @param snapshot The snapshot to merge.
+	*/
+	merge(snapshot) {
+		try {
+			this.state.merge(snapshot);
+			this.state.snapshot();
+		} catch (cause) {
+			throw unknownError(cause, "CredentialEntries.merge()");
+		}
+	}
+	/**
+	* Registers an event listener for the specified event type.
+	*
+	* @param type The event type.
+	* @param listener The event listener, or `null`.
+	* @param options The event listener options.
+	*/
+	addEventListener(type, listener, options) {
+		try {
+			(this.eventTarget ??= new EventTarget()).addEventListener(type, listener, options);
+		} catch (cause) {
+			throw unknownError(cause, "CredentialEntries.addEventListener()");
+		}
+	}
+	/**
+	* Removes an event listener previously registered with
+	* {@link addEventListener}.
+	*
+	* @param type The event type.
+	* @param listener The event listener to remove, or `null`.
+	* @param options The event listener options.
+	*/
+	removeEventListener(type, listener, options) {
+		try {
+			this.eventTarget?.removeEventListener(type, listener, options);
+		} catch (cause) {
+			throw unknownError(cause, "CredentialEntries.removeEventListener()");
+		}
+	}
+	/**
+	* Dispatches an event to the registered listeners.
+	*
+	* @param type The event type.
+	* @param detail The value exposed through `CustomEvent.detail`.
+	*/
+	dispatchEvent(type, detail) {
+		try {
+			this.eventTarget?.dispatchEvent(new CustomEvent(type, { detail }));
+		} catch (cause) {
+			throw unknownError(cause, "CredentialEntries.dispatchEvent()");
+		}
+	}
+};
+// src/RecentEntries/class.ts
+/**
+* Maintains the ordered list of recently accessed objects.
+*
+* Entries are ordered from most recently accessed to least recently accessed,
+* deduplicated by identifier, and limited to 20 entries.
+*/
+var RecentEntries = class {
+	id;
+	cipherKey;
+	state;
+	deltaBuffer = new Array();
+	eventTarget;
+	/**
+	* Creates a recent entries list.
+	*
+	* @param id The identifier of the persisted recent entries object.
+	* @param cipherKey The key used to encrypt the entries object.
+	* @param actorID The actor identifier used by the sequenced array.
+	* @param trustedSnapshot An optional snapshot used to initialize the state.
+	*/
+	constructor(id, cipherKey, actorID, trustedSnapshot) {
+		this.id = id;
+		this.cipherKey = cipherKey;
+		try {
+			this.state = new Sequenced.Array(actorID, trustedSnapshot);
+			const debouncedDispatch = afterIdleFor(250, () => {
+				Explorer.dispatchEvent("delta", ["recentEntries", this.deltaBuffer.splice(0)]);
+			});
+			this.state.addEventListener("delta", ({ detail }) => {
+				this.deltaBuffer.push(...detail);
+				debouncedDispatch();
+			});
+			const debouncedSave = afterIdleFor(250, async (snapshot) => {
+				await Explorer.storeObjectByID(this.id, snapshot, this.cipherKey);
+			});
+			this.state.addEventListener("snapshot", ({ detail }) => {
+				debouncedSave(detail);
+			});
+			this.state.addEventListener("change", ({ detail }) => {
+				this.dispatchEvent("change", detail);
+			});
+			const seen = /* @__PURE__ */ new Set();
+			const duplicates = [];
+			for (let index = 0; index < this.state.length; index++) {
+				const entry = this.state.at(index);
+				if (!entry) continue;
+				if (seen.has(entry.id) || seen.size >= 20) duplicates.push(index);
+				else seen.add(entry.id);
+			}
+			for (let index = duplicates.length - 1; index >= 0; index--) this.state.delete(duplicates[index]);
+			if (duplicates.length > 0 || this.deltaBuffer.length > 0) this.state.snapshot();
+		} catch (cause) {
+			throw unknownError(cause, "RecentEntries.constructor()");
+		}
+	}
+	/**
+	* Marks an entry as most recently accessed.
+	*
+	* Any existing entry with the same identifier is removed before the new
+	* entry is inserted at the beginning of the list.
+	*
+	* @param accessed The entry that was accessed.
+	*/
+	update(accessed) {
+		try {
+			for (let index = this.state.length - 1; index >= 0; index--) if (this.state.at(index)?.id === accessed.id) this.state.delete(index);
+			this.state.unshift(accessed);
+			while (this.state.length > 20) this.state.pop();
+			this.state.snapshot();
+		} catch (cause) {
+			throw unknownError(cause, "RecentEntries.update()");
+		}
+	}
+	/**
+	* Removes an entry from the recent entries list.
+	*
+	* The referenced object is not deleted.
+	*
+	* @param id The identifier of the entry to remove.
+	*/
+	delete(id) {
+		try {
+			let deleted = false;
+			for (let index = this.state.length - 1; index >= 0; index--) {
+				if (this.state.at(index)?.id !== id) continue;
+				this.state.delete(index);
+				deleted = true;
+			}
+			if (deleted) this.state.snapshot();
+		} catch (cause) {
+			throw unknownError(cause, "RecentEntries.delete()");
+		}
+	}
+	/**
+	* Returns the recent entries ordered by most recent access.
+	*/
+	list() {
+		try {
+			return this.state.slice().sort((a, b) => b.dateAccessed - a.dateAccessed || a.id.localeCompare(b.id));
+		} catch (cause) {
+			throw unknownError(cause, "RecentEntries.list()");
+		}
+	}
+	/**
+	* Applies a sequenced delta to the recent entries list.
+	*
+	* @param delta The delta to apply.
+	*/
+	apply(delta) {
+		try {
+			this.state.apply(delta);
+			this.state.snapshot();
+		} catch (cause) {
+			throw unknownError(cause, "RecentEntries.apply()");
+		}
+	}
+	/**
+	* Merges a snapshot into the recent entries list.
+	*
+	* @param snapshot The snapshot to merge.
+	*/
+	merge(snapshot) {
+		try {
+			this.state.merge(snapshot);
+			this.state.snapshot();
+		} catch (cause) {
+			throw unknownError(cause, "RecentEntries.merge()");
+		}
+	}
+	/**
+	* Registers an event listener for the specified event type.
+	*
+	* @param type The event type.
+	* @param listener The event listener, or `null`.
+	* @param options The event listener options.
+	*/
+	addEventListener(type, listener, options) {
+		try {
+			(this.eventTarget ??= new EventTarget()).addEventListener(type, listener, options);
+		} catch (cause) {
+			throw unknownError(cause, "RecentEntries.addEventListener()");
+		}
+	}
+	/**
+	* Removes an event listener previously registered with
+	* {@link addEventListener}.
+	*
+	* @param type The event type.
+	* @param listener The event listener to remove, or `null`.
+	* @param options The event listener options.
+	*/
+	removeEventListener(type, listener, options) {
+		try {
+			this.eventTarget?.removeEventListener(type, listener, options);
+		} catch (cause) {
+			throw unknownError(cause, "RecentEntries.removeEventListener()");
+		}
+	}
+	/**
+	* Dispatches an event to the registered listeners.
+	*
+	* @param type The event type.
+	* @param detail The value exposed through `CustomEvent.detail`.
+	*/
+	dispatchEvent(type, detail) {
+		try {
+			this.eventTarget?.dispatchEvent(new CustomEvent(type, { detail }));
+		} catch (cause) {
+			throw unknownError(cause, "RecentEntries.dispatchEvent()");
+		}
+	}
+};
+// src/class.ts
+/**
+* Provides authentication, encrypted object storage, and access to
+* the database's synchronized entries.
+*
+* Maintains the authenticated database context and exposes static methods
+* for managing stored objects, observing entries, and applying remote deltas.
+*/
+var Explorer = class {
+	/** The identifier of the authenticated database. */
+	static databaseID;
+	/** Indicates whether the database has been authenticated. */
+	static isAuthenticated;
+	static storageURL;
+	static eventTarget;
+	static databaseSecret;
+	static sessionCredential = {};
+	/**
+	* Caches cipher keys by object identifier.
+	*
+	* Existing entries are preserved when an object is accessed with
+	* a cipher key.
+	*/
+	static cipherKeyCache = /* @__PURE__ */ new Map();
+	/**
+	* Authenticates a database using a data PIN and device-bound entropy.
+	*
+	* Derives the credential and database identifiers from cryptographic
+	* secrets. When setup parameters are provided, creates and stores a
+	* new credential. Otherwise, loads the existing credential.
+	*
+	* Records the authenticated credential in the database's credential list.
+	*
+	* @param dataPIN The PIN used to derive the credential and database secrets.
+	* @param storageURL The base URL used to access persisted database objects.
+	* @param setupParams Optional parameters for creating a new credential.
+	* @returns The authentication result.
+	*/
+	static async authenticate(dataPIN, storageURL, setupParams) {
+		try {
+			this.storageURL = storageURL;
+			const deviceEntropy = await deriveDeviceEntropy();
+			if (!deviceEntropy) return "authenticator-error";
+			this.sessionCredential = {
+				timestamp: Date.now(),
+				userAgent: readableUserAgent()
+			};
+			const dataPINBytes = Bytes.utf8.decode(dataPIN);
+			const credentialSecret = await Bytes.derive(deviceEntropy, dataPINBytes, 32);
+			const credentialID = await Cryptographic.identifier.derive(credentialSecret, Bytes.utf8.decode("@sovereignbase/explorer:CredentialID"), 32);
+			this.sessionCredential.id = credentialID;
+			const credentialCipherKey = await Cryptographic.cipherMessage.deriveKey(credentialSecret, Bytes.utf8.decode("@sovereignbase/explorer:CredentialCipherKey"));
+			let virtualEntropy;
+			if (isRecord(setupParams)) {
+				virtualEntropy = Bytes.generate(64);
+				await this.storeObjectByID(credentialID, virtualEntropy, credentialCipherKey);
+				this.sessionCredential.name = setupParams.credentialName;
+				this.sessionCredential.entropy = deviceEntropy;
+				this.sessionCredential.storage = setupParams.bindingStorage;
+			} else {
+				const result = await this.loadObjectByID(credentialID, credentialCipherKey);
+				if (!(result instanceof Uint8Array) || result.byteLength !== 64) return "invalid-data-pin";
+				virtualEntropy = result;
+			}
+			this.databaseSecret = await Bytes.derive(virtualEntropy, dataPINBytes, 64);
+			this.databaseID = await Cryptographic.identifier.derive(this.databaseSecret, Bytes.utf8.decode("@sovereignbase/explorer:DatabaseID"), 32);
+			this.isAuthenticated = true;
+			(await this.loadCredentialEntries()).record(this.sessionCredential);
+			delete this.sessionCredential;
+			this.dispatchEvent("authenticated", true);
+			return "authenticated";
+		} catch (cause) {
+			throw unknownError(cause, "Explorer.authenticate()");
+		}
+	}
+	/**
+	* Permanently revokes a credential and deletes its persisted data.
+	*
+	* Removes the credential from the database's registered credentials.
+	*
+	* @param credentialID The identifier of the credential to revoke.
+	* @throws {ExplorerError} If the database is not authenticated.
+	*/
+	static async permanentlyDeleteCredential(credentialID) {
+		try {
+			await (await this.loadCredentialEntries()).revoke(credentialID);
+			return;
+		} catch (cause) {
+			throw unknownError(cause, "Explorer.permanentlyDeleteCredential()");
+		}
+	}
+	/**
+	* Returns the registered credentials and optionally observes their changes.
+	*
+	* The returned tuple contains a cleanup function, the current credential
+	* entries, and the identifier of the current session's credential.
+	*
+	* The cleanup function removes the registered change listener, if any.
+	*
+	* @param onChange An optional callback invoked when the entries change.
+	* @returns The cleanup function, credential entries, and session credential ID.
+	* @throws {ExplorerError} If the database is not authenticated.
+	*/
+	static async listCredentialEntries(onChange) {
+		try {
+			const credentialEntries = await this.loadCredentialEntries();
+			const listener = onChange ? ({ detail }) => onChange(detail) : void 0;
+			if (listener) credentialEntries.addEventListener("change", listener);
+			return [
+				() => {
+					if (listener) credentialEntries.removeEventListener("change", listener);
+				},
+				credentialEntries.list(),
+				credentialEntries.sessionCredentialID
+			];
+		} catch (cause) {
+			throw unknownError(cause, "Explorer.listCredentialEntries()");
+		}
+	}
+	/**
+	* Returns the recently accessed objects and optionally observes their changes.
+	*
+	* The returned tuple contains a cleanup function and the current recent
+	* entries. The cleanup function removes the registered change listener,
+	* if any.
+	*
+	* @param onChange An optional callback invoked when the entries change.
+	* @returns The cleanup function and recent entries.
+	* @throws {ExplorerError} If the database is not authenticated.
+	*/
+	static async listRecentEntries(onChange) {
+		try {
+			const recentEntries = await this.loadRecentEntries();
+			const listener = onChange ? ({ detail }) => onChange(detail) : void 0;
+			if (listener) recentEntries.addEventListener("change", listener);
+			return [() => {
+				if (listener) recentEntries.removeEventListener("change", listener);
+			}, recentEntries.list()];
+		} catch (cause) {
+			throw unknownError(cause, "Explorer.listRecentEntries()");
+		}
+	}
+	/**
+	* Loads an encrypted object using its identifier and cipher key.
+	*
+	* Caches the cipher key if the identifier has not been encountered before.
+	*
+	* @typeParam T The expected type of the loaded object.
+	* @param id The identifier of the object to load.
+	* @param cipherKey The key used to decrypt the object.
+	* @param onNetworkResponse An optional callback for network responses.
+	* @returns The loaded object, or `undefined` if no object is available.
+	*/
+	static async loadObjectByID(id, cipherKey, onNetworkResponse) {
+		try {
+			if (!this.cipherKeyCache.has(id)) this.cipherKeyCache.set(id, cipherKey);
+			return await loadObject(this.storageURL + id, cipherKey, false, onNetworkResponse);
+		} catch (cause) {
+			throw unknownError(cause, "Explorer.loadObjectByID()");
+		}
+	}
+	/**
+	* Encrypts and stores an object using its identifier and cipher key.
+	*
+	* Caches the cipher key if the identifier has not been encountered before.
+	*
+	* @typeParam T The type of the object to store.
+	* @param id The identifier of the object to store.
+	* @param object The object to encrypt and store.
+	* @param cipherKey The key used to encrypt the object.
+	*/
+	static async storeObjectByID(id, object, cipherKey) {
+		try {
+			if (!this.cipherKeyCache.has(id)) this.cipherKeyCache.set(id, cipherKey);
+			await storeObject(this.storageURL + id, object, cipherKey);
+			return;
+		} catch (cause) {
+			throw unknownError(cause, "Explorer.storeObjectByID()");
+		}
+	}
+	/**
+	* Deletes a persisted object using its identifier.
+	*
+	* @param id The identifier of the object to delete.
+	*/
+	static async deleteObjectByID(id) {
+		try {
+			await deleteObject(this.storageURL + id);
+			(await this.loadRecentEntries()).delete(id);
+			return;
+		} catch (cause) {
+			throw unknownError(cause, "Explorer.deleteObjectByID()");
+		}
+	}
+	/**
+	* Schedules the application of a synchronized Explorer delta.
+	*
+	* Recognized deltas are forwarded to their corresponding entries list.
+	* Invalid or unrecognized delta types are ignored.
+	*
+	* Processing is scheduled in a microtask and is not awaited by the caller.
+	*
+	* @param data The delta to apply.
+	*/
+	static apply(data) {
+		queueMicrotask(async () => {
+			try {
+				if (!this.isExplorerDelta(data)) return;
+				switch (data[0]) {
+					case "recentEntries":
+						(await this.loadRecentEntries()).apply(data[1]);
+						break;
+					case "credentialEntries": (await this.loadCredentialEntries()).apply(data[1]);
+				}
+				return;
+			} catch (cause) {
+				throw unknownError(cause, "Explorer.apply()");
+			}
+		});
+	}
+	/**
+	* Registers an event listener for the specified event type.
+	*
+	* @param type The event type.
+	* @param listener The event listener, or `null`.
+	* @param options The event listener options.
+	*/
+	static addEventListener(type, listener, options) {
+		try {
+			(this.eventTarget ??= new EventTarget()).addEventListener(type, listener, options);
+		} catch (cause) {
+			throw unknownError(cause, "Explorer.addEventListener()");
+		}
+	}
+	/**
+	* Removes an event listener previously registered with
+	* {@link addEventListener}.
+	*
+	* @param type The event type.
+	* @param listener The event listener to remove, or `null`.
+	* @param options The event listener options.
+	*/
+	static removeEventListener(type, listener, options) {
+		try {
+			this.eventTarget?.removeEventListener(type, listener, options);
+		} catch (cause) {
+			throw unknownError(cause, "Explorer.removeEventListener()");
+		}
+	}
+	/**
+	* Dispatches an event to the registered listeners.
+	*
+	* @param type The event type.
+	* @param detail The value exposed through `CustomEvent.detail`.
+	*/
+	static dispatchEvent(type, detail) {
+		try {
+			this.eventTarget?.dispatchEvent(new CustomEvent(type, { detail }));
+		} catch (cause) {
+			throw unknownError(cause, "Explorer.dispatchEvent()");
+		}
+	}
+	/**
+	* Determines whether a value has the basic structure of an Explorer delta.
+	*
+	* @param data The value to inspect.
+	* @returns Whether the value has a string discriminator.
+	*/
+	static isExplorerDelta(data) {
+		return Array.isArray(data) && typeof data[0] === "string";
+	}
+	static recentEntries;
+	/**
+	* Loads or returns the cached recent entries list.
+	*
+	* Derives the list identifier and cipher key from the database secret
+	* and merges subsequent network responses into the loaded state.
+	*
+	* @returns The recent entries list.
+	* @throws {ExplorerError} If the database is not authenticated.
+	*/
+	static async loadRecentEntries() {
+		try {
+			if (!this.isAuthenticated) throw new ExplorerError("NOT_AUTHENTICATED");
+			if (this.recentEntries) return this.recentEntries;
+			const id = await Cryptographic.identifier.derive(this.databaseSecret, Bytes.utf8.decode("@sovereignbase/explorer:RecentEntriesID"), 32);
+			const ck = await Cryptographic.cipherMessage.deriveKey(this.databaseSecret, Bytes.utf8.decode("@sovereignbase/explorer:RecentEntriesCipherKey"));
+			const trustedSnapshot = await this.loadObjectByID(id, ck, (snapshot) => void this.recentEntries.merge(snapshot));
+			this.recentEntries = new RecentEntries(id, ck, 0, trustedSnapshot);
+			return this.recentEntries;
+		} catch (cause) {
+			throw unknownError(cause, "Explorer.loadRecentEntries()");
+		}
+	}
+	static credentialEntries;
+	/**
+	* Loads or returns the cached credential entries list.
+	*
+	* Derives the list identifier and cipher key from the database secret
+	* and merges subsequent network responses into the loaded state.
+	*
+	* @returns The credential entries list.
+	* @throws {ExplorerError} If the database is not authenticated.
+	*/
+	static async loadCredentialEntries() {
+		try {
+			if (!this.isAuthenticated) throw new ExplorerError("NOT_AUTHENTICATED");
+			if (this.credentialEntries) return this.credentialEntries;
+			const id = await Cryptographic.identifier.derive(this.databaseSecret, Bytes.utf8.decode("@sovereignbase/explorer:CredentialEntriesID"), 32);
+			const ck = await Cryptographic.cipherMessage.deriveKey(this.databaseSecret, Bytes.utf8.decode("@sovereignbase/explorer:CredentialEntriesCipherKey"));
+			const trustedSnapshot = await this.loadObjectByID(id, ck, (snapshot) => void this.credentialEntries.merge(snapshot));
+			this.credentialEntries = new CredentialEntries(id, ck, this.sessionCredential.id, 0, trustedSnapshot);
+			return this.credentialEntries;
+		} catch (cause) {
+			throw unknownError(cause, "Explorer.loadCredentialEntries()");
+		}
+	}
+};
+export { Explorer };
+
+//# sourceMappingURL=class.js.map