@coffre/core 0.15.0 → 0.16.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.
Files changed (70) hide show
  1. package/README.md +1 -1
  2. package/dist/{access-CgQTlUMz.js → access-CF8UG59J.js} +70 -95
  3. package/dist/{access-DqLJjnLM.d.ts → access-ERdGGHG7.d.ts} +45 -64
  4. package/dist/access.d.ts +2 -2
  5. package/dist/access.js +2 -2
  6. package/dist/envelope.d.ts +28 -9
  7. package/dist/envelope.js +25 -8
  8. package/dist/identity.d.ts +3 -1018
  9. package/dist/identity.js +885 -623
  10. package/dist/index-DuG9p3GH.d.ts +1233 -0
  11. package/dist/kek.d.ts +10 -16
  12. package/dist/kek.js +26 -41
  13. package/dist/log.d.ts +114 -0
  14. package/dist/log.js +291 -0
  15. package/dist/mcp.d.ts +27 -4
  16. package/dist/mcp.js +31 -10
  17. package/dist/recipe-BgJpmJum.d.ts +128 -0
  18. package/dist/recipe.d.ts +2 -127
  19. package/dist/{registry-D7X-x202.d.ts → registry-B7_LUDsJ.d.ts} +30 -5
  20. package/dist/schemas.d.ts +11 -9
  21. package/dist/schemas.js +16 -14
  22. package/dist/{types-Cp3lB_-W.js → types-DwTO_b4H.js} +17 -5
  23. package/dist/vault.d.ts +1771 -1419
  24. package/dist/vault.js +96 -302
  25. package/dist/{workloads-D049JH0M.d.ts → workloads-CW2dK4AW.d.ts} +1 -9
  26. package/dist/workloads.d.ts +2 -2
  27. package/dist/workloads.js +1 -9
  28. package/package.json +7 -7
  29. package/src/access.ts +63 -95
  30. package/src/changes/access.ts +140 -0
  31. package/src/changes/freezes.ts +40 -0
  32. package/src/changes/mcp.ts +150 -0
  33. package/src/changes/places.ts +219 -0
  34. package/src/changes/secrets.ts +235 -0
  35. package/src/changes/signin.ts +197 -0
  36. package/src/changes/workloads.ts +166 -0
  37. package/src/context.ts +18 -2
  38. package/src/envelope.ts +35 -12
  39. package/src/identity/auth.ts +11 -3
  40. package/src/identity/aws.ts +62 -0
  41. package/src/identity/github-app.ts +45 -24
  42. package/src/identity/index.ts +3 -2
  43. package/src/identity/{profile-rules.ts → profiles.ts} +1 -9
  44. package/src/identity/proofs.ts +306 -0
  45. package/src/identity/signin/config.ts +1 -1
  46. package/src/identity/tokens.ts +10 -3
  47. package/src/identity/verifier.ts +73 -14
  48. package/src/identity/workload-token.ts +4 -0
  49. package/src/identity/workloads.ts +0 -11
  50. package/src/kek/aws-kms.ts +18 -13
  51. package/src/kek/check.ts +16 -46
  52. package/src/kek/index.ts +2 -2
  53. package/src/kek/types.ts +15 -3
  54. package/src/log/index.ts +7 -0
  55. package/src/{audit → log}/tiles.ts +18 -49
  56. package/src/{audit → log}/tree.ts +2 -2
  57. package/src/mcp.ts +36 -9
  58. package/src/schemas.ts +15 -12
  59. package/src/vault.ts +251 -1150
  60. package/dist/merkle.d.ts +0 -456
  61. package/dist/merkle.js +0 -964
  62. package/src/answers.ts +0 -209
  63. package/src/audit/leaf.ts +0 -81
  64. package/src/audit/merkle.ts +0 -13
  65. package/src/audit/note.ts +0 -187
  66. package/src/audit/pair.ts +0 -86
  67. package/src/audit/verify.ts +0 -393
  68. package/src/audit/witness.ts +0 -50
  69. package/src/checkpoint.ts +0 -22
  70. package/src/identity/run-proof.ts +0 -159
package/src/kek/check.ts CHANGED
@@ -1,49 +1,8 @@
1
- // What a vault key, or the app key, can be checked against without opening
2
- // anything else: the vault's `key.check` entries, each a known value wrapped
3
- // under one vault key, and the key id the log records for the app's entries,
4
- // a fingerprint of the key they are signed with. The vault writes the
5
- // checks; `coffre verify keys` holds an escrowed key to them, on the
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 { appLogKeyId, derivedSigningKey, KEY_CHECK, KEY_CHECK_CONTEXT, KEY_CHECK_VALUE, opensKeyCheck } from './check.ts';
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, and
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 refusing coffre's own credentials. Nothing is known about the
54
- * wrapped key, so the vault fails the call instead of refusing it.
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';
@@ -0,0 +1,7 @@
1
+ /**
2
+ * 0.16's log (docs/design/0.16.md): an RFC 9162 Merkle tree over the entries,
3
+ * stored as tiles of 256 hashes. Pure code: the signer and the database wire
4
+ * it.
5
+ */
6
+ export * from './tiles.ts';
7
+ export * from './tree.ts';
@@ -1,16 +1,28 @@
1
1
  import { HASH_SIZE, nodeHash, treeHash, type Hash, type Nodes } from './tree.ts';
2
2
 
3
3
  /**
4
- * The tree's storage: tiles, as Go's sumdb and C2SP tlog-tiles lay them out,
5
- * of height 8. The tile at (level t, index i) holds up to 256 hashes: the
6
- * nodes at tree level 8t numbered i·256 onwards, concatenated. A level-0 tile
7
- * holds leaf hashes; a level-1 tile, the roots of 256-leaf subtrees; and so
8
- * on. Any perfect subtree's hash is in one tile or is at most 128 hashes away
9
- * from one, so a proof reads one tile per 8 levels: 4 tiles at 2^32 leaves.
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.
10
12
  *
11
13
  * A tile's hashes never change once written, only grow (the partial tile at
12
14
  * the tree's right edge), so a tile is read for any older tree size by taking
13
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.
14
26
  */
15
27
  export const HEIGHT = 8;
16
28
  export const WIDTH = 256;
@@ -28,26 +40,6 @@ export function tileOf(level: number, index: number): { tile: TileKey; offset: n
28
40
  return { tile: { level: t, index: Math.floor(first / WIDTH) }, offset: first % WIDTH, count };
29
41
  }
30
42
 
31
- /**
32
- * The leaves a tile's hashes stand for: [first, end). Tiles are partitioned by
33
- * it (a level-0 tile by the 256 leaves it holds), so retention drops whole
34
- * ranges of them instead of deleting rows.
35
- */
36
- export function tileLeaves(t: TileKey): { first: number; end: number } {
37
- const span = 2 ** (HEIGHT * (t.level + 1));
38
- return { first: t.index * span, end: (t.index + 1) * span };
39
- }
40
-
41
- /**
42
- * Whether a tile is still read once retention has cut the tree below leaf
43
- * `cut`: proofs of leaves at or above the cut, and consistency proofs from
44
- * sizes at or above it, read only tiles that reach past it, which at each
45
- * level is the tile holding the cut and those after it. Every tile wholly
46
- * below the cut can go, at every level: about one tile per level stays
47
- * where a day of tiles would.
48
- */
49
- export const keptAbove = (t: TileKey, cut: number): boolean => tileLeaves(t).end > cut;
50
-
51
43
  /** A `Nodes` over a set of tiles, keyed by `tileKey`: each node from the hashes of its tile. */
52
44
  export function nodesFrom(tiles: ReadonlyMap<string, Buffer>): Nodes {
53
45
  return (level, index) => {
@@ -172,26 +164,3 @@ export class Edge {
172
164
  return edgeOf(this.size).map(({ level, index }) => ({ level, index, hashes: Buffer.concat(this.tiles[level] ?? []) }));
173
165
  }
174
166
  }
175
-
176
- /** Go's tile path, `tile/8/<L>/<N>[.p/<W>]`, N in groups of three digits (x001/x234/067). */
177
- export function tilePath(t: TileKey, width: number): string {
178
- let n = String(t.index);
179
- const groups: string[] = [];
180
- while (n.length > 3) {
181
- groups.unshift(n.slice(-3));
182
- n = n.slice(0, -3);
183
- }
184
- const parts = [n.padStart(3, '0'), ...groups].map((g, i, all) => (i < all.length - 1 ? `x${g}` : g));
185
- return `tile/${HEIGHT}/${t.level}/${parts.join('/')}${width < WIDTH ? `.p/${width}` : ''}`;
186
- }
187
-
188
- export function parseTilePath(path: string): (TileKey & { width: number }) | null {
189
- const m = /^tile\/8\/(\d{1,2})\/((?:x\d{3}\/)*\d{3})(?:\.p\/(\d{1,3}))?$/.exec(path);
190
- if (m === null) return null;
191
- // A partial tile holds 1 to 255 hashes; a full one has no `.p` part.
192
- const width = m[3] === undefined ? WIDTH : Number(m[3]);
193
- if (width < 1 || (m[3] !== undefined && width >= WIDTH)) return null;
194
- const tile = { level: Number(m[1]), index: Number(m[2]!.replaceAll('x', '').replaceAll('/', '')), width };
195
- // Canonical only, as Go writes them: no leading zeros in the level, no padded groups, so one tile has one path.
196
- return Number.isSafeInteger(tile.index) && tilePath(tile, width) === path ? tile : null;
197
- }
@@ -4,8 +4,8 @@ import { createHash } from 'node:crypto';
4
4
  * RFC 9162's Merkle tree (Certificate Transparency 2.0, the same tree as RFC
5
5
  * 6962), byte for byte: a leaf hashes as SHA-256(0x00 || data), a node as
6
6
  * SHA-256(0x01 || left || right), and a tree of n leaves splits at the largest
7
- * power of two below n. Go's golang.org/x/mod/sumdb/tlog checks what this
8
- * produces (packages/core/test/go, docs/design/audit-tree.md).
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
9
  *
10
10
  * Every hash here comes from `Nodes`, which answers for perfect subtrees only
11
11
  * (2^level leaves starting at leaf index·2^level). Tiles store those; a proof
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,17 +170,22 @@ export type ClientMetadata = {
151
170
 
152
171
  const MAX_REDIRECTS = 10;
153
172
  const MAX_NAME = 100;
154
- /** The longest client ID URL: a token's issue or revoke through its connection names it in the vault's record, which takes no longer. */
155
- const MAX_CLIENT_ID = 2048;
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);
156
182
 
157
183
  /**
158
184
  * Whether `value` is a Client ID Metadata Document's URL: HTTPS, with a
159
- * path, and nothing a document's address has no use for, no longer than
160
- * `MAX_CLIENT_ID`. On a loopback instance, a loopback one too, for
161
- * development and conformance.
185
+ * path, and nothing a document's address has no use for. On a loopback
186
+ * instance, a loopback one too, for development and conformance.
162
187
  */
163
188
  export function isClientIdUrl(value: string, options: { allowLoopback: boolean }): boolean {
164
- if (value.length > MAX_CLIENT_ID) return false;
165
189
  if (!value.startsWith('https://') && !(options.allowLoopback && value.startsWith('http://'))) return false;
166
190
  let url: URL;
167
191
  try {
@@ -226,11 +250,14 @@ export function registrationRedirects(value: unknown): { kept: string[]; dropped
226
250
  return { kept, dropped };
227
251
  }
228
252
 
229
- /** A client's name as shown: its own, cut short, or its host when it gives none. */
253
+ /** A client's name as shown: its own, or its host when it gives none, cut short. */
230
254
  export function clientName(value: unknown, fallback: string): string {
231
255
  // Control and bidirectional characters could make one name look like another.
232
- const name = typeof value === 'string' ? value.replace(/[\p{Cc}\p{Cf}]/gu, '').trim() : '';
233
- return name === '' ? fallback : name.slice(0, MAX_NAME);
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();
234
261
  }
235
262
 
236
263
  function redirectList(value: unknown): string[] {
package/src/schemas.ts CHANGED
@@ -42,27 +42,30 @@ export function tombstoneOf(slug: string, day: Date, n = 1): string {
42
42
  return n === 1 ? base : `${base}-${n}`;
43
43
  }
44
44
 
45
- /**
46
- * The slug an environment deleted with its project keeps, with 0.15's log:
47
- * `dev~deleted`, undated. Its project is deleted once, so within it no other
48
- * environment holds it, and an environment deleted alone holds a dated one.
49
- * The project's tombstone dates both; its old path still names it,
50
- * `market~deleted-2026-10-05/dev` (`resolvePath`'s `tombstones`).
51
- */
52
- export function deletedWithProject(slug: string): string {
53
- return `${slug}${TOMBSTONE}deleted`;
54
- }
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*)?$/);
55
47
  export const displayName = z.string().trim().min(1).max(120);
56
- /** 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). */
57
49
  export const folderName = z.string().min(1).max(64)
58
50
  .refine((name) => name === name.trim(), 'a folder name cannot start or end with a space')
59
- .refine((name) => !/[/\p{Cc}]/u.test(name), 'a folder name cannot hold "/" or a control character');
51
+ .refine((name) => !/[/\p{Cc}\p{Cs}]/u.test(name), 'a folder name cannot hold "/", a control character or half of a surrogate pair');
60
52
  export const secretKey = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]{0,127}$/);
61
53
  /**
62
54
  * A member as people read it, in a message or on a page: a service account
63
55
  * as `service:<name>`, though the API, the vault and the log keep the
64
56
  * `token:<name>` their signed entries hold.
65
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
+
66
69
  export function shownMember(member: string): string {
67
70
  return member.startsWith('token:') ? `service:${member.slice('token:'.length)}` : member;
68
71
  }