@aura-stack/auth 0.4.0-rc.5 → 0.5.0

package/dist/index-_aXtxb_s.d.ts

@@ -0,0 +1,1377 @@
+import * as zod from 'zod';
+import { z } from 'zod';
+import { OAuthAuthorizationErrorResponse, OAuthAccessTokenErrorResponse, OAuthEnvSchema } from './schemas.js';
+import * as _aura_stack_jose from '@aura-stack/jose';
+import { DecodedJWTPayloadOptions, TypedJWTPayload, JWTVerifyOptions } from '@aura-stack/jose';
+import * as _aura_stack_jose_jose from '@aura-stack/jose/jose';
+import { JWTPayload } from '@aura-stack/jose/jose';
+import '@aura-stack/jose/crypto';
+import { SerializeOptions } from '@aura-stack/router/cookie';
+import { LiteralUnion, Prettify } from './@types/utility.js';
+import * as jose from 'jose';
+import * as _aura_stack_router from '@aura-stack/router';
+import { GlobalContext, ClientOptions } from '@aura-stack/router';
+import * as zod_v4_core from 'zod/v4/core';
+
+/**
+ * Log message definitions organized by category.
+ * Each message includes facility, severity, msgId, and default message.
+ */
+declare const logMessages: {
+    readonly ROUTER_INTERNAL_ERROR: {
+        readonly facility: 10;
+        readonly severity: "error";
+        readonly msgId: "ROUTER_INTERNAL_ERROR";
+        readonly message: "Unhandled router error while processing the request";
+    };
+    readonly INVALID_REQUEST: {
+        readonly facility: 10;
+        readonly severity: "warning";
+        readonly msgId: "INVALID_REQUEST";
+        readonly message: "Request validation failed against the expected schema";
+    };
+    readonly SERVER_ERROR: {
+        readonly facility: 10;
+        readonly severity: "error";
+        readonly msgId: "SERVER_ERROR";
+        readonly message: "Unexpected internal server error during authentication";
+    };
+    readonly OAUTH_PROTOCOL_ERROR: {
+        readonly facility: 10;
+        readonly severity: "warning";
+        readonly msgId: "OAUTH_PROTOCOL_ERROR";
+        readonly message: "OAuth provider returned an invalid or unexpected protocol response";
+    };
+    readonly OAUTH_AUTHORIZATION_ERROR: {
+        readonly facility: 10;
+        readonly severity: "error";
+        readonly msgId: "OAUTH_AUTHORIZATION_ERROR";
+        readonly message: "OAuth authorization request was rejected or failed";
+    };
+    readonly INVALID_OAUTH_CONFIGURATION: {
+        readonly facility: 10;
+        readonly severity: "error";
+        readonly msgId: "INVALID_OAUTH_CONFIGURATION";
+        readonly message: "The OAuth provider configuration is invalid or incomplete";
+    };
+    readonly OAUTH_ACCESS_TOKEN_REQUEST_INITIATED: {
+        readonly facility: 10;
+        readonly severity: "debug";
+        readonly msgId: "OAUTH_ACCESS_TOKEN_REQUEST_INITIATED";
+        readonly message: "Starting OAuth access token request to the provider";
+    };
+    readonly INVALID_OAUTH_ACCESS_TOKEN_RESPONSE: {
+        readonly facility: 10;
+        readonly severity: "error";
+        readonly msgId: "INVALID_OAUTH_ACCESS_TOKEN_RESPONSE";
+        readonly message: "OAuth access token endpoint returned an invalid or malformed response";
+    };
+    readonly OAUTH_ACCESS_TOKEN_ERROR: {
+        readonly facility: 10;
+        readonly severity: "error";
+        readonly msgId: "OAUTH_ACCESS_TOKEN_ERROR";
+        readonly message: "OAuth access token endpoint returned an error response";
+    };
+    readonly OAUTH_ACCESS_TOKEN_SUCCESS: {
+        readonly facility: 10;
+        readonly severity: "info";
+        readonly msgId: "OAUTH_ACCESS_TOKEN_SUCCESS";
+        readonly message: "Successfully retrieved OAuth access token from the provider";
+    };
+    readonly OAUTH_ACCESS_TOKEN_REQUEST_FAILED: {
+        readonly facility: 10;
+        readonly severity: "error";
+        readonly msgId: "OAUTH_ACCESS_TOKEN_REQUEST_FAILED";
+        readonly message: "Network or server error while requesting OAuth access token";
+    };
+    readonly OAUTH_USERINFO_REQUEST_INITIATED: {
+        readonly facility: 10;
+        readonly severity: "debug";
+        readonly msgId: "OAUTH_USERINFO_REQUEST_INITIATED";
+        readonly message: "Starting OAuth userinfo request to the provider";
+    };
+    readonly OAUTH_USERINFO_INVALID_RESPONSE: {
+        readonly facility: 10;
+        readonly severity: "error";
+        readonly msgId: "OAUTH_USERINFO_INVALID_RESPONSE";
+        readonly message: "OAuth userinfo endpoint returned an invalid or malformed response";
+    };
+    readonly OAUTH_USERINFO_ERROR: {
+        readonly facility: 10;
+        readonly severity: "error";
+        readonly msgId: "OAUTH_USERINFO_ERROR";
+        readonly message: "OAuth userinfo endpoint returned an error response";
+    };
+    readonly OAUTH_USERINFO_SUCCESS: {
+        readonly facility: 10;
+        readonly severity: "info";
+        readonly msgId: "OAUTH_USERINFO_SUCCESS";
+        readonly message: "Successfully retrieved user information from the OAuth provider";
+    };
+    readonly OAUTH_USERINFO_REQUEST_FAILED: {
+        readonly facility: 10;
+        readonly severity: "error";
+        readonly msgId: "OAUTH_USERINFO_REQUEST_FAILED";
+        readonly message: "Network or server error while requesting user information from the OAuth provider";
+    };
+    readonly OAUTH_CALLBACK_SUCCESS: {
+        readonly facility: 4;
+        readonly severity: "info";
+        readonly msgId: "OAUTH_CALLBACK_SUCCESS";
+        readonly message: "OAuth callback completed successfully and session was created";
+    };
+    readonly MISMATCHING_STATE: {
+        readonly facility: 4;
+        readonly severity: "critical";
+        readonly msgId: "MISMATCHING_STATE";
+        readonly message: "OAuth response state parameter does not match the stored state value";
+    };
+    readonly POTENTIAL_OPEN_REDIRECT_ATTACK_DETECTED: {
+        readonly facility: 4;
+        readonly severity: "critical";
+        readonly msgId: "POTENTIAL_OPEN_REDIRECT_ATTACK_DETECTED";
+        readonly message: "Blocked redirect to untrusted or external URL (potential open redirect attack)";
+    };
+    readonly OPEN_REDIRECT_ATTACK: {
+        readonly facility: 4;
+        readonly severity: "warning";
+        readonly msgId: "OPEN_REDIRECT_ATTACK";
+        readonly message: "Detected redirect target that does not match the trusted origin";
+    };
+    readonly SESSION_TOKEN_MISSING: {
+        readonly facility: 4;
+        readonly severity: "warning";
+        readonly msgId: "SESSION_TOKEN_MISSING";
+        readonly message: "Session cookie is missing from the request";
+    };
+    readonly CSRF_TOKEN_MISSING: {
+        readonly facility: 4;
+        readonly severity: "warning";
+        readonly msgId: "CSRF_TOKEN_MISSING";
+        readonly message: "CSRF token cookie is missing from the request";
+    };
+    readonly CSRF_HEADER_MISSING: {
+        readonly facility: 4;
+        readonly severity: "warning";
+        readonly msgId: "CSRF_HEADER_MISSING";
+        readonly message: "CSRF header is missing from the request";
+    };
+    readonly CSRF_TOKEN_INVALID: {
+        readonly facility: 4;
+        readonly severity: "error";
+        readonly msgId: "CSRF_TOKEN_INVALID";
+        readonly message: "CSRF token verification failed or token is invalid";
+    };
+    readonly SIGN_IN_INITIATED: {
+        readonly facility: 4;
+        readonly severity: "info";
+        readonly msgId: "SIGN_IN_INITIATED";
+        readonly message: "Starting OAuth sign-in flow for the selected provider";
+    };
+    readonly SIGN_OUT_ATTEMPT: {
+        readonly facility: 4;
+        readonly severity: "debug";
+        readonly msgId: "SIGN_OUT_ATTEMPT";
+        readonly message: "Received sign-out request from client";
+    };
+    readonly SIGN_OUT_CSRF_VERIFIED: {
+        readonly facility: 4;
+        readonly severity: "info";
+        readonly msgId: "SIGN_OUT_CSRF_VERIFIED";
+        readonly message: "CSRF token was successfully verified during sign-out";
+    };
+    readonly SIGN_OUT_SUCCESS: {
+        readonly facility: 4;
+        readonly severity: "info";
+        readonly msgId: "SIGN_OUT_SUCCESS";
+        readonly message: "User session was cleared and sign-out completed successfully";
+    };
+    readonly SIGN_OUT_REDIRECT: {
+        readonly facility: 4;
+        readonly severity: "debug";
+        readonly msgId: "SIGN_OUT_REDIRECT";
+        readonly message: "Redirecting client after successful sign-out";
+    };
+    readonly AUTH_SESSION_VALID: {
+        readonly facility: 4;
+        readonly severity: "info";
+        readonly msgId: "AUTH_SESSION_VALID";
+        readonly message: "Session token is valid and user session was returned";
+    };
+    readonly AUTH_SESSION_INVALID: {
+        readonly facility: 4;
+        readonly severity: "notice";
+        readonly msgId: "AUTH_SESSION_INVALID";
+        readonly message: "Session token is missing, expired, or invalid";
+    };
+    readonly INVALID_JWT_TOKEN: {
+        readonly facility: 4;
+        readonly severity: "warning";
+        readonly msgId: "INVALID_JWT_TOKEN";
+        readonly message: "JWT session token failed validation during sign-out";
+    };
+    readonly CSRF_TOKEN_REQUESTED: {
+        readonly facility: 4;
+        readonly severity: "debug";
+        readonly msgId: "CSRF_TOKEN_REQUESTED";
+        readonly message: "Client requested a CSRF token";
+    };
+    readonly CSRF_TOKEN_ISSUED: {
+        readonly facility: 4;
+        readonly severity: "debug";
+        readonly msgId: "CSRF_TOKEN_ISSUED";
+        readonly message: "Issued a new CSRF token to the client";
+    };
+    readonly INVALID_URL: {
+        readonly facility: 10;
+        readonly severity: "error";
+        readonly msgId: "INVALID_URL";
+        readonly message: "Derived origin URL is invalid or malformed";
+    };
+    readonly COOKIE_HTTPONLY_DISABLED: {
+        readonly facility: 10;
+        readonly severity: "critical";
+        readonly msgId: "COOKIE_HTTPONLY_DISABLED";
+        readonly message: "Cookie is configured without HttpOnly. This allows JavaScript access via document.cookie and increases XSS exposure.";
+    };
+    readonly COOKIE_WILDCARD_DOMAIN: {
+        readonly facility: 10;
+        readonly severity: "critical";
+        readonly msgId: "COOKIE_WILDCARD_DOMAIN";
+        readonly message: "Cookie 'Domain' is set to a wildcard, which is insecure and should be avoided.";
+    };
+    readonly COOKIE_SECURE_DISABLED: {
+        readonly facility: 10;
+        readonly severity: "warning";
+        readonly msgId: "COOKIE_SECURE_DISABLED";
+        readonly message: "Cookie is configured with 'Secure' but the request is not HTTPS. The 'Secure' attribute will be ignored by the browser.";
+    };
+    readonly COOKIE_SAMESITE_NONE_WITHOUT_SECURE: {
+        readonly facility: 10;
+        readonly severity: "warning";
+        readonly msgId: "COOKIE_SAMESITE_NONE_WITHOUT_SECURE";
+        readonly message: "Cookie uses SameSite=None without Secure. Falling back to SameSite=Lax for safer defaults.";
+    };
+    readonly COOKIE_INSECURE_IN_PRODUCTION: {
+        readonly facility: 10;
+        readonly severity: "critical";
+        readonly msgId: "COOKIE_INSECURE_IN_PRODUCTION";
+        readonly message: "Cookies are being served over an insecure connection in production, which is a serious security risk.";
+    };
+    readonly COOKIE_HOST_STRATEGY_INSECURE: {
+        readonly facility: 10;
+        readonly severity: "critical";
+        readonly msgId: "COOKIE_HOST_STRATEGY_INSECURE";
+        readonly message: "__Host- cookies require a secure HTTPS context. Falling back to standard cookie settings.";
+    };
+    readonly UNTRUSTED_ORIGIN: {
+        readonly facility: 10;
+        readonly severity: "error";
+        readonly msgId: "UNTRUSTED_ORIGIN";
+        readonly message: "The constructed origin URL is not trusted.";
+    };
+};
+declare const createLogEntry: <T extends keyof typeof logMessages>(key: T, overrides?: Partial<SyslogOptions>) => SyslogOptions;
+declare const createSyslogMessage: (options: SyslogOptions) => string;
+declare const createLogger: (logger?: Required<Logger>) => InternalLogger | undefined;
+/**
+ * Creates the logger instance based on the provided configuration and environment variables.
+ * Priority: config.logger, LOG_LEVEL env, DEBUG env and defaults to undefined if logging is not enabled.
+ *
+ */
+declare const createProxyLogger: (config?: AuthConfig) => InternalLogger | undefined;
+
+/**
+ * Creates the JOSE instance used for signing and verifying tokens. It derives keys
+ * for session tokens and CSRF tokens. For security and determinism, it's required
+ * to set a salt value in `AURA_AUTH_SALT` or `AUTH_SALT` env.
+ *
+ * @param secret the base secret for key derivation
+ * @returns jose instance with methods for encoding/decoding JWTs and signing/verifying JWSs
+ */
+declare const createJoseInstance: (secret?: string) => {
+    decodeJWT: (token: string, options?: DecodedJWTPayloadOptions) => Promise<TypedJWTPayload<User>>;
+    encodeJWT: (payload: TypedJWTPayload<Partial<User>>) => Promise<string>;
+    signJWS: (payload: TypedJWTPayload<Partial<_aura_stack_jose_jose.JWTPayload>>) => Promise<string>;
+    verifyJWS: (payload: string, options?: JWTVerifyOptions | undefined) => Promise<_aura_stack_jose_jose.JWTPayload>;
+    encryptJWE: (payload: string, options?: _aura_stack_jose.EncryptOptions | undefined) => Promise<string>;
+    decryptJWE: (payload: string, options?: _aura_stack_jose.JWTDecryptOptions | undefined) => Promise<string>;
+};
+declare const jwtVerificationOptions: JWTVerifyOptions;
+declare const decodeJWTOptions: DecodedJWTPayloadOptions;
+
+interface ExtendedProfile {
+    job_title: string;
+    organization: string;
+    department: string;
+    location: string;
+}
+interface AtlassianProfile {
+    account_id: string;
+    account_type: string;
+    account_status: LiteralUnion<"active">;
+    email: string;
+    email_verified: boolean;
+    name: string;
+    picture: string;
+    nickname: string;
+    zoneinfo: string;
+    locale: string;
+    extended_profile: ExtendedProfile;
+    last_updated: string;
+    created_at: string;
+}
+/**
+ * @see [Atlassian - OAuth Apps](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/)
+ * @see [Atlassian - My Apps](https://developer.atlassian.com/console/myapps/)
+ * @see [Atlassian - Retrieve Authenticated User](https://developer.atlassian.com/cloud/jira/software/oauth-2-3lo-apps/#how-do-i-retrieve-the-public-profile-of-the-authenticated-user-)
+ */
+declare const atlassian: (options?: Partial<OAuthProviderCredentials<AtlassianProfile>>) => OAuthProviderCredentials<AtlassianProfile>;
+
+type AccountType = "basic" | "pro" | "business";
+interface Name {
+    given_name: string;
+    surname: string;
+    familiar_name: string;
+    display_name: string;
+    abbreviated_name: string;
+}
+interface RootInfo {
+    team: RootInfo;
+    user: RootInfo;
+}
+interface FullTeam {
+    id: string;
+    name: string;
+    sharing_policies: Record<string, unknown>;
+    office_addin_policy: unknown;
+    top_level_content_policy: unknown;
+}
+interface DropboxProfile {
+    account_id: string;
+    name: Name;
+    email: string;
+    email_verified: boolean;
+    disabled: boolean;
+    locale: string;
+    referral_link: string;
+    is_paired: boolean;
+    account_type: AccountType;
+    root_info: unknown;
+    profile_photo_url?: string;
+    country: string;
+    team?: unknown;
+    team_member_id?: string;
+}
+/**
+ * @see [Dropbox - OAuth Guide](https://developers.dropbox.com/oauth-guide)
+ * @see [Dropbox - API v2](https://www.dropbox.com/developers/documentation/http/documentation)
+ * @see [Dropbox - Get Current Account](https://www.dropbox.com/developers/documentation/http/documentation#users-get_current_account)
+ * @see [Dropbox - My Apps](https://www.dropbox.com/developers/apps)
+ * @see [Dropbox - Developer Guide](https://www.dropbox.com/developers/reference/developer-guide)
+ */
+declare const dropbox: (options?: Partial<OAuthProviderCredentials<DropboxProfile>>) => OAuthProviderCredentials<DropboxProfile>;
+
+interface Person {
+    email: string;
+}
+interface User$1 {
+    object: "user";
+    id: string;
+    name: string;
+    avatar_url: string | null;
+    type: "person";
+    person: Person;
+}
+interface Owner {
+    type: "user";
+    user: User$1;
+}
+interface Bot {
+    owner: Owner;
+}
+/**
+ * @see [Notion - Retrieve your token's bot user](https://developers.notion.com/reference/get-self)
+ */
+interface NotionProfile {
+    object: "user";
+    id: string;
+    name: string;
+    avatar_url: string | null;
+    type: "bot";
+    bot: Bot;
+}
+/**
+ * @see [Notion - Developer Documentation](https://developers.notion.com/)
+ * @see [Notion - Authorization](https://developers.notion.com/docs/authorization)
+ * @see [Notion - Authentication](https://developers.notion.com/reference/authentication)
+ * @see [Notion - Retrieve your token's bot user](https://developers.notion.com/reference/get-self)
+ */
+declare const notion: (options?: Partial<OAuthProviderCredentials<NotionProfile>>) => OAuthProviderCredentials<NotionProfile>;
+
+/**
+ * @see [Twitch - Get Users](https://dev.twitch.tv/docs/api/reference#get-users)
+ */
+interface TwitchProfile {
+    id: string;
+    login: string;
+    display_name: string;
+    type: string;
+    broadcaster_type: string;
+    description: string;
+    profile_image_url: string;
+    offline_image_url: string;
+    view_count: number;
+    email?: string;
+    created_at: string;
+}
+/**
+ * @see [Twitch - Get Started with the Twitch API](https://dev.twitch.tv/docs/api/get-started/)
+ * @see [Twitch - Authorization code grant flow](https://dev.twitch.tv/docs/authentication/getting-tokens-oauth/#authorization-code-grant-flow)
+ * @see [Twitch - Register Your App](https://dev.twitch.tv/docs/authentication/register-app)
+ * @see [Twitch - Setting up Two-Factor Authentication (2FA)](https://help.twitch.tv/s/article/two-factor-authentication?language=en_US)
+ * @see [Twitch - Security and Privacy](https://www.twitch.tv/settings/security)
+ * @see [Twitch - Get Users](https://dev.twitch.tv/docs/api/reference#get-users)
+ * @see [Twitch - Scopes](https://dev.twitch.tv/docs/authentication/scopes/)
+ */
+declare const twitch: (options?: Partial<OAuthProviderCredentials<TwitchProfile>>) => OAuthProviderCredentials<TwitchProfile>;
+
+/**
+ * @see [Pinterest - Get User Account](https://developers.pinterest.com/docs/api/v5/user_account-get)
+ */
+interface PinterestProfile {
+    account_type: LiteralUnion<"PINNER">;
+    id: string;
+    profile_image: string;
+    website_url: string;
+    username: string;
+    about: string;
+    business_name: string;
+    board_count: number;
+    pin_count: number;
+    follower_count: number;
+    following_count: number;
+    monthly_views: number;
+}
+/**
+ * @see [Pinterest - Connect App](https://developers.pinterest.com/docs/getting-started/connect-app/)
+ * @see [Pinterest - My Apps](https://developers.pinterest.com/apps/)
+ * @see [Pinterest - Get User Account](https://developers.pinterest.com/docs/api/v5/user_account-get)
+ */
+declare const pinterest: (options?: Partial<OAuthProviderCredentials<PinterestProfile>>) => OAuthProviderCredentials<PinterestProfile>;
+
+interface Login {
+    email: string;
+    avatar: string | null;
+    login_id: number;
+    login_name: string;
+    login_email: string;
+}
+/**
+ * @see [Mailchimp - API Root](https://mailchimp.com/developer/marketing/api/authentication/)
+ */
+interface MailchimpProfile {
+    dc: string;
+    role: string;
+    accountname: string;
+    user_id: string;
+    login: Login;
+    login_url: string;
+    api_endpoint: string;
+}
+/**
+ * Mailchimp OAuth Provider
+ * @see [Mailchimp - Marketing API](https://mailchimp.com/developer/marketing/api/)
+ * @see [Mailchimp - Apps](https://us1.admin.mailchimp.com/account/oauth2/)
+ * @see [Mailchimp - Create an Application](https://mailchimp.com/developer/marketing/guides/access-user-data-oauth-2/#register-your-app)
+ * @see [Mailchimp - OAuth 2.0 Docs](https://mailchimp.com/developer/marketing/guides/access-user-data-oauth-2/)
+ * @see [Mailchimp - API Root](https://mailchimp.com/developer/marketing/api/root/)
+ */
+declare const mailchimp: (options?: Partial<OAuthProviderCredentials<MailchimpProfile>>) => OAuthProviderCredentials<MailchimpProfile>;
+
+/**
+ * @see [Strava - SummaryClub](https://developers.strava.com/docs/reference/#api-models-SummaryClub)
+ */
+interface SummaryClub {
+    id: number;
+    resource_state: number;
+    name: string;
+    profile_medium: string;
+    cover_photo: string;
+    cover_photo_small: string;
+    sport_type: "cycling" | "running" | "triathlon" | "other";
+    activity_types: string[];
+    city: string;
+    state: string;
+    country: string;
+    private: boolean;
+    member_count: number;
+    featured: boolean;
+    verified: boolean;
+    url: string;
+}
+/**
+ * @see [Strava - SummaryGear](https://developers.strava.com/docs/reference/#api-models-SummaryGear)
+ */
+interface SummaryGear {
+    id: string;
+    resource_state: number;
+    primary: boolean;
+    name: string;
+    distance: number;
+}
+/**
+ * @see [Strava - DetailedAthlete](https://developers.strava.com/docs/reference/#api-models-DetailedAthlete)
+ */
+interface StravaProfile {
+    id: number;
+    resource_state: number;
+    firstname: string;
+    lastname: string;
+    bio: string | null;
+    profile: string;
+    profile_medium: string;
+    city: string;
+    state: string;
+    country: string;
+    sex: string;
+    premium: boolean;
+    summit: boolean;
+    created_at: Date;
+    updated_at: Date;
+    badge_type_id: number;
+    weight: number;
+    friend: null;
+    follower: null;
+    follower_count: number;
+    friend_count: number;
+    measurement_preference: string;
+    ftp: number;
+    clubs: SummaryClub[];
+    bikes: SummaryGear[];
+    shoes: SummaryGear[];
+}
+/**
+ * Strava OAuth Provider
+ * @see [Strava - Getting Started with the Strava API](https://developers.strava.com/docs/getting-started/)
+ * @see [Strava - My Applications](https://www.strava.com/settings/api)
+ * @see [Strava - Authentication](https://developers.strava.com/docs/authentication/)
+ * @see [Strava - API Application](https://www.strava.com/settings/api)
+ * @see [Strava - API Reference](https://developers.strava.com/docs/reference/)
+ */
+declare const strava: (options?: Partial<OAuthProviderCredentials<StravaProfile>>) => OAuthProviderCredentials<StravaProfile>;
+
+/**
+ * @see [X - Get my User](https://docs.x.com/x-api/users/get-my-user)
+ */
+interface XProfile {
+    data: {
+        id: string;
+        name: string;
+        username: string;
+        profile_image_url: string;
+    };
+}
+/**
+ * X (Twitter) OAuth Provider
+ * @see [X - Developer Portal](https://developer.x.com/en/portal/projects-and-apps)
+ * @see [X - Get my User](https://docs.x.com/x-api/users/get-my-user)
+ * @see [X - OAuth 2.0 Authorization Code Flow with PKCE](https://docs.x.com/fundamentals/authentication/oauth-2-0/authorization-code)
+ * @see [X - OAuth 2.0 Scopes](https://docs.x.com/fundamentals/authentication/oauth-2-0/authorization-code#scopes)
+ * @see [X - OAuth 2.0 Bearer Token](https://docs.x.com/fundamentals/authentication/oauth-2-0/application-only)
+ */
+declare const x: (options?: Partial<OAuthProviderCredentials<XProfile>>) => OAuthProviderCredentials<XProfile>;
+
+interface SpotifyImage {
+    url: string;
+    height: number;
+    width: number;
+}
+/**
+ * @see [Spotify - User Object](https://developer.spotify.com/documentation/web-api/reference/object-model/#user-object-private)
+ */
+interface SpotifyProfile {
+    id: string;
+    display_name: string;
+    email: string;
+    type: string;
+    uri: string;
+    country: string;
+    href: string;
+    images: SpotifyImage[];
+    product: string;
+    explicit_content: {
+        filter_enabled: boolean;
+        filter_locked: boolean;
+    };
+    external_urls: {
+        spotify: string;
+    };
+    followers: {
+        href: string;
+        total: number;
+    };
+}
+/**
+ * Spotify OAuth Provider
+ *
+ * @see [Spotify - Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
+ * @see [Spotify - Getting started with Web API](https://developer.spotify.com/documentation/web-api/tutorials/getting-started)
+ * @see [Spotify - Get Current User's Profile](https://developer.spotify.com/documentation/web-api/reference/get-current-users-profile)
+ * @see [Spotify - Scopes](https://developer.spotify.com/documentation/web-api/concepts/scopes)
+ * @see [Spotify - Redirect URIs](https://developer.spotify.com/documentation/web-api/concepts/redirect_uri)
+ */
+declare const spotify: (options?: Partial<OAuthProviderCredentials<SpotifyProfile>>) => OAuthProviderCredentials<SpotifyProfile>;
+
+/**
+ * @see [GitLab - User Structure](https://docs.gitlab.com/ee/api/users.html#external-user-structure)
+ */
+interface GitLabProfile {
+    id: number;
+    username: string;
+    email: string;
+    name: string;
+    state: string;
+    locked: boolean;
+    avatar_url: string;
+    web_url: string;
+    created_at: string;
+    bio: string;
+    location: string | null;
+    public_email: string;
+    linkedin: string;
+    twitter: string;
+    discord: string;
+    github: string;
+    website_url: string;
+    organization: string;
+    job_title: string;
+    pronouns: string;
+    bot: boolean;
+    work_information: string | null;
+    followers: number;
+    following: number;
+    local_time: string;
+    last_sign_in_at: string;
+    confirmed_at: string;
+    theme_id: number;
+    last_activity_on: string;
+    color_scheme_id: number;
+    projects_limit: number;
+    current_sign_in_at: string;
+    identities: {
+        provider: string;
+        extern_uid: string;
+        saml_provider_id: number | null;
+    }[];
+    can_create_group: boolean;
+    can_create_project: boolean;
+    two_factor_enabled: boolean;
+    external: boolean;
+    private_profile: boolean;
+    commit_email: string;
+    preferred_language: string;
+    shared_runners_minutes_limit: number | null;
+    extra_shared_runners_minutes_limit: number | null;
+    scim_identities: unknown[];
+}
+/**
+ * GitLab OAuth Provider
+ *
+ * @see [GitLab - Applications](https://gitlab.com/-/user_settings/applications)
+ * @see [GitLab - OAuth 2.0 identify provider API](https://docs.gitlab.com/api/oauth2/)
+ * @see [GitLab - Scopes](https://docs.gitlab.com/integration/oauth_provider/#view-all-authorized-applications)
+ * @see [GitLab - Get current user](https://docs.gitlab.com/api/users/#get-the-current-user)
+ */
+declare const gitlab: (options?: Partial<OAuthProviderCredentials<GitLabProfile>>) => OAuthProviderCredentials<GitLabProfile>;
+
+/**
+ * @see [Discord - Nameplate Object](https://discord.com/developers/docs/resources/user#nameplate-nameplate-structure)
+ */
+interface Nameplate {
+    sku_id: string;
+    asset: string;
+    label: string;
+    palette: string;
+}
+/**
+ * The `snowflake` type is a string type. The attributes defined with this type are:
+ * - `id`: The unique identifier for the object.
+ * - `primary_guild.identity_guild_id`: The unique identifier for the guild.
+ * - `avatar_decoration_data.sku_id`: The unique identifier for the SKU.
+ *
+ * @see [Discord - User Object](https://discord.com/developers/docs/resources/user#user-object)
+ */
+interface DiscordProfile {
+    id: string;
+    username: string;
+    discriminator: string;
+    global_name: string | null;
+    avatar: string | null;
+    bot?: boolean;
+    system?: boolean;
+    mfa_enabled?: boolean;
+    banner?: string | null;
+    accent_color?: number | null;
+    locale?: string;
+    verified?: boolean;
+    email?: string | null;
+    flags?: number;
+    premium_type?: number;
+    public_flags?: number;
+    avatar_decoration_data?: {
+        asset: string;
+        sku_id: string;
+    };
+    collections?: Record<string, Nameplate>;
+    primary_guild?: {
+        identity_guild_id: string;
+        identity_enabled: boolean | null;
+        tag: string | null;
+        badge: string | null;
+    };
+}
+/**
+ * Discord OAuth Provider
+ *
+ * @see [Discord - Applications](https://discord.com/developers/applications)
+ * @see [Discord - OAuth2](https://discord.com/developers/docs/topics/oauth2)
+ * @see [Discord - Get Current User](https://discord.com/developers/docs/resources/user#get-current-user)
+ * @see [Discord - User Object](https://discord.com/developers/docs/resources/user#user-object)
+ * @see [Discord - OAuth2 Scopes](https://discord.com/developers/docs/topics/oauth2#shared-resources-oauth2-scopes)
+ * @see [Discord - Image Formatting](https://discord.com/developers/docs/reference#image-formatting)
+ * @see [Discord - Display Names](https://discord.com/developers/docs/change-log#display-names)
+ */
+declare const discord: (options?: Partial<OAuthProviderCredentials<DiscordProfile>>) => OAuthProviderCredentials<DiscordProfile>;
+
+/**
+ * @see [Figma API - Users](https://developers.figma.com/docs/rest-api/users-types/)
+ */
+interface FigmaProfile {
+    id: string;
+    handle: string;
+    img_url: string;
+    email: string;
+}
+/**
+ * Figma OAuth Provider
+ * @see [Figma - REST API Introduction](https://developers.figma.com/docs/rest-api/)
+ * @see [Figma - OAuth App](https://www.figma.com/developers/apps/)
+ * @see [Figma - Create an OAuth App](https://developers.figma.com/docs/rest-api/authentication/#create-an-oauth-app)
+ * @see [Figma - OAuth Scopes](https://developers.figma.com/docs/rest-api/scopes/)
+ */
+declare const figma: (options?: Partial<OAuthProviderCredentials<FigmaProfile>>) => OAuthProviderCredentials<FigmaProfile>;
+
+/**
+ * @see [Get current user](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-users/#api-user-get)
+ */
+interface BitbucketProfile {
+    display_name: string;
+    links: Record<LiteralUnion<"self" | "avatar" | "repositories" | "snippets" | "html" | "hooks">, {
+        href?: string;
+    }>;
+    created_on: string;
+    type: string;
+    uuid: string;
+    has_2fa_enabled: boolean;
+    username: string;
+    nickname: string;
+    is_staff: boolean;
+    account_id: string;
+    account_status: LiteralUnion<"active" | "inactive" | "closed">;
+    location: string | null;
+}
+/**
+ * Bitbucket OAuth Provider
+ *
+ * @see [Bitbucket - Official App](https://bitbucket.org/)
+ * @see [Bitbucket - Workspaces](https://bitbucket.org/account/workspaces/)
+ * @see [Bitbucket - Workspace Settings](https://bitbucket.org/{workspace-name}/workspace/settings/)
+ * @see [Bitbucket - OAuth 2.0](https://developer.atlassian.com/cloud/bitbucket/oauth-2/)
+ * @see [Bitbucket - Use OAuth on Bitbucket Cloud](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/)
+ * @see [Bitbucket - Cloud REST API](https://developer.atlassian.com/cloud/bitbucket/rest/intro/)
+ * @see [Bitbucket - User Endpoint](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-users/#api-users-endpoint)
+ */
+declare const bitbucket: (options?: Partial<OAuthProviderCredentials<BitbucketProfile>>) => OAuthProviderCredentials<BitbucketProfile>;
+
+/**
+ * @see [Get the authenticated user](https://docs.github.com/en/rest/users/users?apiVersion=2022-11-28#get-the-authenticated-user)
+ */
+interface GitHubProfile {
+    login: string;
+    id: number;
+    user_view_type: string;
+    node_id: string;
+    avatar_url: string;
+    gravatar_id: string | null;
+    url: string;
+    html_url: string;
+    followers_url: string;
+    following_url: string;
+    gists_url: string;
+    starred_url: string;
+    subscriptions_url: string;
+    organizations_url: string;
+    repos_url: string;
+    events_url: string;
+    received_events_url: string;
+    type: string;
+    site_admin: boolean;
+    name: string | null;
+    company: string | null;
+    blog: string | null;
+    location: string | null;
+    email: string | null;
+    notification_email: string | null;
+    hireable: boolean | null;
+    bio: string | null;
+    twitter_username?: string | null;
+    public_repos: number;
+    public_gists: number;
+    followers: number;
+    following: number;
+    created_at: string;
+    updated_at: string;
+    private_gists?: number;
+    total_private_repos?: number;
+    owned_private_repos?: number;
+    disk_usage?: number;
+    collaborators?: number;
+    two_factor_authentication: boolean;
+    plan?: {
+        collaborators: number;
+        name: string;
+        space: number;
+        private_repos: number;
+    };
+}
+/**
+ * GitHub OAuth Provider
+ *
+ * @see [GitHub - Creating an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app)
+ * @see [GitHub - Authorizing OAuth Apps](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps)
+ * @see [GitHub - Configure your GitHub OAuth Apps](https://github.com/settings/developers)
+ * @see [Github - Get the authenticated user](https://docs.github.com/en/rest/users/users?apiVersion=2022-11-28#get-the-authenticated-user)
+ */
+declare const github: (options?: Partial<OAuthProviderCredentials<GitHubProfile>>) => OAuthProviderCredentials<GitHubProfile>;
+
+declare const builtInOAuthProviders: {
+    readonly github: (options?: Partial<OAuthProviderCredentials<GitHubProfile>>) => OAuthProviderCredentials<GitHubProfile>;
+    readonly bitbucket: (options?: Partial<OAuthProviderCredentials<BitbucketProfile>>) => OAuthProviderCredentials<BitbucketProfile>;
+    readonly figma: (options?: Partial<OAuthProviderCredentials<FigmaProfile>>) => OAuthProviderCredentials<FigmaProfile>;
+    readonly discord: (options?: Partial<OAuthProviderCredentials<DiscordProfile>>) => OAuthProviderCredentials<DiscordProfile>;
+    readonly gitlab: (options?: Partial<OAuthProviderCredentials<GitLabProfile>>) => OAuthProviderCredentials<GitLabProfile>;
+    readonly spotify: (options?: Partial<OAuthProviderCredentials<SpotifyProfile>>) => OAuthProviderCredentials<SpotifyProfile>;
+    readonly x: (options?: Partial<OAuthProviderCredentials<XProfile>>) => OAuthProviderCredentials<XProfile>;
+    readonly strava: (options?: Partial<OAuthProviderCredentials<StravaProfile>>) => OAuthProviderCredentials<StravaProfile>;
+    readonly mailchimp: (options?: Partial<OAuthProviderCredentials<MailchimpProfile>>) => OAuthProviderCredentials<MailchimpProfile>;
+    readonly pinterest: (options?: Partial<OAuthProviderCredentials<PinterestProfile>>) => OAuthProviderCredentials<PinterestProfile>;
+    readonly twitch: (options?: Partial<OAuthProviderCredentials<TwitchProfile>>) => OAuthProviderCredentials<TwitchProfile>;
+    readonly notion: (options?: Partial<OAuthProviderCredentials<NotionProfile>>) => OAuthProviderCredentials<NotionProfile>;
+    readonly dropbox: (options?: Partial<OAuthProviderCredentials<DropboxProfile>>) => OAuthProviderCredentials<DropboxProfile>;
+    readonly atlassian: (options?: Partial<OAuthProviderCredentials<AtlassianProfile>>) => OAuthProviderCredentials<AtlassianProfile>;
+};
+/**
+ * Constructs OAuth provider configurations from an array of provider names or configurations.
+ * It loads the client ID and client secret from environment variables if only the provider name is provided.
+ *
+ * @param oauth - Array of OAuth provider configurations or provider names to be defined from environment variables
+ * @returns A record of OAuth provider configurations
+ * @example
+ * // Using built-in provider with env variables
+ * createBuiltInOAuthProviders(["github"])
+ *
+ * // Using built-in provider with explicit credentials via factory
+ * createBuiltInOAuthProviders([github({ clientId: "...", clientSecret: "..." })])
+ */
+declare const createBuiltInOAuthProviders: (oauth?: (BuiltInOAuthProvider | OAuthProviderCredentials<any>)[]) => Record<LiteralUnion<BuiltInOAuthProvider>, OAuthProviderCredentials<any>>;
+type BuiltInOAuthProvider = keyof typeof builtInOAuthProviders;
+
+/**
+ * Creates the authentication instance with the configuration provided for OAuth provider.
+ * > NOTE: The handlers returned by this function should be used in the server to handle the authentication routes
+ * and within the `/auth` base path
+ *
+ * @param authConfig - Authentication configuration including OAuth provider
+ * @returns Authentication instance with handlers to be used in the server
+ * @example
+ * const auth = createAuth({
+ *   oauth: ["github", {
+ *     id: "custom-oauth",
+ *     name: "custom-oauth",
+ *     authorizationURL: "https://custom-oauth.com/oauth/authorize",
+ *     accessToken: "https://custom-oauth.com/oauth/token",
+ *     scope: "profile email",
+ *     responseType: "code",
+ *     userInfo: "https://custom-oauth.com/api/userinfo",
+ *     clientId: process.env.AURA_AUTH_CUSTOM_OAUTH_CLIENT_ID!,
+ *     clientSecret: process.env.AURA_AUTH_CUSTOM_OAUTH_CLIENT_SECRET!,
+ *   }]
+ * })
+ */
+declare const createAuthInstance: (authConfig: AuthConfig) => {
+    handlers: _aura_stack_router.Router<[_aura_stack_router.RouteEndpoint<"GET", "/signIn/:oauth", {
+        schemas?: {
+            params: zod.ZodObject<{
+                oauth: zod.ZodEnum<{
+                    [x: string & Record<never, never>]: string & Record<never, never>;
+                    github: "github";
+                    bitbucket: "bitbucket";
+                    figma: "figma";
+                    discord: "discord";
+                    gitlab: "gitlab";
+                    spotify: "spotify";
+                    x: "x";
+                    strava: "strava";
+                    mailchimp: "mailchimp";
+                    pinterest: "pinterest";
+                    twitch: "twitch";
+                    notion: "notion";
+                    dropbox: "dropbox";
+                    atlassian: "atlassian";
+                }>;
+            }, zod_v4_core.$strip>;
+            searchParams: zod.ZodObject<{
+                redirect: zod.ZodDefault<zod.ZodOptional<zod.ZodCodec<zod.ZodString, zod.ZodBoolean>>>;
+                redirectTo: zod.ZodOptional<zod.ZodString>;
+            }, zod_v4_core.$strip>;
+        } | undefined;
+    }>, _aura_stack_router.RouteEndpoint<"GET", "/callback/:oauth", {
+        schemas?: {
+            params: zod.ZodObject<{
+                oauth: zod.ZodEnum<{
+                    [x: string & Record<never, never>]: string & Record<never, never>;
+                    github: "github";
+                    bitbucket: "bitbucket";
+                    figma: "figma";
+                    discord: "discord";
+                    gitlab: "gitlab";
+                    spotify: "spotify";
+                    x: "x";
+                    strava: "strava";
+                    mailchimp: "mailchimp";
+                    pinterest: "pinterest";
+                    twitch: "twitch";
+                    notion: "notion";
+                    dropbox: "dropbox";
+                    atlassian: "atlassian";
+                }>;
+            }, zod_v4_core.$strip>;
+            searchParams: zod.ZodObject<{
+                code: zod.ZodString;
+                state: zod.ZodString;
+            }, zod_v4_core.$strip>;
+        } | undefined;
+    }>, _aura_stack_router.RouteEndpoint<"GET", "/session", {
+        schemas?: _aura_stack_router.EndpointSchemas | undefined;
+    }>, _aura_stack_router.RouteEndpoint<"POST", "/signOut", {
+        schemas?: {
+            searchParams: zod.ZodObject<{
+                token_type_hint: zod.ZodLiteral<"session_token">;
+                redirectTo: zod.ZodOptional<zod.ZodString>;
+            }, zod_v4_core.$strip>;
+        } | undefined;
+    }>, _aura_stack_router.RouteEndpoint<"GET", "/csrfToken", {
+        schemas?: _aura_stack_router.EndpointSchemas | undefined;
+    }>]>;
+    jose: {
+        decodeJWT: (token: string, options?: _aura_stack_jose.DecodedJWTPayloadOptions) => Promise<_aura_stack_jose.TypedJWTPayload<User>>;
+        encodeJWT: (payload: _aura_stack_jose.TypedJWTPayload<Partial<User>>) => Promise<string>;
+        signJWS: (payload: _aura_stack_jose.TypedJWTPayload<Partial<jose.JWTPayload>>) => Promise<string>;
+        verifyJWS: (payload: string, options?: jose.JWTVerifyOptions | undefined) => Promise<jose.JWTPayload>;
+        encryptJWE: (payload: string, options?: _aura_stack_jose.EncryptOptions | undefined) => Promise<string>;
+        decryptJWE: (payload: string, options?: jose.JWTDecryptOptions | undefined) => Promise<string>;
+    };
+    api: {
+        getSession: (options: GetSessionAPIOptions) => Promise<SessionResponse>;
+        signIn: <Redirect extends boolean = true>(oauth: LiteralUnion<BuiltInOAuthProvider>, options?: SignInAPIOptions<Redirect>) => Promise<SignInReturn<Redirect>>;
+        signOut: (options: SignOutAPIOptions) => Promise<Response>;
+    };
+};
+declare const createAuth: (config: AuthConfig) => AuthInstance;
+
+declare const createAuthAPI: (ctx: GlobalContext) => {
+    getSession: (options: GetSessionAPIOptions) => Promise<SessionResponse>;
+    signIn: <Redirect extends boolean = true>(oauth: LiteralUnion<BuiltInOAuthProvider>, options?: SignInAPIOptions<Redirect>) => Promise<SignInReturn<Redirect>>;
+    signOut: (options: SignOutAPIOptions) => Promise<Response>;
+};
+
+/**
+ * Standard JWT claims that are managed internally by the token system.
+ * These fields are typically filtered out before returning user data.
+ */
+type JWTStandardClaims = Pick<JWTPayload, "exp" | "iat" | "jti" | "nbf" | "sub" | "aud" | "iss">;
+/**
+ * JWT payload structure that includes a mandatory `token` field used to verify CSRF Tokens
+ */
+type JWTPayloadWithToken = JWTPayload & {
+    token: string;
+};
+/**
+ * Standardized user profile returned by OAuth providers after fetching user information
+ * and mapping the response to this format by default or via the `profile` custom function.
+ */
+interface User extends Record<string, unknown> {
+    sub: string;
+    name?: string | null;
+    email?: string | null;
+    image?: string | null;
+}
+/**
+ * Session data returned by the session endpoint.
+ */
+interface Session {
+    user: User;
+    expires: string;
+}
+type AuthorizeParams = LiteralUnion<"clientId" | "prompt" | "scope" | "responseMode" | "audience" | "loginHint" | "nonce" | "display">;
+type ResponseType = LiteralUnion<"code" | "token" | "refresh_token" | "id_token">;
+/**
+ * Configuration for an OAuth provider without credentials.
+ * Use this type when defining provider metadata and endpoints.
+ */
+interface OAuthProviderConfig<Profile extends object = Record<string, any>> {
+    id: string;
+    name: string;
+    /**
+     * @deprecated
+     * use `authorize` instead of `authorizeURL`
+     */
+    authorizeURL?: string;
+    authorize: string | {
+        url: string;
+        params?: Partial<Record<AuthorizeParams, string> & {
+            responseType: ResponseType;
+        }>;
+    };
+    accessToken: string | {
+        url: string;
+        headers?: Record<string, string>;
+    };
+    userInfo: string | {
+        url: string;
+        headers?: Record<string, string>;
+        method?: string;
+    };
+    /**
+     * @deprecated
+     * use `authorize.params.scope` instead of `scope`
+     */
+    scope?: string;
+    /**
+     * @deprecated
+     * use `authorize.params.response_type` instead of `responseType`
+     */
+    responseType?: ResponseType;
+    profile?: (profile: Profile) => User | Promise<User>;
+}
+/**
+ * OAuth provider configuration with client credentials.
+ * Extends OAuthProviderConfig with clientId and clientSecret.
+ */
+interface OAuthProviderCredentials<Profile extends object = Record<string, any>> extends OAuthProviderConfig<Profile> {
+    clientId?: string;
+    clientSecret?: string;
+}
+/**
+ * Complete OAuth provider type combining configuration and credentials.
+ */
+type OAuthProvider<Profile extends object = Record<string, any>> = OAuthProviderCredentials<Profile>;
+/**
+ * Cookie type with __Secure- prefix, must be Secure.
+ * @see https://httpwg.org/http-extensions/draft-ietf-httpbis-rfc6265bis.html#name-the-__secure-prefix
+ */
+type SecureCookie = {
+    strategy: "secure";
+} & Prettify<Omit<SerializeOptions, "secure" | "encode">>;
+/**
+ * Cookie type with __Host- prefix, must be Secure, Path=/, no Domain attribute.
+ * @see https://httpwg.org/http-extensions/draft-ietf-httpbis-rfc6265bis.html#name-the-__host-prefix
+ */
+type HostCookie = {
+    strategy: "host";
+} & Prettify<Omit<SerializeOptions, "secure" | "path" | "domain" | "encode">>;
+/**
+ * Standard cookie type without security prefixes.
+ * Can be sent over both HTTP and HTTPS connections (default in development).
+ */
+type StandardCookie = {
+    strategy?: "standard";
+} & Prettify<Omit<SerializeOptions, "encode">>;
+/**
+ * Union type for cookie options based on the specified strategy.
+ * - `secure`: Cookies are only sent over HTTPS connections
+ * - `host`: Cookies use the __Host- prefix and are only sent over HTTPS connections
+ * - `standard`: Cookies can be sent over both HTTP and HTTPS connections (default in development)
+ */
+type CookieStrategyAttributes = StandardCookie | SecureCookie | HostCookie;
+/**
+ * Names of cookies used by Aura Auth for session management and OAuth flows.
+ * - `sessionToken`: User session JWT
+ * - `csrfToken`: CSRF protection token
+ * - `state`: OAuth state parameter for CSRF protection
+ * - `code_verifier`: PKCE code verifier for authorization code flow
+ * - `redirect_uri`: OAuth callback URI
+ * - `redirect_to`: Post-authentication redirect path
+ * - `nonce`: OpenID Connect nonce parameter
+ */
+type CookieName = "sessionToken" | "csrfToken" | "state" | "codeVerifier" | "redirectTo" | "redirectURI";
+type CookieStoreConfig = Record<CookieName, {
+    name: string;
+    attributes: CookieStrategyAttributes;
+}>;
+interface CookieConfig {
+    /**
+     * Prefix to be added to all cookie names. By default "aura-stack".
+     */
+    prefix?: string;
+    overrides?: Partial<CookieStoreConfig>;
+}
+/**
+ * Main configuration interface for Aura Auth.
+ * This is the user-facing configuration object passed to `createAuth()`.
+ */
+interface AuthConfig {
+    /**
+     * OAuth providers available in the authentication and authorization flows. It provides a type-inference
+     * for the OAuth providers that are supported by Aura Stack Auth; alternatively, you can provide a custom
+     * OAuth third-party authorization service by implementing the `OAuthProviderCredentials` interface.
+     *
+     * Built-in OAuth providers:
+     * oauth: ["github", "google"]
+     *
+     * Custom credentials via factory:
+     * oauth: [github({ clientId: "...", clientSecret: "..." })]
+     *
+     * Custom OAuth providers:
+     * oauth: [
+     *   {
+     *     id: "oauth-providers",
+     *     name: "OAuth",
+     *     authorizeURL: "https://example.com/oauth/authorize",
+     *     accessToken: "https://example.com/oauth/token",
+     *     scope: "profile email",
+     *     responseType: "code",
+     *     userInfo: "https://example.com/oauth/userinfo",
+     *     clientId: process.env.AURA_AUTH_PROVIDER_CLIENT_ID,
+     *     clientSecret: process.env.AURA_AUTH_PROVIDER_CLIENT_SECRET,
+     *   }
+     * ]
+     */
+    oauth: (BuiltInOAuthProvider | OAuthProviderCredentials<any>)[];
+    /**
+     * Cookie options defines the configuration for cookies used in Aura Auth.
+     * It includes a prefix for cookie names and flag options to determine
+     * the security and scope of the cookies.
+     *
+     * **⚠️ WARNING:** Ensure that the cookie options are configured correctly to
+     * maintain the security and integrity of the authentication process. `Aura Auth`
+     * is not responsible for misconfigured cookies that may lead to security vulnerabilities.
+     *
+     * - prefix: A string prefix to be added to all cookie names, by default "aura-stack".
+     * - flag options (This attributes help to define the security level of the cookies):
+     *   - secure: Cookies use the __Secure- prefix and are only sent over HTTPS connections.
+     *   - host: Cookies use the __Host- prefix and are only sent over HTTPS connections.
+     *   - standard: Cookies can be sent over both HTTP and HTTPS connections. (default in development)
+     *
+     * @see https://httpwg.org/http-extensions/draft-ietf-httpbis-rfc6265bis.html#name-the-__secure-prefix
+     * @see https://httpwg.org/http-extensions/draft-ietf-httpbis-rfc6265bis.html#name-the-__host-prefix
+     */
+    cookies?: Partial<CookieConfig>;
+    /**
+     * Secret used to sign and verify JWT tokens for session and csrf protection.
+     * If not provided, it will load from the environment variable `AURA_AUTH_SECRET` or `AUTH_SECRET`, but if it
+     * doesn't exist, it will throw an error during the initialization of the Auth module.
+     */
+    secret?: string;
+    /**
+     * Base URL of the application, used to construct the incoming request's origin.
+     */
+    baseURL?: string;
+    /**
+     * Base path for all authentication routes. Default is `/auth`.
+     */
+    basePath?: `/${string}`;
+    /**
+     * Enable trusted proxy headers for scenarios where the application is behind a reverse proxy or load balancer.
+     * This setting allows Aura Auth to correctly interpret headers like `X-Forwarded-For` and `X-Forwarded-Proto`
+     * to determine the original client IP address and protocol.
+     *
+     * Default is `false`. Enable this option only if you are certain that your application is behind a trusted proxy.
+     * Misconfiguration can lead to security vulnerabilities, such as incorrect handling of secure cookies or
+     * inaccurate client IP logging.
+     *
+     * This value can also be set via environment variable as `AURA_AUTH_TRUSTED_PROXY_HEADERS`
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded
+     * @experimental
+     */
+    trustedProxyHeaders?: boolean;
+    logger?: boolean | Logger;
+    /**
+     * Defines trusted origins for your application to prevent open redirect attacks.
+     * URLs from the Referer header, Origin header, request URL, and redirectTo option
+     * are validated against this list before redirecting.
+     *
+     * - **Exact URL**: `https://example.com` matches only that origin.
+     * - **Subdomain wildcard**: `https://*.example.com` matches `https://app.example.com`, `https://api.example.com`, etc.
+     * @example
+     * trustedOrigins: ["https://example.com", "https://*.example.com", "http://localhost:3000"]
+     *
+     *
+     * trustedOrigins: async (request) => {
+     *   const origin = new URL(request.url).origin
+     *   return [origin, "https://admin.example.com"]
+     * }
+     */
+    trustedOrigins?: TrustedOrigin[] | ((request: Request) => Promise<TrustedOrigin[]> | TrustedOrigin[]);
+}
+/**
+ * A trusted origin URL or pattern. Supports:
+ * - Exact: `https://example.com`
+ * - Subdomain wildcard: `https://*.example.com`
+ */
+type TrustedOrigin = string;
+type JoseInstance = ReturnType<typeof createJoseInstance>;
+type OAuthProviderRecord = Record<LiteralUnion<BuiltInOAuthProvider>, OAuthProviderCredentials>;
+type InternalLogger = {
+    level: LogLevel;
+    log: typeof createLogEntry;
+};
+type SessionResponse = {
+    session: Session;
+    authenticated: true;
+} | {
+    session: null;
+    authenticated: false;
+};
+type GetSessionAPI = (options: {
+    headers: HeadersInit;
+}) => Promise<SessionResponse>;
+type AuthAPI = ReturnType<typeof createAuthAPI>;
+interface RouterGlobalContext {
+    oauth: OAuthProviderRecord;
+    cookies: CookieStoreConfig;
+    jose: JoseInstance;
+    secret?: string;
+    baseURL?: string;
+    basePath: string;
+    trustedProxyHeaders: boolean;
+    trustedOrigins?: TrustedOrigin[] | ((request: Request) => Promise<TrustedOrigin[]> | TrustedOrigin[]);
+    logger?: InternalLogger;
+}
+/**
+ * Internal runtime configuration used within Aura Auth after initialization.
+ * All optional fields from AuthConfig are resolved to their default values.
+ */
+type AuthRuntimeConfig = RouterGlobalContext;
+interface AuthInstance {
+    handlers: {
+        GET: (request: Request) => Response | Promise<Response>;
+        POST: (request: Request) => Response | Promise<Response>;
+        ALL: (request: Request) => Response | Promise<Response>;
+    };
+    jose: JoseInstance;
+    api: AuthAPI;
+}
+/**
+ * Base OAuth error response structure.
+ */
+interface OAuthError<T extends string> {
+    error: T;
+    error_description?: string;
+}
+/**
+ * OAuth 2.0 Authorization Error Response Types
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
+ */
+type AuthorizationError = OAuthError<z.infer<typeof OAuthAuthorizationErrorResponse>["error"]>;
+/**
+ * OAuth 2.0 Access Token Error Response Types
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ */
+type AccessTokenError = OAuthError<z.infer<typeof OAuthAccessTokenErrorResponse>["error"]>;
+/**
+ * OAuth 2.0 Token Revocation Error Response Types
+ * @see https://datatracker.ietf.org/doc/html/rfc7009#section-2.2.1
+ */
+type TokenRevocationError = OAuthError<"invalid_session_token">;
+type ErrorType = AuthorizationError["error"] | AccessTokenError["error"] | TokenRevocationError["error"];
+type AuthInternalErrorCode = "INVALID_OAUTH_CONFIGURATION" | "INVALID_JWT_TOKEN" | "JOSE_INITIALIZATION_FAILED" | "SESSION_STORE_NOT_INITIALIZED" | "COOKIE_STORE_NOT_INITIALIZED" | "COOKIE_PARSING_FAILED" | "COOKIE_NOT_FOUND" | "INVALID_ENVIRONMENT_CONFIGURATION" | "INVALID_URL" | "INVALID_SALT_SECRET_VALUE" | "UNTRUSTED_ORIGIN" | "INVALID_OAUTH_PROVIDER_CONFIGURATION" | "DUPLICATED_OAUTH_PROVIDER_ID";
+type AuthSecurityErrorCode = "INVALID_STATE" | "MISMATCHING_STATE" | "POTENTIAL_OPEN_REDIRECT_ATTACK_DETECTED" | "CSRF_TOKEN_INVALID" | "CSRF_TOKEN_MISSING" | "SESSION_TOKEN_MISSING";
+type OAuthEnv = z.infer<typeof OAuthEnvSchema>;
+type APIErrorMap = Record<string, {
+    code: string;
+    message: string;
+}>;
+/**
+ * Log level for logger messages.
+ */
+type LogLevel = "warn" | "error" | "debug" | "info";
+/** Defines the Severity between 0 to 7 */
+type Severity = "emergency" | "alert" | "critical" | "error" | "warning" | "notice" | "info" | "debug";
+/**
+ * @see https://datatracker.ietf.org/doc/html/rfc5424
+ */
+type SyslogOptions = {
+    facility: 4 | 10;
+    severity: Severity;
+    timestamp?: string;
+    hostname?: string;
+    appName?: string;
+    procId?: string;
+    msgId: string;
+    message: string;
+    structuredData?: Record<string, string | number | boolean>;
+};
+/**
+ * Logger function interface for structured logging.
+ * Called when errors or warnings occur during authentication flows.
+ */
+interface Logger {
+    level?: LogLevel;
+    log?: (args: SyslogOptions) => void;
+}
+type AuthClient = ReturnType<typeof createAuthInstance>["handlers"];
+type AuthClientOptions = Prettify<Omit<ClientOptions, "baseURL"> & {
+    baseURL?: string;
+}>;
+interface SignInOptions {
+    redirect?: boolean;
+    redirectTo?: string;
+}
+interface SignOutOptions {
+    redirect?: boolean;
+    redirectTo?: string;
+}
+interface GetSessionAPIOptions {
+    headers: HeadersInit;
+}
+interface SignOutAPIOptions {
+    headers: HeadersInit;
+    redirectTo?: string;
+    skipCSRFCheck?: boolean;
+}
+interface SignInAPIOptions<Redirect extends boolean = boolean> {
+    headers?: HeadersInit;
+    redirect?: Redirect;
+    redirectTo?: string;
+    request?: Request;
+}
+type FunctionAPIContext<Options extends object> = {
+    ctx: RouterGlobalContext;
+} & Options;
+type SignInReturn<Redirect extends boolean = boolean> = Redirect extends true ? Response : {
+    redirect: false;
+    signInURL: string;
+};
+type InternalContext = RouterGlobalContext & {
+    cookieConfig: {
+        secure: CookieStoreConfig;
+        standard: CookieStoreConfig;
+    };
+};
+
+export { dropbox as $, type AuthConfig as A, type BuiltInOAuthProvider as B, type CookieConfig as C, createProxyLogger as D, type ErrorType as E, type FunctionAPIContext as F, type GetSessionAPIOptions as G, logMessages as H, type InternalContext as I, type JWTPayloadWithToken as J, createJoseInstance as K, type LogLevel as L, decodeJWTOptions as M, jwtVerificationOptions as N, type OAuthProviderRecord as O, type AtlassianProfile as P, type ExtendedProfile as Q, type RouterGlobalContext as R, type SessionResponse as S, type TrustedOrigin as T, type User as U, atlassian as V, type AccountType as W, type DropboxProfile as X, type FullTeam as Y, type Name as Z, type RootInfo as _, type InternalLogger as a, type Bot as a0, type NotionProfile as a1, type Owner as a2, type Person as a3, type User$1 as a4, notion as a5, type TwitchProfile as a6, twitch as a7, type PinterestProfile as a8, pinterest as a9, type AccessTokenError as aA, type AuthorizationError as aB, type AuthorizeParams as aC, type CookieName as aD, type CookieStrategyAttributes as aE, type GetSessionAPI as aF, type HostCookie as aG, type JWTStandardClaims as aH, type OAuthEnv as aI, type OAuthError as aJ, type ResponseType as aK, type SecureCookie as aL, type Severity as aM, type StandardCookie as aN, type SyslogOptions as aO, type TokenRevocationError as aP, type Login as aa, type MailchimpProfile as ab, mailchimp as ac, type StravaProfile as ad, type SummaryClub as ae, type SummaryGear as af, strava as ag, type XProfile as ah, x as ai, type SpotifyImage as aj, type SpotifyProfile as ak, spotify as al, type GitLabProfile as am, gitlab as an, type DiscordProfile as ao, type Nameplate as ap, discord as aq, type FigmaProfile as ar, figma as as, type BitbucketProfile as at, bitbucket as au, type GitHubProfile as av, github as aw, createBuiltInOAuthProviders as ax, createAuthInstance as ay, createAuthAPI as az, type CookieStoreConfig as b, type AuthRuntimeConfig as c, type AuthInternalErrorCode as d, type AuthSecurityErrorCode as e, type APIErrorMap as f, type SignInAPIOptions as g, type SignInReturn as h, type SignOutAPIOptions as i, type OAuthProviderCredentials as j, type OAuthProvider as k, type AuthClientOptions as l, type Session as m, type SignInOptions as n, type SignOutOptions as o, type AuthClient as p, type AuthAPI as q, type AuthInstance as r, type JoseInstance as s, type Logger as t, type OAuthProviderConfig as u, builtInOAuthProviders as v, createAuth as w, createSyslogMessage as x, createLogEntry as y, createLogger as z };