s3kit 0.1.0

package/README.md

@@ -0,0 +1,398 @@
+# s3kit
+
+A secure, server-driven, framework-agnostic S3 file manager with a React UI.
+
+Package modules:
+
+- `core`: S3 operations (virtual folders, pagination, presigned uploads, previews)
+- `http`: thin HTTP handler (maps requests to core)
+- `adapters/*`: framework adapters (Express, Next.js, Fetch/Remix)
+- `client`: browser helper (typed API calls + multi-file upload orchestration)
+
+## Install
+
+```bash
+npm i s3kit
+```
+
+## Quickstart (local testing)
+
+This repo includes a working Next.js example with a customizer UI and live preview.
+
+### 1) Set up the Next.js example
+
+```bash
+cd examples/nextjs-app
+
+# Copy environment template and configure
+cp .env.example .env
+```
+
+Edit `.env` with your S3 credentials:
+
+```env
+AWS_REGION=us-east-1
+S3_BUCKET=your-bucket-name
+S3_ROOT_PREFIX=dev  # optional, keeps test files under dev/
+```
+
+Then run:
+
+```bash
+npm install
+npm run dev
+```
+
+Open `http://localhost:3000`
+
+### 2) Configure S3 CORS (required for browser uploads)
+
+Uploads use presigned `PUT` URLs, which means the browser uploads directly to S3.
+
+Your bucket must allow CORS from your UI origin (example: `http://localhost:3000`) with:
+
+- `PUT` (uploads)
+- `GET` (previews)
+- `HEAD` (often used by browsers)
+
+Example CORS configuration:
+
+```json
+[
+  {
+    "AllowedOrigins": ["http://localhost:3000"],
+    "AllowedMethods": ["GET", "PUT", "HEAD", "OPTIONS"],
+    "AllowedHeaders": ["*"],
+    "ExposeHeaders": ["ETag"]
+  }
+]
+```
+
+If uploads still fail with a CORS error:
+
+- Confirm the UI origin matches exactly (scheme, host, and port).
+- Ensure the bucket CORS rules are applied to the correct bucket.
+- Include `OPTIONS` and `PUT` in `AllowedMethods` (preflight + upload).
+- If you set custom headers in `prepareUploads`, include them in `AllowedHeaders`.
+
+## Credentials and security
+
+- S3 credentials must be configured on the server (Node).
+- Do not put credentials in the browser app.
+- Credentials are read from environment variables or AWS SDK defaults.
+
+## Server-side (core)
+
+```ts
+import { S3Client } from '@aws-sdk/client-s3';
+import { S3FileManager } from 's3kit/core';
+
+const s3 = new S3Client({ region: process.env.AWS_REGION });
+
+const manager = new S3FileManager(s3, {
+  bucket: process.env.S3_BUCKET!,
+  rootPrefix: 'uploads',
+  authorizationMode: 'deny-by-default',
+  hooks: {
+    authorize: ({ ctx }) => Boolean(ctx.userId),
+    allowAction: ({ action, path }) => {
+      if (action === 'file.delete') return false;
+      if (path && path.startsWith('private/')) return false;
+      return true;
+    }
+  }
+});
+```
+
+`authorize` returning `false` responds with a 401. `allowAction` returning `false` responds with a 403. `authorizationMode` defaults to `deny-by-default`.
+
+### Authorization hooks (agnostic)
+
+Use `authorize` for auth checks and `allowAction` for per-action rules. Both hooks are optional, but with the default `deny-by-default`, you must provide at least one.
+
+Example: API key auth (framework-agnostic)
+
+```ts
+const manager = new S3FileManager(s3, {
+  bucket: process.env.S3_BUCKET!,
+  authorizationMode: 'deny-by-default',
+  hooks: {
+    authorize: ({ ctx }) => ctx.apiKey === process.env.FILE_MANAGER_API_KEY
+  }
+});
+```
+
+### S3-compatible endpoints (MinIO, LocalStack, R2, Spaces, Wasabi, ...)
+
+You can point the AWS SDK client at an S3-compatible endpoint:
+
+```ts
+const s3 = new S3Client({
+  region: process.env.AWS_REGION,
+  endpoint: process.env.S3_ENDPOINT,
+  forcePathStyle: process.env.S3_FORCE_PATH_STYLE === '1'
+});
+```
+
+### Virtual folder listing + pagination
+
+```ts
+const page1 = await manager.list({ path: '', limit: 100 }, { userId: '123' });
+const page2 = await manager.list({ path: '', cursor: page1.nextCursor, limit: 100 }, { userId: '123' });
+```
+
+## HTTP layer
+
+The HTTP handler expects JSON `POST` requests.
+
+Routes:
+
+- `POST /list`
+- `POST /search`
+- `POST /folder/create`
+- `POST /folder/delete`
+- `POST /files/delete`
+- `POST /files/copy`
+- `POST /files/move`
+- `POST /upload/prepare`
+- `POST /preview`
+
+Notes:
+
+- `POST /search` returns file entries in stable, S3 listing order (lexicographic by key/path) so pagination via `cursor` is deterministic.
+- `cursor` is the underlying S3 continuation token; pass `nextCursor` from the previous response to fetch the next page.
+
+### Next.js (App Router) adapter
+
+```ts
+// app/api/s3/[...path]/route.ts
+import { createNextRouteHandlerFromEnv } from 's3kit/adapters/next';
+
+export const POST = createNextRouteHandlerFromEnv({
+  basePath: '/api/s3',
+  authorization: {
+    mode: 'allow-by-default'
+  },
+  env: {
+    region: 'AWS_REGION',
+    bucket: 'S3_BUCKET',
+    rootPrefix: 'S3_ROOT_PREFIX',
+    endpoint: 'S3_ENDPOINT',
+    forcePathStyle: 'S3_FORCE_PATH_STYLE',
+    requireUserId: 'REQUIRE_USER_ID'
+  }
+});
+```
+
+This helper reads env values from the map above. At minimum, `region` and `bucket`
+must point to defined env vars. For production, replace the example `allow-by-default`
+with your own `authorize` / `allowAction` hooks.
+
+### Express adapter
+
+```ts
+import express from 'express';
+import { createExpressS3FileManagerHandler } from 's3kit/adapters/express';
+
+const app = express();
+app.use(express.json({ limit: '2mb' }));
+
+app.use(
+  '/api/s3',
+  createExpressS3FileManagerHandler({
+    manager,
+    getContext: (req) => ({ userId: req.header('x-user-id') ?? undefined }),
+    api: { basePath: '/api/s3' }
+  })
+);
+
+app.listen(3001);
+```
+
+### Fetch/Remix adapter
+
+```ts
+import { createFetchHandler } from 's3kit/adapters/fetch';
+
+export const handler = createFetchHandler({
+  manager,
+  getContext: async (req) => ({ userId: req.headers.get('x-user-id') ?? undefined }),
+  api: { basePath: '/api/s3' }
+});
+```
+
+## Client helper
+
+```ts
+import { S3FileManagerClient } from 's3kit/client';
+
+const client = new S3FileManagerClient({
+  apiUrl: '/api/s3'
+});
+
+const listing = await client.list({ path: '' });
+
+const preview = await client.getPreviewUrl({ path: 'docs/readme.pdf', inline: true });
+
+await client.uploadFiles({
+  files: [
+    { file: someFile, path: `docs/${someFile.name}` },
+    { file: otherFile, path: `docs/${otherFile.name}` }
+  ],
+  hooks: {
+    onUploadProgress: ({ path, loaded, total }) => {
+      console.log(path, loaded, total);
+    }
+  }
+});
+```
+
+### Alternative client config
+
+If you prefer splitting origin + mount path:
+
+```ts
+const client = new S3FileManagerClient({
+  baseUrl: 'http://localhost:3000',
+  basePath: '/api/s3'
+});
+```
+
+## Multiple S3 configs (multiple API endpoints)
+
+For multi-bucket / multi-environment setups, keep configs on the server and expose them as separate API endpoints.
+
+- The client simply points to the right `apiUrl` (e.g. `/api/s3` vs `/api/s3-media`).
+- The server routes each endpoint to its own `S3FileManager` instance.
+
+Example (framework-agnostic `http` handler):
+
+```ts
+import { createS3FileManagerHttpHandler } from 's3kit/http';
+
+export const s3Handler = createS3FileManagerHttpHandler({
+  getManager: () => managers.default,
+  api: { basePath: '/api/s3' }
+});
+
+export const mediaHandler = createS3FileManagerHttpHandler({
+  getManager: () => managers.media,
+  api: { basePath: '/api/s3-media' }
+});
+```
+
+## React embed examples
+
+### Common UI props
+
+- `theme`: `'light' | 'dark' | 'system'`
+- `mode`: `'viewer' | 'picker' | 'manager'`
+- `selection`: `'single' | 'multiple'`
+- `toolbar`: `{ search, breadcrumbs, viewSwitcher, sort }`
+- `labels`: text overrides for buttons and placeholders
+- `viewMode`: `'grid' | 'list'`
+
+The React UI is styled with CSS variables + CSS modules to keep styles scoped.
+
+### 1) Viewer (read-only file browser)
+
+```tsx
+import { FileManager } from 's3kit/react';
+
+export function FileViewer() {
+  return (
+    <FileManager
+      apiUrl="/api/s3"
+      mode="viewer"
+      allowActions={{ upload: false, createFolder: false, delete: false, rename: false, move: false, copy: false, restore: false }}
+    />
+  );
+}
+```
+
+### 2) Picker (select one or many files)
+
+```tsx
+import { FilePicker } from 's3kit/react';
+
+export function FileField() {
+  return (
+    <FilePicker
+      apiUrl="/api/s3"
+      selection="single"
+      onConfirm={(entries) => {
+        const file = entries[0];
+        console.log('Selected:', file);
+      }}
+      onSelectionChange={(entries) => {
+        console.log('Current selection:', entries);
+      }}
+      confirmLabel="Use file"
+      allowActions={{ upload: true, createFolder: true }}
+    />
+  );
+}
+```
+
+### 3) Manager (full CRUD)
+
+```tsx
+import { FileManager } from 's3kit/react';
+
+export function FileManagerAdmin() {
+  return (
+    <FileManager
+      apiUrl="/api/s3"
+      mode="manager"
+      selection="multiple"
+      allowActions={{
+        upload: true,
+        createFolder: true,
+        delete: true,
+        rename: true,
+        move: true,
+        copy: true,
+        restore: true
+      }}
+    />
+  );
+}
+```
+
+### UI customization (toolbar + labels)
+
+```tsx
+import { FileManager } from 's3kit/react';
+
+export function FileManagerCustomized() {
+  return (
+    <FileManager
+      apiUrl="/api/s3"
+      toolbar={{ search: false, breadcrumbs: true, viewSwitcher: true, sort: false }}
+      labels={{
+        upload: 'Add files',
+        newFolder: 'Create folder',
+        delete: 'Remove',
+        deleteForever: 'Remove forever',
+        restore: 'Restore',
+        emptyTrash: 'Clear trash',
+        confirm: 'Select',
+        searchPlaceholder: 'Search...'
+      }}
+      viewMode="grid"
+    />
+  );
+}
+```
+
+## Example
+
+- `examples/nextjs-app`: Next.js App Router example with a customizer panel and live preview
+
+## Security checklist
+
+- Keep S3 credentials on the server only.
+- Require auth on the API route (session/JWT/API key).
+- Use `deny-by-default` and implement `authorize` / `allowAction`.
+- Enforce least-privilege IAM policies for the bucket.
+- Validate inputs (paths, allowed actions) and consider rate limiting.

package/dist/adapters/express.cjs

@@ -0,0 +1,305 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/adapters/express.ts
+var express_exports = {};
+__export(express_exports, {
+  createExpressS3FileManagerHandler: () => createExpressS3FileManagerHandler
+});
+module.exports = __toCommonJS(express_exports);
+
+// src/core/errors.ts
+var S3FileManagerAuthorizationError = class extends Error {
+  status;
+  code;
+  constructor(message, status, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+};
+
+// src/http/handler.ts
+var S3FileManagerHttpError = class extends Error {
+  status;
+  code;
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+};
+function normalizeBasePath(basePath) {
+  if (!basePath) return "";
+  if (basePath === "/") return "";
+  return basePath.startsWith("/") ? basePath.replace(/\/+$/, "") : `/${basePath.replace(/\/+$/, "")}`;
+}
+function jsonError(status, code, message) {
+  return {
+    status,
+    headers: { "content-type": "application/json" },
+    body: {
+      error: {
+        code,
+        message
+      }
+    }
+  };
+}
+function ensureObject(body) {
+  if (body && typeof body === "object" && !Array.isArray(body))
+    return body;
+  throw new S3FileManagerHttpError(400, "invalid_body", "Expected JSON object body");
+}
+function optionalString(value, key) {
+  if (value === void 0) return void 0;
+  if (typeof value === "string") return value;
+  throw new S3FileManagerHttpError(400, "invalid_body", `Expected '${key}' to be a string`);
+}
+function requiredString(value, key) {
+  if (typeof value === "string") return value;
+  throw new S3FileManagerHttpError(400, "invalid_body", `Expected '${key}' to be a string`);
+}
+function optionalNumber(value, key) {
+  if (value === void 0) return void 0;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  throw new S3FileManagerHttpError(400, "invalid_body", `Expected '${key}' to be a finite number`);
+}
+function optionalBoolean(value, key) {
+  if (value === void 0) return void 0;
+  if (typeof value === "boolean") return value;
+  throw new S3FileManagerHttpError(400, "invalid_body", `Expected '${key}' to be a boolean`);
+}
+function requiredStringArray(value, key) {
+  if (!Array.isArray(value)) {
+    throw new S3FileManagerHttpError(
+      400,
+      "invalid_body",
+      `Expected '${key}' to be an array of strings`
+    );
+  }
+  for (const item of value) {
+    if (typeof item !== "string") {
+      throw new S3FileManagerHttpError(
+        400,
+        "invalid_body",
+        `Expected '${key}' to be an array of strings`
+      );
+    }
+  }
+  return value;
+}
+function optionalStringRecord(value, key) {
+  if (value === void 0) return void 0;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new S3FileManagerHttpError(
+      400,
+      "invalid_body",
+      `Expected '${key}' to be an object of strings`
+    );
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (typeof v !== "string") {
+      throw new S3FileManagerHttpError(400, "invalid_body", `Expected '${key}.${k}' to be a string`);
+    }
+    out[k] = v;
+  }
+  return out;
+}
+function parseListOptions(body) {
+  const obj = ensureObject(body);
+  return {
+    path: requiredString(obj.path, "path"),
+    cursor: optionalString(obj.cursor, "cursor"),
+    limit: optionalNumber(obj.limit, "limit")
+  };
+}
+function parseSearchOptions(body) {
+  const obj = ensureObject(body);
+  return {
+    query: requiredString(obj.query, "query"),
+    path: optionalString(obj.path, "path"),
+    recursive: optionalBoolean(obj.recursive, "recursive"),
+    limit: optionalNumber(obj.limit, "limit"),
+    cursor: optionalString(obj.cursor, "cursor")
+  };
+}
+function parseCreateFolderOptions(body) {
+  const obj = ensureObject(body);
+  return { path: requiredString(obj.path, "path") };
+}
+function parseDeleteFolderOptions(body) {
+  const obj = ensureObject(body);
+  return {
+    path: requiredString(obj.path, "path"),
+    recursive: optionalBoolean(obj.recursive, "recursive")
+  };
+}
+function parseDeleteFilesOptions(body) {
+  const obj = ensureObject(body);
+  return { paths: requiredStringArray(obj.paths, "paths") };
+}
+function parseCopyMoveOptions(body) {
+  const obj = ensureObject(body);
+  return {
+    fromPath: requiredString(obj.fromPath, "fromPath"),
+    toPath: requiredString(obj.toPath, "toPath")
+  };
+}
+function parsePrepareUploadsOptions(body) {
+  const obj = ensureObject(body);
+  const itemsValue = obj.items;
+  if (!Array.isArray(itemsValue)) {
+    throw new S3FileManagerHttpError(400, "invalid_body", "Expected 'items' to be an array");
+  }
+  const items = itemsValue.map((raw, idx) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new S3FileManagerHttpError(
+        400,
+        "invalid_body",
+        `Expected 'items[${idx}]' to be an object`
+      );
+    }
+    const item = raw;
+    return {
+      path: requiredString(item.path, `items[${idx}].path`),
+      contentType: optionalString(item.contentType, `items[${idx}].contentType`),
+      cacheControl: optionalString(item.cacheControl, `items[${idx}].cacheControl`),
+      contentDisposition: optionalString(
+        item.contentDisposition,
+        `items[${idx}].contentDisposition`
+      ),
+      metadata: optionalStringRecord(item.metadata, `items[${idx}].metadata`)
+    };
+  });
+  return {
+    items,
+    expiresInSeconds: optionalNumber(obj.expiresInSeconds, "expiresInSeconds")
+  };
+}
+function parsePreviewOptions(body) {
+  const obj = ensureObject(body);
+  return {
+    path: requiredString(obj.path, "path"),
+    expiresInSeconds: optionalNumber(obj.expiresInSeconds, "expiresInSeconds"),
+    inline: optionalBoolean(obj.inline, "inline")
+  };
+}
+function createS3FileManagerHttpHandler(options) {
+  const basePath = normalizeBasePath(options.api?.basePath);
+  if (!options.manager && !options.getManager) {
+    throw new Error("createS3FileManagerHttpHandler requires either manager or getManager");
+  }
+  return async (req) => {
+    try {
+      const ctx = await options.getContext?.(req) ?? {};
+      const manager = options.getManager ? await options.getManager(req, ctx) : options.manager;
+      const method = req.method.toUpperCase();
+      const path = req.path.startsWith(basePath) ? req.path.slice(basePath.length) || "/" : req.path;
+      if (method === "POST" && path === "/list") {
+        const out = await manager.list(parseListOptions(req.body), ctx);
+        return { status: 200, headers: { "content-type": "application/json" }, body: out };
+      }
+      if (method === "POST" && path === "/search") {
+        const out = await manager.search(parseSearchOptions(req.body), ctx);
+        return { status: 200, headers: { "content-type": "application/json" }, body: out };
+      }
+      if (method === "POST" && path === "/folder/create") {
+        await manager.createFolder(parseCreateFolderOptions(req.body), ctx);
+        return { status: 204 };
+      }
+      if (method === "POST" && path === "/folder/delete") {
+        await manager.deleteFolder(parseDeleteFolderOptions(req.body), ctx);
+        return { status: 204 };
+      }
+      if (method === "POST" && path === "/files/delete") {
+        await manager.deleteFiles(parseDeleteFilesOptions(req.body), ctx);
+        return { status: 204 };
+      }
+      if (method === "POST" && path === "/files/copy") {
+        await manager.copy(parseCopyMoveOptions(req.body), ctx);
+        return { status: 204 };
+      }
+      if (method === "POST" && path === "/files/move") {
+        await manager.move(parseCopyMoveOptions(req.body), ctx);
+        return { status: 204 };
+      }
+      if (method === "POST" && path === "/upload/prepare") {
+        const out = await manager.prepareUploads(parsePrepareUploadsOptions(req.body), ctx);
+        return { status: 200, headers: { "content-type": "application/json" }, body: out };
+      }
+      if (method === "POST" && path === "/preview") {
+        const out = await manager.getPreviewUrl(parsePreviewOptions(req.body), ctx);
+        return { status: 200, headers: { "content-type": "application/json" }, body: out };
+      }
+      return jsonError(404, "not_found", "Route not found");
+    } catch (err) {
+      if (err instanceof S3FileManagerHttpError) {
+        return jsonError(err.status, err.code, err.message);
+      }
+      if (err instanceof S3FileManagerAuthorizationError) {
+        return jsonError(err.status, err.code, err.message);
+      }
+      console.error("[S3FileManager Error]", err);
+      const message = err instanceof Error ? err.message : "Unknown error";
+      return jsonError(500, "internal_error", message);
+    }
+  };
+}
+
+// src/adapters/express.ts
+function toSingleHeaderValue(val) {
+  if (typeof val === "string") return val;
+  if (Array.isArray(val)) return val.join(",");
+  return void 0;
+}
+function createExpressS3FileManagerHandler(options) {
+  const handler = createS3FileManagerHttpHandler(options);
+  return async (req, res) => {
+    const httpReq = {
+      method: req.method,
+      path: `${req.baseUrl ?? ""}${req.path}`,
+      query: req.query,
+      headers: req.headers,
+      body: req.body
+    };
+    const out = await handler(httpReq);
+    if (out.headers) {
+      for (const [k, v] of Object.entries(out.headers)) {
+        res.setHeader(k, v);
+      }
+    }
+    if (out.status === 204) {
+      res.status(204).end();
+      return;
+    }
+    const ct = toSingleHeaderValue((out.headers ?? {})["content-type"]);
+    if (ct?.includes("application/json")) {
+      res.status(out.status).json(out.body ?? null);
+      return;
+    }
+    res.status(out.status).send(out.body ?? null);
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createExpressS3FileManagerHandler
+});
+//# sourceMappingURL=express.cjs.map