authhero 9.10.0 → 9.11.0

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/reserved-claims.d.ts

@@ -15,9 +15,9 @@ export declare const USERINFO_RESERVED_CLAIMS: readonly ["iss", "sub", "aud", "e
  * 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" | "org_id" | "org_name" | "sub" | "permissions" | "iat" | "exp" | "iss" | "aud" | "auth_time" | "acr" | "amr" | "nbf" | "jti" | "act" | "requested_userinfo_claims" | "gty")[];
+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" | "org_id" | "org_name" | "sub" | "permissions" | "iat" | "exp" | "iss" | "aud" | "auth_time" | "acr" | "amr" | "azp" | "nbf" | "jti" | "act" | "requested_userinfo_claims" | "gty")[];
+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];
 /**

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>;