@stacksjs/storage 0.70.45 → 0.70.54

package/dist/src/adapters/bun.d.ts

@@ -1,10 +1,12 @@
 import { Buffer } from 'node:buffer';
-import type { ChecksumOptions, DirectoryListing, FileContents, ListOptions, MimeTypeOptions, PublicUrlOptions, SignedUrlOptions, StatEntry, StorageAdapter, StorageAdapterConfig, TemporaryUrlOptions, Visibility } from '../types';
+import type { ChecksumOptions, DirectoryListing, FileContents, GetStreamOptions, ListOptions, MimeTypeOptions, PublicUrlOptions, PutResult, PutStreamOptions, SignedUrlOptions, StatEntry, StorageAdapter, StorageAdapterConfig, TemporaryUrlOptions, Visibility } from '../types';
 export declare function createBunStorage(config?: StorageAdapterConfig): BunStorageAdapter;
 export declare class BunStorageAdapter implements StorageAdapter {
   constructor(config?: StorageAdapterConfig);
-  write(path: string, contents: FileContents): Promise<void>;
+  write(path: string, contents: FileContents): Promise<PutResult>;
   read(path: string): Promise<FileContents>;
+  getStream(path: string, _options?: GetStreamOptions): Promise<ReadableStream<Uint8Array>>;
+  putStream(path: string, stream: ReadableStream<Uint8Array>, options?: PutStreamOptions): Promise<PutResult>;
   readToString(path: string): Promise<string>;
   readToBuffer(path: string): Promise<Buffer>;
   readToUint8Array(path: string): Promise<Uint8Array>;
@@ -15,8 +17,8 @@ export declare class BunStorageAdapter implements StorageAdapter {
   copyFile(from: string, to: string): Promise<void>;
   stat(path: string): Promise<StatEntry>;
   list(path: string, options?: ListOptions): DirectoryListing;
-  changeVisibility(_path: string, _visibility: Visibility): Promise<void>;
-  visibility(_path: string): Promise<Visibility>;
+  changeVisibility(path: string, vis: Visibility): Promise<void>;
+  visibility(path: string): Promise<Visibility>;
   fileExists(path: string): Promise<boolean>;
   directoryExists(path: string): Promise<boolean>;
   publicUrl(path: string, options?: PublicUrlOptions): Promise<string>;

package/dist/src/adapters/index.d.ts

@@ -2,3 +2,5 @@ export * from './local';
 export * from './memory';
 export * from './s3';
 export * from './bun';
+// Per-tenant prefix scoping wrapper (stacksjs/stacks#1887 S-11)
+export * from './scoped';

package/dist/src/adapters/local.d.ts

@@ -1,6 +1,6 @@
 import { Buffer } from 'node:buffer';
 import { copyFile, stat } from 'node:fs/promises';
-import type { ChecksumOptions, DirectoryListing, FileContents, ListOptions, MimeTypeOptions, PublicUrlOptions, SignedUrlOptions, StatEntry, StorageAdapter, StorageAdapterConfig, TemporaryUrlOptions, Visibility } from '../types';
+import type { ChecksumOptions, DirectoryListing, FileContents, GetStreamOptions, ListOptions, MimeTypeOptions, PublicUrlOptions, PutResult, PutStreamOptions, SignedUrlOptions, StatEntry, StorageAdapter, StorageAdapterConfig, TemporaryUrlOptions, Visibility } from '../types';
 /**
  * Create a local storage adapter instance
  */
@@ -10,8 +10,10 @@ export declare function createLocalStorage(config?: StorageAdapterConfig): Local
  */
 export declare class LocalStorageAdapter implements StorageAdapter {
   constructor(config?: StorageAdapterConfig);
-  write(path: string, contents: FileContents): Promise<void>;
+  write(path: string, contents: FileContents): Promise<PutResult>;
   read(path: string): Promise<FileContents>;
+  getStream(path: string, options?: GetStreamOptions): Promise<ReadableStream<Uint8Array>>;
+  putStream(path: string, stream: ReadableStream<Uint8Array>, options?: PutStreamOptions): Promise<PutResult>;
   readToString(path: string): Promise<string>;
   readToBuffer(path: string): Promise<Buffer>;
   readToUint8Array(path: string): Promise<Uint8Array>;
@@ -22,8 +24,8 @@ export declare class LocalStorageAdapter implements StorageAdapter {
   copyFile(from: string, to: string): Promise<void>;
   stat(path: string): Promise<StatEntry>;
   list(path: string, options?: ListOptions): DirectoryListing;
-  changeVisibility(_path: string, _visibility: Visibility): Promise<void>;
-  visibility(_path: string): Promise<Visibility>;
+  changeVisibility(path: string, vis: Visibility): Promise<void>;
+  visibility(path: string): Promise<Visibility>;
   fileExists(path: string): Promise<boolean>;
   directoryExists(path: string): Promise<boolean>;
   publicUrl(path: string, options?: PublicUrlOptions): Promise<string>;

package/dist/src/adapters/memory.d.ts

@@ -1,5 +1,5 @@
 import { Buffer } from 'node:buffer';
-import type { ChecksumOptions, DirectoryListing, FileContents, ListOptions, MimeTypeOptions, PublicUrlOptions, SignedUrlOptions, StatEntry, StorageAdapter, TemporaryUrlOptions, Visibility } from '../types';
+import type { ChecksumOptions, DirectoryListing, FileContents, GetStreamOptions, ListOptions, MimeTypeOptions, PublicUrlOptions, PutResult, PutStreamOptions, SignedUrlOptions, StatEntry, StorageAdapter, TemporaryUrlOptions, Visibility } from '../types';
 /**
  * Create an in-memory storage adapter instance
  */
@@ -9,8 +9,10 @@ export declare function createMemoryStorage(): InMemoryStorageAdapter;
  */
 export declare class InMemoryStorageAdapter implements StorageAdapter {
   constructor();
-  write(path: string, contents: FileContents): Promise<void>;
+  write(path: string, contents: FileContents): Promise<PutResult>;
   read(path: string): Promise<FileContents>;
+  getStream(path: string, _options?: GetStreamOptions): Promise<ReadableStream<Uint8Array>>;
+  putStream(path: string, stream: ReadableStream<Uint8Array>, options?: PutStreamOptions): Promise<PutResult>;
   readToString(path: string): Promise<string>;
   readToBuffer(path: string): Promise<Buffer>;
   readToUint8Array(path: string): Promise<Uint8Array>;

package/dist/src/adapters/s3.d.ts

@@ -1,17 +1,32 @@
 import { Buffer } from 'node:buffer';
-import { S3Client } from '@stacksjs/ts-cloud';
-import type { ChecksumOptions, DirectoryListing, FileContents, ListOptions, MimeTypeOptions, PublicUrlOptions, SignedUrlOptions, StatEntry, StorageAdapter, StorageAdapterConfig, TemporaryUrlOptions, Visibility } from '../types';
+import type { ChecksumOptions, DirectoryListing, FileContents, GetStreamOptions, ListOptions, MimeTypeOptions, PresignedUploadPolicy, PresignedUploadPolicyOptions, PresignedUploadUrl, PresignedUploadUrlOptions, PublicUrlOptions, PutResult, PutStreamOptions, SignedUrlOptions, StatEntry, StorageAdapter, StorageAdapterConfig, TemporaryUrlOptions, Visibility } from '../types';
+import type { S3Client } from '@stacksjs/ts-cloud';
 /**
  * Create an S3 storage adapter instance
  */
-export declare function createS3Storage(client: S3Client, config: StorageAdapterConfig): S3StorageAdapter;
+export declare function createS3Storage(client: S3Client | null, config: StorageAdapterConfig): S3StorageAdapter;
+/**
+ * Append-and-take byte buffer used by the multipart pipeline
+ * (stacksjs/stacks#1886). Holds incoming chunks until they reach
+ * the configured part size, then yields them as a single Uint8Array
+ * via `take(n)` or `flush()`.
+ */
+declare class ChunkBuffer {
+  constructor(_partSize: number);
+  get length(): number;
+  push(c: Uint8Array): void;
+  take(n: number): Uint8Array;
+  flush(): Uint8Array;
+}
 /**
  * AWS S3 storage adapter using ts-cloud S3Client
  */
 export declare class S3StorageAdapter implements StorageAdapter {
-  constructor(client: S3Client, config: StorageAdapterConfig);
-  write(path: string, contents: FileContents): Promise<void>;
+  constructor(client: S3Client | null, config: StorageAdapterConfig);
+  write(path: string, contents: FileContents): Promise<PutResult>;
   read(path: string): Promise<FileContents>;
+  getStream(path: string, _options?: GetStreamOptions): Promise<ReadableStream<Uint8Array>>;
+  putStream(path: string, stream: ReadableStream<Uint8Array>, options?: PutStreamOptions): Promise<PutResult>;
   readToString(path: string): Promise<string>;
   readToBuffer(path: string): Promise<Buffer>;
   readToUint8Array(path: string): Promise<Uint8Array>;
@@ -22,13 +37,15 @@ export declare class S3StorageAdapter implements StorageAdapter {
   copyFile(from: string, to: string): Promise<void>;
   stat(path: string): Promise<StatEntry>;
   list(path: string, options?: ListOptions): DirectoryListing;
-  changeVisibility(_path: string, _visibility: Visibility): Promise<void>;
-  visibility(_path: string): Promise<Visibility>;
+  changeVisibility(path: string, vis: Visibility): Promise<void>;
+  visibility(path: string): Promise<Visibility>;
   fileExists(path: string): Promise<boolean>;
   directoryExists(path: string): Promise<boolean>;
   publicUrl(path: string, options?: PublicUrlOptions): Promise<string>;
   temporaryUrl(path: string, options: TemporaryUrlOptions): Promise<string>;
   signedUrl(path: string, options: SignedUrlOptions): Promise<string>;
+  presignedUploadUrl(options: PresignedUploadUrlOptions): Promise<PresignedUploadUrl>;
+  presignedUploadPolicy(options: PresignedUploadPolicyOptions): Promise<PresignedUploadPolicy>;
   checksum(path: string, options?: ChecksumOptions): Promise<string>;
   mimeType(path: string, _options?: MimeTypeOptions): Promise<string>;
   lastModified(path: string): Promise<number>;

package/dist/src/adapters/scoped.d.ts

@@ -0,0 +1,68 @@
+import type { ChecksumOptions, DirectoryListing, FileContents, GetStreamOptions, ListOptions, MimeTypeOptions, PresignedUploadPolicy, PresignedUploadPolicyOptions, PresignedUploadUrl, PresignedUploadUrlOptions, PublicUrlOptions, PutResult, PutStreamOptions, SignedUrlOptions, StatEntry, StorageAdapter, TemporaryUrlOptions, Visibility } from '../types';
+/**
+ * Convenience factory — most app code reads cleaner with the
+ * function form than `new ScopedStorageAdapter(...)`.
+ *
+ * @example
+ * ```ts
+ * const tenantDisk = scoped(Storage.disk('s3'), { scope: `tenant-${id}` })
+ * ```
+ */
+export declare function scoped(inner: StorageAdapter, options: ScopedAdapterOptions): ScopedStorageAdapter;
+/**
+ * Configuration for a scoped adapter.
+ */
+export declare interface ScopedAdapterOptions {
+  scope: string
+  scopePattern?: RegExp
+}
+/**
+ * Wrap any `StorageAdapter` to scope every operation under a
+ * per-tenant prefix. The wrapped instance presents the same
+ * `StorageAdapter` interface so the session middleware /
+ * `Storage.disk()` / cross-disk copy all work transparently.
+ *
+ * Construction validates the scope against
+ * {@link ScopedAdapterOptions.scopePattern} so a hostile or
+ * malformed tenant id can't escape via `..` segments or path
+ * separators.
+ *
+ * @example
+ * ```ts
+ * const tenantDisk = new ScopedStorageAdapter(
+ *   Storage.disk('s3'),
+ *   { scope: `tenant-${tenantId}` },
+ * )
+ * await tenantDisk.write('avatar.jpg', file)  // → tenant-42/avatar.jpg
+ * ```
+ */
+export declare class ScopedStorageAdapter implements StorageAdapter {
+  constructor(inner: StorageAdapter, options: ScopedAdapterOptions);
+  write(path: string, contents: FileContents): Promise<PutResult>;
+  read(path: string): Promise<FileContents>;
+  readToString(path: string): Promise<string>;
+  readToBuffer(path: string): Promise<Buffer>;
+  readToUint8Array(path: string): Promise<Uint8Array>;
+  deleteFile(path: string): Promise<void>;
+  deleteDirectory(path: string): Promise<void>;
+  createDirectory(path: string): Promise<void>;
+  moveFile(from: string, to: string): Promise<void>;
+  copyFile(from: string, to: string): Promise<void>;
+  stat(path: string): Promise<StatEntry>;
+  list(path: string, options?: ListOptions): DirectoryListing;
+  changeVisibility(path: string, visibility: Visibility): Promise<void>;
+  visibility(path: string): Promise<Visibility>;
+  fileExists(path: string): Promise<boolean>;
+  directoryExists(path: string): Promise<boolean>;
+  publicUrl(path: string, options?: PublicUrlOptions): Promise<string>;
+  temporaryUrl(path: string, options: TemporaryUrlOptions): Promise<string>;
+  signedUrl(path: string, options: SignedUrlOptions): Promise<string>;
+  presignedUploadUrl(options: PresignedUploadUrlOptions): Promise<PresignedUploadUrl>;
+  presignedUploadPolicy(options: PresignedUploadPolicyOptions): Promise<PresignedUploadPolicy>;
+  getStream(path: string, options?: GetStreamOptions): Promise<ReadableStream<Uint8Array>>;
+  putStream(path: string, stream: ReadableStream<Uint8Array>, options?: PutStreamOptions): Promise<PutResult>;
+  checksum(path: string, options?: ChecksumOptions): Promise<string>;
+  mimeType(path: string, options?: MimeTypeOptions): Promise<string>;
+  lastModified(path: string): Promise<number>;
+  fileSize(path: string): Promise<number>;
+}

package/dist/src/facade.d.ts

@@ -1,5 +1,6 @@
-import type { DiskConfig, FilesystemConfig, LocalDiskConfig, S3DiskConfig } from './types/filesystem';
-import type { SignedUrlOptions, StorageAdapter } from './types';
+import type { DiskConfig, DiskName, FilesystemConfig, LocalDiskConfig, S3DiskConfig } from './types/filesystem';
+import type { GetStreamOptions, PresignedUploadPolicy, PresignedUploadPolicyOptions, PresignedUploadUrl, PresignedUploadUrlOptions, PutResult, PutStreamOptions, SignedUrlOptions, StatEntry, StorageAdapter } from './types';
+import type { PutFileOptions, UploadedFileLike } from './put-file';
 export type {
   DiskConfig,
   FilesystemConfig,
@@ -15,8 +16,15 @@ export declare const Storage: StorageManager;
 // =============================================================================
 declare class StorageManager {
   init(config: Partial<FilesystemConfig>): this;
-  disk(name?: string): StorageAdapter;
-  put(path: string, contents: string | Uint8Array | Buffer): Promise<void>;
+  disk(name?: DiskName): StorageAdapter;
+  put(path: string, contents: string | Uint8Array | Buffer): Promise<PutResult>;
+  put(file: UploadedFileLike, opts?: PutFileOptions): Promise<PutResult & { url: string }>;
+  put(pathOrFile: string | UploadedFileLike, contentsOrOpts?: string | Uint8Array | Buffer | PutFileOptions): Promise<PutResult | (PutResult & { url: string })>;
+  stat(path: string): Promise<StatEntry>;
+  getStream(path: string, options?: GetStreamOptions): Promise<ReadableStream<Uint8Array>>;
+  putStream(path: string, stream: ReadableStream<Uint8Array>, options?: PutStreamOptions): Promise<PutResult>;
+  copyAcross(source: string, dest: string): Promise<PutResult>;
+  moveAcross(source: string, dest: string): Promise<PutResult>;
   get(path: string): Promise<string>;
   exists(path: string): Promise<boolean>;
   missing(path: string): Promise<boolean>;
@@ -25,6 +33,8 @@ declare class StorageManager {
   move(from: string, to: string): Promise<void>;
   url(path: string): Promise<string>;
   signedUrl(path: string, options: SignedUrlOptions): Promise<string>;
+  presignedUploadUrl(options: PresignedUploadUrlOptions): Promise<PresignedUploadUrl>;
+  presignedUploadPolicy(options: PresignedUploadPolicyOptions): Promise<PresignedUploadPolicy>;
   size(path: string): Promise<number>;
   lastModified(path: string): Promise<number>;
   mimeType(path: string): Promise<string>;

package/dist/src/image.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Wrap a Sharp pipeline so it composes with
+ * `Storage.put(file, { transform })`. The pipeline function receives a
+ * fresh Sharp instance preloaded with the file's bytes; its return
+ * value is the final pipeline chain (sharp's methods are chainable so
+ * "return img.resize(...)" is the normal shape).
+ *
+ * The wrapper handles the buffer normalisation + final `.toBuffer()`
+ * call so callers don't have to.
+ */
+export declare function transform(pipeline: (img: SharpInstance) => SharpInstance | Promise<SharpInstance>): (input: Uint8Array | Buffer | ArrayBuffer) => Promise<Buffer>;
+/**
+ * Common preset for square avatars — resizes + crops to fit, encodes
+ * as WebP at quality 85. Covers the by-far most common
+ * `Storage.put(file, { transform: ... })` callsite.
+ *
+ * @example
+ * ```ts
+ * import { avatar } from '@stacksjs/storage/image'
+ *
+ * await Storage.put(file, {
+ *   dir: 'avatars',
+ *   transform: avatar(512),
+ * })
+ * ```
+ */
+export declare function avatar(size?: number, quality?: number): (input: Uint8Array | Buffer | ArrayBuffer) => Promise<Buffer>;
+/**
+ * Generic resize preset. `fit` defaults to `'inside'` (preserve aspect
+ * ratio, don't crop) which is the most common non-avatar case.
+ */
+export declare function resize(width: number, height: number, fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside'): (input: Uint8Array | Buffer | ArrayBuffer) => Promise<Buffer>;
+/**
+ * Strip EXIF + colour profile + other embedded metadata. Useful when
+ * accepting user uploads where you don't want to leak GPS coordinates
+ * embedded in phone photos. Pairs well with resize/format presets via
+ * the explicit `transform()` form when needed.
+ *
+ * sharp strips metadata by default unless `withMetadata()` is called;
+ * this preset just makes the intent explicit.
+ */
+export declare function stripMetadata(): (input: Uint8Array | Buffer | ArrayBuffer) => Promise<Buffer>;
+declare interface SharpInstance {
+  toBuffer(): Promise<Buffer>
+  resize: (...args: unknown[]) => SharpInstance
+  jpeg: (...args: unknown[]) => SharpInstance
+  png: (...args: unknown[]) => SharpInstance
+  webp: (...args: unknown[]) => SharpInstance
+  avif: (...args: unknown[]) => SharpInstance
+  gif: (...args: unknown[]) => SharpInstance
+  rotate: (...args: unknown[]) => SharpInstance
+  blur: (...args: unknown[]) => SharpInstance
+  withMetadata: (...args: unknown[]) => SharpInstance
+  [k: string]: unknown
+}

package/dist/src/index.d.ts

@@ -1,7 +1,21 @@
 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';
@@ -24,4 +38,23 @@ 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 { createSignedStorageToken, verifySignedStorageToken } from './signed-url';
+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/src/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/src/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/src/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/src/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
+}