emdash-multisite 0.0.0-stage → 0.7.0

package/SETUP.md

@@ -0,0 +1,205 @@
+# Setup — wire emdash-multisite into an EmDash + Cloudflare app
+
+This is the copy-paste wiring to turn a normal single-site EmDash app (Astro +
+`@astrojs/cloudflare` + D1) into a multi-tenant one: many sites, one Worker, one
+D1 database, subdomain-per-site.
+
+> Prefer one command? `npx create-emdash-multisite` scaffolds all of this into an
+> existing EmDash app. This file is the manual reference for what that does and
+> for customising it.
+
+**Prerequisites**
+- An EmDash app that already builds and deploys to Cloudflare Workers with a D1
+  binding (`@emdash-cms/cloudflare`, `d1({ binding: "DB" })`).
+- `emdash` ≥ 0.30, `kysely` ≥ 0.29, Node ≥ 22.18.
+- Install: `pnpm add emdash-multisite` (or npm/yarn).
+
+There are **four** edits. Three are in `astro.config.mjs`; one is `src/worker.ts`
+plus two lines of `wrangler.jsonc`. Read the main `README.md` for what each
+mechanism does and the gotchas; this file is just the wiring.
+
+---
+
+## 1. `astro.config.mjs` — the three wires
+
+```js
+// --- add these imports ---
+import { d1, r2 } from "@emdash-cms/cloudflare";
+import { multisitePlugin, withSites } from "emdash-multisite";
+import { multisiteCaches } from "emdash-multisite/vite";
+import emdash from "emdash/astro";
+
+export default defineConfig({
+  // WIRE 2 — per-site caches. Add the Vite plugin so EmDash's process-wide
+  // caches are rewritten to be per-site at build time. Without this, one
+  // tenant's cached settings/collections/etc. leak into another. The build
+  // fails loudly if a core cache is unclassified (that is the safety net).
+  vite: {
+    plugins: [multisiteCaches()],
+    // ...your other vite plugins
+  },
+  integrations: [
+    emdash({
+      // WIRE 1 — database wrapper. withSites() wraps your D1 descriptor so each
+      // site reads/writes its own prefixed tables (ec_posts$acme). The "primary"
+      // site keeps unprefixed names, so an existing single-site install is
+      // unchanged.
+      database: withSites(d1({ binding: "DB" }), {
+        primary: "main",            // the control-plane site (unprefixed tables)
+        wildcard: "example.com",    // slug.example.com -> site "slug" (production)
+        // hosts: { "acme.example.com": "acme" },  // explicit host->site (test/workers.dev)
+        // themes, defaultTheme, limits, appUrl, accountTab, authLinks — see README.
+      }),
+
+      // Per-site media in one R2 bucket (keys are namespaced per site).
+      storage: { ...r2({ binding: "MEDIA" }), entrypoint: "emdash-multisite/storage" },
+
+      // WIRE 3 — outer middleware. Resolves the site from the request hostname
+      // before EmDash reads anything, and (on the primary site) turns "create a
+      // Better Auth organization" into "provision a site".
+      middleware: { outer: "emdash-multisite/middleware" },
+
+      // The provisioning / console / fleet glue (org-create guard, status API,
+      // theme switch, customer "My sites" console).
+      plugins: [multisitePlugin()],
+    }),
+  ],
+});
+```
+
+`primary` is the only required field. `wildcard` (production) or `hosts`
+(test / `workers.dev`, which has no wildcard subdomains) decides how a hostname
+maps to a site. Full config reference: `README.md`.
+
+---
+
+## 2. `src/worker.ts` — the host-aware edge cache
+
+Cloudflare Workers Cache keys entries by **path + query, not hostname**, and one
+Worker serves every tenant. So the host must go into the cache key via a cached
+inner entrypoint. This is the one piece that cannot live inside the npm package
+(it is per-project Cloudflare Worker config). Copy this file:
+
+```ts
+import handler, { createScheduledHandler } from "@emdash-cms/cloudflare/worker";
+import { WorkerEntrypoint } from "cloudflare:workers";
+import {
+  EDGE_REQUEST_HEADER,
+  cacheableRequest,
+  guardResponse,
+  normalizeHost,
+} from "emdash-multisite/edge-cache";
+import { perSiteScheduled } from "emdash-multisite/scheduled";
+
+/** Inner entrypoint: Workers Cache is ON here only; `props.host` is part of the key. */
+export class PublicCache extends WorkerEntrypoint<Env, { host: string; gpc: boolean }> {
+  async fetch(request: Request): Promise<Response> {
+    const headers = new Headers(request.headers);
+    headers.set(EDGE_REQUEST_HEADER, "1"); // ask the middleware to tag the response with its site
+    const res = await handler.fetch(
+      new Request(request, { headers }) as never,
+      this.env as never,
+      this.ctx as never,
+    );
+    return guardResponse(res as Response); // default-deny: only a clean anonymous 200 is stored
+  }
+  /** Purges only work from inside the cached entrypoint, so callers RPC here. */
+  async purgeTag(tags: string[]) {
+    const { cache } = await import("cloudflare:workers");
+    return cache.purge({ tags });
+  }
+}
+
+type Gateway = {
+  exports: Record<string, (o: { props: { host: string; gpc: boolean } }) => Fetcher>;
+};
+
+export default {
+  ...handler,
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    const url = new URL(request.url);
+    // Not cacheable (signed-in, non-GET, has query, admin/api): straight through, uncached.
+    if (!cacheableRequest(request.method, url, request.headers)) {
+      return handler.fetch(request as never, env as never, ctx as never);
+    }
+    const props = { host: normalizeHost(url.hostname), gpc: request.headers.get("sec-gpc") === "1" };
+    return (ctx as unknown as Gateway).exports.PublicCache({ props }).fetch(request);
+  },
+  // EmDash's scheduled handler serves one site; run it once per ready site.
+  scheduled: perSiteScheduled(createScheduledHandler() as never) as ExportedHandler["scheduled"],
+} satisfies ExportedHandler;
+```
+
+> If you render comments/forms behind Turnstile, or want immutable cache headers
+> on `/_image` and media, see the extended `worker.ts` in the reference host app
+> (link in README). Those are optional add-ons, not required for multi-site.
+
+---
+
+## 3. `wrangler.jsonc` — point `main` at the Worker and declare the two entrypoints
+
+```jsonc
+{
+  "main": "./src/worker.ts",
+
+  // Host-aware edge cache: the default (gateway) entrypoint is uncached; the
+  // PublicCache entrypoint is cached, with the host in ctx.props.
+  "cache": { "enabled": true },
+  "exports": {
+    "default": { "type": "worker", "cache": { "enabled": false } },
+    "PublicCache": { "type": "worker", "cache": { "enabled": true } }
+  }
+
+  // ...your existing d1_databases (binding "DB"), r2_buckets (binding "MEDIA"),
+  //    kv, routes / custom_domain, compatibility_date, etc.
+}
+```
+
+For production subdomains you also need, on the Cloudflare side:
+- a **custom domain** route for the apex, and a route for `*.example.com`,
+- a **wildcard DNS** record (`*` → the Worker, proxied).
+
+On a `workers.dev` test Worker there is no wildcard: map each tenant hostname in
+`hosts` and deploy with `wrangler versions upload --preview-alias <name>`.
+
+---
+
+## 4. First admin (run once)
+
+Tenant sites are born with an admin, so EmDash's first-run setup wizard never
+runs on them. The **primary** (control-plane) site's first user signs up through
+Better Auth as a normal subscriber — promote them once:
+
+```ts
+import { bootstrapControlPlane } from "emdash-multisite/bootstrap";
+// run once against the primary site's DB, with the user's email
+await bootstrapControlPlane(db, "you@example.com");
+```
+
+See `README.md` → "First admin & the setup wizard".
+
+---
+
+## Verify
+
+From the package (Node ≥ 22.18):
+
+```bash
+# cache tripwire: scans your installed emdash + @emdash-cms/* for unclassified caches
+node --no-warnings node_modules/emdash-multisite/scripts/caches.selfcheck.ts ./node_modules
+```
+
+Then build, deploy, and open **two** hostnames mapping to two sites. Set a
+different site title on each; the titles must not cross. That two-site title test
+under concurrency is the real gate.
+
+## Don'ts (the short list — full list in README "Limits & gotchas")
+
+- Don't enable Workers Cache any other way (`cacheCloudflare()`, `routeRules`
+  maxAge): its key ignores the host and will cross tenants.
+- Don't enable the EmDash object cache or assume R2 is per-site yet (keys are not
+  namespaced per site — media could cross).
+- Don't save platform secrets in the control-plane admin settings: provisioning
+  copies auth settings into every tenant. Use Worker secrets / env instead.
+- On every EmDash core upgrade, re-run the cache tripwire in staging before
+  deploying — a new core cache fails the build until you classify it.

package/bin/setup.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// emdash-multisite setup — scaffold the multi-tenant wiring into an existing
+// EmDash + Cloudflare Astro app.
+//
+// Usage (from your EmDash app root):
+//   npx emdash-multisite setup [--force] [--dir .]
+//
+// What it does (idempotent, non-destructive by default):
+//   1. Writes src/worker.ts           (host-aware edge cache; the one per-project file)
+//   2. Writes wrangler.multisite.jsonc (the keys to merge into your wrangler.jsonc)
+//   3. Writes astro.config.multisite.mjs (the config to merge into your astro.config)
+//   4. Prints the exact next steps (merge the two snippets, bootstrap the admin)
+//
+// It NEVER overwrites an existing file unless --force. Snippets for files it
+// won't auto-merge (wrangler.jsonc, astro.config.mjs) are written next to them
+// with a `.multisite.` marker so you can diff + merge by hand — merging JSONC
+// and arbitrary astro config safely by machine is not worth the risk.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const args = process.argv.slice(2);
+if (args[0] === "setup") args.shift(); // allow both `emdash-multisite setup` and bare
+const force = args.includes("--force");
+const dirFlag = args.indexOf("--dir");
+const root = resolve(dirFlag >= 0 ? args[dirFlag + 1] : ".");
+const templates = resolve(dirname(fileURLToPath(import.meta.url)), "..", "templates");
+
+const C = { gray: "\x1b[90m", green: "\x1b[32m", yellow: "\x1b[33m", bold: "\x1b[1m", reset: "\x1b[0m" };
+const log = (s = "") => process.stdout.write(`${s}\n`);
+const ok = (s) => log(`  ${C.green}✓${C.reset} ${s}`);
+const skip = (s) => log(`  ${C.yellow}•${C.reset} ${s}`);
+
+function sanityCheck() {
+	const pkgPath = join(root, "package.json");
+	if (!existsSync(pkgPath)) {
+		log(`${C.yellow}No package.json in ${root}. Run this from your EmDash app root (or pass --dir).${C.reset}`);
+		process.exit(1);
+	}
+	const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+	const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+	if (!deps.emdash) {
+		log(`${C.yellow}Warning: "emdash" is not a dependency here. This scaffolder is for an existing EmDash app.${C.reset}`);
+	}
+	return { pkgPath, pkg, deps };
+}
+
+function copy(fromName, toRel, { marker = false } = {}) {
+	const to = join(root, toRel);
+	const src = join(templates, fromName);
+	if (!existsSync(src)) {
+		skip(`template ${fromName} missing in package — skipped`);
+		return;
+	}
+	if (existsSync(to) && !force) {
+		skip(`${toRel} exists — left as is ${C.gray}(--force to overwrite)${C.reset}`);
+		return;
+	}
+	mkdirSync(dirname(to), { recursive: true });
+	writeFileSync(to, readFileSync(src, "utf8"));
+	ok(`${marker ? "wrote snippet " : "wrote "}${toRel}`);
+}
+
+log(`\n${C.bold}emdash-multisite setup${C.reset} ${C.gray}(${root})${C.reset}\n`);
+const { deps } = sanityCheck();
+
+// 1. the one real per-project file
+copy("worker.ts", "src/worker.ts");
+
+// 2 + 3. snippets to merge (never auto-edit the user's config/wrangler)
+copy("wrangler.snippet.jsonc", "wrangler.multisite.jsonc", { marker: true });
+copy("astro.config.snippet.mjs", "astro.config.multisite.mjs", { marker: true });
+
+log(`\n${C.bold}Next steps${C.reset}`);
+if (!deps["emdash-multisite"]) {
+	log(`  1. Install the package:   ${C.bold}pnpm add emdash-multisite${C.reset}`);
+}
+log(`  ${deps["emdash-multisite"] ? "1" : "2"}. Merge ${C.bold}astro.config.multisite.mjs${C.reset} into your astro.config.mjs (3 wires: database, vite plugin, middleware).`);
+log(`  ${deps["emdash-multisite"] ? "2" : "3"}. Merge ${C.bold}wrangler.multisite.jsonc${C.reset} into your wrangler.jsonc (main + cache + exports).`);
+log(`  ${deps["emdash-multisite"] ? "3" : "4"}. Bootstrap the control-plane admin once (see README "First admin"): ${C.gray}bootstrapControlPlane(db, "you@example.com")${C.reset}`);
+log(`  ${deps["emdash-multisite"] ? "4" : "5"}. Verify: ${C.gray}node --no-warnings node_modules/emdash-multisite/scripts/caches.selfcheck.ts ./node_modules${C.reset}`);
+log(`\nFull guide: ${C.bold}SETUP.md${C.reset} · Reference & gotchas: ${C.bold}README.md${C.reset}\n`);

package/package.json

@@ -1,6 +1,93 @@
 {
   "name": "emdash-multisite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.0",
+  "description": "Run many EmDash sites from one Cloudflare Worker and one D1 database. Per-site table prefixing in the Kysely dialect, per-site caches via a build-time patch, and hostname-based site resolution. No Workers for Platforms, no fork of EmDash core.",
+  "license": "MIT",
+  "author": "The Weekend Projects",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theweekendprojects/emdash-multisite.git"
+  },
+  "homepage": "https://github.com/theweekendprojects/emdash-multisite#readme",
+  "bugs": {
+    "url": "https://github.com/theweekendprojects/emdash-multisite/issues"
+  },
+  "keywords": [
+    "emdash",
+    "emdash-cms",
+    "cms",
+    "multi-tenant",
+    "multisite",
+    "multi-site",
+    "cloudflare",
+    "cloudflare-workers",
+    "d1",
+    "astro",
+    "kysely"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "emdash-multisite": "./bin/setup.mjs"
+  },
+  "files": [
+    "src",
+    "templates",
+    "bin",
+    "README.md",
+    "SETUP.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./db/d1": "./src/db/d1.ts",
+    "./db/sqlite": "./src/db/sqlite.ts",
+    "./provision": "./src/provision.ts",
+    "./vite": "./src/vite.ts",
+    "./middleware": "./src/middleware.ts",
+    "./bootstrap": "./src/bootstrap.ts",
+    "./fleet": "./src/fleet.ts",
+    "./scheduled": "./src/scheduled.ts",
+    "./storage": "./src/storage.ts",
+    "./auth-ui": "./src/auth-ui.ts",
+    "./auth-links": "./src/auth-links.ts",
+    "./plugin-entry": "./src/plugin-entry.ts",
+    "./plugin": "./src/plugin.ts",
+    "./edge-cache": "./src/edge-cache.ts"
+  },
+  "scripts": {
+    "selfcheck": "node --no-warnings scripts/selfcheck.ts",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "emdash": ">=0.30.0",
+    "@emdash-cms/cloudflare": "*",
+    "kysely": ">=0.29.0",
+    "@better-auth-ui/core": "*",
+    "react": "*",
+    "@heroui/react": ">=3.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@emdash-cms/cloudflare": {
+      "optional": true
+    },
+    "@better-auth-ui/core": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "@heroui/react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "22.20.5",
+    "typescript": "5.9.3",
+    "kysely": "0.29.2"
+  },
+  "engines": {
+    "node": ">=22.18"
+  }
+}

package/src/abuse.ts

@@ -0,0 +1,65 @@
+/**
+ * Brakes on automated abuse of open sign-up. Uses Cloudflare's Rate Limiting
+ * bindings when the host declares them, and does nothing when it does not:
+ *   SIGNUP_LIMITER    keyed by client IP    (sign-up requests)
+ *   CREATE_LIMITER    keyed by user id      (site creation, per user)
+ *   CREATE_IP_LIMITER keyed by client IP    (site creation, per IP - OP-13)
+ * Declare them in wrangler.jsonc, e.g.
+ *   "ratelimits": [{ "name": "SIGNUP_LIMITER", "namespace_id": "1001", "simple": { "limit": 5, "period": 60 } }]
+ * ponytail: counters are per Cloudflare location and periods are 10 or 60 s, so this stops
+ * bursts, not slow trickles. Upgrade path: Turnstile on sign-up (needs a site key).
+ */
+import { platformEnv } from "./platform-env.ts";
+
+export type Limiter = "SIGNUP_LIMITER" | "CREATE_LIMITER" | "CREATE_IP_LIMITER";
+
+/** True when `key` is over the limit of the named binding. Fails open (no binding, or it errors). */
+export async function overLimit(name: Limiter, key: string): Promise<boolean> {
+	const binding = (await platformEnv())?.[name] as { limit(o: { key: string }): Promise<{ success: boolean }> } | undefined;
+	if (!binding) return false;
+	try {
+		return !(await binding.limit({ key })).success;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * OP-13: Turnstile verification on sign-up.
+ * Verifies the Turnstile token sent by the client. When TURNSTILE_SECRET env var
+ * is unset (dev/test), the check is skipped (fails open).
+ * Returns null if verified, or an error response if failed/missing.
+ */
+export async function verifyTurnstile(token: string | undefined, remoteIp: string | undefined): Promise<Response | null> {
+	const secret = (await platformEnv())?.TURNSTILE_SECRET;
+	// No secret configured (dev/test, or Turnstile not enabled): skip entirely, including the token check,
+	// so the sign-up flow is unchanged until an operator sets TURNSTILE_SECRET and renders the widget.
+	if (typeof secret !== "string" || secret === "") return null;
+
+	const fail = (code: string, message: string) =>
+		new Response(JSON.stringify({ code, message }), {
+			status: 403,
+			headers: { "content-type": "application/json", "cache-control": "no-store" },
+		});
+	// Secret is set, so the client must send a token.
+	if (!token) return fail("TURNSTILE_MISSING", "Security check failed. Please try again.");
+
+	try {
+		const formData = new FormData();
+		formData.append("response", token);
+		formData.append("secret", secret);
+		if (remoteIp) formData.append("remoteip", remoteIp);
+
+		const result = await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", {
+			method: "POST",
+			body: formData,
+		});
+
+		const outcome = (await result.json()) as { success: boolean; "error-codes"?: string[] };
+		if (!outcome.success) return fail("TURNSTILE_FAILED", `Security check failed: ${outcome["error-codes"]?.join(", ") ?? "Invalid token"}`);
+		return null;
+	} catch {
+		// Network error - fail open to avoid blocking legitimate users
+		return null;
+	}
+}

package/src/auth-links.ts

@@ -0,0 +1,21 @@
+/**
+ * Which account links a theme header shows. Pure, so a plain-Node self-check covers it; the host's
+ * `AuthLinks.astro` component calls it and prints the result as plain `<a>` elements: no script, no extra request.
+ *
+ * - visitor, public sign-up on:  Sign in, Sign up
+ * - visitor, public sign-up off: nothing
+ * - signed in:                   My account, and Admin from the author role (30) up (unless the theme draws its own)
+ */
+export interface AuthLink {
+	label: string;
+	href: string;
+	/** The call to action (Sign up). */
+	cta?: boolean;
+}
+
+export function authLinksFor(opts: { signup: boolean; account: string; user: { role?: number } | null | undefined; admin?: boolean }): AuthLink[] {
+	if (!opts.user) return opts.signup ? [{ label: "Sign in", href: "/login" }, { label: "Sign up", href: "/signup", cta: true }] : [];
+	const links: AuthLink[] = [{ label: "My account", href: opts.account }];
+	if (opts.admin !== false && (opts.user.role ?? 0) >= 30) links.push({ label: "Admin", href: "/_emdash/admin" });
+	return links;
+}