@stacksjs/storage 0.70.88 → 0.70.90

package/dist/s3-presigned-post.js

@@ -0,0 +1,68 @@
+import { createHmac } from "node:crypto";
+import { Buffer } from "node:buffer";
+const ALGORITHM = "AWS4-HMAC-SHA256", MIN_EXPIRY = 60, MAX_EXPIRY = 604800;
+function hmac(key, data) {
+  return createHmac("sha256", key).update(data, "utf8").digest();
+}
+function deriveSigningKey(secretAccessKey, dateStamp, region) {
+  const kDate = hmac(`AWS4${secretAccessKey}`, dateStamp), kRegion = hmac(kDate, region), kService = hmac(kRegion, "s3");
+  return hmac(kService, "aws4_request");
+}
+function isoDate(now) {
+  const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, ""), dateStamp = amzDate.slice(0, 8);
+  return { amzDate, dateStamp };
+}
+export function signS3PresignedPost(input) {
+  const expiresIn = Math.floor(input.expiresIn);
+  if (!Number.isFinite(expiresIn) || expiresIn < MIN_EXPIRY || expiresIn > MAX_EXPIRY)
+    throw RangeError(`[storage/s3-post] expiresIn must be between ${MIN_EXPIRY}s and ${MAX_EXPIRY}s (got ${expiresIn}s)`);
+  if (!input.bucket)
+    throw Error("[storage/s3-post] bucket is required");
+  if (!input.credentials?.accessKeyId || !input.credentials?.secretAccessKey)
+    throw Error("[storage/s3-post] credentials.accessKeyId and credentials.secretAccessKey are required");
+  const now = new Date, { amzDate, dateStamp } = isoDate(now), credentialScope = `${dateStamp}/${input.region}/s3/aws4_request`, credentialField = `${input.credentials.accessKeyId}/${credentialScope}`, expirationDate = new Date(now.getTime() + expiresIn * 1000).toISOString().replace(/\.\d{3}Z$/, "Z"), conditions = [];
+  conditions.push({ bucket: input.bucket });
+  if (typeof input.key === "string")
+    conditions.push({ key: input.key });
+  else
+    conditions.push(["starts-with", "$key", input.key.startsWith]);
+  const acl = input.acl ?? "private";
+  conditions.push({ acl });
+  if (typeof input.contentType === "string")
+    conditions.push({ "Content-Type": input.contentType });
+  else
+    conditions.push(["starts-with", "$Content-Type", input.contentType.startsWith]);
+  if (input.contentLengthRange) {
+    if (!Number.isFinite(input.contentLengthRange.min) || input.contentLengthRange.min < 0 || !Number.isFinite(input.contentLengthRange.max) || input.contentLengthRange.max < input.contentLengthRange.min)
+      throw RangeError("[storage/s3-post] contentLengthRange must satisfy 0 <= min <= max");
+    conditions.push(["content-length-range", input.contentLengthRange.min, input.contentLengthRange.max]);
+  }
+  if (input.fields)
+    for (const [k, v] of Object.entries(input.fields))
+      conditions.push({ [k]: v });
+  conditions.push({ "x-amz-credential": credentialField });
+  conditions.push({ "x-amz-algorithm": ALGORITHM });
+  conditions.push({ "x-amz-date": amzDate });
+  if (input.credentials.sessionToken)
+    conditions.push({ "x-amz-security-token": input.credentials.sessionToken });
+  const policy = {
+    expiration: expirationDate,
+    conditions
+  }, policyBase64 = Buffer.from(JSON.stringify(policy), "utf8").toString("base64"), signingKey = deriveSigningKey(input.credentials.secretAccessKey, dateStamp, input.region), signature = createHmac("sha256", signingKey).update(policyBase64, "utf8").digest("hex"), fields = {
+    key: typeof input.key === "string" ? input.key : `${input.key.startsWith}\${filename}`,
+    acl,
+    "Content-Type": typeof input.contentType === "string" ? input.contentType : input.contentType.startsWith,
+    "x-amz-credential": credentialField,
+    "x-amz-algorithm": ALGORITHM,
+    "x-amz-date": amzDate,
+    policy: policyBase64,
+    "x-amz-signature": signature,
+    ...input.credentials.sessionToken ? { "x-amz-security-token": input.credentials.sessionToken } : {},
+    ...input.fields ?? {}
+  };
+  return {
+    url: `https://${input.bucket}.s3.${input.region}.amazonaws.com/`,
+    fields,
+    key: typeof input.key === "string" ? input.key : input.key.startsWith
+  };
+}

package/dist/signed-url.d.ts

@@ -0,0 +1,69 @@
+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/signed-url.js

@@ -0,0 +1,86 @@
+import { Buffer } from "node:buffer";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import process from "node:process";
+const ALG = "HS256";
+function getAppKey() {
+  const k = process.env.APP_KEY;
+  if (!k || k.length < 16) {
+    if (process.env.APP_ENV === "production" || process.env.NODE_ENV === "production")
+      throw Error("[storage/signed-url] APP_KEY is missing or too short (need \u226516 chars). Cannot sign URL.");
+  }
+  return k || "stacks-default-key-dev-only-do-not-use-prod";
+}
+function base64UrlEncode(buf) {
+  return buf.toString("base64url");
+}
+function base64UrlDecode(str) {
+  return Buffer.from(str, "base64url");
+}
+function normalizeExpiry(expiresIn) {
+  if (expiresIn instanceof Date)
+    return Math.floor(expiresIn.getTime() / 1000);
+  return Math.floor(Date.now() / 1000) + Math.floor(expiresIn);
+}
+export function createSignedStorageToken(path, options) {
+  const exp = normalizeExpiry(options.expiresIn), iat = Math.floor(Date.now() / 1000), header = { alg: ALG, typ: "JWT" }, payload = {
+    iss: options.issuer || "stacks",
+    iat,
+    exp,
+    path
+  }, headerPart = base64UrlEncode(Buffer.from(JSON.stringify(header))), payloadPart = base64UrlEncode(Buffer.from(JSON.stringify(payload))), signingInput = `${headerPart}.${payloadPart}`, sig = base64UrlEncode(createHmac("sha256", getAppKey()).update(signingInput).digest());
+  return `${signingInput}.${sig}`;
+}
+const REVOCATION_LIMIT = 1e5, revokedSignatures = new Set;
+function rememberRevoked(sigPart) {
+  if (revokedSignatures.has(sigPart))
+    return;
+  if (revokedSignatures.size >= REVOCATION_LIMIT) {
+    const oldest = revokedSignatures.values().next().value;
+    if (oldest !== void 0)
+      revokedSignatures.delete(oldest);
+  }
+  revokedSignatures.add(sigPart);
+}
+export function revokeSignedStorageToken(token) {
+  if (typeof token !== "string" || token.length === 0)
+    return;
+  const parts = token.split("."), sig = parts.length === 3 ? parts[2] : token;
+  if (sig)
+    rememberRevoked(sig);
+}
+export function isSignedStorageTokenRevoked(sigPart) {
+  return revokedSignatures.has(sigPart);
+}
+export function clearRevokedSignedStorageTokens() {
+  revokedSignatures.clear();
+}
+export function verifySignedStorageToken(token, requestedPath) {
+  if (typeof token !== "string")
+    return { valid: !1, reason: "malformed" };
+  const parts = token.split(".");
+  if (parts.length !== 3)
+    return { valid: !1, reason: "malformed" };
+  const headerPart = parts[0], payloadPart = parts[1], sigPart = parts[2], signingInput = `${headerPart}.${payloadPart}`, expectedSig = createHmac("sha256", getAppKey()).update(signingInput).digest();
+  let providedSig;
+  try {
+    providedSig = base64UrlDecode(sigPart);
+  } catch {
+    return { valid: !1, reason: "malformed" };
+  }
+  if (providedSig.length !== expectedSig.length || !timingSafeEqual(providedSig, expectedSig))
+    return { valid: !1, reason: "bad_signature" };
+  if (revokedSignatures.has(sigPart))
+    return { valid: !1, reason: "revoked" };
+  let claims;
+  try {
+    claims = JSON.parse(base64UrlDecode(payloadPart).toString("utf8"));
+  } catch {
+    return { valid: !1, reason: "malformed" };
+  }
+  const now = Math.floor(Date.now() / 1000);
+  if (typeof claims.exp !== "number" || now >= claims.exp)
+    return { valid: !1, reason: "expired" };
+  if (claims.path !== requestedPath)
+    return { valid: !1, reason: "path_mismatch" };
+  return { valid: !0, claims };
+}

package/dist/static-serve.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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/static-serve.js

@@ -0,0 +1,110 @@
+import { createHash } from "node:crypto";
+import { extname } from "node:path";
+const etagCache = new Map, ETAG_CACHE_MAX = 5000, FINGERPRINTED = /\.[a-f0-9]{8,}\./;
+export async function serveFile(req, filePath, options = {}) {
+  const file = Bun.file(filePath);
+  if (!await file.exists())
+    return new Response("Not Found", { status: 404 });
+  const stat = await file.stat(), mtimeMs = Math.floor(typeof stat.mtimeMs === "number" ? stat.mtimeMs : stat.mtime?.getTime() ?? Date.now()), lastModified = new Date(mtimeMs).toUTCString(), contentType = options.contentType || file.type || guessMime(filePath);
+  let etag;
+  if (options.etag !== !1)
+    etag = await computeEtag(filePath, mtimeMs, file);
+  const ifNoneMatch = req.headers.get("if-none-match");
+  if (etag && ifNoneMatch && stripWeak(ifNoneMatch) === etag)
+    return new Response(null, {
+      status: 304,
+      headers: buildHeaders({ etag, lastModified, contentType, filePath, options, omitContentType: !0 })
+    });
+  const ifModifiedSince = req.headers.get("if-modified-since");
+  if (ifModifiedSince) {
+    const sinceMs = Date.parse(ifModifiedSince);
+    if (!Number.isNaN(sinceMs) && mtimeMs <= sinceMs)
+      return new Response(null, {
+        status: 304,
+        headers: buildHeaders({ etag, lastModified, contentType, filePath, options, omitContentType: !0 })
+      });
+  }
+  return new Response(file, {
+    status: 200,
+    headers: buildHeaders({ etag, lastModified, contentType, filePath, options })
+  });
+}
+function buildHeaders(input) {
+  const h = new Headers;
+  if (!input.omitContentType)
+    h.set("Content-Type", input.contentType);
+  h.set("Last-Modified", input.lastModified);
+  if (input.etag)
+    h.set("ETag", `"${input.etag}"`);
+  h.set("Cache-Control", input.options.cacheControl || pickCacheControl(input.filePath, input.options));
+  h.set("Vary", "Accept-Encoding");
+  return h;
+}
+function pickCacheControl(filePath, options) {
+  if (FINGERPRINTED.test(filePath))
+    return "public, max-age=31536000, immutable";
+  return `public, max-age=${options.defaultMaxAge ?? 300}, must-revalidate`;
+}
+async function computeEtag(filePath, mtimeMs, file) {
+  const cached = etagCache.get(filePath);
+  if (cached && cached.mtimeMs === mtimeMs)
+    return cached.etag;
+  const buf = await file.arrayBuffer(), etag = createHash("sha256").update(new Uint8Array(buf)).digest("hex").slice(0, 16);
+  if (etagCache.size >= ETAG_CACHE_MAX) {
+    const firstKey = etagCache.keys().next().value;
+    if (firstKey !== void 0)
+      etagCache.delete(firstKey);
+  }
+  etagCache.set(filePath, { mtimeMs, etag });
+  return etag;
+}
+function stripWeak(v) {
+  let s = v.trim();
+  if (s.startsWith("W/"))
+    s = s.slice(2);
+  if (s.startsWith('"') && s.endsWith('"'))
+    s = s.slice(1, -1);
+  return s;
+}
+function guessMime(filePath) {
+  switch (extname(filePath).toLowerCase()) {
+    case ".js":
+    case ".mjs":
+    case ".cjs":
+      return "application/javascript; charset=utf-8";
+    case ".css":
+      return "text/css; charset=utf-8";
+    case ".html":
+    case ".htm":
+      return "text/html; charset=utf-8";
+    case ".json":
+      return "application/json; charset=utf-8";
+    case ".svg":
+      return "image/svg+xml";
+    case ".webp":
+      return "image/webp";
+    case ".png":
+      return "image/png";
+    case ".jpg":
+    case ".jpeg":
+      return "image/jpeg";
+    case ".gif":
+      return "image/gif";
+    case ".ico":
+      return "image/x-icon";
+    case ".woff":
+      return "font/woff";
+    case ".woff2":
+      return "font/woff2";
+    case ".ttf":
+      return "font/ttf";
+    case ".txt":
+      return "text/plain; charset=utf-8";
+    case ".wasm":
+      return "application/wasm";
+    case ".map":
+      return "application/json; charset=utf-8";
+    default:
+      return "application/octet-stream";
+  }
+}

package/dist/storage.d.ts

@@ -0,0 +1,9 @@
+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/storage.js

@@ -0,0 +1,9 @@
+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

@@ -0,0 +1,131 @@
+/**
+ * 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 & {});

package/dist/types/filesystem.js

@@ -0,0 +1,40 @@
+export function localDisk(root, options) {
+  return {
+    driver: "local",
+    root,
+    visibility: "private",
+    ...options
+  };
+}
+export function s3Disk(bucket, options) {
+  return {
+    driver: "s3",
+    bucket,
+    region: process.env.AWS_DEFAULT_REGION || "us-east-1",
+    visibility: "private",
+    ...options
+  };
+}
+export function configFromEnv(base = {}) {
+  const env = process.env;
+  return {
+    default: env.FILESYSTEM_DISK || base.default || "local",
+    disks: {
+      ...base.disks,
+      ...env.AWS_ACCESS_KEY_ID && env.AWS_BUCKET ? {
+        s3: {
+          driver: "s3",
+          bucket: env.AWS_BUCKET,
+          region: env.AWS_DEFAULT_REGION || "us-east-1",
+          endpoint: env.AWS_ENDPOINT,
+          url: env.AWS_URL,
+          usePathStyleEndpoint: env.AWS_USE_PATH_STYLE_ENDPOINT === "true",
+          credentials: {
+            key: env.AWS_ACCESS_KEY_ID,
+            secret: env.AWS_SECRET_ACCESS_KEY || ""
+          }
+        }
+      } : {}
+    }
+  };
+}