next-sanctum 0.1.0

package/dist/server.js

@@ -0,0 +1,353 @@
+import 'server-only';
+import { cookies } from '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 cookies();
+    const { json, body: rawBody, baseUrl: _baseUrl, csrf, ...rest } = init;
+    const headers = new Headers(rest.headers);
+    if (!headers.has("accept")) headers.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.has("origin")) headers.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.has(csrfHeaderName)) {
+            headers.set(csrfHeaderName, decodeURIComponent(token));
+        }
+    }
+    const cookieHeader = cookieStore.toString();
+    if (cookieHeader) headers.set("cookie", cookieHeader);
+    let body = rawBody ?? null;
+    if (json !== undefined) {
+        body = JSON.stringify(json);
+        if (!headers.has("content-type")) headers.set("content-type", "application/json");
+    }
+    return fetch(buildServerUrl(baseUrl, path), {
+        ...rest,
+        method,
+        headers,
+        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
+        });
+    };
+}
+
+export { createSanctumRouteProxy, getUser, safeRedirect, serverFetch };

package/package.json

@@ -0,0 +1,140 @@
+{
+  "name": "next-sanctum",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "author": "aliziodev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aliziodev/next-sanctum.git"
+  },
+  "homepage": "https://github.com/aliziodev/next-sanctum#readme",
+  "bugs": "https://github.com/aliziodev/next-sanctum/issues",
+  "description": "Complete Laravel Fortify + Sanctum authentication for Next.js — cookie/CSRF SPA + token, SSR + Client, 2FA, passkeys, Proxy route protection.",
+  "keywords": [
+    "next",
+    "nextjs",
+    "laravel",
+    "sanctum",
+    "fortify",
+    "authentication",
+    "csrf",
+    "2fa",
+    "passkeys",
+    "app-router"
+  ],
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./server": {
+      "import": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.js"
+      },
+      "require": {
+        "types": "./dist/server.d.cts",
+        "default": "./dist/server.cjs"
+      }
+    },
+    "./proxy": {
+      "import": {
+        "types": "./dist/proxy.d.ts",
+        "default": "./dist/proxy.js"
+      },
+      "require": {
+        "types": "./dist/proxy.d.cts",
+        "default": "./dist/proxy.cjs"
+      }
+    },
+    "./actions": {
+      "import": {
+        "types": "./dist/actions.d.ts",
+        "default": "./dist/actions.js"
+      },
+      "require": {
+        "types": "./dist/actions.d.cts",
+        "default": "./dist/actions.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "server": [
+        "./dist/server.d.ts"
+      ],
+      "proxy": [
+        "./dist/proxy.d.ts"
+      ],
+      "actions": [
+        "./dist/actions.d.ts"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "bunchee",
+    "dev": "bunchee --watch",
+    "clean": "rimraf dist",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "attw": "attw --pack .",
+    "prepublishOnly": "pnpm run typecheck && pnpm run test && pnpm run build && pnpm run attw"
+  },
+  "peerDependencies": {
+    "@laravel/passkeys": "*",
+    "next": ">=15.0.0 <17.0.0",
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@laravel/passkeys": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "server-only": "^0.0.1"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.0",
+    "@eslint/js": "^9.0.0",
+    "@testing-library/react": "^16.0.0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitest/coverage-v8": "^3.2.6",
+    "bunchee": "^6.4.0",
+    "eslint": "^9.0.0",
+    "happy-dom": "^15.0.0",
+    "msw": "^2.7.0",
+    "next": "16.2.6",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.0.0"
+  }
+}