@interop/wallet-core 0.4.1 → 0.5.0

package/dist/identity/collectionKeys.d.ts

@@ -0,0 +1,36 @@
+import type { IKeyAgreementKey, IKeyResolver } from '@interop/data-integrity-core';
+/**
+ * Default cosmetic label for a per-collection key-agreement agent. Local naming
+ * only (does not affect key material); safe to override.
+ */
+export declare const DEFAULT_KAK_HANDLE = "was-react-kak";
+/**
+ * Derives one collection's X25519 key agreement key (KAK) plus its resolver, the
+ * material the doc-cipher needs. The concrete KAK type carries `type` /
+ * `publicKeyMultibase`; it is widened to `IKeyAgreementKey` only at the
+ * boundary.
+ */
+export interface CollectionKeys {
+    keyAgreementKey: IKeyAgreementKey;
+    keyResolver: IKeyResolver;
+}
+/**
+ * Derives one collection's vault key material from the master seed:
+ * `HKDF(master, 'kak:v1:<collectionId>')` to a per-collection seed, then the
+ * Ed25519-to-X25519 (Montgomery-form) key-agreement key. Deterministic, so the
+ * same seed decrypts the same envelopes on any device. Encryption uses these
+ * per-collection KAKs from day one -- never share one KAK across collections.
+ *
+ * @param options {object}
+ * @param options.seed {Uint8Array}       the 32-byte master seed
+ * @param options.collectionId {string}   the WAS collection id (the HKDF label)
+ * @param [options.kakHandle] {string}    cosmetic agent label; does not affect
+ *   keys (defaults to `DEFAULT_KAK_HANDLE`)
+ * @returns {Promise<CollectionKeys>}
+ */
+export declare function deriveCollectionKeys({ seed, collectionId, kakHandle }: {
+    seed: Uint8Array;
+    collectionId: string;
+    kakHandle?: string;
+}): Promise<CollectionKeys>;
+//# sourceMappingURL=collectionKeys.d.ts.map

package/dist/identity/collectionKeys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectionKeys.d.ts","sourceRoot":"","sources":["../../src/identity/collectionKeys.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACb,MAAM,8BAA8B,CAAA;AAIrC;;;GAGG;AACH,eAAO,MAAM,kBAAkB,kBAAkB,CAAA;AAMjD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,eAAe,EAAE,gBAAgB,CAAA;IACjC,WAAW,EAAE,YAAY,CAAA;CAC1B;AAiCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,oBAAoB,CAAC,EACzC,IAAI,EACJ,YAAY,EACZ,SAA8B,EAC/B,EAAE;IACD,IAAI,EAAE,UAAU,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgB1B"}

package/dist/identity/collectionKeys.js

@@ -0,0 +1,92 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * Per-collection vault-key (KAK) derivation from a 32-byte master seed.
+ *
+ * SEED-DERIVATION CONVENTION (pinned, part of the shared-key contract): the
+ * pinned `@interop/webkms-client` exposes `CapabilityAgent.fromSeed({ seed })`,
+ * which takes the raw 32 bytes AS-IS (no hashing). We use it for the
+ * per-collection key-agreement keys, feeding raw bytes -- never `fromSecret`,
+ * which salt-hashes a STRING and would derive a different key for a byte array
+ * vs its text form.
+ *
+ * WHAT SELECTS THE KEY (verified against `CapabilityAgent.fromSeed`): the key
+ * material is derived from the `seed` bytes (the HMAC key) and the `keyName`
+ * string (the HMAC message) alone. The `handle` is stored on the returned agent
+ * as a cosmetic identifier and does NOT enter key derivation -- nor the derived
+ * did:key id, which is the fingerprint of the seed+keyName key pair. So the
+ * PINNED derivation inputs are the seed bytes and the `keyName` value
+ * (`KAK_KEY_NAME` below); changing THAT after first use is a data-migration
+ * event. The `kakHandle` parameter is safe to change and exists only so an app
+ * can supply a label for cosmetic continuity; it does not affect the keys or
+ * any stored data.
+ *
+ * Per-collection KAKs derive via `HKDF-SHA256(master, info = 'kak:v1:<id>')` to
+ * a 32-byte per-collection seed, then the standard Ed25519-to-X25519 path. HKDF
+ * one-wayness means a shared per-collection key exposes nothing about the master
+ * or sibling collections -- the future multi-app sharing unit.
+ *
+ * Not test-node-safe on React Native, but fine under Node/Vitest: the crypto
+ * stack (`webkms-client`, `x25519-key-agreement-key`) runs on the standard Web
+ * Crypto that Node 24 provides.
+ */
+import { CapabilityAgent } from '@interop/webkms-client';
+import { X25519KeyAgreementKey2020 } from '@interop/x25519-key-agreement-key';
+import { singleKeyResolver } from './keyResolver.js';
+/**
+ * Default cosmetic label for a per-collection key-agreement agent. Local naming
+ * only (does not affect key material); safe to override.
+ */
+export const DEFAULT_KAK_HANDLE = 'was-react-kak';
+// PINNED key-derivation input (the HMAC message that, with the seed, selects
+// the key). Changing it after first use is a data-migration event.
+const KAK_KEY_NAME = 'kak';
+/**
+ * HKDF-SHA256 expansion of the master seed into a 32-byte per-context seed.
+ *
+ * @param master {Uint8Array}
+ * @param info {string}   the domain-separation label (e.g. `kak:v1:projects`)
+ * @returns {Promise<Uint8Array>}
+ */
+async function hkdfExpand(master, info) {
+    const key = await globalThis.crypto.subtle.importKey('raw', master, 'HKDF', false, ['deriveBits']);
+    const bits = await globalThis.crypto.subtle.deriveBits({
+        name: 'HKDF',
+        hash: 'SHA-256',
+        salt: new Uint8Array(0),
+        info: new TextEncoder().encode(info)
+    }, key, 256);
+    return new Uint8Array(bits);
+}
+/**
+ * Derives one collection's vault key material from the master seed:
+ * `HKDF(master, 'kak:v1:<collectionId>')` to a per-collection seed, then the
+ * Ed25519-to-X25519 (Montgomery-form) key-agreement key. Deterministic, so the
+ * same seed decrypts the same envelopes on any device. Encryption uses these
+ * per-collection KAKs from day one -- never share one KAK across collections.
+ *
+ * @param options {object}
+ * @param options.seed {Uint8Array}       the 32-byte master seed
+ * @param options.collectionId {string}   the WAS collection id (the HKDF label)
+ * @param [options.kakHandle] {string}    cosmetic agent label; does not affect
+ *   keys (defaults to `DEFAULT_KAK_HANDLE`)
+ * @returns {Promise<CollectionKeys>}
+ */
+export async function deriveCollectionKeys({ seed, collectionId, kakHandle = DEFAULT_KAK_HANDLE }) {
+    const collectionSeed = await hkdfExpand(seed, `kak:v1:${collectionId}`);
+    const keyAgent = await CapabilityAgent.fromSeed({
+        seed: collectionSeed,
+        handle: kakHandle,
+        keyName: KAK_KEY_NAME
+    });
+    const keyAgreementKey = X25519KeyAgreementKey2020.fromEd25519VerificationKey2020({
+        keyPair: keyAgent.getVerificationKeyPair()
+    });
+    const keyResolver = singleKeyResolver({ keyAgreementKey });
+    return {
+        keyAgreementKey: keyAgreementKey,
+        keyResolver
+    };
+}
+//# sourceMappingURL=collectionKeys.js.map

package/dist/identity/collectionKeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectionKeys.js","sourceRoot":"","sources":["../../src/identity/collectionKeys.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAA;AAM7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEpD;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAe,CAAA;AAEjD,6EAA6E;AAC7E,mEAAmE;AACnE,MAAM,YAAY,GAAG,KAAK,CAAA;AAa1B;;;;;;GAMG;AACH,KAAK,UAAU,UAAU,CACvB,MAAkB,EAClB,IAAY;IAEZ,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAClD,KAAK,EACL,MAAiC,EACjC,MAAM,EACN,KAAK,EACL,CAAC,YAAY,CAAC,CACf,CAAA;IACD,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CACpD;QACE,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,IAAI,UAAU,CAAC,CAAC,CAAC;QACvB,IAAI,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC;KACrC,EACD,GAAG,EACH,GAAG,CACJ,CAAA;IACD,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,CAAA;AAC7B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,EACzC,IAAI,EACJ,YAAY,EACZ,SAAS,GAAG,kBAAkB,EAK/B;IACC,MAAM,cAAc,GAAG,MAAM,UAAU,CAAC,IAAI,EAAE,UAAU,YAAY,EAAE,CAAC,CAAA;IACvE,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,QAAQ,CAAC;QAC9C,IAAI,EAAE,cAAc;QACpB,MAAM,EAAE,SAAS;QACjB,OAAO,EAAE,YAAY;KACtB,CAAC,CAAA;IACF,MAAM,eAAe,GACnB,yBAAyB,CAAC,8BAA8B,CAAC;QACvD,OAAO,EAAE,QAAQ,CAAC,sBAAsB,EAAE;KAC3C,CAAC,CAAA;IACJ,MAAM,WAAW,GAAG,iBAAiB,CAAC,EAAE,eAAe,EAAE,CAAC,CAAA;IAC1D,OAAO;QACL,eAAe,EAAE,eAAmC;QACpD,WAAW;KACZ,CAAA;AACH,CAAC"}

package/dist/identity/index.d.ts

@@ -10,6 +10,9 @@
  *   single-key resolver) under the fixed bootstrap handle / key name.
  * - `singleKeyResolver` -- the one-key `IKeyResolver` factory (also used by
  *   app-side derivations such as a keyring unlock identity).
+ * - `deriveCollectionKeys` -- per-collection vault-key (KAK) derivation:
+ *   `HKDF-SHA256(master seed, 'kak:v1:<collectionId>')` to a per-collection
+ *   seed, then the Ed25519-to-X25519 key-agreement key plus its resolver.
  *
  * Kept out of the root export: this subpath pulls the webkms-client / ezcap /
  * x25519 dependency graph (the same isolation pattern as `./request`).
@@ -17,4 +20,6 @@
 export { BOOTSTRAP_HANDLE, BOOTSTRAP_KEY_NAME, agentsFromSecret, agentsFromSeed } from './agents.js';
 export type { ProfileAgents } from './agents.js';
 export { singleKeyResolver } from './keyResolver.js';
+export { deriveCollectionKeys, DEFAULT_KAK_HANDLE } from './collectionKeys.js';
+export type { CollectionKeys } from './collectionKeys.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/identity/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/identity/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;GAYG;AACH,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACf,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/identity/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACf,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAC9E,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/identity/index.js

@@ -10,10 +10,14 @@
  *   single-key resolver) under the fixed bootstrap handle / key name.
  * - `singleKeyResolver` -- the one-key `IKeyResolver` factory (also used by
  *   app-side derivations such as a keyring unlock identity).
+ * - `deriveCollectionKeys` -- per-collection vault-key (KAK) derivation:
+ *   `HKDF-SHA256(master seed, 'kak:v1:<collectionId>')` to a per-collection
+ *   seed, then the Ed25519-to-X25519 key-agreement key plus its resolver.
  *
  * Kept out of the root export: this subpath pulls the webkms-client / ezcap /
  * x25519 dependency graph (the same isolation pattern as `./request`).
  */
 export { BOOTSTRAP_HANDLE, BOOTSTRAP_KEY_NAME, agentsFromSecret, agentsFromSeed } from './agents.js';
 export { singleKeyResolver } from './keyResolver.js';
+export { deriveCollectionKeys, DEFAULT_KAK_HANDLE } from './collectionKeys.js';
 //# sourceMappingURL=index.js.map

package/dist/identity/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/identity/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;GAYG;AACH,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACf,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/identity/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACf,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@interop/wallet-core",
   "description": "Shared wallet-domain logic (WAS sync engine core and wallet Space layout contracts) for Interop wallet apps.",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "type": "module",
   "scripts": {
     "build": "pnpm run clear && tsc",