@kokuin/vault 0.0.0-stage → 0.7.0
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.
- package/README.md +164 -2
- package/lib/branch.d.ts +4 -0
- package/lib/branch.js +11 -0
- package/lib/canonical-token.d.ts +1 -0
- package/lib/canonical-token.js +10 -0
- package/lib/digest.d.ts +50 -0
- package/lib/digest.js +82 -0
- package/lib/errors.d.ts +68 -0
- package/lib/errors.js +109 -0
- package/lib/factors.d.ts +29 -0
- package/lib/factors.js +65 -0
- package/lib/id.d.ts +16 -0
- package/lib/id.js +32 -0
- package/lib/index.d.ts +18 -0
- package/lib/index.js +12 -0
- package/lib/key-cache.d.ts +35 -0
- package/lib/key-cache.js +65 -0
- package/lib/pin-throttle.d.ts +16 -0
- package/lib/pin-throttle.js +40 -0
- package/lib/record-types.d.ts +55 -0
- package/lib/record-types.js +507 -0
- package/lib/records.d.ts +110 -0
- package/lib/records.js +301 -0
- package/lib/suite.d.ts +89 -0
- package/lib/suite.js +363 -0
- package/lib/wrappable.d.ts +4 -0
- package/lib/wrappable.js +4 -0
- package/package.json +50 -3
package/lib/suite.js
ADDED
|
@@ -0,0 +1,363 @@
|
|
|
1
|
+
import { deriveSharedSecretAsync } from '@kokuin/jwe';
|
|
2
|
+
import { gcm } from '@noble/ciphers/aes.js';
|
|
3
|
+
import { argon2idAsync } from '@noble/hashes/argon2.js';
|
|
4
|
+
import { hkdf } from '@noble/hashes/hkdf.js';
|
|
5
|
+
import { sha256 } from '@noble/hashes/sha2.js';
|
|
6
|
+
import { concatBytes } from '@noble/hashes/utils.js';
|
|
7
|
+
import { canonicalStringify, fromB64, fromUTF, toB64 } from '@sozai/codec';
|
|
8
|
+
import { checkDescriptorDigest, descriptorDigest } from './digest.js';
|
|
9
|
+
import { InvalidVaultFactors, NoAvailableFactor, UnsupportedVaultSuite, VaultSecretRejected, VaultTampered } from './errors.js';
|
|
10
|
+
/** X25519 / HKDF-SHA256 / Argon2id / A256GCM. */ export const SUITE_VAULT_1 = 1;
|
|
11
|
+
const IV_LENGTH = 12;
|
|
12
|
+
const CONTENT_KEY_LENGTH = 32;
|
|
13
|
+
const FACTOR_SECRET_LENGTH = 32;
|
|
14
|
+
const SALT_LENGTH = 16;
|
|
15
|
+
const WRAP_INFO_PREFIX = 'kokuin/vault/wrap/v1';
|
|
16
|
+
const ARGON2_COST_LIMITS = {
|
|
17
|
+
m: {
|
|
18
|
+
min: 8,
|
|
19
|
+
max: 262_144
|
|
20
|
+
},
|
|
21
|
+
t: {
|
|
22
|
+
min: 1,
|
|
23
|
+
max: 10
|
|
24
|
+
},
|
|
25
|
+
p: {
|
|
26
|
+
min: 1,
|
|
27
|
+
max: 16
|
|
28
|
+
}
|
|
29
|
+
};
|
|
30
|
+
/** Memory KiB, passes, lanes. Costs are per wrapping, independent of suite version. */ export const DEFAULT_ARGON2_COST = {
|
|
31
|
+
m: 19456,
|
|
32
|
+
t: 2,
|
|
33
|
+
p: 1
|
|
34
|
+
};
|
|
35
|
+
function invalidArgon2Cost(cost) {
|
|
36
|
+
for (const name of [
|
|
37
|
+
'm',
|
|
38
|
+
't',
|
|
39
|
+
'p'
|
|
40
|
+
]){
|
|
41
|
+
const value = cost[name];
|
|
42
|
+
const limits = ARGON2_COST_LIMITS[name];
|
|
43
|
+
if (!Number.isSafeInteger(value) || value < limits.min || value > limits.max) {
|
|
44
|
+
return `${name} must be an integer from ${limits.min} through ${limits.max}`;
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
return null;
|
|
48
|
+
}
|
|
49
|
+
// Factor order, wrapping salt, and suite/key/version binding are part of the wire scheme.
|
|
50
|
+
function deriveKEK({ secrets, wrappingID, suiteID, keyID, keyVersion }) {
|
|
51
|
+
const info = fromUTF(`${WRAP_INFO_PREFIX}:${suiteID}:${keyID}:${keyVersion}`);
|
|
52
|
+
return hkdf(sha256, concatBytes(...secrets), fromUTF(wrappingID), info, CONTENT_KEY_LENGTH);
|
|
53
|
+
}
|
|
54
|
+
// Canonical object keys, ordered descriptors.
|
|
55
|
+
function wrappingAAD(descriptors) {
|
|
56
|
+
return fromUTF(canonicalStringify(descriptors));
|
|
57
|
+
}
|
|
58
|
+
function entryAAD({ suiteID, keyID, keyVersion, entryID }) {
|
|
59
|
+
return fromUTF(`kokuin/vault/entry/v1:${suiteID}:${keyID}:${keyVersion}:${entryID}`);
|
|
60
|
+
}
|
|
61
|
+
async function didFactorSecretForSender(recipientDID, methods) {
|
|
62
|
+
const { sharedSecret, ephemeralPublicKey } = await deriveSharedSecretAsync({
|
|
63
|
+
recipient: recipientDID,
|
|
64
|
+
methods: methods ?? []
|
|
65
|
+
});
|
|
66
|
+
return {
|
|
67
|
+
secret: sharedSecret,
|
|
68
|
+
params: {
|
|
69
|
+
recipient: recipientDID,
|
|
70
|
+
epk: toB64(ephemeralPublicKey)
|
|
71
|
+
}
|
|
72
|
+
};
|
|
73
|
+
}
|
|
74
|
+
async function secretFactorForSender(runtime, input, cost) {
|
|
75
|
+
const invalid = invalidArgon2Cost(cost);
|
|
76
|
+
if (invalid != null) {
|
|
77
|
+
throw new InvalidVaultFactors({
|
|
78
|
+
reason: `invalid Argon2 cost: ${invalid}`
|
|
79
|
+
});
|
|
80
|
+
}
|
|
81
|
+
const salt = runtime.getRandomValues(new Uint8Array(SALT_LENGTH));
|
|
82
|
+
const secret = await argon2idAsync(input, salt, {
|
|
83
|
+
...cost,
|
|
84
|
+
dkLen: FACTOR_SECRET_LENGTH
|
|
85
|
+
});
|
|
86
|
+
return {
|
|
87
|
+
secret,
|
|
88
|
+
params: {
|
|
89
|
+
salt: toB64(salt),
|
|
90
|
+
...cost
|
|
91
|
+
}
|
|
92
|
+
};
|
|
93
|
+
}
|
|
94
|
+
async function secretFactorForRecipient(kind, input, params) {
|
|
95
|
+
if (input == null) {
|
|
96
|
+
throw new NoAvailableFactor({
|
|
97
|
+
kind
|
|
98
|
+
});
|
|
99
|
+
}
|
|
100
|
+
const { salt, m, t, p } = params;
|
|
101
|
+
if (typeof salt !== 'string' || typeof m !== 'number' || typeof t !== 'number' || typeof p !== 'number') {
|
|
102
|
+
throw new VaultTampered({
|
|
103
|
+
message: `${kind} factor descriptor carries no usable Argon2 parameters`
|
|
104
|
+
});
|
|
105
|
+
}
|
|
106
|
+
const invalid = invalidArgon2Cost({
|
|
107
|
+
m,
|
|
108
|
+
t,
|
|
109
|
+
p
|
|
110
|
+
});
|
|
111
|
+
if (invalid != null) {
|
|
112
|
+
throw new VaultTampered({
|
|
113
|
+
message: `${kind} factor descriptor has invalid Argon2 cost: ${invalid}`
|
|
114
|
+
});
|
|
115
|
+
}
|
|
116
|
+
let decodedSalt;
|
|
117
|
+
try {
|
|
118
|
+
decodedSalt = fromB64(salt);
|
|
119
|
+
} catch (cause) {
|
|
120
|
+
// biome-ignore lint/style/useErrorCause: the params object forwards options.cause.
|
|
121
|
+
throw new VaultTampered({
|
|
122
|
+
message: `${kind} factor descriptor carries an invalid Argon2 salt`,
|
|
123
|
+
options: {
|
|
124
|
+
cause
|
|
125
|
+
}
|
|
126
|
+
});
|
|
127
|
+
}
|
|
128
|
+
if (decodedSalt.length !== SALT_LENGTH) {
|
|
129
|
+
throw new VaultTampered({
|
|
130
|
+
message: `${kind} factor descriptor Argon2 salt must be ${SALT_LENGTH} bytes`
|
|
131
|
+
});
|
|
132
|
+
}
|
|
133
|
+
return await argon2idAsync(input, decodedSalt, {
|
|
134
|
+
m,
|
|
135
|
+
t,
|
|
136
|
+
p,
|
|
137
|
+
dkLen: FACTOR_SECRET_LENGTH
|
|
138
|
+
});
|
|
139
|
+
}
|
|
140
|
+
// A PIN requires device possession; a passphrase alone does not substitute for it.
|
|
141
|
+
export function validateFactorList(kinds) {
|
|
142
|
+
if (kinds.length === 0) {
|
|
143
|
+
throw new InvalidVaultFactors({
|
|
144
|
+
reason: 'a wrapping needs at least one factor'
|
|
145
|
+
});
|
|
146
|
+
}
|
|
147
|
+
const seen = new Set();
|
|
148
|
+
for (const kind of kinds){
|
|
149
|
+
if (kind === 'did') {
|
|
150
|
+
continue;
|
|
151
|
+
}
|
|
152
|
+
if (seen.has(kind)) {
|
|
153
|
+
throw new InvalidVaultFactors({
|
|
154
|
+
reason: `duplicate "${kind}" factor`
|
|
155
|
+
});
|
|
156
|
+
}
|
|
157
|
+
seen.add(kind);
|
|
158
|
+
}
|
|
159
|
+
if (seen.has('pin') && !kinds.includes('did')) {
|
|
160
|
+
throw new InvalidVaultFactors({
|
|
161
|
+
reason: 'a "pin" factor requires a "did" factor in the same wrapping'
|
|
162
|
+
});
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
async function didFactorSecretForRecipient(identity, params) {
|
|
166
|
+
if (identity == null) {
|
|
167
|
+
throw new NoAvailableFactor({
|
|
168
|
+
kind: 'did'
|
|
169
|
+
});
|
|
170
|
+
}
|
|
171
|
+
const epk = params.epk;
|
|
172
|
+
if (typeof epk !== 'string') {
|
|
173
|
+
throw new VaultTampered({
|
|
174
|
+
message: 'did factor descriptor carries no epk'
|
|
175
|
+
});
|
|
176
|
+
}
|
|
177
|
+
return await identity.agreeKey({
|
|
178
|
+
ephemeralPublicKey: fromB64(epk)
|
|
179
|
+
});
|
|
180
|
+
}
|
|
181
|
+
const suite1 = {
|
|
182
|
+
id: SUITE_VAULT_1,
|
|
183
|
+
name: 'VAULT_1',
|
|
184
|
+
generateContentKey (runtime) {
|
|
185
|
+
return runtime.getRandomValues(new Uint8Array(CONTENT_KEY_LENGTH));
|
|
186
|
+
},
|
|
187
|
+
async wrap (input) {
|
|
188
|
+
const params = {
|
|
189
|
+
...input,
|
|
190
|
+
contentKey: new Uint8Array(input.contentKey),
|
|
191
|
+
factors: input.factors.map((factor)=>{
|
|
192
|
+
return factor.kind === 'did' ? {
|
|
193
|
+
...factor
|
|
194
|
+
} : {
|
|
195
|
+
...factor,
|
|
196
|
+
input: new Uint8Array(factor.input),
|
|
197
|
+
...factor.cost === undefined ? {} : {
|
|
198
|
+
cost: {
|
|
199
|
+
...factor.cost
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
};
|
|
203
|
+
})
|
|
204
|
+
};
|
|
205
|
+
validateFactorList(params.factors.map((factor)=>factor.kind));
|
|
206
|
+
const secrets = [];
|
|
207
|
+
const descriptors = [];
|
|
208
|
+
for (const factor of params.factors){
|
|
209
|
+
switch(factor.kind){
|
|
210
|
+
case 'did':
|
|
211
|
+
{
|
|
212
|
+
const { secret, params: factorParams } = await didFactorSecretForSender(factor.recipientDID, params.methods);
|
|
213
|
+
secrets.push(secret);
|
|
214
|
+
descriptors.push({
|
|
215
|
+
kind: 'did',
|
|
216
|
+
params: factorParams
|
|
217
|
+
});
|
|
218
|
+
break;
|
|
219
|
+
}
|
|
220
|
+
case 'passphrase':
|
|
221
|
+
case 'pin':
|
|
222
|
+
{
|
|
223
|
+
const { secret, params: factorParams } = await secretFactorForSender(params.runtime, factor.input, factor.cost ?? DEFAULT_ARGON2_COST);
|
|
224
|
+
secrets.push(secret);
|
|
225
|
+
descriptors.push({
|
|
226
|
+
kind: factor.kind,
|
|
227
|
+
params: factorParams
|
|
228
|
+
});
|
|
229
|
+
break;
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
const kek = deriveKEK({
|
|
234
|
+
secrets,
|
|
235
|
+
wrappingID: params.wrappingID,
|
|
236
|
+
suiteID: SUITE_VAULT_1,
|
|
237
|
+
keyID: params.keyID,
|
|
238
|
+
keyVersion: params.keyVersion
|
|
239
|
+
});
|
|
240
|
+
const iv = params.runtime.getRandomValues(new Uint8Array(IV_LENGTH));
|
|
241
|
+
return {
|
|
242
|
+
descriptors,
|
|
243
|
+
descriptorDigest: await descriptorDigest({
|
|
244
|
+
...params,
|
|
245
|
+
descriptors
|
|
246
|
+
}),
|
|
247
|
+
iv,
|
|
248
|
+
wrappedKey: gcm(kek, iv, wrappingAAD(descriptors)).encrypt(params.contentKey)
|
|
249
|
+
};
|
|
250
|
+
},
|
|
251
|
+
async unwrap (input) {
|
|
252
|
+
const params = {
|
|
253
|
+
...input,
|
|
254
|
+
descriptors: JSON.parse(JSON.stringify(input.descriptors)),
|
|
255
|
+
iv: new Uint8Array(input.iv),
|
|
256
|
+
wrappedKey: new Uint8Array(input.wrappedKey),
|
|
257
|
+
inputs: input.inputs === undefined ? undefined : Object.fromEntries(Object.entries(input.inputs).flatMap(([kind, bytes])=>{
|
|
258
|
+
return bytes === undefined ? [] : [
|
|
259
|
+
[
|
|
260
|
+
kind,
|
|
261
|
+
new Uint8Array(bytes)
|
|
262
|
+
]
|
|
263
|
+
];
|
|
264
|
+
}))
|
|
265
|
+
};
|
|
266
|
+
if (params.expectedDescriptorDigest !== undefined) {
|
|
267
|
+
await checkDescriptorDigest({
|
|
268
|
+
crypto: params.crypto,
|
|
269
|
+
descriptors: params.descriptors,
|
|
270
|
+
expectedDescriptorDigest: params.expectedDescriptorDigest
|
|
271
|
+
});
|
|
272
|
+
}
|
|
273
|
+
validateFactorList(params.descriptors.map((descriptor)=>descriptor.kind));
|
|
274
|
+
const secrets = [];
|
|
275
|
+
const userSuppliedKinds = [];
|
|
276
|
+
for (const descriptor of params.descriptors){
|
|
277
|
+
switch(descriptor.kind){
|
|
278
|
+
case 'did':
|
|
279
|
+
secrets.push(await didFactorSecretForRecipient(params.identity, descriptor.params));
|
|
280
|
+
break;
|
|
281
|
+
case 'passphrase':
|
|
282
|
+
case 'pin':
|
|
283
|
+
secrets.push(await secretFactorForRecipient(descriptor.kind, params.inputs?.[descriptor.kind], descriptor.params));
|
|
284
|
+
userSuppliedKinds.push(descriptor.kind);
|
|
285
|
+
break;
|
|
286
|
+
default:
|
|
287
|
+
throw new NoAvailableFactor({
|
|
288
|
+
kind: descriptor.kind
|
|
289
|
+
});
|
|
290
|
+
}
|
|
291
|
+
}
|
|
292
|
+
const kek = deriveKEK({
|
|
293
|
+
secrets,
|
|
294
|
+
wrappingID: params.wrappingID,
|
|
295
|
+
suiteID: SUITE_VAULT_1,
|
|
296
|
+
keyID: params.keyID,
|
|
297
|
+
keyVersion: params.keyVersion
|
|
298
|
+
});
|
|
299
|
+
try {
|
|
300
|
+
return gcm(kek, params.iv, wrappingAAD(params.descriptors)).decrypt(params.wrappedKey);
|
|
301
|
+
} catch (cause) {
|
|
302
|
+
// A tag failure cannot attribute corruption versus a wrong secret, including DID-only wraps.
|
|
303
|
+
// biome-ignore lint/style/useErrorCause: the params object forwards options.cause.
|
|
304
|
+
throw new VaultSecretRejected({
|
|
305
|
+
kinds: userSuppliedKinds,
|
|
306
|
+
options: {
|
|
307
|
+
cause,
|
|
308
|
+
keyID: params.keyID
|
|
309
|
+
}
|
|
310
|
+
});
|
|
311
|
+
}
|
|
312
|
+
},
|
|
313
|
+
encryptEntry (params) {
|
|
314
|
+
const iv = params.runtime.getRandomValues(new Uint8Array(IV_LENGTH));
|
|
315
|
+
const aad = entryAAD({
|
|
316
|
+
suiteID: SUITE_VAULT_1,
|
|
317
|
+
keyID: params.keyID,
|
|
318
|
+
keyVersion: params.keyVersion,
|
|
319
|
+
entryID: params.entryID
|
|
320
|
+
});
|
|
321
|
+
return {
|
|
322
|
+
iv,
|
|
323
|
+
ciphertext: gcm(params.contentKey, iv, aad).encrypt(params.plaintext)
|
|
324
|
+
};
|
|
325
|
+
},
|
|
326
|
+
decryptEntry (params) {
|
|
327
|
+
const aad = entryAAD({
|
|
328
|
+
suiteID: SUITE_VAULT_1,
|
|
329
|
+
keyID: params.keyID,
|
|
330
|
+
keyVersion: params.keyVersion,
|
|
331
|
+
entryID: params.entryID
|
|
332
|
+
});
|
|
333
|
+
try {
|
|
334
|
+
return gcm(params.contentKey, params.iv, aad).decrypt(params.ciphertext);
|
|
335
|
+
} catch (cause) {
|
|
336
|
+
// biome-ignore lint/style/useErrorCause: the params object forwards options.cause.
|
|
337
|
+
throw new VaultTampered({
|
|
338
|
+
message: 'vault entry failed authentication: it was altered, or is being read under the wrong key version',
|
|
339
|
+
options: {
|
|
340
|
+
cause
|
|
341
|
+
}
|
|
342
|
+
});
|
|
343
|
+
}
|
|
344
|
+
}
|
|
345
|
+
};
|
|
346
|
+
const SUITES = new Map([
|
|
347
|
+
[
|
|
348
|
+
SUITE_VAULT_1,
|
|
349
|
+
suite1
|
|
350
|
+
]
|
|
351
|
+
]);
|
|
352
|
+
export function getSuite(id) {
|
|
353
|
+
const suite = SUITES.get(id);
|
|
354
|
+
if (suite == null) {
|
|
355
|
+
throw new UnsupportedVaultSuite({
|
|
356
|
+
suite: id
|
|
357
|
+
});
|
|
358
|
+
}
|
|
359
|
+
return suite;
|
|
360
|
+
}
|
|
361
|
+
export function isSupportedSuite(id) {
|
|
362
|
+
return SUITES.has(id);
|
|
363
|
+
}
|
package/lib/wrappable.js
ADDED
package/package.json
CHANGED
|
@@ -1,6 +1,53 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kokuin/vault",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.7.0",
|
|
4
|
+
"description": "Database-free content keys, ordered factor wrapping and authenticated byte encryption",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"vault",
|
|
7
|
+
"encryption",
|
|
8
|
+
"keys"
|
|
9
|
+
],
|
|
10
|
+
"repository": {
|
|
11
|
+
"type": "git",
|
|
12
|
+
"url": "https://github.com/TairuFramework/kokuin",
|
|
13
|
+
"directory": "packages/vault"
|
|
14
|
+
},
|
|
15
|
+
"license": "MIT",
|
|
16
|
+
"sideEffects": false,
|
|
17
|
+
"type": "module",
|
|
18
|
+
"exports": {
|
|
19
|
+
".": "./lib/index.js"
|
|
20
|
+
},
|
|
21
|
+
"main": "lib/index.js",
|
|
22
|
+
"types": "lib/index.d.ts",
|
|
23
|
+
"files": [
|
|
24
|
+
"lib/*"
|
|
25
|
+
],
|
|
26
|
+
"dependencies": {
|
|
27
|
+
"@kokuin/crypto": "^0.7.0",
|
|
28
|
+
"@kokuin/jwe": "^0.7.0",
|
|
29
|
+
"@kokuin/records": "^0.7.0",
|
|
30
|
+
"@kokuin/token": "^0.7.0",
|
|
31
|
+
"@noble/ciphers": "^2.4.0",
|
|
32
|
+
"@noble/hashes": "^2.4.0",
|
|
33
|
+
"@sozai/codec": "^0.4.4",
|
|
34
|
+
"@sozai/hlc": "^0.1.0",
|
|
35
|
+
"@sozai/json": "^0.3.0",
|
|
36
|
+
"@sozai/runtime": "^0.1.0"
|
|
37
|
+
},
|
|
38
|
+
"devDependencies": {
|
|
39
|
+
"@types/node": "^26.6.6"
|
|
40
|
+
},
|
|
41
|
+
"publishConfig": {
|
|
42
|
+
"access": "public"
|
|
43
|
+
},
|
|
44
|
+
"scripts": {
|
|
45
|
+
"build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
|
|
46
|
+
"build:clean": "del-cli lib",
|
|
47
|
+
"build:js": "del-cli 'lib/**/*.js' && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
|
|
48
|
+
"build:types": "del-cli 'lib/**/*.d.ts' 'lib/**/*.d.ts.map' && tsc --emitDeclarationOnly --skipLibCheck",
|
|
49
|
+
"test": "pnpm run test:types && pnpm run test:unit",
|
|
50
|
+
"test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
|
|
51
|
+
"test:unit": "vitest run"
|
|
52
|
+
}
|
|
6
53
|
}
|