next-sanctum 0.1.0

package/dist/proxy.cjs

@@ -0,0 +1,49 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var server = require('next/server');
+
+/** Convert a Next-style pattern (`:param`, `:param*`, `*`) into a RegExp. */ function patternToRegExp(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/:[A-Za-z0-9_]+\*/g, ".*").replace(/:[A-Za-z0-9_]+/g, "[^/]+").replace(/\*/g, ".*");
+    return new RegExp(`^${escaped}/?$`);
+}
+function matchesAny(pathname, patterns) {
+    return patterns.some((pattern)=>patternToRegExp(pattern).test(pathname));
+}
+function hasSession(request, names) {
+    return names.some((name)=>Boolean(request.cookies.get(name)?.value));
+}
+/**
+ * Optimistic route guard for `proxy.ts` (modern Next.js). Reads cookies only —
+ * lightweight & runtime-agnostic. Real authorization stays close to the data source.
+ */ function createSanctumProxy(options = {}) {
+    const authOnly = options.authOnly ?? [];
+    const guestOnly = options.guestOnly ?? [];
+    const sessionCookies = Array.isArray(options.sessionCookie) ? options.sessionCookie : [
+        options.sessionCookie ?? "laravel_session"
+    ];
+    const onAuthOnly = options.redirect?.onAuthOnly ?? "/login";
+    const onGuestOnly = options.redirect?.onGuestOnly ?? "/";
+    const keepRequestedRoute = options.redirect?.keepRequestedRoute ?? false;
+    return function proxy(request) {
+        const { pathname, search } = request.nextUrl;
+        const authed = hasSession(request, sessionCookies);
+        if (!authed && matchesAny(pathname, authOnly)) {
+            const url = request.nextUrl.clone();
+            url.pathname = onAuthOnly;
+            url.search = "";
+            if (keepRequestedRoute) {
+                url.searchParams.set("redirect", pathname + search);
+            }
+            return server.NextResponse.redirect(url);
+        }
+        if (authed && matchesAny(pathname, guestOnly)) {
+            const url = request.nextUrl.clone();
+            url.pathname = onGuestOnly;
+            url.search = "";
+            return server.NextResponse.redirect(url);
+        }
+        return server.NextResponse.next();
+    };
+}
+
+exports.createSanctumProxy = createSanctumProxy;

package/dist/proxy.d.cts

@@ -0,0 +1,29 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+interface SanctumProxyRedirectOptions {
+    onAuthOnly?: string;
+    onGuestOnly?: string;
+    /** Persist the original path in `?redirect=` (same-origin) on auth-only redirects. */
+    keepRequestedRoute?: boolean;
+}
+interface SanctumProxyOptions {
+    /** Paths that require login (e.g. `['/dashboard/:path*']`). */
+    authOnly?: string[];
+    /** Guest-only paths (e.g. `['/login', '/register']`). */
+    guestOnly?: string[];
+    /**
+     * Session marker cookie for the OPTIMISTIC check. Defaults to `['laravel_session']`.
+     * Note: this is optimistic only — real authorization MUST live in a Server Component /
+     * Server Action (see getUser()).
+     */
+    sessionCookie?: string | string[];
+    redirect?: SanctumProxyRedirectOptions;
+}
+/**
+ * Optimistic route guard for `proxy.ts` (modern Next.js). Reads cookies only —
+ * lightweight & runtime-agnostic. Real authorization stays close to the data source.
+ */
+declare function createSanctumProxy(options?: SanctumProxyOptions): (request: NextRequest) => NextResponse;
+
+export { createSanctumProxy };
+export type { SanctumProxyOptions, SanctumProxyRedirectOptions };

package/dist/proxy.d.ts

@@ -0,0 +1,29 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+interface SanctumProxyRedirectOptions {
+    onAuthOnly?: string;
+    onGuestOnly?: string;
+    /** Persist the original path in `?redirect=` (same-origin) on auth-only redirects. */
+    keepRequestedRoute?: boolean;
+}
+interface SanctumProxyOptions {
+    /** Paths that require login (e.g. `['/dashboard/:path*']`). */
+    authOnly?: string[];
+    /** Guest-only paths (e.g. `['/login', '/register']`). */
+    guestOnly?: string[];
+    /**
+     * Session marker cookie for the OPTIMISTIC check. Defaults to `['laravel_session']`.
+     * Note: this is optimistic only — real authorization MUST live in a Server Component /
+     * Server Action (see getUser()).
+     */
+    sessionCookie?: string | string[];
+    redirect?: SanctumProxyRedirectOptions;
+}
+/**
+ * Optimistic route guard for `proxy.ts` (modern Next.js). Reads cookies only —
+ * lightweight & runtime-agnostic. Real authorization stays close to the data source.
+ */
+declare function createSanctumProxy(options?: SanctumProxyOptions): (request: NextRequest) => NextResponse;
+
+export { createSanctumProxy };
+export type { SanctumProxyOptions, SanctumProxyRedirectOptions };

package/dist/proxy.js

@@ -0,0 +1,47 @@
+import { NextResponse } from 'next/server';
+
+/** Convert a Next-style pattern (`:param`, `:param*`, `*`) into a RegExp. */ function patternToRegExp(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/:[A-Za-z0-9_]+\*/g, ".*").replace(/:[A-Za-z0-9_]+/g, "[^/]+").replace(/\*/g, ".*");
+    return new RegExp(`^${escaped}/?$`);
+}
+function matchesAny(pathname, patterns) {
+    return patterns.some((pattern)=>patternToRegExp(pattern).test(pathname));
+}
+function hasSession(request, names) {
+    return names.some((name)=>Boolean(request.cookies.get(name)?.value));
+}
+/**
+ * Optimistic route guard for `proxy.ts` (modern Next.js). Reads cookies only —
+ * lightweight & runtime-agnostic. Real authorization stays close to the data source.
+ */ function createSanctumProxy(options = {}) {
+    const authOnly = options.authOnly ?? [];
+    const guestOnly = options.guestOnly ?? [];
+    const sessionCookies = Array.isArray(options.sessionCookie) ? options.sessionCookie : [
+        options.sessionCookie ?? "laravel_session"
+    ];
+    const onAuthOnly = options.redirect?.onAuthOnly ?? "/login";
+    const onGuestOnly = options.redirect?.onGuestOnly ?? "/";
+    const keepRequestedRoute = options.redirect?.keepRequestedRoute ?? false;
+    return function proxy(request) {
+        const { pathname, search } = request.nextUrl;
+        const authed = hasSession(request, sessionCookies);
+        if (!authed && matchesAny(pathname, authOnly)) {
+            const url = request.nextUrl.clone();
+            url.pathname = onAuthOnly;
+            url.search = "";
+            if (keepRequestedRoute) {
+                url.searchParams.set("redirect", pathname + search);
+            }
+            return NextResponse.redirect(url);
+        }
+        if (authed && matchesAny(pathname, guestOnly)) {
+            const url = request.nextUrl.clone();
+            url.pathname = onGuestOnly;
+            url.search = "";
+            return NextResponse.redirect(url);
+        }
+        return NextResponse.next();
+    };
+}
+
+export { createSanctumProxy };

package/dist/server.cjs

@@ -0,0 +1,358 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+
+require('server-only');
+var headers = require('next/headers');
+
+/**
+ * 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";
+    }
+}
+
+/**
+ * Resolve the server-side base URL (`SANCTUM_BASE_URL`, falling back to the public var
+ * for dev). Shared by `server.ts`/`actions.ts`. Fails fast with a clear ConfigError.
+ */ function resolveServerBaseUrl(explicit, label = "server helpers") {
+    const baseUrl = explicit ?? process.env.SANCTUM_BASE_URL ?? process.env.NEXT_PUBLIC_SANCTUM_BASE_URL;
+    if (!baseUrl) {
+        throw new ConfigError(`SANCTUM_BASE_URL (server) is not set for next-sanctum ${label}.`);
+    }
+    return baseUrl.replace(/\/+$/, "");
+}
+
+/**
+ * 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"
+]);
+
+/**
+ * Shared Set-Cookie parsing helpers (pure — no `next`/`server-only` imports, so this
+ * stays isomorphic and tree-shakes out of the client graph). Used by `server.ts` and
+ * `actions.ts` to mirror Laravel's Set-Cookie into Next's writable cookie store.
+ */ /**
+ * Read all Set-Cookie headers as an array. Prefers `Headers.getSetCookie()` (Node ≥18.14,
+ * all supported Next runtimes). The single-header fallback only handles one cookie — we do
+ * NOT attempt to comma-split, which is unreliable (Expires dates contain commas).
+ */ function getSetCookies(headers) {
+    const anyHeaders = headers;
+    if (typeof anyHeaders.getSetCookie === "function") return anyHeaders.getSetCookie();
+    const value = headers.get("set-cookie");
+    return value ? [
+        value
+    ] : [];
+}
+/** Parse a single Set-Cookie header. Validates attributes; returns null when unusable. */ function parseSetCookie(header) {
+    const segments = header.split(";");
+    const first = segments.shift();
+    if (!first) return null;
+    const eq = first.indexOf("=");
+    if (eq === -1) return null;
+    const name = first.slice(0, eq).trim();
+    if (name === "") return null;
+    let value = first.slice(eq + 1).trim();
+    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+        value = value.slice(1, -1);
+    }
+    const options = {};
+    for (const segment of segments){
+        const idx = segment.indexOf("=");
+        const key = (idx === -1 ? segment : segment.slice(0, idx)).trim().toLowerCase();
+        const val = idx === -1 ? "" : segment.slice(idx + 1).trim();
+        switch(key){
+            case "path":
+                options.path = val;
+                break;
+            case "domain":
+                options.domain = val;
+                break;
+            case "max-age":
+                {
+                    const n = Number(val);
+                    if (val !== "" && Number.isFinite(n)) options.maxAge = n;
+                    break;
+                }
+            case "expires":
+                {
+                    const d = new Date(val);
+                    if (!Number.isNaN(d.getTime())) options.expires = d;
+                    break;
+                }
+            case "samesite":
+                {
+                    const lower = val.toLowerCase();
+                    if (lower === "lax" || lower === "strict" || lower === "none") {
+                        options.sameSite = lower;
+                    }
+                    break;
+                }
+            case "secure":
+                options.secure = true;
+                break;
+            case "httponly":
+                options.httpOnly = true;
+                break;
+        }
+    }
+    return {
+        name,
+        value,
+        options
+    };
+}
+/** Mirror a response's Set-Cookie headers into a writable cookie store. */ function applySetCookies(store, response) {
+    for (const raw of getSetCookies(response.headers)){
+        const parsed = parseSetCookie(raw);
+        if (!parsed) continue;
+        try {
+            store.set(parsed.name, parsed.value, parsed.options);
+        } catch  {
+        // store is read-only (e.g. called from a Server Component) — ignore.
+        }
+    }
+}
+
+const CSRF_COOKIE_ENDPOINT = "/sanctum/csrf-cookie";
+/**
+ * Anti-SSRF: an absolute URL is only allowed when it matches the configured base
+ * origin, otherwise the (cookie-bearing) request could be aimed at an arbitrary host.
+ */ function buildServerUrl(baseUrl, path) {
+    if (/^https?:\/\//i.test(path)) {
+        if (new URL(path).origin !== new URL(baseUrl).origin) {
+            throw new ConfigError("serverFetch: an absolute URL must match the configured base URL origin (anti-SSRF).");
+        }
+        return path;
+    }
+    return `${baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+}
+/**
+ * Authenticated fetch from a SERVER context (Server Component / Route Handler /
+ * Server Action). Forwards cookies from `await cookies()` to Laravel. For stateful
+ * requests it includes the CSRF header, bootstrapping the CSRF cookie when missing
+ * (the bootstrap can only persist cookies from a Server Action / Route Handler).
+ */ async function serverFetch(path, init = {}) {
+    const baseUrl = resolveServerBaseUrl(init.baseUrl);
+    const cookieStore = await headers.cookies();
+    const { json, body: rawBody, baseUrl: _baseUrl, csrf, ...rest } = init;
+    const headers$1 = new Headers(rest.headers);
+    if (!headers$1.has("accept")) headers$1.set("accept", "application/json");
+    // Sanctum's statefulApi() only treats a request as first-party (session/cookie
+    // auth) when its Origin/Referer matches a stateful domain. A server-side fetch
+    // carries no browser Origin, so present the API's own origin — which Sanctum
+    // always includes in its stateful domains by default — so SSR cookie auth
+    // (e.g. getUser() in a Server Component) is recognised instead of 401-ing.
+    if (!headers$1.has("origin")) headers$1.set("origin", new URL(baseUrl).origin);
+    const method = (rest.method ?? "GET").toUpperCase();
+    const csrfCookieName = csrf?.cookie ?? "XSRF-TOKEN";
+    const csrfHeaderName = csrf?.header ?? "X-XSRF-TOKEN";
+    if (STATEFUL_METHODS.has(method)) {
+        let token = cookieStore.get(csrfCookieName)?.value;
+        if (!token) {
+            const csrfResponse = await fetch(`${baseUrl}${CSRF_COOKIE_ENDPOINT}`, {
+                headers: {
+                    cookie: cookieStore.toString(),
+                    accept: "application/json"
+                },
+                cache: "no-store"
+            });
+            applySetCookies(cookieStore, csrfResponse);
+            token = cookieStore.get(csrfCookieName)?.value;
+        }
+        if (token && !headers$1.has(csrfHeaderName)) {
+            headers$1.set(csrfHeaderName, decodeURIComponent(token));
+        }
+    }
+    const cookieHeader = cookieStore.toString();
+    if (cookieHeader) headers$1.set("cookie", cookieHeader);
+    let body = rawBody ?? null;
+    if (json !== undefined) {
+        body = JSON.stringify(json);
+        if (!headers$1.has("content-type")) headers$1.set("content-type", "application/json");
+    }
+    return fetch(buildServerUrl(baseUrl, path), {
+        ...rest,
+        method,
+        headers: headers$1,
+        body,
+        cache: rest.cache ?? "no-store"
+    });
+}
+/**
+ * Fetch the authenticated user on the server (forwards cookies). The result is passed
+ * as `initialUser` to SanctumProvider to prevent a hydration mismatch. Network/parse
+ * errors resolve to `null` (treated as logged-out) so SSR doesn't crash; a missing
+ * `SANCTUM_BASE_URL` still throws (fail-fast).
+ */ async function getUser(options = {}) {
+    try {
+        const response = await serverFetch(options.endpoint ?? "/api/user", {
+            method: "GET",
+            baseUrl: options.baseUrl
+        });
+        if (!response.ok) return null;
+        return await response.json();
+    } catch (error) {
+        if (error instanceof ConfigError) throw error;
+        return null;
+    }
+}
+const FORWARD_REQUEST_HEADERS = [
+    "accept",
+    "accept-language",
+    "content-type",
+    "authorization",
+    "x-xsrf-token",
+    "x-requested-with",
+    // Sanctum's SPA (cookie) auth only treats a request as "stateful" when it
+    // carries an Origin or Referer matching SANCTUM_STATEFUL_DOMAINS. Forwarding
+    // them lets the canonical `routes/api.php` + `auth:sanctum` pattern work
+    // through this proxy. Safe: `upstream` is pinned (anti-SSRF preserved).
+    "origin",
+    "referer"
+];
+// Allowlist of response headers forwarded to the client — internal/debug headers
+// (Server, X-Powered-By, X-Debug-*, rate-limit internals, …) are stripped by default.
+const FORWARD_RESPONSE_HEADERS = [
+    "content-type",
+    "content-language",
+    "content-disposition",
+    "cache-control",
+    "etag",
+    "expires",
+    "last-modified",
+    "location",
+    "vary",
+    "www-authenticate"
+];
+/**
+ * Create a catch-all Route Handler (`app/api/sanctum/[...path]/route.ts`) that
+ * forwards requests to Laravel via the Next domain. **Anti-SSRF**: `upstream` is pinned,
+ * path traversal (`..`, `://`, backslash) is rejected, and only an allowlist of
+ * response headers (plus Set-Cookie) is forwarded — internal headers are not leaked.
+ */ function createSanctumRouteProxy(options) {
+    const upstream = options.upstream.replace(/\/+$/, "");
+    if (!/^https?:\/\//i.test(upstream)) {
+        throw new ConfigError("createSanctumRouteProxy: `upstream` must be an absolute http(s) URL (anti-SSRF).");
+    }
+    const forwardCookies = options.forwardCookies ?? true;
+    return async function handler(request, context) {
+        const { path = [] } = await context.params;
+        for (const segment of path){
+            if (segment === ".." || segment === "." || segment.includes("\\") || segment.includes("://")) {
+                return new Response("Bad request", {
+                    status: 400
+                });
+            }
+        }
+        const suffix = path.map(encodeURIComponent).join("/");
+        const search = new URL(request.url).search;
+        const target = `${upstream}/${suffix}${search}`;
+        const headers = new Headers();
+        for (const name of FORWARD_REQUEST_HEADERS){
+            const value = request.headers.get(name);
+            if (value) headers.set(name, value);
+        }
+        if (forwardCookies) {
+            const cookie = request.headers.get("cookie");
+            if (cookie) headers.set("cookie", cookie);
+        }
+        const method = request.method.toUpperCase();
+        const hasBody = method !== "GET" && method !== "HEAD";
+        const body = hasBody ? await request.arrayBuffer() : undefined;
+        const upstreamResponse = await fetch(target, {
+            method,
+            headers,
+            body,
+            redirect: "manual"
+        });
+        const responseHeaders = new Headers();
+        for (const name of FORWARD_RESPONSE_HEADERS){
+            const value = upstreamResponse.headers.get(name);
+            if (value) responseHeaders.set(name, value);
+        }
+        for (const cookie of getSetCookies(upstreamResponse.headers)){
+            responseHeaders.append("set-cookie", cookie);
+        }
+        return new Response(upstreamResponse.body, {
+            status: upstreamResponse.status,
+            headers: responseHeaders
+        });
+    };
+}
+
+exports.createSanctumRouteProxy = createSanctumRouteProxy;
+exports.getUser = getUser;
+exports.safeRedirect = safeRedirect;
+exports.serverFetch = serverFetch;

package/dist/server.d.cts

@@ -0,0 +1,78 @@
+/**
+ * Public & internal type surface of next-sanctum.
+ * TypeScript-first, generic User model, no public `any`.
+ */
+
+/** Generic user shape; consumers cast it via the generic on the client/hook. */
+type SanctumUser = Record<string, unknown>;
+
+/**
+ * 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).
+ */
+interface SafeRedirectOptions {
+    /** App origin (e.g. https://app.domain.com). When set, same-origin absolute URLs are allowed. */
+    origin?: string;
+    /** Path prefix allowlist. When set, the result must start with one of them. */
+    allowList?: string[];
+}
+/**
+ * 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.
+ */
+declare function safeRedirect(target: string | null | undefined, fallback: string, options?: SafeRedirectOptions): string;
+
+interface ServerFetchInit extends Omit<RequestInit, "body"> {
+    body?: BodyInit | null;
+    /** Shortcut for a JSON body + content-type. */
+    json?: unknown;
+    /** Override the base URL (defaults to env). */
+    baseUrl?: string;
+    /** CSRF cookie/header names (default XSRF-TOKEN / X-XSRF-TOKEN). */
+    csrf?: {
+        cookie?: string;
+        header?: string;
+    };
+}
+/**
+ * Authenticated fetch from a SERVER context (Server Component / Route Handler /
+ * Server Action). Forwards cookies from `await cookies()` to Laravel. For stateful
+ * requests it includes the CSRF header, bootstrapping the CSRF cookie when missing
+ * (the bootstrap can only persist cookies from a Server Action / Route Handler).
+ */
+declare function serverFetch(path: string, init?: ServerFetchInit): Promise<Response>;
+interface GetUserOptions {
+    baseUrl?: string;
+    /** User endpoint, default `/api/user`. */
+    endpoint?: string;
+}
+/**
+ * Fetch the authenticated user on the server (forwards cookies). The result is passed
+ * as `initialUser` to SanctumProvider to prevent a hydration mismatch. Network/parse
+ * errors resolve to `null` (treated as logged-out) so SSR doesn't crash; a missing
+ * `SANCTUM_BASE_URL` still throws (fail-fast).
+ */
+declare function getUser<TUser = SanctumUser>(options?: GetUserOptions): Promise<TUser | null>;
+interface SanctumRouteProxyOptions {
+    /** Laravel base URL — PINNED (anti-SSRF). Must be an absolute http(s) URL. */
+    upstream: string;
+    /** Forward cookies from the request (default true). */
+    forwardCookies?: boolean;
+}
+interface RouteContext {
+    params: Promise<{
+        path?: string[];
+    }>;
+}
+/**
+ * Create a catch-all Route Handler (`app/api/sanctum/[...path]/route.ts`) that
+ * forwards requests to Laravel via the Next domain. **Anti-SSRF**: `upstream` is pinned,
+ * path traversal (`..`, `://`, backslash) is rejected, and only an allowlist of
+ * response headers (plus Set-Cookie) is forwarded — internal headers are not leaked.
+ */
+declare function createSanctumRouteProxy(options: SanctumRouteProxyOptions): (request: Request, context: RouteContext) => Promise<Response>;
+
+export { createSanctumRouteProxy, getUser, safeRedirect, serverFetch };
+export type { GetUserOptions, SafeRedirectOptions, SanctumRouteProxyOptions, ServerFetchInit };

package/dist/server.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Public & internal type surface of next-sanctum.
+ * TypeScript-first, generic User model, no public `any`.
+ */
+
+/** Generic user shape; consumers cast it via the generic on the client/hook. */
+type SanctumUser = Record<string, unknown>;
+
+/**
+ * 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).
+ */
+interface SafeRedirectOptions {
+    /** App origin (e.g. https://app.domain.com). When set, same-origin absolute URLs are allowed. */
+    origin?: string;
+    /** Path prefix allowlist. When set, the result must start with one of them. */
+    allowList?: string[];
+}
+/**
+ * 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.
+ */
+declare function safeRedirect(target: string | null | undefined, fallback: string, options?: SafeRedirectOptions): string;
+
+interface ServerFetchInit extends Omit<RequestInit, "body"> {
+    body?: BodyInit | null;
+    /** Shortcut for a JSON body + content-type. */
+    json?: unknown;
+    /** Override the base URL (defaults to env). */
+    baseUrl?: string;
+    /** CSRF cookie/header names (default XSRF-TOKEN / X-XSRF-TOKEN). */
+    csrf?: {
+        cookie?: string;
+        header?: string;
+    };
+}
+/**
+ * Authenticated fetch from a SERVER context (Server Component / Route Handler /
+ * Server Action). Forwards cookies from `await cookies()` to Laravel. For stateful
+ * requests it includes the CSRF header, bootstrapping the CSRF cookie when missing
+ * (the bootstrap can only persist cookies from a Server Action / Route Handler).
+ */
+declare function serverFetch(path: string, init?: ServerFetchInit): Promise<Response>;
+interface GetUserOptions {
+    baseUrl?: string;
+    /** User endpoint, default `/api/user`. */
+    endpoint?: string;
+}
+/**
+ * Fetch the authenticated user on the server (forwards cookies). The result is passed
+ * as `initialUser` to SanctumProvider to prevent a hydration mismatch. Network/parse
+ * errors resolve to `null` (treated as logged-out) so SSR doesn't crash; a missing
+ * `SANCTUM_BASE_URL` still throws (fail-fast).
+ */
+declare function getUser<TUser = SanctumUser>(options?: GetUserOptions): Promise<TUser | null>;
+interface SanctumRouteProxyOptions {
+    /** Laravel base URL — PINNED (anti-SSRF). Must be an absolute http(s) URL. */
+    upstream: string;
+    /** Forward cookies from the request (default true). */
+    forwardCookies?: boolean;
+}
+interface RouteContext {
+    params: Promise<{
+        path?: string[];
+    }>;
+}
+/**
+ * Create a catch-all Route Handler (`app/api/sanctum/[...path]/route.ts`) that
+ * forwards requests to Laravel via the Next domain. **Anti-SSRF**: `upstream` is pinned,
+ * path traversal (`..`, `://`, backslash) is rejected, and only an allowlist of
+ * response headers (plus Set-Cookie) is forwarded — internal headers are not leaked.
+ */
+declare function createSanctumRouteProxy(options: SanctumRouteProxyOptions): (request: Request, context: RouteContext) => Promise<Response>;
+
+export { createSanctumRouteProxy, getUser, safeRedirect, serverFetch };
+export type { GetUserOptions, SafeRedirectOptions, SanctumRouteProxyOptions, ServerFetchInit };