@coffre/core 0.14.7 → 0.16.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 +1 -1
- package/dist/{access-BrdZKp1d.js → access-CF8UG59J.js} +70 -8
- package/dist/{access-qkMZa-6Z.d.ts → access-ERdGGHG7.d.ts} +45 -3
- package/dist/access.d.ts +2 -2
- package/dist/access.js +2 -2
- package/dist/envelope.d.ts +28 -9
- package/dist/envelope.js +25 -8
- package/dist/identity.d.ts +2 -917
- package/dist/identity.js +1036 -525
- package/dist/index-DuG9p3GH.d.ts +1233 -0
- package/dist/kek.d.ts +10 -16
- package/dist/kek.js +26 -41
- package/dist/log.d.ts +114 -0
- package/dist/log.js +291 -0
- package/dist/mcp.d.ts +25 -1
- package/dist/mcp.js +29 -4
- package/dist/recipe-BgJpmJum.d.ts +128 -0
- package/dist/recipe.d.ts +2 -127
- package/dist/{registry-D7X-x202.d.ts → registry-B7_LUDsJ.d.ts} +30 -5
- package/dist/schemas.d.ts +14 -4
- package/dist/schemas.js +16 -4
- package/dist/{types-Cp3lB_-W.js → types-DwTO_b4H.js} +17 -5
- package/dist/vault.d.ts +1800 -299
- package/dist/vault.js +99 -32
- package/package.json +8 -3
- package/src/access.ts +63 -8
- package/src/changes/access.ts +140 -0
- package/src/changes/freezes.ts +40 -0
- package/src/changes/mcp.ts +150 -0
- package/src/changes/places.ts +219 -0
- package/src/changes/secrets.ts +235 -0
- package/src/changes/signin.ts +197 -0
- package/src/changes/workloads.ts +166 -0
- package/src/context.ts +18 -2
- package/src/envelope.ts +35 -12
- package/src/identity/auth.ts +11 -3
- package/src/identity/aws.ts +62 -0
- package/src/identity/github-app.ts +45 -24
- package/src/identity/index.ts +3 -0
- package/src/identity/profiles.ts +139 -0
- package/src/identity/proofs.ts +306 -0
- package/src/identity/signin/config.ts +1 -1
- package/src/identity/tokens.ts +10 -3
- package/src/identity/verifier.ts +73 -14
- package/src/identity/workload-token.ts +4 -0
- package/src/kek/aws-kms.ts +18 -13
- package/src/kek/check.ts +16 -46
- package/src/kek/index.ts +2 -2
- package/src/kek/types.ts +15 -3
- package/src/log/index.ts +7 -0
- package/src/log/tiles.ts +166 -0
- package/src/log/tree.ts +163 -0
- package/src/mcp.ts +34 -3
- package/src/schemas.ts +16 -2
- package/src/vault.ts +308 -276
- package/src/checkpoint.ts +0 -22
package/src/kek/aws-kms.ts
CHANGED
|
@@ -5,6 +5,7 @@ import {
|
|
|
5
5
|
DEK_BYTES,
|
|
6
6
|
KekBadClaimError,
|
|
7
7
|
KekCancelledError,
|
|
8
|
+
KekRefusedError,
|
|
8
9
|
KekUnavailableError,
|
|
9
10
|
type KeyOperation,
|
|
10
11
|
type KekProvider,
|
|
@@ -103,11 +104,11 @@ export class AwsKmsKekProvider implements KekProvider {
|
|
|
103
104
|
CiphertextBlob: base64(wrapped.bytes),
|
|
104
105
|
EncryptionContext: encryptionContext(ctx),
|
|
105
106
|
}, operation);
|
|
106
|
-
if (KeyId !== this.keyId) throw new
|
|
107
|
+
if (KeyId !== this.keyId) throw new KekRefusedError(`KMS decrypted under ${KeyId}, not ${this.keyId}`, true);
|
|
107
108
|
const dek = Buffer.from(Plaintext, 'base64');
|
|
108
109
|
if (dek.length !== DEK_BYTES) {
|
|
109
110
|
dek.fill(0);
|
|
110
|
-
throw new
|
|
111
|
+
throw new KekRefusedError('unwrapped DEK has the wrong length', true);
|
|
111
112
|
}
|
|
112
113
|
return dek;
|
|
113
114
|
}
|
|
@@ -116,7 +117,9 @@ export class AwsKmsKekProvider implements KekProvider {
|
|
|
116
117
|
* One KMS call, tried up to three times while KMS throttles, fails on its
|
|
117
118
|
* side or does not answer. Every failure but a ciphertext that does not
|
|
118
119
|
* open is a `KekUnavailableError`, retried or not: a key KMS will not use
|
|
119
|
-
* or credentials it refuses say nothing about the claim either.
|
|
120
|
+
* or credentials it refuses say nothing about the claim either. What KMS
|
|
121
|
+
* answered and will answer again, such as `AccessDeniedException` or
|
|
122
|
+
* `DisabledException`, is a `KekRefusedError`, which only its operator mends.
|
|
120
123
|
*/
|
|
121
124
|
async #call(action: 'Encrypt' | 'Decrypt', request: object, operation?: KeyOperation): Promise<Record<string, string>> {
|
|
122
125
|
const body = JSON.stringify(request);
|
|
@@ -144,7 +147,8 @@ export class AwsKmsKekProvider implements KekProvider {
|
|
|
144
147
|
throw new KekBadClaimError(`KMS ${action}: ${answer.type}`);
|
|
145
148
|
}
|
|
146
149
|
if (!answer.retry || attempt === ATTEMPTS) {
|
|
147
|
-
|
|
150
|
+
const failed = answer.refused ? KekRefusedError : KekUnavailableError;
|
|
151
|
+
throw new failed(`KMS ${action} failed${attempt > 1 ? ` ${attempt} times` : ''}: ${answer.failure}`, uncertain);
|
|
148
152
|
}
|
|
149
153
|
try {
|
|
150
154
|
await delay(100 * 4 ** (attempt - 1) * (1 + Math.random()), signal);
|
|
@@ -162,7 +166,7 @@ export class AwsKmsKekProvider implements KekProvider {
|
|
|
162
166
|
credentials: AwsCredentials,
|
|
163
167
|
signal?: AbortSignal,
|
|
164
168
|
operation?: KeyOperation,
|
|
165
|
-
): Promise<{ data: Record<string, string> } | { type: string; failure: string; retry: boolean; uncertain: boolean }> {
|
|
169
|
+
): Promise<{ data: Record<string, string> } | { type: string; failure: string; retry: boolean; refused: boolean; uncertain: boolean }> {
|
|
166
170
|
const headers = signV4({
|
|
167
171
|
method: 'POST',
|
|
168
172
|
url: this.#url,
|
|
@@ -186,25 +190,22 @@ export class AwsKmsKekProvider implements KekProvider {
|
|
|
186
190
|
});
|
|
187
191
|
text = await response.text();
|
|
188
192
|
} catch (error) {
|
|
189
|
-
return { type: 'network', failure: messageOf(error), retry: sent, uncertain: sent };
|
|
193
|
+
return { type: 'network', failure: messageOf(error), retry: sent, refused: false, uncertain: sent };
|
|
190
194
|
}
|
|
191
195
|
const parsed = parse(text);
|
|
192
196
|
if (response.ok) {
|
|
193
197
|
const complete =
|
|
194
198
|
parsed !== null && (action === 'Encrypt' ? typeof parsed.CiphertextBlob === 'string' : typeof parsed.Plaintext === 'string');
|
|
195
199
|
if (complete) return { data: parsed as Record<string, string> };
|
|
196
|
-
return { type: 'malformed', failure: `KMS answered ${response.status} without a result`, retry: true, uncertain: true };
|
|
200
|
+
return { type: 'malformed', failure: `KMS answered ${response.status} without a result`, retry: true, refused: false, uncertain: true };
|
|
197
201
|
}
|
|
198
202
|
// `__type` may carry a namespace (`com.amazonaws.kms#…`), the header a URL after `:`.
|
|
199
203
|
const raw = response.headers.get('x-amzn-errortype') ?? (typeof parsed?.__type === 'string' ? parsed.__type : '');
|
|
200
204
|
const type = raw.split(':')[0]!.split('#').pop() || `HTTP ${response.status}`;
|
|
201
205
|
const message = parsed?.message ?? parsed?.Message;
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
uncertain: false,
|
|
206
|
-
retry: response.status >= 500 || response.status === 429 || type === 'ThrottlingException',
|
|
207
|
-
};
|
|
206
|
+
const retry = response.status >= 500 || response.status === 429 || type === 'ThrottlingException';
|
|
207
|
+
// Any other answer is KMS's word on coffre's request itself, which it gives again: refused.
|
|
208
|
+
return { type, failure: `${type}${typeof message === 'string' ? `, ${message}` : ''}`, uncertain: false, retry, refused: !retry };
|
|
208
209
|
}
|
|
209
210
|
}
|
|
210
211
|
|
|
@@ -222,6 +223,10 @@ function encryptionContext(ctx: SecretContext): Record<string, string> {
|
|
|
222
223
|
...(ctx.owner === undefined ? {} : { 'coffre:owner': ctx.owner }),
|
|
223
224
|
// A sensitive value's: KMS refuses to decrypt it as anything else.
|
|
224
225
|
...(ctx.sensitive === true ? { 'coffre:sensitive': 'true' } : {}),
|
|
226
|
+
// A plain value's, from envelope version 2: KMS refuses to decrypt a secret as one.
|
|
227
|
+
...(ctx.plain === true ? { 'coffre:plain': 'true' } : {}),
|
|
228
|
+
// The version's number, from envelope version 2: KMS refuses to decrypt one version's key as another's.
|
|
229
|
+
...(ctx.version === undefined ? {} : { 'coffre:version': String(ctx.version) }),
|
|
225
230
|
};
|
|
226
231
|
}
|
|
227
232
|
|
package/src/kek/check.ts
CHANGED
|
@@ -1,49 +1,8 @@
|
|
|
1
|
-
// What a vault
|
|
2
|
-
//
|
|
3
|
-
//
|
|
4
|
-
//
|
|
5
|
-
|
|
6
|
-
// operator's machine, the key never sent anywhere.
|
|
7
|
-
import { createHash, hkdfSync } from 'node:crypto';
|
|
8
|
-
|
|
9
|
-
import { deriveLogKey } from '../audit/chain.ts';
|
|
10
|
-
import type { SecretContext } from '../context.ts';
|
|
11
|
-
import { equalBytes, LocalKekProvider } from './local.ts';
|
|
12
|
-
import { KekBadClaimError, type WrappedDek } from './types.ts';
|
|
13
|
-
|
|
14
|
-
/** The action of the vault's entry that holds a vault key's check. */
|
|
15
|
-
export const KEY_CHECK = 'key.check';
|
|
16
|
-
|
|
17
|
-
/** The known value a check wraps: the size of a data key. */
|
|
18
|
-
export const KEY_CHECK_VALUE: Buffer = createHash('sha256').update('coffre.kek.check.v1').digest();
|
|
19
|
-
|
|
20
|
-
const NIL = '00000000-0000-0000-0000-000000000000';
|
|
21
|
-
|
|
22
|
-
/** The context a check is wrapped in, which no secret has: the nil UUID throughout. */
|
|
23
|
-
export const KEY_CHECK_CONTEXT: SecretContext = { projectId: NIL, environmentId: NIL, secretId: NIL };
|
|
24
|
-
|
|
25
|
-
/**
|
|
26
|
-
* Whether `key`, a local vault key, is the one that wrapped `check`: it
|
|
27
|
-
* opens it, under the vault ID the check names, to the known value. The ID
|
|
28
|
-
* is bound into the wrap, so a match also says the ID is the escrowed one's.
|
|
29
|
-
*/
|
|
30
|
-
export async function opensKeyCheck(key: Buffer, check: WrappedDek): Promise<boolean> {
|
|
31
|
-
if (check.kekProvider !== 'local' || key.length !== 32) return false;
|
|
32
|
-
try {
|
|
33
|
-
const value = await new LocalKekProvider(key, check.kekId, check.kekVersion).unwrap(check, KEY_CHECK_CONTEXT);
|
|
34
|
-
const right = equalBytes(value, KEY_CHECK_VALUE);
|
|
35
|
-
value.fill(0);
|
|
36
|
-
return right;
|
|
37
|
-
} catch (error) {
|
|
38
|
-
if (error instanceof KekBadClaimError) return false;
|
|
39
|
-
throw error;
|
|
40
|
-
}
|
|
41
|
-
}
|
|
42
|
-
|
|
43
|
-
/** The id the log records for entries the app signs with `key`, its APP_KEY. */
|
|
44
|
-
export function appLogKeyId(key: Uint8Array): string {
|
|
45
|
-
return deriveLogKey('app', key).keyId;
|
|
46
|
-
}
|
|
1
|
+
// What a vault's keys can be checked against without opening anything:
|
|
2
|
+
// each of its signing keys' check (`keyCheckOf`), which the vault answers
|
|
3
|
+
// in `about` and `coffre verify keys` computes again from an escrowed key,
|
|
4
|
+
// on the operator's machine, the key never sent anywhere.
|
|
5
|
+
import { hkdfSync } from 'node:crypto';
|
|
47
6
|
|
|
48
7
|
/** The label no other use of a vault key shares: a local vault key is otherwise only ever an AES-256-GCM key. */
|
|
49
8
|
const SIGNING_KEY_LABEL = 'coffre.vault.signing-key.v1';
|
|
@@ -56,3 +15,14 @@ const SIGNING_KEY_LABEL = 'coffre.vault.signing-key.v1';
|
|
|
56
15
|
export function derivedSigningKey(kek: Uint8Array): Buffer {
|
|
57
16
|
return Buffer.from(hkdfSync('sha256', kek, new Uint8Array(0), SIGNING_KEY_LABEL, 32));
|
|
58
17
|
}
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* A signing key's check, hex: HKDF-SHA-256 of the key under a label of its
|
|
21
|
+
* own, as the vault's other keys are each derived from it under theirs
|
|
22
|
+
* (`keyOf` in @coffre/vault), so the check opens, signs and names nothing.
|
|
23
|
+
* Whoever holds a key tells whether it is the vault's by computing its
|
|
24
|
+
* check; whoever holds only the check learns nothing of the key.
|
|
25
|
+
*/
|
|
26
|
+
export function keyCheckOf(seed: Uint8Array): string {
|
|
27
|
+
return Buffer.from(hkdfSync('sha256', seed, new Uint8Array(0), 'coffre.vault.key-check.v2', 32)).toString('hex');
|
|
28
|
+
}
|
package/src/kek/index.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
export type { KekProvider, WrappedDek, KeyOperation } from './types.ts';
|
|
2
|
-
export { DEK_BYTES, KekUnavailableError, KekCancelledError, KekBadClaimError } from './types.ts';
|
|
2
|
+
export { DEK_BYTES, KekUnavailableError, KekCancelledError, KekRefusedError, KekBadClaimError } from './types.ts';
|
|
3
3
|
export { LocalKekProvider, equalBytes } from './local.ts';
|
|
4
4
|
export { KekRegistry } from './registry.ts';
|
|
5
5
|
export { AwsKmsKekProvider, awsKms, type AwsKmsOptions } from './aws-kms.ts';
|
|
6
|
-
export {
|
|
6
|
+
export { derivedSigningKey, keyCheckOf } from './check.ts';
|
|
7
7
|
export type { AwsCredentials } from './sigv4.ts';
|
package/src/kek/types.ts
CHANGED
|
@@ -32,7 +32,8 @@ export type KeyOperation = { deadline: number; signal: AbortSignal };
|
|
|
32
32
|
* context (`aws-kms.ts`). Scaleway's Audit Trail does not log Key Manager
|
|
33
33
|
* Decrypt at all, which is why AWS came first.
|
|
34
34
|
*
|
|
35
|
-
* `unwrap` throws `KekUnavailableError` when the service cannot answer,
|
|
35
|
+
* `unwrap` throws `KekUnavailableError` when the service cannot answer,
|
|
36
|
+
* `KekRefusedError` when it refuses coffre itself for good, and
|
|
36
37
|
* `KekBadClaimError` when the wrapped DEK does not open under `ctx`. Other
|
|
37
38
|
* errors are unexpected faults; the vault records them and fails the call.
|
|
38
39
|
*/
|
|
@@ -50,8 +51,9 @@ export const DEK_BYTES = 32;
|
|
|
50
51
|
|
|
51
52
|
/**
|
|
52
53
|
* The key service could not answer: it is down, throttling past the
|
|
53
|
-
* retries, or
|
|
54
|
-
* wrapped key, so the vault fails the call
|
|
54
|
+
* retries, or out of time; or it refuses coffre itself (`KekRefusedError`).
|
|
55
|
+
* Nothing is known about the wrapped key, so the vault fails the call
|
|
56
|
+
* instead of refusing it.
|
|
55
57
|
*/
|
|
56
58
|
export class KekUnavailableError extends Error {
|
|
57
59
|
override readonly name: string = 'KekUnavailableError';
|
|
@@ -73,6 +75,16 @@ export class KekCancelledError extends KekUnavailableError {
|
|
|
73
75
|
}
|
|
74
76
|
}
|
|
75
77
|
|
|
78
|
+
/**
|
|
79
|
+
* The key service answered, and said no for good: it refuses coffre's
|
|
80
|
+
* credentials, the key is disabled or gone, or it opened under another key.
|
|
81
|
+
* Asked again, it says the same: the vault fails the call as for any other
|
|
82
|
+
* `KekUnavailableError`, but whoever runs coffre must act, and nobody's retry helps.
|
|
83
|
+
*/
|
|
84
|
+
export class KekRefusedError extends KekUnavailableError {
|
|
85
|
+
override readonly name = 'KekRefusedError';
|
|
86
|
+
}
|
|
87
|
+
|
|
76
88
|
/** The ciphertext does not open under the claimed key and context. */
|
|
77
89
|
export class KekBadClaimError extends Error {
|
|
78
90
|
override readonly name = 'KekBadClaimError';
|
package/src/log/index.ts
ADDED
package/src/log/tiles.ts
ADDED
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
import { HASH_SIZE, nodeHash, treeHash, type Hash, type Nodes } from './tree.ts';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The tree's storage (docs/design/0.16.md, `log_tiles`): tiles, as Go's sumdb
|
|
5
|
+
* and C2SP tlog-tiles lay them out, of height 8. The tile at (level t, index
|
|
6
|
+
* i) holds up to 256 hashes: the nodes at tree level 8t numbered i·256
|
|
7
|
+
* onwards, concatenated. A level-0 tile holds leaf hashes; a level-1 tile,
|
|
8
|
+
* the roots of 256-leaf subtrees; and so on. Any perfect subtree's hash is in
|
|
9
|
+
* one tile or is at most 128 hashes away from one, so a proof reads at most
|
|
10
|
+
* two tiles per level of tiles, the entry's and the right edge's: 7 at 2^32
|
|
11
|
+
* leaves.
|
|
12
|
+
*
|
|
13
|
+
* A tile's hashes never change once written, only grow (the partial tile at
|
|
14
|
+
* the tree's right edge), so a tile is read for any older tree size by taking
|
|
15
|
+
* its prefix.
|
|
16
|
+
*
|
|
17
|
+
* Pruning a tree deletes level-0 tiles from its start, whole, with the 256
|
|
18
|
+
* entries each stands for. The level-1 tile above keeps each one's root, so
|
|
19
|
+
* the head still covers the pruned entries, and every entry that is kept
|
|
20
|
+
* proves from tiles that are kept.
|
|
21
|
+
*
|
|
22
|
+
* A full verify of a pruned tree is `Edge.load` at the first kept entry, then
|
|
23
|
+
* `append` of every kept entry's hash, which must arrive at the signed head.
|
|
24
|
+
* `nodesFrom` cannot do it: it answers for a block of 256 from the tile above
|
|
25
|
+
* and never reads the block's own hashes.
|
|
26
|
+
*/
|
|
27
|
+
export const HEIGHT = 8;
|
|
28
|
+
export const WIDTH = 256;
|
|
29
|
+
|
|
30
|
+
export type TileKey = { level: number; index: number };
|
|
31
|
+
export type Tile = TileKey & { hashes: Buffer };
|
|
32
|
+
|
|
33
|
+
export const tileKey = (level: number, index: number) => `${level}/${index}`;
|
|
34
|
+
|
|
35
|
+
/** Which tile, and where in it, holds what node (level, index) is computed from. */
|
|
36
|
+
export function tileOf(level: number, index: number): { tile: TileKey; offset: number; count: number } {
|
|
37
|
+
const t = Math.floor(level / HEIGHT);
|
|
38
|
+
const count = 2 ** (level - t * HEIGHT);
|
|
39
|
+
const first = index * count;
|
|
40
|
+
return { tile: { level: t, index: Math.floor(first / WIDTH) }, offset: first % WIDTH, count };
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** A `Nodes` over a set of tiles, keyed by `tileKey`: each node from the hashes of its tile. */
|
|
44
|
+
export function nodesFrom(tiles: ReadonlyMap<string, Buffer>): Nodes {
|
|
45
|
+
return (level, index) => {
|
|
46
|
+
const { tile, offset, count } = tileOf(level, index);
|
|
47
|
+
const hashes = tiles.get(tileKey(tile.level, tile.index));
|
|
48
|
+
if (hashes === undefined || hashes.length < (offset + count) * HASH_SIZE) {
|
|
49
|
+
throw new Error(`tile ${tile.level}/${tile.index} lacks node ${level}/${index}`);
|
|
50
|
+
}
|
|
51
|
+
const layer: Hash[] = [];
|
|
52
|
+
for (let i = 0; i < count; i += 1) layer.push(hashes.subarray((offset + i) * HASH_SIZE, (offset + i + 1) * HASH_SIZE));
|
|
53
|
+
return hashUp(layer);
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** The root of a perfect subtree from its 2^k bottom hashes. */
|
|
58
|
+
function hashUp(hashes: readonly Hash[]): Hash {
|
|
59
|
+
let layer = hashes;
|
|
60
|
+
while (layer.length > 1) {
|
|
61
|
+
const up: Hash[] = [];
|
|
62
|
+
for (let i = 0; i < layer.length; i += 2) up.push(nodeHash(layer[i]!, layer[i + 1]!));
|
|
63
|
+
layer = up;
|
|
64
|
+
}
|
|
65
|
+
return Buffer.from(layer[0]!);
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** The tiles a computation over `Nodes` reads: run it once against a recorder, then fetch them all in one query. */
|
|
69
|
+
export function tilesFor(compute: (nodes: Nodes) => unknown): TileKey[] {
|
|
70
|
+
const seen = new Map<string, TileKey>();
|
|
71
|
+
compute((level, index) => {
|
|
72
|
+
const { tile } = tileOf(level, index);
|
|
73
|
+
seen.set(tileKey(tile.level, tile.index), tile);
|
|
74
|
+
return Buffer.alloc(HASH_SIZE);
|
|
75
|
+
});
|
|
76
|
+
return [...seen.values()];
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export function tileMap(tiles: readonly Tile[]): Map<string, Buffer> {
|
|
80
|
+
return new Map(tiles.map((t) => [tileKey(t.level, t.index), t.hashes]));
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/** The tiles at the right edge of a tree of `size` leaves, one per level, with their widths: all the state appending needs. */
|
|
84
|
+
export function edgeOf(size: number): (TileKey & { width: number })[] {
|
|
85
|
+
const edge: (TileKey & { width: number })[] = [];
|
|
86
|
+
for (let t = 0; ; t += 1) {
|
|
87
|
+
const below = Math.floor(size / 2 ** (t * HEIGHT));
|
|
88
|
+
edge.push({ level: t, index: Math.floor(below / WIDTH), width: below % WIDTH });
|
|
89
|
+
if (below < WIDTH) return edge;
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* The tree's growing edge, in memory: the partial tile at each level.
|
|
95
|
+
* Appending leaves fills level 0; each tile that fills up pushes its root into
|
|
96
|
+
* the level above. What changed comes back as tiles to write: every tile
|
|
97
|
+
* filled, and every partial edge tile that grew.
|
|
98
|
+
*/
|
|
99
|
+
export class Edge {
|
|
100
|
+
size: number;
|
|
101
|
+
private tiles: Hash[][];
|
|
102
|
+
|
|
103
|
+
private constructor(size: number, tiles: Hash[][]) {
|
|
104
|
+
this.size = size;
|
|
105
|
+
this.tiles = tiles;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
static empty(): Edge {
|
|
109
|
+
return new Edge(0, [[]]);
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/** From the stored edge tiles of a tree of `size` leaves (`edgeOf(size)`), each cut to its width. */
|
|
113
|
+
static load(size: number, stored: ReadonlyMap<string, Buffer>): Edge {
|
|
114
|
+
const tiles = edgeOf(size).map(({ level, index, width }) => {
|
|
115
|
+
if (width === 0) return [];
|
|
116
|
+
const hashes = stored.get(tileKey(level, index));
|
|
117
|
+
if (hashes === undefined || hashes.length < width * HASH_SIZE) throw new Error(`edge tile ${level}/${index} missing or short`);
|
|
118
|
+
return Array.from({ length: width }, (_, i) => Buffer.from(hashes.subarray(i * HASH_SIZE, (i + 1) * HASH_SIZE)));
|
|
119
|
+
});
|
|
120
|
+
return new Edge(size, tiles);
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/** A copy to append to, so a failed write leaves this edge at the head it was. */
|
|
124
|
+
clone(): Edge {
|
|
125
|
+
return new Edge(this.size, this.tiles.map((t) => [...t]));
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
append(leaves: readonly Hash[]): Tile[] {
|
|
129
|
+
const changed: Tile[] = [];
|
|
130
|
+
// Levels whose partial tile grew: written as they stand once every leaf is in.
|
|
131
|
+
const grew = new Set<number>();
|
|
132
|
+
for (const leaf of leaves) {
|
|
133
|
+
let hash = leaf;
|
|
134
|
+
for (let t = 0; ; t += 1) {
|
|
135
|
+
const tile = (this.tiles[t] ??= []);
|
|
136
|
+
tile.push(hash);
|
|
137
|
+
if (tile.length < WIDTH) {
|
|
138
|
+
grew.add(t);
|
|
139
|
+
break;
|
|
140
|
+
}
|
|
141
|
+
// A full tile is written now and never again; its root goes up a level.
|
|
142
|
+
changed.push({ level: t, index: Math.floor(this.size / 2 ** ((t + 1) * HEIGHT)), hashes: Buffer.concat(tile) });
|
|
143
|
+
grew.delete(t);
|
|
144
|
+
hash = hashUp(tile);
|
|
145
|
+
this.tiles[t] = [];
|
|
146
|
+
}
|
|
147
|
+
this.size += 1;
|
|
148
|
+
}
|
|
149
|
+
for (const t of grew) changed.push({ level: t, index: Math.floor(this.size / 2 ** ((t + 1) * HEIGHT)), hashes: Buffer.concat(this.tiles[t]!) });
|
|
150
|
+
return changed;
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/** The tree head now. */
|
|
154
|
+
root(): Hash {
|
|
155
|
+
return treeHash(nodesFrom(tileMap(this.edgeTiles())), this.size);
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* The tile at the right edge of each level, as it stands. With the tiles an append filled, they hold every node a
|
|
160
|
+
* proof of a leaf that append added reads: the tile of the leaf's ancestor at each level is one of them, and so is
|
|
161
|
+
* every tile to its right.
|
|
162
|
+
*/
|
|
163
|
+
edgeTiles(): Tile[] {
|
|
164
|
+
return edgeOf(this.size).map(({ level, index }) => ({ level, index, hashes: Buffer.concat(this.tiles[level] ?? []) }));
|
|
165
|
+
}
|
|
166
|
+
}
|
package/src/log/tree.ts
ADDED
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* RFC 9162's Merkle tree (Certificate Transparency 2.0, the same tree as RFC
|
|
5
|
+
* 6962), byte for byte: a leaf hashes as SHA-256(0x00 || data), a node as
|
|
6
|
+
* SHA-256(0x01 || left || right), and a tree of n leaves splits at the largest
|
|
7
|
+
* power of two below n. The tests hold it to heads, proofs and tiles that
|
|
8
|
+
* Go's golang.org/x/mod/sumdb/tlog computed (test/vectors/log-tree-go.json).
|
|
9
|
+
*
|
|
10
|
+
* Every hash here comes from `Nodes`, which answers for perfect subtrees only
|
|
11
|
+
* (2^level leaves starting at leaf index·2^level). Tiles store those; a proof
|
|
12
|
+
* never needs another kind.
|
|
13
|
+
*
|
|
14
|
+
* Sizes and indexes are plain numbers: exact to 2^53 leaves, 285,000 years at
|
|
15
|
+
* 1,000 a second. No bitwise operator touches them, since JavaScript's cut to
|
|
16
|
+
* 32 bits, and a log passes 2^32 leaves in 50 days at that rate.
|
|
17
|
+
*/
|
|
18
|
+
export type Hash = Buffer;
|
|
19
|
+
|
|
20
|
+
export const HASH_SIZE = 32;
|
|
21
|
+
|
|
22
|
+
const LEAF = Buffer.from([0]);
|
|
23
|
+
const NODE = Buffer.from([1]);
|
|
24
|
+
|
|
25
|
+
export function leafHash(data: Uint8Array): Hash {
|
|
26
|
+
return createHash('sha256').update(LEAF).update(data).digest();
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
export function nodeHash(left: Hash, right: Hash): Hash {
|
|
30
|
+
return createHash('sha256').update(NODE).update(left).update(right).digest();
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** The head of the empty tree: SHA-256 of nothing. */
|
|
34
|
+
export const EMPTY_ROOT: Hash = createHash('sha256').digest();
|
|
35
|
+
|
|
36
|
+
/** The hash of the perfect subtree of 2^level leaves starting at leaf index·2^level. */
|
|
37
|
+
export type Nodes = (level: number, index: number) => Hash;
|
|
38
|
+
|
|
39
|
+
/** The largest power of two strictly below n (n ≥ 2). */
|
|
40
|
+
function split(n: number): number {
|
|
41
|
+
let k = 1;
|
|
42
|
+
while (k * 2 < n) k *= 2;
|
|
43
|
+
return k;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
const log2 = (n: number) => Math.round(Math.log2(n));
|
|
47
|
+
|
|
48
|
+
export const isPowerOfTwo = (n: number) => n > 0 && 2 ** log2(n) === n;
|
|
49
|
+
|
|
50
|
+
/** MTH(D[start:start+n]): the hash of any range, from the perfect subtrees it decomposes into. */
|
|
51
|
+
export function rangeHash(nodes: Nodes, start: number, n: number): Hash {
|
|
52
|
+
if (n === 0) return EMPTY_ROOT;
|
|
53
|
+
if (isPowerOfTwo(n) && start % n === 0) return nodes(log2(n), start / n);
|
|
54
|
+
const k = split(n);
|
|
55
|
+
return nodeHash(rangeHash(nodes, start, k), rangeHash(nodes, start + k, n - k));
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** The tree head: MTH of the first `size` leaves. */
|
|
59
|
+
export function treeHash(nodes: Nodes, size: number): Hash {
|
|
60
|
+
return rangeHash(nodes, 0, size);
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** RFC 9162 2.1.3.1, PATH(m, D[n]): the inclusion proof of leaf m in the tree of n leaves, leaf to root. */
|
|
64
|
+
export function inclusionProof(nodes: Nodes, m: number, n: number): Hash[] {
|
|
65
|
+
if (!Number.isSafeInteger(m) || m < 0 || m >= n) throw new Error(`leaf ${m} is not in a tree of ${n}`);
|
|
66
|
+
const path: Hash[] = [];
|
|
67
|
+
const walk = (m: number, start: number, n: number): void => {
|
|
68
|
+
if (n === 1) return;
|
|
69
|
+
const k = split(n);
|
|
70
|
+
if (m < k) {
|
|
71
|
+
walk(m, start, k);
|
|
72
|
+
path.push(rangeHash(nodes, start + k, n - k));
|
|
73
|
+
} else {
|
|
74
|
+
walk(m - k, start + k, n - k);
|
|
75
|
+
path.push(rangeHash(nodes, start, k));
|
|
76
|
+
}
|
|
77
|
+
};
|
|
78
|
+
walk(m, 0, n);
|
|
79
|
+
return path;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** RFC 9162 2.1.4.1, PROOF(m, D[n]): that the tree of m leaves is a prefix of the tree of n. */
|
|
83
|
+
export function consistencyProof(nodes: Nodes, m: number, n: number): Hash[] {
|
|
84
|
+
if (!Number.isSafeInteger(m) || m < 0 || m > n) throw new Error(`no consistency from ${m} to ${n}`);
|
|
85
|
+
if (m === 0 || m === n) return [];
|
|
86
|
+
const path: Hash[] = [];
|
|
87
|
+
const sub = (m: number, start: number, n: number, whole: boolean): void => {
|
|
88
|
+
if (m === n) {
|
|
89
|
+
if (!whole) path.push(rangeHash(nodes, start, n));
|
|
90
|
+
return;
|
|
91
|
+
}
|
|
92
|
+
const k = split(n);
|
|
93
|
+
if (m <= k) {
|
|
94
|
+
sub(m, start, k, whole);
|
|
95
|
+
path.push(rangeHash(nodes, start + k, n - k));
|
|
96
|
+
} else {
|
|
97
|
+
sub(m - k, start + k, n - k, false);
|
|
98
|
+
path.push(rangeHash(nodes, start, k));
|
|
99
|
+
}
|
|
100
|
+
};
|
|
101
|
+
sub(m, 0, n, true);
|
|
102
|
+
return path;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/** RFC 9162 2.1.3.2: whether `proof` shows `leaf` at index m of the tree of n leaves whose head is `root`. */
|
|
106
|
+
export function verifyInclusion(leaf: Hash, m: number, n: number, proof: readonly Hash[], root: Hash): boolean {
|
|
107
|
+
if (!Number.isSafeInteger(m) || !Number.isSafeInteger(n) || m < 0 || m >= n) return false;
|
|
108
|
+
let fn = m;
|
|
109
|
+
let sn = n - 1;
|
|
110
|
+
let r = leaf;
|
|
111
|
+
for (const p of proof) {
|
|
112
|
+
if (sn === 0) return false;
|
|
113
|
+
if (fn % 2 === 1 || fn === sn) {
|
|
114
|
+
r = nodeHash(p, r);
|
|
115
|
+
if (fn % 2 === 0) {
|
|
116
|
+
while (fn % 2 === 0 && fn !== 0) {
|
|
117
|
+
fn = Math.floor(fn / 2);
|
|
118
|
+
sn = Math.floor(sn / 2);
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
} else {
|
|
122
|
+
r = nodeHash(r, p);
|
|
123
|
+
}
|
|
124
|
+
fn = Math.floor(fn / 2);
|
|
125
|
+
sn = Math.floor(sn / 2);
|
|
126
|
+
}
|
|
127
|
+
return sn === 0 && r.equals(root);
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** RFC 9162 2.1.4.2: whether `proof` shows the tree of m leaves (head `first`) a prefix of the tree of n (head `second`). */
|
|
131
|
+
export function verifyConsistency(m: number, n: number, first: Hash, second: Hash, proof: readonly Hash[]): boolean {
|
|
132
|
+
if (!Number.isSafeInteger(m) || !Number.isSafeInteger(n) || m < 0 || m > n) return false;
|
|
133
|
+
if (m === 0) return proof.length === 0 && first.equals(EMPTY_ROOT) && (n > 0 || second.equals(EMPTY_ROOT));
|
|
134
|
+
if (m === n) return proof.length === 0 && first.equals(second);
|
|
135
|
+
const path = isPowerOfTwo(m) ? [first, ...proof] : [...proof];
|
|
136
|
+
if (path.length === 0) return false;
|
|
137
|
+
let fn = m - 1;
|
|
138
|
+
let sn = n - 1;
|
|
139
|
+
while (fn % 2 === 1) {
|
|
140
|
+
fn = Math.floor(fn / 2);
|
|
141
|
+
sn = Math.floor(sn / 2);
|
|
142
|
+
}
|
|
143
|
+
let fr = path[0]!;
|
|
144
|
+
let sr = path[0]!;
|
|
145
|
+
for (const c of path.slice(1)) {
|
|
146
|
+
if (sn === 0) return false;
|
|
147
|
+
if (fn % 2 === 1 || fn === sn) {
|
|
148
|
+
fr = nodeHash(c, fr);
|
|
149
|
+
sr = nodeHash(c, sr);
|
|
150
|
+
if (fn % 2 === 0) {
|
|
151
|
+
while (fn % 2 === 0 && fn !== 0) {
|
|
152
|
+
fn = Math.floor(fn / 2);
|
|
153
|
+
sn = Math.floor(sn / 2);
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
} else {
|
|
157
|
+
sr = nodeHash(sr, c);
|
|
158
|
+
}
|
|
159
|
+
fn = Math.floor(fn / 2);
|
|
160
|
+
sn = Math.floor(sn / 2);
|
|
161
|
+
}
|
|
162
|
+
return sn === 0 && fr.equals(first) && sr.equals(second);
|
|
163
|
+
}
|
package/src/mcp.ts
CHANGED
|
@@ -29,6 +29,23 @@ export const MCP_SCOPE_INFO: Record<McpScope, { label: string; description: stri
|
|
|
29
29
|
},
|
|
30
30
|
};
|
|
31
31
|
|
|
32
|
+
/** How long a code waits for its client: long enough for a redirect, and no longer. */
|
|
33
|
+
export const CODE_SECONDS = 60;
|
|
34
|
+
/** An hour: what a leaked access token is good for, at most, unless its connection ends sooner. */
|
|
35
|
+
export const ACCESS_TOKEN_MINUTES = 60;
|
|
36
|
+
/** Connections a person may hold at once, codes waiting included, before Connected apps has to lose one. */
|
|
37
|
+
export const MAX_CONNECTIONS = 20;
|
|
38
|
+
/** Registered clients the instance keeps at most: anyone may register one, so the table has a ceiling. */
|
|
39
|
+
export const MAX_CLIENTS = 10_000;
|
|
40
|
+
/** How long an approval waits for its person: a change an MCP client asks for that nobody decides by then expired. */
|
|
41
|
+
export const APPROVAL_SECONDS = 5 * 60;
|
|
42
|
+
/** Approvals a connection holds waiting at once: no flood of prompts, and no more than this many entries an expiry. */
|
|
43
|
+
export const MAX_PENDING = 5;
|
|
44
|
+
/** The longest a call's arguments are, as canonical JSON, that an approval keeps: a few names, a note, a scope of some places. */
|
|
45
|
+
export const MAX_ASK_ARGUMENTS = 4096;
|
|
46
|
+
/** The tools whose Approve changes nothing but shows the person a value (`mcp.decide`): every other is approved by its change. */
|
|
47
|
+
export const MCP_SHOWS: readonly string[] = ['show_secret_value'];
|
|
48
|
+
|
|
32
49
|
/** What OAuth's `offline_access` asks for, a refresh token, every connection has: accepted and dropped. */
|
|
33
50
|
const IGNORED_SCOPES = new Set(['offline_access']);
|
|
34
51
|
|
|
@@ -94,6 +111,8 @@ export type RedirectKind = 'https' | 'loopback';
|
|
|
94
111
|
* scheme, no fragment, no user or password.
|
|
95
112
|
*/
|
|
96
113
|
export function redirectKind(value: string): RedirectKind {
|
|
114
|
+
// The URL parser drops a trailing NUL, but the vault keeps the text as given, and Postgres stores no NUL nor half of a surrogate pair.
|
|
115
|
+
if (/[\0\p{Cs}]/u.test(value)) throw new ClientInvalid('a redirect holds a NUL or half of a surrogate pair');
|
|
97
116
|
let url: URL;
|
|
98
117
|
try {
|
|
99
118
|
url = new URL(value);
|
|
@@ -151,6 +170,15 @@ export type ClientMetadata = {
|
|
|
151
170
|
|
|
152
171
|
const MAX_REDIRECTS = 10;
|
|
153
172
|
const MAX_NAME = 100;
|
|
173
|
+
/** The longest client id the vault keeps (`text` in its ops). */
|
|
174
|
+
export const MAX_CLIENT_ID = 256;
|
|
175
|
+
|
|
176
|
+
/**
|
|
177
|
+
* Whether a client_id is one the vault and Postgres keep: 256 characters at
|
|
178
|
+
* most, with no NUL and no half of a surrogate pair. Any other is no
|
|
179
|
+
* client's, and is answered as such before it is read or sent anywhere.
|
|
180
|
+
*/
|
|
181
|
+
export const clientIdKept = (value: string): boolean => value.length <= MAX_CLIENT_ID && !/[\0\p{Cs}]/u.test(value);
|
|
154
182
|
|
|
155
183
|
/**
|
|
156
184
|
* Whether `value` is a Client ID Metadata Document's URL: HTTPS, with a
|
|
@@ -222,11 +250,14 @@ export function registrationRedirects(value: unknown): { kept: string[]; dropped
|
|
|
222
250
|
return { kept, dropped };
|
|
223
251
|
}
|
|
224
252
|
|
|
225
|
-
/** A client's name as shown: its own,
|
|
253
|
+
/** A client's name as shown: its own, or its host when it gives none, cut short. */
|
|
226
254
|
export function clientName(value: unknown, fallback: string): string {
|
|
227
255
|
// Control and bidirectional characters could make one name look like another.
|
|
228
|
-
|
|
229
|
-
|
|
256
|
+
// Half of a surrogate pair goes too: it is no text Postgres stores.
|
|
257
|
+
const own = typeof value === 'string' ? value.replace(/[\p{Cc}\p{Cf}\p{Cs}]/gu, '').trim() : '';
|
|
258
|
+
// Cut on a whole character, and trimmed again: what the vault keeps is the name as shown (`named` in its ops/mcp.ts).
|
|
259
|
+
// A host is cut too: a document's may be 200 characters, and the vault keeps 100.
|
|
260
|
+
return (own === '' ? fallback : own).slice(0, MAX_NAME).replace(/[\uD800-\uDBFF]$/, '').trim();
|
|
230
261
|
}
|
|
231
262
|
|
|
232
263
|
function redirectList(value: unknown): string[] {
|
package/src/schemas.ts
CHANGED
|
@@ -41,17 +41,31 @@ export function tombstoneOf(slug: string, day: Date, n = 1): string {
|
|
|
41
41
|
const base = `${slug}${TOMBSTONE}deleted-${day.toISOString().slice(0, 10)}`;
|
|
42
42
|
return n === 1 ? base : `${base}-${n}`;
|
|
43
43
|
}
|
|
44
|
+
|
|
45
|
+
/** A tombstone's slug, as `tombstoneOf` writes it: the name a deleted place's log is still read by. */
|
|
46
|
+
export const tombstoneSlug = z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}~deleted-\d{4}-\d{2}-\d{2}(?:-[1-9]\d*)?$/);
|
|
44
47
|
export const displayName = z.string().trim().min(1).max(120);
|
|
45
|
-
/** A folder: 1 to 64 characters, no `/`, no control character, no space at either end (the tables check it too). */
|
|
48
|
+
/** A folder: 1 to 64 characters of well-formed Unicode, no `/`, no control character, no space at either end (the tables and the vault check it too). */
|
|
46
49
|
export const folderName = z.string().min(1).max(64)
|
|
47
50
|
.refine((name) => name === name.trim(), 'a folder name cannot start or end with a space')
|
|
48
|
-
.refine((name) => !/[/\p{Cc}]/u.test(name), 'a folder name cannot hold "/" or a
|
|
51
|
+
.refine((name) => !/[/\p{Cc}\p{Cs}]/u.test(name), 'a folder name cannot hold "/", a control character or half of a surrogate pair');
|
|
49
52
|
export const secretKey = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]{0,127}$/);
|
|
50
53
|
/**
|
|
51
54
|
* A member as people read it, in a message or on a page: a service account
|
|
52
55
|
* as `service:<name>`, though the API, the vault and the log keep the
|
|
53
56
|
* `token:<name>` their signed entries hold.
|
|
54
57
|
*/
|
|
58
|
+
/** A service account by its member id, `token:<name>`, as the vault takes one (`principals_id_check`). */
|
|
59
|
+
export const SERVICE_MEMBER = /^token:[^\s:]\S*$/;
|
|
60
|
+
/** A service account's member id as the vault's contract takes one: `SERVICE_MEMBER`, in 256 characters of well-formed Unicode with no NUL. */
|
|
61
|
+
export function isServiceMember(value: unknown): value is string {
|
|
62
|
+
return typeof value === 'string' && value.length <= 256 && !/[\0\p{Cs}]/u.test(value) && SERVICE_MEMBER.test(value);
|
|
63
|
+
}
|
|
64
|
+
/** A row's id as the vault draws and takes one: a UUID, in lowercase. */
|
|
65
|
+
export const ROW_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
|
|
66
|
+
/** A row's id as a request may spell it: any UUID, in the lowercase the vault takes. */
|
|
67
|
+
export const rowId = z.uuid().transform((id) => id.toLowerCase());
|
|
68
|
+
|
|
55
69
|
export function shownMember(member: string): string {
|
|
56
70
|
return member.startsWith('token:') ? `service:${member.slice('token:'.length)}` : member;
|
|
57
71
|
}
|