secure-s3-storage 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nemovim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,131 @@
+# secure-s3-storage
+
+S3-backed file upload module with content validation, category-based paths, UUID filenames, and date-based (`YYYY-MM-DD`) object keys.
+
+## Install
+
+```bash
+npm install secure-s3-storage
+```
+
+## Quick Start
+
+```ts
+import { init } from "secure-s3-storage";
+import { readFile } from "node:fs/promises";
+
+const storage = init({
+  bucket: "my-bucket",
+  region: "ap-northeast-2",
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  categories: {
+    images: ["jpg", "jpeg", "png", "webp"],
+    documents: ["pdf", "txt", "md"],
+  },
+});
+
+const result = await storage.upload(file);
+
+const body = await readFile("./photo.png");
+await storage.put("images", body, "image/png");
+
+await storage.remove(result.key);
+```
+
+If you use temporary AWS credentials, pass `sessionToken` as well.
+
+```ts
+const storage = init({
+  bucket: "my-bucket",
+  region: "ap-northeast-2",
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  sessionToken: process.env.AWS_SESSION_TOKEN!,
+  categories: {
+    images: ["jpg", "jpeg", "png", "webp"],
+    documents: ["pdf", "txt", "md"],
+  },
+});
+```
+
+## API
+
+### `init(options)`
+
+Creates a storage instance.
+
+- `bucket`: S3 bucket name
+- `region`: S3 region
+- `accessKeyId` / `secretAccessKey`: AWS keys. Passing only one throws an error.
+- `sessionToken`: Only needed for temporary AWS credentials.
+- `categories`: Mapping of category names to allowed file extensions
+
+Example `categories`:
+
+```ts
+{
+  images: ["jpg", "jpeg", "png", "webp"],
+  documents: ["pdf", "txt", "md"],
+}
+```
+
+Behavior:
+
+1. The file extension decides which category to use.
+2. The category name becomes the S3 key prefix and must be a valid key path segment.
+3. Unlisted extensions are rejected with `StorageValidationError`.
+4. If the same extension appears in multiple categories, the first one wins.
+
+### `storage.upload(file)`
+
+Uploads a browser `File`.
+
+- Returns: `UploadResult`
+- `file`: `{ arrayBuffer(): Promise<ArrayBuffer>; name: string; type?: string }`
+
+### `storage.put(path, body, contentType?)`
+
+Uploads a server-side `Buffer`.
+
+- Returns: `UploadResult`
+
+### `storage.remove(key)`
+
+Deletes an S3 object by full object key.
+
+### `storage.getUrl(key)`
+
+Builds the public URL for an object key.
+
+## Validation And Errors
+
+- Validates file content against the file extension.
+- Blocks dangerous executable and script-like extensions.
+- `upload()` validates file content and filename together.
+- `remove()` and `getUrl()` validate empty keys, normalize separators and repeated slashes, and reject `.` and `..` path segments.
+
+Validation failures throw `StorageValidationError`.
+
+Common error cases:
+
+- Unknown category
+- Disallowed extension
+- File content does not match the extension
+- Empty key, invalid path segments, or path traversal in a key
+
+## Output Types
+
+### `UploadResult`
+
+Return value from `storage.upload()` and `storage.put()`.
+
+```ts
+{
+  bucket: string;
+  key: string;
+  filename: string;
+  extension: string;
+  contentType?: string;
+}
+```

package/README.md

@@ -0,0 +1,133 @@
+# secure-s3-storage
+
+[English README](./README.en.md)
+
+S3 기반 파일 업로드 모듈입니다. 파일 내용을 검증하고, 카테고리별 경로로 업로드하며, UUID 파일명과 날짜 기반(`YYYY-MM-DD`) object key를 생성합니다.
+
+## Install
+
+```bash
+npm install secure-s3-storage
+```
+
+## Quick Start
+
+```ts
+import { init } from "secure-s3-storage";
+import { readFile } from "node:fs/promises";
+
+const storage = init({
+  bucket: "my-bucket",
+  region: "ap-northeast-2",
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  categories: {
+    images: ["jpg", "jpeg", "png", "webp"],
+    documents: ["pdf", "txt", "md"],
+  },
+});
+
+const result = await storage.upload(file);
+
+const body = await readFile("./photo.png");
+await storage.put("images", body, "image/png");
+
+await storage.remove(result.key);
+```
+
+임시 AWS credential을 쓰는 경우에는 `sessionToken`도 함께 넣으면 됩니다.
+
+```ts
+const storage = init({
+  bucket: "my-bucket",
+  region: "ap-northeast-2",
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  sessionToken: process.env.AWS_SESSION_TOKEN!,
+  categories: {
+    images: ["jpg", "jpeg", "png", "webp"],
+    documents: ["pdf", "txt", "md"],
+  },
+});
+```
+
+## API
+
+### `init(options)`
+
+스토리지 인스턴스를 생성합니다.
+
+- `bucket`: S3 버킷 이름
+- `region`: S3 리전
+- `accessKeyId` / `secretAccessKey`: AWS key입니다. 둘 중 하나만 넣으면 에러가 발생합니다.
+- `sessionToken`: 임시 AWS credential을 사용할 때만 필요합니다.
+- `categories`: 카테고리 이름과 허용할 확장자 목록입니다.
+
+`categories` 예시:
+
+```ts
+{
+  images: ["jpg", "jpeg", "png", "webp"],
+  documents: ["pdf", "txt", "md"],
+}
+```
+
+동작 방식:
+
+1. 파일 확장자를 기준으로 업로드할 카테고리를 결정합니다.
+2. 카테고리 이름이 S3 key prefix로 사용되며, 유효한 key path segment 형태여야 합니다.
+3. 허용되지 않은 확장자는 `StorageValidationError`와 함께 차단됩니다.
+4. 같은 확장자가 여러 카테고리에 있으면 먼저 정의한 카테고리를 사용합니다.
+
+### `storage.upload(file)`
+
+브라우저 `File` 객체를 업로드합니다.
+
+- 반환값: `UploadResult`
+- `file`: `{ arrayBuffer(): Promise<ArrayBuffer>; name: string; type?: string }`
+
+### `storage.put(path, body, contentType?)`
+
+서버에서 `Buffer`를 직접 업로드합니다.
+
+- 반환값: `UploadResult`
+
+### `storage.remove(key)`
+
+저장된 전체 object key를 받아 S3 객체를 삭제합니다.
+
+### `storage.getUrl(key)`
+
+object key 기준으로 공개 URL을 생성합니다.
+
+## Validation And Errors
+
+- 파일 내용과 확장자를 비교해 검증합니다.
+- 실행 파일, 스크립트 같은 위험한 확장자는 차단합니다.
+- `upload()`는 파일 내용과 파일명까지 함께 보고 더 엄격하게 검증합니다.
+- `remove()`와 `getUrl()`은 빈 key를 막고, 경로 구분자와 중복 슬래시를 정규화하며, `.` 및 `..` 경로 세그먼트를 검증합니다.
+
+검증에 실패하면 `StorageValidationError`가 발생합니다.
+
+주요 에러 상황:
+
+- 알 수 없는 카테고리
+- 허용되지 않은 확장자
+- 파일 내용과 확장자가 맞지 않는 경우
+- key가 비어 있거나 잘못된 path segment 또는 path traversal이 포함된 경우
+
+## Output Types
+
+### `UploadResult`
+
+`storage.upload()`와 `storage.put()`의 반환값입니다.
+
+```ts
+{
+  bucket: string;
+  key: string;
+  filename: string;
+  extension: string;
+  contentType?: string;
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import { type S3ClientConfig } from "@aws-sdk/client-s3";
+export type StorageInitOptions = {
+    bucket: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    sessionToken?: string;
+} & Omit<S3ClientConfig, "credentials"> & {
+    categories: Record<string, string[]>;
+};
+export type BrowserFile = {
+    arrayBuffer(): Promise<ArrayBuffer>;
+    name: string;
+    type?: string;
+};
+export type UploadResult = {
+    bucket: string;
+    key: string;
+    filename: string;
+    extension: string;
+    contentType?: string;
+};
+export type Storage = ReturnType<typeof init>;
+export declare class StorageValidationError extends Error {
+    constructor(message: string);
+}
+export declare function init(options: StorageInitOptions): {
+    put: (path: string, file: Buffer, contentType?: string) => Promise<UploadResult>;
+    upload: (file: BrowserFile) => Promise<UploadResult>;
+    remove: (key: string) => Promise<void>;
+    getUrl: (key: string) => string;
+};

package/dist/index.js

@@ -0,0 +1,349 @@
+import { DeleteObjectCommand, PutObjectCommand, S3Client, } from "@aws-sdk/client-s3";
+import { randomUUID } from "node:crypto";
+import { fileTypeFromBuffer } from "file-type";
+import { lookup as lookupMimeType, extension as mimeExtension } from "mime-types";
+const DANGEROUS_EXTENSIONS = new Set([
+    "ade",
+    "adp",
+    "app",
+    "asp",
+    "aspx",
+    "bat",
+    "cer",
+    "cgi",
+    "chm",
+    "cmd",
+    "com",
+    "cpl",
+    "crt",
+    "cshtml",
+    "dll",
+    "drv",
+    "exe",
+    "hta",
+    "htaccess",
+    "htm",
+    "html",
+    "inf",
+    "iso",
+    "jar",
+    "js",
+    "jsp",
+    "jsx",
+    "lnk",
+    "mht",
+    "mhtml",
+    "mjs",
+    "msi",
+    "msix",
+    "php",
+    "phar",
+    "php3",
+    "php4",
+    "php5",
+    "phtml",
+    "pl",
+    "ps1",
+    "py",
+    "rb",
+    "reg",
+    "scr",
+    "sh",
+    "svg",
+    "svgz",
+    "swf",
+    "ts",
+    "tsx",
+    "vb",
+    "vbe",
+    "vbs",
+    "war",
+    "ws",
+    "wsc",
+    "wsf",
+    "wsh",
+    "xhtml",
+    "xml",
+]);
+const TEXT_EXTENSIONS = new Set(["csv", "json", "md", "txt", "yml", "yaml"]);
+export class StorageValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "StorageValidationError";
+    }
+}
+export function init(options) {
+    const { bucket, categories, accessKeyId, secretAccessKey, sessionToken, ...s3Config } = options;
+    const normalizedAccessKeyId = typeof accessKeyId === "string" ? accessKeyId.trim() : undefined;
+    const normalizedSecretAccessKey = typeof secretAccessKey === "string" ? secretAccessKey.trim() : undefined;
+    const normalizedSessionToken = typeof sessionToken === "string" ? sessionToken.trim() : undefined;
+    const hasAccessKeyId = typeof normalizedAccessKeyId === "string" && normalizedAccessKeyId.length > 0;
+    const hasSecretAccessKey = typeof normalizedSecretAccessKey === "string" && normalizedSecretAccessKey.length > 0;
+    if (hasAccessKeyId !== hasSecretAccessKey) {
+        throw new StorageValidationError("accessKeyId and secretAccessKey must be provided together.");
+    }
+    const client = new S3Client({
+        ...s3Config,
+        ...(hasAccessKeyId && hasSecretAccessKey
+            ? {
+                credentials: {
+                    accessKeyId: normalizedAccessKeyId,
+                    secretAccessKey: normalizedSecretAccessKey,
+                    ...(normalizedSessionToken ? { sessionToken: normalizedSessionToken } : {}),
+                },
+            }
+            : {}),
+    });
+    const normalizedPaths = normalizePathConfigs(categories);
+    const region = s3Config.region || 'us-east-1';
+    const extensionToPath = new Map();
+    for (const [name, cfg] of Object.entries(normalizedPaths)) {
+        for (const ext of cfg.allowedExtensions) {
+            if (!extensionToPath.has(ext))
+                extensionToPath.set(ext, name);
+        }
+    }
+    async function put(path, file, contentType) {
+        const config = getPathConfig(normalizedPaths, path);
+        const detected = await fileTypeFromBuffer(file);
+        let extension = detected?.ext || "";
+        if (!extension && contentType) {
+            const fromMime = mimeExtension(contentType);
+            if (typeof fromMime === "string") {
+                extension = fromMime;
+            }
+        }
+        if (!extension) {
+            throw new StorageValidationError("Could not determine file extension for put().");
+        }
+        if (DANGEROUS_EXTENSIONS.has(extension)) {
+            throw new StorageValidationError(`Files with .${extension} extension are blocked.`);
+        }
+        if (!config.allowedExtensions.has(extension)) {
+            throw new StorageValidationError(`.${extension} is not allowed for this storage path.`);
+        }
+        const filename = buildGeneratedFilename(extension);
+        const datePrefix = getDatePrefix();
+        const prefixWithDate = `${datePrefix}/${config.prefix}`;
+        const key = buildObjectKey(prefixWithDate, filename);
+        const finalContentType = contentType ?? detected?.mime ?? getContentTypeFromFilename(filename);
+        await client.send(new PutObjectCommand({
+            Bucket: bucket,
+            Key: key,
+            Body: file,
+            ContentType: finalContentType,
+        }));
+        return {
+            bucket,
+            key,
+            filename,
+            extension,
+            contentType: finalContentType,
+        };
+    }
+    async function upload(file) {
+        const normalized = await normalizeUploadFile(file);
+        const extension = normalized.filename ? getExtension(normalized.filename) : "";
+        if (!extension) {
+            throw new StorageValidationError("Could not determine file extension for upload(). Provide a File with a filename or detectable content.");
+        }
+        const pathName = extensionToPath.get(extension);
+        if (!pathName) {
+            throw new StorageValidationError(`No storage path configured for .${extension} files.`);
+        }
+        const config = getPathConfig(normalizedPaths, pathName);
+        const resolved = await resolveUploadTarget({
+            allowedExtensions: config.allowedExtensions,
+            body: normalized.body,
+            requestedFilename: normalized.filename,
+            sourceFilename: normalized.filename,
+            sourceContentType: normalized.contentType,
+        });
+        const datePrefix = getDatePrefix();
+        const prefixWithDate = `${datePrefix}/${config.prefix}`;
+        const key = buildObjectKey(prefixWithDate, resolved.filename);
+        await client.send(new PutObjectCommand({
+            Bucket: bucket,
+            Key: key,
+            Body: normalized.body,
+            ContentType: resolved.contentType,
+        }));
+        return {
+            bucket,
+            key,
+            filename: resolved.filename,
+            extension: resolved.extension,
+            contentType: resolved.contentType,
+        };
+    }
+    async function remove(key) {
+        const normalizedKey = normalizeObjectKeyInput(key);
+        await client.send(new DeleteObjectCommand({
+            Bucket: bucket,
+            Key: normalizedKey,
+        }));
+    }
+    function getUrl(key) {
+        const normalizedKey = normalizeObjectKeyInput(key);
+        const endpoint = region === 'us-east-1'
+            ? `https://${bucket}.s3.amazonaws.com`
+            : `https://${bucket}.s3.${region}.amazonaws.com`;
+        return `${endpoint}/${encodeObjectKey(normalizedKey)}`;
+    }
+    return {
+        put,
+        upload,
+        remove,
+        getUrl,
+    };
+}
+function normalizePathConfigs(categories) {
+    return Object.fromEntries(Object.entries(categories).map(([name, extensions]) => [
+        name,
+        {
+            prefix: normalizeCategoryPrefix(name),
+            allowedExtensions: new Set(extensions.map(normalizeExtension)),
+        },
+    ]));
+}
+function getPathConfig(paths, path) {
+    const config = paths[path];
+    if (!config) {
+        throw new StorageValidationError(`Unknown storage path: ${path}`);
+    }
+    return config;
+}
+async function resolveUploadTarget(input) {
+    const requestedExtension = input.requestedFilename
+        ? getExtension(input.requestedFilename)
+        : "";
+    const sourceExtension = input.sourceFilename ? getExtension(input.sourceFilename) : "";
+    const detected = await fileTypeFromBuffer(input.body);
+    const extension = detected?.ext || requestedExtension || sourceExtension;
+    if (!extension) {
+        throw new StorageValidationError("Could not determine file extension. Pass a File object or provide filename explicitly.");
+    }
+    if (DANGEROUS_EXTENSIONS.has(extension)) {
+        throw new StorageValidationError(`Files with .${extension} extension are blocked.`);
+    }
+    if (!input.allowedExtensions.has(extension)) {
+        throw new StorageValidationError(`.${extension} is not allowed for this storage path.`);
+    }
+    if (detected) {
+        if (requestedExtension && requestedExtension !== detected.ext) {
+            throw new StorageValidationError(`File content does not match the requested extension .${requestedExtension}.`);
+        }
+        if (sourceExtension && sourceExtension !== detected.ext) {
+            throw new StorageValidationError(`File content does not match the source extension .${sourceExtension}.`);
+        }
+        const expectedMime = getContentTypeFromFilename(`file.${extension}`);
+        if (expectedMime && detected.mime !== expectedMime) {
+            throw new StorageValidationError(`File content does not match the expected MIME type for .${extension}.`);
+        }
+        return {
+            extension,
+            filename: buildGeneratedFilename(extension),
+            contentType: detected.mime,
+        };
+    }
+    if (TEXT_EXTENSIONS.has(extension) && isLikelyUtf8Text(input.body)) {
+        return {
+            extension,
+            filename: buildGeneratedFilename(extension),
+            contentType: input.sourceContentType ?? getContentTypeFromFilename(`file.${extension}`),
+        };
+    }
+    throw new StorageValidationError(`Unable to validate file contents for .${extension}.`);
+}
+function buildObjectKey(prefix, filename, customKey) {
+    const target = customKey ? customKey.trim() : sanitizeFilename(filename);
+    if (!target) {
+        throw new StorageValidationError("A valid filename or key is required.");
+    }
+    const normalizedTarget = normalizeObjectKeyInput(target);
+    return ensureKeyInsidePrefix(prefix, normalizedTarget);
+}
+function ensureKeyInsidePrefix(prefix, key) {
+    const normalizedKey = normalizeObjectKeyInput(key);
+    if (!prefix) {
+        return normalizedKey;
+    }
+    if (normalizedKey === prefix || normalizedKey.startsWith(`${prefix}/`)) {
+        return normalizedKey;
+    }
+    return `${prefix}/${normalizedKey}`;
+}
+function normalizeCategoryPrefix(prefix) {
+    const normalizedPrefix = normalizeObjectKeyInput(prefix);
+    if (normalizedPrefix === ".") {
+        throw new StorageValidationError("Category prefix must not be a current-directory segment.");
+    }
+    return normalizedPrefix;
+}
+function normalizeObjectKeyInput(key) {
+    const collapsedKey = stripLeadingSlash(key.trim().replace(/\\/g, "/")).replace(/\/+/g, "/");
+    if (!collapsedKey) {
+        throw new StorageValidationError("Object key is required.");
+    }
+    const segments = collapsedKey.split("/");
+    if (segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
+        throw new StorageValidationError("Object key contains invalid path segments.");
+    }
+    return segments.join("/");
+}
+function stripLeadingSlash(value) {
+    return value.replace(/^\/+/, "");
+}
+function getExtension(filename) {
+    const match = /\.([a-z0-9]+)$/i.exec(filename.trim());
+    return match ? normalizeExtension(match[1]) : "";
+}
+function normalizeExtension(extension) {
+    return extension.replace(/^\./, "").trim().toLowerCase();
+}
+function sanitizeFilename(filename) {
+    return filename
+        .trim()
+        .replace(/[<>:"\\|?*\u0000-\u001f]/g, "-")
+        .replace(/\s+/g, "-")
+        .replace(/\/+/g, "-");
+}
+function encodeObjectKey(key) {
+    return stripLeadingSlash(key)
+        .split("/")
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+}
+function getContentTypeFromFilename(filename) {
+    const mime = lookupMimeType(filename);
+    return typeof mime === "string" ? mime : undefined;
+}
+async function normalizeUploadFile(file) {
+    const body = Buffer.from(await file.arrayBuffer());
+    const contentType = file.type || undefined;
+    const filename = typeof file.name === "string" ? file.name : undefined;
+    return { body, filename, contentType };
+}
+function isLikelyUtf8Text(buffer) {
+    if (buffer.length === 0) {
+        return true;
+    }
+    let suspicious = 0;
+    for (const byte of buffer) {
+        const isControl = byte < 0x09 || (byte > 0x0d && byte < 0x20);
+        if (isControl) {
+            suspicious += 1;
+        }
+    }
+    return suspicious / buffer.length < 0.02;
+}
+function buildGeneratedFilename(extension) {
+    return `${randomUUID()}.${extension}`;
+}
+function getDatePrefix() {
+    const now = new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, '0');
+    const date = String(now.getDate()).padStart(2, '0');
+    return `${year}-${month}-${date}`;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "secure-s3-storage",
+  "version": "1.0.1",
+  "description": "S3-backed storage module with automatic file validation",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "keywords": [
+    "s3",
+    "storage",
+    "secure",
+    "upload",
+    "typescript"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.1054.0",
+    "file-type": "^22.0.1",
+    "mime-types": "^3.0.2"
+  },
+  "devDependencies": {
+    "@types/mime-types": "^3.0.1",
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3"
+  }
+}