@poly-x/next 0.2.0 → 0.3.0

package/README.md

@@ -150,6 +150,45 @@ platform's update applies whatever recognised fields it receives — including
 turn a profile form into a way to change a credential or grant a role. Only the
 six profile fields ever leave the server.
 
+## Cross-application sign-on and switching workspace
+
+`createPolyXHandler()` also mounts `/api/polyx/hop` and `/api/polyx/hop-complete`. You do not
+call these directly — `@poly-x/react`'s `useWarmHop()` and `switchWorkspace()` drive them.
+
+**The attempt is made by the browser, and it has to be.** The platform recognises a returning
+person from an ecosystem cookie set on *its own* domain. Your server does not have that cookie,
+so a server-side attempt is told "sign-in required" every single time — correctly, and
+indistinguishably from someone who genuinely is signed out. The feature would look implemented
+and never once work.
+
+So the routes bracket a browser-made request rather than making one:
+
+- **`hop`** mints the PKCE pair, keeps the verifier in an httpOnly cookie, and returns only a
+  URL. It makes no request of its own.
+- **`hop-complete`** takes the `code` the browser received and exchanges it here. The code is
+  safe for a page to hold precisely because the verifier that redeems it never left your server.
+
+Because of that, calling `completeAuthorize()` from server code **throws**
+(`WARM_HOP_ON_SERVER`) rather than returning the plausible answer.
+
+Register your `/api/polyx/callback` on the App even though nothing redirects to it during a
+hop — the platform validates `redirect_uri` on both the authorize and the exchange.
+
+> **Warm hop needs https end to end** (or a `localhost` dev setup). The platform issues its
+> ecosystem cookie with `Secure`, and a browser silently discards a `Secure` cookie delivered
+> over http. Nothing reports this: sign-in still succeeds, the `Set-Cookie` header is still
+> there, and every hop afterwards reports "sign-in required" — indistinguishable from someone
+> who is genuinely signed out. `localhost` is the one host browsers exempt.
+
+### The boundary, stated plainly
+
+**This works between applications that share the ecosystem cookie's domain.** Browsers block
+third-party cookies by default, so an application on an unrelated domain cannot see that cookie
+and will fall back to ordinary sign-in. That is a browser policy, not a limitation we can
+configure away — solving it needs a different mechanism entirely. Nothing here claims otherwise.
+
+Switching workspace is unaffected by that boundary: it happens inside one application.
+
 ## Exports
 
 - `@poly-x/next` — the client surface (re-exports `@poly-x/react`): `PolyXProvider`,

package/dist/index.cjs

@@ -3,7 +3,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/index.ts
 const PACKAGE_NAME = "@poly-x/next";
 /** The published version of this package, injected at build time. */
-const version = "0.2.0";
+const version = "0.3.0";
 //#endregion
 exports.PACKAGE_NAME = PACKAGE_NAME;
 exports.version = version;

package/dist/index.mjs

@@ -3,6 +3,6 @@ export * from "@poly-x/react";
 //#region src/index.ts
 const PACKAGE_NAME = "@poly-x/next";
 /** The published version of this package, injected at build time. */
-const version = "0.2.0";
+const version = "0.3.0";
 //#endregion
 export { PACKAGE_NAME, version };

package/dist/server.cjs

@@ -512,6 +512,8 @@ const POLYX_ACTIONS = {
 	"forgot-password": "forgotPassword",
 	"reset-password": "resetPassword",
 	callback: "callback",
+	hop: "hop",
+	"hop-complete": "hopComplete",
 	refresh: "refresh",
 	signout: "signout",
 	session: "session",
@@ -534,6 +536,8 @@ const POLYX_ACTION_METHODS = {
 	"subscription-credential": ["GET"],
 	"realtime-ticket": ["GET"],
 	authenticate: ["POST"],
+	hop: ["POST"],
+	"hop-complete": ["POST"],
 	"forgot-password": ["POST"],
 	"reset-password": ["POST"],
 	refresh: ["POST"],
@@ -1125,6 +1129,110 @@ function createAuthHandlers(handlersConfig = {}) {
 			}
 			return Response.redirect(home, 302);
 		},
+		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 (0, _poly_x_core.generatePkce)();
+			const state = (0, _poly_x_core.randomState)();
+			(await (0, next_headers.cookies)()).set(VERIFIER_COOKIE, JSON.stringify({
+				verifier,
+				state,
+				redirectUri,
+				...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 store = await (0, next_headers.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,

package/dist/server.d.cts

@@ -221,6 +221,8 @@ declare const POLYX_ACTIONS: {
   readonly "forgot-password": "forgotPassword";
   readonly "reset-password": "resetPassword";
   readonly callback: "callback";
+  readonly hop: "hop";
+  readonly "hop-complete": "hopComplete";
   readonly refresh: "refresh";
   readonly signout: "signout";
   readonly session: "session";
@@ -383,6 +385,28 @@ interface AuthHandlers {
    */
   resetPassword(request: Request): Promise<Response>;
   callback(request: Request): Promise<Response>;
+  /**
+   * Prepare a warm hop — the silent sign-in attempt (F026 / FR-HOP-1).
+   *
+   * Returns the authorize URL for **the browser** to call, and keeps the PKCE verifier in an
+   * httpOnly cookie. It deliberately makes no request of its own: the platform resolves this
+   * from the browser's ecosystem cookie, which a server-side call does not carry, so a
+   * server-side attempt would report "sign-in required" every time and the feature would look
+   * built while never working (FR-HOP-5).
+   *
+   * An optional `{ tenantId }` / `{ organizationCode }` body pins a workspace. The platform
+   * matches it **only within the person's own memberships**, so it can narrow a choice but
+   * never widen access — which is what also makes this the route the workspace switch uses.
+   */
+  hop(request: Request): Promise<Response>;
+  /**
+   * Finish a warm hop: exchange the `code` the browser received for a session (F026 / FR-HOP-3).
+   *
+   * The code is safe for a browser to hold because it is worthless without the PKCE verifier,
+   * and the verifier never left this server. The exchange happens here, so tokens never touch
+   * the page — the same custody path as every other sign-in, not a second mechanism.
+   */
+  hopComplete(request: Request): Promise<Response>;
   refresh(request: Request): Promise<Response>;
   signout(request: Request): Promise<Response>;
   /**

package/dist/server.d.mts

@@ -221,6 +221,8 @@ declare const POLYX_ACTIONS: {
   readonly "forgot-password": "forgotPassword";
   readonly "reset-password": "resetPassword";
   readonly callback: "callback";
+  readonly hop: "hop";
+  readonly "hop-complete": "hopComplete";
   readonly refresh: "refresh";
   readonly signout: "signout";
   readonly session: "session";
@@ -383,6 +385,28 @@ interface AuthHandlers {
    */
   resetPassword(request: Request): Promise<Response>;
   callback(request: Request): Promise<Response>;
+  /**
+   * Prepare a warm hop — the silent sign-in attempt (F026 / FR-HOP-1).
+   *
+   * Returns the authorize URL for **the browser** to call, and keeps the PKCE verifier in an
+   * httpOnly cookie. It deliberately makes no request of its own: the platform resolves this
+   * from the browser's ecosystem cookie, which a server-side call does not carry, so a
+   * server-side attempt would report "sign-in required" every time and the feature would look
+   * built while never working (FR-HOP-5).
+   *
+   * An optional `{ tenantId }` / `{ organizationCode }` body pins a workspace. The platform
+   * matches it **only within the person's own memberships**, so it can narrow a choice but
+   * never widen access — which is what also makes this the route the workspace switch uses.
+   */
+  hop(request: Request): Promise<Response>;
+  /**
+   * Finish a warm hop: exchange the `code` the browser received for a session (F026 / FR-HOP-3).
+   *
+   * The code is safe for a browser to hold because it is worthless without the PKCE verifier,
+   * and the verifier never left this server. The exchange happens here, so tokens never touch
+   * the page — the same custody path as every other sign-in, not a second mechanism.
+   */
+  hopComplete(request: Request): Promise<Response>;
   refresh(request: Request): Promise<Response>;
   signout(request: Request): Promise<Response>;
   /**

package/dist/server.mjs

@@ -511,6 +511,8 @@ const POLYX_ACTIONS = {
 	"forgot-password": "forgotPassword",
 	"reset-password": "resetPassword",
 	callback: "callback",
+	hop: "hop",
+	"hop-complete": "hopComplete",
 	refresh: "refresh",
 	signout: "signout",
 	session: "session",
@@ -533,6 +535,8 @@ const POLYX_ACTION_METHODS = {
 	"subscription-credential": ["GET"],
 	"realtime-ticket": ["GET"],
 	authenticate: ["POST"],
+	hop: ["POST"],
+	"hop-complete": ["POST"],
 	"forgot-password": ["POST"],
 	"reset-password": ["POST"],
 	refresh: ["POST"],
@@ -1124,6 +1128,110 @@ function createAuthHandlers(handlersConfig = {}) {
 			}
 			return Response.redirect(home, 302);
 		},
+		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 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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poly-x/next",
-  "version": "0.2.0",
+  "version": "0.3.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.2.0",
-    "@poly-x/react": "0.2.0"
+    "@poly-x/core": "0.3.0",
+    "@poly-x/react": "0.3.0"
   },
   "peerDependencies": {
     "next": ">=14",