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

package/dist/lib/encrypted_maps.es.js

@@ -1,11 +1,11 @@
-import { T as h, E as f, D as g, a as v } from "./index-BUXhtQhx.mjs";
-import { A as m } from "./actor-4fotMNaR.mjs";
+import { T as v, E as f, D as g, a as m } from "./index-BUXhtQhx.mjs";
+import { A as w } from "./actor-CrGCNm9W.mjs";
 function y(r) {
   return new Promise((e, t) => {
     r.oncomplete = r.onsuccess = () => e(r.result), r.onabort = r.onerror = () => t(r.error);
   });
 }
-function w(r, e) {
+function h(r, e) {
   let t;
   const n = () => {
     if (t)
@@ -18,17 +18,54 @@ function w(r, e) {
   };
   return (a, i) => n().then((s) => i(s.transaction(e, a).objectStore(e)));
 }
-let u;
-function d() {
-  return u || (u = w("keyval-store", "keyval")), u;
+let _;
+function p() {
+  return _ || (_ = h("keyval-store", "keyval")), _;
 }
-function k(r, e = d()) {
+function k(r, e = p()) {
   return e("readonly", (t) => y(t.get(r)));
 }
-function E(r, e, t = d()) {
+function E(r, e, t = p()) {
   return t("readwrite", (n) => (n.put(e, r), y(n.transaction)));
 }
-const V = ({ IDL: r }) => {
+function V(r = p()) {
+  return r("readwrite", (e) => (e.clear(), y(e.transaction)));
+}
+class K {
+  #e = /* @__PURE__ */ new Map();
+  get(e) {
+    return Promise.resolve(this.#e.get(e));
+  }
+  set(e, t) {
+    return this.#e.set(e, t), Promise.resolve();
+  }
+  clear() {
+    return this.#e.clear(), Promise.resolve();
+  }
+}
+class C {
+  #e;
+  /**
+   * @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(e = "ic-vetkeys") {
+    this.#e = h(e, "derived-key-material");
+  }
+  async get(e) {
+    return k(e, this.#e);
+  }
+  async set(e, t) {
+    await E(e, t, this.#e);
+  }
+  async clear() {
+    await V(this.#e);
+  }
+}
+const A = ({ IDL: r }) => {
   const e = r.Record({ inner: r.Vec(r.Nat8) }), t = r.Variant({
     Read: r.Null,
     ReadWrite: r.Null,
@@ -47,7 +84,7 @@ const V = ({ IDL: r }) => {
   }), o = r.Variant({
     Ok: r.Opt(t),
     Err: r.Text
-  }), _ = r.Variant({ Ok: r.Vec(e), Err: r.Text });
+  }), u = r.Variant({ Ok: r.Vec(e), Err: r.Text });
   return r.Service({
     get_accessible_shared_map_names: r.Func(
       [],
@@ -112,7 +149,7 @@ const V = ({ IDL: r }) => {
       [a],
       []
     ),
-    remove_map_values: r.Func([r.Principal, e], [_], []),
+    remove_map_values: r.Func([r.Principal, e], [u], []),
     remove_user: r.Func(
       [r.Principal, e, r.Principal],
       [o],
@@ -125,10 +162,10 @@ const V = ({ IDL: r }) => {
     )
   });
 };
-class U {
+class R {
   actor;
   constructor(e, t) {
-    this.actor = m.createActor(V, {
+    this.actor = w.createActor(A, {
       agent: e,
       canisterId: t
     });
@@ -184,7 +221,7 @@ class U {
     return this.actor.remove_user(e, t, n);
   }
 }
-class F {
+class O {
   /**
    * The client instance for interacting with the EncryptedMaps canister.
    */
@@ -193,18 +230,44 @@ class F {
    * The cached verification key for validating encrypted VetKeys.
    */
   verificationKey = void 0;
+  /**
+   * Cache backing the per-map derived key material handles.
+   */
+  #e;
   /**
    * 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(e) {
-    this.canisterClient = e;
+  constructor(e, t) {
+    this.canisterClient = e, this.#e = t?.cache ?? new K();
   }
   /**
    * Retrieves a list of maps that were shared with the user and the user still has access to.
@@ -240,13 +303,13 @@ class F {
     for (const [n, a] of e) {
       const i = Uint8Array.from(n[1].inner), s = [];
       for (const [l, o] of a) {
-        const _ = Uint8Array.from(l.inner), p = await this.decryptFor(
+        const u = Uint8Array.from(l.inner), d = await this.decryptFor(
           n[0],
           i,
-          _,
+          u,
           Uint8Array.from(o.inner)
         );
-        s.push([_, p]);
+        s.push([u, d]);
       }
       t.push([
         [n[0], Uint8Array.from(n[1].inner)],
@@ -268,13 +331,13 @@ class F {
         s,
         l
       ] of n.keyvals) {
-        const o = Uint8Array.from(s.inner), _ = await this.decryptFor(
+        const o = Uint8Array.from(s.inner), u = await this.decryptFor(
           n.map_owner,
           a,
           o,
           Uint8Array.from(l.inner)
         );
-        i.push([o, _]);
+        i.push([o, u]);
       }
       t.push({
         accessControl: n.access_control,
@@ -342,13 +405,13 @@ class F {
       ]);
     const i = new Array();
     for (const [s, l] of n.Ok) {
-      const o = Uint8Array.from(s.inner), _ = await this.decryptFor(
+      const o = Uint8Array.from(s.inner), u = await this.decryptFor(
         e,
         t,
         o,
         Uint8Array.from(l.inner)
       );
-      i.push([o, _]);
+      i.push([o, u]);
     }
     return i;
   }
@@ -567,7 +630,7 @@ class F {
    * @throws Error if the operation fails
    */
   async getDerivedKeyMaterial(e, t) {
-    const n = h.random(), a = await this.canisterClient.get_encrypted_vetkey(
+    const n = v.random(), a = await this.canisterClient.get_encrypted_vetkey(
       e,
       c(t),
       c(n.publicKeyBytes())
@@ -579,10 +642,10 @@ class F {
         e.toUint8Array().length,
         ...e.toUint8Array(),
         ...t
-      ]), o = f.deserialize(i), _ = g.deserialize(s);
+      ]), o = f.deserialize(i), u = g.deserialize(s);
       return await o.decryptAndVerify(
         n,
-        _,
+        u,
         l
       ).asDerivedKeyMaterial();
     }
@@ -623,28 +686,50 @@ class F {
    * @returns Promise resolving to the derived key material
    */
   async getDerivedKeyMaterialOrFetchIfNeeded(e, t) {
-    const n = new Uint8Array(t), a = await k([
-      e.toString(),
-      n
-    ]);
+    const n = M(e, t), a = await this.#e.get(n);
     if (a)
-      return await v.fromCryptoKey(
+      return await m.fromCryptoKey(
         a
       );
     const i = await this.getDerivedKeyMaterial(
       e,
       t
     );
-    return await E(
-      [e.toString(), n],
+    return await this.#e.set(
+      n,
       i.getCryptoKey()
     ), i;
   }
+  /**
+   * 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.
+   */
+  async clearCache() {
+    await this.#e.clear();
+  }
+}
+function M(r, e) {
+  return `${r.toString()}|${F(e)}`;
+}
+function F(r) {
+  let e = "";
+  for (const t of r)
+    e += t.toString(16).padStart(2, "0");
+  return e;
 }
 function c(r) {
   return { inner: r };
 }
 export {
-  U as DefaultEncryptedMapsClient,
-  F as EncryptedMaps
+  R as DefaultEncryptedMapsClient,
+  O as EncryptedMaps,
+  K as InMemoryDerivedKeyMaterialCache,
+  C as IndexedDbDerivedKeyMaterialCache
 };

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 { A as h } from "./actor-CrGCNm9W.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.5.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,7 +57,7 @@
     "module": "dist/lib/index.es.js",
     "typings": "dist/types/index.d.ts",
     "dependencies": {
-        "@icp-sdk/core": "^5.2.1",
+        "@icp-sdk/core": "^5.4.0",
         "idb-keyval": "^6.2.1"
     },
     "devDependencies": {
@@ -77,7 +76,7 @@
         "typescript-eslint": "^8.59.0",
         "vite": "^7.0.8",
         "vite-plugin-dts": "^4.5.3",
-        "vitest": "^3.0.5"
+        "vitest": "^3.2.6"
     },
     "scripts": {
         "build": "tsc && vite build",