authhero 5.8.1 → 5.9.1

package/dist/types/utils/encryption.d.ts

@@ -0,0 +1,22 @@
+import * as x509 from "@peculiar/x509";
+import { SigningKey } from "@authhero/adapter-interfaces";
+/**
+ * Supported signing-key shapes. Note: `EC-P-521` is not supported on
+ * Cloudflare Workers (`workerd`) — `crypto.subtle.generateKey` will reject
+ * `{ name: "ECDSA", namedCurve: "P-521" }` there. Callers running on Workers
+ * must pick `RSA`, `EC-P-256`, or `EC-P-384`.
+ */
+export type SigningKeyType = "RSA" | "EC-P-256" | "EC-P-384" | "EC-P-521";
+export interface CreateX509CertificateParams {
+    name: string;
+    /**
+     * The key type to generate. Defaults to "RSA" (RS256-compatible) for
+     * backwards compatibility with existing tenants.
+     */
+    keyType?: SigningKeyType;
+}
+export declare function createX509Certificate(params: CreateX509CertificateParams): Promise<SigningKey>;
+export declare function convertPKCS7ToPem(keyType: "PRIVATE" | "PUBLIC", binaryData: ArrayBuffer): string;
+export declare function toJWKS(key: CryptoKey): Promise<JsonWebKey>;
+export declare function getJWKThumbprint(cert: x509.X509Certificate): Promise<string>;
+export declare function computeJWKThumbprint(jwk: JsonWebKey): Promise<string>;

package/dist/types/utils/entity-id.d.ts

@@ -0,0 +1,13 @@
+export type EntityType = "organization" | "connection" | "action" | "hook" | "rule" | "resource_server" | "guardian_factor" | "invite" | "flow";
+export declare function generateEntityId(entityType: EntityType): string;
+export declare function parseEntityId(entityId: string, entityType: EntityType): string;
+export declare function generateOrganizationId(): string;
+export declare function generateConnectionId(): string;
+export declare function generateActionId(): string;
+export declare function generateHookId(): string;
+export declare function generateRuleId(): string;
+export declare function generateResourceServerId(): string;
+export declare function generateGuardianFactorId(): string;
+export declare function generateInviteId(): string;
+export declare function generateFlowId(): string;
+export declare function getEntityTypeFromId(entityId: string): EntityType | null;

package/dist/types/utils/fetchAll.d.ts

@@ -0,0 +1,60 @@
+import { ListParams } from "@authhero/adapter-interfaces";
+/**
+ * Options for fetching all resources with pagination.
+ */
+export interface FetchAllOptions {
+    /**
+     * The field to use for cursor-based pagination.
+     * This field should be unique and sortable (e.g., 'id', 'created_at').
+     * @default 'id'
+     */
+    cursorField?: string;
+    /**
+     * The sort order for the cursor field.
+     * @default 'asc'
+     */
+    sortOrder?: "asc" | "desc";
+    /**
+     * Maximum number of items to fetch per page.
+     * @default 100
+     */
+    pageSize?: number;
+    /**
+     * Maximum total items to fetch (for safety).
+     * Set to -1 for unlimited.
+     * @default 10000
+     */
+    maxItems?: number;
+    /**
+     * Optional filter query (Lucene-style).
+     */
+    q?: string;
+}
+/**
+ * Fetches all resources from a paginated list endpoint by iterating through pages.
+ *
+ * Uses cursor-based pagination by filtering on a sortable field (like 'id') to ensure
+ * consistent results even if data changes between requests.
+ *
+ * @param listFn - The list function from the adapter (e.g., adapters.tenants.list)
+ * @param itemsKey - The key in the response that contains the array of items (e.g., 'tenants', 'users')
+ * @param options - Pagination options
+ * @returns Promise resolving to an array of all items
+ *
+ * @example
+ * ```typescript
+ * // Fetch all tenants
+ * const allTenants = await fetchAll(
+ *   (params) => adapters.tenants.list(params),
+ *   'tenants'
+ * );
+ *
+ * // Fetch all users for a tenant with custom options
+ * const allUsers = await fetchAll(
+ *   (params) => adapters.users.list(tenantId, params),
+ *   'users',
+ *   { cursorField: 'user_id', pageSize: 50 }
+ * );
+ * ```
+ */
+export declare function fetchAll<T>(listFn: (params: ListParams) => Promise<any>, itemsKey: string, options?: FetchAllOptions): Promise<T[]>;

package/dist/types/utils/form-post.d.ts

@@ -0,0 +1 @@
+export declare function formPostResponse(redirectUri: string, params: Record<string, string>, headers: Headers): Response;

package/dist/types/utils/id-token-hash.d.ts

@@ -0,0 +1 @@
+export declare function computeIdTokenHash(value: string, signingAlg: string): Promise<string>;

package/dist/types/utils/incognito.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Synchronously checks if the browser is in incognito mode by reading from session storage
+ * @returns true if incognito, false if not incognito, undefined if not yet determined
+ */
+export declare function isIncognito(): boolean | undefined;
+/**
+ * Detects incognito mode using the detectincognitojs library and persists the result to session storage
+ * Only performs detection if not already cached in session storage
+ * @returns Promise<boolean> indicating if the browser is in incognito mode
+ */
+export declare function detectAndCacheIncognito(): Promise<boolean>;

package/dist/types/utils/instance-to-json.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Converts an iterable object (like Headers, URLSearchParams) to a plain JSON object.
+ * This is useful for serializing objects that don't naturally serialize to JSON.
+ *
+ * @param instance - An iterable object where each item is a [key, value] pair
+ * @returns A plain object with the key-value pairs
+ */
+export declare function instanceToJson<T = string>(instance: Headers | URLSearchParams | Iterable<[string, T]>): Record<string, T>;

package/dist/types/utils/ip.d.ts

@@ -0,0 +1,8 @@
+export declare function isIPv4(ip: string): boolean;
+export declare function isIPv6(ip: string): boolean;
+export declare function stripPort(ip: string): string;
+export declare function normalizeIp(ip: string): {
+    family: 4 | 6;
+    normalized: string;
+} | null;
+export declare function isIpMatch(ipA: string, ipB: string, strict?: boolean): boolean;

package/dist/types/utils/is-valid-redirect-url.d.ts

@@ -0,0 +1,4 @@
+export declare function isValidRedirectUrl(url: string, allowedUrls?: string[], options?: {
+    allowPathWildcards?: boolean;
+    allowSubDomainWildcards?: boolean;
+}): boolean;

package/dist/types/utils/jwk-alg.d.ts

@@ -0,0 +1,20 @@
+export type SupportedAlg = "RS256" | "RS384" | "RS512" | "ES256" | "ES384" | "ES512";
+export declare function algForJwk(jwk: {
+    kty: string;
+    crv?: string;
+    alg?: string;
+}): SupportedAlg;
+export declare function importParamsForJwk(jwk: {
+    kty: string;
+    crv?: string;
+}, alg: string): RsaHashedImportParams | EcKeyImportParams;
+/**
+ * The set of `id_token_signing_alg_values_supported` we currently advertise.
+ * Derived from the algorithms we can actually issue + verify.
+ */
+export declare const SUPPORTED_ID_TOKEN_SIGNING_ALGS: SupportedAlg[];
+/**
+ * Derive the JWS signing algorithm to use with a signing key, by inspecting
+ * the public-key material embedded in its X.509 cert.
+ */
+export declare function algForCert(certPem: string): Promise<SupportedAlg>;

package/dist/types/utils/jwks.d.ts

@@ -0,0 +1,41 @@
+import { DataAdapters } from "@authhero/adapter-interfaces";
+import { SigningKeyModeOption } from "../types/AuthHeroConfig";
+/**
+ * Helper function to fetch JWKS keys from the database for token *verification*.
+ *
+ * Returns every non-revoked `jwt_signing` key regardless of tenant scope so a
+ * token signed by any key (control-plane or any tenant) can be matched by kid.
+ * Use `getJwksForPublication` for the public `/.well-known/jwks.json` endpoint.
+ */
+export declare function getJwksFromDatabase(data: DataAdapters): Promise<{
+    alg: "RS256" | "RS384" | "RS512" | "ES256" | "ES384" | "ES512" | "HS256" | "HS384" | "HS512";
+    kid: string;
+    kty: "EC" | "RSA" | "oct";
+    use?: "sig" | "enc" | undefined;
+    n?: string | undefined;
+    e?: string | undefined;
+    crv?: string | undefined;
+    x?: string | undefined;
+    y?: string | undefined;
+    x5t?: string | undefined;
+    x5c?: string[] | undefined;
+}[]>;
+/**
+ * JWKS for publication on a tenant's `/.well-known/jwks.json`. Honors the
+ * configured `signingKeyMode` and, in `"tenant"` mode, returns the union of
+ * the tenant's keys and the control-plane fallback so tokens signed by either
+ * still verify during the per-tenant key rollout.
+ */
+export declare function getJwksForPublication(data: DataAdapters, tenantId: string, modeOption: SigningKeyModeOption | undefined): Promise<{
+    alg: "RS256" | "RS384" | "RS512" | "ES256" | "ES384" | "ES512" | "HS256" | "HS384" | "HS512";
+    kid: string;
+    kty: "EC" | "RSA" | "oct";
+    use?: "sig" | "enc" | undefined;
+    n?: string | undefined;
+    e?: string | undefined;
+    crv?: string | undefined;
+    x?: string | undefined;
+    y?: string | undefined;
+    x5t?: string | undefined;
+    x5c?: string[] | undefined;
+}[]>;

package/dist/types/utils/jwt.d.ts

@@ -0,0 +1,15 @@
+import { Context } from "hono";
+export interface JwtPayload {
+    sub: string;
+    iss: string;
+    aud: string | string[];
+    iat: number;
+    exp: number;
+    scope: string;
+    permissions?: string[];
+    azp?: string;
+    tenant_id?: string;
+    org_id?: string;
+    org_name?: string;
+}
+export declare function validateJwtToken(ctx: Context, token: string): Promise<JwtPayload>;

package/dist/types/utils/organization-id.d.ts

@@ -0,0 +1,2 @@
+export declare function organizationIdGenerate(): string;
+export declare function organizationIdParse(organizationId: string): string;

package/dist/types/utils/otp.d.ts

@@ -0,0 +1 @@
+export default function generateOTP(): string;

package/dist/types/utils/refresh-token-format.d.ts

@@ -0,0 +1,20 @@
+export declare const REFRESH_TOKEN_PREFIX = "rt_";
+export declare const LOOKUP_BYTES = 7;
+export declare const SECRET_BYTES = 32;
+export declare const LEGACY_CUTOFF: Date;
+export type ParsedRefreshToken = {
+    kind: "new";
+    lookup: string;
+    secret: string;
+} | {
+    kind: "legacy";
+    id: string;
+};
+export declare function generateRefreshTokenParts(): {
+    lookup: string;
+    secret: string;
+};
+export declare function hashRefreshTokenSecret(secret: string): Promise<string>;
+export declare function formatRefreshToken(lookup: string, secret: string): string;
+export declare function parseRefreshToken(token: string): ParsedRefreshToken;
+export declare function isLegacyRefreshTokenAccepted(now?: Date): boolean;

package/dist/types/utils/safe-compare.d.ts

@@ -0,0 +1 @@
+export declare function safeCompare(a?: string, b?: string): boolean;

package/dist/types/utils/sort.d.ts

@@ -0,0 +1,4 @@
+export declare function parseSort(sort?: string): undefined | {
+    sort_by: string;
+    sort_order: "asc" | "desc";
+};

package/dist/types/utils/ssrf-fetch.d.ts

@@ -0,0 +1,44 @@
+export interface SsrfFetchOptions {
+    /** Max bytes to read from the response body. Defaults to 64 KiB. */
+    maxBytes?: number;
+    /** Request timeout in ms. Defaults to 5000ms. */
+    timeoutMs?: number;
+    /** Allowed schemes. Defaults to ["https:"]. Set to ["http:", "https:"] for tests. */
+    allowedSchemes?: string[];
+    /**
+     * When true, hostnames resolving to private/loopback ranges (and
+     * `localhost`) are allowed. Intended for tests only.
+     */
+    allowPrivateHosts?: boolean;
+}
+export declare class SsrfBlockedError extends Error {
+    constructor(reason: string);
+}
+/**
+ * Inspect a URL string and throw {@link SsrfBlockedError} if its literal
+ * hostname is an IP address in a blocked range (see {@link isBlockedIPv4},
+ * {@link isBlockedIPv6}) or a known loopback/broadcast hostname (see
+ * {@link BLOCKED_HOSTNAMES}).
+ *
+ * IMPORTANT: this function does NOT perform DNS resolution. A public-looking
+ * hostname whose A/AAAA records point to a private/loopback/metadata IP will
+ * pass this check and only be rejected later (or not at all) by the underlying
+ * fetch. Production deployments that need full SSRF protection must add either:
+ *   - egress controls (firewall / network policy blocking RFC1918 + 169.254 +
+ *     fc00::/7 + fe80::/10 from the auth server), or
+ *   - a server-side DNS check that resolves the host with `dns.lookup` and
+ *     re-runs {@link isBlockedIPv4}/{@link isBlockedIPv6} on each address (or
+ *     connect by resolved IP while passing the original Host header).
+ */
+export declare function assertSsrfSafeUrl(rawUrl: string, opts?: SsrfFetchOptions): URL;
+/**
+ * Fetch a URL with SSRF protection: blocks private/loopback/link-local
+ * targets, requires https by default, applies a strict timeout, and caps the
+ * response body. Intended for fetching client-published artifacts (jwks_uri,
+ * request_uri) where the URL comes from untrusted client metadata.
+ */
+export declare function ssrfSafeFetch(rawUrl: string, opts?: SsrfFetchOptions): Promise<{
+    status: number;
+    body: string;
+    contentType: string | null;
+}>;

package/dist/types/utils/ulid.d.ts

@@ -0,0 +1 @@
+export declare function ulid(): string;

package/dist/types/utils/url.d.ts

@@ -0,0 +1,16 @@
+export declare function setSearchParams(url: URL, params: {
+    [key: string]: string | undefined | null;
+}): void;
+/**
+ * Redacts sensitive data from a URL for logging purposes.
+ * Shows parameter names but redacts their values to aid troubleshooting
+ * while protecting PII, tokens, and other sensitive information.
+ *
+ * @param url - The URL to redact (can be a string or URL object)
+ * @returns The redacted URL with parameter names visible but values hidden
+ *
+ * @example
+ * redactUrlForLogging("https://example.com/path?token=secret&code=abc#id_token=jwt")
+ * // Returns: "https://example.com/path?token=[REDACTED]&code=[REDACTED]#[REDACTED]"
+ */
+export declare function redactUrlForLogging(url: string | URL): string;

package/dist/types/utils/user-id.d.ts

@@ -0,0 +1,2 @@
+export declare function userIdGenerate(): string;
+export declare function userIdParse(userId: string): string | undefined;

package/dist/types/utils/username-password-provider.d.ts

@@ -0,0 +1,67 @@
+import { User } from "@authhero/adapter-interfaces";
+import { Context } from "hono";
+import { Bindings, Variables } from "../types";
+import { EnrichedClient } from "../helpers/client";
+/**
+ * TRANSITIONAL helpers for the auth2 → auth0 provider migration.
+ *
+ * Historically every native database user has been stored with
+ * `provider = "auth2"` and `user_id = "auth2|<id>"`. We're moving onto the
+ * `"auth0"` provider value, one tenant at a time, by setting
+ * `init({ usernamePasswordProvider })` to return `"auth0"` for the
+ * migrated tenants.
+ *
+ * Two surfaces are exposed:
+ *
+ * - {@link resolveUsernamePasswordProvider} — used at WRITE sites to pick
+ *   the value to stamp on a new row. Defaults to `"auth2"`.
+ * - {@link isUsernamePasswordProvider} / {@link getUsernamePasswordUser} /
+ *   {@link getPrimaryUsernamePasswordUser} — used at READ sites to match
+ *   existing rows under EITHER value, so a tenant can have a mix of
+ *   `auth2|*` and `auth0|*` rows during/after the cutover.
+ *
+ * Once every tenant has been backfilled to a single provider value, this
+ * module and its callers can be deleted in favour of a plain constant.
+ */
+declare const LEGACY_PROVIDER = "auth2";
+declare const TARGET_PROVIDER = "auth0";
+export type UsernamePasswordProviderValue = typeof LEGACY_PROVIDER | typeof TARGET_PROVIDER;
+export declare function resolveUsernamePasswordProvider(env: Bindings, tenant_id: string): Promise<UsernamePasswordProviderValue>;
+export declare function isUsernamePasswordProvider(provider: string | undefined | null): boolean;
+interface DualReadParams {
+    env: Bindings;
+    tenant_id: string;
+    username: string;
+}
+/**
+ * Look up a native database user, accepting either provider value.
+ *
+ * ALWAYS tries `"auth2"` first, then `"auth0"`, regardless of the tenant's
+ * configured write value. The `auth2` row is the one carrying the bcrypt
+ * password legacy users have been logging in with — if both rows happen
+ * to coexist for the same identifier (partial backfill, Auth0 import,
+ * etc.) we want login to keep using the `auth2` row so credentials
+ * continue to work. The migration script merges the duplicates.
+ */
+export declare function getUsernamePasswordUser({ env, tenant_id, username, }: DualReadParams): Promise<User | null>;
+/**
+ * Same as {@link getUsernamePasswordUser} but resolves to the primary user
+ * if a linked secondary is matched. Same `auth2`-first ordering.
+ */
+export declare function getPrimaryUsernamePasswordUser({ env, tenant_id, username, }: DualReadParams): Promise<User | null>;
+/**
+ * Find-or-create wrapper that first looks for an existing native database
+ * user under EITHER provider value, and only creates a new row (under the
+ * configured provider) if none exists. Prevents duplicating an existing
+ * `auth2|*` user when the tenant is migrated to `"auth0"`.
+ */
+export declare function getOrCreateUsernamePasswordUser(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, params: {
+    client: EnrichedClient;
+    username: string;
+    connection: string;
+    ip?: string;
+}): Promise<User>;
+export {};

package/dist/types/utils/username.d.ts

@@ -0,0 +1,11 @@
+import { CountryCode } from "libphonenumber-js";
+type ConnectionType = "email" | "sms" | "username";
+interface NormalizedResult {
+    connectionType: ConnectionType;
+    normalized: string | null;
+    isValid: boolean;
+    /** The provider to use for user lookup. For email, this is "email" but password users use the username-password provider */
+    provider: string;
+}
+export declare function getConnectionFromIdentifier(input: string, defaultCountry?: CountryCode): NormalizedResult;
+export {};

package/dist/types/variables.d.ts

@@ -0,0 +1,4 @@
+import { Bindings } from "./types";
+export declare function getIssuer(env: Bindings, customDomain?: string): string;
+export declare function getUniversalLoginUrl(env: Bindings, customDomain?: string): string;
+export declare function getAuthUrl(env: Bindings, customDomain?: string): string;

package/package.json

@@ -11,7 +11,7 @@
     "type": "git",
     "url": "https://github.com/markusahlstrand/authhero"
   },
-  "version": "5.8.1",
+  "version": "5.9.1",
   "files": [
     "dist"
   ],
@@ -32,10 +32,9 @@
   "devDependencies": {
     "@ape-egg/tailwind-rows-columns": "^1.0.2",
     "@hono/node-server": "^1.19.14",
+    "@hono/zod-openapi": "^1.4.0",
     "@react-email/components": "^1.0.12",
     "@react-email/render": "^2.0.6",
-    "tsx": "^4.21.0",
-    "@hono/zod-openapi": "^0.19.10",
     "@storybook/react": "^10.0.4",
     "@storybook/react-vite": "^10.0.4",
     "@types/node": "^24.10.0",
@@ -47,7 +46,6 @@
     "better-sqlite3": "^12.4.1",
     "cssnano": "7.1.2",
     "detectincognitojs": "^1.6.2",
-    "dts-bundle-generator": "^9.5.1",
     "fast-xml-parser": "^5.3.1",
     "hono": "^4.10.4",
     "i18nexus-cli": "^3.8.2",
@@ -55,15 +53,17 @@
     "postcss": "8.5.6",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
+    "rollup-plugin-dts": "^6.4.1",
     "rollup-plugin-visualizer": "^6.0.5",
     "storybook": "^10.0.4",
     "tailwindcss": "3.4.18",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vite": "^7.2.0",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^4.0.7",
-    "@authhero/kysely-adapter": "11.2.2",
-    "@authhero/widget": "0.32.26"
+    "@authhero/kysely-adapter": "11.3.0",
+    "@authhero/widget": "0.32.27"
   },
   "dependencies": {
     "@peculiar/x509": "^1.14.0",
@@ -74,19 +74,19 @@
     "cookie": "^1.1.1",
     "country-list": "^2.4.1",
     "i18next": "^25.6.0",
-    "liquidjs": "^10.21.0",
     "libphonenumber-js": "^1.12.25",
+    "liquidjs": "^10.21.0",
     "nanoid": "^5.1.6",
     "oslo": "^1.2.1",
     "qrcode": "^1.5.4",
     "sanitize-html": "^2.17.0",
     "xstate": "^5.25.0",
-    "@authhero/saml": "0.3.0",
-    "@authhero/adapter-interfaces": "2.5.0"
+    "@authhero/adapter-interfaces": "2.6.0",
+    "@authhero/saml": "0.4.0"
   },
   "peerDependencies": {
     "@authhero/widget": "^0.1.0",
-    "@hono/zod-openapi": "^0.19.2",
+    "@hono/zod-openapi": "^1.4.0",
     "hono": "^4.8.7",
     "ua-parser-js": "^2.0.0"
   },
@@ -103,7 +103,7 @@
   },
   "scripts": {
     "dev": "bun --watch src/bun.ts",
-    "build": "export NODE_OPTIONS=--max-old-space-size=8192 && pnpm build:i18n && pnpm build:emails && pnpm build:tailwind && pnpm build:client && tsc && vite build && dts-bundle-generator --config ./dts-bundle-generator.config.ts && pnpm build:assets",
+    "build": "pnpm build:i18n && pnpm build:emails && pnpm build:tailwind && pnpm build:client && tsc -p tsconfig.types.json && vite build && rollup -c rollup.dts.config.mjs && pnpm build:assets",
     "build:i18n": "node scripts/generate-locale-types.js",
     "build:emails": "tsx scripts/build-emails.tsx",
     "build:tailwind": "node build-tailwind.js",