@coffre/client 0.7.0 → 0.8.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.
@@ -0,0 +1,24 @@
1
+ //#region src/credential.d.ts
2
+ /**
3
+ * A credential through coffre's credential proxy, for an app `coffre run`
4
+ * started with stand-ins (docs/design/credential-proxy.md): where its
5
+ * client takes no base URL to point at the proxy, or the code is new.
6
+ *
7
+ * import { credential } from '@coffre/client/credential';
8
+ * const schumann = credential('schumann');
9
+ * const companies = await (await schumann.fetch('/companies?q=acme')).json();
10
+ *
11
+ * `coffre run` sets `COFFRE_CREDENTIALS`, each credential's URL on the
12
+ * proxy by name, and `COFFRE_HANDLE`, the handle that stands in for the
13
+ * environment's values; the proxy injects the key, and the app never holds it.
14
+ */
15
+ export type ProxiedCredential = {
16
+ /** The credential's URL on the proxy: `<url>/<path>` is `<upstream>/<path>`. */
17
+ url: string;
18
+ /** `fetch`, at a path under the credential's upstream, with the handle the proxy takes. */
19
+ fetch(path: string, init?: RequestInit): Promise<Response>;
20
+ };
21
+ type Env = Record<string, string | undefined>;
22
+ /** The credential `name`, as `coffre run` gave the app it; `env` and `fetcher` for tests and odd runtimes. */
23
+ export declare function credential(name: string, env?: Env, fetcher?: (input: string, init?: RequestInit) => Promise<Response>): ProxiedCredential;
24
+ //#endregion
@@ -0,0 +1,26 @@
1
+ //#region src/credential.ts
2
+ /** The credential `name`, as `coffre run` gave the app it; `env` and `fetcher` for tests and odd runtimes. */
3
+ function credential(name, env = globalThis.process?.env ?? {}, fetcher = (input, init) => fetch(input, init)) {
4
+ let urls;
5
+ try {
6
+ urls = JSON.parse(env.COFFRE_CREDENTIALS ?? "{}");
7
+ } catch {
8
+ throw new Error("COFFRE_CREDENTIALS is not what `coffre run` sets: run the app with `coffre run <project>/<environment> -- …`");
9
+ }
10
+ const url = urls[name];
11
+ const handle = env.COFFRE_HANDLE;
12
+ if (typeof url !== "string" || handle === void 0) throw new Error(`no credential ${name} here: \`coffre run\` gives the app the credentials its environment holds, which the deployment's proxy names`);
13
+ return {
14
+ url,
15
+ fetch: (path, init = {}) => {
16
+ const headers = new Headers(init.headers);
17
+ headers.set("x-coffre-handle", handle);
18
+ return fetcher(`${url}${path.startsWith("/") ? "" : "/"}${path}`, {
19
+ ...init,
20
+ headers
21
+ });
22
+ }
23
+ };
24
+ }
25
+ //#endregion
26
+ export { credential };
@@ -1344,6 +1344,21 @@ type Api = {
1344
1344
  }[];
1345
1345
  };
1346
1346
  };
1347
+ "POST /handles": {
1348
+ input: {
1349
+ label: string;
1350
+ paths: string[];
1351
+ expiresInMinutes?: number;
1352
+ };
1353
+ output: {
1354
+ id: string;
1355
+ token: string;
1356
+ expiresAt: string;
1357
+ scope: {
1358
+ [key: string]: "access-manager" | "auditor" | "developer" | "maintainer" | "owner" | "viewer";
1359
+ };
1360
+ };
1361
+ };
1347
1362
  };
1348
1363
  type AccessValue = "access-manager" | "auditor" | "developer" | "maintainer" | "owner" | "viewer" | null | {
1349
1364
  role: "access-manager" | "auditor" | "developer" | "maintainer" | "owner" | "viewer";
@@ -2703,6 +2718,21 @@ declare function createClient(options: ClientOptions): {
2703
2718
  revoked: true;
2704
2719
  }>;
2705
2720
  };
2721
+ /**
2722
+ * Handles: stand-ins a person's app holds in place of an environment's
2723
+ * values, which only the credential proxy (`/use`) takes. The value is
2724
+ * in the answer, and only there; it is revoked as a token is.
2725
+ */
2726
+ handles: {
2727
+ create: (input: RouteInput<"POST /handles">) => Promise<{
2728
+ id: string;
2729
+ token: string;
2730
+ expiresAt: string;
2731
+ scope: {
2732
+ [key: string]: "access-manager" | "auditor" | "developer" | "maintainer" | "owner" | "viewer";
2733
+ };
2734
+ }>;
2735
+ };
2706
2736
  /** Trust bindings: which CI runs may sign in as a service, by their platform's ID token. */
2707
2737
  bindings: {
2708
2738
  list: (member: string) => Promise<{
package/dist/index.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- import { $ as TokenPlan, A as Decision, B as Me, C as ApprovalView, D as BindingPlan, E as AuthorizationView, F as DryRunResult, G as PersonalConfig, H as MemberAccess, I as IdentityRow, J as RemovedMember, K as ProjectSummary, L as InheritResult, M as DeletionResult, N as DismissedKey, O as BindingView, P as DryRunOutcome, Q as SetResult, R as KeysPlan, S as Api, T as AuthInfo, U as MissingKey, V as Member, W as OffboardingReport, X as SecretVersion, Y as SecretKey, Z as SessionRow, _ as byFolder, a as Params, b as olderThan, c as RouteOutput, d as planImport, et as TokenRow, f as Unreachable, g as shownMember, h as serviceName, i as ImportAction, j as Deletion, k as ConnectedApp, l as Transport, m as apiMember, n as CoffreClient, o as RouteInput, p as unreachable, q as ReferenceView, r as CoffreError, s as RouteKey, t as ClientOptions, tt as WorkloadIds, u as createClient, v as foldersOf, w as AuditEntryView, x as AccessValue, y as ageInDays, z as ListedReference } from "./index-D802ZJF6.js";
1
+ import { $ as TokenPlan, A as Decision, B as Me, C as ApprovalView, D as BindingPlan, E as AuthorizationView, F as DryRunResult, G as PersonalConfig, H as MemberAccess, I as IdentityRow, J as RemovedMember, K as ProjectSummary, L as InheritResult, M as DeletionResult, N as DismissedKey, O as BindingView, P as DryRunOutcome, Q as SetResult, R as KeysPlan, S as Api, T as AuthInfo, U as MissingKey, V as Member, W as OffboardingReport, X as SecretVersion, Y as SecretKey, Z as SessionRow, _ as byFolder, a as Params, b as olderThan, c as RouteOutput, d as planImport, et as TokenRow, f as Unreachable, g as shownMember, h as serviceName, i as ImportAction, j as Deletion, k as ConnectedApp, l as Transport, m as apiMember, n as CoffreClient, o as RouteInput, p as unreachable, q as ReferenceView, r as CoffreError, s as RouteKey, t as ClientOptions, tt as WorkloadIds, u as createClient, v as foldersOf, w as AuditEntryView, x as AccessValue, y as ageInDays, z as ListedReference } from "./index-DgII_R1y.js";
2
2
  export { type AccessValue, type Api, type ApprovalView, type AuditEntryView, type AuthInfo, type AuthorizationView, type BindingPlan, type BindingView, ClientOptions, CoffreClient, CoffreError, type ConnectedApp, type Decision, type Deletion, type DeletionResult, type DismissedKey, type DryRunOutcome, type DryRunResult, type IdentityRow, ImportAction, type InheritResult, type KeysPlan, type ListedReference, type Me, type Member, type MemberAccess, type MissingKey, type OffboardingReport, Params, type PersonalConfig, type ProjectSummary, type ReferenceView, type RemovedMember, RouteInput, RouteKey, RouteOutput, type SecretKey, type SecretVersion, type SessionRow, type SetResult, type TokenPlan, type TokenRow, Transport, Unreachable, type WorkloadIds, ageInDays, apiMember, byFolder, createClient, foldersOf, olderThan, planImport, serviceName, shownMember, unreachable };
package/dist/index.js CHANGED
@@ -279,6 +279,12 @@ function createClient(options) {
279
279
  id
280
280
  })
281
281
  },
282
+ /**
283
+ * Handles: stand-ins a person's app holds in place of an environment's
284
+ * values, which only the credential proxy (`/use`) takes. The value is
285
+ * in the answer, and only there; it is revoked as a token is.
286
+ */
287
+ handles: { create: (input) => call("POST /handles", {}, input) },
282
288
  /** Trust bindings: which CI runs may sign in as a service, by their platform's ID token. */
283
289
  bindings: {
284
290
  list: (member) => call("GET /members/:member/bindings", { member }),
package/dist/routes.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { a as Params, o as RouteInput, s as RouteKey } from "./index-D802ZJF6.js";
1
+ import { a as Params, o as RouteInput, s as RouteKey } from "./index-DgII_R1y.js";
2
2
  //#region src/routes.d.ts
3
3
  export type GetKey = Extract<RouteKey, `GET ${string}`>;
4
4
  /** Each GET route, with what to ask it. */
package/dist/routes.js CHANGED
@@ -99,6 +99,7 @@ const EVERY_ROUTE = {
99
99
  "GET /members/:member/tokens": true,
100
100
  "POST /members/:member/tokens": true,
101
101
  "DELETE /members/:member/tokens/:id": true,
102
+ "POST /handles": true,
102
103
  "GET /members/:member/bindings": true,
103
104
  "POST /members/:member/bindings": true,
104
105
  "POST /members/:member/bindings/keys": true,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@coffre/client",
3
- "version": "0.7.0",
3
+ "version": "0.8.0",
4
4
  "description": "The coffre API as typed function calls.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -27,6 +27,11 @@
27
27
  "types": "./dist/routes.d.ts",
28
28
  "default": "./dist/routes.js"
29
29
  },
30
+ "./credential": {
31
+ "coffre:source": "./src/credential.ts",
32
+ "types": "./dist/credential.d.ts",
33
+ "default": "./dist/credential.js"
34
+ },
30
35
  "./package.json": "./package.json"
31
36
  },
32
37
  "devDependencies": {
package/src/api.ts CHANGED
@@ -1347,6 +1347,21 @@ export type Api = {
1347
1347
  }[];
1348
1348
  };
1349
1349
  };
1350
+ "POST /handles": {
1351
+ input: {
1352
+ label: string;
1353
+ paths: string[];
1354
+ expiresInMinutes?: number;
1355
+ };
1356
+ output: {
1357
+ id: string;
1358
+ token: string;
1359
+ expiresAt: string;
1360
+ scope: {
1361
+ [key: string]: "access-manager" | "auditor" | "developer" | "maintainer" | "owner" | "viewer";
1362
+ };
1363
+ };
1364
+ };
1350
1365
  };
1351
1366
 
1352
1367
  export type AccessValue = "access-manager" | "auditor" | "developer" | "maintainer" | "owner" | "viewer" | null | {
@@ -0,0 +1,48 @@
1
+ /**
2
+ * A credential through coffre's credential proxy, for an app `coffre run`
3
+ * started with stand-ins (docs/design/credential-proxy.md): where its
4
+ * client takes no base URL to point at the proxy, or the code is new.
5
+ *
6
+ * import { credential } from '@coffre/client/credential';
7
+ * const schumann = credential('schumann');
8
+ * const companies = await (await schumann.fetch('/companies?q=acme')).json();
9
+ *
10
+ * `coffre run` sets `COFFRE_CREDENTIALS`, each credential's URL on the
11
+ * proxy by name, and `COFFRE_HANDLE`, the handle that stands in for the
12
+ * environment's values; the proxy injects the key, and the app never holds it.
13
+ */
14
+ export type ProxiedCredential = {
15
+ /** The credential's URL on the proxy: `<url>/<path>` is `<upstream>/<path>`. */
16
+ url: string;
17
+ /** `fetch`, at a path under the credential's upstream, with the handle the proxy takes. */
18
+ fetch(path: string, init?: RequestInit): Promise<Response>;
19
+ };
20
+
21
+ type Env = Record<string, string | undefined>;
22
+
23
+ /** The credential `name`, as `coffre run` gave the app it; `env` and `fetcher` for tests and odd runtimes. */
24
+ export function credential(
25
+ name: string,
26
+ env: Env = (globalThis as { process?: { env: Env } }).process?.env ?? {},
27
+ fetcher: (input: string, init?: RequestInit) => Promise<Response> = (input, init) => fetch(input, init),
28
+ ): ProxiedCredential {
29
+ let urls: Record<string, unknown>;
30
+ try {
31
+ urls = JSON.parse(env.COFFRE_CREDENTIALS ?? '{}') as Record<string, unknown>;
32
+ } catch {
33
+ throw new Error('COFFRE_CREDENTIALS is not what `coffre run` sets: run the app with `coffre run <project>/<environment> -- …`');
34
+ }
35
+ const url = urls[name];
36
+ const handle = env.COFFRE_HANDLE;
37
+ if (typeof url !== 'string' || handle === undefined) {
38
+ throw new Error(`no credential ${name} here: \`coffre run\` gives the app the credentials its environment holds, which the deployment's proxy names`);
39
+ }
40
+ return {
41
+ url,
42
+ fetch: (path, init = {}) => {
43
+ const headers = new Headers(init.headers);
44
+ headers.set('x-coffre-handle', handle);
45
+ return fetcher(`${url}${path.startsWith('/') ? '' : '/'}${path}`, { ...init, headers });
46
+ },
47
+ };
48
+ }
package/src/index.ts CHANGED
@@ -292,6 +292,15 @@ export function createClient(options: ClientOptions) {
292
292
  revoke: (member: string, id: string) => call('DELETE /members/:member/tokens/:id', { member, id }),
293
293
  },
294
294
 
295
+ /**
296
+ * Handles: stand-ins a person's app holds in place of an environment's
297
+ * values, which only the credential proxy (`/use`) takes. The value is
298
+ * in the answer, and only there; it is revoked as a token is.
299
+ */
300
+ handles: {
301
+ create: (input: RouteInput<'POST /handles'>) => call('POST /handles', {}, input),
302
+ },
303
+
295
304
  /** Trust bindings: which CI runs may sign in as a service, by their platform's ID token. */
296
305
  bindings: {
297
306
  list: (member: string) => call('GET /members/:member/bindings', { member }),
package/src/routes.ts CHANGED
@@ -100,6 +100,7 @@ const EVERY_ROUTE: { [K in RouteKey]: true } = {
100
100
  'GET /members/:member/tokens': true,
101
101
  'POST /members/:member/tokens': true,
102
102
  'DELETE /members/:member/tokens/:id': true,
103
+ 'POST /handles': true,
103
104
  'GET /members/:member/bindings': true,
104
105
  'POST /members/:member/bindings': true,
105
106
  'POST /members/:member/bindings/keys': true,