@xylex-group/athena 2.12.1 → 2.13.0

package/dist/athena-auth-url-oLux_57a.d.cts

@@ -0,0 +1,377 @@
+/**
+ * Cookie name prefixes treated as Athena Auth / Better Auth session material.
+ *
+ * Used by {@link clearAuthCookies} when matching `document.cookie` names
+ * (including `__Secure-` prefixed variants).
+ *
+ * | Prefix | Typical cookies |
+ * |--------|-----------------|
+ * | `athena-auth` | `athena-auth.session_token`, `athena-auth.session-token`, chunked `session_data.*` |
+ * | `__Secure-athena-auth` | HTTPS-prefixed Athena cookies |
+ * | `better-auth` | Legacy Better Auth session cookies |
+ * | `__Secure-better-auth` | HTTPS-prefixed Better Auth cookies |
+ *
+ * @see {@link clearAuthCookies}
+ * @see docs/auth-cookies.md
+ */
+declare const ATHENA_AUTH_COOKIE_PREFIXES: readonly ["athena-auth", "__Secure-athena-auth", "better-auth", "__Secure-better-auth"];
+/** @deprecated Prefer {@link ATHENA_AUTH_COOKIE_PREFIXES}. */
+declare const DEFAULT_AUTH_COOKIE_PREFIXES: readonly ["athena-auth", "__Secure-athena-auth", "better-auth", "__Secure-better-auth"];
+interface ClearAuthCookiesOptions {
+    /**
+     * Name prefixes to clear. Defaults to {@link ATHENA_AUTH_COOKIE_PREFIXES}.
+     */
+    prefixes?: string[];
+    /**
+     * Hostname used to build domain candidates (host + parent domains).
+     * Defaults to `window.location.hostname` when available.
+     */
+    hostname?: string;
+    /**
+     * Cookie path attribute when expiring cookies.
+     * @default `/`
+     */
+    path?: string;
+    /**
+     * Override cookie header to scan (tests). Defaults to `document.cookie`.
+     */
+    cookieHeader?: string;
+}
+/**
+ * Clears Athena Auth / Better Auth browser cookies by name prefix.
+ *
+ * Safe to call from server/SSR: returns `[]` when `document` is unavailable.
+ * Prefer this over local copies of cookie-clearing loops in app `signOut`
+ * helpers.
+ *
+ * Compared to a minimal `document.cookie = …; path=/` wipe, this helper also:
+ * - expires with `Max-Age=0`
+ * - tries host + parent domain attributes (for subdomain deployments)
+ * - skips domain attributes on localhost / local hostnames
+ *
+ * For the **app-host bridge** httpOnly cookie written by
+ * `createAthenaAuthSessionBridgeHandlers`, also call
+ * `clearAthenaAuthSessionOnAppHost()` from `@xylex-group/athena/next/client`
+ * (that cookie is not always visible to `document.cookie`).
+ *
+ * @param options - Optional prefixes, hostname, path, or cookie header override
+ * @returns Cookie names that matched and were targeted for deletion
+ *
+ * @example
+ * ```ts
+ * import { clearAuthCookies } from "@xylex-group/athena/utils"
+ *
+ * export async function signOut(options?: { redirect?: boolean }) {
+ *   try {
+ *     await authClient.signOut({ fetchOptions: { throw: true } })
+ *   } catch (error) {
+ *     console.error("[auth] Sign out failed:", error)
+ *   } finally {
+ *     clearAuthCookies()
+ *     if (options?.redirect !== false && typeof window !== "undefined") {
+ *       window.location.href = "/sign-in"
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function clearAuthCookies(options?: ClearAuthCookiesOptions): string[];
+
+/**
+ * Shared Athena Auth UI route segments, views, and redirect helpers.
+ *
+ * Aligned with `@xylex-group/athena-auth-ui` / Auth UI `routes.ts` so apps can
+ * import from `@xylex-group/athena/utils` instead of copying route maps.
+ */
+/**
+ * Canonical auth screen ids used by UI routing and middleware.
+ *
+ * Note: the canonical forgot-password view id is `forgot-password`. The URL
+ * segment `forget-password` is accepted as a legacy alias and maps to that view.
+ */
+type AuthView = 'sign-in' | 'sign-up' | 'forgot-password' | 'reset-password' | 'reset-email-sent' | 'check-email' | 'accept-invitation' | 'logout';
+/** Default view when no path segment is present. */
+declare const AUTH_DEFAULT_VIEW = "sign-in";
+/** Optional two-factor path segment used by some app routers. */
+declare const AUTH_TWO_FACTOR_SEGMENT = "two-factor";
+/**
+ * Map of URL path segments → {@link AuthView}.
+ *
+ * Includes `forget-password` as a legacy alias for `forgot-password`.
+ */
+declare const AUTH_VIEW_BY_SEGMENT: Readonly<Record<string, AuthView>>;
+/**
+ * Views that should bounce **authenticated** users away (e.g. to app home).
+ * Reset/check-email/logout stay reachable while signed in.
+ */
+declare const AUTHENTICATED_REDIRECT_VIEW_SET: Set<AuthView>;
+/**
+ * Resolve an auth UI view from a single path segment.
+ *
+ * @param segment - e.g. `"sign-in"` from `/auth/[segment]`; `undefined` → default
+ * @returns Canonical {@link AuthView}, or `null` when the segment is unknown
+ *
+ * @example
+ * ```ts
+ * resolveAuthViewFromSegment(undefined) // "sign-in"
+ * resolveAuthViewFromSegment("forget-password") // "forgot-password"
+ * resolveAuthViewFromSegment("unknown") // null
+ * ```
+ */
+declare function resolveAuthViewFromSegment(segment: string | undefined): AuthView | null;
+/**
+ * Whether an authenticated user should be redirected away from this auth view.
+ *
+ * @param view - Resolved auth view
+ */
+declare function shouldRedirectAuthenticatedAuthView(view: AuthView): boolean;
+/**
+ * Default page routes under `/auth/*` for Next.js (or similar) apps.
+ */
+declare const AUTH_ROUTES: {
+    readonly acceptInvitation: "/auth/accept-invitation";
+    readonly appHome: "/";
+    readonly checkEmail: "/auth/check-email";
+    readonly forgotPassword: "/auth/forgot-password";
+    readonly logout: "/auth/logout";
+    readonly resetEmailSent: "/auth/reset-email-sent";
+    readonly resetPassword: "/auth/reset-password";
+    readonly signIn: "/auth/sign-in";
+    readonly signUp: "/auth/sign-up";
+    readonly socialCallback: "/auth/social-callback";
+};
+type AuthRoutes = Record<keyof typeof AUTH_ROUTES, string>;
+/**
+ * Build an auth route map with optional path overrides.
+ */
+declare function createAuthRoutes(overrides?: Partial<AuthRoutes>): AuthRoutes;
+/**
+ * Query/mode → path redirects used by legacy `?mode=` style entrypoints.
+ */
+interface AuthModeRedirects {
+    readonly 'forgot-password': string;
+    readonly login: string;
+    readonly logout: string;
+    readonly 'reset-password': string;
+    readonly signup: string;
+}
+declare function createAuthModeRedirects(routes?: AuthRoutes): AuthModeRedirects;
+declare const AUTH_MODE_REDIRECTS: AuthModeRedirects;
+type AuthMode = keyof AuthModeRedirects;
+declare const AUTH_MODE_SET: Set<string>;
+declare const AUTHENTICATED_REDIRECT_MODE_SET: Set<keyof AuthModeRedirects>;
+/**
+ * Type guard for legacy auth `mode` query values (`login`, `signup`, …).
+ */
+declare function isAuthMode(value: string): value is AuthMode;
+/**
+ * Whether an authenticated user should be redirected away from this auth mode.
+ */
+declare function shouldRedirectAuthenticatedAuthMode(mode: AuthMode): boolean;
+/**
+ * Resolve a path for a legacy auth mode string.
+ *
+ * @returns Path from {@link AUTH_MODE_REDIRECTS}, or `null` if unknown
+ */
+declare function resolveAuthModeRedirect(mode: string | undefined, redirects?: AuthModeRedirects): string | null;
+
+/**
+ * Resolve Athena Auth base / upstream URLs from env or explicit config.
+ *
+ * Mirrors the Athena Auth UI base-url contract so apps and the SDK share one
+ * precedence order for `ATHENA_AUTH_*` environment variables.
+ */
+/** Default browser/proxy path for same-origin auth routing. */
+declare const ATHENA_AUTH_PATH = "/api/auth";
+/** Fallback origin when no absolute upstream is configured (server-side). */
+declare const LOCAL_DEV_ORIGIN = "http://localhost:3000";
+/**
+ * Hosted Athena Auth origin used when no upstream override is supplied.
+ * Origin only — no `/api/auth` suffix.
+ */
+declare const DEFAULT_ATHENA_AUTH_ORIGIN = "https://auth.athena-auth.com";
+/**
+ * @deprecated Prefer {@link DEFAULT_ATHENA_AUTH_ORIGIN}.
+ * Kept for callers that used the older name.
+ */
+declare const DEFAULT_ATHENA_AUTH_UPSTREAM_URL = "https://auth.athena-auth.com";
+/**
+ * Environment keys checked (in order) for the Athena Auth upstream URL.
+ *
+ * Prefer server-only keys first so private upstream hosts are not forced to
+ * rely on `NEXT_PUBLIC_*` values.
+ */
+declare const ATHENA_AUTH_UPSTREAM_ENV_KEYS: readonly ["ATHENA_AUTH_UPSTREAM_URL", "ATHENA_AUTH_URL", "NEXT_PUBLIC_ATHENA_AUTH_UPSTREAM_URL", "NEXT_PUBLIC_ATHENA_AUTH_URL"];
+/**
+ * Auth UI naming parity (`base-url.ts`).
+ * Same ordered list as {@link ATHENA_AUTH_UPSTREAM_ENV_KEYS}.
+ */
+declare const ATHENA_AUTH_UPSTREAM_URL_ENV_NAMES: readonly ["ATHENA_AUTH_UPSTREAM_URL", "ATHENA_AUTH_URL", "NEXT_PUBLIC_ATHENA_AUTH_UPSTREAM_URL", "NEXT_PUBLIC_ATHENA_AUTH_URL"];
+type AthenaAuthUpstreamEnvKey = (typeof ATHENA_AUTH_UPSTREAM_ENV_KEYS)[number];
+/** Loose env map (Node `process.env` or a test fixture). */
+type EnvLike = Record<string, string | undefined>;
+type AthenaAuthUpstreamEnv = Partial<Record<AthenaAuthUpstreamEnvKey, string | undefined>> & EnvLike;
+interface AthenaAuthClientBaseUrlOptions {
+    /**
+     * When `true` (default), ensure the client base ends with `/api/auth`.
+     * Set `false` when the auth server is mounted at a custom path or root.
+     */
+    appendAuthPath?: boolean;
+}
+/**
+ * Returns `true` when the value is an absolute `http://` or `https://` URL.
+ */
+declare function isAbsoluteUrl(value: string): boolean;
+/**
+ * Read the first non-empty Athena Auth upstream URL from an env-like map.
+ *
+ * @returns Trimmed URL string, or `undefined` when none of the keys are set
+ */
+declare function readAthenaAuthUpstreamUrlFromEnv(env: EnvLike): string | undefined;
+/**
+ * Normalize a consumer-supplied auth base URL so it targets `/api/auth`
+ * (unless the path already ends with that segment).
+ *
+ * Absolute URLs keep origin and rewrite pathname; relative paths are ensured
+ * to end with `/api/auth`.
+ *
+ * @example
+ * ```ts
+ * normalizeAthenaAuthBaseUrl('https://auth.example.com')
+ * // => 'https://auth.example.com/api/auth'
+ *
+ * normalizeAthenaAuthBaseUrl('/api/auth')
+ * // => '/api/auth'
+ * ```
+ */
+declare function normalizeAthenaAuthBaseUrl(urlOrPath: string): string;
+/**
+ * Resolve the **server-side** Athena Auth upstream origin (no `/api/auth` suffix).
+ *
+ * Used when proxying or calling the auth host directly from Node / edge.
+ *
+ * @param rawUpstreamUrl - Explicit URL, env map, or omit to read `process.env`
+ * @returns Origin like `https://auth.example.com` (no trailing slash)
+ */
+declare function resolveAthenaAuthUpstreamUrl(rawUpstreamUrl?: string | AthenaAuthUpstreamEnv): string;
+/**
+ * Resolve the **browser-facing** auth client base URL.
+ *
+ * Default behavior appends `/api/auth` for same-origin proxying. Pass
+ * `{ appendAuthPath: false }` to keep a custom path or root mount.
+ *
+ * Overloads match common call styles from Athena Auth UI and app code:
+ * - `resolveAthenaAuthClientBaseUrl("https://auth.example.com")`
+ * - `resolveAthenaAuthClientBaseUrl(process.env)`
+ * - `resolveAthenaAuthClientBaseUrl(undefined)` → env + defaults
+ * - `resolveAthenaAuthClientBaseUrl(path, upstream, { appendAuthPath: false })`
+ */
+declare function resolveAthenaAuthClientBaseUrl(configuredAuthBaseUrl?: string | EnvLike, rawUpstreamUrl?: string | AthenaAuthUpstreamEnv, options?: AthenaAuthClientBaseUrlOptions): string;
+declare function resolveAthenaAuthClientBaseUrl(configuredAuthBaseUrl: string, rawUpstreamUrl?: string | AthenaAuthUpstreamEnv, options?: AthenaAuthClientBaseUrlOptions): string;
+/**
+ * Build an absolute Athena Auth request URL for a path under the client base.
+ *
+ * Resolves at **call time** (reads env when `rawBaseUrl` is omitted) so module
+ * load order does not freeze a stale URL.
+ *
+ * @param path - Path relative to the auth base (leading slashes stripped)
+ * @param rawBaseUrl - Optional base string or env map
+ *
+ * @example
+ * ```ts
+ * resolveAthenaAuthRequestUrl('get-session', 'https://auth.example.com')
+ * // => 'https://auth.example.com/api/auth/get-session'
+ * ```
+ */
+declare function resolveAthenaAuthRequestUrl(path: string, rawBaseUrl?: string | EnvLike): string;
+/** Relative auth path for email verification (`GET /verify-email`). */
+declare const ATHENA_AUTH_VERIFY_EMAIL_PATH = "verify-email";
+/**
+ * Relative segment for session lookup (`GET /get-session`).
+ * Prefer with {@link resolveAthenaAuthRequestUrl} when `base` already ends in `/api/auth`.
+ */
+declare const ATHENA_AUTH_GET_SESSION_PATH = "get-session";
+/**
+ * Absolute app/proxy path for session lookup.
+ * Use with `new URL(ATHENA_AUTH_GET_SESSION_ABSOLUTE_PATH, appOrigin)` when
+ * `baseUrl` is the **app origin** (e.g. `https://app.example.com`), not the auth client base.
+ */
+declare const ATHENA_AUTH_GET_SESSION_ABSOLUTE_PATH = "/api/auth/get-session";
+/**
+ * @deprecated Alias of {@link ATHENA_AUTH_GET_SESSION_ABSOLUTE_PATH} for drop-in
+ * replacement of app-local `AUTH_SESSION_PATH` constants. Prefer the `ATHENA_` name.
+ */
+declare const AUTH_SESSION_PATH = "/api/auth/get-session";
+/**
+ * Query param that forces Athena Auth / Better Auth style session handlers to
+ * skip cookie cache and re-read the live session cookie.
+ */
+declare const ATHENA_AUTH_DISABLE_COOKIE_CACHE_QUERY_PARAM = "disableCookieCache";
+/**
+ * @deprecated Alias of {@link ATHENA_AUTH_DISABLE_COOKIE_CACHE_QUERY_PARAM}.
+ */
+declare const DISABLE_COOKIE_CACHE_QUERY_PARAM = "disableCookieCache";
+/** Value paired with {@link ATHENA_AUTH_DISABLE_COOKIE_CACHE_QUERY_PARAM}. */
+declare const ATHENA_AUTH_DISABLE_COOKIE_CACHE_QUERY_VALUE = "true";
+/**
+ * @deprecated Alias of {@link ATHENA_AUTH_DISABLE_COOKIE_CACHE_QUERY_VALUE}.
+ */
+declare const DISABLE_COOKIE_CACHE_QUERY_VALUE = "true";
+/**
+ * Optional request/response header some apps use to pass serialized session
+ * payload between edge middleware and the app (not set by the SDK itself).
+ */
+declare const ATHENA_SESSION_DATA_HEADER = "x-session-data";
+/**
+ * @deprecated Alias of {@link ATHENA_SESSION_DATA_HEADER}.
+ */
+declare const SESSION_DATA_HEADER = "x-session-data";
+/**
+ * Absolute callback URL for email verification.
+ *
+ * Equivalent to `resolveAthenaAuthRequestUrl("verify-email")` — use this in
+ * sign-up / send-verification payloads as `callbackURL` instead of a local
+ * wrapper around Auth UI `base-url` helpers.
+ *
+ * @param rawBaseUrl - Optional base string or env map (defaults to process env)
+ * @returns e.g. `https://auth.example.com/api/auth/verify-email`
+ *
+ * @example
+ * ```ts
+ * import { resolveEmailVerificationCallbackUrl } from "@xylex-group/athena/utils"
+ *
+ * await client.auth.signUp.email({
+ *   email,
+ *   password,
+ *   name,
+ *   callbackURL: resolveEmailVerificationCallbackUrl(),
+ * })
+ * ```
+ */
+declare function resolveEmailVerificationCallbackUrl(rawBaseUrl?: string | EnvLike): string;
+/**
+ * Build a same-origin (or absolute) **fresh** get-session URL.
+ *
+ * Appends `disableCookieCache=true` so middleware / RSC session probes do not
+ * reuse a stale cookie-cache entry.
+ *
+ * @param baseUrl - App origin (`https://app.example.com`) or any base accepted by
+ *   the `URL` constructor. Resolves {@link ATHENA_AUTH_GET_SESSION_ABSOLUTE_PATH}
+ *   (`/api/auth/get-session`) against that base.
+ * @returns URL such as `https://app.example.com/api/auth/get-session?disableCookieCache=true`
+ *
+ * @example
+ * ```ts
+ * import { createFreshSessionLookupUrl } from "@xylex-group/athena/utils"
+ *
+ * const url = createFreshSessionLookupUrl("https://app.example.com")
+ * await fetch(url, { headers: { cookie: requestHeaders.get("cookie") ?? "" } })
+ * ```
+ *
+ * For auth-client base URLs that already include `/api/auth`, prefer:
+ * `resolveAthenaAuthRequestUrl("get-session", authBase) + "?disableCookieCache=true"`
+ * or pass the **app** origin into this helper when you proxy `/api/auth/*` locally.
+ */
+declare function createFreshSessionLookupUrl(baseUrl: string | URL): URL;
+
+export { ATHENA_AUTH_COOKIE_PREFIXES as A, AUTH_SESSION_PATH as B, type ClearAuthCookiesOptions as C, DEFAULT_ATHENA_AUTH_ORIGIN as D, type EnvLike as E, AUTH_TWO_FACTOR_SEGMENT as F, type AthenaAuthClientBaseUrlOptions as G, type AthenaAuthUpstreamEnv as H, type AthenaAuthUpstreamEnvKey as I, type AuthMode as J, type AuthModeRedirects as K, type AuthRoutes as L, DEFAULT_ATHENA_AUTH_UPSTREAM_URL as M, DEFAULT_AUTH_COOKIE_PREFIXES as N, DISABLE_COOKIE_CACHE_QUERY_PARAM as O, DISABLE_COOKIE_CACHE_QUERY_VALUE as P, LOCAL_DEV_ORIGIN as Q, createAuthModeRedirects as R, SESSION_DATA_HEADER as S, createAuthRoutes as T, createFreshSessionLookupUrl as U, isAuthMode as V, readAthenaAuthUpstreamUrlFromEnv as W, resolveAuthModeRedirect as X, shouldRedirectAuthenticatedAuthMode as Y, ATHENA_AUTH_PATH as a, ATHENA_AUTH_UPSTREAM_ENV_KEYS as b, ATHENA_AUTH_UPSTREAM_URL_ENV_NAMES as c, AUTH_DEFAULT_VIEW as d, AUTH_ROUTES as e, AUTH_VIEW_BY_SEGMENT as f, type AuthView as g, clearAuthCookies as h, isAbsoluteUrl as i, resolveAthenaAuthRequestUrl as j, resolveAthenaAuthUpstreamUrl as k, resolveAuthViewFromSegment as l, resolveEmailVerificationCallbackUrl as m, normalizeAthenaAuthBaseUrl as n, ATHENA_AUTH_DISABLE_COOKIE_CACHE_QUERY_PARAM as o, ATHENA_AUTH_DISABLE_COOKIE_CACHE_QUERY_VALUE as p, ATHENA_AUTH_GET_SESSION_ABSOLUTE_PATH as q, resolveAthenaAuthClientBaseUrl as r, shouldRedirectAuthenticatedAuthView as s, ATHENA_AUTH_GET_SESSION_PATH as t, ATHENA_AUTH_VERIFY_EMAIL_PATH as u, ATHENA_SESSION_DATA_HEADER as v, AUTHENTICATED_REDIRECT_MODE_SET as w, AUTHENTICATED_REDIRECT_VIEW_SET as x, AUTH_MODE_REDIRECTS as y, AUTH_MODE_SET as z };