@poly-x/next 0.1.0-alpha.9 → 0.1.1

package/dist/proxy.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-require("./server-session-DmR0ZJqP.cjs");
+require("./server-session-Df9HXl_5.cjs");
 let next_server = require("next/server");
 //#region src/proxy.ts
 /**

package/dist/proxy.mjs

@@ -1,4 +1,4 @@
-import "./server-session-CXVB1Rgx.mjs";
+import "./server-session-pY-nzh5x.mjs";
 import { NextResponse } from "next/server";
 //#region src/proxy.ts
 /**

package/dist/{server-session-DmR0ZJqP.cjs → server-session-Df9HXl_5.cjs}

@@ -1,23 +1,45 @@
 let _poly_x_core = require("@poly-x/core");
-//#region src/cookie-adapter.ts
+//#region src/cookie-codec.ts
 /**
-* Attributes for the session cookie (ADR-0004 secure custody). `secure` is decided at
-* write time from the actual transport: a `Secure` cookie is silently dropped by the
-* browser over plain http, so http/localhost dev must set `secure:false` while https
-* always sets `secure:true`. This is not a downgrade — `Secure` carries no meaning on
-* http; setting it there just breaks the session. httpOnly/sameSite/path are unchanged.
+* AES-GCM sealing of the session cookie (F007 / ADR-0004). The key is derived
+* (SHA-256) from the consumer's `POLYX_SESSION_SECRET`; AES-GCM gives
+* confidentiality + tamper-detection together, so any corruption, truncation,
+* or wrong-secret input decrypts to `null` rather than a partial session.
+* Web Crypto is universal (Node ≥20 + edge runtimes), so this runs anywhere a
+* Next route handler runs.
 */
-function buildSessionCookieOptions(secure) {
-	return {
-		httpOnly: true,
-		secure,
-		sameSite: "lax",
-		path: "/"
-	};
-}
-//#endregion
-//#region src/cookie-codec.ts
 const IV_BYTES = 12;
+/**
+* Browsers cap a single cookie at roughly 4096 bytes for the whole `Set-Cookie` pair —
+* name, value and attributes together — and enforce it by DISCARDING the cookie without
+* an error. For a session cookie that failure is invisible and badly misleading: the
+* platform authenticates, the handler answers 200, and the user is bounced back to
+* sign-in on the next request because the cookie was never stored.
+*
+* poly-x-sdk/ADR-0006 measured a live Odin session at 2628 bytes and recorded the missing
+* guard as an open follow-up; a per-tenant flag that inflates the JWT is enough to cross
+* the line. We fail loudly here instead.
+*/
+const SESSION_COOKIE_MAX_BYTES = 4096;
+/** Attributes `buildSessionCookieOptions` always sets: `Path=/; HttpOnly; Secure; SameSite=Lax`. */
+const COOKIE_ATTRIBUTE_BYTES = 45;
+/** Bytes the whole `Set-Cookie` pair will occupy for this value under this cookie name. */
+function sealedCookieByteLength(value, cookieName = "polyx_session") {
+	return new TextEncoder().encode(cookieName).length + 1 + value.length + COOKIE_ATTRIBUTE_BYTES;
+}
+/**
+* Thrown when a sealed session would exceed what a browser will store. Never includes the
+* session itself — the claims that caused the overflow are exactly the data we must not log.
+*/
+var SessionCookieTooLargeError = class extends _poly_x_core.PolyXError {
+	bytes;
+	limit;
+	constructor(bytes, limit, cookieName) {
+		super(`PolyX session cookie is ${bytes} bytes, over the ~${limit}-byte browser limit for "${cookieName}". The browser would discard it silently and the user would appear signed out. Reduce what the platform puts in the session — the usual cause is a tenant configured to embed full permissions in the JWT (includeFullPermissionInJwt).`, { code: "SESSION_COOKIE_TOO_LARGE" });
+		this.bytes = bytes;
+		this.limit = limit;
+	}
+};
 function base64UrlEncode(bytes) {
 	let binary = "";
 	for (const byte of bytes) binary += String.fromCharCode(byte);
@@ -35,7 +57,7 @@ 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) {
+async function sealSession(session, secret, options = {}) {
 	const key = await deriveKey(secret);
 	const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
 	const plaintext = new TextEncoder().encode(JSON.stringify(session));
@@ -46,7 +68,11 @@ async function sealSession(session, secret) {
 	const packed = new Uint8Array(iv.length + ciphertext.length);
 	packed.set(iv);
 	packed.set(ciphertext, iv.length);
-	return base64UrlEncode(packed);
+	const sealed = base64UrlEncode(packed);
+	const cookieName = options.cookieName ?? "polyx_session";
+	const bytes = sealedCookieByteLength(sealed, cookieName);
+	if (bytes > 4096) throw new SessionCookieTooLargeError(bytes, SESSION_COOKIE_MAX_BYTES, cookieName);
+	return sealed;
 }
 async function openSession(token, secret) {
 	try {
@@ -65,6 +91,23 @@ async function openSession(token, secret) {
 	}
 }
 //#endregion
+//#region src/cookie-adapter.ts
+/**
+* Attributes for the session cookie (ADR-0004 secure custody). `secure` is decided at
+* write time from the actual transport: a `Secure` cookie is silently dropped by the
+* browser over plain http, so http/localhost dev must set `secure:false` while https
+* always sets `secure:true`. This is not a downgrade — `Secure` carries no meaning on
+* http; setting it there just breaks the session. httpOnly/sameSite/path are unchanged.
+*/
+function buildSessionCookieOptions(secure) {
+	return {
+		httpOnly: true,
+		secure,
+		sameSite: "lax",
+		path: "/"
+	};
+}
+//#endregion
 //#region src/server-session.ts
 /**
 * The framework-agnostic BFF session controller (F007): tokens sealed in an
@@ -85,11 +128,12 @@ var ServerSession = class {
 		this.cookieName = options.cookieName ?? "polyx_session";
 		this.secure = options.secure ?? true;
 	}
-	async establishFromCode(code, codeVerifier, redirectUri) {
+	async establishFromCode(code, codeVerifier, redirectUri, forwardedHeaders) {
 		const stored = await this.authClient.exchangeCode({
 			code,
 			codeVerifier,
-			redirectUri
+			redirectUri,
+			forwardedHeaders
 		});
 		await this.write(stored);
 		return stored;
@@ -112,14 +156,37 @@ var ServerSession = class {
 				this.clear();
 				return null;
 			}
+			if (error instanceof SessionCookieTooLargeError) {
+				console.error(`[polyx] ${error.message}`);
+				this.clear();
+				return null;
+			}
 			throw error;
 		}
 	}
+	/**
+	* End the session upstream, then locally. `device` revokes this session; `everywhere`
+	* revokes every session for the user (FR-SSO-5).
+	*
+	* Order is load-bearing: revocation is authenticated with the access token sealed in the
+	* cookie, so the cookie must be read before it is dropped. The upstream call is
+	* best-effort — an unreachable platform must not strand the user half-signed-in — but the
+	* call itself is real: the ecosystem logout the SDK used before resolves its session from
+	* a browser cookie, which a server-to-server fetch never carries, so it silently revoked
+	* nothing and answered 200.
+	*/
+	async revoke(scope = "device") {
+		const current = await this.read();
+		if (current) try {
+			await this.authClient.revokeSession(current.tokens.accessToken, scope);
+		} catch {}
+		this.clear();
+	}
 	clear() {
 		this.cookies.delete(this.cookieName);
 	}
 	async write(session) {
-		const sealed = await sealSession(session, this.secret);
+		const sealed = await sealSession(session, this.secret, { cookieName: this.cookieName });
 		this.cookies.set(this.cookieName, sealed, buildSessionCookieOptions(this.secure));
 	}
 };
@@ -143,12 +210,24 @@ Object.defineProperty(exports, "DEFAULT_SESSION_COOKIE", {
 		return DEFAULT_SESSION_COOKIE;
 	}
 });
+Object.defineProperty(exports, "SESSION_COOKIE_MAX_BYTES", {
+	enumerable: true,
+	get: function() {
+		return SESSION_COOKIE_MAX_BYTES;
+	}
+});
 Object.defineProperty(exports, "ServerSession", {
 	enumerable: true,
 	get: function() {
 		return ServerSession;
 	}
 });
+Object.defineProperty(exports, "SessionCookieTooLargeError", {
+	enumerable: true,
+	get: function() {
+		return SessionCookieTooLargeError;
+	}
+});
 Object.defineProperty(exports, "openSession", {
 	enumerable: true,
 	get: function() {
@@ -161,6 +240,12 @@ Object.defineProperty(exports, "sealSession", {
 		return sealSession;
 	}
 });
+Object.defineProperty(exports, "sealedCookieByteLength", {
+	enumerable: true,
+	get: function() {
+		return sealedCookieByteLength;
+	}
+});
 Object.defineProperty(exports, "toAuthContext", {
 	enumerable: true,
 	get: function() {

package/dist/{server-session-CXVB1Rgx.mjs → server-session-pY-nzh5x.mjs}

@@ -1,23 +1,45 @@
-import { SessionExpiredError, SessionRevokedError } from "@poly-x/core";
-//#region src/cookie-adapter.ts
+import { PolyXError, SessionExpiredError, SessionRevokedError } from "@poly-x/core";
+//#region src/cookie-codec.ts
 /**
-* Attributes for the session cookie (ADR-0004 secure custody). `secure` is decided at
-* write time from the actual transport: a `Secure` cookie is silently dropped by the
-* browser over plain http, so http/localhost dev must set `secure:false` while https
-* always sets `secure:true`. This is not a downgrade — `Secure` carries no meaning on
-* http; setting it there just breaks the session. httpOnly/sameSite/path are unchanged.
+* AES-GCM sealing of the session cookie (F007 / ADR-0004). The key is derived
+* (SHA-256) from the consumer's `POLYX_SESSION_SECRET`; AES-GCM gives
+* confidentiality + tamper-detection together, so any corruption, truncation,
+* or wrong-secret input decrypts to `null` rather than a partial session.
+* Web Crypto is universal (Node ≥20 + edge runtimes), so this runs anywhere a
+* Next route handler runs.
 */
-function buildSessionCookieOptions(secure) {
-	return {
-		httpOnly: true,
-		secure,
-		sameSite: "lax",
-		path: "/"
-	};
-}
-//#endregion
-//#region src/cookie-codec.ts
 const IV_BYTES = 12;
+/**
+* Browsers cap a single cookie at roughly 4096 bytes for the whole `Set-Cookie` pair —
+* name, value and attributes together — and enforce it by DISCARDING the cookie without
+* an error. For a session cookie that failure is invisible and badly misleading: the
+* platform authenticates, the handler answers 200, and the user is bounced back to
+* sign-in on the next request because the cookie was never stored.
+*
+* poly-x-sdk/ADR-0006 measured a live Odin session at 2628 bytes and recorded the missing
+* guard as an open follow-up; a per-tenant flag that inflates the JWT is enough to cross
+* the line. We fail loudly here instead.
+*/
+const SESSION_COOKIE_MAX_BYTES = 4096;
+/** Attributes `buildSessionCookieOptions` always sets: `Path=/; HttpOnly; Secure; SameSite=Lax`. */
+const COOKIE_ATTRIBUTE_BYTES = 45;
+/** Bytes the whole `Set-Cookie` pair will occupy for this value under this cookie name. */
+function sealedCookieByteLength(value, cookieName = "polyx_session") {
+	return new TextEncoder().encode(cookieName).length + 1 + value.length + COOKIE_ATTRIBUTE_BYTES;
+}
+/**
+* Thrown when a sealed session would exceed what a browser will store. Never includes the
+* session itself — the claims that caused the overflow are exactly the data we must not log.
+*/
+var SessionCookieTooLargeError = class extends PolyXError {
+	bytes;
+	limit;
+	constructor(bytes, limit, cookieName) {
+		super(`PolyX session cookie is ${bytes} bytes, over the ~${limit}-byte browser limit for "${cookieName}". The browser would discard it silently and the user would appear signed out. Reduce what the platform puts in the session — the usual cause is a tenant configured to embed full permissions in the JWT (includeFullPermissionInJwt).`, { code: "SESSION_COOKIE_TOO_LARGE" });
+		this.bytes = bytes;
+		this.limit = limit;
+	}
+};
 function base64UrlEncode(bytes) {
 	let binary = "";
 	for (const byte of bytes) binary += String.fromCharCode(byte);
@@ -35,7 +57,7 @@ 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) {
+async function sealSession(session, secret, options = {}) {
 	const key = await deriveKey(secret);
 	const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
 	const plaintext = new TextEncoder().encode(JSON.stringify(session));
@@ -46,7 +68,11 @@ async function sealSession(session, secret) {
 	const packed = new Uint8Array(iv.length + ciphertext.length);
 	packed.set(iv);
 	packed.set(ciphertext, iv.length);
-	return base64UrlEncode(packed);
+	const sealed = base64UrlEncode(packed);
+	const cookieName = options.cookieName ?? "polyx_session";
+	const bytes = sealedCookieByteLength(sealed, cookieName);
+	if (bytes > 4096) throw new SessionCookieTooLargeError(bytes, SESSION_COOKIE_MAX_BYTES, cookieName);
+	return sealed;
 }
 async function openSession(token, secret) {
 	try {
@@ -65,6 +91,23 @@ async function openSession(token, secret) {
 	}
 }
 //#endregion
+//#region src/cookie-adapter.ts
+/**
+* Attributes for the session cookie (ADR-0004 secure custody). `secure` is decided at
+* write time from the actual transport: a `Secure` cookie is silently dropped by the
+* browser over plain http, so http/localhost dev must set `secure:false` while https
+* always sets `secure:true`. This is not a downgrade — `Secure` carries no meaning on
+* http; setting it there just breaks the session. httpOnly/sameSite/path are unchanged.
+*/
+function buildSessionCookieOptions(secure) {
+	return {
+		httpOnly: true,
+		secure,
+		sameSite: "lax",
+		path: "/"
+	};
+}
+//#endregion
 //#region src/server-session.ts
 /**
 * The framework-agnostic BFF session controller (F007): tokens sealed in an
@@ -85,11 +128,12 @@ var ServerSession = class {
 		this.cookieName = options.cookieName ?? "polyx_session";
 		this.secure = options.secure ?? true;
 	}
-	async establishFromCode(code, codeVerifier, redirectUri) {
+	async establishFromCode(code, codeVerifier, redirectUri, forwardedHeaders) {
 		const stored = await this.authClient.exchangeCode({
 			code,
 			codeVerifier,
-			redirectUri
+			redirectUri,
+			forwardedHeaders
 		});
 		await this.write(stored);
 		return stored;
@@ -112,14 +156,37 @@ var ServerSession = class {
 				this.clear();
 				return null;
 			}
+			if (error instanceof SessionCookieTooLargeError) {
+				console.error(`[polyx] ${error.message}`);
+				this.clear();
+				return null;
+			}
 			throw error;
 		}
 	}
+	/**
+	* End the session upstream, then locally. `device` revokes this session; `everywhere`
+	* revokes every session for the user (FR-SSO-5).
+	*
+	* Order is load-bearing: revocation is authenticated with the access token sealed in the
+	* cookie, so the cookie must be read before it is dropped. The upstream call is
+	* best-effort — an unreachable platform must not strand the user half-signed-in — but the
+	* call itself is real: the ecosystem logout the SDK used before resolves its session from
+	* a browser cookie, which a server-to-server fetch never carries, so it silently revoked
+	* nothing and answered 200.
+	*/
+	async revoke(scope = "device") {
+		const current = await this.read();
+		if (current) try {
+			await this.authClient.revokeSession(current.tokens.accessToken, scope);
+		} catch {}
+		this.clear();
+	}
 	clear() {
 		this.cookies.delete(this.cookieName);
 	}
 	async write(session) {
-		const sealed = await sealSession(session, this.secret);
+		const sealed = await sealSession(session, this.secret, { cookieName: this.cookieName });
 		this.cookies.set(this.cookieName, sealed, buildSessionCookieOptions(this.secure));
 	}
 };
@@ -137,4 +204,4 @@ function toAuthContext(session) {
 	};
 }
 //#endregion
-export { sealSession as a, openSession as i, ServerSession as n, toAuthContext as r, DEFAULT_SESSION_COOKIE as t };
+export { SessionCookieTooLargeError as a, sealedCookieByteLength as c, SESSION_COOKIE_MAX_BYTES as i, ServerSession as n, openSession as o, toAuthContext as r, sealSession as s, DEFAULT_SESSION_COOKIE as t };

package/dist/server.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_server_session = require("./server-session-DmR0ZJqP.cjs");
+const require_server_session = require("./server-session-Df9HXl_5.cjs");
 let _poly_x_core = require("@poly-x/core");
 let next_headers = require("next/headers");
 //#region src/config.ts
@@ -72,6 +72,79 @@ function resolveCookieSecure(request, config) {
 		return true;
 	}
 }
+/** Browser request headers the platform reads for session device attribution. */
+const FORWARDED_DEVICE_HEADERS = [
+	"user-agent",
+	"accept-language",
+	"sec-ch-ua",
+	"sec-ch-ua-platform",
+	"sec-ch-ua-mobile",
+	"sec-ch-ua-model"
+];
+/**
+* The end user's IP as observed by THIS BFF's own infrastructure — the left-most
+* entry of the inbound `x-forwarded-for` (what the platform/proxy in front of the
+* app set), falling back to `x-real-ip`. Returns undefined on localhost/dev where
+* neither is present, letting the platform fall back to its own resolution rather
+* than recording a blank. (This trusts the infra-set forwarded chain, not a value
+* the browser could set on the same-origin BFF request.)
+*/
+function resolveClientIp(request) {
+	const first = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+	if (first) return first;
+	return request.headers.get("x-real-ip")?.trim() || void 0;
+}
+/**
+* Curate the browser context to forward on the session-creating token exchange.
+* In a BFF deployment the outbound call to poly-auth is made by Node, so without
+* this the platform attributes the session to the server ("node"/Unknown UA, the
+* server's IP). We forward a fixed allowlist of the browser's own request headers
+* plus the observed client IP (as `x-forwarded-for`). Only headers actually
+* present are forwarded — never blank values that would clobber the platform's
+* own fallback resolution.
+*/
+function collectForwardedDeviceHeaders(request) {
+	const forwarded = {};
+	for (const name of FORWARDED_DEVICE_HEADERS) {
+		const value = request.headers.get(name);
+		if (value) forwarded[name] = value;
+	}
+	const clientIp = resolveClientIp(request);
+	if (clientIp) forwarded["x-forwarded-for"] = clientIp;
+	return forwarded;
+}
+/**
+* Build the forwarded precise-location headers (`x-polyx-geo-*`) from the browser's login
+* body (v6, FR-LOC-7). The browser captures a consented position client-side and posts it;
+* the platform reads these on the token exchange. Only well-formed values are forwarded, and
+* the consent state rides even when coordinates are absent (denied/timeout → coarse fallback).
+*/
+function geoHeadersFromBody(geo) {
+	const headers = {};
+	if (!geo || typeof geo !== "object") return headers;
+	const g = geo;
+	const lat = Number(g.latitude);
+	const lon = Number(g.longitude);
+	if (typeof g.latitude === "string" && Number.isFinite(lat) && lat >= -90 && lat <= 90) headers["x-polyx-geo-lat"] = g.latitude;
+	if (typeof g.longitude === "string" && Number.isFinite(lon) && lon >= -180 && lon <= 180) headers["x-polyx-geo-lon"] = g.longitude;
+	if (typeof g.accuracyMeters === "number" && Number.isFinite(g.accuracyMeters) && g.accuracyMeters >= 0) headers["x-polyx-geo-accuracy"] = String(g.accuracyMeters);
+	if (g.consent === "granted" || g.consent === "denied" || g.consent === "revoked") headers["x-polyx-geo-consent"] = g.consent;
+	return headers;
+}
+/**
+* Build the device-context headers (`x-timezone` / `x-screen-resolution`) from the browser's login
+* body (v6). These are not automatic request headers — the browser captures them client-side and
+* posts them; the platform reads them for session device attribution. Only well-formed values are
+* forwarded (a sane timezone string, a `WxH` resolution) so junk never reaches the platform.
+*/
+function deviceContextHeadersFromBody(deviceContext) {
+	const headers = {};
+	if (!deviceContext || typeof deviceContext !== "object") return headers;
+	const d = deviceContext;
+	if (typeof d.timezone === "string" && d.timezone.length > 0 && d.timezone.length <= 64) headers["x-timezone"] = d.timezone;
+	if (typeof d.screenResolution === "string" && /^\d{1,5}x\d{1,5}$/.test(d.screenResolution)) headers["x-screen-resolution"] = d.screenResolution;
+	return headers;
+}
 /** Read the current session — safe in Server Components (no cookie write). */
 async function auth(overrides) {
 	const config = resolveNextConfig(overrides);
@@ -128,6 +201,8 @@ function createAuthHandlers(handlersConfig = {}) {
 			} catch {
 				return Response.json({ status: "invalid_request" }, { status: 400 });
 			}
+			const geoHeaders = geoHeadersFromBody(payload.geo);
+			const deviceContextHeaders = deviceContextHeadersFromBody(payload.deviceContext);
 			const email = typeof payload.email === "string" ? payload.email : "";
 			const password = typeof payload.password === "string" ? payload.password : "";
 			if (!email || !password) return Response.json({ status: "invalid_request" }, { status: 400 });
@@ -148,12 +223,30 @@ function createAuthHandlers(handlersConfig = {}) {
 					tenantId
 				});
 				switch (outcome.type) {
-					case "authorized":
-						await newSession(adapt(await (0, next_headers.cookies)()), config, secure).establishFromCode(outcome.code, verifier, redirectUri);
+					case "authorized": {
+						const store = await (0, next_headers.cookies)();
+						try {
+							await newSession(adapt(store), config, secure).establishFromCode(outcome.code, verifier, redirectUri, {
+								...collectForwardedDeviceHeaders(request),
+								...geoHeaders,
+								...deviceContextHeaders
+							});
+						} catch (error) {
+							if (error instanceof require_server_session.SessionCookieTooLargeError) {
+								console.error(`[polyx] ${error.message}`);
+								return Response.json({
+									status: "session_too_large",
+									bytes: error.bytes,
+									limit: error.limit
+								}, { status: 500 });
+							}
+							throw error;
+						}
 						return Response.json({
 							status: "success",
 							redirectTo: afterSignInPath
 						});
+					}
 					case "select_tenant": return Response.json({
 						status: "select_tenant",
 						tenants: outcome.tenants,
@@ -249,7 +342,15 @@ function createAuthHandlers(handlersConfig = {}) {
 			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, secure).establishFromCode(code, tx.verifier, tx.redirectUri);
+			try {
+				await newSession(adapt(store), config, secure).establishFromCode(code, tx.verifier, tx.redirectUri, collectForwardedDeviceHeaders(request));
+			} catch (error) {
+				if (error instanceof require_server_session.SessionCookieTooLargeError) {
+					console.error(`[polyx] ${error.message}`);
+					return Response.redirect(home, 302);
+				}
+				throw error;
+			}
 			return Response.redirect(home, 302);
 		},
 		async refresh(request) {
@@ -258,22 +359,50 @@ function createAuthHandlers(handlersConfig = {}) {
 			const session = await newSession(await requestCookies(), config, secure).refresh();
 			return Response.json({ isSignedIn: session !== null }, { status: session ? 200 : 401 });
 		},
+		/**
+		* End the session: revoke it upstream (bearer-authenticated, using the sealed token)
+		* and unseal the cookie. `?scope=everywhere` signs the user out of every device.
+		*
+		* Content-negotiated so both callers work: a plain link/form navigation gets the 302 it
+		* expects, while `Accept: application/json` (what `<UserButton/>` sends) gets JSON and
+		* decides its own destination client-side. Deliberately no server-side redirect target
+		* — a caller-supplied one would be an open redirect on the auth path, and the client
+		* already knows where it wants to land.
+		*/
 		async signout(request) {
 			const config = resolveNextConfig(handlersConfig);
 			const secure = resolveCookieSecure(request, config);
-			newSession(adapt(await (0, next_headers.cookies)()), config, secure).clear();
-			try {
-				await buildServerAuthClient(config).logout("device");
-			} catch {}
+			const scope = new URL(request.url).searchParams.get("scope") === "everywhere" ? "everywhere" : "device";
+			await newSession(adapt(await (0, next_headers.cookies)()), config, secure).revoke(scope);
+			if (request.headers.get("accept")?.includes("application/json")) return Response.json({ signedOut: true });
 			return Response.redirect(new URL(request.url).origin + "/", 302);
+		},
+		async session() {
+			return Response.json(await auth(handlersConfig));
+		},
+		async subscriptionCredential() {
+			const config = resolveNextConfig(handlersConfig);
+			const current = await new require_server_session.ServerSession({
+				authClient: buildServerAuthClient(config),
+				secret: config.secret,
+				cookies: await requestCookies()
+			}).read();
+			if (!current) return Response.json({ status: "signed_out" }, { status: 401 });
+			return Response.json({
+				token: current.tokens.accessToken,
+				organizationId: current.session.claims.organizationId
+			});
 		}
 	};
 }
 //#endregion
 exports.DEFAULT_SESSION_COOKIE = require_server_session.DEFAULT_SESSION_COOKIE;
+exports.SESSION_COOKIE_MAX_BYTES = require_server_session.SESSION_COOKIE_MAX_BYTES;
 exports.ServerSession = require_server_session.ServerSession;
+exports.SessionCookieTooLargeError = require_server_session.SessionCookieTooLargeError;
 exports.auth = auth;
 exports.createAuthHandlers = createAuthHandlers;
 exports.openSession = require_server_session.openSession;
 exports.resolveNextConfig = resolveNextConfig;
 exports.sealSession = require_server_session.sealSession;
+exports.sealedCookieByteLength = require_server_session.sealedCookieByteLength;

package/dist/server.d.cts

@@ -1,4 +1,4 @@
-import { AuthClient, StoredSession } from "@poly-x/core";
+import { AuthClient, PolyXError, StoredSession } from "@poly-x/core";
 
 //#region src/config.d.ts
 interface NextServerConfig {
@@ -58,10 +58,22 @@ declare class ServerSession {
   private readonly cookieName;
   private readonly secure;
   constructor(options: ServerSessionOptions);
-  establishFromCode(code: string, codeVerifier: string, redirectUri: string): Promise<StoredSession>;
+  establishFromCode(code: string, codeVerifier: string, redirectUri: string, forwardedHeaders?: Record<string, string>): Promise<StoredSession>;
   read(): Promise<StoredSession | null>;
   /** Rotate the tokens; clears the cookie (returns null) on a terminal refresh failure. */
   refresh(): Promise<StoredSession | null>;
+  /**
+   * End the session upstream, then locally. `device` revokes this session; `everywhere`
+   * revokes every session for the user (FR-SSO-5).
+   *
+   * Order is load-bearing: revocation is authenticated with the access token sealed in the
+   * cookie, so the cookie must be read before it is dropped. The upstream call is
+   * best-effort — an unreachable platform must not strand the user half-signed-in — but the
+   * call itself is real: the ecosystem logout the SDK used before resolves its session from
+   * a browser cookie, which a server-to-server fetch never carries, so it silently revoked
+   * nothing and answered 200.
+   */
+  revoke(scope?: "device" | "everywhere"): Promise<void>;
   clear(): void;
   private write;
 }
@@ -73,7 +85,34 @@ interface AuthContext {
 }
 //#endregion
 //#region src/cookie-codec.d.ts
-declare function sealSession(session: StoredSession, secret: string): Promise<string>;
+/**
+ * Browsers cap a single cookie at roughly 4096 bytes for the whole `Set-Cookie` pair —
+ * name, value and attributes together — and enforce it by DISCARDING the cookie without
+ * an error. For a session cookie that failure is invisible and badly misleading: the
+ * platform authenticates, the handler answers 200, and the user is bounced back to
+ * sign-in on the next request because the cookie was never stored.
+ *
+ * poly-x-sdk/ADR-0006 measured a live Odin session at 2628 bytes and recorded the missing
+ * guard as an open follow-up; a per-tenant flag that inflates the JWT is enough to cross
+ * the line. We fail loudly here instead.
+ */
+declare const SESSION_COOKIE_MAX_BYTES = 4096;
+/** Bytes the whole `Set-Cookie` pair will occupy for this value under this cookie name. */
+declare function sealedCookieByteLength(value: string, cookieName?: string): number;
+/**
+ * Thrown when a sealed session would exceed what a browser will store. Never includes the
+ * session itself — the claims that caused the overflow are exactly the data we must not log.
+ */
+declare class SessionCookieTooLargeError extends PolyXError {
+  readonly bytes: number;
+  readonly limit: number;
+  constructor(bytes: number, limit: number, cookieName: string);
+}
+interface SealSessionOptions {
+  /** The cookie name the value will be stored under; counted against the browser budget. */
+  cookieName?: string;
+}
+declare function sealSession(session: StoredSession, secret: string, options?: SealSessionOptions): Promise<string>;
 declare function openSession(token: string, secret: string): Promise<StoredSession | null>;
 //#endregion
 //#region src/server.d.ts
@@ -108,6 +147,21 @@ interface AuthHandlers {
   callback(request: Request): Promise<Response>;
   refresh(request: Request): Promise<Response>;
   signout(request: Request): Promise<Response>;
+  /**
+   * The client's view of the session: the same `AuthContext` `auth()` returns in a Server
+   * Component, as JSON. This is what makes client components work under BFF custody, where
+   * the browser holds no token and so cannot derive a session for itself — the hooks read
+   * server truth instead. Never carries a token.
+   */
+  session(request: Request): Promise<Response>;
+  /**
+   * v2 (ADR-0008): a session-derived credential for the real-time `authz:changed` channel. Returns
+   * `{ token, organizationId }` read from the sealed session server-side — the token is for the
+   * socket handshake only (in-memory; never persisted), per the pragmatic custody decision. A
+   * signed-out caller gets `401` with no token. This is the one place a token leaves the BFF, and
+   * only to open the live-authz subscription.
+   */
+  subscriptionCredential(request: Request): Promise<Response>;
 }
 /** The JSON the `forgotPassword` handler returns — always uniform (no enumeration). */
 type ForgotPasswordResult = {
@@ -148,9 +202,13 @@ type AuthenticateResult = {
   status: "no_access";
 } | {
   status: "invalid_credentials";
+} /** Credentials were correct, but the sealed session exceeds what a browser will store. */ | {
+  status: "session_too_large";
+  bytes: number;
+  limit: number;
 } | {
   status: "invalid_request";
 };
 declare function createAuthHandlers(handlersConfig?: AuthHandlersConfig): AuthHandlers;
 //#endregion
-export { type AuthContext, AuthHandlers, AuthHandlersConfig, AuthenticateResult, type CookieAdapter, type CookieSetOptions, DEFAULT_SESSION_COOKIE, ForgotPasswordResult, type NextServerConfig, ResetPasswordResult, ServerSession, auth, createAuthHandlers, openSession, resolveNextConfig, sealSession };
+export { type AuthContext, AuthHandlers, AuthHandlersConfig, AuthenticateResult, type CookieAdapter, type CookieSetOptions, DEFAULT_SESSION_COOKIE, ForgotPasswordResult, type NextServerConfig, ResetPasswordResult, SESSION_COOKIE_MAX_BYTES, ServerSession, SessionCookieTooLargeError, auth, createAuthHandlers, openSession, resolveNextConfig, sealSession, sealedCookieByteLength };

package/dist/server.d.mts

@@ -1,4 +1,4 @@
-import { AuthClient, StoredSession } from "@poly-x/core";
+import { AuthClient, PolyXError, StoredSession } from "@poly-x/core";
 
 //#region src/config.d.ts
 interface NextServerConfig {
@@ -58,10 +58,22 @@ declare class ServerSession {
   private readonly cookieName;
   private readonly secure;
   constructor(options: ServerSessionOptions);
-  establishFromCode(code: string, codeVerifier: string, redirectUri: string): Promise<StoredSession>;
+  establishFromCode(code: string, codeVerifier: string, redirectUri: string, forwardedHeaders?: Record<string, string>): Promise<StoredSession>;
   read(): Promise<StoredSession | null>;
   /** Rotate the tokens; clears the cookie (returns null) on a terminal refresh failure. */
   refresh(): Promise<StoredSession | null>;
+  /**
+   * End the session upstream, then locally. `device` revokes this session; `everywhere`
+   * revokes every session for the user (FR-SSO-5).
+   *
+   * Order is load-bearing: revocation is authenticated with the access token sealed in the
+   * cookie, so the cookie must be read before it is dropped. The upstream call is
+   * best-effort — an unreachable platform must not strand the user half-signed-in — but the
+   * call itself is real: the ecosystem logout the SDK used before resolves its session from
+   * a browser cookie, which a server-to-server fetch never carries, so it silently revoked
+   * nothing and answered 200.
+   */
+  revoke(scope?: "device" | "everywhere"): Promise<void>;
   clear(): void;
   private write;
 }
@@ -73,7 +85,34 @@ interface AuthContext {
 }
 //#endregion
 //#region src/cookie-codec.d.ts
-declare function sealSession(session: StoredSession, secret: string): Promise<string>;
+/**
+ * Browsers cap a single cookie at roughly 4096 bytes for the whole `Set-Cookie` pair —
+ * name, value and attributes together — and enforce it by DISCARDING the cookie without
+ * an error. For a session cookie that failure is invisible and badly misleading: the
+ * platform authenticates, the handler answers 200, and the user is bounced back to
+ * sign-in on the next request because the cookie was never stored.
+ *
+ * poly-x-sdk/ADR-0006 measured a live Odin session at 2628 bytes and recorded the missing
+ * guard as an open follow-up; a per-tenant flag that inflates the JWT is enough to cross
+ * the line. We fail loudly here instead.
+ */
+declare const SESSION_COOKIE_MAX_BYTES = 4096;
+/** Bytes the whole `Set-Cookie` pair will occupy for this value under this cookie name. */
+declare function sealedCookieByteLength(value: string, cookieName?: string): number;
+/**
+ * Thrown when a sealed session would exceed what a browser will store. Never includes the
+ * session itself — the claims that caused the overflow are exactly the data we must not log.
+ */
+declare class SessionCookieTooLargeError extends PolyXError {
+  readonly bytes: number;
+  readonly limit: number;
+  constructor(bytes: number, limit: number, cookieName: string);
+}
+interface SealSessionOptions {
+  /** The cookie name the value will be stored under; counted against the browser budget. */
+  cookieName?: string;
+}
+declare function sealSession(session: StoredSession, secret: string, options?: SealSessionOptions): Promise<string>;
 declare function openSession(token: string, secret: string): Promise<StoredSession | null>;
 //#endregion
 //#region src/server.d.ts
@@ -108,6 +147,21 @@ interface AuthHandlers {
   callback(request: Request): Promise<Response>;
   refresh(request: Request): Promise<Response>;
   signout(request: Request): Promise<Response>;
+  /**
+   * The client's view of the session: the same `AuthContext` `auth()` returns in a Server
+   * Component, as JSON. This is what makes client components work under BFF custody, where
+   * the browser holds no token and so cannot derive a session for itself — the hooks read
+   * server truth instead. Never carries a token.
+   */
+  session(request: Request): Promise<Response>;
+  /**
+   * v2 (ADR-0008): a session-derived credential for the real-time `authz:changed` channel. Returns
+   * `{ token, organizationId }` read from the sealed session server-side — the token is for the
+   * socket handshake only (in-memory; never persisted), per the pragmatic custody decision. A
+   * signed-out caller gets `401` with no token. This is the one place a token leaves the BFF, and
+   * only to open the live-authz subscription.
+   */
+  subscriptionCredential(request: Request): Promise<Response>;
 }
 /** The JSON the `forgotPassword` handler returns — always uniform (no enumeration). */
 type ForgotPasswordResult = {
@@ -148,9 +202,13 @@ type AuthenticateResult = {
   status: "no_access";
 } | {
   status: "invalid_credentials";
+} /** Credentials were correct, but the sealed session exceeds what a browser will store. */ | {
+  status: "session_too_large";
+  bytes: number;
+  limit: number;
 } | {
   status: "invalid_request";
 };
 declare function createAuthHandlers(handlersConfig?: AuthHandlersConfig): AuthHandlers;
 //#endregion
-export { type AuthContext, AuthHandlers, AuthHandlersConfig, AuthenticateResult, type CookieAdapter, type CookieSetOptions, DEFAULT_SESSION_COOKIE, ForgotPasswordResult, type NextServerConfig, ResetPasswordResult, ServerSession, auth, createAuthHandlers, openSession, resolveNextConfig, sealSession };
+export { type AuthContext, AuthHandlers, AuthHandlersConfig, AuthenticateResult, type CookieAdapter, type CookieSetOptions, DEFAULT_SESSION_COOKIE, ForgotPasswordResult, type NextServerConfig, ResetPasswordResult, SESSION_COOKIE_MAX_BYTES, ServerSession, SessionCookieTooLargeError, auth, createAuthHandlers, openSession, resolveNextConfig, sealSession, sealedCookieByteLength };

package/dist/server.mjs

@@ -1,4 +1,4 @@
-import { a as sealSession, i as openSession, n as ServerSession, r as toAuthContext, t as DEFAULT_SESSION_COOKIE } from "./server-session-CXVB1Rgx.mjs";
+import { a as SessionCookieTooLargeError, c as sealedCookieByteLength, i as SESSION_COOKIE_MAX_BYTES, n as ServerSession, o as openSession, r as toAuthContext, s as sealSession, t as DEFAULT_SESSION_COOKIE } from "./server-session-pY-nzh5x.mjs";
 import { AuthClient, FetchTransport, generatePkce, randomState, resolveConfig } from "@poly-x/core";
 import { cookies } from "next/headers";
 //#region src/config.ts
@@ -71,6 +71,79 @@ function resolveCookieSecure(request, config) {
 		return true;
 	}
 }
+/** Browser request headers the platform reads for session device attribution. */
+const FORWARDED_DEVICE_HEADERS = [
+	"user-agent",
+	"accept-language",
+	"sec-ch-ua",
+	"sec-ch-ua-platform",
+	"sec-ch-ua-mobile",
+	"sec-ch-ua-model"
+];
+/**
+* The end user's IP as observed by THIS BFF's own infrastructure — the left-most
+* entry of the inbound `x-forwarded-for` (what the platform/proxy in front of the
+* app set), falling back to `x-real-ip`. Returns undefined on localhost/dev where
+* neither is present, letting the platform fall back to its own resolution rather
+* than recording a blank. (This trusts the infra-set forwarded chain, not a value
+* the browser could set on the same-origin BFF request.)
+*/
+function resolveClientIp(request) {
+	const first = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+	if (first) return first;
+	return request.headers.get("x-real-ip")?.trim() || void 0;
+}
+/**
+* Curate the browser context to forward on the session-creating token exchange.
+* In a BFF deployment the outbound call to poly-auth is made by Node, so without
+* this the platform attributes the session to the server ("node"/Unknown UA, the
+* server's IP). We forward a fixed allowlist of the browser's own request headers
+* plus the observed client IP (as `x-forwarded-for`). Only headers actually
+* present are forwarded — never blank values that would clobber the platform's
+* own fallback resolution.
+*/
+function collectForwardedDeviceHeaders(request) {
+	const forwarded = {};
+	for (const name of FORWARDED_DEVICE_HEADERS) {
+		const value = request.headers.get(name);
+		if (value) forwarded[name] = value;
+	}
+	const clientIp = resolveClientIp(request);
+	if (clientIp) forwarded["x-forwarded-for"] = clientIp;
+	return forwarded;
+}
+/**
+* Build the forwarded precise-location headers (`x-polyx-geo-*`) from the browser's login
+* body (v6, FR-LOC-7). The browser captures a consented position client-side and posts it;
+* the platform reads these on the token exchange. Only well-formed values are forwarded, and
+* the consent state rides even when coordinates are absent (denied/timeout → coarse fallback).
+*/
+function geoHeadersFromBody(geo) {
+	const headers = {};
+	if (!geo || typeof geo !== "object") return headers;
+	const g = geo;
+	const lat = Number(g.latitude);
+	const lon = Number(g.longitude);
+	if (typeof g.latitude === "string" && Number.isFinite(lat) && lat >= -90 && lat <= 90) headers["x-polyx-geo-lat"] = g.latitude;
+	if (typeof g.longitude === "string" && Number.isFinite(lon) && lon >= -180 && lon <= 180) headers["x-polyx-geo-lon"] = g.longitude;
+	if (typeof g.accuracyMeters === "number" && Number.isFinite(g.accuracyMeters) && g.accuracyMeters >= 0) headers["x-polyx-geo-accuracy"] = String(g.accuracyMeters);
+	if (g.consent === "granted" || g.consent === "denied" || g.consent === "revoked") headers["x-polyx-geo-consent"] = g.consent;
+	return headers;
+}
+/**
+* Build the device-context headers (`x-timezone` / `x-screen-resolution`) from the browser's login
+* body (v6). These are not automatic request headers — the browser captures them client-side and
+* posts them; the platform reads them for session device attribution. Only well-formed values are
+* forwarded (a sane timezone string, a `WxH` resolution) so junk never reaches the platform.
+*/
+function deviceContextHeadersFromBody(deviceContext) {
+	const headers = {};
+	if (!deviceContext || typeof deviceContext !== "object") return headers;
+	const d = deviceContext;
+	if (typeof d.timezone === "string" && d.timezone.length > 0 && d.timezone.length <= 64) headers["x-timezone"] = d.timezone;
+	if (typeof d.screenResolution === "string" && /^\d{1,5}x\d{1,5}$/.test(d.screenResolution)) headers["x-screen-resolution"] = d.screenResolution;
+	return headers;
+}
 /** Read the current session — safe in Server Components (no cookie write). */
 async function auth(overrides) {
 	const config = resolveNextConfig(overrides);
@@ -127,6 +200,8 @@ function createAuthHandlers(handlersConfig = {}) {
 			} catch {
 				return Response.json({ status: "invalid_request" }, { status: 400 });
 			}
+			const geoHeaders = geoHeadersFromBody(payload.geo);
+			const deviceContextHeaders = deviceContextHeadersFromBody(payload.deviceContext);
 			const email = typeof payload.email === "string" ? payload.email : "";
 			const password = typeof payload.password === "string" ? payload.password : "";
 			if (!email || !password) return Response.json({ status: "invalid_request" }, { status: 400 });
@@ -147,12 +222,30 @@ function createAuthHandlers(handlersConfig = {}) {
 					tenantId
 				});
 				switch (outcome.type) {
-					case "authorized":
-						await newSession(adapt(await cookies()), config, secure).establishFromCode(outcome.code, verifier, redirectUri);
+					case "authorized": {
+						const store = await cookies();
+						try {
+							await newSession(adapt(store), config, secure).establishFromCode(outcome.code, verifier, redirectUri, {
+								...collectForwardedDeviceHeaders(request),
+								...geoHeaders,
+								...deviceContextHeaders
+							});
+						} catch (error) {
+							if (error instanceof SessionCookieTooLargeError) {
+								console.error(`[polyx] ${error.message}`);
+								return Response.json({
+									status: "session_too_large",
+									bytes: error.bytes,
+									limit: error.limit
+								}, { status: 500 });
+							}
+							throw error;
+						}
 						return Response.json({
 							status: "success",
 							redirectTo: afterSignInPath
 						});
+					}
 					case "select_tenant": return Response.json({
 						status: "select_tenant",
 						tenants: outcome.tenants,
@@ -248,7 +341,15 @@ function createAuthHandlers(handlersConfig = {}) {
 			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, secure).establishFromCode(code, tx.verifier, tx.redirectUri);
+			try {
+				await newSession(adapt(store), config, secure).establishFromCode(code, tx.verifier, tx.redirectUri, collectForwardedDeviceHeaders(request));
+			} catch (error) {
+				if (error instanceof SessionCookieTooLargeError) {
+					console.error(`[polyx] ${error.message}`);
+					return Response.redirect(home, 302);
+				}
+				throw error;
+			}
 			return Response.redirect(home, 302);
 		},
 		async refresh(request) {
@@ -257,16 +358,41 @@ function createAuthHandlers(handlersConfig = {}) {
 			const session = await newSession(await requestCookies(), config, secure).refresh();
 			return Response.json({ isSignedIn: session !== null }, { status: session ? 200 : 401 });
 		},
+		/**
+		* End the session: revoke it upstream (bearer-authenticated, using the sealed token)
+		* and unseal the cookie. `?scope=everywhere` signs the user out of every device.
+		*
+		* Content-negotiated so both callers work: a plain link/form navigation gets the 302 it
+		* expects, while `Accept: application/json` (what `<UserButton/>` sends) gets JSON and
+		* decides its own destination client-side. Deliberately no server-side redirect target
+		* — a caller-supplied one would be an open redirect on the auth path, and the client
+		* already knows where it wants to land.
+		*/
 		async signout(request) {
 			const config = resolveNextConfig(handlersConfig);
 			const secure = resolveCookieSecure(request, config);
-			newSession(adapt(await cookies()), config, secure).clear();
-			try {
-				await buildServerAuthClient(config).logout("device");
-			} catch {}
+			const scope = new URL(request.url).searchParams.get("scope") === "everywhere" ? "everywhere" : "device";
+			await newSession(adapt(await cookies()), config, secure).revoke(scope);
+			if (request.headers.get("accept")?.includes("application/json")) return Response.json({ signedOut: true });
 			return Response.redirect(new URL(request.url).origin + "/", 302);
+		},
+		async session() {
+			return Response.json(await auth(handlersConfig));
+		},
+		async subscriptionCredential() {
+			const config = resolveNextConfig(handlersConfig);
+			const current = await new ServerSession({
+				authClient: buildServerAuthClient(config),
+				secret: config.secret,
+				cookies: await requestCookies()
+			}).read();
+			if (!current) return Response.json({ status: "signed_out" }, { status: 401 });
+			return Response.json({
+				token: current.tokens.accessToken,
+				organizationId: current.session.claims.organizationId
+			});
 		}
 	};
 }
 //#endregion
-export { DEFAULT_SESSION_COOKIE, ServerSession, auth, createAuthHandlers, openSession, resolveNextConfig, sealSession };
+export { DEFAULT_SESSION_COOKIE, SESSION_COOKIE_MAX_BYTES, ServerSession, SessionCookieTooLargeError, auth, createAuthHandlers, openSession, resolveNextConfig, sealSession, sealedCookieByteLength };

package/dist/styles.css

@@ -10,8 +10,33 @@
  * (`:root`, a wrapper div, …) — that is the supported theming surface. Dark mode
  * follows the OS by default and defers to an explicit `.dark` / `[data-theme]`
  * on a host ancestor when one is present.
+ *
+ * ---------------------------------------------------------------------------
+ * Cascade: everything here lives in the `polyx` layer, and that is load-bearing.
+ *
+ * Unlayered CSS beats layered CSS outright — not by specificity, but by rank; no
+ * import order or selector weight changes it. Shipping these rules unlayered
+ * therefore beat every Tailwind utility a host wrote (Tailwind emits utilities
+ * into `@layer utilities`), so `className`/`triggerClassName` silently did
+ * nothing and hosts were pushed toward `!important`. Layering hands that control
+ * back: a host's utilities and unlayered CSS both outrank us now.
+ *
+ * The statement below fixes where `polyx` sits. It must land AFTER `base` —
+ * Tailwind's preflight puts `*, ::before, ::after { border: 0 solid }` there, and
+ * that would erase our own borders if we ranked lower — and BEFORE `utilities`,
+ * so host utilities still win. Naming Tailwind's layers costs nothing when the
+ * host doesn't use Tailwind: the names simply resolve to empty layers.
+ *
+ * Layer order is set by first declaration, so this only holds if our stylesheet
+ * is imported BEFORE the host's Tailwind entry. Import it later and `polyx` is
+ * appended last, which puts us back to outranking utilities — no worse than the
+ * unlayered behaviour, but not the fix either. Import us first.
  */
 
+@layer theme, base, polyx, components, utilities;
+
+@layer polyx {
+
 .polyx-signin {
 	/* Colors */
 	--polyx-brand: #4f46e5;
@@ -497,3 +522,194 @@
 	background: var(--polyx-input-bg);
 	border-color: var(--polyx-brand);
 }
+
+/* --- User button --------------------------------------------------------- */
+
+/* The root carries `polyx-signin` too, so the theme tokens above (and any consumer
+   override of them) reach this menu without a second declaration to keep in sync. */
+
+.polyx-userbutton {
+	position: relative;
+	display: inline-block;
+}
+
+.polyx-userbutton__trigger {
+	display: inline-flex;
+	align-items: center;
+	gap: 0.5rem;
+	padding: 0.125rem;
+	color: var(--polyx-fg);
+	background: none;
+	border: none;
+	border-radius: 999px;
+	cursor: pointer;
+	font: inherit;
+}
+
+.polyx-userbutton__trigger:focus-visible {
+	outline: none;
+	box-shadow: 0 0 0 3px var(--polyx-ring);
+}
+
+.polyx-userbutton__trigger-name {
+	padding-right: 0.25rem;
+	font-size: 0.875rem;
+	font-weight: 500;
+}
+
+.polyx-userbutton__avatar {
+	display: inline-flex;
+	flex: none;
+	align-items: center;
+	justify-content: center;
+	overflow: hidden;
+	border-radius: 999px;
+	background: color-mix(in srgb, var(--polyx-brand) 12%, transparent);
+	color: var(--polyx-brand);
+	font-size: 0.75rem;
+	font-weight: 600;
+	letter-spacing: 0.02em;
+	object-fit: cover;
+	user-select: none;
+}
+
+/* Placement is expressed as data attributes and resolved in CSS: the component measures which
+   side has room and says so; where that lands is a styling concern. `--polyx-gap` is the space
+   between trigger and menu, and the JS assumes the same 8px when it measures. */
+.polyx-userbutton__menu {
+	--polyx-gap: 0.5rem;
+	position: absolute;
+	z-index: 50;
+	min-width: 15rem;
+	padding: 0.375rem;
+	background: var(--polyx-bg);
+	border: 1px solid var(--polyx-border);
+	border-radius: var(--polyx-radius);
+	box-shadow: var(--polyx-shadow);
+}
+
+/* Vertical sides: offset above/below, then align along the horizontal axis. */
+.polyx-userbutton__menu[data-polyx-side="bottom"] {
+	top: calc(100% + var(--polyx-gap));
+}
+.polyx-userbutton__menu[data-polyx-side="top"] {
+	bottom: calc(100% + var(--polyx-gap));
+}
+.polyx-userbutton__menu[data-polyx-side="bottom"][data-polyx-align="end"],
+.polyx-userbutton__menu[data-polyx-side="top"][data-polyx-align="end"] {
+	right: 0;
+}
+.polyx-userbutton__menu[data-polyx-side="bottom"][data-polyx-align="start"],
+.polyx-userbutton__menu[data-polyx-side="top"][data-polyx-align="start"] {
+	left: 0;
+}
+.polyx-userbutton__menu[data-polyx-side="bottom"][data-polyx-align="center"],
+.polyx-userbutton__menu[data-polyx-side="top"][data-polyx-align="center"] {
+	left: 50%;
+	transform: translateX(-50%);
+}
+
+/* Horizontal sides: offset left/right, then align along the vertical axis. */
+.polyx-userbutton__menu[data-polyx-side="right"] {
+	left: calc(100% + var(--polyx-gap));
+}
+.polyx-userbutton__menu[data-polyx-side="left"] {
+	right: calc(100% + var(--polyx-gap));
+}
+.polyx-userbutton__menu[data-polyx-side="right"][data-polyx-align="end"],
+.polyx-userbutton__menu[data-polyx-side="left"][data-polyx-align="end"] {
+	bottom: 0;
+}
+.polyx-userbutton__menu[data-polyx-side="right"][data-polyx-align="start"],
+.polyx-userbutton__menu[data-polyx-side="left"][data-polyx-align="start"] {
+	top: 0;
+}
+.polyx-userbutton__menu[data-polyx-side="right"][data-polyx-align="center"],
+.polyx-userbutton__menu[data-polyx-side="left"][data-polyx-align="center"] {
+	top: 50%;
+	transform: translateY(-50%);
+}
+
+/* Consumer-supplied rows: give them room and get out of the way — no colours, no type, no
+   cursor. Whatever they render is theirs. */
+.polyx-userbutton__custom {
+	padding: 0.375rem 0.625rem;
+}
+
+.polyx-userbutton__identity {
+	display: flex;
+	align-items: center;
+	gap: 0.625rem;
+	padding: 0.5rem 0.625rem 0.625rem;
+	border-bottom: 1px solid var(--polyx-border);
+}
+
+.polyx-userbutton__identity-text {
+	display: flex;
+	min-width: 0;
+	flex-direction: column;
+}
+
+/* Names and emails are user data: let them truncate rather than stretch the menu. */
+.polyx-userbutton__name,
+.polyx-userbutton__email {
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+.polyx-userbutton__name {
+	font-size: 0.875rem;
+	font-weight: 600;
+}
+
+.polyx-userbutton__email {
+	font-size: 0.75rem;
+	color: var(--polyx-muted-fg);
+}
+
+.polyx-userbutton__items {
+	display: flex;
+	flex-direction: column;
+	margin: 0.375rem 0 0;
+	padding: 0;
+	list-style: none;
+}
+
+.polyx-userbutton__item {
+	display: flex;
+	width: 100%;
+	align-items: center;
+	gap: 0.5rem;
+	padding: 0.5rem 0.625rem;
+	color: var(--polyx-fg);
+	background: none;
+	border: none;
+	border-radius: var(--polyx-radius-sm);
+	cursor: pointer;
+	font: inherit;
+	font-size: 0.875rem;
+	text-align: left;
+	text-decoration: none;
+}
+
+.polyx-userbutton__item:hover {
+	background: color-mix(in srgb, var(--polyx-fg) 6%, transparent);
+}
+
+.polyx-userbutton__item:focus-visible {
+	outline: none;
+	box-shadow: 0 0 0 2px var(--polyx-ring);
+}
+
+.polyx-userbutton__icon {
+	flex: none;
+	width: 1rem;
+	height: 1rem;
+	color: var(--polyx-muted-fg);
+}
+
+/* Closes `@layer polyx` — opened at the top of the file. The rules above are left
+   unindented deliberately: wrapping the sheet in a layer is a cascade change, not a
+   reformat, and re-indenting 600 lines would bury it in the diff. */
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poly-x/next",
-  "version": "0.1.0-alpha.9",
+  "version": "0.1.1",
   "description": "PolyX SDK for Next.js App Router - components plus server helpers",
   "license": "MIT",
   "type": "module",
@@ -47,8 +47,8 @@
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.cts",
   "dependencies": {
-    "@poly-x/core": "0.1.0-alpha.9",
-    "@poly-x/react": "0.1.0-alpha.9"
+    "@poly-x/core": "0.1.1",
+    "@poly-x/react": "0.1.1"
   },
   "peerDependencies": {
     "next": ">=14",