@coffre/client 0.3.0 → 0.4.1

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/folders.ts ADDED
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Rows grouped by folder, as every list shows them: those in no folder
3
+ * first, then each folder by name, each keeping the order it was given. A
4
+ * folder only arranges a list (docs/design/environments.md).
5
+ */
6
+ export function byFolder<T extends { folder: string | null }>(rows: readonly T[]): [string | null, T[]][] {
7
+ const groups = new Map<string | null, T[]>([[null, []]]);
8
+ for (const folder of [...new Set(rows.flatMap((row) => (row.folder === null ? [] : [row.folder])))].sort()) groups.set(folder, []);
9
+ for (const row of rows) groups.get(row.folder)!.push(row);
10
+ return [...groups].filter(([, inFolder]) => inFolder.length > 0);
11
+ }
12
+
13
+ /** The folders in use among `rows`, by name. */
14
+ export function foldersOf(rows: readonly { folder: string | null }[]): string[] {
15
+ return [...new Set(rows.flatMap((row) => (row.folder === null ? [] : [row.folder])))].sort();
16
+ }
package/src/index.ts CHANGED
@@ -9,23 +9,33 @@
9
9
  * else: the web app hands requests straight to its router, and the CLI adds
10
10
  * its own handling of Cloudflare Access redirects.
11
11
  */
12
- import type { Api, AuthInfo, BindingPlan, BindingView, DryRunOutcome, DryRunResult, SetResult } from './api.ts';
12
+ import type { Api, AuthInfo, BindingPlan, BindingView, DeletionResult, DryRunOutcome, DryRunResult, SetResult } from './api.ts';
13
13
 
14
14
  export type {
15
15
  AccessValue,
16
16
  Api,
17
+ ApprovalView,
17
18
  AuditEntryView,
18
19
  AuthInfo,
20
+ AuthorizationView,
19
21
  BindingPlan,
20
22
  BindingView,
23
+ ConnectedApp,
24
+ Decision,
25
+ Deletion,
26
+ DeletionResult,
27
+ DismissedKey,
21
28
  DryRunOutcome,
22
29
  DryRunResult,
23
30
  IdentityRow,
24
- InstanceState,
31
+ InheritedGrant,
32
+ ListedReference,
25
33
  Me,
26
34
  Member,
35
+ MissingKey,
27
36
  OffboardingReport,
28
37
  ProjectSummary,
38
+ ReferenceView,
29
39
  RemovedMember,
30
40
  SecretKey,
31
41
  SecretVersion,
@@ -35,6 +45,9 @@ export type {
35
45
  WorkloadIds,
36
46
  } from './api.ts';
37
47
 
48
+ export { byFolder, foldersOf } from './folders.ts';
49
+ export { apiMember, serviceName, shownMember } from './members.ts';
50
+
38
51
  export type RouteKey = keyof Api;
39
52
  /** What a caller sends: the body, or the query string for a GET. */
40
53
  export type RouteInput<K extends RouteKey> = Api[K]['input'];
@@ -151,6 +164,13 @@ export function createClient(options: ClientOptions) {
151
164
  call('PUT /projects/:project', { project }, input),
152
165
  update: (project: string, patch: RouteInput<'PATCH /projects/:project'>) =>
153
166
  call('PATCH /projects/:project', { project }, patch),
167
+ /** What deleting an archived project would erase and revoke; changes nothing. */
168
+ previewDelete: (project: string) => {
169
+ const [method, route] = address('DELETE /projects/:project', { project });
170
+ return send(method, `${route}?dryRun=1`, undefined) as Promise<DeletionResult>;
171
+ },
172
+ /** Delete an archived project for good: its values erased, its grants revoked, its slug free. Owners only. */
173
+ delete: (project: string) => call('DELETE /projects/:project', { project }),
154
174
  },
155
175
 
156
176
  environments: {
@@ -158,6 +178,18 @@ export function createClient(options: ClientOptions) {
158
178
  call('PUT /projects/:project/:environment', place(path), input),
159
179
  update: (path: string, patch: RouteInput<'PATCH /projects/:project/:environment'>) =>
160
180
  call('PATCH /projects/:project/:environment', place(path), patch),
181
+ /** What deleting an archived environment would erase and revoke; changes nothing. */
182
+ previewDelete: (path: string) => {
183
+ const [method, route] = address('DELETE /projects/:project/:environment', place(path));
184
+ return send(method, `${route}?dryRun=1`, undefined) as Promise<DeletionResult>;
185
+ },
186
+ /** Delete an archived environment for good, as a project is. Owners only. */
187
+ delete: (path: string) => call('DELETE /projects/:project/:environment', place(path)),
188
+ /** The keys its sibling environments have and it lacks, those you can see, and those its team dismissed. */
189
+ missing: (path: string) => call('GET /projects/:project/:environment/missing', place(path)),
190
+ /** Dismiss missing keys (`true`) or restore them (`null`). */
191
+ dismiss: (path: string, patch: RouteInput<'PATCH /projects/:project/:environment/dismissals'>) =>
192
+ call('PATCH /projects/:project/:environment/dismissals', place(path), patch),
161
193
  },
162
194
 
163
195
  secrets: {
@@ -187,6 +219,17 @@ export function createClient(options: ClientOptions) {
187
219
  call('PATCH /secrets/:project/:environment/:key', place(path), patch),
188
220
  },
189
221
 
222
+ /**
223
+ * References: secrets read through others (docs/design/environments.md).
224
+ * A key becomes one with `secrets.set(path, { KEY: { ref: 'market/prod/KEY' } })`.
225
+ */
226
+ references: {
227
+ /** The live references into and out of a place, `market`, `market/prod` or `market/prod/KEY`, and who reads through them. */
228
+ list: (path: string) => call('GET /references', {}, { path }),
229
+ /** Break the reference a secret is: its readers stop reading the source through it. */
230
+ break: (path: string) => call('DELETE /secrets/:project/:environment/:key/reference', place(path)),
231
+ },
232
+
190
233
  members: {
191
234
  /** People and tokens, their role and their access; at a place, those who reach it. */
192
235
  list: (path?: string) => call('GET /members', {}, { path }),
@@ -245,6 +288,51 @@ export function createClient(options: ClientOptions) {
245
288
  decide: (code: string, approve: boolean) => call('POST /device-logins/:code', { code }, { approve }),
246
289
  },
247
290
 
291
+ /**
292
+ * Folders, which arrange lists and do nothing else: a folder exists while
293
+ * something is filed in it. Renaming one re-files all of it, onto a folder
294
+ * that exists merges the two; removing one takes all of it out, each item
295
+ * staying where it is, in no folder. Moving one item is `projects.update`
296
+ * or `secrets.update` with a `folder`.
297
+ */
298
+ folders: {
299
+ /** A folder of projects, renamed. Takes managing every project in it. */
300
+ rename: (folder: string, name: string) => call('PATCH /folders/:folder', { folder }, { name }),
301
+ /** Every project out of a folder. */
302
+ remove: (folder: string) => call('DELETE /folders/:folder', { folder }),
303
+ /** One of an environment's key folders, `market/prod`, renamed. Takes writing there. */
304
+ renameKeys: (environment: string, folder: string, name: string) => {
305
+ const { project, environment: slug } = place(environment);
306
+ return call('PATCH /folders/:project/:environment/:folder', { project, environment: slug, folder }, { name });
307
+ },
308
+ /** Every key out of one of an environment's folders. */
309
+ removeKeys: (environment: string, folder: string) => {
310
+ const { project, environment: slug } = place(environment);
311
+ return call('DELETE /folders/:project/:environment/:folder', { project, environment: slug, folder });
312
+ },
313
+ },
314
+
315
+ /**
316
+ * An MCP client asking to connect, by its authorization request, and the
317
+ * person's answer: where to send the browser next.
318
+ */
319
+ oauth: {
320
+ describe: (request: RouteInput<'GET /oauth/authorizations'>) => call('GET /oauth/authorizations', {}, request),
321
+ decide: (input: RouteInput<'POST /oauth/authorizations'>) => call('POST /oauth/authorizations', {}, input),
322
+ },
323
+
324
+ /** The MCP clients I connected. */
325
+ /** A change an MCP client asked for: what it would do, and the person's decision, which makes it. */
326
+ approvals: {
327
+ get: (id: string) => call('GET /approvals/:id', { id }),
328
+ decide: (id: string, input: RouteInput<'POST /approvals/:id'>) => call('POST /approvals/:id', { id }, input),
329
+ },
330
+
331
+ apps: {
332
+ list: () => call('GET /apps', {}),
333
+ disconnect: (id: string) => call('DELETE /apps/:id', { id }),
334
+ },
335
+
248
336
  audit: {
249
337
  list: (query: RouteInput<'GET /audit'> = {}) => call('GET /audit', {}, query),
250
338
  verify: () => call('GET /audit/verification', {}),
package/src/members.ts ADDED
@@ -0,0 +1,23 @@
1
+ /**
2
+ * How members are named, to people and to the API. A service account, a
3
+ * machine identity that signs in by OIDC (trust bindings) or with bearer
4
+ * tokens, is `service:<name>` wherever a person reads or types one. The
5
+ * API, the vault and the audit log keep `token:<name>`, which the log's
6
+ * signed entries hold: so the rename is here, at the edges, and nothing
7
+ * stored or verified changes.
8
+ */
9
+
10
+ /** A member as people read it: `service:deploy` for the API's `token:deploy`; anyone else as they are. */
11
+ export function shownMember(member: string): string {
12
+ return member.startsWith('token:') ? `service:${member.slice('token:'.length)}` : member;
13
+ }
14
+
15
+ /** A member as the API takes it, from what a person typed: `service:deploy` and `token:deploy` alike name a service account. */
16
+ export function apiMember(member: string): string {
17
+ return member.startsWith('service:') ? `token:${member.slice('service:'.length)}` : member;
18
+ }
19
+
20
+ /** A service account's name alone, from any of its forms: `deploy`, `service:deploy` or `token:deploy`. */
21
+ export function serviceName(member: string): string {
22
+ return member.replace(/^(?:service|token):/, '');
23
+ }
package/src/routes.ts CHANGED
@@ -27,11 +27,15 @@ export function getCalls({ places, secrets, members, services }: Subjects): GetC
27
27
  'GET /me': [{ params: {} }],
28
28
  'GET /projects': [{ params: {} }],
29
29
  'GET /secrets/:project/:environment': places.map((params) => ({ params })),
30
+ 'GET /projects/:project/:environment/missing': places.map((params) => ({ params })),
30
31
  'GET /secrets/:project/:environment/:key/versions': secrets.map((params) => ({ params })),
31
32
  'GET /members': [
32
33
  { params: {} },
33
34
  ...(first === undefined ? [] : [{ params: {}, input: { path: `${first.project}/${first.environment}` } }]),
34
35
  ],
36
+ 'GET /references': [
37
+ ...(first === undefined ? [] : [{ params: {}, input: { path: first.project } }, { params: {}, input: { path: `${first.project}/${first.environment}` } }]),
38
+ ],
35
39
  'GET /members/:member': members.map((member) => ({ params: { member } })),
36
40
  'GET /members/:member/tokens': services.map((member) => ({ params: { member } })),
37
41
  'GET /members/:member/bindings': services.map((member) => ({ params: { member } })),
@@ -39,6 +43,9 @@ export function getCalls({ places, secrets, members, services }: Subjects): GetC
39
43
  'GET /sessions': [{ params: {} }],
40
44
  'GET /identities': [{ params: {} }],
41
45
  'GET /device-logins/:code': [{ params: { code: 'BCDF-GHJK' } }],
46
+ 'GET /oauth/authorizations': [{ params: {}, input: { client_id: '00000000-0000-4000-8000-000000000000', redirect_uri: 'https://conformance.invalid/callback' } }],
47
+ 'GET /approvals/:id': [{ params: { id: '00000000-0000-4000-8000-000000000000' } }],
48
+ 'GET /apps': [{ params: {} }],
42
49
  'GET /audit': [{ params: {}, input: { limit: 500 } }, { params: {}, input: { limit: 500, detail: '1' } }],
43
50
  'GET /audit/verification': [{ params: {} }],
44
51
  'GET /audit/keys': [{ params: {} }],
@@ -60,13 +67,23 @@ const EVERY_ROUTE: { [K in RouteKey]: true } = {
60
67
  'GET /projects': true,
61
68
  'PUT /projects/:project': true,
62
69
  'PATCH /projects/:project': true,
70
+ 'DELETE /projects/:project': true,
63
71
  'PUT /projects/:project/:environment': true,
64
72
  'PATCH /projects/:project/:environment': true,
73
+ 'DELETE /projects/:project/:environment': true,
74
+ 'GET /projects/:project/:environment/missing': true,
75
+ 'PATCH /projects/:project/:environment/dismissals': true,
65
76
  'GET /secrets/:project/:environment': true,
66
77
  'PATCH /secrets/:project/:environment': true,
67
78
  'PATCH /secrets/:project/:environment/:key': true,
68
79
  'GET /secrets/:project/:environment/:key/versions': true,
69
80
  'POST /secrets/:project/:environment/:key/restore': true,
81
+ 'DELETE /secrets/:project/:environment/:key/reference': true,
82
+ 'PATCH /folders/:folder': true,
83
+ 'DELETE /folders/:folder': true,
84
+ 'PATCH /folders/:project/:environment/:folder': true,
85
+ 'DELETE /folders/:project/:environment/:folder': true,
86
+ 'GET /references': true,
70
87
  'POST /reveals': true,
71
88
  'GET /members': true,
72
89
  'GET /members/:member': true,
@@ -86,6 +103,12 @@ const EVERY_ROUTE: { [K in RouteKey]: true } = {
86
103
  'DELETE /identities/:id': true,
87
104
  'GET /device-logins/:code': true,
88
105
  'POST /device-logins/:code': true,
106
+ 'GET /oauth/authorizations': true,
107
+ 'POST /oauth/authorizations': true,
108
+ 'GET /approvals/:id': true,
109
+ 'POST /approvals/:id': true,
110
+ 'GET /apps': true,
111
+ 'DELETE /apps/:id': true,
89
112
  'GET /audit': true,
90
113
  'GET /audit/verification': true,
91
114
  'GET /audit/keys': true,