next-sanctum 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1395 @@
+'use client';
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var jsxRuntime = require('react/jsx-runtime');
+var react = require('react');
+
+/**
+ * Error types for next-sanctum. All failures are normalized to `SanctumError`
+ * so consumers can handle them consistently (see plan §10: errors must not leak).
+ */ /** Base error for all module failures. */ class SanctumError extends Error {
+    constructor(message, options){
+        super(message, {
+            cause: options.cause
+        });
+        this.name = "SanctumError";
+        this.kind = options.kind;
+        this.status = options.status;
+        this.data = options.data;
+    }
+}
+/** Invalid configuration — fail-fast on init (see resolveConfig). */ class ConfigError extends SanctumError {
+    constructor(message, cause){
+        super(message, {
+            kind: "config",
+            cause
+        });
+        this.name = "ConfigError";
+    }
+}
+/**
+ * HTTP 422 from Laravel. Exposes field errors (`{ field: string[] }`) so
+ * consumers can map them to their forms.
+ */ class ValidationError extends SanctumError {
+    constructor(message, errors, data){
+        super(message, {
+            kind: "validation",
+            status: 422,
+            data
+        });
+        this.name = "ValidationError";
+        this.errors = errors;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/** Try to read the response body as JSON; return undefined if it isn't JSON. */ async function readBody(response) {
+    const contentType = response.headers.get("content-type") ?? "";
+    try {
+        if (contentType.includes("application/json")) {
+            return await response.json();
+        }
+        const text = await response.text();
+        return text.length > 0 ? text : undefined;
+    } catch  {
+        return undefined;
+    }
+}
+function kindForStatus(status) {
+    switch(status){
+        case 401:
+            return "unauthorized";
+        case 403:
+            return "forbidden";
+        case 419:
+            return "csrf";
+        case 422:
+            return "validation";
+        default:
+            return "http";
+    }
+}
+/**
+ * Build a `SanctumError` from a non-2xx Response. The message is taken from the
+ * Laravel body (`message`) when present, without leaking the stack or internal details.
+ */ async function errorFromResponse(response) {
+    const data = await readBody(response);
+    const body = isRecord(data) ? data : {};
+    const message = body.message ?? `Request failed with status ${response.status}.`;
+    if (response.status === 422) {
+        return new ValidationError(message, body.errors ?? {}, data);
+    }
+    return new SanctumError(message, {
+        kind: kindForStatus(response.status),
+        status: response.status,
+        data
+    });
+}
+/** Wrap a network error (fetch rejection) into a SanctumError. */ function networkError(cause) {
+    const message = cause instanceof Error ? cause.message : "Network request failed.";
+    return new SanctumError(message, {
+        kind: "network",
+        cause
+    });
+}
+
+/** Typed lifecycle emitter (see SanctumEventMap). */ class SanctumEventEmitter {
+    on(event, handler) {
+        let set = this.handlers.get(event);
+        if (!set) {
+            set = new Set();
+            this.handlers.set(event, set);
+        }
+        const fn = handler;
+        set.add(fn);
+        return ()=>{
+            set.delete(fn);
+        };
+    }
+    emit(event, payload) {
+        const set = this.handlers.get(event);
+        if (!set) return;
+        // Snapshot + isolate: a throwing consumer handler must not break the auth/request
+        // flow this is emitted from, nor skip the remaining handlers.
+        for (const handler of [
+            ...set
+        ]){
+            try {
+                handler(payload);
+            } catch  {
+            // swallow consumer handler errors
+            }
+        }
+    }
+    /** Register many handlers at once (used by the provider from config.events). */ register(handlers) {
+        for (const key of Object.keys(handlers)){
+            const handler = handlers[key];
+            if (!handler) continue;
+            let set = this.handlers.get(key);
+            if (!set) {
+                set = new Set();
+                this.handlers.set(key, set);
+            }
+            set.add(handler);
+        }
+    }
+    constructor(){
+        this.handlers = new Map();
+    }
+}
+
+const PREFIX = "[next-sanctum]";
+/** Leveled logger. logLevel 0 = silent; 3 = info (default). */ function createLogger(level) {
+    const enabled = (threshold)=>level >= threshold;
+    return {
+        error: (...args)=>{
+            if (enabled(1)) console.error(PREFIX, ...args);
+        },
+        warn: (...args)=>{
+            if (enabled(2)) console.warn(PREFIX, ...args);
+        },
+        info: (...args)=>{
+            if (enabled(3)) console.info(PREFIX, ...args);
+        },
+        debug: (...args)=>{
+            if (enabled(4)) console.debug(PREFIX, ...args);
+        }
+    };
+}
+
+const DEFAULT_ENDPOINTS = {
+    csrf: "/sanctum/csrf-cookie",
+    login: "/login",
+    logout: "/logout",
+    user: "/api/user",
+    register: "/register",
+    forgotPassword: "/forgot-password",
+    resetPassword: "/reset-password",
+    emailVerificationNotification: "/email/verification-notification",
+    verifyEmail: "/email/verify",
+    confirmPassword: "/user/confirm-password",
+    confirmedPasswordStatus: "/user/confirmed-password-status",
+    profileInformation: "/user/profile-information",
+    updatePassword: "/user/password",
+    twoFactor: {
+        challenge: "/two-factor-challenge",
+        enable: "/user/two-factor-authentication",
+        confirm: "/user/confirmed-two-factor-authentication",
+        disable: "/user/two-factor-authentication",
+        qrCode: "/user/two-factor-qr-code",
+        secretKey: "/user/two-factor-secret-key",
+        recoveryCodes: "/user/two-factor-recovery-codes"
+    },
+    passkeys: {
+        loginOptions: "/passkeys/login/options",
+        login: "/passkeys/login",
+        confirmOptions: "/passkeys/confirm/options",
+        confirm: "/passkeys/confirm",
+        registerOptions: "/user/passkeys/options",
+        register: "/user/passkeys",
+        delete: "/user/passkeys"
+    },
+    sessions: {
+        list: "/api/sessions",
+        logoutOthers: "/api/sessions/others",
+        logout: "/api/sessions"
+    }
+};
+function resolveTwoFactor(value) {
+    if (value === false) return false;
+    if (value === undefined || value === true) {
+        return {
+            confirm: true,
+            confirmPassword: true
+        };
+    }
+    return {
+        confirm: value.confirm ?? true,
+        confirmPassword: value.confirmPassword ?? true
+    };
+}
+function resolvePasskeys(value) {
+    if (value === undefined || value === false) return false;
+    if (value === true) return {
+        confirmPassword: true
+    };
+    return {
+        confirmPassword: value.confirmPassword ?? true
+    };
+}
+function defaultOrigin(input) {
+    if (input) return input;
+    if (typeof window !== "undefined") return window.location.origin;
+    return undefined;
+}
+function resolveFetch(input) {
+    const impl = input ?? globalThis.fetch;
+    if (typeof impl !== "function") {
+        throw new ConfigError("Native `fetch` is not available. Provide `config.fetch` (Node < 18) or use a modern runtime.");
+    }
+    return impl.bind(globalThis);
+}
+/**
+ * Validate + fill in config defaults. Fail-fast when `baseUrl` is missing to avoid
+ * an SSR loop / fetching the URL `undefined` (see plan §10 risks).
+ */ function resolveConfig(input) {
+    if (!input || typeof input.baseUrl !== "string" || input.baseUrl.trim() === "") {
+        throw new ConfigError("`baseUrl` is required (the Laravel API URL, e.g. https://api.domain.com).");
+    }
+    const features = input.features ?? {};
+    const endpoints = input.endpoints ?? {};
+    return {
+        baseUrl: input.baseUrl.replace(/\/+$/, ""),
+        mode: input.mode ?? "cookie",
+        origin: defaultOrigin(input.origin),
+        features: {
+            registration: features.registration ?? true,
+            resetPasswords: features.resetPasswords ?? true,
+            emailVerification: features.emailVerification ?? true,
+            updateProfileInformation: features.updateProfileInformation ?? true,
+            updatePasswords: features.updatePasswords ?? true,
+            deviceSessions: features.deviceSessions ?? false,
+            twoFactorAuthentication: resolveTwoFactor(features.twoFactorAuthentication),
+            passkeys: resolvePasskeys(features.passkeys)
+        },
+        endpoints: {
+            ...DEFAULT_ENDPOINTS,
+            ...endpoints,
+            twoFactor: {
+                ...DEFAULT_ENDPOINTS.twoFactor,
+                ...endpoints.twoFactor
+            },
+            passkeys: {
+                ...DEFAULT_ENDPOINTS.passkeys,
+                ...endpoints.passkeys
+            },
+            sessions: {
+                ...DEFAULT_ENDPOINTS.sessions,
+                ...endpoints.sessions
+            }
+        },
+        csrf: {
+            cookie: input.csrf?.cookie ?? "XSRF-TOKEN",
+            header: input.csrf?.header ?? "X-XSRF-TOKEN"
+        },
+        redirect: {
+            onLogin: input.redirect?.onLogin ?? "/",
+            onLogout: input.redirect?.onLogout ?? "/",
+            onAuthOnly: input.redirect?.onAuthOnly ?? "/login",
+            onGuestOnly: input.redirect?.onGuestOnly ?? "/",
+            keepRequestedRoute: input.redirect?.keepRequestedRoute ?? false
+        },
+        logLevel: input.logLevel ?? 3,
+        initialRequest: input.initialRequest ?? true,
+        retryOnCsrfMismatch: input.retryOnCsrfMismatch ?? true,
+        storage: input.storage,
+        interceptors: {
+            request: input.interceptors?.request ?? [],
+            response: input.interceptors?.response ?? []
+        },
+        events: input.events ?? {},
+        redirectIfUnauthenticated: input.redirectIfUnauthenticated ?? false,
+        fetch: resolveFetch(input.fetch)
+    };
+}
+
+/**
+ * Open-redirect protection. Only allows SAME-ORIGIN destinations (a relative path
+ * or an absolute URL with the same origin), with an optional path allowlist.
+ * See PRD §12.1 (Open redirect) & §18 (a unit test is required).
+ */ /** Reject backslashes and any control character (Tab/LF/CR are stripped by the URL
+ * parser, which could turn `/\t/evil.com` into `//evil.com` and bypass the `//` guard). */ function hasUnsafeChars(value) {
+    for(let i = 0; i < value.length; i++){
+        const code = value.charCodeAt(i);
+        if (code <= 0x1f || code === 0x7f) return true;
+        if (value[i] === "\\") return true;
+    }
+    return false;
+}
+/**
+ * Return `target` when it is safe (same-origin), otherwise `fallback`.
+ * Rejects: `//evil.com`, `https://evil.com`, the `javascript:` scheme, control-char
+ * injection (`/\t//evil.com`), and backslash tricks.
+ */ function safeRedirect(target, fallback, options = {}) {
+    if (!target) return fallback;
+    const trimmed = target.trim();
+    if (trimmed === "") return fallback;
+    if (hasUnsafeChars(trimmed)) return fallback;
+    let path = null;
+    if (trimmed.startsWith("/")) {
+        // Reject protocol-relative (//evil.com).
+        if (trimmed.startsWith("//")) return fallback;
+        path = trimmed;
+    } else if (options.origin) {
+        try {
+            const url = new URL(trimmed);
+            const base = new URL(options.origin);
+            if (url.origin === base.origin) {
+                path = url.pathname + url.search + url.hash;
+            }
+        } catch  {
+        // not a valid URL → reject
+        }
+    }
+    if (path === null) return fallback;
+    // Defense-in-depth: resolve the path and confirm it stays same-origin.
+    try {
+        const base = options.origin ?? "https://sanctum.invalid";
+        if (new URL(path, base).origin !== new URL(base).origin) return fallback;
+    } catch  {
+        return fallback;
+    }
+    if (options.allowList && options.allowList.length > 0) {
+        const safe = path;
+        const allowed = options.allowList.some((prefix)=>safe === prefix || safe.startsWith(prefix));
+        if (!allowed) return fallback;
+    }
+    return path;
+}
+
+/** HTTP methods that require CSRF protection in cookie mode. */ const STATEFUL_METHODS = new Set([
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE"
+]);
+/** Join baseUrl + path. Absolute paths (http/https) are passed through as-is. */ function joinUrl(baseUrl, path) {
+    if (/^https?:\/\//i.test(path)) return path;
+    const base = baseUrl.replace(/\/+$/, "");
+    const suffix = path.startsWith("/") ? path : `/${path}`;
+    return base + suffix;
+}
+/**
+ * Parse the response body as JSON. Returns `undefined` (cast to T)
+ * for 204 / an empty body so the caller doesn't need a manual try/catch.
+ */ async function parseJson(response) {
+    if (response.status === 204) return undefined;
+    const text = await response.text();
+    if (text.length === 0) return undefined;
+    try {
+        return JSON.parse(text);
+    } catch (cause) {
+        throw new SanctumError("Failed to parse the JSON response body.", {
+            kind: "unknown",
+            status: response.status,
+            cause
+        });
+    }
+}
+
+/**
+ * CSRF cookie reading (browser). Sanctum stores `XSRF-TOKEN` in URL-encoded
+ * form, so its value MUST be decoded before being sent as the
+ * `X-XSRF-TOKEN` header (the most common source of Sanctum integration bugs).
+ */ /** Read a single cookie from document.cookie. Null on the server (no document). */ function readCookie(name) {
+    if (typeof document === "undefined") return null;
+    const cookies = document.cookie ? document.cookie.split("; ") : [];
+    for (const cookie of cookies){
+        const eq = cookie.indexOf("=");
+        const key = eq === -1 ? cookie : cookie.slice(0, eq);
+        if (key === name) {
+            return eq === -1 ? "" : cookie.slice(eq + 1);
+        }
+    }
+    return null;
+}
+/** Read the XSRF token from the cookie, then URL-decode it. */ function readXsrfToken(cookieName) {
+    const raw = readCookie(cookieName);
+    if (raw === null) return null;
+    try {
+        return decodeURIComponent(raw);
+    } catch  {
+        return raw;
+    }
+}
+
+/**
+ * The native-fetch core used by every feature: attaches CSRF (cookie) or
+ * Bearer (token), credentials, base URL, interceptors, a single 419 retry, and
+ * normalizes errors.
+ */ function createSanctumClient(config, deps = {}) {
+    const fetchImpl = config.fetch;
+    const { logger, emitter } = deps;
+    async function fetchCsrfCookie() {
+        const url = joinUrl(config.baseUrl, config.endpoints.csrf);
+        logger?.debug("GET", url);
+        try {
+            await fetchImpl(url, {
+                method: "GET",
+                credentials: "include",
+                headers: {
+                    accept: "application/json"
+                }
+            });
+        } catch (cause) {
+            throw networkError(cause);
+        }
+    }
+    // De-duplicate concurrent CSRF-cookie fetches so parallel stateful requests on a
+    // fresh page don't each fire (and race) a `GET /sanctum/csrf-cookie`.
+    let csrfInFlight = null;
+    async function ensureCsrf(force = false) {
+        if (config.mode !== "cookie") return;
+        if (!force && readXsrfToken(config.csrf.cookie)) return;
+        if (!force && csrfInFlight) return csrfInFlight;
+        const pending = fetchCsrfCookie().finally(()=>{
+            if (csrfInFlight === pending) csrfInFlight = null;
+        });
+        csrfInFlight = pending;
+        return pending;
+    }
+    async function buildRequest(path, init) {
+        const url = joinUrl(config.baseUrl, path);
+        const method = (init.method ?? "GET").toUpperCase();
+        const headers = new Headers(init.headers);
+        if (!headers.has("accept")) headers.set("accept", "application/json");
+        const { json, body: rawBody, ...rest } = init;
+        let body = rawBody ?? null;
+        if (json !== undefined) {
+            body = JSON.stringify(json);
+            if (!headers.has("content-type")) {
+                headers.set("content-type", "application/json");
+            }
+        }
+        if (config.mode === "cookie") {
+            const token = readXsrfToken(config.csrf.cookie);
+            if (token && !headers.has(config.csrf.header)) {
+                headers.set(config.csrf.header, token);
+            }
+        } else if (deps.getToken) {
+            const token = await deps.getToken();
+            if (token && !headers.has("authorization")) {
+                headers.set("authorization", `Bearer ${token}`);
+            }
+        }
+        const credentials = config.mode === "cookie" ? "include" : init.credentials ?? "same-origin";
+        let request = new Request(url, {
+            ...rest,
+            method,
+            headers,
+            body,
+            credentials
+        });
+        for (const interceptor of config.interceptors.request){
+            request = await interceptor(request);
+        }
+        return request;
+    }
+    async function send(path, init, isRetry) {
+        const request = await buildRequest(path, init);
+        emitter?.emit("request", {
+            url: request.url,
+            init
+        });
+        let response;
+        try {
+            response = await fetchImpl(request);
+        } catch (cause) {
+            const error = networkError(cause);
+            emitter?.emit("error", {
+                error
+            });
+            throw error;
+        }
+        for (const interceptor of config.interceptors.response){
+            response = await interceptor(response, request);
+        }
+        emitter?.emit("response", {
+            url: request.url,
+            response
+        });
+        if (response.status === 419 && config.mode === "cookie" && config.retryOnCsrfMismatch && !isRetry) {
+            logger?.warn("CSRF mismatch (419) — refresh token & retry once");
+            await ensureCsrf(true);
+            return send(path, init, true);
+        }
+        if (!response.ok) {
+            const error = await errorFromResponse(response);
+            emitter?.emit("error", {
+                error
+            });
+            throw error;
+        }
+        return response;
+    }
+    async function raw(path, init = {}) {
+        const method = (init.method ?? "GET").toUpperCase();
+        if (config.mode === "cookie" && STATEFUL_METHODS.has(method)) {
+            await ensureCsrf();
+        }
+        return send(path, init, false);
+    }
+    async function request(path, init = {}) {
+        const response = await raw(path, init);
+        return parseJson(response);
+    }
+    return {
+        config,
+        ensureCsrf,
+        raw,
+        request
+    };
+}
+
+/**
+ * Core auth API (framework-agnostic). The React provider wraps it to
+ * manage state. Login detects `two_factor` BEFORE fetching the user
+ * so consumers cannot forget to handle 2FA (discriminated result).
+ */ function createAuthApi(client, config, deps = {}) {
+    const { emitter } = deps;
+    async function refreshIdentity() {
+        try {
+            const user = await client.request(config.endpoints.user, {
+                method: "GET"
+            });
+            const resolved = user ?? null;
+            emitter?.emit("refresh", {
+                user: resolved
+            });
+            return resolved;
+        } catch (error) {
+            if (error instanceof SanctumError && error.kind === "unauthorized") {
+                emitter?.emit("refresh", {
+                    user: null
+                });
+                return null;
+            }
+            throw error;
+        }
+    }
+    async function login(credentials) {
+        const data = await client.request(config.endpoints.login, {
+            method: "POST",
+            json: credentials
+        });
+        if (data?.two_factor) {
+            // Token mode + 2FA is not completable via the standard Fortify flow: the
+            // `/two-factor-challenge` endpoint establishes a session and returns no token.
+            // Fail loud instead of leaving the user silently unauthenticated.
+            if (config.mode === "token") {
+                throw new ConfigError("Two-factor authentication during login is only supported in cookie mode. " + "In token mode, mint the token from a 2FA-aware endpoint.");
+            }
+            emitter?.emit("two-factor-required", {});
+            return {
+                status: "two-factor-required"
+            };
+        }
+        if (config.mode === "token" && data?.token) {
+            await deps.setToken?.(data.token);
+        }
+        const user = await refreshIdentity();
+        if (!user) {
+            throw new SanctumError("Login succeeded but failed to fetch the user data. Check the user endpoint & configuration.", {
+                kind: "unknown"
+            });
+        }
+        emitter?.emit("login", {
+            user
+        });
+        return {
+            status: "authenticated",
+            user
+        };
+    }
+    async function logout() {
+        try {
+            await client.raw(config.endpoints.logout, {
+                method: "POST"
+            });
+        } finally{
+            if (config.mode === "token") await deps.clearToken?.();
+            emitter?.emit("logout", {});
+        }
+    }
+    return {
+        login,
+        logout,
+        refreshIdentity
+    };
+}
+
+/** Registration (Fortify `POST /register`). On success → a login session is created by the backend. */ function createRegistrationApi(client, config) {
+    return {
+        async register (payload) {
+            if (!config.features.registration) {
+                throw new ConfigError('The "registration" feature is disabled in config.');
+            }
+            await client.raw(config.endpoints.register, {
+                method: "POST",
+                json: payload
+            });
+        }
+    };
+}
+
+function createPasswordApi(client, config) {
+    const ep = config.endpoints;
+    return {
+        async forgotPassword (payload) {
+            await client.raw(ep.forgotPassword, {
+                method: "POST",
+                json: payload
+            });
+        },
+        async resetPassword (payload) {
+            await client.raw(ep.resetPassword, {
+                method: "POST",
+                json: payload
+            });
+        },
+        async confirmPassword (payload) {
+            await client.raw(ep.confirmPassword, {
+                method: "POST",
+                json: payload
+            });
+        },
+        async confirmedPasswordStatus () {
+            const data = await client.request(ep.confirmedPasswordStatus, {
+                method: "GET"
+            });
+            return Boolean(data?.confirmed);
+        },
+        async updatePassword (payload) {
+            await client.raw(ep.updatePassword, {
+                method: "PUT",
+                json: payload
+            });
+        }
+    };
+}
+
+function createProfileApi(client, config) {
+    return {
+        async updateProfileInformation (payload) {
+            await client.raw(config.endpoints.profileInformation, {
+                method: "PUT",
+                json: payload
+            });
+        }
+    };
+}
+
+function createEmailVerificationApi(client, config) {
+    return {
+        async resendEmailVerification () {
+            await client.raw(config.endpoints.emailVerificationNotification, {
+                method: "POST"
+            });
+        },
+        async verifyEmail (payload) {
+            const query = new URLSearchParams({
+                expires: String(payload.expires),
+                signature: payload.signature
+            }).toString();
+            const path = `${config.endpoints.verifyEmail}/${encodeURIComponent(String(payload.id))}/${encodeURIComponent(payload.hash)}?${query}`;
+            await client.request(path, {
+                method: "GET"
+            });
+        }
+    };
+}
+
+function createTwoFactorApi(client, config) {
+    const ep = config.endpoints.twoFactor;
+    function ensureEnabled() {
+        if (config.features.twoFactorAuthentication === false) {
+            throw new ConfigError('The "twoFactorAuthentication" feature is disabled in config.');
+        }
+    }
+    return {
+        async challenge (payload) {
+            // Challenge may run even when 2FA management is disabled (login flow).
+            await client.raw(ep.challenge, {
+                method: "POST",
+                json: payload
+            });
+        },
+        async enable () {
+            ensureEnabled();
+            await client.raw(ep.enable, {
+                method: "POST"
+            });
+        },
+        async confirm (code) {
+            ensureEnabled();
+            await client.raw(ep.confirm, {
+                method: "POST",
+                json: {
+                    code
+                }
+            });
+        },
+        async disable () {
+            ensureEnabled();
+            await client.raw(ep.disable, {
+                method: "DELETE"
+            });
+        },
+        async getQrCode () {
+            ensureEnabled();
+            return client.request(ep.qrCode, {
+                method: "GET"
+            });
+        },
+        async getSecretKey () {
+            ensureEnabled();
+            return client.request(ep.secretKey, {
+                method: "GET"
+            });
+        },
+        async getRecoveryCodes () {
+            ensureEnabled();
+            return client.request(ep.recoveryCodes, {
+                method: "GET"
+            });
+        },
+        async regenerateRecoveryCodes () {
+            ensureEnabled();
+            await client.raw(ep.recoveryCodes, {
+                method: "POST"
+            });
+        }
+    };
+}
+
+async function loadPasskeys() {
+    try {
+        const mod = await import('@laravel/passkeys');
+        return mod.Passkeys;
+    } catch (cause) {
+        throw new ConfigError("The @laravel/passkeys package is not installed. Run: pnpm add @laravel/passkeys", cause);
+    }
+}
+/**
+ * Passkeys interop (Fortify). The WebAuthn ceremony is delegated to @laravel/passkeys
+ * (dynamic import, browser-only, optional peer). We map the endpoints from config
+ * & set credentials/CSRF so the request is authenticated.
+ */ function createPasskeysApi(client, config) {
+    const ep = config.endpoints.passkeys;
+    const abs = (path)=>joinUrl(config.baseUrl, path);
+    function ensureEnabled() {
+        if (config.features.passkeys === false) {
+            throw new ConfigError('The "passkeys" feature is disabled in config.');
+        }
+    }
+    async function configured() {
+        ensureEnabled();
+        const Passkeys = await loadPasskeys();
+        await client.ensureCsrf();
+        const xsrf = readXsrfToken(config.csrf.cookie);
+        Passkeys.configure({
+            fetch: {
+                credentials: "include",
+                headers: xsrf ? {
+                    [config.csrf.header]: xsrf
+                } : {}
+            }
+        });
+        return Passkeys;
+    }
+    return {
+        async isSupported () {
+            const Passkeys = await loadPasskeys();
+            return Passkeys.isSupported();
+        },
+        async register (name) {
+            const Passkeys = await configured();
+            return Passkeys.register({
+                name,
+                routes: {
+                    options: abs(ep.registerOptions),
+                    submit: abs(ep.register)
+                }
+            });
+        },
+        async login () {
+            const Passkeys = await configured();
+            await Passkeys.verify({
+                routes: {
+                    options: abs(ep.loginOptions),
+                    submit: abs(ep.login)
+                }
+            });
+        },
+        async confirmPassword () {
+            const Passkeys = await configured();
+            await Passkeys.verify({
+                routes: {
+                    options: abs(ep.confirmOptions),
+                    submit: abs(ep.confirm)
+                }
+            });
+        },
+        async delete (id) {
+            ensureEnabled();
+            await client.raw(`${ep.delete}/${encodeURIComponent(id)}`, {
+                method: "DELETE"
+            });
+        }
+    };
+}
+
+/** In-memory token storage (lost on reload). Default for token mode. */ class MemoryStorage {
+    get() {
+        return this.token;
+    }
+    set(token) {
+        this.token = token;
+    }
+    remove() {
+        this.token = null;
+    }
+    constructor(){
+        this.token = null;
+    }
+}
+
+const DEFAULT_KEY = "sanctum.token";
+let warned$1 = false;
+/** Token storage in localStorage. OPT-IN — vulnerable to XSS (see PRD §12). */ class LocalStorage {
+    constructor(key = DEFAULT_KEY){
+        this.key = key;
+    }
+    warnOnce() {
+        if (warned$1) return;
+        warned$1 = true;
+        console.warn("[next-sanctum] LocalStorage token storage is vulnerable to XSS. Use it only when necessary (e.g. Capacitor); for the web, prefer HttpOnly cookies + a server proxy.");
+    }
+    get() {
+        if (typeof window === "undefined") return null;
+        this.warnOnce();
+        return window.localStorage.getItem(this.key);
+    }
+    set(token) {
+        if (typeof window === "undefined") return;
+        this.warnOnce();
+        window.localStorage.setItem(this.key, token);
+    }
+    remove() {
+        if (typeof window === "undefined") return;
+        window.localStorage.removeItem(this.key);
+    }
+}
+
+let warned = false;
+/**
+ * Cookie-based token storage written by the client. NOTE: cookies written by
+ * JS CANNOT be HttpOnly. For true HttpOnly, set the cookie via a Route Handler/Server
+ * Action and then attach the Bearer on the server (catch-all proxy). This storage is for
+ * simple persistence, NOT a replacement for HttpOnly.
+ */ class CookieTokenStorage {
+    constructor(options = {}){
+        this.name = options.name ?? "sanctum_token";
+        this.maxAge = options.maxAge ?? 60 * 60 * 24 * 14;
+        this.sameSite = options.sameSite ?? "Strict";
+        this.secure = options.secure ?? true;
+        this.path = options.path ?? "/";
+    }
+    warnOnce() {
+        if (warned) return;
+        warned = true;
+        console.warn("[next-sanctum] CookieTokenStorage writes a non-HttpOnly cookie that is readable by JS (XSS-exposed). For production web apps, prefer an HttpOnly cookie set server-side + the catch-all proxy.");
+    }
+    get() {
+        const raw = readCookie(this.name);
+        if (raw === null || raw === "") return null;
+        this.warnOnce();
+        try {
+            return decodeURIComponent(raw);
+        } catch  {
+            return raw;
+        }
+    }
+    set(token) {
+        if (typeof document === "undefined") return;
+        this.warnOnce();
+        const parts = [
+            `${this.name}=${encodeURIComponent(token)}`,
+            `Path=${this.path}`,
+            `Max-Age=${this.maxAge}`,
+            `SameSite=${this.sameSite}`
+        ];
+        if (this.secure) parts.push("Secure");
+        document.cookie = parts.join("; ");
+    }
+    remove() {
+        if (typeof document === "undefined") return;
+        document.cookie = `${this.name}=; Path=${this.path}; Max-Age=0`;
+    }
+}
+
+/** Effective storage: config.storage, or the default MemoryStorage for token mode. */ function resolveTokenStorage(config) {
+    if (config.storage) return config.storage;
+    if (config.mode === "token") return new MemoryStorage();
+    return undefined;
+}
+
+const SanctumContext = /*#__PURE__*/ react.createContext(null);
+/** Get the context; throws a clear error if used outside the provider. */ function useSanctumContext() {
+    const ctx = react.useContext(SanctumContext);
+    if (!ctx) {
+        throw new Error("next-sanctum hooks must be used inside <SanctumProvider>.");
+    }
+    return ctx;
+}
+
+function SanctumProvider({ config, initialUser, children }) {
+    // Config resolution + client/feature-api creation happens once (on mount).
+    const instanceRef = react.useRef(null);
+    if (instanceRef.current === null) {
+        const resolved = resolveConfig(config);
+        const logger = createLogger(resolved.logLevel);
+        const emitter = new SanctumEventEmitter();
+        emitter.register(resolved.events);
+        const storage = resolveTokenStorage(resolved);
+        const client = createSanctumClient(resolved, {
+            logger,
+            emitter,
+            getToken: storage ? ()=>storage.get() : undefined
+        });
+        const auth = createAuthApi(client, resolved, {
+            emitter,
+            setToken: storage ? (token)=>storage.set(token) : undefined,
+            clearToken: storage ? ()=>storage.remove() : undefined
+        });
+        instanceRef.current = {
+            config: resolved,
+            client,
+            emitter,
+            auth,
+            registration: createRegistrationApi(client, resolved),
+            password: createPasswordApi(client, resolved),
+            profile: createProfileApi(client, resolved),
+            emailVerification: createEmailVerificationApi(client, resolved),
+            twoFactor: createTwoFactorApi(client, resolved),
+            passkeys: createPasskeysApi(client, resolved)
+        };
+    }
+    const { config: resolved, client, emitter, auth, registration, password, profile, emailVerification, twoFactor: rawTwoFactor, passkeys: rawPasskeys } = instanceRef.current;
+    const [user, setUser] = react.useState(()=>initialUser ?? null);
+    const [status, setStatus] = react.useState(()=>initialUser !== undefined ? initialUser ? "authenticated" : "unauthenticated" : resolved.initialRequest ? "loading" : "unauthenticated");
+    const userRef = react.useRef(user);
+    react.useEffect(()=>{
+        userRef.current = user;
+    }, [
+        user
+    ]);
+    // De-duplicate concurrent login() calls (double-submit) by sharing the in-flight promise.
+    const loginInFlight = react.useRef(null);
+    const login = react.useCallback((credentials)=>{
+        if (loginInFlight.current) return loginInFlight.current;
+        const pending = (async ()=>{
+            setStatus("loading");
+            try {
+                const result = await auth.login(credentials);
+                if (result.status === "authenticated") {
+                    setUser(result.user);
+                    setStatus("authenticated");
+                } else {
+                    setStatus("unauthenticated");
+                }
+                return result;
+            } catch (error) {
+                setStatus(userRef.current ? "authenticated" : "unauthenticated");
+                throw error;
+            } finally{
+                loginInFlight.current = null;
+            }
+        })();
+        loginInFlight.current = pending;
+        return pending;
+    }, [
+        auth
+    ]);
+    const logout = react.useCallback(async ()=>{
+        try {
+            await auth.logout();
+        } finally{
+            setUser(null);
+            setStatus("unauthenticated");
+        }
+    }, [
+        auth
+    ]);
+    const refresh = react.useCallback(async ()=>{
+        const next = await auth.refreshIdentity();
+        setUser(next);
+        setStatus(next ? "authenticated" : "unauthenticated");
+        return next;
+    }, [
+        auth
+    ]);
+    // Actions that change identity → refresh state after success.
+    const register = react.useCallback(async (payload)=>{
+        await registration.register(payload);
+        await refresh().catch(()=>{});
+    }, [
+        registration,
+        refresh
+    ]);
+    const updateProfile = react.useCallback(async (payload)=>{
+        await profile.updateProfileInformation(payload);
+        await refresh().catch(()=>{});
+    }, [
+        profile,
+        refresh
+    ]);
+    const verifyEmail = react.useCallback(async (payload)=>{
+        await emailVerification.verifyEmail(payload);
+        await refresh().catch(()=>{});
+    }, [
+        emailVerification,
+        refresh
+    ]);
+    const twoFactor = react.useMemo(()=>({
+            ...rawTwoFactor,
+            challenge: async (payload)=>{
+                await rawTwoFactor.challenge(payload);
+                await refresh().catch(()=>{});
+            }
+        }), [
+        rawTwoFactor,
+        refresh
+    ]);
+    const passkeys = react.useMemo(()=>({
+            ...rawPasskeys,
+            login: async ()=>{
+                await rawPasskeys.login();
+                await refresh().catch(()=>{});
+            }
+        }), [
+        rawPasskeys,
+        refresh
+    ]);
+    // Reactive logout on 401 (expired session) + optional redirect.
+    react.useEffect(()=>{
+        const off = emitter.on("error", ({ error })=>{
+            if (error.kind !== "unauthorized") return;
+            // Only react when we currently believe we're authenticated (session expiry) —
+            // not on the initial "am I logged in?" probe 401 for a guest on a public page.
+            if (!userRef.current) return;
+            setUser(null);
+            setStatus("unauthenticated");
+            const target = resolved.redirectIfUnauthenticated;
+            if (target && typeof window !== "undefined") {
+                const safe = safeRedirect(target, "/", {
+                    origin: resolved.origin
+                });
+                emitter.emit("redirect", {
+                    to: safe,
+                    reason: "unauthenticated"
+                });
+                window.location.assign(safe);
+            }
+        });
+        return off;
+    }, [
+        emitter,
+        resolved
+    ]);
+    // Init: emit event + fetch user when not prefetched from the server.
+    react.useEffect(()=>{
+        emitter.emit("init", {
+            user: userRef.current
+        });
+        if (initialUser !== undefined || !resolved.initialRequest) return;
+        let active = true;
+        auth.refreshIdentity().then((next)=>{
+            if (!active) return;
+            setUser(next);
+            setStatus(next ? "authenticated" : "unauthenticated");
+        }).catch(()=>{
+            if (active) setStatus("unauthenticated");
+        });
+        return ()=>{
+            active = false;
+        };
+    }, []);
+    const value = react.useMemo(()=>({
+            config: resolved,
+            client,
+            emitter,
+            user,
+            status,
+            isAuthenticated: status === "authenticated" && user !== null,
+            isLoading: status === "loading",
+            login,
+            logout,
+            refresh,
+            setUser,
+            register,
+            forgotPassword: password.forgotPassword,
+            resetPassword: password.resetPassword,
+            confirmPassword: password.confirmPassword,
+            confirmedPasswordStatus: password.confirmedPasswordStatus,
+            updatePassword: password.updatePassword,
+            updateProfile,
+            resendEmailVerification: emailVerification.resendEmailVerification,
+            verifyEmail,
+            twoFactor,
+            passkeys
+        }), [
+        resolved,
+        client,
+        emitter,
+        user,
+        status,
+        login,
+        logout,
+        refresh,
+        register,
+        updateProfile,
+        verifyEmail,
+        twoFactor,
+        passkeys,
+        password,
+        emailVerification
+    ]);
+    return /*#__PURE__*/ jsxRuntime.jsx(SanctumContext.Provider, {
+        value: value,
+        children: children
+    });
+}
+
+/** Authentication & account state and actions (login, register, password, profile, email verification). */ function useAuth() {
+    const ctx = useSanctumContext();
+    return {
+        user: ctx.user,
+        isAuthenticated: ctx.isAuthenticated,
+        isLoading: ctx.isLoading,
+        login: ctx.login,
+        logout: ctx.logout,
+        refresh: ctx.refresh,
+        register: ctx.register,
+        forgotPassword: ctx.forgotPassword,
+        resetPassword: ctx.resetPassword,
+        confirmPassword: ctx.confirmPassword,
+        confirmedPasswordStatus: ctx.confirmedPasswordStatus,
+        updatePassword: ctx.updatePassword,
+        updateProfile: ctx.updateProfile,
+        resendEmailVerification: ctx.resendEmailVerification,
+        verifyEmail: ctx.verifyEmail
+    };
+}
+
+/** Reactive user (null when not authenticated). Cast via the generic. */ function useUser() {
+    return useSanctumContext().user;
+}
+
+/**
+ * Authenticated fetch on the client. Minimal but sufficient for most cases;
+ * SWR/TanStack Query adapters can be built on top of `useSanctumContext().client`.
+ */ function useApi(path, options = {}) {
+    const { client } = useSanctumContext();
+    const { enabled = true, ...init } = options;
+    const initRef = react.useRef(init);
+    initRef.current = init;
+    // Serialize the request shape so option changes (method/json/body) trigger a refetch,
+    // not just `path`. Header changes are intentionally not part of the key (Headers
+    // aren't reliably serializable) — encode dynamic values into `path`/`json`.
+    const requestKey = JSON.stringify({
+        method: init.method ?? "GET",
+        json: init.json ?? null,
+        body: typeof init.body === "string" ? init.body : null
+    });
+    const [data, setData] = react.useState(undefined);
+    const [error, setError] = react.useState(null);
+    const [isLoading, setIsLoading] = react.useState(enabled);
+    const refetch = react.useCallback(async ()=>{
+        setIsLoading(true);
+        setError(null);
+        try {
+            setData(await client.request(path, initRef.current));
+        } catch (err) {
+            setError(err);
+        } finally{
+            setIsLoading(false);
+        }
+    }, [
+        client,
+        path,
+        requestKey
+    ]);
+    react.useEffect(()=>{
+        if (!enabled) return;
+        let active = true;
+        setIsLoading(true);
+        setError(null);
+        client.request(path, initRef.current).then((result)=>{
+            if (active) setData(result);
+        }).catch((err)=>{
+            if (active) setError(err);
+        }).finally(()=>{
+            if (active) setIsLoading(false);
+        });
+        return ()=>{
+            active = false;
+        };
+    }, [
+        client,
+        path,
+        enabled,
+        requestKey
+    ]);
+    return {
+        data,
+        error,
+        isLoading,
+        refetch
+    };
+}
+
+/**
+ * The authenticated HTTP client for imperative requests — i.e. CRUD beyond auth
+ * (create/update/delete or on-demand reads). `client.request<T>(path, { method, json })`
+ * returns parsed JSON; `client.raw(...)` returns the Response. It automatically attaches
+ * CSRF (cookie mode) or Bearer (token mode), the base URL, and credentials.
+ */ function useClient() {
+    return useSanctumContext().client;
+}
+
+/**
+ * A typed REST resource over the authenticated client — convenience sugar for CRUD.
+ * Credentials (CSRF/cookie or Bearer) are attached automatically. `TList` defaults to
+ * `T[]`; set it (e.g. `{ data: T[]; meta: … }`) for paginated Laravel resources.
+ *
+ * ```ts
+ * const posts = useResource<Post>("/api/posts")
+ * await posts.list()             // GET    /api/posts
+ * await posts.create({ title })  // POST   /api/posts
+ * await posts.update(1, { title })// PUT   /api/posts/1
+ * await posts.delete(1)          // DELETE /api/posts/1
+ * ```
+ */ function useResource(basePath) {
+    const { client } = useSanctumContext();
+    return react.useMemo(()=>{
+        const base = basePath.replace(/\/+$/, "");
+        const at = (id)=>`${base}/${encodeURIComponent(String(id))}`;
+        return {
+            list: (init)=>client.request(base, {
+                    ...init,
+                    method: "GET"
+                }),
+            get: (id, init)=>client.request(at(id), {
+                    ...init,
+                    method: "GET"
+                }),
+            create: (data, init)=>client.request(base, {
+                    ...init,
+                    method: "POST",
+                    json: data
+                }),
+            update: (id, data, init)=>client.request(at(id), {
+                    ...init,
+                    method: "PUT",
+                    json: data
+                }),
+            patch: (id, data, init)=>client.request(at(id), {
+                    ...init,
+                    method: "PATCH",
+                    json: data
+                }),
+            delete: (id, init)=>client.request(at(id), {
+                    ...init,
+                    method: "DELETE"
+                })
+        };
+    }, [
+        client,
+        basePath
+    ]);
+}
+
+/**
+ * A lightweight mutation hook (Inertia-style lifecycle) for imperative requests —
+ * pair it with `useClient` / `useResource`. Manages `isPending` / `error` / `data`
+ * and fires `onBefore` / `onSuccess` / `onError` / `onFinish`.
+ *
+ * ```tsx
+ * const { request } = useClient()
+ * const create = useMutation(
+ *   (vars: { title: string }) => request<Post>("/api/posts", { method: "POST", json: vars }),
+ *   { onSuccess: (post) => toast("Created"), onError: (e) => toast(e.message) },
+ * )
+ * <button disabled={create.isPending} onClick={() => create.mutate({ title })}>Save</button>
+ * ```
+ */ function useMutation(mutationFn, options = {}) {
+    const [isPending, setIsPending] = react.useState(false);
+    const [error, setError] = react.useState(null);
+    const [data, setData] = react.useState(undefined);
+    const fnRef = react.useRef(mutationFn);
+    fnRef.current = mutationFn;
+    const optionsRef = react.useRef(options);
+    optionsRef.current = options;
+    const mutateAsync = react.useCallback(async (vars)=>{
+        const opts = optionsRef.current;
+        if (await opts.onBefore?.(vars) === false) {
+            throw new Error("Mutation cancelled in onBefore");
+        }
+        setIsPending(true);
+        setError(null);
+        try {
+            const result = await fnRef.current(vars);
+            setData(result);
+            opts.onSuccess?.(result, vars);
+            return result;
+        } catch (err) {
+            const sanctumError = err;
+            setError(sanctumError);
+            opts.onError?.(sanctumError, vars);
+            throw sanctumError;
+        } finally{
+            setIsPending(false);
+            opts.onFinish?.(vars);
+        }
+    }, []);
+    const mutate = react.useCallback((vars)=>{
+        void mutateAsync(vars).catch(()=>{});
+    }, [
+        mutateAsync
+    ]);
+    const reset = react.useCallback(()=>{
+        setIsPending(false);
+        setError(null);
+        setData(undefined);
+    }, []);
+    return {
+        mutate,
+        mutateAsync,
+        isPending,
+        error,
+        data,
+        reset
+    };
+}
+
+/**
+ * Two-factor API (Fortify): challenge during login + management (enable/confirm/disable,
+ * QR, recovery codes). `challenge()` automatically refreshes the identity on success.
+ */ function useTwoFactor() {
+    return useSanctumContext().twoFactor;
+}
+
+/**
+ * Passkeys API (interop with @laravel/passkeys). `login()` automatically refreshes
+ * the identity on success. Requires the `@laravel/passkeys` package in the consumer.
+ */ function usePasskeys() {
+    return useSanctumContext().passkeys;
+}
+
+exports.ConfigError = ConfigError;
+exports.CookieTokenStorage = CookieTokenStorage;
+exports.LocalStorage = LocalStorage;
+exports.MemoryStorage = MemoryStorage;
+exports.SanctumError = SanctumError;
+exports.SanctumProvider = SanctumProvider;
+exports.ValidationError = ValidationError;
+exports.useApi = useApi;
+exports.useAuth = useAuth;
+exports.useClient = useClient;
+exports.useMutation = useMutation;
+exports.usePasskeys = usePasskeys;
+exports.useResource = useResource;
+exports.useTwoFactor = useTwoFactor;
+exports.useUser = useUser;