@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.
- package/README.md +1 -1
- package/dist/{access-CgQTlUMz.js → access-CF8UG59J.js} +70 -95
- package/dist/{access-DqLJjnLM.d.ts → access-ERdGGHG7.d.ts} +45 -64
- 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 +3 -1018
- package/dist/identity.js +885 -623
- 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 +27 -4
- package/dist/mcp.js +31 -10
- 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 +11 -9
- package/dist/schemas.js +16 -14
- package/dist/{types-Cp3lB_-W.js → types-DwTO_b4H.js} +17 -5
- package/dist/vault.d.ts +1771 -1419
- package/dist/vault.js +96 -302
- package/dist/{workloads-D049JH0M.d.ts → workloads-CW2dK4AW.d.ts} +1 -9
- package/dist/workloads.d.ts +2 -2
- package/dist/workloads.js +1 -9
- package/package.json +7 -7
- package/src/access.ts +63 -95
- 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 -2
- package/src/identity/{profile-rules.ts → profiles.ts} +1 -9
- 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/identity/workloads.ts +0 -11
- 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/{audit → log}/tiles.ts +18 -49
- package/src/{audit → log}/tree.ts +2 -2
- package/src/mcp.ts +36 -9
- package/src/schemas.ts +15 -12
- package/src/vault.ts +251 -1150
- package/dist/merkle.d.ts +0 -456
- package/dist/merkle.js +0 -964
- package/src/answers.ts +0 -209
- package/src/audit/leaf.ts +0 -81
- package/src/audit/merkle.ts +0 -13
- package/src/audit/note.ts +0 -187
- package/src/audit/pair.ts +0 -86
- package/src/audit/verify.ts +0 -393
- package/src/audit/witness.ts +0 -50
- package/src/checkpoint.ts +0 -22
- package/src/identity/run-proof.ts +0 -159
package/src/answers.ts
DELETED
|
@@ -1,209 +0,0 @@
|
|
|
1
|
-
import {
|
|
2
|
-
DEFAULT_POLICY,
|
|
3
|
-
definitionProblem,
|
|
4
|
-
EVERY_ENVIRONMENT,
|
|
5
|
-
EVERYWHERE,
|
|
6
|
-
grantKind,
|
|
7
|
-
INSTANCE_ROLES,
|
|
8
|
-
isInstanceRole,
|
|
9
|
-
isScope,
|
|
10
|
-
ROLES,
|
|
11
|
-
UNWRITTEN_FORK_MS,
|
|
12
|
-
type InstanceRole,
|
|
13
|
-
type Policy,
|
|
14
|
-
type Role,
|
|
15
|
-
type RoleDefinition,
|
|
16
|
-
type Scope,
|
|
17
|
-
} from './access.ts';
|
|
18
|
-
import { accessRevision, type Access, type Grant, type Settings } from './vault.ts';
|
|
19
|
-
|
|
20
|
-
// What the vault answers about a principal, the policy and its settings,
|
|
21
|
-
// from the rows that hold them: the vault, once it has checked each row by
|
|
22
|
-
// its MAC, and the app, which holds no key of the vault's and checks none,
|
|
23
|
-
// for what it only shows (`GET /api/me`). One rule for both, so the two
|
|
24
|
-
// answers agree whenever the rows are the vault's.
|
|
25
|
-
|
|
26
|
-
/** A member: `user:<email>` or `token:<name>`. */
|
|
27
|
-
export const PRINCIPAL = /^(user|token):[^\s:][^\s]*$/;
|
|
28
|
-
|
|
29
|
-
const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
|
|
30
|
-
|
|
31
|
-
/** A member's row, as `vault_members` holds it, its instance role and scope read (`storedRole` in @coffre/db/grants). */
|
|
32
|
-
export type MemberFacts = {
|
|
33
|
-
status: 'active' | 'removed';
|
|
34
|
-
role: InstanceRole;
|
|
35
|
-
scope: Scope;
|
|
36
|
-
generation: number;
|
|
37
|
-
/** Milliseconds since the epoch. */
|
|
38
|
-
statusChangedAt: number;
|
|
39
|
-
statusChangedBy: string;
|
|
40
|
-
};
|
|
41
|
-
|
|
42
|
-
/** A grant, as `vault_grants` holds it, its environment's project filled in; times in milliseconds since the epoch. */
|
|
43
|
-
export type GrantFacts = {
|
|
44
|
-
projectId: string | null;
|
|
45
|
-
environmentId: string | null;
|
|
46
|
-
role: string;
|
|
47
|
-
expiresAt: number | null;
|
|
48
|
-
grantedAt: number;
|
|
49
|
-
grantedBy: string;
|
|
50
|
-
};
|
|
51
|
-
|
|
52
|
-
/**
|
|
53
|
-
* What `access` answers about `principal`, from their row and their
|
|
54
|
-
* grants, lapsed ones too, as of `at`; `tampered` when a row failed the
|
|
55
|
-
* vault's check, which only the vault can tell.
|
|
56
|
-
*/
|
|
57
|
-
export function answerFrom(principal: string, row: MemberFacts | undefined, held: readonly GrantFacts[], at: number, tampered: boolean, policy: Policy): Access {
|
|
58
|
-
const active = PRINCIPAL.test(principal) && !tampered && row?.status === 'active';
|
|
59
|
-
const access: Access = {
|
|
60
|
-
principal,
|
|
61
|
-
status: tampered ? 'tampered' : !PRINCIPAL.test(principal) ? 'unknown' : (row?.status ?? 'unknown'),
|
|
62
|
-
generation: row?.generation ?? 0,
|
|
63
|
-
...(active ? roleOf(principal, row) : { role: 'member', scope: EVERYWHERE }),
|
|
64
|
-
grants: active ? held.filter((grant) => live(grant, at) && grantKind(grant) !== null).map(view) : [],
|
|
65
|
-
since: row ? iso(row.statusChangedAt) : null,
|
|
66
|
-
by: row?.statusChangedBy ?? null,
|
|
67
|
-
policy,
|
|
68
|
-
};
|
|
69
|
-
return { ...access, revision: accessRevision(access) };
|
|
70
|
-
}
|
|
71
|
-
|
|
72
|
-
/** A member's instance role, as their row has it: service accounts are members, whatever a row says. */
|
|
73
|
-
export function roleOf(principal: string, row: Pick<MemberFacts, 'role' | 'scope'>): { role: InstanceRole; scope: Scope } {
|
|
74
|
-
return principal.startsWith('user:') ? { role: row.role, scope: row.scope } : { role: 'member', scope: EVERYWHERE };
|
|
75
|
-
}
|
|
76
|
-
|
|
77
|
-
/** Whether a grant still holds at `at`. */
|
|
78
|
-
export function live(grant: { expiresAt: number | null }, at: number): boolean {
|
|
79
|
-
return grant.expiresAt === null || grant.expiresAt > at;
|
|
80
|
-
}
|
|
81
|
-
|
|
82
|
-
/** A grant as `access` answers it. */
|
|
83
|
-
export function view(grant: GrantFacts): Grant {
|
|
84
|
-
return {
|
|
85
|
-
projectId: grant.projectId,
|
|
86
|
-
environmentId: grant.environmentId,
|
|
87
|
-
role: grant.role as Role,
|
|
88
|
-
expiresAt: grant.expiresAt === null ? null : iso(grant.expiresAt),
|
|
89
|
-
grantedAt: iso(grant.grantedAt),
|
|
90
|
-
grantedBy: grant.grantedBy,
|
|
91
|
-
};
|
|
92
|
-
}
|
|
93
|
-
|
|
94
|
-
function iso(ms: number): string {
|
|
95
|
-
return new Date(ms).toISOString();
|
|
96
|
-
}
|
|
97
|
-
|
|
98
|
-
// --- the policy -------------------------------------------------------------------
|
|
99
|
-
|
|
100
|
-
/**
|
|
101
|
-
* What a `policy.change` entry keeps: the roles an Owner edited or made,
|
|
102
|
-
* each whole, and the protected environments. A role as it ships is kept by
|
|
103
|
-
* none, so a release that changes a default changes it where nobody edited it.
|
|
104
|
-
*/
|
|
105
|
-
export type PolicyEdits = { roles: Record<string, RoleDefinition>; instanceRoles: Partial<Record<InstanceRole, RoleDefinition>>; protected: ProtectedPlace[] };
|
|
106
|
-
|
|
107
|
-
/**
|
|
108
|
-
* A protected environment, with its project's id, what a grant on the whole
|
|
109
|
-
* project reaches of it, and when it was protected, by the vault's clock:
|
|
110
|
-
* an id with no row ten minutes later is a fork that was never written.
|
|
111
|
-
*/
|
|
112
|
-
export type ProtectedPlace = { projectId: string; environmentId: string; at: number };
|
|
113
|
-
|
|
114
|
-
export const NO_EDITS: PolicyEdits = { roles: {}, instanceRoles: {}, protected: [] };
|
|
115
|
-
|
|
116
|
-
/** A role holding nothing, which every role but Owner is under the closed policy. */
|
|
117
|
-
const NOTHING_HELD = (definition: RoleDefinition): RoleDefinition => ({ ...definition, permissions: [], protected: [] });
|
|
118
|
-
|
|
119
|
-
/**
|
|
120
|
-
* The policy when the log has some, but none the vault wrote within reach:
|
|
121
|
-
* whoever inserted rows may have hidden an Owner's narrowing, so no role
|
|
122
|
-
* holds anything, a service account's neither, but Owner, which holds
|
|
123
|
-
* everything always and so may write the policy again.
|
|
124
|
-
*/
|
|
125
|
-
export const CLOSED_POLICY: Policy = {
|
|
126
|
-
roles: Object.fromEntries(Object.entries(ROLES).map(([id, definition]) => [id, id === 'owner' ? definition : NOTHING_HELD(definition)])),
|
|
127
|
-
instanceRoles: Object.fromEntries(Object.entries(INSTANCE_ROLES).map(([id, definition]) => [id, id === 'owner' ? definition : NOTHING_HELD(definition)])) as Policy['instanceRoles'],
|
|
128
|
-
protected: [EVERY_ENVIRONMENT],
|
|
129
|
-
protectedIn: {},
|
|
130
|
-
};
|
|
131
|
-
|
|
132
|
-
/** An environment a policy names, as the policy reads it. */
|
|
133
|
-
export type PolicyEnvironment = { slug: string | null; deleted: boolean };
|
|
134
|
-
|
|
135
|
-
/**
|
|
136
|
-
* The policy the newest `policy.change` says, from its metadata, as of
|
|
137
|
-
* `at`, with the rows of the environments it protects: none for no entry,
|
|
138
|
-
* the roles as they ship; and closed for one whose edits do not hold.
|
|
139
|
-
*/
|
|
140
|
-
export function policyFrom(metadata: string | null, rows: ReadonlyMap<string, PolicyEnvironment>, at: number): { policy: Policy; edits: PolicyEdits; readable: boolean } {
|
|
141
|
-
if (metadata === null) return { policy: DEFAULT_POLICY, edits: NO_EDITS, readable: true };
|
|
142
|
-
let stored: unknown;
|
|
143
|
-
try {
|
|
144
|
-
stored = JSON.parse(metadata);
|
|
145
|
-
} catch {}
|
|
146
|
-
const edits = typeof stored === 'object' && stored !== null ? readEdits(stored as { policy?: unknown }) : null;
|
|
147
|
-
if (edits === null) return { policy: CLOSED_POLICY, edits: NO_EDITS, readable: false };
|
|
148
|
-
return { policy: livePolicy(rows, edits, at), edits, readable: true };
|
|
149
|
-
}
|
|
150
|
-
|
|
151
|
-
/** A policy entry's edits, checked as the vault wrote them, or null for any that does not hold. */
|
|
152
|
-
export function readEdits(stored: { policy?: unknown }): PolicyEdits | null {
|
|
153
|
-
const edits = stored.policy as Partial<PolicyEdits> | undefined;
|
|
154
|
-
if (typeof edits !== 'object' || edits === null) return null;
|
|
155
|
-
const { roles, instanceRoles, protected: protectedIds } = edits;
|
|
156
|
-
if (typeof roles !== 'object' || roles === null || typeof instanceRoles !== 'object' || instanceRoles === null || !Array.isArray(protectedIds)) return null;
|
|
157
|
-
const defined = (table: object) => Object.values(table).every((definition) => definitionProblem(definition as RoleDefinition) === null);
|
|
158
|
-
if (!defined(roles) || !defined(instanceRoles) || Object.keys(instanceRoles).some((role) => !isInstanceRole(role))) return null;
|
|
159
|
-
if (protectedIds.some((place) => typeof place !== 'object' || place === null || !UUID.test((place as ProtectedPlace).projectId) || !UUID.test((place as ProtectedPlace).environmentId)
|
|
160
|
-
|| !Number.isSafeInteger((place as ProtectedPlace).at))) return null;
|
|
161
|
-
return { roles: roles as Record<string, RoleDefinition>, instanceRoles: instanceRoles as PolicyEdits['instanceRoles'], protected: protectedIds as ProtectedPlace[] };
|
|
162
|
-
}
|
|
163
|
-
|
|
164
|
-
/**
|
|
165
|
-
* The policy `edits` say as of `at`: the roles as they ship, each edited
|
|
166
|
-
* one replaced and each made one added; and the protected environments, but
|
|
167
|
-
* for those deleted since, the project around one's included: a deleted
|
|
168
|
-
* prod protects nothing, and holds nobody back from giving a service
|
|
169
|
-
* account a role on all of its project (`givesService`). A fork's id with
|
|
170
|
-
* no row yet stays, protected before it is written, ten minutes: one with
|
|
171
|
-
* none after that is a fork refused or abandoned, never written. Each
|
|
172
|
-
* keeps its slug, which a scoped instance role's filters read. The edits
|
|
173
|
-
* keep them all: no write is needed.
|
|
174
|
-
*/
|
|
175
|
-
export function livePolicy(rows: ReadonlyMap<string, PolicyEnvironment>, edits: PolicyEdits, at: number): Policy {
|
|
176
|
-
const live = edits.protected.filter((place) => {
|
|
177
|
-
const row = rows.get(place.environmentId);
|
|
178
|
-
return row === undefined ? at - place.at < UNWRITTEN_FORK_MS : !row.deleted;
|
|
179
|
-
});
|
|
180
|
-
const slugOf = (place: ProtectedPlace) => rows.get(place.environmentId)?.slug ?? null;
|
|
181
|
-
return {
|
|
182
|
-
roles: { ...ROLES, ...edits.roles },
|
|
183
|
-
instanceRoles: { ...INSTANCE_ROLES, ...edits.instanceRoles },
|
|
184
|
-
protected: live.map((place) => place.environmentId),
|
|
185
|
-
protectedIn: live.reduce<Record<string, { environmentId: string; slug: string | null }[]>>(
|
|
186
|
-
(byProject, place) => ({ ...byProject, [place.projectId]: [...(byProject[place.projectId] ?? []), { environmentId: place.environmentId, slug: slugOf(place) }] }),
|
|
187
|
-
{},
|
|
188
|
-
),
|
|
189
|
-
};
|
|
190
|
-
}
|
|
191
|
-
|
|
192
|
-
// --- the settings -----------------------------------------------------------------
|
|
193
|
-
|
|
194
|
-
/** The settings before anyone changed them: people set up service accounts anywhere they hold access. */
|
|
195
|
-
export const DEFAULT_SETTINGS: Settings = { serviceAccounts: EVERYWHERE };
|
|
196
|
-
|
|
197
|
-
/** The settings when the log has some, but none the vault wrote within reach: people set up no service accounts. */
|
|
198
|
-
export const CLOSED_SETTINGS: Settings = { serviceAccounts: { projects: { only: [] }, environments: 'all' } };
|
|
199
|
-
|
|
200
|
-
/** The settings the newest `settings.change` says, from its metadata: none for no entry, the default; closed for one that does not hold. */
|
|
201
|
-
export function settingsFrom(metadata: string | null): Settings {
|
|
202
|
-
if (metadata === null) return DEFAULT_SETTINGS;
|
|
203
|
-
let stored: unknown;
|
|
204
|
-
try {
|
|
205
|
-
stored = JSON.parse(metadata);
|
|
206
|
-
} catch {}
|
|
207
|
-
const serviceAccounts = typeof stored === 'object' && stored !== null ? (stored as { serviceAccounts?: unknown }).serviceAccounts : undefined;
|
|
208
|
-
return isScope(serviceAccounts) ? { serviceAccounts } : CLOSED_SETTINGS;
|
|
209
|
-
}
|
package/src/audit/leaf.ts
DELETED
|
@@ -1,81 +0,0 @@
|
|
|
1
|
-
import type { TreeName } from './pair.ts';
|
|
2
|
-
import { MAX_NUMBER } from './note.ts';
|
|
3
|
-
import { leafHash, type Hash } from './tree.ts';
|
|
4
|
-
|
|
5
|
-
/**
|
|
6
|
-
* A leaf is a whole entry: its tree, its number, then every column of its row
|
|
7
|
-
* in the table's order, its MAC included. The number is sealed with the
|
|
8
|
-
* entry, so a sealed entry cannot be renumbered, and the tree is too, so an
|
|
9
|
-
* entry moved from one tree to the other is no longer its leaf. Anyone who
|
|
10
|
-
* holds the public keys can check rows against the trees; the MAC key matters
|
|
11
|
-
* only until an entry is sealed.
|
|
12
|
-
*
|
|
13
|
-
* "coffre.audit.leaf.v1" 0x0a tree 0x0a number(8 bytes, big-endian) count(4)
|
|
14
|
-
* then per column: tag(1) length(4) bytes
|
|
15
|
-
* tag 0 null (length 0), 1 bytes, 2 text (UTF-8), 3 integer (decimal text)
|
|
16
|
-
*
|
|
17
|
-
* Every column is tagged and length-prefixed, so the encoding is injective:
|
|
18
|
-
* no two rows share their bytes, whatever their values. A change to it is a
|
|
19
|
-
* new format, never an edit of this one (test/vectors/audit-tree.json pins it).
|
|
20
|
-
*/
|
|
21
|
-
export const LEAF_FORMAT = 'coffre.audit.leaf.v1';
|
|
22
|
-
|
|
23
|
-
export type LeafValue = Uint8Array | string | bigint | number | null;
|
|
24
|
-
|
|
25
|
-
export function leafData(tree: TreeName, number: bigint, columns: readonly LeafValue[]): Buffer {
|
|
26
|
-
if (number < 0n || number > MAX_NUMBER) throw new Error(`entry number ${number} is out of range`);
|
|
27
|
-
return encode(`${LEAF_FORMAT}\n${tree}\n`, number, columns);
|
|
28
|
-
}
|
|
29
|
-
|
|
30
|
-
/**
|
|
31
|
-
* What an entry's MAC covers: its tree and every column but its number,
|
|
32
|
-
* which the database takes, and the MAC itself, the same tagged encoding as
|
|
33
|
-
* a leaf's. The tree is in it (Seal.tla's KindInMac): a change moved into
|
|
34
|
-
* the uses table before its tick would otherwise be sealed into the uses
|
|
35
|
-
* tree, and pruned with the uses.
|
|
36
|
-
*
|
|
37
|
-
* "coffre.log.mac.v1" 0x0a tree 0x0a column count(4), then the columns as a leaf's
|
|
38
|
-
*/
|
|
39
|
-
export const MAC_FORMAT = 'coffre.log.mac.v1';
|
|
40
|
-
|
|
41
|
-
export function macData(tree: TreeName, columns: readonly LeafValue[]): Buffer {
|
|
42
|
-
return encode(`${MAC_FORMAT}\n${tree}\n`, null, columns);
|
|
43
|
-
}
|
|
44
|
-
|
|
45
|
-
/**
|
|
46
|
-
* The prefix, the number if any (8 bytes), the column count, then each
|
|
47
|
-
* column tagged and length-prefixed: sized first, then written into one
|
|
48
|
-
* buffer, which a walk does for every entry it checks.
|
|
49
|
-
*/
|
|
50
|
-
function encode(prefix: string, number: bigint | null, columns: readonly LeafValue[]): Buffer {
|
|
51
|
-
const tags: number[] = [];
|
|
52
|
-
const values: (Uint8Array | string | null)[] = [];
|
|
53
|
-
let size = Buffer.byteLength(prefix, 'utf8') + (number === null ? 0 : 8) + 4;
|
|
54
|
-
for (const [i, value] of columns.entries()) {
|
|
55
|
-
let tag: number;
|
|
56
|
-
let bytes: Uint8Array | string | null;
|
|
57
|
-
if (value === null) [tag, bytes] = [0, null];
|
|
58
|
-
else if (value instanceof Uint8Array) [tag, bytes] = [1, value];
|
|
59
|
-
else if (typeof value === 'string') {
|
|
60
|
-
if (/[\uD800-\uDFFF]/u.test(value)) throw new Error(`column ${i} is not well-formed Unicode`);
|
|
61
|
-
[tag, bytes] = [2, value];
|
|
62
|
-
} else if (typeof value === 'bigint' || Number.isSafeInteger(value)) [tag, bytes] = [3, value.toString(10)];
|
|
63
|
-
else throw new Error(`column ${i} is not a whole number`);
|
|
64
|
-
tags.push(tag);
|
|
65
|
-
values.push(bytes);
|
|
66
|
-
size += 5 + (bytes === null ? 0 : typeof bytes === 'string' ? Buffer.byteLength(bytes, 'utf8') : bytes.length);
|
|
67
|
-
}
|
|
68
|
-
const out = Buffer.allocUnsafe(size);
|
|
69
|
-
let at = out.write(prefix, 0, 'utf8');
|
|
70
|
-
if (number !== null) at = out.writeBigUInt64BE(number, at);
|
|
71
|
-
at = out.writeUInt32BE(columns.length, at);
|
|
72
|
-
for (const [i, bytes] of values.entries()) {
|
|
73
|
-
at = out.writeUInt8(tags[i]!, at);
|
|
74
|
-
const length = bytes === null ? 0 : typeof bytes === 'string' ? out.write(bytes, at + 4, 'utf8') : (out.set(bytes, at + 4), bytes.length);
|
|
75
|
-
at = out.writeUInt32BE(length, at) + length;
|
|
76
|
-
}
|
|
77
|
-
return out;
|
|
78
|
-
}
|
|
79
|
-
|
|
80
|
-
/** The leaf hash of an entry. */
|
|
81
|
-
export const entryLeaf = (tree: TreeName, number: bigint, columns: readonly LeafValue[]): Hash => leafHash(leafData(tree, number, columns));
|
package/src/audit/merkle.ts
DELETED
|
@@ -1,13 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* 0.15's audit trees (docs/design/audit-tree.md): RFC 9162 trees stored as
|
|
3
|
-
* C2SP tiles, signed as C2SP checkpoints, two of them moving as one pair, the
|
|
4
|
-
* leaf every entry becomes, a witness's rule, and the verifier's walk. Pure
|
|
5
|
-
* code: the vault's checkpointer and the database wire it.
|
|
6
|
-
*/
|
|
7
|
-
export * from './leaf.ts';
|
|
8
|
-
export * from './note.ts';
|
|
9
|
-
export * from './pair.ts';
|
|
10
|
-
export * from './tiles.ts';
|
|
11
|
-
export * from './tree.ts';
|
|
12
|
-
export * from './verify.ts';
|
|
13
|
-
export * from './witness.ts';
|
package/src/audit/note.ts
DELETED
|
@@ -1,187 +0,0 @@
|
|
|
1
|
-
import { createHash } from 'node:crypto';
|
|
2
|
-
|
|
3
|
-
import { HASH_SIZE, type Hash } from './tree.ts';
|
|
4
|
-
|
|
5
|
-
/**
|
|
6
|
-
* Signed checkpoints in the C2SP formats the transparency ecosystem shares
|
|
7
|
-
* (tlog-checkpoint inside a signed note), so a Go sumdb client, a
|
|
8
|
-
* transparency-dev witness or Sigstore's tooling reads them as they are:
|
|
9
|
-
*
|
|
10
|
-
* coffre.example/audit/uses origin: which log
|
|
11
|
-
* 1048576 tree size
|
|
12
|
-
* 4Ht6…= tree head, base64
|
|
13
|
-
* upto 2026102600000001048599 extension: every number at or below it is final
|
|
14
|
-
* at 1793048700000 extension: when it was signed, ms since the epoch
|
|
15
|
-
* floor 1793048697000 extension: the floor of `at` its barrier set
|
|
16
|
-
* prev 1793048696500 extension: the floor of the pair signed before it
|
|
17
|
-
*
|
|
18
|
-
* — coffre.example/audit/uses Az3g… key ID (4 bytes) and Ed25519 signature, base64
|
|
19
|
-
*
|
|
20
|
-
* `upto` is what turns a gap in the numbers from "maybe deleted" into "never
|
|
21
|
-
* was": every number at or below it is in the tree or will never appear.
|
|
22
|
-
* `floor` is the lowest `at` a use may still be written with once its barrier
|
|
23
|
-
* ran: the database's row of it is unsigned, so the signer holds it here and
|
|
24
|
-
* the next barrier must find it no lower (HotPathOne.tla's BarrierChecksFloor).
|
|
25
|
-
* `prev` is the floor of the pair the signer signed just before, so that a pair
|
|
26
|
-
* is provably the first past a time from its own note: its floor at or past
|
|
27
|
-
* it, its `prev` below. Retention cuts a day there (Seal.tla's CutFirst); a
|
|
28
|
-
* writer who deletes rows cannot make a later pair pass for it.
|
|
29
|
-
* Ed25519 through WebCrypto, which Node and Workers both have.
|
|
30
|
-
*/
|
|
31
|
-
export type Checkpoint = { origin: string; size: number; root: Hash; upto: bigint; at: number; floor: number; prev: number };
|
|
32
|
-
|
|
33
|
-
/** The largest number a log entry may carry: Postgres's bigint. */
|
|
34
|
-
export const MAX_NUMBER = 2n ** 63n - 1n;
|
|
35
|
-
|
|
36
|
-
export function checkpointBody(c: Checkpoint): string {
|
|
37
|
-
return `${c.origin}\n${c.size}\n${c.root.toString('base64')}\nupto ${c.upto}\nat ${c.at}\nfloor ${c.floor}\nprev ${c.prev}\n`;
|
|
38
|
-
}
|
|
39
|
-
|
|
40
|
-
/** The checkpoint a note's text holds; throws on anything else, byte for byte, since the database is a writer's to shape. */
|
|
41
|
-
export function parseCheckpoint(text: string): Checkpoint {
|
|
42
|
-
const lines = text.split('\n');
|
|
43
|
-
const [origin, size, root, upto, at, floor, prev, end] = lines;
|
|
44
|
-
const hash = Buffer.from(root ?? '', 'base64');
|
|
45
|
-
const ok = lines.length === 8 && end === '' && origin !== undefined && /^[^\s+]+$/.test(origin)
|
|
46
|
-
&& /^(0|[1-9]\d{0,15})$/.test(size ?? '') && hash.length === HASH_SIZE && hash.toString('base64') === root
|
|
47
|
-
&& /^upto (0|[1-9]\d{0,18})$/.test(upto ?? '') && /^at (0|[1-9]\d{0,15})$/.test(at ?? '') && /^floor (0|[1-9]\d{0,15})$/.test(floor ?? '')
|
|
48
|
-
&& /^prev (0|[1-9]\d{0,15})$/.test(prev ?? '');
|
|
49
|
-
// Sizes and times are exact numbers up to 2^53, as the tree's arithmetic; numbers are Postgres bigints.
|
|
50
|
-
const [n, t, f, b] = [Number(size), Number(at?.slice(3)), Number(floor?.slice(6)), Number(prev?.slice(5))];
|
|
51
|
-
if (!ok || BigInt(upto!.slice(5)) > MAX_NUMBER || ![n, t, f, b].every(Number.isSafeInteger)) throw new Error('not a checkpoint');
|
|
52
|
-
return { origin: origin!, size: n, root: hash, upto: BigInt(upto!.slice(5)), at: t, floor: f, prev: b };
|
|
53
|
-
}
|
|
54
|
-
|
|
55
|
-
const ED25519 = 1;
|
|
56
|
-
const PKCS8_ED25519 = Buffer.from('302e020100300506032b657004220420', 'hex');
|
|
57
|
-
|
|
58
|
-
/** A note key's ID: the first 4 bytes of SHA-256(name || "\n" || 0x01 || public key). */
|
|
59
|
-
function keyId(name: string, publicKey: Buffer): Buffer {
|
|
60
|
-
return createHash('sha256').update(name).update('\n').update(Buffer.from([ED25519])).update(publicKey).digest().subarray(0, 4);
|
|
61
|
-
}
|
|
62
|
-
|
|
63
|
-
export type NoteSigner = {
|
|
64
|
-
name: string;
|
|
65
|
-
id: Buffer;
|
|
66
|
-
publicKey: Buffer;
|
|
67
|
-
/** Go's note verifier key: `<name>+<key ID, hex>+<base64(0x01 || public key)>`. */
|
|
68
|
-
verifierKey: string;
|
|
69
|
-
sign(message: Uint8Array): Promise<Buffer>;
|
|
70
|
-
};
|
|
71
|
-
|
|
72
|
-
export type NoteVerifier = { name: string; id: Buffer; verify(message: Uint8Array, signature: Uint8Array): Promise<boolean> };
|
|
73
|
-
|
|
74
|
-
/** A signer named `name`, from a 32-byte Ed25519 seed. */
|
|
75
|
-
export async function noteSigner(name: string, seed: Uint8Array): Promise<NoteSigner> {
|
|
76
|
-
if (seed.length !== 32) throw new Error('an Ed25519 seed is 32 bytes');
|
|
77
|
-
if (!/^[^\s+]+$/.test(name)) throw new Error('a note key name has no spaces and no +');
|
|
78
|
-
const key = await crypto.subtle.importKey('pkcs8', new Uint8Array(Buffer.concat([PKCS8_ED25519, seed])), { name: 'Ed25519' }, true, ['sign']);
|
|
79
|
-
// A private JWK carries its public half, `x`; the raw private key does not export it.
|
|
80
|
-
const { x } = (await crypto.subtle.exportKey('jwk', key)) as JsonWebKey;
|
|
81
|
-
const publicKey = Buffer.from(x!, 'base64url');
|
|
82
|
-
const id = keyId(name, publicKey);
|
|
83
|
-
return {
|
|
84
|
-
name,
|
|
85
|
-
id,
|
|
86
|
-
publicKey,
|
|
87
|
-
verifierKey: `${name}+${id.toString('hex')}+${Buffer.concat([Buffer.from([ED25519]), publicKey]).toString('base64')}`,
|
|
88
|
-
sign: async (message) => Buffer.from(await crypto.subtle.sign('Ed25519', key, new Uint8Array(message))),
|
|
89
|
-
};
|
|
90
|
-
}
|
|
91
|
-
|
|
92
|
-
export async function noteVerifier(verifierKey: string): Promise<NoteVerifier> {
|
|
93
|
-
// name+hash+data; the base64 data may itself hold '+'.
|
|
94
|
-
const m = /^([^\s+]+)\+([0-9a-f]{8})\+(.+)$/.exec(verifierKey);
|
|
95
|
-
if (m === null) throw new Error('not a note verifier key');
|
|
96
|
-
const [, name, hash, data] = m as unknown as [string, string, string, string];
|
|
97
|
-
const raw = Buffer.from(data, 'base64');
|
|
98
|
-
if (raw[0] !== ED25519 || raw.length !== 33) throw new Error('not an Ed25519 note key');
|
|
99
|
-
const publicKey = raw.subarray(1);
|
|
100
|
-
const id = keyId(name, publicKey);
|
|
101
|
-
if (id.toString('hex') !== hash) throw new Error('the key ID does not match the key');
|
|
102
|
-
const key = await crypto.subtle.importKey('raw', new Uint8Array(publicKey), { name: 'Ed25519' }, false, ['verify']);
|
|
103
|
-
return { name, id, verify: (message, signature) => crypto.subtle.verify('Ed25519', key, new Uint8Array(signature), new Uint8Array(message)) };
|
|
104
|
-
}
|
|
105
|
-
|
|
106
|
-
async function signatureLine(text: string, signer: NoteSigner): Promise<string> {
|
|
107
|
-
return `— ${signer.name} ${Buffer.concat([signer.id, await signer.sign(Buffer.from(text))]).toString('base64')}\n`;
|
|
108
|
-
}
|
|
109
|
-
|
|
110
|
-
/** A signed note: the text, a blank line, then one signature line per signer. */
|
|
111
|
-
export async function signNote(text: string, signers: readonly NoteSigner[]): Promise<string> {
|
|
112
|
-
if (!text.endsWith('\n') || text.includes('\n\n')) throw new Error('a note text ends with a newline and has no blank line');
|
|
113
|
-
return `${text}\n${(await Promise.all(signers.map((s) => signatureLine(text, s)))).join('')}`;
|
|
114
|
-
}
|
|
115
|
-
|
|
116
|
-
/** Adds a signature (a witness's cosignature) to a signed note. */
|
|
117
|
-
export async function cosignNote(note: string, signer: NoteSigner): Promise<string> {
|
|
118
|
-
return `${note}${await signatureLine(splitNote(note).text, signer)}`;
|
|
119
|
-
}
|
|
120
|
-
|
|
121
|
-
/** At most this many signature lines, as Go's note.Open: a crafted row cannot make a reader verify without end. */
|
|
122
|
-
const MAX_SIGNATURES = 100;
|
|
123
|
-
|
|
124
|
-
/** A key name, as Go's: not empty, no white space, no '+'. */
|
|
125
|
-
const validName = (name: string) => name.length > 0 && !/[\s\u0085+]/u.test(name) && !/[\uD800-\uDFFF]/u.test(name);
|
|
126
|
-
|
|
127
|
-
/**
|
|
128
|
-
* A signed note's text and signature lines, read as strictly as Go's
|
|
129
|
-
* note.Open, so that a note stored in the database opens here only if every
|
|
130
|
-
* Go reader and C2SP witness would open it too. Throws on anything else.
|
|
131
|
-
*/
|
|
132
|
-
export function splitNote(note: string): { text: string; signatures: { name: string; id: Buffer; signature: Buffer }[] } {
|
|
133
|
-
// Well-formed Unicode, and no ASCII control character but the newline.
|
|
134
|
-
if (/[\u0000-\u0009\u000b-\u001f]/.test(note) || /[\uD800-\uDFFF]/u.test(note)) throw new Error('not a signed note');
|
|
135
|
-
const at = note.lastIndexOf('\n\n');
|
|
136
|
-
if (at < 0 || note.length === at + 2 || !note.endsWith('\n')) throw new Error('not a signed note');
|
|
137
|
-
const text = note.slice(0, at + 1);
|
|
138
|
-
const lines = note.slice(at + 2, -1).split('\n');
|
|
139
|
-
if (lines.length > MAX_SIGNATURES) throw new Error('too many signature lines');
|
|
140
|
-
const signatures = lines.map((line) => {
|
|
141
|
-
if (!line.startsWith('— ')) throw new Error('malformed signature line');
|
|
142
|
-
const rest = line.slice(2);
|
|
143
|
-
const space = rest.indexOf(' ');
|
|
144
|
-
const [name, encoded] = space < 0 ? [rest, ''] : [rest.slice(0, space), rest.slice(space + 1)];
|
|
145
|
-
// Canonical base64 only: what decodes here decodes to the same bytes in Go's StdEncoding.
|
|
146
|
-
const raw = Buffer.from(encoded, 'base64');
|
|
147
|
-
if (!validName(name) || encoded === '' || raw.toString('base64') !== encoded || raw.length < 5) throw new Error('malformed signature line');
|
|
148
|
-
return { name, id: raw.subarray(0, 4), signature: raw.subarray(4) };
|
|
149
|
-
});
|
|
150
|
-
return { text, signatures };
|
|
151
|
-
}
|
|
152
|
-
|
|
153
|
-
/**
|
|
154
|
-
* The note's text if `verifier` signed it, else null; null for anything that
|
|
155
|
-
* is not a signed note too. As Go's note.Open given this one key, the first
|
|
156
|
-
* signature line that names this key decides: if it does not verify, the
|
|
157
|
-
* whole note is invalid, whatever other lines say; later lines by the key are
|
|
158
|
-
* ignored. (Given several keys, Go also refuses a bad line
|
|
159
|
-
* by any of them; each tree's note is opened with its own key alone.)
|
|
160
|
-
*/
|
|
161
|
-
export async function openNote(note: string, verifier: NoteVerifier): Promise<string | null> {
|
|
162
|
-
let parts: ReturnType<typeof splitNote>;
|
|
163
|
-
try {
|
|
164
|
-
parts = splitNote(note);
|
|
165
|
-
} catch {
|
|
166
|
-
return null;
|
|
167
|
-
}
|
|
168
|
-
let verified = false;
|
|
169
|
-
for (const s of parts.signatures) {
|
|
170
|
-
if (s.name !== verifier.name || !s.id.equals(verifier.id) || verified) continue;
|
|
171
|
-
if (s.signature.length !== 64 || !(await verifier.verify(Buffer.from(parts.text), s.signature))) return null;
|
|
172
|
-
verified = true;
|
|
173
|
-
}
|
|
174
|
-
return verified ? parts.text : null;
|
|
175
|
-
}
|
|
176
|
-
|
|
177
|
-
/** A checkpoint if `verifier` signed it and it names that key's log as its origin, else null. */
|
|
178
|
-
export async function openCheckpoint(note: string, verifier: NoteVerifier): Promise<Checkpoint | null> {
|
|
179
|
-
const text = await openNote(note, verifier);
|
|
180
|
-
if (text === null) return null;
|
|
181
|
-
try {
|
|
182
|
-
const c = parseCheckpoint(text);
|
|
183
|
-
return c.origin === verifier.name ? c : null;
|
|
184
|
-
} catch {
|
|
185
|
-
return null;
|
|
186
|
-
}
|
|
187
|
-
}
|
package/src/audit/pair.ts
DELETED
|
@@ -1,86 +0,0 @@
|
|
|
1
|
-
import { hkdfSync } from 'node:crypto';
|
|
2
|
-
|
|
3
|
-
import { checkpointBody, noteSigner, noteVerifier, openCheckpoint, signNote, type Checkpoint, type NoteSigner, type NoteVerifier } from './note.ts';
|
|
4
|
-
import type { Hash } from './tree.ts';
|
|
5
|
-
|
|
6
|
-
/**
|
|
7
|
-
* 0.15's log is two growing trees, one per retention class (W212, by numbers):
|
|
8
|
-
* `changes`, kept for good, and `uses`, dropped by day. Each is a standard log
|
|
9
|
-
* with its own origin and key, so any C2SP witness or Go's tlog reads either
|
|
10
|
-
* one alone. They stay one log by moving as one pair:
|
|
11
|
-
*
|
|
12
|
-
* - one tick signs both, with the same `upto`, `at` and `floor`;
|
|
13
|
-
* - the signer remembers both in one record, before the database has either;
|
|
14
|
-
* - one statement writes both;
|
|
15
|
-
* - opening, each tick and witnesses check both, as one value.
|
|
16
|
-
*
|
|
17
|
-
* So no state anywhere holds one head without the other, and a fork of either
|
|
18
|
-
* tree is a fork of the pair.
|
|
19
|
-
*/
|
|
20
|
-
export const TREES = ['changes', 'uses'] as const;
|
|
21
|
-
export type TreeName = (typeof TREES)[number];
|
|
22
|
-
|
|
23
|
-
export type Pair = { upto: bigint; at: number; floor: number; prev: number; changes: Checkpoint; uses: Checkpoint };
|
|
24
|
-
|
|
25
|
-
/** The pair as it is stored, remembered and published: each tree's signed note. */
|
|
26
|
-
export type PairNotes = { changes: string; uses: string };
|
|
27
|
-
|
|
28
|
-
export type PairSigners = Record<TreeName, NoteSigner>;
|
|
29
|
-
export type PairVerifiers = Record<TreeName, NoteVerifier>;
|
|
30
|
-
|
|
31
|
-
/** A tree's origin: the log's own, then the tree's name. */
|
|
32
|
-
export const treeOrigin = (origin: string, tree: TreeName) => `${origin}/${tree}`;
|
|
33
|
-
|
|
34
|
-
/** The two trees' keys, derived from one 32-byte signing seed, each under its own origin. */
|
|
35
|
-
export async function pairSigners(origin: string, seed: Uint8Array): Promise<PairSigners> {
|
|
36
|
-
if (seed.length < 32) throw new Error('a signing seed is at least 32 bytes');
|
|
37
|
-
const derive = (tree: TreeName) => new Uint8Array(hkdfSync('sha256', seed, new Uint8Array(0), `coffre.audit.tree.v1.${tree}`, 32));
|
|
38
|
-
const [changes, uses] = await Promise.all(TREES.map((tree) => noteSigner(treeOrigin(origin, tree), derive(tree))));
|
|
39
|
-
return { changes: changes!, uses: uses! };
|
|
40
|
-
}
|
|
41
|
-
|
|
42
|
-
export async function pairVerifiers(keys: Record<TreeName, string>): Promise<PairVerifiers> {
|
|
43
|
-
const [changes, uses] = await Promise.all(TREES.map((tree) => noteVerifier(keys[tree])));
|
|
44
|
-
return { changes: changes!, uses: uses! };
|
|
45
|
-
}
|
|
46
|
-
|
|
47
|
-
export type Heads = Record<TreeName, { size: number; root: Hash }>;
|
|
48
|
-
|
|
49
|
-
/**
|
|
50
|
-
* One tick's signatures: both heads, at one `upto`, `at`, `floor` (the floor of `at` its barrier set; 0 at genesis) and
|
|
51
|
-
* `prev` (the floor of the pair signed before it; 0 at genesis).
|
|
52
|
-
*/
|
|
53
|
-
export async function signPair(signers: PairSigners, upto: bigint, at: number, heads: Heads, floor = 0, prev = 0): Promise<{ pair: Pair; notes: PairNotes }> {
|
|
54
|
-
const checkpoint = (tree: TreeName): Checkpoint => ({ origin: signers[tree].name, size: heads[tree].size, root: heads[tree].root, upto, at, floor, prev });
|
|
55
|
-
const pair: Pair = { upto, at, floor, prev, changes: checkpoint('changes'), uses: checkpoint('uses') };
|
|
56
|
-
const [changes, uses] = await Promise.all(TREES.map((tree) => signNote(checkpointBody(pair[tree]), [signers[tree]])));
|
|
57
|
-
return { pair, notes: { changes: changes!, uses: uses! } };
|
|
58
|
-
}
|
|
59
|
-
|
|
60
|
-
/** The pair two notes make, if each is signed by its tree's key and both name the same `upto`, `at`, `floor` and `prev`; else null. */
|
|
61
|
-
export async function openPair(notes: PairNotes, verifiers: PairVerifiers): Promise<Pair | null> {
|
|
62
|
-
const [changes, uses] = await Promise.all(TREES.map((tree) => openCheckpoint(notes[tree], verifiers[tree])));
|
|
63
|
-
if (!changes || !uses || changes.upto !== uses.upto || changes.at !== uses.at || changes.floor !== uses.floor || changes.prev !== uses.prev) return null;
|
|
64
|
-
return { upto: changes.upto, at: changes.at, floor: changes.floor, prev: changes.prev, changes, uses };
|
|
65
|
-
}
|
|
66
|
-
|
|
67
|
-
/** Whether two pairs are the same heads: same place, same sizes and roots in both trees. Not `at`: callers that need one signing compare it too. */
|
|
68
|
-
export const samePair = (a: Pair, b: Pair) =>
|
|
69
|
-
a.upto === b.upto && TREES.every((tree) => a[tree].size === b[tree].size && a[tree].root.equals(b[tree].root));
|
|
70
|
-
|
|
71
|
-
/** The one record the signer remembers, holding both notes. */
|
|
72
|
-
export function encodePair(notes: PairNotes): string {
|
|
73
|
-
return JSON.stringify({ changes: notes.changes, uses: notes.uses });
|
|
74
|
-
}
|
|
75
|
-
|
|
76
|
-
export function decodePair(record: string): PairNotes | null {
|
|
77
|
-
try {
|
|
78
|
-
const value = JSON.parse(record) as unknown;
|
|
79
|
-
if (typeof value !== 'object' || value === null) return null;
|
|
80
|
-
const { changes, uses, ...rest } = value as Record<string, unknown>;
|
|
81
|
-
if (typeof changes !== 'string' || typeof uses !== 'string' || Object.keys(rest).length > 0) return null;
|
|
82
|
-
return { changes, uses };
|
|
83
|
-
} catch {
|
|
84
|
-
return null;
|
|
85
|
-
}
|
|
86
|
-
}
|