create-authhero 0.45.0 → 0.47.0

package/dist/cloudflare-control-plane/wrangler.toml

@@ -0,0 +1,46 @@
+# ════════════════════════════════════════════════════════════════════════════
+# AuthHero Control Plane Worker
+# ════════════════════════════════════════════════════════════════════════════
+# The management surface + rollout source for a Workers-for-Platforms setup.
+# It manages tenants (/api/v2/tenants), serves colocated tenants, and projects
+# the control plane's default connections/prompts/branding into each WFP
+# tenant's own database via POST /internal/tenants/:id/sync-defaults.
+#
+# Pair with:
+#   - cloudflare-wfp-dispatcher  (front door)
+#   - cloudflare-wfp-tenant      (per-tenant Workers)
+#
+# Sensitive IDs (database_id) go in wrangler.local.toml (gitignored).
+# ════════════════════════════════════════════════════════════════════════════
+
+name = "authhero-control-plane"
+main = "src/index.ts"
+compatibility_date = "2026-05-01"
+compatibility_flags = ["nodejs_compat"]
+
+[assets]
+directory = "./dist/assets"
+
+# ════════════════════════════════════════════════════════════════════════════
+# Control plane database (shared platform D1)
+# ════════════════════════════════════════════════════════════════════════════
+# Holds the control plane tenant's rows (the defaults bundle), tenant records,
+# custom_domains and proxy_routes. The dispatcher reads this same database.
+[[d1_databases]]
+binding = "AUTH_DB"
+database_name = "authhero-db"
+database_id = "local"  # Use "local" for local dev, or your actual ID in wrangler.local.toml
+migrations_dir = "node_modules/@authhero/drizzle/drizzle"
+
+# ════════════════════════════════════════════════════════════════════════════
+# Encryption keys (set as secrets, not here)
+# ════════════════════════════════════════════════════════════════════════════
+#   wrangler secret put ENCRYPTION_KEY                 # control plane's own key
+#   wrangler secret put CONTROL_PLANE_ENCRYPTION_KEY   # shared "cp" key
+#
+# CONTROL_PLANE_ENCRYPTION_KEY must be byte-identical to the key each tenant
+# Worker holds, so projected secrets decrypt on the tenant side.
+
+# Optional: Enable observability
+# [observability]
+# enabled = true

package/dist/cloudflare-wfp-dispatcher/README.md

@@ -0,0 +1,94 @@
+# AuthHero WFP Dispatcher
+
+Thin Cloudflare Worker that fronts a Workers-for-Platforms deployment of AuthHero. Resolves an incoming request's `Host` header to a tenant via the shared platform D1 (`custom_domains` table) and dispatches the request to that tenant's full authhero auth server, deployed as a script in a Cloudflare dispatch namespace.
+
+## Architecture
+
+```
+Internet
+   |
+   v
+[This worker — the dispatcher]
+   1. Host header -> custom_domains -> tenant_id
+   2. env.DISPATCHER.get('tenant-<id>-auth').fetch(request)
+   |
+   v
+[authhero-tenants dispatch namespace]
+   |- tenant-acme-auth   (full authhero, deployed from the `cloudflare` template)
+   |- tenant-bob-auth
+   |- ...
+```
+
+Tenant workers come from the **`cloudflare` create-authhero template** — they're the same single-tenant auth server, deployed into the namespace instead of standalone.
+
+## Prerequisites
+
+- A Cloudflare account on the **Workers for Platforms** plan (required for dispatch namespaces).
+- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/).
+- A D1 database (shared with the tenant workers).
+
+## One-time platform setup
+
+```bash
+# 1. Create the dispatch namespace
+npx wrangler dispatch-namespace create authhero-tenants
+
+# 2. Create the shared D1 (or reuse the one your tenant workers use)
+npx wrangler d1 create authhero-db
+
+# 3. Copy wrangler.toml -> wrangler.local.toml and paste the database_id
+
+# 4. Install project dependencies (provides the local wrangler used by the
+#    db:migrate:* scripts)
+npm install
+
+# 5. Apply migrations to the shared D1
+npm run db:migrate:remote
+# Or, without installing dependencies first:
+#   npx wrangler d1 migrations apply AUTH_DB --remote --config wrangler.local.toml
+```
+
+## Deploy the dispatcher
+
+```bash
+npm run deploy
+```
+
+## Onboard a tenant
+
+For each publisher:
+
+1. **Provision the tenant in D1** — insert a `tenants` row, then a `custom_domains` row mapping their domain to the tenant_id. (Either via the authhero management API or by direct D1 query.)
+
+2. **Deploy their auth worker into the namespace.** From the sibling `cloudflare` template:
+
+   ```bash
+   # In the tenant's directory (scaffolded from `create-authhero --template=cloudflare`)
+   npx wrangler deploy \
+     --dispatch-namespace=authhero-tenants \
+     --name=tenant-<tenant_id>-auth
+   ```
+
+3. **Point their custom domain at this dispatcher worker** (Cloudflare → Workers → Triggers → Add Custom Domain on this worker, or via DNS to the worker's `*.workers.dev` route).
+
+Once those three steps are done, a request to `auth.<their-domain>/authorize?...` flows to this dispatcher → resolved via custom_domains → dispatched to their tenant worker.
+
+## Per-tenant routing customization
+
+By default, hosts with no `proxy_routes` rows get a single catch-all that dispatches to `tenant-<tenant_id>-auth`. If a tenant needs richer routing — different middleware chains, CORS, a special path that bypasses the namespace — insert `proxy_routes` rows for that `custom_domain_id`. The dispatcher uses the configured routes verbatim instead of the default.
+
+The script-name template (`tenant-{tenant_id}-auth`) can be overridden globally via the `SCRIPT_NAME_TEMPLATE` env var. Supported placeholders: `{tenant_id}`, `{custom_domain_id}`, `{domain}`, `{host}`.
+
+## Local development
+
+```bash
+npm run dev
+```
+
+`wrangler dev` runs against a **local SQLite-backed D1**. The dispatch namespace cannot be emulated locally — for end-to-end tests, deploy to a real Cloudflare account using `npm run dev:remote`.
+
+## Files
+
+- `src/index.ts` — dispatcher worker entrypoint
+- `src/types.ts` — Env interface (D1 binding + DISPATCHER namespace binding)
+- `wrangler.toml` — Cloudflare config (assets, D1, dispatch namespace)

package/dist/cloudflare-wfp-dispatcher/src/index.ts

@@ -0,0 +1,72 @@
+import { drizzle } from "drizzle-orm/d1";
+import { createProxyDataAdapter } from "@authhero/drizzle";
+import * as schema from "@authhero/drizzle/schema/sqlite";
+import {
+  createProxyApp,
+  type ProxyDataAdapter,
+  type ResolvedHost,
+} from "@authhero/proxy";
+import type { Env } from "./types";
+
+// `tenant-{tenant_id}-auth` is the deploy convention used by this template's
+// per-tenant worker setup. Override with the SCRIPT_NAME_TEMPLATE env var or
+// by configuring proxy_routes rows per tenant for richer routing.
+const DEFAULT_SCRIPT_NAME_TEMPLATE = "tenant-{tenant_id}-auth";
+
+// If a host resolves to a known tenant but has no proxy_routes configured,
+// synthesize a single catch-all that dispatches to the tenant's auth worker
+// in the namespace. Operators who need middleware (CORS, headers, rate
+// limiting) per tenant can add real proxy_routes rows and this fallback
+// stays out of the way.
+function withDefaultDispatchRoute(
+  inner: ProxyDataAdapter,
+  binding: string,
+  scriptNameTemplate: string,
+): ProxyDataAdapter {
+  return {
+    proxyRoutes: inner.proxyRoutes,
+    resolveHost: async (host): Promise<ResolvedHost | null> => {
+      const resolved = await inner.resolveHost(host);
+      if (!resolved || resolved.routes.length > 0) return resolved;
+      const now = new Date(0).toISOString();
+      return {
+        ...resolved,
+        routes: [
+          {
+            id: `default-${resolved.custom_domain_id}`,
+            tenant_id: resolved.tenant_id,
+            custom_domain_id: resolved.custom_domain_id,
+            priority: 1000,
+            match: { path: "/*" },
+            handlers: [
+              {
+                type: "dispatch_namespace",
+                options: { binding, script_name: scriptNameTemplate },
+              },
+            ],
+            created_at: now,
+            updated_at: now,
+          },
+        ],
+      };
+    },
+  };
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const db = drizzle(env.AUTH_DB, { schema });
+    const data = withDefaultDispatchRoute(
+      createProxyDataAdapter(db),
+      "DISPATCHER",
+      env.SCRIPT_NAME_TEMPLATE || DEFAULT_SCRIPT_NAME_TEMPLATE,
+    );
+
+    const app = createProxyApp({
+      data,
+      bindings: { DISPATCHER: env.DISPATCHER },
+    });
+
+    return app.fetch(request);
+  },
+};

package/dist/cloudflare-wfp-dispatcher/src/types.ts

@@ -0,0 +1,17 @@
+/// <reference types="@cloudflare/workers-types" />
+
+export interface Env {
+  // The shared platform D1 database. Holds custom_domains (host -> tenant)
+  // and proxy_routes (optional per-host route overrides).
+  AUTH_DB: D1Database;
+
+  // The Cloudflare Workers for Platforms dispatch namespace where each
+  // tenant's auth worker is deployed. Wrangler binding configured in
+  // wrangler.toml as `[[dispatch_namespaces]] binding = "DISPATCHER"`.
+  DISPATCHER: DispatchNamespace;
+
+  // Optional template for resolving a tenant to a dispatch namespace
+  // script name. Defaults to `tenant-{tenant_id}-auth`. Supported
+  // placeholders: {tenant_id}, {custom_domain_id}, {domain}, {host}.
+  SCRIPT_NAME_TEMPLATE?: string;
+}

package/dist/cloudflare-wfp-dispatcher/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["@cloudflare/workers-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}

package/dist/cloudflare-wfp-dispatcher/wrangler.toml

@@ -0,0 +1,56 @@
+# ════════════════════════════════════════════════════════════════════════════
+# AuthHero WFP Dispatcher Configuration
+# ════════════════════════════════════════════════════════════════════════════
+# Thin Cloudflare Worker that resolves a request's Host header to a tenant
+# (via the shared platform D1) and dispatches to that tenant's full
+# authhero auth server, deployed as a script in the `authhero-tenants`
+# dispatch namespace.
+#
+# Tenant workers are deployed separately via the `cloudflare` template,
+# using `wrangler deploy --dispatch-namespace=authhero-tenants
+# --name=tenant-<id>-auth`.
+#
+# Sensitive IDs (database_id) go in wrangler.local.toml (gitignored) or
+# GitHub Secrets, not this file.
+# ════════════════════════════════════════════════════════════════════════════
+
+name = "authhero-wfp-dispatcher"
+main = "src/index.ts"
+compatibility_date = "2026-05-01"
+compatibility_flags = ["nodejs_compat"]
+
+# ════════════════════════════════════════════════════════════════════════════
+# Dispatch namespace binding
+# ════════════════════════════════════════════════════════════════════════════
+# Create the namespace once before the first deploy:
+#   npx wrangler dispatch-namespace create authhero-tenants
+[[dispatch_namespaces]]
+binding = "DISPATCHER"
+namespace = "authhero-tenants"
+
+# ════════════════════════════════════════════════════════════════════════════
+# Shared platform D1 database
+# ════════════════════════════════════════════════════════════════════════════
+# Same D1 that the tenant workers read/write. Holds custom_domains and
+# proxy_routes that drive the dispatcher's host -> tenant resolution.
+[[d1_databases]]
+binding = "AUTH_DB"
+database_name = "authhero-db"
+database_id = "local"  # Use "local" for local dev, or your actual ID in wrangler.local.toml
+migrations_dir = "node_modules/@authhero/drizzle/drizzle"
+
+# ════════════════════════════════════════════════════════════════════════════
+# OPTIONAL: Custom Domain
+# ════════════════════════════════════════════════════════════════════════════
+# Point your platform's wildcard or per-publisher custom domains at this
+# worker. The publishers' subdomains must resolve here so the dispatcher
+# can route into the namespace.
+#
+# [[routes]]
+# pattern = "*.auth.yourplatform.com/*"
+# zone_name = "yourplatform.com"
+
+# Optional: Enable observability for `wrangler tail` insight into dispatch
+# decisions and namespace invocation latency.
+# [observability]
+# enabled = true

package/dist/cloudflare-wfp-tenant/.dev.vars.example

@@ -0,0 +1,17 @@
+# ============================================================================
+# Development Environment Variables — WFP Tenant Worker
+# ============================================================================
+# Copy this file to .dev.vars and fill in your values.
+# ============================================================================
+
+# This tenant's own at-rest encryption key (base64-encoded 32 bytes).
+# `create-authhero` writes a generated key here for local dev. In production:
+#   wrangler secret put ENCRYPTION_KEY
+# Generate one with: openssl rand -base64 32
+# ENCRYPTION_KEY=
+
+# The CONTROL PLANE key (key id "cp"). Decrypts the shared secrets the control
+# plane projected into this tenant's database. Must be byte-identical to the
+# control plane's CONTROL_PLANE_ENCRYPTION_KEY. In production:
+#   wrangler secret put CONTROL_PLANE_ENCRYPTION_KEY
+# CONTROL_PLANE_ENCRYPTION_KEY=

package/dist/cloudflare-wfp-tenant/README.md

@@ -0,0 +1,62 @@
+# AuthHero — WFP Tenant Worker
+
+The full `authhero` app for **one tenant**, deployed into a Workers-for-Platforms
+dispatch namespace. It reads only its **own D1** and inherits the control
+plane's defaults (shared social logins, prompts, branding, system resource
+servers, inheritable hooks) from rows the **control plane rollout** projects
+into that database.
+
+This is one of three pieces:
+
+| Piece | Template |
+| --- | --- |
+| Front door (host → tenant → dispatch) | `cloudflare-wfp-dispatcher` |
+| **This tenant Worker** | `cloudflare-wfp-tenant` |
+| Control plane (rollout source + management) | `cloudflare-control-plane` |
+
+## How defaults work
+
+`src/index.ts` layers the data adapter:
+
+```
+D1 → keyed encryption (tenant key + "cp" key) → withRuntimeFallback(control_plane)
+```
+
+`withRuntimeFallback` resolves the control-plane rows that the rollout wrote into
+this database under the `control_plane` tenant id — the same read path a
+control-plane-colocated tenant uses. **No request-time call to the control
+plane.**
+
+## Secrets
+
+Two keys, both Worker secrets (never in the database):
+
+- `ENCRYPTION_KEY` — this tenant's own secrets.
+- `CONTROL_PLANE_ENCRYPTION_KEY` — the shared `cp` key. Decrypts the inherited
+  secrets (e.g. Google `client_secret`). It must be **byte-identical** to the
+  control plane's key, or the inherited secrets won't decrypt. A raw export of
+  `AUTH_DB` keeps those secrets opaque without it.
+
+## Setup
+
+```bash
+npm install
+npm run setup            # creates wrangler.local.toml + .dev.vars (ENCRYPTION_KEY generated)
+# paste CONTROL_PLANE_ENCRYPTION_KEY (from the control plane) into .dev.vars
+npm run migrate          # apply schema to this tenant's D1
+npm run dev
+```
+
+## Deploy into the namespace
+
+```bash
+# one Worker per tenant
+wrangler deploy --dispatch-namespace=authhero-tenants --name=tenant-<id>-auth
+wrangler secret put ENCRYPTION_KEY                --name tenant-<id>-auth
+wrangler secret put CONTROL_PLANE_ENCRYPTION_KEY  --name tenant-<id>-auth
+```
+
+After the Worker and its D1 exist, run the control plane's
+`sync-defaults` for this tenant so its inherited rows are populated. See the
+[Control Plane Defaults](https://authhero.net/docs/customization/multi-tenancy/control-plane-defaults)
+docs for the full flow.

package/dist/cloudflare-wfp-tenant/copy-assets.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+/**
+ * Copy AuthHero assets to dist directory
+ *
+ * This script copies static assets from the authhero package to the dist directory
+ * so they can be served as static files. Most deployment targets do not support
+ * serving files directly from node_modules.
+ */
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const sourceDir = path.join(
+  __dirname,
+  "node_modules",
+  "authhero",
+  "dist",
+  "assets",
+);
+const targetDir = path.join(__dirname, "dist", "assets");
+
+/**
+ * Recursively copy directory contents
+ */
+function copyDirectory(src, dest) {
+  // Create destination directory if it doesn't exist
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  // Read source directory
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirectory(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+try {
+  console.log("📦 Copying AuthHero assets...");
+
+  if (!fs.existsSync(sourceDir)) {
+    console.error(`❌ Source directory not found: ${sourceDir}`);
+    console.error("Make sure the authhero package is installed.");
+    process.exit(1);
+  }
+
+  // Clean target directory to remove stale files from previous builds
+  if (fs.existsSync(targetDir)) {
+    fs.rmSync(targetDir, { recursive: true });
+    console.log("🧹 Cleaned old assets");
+  }
+
+  copyDirectory(sourceDir, targetDir);
+
+  // Also copy widget files from @authhero/widget package
+  const widgetSourceDir = path.join(
+    __dirname,
+    "node_modules",
+    "@authhero",
+    "widget",
+    "dist",
+    "authhero-widget",
+  );
+  const widgetTargetDir = path.join(targetDir, "u", "widget");
+
+  if (fs.existsSync(widgetSourceDir)) {
+    console.log("📦 Copying widget assets...");
+    copyDirectory(widgetSourceDir, widgetTargetDir);
+  } else {
+    console.warn(`⚠️  Widget directory not found: ${widgetSourceDir}`);
+    console.warn(
+      "Widget features may not work. Install @authhero/widget to enable.",
+    );
+  }
+
+  // Copy admin UI files from @authhero/admin package
+  const adminSourceDir = path.join(
+    __dirname,
+    "node_modules",
+    "@authhero",
+    "admin",
+    "dist",
+  );
+
+  if (fs.existsSync(adminSourceDir)) {
+    console.log("📦 Copying admin UI assets...");
+    const adminTargetDir = path.join(targetDir, "admin");
+    copyDirectory(adminSourceDir, adminTargetDir);
+
+    // Inject runtime config into index.html
+    // Uses window.location.origin so the admin UI automatically points to its own server
+    const adminIndexPath = path.join(adminSourceDir, "index.html");
+    const adminHtml = fs
+      .readFileSync(adminIndexPath, "utf-8")
+      .replace(/src="\.\/assets\//g, 'src="/admin/assets/')
+      .replace(/href="\.\/assets\//g, 'href="/admin/assets/');
+    const configScript = `<script>window.__AUTHHERO_ADMIN_CONFIG__={domain:window.location.origin,clientId:"default",basePath:"/admin"}</script>`;
+    const injectedHtml = adminHtml.replace(
+      "</head>",
+      configScript + "\n</head>",
+    );
+
+    // Write injected HTML to CDN assets (for direct /admin/ access)
+    fs.writeFileSync(path.join(adminTargetDir, "index.html"), injectedHtml);
+
+    // Write as TS module for worker to import (for SPA fallback on deep links)
+    const srcDir = path.join(__dirname, "src");
+    fs.writeFileSync(
+      path.join(srcDir, "admin-index-html.ts"),
+      `export default ${JSON.stringify(injectedHtml)};\n`,
+    );
+    console.log("✅ Admin UI assets copied and configured");
+  }
+
+  console.log(`✅ Assets copied to ${targetDir}`);
+} catch (error) {
+  console.error("❌ Error copying assets:", error.message);
+  process.exit(1);
+}

package/dist/cloudflare-wfp-tenant/drizzle.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from "drizzle-kit";
+
+// ⚠️ WARNING: Do not run `drizzle-kit generate` or `npm run db:generate`
+//
+// This configuration is for reference only. Migrations are pre-generated and
+// shipped with the @authhero/drizzle package. The schema is managed by AuthHero
+// and should not be customized to ensure compatibility with future updates.
+//
+// To apply migrations:
+//   Local:  npm run migrate
+//   Remote: npm run db:migrate:remote
+
+export default defineConfig({
+  out: "./node_modules/@authhero/drizzle/drizzle",
+  schema: "./node_modules/@authhero/drizzle/src/schema/sqlite/index.ts",
+  dialect: "sqlite",
+});

package/dist/cloudflare-wfp-tenant/scripts/decrypt-field.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { loadEncryptionKey, decryptField } from "authhero";
+
+// Decrypt a stored field value using ENCRYPTION_KEY from the environment.
+// Usage: node --env-file=.env scripts/decrypt-field.mjs "enc:v1:..."
+// Values without the enc:v1: prefix (legacy plaintext) are printed unchanged.
+const value = process.argv[2];
+
+if (!value) {
+  console.error(
+    'Usage: node --env-file=<env> scripts/decrypt-field.mjs "<value>"',
+  );
+  process.exit(1);
+}
+
+const keyB64 = process.env.ENCRYPTION_KEY;
+if (!keyB64) {
+  console.error(
+    "ENCRYPTION_KEY is not set. Pass it via --env-file or the environment.",
+  );
+  process.exit(1);
+}
+
+try {
+  const key = await loadEncryptionKey(keyB64);
+  console.log(await decryptField(value, key));
+} catch (error) {
+  console.error(
+    "Failed to decrypt:",
+    error instanceof Error ? error.message : error,
+  );
+  process.exit(1);
+}

package/dist/cloudflare-wfp-tenant/scripts/generate-encryption-key.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+
+// Print a fresh base64-encoded 32-byte (AES-256) key suitable for
+// ENCRYPTION_KEY. Copy the output into your env file (.env / .dev.vars) or set
+// it as a production secret.
+console.log(crypto.randomBytes(32).toString("base64"));

package/dist/cloudflare-wfp-tenant/src/app.ts

@@ -0,0 +1,37 @@
+import { Context } from "hono";
+import { AuthHeroConfig, init } from "authhero";
+import { swaggerUI } from "@hono/swagger-ui";
+
+// A WFP tenant Worker serves a single tenant; its defaults are inherited from
+// the control plane via the rows projected into its own database (see
+// src/index.ts). No multi-tenancy routing is needed here.
+export default function createApp(config: AuthHeroConfig) {
+  const { app } = init(config);
+
+  app
+    .onError((err, ctx) => {
+      // Duck-typing avoids instanceof issues with bundled dependencies.
+      if (
+        err &&
+        typeof err === "object" &&
+        "getResponse" in err &&
+        typeof (err as { getResponse?: unknown }).getResponse === "function"
+      ) {
+        return (err as { getResponse: () => Response }).getResponse();
+      }
+      console.error(err);
+      return ctx.text(
+        err instanceof Error ? err.message : "Internal Server Error",
+        500,
+      );
+    })
+    .get("/", async (ctx: Context) => {
+      return ctx.json({
+        name: "AuthHero WFP Tenant Server",
+        status: "running",
+      });
+    })
+    .get("/docs", swaggerUI({ url: "/api/v2/spec" }));
+
+  return app;
+}