@c9up/archive 0.1.20 → 0.1.21

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 (87) hide show
  1. package/README.md +96 -3
  2. package/dist/ArchiveProvider.d.ts +6 -1
  3. package/dist/ArchiveProvider.d.ts.map +1 -1
  4. package/dist/ArchiveProvider.js +73 -1
  5. package/dist/ArchiveProvider.js.map +1 -1
  6. package/dist/DriveManager.d.ts +10 -3
  7. package/dist/DriveManager.d.ts.map +1 -1
  8. package/dist/DriveManager.js +23 -6
  9. package/dist/DriveManager.js.map +1 -1
  10. package/dist/GcsDriver.d.ts +14 -9
  11. package/dist/GcsDriver.d.ts.map +1 -1
  12. package/dist/GcsDriver.js +202 -98
  13. package/dist/GcsDriver.js.map +1 -1
  14. package/dist/S3Driver.d.ts +11 -7
  15. package/dist/S3Driver.d.ts.map +1 -1
  16. package/dist/S3Driver.js +73 -110
  17. package/dist/S3Driver.js.map +1 -1
  18. package/dist/StaticMiddleware.d.ts +5 -1
  19. package/dist/StaticMiddleware.d.ts.map +1 -1
  20. package/dist/StaticMiddleware.js +114 -13
  21. package/dist/StaticMiddleware.js.map +1 -1
  22. package/dist/StorageManager.d.ts +28 -3
  23. package/dist/StorageManager.d.ts.map +1 -1
  24. package/dist/StorageManager.js +333 -132
  25. package/dist/StorageManager.js.map +1 -1
  26. package/dist/augmentations.d.ts +17 -0
  27. package/dist/augmentations.d.ts.map +1 -1
  28. package/dist/errno.d.ts +6 -0
  29. package/dist/errno.d.ts.map +1 -0
  30. package/dist/errno.js +11 -0
  31. package/dist/errno.js.map +1 -0
  32. package/dist/index.d.ts +1 -0
  33. package/dist/index.d.ts.map +1 -1
  34. package/dist/index.js.map +1 -1
  35. package/dist/keys.d.ts +34 -0
  36. package/dist/keys.d.ts.map +1 -0
  37. package/dist/keys.js +88 -0
  38. package/dist/keys.js.map +1 -0
  39. package/dist/local-signature.d.ts +32 -0
  40. package/dist/local-signature.d.ts.map +1 -0
  41. package/dist/local-signature.js +58 -0
  42. package/dist/local-signature.js.map +1 -0
  43. package/dist/move-to-disk.d.ts +24 -0
  44. package/dist/move-to-disk.d.ts.map +1 -0
  45. package/dist/move-to-disk.js +167 -0
  46. package/dist/move-to-disk.js.map +1 -0
  47. package/dist/objects.d.ts.map +1 -1
  48. package/dist/objects.js +5 -2
  49. package/dist/objects.js.map +1 -1
  50. package/dist/provider-fetch.d.ts +36 -0
  51. package/dist/provider-fetch.d.ts.map +1 -0
  52. package/dist/provider-fetch.js +158 -0
  53. package/dist/provider-fetch.js.map +1 -0
  54. package/dist/services/main.d.ts +1 -1
  55. package/dist/services/main.d.ts.map +1 -1
  56. package/dist/services/main.js +14 -1
  57. package/dist/services/main.js.map +1 -1
  58. package/dist/signed-route.d.ts +18 -6
  59. package/dist/signed-route.d.ts.map +1 -1
  60. package/dist/signed-route.js +186 -31
  61. package/dist/signed-route.js.map +1 -1
  62. package/dist/streams.d.ts +36 -0
  63. package/dist/streams.d.ts.map +1 -0
  64. package/dist/streams.js +108 -0
  65. package/dist/streams.js.map +1 -0
  66. package/dist/testing/FakeStorage.d.ts.map +1 -1
  67. package/dist/testing/FakeStorage.js +2 -1
  68. package/dist/testing/FakeStorage.js.map +1 -1
  69. package/package.json +7 -3
  70. package/src/ArchiveProvider.ts +105 -4
  71. package/src/DriveManager.ts +32 -6
  72. package/src/GcsDriver.ts +256 -139
  73. package/src/S3Driver.ts +87 -130
  74. package/src/StaticMiddleware.ts +124 -13
  75. package/src/StorageManager.ts +398 -141
  76. package/src/augmentations.ts +24 -1
  77. package/src/errno.ts +10 -0
  78. package/src/index.ts +1 -0
  79. package/src/keys.ts +104 -0
  80. package/src/local-signature.ts +76 -0
  81. package/src/move-to-disk.ts +234 -0
  82. package/src/objects.ts +5 -2
  83. package/src/provider-fetch.ts +171 -0
  84. package/src/services/main.ts +15 -2
  85. package/src/signed-route.ts +216 -36
  86. package/src/streams.ts +118 -0
  87. package/src/testing/FakeStorage.ts +2 -3
@@ -10,12 +10,19 @@ import * as fsp from "node:fs/promises";
10
10
  import * as path from "node:path";
11
11
  import { pipeline } from "node:stream/promises";
12
12
  import * as url from "node:url";
13
+ import { errnoCode } from "./errno.js";
13
14
  import { ArchiveError } from "./errors.js";
14
15
  import {
15
16
  assertValidExpiry,
16
17
  DEFAULT_EXPIRES_IN,
17
18
  parseExpiry,
18
19
  } from "./expiry.js";
20
+ import { normalizeKey, normalizePrefix } from "./keys.js";
21
+ import {
22
+ overrideQuery,
23
+ requestedOverrides,
24
+ signedPayload,
25
+ } from "./local-signature.js";
19
26
  import { inferMimeType } from "./mime-types.js";
20
27
  import { DriveDirectory, DriveFile, type FileSnapshot } from "./objects.js";
21
28
 
@@ -29,9 +36,17 @@ export interface SignedUrlOptions {
29
36
  * (5 minutes). Bounds after parsing: 1–604800.
30
37
  */
31
38
  expiresIn?: number | string;
32
- /** Sets the response `Content-Type` served with the signed URL (cloud drivers). */
39
+ /**
40
+ * Sets the response `Content-Type` served with the signed URL. Cloud
41
+ * drivers pass it to the provider; the local disk signs it into the URL
42
+ * and the signed route sends it.
43
+ */
33
44
  contentType?: string;
34
- /** Sets the response `Content-Disposition` served with the signed URL (cloud drivers). */
45
+ /**
46
+ * Sets the response `Content-Disposition` served with the signed URL —
47
+ * `attachment; filename="…"` to download rather than display. Same
48
+ * handling as {@link SignedUrlOptions.contentType}.
49
+ */
35
50
  contentDisposition?: string;
36
51
  }
37
52
 
@@ -263,6 +278,13 @@ export interface LocalDriverOptions {
263
278
  * declares it with `Env.schema.secret()`), released once by the driver.
264
279
  */
265
280
  signingSecret?: string | ReleasableSecret;
281
+ /**
282
+ * The URL path files are served under (default `/storage`). `publicUrl`,
283
+ * `url` and `getSignedUrl` build on it, and the signed route reads it from
284
+ * the driver, so the URLs handed out and the route serving them cannot
285
+ * disagree. A trailing `/` is dropped.
286
+ */
287
+ routeBasePath?: string;
266
288
  }
267
289
 
268
290
  /** Anything that releases a secret string — an environment `Secret`. */
@@ -297,9 +319,29 @@ function releaseSecret(secret: unknown): string | undefined {
297
319
  */
298
320
  const O_NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
299
321
 
322
+ /**
323
+ * A route base path, without its trailing `/`. Refused unless it is an
324
+ * absolute URL path with at least one segment and nothing a URL would read
325
+ * as a query, a fragment or a break.
326
+ */
327
+ function routeBasePath(given: string): string {
328
+ const trimmed = given.replace(/\/+$/, "");
329
+ if (!/^(\/[^/?#\s]+)+$/.test(trimmed)) {
330
+ throw new ArchiveError(
331
+ "E_ARCHIVE_INVALID_ROUTE_BASE_PATH",
332
+ `LocalDriver routeBasePath must be an absolute URL path such as '/storage', got ${JSON.stringify(given)}`,
333
+ {
334
+ hint: "Start it with '/', name at least one segment, and leave out '?', '#' and whitespace.",
335
+ },
336
+ );
337
+ }
338
+ return trimmed;
339
+ }
340
+
300
341
  export class LocalDriver implements StorageDriver {
301
342
  #root: string;
302
343
  #signingSecret: string | null;
344
+ #routeBasePath: string;
303
345
 
304
346
  /**
305
347
  * The only synchronous filesystem access left in this driver, and the only
@@ -310,6 +352,9 @@ export class LocalDriver implements StorageDriver {
310
352
  * request in the process for its whole duration.
311
353
  */
312
354
  constructor(root: string, options?: LocalDriverOptions) {
355
+ // Validated before the root is created: a refused config leaves
356
+ // nothing behind on disk.
357
+ this.#routeBasePath = routeBasePath(options?.routeBasePath ?? "/storage");
313
358
  const resolved = path.resolve(root);
314
359
  if (!fs.existsSync(resolved)) {
315
360
  fs.mkdirSync(resolved, { recursive: true });
@@ -349,28 +394,50 @@ export class LocalDriver implements StorageDriver {
349
394
  * is the failure that matters.
350
395
  */
351
396
  #lexicalPath(filePath: string): string {
352
- // Reject control chars that would smuggle HMAC delimiters or
353
- // confuse path handling. `\n` (10) is the signing payload
354
- // separator — a filename containing `\n` could otherwise forge
355
- // `exp`. `\r` (13) and NUL (0) round out the trio.
356
- for (let i = 0; i < filePath.length; i++) {
357
- const code = filePath.charCodeAt(i);
358
- if (code === 0 || code === 10 || code === 13) {
359
- throw new Error(
360
- "Invalid filePath: control characters (NUL, LF, CR) are not allowed",
361
- );
362
- }
363
- }
364
- const full = path.resolve(this.#root, filePath);
365
- // Lexical guard — cheap and covers the `..` case.
366
- if (!full.startsWith(this.#root + path.sep) && full !== this.#root) {
367
- throw new Error(
397
+ const key = this.#key(filePath);
398
+ const full = path.resolve(this.#root, key);
399
+ // Lexical guard, kept behind the normaliser: a normalised key has no
400
+ // `..` and no leading `/`, but a drive-letter key resolves to an
401
+ // absolute path on Windows, and a containment check is not where to
402
+ // rely on one layer only.
403
+ if (!full.startsWith(this.#root + path.sep)) {
404
+ throw new ArchiveError(
405
+ "E_ARCHIVE_PATH_TRAVERSAL_DETECTED",
368
406
  `Path traversal blocked: '${filePath}' resolves outside storage root`,
407
+ { hint: "Keys are relative to the disk root." },
369
408
  );
370
409
  }
371
410
  return full;
372
411
  }
373
412
 
413
+ /**
414
+ * The normalised key (see `keys.ts`), refused when it names a visibility
415
+ * marker.
416
+ *
417
+ * Control characters are refused by the normaliser; that matters here
418
+ * because `\n` is the signing payload separator — a key containing one
419
+ * could otherwise forge `exp`.
420
+ */
421
+ #key(filePath: string): string {
422
+ const key = normalizeKey(filePath);
423
+ // The visibility markers live beside the files they describe, so a key
424
+ // naming one would let a caller write, delete or read the marker of
425
+ // another file — `put("secret.pdf.archive-visibility.json", …)` turned a
426
+ // private file public. Refused on every segment (a marker name used as a
427
+ // directory blocks the marker write too) and case-insensitively (the
428
+ // same file on a case-insensitive filesystem).
429
+ for (const segment of key.split("/")) {
430
+ if (segment.toLowerCase().endsWith(VISIBILITY_SIDECAR_SUFFIX)) {
431
+ throw new ArchiveError(
432
+ "E_ARCHIVE_INVALID_KEY",
433
+ `Invalid key '${filePath}': names ending in '${VISIBILITY_SIDECAR_SUFFIX}' are reserved for visibility markers`,
434
+ { hint: "Store the object under a name without that suffix." },
435
+ );
436
+ }
437
+ }
438
+ return key;
439
+ }
440
+
374
441
  /**
375
442
  * Resolve and validate a file path — prevents traversal outside
376
443
  * the root, INCLUDING via symlinks planted inside the root.
@@ -392,13 +459,15 @@ export class LocalDriver implements StorageDriver {
392
459
  !realProbe.startsWith(this.#root + path.sep) &&
393
460
  realProbe !== this.#root
394
461
  ) {
395
- throw new Error(
462
+ throw new ArchiveError(
463
+ "E_ARCHIVE_PATH_TRAVERSAL_DETECTED",
396
464
  `Path traversal blocked: '${filePath}' resolves outside storage root via symlink`,
465
+ { hint: "A link inside the disk root points outside it." },
397
466
  );
398
467
  }
399
468
  return full;
400
469
  } catch (err) {
401
- if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
470
+ if (errnoCode(err) !== "ENOENT") throw err;
402
471
  const parent = path.dirname(probe);
403
472
  // The root itself is canonicalised at construction, so the walk
404
473
  // always terminates at something that resolves.
@@ -423,8 +492,88 @@ export class LocalDriver implements StorageDriver {
423
492
  // by name follows it — the check passed on one object and the write
424
493
  // landed on another. Refusing to follow a link at open time takes the
425
494
  // swap off the table: the open fails instead of writing outside the root.
495
+ //
496
+ // Only `visibility` has a filesystem-equivalent (the marker);
497
+ // contentType/cacheControl/... have no local meaning.
498
+ await this.#writeMarked(full, options?.visibility, async () => {
499
+ const handle = await fsp.open(
500
+ full,
501
+ fs.constants.O_WRONLY |
502
+ fs.constants.O_CREAT |
503
+ fs.constants.O_TRUNC |
504
+ O_NOFOLLOW,
505
+ 0o666,
506
+ );
507
+ try {
508
+ await handle.writeFile(content);
509
+ } finally {
510
+ await handle.close();
511
+ }
512
+ });
513
+ }
514
+
515
+ /**
516
+ * Run `write`, which puts data at `full`, and leave the object with
517
+ * `visibility` — without it ever being readable as public while it should
518
+ * not be.
519
+ *
520
+ * The marker is a second file, and its absence means public. A PRIVATE
521
+ * marker therefore goes down BEFORE the data: written after, the object
522
+ * was public for the whole write — served unsigned by the signed route and
523
+ * by a static server over the disk — and stayed public for good when the
524
+ * marker write failed. If the data write then fails, the half-written
525
+ * object is removed, and its marker only once the data is gone: the object
526
+ * ends private or absent, never public.
527
+ *
528
+ * A PUBLIC marker goes down AFTER the data, for the same reason the other
529
+ * way round: the bytes being replaced may be private, and they keep their
530
+ * marker until the new ones have landed.
531
+ */
532
+ async #writeMarked(
533
+ full: string,
534
+ visibility: Visibility | undefined,
535
+ write: () => Promise<void>,
536
+ ): Promise<void> {
537
+ if (visibility !== "private") {
538
+ await write();
539
+ if (visibility !== undefined) await this.#writeMarker(full, visibility);
540
+ return;
541
+ }
542
+ await this.#markPrivate(full);
543
+ try {
544
+ await write();
545
+ } catch (err) {
546
+ await discardPrivate(full);
547
+ throw err;
548
+ }
549
+ }
550
+
551
+ /**
552
+ * Mark `full` private before its data is touched. A marker write that
553
+ * fails puts the previous marker back (or leaves a damaged one, which
554
+ * reads as undetermined and is served to nobody), and rethrows: the
555
+ * caller writes no data.
556
+ */
557
+ async #markPrivate(full: string): Promise<MarkerSnapshot> {
558
+ const previous = await markerSnapshot(full);
559
+ try {
560
+ await this.#writeMarker(full, "private");
561
+ } catch (err) {
562
+ await restoreMarker(full, previous);
563
+ throw err;
564
+ }
565
+ return previous;
566
+ }
567
+
568
+ /**
569
+ * Write the visibility marker of the file at `full`, a path `#safePath`
570
+ * already resolved. Through an O_NOFOLLOW descriptor, as the data is: a
571
+ * link planted at the marker's name is refused rather than followed to
572
+ * write outside the root.
573
+ */
574
+ async #writeMarker(full: string, visibility: Visibility): Promise<void> {
426
575
  const handle = await fsp.open(
427
- full,
576
+ full + VISIBILITY_SIDECAR_SUFFIX,
428
577
  fs.constants.O_WRONLY |
429
578
  fs.constants.O_CREAT |
430
579
  fs.constants.O_TRUNC |
@@ -432,15 +581,10 @@ export class LocalDriver implements StorageDriver {
432
581
  0o666,
433
582
  );
434
583
  try {
435
- await handle.writeFile(content);
584
+ await handle.writeFile(JSON.stringify({ visibility }));
436
585
  } finally {
437
586
  await handle.close();
438
587
  }
439
- // Only `visibility` has a filesystem-equivalent (the sidecar).
440
- // contentType/cacheControl/... have no local meaning.
441
- if (options?.visibility !== undefined) {
442
- await this.setVisibility(filePath, options.visibility);
443
- }
444
588
  }
445
589
 
446
590
  async getBytes(filePath: string): Promise<Uint8Array> {
@@ -493,7 +637,7 @@ export class LocalDriver implements StorageDriver {
493
637
  } catch (err) {
494
638
  // One syscall instead of exists-then-read: the pair also answered
495
639
  // `null` for a file that was deleted between the two.
496
- if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
640
+ if (errnoCode(err) === "ENOENT") return null;
497
641
  throw err;
498
642
  }
499
643
  }
@@ -508,7 +652,7 @@ export class LocalDriver implements StorageDriver {
508
652
  try {
509
653
  handle = await fsp.open(full, fs.constants.O_RDONLY | O_NOFOLLOW);
510
654
  } catch (err) {
511
- if ((err as NodeJS.ErrnoException).code === "ENOENT") {
655
+ if (errnoCode(err) === "ENOENT") {
512
656
  throw new ArchiveError(
513
657
  "E_ARCHIVE_NOT_FOUND",
514
658
  `File does not exist at path '${filePath}'`,
@@ -526,7 +670,7 @@ export class LocalDriver implements StorageDriver {
526
670
  try {
527
671
  await fsp.unlink(full);
528
672
  } catch (err) {
529
- if ((err as NodeJS.ErrnoException).code === "ENOENT") return false;
673
+ if (errnoCode(err) === "ENOENT") return false;
530
674
  throw err;
531
675
  }
532
676
  // Sidecar cleanup is best-effort. The main file is already gone
@@ -543,9 +687,7 @@ export class LocalDriver implements StorageDriver {
543
687
  }
544
688
 
545
689
  async exists(filePath: string): Promise<boolean> {
546
- // Sidecars are an implementation detail — pretend they don't
547
- // exist from the public API's point of view.
548
- if (filePath.endsWith(VISIBILITY_SIDECAR_SUFFIX)) return false;
690
+ // A marker name is refused by the path guard, as by every other method.
549
691
  return exists(await this.#safePath(filePath));
550
692
  }
551
693
 
@@ -554,11 +696,20 @@ export class LocalDriver implements StorageDriver {
554
696
  // survive the trip through an HTTP layer. The middleware mirrors
555
697
  // this by decoding each segment before recomputing the HMAC —
556
698
  // skipping encoding here would leave the URL unparseable.
557
- const encoded = filePath
699
+ const encoded = this.#key(filePath)
558
700
  .split("/")
559
701
  .map((seg) => encodeURIComponent(seg))
560
702
  .join("/");
561
- return `/storage/${encoded}`;
703
+ return `${this.#routeBasePath}/${encoded}`;
704
+ }
705
+
706
+ /**
707
+ * The URL path this driver's files are served under. The signed route
708
+ * reads it, so the URLs this driver builds and the route that serves them
709
+ * derive from one value.
710
+ */
711
+ getRouteBasePath(): string {
712
+ return this.#routeBasePath;
562
713
  }
563
714
 
564
715
  async url(filePath: string): Promise<string> {
@@ -573,7 +724,7 @@ export class LocalDriver implements StorageDriver {
573
724
  try {
574
725
  stat = await fsp.stat(full);
575
726
  } catch (err) {
576
- if ((err as NodeJS.ErrnoException).code === "ENOENT") {
727
+ if (errnoCode(err) === "ENOENT") {
577
728
  throw new ArchiveError(
578
729
  "E_ARCHIVE_NOT_FOUND",
579
730
  `File does not exist at path '${filePath}'`,
@@ -614,8 +765,7 @@ export class LocalDriver implements StorageDriver {
614
765
  { hint: "put() the file before calling setVisibility()." },
615
766
  );
616
767
  }
617
- const sidecar = full + VISIBILITY_SIDECAR_SUFFIX;
618
- await fsp.writeFile(sidecar, JSON.stringify({ visibility }), { flag: "w" });
768
+ await this.#writeMarker(full, visibility);
619
769
  }
620
770
 
621
771
  /**
@@ -636,18 +786,18 @@ export class LocalDriver implements StorageDriver {
636
786
  } catch (err) {
637
787
  // Absent sidecar is the documented default, and it is the common
638
788
  // case: one syscall answers both that and a real read failure.
639
- if ((err as NodeJS.ErrnoException).code === "ENOENT") return "public";
789
+ if (errnoCode(err) === "ENOENT") return "public";
640
790
  throw new ArchiveError(
641
791
  "E_ARCHIVE_VISIBILITY_CORRUPT",
642
- `Failed to read visibility sidecar for '${filePath}' (${(err as NodeJS.ErrnoException).code ?? "I/O error"}); refusing to default to 'public'.`,
792
+ `Failed to read visibility sidecar for '${filePath}' (${errnoCode(err) ?? "I/O error"}); refusing to default to 'public'.`,
643
793
  {
644
794
  hint: "Inspect the sidecar file or re-apply visibility via setVisibility().",
645
795
  },
646
796
  );
647
797
  }
648
- let parsed: { visibility?: unknown };
798
+ let parsed: unknown;
649
799
  try {
650
- parsed = JSON.parse(raw) as { visibility?: unknown };
800
+ parsed = JSON.parse(raw);
651
801
  } catch {
652
802
  throw new ArchiveError(
653
803
  "E_ARCHIVE_VISIBILITY_CORRUPT",
@@ -665,12 +815,16 @@ export class LocalDriver implements StorageDriver {
665
815
  // handed out `/storage/<path>` instead of a signed URL. The doc comment
666
816
  // above already promised this for unparseable JSON; a JSON document
667
817
  // that parses and says nothing usable is the same situation.
668
- if (parsed.visibility === "private" || parsed.visibility === "public") {
669
- return parsed.visibility;
818
+ const visibility =
819
+ typeof parsed === "object" && parsed !== null && "visibility" in parsed
820
+ ? parsed.visibility
821
+ : undefined;
822
+ if (visibility === "private" || visibility === "public") {
823
+ return visibility;
670
824
  }
671
825
  throw new ArchiveError(
672
826
  "E_ARCHIVE_VISIBILITY_CORRUPT",
673
- `Sidecar for '${filePath}' carries no usable visibility (${JSON.stringify(parsed.visibility)}); refusing to default to 'public'.`,
827
+ `Sidecar for '${filePath}' carries no usable visibility (${JSON.stringify(visibility)}); refusing to default to 'public'.`,
674
828
  {
675
829
  hint: "Delete the sidecar file and re-apply visibility via setVisibility().",
676
830
  },
@@ -687,8 +841,10 @@ export class LocalDriver implements StorageDriver {
687
841
  // signing a URL reads no file — the read it leads to goes through the
688
842
  // full check. What must NOT be skipped here is the control-character
689
843
  // rejection, since `\n` is this signature's own payload separator, and
690
- // `#lexicalPath` is where that lives.
844
+ // `#lexicalPath` is where that lives. What is signed is the
845
+ // normalised key, which is what the route recomputes it over.
691
846
  this.#lexicalPath(filePath);
847
+ const key = this.#key(filePath);
692
848
  const expiresIn = parseExpiry(options?.expiresIn ?? DEFAULT_EXPIRES_IN);
693
849
  assertValidExpiry(expiresIn);
694
850
  const secret = this.#signingSecret;
@@ -705,9 +861,13 @@ export class LocalDriver implements StorageDriver {
705
861
  // Newline-delimited payload: a filePath cannot forge `exp` by
706
862
  // embedding `&exp=...` in its own bytes (URL-decoding still
707
863
  // keeps the literal `\n` separator in the signed material).
708
- const message = `${filePath}\n${exp}`;
864
+ // Response-header overrides are signed with the rest and carried in the
865
+ // query, where the signed route reads, verifies and emits them.
866
+ const overrides = requestedOverrides(options ?? {});
867
+ const message = signedPayload(key, exp, overrides);
709
868
  const sig = createHmac("sha256", secret).update(message).digest("hex");
710
- return `${this.publicUrl(filePath)}?exp=${exp}&sig=${sig}`;
869
+ const url = `${this.publicUrl(key)}?exp=${exp}&sig=${sig}`;
870
+ return overrides.length === 0 ? url : `${url}&${overrideQuery(overrides)}`;
711
871
  }
712
872
 
713
873
  /**
@@ -744,12 +904,12 @@ export class LocalDriver implements StorageDriver {
744
904
  );
745
905
  }
746
906
  await fsp.mkdir(path.dirname(toFull), { recursive: true });
747
- await fsp.copyFile(fromFull, toFull);
748
907
  // Intentionally do NOT copy the visibility sidecar — new object
749
- // takes default visibility unless the caller asks otherwise.
750
- if (options?.visibility !== undefined) {
751
- await this.setVisibility(to, options.visibility);
752
- }
908
+ // takes default visibility unless the caller asks otherwise. A private
909
+ // one is marked before the bytes are copied, as put() does.
910
+ await this.#writeMarked(toFull, options?.visibility, () =>
911
+ fsp.copyFile(fromFull, toFull),
912
+ );
753
913
  }
754
914
 
755
915
  async move(from: string, to: string, options?: WriteOptions): Promise<void> {
@@ -768,44 +928,54 @@ export class LocalDriver implements StorageDriver {
768
928
  // silently downgrade private→public. `#readVisibility` throws on
769
929
  // corruption, which surfaces here BEFORE we mutate anything.
770
930
  const fromSidecar = fromFull + VISIBILITY_SIDECAR_SUFFIX;
771
- const toSidecar = toFull + VISIBILITY_SIDECAR_SUFFIX;
772
931
  const capturedVisibility: Visibility | undefined = (await exists(
773
932
  fromSidecar,
774
933
  ))
775
934
  ? await this.#readVisibility(from)
776
935
  : undefined;
936
+ // An explicit visibility override wins over the preserved value.
937
+ const target = options?.visibility ?? capturedVisibility;
777
938
  await fsp.mkdir(path.dirname(toFull), { recursive: true });
939
+ // A private target is marked BEFORE the file arrives: renamed first, the
940
+ // moved private file sat at the target with no marker — public — until
941
+ // the second write, and for good when that write failed.
942
+ const previous =
943
+ target === "private" ? await this.#markPrivate(toFull) : undefined;
778
944
  try {
779
945
  await fsp.rename(fromFull, toFull);
780
946
  } catch (err) {
781
- // Cross-device rename — fall back to copy+unlink.
782
- if ((err as NodeJS.ErrnoException).code === "EXDEV") {
783
- await fsp.copyFile(fromFull, toFull);
784
- await fsp.unlink(fromFull);
785
- } else {
947
+ if (errnoCode(err) !== "EXDEV") {
948
+ // Nothing moved: the target is what it was, so is its marker.
949
+ if (previous !== undefined) await restoreMarker(toFull, previous);
786
950
  throw err;
787
951
  }
952
+ // Cross-device rename — fall back to copy+unlink. A half-copied
953
+ // target is removed, and its marker only once the data is gone.
954
+ try {
955
+ await fsp.copyFile(fromFull, toFull);
956
+ } catch (copyErr) {
957
+ await discardPrivate(toFull);
958
+ throw copyErr;
959
+ }
960
+ await fsp.unlink(fromFull);
788
961
  }
789
- // Visibility carries forward by re-writing the new sidecar from
790
- // captured data — atomic relative to the rename, immune to the
791
- // EXDEV/perm failure modes that plagued the rename-the-sidecar path.
792
- // Public is the default, so an absent source sidecar means no work.
793
- if (capturedVisibility !== undefined) {
962
+ // A public target is marked AFTER the move: until then, whatever was at
963
+ // the target keeps its own marker. Public is the default, so an absent
964
+ // source sidecar and no override mean no work.
965
+ if (target === "public") {
794
966
  try {
795
- await fsp.writeFile(
796
- toSidecar,
797
- JSON.stringify({ visibility: capturedVisibility }),
798
- { flag: "w" },
799
- );
967
+ await this.#writeMarker(toFull, target);
800
968
  } catch (err) {
801
969
  throw new ArchiveError(
802
970
  "E_ARCHIVE_VISIBILITY_MOVE_FAILED",
803
- `move('${from}' -> '${to}'): main file moved but visibility sidecar write failed (${(err as NodeJS.ErrnoException).code ?? "unknown"}). Target visibility is undefined.`,
971
+ `move('${from}' -> '${to}'): main file moved but visibility sidecar write failed (${errnoCode(err) ?? "unknown"}). Target visibility is undefined.`,
804
972
  {
805
973
  hint: "Re-apply visibility via setVisibility() on the target path.",
806
974
  },
807
975
  );
808
976
  }
977
+ }
978
+ if (capturedVisibility !== undefined) {
809
979
  // Best-effort cleanup of the source sidecar — visibility is already
810
980
  // preserved on the target side. A failure here leaves a stale
811
981
  // sidecar pointing at the now-missing source file; benign.
@@ -815,17 +985,14 @@ export class LocalDriver implements StorageDriver {
815
985
  // benign — source dir may be cleaned up by later operations.
816
986
  }
817
987
  }
818
- // An explicit visibility override wins over the preserved value.
819
- if (options?.visibility !== undefined) {
820
- await this.setVisibility(to, options.visibility);
821
- }
822
988
  }
823
989
 
824
990
  async deleteAll(prefix: string): Promise<void> {
825
991
  // Walk the existing listing (already sidecar-aware + safe) and
826
992
  // remove every match. delete() also drops each file's sidecar.
993
+ const normalized = normalizePrefix(prefix);
827
994
  const paths: string[] = [];
828
- for await (const entry of this.list(prefix)) {
995
+ for await (const entry of this.list(normalized)) {
829
996
  paths.push(entry.path);
830
997
  }
831
998
  for (const p of paths) {
@@ -833,8 +1000,8 @@ export class LocalDriver implements StorageDriver {
833
1000
  }
834
1001
  // Prune the prefix directory itself when it is now empty, mirroring
835
1002
  // flydrive's "the folder is deleted" behaviour. Best-effort.
836
- const dir = await this.#safePath(prefix);
837
- if (dir !== this.#root) {
1003
+ if (normalized !== "") {
1004
+ const dir = await this.#safePath(normalized);
838
1005
  try {
839
1006
  const stat = await fsp.stat(dir);
840
1007
  if (stat.isDirectory() && (await fsp.readdir(dir)).length === 0) {
@@ -853,12 +1020,9 @@ export class LocalDriver implements StorageDriver {
853
1020
  const recursive = options?.recursive ?? false;
854
1021
  const files: DriveFile[] = [];
855
1022
  const directories = new Map<string, DriveDirectory>();
1023
+ const given = normalizePrefix(prefix);
856
1024
  const normalizedPrefix =
857
- prefix === "" || prefix === "/"
858
- ? ""
859
- : prefix.endsWith("/")
860
- ? prefix
861
- : `${prefix}/`;
1025
+ given === "" || given.endsWith("/") ? given : `${given}/`;
862
1026
  for await (const entry of this.list(normalizedPrefix)) {
863
1027
  if (recursive) {
864
1028
  files.push(
@@ -881,6 +1045,9 @@ export class LocalDriver implements StorageDriver {
881
1045
  }
882
1046
  }
883
1047
  }
1048
+ // Sorted by key, as upstream lists: the walk's order is the
1049
+ // filesystem's, which differs between machines.
1050
+ files.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
884
1051
  return { objects: [...directories.values(), ...files] };
885
1052
  }
886
1053
 
@@ -898,31 +1065,33 @@ export class LocalDriver implements StorageDriver {
898
1065
  };
899
1066
  }
900
1067
 
901
- async *list(prefix: string): AsyncIterable<StorageEntry> {
902
- // `recursive: true` gives us every descendant in one call;
903
- // `withFileTypes: true` lets us skip directories and inspect each
904
- // entry without a follow-up stat for type.
905
- let entries: fs.Dirent[];
1068
+ async *list(given: string): AsyncIterable<StorageEntry> {
1069
+ const prefix = normalizePrefix(given);
1070
+ // Start the walk at the deepest directory the prefix names, not at the
1071
+ // root: `avatars/42/` reads `avatars/42`, `avatars/4` reads
1072
+ // `avatars`. Walking the whole root and filtering afterwards cost the
1073
+ // size of the entire disk for every listing, however narrow.
1074
+ const slash = prefix.lastIndexOf("/");
1075
+ const dir = slash === -1 ? "" : prefix.slice(0, slash);
1076
+ const start = dir === "" ? this.#root : await this.#safePath(dir);
1077
+ let walk: fs.Dir;
906
1078
  try {
907
- entries = await fsp.readdir(this.#root, {
908
- recursive: true,
909
- withFileTypes: true,
910
- });
1079
+ // Read lazily: entries arrive as the walk reaches them instead of
1080
+ // the whole subtree being held in memory first. Links are listed,
1081
+ // not followed, so the walk stays inside the root.
1082
+ walk = await fsp.opendir(start, { recursive: true });
911
1083
  } catch (err) {
912
- if ((err as NodeJS.ErrnoException).code === "ENOENT") return;
1084
+ const code = errnoCode(err);
1085
+ // Nothing stored under that prefix, or it names a file.
1086
+ if (code === "ENOENT" || code === "ENOTDIR") return;
913
1087
  throw err;
914
1088
  }
915
- for (const entry of entries) {
1089
+ for await (const entry of walk) {
916
1090
  if (!entry.isFile()) continue;
917
- // `parentPath` is typed on Dirent since Node 20.12, which the engine
918
- // range already requires — the double cast that used to read it
919
- // (and its `path` fallback for older shapes) is no longer buying
920
- // anything.
921
- const parent = entry.parentPath ?? this.#root;
922
- const full = path.join(parent, entry.name);
1091
+ const full = path.join(entry.parentPath, entry.name);
923
1092
  const rel = path.relative(this.#root, full).split(path.sep).join("/");
924
1093
  // Exclude sidecars — implementation detail.
925
- if (rel.endsWith(VISIBILITY_SIDECAR_SUFFIX)) continue;
1094
+ if (rel.toLowerCase().endsWith(VISIBILITY_SIDECAR_SUFFIX)) continue;
926
1095
  if (!rel.startsWith(prefix)) continue;
927
1096
  const stat = await fsp.stat(full);
928
1097
  yield { path: rel, size: stat.size, lastModified: stat.mtime };
@@ -930,6 +1099,82 @@ export class LocalDriver implements StorageDriver {
930
1099
  }
931
1100
  }
932
1101
 
1102
+ /**
1103
+ * What a visibility marker held before a write replaced it, so a write that
1104
+ * fails can put it back. `unknown` — a marker that could not be read, a link
1105
+ * planted at its name — is never touched again.
1106
+ */
1107
+ type MarkerSnapshot =
1108
+ | { readonly state: "absent" }
1109
+ | { readonly state: "present"; readonly bytes: Buffer }
1110
+ | { readonly state: "unknown" };
1111
+
1112
+ /** The marker of the file at `full` as it is now. */
1113
+ async function markerSnapshot(full: string): Promise<MarkerSnapshot> {
1114
+ try {
1115
+ const handle = await fsp.open(
1116
+ full + VISIBILITY_SIDECAR_SUFFIX,
1117
+ fs.constants.O_RDONLY | O_NOFOLLOW,
1118
+ );
1119
+ try {
1120
+ return { state: "present", bytes: await handle.readFile() };
1121
+ } finally {
1122
+ await handle.close();
1123
+ }
1124
+ } catch (err) {
1125
+ return errnoCode(err) === "ENOENT"
1126
+ ? { state: "absent" }
1127
+ : { state: "unknown" };
1128
+ }
1129
+ }
1130
+
1131
+ /**
1132
+ * Put back the marker `snapshot` recorded. Best-effort, never throws: it runs
1133
+ * on a path that is already failing, and a restore that fails leaves the
1134
+ * private marker (or a damaged one, read as undetermined) — closed either way.
1135
+ */
1136
+ async function restoreMarker(
1137
+ full: string,
1138
+ snapshot: MarkerSnapshot,
1139
+ ): Promise<void> {
1140
+ const marker = full + VISIBILITY_SIDECAR_SUFFIX;
1141
+ try {
1142
+ if (snapshot.state === "absent") {
1143
+ await fsp.unlink(marker);
1144
+ } else if (snapshot.state === "present") {
1145
+ const handle = await fsp.open(
1146
+ marker,
1147
+ fs.constants.O_WRONLY | fs.constants.O_TRUNC | O_NOFOLLOW,
1148
+ );
1149
+ try {
1150
+ await handle.writeFile(snapshot.bytes);
1151
+ } finally {
1152
+ await handle.close();
1153
+ }
1154
+ }
1155
+ } catch {
1156
+ // Closed either way — see above.
1157
+ }
1158
+ }
1159
+
1160
+ /**
1161
+ * Remove a private object whose data write failed half-way: the data first,
1162
+ * then its marker — only once the data is gone, so the bytes are never left
1163
+ * without the marker that keeps them private. Never throws.
1164
+ */
1165
+ async function discardPrivate(full: string): Promise<void> {
1166
+ try {
1167
+ await fsp.unlink(full);
1168
+ } catch (err) {
1169
+ if (errnoCode(err) !== "ENOENT") return;
1170
+ }
1171
+ try {
1172
+ await fsp.unlink(full + VISIBILITY_SIDECAR_SUFFIX);
1173
+ } catch {
1174
+ // An orphan marker serves nothing.
1175
+ }
1176
+ }
1177
+
933
1178
  /**
934
1179
  * Whether a path exists, without `existsSync` blocking the event loop.
935
1180
  *
@@ -951,6 +1196,10 @@ function localPath(source: string | URL): string {
951
1196
  return source instanceof URL ? url.fileURLToPath(source) : source;
952
1197
  }
953
1198
 
1199
+ /**
1200
+ * The disk an application talks to: one driver behind it, and every key
1201
+ * normalised (see `keys.ts`) before that driver sees it, whatever the driver.
1202
+ */
954
1203
  export class StorageManager {
955
1204
  #driver: StorageDriver;
956
1205
 
@@ -958,12 +1207,12 @@ export class StorageManager {
958
1207
  this.#driver = driver;
959
1208
  }
960
1209
 
961
- put(
1210
+ async put(
962
1211
  filePath: string,
963
1212
  content: Buffer | string,
964
1213
  options?: WriteOptions,
965
1214
  ): Promise<void> {
966
- return this.#driver.put(filePath, content, options);
1215
+ return this.#driver.put(normalizeKey(filePath), content, options);
967
1216
  }
968
1217
 
969
1218
  /**
@@ -1009,9 +1258,12 @@ export class StorageManager {
1009
1258
  destination: string,
1010
1259
  options?: WriteOptions,
1011
1260
  ): Promise<void> {
1261
+ // Before the source is opened: a destination that is not a valid key
1262
+ // is refused without a descriptor to clean up.
1263
+ const key = normalizeKey(destination);
1012
1264
  const stream = fs.createReadStream(localPath(source));
1013
1265
  try {
1014
- await this.#driver.putStream(destination, stream, options);
1266
+ await this.#driver.putStream(key, stream, options);
1015
1267
  } catch (error) {
1016
1268
  // The driver can reject BEFORE reading a byte — a destination outside
1017
1269
  // the disk is rejected up front. The stream is then never consumed:
@@ -1045,102 +1297,107 @@ export class StorageManager {
1045
1297
  await fs.promises.unlink(from);
1046
1298
  }
1047
1299
 
1048
- putStream(
1300
+ async putStream(
1049
1301
  filePath: string,
1050
1302
  readable: NodeJS.ReadableStream,
1051
1303
  options?: PutStreamOptions,
1052
1304
  ): Promise<void> {
1053
- return this.#driver.putStream(filePath, readable, options);
1305
+ return this.#driver.putStream(normalizeKey(filePath), readable, options);
1054
1306
  }
1055
1307
 
1056
- get(filePath: string): Promise<Buffer | null> {
1057
- return this.#driver.get(filePath);
1308
+ async get(filePath: string): Promise<Buffer | null> {
1309
+ return this.#driver.get(normalizeKey(filePath));
1058
1310
  }
1059
1311
 
1060
1312
  /** Contents as a `Uint8Array`. Throws `E_ARCHIVE_NOT_FOUND` if absent. */
1061
- getBytes(filePath: string): Promise<Uint8Array> {
1062
- return this.#driver.getBytes(filePath);
1313
+ async getBytes(filePath: string): Promise<Uint8Array> {
1314
+ return this.#driver.getBytes(normalizeKey(filePath));
1063
1315
  }
1064
1316
 
1065
1317
  /** @deprecated AdonisJS Drive alias — use {@link StorageManager.getBytes}. */
1066
- getArrayBuffer(filePath: string): Promise<Uint8Array> {
1067
- return this.#driver.getBytes(filePath);
1318
+ async getArrayBuffer(filePath: string): Promise<Uint8Array> {
1319
+ return this.#driver.getBytes(normalizeKey(filePath));
1068
1320
  }
1069
1321
 
1070
- getStream(filePath: string): Promise<NodeJS.ReadableStream> {
1071
- return this.#driver.getStream(filePath);
1322
+ async getStream(filePath: string): Promise<NodeJS.ReadableStream> {
1323
+ return this.#driver.getStream(normalizeKey(filePath));
1072
1324
  }
1073
1325
 
1074
- delete(filePath: string): Promise<boolean> {
1075
- return this.#driver.delete(filePath);
1326
+ async delete(filePath: string): Promise<boolean> {
1327
+ return this.#driver.delete(normalizeKey(filePath));
1076
1328
  }
1077
1329
 
1078
- exists(filePath: string): Promise<boolean> {
1079
- return this.#driver.exists(filePath);
1330
+ async exists(filePath: string): Promise<boolean> {
1331
+ return this.#driver.exists(normalizeKey(filePath));
1080
1332
  }
1081
1333
 
1082
- url(filePath: string): Promise<string> {
1083
- return this.#driver.url(filePath);
1334
+ async url(filePath: string): Promise<string> {
1335
+ return this.#driver.url(normalizeKey(filePath));
1084
1336
  }
1085
1337
 
1086
1338
  /** AdonisJS Drive name for {@link url}. */
1087
- getUrl(filePath: string): Promise<string> {
1088
- return this.#driver.url(filePath);
1339
+ async getUrl(filePath: string): Promise<string> {
1340
+ return this.#driver.url(normalizeKey(filePath));
1089
1341
  }
1090
1342
 
1091
1343
  publicUrl(filePath: string): string {
1092
- return this.#driver.publicUrl(filePath);
1344
+ return this.#driver.publicUrl(normalizeKey(filePath));
1093
1345
  }
1094
1346
 
1095
1347
  getSignedUrl(
1096
1348
  filePath: string,
1097
1349
  options?: SignedUrlOptions,
1098
1350
  ): string | Promise<string> {
1099
- return this.#driver.getSignedUrl(filePath, options);
1351
+ return this.#driver.getSignedUrl(normalizeKey(filePath), options);
1100
1352
  }
1101
1353
 
1102
1354
  getSignedUploadUrl(
1103
1355
  filePath: string,
1104
1356
  options?: SignedUrlOptions,
1105
1357
  ): string | Promise<string> {
1106
- return this.#driver.getSignedUploadUrl(filePath, options);
1358
+ return this.#driver.getSignedUploadUrl(normalizeKey(filePath), options);
1107
1359
  }
1108
1360
 
1109
- getMetadata(filePath: string): Promise<Metadata> {
1110
- return this.#driver.getMetadata(filePath);
1361
+ async getMetadata(filePath: string): Promise<Metadata> {
1362
+ return this.#driver.getMetadata(normalizeKey(filePath));
1111
1363
  }
1112
1364
 
1113
1365
  /** AdonisJS Drive casing for {@link getMetadata}. */
1114
- getMetaData(filePath: string): Promise<Metadata> {
1115
- return this.#driver.getMetadata(filePath);
1366
+ async getMetaData(filePath: string): Promise<Metadata> {
1367
+ return this.#driver.getMetadata(normalizeKey(filePath));
1116
1368
  }
1117
1369
 
1118
- getVisibility(filePath: string): Promise<Visibility> {
1119
- return this.#driver.getVisibility(filePath);
1370
+ async getVisibility(filePath: string): Promise<Visibility> {
1371
+ return this.#driver.getVisibility(normalizeKey(filePath));
1120
1372
  }
1121
1373
 
1122
- setVisibility(filePath: string, visibility: Visibility): Promise<void> {
1123
- return this.#driver.setVisibility(filePath, visibility);
1374
+ async setVisibility(filePath: string, visibility: Visibility): Promise<void> {
1375
+ return this.#driver.setVisibility(normalizeKey(filePath), visibility);
1124
1376
  }
1125
1377
 
1126
- copy(from: string, to: string, options?: WriteOptions): Promise<void> {
1127
- return this.#driver.copy(from, to, options);
1378
+ async copy(from: string, to: string, options?: WriteOptions): Promise<void> {
1379
+ return this.#driver.copy(normalizeKey(from), normalizeKey(to), options);
1128
1380
  }
1129
1381
 
1130
- move(from: string, to: string, options?: WriteOptions): Promise<void> {
1131
- return this.#driver.move(from, to, options);
1382
+ async move(from: string, to: string, options?: WriteOptions): Promise<void> {
1383
+ return this.#driver.move(normalizeKey(from), normalizeKey(to), options);
1132
1384
  }
1133
1385
 
1134
- deleteAll(prefix: string): Promise<void> {
1135
- return this.#driver.deleteAll(prefix);
1386
+ async deleteAll(prefix: string): Promise<void> {
1387
+ return this.#driver.deleteAll(normalizePrefix(prefix));
1136
1388
  }
1137
1389
 
1138
1390
  list(prefix: string): AsyncIterable<StorageEntry> {
1139
- return this.#driver.list(prefix);
1391
+ // Validated now, not on the first iteration: a refused prefix is the
1392
+ // caller's mistake and should surface where the call was made.
1393
+ return this.#driver.list(normalizePrefix(prefix));
1140
1394
  }
1141
1395
 
1142
1396
  /** AdonisJS Drive `listAll` — paged {@link DriveFile}/{@link DriveDirectory}. */
1143
- listAll(prefix: string, options?: ListAllOptions): Promise<ListAllResult> {
1144
- return this.#driver.listAll(prefix, options);
1397
+ async listAll(
1398
+ prefix: string,
1399
+ options?: ListAllOptions,
1400
+ ): Promise<ListAllResult> {
1401
+ return this.#driver.listAll(normalizePrefix(prefix), options);
1145
1402
  }
1146
1403
  }