@poly-x/core 0.1.1 → 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

@@ -630,7 +630,7 @@ var SessionEngine = class {
 			this.applySignOut("expired", true);
 			return;
 		}
-		if (error instanceof UpstreamError || error instanceof Error) this.dispatch({ type: "refresh-failed-transient" });
+		this.dispatch({ type: "refresh-failed-transient" });
 	}
 	async applySignOut(reason, broadcast) {
 		if (this.state.status === "signed-out") return;
@@ -789,6 +789,18 @@ function parseAuthorizeOutcome(status, body) {
 	if (statusField === "login_required" || b.code === "LOGIN_REQUIRED") return { type: "login_required" };
 	return { type: "login_required" };
 }
+/**
+* Platform codes that mean "this app is misconfigured", verified against poly-auth
+* `api/constants/auth-responses.ts` and `idp.controller.ts:validateClientAndRedirect`
+* (2026-07-29). Only these map across — an unrecognised 400 keeps the previous
+* behaviour rather than being mislabelled as misconfiguration.
+*/
+const CONFIGURATION_ERROR_CODES = /* @__PURE__ */ new Set([
+	"REDIRECT_URI_NOT_ALLOWED",
+	"INVALID_CLIENT",
+	"KEY_DEPLOYMENT_MISMATCH",
+	"KEY_ENVIRONMENT_MISMATCH"
+]);
 function parsePasswordOutcome(status, body) {
 	const b = asRecord$1(body);
 	const statusField = typeof b.status === "string" ? b.status : void 0;
@@ -809,6 +821,16 @@ function parsePasswordOutcome(status, body) {
 		ticket: typeof b.ticket === "string" ? b.ticket : void 0
 	};
 	if (status === 403) return { type: "no_access" };
+	if (statusField === "verification_required" && typeof b.challengeId === "string") return {
+		type: "verification_required",
+		challengeId: b.challengeId,
+		factorTypes: Array.isArray(b.factorTypes) ? b.factorTypes.filter((f) => typeof f === "string") : []
+	};
+	if (status === 400 && typeof b.code === "string" && CONFIGURATION_ERROR_CODES.has(b.code)) return {
+		type: "configuration_error",
+		code: b.code,
+		message: typeof b.message === "string" ? b.message : void 0
+	};
 	return { type: "invalid_credentials" };
 }
 function parseResetOutcome(status, body) {
@@ -863,6 +885,23 @@ function deriveDisplayName(user) {
 	return displayString([displayString(user.firstName, MAX_DISPLAY_NAME), displayString(user.lastName, MAX_DISPLAY_NAME)].filter(Boolean).join(" "), MAX_DISPLAY_NAME) ?? displayString(user.username, MAX_DISPLAY_NAME) ?? displayString(user.email, MAX_DISPLAY_NAME);
 }
 /**
+* The bounded display subset of a user record: name, email, avatar (ADR-0006).
+*
+* Exported because a profile update has to re-derive exactly these — and only these — after the
+* platform saves. `normalizeRefresh` carries claims forward unchanged, so without a deliberate
+* re-derivation the display name and avatar are whatever they were at login, forever.
+*
+* Identity and authorization claims are deliberately absent: this returns what is safe to
+* recompute from a profile response, not a whole claim set.
+*/
+function deriveDisplayClaims(user) {
+	return {
+		displayName: deriveDisplayName(user),
+		email: displayString(user.email, MAX_DISPLAY_NAME),
+		avatarUrl: displayString(user.profilePicture, MAX_AVATAR_URL)
+	};
+}
+/**
 * `POST /idp/token` → StoredSession. Claims carry identity plus the bounded display subset
 * (ADR-0006); AUTHZ populates roles/permissions later.
 *
@@ -950,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)
@@ -1139,12 +1196,117 @@ var AuthClient = class {
 	}
 };
 //#endregion
+//#region src/profile/validation.ts
+/**
+* Profile input rules (FR-VALID-1…8).
+*
+* These are **mirrored from the platform's own validation** (`poly-auth`
+* `src/api/validations/common-fields.ts`), not invented here. That is the whole point: a value
+* this module accepts must not be one the platform rejects, or a person is shown an error they
+* cannot act on — and the error arrives after a round trip, attached to nothing in particular.
+*
+* The mirroring is the fragile part. It is pinned by tests that restate the platform's patterns
+* as literals and assert both agree, so a drift fails a build rather than a person's save.
+*/
+/**
+* One or more Unicode letters, optionally joined by a single space, hyphen or apostrophe —
+* "José", "O'Brien", "Anne-Marie", "van der Berg". No digits, no leading/trailing/double
+* separators. (poly-auth `PERSON_NAME_REGEX`.)
+*/
+const PERSON_NAME_REGEX = /^\p{L}+(?:[ '-]\p{L}+)*$/u;
+/** Leading "+", country code starting 1-9, then 7-14 more digits. (poly-auth `E164_PHONE_REGEX`.) */
+const E164_PHONE_REGEX = /^\+[1-9]\d{7,14}$/;
+/** poly-auth's person-name bounds for these two fields (`min: 1, max: 20`). */
+const NAME_MAX = 20;
+/** poly-auth's `imageUpload.middleware` cap. */
+const MAX_PROFILE_IMAGE_BYTES = 50 * 1024 * 1024;
+/** The text fields this release makes editable (FR-PROF-4 / D25). */
+const PROFILE_FIELDS = [
+	"firstName",
+	"lastName",
+	"phoneNumber",
+	"cnic",
+	"gender"
+];
+function name(value, label) {
+	const trimmed = (value ?? "").trim();
+	if (trimmed === "") return `${label} is required`;
+	if (trimmed.length > NAME_MAX) return `${label} cannot exceed ${NAME_MAX} characters`;
+	if (!PERSON_NAME_REGEX.test(trimmed)) return `${label} may contain only letters, spaces, hyphens and apostrophes`;
+}
+/**
+* Validate a whole draft and report **every** bad field, not the first one.
+*
+* Returning on the first failure would make someone fix one field per attempt — the experience
+* D27 exists to rule out.
+*/
+function validateProfileDraft(draft) {
+	const errors = {};
+	const firstName = name(draft.firstName, "First name");
+	if (firstName) errors.firstName = firstName;
+	const lastName = name(draft.lastName, "Last name");
+	if (lastName) errors.lastName = lastName;
+	const phone = (draft.phoneNumber ?? "").trim();
+	if (phone !== "" && !E164_PHONE_REGEX.test(phone)) errors.phoneNumber = "Phone number must include the country code, e.g. +14155552671";
+	const cnic = (draft.cnic ?? "").trim();
+	if (cnic !== "" && cnic.replace(/\D/g, "") === "") errors.cnic = "National ID must contain digits";
+	return errors;
+}
+/** `null` when the file is acceptable (or absent — a photo is optional). */
+function validateProfileImage(file) {
+	if (!file) return null;
+	if (!file.type.startsWith("image/")) return "Choose an image file";
+	if (file.size > 52428800) return `Image must be smaller than ${Math.round(MAX_PROFILE_IMAGE_BYTES / (1024 * 1024))}MB`;
+	return null;
+}
+/**
+* The changed fields only, trimmed.
+*
+* Two deliberate exclusions: unchanged fields (so an untouched save is a no-op, FR-PROF-7) and
+* fields the person *emptied*. The platform's update applies truthy values only, so an empty
+* one is ignored today — but sending it would mean a future backend that honours empties could
+* blank stored data on a save nobody intended as a deletion.
+*/
+function buildProfileUpdate(draft, stored) {
+	const update = {};
+	for (const field of PROFILE_FIELDS) {
+		const next = (draft[field] ?? "").trim();
+		const current = (stored[field] ?? "").trim();
+		if (next === "" || next === current) continue;
+		update[field] = next;
+	}
+	return update;
+}
+/**
+* poly-auth's fixed conflict messages, mapped to the field each is about.
+*
+* Mirrors `IDENTITY_CONFLICT_MESSAGES` in `poly-auth/src/api/controllers/identity-conflict.util.ts`.
+* The platform reports a uniqueness conflict as a 409 with one of a known set of messages and no
+* machine-readable field, so this is the only way to put the error where the person can act on it
+* (FR-VALID-6) — and matching a fixed enum of strings is a mirror, not a guess at prose.
+*
+* `username` and `email` are absent on purpose: neither is editable here (D25), so there is no
+* field to attach them to and the caller must show them generally rather than drop them.
+*/
+const CONFLICT_MESSAGES = [["an account with this phone number already exists.", "phoneNumber"], ["an account with this cnic already exists.", "cnic"]];
+/**
+* Which editable field a platform conflict message is about, or `null` when it is about something
+* this surface does not edit — or is a message we do not recognise, in which case the caller
+* should show it as a general error. A reworded message degrades to that, rather than breaking.
+*/
+function conflictField(message) {
+	const normalized = (message ?? "").trim().toLowerCase();
+	if (normalized === "") return null;
+	return CONFLICT_MESSAGES.find(([text]) => text === normalized)?.[1] ?? null;
+}
+//#endregion
 //#region src/index.ts
 /**
 * @poly-x/core — framework-agnostic guts of the PolyX SDK.
 */
 const PACKAGE_NAME = "@poly-x/core";
-const version = "0.0.0";
+/** The published version of this package, injected at build time. */
+const version = "0.3.0";
 //#endregion
 exports.AuthClient = AuthClient;
 exports.DEFAULT_RETRY_POLICY = DEFAULT_RETRY_POLICY;
@@ -1157,8 +1319,10 @@ exports.InMemoryLock = InMemoryLock;
 exports.InMemoryPkceStore = InMemoryPkceStore;
 exports.InMemorySessionChannel = InMemorySessionChannel;
 exports.InMemorySessionStore = InMemorySessionStore;
+exports.MAX_PROFILE_IMAGE_BYTES = MAX_PROFILE_IMAGE_BYTES;
 exports.MockTransport = MockTransport;
 exports.PACKAGE_NAME = PACKAGE_NAME;
+exports.PROFILE_FIELDS = PROFILE_FIELDS;
 exports.PolyXConfigError = PolyXConfigError;
 exports.PolyXError = PolyXError;
 exports.RateLimitedError = RateLimitedError;
@@ -1169,9 +1333,12 @@ exports.SystemClock = SystemClock;
 exports.UnauthenticatedError = UnauthenticatedError;
 exports.UpstreamError = UpstreamError;
 exports.ValidationError = ValidationError;
+exports.buildProfileUpdate = buildProfileUpdate;
 exports.computeChallenge = computeChallenge;
+exports.conflictField = conflictField;
 exports.createSessionEngine = createSessionEngine;
 exports.decodeJwtExp = decodeJwtExp;
+exports.deriveDisplayClaims = deriveDisplayClaims;
 exports.generatePkce = generatePkce;
 exports.isTransientStatus = isTransientStatus;
 exports.mapPlatformError = mapPlatformError;
@@ -1185,4 +1352,6 @@ exports.randomState = randomState;
 exports.redactSensitive = redactSensitive;
 exports.reduceSessionState = reduce;
 exports.resolveConfig = resolveConfig;
+exports.validateProfileDraft = validateProfileDraft;
+exports.validateProfileImage = validateProfileImage;
 exports.version = version;

package/dist/index.d.cts

@@ -490,6 +490,34 @@ type PasswordAuthOutcome = {
   ticket?: string;
 } | {
   type: "no_access";
+}
+/**
+ * The credentials were accepted, but the platform wants a second proof of identity
+ * before issuing a session.
+ *
+ * RESERVED, NOT IMPLEMENTED. No deployment produces this today — multi-factor
+ * authentication is a platform release of its own. It is modelled now because the v1
+ * specification claimed the sign-in machine already accommodated a step like this and
+ * it did not: adding the variant later would be a breaking change across three
+ * packages, which is precisely the "flip, not a rebuild" promise that would have been
+ * broken. See the FSD (FR-STEP-1…4).
+ */
+| {
+  type: "verification_required";
+  challengeId: string;
+  factorTypes: readonly string[];
+}
+/**
+ * The APP is misconfigured — not the user's credentials. Reported for an
+ * unregistered `redirect_uri`, an unknown client, or a key bound to another
+ * deployment/environment. Kept separate because collapsing it into
+ * `invalid_credentials` tells a developer with a deployment problem that their
+ * password is wrong, which is exactly what consuming apps had to work around.
+ */
+| {
+  type: "configuration_error";
+  code: string;
+  message?: string;
 };
 declare function parsePasswordOutcome(status: number, body: unknown): PasswordAuthOutcome;
 /**
@@ -503,6 +531,21 @@ declare function parseResetOutcome(status: number, body: unknown): PasswordReset
 //#endregion
 //#region src/auth/normalize.d.ts
 declare function decodeJwtExp(token: string): number | null;
+/**
+ * The bounded display subset of a user record: name, email, avatar (ADR-0006).
+ *
+ * Exported because a profile update has to re-derive exactly these — and only these — after the
+ * platform saves. `normalizeRefresh` carries claims forward unchanged, so without a deliberate
+ * re-derivation the display name and avatar are whatever they were at login, forever.
+ *
+ * Identity and authorization claims are deliberately absent: this returns what is safe to
+ * recompute from a profile response, not a whole claim set.
+ */
+declare function deriveDisplayClaims(user: Record<string, unknown>): {
+  displayName?: string;
+  email?: string;
+  avatarUrl?: string;
+};
 /**
  * `POST /idp/token` → StoredSession. Claims carry identity plus the bounded display subset
  * (ADR-0006); AUTHZ populates roles/permissions later.
@@ -615,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
@@ -681,11 +741,62 @@ declare class AuthClient {
   private toError;
 }
 //#endregion
+//#region src/profile/validation.d.ts
+/**
+ * Profile input rules (FR-VALID-1…8).
+ *
+ * These are **mirrored from the platform's own validation** (`poly-auth`
+ * `src/api/validations/common-fields.ts`), not invented here. That is the whole point: a value
+ * this module accepts must not be one the platform rejects, or a person is shown an error they
+ * cannot act on — and the error arrives after a round trip, attached to nothing in particular.
+ *
+ * The mirroring is the fragile part. It is pinned by tests that restate the platform's patterns
+ * as literals and assert both agree, so a drift fails a build rather than a person's save.
+ */
+/** poly-auth's `imageUpload.middleware` cap. */
+declare const MAX_PROFILE_IMAGE_BYTES: number;
+/** The text fields this release makes editable (FR-PROF-4 / D25). */
+declare const PROFILE_FIELDS: readonly ["firstName", "lastName", "phoneNumber", "cnic", "gender"];
+type ProfileField = (typeof PROFILE_FIELDS)[number];
+type ProfileDraft = Partial<Record<ProfileField, string>>;
+type ProfileErrors = Partial<Record<ProfileField, string>>;
+/** The subset of `File` these rules need, so this stays testable without a DOM. */
+interface ProfileImageLike {
+  type: string;
+  size: number;
+  name?: string;
+}
+/**
+ * Validate a whole draft and report **every** bad field, not the first one.
+ *
+ * Returning on the first failure would make someone fix one field per attempt — the experience
+ * D27 exists to rule out.
+ */
+declare function validateProfileDraft(draft: ProfileDraft): ProfileErrors;
+/** `null` when the file is acceptable (or absent — a photo is optional). */
+declare function validateProfileImage(file: ProfileImageLike | null | undefined): string | null;
+/**
+ * The changed fields only, trimmed.
+ *
+ * Two deliberate exclusions: unchanged fields (so an untouched save is a no-op, FR-PROF-7) and
+ * fields the person *emptied*. The platform's update applies truthy values only, so an empty
+ * one is ignored today — but sending it would mean a future backend that honours empties could
+ * blank stored data on a save nobody intended as a deletion.
+ */
+declare function buildProfileUpdate(draft: ProfileDraft, stored: ProfileDraft): ProfileDraft;
+/**
+ * Which editable field a platform conflict message is about, or `null` when it is about something
+ * this surface does not edit — or is a message we do not recognise, in which case the caller
+ * should show it as a general error. A reworded message degrades to that, rather than breaking.
+ */
+declare function conflictField(message: string | undefined | null): ProfileField | null;
+//#endregion
 //#region src/index.d.ts
 /**
  * @poly-x/core — framework-agnostic guts of the PolyX SDK.
  */
 declare const PACKAGE_NAME = "@poly-x/core";
-declare const version = "0.0.0";
+/** The published version of this package, injected at build time. */
+declare const version: string;
 //#endregion
-export { AuthClient, type AuthClientOptions, type AuthorizeOutcome, type AuthorizeWithPasswordParams, type BrandingTokens, type BuildAuthorizeUrlParams, type Clock, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, ENDPOINTS, type ExchangeCodeParams, type FetchBrandingParams, FetchTransport, type FieldError, ForbiddenError, type HttpMethod, INITIAL_STATE as INITIAL_SESSION_STATE, InMemoryLock, InMemoryPkceStore, InMemorySessionChannel, InMemorySessionStore, type KeyEnv, type KeyKind, type Lock, type MockRoute, MockTransport, PACKAGE_NAME, type ParsedKey, type PasswordAuthOutcome, type PasswordResetOutcome, type PkceEntry, type PkcePair, type PkceStore, type PlatformResponseLike, PolyXConfigError, PolyXError, type PolyXErrorOptions, RateLimitedError, type RefreshTokens, type ResolveConfigInput, type ResolvedConfig, type RetryPolicy, type RuntimeContext, type Session, type SessionChannel, type SessionChannelEvent, type SessionClaims, SessionEngine, type SessionEngineOptions, type SessionEvent, SessionExpiredError, SessionRevokedError, type SessionState, type SessionStore, type SetPasswordParams, type SignedOutReason, type StoredSession, SystemClock, type TenantOption, type TimerHandle, type TokenSet, type Transport, type TransportRequest, type TransportResponse, UnauthenticatedError, UpstreamError, ValidationError, computeChallenge, createSessionEngine, decodeJwtExp, generatePkce, isTransientStatus, mapPlatformError, normalizeExchange, normalizeRefresh, parseAuthorizeOutcome, parsePasswordOutcome, parsePolyXKey, parseResetOutcome, randomState, redactSensitive, reduce as reduceSessionState, resolveConfig, version };
+export { AuthClient, type AuthClientOptions, type AuthorizeOutcome, type AuthorizeWithPasswordParams, type BrandingTokens, type BuildAuthorizeUrlParams, type Clock, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, ENDPOINTS, type ExchangeCodeParams, type FetchBrandingParams, FetchTransport, type FieldError, ForbiddenError, type HttpMethod, INITIAL_STATE as INITIAL_SESSION_STATE, InMemoryLock, InMemoryPkceStore, InMemorySessionChannel, InMemorySessionStore, type KeyEnv, type KeyKind, type Lock, MAX_PROFILE_IMAGE_BYTES, type MockRoute, MockTransport, PACKAGE_NAME, PROFILE_FIELDS, type ParsedKey, type PasswordAuthOutcome, type PasswordResetOutcome, type PkceEntry, type PkcePair, type PkceStore, type PlatformResponseLike, PolyXConfigError, PolyXError, type PolyXErrorOptions, type ProfileDraft, type ProfileErrors, type ProfileField, type ProfileImageLike, RateLimitedError, type RefreshTokens, type ResolveConfigInput, type ResolvedConfig, type RetryPolicy, type RuntimeContext, type Session, type SessionChannel, type SessionChannelEvent, type SessionClaims, SessionEngine, type SessionEngineOptions, type SessionEvent, SessionExpiredError, SessionRevokedError, type SessionState, type SessionStore, type SetPasswordParams, type SignedOutReason, type StoredSession, SystemClock, type TenantOption, type TimerHandle, type TokenSet, type Transport, type TransportRequest, type TransportResponse, 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/dist/index.d.mts

@@ -490,6 +490,34 @@ type PasswordAuthOutcome = {
   ticket?: string;
 } | {
   type: "no_access";
+}
+/**
+ * The credentials were accepted, but the platform wants a second proof of identity
+ * before issuing a session.
+ *
+ * RESERVED, NOT IMPLEMENTED. No deployment produces this today — multi-factor
+ * authentication is a platform release of its own. It is modelled now because the v1
+ * specification claimed the sign-in machine already accommodated a step like this and
+ * it did not: adding the variant later would be a breaking change across three
+ * packages, which is precisely the "flip, not a rebuild" promise that would have been
+ * broken. See the FSD (FR-STEP-1…4).
+ */
+| {
+  type: "verification_required";
+  challengeId: string;
+  factorTypes: readonly string[];
+}
+/**
+ * The APP is misconfigured — not the user's credentials. Reported for an
+ * unregistered `redirect_uri`, an unknown client, or a key bound to another
+ * deployment/environment. Kept separate because collapsing it into
+ * `invalid_credentials` tells a developer with a deployment problem that their
+ * password is wrong, which is exactly what consuming apps had to work around.
+ */
+| {
+  type: "configuration_error";
+  code: string;
+  message?: string;
 };
 declare function parsePasswordOutcome(status: number, body: unknown): PasswordAuthOutcome;
 /**
@@ -503,6 +531,21 @@ declare function parseResetOutcome(status: number, body: unknown): PasswordReset
 //#endregion
 //#region src/auth/normalize.d.ts
 declare function decodeJwtExp(token: string): number | null;
+/**
+ * The bounded display subset of a user record: name, email, avatar (ADR-0006).
+ *
+ * Exported because a profile update has to re-derive exactly these — and only these — after the
+ * platform saves. `normalizeRefresh` carries claims forward unchanged, so without a deliberate
+ * re-derivation the display name and avatar are whatever they were at login, forever.
+ *
+ * Identity and authorization claims are deliberately absent: this returns what is safe to
+ * recompute from a profile response, not a whole claim set.
+ */
+declare function deriveDisplayClaims(user: Record<string, unknown>): {
+  displayName?: string;
+  email?: string;
+  avatarUrl?: string;
+};
 /**
  * `POST /idp/token` → StoredSession. Claims carry identity plus the bounded display subset
  * (ADR-0006); AUTHZ populates roles/permissions later.
@@ -615,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
@@ -681,11 +741,62 @@ declare class AuthClient {
   private toError;
 }
 //#endregion
+//#region src/profile/validation.d.ts
+/**
+ * Profile input rules (FR-VALID-1…8).
+ *
+ * These are **mirrored from the platform's own validation** (`poly-auth`
+ * `src/api/validations/common-fields.ts`), not invented here. That is the whole point: a value
+ * this module accepts must not be one the platform rejects, or a person is shown an error they
+ * cannot act on — and the error arrives after a round trip, attached to nothing in particular.
+ *
+ * The mirroring is the fragile part. It is pinned by tests that restate the platform's patterns
+ * as literals and assert both agree, so a drift fails a build rather than a person's save.
+ */
+/** poly-auth's `imageUpload.middleware` cap. */
+declare const MAX_PROFILE_IMAGE_BYTES: number;
+/** The text fields this release makes editable (FR-PROF-4 / D25). */
+declare const PROFILE_FIELDS: readonly ["firstName", "lastName", "phoneNumber", "cnic", "gender"];
+type ProfileField = (typeof PROFILE_FIELDS)[number];
+type ProfileDraft = Partial<Record<ProfileField, string>>;
+type ProfileErrors = Partial<Record<ProfileField, string>>;
+/** The subset of `File` these rules need, so this stays testable without a DOM. */
+interface ProfileImageLike {
+  type: string;
+  size: number;
+  name?: string;
+}
+/**
+ * Validate a whole draft and report **every** bad field, not the first one.
+ *
+ * Returning on the first failure would make someone fix one field per attempt — the experience
+ * D27 exists to rule out.
+ */
+declare function validateProfileDraft(draft: ProfileDraft): ProfileErrors;
+/** `null` when the file is acceptable (or absent — a photo is optional). */
+declare function validateProfileImage(file: ProfileImageLike | null | undefined): string | null;
+/**
+ * The changed fields only, trimmed.
+ *
+ * Two deliberate exclusions: unchanged fields (so an untouched save is a no-op, FR-PROF-7) and
+ * fields the person *emptied*. The platform's update applies truthy values only, so an empty
+ * one is ignored today — but sending it would mean a future backend that honours empties could
+ * blank stored data on a save nobody intended as a deletion.
+ */
+declare function buildProfileUpdate(draft: ProfileDraft, stored: ProfileDraft): ProfileDraft;
+/**
+ * Which editable field a platform conflict message is about, or `null` when it is about something
+ * this surface does not edit — or is a message we do not recognise, in which case the caller
+ * should show it as a general error. A reworded message degrades to that, rather than breaking.
+ */
+declare function conflictField(message: string | undefined | null): ProfileField | null;
+//#endregion
 //#region src/index.d.ts
 /**
  * @poly-x/core — framework-agnostic guts of the PolyX SDK.
  */
 declare const PACKAGE_NAME = "@poly-x/core";
-declare const version = "0.0.0";
+/** The published version of this package, injected at build time. */
+declare const version: string;
 //#endregion
-export { AuthClient, type AuthClientOptions, type AuthorizeOutcome, type AuthorizeWithPasswordParams, type BrandingTokens, type BuildAuthorizeUrlParams, type Clock, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, ENDPOINTS, type ExchangeCodeParams, type FetchBrandingParams, FetchTransport, type FieldError, ForbiddenError, type HttpMethod, INITIAL_STATE as INITIAL_SESSION_STATE, InMemoryLock, InMemoryPkceStore, InMemorySessionChannel, InMemorySessionStore, type KeyEnv, type KeyKind, type Lock, type MockRoute, MockTransport, PACKAGE_NAME, type ParsedKey, type PasswordAuthOutcome, type PasswordResetOutcome, type PkceEntry, type PkcePair, type PkceStore, type PlatformResponseLike, PolyXConfigError, PolyXError, type PolyXErrorOptions, RateLimitedError, type RefreshTokens, type ResolveConfigInput, type ResolvedConfig, type RetryPolicy, type RuntimeContext, type Session, type SessionChannel, type SessionChannelEvent, type SessionClaims, SessionEngine, type SessionEngineOptions, type SessionEvent, SessionExpiredError, SessionRevokedError, type SessionState, type SessionStore, type SetPasswordParams, type SignedOutReason, type StoredSession, SystemClock, type TenantOption, type TimerHandle, type TokenSet, type Transport, type TransportRequest, type TransportResponse, UnauthenticatedError, UpstreamError, ValidationError, computeChallenge, createSessionEngine, decodeJwtExp, generatePkce, isTransientStatus, mapPlatformError, normalizeExchange, normalizeRefresh, parseAuthorizeOutcome, parsePasswordOutcome, parsePolyXKey, parseResetOutcome, randomState, redactSensitive, reduce as reduceSessionState, resolveConfig, version };
+export { AuthClient, type AuthClientOptions, type AuthorizeOutcome, type AuthorizeWithPasswordParams, type BrandingTokens, type BuildAuthorizeUrlParams, type Clock, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, ENDPOINTS, type ExchangeCodeParams, type FetchBrandingParams, FetchTransport, type FieldError, ForbiddenError, type HttpMethod, INITIAL_STATE as INITIAL_SESSION_STATE, InMemoryLock, InMemoryPkceStore, InMemorySessionChannel, InMemorySessionStore, type KeyEnv, type KeyKind, type Lock, MAX_PROFILE_IMAGE_BYTES, type MockRoute, MockTransport, PACKAGE_NAME, PROFILE_FIELDS, type ParsedKey, type PasswordAuthOutcome, type PasswordResetOutcome, type PkceEntry, type PkcePair, type PkceStore, type PlatformResponseLike, PolyXConfigError, PolyXError, type PolyXErrorOptions, type ProfileDraft, type ProfileErrors, type ProfileField, type ProfileImageLike, RateLimitedError, type RefreshTokens, type ResolveConfigInput, type ResolvedConfig, type RetryPolicy, type RuntimeContext, type Session, type SessionChannel, type SessionChannelEvent, type SessionClaims, SessionEngine, type SessionEngineOptions, type SessionEvent, SessionExpiredError, SessionRevokedError, type SessionState, type SessionStore, type SetPasswordParams, type SignedOutReason, type StoredSession, SystemClock, type TenantOption, type TimerHandle, type TokenSet, type Transport, type TransportRequest, type TransportResponse, 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/dist/index.mjs

@@ -629,7 +629,7 @@ var SessionEngine = class {
 			this.applySignOut("expired", true);
 			return;
 		}
-		if (error instanceof UpstreamError || error instanceof Error) this.dispatch({ type: "refresh-failed-transient" });
+		this.dispatch({ type: "refresh-failed-transient" });
 	}
 	async applySignOut(reason, broadcast) {
 		if (this.state.status === "signed-out") return;
@@ -788,6 +788,18 @@ function parseAuthorizeOutcome(status, body) {
 	if (statusField === "login_required" || b.code === "LOGIN_REQUIRED") return { type: "login_required" };
 	return { type: "login_required" };
 }
+/**
+* Platform codes that mean "this app is misconfigured", verified against poly-auth
+* `api/constants/auth-responses.ts` and `idp.controller.ts:validateClientAndRedirect`
+* (2026-07-29). Only these map across — an unrecognised 400 keeps the previous
+* behaviour rather than being mislabelled as misconfiguration.
+*/
+const CONFIGURATION_ERROR_CODES = /* @__PURE__ */ new Set([
+	"REDIRECT_URI_NOT_ALLOWED",
+	"INVALID_CLIENT",
+	"KEY_DEPLOYMENT_MISMATCH",
+	"KEY_ENVIRONMENT_MISMATCH"
+]);
 function parsePasswordOutcome(status, body) {
 	const b = asRecord$1(body);
 	const statusField = typeof b.status === "string" ? b.status : void 0;
@@ -808,6 +820,16 @@ function parsePasswordOutcome(status, body) {
 		ticket: typeof b.ticket === "string" ? b.ticket : void 0
 	};
 	if (status === 403) return { type: "no_access" };
+	if (statusField === "verification_required" && typeof b.challengeId === "string") return {
+		type: "verification_required",
+		challengeId: b.challengeId,
+		factorTypes: Array.isArray(b.factorTypes) ? b.factorTypes.filter((f) => typeof f === "string") : []
+	};
+	if (status === 400 && typeof b.code === "string" && CONFIGURATION_ERROR_CODES.has(b.code)) return {
+		type: "configuration_error",
+		code: b.code,
+		message: typeof b.message === "string" ? b.message : void 0
+	};
 	return { type: "invalid_credentials" };
 }
 function parseResetOutcome(status, body) {
@@ -862,6 +884,23 @@ function deriveDisplayName(user) {
 	return displayString([displayString(user.firstName, MAX_DISPLAY_NAME), displayString(user.lastName, MAX_DISPLAY_NAME)].filter(Boolean).join(" "), MAX_DISPLAY_NAME) ?? displayString(user.username, MAX_DISPLAY_NAME) ?? displayString(user.email, MAX_DISPLAY_NAME);
 }
 /**
+* The bounded display subset of a user record: name, email, avatar (ADR-0006).
+*
+* Exported because a profile update has to re-derive exactly these — and only these — after the
+* platform saves. `normalizeRefresh` carries claims forward unchanged, so without a deliberate
+* re-derivation the display name and avatar are whatever they were at login, forever.
+*
+* Identity and authorization claims are deliberately absent: this returns what is safe to
+* recompute from a profile response, not a whole claim set.
+*/
+function deriveDisplayClaims(user) {
+	return {
+		displayName: deriveDisplayName(user),
+		email: displayString(user.email, MAX_DISPLAY_NAME),
+		avatarUrl: displayString(user.profilePicture, MAX_AVATAR_URL)
+	};
+}
+/**
 * `POST /idp/token` → StoredSession. Claims carry identity plus the bounded display subset
 * (ADR-0006); AUTHZ populates roles/permissions later.
 *
@@ -949,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)
@@ -1138,11 +1195,116 @@ var AuthClient = class {
 	}
 };
 //#endregion
+//#region src/profile/validation.ts
+/**
+* Profile input rules (FR-VALID-1…8).
+*
+* These are **mirrored from the platform's own validation** (`poly-auth`
+* `src/api/validations/common-fields.ts`), not invented here. That is the whole point: a value
+* this module accepts must not be one the platform rejects, or a person is shown an error they
+* cannot act on — and the error arrives after a round trip, attached to nothing in particular.
+*
+* The mirroring is the fragile part. It is pinned by tests that restate the platform's patterns
+* as literals and assert both agree, so a drift fails a build rather than a person's save.
+*/
+/**
+* One or more Unicode letters, optionally joined by a single space, hyphen or apostrophe —
+* "José", "O'Brien", "Anne-Marie", "van der Berg". No digits, no leading/trailing/double
+* separators. (poly-auth `PERSON_NAME_REGEX`.)
+*/
+const PERSON_NAME_REGEX = /^\p{L}+(?:[ '-]\p{L}+)*$/u;
+/** Leading "+", country code starting 1-9, then 7-14 more digits. (poly-auth `E164_PHONE_REGEX`.) */
+const E164_PHONE_REGEX = /^\+[1-9]\d{7,14}$/;
+/** poly-auth's person-name bounds for these two fields (`min: 1, max: 20`). */
+const NAME_MAX = 20;
+/** poly-auth's `imageUpload.middleware` cap. */
+const MAX_PROFILE_IMAGE_BYTES = 50 * 1024 * 1024;
+/** The text fields this release makes editable (FR-PROF-4 / D25). */
+const PROFILE_FIELDS = [
+	"firstName",
+	"lastName",
+	"phoneNumber",
+	"cnic",
+	"gender"
+];
+function name(value, label) {
+	const trimmed = (value ?? "").trim();
+	if (trimmed === "") return `${label} is required`;
+	if (trimmed.length > NAME_MAX) return `${label} cannot exceed ${NAME_MAX} characters`;
+	if (!PERSON_NAME_REGEX.test(trimmed)) return `${label} may contain only letters, spaces, hyphens and apostrophes`;
+}
+/**
+* Validate a whole draft and report **every** bad field, not the first one.
+*
+* Returning on the first failure would make someone fix one field per attempt — the experience
+* D27 exists to rule out.
+*/
+function validateProfileDraft(draft) {
+	const errors = {};
+	const firstName = name(draft.firstName, "First name");
+	if (firstName) errors.firstName = firstName;
+	const lastName = name(draft.lastName, "Last name");
+	if (lastName) errors.lastName = lastName;
+	const phone = (draft.phoneNumber ?? "").trim();
+	if (phone !== "" && !E164_PHONE_REGEX.test(phone)) errors.phoneNumber = "Phone number must include the country code, e.g. +14155552671";
+	const cnic = (draft.cnic ?? "").trim();
+	if (cnic !== "" && cnic.replace(/\D/g, "") === "") errors.cnic = "National ID must contain digits";
+	return errors;
+}
+/** `null` when the file is acceptable (or absent — a photo is optional). */
+function validateProfileImage(file) {
+	if (!file) return null;
+	if (!file.type.startsWith("image/")) return "Choose an image file";
+	if (file.size > 52428800) return `Image must be smaller than ${Math.round(MAX_PROFILE_IMAGE_BYTES / (1024 * 1024))}MB`;
+	return null;
+}
+/**
+* The changed fields only, trimmed.
+*
+* Two deliberate exclusions: unchanged fields (so an untouched save is a no-op, FR-PROF-7) and
+* fields the person *emptied*. The platform's update applies truthy values only, so an empty
+* one is ignored today — but sending it would mean a future backend that honours empties could
+* blank stored data on a save nobody intended as a deletion.
+*/
+function buildProfileUpdate(draft, stored) {
+	const update = {};
+	for (const field of PROFILE_FIELDS) {
+		const next = (draft[field] ?? "").trim();
+		const current = (stored[field] ?? "").trim();
+		if (next === "" || next === current) continue;
+		update[field] = next;
+	}
+	return update;
+}
+/**
+* poly-auth's fixed conflict messages, mapped to the field each is about.
+*
+* Mirrors `IDENTITY_CONFLICT_MESSAGES` in `poly-auth/src/api/controllers/identity-conflict.util.ts`.
+* The platform reports a uniqueness conflict as a 409 with one of a known set of messages and no
+* machine-readable field, so this is the only way to put the error where the person can act on it
+* (FR-VALID-6) — and matching a fixed enum of strings is a mirror, not a guess at prose.
+*
+* `username` and `email` are absent on purpose: neither is editable here (D25), so there is no
+* field to attach them to and the caller must show them generally rather than drop them.
+*/
+const CONFLICT_MESSAGES = [["an account with this phone number already exists.", "phoneNumber"], ["an account with this cnic already exists.", "cnic"]];
+/**
+* Which editable field a platform conflict message is about, or `null` when it is about something
+* this surface does not edit — or is a message we do not recognise, in which case the caller
+* should show it as a general error. A reworded message degrades to that, rather than breaking.
+*/
+function conflictField(message) {
+	const normalized = (message ?? "").trim().toLowerCase();
+	if (normalized === "") return null;
+	return CONFLICT_MESSAGES.find(([text]) => text === normalized)?.[1] ?? null;
+}
+//#endregion
 //#region src/index.ts
 /**
 * @poly-x/core — framework-agnostic guts of the PolyX SDK.
 */
 const PACKAGE_NAME = "@poly-x/core";
-const version = "0.0.0";
+/** The published version of this package, injected at build time. */
+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, MockTransport, PACKAGE_NAME, PolyXConfigError, PolyXError, RateLimitedError, SessionEngine, SessionExpiredError, SessionRevokedError, SystemClock, UnauthenticatedError, UpstreamError, ValidationError, computeChallenge, createSessionEngine, decodeJwtExp, generatePkce, isTransientStatus, mapPlatformError, normalizeExchange, normalizeRefresh, parseAuthorizeOutcome, parsePasswordOutcome, parsePolyXKey, parseResetOutcome, randomState, redactSensitive, reduce as reduceSessionState, resolveConfig, version };
+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.1.1",
+  "version": "0.3.0",
   "description": "Framework-agnostic core of the PolyX SDK",
   "license": "MIT",
   "type": "module",