@kokuin/vault 0.1.0 → 0.7.1
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 +108 -1
- package/lib/branch.js +2 -3
- package/lib/digest.d.ts +27 -8
- package/lib/digest.js +63 -41
- package/lib/errors.d.ts +38 -13
- package/lib/errors.js +43 -25
- package/lib/factors.d.ts +18 -6
- package/lib/factors.js +12 -6
- package/lib/id.d.ts +12 -3
- package/lib/id.js +14 -6
- package/lib/index.d.ts +7 -1
- package/lib/index.js +1 -1
- package/lib/key-cache.d.ts +22 -4
- package/lib/key-cache.js +4 -4
- package/lib/record-types.d.ts +17 -6
- package/lib/record-types.js +269 -79
- package/lib/records.d.ts +29 -10
- package/lib/records.js +57 -14
- package/lib/suite.d.ts +3 -3
- package/lib/suite.js +127 -31
- package/package.json +8 -7
package/README.md
CHANGED
|
@@ -65,10 +65,117 @@ GCM unwrap failures throw `VaultSecretRejected` with the original failure as `ca
|
|
|
65
65
|
Missing factors and malformed descriptors retain their distinct validation errors.
|
|
66
66
|
Entry authentication failures throw `VaultTampered` with the original cause.
|
|
67
67
|
|
|
68
|
-
`createVaultKeyID(owner, unique)` hashes the exact owner bytes concatenated with unique bytes using BLAKE3.
|
|
68
|
+
`createVaultKeyID({ owner, unique })` hashes the exact owner bytes concatenated with unique bytes using BLAKE3.
|
|
69
69
|
Its base36 multibase encoding frames unsigned varints for namespace `0xb6`, key type `31`, and digest length `32`.
|
|
70
70
|
Callers normalise owner DIDs before minting IDs used as equality keys.
|
|
71
71
|
Recipient DIDs retain their resolvable long form. `wrappableDID` selects that form when available.
|
|
72
72
|
|
|
73
73
|
The package also exports the public key, wrapping, entry-set and descriptor digest helpers,
|
|
74
74
|
pure factor reconstruction and eligibility checks, a cloning TTL key cache, and an optional in-memory PIN throttle.
|
|
75
|
+
|
|
76
|
+
## Crypto provider migration to 0.7.0
|
|
77
|
+
|
|
78
|
+
All functions below accept top-level `crypto?` in named params objects and now require `await`.
|
|
79
|
+
|
|
80
|
+
| Export | Result |
|
|
81
|
+
| --- | --- |
|
|
82
|
+
| `digestParts(params: DigestPartsParams)` | `Promise<string>` |
|
|
83
|
+
| `vaultKeyDigest(params: VaultKeyDigestParams)` | `Promise<string>` |
|
|
84
|
+
| `vaultWrappingDigest(params: VaultWrappingDigestParams)` | `Promise<string>` |
|
|
85
|
+
| `vaultEntriesDigest(params: VaultEntriesDigestParams)` | `Promise<string>` |
|
|
86
|
+
| `vaultEntryDigest(params: VaultEntryDigestParams)` | `Promise<string>` |
|
|
87
|
+
| `descriptorDigest(params: DescriptorDigestParams)` | `Promise<string>` |
|
|
88
|
+
| `createVaultKeyID(params: CreateVaultKeyIDParams)` | `Promise<string>` |
|
|
89
|
+
| `createVaultKeyReference(params: CreateVaultKeyReferenceParams)` | `Promise<{ keyID: string; keyUnique: string }>` |
|
|
90
|
+
| `vaultRecordMeta(params: VaultRecordMetaParams)` | `Promise<VaultRecordMetas[Type] \| null>` |
|
|
91
|
+
| `decodeVaultRecord(params: DecodeVaultRecordParams)` | `Promise<DecodedVaultRecord>` |
|
|
92
|
+
|
|
93
|
+
`checkDescriptorDigest({ descriptors, expectedDescriptorDigest, crypto? })` now returns `Promise<void>`.
|
|
94
|
+
`VaultRecordTypeParams`, `WrapParams` and `UnwrapParams` gain `crypto?`.
|
|
95
|
+
`vaultRecordTypes` and `vaultProofAuthorizer` capture provider options at construction.
|
|
96
|
+
`vaultKeyVersionReader({ store, opKind, methods?, crypto? })` captures the provider and returns its existing asynchronous callback.
|
|
97
|
+
`vaultHolderTypes(types)`, `getSuite`, wrapping and unwrapping retain their return contracts.
|
|
98
|
+
|
|
99
|
+
Public metadata validation still checks owner/key-ID commitments. Internal structural parsing does not replace that validation boundary.
|
|
100
|
+
`compareVaultBranches` and `selectWinningBranch` remain synchronous and consume verified `contentDigest` values.
|
|
101
|
+
Canonical IDs, digests and encrypted formats remain unchanged. Provider errors propagate through decoding and authorisation.
|
|
102
|
+
SHA-256, X25519, HKDF, AES-GCM, BIP39 and randomness retain their existing implementations.
|
|
103
|
+
|
|
104
|
+
```ts
|
|
105
|
+
const { keyID, keyUnique } = await createVaultKeyReference({ owner: ownerDID, unique, crypto })
|
|
106
|
+
const meta = await vaultRecordMeta({ type: 'vault.key', claim, crypto })
|
|
107
|
+
const decoded = await decodeVaultRecord({ record, recordMeta, crypto })
|
|
108
|
+
await checkDescriptorDigest({ descriptors, expectedDescriptorDigest, crypto })
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
See [provider adoption](../../docs/reference/crypto-provider.md) for selection and strict verification.
|
|
112
|
+
|
|
113
|
+
## Named params migration
|
|
114
|
+
|
|
115
|
+
| Export | Named params type | Fields |
|
|
116
|
+
| --- | --- | --- |
|
|
117
|
+
| `new VaultError` | `VaultErrorParams` | `message, options` |
|
|
118
|
+
| `new NoAvailableFactor` | `NoAvailableFactorParams` | `kind` |
|
|
119
|
+
| `new InvalidVaultFactors` | `InvalidVaultFactorsParams` | `reason` |
|
|
120
|
+
| `new UnsupportedVaultSuite` | `UnsupportedVaultSuiteParams` | `suite` |
|
|
121
|
+
| `new VaultTampered` | `VaultTamperedParams` | `message, options?` |
|
|
122
|
+
| `new VaultSecretRejected` | `VaultSecretRejectedParams` | `kinds, options?` |
|
|
123
|
+
| `new VaultPinRejected` | `VaultPinRejectedParams` | `keyID, options` |
|
|
124
|
+
| `KeyCache.set` | `KeyCacheSetParams` | `keyID, contentKey, keyVersion, branchID` |
|
|
125
|
+
|
|
126
|
+
`VaultRecordPayloadErrorParams` names the existing constructor object without changing its fields.
|
|
127
|
+
|
|
128
|
+
These signature and typing changes preserve cryptographic results, error causes, ordering and storage behaviour.
|
|
129
|
+
|
|
130
|
+
Additional APIs use the same flat params convention.
|
|
131
|
+
|
|
132
|
+
| Export | Named params type | Previous positional form |
|
|
133
|
+
| --- | --- | --- |
|
|
134
|
+
| `decodeVaultRecord` | `DecodeVaultRecordParams` | `decodeVaultRecord(params: DecodeVaultRecordParams)` |
|
|
135
|
+
| `encodeVaultRecordPayload` | `EncodeVaultRecordPayloadParams` | `encodeVaultRecordPayload(type: Type, payload: VaultRecordPayloads[Type])` |
|
|
136
|
+
| `vaultRecordMeta` | `VaultRecordMetaParams` | `vaultRecordMeta(params: VaultRecordMetaParams)` |
|
|
137
|
+
| `vaultRevocationRecordID` | `VaultRevocationRecordIDParams` | `vaultRevocationRecordID(keyID: string, recipientDID: string)` |
|
|
138
|
+
| `digestParts` | `DigestPartsParams` | `digestParts(params: DigestPartsParams)` |
|
|
139
|
+
| `vaultKeyDigest` | `VaultKeyDigestParams` | `vaultKeyDigest(params: VaultKeyDigestParams)` |
|
|
140
|
+
| `vaultWrappingDigest` | `VaultWrappingDigestParams` | `vaultWrappingDigest(params: VaultWrappingDigestParams)` |
|
|
141
|
+
| `vaultEntriesDigest` | `VaultEntriesDigestParams` | `vaultEntriesDigest(params: VaultEntriesDigestParams)` |
|
|
142
|
+
| `vaultEntryDigest` | `VaultEntryDigestParams` | `vaultEntryDigest(params: VaultEntryDigestParams)` |
|
|
143
|
+
| `descriptorDigest` | `DescriptorDigestParams` | `descriptorDigest(params: DescriptorDigestParams)` |
|
|
144
|
+
| `wrappingNamesExcludedRecipient` | `WrappingNamesExcludedRecipientParams` | `wrappingNamesExcludedRecipient(wrapping: { recipientDID: string \| null; factors: ReadonlyArray<FactorDescriptor> }, excluded: ReadonlySet<string>)` |
|
|
145
|
+
| `satisfiableFactors` | `SatisfiableFactorsParams` | `satisfiableFactors(descriptors: Array<FactorDescriptor>, identity: KeyAgreementIdentity \| null)` |
|
|
146
|
+
| `factorsFromDescriptors` | `FactorsFromDescriptorsParams` | `factorsFromDescriptors(descriptors: Array<FactorDescriptor>, inputs?: FactorInputs)` |
|
|
147
|
+
| `createVaultKeyID` | `CreateVaultKeyIDParams` | `createVaultKeyID(params: CreateVaultKeyIDParams)` |
|
|
148
|
+
| `createVaultKeyReference` | `CreateVaultKeyReferenceParams` | `createVaultKeyReference(params: CreateVaultKeyReferenceParams)` |
|
|
149
|
+
| `vaultKeyVersionReader` | `VaultKeyVersionReaderParams` | `vaultKeyVersionReader(store: RecordStoreAdapter, input: Pick<VaultRecordTypeParams, 'opKind' \| 'methods' \| 'crypto'>)` |
|
|
150
|
+
| `vaultProofAuthorizer` | `VaultProofAuthorizerParams` | `vaultProofAuthorizer(input: VaultRecordTypeParams, store: RecordStoreAdapter, transportContext?: unknown)` |
|
|
151
|
+
|
|
152
|
+
Method and callback contracts follow the same convention.
|
|
153
|
+
|
|
154
|
+
| API | Named params type | Previous form |
|
|
155
|
+
| --- | --- | --- |
|
|
156
|
+
| `KeyCache.get` | `KeyCacheGetParams` | `get(keyID, keyVersion)` |
|
|
157
|
+
| `KeyCache.has` | `KeyCacheHasParams` | `has(keyID, keyVersion)` |
|
|
158
|
+
| `KeyCache.evictVersion` | `KeyCacheEvictVersionParams` | `evictVersion(keyID, keyVersion)` |
|
|
159
|
+
| `VaultRecordHooks.validateConsumerMetadata` | `VaultRecordHooksValidateConsumerMetadataParams` | `validateConsumerMetadata(value, request)` |
|
|
160
|
+
|
|
161
|
+
Existing params objects also flatten their options fields:
|
|
162
|
+
|
|
163
|
+
| Existing params type | Updated params type | Field migration |
|
|
164
|
+
| --- | --- | --- |
|
|
165
|
+
| `DecodedAsParams` | `DecodedAsParams` | `Nested options fields → top-level fields` |
|
|
166
|
+
|
|
167
|
+
## Cooperative yielding
|
|
168
|
+
|
|
169
|
+
`vaultRecordTypes`, `vaultKeyVersionReader`, and `vaultProofAuthorizer` accept `yield?: boolean` from `@kokuin/token` (`YieldOptions`).
|
|
170
|
+
Their policies forward it through stored-record and introducing-op verification.
|
|
171
|
+
Factory options are captured when created.
|
|
172
|
+
|
|
173
|
+
`yield: false` skips cooperative timers for these signing and verification paths.
|
|
174
|
+
Record `authorize` and `visibleTo` hooks prefer per-call `ctx.yield` over the construction policy.
|
|
175
|
+
Omitting the option preserves the construction policy, default yielding and all cryptographic checks.
|
|
176
|
+
Callers must yield between transactions when disabling yields inside a transaction.
|
|
177
|
+
|
|
178
|
+
Store adapters may provide a `yield` accessor alongside their scoped `methods` accessor to
|
|
179
|
+
`vaultRecordTypes`, `vaultKeyVersionReader` and `vaultProofAuthorizer`. The accessor follows
|
|
180
|
+
the active store scope; ordinary boolean options are captured when the factory is called.
|
|
181
|
+
This lets store-owned transactions suppress cooperative timers without changing any checks.
|
package/lib/branch.js
CHANGED
|
@@ -1,7 +1,6 @@
|
|
|
1
|
-
import { recordClaimDigest } from '@kokuin/records';
|
|
2
1
|
/** Compare authenticated introducing ops by claim digest, then op hash. */ export function compareVaultBranches(left, right) {
|
|
3
|
-
const a =
|
|
4
|
-
const b =
|
|
2
|
+
const a = left.contentDigest;
|
|
3
|
+
const b = right.contentDigest;
|
|
5
4
|
return a < b ? -1 : a > b ? 1 : left.opHash < right.opHash ? -1 : left.opHash > right.opHash ? 1 : 0;
|
|
6
5
|
}
|
|
7
6
|
export function selectWinningBranch(branches) {
|
package/lib/digest.d.ts
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
|
+
import type { CryptoOptions } from '@kokuin/token';
|
|
1
2
|
import type { FactorDescriptor } from './factors.js';
|
|
2
|
-
export
|
|
3
|
+
export type DigestPartsParams = {
|
|
4
|
+
parts: Array<string>;
|
|
5
|
+
} & CryptoOptions;
|
|
6
|
+
export declare function digestParts({ parts, ...options }: DigestPartsParams): Promise<string>;
|
|
3
7
|
export type VaultKeyDigestInput = {
|
|
4
8
|
ownerDID: string;
|
|
5
9
|
suite: number;
|
|
@@ -19,13 +23,28 @@ export type VaultEntryDigestInput = {
|
|
|
19
23
|
ciphertext: string;
|
|
20
24
|
hlc: string;
|
|
21
25
|
};
|
|
22
|
-
export
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
export declare function
|
|
26
|
+
export type VaultKeyDigestParams = {
|
|
27
|
+
key: VaultKeyDigestInput;
|
|
28
|
+
} & CryptoOptions;
|
|
29
|
+
export declare function vaultKeyDigest({ key, ...options }: VaultKeyDigestParams): Promise<string>;
|
|
30
|
+
export type VaultWrappingDigestParams = {
|
|
31
|
+
wrapping: VaultWrappingDigestInput;
|
|
32
|
+
} & CryptoOptions;
|
|
33
|
+
export declare function vaultWrappingDigest({ wrapping, ...options }: VaultWrappingDigestParams): Promise<string>;
|
|
34
|
+
export type VaultEntriesDigestParams = {
|
|
35
|
+
entries: ReadonlyArray<VaultEntryDigestInput>;
|
|
36
|
+
} & CryptoOptions;
|
|
37
|
+
export declare function vaultEntriesDigest({ entries, ...options }: VaultEntriesDigestParams): Promise<string>;
|
|
38
|
+
export type VaultEntryDigestParams = {
|
|
39
|
+
entry: VaultEntryDigestInput;
|
|
40
|
+
} & CryptoOptions;
|
|
41
|
+
export declare function vaultEntryDigest({ entry, ...options }: VaultEntryDigestParams): Promise<string>;
|
|
26
42
|
/** Same canonical descriptor encoding and length framing as the wrapping digest. */
|
|
27
|
-
export
|
|
28
|
-
|
|
43
|
+
export type DescriptorDigestParams = {
|
|
44
|
+
descriptors: Array<FactorDescriptor>;
|
|
45
|
+
} & CryptoOptions;
|
|
46
|
+
export declare function descriptorDigest({ descriptors, ...options }: DescriptorDigestParams): Promise<string>;
|
|
47
|
+
export declare function checkDescriptorDigest(params: CryptoOptions & {
|
|
29
48
|
descriptors: Array<FactorDescriptor>;
|
|
30
49
|
expectedDescriptorDigest: string;
|
|
31
|
-
}): void
|
|
50
|
+
}): Promise<void>;
|
package/lib/digest.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { nobleCrypto } from '@kokuin/crypto';
|
|
2
2
|
import { fromUTF, toB64U } from '@sozai/codec';
|
|
3
3
|
import { canonicalize } from '@sozai/json';
|
|
4
4
|
import { VaultTampered } from './errors.js';
|
|
@@ -7,54 +7,76 @@ function descriptorJSON(descriptors) {
|
|
|
7
7
|
if (json == null) throw new TypeError('Factor descriptors have no JSON representation');
|
|
8
8
|
return json;
|
|
9
9
|
}
|
|
10
|
-
export function digestParts(parts) {
|
|
10
|
+
export async function digestParts({ parts, ...options }) {
|
|
11
11
|
const framed = parts.map((part)=>`${part.length}:${part}`).join('');
|
|
12
|
-
return toB64U(blake3(
|
|
12
|
+
return toB64U(await (options.crypto ?? nobleCrypto).blake3({
|
|
13
|
+
input: fromUTF(framed),
|
|
13
14
|
dkLen: 32
|
|
14
15
|
}));
|
|
15
16
|
}
|
|
16
|
-
export function vaultKeyDigest(key) {
|
|
17
|
-
return digestParts(
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
17
|
+
export function vaultKeyDigest({ key, ...options }) {
|
|
18
|
+
return digestParts({
|
|
19
|
+
...options,
|
|
20
|
+
parts: [
|
|
21
|
+
key.ownerDID,
|
|
22
|
+
String(key.suite),
|
|
23
|
+
String(key.version),
|
|
24
|
+
key.state
|
|
25
|
+
]
|
|
26
|
+
});
|
|
27
|
+
}
|
|
28
|
+
export function vaultWrappingDigest({ wrapping, ...options }) {
|
|
29
|
+
return digestParts({
|
|
30
|
+
...options,
|
|
31
|
+
parts: [
|
|
32
|
+
wrapping.wrappingID,
|
|
33
|
+
wrapping.recipientDID ?? '',
|
|
34
|
+
wrapping.iv,
|
|
35
|
+
wrapping.wrappedKey,
|
|
36
|
+
descriptorJSON(wrapping.factors)
|
|
37
|
+
]
|
|
38
|
+
});
|
|
39
|
+
}
|
|
40
|
+
export function vaultEntriesDigest({ entries, ...options }) {
|
|
34
41
|
const ordered = [
|
|
35
42
|
...entries
|
|
36
43
|
].sort((left, right)=>{
|
|
37
44
|
return left.entryID < right.entryID ? -1 : left.entryID > right.entryID ? 1 : 0;
|
|
38
45
|
});
|
|
39
|
-
return digestParts(
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
}
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
46
|
+
return digestParts({
|
|
47
|
+
...options,
|
|
48
|
+
parts: ordered.flatMap((entry)=>[
|
|
49
|
+
entry.entryID,
|
|
50
|
+
entry.iv,
|
|
51
|
+
entry.ciphertext,
|
|
52
|
+
entry.hlc
|
|
53
|
+
])
|
|
54
|
+
});
|
|
55
|
+
}
|
|
56
|
+
export function vaultEntryDigest({ entry, ...options }) {
|
|
57
|
+
return vaultEntriesDigest({
|
|
58
|
+
...options,
|
|
59
|
+
entries: [
|
|
60
|
+
entry
|
|
61
|
+
]
|
|
62
|
+
});
|
|
63
|
+
}
|
|
64
|
+
export function descriptorDigest({ descriptors, ...options }) {
|
|
65
|
+
return digestParts({
|
|
66
|
+
...options,
|
|
67
|
+
parts: [
|
|
68
|
+
descriptorJSON(descriptors)
|
|
69
|
+
]
|
|
70
|
+
});
|
|
71
|
+
}
|
|
72
|
+
export async function checkDescriptorDigest(params) {
|
|
73
|
+
const { descriptors, expectedDescriptorDigest, crypto } = params;
|
|
74
|
+
if (await descriptorDigest({
|
|
75
|
+
descriptors,
|
|
76
|
+
crypto
|
|
77
|
+
}) !== expectedDescriptorDigest) {
|
|
78
|
+
throw new VaultTampered({
|
|
79
|
+
message: 'Vault factor descriptors differ from the trusted digest'
|
|
80
|
+
});
|
|
59
81
|
}
|
|
60
82
|
}
|
package/lib/errors.d.ts
CHANGED
|
@@ -1,43 +1,68 @@
|
|
|
1
|
+
export type VaultErrorParams = {
|
|
2
|
+
message: string;
|
|
3
|
+
options: VaultErrorOptions;
|
|
4
|
+
};
|
|
5
|
+
export type NoAvailableFactorParams = {
|
|
6
|
+
kind: string;
|
|
7
|
+
};
|
|
8
|
+
export type InvalidVaultFactorsParams = {
|
|
9
|
+
reason: string;
|
|
10
|
+
};
|
|
11
|
+
export type UnsupportedVaultSuiteParams = {
|
|
12
|
+
suite: number;
|
|
13
|
+
};
|
|
14
|
+
export type VaultTamperedParams = {
|
|
15
|
+
message: string;
|
|
16
|
+
options?: ErrorOptions;
|
|
17
|
+
};
|
|
18
|
+
export type VaultSecretRejectedParams = {
|
|
19
|
+
kinds: Array<string>;
|
|
20
|
+
options?: ErrorOptions & {
|
|
21
|
+
keyID?: string;
|
|
22
|
+
code?: VaultErrorCode;
|
|
23
|
+
};
|
|
24
|
+
};
|
|
25
|
+
export type VaultPinRejectedParams = {
|
|
26
|
+
keyID: string;
|
|
27
|
+
options: ErrorOptions & {
|
|
28
|
+
attemptsRemaining: number;
|
|
29
|
+
retryAfter: number;
|
|
30
|
+
};
|
|
31
|
+
};
|
|
1
32
|
export type VaultErrorCode = 'VAULT_ERROR' | 'VAULT_FACTOR_UNAVAILABLE' | 'VAULT_FACTORS_INVALID' | 'VAULT_SUITE_UNSUPPORTED' | 'VAULT_TAMPERED' | 'VAULT_SECRET_REJECTED' | 'VAULT_PIN_REJECTED';
|
|
2
33
|
export type VaultErrorOptions = ErrorOptions & {
|
|
3
34
|
code: VaultErrorCode;
|
|
4
35
|
};
|
|
5
36
|
export declare class VaultError extends Error {
|
|
6
37
|
#private;
|
|
7
|
-
constructor(message
|
|
38
|
+
constructor({ message, options }: VaultErrorParams);
|
|
8
39
|
get code(): VaultErrorCode;
|
|
9
40
|
}
|
|
10
41
|
export declare class NoAvailableFactor extends VaultError {
|
|
11
42
|
#private;
|
|
12
|
-
constructor(kind:
|
|
43
|
+
constructor({ kind }: NoAvailableFactorParams);
|
|
13
44
|
get kind(): string;
|
|
14
45
|
}
|
|
15
46
|
export declare class InvalidVaultFactors extends VaultError {
|
|
16
|
-
constructor(reason:
|
|
47
|
+
constructor({ reason }: InvalidVaultFactorsParams);
|
|
17
48
|
}
|
|
18
49
|
export declare class UnsupportedVaultSuite extends VaultError {
|
|
19
50
|
#private;
|
|
20
|
-
constructor(suite:
|
|
51
|
+
constructor({ suite }: UnsupportedVaultSuiteParams);
|
|
21
52
|
get suite(): number;
|
|
22
53
|
}
|
|
23
54
|
export declare class VaultTampered extends VaultError {
|
|
24
|
-
constructor(message
|
|
55
|
+
constructor({ message, options }: VaultTamperedParams);
|
|
25
56
|
}
|
|
26
57
|
/** Authentication failed. The original GCM error is retained as cause. */
|
|
27
58
|
export declare class VaultSecretRejected extends VaultError {
|
|
28
59
|
#private;
|
|
29
|
-
constructor(kinds
|
|
30
|
-
keyID?: string;
|
|
31
|
-
code?: VaultErrorCode;
|
|
32
|
-
});
|
|
60
|
+
constructor({ kinds, options }: VaultSecretRejectedParams);
|
|
33
61
|
get kinds(): Array<string>;
|
|
34
62
|
}
|
|
35
63
|
export declare class VaultPinRejected extends VaultSecretRejected {
|
|
36
64
|
#private;
|
|
37
|
-
constructor(keyID
|
|
38
|
-
attemptsRemaining: number;
|
|
39
|
-
retryAfter: number;
|
|
40
|
-
});
|
|
65
|
+
constructor({ keyID, options }: VaultPinRejectedParams);
|
|
41
66
|
get attemptsRemaining(): number;
|
|
42
67
|
get retryAfter(): number;
|
|
43
68
|
}
|
package/lib/errors.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
export class VaultError extends Error {
|
|
2
2
|
#code;
|
|
3
|
-
constructor(message, options){
|
|
3
|
+
constructor({ message, options }){
|
|
4
4
|
super(message, options);
|
|
5
5
|
this.name = 'VaultError';
|
|
6
6
|
this.#code = options.code;
|
|
@@ -11,9 +11,12 @@ export class VaultError extends Error {
|
|
|
11
11
|
}
|
|
12
12
|
export class NoAvailableFactor extends VaultError {
|
|
13
13
|
#kind;
|
|
14
|
-
constructor(kind){
|
|
15
|
-
super(
|
|
16
|
-
|
|
14
|
+
constructor({ kind }){
|
|
15
|
+
super({
|
|
16
|
+
message: `No available vault factor of kind "${kind}" on this device`,
|
|
17
|
+
options: {
|
|
18
|
+
code: 'VAULT_FACTOR_UNAVAILABLE'
|
|
19
|
+
}
|
|
17
20
|
});
|
|
18
21
|
this.name = 'NoAvailableFactor';
|
|
19
22
|
this.#kind = kind;
|
|
@@ -23,18 +26,24 @@ export class NoAvailableFactor extends VaultError {
|
|
|
23
26
|
}
|
|
24
27
|
}
|
|
25
28
|
export class InvalidVaultFactors extends VaultError {
|
|
26
|
-
constructor(reason){
|
|
27
|
-
super(
|
|
28
|
-
|
|
29
|
+
constructor({ reason }){
|
|
30
|
+
super({
|
|
31
|
+
message: `Invalid vault factor list: ${reason}`,
|
|
32
|
+
options: {
|
|
33
|
+
code: 'VAULT_FACTORS_INVALID'
|
|
34
|
+
}
|
|
29
35
|
});
|
|
30
36
|
this.name = 'InvalidVaultFactors';
|
|
31
37
|
}
|
|
32
38
|
}
|
|
33
39
|
export class UnsupportedVaultSuite extends VaultError {
|
|
34
40
|
#suite;
|
|
35
|
-
constructor(suite){
|
|
36
|
-
super(
|
|
37
|
-
|
|
41
|
+
constructor({ suite }){
|
|
42
|
+
super({
|
|
43
|
+
message: `Unsupported vault suite ${suite}`,
|
|
44
|
+
options: {
|
|
45
|
+
code: 'VAULT_SUITE_UNSUPPORTED'
|
|
46
|
+
}
|
|
38
47
|
});
|
|
39
48
|
this.name = 'UnsupportedVaultSuite';
|
|
40
49
|
this.#suite = suite;
|
|
@@ -44,21 +53,27 @@ export class UnsupportedVaultSuite extends VaultError {
|
|
|
44
53
|
}
|
|
45
54
|
}
|
|
46
55
|
export class VaultTampered extends VaultError {
|
|
47
|
-
constructor(message, options){
|
|
48
|
-
super(
|
|
49
|
-
|
|
50
|
-
|
|
56
|
+
constructor({ message, options }){
|
|
57
|
+
super({
|
|
58
|
+
message,
|
|
59
|
+
options: {
|
|
60
|
+
...options,
|
|
61
|
+
code: 'VAULT_TAMPERED'
|
|
62
|
+
}
|
|
51
63
|
});
|
|
52
64
|
this.name = 'VaultTampered';
|
|
53
65
|
}
|
|
54
66
|
}
|
|
55
67
|
/** Authentication failed. The original GCM error is retained as cause. */ export class VaultSecretRejected extends VaultError {
|
|
56
68
|
#kinds;
|
|
57
|
-
constructor(kinds, options){
|
|
69
|
+
constructor({ kinds, options }){
|
|
58
70
|
const keyID = options?.keyID;
|
|
59
|
-
super(
|
|
60
|
-
|
|
61
|
-
|
|
71
|
+
super({
|
|
72
|
+
message: `Vault ${kinds.join(' and ')} rejected${keyID == null ? '' : ` for key ${keyID}`}. If the secret is known to be correct, the wrapping's factor descriptors or ciphertext may have been altered -- the two are indistinguishable at this point.`,
|
|
73
|
+
options: {
|
|
74
|
+
...options,
|
|
75
|
+
code: options?.code ?? 'VAULT_SECRET_REJECTED'
|
|
76
|
+
}
|
|
62
77
|
});
|
|
63
78
|
this.name = 'VaultSecretRejected';
|
|
64
79
|
this.#kinds = kinds;
|
|
@@ -70,13 +85,16 @@ export class VaultTampered extends VaultError {
|
|
|
70
85
|
export class VaultPinRejected extends VaultSecretRejected {
|
|
71
86
|
#attemptsRemaining;
|
|
72
87
|
#retryAfter;
|
|
73
|
-
constructor(keyID, options){
|
|
74
|
-
super(
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
88
|
+
constructor({ keyID, options }){
|
|
89
|
+
super({
|
|
90
|
+
kinds: [
|
|
91
|
+
'pin'
|
|
92
|
+
],
|
|
93
|
+
options: {
|
|
94
|
+
cause: options.cause,
|
|
95
|
+
keyID,
|
|
96
|
+
code: 'VAULT_PIN_REJECTED'
|
|
97
|
+
}
|
|
80
98
|
});
|
|
81
99
|
this.name = 'VaultPinRejected';
|
|
82
100
|
this.#attemptsRemaining = options.attemptsRemaining;
|
package/lib/factors.d.ts
CHANGED
|
@@ -7,11 +7,23 @@ export type FactorDescriptor = {
|
|
|
7
7
|
};
|
|
8
8
|
export declare const SECRET_FACTOR_KINDS: ReadonlyArray<SecretFactorKind>;
|
|
9
9
|
export declare function isSecretFactorKind(kind: string): kind is SecretFactorKind;
|
|
10
|
-
export
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
10
|
+
export type WrappingNamesExcludedRecipientParams = {
|
|
11
|
+
wrapping: {
|
|
12
|
+
recipientDID: string | null;
|
|
13
|
+
factors: ReadonlyArray<FactorDescriptor>;
|
|
14
|
+
};
|
|
15
|
+
excluded: ReadonlySet<string>;
|
|
16
|
+
};
|
|
17
|
+
export declare function wrappingNamesExcludedRecipient({ excluded, wrapping, }: WrappingNamesExcludedRecipientParams): boolean;
|
|
18
|
+
export type SatisfiableFactorsParams = {
|
|
19
|
+
descriptors: Array<FactorDescriptor>;
|
|
20
|
+
identity: KeyAgreementIdentity | null;
|
|
21
|
+
};
|
|
22
|
+
export declare function satisfiableFactors({ identity, descriptors, }: SatisfiableFactorsParams): Array<SecretFactorKind> | null;
|
|
23
|
+
export type FactorsFromDescriptorsParams = {
|
|
24
|
+
descriptors: Array<FactorDescriptor>;
|
|
25
|
+
inputs?: FactorInputs;
|
|
26
|
+
};
|
|
27
|
+
export declare function factorsFromDescriptors({ inputs, descriptors, }: FactorsFromDescriptorsParams): Array<FactorInput>;
|
|
16
28
|
/** Public recipient metadata uses equality form. Descriptors retain resolvable long forms. */
|
|
17
29
|
export declare function recipientDIDForFactors(factors: ReadonlyArray<FactorInput>): string | null;
|
package/lib/factors.js
CHANGED
|
@@ -7,13 +7,13 @@ export const SECRET_FACTOR_KINDS = [
|
|
|
7
7
|
export function isSecretFactorKind(kind) {
|
|
8
8
|
return SECRET_FACTOR_KINDS.includes(kind);
|
|
9
9
|
}
|
|
10
|
-
export function wrappingNamesExcludedRecipient(
|
|
10
|
+
export function wrappingNamesExcludedRecipient({ excluded, wrapping }) {
|
|
11
11
|
return [
|
|
12
12
|
wrapping.recipientDID,
|
|
13
13
|
...wrapping.factors.filter((factor)=>factor.kind === 'did').map((factor)=>factor.params.recipient)
|
|
14
14
|
].some((recipient)=>typeof recipient === 'string' && excluded.has(normalizeDID(recipient)));
|
|
15
15
|
}
|
|
16
|
-
export function satisfiableFactors(
|
|
16
|
+
export function satisfiableFactors({ identity, descriptors }) {
|
|
17
17
|
const needed = [];
|
|
18
18
|
for (const descriptor of descriptors){
|
|
19
19
|
if (isSecretFactorKind(descriptor.kind)) {
|
|
@@ -27,19 +27,25 @@ export function satisfiableFactors(descriptors, identity) {
|
|
|
27
27
|
}
|
|
28
28
|
return needed;
|
|
29
29
|
}
|
|
30
|
-
export function factorsFromDescriptors(
|
|
30
|
+
export function factorsFromDescriptors({ inputs, descriptors }) {
|
|
31
31
|
return descriptors.map((descriptor)=>{
|
|
32
32
|
if (descriptor.kind === 'did') {
|
|
33
33
|
const recipient = descriptor.params.recipient;
|
|
34
|
-
if (typeof recipient !== 'string') throw new VaultTampered(
|
|
34
|
+
if (typeof recipient !== 'string') throw new VaultTampered({
|
|
35
|
+
message: 'did factor descriptor carries no recipient'
|
|
36
|
+
});
|
|
35
37
|
return {
|
|
36
38
|
kind: 'did',
|
|
37
39
|
recipientDID: recipient
|
|
38
40
|
};
|
|
39
41
|
}
|
|
40
|
-
if (!isSecretFactorKind(descriptor.kind)) throw new NoAvailableFactor(
|
|
42
|
+
if (!isSecretFactorKind(descriptor.kind)) throw new NoAvailableFactor({
|
|
43
|
+
kind: descriptor.kind
|
|
44
|
+
});
|
|
41
45
|
const input = inputs?.[descriptor.kind];
|
|
42
|
-
if (input == null) throw new NoAvailableFactor(
|
|
46
|
+
if (input == null) throw new NoAvailableFactor({
|
|
47
|
+
kind: descriptor.kind
|
|
48
|
+
});
|
|
43
49
|
const { m, t, p } = descriptor.params;
|
|
44
50
|
const cost = typeof m === 'number' && typeof t === 'number' && typeof p === 'number' ? {
|
|
45
51
|
m,
|
package/lib/id.d.ts
CHANGED
|
@@ -1,7 +1,16 @@
|
|
|
1
|
+
import type { CryptoOptions } from '@kokuin/token';
|
|
1
2
|
/** Owner binding uses the exact owner bytes; callers normalise equality DIDs before minting. */
|
|
2
|
-
export
|
|
3
|
+
export type CreateVaultKeyIDParams = {
|
|
4
|
+
owner: string | Uint8Array;
|
|
5
|
+
unique: Uint8Array;
|
|
6
|
+
} & CryptoOptions;
|
|
7
|
+
export declare function createVaultKeyID({ unique, owner, ...options }: CreateVaultKeyIDParams): Promise<string>;
|
|
3
8
|
/** Pair the owner commitment with the canonical unique bytes used by signed key metadata. */
|
|
4
|
-
export
|
|
9
|
+
export type CreateVaultKeyReferenceParams = {
|
|
10
|
+
owner: string;
|
|
11
|
+
unique: Uint8Array;
|
|
12
|
+
} & CryptoOptions;
|
|
13
|
+
export declare function createVaultKeyReference({ unique, owner, ...options }: CreateVaultKeyReferenceParams): Promise<{
|
|
5
14
|
keyID: string;
|
|
6
15
|
keyUnique: string;
|
|
7
|
-
}
|
|
16
|
+
}>;
|
package/lib/id.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { nobleCrypto } from '@kokuin/crypto';
|
|
2
2
|
import { concatBytes } from '@noble/hashes/utils.js';
|
|
3
3
|
import { fromUTF, toB64U } from '@sozai/codec';
|
|
4
4
|
// Unsigned varints: namespace 0xb6, key type 31, BLAKE3 digest length 32.
|
|
@@ -8,17 +8,25 @@ const KEY_ID_PREFIX = new Uint8Array([
|
|
|
8
8
|
31,
|
|
9
9
|
32
|
|
10
10
|
]);
|
|
11
|
-
|
|
11
|
+
export async function createVaultKeyID({ unique, owner, ...options }) {
|
|
12
12
|
const ownerBytes = typeof owner === 'string' ? fromUTF(owner) : owner;
|
|
13
|
-
const digest =
|
|
13
|
+
const digest = await (options.crypto ?? nobleCrypto).blake3({
|
|
14
|
+
input: concatBytes(ownerBytes, unique),
|
|
15
|
+
dkLen: 32
|
|
16
|
+
});
|
|
14
17
|
const bytes = concatBytes(KEY_ID_PREFIX, digest);
|
|
15
18
|
let value = 0n;
|
|
16
19
|
for (const byte of bytes)value = value << 8n | BigInt(byte);
|
|
17
20
|
return `k${value.toString(36)}`;
|
|
18
21
|
}
|
|
19
|
-
|
|
22
|
+
export async function createVaultKeyReference({ unique, owner, ...options }) {
|
|
23
|
+
const keyUnique = toB64U(unique);
|
|
20
24
|
return {
|
|
21
|
-
keyID: createVaultKeyID(
|
|
22
|
-
|
|
25
|
+
keyID: await createVaultKeyID({
|
|
26
|
+
...options,
|
|
27
|
+
owner,
|
|
28
|
+
unique
|
|
29
|
+
}),
|
|
30
|
+
keyUnique
|
|
23
31
|
};
|
|
24
32
|
}
|
package/lib/index.d.ts
CHANGED
|
@@ -1,12 +1,18 @@
|
|
|
1
1
|
export * from './branch.js';
|
|
2
2
|
export * from './canonical-token.js';
|
|
3
|
+
export type { DescriptorDigestParams, DigestPartsParams, VaultEntriesDigestParams, VaultEntryDigestParams, VaultKeyDigestParams, VaultWrappingDigestParams, } from './digest.js';
|
|
3
4
|
export * from './digest.js';
|
|
4
5
|
export * from './errors.js';
|
|
6
|
+
export type { FactorsFromDescriptorsParams, SatisfiableFactorsParams, WrappingNamesExcludedRecipientParams, } from './factors.js';
|
|
5
7
|
export * from './factors.js';
|
|
8
|
+
export type { CreateVaultKeyIDParams, CreateVaultKeyReferenceParams } from './id.js';
|
|
6
9
|
export * from './id.js';
|
|
10
|
+
export type { KeyCacheEvictVersionParams, KeyCacheGetParams, KeyCacheHasParams, } from './key-cache.js';
|
|
7
11
|
export * from './key-cache.js';
|
|
8
12
|
export * from './pin-throttle.js';
|
|
13
|
+
export type { VaultKeyVersionReaderParams, VaultProofAuthorizerParams, VaultRecordHooksValidateConsumerMetadataParams, } from './record-types.js';
|
|
9
14
|
export * from './record-types.js';
|
|
10
|
-
export
|
|
15
|
+
export type { DecodedVaultRecord, DecodeVaultRecordParams, EncodeVaultRecordPayloadParams, VaultEntryMetadata, VaultRecordMetaParams, VaultRecordMetas, VaultRecordPayloadErrorParams, VaultRecordPayloads, VaultRecordType, VaultRevocationRecordIDParams, } from './records.js';
|
|
16
|
+
export { decodeVaultRecord, encodeVaultRecordPayload, VAULT_OP_KIND, VAULT_RECORD_TYPES, VaultRecordPayloadError, vaultRecordMeta, vaultRevocationRecordID, } from './records.js';
|
|
11
17
|
export * from './suite.js';
|
|
12
18
|
export * from './wrappable.js';
|