@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.
package/src/vault.ts CHANGED
@@ -1,7 +1,9 @@
1
1
  import { createHash } from 'node:crypto';
2
2
 
3
3
  import type { AccessFault } from './access-fault.ts';
4
- import type { CredentialScope, GrantPlace, InstanceRole, Policy, Role, RoleDefinition, Scope, ServiceSetting } from './access.ts';
4
+ import type { CallerKind, CredentialScope, GrantPlace, InstanceRole, Policy, Role, RoleDefinition, Scope, ServiceSetting } from './access.ts';
5
+
6
+ export type { CallerKind } from './access.ts';
5
7
 
6
8
  export { checkpointMessage, checkpointVerifier, verifyCheckpoint } from './checkpoint.ts';
7
9
  export { describeAccessFault, type AccessFault, type FaultGrant, type FaultNames } from './access-fault.ts';
@@ -39,7 +41,10 @@ export interface Vault {
39
41
  * It needs a write grant, not a read one, since the key never leaves the
40
42
  * vault. A new version is never less sensitive than the one it is made
41
43
  * from, or than its secret's newest: a value is made looser only by
42
- * being written again (`invalid`).
44
+ * being written again (`invalid`). Except one: a key's current sensitive
45
+ * value made a secret, in place, by an Owner of its project, or of the
46
+ * whole instance, on no credential's scope (`ownsProject`; `not_allowed`
47
+ * for anyone else), its entry saying `was: 'sensitive'`.
43
48
  */
44
49
  rewrap(input: RewrapInput): Promise<Outcome<Wrapped>>;
45
50
 
@@ -114,7 +119,8 @@ export interface Vault {
114
119
  * Member;
115
120
  * - environments of one project protected, by whoever manages its
116
121
  * environments, before their rows exist too (a fork's); or
117
- * unprotected, by an Owner of the whole instance.
122
+ * unprotected, by an Owner of the project or of the whole instance
123
+ * (`ownsProject`), as far as that project protected them.
118
124
  * The policy after it, and the newest `policy.change`, which it is as of:
119
125
  * the change's own, when it changed anything.
120
126
  */
@@ -211,6 +217,21 @@ export type RefusalCode =
211
217
  * credential proxy, and service accounts read it.
212
218
  */
213
219
  | 'sensitive'
220
+ /**
221
+ * A service account asked for a sensitive value to be handed back on a
222
+ * credential no Owner of its project issued (`readsSensitive`, R32): it
223
+ * reads every other value there, and that one once an Owner issues it a
224
+ * token or binding.
225
+ */
226
+ | 'not_owner_issued'
227
+ /**
228
+ * A workload asked for a value its credential does not list where the
229
+ * value is held (`useOnly`) for anything but the proxy's use: to read
230
+ * it, compare a guess with it or copy it, or to make a reference to it.
231
+ * It uses that value through coffre, and never holds it, nor moves it
232
+ * where it would.
233
+ */
234
+ | 'use_only'
214
235
  /**
215
236
  * The project or environment was deleted for good: nothing under it is
216
237
  * opened or wrapped again, whatever grant would cover it.
@@ -329,12 +350,22 @@ type Correlation = {
329
350
  };
330
351
 
331
352
  /**
332
- * The scope of the credential the request came in on, a service token's or
333
- * a trust binding's: unlike the correlation, the vault decides on it, and
334
- * its principal holds nothing past it (`allows`). Null, or left out, for a
353
+ * The credential the request came in on, which the vault decides on, unlike
354
+ * the correlation.
355
+ *
356
+ * `credentialScope` is a service token's or a trust binding's scope: its
357
+ * principal holds nothing past it (`allows`). Null, or left out, for a
335
358
  * session's, which carries all its member holds.
359
+ *
360
+ * `caller` is what kind of credential it is (`CallerKind`): a person's, on
361
+ * a `user:` principal; a bearer's or a workload's, on a `token:` one. A
362
+ * workload's comes with its scope, or the vault refuses the call outright,
363
+ * and is handed back only the values the scope lists where each is held
364
+ * (`useOnly`, docs/design/workload-access.md, section 6.1): any other is
365
+ * refused `use_only`. An app older than 0.11 says none, and has no
366
+ * workloads: the vault, deployed first, decides for it as before.
336
367
  */
337
- export type Through = { credentialScope?: CredentialScope | null };
368
+ export type Through = { credentialScope?: CredentialScope | null; caller: CallerKind };
338
369
 
339
370
  export type UnwrapInput = Correlation & Through & {
340
371
  principal: string;