@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/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
+ }
@@ -0,0 +1,4 @@
1
+ export declare function wrappableDID(identity: {
2
+ id: string;
3
+ longForm?: string;
4
+ }): string;
@@ -0,0 +1,4 @@
1
+ export function wrappableDID(identity) {
2
+ const longForm = identity.longForm;
3
+ return typeof longForm === 'string' ? longForm : identity.id;
4
+ }
package/package.json CHANGED
@@ -1,6 +1,53 @@
1
1
  {
2
2
  "name": "@kokuin/vault",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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
  }