@flaredev/cli 0.11.0 → 0.12.0

package/templates/app/components/dashboard/invite-form.tsx

@@ -0,0 +1,86 @@
+"use client";
+
+import { useState, useTransition } from "react";
+import { CheckIcon, CopyIcon } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Field, FieldDescription, FieldGroup, FieldLabel } from "@/components/ui/field";
+import { Input } from "@/components/ui/input";
+import { Spinner } from "@/components/ui/spinner";
+import type { IssuedInvitation } from "@/app/dashboard/invitations/actions";
+
+/**
+ * Issue an invitation and show the link once.
+ *
+ * Once, because only the hash of the token is stored: there is no second chance to read
+ * it. So the link stays on screen until the next one is issued, with a copy button — a
+ * link you have to retype from a toast that has already gone is not a feature.
+ */
+export function InviteForm({ issue }: { issue: (formData: FormData) => Promise<IssuedInvitation> }) {
+  const [pending, startTransition] = useTransition();
+  const [issued, setIssued] = useState<IssuedInvitation | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [copied, setCopied] = useState(false);
+
+  const submit = (formData: FormData) => {
+    setError(null);
+    startTransition(async () => {
+      try {
+        setIssued(await issue(formData));
+        setCopied(false);
+      } catch (cause) {
+        setError(cause instanceof Error ? cause.message : "Could not create the invitation.");
+      }
+    });
+  };
+
+  const copy = async () => {
+    if (!issued) return;
+    try {
+      await navigator.clipboard.writeText(issued.link);
+      setCopied(true);
+    } catch {
+      // A browser that refuses the clipboard still shows the link to select by hand.
+    }
+  };
+
+  return (
+    <div className="flex flex-col gap-4">
+      <form action={submit}>
+        <FieldGroup>
+          <Field>
+            <FieldLabel htmlFor="invite-email">Email address</FieldLabel>
+            <Input id="invite-email" name="email" type="email" placeholder="ada@example.com" autoComplete="off" />
+            <FieldDescription>Leave it empty for a link anybody may use.</FieldDescription>
+          </Field>
+          <Field>
+            <FieldLabel htmlFor="invite-days">Valid for</FieldLabel>
+            <Input id="invite-days" name="days" type="number" min={1} max={90} defaultValue={7} />
+            <FieldDescription>Days until the link stops working.</FieldDescription>
+          </Field>
+          <Button type="submit" disabled={pending}>
+            {pending && <Spinner data-icon="inline-start" />}
+            Create invitation
+          </Button>
+        </FieldGroup>
+      </form>
+
+      {error && <p className="text-sm text-destructive">{error}</p>}
+
+      {issued && (
+        <div className="flex flex-col gap-2 rounded-md border bg-muted/40 p-3">
+          <p className="text-sm font-medium">
+            {issued.email ? `Invitation for ${issued.email}` : "Invitation for anybody with the link"}
+          </p>
+          <div className="flex items-center gap-2">
+            <code className="min-w-0 flex-1 truncate rounded bg-background px-2 py-1 text-xs">{issued.link}</code>
+            <Button type="button" variant="outline" size="sm" onClick={copy}>
+              {copied ? <CheckIcon data-icon="inline-start" /> : <CopyIcon data-icon="inline-start" />}
+              {copied ? "Copied" : "Copy"}
+            </Button>
+          </div>
+          <p className="text-xs text-muted-foreground">Copy it now — it is not stored and cannot be shown again.</p>
+        </div>
+      )}
+    </div>
+  );
+}

package/templates/app/components/dashboard/record-detail.tsx

@@ -1,6 +1,6 @@
 import Link from "next/link";
 import { notFound } from "next/navigation";
-import { clientResource, formatValue, optionLabel, relationGraph, statusTone, storedFields, type Resource } from "@flaredev/core";
+import { clientResource, formatValue, isAuthUserTarget, optionLabel, relationGraph, statusTone, storedFields, type Resource } from "@flaredev/core";
 import { Badge } from "@/components/ui/badge";
 import { FileCell } from "@/components/dashboard/fields/file-cell";
 import { Markdown } from "@/components/dashboard/fields/markdown";
@@ -13,6 +13,7 @@ import { LocalTime } from "./local-time";
 import { PageHeader } from "./page-header";
 import { RecordActions } from "./record-actions";
 import type { RelationMeta } from "./fields/field-widget";
+import { AUTH_USER_RELATION, userTitles } from "@/lib/user-titles";
 
 /** How many of a record's children to show before pointing at the filtered list. */
 const RELATED_LIMIT = 5;
@@ -43,10 +44,20 @@ export async function RecordDetail({ resource, id }: { resource: Resource; id: s
   const relations: Record<string, RelationMeta & { initialTitle?: string }> = {};
   for (const [key, def] of fields) {
     if (def.kind !== "belongsTo") continue;
+    const value = record[key];
+    // Better Auth's account table is not a resource, so it has no store to ask: its
+    // names come from lib/user-titles.ts and its picker from /api/users.
+    if (isAuthUserTarget(def.target)) {
+      relations[key] = AUTH_USER_RELATION;
+      if (typeof value === "string") {
+        const title = (await userTitles([value]))[value];
+        if (title) relationTitles[key] = title;
+      }
+      continue;
+    }
     const target = byName.get(def.target);
     if (!target) continue;
     relations[key] = { name: target.name, label: target.label, pluralLabel: target.pluralLabel, slug: target.slug, titleField: target.titleField };
-    const value = record[key];
     if (typeof value === "string") {
       const titles = await dashboardStore(target.name).titles([value]);
       const title = titles[value];

package/templates/app/components/dashboard/resource-form-page.tsx

@@ -1,9 +1,10 @@
 import { notFound } from "next/navigation";
-import { clientResource, formatValue, storedFields, type Resource } from "@flaredev/core";
+import { clientResource, formatValue, isAuthUserTarget, storedFields, type Resource } from "@flaredev/core";
 import { resourcePath, allResources, confinedField, dashboardStore, requireAccess } from "@/lib/dashboard";
 import type { RelationMeta } from "./fields/field-widget";
 import { PageHeader } from "./page-header";
 import { ResourceForm } from "./resource-form";
+import { AUTH_USER_RELATION, userTitles } from "@/lib/user-titles";
 
 /** Server wrapper for create/edit pages: loads the record and relation titles, renders the heading and form. */
 export async function ResourceFormPage({ resource, id }: { resource: Resource; id?: string }) {
@@ -25,6 +26,13 @@ export async function ResourceFormPage({ resource, id }: { resource: Resource; i
   const relations: Record<string, RelationMeta & { initialTitle?: string }> = {};
   for (const [key, def] of storedFields(resource)) {
     if (def.kind !== "belongsTo") continue;
+    if (isAuthUserTarget(def.target)) {
+      // The accounts table, whose names and picker come from outside the resource store.
+      const current = record?.[key];
+      const titles = typeof current === "string" ? await userTitles([current]) : {};
+      relations[key] = { ...AUTH_USER_RELATION, initialTitle: typeof current === "string" ? titles[current] : undefined };
+      continue;
+    }
     const target = byName.get(def.target);
     if (!target) continue;
     const value = record?.[key];

package/templates/app/components/dashboard/resource-form.tsx

@@ -150,7 +150,9 @@ export function ResourceForm({ resource, mode, id, record, relations = {}, listH
         router.refresh();
         return;
       }
-      const fieldErrors = result.issues ? issuesByField(result.issues) : result.field ? { [result.field]: result.error } : { _form: result.error };
+      // One shape to read: a unique conflict names its column in `issues` now, the same
+      // way a failed rule does, so there is no second path for it.
+      const fieldErrors = result.issues?.length ? issuesByField(result.issues) : { _form: result.error };
       setErrors(fieldErrors);
       const broken = steps.findIndex((entries) => entries.some(([key]) => fieldErrors[key]));
       if (broken >= 0 && broken !== step) setStep(broken);

package/templates/app/components/dashboard/resource-table.tsx

@@ -1,7 +1,7 @@
 import Link from "next/link";
 import { FileCell } from "@/components/dashboard/fields/file-cell";
 import { ArrowDownIcon, ArrowUpIcon, ChevronLeftIcon, ChevronRightIcon, ChevronsUpDownIcon, PlusIcon } from "lucide-react";
-import { clientResource, formatValue, optionLabel, statusTone, storedFields, type Resource, type StoredField } from "@flaredev/core";
+import { clientResource, formatValue, isAuthUserTarget, optionLabel, statusTone, storedFields, type Resource, type StoredField } from "@flaredev/core";
 import { isSortable } from "@/lib/resource/query";
 import { Alert, AlertDescription } from "@/components/ui/alert";
 import { Badge } from "@/components/ui/badge";
@@ -33,6 +33,7 @@ import { ResourceTableToolbar } from "./resource-table-toolbar";
 import { SaveViewButton } from "./save-view-button";
 import { RowActions } from "./row-actions";
 import { RowCheckbox, SelectAllCheckbox, SelectionBar, TableSelection } from "./table-selection";
+import { AUTH_USER_RELATION } from "@/lib/user-titles";
 
 type Column = { key: string; label: string; def: StoredField | { kind: "timestamp" } };
 
@@ -92,6 +93,11 @@ export async function ResourceTable({ resource, searchParams }: { resource: Reso
   const relations: Record<string, RelationMeta & { initialTitle?: string }> = {};
   for (const [key, def] of fields) {
     if (def.kind !== "belongsTo") continue;
+    if (isAuthUserTarget(def.target)) {
+      // The picker fills its own title from /api/users/<id>, so no lookup is needed here.
+      relations[key] = AUTH_USER_RELATION;
+      continue;
+    }
     const target = byName.get(def.target);
     if (!target) continue;
     relations[key] = { name: target.name, label: target.label, pluralLabel: target.pluralLabel, slug: target.slug, titleField: target.titleField };

package/templates/app/lib/api.ts

@@ -1,5 +1,9 @@
 import { headers } from "next/headers";
-import { can, type Policy } from "@flaredev/core";
+import { can, type Policy, rateFor, type Resource } from "@flaredev/core";
+import { PROBLEM_CODES, problemResponse } from "@flaredev/core";
+import { clientIp } from "@flaredev/core/security";
+import type { ResourceAction } from "@/lib/resource";
+import { checkRateLimit } from "@/lib/rate-limit";
 import type { Authorize } from "@/lib/resource/handlers";
 import { policies } from "@/policies";
 import { userFromApiKey } from "./api-keys";
@@ -53,10 +57,44 @@ export function policyFor(resourceName: string): Policy | undefined {
 export const authorize: Authorize = async ({ request, resource, action }) => {
   const session = await auth.api.getSession({ headers: request.headers });
   const viaKey = session ? null : await userFromApiKey(request.headers);
-  if (!session && !viaKey) return Response.json({ error: "Sign in required." }, { status: 401 });
+  if (!session && !viaKey) return problemResponse(401, "Sign in required.", PROBLEM_CODES.unauthenticated);
 
   const role = session ? ((session.user as { role?: string | null }).role ?? null) : viaKey!.role;
   if (!can(policyFor(resource.name), role, action)) {
-    return Response.json({ error: `Your role can't ${action} ${resource.pluralLabel.toLowerCase()}.` }, { status: 403 });
+    return problemResponse(403, `Your role can't ${action} ${resource.pluralLabel.toLowerCase()}.`, PROBLEM_CODES.forbidden);
   }
 };
+
+/**
+ * The rate limit a resource declares for this action, enforced.
+ *
+ * Returns a 429 to send back, or nothing when the call is within the limit — the same
+ * shape as `authorize`, so a route reads the two the same way.
+ *
+ * Counted per caller: the signed-in account where there is one, the client IP otherwise.
+ * So a limit on `create` is a limit on that person rather than on everyone sharing an
+ * office connection, and anonymous callers behind one address share a bucket, which is
+ * the right trade for an endpoint that does not know who is calling.
+ *
+ * Checked after `authorize`, deliberately. A request that is going to be refused anyway
+ * should not use up somebody's quota, and a flood with no session is the edge limiter's
+ * job (`flare gen security`) rather than this one's.
+ */
+export async function rateLimitGuard(context: { request: Request; resource: Resource; action: ResourceAction }): Promise<Response | undefined> {
+  const rate = rateFor(context.resource.rateLimit, context.action);
+  if (!rate) return undefined;
+
+  const account = await currentUser();
+  const caller = account?.id ?? clientIp(context.request) ?? "unknown";
+  const decision = await checkRateLimit(context.resource.name, context.action, caller, rate);
+  if (decision.allowed) return undefined;
+
+  return problemResponse(429, "Too many requests. Try again shortly.", PROBLEM_CODES.rateLimited, undefined, {
+    headers: {
+      "retry-after": String(decision.retryAfter),
+      // What the limit was, so a client can pace itself rather than guess.
+      "x-ratelimit-limit": String(rate.limit),
+      "x-ratelimit-remaining": "0",
+    },
+  });
+}

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

@@ -1,38 +1,60 @@
-/**
- * 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;
+/**
+ * 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 = {
+  /**
+   * Who may create an account.
+   *
+   * - `open` — anybody who finds the sign-up page. Right for a public product.
+   * - `invite` — only somebody holding an invitation link. An admin issues them from
+   *   /dashboard/invitations; see lib/invitations.ts.
+   * - `closed` — nobody. Accounts are made with `flare user:add <email>`.
+   *
+   * The first account is always allowed, whatever this says: an app nobody can sign into
+   * cannot be set up, and in `invite` mode there would be nobody to issue the invitation.
+   * Every later sign-up goes through this.
+   *
+   * Enforced where the account is created rather than on each sign-up route, so it holds
+   * for a password sign-up, a magic link, an email code and a social callback alike.
+   */
+  signup: "__SIGNUP__" as SignupMode,
+  /** 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";
+
+/** Who may create an account. See `authConfig.signup`. */
+export type SignupMode = "open" | "invite" | "closed";
+
+/** Whether the sign-up page should be offered at all. */
+export const signupOffered = authConfig.signup !== "closed";
+
+/** Whether any second factor can be set up. */
+export const twoFactorAvailable = authConfig.twoFactor.authenticator || authConfig.twoFactor.email;

package/templates/app/lib/auth.ts

@@ -1,4 +1,6 @@
 import { env, waitUntil } from "cloudflare:workers";
+import { cookies } from "next/headers";
+import { INVITE_COOKIE, invitationAllows, spendInvitation } from "./invitations";
 import { passkey } from "@better-auth/passkey";
 import { drizzleAdapter } from "@better-auth/drizzle-adapter";
 import { betterAuth } from "better-auth";
@@ -108,6 +110,50 @@ async function guardPassword(path: string, body: Record<string, unknown> | undef
   }
 }
 
+/**
+ * Whether this account may be created at all — `authConfig.signup`.
+ *
+ * Checked where the user row is written rather than on each sign-up route, because there
+ * are four ways to end up with a new account (a password sign-up, a magic link, an email
+ * code, a social callback) and gating them one by one is how one gets missed.
+ *
+ * **The first account is always allowed.** An app nobody can sign into cannot be set up,
+ * and in `invite` mode there would be nobody to issue the invitation. Everybody after
+ * them goes through this; the first account also becomes the admin (see below).
+ */
+async function assertSignUpAllowed(email: string): Promise<void> {
+  if (authConfig.signup === "open") return;
+
+  const [existing] = await getDb().select({ id: schema.user.id }).from(schema.user).limit(1);
+  if (!existing) return;
+
+  if (authConfig.signup === "closed") {
+    throw new APIError("FORBIDDEN", { message: "This app is not accepting new accounts." });
+  }
+
+  // `invite`: the token was put in a cookie when the invitation link was opened.
+  const token = (await cookies()).get(INVITE_COOKIE)?.value;
+  if (!(await invitationAllows(token, email))) {
+    throw new APIError("FORBIDDEN", { message: "You need an invitation to create an account here." });
+  }
+}
+
+/**
+ * Spend the invitation this sign-up used, once the account exists.
+ *
+ * Separate from the check because the account does not exist yet when the check runs: an
+ * invitation has to survive a sign-up that fails validation, and only be used up by one
+ * that worked.
+ */
+async function spendUsedInvitation(): Promise<void> {
+  if (authConfig.signup !== "invite") return;
+  const jar = await cookies();
+  const token = jar.get(INVITE_COOKIE)?.value;
+  if (!token) return;
+  await spendInvitation(token);
+  jar.delete(INVITE_COOKIE);
+}
+
 /**
  * The first account to exist becomes the admin.
  *
@@ -183,6 +229,17 @@ export const auth = betterAuth({
     // Let emails and other deferred work finish after the response is sent.
     backgroundTasks: { handler: waitUntil },
   },
+  databaseHooks: {
+    user: {
+      create: {
+        // The one place every sign-up passes through, whichever route it came in on.
+        before: async (user: { email: string }) => {
+          await assertSignUpAllowed(user.email);
+          return { data: user };
+        },
+      },
+    },
+  },
   hooks: {
     before: createAuthMiddleware(async (ctx) => {
       if (disabledPath(ctx.path)) throw new APIError("NOT_FOUND", { message: "This sign-in method isn't enabled." });
@@ -192,12 +249,20 @@ export const auth = betterAuth({
     // link, a social callback — so this asks after all of them rather than guessing which.
     after: createAuthMiddleware(async () => {
       await promoteFirstUser();
+      await spendUsedInvitation();
     }),
   },
   plugins: [
-    // Adds user.role (default "user") and admin APIs. The /admin area allows ADMIN_ROLES (lib/admin.ts).
+    // Adds user.role (default "user") and admin APIs. The dashboard allows ADMIN_ROLES (lib/dashboard.ts).
     admin({ defaultRole: "user", adminRoles: ["admin"] }),
-    magicLink({ sendMagicLink: ({ email, url }) => sendMagicLink({ email, url }), expiresIn: 5 * 60, disableSignUp: false }),
+    // disableSignUp follows the mode: a magic link to an address with no account would
+    // otherwise create one, which is a sign-up through a side door. In `invite` mode the
+    // link is still how an invited person signs *in* — they have an account by then.
+    magicLink({
+      sendMagicLink: ({ email, url }) => sendMagicLink({ email, url }),
+      expiresIn: 5 * 60,
+      disableSignUp: authConfig.signup !== "open",
+    }),
     emailOTP({ sendVerificationOTP: (data) => sendEmailCode(data), otpLength: 6, expiresIn: 5 * 60, allowedAttempts: 5 }),
     twoFactor({
       issuer: "__APP_NAME__",

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

@@ -11,9 +11,14 @@ export interface DashboardLink {
 export const generatedDashboardLinks: DashboardLink[] = [];
 // generated:end
 
+import { authConfig } from "./auth-config";
+
 /** Links shown under "Platform" in the dashboard sidebar. */
 export const dashboardLinks: DashboardLink[] = [
   { label: "Costs", href: "/dashboard/costs", icon: "wallet" },
+  // Only where invitations are the way in; the page explains itself for the other two
+  // modes, but there is no reason to send anybody to it.
+  ...(authConfig.signup === "invite" ? [{ label: "Invitations", href: "/dashboard/invitations", icon: "mail" }] : []),
   ...generatedDashboardLinks,
   { label: "API reference", href: "/api/reference", icon: "book" },
 ];

package/templates/app/lib/invitations.ts

@@ -0,0 +1,142 @@
+// 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.
+
+/**
+ * Invitations, for an app whose sign-up is `invite` (see lib/auth-config.ts).
+ *
+ * **They live in the `verification` table**, which Better Auth already has and already
+ * uses for exactly this shape of thing: a single-use token with an expiry. Reusing it
+ * means invitations need no table of their own and so no migration — an app switching to
+ * `invite` changes one line in auth-config.ts and nothing else.
+ *
+ * Rows are keyed `invite:<hash>`. Only the hash is stored, never the token itself, for the
+ * same reason a password is not: a leaked database should not be a pile of working
+ * invitations.
+ *
+ * The flow:
+ *
+ *   1. An admin creates one. `createInvitation` returns the token once — it is not
+ *      recoverable afterwards, which is why the link is shown on screen to copy.
+ *   2. The invited person opens the link. `/invite/[token]` puts the token in a
+ *      short-lived cookie and sends them to the sign-up page.
+ *   3. They sign up. `lib/auth.ts` reads the cookie, checks the invitation, and lets the
+ *      account be created — then spends it, so the link cannot be used twice.
+ */
+import { and, eq, like, lt } from "drizzle-orm";
+import { getDb } from "@/db";
+import { verification } from "@/db/auth-schema";
+
+/** How long an invitation is good for, unless you say otherwise. */
+export const DEFAULT_INVITE_DAYS = 7;
+
+/** The cookie an opened invitation link leaves behind, for the sign-up that follows. */
+export const INVITE_COOKIE = "flare_invite";
+
+/** How long that cookie lives: long enough to fill in a form, not long enough to forget. */
+export const INVITE_COOKIE_MAX_AGE = 60 * 60;
+
+const KEY_PREFIX = "invite:";
+
+/**
+ * WebCrypto rather than node:crypto, so the same file runs on Workers and on Node
+ * without a compatibility flag deciding whether it does.
+ */
+const randomToken = () => {
+  const bytes = crypto.getRandomValues(new Uint8Array(32));
+  return btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+
+/** Only the hash is stored, so a copy of the table is not a pile of working invitations. */
+async function hash(token: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(token));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+const key = async (token: string) => `${KEY_PREFIX}${await hash(token)}`;
+
+/** What an invitation is for: one address, or anybody who has the link. */
+export type InviteFor = { email: string } | { anyone: true };
+
+/** An invitation. The token is returned once and never stored. */
+export interface CreatedInvitation {
+  token: string;
+  expiresAt: Date;
+  /** Who it is for, or null when anybody with the link may use it. */
+  email: string | null;
+}
+
+/** Create one. The returned token is the only copy. */
+export async function createInvitation(options: { for: InviteFor; days?: number }): Promise<CreatedInvitation> {
+  const token = randomToken();
+  const email = "email" in options.for ? options.for.email.trim().toLowerCase() : null;
+  const expiresAt = new Date(Date.now() + (options.days ?? DEFAULT_INVITE_DAYS) * 86_400_000);
+  await getDb()
+    .insert(verification)
+    .values({
+      id: crypto.randomUUID(),
+      identifier: await key(token),
+      // `*` rather than an empty string, so "for anybody" is a value and not a mistake.
+      value: email ?? "*",
+      expiresAt,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+  return { token, expiresAt, email };
+}
+
+/** The link to send somebody, given the app's own origin. */
+export const invitationLink = (baseUrl: string, token: string) => `${baseUrl.replace(/\/$/, "")}/invite/${token}`;
+
+/**
+ * Whether this token is a live invitation for this email address.
+ *
+ * Checked, not spent: the account does not exist yet when this is asked, and an
+ * invitation should survive a sign-up that fails validation.
+ */
+export async function invitationAllows(token: string | undefined, email: string): Promise<boolean> {
+  if (!token) return false;
+  const rows = await getDb().select().from(verification).where(eq(verification.identifier, await key(token))).limit(1);
+  const row = rows[0];
+  if (!row) return false;
+  if (row.expiresAt.getTime() <= Date.now()) return false;
+  // An invitation addressed to somebody is for them alone; `*` is for whoever has the link.
+  return row.value === "*" || row.value === email.trim().toLowerCase();
+}
+
+/** Spend it, so the link cannot be used again. Called once the account exists. */
+export async function spendInvitation(token: string | undefined): Promise<void> {
+  if (!token) return;
+  await getDb().delete(verification).where(eq(verification.identifier, await key(token)));
+}
+
+/** Invitations an admin can see: live ones, newest first. Never the tokens. */
+export async function listInvitations(): Promise<{ id: string; email: string | null; expiresAt: Date; createdAt: Date }[]> {
+  const rows = await getDb().select().from(verification).where(like(verification.identifier, `${KEY_PREFIX}%`));
+  return rows
+    .filter((row) => row.expiresAt.getTime() > Date.now())
+    .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())
+    .map((row) => ({ id: row.id, email: row.value === "*" ? null : row.value, expiresAt: row.expiresAt, createdAt: row.createdAt }));
+}
+
+/** Revoke one by its row id, so a link sent to the wrong address stops working. */
+export async function revokeInvitation(id: string): Promise<void> {
+  await getDb().delete(verification).where(eq(verification.id, id));
+}
+
+/**
+ * Drop invitations that have expired.
+ *
+ * Only rows under the `invite:` prefix — the rest of this table is Better Auth's, and
+ * deleting its tokens would sign people out and break magic links.
+ */
+export async function pruneInvitations(): Promise<void> {
+  await getDb()
+    .delete(verification)
+    .where(and(like(verification.identifier, `${KEY_PREFIX}%`), lt(verification.expiresAt, new Date())));
+}