@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
|
@@ -0,0 +1,1233 @@
|
|
|
1
|
+
import { I as WorkloadProfile, P as WorkloadAlert, a as BindingPolicy, c as CheckedBinding, r as BindingClaims } from "./workloads-CW2dK4AW.js";
|
|
2
|
+
import { JSONWebKeySet, JWTPayload } from "jose";
|
|
3
|
+
import { MAX_PROOF_LENGTH as MAX_PROOF_LENGTH$1, MAX_SIGNED_HEADERS as MAX_SIGNED_HEADERS$1, ProofClaims, ProofClaims as ProofClaims$1, PublicJwk, PublicJwk as PublicJwk$1, canonicalHtu as canonicalHtu$1, canonicalRequest, fetchMethod as fetchMethod$1, sentTarget as sentTarget$1, thumbprint as thumbprint$1 } from "@coffre/client/dpop";
|
|
4
|
+
//#region src/identity/github-app.d.ts
|
|
5
|
+
/**
|
|
6
|
+
* The deployment's own GitHub App, made once with `githubApp(…)` and passed
|
|
7
|
+
* to each side that uses it (docs/github-app.md):
|
|
8
|
+
*
|
|
9
|
+
* const app = githubApp({ appId, privateKey, clientId, clientSecret });
|
|
10
|
+
* signin({ providers: [github({ app })], workloads: { limits, github: app } })
|
|
11
|
+
*
|
|
12
|
+
* Sign-in uses its OAuth client, `clientId` and `clientSecret`, as it would
|
|
13
|
+
* an OAuth app's (`github({ app })`). The forge side, `workloads.github`,
|
|
14
|
+
* uses its ID and private key: it lists the repositories the app is
|
|
15
|
+
* installed on, private ones too, where an owner trusts a workflow, and
|
|
16
|
+
* resolves `owner/name` to the IDs a binding names, with Metadata:
|
|
17
|
+
* read-only, so what it reaches there is the names and IDs of those
|
|
18
|
+
* repositories. Either side may go without the other: `github({ clientId,
|
|
19
|
+
* clientSecret })` signs in alone, and an app with no client lists alone.
|
|
20
|
+
*
|
|
21
|
+
* The app's private key lives with the app, the rest of the deployment's
|
|
22
|
+
* configuration, not in the vault: it opens no secret, and the vault's
|
|
23
|
+
* isolation is for the keys that do. It and the client secret stay in this
|
|
24
|
+
* object's private fields, and no message, log line or answer carries them,
|
|
25
|
+
* the JWTs it signs or the installation tokens they buy.
|
|
26
|
+
*
|
|
27
|
+
* The object lives as long as its configuration: the isolate's, on Workers,
|
|
28
|
+
* or the process's. It keeps settled values only (AGENTS.md, "What an
|
|
29
|
+
* isolate keeps"): the imported key, the app's name, and each
|
|
30
|
+
* installation's token until shortly before it expires. Concurrent first
|
|
31
|
+
* calls each import and ask for their own.
|
|
32
|
+
*/
|
|
33
|
+
type GitHubAppOptions = {
|
|
34
|
+
/** The app's ID, on its settings page ("App ID"): a number, not its client ID. */
|
|
35
|
+
appId: string | number;
|
|
36
|
+
/** A private key generated on its settings page: the PEM file, as downloaded. */
|
|
37
|
+
privateKey: string;
|
|
38
|
+
/** Its OAuth client, on the same page: for signing people in with it, `github({ app })`. Both, or neither. */
|
|
39
|
+
clientId?: string;
|
|
40
|
+
clientSecret?: string;
|
|
41
|
+
/** https://github.com, or a GitHub Enterprise Server host: where people sign in. */
|
|
42
|
+
webUrl?: string;
|
|
43
|
+
/**
|
|
44
|
+
* https://api.github.com, or `${host}/api/v3` on Enterprise Server. The
|
|
45
|
+
* forge side takes github.com's only, or the dev IdP's on loopback: an
|
|
46
|
+
* Enterprise Server's runs sign their tokens under another issuer than
|
|
47
|
+
* the one its lookups bind to.
|
|
48
|
+
*/
|
|
49
|
+
apiUrl?: string;
|
|
50
|
+
};
|
|
51
|
+
/** A repository, by the IDs a binding names: what `GET /workloads/lookup` answers. */
|
|
52
|
+
type GitHubRepository = {
|
|
53
|
+
github: string;
|
|
54
|
+
repositoryId: string;
|
|
55
|
+
ownerId: string;
|
|
56
|
+
private: boolean;
|
|
57
|
+
};
|
|
58
|
+
/** What the app reaches: its name and where to install it, the accounts it is installed on, and their repositories. */
|
|
59
|
+
type GitHubAppRepositories = {
|
|
60
|
+
app: {
|
|
61
|
+
name: string;
|
|
62
|
+
installUrl: string;
|
|
63
|
+
};
|
|
64
|
+
/** The accounts it is installed on, by login. */
|
|
65
|
+
installations: string[];
|
|
66
|
+
/** By name. */
|
|
67
|
+
repositories: GitHubRepository[];
|
|
68
|
+
/** More than one listing reaches: the others are typed by name. */
|
|
69
|
+
truncated: boolean;
|
|
70
|
+
};
|
|
71
|
+
/** GitHub could not be asked, or refused the app: the message says which, for a person, and carries no credential. */
|
|
72
|
+
declare class GitHubAppUnavailable extends Error {
|
|
73
|
+
constructor(message: string, options?: {
|
|
74
|
+
cause?: unknown;
|
|
75
|
+
});
|
|
76
|
+
}
|
|
77
|
+
/** Requests one listing makes at most, tokens included: well under a Worker's subrequest limit. */
|
|
78
|
+
declare const MAX_LISTING_REQUESTS = 40;
|
|
79
|
+
/** A token GitHub issues for an hour is used until this long before it ends, so that none expires mid-call. */
|
|
80
|
+
declare const TOKEN_MARGIN_MS: number;
|
|
81
|
+
declare class GitHubApp {
|
|
82
|
+
#private;
|
|
83
|
+
readonly appId: string;
|
|
84
|
+
readonly webUrl: string;
|
|
85
|
+
readonly apiUrl: string;
|
|
86
|
+
/** Its OAuth client's ID, which is no secret; null when it was given none. */
|
|
87
|
+
readonly clientId: string | null;
|
|
88
|
+
constructor(options: {
|
|
89
|
+
appId: string;
|
|
90
|
+
apiUrl: string;
|
|
91
|
+
webUrl?: string;
|
|
92
|
+
pkcs8: Uint8Array<ArrayBuffer>;
|
|
93
|
+
client?: {
|
|
94
|
+
clientId: string;
|
|
95
|
+
clientSecret: string;
|
|
96
|
+
};
|
|
97
|
+
}, io?: {
|
|
98
|
+
fetch?: typeof fetch;
|
|
99
|
+
now?: () => number;
|
|
100
|
+
});
|
|
101
|
+
/** Its OAuth client, for `github({ app })`; null when it was given none. */
|
|
102
|
+
signinClient(): {
|
|
103
|
+
clientId: string;
|
|
104
|
+
clientSecret: string;
|
|
105
|
+
} | null;
|
|
106
|
+
/**
|
|
107
|
+
* Every repository of every account the app is installed on, as many as
|
|
108
|
+
* `MAX_LISTING_REQUESTS` reach. `signal` ends every request still going
|
|
109
|
+
* when it aborts, and the listing with `GitHubAppUnavailable`: the caller's
|
|
110
|
+
* deadline for the whole of it, beside each request's own.
|
|
111
|
+
*/
|
|
112
|
+
repositories(options?: {
|
|
113
|
+
signal?: AbortSignal;
|
|
114
|
+
}): Promise<GitHubAppRepositories>;
|
|
115
|
+
/** `owner/name`'s IDs, when the app is installed on it; null when it is not, its installation is suspended, or GitHub knows no such repository. `signal` as for `repositories`. */
|
|
116
|
+
repository(fullName: string, options?: {
|
|
117
|
+
signal?: AbortSignal;
|
|
118
|
+
}): Promise<GitHubRepository | null>;
|
|
119
|
+
}
|
|
120
|
+
/**
|
|
121
|
+
* A private key's PEM as PKCS #8, which Web Crypto imports: GitHub's
|
|
122
|
+
* download is PKCS #1 (`BEGIN RSA PRIVATE KEY`), wrapped here as an RSA
|
|
123
|
+
* key's PKCS #8. Escaped newlines, as an environment variable sometimes
|
|
124
|
+
* holds them, are newlines. Never says what the key was.
|
|
125
|
+
*/
|
|
126
|
+
declare function pkcs8Of(pem: string): Uint8Array<ArrayBuffer>;
|
|
127
|
+
//#endregion
|
|
128
|
+
//#region src/identity/signin/types.d.ts
|
|
129
|
+
/**
|
|
130
|
+
* What a provider reports about the person who just signed in.
|
|
131
|
+
*
|
|
132
|
+
* `subject` is the provider's permanent id for the account: OIDC's `sub`,
|
|
133
|
+
* GitHub's numeric user id. coffre binds to it and to nothing else, since a
|
|
134
|
+
* login name can be renamed and an email address can be handed to someone new.
|
|
135
|
+
*/
|
|
136
|
+
type SigninProfile = {
|
|
137
|
+
subject: string;
|
|
138
|
+
/** Verified addresses only, lowercased, the provider's primary first. */
|
|
139
|
+
emails: string[];
|
|
140
|
+
name: string | null;
|
|
141
|
+
};
|
|
142
|
+
/**
|
|
143
|
+
* What must survive the round trip through the provider: the anti-CSRF
|
|
144
|
+
* state, the PKCE verifier and, for OIDC, the nonce. coffre keeps it in an
|
|
145
|
+
* encrypted, short-lived cookie rather than in the database, so an
|
|
146
|
+
* unauthenticated visitor cannot make coffre write anything.
|
|
147
|
+
*/
|
|
148
|
+
type PendingSignin = {
|
|
149
|
+
state: string;
|
|
150
|
+
codeVerifier: string;
|
|
151
|
+
nonce: string | null;
|
|
152
|
+
};
|
|
153
|
+
type SigninErrorCode =
|
|
154
|
+
/** The person cancelled, or the provider refused them. */
|
|
155
|
+
'provider_denied' |
|
|
156
|
+
/** The callback does not belong to the sign-in this browser started. */
|
|
157
|
+
'state_mismatch' |
|
|
158
|
+
/** The provider answered, but not in a way that can be trusted. */
|
|
159
|
+
'invalid_response' |
|
|
160
|
+
/** The provider could not be reached. */
|
|
161
|
+
'provider_unavailable' |
|
|
162
|
+
/** The account has no verified email address to match an invitation with. */
|
|
163
|
+
'no_verified_email' |
|
|
164
|
+
/** A Google account outside the configured Workspace domain. */
|
|
165
|
+
'wrong_domain' |
|
|
166
|
+
/** A GitHub account outside the configured organization. */
|
|
167
|
+
'not_in_organization';
|
|
168
|
+
declare class SigninError extends Error {
|
|
169
|
+
readonly code: SigninErrorCode;
|
|
170
|
+
constructor(code: SigninErrorCode, message: string);
|
|
171
|
+
}
|
|
172
|
+
type ProviderOptions = {
|
|
173
|
+
/** Injected by tests; defaults to globalThis.fetch. */
|
|
174
|
+
fetch?: typeof fetch;
|
|
175
|
+
};
|
|
176
|
+
/** Which mark the sign-in button carries: GitHub's, Google's, Microsoft's, or a plain key. */
|
|
177
|
+
type SigninBrand = 'github' | 'google' | 'microsoft' | 'oidc';
|
|
178
|
+
/**
|
|
179
|
+
* A way to sign in: send the browser to whoever knows the person, and take
|
|
180
|
+
* back who they are. `github()`, `google()`, `microsoft()` and `oidc()` make
|
|
181
|
+
* one; so can a deployment, for a provider that is none of those. coffre
|
|
182
|
+
* does everything around it: the pending state, sealed in a cookie between
|
|
183
|
+
* the two calls, binding the profile to a member, sessions, CLI logins and
|
|
184
|
+
* service tokens.
|
|
185
|
+
*
|
|
186
|
+
* const acme: SigninProvider = {
|
|
187
|
+
* id: 'acme',
|
|
188
|
+
* issuer: 'https://sso.acme.example',
|
|
189
|
+
* label: 'Acme SSO',
|
|
190
|
+
* brand: 'oidc',
|
|
191
|
+
* async start(redirectUri) { … return { url, pending: { state, codeVerifier, nonce: null } }; },
|
|
192
|
+
* async finish(callbackUrl, redirectUri, pending) { … return { subject, emails, name }; },
|
|
193
|
+
* };
|
|
194
|
+
*/
|
|
195
|
+
interface SigninProvider {
|
|
196
|
+
/** Stable: part of the callback URL, `/auth/callback/{id}`, and of every account bound through it. */
|
|
197
|
+
readonly id: string;
|
|
198
|
+
/** The authority whose subjects these are; changing it requires linking accounts again. */
|
|
199
|
+
readonly issuer: string;
|
|
200
|
+
/** Button text: "Continue with {label}". */
|
|
201
|
+
readonly label: string;
|
|
202
|
+
readonly brand: SigninBrand;
|
|
203
|
+
/** Where to send the browser, and what to remember until it comes back. */
|
|
204
|
+
start(redirectUri: string, options?: {
|
|
205
|
+
loginHint?: string;
|
|
206
|
+
}): Promise<{
|
|
207
|
+
url: URL;
|
|
208
|
+
pending: PendingSignin;
|
|
209
|
+
}>;
|
|
210
|
+
/**
|
|
211
|
+
* The person back from the provider, verified: check the callback against
|
|
212
|
+
* `pending`, and throw a SigninError for anything that does not hold.
|
|
213
|
+
*/
|
|
214
|
+
finish(callbackUrl: URL, redirectUri: string, pending: PendingSignin): Promise<SigninProfile>;
|
|
215
|
+
}
|
|
216
|
+
//#endregion
|
|
217
|
+
//#region src/identity/signin/github.d.ts
|
|
218
|
+
/**
|
|
219
|
+
* GitHub's OAuth web flow, which is OAuth 2.0 without OpenID Connect: no ID
|
|
220
|
+
* token, so the profile comes from the REST API with the access token the
|
|
221
|
+
* code is exchanged for. That token is used for these two or three calls and
|
|
222
|
+
* then dropped; coffre never stores it.
|
|
223
|
+
*
|
|
224
|
+
* Works with an OAuth App or a GitHub App's user authorization, on github.com
|
|
225
|
+
* or GitHub Enterprise Server.
|
|
226
|
+
*/
|
|
227
|
+
declare class GitHubSigninProvider implements SigninProvider {
|
|
228
|
+
#private;
|
|
229
|
+
readonly id: string;
|
|
230
|
+
readonly issuer: string;
|
|
231
|
+
readonly label: string;
|
|
232
|
+
readonly brand: SigninBrand;
|
|
233
|
+
/** What it was made from, as checked. */
|
|
234
|
+
readonly config: GitHubProviderConfig;
|
|
235
|
+
constructor(config: GitHubProviderConfig, options?: ProviderOptions);
|
|
236
|
+
start(redirectUri: string, options?: {
|
|
237
|
+
loginHint?: string;
|
|
238
|
+
}): Promise<{
|
|
239
|
+
url: URL;
|
|
240
|
+
pending: PendingSignin;
|
|
241
|
+
}>;
|
|
242
|
+
finish(callbackUrl: URL, redirectUri: string, pending: PendingSignin): Promise<SigninProfile>;
|
|
243
|
+
}
|
|
244
|
+
//#endregion
|
|
245
|
+
//#region src/identity/signin/oidc.d.ts
|
|
246
|
+
/**
|
|
247
|
+
* The authorization code flow with PKCE, against any OpenID Connect issuer.
|
|
248
|
+
*
|
|
249
|
+
* Protocol work is delegated to oauth4webapi: discovery with issuer
|
|
250
|
+
* validation, the RFC 9207 `iss` check on the callback, the token request and
|
|
251
|
+
* ID token claim validation (issuer, audience, expiry, nonce). The ID token is
|
|
252
|
+
* received straight from the token endpoint over TLS with client
|
|
253
|
+
* authentication, which OpenID Connect Core 3.1.3.7 accepts in place of
|
|
254
|
+
* checking its signature.
|
|
255
|
+
*/
|
|
256
|
+
declare class OidcSigninProvider implements SigninProvider {
|
|
257
|
+
#private;
|
|
258
|
+
readonly id: string;
|
|
259
|
+
readonly issuer: string;
|
|
260
|
+
readonly label: string;
|
|
261
|
+
readonly brand: SigninBrand;
|
|
262
|
+
/** What it was made from, as checked. */
|
|
263
|
+
readonly config: OidcProviderConfig;
|
|
264
|
+
constructor(config: OidcProviderConfig, options?: ProviderOptions);
|
|
265
|
+
start(redirectUri: string, options?: {
|
|
266
|
+
loginHint?: string;
|
|
267
|
+
}): Promise<{
|
|
268
|
+
url: URL;
|
|
269
|
+
pending: PendingSignin;
|
|
270
|
+
}>;
|
|
271
|
+
finish(callbackUrl: URL, redirectUri: string, pending: PendingSignin): Promise<SigninProfile>;
|
|
272
|
+
}
|
|
273
|
+
//#endregion
|
|
274
|
+
//#region src/identity/signin/config.d.ts
|
|
275
|
+
type ProviderBase = {
|
|
276
|
+
id: string;
|
|
277
|
+
label: string;
|
|
278
|
+
brand: SigninBrand;
|
|
279
|
+
clientId: string;
|
|
280
|
+
clientSecret: string;
|
|
281
|
+
};
|
|
282
|
+
type OidcProviderConfig = ProviderBase & {
|
|
283
|
+
/** Issuer identifier; discovery is fetched from `${issuer}/.well-known/openid-configuration`. */
|
|
284
|
+
issuer: string;
|
|
285
|
+
scopes: string[];
|
|
286
|
+
/** Extra authorization request parameters, such as Google's `hd` hint. */
|
|
287
|
+
authorizationParams: Record<string, string>;
|
|
288
|
+
/**
|
|
289
|
+
* The Google Workspace domain the ID token's `hd` claim must equal. The
|
|
290
|
+
* `hd` request parameter only filters Google's account picker; the claim is
|
|
291
|
+
* what proves membership.
|
|
292
|
+
*/
|
|
293
|
+
hostedDomain: string | null;
|
|
294
|
+
};
|
|
295
|
+
type GitHubProviderConfig = ProviderBase & {
|
|
296
|
+
/** https://github.com, or a GitHub Enterprise Server host. */
|
|
297
|
+
webUrl: string;
|
|
298
|
+
/** https://api.github.com, or `${host}/api/v3` on Enterprise Server. */
|
|
299
|
+
apiUrl: string;
|
|
300
|
+
/** When set, only active members of this organization may sign in. */
|
|
301
|
+
organization: string | null;
|
|
302
|
+
};
|
|
303
|
+
type SigninPage = {
|
|
304
|
+
/** Heading on the sign-in page, e.g. "Acme secrets". */
|
|
305
|
+
title: string;
|
|
306
|
+
/** One line under it, e.g. "Use your acme.example Google account." */
|
|
307
|
+
note: string | null;
|
|
308
|
+
};
|
|
309
|
+
type SigninConfig = {
|
|
310
|
+
/** The origin people reach coffre at. Callback URLs are built from it, never from the Host header. */
|
|
311
|
+
publicUrl: string;
|
|
312
|
+
providers: SigninProvider[];
|
|
313
|
+
page: SigninPage;
|
|
314
|
+
/** Absolute lifetime of a browser session. */
|
|
315
|
+
browserSessionHours: number;
|
|
316
|
+
/** Absolute lifetime of a CLI session. */
|
|
317
|
+
cliSessionDays: number;
|
|
318
|
+
/** CI runs signing in as services with their platform's ID token, when on (`workloads.ts`). */
|
|
319
|
+
workloads: WorkloadsConfig | null;
|
|
320
|
+
/** MCP clients acting as the people who connect them, when on (docs/design/mcp.md). */
|
|
321
|
+
mcp: McpConfig | null;
|
|
322
|
+
};
|
|
323
|
+
/**
|
|
324
|
+
* Workload identity: CI runs that sign in as a service with the ID token
|
|
325
|
+
* their platform signs for them, through the trust bindings an owner sets
|
|
326
|
+
* on the service (docs/design/oidc.md). Off unless the deployment turns it on.
|
|
327
|
+
*/
|
|
328
|
+
type WorkloadsOptions = {
|
|
329
|
+
/**
|
|
330
|
+
* The two limits every exchange passes before coffre does any work for
|
|
331
|
+
* it: one per source address, and one for all sources together. On
|
|
332
|
+
* Workers, two rate-limiting bindings (`env.WORKLOADS_PER_SOURCE`,
|
|
333
|
+
* `env.WORKLOADS_TOTAL`), which Cloudflare counts per location; on Node,
|
|
334
|
+
* `processLimits()` from `@coffre/server/node`, which counts per process.
|
|
335
|
+
* Required: an exchange is never without them.
|
|
336
|
+
*/
|
|
337
|
+
limits: WorkloadLimits;
|
|
338
|
+
/**
|
|
339
|
+
* Lets a binding's issuer be plain HTTP on loopback, as the dev IdP's is:
|
|
340
|
+
* for local development and conformance. Refused unless the public URL is
|
|
341
|
+
* loopback too, so no instance anyone else can reach ever trusts one.
|
|
342
|
+
*/
|
|
343
|
+
allowLoopbackIssuersForDevelopment?: boolean;
|
|
344
|
+
/**
|
|
345
|
+
* The deployment's own GitHub App, `githubApp(…)`, installed on its
|
|
346
|
+
* organizations: where an owner trusts a workflow, the pages list the
|
|
347
|
+
* repositories it is installed on, private ones too, and a repository
|
|
348
|
+
* typed by name resolves through it (docs/github-app.md). The same value
|
|
349
|
+
* may sign people in, `github({ app })`. Left out, repositories are typed,
|
|
350
|
+
* and only public ones' IDs are looked up.
|
|
351
|
+
*/
|
|
352
|
+
github?: GitHubApp;
|
|
353
|
+
/**
|
|
354
|
+
* Leaves services nothing but key-bound sessions (docs/design/
|
|
355
|
+
* workload-access.md, section 6.3): no service token is issued or taken,
|
|
356
|
+
* and `/api/auth/oidc` answers 410. Its sessions still read their
|
|
357
|
+
* bindings' listed `reads`. Taken, and not yet enforced: that design's PR
|
|
358
|
+
* 1a does.
|
|
359
|
+
*/
|
|
360
|
+
useOnly?: boolean;
|
|
361
|
+
/** Stricter still: no binding may list `reads`, so services read plain values only. Taken, and not yet enforced (PR 1a). */
|
|
362
|
+
noReads?: boolean;
|
|
363
|
+
/** The deployment's own delivery of a workload's alerts, called in the background after the response: a Slack webhook, a pager. */
|
|
364
|
+
alert?: (alert: WorkloadAlert) => unknown;
|
|
365
|
+
};
|
|
366
|
+
/** Cloudflare's rate-limiting binding, as coffre calls it; `processLimits()` has the same shape. */
|
|
367
|
+
type RateLimiter = {
|
|
368
|
+
limit(options: {
|
|
369
|
+
key: string;
|
|
370
|
+
}): Promise<{
|
|
371
|
+
success: boolean;
|
|
372
|
+
}>;
|
|
373
|
+
};
|
|
374
|
+
type WorkloadLimits = {
|
|
375
|
+
perSource: RateLimiter;
|
|
376
|
+
total: RateLimiter;
|
|
377
|
+
};
|
|
378
|
+
type WorkloadsConfig = {
|
|
379
|
+
allowLoopback: boolean;
|
|
380
|
+
limits: WorkloadLimits;
|
|
381
|
+
github: GitHubApp | null;
|
|
382
|
+
useOnly: boolean;
|
|
383
|
+
noReads: boolean;
|
|
384
|
+
alert: ((alert: WorkloadAlert) => unknown) | null;
|
|
385
|
+
};
|
|
386
|
+
/**
|
|
387
|
+
* MCP clients, Claude among them, acting as the people who connect them,
|
|
388
|
+
* with coffre as their OAuth authorization server (docs/design/mcp.md). Off
|
|
389
|
+
* unless the deployment turns it on.
|
|
390
|
+
*/
|
|
391
|
+
type McpOptions = {
|
|
392
|
+
/**
|
|
393
|
+
* The limits every unauthenticated OAuth request passes before coffre does
|
|
394
|
+
* any work for it, one per source address and one for all together, and
|
|
395
|
+
* the one each connection's tool calls pass. On Workers, three
|
|
396
|
+
* rate-limiting bindings; on Node, `processLimits()` from
|
|
397
|
+
* `@coffre/server/node`. Required.
|
|
398
|
+
*/
|
|
399
|
+
limits: McpLimits;
|
|
400
|
+
/**
|
|
401
|
+
* Lets a client's metadata document be plain HTTP on loopback: for local
|
|
402
|
+
* development and conformance. Refused unless the public URL is loopback
|
|
403
|
+
* too.
|
|
404
|
+
*/
|
|
405
|
+
allowLoopbackClientsForDevelopment?: boolean;
|
|
406
|
+
};
|
|
407
|
+
type McpLimits = {
|
|
408
|
+
perSource: RateLimiter;
|
|
409
|
+
perConnection: RateLimiter;
|
|
410
|
+
total: RateLimiter;
|
|
411
|
+
};
|
|
412
|
+
type McpConfig = {
|
|
413
|
+
allowLoopback: boolean;
|
|
414
|
+
limits: McpLimits;
|
|
415
|
+
};
|
|
416
|
+
type Credentials = {
|
|
417
|
+
clientId: string;
|
|
418
|
+
clientSecret: string;
|
|
419
|
+
};
|
|
420
|
+
/**
|
|
421
|
+
* Any OpenID Connect provider, by issuer URL.
|
|
422
|
+
*
|
|
423
|
+
* Okta, Auth0, Keycloak, Authentik, Zitadel, Clerk, WorkOS, Dex and the like
|
|
424
|
+
* all live here; so does a broker, for providers that only speak SAML or LDAP.
|
|
425
|
+
*/
|
|
426
|
+
declare function oidc(options: OidcOptions): OidcSigninProvider;
|
|
427
|
+
type OidcOptions = Credentials & {
|
|
428
|
+
id: string;
|
|
429
|
+
label: string;
|
|
430
|
+
issuer: string;
|
|
431
|
+
scopes?: string[];
|
|
432
|
+
authorizationParams?: Record<string, string>;
|
|
433
|
+
};
|
|
434
|
+
/** Google accounts; with `domain`, only that Google Workspace's accounts. */
|
|
435
|
+
declare function google(options: Credentials & {
|
|
436
|
+
id?: string;
|
|
437
|
+
label?: string;
|
|
438
|
+
domain?: string;
|
|
439
|
+
}): OidcSigninProvider;
|
|
440
|
+
/**
|
|
441
|
+
* Microsoft Entra ID, for one tenant.
|
|
442
|
+
*
|
|
443
|
+
* The tenant must be its GUID. Entra's multi-tenant endpoints (`common`,
|
|
444
|
+
* `organizations`) publish an issuer template rather than an issuer, which
|
|
445
|
+
* standard OIDC validation rejects, and "any work account in the world" is not
|
|
446
|
+
* an audience a secrets manager wants anyway.
|
|
447
|
+
*
|
|
448
|
+
* Entra email claims do not prove address ownership. Sign in through another
|
|
449
|
+
* provider and link the Microsoft account first; later sign-ins use its subject.
|
|
450
|
+
*/
|
|
451
|
+
declare function microsoft(options: Credentials & {
|
|
452
|
+
id?: string;
|
|
453
|
+
label?: string;
|
|
454
|
+
tenant: string;
|
|
455
|
+
}): OidcSigninProvider;
|
|
456
|
+
/**
|
|
457
|
+
* GitHub accounts; with `organization`, only that organization's members.
|
|
458
|
+
* Through an OAuth app, or a GitHub App's OAuth client, by its credentials;
|
|
459
|
+
* or the deployment's GitHub App, `github({ app })`, the same value its
|
|
460
|
+
* `workloads.github` lists repositories with:
|
|
461
|
+
*
|
|
462
|
+
* const app = githubApp({ appId, privateKey, clientId, clientSecret });
|
|
463
|
+
* signin({ providers: [github({ app, organization: 'acme' })], workloads: { limits, github: app } })
|
|
464
|
+
*/
|
|
465
|
+
declare function github(options: {
|
|
466
|
+
id?: string;
|
|
467
|
+
label?: string;
|
|
468
|
+
organization?: string;
|
|
469
|
+
} & ((Credentials & {
|
|
470
|
+
webUrl?: string;
|
|
471
|
+
apiUrl?: string;
|
|
472
|
+
}) | {
|
|
473
|
+
app: GitHubApp;
|
|
474
|
+
})): GitHubSigninProvider;
|
|
475
|
+
/**
|
|
476
|
+
* The deployment's GitHub App, checked where it is written: its numeric ID
|
|
477
|
+
* and private key, and its OAuth client when it signs people in too. One
|
|
478
|
+
* value, passed to each side that uses it: `github({ app })` and
|
|
479
|
+
* `workloads.github` (`../github-app.ts`).
|
|
480
|
+
*/
|
|
481
|
+
declare function githubApp(options: GitHubAppOptions): GitHubApp;
|
|
482
|
+
declare function publicOrigin(value: string): string;
|
|
483
|
+
/** Sign-in configuration, checked: at least one provider, each whole, ids unique, lifetimes sane. */
|
|
484
|
+
declare function defineSignin(options: {
|
|
485
|
+
publicUrl: string;
|
|
486
|
+
providers: SigninProvider[];
|
|
487
|
+
page?: {
|
|
488
|
+
title?: string;
|
|
489
|
+
note?: string;
|
|
490
|
+
};
|
|
491
|
+
browserSessionHours?: number;
|
|
492
|
+
cliSessionDays?: number;
|
|
493
|
+
workloads?: WorkloadsOptions;
|
|
494
|
+
mcp?: McpOptions;
|
|
495
|
+
}): SigninConfig;
|
|
496
|
+
declare function lifetime(value: number | undefined, name: string, fallback: number, max: number): number;
|
|
497
|
+
//#endregion
|
|
498
|
+
//#region src/identity/types.d.ts
|
|
499
|
+
/**
|
|
500
|
+
* An authenticated caller.
|
|
501
|
+
*
|
|
502
|
+
* Modelled as a tagged union rather than "a user with an optional email",
|
|
503
|
+
* because Cloudflare Access issues two structurally different tokens:
|
|
504
|
+
*
|
|
505
|
+
* identity token -> sub = user uuid, email = "admin@acme.example"
|
|
506
|
+
* service token -> sub = "" , common_name = "<client-id>.access", NO email
|
|
507
|
+
*
|
|
508
|
+
* Machine callers (external-secrets, CI) are most of the real traffic, so the
|
|
509
|
+
* shape that cannot represent them is the wrong shape.
|
|
510
|
+
*/
|
|
511
|
+
type Principal = {
|
|
512
|
+
type: 'user';
|
|
513
|
+
/** Stable identifier used in grants and in the audit log. */
|
|
514
|
+
id: string;
|
|
515
|
+
email: string;
|
|
516
|
+
subject: string;
|
|
517
|
+
} | {
|
|
518
|
+
type: 'service';
|
|
519
|
+
/** Stable identifier used in grants and in the audit log. */
|
|
520
|
+
id: string;
|
|
521
|
+
commonName: string;
|
|
522
|
+
};
|
|
523
|
+
/**
|
|
524
|
+
* Verifies a bearer token and returns the caller it identifies.
|
|
525
|
+
*
|
|
526
|
+
* Cloudflare mode verifies Access JWTs against the team domain; signin mode
|
|
527
|
+
* looks up coffre's own credentials.
|
|
528
|
+
*/
|
|
529
|
+
interface IdentityVerifier {
|
|
530
|
+
/**
|
|
531
|
+
* `recall`: the request reads values, and has the vault check, before it
|
|
532
|
+
* answers, an answer about its caller kept from an earlier request
|
|
533
|
+
* (server accesses.ts): a verifier that asks the vault may give that one.
|
|
534
|
+
*/
|
|
535
|
+
verify(token: string, request?: {
|
|
536
|
+
sourceIp: string | null;
|
|
537
|
+
recall?: boolean;
|
|
538
|
+
}): Promise<Principal>;
|
|
539
|
+
}
|
|
540
|
+
/** Access delivers the JWT to the origin in this header. */
|
|
541
|
+
declare const ACCESS_JWT_HEADER = "cf-access-jwt-assertion";
|
|
542
|
+
/** Where Access JWTs are checked: the team's keys, and the application's AUD tag. */
|
|
543
|
+
type AccessVerifierConfig = {
|
|
544
|
+
/** Cloudflare Access team domain, e.g. https://acme.cloudflareaccess.com */
|
|
545
|
+
issuer: string;
|
|
546
|
+
/** Usually `${issuer}/cdn-cgi/access/certs`. */
|
|
547
|
+
jwksUrl: string;
|
|
548
|
+
/** The AUD tag of the specific Access application. */
|
|
549
|
+
audience: string;
|
|
550
|
+
/** Seconds of clock skew tolerated. Kept at 0 by default deliberately. */
|
|
551
|
+
clockToleranceSeconds?: number;
|
|
552
|
+
};
|
|
553
|
+
//#endregion
|
|
554
|
+
//#region src/identity/auth.d.ts
|
|
555
|
+
/**
|
|
556
|
+
* Who vouches for the person at the other end of a request.
|
|
557
|
+
*
|
|
558
|
+
* - `signin`: coffre itself, after the person signs in with one of the
|
|
559
|
+
* deployment's providers: GitHub, Google, Microsoft, any OIDC issuer, or
|
|
560
|
+
* one of its own.
|
|
561
|
+
* - `cloudflare`: Cloudflare Access, in front of coffre.
|
|
562
|
+
*
|
|
563
|
+
* Either way, coffre decides who is a member, and issues its own sessions,
|
|
564
|
+
* CLI logins and service tokens.
|
|
565
|
+
*/
|
|
566
|
+
type AuthConfig = {
|
|
567
|
+
mode: 'signin';
|
|
568
|
+
signin: SigninConfig;
|
|
569
|
+
} | {
|
|
570
|
+
mode: 'cloudflare';
|
|
571
|
+
access: AccessVerifierConfig;
|
|
572
|
+
/** How long the coffre session a browser signs in to behind Access lasts, at most: Access is still asked on every request. */
|
|
573
|
+
browserSessionHours: number;
|
|
574
|
+
};
|
|
575
|
+
/**
|
|
576
|
+
* What a deployment writes as `auth`: `signin(…)` or `cloudflareAccess(…)`.
|
|
577
|
+
* Each checks its own options when called; sign-in is finished against the
|
|
578
|
+
* deployment's public URL, which its callbacks are built from.
|
|
579
|
+
*/
|
|
580
|
+
type Auth = {
|
|
581
|
+
resolve(publicUrl: string): AuthConfig;
|
|
582
|
+
};
|
|
583
|
+
/**
|
|
584
|
+
* Cloudflare Access in front of coffre: every request carries Access's
|
|
585
|
+
* signed assertion, checked against the team's keys and the application's
|
|
586
|
+
* AUD tag. A browser's first request signs its person in to a session of
|
|
587
|
+
* coffre's, which every later one shows beside the assertion; the CLI and
|
|
588
|
+
* machines are not served behind Access yet.
|
|
589
|
+
*
|
|
590
|
+
* cloudflareAccess({ teamDomain: 'acme.cloudflareaccess.com', audience: env.ACCESS_AUD })
|
|
591
|
+
*
|
|
592
|
+
* `browserSessionHours`: the longest that session lasts, 12 hours unless
|
|
593
|
+
* set, at most a week. Access's own session is the one people see.
|
|
594
|
+
*/
|
|
595
|
+
declare function cloudflareAccess(options: {
|
|
596
|
+
teamDomain: string;
|
|
597
|
+
audience: string;
|
|
598
|
+
browserSessionHours?: number;
|
|
599
|
+
}): Auth;
|
|
600
|
+
type SigninOptions = {
|
|
601
|
+
/** At least one: `github`, `google`, `microsoft`, `oidc`, or the deployment's own `SigninProvider`. */
|
|
602
|
+
providers: SigninProvider[];
|
|
603
|
+
/** Heading on the sign-in page, e.g. "Acme secrets". */
|
|
604
|
+
title?: string;
|
|
605
|
+
/** One line under it, e.g. "Use your acme.example Google account." */
|
|
606
|
+
note?: string;
|
|
607
|
+
/** Absolute lifetime of a browser session; 12 hours unless set, at most a week. */
|
|
608
|
+
browserSessionHours?: number;
|
|
609
|
+
/** Absolute lifetime of a CLI session; 30 days unless set, at most a year. */
|
|
610
|
+
cliSessionDays?: number;
|
|
611
|
+
/** Lets CI runs sign in as services with their platform's ID token: `{}` turns it on. */
|
|
612
|
+
workloads?: WorkloadsOptions;
|
|
613
|
+
/** Lets MCP clients, Claude among them, act as the people who connect them (docs/mcp.md). */
|
|
614
|
+
mcp?: McpOptions;
|
|
615
|
+
};
|
|
616
|
+
/**
|
|
617
|
+
* coffre's own sign-in page, with these providers:
|
|
618
|
+
*
|
|
619
|
+
* signin({ providers: [github({ clientId, clientSecret, organization: 'acme' })] })
|
|
620
|
+
*/
|
|
621
|
+
declare function signin(options: SigninOptions): Auth;
|
|
622
|
+
//#endregion
|
|
623
|
+
//#region src/identity/workload-token.d.ts
|
|
624
|
+
/**
|
|
625
|
+
* An ID token a CI platform signed for a run, as the exchange checks it
|
|
626
|
+
* (docs/design/oidc.md, section 3). The checks run in this order; each
|
|
627
|
+
* refusal says which, as a reason a CI user can act on.
|
|
628
|
+
*/
|
|
629
|
+
/** A compact JWS is three base64url parts; the whole token at most this long. */
|
|
630
|
+
declare const MAX_TOKEN_BYTES: number;
|
|
631
|
+
/** Each side of every time check. */
|
|
632
|
+
declare const CLOCK_TOLERANCE_SECONDS = 30;
|
|
633
|
+
/** The oldest token accepted, by its `iat`: tokens handed to a job at its start fit, day-old ones do not. */
|
|
634
|
+
declare const MAX_TOKEN_AGE_SECONDS = 3600;
|
|
635
|
+
/** RS256 and ES256 (P-256), as for Access assertions: never `none`, never HS*. */
|
|
636
|
+
declare const WORKLOAD_ALGORITHMS: readonly ["RS256", "ES256"];
|
|
637
|
+
type WorkloadRefusal =
|
|
638
|
+
/** Not a compact JWS, or claims that are not the right types. */
|
|
639
|
+
'malformed' |
|
|
640
|
+
/** The signature does not verify under the issuer's keys. */
|
|
641
|
+
'signature' |
|
|
642
|
+
/** Signed by a key the issuer's set does not hold, now. */
|
|
643
|
+
'unknown_key' |
|
|
644
|
+
/** Past its `exp`. */
|
|
645
|
+
'expired' |
|
|
646
|
+
/** Its `iat` is more than an hour ago, or not yet. */
|
|
647
|
+
'too_old' |
|
|
648
|
+
/** It lives longer than an hour, `exp` − `iat`, where its binding carries its keys. */
|
|
649
|
+
'too_long' |
|
|
650
|
+
/** Its `nbf` is still to come. */
|
|
651
|
+
'not_yet_valid' |
|
|
652
|
+
/** Its audience is not this instance alone. */
|
|
653
|
+
'audience';
|
|
654
|
+
declare class WorkloadTokenRefused extends Error {
|
|
655
|
+
readonly reason: WorkloadRefusal;
|
|
656
|
+
constructor(reason: WorkloadRefusal, message: string);
|
|
657
|
+
}
|
|
658
|
+
/** What a token says before anything about it is trusted: enough to find the binding it would match. */
|
|
659
|
+
type DecodedToken = {
|
|
660
|
+
header: Record<string, unknown>;
|
|
661
|
+
claims: Record<string, unknown> & {
|
|
662
|
+
iss: string;
|
|
663
|
+
sub: string;
|
|
664
|
+
exp: number;
|
|
665
|
+
iat: number;
|
|
666
|
+
};
|
|
667
|
+
/**
|
|
668
|
+
* SHA-256 of `header.payload`, exactly as received: what the signature
|
|
669
|
+
* covers, and so the one spelling of the token. Hashing the whole token
|
|
670
|
+
* would not do: an ES256 signature (r, s) has a twin, (r, n − s), that
|
|
671
|
+
* verifies the same claims, so the whole token has two spellings.
|
|
672
|
+
*/
|
|
673
|
+
signingInputHash: Buffer;
|
|
674
|
+
};
|
|
675
|
+
/** A token's parts and claims, checked for shape and types only. Throws `WorkloadTokenRefused('malformed')`. */
|
|
676
|
+
declare function decodeWorkloadToken(token: string): DecodedToken;
|
|
677
|
+
/**
|
|
678
|
+
* Verify a token under an issuer's keys: the signature by jose, with the
|
|
679
|
+
* algorithms fixed and nothing taken from the header but `alg` and `kid`;
|
|
680
|
+
* the issuer exactly; `exp`, `nbf` and `iat` within the tolerance, `iat` at
|
|
681
|
+
* most an hour old; and the audience, this instance's public URL alone.
|
|
682
|
+
* With `maxLifetime`, in seconds, a token whose `exp` is further than that
|
|
683
|
+
* from its `iat` is refused too. With `maxAge: null`, its `iat` may be any
|
|
684
|
+
* age, and its own `exp` alone ends it: a token its platform hands out
|
|
685
|
+
* again for hours, a managed identity's (docs/design/workload-access.md,
|
|
686
|
+
* section 4.2). Returns the verified claims.
|
|
687
|
+
*/
|
|
688
|
+
declare function verifyWorkloadToken(token: string, keys: JSONWebKeySet, expected: {
|
|
689
|
+
issuer: string;
|
|
690
|
+
audience: string;
|
|
691
|
+
now: Date;
|
|
692
|
+
maxLifetime?: number;
|
|
693
|
+
maxAge?: null;
|
|
694
|
+
}): Promise<JWTPayload & DecodedToken['claims']>;
|
|
695
|
+
/**
|
|
696
|
+
* Why a token issued at `iat` may not be exchanged at `now`, both in
|
|
697
|
+
* seconds, or null: issued `maxAge` seconds ago at most, an hour unless
|
|
698
|
+
* said, exactly, and no further ahead than the clock tolerance.
|
|
699
|
+
* Verification and the exchange's commit both ask it.
|
|
700
|
+
*/
|
|
701
|
+
declare function issuedRefusal(iat: number, now: number, maxAge?: number): WorkloadTokenRefused | null;
|
|
702
|
+
/** At most this many keys in a set, fetched or uploaded. */
|
|
703
|
+
declare const MAX_KEYS = 32;
|
|
704
|
+
/** One key of an uploaded set, as an owner sees it: its `kid`, its algorithm, and its RFC 7638 thumbprint. */
|
|
705
|
+
type KeySummary = {
|
|
706
|
+
kid: string | null;
|
|
707
|
+
alg: (typeof WORKLOAD_ALGORITHMS)[number];
|
|
708
|
+
thumbprint: string;
|
|
709
|
+
};
|
|
710
|
+
/**
|
|
711
|
+
* A key set uploaded with a binding, as the binding keeps it: its public
|
|
712
|
+
* keys alone, as canonical JSON, and that JSON's SHA-256, in hex, which
|
|
713
|
+
* stands in the binding where a URL would and so is under its MAC.
|
|
714
|
+
*/
|
|
715
|
+
type UploadedKeys = {
|
|
716
|
+
jwks: string;
|
|
717
|
+
digest: string;
|
|
718
|
+
keys: KeySummary[];
|
|
719
|
+
};
|
|
720
|
+
/** A key set that cannot be uploaded, said so an owner can fix it. */
|
|
721
|
+
declare class KeysInvalid extends Error {
|
|
722
|
+
constructor(message: string);
|
|
723
|
+
}
|
|
724
|
+
/**
|
|
725
|
+
* An issuer's public keys, as uploaded for a binding: a JWKS, `{ "keys": [
|
|
726
|
+
* … ] }`, of RSA keys of 2048 bits or more, for RS256, and P-256 keys, for
|
|
727
|
+
* ES256, each kept with only the members that verify (`kty`, `kid`, `use`,
|
|
728
|
+
* `alg` and the key), in the order of their thumbprints, so that one set
|
|
729
|
+
* however listed has one digest. An RSA key's parameters are checked
|
|
730
|
+
* before jose sees them, since it takes some that verify anything: an
|
|
731
|
+
* exponent of 1 makes every signature its message. Keys for encryption are
|
|
732
|
+
* left out, as from a fetched set; a private or a symmetric key refuses the
|
|
733
|
+
* whole set, since coffre keeps no secret of an issuer's. Throws
|
|
734
|
+
* `KeysInvalid`.
|
|
735
|
+
*/
|
|
736
|
+
declare function uploadedKeys(value: unknown): Promise<UploadedKeys>;
|
|
737
|
+
/** The keys of a set `uploadedKeys` kept, as an owner sees them. */
|
|
738
|
+
declare function keySummaries(jwks: string): KeySummary[];
|
|
739
|
+
//#endregion
|
|
740
|
+
//#region src/identity/proofs.d.ts
|
|
741
|
+
/**
|
|
742
|
+
* A platform's proof held to a service's bindings (docs/design/0.16.md, "A
|
|
743
|
+
* workload signing in"). The app verifies a token's signature, or asks AWS,
|
|
744
|
+
* since only it reaches the platform; everything else read the binding's
|
|
745
|
+
* row, which only the vault can trust. So the vault decides it, on its own
|
|
746
|
+
* rows and its own clock, with these functions: rows and claims in, a
|
|
747
|
+
* binding or a refusal's word out. No I/O, and no clock but the one passed
|
|
748
|
+
* in, in milliseconds.
|
|
749
|
+
*
|
|
750
|
+
* Example: Ada's `deploy` service has two GitHub bindings on
|
|
751
|
+
* `token.actions.githubusercontent.com`, one for `main` made in March and
|
|
752
|
+
* one for every branch made in May. A run on `main` matches both; the
|
|
753
|
+
* March one, the oldest, issues its credential, with the scope its maker
|
|
754
|
+
* gave it. A run on `feature/x` matches May's alone.
|
|
755
|
+
*/
|
|
756
|
+
/**
|
|
757
|
+
* Why a proof is refused, in the vault's words. `no_match`: no binding of
|
|
758
|
+
* the service takes it. `audience`, `expired`, `too_old`, `malformed`: the
|
|
759
|
+
* token is not for this instance or this key, is past its time, or breaks
|
|
760
|
+
* its profile's rule. `unknown_signer`: a binding carries its keys, and they
|
|
761
|
+
* lack the one the token names.
|
|
762
|
+
*/
|
|
763
|
+
type ExchangeRefusal = 'no_match' | 'audience' | 'expired' | 'too_old' | 'malformed' | 'unknown_signer';
|
|
764
|
+
type ExchangeRefused = {
|
|
765
|
+
refused: ExchangeRefusal;
|
|
766
|
+
};
|
|
767
|
+
/** A trust binding as a decision reads it: the columns of its row that say what it takes. */
|
|
768
|
+
type ProofBinding = {
|
|
769
|
+
id: string;
|
|
770
|
+
profile: string;
|
|
771
|
+
issuer: string;
|
|
772
|
+
/** Where its issuer's keys are fetched from, or `sha256:<hex>` of those it carries (`CARRIED`). */
|
|
773
|
+
jwksUri: string;
|
|
774
|
+
/** The keys it carries, a JWKS as JSON: null when they are fetched. */
|
|
775
|
+
jwks: string | null;
|
|
776
|
+
/** JSON, sorted by claim name (`canonicalClaims`). */
|
|
777
|
+
claims: string;
|
|
778
|
+
/** Canonical JSON (`policyText`): null on a binding that issues a CI run's token, which no session is made from. */
|
|
779
|
+
policy: string | null;
|
|
780
|
+
createdAt: Date;
|
|
781
|
+
};
|
|
782
|
+
/** A binding's `jwks_uri` when it carries its issuer's keys: the SHA-256 of those keys, where a fetched set's URL would be. */
|
|
783
|
+
declare const CARRIED = "sha256:";
|
|
784
|
+
/**
|
|
785
|
+
* The keys a token was verified under, as the app says: its issuer, and
|
|
786
|
+
* their address, the URL it fetched them from. For a binding that carries
|
|
787
|
+
* its keys the address is theirs, `sha256:<hex>`, and the vault verifies the
|
|
788
|
+
* signature itself (`signatureRefusal`).
|
|
789
|
+
*/
|
|
790
|
+
type VerifiedUnder = {
|
|
791
|
+
issuer: string;
|
|
792
|
+
jwksUri: string;
|
|
793
|
+
};
|
|
794
|
+
/**
|
|
795
|
+
* What a proof is traded for: a CI run's five-minute token (`run`), from a
|
|
796
|
+
* binding with no policy, or a workload's session bound to a key
|
|
797
|
+
* (`session`), from one with a policy.
|
|
798
|
+
*/
|
|
799
|
+
type ProofFor = {
|
|
800
|
+
kind: 'run';
|
|
801
|
+
} | {
|
|
802
|
+
kind: 'session';
|
|
803
|
+
jkt: string;
|
|
804
|
+
};
|
|
805
|
+
/** A token's claims and the hash of what was signed, or `malformed`. */
|
|
806
|
+
declare function readIdToken(token: string): DecodedToken | ExchangeRefused;
|
|
807
|
+
/** A binding's policy as its row holds it: null for none, undefined for one that does not read as a policy, which takes nothing. */
|
|
808
|
+
declare function policyOf(binding: Pick<ProofBinding, 'policy'>): BindingPolicy | null | undefined;
|
|
809
|
+
/** Whether a binding issues what a proof is traded for: a CI run's token from a bearer profile with no policy, a session from an ID-token profile with one. */
|
|
810
|
+
declare function issues(binding: Pick<ProofBinding, 'profile' | 'policy'>, wanted: ProofFor['kind']): boolean;
|
|
811
|
+
/** The audience a token names, alone; null for none, or several. */
|
|
812
|
+
declare function soleAudience(aud: unknown): string | null;
|
|
813
|
+
/**
|
|
814
|
+
* The audiences a binding takes: this instance's URL for a CI run's; for a
|
|
815
|
+
* session's, its policy's, the session's key or its profile's
|
|
816
|
+
* (`expectedAudiences`). None for one whose policy does not read.
|
|
817
|
+
*/
|
|
818
|
+
declare function audiencesOf(binding: Pick<ProofBinding, 'profile' | 'policy'>, publicUrl: string, wanted: ProofFor): string[];
|
|
819
|
+
/**
|
|
820
|
+
* Which audience a token is held to, and the bindings that take it: the
|
|
821
|
+
* token's own if some binding takes it, otherwise the instance's, 0.14's
|
|
822
|
+
* rule. A token none takes is refused `audience` once its times are checked.
|
|
823
|
+
*/
|
|
824
|
+
declare function audienceTried<B extends ProofBinding>(aud: unknown, bindings: readonly B[], publicUrl: string, wanted: ProofFor): {
|
|
825
|
+
audience: string;
|
|
826
|
+
taking: B[];
|
|
827
|
+
};
|
|
828
|
+
/**
|
|
829
|
+
* A token's times on the vault's clock, `now` in milliseconds, each within
|
|
830
|
+
* the clock tolerance, as 0.14 held them: not before its `nbf`, to jose's
|
|
831
|
+
* whole second; before its `exp`, to the millisecond, as 0.14's exchange
|
|
832
|
+
* checked it again; issued `maxAge` seconds ago at most (an hour,
|
|
833
|
+
* or any age for a token its platform hands out again), and, where a binding
|
|
834
|
+
* carries its keys, living `maxLifetime` seconds at most.
|
|
835
|
+
*/
|
|
836
|
+
declare function timesRefusal(claims: DecodedToken['claims'], now: number, { maxAge, maxLifetime }?: {
|
|
837
|
+
maxAge?: number | null;
|
|
838
|
+
maxLifetime?: number | null;
|
|
839
|
+
}): ExchangeRefusal | null;
|
|
840
|
+
/** The oldest of `bindings` whose every claim the token carries (`differingClaims`), in the order the bindings' index reads them. */
|
|
841
|
+
declare function oldestMatching<B extends Pick<ProofBinding, 'id' | 'profile' | 'claims' | 'createdAt'>>(bindings: readonly B[], claims: Record<string, unknown>): B | null;
|
|
842
|
+
/** Why a token its binding matched still breaks its profile's own rule (`PROFILE_RULES`: Azure's version, Kubernetes' subject), or null. */
|
|
843
|
+
declare function profileRefusal(binding: Pick<ProofBinding, 'profile' | 'issuer' | 'claims'>, policy: BindingPolicy, claims: Record<string, unknown>): 'malformed' | null;
|
|
844
|
+
/**
|
|
845
|
+
* Whether a proof is spent once it is traded, by the SHA-256 of what was
|
|
846
|
+
* signed: a CI run's token always; a session's token unless it names the
|
|
847
|
+
* session's key, which works for no other, or its platform hands the same
|
|
848
|
+
* one out again (`REPEATING_PROFILES`), which spending would refuse.
|
|
849
|
+
*/
|
|
850
|
+
declare function spends(binding: Pick<ProofBinding, 'profile'>, policy: BindingPolicy | null, wanted: ProofFor['kind']): boolean;
|
|
851
|
+
/**
|
|
852
|
+
* A session's hard end, in milliseconds: the earliest of its binding's
|
|
853
|
+
* `sessionHours` after `at`, where its profile has them (24 unless said),
|
|
854
|
+
* and, unless the token names the session's key, the token's own `exp`, so
|
|
855
|
+
* that a copy of it buys no more than the platform's lifetime. `exp` is in
|
|
856
|
+
* seconds, null for a proof that is no token. A session whose end is not
|
|
857
|
+
* after `at` is refused `expired`.
|
|
858
|
+
*/
|
|
859
|
+
declare function hardEnd(binding: Pick<ProofBinding, 'profile'>, policy: BindingPolicy, at: number, exp: number | null): number;
|
|
860
|
+
/**
|
|
861
|
+
* Why a session is refused at its sign-in, from its binding's policy and the
|
|
862
|
+
* request's address: the deployment lets no binding list reads (`noReads`)
|
|
863
|
+
* and this one does, or it names its sources and the request came from
|
|
864
|
+
* outside them, or from nowhere the app could tell. Both are `no_match`, as
|
|
865
|
+
* the design's refusals have it; 0.14 answered the second `source`.
|
|
866
|
+
*/
|
|
867
|
+
declare function sessionRefusal(policy: BindingPolicy, ip: string | null, { noReads }: {
|
|
868
|
+
noReads: boolean;
|
|
869
|
+
}): 'no_match' | null;
|
|
870
|
+
/** An ID token held to a service's bindings: the binding it is traded at, its claims and policy, and the hash it spends, if any. */
|
|
871
|
+
type IdTokenMatch<B extends ProofBinding> = {
|
|
872
|
+
binding: B;
|
|
873
|
+
policy: BindingPolicy | null;
|
|
874
|
+
claims: DecodedToken['claims'];
|
|
875
|
+
spends: Buffer | null;
|
|
876
|
+
};
|
|
877
|
+
/**
|
|
878
|
+
* An ID token whose signature verified under `under`, held to the
|
|
879
|
+
* service's live bindings, in 0.14's order:
|
|
880
|
+
*
|
|
881
|
+
* 1. of the bindings that issue what it is traded for (`issues`), those
|
|
882
|
+
* on its issuer under the keys it was verified under;
|
|
883
|
+
* 2. the audience tried, and the bindings that take it (`audienceTried`);
|
|
884
|
+
* 3. its times (`timesRefusal`): any age for a token its platform hands
|
|
885
|
+
* out again, where a binding that takes it is of such a platform, and
|
|
886
|
+
* an hour's lifetime at most under keys a binding carries;
|
|
887
|
+
* 4. that audience, the token's own, alone;
|
|
888
|
+
* 5. the oldest whose claims match (`oldestMatching`);
|
|
889
|
+
* 6. an hour's age after all, if the binding that matched is of a
|
|
890
|
+
* platform that hands out no token twice;
|
|
891
|
+
* 7. its profile's own rule (`profileRefusal`).
|
|
892
|
+
*
|
|
893
|
+
* `bindings` are the sealed rows the read found: a decision that picks the
|
|
894
|
+
* oldest of several refuses before this if any row it read is not the
|
|
895
|
+
* vault's, since one passed over would let a later one answer.
|
|
896
|
+
*/
|
|
897
|
+
declare function matchIdToken<B extends ProofBinding>(token: DecodedToken, bindings: readonly B[], { under, publicUrl, wanted, now }: {
|
|
898
|
+
under: VerifiedUnder;
|
|
899
|
+
publicUrl: string;
|
|
900
|
+
wanted: ProofFor;
|
|
901
|
+
now: number;
|
|
902
|
+
}): IdTokenMatch<B> | ExchangeRefused;
|
|
903
|
+
/**
|
|
904
|
+
* Whether a token's signature verifies under keys a binding carries, a JWKS
|
|
905
|
+
* as its row holds it: null if it does, `unknown_signer` when the set lacks
|
|
906
|
+
* the key the token names, and `malformed` for any other failure, a
|
|
907
|
+
* signature that does not verify under it included. The algorithms are
|
|
908
|
+
* fixed, and nothing is taken from the header but `alg` and `kid`; a set
|
|
909
|
+
* with several keys the header could name tries each. A token that does
|
|
910
|
+
* not read as one (`readIdToken`), an unencoded payload's included, is
|
|
911
|
+
* `malformed` before any key is tried. It checks no claim: the times and
|
|
912
|
+
* the audience are `matchIdToken`'s.
|
|
913
|
+
*/
|
|
914
|
+
declare function signatureRefusal(token: string, jwks: string): Promise<'unknown_signer' | 'malformed' | null>;
|
|
915
|
+
/**
|
|
916
|
+
* The claims of the run a credential was issued for, as its issuer stated
|
|
917
|
+
* them: those that say which run, each bounded, in the exchange's entry and
|
|
918
|
+
* the credential's row, so that a read leads back to its run. What the
|
|
919
|
+
* issuer says, not proof of which run sent the request.
|
|
920
|
+
*/
|
|
921
|
+
declare const RUN_CLAIMS: readonly ["sub", "jti", "actor", "event_name", "ref", "base_ref", "head_ref", "sha", "repository", "repository_id", "run_id", "run_attempt", "workflow_ref", "job_workflow_ref", "job_workflow_sha", "environment", "project_path", "project_id", "namespace_id", "pipeline_id", "pipeline_source", "job_id", "kubernetes.io.pod.name"];
|
|
922
|
+
declare const MAX_RUN_CLAIM = 256;
|
|
923
|
+
/** The run's claims, as the issuer stated them: each a string of 256 characters at most, or a finite number. */
|
|
924
|
+
declare function runClaims(claims: Record<string, unknown>): Record<string, string | number>;
|
|
925
|
+
//#endregion
|
|
926
|
+
//#region src/identity/aws.d.ts
|
|
927
|
+
/**
|
|
928
|
+
* The `aws` proof's answer, held to a service's bindings
|
|
929
|
+
* (docs/design/workload-access.md, section 4.3; docs/design/0.16.md, "A
|
|
930
|
+
* workload signing in"). The app checks the request the workload signed,
|
|
931
|
+
* a `GetCallerIdentity` naming this instance and the session's key, sends
|
|
932
|
+
* it to STS, and hands the vault STS's answer, on its word: which account,
|
|
933
|
+
* and whose credentials. The vault says which binding that is.
|
|
934
|
+
*/
|
|
935
|
+
/** What STS says signed the request: `GetCallerIdentityResult`'s three fields. */
|
|
936
|
+
type CallerIdentity = {
|
|
937
|
+
account: string;
|
|
938
|
+
arn: string;
|
|
939
|
+
userId: string;
|
|
940
|
+
};
|
|
941
|
+
/** An assumed role's session, as a binding names its role: by account and the role's unique ID, which a role made again under the same name does not keep. */
|
|
942
|
+
type AwsIdentity = {
|
|
943
|
+
account: string;
|
|
944
|
+
roleId: string;
|
|
945
|
+
arn: string;
|
|
946
|
+
role: string;
|
|
947
|
+
session: string;
|
|
948
|
+
};
|
|
949
|
+
/**
|
|
950
|
+
* The role a caller's identity is a session of, or why none: an account's
|
|
951
|
+
* root, a federated user and an IAM user are `no_match`, since each means a
|
|
952
|
+
* long-lived key on disk, which a workload does not hold, and so is any
|
|
953
|
+
* other partition than `aws`. An answer whose account, ARN and user ID
|
|
954
|
+
* disagree is no answer STS gives: `malformed` (0.14's server took it as
|
|
955
|
+
* STS unavailable).
|
|
956
|
+
*/
|
|
957
|
+
declare function assumedRole(identity: CallerIdentity): AwsIdentity | ExchangeRefused;
|
|
958
|
+
/** The claims an `aws` binding matches, as the proof makes them. */
|
|
959
|
+
declare function awsClaims(identity: AwsIdentity): {
|
|
960
|
+
account: string;
|
|
961
|
+
role_id: string;
|
|
962
|
+
};
|
|
963
|
+
/**
|
|
964
|
+
* STS's answer held to a service's bindings: the oldest `aws` binding with
|
|
965
|
+
* a policy that names its role's account and unique ID, and the claims the
|
|
966
|
+
* session's entry gives, the role's ARN and session name with them. The
|
|
967
|
+
* request named the session's key and this instance under its signature,
|
|
968
|
+
* so nothing is spent, and nothing but its binding's hours ends the
|
|
969
|
+
* session early.
|
|
970
|
+
*/
|
|
971
|
+
declare function matchAwsAnswer<B extends ProofBinding>(answer: CallerIdentity, bindings: readonly B[]): {
|
|
972
|
+
binding: B;
|
|
973
|
+
claims: Record<string, string>;
|
|
974
|
+
} | ExchangeRefused;
|
|
975
|
+
//#endregion
|
|
976
|
+
//#region src/identity/dpop.d.ts
|
|
977
|
+
/** How far a proof's `iat` may be from now: the nonce, not the clock, is what makes a proof fresh. */
|
|
978
|
+
declare const PROOF_SKEW_SECONDS = 300;
|
|
979
|
+
/** Why a proof was refused, which a 401's `reason` names under `error="invalid_dpop_proof"`. */
|
|
980
|
+
type ProofReason = 'malformed' | 'key' | 'jkt' | 'signature' | 'htm' | 'htu' | 'ath' | 'req' | 'iat';
|
|
981
|
+
type ProofRefusal = {
|
|
982
|
+
ok: false;
|
|
983
|
+
reason: ProofReason;
|
|
984
|
+
message: string;
|
|
985
|
+
};
|
|
986
|
+
/** A proof whose shape, key and claims hold: what `verifyProof` checks against the request. */
|
|
987
|
+
type ParsedProof = {
|
|
988
|
+
ok: true;
|
|
989
|
+
jwk: PublicJwk;
|
|
990
|
+
claims: ProofClaims;
|
|
991
|
+
/** The headers it signs, in `hdr`'s order; null for a proof that signs no content. */
|
|
992
|
+
hdr: readonly string[] | null;
|
|
993
|
+
signingInput: string;
|
|
994
|
+
signature: Uint8Array;
|
|
995
|
+
};
|
|
996
|
+
/** A proof that holds for its request: its key's thumbprint, and what the gate checks. */
|
|
997
|
+
type VerifiedProof = {
|
|
998
|
+
ok: true;
|
|
999
|
+
jkt: string;
|
|
1000
|
+
jti: string;
|
|
1001
|
+
nonce: string | null;
|
|
1002
|
+
iat: number;
|
|
1003
|
+
hdr: readonly string[] | null;
|
|
1004
|
+
};
|
|
1005
|
+
/** What the request says a proof must sign. */
|
|
1006
|
+
type ProofExpectation = {
|
|
1007
|
+
/** The request's method and URL, as received: `Request.method`, which the Fetch API has normalized as `fetchMethod` does. */
|
|
1008
|
+
method: string;
|
|
1009
|
+
url: string | URL;
|
|
1010
|
+
/** The session row's `jkt`; none at the exchange, where the proof's key becomes the session's. */
|
|
1011
|
+
jkt?: string;
|
|
1012
|
+
/** The session token the request carries, which `ath` signs; none at the exchange. */
|
|
1013
|
+
token?: string;
|
|
1014
|
+
/** The request's headers and its body's digest, which `hdr` and `req` sign: for a request coffre forwards. */
|
|
1015
|
+
content?: {
|
|
1016
|
+
headers: Headers;
|
|
1017
|
+
body: string;
|
|
1018
|
+
};
|
|
1019
|
+
/** Seconds `iat` may be from now: 300 unless said, 60 at the exchange. */
|
|
1020
|
+
skewSeconds?: number;
|
|
1021
|
+
/** Now, in milliseconds, for tests. */
|
|
1022
|
+
now?: number;
|
|
1023
|
+
};
|
|
1024
|
+
/** Steps 1 to 3: the proof's shape, its key's and its claims', with no I/O. */
|
|
1025
|
+
declare function parseProof(proof: string): ParsedProof | ProofRefusal;
|
|
1026
|
+
/**
|
|
1027
|
+
* Steps 5 and 6: the proof against its request, `parseProof`'s first when
|
|
1028
|
+
* given a string. Nothing here reads a store, so the gate (step 7) still
|
|
1029
|
+
* decides whether this `jti` was seen.
|
|
1030
|
+
*/
|
|
1031
|
+
declare function verifyProof(proof: string | ParsedProof, expect: ProofExpectation): Promise<VerifiedProof | ProofRefusal>;
|
|
1032
|
+
/** A count a request asks the gate for: the requests under `key` in the last `windowMs`, at most `most`. */
|
|
1033
|
+
type GateCount = {
|
|
1034
|
+
key: string;
|
|
1035
|
+
windowMs: number;
|
|
1036
|
+
most: number;
|
|
1037
|
+
};
|
|
1038
|
+
/** What the gate answers a request: its nonce on success, or why not. */
|
|
1039
|
+
type GateAdmission = {
|
|
1040
|
+
ok: true;
|
|
1041
|
+
nonce: string;
|
|
1042
|
+
} | {
|
|
1043
|
+
ok: false;
|
|
1044
|
+
reason: 'use_dpop_nonce';
|
|
1045
|
+
nonce: string;
|
|
1046
|
+
} | {
|
|
1047
|
+
ok: false;
|
|
1048
|
+
reason: 'replayed' | 'overloaded';
|
|
1049
|
+
} |
|
|
1050
|
+
/** `first`: the first refusal of this key in its window, which alerts. */
|
|
1051
|
+
{
|
|
1052
|
+
ok: false;
|
|
1053
|
+
reason: 'limit';
|
|
1054
|
+
key: string;
|
|
1055
|
+
retryAfterMs: number;
|
|
1056
|
+
first: boolean;
|
|
1057
|
+
};
|
|
1058
|
+
/**
|
|
1059
|
+
* One workload's gate (section 5.2): a Durable Object on Workers, an object
|
|
1060
|
+
* in the process on Node. Its nonces are epochs: a gate accepts the current
|
|
1061
|
+
* and the previous one, remembers each epoch's `jti`s, and draws a new epoch
|
|
1062
|
+
* when it starts, so a restart forgets nothing that matters. It decides no
|
|
1063
|
+
* one's access: freezes, revocations and grants are the database's.
|
|
1064
|
+
*/
|
|
1065
|
+
interface Gate {
|
|
1066
|
+
/** Its current nonce, `g<n>.<epoch>`, for an answer that admits no proof: the exchange's `DPoP-Nonce`. */
|
|
1067
|
+
nonce(): Promise<string>;
|
|
1068
|
+
/**
|
|
1069
|
+
* Replay and nonce, for a request that carries a proof (a Cloudflare call
|
|
1070
|
+
* carries none, and has counts only); then, in the same call, every count
|
|
1071
|
+
* the request asks for. A nonce of an epoch gone gets `use_dpop_nonce`; a
|
|
1072
|
+
* proof with none never reaches the gate, and gets `nonce()`'s.
|
|
1073
|
+
*/
|
|
1074
|
+
admit(request: {
|
|
1075
|
+
replay?: {
|
|
1076
|
+
session: string;
|
|
1077
|
+
jti: string;
|
|
1078
|
+
nonce: string;
|
|
1079
|
+
};
|
|
1080
|
+
counts?: readonly GateCount[];
|
|
1081
|
+
}): Promise<GateAdmission>;
|
|
1082
|
+
}
|
|
1083
|
+
//#endregion
|
|
1084
|
+
//#region src/identity/profiles.d.ts
|
|
1085
|
+
/**
|
|
1086
|
+
* What each platform's binding and tokens must say beyond the claims a
|
|
1087
|
+
* binding names (docs/design/workload-access.md, section 4.2). Core holds
|
|
1088
|
+
* the rules every profile shares: the required claims, the issuers that
|
|
1089
|
+
* force a profile, the policy's fields. These are each platform's own:
|
|
1090
|
+
* the shape of the IDs it issues, which issuer goes with which, and what a
|
|
1091
|
+
* token of it says that its binding cannot.
|
|
1092
|
+
*
|
|
1093
|
+
* A binding names IDs the platform never reuses, so each is checked for
|
|
1094
|
+
* the shape the platform gives it: a name in its place is refused, since a
|
|
1095
|
+
* name can be taken again after its owner is gone.
|
|
1096
|
+
*/
|
|
1097
|
+
type ProfileRules = {
|
|
1098
|
+
/** At binding time, after `checkBinding` and `checkPolicy`. Throws `BindingInvalid`. */
|
|
1099
|
+
binding(binding: CheckedBinding, policy: BindingPolicy): void;
|
|
1100
|
+
/** At the exchange, once the token verified and matched its binding's claims: why it is still refused, or null. */
|
|
1101
|
+
token(claims: Record<string, unknown>, binding: {
|
|
1102
|
+
issuer: string;
|
|
1103
|
+
claims: BindingClaims;
|
|
1104
|
+
policy: BindingPolicy;
|
|
1105
|
+
}): string | null;
|
|
1106
|
+
};
|
|
1107
|
+
declare const PROFILE_RULES: { readonly [P in WorkloadProfile]?: ProfileRules; };
|
|
1108
|
+
/**
|
|
1109
|
+
* The audiences a token of a binding may name, the first the one its SDK
|
|
1110
|
+
* asks for: the session's key, `<publicUrl>#jkt=<thumbprint>`, for the
|
|
1111
|
+
* platforms whose caller picks the audience, and `?jkt=` for one that
|
|
1112
|
+
* refuses a `#` in it (section 4.2); the exact audience of a platform that
|
|
1113
|
+
* fixes it; this instance's URL for every other.
|
|
1114
|
+
*/
|
|
1115
|
+
declare function expectedAudiences(profile: WorkloadProfile, policy: BindingPolicy, expected: {
|
|
1116
|
+
publicUrl: string;
|
|
1117
|
+
jkt: string;
|
|
1118
|
+
}): string[];
|
|
1119
|
+
//#endregion
|
|
1120
|
+
//#region src/identity/signin/sealed.d.ts
|
|
1121
|
+
/**
|
|
1122
|
+
* Derive a purpose-bound key from one of coffre's existing 32-byte secrets.
|
|
1123
|
+
*
|
|
1124
|
+
* HKDF with a distinct `info` string gives a key that is independent of the
|
|
1125
|
+
* source for every practical purpose, so the sign-in cookie needs no new
|
|
1126
|
+
* secret to provision and a leak of one derived key says nothing about the
|
|
1127
|
+
* others.
|
|
1128
|
+
*/
|
|
1129
|
+
declare function deriveKey(secret: Uint8Array, purpose: string): Buffer;
|
|
1130
|
+
/**
|
|
1131
|
+
* Encrypt a small JSON value for a round trip through the browser.
|
|
1132
|
+
*
|
|
1133
|
+
* AES-256-GCM authenticates as well as hides, so a tampered or forged value
|
|
1134
|
+
* fails to open rather than decoding into something else. The expiry sits
|
|
1135
|
+
* inside the ciphertext, which keeps an old cookie from being replayed past
|
|
1136
|
+
* it even by a client that ignores Max-Age.
|
|
1137
|
+
*/
|
|
1138
|
+
declare function seal(key: Uint8Array, value: unknown, ttlSeconds: number, now?: number): string;
|
|
1139
|
+
/** The sealed value, or null when it is malformed, forged, tampered with or expired. */
|
|
1140
|
+
declare function unseal<T>(key: Uint8Array, sealed: string | undefined | null, now?: number): T | null;
|
|
1141
|
+
//#endregion
|
|
1142
|
+
//#region src/identity/tokens.d.ts
|
|
1143
|
+
/**
|
|
1144
|
+
* Bearer credentials coffre issues itself: browser sessions, CLI sessions,
|
|
1145
|
+
* service tokens, personal tokens, which act as the person who made
|
|
1146
|
+
* them within the scope they named, and handles, which reach nothing but
|
|
1147
|
+
* the credential proxy (`@coffre/server/plugins/credential-proxy`): the
|
|
1148
|
+
* placeholder a person's app holds in place of a secret's value. And a
|
|
1149
|
+
* workload's sessions, which are bound to its key and useless without a
|
|
1150
|
+
* proof it signs (docs/design/workload-access.md, section 5), and the
|
|
1151
|
+
* enrollment codes CI mints for platforms that sign nothing, which are no
|
|
1152
|
+
* credential at all: they buy a session at `/api/auth/workload`, and every
|
|
1153
|
+
* other route refuses one.
|
|
1154
|
+
*
|
|
1155
|
+
* A token is a kind prefix and 32 random bytes, e.g.
|
|
1156
|
+
* `coffre_cli_Qm9Y...`. The prefix tells a person (or a secret scanner) what a
|
|
1157
|
+
* leaked string is; the database stores only its SHA-256, which is enough
|
|
1158
|
+
* for lookups and useless to anyone who reads the table. A plain hash is the
|
|
1159
|
+
* right tool here, unlike for passwords: 256 bits of randomness leave nothing
|
|
1160
|
+
* to brute-force.
|
|
1161
|
+
*/
|
|
1162
|
+
type CredentialKind = 'browser' | 'cli' | 'service' | 'personal' | 'handle' | 'workload';
|
|
1163
|
+
/**
|
|
1164
|
+
* What a token's prefix says it is: a credential, an enrollment code, or
|
|
1165
|
+
* an MCP client's tokens: an access token, good at `/mcp` alone, and the
|
|
1166
|
+
* refresh token it gets the next one with, good at the token endpoint alone
|
|
1167
|
+
* (docs/design/0.16.md, "MCP connections").
|
|
1168
|
+
*/
|
|
1169
|
+
type TokenKind = CredentialKind | 'enrollment' | 'mcp' | 'mcp-refresh';
|
|
1170
|
+
declare function generateToken(kind: TokenKind): string;
|
|
1171
|
+
/** Whether a string has the shape of a coffre token, before any lookup. */
|
|
1172
|
+
declare function isCoffreToken(value: string): boolean;
|
|
1173
|
+
/**
|
|
1174
|
+
* The kind a token's prefix says, before any lookup. Its hash covers the
|
|
1175
|
+
* prefix, so a token found under its hash is the kind it says.
|
|
1176
|
+
*/
|
|
1177
|
+
declare function tokenKind(token: string): TokenKind | null;
|
|
1178
|
+
declare function hashToken(token: string): Buffer;
|
|
1179
|
+
/**
|
|
1180
|
+
* Enough of a token to recognize it in a list, never enough to use it: the
|
|
1181
|
+
* kind prefix and the last four characters. The prefix is matched rather than
|
|
1182
|
+
* cut at the last underscore, because base64url uses `_` too.
|
|
1183
|
+
*/
|
|
1184
|
+
declare function tokenHint(token: string): string;
|
|
1185
|
+
//#endregion
|
|
1186
|
+
//#region src/identity/verifier.d.ts
|
|
1187
|
+
type AccessClaims = JWTPayload & {
|
|
1188
|
+
email?: unknown;
|
|
1189
|
+
common_name?: unknown;
|
|
1190
|
+
};
|
|
1191
|
+
/** The team's keys could not be fetched, or are no key set: no assertion can be checked, which is not the caller's fault. */
|
|
1192
|
+
declare class AccessKeysUnavailable extends Error {
|
|
1193
|
+
constructor(message: string, options?: {
|
|
1194
|
+
cause?: unknown;
|
|
1195
|
+
});
|
|
1196
|
+
}
|
|
1197
|
+
/** How the verifier fetches the team's key set, and what time it is. */
|
|
1198
|
+
type AccessVerifierIo = {
|
|
1199
|
+
/** GET a JSON document; throws when it cannot. The global `fetch` unless given. */
|
|
1200
|
+
json?: (url: URL) => Promise<unknown>;
|
|
1201
|
+
now?: () => number;
|
|
1202
|
+
};
|
|
1203
|
+
/**
|
|
1204
|
+
* Verifies Cloudflare Access JWTs.
|
|
1205
|
+
*
|
|
1206
|
+
* Signature and claim verification of the token Access sends with each
|
|
1207
|
+
* request. The team's keys are fetched when first needed, used for ten
|
|
1208
|
+
* minutes, and fetched again sooner for a key they lack, at most every 30
|
|
1209
|
+
* seconds. The verifier lives as long as its configuration (an isolate's,
|
|
1210
|
+
* on Workers) and keeps settled values only, never a fetch in flight
|
|
1211
|
+
* (AGENTS.md, "What an isolate keeps"): concurrent requests that find no
|
|
1212
|
+
* key set each fetch their own, and the last to land is kept. The 30
|
|
1213
|
+
* seconds count from the last refresh started, landed or not, and are
|
|
1214
|
+
* taken before it starts: of a burst of assertions naming a key the set
|
|
1215
|
+
* lacks, one fetches, and the others are refused as the key unknown.
|
|
1216
|
+
*/
|
|
1217
|
+
declare class AccessIdentityVerifier implements IdentityVerifier {
|
|
1218
|
+
#private;
|
|
1219
|
+
constructor(config: AccessVerifierConfig, io?: AccessVerifierIo);
|
|
1220
|
+
verify(token: string): Promise<Principal>;
|
|
1221
|
+
}
|
|
1222
|
+
/**
|
|
1223
|
+
* Derive the caller from verified claims.
|
|
1224
|
+
*
|
|
1225
|
+
* Order matters. A service token is identified by `common_name` and carries an
|
|
1226
|
+
* empty `sub`; an identity token carries both `sub` and `email`. Anything else
|
|
1227
|
+
* is rejected rather than being allowed through as an authenticated caller
|
|
1228
|
+
* with no name -- an audit row with a null actor answers no question worth
|
|
1229
|
+
* asking.
|
|
1230
|
+
*/
|
|
1231
|
+
declare function toPrincipal(claims: AccessClaims): Principal;
|
|
1232
|
+
//#endregion
|
|
1233
|
+
export { audiencesOf as $, google as $t, VerifiedProof as A, Auth as At, assumedRole as B, McpConfig as Bt, PROOF_SKEW_SECONDS as C, WorkloadRefusal as Ct, ProofReason as D, keySummaries as Dt, ProofExpectation as E, issuedRefusal as Et, sentTarget$1 as F, ACCESS_JWT_HEADER as Ft, ExchangeRefused as G, SigninConfig as Gt, matchAwsAnswer as H, McpOptions as Ht, thumbprint$1 as I, AccessVerifierConfig as It, ProofBinding as J, WorkloadsConfig as Jt, IdTokenMatch as K, SigninPage as Kt, verifyProof as L, IdentityVerifier as Lt, canonicalRequest as M, SigninOptions as Mt, fetchMethod$1 as N, cloudflareAccess as Nt, ProofRefusal as O, uploadedKeys as Ot, parseProof as P, signin as Pt, audienceTried as Q, githubApp as Qt, AwsIdentity as R, Principal as Rt, MAX_SIGNED_HEADERS$1 as S, WORKLOAD_ALGORITHMS as St, ProofClaims$1 as T, decodeWorkloadToken as Tt, CARRIED as U, OidcProviderConfig as Ut, awsClaims as V, McpLimits as Vt, ExchangeRefusal as W, RateLimiter as Wt, RUN_CLAIMS as X, defineSignin as Xt, ProofFor as Y, WorkloadsOptions as Yt, VerifiedUnder as Z, github as Zt, expectedAudiences as _, GitHubRepository as _n, KeysInvalid as _t, CredentialKind as a, GitHubSigninProvider as an, profileRefusal as at, GateCount as b, pkcs8Of as bn, MAX_TOKEN_BYTES as bt, hashToken as c, SigninBrand as cn, sessionRefusal as ct, tokenKind as d, SigninProfile as dn, spends as dt, lifetime as en, hardEnd as et, deriveKey as f, SigninProvider as fn, timesRefusal as ft, ProfileRules as g, GitHubAppUnavailable as gn, KeySummary as gt, PROFILE_RULES as h, GitHubAppRepositories as hn, JSONWebKeySet as ht, toPrincipal as i, OidcSigninProvider as in, policyOf as it, canonicalHtu$1 as j, AuthConfig as jt, PublicJwk$1 as k, verifyWorkloadToken as kt, isCoffreToken as l, SigninError as ln, signatureRefusal as lt, unseal as m, GitHubAppOptions as mn, DecodedToken as mt, AccessKeysUnavailable as n, oidc as nn, matchIdToken as nt, TokenKind as o, PendingSignin as on, readIdToken as ot, seal as p, GitHubApp as pn, CLOCK_TOLERANCE_SECONDS as pt, MAX_RUN_CLAIM as q, WorkloadLimits as qt, AccessVerifierIo as r, publicOrigin as rn, oldestMatching as rt, generateToken as s, ProviderOptions as sn, runClaims as st, AccessIdentityVerifier as t, microsoft as tn, issues as tt, tokenHint as u, SigninErrorCode as un, soleAudience as ut, Gate as v, MAX_LISTING_REQUESTS as vn, MAX_KEYS as vt, ParsedProof as w, WorkloadTokenRefused as wt, MAX_PROOF_LENGTH$1 as x, UploadedKeys as xt, GateAdmission as y, TOKEN_MARGIN_MS as yn, MAX_TOKEN_AGE_SECONDS as yt, CallerIdentity as z, GitHubProviderConfig as zt };
|