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

package/dist/proxy.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-require("./server-session-DmR0ZJqP.cjs");
+require("./server-session-QJLA_Tz-.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-CjP44zFC.mjs";
 import { NextResponse } from "next/server";
 //#region src/proxy.ts
 /**

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

@@ -85,11 +85,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;
@@ -115,6 +116,24 @@ var ServerSession = class {
 			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);
 	}

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

@@ -85,11 +85,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;
@@ -115,6 +116,24 @@ var ServerSession = class {
 			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);
 	}

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-QJLA_Tz-.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 });
@@ -149,7 +224,11 @@ function createAuthHandlers(handlersConfig = {}) {
 				});
 				switch (outcome.type) {
 					case "authorized":
-						await newSession(adapt(await (0, next_headers.cookies)()), config, secure).establishFromCode(outcome.code, verifier, redirectUri);
+						await newSession(adapt(await (0, next_headers.cookies)()), config, secure).establishFromCode(outcome.code, verifier, redirectUri, {
+							...collectForwardedDeviceHeaders(request),
+							...geoHeaders,
+							...deviceContextHeaders
+						});
 						return Response.json({
 							status: "success",
 							redirectTo: afterSignInPath
@@ -249,7 +328,7 @@ 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);
+			await newSession(adapt(store), config, secure).establishFromCode(code, tx.verifier, tx.redirectUri, collectForwardedDeviceHeaders(request));
 			return Response.redirect(home, 302);
 		},
 		async refresh(request) {
@@ -258,14 +337,39 @@ 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
+			});
 		}
 	};
 }

package/dist/server.d.cts

@@ -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;
 }
@@ -108,6 +120,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 = {

package/dist/server.d.mts

@@ -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;
 }
@@ -108,6 +120,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 = {

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 sealSession, i as openSession, n as ServerSession, r as toAuthContext, t as DEFAULT_SESSION_COOKIE } from "./server-session-CjP44zFC.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 });
@@ -148,7 +223,11 @@ function createAuthHandlers(handlersConfig = {}) {
 				});
 				switch (outcome.type) {
 					case "authorized":
-						await newSession(adapt(await cookies()), config, secure).establishFromCode(outcome.code, verifier, redirectUri);
+						await newSession(adapt(await cookies()), config, secure).establishFromCode(outcome.code, verifier, redirectUri, {
+							...collectForwardedDeviceHeaders(request),
+							...geoHeaders,
+							...deviceContextHeaders
+						});
 						return Response.json({
 							status: "success",
 							redirectTo: afterSignInPath
@@ -248,7 +327,7 @@ 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);
+			await newSession(adapt(store), config, secure).establishFromCode(code, tx.verifier, tx.redirectUri, collectForwardedDeviceHeaders(request));
 			return Response.redirect(home, 302);
 		},
 		async refresh(request) {
@@ -257,14 +336,39 @@ 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
+			});
 		}
 	};
 }

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.0",
   "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.0",
+    "@poly-x/react": "0.1.0"
   },
   "peerDependencies": {
     "next": ">=14",