@nage-api/storage 1.0.0-beta.2

package/dist/ports.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Storage contracts (PLAN.md §8, §12, §25 P1).
+ *
+ * One port, several backends. The application asks for "put this somewhere and
+ * give me a URL"; whether that is a local directory, S3 or Azure is a
+ * configuration choice made once at boot.
+ *
+ * The port is deliberately narrow. Buckets, ACLs, storage classes and
+ * multipart uploads are backend concepts; exposing them here would make every
+ * caller depend on the one backend that has them.
+ */
+/** A file on its way in. `content` is a buffer; streaming is a later concern. */
+export interface UploadInput {
+    /** Name as the client supplied it — untrusted, and sanitised before use. */
+    readonly filename: string;
+    readonly content: Buffer;
+    /** Declared by the client. Verified against the bytes, never believed. */
+    readonly contentType?: string;
+    /** Logical folder, e.g. `avatars`. Never a filesystem path. */
+    readonly directory?: string;
+    /** Copied to the backend where it supports metadata. */
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+/** A file that has been stored. */
+export interface StoredFile {
+    /** Backend-relative key: `avatars/2026/01/a1b2c3-photo.jpg`. */
+    readonly key: string;
+    readonly size: number;
+    /** The verified type, which may differ from what the client declared. */
+    readonly contentType: string;
+    /** SHA-256 of the bytes, for de-duplication and integrity checks. */
+    readonly checksum: string;
+    readonly uploadedAt: number;
+    /** Public URL, when the backend and configuration provide one. */
+    readonly url?: string;
+}
+/** A storage backend. */
+export interface StorageDriver {
+    readonly name: string;
+    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>;
+    /** A time-limited URL, where the backend can mint one. */
+    signedUrl?(key: string, expiresInSeconds: number): Promise<string>;
+}
+/** What a file must satisfy to be accepted (PLAN.md §12). */
+export interface UploadPolicy {
+    readonly maxSizeBytes: number;
+    /** Allow-list of MIME types. Empty means nothing is accepted. */
+    readonly allowedMimeTypes: readonly string[];
+    /**
+     * Verify the declared type against the file's magic bytes.
+     *
+     * On by default. A client that says `image/png` and sends a PHP script is
+     * the oldest upload attack there is, and the extension proves nothing.
+     */
+    readonly verifyMagicBytes: boolean;
+    /** Extensions refused regardless of the MIME type. */
+    readonly deniedExtensions: readonly string[];
+}
+/** Injected so keys and expiry are deterministic in tests. */
+export interface Clock {
+    now(): number;
+}
+export declare const systemClock: Clock;
+//# sourceMappingURL=ports.d.ts.map

package/dist/ports.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * Storage contracts (PLAN.md §8, §12, §25 P1).
+ *
+ * One port, several backends. The application asks for "put this somewhere and
+ * give me a URL"; whether that is a local directory, S3 or Azure is a
+ * configuration choice made once at boot.
+ *
+ * The port is deliberately narrow. Buckets, ACLs, storage classes and
+ * multipart uploads are backend concepts; exposing them here would make every
+ * caller depend on the one backend that has them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemClock = void 0;
+exports.systemClock = { now: () => Date.now() };
+//# sourceMappingURL=ports.js.map

package/dist/remote-fetch.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Fetching a file from a URL the application was given (PLAN.md §12:
+ * "upload+CDN+validation, SSRF-safe").
+ *
+ * "Import this image from a URL" is a server-side request forgery primitive.
+ * The URL comes from a client, the request comes from inside the network, and
+ * cloud metadata endpoints — `169.254.169.254` — hand out credentials to
+ * anything that asks from the right place.
+ *
+ * The defence is layered, because each layer alone is bypassable:
+ *
+ *  1. **scheme allow-list** — `file:`, `gopher:`, `ftp:` and friends are not
+ *     fetches an application means to make;
+ *  2. **DNS resolution before connecting** — a hostname that resolves to a
+ *     private address is refused. Checking the hostname's *text* is useless:
+ *     an attacker controls a domain that resolves to 127.0.0.1;
+ *  3. **redirects re-checked** — a public URL that redirects to
+ *     `http://169.254.169.254/` defeats a check that only ran on the first
+ *     URL, so redirects are followed manually and each hop is re-validated;
+ *  4. **size and time limits** — a URL that streams forever is a denial of
+ *     service, not a download.
+ *
+ * A residual DNS-rebinding window remains: resolution and connection are two
+ * separate operations. Closing it needs a custom agent that pins the resolved
+ * address, which is noted in the README rather than pretended away.
+ */
+export interface RemoteFetchOptions {
+    /** Schemes that may be fetched. */
+    readonly allowedProtocols?: readonly string[];
+    /** Refuse a response larger than this. */
+    readonly maxBytes?: number;
+    readonly timeoutMs?: number;
+    /** Redirect hops followed before giving up. */
+    readonly maxRedirects?: number;
+    /**
+     * Hosts allowed even though they resolve privately.
+     *
+     * For an internal service you deliberately fetch from. Empty by default.
+     */
+    readonly allowedHosts?: readonly string[];
+    /** Injected in tests; defaults to the global `fetch`. */
+    readonly fetchImpl?: typeof fetch;
+    /** Injected in tests; defaults to a real DNS lookup. */
+    readonly resolve?: (hostname: string) => Promise<readonly string[]>;
+}
+export interface FetchedFile {
+    readonly content: Buffer;
+    readonly contentType: string | undefined;
+    /** The URL actually fetched, after redirects. */
+    readonly finalUrl: string;
+}
+export declare class RemoteFetcher {
+    #private;
+    constructor(options?: RemoteFetchOptions);
+    /**
+     * Fetch a URL, re-validating every redirect hop.
+     *
+     * @throws ValidationError when the URL is not one this application may fetch
+     * @throws ExternalServiceError when the fetch itself fails
+     */
+    fetch(url: string): Promise<FetchedFile>;
+    /**
+     * Check a URL without fetching it.
+     *
+     * @throws ValidationError with a client-safe message
+     */
+    assertFetchable(url: string): Promise<void>;
+}
+/**
+ * Whether an address is one an application should never be tricked into
+ * reaching: loopback, link-local (which includes the cloud metadata endpoint),
+ * the RFC 1918 ranges, carrier-grade NAT, and their IPv6 equivalents.
+ */
+export declare function isPrivateAddress(address: string): boolean;
+//# sourceMappingURL=remote-fetch.d.ts.map

package/dist/remote-fetch.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * Fetching a file from a URL the application was given (PLAN.md §12:
+ * "upload+CDN+validation, SSRF-safe").
+ *
+ * "Import this image from a URL" is a server-side request forgery primitive.
+ * The URL comes from a client, the request comes from inside the network, and
+ * cloud metadata endpoints — `169.254.169.254` — hand out credentials to
+ * anything that asks from the right place.
+ *
+ * The defence is layered, because each layer alone is bypassable:
+ *
+ *  1. **scheme allow-list** — `file:`, `gopher:`, `ftp:` and friends are not
+ *     fetches an application means to make;
+ *  2. **DNS resolution before connecting** — a hostname that resolves to a
+ *     private address is refused. Checking the hostname's *text* is useless:
+ *     an attacker controls a domain that resolves to 127.0.0.1;
+ *  3. **redirects re-checked** — a public URL that redirects to
+ *     `http://169.254.169.254/` defeats a check that only ran on the first
+ *     URL, so redirects are followed manually and each hop is re-validated;
+ *  4. **size and time limits** — a URL that streams forever is a denial of
+ *     service, not a download.
+ *
+ * A residual DNS-rebinding window remains: resolution and connection are two
+ * separate operations. Closing it needs a custom agent that pins the resolved
+ * address, which is noted in the README rather than pretended away.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RemoteFetcher = void 0;
+exports.isPrivateAddress = isPrivateAddress;
+const promises_1 = require("node:dns/promises");
+const node_net_1 = require("node:net");
+const core_1 = require("@nage-api/core");
+const DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_REDIRECTS = 3;
+class RemoteFetcher {
+    #allowedProtocols;
+    #maxBytes;
+    #timeoutMs;
+    #maxRedirects;
+    #allowedHosts;
+    #fetch;
+    #resolve;
+    constructor(options = {}) {
+        this.#allowedProtocols = options.allowedProtocols ?? ['https:'];
+        this.#maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+        this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.#maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+        this.#allowedHosts = new Set(options.allowedHosts ?? []);
+        this.#fetch = options.fetchImpl ?? globalThis.fetch;
+        this.#resolve = options.resolve ?? defaultResolve;
+    }
+    /**
+     * Fetch a URL, re-validating every redirect hop.
+     *
+     * @throws ValidationError when the URL is not one this application may fetch
+     * @throws ExternalServiceError when the fetch itself fails
+     */
+    async fetch(url) {
+        let current = url;
+        for (let hop = 0; hop <= this.#maxRedirects; hop += 1) {
+            await this.assertFetchable(current);
+            const response = await this.#request(current);
+            const location = response.headers.get('location');
+            if (isRedirect(response.status) && location !== null) {
+                // Followed by hand so the next hop goes back through validation. A
+                // public URL that redirects to the metadata endpoint is the standard
+                // bypass for a check that only ran once.
+                current = new URL(location, current).toString();
+                continue;
+            }
+            if (!response.ok) {
+                throw new core_1.ExternalServiceError('remote-fetch', {
+                    detail: `Fetching ${current} returned ${String(response.status)}`,
+                    meta: { status: response.status },
+                });
+            }
+            return {
+                content: await this.#readBounded(response),
+                contentType: response.headers.get('content-type') ?? undefined,
+                finalUrl: current,
+            };
+        }
+        throw new core_1.ValidationError({
+            message: 'The URL redirected too many times.',
+            detail: `More than ${String(this.#maxRedirects)} redirects starting from ${url}`,
+        });
+    }
+    /**
+     * Check a URL without fetching it.
+     *
+     * @throws ValidationError with a client-safe message
+     */
+    async assertFetchable(url) {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw new core_1.ValidationError({ message: 'That is not a valid URL.' });
+        }
+        if (!this.#allowedProtocols.includes(parsed.protocol)) {
+            throw new core_1.ValidationError({
+                message: 'That URL scheme is not accepted.',
+                detail: `Protocol ${parsed.protocol} is not in the allow-list`,
+                meta: { protocol: parsed.protocol },
+            });
+        }
+        if (this.#allowedHosts.has(parsed.hostname))
+            return;
+        // Resolved, not pattern-matched: an attacker controls a public domain that
+        // resolves to 127.0.0.1, and no amount of string inspection catches it.
+        const addresses = (0, node_net_1.isIP)(parsed.hostname) !== 0
+            ? [parsed.hostname]
+            : await this.#resolveOrRefuse(parsed.hostname);
+        for (const address of addresses) {
+            if (isPrivateAddress(address)) {
+                throw new core_1.ValidationError({
+                    message: 'That URL is not reachable from here.',
+                    detail: `${parsed.hostname} resolves to the private address ${address}`,
+                    meta: { hostname: parsed.hostname },
+                });
+            }
+        }
+    }
+    async #resolveOrRefuse(hostname) {
+        try {
+            const addresses = await this.#resolve(hostname);
+            if (addresses.length === 0)
+                throw new Error('no addresses');
+            return addresses;
+        }
+        catch {
+            // A name that does not resolve is refused rather than attempted: letting
+            // the fetch proceed would move the decision to the resolver the runtime
+            // happens to use.
+            throw new core_1.ValidationError({
+                message: 'That URL is not reachable from here.',
+                detail: `${hostname} could not be resolved`,
+                meta: { hostname },
+            });
+        }
+    }
+    async #request(url) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => {
+            controller.abort();
+        }, this.#timeoutMs);
+        timer.unref();
+        try {
+            return await this.#fetch(url, {
+                redirect: 'manual',
+                signal: controller.signal,
+                headers: { accept: '*/*' },
+            });
+        }
+        catch (error) {
+            throw new core_1.ExternalServiceError('remote-fetch', {
+                detail: `Fetching ${url} failed: ${error instanceof Error ? error.message : String(error)}`,
+                cause: error,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Read a body, refusing to buffer more than the limit.
+     *
+     * `Content-Length` is checked first because it is cheap, and then the actual
+     * bytes are counted, because a server can lie about the header or omit it.
+     */
+    async #readBounded(response) {
+        const declared = Number(response.headers.get('content-length') ?? '0');
+        if (declared > this.#maxBytes) {
+            throw new core_1.ValidationError({
+                message: 'That file is too large.',
+                meta: { maxBytes: this.#maxBytes },
+            });
+        }
+        const buffer = Buffer.from(await response.arrayBuffer());
+        if (buffer.length > this.#maxBytes) {
+            throw new core_1.ValidationError({
+                message: 'That file is too large.',
+                detail: `Body was ${String(buffer.length)} bytes against a limit of ${String(this.#maxBytes)}`,
+                meta: { maxBytes: this.#maxBytes },
+            });
+        }
+        return buffer;
+    }
+}
+exports.RemoteFetcher = RemoteFetcher;
+async function defaultResolve(hostname) {
+    const results = await (0, promises_1.lookup)(hostname, { all: true });
+    return results.map((entry) => entry.address);
+}
+function isRedirect(status) {
+    return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+/**
+ * Whether an address is one an application should never be tricked into
+ * reaching: loopback, link-local (which includes the cloud metadata endpoint),
+ * the RFC 1918 ranges, carrier-grade NAT, and their IPv6 equivalents.
+ */
+function isPrivateAddress(address) {
+    const version = (0, node_net_1.isIP)(address);
+    if (version === 4) {
+        const octets = address.split('.').map(Number);
+        const [a = 0, b = 0] = octets;
+        if (a === 0 || a === 10 || a === 127)
+            return true;
+        if (a === 169 && b === 254)
+            return true; // link-local, incl. 169.254.169.254
+        if (a === 172 && b >= 16 && b <= 31)
+            return true;
+        if (a === 192 && b === 168)
+            return true;
+        if (a === 100 && b >= 64 && b <= 127)
+            return true; // carrier-grade NAT
+        if (a >= 224)
+            return true; // multicast and reserved
+        return false;
+    }
+    if (version === 6) {
+        const normalised = address.toLowerCase();
+        if (normalised === '::' || normalised === '::1')
+            return true;
+        if (normalised.startsWith('fe80'))
+            return true; // link-local
+        if (normalised.startsWith('fc') || normalised.startsWith('fd'))
+            return true; // unique local
+        if (normalised.startsWith('ff'))
+            return true; // multicast
+        // An IPv4-mapped address is still that IPv4 address.
+        const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(normalised);
+        if (mapped?.[1] !== undefined)
+            return isPrivateAddress(mapped[1]);
+        return false;
+    }
+    // Not an address at all: refuse rather than guess.
+    return true;
+}
+//# sourceMappingURL=remote-fetch.js.map

package/dist/storage.module.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `NageStorageModule.forRoot(config)` (PLAN.md §11.1 item 6).
+ *
+ * The driver is a scaffold-time choice, like the database driver: `local` is
+ * built in, and `s3`/`azure` are bound by the application because their SDKs
+ * are large and neither belongs in an install that does not use them.
+ */
+import { type DynamicModule } from '@nestjs/common';
+import type { StorageConfig } from '@nage-api/contracts';
+import { RemoteFetcher } from './remote-fetch.js';
+import type { Clock, StorageDriver, UploadPolicy } from './ports.js';
+export interface NageStorageModuleOptions {
+    readonly storage?: StorageConfig;
+    /** Required for `s3` and `azure`, which this package does not implement. */
+    readonly driver?: StorageDriver;
+    /** Root directory for the local driver. */
+    readonly root?: string;
+    /** Override the upload policy; the default allows images and PDFs. */
+    readonly policy?: Partial<UploadPolicy>;
+    /** Supply one to enable `uploadFromUrl`. */
+    readonly fetcher?: RemoteFetcher;
+    readonly clock?: Clock;
+}
+export declare class NageStorageModule {
+    static forRoot(options?: NageStorageModuleOptions): DynamicModule;
+    private static buildDriver;
+}
+/** `10MB`, `512KB`, or a plain byte count. */
+export declare function parseSize(size: string): number;
+//# sourceMappingURL=storage.module.d.ts.map

package/dist/storage.module.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * `NageStorageModule.forRoot(config)` (PLAN.md §11.1 item 6).
+ *
+ * The driver is a scaffold-time choice, like the database driver: `local` is
+ * built in, and `s3`/`azure` are bound by the application because their SDKs
+ * are large and neither belongs in an install that does not use them.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var NageStorageModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NageStorageModule = void 0;
+exports.parseSize = parseSize;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nage-api/core");
+const local_driver_js_1 = require("./local.driver.js");
+const storage_service_js_1 = require("./storage.service.js");
+const validation_js_1 = require("./validation.js");
+const tokens_js_1 = require("./tokens.js");
+let NageStorageModule = NageStorageModule_1 = class NageStorageModule {
+    static forRoot(options = {}) {
+        const config = options.storage ?? {};
+        if (config.enabled === false) {
+            return { module: NageStorageModule_1, providers: [], exports: [] };
+        }
+        const driver = options.driver ?? NageStorageModule_1.buildDriver(config, options);
+        const service = new storage_service_js_1.StorageService({
+            driver,
+            policy: { ...(0, validation_js_1.defaultUploadPolicy)(), ...resolvePolicy(config), ...options.policy },
+            ...(config.publicBaseUrl === undefined ? {} : { publicBaseUrl: config.publicBaseUrl }),
+            ...(options.fetcher === undefined ? {} : { fetcher: options.fetcher }),
+            ...(options.clock === undefined ? {} : { clock: options.clock }),
+        });
+        const providers = [
+            { provide: tokens_js_1.NAGE_STORAGE_DRIVER, useValue: driver },
+            { provide: tokens_js_1.NAGE_STORAGE, useValue: service },
+            { provide: storage_service_js_1.StorageService, useValue: service },
+        ];
+        return {
+            module: NageStorageModule_1,
+            providers,
+            exports: [tokens_js_1.NAGE_STORAGE, tokens_js_1.NAGE_STORAGE_DRIVER, storage_service_js_1.StorageService],
+        };
+    }
+    static buildDriver(config, options) {
+        const cdn = config.cdn ?? 'local';
+        if (cdn !== 'local') {
+            // Refused at composition time rather than at the first upload: a
+            // deployment should fail to boot instead.
+            throw new core_1.ConfigurationError({
+                detail: `storage.cdn "${cdn}" needs a driver; pass one to NageStorageModule.forRoot({ driver })`,
+                meta: { setting: 'storage.cdn', cdn },
+            });
+        }
+        return new local_driver_js_1.LocalStorageDriver({
+            root: options.root ?? './storage',
+            ...(config.publicBaseUrl === undefined ? {} : { publicBaseUrl: config.publicBaseUrl }),
+        });
+    }
+};
+exports.NageStorageModule = NageStorageModule;
+exports.NageStorageModule = NageStorageModule = NageStorageModule_1 = __decorate([
+    (0, common_1.Module)({})
+], NageStorageModule);
+/** Read the validation block into an upload policy. */
+function resolvePolicy(config) {
+    const validation = config.validation;
+    if (validation === undefined)
+        return {};
+    return {
+        ...(validation.maxSize === undefined ? {} : { maxSizeBytes: parseSize(validation.maxSize) }),
+        ...(validation.mime === undefined ? {} : { allowedMimeTypes: validation.mime }),
+        ...(validation.magicBytes === undefined ? {} : { verifyMagicBytes: validation.magicBytes }),
+    };
+}
+/** `10MB`, `512KB`, or a plain byte count. */
+function parseSize(size) {
+    const match = /^(\d+)\s*(b|kb|mb|gb)?$/i.exec(size.trim());
+    if (match === null) {
+        throw new core_1.ConfigurationError({
+            detail: `storage.validation.maxSize is not a size ("${size}"); use forms like 10MB`,
+            meta: { setting: 'storage.validation.maxSize', value: size },
+        });
+    }
+    const amount = Number(match[1]);
+    switch (match[2]?.toLowerCase()) {
+        case 'kb':
+            return amount * 1024;
+        case 'mb':
+            return amount * 1024 * 1024;
+        case 'gb':
+            return amount * 1024 * 1024 * 1024;
+        default:
+            return amount;
+    }
+}
+//# sourceMappingURL=storage.module.js.map

package/dist/storage.service.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ */
+import type { RemoteFetcher } from './remote-fetch.js';
+import type { Clock, StorageDriver, StoredFile, UploadInput, UploadPolicy } from './ports.js';
+export interface StorageServiceOptions {
+    readonly driver: StorageDriver;
+    readonly policy?: UploadPolicy;
+    /** Base URL stored files are served from. */
+    readonly publicBaseUrl?: string;
+    /** Supplied when the application imports files from URLs. */
+    readonly fetcher?: RemoteFetcher;
+    readonly clock?: Clock;
+}
+export declare class StorageService {
+    #private;
+    constructor(options: StorageServiceOptions);
+    /**
+     * 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.
+     */
+    upload(input: UploadInput): Promise<StoredFile>;
+    /**
+     * 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.
+     */
+    uploadFromUrl(url: string, options?: {
+        directory?: string;
+        filename?: string;
+    }): Promise<StoredFile>;
+    download(key: string): Promise<Buffer>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    /** A time-limited URL, when the driver can mint one. */
+    signedUrl(key: string, expiresInSeconds?: number): Promise<string | undefined>;
+    /** The public URL for a key, when one is configured. */
+    url(key: string): string | undefined;
+    get policy(): UploadPolicy;
+}
+//# sourceMappingURL=storage.service.d.ts.map