@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
@@ -9,8 +9,11 @@ import * as fsp from "node:fs/promises";
9
9
  import * as path from "node:path";
10
10
  import { pipeline } from "node:stream/promises";
11
11
  import * as url from "node:url";
12
+ import { errnoCode } from "./errno.js";
12
13
  import { ArchiveError } from "./errors.js";
13
14
  import { assertValidExpiry, DEFAULT_EXPIRES_IN, parseExpiry, } from "./expiry.js";
15
+ import { normalizeKey, normalizePrefix } from "./keys.js";
16
+ import { overrideQuery, requestedOverrides, signedPayload, } from "./local-signature.js";
14
17
  import { inferMimeType } from "./mime-types.js";
15
18
  import { DriveDirectory, DriveFile } from "./objects.js";
16
19
  export { DriveDirectory, DriveFile } from "./objects.js";
@@ -45,9 +48,24 @@ function releaseSecret(secret) {
45
48
  * the flag is contributed only where it exists.
46
49
  */
47
50
  const O_NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
51
+ /**
52
+ * A route base path, without its trailing `/`. Refused unless it is an
53
+ * absolute URL path with at least one segment and nothing a URL would read
54
+ * as a query, a fragment or a break.
55
+ */
56
+ function routeBasePath(given) {
57
+ const trimmed = given.replace(/\/+$/, "");
58
+ if (!/^(\/[^/?#\s]+)+$/.test(trimmed)) {
59
+ throw new ArchiveError("E_ARCHIVE_INVALID_ROUTE_BASE_PATH", `LocalDriver routeBasePath must be an absolute URL path such as '/storage', got ${JSON.stringify(given)}`, {
60
+ hint: "Start it with '/', name at least one segment, and leave out '?', '#' and whitespace.",
61
+ });
62
+ }
63
+ return trimmed;
64
+ }
48
65
  export class LocalDriver {
49
66
  #root;
50
67
  #signingSecret;
68
+ #routeBasePath;
51
69
  /**
52
70
  * The only synchronous filesystem access left in this driver, and the only
53
71
  * one that cannot be anything else: a constructor cannot await. It runs
@@ -57,6 +75,9 @@ export class LocalDriver {
57
75
  * request in the process for its whole duration.
58
76
  */
59
77
  constructor(root, options) {
78
+ // Validated before the root is created: a refused config leaves
79
+ // nothing behind on disk.
80
+ this.#routeBasePath = routeBasePath(options?.routeBasePath ?? "/storage");
60
81
  const resolved = path.resolve(root);
61
82
  if (!fs.existsSync(resolved)) {
62
83
  fs.mkdirSync(resolved, { recursive: true });
@@ -91,23 +112,40 @@ export class LocalDriver {
91
112
  * is the failure that matters.
92
113
  */
93
114
  #lexicalPath(filePath) {
94
- // Reject control chars that would smuggle HMAC delimiters or
95
- // confuse path handling. `\n` (10) is the signing payload
96
- // separator — a filename containing `\n` could otherwise forge
97
- // `exp`. `\r` (13) and NUL (0) round out the trio.
98
- for (let i = 0; i < filePath.length; i++) {
99
- const code = filePath.charCodeAt(i);
100
- if (code === 0 || code === 10 || code === 13) {
101
- throw new Error("Invalid filePath: control characters (NUL, LF, CR) are not allowed");
102
- }
103
- }
104
- const full = path.resolve(this.#root, filePath);
105
- // Lexical guard — cheap and covers the `..` case.
106
- if (!full.startsWith(this.#root + path.sep) && full !== this.#root) {
107
- throw new Error(`Path traversal blocked: '${filePath}' resolves outside storage root`);
115
+ const key = this.#key(filePath);
116
+ const full = path.resolve(this.#root, key);
117
+ // Lexical guard, kept behind the normaliser: a normalised key has no
118
+ // `..` and no leading `/`, but a drive-letter key resolves to an
119
+ // absolute path on Windows, and a containment check is not where to
120
+ // rely on one layer only.
121
+ if (!full.startsWith(this.#root + path.sep)) {
122
+ throw new ArchiveError("E_ARCHIVE_PATH_TRAVERSAL_DETECTED", `Path traversal blocked: '${filePath}' resolves outside storage root`, { hint: "Keys are relative to the disk root." });
108
123
  }
109
124
  return full;
110
125
  }
126
+ /**
127
+ * The normalised key (see `keys.ts`), refused when it names a visibility
128
+ * marker.
129
+ *
130
+ * Control characters are refused by the normaliser; that matters here
131
+ * because `\n` is the signing payload separator — a key containing one
132
+ * could otherwise forge `exp`.
133
+ */
134
+ #key(filePath) {
135
+ const key = normalizeKey(filePath);
136
+ // The visibility markers live beside the files they describe, so a key
137
+ // naming one would let a caller write, delete or read the marker of
138
+ // another file — `put("secret.pdf.archive-visibility.json", …)` turned a
139
+ // private file public. Refused on every segment (a marker name used as a
140
+ // directory blocks the marker write too) and case-insensitively (the
141
+ // same file on a case-insensitive filesystem).
142
+ for (const segment of key.split("/")) {
143
+ if (segment.toLowerCase().endsWith(VISIBILITY_SIDECAR_SUFFIX)) {
144
+ throw new ArchiveError("E_ARCHIVE_INVALID_KEY", `Invalid key '${filePath}': names ending in '${VISIBILITY_SIDECAR_SUFFIX}' are reserved for visibility markers`, { hint: "Store the object under a name without that suffix." });
145
+ }
146
+ }
147
+ return key;
148
+ }
111
149
  /**
112
150
  * Resolve and validate a file path — prevents traversal outside
113
151
  * the root, INCLUDING via symlinks planted inside the root.
@@ -127,12 +165,12 @@ export class LocalDriver {
127
165
  const realProbe = await fsp.realpath(probe);
128
166
  if (!realProbe.startsWith(this.#root + path.sep) &&
129
167
  realProbe !== this.#root) {
130
- throw new Error(`Path traversal blocked: '${filePath}' resolves outside storage root via symlink`);
168
+ throw new ArchiveError("E_ARCHIVE_PATH_TRAVERSAL_DETECTED", `Path traversal blocked: '${filePath}' resolves outside storage root via symlink`, { hint: "A link inside the disk root points outside it." });
131
169
  }
132
170
  return full;
133
171
  }
134
172
  catch (err) {
135
- if (err.code !== "ENOENT")
173
+ if (errnoCode(err) !== "ENOENT")
136
174
  throw err;
137
175
  const parent = path.dirname(probe);
138
176
  // The root itself is canonicalised at construction, so the walk
@@ -154,21 +192,89 @@ export class LocalDriver {
154
192
  // by name follows it — the check passed on one object and the write
155
193
  // landed on another. Refusing to follow a link at open time takes the
156
194
  // swap off the table: the open fails instead of writing outside the root.
157
- const handle = await fsp.open(full, fs.constants.O_WRONLY |
195
+ //
196
+ // Only `visibility` has a filesystem-equivalent (the marker);
197
+ // contentType/cacheControl/... have no local meaning.
198
+ await this.#writeMarked(full, options?.visibility, async () => {
199
+ const handle = await fsp.open(full, fs.constants.O_WRONLY |
200
+ fs.constants.O_CREAT |
201
+ fs.constants.O_TRUNC |
202
+ O_NOFOLLOW, 0o666);
203
+ try {
204
+ await handle.writeFile(content);
205
+ }
206
+ finally {
207
+ await handle.close();
208
+ }
209
+ });
210
+ }
211
+ /**
212
+ * Run `write`, which puts data at `full`, and leave the object with
213
+ * `visibility` — without it ever being readable as public while it should
214
+ * not be.
215
+ *
216
+ * The marker is a second file, and its absence means public. A PRIVATE
217
+ * marker therefore goes down BEFORE the data: written after, the object
218
+ * was public for the whole write — served unsigned by the signed route and
219
+ * by a static server over the disk — and stayed public for good when the
220
+ * marker write failed. If the data write then fails, the half-written
221
+ * object is removed, and its marker only once the data is gone: the object
222
+ * ends private or absent, never public.
223
+ *
224
+ * A PUBLIC marker goes down AFTER the data, for the same reason the other
225
+ * way round: the bytes being replaced may be private, and they keep their
226
+ * marker until the new ones have landed.
227
+ */
228
+ async #writeMarked(full, visibility, write) {
229
+ if (visibility !== "private") {
230
+ await write();
231
+ if (visibility !== undefined)
232
+ await this.#writeMarker(full, visibility);
233
+ return;
234
+ }
235
+ await this.#markPrivate(full);
236
+ try {
237
+ await write();
238
+ }
239
+ catch (err) {
240
+ await discardPrivate(full);
241
+ throw err;
242
+ }
243
+ }
244
+ /**
245
+ * Mark `full` private before its data is touched. A marker write that
246
+ * fails puts the previous marker back (or leaves a damaged one, which
247
+ * reads as undetermined and is served to nobody), and rethrows: the
248
+ * caller writes no data.
249
+ */
250
+ async #markPrivate(full) {
251
+ const previous = await markerSnapshot(full);
252
+ try {
253
+ await this.#writeMarker(full, "private");
254
+ }
255
+ catch (err) {
256
+ await restoreMarker(full, previous);
257
+ throw err;
258
+ }
259
+ return previous;
260
+ }
261
+ /**
262
+ * Write the visibility marker of the file at `full`, a path `#safePath`
263
+ * already resolved. Through an O_NOFOLLOW descriptor, as the data is: a
264
+ * link planted at the marker's name is refused rather than followed to
265
+ * write outside the root.
266
+ */
267
+ async #writeMarker(full, visibility) {
268
+ const handle = await fsp.open(full + VISIBILITY_SIDECAR_SUFFIX, fs.constants.O_WRONLY |
158
269
  fs.constants.O_CREAT |
159
270
  fs.constants.O_TRUNC |
160
271
  O_NOFOLLOW, 0o666);
161
272
  try {
162
- await handle.writeFile(content);
273
+ await handle.writeFile(JSON.stringify({ visibility }));
163
274
  }
164
275
  finally {
165
276
  await handle.close();
166
277
  }
167
- // Only `visibility` has a filesystem-equivalent (the sidecar).
168
- // contentType/cacheControl/... have no local meaning.
169
- if (options?.visibility !== undefined) {
170
- await this.setVisibility(filePath, options.visibility);
171
- }
172
278
  }
173
279
  async getBytes(filePath) {
174
280
  const buf = await this.get(filePath);
@@ -209,7 +315,7 @@ export class LocalDriver {
209
315
  catch (err) {
210
316
  // One syscall instead of exists-then-read: the pair also answered
211
317
  // `null` for a file that was deleted between the two.
212
- if (err.code === "ENOENT")
318
+ if (errnoCode(err) === "ENOENT")
213
319
  return null;
214
320
  throw err;
215
321
  }
@@ -225,7 +331,7 @@ export class LocalDriver {
225
331
  handle = await fsp.open(full, fs.constants.O_RDONLY | O_NOFOLLOW);
226
332
  }
227
333
  catch (err) {
228
- if (err.code === "ENOENT") {
334
+ if (errnoCode(err) === "ENOENT") {
229
335
  throw new ArchiveError("E_ARCHIVE_NOT_FOUND", `File does not exist at path '${filePath}'`, { hint: "Confirm the path and that the file was put() first." });
230
336
  }
231
337
  throw err;
@@ -239,7 +345,7 @@ export class LocalDriver {
239
345
  await fsp.unlink(full);
240
346
  }
241
347
  catch (err) {
242
- if (err.code === "ENOENT")
348
+ if (errnoCode(err) === "ENOENT")
243
349
  return false;
244
350
  throw err;
245
351
  }
@@ -257,10 +363,7 @@ export class LocalDriver {
257
363
  return true;
258
364
  }
259
365
  async exists(filePath) {
260
- // Sidecars are an implementation detail — pretend they don't
261
- // exist from the public API's point of view.
262
- if (filePath.endsWith(VISIBILITY_SIDECAR_SUFFIX))
263
- return false;
366
+ // A marker name is refused by the path guard, as by every other method.
264
367
  return exists(await this.#safePath(filePath));
265
368
  }
266
369
  publicUrl(filePath) {
@@ -268,11 +371,19 @@ export class LocalDriver {
268
371
  // survive the trip through an HTTP layer. The middleware mirrors
269
372
  // this by decoding each segment before recomputing the HMAC —
270
373
  // skipping encoding here would leave the URL unparseable.
271
- const encoded = filePath
374
+ const encoded = this.#key(filePath)
272
375
  .split("/")
273
376
  .map((seg) => encodeURIComponent(seg))
274
377
  .join("/");
275
- return `/storage/${encoded}`;
378
+ return `${this.#routeBasePath}/${encoded}`;
379
+ }
380
+ /**
381
+ * The URL path this driver's files are served under. The signed route
382
+ * reads it, so the URLs this driver builds and the route that serves them
383
+ * derive from one value.
384
+ */
385
+ getRouteBasePath() {
386
+ return this.#routeBasePath;
276
387
  }
277
388
  async url(filePath) {
278
389
  const visibility = await this.#readVisibility(filePath);
@@ -287,7 +398,7 @@ export class LocalDriver {
287
398
  stat = await fsp.stat(full);
288
399
  }
289
400
  catch (err) {
290
- if (err.code === "ENOENT") {
401
+ if (errnoCode(err) === "ENOENT") {
291
402
  throw new ArchiveError("E_ARCHIVE_NOT_FOUND", `File does not exist at path '${filePath}'`, { hint: "Confirm the path and that the file was put() first." });
292
403
  }
293
404
  throw err;
@@ -318,8 +429,7 @@ export class LocalDriver {
318
429
  if (!(await exists(full))) {
319
430
  throw new ArchiveError("E_ARCHIVE_NOT_FOUND", `Cannot set visibility — file does not exist at path '${filePath}'`, { hint: "put() the file before calling setVisibility()." });
320
431
  }
321
- const sidecar = full + VISIBILITY_SIDECAR_SUFFIX;
322
- await fsp.writeFile(sidecar, JSON.stringify({ visibility }), { flag: "w" });
432
+ await this.#writeMarker(full, visibility);
323
433
  }
324
434
  /**
325
435
  * Read the sidecar marker.
@@ -339,9 +449,9 @@ export class LocalDriver {
339
449
  catch (err) {
340
450
  // Absent sidecar is the documented default, and it is the common
341
451
  // case: one syscall answers both that and a real read failure.
342
- if (err.code === "ENOENT")
452
+ if (errnoCode(err) === "ENOENT")
343
453
  return "public";
344
- throw new ArchiveError("E_ARCHIVE_VISIBILITY_CORRUPT", `Failed to read visibility sidecar for '${filePath}' (${err.code ?? "I/O error"}); refusing to default to 'public'.`, {
454
+ throw new ArchiveError("E_ARCHIVE_VISIBILITY_CORRUPT", `Failed to read visibility sidecar for '${filePath}' (${errnoCode(err) ?? "I/O error"}); refusing to default to 'public'.`, {
345
455
  hint: "Inspect the sidecar file or re-apply visibility via setVisibility().",
346
456
  });
347
457
  }
@@ -362,10 +472,13 @@ export class LocalDriver {
362
472
  // handed out `/storage/<path>` instead of a signed URL. The doc comment
363
473
  // above already promised this for unparseable JSON; a JSON document
364
474
  // that parses and says nothing usable is the same situation.
365
- if (parsed.visibility === "private" || parsed.visibility === "public") {
366
- return parsed.visibility;
475
+ const visibility = typeof parsed === "object" && parsed !== null && "visibility" in parsed
476
+ ? parsed.visibility
477
+ : undefined;
478
+ if (visibility === "private" || visibility === "public") {
479
+ return visibility;
367
480
  }
368
- throw new ArchiveError("E_ARCHIVE_VISIBILITY_CORRUPT", `Sidecar for '${filePath}' carries no usable visibility (${JSON.stringify(parsed.visibility)}); refusing to default to 'public'.`, {
481
+ throw new ArchiveError("E_ARCHIVE_VISIBILITY_CORRUPT", `Sidecar for '${filePath}' carries no usable visibility (${JSON.stringify(visibility)}); refusing to default to 'public'.`, {
369
482
  hint: "Delete the sidecar file and re-apply visibility via setVisibility().",
370
483
  });
371
484
  }
@@ -379,8 +492,10 @@ export class LocalDriver {
379
492
  // signing a URL reads no file — the read it leads to goes through the
380
493
  // full check. What must NOT be skipped here is the control-character
381
494
  // rejection, since `\n` is this signature's own payload separator, and
382
- // `#lexicalPath` is where that lives.
495
+ // `#lexicalPath` is where that lives. What is signed is the
496
+ // normalised key, which is what the route recomputes it over.
383
497
  this.#lexicalPath(filePath);
498
+ const key = this.#key(filePath);
384
499
  const expiresIn = parseExpiry(options?.expiresIn ?? DEFAULT_EXPIRES_IN);
385
500
  assertValidExpiry(expiresIn);
386
501
  const secret = this.#signingSecret;
@@ -393,9 +508,13 @@ export class LocalDriver {
393
508
  // Newline-delimited payload: a filePath cannot forge `exp` by
394
509
  // embedding `&exp=...` in its own bytes (URL-decoding still
395
510
  // keeps the literal `\n` separator in the signed material).
396
- const message = `${filePath}\n${exp}`;
511
+ // Response-header overrides are signed with the rest and carried in the
512
+ // query, where the signed route reads, verifies and emits them.
513
+ const overrides = requestedOverrides(options ?? {});
514
+ const message = signedPayload(key, exp, overrides);
397
515
  const sig = createHmac("sha256", secret).update(message).digest("hex");
398
- return `${this.publicUrl(filePath)}?exp=${exp}&sig=${sig}`;
516
+ const url = `${this.publicUrl(key)}?exp=${exp}&sig=${sig}`;
517
+ return overrides.length === 0 ? url : `${url}&${overrideQuery(overrides)}`;
399
518
  }
400
519
  /**
401
520
  * The LocalDriver serves uploads through the app (not a presigned
@@ -421,12 +540,10 @@ export class LocalDriver {
421
540
  throw new ArchiveError("E_ARCHIVE_NOT_FOUND", `Cannot copy — source does not exist at path '${from}'`, { hint: "Confirm the source path was put() first." });
422
541
  }
423
542
  await fsp.mkdir(path.dirname(toFull), { recursive: true });
424
- await fsp.copyFile(fromFull, toFull);
425
543
  // Intentionally do NOT copy the visibility sidecar — new object
426
- // takes default visibility unless the caller asks otherwise.
427
- if (options?.visibility !== undefined) {
428
- await this.setVisibility(to, options.visibility);
429
- }
544
+ // takes default visibility unless the caller asks otherwise. A private
545
+ // one is marked before the bytes are copied, as put() does.
546
+ await this.#writeMarked(toFull, options?.visibility, () => fsp.copyFile(fromFull, toFull));
430
547
  }
431
548
  async move(from, to, options) {
432
549
  const fromFull = await this.#safePath(from);
@@ -440,37 +557,51 @@ export class LocalDriver {
440
557
  // silently downgrade private→public. `#readVisibility` throws on
441
558
  // corruption, which surfaces here BEFORE we mutate anything.
442
559
  const fromSidecar = fromFull + VISIBILITY_SIDECAR_SUFFIX;
443
- const toSidecar = toFull + VISIBILITY_SIDECAR_SUFFIX;
444
560
  const capturedVisibility = (await exists(fromSidecar))
445
561
  ? await this.#readVisibility(from)
446
562
  : undefined;
563
+ // An explicit visibility override wins over the preserved value.
564
+ const target = options?.visibility ?? capturedVisibility;
447
565
  await fsp.mkdir(path.dirname(toFull), { recursive: true });
566
+ // A private target is marked BEFORE the file arrives: renamed first, the
567
+ // moved private file sat at the target with no marker — public — until
568
+ // the second write, and for good when that write failed.
569
+ const previous = target === "private" ? await this.#markPrivate(toFull) : undefined;
448
570
  try {
449
571
  await fsp.rename(fromFull, toFull);
450
572
  }
451
573
  catch (err) {
452
- // Cross-device rename — fall back to copy+unlink.
453
- if (err.code === "EXDEV") {
574
+ if (errnoCode(err) !== "EXDEV") {
575
+ // Nothing moved: the target is what it was, so is its marker.
576
+ if (previous !== undefined)
577
+ await restoreMarker(toFull, previous);
578
+ throw err;
579
+ }
580
+ // Cross-device rename — fall back to copy+unlink. A half-copied
581
+ // target is removed, and its marker only once the data is gone.
582
+ try {
454
583
  await fsp.copyFile(fromFull, toFull);
455
- await fsp.unlink(fromFull);
456
584
  }
457
- else {
458
- throw err;
585
+ catch (copyErr) {
586
+ await discardPrivate(toFull);
587
+ throw copyErr;
459
588
  }
589
+ await fsp.unlink(fromFull);
460
590
  }
461
- // Visibility carries forward by re-writing the new sidecar from
462
- // captured data — atomic relative to the rename, immune to the
463
- // EXDEV/perm failure modes that plagued the rename-the-sidecar path.
464
- // Public is the default, so an absent source sidecar means no work.
465
- if (capturedVisibility !== undefined) {
591
+ // A public target is marked AFTER the move: until then, whatever was at
592
+ // the target keeps its own marker. Public is the default, so an absent
593
+ // source sidecar and no override mean no work.
594
+ if (target === "public") {
466
595
  try {
467
- await fsp.writeFile(toSidecar, JSON.stringify({ visibility: capturedVisibility }), { flag: "w" });
596
+ await this.#writeMarker(toFull, target);
468
597
  }
469
598
  catch (err) {
470
- throw new ArchiveError("E_ARCHIVE_VISIBILITY_MOVE_FAILED", `move('${from}' -> '${to}'): main file moved but visibility sidecar write failed (${err.code ?? "unknown"}). Target visibility is undefined.`, {
599
+ throw new ArchiveError("E_ARCHIVE_VISIBILITY_MOVE_FAILED", `move('${from}' -> '${to}'): main file moved but visibility sidecar write failed (${errnoCode(err) ?? "unknown"}). Target visibility is undefined.`, {
471
600
  hint: "Re-apply visibility via setVisibility() on the target path.",
472
601
  });
473
602
  }
603
+ }
604
+ if (capturedVisibility !== undefined) {
474
605
  // Best-effort cleanup of the source sidecar — visibility is already
475
606
  // preserved on the target side. A failure here leaves a stale
476
607
  // sidecar pointing at the now-missing source file; benign.
@@ -481,16 +612,13 @@ export class LocalDriver {
481
612
  // benign — source dir may be cleaned up by later operations.
482
613
  }
483
614
  }
484
- // An explicit visibility override wins over the preserved value.
485
- if (options?.visibility !== undefined) {
486
- await this.setVisibility(to, options.visibility);
487
- }
488
615
  }
489
616
  async deleteAll(prefix) {
490
617
  // Walk the existing listing (already sidecar-aware + safe) and
491
618
  // remove every match. delete() also drops each file's sidecar.
619
+ const normalized = normalizePrefix(prefix);
492
620
  const paths = [];
493
- for await (const entry of this.list(prefix)) {
621
+ for await (const entry of this.list(normalized)) {
494
622
  paths.push(entry.path);
495
623
  }
496
624
  for (const p of paths) {
@@ -498,8 +626,8 @@ export class LocalDriver {
498
626
  }
499
627
  // Prune the prefix directory itself when it is now empty, mirroring
500
628
  // flydrive's "the folder is deleted" behaviour. Best-effort.
501
- const dir = await this.#safePath(prefix);
502
- if (dir !== this.#root) {
629
+ if (normalized !== "") {
630
+ const dir = await this.#safePath(normalized);
503
631
  try {
504
632
  const stat = await fsp.stat(dir);
505
633
  if (stat.isDirectory() && (await fsp.readdir(dir)).length === 0) {
@@ -515,11 +643,8 @@ export class LocalDriver {
515
643
  const recursive = options?.recursive ?? false;
516
644
  const files = [];
517
645
  const directories = new Map();
518
- const normalizedPrefix = prefix === "" || prefix === "/"
519
- ? ""
520
- : prefix.endsWith("/")
521
- ? prefix
522
- : `${prefix}/`;
646
+ const given = normalizePrefix(prefix);
647
+ const normalizedPrefix = given === "" || given.endsWith("/") ? given : `${given}/`;
523
648
  for await (const entry of this.list(normalizedPrefix)) {
524
649
  if (recursive) {
525
650
  files.push(new DriveFile(entry.path, this, await this.#entryMetadata(entry)));
@@ -539,6 +664,9 @@ export class LocalDriver {
539
664
  }
540
665
  }
541
666
  }
667
+ // Sorted by key, as upstream lists: the walk's order is the
668
+ // filesystem's, which differs between machines.
669
+ files.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
542
670
  return { objects: [...directories.values(), ...files] };
543
671
  }
544
672
  /** Build a metadata snapshot from a cheap `list()` entry (no extra stat). */
@@ -554,34 +682,36 @@ export class LocalDriver {
554
682
  visibility: await this.#readVisibility(entry.path),
555
683
  };
556
684
  }
557
- async *list(prefix) {
558
- // `recursive: true` gives us every descendant in one call;
559
- // `withFileTypes: true` lets us skip directories and inspect each
560
- // entry without a follow-up stat for type.
561
- let entries;
685
+ async *list(given) {
686
+ const prefix = normalizePrefix(given);
687
+ // Start the walk at the deepest directory the prefix names, not at the
688
+ // root: `avatars/42/` reads `avatars/42`, `avatars/4` reads
689
+ // `avatars`. Walking the whole root and filtering afterwards cost the
690
+ // size of the entire disk for every listing, however narrow.
691
+ const slash = prefix.lastIndexOf("/");
692
+ const dir = slash === -1 ? "" : prefix.slice(0, slash);
693
+ const start = dir === "" ? this.#root : await this.#safePath(dir);
694
+ let walk;
562
695
  try {
563
- entries = await fsp.readdir(this.#root, {
564
- recursive: true,
565
- withFileTypes: true,
566
- });
696
+ // Read lazily: entries arrive as the walk reaches them instead of
697
+ // the whole subtree being held in memory first. Links are listed,
698
+ // not followed, so the walk stays inside the root.
699
+ walk = await fsp.opendir(start, { recursive: true });
567
700
  }
568
701
  catch (err) {
569
- if (err.code === "ENOENT")
702
+ const code = errnoCode(err);
703
+ // Nothing stored under that prefix, or it names a file.
704
+ if (code === "ENOENT" || code === "ENOTDIR")
570
705
  return;
571
706
  throw err;
572
707
  }
573
- for (const entry of entries) {
708
+ for await (const entry of walk) {
574
709
  if (!entry.isFile())
575
710
  continue;
576
- // `parentPath` is typed on Dirent since Node 20.12, which the engine
577
- // range already requires — the double cast that used to read it
578
- // (and its `path` fallback for older shapes) is no longer buying
579
- // anything.
580
- const parent = entry.parentPath ?? this.#root;
581
- const full = path.join(parent, entry.name);
711
+ const full = path.join(entry.parentPath, entry.name);
582
712
  const rel = path.relative(this.#root, full).split(path.sep).join("/");
583
713
  // Exclude sidecars — implementation detail.
584
- if (rel.endsWith(VISIBILITY_SIDECAR_SUFFIX))
714
+ if (rel.toLowerCase().endsWith(VISIBILITY_SIDECAR_SUFFIX))
585
715
  continue;
586
716
  if (!rel.startsWith(prefix))
587
717
  continue;
@@ -590,6 +720,68 @@ export class LocalDriver {
590
720
  }
591
721
  }
592
722
  }
723
+ /** The marker of the file at `full` as it is now. */
724
+ async function markerSnapshot(full) {
725
+ try {
726
+ const handle = await fsp.open(full + VISIBILITY_SIDECAR_SUFFIX, fs.constants.O_RDONLY | O_NOFOLLOW);
727
+ try {
728
+ return { state: "present", bytes: await handle.readFile() };
729
+ }
730
+ finally {
731
+ await handle.close();
732
+ }
733
+ }
734
+ catch (err) {
735
+ return errnoCode(err) === "ENOENT"
736
+ ? { state: "absent" }
737
+ : { state: "unknown" };
738
+ }
739
+ }
740
+ /**
741
+ * Put back the marker `snapshot` recorded. Best-effort, never throws: it runs
742
+ * on a path that is already failing, and a restore that fails leaves the
743
+ * private marker (or a damaged one, read as undetermined) — closed either way.
744
+ */
745
+ async function restoreMarker(full, snapshot) {
746
+ const marker = full + VISIBILITY_SIDECAR_SUFFIX;
747
+ try {
748
+ if (snapshot.state === "absent") {
749
+ await fsp.unlink(marker);
750
+ }
751
+ else if (snapshot.state === "present") {
752
+ const handle = await fsp.open(marker, fs.constants.O_WRONLY | fs.constants.O_TRUNC | O_NOFOLLOW);
753
+ try {
754
+ await handle.writeFile(snapshot.bytes);
755
+ }
756
+ finally {
757
+ await handle.close();
758
+ }
759
+ }
760
+ }
761
+ catch {
762
+ // Closed either way — see above.
763
+ }
764
+ }
765
+ /**
766
+ * Remove a private object whose data write failed half-way: the data first,
767
+ * then its marker — only once the data is gone, so the bytes are never left
768
+ * without the marker that keeps them private. Never throws.
769
+ */
770
+ async function discardPrivate(full) {
771
+ try {
772
+ await fsp.unlink(full);
773
+ }
774
+ catch (err) {
775
+ if (errnoCode(err) !== "ENOENT")
776
+ return;
777
+ }
778
+ try {
779
+ await fsp.unlink(full + VISIBILITY_SIDECAR_SUFFIX);
780
+ }
781
+ catch {
782
+ // An orphan marker serves nothing.
783
+ }
784
+ }
593
785
  /**
594
786
  * Whether a path exists, without `existsSync` blocking the event loop.
595
787
  *
@@ -610,13 +802,17 @@ async function exists(target) {
610
802
  function localPath(source) {
611
803
  return source instanceof URL ? url.fileURLToPath(source) : source;
612
804
  }
805
+ /**
806
+ * The disk an application talks to: one driver behind it, and every key
807
+ * normalised (see `keys.ts`) before that driver sees it, whatever the driver.
808
+ */
613
809
  export class StorageManager {
614
810
  #driver;
615
811
  constructor(driver) {
616
812
  this.#driver = driver;
617
813
  }
618
- put(filePath, content, options) {
619
- return this.#driver.put(filePath, content, options);
814
+ async put(filePath, content, options) {
815
+ return this.#driver.put(normalizeKey(filePath), content, options);
620
816
  }
621
817
  /**
622
818
  * A handle on one object, without reading it (flydrive `file`).
@@ -655,9 +851,12 @@ export class StorageManager {
655
851
  * and cannot see the local path at all when the disk is remote.
656
852
  */
657
853
  async copyFromFs(source, destination, options) {
854
+ // Before the source is opened: a destination that is not a valid key
855
+ // is refused without a descriptor to clean up.
856
+ const key = normalizeKey(destination);
658
857
  const stream = fs.createReadStream(localPath(source));
659
858
  try {
660
- await this.#driver.putStream(destination, stream, options);
859
+ await this.#driver.putStream(key, stream, options);
661
860
  }
662
861
  catch (error) {
663
862
  // The driver can reject BEFORE reading a byte — a destination outside
@@ -686,73 +885,75 @@ export class StorageManager {
686
885
  await this.copyFromFs(from, destination, options);
687
886
  await fs.promises.unlink(from);
688
887
  }
689
- putStream(filePath, readable, options) {
690
- return this.#driver.putStream(filePath, readable, options);
888
+ async putStream(filePath, readable, options) {
889
+ return this.#driver.putStream(normalizeKey(filePath), readable, options);
691
890
  }
692
- get(filePath) {
693
- return this.#driver.get(filePath);
891
+ async get(filePath) {
892
+ return this.#driver.get(normalizeKey(filePath));
694
893
  }
695
894
  /** Contents as a `Uint8Array`. Throws `E_ARCHIVE_NOT_FOUND` if absent. */
696
- getBytes(filePath) {
697
- return this.#driver.getBytes(filePath);
895
+ async getBytes(filePath) {
896
+ return this.#driver.getBytes(normalizeKey(filePath));
698
897
  }
699
898
  /** @deprecated AdonisJS Drive alias — use {@link StorageManager.getBytes}. */
700
- getArrayBuffer(filePath) {
701
- return this.#driver.getBytes(filePath);
899
+ async getArrayBuffer(filePath) {
900
+ return this.#driver.getBytes(normalizeKey(filePath));
702
901
  }
703
- getStream(filePath) {
704
- return this.#driver.getStream(filePath);
902
+ async getStream(filePath) {
903
+ return this.#driver.getStream(normalizeKey(filePath));
705
904
  }
706
- delete(filePath) {
707
- return this.#driver.delete(filePath);
905
+ async delete(filePath) {
906
+ return this.#driver.delete(normalizeKey(filePath));
708
907
  }
709
- exists(filePath) {
710
- return this.#driver.exists(filePath);
908
+ async exists(filePath) {
909
+ return this.#driver.exists(normalizeKey(filePath));
711
910
  }
712
- url(filePath) {
713
- return this.#driver.url(filePath);
911
+ async url(filePath) {
912
+ return this.#driver.url(normalizeKey(filePath));
714
913
  }
715
914
  /** AdonisJS Drive name for {@link url}. */
716
- getUrl(filePath) {
717
- return this.#driver.url(filePath);
915
+ async getUrl(filePath) {
916
+ return this.#driver.url(normalizeKey(filePath));
718
917
  }
719
918
  publicUrl(filePath) {
720
- return this.#driver.publicUrl(filePath);
919
+ return this.#driver.publicUrl(normalizeKey(filePath));
721
920
  }
722
921
  getSignedUrl(filePath, options) {
723
- return this.#driver.getSignedUrl(filePath, options);
922
+ return this.#driver.getSignedUrl(normalizeKey(filePath), options);
724
923
  }
725
924
  getSignedUploadUrl(filePath, options) {
726
- return this.#driver.getSignedUploadUrl(filePath, options);
925
+ return this.#driver.getSignedUploadUrl(normalizeKey(filePath), options);
727
926
  }
728
- getMetadata(filePath) {
729
- return this.#driver.getMetadata(filePath);
927
+ async getMetadata(filePath) {
928
+ return this.#driver.getMetadata(normalizeKey(filePath));
730
929
  }
731
930
  /** AdonisJS Drive casing for {@link getMetadata}. */
732
- getMetaData(filePath) {
733
- return this.#driver.getMetadata(filePath);
931
+ async getMetaData(filePath) {
932
+ return this.#driver.getMetadata(normalizeKey(filePath));
734
933
  }
735
- getVisibility(filePath) {
736
- return this.#driver.getVisibility(filePath);
934
+ async getVisibility(filePath) {
935
+ return this.#driver.getVisibility(normalizeKey(filePath));
737
936
  }
738
- setVisibility(filePath, visibility) {
739
- return this.#driver.setVisibility(filePath, visibility);
937
+ async setVisibility(filePath, visibility) {
938
+ return this.#driver.setVisibility(normalizeKey(filePath), visibility);
740
939
  }
741
- copy(from, to, options) {
742
- return this.#driver.copy(from, to, options);
940
+ async copy(from, to, options) {
941
+ return this.#driver.copy(normalizeKey(from), normalizeKey(to), options);
743
942
  }
744
- move(from, to, options) {
745
- return this.#driver.move(from, to, options);
943
+ async move(from, to, options) {
944
+ return this.#driver.move(normalizeKey(from), normalizeKey(to), options);
746
945
  }
747
- deleteAll(prefix) {
748
- return this.#driver.deleteAll(prefix);
946
+ async deleteAll(prefix) {
947
+ return this.#driver.deleteAll(normalizePrefix(prefix));
749
948
  }
750
949
  list(prefix) {
751
- return this.#driver.list(prefix);
950
+ // Validated now, not on the first iteration: a refused prefix is the
951
+ // caller's mistake and should surface where the call was made.
952
+ return this.#driver.list(normalizePrefix(prefix));
752
953
  }
753
954
  /** AdonisJS Drive `listAll` — paged {@link DriveFile}/{@link DriveDirectory}. */
754
- listAll(prefix, options) {
755
- return this.#driver.listAll(prefix, options);
955
+ async listAll(prefix, options) {
956
+ return this.#driver.listAll(normalizePrefix(prefix), options);
756
957
  }
757
958
  }
758
959
  //# sourceMappingURL=StorageManager.js.map