@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/README.md
CHANGED
|
@@ -1,3 +1,165 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @kokuin/vault
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Database-free content keys, ordered factor wrapping, and authenticated encryption of opaque bytes.
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
import { getSuite, SUITE_VAULT_1, wrappableDID } from '@kokuin/vault'
|
|
7
|
+
import { createRuntime } from '@sozai/runtime'
|
|
8
|
+
|
|
9
|
+
const runtime = createRuntime()
|
|
10
|
+
const suite = getSuite(SUITE_VAULT_1)
|
|
11
|
+
const keyID = 'host-content-key'
|
|
12
|
+
const keyVersion = 1
|
|
13
|
+
const wrappingID = 'device-wrapping'
|
|
14
|
+
const contentKey = suite.generateContentKey(runtime)
|
|
15
|
+
const wrapped = await suite.wrap({
|
|
16
|
+
runtime,
|
|
17
|
+
keyID,
|
|
18
|
+
keyVersion,
|
|
19
|
+
wrappingID,
|
|
20
|
+
contentKey,
|
|
21
|
+
factors: [{ kind: 'did', recipientDID: wrappableDID(deviceIdentity) }],
|
|
22
|
+
})
|
|
23
|
+
|
|
24
|
+
// Keep this digest in trusted local state or independently authenticated metadata.
|
|
25
|
+
const trustedDigest = wrapped.descriptorDigest
|
|
26
|
+
const openedKey = await suite.unwrap({
|
|
27
|
+
...wrapped,
|
|
28
|
+
keyID,
|
|
29
|
+
keyVersion,
|
|
30
|
+
wrappingID,
|
|
31
|
+
identity: deviceIdentity,
|
|
32
|
+
expectedDescriptorDigest: trustedDigest,
|
|
33
|
+
})
|
|
34
|
+
const entryID = 'current-state'
|
|
35
|
+
const encrypted = suite.encryptEntry({
|
|
36
|
+
runtime,
|
|
37
|
+
keyID,
|
|
38
|
+
keyVersion,
|
|
39
|
+
entryID,
|
|
40
|
+
contentKey: openedKey,
|
|
41
|
+
plaintext: hostBytes,
|
|
42
|
+
})
|
|
43
|
+
const recovered = suite.decryptEntry({
|
|
44
|
+
...encrypted,
|
|
45
|
+
keyID,
|
|
46
|
+
keyVersion,
|
|
47
|
+
entryID,
|
|
48
|
+
contentKey: openedKey,
|
|
49
|
+
})
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
`deviceIdentity` supplies an already available agreement key. The host must ensure `agreeKey` never prompts on its message path.
|
|
53
|
+
The host owns persistence and atomically replaces the current ciphertext with its journal or outbox transaction.
|
|
54
|
+
The host also owns device binding, rollback protection, and refusal to sync, export, or retain historical MLS state.
|
|
55
|
+
|
|
56
|
+
`VAULT_1` uses X25519 agreement, HKDF-SHA256, Argon2id, and AES-256-GCM.
|
|
57
|
+
Descriptors preserve factor order. A PIN requires a DID factor in the same wrapping.
|
|
58
|
+
The default Argon2id cost is `{ m: 19456, t: 2, p: 1 }`, with memory measured in KiB.
|
|
59
|
+
IVs are 12 bytes. Encrypted values contain ciphertext followed by the 16-byte authentication tag.
|
|
60
|
+
Entry AAD binds the suite, key ID, version, and entry ID.
|
|
61
|
+
|
|
62
|
+
`expectedDescriptorDigest` is optional. A trusted mismatch throws `VaultTampered` before agreement, KDF work, or decryption.
|
|
63
|
+
The `descriptorDigest` carried beside a presented wrapping is informational and cannot establish trust by itself.
|
|
64
|
+
GCM unwrap failures throw `VaultSecretRejected` with the original failure as `cause`, including for DID-only wrappings.
|
|
65
|
+
Missing factors and malformed descriptors retain their distinct validation errors.
|
|
66
|
+
Entry authentication failures throw `VaultTampered` with the original cause.
|
|
67
|
+
|
|
68
|
+
`createVaultKeyID({ owner, unique })` hashes the exact owner bytes concatenated with unique bytes using BLAKE3.
|
|
69
|
+
Its base36 multibase encoding frames unsigned varints for namespace `0xb6`, key type `31`, and digest length `32`.
|
|
70
|
+
Callers normalise owner DIDs before minting IDs used as equality keys.
|
|
71
|
+
Recipient DIDs retain their resolvable long form. `wrappableDID` selects that form when available.
|
|
72
|
+
|
|
73
|
+
The package also exports the public key, wrapping, entry-set and descriptor digest helpers,
|
|
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` |
|
package/lib/branch.d.ts
ADDED
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import type { VerifiedRecordOp } from '@kokuin/records';
|
|
2
|
+
/** Compare authenticated introducing ops by claim digest, then op hash. */
|
|
3
|
+
export declare function compareVaultBranches(left: VerifiedRecordOp, right: VerifiedRecordOp): number;
|
|
4
|
+
export declare function selectWinningBranch(branches: ReadonlyArray<VerifiedRecordOp>): VerifiedRecordOp;
|
package/lib/branch.js
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/** Compare authenticated introducing ops by claim digest, then op hash. */ export function compareVaultBranches(left, right) {
|
|
2
|
+
const a = left.contentDigest;
|
|
3
|
+
const b = right.contentDigest;
|
|
4
|
+
return a < b ? -1 : a > b ? 1 : left.opHash < right.opHash ? -1 : left.opHash > right.opHash ? 1 : 0;
|
|
5
|
+
}
|
|
6
|
+
export function selectWinningBranch(branches) {
|
|
7
|
+
if (branches.length === 0) throw new RangeError('At least one authenticated branch is required');
|
|
8
|
+
return branches.reduce((winner, candidate)=>{
|
|
9
|
+
return compareVaultBranches(candidate, winner) > 0 ? candidate : winner;
|
|
10
|
+
});
|
|
11
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function isCanonicalCompactToken(token: string): boolean;
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { fromB64U, toB64U } from '@sozai/codec';
|
|
2
|
+
export function isCanonicalCompactToken(token) {
|
|
3
|
+
const segments = token.split('.');
|
|
4
|
+
if (segments.length !== 3) return false;
|
|
5
|
+
try {
|
|
6
|
+
return segments.every((segment)=>toB64U(fromB64U(segment)) === segment);
|
|
7
|
+
} catch {
|
|
8
|
+
return false;
|
|
9
|
+
}
|
|
10
|
+
}
|
package/lib/digest.d.ts
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import type { CryptoOptions } from '@kokuin/token';
|
|
2
|
+
import type { FactorDescriptor } from './factors.js';
|
|
3
|
+
export type DigestPartsParams = {
|
|
4
|
+
parts: Array<string>;
|
|
5
|
+
} & CryptoOptions;
|
|
6
|
+
export declare function digestParts({ parts, ...options }: DigestPartsParams): Promise<string>;
|
|
7
|
+
export type VaultKeyDigestInput = {
|
|
8
|
+
ownerDID: string;
|
|
9
|
+
suite: number;
|
|
10
|
+
version: number;
|
|
11
|
+
state: string;
|
|
12
|
+
};
|
|
13
|
+
export type VaultWrappingDigestInput = {
|
|
14
|
+
wrappingID: string;
|
|
15
|
+
recipientDID: string | null;
|
|
16
|
+
iv: string;
|
|
17
|
+
wrappedKey: string;
|
|
18
|
+
factors: Array<FactorDescriptor>;
|
|
19
|
+
};
|
|
20
|
+
export type VaultEntryDigestInput = {
|
|
21
|
+
entryID: string;
|
|
22
|
+
iv: string;
|
|
23
|
+
ciphertext: string;
|
|
24
|
+
hlc: string;
|
|
25
|
+
};
|
|
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>;
|
|
42
|
+
/** Same canonical descriptor encoding and length framing as the wrapping digest. */
|
|
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 & {
|
|
48
|
+
descriptors: Array<FactorDescriptor>;
|
|
49
|
+
expectedDescriptorDigest: string;
|
|
50
|
+
}): Promise<void>;
|
package/lib/digest.js
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import { nobleCrypto } from '@kokuin/crypto';
|
|
2
|
+
import { fromUTF, toB64U } from '@sozai/codec';
|
|
3
|
+
import { canonicalize } from '@sozai/json';
|
|
4
|
+
import { VaultTampered } from './errors.js';
|
|
5
|
+
function descriptorJSON(descriptors) {
|
|
6
|
+
const json = canonicalize(descriptors);
|
|
7
|
+
if (json == null) throw new TypeError('Factor descriptors have no JSON representation');
|
|
8
|
+
return json;
|
|
9
|
+
}
|
|
10
|
+
export async function digestParts({ parts, ...options }) {
|
|
11
|
+
const framed = parts.map((part)=>`${part.length}:${part}`).join('');
|
|
12
|
+
return toB64U(await (options.crypto ?? nobleCrypto).blake3({
|
|
13
|
+
input: fromUTF(framed),
|
|
14
|
+
dkLen: 32
|
|
15
|
+
}));
|
|
16
|
+
}
|
|
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 }) {
|
|
41
|
+
const ordered = [
|
|
42
|
+
...entries
|
|
43
|
+
].sort((left, right)=>{
|
|
44
|
+
return left.entryID < right.entryID ? -1 : left.entryID > right.entryID ? 1 : 0;
|
|
45
|
+
});
|
|
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
|
+
});
|
|
81
|
+
}
|
|
82
|
+
}
|
package/lib/errors.d.ts
ADDED
|
@@ -0,0 +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
|
+
};
|
|
32
|
+
export type VaultErrorCode = 'VAULT_ERROR' | 'VAULT_FACTOR_UNAVAILABLE' | 'VAULT_FACTORS_INVALID' | 'VAULT_SUITE_UNSUPPORTED' | 'VAULT_TAMPERED' | 'VAULT_SECRET_REJECTED' | 'VAULT_PIN_REJECTED';
|
|
33
|
+
export type VaultErrorOptions = ErrorOptions & {
|
|
34
|
+
code: VaultErrorCode;
|
|
35
|
+
};
|
|
36
|
+
export declare class VaultError extends Error {
|
|
37
|
+
#private;
|
|
38
|
+
constructor({ message, options }: VaultErrorParams);
|
|
39
|
+
get code(): VaultErrorCode;
|
|
40
|
+
}
|
|
41
|
+
export declare class NoAvailableFactor extends VaultError {
|
|
42
|
+
#private;
|
|
43
|
+
constructor({ kind }: NoAvailableFactorParams);
|
|
44
|
+
get kind(): string;
|
|
45
|
+
}
|
|
46
|
+
export declare class InvalidVaultFactors extends VaultError {
|
|
47
|
+
constructor({ reason }: InvalidVaultFactorsParams);
|
|
48
|
+
}
|
|
49
|
+
export declare class UnsupportedVaultSuite extends VaultError {
|
|
50
|
+
#private;
|
|
51
|
+
constructor({ suite }: UnsupportedVaultSuiteParams);
|
|
52
|
+
get suite(): number;
|
|
53
|
+
}
|
|
54
|
+
export declare class VaultTampered extends VaultError {
|
|
55
|
+
constructor({ message, options }: VaultTamperedParams);
|
|
56
|
+
}
|
|
57
|
+
/** Authentication failed. The original GCM error is retained as cause. */
|
|
58
|
+
export declare class VaultSecretRejected extends VaultError {
|
|
59
|
+
#private;
|
|
60
|
+
constructor({ kinds, options }: VaultSecretRejectedParams);
|
|
61
|
+
get kinds(): Array<string>;
|
|
62
|
+
}
|
|
63
|
+
export declare class VaultPinRejected extends VaultSecretRejected {
|
|
64
|
+
#private;
|
|
65
|
+
constructor({ keyID, options }: VaultPinRejectedParams);
|
|
66
|
+
get attemptsRemaining(): number;
|
|
67
|
+
get retryAfter(): number;
|
|
68
|
+
}
|
package/lib/errors.js
ADDED
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
export class VaultError extends Error {
|
|
2
|
+
#code;
|
|
3
|
+
constructor({ message, options }){
|
|
4
|
+
super(message, options);
|
|
5
|
+
this.name = 'VaultError';
|
|
6
|
+
this.#code = options.code;
|
|
7
|
+
}
|
|
8
|
+
get code() {
|
|
9
|
+
return this.#code;
|
|
10
|
+
}
|
|
11
|
+
}
|
|
12
|
+
export class NoAvailableFactor extends VaultError {
|
|
13
|
+
#kind;
|
|
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
|
+
}
|
|
20
|
+
});
|
|
21
|
+
this.name = 'NoAvailableFactor';
|
|
22
|
+
this.#kind = kind;
|
|
23
|
+
}
|
|
24
|
+
get kind() {
|
|
25
|
+
return this.#kind;
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
export class InvalidVaultFactors extends VaultError {
|
|
29
|
+
constructor({ reason }){
|
|
30
|
+
super({
|
|
31
|
+
message: `Invalid vault factor list: ${reason}`,
|
|
32
|
+
options: {
|
|
33
|
+
code: 'VAULT_FACTORS_INVALID'
|
|
34
|
+
}
|
|
35
|
+
});
|
|
36
|
+
this.name = 'InvalidVaultFactors';
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
export class UnsupportedVaultSuite extends VaultError {
|
|
40
|
+
#suite;
|
|
41
|
+
constructor({ suite }){
|
|
42
|
+
super({
|
|
43
|
+
message: `Unsupported vault suite ${suite}`,
|
|
44
|
+
options: {
|
|
45
|
+
code: 'VAULT_SUITE_UNSUPPORTED'
|
|
46
|
+
}
|
|
47
|
+
});
|
|
48
|
+
this.name = 'UnsupportedVaultSuite';
|
|
49
|
+
this.#suite = suite;
|
|
50
|
+
}
|
|
51
|
+
get suite() {
|
|
52
|
+
return this.#suite;
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
export class VaultTampered extends VaultError {
|
|
56
|
+
constructor({ message, options }){
|
|
57
|
+
super({
|
|
58
|
+
message,
|
|
59
|
+
options: {
|
|
60
|
+
...options,
|
|
61
|
+
code: 'VAULT_TAMPERED'
|
|
62
|
+
}
|
|
63
|
+
});
|
|
64
|
+
this.name = 'VaultTampered';
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
/** Authentication failed. The original GCM error is retained as cause. */ export class VaultSecretRejected extends VaultError {
|
|
68
|
+
#kinds;
|
|
69
|
+
constructor({ kinds, options }){
|
|
70
|
+
const keyID = options?.keyID;
|
|
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
|
+
}
|
|
77
|
+
});
|
|
78
|
+
this.name = 'VaultSecretRejected';
|
|
79
|
+
this.#kinds = kinds;
|
|
80
|
+
}
|
|
81
|
+
get kinds() {
|
|
82
|
+
return this.#kinds;
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
export class VaultPinRejected extends VaultSecretRejected {
|
|
86
|
+
#attemptsRemaining;
|
|
87
|
+
#retryAfter;
|
|
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
|
+
}
|
|
98
|
+
});
|
|
99
|
+
this.name = 'VaultPinRejected';
|
|
100
|
+
this.#attemptsRemaining = options.attemptsRemaining;
|
|
101
|
+
this.#retryAfter = options.retryAfter;
|
|
102
|
+
}
|
|
103
|
+
get attemptsRemaining() {
|
|
104
|
+
return this.#attemptsRemaining;
|
|
105
|
+
}
|
|
106
|
+
get retryAfter() {
|
|
107
|
+
return this.#retryAfter;
|
|
108
|
+
}
|
|
109
|
+
}
|
package/lib/factors.d.ts
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import type { KeyAgreementIdentity } from '@kokuin/token';
|
|
2
|
+
import type { FactorInput, FactorInputs, SecretFactorKind } from './suite.js';
|
|
3
|
+
/** Ordered public descriptors. Unknown kinds are retained for fail-closed suite dispatch. */
|
|
4
|
+
export type FactorDescriptor = {
|
|
5
|
+
kind: string;
|
|
6
|
+
params: Record<string, unknown>;
|
|
7
|
+
};
|
|
8
|
+
export declare const SECRET_FACTOR_KINDS: ReadonlyArray<SecretFactorKind>;
|
|
9
|
+
export declare function isSecretFactorKind(kind: string): kind is SecretFactorKind;
|
|
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>;
|
|
28
|
+
/** Public recipient metadata uses equality form. Descriptors retain resolvable long forms. */
|
|
29
|
+
export declare function recipientDIDForFactors(factors: ReadonlyArray<FactorInput>): string | null;
|
package/lib/factors.js
ADDED
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import { normalizeDID } from '@kokuin/token';
|
|
2
|
+
import { NoAvailableFactor, VaultTampered } from './errors.js';
|
|
3
|
+
export const SECRET_FACTOR_KINDS = [
|
|
4
|
+
'passphrase',
|
|
5
|
+
'pin'
|
|
6
|
+
];
|
|
7
|
+
export function isSecretFactorKind(kind) {
|
|
8
|
+
return SECRET_FACTOR_KINDS.includes(kind);
|
|
9
|
+
}
|
|
10
|
+
export function wrappingNamesExcludedRecipient({ excluded, wrapping }) {
|
|
11
|
+
return [
|
|
12
|
+
wrapping.recipientDID,
|
|
13
|
+
...wrapping.factors.filter((factor)=>factor.kind === 'did').map((factor)=>factor.params.recipient)
|
|
14
|
+
].some((recipient)=>typeof recipient === 'string' && excluded.has(normalizeDID(recipient)));
|
|
15
|
+
}
|
|
16
|
+
export function satisfiableFactors({ identity, descriptors }) {
|
|
17
|
+
const needed = [];
|
|
18
|
+
for (const descriptor of descriptors){
|
|
19
|
+
if (isSecretFactorKind(descriptor.kind)) {
|
|
20
|
+
needed.push(descriptor.kind);
|
|
21
|
+
continue;
|
|
22
|
+
}
|
|
23
|
+
if (descriptor.kind !== 'did') return null;
|
|
24
|
+
const recipient = descriptor.params.recipient;
|
|
25
|
+
if (identity === null || typeof recipient !== 'string') return null;
|
|
26
|
+
if (normalizeDID(recipient) !== normalizeDID(identity.id)) return null;
|
|
27
|
+
}
|
|
28
|
+
return needed;
|
|
29
|
+
}
|
|
30
|
+
export function factorsFromDescriptors({ inputs, descriptors }) {
|
|
31
|
+
return descriptors.map((descriptor)=>{
|
|
32
|
+
if (descriptor.kind === 'did') {
|
|
33
|
+
const recipient = descriptor.params.recipient;
|
|
34
|
+
if (typeof recipient !== 'string') throw new VaultTampered({
|
|
35
|
+
message: 'did factor descriptor carries no recipient'
|
|
36
|
+
});
|
|
37
|
+
return {
|
|
38
|
+
kind: 'did',
|
|
39
|
+
recipientDID: recipient
|
|
40
|
+
};
|
|
41
|
+
}
|
|
42
|
+
if (!isSecretFactorKind(descriptor.kind)) throw new NoAvailableFactor({
|
|
43
|
+
kind: descriptor.kind
|
|
44
|
+
});
|
|
45
|
+
const input = inputs?.[descriptor.kind];
|
|
46
|
+
if (input == null) throw new NoAvailableFactor({
|
|
47
|
+
kind: descriptor.kind
|
|
48
|
+
});
|
|
49
|
+
const { m, t, p } = descriptor.params;
|
|
50
|
+
const cost = typeof m === 'number' && typeof t === 'number' && typeof p === 'number' ? {
|
|
51
|
+
m,
|
|
52
|
+
t,
|
|
53
|
+
p
|
|
54
|
+
} : undefined;
|
|
55
|
+
return {
|
|
56
|
+
kind: descriptor.kind,
|
|
57
|
+
input,
|
|
58
|
+
cost
|
|
59
|
+
};
|
|
60
|
+
});
|
|
61
|
+
}
|
|
62
|
+
/** Public recipient metadata uses equality form. Descriptors retain resolvable long forms. */ export function recipientDIDForFactors(factors) {
|
|
63
|
+
const factor = factors[0];
|
|
64
|
+
return factors.length === 1 && factor?.kind === 'did' ? normalizeDID(factor.recipientDID) : null;
|
|
65
|
+
}
|
package/lib/id.d.ts
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import type { CryptoOptions } from '@kokuin/token';
|
|
2
|
+
/** Owner binding uses the exact owner bytes; callers normalise equality DIDs before minting. */
|
|
3
|
+
export type CreateVaultKeyIDParams = {
|
|
4
|
+
owner: string | Uint8Array;
|
|
5
|
+
unique: Uint8Array;
|
|
6
|
+
} & CryptoOptions;
|
|
7
|
+
export declare function createVaultKeyID({ unique, owner, ...options }: CreateVaultKeyIDParams): Promise<string>;
|
|
8
|
+
/** Pair the owner commitment with the canonical unique bytes used by signed key metadata. */
|
|
9
|
+
export type CreateVaultKeyReferenceParams = {
|
|
10
|
+
owner: string;
|
|
11
|
+
unique: Uint8Array;
|
|
12
|
+
} & CryptoOptions;
|
|
13
|
+
export declare function createVaultKeyReference({ unique, owner, ...options }: CreateVaultKeyReferenceParams): Promise<{
|
|
14
|
+
keyID: string;
|
|
15
|
+
keyUnique: string;
|
|
16
|
+
}>;
|
package/lib/id.js
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import { nobleCrypto } from '@kokuin/crypto';
|
|
2
|
+
import { concatBytes } from '@noble/hashes/utils.js';
|
|
3
|
+
import { fromUTF, toB64U } from '@sozai/codec';
|
|
4
|
+
// Unsigned varints: namespace 0xb6, key type 31, BLAKE3 digest length 32.
|
|
5
|
+
const KEY_ID_PREFIX = new Uint8Array([
|
|
6
|
+
0xb6,
|
|
7
|
+
0x01,
|
|
8
|
+
31,
|
|
9
|
+
32
|
|
10
|
+
]);
|
|
11
|
+
export async function createVaultKeyID({ unique, owner, ...options }) {
|
|
12
|
+
const ownerBytes = typeof owner === 'string' ? fromUTF(owner) : owner;
|
|
13
|
+
const digest = await (options.crypto ?? nobleCrypto).blake3({
|
|
14
|
+
input: concatBytes(ownerBytes, unique),
|
|
15
|
+
dkLen: 32
|
|
16
|
+
});
|
|
17
|
+
const bytes = concatBytes(KEY_ID_PREFIX, digest);
|
|
18
|
+
let value = 0n;
|
|
19
|
+
for (const byte of bytes)value = value << 8n | BigInt(byte);
|
|
20
|
+
return `k${value.toString(36)}`;
|
|
21
|
+
}
|
|
22
|
+
export async function createVaultKeyReference({ unique, owner, ...options }) {
|
|
23
|
+
const keyUnique = toB64U(unique);
|
|
24
|
+
return {
|
|
25
|
+
keyID: await createVaultKeyID({
|
|
26
|
+
...options,
|
|
27
|
+
owner,
|
|
28
|
+
unique
|
|
29
|
+
}),
|
|
30
|
+
keyUnique
|
|
31
|
+
};
|
|
32
|
+
}
|
package/lib/index.d.ts
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
export * from './branch.js';
|
|
2
|
+
export * from './canonical-token.js';
|
|
3
|
+
export type { DescriptorDigestParams, DigestPartsParams, VaultEntriesDigestParams, VaultEntryDigestParams, VaultKeyDigestParams, VaultWrappingDigestParams, } from './digest.js';
|
|
4
|
+
export * from './digest.js';
|
|
5
|
+
export * from './errors.js';
|
|
6
|
+
export type { FactorsFromDescriptorsParams, SatisfiableFactorsParams, WrappingNamesExcludedRecipientParams, } from './factors.js';
|
|
7
|
+
export * from './factors.js';
|
|
8
|
+
export type { CreateVaultKeyIDParams, CreateVaultKeyReferenceParams } from './id.js';
|
|
9
|
+
export * from './id.js';
|
|
10
|
+
export type { KeyCacheEvictVersionParams, KeyCacheGetParams, KeyCacheHasParams, } from './key-cache.js';
|
|
11
|
+
export * from './key-cache.js';
|
|
12
|
+
export * from './pin-throttle.js';
|
|
13
|
+
export type { VaultKeyVersionReaderParams, VaultProofAuthorizerParams, VaultRecordHooksValidateConsumerMetadataParams, } from './record-types.js';
|
|
14
|
+
export * from './record-types.js';
|
|
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';
|
|
17
|
+
export * from './suite.js';
|
|
18
|
+
export * from './wrappable.js';
|