fix(encrypted_maps): harden derived key material caching

[marc0olo]

Context

A Zeropath security review flagged that the EncryptedMaps frontend SDK persisted per-map derived key material (a non-extractable WebCrypto CryptoKey) in IndexedDB indefinitely, in a fixed store keyed only by [mapOwner, mapName].

Security assessment

The finding is valid, with nuance:

• The cached CryptoKey is non-extractable, so an attacker cannot exfiltrate the raw key bytes (crypto.subtle.exportKey throws). Storing a non-extractable key in IndexedDB is itself the WebCrypto-recommended pattern.
• But the risk is real: any same-origin code (XSS, malicious extension, shared browser profile) can use the persisted handle in place to decrypt and exfiltrate plaintext, with no authenticated session. The exposure is data compromise, not key theft.
• Two distinct problems:
  1. At-rest persistence with no expiry / no clear on logout — persisted indefinitely, extending the window for later/offline compromise. (This is the core finding.)
  2. A fixed, cross-identity store — because entries were keyed only by [mapOwner, mapName] in one shared store, after an identity switch on the same origin a different principal could be served key material cached by a prior one.

Approach

Key material is cached, but identity lifecycle stays the consumer's responsibility — the library does not introspect the agent's identity. (An earlier revision routed the caller principal through the client interface to auto-scope the key; that was reverted because it broke the canister-mirror interface and introduced a TOCTOU race between the principal read for the key and the identity used for the fetch.)

Changes

• In-memory caching by default (InMemoryDerivedKeyMaterialCache) — never touches disk, discarded on reload. Persistence to IndexedDB (IndexedDbDerivedKeyMaterialCache) is now an explicit opt-in via the constructor.
• Cross-identity isolation is a property of the cache, owned by the consumer who knows the identity:
  • in-memory default → use a fresh EncryptedMaps instance per identity (or clearCache() on switch);
  • IndexedDB → give the store a per-identity namespace (e.g. include the principal in the DB name).
• EncryptedMaps.clearCache() — strongly recommended on logout / identity change to drop the still-usable decryption capability.
• Configurable caching strategy via new EncryptedMaps(client, { cache }). The EncryptedMapsClient interface is unchanged (still a pure canister mirror).
• Bump @icp-sdk/core to ^5.4.0.

⚠️ Breaking change

EncryptedMaps no longer persists key material by default (one extra key derivation per map per page load unless opting into IndexedDB). No interface changes — existing custom EncryptedMapsClient implementations keep working.

Upgrading from ≤0.4.0

Versions 0.1.0–0.4.0 persisted derived key material to idb-keyval's default store. The new cache uses a dedicated store, so legacy entries are neither used nor cleared by this version. The CHANGELOG includes a surgical one-time cleanup snippet that deletes only legacy-shaped entries ([string, Uint8Array] -> CryptoKey) from the default store, leaving other app data untouched.

Tests

• 11 tests in cache.test.ts: in-memory & IndexedDB round-trip, non-extractable key survives persistence (exportKey still rejects), cache hit/miss, owner distinction, prefix-collision safety, separate-instance isolation, IndexedDB namespace isolation, and clearCache() re-fetch.
• Full suite green incl. canister integration: 45/45 on @icp-sdk/core 5.4.0, on local + CI (Linux & macOS). tsc, vite build, lint, and prettier-check clean.

Reviewer notes (advisory, not blocking)

• Cache-key collisions are impossible: the key is ${mapOwner}|${hex(mapName)} — principal text is base32 ([a-z2-7-]) and bytesToHex is [0-9a-f], so the | delimiter can never appear inside a field; the key is injective.
• Cross-identity isolation is a documented consumer contract (fresh instance / per-identity namespace + clearCache() on logout), not enforced by identity introspection — deliberately, to keep the canister-client interface stable and avoid a TOCTOU race.

Note for maintainers

package.json still reads 0.4.0 while the CHANGELOG targets 0.5.0 - Unreleased; the breaking change above should land under 0.5.0 per the release flow.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR hardens EncryptedMaps derived key material caching to reduce at-rest exposure and prevent cross-identity cache hits on the same origin, addressing the security review findings while keeping persistence available as an explicit opt-in.

Changes:

• Replaces implicit IndexedDB persistence with an explicit caching strategy (InMemory… default; IndexedDb… opt-in) and adds EncryptedMaps.clearCache().
• Scopes derived-key cache entries to the authenticated caller via a new EncryptedMapsClient.getCallerPrincipal() requirement.
• Updates dependencies to @icp-sdk/core@^5.4.0 and adds tests covering cache behavior and caller scoping.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pnpm-lock.yaml	Locks @icp-sdk/core to 5.4.0 (and transitive updates).
frontend/ic_vetkeys/src/encrypted_maps/index.ts	Introduces pluggable cache strategy, caller-scoped cache keys, and clearCache().
frontend/ic_vetkeys/src/encrypted_maps/encrypted_maps_canister.ts	Implements getCallerPrincipal() in the default client via the agent.
frontend/ic_vetkeys/src/encrypted_maps/cache.ts	Adds cache strategy interface plus in-memory and IndexedDB implementations.
frontend/ic_vetkeys/src/encrypted_maps/cache.test.ts	Adds unit tests for cache round-trips, caller scoping, and clearCache().
frontend/ic_vetkeys/package.json	Bumps @icp-sdk/core dependency range to ^5.4.0.
frontend/ic_vetkeys/CHANGELOG.md	Documents the caching strategy changes, security implications, and breaking API updates.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated 3 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

[Copilot]

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

[Copilot]

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file