@icp-sdk/vetkeys 0.5.0-beta.0 → 0.6.0

package/dist/lib/key_manager.es.js

@@ -1,5 +1,5 @@
-import { T as u, D as _, E as l } from "./index-BUXhtQhx.mjs";
-import { A as h } from "./actor-4fotMNaR.mjs";
+import { TransportSecretKey as u, DerivedPublicKey as _, EncryptedVetKey as l } from "./index.es.js";
+import { A as h } from "./actor-CFYb2LZx.mjs";
 const g = ({ IDL: e }) => {
   const r = e.Record({ inner: e.Vec(e.Nat8) }), t = e.Variant({ Ok: r, Err: e.Text }), s = e.Variant({
     Read: e.Null,

package/dist/types/encrypted_maps/cache.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @module @icp-sdk/vetkeys/encrypted_maps
+ *
+ * @description Caching strategies for derived key material. See
+ * {@link DerivedKeyMaterialCache}.
+ */
+/**
+ * Strategy for caching the per-map derived key material handles used by
+ * {@link EncryptedMaps}.
+ *
+ * Deriving key material requires a canister round-trip and threshold
+ * cryptography, so it is cached and reused. The cached value is a
+ * non-extractable {@link CryptoKey} handle: its raw bytes can never be read
+ * back (`crypto.subtle.exportKey` throws), but the handle can still be *used*
+ * to decrypt. Where that handle lives therefore matters for security — see the
+ * provided implementations.
+ *
+ * Cache entries are keyed by an opaque string derived from the map owner and
+ * map name. Derived key material is per map, not per caller, so the key does
+ * not encode the identity. Isolating one identity's cached keys from another's
+ * on the same origin is therefore a property of the cache instance: use a fresh
+ * cache per identity (the in-memory default is naturally per-instance), or give
+ * a persistent cache a per-identity namespace (see
+ * {@link IndexedDbDerivedKeyMaterialCache}).
+ */
+export interface DerivedKeyMaterialCache {
+    /**
+     * Returns the cached key handle for the given key, or `undefined` on a miss.
+     */
+    get(key: string): Promise<CryptoKey | undefined>;
+    /**
+     * Stores a key handle under the given key.
+     */
+    set(key: string, value: CryptoKey): Promise<void>;
+    /**
+     * Removes every cached key handle.
+     *
+     * Call this on logout or whenever the authenticated identity changes to
+     * avoid leaving usable decryption capability behind.
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Default {@link DerivedKeyMaterialCache} that keeps key handles in memory only.
+ *
+ * Nothing is written to disk, so the cache is discarded when the page is
+ * reloaded or the tab is closed and there is no at-rest exposure. The trade-off
+ * is one extra key derivation per map per page load.
+ */
+export declare class InMemoryDerivedKeyMaterialCache implements DerivedKeyMaterialCache {
+    #private;
+    get(key: string): Promise<CryptoKey | undefined>;
+    set(key: string, value: CryptoKey): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Opt-in {@link DerivedKeyMaterialCache} that persists key handles in IndexedDB.
+ *
+ * Key handles survive page reloads, avoiding repeated key derivation, but this
+ * is a deliberate security trade-off: the persisted handle is non-extractable
+ * (its raw bytes cannot be stolen), yet any same-origin code — e.g. via XSS, a
+ * malicious extension, or a shared browser profile — can read the handle and
+ * use it to decrypt the user's data without an authenticated session, for as
+ * long as it remains stored.
+ *
+ * Prefer {@link InMemoryDerivedKeyMaterialCache} (the default) unless you need
+ * cross-reload persistence and accept this exposure. When using this cache, be
+ * sure to call {@link EncryptedMaps.clearCache} on logout or identity change.
+ *
+ * Because the cache key does not encode the identity, **give the store a
+ * per-identity namespace** to keep one identity's persisted keys from being
+ * served to another on the same origin — e.g. include the caller's principal in
+ * the database name:
+ *
+ * ```ts
+ * new IndexedDbDerivedKeyMaterialCache(`vetkeys-${principal}`);
+ * ```
+ *
+ * A dedicated IndexedDB store is used, so {@link clear} only removes entries
+ * written by this cache and never touches other application data.
+ */
+export declare class IndexedDbDerivedKeyMaterialCache implements DerivedKeyMaterialCache {
+    #private;
+    /**
+     * @param dbName - IndexedDB database name. Defaults to `"ic-vetkeys"`. This
+     *   is the isolation knob: give each identity its own database name (e.g.
+     *   `` `vetkeys-${principal}` ``) so one identity's persisted keys are never
+     *   served to another. The object store name is fixed, because `idb-keyval`
+     *   supports only a single object store per database.
+     */
+    constructor(dbName?: string);
+    get(key: string): Promise<CryptoKey | undefined>;
+    set(key: string, value: CryptoKey): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/types/encrypted_maps/cache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/encrypted_maps/index.d.ts

@@ -1,7 +1,9 @@
 import { Principal } from '@icp-sdk/core/principal';
 import { DerivedKeyMaterial } from '../utils/utils';
+import { DerivedKeyMaterialCache } from './cache';
 import { AccessRights, ByteBuf } from '../declarations/ic_vetkeys_manager_canister/ic_vetkeys_manager_canister.did.js';
 export { DefaultEncryptedMapsClient } from './encrypted_maps_canister';
+export { type DerivedKeyMaterialCache, InMemoryDerivedKeyMaterialCache, IndexedDbDerivedKeyMaterialCache, } from './cache';
 export type { AccessRights, ByteBuf, } from '../declarations/ic_vetkeys_manager_canister/ic_vetkeys_manager_canister.did.js';
 /**
  * The **EncryptedMaps** frontend library facilitates interaction with an [**EncryptedMaps-enabled canister**](https://docs.rs/ic-vetkeys/latest/ic_vetkeys/encrypted_maps/struct.EncryptedMaps.html) on the **Internet Computer (ICP)**.
@@ -19,9 +21,23 @@ export type { AccessRights, ByteBuf, } from '../declarations/ic_vetkeys_manager_
  *
  * - **Access Rights** should be carefully managed to prevent unauthorized access.
  * - VetKeys should be decrypted **only in trusted environments** such as user browsers to prevent leaks.
+ * - Derived key material is cached **in memory by default** ({@link InMemoryDerivedKeyMaterialCache}),
+ *   so it never touches disk and is discarded on page reload. Persisting it across
+ *   reloads with {@link IndexedDbDerivedKeyMaterialCache} is an explicit, opt-in trade-off:
+ *   the persisted handle is non-extractable, but any same-origin code can use it to decrypt
+ *   without an authenticated session for as long as it is stored.
+ * - The cache belongs to a single authenticated identity. Identity lifecycle is the
+ *   caller's responsibility, so to avoid serving one identity's key material to another
+ *   on the same origin:
+ *   - with the in-memory default, use a **fresh `EncryptedMaps` instance per identity**
+ *     (or call {@link EncryptedMaps.clearCache} on logout / identity change);
+ *   - with {@link IndexedDbDerivedKeyMaterialCache}, give the store a **per-identity
+ *     namespace** (e.g. include the caller's principal in the database name) so entries
+ *     are physically separated, and call {@link EncryptedMaps.clearCache} on logout.
  *
  */
 export declare class EncryptedMaps {
+    #private;
     /**
      * The client instance for interacting with the EncryptedMaps canister.
      */
@@ -33,14 +49,38 @@ export declare class EncryptedMaps {
     /**
      * Creates a new instance of the EncryptedMaps client.
      *
+     * @param canisterClient - The client used to talk to the EncryptedMaps canister.
+     * @param options - Optional configuration.
+     * @param options.cache - Strategy for caching derived key material. Defaults to
+     *   {@link InMemoryDerivedKeyMaterialCache} (in-memory only, never persisted).
+     *   Pass {@link IndexedDbDerivedKeyMaterialCache} to persist across page reloads —
+     *   see the security note in the class description.
+     *
      * @example
      * ```ts
      * import { EncryptedMaps } from "@icp-sdk/vetkeys/encrypted_maps";
      *
      * const encryptedMaps = new EncryptedMaps(encryptedMapsClientInstance);
      * ```
+     *
+     * @example Opt into persistent caching, namespaced per identity
+     * ```ts
+     * import {
+     *     EncryptedMaps,
+     *     IndexedDbDerivedKeyMaterialCache,
+     * } from "@icp-sdk/vetkeys/encrypted_maps";
+     *
+     * const encryptedMaps = new EncryptedMaps(encryptedMapsClientInstance, {
+     *     // Namespace the store per identity so one identity's cached keys are
+     *     // never served to another on the same origin.
+     *     cache: new IndexedDbDerivedKeyMaterialCache(`vetkeys-${myPrincipal}`),
+     * });
+     * // Remember to call encryptedMaps.clearCache() on logout / identity change.
+     * ```
      */
-    constructor(canisterClient: EncryptedMapsClient);
+    constructor(canisterClient: EncryptedMapsClient, options?: {
+        cache?: DerivedKeyMaterialCache;
+    });
     /**
      * Retrieves a list of maps that were shared with the user and the user still has access to.
      *
@@ -255,6 +295,18 @@ export declare class EncryptedMaps {
      * @returns Promise resolving to the derived key material
      */
     getDerivedKeyMaterialOrFetchIfNeeded(mapOwner: Principal, mapName: Uint8Array): Promise<DerivedKeyMaterial>;
+    /**
+     * Clears all cached derived key material.
+     *
+     * Strongly recommended on logout or whenever the authenticated identity
+     * changes: the cache belongs to a single identity, so clearing it (or
+     * discarding the `EncryptedMaps` instance) prevents one identity's key
+     * material from being served to another, and drops the still-usable
+     * decryption capability that otherwise lingers. This matters most with
+     * {@link IndexedDbDerivedKeyMaterialCache}, where cached key handles persist
+     * across sessions until cleared.
+     */
+    clearCache(): Promise<void>;
 }
 /**
  * Interface for map data structure.

package/package.json

@@ -1,7 +1,6 @@
 {
     "name": "@icp-sdk/vetkeys",
-    "version": "0.5.0-beta.0",
-    "packageManager": "pnpm@10.10.0",
+    "version": "0.6.0",
     "author": "DFINITY Stiftung",
     "description": "JavaScript and TypeScript library to use Internet Computer vetKeys",
     "homepage": "https://internetcomputer.org/docs/building-apps/network-features/vetkeys/introduction",
@@ -58,26 +57,26 @@
     "module": "dist/lib/index.es.js",
     "typings": "dist/types/index.d.ts",
     "dependencies": {
-        "@icp-sdk/core": "^5.2.1",
-        "idb-keyval": "^6.2.1"
+        "@icp-sdk/core": "^6.1.0",
+        "idb-keyval": "^6.3.0"
     },
     "devDependencies": {
+        "@eslint/js": "^9.39.5",
         "@noble/curves": "^1.9.7",
         "@noble/hashes": "^1.8.0",
-        "@eslint/js": "^9.22.0",
-        "@types/node": "^24.0.4",
-        "@vitest/coverage-v8": "^3.0.5",
-        "eslint": "^9.22",
-        "eslint-config-prettier": "^10.1.5",
-        "eslint-plugin-prettier": "^5.2.6",
-        "fake-indexeddb": "^6.0.0",
-        "prettier": "^3.5.3",
-        "typedoc": "^0.28.3",
+        "@types/node": "^24.13.3",
+        "@vitest/coverage-v8": "^3.2.7",
+        "eslint": "^9.39.5",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-plugin-prettier": "^5.5.6",
+        "fake-indexeddb": "^6.2.5",
+        "prettier": "^3.9.6",
+        "typedoc": "^0.28.20",
         "typescript": "^5.9.3",
-        "typescript-eslint": "^8.59.0",
-        "vite": "^7.0.8",
-        "vite-plugin-dts": "^4.5.3",
-        "vitest": "^3.0.5"
+        "typescript-eslint": "^8.68.0",
+        "vite": "^7.3.6",
+        "vite-plugin-dts": "^4.5.4",
+        "vitest": "^3.2.7"
     },
     "scripts": {
         "build": "tsc && vite build",