@c9up/archive 0.1.3

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.
Files changed (63) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +35 -0
  3. package/dist/ArchiveProvider.d.ts +32 -0
  4. package/dist/ArchiveProvider.d.ts.map +1 -0
  5. package/dist/ArchiveProvider.js +91 -0
  6. package/dist/ArchiveProvider.js.map +1 -0
  7. package/dist/GcsDriver.d.ts +41 -0
  8. package/dist/GcsDriver.d.ts.map +1 -0
  9. package/dist/GcsDriver.js +387 -0
  10. package/dist/GcsDriver.js.map +1 -0
  11. package/dist/S3Driver.d.ts +50 -0
  12. package/dist/S3Driver.d.ts.map +1 -0
  13. package/dist/S3Driver.js +642 -0
  14. package/dist/S3Driver.js.map +1 -0
  15. package/dist/StaticMiddleware.d.ts +46 -0
  16. package/dist/StaticMiddleware.d.ts.map +1 -0
  17. package/dist/StaticMiddleware.js +121 -0
  18. package/dist/StaticMiddleware.js.map +1 -0
  19. package/dist/StorageManager.d.ts +178 -0
  20. package/dist/StorageManager.d.ts.map +1 -0
  21. package/dist/StorageManager.js +405 -0
  22. package/dist/StorageManager.js.map +1 -0
  23. package/dist/errors.d.ts +11 -0
  24. package/dist/errors.d.ts.map +1 -0
  25. package/dist/errors.js +14 -0
  26. package/dist/errors.js.map +1 -0
  27. package/dist/expiry.d.ts +15 -0
  28. package/dist/expiry.d.ts.map +1 -0
  29. package/dist/expiry.js +26 -0
  30. package/dist/expiry.js.map +1 -0
  31. package/dist/index.d.ts +17 -0
  32. package/dist/index.d.ts.map +1 -0
  33. package/dist/index.js +17 -0
  34. package/dist/index.js.map +1 -0
  35. package/dist/mime-types.d.ts +17 -0
  36. package/dist/mime-types.d.ts.map +1 -0
  37. package/dist/mime-types.js +47 -0
  38. package/dist/mime-types.js.map +1 -0
  39. package/dist/services/main.d.ts +19 -0
  40. package/dist/services/main.d.ts.map +1 -0
  41. package/dist/services/main.js +33 -0
  42. package/dist/services/main.js.map +1 -0
  43. package/dist/signed-route.d.ts +61 -0
  44. package/dist/signed-route.d.ts.map +1 -0
  45. package/dist/signed-route.js +155 -0
  46. package/dist/signed-route.js.map +1 -0
  47. package/dist/testing/FakeStorage.d.ts +72 -0
  48. package/dist/testing/FakeStorage.d.ts.map +1 -0
  49. package/dist/testing/FakeStorage.js +266 -0
  50. package/dist/testing/FakeStorage.js.map +1 -0
  51. package/package.json +67 -0
  52. package/src/ArchiveProvider.ts +134 -0
  53. package/src/GcsDriver.ts +490 -0
  54. package/src/S3Driver.ts +791 -0
  55. package/src/StaticMiddleware.ts +175 -0
  56. package/src/StorageManager.ts +627 -0
  57. package/src/errors.ts +14 -0
  58. package/src/expiry.ts +41 -0
  59. package/src/index.ts +41 -0
  60. package/src/mime-types.ts +51 -0
  61. package/src/services/main.ts +41 -0
  62. package/src/signed-route.ts +223 -0
  63. package/src/testing/FakeStorage.ts +372 -0
@@ -0,0 +1,642 @@
1
+ /**
2
+ * S3Driver — S3-compatible cloud storage (AWS S3, Cloudflare R2, MinIO).
3
+ *
4
+ * Uses fetch API — no external SDK dependency.
5
+ * Implements the StorageDriver interface.
6
+ *
7
+ * @implements MISS-24
8
+ */
9
+ import { createHash, createHmac } from "node:crypto";
10
+ import { Readable } from "node:stream";
11
+ import { ArchiveError } from "./errors.js";
12
+ import { assertValidExpiry, DEFAULT_EXPIRES_IN } from "./expiry.js";
13
+ /** AWS minimum for a non-final multipart part. */
14
+ const S3_MULTIPART_PART_SIZE = 5 * 1024 * 1024;
15
+ /**
16
+ * AWS SigV4 strict URI encoding: RFC3986 unreserved set only
17
+ * (`A-Z a-z 0-9 - . _ ~`). `encodeURIComponent` leaves `! * ' ( )`
18
+ * unencoded, but AWS canonicalisation requires them encoded — a
19
+ * signature derived with `encodeURIComponent` alone will silently
20
+ * mismatch for keys containing those characters.
21
+ */
22
+ function s3StrictEncode(str) {
23
+ return encodeURIComponent(str).replace(/[!*'()]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
24
+ }
25
+ /**
26
+ * URI-encode an S3 object key per AWS SigV4 rules: encode each path segment
27
+ * individually but preserve `/` separators. Handles spaces, unicode, `#`, `?`, `%`
28
+ * as well as the strict AWS set (`! * ' ( )`).
29
+ */
30
+ function s3EncodeKey(key) {
31
+ return key.split("/").map(s3StrictEncode).join("/");
32
+ }
33
+ export class S3Driver {
34
+ #config;
35
+ #endpoint;
36
+ constructor(config) {
37
+ // Require at least one of `region` or `endpoint`. Defaulting to
38
+ // `us-east-1` silently would mis-sign requests against a
39
+ // non-AWS-default region (e.g. eu-west-3) and produce signature
40
+ // errors only at runtime — much better to fail fast here.
41
+ if (!config.endpoint && !config.region) {
42
+ throw new Error("S3Driver: either `region` or `endpoint` is required. Pass `region` for AWS S3, or `endpoint` for S3-compatible services (MinIO, R2, etc.).");
43
+ }
44
+ this.#config = config;
45
+ const rawEndpoint = config.endpoint ?? `https://s3.${config.region}.amazonaws.com`;
46
+ // Strip any trailing slash: a user-configured endpoint like
47
+ // `https://minio.local/` would otherwise produce `//bucket/key`
48
+ // URLs that real S3/MinIO reject AND whose canonical URI used
49
+ // for signing would no longer match the request URL.
50
+ this.#endpoint = rawEndpoint.replace(/\/+$/, "");
51
+ }
52
+ async put(filePath, content) {
53
+ const body = typeof content === "string" ? Buffer.from(content) : content;
54
+ const url = `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}`;
55
+ const headers = this.#signRequest({ method: "PUT", key: filePath, body });
56
+ const res = await fetch(url, {
57
+ method: "PUT",
58
+ headers,
59
+ body: body,
60
+ });
61
+ if (!res.ok) {
62
+ throw new Error(`S3 PUT failed (${res.status}): ${await res.text()}`);
63
+ }
64
+ }
65
+ async putStream(filePath, readable, options) {
66
+ const { contentType, contentLength } = options ?? {};
67
+ // Small-file fast path: known length ≤ 5 MiB → buffer & single PUT.
68
+ if (contentLength !== undefined &&
69
+ contentLength <= S3_MULTIPART_PART_SIZE) {
70
+ const body = await collectToBuffer(readable, contentLength);
71
+ const url = `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}`;
72
+ const signed = this.#signRequest({ method: "PUT", key: filePath, body });
73
+ // content-type kept UNSIGNED — undici may rewrite it for
74
+ // non-Buffer bodies, which would invalidate a signed value.
75
+ const headers = contentType
76
+ ? { ...signed, "content-type": contentType }
77
+ : signed;
78
+ const res = await fetch(url, {
79
+ method: "PUT",
80
+ headers,
81
+ body: body,
82
+ });
83
+ if (!res.ok) {
84
+ throw new Error(`S3 PUT failed (${res.status}): ${await res.text()}`);
85
+ }
86
+ return;
87
+ }
88
+ // Multipart path: unknown length OR > 5 MiB.
89
+ //
90
+ // Peek the first chunk before initiating: strict S3-compatible
91
+ // servers reject multipart uploads whose (only) part is empty,
92
+ // and spinning up the 3-step dance for a 0-byte object is waste
93
+ // anyway. Fall through to a direct single-PUT in that case.
94
+ const chunks = chunkStream(readable, S3_MULTIPART_PART_SIZE);
95
+ const iterator = chunks[Symbol.asyncIterator]();
96
+ const firstChunk = await iterator.next();
97
+ if (firstChunk.done) {
98
+ await this.put(filePath, Buffer.alloc(0));
99
+ return;
100
+ }
101
+ const uploadId = await this.#initiateMultipartUpload(filePath, contentType);
102
+ const parts = [];
103
+ try {
104
+ let partNumber = 1;
105
+ let chunk = firstChunk.value;
106
+ while (chunk !== undefined) {
107
+ const etag = await this.#uploadPart(filePath, uploadId, partNumber, chunk, contentType);
108
+ parts.push({ partNumber, etag });
109
+ partNumber++;
110
+ const next = await iterator.next();
111
+ chunk = next.done ? undefined : next.value;
112
+ }
113
+ await this.#completeMultipartUpload(filePath, uploadId, parts);
114
+ }
115
+ catch (err) {
116
+ // Best-effort abort so we don't leak staged parts. The
117
+ // original error is what bubbles up.
118
+ await this.#abortMultipartUpload(filePath, uploadId).catch(() => { });
119
+ throw err;
120
+ }
121
+ }
122
+ async getStream(filePath) {
123
+ const url = `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}`;
124
+ const headers = this.#signRequest({ method: "GET", key: filePath });
125
+ const res = await fetch(url, { method: "GET", headers });
126
+ if (res.status === 404) {
127
+ throw new ArchiveError("ARCHIVE_NOT_FOUND", `S3 object does not exist at path '${filePath}'`, {
128
+ hint: "Confirm the bucket + key and that the object was put() first.",
129
+ });
130
+ }
131
+ if (!res.ok)
132
+ throw new Error(`S3 GET failed (${res.status})`);
133
+ if (res.body === null) {
134
+ // Edge case: 200 with no body. Return an empty readable.
135
+ return Readable.from(Buffer.alloc(0));
136
+ }
137
+ // Node's `Readable.fromWeb` expects the `node:stream/web` variant,
138
+ // while `fetch().body` gives the lib.dom variant. Runtime shape is
139
+ // identical — the difference is only in TS lib typings. A single
140
+ // cast to the node-side type is enough (no `unknown` pivot).
141
+ return Readable.fromWeb(res.body);
142
+ }
143
+ async get(filePath) {
144
+ const url = `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}`;
145
+ const headers = this.#signRequest({ method: "GET", key: filePath });
146
+ const res = await fetch(url, { method: "GET", headers });
147
+ if (res.status === 404)
148
+ return null;
149
+ if (!res.ok)
150
+ throw new Error(`S3 GET failed (${res.status})`);
151
+ const arrayBuffer = await res.arrayBuffer();
152
+ return Buffer.from(arrayBuffer);
153
+ }
154
+ async delete(filePath) {
155
+ const url = `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}`;
156
+ const headers = this.#signRequest({ method: "DELETE", key: filePath });
157
+ const res = await fetch(url, { method: "DELETE", headers });
158
+ return res.ok || res.status === 204;
159
+ }
160
+ async exists(filePath) {
161
+ const url = `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}`;
162
+ const headers = this.#signRequest({ method: "HEAD", key: filePath });
163
+ const res = await fetch(url, { method: "HEAD", headers });
164
+ return res.ok;
165
+ }
166
+ publicUrl(filePath) {
167
+ if (this.#config.publicUrl) {
168
+ // Strip trailing slash to avoid `cdn.example.com//key` artifacts.
169
+ const publicRoot = this.#config.publicUrl.replace(/\/+$/, "");
170
+ return `${publicRoot}/${s3EncodeKey(filePath)}`;
171
+ }
172
+ return `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}`;
173
+ }
174
+ async url(filePath) {
175
+ const meta = await this.getMetadata(filePath);
176
+ if (meta.visibility === "public")
177
+ return this.publicUrl(filePath);
178
+ return this.getSignedUrl(filePath);
179
+ }
180
+ async getMetadata(filePath) {
181
+ // HEAD for size / mime / lastModified / etag.
182
+ const headUrl = `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}`;
183
+ const headHeaders = this.#signRequest({ method: "HEAD", key: filePath });
184
+ const headRes = await fetch(headUrl, {
185
+ method: "HEAD",
186
+ headers: headHeaders,
187
+ });
188
+ if (headRes.status === 404) {
189
+ throw new ArchiveError("ARCHIVE_NOT_FOUND", `S3 object does not exist at path '${filePath}'`, {
190
+ hint: "Confirm the bucket + key and that the object was put() first.",
191
+ });
192
+ }
193
+ if (!headRes.ok) {
194
+ throw new Error(`S3 HEAD failed (${headRes.status})`);
195
+ }
196
+ const size = Number.parseInt(headRes.headers.get("content-length") ?? "0", 10);
197
+ const mimeType = headRes.headers.get("content-type") ?? "application/octet-stream";
198
+ const lastModifiedHeader = headRes.headers.get("last-modified");
199
+ const lastModified = lastModifiedHeader
200
+ ? new Date(lastModifiedHeader)
201
+ : new Date(0);
202
+ const rawEtag = headRes.headers.get("etag") ?? "";
203
+ // Strip surrounding quotes, preserving any `W/` weak prefix.
204
+ // The naive `/^"|"$/g` would only strip the trailing `"` from
205
+ // `W/"abc"`, leaving `W/"abc` — a malformed etag.
206
+ const etag = rawEtag.replace(/^(W\/)?"(.*)"$/, "$1$2");
207
+ // GET ?acl to determine visibility. AllUsers READ grant → public.
208
+ const aclUrl = `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}?acl`;
209
+ const aclHeaders = this.#signRequest({
210
+ method: "GET",
211
+ key: filePath,
212
+ queryParams: [["acl", ""]],
213
+ });
214
+ const aclRes = await fetch(aclUrl, { method: "GET", headers: aclHeaders });
215
+ let visibility = "private";
216
+ if (aclRes.ok) {
217
+ const xml = await aclRes.text();
218
+ if (isPublicAcl(xml))
219
+ visibility = "public";
220
+ }
221
+ // Non-2xx on ACL (e.g. 403 on a bucket without permission) falls
222
+ // through to `private` — the safer default.
223
+ return { size, mimeType, lastModified, etag, visibility };
224
+ }
225
+ async setVisibility(filePath, visibility) {
226
+ const cannedAcl = visibility === "public" ? "public-read" : "private";
227
+ const url = `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}?acl`;
228
+ const headers = this.#signRequest({
229
+ method: "PUT",
230
+ key: filePath,
231
+ queryParams: [["acl", ""]],
232
+ extraHeaders: { "x-amz-acl": cannedAcl },
233
+ });
234
+ const res = await fetch(url, { method: "PUT", headers });
235
+ if (!res.ok) {
236
+ throw new Error(`S3 PUT failed (${res.status}): ${await res.text()}`);
237
+ }
238
+ }
239
+ /**
240
+ * Generate a presigned GET URL per AWS SigV4 query-parameter spec.
241
+ *
242
+ * The returned URL always targets the **signing endpoint**
243
+ * (`config.endpoint` or the derived AWS endpoint), *not*
244
+ * `config.publicUrl` — presigned URLs only validate against the
245
+ * host that signed them. For a CDN-fronted bucket, serve unsigned
246
+ * reads via {@link url} instead of presigning.
247
+ *
248
+ * Canonical differences from header-signed requests:
249
+ * - SignedHeaders is `host` only (no `x-amz-date`/content-hash).
250
+ * - Payload hash is the literal `UNSIGNED-PAYLOAD`.
251
+ * - Credentials and expiry live in query params, not headers.
252
+ */
253
+ getSignedUrl(filePath, options) {
254
+ const expiresIn = options?.expiresIn ?? DEFAULT_EXPIRES_IN;
255
+ assertValidExpiry(expiresIn);
256
+ const dateStamp = amzDateNow();
257
+ const shortDate = dateStamp.slice(0, 8);
258
+ const region = this.#config.region ?? "us-east-1";
259
+ const service = "s3";
260
+ const scope = `${shortDate}/${region}/${service}/aws4_request`;
261
+ const credential = `${this.#config.accessKeyId}/${scope}`;
262
+ // Canonical query params — names MUST be URI-encoded and the
263
+ // whole string sorted by key before signing. Every `X-Amz-*`
264
+ // key is already safe, so we only URI-encode values.
265
+ const queryParams = [
266
+ ["X-Amz-Algorithm", "AWS4-HMAC-SHA256"],
267
+ ["X-Amz-Credential", credential],
268
+ ["X-Amz-Date", dateStamp],
269
+ ["X-Amz-Expires", String(expiresIn)],
270
+ ["X-Amz-SignedHeaders", "host"],
271
+ ];
272
+ const canonicalQs = queryParams
273
+ .slice()
274
+ .sort((a, b) => (a[0] < b[0] ? -1 : 1))
275
+ .map(([k, v]) => `${k}=${s3StrictEncode(v)}`)
276
+ .join("&");
277
+ const host = new URL(this.#endpoint).host;
278
+ const canonicalRequest = [
279
+ "GET",
280
+ `/${this.#config.bucket}/${s3EncodeKey(filePath)}`,
281
+ canonicalQs,
282
+ `host:${host}\n`,
283
+ "host",
284
+ "UNSIGNED-PAYLOAD",
285
+ ].join("\n");
286
+ const stringToSign = [
287
+ "AWS4-HMAC-SHA256",
288
+ dateStamp,
289
+ scope,
290
+ createHash("sha256").update(canonicalRequest).digest("hex"),
291
+ ].join("\n");
292
+ const signingKey = this.#derivingKey(shortDate, region, service);
293
+ const signature = createHmac("sha256", signingKey)
294
+ .update(stringToSign)
295
+ .digest("hex");
296
+ return `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}?${canonicalQs}&X-Amz-Signature=${signature}`;
297
+ }
298
+ async copy(from, to) {
299
+ const url = `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(to)}`;
300
+ const copySource = `/${this.#config.bucket}/${s3EncodeKey(from)}`;
301
+ const headers = this.#signRequest({
302
+ method: "PUT",
303
+ key: to,
304
+ extraHeaders: { "x-amz-copy-source": copySource },
305
+ });
306
+ const res = await fetch(url, { method: "PUT", headers });
307
+ if (!res.ok) {
308
+ const body = await res.text();
309
+ if (/\bNoSuchKey\b/.test(body) || res.status === 404) {
310
+ throw new ArchiveError("ARCHIVE_NOT_FOUND", `S3 copy source does not exist at path '${from}'`, { hint: "Confirm the source object was put() first." });
311
+ }
312
+ throw new Error(`S3 COPY failed (${res.status}): ${body}`);
313
+ }
314
+ // S3 CopyObject can return 200 + an XML <Error> body (streaming
315
+ // copies that fail mid-flight). Matches the same pattern handled
316
+ // in #completeMultipartUpload — don't silently succeed.
317
+ const body = await res.text();
318
+ if (/<Error>/i.test(body)) {
319
+ throw new Error(`S3 COPY returned error body: ${body}`);
320
+ }
321
+ }
322
+ async move(from, to) {
323
+ // Non-atomic: copy then delete. An observer between the two
324
+ // steps sees both objects — documented in the interface JSDoc.
325
+ await this.copy(from, to);
326
+ await this.delete(from);
327
+ }
328
+ async *list(prefix) {
329
+ let continuationToken;
330
+ do {
331
+ const qp = [
332
+ ["list-type", "2"],
333
+ ["prefix", prefix],
334
+ ];
335
+ if (continuationToken)
336
+ qp.push(["continuation-token", continuationToken]);
337
+ const canonicalQs = qp
338
+ .slice()
339
+ .sort((a, b) => (a[0] < b[0] ? -1 : 1))
340
+ .map(([k, v]) => `${k}=${s3StrictEncode(v)}`)
341
+ .join("&");
342
+ const url = `${this.#endpoint}/${this.#config.bucket}?${canonicalQs}`;
343
+ const headers = this.#signRequest({
344
+ method: "GET",
345
+ key: "",
346
+ queryParams: qp,
347
+ });
348
+ const res = await fetch(url, { method: "GET", headers });
349
+ if (!res.ok) {
350
+ throw new Error(`S3 LIST failed (${res.status}): ${await res.text()}`);
351
+ }
352
+ const xml = await res.text();
353
+ // Parse each <Contents> block independently, then extract
354
+ // each field by its own regex. Some S3-compatible servers
355
+ // (R2, MinIO variants) emit fields in different orders than
356
+ // AWS — an ordered regex would yield corrupt values silently.
357
+ const blockRe = /<Contents>([\s\S]*?)<\/Contents>/g;
358
+ let blockMatch = blockRe.exec(xml);
359
+ while (blockMatch !== null) {
360
+ const block = blockMatch[1] ?? "";
361
+ const key = block.match(/<Key>([^<]+)<\/Key>/)?.[1] ?? "";
362
+ const sizeRaw = block.match(/<Size>([^<]+)<\/Size>/)?.[1] ?? "0";
363
+ const lm = block.match(/<LastModified>([^<]+)<\/LastModified>/)?.[1];
364
+ yield {
365
+ path: key,
366
+ size: Number.parseInt(sizeRaw, 10),
367
+ lastModified: lm ? new Date(lm) : new Date(0),
368
+ };
369
+ blockMatch = blockRe.exec(xml);
370
+ }
371
+ const truncated = /<IsTruncated>true<\/IsTruncated>/i.test(xml);
372
+ const tokenMatch = xml.match(/<NextContinuationToken>([^<]+)<\/NextContinuationToken>/);
373
+ continuationToken = truncated && tokenMatch ? tokenMatch[1] : undefined;
374
+ } while (continuationToken);
375
+ }
376
+ /**
377
+ * Sign a request with AWS Signature V4 (header-signed flow).
378
+ *
379
+ * `queryParams` appear both in the canonical query string (sorted,
380
+ * strict-encoded, empty values kept as `k=`) and on the actual
381
+ * request URL. Use for subresources (`acl`, `uploads`) and for
382
+ * multi-value queries (`partNumber=N&uploadId=X`). `extraHeaders`
383
+ * are merged into the signed-headers set — use for `x-amz-acl` and
384
+ * friends so the server verifies them against the signature.
385
+ *
386
+ * For production, consider using @aws-sdk/signature-v4 for full compliance.
387
+ */
388
+ #signRequest(opts) {
389
+ const { method, key, body, queryParams, extraHeaders } = opts;
390
+ const dateStamp = amzDateNow();
391
+ const shortDate = dateStamp.slice(0, 8);
392
+ const region = this.#config.region ?? "us-east-1";
393
+ const service = "s3";
394
+ const payloadHash = createHash("sha256")
395
+ .update(body ?? "")
396
+ .digest("hex");
397
+ // `content-length` is intentionally NOT signed. undici (Node's
398
+ // fetch implementation) sets / overrides the Content-Length
399
+ // header itself when the body is a Buffer, which would cause a
400
+ // signature mismatch if we included it in SignedHeaders. S3
401
+ // accepts unsigned Content-Length — SigV4 only requires `host`,
402
+ // `x-amz-date`, and `x-amz-content-sha256` to be signed.
403
+ const headers = {
404
+ host: new URL(this.#endpoint).host,
405
+ "x-amz-date": dateStamp,
406
+ "x-amz-content-sha256": payloadHash,
407
+ ...(extraHeaders ?? {}),
408
+ };
409
+ // Canonical request — header names are lowercased for signing
410
+ // (AWS requirement); the actual wire values stay as-provided.
411
+ const sortedHeaderKeys = Object.keys(headers).sort();
412
+ const signedHeaders = sortedHeaderKeys.join(";");
413
+ const canonicalHeaders = sortedHeaderKeys
414
+ .map((k) => `${k}:${headers[k]}\n`)
415
+ .join("");
416
+ // Canonical query string: sorted by key, strict-encoded values,
417
+ // empty values kept as `k=` (AWS canonical form for bare
418
+ // subresources like `?acl` and `?uploads`).
419
+ const canonicalQuery = (queryParams ?? [])
420
+ .slice()
421
+ .sort((a, b) => (a[0] < b[0] ? -1 : 1))
422
+ .map(([k, v]) => `${k}=${s3StrictEncode(v)}`)
423
+ .join("&");
424
+ const canonicalRequest = [
425
+ method,
426
+ `/${this.#config.bucket}/${s3EncodeKey(key)}`,
427
+ canonicalQuery,
428
+ canonicalHeaders,
429
+ signedHeaders,
430
+ payloadHash,
431
+ ].join("\n");
432
+ // String to sign
433
+ const scope = `${shortDate}/${region}/${service}/aws4_request`;
434
+ const stringToSign = [
435
+ "AWS4-HMAC-SHA256",
436
+ dateStamp,
437
+ scope,
438
+ createHash("sha256").update(canonicalRequest).digest("hex"),
439
+ ].join("\n");
440
+ const signingKey = this.#derivingKey(shortDate, region, service);
441
+ const signature = createHmac("sha256", signingKey)
442
+ .update(stringToSign)
443
+ .digest("hex");
444
+ headers.authorization = `AWS4-HMAC-SHA256 Credential=${this.#config.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
445
+ return headers;
446
+ }
447
+ /** Initiate a multipart upload. Returns the server-assigned UploadId. */
448
+ async #initiateMultipartUpload(filePath, contentType) {
449
+ const url = `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}?uploads`;
450
+ const signed = this.#signRequest({
451
+ method: "POST",
452
+ key: filePath,
453
+ queryParams: [["uploads", ""]],
454
+ });
455
+ const headers = contentType
456
+ ? { ...signed, "content-type": contentType }
457
+ : signed;
458
+ const res = await fetch(url, { method: "POST", headers });
459
+ if (!res.ok) {
460
+ throw new Error(`S3 multipart initiate failed (${res.status}): ${await res.text()}`);
461
+ }
462
+ const xml = await res.text();
463
+ const match = xml.match(/<UploadId>([^<]+)<\/UploadId>/);
464
+ // Capture group 1 must be defined because the regex includes it
465
+ // and `match` returned non-null. If the regex ever changes to
466
+ // something with optional groups, the `match[1] === undefined`
467
+ // path must be handled explicitly — not silently defaulted.
468
+ if (!match || match[1] === undefined) {
469
+ throw new Error(`S3 multipart initiate: UploadId missing from response: ${xml}`);
470
+ }
471
+ return match[1];
472
+ }
473
+ /** Upload a single part. Returns the server-reported ETag (quotes kept). */
474
+ async #uploadPart(filePath, uploadId, partNumber, body, contentType) {
475
+ const queryParams = [
476
+ ["partNumber", String(partNumber)],
477
+ ["uploadId", uploadId],
478
+ ];
479
+ const qs = `partNumber=${partNumber}&uploadId=${s3StrictEncode(uploadId)}`;
480
+ const url = `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}?${qs}`;
481
+ const signed = this.#signRequest({
482
+ method: "PUT",
483
+ key: filePath,
484
+ body,
485
+ queryParams,
486
+ });
487
+ const headers = contentType
488
+ ? { ...signed, "content-type": contentType }
489
+ : signed;
490
+ const res = await fetch(url, {
491
+ method: "PUT",
492
+ headers,
493
+ body: body,
494
+ });
495
+ if (!res.ok) {
496
+ throw new Error(`S3 UploadPart failed part=${partNumber} (${res.status}): ${await res.text()}`);
497
+ }
498
+ const etag = res.headers.get("etag");
499
+ if (!etag) {
500
+ throw new Error(`S3 UploadPart part=${partNumber}: ETag missing from response`);
501
+ }
502
+ // Keep the quotes — CompleteMultipartUpload XML requires the
503
+ // ETag value exactly as S3 returned it.
504
+ return etag;
505
+ }
506
+ /** Finalise a multipart upload with the collected part ETags. */
507
+ async #completeMultipartUpload(filePath, uploadId, parts) {
508
+ const xmlBody = Buffer.from(`<CompleteMultipartUpload>${parts
509
+ .map((p) => `<Part><PartNumber>${p.partNumber}</PartNumber><ETag>${p.etag}</ETag></Part>`)
510
+ .join("")}</CompleteMultipartUpload>`);
511
+ const url = `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}?uploadId=${s3StrictEncode(uploadId)}`;
512
+ const signed = this.#signRequest({
513
+ method: "POST",
514
+ key: filePath,
515
+ body: xmlBody,
516
+ queryParams: [["uploadId", uploadId]],
517
+ });
518
+ const res = await fetch(url, {
519
+ method: "POST",
520
+ headers: signed,
521
+ body: xmlBody,
522
+ });
523
+ if (!res.ok) {
524
+ throw new Error(`S3 CompleteMultipartUpload failed (${res.status}): ${await res.text()}`);
525
+ }
526
+ // S3 can return 200 + an XML error body (!) — detect via
527
+ // <Error> root element and throw.
528
+ const text = await res.text();
529
+ if (/^\s*<\?xml[^?]*\?>\s*<Error>/i.test(text) ||
530
+ /^\s*<Error>/.test(text)) {
531
+ throw new Error(`S3 CompleteMultipartUpload returned Error body: ${text}`);
532
+ }
533
+ }
534
+ /** Release a multipart upload's staged parts. Best-effort. */
535
+ async #abortMultipartUpload(filePath, uploadId) {
536
+ const url = `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}?uploadId=${s3StrictEncode(uploadId)}`;
537
+ const headers = this.#signRequest({
538
+ method: "DELETE",
539
+ key: filePath,
540
+ queryParams: [["uploadId", uploadId]],
541
+ });
542
+ await fetch(url, { method: "DELETE", headers });
543
+ }
544
+ /**
545
+ * Derive the SigV4 signing key (k_date → k_region → k_service →
546
+ * k_signing). Extracted so `#signRequest` and `getSignedUrl` share
547
+ * the same chain without copy-paste drift.
548
+ */
549
+ #derivingKey(shortDate, region, service) {
550
+ const kDate = createHmac("sha256", `AWS4${this.#config.secretAccessKey}`)
551
+ .update(shortDate)
552
+ .digest();
553
+ const kRegion = createHmac("sha256", kDate).update(region).digest();
554
+ const kService = createHmac("sha256", kRegion).update(service).digest();
555
+ return createHmac("sha256", kService).update("aws4_request").digest();
556
+ }
557
+ }
558
+ /** Returns the current instant in AWS basic-ISO8601 form: `YYYYMMDDTHHMMSSZ`. */
559
+ function amzDateNow() {
560
+ return `${new Date().toISOString().replace(/[-:]/g, "").split(".")[0]}Z`;
561
+ }
562
+ /**
563
+ * Drain a readable into a single Buffer, capped at `maxBytes`. Throws
564
+ * if the stream yields more than that — caller declared a contentLength
565
+ * and we refuse to silently over-buffer.
566
+ */
567
+ /**
568
+ * Type guard for any readable that exposes `destroy()` (Node streams
569
+ * do; a generic `ReadableStream` iterable doesn't). Lets us release
570
+ * file descriptors / sockets without an `as unknown as T` cast.
571
+ */
572
+ function hasDestroy(x) {
573
+ return (typeof x === "object" &&
574
+ x !== null &&
575
+ typeof x.destroy === "function");
576
+ }
577
+ async function collectToBuffer(readable, maxBytes) {
578
+ const chunks = [];
579
+ let total = 0;
580
+ for await (const chunk of readable) {
581
+ const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
582
+ total += buf.length;
583
+ if (total > maxBytes) {
584
+ // Destroy the upstream so FDs / sockets don't leak. Without
585
+ // this, an `fs.createReadStream` or `IncomingMessage` would
586
+ // stay open for the lifetime of the process.
587
+ if (hasDestroy(readable))
588
+ readable.destroy();
589
+ throw new Error(`putStream: readable exceeded declared contentLength (${total} > ${maxBytes})`);
590
+ }
591
+ chunks.push(buf);
592
+ }
593
+ return Buffer.concat(chunks, total);
594
+ }
595
+ /**
596
+ * Async-iterable that yields Buffers of exactly `partSize` bytes (last
597
+ * one may be smaller). Used to slice a stream into S3 multipart parts.
598
+ *
599
+ * **Backpressure.** Memory usage is bounded by `partSize + readable`'s
600
+ * own `highWaterMark`. The `for await` loop pulls from `readable` only
601
+ * when the consumer has finished awaiting the previous yield, so a slow
602
+ * consumer naturally throttles a fast producer through Node's stream
603
+ * pause/resume protocol — `pending` is drained to a single yield before
604
+ * the loop pulls the next chunk. Pass a `Readable` with a tighter
605
+ * `highWaterMark` to lower the peak. Pre-buffered streams (e.g.
606
+ * `Readable.from(buffer)`) bypass this and surface their entire payload
607
+ * in one tick; for those, expect peak ≈ `payload + partSize`.
608
+ */
609
+ async function* chunkStream(readable, partSize) {
610
+ let pending = [];
611
+ let pendingSize = 0;
612
+ for await (const chunk of readable) {
613
+ const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
614
+ pending.push(buf);
615
+ pendingSize += buf.length;
616
+ while (pendingSize >= partSize) {
617
+ const joined = Buffer.concat(pending, pendingSize);
618
+ yield joined.subarray(0, partSize);
619
+ const leftover = joined.subarray(partSize);
620
+ pending = leftover.length > 0 ? [leftover] : [];
621
+ pendingSize = leftover.length;
622
+ }
623
+ }
624
+ if (pendingSize > 0) {
625
+ yield Buffer.concat(pending, pendingSize);
626
+ }
627
+ }
628
+ /**
629
+ * Quick-and-narrow ACL XML classification: treat the object as public
630
+ * iff the ACL grants `READ` to the `AllUsers` group. Anything else
631
+ * (specific-user grants, `AuthenticatedUsers`, no Grant block) maps to
632
+ * `private`. Good enough for the two-state visibility API — upgrading
633
+ * to a real XML parser would just add a dependency without shifting
634
+ * the result.
635
+ */
636
+ function isPublicAcl(xml) {
637
+ // Normalise whitespace to keep the regex tractable across S3/MinIO/R2
638
+ // variants that differ in indentation and attribute order.
639
+ const flat = xml.replace(/\s+/g, " ");
640
+ return /<Grant>[^<]*<Grantee[^>]*>[^<]*<URI>[^<]*AllUsers<\/URI>[^<]*<\/Grantee>[^<]*<Permission>\s*READ\s*<\/Permission>/i.test(flat);
641
+ }
642
+ //# sourceMappingURL=S3Driver.js.map