@authhero/cloudflare-adapter 2.37.6 → 2.38.1

package/dist/types/index.d.ts

@@ -19,8 +19,8 @@ export { createAnalyticsEngineAnalyticsAdapter } from "./analytics-engine-logs";
 export { createAnalyticsEngineActionExecutionsAdapter } from "./analytics-engine-action-executions";
 export { createR2SQLLogsAdapter } from "./r2-sql-logs";
 export { createR2SQLStatsAdapter } from "./r2-sql-logs";
-export { createCloudflareWfpD1Provisioner, createWfpTenantProvisioningHook, createWfpForwardMiddleware, CloudflareApiClient, CloudflareApiError, } from "./wfp-provisioner";
-export type { CloudflareWfpD1Provisioner, CloudflareWfpD1ProvisionerOptions, ProvisionResult, ProvisionerMigration, TenantSecretsResolver, WfpTenantProvisioningHook, WfpTenantProvisioningHookOptions, CfApiClientOptions, D1Database, D1QueryResult, ScriptBinding, ScriptUploadOptions, WfpForwardOptions, } from "./wfp-provisioner";
+export { createCloudflareWfpD1Provisioner, createWfpProvisionerSteps, createWfpTenantProvisioningHook, createWfpForwardMiddleware, CloudflareApiClient, CloudflareApiError, } from "./wfp-provisioner";
+export type { CloudflareWfpD1Provisioner, CloudflareWfpD1ProvisionerOptions, TenantProvisionerSteps, TenantProvisionNames, WfpProvisionerSteps, ProvisionResult, ProvisionerMigration, TenantSecretsResolver, WfpTenantProvisioningHook, WfpTenantProvisioningHookOptions, CfApiClientOptions, D1Database, D1QueryResult, ScriptBinding, ScriptUploadOptions, WfpForwardOptions, } from "./wfp-provisioner";
 export interface CloudflareAdapters {
     customDomains: CustomDomainsAdapter;
     cache: CacheAdapter;

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

@@ -1,4 +1,7 @@
 export { createCloudflareWfpD1Provisioner } from "./provisioner";
+export { createWfpProvisionerSteps, escapeSqlLiteral, } from "./provisioner-steps";
+export type { TenantProvisionerSteps, TenantProvisionNames, WfpProvisionerSteps, } from "./provisioner-steps";
+export { collectSyncDefaultsErrors } from "./sync-defaults-errors";
 export type { CloudflareWfpD1Provisioner, CloudflareWfpD1ProvisionerOptions, ProvisionResult, ProvisionerMigration, TenantSecretsResolver, } from "./types";
 export { createWfpTenantProvisioningHook } from "./tenant-hook";
 export type { WfpTenantProvisioningHook, WfpTenantProvisioningHookOptions, } from "./tenant-hook";

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

@@ -0,0 +1,54 @@
+import { CloudflareApiClient } from "./cf-api";
+import type { CloudflareWfpD1ProvisionerOptions } from "./types";
+export declare function isNotFoundError(err: unknown): boolean;
+export declare function escapeSqlLiteral(value: string): string;
+export interface TenantProvisionNames {
+    scriptName: string;
+    databaseName: string;
+}
+/**
+ * Provider-agnostic contract for the individual, idempotent units of
+ * tenant provisioning. Deliberately free of Cloudflare/D1 terminology so
+ * the durable operation orchestration (issue #1026 phase 2) — and any
+ * future provider (e.g. Bunny with its SQLite databases) — can run against
+ * it. `createWfpProvisionerSteps` is the Cloudflare Workers-for-Platforms
+ * + D1 implementation.
+ */
+export interface TenantProvisionerSteps {
+    names(tenantId: string): TenantProvisionNames;
+    /**
+     * Validate the version token persisted into `tenants.database_version`
+     * BEFORE any provider side effects. Returns the recorded versions.
+     */
+    validate(): {
+        databaseVersion?: string;
+        bundleConfiguration?: string;
+        workerVersion?: string;
+    };
+    findOrCreateDatabase(name: string): Promise<{
+        id: string;
+        created: boolean;
+    }>;
+    /**
+     * Reconcile migrations against the provisioner-owned tracking table
+     * (`_authhero_provisioner_migrations`), including the legacy backfill
+     * branch for pre-tracking databases.
+     */
+    applyMigrations(databaseId: string, created: boolean): Promise<void>;
+    uploadScript(scriptName: string, databaseId: string): Promise<void>;
+    uploadSecrets(scriptName: string, tenantId: string): Promise<void>;
+    /** Best-effort teardown of both resources; throws a combined error. */
+    deprovision(tenantId: string): Promise<void>;
+}
+/**
+ * The Cloudflare WFP + D1 implementation of `TenantProvisionerSteps`,
+ * extracted from `createCloudflareWfpD1Provisioner` so each unit can run
+ * as its own durable workflow step while the inline provisioner keeps
+ * running them as one sequence. No behavior change from the original
+ * closures — the provisioner is a thin sequence over this object.
+ */
+export interface WfpProvisionerSteps extends TenantProvisionerSteps {
+    /** Underlying REST client — shared with deprovision and the verify step. */
+    client: CloudflareApiClient;
+}
+export declare function createWfpProvisionerSteps(options: CloudflareWfpD1ProvisionerOptions): WfpProvisionerSteps;

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

@@ -43,5 +43,9 @@ import type { CloudflareWfpD1Provisioner, CloudflareWfpD1ProvisionerOptions } fr
  * partial migrations applied) are NOT rolled back. The operator should
  * treat re-running `onProvision(tenantId)` as safe; each step is idempotent
  * on "already exists".
+ *
+ * The individual steps live in `createWfpProvisionerSteps` so the durable
+ * workflow executor (issue #1026 phase 2) can run the same units with
+ * per-step retries; this factory is a thin inline sequence over them.
  */
 export declare function createCloudflareWfpD1Provisioner(options: CloudflareWfpD1ProvisionerOptions): CloudflareWfpD1Provisioner;

package/dist/types/wfp-provisioner/sync-defaults-errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Collects per-entity `errors` from a sync-defaults apply result. The seed runs
+ * with `continueOnError`, so the tenant worker returns a 2xx (no rejection)
+ * even when individual entities fail — a clean resolve is therefore not proof
+ * the seed landed. Walk the result's entity outcomes and surface any collected
+ * errors so a partially-seeded tenant isn't marked `ready`.
+ *
+ * Shared between the inline tenant hook and the durable workflow's
+ * seed-defaults step (issue #1026 phase 2).
+ */
+export declare function collectSyncDefaultsErrors(result: unknown): string[];

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

@@ -78,8 +78,16 @@ export interface WfpTenantProvisioningHookOptions {
      */
     syncDefaults?: (tenantId: string) => Promise<unknown>;
 }
+/**
+ * Structural mirror of `@authhero/multi-tenancy`'s `StepReporter` — kept
+ * local so this module carries no multi-tenancy dependency. When the
+ * control plane records provisions as tenant operations (issue #1026),
+ * the hook receives this callback and surfaces coarse step boundaries
+ * (`provision-resources`, `seed-defaults`) in the operation history.
+ */
+export type WfpProvisioningStepReporter = (step: string, outcome: "started" | "succeeded" | "failed", detail?: Record<string, unknown>) => Promise<void>;
 export interface WfpTenantProvisioningHook {
-    onProvision(tenantId: string): Promise<void>;
+    onProvision(tenantId: string, report?: WfpProvisioningStepReporter): Promise<void>;
     onDeprovision(tenantId: string): Promise<void>;
     /**
      * Re-run provisioning for an already-existing WFP tenant to pull it onto the
@@ -93,6 +101,6 @@ export interface WfpTenantProvisioningHook {
      * Throws if the tenant doesn't exist or isn't WFP-provisioned — callers
      * (e.g. a management-API redeploy endpoint) surface that as a 4xx.
      */
-    onUpgrade(tenantId: string): Promise<void>;
+    onUpgrade(tenantId: string, report?: WfpProvisioningStepReporter): Promise<void>;
 }
 export declare function createWfpTenantProvisioningHook(options: WfpTenantProvisioningHookOptions): WfpTenantProvisioningHook;

package/dist/types/workflows/enqueue-hook.d.ts

@@ -0,0 +1,49 @@
+import type { TenantOperation, TenantsDataAdapter } from "@authhero/adapter-interfaces";
+import type { WfpTenantProvisioningHook } from "../wfp-provisioner/tenant-hook";
+export interface WfpWorkflowProvisioningHookOptions {
+    tenants: TenantsDataAdapter;
+    /**
+     * Enqueues a provision operation on the durable engine — typically
+     * `(input) => enqueueTenantOperation(stores, createCloudflareWorkflowsExecutor({ binding }), input)`.
+     * Resolves as soon as the engine instance is created.
+     */
+    enqueueOperation: (input: {
+        kind: "provision";
+        tenant_id: string;
+        initiated_by?: string;
+    }) => Promise<TenantOperation>;
+    /** Same gate + default as the inline hook: `deployment_type === "wfp"`. */
+    shouldProvision?: (tenant: {
+        id: string;
+        deployment_type?: string;
+        storage_kind?: string;
+    }) => boolean;
+    /**
+     * The existing inline hook (`createWfpTenantProvisioningHook(...)`).
+     * Upgrade and deprovision keep running inline until later phases make
+     * them durable.
+     */
+    inline: WfpTenantProvisioningHook;
+}
+/**
+ * Drop-in replacement for `createWfpTenantProvisioningHook` on control
+ * planes that run provisioning through Cloudflare Workflows (issue #1026
+ * phase 2): `onProvision` enqueues a durable provision operation and
+ * returns immediately, leaving the tenant `pending` — the workflow's
+ * `mark-ready` / `mark-failed` steps own the terminal snapshot writes, and
+ * the reconciler covers instances that die mid-run.
+ *
+ * Semantic change to plan for downstream: tenant-create now returns with
+ * `provisioning_state: "pending"`; clients poll the tenant row or the
+ * operations API. An enqueue failure still throws, so
+ * `createProvisioningHooks.afterCreate` rolls the tenant row back exactly
+ * like an inline provision failure does today. This also replaces any
+ * best-effort post-create seed — the seed is a durable step inside the
+ * workflow.
+ *
+ * Wire it with `databaseIsolation.recordProvisionOperations: false` — this
+ * hook's `enqueueOperation` creates the operation row itself, and the
+ * multi-tenancy recording wrapper would otherwise write a second row that
+ * gets marked succeeded while the engine run is still in flight.
+ */
+export declare function createWfpWorkflowProvisioningHook(options: WfpWorkflowProvisioningHookOptions): WfpTenantProvisioningHook;

package/dist/types/workflows/entrypoint.example.d.ts

@@ -0,0 +1,118 @@
+/**
+ * REFERENCE ONLY — not part of the published bundle (nothing imports it).
+ *
+ * The downstream control-plane worker (the deploy repo) owns the
+ * `WorkflowEntrypoint` shell, because `cloudflare:workers` only exists in
+ * the Workers runtime. Everything else — orchestration, verify, write-back
+ * — comes from `@authhero/cloudflare-adapter/workflows`.
+ *
+ * wrangler.jsonc:
+ * ```jsonc
+ * {
+ *   "workflows": [
+ *     {
+ *       "name": "tenant-operations",
+ *       "binding": "TENANT_OPERATIONS_WORKFLOW",
+ *       "class_name": "TenantOperationWorkflow"
+ *     }
+ *   ],
+ *   // Reconciler cadence: at least daily (engine retention is 30 days);
+ *   // every 15–60 minutes recommended.
+ *   "triggers": { "crons": ["0,30 * * * *"] }
+ * }
+ * ```
+ *
+ * Worker module:
+ * ```ts
+ * import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
+ * import {
+ *   createProvisionVerifier,
+ *   createCloudflareWorkflowsExecutor,
+ *   createWfpWorkflowProvisioningHook,
+ *   reconcileTenantOperations,
+ *   runProvisionOperation,
+ *   type ProvisionOperationDeps,
+ *   type TenantOperationWorkflowParams,
+ * } from "@authhero/cloudflare-adapter/workflows";
+ * import { enqueueTenantOperation } from "@authhero/multi-tenancy";
+ * import {
+ *   createWfpProvisionerSteps,
+ *   createWfpTenantProvisioningHook,
+ *   CloudflareApiClient,
+ * } from "@authhero/cloudflare-adapter";
+ * import { createDispatchSyncDefaults } from "@authhero/cloudflare-adapter/wfp";
+ *
+ * // Host-owned: build every workflow dependency from the worker env. Params
+ * // carry only { operation_id, tenant_id, kind } — never secrets.
+ * function buildProvisionDeps(env: Env): ProvisionOperationDeps {
+ *   const adapters = createControlPlaneAdapters(env); // host's DB wiring
+ *   const steps = createWfpProvisionerSteps({
+ *     accountId: env.CLOUDFLARE_ACCOUNT_ID,
+ *     apiToken: env.CLOUDFLARE_API_TOKEN,
+ *     dispatchNamespace: "authhero-tenants",
+ *     controlPlaneBaseUrl: env.PUBLIC_BASE_URL,
+ *     tenantWorkerScript,
+ *     migrations,
+ *     secrets: async (tenantId) => ({ ... }),
+ *   });
+ *   return {
+ *     steps,
+ *     tenants: adapters.tenants,
+ *     stores: {
+ *       tenantOperations: adapters.tenantOperations!,
+ *       tenantOperationEvents: adapters.tenantOperationEvents!,
+ *     },
+ *     syncDefaults: createDispatchSyncDefaults({ ... }),
+ *     verify: createProvisionVerifier({ client: steps.client }),
+ *   };
+ * }
+ *
+ * export class TenantOperationWorkflow extends WorkflowEntrypoint<Env, TenantOperationWorkflowParams> {
+ *   async run(event: WorkflowEvent<TenantOperationWorkflowParams>, step: WorkflowStep) {
+ *     // CF's WorkflowStep satisfies StepRunner structurally.
+ *     await runProvisionOperation(buildProvisionDeps(this.env), event.payload, step);
+ *   }
+ * }
+ *
+ * export default {
+ *   fetch: app.fetch,
+ *   async scheduled(_controller: ScheduledController, env: Env) {
+ *     const adapters = createControlPlaneAdapters(env);
+ *     const result = await reconcileTenantOperations({
+ *       stores: {
+ *         tenantOperations: adapters.tenantOperations!,
+ *         tenantOperationEvents: adapters.tenantOperationEvents!,
+ *       },
+ *       tenants: adapters.tenants,
+ *       binding: env.TENANT_OPERATIONS_WORKFLOW,
+ *     });
+ *     console.log("reconcileTenantOperations", result);
+ *   },
+ * };
+ *
+ * // Tenant create wiring — replaces the inline provision (and any
+ * // best-effort post-create seed) with a durable enqueue:
+ * const inlineHook = createWfpTenantProvisioningHook({ provisioner, tenants, syncDefaults });
+ * const workflowHook = createWfpWorkflowProvisioningHook({
+ *   tenants: adapters.tenants,
+ *   inline: inlineHook, // upgrade/deprovision stay inline until phase 3/4
+ *   enqueueOperation: (input) =>
+ *     enqueueTenantOperation(
+ *       stores,
+ *       createCloudflareWorkflowsExecutor({ binding: env.TENANT_OPERATIONS_WORKFLOW }),
+ *       input,
+ *     ),
+ * });
+ * // databaseIsolation: {
+ * //   getAdapters,
+ * //   onProvision: workflowHook.onProvision,
+ * //   onDeprovision: workflowHook.onDeprovision,
+ * //   recordProvisionOperations: false, // the workflow owns the operation row
+ * // }
+ * ```
+ *
+ * Rollout order for existing deployments: apply the control-plane
+ * migrations first, deploy the worker with both paths available, then flip
+ * tenant-create to the workflow hook.
+ */
+export {};

package/dist/types/workflows/executor.d.ts

@@ -0,0 +1,17 @@
+import { type TenantOperationExecutor } from "@authhero/multi-tenancy";
+import type { WorkflowsBinding } from "./types";
+export interface CloudflareWorkflowsExecutorOptions {
+    binding: WorkflowsBinding;
+}
+/**
+ * `TenantOperationExecutor` backed by a Cloudflare Workflows binding
+ * (issue #1026 phase 2). Row-first contract: `enqueueTenantOperation` has
+ * already persisted the operation (with its deterministic
+ * `engine_instance_id`) before `start` is called, so an instance can never
+ * exist without a tracking row.
+ *
+ * `start` resolves as soon as the instance is created — the workflow owns
+ * every subsequent write. Creating an instance whose id already exists is
+ * treated as success (idempotent re-enqueue after a crashed caller).
+ */
+export declare function createCloudflareWorkflowsExecutor(options: CloudflareWorkflowsExecutorOptions): TenantOperationExecutor;

package/dist/types/workflows/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Durable tenant lifecycle operations on Cloudflare Workflows
+ * (issue #1026 phase 2). The control-plane database is the source of
+ * truth; the engine is the executor — the workflow writes back to the
+ * `tenant_operations` / `tenant_operation_events` log at every step
+ * boundary, and `reconcileTenantOperations` sweeps up instances that died
+ * before their terminal write.
+ *
+ * Requires the optional `@authhero/multi-tenancy` peer (like `./wfp`).
+ * Nothing here imports `cloudflare:workers`: the downstream worker
+ * provides the ~10-line `WorkflowEntrypoint` shell (see
+ * `entrypoint.example.ts`) whose `WorkflowStep` satisfies `StepRunner`
+ * structurally.
+ */
+export { runProvisionOperation, type ProvisionOperationDeps, type ProvisionStepName, } from "./provision-operation";
+export { createProvisionVerifier, TenantProvisionVerificationError, type ProvisionVerifierOptions, } from "./verify";
+export { createCloudflareWorkflowsExecutor, type CloudflareWorkflowsExecutorOptions, } from "./executor";
+export { reconcileTenantOperations, type ReconcileTenantOperationsOptions, type ReconcileTenantOperationsResult, } from "./reconcile";
+export { createWfpWorkflowProvisioningHook, type WfpWorkflowProvisioningHookOptions, } from "./enqueue-hook";
+export { TENANT_OPERATION_ENGINE, type TenantOperationWorkflowParams, type WorkflowInstanceHandle, type WorkflowInstanceStatus, type WorkflowsBinding, } from "./types";

package/dist/types/workflows/provision-operation.d.ts

@@ -0,0 +1,56 @@
+import type { TenantsDataAdapter } from "@authhero/adapter-interfaces";
+import { type StepConfig, type StepRunner, type TenantOperationStores } from "@authhero/multi-tenancy";
+import type { TenantProvisionerSteps } from "../wfp-provisioner/provisioner-steps";
+import type { TenantOperationWorkflowParams } from "./types";
+export type ProvisionStepName = "mark-running" | "create-database" | "apply-migrations" | "upload-script" | "upload-secrets" | "seed-defaults" | "verify" | "mark-ready" | "mark-failed";
+export interface ProvisionOperationDeps {
+    /** Provider-agnostic provisioner steps (all idempotent) — e.g.
+     * `createWfpProvisionerSteps` for Cloudflare WFP + D1. */
+    steps: TenantProvisionerSteps;
+    /** Control-plane tenants adapter (snapshot writes). */
+    tenants: TenantsDataAdapter;
+    /** Control-plane operation log stores. */
+    stores: TenantOperationStores;
+    /**
+     * Defaults seed (`createDispatchSyncDefaults(...)`). Runs as a retried
+     * step BEFORE `ready`; per-entity errors in the resolved result fail the
+     * step. Optional only for parity with the inline hook — WFP control
+     * planes should always set it.
+     */
+    syncDefaults?: (tenantId: string) => Promise<unknown>;
+    /**
+     * Post-seed verification (`createProvisionVerifier(...)`). Throws until
+     * the tenant database actually holds keys + the tenant row; retried with backoff so a
+     * propagation race becomes a few retries instead of a bad `ready`.
+     */
+    verify?: (databaseId: string, tenantId: string) => Promise<void>;
+    /** Same gate + default as the inline hook: `deployment_type === "wfp"`. */
+    shouldProvision?: (tenant: {
+        id: string;
+        deployment_type?: string;
+        storage_kind?: string;
+    }) => boolean;
+    logger?: Pick<Console, "warn">;
+    /** Per-step overrides of the retry/timeout defaults. */
+    stepConfig?: Partial<Record<ProvisionStepName, StepConfig>>;
+}
+/**
+ * Durable provision-as-workflow (issue #1026 phase 2): the full provision
+ * sequence — resources, migrations, script, secrets, seed, verify — as one
+ * engine step per unit, writing back to the control-plane operation log at
+ * every step boundary. The DB write happens inside the same `step.do` as
+ * the side effect, so it is durable and retried with the step; all side
+ * effects are idempotent, which makes replay after a retry or eviction
+ * safe.
+ *
+ * Terminal writes: `mark-ready` flips the tenant snapshot to `ready` and
+ * the operation to `succeeded`; any failure runs `mark-failed` (persisting
+ * whatever resource ids exist, mirroring the inline hook's failed branch)
+ * and rethrows so the engine instance ends `errored`. If even `mark-failed`
+ * dies, the operation stays `running` and the reconciler sweep copies the
+ * engine's terminal state into the DB.
+ *
+ * Runs against any `StepRunner` — Cloudflare's `WorkflowStep` satisfies it
+ * structurally, and tests use fakes.
+ */
+export declare function runProvisionOperation(deps: ProvisionOperationDeps, params: TenantOperationWorkflowParams, step: StepRunner): Promise<void>;

package/dist/types/workflows/reconcile.d.ts

@@ -0,0 +1,45 @@
+import type { TenantsDataAdapter } from "@authhero/adapter-interfaces";
+import { type TenantOperationStores } from "@authhero/multi-tenancy";
+import { type WorkflowsBinding } from "./types";
+export interface ReconcileTenantOperationsOptions {
+    stores: TenantOperationStores;
+    tenants: TenantsDataAdapter;
+    binding: WorkflowsBinding;
+    /**
+     * Only touch operations whose `updated_at` is older than this — fresh
+     * runs write at every step boundary, so a recently-updated operation is
+     * alive. Default 10 minutes.
+     */
+    minAgeMs?: number;
+    /** Max stuck operations per sweep. Default 100. */
+    limit?: number;
+    logger?: Pick<Console, "warn">;
+}
+export interface ReconcileTenantOperationsResult {
+    scanned: number;
+    markedFailed: number;
+    markedSucceeded: number;
+    stillRunning: number;
+    instanceMissing: number;
+    errors: number;
+}
+/**
+ * Sweep for operations stuck in `pending`/`running` whose engine instance
+ * died before reaching its own terminal write (issue #1026): resolve the
+ * instance (via the stored — or re-derived, it's deterministic — id), and
+ * copy terminal engine states into the control-plane DB.
+ *
+ * The engine retains completed-instance state for at most 30 days, so
+ * hosts must run this at least daily; every 15–60 minutes is recommended
+ * (wire it to the worker's `scheduled` handler). One operation's engine
+ * error never aborts the sweep.
+ *
+ * Decision table per stuck operation:
+ * - handle lookup throws (expired / never created) → `failed`
+ * - engine `errored` / `terminated` → `failed` (engine error copied)
+ * - engine `complete` but operation non-terminal (the final write raced or
+ *   was lost) → decided from the tenant snapshot, which is the source of
+ *   truth: `provisioning_state === "ready"` → `succeeded`, else `failed`
+ * - anything else → still running, left untouched
+ */
+export declare function reconcileTenantOperations(options: ReconcileTenantOperationsOptions): Promise<ReconcileTenantOperationsResult>;

package/dist/types/workflows/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Structural types for the Cloudflare Workflows engine. Deliberately NOT
+ * imported from `cloudflare:workers` / `@cloudflare/workers-types` — this
+ * package ships platform-agnostic bundles and the real runtime objects
+ * satisfy these shapes structurally (precedent: `@authhero/proxy`'s local
+ * binding types). Only the downstream worker's `WorkflowEntrypoint` shell
+ * touches `cloudflare:workers` (see `entrypoint.example.ts`).
+ */
+/**
+ * The ONLY data that crosses the enqueue boundary. Workflows persists
+ * params (and shows them in the dashboard), so never put secrets here —
+ * the workflow re-resolves everything else from its worker env.
+ */
+export interface TenantOperationWorkflowParams {
+    operation_id: string;
+    tenant_id: string;
+    /** Widened beyond "provision" in later phases (upgrade, backup, …). */
+    kind: "provision";
+}
+/**
+ * Instance status as reported by the engine. The exact value set has
+ * drifted across Cloudflare releases; the reconciler only branches on the
+ * terminal values and treats anything unrecognized as still-running.
+ */
+export interface WorkflowInstanceStatus {
+    status: "queued" | "running" | "paused" | "errored" | "terminated" | "complete" | "waiting" | "waitingForPause" | "unknown" | (string & {});
+    error?: {
+        name?: string;
+        message?: string;
+    } | string | null;
+    output?: unknown;
+}
+/** Structurally satisfied by the handles a `workflows` binding returns. */
+export interface WorkflowInstanceHandle {
+    id: string;
+    status(): Promise<WorkflowInstanceStatus>;
+}
+/**
+ * Structurally satisfied by a Workflows binding
+ * (e.g. `env.TENANT_OPERATIONS_WORKFLOW`).
+ */
+export interface WorkflowsBinding {
+    create(options: {
+        id: string;
+        params: TenantOperationWorkflowParams;
+    }): Promise<WorkflowInstanceHandle>;
+    get(id: string): Promise<WorkflowInstanceHandle>;
+}
+export declare const TENANT_OPERATION_ENGINE = "cloudflare-workflows";

package/dist/types/workflows/verify.d.ts

@@ -0,0 +1,35 @@
+import { CloudflareApiClient } from "../wfp-provisioner/cf-api";
+export interface ProvisionVerifierOptions {
+    client: CloudflareApiClient;
+    /** Minimum number of signing keys the tenant D1 must hold. Default 1. */
+    minKeys?: number;
+}
+/**
+ * Thrown when the freshly provisioned D1 fails the post-seed checks. The
+ * message is self-contained (it survives workflow step serialization) and
+ * names exactly which check failed — it ends up in
+ * `tenant_operation_events.detail` and, when retries exhaust, in
+ * `tenants.provisioning_error`.
+ */
+export declare class TenantProvisionVerificationError extends Error {
+    readonly checks: {
+        keyCount: number;
+        tenantRowCount: number;
+    };
+    constructor(message: string, checks: {
+        keyCount: number;
+        tenantRowCount: number;
+    });
+}
+/**
+ * Post-provision verification (issue #1026): assert the tenant D1 actually
+ * contains signing keys and its own tenant row before the tenant is marked
+ * `ready`. Queries D1 over the same REST path the provisioner's migrations
+ * use — this is what turns the 2026-07-02 "ready but empty D1" incident
+ * class into a retried workflow step instead of a silent success.
+ *
+ * Limitation (accepted for v1): this proves the rows landed in D1 via the
+ * REST API, not that the tenant worker's binding observes them; a worker
+ * HTTP probe can be layered on later.
+ */
+export declare function createProvisionVerifier(options: ProvisionVerifierOptions): (databaseId: string, tenantId: string) => Promise<void>;

package/dist/workflows.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./sync-defaults-errors-Htp1NWTq.js");let t=require("@authhero/multi-tenancy");var n={retries:{limit:5,delay:`5 seconds`,backoff:`exponential`},timeout:`2 minutes`},r={retries:{limit:8,delay:`10 seconds`,backoff:`exponential`},timeout:`1 minute`};function i(e){return e instanceof Error?e.message:String(e)}async function a(a,o,s){let c=(0,t.createOperationRecorder)(a.stores),l=a.shouldProvision??(e=>e.deployment_type===`wfp`),u=e=>a.stepConfig?.[e]??(e===`verify`?r:n),d=o.operation_id,f=o.tenant_id,p=await s.do(`mark-running`,u(`mark-running`),async()=>{let e=await a.tenants.get(f);if(!e||!l(e))return await c.appendEvent(d,{step:`mark-running`,outcome:`skipped`,detail:{reason:e?`tenant is not WFP-provisioned`:`tenant row missing (rolled back?)`}}),await c.markSucceeded(d),{skipped:!0,scriptName:``,databaseName:``};let t=a.steps.validate(),n=a.steps.names(f);return await c.markRunning(d,`mark-running`),await c.appendEvent(d,{step:`mark-running`,outcome:`succeeded`}),{skipped:!1,...n,...t}});if(p.skipped)return;let m={worker_script_name:p.scriptName,bundle_configuration:p.bundleConfiguration,worker_version:p.workerVersion,database_version:p.databaseVersion};try{let t=await s.do(`create-database`,u(`create-database`),async()=>{await c.setCurrentStep(d,`create-database`);let{id:e,created:t}=await a.steps.findOrCreateDatabase(p.databaseName);return await c.appendEvent(d,{step:`create-database`,outcome:`succeeded`,detail:{database_id:e,created:t}}),{databaseId:e,created:t}});if(m.d1_database_id=t.databaseId,await s.do(`apply-migrations`,u(`apply-migrations`),async()=>{await c.setCurrentStep(d,`apply-migrations`),await a.steps.applyMigrations(t.databaseId,t.created),await c.appendEvent(d,{step:`apply-migrations`,outcome:`succeeded`,detail:{database_version:p.databaseVersion}})}),await s.do(`upload-script`,u(`upload-script`),async()=>{await c.setCurrentStep(d,`upload-script`),await a.steps.uploadScript(p.scriptName,t.databaseId),await c.appendEvent(d,{step:`upload-script`,outcome:`succeeded`,detail:{worker_version:p.workerVersion}})}),await s.do(`upload-secrets`,u(`upload-secrets`),async()=>{await c.setCurrentStep(d,`upload-secrets`),await a.steps.uploadSecrets(p.scriptName,f),await c.appendEvent(d,{step:`upload-secrets`,outcome:`succeeded`})}),a.syncDefaults){let t=a.syncDefaults;await s.do(`seed-defaults`,u(`seed-defaults`),async()=>{await c.setCurrentStep(d,`seed-defaults`);let n=e.t(await t(f));if(n.length>0)throw Error(`sync-defaults seed reported ${n.length} error(s): ${n.join(`; `)}`);await c.appendEvent(d,{step:`seed-defaults`,outcome:`succeeded`})})}if(a.verify){let e=a.verify;await s.do(`verify`,u(`verify`),async()=>{await c.setCurrentStep(d,`verify`),await e(t.databaseId,f),await c.appendEvent(d,{step:`verify`,outcome:`succeeded`})})}await s.do(`mark-ready`,u(`mark-ready`),async()=>{await c.setCurrentStep(d,`mark-ready`),await a.tenants.update(f,{...m,provisioning_state:`ready`,provisioning_error:void 0,provisioning_state_changed_at:new Date().toISOString()}),await c.appendEvent(d,{step:`mark-ready`,outcome:`succeeded`}),await c.markSucceeded(d)})}catch(e){throw await s.do(`mark-failed`,u(`mark-failed`),async()=>{let t=i(e);try{await a.tenants.update(f,{...m,provisioning_state:`failed`,provisioning_error:t.slice(0,2048),provisioning_state_changed_at:new Date().toISOString()})}catch(e){a.logger?.warn(`Failed to write provisioning_state="failed" for tenant ${f}:`,e)}await c.appendEvent(d,{step:`mark-failed`,outcome:`failed`,detail:{message:t}}),await c.markFailed(d,e)}),e}}var o=class extends Error{checks;constructor(e,t){super(e),this.name=`TenantProvisionVerificationError`,this.checks=t}};function s(e,t){for(let n of e)for(let e of n.results??[])if(!(!e||typeof e!=`object`)){for(let[n,r]of Object.entries(e))if(n===t){if(typeof r==`number`)return r;if(typeof r==`string`&&r!==``&&!isNaN(Number(r)))return Number(r)}}return 0}function c(t){let n=t.minKeys??1;return async(r,i)=>{let a=await t.client.execD1(r,`SELECT (SELECT COUNT(*) FROM keys) AS key_count, (SELECT COUNT(*) FROM tenants WHERE id = '${e.r(i)}') AS tenant_count;`),c=s(a,`key_count`),l=s(a,`tenant_count`),u=[];if(c<n&&u.push(`expected at least ${n} signing key(s) in "keys", found ${c}`),l<1&&u.push(`tenant row "${i}" missing from "tenants"`),u.length>0)throw new o(`Tenant D1 verification failed for "${i}": ${u.join(`; `)}`,{keyCount:c,tenantRowCount:l})}}function l(e){let t=e instanceof Error?e.message:String(e??``);return/already exists|already been created|duplicate/i.test(t)}function u(e){return{engine:`cloudflare-workflows`,async start(n){if(n.kind!==`provision`)throw Error(`The Cloudflare Workflows executor does not support "${n.kind}" operations yet (phase 2 covers provision only)`);if(!n.tenant_id)throw Error(`provision operations require a tenant_id`);let r=n.engine_instance_id??(0,t.buildEngineInstanceId)(n);try{await e.binding.create({id:r,params:{operation_id:n.id,tenant_id:n.tenant_id,kind:n.kind}})}catch(e){if(!l(e))throw e}}}}var d=`cloudflare-workflows`;async function f(e){let{stores:n,tenants:r,binding:i}=e,a=(0,t.createOperationRecorder)(n),o=e.minAgeMs??600*1e3,s=e.limit??100,c=new Date(Date.now()-o).toISOString(),{operations:l}=await n.tenantOperations.list({status:[`pending`,`running`],engine:d,updated_before:c,per_page:s}),u={scanned:l.length,markedFailed:0,markedSucceeded:0,stillRunning:0,instanceMissing:0,errors:0};for(let t of l)try{await p(t)}catch(n){u.errors++,e.logger?.warn(`Failed to reconcile tenant operation ${t.id}:`,n)}return u;async function f(e,t){await a.appendEvent(e.id,{step:e.current_step??`reconcile`,outcome:`reconciled`,detail:{resolution:`failed`,reason:t}}),await a.markFailed(e.id,t),e.kind===`provision`&&e.tenant_id&&(await r.get(e.tenant_id))?.provisioning_state===`pending`&&await r.update(e.tenant_id,{provisioning_state:`failed`,provisioning_error:t.slice(0,2048),provisioning_state_changed_at:new Date().toISOString()})}async function p(e){let o=await n.tenantOperations.get(e.id);if(!o||(0,t.isTerminalStatus)(o.status))return;let s=o.engine_instance_id??(0,t.buildEngineInstanceId)(o),c;try{c=await i.get(s)}catch{u.instanceMissing++,u.markedFailed++,await f(o,`engine instance "${s}" not found (expired past retention or never started)`);return}let l=await c.status();if(l.status===`errored`||l.status===`terminated`){let e=typeof l.error==`string`?l.error:l.error?.message??`engine reported ${l.status}`;u.markedFailed++,await f(o,e);return}if(l.status===`complete`){(o.tenant_id?await r.get(o.tenant_id):null)?.provisioning_state===`ready`?(u.markedSucceeded++,await a.appendEvent(o.id,{step:o.current_step??`reconcile`,outcome:`reconciled`,detail:{resolution:`succeeded`}}),await a.markSucceeded(o.id)):(u.markedFailed++,await f(o,`engine instance completed but the operation was never finalized and the tenant is not ready`));return}u.stillRunning++}}function p(e){let t=e.shouldProvision??(e=>e.deployment_type===`wfp`);return{async onProvision(n,r){let i=await e.tenants.get(n);i&&t(i)&&await e.enqueueOperation({kind:`provision`,tenant_id:n})},async onUpgrade(t,n){await e.inline.onUpgrade(t,n)},async onDeprovision(t){await e.inline.onDeprovision(t)}}}exports.TENANT_OPERATION_ENGINE=d,exports.TenantProvisionVerificationError=o,exports.createCloudflareWorkflowsExecutor=u,exports.createProvisionVerifier=c,exports.createWfpWorkflowProvisioningHook=p,exports.reconcileTenantOperations=f,exports.runProvisionOperation=a;