@coffre/core 0.10.1 → 0.11.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.
@@ -0,0 +1,418 @@
1
+ //#region src/identity/constraints.d.ts
2
+ type Constraints = {
3
+ /** Environments, `<project>/<environment>`. */
4
+ readonly places?: readonly string[];
5
+ /** The credentials, signers, verifiers, tunnels and minters it may reach, by name. */
6
+ readonly credentials?: readonly string[];
7
+ readonly methods?: readonly string[];
8
+ /** Path prefixes, each matching whole segments. */
9
+ readonly paths?: readonly string[];
10
+ };
11
+ /** The most entries in each list. */
12
+ declare const MAX_CONSTRAINTS = 32;
13
+ /** A constraint that does not parse, said so the caller can fix it. */
14
+ declare class ConstraintsInvalid extends Error {
15
+ constructor(message: string);
16
+ }
17
+ /**
18
+ * Constraints as a child asks for them, checked and canonical: each list
19
+ * sorted, without duplicates; methods as Fetch sends them; prefixes absolute,
20
+ * with no trailing slash, escape, `;` or dot segment, and none under
21
+ * another, which it would add nothing to. Throws `ConstraintsInvalid`.
22
+ */
23
+ declare function checkConstraints(input: unknown): Constraints;
24
+ /**
25
+ * What a child holds: what it asked within what its parent holds, list by
26
+ * list, and for paths each prefix of one side that is under one of the
27
+ * other's. A parent with none is a root, which only its scope bounds. Never
28
+ * wider than either: whatever `intersect(a, b)` allows, `a` and `b` allow.
29
+ */
30
+ declare function intersect(parent: Constraints | null, child: Constraints): Constraints;
31
+ /** The constraints as a row's `constraints` column and its MAC hold them: `checkConstraints`'s keys in order. */
32
+ declare function constraintsText(constraints: Constraints): string;
33
+ /**
34
+ * Whether one operation is within the constraints: its place and credential
35
+ * named, and, for one that sends a request upstream, its method and the
36
+ * path of the URL it is about to send, as the WHATWG parser resolved it.
37
+ * An operation with no request to check (`sign`, `verify`, `mint`, the
38
+ * tunnel) is refused wherever methods or paths are limited: a constraint
39
+ * that cannot be checked refuses.
40
+ */
41
+ declare function constraintsAllow(constraints: Constraints | null, operation: {
42
+ place: string;
43
+ credential: string;
44
+ request?: {
45
+ method: string;
46
+ url: string | URL;
47
+ };
48
+ }): boolean;
49
+ //#endregion
50
+ //#region src/identity/workloads.d.ts
51
+ declare const GITHUB_ISSUER = "https://token.actions.githubusercontent.com";
52
+ declare const GITLAB_ISSUER = "https://gitlab.com";
53
+ /**
54
+ * - `github`: a workflow of the repository.
55
+ * - `github-reusable`: a reusable workflow, pinned to one commit, called from
56
+ * one repository at one ref.
57
+ * - `github-reusable-organization`: the same, called from any repository of
58
+ * the organization: an explicit choice, never what a missing claim means.
59
+ * - `gitlab`: a project's pipelines, outside merge requests.
60
+ * - `custom`: any other issuer, by its subject, which the owner vouches for.
61
+ *
62
+ * Then the platforms of docs/design/workload-access.md, section 4, which
63
+ * sign in at `/api/auth/workload` alone, for a key-bound session:
64
+ *
65
+ * - `kubernetes`, `gcp`, `azure`, `fly`, `vercel`: the platform's ID token.
66
+ * - `aws`: a signed `GetCallerIdentity`, bound to the session's key.
67
+ * - `enrollment`: a code CI mints, for platforms that sign nothing.
68
+ * - `cloudflare`: a service binding's `props`, which no request carries.
69
+ */
70
+ type WorkloadProfile = 'github' | 'github-reusable' | 'github-reusable-organization' | 'gitlab' | 'custom' | 'kubernetes' | 'gcp' | 'azure' | 'fly' | 'vercel' | 'aws' | 'enrollment' | 'cloudflare';
71
+ declare const WORKLOAD_PROFILES: readonly WorkloadProfile[];
72
+ /**
73
+ * The profiles `/api/auth/oidc` exchanges for a bearer credential, and only
74
+ * on a binding with no policy: a platform's token bought at that route reads
75
+ * values, so a binding made for a key-bound session, policy and all, is never
76
+ * one it matches. Every binding of another profile carries a policy.
77
+ */
78
+ declare const BEARER_PROFILES: readonly ["github", "github-reusable", "github-reusable-organization", "gitlab", "custom"];
79
+ type BearerProfile = (typeof BEARER_PROFILES)[number];
80
+ /** Whether a binding's profile is one `/api/auth/oidc` takes; it takes the binding only if it has no policy, too. */
81
+ declare function isBearerProfile(profile: string): profile is BearerProfile;
82
+ /** The profiles whose proof is no ID token: their binding's issuer is this URN, which no token names, and its keys none. */
83
+ declare const PROFILE_URNS: {
84
+ readonly aws: "urn:coffre:aws";
85
+ readonly enrollment: "urn:coffre:enrollment";
86
+ readonly cloudflare: "urn:coffre:cloudflare";
87
+ };
88
+ /** The profiles whose proof is a platform's ID token. */
89
+ declare const OIDC_PROFILES: readonly WorkloadProfile[];
90
+ /**
91
+ * Tokens a platform hands out again, the same one to every replica and
92
+ * restart for its lifetime: a managed identity's. Spending one would
93
+ * refuse them, so none is spent: it is a bearer until its own `exp`, which
94
+ * ends the session it makes (section 4.2).
95
+ */
96
+ declare const REPEATING_PROFILES: readonly WorkloadProfile[];
97
+ /** The claims each profile requires; a binding may add more, to narrow it. An `aws` binding's are the role's account and unique ID. */
98
+ declare const REQUIRED_CLAIMS: Record<WorkloadProfile, readonly string[]>;
99
+ /**
100
+ * The events a GitHub binding may trust. The first four are started by
101
+ * someone with write access, at the ref the binding names. The last two
102
+ * can run code nobody reviewed, so the owner opts in to each:
103
+ *
104
+ * - `pull_request` runs the pull request's own code and workflow file, at
105
+ * `refs/pull/<n>/merge`; a binding matches it by the branch it merges
106
+ * into. Forks get no ID token, unless the repository sends write tokens
107
+ * to their pull requests (a setting of private repositories), so this
108
+ * trusts whoever can push a branch to the repository.
109
+ * - `workflow_run` runs the default branch's workflow, but a fork's pull
110
+ * request can start it: the run is as safe as what it does with the
111
+ * code and artifacts of the run that started it.
112
+ *
113
+ * `pull_request_target` and the rest are refused, even when their ref
114
+ * happens to match: they exist to act on anyone's pull request, with the
115
+ * base repository's tokens.
116
+ */
117
+ declare const GITHUB_EVENTS: readonly ["push", "workflow_dispatch", "schedule", "release", "pull_request", "workflow_run"];
118
+ /**
119
+ * What trusting each of the last two events exposes, as the UI, the CLI and
120
+ * the approval page say it when one is chosen.
121
+ */
122
+ declare const EVENT_EXPOSURE: Readonly<Record<string, string>>;
123
+ /** Pipelines that run the project's own code, at its own ref: never a merge request's. */
124
+ declare const GITLAB_PIPELINE_SOURCES: readonly ["push", "web", "schedule"];
125
+ /** At most this many live bindings per service, and claims per binding. */
126
+ declare const MAX_BINDINGS = 16;
127
+ declare const MAX_CLAIMS = 16;
128
+ /** The longest claim value, in bytes. */
129
+ declare const MAX_CLAIM_BYTES = 256;
130
+ /** A claim a binding names: one value, or, for what started the run, any of several. */
131
+ type ClaimValue = string | string[];
132
+ type BindingClaims = Record<string, ClaimValue>;
133
+ /**
134
+ * What makes a binding, checked: its profile, its issuer, and its claims,
135
+ * sorted. The issuer is a URL coffre may fetch, unless the binding carries
136
+ * its keys (`uploaded`): then coffre fetches nothing, and it is any string,
137
+ * matched exactly, such as a private Kubernetes cluster's.
138
+ */
139
+ type CheckedBinding = {
140
+ profile: WorkloadProfile;
141
+ issuer: string;
142
+ claims: BindingClaims;
143
+ };
144
+ /** A binding that breaks a rule, said so an owner can fix it. */
145
+ declare class BindingInvalid extends Error {
146
+ constructor(message: string);
147
+ }
148
+ /** Google's, for every `gcp` binding. */
149
+ declare const GOOGLE_ISSUER = "https://accounts.google.com";
150
+ /**
151
+ * The issuer a profile means when none is given: github.com's, gitlab.com's
152
+ * or Google's, or the URN of a profile that is no ID token. A GitHub
153
+ * Enterprise Server, a self-managed GitLab, a cluster, a tenant or a team
154
+ * names its own.
155
+ */
156
+ declare function defaultIssuer(profile: WorkloadProfile): string | null;
157
+ /** The longest issuer a binding with uploaded keys names, in bytes. */
158
+ declare const MAX_ISSUER_BYTES = 400;
159
+ /**
160
+ * Check a binding against its profile, and return it as stored: the
161
+ * issuer as given, the claims sorted by name. With `uploaded`, the binding
162
+ * carries its issuer's keys, and its issuer need not be a URL coffre can
163
+ * fetch. Throws `BindingInvalid`.
164
+ */
165
+ declare function checkBinding(input: {
166
+ profile: string;
167
+ issuer: string | null;
168
+ claims: Record<string, unknown>;
169
+ }, options?: {
170
+ allowLoopback?: boolean;
171
+ uploaded?: boolean;
172
+ }): CheckedBinding;
173
+ /** A claim's values, one or several. */
174
+ declare function claimValues(value: ClaimValue | undefined): string[];
175
+ /**
176
+ * A claim of a token, by the name a binding gives it: a top-level claim, or
177
+ * one nested in objects, its path joined by dots. A key may hold dots of
178
+ * its own, as Kubernetes' `kubernetes.io` does, so a name is read every way
179
+ * its dots can split it, and names a claim only when exactly one of those
180
+ * readings reaches a value; none, or several, and it names nothing. In
181
+ *
182
+ * { "sub": "system:serviceaccount:ci:deploy",
183
+ * "kubernetes.io": { "namespace": "ci", "serviceaccount": { "name": "deploy", "uid": "4f1c…" } } }
184
+ *
185
+ * `kubernetes.io.serviceaccount.uid` is `4f1c…`, `kubernetes.io` an object,
186
+ * and `kubernetes.io.pod` nothing.
187
+ */
188
+ declare function claimAt(claims: Record<string, unknown>, name: string): unknown;
189
+ /**
190
+ * The claims of a verified token that differ from what a binding expects,
191
+ * by name: none when it matches. A claim matches when the token carries its
192
+ * value, or one of its values, where `claimAt` reads it. On GitHub's
193
+ * profiles, two readings:
194
+ *
195
+ * - A `pull_request` run, at `refs/pull/<n>/merge`, counts as a run at the
196
+ * branch it merges into: its `ref`, and the ref its `workflow_ref` ends
197
+ * in, are read as `refs/heads/<base_ref>`.
198
+ * - `environment` matches whatever its case: GitHub's environment names are
199
+ * case-insensitive, so `Production` and `production` are one environment,
200
+ * under the same protection rules.
201
+ */
202
+ declare function differingClaims(profile: WorkloadProfile, expected: BindingClaims, token: Record<string, unknown>): string[];
203
+ /** The claims as the MAC and the database hold them: JSON, sorted by name. */
204
+ declare function canonicalClaims(claims: BindingClaims): string;
205
+ /**
206
+ * A URL coffre may fetch for a binding: an issuer, or the keys its
207
+ * discovery names. `https` on port 443, a host name rather than an address,
208
+ * and nothing that names this machine or its network. Loopback over plain
209
+ * HTTP only where the deployment allows it, for the dev IdP. Where the name
210
+ * resolves is checked again when connecting, on Node (`addresses.ts` in the
211
+ * server).
212
+ */
213
+ declare function checkFetchUrl(value: string, what: string, options: {
214
+ allowLoopback?: boolean;
215
+ path: boolean;
216
+ query: boolean;
217
+ }): URL;
218
+ /** What a preset fills in: a profile `/api/auth/oidc` takes, and its claims. */
219
+ type Preset = {
220
+ profile: BearerProfile;
221
+ claims: BindingClaims;
222
+ };
223
+ /** `refs/heads/main`, or `refs/tags/v1`, as GitHub names a ref. */
224
+ declare function fullRef(kind: 'branch' | 'tag', name: string): string;
225
+ /** The GitHub events a binding at a branch, or at a tag, may name. */
226
+ declare function githubEventsAt(kind: 'branch' | 'tag'): string[];
227
+ /** A workflow file at a ref, as GitHub's tokens name it: `acme/api/.github/workflows/deploy.yml@refs/heads/main`. */
228
+ declare function workflowRef(repository: string, file: string, ref: string): string;
229
+ /**
230
+ * What started the run, as the presets take it: `event` (`source`, for
231
+ * GitLab), the one value 0.4.6's presets took, or `events` (`sources`), any
232
+ * of several. Naming both, or neither, is a type error and, for a caller the
233
+ * types do not reach, a `BindingInvalid` at run time: a preset never guesses
234
+ * which one was meant.
235
+ */
236
+ type Starts<One extends string, Many extends string> = ({ [K in One]: string; } & { [K in Many]?: never; }) | ({ [K in Many]: string[]; } & { [K in One]?: never; });
237
+ /**
238
+ * A workflow of the repository, run at `ref` by any of `events`; a pull
239
+ * request, by the branch it merges into. An `environment` narrows it to the
240
+ * jobs that run in that GitHub environment.
241
+ */
242
+ declare function githubWorkflow(input: {
243
+ repository: string;
244
+ repositoryId: string;
245
+ ownerId: string;
246
+ workflow: string;
247
+ ref: string;
248
+ environment?: string;
249
+ } & Starts<'event', 'events'>): Preset;
250
+ /**
251
+ * A reusable workflow at one commit, called at `ref`: from one repository,
252
+ * or, with `repositoryId` null, from any repository of the organization. A
253
+ * `caller` workflow narrows it to one calling workflow, and an
254
+ * `environment` to the jobs that run in that GitHub environment.
255
+ */
256
+ declare function githubReusable(input: {
257
+ repositoryId: string | null;
258
+ ownerId: string;
259
+ ref: string;
260
+ called: string;
261
+ sha: string;
262
+ caller?: {
263
+ repository: string;
264
+ workflow: string;
265
+ };
266
+ environment?: string;
267
+ } & Starts<'event', 'events'>): Preset;
268
+ /** A GitLab project's pipelines from any of `sources`, at a branch or tag. */
269
+ declare function gitlabProject(input: {
270
+ namespaceId: string;
271
+ projectId: string;
272
+ refType: 'branch' | 'tag';
273
+ ref: string;
274
+ } & Starts<'source', 'sources'>): Preset;
275
+ /**
276
+ * What a binding's sessions may read, by environment ID and key ID, so a
277
+ * rename moves nothing: `keys` lists keys, or `'*'` every key of the
278
+ * environment; `mints`, the minters whose children it is handed.
279
+ */
280
+ type BindingReads = Readonly<Record<string, {
281
+ readonly keys?: readonly string[] | '*';
282
+ readonly mints?: readonly string[];
283
+ }>>;
284
+ /**
285
+ * A binding's policy, as `checkPolicy` returns it: a field left out holds
286
+ * its default (`POLICY_DEFAULTS`), so one policy has one spelling.
287
+ *
288
+ * - `audience`: the exact audience of an `azure` token, an Entra
289
+ * application ID URI, which Entra fixes; required for it, refused for
290
+ * every other profile.
291
+ * - `keyAudience`: the token's audience must name the session's key,
292
+ * `<publicUrl>#jkt=<thumbprint>`: always for the platforms whose caller
293
+ * picks the audience (`KEY_NAMING_PROFILES`), and where a `custom`
294
+ * binding says so.
295
+ * - `reads`: the escape hatch, by ID (section 6.1).
296
+ * - `sources`: CIDRs a session's client address must be within.
297
+ * - `sessionHours`: a session's hard end after its proof, at most 168.
298
+ * - An `enrollment` binding's codes: `replicas` (required), `sessionDays`,
299
+ * `overlapMinutes`, `mintedBy` (the service, never the binding's own,
300
+ * that may mint them), `approve` and `onContention` (section 4.4).
301
+ * - `unsignedUploads`: a streamed upload no digest binds may go through a
302
+ * credential that takes one (section 5.1), which leaves column B at use.
303
+ */
304
+ type BindingPolicy = {
305
+ readonly audience?: string;
306
+ readonly keyAudience?: true;
307
+ readonly reads?: BindingReads;
308
+ readonly sources?: readonly string[];
309
+ readonly sessionHours?: number;
310
+ readonly replicas?: number;
311
+ readonly sessionDays?: number;
312
+ readonly overlapMinutes?: number;
313
+ readonly mintedBy?: string;
314
+ readonly approve?: true;
315
+ readonly onContention?: 'alert';
316
+ readonly unsignedUploads?: true;
317
+ };
318
+ /** What a field left out of a policy means. */
319
+ declare const POLICY_DEFAULTS: {
320
+ readonly keyAudience: false;
321
+ readonly sessionHours: 24;
322
+ readonly sessionDays: 30;
323
+ readonly overlapMinutes: 15;
324
+ readonly approve: false;
325
+ readonly onContention: "freeze";
326
+ readonly unsignedUploads: false;
327
+ };
328
+ /** The most environments, and keys in each, a binding's `reads` lists; the most `sources`. */
329
+ declare const MAX_READ_PLACES = 64;
330
+ declare const MAX_READ_KEYS = 256;
331
+ declare const MAX_SOURCES = 16;
332
+ type PolicyField = keyof BindingPolicy;
333
+ /**
334
+ * The profiles whose caller picks the token's audience, so their binding's
335
+ * policy always says `keyAudience`: `checkPolicy` sets it, and refuses it off.
336
+ * A Vercel function picks one by exchanging its own token at
337
+ * `https://oidc.vercel.com/~token`, as `@vercel/oidc`'s
338
+ * `getVercelOidcToken({ audience })` does.
339
+ */
340
+ declare const KEY_NAMING_PROFILES: readonly WorkloadProfile[];
341
+ /** The fields each profile's policy may hold. */
342
+ declare const POLICY_FIELDS: Record<WorkloadProfile, readonly PolicyField[]>;
343
+ /** A credential's name in the proxy's config: a minter's, a signer's, an upstream's. */
344
+ declare const CREDENTIAL_NAME: RegExp;
345
+ /**
346
+ * Check a binding's policy against its profile and return it canonical:
347
+ * every field its profile allows, valid, those at their default left out,
348
+ * lists sorted and IDs in lower case, so that one policy has one spelling
349
+ * (`policyText`). `service` is the binding's own, `token:<name>`, which its
350
+ * `mintedBy` may not name: a session of the service would then mint codes
351
+ * for itself, and outlive every deploy. Throws `BindingInvalid`.
352
+ */
353
+ declare function checkPolicy(profile: WorkloadProfile, input: unknown, options: {
354
+ service: string;
355
+ }): BindingPolicy;
356
+ /** A policy as the binding's `policy` column and its MAC hold it: `checkPolicy`'s result, as canonical JSON. */
357
+ declare function policyText(policy: BindingPolicy): string;
358
+ /** An address block: its version, its network's bytes, its prefix length, and its one spelling. */
359
+ type Cidr = {
360
+ version: 4 | 6;
361
+ bytes: Uint8Array;
362
+ bits: number;
363
+ text: string;
364
+ };
365
+ /** An address, IPv4 dotted or IPv6 in hex groups; null for anything else. */
366
+ declare function parseAddress(text: string): {
367
+ version: 4 | 6;
368
+ bytes: Uint8Array;
369
+ } | null;
370
+ /**
371
+ * A CIDR, `162.220.232.0/24` or `2001:db8::/32`, as its one spelling; null
372
+ * for anything else, a block with host bits set included, since
373
+ * `162.220.232.5/24` most likely means another block than it says.
374
+ */
375
+ declare function parseCidr(text: string): Cidr | null;
376
+ /** Whether an address is within any of these blocks, each `parseCidr`'s: never for an address that does not parse, or of the other version. */
377
+ declare function addressWithin(address: string, sources: readonly string[]): boolean;
378
+ /**
379
+ * What a freeze names, in its one spelling (section 8.2): every workload's
380
+ * use, one service, one binding, one session, or one upstream credential of
381
+ * an environment, by the environment's ID so a rename moves nothing.
382
+ *
383
+ * freezeTarget('Binding:0F0E…') → null freezeTarget('binding:0f0e…') → 'binding:0f0e…'
384
+ * freezeTarget('credential:6B1C…-…/stripe') → 'credential:6b1c…-…/stripe'
385
+ */
386
+ declare function freezeTarget(text: string): string | null;
387
+ /**
388
+ * A workload, authenticated for one request (section 5.3): a key-bound
389
+ * session's, or a Cloudflare service binding's, which has no session row.
390
+ * `PluginContext.workload(request, …)` returns it, so the proxy sees one
391
+ * kind of caller whichever way it signed in, and never parses a proof.
392
+ */
393
+ type WorkloadCaller = {
394
+ readonly kind: 'workload';
395
+ /** The service, `token:<name>`. */
396
+ readonly principal: string;
397
+ /** The session's credential ID, or `binding:<id>` for a Cloudflare call: what the log names. */
398
+ readonly credentialId: string;
399
+ readonly bindingId: string;
400
+ readonly profile: WorkloadProfile;
401
+ /** A `narrow` child's limits; null for a root, which only its scope bounds. */
402
+ readonly constraints: Constraints | null;
403
+ /** The headers the proof signs, which alone are forwarded; null for a Cloudflare call, whose request nobody in between could change. */
404
+ readonly hdr: readonly string[] | null;
405
+ readonly sourceIp: string | null;
406
+ };
407
+ /** What a workload's alert says (section 8.3), to the log and to the deployment's `alert`. */
408
+ type WorkloadAlert = {
409
+ readonly kind: 'enrolled' | 'contention' | 'limit' | 'expiring' | 'frozen';
410
+ readonly service: string;
411
+ readonly binding: string | null;
412
+ readonly session: string | null;
413
+ readonly ip: string | null;
414
+ /** One line for a person: `api-prod enrolled from 203.0.113.9 (railway, code minted by deploy run 7001)`. */
415
+ readonly text: string;
416
+ };
417
+ //#endregion
418
+ export { parseAddress as $, REPEATING_PROFILES as A, checkFetchUrl as B, MAX_READ_PLACES as C, POLICY_FIELDS as D, POLICY_DEFAULTS as E, WorkloadCaller as F, differingClaims as G, claimAt as H, WorkloadProfile as I, githubEventsAt as J, freezeTarget as K, addressWithin as L, Starts as M, WORKLOAD_PROFILES as N, PROFILE_URNS as O, WorkloadAlert as P, isBearerProfile as Q, canonicalClaims as R, MAX_READ_KEYS as S, OIDC_PROFILES as T, claimValues as U, checkPolicy as V, defaultIssuer as W, githubWorkflow as X, githubReusable as Y, gitlabProject as Z, KEY_NAMING_PROFILES as _, BindingPolicy as a, MAX_CONSTRAINTS as at, MAX_CLAIM_BYTES as b, CheckedBinding as c, constraintsText as ct, EVENT_EXPOSURE as d, parseCidr as et, GITHUB_EVENTS as f, GOOGLE_ISSUER as g, GITLAB_PIPELINE_SOURCES as h, BindingInvalid as i, ConstraintsInvalid as it, REQUIRED_CLAIMS as j, Preset as k, Cidr as l, intersect as lt, GITLAB_ISSUER as m, BearerProfile as n, workflowRef as nt, BindingReads as o, checkConstraints as ot, GITHUB_ISSUER as p, fullRef as q, BindingClaims as r, Constraints as rt, CREDENTIAL_NAME as s, constraintsAllow as st, BEARER_PROFILES as t, policyText as tt, ClaimValue as u, MAX_BINDINGS as v, MAX_SOURCES as w, MAX_ISSUER_BYTES as x, MAX_CLAIMS as y, checkBinding as z };
@@ -1,206 +1,2 @@
1
- //#region src/identity/workloads.d.ts
2
- /**
3
- * Trust bindings: which CI runs may sign in as a service, by the ID token
4
- * their platform signs for them (docs/design/oidc.md).
5
- *
6
- * A binding names a profile, an issuer, and claims a token must carry, each
7
- * a string matched exactly, at the top of the token or nested in it
8
- * (`claimAt`). The event that started the run may be any of several: a
9
- * list. The profile sets the minimum: the server refuses a binding that
10
- * lacks a claim its profile requires, from the UI, the CLI or the API
11
- * alike. Say a service is bound to `ci.yml` of
12
- * `acme/api`, pushed or dispatched on `main`, or run for a pull request
13
- * into `main`:
14
- *
15
- * { profile: 'github', issuer: 'https://token.actions.githubusercontent.com',
16
- * claims: { repository_owner_id: '9919', repository_id: '41532',
17
- * workflow_ref: 'acme/api/.github/workflows/ci.yml@refs/heads/main',
18
- * ref: 'refs/heads/main',
19
- * event_name: ['pull_request', 'push', 'workflow_dispatch'] } }
20
- *
21
- * A GitHub binding may also name `environment`, the GitHub environment its
22
- * job runs in, so that the environment's protection rules (its required
23
- * reviewers, the branches it deploys) gate every run that signs in. GitHub
24
- * changes `sub` for such a job, `repo:acme/api:environment:production`, but
25
- * no GitHub binding matches `sub`: `ref` and `workflow_ref` stay as they were.
26
- */
27
- export declare const GITHUB_ISSUER = "https://token.actions.githubusercontent.com";
28
- export declare const GITLAB_ISSUER = "https://gitlab.com";
29
- /**
30
- * - `github`: a workflow of the repository.
31
- * - `github-reusable`: a reusable workflow, pinned to one commit, called from
32
- * one repository at one ref.
33
- * - `github-reusable-organization`: the same, called from any repository of
34
- * the organization: an explicit choice, never what a missing claim means.
35
- * - `gitlab`: a project's pipelines, outside merge requests.
36
- * - `custom`: any other issuer, by its subject, which the owner vouches for.
37
- */
38
- export type WorkloadProfile = 'github' | 'github-reusable' | 'github-reusable-organization' | 'gitlab' | 'custom';
39
- export declare const WORKLOAD_PROFILES: readonly WorkloadProfile[];
40
- /** The claims each profile requires; a binding may add more, to narrow it. */
41
- export declare const REQUIRED_CLAIMS: Record<WorkloadProfile, readonly string[]>;
42
- /**
43
- * The events a GitHub binding may trust. The first four are started by
44
- * someone with write access, at the ref the binding names. The last two
45
- * can run code nobody reviewed, so the owner opts in to each:
46
- *
47
- * - `pull_request` runs the pull request's own code and workflow file, at
48
- * `refs/pull/<n>/merge`; a binding matches it by the branch it merges
49
- * into. Forks get no ID token, unless the repository sends write tokens
50
- * to their pull requests (a setting of private repositories), so this
51
- * trusts whoever can push a branch to the repository.
52
- * - `workflow_run` runs the default branch's workflow, but a fork's pull
53
- * request can start it: the run is as safe as what it does with the
54
- * code and artifacts of the run that started it.
55
- *
56
- * `pull_request_target` and the rest are refused, even when their ref
57
- * happens to match: they exist to act on anyone's pull request, with the
58
- * base repository's tokens.
59
- */
60
- export declare const GITHUB_EVENTS: readonly ["push", "workflow_dispatch", "schedule", "release", "pull_request", "workflow_run"];
61
- /**
62
- * What trusting each of the last two events exposes, as the UI, the CLI and
63
- * the approval page say it when one is chosen.
64
- */
65
- export declare const EVENT_EXPOSURE: Readonly<Record<string, string>>;
66
- /** Pipelines that run the project's own code, at its own ref: never a merge request's. */
67
- export declare const GITLAB_PIPELINE_SOURCES: readonly ["push", "web", "schedule"];
68
- /** At most this many live bindings per service, and claims per binding. */
69
- export declare const MAX_BINDINGS = 16;
70
- export declare const MAX_CLAIMS = 16;
71
- /** The longest claim value, in bytes. */
72
- export declare const MAX_CLAIM_BYTES = 256;
73
- /** A claim a binding names: one value, or, for what started the run, any of several. */
74
- export type ClaimValue = string | string[];
75
- export type BindingClaims = Record<string, ClaimValue>;
76
- /**
77
- * What makes a binding, checked: its profile, its issuer, and its claims,
78
- * sorted. The issuer is a URL coffre may fetch, unless the binding carries
79
- * its keys (`uploaded`): then coffre fetches nothing, and it is any string,
80
- * matched exactly, such as a private Kubernetes cluster's.
81
- */
82
- export type BindingPolicy = {
83
- profile: WorkloadProfile;
84
- issuer: string;
85
- claims: BindingClaims;
86
- };
87
- /** A binding that breaks a rule, said so an owner can fix it. */
88
- export declare class BindingInvalid extends Error {
89
- constructor(message: string);
90
- }
91
- /** The issuer a profile means when none is given: github.com's or gitlab.com's. A GitHub Enterprise Server or a self-managed GitLab names its own. */
92
- export declare function defaultIssuer(profile: WorkloadProfile): string | null;
93
- /** The longest issuer a binding with uploaded keys names, in bytes. */
94
- export declare const MAX_ISSUER_BYTES = 400;
95
- /**
96
- * Check a binding against its profile, and return it as stored: the
97
- * issuer as given, the claims sorted by name. With `uploaded`, the binding
98
- * carries its issuer's keys, and its issuer need not be a URL coffre can
99
- * fetch. Throws `BindingInvalid`.
100
- */
101
- export declare function checkBinding(input: {
102
- profile: string;
103
- issuer: string | null;
104
- claims: Record<string, unknown>;
105
- }, options?: {
106
- allowLoopback?: boolean;
107
- uploaded?: boolean;
108
- }): BindingPolicy;
109
- /** A claim's values, one or several. */
110
- export declare function claimValues(value: ClaimValue | undefined): string[];
111
- /**
112
- * A claim of a token, by the name a binding gives it: a top-level claim, or
113
- * one nested in objects, its path joined by dots. A key may hold dots of
114
- * its own, as Kubernetes' `kubernetes.io` does, so a name is read every way
115
- * its dots can split it, and names a claim only when exactly one of those
116
- * readings reaches a value; none, or several, and it names nothing. In
117
- *
118
- * { "sub": "system:serviceaccount:ci:deploy",
119
- * "kubernetes.io": { "namespace": "ci", "serviceaccount": { "name": "deploy", "uid": "4f1c…" } } }
120
- *
121
- * `kubernetes.io.serviceaccount.uid` is `4f1c…`, `kubernetes.io` an object,
122
- * and `kubernetes.io.pod` nothing.
123
- */
124
- export declare function claimAt(claims: Record<string, unknown>, name: string): unknown;
125
- /**
126
- * The claims of a verified token that differ from what a binding expects,
127
- * by name: none when it matches. A claim matches when the token carries its
128
- * value, or one of its values, where `claimAt` reads it. On GitHub's
129
- * profiles, two readings:
130
- *
131
- * - A `pull_request` run, at `refs/pull/<n>/merge`, counts as a run at the
132
- * branch it merges into: its `ref`, and the ref its `workflow_ref` ends
133
- * in, are read as `refs/heads/<base_ref>`.
134
- * - `environment` matches whatever its case: GitHub's environment names are
135
- * case-insensitive, so `Production` and `production` are one environment,
136
- * under the same protection rules.
137
- */
138
- export declare function differingClaims(profile: WorkloadProfile, expected: BindingClaims, token: Record<string, unknown>): string[];
139
- /** The claims as the MAC and the database hold them: JSON, sorted by name. */
140
- export declare function canonicalClaims(claims: BindingClaims): string;
141
- /**
142
- * A URL coffre may fetch for a binding: an issuer, or the keys its
143
- * discovery names. `https` on port 443, a host name rather than an address,
144
- * and nothing that names this machine or its network. Loopback over plain
145
- * HTTP only where the deployment allows it, for the dev IdP. Where the name
146
- * resolves is checked again when connecting, on Node (`addresses.ts` in the
147
- * server).
148
- */
149
- export declare function checkFetchUrl(value: string, what: string, options: {
150
- allowLoopback?: boolean;
151
- path: boolean;
152
- query: boolean;
153
- }): URL;
154
- /** `refs/heads/main`, or `refs/tags/v1`, as GitHub names a ref. */
155
- export declare function fullRef(kind: 'branch' | 'tag', name: string): string;
156
- /** The GitHub events a binding at a branch, or at a tag, may name. */
157
- export declare function githubEventsAt(kind: 'branch' | 'tag'): string[];
158
- /** A workflow file at a ref, as GitHub's tokens name it: `acme/api/.github/workflows/deploy.yml@refs/heads/main`. */
159
- export declare function workflowRef(repository: string, file: string, ref: string): string;
160
- /**
161
- * What started the run, as the presets take it: `event` (`source`, for
162
- * GitLab), the one value 0.4.6's presets took, or `events` (`sources`), any
163
- * of several. Naming both, or neither, is a type error and, for a caller the
164
- * types do not reach, a `BindingInvalid` at run time: a preset never guesses
165
- * which one was meant.
166
- */
167
- export type Starts<One extends string, Many extends string> = ({ [K in One]: string; } & { [K in Many]?: never; }) | ({ [K in Many]: string[]; } & { [K in One]?: never; });
168
- /**
169
- * A workflow of the repository, run at `ref` by any of `events`; a pull
170
- * request, by the branch it merges into. An `environment` narrows it to the
171
- * jobs that run in that GitHub environment.
172
- */
173
- export declare function githubWorkflow(input: {
174
- repository: string;
175
- repositoryId: string;
176
- ownerId: string;
177
- workflow: string;
178
- ref: string;
179
- environment?: string;
180
- } & Starts<'event', 'events'>): Omit<BindingPolicy, 'issuer'>;
181
- /**
182
- * A reusable workflow at one commit, called at `ref`: from one repository,
183
- * or, with `repositoryId` null, from any repository of the organization. A
184
- * `caller` workflow narrows it to one calling workflow, and an
185
- * `environment` to the jobs that run in that GitHub environment.
186
- */
187
- export declare function githubReusable(input: {
188
- repositoryId: string | null;
189
- ownerId: string;
190
- ref: string;
191
- called: string;
192
- sha: string;
193
- caller?: {
194
- repository: string;
195
- workflow: string;
196
- };
197
- environment?: string;
198
- } & Starts<'event', 'events'>): Omit<BindingPolicy, 'issuer'>;
199
- /** A GitLab project's pipelines from any of `sources`, at a branch or tag. */
200
- export declare function gitlabProject(input: {
201
- namespaceId: string;
202
- projectId: string;
203
- refType: 'branch' | 'tag';
204
- ref: string;
205
- } & Starts<'source', 'sources'>): Omit<BindingPolicy, 'issuer'>;
206
- //#endregion
1
+ import { $ as parseAddress, A as REPEATING_PROFILES, B as checkFetchUrl, C as MAX_READ_PLACES, D as POLICY_FIELDS, E as POLICY_DEFAULTS, F as WorkloadCaller, G as differingClaims, H as claimAt, I as WorkloadProfile, J as githubEventsAt, K as freezeTarget, L as addressWithin, M as Starts, N as WORKLOAD_PROFILES, O as PROFILE_URNS, P as WorkloadAlert, Q as isBearerProfile, R as canonicalClaims, S as MAX_READ_KEYS, T as OIDC_PROFILES, U as claimValues, V as checkPolicy, W as defaultIssuer, X as githubWorkflow, Y as githubReusable, Z as gitlabProject, _ as KEY_NAMING_PROFILES, a as BindingPolicy, b as MAX_CLAIM_BYTES, c as CheckedBinding, d as EVENT_EXPOSURE, et as parseCidr, f as GITHUB_EVENTS, g as GOOGLE_ISSUER, h as GITLAB_PIPELINE_SOURCES, i as BindingInvalid, j as REQUIRED_CLAIMS, k as Preset, l as Cidr, m as GITLAB_ISSUER, n as BearerProfile, nt as workflowRef, o as BindingReads, p as GITHUB_ISSUER, q as fullRef, r as BindingClaims, s as CREDENTIAL_NAME, t as BEARER_PROFILES, tt as policyText, u as ClaimValue, v as MAX_BINDINGS, w as MAX_SOURCES, x as MAX_ISSUER_BYTES, y as MAX_CLAIMS, z as checkBinding } from "./workloads-CP54Q72p.js";
2
+ export { BEARER_PROFILES, BearerProfile, BindingClaims, BindingInvalid, BindingPolicy, BindingReads, CREDENTIAL_NAME, CheckedBinding, Cidr, ClaimValue, EVENT_EXPOSURE, GITHUB_EVENTS, GITHUB_ISSUER, GITLAB_ISSUER, GITLAB_PIPELINE_SOURCES, GOOGLE_ISSUER, KEY_NAMING_PROFILES, MAX_BINDINGS, MAX_CLAIMS, MAX_CLAIM_BYTES, MAX_ISSUER_BYTES, MAX_READ_KEYS, MAX_READ_PLACES, MAX_SOURCES, OIDC_PROFILES, POLICY_DEFAULTS, POLICY_FIELDS, PROFILE_URNS, Preset, REPEATING_PROFILES, REQUIRED_CLAIMS, Starts, WORKLOAD_PROFILES, WorkloadAlert, WorkloadCaller, WorkloadProfile, addressWithin, canonicalClaims, checkBinding, checkFetchUrl, checkPolicy, claimAt, claimValues, defaultIssuer, differingClaims, freezeTarget, fullRef, githubEventsAt, githubReusable, githubWorkflow, gitlabProject, isBearerProfile, parseAddress, parseCidr, policyText, workflowRef };