@coffre/core 0.14.5 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/vault.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { B as isInstanceRole, H as isScope, M as grantKind, O as definitionProblem, _ as ROLES, b as UNWRITTEN_FORK_MS, i as EVERYWHERE, l as INSTANCE_ROLES, t as DEFAULT_POLICY } from "./access-CgQTlUMz.js";
1
2
  import { createHash } from "node:crypto";
2
3
  //#region src/checkpoint.ts
3
4
  /** What a checkpoint's signature covers: the prefix of the log up to entry `seq`, and when. */
@@ -40,8 +41,202 @@ function describeAccessFault(fault, names = {}) {
40
41
  }
41
42
  }
42
43
  //#endregion
44
+ //#region src/answers.ts
45
+ /** A member: `user:<email>` or `token:<name>`. */
46
+ const PRINCIPAL = /^(user|token):[^\s:][^\s]*$/;
47
+ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
48
+ /**
49
+ * What `access` answers about `principal`, from their row and their
50
+ * grants, lapsed ones too, as of `at`; `tampered` when a row failed the
51
+ * vault's check, which only the vault can tell.
52
+ */
53
+ function answerFrom(principal, row, held, at, tampered, policy) {
54
+ const active = PRINCIPAL.test(principal) && !tampered && row?.status === "active";
55
+ const access = {
56
+ principal,
57
+ status: tampered ? "tampered" : !PRINCIPAL.test(principal) ? "unknown" : row?.status ?? "unknown",
58
+ generation: row?.generation ?? 0,
59
+ ...active ? roleOf(principal, row) : {
60
+ role: "member",
61
+ scope: EVERYWHERE
62
+ },
63
+ grants: active ? held.filter((grant) => live(grant, at) && grantKind(grant) !== null).map(view) : [],
64
+ since: row ? iso(row.statusChangedAt) : null,
65
+ by: row?.statusChangedBy ?? null,
66
+ policy
67
+ };
68
+ return {
69
+ ...access,
70
+ revision: accessRevision(access)
71
+ };
72
+ }
73
+ /** A member's instance role, as their row has it: service accounts are members, whatever a row says. */
74
+ function roleOf(principal, row) {
75
+ return principal.startsWith("user:") ? {
76
+ role: row.role,
77
+ scope: row.scope
78
+ } : {
79
+ role: "member",
80
+ scope: EVERYWHERE
81
+ };
82
+ }
83
+ /** Whether a grant still holds at `at`. */
84
+ function live(grant, at) {
85
+ return grant.expiresAt === null || grant.expiresAt > at;
86
+ }
87
+ /** A grant as `access` answers it. */
88
+ function view(grant) {
89
+ return {
90
+ projectId: grant.projectId,
91
+ environmentId: grant.environmentId,
92
+ role: grant.role,
93
+ expiresAt: grant.expiresAt === null ? null : iso(grant.expiresAt),
94
+ grantedAt: iso(grant.grantedAt),
95
+ grantedBy: grant.grantedBy
96
+ };
97
+ }
98
+ function iso(ms) {
99
+ return new Date(ms).toISOString();
100
+ }
101
+ const NO_EDITS = {
102
+ roles: {},
103
+ instanceRoles: {},
104
+ protected: []
105
+ };
106
+ /** A role holding nothing, which every role but Owner is under the closed policy. */
107
+ const NOTHING_HELD = (definition) => ({
108
+ ...definition,
109
+ permissions: [],
110
+ protected: []
111
+ });
112
+ /**
113
+ * The policy when the log has some, but none the vault wrote within reach:
114
+ * whoever inserted rows may have hidden an Owner's narrowing, so no role
115
+ * holds anything, a service account's neither, but Owner, which holds
116
+ * everything always and so may write the policy again.
117
+ */
118
+ const CLOSED_POLICY = {
119
+ roles: Object.fromEntries(Object.entries(ROLES).map(([id, definition]) => [id, id === "owner" ? definition : NOTHING_HELD(definition)])),
120
+ instanceRoles: Object.fromEntries(Object.entries(INSTANCE_ROLES).map(([id, definition]) => [id, id === "owner" ? definition : NOTHING_HELD(definition)])),
121
+ protected: ["*"],
122
+ protectedIn: {}
123
+ };
124
+ /**
125
+ * The policy the newest `policy.change` says, from its metadata, as of
126
+ * `at`, with the rows of the environments it protects: none for no entry,
127
+ * the roles as they ship; and closed for one whose edits do not hold.
128
+ */
129
+ function policyFrom(metadata, rows, at) {
130
+ if (metadata === null) return {
131
+ policy: DEFAULT_POLICY,
132
+ edits: NO_EDITS,
133
+ readable: true
134
+ };
135
+ let stored;
136
+ try {
137
+ stored = JSON.parse(metadata);
138
+ } catch {}
139
+ const edits = typeof stored === "object" && stored !== null ? readEdits(stored) : null;
140
+ if (edits === null) return {
141
+ policy: CLOSED_POLICY,
142
+ edits: NO_EDITS,
143
+ readable: false
144
+ };
145
+ return {
146
+ policy: livePolicy(rows, edits, at),
147
+ edits,
148
+ readable: true
149
+ };
150
+ }
151
+ /** A policy entry's edits, checked as the vault wrote them, or null for any that does not hold. */
152
+ function readEdits(stored) {
153
+ const edits = stored.policy;
154
+ if (typeof edits !== "object" || edits === null) return null;
155
+ const { roles, instanceRoles, protected: protectedIds } = edits;
156
+ if (typeof roles !== "object" || roles === null || typeof instanceRoles !== "object" || instanceRoles === null || !Array.isArray(protectedIds)) return null;
157
+ const defined = (table) => Object.values(table).every((definition) => definitionProblem(definition) === null);
158
+ if (!defined(roles) || !defined(instanceRoles) || Object.keys(instanceRoles).some((role) => !isInstanceRole(role))) return null;
159
+ if (protectedIds.some((place) => typeof place !== "object" || place === null || !UUID.test(place.projectId) || !UUID.test(place.environmentId) || !Number.isSafeInteger(place.at))) return null;
160
+ return {
161
+ roles,
162
+ instanceRoles,
163
+ protected: protectedIds
164
+ };
165
+ }
166
+ /**
167
+ * The policy `edits` say as of `at`: the roles as they ship, each edited
168
+ * one replaced and each made one added; and the protected environments, but
169
+ * for those deleted since, the project around one's included: a deleted
170
+ * prod protects nothing, and holds nobody back from giving a service
171
+ * account a role on all of its project (`givesService`). A fork's id with
172
+ * no row yet stays, protected before it is written, ten minutes: one with
173
+ * none after that is a fork refused or abandoned, never written. Each
174
+ * keeps its slug, which a scoped instance role's filters read. The edits
175
+ * keep them all: no write is needed.
176
+ */
177
+ function livePolicy(rows, edits, at) {
178
+ const live = edits.protected.filter((place) => {
179
+ const row = rows.get(place.environmentId);
180
+ return row === void 0 ? at - place.at < UNWRITTEN_FORK_MS : !row.deleted;
181
+ });
182
+ const slugOf = (place) => rows.get(place.environmentId)?.slug ?? null;
183
+ return {
184
+ roles: {
185
+ ...ROLES,
186
+ ...edits.roles
187
+ },
188
+ instanceRoles: {
189
+ ...INSTANCE_ROLES,
190
+ ...edits.instanceRoles
191
+ },
192
+ protected: live.map((place) => place.environmentId),
193
+ protectedIn: live.reduce((byProject, place) => ({
194
+ ...byProject,
195
+ [place.projectId]: [...byProject[place.projectId] ?? [], {
196
+ environmentId: place.environmentId,
197
+ slug: slugOf(place)
198
+ }]
199
+ }), {})
200
+ };
201
+ }
202
+ /** The settings before anyone changed them: people set up service accounts anywhere they hold access. */
203
+ const DEFAULT_SETTINGS = { serviceAccounts: EVERYWHERE };
204
+ /** The settings when the log has some, but none the vault wrote within reach: people set up no service accounts. */
205
+ const CLOSED_SETTINGS = { serviceAccounts: {
206
+ projects: { only: [] },
207
+ environments: "all"
208
+ } };
209
+ /** The settings the newest `settings.change` says, from its metadata: none for no entry, the default; closed for one that does not hold. */
210
+ function settingsFrom(metadata) {
211
+ if (metadata === null) return DEFAULT_SETTINGS;
212
+ let stored;
213
+ try {
214
+ stored = JSON.parse(metadata);
215
+ } catch {}
216
+ const serviceAccounts = typeof stored === "object" && stored !== null ? stored.serviceAccounts : void 0;
217
+ return isScope(serviceAccounts) ? { serviceAccounts } : CLOSED_SETTINGS;
218
+ }
219
+ //#endregion
43
220
  //#region src/vault.ts
44
221
  /**
222
+ * What the error of a change says when the change committed but its seal
223
+ * did not come in time (T169): the checkpointer stalled, or cannot be
224
+ * reached. Its words are the contract, since only an error's message
225
+ * crosses Workers' RPC: the app answers 503 with Retry-After
226
+ * (`isUnsealed`), and the change is in force.
227
+ */
228
+ const UNSEALED = "was committed, but not sealed in time";
229
+ /** Whether `error`, or one of its causes, is a change's seal that did not come in time (`UNSEALED`). */
230
+ function isUnsealed(error) {
231
+ for (let cause = error; typeof cause === "object" && cause !== null; cause = cause.cause) {
232
+ const { message } = cause;
233
+ if (typeof message === "string" && message.includes("was committed, but not sealed in time")) return true;
234
+ }
235
+ return false;
236
+ }
237
+ /** The most entries one `vouch` call checks: a page of the audit log lists a few hundred at most. */
238
+ const VOUCHED_AT_ONCE = 2e3;
239
+ /**
45
240
  * The vault's entries that change what a member holds: what their row's
46
241
  * `access_seq` names, and what a finding about them is newer than while it
47
242
  * stands.
@@ -55,6 +250,66 @@ const ACCESS_ACTIONS = [
55
250
  "access.grant",
56
251
  "access.revoke"
57
252
  ];
253
+ /** What each refusal says, as the vault answers it and the app shows it. */
254
+ const REFUSAL_MESSAGES = {
255
+ removed: "this member was removed",
256
+ not_a_member: "not a member",
257
+ no_grant: "no grant covers this",
258
+ expired: "the grant that covered this has expired",
259
+ bulk_limit: "too many secrets read in too short a time",
260
+ bad_claim: "the key does not belong to this secret",
261
+ deleted: "this project or environment was deleted",
262
+ ended: "the reference read through was ended",
263
+ personal: "a personal config's values are its owner's alone",
264
+ sensitive: "a sensitive value is never shown to anyone, Owners included: `coffre run` gives your app a placeholder for it through the credential proxy, and a service account reads it",
265
+ not_owner_issued: "a service account reads a sensitive value only on a token or trust binding an Owner of its project issued",
266
+ use_only: "a workload uses this value through coffre and never holds it: list it in its binding's reads, where the value is held, if it must",
267
+ not_allowed: "not allowed to change this",
268
+ last_owner: "the last Owner of the whole instance stays one: make someone else an Owner first",
269
+ invalid: "not something the rules allow",
270
+ policy_changed: "the instance's roles or protected environments changed while this was asked: try again",
271
+ access_changed: "what this member holds changed since the read was decided: try again",
272
+ log_broken: "the vault log does not hold from the last checkpoint",
273
+ wrong_kek: "this vault's key does not open the data it holds",
274
+ tampered: "this member's record failed the vault's integrity check"
275
+ };
276
+ /**
277
+ * A use's purpose, keepsSensitive and way in as 0.15's log stores them, in
278
+ * one smallint (`log_uses.purpose`, schema 0022, 0046): the purpose's code,
279
+ * plus 256 when a copy keeps values sensitive, plus 512 times its way in's
280
+ * (`USE_WAYS`; T147). The vault writes them; the audit pages read them back
281
+ * (T166).
282
+ */
283
+ const USE_PURPOSES = [
284
+ "reveal",
285
+ "run",
286
+ "compare",
287
+ "copy",
288
+ "use",
289
+ "expose"
290
+ ];
291
+ /** Each way in by its code: a credential's, 0, as every use before T147; then `UseWay`'s. */
292
+ const USE_WAYS = [
293
+ "credential",
294
+ "connection",
295
+ "binding",
296
+ "access"
297
+ ];
298
+ /** A use's code (`USE_PURPOSES`). */
299
+ function useCode(use) {
300
+ return USE_PURPOSES.indexOf(use.purpose) + (use.keepsSensitive === true ? 256 : 0) + 512 * USE_WAYS.indexOf(use.way ?? "credential");
301
+ }
302
+ /** The purpose, keepsSensitive and way in a use's code stores; null for a code no release writes. */
303
+ function useOfCode(code) {
304
+ const purpose = USE_PURPOSES[code % 256];
305
+ const way = USE_WAYS[Math.floor(code / 512)];
306
+ if (!Number.isInteger(code) || code < 0 || purpose === void 0 || way === void 0) return null;
307
+ return {
308
+ purpose,
309
+ keepsSensitive: code % 512 >= 256,
310
+ ...way === "credential" ? {} : { way }
311
+ };
312
+ }
58
313
  /**
59
314
  * Whether a read hands values back to whoever asked, which a person never
60
315
  * gets of a sensitive value: every purpose but the proxy's `use` and a
@@ -108,5 +363,23 @@ function policyRevision(seq, policy) {
108
363
  }
109
364
  /** A revision as `policyRevision` writes it. */
110
365
  const POLICY_REVISION = /^(none|[1-9][0-9]{0,15})\.[0-9a-f]{16}$/;
366
+ /** The longest a use may take from its time to its answer, held in Postgres too (R53): no use is decided later than this after its `at`. */
367
+ const USE_DEADLINE_MS = 3e3;
368
+ /** A use's request id: 63 random bits, as text, unique within its millisecond (hot-path-one.md, "Row size"). */
369
+ function newUseRequestId() {
370
+ const bytes = crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(8));
371
+ return (new DataView(bytes.buffer).getBigUint64(0) >> 1n).toString();
372
+ }
373
+ /** What a use's refusal says: the rules' as `REFUSAL_MESSAGES`, and those of sealed inputs. */
374
+ function useRefusalMessage(code) {
375
+ switch (code) {
376
+ case "stale": return "what this read decides on is not as the vault last sealed it: it was put back, or written around coffre";
377
+ case "credential": return "that credential is unknown, expired or revoked";
378
+ case "missing": return "no such key";
379
+ case "no_policy": return "the vault's log holds no bulk cap yet";
380
+ case "archived": return "what it reads is archived";
381
+ default: return REFUSAL_MESSAGES[code];
382
+ }
383
+ }
111
384
  //#endregion
112
- export { ACCESS_ACTIONS, POLICY_REVISION, USE_METADATA_LENGTH, accessRevision, checkpointMessage, checkpointVerifier, describeAccessFault, handsBack, policyRevision, verifyCheckpoint };
385
+ export { ACCESS_ACTIONS, CLOSED_POLICY, CLOSED_SETTINGS, DEFAULT_SETTINGS, NO_EDITS, POLICY_REVISION, PRINCIPAL, REFUSAL_MESSAGES, UNSEALED, USE_DEADLINE_MS, USE_METADATA_LENGTH, USE_PURPOSES, USE_WAYS, VOUCHED_AT_ONCE, accessRevision, answerFrom, checkpointMessage, checkpointVerifier, describeAccessFault, handsBack, isUnsealed, live, livePolicy, newUseRequestId, policyFrom, policyRevision, readEdits, roleOf, settingsFrom, useCode, useOfCode, useRefusalMessage, verifyCheckpoint, view };
@@ -315,6 +315,14 @@ type BindingPolicy = {
315
315
  readonly onContention?: 'alert';
316
316
  readonly unsignedUploads?: true;
317
317
  };
318
+ /** How long a credential an exchange issues lives: one `coffre run` needs it for seconds. The vault holds a sign-in to it (T149). */
319
+ declare const EXCHANGED_CREDENTIAL_MS: number;
320
+ /** How long a session lives past each renewal, unless its proof says less: an hour (section 5.4). The vault holds a sign-in to it. */
321
+ declare const SESSION_MS: number;
322
+ /** A workload's sign-in route, whose URL on the instance its DPoP proof signs: the app's route, and what the vault checks the proof for (PR 3b). */
323
+ declare const WORKLOAD_SIGN_IN_PATH = "/api/auth/workload";
324
+ /** How far a sign-in's DPoP proof's `iat` may be from now: it carries no nonce, so its clock bounds it (section 4.1). The app and the vault alike. */
325
+ declare const EXCHANGE_SKEW_SECONDS = 60;
318
326
  /** What a field left out of a policy means. */
319
327
  declare const POLICY_DEFAULTS: {
320
328
  readonly keyAudience: false;
@@ -416,4 +424,4 @@ type WorkloadAlert = {
416
424
  readonly text: string;
417
425
  };
418
426
  //#endregion
419
- 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 };
427
+ export { githubReusable as $, PROFILE_URNS as A, WorkloadProfile as B, MAX_ISSUER_BYTES as C, OIDC_PROFILES as D, MAX_SOURCES as E, Starts as F, checkPolicy as G, canonicalClaims as H, WORKLOAD_PROFILES as I, defaultIssuer as J, claimAt as K, WORKLOAD_SIGN_IN_PATH as L, REPEATING_PROFILES as M, REQUIRED_CLAIMS as N, POLICY_DEFAULTS as O, SESSION_MS as P, githubEventsAt as Q, WorkloadAlert as R, MAX_CLAIM_BYTES as S, MAX_READ_PLACES as T, checkBinding as U, addressWithin as V, checkFetchUrl as W, freezeTarget as X, differingClaims as Y, fullRef as Z, GITLAB_PIPELINE_SOURCES as _, BindingPolicy as a, policyText as at, MAX_BINDINGS as b, CheckedBinding as c, ConstraintsInvalid as ct, EVENT_EXPOSURE as d, constraintsAllow as dt, githubWorkflow as et, EXCHANGED_CREDENTIAL_MS as f, constraintsText as ft, GITLAB_ISSUER as g, GITHUB_ISSUER as h, BindingInvalid as i, parseCidr as it, Preset as j, POLICY_FIELDS as k, Cidr as l, MAX_CONSTRAINTS as lt, GITHUB_EVENTS as m, BearerProfile as n, isBearerProfile as nt, BindingReads as o, workflowRef as ot, EXCHANGE_SKEW_SECONDS as p, intersect as pt, claimValues as q, BindingClaims as r, parseAddress as rt, CREDENTIAL_NAME as s, Constraints as st, BEARER_PROFILES as t, gitlabProject as tt, ClaimValue as u, checkConstraints as ut, GOOGLE_ISSUER as v, MAX_READ_KEYS as w, MAX_CLAIMS as x, KEY_NAMING_PROFILES as y, WorkloadCaller as z };
@@ -1,2 +1,2 @@
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-CW2dK4AW.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 };
1
+ import { $ as githubReusable, A as PROFILE_URNS, B as WorkloadProfile, C as MAX_ISSUER_BYTES, D as OIDC_PROFILES, E as MAX_SOURCES, F as Starts, G as checkPolicy, H as canonicalClaims, I as WORKLOAD_PROFILES, J as defaultIssuer, K as claimAt, L as WORKLOAD_SIGN_IN_PATH, M as REPEATING_PROFILES, N as REQUIRED_CLAIMS, O as POLICY_DEFAULTS, P as SESSION_MS, Q as githubEventsAt, R as WorkloadAlert, S as MAX_CLAIM_BYTES, T as MAX_READ_PLACES, U as checkBinding, V as addressWithin, W as checkFetchUrl, X as freezeTarget, Y as differingClaims, Z as fullRef, _ as GITLAB_PIPELINE_SOURCES, a as BindingPolicy, at as policyText, b as MAX_BINDINGS, c as CheckedBinding, d as EVENT_EXPOSURE, et as githubWorkflow, f as EXCHANGED_CREDENTIAL_MS, g as GITLAB_ISSUER, h as GITHUB_ISSUER, i as BindingInvalid, it as parseCidr, j as Preset, k as POLICY_FIELDS, l as Cidr, m as GITHUB_EVENTS, n as BearerProfile, nt as isBearerProfile, o as BindingReads, ot as workflowRef, p as EXCHANGE_SKEW_SECONDS, q as claimValues, r as BindingClaims, rt as parseAddress, s as CREDENTIAL_NAME, t as BEARER_PROFILES, tt as gitlabProject, u as ClaimValue, v as GOOGLE_ISSUER, w as MAX_READ_KEYS, x as MAX_CLAIMS, y as KEY_NAMING_PROFILES, z as WorkloadCaller } from "./workloads-D049JH0M.js";
2
+ export { BEARER_PROFILES, BearerProfile, BindingClaims, BindingInvalid, BindingPolicy, BindingReads, CREDENTIAL_NAME, CheckedBinding, Cidr, ClaimValue, EVENT_EXPOSURE, EXCHANGED_CREDENTIAL_MS, EXCHANGE_SKEW_SECONDS, 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, SESSION_MS, Starts, WORKLOAD_PROFILES, WORKLOAD_SIGN_IN_PATH, WorkloadAlert, WorkloadCaller, WorkloadProfile, addressWithin, canonicalClaims, checkBinding, checkFetchUrl, checkPolicy, claimAt, claimValues, defaultIssuer, differingClaims, freezeTarget, fullRef, githubEventsAt, githubReusable, githubWorkflow, gitlabProject, isBearerProfile, parseAddress, parseCidr, policyText, workflowRef };
package/dist/workloads.js CHANGED
@@ -539,6 +539,14 @@ function gitlabProject(input) {
539
539
  }
540
540
  };
541
541
  }
542
+ /** How long a credential an exchange issues lives: one `coffre run` needs it for seconds. The vault holds a sign-in to it (T149). */
543
+ const EXCHANGED_CREDENTIAL_MS = 3e5;
544
+ /** How long a session lives past each renewal, unless its proof says less: an hour (section 5.4). The vault holds a sign-in to it. */
545
+ const SESSION_MS = 36e5;
546
+ /** A workload's sign-in route, whose URL on the instance its DPoP proof signs: the app's route, and what the vault checks the proof for (PR 3b). */
547
+ const WORKLOAD_SIGN_IN_PATH = "/api/auth/workload";
548
+ /** How far a sign-in's DPoP proof's `iat` may be from now: it carries no nonce, so its clock bounds it (section 4.1). The app and the vault alike. */
549
+ const EXCHANGE_SKEW_SECONDS = 60;
542
550
  /** What a field left out of a policy means. */
543
551
  const POLICY_DEFAULTS = {
544
552
  keyAudience: false,
@@ -844,4 +852,4 @@ function freezeTarget(text) {
844
852
  }
845
853
  }
846
854
  //#endregion
847
- export { BEARER_PROFILES, BindingInvalid, CREDENTIAL_NAME, 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, REPEATING_PROFILES, REQUIRED_CLAIMS, WORKLOAD_PROFILES, addressWithin, canonicalClaims, checkBinding, checkFetchUrl, checkPolicy, claimAt, claimValues, defaultIssuer, differingClaims, freezeTarget, fullRef, githubEventsAt, githubReusable, githubWorkflow, gitlabProject, isBearerProfile, parseAddress, parseCidr, policyText, workflowRef };
855
+ export { BEARER_PROFILES, BindingInvalid, CREDENTIAL_NAME, EVENT_EXPOSURE, EXCHANGED_CREDENTIAL_MS, EXCHANGE_SKEW_SECONDS, 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, REPEATING_PROFILES, REQUIRED_CLAIMS, SESSION_MS, WORKLOAD_PROFILES, WORKLOAD_SIGN_IN_PATH, addressWithin, canonicalClaims, checkBinding, checkFetchUrl, checkPolicy, claimAt, claimValues, defaultIssuer, differingClaims, freezeTarget, fullRef, githubEventsAt, githubReusable, githubWorkflow, gitlabProject, isBearerProfile, parseAddress, parseCidr, policyText, workflowRef };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@coffre/core",
3
- "version": "0.14.5",
3
+ "version": "0.15.0",
4
4
  "description": "What coffre's packages share: roles, envelopes, identity, the audit chain and the vault's contract.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -47,6 +47,11 @@
47
47
  "types": "./dist/kek.d.ts",
48
48
  "default": "./dist/kek.js"
49
49
  },
50
+ "./merkle": {
51
+ "coffre:source": "./src/audit/merkle.ts",
52
+ "types": "./dist/merkle.d.ts",
53
+ "default": "./dist/merkle.js"
54
+ },
50
55
  "./mcp": {
51
56
  "coffre:source": "./src/mcp.ts",
52
57
  "types": "./dist/mcp.d.ts",
@@ -83,14 +88,14 @@
83
88
  "jose": "6.2.3",
84
89
  "oauth4webapi": "3.8.8",
85
90
  "zod": "4.4.3",
86
- "@coffre/client": "0.14.5"
91
+ "@coffre/client": "0.15.0"
87
92
  },
88
93
  "devDependencies": {
89
94
  "@hegeldev/hegel": "0.4.7",
90
95
  "@types/node": "26.1.1",
91
96
  "tsdown": "0.23.0",
92
97
  "typescript": "5.9.3",
93
- "@coffre/conformance": "0.14.5"
98
+ "@coffre/conformance": "0.15.0"
94
99
  },
95
100
  "scripts": {
96
101
  "build": "tsdown",
package/src/access.ts CHANGED
@@ -552,6 +552,21 @@ export function delegableRoles(policy: Policy = DEFAULT_POLICY): Role[] {
552
552
  /** The roles a personal token's scope may name, as they ship. */
553
553
  export const DELEGABLE_ROLES: readonly Role[] = delegableRoles();
554
554
 
555
+ /** What a handle reads and uses, and no more: it writes nothing. */
556
+ export const HANDLE_HOLDS: RoleDefinition = { name: 'Handle', description: 'Read and use, as its person does.', permissions: ['secret.read', 'secret.use'], protected: ['secret.read', 'secret.use'] };
557
+
558
+ /**
559
+ * The roles a handle's scope is issued under (the server's `issueHandle`; the vault holds a handle's columns to them, T149): each place
560
+ * keeps what its person holds there, in each column, of reading and using
561
+ * (`issuedGrant`, capped by `heldColumns`), whatever an Owner made of the
562
+ * roles. `viewer` names a place its person reads, `contributor` one they
563
+ * only use.
564
+ *
565
+ * an Owner, at a protected prod read, use / read, use
566
+ * a Developer, at the same read, use / use
567
+ */
568
+ export const HANDLE_POLICY: Policy = { ...DEFAULT_POLICY, roles: { ...ROLES, viewer: HANDLE_HOLDS, contributor: HANDLE_HOLDS } };
569
+
555
570
  /**
556
571
  * The longest a personal token lasts: a week. It is for an afternoon's
557
572
  * script or agent, and whoever needs it longer makes another, as a person,
@@ -559,6 +574,9 @@ export const DELEGABLE_ROLES: readonly Role[] = delegableRoles();
559
574
  */
560
575
  export const MAX_PERSONAL_TOKEN_MINUTES = 7 * 24 * 60;
561
576
 
577
+ /** The longest a service account's token lives, in days. The vault holds an issue to it (T149). */
578
+ export const MAX_SERVICE_TOKEN_DAYS = 366;
579
+
562
580
  /**
563
581
  * How long a `coffre login` code waits to be approved. The server expires it
564
582
  * then, and the CLI's sign-in hint says so before it has asked for one.
@@ -791,6 +809,75 @@ export function scopeWithReads(
791
809
  return result;
792
810
  }
793
811
 
812
+ /**
813
+ * A scope as a token's or binding's row stores it, under its MAC: its
814
+ * grants as JSON, by place, each with what its role held when it was
815
+ * issued (`issuedGrant`), so that a role widened later widens no credential,
816
+ * and, a service's, whether it reads the sensitive values there.
817
+ */
818
+ export function storedScope(scope: CredentialScope, { reads = false }: { reads?: boolean } = {}): string {
819
+ const key = (grant: CredentialScope[number]) => `${grant.projectId}/${grant.environmentId ?? ''}`;
820
+ return JSON.stringify(
821
+ [...scope]
822
+ .sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0))
823
+ .map((grant) => {
824
+ const { permissions, protected: guarded } = scopeDefinition(grant);
825
+ return {
826
+ projectId: grant.projectId,
827
+ environmentId: grant.environmentId,
828
+ role: grant.role,
829
+ permissions: { normal: [...permissions], protected: [...guarded] },
830
+ ...(grant.sensitive === undefined ? {} : { sensitive: grant.sensitive }),
831
+ // A workload session's, with 0.15's log: the keys its binding lets it read, which its object holds (`sealedSessionScope`).
832
+ ...(!reads || grant.reads === undefined ? {} : { reads: grant.reads }),
833
+ };
834
+ }),
835
+ );
836
+ }
837
+
838
+ /**
839
+ * The scope a row stores: null for one 0.4 made, not sealed yet, which
840
+ * reaches all its account holds, as then. One its MAC checked but that
841
+ * does not read as a scope reaches nothing.
842
+ */
843
+ export function readScope(stored: string | null): CredentialScope | null {
844
+ if (stored === null) return null;
845
+ let parsed: unknown = null;
846
+ try {
847
+ parsed = JSON.parse(stored);
848
+ } catch {}
849
+ return isCredentialScope(parsed) ? parsed : [];
850
+ }
851
+
852
+ /** What a workload binding's policy lists of reads, by environment id (`BindingPolicy['reads']`). */
853
+ type ListedReads = Readonly<Record<string, { readonly keys?: readonly string[] | '*' }>>;
854
+
855
+ /**
856
+ * What a session reaches, as its caller holds it: its row's scope, an
857
+ * enrollment code's, or else its binding's, never null, with its binding's
858
+ * `reads` on the grants of the environments they list (`scopeWithReads`).
859
+ * Binding creation gives each such environment a grant of its own, so the
860
+ * scope itself says each one's project, with nothing to look up. A grant
861
+ * without `reads` is use-only, there.
862
+ */
863
+ export function sessionScope(row: { scope: string | null }, binding: { scope: string | null }, policy: { reads?: ListedReads }): CredentialScope {
864
+ const scope = readScope(row.scope ?? binding.scope) ?? [];
865
+ const projectOf = new Map<string, string>();
866
+ for (const { projectId, environmentId } of scope) if (environmentId != null && projectId !== null) projectOf.set(environmentId, projectId);
867
+ return scopeWithReads(scope, policy.reads, projectOf);
868
+ }
869
+
870
+ /**
871
+ * A workload session's scope as its row stores it with 0.15's log: what its
872
+ * uses hold (`sessionScope`), its binding's per-key reads included, so that
873
+ * its object, all a 0.15 use decides on, is no wider than what 0.14 decides
874
+ * on from its binding. The vault makes it from the binding's columns too,
875
+ * for the session it signs in (T149).
876
+ */
877
+ export function sealedSessionScope(scope: string | null, binding: { scope: string | null }, policy: { reads?: ListedReads }): string {
878
+ return storedScope(sessionScope({ scope }, binding, policy), { reads: true });
879
+ }
880
+
794
881
  /**
795
882
  * Whether the actor may give or take grants at this place: with
796
883
  * `grant.manage` there, from a project grant or an instance role whose