@coffre/client 0.15.0 → 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.
@@ -0,0 +1,57 @@
1
+ //#region src/credential.d.ts
2
+ /** What a cipher's encrypt gives: the IV coffre drew, 12 bytes, the ciphertext, and the 16-byte tag, which the app stores in its own format. */
3
+ type Sealed = {
4
+ iv: Uint8Array;
5
+ ciphertext: Uint8Array;
6
+ tag: Uint8Array;
7
+ };
8
+ type ProxiedCredential = {
9
+ /** The credential's URL on the proxy: `<url>/<path>` is `<upstream>/<path>`. */
10
+ url: string;
11
+ /** `fetch`, at a path under the credential's upstream, with the handle the proxy takes. */
12
+ fetch(path: string, init?: RequestInit): Promise<Response>;
13
+ /**
14
+ * A presigned GET (or HEAD) of `path` under an AWS-signed credential's
15
+ * upstream, `/bucket/key` with each segment encoded as in a URL: coffre
16
+ * signs it with the real key pair, for `expiresIn` seconds (15 minutes
17
+ * unless set, an hour at most), and the URL is the upstream's own, for a
18
+ * browser or anyone to use until then.
19
+ */
20
+ presign(path: string, options?: {
21
+ method?: 'GET' | 'HEAD';
22
+ expiresIn?: number;
23
+ query?: Record<string, string>;
24
+ }): Promise<{
25
+ url: string;
26
+ expiresAt: string;
27
+ }>;
28
+ /**
29
+ * A signature of `message` (a string signs as its UTF-8) by a signer's
30
+ * key, which stays in coffre: a private key's, what Node's
31
+ * `crypto.sign(undefined, message, key)` gives, base64url, each one use
32
+ * in coffre's log; an HMAC secret's, as its `hmac()` writes it. A message
33
+ * past 1 MiB goes raw, its bytes as the request's body, which coffre
34
+ * signs as they come, never held: an `hmac()` signer's whose `maxBytes`
35
+ * takes it, SumSub's document upload say.
36
+ */
37
+ sign(message: Uint8Array | string): Promise<string>;
38
+ /**
39
+ * Whether `signature`, as its header carried it (`sha256=…`), is a
40
+ * verifier's HMAC of `message`: an inbound webhook's body, the bytes as
41
+ * they came, never the JSON parsed and written again. The secret stays
42
+ * in coffre, which compares in constant time and says only yes or no.
43
+ */
44
+ verify(message: Uint8Array | string, signature: string): Promise<boolean>;
45
+ /**
46
+ * `plaintext` (a string as its UTF-8) encrypted with a cipher's AES-256-GCM key, which stays in coffre, under `aad`
47
+ * if given: under an IV coffre draws for each, never the app's.
48
+ */
49
+ encrypt(plaintext: Uint8Array | string, aad?: Uint8Array | string): Promise<Sealed>;
50
+ /** The plaintext `sealed` holds under the cipher's key and `aad`, or null when it does not decrypt: whatever part is wrong, coffre says no more. */
51
+ decrypt(sealed: Sealed, aad?: Uint8Array | string): Promise<Uint8Array | null>;
52
+ };
53
+ type Env = Record<string, string | undefined>;
54
+ /** The credential `name`, as `coffre run` gave the app it; `env` and `fetcher` for tests and odd runtimes. */
55
+ declare function credential(name: string, env?: Env, fetcher?: (input: string, init?: RequestInit) => Promise<Response>): ProxiedCredential;
56
+ //#endregion
57
+ export { Sealed as n, credential as r, ProxiedCredential as t };
@@ -1,54 +1,2 @@
1
- //#region src/credential.d.ts
2
- /**
3
- * A credential through coffre's credential proxy, for an app `coffre run`
4
- * started with placeholders (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, its environment's (`…/use/market/dev/schumann`), and
13
- * `COFFRE_HANDLE`, the handle that stands in for the environment's values;
14
- * the proxy injects the key, and the app never holds it.
15
- */
16
- export type ProxiedCredential = {
17
- /** The credential's URL on the proxy: `<url>/<path>` is `<upstream>/<path>`. */
18
- url: string;
19
- /** `fetch`, at a path under the credential's upstream, with the handle the proxy takes. */
20
- fetch(path: string, init?: RequestInit): Promise<Response>;
21
- /**
22
- * A presigned GET (or HEAD) of `path` under an AWS-signed credential's
23
- * upstream, `/bucket/key` with each segment encoded as in a URL: coffre
24
- * signs it with the real key pair, for `expiresIn` seconds (15 minutes
25
- * unless set, an hour at most), and the URL is the upstream's own, for a
26
- * browser or anyone to use until then.
27
- */
28
- presign(path: string, options?: {
29
- method?: 'GET' | 'HEAD';
30
- expiresIn?: number;
31
- query?: Record<string, string>;
32
- }): Promise<{
33
- url: string;
34
- expiresAt: string;
35
- }>;
36
- /**
37
- * A signature of `message` (a string signs as its UTF-8) by a signer's
38
- * key, which stays in coffre: a private key's, what Node's
39
- * `crypto.sign(undefined, message, key)` gives, base64url, each one use
40
- * in coffre's log; an HMAC secret's, as its `hmac()` writes it.
41
- */
42
- sign(message: Uint8Array | string): Promise<string>;
43
- /**
44
- * Whether `signature`, as its header carried it (`sha256=…`), is a
45
- * verifier's HMAC of `message`: an inbound webhook's body, the bytes as
46
- * they came, never the JSON parsed and written again. The secret stays
47
- * in coffre, which compares in constant time and says only yes or no.
48
- */
49
- verify(message: Uint8Array | string, signature: string): Promise<boolean>;
50
- };
51
- type Env = Record<string, string | undefined>;
52
- /** The credential `name`, as `coffre run` gave the app it; `env` and `fetcher` for tests and odd runtimes. */
53
- export declare function credential(name: string, env?: Env, fetcher?: (input: string, init?: RequestInit) => Promise<Response>): ProxiedCredential;
54
- //#endregion
1
+ import { n as Sealed, r as credential, t as ProxiedCredential } from "./credential-DyAuH0om.js";
2
+ export { ProxiedCredential, Sealed, credential };
@@ -1,4 +1,19 @@
1
+ import { fromBase64url } from "./dpop.js";
1
2
  //#region src/credential.ts
3
+ /**
4
+ * A credential through coffre's credential proxy, for an app `coffre run`
5
+ * started with placeholders (docs/design/credential-proxy.md): where its
6
+ * client takes no base URL to point at the proxy, or the code is new.
7
+ *
8
+ * import { credential } from '@coffre/client/credential';
9
+ * const schumann = credential('schumann');
10
+ * const companies = await (await schumann.fetch('/companies?q=acme')).json();
11
+ *
12
+ * `coffre run` sets `COFFRE_CREDENTIALS`, each credential's URL on the
13
+ * proxy by name, its environment's (`…/use/market/dev/schumann`), and
14
+ * `COFFRE_HANDLE`, the handle that stands in for the environment's values;
15
+ * the proxy injects the key, and the app never holds it.
16
+ */
2
17
  /** The credential `name`, as `coffre run` gave the app it; `env` and `fetcher` for tests and odd runtimes. */
3
18
  function credential(name, env = globalThis.process?.env ?? {}, fetcher = (input, init) => fetch(input, init)) {
4
19
  let urls;
@@ -25,6 +40,24 @@ function credential(name, env = globalThis.process?.env ?? {}, fetcher = (input,
25
40
  body: await answer.json()
26
41
  };
27
42
  };
43
+ /** A message past what JSON takes, signed raw: its bytes as the body, with the SHA-256 that `coffre serve` streams it by, and coffre checks. */
44
+ const raw = async (bytes) => {
45
+ const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
46
+ const answer = await fetcher(`${url.slice(0, url.lastIndexOf("/"))}?sign=${encodeURIComponent(name)}`, {
47
+ method: "POST",
48
+ headers: {
49
+ authorization: `Bearer ${handle}`,
50
+ "content-type": "application/octet-stream",
51
+ "content-length": String(bytes.length),
52
+ "content-digest": `sha-256=:${btoa(String.fromCharCode(...digest))}:`
53
+ },
54
+ body: bytes
55
+ });
56
+ return {
57
+ answer,
58
+ body: await answer.json()
59
+ };
60
+ };
28
61
  const bytesOf = (message) => {
29
62
  const bytes = typeof message === "string" ? new TextEncoder().encode(message) : message;
30
63
  let binary = "";
@@ -54,9 +87,10 @@ function credential(name, env = globalThis.process?.env ?? {}, fetcher = (input,
54
87
  };
55
88
  },
56
89
  sign: async (message) => {
57
- const { answer, body } = await compute({ sign: {
90
+ const bytes = typeof message === "string" ? new TextEncoder().encode(message) : message;
91
+ const { answer, body } = bytes.length > 1048576 ? await raw(bytes) : await compute({ sign: {
58
92
  credential: name,
59
- message: bytesOf(message)
93
+ message: bytesOf(bytes)
60
94
  } });
61
95
  if (!answer.ok || body.signature === void 0) throw new Error(`coffre signed nothing: ${body.message ?? answer.status}`);
62
96
  return body.signature;
@@ -69,6 +103,38 @@ function credential(name, env = globalThis.process?.env ?? {}, fetcher = (input,
69
103
  } });
70
104
  if (!answer.ok || typeof body.valid !== "boolean") throw new Error(`coffre verified nothing: ${body.message ?? answer.status}`);
71
105
  return body.valid;
106
+ },
107
+ encrypt: async (plaintext, aad) => {
108
+ const { answer, body } = await compute({ encrypt: {
109
+ credential: name,
110
+ plaintext: bytesOf(plaintext),
111
+ ...aad === void 0 ? {} : { aad: bytesOf(aad) }
112
+ } });
113
+ const [iv, ciphertext, tag] = [
114
+ body.iv,
115
+ body.ciphertext,
116
+ body.tag
117
+ ].map((part) => typeof part === "string" ? fromBase64url(part) : null);
118
+ if (!answer.ok || !iv || !ciphertext || !tag) throw new Error(`coffre encrypted nothing: ${body.message ?? answer.status}`);
119
+ return {
120
+ iv,
121
+ ciphertext,
122
+ tag
123
+ };
124
+ },
125
+ decrypt: async ({ iv, ciphertext, tag }, aad) => {
126
+ const { answer, body } = await compute({ decrypt: {
127
+ credential: name,
128
+ iv: bytesOf(iv),
129
+ ciphertext: bytesOf(ciphertext),
130
+ tag: bytesOf(tag),
131
+ ...aad === void 0 ? {} : { aad: bytesOf(aad) }
132
+ } });
133
+ if (!answer.ok || body.plaintext !== null && typeof body.plaintext !== "string") throw new Error(`coffre decrypted nothing: ${body.message ?? answer.status}`);
134
+ if (body.plaintext === null) return null;
135
+ const plaintext = fromBase64url(body.plaintext);
136
+ if (plaintext === null) throw new Error("coffre decrypted nothing: its answer is no base64url");
137
+ return plaintext;
72
138
  }
73
139
  };
74
140
  }
@@ -97,6 +97,8 @@ declare function bodyDigest(body: Uint8Array | string): Promise<string>;
97
97
  * not the zone's.
98
98
  */
99
99
  declare const MAX_DIGESTED_BODY: number;
100
+ /** The longest message `sign` sends as JSON, base64url: what coffre reads whole. A longer one goes raw, the body itself. */
101
+ declare const JSON_MESSAGE_BYTES: number;
100
102
  /** A body's `Content-Digest` (RFC 9530) from its SHA-256 in hex, as the SDK and `coffre serve` send it: `sha-256=:<base64>:`. */
101
103
  declare function contentDigest(sha256: string): string;
102
104
  /**
@@ -207,4 +209,4 @@ declare function createProof(key: ProofKey, request: {
207
209
  jti?: string;
208
210
  }): Promise<string>;
209
211
  //#endregion
210
- export { signedHeaders as C, sentTarget as S, tokenDigest as T, declaredDigest as _, ProofClaims as a, generateProofKey as b, UNSIGNED_BODY as c, bodyDigest as d, bodyLine as f, createProof as g, contentDigest as h, METHOD_TOKEN as i, UNSIGNED_HEADERS as l, canonicalRequest as m, MAX_PROOF_LENGTH as n, ProofKey as o, canonicalHtu as p, MAX_SIGNED_HEADERS as r, PublicJwk as s, MAX_DIGESTED_BODY as t, base64url as u, fetchMethod as v, thumbprint as w, requestDigest as x, fromBase64url as y };
212
+ export { sentTarget as C, tokenDigest as E, requestDigest as S, thumbprint as T, createProof as _, METHOD_TOKEN as a, fromBase64url as b, PublicJwk as c, base64url as d, bodyDigest as f, contentDigest as g, canonicalRequest as h, MAX_SIGNED_HEADERS as i, UNSIGNED_BODY as l, canonicalHtu as m, MAX_DIGESTED_BODY as n, ProofClaims as o, bodyLine as p, MAX_PROOF_LENGTH as r, ProofKey as s, JSON_MESSAGE_BYTES as t, UNSIGNED_HEADERS as u, declaredDigest as v, signedHeaders as w, generateProofKey as x, fetchMethod as y };
package/dist/dpop.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- import { C as signedHeaders, S as sentTarget, T as tokenDigest, _ as declaredDigest, a as ProofClaims, b as generateProofKey, c as UNSIGNED_BODY, d as bodyDigest, f as bodyLine, g as createProof, h as contentDigest, i as METHOD_TOKEN, l as UNSIGNED_HEADERS, m as canonicalRequest, n as MAX_PROOF_LENGTH, o as ProofKey, p as canonicalHtu, r as MAX_SIGNED_HEADERS, s as PublicJwk, t as MAX_DIGESTED_BODY, u as base64url, v as fetchMethod, w as thumbprint, x as requestDigest, y as fromBase64url } from "./dpop-CYJtAnvD.js";
2
- export { MAX_DIGESTED_BODY, MAX_PROOF_LENGTH, MAX_SIGNED_HEADERS, METHOD_TOKEN, ProofClaims, ProofKey, PublicJwk, UNSIGNED_BODY, UNSIGNED_HEADERS, base64url, bodyDigest, bodyLine, canonicalHtu, canonicalRequest, contentDigest, createProof, declaredDigest, fetchMethod, fromBase64url, generateProofKey, requestDigest, sentTarget, signedHeaders, thumbprint, tokenDigest };
1
+ import { C as sentTarget, E as tokenDigest, S as requestDigest, T as thumbprint, _ as createProof, a as METHOD_TOKEN, b as fromBase64url, c as PublicJwk, d as base64url, f as bodyDigest, g as contentDigest, h as canonicalRequest, i as MAX_SIGNED_HEADERS, l as UNSIGNED_BODY, m as canonicalHtu, n as MAX_DIGESTED_BODY, o as ProofClaims, p as bodyLine, r as MAX_PROOF_LENGTH, s as ProofKey, t as JSON_MESSAGE_BYTES, u as UNSIGNED_HEADERS, v as declaredDigest, w as signedHeaders, x as generateProofKey, y as fetchMethod } from "./dpop-C9EOdNCi.js";
2
+ export { JSON_MESSAGE_BYTES, MAX_DIGESTED_BODY, MAX_PROOF_LENGTH, MAX_SIGNED_HEADERS, METHOD_TOKEN, ProofClaims, ProofKey, PublicJwk, UNSIGNED_BODY, UNSIGNED_HEADERS, base64url, bodyDigest, bodyLine, canonicalHtu, canonicalRequest, contentDigest, createProof, declaredDigest, fetchMethod, fromBase64url, generateProofKey, requestDigest, sentTarget, signedHeaders, thumbprint, tokenDigest };
package/dist/dpop.js CHANGED
@@ -167,6 +167,8 @@ async function bodyDigest(body) {
167
167
  * not the zone's.
168
168
  */
169
169
  const MAX_DIGESTED_BODY = 99614720;
170
+ /** The longest message `sign` sends as JSON, base64url: what coffre reads whole. A longer one goes raw, the body itself. */
171
+ const JSON_MESSAGE_BYTES = 1048576;
170
172
  /** A body's `Content-Digest` (RFC 9530) from its SHA-256 in hex, as the SDK and `coffre serve` send it: `sha-256=:<base64>:`. */
171
173
  function contentDigest(sha256) {
172
174
  if (!SHA256_HEX.test(sha256)) throw new TypeError("a Content-Digest is made from a SHA-256 in hex");
@@ -324,4 +326,4 @@ async function createProof(key, request) {
324
326
  return `${input}.${base64url(new Uint8Array(signature))}`;
325
327
  }
326
328
  //#endregion
327
- export { MAX_DIGESTED_BODY, MAX_PROOF_LENGTH, MAX_SIGNED_HEADERS, METHOD_TOKEN, UNSIGNED_BODY, UNSIGNED_HEADERS, base64url, bodyDigest, bodyLine, canonicalHtu, canonicalRequest, contentDigest, createProof, declaredDigest, fetchMethod, fromBase64url, generateProofKey, requestDigest, sentTarget, signedHeaders, thumbprint, tokenDigest };
329
+ export { JSON_MESSAGE_BYTES, MAX_DIGESTED_BODY, MAX_PROOF_LENGTH, MAX_SIGNED_HEADERS, METHOD_TOKEN, UNSIGNED_BODY, UNSIGNED_HEADERS, base64url, bodyDigest, bodyLine, canonicalHtu, canonicalRequest, contentDigest, createProof, declaredDigest, fetchMethod, fromBase64url, generateProofKey, requestDigest, sentTarget, signedHeaders, thumbprint, tokenDigest };