@flaredev/cli 0.10.0 → 0.12.0

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,
+  };
+}

package/templates/app/lib/storage.ts

@@ -1,12 +1,35 @@
 import { env } from "cloudflare:workers";
-import { createObjectKey, createStorage } from "@flaredev/core";
+import { createObjectKey, createStorage, type StorageBucket } from "@flaredev/core";
+import { cloudinaryBucket } from "./storage/cloudinary";
+import { uploadThingBucket } from "./storage/uploadthing";
 
 /**
- * File storage on the `STORAGE` R2 bucket.
+ * Where uploaded files go.
  *
- * `createUploadUrl` / `createReadUrl` return short-lived signed URLs redeemed by
- * `app/api/storage/route.ts`. A URL grants access to whoever holds it, so check
- * that the current user may upload or view the object before issuing one.
+ * The default is the `STORAGE` R2 bucket this app is already bound to: no account to
+ * create, no keys to copy, and Wrangler simulates it locally as a directory. Set
+ * `STORAGE_DRIVER` to send files to a content delivery network instead.
+ *
+ *   r2           The bound bucket. The default, and nothing to configure.
+ *   cloudinary   A CDN with an image pipeline. Serves from res.cloudinary.com.
+ *   uploadthing  A CDN with an uploader. Serves from <app>.ufs.sh.
+ *
+ * The drivers are in `lib/storage/`, in your repository, and are ordinary files you can
+ * read and change. Adding one means writing `get`, `put` and `delete`.
+ *
+ * `disk` exists on the Next.js stack and not here: a Worker has no filesystem to write
+ * to, and the bound bucket already covers what it is for.
+ *
+ * ## Private by default, and what breaks that
+ *
+ * With `r2`, a read URL is a short-lived signed token redeemed by
+ * `app/api/storage/route.ts`, so whoever issued it decided the viewer was allowed it.
+ *
+ * `cloudinary` and `uploadthing` are content delivery networks, and serving through
+ * this Worker would throw away the thing you are paying them for. So they hand back
+ * their own URL, which **anyone with the link can read, forever**. That is the normal
+ * way to use them and the wrong way to store a medical record. Set
+ * `STORAGE_PUBLIC=false` to keep every read signed and proxied.
  *
  *   const { url } = await storage.createUploadUrl({
  *     key: createObjectKey(file.name, `users/${user.id}`),
@@ -17,8 +40,51 @@ import { createObjectKey, createStorage } from "@flaredev/core";
  *
  *   const src = await storage.createReadUrl({ key });
  */
+
+type StorageDriver = "r2" | "cloudinary" | "uploadthing";
+
+const DRIVERS: StorageDriver[] = ["r2", "cloudinary", "uploadthing"];
+
+const vars = env as unknown as Record<string, string | undefined>;
+
+const configured = (vars.STORAGE_DRIVER ?? "r2").trim().toLowerCase();
+if (!DRIVERS.includes(configured as StorageDriver)) {
+  throw new Error(`Unknown STORAGE_DRIVER "${configured}". One of: ${DRIVERS.join(", ")}.`);
+}
+const driver = configured as StorageDriver;
+
+/** Required configuration, named in the error rather than left as `undefined`. */
+function required(name: string): string {
+  const value = vars[name];
+  if (!value) throw new Error(`STORAGE_DRIVER is "${driver}" and needs ${name}, which is not set. Add it with: wrangler secret put ${name}`);
+  return value;
+}
+
+/** Public delivery is the point of a CDN, so it is on unless it is turned off. */
+const publicDelivery = vars.STORAGE_PUBLIC !== "false";
+
+function selectBucket(): StorageBucket {
+  switch (driver) {
+    case "cloudinary":
+      return cloudinaryBucket({
+        cloudName: required("CLOUDINARY_CLOUD_NAME"),
+        apiKey: required("CLOUDINARY_API_KEY"),
+        apiSecret: required("CLOUDINARY_API_SECRET"),
+        publicDelivery,
+      });
+    case "uploadthing":
+      return uploadThingBucket({
+        token: required("UPLOADTHING_TOKEN"),
+        appId: required("UPLOADTHING_APP_ID"),
+        publicDelivery,
+      });
+    case "r2":
+      return env.STORAGE;
+  }
+}
+
 export const storage = createStorage({
-  bucket: env.STORAGE,
+  bucket: selectBucket(),
   // Signing keys are derived from the auth secret with a storage-specific label.
   secret: env.BETTER_AUTH_SECRET,
 });

package/templates/app/lib/user-titles.ts

@@ -0,0 +1,52 @@
+// 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.
+
+/**
+ * Names for the accounts a `belongsTo("User")` field points at.
+ *
+ * Better Auth owns the account table, so it is not a Flare resource and has no store to
+ * ask — but the admin still has to show "Ada Lovelace" where the column holds a uuid.
+ * This is the one place that reads it, and it reads two columns and no more.
+ *
+ * An account may have no name (a passkey-only sign-up, say), so the email stands in. It
+ * is the same fallback `/api/users` uses, so a record reads the same in the table, on
+ * the detail page and in the picker.
+ */
+import { inArray } from "drizzle-orm";
+import { getDb } from "@/db";
+import { user } from "@/db/auth-schema";
+
+/** What the admin needs to treat Better Auth's account table as a relation target. */
+export const AUTH_USER_RELATION = {
+  name: "User",
+  label: "User",
+  pluralLabel: "Users",
+  slug: "users",
+  titleField: "name",
+} as const;
+
+/** id → display name, for the ids that exist. Unknown ids are simply absent. */
+export async function userTitles(ids: string[]): Promise<Record<string, string>> {
+  const wanted = [...new Set(ids.filter(Boolean))];
+  if (wanted.length === 0) return {};
+  const rows = await getDb().select({ id: user.id, name: user.name, email: user.email }).from(user).where(inArray(user.id, wanted));
+  return Object.fromEntries(rows.map((row) => [row.id, row.name?.trim() || row.email]));
+}
+
+/**
+ * Whether anybody has an account yet.
+ *
+ * Asked by the sign-up page: the gate in lib/auth.ts always lets the *first* account
+ * through, whatever `authConfig.signup` says, because an app nobody can sign into cannot
+ * be set up. So "sign-up is closed" is only true once somebody exists.
+ */
+export async function anyAccountExists(): Promise<boolean> {
+  const [first] = await getDb().select({ id: user.id }).from(user).limit(1);
+  return first !== undefined;
+}

package/templates/app/worker/index.ts

@@ -1,4 +1,5 @@
 import app from "vinext/server/app-router-entry";
+import { RateLimitCounter } from "@flaredev/core/rate-limit/server";
 import { RealtimeChannel, handleRealtimeUpgrade } from "@flaredev/core/realtime/server";
 import { SecurityMonitor } from "@flaredev/core/security/server";
 import { authorizeRealtime } from "../lib/realtime";
@@ -9,12 +10,14 @@ import { protect } from "../lib/security";
 // the `cloudflare:workers` module.
 
 // Durable Object classes must be exported from the Worker's main module.
-export { RealtimeChannel, SecurityMonitor };
+export { RateLimitCounter, RealtimeChannel, SecurityMonitor };
 
 export interface AppEnv {
   ASSETS: Fetcher;
   DB: D1Database;
   FLARE_REALTIME: DurableObjectNamespace<RealtimeChannel>;
+  /** Counters for the rate limits a descriptor declares (see lib/rate-limit.ts). */
+  FLARE_RATE_LIMIT: DurableObjectNamespace<RateLimitCounter>;
 }
 
 export interface AppContext {

package/templates/app/wrangler.jsonc

@@ -16,6 +16,13 @@
         // Object instance created on demand; wrangler provisions nothing upfront.
         "name": "FLARE_REALTIME",
         "class_name": "RealtimeChannel"
+      },
+      {
+        // Rate limit counters (see lib/rate-limit.ts). One instance per resource and
+        // action, holding a count per caller — so a limited endpoint costs one object
+        // request, not one per person calling it.
+        "name": "FLARE_RATE_LIMIT",
+        "class_name": "RateLimitCounter"
       }
     ]
   },
@@ -23,6 +30,10 @@
     {
       "tag": "v1",
       "new_sqlite_classes": ["RealtimeChannel"]
+    },
+    {
+      "tag": "v2",
+      "new_sqlite_classes": ["RateLimitCounter"]
     }
   ],
   "d1_databases": [