@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.
Files changed (56) hide show
  1. package/README.md +1 -1
  2. package/dist/{access-BrdZKp1d.js → access-CF8UG59J.js} +70 -8
  3. package/dist/{access-qkMZa-6Z.d.ts → access-ERdGGHG7.d.ts} +45 -3
  4. package/dist/access.d.ts +2 -2
  5. package/dist/access.js +2 -2
  6. package/dist/envelope.d.ts +28 -9
  7. package/dist/envelope.js +25 -8
  8. package/dist/identity.d.ts +2 -917
  9. package/dist/identity.js +1036 -525
  10. package/dist/index-DuG9p3GH.d.ts +1233 -0
  11. package/dist/kek.d.ts +10 -16
  12. package/dist/kek.js +26 -41
  13. package/dist/log.d.ts +114 -0
  14. package/dist/log.js +291 -0
  15. package/dist/mcp.d.ts +25 -1
  16. package/dist/mcp.js +29 -4
  17. package/dist/recipe-BgJpmJum.d.ts +128 -0
  18. package/dist/recipe.d.ts +2 -127
  19. package/dist/{registry-D7X-x202.d.ts → registry-B7_LUDsJ.d.ts} +30 -5
  20. package/dist/schemas.d.ts +14 -4
  21. package/dist/schemas.js +16 -4
  22. package/dist/{types-Cp3lB_-W.js → types-DwTO_b4H.js} +17 -5
  23. package/dist/vault.d.ts +1800 -299
  24. package/dist/vault.js +99 -32
  25. package/package.json +8 -3
  26. package/src/access.ts +63 -8
  27. package/src/changes/access.ts +140 -0
  28. package/src/changes/freezes.ts +40 -0
  29. package/src/changes/mcp.ts +150 -0
  30. package/src/changes/places.ts +219 -0
  31. package/src/changes/secrets.ts +235 -0
  32. package/src/changes/signin.ts +197 -0
  33. package/src/changes/workloads.ts +166 -0
  34. package/src/context.ts +18 -2
  35. package/src/envelope.ts +35 -12
  36. package/src/identity/auth.ts +11 -3
  37. package/src/identity/aws.ts +62 -0
  38. package/src/identity/github-app.ts +45 -24
  39. package/src/identity/index.ts +3 -0
  40. package/src/identity/profiles.ts +139 -0
  41. package/src/identity/proofs.ts +306 -0
  42. package/src/identity/signin/config.ts +1 -1
  43. package/src/identity/tokens.ts +10 -3
  44. package/src/identity/verifier.ts +73 -14
  45. package/src/identity/workload-token.ts +4 -0
  46. package/src/kek/aws-kms.ts +18 -13
  47. package/src/kek/check.ts +16 -46
  48. package/src/kek/index.ts +2 -2
  49. package/src/kek/types.ts +15 -3
  50. package/src/log/index.ts +7 -0
  51. package/src/log/tiles.ts +166 -0
  52. package/src/log/tree.ts +163 -0
  53. package/src/mcp.ts +34 -3
  54. package/src/schemas.ts +16 -2
  55. package/src/vault.ts +308 -276
  56. package/src/checkpoint.ts +0 -22
@@ -0,0 +1,219 @@
1
+ /** The changes of projects and environments (`packages/vault/src/ops/places.ts`). */
2
+ export type PlacesChanges = ProjectCreate | EnvironmentCreate | ProjectEdit | EnvironmentEdit | FolderRefile | PlaceDelete;
3
+
4
+ /**
5
+ * An edit answers the place as it leaves it, `archivedAt` in ISO 8601;
6
+ * asked for what is so already, it changes nothing, and is logged all the
7
+ * same.
8
+ */
9
+ export type ProjectEdited = { id: string; slug: string; archivedAt: string | null; folder: string | null };
10
+ export type EnvironmentEdited = { id: string; slug: string; archivedAt: string | null; protected: boolean };
11
+
12
+ export type PlacesAnswers = {
13
+ 'project.create': { id: string };
14
+ /**
15
+ * Its slug is the one asked for, or, for a personal config, the one made
16
+ * for it, which only a list for deletion shows. A personal config is
17
+ * `protected` as the environment it is a config of is.
18
+ */
19
+ 'environment.create': { id: string; slug: string; protected: boolean; forked?: Forked };
20
+ /** The projects it filed, by slug. */
21
+ 'folder.refile': { moved: string[] };
22
+ 'project.delete': PlaceDeleted;
23
+ 'environment.delete': PlaceDeleted;
24
+ } & { [K in ProjectEdit['op']]: ProjectEdited } & { [K in EnvironmentEdit['op']]: EnvironmentEdited };
25
+
26
+ /**
27
+ * Make a project, as an Admin or Owner of the instance whose scope takes in
28
+ * new projects, on a session's credential. Its slug is free: no project has
29
+ * it, archived ones included. A slug is 1 to 63 of `a-z`, `0-9` and `-`,
30
+ * starting with a letter or digit; past that the call is a fault, not a
31
+ * refusal: the app checks it first.
32
+ */
33
+ export type ProjectCreate = {
34
+ op: 'project.create';
35
+ project: string;
36
+ };
37
+
38
+ /**
39
+ * Make an environment in a live project, as one who manages its
40
+ * environments (`environment.manage`): its slug free in the project,
41
+ * shaped as a project's and none of a project's pages (`PROJECT_PAGES`).
42
+ * With `parent`, a fork that inherits from that environment, live, never
43
+ * a personal config, which the caller reads, and which inherits from two
44
+ * at most, so that the fork inherits from three; with `copy`, a fork that
45
+ * copies one (`EnvironmentCopy`). A fork of a protected environment is
46
+ * protected, whatever `protected` says.
47
+ *
48
+ * With `mine`, the caller's personal config of `environment` instead: a
49
+ * person's, who reads or uses it, live, never a personal config itself,
50
+ * with two parents at most. One per person per environment. Its slug is
51
+ * made here, and it is protected as its environment is, through it.
52
+ */
53
+ export type EnvironmentCreate = { op: 'environment.create'; project: string; environment: string } & (
54
+ | { mine: false; parent: string | null; protected: boolean; copy?: EnvironmentCopy }
55
+ | { mine: true }
56
+ );
57
+
58
+ /**
59
+ * A fork that copies (docs/design/forking.md, "Forks"): with `copy`, the
60
+ * new environment inherits from nothing (`parent` null) and holds, made in
61
+ * the same change, each key `from` reads now, as a use of it finds them:
62
+ * its own and those it inherits, each from the nearest environment that
63
+ * holds it or dismissed it, with the folder it is filed in there, and none
64
+ * of its history. A key with no value, a reference broken, is left out.
65
+ * Who forks manages the project's environments and reads `from`, and each
66
+ * environment above it a key comes from (`parent_unreadable`); `from` is a
67
+ * live environment of the project, no personal config, whose chain stands
68
+ * (`broken_chain`).
69
+ *
70
+ * Each key is a copy of its value by default: the vault opens the version
71
+ * and seals it again as the new key's first version, and nobody else holds
72
+ * it. It is kept as it was, plain, a secret or sensitive, and its first
73
+ * date is its source's; it has no recipe and is in no pair, as one typed.
74
+ * With `references`, each key is a reference instead, one hop, to where its
75
+ * value is held: the parent's key, a key it inherits, or a reference's
76
+ * source. That is a reference made, as `secret.write` makes one: its
77
+ * forker reads the source where it is held, by their own grants, and uses
78
+ * it there too if it is sensitive. A key whose source they do not is
79
+ * copied, and named in `copied`. A sensitive value reached through a
80
+ * reference is never copied, whatever is asked: a copy would hold it under
81
+ * this project, which another project's value is not. It stays a reference
82
+ * to its source, which its forker must be able to make, or the fork is
83
+ * refused, `no_access`. A workload copies or refers to no value it only
84
+ * uses where it is held (`use_only`).
85
+ *
86
+ * One change opens and seals again 2,000 values at most (`too_many_keys`),
87
+ * and 8 MiB of them as stored (`too_much_to_copy`, the vault's
88
+ * `MOST_COPIED`, which a mark shares): past either, nothing is made, and
89
+ * the fork is made by references or inherits instead. Either is weighed
90
+ * before any value is read: one that copies by default, by every value it
91
+ * copies; one by references, by every value it may copy (each sensitive
92
+ * value its chain holds, and each a reference reads that is not), so past
93
+ * the bound it is refused even where the forker uses most of them, and is
94
+ * made inheriting instead (docs/design/0.16.md, the paragraph on
95
+ * `MOST_COPIED`).
96
+ */
97
+ export type EnvironmentCopy = { from: string; references: boolean };
98
+
99
+ /** What a fork that copies made: how many keys, how many of them references, and those copied where references were asked for. */
100
+ export type Forked = { keys: number; references: number; copied: string[] };
101
+
102
+ /**
103
+ * A project edited, archived or not, by whoever manages it
104
+ * (`project.manage`), on a project there or archived: a deleted one's
105
+ * tombstone is no project.
106
+ *
107
+ * - `project.update`: its slug, to one free as a new project's is.
108
+ * - `project.archive`: refused, `referenced`, while a reference held
109
+ * outside it reads a value in it (D41): archiving would stop that read.
110
+ * - `project.restore`.
111
+ * - `project.move`: filed in a folder, 1 to 64 characters with no `/`, no
112
+ * control character and no space at either end, or in none.
113
+ */
114
+ export type ProjectEdit = { project: string } & (
115
+ | { op: 'project.update'; slug: string }
116
+ | { op: 'project.archive' }
117
+ | { op: 'project.restore' }
118
+ | { op: 'project.move'; folder: string | null }
119
+ );
120
+
121
+ /**
122
+ * An environment edited, there or archived, by whoever manages its
123
+ * project's environments (`environment.manage`), unless said otherwise. A
124
+ * personal config is edited by none of these: it is archived and restored
125
+ * with its environment, and protected through it.
126
+ *
127
+ * - `environment.update`: its slug, to one free in the project and none of
128
+ * a project's pages. Scopes name environments by slug, so this moves who
129
+ * an instance role reaches there.
130
+ * - `environment.archive`, with its personal configs: refused while a live
131
+ * fork inherits from it (`inherited`), or a reference held outside it
132
+ * reads a value in it (`referenced`).
133
+ * - `environment.restore`, with its personal configs: refused while an
134
+ * environment it inherits from is archived or deleted (`parent_archived`),
135
+ * or one is not there to say (`broken_chain`).
136
+ * - `environment.protect`: each role holds there what its protected column
137
+ * says, for people (docs/design/roles.md). Never by a workload's session
138
+ * (`workload_cannot_issue`), which changes no one's access.
139
+ * - `environment.unprotect`: as protecting, and by an Owner of its project
140
+ * alone, by a grant on it or an instance role whose scope takes in all
141
+ * of it, on no credential's scope (`ownsProject`, R30).
142
+ * - `upstream.freeze`: the deployment's upstream credential of that name,
143
+ * `stripe`, used by nobody in this live environment, by whoever writes
144
+ * there (`secret.write`); `upstream.thaw` lifts it, by an Owner of the
145
+ * project (docs/design/workload-access.md, section 8.2).
146
+ */
147
+ export type EnvironmentEdit = { project: string; environment: string } & (
148
+ | { op: 'environment.update'; slug: string }
149
+ | { op: 'environment.archive' }
150
+ | { op: 'environment.restore' }
151
+ | { op: 'environment.protect' }
152
+ | { op: 'environment.unprotect' }
153
+ | { op: 'upstream.freeze'; upstream: string }
154
+ | { op: 'upstream.thaw'; upstream: string }
155
+ );
156
+
157
+ /**
158
+ * A folder of projects renamed, `to` a name shaped as `project.move`
159
+ * takes one, or emptied, `to` null: every project filed there, archived
160
+ * ones included, in one change, by whoever manages each of them
161
+ * (`project.manage`). A folder is a label, so renaming onto one that is
162
+ * there merges the two. A folder none of whose projects the caller may
163
+ * file is no folder of theirs: refused as one with no project.
164
+ */
165
+ export type FolderRefile = { op: 'folder.refile'; folder: string; to: string | null };
166
+
167
+ /**
168
+ * A place deleted for good, as 0.14.7 deleted one (`deletePlace`), in one
169
+ * change: every version under it erased, its ciphertext and wrapped data
170
+ * key emptied, and a plain one's copy cleared; every grant on it revoked;
171
+ * every reference into it or out of it ended, its holder reading nothing
172
+ * since (a reference holds no value of its own); and its slug made a
173
+ * tombstone, `market~deleted-2026-10-05` (`tombstoneOf`), which frees the
174
+ * slug and is never mistaken for what takes it next. Its rows stay, names
175
+ * and dates only, because the log names them. A copy made of one of its
176
+ * values elsewhere, a fork's, is a value of its own and stays. Weighed
177
+ * (`weigh`), it says what it would take, and changes nothing.
178
+ *
179
+ * - `project.delete`: an archived project, with every environment and
180
+ * personal config in it.
181
+ * - `environment.delete`: an archived environment itself, whatever its
182
+ * project is, with its personal configs; refused, `inherited`, while a
183
+ * fork inherits from it, archived or not: deleted, it would leave the
184
+ * fork naming a tombstone.
185
+ *
186
+ * Both by an Admin or Owner of the whole instance, on no credential's
187
+ * scope (`runsInstance`); a place there but live is `not_archived`. A
188
+ * personal config is deleted by its owner, or by whoever manages its
189
+ * project's environments (`environment.manage`), archived or not, never
190
+ * on a personal token (deleting for good stays with people):
191
+ * `environment` names it by its own slug, which only a list for deletion
192
+ * shows, or, with `mine`, the environment it is the caller's config of.
193
+ * A place that holds more versions with a value than one change erases
194
+ * (`MOST_ERASED` in the vault) is refused, `too_large`, and nothing is
195
+ * erased: its environments are deleted one at a time first.
196
+ */
197
+ export type PlaceDelete =
198
+ | { op: 'project.delete'; project: string }
199
+ | { op: 'environment.delete'; project: string; environment: string; mine: boolean };
200
+
201
+ /** What deleting a place takes, or took. */
202
+ export type PlaceDeleted = {
203
+ /** `market`, `market/prod`, or a personal config's `market/dev@ada@acme.example`. */
204
+ path: string;
205
+ /** The slug its tombstone keeps: `market~deleted-2026-10-05`. */
206
+ tombstone: string;
207
+ /** The environments it takes, personal configs too, these by their environment and owner (`dev@ada@acme.example`): a project's every one, or the one with its configs. */
208
+ environments: string[];
209
+ /** The keys named there, which the tombstone keeps, never their values. */
210
+ keys: number;
211
+ /** The versions whose values it erases. */
212
+ versions: number;
213
+ /** The grants on it, lapsed ones too, which it revokes. */
214
+ grants: { member: string; place: string; role: string }[];
215
+ /** The references into it and out of it, which it ends: each holder, and the source it read (`(gone)` for one not found). */
216
+ references: { holder: string; source: string }[];
217
+ /** Members who hold nothing anywhere afterwards, with no instance role: a service among them may be offboarded. */
218
+ stranded: string[];
219
+ };
@@ -0,0 +1,235 @@
1
+ import type { Generation } from '../recipe.ts';
2
+
3
+ /** The changes of keys and their values (`packages/vault/src/ops/secrets.ts`). */
4
+ export type SecretsChanges = SecretWrite | SecretRename | SecretRefile | ReferenceBreak | MissingDismiss;
5
+
6
+ export type SecretsAnswers = {
7
+ /**
8
+ * Each key given a value, written or restored: the version it is at now, and the nature it was written as. A key made a
9
+ * reference is given none. And what the write does to each key asked (`outcomes`), which a dry run tells (`weigh`).
10
+ */
11
+ 'secret.write': { keys: Record<string, { version: number; nature: Nature }>; outcomes: Record<string, KeyOutcome> };
12
+ /** Where the reference read, as its source's rows say: null when the vault does not see them. */
13
+ 'reference.break': { source: SecretPath | null };
14
+ /** The key renamed, by its id. */
15
+ 'secret.rename': { id: string };
16
+ /** The keys filed there, by name, in order. */
17
+ 'secret.refile': { moved: string[] };
18
+ /** What the change did to each key it named: dismissed, restored, or nothing, as it was already. */
19
+ 'missing.dismiss': { keys: Record<string, 'dismissed' | 'restored' | 'unchanged'> };
20
+ };
21
+
22
+ /**
23
+ * What a write does to one key, as 0.14's dry run said it (`DryRunOutcome`):
24
+ * `added`, a key made, by a value or a reference; `archived`; `unchanged`,
25
+ * nothing at all, a key archived already, filed where it is, or made a
26
+ * reference to the source it reads; `changed`, anything else. Or, for a
27
+ * value written over the key's own, live, of the nature it is written as,
28
+ * typed and no reference (`compare`): the same or not only by opening that
29
+ * version, which a decision never does. A dry run asks a use to compare
30
+ * (purpose `compare`), which opens and logs the value as a read: the version
31
+ * named is the one a use must hand back for the answer to stand. The write
32
+ * itself never compares: it writes the value as a new version.
33
+ */
34
+ export type KeyOutcome = 'added' | 'changed' | 'archived' | 'unchanged' | { compare: { secret: string; version: number } };
35
+
36
+ /** A key by where it is held: `market/prod/STRIPE_KEY`. */
37
+ export type SecretPath = { project: string; environment: string; key: string };
38
+
39
+ /** How a value is kept: a secret, a sensitive one that no person is handed back, or a plain one that whoever lists its environment sees. */
40
+ export type Nature = 'secret' | 'sensitive' | 'plain';
41
+
42
+ /**
43
+ * What a write does to one key of its environment, one thing or several:
44
+ *
45
+ * - `value`: the key's next version, the key made if the environment has
46
+ * none by that name. Its `nature` as given, or, given none, the key's
47
+ * own kept, or, where the environment holds none, the one it inherits,
48
+ * and both for an archived key brought back: sensitive stays sensitive, and anything else is written a secret, a
49
+ * plain one's and one inherited from nowhere included. A reference's is
50
+ * its source's.
51
+ * `generated`: a client made it, by that recipe, which Regenerate makes
52
+ * the next one by (`@coffre/core/recipe`), as `formatRecipe` writes it.
53
+ * Never plain. A key pair's recipe writes its two keys together, each
54
+ * naming both, `{ private, public }`, with the same recipe: the two
55
+ * halves of one pair. A value typed, restored or referred to makes none.
56
+ * - `restore`: the key's next version, the value of that version of its
57
+ * own, opened and sealed again by the vault, which never hands it out.
58
+ * The value comes back as it was kept, plain, a secret or sensitive, and
59
+ * sensitive while the key is, as a write with no nature says (above), or
60
+ * while the key's newest value was. Its first date is its source's (the
61
+ * member report's). Made by a recipe or in a pair, it comes back as typed:
62
+ * Regenerate makes a new value, and it pairs with nothing. Whoever restores
63
+ * reads the key there (`secret.read`): the value serves again. And never
64
+ * looser than the newest copy of the same value, by its first date: a
65
+ * value marked sensitive comes back sensitive from a version before the
66
+ * mark, and one marked a secret from its plain version.
67
+ * - `nature` alone (`coffre mark`): the key's value kept, made of that
68
+ * nature, as the key's next version, which the vault opens and seals
69
+ * again: nature and version are in what its encryption names. Its first
70
+ * date, recipe and pair are kept: the value is the same. Stricter only,
71
+ * plain to a secret or sensitive, a secret to sensitive, by whoever
72
+ * writes keys there (`secret.write`); a sensitive value made a secret by
73
+ * an Owner of the project alone, as a person on no credential's scope
74
+ * (`not_owner` to anyone else), and plain never: that takes the value
75
+ * written again (`looser`). The nature it has already writes nothing
76
+ * (`unchanged`). The key is the environment's own, live and holding a
77
+ * value: `archived`, `is_reference` (mark its source), `inherited_key`
78
+ * (mark it where it is held), `no_value`, or `unknown_key`. A change
79
+ * that makes any key looser is logged `secret.loosen`, with every key's
80
+ * line, and `secret.write` otherwise.
81
+ * - `ref`: the key made a reference to that key, which whoever reads this
82
+ * environment then reads through it, value and nature, as it changes. Its
83
+ * own value, if any, is history. The source is a key of a live project and
84
+ * environment, no personal config's, that the writer reads there (and
85
+ * uses, a sensitive one), and that is no reference itself; nor is a key
86
+ * other references read made one: one hop only. A workload refers only to
87
+ * a value it is handed back where it is held, a plain one or one its
88
+ * binding lists.
89
+ * - `archived`: true archives the key, false brings it back. A key is
90
+ * archived with no value written.
91
+ * - `folder`: the folder it is listed in, null for none.
92
+ * - `inherit`, alone: in a fork, true resets the key to what a parent
93
+ * passes down, its own row archived with its history, and false makes
94
+ * its own value serve over that again. Either takes `secret.write`, as
95
+ * writing over a parent's does, and false `secret.read` too: the value
96
+ * serves again. A key no parent passes down is `not_inherited`.
97
+ *
98
+ * Any of these but `inherit` may say what the key read when its author
99
+ * looked (`replaces`): the version the key's value is now, by its id, as a
100
+ * listing gave it (`versionId`), its own live one or, in a fork that holds
101
+ * none live, the one it inherits; `{ source }`, a reference, here or
102
+ * inherited, to that secret, by its id (a listing's `reference.sourceId`);
103
+ * or `null`, a key that reads no value now and is no reference, here or
104
+ * inherited (new, archived with none passed down, or a reference broken).
105
+ * Anything else, a key renamed, archived, made a reference or written
106
+ * since, refuses the write, `stale`: a regenerate, or an MCP approval's
107
+ * change, addresses keys by name, and would otherwise change a key that no
108
+ * longer holds what its person read.
109
+ *
110
+ * A key that gets neither a value nor a reference is one the environment
111
+ * holds. In a fork, a key reset to what it inherits is written over as if
112
+ * it were live: it overrides its parent's again, as 0.14's did.
113
+ */
114
+ export type KeyWrite = { key: string; archived?: boolean; folder?: string | null; replaces?: Replaces; inherit?: undefined } & (
115
+ | { value: string; nature?: Nature; generated?: Generation; ref?: undefined; restore?: undefined }
116
+ | { restore: number; value?: undefined; nature?: undefined; generated?: undefined; ref?: undefined }
117
+ | { ref: SecretPath; value?: undefined; nature?: undefined; generated?: undefined; restore?: undefined }
118
+ | { value?: undefined; nature?: undefined; generated?: undefined; ref?: undefined; restore?: undefined }
119
+ ) | { key: string; nature: Nature; replaces?: Replaces; archived?: undefined; folder?: undefined; inherit?: undefined; value?: undefined; generated?: undefined; ref?: undefined; restore?: undefined }
120
+ | { key: string; inherit: boolean; archived?: undefined; folder?: undefined; value?: undefined; nature?: undefined; generated?: undefined; replaces?: undefined; ref?: undefined; restore?: undefined };
121
+
122
+ /** What a key read when its author looked (`KeyWrite`'s): a version by its id, a reference to a secret by its id, or nothing. */
123
+ export type Replaces = string | null | { source: string };
124
+
125
+ /**
126
+ * Write keys in one environment, all of them or none. 1 to 2,000 keys,
127
+ * each once and named as a key is (`[A-Za-z_][A-Za-z0-9_]{0,127}`); a value
128
+ * is well-formed text with no NUL, 64 Ki characters at most, generated by a recipe as `formatRecipe` writes it, a key pair's two halves both in the write, and replacing a version named by a UUID, and the values
129
+ * of one write 1 MiB of UTF-8 in all, each version restored counted as the most a value weighs, 192 KiB (so 5 at most), since its size is known only once the vault reads it; a version restored a positive integer; a reference's source named by slugs and its key's name; a folder 1 to 64 UTF-16 units, with no slash or control character
130
+ * and nothing `trim` removes at either end (`folderName`); a mark one of the three natures, alone. Past any of these
131
+ * the call is a fault, not a refusal: the app checks them first.
132
+ *
133
+ * In a personal config (`mine`), its owner alone writes, a person
134
+ * (`not_a_person` to a service account), while they read or use the
135
+ * environment it is a config of, and as far as their credential's scope
136
+ * does there; no grant or role reaches it. It holds no reference, and a
137
+ * value written there with no nature over a plain one stays plain: nobody
138
+ * but its owner lists it. A write that gives a key a value makes the
139
+ * config where they have none, as an environment of three parents at most
140
+ * (`too_deep`); anything else asked of a config not there is asked of a
141
+ * key not there.
142
+ */
143
+ export type SecretWrite = {
144
+ op: 'secret.write';
145
+ project: string;
146
+ environment: string;
147
+ /** In the caller's personal config of `environment` (`dev@me`), made by this write if they have none and it gives a key a value. */
148
+ mine?: boolean;
149
+ keys: KeyWrite[];
150
+ };
151
+
152
+ /**
153
+ * A key renamed (`to`), with its history, by whoever writes keys there. A
154
+ * live key, named as `SecretWrite`'s: an archived one is brought back
155
+ * first (`archived`), and a name the environment holds already, archived
156
+ * or not, is `duplicate_key`. Its references read it still, by its id.
157
+ *
158
+ * The name carries down to every environment that inherits from it, forks
159
+ * of forks, archived ones and personal configs included: each one's own
160
+ * row of the key, its override, takes the new name, and so does its
161
+ * dismissal, so each goes on overriding or doing without the key it did.
162
+ * Where one already holds a key of the new name of its own, a shared fork
163
+ * refuses the rename, `duplicate_key_below`; a personal config, named to
164
+ * nobody but its owner, has its own moved out of the way, `NEW_2` (or
165
+ * `_3`, and on). No value moves, so the renamer needs nothing in the
166
+ * forks. Renamed onto its own name, nothing changes. In the caller's
167
+ * personal config (`mine`), as `SecretWrite`'s: a config has no forks.
168
+ */
169
+ export type SecretRename = {
170
+ op: 'secret.rename';
171
+ project: string;
172
+ environment: string;
173
+ /** In the caller's personal config of `environment` (`dev@me`). */
174
+ mine?: boolean;
175
+ key: string;
176
+ to: string;
177
+ /** What the key read when its author looked, as a write's (`KeyWrite`): anything else now, `stale`. */
178
+ replaces?: Replaces;
179
+ };
180
+
181
+ /**
182
+ * A folder of one environment's keys renamed (`to`), or emptied (`to`
183
+ * null): every key filed there, archived ones too, all of them or none, by
184
+ * whoever writes keys there. A folder is a label, so renaming onto one
185
+ * that is there merges the two. A folder no key is filed in is no folder:
186
+ * refused `no_folder`. Folders are named as `SecretWrite`'s; past that, a
187
+ * fault.
188
+ */
189
+ export type SecretRefile = {
190
+ op: 'secret.refile';
191
+ project: string;
192
+ environment: string;
193
+ /** In the caller's personal config of `environment` (`dev@me`). */
194
+ mine?: boolean;
195
+ folder: string;
196
+ to: string | null;
197
+ };
198
+
199
+ /**
200
+ * End the reference a key is: whoever read through it reads nothing there,
201
+ * until the key is given a value or made a reference again. Whoever writes
202
+ * the key may, and whoever manages access in its source's project, who
203
+ * need not see the key's environment at all.
204
+ */
205
+ export type ReferenceBreak = {
206
+ op: 'reference.break';
207
+ project: string;
208
+ environment: string;
209
+ key: string;
210
+ };
211
+
212
+ /**
213
+ * Keys an environment does without (`dismissed: true`), or does again
214
+ * (`false`), 0.14's `setDismissals`, by whoever writes keys there: the
215
+ * team's decision, which its missing keys list leaves out until someone
216
+ * restores it. A key named twice, or a key past 2,000 in one change, is a
217
+ * fault and a refusal (`too_many_keys`) respectively.
218
+ *
219
+ * In a fork, or a personal config (`mine`), a dismissal is also a removal:
220
+ * the environment no longer inherits the key, and a use there reads
221
+ * nothing of it. One it holds a live row of, a value or a reference, would
222
+ * serve whatever is dismissed, so dismissing it is refused, `held_here`:
223
+ * reset it to what it inherits first, or archive it. Outside a fork, such a
224
+ * dismissal is moot, and allowed, as in 0.14.7. A personal config is
225
+ * dismissed in only by its owner, and only once they have one: a
226
+ * dismissal makes none, `no_config`.
227
+ */
228
+ export type MissingDismiss = {
229
+ op: 'missing.dismiss';
230
+ project: string;
231
+ environment: string;
232
+ /** In the caller's personal config of `environment` (`dev@me`). */
233
+ mine?: boolean;
234
+ keys: { key: string; dismissed: boolean }[];
235
+ };
@@ -0,0 +1,197 @@
1
+ /**
2
+ * The changes of sign-in and of credentials (`packages/vault/src/ops/signin.ts`,
3
+ * docs/design/0.16.md, "Signing in").
4
+ */
5
+ export type SigninChanges = Signin | CredentialEnd | AccountLink | AccountUnlink | TokenCreate | DeviceStart | DeviceDecide | DeviceRedeem;
6
+
7
+ export type SigninAnswers = {
8
+ signin: Issued;
9
+ /** The credential ended. */
10
+ 'credential.end': { credential: string };
11
+ /** The identity the account is bound by. */
12
+ 'account.link': { identity: string };
13
+ 'account.unlink': { identity: string };
14
+ /**
15
+ * The token made, and what it reaches, each place by its path and the
16
+ * role there; a service's, the places of those whose sensitive values it
17
+ * will not read (`withheld`, R32), as `token.bind` answers them.
18
+ */
19
+ 'token.create': Issued & { scope: Record<string, string>; withheld?: string[] };
20
+ /** The device login, and when its codes stop being good, ISO 8601. */
21
+ 'device.start': { deviceLogin: string; expiresAt: string };
22
+ /** The device login decided. */
23
+ 'device.decide': { deviceLogin: string };
24
+ /** The CLI's session. */
25
+ 'device.redeem': Issued;
26
+ };
27
+
28
+ /**
29
+ * The operations nobody asks: no credential comes with them, only where
30
+ * their request came from (`Trace`). Each rests on what the app verified,
31
+ * or on a secret of its own (a device code).
32
+ */
33
+ export type Unasked = 'signin' | 'device.start' | 'device.redeem';
34
+
35
+ /**
36
+ * An account at a sign-in provider, as the app verified it with the
37
+ * provider: the vault takes it on the app's word, and its entry says so.
38
+ * `issuer` is the hash the app keeps a provider's issuer by; `emails` are
39
+ * the addresses the provider verified, lowercase, its primary one first, 20
40
+ * at most.
41
+ */
42
+ export type Account = { provider: string; issuer: string; subject: string; emails: string[] };
43
+
44
+ /**
45
+ * A credential to make. The app draws its token and sends the SHA-256,
46
+ * lowercase hex: the vault never sees a token. `minutes` is how long it
47
+ * lasts, within what its kind may.
48
+ */
49
+ export type NewCredential = { token: string; minutes: number; label: string | null };
50
+
51
+ /** A credential made: whose it is, its id, and when it ends, ISO 8601. */
52
+ export type Issued = { principal: string; credential: string; expiresAt: string };
53
+
54
+ /**
55
+ * A person signs in to a browser with an account the app verified.
56
+ *
57
+ * - The account is bound, its identity not revoked: its member signs in,
58
+ * if they are active and of the generation it was bound in
59
+ * (`deactivated` otherwise).
60
+ * - The account is new: the first of its emails that names a member names
61
+ * who it is (`not_registered` for none). They must be active
62
+ * (`deactivated`) and have no account yet (`account_mismatch`: they sign
63
+ * in with the one they have, and link this one). It is bound to them.
64
+ * - An email the vault's configuration names an Owner is a member whatever
65
+ * the rows say: made one, or made an active Owner of the whole instance
66
+ * again, in the same change.
67
+ * - Before the vault has adopted the database nobody signs in
68
+ * (`adopting`, for the app to answer 503). A row the decision would read
69
+ * that is there and not the vault's refuses it (`tampered`).
70
+ *
71
+ * `replaces` is the SHA-256 of the session token the browser showed, if it
72
+ * showed one: that session ends in the same change, whoever's it was.
73
+ */
74
+ export type Signin = { op: 'signin'; account: Account; session: NewCredential; replaces: string | null };
75
+
76
+ /**
77
+ * End a credential: write its row revoked. Ending one that is already
78
+ * ended, expired, not there or not the caller's to end is one refusal,
79
+ * `unknown_credential`, which does not say which.
80
+ *
81
+ * - `credential` null: the one the request came in on, signing out
82
+ * (`sign_out`). Any credential that stands signs itself out but a
83
+ * handle, which is the proxy's; one that does not is told
84
+ * `unauthenticated`, which the app answers as signed out all the same.
85
+ * - `credential` an id (`token.revoke`), by what the route named it as
86
+ * (`of`), and by the callers 0.14.7's route reached: no personal token
87
+ * but on the handles route. A credential with a scope holds nothing of
88
+ * the instance's own (`runsInstance` in @coffre/core/access), so a
89
+ * service's token ends its own service's alone, or one of a service it
90
+ * manages:
91
+ * - `of` null: one of the caller's own, any kind, or anyone's for whoever
92
+ * runs the instance (`DELETE /sessions/:id`, which a workload's session
93
+ * does not reach);
94
+ * - `of` `'handle'`: a handle of the caller's own, and nothing else, on
95
+ * a personal token too (`DELETE /handles/:id`, `coffre run` ending its
96
+ * own);
97
+ * - `of` a member: a token or a workload's session of that member
98
+ * (`DELETE /members/:member/tokens/:id`): theirs, for a person who
99
+ * manages the service account (`managesService`), or for whoever runs
100
+ * the instance.
101
+ */
102
+ export type CredentialEnd = { op: 'credential.end' } & ({ credential: null; of: null } | { credential: string; of: null | 'handle' | { member: string } });
103
+
104
+ /**
105
+ * A person, on a browser session, binds a second account the app verified
106
+ * to themselves. Refused `already_linked` if the account is bound to
107
+ * anyone, themselves included.
108
+ */
109
+ export type AccountLink = { op: 'account.link'; account: Account };
110
+
111
+ /**
112
+ * The caller revokes one of their own accounts, by its identity's id
113
+ * (`unknown_identity` for one that is not theirs, or not bound). The
114
+ * sessions it opened end with it, with no write: the rule that reads them
115
+ * refuses a session whose account is revoked. Their last account too: they
116
+ * sign in again with any account a verified email of theirs names, as the
117
+ * first time.
118
+ */
119
+ export type AccountUnlink = { op: 'account.unlink'; identity: string };
120
+
121
+ /**
122
+ * Make a token (`token.create`), one of three kinds. The app draws it and
123
+ * sends its SHA-256 (`credential`), and its hint as the token's list shows it,
124
+ * its kind's prefix and its last four characters (`coffre_pat_…x7Qd`). Its
125
+ * scope is sealed on its row, each place by id with what its role held
126
+ * there as it was made, and never changes after: a request made with it
127
+ * holds what both that and its member hold then. A credential with a
128
+ * scope never makes one, but a personal token a handle; a personal token
129
+ * asking for a personal token is told what it is (`personal_token`), whoever
130
+ * it names; a workload's session makes none (`workload_cannot_issue`).
131
+ *
132
+ * - `personal`: a person, on a session, for themselves (`member`, the route's
133
+ * `user:<email>`: anyone else's is `no_access`, as 0.14.7 refused a person
134
+ * making another's); a label, a week at most, and a scope by path (`{ "market/dev": "viewer" }`), each role one
135
+ * that manages no access and that they hold all of at its place now, in
136
+ * a project's protected environments too (0.14.7's `personalScope`).
137
+ * - `handle`: a person, on a session or a personal token of theirs, for
138
+ * the proxy (docs/design/credential-proxy.md); a label, a week at most
139
+ * and never past the token it is made on, and the environments it stands
140
+ * in for by path, `@me` for the person's personal config of one. It
141
+ * reaches each, and each parent it inherits from that they read or use,
142
+ * reading where they read and using where they only use.
143
+ * - `service`: a token of the service account `member`, for whoever
144
+ * manages it (`issuesCredential`); a label or none, 366 days at most, and
145
+ * the scope asked or, `scope` null, every grant it holds. Each place
146
+ * reads the sensitive values there only if the caller is an Owner of its
147
+ * project (`ownsProject`, R32). Refused `use_only` on an instance whose
148
+ * services sign in with a key only.
149
+ *
150
+ * A place that is not there and one beyond the caller are one refusal,
151
+ * `no_access`; a role there is not, or one its place does not take,
152
+ * `invalid`; a service's token with nothing to reach, `no_grants`.
153
+ */
154
+ export type TokenCreate = { op: 'token.create'; credential: NewCredential; hint: string } & (
155
+ | { kind: 'personal'; member: string; scope: Record<string, string> }
156
+ | { kind: 'handle'; paths: string[] }
157
+ | { kind: 'service'; member: string; scope: Record<string, string> | null }
158
+ );
159
+
160
+ /**
161
+ * A CLI asks to be signed in from a browser (RFC 8628, `coffre login`).
162
+ * The app draws both codes: the device code, which only the CLI holds and
163
+ * the vault has by its SHA-256 (`code`, lowercase hex), and the user code
164
+ * a person types in their browser (`USER_CODE` in @coffre/core/access).
165
+ * `label` is what the CLI calls itself, as the person approving it sees
166
+ * it. It waits 10 minutes for a decision (`DEVICE_TTL_SECONDS`).
167
+ *
168
+ * Refused `taken` when a row holds either code already, expired or not:
169
+ * the app draws again. Before the vault has adopted the database,
170
+ * `adopting`; with an instance's row that is not the vault's, `tampered`.
171
+ * How many wait at once is the app's to cap, before it asks.
172
+ */
173
+ export type DeviceStart = { op: 'device.start'; code: string; userCode: string; label: string | null };
174
+
175
+ /**
176
+ * A person, on a session of theirs, approves or denies a device login by
177
+ * the user code it shows (`device.approve`, `device.deny`): approved, the
178
+ * CLI that holds its device code collects a session of theirs. One that is
179
+ * not there, decided, or past its 10 minutes is refused `unknown_code`;
180
+ * a token, a service account's or a person's, `no_access`.
181
+ */
182
+ export type DeviceDecide = { op: 'device.decide'; userCode: string; approve: boolean };
183
+
184
+ /**
185
+ * The CLI collects its session, by its device code's SHA-256 (`code`): once
186
+ * a person approved its device login, within its 10 minutes, and once. The
187
+ * session is the approver's, of the generation they approved it in, for
188
+ * `minutes` (365 days at most), labelled as the CLI called itself.
189
+ *
190
+ * The CLI polls until then. Refused, writing nothing (RFC 8628's errors):
191
+ * `pending` while nobody has decided; `denied` once someone denied it, or
192
+ * when its approver is no longer an active member of the generation they
193
+ * approved it in; `expired` for one that is past its 10 minutes, collected
194
+ * already, or not there. `adopting` and `tampered` as for a sign-in, and
195
+ * `tampered` for a device login or its approver written behind the vault.
196
+ */
197
+ export type DeviceRedeem = { op: 'device.redeem'; code: string; session: { token: string; minutes: number } };