@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.
@@ -0,0 +1,507 @@
1
+ import { nobleCrypto } from '@kokuin/crypto';
2
+ import { compareRecordDecisionHLC, parseCanonicalHLC, RecordContentRefusalError, recordPayloadDigest, recordPayloadMatches, verifyRecordOp, verifySignedRecord } from '@kokuin/records';
3
+ import { normalizeDID } from '@kokuin/token';
4
+ import { decodeVaultRecord, encodeVaultRecordPayload, parseVaultRecordMeta, VAULT_RECORD_TYPES, VaultRecordPayloadError, vaultRecordMeta } from './records.js';
5
+ const KEY = 'vault.key';
6
+ const BRANCH = 'vault.key-branch';
7
+ const WRAPPING = 'vault.wrapping';
8
+ const ENTRY = 'vault.entry';
9
+ const REVOCATION = 'vault.revocation';
10
+ function requestFor({ op, record, store, transportContext, verb }) {
11
+ const getMany = store.getMany;
12
+ const read = {
13
+ get: (key)=>store.get(key),
14
+ list: (types)=>store.list(types),
15
+ ...getMany === undefined ? {} : {
16
+ getMany: (keys)=>getMany.call(store, keys)
17
+ }
18
+ };
19
+ return {
20
+ source: 'record',
21
+ op,
22
+ owner: op.claim.owner,
23
+ issuer: op.issuer,
24
+ verb,
25
+ recordKey: {
26
+ type: op.claim.type,
27
+ owner: op.claim.owner,
28
+ id: op.claim.id
29
+ },
30
+ transportContext,
31
+ record,
32
+ store: read
33
+ };
34
+ }
35
+ async function authorized(params, request) {
36
+ return await params.validateConsumerMetadata({
37
+ value: request.op.claim.meta.consumer,
38
+ request
39
+ }) && await params.authority.authorize(request);
40
+ }
41
+ function entryOrder(claim) {
42
+ const meta = parseVaultRecordMeta(ENTRY, claim);
43
+ const stamp = meta === null ? null : parseCanonicalHLC(meta.contentHLC);
44
+ if (meta === null || stamp === null) throw new RecordContentRefusalError({
45
+ message: 'Entry content stamp is malformed'
46
+ });
47
+ const node = Array.from({
48
+ length: stamp.nodeID.length
49
+ }, (_, i)=>stamp.nodeID.charCodeAt(i));
50
+ return [
51
+ stamp.wallTime,
52
+ stamp.counter,
53
+ ...node,
54
+ -1,
55
+ meta.keyVersion
56
+ ];
57
+ }
58
+ function keyOrder(claim) {
59
+ const meta = parseVaultRecordMeta(KEY, claim);
60
+ if (meta === null) throw new RecordContentRefusalError({
61
+ message: 'Key metadata is malformed'
62
+ });
63
+ return [
64
+ meta.version,
65
+ claim.deleted ? 2 : meta.state === 'retired' ? 1 : 0
66
+ ];
67
+ }
68
+ async function validStructure(type, op, options) {
69
+ const meta = await vaultRecordMeta({
70
+ ...options,
71
+ type,
72
+ claim: op.claim
73
+ });
74
+ if (meta === null) return false;
75
+ if (type === ENTRY) {
76
+ const entry = meta;
77
+ return entry !== null && parseCanonicalHLC(op.claim.hlc) !== null && compareRecordDecisionHLC(entry.contentHLC, op.claim.hlc) <= 0;
78
+ }
79
+ return true;
80
+ }
81
+ async function decodedAs({ record, op, type, ...options }) {
82
+ if (op.claim.deleted || !await recordPayloadMatches({
83
+ ...options,
84
+ record,
85
+ claim: op.claim
86
+ })) return null;
87
+ try {
88
+ const decoded = await decodeVaultRecord({
89
+ ...options,
90
+ record,
91
+ recordMeta: op.claim.meta
92
+ });
93
+ return decoded.type === type ? decoded : null;
94
+ } catch (error) {
95
+ if (!(error instanceof VaultRecordPayloadError)) throw error;
96
+ return null;
97
+ }
98
+ }
99
+ function keyAtLeast(owner, keyID, version) {
100
+ return {
101
+ type: KEY,
102
+ owner,
103
+ id: keyID,
104
+ satisfiedBy: (op)=>{
105
+ const meta = parseVaultRecordMeta(KEY, op.claim);
106
+ return op.claim.owner === owner && meta !== null && meta.version >= version;
107
+ }
108
+ };
109
+ }
110
+ function exactBranch(op, meta) {
111
+ return {
112
+ type: BRANCH,
113
+ owner: op.claim.owner,
114
+ id: meta.branchRecordID,
115
+ satisfiedBy: (branch)=>{
116
+ const info = parseVaultRecordMeta(BRANCH, branch.claim);
117
+ return info !== null && branch.claim.owner === op.claim.owner && !branch.claim.deleted && info.keyID === meta.keyID && info.keyVersion === meta.keyVersion && info.branchID === meta.branchID;
118
+ }
119
+ };
120
+ }
121
+ function dependencies(type, op) {
122
+ if (type === KEY) return [];
123
+ const meta = parseVaultRecordMeta(type, op.claim);
124
+ if (meta === null) return [];
125
+ const key = {
126
+ type: KEY,
127
+ owner: op.claim.owner,
128
+ id: meta.keyID
129
+ };
130
+ if (type === REVOCATION) return [
131
+ key
132
+ ];
133
+ const version = op.claim.meta.keyVersion;
134
+ if (type === BRANCH) return [
135
+ keyAtLeast(op.claim.owner, meta.keyID, version)
136
+ ];
137
+ const result = [
138
+ type === WRAPPING && op.claim.deleted ? key : keyAtLeast(op.claim.owner, meta.keyID, version)
139
+ ];
140
+ if (type === WRAPPING && op.claim.deleted) return result;
141
+ const { branchID, branchRecordID } = op.claim.meta;
142
+ if (typeof branchID === 'string' && typeof branchRecordID === 'string') result.push(exactBranch(op, {
143
+ keyID: meta.keyID,
144
+ keyVersion: version,
145
+ branchID,
146
+ branchRecordID
147
+ }));
148
+ return result;
149
+ }
150
+ async function keyOwnerMatches(params, op, ctx) {
151
+ // Apply serves the chunk's batched view. Holder proofs outside apply read the store.
152
+ const read = ctx.decision ?? ((key)=>ctx.store.get(key));
153
+ const decision = await read({
154
+ type: KEY,
155
+ owner: op.claim.owner,
156
+ id: op.claim.meta.keyID
157
+ });
158
+ if (decision === null) return false;
159
+ const keys = await Promise.all(decision.copies.map((record)=>{
160
+ return verifySignedRecord({
161
+ record,
162
+ opKind: params.opKind,
163
+ methods: params.methods,
164
+ crypto: params?.crypto
165
+ });
166
+ }));
167
+ for (const key of keys){
168
+ if (key !== null && key.claim.owner === op.claim.owner && await vaultRecordMeta({
169
+ ...params,
170
+ type: KEY,
171
+ claim: key.claim
172
+ }) !== null) return true;
173
+ }
174
+ return false;
175
+ }
176
+ async function revoked({ params, op, store, descriptors }) {
177
+ const denied = new Set((await params.portsFor(store).listRevocations({
178
+ ownerDID: op.claim.owner,
179
+ keyID: op.claim.meta.keyID
180
+ })).map((did)=>normalizeDID(did)));
181
+ const recipients = [
182
+ op.claim.meta.recipient,
183
+ ...descriptors.filter((d)=>d.kind === 'did').map((d)=>d.params.recipient)
184
+ ];
185
+ for (const recipient of recipients){
186
+ if (recipient === null || recipient === undefined) continue;
187
+ if (typeof recipient !== 'string') return true;
188
+ try {
189
+ if (denied.has(normalizeDID(recipient))) return true;
190
+ } catch {
191
+ return true;
192
+ }
193
+ }
194
+ return false;
195
+ }
196
+ async function authorizeBranch(params, op, ctx) {
197
+ const meta = await vaultRecordMeta({
198
+ ...params,
199
+ type: BRANCH,
200
+ claim: op.claim
201
+ });
202
+ const decoded = await decodedAs({
203
+ ...params,
204
+ record: ctx.record,
205
+ op,
206
+ type: BRANCH
207
+ });
208
+ if (meta === null || decoded === null) return false;
209
+ const payload = decoded.payload;
210
+ const introducing = await verifyRecordOp({
211
+ opJWT: payload.opJWT,
212
+ opKind: params.opKind,
213
+ methods: params.methods,
214
+ crypto: params?.crypto
215
+ });
216
+ const key = introducing === null ? null : await vaultRecordMeta({
217
+ ...params,
218
+ type: KEY,
219
+ claim: introducing.claim
220
+ });
221
+ if (introducing === null || key === null || introducing.claim.deleted || introducing.claim.id !== meta.keyID || introducing.claim.owner !== op.claim.owner || key.version !== meta.keyVersion || introducing.opHash !== payload.opHash || introducing.claim.hlc !== payload.hlc || introducing.issuer !== normalizeDID(payload.authorDID) || meta.branchID !== `${payload.hlc}:${payload.opHash}`) return false;
222
+ const keyPayload = encodeVaultRecordPayload({
223
+ type: KEY,
224
+ payload: {
225
+ suite: payload.suite,
226
+ state: key.state
227
+ }
228
+ });
229
+ if (introducing.claim.payloadDigest !== await recordPayloadDigest({
230
+ ...params,
231
+ payload: keyPayload
232
+ })) return false;
233
+ // The embedded op is independent authenticated evidence and gets its own consumer decision.
234
+ const keyRecord = {
235
+ type: KEY,
236
+ id: introducing.claim.id,
237
+ owner: introducing.claim.owner,
238
+ hlc: introducing.claim.hlc,
239
+ payload: keyPayload,
240
+ opJWT: payload.opJWT,
241
+ opHash: introducing.opHash
242
+ };
243
+ return await authorized(params, requestFor({
244
+ op: introducing,
245
+ record: keyRecord,
246
+ store: ctx.store,
247
+ transportContext: ctx.transportContext,
248
+ verb: 'administer'
249
+ })) && await authorized(params, requestFor({
250
+ op,
251
+ record: ctx.record,
252
+ store: ctx.store,
253
+ transportContext: ctx.transportContext,
254
+ verb: 'administer'
255
+ }));
256
+ }
257
+ function createType(type, params, bindReceiver = true) {
258
+ const definition = {
259
+ type,
260
+ policy: type === KEY ? {
261
+ kind: 'monotonic',
262
+ version: keyOrder
263
+ } : type === ENTRY ? {
264
+ kind: 'monotonic',
265
+ version: entryOrder
266
+ } : type === BRANCH ? {
267
+ kind: 'immutable'
268
+ } : {
269
+ kind: 'lww'
270
+ },
271
+ dependsOn: type === KEY ? [] : type === ENTRY || type === WRAPPING ? [
272
+ KEY,
273
+ BRANCH
274
+ ] : [
275
+ KEY
276
+ ],
277
+ precheck: async ({ op })=>await validStructure(type, op, params),
278
+ dependencies: ({ record: _record, op })=>dependencies(type, op),
279
+ async authorize ({ op, ctx }) {
280
+ // Enforce the factory's replay domain even when the engine is misconfigured.
281
+ const checked = await verifySignedRecord({
282
+ record: ctx.record,
283
+ opKind: params.opKind,
284
+ methods: params.methods,
285
+ crypto: params?.crypto
286
+ });
287
+ if (checked === null || checked.opHash !== op.opHash) return false;
288
+ if (!await validStructure(type, op, params) || !await recordPayloadMatches({
289
+ ...params,
290
+ record: ctx.record,
291
+ claim: op.claim
292
+ })) return false;
293
+ if (type !== KEY && !await keyOwnerMatches(params, op, ctx)) return false;
294
+ if (type === BRANCH) return await authorizeBranch(params, op, ctx);
295
+ if (!op.claim.deleted) {
296
+ const decoded = await decodedAs({
297
+ ...params,
298
+ record: ctx.record,
299
+ op,
300
+ type
301
+ });
302
+ if (decoded === null) return false;
303
+ if (decoded.type === KEY && decoded.payload.state !== op.claim.meta.state) return false;
304
+ if (decoded.type === WRAPPING && await revoked({
305
+ params,
306
+ op,
307
+ store: ctx.store,
308
+ descriptors: decoded.payload.descriptors
309
+ })) return false;
310
+ }
311
+ if (!await authorized(params, requestFor({
312
+ op,
313
+ record: ctx.record,
314
+ store: ctx.store,
315
+ transportContext: ctx.transportContext,
316
+ verb: 'administer'
317
+ }))) return false;
318
+ return type !== WRAPPING || !bindReceiver || await authorized(params, requestFor({
319
+ op,
320
+ record: ctx.record,
321
+ store: ctx.store,
322
+ transportContext: ctx.transportContext,
323
+ verb: 'read'
324
+ }));
325
+ },
326
+ async visibleTo ({ record, ctx }) {
327
+ if (ctx.opKind !== params.opKind) return false;
328
+ const op = await verifySignedRecord({
329
+ record,
330
+ opKind: params.opKind,
331
+ methods: params.methods,
332
+ crypto: params?.crypto
333
+ });
334
+ if (op === null || !await validStructure(type, op, params) || !await recordPayloadMatches({
335
+ ...params,
336
+ record,
337
+ claim: op.claim
338
+ })) return false;
339
+ if (!op.claim.deleted) {
340
+ const decoded = await decodedAs({
341
+ ...params,
342
+ record,
343
+ op,
344
+ type
345
+ });
346
+ if (decoded === null) return false;
347
+ if (decoded.type === WRAPPING && await revoked({
348
+ params,
349
+ op,
350
+ store: ctx.store,
351
+ descriptors: decoded.payload.descriptors
352
+ })) return false;
353
+ }
354
+ return await authorized(params, requestFor({
355
+ op,
356
+ record,
357
+ store: ctx.store,
358
+ transportContext: ctx.transportContext,
359
+ verb: 'read'
360
+ }));
361
+ },
362
+ async lockKeys ({ incoming, stored }) {
363
+ const keys = new Map();
364
+ const records = [
365
+ incoming,
366
+ ...stored?.copies ?? []
367
+ ];
368
+ const ops = await Promise.all(records.map((record)=>{
369
+ return verifySignedRecord({
370
+ record,
371
+ opKind: params.opKind,
372
+ methods: params.methods,
373
+ crypto: params?.crypto
374
+ });
375
+ }));
376
+ for (const op of ops){
377
+ if (op === null) continue;
378
+ const keyID = op.claim.type === KEY ? op.claim.id : op.claim.meta.keyID;
379
+ if (typeof keyID !== 'string' || keyID === '') continue;
380
+ const key = JSON.stringify([
381
+ op.claim.owner,
382
+ keyID
383
+ ]);
384
+ keys.set(key, {
385
+ type: KEY,
386
+ key
387
+ });
388
+ }
389
+ return [
390
+ ...keys.values()
391
+ ];
392
+ }
393
+ };
394
+ if (type === KEY) {
395
+ // Equal-version branches remain independently proven; the current head uses claim digest.
396
+ definition.onEqual = ()=>'fork';
397
+ }
398
+ if (type === ENTRY) {
399
+ definition.afterAuthorize = async ({ record, store })=>{
400
+ await params.portsFor(store).retainEntryCandidate(record);
401
+ };
402
+ }
403
+ if (type === WRAPPING || type === REVOCATION) {
404
+ definition.afterApply = async ({ record, store })=>{
405
+ const op = await verifySignedRecord({
406
+ record,
407
+ opKind: params.opKind,
408
+ methods: params.methods,
409
+ crypto: params?.crypto
410
+ });
411
+ if (op === null) throw new Error('Applied record signature is invalid');
412
+ await params.portsFor(store).dropRevokedWrappings({
413
+ ownerDID: op.claim.owner,
414
+ keyID: op.claim.meta.keyID
415
+ });
416
+ };
417
+ }
418
+ return definition;
419
+ }
420
+ function captureParams(input) {
421
+ const getter = Object.getOwnPropertyDescriptor(input, 'methods')?.get;
422
+ const methods = input.methods?.map((method)=>{
423
+ return {
424
+ ...method,
425
+ resolve: method.resolve.bind(method),
426
+ resolveHistoric: method.resolveHistoric?.bind(method),
427
+ resolveDenySet: method.resolveDenySet?.bind(method),
428
+ resolveAgreementKey: method.resolveAgreementKey?.bind(method)
429
+ };
430
+ });
431
+ return {
432
+ ...input,
433
+ crypto: input.crypto ?? nobleCrypto,
434
+ // Store adapters supply an accessor bound to their current transaction.
435
+ get methods () {
436
+ return getter === undefined ? methods : getter.call(input);
437
+ }
438
+ };
439
+ }
440
+ /** One explicit replay domain and consumer policy for the five generic record types. */ export function vaultRecordTypes(input) {
441
+ const params = captureParams(input);
442
+ if (typeof params.opKind !== 'string' || params.opKind.length === 0) throw new TypeError('An explicit operation kind is required');
443
+ return new Map(VAULT_RECORD_TYPES.map((type)=>[
444
+ type,
445
+ createType(type, params)
446
+ ]));
447
+ }
448
+ /** Only wrappings can prove key holding, regardless of other records' metadata. */ export function vaultHolderTypes(types) {
449
+ const wrapping = types.get(WRAPPING);
450
+ return new Map(wrapping === undefined ? [] : [
451
+ [
452
+ WRAPPING,
453
+ wrapping
454
+ ]
455
+ ]);
456
+ }
457
+ export function vaultKeyVersionReader(input) {
458
+ const { store } = input;
459
+ const params = captureParams(input);
460
+ return async ({ owner, keyID })=>{
461
+ const stored = await store.get({
462
+ type: KEY,
463
+ owner,
464
+ id: keyID
465
+ });
466
+ const copy = stored?.copies[0];
467
+ const op = copy === undefined ? null : await verifySignedRecord({
468
+ record: copy,
469
+ opKind: params.opKind,
470
+ methods: params.methods,
471
+ crypto: params?.crypto
472
+ });
473
+ const meta = op === null ? null : await vaultRecordMeta({
474
+ ...params,
475
+ type: KEY,
476
+ claim: op.claim
477
+ });
478
+ return op === null || meta === null || op.claim.deleted || op.claim.owner !== owner ? null : meta.version;
479
+ };
480
+ }
481
+ export function vaultProofAuthorizer(input) {
482
+ const { transportContext, store } = input;
483
+ const params = captureParams(input);
484
+ const wrapping = createType(WRAPPING, params, false);
485
+ return async ({ record, stored })=>{
486
+ if (record.type !== WRAPPING) return false;
487
+ const op = await verifySignedRecord({
488
+ record,
489
+ opKind: params.opKind,
490
+ methods: params.methods,
491
+ crypto: params?.crypto
492
+ });
493
+ if (op === null) return false;
494
+ return await wrapping.authorize({
495
+ op,
496
+ ctx: {
497
+ record,
498
+ stored,
499
+ store,
500
+ transportContext,
501
+ // Generic vault policy delegates all authority to the consumer callback.
502
+ resolveController: async ()=>null,
503
+ verifyCapability: async ()=>false
504
+ }
505
+ });
506
+ };
507
+ }
@@ -0,0 +1,110 @@
1
+ import type { RecordClaim, SignedRecord } from '@kokuin/records';
2
+ import type { CryptoOptions } from '@kokuin/token';
3
+ import type { EncryptEntryResult, WrapResult } from './suite.js';
4
+ export type VaultRecordPayloadErrorParams = {
5
+ type: string;
6
+ id: string;
7
+ reason: string;
8
+ cause?: unknown;
9
+ };
10
+ export declare const VAULT_OP_KIND = "kokuin/vault-op/v1";
11
+ export declare const VAULT_RECORD_TYPES: readonly ["vault.key", "vault.key-branch", "vault.wrapping", "vault.entry", "vault.revocation"];
12
+ export type VaultRecordType = (typeof VAULT_RECORD_TYPES)[number];
13
+ export type VaultRecordPayloads = {
14
+ 'vault.key': {
15
+ suite: number;
16
+ state: 'active' | 'retired';
17
+ };
18
+ 'vault.key-branch': {
19
+ authorDID: string;
20
+ hlc: string;
21
+ opJWT: string;
22
+ opHash: string;
23
+ suite: number;
24
+ };
25
+ 'vault.wrapping': WrapResult;
26
+ 'vault.entry': EncryptEntryResult;
27
+ 'vault.revocation': Record<string, never>;
28
+ };
29
+ export type VaultEntryMetadata = {
30
+ kind: string;
31
+ label: string;
32
+ attributes: Record<string, string>;
33
+ };
34
+ type BranchReference = {
35
+ branchID: string;
36
+ branchRecordID: string;
37
+ };
38
+ export type VaultRecordMetas = {
39
+ 'vault.key': {
40
+ keyID: string;
41
+ keyUnique: string;
42
+ version: number;
43
+ state: 'active' | 'retired' | 'deleted';
44
+ consumer: unknown;
45
+ };
46
+ 'vault.key-branch': {
47
+ keyID: string;
48
+ keyVersion: number;
49
+ branchID: string;
50
+ consumer: unknown;
51
+ };
52
+ 'vault.wrapping': {
53
+ keyID: string;
54
+ keyVersion: number;
55
+ recipient: string | null;
56
+ consumer: unknown;
57
+ } & Partial<BranchReference>;
58
+ 'vault.entry': {
59
+ keyID: string;
60
+ keyVersion: number;
61
+ contentHLC: string;
62
+ consumer: unknown;
63
+ } & Partial<BranchReference> & Partial<VaultEntryMetadata>;
64
+ 'vault.revocation': {
65
+ keyID: string;
66
+ revokedDID: string;
67
+ consumer: unknown;
68
+ };
69
+ };
70
+ export type DecodedVaultRecord = {
71
+ [Type in VaultRecordType]: {
72
+ type: Type;
73
+ id: string;
74
+ owner: string;
75
+ hlc: string;
76
+ meta: VaultRecordMetas[Type];
77
+ payload: VaultRecordPayloads[Type];
78
+ };
79
+ }[VaultRecordType];
80
+ export declare class VaultRecordPayloadError extends Error {
81
+ #private;
82
+ constructor(params: VaultRecordPayloadErrorParams);
83
+ get type(): string;
84
+ get id(): string;
85
+ }
86
+ export type VaultRevocationRecordIDParams = {
87
+ keyID: string;
88
+ recipientDID: string;
89
+ };
90
+ export declare function vaultRevocationRecordID({ recipientDID, keyID, }: VaultRevocationRecordIDParams): string;
91
+ /** Structural metadata only. Consumer evidence is checked by the injected validator. */
92
+ export declare function parseVaultRecordMeta<Type extends VaultRecordType>(type: Type, claim: RecordClaim): VaultRecordMetas[Type] | null;
93
+ export type VaultRecordMetaParams<Type extends VaultRecordType> = {
94
+ type: Type;
95
+ claim: RecordClaim;
96
+ } & CryptoOptions;
97
+ export declare function vaultRecordMeta<Type extends VaultRecordType>({ claim, type, ...options }: VaultRecordMetaParams<Type>): Promise<VaultRecordMetas[Type] | null>;
98
+ /** Canonical JSON with binary fields encoded as unpadded base64url. */
99
+ export type EncodeVaultRecordPayloadParams<Type extends VaultRecordType> = {
100
+ type: Type;
101
+ payload: VaultRecordPayloads[Type];
102
+ };
103
+ export declare function encodeVaultRecordPayload<Type extends VaultRecordType>({ payload, type, }: EncodeVaultRecordPayloadParams<Type>): Uint8Array;
104
+ /** Pure codec. Signature and payload-digest verification belong to the caller. */
105
+ export type DecodeVaultRecordParams = {
106
+ record: Pick<SignedRecord, 'type' | 'id' | 'owner' | 'hlc' | 'payload'>;
107
+ recordMeta: Record<string, unknown>;
108
+ } & CryptoOptions;
109
+ export declare function decodeVaultRecord({ recordMeta, record, ...options }: DecodeVaultRecordParams): Promise<DecodedVaultRecord>;
110
+ export {};