authhero 5.8.1 → 5.9.0

package/dist/types/adapters/cache/in-memory.d.ts

@@ -0,0 +1,52 @@
+import { CacheAdapter } from "@authhero/adapter-interfaces";
+export interface InMemoryCacheConfig {
+    /**
+     * Default TTL in seconds for cache entries (optional)
+     */
+    defaultTtlSeconds?: number;
+    /**
+     * Maximum number of entries in the cache (optional, for basic LRU behavior)
+     */
+    maxEntries?: number;
+    /**
+     * Interval in milliseconds for cleanup of expired entries (default: 60000ms = 1 minute)
+     */
+    cleanupIntervalMs?: number;
+}
+export declare class InMemoryCache implements CacheAdapter {
+    private config;
+    private cache;
+    private accessOrder;
+    private accessCounter;
+    private cleanupTimer?;
+    constructor(config?: InMemoryCacheConfig);
+    get<T = any>(key: string): Promise<T | null>;
+    set<T = any>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    deleteByPrefix(prefix: string): Promise<number>;
+    clear(): Promise<void>;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        maxEntries: number | undefined;
+        defaultTtlSeconds: number | undefined;
+    };
+    /**
+     * Clean up expired entries
+     */
+    private cleanupExpired;
+    /**
+     * Evict least recently used entry
+     */
+    private evictLeastRecentlyUsed;
+    /**
+     * Stop cleanup timer (useful for testing or graceful shutdown)
+     */
+    destroy(): void;
+}
+/**
+ * Create an in-memory cache adapter
+ */
+export declare function createInMemoryCache(config?: InMemoryCacheConfig): CacheAdapter;

package/dist/types/adapters/cache/index.d.ts

@@ -0,0 +1,2 @@
+export { createInMemoryCache } from "./in-memory";
+export type { InMemoryCacheConfig } from "./in-memory";

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

@@ -0,0 +1 @@
+export * from "./cache";

package/dist/types/authentication-flows/auth0-migration.d.ts

@@ -0,0 +1,53 @@
+import { Context } from "hono";
+import { Connection, User } from "@authhero/adapter-interfaces";
+import { Bindings, Variables } from "../types";
+import { EnrichedClient } from "../helpers/client";
+interface Auth0SourceCredentials {
+    tokenEndpoint: string;
+    userinfoEndpoint: string;
+    clientId: string;
+    clientSecret: string;
+    realm?: string;
+}
+/**
+ * Read the upstream migration credentials from a DB connection's
+ * `options.configuration` (Auth0-shape: the destination connection holds the
+ * upstream creds inline). Returns null if any required field is missing —
+ * callers should treat this as "migration is not configured" and fall through
+ * to the normal failure path.
+ */
+export declare function readAuth0SourceCredentials(dbConnection: Connection): Auth0SourceCredentials | null;
+interface AttemptUpstreamPasswordParams {
+    ctx: Context<{
+        Bindings: Bindings;
+        Variables: Variables;
+    }>;
+    client: EnrichedClient;
+    username: string;
+    password: string;
+    /**
+     * The local DB connection the login is targeting. Its `name` is sent as
+     * `realm` to upstream Auth0 (unless `options.configuration.realm` overrides
+     * it), and its `options.configuration` carries the upstream credentials.
+     * Must have `options.import_mode: true` to be eligible.
+     */
+    dbConnection: Connection;
+    /**
+     * The local user, if one already exists. When null, a new user record is
+     * created from the `/userinfo` profile on upstream success.
+     */
+    existingUser: User | null;
+}
+/**
+ * Attempts to verify the supplied password against the upstream Auth0 tenant
+ * via the password-realm grant. On success, creates the local user (if
+ * missing), stores the bcrypt hash of the password locally, and returns the
+ * user. On any failure, returns null — the caller surfaces the existing
+ * INVALID_PASSWORD/USER_NOT_FOUND error so the upstream's existence is not
+ * leaked to clients.
+ *
+ * Subsequent logins are served entirely locally because the password row now
+ * exists on our side.
+ */
+export declare function attemptUpstreamPasswordFallback(params: AttemptUpstreamPasswordParams): Promise<User | null>;
+export {};

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

@@ -0,0 +1,23 @@
+import { Context } from "hono";
+import { z } from "@hono/zod-openapi";
+import { Bindings, Variables } from "../types";
+import { TokenResponse } from "@authhero/adapter-interfaces";
+import { GrantFlowUserResult } from "src/types/GrantFlowResult";
+export declare const authorizationCodeGrantParamsSchema: z.ZodObject<{
+    grant_type: z.ZodLiteral<"authorization_code">;
+    client_id: z.ZodString;
+    code: z.ZodString;
+    redirect_uri: z.ZodOptional<z.ZodString>;
+    client_secret: z.ZodOptional<z.ZodString>;
+    code_verifier: z.ZodOptional<z.ZodString>;
+    organization: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AuthorizationCodeGrantTypeParams = z.infer<typeof authorizationCodeGrantParamsSchema>;
+export declare function authorizationCodeGrantUser(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, params: AuthorizationCodeGrantTypeParams): Promise<GrantFlowUserResult>;
+export declare function authorizationCodeGrant(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, params: AuthorizationCodeGrantTypeParams): Promise<TokenResponse | Response>;

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

@@ -0,0 +1,16 @@
+import { Context } from "hono";
+import { z } from "@hono/zod-openapi";
+import { Bindings, Variables } from "../types";
+import { GrantFlowResult } from "../types/GrantFlowResult";
+export declare const clientCredentialGrantParamsSchema: z.ZodObject<{
+    grant_type: z.ZodLiteral<"client_credentials">;
+    scope: z.ZodOptional<z.ZodString>;
+    client_secret: z.ZodOptional<z.ZodString>;
+    client_id: z.ZodString;
+    audience: z.ZodOptional<z.ZodString>;
+    organization: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare function clientCredentialsGrant(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, params: z.infer<typeof clientCredentialGrantParamsSchema>): Promise<GrantFlowResult>;

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

@@ -0,0 +1,253 @@
+import { AuthorizationResponseType, AuthParams, LoginSession, RefreshToken, User, TokenResponse } from "@authhero/adapter-interfaces";
+import { EnrichedClient } from "../helpers/client";
+import { Context } from "hono";
+import { Bindings, Variables } from "../types";
+import { GrantType } from "@authhero/adapter-interfaces";
+/**
+ * Minimal client properties actually used by createAuthTokens.
+ * This avoids requiring a full EnrichedClient when only a few fields are needed
+ * (e.g. service tokens).
+ */
+export interface AuthTokenClient {
+    client_id: string;
+    tenant: {
+        audience: string;
+        default_audience?: string;
+        allow_organization_name_in_authentication_api?: boolean;
+    };
+    auth0_conformant?: boolean;
+}
+export interface CreateAuthTokensParams {
+    authParams: AuthParams;
+    client: AuthTokenClient;
+    loginSession?: LoginSession;
+    user?: User;
+    session_id?: string;
+    refresh_token?: string;
+    authStrategy?: {
+        strategy: string;
+        strategy_type: string;
+    };
+    /** The connection name used for authentication (e.g., "email", "google-oauth2") */
+    authConnection?: string;
+    ticketAuth?: boolean;
+    skipHooks?: boolean;
+    organization?: {
+        id: string;
+        name: string;
+    };
+    permissions?: string[];
+    grantType?: GrantType;
+    impersonatingUser?: User;
+    auth_time?: number;
+    /** Custom claims to add to the access token payload (cannot override reserved claims) */
+    customClaims?: Record<string, unknown>;
+    /** Access token lifetime in seconds, from resource server config */
+    token_lifetime?: number;
+    /**
+     * Authorization code co-issued in the same front-channel response (hybrid
+     * flow). When provided AND an id_token is being issued, a `c_hash` claim
+     * covering this code is added to the id_token per OIDC Core 3.3.2.11.
+     */
+    code?: string;
+}
+export declare function createAuthTokens(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, params: CreateAuthTokensParams): Promise<TokenResponse>;
+export interface CreateCodeParams {
+    user: User;
+    client: EnrichedClient;
+    authParams: AuthParams;
+    login_id: string;
+}
+export declare function createCodeData(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, params: CreateCodeParams): Promise<{
+    code: string;
+    state: string | undefined;
+}>;
+export interface CreateRefreshTokenParams {
+    user: User;
+    client: EnrichedClient;
+    login_id: string;
+    scope: string;
+    audience?: string;
+}
+export interface CreatedRefreshToken {
+    row: RefreshToken;
+    wireToken: string;
+}
+export declare function createRefreshToken(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, params: CreateRefreshTokenParams): Promise<CreatedRefreshToken>;
+export interface CreateSessionParams {
+    user: User;
+    client: EnrichedClient;
+    loginSession: LoginSession;
+}
+export interface AuthenticateLoginSessionParams {
+    user: User;
+    client: EnrichedClient;
+    loginSession: LoginSession;
+    /** Optional existing session to reuse instead of creating a new one */
+    existingSessionId?: string;
+    /** The connection name used for authentication (e.g., "email", "google-oauth2") */
+    authConnection?: string;
+}
+/**
+ * Authenticate a login session - transitions from PENDING to AUTHENTICATED
+ *
+ * This is the single source of truth for authentication state transitions.
+ * It either creates a new session or links an existing one, and always
+ * transitions the state to AUTHENTICATED.
+ *
+ * Uses optimistic concurrency: re-fetches current state to prevent stale overwrites
+ * and guards against terminal states (FAILED, EXPIRED, COMPLETED)
+ *
+ * @returns The session ID (either newly created or existing)
+ */
+export declare function authenticateLoginSession(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, { user, client, loginSession, existingSessionId, authConnection, }: AuthenticateLoginSessionParams): Promise<string>;
+export interface FinalizeAuthenticatedSessionParams extends AuthenticateLoginSessionParams {
+    /** Strategy metadata persisted so /authorize/resume can rehydrate it */
+    authStrategy?: {
+        strategy: string;
+        strategy_type: string;
+    };
+}
+/**
+ * Persist an authenticated identity onto the login session and 302 the browser
+ * to `/authorize/resume?state=…`. This is the terminal step for sub-flows
+ * (social callback, UL password/OTP/signup, SAML SP-ACS, etc.) — instead of
+ * issuing tokens and setting the session cookie inline, they persist enough
+ * state for the resume endpoint to do it on the correct domain.
+ *
+ * Mirrors Auth0's pattern where /u/login/{password,…} 302s to /authorize/resume.
+ */
+export declare function finalizeAuthenticatedSession(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, params: FinalizeAuthenticatedSessionParams): Promise<Response>;
+/**
+ * @deprecated Use authenticateLoginSession instead.
+ * This function is kept for backward compatibility but will be removed.
+ */
+export declare function createSession(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, { user, client, loginSession }: CreateSessionParams): Promise<{
+    id: string;
+}>;
+/**
+ * Mark a login session as failed
+ * This should be called when authentication fails (wrong password, blocked user, etc.)
+ *
+ * Uses optimistic concurrency: re-fetches current state to prevent stale overwrites
+ */
+export declare function failLoginSession(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, tenantId: string, loginSession: LoginSession, reason: string): Promise<void>;
+/**
+ * Mark a login session as awaiting hook completion
+ * This should be called when redirecting to a form, page, or external URL
+ *
+ * Uses optimistic concurrency: re-fetches current state to prevent stale overwrites
+ */
+export declare function startLoginSessionHook(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, tenantId: string, loginSession: LoginSession, hookId?: string): Promise<void>;
+/**
+ * Mark a login session as returning from a hook
+ * This should be called when the user returns via /u/continue after a form/page redirect
+ *
+ * Uses optimistic concurrency: re-fetches current state to prevent stale overwrites
+ */
+export declare function completeLoginSessionHook(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, tenantId: string, loginSession: LoginSession): Promise<void>;
+/**
+ * Mark a login session as completed (tokens issued)
+ * This should be called when tokens are successfully returned to the client
+ *
+ * Uses optimistic concurrency: re-fetches current state to prevent stale overwrites
+ */
+export declare function completeLoginSession(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, tenantId: string, loginSession: LoginSession, auth_connection?: string): Promise<void>;
+/**
+ * Start a continuation - user is redirected to an account page (change-email, etc.)
+ * This transitions to AWAITING_CONTINUATION and stores the allowed scope and return URL
+ *
+ * Uses optimistic concurrency: re-fetches current state to prevent stale overwrites
+ */
+export declare function startLoginSessionContinuation(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, tenantId: string, loginSession: LoginSession, scope: string[], returnUrl: string): Promise<void>;
+/**
+ * Complete a continuation - user finished the account page action
+ * This transitions back to AUTHENTICATED so the login flow can continue
+ *
+ * Uses optimistic concurrency: re-fetches current state to prevent stale overwrites
+ */
+export declare function completeLoginSessionContinuation(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, tenantId: string, loginSession: LoginSession): Promise<string | undefined>;
+/**
+ * Check if a login session allows access to a given scope during continuation
+ */
+export declare function hasValidContinuationScope(loginSession: LoginSession, requiredScope: string): boolean;
+export interface CreateAuthResponseParams {
+    authParams: AuthParams;
+    client: EnrichedClient;
+    user: User;
+    loginSession?: LoginSession;
+    /**
+     * An existing session ID to link to the login session instead of creating a new one.
+     * Use this when the user already has a valid session (e.g., from a cookie) that should be reused.
+     *
+     * If not provided and loginSession is in PENDING state, a new session will be created.
+     * If provided, this session will be linked and the state will transition to AUTHENTICATED.
+     */
+    existingSessionIdToLink?: string;
+    refreshToken?: string;
+    ticketAuth?: boolean;
+    authStrategy?: {
+        strategy: string;
+        strategy_type: string;
+    };
+    /** The connection name used for authentication (e.g., "email", "google-oauth2") */
+    authConnection?: string;
+    skipHooks?: boolean;
+    organization?: {
+        id: string;
+        name: string;
+    };
+    impersonatingUser?: User;
+}
+export declare function createFrontChannelAuthResponse(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, params: CreateAuthResponseParams): Promise<Response>;
+export declare function completeLogin(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, params: Omit<CreateAuthTokensParams, "client"> & {
+    client: EnrichedClient;
+    responseType?: AuthorizationResponseType;
+}): Promise<TokenResponse | {
+    code: string;
+    state?: string;
+} | (TokenResponse & {
+    code: string;
+}) | Response>;

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

@@ -0,0 +1,17 @@
+import { Context } from "hono";
+import { AuthParams } from "@authhero/adapter-interfaces";
+import { EnrichedClient } from "../helpers/client";
+import { Bindings, Variables } from "../types";
+export declare function connectionAuth(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, client: EnrichedClient, connectionName: string, authParams: AuthParams): Promise<Response>;
+interface SocialAuthCallbackParams {
+    code: string;
+    state: string;
+}
+export declare function connectionCallback(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, { code, state }: SocialAuthCallbackParams): Promise<Response>;
+export {};

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

@@ -0,0 +1,49 @@
+import { Context } from "hono";
+import { LoginSession, AuthenticationMethod } from "@authhero/adapter-interfaces";
+import { Bindings, Variables } from "../types";
+import { EnrichedClient } from "../helpers/client";
+export type MfaCheckResult = {
+    required: false;
+} | {
+    required: true;
+    enrolled: false;
+} | {
+    required: true;
+    enrolled: true;
+    enrollment: AuthenticationMethod;
+    allEnrollments: AuthenticationMethod[];
+};
+/**
+ * Check if MFA is required for a user based on tenant policy and enrollment status.
+ */
+export declare function checkMfaRequired(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, tenantId: string, userId: string): Promise<MfaCheckResult>;
+/**
+ * Send an MFA OTP code via SMS using the tenant's configured SMS provider.
+ */
+export declare function sendMfaOtp(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, client: EnrichedClient, loginSession: LoginSession, phoneNumber: string): Promise<void>;
+/**
+ * Verify an MFA OTP code against the stored code.
+ * Returns true if valid, false otherwise.
+ */
+export declare function verifyMfaOtp(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, tenantId: string, loginSessionId: string, submittedCode: string): Promise<boolean>;
+/**
+ * Generate a random TOTP secret and return it as a base32-encoded string.
+ */
+export declare function generateTotpSecret(): string;
+/**
+ * Create an otpauth:// URI for enrolling in TOTP (used for QR code generation).
+ */
+export declare function createTotpUri(issuer: string, accountName: string, secretBase32: string): string;
+/**
+ * Verify a TOTP code against a base32-encoded secret.
+ */
+export declare function verifyTotpCode(secretBase32: string, code: string): Promise<boolean>;

package/dist/types/authentication-flows/passkey-enrollment.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Passkey progressive enrollment — nudge logic
+ *
+ * Decides whether to show a passkey enrollment nudge to the user after login.
+ * Mirrors Auth0's progressive enrollment behaviour:
+ *   1. Connection must have progressive_enrollment_enabled + passkey enabled
+ *   2. User must have zero confirmed passkey/webauthn enrollments
+ *   3. User hasn't permanently opted out
+ *   4. User hasn't snoozed within the last 30 days
+ */
+import { Context } from "hono";
+import { Bindings, Variables } from "../types";
+export interface PasskeyNudgeResult {
+    show: boolean;
+}
+export declare function checkPasskeyNudgeRequired(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, tenantId: string, userId: string, connectionName?: string): Promise<PasskeyNudgeResult>;

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

@@ -0,0 +1,24 @@
+import { Context } from "hono";
+import { AuthParams, LoginSession } from "@authhero/adapter-interfaces";
+import { EnrichedClient } from "../helpers/client";
+import { Bindings, GrantFlowUserResult, Variables } from "../types";
+export declare function passwordGrant(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, client: EnrichedClient, authParams: AuthParams & {
+    password: string;
+}, loginSession?: LoginSession, realm?: string): Promise<GrantFlowUserResult>;
+export declare function loginWithPassword(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, client: EnrichedClient, authParams: AuthParams & {
+    password: string;
+}, loginSession?: LoginSession, ticketAuth?: boolean, realm?: string): Promise<Response>;
+export declare function changePassword(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, client: EnrichedClient, userId: string, newPassword: string, connectionName: string): Promise<void>;
+export declare function requestPasswordReset(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, client: EnrichedClient, email: string, state: string, verification_method?: "link" | "code"): Promise<void>;