@poly-x/core 0.1.0-alpha.0 → 0.1.0-alpha.10

package/dist/index.cjs

@@ -167,11 +167,21 @@ function resolveConfig(input) {
 		}
 		baseUrl = normalizeBaseUrl(input.baseUrl);
 	} else baseUrl = `https://${normalizeBaseUrl(key.host)}`;
+	let signInUrl;
+	if (input.signInUrl !== void 0) {
+		try {
+			new URL(input.signInUrl);
+		} catch {
+			throw new PolyXConfigError("The signInUrl is not a valid URL.", { code: "SIGN_IN_URL_INVALID" });
+		}
+		signInUrl = normalizeBaseUrl(input.signInUrl);
+	}
 	return {
 		key,
 		kind: key.kind,
 		env: key.env,
 		baseUrl,
+		signInUrl,
 		context
 	};
 }
@@ -183,7 +193,16 @@ function resolveConfig(input) {
 * against poly-auth/src/api/constants/auth-responses.ts (2026-07-06). Unknown
 * shapes become a typed UNRECOGNIZED_RESPONSE — never a guess.
 */
-const REVOKED_CODES = /* @__PURE__ */ new Set(["REFRESH_TOKEN_REUSE", "SESSION_REVOKED"]);
+/**
+* Terminal: the session is gone and no retry brings it back. The platform revokes every session
+* for a user on permission change, suspension, and password reset — `SESSION_REVOKED` for the
+* revocation itself, `SESSION_MISMATCH` when the presented token no longer matches its session.
+*/
+const REVOKED_CODES = /* @__PURE__ */ new Set([
+	"REFRESH_TOKEN_REUSE",
+	"SESSION_REVOKED",
+	"SESSION_MISMATCH"
+]);
 const EXPIRED_CODES = /* @__PURE__ */ new Set([
 	"SESSION_EXPIRED",
 	"REFRESH_TOKEN_REQUIRED",
@@ -698,8 +717,41 @@ const ENDPOINTS = {
 	authorize: "/v1/idp/authorize",
 	token: "/v1/idp/token",
 	refresh: "/v1/auth/refresh-token",
+	/**
+	* Ecosystem (SSO) logout. Resolves the session from the *browser's* ecosystem cookie,
+	* so it only revokes when called from a context that carries it — a top-level hop.
+	* A server-to-server call reaches it without the cookie and revokes nothing (it still
+	* answers 200), which is why BFF sign-out must use the bearer-authenticated pair below.
+	*/
 	logout: "/v1/idp/logout",
-	orgResolve: "/v1/idp/org-resolve"
+	/**
+	* Bearer-authenticated revocation: the access token identifies the session, so these
+	* work from any context that holds one — notably the BFF, where the token is sealed in
+	* the session cookie and no browser cookie reaches poly-auth. `logout` revokes this
+	* session; `logoutAll` revokes every session for the user.
+	*/
+	authLogout: "/v1/auth/logout",
+	authLogoutAll: "/v1/auth/logout-all",
+	orgResolve: "/v1/idp/org-resolve",
+	/**
+	* Completes the admin temp-password flow: the user signed in with a temporary
+	* password, poly-auth answered `403 {userPasswordSet, userId}`, and this sets
+	* the real one. Only succeeds while the account is flagged `mustChangePassword`.
+	*/
+	setPassword: "/v1/auth/set-password",
+	/**
+	* Server-mediated self-service reset (poly-x v5 / F040). `forgotPassword` starts it
+	* — always a uniform 202, the token is emailed to the mailbox, never returned.
+	* `resetPassword` redeems that opaque token single-use and sets the new password.
+	*/
+	forgotPassword: "/v1/idp/forgot-password",
+	resetPassword: "/v1/idp/reset-password",
+	/**
+	* Public, pk_-scoped login-page branding (F037 / FR-BRND). GET with `client_id`
+	* (+ optional `organizationCode`) → the bounded `{ tokens }` set. Never 5xx's /
+	* never blocks login; the SDK falls back to its built-in defaults on any failure.
+	*/
+	branding: "/v1/idp/branding"
 };
 //#endregion
 //#region src/auth/outcomes.ts
@@ -737,6 +789,33 @@ function parseAuthorizeOutcome(status, body) {
 	if (statusField === "login_required" || b.code === "LOGIN_REQUIRED") return { type: "login_required" };
 	return { type: "login_required" };
 }
+function parsePasswordOutcome(status, body) {
+	const b = asRecord$1(body);
+	const statusField = typeof b.status === "string" ? b.status : void 0;
+	if (statusField === "authorized" && typeof b.code === "string") return {
+		type: "authorized",
+		code: b.code,
+		state: typeof b.state === "string" ? b.state : "",
+		redirectUri: typeof b.redirectUri === "string" ? b.redirectUri : void 0
+	};
+	if (statusField === "select_tenant") return {
+		type: "select_tenant",
+		state: typeof b.state === "string" ? b.state : "",
+		tenants: parseTenants(b.tenants)
+	};
+	if (status === 403 && b.userPasswordSet === true && typeof b.userId === "string") return {
+		type: "password_change_required",
+		userId: b.userId,
+		ticket: typeof b.ticket === "string" ? b.ticket : void 0
+	};
+	if (status === 403) return { type: "no_access" };
+	return { type: "invalid_credentials" };
+}
+function parseResetOutcome(status, body) {
+	if (status === 200) return "ok";
+	if (asRecord$1(body).status === "weak_password") return "weak_password";
+	return "invalid_or_expired";
+}
 //#endregion
 //#region src/auth/normalize.ts
 const FALLBACK_TTL_MS = 5 * 6e4;
@@ -762,7 +841,35 @@ function toTokenSet(accessToken, refreshToken, now) {
 function asRecord(value) {
 	return value && typeof value === "object" ? value : {};
 }
-/** `POST /idp/token` → StoredSession. Claims mapping is minimal in v1 (userId + org); AUTHZ populates roles/permissions later. */
+/**
+* Display-claim caps (ADR-0006). These values are user-controlled and unbounded in the
+* platform's schema, and they ride in a sealed ~4KB cookie whose failure mode is the browser
+* silently dropping it. Cap at the boundary rather than trusting the input.
+*/
+const MAX_DISPLAY_NAME = 128;
+const MAX_AVATAR_URL = 512;
+/** A non-blank string, trimmed and capped — otherwise undefined. The shim never guesses. */
+function displayString(value, max) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return void 0;
+	return trimmed.slice(0, max);
+}
+/**
+* The best human label the token response can give us: full name, else username, else email.
+* Each part is checked independently so a user with only one of them never renders "undefined".
+*/
+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);
+}
+/**
+* `POST /idp/token` → StoredSession. Claims carry identity plus the bounded display subset
+* (ADR-0006); AUTHZ populates roles/permissions later.
+*
+* `organizationId` comes from the exchange's `tenantId`, never from the user document: a
+* cross-membership login resolves a tenant that is deliberately *not* the user's home
+* organization, and reading it off the user would silently sign them into the wrong one.
+*/
 function normalizeExchange(body, now) {
 	const data = asRecord(asRecord(body).data);
 	const user = asRecord(data.user);
@@ -772,7 +879,10 @@ function normalizeExchange(body, now) {
 		userId,
 		organizationId: data.tenantId != null ? String(data.tenantId) : void 0,
 		roles: [],
-		permissions: []
+		permissions: [],
+		displayName: deriveDisplayName(user),
+		email: displayString(user.email, MAX_DISPLAY_NAME),
+		avatarUrl: displayString(user.profilePicture, MAX_AVATAR_URL)
 	};
 	return {
 		tokens: toTokenSet(String(data.accessToken ?? ""), stringOrUndefined(data.refreshToken), now),
@@ -815,10 +925,9 @@ var AuthClient = class {
 		this.transport = options.transport;
 		this.clock = options.clock ?? new SystemClock();
 	}
-	buildAuthorizeUrl(params) {
-		const url = new URL(this.config.baseUrl + ENDPOINTS.authorize);
+	appendAuthorizeParams(url, params) {
 		url.searchParams.set("response_type", "code");
-		url.searchParams.set("client", this.config.key.raw);
+		url.searchParams.set("client_id", this.config.key.raw);
 		url.searchParams.set("redirect_uri", params.redirectUri);
 		url.searchParams.set("state", params.state);
 		url.searchParams.set("code_challenge", params.challenge);
@@ -827,6 +936,20 @@ var AuthClient = class {
 		if (params.prompt) url.searchParams.set("prompt", params.prompt);
 		return url.toString();
 	}
+	/** The API `GET /v1/idp/authorize` URL — used for the silent warm-hop probe. */
+	buildAuthorizeUrl(params) {
+		return this.appendAuthorizeParams(new URL(this.config.baseUrl + ENDPOINTS.authorize), params);
+	}
+	/**
+	* The URL the interactive sign-in popup/redirect opens. Targets the HOSTED login
+	* PAGE (`config.signInUrl`) — which renders the form, POSTs the API, and redirects
+	* to `redirect_uri` with the code. Falls back to the API authorize URL when no
+	* `signInUrl` is configured (deployments where the API host serves the page).
+	*/
+	buildSignInUrl(params) {
+		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. */
 	async completeAuthorize(params) {
 		const response = await this.transport.request({
@@ -836,6 +959,86 @@ var AuthClient = class {
 		if (response.status >= 500) throw this.toError(response);
 		return parseAuthorizeOutcome(response.status, response.body);
 	}
+	/**
+	* The embedded `<SignIn/>` credential flow (D2b): POST `/idp/authorize` with
+	* email/password + PKCE. On `authorized` the caller exchanges the returned
+	* `code` (server-side, via the BFF) for a session — no redirect to a hosted
+	* login page. Creds live only for the duration of this request; the SDK never
+	* stores them. 5xx surfaces as a typed error; every other status is a typed
+	* outcome the UI branches on.
+	*/
+	async authorizeWithPassword(params) {
+		const response = await this.transport.request({
+			method: "POST",
+			url: this.config.baseUrl + ENDPOINTS.authorize,
+			body: {
+				response_type: "code",
+				client_id: this.config.key.raw,
+				redirect_uri: params.redirectUri,
+				state: params.state,
+				code_challenge: params.challenge,
+				code_challenge_method: "S256",
+				email: params.email,
+				password: params.password,
+				...params.organizationCode ? { organizationCode: params.organizationCode } : {},
+				...params.tenantId ? { tenantId: params.tenantId } : {}
+			}
+		});
+		if (response.status >= 500) throw this.toError(response);
+		return parsePasswordOutcome(response.status, response.body);
+	}
+	/**
+	* Set the real password for a user the platform has flagged `mustChangePassword`
+	* (the admin temp-password flow). Call this only after `authorizeWithPassword`
+	* has returned `password_change_required` for that same user — that response IS
+	* the proof the caller knows the temporary password.
+	*/
+	async setPassword(params) {
+		const response = await this.transport.request({
+			method: "PATCH",
+			url: this.config.baseUrl + ENDPOINTS.setPassword,
+			body: {
+				userId: params.userId,
+				newPassword: params.newPassword,
+				confirmPassword: params.confirmPassword,
+				...params.ticket ? { ticket: params.ticket } : {}
+			}
+		});
+		if (response.status !== 200) throw this.toError(response);
+	}
+	/**
+	* Start a server-mediated self-service reset (F040). POSTs the email + this app's
+	* publishable key; the backend resolves the account, mints a single-use token, and
+	* emails the link ITSELF — nothing comes back but a uniform 202. Resolves on success;
+	* a 4xx (e.g. a misconfigured key) surfaces as a typed error for the developer.
+	*/
+	async requestPasswordReset(params) {
+		const response = await this.transport.request({
+			method: "POST",
+			url: this.config.baseUrl + ENDPOINTS.forgotPassword,
+			body: {
+				email: params.email,
+				client_id: this.config.key.raw
+			}
+		});
+		if (response.status >= 400) throw this.toError(response);
+	}
+	/**
+	* Redeem a reset token (the opaque value from the emailed link) single-use and set
+	* the new password. Returns a typed outcome the UI branches on; only a 5xx throws.
+	*/
+	async resetPassword(params) {
+		const response = await this.transport.request({
+			method: "POST",
+			url: this.config.baseUrl + ENDPOINTS.resetPassword,
+			body: {
+				token: params.token,
+				newPassword: params.newPassword
+			}
+		});
+		if (response.status >= 500) throw this.toError(response);
+		return parseResetOutcome(response.status, response.body);
+	}
 	async exchangeCode(params) {
 		const response = await this.transport.request({
 			method: "POST",
@@ -845,12 +1048,33 @@ var AuthClient = class {
 				code: params.code,
 				code_verifier: params.codeVerifier,
 				redirect_uri: params.redirectUri,
-				client: this.config.key.raw
+				client_id: this.config.key.raw
 			}
 		});
 		if (response.status !== 200) throw this.toError(response);
 		return normalizeExchange(response.body, this.clock.now());
 	}
+	/**
+	* Fetch this app's login-page branding (public, pk_-scoped). NEVER throws and never
+	* blocks the sign-in form: any non-200, malformed body, or network failure resolves
+	* to an empty token set so the caller keeps its built-in defaults (FR-BRND-3).
+	*/
+	async fetchBranding(params = {}) {
+		try {
+			const url = new URL(this.config.baseUrl + ENDPOINTS.branding);
+			url.searchParams.set("client_id", this.config.key.raw);
+			if (params.organizationCode) url.searchParams.set("organizationCode", params.organizationCode);
+			const response = await this.transport.request({
+				method: "GET",
+				url: url.toString()
+			});
+			if (response.status !== 200) return {};
+			const tokens = response.body?.tokens;
+			return tokens && typeof tokens === "object" ? tokens : {};
+		} catch {
+			return {};
+		}
+	}
 	/** The `RefreshTokens` function the SessionEngine (F003) injects. */
 	createRefresher() {
 		return async (current) => {
@@ -863,6 +1087,11 @@ var AuthClient = class {
 			return normalizeRefresh(response.body, current, this.clock.now());
 		};
 	}
+	/**
+	* Ecosystem logout — only revokes when the caller carries the browser's ecosystem
+	* cookie (a top-level hop). From a server-to-server context it clears nothing and
+	* still answers 200; use `revokeSession` there.
+	*/
 	async logout(scope = "device") {
 		const response = await this.transport.request({
 			method: "POST",
@@ -871,6 +1100,22 @@ var AuthClient = class {
 		});
 		if (response.status >= 400) throw this.toError(response);
 	}
+	/**
+	* Revoke a session using the access token as proof — the only logout that works
+	* server-side, where no browser cookie reaches poly-auth. `device` ends this session;
+	* `everywhere` ends every session for the user (FR-SSO-5).
+	*
+	* The token goes in the Authorization header and nowhere else: repeating it in the
+	* body would only widen where it can leak.
+	*/
+	async revokeSession(accessToken, scope = "device") {
+		const response = await this.transport.request({
+			method: "POST",
+			url: this.config.baseUrl + (scope === "everywhere" ? ENDPOINTS.authLogoutAll : ENDPOINTS.authLogout),
+			headers: { Authorization: `Bearer ${accessToken}` }
+		});
+		if (response.status >= 400) throw this.toError(response);
+	}
 	async resolveOrg(email) {
 		const response = await this.transport.request({
 			method: "POST",
@@ -932,7 +1177,9 @@ exports.mapPlatformError = mapPlatformError;
 exports.normalizeExchange = normalizeExchange;
 exports.normalizeRefresh = normalizeRefresh;
 exports.parseAuthorizeOutcome = parseAuthorizeOutcome;
+exports.parsePasswordOutcome = parsePasswordOutcome;
 exports.parsePolyXKey = parsePolyXKey;
+exports.parseResetOutcome = parseResetOutcome;
 exports.randomState = randomState;
 exports.redactSensitive = redactSensitive;
 exports.reduceSessionState = reduce;

package/dist/index.d.cts

@@ -27,6 +27,14 @@ interface ResolveConfigInput {
   key: string;
   /** Wins over the key-embedded host. */
   baseUrl?: string;
+  /**
+   * URL of the HOSTED sign-in page (the account portal that renders the login
+   * form) — distinct from the API `baseUrl` the key encodes. The interactive
+   * sign-in popup/redirect targets this; the silent warm-hop probe still hits the
+   * API. When unset, sign-in falls back to the API's `/v1/idp/authorize` (for
+   * deployments where the API host also serves the login page).
+   */
+  signInUrl?: string;
   /** Defaults to runtime auto-detection. */
   context?: RuntimeContext;
 }
@@ -35,6 +43,8 @@ interface ResolvedConfig {
   kind: KeyKind;
   env: KeyEnv;
   baseUrl: string;
+  /** Hosted sign-in page URL (see ResolveConfigInput.signInUrl); undefined = use the API. */
+  signInUrl?: string;
   context: RuntimeContext;
 }
 declare function resolveConfig(input: ResolveConfigInput): ResolvedConfig;
@@ -193,11 +203,24 @@ interface TokenSet {
   /** Epoch milliseconds when the access token expires, per the server. */
   accessTokenExpiresAt: number;
 }
+/**
+ * The verified identity a session carries. Per ADR-0006 this holds identity plus a **bounded
+ * display subset** — enough for a signed-in user surface — and never bulk authorization data
+ * (module graphs, team lists). Claims are sealed into a ~4KB cookie that fails by being
+ * silently dropped, so a field earns its place by being bounded and small, not by being useful.
+ *
+ * The display fields are optional: they are derived defensively from whatever the platform
+ * returns, and their absence is normal, not an error.
+ */
 interface SessionClaims {
   userId: string;
   organizationId?: string;
   roles: readonly string[];
   permissions: readonly string[];
+  /** Best available human label: full name → username → email. */
+  displayName?: string;
+  email?: string;
+  avatarUrl?: string;
 }
 interface Session {
   claims: SessionClaims;
@@ -380,8 +403,41 @@ declare const ENDPOINTS: {
   readonly authorize: "/v1/idp/authorize";
   readonly token: "/v1/idp/token";
   readonly refresh: "/v1/auth/refresh-token";
+  /**
+   * Ecosystem (SSO) logout. Resolves the session from the *browser's* ecosystem cookie,
+   * so it only revokes when called from a context that carries it — a top-level hop.
+   * A server-to-server call reaches it without the cookie and revokes nothing (it still
+   * answers 200), which is why BFF sign-out must use the bearer-authenticated pair below.
+   */
   readonly logout: "/v1/idp/logout";
+  /**
+   * Bearer-authenticated revocation: the access token identifies the session, so these
+   * work from any context that holds one — notably the BFF, where the token is sealed in
+   * the session cookie and no browser cookie reaches poly-auth. `logout` revokes this
+   * session; `logoutAll` revokes every session for the user.
+   */
+  readonly authLogout: "/v1/auth/logout";
+  readonly authLogoutAll: "/v1/auth/logout-all";
   readonly orgResolve: "/v1/idp/org-resolve";
+  /**
+   * Completes the admin temp-password flow: the user signed in with a temporary
+   * password, poly-auth answered `403 {userPasswordSet, userId}`, and this sets
+   * the real one. Only succeeds while the account is flagged `mustChangePassword`.
+   */
+  readonly setPassword: "/v1/auth/set-password";
+  /**
+   * Server-mediated self-service reset (poly-x v5 / F040). `forgotPassword` starts it
+   * — always a uniform 202, the token is emailed to the mailbox, never returned.
+   * `resetPassword` redeems that opaque token single-use and sets the new password.
+   */
+  readonly forgotPassword: "/v1/idp/forgot-password";
+  readonly resetPassword: "/v1/idp/reset-password";
+  /**
+   * Public, pk_-scoped login-page branding (F037 / FR-BRND). GET with `client_id`
+   * (+ optional `organizationCode`) → the bounded `{ tokens }` set. Never 5xx's /
+   * never blocks login; the SDK falls back to its built-in defaults on any failure.
+   */
+  readonly branding: "/v1/idp/branding";
 };
 //#endregion
 //#region src/auth/outcomes.d.ts
@@ -411,10 +467,50 @@ type AuthorizeOutcome = {
   type: "login_required";
 };
 declare function parseAuthorizeOutcome(status: number, body: unknown): AuthorizeOutcome;
+/**
+ * Outcome of a PASSWORD authorize (`POST /idp/authorize` with credentials) — the
+ * embedded `<SignIn/>` flow. Distinguishes invalid-credentials and the
+ * must-set-password step from the membership outcomes (the GET warm-hop parser
+ * collapses those into login_required).
+ */
+type PasswordAuthOutcome = {
+  type: "authorized";
+  code: string;
+  state: string;
+  redirectUri?: string;
+} | {
+  type: "select_tenant";
+  state: string;
+  tenants: TenantOption[];
+} | {
+  type: "invalid_credentials";
+} | {
+  type: "password_change_required";
+  userId: string;
+  ticket?: string;
+} | {
+  type: "no_access";
+};
+declare function parsePasswordOutcome(status: number, body: unknown): PasswordAuthOutcome;
+/**
+ * The outcome of redeeming a reset token (`POST /idp/reset-password`, F040):
+ * `ok` on success, `weak_password` when it fails the platform floor, and a
+ * uniform `invalid_or_expired` for an unknown/used/expired token (the backend
+ * does not distinguish unknown from expired to the caller).
+ */
+type PasswordResetOutcome = "ok" | "weak_password" | "invalid_or_expired";
+declare function parseResetOutcome(status: number, body: unknown): PasswordResetOutcome;
 //#endregion
 //#region src/auth/normalize.d.ts
 declare function decodeJwtExp(token: string): number | null;
-/** `POST /idp/token` → StoredSession. Claims mapping is minimal in v1 (userId + org); AUTHZ populates roles/permissions later. */
+/**
+ * `POST /idp/token` → StoredSession. Claims carry identity plus the bounded display subset
+ * (ADR-0006); AUTHZ populates roles/permissions later.
+ *
+ * `organizationId` comes from the exchange's `tenantId`, never from the user document: a
+ * cross-membership login resolves a tenant that is deliberately *not* the user's home
+ * organization, and reading it off the user would silently sign them into the wrong one.
+ */
 declare function normalizeExchange(body: unknown, now: number): StoredSession;
 /** `POST /auth/refresh-token` → StoredSession. No user in the response, so claims carry forward. */
 declare function normalizeRefresh(body: unknown, current: StoredSession, now: number): StoredSession;
@@ -462,18 +558,112 @@ interface ExchangeCodeParams {
   codeVerifier: string;
   redirectUri: string;
 }
+interface SetPasswordParams {
+  userId: string;
+  newPassword: string;
+  confirmPassword: string;
+  /**
+   * Single-use proof-of-possession ticket from the `password_change_required`
+   * outcome. When present the platform trusts the ticket over `userId`; when the
+   * backend enforces tickets, it's required. Omit against older backends.
+   */
+  ticket?: string;
+}
+interface AuthorizeWithPasswordParams {
+  email: string;
+  password: string;
+  redirectUri: string;
+  state: string;
+  challenge: string;
+  organizationCode?: string;
+  /** Set on the re-attempt after the user picks a workspace (select_tenant). */
+  tenantId?: string;
+}
+/** The bounded login-page branding token set (FR-BRND-1). Every field is optional. */
+interface BrandingTokens {
+  displayName?: string;
+  logoUrl?: string;
+  primaryColor?: string;
+  backgroundColor?: string;
+}
+interface FetchBrandingParams {
+  /** Refine app-level branding with an org's when the org is already known. */
+  organizationCode?: string;
+}
 declare class AuthClient {
   private readonly config;
   private readonly transport;
   private readonly clock;
   constructor(options: AuthClientOptions);
+  private appendAuthorizeParams;
+  /** The API `GET /v1/idp/authorize` URL — used for the silent warm-hop probe. */
   buildAuthorizeUrl(params: BuildAuthorizeUrlParams): string;
+  /**
+   * The URL the interactive sign-in popup/redirect opens. Targets the HOSTED login
+   * PAGE (`config.signInUrl`) — which renders the form, POSTs the API, and redirects
+   * to `redirect_uri` with the code. Falls back to the API authorize URL when no
+   * `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. */
   completeAuthorize(params: BuildAuthorizeUrlParams): Promise<AuthorizeOutcome>;
+  /**
+   * The embedded `<SignIn/>` credential flow (D2b): POST `/idp/authorize` with
+   * email/password + PKCE. On `authorized` the caller exchanges the returned
+   * `code` (server-side, via the BFF) for a session — no redirect to a hosted
+   * login page. Creds live only for the duration of this request; the SDK never
+   * stores them. 5xx surfaces as a typed error; every other status is a typed
+   * outcome the UI branches on.
+   */
+  authorizeWithPassword(params: AuthorizeWithPasswordParams): Promise<PasswordAuthOutcome>;
+  /**
+   * Set the real password for a user the platform has flagged `mustChangePassword`
+   * (the admin temp-password flow). Call this only after `authorizeWithPassword`
+   * has returned `password_change_required` for that same user — that response IS
+   * the proof the caller knows the temporary password.
+   */
+  setPassword(params: SetPasswordParams): Promise<void>;
+  /**
+   * Start a server-mediated self-service reset (F040). POSTs the email + this app's
+   * publishable key; the backend resolves the account, mints a single-use token, and
+   * emails the link ITSELF — nothing comes back but a uniform 202. Resolves on success;
+   * a 4xx (e.g. a misconfigured key) surfaces as a typed error for the developer.
+   */
+  requestPasswordReset(params: {
+    email: string;
+  }): Promise<void>;
+  /**
+   * Redeem a reset token (the opaque value from the emailed link) single-use and set
+   * the new password. Returns a typed outcome the UI branches on; only a 5xx throws.
+   */
+  resetPassword(params: {
+    token: string;
+    newPassword: string;
+  }): Promise<PasswordResetOutcome>;
   exchangeCode(params: ExchangeCodeParams): Promise<StoredSession>;
+  /**
+   * Fetch this app's login-page branding (public, pk_-scoped). NEVER throws and never
+   * blocks the sign-in form: any non-200, malformed body, or network failure resolves
+   * to an empty token set so the caller keeps its built-in defaults (FR-BRND-3).
+   */
+  fetchBranding(params?: FetchBrandingParams): Promise<BrandingTokens>;
   /** The `RefreshTokens` function the SessionEngine (F003) injects. */
   createRefresher(): RefreshTokens;
+  /**
+   * Ecosystem logout — only revokes when the caller carries the browser's ecosystem
+   * cookie (a top-level hop). From a server-to-server context it clears nothing and
+   * still answers 200; use `revokeSession` there.
+   */
   logout(scope?: "device" | "everywhere"): Promise<void>;
+  /**
+   * Revoke a session using the access token as proof — the only logout that works
+   * server-side, where no browser cookie reaches poly-auth. `device` ends this session;
+   * `everywhere` ends every session for the user (FR-SSO-5).
+   *
+   * The token goes in the Authorization header and nowhere else: repeating it in the
+   * body would only widen where it can leak.
+   */
+  revokeSession(accessToken: string, scope?: "device" | "everywhere"): Promise<void>;
   resolveOrg(email: string): Promise<{
     resolved: boolean;
     organizationCode?: string;
@@ -488,4 +678,4 @@ declare class AuthClient {
 declare const PACKAGE_NAME = "@poly-x/core";
 declare const version = "0.0.0";
 //#endregion
-export { AuthClient, type AuthClientOptions, type AuthorizeOutcome, type BuildAuthorizeUrlParams, type Clock, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, ENDPOINTS, type ExchangeCodeParams, 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 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 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, parsePolyXKey, 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, 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 };

package/dist/index.d.mts

@@ -27,6 +27,14 @@ interface ResolveConfigInput {
   key: string;
   /** Wins over the key-embedded host. */
   baseUrl?: string;
+  /**
+   * URL of the HOSTED sign-in page (the account portal that renders the login
+   * form) — distinct from the API `baseUrl` the key encodes. The interactive
+   * sign-in popup/redirect targets this; the silent warm-hop probe still hits the
+   * API. When unset, sign-in falls back to the API's `/v1/idp/authorize` (for
+   * deployments where the API host also serves the login page).
+   */
+  signInUrl?: string;
   /** Defaults to runtime auto-detection. */
   context?: RuntimeContext;
 }
@@ -35,6 +43,8 @@ interface ResolvedConfig {
   kind: KeyKind;
   env: KeyEnv;
   baseUrl: string;
+  /** Hosted sign-in page URL (see ResolveConfigInput.signInUrl); undefined = use the API. */
+  signInUrl?: string;
   context: RuntimeContext;
 }
 declare function resolveConfig(input: ResolveConfigInput): ResolvedConfig;
@@ -193,11 +203,24 @@ interface TokenSet {
   /** Epoch milliseconds when the access token expires, per the server. */
   accessTokenExpiresAt: number;
 }
+/**
+ * The verified identity a session carries. Per ADR-0006 this holds identity plus a **bounded
+ * display subset** — enough for a signed-in user surface — and never bulk authorization data
+ * (module graphs, team lists). Claims are sealed into a ~4KB cookie that fails by being
+ * silently dropped, so a field earns its place by being bounded and small, not by being useful.
+ *
+ * The display fields are optional: they are derived defensively from whatever the platform
+ * returns, and their absence is normal, not an error.
+ */
 interface SessionClaims {
   userId: string;
   organizationId?: string;
   roles: readonly string[];
   permissions: readonly string[];
+  /** Best available human label: full name → username → email. */
+  displayName?: string;
+  email?: string;
+  avatarUrl?: string;
 }
 interface Session {
   claims: SessionClaims;
@@ -380,8 +403,41 @@ declare const ENDPOINTS: {
   readonly authorize: "/v1/idp/authorize";
   readonly token: "/v1/idp/token";
   readonly refresh: "/v1/auth/refresh-token";
+  /**
+   * Ecosystem (SSO) logout. Resolves the session from the *browser's* ecosystem cookie,
+   * so it only revokes when called from a context that carries it — a top-level hop.
+   * A server-to-server call reaches it without the cookie and revokes nothing (it still
+   * answers 200), which is why BFF sign-out must use the bearer-authenticated pair below.
+   */
   readonly logout: "/v1/idp/logout";
+  /**
+   * Bearer-authenticated revocation: the access token identifies the session, so these
+   * work from any context that holds one — notably the BFF, where the token is sealed in
+   * the session cookie and no browser cookie reaches poly-auth. `logout` revokes this
+   * session; `logoutAll` revokes every session for the user.
+   */
+  readonly authLogout: "/v1/auth/logout";
+  readonly authLogoutAll: "/v1/auth/logout-all";
   readonly orgResolve: "/v1/idp/org-resolve";
+  /**
+   * Completes the admin temp-password flow: the user signed in with a temporary
+   * password, poly-auth answered `403 {userPasswordSet, userId}`, and this sets
+   * the real one. Only succeeds while the account is flagged `mustChangePassword`.
+   */
+  readonly setPassword: "/v1/auth/set-password";
+  /**
+   * Server-mediated self-service reset (poly-x v5 / F040). `forgotPassword` starts it
+   * — always a uniform 202, the token is emailed to the mailbox, never returned.
+   * `resetPassword` redeems that opaque token single-use and sets the new password.
+   */
+  readonly forgotPassword: "/v1/idp/forgot-password";
+  readonly resetPassword: "/v1/idp/reset-password";
+  /**
+   * Public, pk_-scoped login-page branding (F037 / FR-BRND). GET with `client_id`
+   * (+ optional `organizationCode`) → the bounded `{ tokens }` set. Never 5xx's /
+   * never blocks login; the SDK falls back to its built-in defaults on any failure.
+   */
+  readonly branding: "/v1/idp/branding";
 };
 //#endregion
 //#region src/auth/outcomes.d.ts
@@ -411,10 +467,50 @@ type AuthorizeOutcome = {
   type: "login_required";
 };
 declare function parseAuthorizeOutcome(status: number, body: unknown): AuthorizeOutcome;
+/**
+ * Outcome of a PASSWORD authorize (`POST /idp/authorize` with credentials) — the
+ * embedded `<SignIn/>` flow. Distinguishes invalid-credentials and the
+ * must-set-password step from the membership outcomes (the GET warm-hop parser
+ * collapses those into login_required).
+ */
+type PasswordAuthOutcome = {
+  type: "authorized";
+  code: string;
+  state: string;
+  redirectUri?: string;
+} | {
+  type: "select_tenant";
+  state: string;
+  tenants: TenantOption[];
+} | {
+  type: "invalid_credentials";
+} | {
+  type: "password_change_required";
+  userId: string;
+  ticket?: string;
+} | {
+  type: "no_access";
+};
+declare function parsePasswordOutcome(status: number, body: unknown): PasswordAuthOutcome;
+/**
+ * The outcome of redeeming a reset token (`POST /idp/reset-password`, F040):
+ * `ok` on success, `weak_password` when it fails the platform floor, and a
+ * uniform `invalid_or_expired` for an unknown/used/expired token (the backend
+ * does not distinguish unknown from expired to the caller).
+ */
+type PasswordResetOutcome = "ok" | "weak_password" | "invalid_or_expired";
+declare function parseResetOutcome(status: number, body: unknown): PasswordResetOutcome;
 //#endregion
 //#region src/auth/normalize.d.ts
 declare function decodeJwtExp(token: string): number | null;
-/** `POST /idp/token` → StoredSession. Claims mapping is minimal in v1 (userId + org); AUTHZ populates roles/permissions later. */
+/**
+ * `POST /idp/token` → StoredSession. Claims carry identity plus the bounded display subset
+ * (ADR-0006); AUTHZ populates roles/permissions later.
+ *
+ * `organizationId` comes from the exchange's `tenantId`, never from the user document: a
+ * cross-membership login resolves a tenant that is deliberately *not* the user's home
+ * organization, and reading it off the user would silently sign them into the wrong one.
+ */
 declare function normalizeExchange(body: unknown, now: number): StoredSession;
 /** `POST /auth/refresh-token` → StoredSession. No user in the response, so claims carry forward. */
 declare function normalizeRefresh(body: unknown, current: StoredSession, now: number): StoredSession;
@@ -462,18 +558,112 @@ interface ExchangeCodeParams {
   codeVerifier: string;
   redirectUri: string;
 }
+interface SetPasswordParams {
+  userId: string;
+  newPassword: string;
+  confirmPassword: string;
+  /**
+   * Single-use proof-of-possession ticket from the `password_change_required`
+   * outcome. When present the platform trusts the ticket over `userId`; when the
+   * backend enforces tickets, it's required. Omit against older backends.
+   */
+  ticket?: string;
+}
+interface AuthorizeWithPasswordParams {
+  email: string;
+  password: string;
+  redirectUri: string;
+  state: string;
+  challenge: string;
+  organizationCode?: string;
+  /** Set on the re-attempt after the user picks a workspace (select_tenant). */
+  tenantId?: string;
+}
+/** The bounded login-page branding token set (FR-BRND-1). Every field is optional. */
+interface BrandingTokens {
+  displayName?: string;
+  logoUrl?: string;
+  primaryColor?: string;
+  backgroundColor?: string;
+}
+interface FetchBrandingParams {
+  /** Refine app-level branding with an org's when the org is already known. */
+  organizationCode?: string;
+}
 declare class AuthClient {
   private readonly config;
   private readonly transport;
   private readonly clock;
   constructor(options: AuthClientOptions);
+  private appendAuthorizeParams;
+  /** The API `GET /v1/idp/authorize` URL — used for the silent warm-hop probe. */
   buildAuthorizeUrl(params: BuildAuthorizeUrlParams): string;
+  /**
+   * The URL the interactive sign-in popup/redirect opens. Targets the HOSTED login
+   * PAGE (`config.signInUrl`) — which renders the form, POSTs the API, and redirects
+   * to `redirect_uri` with the code. Falls back to the API authorize URL when no
+   * `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. */
   completeAuthorize(params: BuildAuthorizeUrlParams): Promise<AuthorizeOutcome>;
+  /**
+   * The embedded `<SignIn/>` credential flow (D2b): POST `/idp/authorize` with
+   * email/password + PKCE. On `authorized` the caller exchanges the returned
+   * `code` (server-side, via the BFF) for a session — no redirect to a hosted
+   * login page. Creds live only for the duration of this request; the SDK never
+   * stores them. 5xx surfaces as a typed error; every other status is a typed
+   * outcome the UI branches on.
+   */
+  authorizeWithPassword(params: AuthorizeWithPasswordParams): Promise<PasswordAuthOutcome>;
+  /**
+   * Set the real password for a user the platform has flagged `mustChangePassword`
+   * (the admin temp-password flow). Call this only after `authorizeWithPassword`
+   * has returned `password_change_required` for that same user — that response IS
+   * the proof the caller knows the temporary password.
+   */
+  setPassword(params: SetPasswordParams): Promise<void>;
+  /**
+   * Start a server-mediated self-service reset (F040). POSTs the email + this app's
+   * publishable key; the backend resolves the account, mints a single-use token, and
+   * emails the link ITSELF — nothing comes back but a uniform 202. Resolves on success;
+   * a 4xx (e.g. a misconfigured key) surfaces as a typed error for the developer.
+   */
+  requestPasswordReset(params: {
+    email: string;
+  }): Promise<void>;
+  /**
+   * Redeem a reset token (the opaque value from the emailed link) single-use and set
+   * the new password. Returns a typed outcome the UI branches on; only a 5xx throws.
+   */
+  resetPassword(params: {
+    token: string;
+    newPassword: string;
+  }): Promise<PasswordResetOutcome>;
   exchangeCode(params: ExchangeCodeParams): Promise<StoredSession>;
+  /**
+   * Fetch this app's login-page branding (public, pk_-scoped). NEVER throws and never
+   * blocks the sign-in form: any non-200, malformed body, or network failure resolves
+   * to an empty token set so the caller keeps its built-in defaults (FR-BRND-3).
+   */
+  fetchBranding(params?: FetchBrandingParams): Promise<BrandingTokens>;
   /** The `RefreshTokens` function the SessionEngine (F003) injects. */
   createRefresher(): RefreshTokens;
+  /**
+   * Ecosystem logout — only revokes when the caller carries the browser's ecosystem
+   * cookie (a top-level hop). From a server-to-server context it clears nothing and
+   * still answers 200; use `revokeSession` there.
+   */
   logout(scope?: "device" | "everywhere"): Promise<void>;
+  /**
+   * Revoke a session using the access token as proof — the only logout that works
+   * server-side, where no browser cookie reaches poly-auth. `device` ends this session;
+   * `everywhere` ends every session for the user (FR-SSO-5).
+   *
+   * The token goes in the Authorization header and nowhere else: repeating it in the
+   * body would only widen where it can leak.
+   */
+  revokeSession(accessToken: string, scope?: "device" | "everywhere"): Promise<void>;
   resolveOrg(email: string): Promise<{
     resolved: boolean;
     organizationCode?: string;
@@ -488,4 +678,4 @@ declare class AuthClient {
 declare const PACKAGE_NAME = "@poly-x/core";
 declare const version = "0.0.0";
 //#endregion
-export { AuthClient, type AuthClientOptions, type AuthorizeOutcome, type BuildAuthorizeUrlParams, type Clock, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, ENDPOINTS, type ExchangeCodeParams, 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 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 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, parsePolyXKey, 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, 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 };

package/dist/index.mjs

@@ -166,11 +166,21 @@ function resolveConfig(input) {
 		}
 		baseUrl = normalizeBaseUrl(input.baseUrl);
 	} else baseUrl = `https://${normalizeBaseUrl(key.host)}`;
+	let signInUrl;
+	if (input.signInUrl !== void 0) {
+		try {
+			new URL(input.signInUrl);
+		} catch {
+			throw new PolyXConfigError("The signInUrl is not a valid URL.", { code: "SIGN_IN_URL_INVALID" });
+		}
+		signInUrl = normalizeBaseUrl(input.signInUrl);
+	}
 	return {
 		key,
 		kind: key.kind,
 		env: key.env,
 		baseUrl,
+		signInUrl,
 		context
 	};
 }
@@ -182,7 +192,16 @@ function resolveConfig(input) {
 * against poly-auth/src/api/constants/auth-responses.ts (2026-07-06). Unknown
 * shapes become a typed UNRECOGNIZED_RESPONSE — never a guess.
 */
-const REVOKED_CODES = /* @__PURE__ */ new Set(["REFRESH_TOKEN_REUSE", "SESSION_REVOKED"]);
+/**
+* Terminal: the session is gone and no retry brings it back. The platform revokes every session
+* for a user on permission change, suspension, and password reset — `SESSION_REVOKED` for the
+* revocation itself, `SESSION_MISMATCH` when the presented token no longer matches its session.
+*/
+const REVOKED_CODES = /* @__PURE__ */ new Set([
+	"REFRESH_TOKEN_REUSE",
+	"SESSION_REVOKED",
+	"SESSION_MISMATCH"
+]);
 const EXPIRED_CODES = /* @__PURE__ */ new Set([
 	"SESSION_EXPIRED",
 	"REFRESH_TOKEN_REQUIRED",
@@ -697,8 +716,41 @@ const ENDPOINTS = {
 	authorize: "/v1/idp/authorize",
 	token: "/v1/idp/token",
 	refresh: "/v1/auth/refresh-token",
+	/**
+	* Ecosystem (SSO) logout. Resolves the session from the *browser's* ecosystem cookie,
+	* so it only revokes when called from a context that carries it — a top-level hop.
+	* A server-to-server call reaches it without the cookie and revokes nothing (it still
+	* answers 200), which is why BFF sign-out must use the bearer-authenticated pair below.
+	*/
 	logout: "/v1/idp/logout",
-	orgResolve: "/v1/idp/org-resolve"
+	/**
+	* Bearer-authenticated revocation: the access token identifies the session, so these
+	* work from any context that holds one — notably the BFF, where the token is sealed in
+	* the session cookie and no browser cookie reaches poly-auth. `logout` revokes this
+	* session; `logoutAll` revokes every session for the user.
+	*/
+	authLogout: "/v1/auth/logout",
+	authLogoutAll: "/v1/auth/logout-all",
+	orgResolve: "/v1/idp/org-resolve",
+	/**
+	* Completes the admin temp-password flow: the user signed in with a temporary
+	* password, poly-auth answered `403 {userPasswordSet, userId}`, and this sets
+	* the real one. Only succeeds while the account is flagged `mustChangePassword`.
+	*/
+	setPassword: "/v1/auth/set-password",
+	/**
+	* Server-mediated self-service reset (poly-x v5 / F040). `forgotPassword` starts it
+	* — always a uniform 202, the token is emailed to the mailbox, never returned.
+	* `resetPassword` redeems that opaque token single-use and sets the new password.
+	*/
+	forgotPassword: "/v1/idp/forgot-password",
+	resetPassword: "/v1/idp/reset-password",
+	/**
+	* Public, pk_-scoped login-page branding (F037 / FR-BRND). GET with `client_id`
+	* (+ optional `organizationCode`) → the bounded `{ tokens }` set. Never 5xx's /
+	* never blocks login; the SDK falls back to its built-in defaults on any failure.
+	*/
+	branding: "/v1/idp/branding"
 };
 //#endregion
 //#region src/auth/outcomes.ts
@@ -736,6 +788,33 @@ function parseAuthorizeOutcome(status, body) {
 	if (statusField === "login_required" || b.code === "LOGIN_REQUIRED") return { type: "login_required" };
 	return { type: "login_required" };
 }
+function parsePasswordOutcome(status, body) {
+	const b = asRecord$1(body);
+	const statusField = typeof b.status === "string" ? b.status : void 0;
+	if (statusField === "authorized" && typeof b.code === "string") return {
+		type: "authorized",
+		code: b.code,
+		state: typeof b.state === "string" ? b.state : "",
+		redirectUri: typeof b.redirectUri === "string" ? b.redirectUri : void 0
+	};
+	if (statusField === "select_tenant") return {
+		type: "select_tenant",
+		state: typeof b.state === "string" ? b.state : "",
+		tenants: parseTenants(b.tenants)
+	};
+	if (status === 403 && b.userPasswordSet === true && typeof b.userId === "string") return {
+		type: "password_change_required",
+		userId: b.userId,
+		ticket: typeof b.ticket === "string" ? b.ticket : void 0
+	};
+	if (status === 403) return { type: "no_access" };
+	return { type: "invalid_credentials" };
+}
+function parseResetOutcome(status, body) {
+	if (status === 200) return "ok";
+	if (asRecord$1(body).status === "weak_password") return "weak_password";
+	return "invalid_or_expired";
+}
 //#endregion
 //#region src/auth/normalize.ts
 const FALLBACK_TTL_MS = 5 * 6e4;
@@ -761,7 +840,35 @@ function toTokenSet(accessToken, refreshToken, now) {
 function asRecord(value) {
 	return value && typeof value === "object" ? value : {};
 }
-/** `POST /idp/token` → StoredSession. Claims mapping is minimal in v1 (userId + org); AUTHZ populates roles/permissions later. */
+/**
+* Display-claim caps (ADR-0006). These values are user-controlled and unbounded in the
+* platform's schema, and they ride in a sealed ~4KB cookie whose failure mode is the browser
+* silently dropping it. Cap at the boundary rather than trusting the input.
+*/
+const MAX_DISPLAY_NAME = 128;
+const MAX_AVATAR_URL = 512;
+/** A non-blank string, trimmed and capped — otherwise undefined. The shim never guesses. */
+function displayString(value, max) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return void 0;
+	return trimmed.slice(0, max);
+}
+/**
+* The best human label the token response can give us: full name, else username, else email.
+* Each part is checked independently so a user with only one of them never renders "undefined".
+*/
+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);
+}
+/**
+* `POST /idp/token` → StoredSession. Claims carry identity plus the bounded display subset
+* (ADR-0006); AUTHZ populates roles/permissions later.
+*
+* `organizationId` comes from the exchange's `tenantId`, never from the user document: a
+* cross-membership login resolves a tenant that is deliberately *not* the user's home
+* organization, and reading it off the user would silently sign them into the wrong one.
+*/
 function normalizeExchange(body, now) {
 	const data = asRecord(asRecord(body).data);
 	const user = asRecord(data.user);
@@ -771,7 +878,10 @@ function normalizeExchange(body, now) {
 		userId,
 		organizationId: data.tenantId != null ? String(data.tenantId) : void 0,
 		roles: [],
-		permissions: []
+		permissions: [],
+		displayName: deriveDisplayName(user),
+		email: displayString(user.email, MAX_DISPLAY_NAME),
+		avatarUrl: displayString(user.profilePicture, MAX_AVATAR_URL)
 	};
 	return {
 		tokens: toTokenSet(String(data.accessToken ?? ""), stringOrUndefined(data.refreshToken), now),
@@ -814,10 +924,9 @@ var AuthClient = class {
 		this.transport = options.transport;
 		this.clock = options.clock ?? new SystemClock();
 	}
-	buildAuthorizeUrl(params) {
-		const url = new URL(this.config.baseUrl + ENDPOINTS.authorize);
+	appendAuthorizeParams(url, params) {
 		url.searchParams.set("response_type", "code");
-		url.searchParams.set("client", this.config.key.raw);
+		url.searchParams.set("client_id", this.config.key.raw);
 		url.searchParams.set("redirect_uri", params.redirectUri);
 		url.searchParams.set("state", params.state);
 		url.searchParams.set("code_challenge", params.challenge);
@@ -826,6 +935,20 @@ var AuthClient = class {
 		if (params.prompt) url.searchParams.set("prompt", params.prompt);
 		return url.toString();
 	}
+	/** The API `GET /v1/idp/authorize` URL — used for the silent warm-hop probe. */
+	buildAuthorizeUrl(params) {
+		return this.appendAuthorizeParams(new URL(this.config.baseUrl + ENDPOINTS.authorize), params);
+	}
+	/**
+	* The URL the interactive sign-in popup/redirect opens. Targets the HOSTED login
+	* PAGE (`config.signInUrl`) — which renders the form, POSTs the API, and redirects
+	* to `redirect_uri` with the code. Falls back to the API authorize URL when no
+	* `signInUrl` is configured (deployments where the API host serves the page).
+	*/
+	buildSignInUrl(params) {
+		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. */
 	async completeAuthorize(params) {
 		const response = await this.transport.request({
@@ -835,6 +958,86 @@ var AuthClient = class {
 		if (response.status >= 500) throw this.toError(response);
 		return parseAuthorizeOutcome(response.status, response.body);
 	}
+	/**
+	* The embedded `<SignIn/>` credential flow (D2b): POST `/idp/authorize` with
+	* email/password + PKCE. On `authorized` the caller exchanges the returned
+	* `code` (server-side, via the BFF) for a session — no redirect to a hosted
+	* login page. Creds live only for the duration of this request; the SDK never
+	* stores them. 5xx surfaces as a typed error; every other status is a typed
+	* outcome the UI branches on.
+	*/
+	async authorizeWithPassword(params) {
+		const response = await this.transport.request({
+			method: "POST",
+			url: this.config.baseUrl + ENDPOINTS.authorize,
+			body: {
+				response_type: "code",
+				client_id: this.config.key.raw,
+				redirect_uri: params.redirectUri,
+				state: params.state,
+				code_challenge: params.challenge,
+				code_challenge_method: "S256",
+				email: params.email,
+				password: params.password,
+				...params.organizationCode ? { organizationCode: params.organizationCode } : {},
+				...params.tenantId ? { tenantId: params.tenantId } : {}
+			}
+		});
+		if (response.status >= 500) throw this.toError(response);
+		return parsePasswordOutcome(response.status, response.body);
+	}
+	/**
+	* Set the real password for a user the platform has flagged `mustChangePassword`
+	* (the admin temp-password flow). Call this only after `authorizeWithPassword`
+	* has returned `password_change_required` for that same user — that response IS
+	* the proof the caller knows the temporary password.
+	*/
+	async setPassword(params) {
+		const response = await this.transport.request({
+			method: "PATCH",
+			url: this.config.baseUrl + ENDPOINTS.setPassword,
+			body: {
+				userId: params.userId,
+				newPassword: params.newPassword,
+				confirmPassword: params.confirmPassword,
+				...params.ticket ? { ticket: params.ticket } : {}
+			}
+		});
+		if (response.status !== 200) throw this.toError(response);
+	}
+	/**
+	* Start a server-mediated self-service reset (F040). POSTs the email + this app's
+	* publishable key; the backend resolves the account, mints a single-use token, and
+	* emails the link ITSELF — nothing comes back but a uniform 202. Resolves on success;
+	* a 4xx (e.g. a misconfigured key) surfaces as a typed error for the developer.
+	*/
+	async requestPasswordReset(params) {
+		const response = await this.transport.request({
+			method: "POST",
+			url: this.config.baseUrl + ENDPOINTS.forgotPassword,
+			body: {
+				email: params.email,
+				client_id: this.config.key.raw
+			}
+		});
+		if (response.status >= 400) throw this.toError(response);
+	}
+	/**
+	* Redeem a reset token (the opaque value from the emailed link) single-use and set
+	* the new password. Returns a typed outcome the UI branches on; only a 5xx throws.
+	*/
+	async resetPassword(params) {
+		const response = await this.transport.request({
+			method: "POST",
+			url: this.config.baseUrl + ENDPOINTS.resetPassword,
+			body: {
+				token: params.token,
+				newPassword: params.newPassword
+			}
+		});
+		if (response.status >= 500) throw this.toError(response);
+		return parseResetOutcome(response.status, response.body);
+	}
 	async exchangeCode(params) {
 		const response = await this.transport.request({
 			method: "POST",
@@ -844,12 +1047,33 @@ var AuthClient = class {
 				code: params.code,
 				code_verifier: params.codeVerifier,
 				redirect_uri: params.redirectUri,
-				client: this.config.key.raw
+				client_id: this.config.key.raw
 			}
 		});
 		if (response.status !== 200) throw this.toError(response);
 		return normalizeExchange(response.body, this.clock.now());
 	}
+	/**
+	* Fetch this app's login-page branding (public, pk_-scoped). NEVER throws and never
+	* blocks the sign-in form: any non-200, malformed body, or network failure resolves
+	* to an empty token set so the caller keeps its built-in defaults (FR-BRND-3).
+	*/
+	async fetchBranding(params = {}) {
+		try {
+			const url = new URL(this.config.baseUrl + ENDPOINTS.branding);
+			url.searchParams.set("client_id", this.config.key.raw);
+			if (params.organizationCode) url.searchParams.set("organizationCode", params.organizationCode);
+			const response = await this.transport.request({
+				method: "GET",
+				url: url.toString()
+			});
+			if (response.status !== 200) return {};
+			const tokens = response.body?.tokens;
+			return tokens && typeof tokens === "object" ? tokens : {};
+		} catch {
+			return {};
+		}
+	}
 	/** The `RefreshTokens` function the SessionEngine (F003) injects. */
 	createRefresher() {
 		return async (current) => {
@@ -862,6 +1086,11 @@ var AuthClient = class {
 			return normalizeRefresh(response.body, current, this.clock.now());
 		};
 	}
+	/**
+	* Ecosystem logout — only revokes when the caller carries the browser's ecosystem
+	* cookie (a top-level hop). From a server-to-server context it clears nothing and
+	* still answers 200; use `revokeSession` there.
+	*/
 	async logout(scope = "device") {
 		const response = await this.transport.request({
 			method: "POST",
@@ -870,6 +1099,22 @@ var AuthClient = class {
 		});
 		if (response.status >= 400) throw this.toError(response);
 	}
+	/**
+	* Revoke a session using the access token as proof — the only logout that works
+	* server-side, where no browser cookie reaches poly-auth. `device` ends this session;
+	* `everywhere` ends every session for the user (FR-SSO-5).
+	*
+	* The token goes in the Authorization header and nowhere else: repeating it in the
+	* body would only widen where it can leak.
+	*/
+	async revokeSession(accessToken, scope = "device") {
+		const response = await this.transport.request({
+			method: "POST",
+			url: this.config.baseUrl + (scope === "everywhere" ? ENDPOINTS.authLogoutAll : ENDPOINTS.authLogout),
+			headers: { Authorization: `Bearer ${accessToken}` }
+		});
+		if (response.status >= 400) throw this.toError(response);
+	}
 	async resolveOrg(email) {
 		const response = await this.transport.request({
 			method: "POST",
@@ -899,4 +1144,4 @@ var AuthClient = class {
 const PACKAGE_NAME = "@poly-x/core";
 const version = "0.0.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, parsePolyXKey, 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, 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poly-x/core",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.10",
   "description": "Framework-agnostic core of the PolyX SDK",
   "license": "MIT",
   "type": "module",