@sovereignbase/explorer 0.0.0-alpha.4 → 0.0.0-alpha.6

package/dist/class.js

@@ -18,7 +18,7 @@ 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 { accessDeviceBinding, createDeviceBinding, invalidateDeviceBinding } from "@sovereignbase/hardware-bound";
 import { Cryptographic } from "@sovereignbase/cryptosuite";
 import { Sequenced } from "@sovereignbase/sequenced";
 // src/.errors/class.ts
@@ -56,10 +56,11 @@ function unknownError(cause, operation) {
 }
 // src/CredentialEntries/class.ts
 /**
-* Maintains the database's credential entries.
+* Maintains the database's registered credentials.
 *
-* Entries are identified by credential ID and synchronized through
-* a sequenced array. Changes are persisted as encrypted snapshots.
+* Entries are identified by their object and credential identifiers.
+* Changes are synchronized through a sequenced array and persisted
+* as encrypted snapshots.
 */
 var CredentialEntries = class {
 	id;
@@ -73,7 +74,7 @@ var CredentialEntries = class {
 	*
 	* @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 sessionCredentialID The WebAuthn 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.
 	*/
@@ -99,13 +100,17 @@ var CredentialEntries = class {
 			this.state.addEventListener("change", ({ detail }) => {
 				this.dispatchEvent("change", detail);
 			});
-			const seen = /* @__PURE__ */ new Set();
+			const seenObjects = /* @__PURE__ */ new Set();
+			const seenCredentials = /* @__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);
+				if (seenObjects.has(entry.objectID) || seenCredentials.has(entry.credentialID)) duplicates.push(index);
+				else {
+					seenObjects.add(entry.objectID);
+					seenCredentials.add(entry.credentialID);
+				}
 			}
 			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();
@@ -126,17 +131,17 @@ var CredentialEntries = class {
 	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.");
+			const { objectID, credentialID, timestamp, userAgent, name, entropy, storage } = credentialEvent;
+			if (typeof objectID !== "string" || typeof timestamp !== "number" || !Number.isFinite(timestamp) || typeof userAgent !== "string") throw new ExplorerError("INVALID_CREDENTIAL_EVENT", "A credential event requires an object 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) {
+				if (entry?.objectID === objectID || credentialID !== void 0 && entry?.credentialID === credentialID) {
 					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.");
+			if (!existing && (typeof credentialID !== "string" || typeof name !== "string" || !(entropy instanceof Uint8Array) || typeof storage !== "string")) throw new ExplorerError("MISSING_CREDENTIAL_SETUP_PROPERTIES", "A new credential requires a credential ID, 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);
@@ -145,14 +150,18 @@ var CredentialEntries = class {
 				lastSeen: timestamp
 			});
 			const entry = {
-				id,
+				objectID,
+				credentialID: credentialID ?? existing.credentialID,
 				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);
+			for (let index = this.state.length - 1; index >= 0; index--) {
+				const current = this.state.at(index);
+				if (current?.objectID === entry.objectID || current?.credentialID === entry.credentialID) this.state.delete(index);
+			}
 			this.state.unshift(entry);
 			this.state.snapshot();
 		} catch (cause) {
@@ -160,24 +169,33 @@ var CredentialEntries = class {
 		}
 	}
 	/**
-	* Revokes a credential by deleting its persisted data and list entries.
+	* Revokes a credential and removes its registered entries.
 	*
-	* The list remains unchanged if deletion of the persisted credential fails.
+	* Deletes the credential's persisted objects before removing its entries.
+	* The entries remain unchanged if deletion fails. Credential invalidation
+	* is requested on a best-effort basis after successful removal.
 	*
-	* @param credentialID The identifier of the credential to revoke.
+	* @param credentialID The WebAuthn credential identifier to revoke.
 	*/
 	async revoke(credentialID) {
 		try {
-			let exists = false;
+			const objectIDs = /* @__PURE__ */ new Set();
 			for (let index = this.state.length - 1; index >= 0; index--) {
-				if (this.state.at(index)?.id !== credentialID) continue;
-				exists = true;
-				break;
+				const entry = this.state.at(index);
+				if (entry?.credentialID === credentialID) objectIDs.add(entry.objectID);
 			}
-			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();
+			if (objectIDs.size === 0) return;
+			for (const objectID of objectIDs) await Explorer.deleteObjectByID(objectID);
+			let removed = false;
+			for (let index = this.state.length - 1; index >= 0; index--) if (this.state.at(index)?.credentialID === credentialID) {
+				this.state.delete(index);
+				removed = true;
+			}
+			if (removed) this.state.snapshot();
+			try {
+				await invalidateDeviceBinding(credentialID);
+			} catch {}
+			if (credentialID === this.sessionCredentialID) window.location.reload();
 		} catch (cause) {
 			throw unknownError(cause, "CredentialEntries.revoke()");
 		}
@@ -185,11 +203,11 @@ var CredentialEntries = class {
 	/**
 	* Returns the credential entries ordered by most recent use.
 	*
-	* Entries with equal timestamps are ordered by identifier.
+	* Entries with equal timestamps are ordered by credential identifier.
 	*/
 	list() {
 		try {
-			return this.state.slice().sort((a, b) => b.lastUsed - a.lastUsed || a.id.localeCompare(b.id));
+			return this.state.slice().sort((a, b) => b.lastUsed - a.lastUsed || a.credentialID.localeCompare(b.credentialID));
 		} catch (cause) {
 			throw unknownError(cause, "CredentialEntries.list()");
 		}
@@ -438,20 +456,27 @@ var RecentEntries = class {
 };
 // src/class.ts
 /**
-* Provides authentication, encrypted object storage, and access to
-* the database's synchronized entries.
+* Provides access to an authenticated Sovereignbase database.
 *
-* Maintains the authenticated database context and exposes static methods
-* for managing stored objects, observing entries, and applying remote deltas.
+* Manages database authentication, encrypted object storage, credential
+* registration, database linking, and synchronized entries.
 */
 var Explorer = class {
 	/** The identifier of the authenticated database. */
 	static databaseID;
-	/** Indicates whether the database has been authenticated. */
+	/** Indicates whether a database has been authenticated. */
 	static isAuthenticated;
+	/** The base URL used to access database objects. */
 	static storageURL;
+	/** The event target used for Explorer events. */
 	static eventTarget;
+	/** The data PIN associated with the current session. */
+	static dataPIN;
+	/** The virtual entropy associated with the authenticated database. */
+	static virtualEntropy;
+	/** The secret used to access the authenticated database. */
 	static databaseSecret;
+	/** The credential information associated with the current authentication. */
 	static sessionCredential = {};
 	/**
 	* Caches cipher keys by object identifier.
@@ -461,46 +486,50 @@ var Explorer = class {
 	*/
 	static cipherKeyCache = /* @__PURE__ */ new Map();
 	/**
-	* Authenticates a database using a data PIN and device-bound entropy.
+	* Authenticates a database using a data PIN and an existing device binding.
+	*
+	* Establishes the authenticated database context and records the credential
+	* used for authentication.
 	*
-	* 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.
+	* When setup parameters are provided, registers a credential using the
+	* supplied virtual entropy or generates new virtual entropy.
 	*
-	* Records the authenticated credential in the database's credential list.
+	* @param dataPIN The PIN associated with the database.
+	* @param storageURL The base URL used to access database objects.
+	* @param setupParams Optional parameters for registering a credential.
 	*
-	* @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.
+	* @param credentialId An optional credential identifier used to restrict credential selection.
 	* @returns The authentication result.
 	*/
-	static async authenticate(dataPIN, storageURL, setupParams) {
+	static async authenticate(dataPIN, storageURL, setupParams, credentialId) {
 		try {
+			this.dataPIN = dataPIN;
 			this.storageURL = storageURL;
-			const deviceEntropy = await deriveDeviceEntropy();
-			if (!deviceEntropy) return "authenticator-error";
+			const deviceBinding = await accessDeviceBinding(credentialId);
+			if (!Array.isArray(deviceBinding)) return "authenticator-error";
+			const [credentialID, deviceEntropy] = deviceBinding;
 			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 credentialObjectID = await Cryptographic.identifier.derive(credentialSecret, Bytes.utf8.decode("@sovereignbase/explorer:CredentialObjectID"), 32);
+			this.sessionCredential.objectID = credentialObjectID;
+			this.sessionCredential.credentialID = 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.virtualEntropy = setupParams.virtualEntropy instanceof Uint8Array ? setupParams.virtualEntropy : Bytes.generate(64);
+				await this.storeObjectByID(credentialObjectID, this.virtualEntropy, credentialCipherKey);
 				this.sessionCredential.name = setupParams.credentialName;
 				this.sessionCredential.entropy = deviceEntropy;
 				this.sessionCredential.storage = setupParams.bindingStorage;
 			} else {
-				const result = await this.loadObjectByID(credentialID, credentialCipherKey);
+				const result = await this.loadObjectByID(credentialObjectID, credentialCipherKey);
 				if (!(result instanceof Uint8Array) || result.byteLength !== 64) return "invalid-data-pin";
-				virtualEntropy = result;
+				this.virtualEntropy = result;
 			}
-			this.databaseSecret = await Bytes.derive(virtualEntropy, dataPINBytes, 64);
+			this.databaseSecret = await Bytes.derive(this.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);
@@ -511,10 +540,71 @@ var Explorer = class {
 			throw unknownError(cause, "Explorer.authenticate()");
 		}
 	}
+	/** The number of consecutive failed database linking PIN attempts. */
+	static failCounter = 0;
 	/**
-	* Permanently revokes a credential and deletes its persisted data.
+	* Prepares an authenticated database for linking to another device.
 	*
-	* Removes the credential from the database's registered credentials.
+	* Verifies the current data PIN and prepares an encrypted transfer
+	* containing the information required to access the same database.
+	*
+	* Repeated PIN failures cause the current page to reload.
+	*
+	* @param dataPIN The PIN associated with the authenticated database.
+	* @param encapsulateKey The key used to establish encryption for the transfer.
+	* @returns The key offer and encrypted transfer message, or `false`
+	* if the supplied PIN is incorrect.
+	*/
+	static async prepareDatabaseLink(dataPIN, encapsulateKey) {
+		try {
+			if (!this.isAuthenticated) throw new ExplorerError("NOT_AUTHENTICATED");
+			if (dataPIN !== this.dataPIN) {
+				if (this.failCounter >= 2) window.location.reload();
+				this.failCounter++;
+				return false;
+			}
+			this.failCounter = 0;
+			const { keyOffer, cipherKey } = await Cryptographic.keyAgreement.encapsulate(encapsulateKey);
+			return [keyOffer, await Cryptographic.cipherMessage.encrypt(cipherKey, Bytes.concat([this.virtualEntropy, Bytes.utf8.decode(dataPIN)]))];
+		} catch (cause) {
+			throw unknownError(cause, "Explorer.prepareDatabaseLink()");
+		}
+	}
+	/**
+	* Links the current device to an existing database.
+	*
+	* Accesses the transferred database information, creates a device binding,
+	* and registers a credential for the existing database.
+	*
+	* @param keyOffer The key offer associated with the database link.
+	* @param cipherMessage The encrypted database linking message.
+	* @param decapsulateKey The key used to establish decryption for the transfer.
+	* @param credentialName The display name assigned to the new credential.
+	* @param storageURL The base URL used to access database objects.
+	* @returns `true` if the database was linked and authenticated;
+	* otherwise, `false`.
+	*/
+	static async linkToDatabase(keyOffer, cipherMessage, decapsulateKey, credentialName, storageURL) {
+		try {
+			const { cipherKey } = await Cryptographic.keyAgreement.decapsulate(keyOffer, decapsulateKey);
+			const raw = await Cryptographic.cipherMessage.decrypt(cipherKey, cipherMessage);
+			const setupResult = await createDeviceBinding(credentialName);
+			if (!Array.isArray(setupResult)) return false;
+			const [credentialId, bindingStorage] = setupResult;
+			return await this.authenticate(Bytes.utf8.encode(raw.slice(64)), storageURL, {
+				credentialName,
+				virtualEntropy: raw.slice(0, 64),
+				bindingStorage
+			}, credentialId) === "authenticated" ? true : false;
+		} catch (cause) {
+			throw unknownError(cause, "Explorer.linkToDatabase()");
+		}
+	}
+	/**
+	* Permanently revokes a registered database credential.
+	*
+	* Removes the credential's persisted data and registration from
+	* the authenticated database.
 	*
 	* @param credentialID The identifier of the credential to revoke.
 	* @throws {ExplorerError} If the database is not authenticated.
@@ -528,15 +618,14 @@ var Explorer = class {
 		}
 	}
 	/**
-	* Returns the registered credentials and optionally observes their changes.
+	* Returns the registered database credentials.
 	*
-	* 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.
+	* Optionally registers a listener for changes to the credential entries.
+	* The returned cleanup function removes the registered listener.
 	*
 	* @param onChange An optional callback invoked when the entries change.
-	* @returns The cleanup function, credential entries, and session credential ID.
+	* @returns The cleanup function, credential entries, and identifier
+	* of the current session's credential.
 	* @throws {ExplorerError} If the database is not authenticated.
 	*/
 	static async listCredentialEntries(onChange) {
@@ -556,11 +645,10 @@ var Explorer = class {
 		}
 	}
 	/**
-	* Returns the recently accessed objects and optionally observes their changes.
+	* Returns the recently accessed database objects.
 	*
-	* The returned tuple contains a cleanup function and the current recent
-	* entries. The cleanup function removes the registered change listener,
-	* if any.
+	* Optionally registers a listener for changes to the recent entries.
+	* The returned cleanup function removes the registered listener.
 	*
 	* @param onChange An optional callback invoked when the entries change.
 	* @returns The cleanup function and recent entries.
@@ -579,9 +667,9 @@ var Explorer = class {
 		}
 	}
 	/**
-	* Loads an encrypted object using its identifier and cipher key.
+	* Loads an encrypted database object by its identifier.
 	*
-	* Caches the cipher key if the identifier has not been encountered before.
+	* Caches the supplied cipher key if no key has been cached for the object.
 	*
 	* @typeParam T The expected type of the loaded object.
 	* @param id The identifier of the object to load.
@@ -598,9 +686,9 @@ var Explorer = class {
 		}
 	}
 	/**
-	* Encrypts and stores an object using its identifier and cipher key.
+	* Encrypts and stores a database object by its identifier.
 	*
-	* Caches the cipher key if the identifier has not been encountered before.
+	* Caches the supplied cipher key if no key has been cached for the object.
 	*
 	* @typeParam T The type of the object to store.
 	* @param id The identifier of the object to store.
@@ -617,7 +705,9 @@ var Explorer = class {
 		}
 	}
 	/**
-	* Deletes a persisted object using its identifier.
+	* Deletes a database object by its identifier.
+	*
+	* Removes the persisted object and its corresponding recent entry.
 	*
 	* @param id The identifier of the object to delete.
 	*/
@@ -657,8 +747,9 @@ var Explorer = class {
 		});
 	}
 	/**
-	* Registers an event listener for the specified event type.
+	* Registers an event listener for the specified Explorer event.
 	*
+	* @typeParam K The event name that determines the event detail type.
 	* @param type The event type.
 	* @param listener The event listener, or `null`.
 	* @param options The event listener options.
@@ -674,6 +765,7 @@ var Explorer = class {
 	* Removes an event listener previously registered with
 	* {@link addEventListener}.
 	*
+	* @typeParam K The event name that determines the listener type.
 	* @param type The event type.
 	* @param listener The event listener to remove, or `null`.
 	* @param options The event listener options.
@@ -686,8 +778,9 @@ var Explorer = class {
 		}
 	}
 	/**
-	* Dispatches an event to the registered listeners.
+	* Dispatches an Explorer event to registered listeners.
 	*
+	* @typeParam K The event name that determines the event detail type.
 	* @param type The event type.
 	* @param detail The value exposed through `CustomEvent.detail`.
 	*/
@@ -707,6 +800,7 @@ var Explorer = class {
 	static isExplorerDelta(data) {
 		return Array.isArray(data) && typeof data[0] === "string";
 	}
+	/** The cached recent entries list. */
 	static recentEntries;
 	/**
 	* Loads or returns the cached recent entries list.
@@ -730,6 +824,7 @@ var Explorer = class {
 			throw unknownError(cause, "Explorer.loadRecentEntries()");
 		}
 	}
+	/** The cached credential entries list. */
 	static credentialEntries;
 	/**
 	* Loads or returns the cached credential entries list.
@@ -747,13 +842,13 @@ var Explorer = class {
 			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);
+			this.credentialEntries = new CredentialEntries(id, ck, this.sessionCredential.credentialID, 0, trustedSnapshot);
 			return this.credentialEntries;
 		} catch (cause) {
 			throw unknownError(cause, "Explorer.loadCredentialEntries()");
 		}
 	}
 };
-export { Explorer };
+export { Explorer, ExplorerError };
 
 //# sourceMappingURL=class.js.map