@coffre/client 0.10.2 → 0.11.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/dist/dpop-C5Zyaixy.d.ts +183 -0
- package/dist/dpop.d.ts +2 -0
- package/dist/dpop.js +290 -0
- package/dist/{index-D86fJBDd.d.ts → index--nfmYCFv.d.ts} +222 -13
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -485
- package/dist/routes.d.ts +1 -1
- package/dist/routes.js +13 -0
- package/dist/src-CDyZe9vW.js +490 -0
- package/dist/workload-9LPBYMmN.d.ts +250 -0
- package/dist/workload-postgres.d.ts +54 -0
- package/dist/workload-postgres.js +210 -0
- package/dist/workload-w4QPSyjj.js +1018 -0
- package/dist/workload.d.ts +3 -0
- package/dist/workload.js +3 -0
- package/package.json +16 -1
- package/src/api.ts +178 -10
- package/src/dpop.ts +301 -0
- package/src/index.ts +3 -1
- package/src/routes.ts +10 -0
- package/src/workload-postgres.ts +254 -0
- package/src/workload-proofs.ts +365 -0
- package/src/workload.ts +711 -0
package/src/dpop.ts
ADDED
|
@@ -0,0 +1,301 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The signing half of a workload's proofs (docs/design/workload-access.md,
|
|
3
|
+
* section 5.1): DPoP (RFC 9449) with two claims of coffre's own, `hdr` and
|
|
4
|
+
* `req`, which sign the request's headers, query and body as well as its
|
|
5
|
+
* method and URL. The SDK and the server run this one canonicalization, so
|
|
6
|
+
* what a workload signs is exactly what coffre recomputes and forwards;
|
|
7
|
+
* the server's verifier is `verifyProof` in `@coffre/core/identity`.
|
|
8
|
+
*
|
|
9
|
+
* WebCrypto only, and no dependency, like the rest of the client.
|
|
10
|
+
*
|
|
11
|
+
* A proof is a compact JWS:
|
|
12
|
+
*
|
|
13
|
+
* { "typ": "dpop+jwt", "alg": "ES256", "jwk": { "kty": "EC", "crv": "P-256", "x": "…", "y": "…" } }
|
|
14
|
+
* { "jti": "pA6p8w2Yb3fQe1kHn0S9qg", "htm": "POST", "htu": "https://secrets.acme.example/use/stripe/v1/charges",
|
|
15
|
+
* "iat": 1792805400, "ath": "fUHy…", "nonce": "g1.7Hq2…",
|
|
16
|
+
* "hdr": "content-type idempotency-key", "req": "kq9V…" }
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
/** The longest proof, in characters, which the verifier refuses past and the signer never makes. */
|
|
20
|
+
export const MAX_PROOF_LENGTH = 2048;
|
|
21
|
+
/** The most headers one proof signs: the verifier refuses more, and the signer signs no more. */
|
|
22
|
+
export const MAX_SIGNED_HEADERS = 32;
|
|
23
|
+
|
|
24
|
+
/** A P-256 public key, as a proof carries it: these four members and nothing else. */
|
|
25
|
+
export type PublicJwk = { kty: 'EC'; crv: 'P-256'; x: string; y: string };
|
|
26
|
+
|
|
27
|
+
/** A workload's key: the private half non-extractable, and the public half as a proof names it. */
|
|
28
|
+
export type ProofKey = { privateKey: CryptoKey; jwk: PublicJwk };
|
|
29
|
+
|
|
30
|
+
/** What a proof's payload holds. `ath` signs the token, `hdr` and `req` the rest of the request. */
|
|
31
|
+
export type ProofClaims = {
|
|
32
|
+
jti: string;
|
|
33
|
+
htm: string;
|
|
34
|
+
htu: string;
|
|
35
|
+
iat: number;
|
|
36
|
+
ath?: string;
|
|
37
|
+
nonce?: string;
|
|
38
|
+
hdr?: string;
|
|
39
|
+
req?: string;
|
|
40
|
+
};
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Headers a proof never signs, so neither forwards: those the transport
|
|
44
|
+
* owns and an intermediary may rewrite, the credentials of the request to
|
|
45
|
+
* coffre itself, and cookies. Coffre sets the transport's own on the way out.
|
|
46
|
+
*/
|
|
47
|
+
export const UNSIGNED_HEADERS: ReadonlySet<string> = new Set([
|
|
48
|
+
'accept-encoding',
|
|
49
|
+
'authorization',
|
|
50
|
+
'connection',
|
|
51
|
+
'content-length',
|
|
52
|
+
'cookie',
|
|
53
|
+
'dpop',
|
|
54
|
+
'host',
|
|
55
|
+
'keep-alive',
|
|
56
|
+
'proxy-authenticate',
|
|
57
|
+
'proxy-authorization',
|
|
58
|
+
'proxy-connection',
|
|
59
|
+
'te',
|
|
60
|
+
'trailer',
|
|
61
|
+
'transfer-encoding',
|
|
62
|
+
'upgrade',
|
|
63
|
+
]);
|
|
64
|
+
|
|
65
|
+
const ENCODER = new TextEncoder();
|
|
66
|
+
|
|
67
|
+
/** Bytes as base64url, without padding. */
|
|
68
|
+
export function base64url(bytes: Uint8Array): string {
|
|
69
|
+
let binary = '';
|
|
70
|
+
for (const byte of bytes) binary += String.fromCharCode(byte);
|
|
71
|
+
return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Base64url without padding, back to bytes; null for anything else, or for a
|
|
76
|
+
* spelling that is not the one `base64url` writes (stray bits in its last
|
|
77
|
+
* character), so that one value has one spelling.
|
|
78
|
+
*/
|
|
79
|
+
export function fromBase64url(text: string): Uint8Array | null {
|
|
80
|
+
if (!/^[A-Za-z0-9_-]*$/.test(text) || text.length % 4 === 1) return null;
|
|
81
|
+
const binary = atob(text.replace(/-/g, '+').replace(/_/g, '/'));
|
|
82
|
+
const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
|
|
83
|
+
return base64url(bytes) === text ? bytes : null;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
async function sha256(data: Uint8Array | string): Promise<Uint8Array> {
|
|
87
|
+
const bytes = typeof data === 'string' ? ENCODER.encode(data) : data;
|
|
88
|
+
return new Uint8Array(await crypto.subtle.digest('SHA-256', bytes as Uint8Array<ArrayBuffer>));
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
function hex(bytes: Uint8Array): string {
|
|
92
|
+
return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** The key's RFC 7638 thumbprint, `jkt`: base64url SHA-256 of its required members in this order, 43 characters. */
|
|
96
|
+
export async function thumbprint(jwk: PublicJwk): Promise<string> {
|
|
97
|
+
return base64url(await sha256(JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y })));
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** A new key for a process: P-256, its private half never exportable, never written anywhere. */
|
|
101
|
+
export async function generateProofKey(): Promise<ProofKey> {
|
|
102
|
+
const pair = await crypto.subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, false, ['sign', 'verify']);
|
|
103
|
+
const { kty, crv, x, y } = await crypto.subtle.exportKey('jwk', pair.publicKey);
|
|
104
|
+
return { privateKey: pair.privateKey, jwk: { kty: kty as 'EC', crv: crv as 'P-256', x: x!, y: y! } };
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/** A method, as RFC 9110 writes one: a token, of any length the proof's own limit leaves. */
|
|
108
|
+
export const METHOD_TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
|
|
109
|
+
|
|
110
|
+
/** RFC 3986's unreserved characters, which an escape never needs. */
|
|
111
|
+
const UNRESERVED = /^[A-Za-z0-9\-._~]$/;
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* A URL as `htu` names it: scheme and host lowercased, no default port, no
|
|
115
|
+
* user, query or fragment, and its path as Cloudflare's zones normalize an
|
|
116
|
+
* incoming one by default, in their order: an escaped unreserved character
|
|
117
|
+
* decoded and every other escape's hex in upper case (RFC 3986, section
|
|
118
|
+
* 6.2.2), `\` made `/`, runs of `/` merged, then dot segments removed.
|
|
119
|
+
* Both sides sign this form, so a zone's normalization changes nothing, and
|
|
120
|
+
* a mismatch fails closed. Idempotent. Throws on a URL that is not http or
|
|
121
|
+
* https, and on a `%` that two hex digits do not follow, which would let
|
|
122
|
+
* two paths read as one.
|
|
123
|
+
*
|
|
124
|
+
* canonicalHtu('HTTPS://Secrets.Acme.Example:443//use/%7estripe/a%2fb?x=1')
|
|
125
|
+
* === 'https://secrets.acme.example/use/~stripe/a%2Fb'
|
|
126
|
+
* canonicalHtu('https://secrets.acme.example/hello//../path')
|
|
127
|
+
* === 'https://secrets.acme.example/path'
|
|
128
|
+
*/
|
|
129
|
+
export function canonicalHtu(input: string | URL): string {
|
|
130
|
+
const url = new URL(String(input));
|
|
131
|
+
if (url.protocol !== 'https:' && url.protocol !== 'http:') throw new TypeError(`a proof signs an http or https URL, not ${url.protocol}`);
|
|
132
|
+
// The path as given, before the WHATWG parser removes its dot segments, which it would do before merging slashes.
|
|
133
|
+
// A `\` ends the authority as `/` does, and any run of either starts it, as the WHATWG parser reads an http(s) URL: the path fetch sends.
|
|
134
|
+
const raw = typeof input === 'string' ? /^[^:/\\?#]+:[/\\]{2,}[^/\\?#]*([^?#]*)/.exec(input)?.[1] ?? url.pathname : url.pathname;
|
|
135
|
+
if (/%(?![0-9A-Fa-f]{2})/.test(raw)) throw new TypeError('a URL a proof signs escapes a character with % and two hex digits, never a lone %');
|
|
136
|
+
const decoded = raw.replace(/%([0-9A-Fa-f]{2})/g, (_, code: string) => {
|
|
137
|
+
const char = String.fromCharCode(parseInt(code, 16));
|
|
138
|
+
return UNRESERVED.test(char) ? char : `%${code.toUpperCase()}`;
|
|
139
|
+
});
|
|
140
|
+
const merged = decoded.replace(/\\/g, '/').replace(/\/{2,}/g, '/');
|
|
141
|
+
// Then as the parser writes a path: characters a path never holds raw escaped, as fetch sends them.
|
|
142
|
+
return `${url.protocol}//${url.host}${new URL(withoutDotSegments(merged.startsWith('/') ? merged : `/${merged}`), url.origin).pathname}`;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/** RFC 3986's `remove_dot_segments` (section 5.2.4), on an absolute path. */
|
|
146
|
+
function withoutDotSegments(path: string): string {
|
|
147
|
+
const kept: string[] = [];
|
|
148
|
+
const parts = path.split('/').slice(1);
|
|
149
|
+
parts.forEach((part, i) => {
|
|
150
|
+
if (part !== '.' && part !== '..') kept.push(part);
|
|
151
|
+
else {
|
|
152
|
+
if (part === '..') kept.pop();
|
|
153
|
+
// `/a/b/..` is `/a/`: a dot segment last leaves its slash.
|
|
154
|
+
if (i === parts.length - 1) kept.push('');
|
|
155
|
+
}
|
|
156
|
+
});
|
|
157
|
+
return `/${kept.join('/')}`;
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/**
|
|
161
|
+
* A method as `htm` names it, and the Fetch API sends it: one of DELETE,
|
|
162
|
+
* GET, HEAD, OPTIONS, POST and PUT in upper case, whatever case it was
|
|
163
|
+
* given in, and any other exactly as given. Methods are case-sensitive
|
|
164
|
+
* (RFC 9110, section 9.1), so `patch` is not `PATCH`, and a proof signs one.
|
|
165
|
+
*/
|
|
166
|
+
export function fetchMethod(method: string): string {
|
|
167
|
+
if (!METHOD_TOKEN.test(method)) throw new TypeError(`${JSON.stringify(method)} is no HTTP method: a method is a token (RFC 9110, section 9.1)`);
|
|
168
|
+
const upper = method.toUpperCase();
|
|
169
|
+
return ['DELETE', 'GET', 'HEAD', 'OPTIONS', 'POST', 'PUT'].includes(upper) ? upper : method;
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
/** The SHA-256 of a buffered body, in hex, as a canonical request's last line holds it. */
|
|
173
|
+
export async function bodyDigest(body: Uint8Array | string): Promise<string> {
|
|
174
|
+
return hex(await sha256(body));
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/** `ath`: base64url SHA-256 of the session token the proof is sent with. */
|
|
178
|
+
export async function tokenDigest(token: string): Promise<string> {
|
|
179
|
+
return base64url(await sha256(token));
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/**
|
|
183
|
+
* A canonical request's last line for a body no digest binds: a streamed
|
|
184
|
+
* upload whose SigV4 `x-amz-content-sha256` is `UNSIGNED-PAYLOAD` or
|
|
185
|
+
* `STREAMING-…`. Coffre takes it only through a credential that says
|
|
186
|
+
* `unsignedUploads`, whose page notes what that leaves open.
|
|
187
|
+
*/
|
|
188
|
+
export const UNSIGNED_BODY = 'UNSIGNED-PAYLOAD';
|
|
189
|
+
|
|
190
|
+
const SHA256_HEX = /^[0-9a-f]{64}$/;
|
|
191
|
+
|
|
192
|
+
/**
|
|
193
|
+
* A body's line in `req` (section 5.1), one rule for the SDK and coffre,
|
|
194
|
+
* each from what it knows of the body:
|
|
195
|
+
*
|
|
196
|
+
* - `declared`: its `x-amz-content-sha256`, given only through a credential
|
|
197
|
+
* `sigv4` signs; null otherwise, or when it sets none.
|
|
198
|
+
* - `length`: its bytes as known: those read, a stream's `content-length`,
|
|
199
|
+
* or null for a stream of no stated length.
|
|
200
|
+
*
|
|
201
|
+
* A body of no bytes signs the empty body's digest, whatever it declares.
|
|
202
|
+
* One that declares a hash signs it, which S3 checks against the bytes, so
|
|
203
|
+
* it may stream: 64 lower-case hex digits, or `UNSIGNED_BODY` for any other
|
|
204
|
+
* value. Every other body signs its bytes' digest (`bytes`, none for none).
|
|
205
|
+
*
|
|
206
|
+
* bodyLine({ declared: null, length: 6, bytes }) bodyDigest(bytes)
|
|
207
|
+
* bodyLine({ declared: 'UNSIGNED-PAYLOAD', length: 0 }) bodyDigest('')
|
|
208
|
+
* bodyLine({ declared: 'UNSIGNED-PAYLOAD', length: null }) UNSIGNED_BODY
|
|
209
|
+
* bodyLine({ declared: '9f86…0f00a08', length: 4 }) '9f86…0f00a08'
|
|
210
|
+
*/
|
|
211
|
+
export async function bodyLine(body: { declared: string | null; length: number | null; bytes?: Uint8Array | null }): Promise<string> {
|
|
212
|
+
if (body.declared !== null && body.length !== 0) return SHA256_HEX.test(body.declared) ? body.declared : UNSIGNED_BODY;
|
|
213
|
+
return bodyDigest(body.bytes ?? new Uint8Array());
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/**
|
|
217
|
+
* What `req` signs, one line each:
|
|
218
|
+
*
|
|
219
|
+
* <the path as sent, as the WHATWG parser writes it: every slash and escape kept>
|
|
220
|
+
* <the raw query string as sent, without "?", or empty>
|
|
221
|
+
* <name>:<value> for each header `hdr` names, in its order, its value as received
|
|
222
|
+
* <the body's SHA-256, in lower-case hex>
|
|
223
|
+
*
|
|
224
|
+
* `htu` signs the path as a zone normalizes it, so a proof still holds
|
|
225
|
+
* behind one; this line signs it as it goes upstream, so `/use/s3/a/b` and
|
|
226
|
+
* `/use/s3/a//b`, one object and another to S3, are two requests. A path a
|
|
227
|
+
* zone changed fails closed. The body's line is its buffered bytes' digest
|
|
228
|
+
* (`bodyDigest`), or, for a streamed upload through a credential `sigv4`
|
|
229
|
+
* signs, the 64 hex digits its `x-amz-content-sha256` declares, which S3
|
|
230
|
+
* checks against the bytes; any other declared value is `UNSIGNED_BODY`. A
|
|
231
|
+
* header sent several times is one value, joined by `, `, as `Headers`
|
|
232
|
+
* gives it. No line holds a line break, so no two requests read as one;
|
|
233
|
+
* throws on one that does, or on a body line that is neither.
|
|
234
|
+
*/
|
|
235
|
+
export function canonicalRequest(request: { path: string; query: string; headers: readonly (readonly [string, string])[]; body: string }): string {
|
|
236
|
+
const lines = [request.path, request.query, ...request.headers.map(([name, value]) => `${name}:${value}`)];
|
|
237
|
+
if (lines.some((line) => /[\r\n]/.test(line))) throw new TypeError('a signed request holds no line break in its path, query or headers');
|
|
238
|
+
if (!SHA256_HEX.test(request.body) && request.body !== UNSIGNED_BODY) throw new TypeError('a signed request\'s body is a SHA-256 in hex, or UNSIGNED_BODY');
|
|
239
|
+
return `${lines.map((line) => `${line}\n`).join('')}${request.body}`;
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/** The path and the query a URL sends, as `canonicalRequest` signs them. */
|
|
243
|
+
export function sentTarget(url: string | URL): { path: string; query: string } {
|
|
244
|
+
const parsed = new URL(String(url));
|
|
245
|
+
return { path: parsed.pathname, query: parsed.search.slice(1) };
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/** `req`: base64url SHA-256 of the canonical request. */
|
|
249
|
+
export async function requestDigest(request: Parameters<typeof canonicalRequest>[0]): Promise<string> {
|
|
250
|
+
return base64url(await sha256(canonicalRequest(request)));
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
/** The headers a proof signs from what the app set: every one but `UNSIGNED_HEADERS`, lowercased, in `Headers`' order. */
|
|
254
|
+
export function signedHeaders(headers: HeadersInit): [string, string][] {
|
|
255
|
+
return [...new Headers(headers)].filter(([name]) => !UNSIGNED_HEADERS.has(name));
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
/**
|
|
259
|
+
* A proof for one request, signed by `key`.
|
|
260
|
+
*
|
|
261
|
+
* - `token` adds `ath`, for a request made with a session; the exchange has none.
|
|
262
|
+
* - `nonce` is the gate's newest, from the last answer's `DPoP-Nonce`.
|
|
263
|
+
* - `content` adds `hdr` and `req`: the headers the app set, and the body's
|
|
264
|
+
* line (`bodyDigest`, a streamed SigV4 upload's declared digest, or
|
|
265
|
+
* `UNSIGNED_BODY`).
|
|
266
|
+
* Whatever it names is all coffre forwards.
|
|
267
|
+
*/
|
|
268
|
+
export async function createProof(
|
|
269
|
+
key: ProofKey,
|
|
270
|
+
request: {
|
|
271
|
+
method: string;
|
|
272
|
+
url: string | URL;
|
|
273
|
+
token?: string;
|
|
274
|
+
nonce?: string;
|
|
275
|
+
content?: { headers: HeadersInit; body: string };
|
|
276
|
+
/** For tests: the proof's time, in seconds, and its ID. */
|
|
277
|
+
iat?: number;
|
|
278
|
+
jti?: string;
|
|
279
|
+
},
|
|
280
|
+
): Promise<string> {
|
|
281
|
+
const header = { typ: 'dpop+jwt', alg: 'ES256', jwk: { kty: key.jwk.kty, crv: key.jwk.crv, x: key.jwk.x, y: key.jwk.y } };
|
|
282
|
+
const claims: ProofClaims = {
|
|
283
|
+
jti: request.jti ?? base64url(crypto.getRandomValues(new Uint8Array(16))),
|
|
284
|
+
htm: fetchMethod(request.method),
|
|
285
|
+
htu: canonicalHtu(request.url),
|
|
286
|
+
iat: request.iat ?? Math.floor(Date.now() / 1000),
|
|
287
|
+
};
|
|
288
|
+
if (request.token !== undefined) claims.ath = await tokenDigest(request.token);
|
|
289
|
+
if (request.nonce !== undefined) claims.nonce = request.nonce;
|
|
290
|
+
if (request.content !== undefined) {
|
|
291
|
+
const headers = signedHeaders(request.content.headers);
|
|
292
|
+
if (headers.length > MAX_SIGNED_HEADERS) throw new TypeError(`a proof signs at most ${MAX_SIGNED_HEADERS} headers: this request sets ${headers.length}`);
|
|
293
|
+
claims.hdr = headers.map(([name]) => name).join(' ');
|
|
294
|
+
claims.req = await requestDigest({ ...sentTarget(request.url), headers, body: request.content.body });
|
|
295
|
+
}
|
|
296
|
+
const input = `${base64url(ENCODER.encode(JSON.stringify(header)))}.${base64url(ENCODER.encode(JSON.stringify(claims)))}`;
|
|
297
|
+
// 86 characters of signature and its dot: a proof the verifier would refuse for its size is never made.
|
|
298
|
+
if (input.length + 87 > MAX_PROOF_LENGTH) throw new TypeError(`a proof is at most ${MAX_PROOF_LENGTH} characters: this request's URL or headers are too long to sign`);
|
|
299
|
+
const signature = await crypto.subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, key.privateKey, ENCODER.encode(input));
|
|
300
|
+
return `${input}.${base64url(new Uint8Array(signature))}`;
|
|
301
|
+
}
|
package/src/index.ts
CHANGED
|
@@ -212,7 +212,7 @@ export function createClient(options: ClientOptions) {
|
|
|
212
212
|
/**
|
|
213
213
|
* Protected, a person holds their role's protected column there
|
|
214
214
|
* (docs/design/roles.md); whoever manages the project's environments
|
|
215
|
-
* protects one, and only an Owner of the whole instance unprotects it.
|
|
215
|
+
* protects one, and only an Owner of its project, or of the whole instance, unprotects it.
|
|
216
216
|
*/
|
|
217
217
|
protect: (path: string, on = true) => call('PATCH /projects/:project/:environment', place(path), { protected: on }),
|
|
218
218
|
/** What deleting an archived environment would erase and revoke; changes nothing. */
|
|
@@ -318,6 +318,8 @@ export function createClient(options: ClientOptions) {
|
|
|
318
318
|
*/
|
|
319
319
|
handles: {
|
|
320
320
|
create: (input: RouteInput<'POST /handles'>) => call('POST /handles', {}, input),
|
|
321
|
+
/** Ends a handle of the caller's own, as `coffre run` does once its command ends. */
|
|
322
|
+
revoke: (id: string) => call('DELETE /handles/:id', { id }),
|
|
321
323
|
},
|
|
322
324
|
|
|
323
325
|
/** Trust bindings: which CI runs may sign in as a service, by their platform's ID token. */
|
package/src/routes.ts
CHANGED
|
@@ -42,8 +42,10 @@ export function getCalls({ places, secrets, members, services }: Subjects): GetC
|
|
|
42
42
|
'GET /members/:member/access': members.map((member) => ({ params: { member } })),
|
|
43
43
|
'GET /members/:member/tokens': services.map((member) => ({ params: { member } })),
|
|
44
44
|
'GET /members/:member/bindings': services.map((member) => ({ params: { member } })),
|
|
45
|
+
'GET /members/:member/bindings/:id/enrollments': services.map((member) => ({ params: { member, id: '00000000-0000-4000-8000-000000000000' } })),
|
|
45
46
|
'GET /workloads/lookup': [{ params: {}, input: { github: 'acme/api' } }],
|
|
46
47
|
'GET /workloads/repositories': [{ params: {} }],
|
|
48
|
+
'GET /freezes': [{ params: {} }],
|
|
47
49
|
'GET /roles': [{ params: {} }],
|
|
48
50
|
'GET /settings': [{ params: {} }],
|
|
49
51
|
'GET /sessions': [{ params: {} }],
|
|
@@ -102,10 +104,18 @@ const EVERY_ROUTE: { [K in RouteKey]: true } = {
|
|
|
102
104
|
'POST /members/:member/tokens': true,
|
|
103
105
|
'DELETE /members/:member/tokens/:id': true,
|
|
104
106
|
'POST /handles': true,
|
|
107
|
+
'DELETE /handles/:id': true,
|
|
105
108
|
'GET /members/:member/bindings': true,
|
|
106
109
|
'POST /members/:member/bindings': true,
|
|
107
110
|
'POST /members/:member/bindings/keys': true,
|
|
108
111
|
'DELETE /members/:member/bindings/:id': true,
|
|
112
|
+
'GET /members/:member/bindings/:id/enrollments': true,
|
|
113
|
+
'POST /members/:member/bindings/:id/enrollments': true,
|
|
114
|
+
'POST /members/:member/bindings/:id/enrollments/:enrollment/promote': true,
|
|
115
|
+
'POST /members/:member/tokens/:id/approve': true,
|
|
116
|
+
'GET /freezes': true,
|
|
117
|
+
'POST /freezes': true,
|
|
118
|
+
'DELETE /freezes/:target': true,
|
|
109
119
|
'GET /workloads/lookup': true,
|
|
110
120
|
'GET /workloads/repositories': true,
|
|
111
121
|
'GET /roles': true,
|
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Postgres from a workload, through coffre's tunnel (docs/design/workload-access.md,
|
|
3
|
+
* section 9.1): a stream node-postgres takes as its socket, carried over the
|
|
4
|
+
* tunnel's WebSocket and signed by the session. No listener, no password,
|
|
5
|
+
* and no database URL in the app: coffre logs in to the database.
|
|
6
|
+
*
|
|
7
|
+
* import pg from 'pg';
|
|
8
|
+
* import { connect } from '@coffre/client/workload/postgres';
|
|
9
|
+
*
|
|
10
|
+
* const pool = new pg.Pool({ stream: () => connect(coffre, 'db') });
|
|
11
|
+
*
|
|
12
|
+
* The WebSocket is the runtime's own (`globalThis.WebSocket`: Node 22 and
|
|
13
|
+
* later, Deno, Bun), which takes the upgrade's headers; on Node 20, pass the
|
|
14
|
+
* `ws` package's: `connect(coffre, 'db', { WebSocket })`.
|
|
15
|
+
*
|
|
16
|
+
* The bytes go by credit, as `coffre run`'s listener sends them
|
|
17
|
+
* (packages/cli/src/tunnels.ts): each side counts back what it took, in
|
|
18
|
+
* text messages, and sends at most a window the other has not counted, so a
|
|
19
|
+
* large result waits in coffre's Durable Object no more than a window. A
|
|
20
|
+
* coffre on Node says so with a byte before any count, and paces nothing.
|
|
21
|
+
*/
|
|
22
|
+
import { Buffer } from 'node:buffer';
|
|
23
|
+
import { Duplex } from 'node:stream';
|
|
24
|
+
|
|
25
|
+
import { upgradeHeaders, upgradeRefused, type Workload } from './workload.ts';
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* What the stream uses of a WebSocket: the WHATWG API's, which Node's,
|
|
29
|
+
* Deno's, Bun's and the `ws` package's all have; and `pause` and `resume`,
|
|
30
|
+
* which only the `ws` package's has, and which hold back a coffre that does
|
|
31
|
+
* not pace while the app reads nothing.
|
|
32
|
+
*/
|
|
33
|
+
export type TunnelSocket = {
|
|
34
|
+
binaryType: string;
|
|
35
|
+
readonly readyState: number;
|
|
36
|
+
readonly bufferedAmount: number;
|
|
37
|
+
send(data: Uint8Array | string): void;
|
|
38
|
+
close(): void;
|
|
39
|
+
addEventListener(type: 'open' | 'close' | 'error' | 'message', listener: (event: object) => void): void;
|
|
40
|
+
pause?(): void;
|
|
41
|
+
resume?(): void;
|
|
42
|
+
/** The `ws` package's: ends the connection at once, a paused one included, which reads no closing handshake. */
|
|
43
|
+
terminate?(): void;
|
|
44
|
+
};
|
|
45
|
+
|
|
46
|
+
/** A WebSocket class that takes the upgrade's headers, as all of those do. */
|
|
47
|
+
export type WebSocketClass = new (url: string, options: { headers: Record<string, string> }) => TunnelSocket;
|
|
48
|
+
|
|
49
|
+
const FLOW = 'coffre-tunnel-flow';
|
|
50
|
+
/** What either side may send that the other has not counted back. */
|
|
51
|
+
const WINDOW = 1024 * 1024;
|
|
52
|
+
/** How much the app takes before the stream counts it back: well under the window. */
|
|
53
|
+
const COUNT_EVERY = 128 * 1024;
|
|
54
|
+
/** How much the stream sends before it waits for the WebSocket to send it: a few COPY chunks. */
|
|
55
|
+
const HIGH_WATER = 1024 * 1024;
|
|
56
|
+
/** The most one message carries: a large query is sent in frames, each within the credit left. */
|
|
57
|
+
const FRAME = 64 * 1024;
|
|
58
|
+
/** How often an open connection says it is there, so that an idle one outlives Cloudflare's 100-second timeout. */
|
|
59
|
+
const KEEPALIVE_MS = 30_000;
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* A stream to the database behind the tunnel `name`, which node-postgres
|
|
63
|
+
* connects, writes and ends as it would a socket.
|
|
64
|
+
*/
|
|
65
|
+
export function connect(coffre: Workload, name: string, options: { WebSocket?: WebSocketClass } = {}): TunnelStream {
|
|
66
|
+
const WebSocketImpl = options.WebSocket ?? (globalThis as unknown as { WebSocket?: WebSocketClass }).WebSocket;
|
|
67
|
+
if (WebSocketImpl === undefined) throw new Error("this runtime has no WebSocket of its own (Node 20): connect(coffre, name, { WebSocket }) with the ws package's");
|
|
68
|
+
return new TunnelStream(coffre, tunnelUrl(coffre, name), WebSocketImpl);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* The WebSocket URL of the tunnel `name`: always under its environment,
|
|
73
|
+
* `/use/<project>/<env>/<name>`, which coffre's tunnel route requires,
|
|
74
|
+
* where `url(name)` shortens a single place's to `/use/<name>`.
|
|
75
|
+
*/
|
|
76
|
+
export function tunnelUrl(coffre: Workload, name: string): string {
|
|
77
|
+
const url = new URL(coffre.url(name));
|
|
78
|
+
if (coffre.places.length === 1) url.pathname = `/use/${[...coffre.places[0]!.split('/'), name].map(encodeURIComponent).join('/')}`;
|
|
79
|
+
return url.href.replace(/^http/, 'ws');
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
export class TunnelStream extends Duplex {
|
|
83
|
+
#ws: TunnelSocket | null = null;
|
|
84
|
+
/** Whether coffre paces: unknown until its first message says. */
|
|
85
|
+
#pacing: boolean | null = null;
|
|
86
|
+
/** Bytes sent that coffre has not counted; bytes the app took that this has not counted back; bytes coffre sent that it has not. */
|
|
87
|
+
#uncounted = 0;
|
|
88
|
+
#taken = 0;
|
|
89
|
+
#owed = 0;
|
|
90
|
+
/** Bytes pushed while the app was not reading: counted back once it reads, so coffre waits for it. */
|
|
91
|
+
#held = 0;
|
|
92
|
+
/** A write waiting for room: credit from coffre, or the WebSocket's own buffer to empty. */
|
|
93
|
+
#waiting: (() => void) | null = null;
|
|
94
|
+
#keepalive: ReturnType<typeof setInterval> | undefined;
|
|
95
|
+
/** Whether coffre took the upgrade. */
|
|
96
|
+
#opened = false;
|
|
97
|
+
|
|
98
|
+
constructor(coffre: Workload, url: string, WebSocketImpl: WebSocketClass) {
|
|
99
|
+
super();
|
|
100
|
+
void upgradeHeaders(coffre, url).then(
|
|
101
|
+
(headers) => {
|
|
102
|
+
// Ended or destroyed while it was signed: no connection is opened for it.
|
|
103
|
+
if (this.destroyed || this.writableEnded) return void (this.destroyed || this.destroy());
|
|
104
|
+
const ws = new WebSocketImpl(url, { headers: { ...headers, [FLOW]: 'credit' } });
|
|
105
|
+
ws.binaryType = 'arraybuffer';
|
|
106
|
+
this.#ws = ws;
|
|
107
|
+
ws.addEventListener('open', () => {
|
|
108
|
+
this.#opened = true;
|
|
109
|
+
this.emit('connect');
|
|
110
|
+
this.emit('ready');
|
|
111
|
+
this.#keepalive = setInterval(() => this.#count(), KEEPALIVE_MS);
|
|
112
|
+
(this.#keepalive as { unref?: () => void }).unref?.();
|
|
113
|
+
this.#release();
|
|
114
|
+
});
|
|
115
|
+
ws.addEventListener('message', (event) => this.#message((event as { data: ArrayBuffer | string }).data));
|
|
116
|
+
ws.addEventListener('close', () => {
|
|
117
|
+
clearInterval(this.#keepalive);
|
|
118
|
+
this.push(null);
|
|
119
|
+
this.destroy();
|
|
120
|
+
});
|
|
121
|
+
ws.addEventListener('error', () => {
|
|
122
|
+
// Refused before it opened, perhaps for its nonce, which this WebSocket does not show: the next one asks for the newest.
|
|
123
|
+
if (ws.readyState !== 1 && !this.#opened) upgradeRefused(coffre);
|
|
124
|
+
this.destroy(new Error(`the tunnel to ${url} was refused or cut`));
|
|
125
|
+
});
|
|
126
|
+
},
|
|
127
|
+
(error: unknown) => this.destroy(error as Error),
|
|
128
|
+
);
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/** node-postgres connects its stream itself; this one is connecting already, and says so with `connect`. */
|
|
132
|
+
connect(): this {
|
|
133
|
+
return this;
|
|
134
|
+
}
|
|
135
|
+
setNoDelay(): this {
|
|
136
|
+
return this;
|
|
137
|
+
}
|
|
138
|
+
setKeepAlive(): this {
|
|
139
|
+
return this;
|
|
140
|
+
}
|
|
141
|
+
ref(): this {
|
|
142
|
+
return this;
|
|
143
|
+
}
|
|
144
|
+
unref(): this {
|
|
145
|
+
return this;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
#open(): boolean {
|
|
149
|
+
return this.#ws !== null && this.#ws.readyState === 1;
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
#full(): boolean {
|
|
153
|
+
return !this.#open() || this.#ws!.bufferedAmount >= HIGH_WATER || (this.#pacing !== false && this.#uncounted >= WINDOW);
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/** Let a waiting write go, once there is room: the WebSocket's own buffer is polled, as it has no event for emptying. */
|
|
157
|
+
#release(): void {
|
|
158
|
+
if (this.#waiting === null) return;
|
|
159
|
+
if (!this.#full()) {
|
|
160
|
+
const go = this.#waiting;
|
|
161
|
+
this.#waiting = null;
|
|
162
|
+
go();
|
|
163
|
+
return;
|
|
164
|
+
}
|
|
165
|
+
if (this.#open() && this.#ws!.bufferedAmount >= HIGH_WATER) setTimeout(() => this.#release(), 10);
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
#count(): void {
|
|
169
|
+
if (!this.#open()) return;
|
|
170
|
+
this.#ws!.send(String(this.#taken));
|
|
171
|
+
this.#owed -= this.#taken;
|
|
172
|
+
this.#taken = 0;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
#message(data: ArrayBuffer | string): void {
|
|
176
|
+
if (typeof data === 'string') {
|
|
177
|
+
// coffre's count of what it took, the first saying that it paces: one that is no count of bytes it was sent ends the connection.
|
|
178
|
+
const counted = Number(data);
|
|
179
|
+
if (this.#pacing === false || !/^\d{1,10}$/.test(data) || counted > this.#uncounted) {
|
|
180
|
+
this.destroy(new Error('the tunnel broke its flow'));
|
|
181
|
+
return;
|
|
182
|
+
}
|
|
183
|
+
this.#pacing = true;
|
|
184
|
+
this.#uncounted -= counted;
|
|
185
|
+
this.#release();
|
|
186
|
+
return;
|
|
187
|
+
}
|
|
188
|
+
if (this.#pacing === null) {
|
|
189
|
+
// A byte first: coffre paces nothing, and the app is held to the window no longer.
|
|
190
|
+
this.#pacing = false;
|
|
191
|
+
this.#release();
|
|
192
|
+
}
|
|
193
|
+
this.#owed += data.byteLength;
|
|
194
|
+
if (this.#pacing === true && this.#owed > 2 * WINDOW) {
|
|
195
|
+
this.destroy(new Error('the tunnel sent past its window'));
|
|
196
|
+
return;
|
|
197
|
+
}
|
|
198
|
+
if (this.push(Buffer.from(data))) this.#took(data.byteLength);
|
|
199
|
+
else {
|
|
200
|
+
this.#held += data.byteLength;
|
|
201
|
+
// A coffre that paces waits for the count; one that does not is held back where the WebSocket can pause.
|
|
202
|
+
if (this.#pacing === false) this.#ws!.pause?.();
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
#took(bytes: number): void {
|
|
207
|
+
this.#taken += bytes;
|
|
208
|
+
if (this.#taken >= COUNT_EVERY) this.#count();
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
override _read(): void {
|
|
212
|
+
// The app reads again: what it was holding is taken now, and counted back.
|
|
213
|
+
const held = this.#held;
|
|
214
|
+
this.#held = 0;
|
|
215
|
+
if (held > 0) this.#took(held);
|
|
216
|
+
if (this.#pacing === false) this.#ws?.resume?.();
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
override _write(chunk: Buffer, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void {
|
|
220
|
+
// In frames, each sent within the window coffre has left: a query larger than the window waits for its counts between them.
|
|
221
|
+
let offset = 0;
|
|
222
|
+
const next = () => {
|
|
223
|
+
while (offset < chunk.length) {
|
|
224
|
+
if (this.#full()) {
|
|
225
|
+
if (this.#ws !== null && this.#ws.readyState > 1) return callback(new Error('the tunnel is closed'));
|
|
226
|
+
this.#waiting = next;
|
|
227
|
+
return this.#release();
|
|
228
|
+
}
|
|
229
|
+
const frame = chunk.subarray(offset, offset + FRAME);
|
|
230
|
+
offset += frame.length;
|
|
231
|
+
this.#uncounted += frame.length;
|
|
232
|
+
this.#ws!.send(frame);
|
|
233
|
+
}
|
|
234
|
+
callback();
|
|
235
|
+
};
|
|
236
|
+
next();
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
override _final(callback: (error?: Error | null) => void): void {
|
|
240
|
+
this.#ws?.close();
|
|
241
|
+
callback();
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
override _destroy(error: Error | null, callback: (error?: Error | null) => void): void {
|
|
245
|
+
clearInterval(this.#keepalive);
|
|
246
|
+
if (this.#ws !== null && this.#ws.readyState <= 1) {
|
|
247
|
+
if (this.#ws.terminate !== undefined) this.#ws.terminate();
|
|
248
|
+
else this.#ws.close();
|
|
249
|
+
}
|
|
250
|
+
// Writes that waited for room end with the stream.
|
|
251
|
+
this.#waiting = null;
|
|
252
|
+
callback(error);
|
|
253
|
+
}
|
|
254
|
+
}
|