@poly-x/next 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,60 @@
+# @poly-x/next
+
+PolyX authentication for the Next.js App Router. Everything in `@poly-x/react`,
+plus a server side: tokens live **AES-GCM-encrypted in an httpOnly cookie on your
+own domain** — browser JavaScript never sees them.
+
+## Install
+
+```bash
+npm install @poly-x/next
+```
+
+Set two env vars: `NEXT_PUBLIC_POLYX_PUBLISHABLE_KEY` (the `pk_…` key) and
+`POLYX_SESSION_SECRET` (used to encrypt the session cookie).
+
+## Client
+
+The client entry re-exports `@poly-x/react` — `PolyXProvider`, hooks, `<SignIn>`,
+`<Protected>`, and friends:
+
+```tsx
+import { PolyXProvider } from "@poly-x/next";
+```
+
+## Server
+
+Read the session in a Server Component or route handler (read-only — Server
+Components can't set cookies):
+
+```ts
+import { auth } from "@poly-x/next/server";
+
+export default async function Page() {
+  const { isSignedIn, userId } = await auth();
+  // …
+}
+```
+
+Mount the route handlers that own every cookie write (login / callback / refresh
+/ signout):
+
+```ts
+// app/api/polyx/[...action]/route.ts
+import { createAuthHandlers } from "@poly-x/next/server";
+export const { signin: GET } = createAuthHandlers();
+```
+
+Gate routes with the proxy (Next 16 `proxy.ts`; `middleware.ts` on ≤15):
+
+```ts
+import { proxy } from "@poly-x/next/proxy";
+export const proxy = proxyHandler; // from proxy({ protectedRoutes: ["/dashboard"] })
+```
+
+## Exports
+
+`@poly-x/next` (client) · `@poly-x/next/server` (`auth`, `createAuthHandlers`,
+`ServerSession`) · `@poly-x/next/proxy` (`proxy`).
+
+MIT licensed.

package/dist/index.cjs

@@ -0,0 +1,17 @@
+"use client";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/index.ts
+const PACKAGE_NAME = "@poly-x/next";
+const version = "0.0.0";
+//#endregion
+exports.PACKAGE_NAME = PACKAGE_NAME;
+exports.version = version;
+var _poly_x_react = require("@poly-x/react");
+Object.keys(_poly_x_react).forEach(function(k) {
+	if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function() {
+			return _poly_x_react[k];
+		}
+	});
+});

package/dist/index.d.cts

@@ -0,0 +1,7 @@
+export * from "@poly-x/react";
+
+//#region src/index.d.ts
+declare const PACKAGE_NAME = "@poly-x/next";
+declare const version = "0.0.0";
+//#endregion
+export { PACKAGE_NAME, version };

package/dist/index.d.mts

@@ -0,0 +1,7 @@
+export * from "@poly-x/react";
+
+//#region src/index.d.ts
+declare const PACKAGE_NAME = "@poly-x/next";
+declare const version = "0.0.0";
+//#endregion
+export { PACKAGE_NAME, version };

package/dist/index.mjs

@@ -0,0 +1,7 @@
+"use client";
+export * from "@poly-x/react";
+//#region src/index.ts
+const PACKAGE_NAME = "@poly-x/next";
+const version = "0.0.0";
+//#endregion
+export { PACKAGE_NAME, version };

package/dist/proxy.cjs

@@ -0,0 +1,24 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("./server-session-YbnXBt3c.cjs");
+let next_server = require("next/server");
+//#region src/proxy.ts
+/**
+* @poly-x/next/proxy — route gating (F007). In Next 16 this is wired via
+* `proxy.ts` (`export { proxy as proxy }`); on ≤15 it's `middleware.ts`. It
+* gates on the session cookie's *presence* (a fast edge check) and redirects
+* signed-out users to sign-in; `auth()` does the real decrypt server-side.
+*/
+function isProtected(pathname, routes) {
+	return routes.some((route) => typeof route === "string" ? pathname.startsWith(route) : route.test(pathname));
+}
+function proxy(config) {
+	const cookieName = config.cookieName ?? "polyx_session";
+	const signInPath = config.signInPath ?? "/api/polyx/signin";
+	return (request) => {
+		if (!isProtected(request.nextUrl.pathname, config.protectedRoutes)) return next_server.NextResponse.next();
+		if (request.cookies.get(cookieName)?.value) return next_server.NextResponse.next();
+		return next_server.NextResponse.redirect(new URL(signInPath, request.url));
+	};
+}
+//#endregion
+exports.proxy = proxy;

package/dist/proxy.d.cts

@@ -0,0 +1,13 @@
+import { NextRequest, NextResponse } from "next/server";
+
+//#region src/proxy.d.ts
+interface ProxyConfig {
+  /** Path prefixes or patterns that require a session. */
+  protectedRoutes: Array<string | RegExp>;
+  /** Where to send signed-out users. Default `/api/polyx/signin`. */
+  signInPath?: string;
+  cookieName?: string;
+}
+declare function proxy(config: ProxyConfig): (request: NextRequest) => NextResponse;
+//#endregion
+export { ProxyConfig, proxy };

package/dist/proxy.d.mts

@@ -0,0 +1,13 @@
+import { NextRequest, NextResponse } from "next/server";
+
+//#region src/proxy.d.ts
+interface ProxyConfig {
+  /** Path prefixes or patterns that require a session. */
+  protectedRoutes: Array<string | RegExp>;
+  /** Where to send signed-out users. Default `/api/polyx/signin`. */
+  signInPath?: string;
+  cookieName?: string;
+}
+declare function proxy(config: ProxyConfig): (request: NextRequest) => NextResponse;
+//#endregion
+export { ProxyConfig, proxy };

package/dist/proxy.mjs

@@ -0,0 +1,23 @@
+import "./server-session-B3zJ7CS8.mjs";
+import { NextResponse } from "next/server";
+//#region src/proxy.ts
+/**
+* @poly-x/next/proxy — route gating (F007). In Next 16 this is wired via
+* `proxy.ts` (`export { proxy as proxy }`); on ≤15 it's `middleware.ts`. It
+* gates on the session cookie's *presence* (a fast edge check) and redirects
+* signed-out users to sign-in; `auth()` does the real decrypt server-side.
+*/
+function isProtected(pathname, routes) {
+	return routes.some((route) => typeof route === "string" ? pathname.startsWith(route) : route.test(pathname));
+}
+function proxy(config) {
+	const cookieName = config.cookieName ?? "polyx_session";
+	const signInPath = config.signInPath ?? "/api/polyx/signin";
+	return (request) => {
+		if (!isProtected(request.nextUrl.pathname, config.protectedRoutes)) return NextResponse.next();
+		if (request.cookies.get(cookieName)?.value) return NextResponse.next();
+		return NextResponse.redirect(new URL(signInPath, request.url));
+	};
+}
+//#endregion
+export { proxy };

package/dist/server-session-B3zJ7CS8.mjs

@@ -0,0 +1,130 @@
+import { SessionExpiredError, SessionRevokedError } from "@poly-x/core";
+//#region src/cookie-adapter.ts
+/** Default attributes for the session cookie (ADR-0004 secure custody). */
+const SESSION_COOKIE_OPTIONS = {
+	httpOnly: true,
+	secure: true,
+	sameSite: "lax",
+	path: "/"
+};
+//#endregion
+//#region src/cookie-codec.ts
+const IV_BYTES = 12;
+function base64UrlEncode(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(text) {
+	const base64 = text.replace(/-/g, "+").replace(/_/g, "/");
+	const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+	const binary = atob(padded);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+async function deriveKey(secret) {
+	const hash = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(secret));
+	return crypto.subtle.importKey("raw", hash, "AES-GCM", false, ["encrypt", "decrypt"]);
+}
+async function sealSession(session, secret) {
+	const key = await deriveKey(secret);
+	const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+	const plaintext = new TextEncoder().encode(JSON.stringify(session));
+	const ciphertext = new Uint8Array(await crypto.subtle.encrypt({
+		name: "AES-GCM",
+		iv
+	}, key, plaintext));
+	const packed = new Uint8Array(iv.length + ciphertext.length);
+	packed.set(iv);
+	packed.set(ciphertext, iv.length);
+	return base64UrlEncode(packed);
+}
+async function openSession(token, secret) {
+	try {
+		const packed = base64UrlDecode(token);
+		if (packed.length <= IV_BYTES) return null;
+		const iv = packed.slice(0, IV_BYTES);
+		const ciphertext = packed.slice(IV_BYTES);
+		const key = await deriveKey(secret);
+		const plaintext = await crypto.subtle.decrypt({
+			name: "AES-GCM",
+			iv
+		}, key, ciphertext);
+		return JSON.parse(new TextDecoder().decode(plaintext));
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/server-session.ts
+/**
+* The framework-agnostic BFF session controller (F007): tokens sealed in an
+* httpOnly cookie on the consumer's domain, exchanged/refreshed server-side.
+* Composes core's AuthClient with a CookieAdapter seam; fully unit-testable.
+*/
+const DEFAULT_SESSION_COOKIE = "polyx_session";
+var ServerSession = class {
+	authClient;
+	secret;
+	cookies;
+	cookieName;
+	constructor(options) {
+		this.authClient = options.authClient;
+		this.secret = options.secret;
+		this.cookies = options.cookies;
+		this.cookieName = options.cookieName ?? "polyx_session";
+	}
+	async establishFromCode(code, codeVerifier, redirectUri) {
+		const stored = await this.authClient.exchangeCode({
+			code,
+			codeVerifier,
+			redirectUri
+		});
+		await this.write(stored);
+		return stored;
+	}
+	async read() {
+		const raw = this.cookies.get(this.cookieName);
+		if (!raw) return null;
+		return openSession(raw, this.secret);
+	}
+	/** Rotate the tokens; clears the cookie (returns null) on a terminal refresh failure. */
+	async refresh() {
+		const current = await this.read();
+		if (!current) return null;
+		try {
+			const next = await this.authClient.createRefresher()(current);
+			await this.write(next);
+			return next;
+		} catch (error) {
+			if (error instanceof SessionRevokedError || error instanceof SessionExpiredError) {
+				this.clear();
+				return null;
+			}
+			throw error;
+		}
+	}
+	clear() {
+		this.cookies.delete(this.cookieName);
+	}
+	async write(session) {
+		const sealed = await sealSession(session, this.secret);
+		this.cookies.set(this.cookieName, sealed, SESSION_COOKIE_OPTIONS);
+	}
+};
+function toAuthContext(session) {
+	if (!session) return {
+		isSignedIn: false,
+		userId: null,
+		claims: null
+	};
+	return {
+		isSignedIn: true,
+		userId: session.session.claims.userId,
+		organizationId: session.session.claims.organizationId,
+		claims: session.session.claims
+	};
+}
+//#endregion
+export { sealSession as a, openSession as i, ServerSession as n, toAuthContext as r, DEFAULT_SESSION_COOKIE as t };

package/dist/server-session-YbnXBt3c.cjs

@@ -0,0 +1,159 @@
+let _poly_x_core = require("@poly-x/core");
+//#region src/cookie-adapter.ts
+/** Default attributes for the session cookie (ADR-0004 secure custody). */
+const SESSION_COOKIE_OPTIONS = {
+	httpOnly: true,
+	secure: true,
+	sameSite: "lax",
+	path: "/"
+};
+//#endregion
+//#region src/cookie-codec.ts
+const IV_BYTES = 12;
+function base64UrlEncode(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(text) {
+	const base64 = text.replace(/-/g, "+").replace(/_/g, "/");
+	const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+	const binary = atob(padded);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+async function deriveKey(secret) {
+	const hash = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(secret));
+	return crypto.subtle.importKey("raw", hash, "AES-GCM", false, ["encrypt", "decrypt"]);
+}
+async function sealSession(session, secret) {
+	const key = await deriveKey(secret);
+	const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+	const plaintext = new TextEncoder().encode(JSON.stringify(session));
+	const ciphertext = new Uint8Array(await crypto.subtle.encrypt({
+		name: "AES-GCM",
+		iv
+	}, key, plaintext));
+	const packed = new Uint8Array(iv.length + ciphertext.length);
+	packed.set(iv);
+	packed.set(ciphertext, iv.length);
+	return base64UrlEncode(packed);
+}
+async function openSession(token, secret) {
+	try {
+		const packed = base64UrlDecode(token);
+		if (packed.length <= IV_BYTES) return null;
+		const iv = packed.slice(0, IV_BYTES);
+		const ciphertext = packed.slice(IV_BYTES);
+		const key = await deriveKey(secret);
+		const plaintext = await crypto.subtle.decrypt({
+			name: "AES-GCM",
+			iv
+		}, key, ciphertext);
+		return JSON.parse(new TextDecoder().decode(plaintext));
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/server-session.ts
+/**
+* The framework-agnostic BFF session controller (F007): tokens sealed in an
+* httpOnly cookie on the consumer's domain, exchanged/refreshed server-side.
+* Composes core's AuthClient with a CookieAdapter seam; fully unit-testable.
+*/
+const DEFAULT_SESSION_COOKIE = "polyx_session";
+var ServerSession = class {
+	authClient;
+	secret;
+	cookies;
+	cookieName;
+	constructor(options) {
+		this.authClient = options.authClient;
+		this.secret = options.secret;
+		this.cookies = options.cookies;
+		this.cookieName = options.cookieName ?? "polyx_session";
+	}
+	async establishFromCode(code, codeVerifier, redirectUri) {
+		const stored = await this.authClient.exchangeCode({
+			code,
+			codeVerifier,
+			redirectUri
+		});
+		await this.write(stored);
+		return stored;
+	}
+	async read() {
+		const raw = this.cookies.get(this.cookieName);
+		if (!raw) return null;
+		return openSession(raw, this.secret);
+	}
+	/** Rotate the tokens; clears the cookie (returns null) on a terminal refresh failure. */
+	async refresh() {
+		const current = await this.read();
+		if (!current) return null;
+		try {
+			const next = await this.authClient.createRefresher()(current);
+			await this.write(next);
+			return next;
+		} catch (error) {
+			if (error instanceof _poly_x_core.SessionRevokedError || error instanceof _poly_x_core.SessionExpiredError) {
+				this.clear();
+				return null;
+			}
+			throw error;
+		}
+	}
+	clear() {
+		this.cookies.delete(this.cookieName);
+	}
+	async write(session) {
+		const sealed = await sealSession(session, this.secret);
+		this.cookies.set(this.cookieName, sealed, SESSION_COOKIE_OPTIONS);
+	}
+};
+function toAuthContext(session) {
+	if (!session) return {
+		isSignedIn: false,
+		userId: null,
+		claims: null
+	};
+	return {
+		isSignedIn: true,
+		userId: session.session.claims.userId,
+		organizationId: session.session.claims.organizationId,
+		claims: session.session.claims
+	};
+}
+//#endregion
+Object.defineProperty(exports, "DEFAULT_SESSION_COOKIE", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_SESSION_COOKIE;
+	}
+});
+Object.defineProperty(exports, "ServerSession", {
+	enumerable: true,
+	get: function() {
+		return ServerSession;
+	}
+});
+Object.defineProperty(exports, "openSession", {
+	enumerable: true,
+	get: function() {
+		return openSession;
+	}
+});
+Object.defineProperty(exports, "sealSession", {
+	enumerable: true,
+	get: function() {
+		return sealSession;
+	}
+});
+Object.defineProperty(exports, "toAuthContext", {
+	enumerable: true,
+	get: function() {
+		return toAuthContext;
+	}
+});

package/dist/server.cjs

@@ -0,0 +1,127 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_server_session = require("./server-session-YbnXBt3c.cjs");
+let _poly_x_core = require("@poly-x/core");
+let next_headers = require("next/headers");
+//#region src/config.ts
+function resolveNextConfig(overrides = {}) {
+	const publishableKey = overrides.publishableKey ?? process.env.NEXT_PUBLIC_POLYX_PUBLISHABLE_KEY;
+	const secret = overrides.secret ?? process.env.POLYX_SESSION_SECRET;
+	if (!publishableKey) throw new Error("PolyX: missing publishable key (set NEXT_PUBLIC_POLYX_PUBLISHABLE_KEY or pass config.publishableKey).");
+	if (!secret) throw new Error("PolyX: missing POLYX_SESSION_SECRET (needed to encrypt the session cookie).");
+	return {
+		publishableKey,
+		secret,
+		baseUrl: overrides.baseUrl ?? process.env.POLYX_BASE_URL
+	};
+}
+function buildServerAuthClient(config) {
+	return new _poly_x_core.AuthClient({
+		config: (0, _poly_x_core.resolveConfig)({
+			key: config.publishableKey,
+			baseUrl: config.baseUrl,
+			context: "server"
+		}),
+		transport: new _poly_x_core.FetchTransport()
+	});
+}
+//#endregion
+//#region src/server.ts
+/**
+* @poly-x/next/server — App Router server helpers (F007). `auth()` reads the
+* httpOnly session cookie (usable in RSC — read-only); `createAuthHandlers()`
+* returns the route handlers that do every cookie write (login/callback/refresh/
+* signout), since Server Components can't set cookies.
+*/
+const VERIFIER_COOKIE = "polyx_pkce";
+const VERIFIER_MAX_AGE = 600;
+function adapt(store) {
+	return {
+		get: (name) => store.get(name)?.value,
+		set: (name, value, options) => store.set(name, value, options),
+		delete: (name) => store.delete(name)
+	};
+}
+async function requestCookies() {
+	return adapt(await (0, next_headers.cookies)());
+}
+/** Read the current session — safe in Server Components (no cookie write). */
+async function auth(overrides) {
+	const config = resolveNextConfig(overrides);
+	return require_server_session.toAuthContext(await new require_server_session.ServerSession({
+		authClient: buildServerAuthClient(config),
+		secret: config.secret,
+		cookies: await requestCookies()
+	}).read());
+}
+function createAuthHandlers(handlersConfig = {}) {
+	const callbackPath = handlersConfig.callbackPath ?? "/api/polyx/callback";
+	const afterSignInPath = handlersConfig.afterSignInPath ?? "/";
+	function newSession(store, config) {
+		return new require_server_session.ServerSession({
+			authClient: buildServerAuthClient(config),
+			secret: config.secret,
+			cookies: store
+		});
+	}
+	return {
+		async signin(request) {
+			const config = resolveNextConfig(handlersConfig);
+			const redirectUri = `${new URL(request.url).origin}${callbackPath}`;
+			const { verifier, challenge } = await (0, _poly_x_core.generatePkce)();
+			const state = (0, _poly_x_core.randomState)();
+			(await (0, next_headers.cookies)()).set(VERIFIER_COOKIE, JSON.stringify({
+				verifier,
+				state,
+				redirectUri
+			}), {
+				httpOnly: true,
+				secure: true,
+				sameSite: "lax",
+				path: "/",
+				maxAge: VERIFIER_MAX_AGE
+			});
+			const url = buildServerAuthClient(config).buildAuthorizeUrl({
+				redirectUri,
+				state,
+				challenge
+			});
+			return Response.redirect(url, 302);
+		},
+		async callback(request) {
+			const config = resolveNextConfig(handlersConfig);
+			const url = new URL(request.url);
+			const code = url.searchParams.get("code");
+			const state = url.searchParams.get("state");
+			const store = await (0, next_headers.cookies)();
+			const raw = store.get(VERIFIER_COOKIE)?.value;
+			store.delete(VERIFIER_COOKIE);
+			const home = `${url.origin}${afterSignInPath}`;
+			if (!code || !state || !raw) return Response.redirect(home, 302);
+			const tx = JSON.parse(raw);
+			if (tx.state !== state) return Response.redirect(home, 302);
+			await newSession(adapt(store), config).establishFromCode(code, tx.verifier, tx.redirectUri);
+			return Response.redirect(home, 302);
+		},
+		async refresh() {
+			const config = resolveNextConfig(handlersConfig);
+			const session = await newSession(await requestCookies(), config).refresh();
+			return Response.json({ isSignedIn: session !== null }, { status: session ? 200 : 401 });
+		},
+		async signout(request) {
+			const config = resolveNextConfig(handlersConfig);
+			newSession(adapt(await (0, next_headers.cookies)()), config).clear();
+			try {
+				await buildServerAuthClient(config).logout("device");
+			} catch {}
+			return Response.redirect(new URL(request.url).origin + "/", 302);
+		}
+	};
+}
+//#endregion
+exports.DEFAULT_SESSION_COOKIE = require_server_session.DEFAULT_SESSION_COOKIE;
+exports.ServerSession = require_server_session.ServerSession;
+exports.auth = auth;
+exports.createAuthHandlers = createAuthHandlers;
+exports.openSession = require_server_session.openSession;
+exports.resolveNextConfig = resolveNextConfig;
+exports.sealSession = require_server_session.sealSession;

package/dist/server.d.cts

@@ -0,0 +1,80 @@
+import { AuthClient, StoredSession } from "@poly-x/core";
+
+//#region src/config.d.ts
+interface NextServerConfig {
+  publishableKey: string;
+  /** Secret for encrypting the session cookie (AES-GCM key derivation). */
+  secret: string;
+  baseUrl?: string;
+}
+declare function resolveNextConfig(overrides?: Partial<NextServerConfig>): NextServerConfig;
+//#endregion
+//#region src/cookie-adapter.d.ts
+/**
+ * Cookie access behind a seam so the server-session core is testable without a
+ * Next runtime. The Next adapter (built from an awaited `cookies()` store) lives
+ * in server.ts / proxy.ts; a fake backs the unit tests.
+ */
+interface CookieSetOptions {
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: "lax" | "strict" | "none";
+  path?: string;
+  maxAge?: number;
+}
+interface CookieAdapter {
+  get(name: string): string | undefined;
+  set(name: string, value: string, options?: CookieSetOptions): void;
+  delete(name: string): void;
+}
+//#endregion
+//#region src/server-session.d.ts
+declare const DEFAULT_SESSION_COOKIE = "polyx_session";
+interface ServerSessionOptions {
+  authClient: AuthClient;
+  secret: string;
+  cookies: CookieAdapter;
+  cookieName?: string;
+}
+declare class ServerSession {
+  private readonly authClient;
+  private readonly secret;
+  private readonly cookies;
+  private readonly cookieName;
+  constructor(options: ServerSessionOptions);
+  establishFromCode(code: string, codeVerifier: string, redirectUri: string): Promise<StoredSession>;
+  read(): Promise<StoredSession | null>;
+  /** Rotate the tokens; clears the cookie (returns null) on a terminal refresh failure. */
+  refresh(): Promise<StoredSession | null>;
+  clear(): void;
+  private write;
+}
+interface AuthContext {
+  isSignedIn: boolean;
+  userId: string | null;
+  organizationId?: string;
+  claims: StoredSession["session"]["claims"] | null;
+}
+//#endregion
+//#region src/cookie-codec.d.ts
+declare function sealSession(session: StoredSession, secret: string): Promise<string>;
+declare function openSession(token: string, secret: string): Promise<StoredSession | null>;
+//#endregion
+//#region src/server.d.ts
+/** Read the current session — safe in Server Components (no cookie write). */
+declare function auth(overrides?: Partial<NextServerConfig>): Promise<AuthContext>;
+interface AuthHandlersConfig extends Partial<NextServerConfig> {
+  /** Where to send the user after a successful sign-in. Default `/`. */
+  afterSignInPath?: string;
+  /** The callback route path this app mounts. Default `/api/polyx/callback`. */
+  callbackPath?: string;
+}
+interface AuthHandlers {
+  signin(request: Request): Promise<Response>;
+  callback(request: Request): Promise<Response>;
+  refresh(request: Request): Promise<Response>;
+  signout(request: Request): Promise<Response>;
+}
+declare function createAuthHandlers(handlersConfig?: AuthHandlersConfig): AuthHandlers;
+//#endregion
+export { type AuthContext, AuthHandlers, AuthHandlersConfig, type CookieAdapter, type CookieSetOptions, DEFAULT_SESSION_COOKIE, type NextServerConfig, ServerSession, auth, createAuthHandlers, openSession, resolveNextConfig, sealSession };

package/dist/server.d.mts

@@ -0,0 +1,80 @@
+import { AuthClient, StoredSession } from "@poly-x/core";
+
+//#region src/config.d.ts
+interface NextServerConfig {
+  publishableKey: string;
+  /** Secret for encrypting the session cookie (AES-GCM key derivation). */
+  secret: string;
+  baseUrl?: string;
+}
+declare function resolveNextConfig(overrides?: Partial<NextServerConfig>): NextServerConfig;
+//#endregion
+//#region src/cookie-adapter.d.ts
+/**
+ * Cookie access behind a seam so the server-session core is testable without a
+ * Next runtime. The Next adapter (built from an awaited `cookies()` store) lives
+ * in server.ts / proxy.ts; a fake backs the unit tests.
+ */
+interface CookieSetOptions {
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: "lax" | "strict" | "none";
+  path?: string;
+  maxAge?: number;
+}
+interface CookieAdapter {
+  get(name: string): string | undefined;
+  set(name: string, value: string, options?: CookieSetOptions): void;
+  delete(name: string): void;
+}
+//#endregion
+//#region src/server-session.d.ts
+declare const DEFAULT_SESSION_COOKIE = "polyx_session";
+interface ServerSessionOptions {
+  authClient: AuthClient;
+  secret: string;
+  cookies: CookieAdapter;
+  cookieName?: string;
+}
+declare class ServerSession {
+  private readonly authClient;
+  private readonly secret;
+  private readonly cookies;
+  private readonly cookieName;
+  constructor(options: ServerSessionOptions);
+  establishFromCode(code: string, codeVerifier: string, redirectUri: string): Promise<StoredSession>;
+  read(): Promise<StoredSession | null>;
+  /** Rotate the tokens; clears the cookie (returns null) on a terminal refresh failure. */
+  refresh(): Promise<StoredSession | null>;
+  clear(): void;
+  private write;
+}
+interface AuthContext {
+  isSignedIn: boolean;
+  userId: string | null;
+  organizationId?: string;
+  claims: StoredSession["session"]["claims"] | null;
+}
+//#endregion
+//#region src/cookie-codec.d.ts
+declare function sealSession(session: StoredSession, secret: string): Promise<string>;
+declare function openSession(token: string, secret: string): Promise<StoredSession | null>;
+//#endregion
+//#region src/server.d.ts
+/** Read the current session — safe in Server Components (no cookie write). */
+declare function auth(overrides?: Partial<NextServerConfig>): Promise<AuthContext>;
+interface AuthHandlersConfig extends Partial<NextServerConfig> {
+  /** Where to send the user after a successful sign-in. Default `/`. */
+  afterSignInPath?: string;
+  /** The callback route path this app mounts. Default `/api/polyx/callback`. */
+  callbackPath?: string;
+}
+interface AuthHandlers {
+  signin(request: Request): Promise<Response>;
+  callback(request: Request): Promise<Response>;
+  refresh(request: Request): Promise<Response>;
+  signout(request: Request): Promise<Response>;
+}
+declare function createAuthHandlers(handlersConfig?: AuthHandlersConfig): AuthHandlers;
+//#endregion
+export { type AuthContext, AuthHandlers, AuthHandlersConfig, type CookieAdapter, type CookieSetOptions, DEFAULT_SESSION_COOKIE, type NextServerConfig, ServerSession, auth, createAuthHandlers, openSession, resolveNextConfig, sealSession };

package/dist/server.mjs

@@ -0,0 +1,120 @@
+import { a as sealSession, i as openSession, n as ServerSession, r as toAuthContext, t as DEFAULT_SESSION_COOKIE } from "./server-session-B3zJ7CS8.mjs";
+import { AuthClient, FetchTransport, generatePkce, randomState, resolveConfig } from "@poly-x/core";
+import { cookies } from "next/headers";
+//#region src/config.ts
+function resolveNextConfig(overrides = {}) {
+	const publishableKey = overrides.publishableKey ?? process.env.NEXT_PUBLIC_POLYX_PUBLISHABLE_KEY;
+	const secret = overrides.secret ?? process.env.POLYX_SESSION_SECRET;
+	if (!publishableKey) throw new Error("PolyX: missing publishable key (set NEXT_PUBLIC_POLYX_PUBLISHABLE_KEY or pass config.publishableKey).");
+	if (!secret) throw new Error("PolyX: missing POLYX_SESSION_SECRET (needed to encrypt the session cookie).");
+	return {
+		publishableKey,
+		secret,
+		baseUrl: overrides.baseUrl ?? process.env.POLYX_BASE_URL
+	};
+}
+function buildServerAuthClient(config) {
+	return new AuthClient({
+		config: resolveConfig({
+			key: config.publishableKey,
+			baseUrl: config.baseUrl,
+			context: "server"
+		}),
+		transport: new FetchTransport()
+	});
+}
+//#endregion
+//#region src/server.ts
+/**
+* @poly-x/next/server — App Router server helpers (F007). `auth()` reads the
+* httpOnly session cookie (usable in RSC — read-only); `createAuthHandlers()`
+* returns the route handlers that do every cookie write (login/callback/refresh/
+* signout), since Server Components can't set cookies.
+*/
+const VERIFIER_COOKIE = "polyx_pkce";
+const VERIFIER_MAX_AGE = 600;
+function adapt(store) {
+	return {
+		get: (name) => store.get(name)?.value,
+		set: (name, value, options) => store.set(name, value, options),
+		delete: (name) => store.delete(name)
+	};
+}
+async function requestCookies() {
+	return adapt(await cookies());
+}
+/** Read the current session — safe in Server Components (no cookie write). */
+async function auth(overrides) {
+	const config = resolveNextConfig(overrides);
+	return toAuthContext(await new ServerSession({
+		authClient: buildServerAuthClient(config),
+		secret: config.secret,
+		cookies: await requestCookies()
+	}).read());
+}
+function createAuthHandlers(handlersConfig = {}) {
+	const callbackPath = handlersConfig.callbackPath ?? "/api/polyx/callback";
+	const afterSignInPath = handlersConfig.afterSignInPath ?? "/";
+	function newSession(store, config) {
+		return new ServerSession({
+			authClient: buildServerAuthClient(config),
+			secret: config.secret,
+			cookies: store
+		});
+	}
+	return {
+		async signin(request) {
+			const config = resolveNextConfig(handlersConfig);
+			const redirectUri = `${new URL(request.url).origin}${callbackPath}`;
+			const { verifier, challenge } = await generatePkce();
+			const state = randomState();
+			(await cookies()).set(VERIFIER_COOKIE, JSON.stringify({
+				verifier,
+				state,
+				redirectUri
+			}), {
+				httpOnly: true,
+				secure: true,
+				sameSite: "lax",
+				path: "/",
+				maxAge: VERIFIER_MAX_AGE
+			});
+			const url = buildServerAuthClient(config).buildAuthorizeUrl({
+				redirectUri,
+				state,
+				challenge
+			});
+			return Response.redirect(url, 302);
+		},
+		async callback(request) {
+			const config = resolveNextConfig(handlersConfig);
+			const url = new URL(request.url);
+			const code = url.searchParams.get("code");
+			const state = url.searchParams.get("state");
+			const store = await cookies();
+			const raw = store.get(VERIFIER_COOKIE)?.value;
+			store.delete(VERIFIER_COOKIE);
+			const home = `${url.origin}${afterSignInPath}`;
+			if (!code || !state || !raw) return Response.redirect(home, 302);
+			const tx = JSON.parse(raw);
+			if (tx.state !== state) return Response.redirect(home, 302);
+			await newSession(adapt(store), config).establishFromCode(code, tx.verifier, tx.redirectUri);
+			return Response.redirect(home, 302);
+		},
+		async refresh() {
+			const config = resolveNextConfig(handlersConfig);
+			const session = await newSession(await requestCookies(), config).refresh();
+			return Response.json({ isSignedIn: session !== null }, { status: session ? 200 : 401 });
+		},
+		async signout(request) {
+			const config = resolveNextConfig(handlersConfig);
+			newSession(adapt(await cookies()), config).clear();
+			try {
+				await buildServerAuthClient(config).logout("device");
+			} catch {}
+			return Response.redirect(new URL(request.url).origin + "/", 302);
+		}
+	};
+}
+//#endregion
+export { DEFAULT_SESSION_COOKIE, ServerSession, auth, createAuthHandlers, openSession, resolveNextConfig, sealSession };

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@poly-x/next",
+  "version": "0.1.0-alpha.0",
+  "description": "PolyX SDK for Next.js App Router - components plus server helpers",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./server": {
+      "import": {
+        "types": "./dist/server.d.mts",
+        "default": "./dist/server.mjs"
+      },
+      "require": {
+        "types": "./dist/server.d.cts",
+        "default": "./dist/server.cjs"
+      }
+    },
+    "./proxy": {
+      "import": {
+        "types": "./dist/proxy.d.mts",
+        "default": "./dist/proxy.mjs"
+      },
+      "require": {
+        "types": "./dist/proxy.d.cts",
+        "default": "./dist/proxy.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "dependencies": {
+    "@poly-x/react": "0.1.0-alpha.0",
+    "@poly-x/core": "0.1.0-alpha.0"
+  },
+  "peerDependencies": {
+    "next": ">=14",
+    "react": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://dev.azure.com/waiindustries/wAI%20Engineering/_git/poly-x-sdk"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.17",
+    "next": "^16.2.10",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "lint": "eslint src"
+  }
+}