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

package/dist/class.d.ts

@@ -0,0 +1,274 @@
+
+import { URLString } from "@sovereignbase/storage";
+import { DeepReadonly } from "@sovereignbase/utils";
+import { DeviceBindingStorage } from "@sovereignbase/hardware-bound";
+import { CipherKey } from "@sovereignbase/cryptosuite";
+import { SequencedArrayChange, SequencedArrayDelta } from "@sovereignbase/sequenced";
+/**
+ * Describes an entry in the recent objects list.
+ */
+type RecentEntry = {
+  /** The identifier of the referenced object. */
+  id: string;
+  /** The display name of the referenced object. */
+  name: string;
+  /** The cipher key used to access the referenced object. */
+  cipherKey: CipherKey;
+  /** The date and time at which the object was most recently accessed. */
+  dateAccessed: number;
+};
+/**
+ * Represents a sequenced delta produced by the recent entries list.
+ */
+type RecentEntriesDelta = Readonly<['recentEntries', DeepReadonly<SequencedArrayDelta<RecentEntry>>]>;
+/**
+ * Represents a sequenced change produced by the recent entries list.
+ */
+type RecentEntriesChange = DeepReadonly<SequencedArrayChange<RecentEntry>>;
+/**
+ * Describes a credential registered with the database.
+ */
+type CredentialEntry = {
+  /** The identifier of the credential. */
+  id: string;
+  /** The display name of the credential. */
+  name: string;
+  /** The entropy associated with the credential. */
+  entropy: Uint8Array;
+  /** The storage mechanism used for device binding. */
+  storage: DeviceBindingStorage;
+  /** The timestamp of the most recent use of the credential. */
+  lastUsed: number;
+  /** The user agents that have used the credential. */
+  userAgents: Array<{
+    /** The user agent string. */
+    name: string;
+    /** The timestamp of the most recent use by the user agent. */
+    lastSeen: number;
+  }>;
+};
+/**
+ * Represents a sequenced delta produced by the credential entries list.
+ */
+type CredentialEntriesDelta = Readonly<['credentialEntries', DeepReadonly<SequencedArrayDelta<CredentialEntry>>]>;
+/**
+ * Represents a sequenced change produced by the credential entries list.
+ */
+type CredentialEntriesChange = DeepReadonly<SequencedArrayChange<CredentialEntry>>;
+/**
+ * Represents the outcome of a database authentication attempt.
+ */
+type AuthenticationResult =
+/** The database was successfully authenticated. */
+'authenticated' |
+/** The device authenticator could not provide the required entropy. */
+'authenticator-error' |
+/** The supplied data PIN could not unlock the credential. */
+'invalid-data-pin';
+/**
+ * Describes the parameters used to register a new database credential.
+ */
+type AuthenticationSetupParams = Readonly<{
+  /** The display name assigned to the credential. */
+  credentialName: string;
+  /** The storage mechanism used to bind the credential to the device. */
+  bindingStorage: DeviceBindingStorage;
+}>;
+/**
+ * Represents a synchronized delta exchanged between Explorer instances.
+ *
+ * Includes changes to recent and credential entries, as well as
+ * a reserved variant for other delta types.
+ */
+type ExplorerDelta = RecentEntriesDelta | CredentialEntriesDelta | ['other' | []];
+/**
+ * Maps Explorer event names to their detail types.
+ */
+type ExplorerEventMap = {
+  /** Fired when the database authentication state changes. */
+  authenticated: boolean;
+  /** Fired when a synchronized delta is produced. */
+  delta: ExplorerDelta;
+};
+/**
+ * Represents an event listener for an {@link Explorer} event.
+ *
+ * @typeParam K The event name that determines the event detail type.
+ */
+type ExplorerEventListener<K extends keyof ExplorerEventMap> = ((event: CustomEvent<ExplorerEventMap[K]>) => void) | {
+  handleEvent(event: CustomEvent<ExplorerEventMap[K]>): void;
+};
+/**
+ * Resolves an event name to its corresponding listener type.
+ *
+ * @typeParam K The event name to resolve.
+ */
+type ExplorerEventListenerFor<K extends string> = K extends keyof ExplorerEventMap ? ExplorerEventListener<K> : EventListenerOrEventListenerObject;
+/**
+ * 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.
+ */
+export declare class Explorer {
+  /** The identifier of the authenticated database. */
+  static databaseID: string;
+  /** Indicates whether the database has been authenticated. */
+  static isAuthenticated: boolean;
+  private static storageURL;
+  private static eventTarget?;
+  private static databaseSecret;
+  private static sessionCredential?;
+  /**
+   * Caches cipher keys by object identifier.
+   *
+   * Existing entries are preserved when an object is accessed with
+   * a cipher key.
+   */
+  static readonly cipherKeyCache: Map<string, CipherKey>;
+  /**
+   * 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 authenticate(dataPIN: string, storageURL: URLString, setupParams?: AuthenticationSetupParams): Promise<AuthenticationResult>;
+  /**
+   * 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 permanentlyDeleteCredential(credentialID: string): Promise<void>;
+  /**
+   * 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 listCredentialEntries(onChange?: (splice: CredentialEntriesChange) => void): Promise<[cleanup: () => void, entries: DeepReadonly<Array<CredentialEntry>>, sessionCredentialID: string]>;
+  /**
+   * 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 listRecentEntries(onChange?: (splice: RecentEntriesChange) => void): Promise<[cleanup: () => void, entries: DeepReadonly<Array<RecentEntry>>]>;
+  /**
+   * 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 loadObjectByID<T>(id: string, cipherKey: CipherKey, onNetworkResponse?: (data: unknown) => void | Promise<void>): Promise<T | undefined>;
+  /**
+   * 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 storeObjectByID<T>(id: string, object: T, cipherKey: CipherKey): Promise<void>;
+  /**
+   * Deletes a persisted object using its identifier.
+   *
+   * @param id The identifier of the object to delete.
+   */
+  static deleteObjectByID(id: string): Promise<void>;
+  /**
+   * 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: unknown): void;
+  /**
+   * 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<K extends keyof ExplorerEventMap>(type: K, listener: ExplorerEventListenerFor<K> | null, options?: boolean | AddEventListenerOptions): void;
+  /**
+   * 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<K extends keyof ExplorerEventMap>(type: K, listener: ExplorerEventListenerFor<K> | null, options?: boolean | EventListenerOptions): void;
+  /**
+   * Dispatches an event to the registered listeners.
+   *
+   * @param type The event type.
+   * @param detail The value exposed through `CustomEvent.detail`.
+   */
+  static dispatchEvent<K extends keyof ExplorerEventMap>(type: K, detail: ExplorerEventMap[K]): void;
+  /**
+   * 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.
+   */
+  private static isExplorerDelta;
+  private 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.
+   */
+  private static loadRecentEntries;
+  private 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.
+   */
+  private static loadCredentialEntries;
+}
+export {};
+//# sourceMappingURL=class.d.ts.map

package/dist/class.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"class.d.ts","names":[],"sources":["../src/RecentEntries/class.ts","../src/CredentialEntries/class.ts","../src/.types/type.ts","../src/class.ts"],"mappings":";;;;;;;;;KAsBY;;EAEV;;EAGA;;EAGA,WAAW;;EAGX;;;;;KAMU,qBAAqB,2BACb,aAAa,oBAAoB;;;;KAMzC,sBAAsB,aAChC,qBAAqB;;;;KCvBX;;EAEV;;EAGA;;EAGA,SAAS;;EAGT,SAAS;;EAGT;;EAGA,YAAY;;IAEV;;IAGA;;;;;;KAiCQ,yBAAyB,+BACb,aAAa,oBAAoB;;;;KAM7C,0BAA0B,aACpC,qBAAqB;;;;KChFX;;;;;;;;;;KAWA,4BAA4B;;EAEtC;;EAGA,gBAAgB;;;;;;;;KASN,gBACV,qBAAqB;;;;KAKX;;EAEV;;EAGA,OAAO;;;;;;;KAQG,sBAAsB,gBAAgB,sBAC5C,OAAO,YAAY,iBAAiB;EACpC,YAAY,OAAO,YAAY,iBAAiB;;;;;;;KAO1C,yBAAyB,oBACnC,gBAAgB,mBACZ,sBAAsB,KACtB;;;;;;;;qBClBO;;SAEG;;SAGA;iBAGC;iBACA;iBACA;iBACA;;;;;;;kBAQQ,gBAAgB,YAAY;;;;;;;;;;;;;;;SAgB/B,aAClB,iBACA,YAAY,WACZ,cAAc,4BACb,QAAQ;;;;;;;;;SA0FS,4BAClB,uBACC;;;;;;;;;;;;;SAsBiB,sBAClB,YAAY,QAAQ,mCACnB,SAEC,qBACA,SAAS,aAAa,MAAM,mBAC5B;;;;;;;;;;;;SAoCgB,kBAClB,YAAY,QAAQ,+BACnB,SAAS,qBAAqB,SAAS,aAAa,MAAM;;;;;;;;;;;;SAgCzC,eAAe,GACjC,YACA,WAAW,WACX,qBAAqB,yBAAyB,gBAC7C,QAAQ;;;;;;;;;;;SA0BS,gBAAgB,GAClC,YACA,QAAQ,GACR,WAAW,YACV;;;;;;SAoBiB,iBAAiB,aAAa;;;;;;;;;;;SAmBpC,MAAM;;;;;;;;SAmCN,iBAAiB,gBAAgB,kBAC7C,MAAM,GACN,UAAU,yBAAyB,WACnC,oBAAoB;;;;;;;;;SAqBR,oBAAoB,gBAAgB,kBAChD,MAAM,GACN,UAAU,yBAAyB,WACnC,oBAAoB;;;;;;;SAmBR,cAAc,gBAAgB,kBAC1C,MAAM,GACN,QAAQ,iBAAiB;;;;;;;iBAsBZ;iBAIA;;;;;;;;;;iBAWM;iBA8BN;;;;;;;;;;iBAWM"}