@nestm/storage 0.1.0-alpha.0 → 0.1.0-alpha.10

package/dist/gateway/storage-gateway.controller.js

@@ -14,12 +14,84 @@ import { BadRequestException, Body, Controller, Delete, Get, Head, HttpException
 import { ServerResponse } from 'node:http';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
-import { StorageError, StorageErrorCode } from '../storage.error.js';
+import { StorageError, StorageErrorCode, isStorageError, } from '../storage.error.js';
+import { isCanonicalStorageEtag, storageEtagHeader } from '../storage-etag.js';
 import { StorageService } from '../storage.service.js';
 import { StorageGatewayGuard } from './storage-gateway.guard.js';
 import { FASTIFY_STORAGE_UPLOAD_CONFIG } from './storage-gateway-fastify-parser.js';
-import { STORAGE_GATEWAY_OPTIONS } from './storage-gateway.tokens.js';
+import { STORAGE_GATEWAY_KEY_POLICY, STORAGE_GATEWAY_OPTIONS, } from './storage-gateway.tokens.js';
 import { StorageGatewayOperation, } from './storage-gateway.types.js';
+const MAX_GATEWAY_PATH_LENGTH = 1024;
+function parseGatewayPath(value, target) {
+    if (value === undefined) {
+        if (target === 'prefix') {
+            return undefined;
+        }
+        throw new BadRequestException(`${target} is required.`);
+    }
+    if (value.length > MAX_GATEWAY_PATH_LENGTH) {
+        throw new BadRequestException(`${target} cannot exceed ${MAX_GATEWAY_PATH_LENGTH} characters.`);
+    }
+    if (value.length === 0) {
+        if (target === 'prefix') {
+            return Object.freeze({
+                segments: Object.freeze([]),
+                trailingSlash: false,
+                value,
+            });
+        }
+        throw new BadRequestException(`${target} must be a non-empty string.`);
+    }
+    if ([...value].some((character) => {
+        const codePoint = character.codePointAt(0);
+        return (character === '\\' ||
+            codePoint === undefined ||
+            codePoint <= 0x1f ||
+            codePoint === 0x7f);
+    })) {
+        throw new BadRequestException(`${target} cannot contain control characters or backslashes.`);
+    }
+    if (target === 'pattern') {
+        return Object.freeze({
+            segments: Object.freeze(value.split('/')),
+            trailingSlash: value.endsWith('/'),
+            value,
+        });
+    }
+    if (value.startsWith('/') || value.trim() !== value) {
+        throw new BadRequestException(`${target} must be a relative object path without surrounding whitespace.`);
+    }
+    const trailingSlash = value.endsWith('/');
+    const segments = value.split('/');
+    if (trailingSlash) {
+        segments.pop();
+    }
+    if (segments.some((segment) => segment.length === 0 || segment === '.' || segment === '..')) {
+        throw new BadRequestException(`${target} cannot contain empty, dot, or parent path segments.`);
+    }
+    return Object.freeze({
+        segments: Object.freeze(segments),
+        trailingSlash,
+        value,
+    });
+}
+function exactContentType(value, field) {
+    const normalized = value.toLowerCase();
+    if (value !== normalized ||
+        !/^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/u.test(value)) {
+        throw new BadRequestException(`${field} must be a lowercase exact MIME type without parameters.`);
+    }
+    return normalized;
+}
+function safeContentDisposition(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value !== 'attachment' && value !== 'inline') {
+        throw new BadRequestException('responseContentDisposition must be either "attachment" or "inline".');
+    }
+    return value;
+}
 function recordOf(value, label) {
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
         throw new BadRequestException(`${label} must be a JSON object.`);
@@ -141,11 +213,21 @@ async function* enforceUploadLimit(source, maxBytes) {
         yield bytes;
     }
 }
-function setObjectHeaders(response, object) {
+function providerEtagHeader(object) {
+    const etag = object.etag === undefined ? undefined : storageEtagHeader(object.etag);
+    if (object.etag !== undefined && etag === undefined) {
+        throw new StorageError('Storage provider returned a malformed ETag.', {
+            code: StorageErrorCode.PROVIDER,
+            permanent: true,
+        });
+    }
+    return etag;
+}
+function setObjectHeaders(response, object, etag) {
     response.setHeader('content-length', String(object.size));
     response.setHeader('content-type', object.contentType);
-    if (object.etag !== undefined) {
-        response.setHeader('etag', object.etag);
+    if (etag !== undefined) {
+        response.setHeader('etag', etag);
     }
     if (object.lastModified !== undefined) {
         response.setHeader('last-modified', object.lastModified.toUTCString());
@@ -190,11 +272,17 @@ function toHttpException(error) {
     if (error instanceof HttpException) {
         return error;
     }
-    if (error instanceof StorageError) {
+    if (isStorageError(error)) {
         return new HttpException({
             error: {
                 code: error.code,
                 message: publicStorageMessages[error.code],
+                ...(error.applied === true && { applied: true }),
+                ...(error.applied === true &&
+                    error.appliedEtag !== undefined &&
+                    isCanonicalStorageEtag(error.appliedEtag) && {
+                    appliedEtag: error.appliedEtag,
+                }),
             },
         }, storageHttpStatus(error), { cause: error });
     }
@@ -208,24 +296,28 @@ function toHttpException(error) {
 let StorageGatewayController = class StorageGatewayController {
     storage;
     options;
-    constructor(storage, options) {
+    keyPolicy;
+    constructor(storage, options, keyPolicy) {
         this.storage = storage;
         this.options = options;
+        this.keyPolicy = keyPolicy;
     }
-    async download(key, proxy, rangeStart, rangeEnd, disposition, response) {
+    async download(key, proxy, rangeStart, rangeEnd, disposition, request, response) {
         await this.#run(async () => {
             this.#assertAllowed(StorageGatewayOperation.DOWNLOAD);
-            const objectKey = this.#key(key);
+            const responseContentDisposition = safeContentDisposition(disposition);
             const client = this.storage.use(this.options.store);
             const forceProxy = proxy === 'true' || proxy === '1';
             const canSign = this.options.operations.has(StorageGatewayOperation.SIGN_DOWNLOAD) &&
-                client.capabilities.signedDownload.supported;
+                client.capabilities.signedDownload.supported &&
+                client.capabilities.signedDownloadPolicy?.expiresIn === true;
             if (!forceProxy && this.options.mode !== 'proxy' && canSign) {
                 try {
-                    const url = await client.signDownload(objectKey, {
+                    const signedObjectKey = await this.#resolvePath(request, StorageGatewayOperation.SIGN_DOWNLOAD, 'key', key);
+                    const url = await client.signDownload(signedObjectKey, {
                         expiresIn: this.options.defaultSignedUrlExpiresIn,
-                        ...(disposition !== undefined && {
-                            responseContentDisposition: disposition,
+                        ...(responseContentDisposition !== undefined && {
+                            responseContentDisposition,
                         }),
                     });
                     const raw = rawResponseOf(response);
@@ -236,7 +328,7 @@ let StorageGatewayController = class StorageGatewayController {
                 }
                 catch (error) {
                     if (this.options.mode !== 'hybrid' ||
-                        !(error instanceof StorageError) ||
+                        !isStorageError(error) ||
                         error.code !== StorageErrorCode.NOT_SUPPORTED) {
                         throw error;
                     }
@@ -245,10 +337,10 @@ let StorageGatewayController = class StorageGatewayController {
             if (this.options.mode === 'signed') {
                 throw new StorageError('Signed downloads are unavailable for this store.', {
                     code: StorageErrorCode.NOT_SUPPORTED,
-                    key: objectKey,
                     permanent: true,
                 });
             }
+            const objectKey = await this.#resolvePath(request, StorageGatewayOperation.DOWNLOAD, 'key', key);
             const start = queryInteger(rangeStart, 'rangeStart');
             const end = queryInteger(rangeEnd, 'rangeEnd');
             if (end !== undefined && start === undefined) {
@@ -260,10 +352,18 @@ let StorageGatewayController = class StorageGatewayController {
             const object = await client.downloadStream(objectKey, {
                 ...(range !== undefined && { range }),
             });
+            let etag;
+            try {
+                etag = providerEtagHeader(object);
+            }
+            catch (error) {
+                await object.body.cancel(error).catch(() => undefined);
+                throw error;
+            }
             const raw = rawResponseOf(response);
             raw.statusCode =
                 range === undefined ? HttpStatus.OK : HttpStatus.PARTIAL_CONTENT;
-            setObjectHeaders(raw, object);
+            setObjectHeaders(raw, object, etag);
             const baseContentType = object.contentType
                 .split(';', 1)[0]
                 ?.trim()
@@ -300,7 +400,7 @@ let StorageGatewayController = class StorageGatewayController {
                     permanent: true,
                 });
             }
-            const objectKey = this.#key(key);
+            const objectKey = await this.#resolvePath(request, StorageGatewayOperation.UPLOAD, 'key', key);
             const transportContentType = requestHeader(request, 'content-type')
                 ?.split(';', 1)[0]
                 ?.trim()
@@ -322,53 +422,58 @@ let StorageGatewayController = class StorageGatewayController {
             }
             const source = uploadSourceOf(request);
             const body = Readable.toWeb(Readable.from(enforceUploadLimit(source, this.options.maxUploadBytes)));
-            const contentType = requestHeader(request, 'x-storage-content-type') ??
-                'application/octet-stream';
+            const contentType = exactContentType(requestHeader(request, 'x-storage-content-type') ??
+                'application/octet-stream', 'x-storage-content-type');
             const result = await this.storage
                 .use(this.options.store)
                 .upload(objectKey, body, { contentType, multipart: true });
             return { data: result };
         });
     }
-    async head(key, response) {
+    async head(key, request, response) {
         await this.#run(async () => {
             this.#assertAllowed(StorageGatewayOperation.HEAD);
+            const objectKey = await this.#resolvePath(request, StorageGatewayOperation.HEAD, 'key', key);
             const metadata = await this.storage
                 .use(this.options.store)
-                .head(this.#key(key));
+                .head(objectKey);
+            const etag = providerEtagHeader(metadata);
             const raw = rawResponseOf(response);
             raw.statusCode = HttpStatus.OK;
-            setObjectHeaders(raw, metadata);
+            setObjectHeaders(raw, metadata, etag);
             raw.end();
         });
     }
-    async delete(key) {
+    async delete(key, request) {
         return this.#run(async () => {
             this.#assertAllowed(StorageGatewayOperation.DELETE);
-            await this.storage.use(this.options.store).delete(this.#key(key));
+            const objectKey = await this.#resolvePath(request, StorageGatewayOperation.DELETE, 'key', key);
+            await this.storage.use(this.options.store).delete(objectKey);
             return { data: { deleted: true } };
         });
     }
-    async list(prefix, cursor, limit, delimiter) {
+    async list(prefix, cursor, limit, delimiter, request) {
         return this.#run(async () => {
             this.#assertAllowed(StorageGatewayOperation.LIST);
             const parsedLimit = queryInteger(limit, 'limit') ?? this.options.maxListResults;
             if (parsedLimit === 0 || parsedLimit > this.options.maxListResults) {
                 throw new BadRequestException(`limit must be between 1 and ${this.options.maxListResults}.`);
             }
+            const resolvedPrefix = await this.#resolvePath(request, StorageGatewayOperation.LIST, 'prefix', prefix);
             const result = await this.storage.use(this.options.store).list({
                 ...(cursor !== undefined && { cursor }),
                 ...(delimiter !== undefined && { delimiter }),
                 limit: parsedLimit,
-                ...(prefix !== undefined && { prefix }),
+                prefix: resolvedPrefix,
             });
             return { data: result };
         });
     }
-    async search(pattern, prefix, limit, maxResults, match, caseInsensitive) {
+    async search(pattern, prefix, limit, maxResults, match, caseInsensitive, request) {
         return this.#run(async () => {
             this.#assertAllowed(StorageGatewayOperation.SEARCH);
-            const searchPattern = this.#key(pattern, 'pattern');
+            const searchPattern = await this.#resolvePath(request, StorageGatewayOperation.SEARCH, 'pattern', pattern);
+            const resolvedPrefix = await this.#resolvePath(request, StorageGatewayOperation.SEARCH, 'prefix', prefix);
             if (match !== undefined &&
                 !['glob', 'regex', 'substring', 'exact'].includes(match)) {
                 throw new BadRequestException('Invalid search match mode.');
@@ -395,7 +500,7 @@ let StorageGatewayController = class StorageGatewayController {
                     match: match,
                 }),
                 maxResults: parsedMaxResults,
-                ...(prefix !== undefined && { prefix }),
+                prefix: resolvedPrefix,
             })) {
                 objects.push(object);
                 if (objects.length === parsedMaxResults) {
@@ -405,7 +510,7 @@ let StorageGatewayController = class StorageGatewayController {
             return { data: objects };
         });
     }
-    async signDownload(body) {
+    async signDownload(body, request) {
         return this.#run(async () => {
             this.#assertAllowed(StorageGatewayOperation.SIGN_DOWNLOAD);
             if (this.options.mode === 'proxy') {
@@ -415,21 +520,28 @@ let StorageGatewayController = class StorageGatewayController {
                 });
             }
             const input = recordOf(body, 'body');
-            const responseContentDisposition = optionalString(input, 'responseContentDisposition');
+            const responseContentDisposition = safeContentDisposition(optionalString(input, 'responseContentDisposition'));
             const options = {
-                expiresIn: optionalPositiveInteger(input, 'expiresIn') ??
-                    this.options.defaultSignedUrlExpiresIn,
+                expiresIn: this.#signedExpiry(input),
                 ...(responseContentDisposition !== undefined && {
                     responseContentDisposition,
                 }),
             };
-            const url = await this.storage
-                .use(this.options.store)
-                .signDownload(requiredString(input, 'key'), options);
+            const objectKey = await this.#resolvePath(request, StorageGatewayOperation.SIGN_DOWNLOAD, 'key', requiredString(input, 'key'));
+            const client = this.storage.use(this.options.store);
+            if (client.capabilities.signedDownloadPolicy?.expiresIn !== true) {
+                throw new StorageError('This store cannot prove that signed-download expiry is provider-enforced.', {
+                    code: StorageErrorCode.NOT_SUPPORTED,
+                    key: objectKey,
+                    operation: 'signDownload',
+                    permanent: true,
+                });
+            }
+            const url = await client.signDownload(objectKey, options);
             return { data: { url } };
         });
     }
-    async signUpload(body) {
+    async signUpload(body, request) {
         return this.#run(async () => {
             this.#assertAllowed(StorageGatewayOperation.SIGN_UPLOAD);
             if (this.options.mode === 'proxy') {
@@ -439,42 +551,70 @@ let StorageGatewayController = class StorageGatewayController {
                 });
             }
             const input = recordOf(body, 'body');
-            const contentType = optionalString(input, 'contentType');
-            const maxSize = optionalPositiveInteger(input, 'maxSize');
+            const rawContentType = optionalString(input, 'contentType');
+            if (rawContentType === undefined) {
+                throw new BadRequestException('contentType is required for signed uploads.');
+            }
+            const contentType = exactContentType(rawContentType, 'contentType');
+            if (!this.options.signedUploadContentTypes.has(contentType)) {
+                throw new BadRequestException(`contentType "${contentType}" is not allowed for signed uploads.`);
+            }
+            const requestedMaxSize = optionalPositiveInteger(input, 'maxSize');
+            if (requestedMaxSize !== undefined &&
+                requestedMaxSize > this.options.maxSignedUploadBytes) {
+                throw new StorageError(`Signed upload exceeds the ${this.options.maxSignedUploadBytes}-byte gateway limit.`, {
+                    code: StorageErrorCode.LIMIT_EXCEEDED,
+                    permanent: true,
+                });
+            }
+            const maxSize = requestedMaxSize ?? this.options.maxSignedUploadBytes;
             const minSize = optionalNonNegativeInteger(input, 'minSize');
             if (maxSize !== undefined && minSize !== undefined && minSize > maxSize) {
                 throw new BadRequestException('minSize cannot be greater than maxSize.');
             }
             const options = {
-                expiresIn: optionalPositiveInteger(input, 'expiresIn') ??
-                    this.options.defaultSignedUrlExpiresIn,
-                ...(contentType !== undefined && { contentType }),
-                ...(maxSize !== undefined && { maxSize }),
+                contentType,
+                expiresIn: this.#signedExpiry(input),
+                maxSize,
                 ...(minSize !== undefined && { minSize }),
             };
-            const result = await this.storage
-                .use(this.options.store)
-                .signUpload(requiredString(input, 'key'), options);
+            const objectKey = await this.#resolvePath(request, StorageGatewayOperation.SIGN_UPLOAD, 'key', requiredString(input, 'key'));
+            const client = this.storage.use(this.options.store);
+            const policyCapability = client.capabilities.signedUploadPolicy;
+            if (policyCapability?.contentType !== true ||
+                policyCapability.sizeRange !== true) {
+                throw new StorageError('This store cannot prove that signed-upload MIME and size constraints are provider-enforced.', {
+                    code: StorageErrorCode.NOT_SUPPORTED,
+                    key: objectKey,
+                    operation: 'signUpload',
+                    permanent: true,
+                });
+            }
+            const result = await client.signUpload(objectKey, options);
             return { data: result };
         });
     }
-    async copy(body) {
+    async copy(body, request) {
         return this.#run(async () => {
             this.#assertAllowed(StorageGatewayOperation.COPY);
             const input = recordOf(body, 'body');
-            await this.storage
-                .use(this.options.store)
-                .copy(requiredString(input, 'from'), requiredString(input, 'to'));
+            const [from, to] = await Promise.all([
+                this.#resolvePath(request, StorageGatewayOperation.COPY, 'from', requiredString(input, 'from')),
+                this.#resolvePath(request, StorageGatewayOperation.COPY, 'to', requiredString(input, 'to')),
+            ]);
+            await this.storage.use(this.options.store).copy(from, to);
             return { data: { copied: true } };
         });
     }
-    async move(body) {
+    async move(body, request) {
         return this.#run(async () => {
             this.#assertAllowed(StorageGatewayOperation.MOVE);
             const input = recordOf(body, 'body');
-            await this.storage
-                .use(this.options.store)
-                .move(requiredString(input, 'from'), requiredString(input, 'to'));
+            const [from, to] = await Promise.all([
+                this.#resolvePath(request, StorageGatewayOperation.MOVE, 'from', requiredString(input, 'from')),
+                this.#resolvePath(request, StorageGatewayOperation.MOVE, 'to', requiredString(input, 'to')),
+            ]);
+            await this.storage.use(this.options.store).move(from, to);
             return { data: { moved: true } };
         });
     }
@@ -488,11 +628,31 @@ let StorageGatewayController = class StorageGatewayController {
             }, HttpStatus.FORBIDDEN);
         }
     }
-    #key(value, label = 'key') {
-        if (value === undefined || value.length === 0) {
-            throw new BadRequestException(`${label} is required.`);
+    async #resolvePath(request, operation, target, value) {
+        const input = parseGatewayPath(value, target);
+        const resolved = await this.keyPolicy.resolve({
+            input,
+            operation,
+            request,
+            target,
+        });
+        const parsed = parseGatewayPath(resolved, target);
+        if (parsed === undefined) {
+            throw new StorageError(`Storage gateway key policy did not resolve ${target}.`, {
+                code: StorageErrorCode.UNAUTHORIZED,
+                operation,
+                permanent: true,
+            });
+        }
+        return parsed.value;
+    }
+    #signedExpiry(input) {
+        const expiresIn = optionalPositiveInteger(input, 'expiresIn') ??
+            this.options.defaultSignedUrlExpiresIn;
+        if (expiresIn > this.options.maxSignedUrlExpiresIn) {
+            throw new BadRequestException(`expiresIn cannot exceed ${this.options.maxSignedUrlExpiresIn} seconds.`);
         }
-        return value;
+        return expiresIn;
     }
     async #run(operation) {
         try {
@@ -510,9 +670,10 @@ __decorate([
     __param(2, Query('rangeStart')),
     __param(3, Query('rangeEnd')),
     __param(4, Query('disposition')),
-    __param(5, Res()),
+    __param(5, Req()),
+    __param(6, Res()),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object, Object, Object, Object, Object, Object]),
+    __metadata("design:paramtypes", [Object, Object, Object, Object, Object, Object, Object]),
     __metadata("design:returntype", Promise)
 ], StorageGatewayController.prototype, "download", null);
 __decorate([
@@ -529,16 +690,18 @@ __decorate([
 __decorate([
     Head('metadata'),
     __param(0, Query('key')),
-    __param(1, Res()),
+    __param(1, Req()),
+    __param(2, Res()),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:paramtypes", [Object, Object, Object]),
     __metadata("design:returntype", Promise)
 ], StorageGatewayController.prototype, "head", null);
 __decorate([
     Delete('object'),
     __param(0, Query('key')),
+    __param(1, Req()),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object]),
+    __metadata("design:paramtypes", [Object, Object]),
     __metadata("design:returntype", Promise)
 ], StorageGatewayController.prototype, "delete", null);
 __decorate([
@@ -547,8 +710,9 @@ __decorate([
     __param(1, Query('cursor')),
     __param(2, Query('limit')),
     __param(3, Query('delimiter')),
+    __param(4, Req()),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object, Object, Object, Object]),
+    __metadata("design:paramtypes", [Object, Object, Object, Object, Object]),
     __metadata("design:returntype", Promise)
 ], StorageGatewayController.prototype, "list", null);
 __decorate([
@@ -559,43 +723,49 @@ __decorate([
     __param(3, Query('maxResults')),
     __param(4, Query('match')),
     __param(5, Query('caseInsensitive')),
+    __param(6, Req()),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object, Object, Object, Object, Object, Object]),
+    __metadata("design:paramtypes", [Object, Object, Object, Object, Object, Object, Object]),
     __metadata("design:returntype", Promise)
 ], StorageGatewayController.prototype, "search", null);
 __decorate([
     Post('sign-download'),
     __param(0, Body()),
+    __param(1, Req()),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object]),
+    __metadata("design:paramtypes", [Object, Object]),
     __metadata("design:returntype", Promise)
 ], StorageGatewayController.prototype, "signDownload", null);
 __decorate([
     Post('sign-upload'),
     __param(0, Body()),
+    __param(1, Req()),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object]),
+    __metadata("design:paramtypes", [Object, Object]),
     __metadata("design:returntype", Promise)
 ], StorageGatewayController.prototype, "signUpload", null);
 __decorate([
     Post('copy'),
     __param(0, Body()),
+    __param(1, Req()),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object]),
+    __metadata("design:paramtypes", [Object, Object]),
     __metadata("design:returntype", Promise)
 ], StorageGatewayController.prototype, "copy", null);
 __decorate([
     Post('move'),
     __param(0, Body()),
+    __param(1, Req()),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object]),
+    __metadata("design:paramtypes", [Object, Object]),
     __metadata("design:returntype", Promise)
 ], StorageGatewayController.prototype, "move", null);
 StorageGatewayController = __decorate([
     Controller('storage'),
     UseGuards(StorageGatewayGuard),
     __param(1, Inject(STORAGE_GATEWAY_OPTIONS)),
-    __metadata("design:paramtypes", [StorageService, Object])
+    __param(2, Inject(STORAGE_GATEWAY_KEY_POLICY)),
+    __metadata("design:paramtypes", [StorageService, Object, Object])
 ], StorageGatewayController);
 export { StorageGatewayController };
 //# sourceMappingURL=storage-gateway.controller.js.map