@nage-api/storage 1.0.0-beta.2

package/dist/storage.service.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * The storage service application code uses (PLAN.md §8, §12).
+ *
+ * Every write goes through the same three steps in the same order: validate the
+ * bytes, build a safe key, then store. There is no method that skips a step,
+ * because the one call site that skipped validation is where the stored XSS
+ * came from.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageService = void 0;
+const node_crypto_1 = require("node:crypto");
+const core_1 = require("@nage-api/core");
+const keys_js_1 = require("./keys.js");
+const validation_js_1 = require("./validation.js");
+class StorageService {
+    #driver;
+    #policy;
+    #publicBaseUrl;
+    #fetcher;
+    #clock;
+    constructor(options) {
+        this.#driver = options.driver;
+        this.#policy = options.policy ?? (0, validation_js_1.defaultUploadPolicy)();
+        this.#publicBaseUrl = options.publicBaseUrl;
+        this.#fetcher = options.fetcher;
+        this.#clock = options.clock ?? { now: () => Date.now() };
+    }
+    /**
+     * Validate and store an upload.
+     *
+     * The stored extension comes from the **verified** content type, not from the
+     * client's filename — so a `.php` named `image/png` is stored as `.png` even
+     * if every other check somehow passed.
+     */
+    async upload(input) {
+        const contentType = (0, validation_js_1.validateUpload)(input, this.#policy);
+        const key = (0, keys_js_1.buildStorageKey)({
+            filename: input.filename,
+            ...(input.directory === undefined ? {} : { directory: input.directory }),
+            extension: (0, keys_js_1.extensionForMimeType)(contentType),
+        });
+        await this.#driver.put(key, input.content, contentType);
+        const url = this.url(key);
+        return {
+            key,
+            size: input.content.length,
+            contentType,
+            checksum: (0, node_crypto_1.createHash)('sha256').update(input.content).digest('hex'),
+            uploadedAt: this.#clock.now(),
+            ...(url === undefined ? {} : { url }),
+        };
+    }
+    /**
+     * Fetch a URL and store what comes back.
+     *
+     * The fetch is SSRF-checked and the bytes are validated exactly as an upload
+     * is: a file arriving over HTTP is no more trustworthy than one arriving in a
+     * form.
+     */
+    async uploadFromUrl(url, options = {}) {
+        if (this.#fetcher === undefined) {
+            throw new core_1.NotFoundError({
+                detail: 'Fetching from a URL needs a RemoteFetcher; pass one to StorageService',
+            });
+        }
+        const fetched = await this.#fetcher.fetch(url);
+        return this.upload({
+            filename: options.filename ?? filenameFromUrl(fetched.finalUrl),
+            content: fetched.content,
+            ...(fetched.contentType === undefined ? {} : { contentType: fetched.contentType }),
+            ...(options.directory === undefined ? {} : { directory: options.directory }),
+        });
+    }
+    async download(key) {
+        (0, keys_js_1.assertSafeKey)(key);
+        const content = await this.#driver.get(key);
+        if (content === undefined) {
+            throw new core_1.NotFoundError({ detail: `No stored file with key ${key}`, meta: { key } });
+        }
+        return content;
+    }
+    async exists(key) {
+        (0, keys_js_1.assertSafeKey)(key);
+        return this.#driver.exists(key);
+    }
+    async delete(key) {
+        (0, keys_js_1.assertSafeKey)(key);
+        await this.#driver.delete(key);
+    }
+    /** A time-limited URL, when the driver can mint one. */
+    async signedUrl(key, expiresInSeconds = 300) {
+        (0, keys_js_1.assertSafeKey)(key);
+        if (this.#driver.signedUrl === undefined)
+            return undefined;
+        return this.#driver.signedUrl(key, expiresInSeconds);
+    }
+    /** The public URL for a key, when one is configured. */
+    url(key) {
+        if (this.#publicBaseUrl === undefined)
+            return undefined;
+        (0, keys_js_1.assertSafeKey)(key);
+        return `${this.#publicBaseUrl.replace(/\/$/, '')}/${key}`;
+    }
+    get policy() {
+        return this.#policy;
+    }
+}
+exports.StorageService = StorageService;
+/** A best-effort name from a URL; sanitised later regardless. */
+function filenameFromUrl(url) {
+    try {
+        const last = new URL(url).pathname.split('/').pop();
+        return last === undefined || last === '' ? 'download' : last;
+    }
+    catch {
+        return 'download';
+    }
+}
+//# sourceMappingURL=storage.service.js.map

package/dist/tokens.d.ts

@@ -0,0 +1,7 @@
+/** DI tokens for storage (PLAN.md §7.3). */
+import { type Token } from '@nage-api/core';
+import type { StorageDriver } from './ports.js';
+import type { StorageService } from './storage.service.js';
+export declare const NAGE_STORAGE: Token<StorageService>;
+export declare const NAGE_STORAGE_DRIVER: Token<StorageDriver>;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.js

@@ -0,0 +1,8 @@
+"use strict";
+/** DI tokens for storage (PLAN.md §7.3). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAGE_STORAGE_DRIVER = exports.NAGE_STORAGE = void 0;
+const core_1 = require("@nage-api/core");
+exports.NAGE_STORAGE = (0, core_1.createToken)('NAGE_STORAGE');
+exports.NAGE_STORAGE_DRIVER = (0, core_1.createToken)('NAGE_STORAGE_DRIVER');
+//# sourceMappingURL=tokens.js.map

package/dist/validation.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Upload validation (PLAN.md §12).
+ *
+ * Four checks, in the order that costs least first: size, then the shape of the
+ * name, then the extensions, then the bytes themselves.
+ *
+ * The one that matters is the last. A client's `Content-Type` header is a
+ * claim, and the file extension is a claim, and both are attacker-controlled.
+ * The magic bytes are not: a file that says `image/png` and starts with `<?php`
+ * is refused here rather than served back from a CDN later.
+ *
+ * The signature table is deliberately short. It covers the types an application
+ * actually allows people to upload; anything outside it fails closed, which is
+ * the right default for a check whose job is to refuse surprises.
+ */
+import type { UploadInput, UploadPolicy } from './ports.js';
+/** Leading bytes that identify a format, with the offset they appear at. */
+export interface MagicSignature {
+    readonly mime: string;
+    readonly offset: number;
+    readonly bytes: readonly number[];
+    /** Extra bytes that must also match, e.g. `WEBP` inside a RIFF container. */
+    readonly trailer?: {
+        readonly offset: number;
+        readonly bytes: readonly number[];
+    };
+}
+export declare const MAGIC_SIGNATURES: readonly MagicSignature[];
+/** Extensions that are executable somewhere, whatever they claim to be. */
+export declare const DEFAULT_DENIED_EXTENSIONS: readonly string[];
+export declare const DEFAULT_MAX_SIZE_BYTES: number;
+/** A conservative default: images and PDFs, nothing that executes. */
+export declare const DEFAULT_ALLOWED_MIME_TYPES: readonly string[];
+export declare function defaultUploadPolicy(): UploadPolicy;
+/**
+ * Validate an upload, returning the **verified** content type.
+ *
+ * The returned type is what the bytes say, not what the client said, and it is
+ * what gets stored and served back — so a mislabelled file cannot later be
+ * served with a type that makes a browser execute it.
+ *
+ * @throws ValidationError with field-level detail
+ */
+export declare function validateUpload(input: UploadInput, policy: UploadPolicy): string;
+/** The MIME type the bytes say this is, or `undefined` if unrecognised. */
+export declare function detectMimeType(content: Buffer): string | undefined;
+/** Lowercased final extension, including the dot. */
+export declare function extensionOf(filename: string): string;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.js

@@ -0,0 +1,200 @@
+"use strict";
+/**
+ * Upload validation (PLAN.md §12).
+ *
+ * Four checks, in the order that costs least first: size, then the shape of the
+ * name, then the extensions, then the bytes themselves.
+ *
+ * The one that matters is the last. A client's `Content-Type` header is a
+ * claim, and the file extension is a claim, and both are attacker-controlled.
+ * The magic bytes are not: a file that says `image/png` and starts with `<?php`
+ * is refused here rather than served back from a CDN later.
+ *
+ * The signature table is deliberately short. It covers the types an application
+ * actually allows people to upload; anything outside it fails closed, which is
+ * the right default for a check whose job is to refuse surprises.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ALLOWED_MIME_TYPES = exports.DEFAULT_MAX_SIZE_BYTES = exports.DEFAULT_DENIED_EXTENSIONS = exports.MAGIC_SIGNATURES = void 0;
+exports.defaultUploadPolicy = defaultUploadPolicy;
+exports.validateUpload = validateUpload;
+exports.detectMimeType = detectMimeType;
+exports.extensionOf = extensionOf;
+const core_1 = require("@nage-api/core");
+/** ASCII bytes of a signature literal. All of them are ASCII by construction. */
+const ASCII = (text) => Array.from(text, (char) => char.charCodeAt(0));
+exports.MAGIC_SIGNATURES = [
+    { mime: 'image/jpeg', offset: 0, bytes: [0xff, 0xd8, 0xff] },
+    { mime: 'image/png', offset: 0, bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] },
+    { mime: 'image/gif', offset: 0, bytes: ASCII('GIF8') },
+    {
+        mime: 'image/webp',
+        offset: 0,
+        bytes: ASCII('RIFF'),
+        trailer: { offset: 8, bytes: ASCII('WEBP') },
+    },
+    { mime: 'application/pdf', offset: 0, bytes: ASCII('%PDF-') },
+    // Every OOXML document and every .zip share this header; the distinction is
+    // inside the archive, which is more unpacking than a signature check should do.
+    { mime: 'application/zip', offset: 0, bytes: [0x50, 0x4b, 0x03, 0x04] },
+];
+/** Extensions that are executable somewhere, whatever they claim to be. */
+exports.DEFAULT_DENIED_EXTENSIONS = [
+    '.php',
+    '.phtml',
+    '.phar',
+    '.jsp',
+    '.asp',
+    '.aspx',
+    '.cgi',
+    '.pl',
+    '.py',
+    '.rb',
+    '.sh',
+    '.bash',
+    '.exe',
+    '.dll',
+    '.so',
+    '.bat',
+    '.cmd',
+    '.com',
+    '.scr',
+    '.js',
+    '.mjs',
+    '.cjs',
+    '.jar',
+    '.war',
+    '.htaccess',
+    '.htpasswd',
+    '.svg',
+];
+exports.DEFAULT_MAX_SIZE_BYTES = 10 * 1024 * 1024;
+/** A conservative default: images and PDFs, nothing that executes. */
+exports.DEFAULT_ALLOWED_MIME_TYPES = [
+    'image/jpeg',
+    'image/png',
+    'image/gif',
+    'image/webp',
+    'application/pdf',
+];
+function defaultUploadPolicy() {
+    return {
+        maxSizeBytes: exports.DEFAULT_MAX_SIZE_BYTES,
+        allowedMimeTypes: exports.DEFAULT_ALLOWED_MIME_TYPES,
+        verifyMagicBytes: true,
+        deniedExtensions: exports.DEFAULT_DENIED_EXTENSIONS,
+    };
+}
+/**
+ * Validate an upload, returning the **verified** content type.
+ *
+ * The returned type is what the bytes say, not what the client said, and it is
+ * what gets stored and served back — so a mislabelled file cannot later be
+ * served with a type that makes a browser execute it.
+ *
+ * @throws ValidationError with field-level detail
+ */
+function validateUpload(input, policy) {
+    const failures = {};
+    if (input.content.length === 0) {
+        failures['empty'] = 'The file is empty.';
+    }
+    if (input.content.length > policy.maxSizeBytes) {
+        failures['maxSize'] = `Must be ${formatBytes(policy.maxSizeBytes)} or smaller.`;
+    }
+    // RFC 7578 §4.2 makes the multipart `filename` a basename, so a separator or a
+    // null byte in one is refused rather than rewritten. Refusing matters because
+    // the two extension checks below split the name on dots alone: given
+    // `photo.php/avatar.png` they read `.php/avatar`, which no deny-list contains,
+    // and the file is accepted as an image. `buildStorageKey` would neutralise the
+    // same name into a safe key, but that is the second line of defence, and a
+    // caller that validates here and then keys on the client's name — a pre-signed
+    // upload, say — does not get the second line at all.
+    if (input.filename.includes('/') ||
+        input.filename.includes('\\') ||
+        input.filename.includes('\0')) {
+        failures['filename'] = 'The file name must be a name, not a path.';
+    }
+    const extension = extensionOf(input.filename);
+    if (extension !== '' && policy.deniedExtensions.includes(extension)) {
+        failures['extension'] = `Files ending in ${extension} are not accepted.`;
+    }
+    // A name with two extensions — `photo.png.php` — is how an upload gets
+    // executed by a misconfigured server that dispatches on the last one it
+    // recognises rather than the last one present.
+    for (const part of secondaryExtensions(input.filename)) {
+        if (policy.deniedExtensions.includes(part)) {
+            failures['extension'] = `The name contains a ${part} extension.`;
+        }
+    }
+    const detected = detectMimeType(input.content);
+    const declared = normaliseMime(input.contentType);
+    const effective = detected ?? declared;
+    if (effective === undefined) {
+        failures['type'] = 'The file type could not be determined.';
+    }
+    else if (!policy.allowedMimeTypes.includes(effective)) {
+        failures['type'] = `${effective} files are not accepted.`;
+    }
+    if (policy.verifyMagicBytes &&
+        detected !== undefined &&
+        declared !== undefined &&
+        detected !== declared) {
+        // The claim and the bytes disagree. Refused rather than silently corrected,
+        // because a caller that lies about one thing is not trustworthy about the
+        // rest of the request either.
+        failures['type'] = 'The file contents do not match the declared type.';
+    }
+    if (policy.verifyMagicBytes && detected === undefined && declared !== undefined) {
+        failures['type'] = `${declared} was declared but the contents are not recognisable as one.`;
+    }
+    if (Object.keys(failures).length > 0 || effective === undefined) {
+        const details = [{ field: 'file', constraints: failures }];
+        throw new core_1.ValidationError({ message: 'The uploaded file was rejected.', details });
+    }
+    return effective;
+}
+/** The MIME type the bytes say this is, or `undefined` if unrecognised. */
+function detectMimeType(content) {
+    for (const signature of exports.MAGIC_SIGNATURES) {
+        if (!matches(content, signature.offset, signature.bytes))
+            continue;
+        if (signature.trailer !== undefined &&
+            !matches(content, signature.trailer.offset, signature.trailer.bytes)) {
+            continue;
+        }
+        return signature.mime;
+    }
+    return undefined;
+}
+function matches(content, offset, bytes) {
+    if (content.length < offset + bytes.length)
+        return false;
+    return bytes.every((byte, index) => content[offset + index] === byte);
+}
+/** Lowercased final extension, including the dot. */
+function extensionOf(filename) {
+    const index = filename.lastIndexOf('.');
+    return index === -1 ? '' : filename.slice(index).toLowerCase();
+}
+/** Every extension except the last, for `photo.png.php`. */
+function secondaryExtensions(filename) {
+    const parts = filename.toLowerCase().split('.');
+    if (parts.length <= 2)
+        return [];
+    return parts.slice(1, -1).map((part) => `.${part}`);
+}
+function normaliseMime(contentType) {
+    if (contentType === undefined || contentType.trim() === '')
+        return undefined;
+    // `image/png; charset=binary` — the parameters are not part of the type.
+    return contentType.split(';')[0]?.trim().toLowerCase();
+}
+function formatBytes(bytes) {
+    if (bytes >= 1024 * 1024)
+        return `${String(Math.round(bytes / (1024 * 1024)))}MB`;
+    if (bytes >= 1024)
+        return `${String(Math.round(bytes / 1024))}KB`;
+    return `${String(bytes)} bytes`;
+}
+//# sourceMappingURL=validation.js.map

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@nage-api/storage",
+  "version": "1.0.0-beta.2",
+  "description": "File storage for @nage-api — pluggable CDN, content validation, SSRF-safe fetch",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "!dist/**/*.map",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nage-api/contracts": "1.0.0-beta.2",
+    "@nage-api/core": "1.0.0-beta.2"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "reflect-metadata": "^0.2.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "11.1.29",
+    "@nestjs/core": "11.1.29",
+    "@nestjs/testing": "11.1.29",
+    "@swc/core": "1.15.47",
+    "@types/node": "22.20.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "reflect-metadata": "0.2.2",
+    "rimraf": "6.1.3",
+    "rxjs": "7.8.2",
+    "typescript": "5.9.3",
+    "unplugin-swc": "1.5.11",
+    "vitest": "4.1.10",
+    "@nage-api/testing": "1.0.0-beta.2"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "clean": "rimraf dist .turbo",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}