authhero 8.23.1 → 8.24.0

package/dist/types/adapters/control-plane-custom-domains.d.ts

@@ -0,0 +1,35 @@
+import { CustomDomainsAdapter } from "@authhero/adapter-interfaces";
+import { ControlPlaneClient } from "../helpers/control-plane-client";
+export declare const CONTROL_PLANE_CUSTOM_DOMAINS_PATH = "/api/v2/proxy/control-plane/custom-domains";
+export interface ControlPlaneCustomDomainsOptions {
+    /** Authed transport to the control plane. */
+    client: ControlPlaneClient;
+    /**
+     * Local read-cache for custom domains — normally the shard's own database
+     * adapter (`database.customDomains`). The control plane owns the row; this
+     * mirror exists so `getByDomain` (tenant resolution, a hot path) and `list`
+     * don't need a network hop.
+     */
+    mirror: CustomDomainsAdapter;
+    /** Override the control-plane resource path (tests, custom mounts). */
+    basePath?: string;
+}
+/**
+ * A `CustomDomainsAdapter` for a tenant shard that cannot register hostnames
+ * itself: a CF-for-SaaS custom hostname is an account-global resource in one
+ * shared zone, and only the control plane holds the account credentials — and
+ * only something above all shards can see that `login.acme.com` is already
+ * claimed by another tenant.
+ *
+ * So the control plane is authoritative: writes go there synchronously and the
+ * result is mirrored into the shard's own database as a read cache. On a
+ * conflict nothing is written locally, which is what prevents the
+ * half-provisioned, unroutable row this replaces.
+ *
+ * Reads trust the mirror once a domain is `ready`. A `pending` domain flips to
+ * `ready` on Cloudflare's timeline (after the customer adds the DV record) and
+ * that transition happens at the control plane, so a non-ready row is
+ * refreshed from upstream on read. `getByDomain` always reads the mirror — it
+ * is on the tenant-resolution path and must not take a network hop.
+ */
+export declare function createControlPlaneCustomDomainsAdapter(options: ControlPlaneCustomDomainsOptions): CustomDomainsAdapter;

package/dist/types/authentication-flows/passwordless.d.ts

@@ -367,7 +367,7 @@ export declare function passwordlessGrantUser(ctx: Context<{
                             active?: boolean | undefined;
                         } | undefined;
                         signup?: {
-                            status?: "required" | "optional" | "disabled" | undefined;
+                            status?: "optional" | "required" | "disabled" | undefined;
                             verification?: {
                                 active?: boolean | undefined;
                             } | undefined;
@@ -384,7 +384,7 @@ export declare function passwordlessGrantUser(ctx: Context<{
                             active?: boolean | undefined;
                         } | undefined;
                         signup?: {
-                            status?: "required" | "optional" | "disabled" | undefined;
+                            status?: "optional" | "required" | "disabled" | undefined;
                         } | undefined;
                         validation?: {
                             max_length?: number | undefined;
@@ -401,7 +401,7 @@ export declare function passwordlessGrantUser(ctx: Context<{
                             active?: boolean | undefined;
                         } | undefined;
                         signup?: {
-                            status?: "required" | "optional" | "disabled" | undefined;
+                            status?: "optional" | "required" | "disabled" | undefined;
                         } | undefined;
                     } | undefined;
                 } | undefined;
@@ -549,8 +549,8 @@ export declare function passwordlessGrantUser(ctx: Context<{
         } | undefined;
         authenticated_at?: string | undefined;
     };
-    connectionType: "email" | "username" | "sms";
-    authConnection: "email" | "username" | "sms";
+    connectionType: "sms" | "email" | "username";
+    authConnection: "sms" | "email" | "username";
     session_id: string | undefined;
     authParams: {
         client_id: string;

package/dist/types/helpers/control-plane-client.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Mints a bearer token for a tenant against the control plane. On a tenant
+ * shard this is `createServiceTokenCore` bound to the shard's own tenants/keys
+ * adapters — the control plane verifies it against the shard's published JWKS,
+ * so no shared client secret is involved.
+ */
+export type GetControlPlaneToken = (tenantId: string, scope: string) => Promise<string>;
+export interface ControlPlaneClientOptions {
+    /** Base URL of the control-plane authhero instance, no trailing slash required. */
+    baseUrl: string;
+    getServiceToken: GetControlPlaneToken;
+    /** Per-request timeout (default: 5s). */
+    timeoutMs?: number;
+    /** Refresh a cached token this many seconds before it expires (default: 60). */
+    tokenRefreshSkewSeconds?: number;
+    /** Override for tests, or to route over a Cloudflare service binding. */
+    fetchImpl?: typeof fetch;
+}
+export interface ControlPlaneRequest {
+    tenantId: string;
+    scope: string;
+    method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+    /** Path below the base URL, e.g. `/api/v2/proxy/control-plane/custom-domains`. */
+    path: string;
+    body?: unknown;
+}
+export interface ControlPlaneResponse {
+    status: number;
+    /** Parsed JSON body, or null for empty/non-JSON responses. */
+    data: unknown;
+}
+export interface ControlPlaneClient {
+    /**
+     * Perform an authed request. Returns the status and parsed body for ANY HTTP
+     * response — including 4xx/5xx — so callers can map status to domain
+     * semantics (409 → conflict, 404 → null). Throws only when the request never
+     * produced a response (network error, timeout, token minting failure).
+     */
+    request(req: ControlPlaneRequest): Promise<ControlPlaneResponse>;
+}
+/**
+ * Authed transport to the control plane with an in-memory, per-(tenant, scope)
+ * token cache and single-flight minting. Shared by every control-plane-backed
+ * adapter so the token handling exists once.
+ */
+export declare function createControlPlaneClient(options: ControlPlaneClientOptions): ControlPlaneClient;

package/dist/types/helpers/control-plane-sync-events.d.ts

@@ -1,8 +1,16 @@
 import { Context } from "hono";
-import { CustomDomain, ProxyRoute } from "@authhero/adapter-interfaces";
+import { ProxyRoute } from "@authhero/adapter-interfaces";
 import { Bindings, Variables } from "../types";
 export declare const CONTROL_PLANE_SYNC_EVENT_PREFIX = "controlplane.sync.";
-export type SyncEntity = "custom_domain" | "proxy_route";
+/**
+ * Only `proxy_route` replicates upward. Custom domains used to sync the same
+ * way, which is exactly what left them half-provisioned: the row reached the
+ * control plane but nothing ever registered the hostname in Cloudflare. They
+ * are now written through the control plane synchronously
+ * (`createControlPlaneCustomDomainsAdapter`), which owns the row and performs
+ * the account-level side effect.
+ */
+export type SyncEntity = "proxy_route";
 export type SyncOp = "created" | "updated" | "deleted";
 /**
  * Wire shape posted from the tenant shard to the control plane. The destination
@@ -11,34 +19,10 @@ export type SyncOp = "created" | "updated" | "deleted";
  * batched-delivery destination.
  */
 export type SyncEvent = {
-    event_id: string;
-    tenant_id: string;
-    entity: "custom_domain";
-    op: "created" | "updated";
-    aggregate_id: string;
-    payload: CustomDomain;
-    occurred_at: string;
-} | {
-    event_id: string;
-    tenant_id: string;
-    entity: "custom_domain";
-    op: "deleted";
-    aggregate_id: string;
-    payload: CustomDomain;
-    occurred_at: string;
-} | {
     event_id: string;
     tenant_id: string;
     entity: "proxy_route";
-    op: "created" | "updated";
-    aggregate_id: string;
-    payload: ProxyRoute;
-    occurred_at: string;
-} | {
-    event_id: string;
-    tenant_id: string;
-    entity: "proxy_route";
-    op: "deleted";
+    op: SyncOp;
     aggregate_id: string;
     payload: ProxyRoute;
     occurred_at: string;
@@ -48,7 +32,7 @@ interface EnqueueArgs {
     entity: SyncEntity;
     op: SyncOp;
     aggregateId: string;
-    payload: CustomDomain | ProxyRoute;
+    payload: ProxyRoute;
 }
 /**
  * Enqueue a `controlplane.sync.*` event to the outbox so the