@poly-x/core 0.2.0 → 0.3.0

package/README.md

@@ -16,10 +16,36 @@ don't import this directly; reach for the framework package instead.
 - **Transport** — a `Transport` seam with a fetch implementation (timeout +
   bounded transient retries) and a `MockTransport` for tests.
 - **Session engine** — the auth state machine (`resolving → authenticated ⇄
-  refreshing → signed-out`), single-flight refresh with reuse→revoke, cross-tab
-  sign-out, and server-authoritative proactive refresh, over swappable seams.
+  refreshing → signed-out`), single-flight refresh, cross-tab sign-out, and
+  server-authoritative proactive refresh, over swappable seams.
 - **Auth protocol client** — PKCE, authorize-URL building, the membership-outcome
-  parse, code exchange, refresh, logout.
+  parse, code exchange, refresh, logout, and the silent warm-hop probe.
+
+### `completeAuthorize` refuses to run on a server
+
+The warm hop asks the platform to recognise a browser it has seen before, and the platform
+resolves that from a cookie on **its own** domain. A server-side request carries no browser
+cookie, so it would be told "sign-in required" every single time — correctly, and
+indistinguishably from someone who genuinely is signed out. Built that way, the feature looks
+finished and never works.
+
+So calling it from a server context throws `WARM_HOP_ON_SERVER` rather than returning that
+plausible answer, and does not send the request at all. `@poly-x/next`'s `hop` routes prepare the
+attempt for the browser to make; use those.
+
+### What refresh does and does not protect against
+
+Refresh is **single-flight** — concurrent callers coalesce onto one in-flight request, so a burst
+of expired calls produces one refresh rather than a stampede.
+
+It is **not** refresh-token rotation, and the SDK does not claim reuse detection. Verified against
+a running platform (2026-07-29): PolyX returns the *same* refresh token on refresh, so a refresh
+token is a long-lived credential that can be replayed for its lifetime, and its capture is not
+detectable. Session expiry and revocation still apply.
+
+**This is why custody matters more than it looks.** Under `@poly-x/next`'s BFF the refresh token
+never reaches the browser at all. If you hold refresh tokens client-side in your own integration,
+you are carrying that risk yourself.
 
 ```ts
 import { createSessionEngine, AuthClient, resolveConfig } from "@poly-x/core";

package/dist/index.cjs

@@ -989,8 +989,26 @@ var AuthClient = class {
 		if (!this.config.signInUrl) return this.buildAuthorizeUrl(params);
 		return this.appendAuthorizeParams(new URL(this.config.signInUrl), params);
 	}
-	/** Probe the warm hop (GET /idp/authorize) and return the typed outcome. */
+	/**
+	* Probe the warm hop (GET /idp/authorize) and return the typed outcome.
+	*
+	* **Browser only, and it refuses to run anywhere else** (FR-HOP-5/6).
+	*
+	* The platform resolves this from the *browser's* ecosystem cookie, set on the platform's
+	* own domain. A request issued from a server carries no browser cookie, so the platform
+	* would answer `login_required` — correctly, and every single time. The caller would see a
+	* perfectly ordinary "this person must sign in", identical to the answer for someone who
+	* genuinely is signed out. The whole feature would look implemented and never once work,
+	* with nothing red anywhere to say so.
+	*
+	* That is why this throws instead of returning the plausible answer: a loud failure at the
+	* one wrong call site is worth far more than a silent no-op nobody notices for a release.
+	* A cross-origin `fetch(credentials:"include")` from the browser is the supported path
+	* (`@poly-x/next`'s hop routes prepare it); it works because the ecosystem cookie is
+	* attached by the browser to the platform host.
+	*/
 	async completeAuthorize(params) {
+		if (this.config.context === "server") throw new PolyXConfigError("The warm hop cannot be attempted from a server. The platform reads the ecosystem session from the browser's cookie, which a server-side request does not carry — so this call would report 'sign-in required' every time, whether or not the person is signed in. Start the hop from the browser instead (see createAuthHandlers().hop).", { code: "WARM_HOP_ON_SERVER" });
 		const response = await this.transport.request({
 			method: "GET",
 			url: this.buildAuthorizeUrl(params)
@@ -1288,7 +1306,7 @@ function conflictField(message) {
 */
 const PACKAGE_NAME = "@poly-x/core";
 /** The published version of this package, injected at build time. */
-const version = "0.2.0";
+const version = "0.3.0";
 //#endregion
 exports.AuthClient = AuthClient;
 exports.DEFAULT_RETRY_POLICY = DEFAULT_RETRY_POLICY;

package/dist/index.d.cts

@@ -658,7 +658,24 @@ declare class AuthClient {
    * `signInUrl` is configured (deployments where the API host serves the page).
    */
   buildSignInUrl(params: BuildAuthorizeUrlParams): string;
-  /** Probe the warm hop (GET /idp/authorize) and return the typed outcome. */
+  /**
+   * Probe the warm hop (GET /idp/authorize) and return the typed outcome.
+   *
+   * **Browser only, and it refuses to run anywhere else** (FR-HOP-5/6).
+   *
+   * The platform resolves this from the *browser's* ecosystem cookie, set on the platform's
+   * own domain. A request issued from a server carries no browser cookie, so the platform
+   * would answer `login_required` — correctly, and every single time. The caller would see a
+   * perfectly ordinary "this person must sign in", identical to the answer for someone who
+   * genuinely is signed out. The whole feature would look implemented and never once work,
+   * with nothing red anywhere to say so.
+   *
+   * That is why this throws instead of returning the plausible answer: a loud failure at the
+   * one wrong call site is worth far more than a silent no-op nobody notices for a release.
+   * A cross-origin `fetch(credentials:"include")` from the browser is the supported path
+   * (`@poly-x/next`'s hop routes prepare it); it works because the ecosystem cookie is
+   * attached by the browser to the platform host.
+   */
   completeAuthorize(params: BuildAuthorizeUrlParams): Promise<AuthorizeOutcome>;
   /**
    * The embedded `<SignIn/>` credential flow (D2b): POST `/idp/authorize` with

package/dist/index.d.mts

@@ -658,7 +658,24 @@ declare class AuthClient {
    * `signInUrl` is configured (deployments where the API host serves the page).
    */
   buildSignInUrl(params: BuildAuthorizeUrlParams): string;
-  /** Probe the warm hop (GET /idp/authorize) and return the typed outcome. */
+  /**
+   * Probe the warm hop (GET /idp/authorize) and return the typed outcome.
+   *
+   * **Browser only, and it refuses to run anywhere else** (FR-HOP-5/6).
+   *
+   * The platform resolves this from the *browser's* ecosystem cookie, set on the platform's
+   * own domain. A request issued from a server carries no browser cookie, so the platform
+   * would answer `login_required` — correctly, and every single time. The caller would see a
+   * perfectly ordinary "this person must sign in", identical to the answer for someone who
+   * genuinely is signed out. The whole feature would look implemented and never once work,
+   * with nothing red anywhere to say so.
+   *
+   * That is why this throws instead of returning the plausible answer: a loud failure at the
+   * one wrong call site is worth far more than a silent no-op nobody notices for a release.
+   * A cross-origin `fetch(credentials:"include")` from the browser is the supported path
+   * (`@poly-x/next`'s hop routes prepare it); it works because the ecosystem cookie is
+   * attached by the browser to the platform host.
+   */
   completeAuthorize(params: BuildAuthorizeUrlParams): Promise<AuthorizeOutcome>;
   /**
    * The embedded `<SignIn/>` credential flow (D2b): POST `/idp/authorize` with

package/dist/index.mjs

@@ -988,8 +988,26 @@ var AuthClient = class {
 		if (!this.config.signInUrl) return this.buildAuthorizeUrl(params);
 		return this.appendAuthorizeParams(new URL(this.config.signInUrl), params);
 	}
-	/** Probe the warm hop (GET /idp/authorize) and return the typed outcome. */
+	/**
+	* Probe the warm hop (GET /idp/authorize) and return the typed outcome.
+	*
+	* **Browser only, and it refuses to run anywhere else** (FR-HOP-5/6).
+	*
+	* The platform resolves this from the *browser's* ecosystem cookie, set on the platform's
+	* own domain. A request issued from a server carries no browser cookie, so the platform
+	* would answer `login_required` — correctly, and every single time. The caller would see a
+	* perfectly ordinary "this person must sign in", identical to the answer for someone who
+	* genuinely is signed out. The whole feature would look implemented and never once work,
+	* with nothing red anywhere to say so.
+	*
+	* That is why this throws instead of returning the plausible answer: a loud failure at the
+	* one wrong call site is worth far more than a silent no-op nobody notices for a release.
+	* A cross-origin `fetch(credentials:"include")` from the browser is the supported path
+	* (`@poly-x/next`'s hop routes prepare it); it works because the ecosystem cookie is
+	* attached by the browser to the platform host.
+	*/
 	async completeAuthorize(params) {
+		if (this.config.context === "server") throw new PolyXConfigError("The warm hop cannot be attempted from a server. The platform reads the ecosystem session from the browser's cookie, which a server-side request does not carry — so this call would report 'sign-in required' every time, whether or not the person is signed in. Start the hop from the browser instead (see createAuthHandlers().hop).", { code: "WARM_HOP_ON_SERVER" });
 		const response = await this.transport.request({
 			method: "GET",
 			url: this.buildAuthorizeUrl(params)
@@ -1287,6 +1305,6 @@ function conflictField(message) {
 */
 const PACKAGE_NAME = "@poly-x/core";
 /** The published version of this package, injected at build time. */
-const version = "0.2.0";
+const version = "0.3.0";
 //#endregion
 export { AuthClient, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, ENDPOINTS, FetchTransport, ForbiddenError, INITIAL_STATE as INITIAL_SESSION_STATE, InMemoryLock, InMemoryPkceStore, InMemorySessionChannel, InMemorySessionStore, MAX_PROFILE_IMAGE_BYTES, MockTransport, PACKAGE_NAME, PROFILE_FIELDS, PolyXConfigError, PolyXError, RateLimitedError, SessionEngine, SessionExpiredError, SessionRevokedError, SystemClock, UnauthenticatedError, UpstreamError, ValidationError, buildProfileUpdate, computeChallenge, conflictField, createSessionEngine, decodeJwtExp, deriveDisplayClaims, generatePkce, isTransientStatus, mapPlatformError, normalizeExchange, normalizeRefresh, parseAuthorizeOutcome, parsePasswordOutcome, parsePolyXKey, parseResetOutcome, randomState, redactSensitive, reduce as reduceSessionState, resolveConfig, validateProfileDraft, validateProfileImage, version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poly-x/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Framework-agnostic core of the PolyX SDK",
   "license": "MIT",
   "type": "module",