@flaredev/cli 0.1.2 → 0.3.0

package/templates/app/lib/auth-config.ts

@@ -0,0 +1,38 @@
+/**
+ * How people sign in to this app. `flare create` wrote the choices you made; change
+ * them here any time. Every method's tables already exist, so switching one on or off
+ * needs no migration, and a method that's off is refused by the API, not just hidden.
+ *
+ * Email and password sign-in is always available.
+ */
+export const authConfig = {
+  /** A sign-in link by email. */
+  magicLink: true,
+  /** A 6-digit sign-in code by email. */
+  emailOtp: true,
+  /** Face ID, Touch ID, Windows Hello or a security key. */
+  passkeys: true,
+  twoFactor: {
+    /** Codes from an authenticator app (TOTP), with backup codes. */
+    authenticator: true,
+    /** Codes by email as the second step. */
+    email: true,
+  },
+  /**
+   * Social sign-in. Each provider also needs its credentials (see .dev.vars.example);
+   * without them its button stays hidden.
+   */
+  social: [] as SocialProvider[],
+  /** Refuse password sign-in until the email address is verified. */
+  requireEmailVerification: false,
+  /**
+   * Check new passwords against Have I Been Pwned's breach list. Only the first five
+   * characters of the password's hash are sent, and an outage lets the password through.
+   */
+  checkBreachedPasswords: true,
+};
+
+export type SocialProvider = "google" | "github" | "apple" | "microsoft";
+
+/** Whether any second factor can be set up. */
+export const twoFactorAvailable = authConfig.twoFactor.authenticator || authConfig.twoFactor.email;

package/templates/app/lib/auth-emails.ts

@@ -0,0 +1,94 @@
+import { eq } from "drizzle-orm";
+import { getDb } from "@/db";
+import { user } from "@/db/auth-schema";
+import { sendTransactionalEmail } from "./mail";
+
+/**
+ * Every email the sign-in flows send. Change the wording here; the layout comes from
+ * lib/mail.ts. Without RESEND_API_KEY these print to the console, links and codes included.
+ */
+
+const ignore = "If you didn't ask for this, you can ignore this email.";
+
+/** Accounts with two-factor sign-in never get a one-step email sign-in (it would skip the second factor). */
+async function usesTwoFactor(email: string): Promise<boolean> {
+  const row = await getDb().select({ on: user.twoFactorEnabled }).from(user).where(eq(user.email, email.toLowerCase())).get();
+  return Boolean(row?.on);
+}
+
+async function sendTwoFactorNotice(email: string) {
+  await sendTransactionalEmail({
+    to: email,
+    subject: "Sign in with your password or a passkey",
+    heading: "Email sign-in is off for your account",
+    paragraphs: [
+      "Someone asked to sign in to your account by email. Your account uses two-factor authentication, so we don't send sign-in links or codes.",
+      "Sign in with your password and second factor, or with a passkey.",
+    ],
+    footer: ignore,
+  });
+}
+
+export async function sendMagicLink({ email, url }: { email: string; url: string }) {
+  if (await usesTwoFactor(email)) return sendTwoFactorNotice(email);
+  await sendTransactionalEmail({
+    to: email,
+    subject: "Your sign-in link",
+    heading: "Sign in",
+    paragraphs: ["Use this link to sign in. It works once and expires in 5 minutes."],
+    action: { label: "Sign in", url },
+    footer: ignore,
+    preheader: "Your sign-in link",
+  });
+}
+
+export async function sendEmailCode({ email, otp, type }: { email: string; otp: string; type: "sign-in" | "email-verification" | "forget-password" | "change-email" }) {
+  if (type === "sign-in" && (await usesTwoFactor(email))) return sendTwoFactorNotice(email);
+  const purpose = {
+    "sign-in": ["Your sign-in code", "Enter this code to sign in."],
+    "email-verification": ["Verify your email", "Enter this code to verify your email address."],
+    "forget-password": ["Reset your password", "Enter this code to choose a new password."],
+    "change-email": ["Confirm your new email", "Enter this code to confirm your new email address."],
+  }[type];
+  await sendTransactionalEmail({
+    to: email,
+    subject: `${purpose[0]}: ${otp}`,
+    heading: otp,
+    paragraphs: [purpose[1], "It expires in 5 minutes."],
+    footer: ignore,
+    preheader: purpose[0],
+  });
+}
+
+export async function sendTwoFactorCode({ user, otp }: { user: { email: string }; otp: string }) {
+  await sendTransactionalEmail({
+    to: user.email,
+    subject: `Your verification code: ${otp}`,
+    heading: otp,
+    paragraphs: ["Enter this code to finish signing in. It expires in 5 minutes."],
+    footer: "If you didn't just sign in, change your password: someone else knows it.",
+    preheader: "Your verification code",
+  });
+}
+
+export async function sendPasswordReset({ user, url }: { user: { email: string }; url: string }) {
+  await sendTransactionalEmail({
+    to: user.email,
+    subject: "Reset your password",
+    heading: "Reset your password",
+    paragraphs: ["Use this link to choose a new password. It expires in 1 hour."],
+    action: { label: "Choose a new password", url },
+    footer: ignore,
+  });
+}
+
+export async function sendVerificationEmail({ user, url }: { user: { email: string }; url: string }) {
+  await sendTransactionalEmail({
+    to: user.email,
+    subject: "Verify your email",
+    heading: "Verify your email",
+    paragraphs: ["Confirm this is your email address."],
+    action: { label: "Verify email", url },
+    footer: ignore,
+  });
+}

package/templates/app/lib/auth.ts

@@ -1,13 +1,88 @@
 import { env, waitUntil } from "cloudflare:workers";
-import { betterAuth } from "better-auth";
+import { passkey } from "@better-auth/passkey";
 import { drizzleAdapter } from "@better-auth/drizzle-adapter";
+import { betterAuth } from "better-auth";
+import { APIError, createAuthMiddleware } from "better-auth/api";
 import { nextCookies } from "better-auth/next-js";
 import { admin } from "better-auth/plugins/admin";
+import { emailOTP } from "better-auth/plugins/email-otp";
+import { magicLink } from "better-auth/plugins/magic-link";
+import { twoFactor } from "better-auth/plugins/two-factor";
 import { hashPassword, verifyPassword } from "@flaredev/core";
 import { getDb, schema } from "@/db";
+import { authConfig, type SocialProvider } from "./auth-config";
+import { checkPassword, isBreachedPassword, PASSWORD_MAX_LENGTH } from "./password-rules";
+import { sendEmailCode, sendMagicLink, sendPasswordReset, sendTwoFactorCode, sendVerificationEmail } from "./auth-emails";
+
+const vars = env as unknown as Record<string, string | undefined>;
 
 /** Optional: set when serving from a custom domain (e.g. https://example.com). */
-const configuredURL = (env as { BETTER_AUTH_URL?: string }).BETTER_AUTH_URL;
+const configuredURL = vars.BETTER_AUTH_URL;
+
+/** A provider's credentials from the environment, when both are set. */
+function credentials(prefix: string) {
+  const clientId = vars[`${prefix}_CLIENT_ID`];
+  const clientSecret = vars[`${prefix}_CLIENT_SECRET`];
+  return clientId && clientSecret ? { clientId, clientSecret } : undefined;
+}
+
+const providerSettings: Record<SocialProvider, Record<string, string> | undefined> = {
+  google: credentials("GOOGLE"),
+  github: credentials("GITHUB"),
+  // Apple's client secret is a JWT you generate from your key (see the auth guide).
+  apple: credentials("APPLE") && { ...credentials("APPLE")!, ...(vars.APPLE_APP_BUNDLE_ID ? { appBundleIdentifier: vars.APPLE_APP_BUNDLE_ID } : {}) },
+  // "common" accepts personal and work accounts; set a tenant id to allow only your organisation.
+  microsoft: credentials("MICROSOFT") && { ...credentials("MICROSOFT")!, tenantId: vars.MICROSOFT_TENANT_ID || "common" },
+};
+
+/** Social providers switched on in lib/auth-config.ts that also have credentials. */
+const socialProviders = Object.fromEntries(
+  authConfig.social.flatMap((provider) => (providerSettings[provider] ? [[provider, providerSettings[provider]]] : [])),
+);
+
+/** Endpoints of methods switched off in lib/auth-config.ts: refused, not just hidden. */
+function disabledPath(path: string): boolean {
+  if (!authConfig.magicLink && (path === "/sign-in/magic-link" || path === "/magic-link/verify")) return true;
+  if (!authConfig.emailOtp && (path.startsWith("/email-otp/") || path === "/sign-in/email-otp" || path === "/forget-password/email-otp")) return true;
+  if (!authConfig.passkeys && path.startsWith("/passkey/")) return true;
+  const { authenticator, email } = authConfig.twoFactor;
+  if (!authenticator && !email && path.startsWith("/two-factor/")) return true;
+  if (!authenticator && (path === "/two-factor/get-totp-uri" || path === "/two-factor/verify-totp")) return true;
+  if (!email && (path === "/two-factor/send-otp" || path === "/two-factor/verify-otp")) return true;
+  return false;
+}
+
+/** Where a new password arrives, and what it's called in the body. */
+const NEW_PASSWORD_FIELDS: Record<string, string> = {
+  "/sign-up/email": "password",
+  "/reset-password": "newPassword",
+  "/change-password": "newPassword",
+};
+
+/**
+ * The same password rules the sign-up and reset forms show as you type
+ * (lib/password-rules.ts), enforced here so the API agrees with the screens.
+ * Checked on the way in, before the password is hashed or stored.
+ */
+async function guardPassword(path: string, body: Record<string, unknown> | undefined) {
+  const field = NEW_PASSWORD_FIELDS[path];
+  if (!field) return;
+  const password = body?.[field];
+  if (typeof password !== "string") return;
+
+  if (password.length > PASSWORD_MAX_LENGTH) {
+    throw new APIError("BAD_REQUEST", { message: `Passwords can be at most ${PASSWORD_MAX_LENGTH} characters.` });
+  }
+  const check = checkPassword(password, [body?.email as string | undefined, body?.name as string | undefined]);
+  if (!check.valid) throw new APIError("BAD_REQUEST", { message: check.advice ?? "That password is too short." });
+
+  // A password in a public breach list is already guessed, however strong it looks.
+  if (authConfig.checkBreachedPasswords && (await isBreachedPassword(password))) {
+    throw new APIError("BAD_REQUEST", {
+      message: "That password has appeared in a data breach, so it isn't safe to use here. Pick a different one.",
+    });
+  }
+}
 
 export const auth = betterAuth({
   appName: "__APP_NAME__",
@@ -18,20 +93,54 @@ export const auth = betterAuth({
   baseURL: configuredURL || {
     allowedHosts: ["localhost:*", "127.0.0.1:*", "*.trycloudflare.com", "__APP_NAME__.*.workers.dev"],
   },
+  // Sign in with Apple posts back from Apple's own origin.
+  trustedOrigins: authConfig.social.includes("apple") ? ["https://appleid.apple.com"] : [],
   database: drizzleAdapter(getDb(), { provider: "sqlite", schema }),
-  socialProviders: __SOCIAL_PROVIDERS__,
+  socialProviders,
+  account: {
+    // Signing in with Google as ada@example.com joins Ada's existing account (the provider has verified the address).
+    accountLinking: { enabled: true, trustedProviders: ["google", "github", "apple", "microsoft"] },
+  },
   emailAndPassword: {
     enabled: true,
+    requireEmailVerification: authConfig.requireEmailVerification,
     // PBKDF2 via WebCrypto: the default scrypt exceeds Workers CPU limits.
     password: { hash: hashPassword, verify: verifyPassword },
+    sendResetPassword: ({ user, url }) => sendPasswordReset({ user, url }),
+    resetPasswordTokenExpiresIn: 60 * 60,
+    // A password reset signs every other device out.
+    revokeSessionsOnPasswordReset: true,
+  },
+  emailVerification: {
+    sendVerificationEmail: ({ user, url }) => sendVerificationEmail({ user, url }),
+    sendOnSignUp: true,
+    autoSignInAfterVerification: true,
   },
   advanced: {
     // Let emails and other deferred work finish after the response is sent.
     backgroundTasks: { handler: waitUntil },
   },
+  hooks: {
+    before: createAuthMiddleware(async (ctx) => {
+      if (disabledPath(ctx.path)) throw new APIError("NOT_FOUND", { message: "This sign-in method isn't enabled." });
+      await guardPassword(ctx.path, ctx.body as Record<string, unknown> | undefined);
+    }),
+  },
   plugins: [
     // Adds user.role (default "user") and admin APIs. The /admin area allows ADMIN_ROLES (lib/admin.ts).
     admin({ defaultRole: "user", adminRoles: ["admin"] }),
+    magicLink({ sendMagicLink: ({ email, url }) => sendMagicLink({ email, url }), expiresIn: 5 * 60, disableSignUp: false }),
+    emailOTP({ sendVerificationOTP: (data) => sendEmailCode(data), otpLength: 6, expiresIn: 5 * 60, allowedAttempts: 5 }),
+    twoFactor({
+      issuer: "__APP_NAME__",
+      otpOptions: { sendOTP: ({ user, otp }) => sendTwoFactorCode({ user, otp }), allowedAttempts: 5 },
+      // With only email codes switched on there's no authenticator app to confirm first.
+      skipVerificationOnEnable: !authConfig.twoFactor.authenticator,
+      // People who signed up with a social account have no password to confirm with;
+      // accounts that do have one must still give it.
+      allowPasswordless: true,
+    }),
+    passkey({ rpName: "__APP_NAME__" }),
     // Must stay last: lets server actions set auth cookies.
     nextCookies(),
   ],
@@ -39,7 +148,7 @@ export const auth = betterAuth({
 
 export type Session = typeof auth.$Infer.Session;
 
-/** OAuth providers with credentials configured, e.g. ["github"]. */
-export function enabledSocialProviders(): string[] {
-  return Object.keys(auth.options.socialProviders ?? {});
+/** OAuth providers switched on and configured, e.g. ["github"], for the sign-in buttons. */
+export function enabledSocialProviders(): SocialProvider[] {
+  return Object.keys(socialProviders) as SocialProvider[];
 }

package/templates/app/lib/cache.ts

@@ -1,83 +1,83 @@
-import { revalidateTag, unstable_cache } from "next/cache";
-import type { ChangeEvent } from "@flaredev/core/server";
-
-/**
- * Caching for data you read far more often than you write.
- *
- * Only the **data cache** (Workers KV) is configured in `vite.config.ts`. It is
- * what `cached()` below, `fetch()` and `"use cache"` write to. Shared by every
- * colo and every isolate, so a value computed once is reused until it expires or
- * its tag is revalidated.
- *
- * vinext's page-level CDN cache (the Workers Cache `cdn` adapter) is off until a
- * vinext fix lands: in the current beta, pages that redirect break behind it.
- *
- * Nothing here caches per-user data: everything keyed by session belongs
- * outside the cache, since these entries are shared between visitors.
- */
-
-/** How long cached values stay fresh, in seconds. Pick the one that matches how stale you can stand. */
-export const TTL = {
-  /** Changes often, cheap to recompute: counts, dashboards. */
-  short: 60,
-  /** The usual case: lists and detail views behind a resource tag. */
-  medium: 5 * 60,
-  /** Rarely changes: settings, published content, reference tables. */
-  long: 60 * 60,
-} as const;
-
-/** Tag for everything derived from a resource, e.g. `resource/Deal`. */
-export const resourceTag = (resource: string) => `resource/${resource}`;
-
-/** Tag for one record, e.g. `resource/Deal/0f9…`. */
-export const recordTag = (resource: string, id: string) => `resource/${resource}/${id}`;
-
-/**
- * The KV data cache silently ignores tags containing `:`, `\` or control
- * characters — the entry is stored untagged, so no revalidation ever reaches
- * it. Refuse them here instead, where the mistake is still visible.
- */
-function checkTag(tag: string): string {
-  if (!tag || tag.length > 256 || /[\x00-\x1f\\:]/.test(tag)) {
-    throw new Error(`Cache tag "${tag}" can't be used: tags must be 1–256 characters without ":", "\\" or control characters.`);
-  }
-  return tag;
-}
-
-/**
- * Cache the result of an async function in the data cache.
- *
- * `keyParts` identify the value (include every argument the result depends on);
- * `tags` say what invalidates it. Cached functions must not read cookies,
- * headers, or anything else request-specific — the value is shared.
- *
- * ```ts
- * const openDeals = cached(
- *   () => getDb().select({ total: count() }).from(deals).where(eq(deals.stage, "open")),
- *   ["deals", "open-count"],
- *   { tags: [resourceTag("Deal")] },
- * );
- * ```
- */
-export function cached<Args extends unknown[], Value>(
-  fn: (...args: Args) => Promise<Value>,
-  keyParts: string[],
-  options: { tags?: string[]; revalidate?: number } = {},
-) {
-  return unstable_cache(fn, keyParts, {
-    revalidate: options.revalidate ?? TTL.medium,
-    tags: (options.tags ?? []).map(checkTag),
-  });
-}
-
-/**
- * Drop everything cached for a resource (and for the record that changed).
- * `lib/admin.ts` and `lib/api.ts` pass this to the store, so writes through the
- * admin or the REST API invalidate without anyone remembering to call it.
- */
-export function revalidateResource({ resource, action, id }: ChangeEvent) {
-  // { expire: 0 }: drop the entry now rather than serving it stale while it refreshes.
-  // A record someone just edited should never come back with its old values.
-  revalidateTag(resourceTag(resource), { expire: 0 });
-  if (action !== "create") revalidateTag(recordTag(resource, id), { expire: 0 });
-}
+import { revalidateTag, unstable_cache } from "next/cache";
+import type { ChangeEvent } from "@flaredev/core/server";
+
+/**
+ * Caching for data you read far more often than you write.
+ *
+ * Only the **data cache** (Workers KV) is configured in `vite.config.ts`. It is
+ * what `cached()` below, `fetch()` and `"use cache"` write to. Shared by every
+ * colo and every isolate, so a value computed once is reused until it expires or
+ * its tag is revalidated.
+ *
+ * vinext's page-level CDN cache (the Workers Cache `cdn` adapter) is off until a
+ * vinext fix lands: in the current beta, pages that redirect break behind it.
+ *
+ * Nothing here caches per-user data: everything keyed by session belongs
+ * outside the cache, since these entries are shared between visitors.
+ */
+
+/** How long cached values stay fresh, in seconds. Pick the one that matches how stale you can stand. */
+export const TTL = {
+  /** Changes often, cheap to recompute: counts, dashboards. */
+  short: 60,
+  /** The usual case: lists and detail views behind a resource tag. */
+  medium: 5 * 60,
+  /** Rarely changes: settings, published content, reference tables. */
+  long: 60 * 60,
+} as const;
+
+/** Tag for everything derived from a resource, e.g. `resource/Deal`. */
+export const resourceTag = (resource: string) => `resource/${resource}`;
+
+/** Tag for one record, e.g. `resource/Deal/0f9…`. */
+export const recordTag = (resource: string, id: string) => `resource/${resource}/${id}`;
+
+/**
+ * The KV data cache silently ignores tags containing `:`, `\` or control
+ * characters — the entry is stored untagged, so no revalidation ever reaches
+ * it. Refuse them here instead, where the mistake is still visible.
+ */
+function checkTag(tag: string): string {
+  if (!tag || tag.length > 256 || /[\x00-\x1f\\:]/.test(tag)) {
+    throw new Error(`Cache tag "${tag}" can't be used: tags must be 1–256 characters without ":", "\\" or control characters.`);
+  }
+  return tag;
+}
+
+/**
+ * Cache the result of an async function in the data cache.
+ *
+ * `keyParts` identify the value (include every argument the result depends on);
+ * `tags` say what invalidates it. Cached functions must not read cookies,
+ * headers, or anything else request-specific — the value is shared.
+ *
+ * ```ts
+ * const openDeals = cached(
+ *   () => getDb().select({ total: count() }).from(deals).where(eq(deals.stage, "open")),
+ *   ["deals", "open-count"],
+ *   { tags: [resourceTag("Deal")] },
+ * );
+ * ```
+ */
+export function cached<Args extends unknown[], Value>(
+  fn: (...args: Args) => Promise<Value>,
+  keyParts: string[],
+  options: { tags?: string[]; revalidate?: number } = {},
+) {
+  return unstable_cache(fn, keyParts, {
+    revalidate: options.revalidate ?? TTL.medium,
+    tags: (options.tags ?? []).map(checkTag),
+  });
+}
+
+/**
+ * Drop everything cached for a resource (and for the record that changed).
+ * `lib/dashboard.ts` and `lib/api.ts` pass this to the store, so writes through the
+ * admin or the REST API invalidate without anyone remembering to call it.
+ */
+export function revalidateResource({ resource, action, id }: ChangeEvent) {
+  // { expire: 0 }: drop the entry now rather than serving it stale while it refreshes.
+  // A record someone just edited should never come back with its old values.
+  revalidateTag(resourceTag(resource), { expire: 0 });
+  if (action !== "create") revalidateTag(recordTag(resource, id), { expire: 0 });
+}

package/templates/app/lib/csv.ts

@@ -0,0 +1,24 @@
+/**
+ * CSV, the way spreadsheets expect it (RFC 4180): fields holding a comma, a quote or a
+ * line break are quoted, and quotes inside them are doubled.
+ *
+ * Shared by the table's "export selected" (in the browser) and the export action (on
+ * the server), so both produce the same file.
+ */
+
+export interface CsvColumn {
+  key: string;
+  label: string;
+}
+
+export function csvCell(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  const text = Array.isArray(value) ? value.join("; ") : value instanceof Date ? value.toISOString() : String(value);
+  return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+
+export function toCsv(rows: Record<string, unknown>[], columns: CsvColumn[]): string {
+  const header = columns.map((column) => csvCell(column.label)).join(",");
+  const body = rows.map((row) => columns.map((column) => csvCell(row[column.key])).join(","));
+  return [header, ...body].join("\r\n");
+}

package/templates/app/lib/dashboard-nav.ts

@@ -0,0 +1,15 @@
+// Extra dashboard sidebar links (maintained by flare generators such as `flare gen security`).
+// Add your own links outside the generated block.
+// generated:start
+export interface DashboardLink {
+  label: string;
+  href: string;
+  /** A resource icon name, e.g. "shield" (see components/dashboard/resource-icon.tsx). */
+  icon: string;
+}
+
+export const generatedDashboardLinks: DashboardLink[] = [];
+// generated:end
+
+/** Links shown under "Platform" in the dashboard sidebar. */
+export const dashboardLinks: DashboardLink[] = [...generatedDashboardLinks, { label: "API reference", href: "/api/reference", icon: "book" }];