@coffre/core 0.9.0 → 0.10.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.
@@ -220,6 +220,8 @@ function encryptionContext(ctx: SecretContext): Record<string, string> {
220
220
  'coffre:secret': ctx.secretId,
221
221
  // A personal config's owner, hashed: KMS refuses to decrypt under any other.
222
222
  ...(ctx.owner === undefined ? {} : { 'coffre:owner': ctx.owner }),
223
+ // A sensitive value's: KMS refuses to decrypt it as anything else.
224
+ ...(ctx.sensitive === true ? { 'coffre:sensitive': 'true' } : {}),
223
225
  };
224
226
  }
225
227
 
package/src/recipe.ts CHANGED
@@ -225,10 +225,10 @@ export async function generate(recipe: Recipe): Promise<Generated> {
225
225
 
226
226
  /**
227
227
  * What a write of generated values sends, by key: each value with how it
228
- * was made, and for a regenerate the version it replaces, which the server
229
- * holds it to.
228
+ * was made, for a regenerate the version it replaces, which the server
229
+ * holds it to, and who sees it, where the write says.
230
230
  */
231
- export type GeneratedWrite = Record<string, { value: string; generated: Generation; replaces?: string }>;
231
+ export type GeneratedWrite = Record<string, { value: string; generated: Generation; replaces?: string; sensitivity?: 'secret' | 'sensitive' }>;
232
232
 
233
233
  /**
234
234
  * A value made by the recipe for `key`, as a write sends it, and for a key
package/src/schemas.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { z } from 'zod';
2
2
 
3
- import { INSTANCE_ROLE_NAMES, type InstanceRole } from './access.ts';
3
+ import { INSTANCE_ROLE_NAMES, ROLE_ID, type InstanceRole } from './access.ts';
4
4
  import { PROJECT_PAGES } from './pages.ts';
5
5
 
6
6
  export const slug = z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/);
@@ -60,6 +60,9 @@ export const principalType = z.enum(['user', 'service']);
60
60
  export const principalId = z.string().trim().min(1).max(320);
61
61
  export const instanceRole = z.enum(INSTANCE_ROLE_NAMES as [InstanceRole, ...InstanceRole[]]);
62
62
 
63
+ /** A project role's id: one coffre ships, or one an Owner made (`ROLE_ID`). Which the instance defines, its policy says. */
64
+ export const roleId = z.string().regex(ROLE_ID, 'a role is named by lowercase letters, digits and dashes, 2 to 32, starting with a letter');
65
+
63
66
  /** Which projects or environments a scope takes in, by slug: `all`, `{ only: [...] }` or `{ except: [...] }`. */
64
67
  export const scopeFilter = z.union([
65
68
  z.literal('all'),
package/src/vault.ts CHANGED
@@ -1,5 +1,7 @@
1
+ import { createHash } from 'node:crypto';
2
+
1
3
  import type { AccessFault } from './access-fault.ts';
2
- import type { CredentialScope, GrantPlace, InstanceRole, Role, Scope, ServiceSetting } from './access.ts';
4
+ import type { CredentialScope, GrantPlace, InstanceRole, Policy, Role, RoleDefinition, Scope, ServiceSetting } from './access.ts';
3
5
 
4
6
  export { checkpointMessage, checkpointVerifier, verifyCheckpoint } from './checkpoint.ts';
5
7
  export { describeAccessFault, type AccessFault, type FaultGrant, type FaultNames } from './access-fault.ts';
@@ -26,15 +28,20 @@ export interface Vault {
26
28
  /**
27
29
  * Wrap fresh data keys for new versions `principal` writes: all, or none.
28
30
  * `seqs` are the `key.wrap` entries, one per key, which the app's
29
- * `secret.write` entries name as related.
31
+ * `secret.write` entries name as related. `sensitive` says, per key,
32
+ * whether its wrap binds it as sensitive: a vault older than 0.10 answers
33
+ * none, binding none, and the app stores no sensitive version it wrapped.
30
34
  */
31
- wrap(input: WrapInput): Promise<Outcome<{ wrapped: WrappedKey[]; seqs: number[] }>>;
35
+ wrap(input: WrapInput): Promise<Outcome<Wrapped>>;
32
36
  /**
33
37
  * Wrap existing data keys again for new versions of the same secrets,
34
- * under the current key: restoring an old value. It needs a write grant,
35
- * not a read one, since the key never leaves the vault.
38
+ * under the current key: restoring an old value, or making one stricter.
39
+ * It needs a write grant, not a read one, since the key never leaves the
40
+ * vault. A new version is never less sensitive than the one it is made
41
+ * from, or than its secret's newest: a value is made looser only by
42
+ * being written again (`invalid`).
36
43
  */
37
- rewrap(input: RewrapInput): Promise<Outcome<{ wrapped: WrappedKey[]; seqs: number[] }>>;
44
+ rewrap(input: RewrapInput): Promise<Outcome<Wrapped>>;
38
45
 
39
46
  /**
40
47
  * Make secrets references to others: whoever can read the holder's
@@ -90,6 +97,29 @@ export interface Vault {
90
97
  /** Change the instance's settings: those who run it, never anyone else. */
91
98
  setSettings(input: SetSettingsInput): Promise<Outcome<{ settings: Settings }>>;
92
99
 
100
+ /**
101
+ * The instance's access policy (`Policy` in @coffre/core/access): its
102
+ * roles, as an Owner edited and made them, and its protected
103
+ * environments, as the vault's newest `policy.change` says, by its MAC.
104
+ * As it ships, before any. A vault older than 0.10 has none, and the app
105
+ * decides as it ships.
106
+ */
107
+ policy(): Promise<Policy>;
108
+ /**
109
+ * Change the policy by one change, its own `policy.change` entry, which
110
+ * names it and what it was (docs/design/roles.md):
111
+ * - a project or instance role defined, or put back as it ships (null),
112
+ * or, one an Owner made, deleted while no grant names it: an Owner of
113
+ * the whole instance, and never the Owner role, nor the instance's
114
+ * Member;
115
+ * - environments of one project protected, by whoever manages its
116
+ * environments, before their rows exist too (a fork's); or
117
+ * unprotected, by an Owner of the whole instance.
118
+ * The policy after it, and the newest `policy.change`, which it is as of:
119
+ * the change's own, when it changed anything.
120
+ */
121
+ changePolicy(input: ChangePolicyInput): Promise<Outcome<{ policy: Policy; seq: number | null }>>;
122
+
93
123
  /**
94
124
  * Sign the log up to its last entry, in an `audit.checkpoint` entry of
95
125
  * the vault's, if the chain recomputes, the vault's entries by their MACs,
@@ -164,11 +194,11 @@ export type RefusalCode =
164
194
  /** The wrapped key does not belong to the secret it was presented as, or a reference is not the vault's. */
165
195
  | 'bad_claim'
166
196
  /**
167
- * A person asked for values to be handed back, where people get stand-ins
168
- * (`people: 'stand-ins'`): their apps use values through the credential
169
- * proxy instead, and only service accounts read them.
197
+ * A person asked for a sensitive value to be handed back (`handsBack`):
198
+ * nobody sees one, Owners included. Their apps use it through the
199
+ * credential proxy, and service accounts read it.
170
200
  */
171
- | 'stand_ins'
201
+ | 'sensitive'
172
202
  /**
173
203
  * The project or environment was deleted for good: nothing under it is
174
204
  * opened or wrapped again, whatever grant would cover it.
@@ -192,6 +222,11 @@ export type RefusalCode =
192
222
  | 'last_owner'
193
223
  /** Well-formed, but not something the rules allow: a project role on an environment, a service account with an instance role. */
194
224
  | 'invalid'
225
+ /**
226
+ * A change to the policy weighed from one revision of it (`revision`)
227
+ * when another came since: asked again, it is weighed as the policy is now.
228
+ */
229
+ | 'policy_changed'
195
230
  /** The vault's own log no longer carries the head the last checkpoint signed, or does not rehash since. */
196
231
  | 'log_broken'
197
232
  /**
@@ -221,8 +256,19 @@ export type SecretRef = {
221
256
  version: number;
222
257
  /** `market/prod/DATABASE_URL`. */
223
258
  path: string;
259
+ /**
260
+ * Whether the version is sensitive: its value is never handed back to a
261
+ * person, on any credential of theirs, only used for them or read by a
262
+ * service account. Its data key's wrap binds it, so a version written
263
+ * sensitive opens as nothing else. Absent, or false, for a secret or a
264
+ * plain value.
265
+ */
266
+ sensitive?: boolean;
224
267
  };
225
268
 
269
+ /** What a wrap or rewrap answers: each key as wrapped, its entry, and whether its wrap binds it sensitive. */
270
+ export type Wrapped = { wrapped: WrappedKey[]; seqs: number[]; sensitive: boolean[] };
271
+
226
272
  /** A wrapped data key and the key encryption key that wrapped it; `bytes` is base64. */
227
273
  export type WrappedKey = { kekProvider: string; kekId: string; kekVersion: string; bytes: string };
228
274
 
@@ -237,18 +283,22 @@ export type KeyChecks = { current: { kekProvider: string; kekId: string }; check
237
283
  /**
238
284
  * Why someone reads: shown in the log, and the same rules apply to each. A
239
285
  * fork reads to `copy`. The credential proxy reads to `use`, a value it
240
- * injects into a request and never hands back, or to `expose`, one the
241
- * deployment lets people's apps hold. Where people get stand-ins
242
- * (`people: 'stand-ins'`), a person opens nothing to `reveal`, `run` or
243
- * `compare` (`HANDED_BACK`).
286
+ * injects into a request and never hands back, or to `expose`, one it
287
+ * gives a person's app as it is (`coffre run`'s plan).
244
288
  */
245
289
  export type Purpose = 'reveal' | 'run' | 'compare' | 'copy' | 'use' | 'expose';
246
290
 
247
291
  /**
248
- * What a person never opens where people get stand-ins: values handed back
249
- * to them, and a dry run's `compare`, which tells them whether a guess was right.
292
+ * Whether a read hands values back to whoever asked, which a person never
293
+ * gets of a sensitive value: every purpose but the proxy's `use` and a
294
+ * fork's `copy` that keeps them sensitive (`keepsSensitive`), a dry run's
295
+ * `compare` included, which tells them whether a guess was right, and any
296
+ * purpose a later app may name.
250
297
  */
251
- export const HANDED_BACK: readonly Purpose[] = ['reveal', 'run', 'compare'];
298
+ export function handsBack(read: { purpose: string; keepsSensitive?: boolean }): boolean {
299
+ if (read.purpose === 'use') return false;
300
+ return !(read.purpose === 'copy' && read.keepsSensitive === true);
301
+ }
252
302
 
253
303
  /** Ties the vault's entries to the app's request and audit rows. */
254
304
  type Correlation = {
@@ -277,6 +327,13 @@ export type Through = { credentialScope?: CredentialScope | null };
277
327
  export type UnwrapInput = Correlation & Through & {
278
328
  principal: string;
279
329
  purpose: Purpose;
330
+ /**
331
+ * That a `copy` keeps each sensitive value sensitive in what it writes:
332
+ * the vault opens a sensitive value to copy for a person only when told
333
+ * so, which an app older than 0.10, that would write it as a secret
334
+ * anyone with read sees, never says.
335
+ */
336
+ keepsSensitive?: boolean;
280
337
  /**
281
338
  * `via` reads a source's current version through a reference: the vault
282
339
  * checks the reader's grants on the holder's environment, as its
@@ -350,6 +407,8 @@ export type Access = {
350
407
  /** When the status last changed, and who changed it; null for strangers. */
351
408
  since: string | null;
352
409
  by: string | null;
410
+ /** The instance's policy, which every decision about them reads: absent from a vault older than 0.10, which decides as it ships. */
411
+ policy?: Policy;
353
412
  };
354
413
 
355
414
  /**
@@ -411,6 +470,47 @@ export type SetSettingsInput = Correlation & Through & {
411
470
  settings: Settings;
412
471
  };
413
472
 
473
+ /** One change to the policy (`changePolicy`). */
474
+ export type PolicyChange =
475
+ | { kind: 'role'; role: Role; definition: RoleDefinition | null }
476
+ | { kind: 'instance-role'; role: InstanceRole; definition: RoleDefinition | null }
477
+ | { kind: 'protect'; projectId: string; environmentIds: string[]; protected: boolean };
478
+
479
+ /**
480
+ * A policy's revision, as a decision made from it names it: its newest
481
+ * `policy.change` (null for none), and the slug of each environment it
482
+ * protects, by id, which a scoped instance role's filters match, and
483
+ * which a rename or a deletion changes with no `policy.change` of its own
484
+ * (docs/design/roles.md, "What changes the policy"). Equal revisions decide
485
+ * alike.
486
+ *
487
+ * 57.3f9a0c2e81b4d7a6 change 57, prod protected as `prod`
488
+ * 57.b20e94d1c6a8f305 change 57, prod renamed `staging`
489
+ */
490
+ export function policyRevision(seq: number | bigint | null, policy: Pick<Policy, 'protectedIn'>): string {
491
+ const places = Object.values(policy.protectedIn).flat()
492
+ .map(({ environmentId, slug }) => `${environmentId}=${slug ?? ''}`)
493
+ .sort();
494
+ return `${seq === null ? 'none' : String(seq)}.${createHash('sha256').update(places.join('\n')).digest('hex').slice(0, 16)}`;
495
+ }
496
+
497
+ /** A revision as `policyRevision` writes it. */
498
+ export const POLICY_REVISION = /^(none|[1-9][0-9]{0,15})\.[0-9a-f]{16}$/;
499
+
500
+ export type ChangePolicyInput = Correlation & Through & {
501
+ actor: string;
502
+ change: PolicyChange;
503
+ /**
504
+ * The policy the caller decided from, as its revision
505
+ * (`policyRevision`): its newest `policy.change` and the rows of the
506
+ * environments it protects. Refused, `policy_changed`, unless the policy
507
+ * under the vault's head is still that one, so that a request carries on
508
+ * from the policy it made (`seq`) only where nothing came between, and a
509
+ * change previewed is made as previewed. Unchecked when absent.
510
+ */
511
+ revision?: string;
512
+ };
513
+
414
514
  /**
415
515
  * A prefix of the log the vault signed: every entry up to `seq`, the last
416
516
  * of which has `hash`, which pins every byte before it. Kept as the vault's