create-authhero 0.5.0 → 0.6.0

package/dist/cloudflare-multitenant/.dev.vars.example

@@ -0,0 +1,9 @@
+# Cloudflare API credentials for multi-tenant database management
+CLOUDFLARE_ACCOUNT_ID=your_account_id_here
+CLOUDFLARE_API_TOKEN=your_api_token_here
+
+# Optional: Separate token for Analytics Engine (if different from main token)
+# ANALYTICS_ENGINE_API_TOKEN=your_analytics_token_here
+
+# Optional: Base domain for subdomain routing
+# BASE_DOMAIN=auth.example.com

package/dist/cloudflare-multitenant/README.md

@@ -0,0 +1,177 @@
+# AuthHero Multi-Tenant Server
+
+A production-grade multi-tenant AuthHero authentication server using Cloudflare Workers with:
+
+- Per-tenant D1 databases (dynamically created via REST API)
+- Analytics Engine for centralized logging
+- Subdomain-based tenant routing (optional)
+
+## Architecture
+
+```
+                    ┌─────────────────────────────────────────┐
+                    │         Cloudflare Worker               │
+                    │                                         │
+                    │  ┌─────────────────────────────────┐   │
+                    │  │      AuthHero Multi-Tenant      │   │
+                    │  └─────────────────────────────────┘   │
+                    │              │                          │
+                    │              ▼                          │
+                    │  ┌─────────────────────────────────┐   │
+                    │  │   Multi-Tenancy Plugin          │   │
+                    │  │   - Access Control              │   │
+                    │  │   - Subdomain Routing           │   │
+                    │  │   - Database Resolution         │   │
+                    │  └─────────────────────────────────┘   │
+                    │              │                          │
+                    └──────────────┼──────────────────────────┘
+                                   │
+          ┌────────────────────────┼────────────────────────┐
+          │                        │                        │
+          ▼                        ▼                        ▼
+   ┌─────────────┐         ┌─────────────┐         ┌─────────────┐
+   │   Main D1   │         │  Tenant D1  │         │  Analytics  │
+   │  Database   │         │  Databases  │         │   Engine    │
+   │  (Bound)    │         │  (via REST) │         │   (Logs)    │
+   └─────────────┘         └─────────────┘         └─────────────┘
+```
+
+## Prerequisites
+
+- [Cloudflare Account](https://dash.cloudflare.com/sign-up) with Workers Paid plan
+- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/)
+- Cloudflare API Token with D1 and Workers permissions
+
+## Getting Started
+
+1. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+2. Create the main D1 database:
+
+   ```bash
+   wrangler d1 create authhero-main-db
+   ```
+
+3. Update `wrangler.toml` with your database ID.
+
+4. Create `.dev.vars` from the example:
+
+   ```bash
+   cp .dev.vars.example .dev.vars
+   ```
+
+5. Update `.dev.vars` with your Cloudflare credentials.
+
+6. Run local database migrations:
+
+   ```bash
+   npm run db:migrate
+   ```
+
+7. Start the development server:
+   ```bash
+   npm run dev
+   ```
+
+## Cloudflare API Token
+
+Create an API token with the following permissions:
+
+- **Account** > D1 > Edit
+- **Account** > Workers Analytics Engine > Edit
+- **Zone** > Workers Routes > Edit (if using custom domains)
+
+## Multi-Tenant Features
+
+### Per-Tenant Database Isolation
+
+Each tenant gets its own D1 database, created dynamically when the tenant is provisioned:
+
+- Main tenant uses the bound D1 database (low latency)
+- Other tenants use D1 databases via REST API
+
+### Access Control
+
+- Users authenticate against the main tenant
+- Organization membership grants access to specific tenants
+- Tokens with `org` claim can access the matching tenant
+
+### Subdomain Routing (Optional)
+
+Enable subdomain routing to route requests based on subdomain:
+
+- `tenant1.auth.example.com` → tenant1
+- `tenant2.auth.example.com` → tenant2
+
+Configure in `wrangler.toml`:
+
+```toml
+[vars]
+BASE_DOMAIN = "auth.example.com"
+```
+
+### Analytics Engine Logs
+
+All authentication events are logged to Analytics Engine for:
+
+- Centralized logging across all tenants
+- Real-time analytics
+- Low-latency writes
+
+## Deployment
+
+1. Deploy to Cloudflare:
+
+   ```bash
+   npm run deploy
+   ```
+
+2. Run production migrations:
+
+   ```bash
+   npm run db:migrate:prod
+   ```
+
+3. Set production secrets:
+   ```bash
+   wrangler secret put CLOUDFLARE_API_TOKEN
+   ```
+
+## Project Structure
+
+```
+├── src/
+│   ├── index.ts           # Worker entry point
+│   ├── app.ts             # AuthHero app configuration
+│   ├── types.ts           # TypeScript type definitions
+│   └── database-factory.ts # Multi-tenant database factory
+├── wrangler.toml          # Cloudflare Worker configuration
+├── .dev.vars.example      # Example environment variables
+└── package.json
+```
+
+## API Documentation
+
+Visit your worker URL with `/docs` to see the Swagger UI documentation.
+
+## Tenant Management
+
+Tenants are managed via the `/management/tenants` endpoint:
+
+```bash
+# Create a new tenant
+curl -X POST https://your-worker.workers.dev/management/tenants \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"id": "tenant1", "name": "Tenant 1"}'
+
+# List all tenants
+curl https://your-worker.workers.dev/management/tenants \
+  -H "Authorization: Bearer <token>"
+```
+
+For more information, visit [https://authhero.net/docs](https://authhero.net/docs).

package/dist/cloudflare-multitenant/src/app.ts

@@ -0,0 +1,47 @@
+import { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { AuthHeroConfig, init } from "authhero";
+import { AuthHeroPlugin } from "@authhero/multi-tenancy";
+import { swaggerUI } from "@hono/swagger-ui";
+
+export default function createApp(
+  config: AuthHeroConfig,
+  multiTenancyPlugin: AuthHeroPlugin,
+) {
+  const { app } = init(config);
+
+  // Apply multi-tenancy middleware
+  if (multiTenancyPlugin.middleware) {
+    app.use("*", multiTenancyPlugin.middleware);
+  }
+
+  // Mount multi-tenancy routes
+  if (multiTenancyPlugin.routes) {
+    for (const route of multiTenancyPlugin.routes) {
+      app.route(route.path, route.handler);
+    }
+  }
+
+  app
+    .onError((err, ctx) => {
+      if (err instanceof HTTPException) {
+        return err.getResponse();
+      }
+      console.error(err);
+      return ctx.text(err.message, 500);
+    })
+    .get("/", async (ctx: Context) => {
+      return ctx.json({
+        name: "AuthHero Multi-Tenant Server",
+        status: "running",
+      });
+    })
+    .get("/docs", swaggerUI({ url: "/api/v2/spec" }));
+
+  // Call onRegister if defined
+  if (multiTenancyPlugin.onRegister) {
+    multiTenancyPlugin.onRegister(app);
+  }
+
+  return app;
+}

package/dist/cloudflare-multitenant/src/database-factory.ts

@@ -0,0 +1,220 @@
+import { DataAdapters } from "@authhero/adapter-interfaces";
+import createKyselyAdapters from "@authhero/kysely-adapter";
+import { D1Dialect } from "kysely-d1";
+import { Kysely, SqliteQueryCompiler } from "kysely";
+import wretch from "wretch";
+
+interface TenantDatabase {
+  database_id: string;
+  database_name: string;
+}
+
+// Cache for tenant database adapters
+const adapterCache = new Map<string, DataAdapters>();
+
+/**
+ * Create a database factory for multi-tenant D1 databases.
+ *
+ * This factory:
+ * - Uses the main D1 database for the main tenant
+ * - Creates/connects to per-tenant D1 databases via REST API for other tenants
+ */
+export function createDatabaseFactory(
+  mainDb: D1Database,
+  accountId: string,
+  apiToken: string,
+  mainTenantId: string,
+) {
+  const mainDialect = new D1Dialect({ database: mainDb });
+  const mainKysely = new Kysely<any>({ dialect: mainDialect });
+  const mainAdapters = createKyselyAdapters(mainKysely);
+
+  return {
+    /**
+     * Get adapters for a specific tenant
+     */
+    async getAdapters(tenantId: string): Promise<DataAdapters> {
+      // Main tenant uses the bound D1 database
+      if (tenantId === mainTenantId) {
+        return mainAdapters;
+      }
+
+      // Check cache first
+      const cached = adapterCache.get(tenantId);
+      if (cached) {
+        return cached;
+      }
+
+      // For other tenants, connect via REST API
+      const adapters = await createRestD1Adapters(
+        tenantId,
+        mainKysely,
+        accountId,
+        apiToken,
+      );
+      adapterCache.set(tenantId, adapters);
+      return adapters;
+    },
+
+    /**
+     * Provision a new database for a tenant
+     */
+    async provision(tenantId: string): Promise<void> {
+      console.log(`Provisioning database for tenant: ${tenantId}`);
+
+      // Create a new D1 database via Cloudflare API
+      const response = await wretch(
+        `https://api.cloudflare.com/client/v4/accounts/${accountId}/d1/database`,
+      )
+        .auth(`Bearer ${apiToken}`)
+        .post({ name: `authhero-tenant-${tenantId}` })
+        .json<{ success: boolean; result: TenantDatabase; errors: any[] }>();
+
+      if (!response.success) {
+        throw new Error(
+          `Failed to create database: ${JSON.stringify(response.errors)}`,
+        );
+      }
+
+      // Store the database mapping in the main database
+      await mainKysely
+        .insertInto("tenant_databases")
+        .values({
+          tenant_id: tenantId,
+          database_id: response.result.database_id,
+          database_name: response.result.database_name,
+          created_at: new Date().toISOString(),
+        })
+        .execute();
+
+      console.log(
+        `Database provisioned for tenant ${tenantId}: ${response.result.database_id}`,
+      );
+    },
+
+    /**
+     * Deprovision (delete) a tenant's database
+     */
+    async deprovision(tenantId: string): Promise<void> {
+      console.log(`Deprovisioning database for tenant: ${tenantId}`);
+
+      // Get the database ID from the main database
+      const mapping = await mainKysely
+        .selectFrom("tenant_databases")
+        .where("tenant_id", "=", tenantId)
+        .selectAll()
+        .executeTakeFirst();
+
+      if (!mapping) {
+        console.warn(`No database mapping found for tenant: ${tenantId}`);
+        return;
+      }
+
+      // Delete the D1 database via Cloudflare API
+      await wretch(
+        `https://api.cloudflare.com/client/v4/accounts/${accountId}/d1/database/${mapping.database_id}`,
+      )
+        .auth(`Bearer ${apiToken}`)
+        .delete()
+        .json();
+
+      // Remove the mapping from the main database
+      await mainKysely
+        .deleteFrom("tenant_databases")
+        .where("tenant_id", "=", tenantId)
+        .execute();
+
+      // Clear from cache
+      adapterCache.delete(tenantId);
+
+      console.log(`Database deprovisioned for tenant: ${tenantId}`);
+    },
+  };
+}
+
+/**
+ * Create adapters that connect to a D1 database via REST API
+ */
+async function createRestD1Adapters(
+  tenantId: string,
+  mainKysely: Kysely<any>,
+  accountId: string,
+  apiToken: string,
+): Promise<DataAdapters> {
+  // Get the database ID from the tenant_databases table
+  const mapping = await mainKysely
+    .selectFrom("tenant_databases")
+    .where("tenant_id", "=", tenantId)
+    .select("database_id")
+    .executeTakeFirst();
+
+  if (!mapping) {
+    throw new Error(`No database found for tenant: ${tenantId}`);
+  }
+
+  // Create a REST-based D1 adapter
+  // Note: This uses the Cloudflare D1 HTTP API
+  const restDialect = createRestD1Dialect(
+    mapping.database_id,
+    accountId,
+    apiToken,
+  );
+  const db = new Kysely<any>({ dialect: restDialect });
+
+  return createKyselyAdapters(db);
+}
+
+/**
+ * Create a Kysely dialect that uses D1 REST API
+ */
+function createRestD1Dialect(
+  databaseId: string,
+  accountId: string,
+  apiToken: string,
+) {
+  return {
+    createAdapter: () => ({
+      supportsCreateIfNotExists: () => true,
+      supportsReturning: () => true,
+      supportsTransactionalDdl: () => false,
+    }),
+    createDriver: () => ({
+      init: async () => {},
+      destroy: async () => {},
+      acquireConnection: async () => ({
+        executeQuery: async <R>(compiledQuery: {
+          sql: string;
+          parameters: readonly unknown[];
+        }) => {
+          const response = await wretch(
+            `https://api.cloudflare.com/client/v4/accounts/${accountId}/d1/database/${databaseId}/query`,
+          )
+            .auth(`Bearer ${apiToken}`)
+            .post({
+              sql: compiledQuery.sql,
+              params: compiledQuery.parameters,
+            })
+            .json<{ success: boolean; result: Array<{ results: R[] }> }>();
+
+          if (!response.success) {
+            throw new Error("D1 REST query failed");
+          }
+
+          return {
+            rows: response.result[0]?.results ?? [],
+            numAffectedRows: BigInt(0),
+            insertId: undefined,
+          };
+        },
+        releaseConnection: async () => {},
+      }),
+      releaseConnection: async () => {},
+    }),
+    createIntrospector: (_db: Kysely<any>) => ({
+      getSchemas: async () => [],
+      getTables: async () => [],
+      getMetadata: async () => ({ schemas: [], tables: [] }),
+    }),
+    createQueryCompiler: () => new SqliteQueryCompiler(),
+  };
+}

package/dist/cloudflare-multitenant/src/index.ts

@@ -0,0 +1,71 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { D1Dialect } from "kysely-d1";
+import { Kysely } from "kysely";
+import createKyselyAdapters from "@authhero/kysely-adapter";
+import createCloudflareAdapters from "@authhero/cloudflare-adapter";
+import { createMultiTenancyPlugin } from "@authhero/multi-tenancy";
+import createApp from "./app";
+import { Env } from "./types";
+import { AuthHeroConfig, Bindings, Variables } from "authhero";
+import { createDatabaseFactory } from "./database-factory";
+
+let app: OpenAPIHono<{ Bindings: Bindings; Variables: Variables }> | undefined;
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    if (!app) {
+      // Create main database adapters
+      const mainDialect = new D1Dialect({ database: env.MAIN_DB });
+      const mainDb = new Kysely<any>({ dialect: mainDialect });
+      const mainDataAdapter = createKyselyAdapters(mainDb);
+
+      // Create database factory for multi-tenant database isolation
+      const databaseFactory = createDatabaseFactory(
+        env.MAIN_DB,
+        env.CLOUDFLARE_ACCOUNT_ID,
+        env.CLOUDFLARE_API_TOKEN,
+        env.MAIN_TENANT_ID,
+      );
+
+      // Create Cloudflare-specific adapters (cache, custom domains, geo)
+      const cloudflareAdapters = createCloudflareAdapters({
+        accountId: env.CLOUDFLARE_ACCOUNT_ID,
+        apiToken: env.CLOUDFLARE_API_TOKEN,
+        // Analytics Engine for logs
+        analyticsEngineLogs: {
+          analyticsEngineBinding: env.AUTH_LOGS,
+          accountId: env.CLOUDFLARE_ACCOUNT_ID,
+          apiToken: env.ANALYTICS_ENGINE_API_TOKEN || env.CLOUDFLARE_API_TOKEN,
+          dataset: "authhero_logs",
+        },
+      });
+
+      // Create multi-tenancy plugin
+      const multiTenancyPlugin = createMultiTenancyPlugin({
+        accessControl: {
+          mainTenantId: env.MAIN_TENANT_ID,
+          defaultPermissions: ["tenant:admin", "tenant:read", "tenant:write"],
+        },
+        subdomainRouting: env.BASE_DOMAIN
+          ? {
+              baseDomain: env.BASE_DOMAIN,
+            }
+          : undefined,
+        databaseIsolation: {
+          getAdapters: databaseFactory.getAdapters,
+          onProvision: databaseFactory.provision,
+          onDeprovision: databaseFactory.deprovision,
+        },
+      });
+
+      const config: AuthHeroConfig = {
+        dataAdapter: mainDataAdapter,
+        ...cloudflareAdapters,
+      };
+
+      app = createApp(config, multiTenancyPlugin);
+    }
+
+    return app.fetch(request, env);
+  },
+};

package/dist/cloudflare-multitenant/src/types.ts

@@ -0,0 +1,24 @@
+/// <reference types="@cloudflare/workers-types" />
+
+import { AnalyticsEngineDataset } from "@authhero/cloudflare-adapter";
+
+export interface Env {
+  // Main D1 database for tenant registry and main tenant data
+  MAIN_DB: D1Database;
+
+  // Analytics Engine for logs
+  AUTH_LOGS: AnalyticsEngineDataset;
+
+  // Cloudflare API credentials for dynamic D1 database management
+  CLOUDFLARE_ACCOUNT_ID: string;
+  CLOUDFLARE_API_TOKEN: string;
+
+  // Optional: Analytics Engine API token (may be different from main API token)
+  ANALYTICS_ENGINE_API_TOKEN?: string;
+
+  // Base domain for subdomain routing (e.g., "auth.example.com")
+  BASE_DOMAIN?: string;
+
+  // Main tenant ID
+  MAIN_TENANT_ID: string;
+}

package/dist/cloudflare-multitenant/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-multitenant/wrangler.toml

@@ -0,0 +1,38 @@
+name = "authhero-multitenant"
+main = "src/index.ts"
+compatibility_date = "2024-11-20"
+
+# Main D1 Database (stores tenant registry and main tenant data)
+# Run: wrangler d1 create authhero-main-db
+# Then update the database_id below:
+[[d1_databases]]
+binding = "MAIN_DB"
+database_name = "authhero-main-db"
+database_id = "local"
+
+# Analytics Engine for logs
+# Create in Cloudflare Dashboard: Workers & Pages > Analytics Engine
+[[analytics_engine_datasets]]
+binding = "AUTH_LOGS"
+dataset = "authhero_logs"
+
+# Environment variables
+# For local development, create a .dev.vars file with these values:
+# CLOUDFLARE_ACCOUNT_ID=your_account_id
+# CLOUDFLARE_API_TOKEN=your_api_token
+# ANALYTICS_ENGINE_API_TOKEN=your_analytics_token (optional)
+# MAIN_TENANT_ID=main
+# BASE_DOMAIN=auth.example.com (optional)
+
+[vars]
+MAIN_TENANT_ID = "main"
+# BASE_DOMAIN = "auth.example.com"
+
+# Optional: Enable observability
+[observability]
+enabled = true
+
+# Optional: Custom domain routing
+# routes = [
+#   { pattern = "*.auth.example.com", custom_domain = true }
+# ]

package/dist/cloudflare-simple/README.md

@@ -0,0 +1,75 @@
+# AuthHero Cloudflare Simple Server
+
+A single-tenant AuthHero authentication server using Cloudflare Workers and D1.
+
+## Prerequisites
+
+- [Cloudflare Account](https://dash.cloudflare.com/sign-up)
+- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/)
+
+## Getting Started
+
+1. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+2. Create a D1 database:
+
+   ```bash
+   wrangler d1 create authhero-db
+   ```
+
+3. Update `wrangler.toml` with your database ID from the output above.
+
+4. Run local database migrations:
+
+   ```bash
+   npm run db:migrate
+   ```
+
+5. Start the development server:
+   ```bash
+   npm run dev
+   ```
+
+## Deployment
+
+1. Deploy to Cloudflare:
+
+   ```bash
+   npm run deploy
+   ```
+
+2. Run production migrations:
+   ```bash
+   npm run db:migrate:prod
+   ```
+
+## Project Structure
+
+```
+├── src/
+│   ├── index.ts    # Worker entry point
+│   ├── app.ts      # AuthHero app configuration
+│   └── types.ts    # TypeScript type definitions
+├── wrangler.toml   # Cloudflare Worker configuration
+└── package.json
+```
+
+## API Documentation
+
+Visit your worker URL with `/docs` to see the Swagger UI documentation.
+
+## Custom Domain
+
+To add a custom domain, update `wrangler.toml`:
+
+```toml
+routes = [
+  { pattern = "auth.yourdomain.com", custom_domain = true }
+]
+```
+
+For more information, visit [https://authhero.net/docs](https://authhero.net/docs).