create-authhero 0.42.0 → 0.44.0

package/dist/proxy/README.md

@@ -0,0 +1,161 @@
+# AuthHero Proxy
+
+A Cloudflare Worker that proxies incoming requests to upstream services based on the request's `Host` header. Built on [@authhero/proxy](https://www.npmjs.com/package/@authhero/proxy).
+
+This template ships with a static, in-file config so you can run it immediately. For production you'll typically swap that adapter for one that reads routes from your authhero deployment — see [Data sources](#data-sources) below.
+
+## Configure your routes (default)
+
+Edit [src/proxy.config.ts](src/proxy.config.ts) to map each public hostname to one or more upstream routes. Path patterns support `*` and `:param` segments, and routes are matched in priority order (lower wins).
+
+```ts
+export const proxyConfig: StaticProxyAdapterOptions = {
+  hosts: {
+    "id.example.com": {
+      tenant_id: "example",
+      routes: [
+        {
+          path_pattern: "/*",
+          upstream_type: "http",
+          upstream_url: "https://upstream.example.com",
+        },
+      ],
+    },
+  },
+};
+```
+
+## Data sources
+
+The proxy reads its routes through a `ProxyDataAdapter`. Three implementations are common:
+
+| Adapter | Best for | Notes |
+| --- | --- | --- |
+| **Static** (default) | Local dev, small fixed deployments | Routes baked into the worker bundle; re-deploy to change them. |
+| **Database** | Same-process or co-located deployments | Reads directly from the proxy_routes table that authhero writes to. |
+| **HTTP / management API** | Geographically distributed proxies, hosted Workers | Calls `/api/v2/proxy-routes` on your authhero server with a service token. |
+
+The authhero server exposes the management API (`/api/v2/proxy-routes`) and creates the underlying table automatically once the standard adapter migrations have run — see the `local` template's [src/index.ts](../local/src/index.ts).
+
+### Database-backed (Kysely)
+
+Add the adapter and your Kysely driver, then swap the data line:
+
+```bash
+npm install @authhero/kysely-adapter kysely
+```
+
+```ts
+import { Kysely } from "kysely";
+import { createProxyApp } from "@authhero/proxy";
+import { createProxyDataAdapter } from "@authhero/kysely-adapter";
+
+const db = new Kysely({ dialect: /* your dialect */ });
+const app = createProxyApp({
+  data: createProxyDataAdapter(db),
+});
+```
+
+Cloudflare Workers can't open SQLite files, so on Workers this path means D1, Hyperdrive, or a remote MySQL/Postgres. For a local Node process, `better-sqlite3` pointing at the same `db.sqlite` your authhero server uses works out of the box.
+
+### HTTP-backed (management API)
+
+The proxy authenticates to authhero's management API with a service token. Issue the token from authhero with the scopes `read:proxy_routes` and `read:custom_domains`, then store it as a worker secret:
+
+```bash
+wrangler secret put AUTHHERO_SERVICE_TOKEN
+```
+
+`wrangler.toml` vars:
+
+```toml
+[vars]
+AUTHHERO_API_URL = "https://auth.example.com"
+AUTHHERO_TENANT_ID = "example"
+```
+
+Then build an adapter that resolves the host via `/api/v2/custom-domains` and the routes via `/api/v2/proxy-routes`:
+
+```ts
+import type { ProxyDataAdapter, ResolvedHost } from "@authhero/proxy";
+
+interface Env {
+  AUTHHERO_API_URL: string;
+  AUTHHERO_TENANT_ID: string;
+  AUTHHERO_SERVICE_TOKEN: string;
+}
+
+function createHttpProxyAdapter(env: Env): ProxyDataAdapter {
+  const headers = {
+    "authorization": `Bearer ${env.AUTHHERO_SERVICE_TOKEN}`,
+    "tenant-id": env.AUTHHERO_TENANT_ID,
+  };
+
+  async function api<T>(path: string): Promise<T> {
+    const res = await fetch(`${env.AUTHHERO_API_URL}${path}`, { headers });
+    if (!res.ok) throw new Error(`${path}: ${res.status}`);
+    return res.json() as Promise<T>;
+  }
+
+  return {
+    // The proxy data plane only needs resolveHost; the CRUD methods on
+    // proxyRoutes stay unused (writes always go through authhero directly).
+    proxyRoutes: {
+      list: () => { throw new Error("read-only proxy adapter"); },
+      get: () => { throw new Error("read-only proxy adapter"); },
+      create: () => { throw new Error("read-only proxy adapter"); },
+      update: () => { throw new Error("read-only proxy adapter"); },
+      remove: () => { throw new Error("read-only proxy adapter"); },
+    },
+    async resolveHost(host): Promise<ResolvedHost | null> {
+      const domains = await api<{ custom_domains: Array<{
+        custom_domain_id: string; domain: string;
+      }> }>("/api/v2/custom-domains");
+      const match = domains.custom_domains.find((d) => d.domain === host);
+      if (!match) return null;
+
+      const routes = await api<{ proxy_routes: unknown[] }>(
+        `/api/v2/proxy-routes?custom_domain_id=${match.custom_domain_id}&per_page=200`,
+      );
+      return {
+        tenant_id: env.AUTHHERO_TENANT_ID,
+        custom_domain_id: match.custom_domain_id,
+        domain: host,
+        routes: routes.proxy_routes as ResolvedHost["routes"],
+      };
+    },
+  };
+}
+```
+
+Cache aggressively (see below) — every cold cache miss is two API round-trips.
+
+## Caching
+
+Resolved hosts are cached in-memory per Worker isolate with a stale-while-revalidate strategy:
+
+- **Fresh** for 5 minutes — served directly from cache.
+- **Stale** for the next hour — served from cache while a background refresh runs.
+- **Negative** (host not found) — cached for 30 seconds so newly-added hosts come online quickly.
+
+For the static adapter the "refresh" is just a re-read of the in-memory config, so the SWR window mainly matters when you swap to the HTTP- or database-backed adapter.
+
+## Develop locally
+
+```bash
+npm run dev
+```
+
+The worker is served at `http://localhost:8787`. To exercise a specific host, send the `Host` header:
+
+```bash
+curl http://localhost:8787/login -H "Host: id.example.com"
+```
+
+## Deploy
+
+```bash
+npm run deploy
+```
+
+Add a custom-domain route in `wrangler.toml` for each hostname you've configured, or attach the worker to existing routes in the Cloudflare dashboard.

package/dist/proxy/src/index.ts

@@ -0,0 +1,40 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import {
+  createProxyApp,
+  createStaticProxyAdapter,
+} from "@authhero/proxy";
+import { proxyConfig } from "./proxy.config";
+
+// AsyncLocalStorage threads each request's ExecutionContext through to the
+// host cache so background SWR refreshes keep running after the response
+// returns. Requires the `nodejs_compat` compatibility flag.
+interface RequestCtx {
+  waitUntil: (promise: Promise<unknown>) => void;
+}
+const requestCtx = new AsyncLocalStorage<RequestCtx>();
+
+const data = createStaticProxyAdapter(proxyConfig);
+
+const app = createProxyApp({
+  data,
+  cache: {
+    // Serve cached values directly for 5 minutes.
+    freshTtlMs: 5 * 60_000,
+    // For the next hour, keep serving the cached value and refresh in the
+    // background. After that, the next request blocks on a fresh fetch.
+    staleTtlMs: 60 * 60_000,
+    // Don't cache "host not found" for as long — new hosts should become
+    // reachable quickly after being added to the config.
+    negativeTtlMs: 30_000,
+    waitUntil: (promise) => requestCtx.getStore()?.waitUntil(promise),
+  },
+});
+
+export default {
+  fetch(request: Request, _env: unknown, ctx: ExecutionContext) {
+    return requestCtx.run(
+      { waitUntil: ctx.waitUntil.bind(ctx) },
+      () => app.fetch(request),
+    );
+  },
+};

package/dist/proxy/src/proxy.config.ts

@@ -0,0 +1,32 @@
+import type { StaticProxyAdapterOptions } from "@authhero/proxy";
+
+// Map each public hostname to the routes the proxy should serve for it.
+// Routes are matched in priority order (lower priority wins). The path
+// pattern in `match.path` supports `*` and `:param` segments (Hono syntax).
+//
+// Each route is an ordered list of handlers. The last handler is the
+// terminal — it produces the response (e.g. `http`, `redirect`, `static`,
+// `service_binding`). Earlier handlers wrap it, like Hono middleware.
+//
+// Edit this file to add your hosts, then re-deploy.
+export const proxyConfig: StaticProxyAdapterOptions = {
+  hosts: {
+    "id.example.com": {
+      tenant_id: "example",
+      routes: [
+        {
+          match: { path: "/*" },
+          handlers: [
+            {
+              type: "http",
+              options: {
+                upstream_url: "https://upstream.example.com",
+                preserve_host: false,
+              },
+            },
+          ],
+        },
+      ],
+    },
+  },
+};

package/dist/proxy/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", "node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}

package/dist/proxy/wrangler.toml

@@ -0,0 +1,22 @@
+# ════════════════════════════════════════════════════════════════════════════
+# AuthHero Proxy — Cloudflare Worker Configuration
+# ════════════════════════════════════════════════════════════════════════════
+
+name = "authhero-proxy"
+main = "src/index.ts"
+compatibility_date = "2025-05-23"
+compatibility_flags = ["nodejs_compat"]
+
+# ════════════════════════════════════════════════════════════════════════════
+# OPTIONAL: Custom Domains
+# ════════════════════════════════════════════════════════════════════════════
+# Route the public hostnames you configured in src/proxy.config.ts to this
+# worker. Each host should be a custom domain (or have a route added) in your
+# Cloudflare account.
+#
+# [[routes]]
+# pattern = "id.example.com"
+# custom_domain = true
+
+[observability]
+enabled = true

package/package.json

@@ -5,7 +5,7 @@
     "type": "git",
     "url": "https://github.com/markusahlstrand/authhero"
   },
-  "version": "0.42.0",
+  "version": "0.44.0",
   "type": "module",
   "main": "dist/create-authhero.js",
   "bin": {
@@ -19,10 +19,10 @@
     "@rollup/plugin-commonjs": "^26.0.1",
     "@rollup/plugin-node-resolve": "^15.2.3",
     "@types/inquirer": "^9.0.7",
-    "@types/node": "^20.14.9",
-    "tsx": "^4.19.4",
+    "@types/node": "^20.19.41",
+    "tsx": "^4.22.3",
     "typescript": "^5.5.2",
-    "vite": "^5.3.2"
+    "vite": "^8.0.14"
   },
   "dependencies": {
     "commander": "^12.1.0",