@stacksjs/storage 0.70.86 → 0.70.88

package/dist/mime-verify.d.ts

@@ -1,65 +0,0 @@
-/**
- * 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/move.d.ts

@@ -1,6 +0,0 @@
-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/path-sanitize.d.ts

@@ -1,92 +0,0 @@
-/**
- * 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/put-file.d.ts

@@ -1,53 +0,0 @@
-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/s3-presigned-post.d.ts

@@ -1,52 +0,0 @@
-/**
- * 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
-}

package/dist/signed-url.d.ts

@@ -1,69 +0,0 @@
-import type { SignedUrlOptions } from './types';
-/**
- * Mint a signed token for the given storage path.
- *
- * @example
- * ```ts
- * const token = createSignedStorageToken('reports/q4.pdf', { expiresIn: 3600 })
- * ```
- */
-export declare function createSignedStorageToken(path: string, options: SignedUrlOptions): string;
-/**
- * Revoke a signed storage token so subsequent
- * {@link verifySignedStorageToken} calls return
- * `{ valid: false, reason: 'revoked' }`. Idempotent — calling
- * twice is a no-op.
- *
- * Pass either the full JWS compact-form token or just the signature
- * segment (the part after the second `.`); both work because
- * verification keys off the signature segment.
- *
- * @example
- * ```ts
- * const url = await Storage.disk('local').signedUrl('reports/q4.pdf', { expiresIn: 3600 })
- * // ... url is shared, then later leaked
- * revokeSignedStorageToken(extractTokenFromUrl(url))
- * // Any further fetch with that URL → 403
- * ```
- */
-export declare function revokeSignedStorageToken(token: string): void;
-/**
- * Check whether a signature has been revoked. Exposed for tests
- * and for distributed-cache replicators that need to peek at the
- * set; production callers should rely on {@link verifySignedStorageToken}
- * to consult this automatically.
- */
-export declare function isSignedStorageTokenRevoked(sigPart: string): boolean;
-/**
- * Test-only: clear the revocation set. The set is process-local
- * and unbounded across tests would let one test's revoke bleed
- * into another's verification.
- */
-export declare function clearRevokedSignedStorageTokens(): void;
-/**
- * Verify a signed storage token. The caller MUST pass the requested
- * path so we can ensure the token's `path` claim matches what the
- * client is trying to fetch — otherwise an attacker could substitute
- * any path in the URL and still pass signature verification.
- *
- * @example
- * ```ts
- * const v = verifySignedStorageToken(req.query.token, requestedPath)
- * if (!v.valid) return new Response('Forbidden', { status: 403 })
- * ```
- */
-export declare function verifySignedStorageToken(token: string, requestedPath: string): SignedTokenVerification;
-declare interface SignedTokenClaims {
-  iss: string
-  iat: number
-  exp: number
-  path: string
-}
-/**
- * Result of verifying a signed token.
- */
-export declare interface SignedTokenVerification {
-  valid: boolean
-  reason?: 'malformed' | 'bad_signature' | 'expired' | 'path_mismatch' | 'revoked'
-  claims?: SignedTokenClaims
-}

package/dist/static-serve.d.ts

@@ -1,37 +0,0 @@
-/**
- * Serve a static file with production-grade cache headers:
- *   - Strong ETag (sha256, first 16 hex chars) computed once per
- *     `(path, mtime)` and cached in-process.
- *   - `Last-Modified` from the file's mtime.
- *   - 304 Not Modified when `If-None-Match` matches OR
- *     `If-Modified-Since` is at-or-after mtime (and ETag didn't mismatch).
- *   - `Cache-Control: public, max-age=31536000, immutable` for paths
- *     that look fingerprinted (e.g. `/_assets/foo.abc12345.js`).
- *   - `Cache-Control: public, max-age=300, must-revalidate` for
- *     everything else.
- *
- * Returns a `404` if the file doesn't exist. Other read errors propagate.
- *
- * @example
- * ```ts
- * import { serveFile } from '@stacksjs/storage'
- * import { resolve } from 'node:path'
- *
- * route.get('/assets/:path', async (req) => {
- *   const url = new URL(req.url)
- *   // url.pathname is e.g. /assets/app.abc12345.js
- *   const filePath = resolve('./public', url.pathname.replace(/^\//, ''))
- *   return serveFile(req, filePath)
- * })
- * ```
- */
-export declare function serveFile(req: Request, filePath: string, options?: ServeFileOptions): Promise<Response>;
-/**
- * Optional knobs for {@link serveFile}.
- */
-export declare interface ServeFileOptions {
-  contentType?: string
-  cacheControl?: string
-  defaultMaxAge?: number
-  etag?: boolean
-}

package/dist/storage.d.ts

@@ -1,9 +0,0 @@
-export * from './copy';
-export * from './delete';
-export * from './files';
-export * from './folders';
-export * from './fs';
-export * from './helpers';
-export * from './move';
-export * from './visibility';
-export * from './zip';

package/dist/types/filesystem.d.ts

@@ -1,131 +0,0 @@
-/**
- * Helper to create a local disk config
- */
-export declare function localDisk(root: string, options?: Partial<Omit<LocalDiskConfig, 'driver' | 'root'>>): LocalDiskConfig;
-/**
- * Helper to create an S3 disk config
- */
-export declare function s3Disk(bucket: string, options?: Partial<Omit<S3DiskConfig, 'driver' | 'bucket'>>): S3DiskConfig;
-/**
- * Create filesystem config from environment variables
- */
-export declare function configFromEnv(base?: Partial<FilesystemConfig>): FilesystemConfig;
-/**
- * Base disk configuration shared by all drivers
- */
-declare interface BaseDiskConfig {
-  name?: string
-  visibility?: Visibility
-  throw?: boolean
-}
-/**
- * Local filesystem disk configuration
- */
-export declare interface LocalDiskConfig extends BaseDiskConfig {
-  driver: 'local'
-  root: string
-  url?: string
-}
-/**
- * S3 disk configuration
- */
-export declare interface S3DiskConfig extends BaseDiskConfig {
-  driver: 's3'
-  bucket: string
-  region?: string
-  prefix?: string
-  endpoint?: string
-  usePathStyleEndpoint?: boolean
-  url?: string
-  credentials?: {
-    key: string
-    secret: string
-  }
-}
-/**
- * Userland-augmentable disk-name registry (stacksjs/stacks#1924).
- *
- * Empty by default — the framework can't know an app's configured
- * disks at its own build time. Apps declare their disks once and get
- * autocomplete on `Storage.disk('…')` everywhere:
- *
- * ```ts
- * // types/storage.d.ts
- * declare module '@stacksjs/storage' {
- *   interface KnownDisks {
- *     local: true
- *     public: true
- *     s3: true
- *   }
- * }
- * ```
- *
- * Mirrors the `DatabaseSchema` pattern from stacksjs/stacks#1923.
- */
-// eslint-disable-next-line ts/no-empty-object-type
-export declare interface KnownDisks {}
-/**
- * Main filesystem configuration
- *
- * @example
- * ```ts
- * const config: FilesystemConfig = {
- *   default: 'local',
- *   disks: {
- *     local: {
- *       driver: 'local',
- *       root: '/storage/app',
- *     },
- *     public: {
- *       driver: 'local',
- *       root: '/public',
- *       url: '/storage',
- *       visibility: 'public',
- *     },
- *     s3: {
- *       driver: 's3',
- *       bucket: 'my-bucket',
- *       region: 'us-east-1',
- *     },
- *   },
- * }
- * ```
- */
-export declare interface FilesystemConfig {
-  default: string
-  disks: Record<string, DiskConfig>
-}
-/**
- * Environment variable mappings for filesystem configuration
- */
-export declare interface FilesystemEnv {
-  FILESYSTEM_DISK?: string
-  AWS_ACCESS_KEY_ID?: string
-  AWS_SECRET_ACCESS_KEY?: string
-  AWS_DEFAULT_REGION?: string
-  AWS_BUCKET?: string
-  AWS_ENDPOINT?: string
-  AWS_URL?: string
-  AWS_USE_PATH_STYLE_ENDPOINT?: string
-}
-/**
- * Filesystem Configuration Types
- *
- * Laravel-style filesystem configuration with clean, typed interfaces.
- * Supports local, public, and S3 disk drivers.
- */
-export type FilesystemDriver = 'local' | 's3';
-export type Visibility = 'public' | 'private';
-/**
- * Union type for all disk configurations
- */
-export type DiskConfig = LocalDiskConfig | S3DiskConfig;
-/**
- * A configured disk name (autocompletes to the keys of an augmented
- * {@link KnownDisks}) or any other string. The `(string & {})` branch
- * keeps the union from collapsing back to `string`, so known disks
- * surface in autocomplete while arbitrary names still type-check —
- * apps that haven't augmented `KnownDisks` keep compiling unchanged.
- */
-// eslint-disable-next-line ts/no-empty-object-type
-export type DiskName = (keyof KnownDisks & string) | (string & {});