@coffre/client 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/src/index.ts CHANGED
@@ -10,7 +10,7 @@
10
10
  * its own handling of Cloudflare Access redirects. A request that never
11
11
  * reaches the instance throws `Unreachable`, which says why.
12
12
  */
13
- import type { Api, AuthInfo, BindingPlan, BindingView, DeletionResult, DryRunOutcome, DryRunResult, InheritResult, KeysPlan, RoleImpact, SetResult, TokenPlan } from './api.ts';
13
+ import type { Api, AuthInfo, BindingPlan, DeletionResult, DryRunOutcome, DryRunResult, KeysPlan, RoleImpact, SetResult, TokenPlan } from './api.ts';
14
14
  import { Unreachable } from './reach.ts';
15
15
 
16
16
  export type {
@@ -59,6 +59,7 @@ export type {
59
59
  export { ageInDays, olderThan } from './age.ts';
60
60
  export { byFolder, foldersOf } from './folders.ts';
61
61
  export { apiMember, serviceName, shownMember } from './members.ts';
62
+ export { judgeProofs, type ProofJudgment } from './proofs.ts';
62
63
  export { unreachable, Unreachable } from './reach.ts';
63
64
 
64
65
  export type RouteKey = keyof Api;
@@ -264,10 +265,10 @@ export function createClient(options: ClientOptions) {
264
265
  call('PATCH /secrets/:project/:environment/:key', place(path), patch),
265
266
  /**
266
267
  * In a fork, a key back to its parent's value (`true`), its own kept,
267
- * or its own served again (`false`); `from` holds the parent's.
268
+ * or its own served again (`false`); the answer says which, `inherit`.
268
269
  */
269
270
  inherit: (path: string, inherit: boolean) =>
270
- call('PATCH /secrets/:project/:environment/:key', place(path), { inherit }) as Promise<InheritResult>,
271
+ call('PATCH /secrets/:project/:environment/:key', place(path), { inherit }),
271
272
  },
272
273
 
273
274
  /**
@@ -331,15 +332,15 @@ export function createClient(options: ClientOptions) {
331
332
  return send(method, `${route}?dryRun=1`, input) as Promise<BindingPlan>;
332
333
  },
333
334
  create: (member: string, input: RouteInput<'POST /members/:member/bindings'>) =>
334
- call('POST /members/:member/bindings', { member }, input) as Promise<{ binding: BindingView; replaced: string[] }>,
335
- /** The service's bindings on an issuer that new keys would replace, and the keys as checked; writes nothing. */
335
+ call('POST /members/:member/bindings', { member }, input) as Promise<Extract<RouteOutput<'POST /members/:member/bindings'>, { binding: unknown }>>,
336
+ /** The service's bindings on an issuer that new keys would replace, the keys as checked, and the places they would withhold; writes nothing. */
336
337
  previewKeys: (member: string, input: RouteInput<'POST /members/:member/bindings/keys'>) => {
337
338
  const [method, route] = address('POST /members/:member/bindings/keys', { member });
338
339
  return send(method, `${route}?dryRun=1`, input) as Promise<KeysPlan>;
339
340
  },
340
341
  /** New keys, uploaded, for every binding of the service on the issuer: each replaced by one the same but for them. */
341
342
  replaceKeys: (member: string, input: RouteInput<'POST /members/:member/bindings/keys'>) =>
342
- call('POST /members/:member/bindings/keys', { member }, input) as Promise<{ bindings: BindingView[]; replaced: string[] }>,
343
+ call('POST /members/:member/bindings/keys', { member }, input) as Promise<Extract<RouteOutput<'POST /members/:member/bindings/keys'>, { bindings: unknown }>>,
343
344
  remove: (member: string, id: string) => call('DELETE /members/:member/bindings/:id', { member, id }),
344
345
  /** A GitHub repository's or GitLab project's IDs, which bindings name: a public one's, or one the deployment's GitHub App is installed on. */
345
346
  lookup: (input: RouteInput<'GET /workloads/lookup'>) => call('GET /workloads/lookup', {}, input),
@@ -347,6 +348,19 @@ export function createClient(options: ClientOptions) {
347
348
  repositories: () => call('GET /workloads/repositories', {}),
348
349
  },
349
350
 
351
+ /**
352
+ * Freezes: every use under a target refused from its next request, its
353
+ * sessions kept, until lifted. A target is `instance`, `service:<name>`,
354
+ * `binding:<id>` or `session:<id>`.
355
+ */
356
+ freezes: {
357
+ /** The freezes standing that you may know of: the instance's, and those of the service accounts you manage. */
358
+ list: () => call('GET /freezes', {}),
359
+ freeze: (target: string, reason: string) => call('POST /freezes', {}, { target, reason }),
360
+ /** Lifts it; a target that is not frozen stays so. */
361
+ unfreeze: (target: string) => call('DELETE /freezes/:target', { target }),
362
+ },
363
+
350
364
  access: {
351
365
  /** What they should hold at each place; the server applies the difference. `null` revokes. */
352
366
  set: (member: string, access: RouteInput<'PATCH /access/:member'>) =>
@@ -458,33 +472,8 @@ export function createClient(options: ClientOptions) {
458
472
 
459
473
  audit: {
460
474
  list: (query: RouteInput<'GET /audit'> = {}) => call('GET /audit', {}, query),
461
- /**
462
- * Whether the log holds, from the newest checkpoint; or, with `from`, a
463
- * stretch of the walk from the first entry: `start`, then each `next`
464
- * until it is null (`verifyWhole`).
465
- */
466
- verify: (query: RouteInput<'GET /audit/verification'> = {}) => call('GET /audit/verification', {}, query),
467
- /**
468
- * The walk from the first entry to the head, a stretch a request, each
469
- * as long as the server walks in one: the first stretch that fails, or
470
- * the last. `onStretch` sees each verdict as it comes.
471
- */
472
- verifyWhole: async (onStretch: (verdict: RouteOutput<'GET /audit/verification'>) => void = () => {}) => {
473
- for (let from = 'start'; ;) {
474
- const verdict: RouteOutput<'GET /audit/verification'> = await call('GET /audit/verification', {}, { from });
475
- onStretch(verdict);
476
- if (!verdict.ok || verdict.next === undefined || verdict.next === null) return verdict;
477
- from = verdict.next;
478
- }
479
- },
480
475
  /** What an escrowed key is checked against: public material, for admins and owners of the whole instance. */
481
476
  keys: () => call('GET /audit/keys', {}),
482
- /**
483
- * Accept that entries `from` to `to` are lost for good, as an Owner of
484
- * the whole instance: the audit watch's finding, inside the range, stays
485
- * in the log, and its anchor goes on past them.
486
- */
487
- acceptLoss: (range: RouteInput<'POST /audit/loss'>) => call('POST /audit/loss', {}, range),
488
477
  },
489
478
  };
490
479
  }
package/src/proofs.ts ADDED
@@ -0,0 +1,42 @@
1
+ // What a page of `GET /audit` says of its own proofs, judged once for every
2
+ // caller: `coffre verify instance` and conformance each read a page, wait
3
+ // out the signing race and word what they find, and both hold it to this.
4
+ import type { Api, AuditEntryView } from './api.ts';
5
+
6
+ type Page = Api['GET /audit']['output'];
7
+
8
+ export type ProofJudgment = {
9
+ /** The vault's head the page was proven against; none stands before the signer's first batch. */
10
+ head: Page['head'];
11
+ /** Entries the head numbers, which a page waits for: a batch signed between the head's read and the log's can put every one past it. */
12
+ numbered: number;
13
+ proven: number;
14
+ /** Within the head and not what it signed. */
15
+ failed: AuditEntryView[];
16
+ /** Neither failed nor as the head places it: unproven though the head numbers it, or proven past it. The signer signs in order, so the head numbers the log's first `size` entries. */
17
+ misplaced: AuditEntryView[];
18
+ /** What the page's stretch lacks, by the trees' counts: null when it cannot say, on a page that is not of the whole log, or with no head. */
19
+ missing: Page['holes'];
20
+ /**
21
+ * A page to ask again before judging it, as a race between the head's read and the log's can leave it, honestly:
22
+ * a batch signed in between puts every listed entry past the head, and a pruning committed in between leaves the
23
+ * older head counting uses it removed, a stretch lacking aging entries alone. A fresh page past the race says neither.
24
+ */
25
+ racing: boolean;
26
+ };
27
+
28
+ export function judgeProofs(page: Page): ProofJudgment {
29
+ const { head, entries } = page;
30
+ const within = (entry: AuditEntryView) => head !== null && entry.seq < head.size;
31
+ const numbered = entries.filter(within).length;
32
+ const pruned = page.holes !== null && page.holes.length > 0 && page.holes.every((hole) => hole.kept === 0);
33
+ return {
34
+ head,
35
+ numbered,
36
+ proven: entries.filter((entry) => entry.proof === 'proven').length,
37
+ failed: entries.filter((entry) => entry.proof === 'failed'),
38
+ misplaced: entries.filter((entry) => entry.proof !== 'failed' && within(entry) !== (entry.proof === 'proven')),
39
+ missing: page.holes,
40
+ racing: numbered === 0 || pruned,
41
+ };
42
+ }
package/src/routes.ts CHANGED
@@ -55,7 +55,6 @@ export function getCalls({ places, secrets, members, services }: Subjects): GetC
55
55
  'GET /approvals/:id': [{ params: { id: '00000000-0000-4000-8000-000000000000' } }],
56
56
  'GET /apps': [{ params: {} }],
57
57
  'GET /audit': [{ params: {}, input: { limit: 500 } }, { params: {}, input: { limit: 500, detail: '1' } }],
58
- 'GET /audit/verification': [{ params: {} }],
59
58
  'GET /audit/keys': [{ params: {} }],
60
59
  };
61
60
  }
@@ -139,9 +138,7 @@ const EVERY_ROUTE: { [K in RouteKey]: true } = {
139
138
  'GET /apps': true,
140
139
  'DELETE /apps/:id': true,
141
140
  'GET /audit': true,
142
- 'GET /audit/verification': true,
143
141
  'GET /audit/keys': true,
144
- 'POST /audit/loss': true,
145
142
  };
146
143
 
147
144
  /**
@@ -128,6 +128,21 @@ export class TunnelStream extends Duplex {
128
128
  );
129
129
  }
130
130
 
131
+ /**
132
+ * As a socket's: `opening` until the WebSocket opens; then `open` while
133
+ * both ways are, `readOnly` once the app ended its side, `writeOnly`
134
+ * once coffre ended its own, and `closed` once neither is, or the stream
135
+ * was destroyed. A driver reads it to know whether to say goodbye and wait
136
+ * for the close: postgres.js ends only an open socket, and its `end()`
137
+ * waits for the `close` of any socket that is not closed.
138
+ */
139
+ get readyState(): 'opening' | 'open' | 'readOnly' | 'writeOnly' | 'closed' {
140
+ if (this.destroyed) return 'closed';
141
+ if (!this.#opened) return 'opening';
142
+ if (this.readable && this.writable) return 'open';
143
+ return this.readable ? 'readOnly' : this.writable ? 'writeOnly' : 'closed';
144
+ }
145
+
131
146
  /** node-postgres connects its stream itself; this one is connecting already, and says so with `connect`. */
132
147
  connect(): this {
133
148
  return this;
@@ -365,7 +365,7 @@ export function oidc(token: string | (() => string | Promise<string>), name = 'o
365
365
  * longer show it; the platform's store still holds it.
366
366
  */
367
367
  export function enrollment(code: string | undefined): Proof {
368
- if (code === undefined || !code.startsWith('coffre_enr_')) throw new Error('enrollment(): no enrollment code: CI sets one each deploy, from `coffre enroll <service>`');
368
+ if (code === undefined || !code.startsWith('coffre_enr_')) throw new Error('enrollment(): no enrollment code: no release issues one yet (docs/workloads.md)');
369
369
  const vars = (globalThis as { process?: { env: Env } }).process?.env;
370
370
  for (const [name, value] of Object.entries(vars ?? {})) if (value === code) delete vars![name];
371
371
  return { name: 'enrollment', kind: 'enrollment', prove: async () => ({ enrollment: code }) };