@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.

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.