authhero 9.9.1 → 9.11.0

package/dist/types/authentication-flows/authorization-code.d.ts

@@ -3,6 +3,7 @@ import { z } from "@hono/zod-openapi";
 import { Bindings, Variables } from "../types";
 import { TokenResponse } from "@authhero/adapter-interfaces";
 import { GrantFlowUserResult } from "src/types/GrantFlowResult";
+import { EnrichedClient } from "../helpers/client";
 export declare const authorizationCodeGrantParamsSchema: z.ZodObject<{
     grant_type: z.ZodLiteral<"authorization_code">;
     client_id: z.ZodString;
@@ -16,7 +17,7 @@ export type AuthorizationCodeGrantTypeParams = z.infer<typeof authorizationCodeG
 export declare function authorizationCodeGrantUser(ctx: Context<{
     Bindings: Bindings;
     Variables: Variables;
-}>, params: AuthorizationCodeGrantTypeParams): Promise<GrantFlowUserResult>;
+}>, params: AuthorizationCodeGrantTypeParams, preloadedClient?: EnrichedClient): Promise<GrantFlowUserResult>;
 export declare function authorizationCodeGrant(ctx: Context<{
     Bindings: Bindings;
     Variables: Variables;

package/dist/types/authentication-flows/client-credentials.d.ts

@@ -2,6 +2,7 @@ import { Context } from "hono";
 import { z } from "@hono/zod-openapi";
 import { Bindings, Variables } from "../types";
 import { GrantFlowResult } from "../types/GrantFlowResult";
+import { EnrichedClient } from "../helpers/client";
 export declare const clientCredentialGrantParamsSchema: z.ZodObject<{
     grant_type: z.ZodLiteral<"client_credentials">;
     scope: z.ZodOptional<z.ZodString>;
@@ -13,4 +14,4 @@ export declare const clientCredentialGrantParamsSchema: z.ZodObject<{
 export declare function clientCredentialsGrant(ctx: Context<{
     Bindings: Bindings;
     Variables: Variables;
-}>, params: z.infer<typeof clientCredentialGrantParamsSchema>): Promise<GrantFlowResult>;
+}>, params: z.infer<typeof clientCredentialGrantParamsSchema>, preloadedClient?: EnrichedClient): Promise<GrantFlowResult>;

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

@@ -1,6 +1,7 @@
 import { Context } from "hono";
 import { z } from "@hono/zod-openapi";
 import { Bindings, Variables } from "../types";
+import { EnrichedClient } from "../helpers/client";
 import { GrantFlowUserResult } from "../types/GrantFlowResult";
 export declare const passwordlessGrantParamsSchema: z.ZodObject<{
     client_id: z.ZodString;
@@ -45,7 +46,7 @@ export declare const passwordlessGrantParamsSchema: z.ZodObject<{
 export declare function passwordlessGrantUser(ctx: Context<{
     Bindings: Bindings;
     Variables: Variables;
-}>, { client_id, username, otp, scope, audience, authParams, enforceIpCheck, }: z.input<typeof passwordlessGrantParamsSchema>): Promise<{
+}>, { client_id, username, otp, scope, audience, authParams, enforceIpCheck, }: z.input<typeof passwordlessGrantParamsSchema>, preloadedClient?: EnrichedClient): Promise<{
     user: {
         connection: string;
         email_verified: boolean;
@@ -474,7 +475,7 @@ export declare function passwordlessGrantUser(ctx: Context<{
         custom_login_page_preview?: string | undefined;
         form_template?: string | undefined;
         addons?: Record<string, any> | undefined;
-        token_endpoint_auth_method?: "none" | "client_secret_post" | "client_secret_basic" | "client_secret_jwt" | "private_key_jwt" | undefined;
+        token_endpoint_auth_method?: "client_secret_post" | "client_secret_basic" | "none" | "client_secret_jwt" | "private_key_jwt" | undefined;
         client_metadata?: Record<string, string> | undefined;
         hide_sign_up_disabled_error?: boolean | undefined;
         mobile?: Record<string, any> | undefined;
@@ -557,8 +558,8 @@ export declare function passwordlessGrantUser(ctx: Context<{
         } | undefined;
         authenticated_at?: string | undefined;
     };
-    connectionType: "username" | "email" | "sms";
-    authConnection: "username" | "email" | "sms";
+    connectionType: "email" | "username" | "sms";
+    authConnection: "email" | "username" | "sms";
     session_id: string | undefined;
     authParams: {
         audience?: string | undefined;
@@ -612,7 +613,7 @@ export declare function passwordlessGrantUser(ctx: Context<{
 export declare function passwordlessOtpGrant(ctx: Context<{
     Bindings: Bindings;
     Variables: Variables;
-}>, params: z.input<typeof passwordlessGrantParamsSchema>): Promise<GrantFlowUserResult>;
+}>, params: z.input<typeof passwordlessGrantParamsSchema>, preloadedClient?: EnrichedClient): Promise<GrantFlowUserResult>;
 export declare function passwordlessGrant(ctx: Context<{
     Bindings: Bindings;
     Variables: Variables;

package/dist/types/authentication-flows/refresh-token.d.ts

@@ -1,6 +1,7 @@
 import { Context } from "hono";
 import { Bindings, Variables, GrantFlowUserResult } from "../types";
 import { z } from "@hono/zod-openapi";
+import { EnrichedClient } from "../helpers/client";
 export declare const refreshTokenParamsSchema: z.ZodObject<{
     grant_type: z.ZodLiteral<"refresh_token">;
     client_id: z.ZodString;
@@ -12,4 +13,4 @@ export declare const refreshTokenParamsSchema: z.ZodObject<{
 export declare function refreshTokenGrant(ctx: Context<{
     Bindings: Bindings;
     Variables: Variables;
-}>, params: z.infer<typeof refreshTokenParamsSchema>): Promise<GrantFlowUserResult>;
+}>, params: z.infer<typeof refreshTokenParamsSchema>, preloadedClient?: EnrichedClient): Promise<GrantFlowUserResult>;

package/dist/types/authentication-flows/token-exchange.d.ts

@@ -1,6 +1,7 @@
 import { Context } from "hono";
 import { z } from "@hono/zod-openapi";
 import { Bindings, Variables, GrantFlowUserResult } from "../types";
+import { EnrichedClient } from "../helpers/client";
 export declare const TOKEN_EXCHANGE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange";
 export declare const tokenExchangeParamsSchema: z.ZodObject<{
     grant_type: z.ZodLiteral<"urn:ietf:params:oauth:grant-type:token-exchange">;
@@ -16,4 +17,4 @@ export type TokenExchangeParams = z.infer<typeof tokenExchangeParamsSchema>;
 export declare function tokenExchangeGrant(ctx: Context<{
     Bindings: Bindings;
     Variables: Variables;
-}>, params: TokenExchangeParams): Promise<GrantFlowUserResult>;
+}>, params: TokenExchangeParams, preloadedClient?: EnrichedClient): Promise<GrantFlowUserResult>;

package/dist/types/helpers/client-assertion-replay.d.ts

@@ -0,0 +1,21 @@
+import { Context } from "hono";
+import { Bindings, Variables } from "../types";
+export interface ConsumeClientAssertionJtiParams {
+    clientId: string;
+    /** The assertion's `jti`. When absent there is nothing to spend. */
+    jti?: string;
+    /** The assertion's `exp`, in seconds — when the marker becomes collectable. */
+    exp: number;
+}
+/**
+ * Spend a client assertion's `jti`.
+ *
+ * @returns false when this assertion has already been presented (the caller
+ *   must reject it as `invalid_client`), true otherwise. An assertion carrying
+ *   no `jti` cannot be tracked, so it returns true — its replay window is
+ *   bounded only by the assertion lifetime cap.
+ */
+export declare function consumeClientAssertionJti(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, tenantId: string, params: ConsumeClientAssertionJtiParams): Promise<boolean>;

package/dist/types/helpers/client-assertion.d.ts

@@ -1,5 +1,12 @@
 import { LoadClientKeysOptions, ClientWithKeys } from "./client-keys";
 declare const ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+/**
+ * Default upper bound on a client assertion's lifetime. RFC 7523 gives no
+ * limit, so without one a client can mint an assertion valid for a year and a
+ * captured assertion stays usable for that whole window. 300s matches the
+ * usual guidance for a single-use token presented directly to the endpoint.
+ */
+declare const DEFAULT_MAX_LIFETIME_SECONDS = 300;
 export type ClientAssertionMethod = "private_key_jwt" | "client_secret_jwt";
 export declare class ClientAssertionError extends Error {
     code: "invalid_client" | "invalid_request" | "unsupported_alg" | "missing_keys";
@@ -18,6 +25,14 @@ export interface VerifyClientAssertionOptions extends LoadClientKeysOptions {
     acceptedAudiences: string[];
     /** Clock-skew leeway in seconds. Defaults to 30. */
     leewaySeconds?: number;
+    /**
+     * Maximum accepted assertion lifetime in seconds. Rejects an assertion whose
+     * `exp - iat` exceeds this, and caps the absolute `exp` at `now + max` so an
+     * assertion that omits `iat` cannot sidestep the bound. Defaults to
+     * DEFAULT_MAX_LIFETIME_SECONDS (300) — the window a captured assertion stays
+     * replayable in is bounded by this, so keep it short.
+     */
+    maxLifetimeSeconds?: number;
     /** Override Date.now() for tests. */
     now?: () => number;
 }
@@ -26,8 +41,15 @@ export interface VerifiedClientAssertion {
     clientId: string;
     /** Which authentication method was actually used. */
     method: ClientAssertionMethod;
-    /** Optional jti claim — useful if callers want to enforce replay protection. */
+    /**
+     * The `jti` claim, when present. `consumeClientAssertionJti`
+     * (helpers/client-assertion-replay.ts) spends it so an assertion cannot be
+     * presented twice; the token endpoint calls that after this verifier
+     * returns.
+     */
     jti?: string;
+    /** The `exp` claim, in seconds. Bounds how long the `jti` must be remembered. */
+    exp: number;
     /** The full verified payload, in case callers need other claims. */
     payload: Record<string, unknown>;
 }
@@ -46,4 +68,4 @@ export interface VerifiedClientAssertion {
  *   any of the iss/sub/aud/exp checks.
  */
 export declare function verifyClientAssertion(assertion: string, client: ClientAssertionClient, opts: VerifyClientAssertionOptions): Promise<VerifiedClientAssertion>;
-export { ASSERTION_TYPE as CLIENT_ASSERTION_TYPE };
+export { ASSERTION_TYPE as CLIENT_ASSERTION_TYPE, DEFAULT_MAX_LIFETIME_SECONDS as CLIENT_ASSERTION_DEFAULT_MAX_LIFETIME_SECONDS, };

package/dist/types/helpers/dcr/metadata-mapping.d.ts

@@ -23,9 +23,9 @@ export declare const dcrRequestSchema: z.ZodObject<{
     grant_types: z.ZodOptional<z.ZodArray<z.ZodString>>;
     response_types: z.ZodOptional<z.ZodArray<z.ZodString>>;
     token_endpoint_auth_method: z.ZodOptional<z.ZodEnum<{
-        none: "none";
         client_secret_post: "client_secret_post";
         client_secret_basic: "client_secret_basic";
+        none: "none";
         client_secret_jwt: "client_secret_jwt";
         private_key_jwt: "private_key_jwt";
     }>>;

package/dist/types/helpers/default-destinations.d.ts

@@ -1,7 +1,7 @@
 import { CodeExecutor, DataAdapters } from "@authhero/adapter-interfaces";
 import { EventDestination } from "./outbox-relay";
 import { type GetServiceToken } from "./outbox-destinations/webhooks";
-import type { WebhookInvoker } from "../types/AuthHeroConfig";
+import type { OutboxPipelineConfig, WebhookInvoker } from "../types/AuthHeroConfig";
 export interface CreateDefaultDestinationsConfig {
     /**
      * Data adapter — the `logs`, `hooks`, `users`, and `logStreams` adapters are
@@ -47,6 +47,12 @@ export interface CreateDefaultDestinationsConfig {
      * failed per-request delivery would be silently skipped on retry.
      */
     codeExecutor?: CodeExecutor;
+    /**
+     * Same shape as `init({ outbox: { pipeline } })`. When set, cron-drained
+     * events are also archived to the Cloudflare Pipelines stream, matching the
+     * per-request destination list. Omit to leave the archive out entirely.
+     */
+    pipeline?: OutboxPipelineConfig;
 }
 /**
  * Build the same array of outbox destinations that authhero's per-request

package/dist/types/helpers/outbox-destinations/index.d.ts

@@ -1,2 +1,3 @@
 export { LogsDestination } from "./logs";
 export { LogStreamDestination } from "./log-streams";
+export { PipelineDestination } from "./pipeline";

package/dist/types/helpers/outbox-destinations/pipeline.d.ts

@@ -0,0 +1,63 @@
+import { AuditEvent, AuditCategory } from "@authhero/adapter-interfaces";
+import { EventDestination } from "../outbox-relay";
+/**
+ * One row of the archive table. The promoted columns are the query and
+ * erasure keys (`actor_id` / `target_id`); `event` carries the untouched
+ * `AuditEvent` so nothing is lost and the promoted set can grow later
+ * without a backfill.
+ *
+ * `actor_id` is emitted as `null` rather than omitted when the actor is
+ * anonymous, so every record has the same key set — Pipelines stream
+ * schemas are fixed once created.
+ */
+export interface PipelineRecord {
+    id: string;
+    timestamp: string;
+    tenant_id: string;
+    event_type: string;
+    log_type: string;
+    category: AuditCategory;
+    actor_id: string | null;
+    target_type: string;
+    target_id: string;
+    event: AuditEvent;
+}
+export interface PipelineDestinationOptions {
+    /** Stream HTTP ingest endpoint, e.g. `https://<stream-id>.ingest.cloudflare.com`. */
+    endpoint: string;
+    /** Stream ingest token, sent as `Authorization: Bearer`. */
+    token: string;
+    /** Per-request timeout (default: 10s). */
+    timeoutMs?: number;
+    /** Override for tests. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Archives audit events to a Cloudflare Pipelines stream, which lands them in
+ * R2 as an Iceberg table. See `apps/docs/architecture/audit-archive.md`.
+ *
+ * HTTP ingest is used rather than the Worker binding so the destination works
+ * in every deployment (Node included) and stays symmetric with the
+ * log-streams destination.
+ *
+ * Duplicates are expected and by design: the relay retries per event, not per
+ * destination, so a failure in a later destination re-delivers this one, and
+ * the Iceberg sink is append-only. Consumers dedup on `id` at query time.
+ */
+export declare class PipelineDestination implements EventDestination {
+    name: string;
+    private endpoint;
+    private token;
+    private timeoutMs;
+    private fetchImpl;
+    constructor(options: PipelineDestinationOptions);
+    /**
+     * Archives the audit trail, not the delivery plumbing: `hook.*` and
+     * `controlplane.sync.*` are instructions to other destinations rather than
+     * records of something a tenant did. Same filter as the log-streams
+     * destination.
+     */
+    accepts(event: AuditEvent): boolean;
+    transform(event: AuditEvent): PipelineRecord;
+    deliver(records: PipelineRecord[]): Promise<void>;
+}

package/dist/types/helpers/outbox-relay.d.ts

@@ -1,4 +1,5 @@
 import { OutboxAdapter, AuditEvent } from "@authhero/adapter-interfaces";
+import type { OutboxMetricsSink } from "../types/OutboxMetrics";
 /**
  * Interface for outbox event destinations.
  * Each destination transforms audit events into its own format and delivers them.
@@ -21,6 +22,7 @@ export interface EventDestination {
  */
 export declare function processOutboxEvents(outbox: OutboxAdapter, ids: string[], destinations: EventDestination[], options?: {
     maxRetries?: number;
+    metrics?: OutboxMetricsSink;
 }): Promise<void>;
 /**
  * Drain unprocessed events from the outbox and deliver to all destinations.
@@ -31,4 +33,5 @@ export declare function drainOutbox(outbox: OutboxAdapter, destinations: EventDe
     batchSize?: number;
     maxRetries?: number;
     retentionDays?: number;
+    metrics?: OutboxMetricsSink;
 }): Promise<void>;

package/dist/types/helpers/reserved-claims.d.ts

@@ -0,0 +1,64 @@
+import { Context } from "hono";
+import { Bindings, Variables } from "../types";
+/** RFC 9068 §2.2 + AuthHero-owned access-token claims. */
+export declare const ACCESS_TOKEN_RESERVED_CLAIMS: readonly ["iss", "sub", "aud", "exp", "nbf", "iat", "jti", "client_id", "azp", "scope", "auth_time", "acr", "amr", "act", "sid", "permissions", "tenant_id", "org_id", "org_name", "requested_userinfo_claims", "gty"];
+/** OIDC Core ID-token claims: the access-token set plus the ID-token-only ones. */
+export declare const ID_TOKEN_RESERVED_CLAIMS: readonly ["iss", "sub", "aud", "exp", "nbf", "iat", "jti", "client_id", "azp", "scope", "auth_time", "acr", "amr", "act", "sid", "permissions", "tenant_id", "org_id", "org_name", "requested_userinfo_claims", "gty", "nonce", "at_hash", "c_hash", "s_hash"];
+/**
+ * /userinfo response. The identity set only — the response body is otherwise
+ * made up of user profile claims, which hooks are expected to extend.
+ */
+export declare const USERINFO_RESERVED_CLAIMS: readonly ["iss", "sub", "aud", "exp", "nbf", "iat", "jti"];
+/**
+ * Internal `auth-service` mints. Same set as an access token except `azp`:
+ * trusted internal hook code overrides it to attribute the call to a
+ * vendor/tenant for downstream APIs while `sub` stays `auth-service`.
+ * Client-bound mints keep `azp` locked (see below).
+ */
+export declare const SERVICE_TOKEN_RESERVED_CLAIMS: ("client_id" | "scope" | "sid" | "tenant_id" | "sub" | "org_name" | "permissions" | "iat" | "org_id" | "exp" | "iss" | "aud" | "auth_time" | "acr" | "amr" | "nbf" | "jti" | "act" | "requested_userinfo_claims" | "gty")[];
+/** Client-bound mints: `azp` must stay the registered client id. */
+export declare const CLIENT_SERVICE_TOKEN_RESERVED_CLAIMS: ("client_id" | "scope" | "sid" | "tenant_id" | "sub" | "org_name" | "permissions" | "iat" | "org_id" | "exp" | "iss" | "aud" | "auth_time" | "acr" | "amr" | "azp" | "nbf" | "jti" | "act" | "requested_userinfo_claims" | "gty")[];
+export type AccessTokenReservedClaim = (typeof ACCESS_TOKEN_RESERVED_CLAIMS)[number];
+export type IdTokenReservedClaim = (typeof ID_TOKEN_RESERVED_CLAIMS)[number];
+/**
+ * The server-owned half of an access-token payload. Typing the payload literal
+ * as this makes TypeScript's excess-property check reject any claim name that
+ * isn't in `ACCESS_TOKEN_RESERVED_CLAIMS`, so a new server-owned claim cannot
+ * be added to the mint without also being reserved.
+ */
+export type ServerOwnedAccessTokenClaims = Partial<Record<AccessTokenReservedClaim, unknown>>;
+/** As `ServerOwnedAccessTokenClaims`, for the ID token. */
+export type ServerOwnedIdTokenClaims = Partial<Record<IdTokenReservedClaim, unknown>>;
+/** Which payload a custom claim is being written to. */
+export type ClaimPayloadKind = "access_token" | "id_token" | "userinfo" | "service_token" | "client_service_token";
+export declare function isReservedClaim(claim: string, kind: ClaimPayloadKind): boolean;
+export interface ApplyCustomClaimOptions {
+    /** Which payload is being written to — selects the reserved set. */
+    kind: ClaimPayloadKind;
+    /**
+     * Who is writing. Used in the warning so an operator can tell which hook
+     * dropped a claim (e.g. `onExecuteCredentialsExchange`,
+     * `template-hook:add-roles`, `createServiceToken`).
+     */
+    source: string;
+    /** Request context, when there is one — the warning goes to the tenant log. */
+    ctx?: Context<{
+        Bindings: Bindings;
+        Variables: Variables;
+    }>;
+    /** Tenant to log against. Defaults to `ctx.var.tenant_id`. */
+    tenantId?: string;
+}
+/**
+ * Write a caller-supplied claim onto a payload unless the authorization server
+ * owns that claim name.
+ *
+ * @returns true when the claim was written, false when it was dropped.
+ */
+export declare function applyCustomClaim(payload: Record<string, unknown>, claim: string, value: unknown, options: ApplyCustomClaimOptions): boolean;
+/**
+ * Bulk variant of `applyCustomClaim`. Returns a new object holding only the
+ * claims that are safe to merge, so callers can keep spreading them into a
+ * payload literal.
+ */
+export declare function applyCustomClaims(claims: Record<string, unknown> | undefined, options: ApplyCustomClaimOptions): Record<string, unknown> | undefined;

package/dist/types/helpers/run-outbox-relay.d.ts

@@ -1,5 +1,6 @@
 import { CodeExecutor, DataAdapters } from "@authhero/adapter-interfaces";
 import type { WebhookInvoker } from "../types/AuthHeroConfig";
+import type { OutboxMetricsSink } from "../types/OutboxMetrics";
 export interface RunOutboxRelayConfig {
     /** Same `DataAdapters` passed to `init()`. Must include `outbox` to drain. */
     dataAdapter: DataAdapters;
@@ -31,6 +32,13 @@ export interface RunOutboxRelayConfig {
      * silently skipped.
      */
     codeExecutor?: CodeExecutor;
+    /**
+     * Optional metrics sink — same shape as `init({ outbox: { metrics } })`.
+     * Receives `outbox_events_processed_total`,
+     * `outbox_events_dead_lettered_total` and `outbox_retry_delay_seconds` for
+     * the events this cron drain handles, tagged `source: "cron"`.
+     */
+    metrics?: OutboxMetricsSink;
 }
 /**
  * One-call outbox relay for cron / scheduled handlers.

package/dist/types/helpers/run-retention.d.ts

@@ -8,6 +8,11 @@ export interface RunRetentionConfig {
     outboxRetentionDays?: number;
     /** Days of action execution history to keep. Default 30. */
     actionExecutionsRetentionDays?: number;
+    /**
+     * Hours to keep finished bulk user-import jobs and their staged rows.
+     * Default 24, matching Auth0's job-data retention.
+     */
+    usersImportRetentionHours?: number;
     /**
      * Scope the session sweep to a single tenant. Codes and outbox events are
      * always swept globally — an expired row is dead regardless of who owns it.

package/dist/types/helpers/users-import/map.d.ts

@@ -0,0 +1,128 @@
+import type { PasswordInsert, UserInsert } from "@authhero/adapter-interfaces";
+import { type UserImportEntry } from "../../types/auth0/UserImport";
+/**
+ * Machine-readable per-row failure reasons, surfaced by the Auth0-compatible
+ * `GET /api/v2/jobs/{id}/errors` endpoint. Stable strings — clients branch on
+ * them, so treat these as API surface.
+ */
+export declare const IMPORT_ERROR_CODES: {
+    /** The entry did not match the import-file schema. */
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    /** A well-formed hash in an algorithm AuthHero cannot verify. */
+    readonly UNSUPPORTED_HASH_ALGORITHM: "UNSUPPORTED_HASH_ALGORITHM";
+    /** bcrypt, but a variant or encoding that would never verify. */
+    readonly UNSUPPORTED_HASH_FORMAT: "UNSUPPORTED_HASH_FORMAT";
+    /** The same identity appears earlier in the same file. */
+    readonly DUPLICATE_ENTRY: "DUPLICATE_ENTRY";
+    /** The user already exists and `upsert` was not enabled. */
+    readonly USER_ALREADY_EXISTS: "USER_ALREADY_EXISTS";
+    /** The write itself failed. */
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
+export type ImportErrorCode = (typeof IMPORT_ERROR_CODES)[keyof typeof IMPORT_ERROR_CODES];
+export interface ImportRowError {
+    code: ImportErrorCode;
+    message: string;
+    path?: string;
+}
+export type MappedPassword = Pick<PasswordInsert, "password" | "algorithm">;
+export interface MappedEntry {
+    user: Omit<UserInsert, "connection"> & {
+        connection: string;
+    };
+    password?: MappedPassword;
+}
+export type MapResult = {
+    ok: true;
+    value: MappedEntry;
+} | {
+    ok: false;
+    error: ImportRowError;
+};
+/**
+ * Resolve the entry's password into something AuthHero can actually verify.
+ *
+ * Returns `undefined` when the entry carries no credential at all — a valid
+ * case that produces a shell user who signs in via password reset or the
+ * upstream `import_mode` fallback.
+ *
+ * AuthHero verifies with `bcryptjs.compare`, so bcrypt is the only algorithm
+ * that can round-trip. Storing anything else would create a user who can
+ * never authenticate, so unsupported hashes fail the row instead.
+ */
+export declare function mapPassword(entry: UserImportEntry): {
+    ok: true;
+    value?: MappedPassword;
+} | {
+    ok: false;
+    error: ImportRowError;
+};
+/**
+ * Build the stored `provider|id` identifier for an imported entry.
+ *
+ * Auth0 prefixes bare import ids with the connection's provider; AuthHero
+ * uses the tenant's resolved username-password provider (`auth0`, or `auth2`
+ * for tenants still pinned to the legacy value) so the password row lands on
+ * the identity the login path actually reads. An entry that already carries
+ * the prefix is not double-prefixed, and one with no id at all gets a
+ * generated one — the users table requires the column.
+ *
+ * Mirrors `POST /api/v2/users`, which derives the id exactly this way.
+ */
+export declare function buildUserId(userId: string | undefined, provider: string, fallbackId?: string): string;
+/**
+ * Deterministic bare id for an import row that supplied no `user_id`.
+ *
+ * Retry safety depends on this. A driver can create a user and then die
+ * before committing that row's outcome, leaving the row `pending`; the next
+ * driver reprocesses it. With a random id the retry cannot tell its own
+ * half-finished write from a genuinely pre-existing user, and reports a
+ * successful import as `USER_ALREADY_EXISTS`. Deriving the id from
+ * `(operation_id, seq)` — both immutable for the life of the row — makes the
+ * retry regenerate the exact same id, so it can recognise its own work.
+ *
+ * Not a security boundary: the inputs are our own identifiers, so this only
+ * needs to be stable and collision-free, which a truncated SHA-256 is.
+ */
+export declare function deriveImportUserId(operationId: string, seq: number): Promise<string>;
+export interface MapEntryParams {
+    entry: UserImportEntry;
+    /** Connection NAME (the users table stores the name, not the id). */
+    connection: string;
+    /** Resolved username-password provider for this tenant. */
+    provider: string;
+    /**
+     * Id to use when the entry supplies none. Pass the value from
+     * {@link deriveImportUserId} so a reprocessed row rebuilds the same id;
+     * omitting it falls back to a random one.
+     */
+    fallbackUserId?: string;
+}
+/**
+ * Map one validated import entry onto the user and password rows to write.
+ * Pure — performs no I/O and makes no existence checks, so it is safe to call
+ * repeatedly when a chunk is retried.
+ */
+export declare function mapEntry({ entry, connection, provider, fallbackUserId, }: MapEntryParams): MapResult;
+/**
+ * Strip credential material from a staged entry before it is returned by
+ * `GET /jobs/{id}/errors`.
+ *
+ * Redaction happens on the way OUT, not on the way in: the staged row is the
+ * work item, so it must keep the hash the job exists to import. What must
+ * never happen is echoing that hash back over the API, which is what this
+ * guards. The marker is left in place so an operator reading an error can
+ * still tell a credential was supplied.
+ */
+export declare function redactEntry(entry: unknown): Record<string, unknown>;
+/**
+ * Normalize a raw file entry into the record shape a staged row stores,
+ * WITHOUT redacting: the row has to carry the credential it is going to
+ * import. {@link redactEntry} is applied when the row is read back out.
+ */
+export declare function toStagedPayload(entry: unknown): Record<string, unknown>;
+/**
+ * Identity keys Auth0 dedupes an import file on: a repeat of any of these
+ * within one file is an error rather than a silent overwrite.
+ */
+export declare function entryIdentityKeys(entry: UserImportEntry): string[];

package/dist/types/helpers/users-import/process.d.ts

@@ -0,0 +1,95 @@
+import type { DataAdapters, TenantOperation } from "@authhero/adapter-interfaces";
+/**
+ * How many staged rows one chunk processes.
+ *
+ * Sized against Cloudflare D1's per-invocation query cap (order of a
+ * thousand): a row costs up to four existence probes plus a user and a
+ * password write, so 50 rows leaves comfortable headroom for the
+ * surrounding reads and the outcome commit. Chunks are cheap — a smaller
+ * one only means more of them, while an oversized one fails the whole
+ * invocation.
+ */
+export declare const DEFAULT_CHUNK_SIZE = 50;
+/** How long a driver's lease on an operation is valid. */
+export declare const DEFAULT_LEASE_MS = 60000;
+export interface UsersImportInput {
+    connection_id: string;
+    connection: string;
+    upsert: boolean;
+    external_id?: string;
+    send_completion_email?: boolean;
+    provider: string;
+}
+export interface AdvanceOptions {
+    /** Stop after this many rows, so a driver can bound its own runtime. */
+    maxRows?: number;
+    /** Rows per chunk; defaults to {@link DEFAULT_CHUNK_SIZE}. */
+    chunkSize?: number;
+    /** Lease duration for this driver's claim. */
+    leaseMs?: number;
+    /**
+     * Wall-clock deadline (epoch ms). The driver stops cleanly at the next
+     * chunk boundary once passed, leaving the remainder `pending` for the
+     * next driver — never mid-chunk, so no work is half-committed.
+     */
+    deadline?: number;
+    /** Identifies the lease holder; defaults to a random id. */
+    workerId?: string;
+}
+export interface AdvanceResult {
+    /** True when no `pending` rows remain and the operation was finalized. */
+    done: boolean;
+    /** Rows this call committed an outcome for. */
+    processed: number;
+    /** Rows still `pending` after this call. */
+    remaining: number;
+    /** False when another live driver holds the lease. */
+    claimed: boolean;
+}
+/**
+ * Read the operation's `input` back into a typed shape. The row is written
+ * by the accept route, so a malformed one means the operation is
+ * unrunnable rather than that the caller made a mistake.
+ */
+export declare function parseImportInput(operation: TenantOperation): UsersImportInput | null;
+/**
+ * Advance a `users_import` operation by processing staged rows until it is
+ * finished or the caller's budget runs out.
+ *
+ * This is the whole execution model. Every engine — an inline kick from the
+ * accepting request, a cron sweep, a Cloudflare Workflow step — calls this
+ * same function; they differ only in how much budget they pass and how often
+ * they call it. Durability comes from the database, not from the caller:
+ * outcomes are committed chunk by chunk, so a driver that dies loses at most
+ * the chunk in flight, and those rows stay `pending` for whoever runs next.
+ */
+export declare function advanceUsersImport(data: DataAdapters, operationId: string, options?: AdvanceOptions): Promise<AdvanceResult>;
+/** Auth0's job summary shape, derived from the staged-row counts. */
+export declare function buildSummary(counts: {
+    total: number;
+    inserted: number;
+    updated: number;
+    failed: number;
+}): Record<string, number>;
+export interface ResumeUsersImportsOptions extends Omit<AdvanceOptions, "workerId"> {
+    /** Maximum operations to advance in one sweep. */
+    maxOperations?: number;
+}
+export interface ResumeUsersImportsResult {
+    scanned: number;
+    advanced: number;
+    completed: number;
+    errors: number;
+}
+/**
+ * Resume every unfinished bulk import that no live driver is working on.
+ *
+ * This is what makes the feature durable regardless of deployment. Wire it
+ * to a scheduled handler alongside `runRetention`: whatever started an
+ * import — a request that timed out, a worker that was evicted, a process
+ * that was redeployed mid-run — the sweep picks the job back up and carries
+ * it to completion from the last committed chunk.
+ *
+ * One operation's failure never aborts the sweep.
+ */
+export declare function resumeUsersImports(data: DataAdapters, options?: ResumeUsersImportsOptions): Promise<ResumeUsersImportsResult>;

package/dist/types/helpers/users-import-cleanup.d.ts

@@ -0,0 +1,26 @@
+import { DataAdapters } from "@authhero/adapter-interfaces";
+/**
+ * Auth0 deletes all job-related data 24 hours after the job is created.
+ */
+export declare const DEFAULT_IMPORT_JOB_RETENTION_HOURS = 24;
+export interface UsersImportCleanupParams {
+    /** Hours to keep finished import jobs. Defaults to Auth0's 24. */
+    retentionHours?: number;
+    /** Maximum jobs to delete per sweep. */
+    limit?: number;
+}
+/**
+ * Delete finished bulk-import jobs (and, by cascade, their staged rows)
+ * older than the retention window.
+ *
+ * Staged rows hold the submitted user entries, so this is a privacy control
+ * as much as a housekeeping one — though credential material is redacted
+ * before staging rather than relying on this sweep.
+ *
+ * Only terminal jobs are removed: an unfinished import may legitimately be
+ * older than the window (a very large file, or one that has been waiting on
+ * a resume sweep), and deleting it would strand the users it had not yet
+ * created. Returns the number of jobs deleted, or `null` when the
+ * deployment has no tenant-operations adapter.
+ */
+export declare function cleanupUsersImports(data: DataAdapters, params?: UsersImportCleanupParams): Promise<number | null>;