@nage-api/storage 1.0.0-beta.2

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,116 @@
+# @nage-api/storage
+
+Uploads, validation and a pluggable CDN (PLAN.md §8, §12, §25 P1).
+
+The package exists mostly to make three attacks unavailable by construction: a
+mislabelled file a browser later executes, a filename that escapes the storage
+root, and a "fetch this URL for me" feature that reaches the cloud metadata
+endpoint.
+
+<!-- docs-example: fragment -->
+
+```ts
+import { StorageService } from '@nage-api/storage';
+
+// Exported by `NageStorageModule.forRoot`, so injecting the class is enough.
+declare const storage: StorageService;
+// Whatever the upload middleware hands the handler. No interceptor ships with
+// this package, so the three untrusted fields arrive under whichever names it
+// uses; these are multer's.
+declare const file: { originalname: string; buffer: Buffer; mimetype: string };
+
+const stored = await storage.upload({
+  filename: file.originalname, // untrusted
+  content: file.buffer,
+  contentType: file.mimetype, // also untrusted
+  directory: 'avatars',
+});
+// → { key: 'avatars/k3f9x2-my-photo.png', contentType: 'image/png', checksum, url }
+```
+
+Every write goes through the same three steps in the same order — validate the
+bytes, build a safe key, then store. No method skips one, because the single
+call site that skipped validation is where the stored XSS came from.
+
+## The bytes decide, not the client
+
+`Content-Type` is a claim and the extension is a claim; both are
+attacker-controlled. The magic bytes are not. A file that says `image/png` and
+starts with `<?php` is refused, and the **verified** type is what gets stored,
+served back, and used to pick the stored extension — so a `.php` that somehow
+survived every other check is still written as `.png`.
+
+Also refused: empty files, oversized files, denied extensions (including `.svg`,
+which is a script container), and double extensions like `photo.png.php` — which
+a server that dispatches on the last extension it _recognises_ will happily
+execute.
+
+The signature table is short by design. It covers what applications actually
+allow people to upload, and anything outside it fails closed.
+
+## Keys cannot escape
+
+A client-supplied filename reaches a filesystem path, so none of it is used
+directly. The key is a random prefix plus a heavily sanitised stem, drawn from
+`[a-z0-9-_]` by allow-list — sanitising by replacement rather than removal, so
+`a/b` and `ab` do not collapse into the same key.
+
+`assertSafeKey` then runs before every read and delete, and the local driver
+independently resolves the path and checks it is still under the root. Two
+checks, because path traversal is the failure mode where one missed check is a
+compromise.
+
+## Fetching a URL is an SSRF primitive
+
+`uploadFromUrl` is defended in layers, because each layer alone is bypassable:
+
+1. **scheme allow-list** — `https:` only by default;
+2. **DNS resolution before connecting** — a hostname that _resolves_ to a
+   private address is refused. Checking the hostname's text is useless: an
+   attacker owns a public domain pointed at `127.0.0.1`;
+3. **every redirect re-checked** — redirects are followed manually, because a
+   public URL that 302s to `169.254.169.254` defeats a check that ran once;
+4. **size and time limits** — a URL that streams forever is a denial of
+   service, not a download.
+
+Private means loopback, link-local (including the metadata endpoint), the RFC
+1918 ranges, carrier-grade NAT, multicast, and their IPv6 equivalents including
+IPv4-mapped forms. Anything that is not parseable as an address is refused
+rather than guessed at.
+
+Error messages are split: the client sees "That URL is not reachable from
+here", the log gets which hostname resolved to what.
+
+**A residual DNS-rebinding window remains.** Resolution and connection are two
+separate operations, so a name can answer publicly for the check and privately
+for the connection. Closing it needs a custom agent that pins the resolved
+address to the socket; that is not written, and pretending otherwise would be
+worse than saying so.
+
+## Drivers
+
+`local` is built in. `s3` and `azure` are declared in `StorageConfig` and must
+be supplied by the application — their SDKs are large, and neither belongs in
+an install that does not use them. A CDN the module cannot build is refused at
+composition time rather than at the first upload.
+
+`storage.bucket` and `storage.region` are part of `StorageConfig` for such a
+driver to read. This package never reads them, so setting them without passing a
+`driver` changes nothing.
+
+## Not yet implemented
+
+- The S3 and Azure drivers themselves. `StorageDriver` is the seam.
+- The per-field upload decorator §12 asks for. The legacy `@FileUploads`
+  decorator, its interceptor and its exception filter have no replacement here:
+  a route parses its own multipart body and calls `upload` itself.
+- Serving files back in `local` mode. Nothing in the framework mounts a static
+  handler, so `publicBaseUrl` describes a URL you have arranged elsewhere.
+- Wildcard MIME patterns. `validation.mime` is matched exactly, so `image/*`
+  accepts nothing rather than every image.
+- The optional anti-virus hook §12 mentions.
+- Streaming uploads; `UploadInput.content` is a `Buffer`, so a very large file
+  is held in memory.
+- Image processing (resize, strip EXIF). Stripping metadata before serving a
+  user-supplied image is a privacy measure worth having.
+- Signed URLs are on the port and unimplemented by the local driver.

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@nage-api/storage` — uploads, validation and a pluggable CDN (PLAN.md §8, §12,
+ * §25 P1).
+ *
+ * The package exists mostly to make three attacks unavailable by construction:
+ * a mislabelled file that a browser later executes, a filename that escapes the
+ * storage root, and a "fetch this URL" feature that reaches the cloud metadata
+ * endpoint.
+ */
+export type * from '@nage-api/contracts';
+export { NageStorageModule, parseSize, type NageStorageModuleOptions } from './storage.module.js';
+export { StorageService, type StorageServiceOptions } from './storage.service.js';
+export { LocalStorageDriver, type LocalStorageDriverOptions } from './local.driver.js';
+export { RemoteFetcher, isPrivateAddress, type FetchedFile, type RemoteFetchOptions, } from './remote-fetch.js';
+export { DEFAULT_ALLOWED_MIME_TYPES, DEFAULT_DENIED_EXTENSIONS, DEFAULT_MAX_SIZE_BYTES, MAGIC_SIGNATURES, defaultUploadPolicy, detectMimeType, extensionOf, validateUpload, type MagicSignature, } from './validation.js';
+export { assertSafeKey, buildStorageKey, extensionForMimeType, sanitiseDirectory, sanitiseSegment, type BuildKeyOptions, } from './keys.js';
+export { NAGE_STORAGE, NAGE_STORAGE_DRIVER } from './tokens.js';
+export { systemClock, type Clock, type StorageDriver, type StoredFile, type UploadInput, type UploadPolicy, } from './ports.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * `@nage-api/storage` — uploads, validation and a pluggable CDN (PLAN.md §8, §12,
+ * §25 P1).
+ *
+ * The package exists mostly to make three attacks unavailable by construction:
+ * a mislabelled file that a browser later executes, a filename that escapes the
+ * storage root, and a "fetch this URL" feature that reaches the cloud metadata
+ * endpoint.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemClock = exports.NAGE_STORAGE_DRIVER = exports.NAGE_STORAGE = exports.sanitiseSegment = exports.sanitiseDirectory = exports.extensionForMimeType = exports.buildStorageKey = exports.assertSafeKey = exports.validateUpload = exports.extensionOf = exports.detectMimeType = exports.defaultUploadPolicy = exports.MAGIC_SIGNATURES = exports.DEFAULT_MAX_SIZE_BYTES = exports.DEFAULT_DENIED_EXTENSIONS = exports.DEFAULT_ALLOWED_MIME_TYPES = exports.isPrivateAddress = exports.RemoteFetcher = exports.LocalStorageDriver = exports.StorageService = exports.parseSize = exports.NageStorageModule = void 0;
+var storage_module_js_1 = require("./storage.module.js");
+Object.defineProperty(exports, "NageStorageModule", { enumerable: true, get: function () { return storage_module_js_1.NageStorageModule; } });
+Object.defineProperty(exports, "parseSize", { enumerable: true, get: function () { return storage_module_js_1.parseSize; } });
+var storage_service_js_1 = require("./storage.service.js");
+Object.defineProperty(exports, "StorageService", { enumerable: true, get: function () { return storage_service_js_1.StorageService; } });
+var local_driver_js_1 = require("./local.driver.js");
+Object.defineProperty(exports, "LocalStorageDriver", { enumerable: true, get: function () { return local_driver_js_1.LocalStorageDriver; } });
+var remote_fetch_js_1 = require("./remote-fetch.js");
+Object.defineProperty(exports, "RemoteFetcher", { enumerable: true, get: function () { return remote_fetch_js_1.RemoteFetcher; } });
+Object.defineProperty(exports, "isPrivateAddress", { enumerable: true, get: function () { return remote_fetch_js_1.isPrivateAddress; } });
+var validation_js_1 = require("./validation.js");
+Object.defineProperty(exports, "DEFAULT_ALLOWED_MIME_TYPES", { enumerable: true, get: function () { return validation_js_1.DEFAULT_ALLOWED_MIME_TYPES; } });
+Object.defineProperty(exports, "DEFAULT_DENIED_EXTENSIONS", { enumerable: true, get: function () { return validation_js_1.DEFAULT_DENIED_EXTENSIONS; } });
+Object.defineProperty(exports, "DEFAULT_MAX_SIZE_BYTES", { enumerable: true, get: function () { return validation_js_1.DEFAULT_MAX_SIZE_BYTES; } });
+Object.defineProperty(exports, "MAGIC_SIGNATURES", { enumerable: true, get: function () { return validation_js_1.MAGIC_SIGNATURES; } });
+Object.defineProperty(exports, "defaultUploadPolicy", { enumerable: true, get: function () { return validation_js_1.defaultUploadPolicy; } });
+Object.defineProperty(exports, "detectMimeType", { enumerable: true, get: function () { return validation_js_1.detectMimeType; } });
+Object.defineProperty(exports, "extensionOf", { enumerable: true, get: function () { return validation_js_1.extensionOf; } });
+Object.defineProperty(exports, "validateUpload", { enumerable: true, get: function () { return validation_js_1.validateUpload; } });
+var keys_js_1 = require("./keys.js");
+Object.defineProperty(exports, "assertSafeKey", { enumerable: true, get: function () { return keys_js_1.assertSafeKey; } });
+Object.defineProperty(exports, "buildStorageKey", { enumerable: true, get: function () { return keys_js_1.buildStorageKey; } });
+Object.defineProperty(exports, "extensionForMimeType", { enumerable: true, get: function () { return keys_js_1.extensionForMimeType; } });
+Object.defineProperty(exports, "sanitiseDirectory", { enumerable: true, get: function () { return keys_js_1.sanitiseDirectory; } });
+Object.defineProperty(exports, "sanitiseSegment", { enumerable: true, get: function () { return keys_js_1.sanitiseSegment; } });
+var tokens_js_1 = require("./tokens.js");
+Object.defineProperty(exports, "NAGE_STORAGE", { enumerable: true, get: function () { return tokens_js_1.NAGE_STORAGE; } });
+Object.defineProperty(exports, "NAGE_STORAGE_DRIVER", { enumerable: true, get: function () { return tokens_js_1.NAGE_STORAGE_DRIVER; } });
+var ports_js_1 = require("./ports.js");
+Object.defineProperty(exports, "systemClock", { enumerable: true, get: function () { return ports_js_1.systemClock; } });
+//# sourceMappingURL=index.js.map

package/dist/keys.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Turning a client-supplied filename into a storage key (PLAN.md §12).
+ *
+ * The filename in a multipart upload is attacker-controlled, and it reaches a
+ * filesystem path. `../../etc/cron.d/x`, a null byte, a 4000-character name and
+ * a name that differs from another only by a Unicode homoglyph are all things a
+ * client can send.
+ *
+ * So none of it is used directly: the key is built from a random prefix plus a
+ * heavily sanitised version of the original, and the sanitiser is
+ * allow-list-based — anything outside `[a-z0-9-_]` is replaced rather than
+ * escaped. Escaping is where these bugs live.
+ */
+export interface BuildKeyOptions {
+    readonly filename: string;
+    /** Logical folder, e.g. `avatars`. Sanitised the same way. */
+    readonly directory?: string;
+    /** Extension to force, derived from the **verified** content type. */
+    readonly extension?: string;
+    /** Injected so a test can assert on an exact key. */
+    readonly prefix?: string;
+}
+/**
+ * Build a storage key.
+ *
+ * The result always has the shape `[directory/]<random>-<stem><ext>`, and every
+ * component is drawn from a restricted alphabet, so it cannot escape a prefix
+ * or mean anything to a shell.
+ */
+export declare function buildStorageKey(options: BuildKeyOptions): string;
+/**
+ * Reduce a path segment to `[a-z0-9-_]`.
+ *
+ * Replacement rather than removal, so `a/b` becomes `a-b` rather than `ab` —
+ * two different inputs should not silently become the same key.
+ */
+export declare function sanitiseSegment(segment: string): string;
+/** A directory of up to three sanitised segments, e.g. `avatars/2026/01`. */
+export declare function sanitiseDirectory(directory: string): string;
+/**
+ * Verify a key is one this package could have produced.
+ *
+ * Called before every read and delete, because a key can arrive from a database
+ * row that was written before a validation rule existed, or from a request
+ * parameter.
+ */
+export declare function assertSafeKey(key: string): void;
+/** The conventional extension for a verified MIME type. */
+export declare function extensionForMimeType(mime: string): string;
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Turning a client-supplied filename into a storage key (PLAN.md §12).
+ *
+ * The filename in a multipart upload is attacker-controlled, and it reaches a
+ * filesystem path. `../../etc/cron.d/x`, a null byte, a 4000-character name and
+ * a name that differs from another only by a Unicode homoglyph are all things a
+ * client can send.
+ *
+ * So none of it is used directly: the key is built from a random prefix plus a
+ * heavily sanitised version of the original, and the sanitiser is
+ * allow-list-based — anything outside `[a-z0-9-_]` is replaced rather than
+ * escaped. Escaping is where these bugs live.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildStorageKey = buildStorageKey;
+exports.sanitiseSegment = sanitiseSegment;
+exports.sanitiseDirectory = sanitiseDirectory;
+exports.assertSafeKey = assertSafeKey;
+exports.extensionForMimeType = extensionForMimeType;
+const core_1 = require("@nage-api/core");
+const core_2 = require("@nage-api/core");
+/** Enough entropy that two uploads of the same name never collide. */
+const PREFIX_LENGTH = 12;
+const MAX_STEM_LENGTH = 64;
+const MAX_DIRECTORY_LENGTH = 64;
+/**
+ * Build a storage key.
+ *
+ * The result always has the shape `[directory/]<random>-<stem><ext>`, and every
+ * component is drawn from a restricted alphabet, so it cannot escape a prefix
+ * or mean anything to a shell.
+ */
+function buildStorageKey(options) {
+    const prefix = options.prefix ?? (0, core_1.randomString)(PREFIX_LENGTH).toLowerCase();
+    const stem = sanitiseSegment(stemOf(options.filename)).slice(0, MAX_STEM_LENGTH) || 'file';
+    const extension = normaliseExtension(options.extension ?? extensionOf(options.filename));
+    const directory = options.directory === undefined ? '' : sanitiseDirectory(options.directory);
+    const name = `${prefix}-${stem}${extension}`;
+    return directory === '' ? name : `${directory}/${name}`;
+}
+/**
+ * Reduce a path segment to `[a-z0-9-_]`.
+ *
+ * Replacement rather than removal, so `a/b` becomes `a-b` rather than `ab` —
+ * two different inputs should not silently become the same key.
+ */
+function sanitiseSegment(segment) {
+    return segment
+        .normalize('NFKD')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .replace(/-{2,}/g, '-');
+}
+/** A directory of up to three sanitised segments, e.g. `avatars/2026/01`. */
+function sanitiseDirectory(directory) {
+    const segments = directory
+        .split('/')
+        .map((segment) => sanitiseSegment(segment))
+        .filter((segment) => segment !== '')
+        .slice(0, 3);
+    return segments.join('/').slice(0, MAX_DIRECTORY_LENGTH);
+}
+/**
+ * Verify a key is one this package could have produced.
+ *
+ * Called before every read and delete, because a key can arrive from a database
+ * row that was written before a validation rule existed, or from a request
+ * parameter.
+ */
+function assertSafeKey(key) {
+    const safe = /^[a-z0-9][a-z0-9\-_]*(?:\/[a-z0-9][a-z0-9\-_]*)*(?:\.[a-z0-9]+)?$/;
+    if (key === '' || key.includes('..') || key.includes('\0') || !safe.test(key)) {
+        throw new core_2.ConfigurationError({
+            detail: `"${key}" is not a storage key this package could have produced`,
+            meta: { key },
+        });
+    }
+}
+function stemOf(filename) {
+    const base = filename.split(/[/\\]/).pop() ?? filename;
+    const index = base.lastIndexOf('.');
+    return index <= 0 ? base : base.slice(0, index);
+}
+function extensionOf(filename) {
+    const base = filename.split(/[/\\]/).pop() ?? filename;
+    const index = base.lastIndexOf('.');
+    return index <= 0 ? '' : base.slice(index);
+}
+function normaliseExtension(extension) {
+    const cleaned = extension.toLowerCase().replace(/[^a-z0-9.]/g, '');
+    if (cleaned === '' || cleaned === '.')
+        return '';
+    return cleaned.startsWith('.') ? cleaned : `.${cleaned}`;
+}
+/** The conventional extension for a verified MIME type. */
+function extensionForMimeType(mime) {
+    const table = {
+        'image/jpeg': '.jpg',
+        'image/png': '.png',
+        'image/gif': '.gif',
+        'image/webp': '.webp',
+        'application/pdf': '.pdf',
+        'application/zip': '.zip',
+    };
+    return table[mime] ?? '';
+}
+//# sourceMappingURL=keys.js.map

package/dist/local.driver.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Files on the local disk (PLAN.md §8: `cdn: 'local' | 's3' | 'azure'`).
+ *
+ * The default driver, and the one every development environment uses. Its whole
+ * job beyond `writeFile` is refusing to write outside its own root: every path
+ * is resolved and then checked against the root, because `path.join` will
+ * happily produce `/etc/passwd` from a key that starts with enough `../`.
+ *
+ * Keys are validated before they get here too, so this is the second of two
+ * independent checks. That redundancy is deliberate — path traversal is the
+ * failure mode where one missed check is a compromise.
+ */
+import type { StorageDriver } from './ports.js';
+export interface LocalStorageDriverOptions {
+    /** Directory every file lives under. Created on first write. */
+    readonly root: string;
+    /** Base URL files are served from, when they are served at all. */
+    readonly publicBaseUrl?: string;
+}
+export declare class LocalStorageDriver implements StorageDriver {
+    #private;
+    readonly name = "local";
+    constructor(options: LocalStorageDriverOptions);
+    put(key: string, content: Buffer, _contentType: string): Promise<void>;
+    get(key: string): Promise<Buffer | undefined>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    /** Where a file is served from, when a base URL is configured. */
+    publicUrl(key: string): string | undefined;
+    get root(): string;
+}
+//# sourceMappingURL=local.driver.d.ts.map

package/dist/local.driver.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Files on the local disk (PLAN.md §8: `cdn: 'local' | 's3' | 'azure'`).
+ *
+ * The default driver, and the one every development environment uses. Its whole
+ * job beyond `writeFile` is refusing to write outside its own root: every path
+ * is resolved and then checked against the root, because `path.join` will
+ * happily produce `/etc/passwd` from a key that starts with enough `../`.
+ *
+ * Keys are validated before they get here too, so this is the second of two
+ * independent checks. That redundancy is deliberate — path traversal is the
+ * failure mode where one missed check is a compromise.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalStorageDriver = void 0;
+const promises_1 = require("node:fs/promises");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const core_1 = require("@nage-api/core");
+const keys_js_1 = require("./keys.js");
+class LocalStorageDriver {
+    name = 'local';
+    #root;
+    #publicBaseUrl;
+    constructor(options) {
+        if (options.root.trim() === '') {
+            throw new core_1.ConfigurationError({
+                detail: 'The local storage driver needs a root directory',
+                meta: { setting: 'storage.root' },
+            });
+        }
+        this.#root = (0, node_path_1.resolve)(options.root);
+        this.#publicBaseUrl = options.publicBaseUrl;
+    }
+    async put(key, content, _contentType) {
+        const path = this.#resolve(key);
+        await (0, promises_1.mkdir)((0, node_path_1.dirname)(path), { recursive: true });
+        await (0, promises_1.writeFile)(path, content);
+    }
+    async get(key) {
+        const path = this.#resolve(key);
+        if (!(0, node_fs_1.existsSync)(path))
+            return undefined;
+        return (0, promises_1.readFile)(path);
+    }
+    async delete(key) {
+        await (0, promises_1.rm)(this.#resolve(key), { force: true });
+    }
+    async exists(key) {
+        await Promise.resolve();
+        return (0, node_fs_1.existsSync)(this.#resolve(key));
+    }
+    /** Where a file is served from, when a base URL is configured. */
+    publicUrl(key) {
+        if (this.#publicBaseUrl === undefined)
+            return undefined;
+        (0, keys_js_1.assertSafeKey)(key);
+        return `${this.#publicBaseUrl.replace(/\/$/, '')}/${key}`;
+    }
+    get root() {
+        return this.#root;
+    }
+    /**
+     * Resolve a key under the root, refusing anything that escapes it.
+     *
+     * Both halves matter: `assertSafeKey` rejects the shapes this package never
+     * produces, and the `relative` check catches anything that still resolves
+     * outside — including through a symlinked parent.
+     */
+    #resolve(key) {
+        (0, keys_js_1.assertSafeKey)(key);
+        const path = (0, node_path_1.resolve)((0, node_path_1.join)(this.#root, key));
+        const relation = (0, node_path_1.relative)(this.#root, path);
+        if (relation.startsWith('..') || relation === '') {
+            throw new core_1.ConfigurationError({
+                detail: `"${key}" resolves outside the storage root`,
+                meta: { key },
+            });
+        }
+        return path;
+    }
+}
+exports.LocalStorageDriver = LocalStorageDriver;
+//# sourceMappingURL=local.driver.js.map