@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.
- package/README.md +1 -1
- package/dist/{access-BrdZKp1d.js → access-CF8UG59J.js} +70 -8
- package/dist/{access-qkMZa-6Z.d.ts → access-ERdGGHG7.d.ts} +45 -3
- package/dist/access.d.ts +2 -2
- package/dist/access.js +2 -2
- package/dist/envelope.d.ts +28 -9
- package/dist/envelope.js +25 -8
- package/dist/identity.d.ts +2 -917
- package/dist/identity.js +1036 -525
- package/dist/index-DuG9p3GH.d.ts +1233 -0
- package/dist/kek.d.ts +10 -16
- package/dist/kek.js +26 -41
- package/dist/log.d.ts +114 -0
- package/dist/log.js +291 -0
- package/dist/mcp.d.ts +25 -1
- package/dist/mcp.js +29 -4
- package/dist/recipe-BgJpmJum.d.ts +128 -0
- package/dist/recipe.d.ts +2 -127
- package/dist/{registry-D7X-x202.d.ts → registry-B7_LUDsJ.d.ts} +30 -5
- package/dist/schemas.d.ts +14 -4
- package/dist/schemas.js +16 -4
- package/dist/{types-Cp3lB_-W.js → types-DwTO_b4H.js} +17 -5
- package/dist/vault.d.ts +1800 -299
- package/dist/vault.js +99 -32
- package/package.json +8 -3
- package/src/access.ts +63 -8
- package/src/changes/access.ts +140 -0
- package/src/changes/freezes.ts +40 -0
- package/src/changes/mcp.ts +150 -0
- package/src/changes/places.ts +219 -0
- package/src/changes/secrets.ts +235 -0
- package/src/changes/signin.ts +197 -0
- package/src/changes/workloads.ts +166 -0
- package/src/context.ts +18 -2
- package/src/envelope.ts +35 -12
- package/src/identity/auth.ts +11 -3
- package/src/identity/aws.ts +62 -0
- package/src/identity/github-app.ts +45 -24
- package/src/identity/index.ts +3 -0
- package/src/identity/profiles.ts +139 -0
- package/src/identity/proofs.ts +306 -0
- package/src/identity/signin/config.ts +1 -1
- package/src/identity/tokens.ts +10 -3
- package/src/identity/verifier.ts +73 -14
- package/src/identity/workload-token.ts +4 -0
- package/src/kek/aws-kms.ts +18 -13
- package/src/kek/check.ts +16 -46
- package/src/kek/index.ts +2 -2
- package/src/kek/types.ts +15 -3
- package/src/log/index.ts +7 -0
- package/src/log/tiles.ts +166 -0
- package/src/log/tree.ts +163 -0
- package/src/mcp.ts +34 -3
- package/src/schemas.ts +16 -2
- package/src/vault.ts +308 -276
- 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 } };
|