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

package/dist/{index-B8jeIElf.d.ts → index-CSyIJmCM.d.ts}

@@ -1,9 +1,269 @@
 import { z } from 'zod';
 import { OAuthAuthorizationErrorResponse, OAuthAccessTokenErrorResponse, OAuthEnvSchema } from './schemas.js';
+import { createJoseInstance } from './jose.js';
 import { SerializeOptions } from '@aura-stack/router/cookie';
-import { JWTVerifyOptions, EncryptOptions, JWTDecryptOptions } from '@aura-stack/jose';
-import { JWTPayload } from '@aura-stack/jose/jose';
 import { LiteralUnion, Prettify } from './@types/utility.js';
+import { JWTPayload } from '@aura-stack/jose/jose';
+
+/**
+ * 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;
 
 /**
  * @see [Pinterest - Get User Account](https://developers.pinterest.com/docs/api/v5/user_account-get)
@@ -27,7 +287,7 @@ interface PinterestProfile {
  * @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: OAuthProviderConfig<PinterestProfile>;
+declare const pinterest: (options?: Partial<OAuthProviderCredentials<PinterestProfile>>) => OAuthProviderCredentials<PinterestProfile>;
 
 interface Login {
     email: string;
@@ -36,6 +296,9 @@ interface Login {
     login_name: string;
     login_email: string;
 }
+/**
+ * @see [Mailchimp - API Root](https://mailchimp.com/developer/marketing/api/authentication/)
+ */
 interface MailchimpProfile {
     dc: string;
     role: string;
@@ -46,9 +309,14 @@ interface MailchimpProfile {
     api_endpoint: string;
 }
 /**
- * @see [Mailchimp - Access Data on Behalf of Other Users with OAuth 2](https://mailchimp.com/developer/marketing/guides/access-user-data-oauth-2/)
+ * 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: OAuthProviderConfig<MailchimpProfile>;
+declare const mailchimp: (options?: Partial<OAuthProviderCredentials<MailchimpProfile>>) => OAuthProviderCredentials<MailchimpProfile>;
 
 /**
  * @see [Strava - SummaryClub](https://developers.strava.com/docs/reference/#api-models-SummaryClub)
@@ -120,7 +388,7 @@ interface StravaProfile {
  * @see [Strava - API Application](https://www.strava.com/settings/api)
  * @see [Strava - API Reference](https://developers.strava.com/docs/reference/)
  */
-declare const strava: OAuthProviderConfig<StravaProfile>;
+declare const strava: (options?: Partial<OAuthProviderCredentials<StravaProfile>>) => OAuthProviderCredentials<StravaProfile>;
 
 /**
  * @see [X - Get my User](https://docs.x.com/x-api/users/get-my-user)
@@ -141,9 +409,9 @@ interface XProfile {
  * @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: OAuthProviderConfig<XProfile>;
+declare const x: (options?: Partial<OAuthProviderCredentials<XProfile>>) => OAuthProviderCredentials<XProfile>;
 
-interface Image {
+interface SpotifyImage {
     url: string;
     height: number;
     width: number;
@@ -159,7 +427,7 @@ interface SpotifyProfile {
     uri: string;
     country: string;
     href: string;
-    images: Image[];
+    images: SpotifyImage[];
     product: string;
     explicit_content: {
         filter_enabled: boolean;
@@ -182,10 +450,10 @@ interface SpotifyProfile {
  * @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: OAuthProviderConfig<SpotifyProfile>;
+declare const spotify: (options?: Partial<OAuthProviderCredentials<SpotifyProfile>>) => OAuthProviderCredentials<SpotifyProfile>;
 
 /**
- * @see [GitLab - Get the current user](https://docs.gitlab.com/api/users/#get-the-current-user)
+ * @see [GitLab - User Structure](https://docs.gitlab.com/ee/api/users.html#external-user-structure)
  */
 interface GitLabProfile {
     id: number;
@@ -244,7 +512,7 @@ interface GitLabProfile {
  * @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: OAuthProviderConfig<GitLabProfile>;
+declare const gitlab: (options?: Partial<OAuthProviderCredentials<GitLabProfile>>) => OAuthProviderCredentials<GitLabProfile>;
 
 /**
  * @see [Discord - Nameplate Object](https://discord.com/developers/docs/resources/user#nameplate-nameplate-structure)
@@ -303,7 +571,7 @@ interface DiscordProfile {
  * @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: OAuthProviderConfig<DiscordProfile>;
+declare const discord: (options?: Partial<OAuthProviderCredentials<DiscordProfile>>) => OAuthProviderCredentials<DiscordProfile>;
 
 /**
  * @see [Figma API - Users](https://developers.figma.com/docs/rest-api/users-types/)
@@ -321,7 +589,7 @@ interface FigmaProfile {
  * @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: OAuthProviderConfig<FigmaProfile>;
+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)
@@ -353,7 +621,7 @@ interface BitbucketProfile {
  * @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: OAuthProviderConfig<BitbucketProfile>;
+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)
@@ -414,19 +682,19 @@ interface GitHubProfile {
  * @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: OAuthProviderConfig<GitHubProfile>;
+declare const github: (options?: Partial<OAuthProviderCredentials<GitHubProfile>>) => OAuthProviderCredentials<GitHubProfile>;
 
 declare const builtInOAuthProviders: {
-    readonly github: OAuthProviderConfig<GitHubProfile>;
-    readonly bitbucket: OAuthProviderConfig<BitbucketProfile>;
-    readonly figma: OAuthProviderConfig<FigmaProfile>;
-    readonly discord: OAuthProviderConfig<DiscordProfile>;
-    readonly gitlab: OAuthProviderConfig<GitLabProfile>;
-    readonly spotify: OAuthProviderConfig<SpotifyProfile>;
-    readonly x: OAuthProviderConfig<XProfile>;
-    readonly strava: OAuthProviderConfig<StravaProfile>;
-    readonly mailchimp: OAuthProviderConfig<MailchimpProfile>;
-    readonly pinterest: OAuthProviderConfig<PinterestProfile>;
+    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>;
 };
 /**
  * Constructs OAuth provider configurations from an array of provider names or configurations.
@@ -434,8 +702,14 @@ declare const builtInOAuthProviders: {
  *
  * @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)[]) => Record<LiteralUnion<BuiltInOAuthProvider>, OAuthProviderCredentials>;
+declare const createBuiltInOAuthProviders: (oauth?: (BuiltInOAuthProvider | OAuthProviderCredentials<any>)[]) => Record<LiteralUnion<BuiltInOAuthProvider>, OAuthProviderCredentials<any>>;
 type BuiltInOAuthProvider = keyof typeof builtInOAuthProviders;
 
 /**
@@ -470,7 +744,7 @@ interface Session {
  * Configuration for an OAuth provider without credentials.
  * Use this type when defining provider metadata and endpoints.
  */
-interface OAuthProviderConfig<Profile extends object = {}> {
+interface OAuthProviderConfig<Profile extends object = Record<string, any>> {
     id: string;
     name: string;
     authorizeURL: string;
@@ -484,14 +758,14 @@ interface OAuthProviderConfig<Profile extends object = {}> {
  * OAuth provider configuration with client credentials.
  * Extends OAuthProviderConfig with clientId and clientSecret.
  */
-interface OAuthProviderCredentials<Profile extends object = {}> extends OAuthProviderConfig<Profile> {
-    clientId: string;
-    clientSecret: string;
+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 = {}> = OAuthProviderCredentials<Profile>;
+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
@@ -555,6 +829,9 @@ interface AuthConfig {
      * Built-in OAuth providers:
      * oauth: ["github", "google"]
      *
+     * Custom credentials via factory:
+     * oauth: [github({ clientId: "...", clientSecret: "..." })]
+     *
      * Custom OAuth providers:
      * oauth: [
      *   {
@@ -565,12 +842,12 @@ interface AuthConfig {
      *     scope: "profile email",
      *     responseType: "code",
      *     userInfo: "https://example.com/oauth/userinfo",
-     *     clientId: process.env.AURA_AUTH_OAUTH_PROVIDER_CLIENT_ID!,
-     *     clientSecret: process.env.AURA_AUTH_OAUTH_PROVIDER_CLIENT_SECRET!,
+     *     clientId: process.env.AURA_AUTH_PROVIDER_CLIENT_ID,
+     *     clientSecret: process.env.AURA_AUTH_PROVIDER_CLIENT_SECRET,
      *   }
      * ]
      */
-    oauth: (BuiltInOAuthProvider | OAuthProviderCredentials)[];
+    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
@@ -615,16 +892,37 @@ interface AuthConfig {
      * @experimental
      */
     trustedProxyHeaders?: boolean;
+    logger?: 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[]);
 }
-interface JoseInstance {
-    decodeJWT: (token: string) => Promise<JWTPayload>;
-    encodeJWT: (payload: JWTPayload) => Promise<string>;
-    signJWS: (payload: JWTPayload) => Promise<string>;
-    verifyJWS: (payload: string, options?: JWTVerifyOptions) => Promise<JWTPayload>;
-    encryptJWE: (payload: string, options?: EncryptOptions) => Promise<string>;
-    decryptJWE: (payload: string, options?: JWTDecryptOptions) => Promise<string>;
-}
+/**
+ * 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;
+};
 interface RouterGlobalContext {
     oauth: OAuthProviderRecord;
     cookies: CookieStoreConfig;
@@ -632,6 +930,8 @@ interface RouterGlobalContext {
     secret?: string;
     basePath: string;
     trustedProxyHeaders: boolean;
+    trustedOrigins?: TrustedOrigin[] | ((request: Request) => Promise<TrustedOrigin[]> | TrustedOrigin[]);
+    logger?: InternalLogger;
 }
 /**
  * Internal runtime configuration used within Aura Auth after initialization.
@@ -668,12 +968,40 @@ type AccessTokenError = OAuthError<z.infer<typeof OAuthAccessTokenErrorResponse>
  */
 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";
+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.
+ */
+type Logger = {
+    level: LogLevel;
+    log: (args: SyslogOptions) => void;
+};
 
-export { type AuthorizationError as $, type AuthRuntimeConfig as A, type BitbucketProfile as B, type CookieConfig as C, type DiscordProfile as D, type ErrorType as E, type FigmaProfile as F, type GitLabProfile as G, createBuiltInOAuthProviders as H, type Image as I, type JWTPayloadWithToken as J, type BuiltInOAuthProvider as K, type Login as L, type MailchimpProfile as M, type Nameplate as N, type OAuthProvider as O, type PinterestProfile as P, type JWTStandardClaims as Q, type RouterGlobalContext as R, type Session as S, type SecureCookie as T, type User as U, type HostCookie as V, type StandardCookie as W, type XProfile as X, type CookieStrategyAttributes as Y, type CookieName as Z, type OAuthError as _, type CookieStoreConfig as a, type AccessTokenError as a0, type TokenRevocationError as a1, type OAuthEnv as a2, type AuthInternalErrorCode as b, type AuthSecurityErrorCode as c, type AuthConfig as d, type JoseInstance as e, type AuthInstance as f, type OAuthProviderConfig as g, type OAuthProviderCredentials as h, type APIErrorMap as i, type OAuthProviderRecord as j, type SummaryClub as k, type SummaryGear as l, mailchimp as m, type StravaProfile as n, type SpotifyProfile as o, pinterest as p, spotify as q, gitlab as r, strava as s, discord as t, figma as u, bitbucket as v, type GitHubProfile as w, x, github as y, builtInOAuthProviders as z };
+export { type SecureCookie as $, type AuthRuntimeConfig as A, figma as B, type CookieConfig as C, type DiscordProfile as D, type ErrorType as E, type FigmaProfile as F, type GitLabProfile as G, type BitbucketProfile as H, type InternalLogger as I, type JWTPayloadWithToken as J, bitbucket as K, type Logger as L, type MailchimpProfile as M, type Nameplate as N, type OAuthProvider as O, type PinterestProfile as P, type GitHubProfile as Q, type RouterGlobalContext as R, type Session as S, type TrustedOrigin as T, type User as U, github as V, builtInOAuthProviders as W, type XProfile as X, createBuiltInOAuthProviders as Y, type BuiltInOAuthProvider as Z, type JWTStandardClaims as _, type CookieStoreConfig as a, type HostCookie as a0, type StandardCookie as a1, type CookieStrategyAttributes as a2, type CookieName as a3, type OAuthError as a4, type AuthorizationError as a5, type AccessTokenError as a6, type TokenRevocationError as a7, type OAuthEnv as a8, type Severity as a9, type SyslogOptions as aa, type AuthInternalErrorCode as b, type AuthSecurityErrorCode as c, type AuthConfig as d, type AuthInstance as e, type JoseInstance as f, type OAuthProviderConfig as g, type OAuthProviderCredentials as h, type LogLevel as i, type APIErrorMap as j, type OAuthProviderRecord as k, logMessages as l, createLogEntry as m, type Login as n, mailchimp as o, pinterest as p, type SummaryClub as q, type SummaryGear as r, type StravaProfile as s, strava as t, type SpotifyImage as u, type SpotifyProfile as v, spotify as w, x, gitlab as y, discord as z };