@poly-x/next 0.1.1 → 0.3.0

package/dist/server.mjs

@@ -1,6 +1,196 @@
-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 { n as readSessionCookie, t as DEFAULT_SESSION_COOKIE } from "./session-cookie-C23WspJZ.mjs";
+import { AuthClient, FetchTransport, PROFILE_FIELDS, PolyXError, SessionExpiredError, SessionRevokedError, deriveDisplayClaims, generatePkce, randomState, resolveConfig } from "@poly-x/core";
 import { cookies } from "next/headers";
+//#region src/cookie-codec.ts
+/**
+* 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.
+*/
+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);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(text) {
+	const base64 = text.replace(/-/g, "+").replace(/_/g, "/");
+	const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+	const binary = atob(padded);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+async function deriveKey(secret) {
+	const hash = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(secret));
+	return crypto.subtle.importKey("raw", hash, "AES-GCM", false, ["encrypt", "decrypt"]);
+}
+async function sealSession(session, secret, options = {}) {
+	const key = await deriveKey(secret);
+	const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+	const plaintext = new TextEncoder().encode(JSON.stringify(session));
+	const ciphertext = new Uint8Array(await crypto.subtle.encrypt({
+		name: "AES-GCM",
+		iv
+	}, key, plaintext));
+	const packed = new Uint8Array(iv.length + ciphertext.length);
+	packed.set(iv);
+	packed.set(ciphertext, iv.length);
+	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;
+}
+function nonEmptyString(value) {
+	return typeof value === "string" && value.length > 0;
+}
+/**
+* Does this decrypt to something every caller can safely use?
+*
+* Decryption proving *authenticity* is not the same as proving *shape*. A cookie sealed with the
+* right secret by a different `StoredSession` version is authentic and unusable — and the SDK is
+* pre-1.0, so that shape has already grown once and will again.
+*
+* It matters because eight call sites reach straight through `session.session.claims`, including
+* `toAuthContext` behind `auth()`. Handing back a malformed object turns each into a TypeError, and
+* the failure does not self-heal: `read()` *succeeded*, so nothing clears the cookie and the person
+* gets a 500 on every request until they clear it by hand. Reporting `null` instead routes into the
+* signed-out path that already exists, which re-authenticates and replaces the cookie.
+*
+* Checked here rather than at each call site because this is the one place every read passes
+* through — a guard at the boundary cannot be forgotten by the ninth caller.
+*/
+function isUsableSession(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const { tokens, session } = value;
+	if (!tokens || typeof tokens !== "object") return false;
+	if (!nonEmptyString(tokens.accessToken)) return false;
+	if (!session || typeof session !== "object") return false;
+	const claims = session.claims;
+	if (!claims || typeof claims !== "object") return false;
+	return nonEmptyString(claims.userId);
+}
+async function openSession(token, secret) {
+	try {
+		const packed = base64UrlDecode(token);
+		if (packed.length <= IV_BYTES) return null;
+		const iv = packed.slice(0, IV_BYTES);
+		const ciphertext = packed.slice(IV_BYTES);
+		const key = await deriveKey(secret);
+		const plaintext = await crypto.subtle.decrypt({
+			name: "AES-GCM",
+			iv
+		}, key, ciphertext);
+		const parsed = JSON.parse(new TextDecoder().decode(plaintext));
+		return isUsableSession(parsed) ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/auth-event.ts
+/**
+* One-shot auth events that survive a navigation (F017 / FR-CLIENT-5).
+*
+* Sign-in and sign-out are full-page navigations, so anything an app queues before them —
+* a toast, an analytics call — is destroyed when the page unloads. Odin built ~80 lines of
+* cookie plumbing to show "Logged in successfully"; this absorbs the shape.
+*
+* A cookie rather than a query parameter on the redirect target: the destination may
+* redirect again before it renders (a route gate sending an unauthorised user elsewhere,
+* for one), which drops the query and the event with it. A cookie survives the chain.
+*
+* It carries no secret — it exists to be read by page script, which is why it is
+* deliberately NOT httpOnly. Never put anything in it that the browser should not see.
+*/
+/** The cookie the SDK publishes a one-shot auth event in. Readable by script, by design. */
+const AUTH_EVENT_COOKIE = "polyx_auth_event";
+/** Serialize the `Set-Cookie` value for a one-shot event. */
+function buildAuthEventCookie(kind, secure) {
+	return `${AUTH_EVENT_COOKIE}=${kind}; Path=/; Max-Age=30; SameSite=Lax${secure ? "; Secure" : ""}`;
+}
+//#endregion
+//#region src/public-origin.ts
+/** First entry of a comma-separated proxy chain, matching how `resolveCookieSecure` reads proto. */
+function firstHop(value) {
+	const first = value?.split(",")[0]?.trim();
+	return first && first.length > 0 ? first : void 0;
+}
+/**
+* A forwarded host must be `hostname[:port]` (or a bracketed IPv6 literal) and nothing
+* else. Without this check a value like `http://[bad` concatenates into
+* `https://http://[bad`, which the URL parser happily reads as host `http` and yields the
+* nonsense origin `https://http` — a broken redirect URI produced from hostile input
+* rather than a clean fall-back.
+*/
+const VALID_FORWARDED_HOST = /^(?:\[[0-9a-fA-F:.]+\]|[a-zA-Z0-9._-]+)(?::\d{1,5})?$/;
+/** `origin` of a URL, or undefined when it will not parse. */
+function originOf(candidate) {
+	try {
+		const url = new URL(candidate);
+		return url.origin && url.origin !== "null" ? url.origin : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Resolve the origin the browser actually reached this app on.
+*
+* Precedence: explicit configuration → forwarded headers (only when trusted) → the
+* request URL. Every step falls through on malformed input rather than emitting a broken
+* origin, because a broken `redirect_uri` fails at the platform with a message about
+* credentials rather than configuration.
+*/
+function resolvePublicOrigin(request, options = {}) {
+	if (options.publicOrigin) {
+		const configured = originOf(options.publicOrigin);
+		if (configured) return configured;
+	}
+	if (options.trustForwardedOrigin) {
+		const host = firstHop(request.headers.get("x-forwarded-host"));
+		if (host && VALID_FORWARDED_HOST.test(host)) {
+			const forwarded = originOf(`${firstHop(request.headers.get("x-forwarded-proto")) ?? originOf(request.url)?.split(":")[0] ?? "https"}://${host}`);
+			if (forwarded) return forwarded;
+		}
+	}
+	return originOf(request.url) ?? "";
+}
+//#endregion
 //#region src/config.ts
 /** Parse a boolean-ish env var; undefined when unset/unrecognized (→ auto-derive). */
 function parseBoolEnv(value) {
@@ -19,7 +209,10 @@ function resolveNextConfig(overrides = {}) {
 		secret,
 		baseUrl: overrides.baseUrl ?? process.env.POLYX_BASE_URL,
 		signInUrl: overrides.signInUrl ?? process.env.NEXT_PUBLIC_POLYX_SIGN_IN_URL,
-		cookieSecure: overrides.cookieSecure ?? parseBoolEnv(process.env.POLYX_COOKIE_SECURE)
+		cookieSecure: overrides.cookieSecure ?? parseBoolEnv(process.env.POLYX_COOKIE_SECURE),
+		publicOrigin: overrides.publicOrigin ?? process.env.POLYX_PUBLIC_ORIGIN,
+		trustForwardedOrigin: overrides.trustForwardedOrigin ?? parseBoolEnv(process.env.POLYX_TRUST_FORWARDED_ORIGIN) ?? false,
+		realtimeBaseUrl: overrides.realtimeBaseUrl ?? process.env.POLYX_REALTIME_URL
 	};
 }
 function buildServerAuthClient(config) {
@@ -34,6 +227,507 @@ function buildServerAuthClient(config) {
 	});
 }
 //#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
+* httpOnly cookie on the consumer's domain, exchanged/refreshed server-side.
+* Composes core's AuthClient with a CookieAdapter seam; fully unit-testable.
+*/
+var ServerSession = class {
+	authClient;
+	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, forwardedHeaders) {
+		const stored = await this.authClient.exchangeCode({
+			code,
+			codeVerifier,
+			redirectUri,
+			forwardedHeaders
+		});
+		await this.write(stored);
+		return stored;
+	}
+	async read() {
+		const raw = this.cookies.get(this.cookieName);
+		if (!raw) return null;
+		return openSession(raw, this.secret);
+	}
+	/**
+	* Re-seal the session with an updated **display** subset — name, email, avatar (ADR-0006).
+	*
+	* Needed because `normalizeRefresh` carries claims forward unchanged: the display claims are
+	* derived once, at login, and never again. So after a profile save the session still describes
+	* the person as they were when they signed in, and every surface reading `useUser()` shows the
+	* old name and photo until they sign out and back in (FR-PROF-5).
+	*
+	* Deliberately narrow. `userId` and `organizationId` are authorization-relevant and are **not**
+	* writable here — a profile save must never become a route to changing who the session is for,
+	* whatever the platform echoes back. Only the three display fields move.
+	*
+	* Returns `false` rather than throwing when the session cannot be re-sealed (an oversized
+	* cookie, a missing session): the caller's own operation has usually already succeeded
+	* upstream, and failing it because the *display* copy could not be updated would report a
+	* successful save as a failure.
+	*/
+	async updateDisplayClaims(patch) {
+		const current = await this.read();
+		if (!current) return false;
+		const next = {
+			...current,
+			session: {
+				...current.session,
+				claims: {
+					...current.session.claims,
+					...patch.displayName !== void 0 ? { displayName: patch.displayName } : {},
+					...patch.email !== void 0 ? { email: patch.email } : {},
+					...patch.avatarUrl !== void 0 ? { avatarUrl: patch.avatarUrl } : {}
+				}
+			}
+		};
+		try {
+			await this.write(next);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/** Rotate the tokens; clears the cookie (returns null) on a terminal refresh failure. */
+	async refresh() {
+		const current = await this.read();
+		if (!current) return null;
+		try {
+			const next = await this.authClient.createRefresher()(current);
+			await this.write(next);
+			return next;
+		} catch (error) {
+			if (error instanceof SessionRevokedError || error instanceof SessionExpiredError) {
+				this.clear();
+				return null;
+			}
+			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, { cookieName: this.cookieName });
+		this.cookies.set(this.cookieName, sealed, buildSessionCookieOptions(this.secure));
+	}
+};
+function toAuthContext(session) {
+	if (!session) return {
+		isSignedIn: false,
+		userId: null,
+		claims: null
+	};
+	return {
+		isSignedIn: true,
+		userId: session.session.claims.userId,
+		organizationId: session.session.claims.organizationId,
+		claims: session.session.claims
+	};
+}
+//#endregion
+//#region src/session-context.ts
+/**
+* Session context (F015 / FR-SESS-2…6).
+*
+* The sealed session carries only a bounded display subset (`poly-x-sdk/ADR-0006`) —
+* correct, because bulk authorization must not live in a cookie. But it left every app
+* needing more than `{userId, organizationId}` to assemble it themselves, and both did:
+* an `/api/polyx/context` route plus a hand-written profile fetch against poly-auth,
+* roughly 170 lines each. The app was issuing platform API calls the SDK should make.
+*
+* The fix is that the SDK makes the same call — NOT that authorization data moves into
+* the session. ADR-0006 is unchanged and apps keep deriving their own route gating.
+*
+* One deliberate improvement over the copies being absorbed: they returned `null` on any
+* failure, which conflates "the directory was briefly unavailable" with "this user has no
+* profile". An app cannot tell those apart, and the safe-looking reaction — sign the user
+* out — is wrong for the first. Here the two are distinct.
+*/
+const SIGNED_OUT = {
+	isSignedIn: false,
+	userId: null,
+	claims: null,
+	user: null
+};
+/**
+* Fetch the platform user profile with the session's own credential.
+*
+* `organization-id` is required, not optional: poly-auth rejects the call outright
+* without it, and it is what scopes the returned permission to the workspace the user
+* actually signed in to.
+*/
+async function fetchProfile(baseUrl, userId, accessToken, organizationId) {
+	try {
+		const response = await fetch(`${baseUrl.replace(/\/$/, "")}/v1/user/${encodeURIComponent(userId)}`, { headers: {
+			Authorization: `Bearer ${accessToken}`,
+			"organization-id": organizationId,
+			Accept: "application/json"
+		} });
+		if (response.status === 401 || response.status === 403) return {
+			user: null,
+			status: "unavailable",
+			unauthorized: true
+		};
+		if (!response.ok) return {
+			user: null,
+			status: "unavailable",
+			unauthorized: false
+		};
+		const body = await response.json();
+		return {
+			user: body.data ?? body ?? null,
+			status: "ok",
+			unauthorized: false
+		};
+	} catch {
+		return {
+			user: null,
+			status: "unavailable",
+			unauthorized: false
+		};
+	}
+}
+function adaptStore$1(store) {
+	return {
+		get: (name) => store.get(name)?.value,
+		set: (name, value, options) => store.set(name, value, options),
+		delete: (name) => store.delete(name)
+	};
+}
+/**
+* Read who is signed in, including the platform profile.
+*
+* Safe in a Server Component: it reads the session and never writes it. The access
+* credential is used to call the platform and is never part of the result (FR-SESS-5).
+*/
+async function getSessionContext(options = {}) {
+	const config = resolveNextConfig(options);
+	const current = await new ServerSession({
+		authClient: buildServerAuthClient(config),
+		secret: config.secret,
+		cookies: adaptStore$1(await cookies())
+	}).read();
+	if (!current) return SIGNED_OUT;
+	const { claims } = current.session;
+	const base = {
+		isSignedIn: true,
+		userId: claims.userId,
+		organizationId: claims.organizationId,
+		claims,
+		user: null
+	};
+	if (options.skipProfile) return base;
+	if (!claims.organizationId) return {
+		...base,
+		profileStatus: "no_organization"
+	};
+	if (!config.baseUrl) return {
+		...base,
+		profileStatus: "unavailable"
+	};
+	const result = await fetchProfile(config.baseUrl, claims.userId, current.tokens.accessToken, claims.organizationId);
+	if (result.unauthorized) return SIGNED_OUT;
+	return {
+		...base,
+		user: result.user,
+		profileStatus: result.status
+	};
+}
+//#endregion
+//#region src/handler.ts
+/**
+* One-declaration route mounting (F012 / FR-MOUNT-1…5).
+*
+* `createAuthHandlers()` returns nine handler methods and mounts nothing, so every
+* consuming app hand-wrote its own action→handler switch plus the GET/POST split —
+* ~100 lines, twice, identically. Worse, the published example
+* (`export const { signin: GET } = createAuthHandlers()`) cannot dispatch by action at
+* all: it wires exactly one action and the rest fail at runtime.
+*
+* This is a thin dispatcher over the existing handlers, not a replacement.
+* `createAuthHandlers()` stays exported and unchanged for apps that already wired it.
+*/
+/**
+* URL segment → handler key. The segments are kebab-case (what a developer types in a
+* path); the handler keys are camelCase (what the object exposes). Keeping the map
+* explicit means a new handler cannot be reached by an unintended segment spelling.
+*/
+const POLYX_ACTIONS = {
+	signin: "signin",
+	authenticate: "authenticate",
+	"forgot-password": "forgotPassword",
+	"reset-password": "resetPassword",
+	callback: "callback",
+	hop: "hop",
+	"hop-complete": "hopComplete",
+	refresh: "refresh",
+	signout: "signout",
+	session: "session",
+	"subscription-credential": "subscriptionCredential",
+	"realtime-ticket": "realtimeTicket",
+	profile: "profile"
+};
+/**
+* Allowed methods per action, stated rather than inferred.
+*
+* `signout` accepts GET as well as POST because signing out has to be a full-page
+* navigation: a client-side redirect leaves the httpOnly cookie in place and the route
+* gate bounces the user straight back in. Both consumers hard-code a
+* `window.location` sign-out for exactly this reason.
+*/
+const POLYX_ACTION_METHODS = {
+	signin: ["GET"],
+	callback: ["GET"],
+	session: ["GET"],
+	"subscription-credential": ["GET"],
+	"realtime-ticket": ["GET"],
+	authenticate: ["POST"],
+	hop: ["POST"],
+	"hop-complete": ["POST"],
+	"forgot-password": ["POST"],
+	"reset-password": ["POST"],
+	refresh: ["POST"],
+	profile: ["GET", "POST"],
+	signout: ["GET", "POST"]
+};
+function jsonError$1(error, status) {
+	return Response.json({ error }, { status });
+}
+/**
+* Resolve the action from the ROUTE PARAMS, never from the request URL.
+*
+* The handler must not trust a path it did not route: the framework tells us what it
+* matched, and a URL string can disagree with that (rewrites, proxies, or a crafted
+* request). Exactly one segment is required, so `/api/polyx/session/extra` is a 404
+* rather than silently resolving to `session`.
+*/
+function resolveActionSegment(params) {
+	const values = Object.values(params);
+	if (values.length !== 1) return null;
+	const segments = values[0];
+	if (!Array.isArray(segments)) return typeof segments === "string" ? segments : null;
+	if (segments.length !== 1) return null;
+	return segments[0] ?? null;
+}
+function isKnownAction(segment) {
+	return Object.prototype.hasOwnProperty.call(POLYX_ACTIONS, segment);
+}
+/**
+* Mount every SDK auth route from one declaration:
+*
+* ```ts
+* // app/api/polyx/[...polyx]/route.ts
+* export const { GET, POST } = createPolyXHandler();
+* ```
+*
+* `handlers` is injectable for tests; production callers pass only the config.
+*/
+function createPolyXHandler(config = {}, handlers = createAuthHandlers(config)) {
+	async function dispatch(request, context, method) {
+		const segment = resolveActionSegment(await context.params);
+		if (segment === null || !isKnownAction(segment)) return jsonError$1("unknown_action", 404);
+		if (!POLYX_ACTION_METHODS[segment].includes(method)) return jsonError$1("method_not_allowed", 405);
+		return handlers[POLYX_ACTIONS[segment]](request);
+	}
+	return {
+		GET: (request, context) => dispatch(request, context, "GET"),
+		POST: (request, context) => dispatch(request, context, "POST")
+	};
+}
+//#endregion
+//#region src/data-proxy.ts
+/**
+* The authenticated data path (F014 / FR-DATA-1…10).
+*
+* Under BFF custody the browser holds no credential, so every authenticated call to an
+* app's own backend has to be proxied server-side. The SDK never shipped that half, even
+* though the tech discovery that chose this custody model said it would ("proxies/
+* decorates outbound PolyX calls"). So both live integrations wrote it themselves — and
+* the result is byte-for-byte identical in each, ~250 lines of the subtlest code in the
+* whole integration, sitting in two places to drift apart.
+*
+* This is a PORT of that proven implementation, not a rewrite: it has run in production
+* in two apps. Two things are deliberately better here:
+*
+*   1. Refresh is IN-PROCESS (`refreshSession`, F013). The consumers had to `fetch` their
+*      own `/api/polyx/refresh` route and re-parse the returned `Set-Cookie` to recover
+*      the new token — a network round trip through their own edge, and a fragile parse.
+*   2. Rotation needs no manual propagation. `refreshSession` writes through Next's cookie
+*      store, so the refreshed cookie lands on the response by itself; the consumers had
+*      to append the re-parsed `Set-Cookie` by hand.
+*/
+/** Never copied from the browser request onto the upstream call. */
+const STRIP_REQUEST_HEADERS = /* @__PURE__ */ new Set([
+	"host",
+	"connection",
+	"content-length",
+	"cookie",
+	"authorization"
+]);
+/** Never copied from the upstream response back to the browser. */
+const STRIP_RESPONSE_HEADERS = /* @__PURE__ */ new Set([
+	"content-encoding",
+	"content-length",
+	"transfer-encoding",
+	"connection",
+	"set-cookie"
+]);
+function jsonError(message, status) {
+	return Response.json({ message }, { status });
+}
+function trailingSlashOff(base) {
+	return base.replace(/\/$/, "");
+}
+/** The catch-all segments, whatever the route names its parameter. */
+function pathSegments(params) {
+	for (const value of Object.values(params)) if (Array.isArray(value)) return value;
+	return [];
+}
+/**
+* Read the sealed session's access credential. Server-side only — this value must never
+* be handed to the browser.
+*/
+async function readAccessToken(store, config) {
+	return (await new ServerSession({
+		authClient: buildServerAuthClient(config),
+		secret: config.secret,
+		cookies: store
+	}).read())?.tokens.accessToken ?? null;
+}
+function adaptStore(store) {
+	return {
+		get: (name) => store.get(name)?.value,
+		set: (name, value, options) => store.set(name, value, options),
+		delete: (name) => store.delete(name)
+	};
+}
+/**
+* Mount an authenticated proxy to one declared backend:
+*
+* ```ts
+* // app/api/billing/proxy/[...path]/route.ts
+* export const { GET, POST, PUT, PATCH, DELETE } = createDataProxy({
+*   upstream: process.env.BILLING_URL!,
+*   label: "Billing",
+* });
+* ```
+*
+* The client keeps calling a same-origin path; the credential is attached on this side of
+* it and never reaches page scripts.
+*/
+function createDataProxy(options) {
+	const label = options.label ?? "PolyX";
+	async function handle(request, context) {
+		const upstreamBase = typeof options.upstream === "function" ? options.upstream() : options.upstream;
+		if (!upstreamBase) return jsonError(`${label} proxy misconfigured: no upstream URL configured.`, 500);
+		let config;
+		try {
+			config = resolveNextConfig(options);
+		} catch {
+			return jsonError(`${label} proxy misconfigured: PolyX configuration is incomplete.`, 500);
+		}
+		const accessToken = await readAccessToken(adaptStore(await cookies()), config);
+		if (!accessToken) return jsonError("Not authenticated.", 401);
+		const incoming = new URL(request.url);
+		const target = `${trailingSlashOff(upstreamBase)}/${pathSegments(await context.params).map(encodeURIComponent).join("/")}${incoming.search}`;
+		const baseHeaders = new Headers();
+		request.headers.forEach((value, key) => {
+			if (!STRIP_REQUEST_HEADERS.has(key.toLowerCase())) baseHeaders.set(key, value);
+		});
+		const method = request.method.toUpperCase();
+		const body = method !== "GET" && method !== "HEAD" ? await request.arrayBuffer() : void 0;
+		const send = (token) => {
+			const headers = new Headers(baseHeaders);
+			headers.set("Authorization", `Bearer ${token}`);
+			return fetch(target, {
+				method,
+				headers,
+				body,
+				redirect: "manual"
+			});
+		};
+		let upstream = await send(accessToken);
+		if (upstream.status === 401) {
+			const refreshed = await refreshSession({
+				...options,
+				request
+			}).catch(() => null);
+			if (!refreshed?.isSignedIn || !refreshed.accessToken) return jsonError("Not authenticated.", 401);
+			upstream = await send(refreshed.accessToken);
+		}
+		const responseHeaders = new Headers();
+		upstream.headers.forEach((value, key) => {
+			if (!STRIP_RESPONSE_HEADERS.has(key.toLowerCase())) responseHeaders.set(key, value);
+		});
+		return new Response(upstream.body, {
+			status: upstream.status,
+			statusText: upstream.statusText,
+			headers: responseHeaders
+		});
+	}
+	return {
+		GET: handle,
+		POST: handle,
+		PUT: handle,
+		PATCH: handle,
+		DELETE: handle,
+		HEAD: handle
+	};
+}
+//#endregion
 //#region src/server.ts
 /**
 * @poly-x/next/server — App Router server helpers (F007). `auth()` reads the
@@ -45,6 +739,25 @@ const VERIFIER_COOKIE = "polyx_pkce";
 const VERIFIER_MAX_AGE = 600;
 /** poly-auth's own floor (Joi: min 6, max 128) — reject early rather than round-trip. */
 const MIN_PASSWORD_LENGTH = 6;
+/**
+* Narrow the platform's user record to what the profile surface needs.
+*
+* Relaying the whole record would leak whatever else poly-auth happens to return alongside it —
+* role and permission references, internal flags, fields added by a future release nobody
+* revisited this code for. An allow-list means new upstream fields stay server-side by default.
+*/
+function pickProfileFields(user) {
+	const picked = {};
+	for (const field of [
+		...PROFILE_FIELDS,
+		"profilePicture",
+		"email"
+	]) {
+		const value = user[field];
+		if (typeof value === "string") picked[field] = value;
+	}
+	return picked;
+}
 function adapt(store) {
 	return {
 		get: (name) => store.get(name)?.value,
@@ -153,6 +866,57 @@ async function auth(overrides) {
 		cookies: await requestCookies()
 	}).read());
 }
+/**
+* Single-flight keyed on the per-request cookie store. Next hands back the same store
+* object for the life of a request, so concurrent callers within one request coalesce,
+* while unrelated users in the same server process never serialise behind each other —
+* which a module-level lock would have caused.
+*/
+const inFlightRefresh = /* @__PURE__ */ new WeakMap();
+/**
+* Refresh the current session from server code (F013 / FR-SESS-1).
+*
+* Before this existed there was no supported way to do it, so both live integrations
+* did something worse: the server issued an HTTP request to its OWN
+* `/api/polyx/refresh` route and then re-parsed the returned `Set-Cookie` header to
+* recover the new token. That is a network round trip through the app's own edge to do
+* something already possible in-process, and the header re-parse is fragile.
+*
+* Terminal-vs-transient classification lives in `ServerSession.refresh()` and is not
+* duplicated here: a revoked family or an unstorable session signs the user out, and a
+* transient upstream failure propagates so the caller can fail closed.
+*/
+async function refreshSession(options = {}) {
+	const store = await cookies();
+	const pending = inFlightRefresh.get(store);
+	if (pending) return pending;
+	const run = (async () => {
+		const config = resolveNextConfig(options);
+		const secure = options.request ? resolveCookieSecure(options.request, config) : config.cookieSecure ?? true;
+		const next = await new ServerSession({
+			authClient: buildServerAuthClient(config),
+			secret: config.secret,
+			cookies: adapt(store),
+			secure
+		}).refresh();
+		if (!next) return {
+			isSignedIn: false,
+			accessToken: null,
+			claims: null
+		};
+		return {
+			isSignedIn: true,
+			accessToken: next.tokens.accessToken,
+			claims: next.session.claims
+		};
+	})();
+	inFlightRefresh.set(store, run);
+	try {
+		return await run;
+	} finally {
+		inFlightRefresh.delete(store);
+	}
+}
 function createAuthHandlers(handlersConfig = {}) {
 	const callbackPath = handlersConfig.callbackPath ?? "/api/polyx/callback";
 	const afterSignInPath = handlersConfig.afterSignInPath ?? "/";
@@ -168,7 +932,7 @@ function createAuthHandlers(handlersConfig = {}) {
 		async signin(request) {
 			const config = resolveNextConfig(handlersConfig);
 			const secure = resolveCookieSecure(request, config);
-			const redirectUri = `${new URL(request.url).origin}${callbackPath}`;
+			const redirectUri = `${resolvePublicOrigin(request, config)}${callbackPath}`;
 			const { verifier, challenge } = await generatePkce();
 			const state = randomState();
 			(await cookies()).set(VERIFIER_COOKIE, JSON.stringify({
@@ -192,7 +956,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 redirectUri = `${resolvePublicOrigin(request, config)}${callbackPath}`;
 			const client = buildServerAuthClient(config);
 			let payload;
 			try {
@@ -244,7 +1008,7 @@ function createAuthHandlers(handlersConfig = {}) {
 						return Response.json({
 							status: "success",
 							redirectTo: afterSignInPath
-						});
+						}, { headers: { "set-cookie": buildAuthEventCookie("signed-in", secure) } });
 					}
 					case "select_tenant": return Response.json({
 						status: "select_tenant",
@@ -256,6 +1020,18 @@ function createAuthHandlers(handlersConfig = {}) {
 						userId: outcome.userId
 					}, { status: 403 });
 					case "no_access": return Response.json({ status: "no_access" }, { status: 403 });
+					case "verification_required": return Response.json({
+						status: "verification_required",
+						challengeId: outcome.challengeId,
+						factorTypes: outcome.factorTypes
+					}, { status: 401 });
+					case "configuration_error":
+						console.error(`[polyx] Sign-in rejected for configuration, not credentials: ${outcome.code}${outcome.message ? ` — ${outcome.message}` : ""}. redirect_uri used: ${redirectUri}. If the app is behind a proxy, set POLYX_PUBLIC_ORIGIN or enable POLYX_TRUST_FORWARDED_ORIGIN.`);
+						return Response.json({
+							status: "configuration_error",
+							code: outcome.code,
+							message: outcome.message
+						}, { status: 500 });
 					default: return Response.json({ status: "invalid_credentials" }, { status: 401 });
 				}
 			}
@@ -352,11 +1128,116 @@ function createAuthHandlers(handlersConfig = {}) {
 			}
 			return Response.redirect(home, 302);
 		},
-		async refresh(request) {
+		async hop(request) {
+			const config = resolveNextConfig(handlersConfig);
+			const secure = resolveCookieSecure(request, config);
+			const redirectUri = `${resolvePublicOrigin(request, config)}${callbackPath}`;
+			let hint = {};
+			try {
+				hint = await request.json() ?? {};
+			} catch {
+				hint = {};
+			}
+			const organizationCode = typeof hint.tenantId === "string" && hint.tenantId !== "" ? hint.tenantId : typeof hint.organizationCode === "string" && hint.organizationCode !== "" ? hint.organizationCode : void 0;
+			const { verifier, challenge } = await generatePkce();
+			const state = randomState();
+			(await cookies()).set(VERIFIER_COOKIE, JSON.stringify({
+				verifier,
+				state,
+				redirectUri,
+				...organizationCode ? { requested: organizationCode } : {}
+			}), {
+				httpOnly: true,
+				secure,
+				sameSite: "lax",
+				path: "/",
+				maxAge: VERIFIER_MAX_AGE
+			});
+			const authorizeUrl = buildServerAuthClient(config).buildAuthorizeUrl({
+				redirectUri,
+				state,
+				challenge,
+				prompt: "none",
+				...organizationCode ? { organizationCode } : {}
+			});
+			return Response.json({
+				status: "ready",
+				authorizeUrl
+			});
+		},
+		async hopComplete(request) {
 			const config = resolveNextConfig(handlersConfig);
 			const secure = resolveCookieSecure(request, config);
-			const session = await newSession(await requestCookies(), config, secure).refresh();
-			return Response.json({ isSignedIn: session !== null }, { status: session ? 200 : 401 });
+			const store = await cookies();
+			let body;
+			try {
+				body = await request.json() ?? {};
+			} catch {
+				return Response.json({ status: "invalid_request" }, { status: 400 });
+			}
+			const code = typeof body.code === "string" ? body.code : "";
+			const state = typeof body.state === "string" ? body.state : "";
+			const raw = store.get(VERIFIER_COOKIE)?.value;
+			store.delete(VERIFIER_COOKIE);
+			if (!code || !state || !raw) return Response.json({ status: "invalid_request" }, { status: 400 });
+			let tx;
+			try {
+				tx = JSON.parse(raw);
+			} catch {
+				return Response.json({ status: "invalid_request" }, { status: 400 });
+			}
+			if (tx.state !== state) return Response.json({ status: "invalid_request" }, { status: 400 });
+			let entered;
+			try {
+				entered = (await newSession(adapt(store), config, secure).establishFromCode(code, tx.verifier, tx.redirectUri, collectForwardedDeviceHeaders(request))).session.claims.organizationId;
+			} 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: 400 });
+				}
+				return Response.json({ status: "exchange_failed" }, { status: 400 });
+			}
+			/**
+			* The substitution guard (verified against a live platform, 2026-07-29).
+			*
+			* The platform only consults a workspace hint when the person has **more than one**
+			* candidate workspace for that application. With exactly one, the hint is ignored and they
+			* are placed in that one — answering `authorized`, with nothing to say the request was not
+			* honoured. Asking for workspace A and being silently seated in workspace B is precisely
+			* the outcome the scope decisions call worse than a prompt: someone can act in the wrong
+			* tenant without noticing.
+			*
+			* A hint can be a tenant id, an organization code, or a slug, and only the first is
+			* comparable to what the session carries. So an id-shaped hint that does not match is
+			* reported as a mismatch; for the other forms the workspace actually entered is returned
+			* and the caller can decide. Either way the answer is never a bare "success" that hides a
+			* substitution.
+			*
+			* The session IS established at this point and is left in place: the person is signed in
+			* somewhere they are entitled to be. This reports what happened rather than tearing down a
+			* valid session the caller may be perfectly happy with.
+			*/
+			const requested = tx.requested;
+			if (typeof requested === "string" && /^[a-f0-9]{24}$/i.test(requested) && entered && requested.toLowerCase() !== entered.toLowerCase()) return Response.json({
+				status: "workspace_mismatch",
+				requested,
+				workspace: entered
+			});
+			return Response.json({
+				status: "success",
+				...entered ? { workspace: entered } : {}
+			});
+		},
+		async refresh(request) {
+			const { isSignedIn } = await refreshSession({
+				...handlersConfig,
+				request
+			});
+			return Response.json({ isSignedIn }, { status: isSignedIn ? 200 : 401 });
 		},
 		/**
 		* End the session: revoke it upstream (bearer-authenticated, using the sealed token)
@@ -373,12 +1254,185 @@ function createAuthHandlers(handlersConfig = {}) {
 			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);
+			const event = buildAuthEventCookie("signed-out", secure);
+			if (request.headers.get("accept")?.includes("application/json")) return Response.json({ signedOut: true }, { headers: { "set-cookie": event } });
+			return new Response(null, {
+				status: 302,
+				headers: {
+					location: resolvePublicOrigin(request, config) + "/",
+					"set-cookie": event
+				}
+			});
 		},
 		async session() {
 			return Response.json(await auth(handlersConfig));
 		},
+		/**
+		* Exchange the sealed session for a realtime handshake ticket (F019 / FR-RT-2).
+		*
+		* The session credential stays on this side: the SDK calls the platform with it and
+		* hands the browser only the ticket, which is single-use and expires in seconds.
+		*/
+		async realtimeTicket(request) {
+			const config = resolveNextConfig(handlersConfig);
+			if (!config.realtimeBaseUrl) return Response.json({
+				status: "unavailable",
+				message: "Set POLYX_REALTIME_URL to issue realtime tickets."
+			}, { status: 503 });
+			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 });
+			const endpoint = `${config.realtimeBaseUrl.replace(/\/$/, "")}/v1/socket-ticket`;
+			const send = (token) => fetch(endpoint, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${token}`,
+					Accept: "application/json"
+				}
+			});
+			let organizationId = current.session.claims.organizationId;
+			try {
+				let upstream = await send(current.tokens.accessToken);
+				if (upstream.status === 401) {
+					const refreshed = await refreshSession({
+						...handlersConfig,
+						request
+					}).catch(() => null);
+					if (!refreshed?.isSignedIn || !refreshed.accessToken) return Response.json({ status: "signed_out" }, { status: 401 });
+					organizationId = refreshed.claims?.organizationId ?? organizationId;
+					upstream = await send(refreshed.accessToken);
+				}
+				if (!upstream.ok) return Response.json({ status: "unavailable" }, { status: 503 });
+				const body = await upstream.json();
+				if (!body.ticket) return Response.json({ status: "unavailable" }, { status: 503 });
+				return Response.json({
+					ticket: body.ticket,
+					expiresInSeconds: body.expiresInSeconds,
+					organizationId
+				});
+			} catch {
+				return Response.json({ status: "unavailable" }, { status: 503 });
+			}
+		},
+		async profile(request) {
+			const config = resolveNextConfig(handlersConfig);
+			const session = new ServerSession({
+				authClient: buildServerAuthClient(config),
+				secret: config.secret,
+				cookies: await requestCookies()
+			});
+			const current = await session.read();
+			if (!current) return Response.json({ status: "signed_out" }, { status: 401 });
+			const { userId, organizationId } = current.session.claims;
+			if (!organizationId) return Response.json({ status: "no_organization" }, { status: 409 });
+			if (!config.baseUrl) return Response.json({ status: "configuration_error" }, { status: 503 });
+			const target = `${config.baseUrl.replace(/\/$/, "")}/v1/user/${encodeURIComponent(userId)}`;
+			const headers = {
+				"organization-id": organizationId,
+				Accept: "application/json"
+			};
+			let body;
+			if (request.method !== "GET") {
+				/**
+				* The body is REBUILT from an allow-list rather than forwarded.
+				*
+				* `updateUser` upstream applies whatever recognised fields it is given — including
+				* `email`, `password` and `role`. Relaying the browser's multipart verbatim would
+				* therefore turn a profile form into a way to change a credential or grant a role,
+				* skipping the verification each of those has (D25). The allow-list is the control:
+				* anything not in it never leaves this process.
+				*/
+				/**
+				* Parsed inside its own guard. `formData()` throws on a body that is not multipart or
+				* form-encoded — the likeliest cause being an integrator posting JSON, which is the
+				* obvious guess — and this sits before the try block that covers the upstream call, so
+				* the rejection escaped the handler and Next answered 500. A 500 says the SDK broke;
+				* an unreadable request is the caller's, and it belongs in nobody's alerting.
+				*/
+				let submitted;
+				try {
+					submitted = await request.formData();
+				} catch {
+					return Response.json({ status: "invalid_request" }, { status: 400 });
+				}
+				body = new FormData();
+				for (const field of PROFILE_FIELDS) {
+					const value = submitted.get(field);
+					if (typeof value === "string" && value.trim() !== "") body.append(field, value.trim());
+				}
+				const image = submitted.get("image");
+				if (image && typeof image !== "string") body.append("image", image);
+			}
+			const send = (token) => fetch(target, {
+				method: request.method === "GET" ? "GET" : "PUT",
+				headers: {
+					...headers,
+					Authorization: `Bearer ${token}`
+				},
+				body
+			});
+			let activeToken = current.tokens.accessToken;
+			try {
+				let upstream = await send(activeToken);
+				if (upstream.status === 401) {
+					const refreshed = await refreshSession({
+						...handlersConfig,
+						request
+					}).catch(() => null);
+					if (!refreshed?.isSignedIn || !refreshed.accessToken) return Response.json({ status: "signed_out" }, { status: 401 });
+					activeToken = refreshed.accessToken;
+					upstream = await send(activeToken);
+				}
+				const payload = await upstream.json().catch(() => ({}));
+				if (!upstream.ok) return Response.json({
+					status: "error",
+					message: typeof payload.message === "string" ? payload.message : void 0
+				}, { status: upstream.status });
+				let user = payload.user ?? payload.data ?? payload;
+				if (request.method !== "GET") {
+					/**
+					* Re-read after a save, because the update answers with the id ALONE.
+					*
+					* poly-auth returns `{message, data: {_id}}` from the update — deliberately, so a
+					* password hash never rides on the response. So the saved document is simply not in
+					* hand here: without this read the caller gets `{}` back and the display-claim update
+					* below is a no-op against every field, leaving the account menu showing the name the
+					* person just corrected (the exact thing FR-PROF-5 exists to prevent).
+					*
+					* The platform contract is frozen for the SDK, so the extra round trip is the answer
+					* rather than asking poly-auth to return more.
+					*/
+					const reread = await fetch(target, {
+						method: "GET",
+						headers: {
+							...headers,
+							Authorization: `Bearer ${activeToken}`
+						}
+					}).catch(() => null);
+					if (reread?.ok) {
+						const body = await reread.json().catch(() => ({}));
+						const fresh = body.user ?? body.data ?? body;
+						if (fresh && typeof fresh === "object") user = fresh;
+					}
+					await session.updateDisplayClaims(deriveDisplayClaims(user));
+				}
+				return Response.json({
+					status: "ok",
+					user: pickProfileFields(user)
+				});
+			} catch {
+				return Response.json({ status: "unavailable" }, { status: 503 });
+			}
+		},
+		/**
+		* @deprecated Superseded by `realtimeTicket` (FR-RT-4). This hands the browser the
+		* SESSION ACCESS TOKEN — the one place the custody guarantee is knowingly broken.
+		* Kept working for this release so consumers migrate on their own schedule
+		* (FR-COMPAT-3); it will be removed in a later major.
+		*/
 		async subscriptionCredential() {
 			const config = resolveNextConfig(handlersConfig);
 			const current = await new ServerSession({
@@ -395,4 +1449,4 @@ function createAuthHandlers(handlersConfig = {}) {
 	};
 }
 //#endregion
-export { DEFAULT_SESSION_COOKIE, SESSION_COOKIE_MAX_BYTES, ServerSession, SessionCookieTooLargeError, auth, createAuthHandlers, openSession, resolveNextConfig, sealSession, sealedCookieByteLength };
+export { AUTH_EVENT_COOKIE, DEFAULT_SESSION_COOKIE, POLYX_ACTIONS, SESSION_COOKIE_MAX_BYTES, ServerSession, SessionCookieTooLargeError, auth, buildAuthEventCookie, createAuthHandlers, createDataProxy, createPolyXHandler, getSessionContext, openSession, readSessionCookie, refreshSession, resolveNextConfig, resolvePublicOrigin, sealSession, sealedCookieByteLength };