@shaferllc/keel 0.66.0 → 0.74.0

package/dist/core/storage.d.ts

@@ -9,37 +9,119 @@
  *   const bytes = await storage().get("avatars/1.png");
  *   const url = storage().url("avatars/1.png");
  *
+ * Private files get a temporary URL instead of a public one:
+ *
+ *   await storage().signedUrl("invoices/42.pdf", { expiresIn: 300 });
+ *
+ * and browsers can upload straight to the bucket — the bytes never transit the
+ * app — with a signed upload URL:
+ *
+ *   await storage().signedUploadUrl("uploads/raw.mov", { contentType: "video/quicktime" });
+ *
  * Register several disks by name and select one with `storage("s3")`.
  */
-/** The bridge to a storage backend — implement it once per backend. */
+import type { MiddlewareHandler } from "hono";
+/** Whether an object is world-readable or needs a signed URL. */
+export type FileVisibility = "public" | "private";
+/** Per-write options. Disks map these onto their backend's own metadata. */
+export interface WriteOptions {
+    /**
+     * The object's MIME type. Inferred from the path's extension when omitted, so
+     * a `.png` is stored as `image/png` rather than `application/octet-stream`.
+     */
+    contentType?: string;
+    /** A `Cache-Control` value to store alongside the object. */
+    cacheControl?: string;
+    /** `"public"` or `"private"`. Disks that can't express this ignore it. */
+    visibility?: FileVisibility;
+    /** Arbitrary user metadata stored with the object. */
+    metadata?: Record<string, string>;
+}
+/** What a disk knows about a stored object. */
+export interface FileMetadata {
+    size: number;
+    contentType?: string;
+    cacheControl?: string;
+    visibility?: FileVisibility;
+    lastModified?: Date;
+    metadata?: Record<string, string>;
+}
+export interface SignedFileOptions {
+    /** Seconds the URL stays valid. Default: 3600 (one hour). */
+    expiresIn?: number;
+}
+export interface SignedUploadOptions extends SignedFileOptions {
+    /** The `Content-Type` the uploader must send. */
+    contentType?: string;
+}
+/**
+ * The bridge to a storage backend — implement it once per backend.
+ *
+ * The first six methods are required. The rest are optional capabilities: a disk
+ * that can do better than the generic implementation (native `HEAD`, a
+ * server-side copy, backend presigning) implements them, and `Storage` uses them
+ * when present.
+ */
 export interface Disk {
-    put(path: string, bytes: Uint8Array): Promise<void>;
+    put(path: string, bytes: Uint8Array, options?: WriteOptions): Promise<void>;
     get(path: string): Promise<Uint8Array | null>;
     exists(path: string): Promise<boolean>;
     delete(path: string): Promise<void>;
     /** Paths currently stored, optionally filtered to those under `prefix`. */
     list(prefix?: string): Promise<string[]>;
-    /** A URL for the stored object (public or signed — the disk decides). */
+    /** A public URL for the stored object. */
     url(path: string): string;
+    /** Size, content type, and friends. `Storage.metadata()` falls back to a read. */
+    metadata?(path: string): Promise<FileMetadata | null>;
+    /** A server-side copy. `Storage.copy()` falls back to read-then-write. */
+    copy?(from: string, to: string): Promise<void>;
+    /** A server-side move. `Storage.move()` falls back to copy-then-delete. */
+    move?(from: string, to: string): Promise<void>;
+    /**
+     * A backend-presigned read URL (S3/R2 SigV4, GCS, …). When a disk doesn't
+     * implement this, `Storage.signedUrl()` signs the disk's own `url()` with
+     * `config('app.key')` — serve it with `serveStorage({ signed: true })`.
+     */
+    signedUrl?(path: string, options?: SignedFileOptions): Promise<string>;
+    /**
+     * A backend-presigned upload URL, so a browser can `PUT` straight to the
+     * bucket. There is no generic fallback — only the backend can accept the write.
+     */
+    signedUploadUrl?(path: string, options?: SignedUploadOptions): Promise<string>;
 }
 export type Contents = string | Uint8Array | ArrayBuffer;
+/** The MIME type for a path's extension, or `application/octet-stream`. */
+export declare function contentTypeFor(path: string): string;
+/**
+ * Sign a URL with `config('app.key')`, adding `expires` and `signature` query
+ * params. Verify it with `verifyStorageUrl()`.
+ */
+export declare function signStorageUrl(url: string, expiresIn?: number): Promise<string>;
+/** Whether a URL carries a valid, unexpired signature from `signStorageUrl()`. */
+export declare function verifyStorageUrl(url: string): Promise<boolean>;
 /** An in-memory `Disk` — the default; ideal for tests. Not shared across processes. */
 export declare class MemoryDisk implements Disk {
     private baseUrl;
     private files;
     constructor(baseUrl?: string);
-    put(path: string, bytes: Uint8Array): Promise<void>;
+    put(path: string, bytes: Uint8Array, options?: WriteOptions): Promise<void>;
     get(path: string): Promise<Uint8Array | null>;
     exists(path: string): Promise<boolean>;
     delete(path: string): Promise<void>;
     list(prefix?: string): Promise<string[]>;
     url(path: string): string;
+    metadata(path: string): Promise<FileMetadata | null>;
+    copy(from: string, to: string): Promise<void>;
+    move(from: string, to: string): Promise<void>;
 }
 export declare class Storage {
     private disk;
     constructor(disk: Disk);
-    /** Write a file (string, bytes, or ArrayBuffer — strings are UTF-8 encoded). */
-    put(path: string, contents: Contents): Promise<void>;
+    /**
+     * Write a file (string, bytes, or ArrayBuffer — strings are UTF-8 encoded).
+     * The content type is inferred from the extension unless you pass one.
+     */
+    put(path: string, contents: Contents, options?: WriteOptions): Promise<void>;
     /** Read a file's raw bytes, or null if it doesn't exist. */
     get(path: string): Promise<Uint8Array | null>;
     /** Read a file as UTF-8 text, or null if it doesn't exist. */
@@ -47,11 +129,82 @@ export declare class Storage {
     exists(path: string): Promise<boolean>;
     delete(path: string): Promise<void>;
     list(prefix?: string): Promise<string[]>;
+    /** Size, content type, and friends — or null if the file doesn't exist. */
+    metadata(path: string): Promise<FileMetadata | null>;
+    /** A file's size in bytes, or null if it doesn't exist. */
+    size(path: string): Promise<number | null>;
+    /** Copy a file. Server-side when the disk supports it, else read-then-write. */
+    copy(from: string, to: string): Promise<void>;
+    /** Move a file. Server-side when the disk supports it, else copy-then-delete. */
+    move(from: string, to: string): Promise<void>;
+    /** A public URL for the object. Use `signedUrl()` for private ones. */
     url(path: string): string;
+    /**
+     * A temporary URL for a private object. Uses the backend's own presigning when
+     * the disk implements `signedUrl` (S3, R2, GCS); otherwise signs the disk's
+     * `url()` with `config('app.key')` — serve those with `serveStorage({ signed: true })`.
+     */
+    signedUrl(path: string, options?: SignedFileOptions): Promise<string>;
+    /**
+     * A URL the browser can `PUT` the file to directly, so the bytes never transit
+     * your app — the point of this on the edge, where proxying a large upload
+     * through a Worker is exactly what you don't want.
+     *
+     * Only the backend can accept such a write, so this requires a disk that
+     * implements `signedUploadUrl` (see the S3/R2 recipe in the storage guide).
+     */
+    signedUploadUrl(path: string, options?: SignedUploadOptions): Promise<string>;
     /** The underlying driver, for backend-specific operations. */
     get driver(): Disk;
 }
+/**
+ * A `Storage` backed by a `MemoryDisk`, with assertions — what `fakeDisk()`
+ * installs so tests never touch a real bucket.
+ */
+export declare class FakeStorage extends Storage {
+    constructor();
+    assertExists(path: string): Promise<void>;
+    assertMissing(path: string): Promise<void>;
+    /** Assert a file's contents, as UTF-8 text. */
+    assertContents(path: string, expected: string): Promise<void>;
+    /** Assert how many files are stored, optionally under a prefix. */
+    assertCount(expected: number, prefix?: string): Promise<void>;
+}
 /** Register a disk, optionally under a name (default: `"default"`). */
 export declare function setDisk(disk: Disk, name?: string): Storage;
 /** The default disk, or a named one registered with `setDisk(disk, name)`. */
 export declare function storage(name?: string): Storage;
+/**
+ * Swap a disk for an in-memory `FakeStorage` so tests never touch a real bucket,
+ * and assert against what was written. Undo with `restoreDisk()`.
+ *
+ *   const disk = fakeDisk();
+ *   await request.post("/avatars", form);
+ *   await disk.assertExists("avatars/1.png");
+ */
+export declare function fakeDisk(name?: string): FakeStorage;
+/** Restore the real disk after `fakeDisk()`. With no name, restores them all. */
+export declare function restoreDisk(name?: string): void;
+export interface ServeStorageOptions {
+    /** Which registered disk to serve from. Default: `"default"`. */
+    disk?: string;
+    /** URL prefix the files live under. Default: `"/storage"`. */
+    basePath?: string;
+    /**
+     * Require a valid signature from `signedUrl()` — the private-file mode.
+     * Unsigned or expired requests get a 403. Default: false.
+     */
+    signed?: boolean;
+    /** `Cache-Control` max-age in seconds. Omit for no header. */
+    maxAge?: number;
+}
+/**
+ * Serve files from a disk over HTTP — what makes the fallback `signedUrl()` real
+ * for disks without backend presigning (the memory disk, a local-filesystem
+ * disk). Requests that don't match `basePath`, or that name a file the disk
+ * doesn't have, fall through to your routes.
+ *
+ *   this.use(serveStorage());                                  // public files
+ *   this.use(serveStorage({ basePath: "/private", signed: true }));
+ */
+export declare function serveStorage(options?: ServeStorageOptions): MiddlewareHandler;

package/dist/core/storage.js

@@ -9,8 +9,19 @@
  *   const bytes = await storage().get("avatars/1.png");
  *   const url = storage().url("avatars/1.png");
  *
+ * Private files get a temporary URL instead of a public one:
+ *
+ *   await storage().signedUrl("invoices/42.pdf", { expiresIn: 300 });
+ *
+ * and browsers can upload straight to the bucket — the bytes never transit the
+ * app — with a signed upload URL:
+ *
+ *   await storage().signedUploadUrl("uploads/raw.mov", { contentType: "video/quicktime" });
+ *
  * Register several disks by name and select one with `storage("s3")`.
  */
+import { getMimeType } from "hono/utils/mime";
+import { config } from "./helpers.js";
 function toBytes(contents) {
     if (typeof contents === "string")
         return new TextEncoder().encode(contents);
@@ -18,7 +29,71 @@ function toBytes(contents) {
         return contents;
     return new Uint8Array(contents);
 }
-/* ------------------------------ memory disk ------------------------------- */
+/** The MIME type for a path's extension, or `application/octet-stream`. */
+export function contentTypeFor(path) {
+    return getMimeType(path) ?? "application/octet-stream";
+}
+/* -------------------------------- signing --------------------------------- */
+/** HMAC-SHA256 hex — Web Crypto, so it works on Node and the edge. */
+async function hmac(key, data) {
+    const enc = new TextEncoder();
+    const cryptoKey = await crypto.subtle.importKey("raw", enc.encode(key), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const sig = await crypto.subtle.sign("HMAC", cryptoKey, enc.encode(data));
+    return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function appKey() {
+    const key = config("app.key", "");
+    if (!key)
+        throw new Error("Signed storage URLs require config('app.key'). Set APP_KEY.");
+    return key;
+}
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/**
+ * The string we actually sign: path + query, never the host. A disk's `url()`
+ * may be absolute (a CDN) or relative (`/storage/x`), while the request that
+ * comes back in is always absolute — signing only the path makes both sides
+ * agree. It also means the same signature is valid across your own hostnames,
+ * which is what you want behind a CDN.
+ */
+function canonical(url, params) {
+    const { pathname } = new URL(url, "http://keel.local");
+    const query = params.toString();
+    return query ? `${pathname}?${query}` : pathname;
+}
+/**
+ * Sign a URL with `config('app.key')`, adding `expires` and `signature` query
+ * params. Verify it with `verifyStorageUrl()`.
+ */
+export async function signStorageUrl(url, expiresIn = 3600) {
+    const mark = url.indexOf("?");
+    const base = mark === -1 ? url : url.slice(0, mark);
+    // Keep any query the disk's own url() already carries — a CDN token, say.
+    const params = new URLSearchParams(mark === -1 ? "" : url.slice(mark + 1));
+    params.set("expires", String(Math.floor(Date.now() / 1000) + expiresIn));
+    const signature = await hmac(appKey(), canonical(base, params));
+    params.set("signature", signature);
+    return `${base}?${params}`;
+}
+/** Whether a URL carries a valid, unexpired signature from `signStorageUrl()`. */
+export async function verifyStorageUrl(url) {
+    const parsed = new URL(url, "http://keel.local");
+    const signature = parsed.searchParams.get("signature");
+    if (!signature)
+        return false;
+    parsed.searchParams.delete("signature");
+    const expires = Number(parsed.searchParams.get("expires"));
+    if (!expires || expires < Math.floor(Date.now() / 1000))
+        return false;
+    const expected = await hmac(appKey(), canonical(parsed.pathname, parsed.searchParams));
+    return timingSafeEqual(signature, expected);
+}
 /** An in-memory `Disk` — the default; ideal for tests. Not shared across processes. */
 export class MemoryDisk {
     baseUrl;
@@ -26,11 +101,21 @@ export class MemoryDisk {
     constructor(baseUrl = "/storage") {
         this.baseUrl = baseUrl;
     }
-    async put(path, bytes) {
-        this.files.set(path, bytes);
+    async put(path, bytes, options = {}) {
+        this.files.set(path, {
+            bytes,
+            meta: {
+                size: bytes.byteLength,
+                contentType: options.contentType ?? contentTypeFor(path),
+                cacheControl: options.cacheControl,
+                visibility: options.visibility ?? "public",
+                lastModified: new Date(),
+                metadata: options.metadata,
+            },
+        });
     }
     async get(path) {
-        return this.files.get(path) ?? null;
+        return this.files.get(path)?.bytes ?? null;
     }
     async exists(path) {
         return this.files.has(path);
@@ -44,6 +129,18 @@ export class MemoryDisk {
     url(path) {
         return `${this.baseUrl}/${path}`;
     }
+    async metadata(path) {
+        return this.files.get(path)?.meta ?? null;
+    }
+    async copy(from, to) {
+        const entry = this.files.get(from);
+        if (entry)
+            this.files.set(to, { bytes: entry.bytes, meta: { ...entry.meta } });
+    }
+    async move(from, to) {
+        await this.copy(from, to);
+        this.files.delete(from);
+    }
 }
 /* -------------------------------- storage --------------------------------- */
 export class Storage {
@@ -51,9 +148,15 @@ export class Storage {
     constructor(disk) {
         this.disk = disk;
     }
-    /** Write a file (string, bytes, or ArrayBuffer — strings are UTF-8 encoded). */
-    put(path, contents) {
-        return this.disk.put(path, toBytes(contents));
+    /**
+     * Write a file (string, bytes, or ArrayBuffer — strings are UTF-8 encoded).
+     * The content type is inferred from the extension unless you pass one.
+     */
+    put(path, contents, options = {}) {
+        return this.disk.put(path, toBytes(contents), {
+            ...options,
+            contentType: options.contentType ?? contentTypeFor(path),
+        });
     }
     /** Read a file's raw bytes, or null if it doesn't exist. */
     get(path) {
@@ -73,16 +176,118 @@ export class Storage {
     list(prefix) {
         return this.disk.list(prefix);
     }
+    /** Size, content type, and friends — or null if the file doesn't exist. */
+    async metadata(path) {
+        if (this.disk.metadata)
+            return this.disk.metadata(path);
+        const bytes = await this.disk.get(path);
+        if (bytes == null)
+            return null;
+        return { size: bytes.byteLength, contentType: contentTypeFor(path) };
+    }
+    /** A file's size in bytes, or null if it doesn't exist. */
+    async size(path) {
+        return (await this.metadata(path))?.size ?? null;
+    }
+    /** Copy a file. Server-side when the disk supports it, else read-then-write. */
+    async copy(from, to) {
+        if (this.disk.copy)
+            return this.disk.copy(from, to);
+        const bytes = await this.disk.get(from);
+        if (bytes == null)
+            throw new Error(`Cannot copy "${from}": no such file.`);
+        const meta = await this.metadata(from);
+        await this.disk.put(to, bytes, {
+            contentType: meta?.contentType ?? contentTypeFor(to),
+            cacheControl: meta?.cacheControl,
+            visibility: meta?.visibility,
+            metadata: meta?.metadata,
+        });
+    }
+    /** Move a file. Server-side when the disk supports it, else copy-then-delete. */
+    async move(from, to) {
+        if (this.disk.move)
+            return this.disk.move(from, to);
+        await this.copy(from, to);
+        await this.disk.delete(from);
+    }
+    /** A public URL for the object. Use `signedUrl()` for private ones. */
     url(path) {
         return this.disk.url(path);
     }
+    /**
+     * A temporary URL for a private object. Uses the backend's own presigning when
+     * the disk implements `signedUrl` (S3, R2, GCS); otherwise signs the disk's
+     * `url()` with `config('app.key')` — serve those with `serveStorage({ signed: true })`.
+     */
+    async signedUrl(path, options = {}) {
+        if (this.disk.signedUrl)
+            return this.disk.signedUrl(path, options);
+        return signStorageUrl(this.disk.url(path), options.expiresIn ?? 3600);
+    }
+    /**
+     * A URL the browser can `PUT` the file to directly, so the bytes never transit
+     * your app — the point of this on the edge, where proxying a large upload
+     * through a Worker is exactly what you don't want.
+     *
+     * Only the backend can accept such a write, so this requires a disk that
+     * implements `signedUploadUrl` (see the S3/R2 recipe in the storage guide).
+     */
+    async signedUploadUrl(path, options = {}) {
+        if (!this.disk.signedUploadUrl) {
+            throw new Error("This disk does not support signed upload URLs. Implement `signedUploadUrl` on it " +
+                "(the storage guide has an S3/R2 recipe) — only the storage backend can accept a direct upload.");
+        }
+        return this.disk.signedUploadUrl(path, {
+            ...options,
+            contentType: options.contentType ?? contentTypeFor(path),
+        });
+    }
     /** The underlying driver, for backend-specific operations. */
     get driver() {
         return this.disk;
     }
 }
+/* --------------------------------- faking --------------------------------- */
+/**
+ * A `Storage` backed by a `MemoryDisk`, with assertions — what `fakeDisk()`
+ * installs so tests never touch a real bucket.
+ */
+export class FakeStorage extends Storage {
+    constructor() {
+        super(new MemoryDisk());
+    }
+    async assertExists(path) {
+        if (!(await this.exists(path))) {
+            throw new Error(`Expected "${path}" to exist on the fake disk, but it does not.`);
+        }
+    }
+    async assertMissing(path) {
+        if (await this.exists(path)) {
+            throw new Error(`Expected "${path}" to be missing from the fake disk, but it exists.`);
+        }
+    }
+    /** Assert a file's contents, as UTF-8 text. */
+    async assertContents(path, expected) {
+        await this.assertExists(path);
+        const actual = await this.getText(path);
+        if (actual !== expected) {
+            throw new Error(`Expected "${path}" to contain ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}.`);
+        }
+    }
+    /** Assert how many files are stored, optionally under a prefix. */
+    async assertCount(expected, prefix) {
+        const actual = (await this.list(prefix)).length;
+        if (actual !== expected) {
+            const where = prefix ? ` under "${prefix}"` : "";
+            throw new Error(`Expected ${expected} file(s)${where} on the fake disk, found ${actual}.`);
+        }
+    }
+}
 /* -------------------------------- global ---------------------------------- */
 const disks = new Map([["default", new Storage(new MemoryDisk())]]);
+/** Disks displaced by `fakeDisk()`, so `restoreDisk()` can put them back. */
+const realDisks = new Map();
 /** Register a disk, optionally under a name (default: `"default"`). */
 export function setDisk(disk, name = "default") {
     const store = new Storage(disk);
@@ -96,3 +301,90 @@ export function storage(name = "default") {
         throw new Error(`No storage disk named "${name}". Register it with setDisk().`);
     return store;
 }
+/**
+ * Swap a disk for an in-memory `FakeStorage` so tests never touch a real bucket,
+ * and assert against what was written. Undo with `restoreDisk()`.
+ *
+ *   const disk = fakeDisk();
+ *   await request.post("/avatars", form);
+ *   await disk.assertExists("avatars/1.png");
+ */
+export function fakeDisk(name = "default") {
+    const existing = disks.get(name);
+    // Only remember the *real* disk — faking twice must not stash a fake.
+    if (existing && !realDisks.has(name))
+        realDisks.set(name, existing);
+    const fake = new FakeStorage();
+    disks.set(name, fake);
+    return fake;
+}
+/** Restore the real disk after `fakeDisk()`. With no name, restores them all. */
+export function restoreDisk(name) {
+    const names = name ? [name] : [...realDisks.keys()];
+    for (const key of names) {
+        const real = realDisks.get(key);
+        if (real)
+            disks.set(key, real);
+        realDisks.delete(key);
+    }
+}
+/**
+ * Serve files from a disk over HTTP — what makes the fallback `signedUrl()` real
+ * for disks without backend presigning (the memory disk, a local-filesystem
+ * disk). Requests that don't match `basePath`, or that name a file the disk
+ * doesn't have, fall through to your routes.
+ *
+ *   this.use(serveStorage());                                  // public files
+ *   this.use(serveStorage({ basePath: "/private", signed: true }));
+ */
+export function serveStorage(options = {}) {
+    const basePath = (options.basePath ?? "/storage").replace(/\/+$/, "");
+    return async (c, next) => {
+        if (c.req.method !== "GET" && c.req.method !== "HEAD")
+            return next();
+        const url = new URL(c.req.url);
+        if (url.pathname !== basePath && !url.pathname.startsWith(`${basePath}/`))
+            return next();
+        const path = decodeURIComponent(url.pathname.slice(basePath.length + 1));
+        if (!path || path.includes(".."))
+            return next(); // path traversal guard
+        const store = storage(options.disk);
+        if (options.signed) {
+            // `signedUrl()` signs the path the *disk* reports. If the disk hands out
+            // `/storage/…` while this middleware is mounted at `/private`, no signature
+            // can ever match and every request would 403 — a misconfiguration that looks
+            // exactly like an expired link. Say so instead of failing quietly.
+            const diskPath = new URL(store.url(path), "http://keel.local").pathname;
+            if (diskPath !== url.pathname) {
+                throw new Error(`serveStorage: the disk serves "${path}" at "${diskPath}", but this middleware is ` +
+                    `mounted at "${url.pathname}". signedUrl() signs the disk's own URL, so no signature ` +
+                    `can match here. Give the disk the matching base URL (e.g. new MemoryDisk("${basePath}")) ` +
+                    `or set basePath to the disk's prefix.`);
+            }
+            if (!(await verifyStorageUrl(c.req.url)))
+                return c.text("Forbidden", 403);
+        }
+        const bytes = await store.get(path);
+        if (bytes == null)
+            return next();
+        const meta = await store.metadata(path);
+        const etag = `W/"${meta?.size ?? bytes.byteLength}-${meta?.lastModified?.getTime() ?? 0}"`;
+        c.header("Content-Type", meta?.contentType ?? contentTypeFor(path));
+        c.header("ETag", etag);
+        if (meta?.lastModified)
+            c.header("Last-Modified", meta.lastModified.toUTCString());
+        const cacheControl = meta?.cacheControl ??
+            (options.maxAge != null
+                ? `${options.signed ? "private" : "public"}, max-age=${options.maxAge}`
+                : undefined);
+        if (cacheControl)
+            c.header("Cache-Control", cacheControl);
+        if (c.req.header("If-None-Match") === etag)
+            return c.body(null, 304);
+        if (c.req.method === "HEAD")
+            return c.body(null, 200);
+        // Copy out of the view's backing buffer — `bytes.buffer` alone may be larger.
+        const body = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+        return c.body(body, 200);
+    };
+}