@stacksjs/storage 0.70.88 → 0.70.90

package/dist/image.js

@@ -0,0 +1,29 @@
+let cachedSharp = null;
+async function loadSharp() {
+  if (cachedSharp)
+    return cachedSharp;
+  try {
+    const mod = await import("sharp");
+    cachedSharp = mod.default ?? mod;
+    return cachedSharp;
+  } catch (err) {
+    throw Error(`[storage/image] \`sharp\` is not installed. Image transforms require it as a peer dependency.
+  Install with: \`bun add sharp\`
+  Original load error: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+export function transform(pipeline) {
+  return async (input) => {
+    const sharp = await loadSharp(), bytes = input instanceof ArrayBuffer ? new Uint8Array(input) : input, buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes), img = sharp(buf);
+    return (await pipeline(img)).toBuffer();
+  };
+}
+export function avatar(size = 512, quality = 85) {
+  return transform((img) => img.resize(size, size, { fit: "cover" }).webp({ quality }));
+}
+export function resize(width, height, fit = "inside") {
+  return transform((img) => img.resize(width, height, { fit }));
+}
+export function stripMetadata() {
+  return transform((img) => img);
+}

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+export type { ServeFileOptions } from './static-serve';
+export type { DiskConfig, FilesystemConfig, LocalDiskConfig, S3DiskConfig } from './facade';
+export type { FilenameStrategy, PutFileOptions, UploadedFileLike } from './put-file';
+// Disk-name autocomplete: userland augments `KnownDisks` to get
+// completion on `Storage.disk('…')` (stacksjs/stacks#1924).
+export type { DiskName, KnownDisks } from './types/filesystem';
+export type { SignedTokenVerification } from './signed-url';
+export type { SignedUrlOptions } from './types';
+export type { ParsedDiskPath } from './path-sanitize';
+export type { MimeVerifyResult } from './mime-verify';
+export type { S3PresignedPostInput, S3PresignedPostResult } from './s3-presigned-post';
+export type {
+  GetStreamOptions,
+  PresignedUploadPolicy,
+  PresignedUploadPolicyOptions,
+  PutResult,
+  PutStreamOptions,
+} from './types';
+export * from './copy';
+export * from './delete';
+export * from './files';
+export * from './folders';
+export * from './fs';
+export * from './glob';
+export * from './hash';
+export * from './helpers';
+export * as storage from './storage';
+export * from './zip';
+// Storage adapters and types
+export * from './adapters/index';
+export * from './types';
+export * from './drivers/index';
+// Static asset serving with ETag/Last-Modified/Cache-Control
+export { serveFile } from './static-serve';
+// Laravel-style Storage facade and UploadedFile
+export { Storage, StorageManager } from './facade';
+export { UploadedFile, uploadedFile, uploadedFiles } from './uploaded-file';
+// Filesystem type helpers
+export { configFromEnv, localDisk, s3Disk } from './types/filesystem';
+// Signed-URL helpers (used by Storage.disk('local').signedUrl())
+export {
+  clearRevokedSignedStorageTokens,
+  createSignedStorageToken,
+  isSignedStorageTokenRevoked,
+  revokeSignedStorageToken,
+  verifySignedStorageToken,
+} from './signed-url';
+// Path-sanitization helpers (used internally by S3 presignedUploadUrl;
+// also re-exported so user code can pre-validate input from request
+// bodies and surface 400s with a clean `PathSanitizeError`.)
+export { parseDiskPath, PathSanitizeError, sanitizePresignedDir, sanitizePresignedFilename } from './path-sanitize';
+// MIME re-verification — server-side check that uploaded bytes match
+// the claimed content type. Run this after a presigned upload
+// completes since `Content-Type` on a presigned PUT is caller-attested.
+export { detectMimeFromMagicBytes, verifyUploadedMime } from './mime-verify';
+// S3 presigned-POST policy signer (stacksjs/stacks#1888 Phase B).
+// Exposed as a standalone for callers that have their own S3 client
+// and just need the policy-signing logic; the Storage facade wraps
+// it as `presignedUploadPolicy()`.
+export { signS3PresignedPost } from './s3-presigned-post';

package/dist/index.js

@@ -0,0 +1,27 @@
+export * from "./copy";
+export * from "./delete";
+export * from "./files";
+export * from "./folders";
+export * from "./fs";
+export * from "./glob";
+export * from "./hash";
+export * from "./helpers";
+export * as storage from "./storage";
+export * from "./zip";
+export * from "./adapters";
+export * from "./types";
+export * from "./drivers";
+export { serveFile } from "./static-serve";
+export { Storage, StorageManager } from "./facade";
+export { UploadedFile, uploadedFile, uploadedFiles } from "./uploaded-file";
+export { configFromEnv, localDisk, s3Disk } from "./types/filesystem";
+export {
+  clearRevokedSignedStorageTokens,
+  createSignedStorageToken,
+  isSignedStorageTokenRevoked,
+  revokeSignedStorageToken,
+  verifySignedStorageToken
+} from "./signed-url";
+export { parseDiskPath, PathSanitizeError, sanitizePresignedDir, sanitizePresignedFilename } from "./path-sanitize";
+export { detectMimeFromMagicBytes, verifyUploadedMime } from "./mime-verify";
+export { signS3PresignedPost } from "./s3-presigned-post";

package/dist/mime-verify.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Detect a MIME type from the first chunk of a file. Returns the
+ * detected MIME (e.g. `'image/png'`) or `null` if the bytes don't
+ * match any known signature.
+ *
+ * Intentionally narrow — only the well-known binary formats that
+ * appear in `presignedUploadUrl`'s extension map are detected. Text
+ * formats are not covered because their signatures are ambiguous.
+ */
+export declare function detectMimeFromMagicBytes(bytes: Uint8Array | ArrayBuffer): string | null;
+/**
+ * Verify that a file's actual contents match the claimed content type.
+ * Returns `{ ok, expected, detected }` so callers can branch on the
+ * result and produce useful error messages.
+ *
+ * Reads up to 32 bytes from the file (enough for every signature we
+ * check), then matches against `detectMimeFromMagicBytes`.
+ *
+ * @example
+ * ```ts
+ * // After a presigned upload completes:
+ * const result = await verifyUploadedMime('uploads/avatar.jpg', 'image/jpeg')
+ * if (!result.ok) {
+ *   await Storage.disk().deleteFile('uploads/avatar.jpg')
+ *   return Response.json({ error: 'content type mismatch', ...result }, { status: 400 })
+ * }
+ * ```
+ */
+export declare function verifyUploadedMime(path: string, expectedContentType: string, options?: { disk?: string }): Promise<MimeVerifyResult>;
+/**
+ * MIME re-verification helpers (stacksjs/stacks#1873 S-3).
+ *
+ * Background: `presignedUploadUrl({ contentType })` lets the caller
+ * declare what they're going to upload, and AWS signs the URL against
+ * that exact `Content-Type` header. Nothing checks that the **bytes**
+ * actually match the claim. An attacker who can call your presigned
+ * endpoint can request `image/jpeg` (which derives a `.jpg`
+ * extension), then PUT a JavaScript file. The server only sees
+ * "object exists, contentType was image/jpeg" — but the bytes are
+ * executable.
+ *
+ * These helpers exist so server code can re-detect the MIME from
+ * magic bytes after the upload finishes, and either delete the
+ * mismatched object or surface it as a 400.
+ *
+ * **Limitations** — magic-byte sniffing only works for binary formats
+ * with a well-defined signature. Text-based types (JSON, CSV, plain
+ * text, SVG, HTML) can't be unambiguously detected from the first few
+ * bytes; for those, validate by parsing the content (e.g. try
+ * `JSON.parse` for `application/json`).
+ */
+/**
+ * Result of a magic-byte detection attempt.
+ *
+ * `ok: true` means the bytes match a known signature for the
+ * expected content type. `ok: false` with `detected: null` means the
+ * bytes didn't match any signature this helper knows; `ok: false`
+ * with `detected: string` means the bytes match a *different*
+ * signature than expected (e.g. PNG bytes uploaded as image/jpeg).
+ */
+export declare interface MimeVerifyResult {
+  ok: boolean
+  expected: string
+  detected: string | null
+}

package/dist/mime-verify.js

@@ -0,0 +1,47 @@
+export function detectMimeFromMagicBytes(bytes) {
+  const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  if (view.length < 4)
+    return null;
+  if (view[0] === 137 && view[1] === 80 && view[2] === 78 && view[3] === 71 && view[4] === 13 && view[5] === 10 && view[6] === 26 && view[7] === 10)
+    return "image/png";
+  if (view[0] === 255 && view[1] === 216 && view[2] === 255)
+    return "image/jpeg";
+  if (view[0] === 71 && view[1] === 73 && view[2] === 70 && view[3] === 56)
+    return "image/gif";
+  if (view[0] === 82 && view[1] === 73 && view[2] === 70 && view[3] === 70 && view.length >= 12) {
+    if (view[8] === 87 && view[9] === 69 && view[10] === 66 && view[11] === 80)
+      return "image/webp";
+    if (view[8] === 87 && view[9] === 65 && view[10] === 86 && view[11] === 69)
+      return "audio/wav";
+  }
+  if (view[0] === 37 && view[1] === 80 && view[2] === 68 && view[3] === 70)
+    return "application/pdf";
+  if (view[0] === 80 && view[1] === 75 && (view[2] === 3 || view[2] === 5) && (view[3] === 4 || view[3] === 6))
+    return "application/zip";
+  if (view.length >= 12 && view[4] === 102 && view[5] === 116 && view[6] === 121 && view[7] === 112) {
+    const brand = String.fromCharCode(view[8] ?? 0, view[9] ?? 0, view[10] ?? 0, view[11] ?? 0);
+    if (brand === "avif" || brand === "avis")
+      return "image/avif";
+    if (brand === "heic" || brand === "heix" || brand === "mif1")
+      return "image/heic";
+    return "video/mp4";
+  }
+  if (view[0] === 26 && view[1] === 69 && view[2] === 223 && view[3] === 163)
+    return "video/webm";
+  if (view[0] === 73 && view[1] === 68 && view[2] === 51)
+    return "audio/mpeg";
+  if (view[0] === 255 && (view[1] ?? 0) >= 224)
+    return "audio/mpeg";
+  return null;
+}
+function normalizeContentType(contentType) {
+  return contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+}
+export async function verifyUploadedMime(path, expectedContentType, options = {}) {
+  const { Storage } = await import("./facade"), bytes = await Storage.disk(options.disk).readToUint8Array(path), expected = normalizeContentType(expectedContentType), detected = detectMimeFromMagicBytes(bytes.slice(0, 32));
+  return {
+    ok: detected === expected || detected === "image/jpeg" && (expected === "image/jpg" || expected === "image/pjpeg"),
+    expected,
+    detected
+  };
+}

package/dist/move.d.ts

@@ -0,0 +1,6 @@
+import type { Result } from '@stacksjs/error-handling';
+export declare function move(src: string | string[], dest: string, options?: MoveOptions): Promise<Result<{ message: string }, Error>>;
+export declare function rename(from: string, to: string, options?: MoveOptions): Promise<Result<{ message: string }, Error>>;
+declare interface MoveOptions {
+  overwrite?: boolean
+}

package/dist/move.js

@@ -0,0 +1,55 @@
+import { err, handleError, ok } from "@stacksjs/error-handling";
+import { log } from "@stacksjs/logging";
+import { path } from "@stacksjs/path";
+import { fs } from "./fs";
+export async function move(src, dest, options) {
+  try {
+    if (Array.isArray(src)) {
+      const errors = [], operations = src.map(async (file) => {
+        const from = file, to = path.resolve(dest, path.basename(file)), result = await rename(from, to, options);
+        if (result.isErr) {
+          log.error(result.error);
+          errors.push(result.error);
+        }
+      });
+      await Promise.all(operations);
+      if (errors.length > 0)
+        return err(handleError(errors[0]));
+      return ok({ message: "Files moved successfully" });
+    }
+    const result = await rename(src, dest, options);
+    if (result.isErr) {
+      log.error(result.error);
+      return err(handleError(result.error));
+    }
+    return ok({ message: "File moved successfully" });
+  } catch (error) {
+    return err(handleError(error));
+  }
+}
+export async function rename(from, to, options) {
+  return new Promise((resolve, reject) => {
+    try {
+      const dir = path.dirname(to);
+      if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: !0 });
+      if (!fs.existsSync(from))
+        return reject(err(Error(`File or directory does not exist: ${from}`)));
+      if (fs.existsSync(to)) {
+        if (!options?.overwrite)
+          return reject(err(Error(`File or directory already exists: ${to}`)));
+        fs.rmSync(to, { recursive: !0, force: !0 });
+      }
+      fs.renameSync(from, to);
+      return resolve(ok({ message: "File moved successfully" }));
+    } catch (error) {
+      if (error.code === "ENOENT")
+        log.error(`File or directory does not exist
+
+`, error);
+      else
+        log.error(error);
+      return reject(err(Error(error)));
+    }
+  });
+}

package/dist/path-sanitize.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Sanitize a `dir` parameter for `presignedUploadUrl`. Returns the
+ * cleaned dir on success (trailing slashes stripped, empty string
+ * preserved as-is) or throws `PathSanitizeError` on:
+ *
+ *  - non-string input
+ *  - absolute paths (`/foo`)
+ *  - traversal segments (`..`, `foo/../bar`)
+ *  - null bytes (`foo\0bar`) — these get stripped by some S3 SDKs
+ *    silently
+ *  - control characters (`\r`, `\n`, etc.) — log-injection risk
+ *  - segments outside `[A-Za-z0-9._-]`
+ *
+ * Empty / undefined dir is allowed (it means "write at the root of
+ * the configured prefix").
+ */
+export declare function sanitizePresignedDir(dir: string | undefined): string;
+/**
+ * Sanitize a `filename` parameter for `presignedUploadUrl`. Returns
+ * the cleaned filename on success or throws `PathSanitizeError`.
+ *
+ * Rejects path separators, traversal tokens, null bytes, control
+ * characters, and disallowed characters. Validates the extension
+ * against a strict alphanumeric pattern (no `.exe.jpg` smuggling —
+ * the caller is responsible for matching extension to expected
+ * content type via the contentType the URL was signed for).
+ */
+export declare function sanitizePresignedFilename(filename: string): string;
+/**
+ * Parse a `disk:path` reference used by `Storage.copyAcross()` /
+ * `moveAcross()` (stacksjs/stacks#1888 S-7).
+ *
+ * Format: `<disk>:<path>` where:
+ *   - `<disk>` is an alphanumeric + dash/underscore disk name
+ *   - `<path>` is a storage-relative path (path-traversal /
+ *     null-byte / control-char checks applied)
+ *
+ * Throws {@link PathSanitizeError} on a malformed input — the
+ * cross-disk helpers turn that into a clear "bad source" / "bad
+ * dest" error rather than crashing inside the adapter.
+ *
+ * @example
+ * ```ts
+ * parseDiskPath('s3:user-uploads/foo.jpg')
+ * // → { disk: 's3', path: 'user-uploads/foo.jpg' }
+ * ```
+ */
+export declare function parseDiskPath(input: string): ParsedDiskPath;
+/**
+ * Parsed `disk:path` reference returned by {@link parseDiskPath}.
+ */
+export declare interface ParsedDiskPath {
+  disk: string
+  path: string
+}
+/**
+ * Path-sanitization helpers for storage adapters (stacksjs/stacks#1873).
+ *
+ * Callers of `presignedUploadUrl({ dir, filename })` pass in
+ * caller-controlled strings that get interpolated straight into the
+ * stored key. Without sanitization, `dir: '../../sensitive'` escapes
+ * the intended prefix and `filename: 'foo/bar.exe'` injects a
+ * directory separator — both let a hostile caller (or a confused
+ * authenticated caller) write to objects outside their intended
+ * scope. These helpers reject the dangerous shapes loudly before the
+ * adapter ever signs anything.
+ *
+ * Note: the local/bun adapters already have a defense-in-depth check
+ * via `path.relative()` in `resolvePath()`. The S3 adapter doesn't,
+ * because S3 keys are opaque strings — there's no filesystem `..`
+ * resolution to lean on. That's exactly why we need this layer.
+ */
+/**
+ * Thrown when `sanitizePresignedDir` or `sanitizePresignedFilename`
+ * detects a value that would escape the intended scope. The `reason`
+ * discriminant lets callers distinguish "you passed an absolute path"
+ * from "you passed a null byte" if they want to surface that in error
+ * messages — most callers can just `catch (e: PathSanitizeError)` and
+ * return a 400.
+ */
+export declare class PathSanitizeError extends Error {
+  readonly reason: | 'empty'
+    | 'not-string'
+    | 'absolute-path'
+    | 'traversal'
+    | 'null-byte'
+    | 'control-char'
+    | 'too-long'
+    | 'invalid-char'
+    | 'invalid-extension';
+  constructor(message: string, reason: PathSanitizeError['reason']);
+}

package/dist/path-sanitize.js

@@ -0,0 +1,84 @@
+export class PathSanitizeError extends Error {
+  reason;
+  constructor(message, reason) {
+    super(message);
+    this.name = "PathSanitizeError";
+    this.reason = reason;
+  }
+}
+const MAX_COMPONENT_LENGTH = 255, ALLOWED_DIR_CHAR = /^[A-Za-z0-9._-]+$/, ALLOWED_FILENAME_CHAR = /^[A-Za-z0-9._-]+$/, ALLOWED_EXTENSION = /^[a-z0-9]+$/;
+export function sanitizePresignedDir(dir) {
+  if (dir === void 0 || dir === "")
+    return "";
+  if (typeof dir !== "string")
+    throw new PathSanitizeError(`dir must be a string, got ${typeof dir}`, "not-string");
+  const trimmed = dir.replace(/^\/+/, "").replace(/\/+$/, "");
+  if (dir.startsWith("/"))
+    throw new PathSanitizeError(`dir must not be absolute: '${dir}'`, "absolute-path");
+  if (trimmed === "")
+    return "";
+  if (trimmed.includes("\x00"))
+    throw new PathSanitizeError("dir contains null byte", "null-byte");
+  if (/[\x00-\x1F\x7F]/.test(trimmed))
+    throw new PathSanitizeError("dir contains control character", "control-char");
+  const segments = trimmed.split("/");
+  for (const segment of segments) {
+    if (segment === "" || segment === "." || segment === "..")
+      throw new PathSanitizeError(`dir contains traversal or empty segment: '${dir}'`, "traversal");
+    if (segment.length > MAX_COMPONENT_LENGTH)
+      throw new PathSanitizeError(`dir segment exceeds ${MAX_COMPONENT_LENGTH} chars`, "too-long");
+    if (!ALLOWED_DIR_CHAR.test(segment))
+      throw new PathSanitizeError(`dir segment contains disallowed character: '${segment}'`, "invalid-char");
+  }
+  return segments.join("/");
+}
+export function sanitizePresignedFilename(filename) {
+  if (typeof filename !== "string")
+    throw new PathSanitizeError(`filename must be a string, got ${typeof filename}`, "not-string");
+  if (filename === "")
+    throw new PathSanitizeError("filename must not be empty", "empty");
+  if (filename.length > MAX_COMPONENT_LENGTH)
+    throw new PathSanitizeError(`filename exceeds ${MAX_COMPONENT_LENGTH} chars`, "too-long");
+  if (filename.includes("\x00"))
+    throw new PathSanitizeError("filename contains null byte", "null-byte");
+  if (/[\x00-\x1F\x7F]/.test(filename))
+    throw new PathSanitizeError("filename contains control character", "control-char");
+  if (filename.includes("/") || filename.includes("\\"))
+    throw new PathSanitizeError(`filename must not contain path separators: '${filename}'`, "traversal");
+  if (filename === "." || filename === ".." || filename.startsWith("../") || filename.includes("/.."))
+    throw new PathSanitizeError(`filename contains traversal token: '${filename}'`, "traversal");
+  if (!ALLOWED_FILENAME_CHAR.test(filename))
+    throw new PathSanitizeError(`filename contains disallowed character: '${filename}'`, "invalid-char");
+  const dotIdx = filename.lastIndexOf(".");
+  if (dotIdx > 0 && dotIdx < filename.length - 1) {
+    const ext = filename.slice(dotIdx + 1).toLowerCase();
+    if (!ALLOWED_EXTENSION.test(ext))
+      throw new PathSanitizeError(`filename has invalid extension: '.${ext}'`, "invalid-extension");
+  }
+  return filename;
+}
+const DISK_NAME_RE = /^[a-z0-9_-]+$/i;
+export function parseDiskPath(input) {
+  if (typeof input !== "string" || input.length === 0)
+    throw new PathSanitizeError("disk-path reference is empty", "empty");
+  if (input.includes("\x00"))
+    throw new PathSanitizeError("disk-path reference contains a null byte", "null-byte");
+  const colonIdx = input.indexOf(":");
+  if (colonIdx <= 0 || colonIdx === input.length - 1)
+    throw new PathSanitizeError(`disk-path reference must use '<disk>:<path>' format, got '${input}'`, "invalid-char");
+  const disk = input.slice(0, colonIdx), path = input.slice(colonIdx + 1);
+  if (!DISK_NAME_RE.test(disk))
+    throw new PathSanitizeError(`disk name '${disk}' is invalid (alphanumeric + '-' / '_' only)`, "invalid-char");
+  if (path.startsWith("/") || /^[A-Za-z]:[\\/]/.test(path))
+    throw new PathSanitizeError(`disk-path '${path}' is absolute`, "absolute-path");
+  if (path.includes("\x00"))
+    throw new PathSanitizeError("disk-path contains a null byte", "null-byte");
+  for (let i = 0;i < path.length; i++) {
+    const code = path.charCodeAt(i);
+    if (code < 32 || code === 127)
+      throw new PathSanitizeError(`disk-path contains a control character at index ${i}`, "control-char");
+  }
+  if (path.split(/[/\\]/).some((seg) => seg === ".."))
+    throw new PathSanitizeError(`disk-path '${path}' contains a '..' segment`, "traversal");
+  return { disk, path };
+}

package/dist/put-file.d.ts

@@ -0,0 +1,53 @@
+import type { DiskName } from './types/filesystem';
+import type { PutResult } from './types';
+import type { StorageManager } from './facade';
+export declare function putUploadedFile(manager: StorageManager, file: UploadedFileLike, opts: PutFileOptions): Promise<PutResult & { url: string }>;
+/**
+ * Optional metadata fields shared by every uploaded-file shape we
+ * accept. The `name` / `mimeType` aliases are present so the router's
+ * `UploadedFile` class (which uses the class-style names) flows
+ * through alongside the direct-parse shape (which uses the
+ * snake-style `originalName` / `mimetype`).
+ */
+declare interface UploadedFileMetadata {
+  originalName?: string
+  name?: string
+  mimetype?: string
+  mimeType?: string
+}
+export declare interface PutFileOptions {
+  disk?: DiskName
+  dir?: string
+  filename?: FilenameStrategy
+  preserveExtension?: boolean
+  transform?: (input: Uint8Array | Buffer | ArrayBuffer) => Promise<Uint8Array | Buffer>
+}
+/**
+ * Minimal structural shape for an uploaded file accepted by
+ * `Storage.put(file, opts)`. Modeled as a discriminated union so the
+ * type-checker rejects `Storage.put({})` and similar empty-object
+ * mistakes (stacksjs/stacks#1873 S-13). At least one of `buffer`,
+ * `bytes()`, or `arrayBuffer()` must be present — that's the runtime
+ * contract `readBytes()` enforces with a throw, and now the
+ * structural contract the type system enforces at compile time.
+ *
+ * Two callsites land here in practice (stacksjs/stacks#1856):
+ *
+ *   1. **Direct multipart parse** (the original router shape, before
+ *      bun-router wrapped each entry in an `UploadedFile` class).
+ *      `{ originalName, mimetype, buffer }` — synchronous.
+ *   2. **Router's `UploadedFile` class** (current shape from
+ *      `req.file(key)` / `req.files`). Exposes `name`, `mimeType`, and
+ *      an async `bytes()` / `arrayBuffer()` accessor instead of a
+ *      `buffer` property — Bun's `File` is lazy by design.
+ */
+export type UploadedFileLike = UploadedFileMetadata & (
+  | { buffer: ArrayBuffer | Uint8Array | Buffer, bytes?: () => Promise<Uint8Array>, arrayBuffer?: () => Promise<ArrayBuffer> }
+  | { bytes: () => Promise<Uint8Array>, buffer?: ArrayBuffer | Uint8Array | Buffer, arrayBuffer?: () => Promise<ArrayBuffer> }
+  | { arrayBuffer: () => Promise<ArrayBuffer>, buffer?: ArrayBuffer | Uint8Array | Buffer, bytes?: () => Promise<Uint8Array> }
+);
+/** Built-in filename strategies for `Storage.put(file, { filename })`. */
+export type FilenameStrategy = | 'uuid'
+  | 'hash'
+  | 'original'
+  | ((file: UploadedFileLike) => string);

package/dist/put-file.js

@@ -0,0 +1,85 @@
+const MIME_TO_EXT = {
+  "image/jpeg": "jpg",
+  "image/jpg": "jpg",
+  "image/png": "png",
+  "image/webp": "webp",
+  "image/gif": "gif",
+  "image/svg+xml": "svg",
+  "image/avif": "avif",
+  "application/pdf": "pdf",
+  "application/json": "json",
+  "application/zip": "zip",
+  "application/octet-stream": "bin",
+  "text/plain": "txt",
+  "text/csv": "csv",
+  "text/html": "html",
+  "video/mp4": "mp4",
+  "video/webm": "webm",
+  "audio/mpeg": "mp3",
+  "audio/wav": "wav"
+};
+function extFromOriginalName(name) {
+  if (!name)
+    return null;
+  const idx = name.lastIndexOf(".");
+  if (idx <= 0 || idx === name.length - 1)
+    return null;
+  const ext = name.slice(idx + 1).toLowerCase();
+  if (!/^[a-z0-9]+$/.test(ext))
+    return null;
+  return ext;
+}
+function originalNameOf(file) {
+  return file.originalName ?? file.name;
+}
+function mimetypeOf(file) {
+  return file.mimetype ?? file.mimeType;
+}
+function deriveExtension(file) {
+  const mime = mimetypeOf(file);
+  return extFromOriginalName(originalNameOf(file)) ?? (mime && MIME_TO_EXT[mime.toLowerCase()]) ?? null;
+}
+async function readBytes(file) {
+  if (file.buffer !== void 0)
+    return file.buffer;
+  if (typeof file.bytes === "function")
+    return await file.bytes();
+  if (typeof file.arrayBuffer === "function")
+    return await file.arrayBuffer();
+  throw Error("UploadedFile is missing both `buffer` and `bytes()`/`arrayBuffer()` accessors \u2014 cannot read file contents.");
+}
+function bufferLikeToHash(buffer) {
+  const view = buffer instanceof ArrayBuffer ? new Uint8Array(buffer) : buffer, hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(view);
+  return hasher.digest("hex").slice(0, 32);
+}
+function sanitizeOriginalName(name) {
+  return name.replace(/[/\\]/g, "_").replace(/\.{2,}/g, "_").replace(/[^A-Za-z0-9._-]/g, "_").replace(/_+/g, "_");
+}
+async function resolveFilename(file, strategy) {
+  if (typeof strategy === "function")
+    return strategy(file);
+  switch (strategy) {
+    case "uuid":
+      return crypto.randomUUID().replace(/-/g, "");
+    case "hash": {
+      const bytes = await readBytes(file);
+      return bufferLikeToHash(bytes);
+    }
+    case "original": {
+      const name = originalNameOf(file);
+      return name ? sanitizeOriginalName(name) : crypto.randomUUID().replace(/-/g, "");
+    }
+  }
+}
+function joinPath(...parts) {
+  return parts.filter(Boolean).map((p, i) => i === 0 ? p.replace(/\/+$/, "") : p.replace(/^\/+/, "").replace(/\/+$/, "")).filter(Boolean).join("/");
+}
+export async function putUploadedFile(manager, file, opts) {
+  const disk = manager.disk(opts.disk), baseName = await resolveFilename(file, opts.filename ?? "uuid"), wantExt = opts.preserveExtension !== !1, baseHasExt = /\.[A-Za-z0-9]+$/.test(baseName), ext = wantExt && !baseHasExt ? deriveExtension(file) : null, finalName = ext ? `${baseName}.${ext}` : baseName, fullPath = joinPath(opts.dir ?? "", finalName), raw = await readBytes(file);
+  let contents = raw instanceof ArrayBuffer ? new Uint8Array(raw) : raw;
+  if (opts.transform)
+    contents = await opts.transform(contents);
+  const written = await disk.write(fullPath, contents), url = await disk.publicUrl(fullPath);
+  return { ...written, path: fullPath, url };
+}

package/dist/s3-presigned-post.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Build + sign an S3 presigned-POST policy.
+ *
+ * @example
+ * ```ts
+ * const post = signS3PresignedPost({
+ *   bucket: 'app-uploads',
+ *   region: 'us-east-1',
+ *   credentials: { accessKeyId, secretAccessKey },
+ *   key: { startsWith: 'avatars/' },
+ *   contentType: { startsWith: 'image/' },
+ *   contentLengthRange: { min: 0, max: 5 * 1024 * 1024 },
+ *   expiresIn: 3600,
+ * })
+ *
+ * // Browser side:
+ * //   const fd = new FormData()
+ * //   Object.entries(post.fields).forEach(([k, v]) => fd.append(k, v))
+ * //   fd.append('file', file)  // MUST be last
+ * //   await fetch(post.url, { method: 'POST', body: fd })
+ * ```
+ */
+export declare function signS3PresignedPost(input: S3PresignedPostInput): S3PresignedPostResult;
+/**
+ * Inputs to {@link signS3PresignedPost}. Mirrors the
+ * `presignedUploadPolicy()` adapter call once it's wired up.
+ */
+export declare interface S3PresignedPostInput {
+  bucket: string
+  region: string
+  credentials: {
+    accessKeyId: string
+    secretAccessKey: string
+    sessionToken?: string
+  }
+  key: string | { startsWith: string }
+  contentType: string | { startsWith: string }
+  contentLengthRange?: { min: number, max: number }
+  acl?: 'private' | 'public-read' | 'public-read-write' | 'authenticated-read' | 'bucket-owner-read' | 'bucket-owner-full-control'
+  expiresIn: number
+  fields?: Record<string, string>
+}
+/**
+ * What the browser submits. The form is `multipart/form-data` POSTed
+ * to `url`; every key in `fields` becomes a form field with the same
+ * name. The actual file MUST be the LAST field, named `'file'`.
+ */
+export declare interface S3PresignedPostResult {
+  url: string
+  fields: Record<string, string>
+  key: string
+}