@flaredev/cli 0.11.0 → 0.12.0

package/templates/app/lib/rate-limit.ts

@@ -0,0 +1,71 @@
+// This file is yours.
+//
+// Flare copies the code that turns a resource descriptor into a working endpoint into
+// your app rather than hiding it in node_modules, for the same reason shadcn/ui copies
+// a component: you cannot fix, read or reason about what you cannot see.
+//
+// `flare diff` shows how your copy differs from the version Flare ships, and
+// `flare update` applies the parts you choose. Neither runs unless you ask.
+
+/**
+ * Where a resource's rate limits are counted — the Cloudflare half.
+ *
+ * A descriptor says `rateLimit: { create: "10/min" }`; the generated route asks here
+ * whether this call is within it. The counters live in a Durable Object, one instance per
+ * resource and action holding a map of caller → count, so a limited call costs one object
+ * request rather than one per caller.
+ *
+ * **If the binding is missing, nothing is limited.** Say so loudly once rather than
+ * failing every request: an app that will not serve anything is worse than one that logs
+ * that a limit is not being enforced, and `flare doctor` reports it as a problem. The
+ * binding is in wrangler.jsonc as FLARE_RATE_LIMIT.
+ */
+import { env } from "cloudflare:workers";
+import { rateLimitKey, type Rate, type RateLimitDecision } from "@flaredev/core";
+import type { RateLimitNamespace } from "@flaredev/core/rate-limit/server";
+
+/** Allowed, with no count kept — what an unconfigured limiter answers. */
+const UNLIMITED: RateLimitDecision = { allowed: true, remaining: Number.MAX_SAFE_INTEGER, retryAfter: 0 };
+
+let warned = false;
+
+/** The FLARE_RATE_LIMIT binding, or undefined when the app has none. */
+function namespace(): RateLimitNamespace | undefined {
+  const binding = (env as { FLARE_RATE_LIMIT?: RateLimitNamespace } | undefined)?.FLARE_RATE_LIMIT;
+  if (binding) return binding;
+  if (!warned) {
+    warned = true;
+    console.warn(
+      "[flare] A resource declares a rateLimit, but there is no FLARE_RATE_LIMIT binding, so nothing is being limited. " +
+        "Add it to wrangler.jsonc (flare doctor will show you).",
+    );
+  }
+  return undefined;
+}
+
+/**
+ * Count one call and say whether it was within the limit.
+ *
+ * `caller` is the signed-in account's id where there is one and the client IP otherwise,
+ * so a limit is per person rather than per everyone behind one connection.
+ */
+export async function checkRateLimit(
+  resource: string,
+  action: string,
+  caller: string,
+  rate: Rate,
+): Promise<RateLimitDecision> {
+  const binding = namespace();
+  if (!binding) return UNLIMITED;
+  try {
+    // One object per resource and action; the caller is a key inside it.
+    const stub = binding.get(binding.idFromName(`${resource}:${action}`));
+    return await stub.hit(rateLimitKey(resource, action, caller), rate);
+  } catch (error) {
+    // A counter that is unreachable must not take the endpoint down with it. Letting the
+    // call through is the safer failure: the alternative is an outage in the limiter
+    // becoming an outage in the app.
+    console.error("[flare] rate limit counter failed, allowing the request:", error);
+    return UNLIMITED;
+  }
+}

package/templates/app/lib/resource/handlers.ts

@@ -13,6 +13,7 @@ import {
   crossOrigin,
   drain,
   failureResponse,
+  PROBLEM_CODES,
   problem,
   readJson,
   respond,
@@ -41,6 +42,12 @@ export interface ResourceHandlerOptions {
   authorize: Authorize;
   /** Who is making the request, for the descriptor's hooks. */
   currentUser?: ResourceStoreOptions["currentUser"];
+  /**
+   * Serve every row, whoever is asking. See {@link ResourceStoreOptions.system} — the
+   * store needs this or `currentUser`, and a route that genuinely has no session is the
+   * one case where it is the honest answer.
+   */
+  system?: ResourceStoreOptions["system"];
   /** Called after a write succeeds, for cache invalidation. */
   onChange?: (event: ChangeEvent) => void | Promise<void>;
 }
@@ -52,7 +59,7 @@ export function createResourceHandlers(options: ResourceHandlerOptions) {
 
   /** The cross-origin guard and the JSON read, in the order a write needs them. */
   const readBody = async (request: Request): Promise<{ body: unknown } | { response: Response }> =>
-    crossOrigin(request) ? { response: problem(403, "Cross-origin request blocked.") } : readJson(request);
+    crossOrigin(request) ? { response: problem(403, "Cross-origin request blocked.", PROBLEM_CODES.crossOriginBlocked) } : readJson(request);
 
   const guard = async (context: AuthorizeContext) => (await authorize(context)) ?? undefined;
 
@@ -99,7 +106,7 @@ export function createResourceHandlers(options: ResourceHandlerOptions) {
       item(request, context, "update", (id) => withBody(request, async (body) => respond(await store.replace(id, body)))),
     DELETE: (request: Request, context: RouteContext) =>
       item(request, context, "delete", async (id) => {
-        if (crossOrigin(request)) return problem(403, "Cross-origin request blocked.");
+        if (crossOrigin(request)) return problem(403, "Cross-origin request blocked.", PROBLEM_CODES.crossOriginBlocked);
         const result = await store.delete(id);
         return result.ok ? new Response(null, { status: 204 }) : failureResponse(result);
       }),

package/templates/app/lib/resource/http.ts

@@ -9,6 +9,11 @@
 // `flare update` applies the parts you choose. Neither runs unless you ask.
 
 import type { Resource } from "@flaredev/core";
+import { PROBLEM_CODES, problemResponse, type ProblemCode, type ProblemIssue } from "@flaredev/core";
+
+// Re-exported so a generated route reads every error code from `@/lib/resource` like
+// everything else it uses. The route never imports the framework directly.
+export { ISSUE_CODES, PROBLEM_CODES, type IssueCode, type ProblemCode, type ProblemIssue } from "@flaredev/core";
 import type { Failure, ResourceAction, Result } from "./store";
 
 export interface AuthorizeContext {
@@ -24,22 +29,26 @@ export type Authorize = (context: AuthorizeContext) => Response | void | Promise
 /** The context Next.js and vinext hand a route under `[id]`. */
 export type RouteContext = { params: Promise<{ id: string }> };
 
-/** A JSON error response. */
-export const problem = (status: number, error: string, extra: object = {}) => Response.json({ error, ...extra }, { status });
+/**
+ * A JSON error response, in the one shape the whole API uses:
+ *
+ *     { "error": "…", "code": "unique_violation", "issues": [{ "path": "…", "message": "…", "code": "unique" }] }
+ *
+ * `error` is the sentence a person reads and its wording may change; `code` is for a
+ * program and does not. `issues` is there whenever the answer is about fields. See
+ * PROBLEM_CODES for the codes, and the API reference for the contract.
+ */
+export const problem = (status: number, error: string, code: ProblemCode, issues?: ProblemIssue[]) =>
+  problemResponse(status, error, code, issues);
 
 /**
  * A store failure as HTTP.
  *
- * The status is decided in store.ts, where the reason is known: 422 with field issues
- * for validation, 409 with the column for a unique conflict, 404 for a missing row.
+ * The status and the code are decided in store.ts, where the reason is known: 422 with
+ * field issues for validation, 409 naming the column for a unique conflict, 404 for a
+ * missing row.
  */
-export function failureResponse(failure: Failure): Response {
-  if (failure.queryIssues) return problem(failure.status, failure.error, { issues: failure.queryIssues });
-  const extra: Record<string, unknown> = {};
-  if (failure.issues) extra.issues = failure.issues;
-  if (failure.field) extra.field = failure.field;
-  return problem(failure.status, failure.error, extra);
-}
+export const failureResponse = (failure: Failure): Response => problemResponse(failure.status, failure.error, failure.code, failure.issues);
 
 /** A store result as HTTP: the data, or the failure above. */
 export const respond = <T>(result: Result<T>, init?: ResponseInit) => (result.ok ? Response.json(result.data, init) : failureResponse(result));
@@ -80,11 +89,13 @@ export const crossOrigin = (request: Request) => {
  */
 export async function readJson(request: Request): Promise<{ body: unknown } | { response: Response }> {
   const type = request.headers.get("content-type") ?? "";
-  if (!/^application\/json\b/i.test(type)) return { response: problem(415, "Send JSON with Content-Type: application/json.") };
+  if (!/^application\/json\b/i.test(type)) {
+    return { response: problem(415, "Send JSON with Content-Type: application/json.", PROBLEM_CODES.unsupportedMediaType) };
+  }
   try {
     return { body: await request.json() };
   } catch {
-    return { response: problem(400, "Request body isn't valid JSON.") };
+    return { response: problem(400, "Request body isn't valid JSON.", PROBLEM_CODES.invalidJson) };
   }
 }
 

package/templates/app/lib/resource/store.ts

@@ -9,6 +9,7 @@
 // `flare update` applies the parts you choose. Neither runs unless you ask.
 
 import { columnName, conditionHolds, fromMinorUnits, ownershipFilter, storedFields, toMinorUnits, type Policy, type Resource } from "@flaredev/core";
+import { ISSUE_CODES, PROBLEM_CODES, type ProblemCode, type ProblemIssue } from "@flaredev/core";
 import { createValidators } from "@flaredev/core";
 import { encodeCursor, isSearchable, parseListQuery, type QueryIssue } from "./query";
 import type { ResourceRows, Row } from "./rows";
@@ -24,14 +25,19 @@ export interface FieldIssue {
 
 export type Failure = {
   ok: false;
-  status: 400 | 403 | 404 | 409 | 422;
+  status: 400 | 401 | 403 | 404 | 409 | 422;
+  /** The sentence a person reads. Its wording is not part of the contract. */
   error: string;
-  /** Validation issues per field. */
-  issues?: FieldIssue[];
-  /** Invalid query parameters. */
-  queryIssues?: QueryIssue[];
-  /** Field that caused a conflict (e.g. a unique violation). */
-  field?: string;
+  /** Why, as a value a program can switch on. See PROBLEM_CODES. */
+  code: ProblemCode;
+  /**
+   * Which fields, whenever the answer is about fields at all: one issue for a unique
+   * conflict, one per failed rule for a validation error, one per bad parameter for a
+   * query. There used to be three ways of saying this — `issues` with a `path`, `issues`
+   * with a `param`, and a bare `field` — and a client had to handle whichever one the
+   * guard that refused it happened to use.
+   */
+  issues?: ProblemIssue[];
 };
 
 export type Result<T> = { ok: true; data: T } | Failure;
@@ -105,10 +111,21 @@ export interface ResourceStoreOptions {
    * perform the action at all is decided before the store is reached, by `authorize` on
    * the API and by the dashboard's own check.
    *
-   * Ownership applies only when `currentUser` is also given. A store built without one
-   * has no session to scope to, which is how a seed or a script writes rows for anybody.
+   * Ownership applies unless `system` says otherwise.
    */
   policy?: Policy | null;
+  /**
+   * Run unconfined, on purpose.
+   *
+   * A store with no session cannot scope anything to an owner, which is right for a
+   * seed, a cron job or a migration script and wrong for anything serving a request.
+   * The two used to look identical — leave `currentUser` off and an `own` policy simply
+   * stopped applying — so the dangerous case was the one you got by forgetting.
+   *
+   * Now it has to be said. Pass `currentUser`, or pass `system: true`; a store with
+   * neither throws where it is built rather than returning everybody's rows at runtime.
+   */
+  system?: true;
   /**
    * Called after a write succeeds, for cache invalidation. Runs before the
    * operation returns, so a caller that revalidates tags can't hand back a
@@ -129,6 +146,16 @@ export function createResourceStore(options: ResourceStoreOptions) {
   const validators = createValidators(resource);
   const fields = storedFields(resource);
 
+  // Before anything else, because the failure it prevents is silent. A store with no
+  // session and no `system` cannot confine an `own` policy, so it would hand back every
+  // row — correct for a seed, a hole in a server action somebody wrote in a hurry.
+  if (!options.currentUser && !options.system) {
+    throw new Error(
+      `Resource "${resource.name}": a store needs \`currentUser\`, or \`system: true\` to say it is meant to run unconfined. ` +
+        `Without one of them an \`own\` policy cannot be applied, and every row would be returned.`,
+    );
+  }
+
   // Drizzle can say up front whether the table matches the descriptor; a Prisma client
   // can't be asked the same question without a round trip, so that check stays here.
   const columns = "columns" in rows ? (rows.columns as Record<string, { name: string }>) : undefined;
@@ -146,7 +173,13 @@ export function createResourceStore(options: ResourceStoreOptions) {
       ? Object.entries(columns).find(([, column]) => column.name === name)?.[0]
       : ["id", "createdAt", "updatedAt", ...fields.map(([key]) => key)].find((key) => columnName(key) === name || key === name);
 
-  const fail = (status: Failure["status"], error: string, extra: Partial<Failure> = {}): Failure => ({ ok: false, status, error, ...extra });
+  const fail = (status: Failure["status"], error: string, code: ProblemCode, issues?: ProblemIssue[]): Failure => ({
+    ok: false,
+    status,
+    error,
+    code,
+    ...(issues?.length ? { issues } : {}),
+  });
 
   /** The same wording whichever database refused the write. */
   function constraintFailure(error: unknown, action: ResourceAction): Failure | undefined {
@@ -155,14 +188,17 @@ export function createResourceStore(options: ResourceStoreOptions) {
     if (hit.kind === "unique") {
       const key = hit.column ? keyForColumn(hit.column) : undefined;
       const label = key ? (resource.fields[key]?.label ?? key) : "Value";
-      return fail(409, `${label} is already taken.`, key ? { field: key } : {});
+      const error = `${label} is already taken.`;
+      // The column goes in as an issue, so a form reads one shape whether a rule or the
+      // database refused the value.
+      return fail(409, error, PROBLEM_CODES.uniqueViolation, key ? [{ path: key, message: error, code: ISSUE_CODES.unique }] : undefined);
     }
     if (hit.kind === "foreignKey") {
       return action === "delete"
-        ? fail(409, `This ${resource.label.toLowerCase()} is still referenced by other records.`)
-        : fail(422, "A related record doesn't exist.");
+        ? fail(409, `This ${resource.label.toLowerCase()} is still referenced by other records.`, PROBLEM_CODES.stillReferenced)
+        : fail(422, "A related record doesn't exist.", PROBLEM_CODES.relatedRecordMissing);
     }
-    return fail(422, "A value is outside its allowed options.");
+    return fail(422, "A value is outside its allowed options.", PROBLEM_CODES.valueNotAllowed);
   }
 
   async function guarded<T>(action: ResourceAction, work: () => Promise<Result<T>>): Promise<Result<T>> {
@@ -196,9 +232,14 @@ export function createResourceStore(options: ResourceStoreOptions) {
   }
 
   const invalid = (issues: { path: PropertyKey[]; message: string }[]) =>
-    fail(422, "Validation failed.", { issues: issues.map((issue) => ({ path: issue.path.map(String).join("."), message: issue.message })) });
+    fail(
+      422,
+      "Validation failed.",
+      PROBLEM_CODES.validationFailed,
+      issues.map((issue) => ({ path: issue.path.map(String).join("."), message: issue.message, code: ISSUE_CODES.invalid })),
+    );
 
-  const notFound = () => fail(404, `${resource.label} not found.`);
+  const notFound = () => fail(404, `${resource.label} not found.`, PROBLEM_CODES.notFound);
 
   /**
    * Money fields, and the currency each one counts in.
@@ -305,15 +346,17 @@ export function createResourceStore(options: ResourceStoreOptions) {
   /**
    * The owner this call is confined to: `null` to touch every row, or a Failure.
    *
-   * Only when a `currentUser` was given — see the option. A policy that restricts rows
-   * and a request with no session is a 403, not an unrestricted query: the API refuses
-   * that earlier, but the dashboard and server actions come through here too, and a
-   * missing session must never widen what a query returns.
+   * Unconfined only when the store said `system` — see the option. A policy that
+   * restricts rows and a request with no session is a 403, not an unrestricted query:
+   * the API refuses that earlier, but the dashboard and server actions come through here
+   * too, and a missing session must never widen what a query returns.
    */
   async function confine(): Promise<{ field: string; value: string } | Failure | null> {
-    if (!ownership || !options.currentUser) return null;
-    const user = await options.currentUser();
-    if (!user) return fail(403, "Sign in required.");
+    // `system` is the only way past an ownership policy, and the constructor has already
+    // insisted that a store without one has a `currentUser` to confine to.
+    if (!ownership || options.system) return null;
+    const user = await options.currentUser!();
+    if (!user) return fail(401, "Sign in required.", PROBLEM_CODES.unauthenticated);
     return ownershipFilter(options.policy, user);
   }
 
@@ -331,7 +374,16 @@ export function createResourceStore(options: ResourceStoreOptions) {
     /** `params`: page, perPage, sort, q, filter[field], cursor (as parsed by parseListQuery). */
     async list(params: URLSearchParams, options: { maxPerPage?: number } = {}): Promise<Result<ListResult>> {
       const parsed = parseListQuery(resource, params, options);
-      if ("issues" in parsed) return fail(400, "Invalid query.", { queryIssues: parsed.issues });
+      // A bad parameter is an issue like any other; it used to arrive under `param`
+      // rather than `path`, which was the fourth shape a client had to know about.
+      if ("issues" in parsed) {
+        return fail(
+          400,
+          "Invalid query.",
+          PROBLEM_CODES.invalidQuery,
+          parsed.issues.map((issue) => ({ path: issue.param, message: issue.message, code: ISSUE_CODES.invalidParameter })),
+        );
+      }
       const { page, perPage, sort, q, cursor } = parsed.query;
 
       const limit = await confine();
@@ -502,9 +554,9 @@ export function createResourceStore(options: ResourceStoreOptions) {
           const sent = (supplied as Record<string, unknown>)[limit.field];
           if (sent !== limit.value) {
             const label = resource.fields[limit.field]?.label ?? limit.field;
-            return fail(422, `You can't change which user this ${resource.label.toLowerCase()} belongs to.`, {
-              issues: [{ path: limit.field, message: `${label} can't be changed.` }],
-            });
+            return fail(422, `You can't change which user this ${resource.label.toLowerCase()} belongs to.`, PROBLEM_CODES.validationFailed, [
+              { path: limit.field, message: `${label} can't be changed.`, code: ISSUE_CODES.immutable },
+            ]);
           }
         }
 

package/templates/app/lib/storage/cloudinary.ts

@@ -0,0 +1,146 @@
+import type { StorageBucket, StorageObjectBody } from "@flaredev/core";
+
+/**
+ * Files on Cloudinary.
+ *
+ * Cloudinary is a CDN with an image pipeline attached, so this bucket serves reads from
+ * `res.cloudinary.com` rather than streaming them back through the app — see
+ * `publicUrl` below, and read what it says about privacy before choosing this one.
+ *
+ * Plain `fetch` and Web Crypto, no SDK: the signing is a sorted query string and a
+ * hash, and the upload is a multipart POST.
+ */
+
+export interface CloudinaryOptions {
+  cloudName: string;
+  apiKey: string;
+  apiSecret: string;
+  /**
+   * Serve reads straight from Cloudinary's CDN. Default true, because it is the reason
+   * to use Cloudinary. See {@link StorageBucket.publicUrl}: those files are readable by
+   * anyone with the link. Set it false to keep every read signed and proxied, and
+   * Cloudinary becomes storage with a good image pipeline you reach for deliberately.
+   */
+  publicDelivery?: boolean;
+}
+
+/**
+ * Cloudinary stores an asset under one of three resource types and the type is part of
+ * its URL, so upload and read have to agree on which. The key's extension decides, and
+ * it decides the same way in both directions — `createObjectKey` keeps the extension
+ * from the uploaded filename, so in practice this is the type the file really is.
+ *
+ * A key with no extension is `raw`, which serves the bytes back unchanged. That is the
+ * safe answer rather than the clever one.
+ */
+const IMAGE = /\.(png|jpe?g|gif|webp|avif|svg|bmp|ico|tiff?|heic|heif)$/i;
+const VIDEO = /\.(mp4|webm|mov|m4v|avi|mkv|ogv|mp3|m4a|wav|ogg|aac|flac)$/i;
+
+export function resourceType(key: string): "image" | "video" | "raw" {
+  if (IMAGE.test(key)) return "image";
+  // Cloudinary files audio under "video"; it is one pipeline.
+  if (VIDEO.test(key)) return "video";
+  return "raw";
+}
+
+/** Hex SHA-1, which is what Cloudinary's signatures use by default. */
+async function sha1Hex(input: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-1", new TextEncoder().encode(input));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Cloudinary's signature: every signed parameter as `name=value`, sorted by name,
+ * joined with `&`, the API secret appended with no separator, then SHA-1.
+ *
+ * `file`, `api_key`, `resource_type` and `cloud_name` are never signed.
+ */
+export async function sign(params: Record<string, string>, apiSecret: string): Promise<string> {
+  const toSign = Object.keys(params)
+    .sort()
+    .map((name) => `${name}=${params[name]}`)
+    .join("&");
+  return sha1Hex(toSign + apiSecret);
+}
+
+export function cloudinaryBucket(options: CloudinaryOptions): StorageBucket {
+  const { cloudName, apiKey, apiSecret } = options;
+  const publicDelivery = options.publicDelivery ?? true;
+  const api = (type: string, action: string) => `https://api.cloudinary.com/v1_1/${cloudName}/${type}/${action}`;
+
+  /**
+   * The key, as a Cloudinary public id.
+   *
+   * An `image` or `video` public id carries no extension — Cloudinary appends the
+   * format, and leaving it on produces `photo.png.png`. A `raw` asset keeps it, because
+   * for raw the public id is the whole filename.
+   */
+  const publicId = (key: string) => (resourceType(key) === "raw" ? key : key.replace(/\.[^./]+$/, ""));
+
+  /** The delivery URL for a key, which is public whether or not it is handed out. */
+  const deliveryUrl = (key: string) =>
+    `https://res.cloudinary.com/${cloudName}/${resourceType(key)}/upload/${publicId(key)
+      .split("/")
+      .map(encodeURIComponent)
+      .join("/")}`;
+
+  return {
+    async get(key: string): Promise<StorageObjectBody | null> {
+      const response = await fetch(deliveryUrl(key));
+      if (!response.ok || !response.body) return null;
+      return {
+        body: response.body,
+        size: Number(response.headers.get("content-length") ?? 0),
+        httpEtag: response.headers.get("etag") ?? "",
+        httpMetadata: { contentType: response.headers.get("content-type") ?? undefined },
+      };
+    },
+
+    async put(key, value, putOptions) {
+      const timestamp = String(Math.floor(Date.now() / 1000));
+      // `overwrite` and `invalidate` so re-uploading a key replaces what the CDN serves
+      // rather than leaving the old bytes cached at the edge under the same URL.
+      const signed: Record<string, string> = {
+        public_id: publicId(key),
+        timestamp,
+        overwrite: "true",
+        invalidate: "true",
+      };
+
+      const form = new FormData();
+      const body = value === null ? new ArrayBuffer(0) : await new Response(value as BodyInit).arrayBuffer();
+      const contentType = putOptions?.httpMetadata?.contentType;
+      form.append("file", new Blob([body], contentType ? { type: contentType } : undefined), key.split("/").pop() ?? "file");
+      form.append("api_key", apiKey);
+      form.append("signature", await sign(signed, apiSecret));
+      for (const [name, entry] of Object.entries(signed)) form.append(name, entry);
+
+      const response = await fetch(api(resourceType(key), "upload"), { method: "POST", body: form });
+      if (!response.ok) {
+        const detail = await response.text().catch(() => "");
+        throw new Error(`Cloudinary upload failed for "${key}": ${response.status} ${detail.slice(0, 300)}`);
+      }
+    },
+
+    async delete(keys) {
+      for (const key of [keys].flat()) {
+        const timestamp = String(Math.floor(Date.now() / 1000));
+        const signed = { public_id: publicId(key), timestamp, invalidate: "true" };
+        const form = new FormData();
+        form.append("api_key", apiKey);
+        form.append("signature", await sign(signed, apiSecret));
+        for (const [name, entry] of Object.entries(signed)) form.append(name, entry);
+
+        const response = await fetch(api(resourceType(key), "destroy"), { method: "POST", body: form });
+        // `destroy` answers 200 with result "not found" for a key that was never there,
+        // which is the outcome asked for. Only a transport-level failure is an error.
+        if (!response.ok) {
+          const detail = await response.text().catch(() => "");
+          throw new Error(`Cloudinary delete failed for "${key}": ${response.status} ${detail.slice(0, 300)}`);
+        }
+      }
+    },
+
+    publicUrl: publicDelivery ? (key: string) => deliveryUrl(key) : undefined,
+  };
+}

package/templates/app/lib/storage/uploadthing.ts

@@ -0,0 +1,122 @@
+import type { StorageBucket, StorageObjectBody } from "@flaredev/core";
+
+/**
+ * Files on UploadThing.
+ *
+ * One wrinkle shapes this whole file: UploadThing mints its own file key on upload, and
+ * a bucket is asked to store bytes under a key it was *given*. The two are reconciled
+ * with `customId`, which UploadThing accepts at upload, addresses in a delivery URL,
+ * and filters by on delete. So Flare's key stays Flare's key and never has to be
+ * stored anywhere, which is what would otherwise be needed.
+ *
+ * A customId is one path segment, so the slashes in `uploads/2026/09/…` are encoded on
+ * the way in. {@link customIdFor} is the only place that knows the encoding and both
+ * directions go through it.
+ *
+ * Requires the `uploadthing` package:
+ *
+ *   pnpm add uploadthing
+ */
+
+export interface UploadThingOptions {
+  /** From the UploadThing dashboard. Defaults to `UPLOADTHING_TOKEN`. */
+  token?: string;
+  /**
+   * The app id, which is the subdomain files are served from. Defaults to
+   * `UPLOADTHING_APP_ID`.
+   */
+  appId: string;
+  /**
+   * Serve reads from UploadThing's CDN. Default true, which is the reason to use it.
+   * See {@link StorageBucket.publicUrl}: those files are readable by anyone with the
+   * link. Set it false and reads are signed and proxied through this app instead.
+   */
+  publicDelivery?: boolean;
+}
+
+/**
+ * A Flare key as an UploadThing customId.
+ *
+ * Percent-encoding with `_` in place of `%`, because `%` in a customId would be decoded
+ * again by whatever reads the URL. Every character outside `[A-Za-z0-9.-]` becomes `_`
+ * and two hex digits — including `_` itself, which is what makes it reversible.
+ *
+ * Reversible matters more than it looks. A lossy encoding maps two different keys onto
+ * one id, and then an upload overwrites a file it has never heard of and a delete
+ * removes somebody else's. The first draft of this mapped `a/b.png` and `a__b.png` to
+ * the same id.
+ */
+export function customIdFor(key: string): string {
+  return key.replace(/[^A-Za-z0-9.-]/g, (char) => `_${char.charCodeAt(0).toString(16).padStart(2, "0")}`);
+}
+
+/**
+ * The part of UTApi this driver uses.
+ *
+ * Described here rather than imported, so an app that does not use this driver still
+ * typechecks without the package installed — which is every app that picked one of the
+ * other three.
+ */
+interface UTApiLike {
+  uploadFiles(file: unknown): Promise<{ error: { message: string } | null }>;
+  deleteFiles(keys: string[], options: { keyType: "customId" }): Promise<unknown>;
+}
+
+/**
+ * The SDK, loaded only if this driver is actually used.
+ *
+ * The specifier is a variable so that neither TypeScript nor the bundler tries to
+ * resolve a package that an app using a different driver has no reason to install.
+ */
+const SDK = "uploadthing/server";
+
+async function api(token: string | undefined): Promise<UTApiLike> {
+  let module: { UTApi: new (options: Record<string, unknown>) => UTApiLike };
+  try {
+    module = (await import(SDK)) as never;
+  } catch {
+    throw new Error('STORAGE_DRIVER is "uploadthing" but the `uploadthing` package is not installed. Run: pnpm add uploadthing');
+  }
+  return new module.UTApi(token ? { token } : {});
+}
+
+export function uploadThingBucket(options: UploadThingOptions): StorageBucket {
+  const publicDelivery = options.publicDelivery ?? true;
+  const deliveryUrl = (key: string) => `https://${options.appId}.ufs.sh/f/${customIdFor(key)}`;
+
+  return {
+    async get(key: string): Promise<StorageObjectBody | null> {
+      const response = await fetch(deliveryUrl(key));
+      if (!response.ok || !response.body) return null;
+      return {
+        body: response.body,
+        size: Number(response.headers.get("content-length") ?? 0),
+        httpEtag: response.headers.get("etag") ?? "",
+        httpMetadata: { contentType: response.headers.get("content-type") ?? undefined },
+      };
+    },
+
+    async put(key, value, putOptions) {
+      const body = value === null ? new ArrayBuffer(0) : await new Response(value as BodyInit).arrayBuffer();
+      const contentType = putOptions?.httpMetadata?.contentType;
+      const name = key.split("/").pop() ?? "file";
+
+      // UTApi takes a Blob with a `name`, and reads `customId` off it. A global `File`
+      // is exactly that on Node 20+, which is the floor Flare builds on anyway.
+      const file = new File([body], name, contentType ? { type: contentType } : undefined) as File & { customId?: string };
+      file.customId = customIdFor(key);
+
+      const { error } = await (await api(options.token)).uploadFiles(file);
+      if (error) throw new Error(`UploadThing upload failed for "${key}": ${error.message}`);
+    },
+
+    async delete(keys) {
+      const ids = [keys].flat().map(customIdFor);
+      if (ids.length === 0) return;
+      // Deleting what was never there is not an error, which is the outcome asked for.
+      await (await api(options.token)).deleteFiles(ids, { keyType: "customId" });
+    },
+
+    publicUrl: publicDelivery ? (key: string) => deliveryUrl(key) : undefined,
+  };
+}