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