@authhero/cloudflare-adapter 2.33.3 → 2.34.0

package/dist/types/wfp-provisioner/cf-api.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Thin Cloudflare REST API client for the WFP+D1 provisioner.
+ *
+ * Each method maps 1:1 to a documented CF endpoint and returns the parsed
+ * response body. Errors surface as `CloudflareApiError` carrying the HTTP
+ * status, endpoint, and (when JSON) the CF error array — making them easy
+ * to log without re-fetching the response.
+ *
+ * Idempotency is the caller's responsibility — the provisioner sequences
+ * calls and tolerates "already exists" / "not found" depending on the
+ * operation (see `provisioner.ts`).
+ */
+export declare class CloudflareApiError extends Error {
+    readonly status: number;
+    readonly endpoint: string;
+    readonly errors: unknown[];
+    readonly body: string;
+    constructor(status: number, endpoint: string, body: string, errors?: unknown[]);
+}
+export interface CfApiClientOptions {
+    accountId: string;
+    apiToken: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    baseUrl?: string;
+}
+export interface D1Database {
+    uuid: string;
+    name: string;
+}
+export interface D1QueryResult {
+    success: boolean;
+    meta?: Record<string, unknown>;
+    results?: unknown[];
+}
+export interface ScriptBinding {
+    type: "d1" | "plain_text" | "secret_text";
+    name: string;
+    id?: string;
+    text?: string;
+}
+export interface ScriptUploadOptions {
+    /** Script source (JavaScript ES module). */
+    script: string;
+    /** Main module filename (must match part name in form data). */
+    mainModule: string;
+    /** Compatibility date, ISO yyyy-mm-dd. */
+    compatibilityDate: string;
+    /** Compatibility flags (e.g. `["nodejs_compat"]`). */
+    compatibilityFlags?: string[];
+    /** Bindings to attach (D1, plain_text, etc.). Secrets go via setSecret(). */
+    bindings?: ScriptBinding[];
+    /** Optional tags, stored on the script for operator-side lookup. */
+    tags?: string[];
+}
+export declare class CloudflareApiClient {
+    private readonly accountId;
+    private readonly apiToken;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly baseUrl;
+    constructor(options: CfApiClientOptions);
+    createD1Database(name: string): Promise<D1Database>;
+    listD1Databases(name?: string): Promise<D1Database[]>;
+    deleteD1Database(databaseId: string): Promise<void>;
+    /**
+     * Execute a single SQL statement (or batch of `;`-separated statements
+     * permitted by D1) against the given database. Use for applying
+     * migrations one file at a time — the per-call response size cap means
+     * very large single calls can fail; splitting per file keeps each call
+     * bounded by the migration author.
+     */
+    execD1(databaseId: string, sql: string): Promise<D1QueryResult[]>;
+    uploadNamespacedScript(namespace: string, scriptName: string, options: ScriptUploadOptions): Promise<void>;
+    deleteNamespacedScript(namespace: string, scriptName: string): Promise<void>;
+    /**
+     * Set a single secret on a namespaced script. The CF API replaces the
+     * value if a secret with that name already exists, so this is safely
+     * re-runnable.
+     */
+    setNamespacedScriptSecret(namespace: string, scriptName: string, secretName: string, secretValue: string): Promise<void>;
+    private request;
+}

package/dist/types/wfp-provisioner/index.d.ts

@@ -0,0 +1,6 @@
+export { createCloudflareWfpD1Provisioner } from "./provisioner";
+export type { CloudflareWfpD1Provisioner, CloudflareWfpD1ProvisionerOptions, ProvisionResult, ProvisionerMigration, TenantSecretsResolver, } from "./types";
+export { createWfpTenantProvisioningHook } from "./tenant-hook";
+export type { WfpTenantProvisioningHook, WfpTenantProvisioningHookOptions, } from "./tenant-hook";
+export { CloudflareApiClient, CloudflareApiError } from "./cf-api";
+export type { CfApiClientOptions, D1Database, D1QueryResult, ScriptBinding, ScriptUploadOptions, } from "./cf-api";

package/dist/types/wfp-provisioner/provisioner.d.ts

@@ -0,0 +1,47 @@
+import type { CloudflareWfpD1Provisioner, CloudflareWfpD1ProvisionerOptions } from "./types";
+/**
+ * Construct the lifecycle hooks for provisioning + deprovisioning a tenant
+ * on Cloudflare Workers-for-Platforms backed by a per-tenant D1.
+ *
+ * Wiring on the control-plane authhero:
+ *
+ * ```ts
+ * import createAdapters from "@authhero/cloudflare-adapter";
+ * import { createCloudflareWfpD1Provisioner } from "@authhero/cloudflare-adapter";
+ * import { initMultiTenant } from "@authhero/multi-tenancy";
+ * import tenantWorkerScript from "./tenant-worker.dist.js?raw";
+ * import migration0001 from "@authhero/drizzle/drizzle/sqlite/0000_initial.sql?raw";
+ *
+ * const provisioner = createCloudflareWfpD1Provisioner({
+ *   accountId: env.CLOUDFLARE_ACCOUNT_ID,
+ *   apiToken: env.CLOUDFLARE_API_TOKEN,
+ *   dispatchNamespace: "authhero-tenants",
+ *   controlPlaneBaseUrl: env.PUBLIC_BASE_URL,
+ *   tenantWorkerScript,
+ *   migrations: [{ name: "0000_initial.sql", sql: migration0001 }],
+ *   secrets: async (tenantId) => ({
+ *     ENCRYPTION_KEY: env.SHARED_ENCRYPTION_KEY,
+ *     ISSUER: `https://${tenantId}.tokens.example.com`,
+ *   }),
+ * });
+ *
+ * const { app } = initMultiTenant({
+ *   dataAdapter,
+ *   controlPlane: { tenantId: "main", clientId: "platform" },
+ *   databaseIsolation: {
+ *     getAdapters: async (tenantId) => { ... },   // resolve per-tenant adapter
+ *     onProvision: provisioner.onProvision,
+ *     onDeprovision: provisioner.onDeprovision,
+ *   },
+ * });
+ * ```
+ *
+ * On tenant create, the management API row write fires
+ * `databaseIsolation.onProvision(tenantId)` which runs the full sequence
+ * below. If any step throws, the upstream `createProvisioningHooks` rolls
+ * back the tenant row — though side effects already taken (D1 created,
+ * partial migrations applied) are NOT rolled back. The operator should
+ * treat re-running `onProvision(tenantId)` as safe; each step is idempotent
+ * on "already exists".
+ */
+export declare function createCloudflareWfpD1Provisioner(options: CloudflareWfpD1ProvisionerOptions): CloudflareWfpD1Provisioner;

package/dist/types/wfp-provisioner/tenant-hook.d.ts

@@ -0,0 +1,68 @@
+import type { TenantsDataAdapter } from "@authhero/adapter-interfaces";
+import type { CloudflareWfpD1Provisioner } from "./types";
+/**
+ * Adapt the provisioner to `@authhero/multi-tenancy`'s
+ * `databaseIsolation.onProvision` / `onDeprovision` contract by:
+ *
+ *  1. Looking up the tenant row first and gating on
+ *     `tenant.deployment_type === "wfp"` — shared tenants short-circuit so
+ *     the same control plane can host both kinds without code branches.
+ *  2. Running the provisioner sequence (D1 + script + secrets).
+ *  3. Writing the resulting `d1_database_id` + `worker_script_name` +
+ *     `provisioning_state` back onto the tenant row so the admin UI can
+ *     show real status, and so a redeploy / re-provision knows which
+ *     resource ids to operate on.
+ *  4. On failure, marking `provisioning_state = "failed"` with the error
+ *     message, then re-throwing — the multi-tenancy hook treats the throw
+ *     as a signal to roll back the tenant row.
+ *
+ * Typical wiring on the control-plane authhero:
+ *
+ * ```ts
+ * import { initMultiTenant } from "@authhero/multi-tenancy";
+ * import {
+ *   createCloudflareWfpD1Provisioner,
+ *   createWfpTenantProvisioningHook,
+ * } from "@authhero/cloudflare-adapter";
+ *
+ * const provisioner = createCloudflareWfpD1Provisioner({ ... });
+ * const hook = createWfpTenantProvisioningHook({
+ *   provisioner,
+ *   tenants: dataAdapter.tenants,
+ * });
+ *
+ * const { app } = initMultiTenant({
+ *   dataAdapter,
+ *   databaseIsolation: {
+ *     getAdapters: async (tenantId) => { ... },
+ *     onProvision: hook.onProvision,
+ *     onDeprovision: hook.onDeprovision,
+ *   },
+ * });
+ * ```
+ */
+export interface WfpTenantProvisioningHookOptions {
+    provisioner: CloudflareWfpD1Provisioner;
+    tenants: TenantsDataAdapter;
+    /**
+     * Optional override of "should this tenant be WFP-provisioned?". Defaults
+     * to `tenant.deployment_type === "wfp"`. Provide a custom predicate when
+     * the gating signal lives elsewhere (a feature flag, a config table, etc.).
+     */
+    shouldProvision?: (tenant: {
+        id: string;
+        deployment_type?: string;
+        storage_kind?: string;
+    }) => boolean;
+    /**
+     * Optional `console`-compatible logger for warnings emitted when the
+     * tenant row write-back fails after a successful provision. Defaults to
+     * a silent no-op so this module stays test-quiet.
+     */
+    logger?: Pick<Console, "warn">;
+}
+export interface WfpTenantProvisioningHook {
+    onProvision(tenantId: string): Promise<void>;
+    onDeprovision(tenantId: string): Promise<void>;
+}
+export declare function createWfpTenantProvisioningHook(options: WfpTenantProvisioningHookOptions): WfpTenantProvisioningHook;

package/dist/types/wfp-provisioner/tenant-worker.example.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Canonical tenant-worker entrypoint for a Workers-for-Platforms + D1
+ * authhero deployment. Reference only — copy into your own tenant-worker
+ * source tree and bundle from there (this file is not bundled into
+ * `@authhero/cloudflare-adapter`'s `dist`).
+ *
+ * The bundle the provisioner uploads must be a single self-contained ESM
+ * `.js`. Operators build it themselves so they can layer in custom hooks,
+ * code-executors, secrets, etc. Below is the minimal shape every operator
+ * needs.
+ *
+ * Env contract set by `createCloudflareWfpD1Provisioner.onProvision`:
+ *
+ *  | Name                     | Source       | Purpose                                              |
+ *  | ------------------------ | ------------ | ---------------------------------------------------- |
+ *  | AUTH_DB                  | D1 binding   | Per-tenant database                                  |
+ *  | CONTROL_PLANE_BASE_URL   | plain_text   | Target of `controlPlaneSync` outbox destination      |
+ *  | ENCRYPTION_KEY           | secret_text  | Encryption at rest (must be byte-stable across plane)|
+ *  | ISSUER                   | secret_text  | `iss` claim in JWTs                                  |
+ *  | …additional secrets…     | secret_text  | JWKS, mail creds, OAuth client secrets, etc.         |
+ *
+ * Recommended bundler call:
+ *
+ * ```sh
+ * esbuild src/tenant-worker.ts \
+ *   --bundle --format=esm --platform=neutral --target=es2022 \
+ *   --conditions=workerd,worker,browser \
+ *   --outfile=dist/tenant-worker.js
+ * ```
+ *
+ * Wiring into the provisioner (control-plane authhero side):
+ *
+ * ```ts
+ * import tenantWorkerScript from "./tenant-worker.dist.js?raw";
+ * import { createCloudflareWfpD1Provisioner } from "@authhero/cloudflare-adapter";
+ *
+ * const provisioner = createCloudflareWfpD1Provisioner({
+ *   accountId,
+ *   apiToken,
+ *   dispatchNamespace: "authhero-tenants",
+ *   controlPlaneBaseUrl: env.PUBLIC_BASE_URL,
+ *   tenantWorkerScript,
+ *   migrations: [
+ *     { name: "0000_initial.sql", sql: initialMigrationSql },
+ *     // ...one entry per @authhero/drizzle migration file, in order
+ *   ],
+ *   secrets: async (tenantId) => ({
+ *     ENCRYPTION_KEY: env.SHARED_ENCRYPTION_KEY,  // byte-stable across all tenants
+ *     ISSUER: `https://${tenantId}.tokens.example.com`,
+ *     // …whichever else authhero reads from env
+ *   }),
+ * });
+ * ```
+ *
+ * Minimal tenant-worker source (copy and adapt):
+ *
+ * ```ts
+ * import { drizzle } from "drizzle-orm/d1";
+ * import createDataAdapters from "@authhero/drizzle";
+ * import { init } from "authhero";
+ *
+ * interface TenantWorkerEnv {
+ *   AUTH_DB: D1Database;
+ *   CONTROL_PLANE_BASE_URL: string;
+ *   ENCRYPTION_KEY: string;
+ *   ISSUER: string;
+ *   // …your additional secrets
+ * }
+ *
+ * export default {
+ *   async fetch(
+ *     request: Request,
+ *     env: TenantWorkerEnv,
+ *     ctx: ExecutionContext,
+ *   ): Promise<Response> {
+ *     const db = drizzle(env.AUTH_DB);
+ *     const dataAdapter = createDataAdapters(db);
+ *
+ *     const { app } = init({
+ *       dataAdapter,
+ *       controlPlaneSync: {
+ *         baseUrl: env.CONTROL_PLANE_BASE_URL,
+ *         timeoutMs: 10_000,
+ *       },
+ *     });
+ *
+ *     return app.fetch(request, env, ctx);
+ *   },
+ * };
+ * ```
+ */
+export {};

package/dist/types/wfp-provisioner/types.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Public types for the Workers-for-Platforms + D1 tenant provisioner.
+ *
+ * Wire-up shape — the operator constructs a provisioner once at control-plane
+ * boot and passes its `onProvision` / `onDeprovision` to
+ * `@authhero/multi-tenancy`'s `databaseIsolation` config. Every tenant
+ * create/delete in the management API then drives a CF API call sequence
+ * that:
+ *   1. (create) provisions a per-tenant D1, applies migrations, deploys a
+ *      namespaced worker bound to that D1, and uploads secrets to it.
+ *   2. (delete) removes the namespaced worker and its D1.
+ *
+ * Failures throw — the multi-tenancy hook wraps `onProvision` such that a
+ * thrown error rolls the tenant row back. Idempotency on retry is best-effort:
+ * each step checks for "already exists" and continues, but the operator
+ * should treat the provisioning sequence as restartable rather than
+ * transactional.
+ */
+/**
+ * SQL migration to run on every new tenant D1, in order.
+ *
+ * Operators bundle these from `@authhero/drizzle`'s `drizzle/sqlite/` files
+ * via their build tool of choice (vite's `?raw`, esbuild loader, webpack's
+ * raw-loader, etc.) — the provisioner is agnostic about how the SQL gets
+ * loaded.
+ */
+export interface ProvisionerMigration {
+    /** Filename, used only for error messages and audit logging. */
+    name: string;
+    /** Full SQL text of the migration. May contain multiple statements. */
+    sql: string;
+}
+/**
+ * Resolver that returns the secret values to upload onto a newly-provisioned
+ * tenant worker. Called once per tenant during `onProvision`.
+ *
+ * Implementations typically pull from a secret store (Vault, GCP Secret
+ * Manager, etc.) — the values must match the control-plane authhero's
+ * expectations for that tenant (notably `ENCRYPTION_KEY` and JWT signing
+ * material, which must be byte-stable to keep encrypted-at-rest data and
+ * issued JWTs valid).
+ */
+export type TenantSecretsResolver = (tenantId: string) => Promise<Record<string, string>>;
+export interface CloudflareWfpD1ProvisionerOptions {
+    /** Cloudflare account id that owns the namespace, D1s, and tenant workers. */
+    accountId: string;
+    /**
+     * API token with at least these permissions on `accountId`:
+     *   - Workers Scripts:Edit
+     *   - D1:Edit
+     *   - Workers for Platforms:Edit (for namespace ops)
+     */
+    apiToken: string;
+    /** Name of the dispatch namespace tenant workers are deployed into. */
+    dispatchNamespace: string;
+    /**
+     * Base URL of the control-plane authhero. Passed to the tenant worker via
+     * the `CONTROL_PLANE_BASE_URL` env var so its `controlPlaneSync` destination
+     * knows where to POST `controlplane.sync.*` events.
+     */
+    controlPlaneBaseUrl: string;
+    /**
+     * Full JavaScript bundle of the tenant worker. The operator builds this
+     * (typically via esbuild/vite of a thin wrapper that calls
+     * `authhero.init({ ... })`), and passes the resulting JS string here.
+     *
+     * The bundle MUST be self-contained — Cloudflare's script upload doesn't
+     * resolve npm dependencies. Use your bundler's `format: 'esm'` + `external`
+     * lists to inline `authhero`, `@authhero/drizzle`, and friends.
+     */
+    tenantWorkerScript: string;
+    /**
+     * Optional script metadata override. Defaults to
+     * `{ main_module: "index.js", compatibility_date, compatibility_flags: ["nodejs_compat"] }`.
+     * Set `compatibility_date` to the same date the rest of your workers use.
+     */
+    scriptMetadata?: {
+        main_module?: string;
+        compatibility_date?: string;
+        compatibility_flags?: string[];
+    };
+    /**
+     * SQL migrations applied in array order to every new tenant D1. Typically
+     * loaded from `@authhero/drizzle`'s shipped migrations via your build tool.
+     */
+    migrations: ProvisionerMigration[];
+    /**
+     * Resolver that returns the secret values to set on the tenant worker.
+     * Called once per `onProvision`. The provisioner uploads each entry via
+     * the per-script secrets API.
+     */
+    secrets: TenantSecretsResolver;
+    /**
+     * Naming convention for the namespaced script. Supports `{tenant_id}`
+     * placeholder. Defaults to `"{tenant_id}"`.
+     *
+     * Must match whatever the dispatcher synthesizes as `script_name` in its
+     * `dispatch_namespace` handler — otherwise the dispatcher can't reach the
+     * worker after provisioning.
+     */
+    scriptNameTemplate?: string;
+    /**
+     * Naming convention for the per-tenant D1. Supports `{tenant_id}`.
+     * Defaults to `"tenant-{tenant_id}"`. CF accepts most ASCII names; keep
+     * it stable so a re-provision finds the existing D1.
+     */
+    d1NameTemplate?: string;
+    /**
+     * Fetch override (tests only). Defaults to global `fetch`.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Per-request timeout (ms) on the CF API. Defaults to 30s. Individual
+     * D1 migrations can take a few seconds each; the upload of a multi-MB
+     * tenant bundle also takes a noticeable chunk of that.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Outcome of a successful `onProvision` — returned so the caller can persist
+ * the resource IDs back onto the tenant row (`tenants.d1_database_id`,
+ * `tenants.worker_script_name`). The control-plane authhero ships these
+ * fields in its schema; `createWfpTenantProvisioningHook` writes them
+ * automatically.
+ */
+export interface ProvisionResult {
+    d1DatabaseId: string;
+    scriptName: string;
+    d1Name: string;
+}
+/**
+ * What `createCloudflareWfpD1Provisioner` returns — the two lifecycle
+ * callbacks that plug into `databaseIsolation` from `@authhero/multi-tenancy`
+ * via the `createWfpTenantProvisioningHook` wrapper (which handles
+ * deployment-type guarding and tenant-row writebacks).
+ */
+export interface CloudflareWfpD1Provisioner {
+    onProvision(tenantId: string): Promise<ProvisionResult>;
+    onDeprovision(tenantId: string): Promise<void>;
+}

package/package.json

@@ -11,7 +11,7 @@
     "type": "git",
     "url": "https://github.com/markusahlstrand/authhero"
   },
-  "version": "2.33.3",
+  "version": "2.34.0",
   "files": [
     "dist"
   ],
@@ -44,8 +44,8 @@
   "dependencies": {
     "nanoid": "^5.1.11",
     "wretch": "^3.0.8",
-    "@authhero/adapter-interfaces": "3.1.0",
-    "@authhero/kysely-adapter": "11.8.7"
+    "@authhero/adapter-interfaces": "3.1.1",
+    "@authhero/kysely-adapter": "11.8.8"
   },
   "scripts": {
     "build": "vite build && tsc -p tsconfig.types.json && rollup -c rollup.dts.config.mjs",