@interop/was-react 0.3.5 → 0.3.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -2,30 +2,28 @@
|
|
|
2
2
|
* Copyright (c) 2026 Interop Alliance. All rights reserved.
|
|
3
3
|
*/
|
|
4
4
|
/**
|
|
5
|
-
* WAS identity
|
|
5
|
+
* WAS master-identity derivation from a 32-byte master seed.
|
|
6
6
|
*
|
|
7
7
|
* SEED-DERIVATION CONVENTION (pinned, part of the shared-key contract): the
|
|
8
8
|
* pinned `@interop/webkms-client` exposes `CapabilityAgent.fromSeed({ seed })`,
|
|
9
|
-
* which takes the raw 32 bytes AS-IS (no hashing). We use it for
|
|
10
|
-
* identity
|
|
11
|
-
*
|
|
12
|
-
* a byte array vs its text form.
|
|
9
|
+
* which takes the raw 32 bytes AS-IS (no hashing). We use it for the master
|
|
10
|
+
* identity, feeding raw bytes -- never `fromSecret`, which salt-hashes a STRING
|
|
11
|
+
* and would derive a different key for a byte array vs its text form.
|
|
13
12
|
*
|
|
14
13
|
* WHAT SELECTS THE KEY (verified against `CapabilityAgent.fromSeed`): the key
|
|
15
14
|
* material is derived from the `seed` bytes (the HMAC key) and the `keyName`
|
|
16
15
|
* string (the HMAC message) alone. The `handle` is stored on the returned agent
|
|
17
16
|
* as a cosmetic identifier and does NOT enter key derivation -- nor the derived
|
|
18
17
|
* did:key id, which is the fingerprint of the seed+keyName key pair. So the
|
|
19
|
-
* PINNED derivation inputs are the seed bytes and the `keyName`
|
|
20
|
-
* (`IDENTITY_KEY_NAME`
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
18
|
+
* PINNED derivation inputs are the seed bytes and the `keyName` value
|
|
19
|
+
* (`IDENTITY_KEY_NAME` below); changing THAT after first use is a data-migration
|
|
20
|
+
* event. The `identityHandle` parameter is safe to change and exists only so an
|
|
21
|
+
* app can supply a label for cosmetic continuity; it does not affect the
|
|
22
|
+
* identity, keys, or any stored data.
|
|
24
23
|
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
* or sibling collections -- the future multi-app sharing unit.
|
|
24
|
+
* The per-collection key-agreement (KAK) derivation now lives in
|
|
25
|
+
* `@interop/wallet-core/identity` (`deriveCollectionKeys`, along with its pinned
|
|
26
|
+
* HKDF derivation inputs) and is re-exported here for compatibility.
|
|
29
27
|
*
|
|
30
28
|
* Not test-node-safe on React Native, but fine under Node/Vitest: the crypto
|
|
31
29
|
* stack (`webkms-client`, `x25519-key-agreement-key`) runs on the standard Web
|
|
@@ -33,17 +31,18 @@
|
|
|
33
31
|
*/
|
|
34
32
|
import { CapabilityAgent } from '@interop/webkms-client';
|
|
35
33
|
import { ZcapClient } from '@interop/ezcap';
|
|
36
|
-
|
|
34
|
+
/**
|
|
35
|
+
* The per-collection vault-key (KAK) derivation, its result type, and its
|
|
36
|
+
* default cosmetic handle now live in `@interop/wallet-core/identity` (moved
|
|
37
|
+
* there verbatim, with their pinned `kak:v1:<collectionId>` HKDF derivation
|
|
38
|
+
* inputs); re-exported here so existing imports keep working.
|
|
39
|
+
*/
|
|
40
|
+
export { deriveCollectionKeys, DEFAULT_KAK_HANDLE, type CollectionKeys } from '@interop/wallet-core/identity';
|
|
37
41
|
/**
|
|
38
42
|
* Default cosmetic label for the master identity agent. Local naming only (does
|
|
39
43
|
* not affect key material or the derived did:key); safe to override.
|
|
40
44
|
*/
|
|
41
45
|
export declare const DEFAULT_IDENTITY_HANDLE = "was-react";
|
|
42
|
-
/**
|
|
43
|
-
* Default cosmetic label for a per-collection key-agreement agent. Local naming
|
|
44
|
-
* only (does not affect key material); safe to override.
|
|
45
|
-
*/
|
|
46
|
-
export declare const DEFAULT_KAK_HANDLE = "was-react-kak";
|
|
47
46
|
/**
|
|
48
47
|
* The agents derived from the master seed: the app's stable did:key controller,
|
|
49
48
|
* its signing agent, and a ZcapClient for signing storage requests later.
|
|
@@ -53,16 +52,6 @@ export interface IdentityAgents {
|
|
|
53
52
|
keyAgent: CapabilityAgent;
|
|
54
53
|
zcapClient: ZcapClient;
|
|
55
54
|
}
|
|
56
|
-
/**
|
|
57
|
-
* Derives one collection's X25519 key agreement key (KAK) plus its resolver, the
|
|
58
|
-
* material the doc-cipher needs. The concrete KAK type carries `type` /
|
|
59
|
-
* `publicKeyMultibase`; it is widened to `IKeyAgreementKey` only at the
|
|
60
|
-
* boundary.
|
|
61
|
-
*/
|
|
62
|
-
export interface CollectionKeys {
|
|
63
|
-
keyAgreementKey: IKeyAgreementKey;
|
|
64
|
-
keyResolver: IKeyResolver;
|
|
65
|
-
}
|
|
66
55
|
/**
|
|
67
56
|
* Derives the master identity agents from the master seed. The did:key
|
|
68
57
|
* controller is stable across devices for the same seed.
|
|
@@ -77,23 +66,4 @@ export declare function deriveIdentity({ seed, identityHandle }: {
|
|
|
77
66
|
seed: Uint8Array;
|
|
78
67
|
identityHandle?: string;
|
|
79
68
|
}): Promise<IdentityAgents>;
|
|
80
|
-
/**
|
|
81
|
-
* Derives one collection's vault key material from the master seed:
|
|
82
|
-
* `HKDF(master, 'kak:v1:<collectionId>')` to a per-collection seed, then the
|
|
83
|
-
* Ed25519-to-X25519 (Montgomery-form) key-agreement key. Deterministic, so the
|
|
84
|
-
* same seed decrypts the same envelopes on any device. Encryption uses these
|
|
85
|
-
* per-collection KAKs from day one -- never share one KAK across collections.
|
|
86
|
-
*
|
|
87
|
-
* @param options {object}
|
|
88
|
-
* @param options.seed {Uint8Array} the 32-byte master seed
|
|
89
|
-
* @param options.collectionId {string} the WAS collection id (the HKDF label)
|
|
90
|
-
* @param [options.kakHandle] {string} cosmetic agent label; does not affect
|
|
91
|
-
* keys (defaults to `DEFAULT_KAK_HANDLE`)
|
|
92
|
-
* @returns {Promise<CollectionKeys>}
|
|
93
|
-
*/
|
|
94
|
-
export declare function deriveCollectionKeys({ seed, collectionId, kakHandle }: {
|
|
95
|
-
seed: Uint8Array;
|
|
96
|
-
collectionId: string;
|
|
97
|
-
kakHandle?: string;
|
|
98
|
-
}): Promise<CollectionKeys>;
|
|
99
69
|
//# sourceMappingURL=agents.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/identity/agents.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH
|
|
1
|
+
{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/identity/agents.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAExD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAE3C;;;;;GAKG;AACH,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,cAAc,EACpB,MAAM,+BAA+B,CAAA;AAEtC;;;GAGG;AACH,eAAO,MAAM,uBAAuB,cAAc,CAAA;AAMlD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAA;IACrB,QAAQ,EAAE,eAAe,CAAA;IACzB,UAAU,EAAE,UAAU,CAAA;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,EACnC,IAAI,EACJ,cAAwC,EACzC,EAAE;IACD,IAAI,EAAE,UAAU,CAAA;IAChB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,GAAG,OAAO,CAAC,cAAc,CAAC,CAa1B"}
|
package/dist/identity/agents.js
CHANGED
|
@@ -2,30 +2,28 @@
|
|
|
2
2
|
* Copyright (c) 2026 Interop Alliance. All rights reserved.
|
|
3
3
|
*/
|
|
4
4
|
/**
|
|
5
|
-
* WAS identity
|
|
5
|
+
* WAS master-identity derivation from a 32-byte master seed.
|
|
6
6
|
*
|
|
7
7
|
* SEED-DERIVATION CONVENTION (pinned, part of the shared-key contract): the
|
|
8
8
|
* pinned `@interop/webkms-client` exposes `CapabilityAgent.fromSeed({ seed })`,
|
|
9
|
-
* which takes the raw 32 bytes AS-IS (no hashing). We use it for
|
|
10
|
-
* identity
|
|
11
|
-
*
|
|
12
|
-
* a byte array vs its text form.
|
|
9
|
+
* which takes the raw 32 bytes AS-IS (no hashing). We use it for the master
|
|
10
|
+
* identity, feeding raw bytes -- never `fromSecret`, which salt-hashes a STRING
|
|
11
|
+
* and would derive a different key for a byte array vs its text form.
|
|
13
12
|
*
|
|
14
13
|
* WHAT SELECTS THE KEY (verified against `CapabilityAgent.fromSeed`): the key
|
|
15
14
|
* material is derived from the `seed` bytes (the HMAC key) and the `keyName`
|
|
16
15
|
* string (the HMAC message) alone. The `handle` is stored on the returned agent
|
|
17
16
|
* as a cosmetic identifier and does NOT enter key derivation -- nor the derived
|
|
18
17
|
* did:key id, which is the fingerprint of the seed+keyName key pair. So the
|
|
19
|
-
* PINNED derivation inputs are the seed bytes and the `keyName`
|
|
20
|
-
* (`IDENTITY_KEY_NAME`
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
18
|
+
* PINNED derivation inputs are the seed bytes and the `keyName` value
|
|
19
|
+
* (`IDENTITY_KEY_NAME` below); changing THAT after first use is a data-migration
|
|
20
|
+
* event. The `identityHandle` parameter is safe to change and exists only so an
|
|
21
|
+
* app can supply a label for cosmetic continuity; it does not affect the
|
|
22
|
+
* identity, keys, or any stored data.
|
|
24
23
|
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
* or sibling collections -- the future multi-app sharing unit.
|
|
24
|
+
* The per-collection key-agreement (KAK) derivation now lives in
|
|
25
|
+
* `@interop/wallet-core/identity` (`deriveCollectionKeys`, along with its pinned
|
|
26
|
+
* HKDF derivation inputs) and is re-exported here for compatibility.
|
|
29
27
|
*
|
|
30
28
|
* Not test-node-safe on React Native, but fine under Node/Vitest: the crypto
|
|
31
29
|
* stack (`webkms-client`, `x25519-key-agreement-key`) runs on the standard Web
|
|
@@ -34,38 +32,21 @@
|
|
|
34
32
|
import { CapabilityAgent } from '@interop/webkms-client';
|
|
35
33
|
import { Ed25519Signature2020 } from '@interop/ed25519-signature';
|
|
36
34
|
import { ZcapClient } from '@interop/ezcap';
|
|
37
|
-
|
|
35
|
+
/**
|
|
36
|
+
* The per-collection vault-key (KAK) derivation, its result type, and its
|
|
37
|
+
* default cosmetic handle now live in `@interop/wallet-core/identity` (moved
|
|
38
|
+
* there verbatim, with their pinned `kak:v1:<collectionId>` HKDF derivation
|
|
39
|
+
* inputs); re-exported here so existing imports keep working.
|
|
40
|
+
*/
|
|
41
|
+
export { deriveCollectionKeys, DEFAULT_KAK_HANDLE } from '@interop/wallet-core/identity';
|
|
38
42
|
/**
|
|
39
43
|
* Default cosmetic label for the master identity agent. Local naming only (does
|
|
40
44
|
* not affect key material or the derived did:key); safe to override.
|
|
41
45
|
*/
|
|
42
46
|
export const DEFAULT_IDENTITY_HANDLE = 'was-react';
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
* only (does not affect key material); safe to override.
|
|
46
|
-
*/
|
|
47
|
-
export const DEFAULT_KAK_HANDLE = 'was-react-kak';
|
|
48
|
-
// PINNED key-derivation inputs (the HMAC message that, with the seed, selects
|
|
49
|
-
// the key). Changing either after first use is a data-migration event.
|
|
47
|
+
// PINNED key-derivation input (the HMAC message that, with the seed, selects
|
|
48
|
+
// the key). Changing it after first use is a data-migration event.
|
|
50
49
|
const IDENTITY_KEY_NAME = 'app-key';
|
|
51
|
-
const KAK_KEY_NAME = 'kak';
|
|
52
|
-
/**
|
|
53
|
-
* HKDF-SHA256 expansion of the master seed into a 32-byte per-context seed.
|
|
54
|
-
*
|
|
55
|
-
* @param master {Uint8Array}
|
|
56
|
-
* @param info {string} the domain-separation label (e.g. `kak:v1:projects`)
|
|
57
|
-
* @returns {Promise<Uint8Array>}
|
|
58
|
-
*/
|
|
59
|
-
async function hkdfExpand(master, info) {
|
|
60
|
-
const key = await globalThis.crypto.subtle.importKey('raw', master, 'HKDF', false, ['deriveBits']);
|
|
61
|
-
const bits = await globalThis.crypto.subtle.deriveBits({
|
|
62
|
-
name: 'HKDF',
|
|
63
|
-
hash: 'SHA-256',
|
|
64
|
-
salt: new Uint8Array(0),
|
|
65
|
-
info: new TextEncoder().encode(info)
|
|
66
|
-
}, key, 256);
|
|
67
|
-
return new Uint8Array(bits);
|
|
68
|
-
}
|
|
69
50
|
/**
|
|
70
51
|
* Derives the master identity agents from the master seed. The did:key
|
|
71
52
|
* controller is stable across devices for the same seed.
|
|
@@ -90,43 +71,4 @@ export async function deriveIdentity({ seed, identityHandle = DEFAULT_IDENTITY_H
|
|
|
90
71
|
});
|
|
91
72
|
return { controllerDid: keyAgent.id, keyAgent, zcapClient };
|
|
92
73
|
}
|
|
93
|
-
/**
|
|
94
|
-
* Derives one collection's vault key material from the master seed:
|
|
95
|
-
* `HKDF(master, 'kak:v1:<collectionId>')` to a per-collection seed, then the
|
|
96
|
-
* Ed25519-to-X25519 (Montgomery-form) key-agreement key. Deterministic, so the
|
|
97
|
-
* same seed decrypts the same envelopes on any device. Encryption uses these
|
|
98
|
-
* per-collection KAKs from day one -- never share one KAK across collections.
|
|
99
|
-
*
|
|
100
|
-
* @param options {object}
|
|
101
|
-
* @param options.seed {Uint8Array} the 32-byte master seed
|
|
102
|
-
* @param options.collectionId {string} the WAS collection id (the HKDF label)
|
|
103
|
-
* @param [options.kakHandle] {string} cosmetic agent label; does not affect
|
|
104
|
-
* keys (defaults to `DEFAULT_KAK_HANDLE`)
|
|
105
|
-
* @returns {Promise<CollectionKeys>}
|
|
106
|
-
*/
|
|
107
|
-
export async function deriveCollectionKeys({ seed, collectionId, kakHandle = DEFAULT_KAK_HANDLE }) {
|
|
108
|
-
const collectionSeed = await hkdfExpand(seed, `kak:v1:${collectionId}`);
|
|
109
|
-
const keyAgent = await CapabilityAgent.fromSeed({
|
|
110
|
-
seed: collectionSeed,
|
|
111
|
-
handle: kakHandle,
|
|
112
|
-
keyName: KAK_KEY_NAME
|
|
113
|
-
});
|
|
114
|
-
const keyAgreementKey = X25519KeyAgreementKey2020.fromEd25519VerificationKey2020({
|
|
115
|
-
keyPair: keyAgent.getVerificationKeyPair()
|
|
116
|
-
});
|
|
117
|
-
const keyResolver = async ({ id }) => {
|
|
118
|
-
if (id !== keyAgreementKey.id) {
|
|
119
|
-
throw new Error(`Unknown key id "${id}".`);
|
|
120
|
-
}
|
|
121
|
-
return {
|
|
122
|
-
id: keyAgreementKey.id,
|
|
123
|
-
type: keyAgreementKey.type,
|
|
124
|
-
publicKeyMultibase: keyAgreementKey.publicKeyMultibase
|
|
125
|
-
};
|
|
126
|
-
};
|
|
127
|
-
return {
|
|
128
|
-
keyAgreementKey: keyAgreementKey,
|
|
129
|
-
keyResolver
|
|
130
|
-
};
|
|
131
|
-
}
|
|
132
74
|
//# sourceMappingURL=agents.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"agents.js","sourceRoot":"","sources":["../../src/identity/agents.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH
|
|
1
|
+
{"version":3,"file":"agents.js","sourceRoot":"","sources":["../../src/identity/agents.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AACjE,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAE3C;;;;;GAKG;AACH,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAEnB,MAAM,+BAA+B,CAAA;AAEtC;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,WAAW,CAAA;AAElD,6EAA6E;AAC7E,mEAAmE;AACnE,MAAM,iBAAiB,GAAG,SAAS,CAAA;AAYnC;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,EACnC,IAAI,EACJ,cAAc,GAAG,uBAAuB,EAIzC;IACC,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,QAAQ,CAAC;QAC9C,IAAI;QACJ,MAAM,EAAE,cAAc;QACtB,OAAO,EAAE,iBAAiB;KAC3B,CAAC,CAAA;IACF,MAAM,MAAM,GAAG,QAAQ,CAAC,SAAS,EAAE,CAAA;IACnC,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC;QAChC,UAAU,EAAE,oBAAoB;QAChC,gBAAgB,EAAE,MAAM;QACxB,gBAAgB,EAAE,MAAM;KACzB,CAAC,CAAA;IACF,OAAO,EAAE,aAAa,EAAE,QAAQ,CAAC,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAA;AAC7D,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@interop/was-react",
|
|
3
3
|
"description": "React library for building 'Bring Your Own Everything' (BYOE) apps on Wallet Attached Storage: DID Auth login via CHAPI wallet, local-first encrypted storage, and background sync to a WAS server.",
|
|
4
|
-
"version": "0.3.
|
|
4
|
+
"version": "0.3.6",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"scripts": {
|
|
7
7
|
"build": "pnpm run clear && tsc",
|
|
@@ -52,6 +52,7 @@
|
|
|
52
52
|
"@interop/security-document-loader": "^9.4.4",
|
|
53
53
|
"@interop/vc": "^11.0.6",
|
|
54
54
|
"@interop/verifier-core": "^3.4.1",
|
|
55
|
+
"@interop/wallet-core": "^0.5.0",
|
|
55
56
|
"@interop/was-client": "^0.19.0",
|
|
56
57
|
"@interop/webkms-client": "^14.7.1",
|
|
57
58
|
"@interop/x25519-key-agreement-key": "^5.2.1",
|