@clubedge/create-clubedge-app 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.32.0
+
+- **Pluggable authentication**: default to Starter `v0.21.0` (#93). Authentication now has four providers behind one interface, so the pages, settings, payments, and jobs stay the same whichever signs users in:
+  - `--auth supabase` and `--auth better-auth`, as before.
+  - **`--auth firebase`** (new): Firebase Authentication from the server, with session cookies. `pnpm auth:dev` starts the Auth Emulator, so development needs no Firebase account. Reset and confirmation emails go through the app's email module.
+  - **`--auth appwrite`** (new): Appwrite accounts on Appwrite Cloud or your own server, with session cookies and an API key. Appwrite sends its own emails.
+  - `@clubedge/auth/conformance` is one test suite every auth provider passes: sign-up and sign-in, sign-out, reset through the emailed link, password changes that sign out other sessions, and account deletion. The Starter's CI runs it against all four, including Appwrite Cloud.
+  - Stripe payments work with every provider.
+  - Switch an existing project with `pnpm clubedge add auth firebase` or `pnpm clubedge add auth appwrite`. After `pnpm clubedge upgrade`, run `pnpm db:migrate`: `users.auth_user_id` becomes text, since Firebase's and Appwrite's user ids aren't UUIDs.
+
 ## 0.31.0
 
 - **Pluggable background jobs**: default to Starter `v0.20.0` (#91). The jobs module now has three providers behind one interface, so job definitions, routes, and the dashboard's jobs card stay the same whichever runs them:

package/README.md

@@ -129,7 +129,7 @@ pnpm dlx @clubedge/create-clubedge-app my-app --yes --no-git --framework tanstac
 pnpm dlx @clubedge/create-clubedge-app my-app --ref main
 
 # Reproduce a specific Starter release or commit
-pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.20.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.21.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -148,7 +148,7 @@ pnpm clubedge add email resend payments stripe              # several modules as
 pnpm clubedge remove storage payments
 pnpm dlx @clubedge/create-clubedge-app add infra local --dry-run
 pnpm dlx @clubedge/create-clubedge-app@latest upgrade        # to the newest CLI's Starter release
-pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.20.0 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.21.0 # or a specific tag, branch, or commit
 ```
 
 The CLI renders the project twice, from the Starter commit and modules recorded in your `package.json` and from the new state, and merges the difference into your project. The new state has other modules for `add` and `remove`, and the newer Starter with the same modules for `upgrade`. Modules a newer Starter introduces start as `none` where possible, so an upgrade never adds a service on its own.
@@ -259,27 +259,27 @@ Projects created with `--infra neon` also have `.github/workflows/preview.yml`,
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.31.0
+create-clubedge-app v0.32.0
         |
         v
-Clubedge Starter v0.20.0
-commit 166fd38a1b4e8e94e6c411ff26f978ed52ce1249
+Clubedge Starter v0.21.0
+commit 8f1201f2d526347ccf0365a701aaa20e883f8d8a
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.31.0` | `clubedge-starter@v0.20.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.32.0` | `clubedge-starter@v0.21.0` | The CLI's required, tested default |
 
 This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter `main`.
 
-The `v0.20.0` tag is expected to resolve to commit
-`166fd38a1b4e8e94e6c411ff26f978ed52ce1249`. The CLI verifies this before
+The `v0.21.0` tag is expected to resolve to commit
+`8f1201f2d526347ccf0365a701aaa20e883f8d8a`. The CLI verifies this before
 scaffolding with the default reference and fails rather than silently using a
 moved tag.
 
-When the Starter changes, its maintainers first publish a new versioned release, such as `v0.20.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.21.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
 
 Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, framework, and modules in `package.json` and `README.md`.
 
@@ -334,7 +334,7 @@ CI packs the CLI with `npm pack`, scaffolds clean projects from the packed tarba
 1. Make and validate changes in `clubedge-starter`.
 2. Run lint, typecheck, unit tests, browser tests, and production build.
 3. Update the Starter package versions.
-4. Commit `main`, create a release tag such as `v0.20.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.21.0`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -376,6 +376,7 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.30.0 | v0.19.0 | `--infra neon` with a free Neon database, the `neon` command, `deploy --preview` with a Neon branch per preview |
 | 0.30.1 | v0.19.1 | Railway previews work with a workspace token and answer on the port their domain targets |
 | 0.31.0 | v0.20.0 | Pluggable background jobs: `--jobs bullmq` and `--jobs inngest` next to pg-boss, and a conformance suite every provider passes |
+| 0.32.0 | v0.21.0 | Pluggable authentication: `--auth firebase` and `--auth appwrite` next to Supabase and Better Auth, and a conformance suite every provider passes |
 | next | | Show the Starter's version of a conflicted file next to yours |
 
 ## Community

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Create a Next.js or TanStack Start application from the Clubedge Starter reference implementation.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
@@ -22,8 +22,8 @@
   },
   "clubedge": {
     "starterRepository": "Clubedge/clubedge-starter",
-    "starterRef": "v0.20.0",
-    "starterCommit": "166fd38a1b4e8e94e6c411ff26f978ed52ce1249"
+    "starterRef": "v0.21.0",
+    "starterCommit": "8f1201f2d526347ccf0365a701aaa20e883f8d8a"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/.env.example

@@ -35,6 +35,27 @@ BETTER_AUTH_SECRET=
 BETTER_AUTH_REQUIRE_EMAIL_VERIFICATION=false # clubedge:only email!=none
 # clubedge:end
 
+# clubedge:if auth=firebase
+# Firebase Authentication. In development, pnpm auth:dev starts the Auth Emulator, which these
+# values point at. In production, set your project's id and Web API key (Project settings,
+# General) and a service account (Project settings, Service accounts), and remove
+# FIREBASE_AUTH_EMULATOR_HOST.
+FIREBASE_PROJECT_ID=demo-clubedge
+FIREBASE_API_KEY=demo-api-key
+FIREBASE_CLIENT_EMAIL=
+FIREBASE_PRIVATE_KEY=
+FIREBASE_AUTH_EMULATOR_HOST=127.0.0.1:9099
+# clubedge:end
+
+# clubedge:if auth=appwrite
+# Appwrite (https://appwrite.io), on Appwrite Cloud or your own server. Create a project, add a
+# Web platform for this app's hostname (localhost in development), and an API key with the
+# sessions.write and users.write scopes. Appwrite sends its own emails (its SMTP settings).
+APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
+APPWRITE_PROJECT_ID=
+APPWRITE_API_KEY=
+# clubedge:end
+
 # clubedge:if cache=redis
 # Optional cache and rate limits (Redis protocol; rediss:// enables TLS). Without it, both use
 # process memory. Upstash example: rediss://default:YOUR_PASSWORD@your-database.upstash.io:6379

package/template/.github/workflows/ci.yml

@@ -22,6 +22,8 @@ jobs:
     env:
       DATABASE_URL: postgresql://postgres:postgres@127.0.0.1:5432/postgres
       REDIS_URL: redis://127.0.0.1:6379 # clubedge:only jobs=bullmq
+      FIREBASE_AUTH_EMULATOR_HOST: 127.0.0.1:9099 # clubedge:only auth=firebase
+      FIREBASE_PROJECT_ID: demo-clubedge # clubedge:only auth=firebase
     steps:
       - uses: actions/checkout@v7
       - uses: pnpm/action-setup@v6
@@ -33,6 +35,15 @@ jobs:
       - run: pnpm format:check
       - run: pnpm lint
       - run: pnpm typecheck
+      # clubedge:if auth=firebase
+      # Firebase's Auth Emulator (firebase.json), for the Firebase provider's conformance tests.
+      - name: Start the Firebase Auth Emulator
+        run: |
+          nohup npx --yes firebase-tools@15 emulators:start --only auth --project demo-clubedge \
+            > "$RUNNER_TEMP/firebase.log" 2>&1 &
+          timeout 240 bash -c 'until curl --silent --output /dev/null http://127.0.0.1:9099/; do sleep 2; done' \
+            || { cat "$RUNNER_TEMP/firebase.log"; exit 1; }
+      # clubedge:end
       - run: pnpm test
       # Build the way the app is developed: with the env example copied into place.
       - run: cp .env.example apps/web/.env.local

package/template/README.md

@@ -57,6 +57,8 @@ Every combination in the CI matrix is generated as a real project and runs its f
 
 - Supabase Auth with server-verified sessions in secure cookies, a protected dashboard, and rate-limited sign-in. <!-- clubedge:only auth=supabase -->
 - Better Auth with users and sessions in your own PostgreSQL, secure session cookies, a protected dashboard, and rate-limited sign-in. <!-- clubedge:only auth=better-auth -->
+- Firebase Authentication through the app's own pages, with server-side session cookies, a protected dashboard, and rate-limited sign-in; the Auth Emulator in development. <!-- clubedge:only auth=firebase -->
+- Appwrite accounts through the app's own pages, on Appwrite Cloud or your own server, with server-side session cookies, a protected dashboard, and rate-limited sign-in. <!-- clubedge:only auth=appwrite -->
 - Password reset by email, and email verification that can be required before sign-in. <!-- clubedge:only auth=better-auth && email!=none -->
 - Password reset by email, sent by Supabase. <!-- clubedge:only auth=supabase -->
 - An account settings page: display name, password change, and account deletion. <!-- clubedge:only auth!=none -->
@@ -97,7 +99,7 @@ Pick modules when you create a project, and change them later with `pnpm clubedg
 | Module        | Options                                                   | Default    |
 | ------------- | --------------------------------------------------------- | ---------- |
 | Framework     | `next`, `tanstack-start`                                  | `next`     |
-| Auth          | `supabase`, `better-auth`, `none`                         | `supabase` |
+| Auth          | `supabase`, `better-auth`, `firebase`, `appwrite`, `none` | `supabase` |
 | Storage       | `s3`, `supabase`, `none`                                  | `s3`       |
 | Cache         | `redis`, `memory`                                         | `redis`    |
 | Email         | `smtp`, `resend`, `none`                                  | `smtp`     |
@@ -219,6 +221,12 @@ flowchart TB
   App -->|auth interface and server sessions| Auth[Better Auth]
   Auth -->|users and sessions| DB
   %% clubedge:end
+  %% clubedge:if auth=firebase
+  App -->|auth interface and server sessions| Auth[Firebase Authentication]
+  %% clubedge:end
+  %% clubedge:if auth=appwrite
+  App -->|auth interface and server sessions| Auth[Appwrite]
+  %% clubedge:end
   %% clubedge:if cache=redis
   App -->|cache and rate limits| Redis[(Redis, or memory)]
   %% clubedge:end
@@ -348,6 +356,8 @@ The TanStack Start app is `apps/start`, run with `pnpm --filter @clubedge/start
 - `packages/auth/`: `AuthProvider` and `CookieStore` interfaces <!-- clubedge:only auth!=none -->
 - `packages/auth-supabase/`: Supabase Auth adapter <!-- clubedge:only auth=supabase -->
 - `packages/auth-better-auth/`: Better Auth adapter, with its own tables and migrations <!-- clubedge:only auth=better-auth -->
+- `packages/auth-firebase/`: Firebase Authentication adapter, with session cookies <!-- clubedge:only auth=firebase -->
+- `packages/auth-appwrite/`: Appwrite adapter, with session cookies <!-- clubedge:only auth=appwrite -->
 - `packages/storage/`: `StorageProvider` interface <!-- clubedge:only storage!=none -->
 - `packages/storage-s3/`: S3-compatible storage adapter <!-- clubedge:only storage=s3 -->
 - `packages/storage-supabase/`: Supabase Storage adapter <!-- clubedge:only storage=supabase -->

package/template/SETUP.md

@@ -43,6 +43,8 @@ The variables are:
 - `NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` (for sign-in): see [Supabase Auth](#supabase-auth). <!-- clubedge:only framework=next && auth=supabase -->
 - `SUPABASE_URL` and `SUPABASE_PUBLISHABLE_KEY` (for sign-in): see [Supabase Auth](#supabase-auth). <!-- clubedge:only framework=tanstack-start && auth=supabase -->
 - `BETTER_AUTH_SECRET` (for sign-in): see [Better Auth](#better-auth). <!-- clubedge:only auth=better-auth -->
+- `FIREBASE_PROJECT_ID`, `FIREBASE_API_KEY`, and in production a service account: see [Firebase Authentication](#firebase-authentication). <!-- clubedge:only auth=firebase -->
+- `APPWRITE_ENDPOINT`, `APPWRITE_PROJECT_ID`, and `APPWRITE_API_KEY` (for sign-in): see [Appwrite](#appwrite). <!-- clubedge:only auth=appwrite -->
 - `REDIS_URL` (optional): see [Redis](#redis). <!-- clubedge:only cache=redis -->
 - `SMTP_URL` and `EMAIL_FROM` (for sending email): see [Email](#email). <!-- clubedge:only email=smtp -->
 - `RESEND_API_KEY` and `EMAIL_FROM` (for sending email): see [Email](#email). <!-- clubedge:only email=resend -->
@@ -103,6 +105,41 @@ These emails are sent by the `send-email` [background job](#background-jobs), so
 
 <!-- clubedge:end -->
 
+<!-- clubedge:if auth=firebase -->
+
+## Firebase Authentication
+
+[Firebase Authentication](https://firebase.google.com/docs/auth) checks passwords and keeps the accounts; the app's own pages sign users in, and the server holds the session in an HTTP-only cookie (a Firebase session cookie, checked for revocation on each request). Password reset and email confirmation links are generated by Firebase and sent through the [email module](#email), so they open the app's own pages and need no setup in the Firebase console. <!-- clubedge:only email!=none -->
+[Firebase Authentication](https://firebase.google.com/docs/auth) checks passwords and keeps the accounts; the app's own pages sign users in, and the server holds the session in an HTTP-only cookie (a Firebase session cookie, checked for revocation on each request). Without the email module there is no password reset. <!-- clubedge:only email=none -->
+
+In development, `pnpm auth:dev` starts Firebase's Auth Emulator (`firebase.json`, port 9099), which the example environment points at: no Firebase project or account is needed. Accounts live in memory until it stops.
+
+In production:
+
+1. In the [Firebase console](https://console.firebase.google.com), create a project and turn on **Email/Password** under Authentication, Sign-in method.
+2. Set `FIREBASE_PROJECT_ID` and `FIREBASE_API_KEY` (the Web API key, under Project settings, General).
+3. Under Project settings, Service accounts, generate a private key, and set `FIREBASE_CLIENT_EMAIL` and `FIREBASE_PRIVATE_KEY` from it (the key's line breaks as `\n` are fine).
+4. Remove `FIREBASE_AUTH_EMULATOR_HOST`; `pnpm check:env` refuses it in production.
+
+Changing a password or resetting it signs out every other session; deleting an account removes it from Firebase after the app's own data for the user.
+
+<!-- clubedge:end -->
+
+<!-- clubedge:if auth=appwrite -->
+
+## Appwrite
+
+[Appwrite](https://appwrite.io) keeps the accounts, on Appwrite Cloud or your own server; the app's own pages sign users in, and the server holds the session's secret in an HTTP-only cookie (`a_session_<project>`). Appwrite sends the email confirmation and password recovery emails itself, through its SMTP settings, with links back to the app's `/auth/callback` and `/reset-password`.
+
+1. Create a project in [Appwrite Cloud](https://cloud.appwrite.io) (free tier) or on your Appwrite server.
+2. Under Overview, Platforms, add a **Web** platform for the app's hostname: `localhost` in development, your domain in production. Appwrite only sends links to registered hostnames.
+3. Under Overview, Integrations, API keys, create a key with the `sessions.write` and `users.write` scopes.
+4. Set `APPWRITE_ENDPOINT` (such as `https://cloud.appwrite.io/v1`), `APPWRITE_PROJECT_ID`, and `APPWRITE_API_KEY`. The key stays on the server.
+
+Changing or resetting a password signs out every other session; deleting an account removes the Appwrite user after the app's own data for them. A self-hosted Appwrite sends email only once its SMTP settings (`_APP_SMTP_HOST` and the rest) are set.
+
+<!-- clubedge:end -->
+
 ## Local services
 
 <!-- clubedge:if infra=docker -->

package/template/apps/start/.env.example

@@ -37,6 +37,27 @@ BETTER_AUTH_SECRET=
 BETTER_AUTH_REQUIRE_EMAIL_VERIFICATION=false # clubedge:only email!=none
 # clubedge:end
 
+# clubedge:if auth=firebase
+# Firebase Authentication. In development, pnpm auth:dev starts the Auth Emulator, which these
+# values point at. In production, set your project's id and Web API key (Project settings,
+# General) and a service account (Project settings, Service accounts), and remove
+# FIREBASE_AUTH_EMULATOR_HOST.
+FIREBASE_PROJECT_ID=demo-clubedge
+FIREBASE_API_KEY=demo-api-key
+FIREBASE_CLIENT_EMAIL=
+FIREBASE_PRIVATE_KEY=
+FIREBASE_AUTH_EMULATOR_HOST=127.0.0.1:9099
+# clubedge:end
+
+# clubedge:if auth=appwrite
+# Appwrite (https://appwrite.io), on Appwrite Cloud or your own server. Create a project, add a
+# Web platform for this app's hostname (localhost in development), and an API key with the
+# sessions.write and users.write scopes. Appwrite sends its own emails (its SMTP settings).
+APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
+APPWRITE_PROJECT_ID=
+APPWRITE_API_KEY=
+# clubedge:end
+
 # clubedge:if cache=redis
 # Optional cache and rate limits (Redis protocol; rediss:// enables TLS). Without it, both use
 # process memory. Upstash example: rediss://default:YOUR_PASSWORD@your-database.upstash.io:6379

package/template/apps/start/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/start",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",
@@ -14,7 +14,9 @@
   },
   "dependencies": {
     "@clubedge/auth": "workspace:*",
+    "@clubedge/auth-appwrite": "workspace:*",
     "@clubedge/auth-better-auth": "workspace:*",
+    "@clubedge/auth-firebase": "workspace:*",
     "@clubedge/auth-supabase": "workspace:*",
     "@clubedge/cache": "workspace:*",
     "@clubedge/cache-redis": "workspace:*",

package/template/apps/start/src/env/auth.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { optional, parseEnv } from "./server";
-// clubedge:if auth=better-auth
+// clubedge:if auth=better-auth|firebase|appwrite
 import { getAppUrl } from "./server";
 // clubedge:end
 
@@ -60,3 +60,68 @@ export function getBetterAuthEnv(): BetterAuthEnv | null {
   };
 }
 // clubedge:end
+
+// clubedge:if auth=firebase
+const firebaseAuthSchema = z.object({
+  FIREBASE_PROJECT_ID: optional(z.string()),
+  // The project's Web API key: Project settings, General.
+  FIREBASE_API_KEY: optional(z.string()),
+  // A service account: Project settings, Service accounts. Not needed with the emulator.
+  FIREBASE_CLIENT_EMAIL: optional(z.string()),
+  FIREBASE_PRIVATE_KEY: optional(z.string()),
+  // The Auth Emulator (pnpm auth:dev) in development, such as 127.0.0.1:9099.
+  FIREBASE_AUTH_EMULATOR_HOST: optional(z.string()),
+});
+
+export interface FirebaseAuthEnv {
+  projectId: string;
+  apiKey: string;
+  clientEmail?: string;
+  privateKey?: string;
+  emulatorHost?: string;
+  baseUrl: string;
+}
+
+/** Firebase Auth settings, or null until the project id and Web API key are set. */
+export function getFirebaseAuthEnv(): FirebaseAuthEnv | null {
+  const env = parseEnv(firebaseAuthSchema, "Firebase Auth");
+  if (!env.FIREBASE_PROJECT_ID || !env.FIREBASE_API_KEY) return null;
+  return {
+    projectId: env.FIREBASE_PROJECT_ID,
+    apiKey: env.FIREBASE_API_KEY,
+    ...(env.FIREBASE_CLIENT_EMAIL ? { clientEmail: env.FIREBASE_CLIENT_EMAIL } : {}),
+    ...(env.FIREBASE_PRIVATE_KEY ? { privateKey: env.FIREBASE_PRIVATE_KEY } : {}),
+    ...(env.FIREBASE_AUTH_EMULATOR_HOST ? { emulatorHost: env.FIREBASE_AUTH_EMULATOR_HOST } : {}),
+    baseUrl: getAppUrl(),
+  };
+}
+// clubedge:end
+
+// clubedge:if auth=appwrite
+const appwriteAuthSchema = z.object({
+  // The API endpoint, such as https://cloud.appwrite.io/v1 or your server's /v1.
+  APPWRITE_ENDPOINT: optional(z.url()),
+  APPWRITE_PROJECT_ID: optional(z.string()),
+  // An API key with the sessions.write and users.write scopes (Overview, Integrations, API keys).
+  APPWRITE_API_KEY: optional(z.string()),
+});
+
+export interface AppwriteAuthEnv {
+  endpoint: string;
+  projectId: string;
+  apiKey: string;
+  baseUrl: string;
+}
+
+/** Appwrite settings, or null until the endpoint, project, and API key are set. */
+export function getAppwriteAuthEnv(): AppwriteAuthEnv | null {
+  const env = parseEnv(appwriteAuthSchema, "Appwrite");
+  if (!env.APPWRITE_ENDPOINT || !env.APPWRITE_PROJECT_ID || !env.APPWRITE_API_KEY) return null;
+  return {
+    endpoint: env.APPWRITE_ENDPOINT,
+    projectId: env.APPWRITE_PROJECT_ID,
+    apiKey: env.APPWRITE_API_KEY,
+    baseUrl: getAppUrl(),
+  };
+}
+// clubedge:end

package/template/apps/start/src/env/production.ts

@@ -23,6 +23,17 @@ export function requiredVariables(env: Env): Requirement[] {
     // clubedge:if auth=better-auth
     { key: "BETTER_AUTH_SECRET", use: "Better Auth sessions" },
     // clubedge:end
+    // clubedge:if auth=appwrite
+    { key: "APPWRITE_ENDPOINT", use: "Appwrite", url: true },
+    { key: "APPWRITE_PROJECT_ID", use: "Appwrite" },
+    { key: "APPWRITE_API_KEY", use: "Appwrite" },
+    // clubedge:end
+    // clubedge:if auth=firebase
+    { key: "FIREBASE_PROJECT_ID", use: "Firebase Authentication" },
+    { key: "FIREBASE_API_KEY", use: "Firebase Authentication" },
+    { key: "FIREBASE_CLIENT_EMAIL", use: "Firebase Authentication (the service account)" },
+    { key: "FIREBASE_PRIVATE_KEY", use: "Firebase Authentication (the service account)" },
+    // clubedge:end
     // clubedge:if cache=redis
     { key: "REDIS_URL", use: "the cache and rate limits", url: true },
     // clubedge:end
@@ -105,6 +116,14 @@ export function checkProductionEnv(env: Env): ProductionEnvCheck {
     invalid.push("INNGEST_DEV is set: production uses Inngest Cloud's keys, so remove it");
   }
   // clubedge:end
+  // clubedge:if auth=firebase
+  // The emulator only runs on a developer's machine.
+  if (env.FIREBASE_AUTH_EMULATOR_HOST?.trim()) {
+    invalid.push(
+      "FIREBASE_AUTH_EMULATOR_HOST is set: production uses your Firebase project, so remove it",
+    );
+  }
+  // clubedge:end
   // clubedge:if auth=better-auth
   const secret = env.BETTER_AUTH_SECRET?.trim();
   if (secret && secret.length < 32) invalid.push("BETTER_AUTH_SECRET needs at least 32 characters");

package/template/apps/start/src/routes/reset-password.tsx

@@ -1,4 +1,5 @@
 import { CircleAlert } from "lucide-react";
+import { linkToken } from "@clubedge/auth";
 import { Link, createFileRoute } from "@tanstack/react-router";
 
 import { AuthForm, PasswordField, SubmitButton } from "@/components/auth/auth-form-controls";
@@ -15,7 +16,8 @@ const asString = (value: unknown) => (typeof value === "string" ? value : undefi
 export const Route = createFileRoute("/reset-password")({
   validateSearch: (search: Record<string, unknown>): { error?: string; token?: string } => ({
     error: asString(search.error),
-    token: asString(search.token),
+    // Appwrite's links carry userId and secret instead of a token.
+    token: linkToken(search, "token") ?? undefined,
   }),
   component: ResetPasswordPage,
 });

package/template/apps/start/src/server/auth-email.ts

@@ -1,5 +1,5 @@
 import "@tanstack/react-start/server-only";
-import type { AuthEmailSender } from "@clubedge/auth-better-auth";
+import type { AuthEmailSender } from "@clubedge/auth";
 // clubedge:if email!=none && jobs=none
 import { email } from "@/server/email";
 // clubedge:end
@@ -9,7 +9,7 @@ import { getJobs } from "@/server/jobs";
 // clubedge:end
 
 /**
- * How Better Auth sends verification and password reset emails: through the email module, or
+ * How the auth provider sends verification and password reset emails (Better Auth, Firebase): through the email module, or
  * not at all without one, which turns both features off.
  */
 export function authEmailSender(): AuthEmailSender | undefined {

package/template/apps/start/src/server/auth-forms.ts

@@ -1,4 +1,5 @@
 import "@tanstack/react-start/server-only";
+import { linkToken } from "@clubedge/auth";
 import { z } from "zod";
 import { getClientIp, safeRedirectPath, reportError } from "@clubedge/core";
 import { getAppUrl } from "@/env/server";
@@ -159,7 +160,8 @@ export async function handleSignOut(): Promise<Response> {
 
 export async function handleAuthCallback(request: Request): Promise<Response> {
   const url = new URL(request.url);
-  const code = url.searchParams.get("code");
+  // Appwrite's links carry userId and secret instead of a code.
+  const code = linkToken(url.searchParams, "code");
   const next = safeRedirectPath(url.searchParams.get("next"));
 
   if (code && isAuthConfigured()) {

package/template/apps/start/src/server/variants/auth.appwrite.ts

@@ -0,0 +1,42 @@
+import "@tanstack/react-start/server-only";
+import type { AuthProvider, AuthUser } from "@clubedge/auth";
+import { createAppwriteAuth } from "@clubedge/auth-appwrite";
+import { AppError, reportError } from "@clubedge/core";
+import { getAppwriteAuthEnv } from "@/env/auth";
+import { requestCookieStore } from "@/server/cookies";
+
+export type { AuthUser } from "@clubedge/auth";
+
+export function isAuthConfigured(): boolean {
+  return getAppwriteAuthEnv() !== null;
+}
+
+/** Request-scoped auth provider. Throws when authentication is not configured. */
+export function getAuth(): AuthProvider {
+  const env = getAppwriteAuthEnv();
+  if (!env) throw new Error("Appwrite is not configured.");
+  return createAppwriteAuth({ ...env, cookies: requestCookieStore() });
+}
+
+/** Validates the session. Runs once per request from src/start.ts. */
+export async function refreshAuthSession(): Promise<void> {
+  if (!isAuthConfigured()) return;
+  try {
+    await getAuth().refreshSession();
+  } catch (error) {
+    // Pages still render; protected handlers re-check the user and reject when needed.
+    reportError(error, { message: "Session refresh failed" });
+  }
+}
+
+export async function getCurrentUser(): Promise<AuthUser | null> {
+  if (!isAuthConfigured()) return null;
+  return getAuth().getUser();
+}
+
+/** For server functions and routes: throws a 401 AppError when signed out. */
+export async function requireUser(): Promise<AuthUser> {
+  const user = await getCurrentUser();
+  if (!user) throw new AppError("Authentication required.", "UNAUTHENTICATED", 401);
+  return user;
+}

package/template/apps/start/src/server/variants/auth.firebase.ts

@@ -0,0 +1,49 @@
+import "@tanstack/react-start/server-only";
+import type { AuthProvider, AuthUser } from "@clubedge/auth";
+import { createFirebaseAuth } from "@clubedge/auth-firebase";
+import { siteConfig } from "@/config/site";
+import { authEmailSender } from "@/server/auth-email";
+import { AppError, reportError } from "@clubedge/core";
+import { getFirebaseAuthEnv } from "@/env/auth";
+import { requestCookieStore } from "@/server/cookies";
+
+export type { AuthUser } from "@clubedge/auth";
+
+export function isAuthConfigured(): boolean {
+  return getFirebaseAuthEnv() !== null;
+}
+
+/** Request-scoped auth provider. Throws when authentication is not configured. */
+export function getAuth(): AuthProvider {
+  const env = getFirebaseAuthEnv();
+  if (!env) throw new Error("Firebase Auth is not configured.");
+  return createFirebaseAuth({
+    ...env,
+    cookies: requestCookieStore(),
+    sendEmail: authEmailSender(),
+    appName: siteConfig.name,
+  });
+}
+
+/** Validates the session. Runs once per request from src/start.ts. */
+export async function refreshAuthSession(): Promise<void> {
+  if (!isAuthConfigured()) return;
+  try {
+    await getAuth().refreshSession();
+  } catch (error) {
+    // Pages still render; protected handlers re-check the user and reject when needed.
+    reportError(error, { message: "Session refresh failed" });
+  }
+}
+
+export async function getCurrentUser(): Promise<AuthUser | null> {
+  if (!isAuthConfigured()) return null;
+  return getAuth().getUser();
+}
+
+/** For server functions and routes: throws a 401 AppError when signed out. */
+export async function requireUser(): Promise<AuthUser> {
+  const user = await getCurrentUser();
+  if (!user) throw new AppError("Authentication required.", "UNAUTHENTICATED", 401);
+  return user;
+}

package/template/apps/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/web",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "private": true,
   "license": "Apache-2.0",
   "scripts": {
@@ -13,7 +13,9 @@
   },
   "dependencies": {
     "@clubedge/auth": "workspace:*",
+    "@clubedge/auth-appwrite": "workspace:*",
     "@clubedge/auth-better-auth": "workspace:*",
+    "@clubedge/auth-firebase": "workspace:*",
     "@clubedge/auth-supabase": "workspace:*",
     "@clubedge/cache": "workspace:*",
     "@clubedge/cache-redis": "workspace:*",

package/template/apps/web/src/app/auth/callback/route.ts

@@ -1,4 +1,5 @@
 import { NextResponse, type NextRequest } from "next/server";
+import { linkToken } from "@clubedge/auth";
 import { safeRedirectPath } from "@clubedge/core";
 import { loginUrl } from "@/lib/login-url";
 import { getAuth } from "@/server/auth";
@@ -14,7 +15,8 @@ function redirectTo(path: string) {
 }
 
 export async function GET(request: NextRequest) {
-  const code = request.nextUrl.searchParams.get("code");
+  // Appwrite's links carry userId and secret instead of a code.
+  const code = linkToken(request.nextUrl.searchParams, "code");
   const next = safeRedirectPath(request.nextUrl.searchParams.get("next"));
 
   if (code) {

package/template/apps/web/src/app/reset-password/page.tsx

@@ -1,4 +1,5 @@
 import { CircleAlert } from "lucide-react";
+import { linkToken } from "@clubedge/auth";
 import Link from "next/link";
 
 import { resetPassword } from "@/app/actions/auth";
@@ -14,9 +15,12 @@ const errorMessages: Record<string, string> = {
 export default async function ResetPasswordPage({
   searchParams,
 }: {
-  searchParams: Promise<{ error?: string; token?: string }>;
+  searchParams: Promise<{ error?: string; token?: string; userId?: string; secret?: string }>;
 }) {
-  const { error, token } = await searchParams;
+  const search = await searchParams;
+  const { error } = search;
+  // Appwrite's links carry userId and secret instead of a token.
+  const token = linkToken(search, "token") ?? undefined;
 
   return (
     <AuthPage