@coffre/core 0.14.4 → 0.15.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/dist/{access-CembYDiI.js → access-CgQTlUMz.js} +93 -1
- package/dist/{access-CU3xEOLH.d.ts → access-DqLJjnLM.d.ts} +67 -1
- package/dist/access.d.ts +2 -2
- package/dist/access.js +2 -2
- package/dist/identity.d.ts +102 -2
- package/dist/identity.js +410 -161
- package/dist/mcp.d.ts +3 -2
- package/dist/mcp.js +6 -2
- package/dist/merkle.d.ts +456 -0
- package/dist/merkle.js +964 -0
- package/dist/schemas.d.ts +11 -3
- package/dist/schemas.js +12 -2
- package/dist/vault.d.ts +1181 -6
- package/dist/vault.js +280 -1
- package/dist/{workloads-CW2dK4AW.d.ts → workloads-D049JH0M.d.ts} +9 -1
- package/dist/workloads.d.ts +2 -2
- package/dist/workloads.js +9 -1
- package/package.json +8 -3
- package/src/access.ts +93 -0
- package/src/answers.ts +209 -0
- package/src/audit/leaf.ts +81 -0
- package/src/audit/merkle.ts +13 -0
- package/src/audit/note.ts +187 -0
- package/src/audit/pair.ts +86 -0
- package/src/audit/tiles.ts +197 -0
- package/src/audit/tree.ts +163 -0
- package/src/audit/verify.ts +393 -0
- package/src/audit/witness.ts +50 -0
- package/src/identity/index.ts +2 -0
- package/src/identity/profile-rules.ts +147 -0
- package/src/identity/run-proof.ts +159 -0
- package/src/identity/workloads.ts +11 -0
- package/src/mcp.ts +6 -2
- package/src/schemas.ts +11 -0
- package/src/vault.ts +955 -1
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
import { expectedAudiences, PROFILE_RULES } from './profile-rules.ts';
|
|
2
|
+
import { CLOCK_TOLERANCE_SECONDS, decodeWorkloadToken, MAX_TOKEN_AGE_SECONDS, uploadedKeys, verifyWorkloadToken, WorkloadTokenRefused, type JSONWebKeySet } from './workload-token.ts';
|
|
3
|
+
import { claimAt, differingClaims, REPEATING_PROFILES, type BindingClaims, type BindingPolicy, type WorkloadProfile } from './workloads.ts';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* The claims of the run a credential was issued for, as the issuer
|
|
7
|
+
* asserted them: in the sign-in's record, so that a read leads back to its
|
|
8
|
+
* run. What the issuer says, not proof of which run sent the request.
|
|
9
|
+
*/
|
|
10
|
+
export const RUN_CLAIMS = [
|
|
11
|
+
'sub', 'jti', 'actor', 'event_name', 'ref', 'base_ref', 'head_ref', 'sha', 'repository', 'repository_id', 'run_id', 'run_attempt',
|
|
12
|
+
'workflow_ref', 'job_workflow_ref', 'job_workflow_sha', 'environment',
|
|
13
|
+
'project_path', 'project_id', 'namespace_id', 'pipeline_id', 'pipeline_source', 'job_id',
|
|
14
|
+
'kubernetes.io.pod.name',
|
|
15
|
+
] as const;
|
|
16
|
+
const MAX_RUN_CLAIM = 256;
|
|
17
|
+
|
|
18
|
+
/** A binding's `jwks_uri` when it carries its issuer's keys: the SHA-256 of those keys (`UploadedKeys`), where a fetched set's URL would be. */
|
|
19
|
+
export const UPLOADED_KEYS = 'sha256:';
|
|
20
|
+
|
|
21
|
+
/** The run's claims, as the issuer stated them: those that say which run, each bounded. */
|
|
22
|
+
export function runClaims(claims: Record<string, unknown>): Record<string, string | number> {
|
|
23
|
+
const run: Record<string, string | number> = {};
|
|
24
|
+
for (const name of RUN_CLAIMS) {
|
|
25
|
+
const value = claimAt(claims, name);
|
|
26
|
+
if (typeof value === 'string') run[name] = value.slice(0, MAX_RUN_CLAIM);
|
|
27
|
+
else if (typeof value === 'number' && Number.isFinite(value)) run[name] = value;
|
|
28
|
+
}
|
|
29
|
+
return run;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** A token's one audience, or null for none or several: a token for several parties is no single party's. */
|
|
33
|
+
export function soleAudience(aud: unknown): string | null {
|
|
34
|
+
if (typeof aud === 'string') return aud;
|
|
35
|
+
return Array.isArray(aud) && aud.length === 1 && typeof aud[0] === 'string' ? aud[0] : null;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* A binding as the vault weighs a sign-in through it (T149, PR 3b): its
|
|
40
|
+
* sealed object's columns, the instance it was made on (`origin`), and the
|
|
41
|
+
* keys uploaded with it as its row keeps them, which must be the ones its
|
|
42
|
+
* `jwksUri` digests. Only such a binding's: the vault fetches nothing, so
|
|
43
|
+
* the tokens of an issuer that publishes its keys are the app's to verify.
|
|
44
|
+
*/
|
|
45
|
+
export type RunBinding = {
|
|
46
|
+
profile: WorkloadProfile;
|
|
47
|
+
issuer: string;
|
|
48
|
+
origin: string;
|
|
49
|
+
jwksUri: string;
|
|
50
|
+
jwks: string;
|
|
51
|
+
claims: string;
|
|
52
|
+
policy: string | null;
|
|
53
|
+
};
|
|
54
|
+
|
|
55
|
+
/** Why a run's proof buys nothing, as the app's refusals say it (`ExchangeReason`), with the key a refused token named. */
|
|
56
|
+
export class RunProofRefused extends Error {
|
|
57
|
+
readonly reason: string;
|
|
58
|
+
readonly kid: string | null;
|
|
59
|
+
constructor(reason: string, message: string, kid: string | null = null) {
|
|
60
|
+
super(message);
|
|
61
|
+
this.name = 'RunProofRefused';
|
|
62
|
+
this.reason = reason;
|
|
63
|
+
this.kid = kid;
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** What a run's proof says, verified: what the credential it buys is held to. */
|
|
68
|
+
export type RunProof = {
|
|
69
|
+
claims: Record<string, unknown>;
|
|
70
|
+
/** The run's claims, for the sign-in's record. */
|
|
71
|
+
run: Record<string, string | number>;
|
|
72
|
+
/** The token's signing input's hash, spent once; null for a token its platform hands out again, or one that names the session's key. */
|
|
73
|
+
spent: Buffer | null;
|
|
74
|
+
/** The last instant the token holds by its own times, ms: a CI run's (its `exp`, its `iat`'s hour); null for a workload's session. */
|
|
75
|
+
validUntil: number | null;
|
|
76
|
+
/** A workload's session's hard end by the token, ms (its `exp`); null when the token names the session's key, or for a CI run. */
|
|
77
|
+
notAfter: number | null;
|
|
78
|
+
};
|
|
79
|
+
|
|
80
|
+
/** A token's `kid`, at most 64 characters, for a refusal and the alert it raises; the token is unverified. */
|
|
81
|
+
function shownKid(header: Record<string, unknown>): string | null {
|
|
82
|
+
return typeof header.kid === 'string' ? header.kid.slice(0, 64) : null;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* Verify a CI run's or a workload's ID token against one binding, sealed
|
|
87
|
+
* (D148), whose keys were uploaded with it: the vault's own check, which
|
|
88
|
+
* no app can steer, and which asks no one. The binding's keys, held to the
|
|
89
|
+
* digest its seal covers (a key they lack is refused, never looked for),
|
|
90
|
+
* its issuer, its audience (the instance it was made on, or, for a
|
|
91
|
+
* platform whose caller names the session's key, that key: `jkt`, from the
|
|
92
|
+
* DPoP proof the vault verified, never from the app), the token's times,
|
|
93
|
+
* the binding's claims and its profile's rules. Throws `RunProofRefused`.
|
|
94
|
+
*/
|
|
95
|
+
export async function verifyRunToken(
|
|
96
|
+
token: string,
|
|
97
|
+
binding: RunBinding,
|
|
98
|
+
context: { now: Date; workload: { jkt: string } | null },
|
|
99
|
+
): Promise<RunProof> {
|
|
100
|
+
let decoded: ReturnType<typeof decodeWorkloadToken>;
|
|
101
|
+
try {
|
|
102
|
+
decoded = decodeWorkloadToken(token);
|
|
103
|
+
} catch (error) {
|
|
104
|
+
throw refusedBy(error);
|
|
105
|
+
}
|
|
106
|
+
const { claims: unverified, header } = decoded;
|
|
107
|
+
if (unverified.iss !== binding.issuer) throw new RunProofRefused('no_match', `the token is from ${unverified.iss}, which this binding does not trust`);
|
|
108
|
+
const policy = binding.policy === null ? null : (JSON.parse(binding.policy) as BindingPolicy);
|
|
109
|
+
if ((context.workload === null) !== (policy === null)) throw new RunProofRefused('no_match', 'a CI run signs in through a binding with no policy, a workload through one with');
|
|
110
|
+
// The audience the binding takes: the instance's, or, for a workload, its profile's (the session's key among them).
|
|
111
|
+
const accepted = context.workload === null
|
|
112
|
+
? [binding.origin]
|
|
113
|
+
: expectedAudiences(binding.profile, policy!, { publicUrl: binding.origin, jkt: context.workload.jkt });
|
|
114
|
+
const named = soleAudience(unverified.aud);
|
|
115
|
+
const audience = named !== null && accepted.includes(named) ? named : accepted[0]!;
|
|
116
|
+
const repeating = context.workload !== null && REPEATING_PROFILES.includes(binding.profile);
|
|
117
|
+
const expected = { issuer: binding.issuer, audience, now: context.now, ...(repeating ? { maxAge: null } : {}) };
|
|
118
|
+
let claims: Record<string, unknown>;
|
|
119
|
+
try {
|
|
120
|
+
// The very keys its seal digests, never others the app names (a forged set).
|
|
121
|
+
const uploaded = await uploadedKeys(JSON.parse(binding.jwks) as unknown);
|
|
122
|
+
if (`${UPLOADED_KEYS}${uploaded.digest}` !== binding.jwksUri) throw new RunProofRefused('keys', 'the keys are not those the binding was made with');
|
|
123
|
+
// No issuer to ask whether a token still stands, so none lives past the hour.
|
|
124
|
+
claims = await verifyWorkloadToken(token, JSON.parse(uploaded.jwks) as JSONWebKeySet, { ...expected, maxLifetime: MAX_TOKEN_AGE_SECONDS });
|
|
125
|
+
} catch (error) {
|
|
126
|
+
if (error instanceof RunProofRefused) throw error;
|
|
127
|
+
if (error instanceof WorkloadTokenRefused && error.reason === 'unknown_key') {
|
|
128
|
+
throw new RunProofRefused('unknown_key', error.message, shownKid(header));
|
|
129
|
+
}
|
|
130
|
+
throw refusedBy(error);
|
|
131
|
+
}
|
|
132
|
+
const differ = differingClaims(binding.profile, JSON.parse(binding.claims) as BindingClaims, claims);
|
|
133
|
+
if (differ.length > 0) throw new RunProofRefused('no_match', `the binding does not trust these claims: ${differ.join(', ')} differ`);
|
|
134
|
+
if (context.workload !== null) {
|
|
135
|
+
const ruled = PROFILE_RULES[binding.profile]?.token(claims, { issuer: binding.issuer, claims: JSON.parse(binding.claims) as BindingClaims, policy: policy! }) ?? null;
|
|
136
|
+
if (ruled !== null) throw new RunProofRefused('no_match', ruled);
|
|
137
|
+
}
|
|
138
|
+
const run = runClaims(claims);
|
|
139
|
+
if (context.workload === null) {
|
|
140
|
+
// The token's own times, held to again in the statement: its `exp`, and its `iat`'s hour, whole ms, down.
|
|
141
|
+
const validUntil = Math.floor(Math.min((decoded.claims.exp + CLOCK_TOLERANCE_SECONDS) * 1000, (decoded.claims.iat + MAX_TOKEN_AGE_SECONDS) * 1000));
|
|
142
|
+
return { claims, run, spent: decoded.signingInputHash, validUntil, notAfter: null };
|
|
143
|
+
}
|
|
144
|
+
// A token that names the session's key, or one its platform hands out again, is never spent; any other once. One that
|
|
145
|
+
// does not name the key ends the session at its own `exp`.
|
|
146
|
+
const namesKey = policy!.keyAudience === true;
|
|
147
|
+
return {
|
|
148
|
+
claims, run,
|
|
149
|
+
spent: namesKey || repeating ? null : decoded.signingInputHash,
|
|
150
|
+
validUntil: null,
|
|
151
|
+
notAfter: namesKey ? null : decoded.claims.exp * 1000,
|
|
152
|
+
};
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
function refusedBy(error: unknown): RunProofRefused {
|
|
156
|
+
if (error instanceof WorkloadTokenRefused) return new RunProofRefused(error.reason, error.message);
|
|
157
|
+
if (error instanceof RunProofRefused) return error;
|
|
158
|
+
return new RunProofRefused('malformed', (error as Error)?.message ?? 'the token is not one coffre reads');
|
|
159
|
+
}
|
|
@@ -673,6 +673,17 @@ export type BindingPolicy = {
|
|
|
673
673
|
readonly unsignedUploads?: true;
|
|
674
674
|
};
|
|
675
675
|
|
|
676
|
+
/** How long a credential an exchange issues lives: one `coffre run` needs it for seconds. The vault holds a sign-in to it (T149). */
|
|
677
|
+
export const EXCHANGED_CREDENTIAL_MS = 5 * 60 * 1000;
|
|
678
|
+
|
|
679
|
+
/** How long a session lives past each renewal, unless its proof says less: an hour (section 5.4). The vault holds a sign-in to it. */
|
|
680
|
+
export const SESSION_MS = 60 * 60 * 1000;
|
|
681
|
+
|
|
682
|
+
/** A workload's sign-in route, whose URL on the instance its DPoP proof signs: the app's route, and what the vault checks the proof for (PR 3b). */
|
|
683
|
+
export const WORKLOAD_SIGN_IN_PATH = '/api/auth/workload';
|
|
684
|
+
/** How far a sign-in's DPoP proof's `iat` may be from now: it carries no nonce, so its clock bounds it (section 4.1). The app and the vault alike. */
|
|
685
|
+
export const EXCHANGE_SKEW_SECONDS = 60;
|
|
686
|
+
|
|
676
687
|
/** What a field left out of a policy means. */
|
|
677
688
|
export const POLICY_DEFAULTS = {
|
|
678
689
|
keyAudience: false,
|
package/src/mcp.ts
CHANGED
|
@@ -151,13 +151,17 @@ export type ClientMetadata = {
|
|
|
151
151
|
|
|
152
152
|
const MAX_REDIRECTS = 10;
|
|
153
153
|
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;
|
|
154
156
|
|
|
155
157
|
/**
|
|
156
158
|
* Whether `value` is a Client ID Metadata Document's URL: HTTPS, with a
|
|
157
|
-
* path, and nothing a document's address has no use for
|
|
158
|
-
* instance, a loopback one too, for
|
|
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.
|
|
159
162
|
*/
|
|
160
163
|
export function isClientIdUrl(value: string, options: { allowLoopback: boolean }): boolean {
|
|
164
|
+
if (value.length > MAX_CLIENT_ID) return false;
|
|
161
165
|
if (!value.startsWith('https://') && !(options.allowLoopback && value.startsWith('http://'))) return false;
|
|
162
166
|
let url: URL;
|
|
163
167
|
try {
|
package/src/schemas.ts
CHANGED
|
@@ -41,6 +41,17 @@ 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
|
+
/**
|
|
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
|
+
}
|
|
44
55
|
export const displayName = z.string().trim().min(1).max(120);
|
|
45
56
|
/** A folder: 1 to 64 characters, no `/`, no control character, no space at either end (the tables check it too). */
|
|
46
57
|
export const folderName = z.string().min(1).max(64)
|