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

package/dist/proxy.cjs

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

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

@@ -1,12 +1,20 @@
 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: "/"
-};
+/**
+* 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/cookie-codec.ts
 const IV_BYTES = 12;
@@ -69,17 +77,20 @@ var ServerSession = class {
 	secret;
 	cookies;
 	cookieName;
+	secure;
 	constructor(options) {
 		this.authClient = options.authClient;
 		this.secret = options.secret;
 		this.cookies = options.cookies;
 		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;
@@ -105,12 +116,30 @@ 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);
 	}
 	async write(session) {
 		const sealed = await sealSession(session, this.secret);
-		this.cookies.set(this.cookieName, sealed, SESSION_COOKIE_OPTIONS);
+		this.cookies.set(this.cookieName, sealed, buildSessionCookieOptions(this.secure));
 	}
 };
 function toAuthContext(session) {

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

@@ -1,12 +1,20 @@
 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: "/"
-};
+/**
+* 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/cookie-codec.ts
 const IV_BYTES = 12;
@@ -69,17 +77,20 @@ var ServerSession = class {
 	secret;
 	cookies;
 	cookieName;
+	secure;
 	constructor(options) {
 		this.authClient = options.authClient;
 		this.secret = options.secret;
 		this.cookies = options.cookies;
 		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;
@@ -105,12 +116,30 @@ 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);
 	}
 	async write(session) {
 		const sealed = await sealSession(session, this.secret);
-		this.cookies.set(this.cookieName, sealed, SESSION_COOKIE_OPTIONS);
+		this.cookies.set(this.cookieName, sealed, buildSessionCookieOptions(this.secure));
 	}
 };
 function toAuthContext(session) {

package/dist/server.cjs

@@ -1,8 +1,15 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_server_session = require("./server-session-YbnXBt3c.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
+/** Parse a boolean-ish env var; undefined when unset/unrecognized (→ auto-derive). */
+function parseBoolEnv(value) {
+	if (value === void 0) return void 0;
+	const v = value.trim().toLowerCase();
+	if (v === "true" || v === "1") return true;
+	if (v === "false" || v === "0") return false;
+}
 function resolveNextConfig(overrides = {}) {
 	const publishableKey = overrides.publishableKey ?? process.env.NEXT_PUBLIC_POLYX_PUBLISHABLE_KEY;
 	const secret = overrides.secret ?? process.env.POLYX_SESSION_SECRET;
@@ -12,7 +19,8 @@ function resolveNextConfig(overrides = {}) {
 		publishableKey,
 		secret,
 		baseUrl: overrides.baseUrl ?? process.env.POLYX_BASE_URL,
-		signInUrl: overrides.signInUrl ?? process.env.NEXT_PUBLIC_POLYX_SIGN_IN_URL
+		signInUrl: overrides.signInUrl ?? process.env.NEXT_PUBLIC_POLYX_SIGN_IN_URL,
+		cookieSecure: overrides.cookieSecure ?? parseBoolEnv(process.env.POLYX_COOKIE_SECURE)
 	};
 }
 function buildServerAuthClient(config) {
@@ -48,6 +56,95 @@ function adapt(store) {
 async function requestCookies() {
 	return adapt(await (0, next_headers.cookies)());
 }
+/**
+* Decide the cookie `Secure` attribute for this request. An explicit `cookieSecure`
+* (from `POLYX_COOKIE_SECURE` or code) wins; otherwise derive from the transport —
+* `x-forwarded-proto` (proxied TLS) then the request URL — and fail secure if unknown.
+* A Secure cookie is dropped by the browser over http, so http/localhost must be false.
+*/
+function resolveCookieSecure(request, config) {
+	if (config.cookieSecure !== void 0) return config.cookieSecure;
+	const forwarded = request.headers.get("x-forwarded-proto");
+	if (forwarded) return forwarded.split(",")[0].trim() === "https";
+	try {
+		return new URL(request.url).protocol === "https:";
+	} catch {
+		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);
@@ -60,16 +157,18 @@ async function auth(overrides) {
 function createAuthHandlers(handlersConfig = {}) {
 	const callbackPath = handlersConfig.callbackPath ?? "/api/polyx/callback";
 	const afterSignInPath = handlersConfig.afterSignInPath ?? "/";
-	function newSession(store, config) {
+	function newSession(store, config, secure) {
 		return new require_server_session.ServerSession({
 			authClient: buildServerAuthClient(config),
 			secret: config.secret,
-			cookies: store
+			cookies: store,
+			secure
 		});
 	}
 	return {
 		async signin(request) {
 			const config = resolveNextConfig(handlersConfig);
+			const secure = resolveCookieSecure(request, config);
 			const redirectUri = `${new URL(request.url).origin}${callbackPath}`;
 			const { verifier, challenge } = await (0, _poly_x_core.generatePkce)();
 			const state = (0, _poly_x_core.randomState)();
@@ -79,7 +178,7 @@ function createAuthHandlers(handlersConfig = {}) {
 				redirectUri
 			}), {
 				httpOnly: true,
-				secure: true,
+				secure,
 				sameSite: "lax",
 				path: "/",
 				maxAge: VERIFIER_MAX_AGE
@@ -93,6 +192,7 @@ function createAuthHandlers(handlersConfig = {}) {
 		},
 		async authenticate(request) {
 			const config = resolveNextConfig(handlersConfig);
+			const secure = resolveCookieSecure(request, config);
 			const redirectUri = `${new URL(request.url).origin}${callbackPath}`;
 			const client = buildServerAuthClient(config);
 			let payload;
@@ -101,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 });
@@ -122,7 +224,11 @@ function createAuthHandlers(handlersConfig = {}) {
 				});
 				switch (outcome.type) {
 					case "authorized":
-						await newSession(adapt(await (0, next_headers.cookies)()), config).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
@@ -211,6 +317,7 @@ function createAuthHandlers(handlersConfig = {}) {
 		},
 		async callback(request) {
 			const config = resolveNextConfig(handlersConfig);
+			const secure = resolveCookieSecure(request, config);
 			const url = new URL(request.url);
 			const code = url.searchParams.get("code");
 			const state = url.searchParams.get("state");
@@ -221,21 +328,48 @@ 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).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() {
+		async refresh(request) {
 			const config = resolveNextConfig(handlersConfig);
-			const session = await newSession(await requestCookies(), config).refresh();
+			const secure = resolveCookieSecure(request, config);
+			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);
-			newSession(adapt(await (0, next_headers.cookies)()), config).clear();
-			try {
-				await buildServerAuthClient(config).logout("device");
-			} catch {}
+			const secure = resolveCookieSecure(request, config);
+			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

@@ -8,6 +8,13 @@ interface NextServerConfig {
   baseUrl?: string;
   /** Hosted sign-in page URL the signin route redirects to. */
   signInUrl?: string;
+  /**
+   * Force the session/verifier cookie `Secure` attribute. Leave undefined (default) to
+   * derive it from the request transport (https → true, http/localhost → false). Set via
+   * `POLYX_COOKIE_SECURE=true|false` only for edge cases (e.g. a TLS-terminating proxy
+   * that doesn't forward `x-forwarded-proto`).
+   */
+  cookieSecure?: boolean;
 }
 declare function resolveNextConfig(overrides?: Partial<NextServerConfig>): NextServerConfig;
 //#endregion
@@ -37,17 +44,36 @@ interface ServerSessionOptions {
   secret: string;
   cookies: CookieAdapter;
   cookieName?: string;
+  /**
+   * Whether to set the `Secure` attribute on the session cookie. Defaults to `true`
+   * (fail secure). Handlers derive it from the request transport so http/localhost dev
+   * works (a Secure cookie is dropped over http). See buildSessionCookieOptions.
+   */
+  secure?: boolean;
 }
 declare class ServerSession {
   private readonly authClient;
   private readonly secret;
   private readonly cookies;
   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;
 }
@@ -94,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

@@ -8,6 +8,13 @@ interface NextServerConfig {
   baseUrl?: string;
   /** Hosted sign-in page URL the signin route redirects to. */
   signInUrl?: string;
+  /**
+   * Force the session/verifier cookie `Secure` attribute. Leave undefined (default) to
+   * derive it from the request transport (https → true, http/localhost → false). Set via
+   * `POLYX_COOKIE_SECURE=true|false` only for edge cases (e.g. a TLS-terminating proxy
+   * that doesn't forward `x-forwarded-proto`).
+   */
+  cookieSecure?: boolean;
 }
 declare function resolveNextConfig(overrides?: Partial<NextServerConfig>): NextServerConfig;
 //#endregion
@@ -37,17 +44,36 @@ interface ServerSessionOptions {
   secret: string;
   cookies: CookieAdapter;
   cookieName?: string;
+  /**
+   * Whether to set the `Secure` attribute on the session cookie. Defaults to `true`
+   * (fail secure). Handlers derive it from the request transport so http/localhost dev
+   * works (a Secure cookie is dropped over http). See buildSessionCookieOptions.
+   */
+  secure?: boolean;
 }
 declare class ServerSession {
   private readonly authClient;
   private readonly secret;
   private readonly cookies;
   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;
 }
@@ -94,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,7 +1,14 @@
-import { a as sealSession, i as openSession, n as ServerSession, r as toAuthContext, t as DEFAULT_SESSION_COOKIE } from "./server-session-B3zJ7CS8.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
+/** Parse a boolean-ish env var; undefined when unset/unrecognized (→ auto-derive). */
+function parseBoolEnv(value) {
+	if (value === void 0) return void 0;
+	const v = value.trim().toLowerCase();
+	if (v === "true" || v === "1") return true;
+	if (v === "false" || v === "0") return false;
+}
 function resolveNextConfig(overrides = {}) {
 	const publishableKey = overrides.publishableKey ?? process.env.NEXT_PUBLIC_POLYX_PUBLISHABLE_KEY;
 	const secret = overrides.secret ?? process.env.POLYX_SESSION_SECRET;
@@ -11,7 +18,8 @@ function resolveNextConfig(overrides = {}) {
 		publishableKey,
 		secret,
 		baseUrl: overrides.baseUrl ?? process.env.POLYX_BASE_URL,
-		signInUrl: overrides.signInUrl ?? process.env.NEXT_PUBLIC_POLYX_SIGN_IN_URL
+		signInUrl: overrides.signInUrl ?? process.env.NEXT_PUBLIC_POLYX_SIGN_IN_URL,
+		cookieSecure: overrides.cookieSecure ?? parseBoolEnv(process.env.POLYX_COOKIE_SECURE)
 	};
 }
 function buildServerAuthClient(config) {
@@ -47,6 +55,95 @@ function adapt(store) {
 async function requestCookies() {
 	return adapt(await cookies());
 }
+/**
+* Decide the cookie `Secure` attribute for this request. An explicit `cookieSecure`
+* (from `POLYX_COOKIE_SECURE` or code) wins; otherwise derive from the transport —
+* `x-forwarded-proto` (proxied TLS) then the request URL — and fail secure if unknown.
+* A Secure cookie is dropped by the browser over http, so http/localhost must be false.
+*/
+function resolveCookieSecure(request, config) {
+	if (config.cookieSecure !== void 0) return config.cookieSecure;
+	const forwarded = request.headers.get("x-forwarded-proto");
+	if (forwarded) return forwarded.split(",")[0].trim() === "https";
+	try {
+		return new URL(request.url).protocol === "https:";
+	} catch {
+		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);
@@ -59,16 +156,18 @@ async function auth(overrides) {
 function createAuthHandlers(handlersConfig = {}) {
 	const callbackPath = handlersConfig.callbackPath ?? "/api/polyx/callback";
 	const afterSignInPath = handlersConfig.afterSignInPath ?? "/";
-	function newSession(store, config) {
+	function newSession(store, config, secure) {
 		return new ServerSession({
 			authClient: buildServerAuthClient(config),
 			secret: config.secret,
-			cookies: store
+			cookies: store,
+			secure
 		});
 	}
 	return {
 		async signin(request) {
 			const config = resolveNextConfig(handlersConfig);
+			const secure = resolveCookieSecure(request, config);
 			const redirectUri = `${new URL(request.url).origin}${callbackPath}`;
 			const { verifier, challenge } = await generatePkce();
 			const state = randomState();
@@ -78,7 +177,7 @@ function createAuthHandlers(handlersConfig = {}) {
 				redirectUri
 			}), {
 				httpOnly: true,
-				secure: true,
+				secure,
 				sameSite: "lax",
 				path: "/",
 				maxAge: VERIFIER_MAX_AGE
@@ -92,6 +191,7 @@ function createAuthHandlers(handlersConfig = {}) {
 		},
 		async authenticate(request) {
 			const config = resolveNextConfig(handlersConfig);
+			const secure = resolveCookieSecure(request, config);
 			const redirectUri = `${new URL(request.url).origin}${callbackPath}`;
 			const client = buildServerAuthClient(config);
 			let payload;
@@ -100,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 });
@@ -121,7 +223,11 @@ function createAuthHandlers(handlersConfig = {}) {
 				});
 				switch (outcome.type) {
 					case "authorized":
-						await newSession(adapt(await cookies()), config).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
@@ -210,6 +316,7 @@ function createAuthHandlers(handlersConfig = {}) {
 		},
 		async callback(request) {
 			const config = resolveNextConfig(handlersConfig);
+			const secure = resolveCookieSecure(request, config);
 			const url = new URL(request.url);
 			const code = url.searchParams.get("code");
 			const state = url.searchParams.get("state");
@@ -220,21 +327,48 @@ 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).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() {
+		async refresh(request) {
 			const config = resolveNextConfig(handlersConfig);
-			const session = await newSession(await requestCookies(), config).refresh();
+			const secure = resolveCookieSecure(request, config);
+			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);
-			newSession(adapt(await cookies()), config).clear();
-			try {
-				await buildServerAuthClient(config).logout("device");
-			} catch {}
+			const secure = resolveCookieSecure(request, config);
+			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;
@@ -208,6 +233,13 @@
 	margin-bottom: 0.75rem;
 }
 
+/* Branding logo fetched from the app's tokens (FR-BRND). */
+.polyx-signin__brand-logo {
+	max-height: 2.25rem;
+	width: auto;
+	object-fit: contain;
+}
+
 .polyx-signin__heading {
 	margin: 0;
 	font-size: 1.375rem;
@@ -270,6 +302,56 @@
 	cursor: not-allowed;
 }
 
+/* --- Password reveal toggle --------------------------------------------- */
+
+.polyx-signin__input-wrap {
+	position: relative;
+	display: flex;
+	align-items: center;
+}
+
+/* Leave room for the reveal button so masked text never slides under it. */
+.polyx-signin__input--has-reveal {
+	padding-right: 2.75rem;
+}
+
+.polyx-signin__reveal {
+	position: absolute;
+	right: 0.25rem;
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	width: 2rem;
+	height: 2rem;
+	padding: 0;
+	color: var(--polyx-muted-fg);
+	background: transparent;
+	border: none;
+	border-radius: var(--polyx-radius-sm);
+	cursor: pointer;
+	transition: color 0.15s ease, box-shadow 0.15s ease;
+}
+
+.polyx-signin__reveal:hover:not(:disabled) {
+	color: var(--polyx-fg);
+}
+
+.polyx-signin__reveal:focus-visible {
+	outline: none;
+	color: var(--polyx-fg);
+	box-shadow: 0 0 0 3px var(--polyx-ring);
+}
+
+.polyx-signin__reveal:disabled {
+	cursor: not-allowed;
+	opacity: 0.6;
+}
+
+.polyx-signin__reveal svg {
+	width: 1.125rem;
+	height: 1.125rem;
+}
+
 /* --- Buttons ------------------------------------------------------------- */
 
 .polyx-signin__submit,
@@ -440,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.8",
+  "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.8",
-    "@poly-x/react": "0.1.0-alpha.8"
+    "@poly-x/core": "0.1.0",
+    "@poly-x/react": "0.1.0"
   },
   "peerDependencies": {
     "next": ">=14",