@poly-x/core 0.1.0-alpha.8 → 0.1.0

package/dist/index.cjs

@@ -193,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",
@@ -708,7 +717,21 @@ 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",
+	/**
+	* 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
@@ -722,7 +745,13 @@ const ENDPOINTS = {
 	* `resetPassword` redeems that opaque token single-use and sets the new password.
 	*/
 	forgotPassword: "/v1/idp/forgot-password",
-	resetPassword: "/v1/idp/reset-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
@@ -812,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);
@@ -822,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),
@@ -983,6 +1043,7 @@ var AuthClient = class {
 		const response = await this.transport.request({
 			method: "POST",
 			url: this.config.baseUrl + ENDPOINTS.token,
+			...params.forwardedHeaders ? { headers: params.forwardedHeaders } : {},
 			body: {
 				grant_type: "authorization_code",
 				code: params.code,
@@ -994,6 +1055,27 @@ var AuthClient = class {
 		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) => {
@@ -1006,6 +1088,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",
@@ -1014,6 +1101,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",

package/dist/index.d.cts

@@ -203,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;
@@ -390,7 +403,21 @@ 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
@@ -405,6 +432,12 @@ declare const ENDPOINTS: {
    */
   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
@@ -470,7 +503,14 @@ declare function parseResetOutcome(status: number, body: unknown): PasswordReset
 //#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;
@@ -517,6 +557,16 @@ interface ExchangeCodeParams {
   code: string;
   codeVerifier: string;
   redirectUri: string;
+  /**
+   * Browser context to attach to the token exchange (the call that creates the
+   * session). In a BFF deployment this request originates from Node, so without
+   * these the platform records the server's user-agent/IP ("node"/Unknown) instead
+   * of the end user's device. The BFF forwards a curated allowlist of the browser's
+   * request headers (user-agent, accept-language, the sec-ch-ua* client hints, and
+   * the observed client IP as x-forwarded-for). Optional and additive — omitting it
+   * preserves the prior behavior.
+   */
+  forwardedHeaders?: Record<string, string>;
 }
 interface SetPasswordParams {
   userId: string;
@@ -539,6 +589,17 @@ interface AuthorizeWithPasswordParams {
   /** 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;
@@ -590,9 +651,29 @@ declare class AuthClient {
     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;
@@ -607,4 +688,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 AuthorizeWithPasswordParams, 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 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, 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

@@ -203,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;
@@ -390,7 +403,21 @@ 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
@@ -405,6 +432,12 @@ declare const ENDPOINTS: {
    */
   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
@@ -470,7 +503,14 @@ declare function parseResetOutcome(status: number, body: unknown): PasswordReset
 //#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;
@@ -517,6 +557,16 @@ interface ExchangeCodeParams {
   code: string;
   codeVerifier: string;
   redirectUri: string;
+  /**
+   * Browser context to attach to the token exchange (the call that creates the
+   * session). In a BFF deployment this request originates from Node, so without
+   * these the platform records the server's user-agent/IP ("node"/Unknown) instead
+   * of the end user's device. The BFF forwards a curated allowlist of the browser's
+   * request headers (user-agent, accept-language, the sec-ch-ua* client hints, and
+   * the observed client IP as x-forwarded-for). Optional and additive — omitting it
+   * preserves the prior behavior.
+   */
+  forwardedHeaders?: Record<string, string>;
 }
 interface SetPasswordParams {
   userId: string;
@@ -539,6 +589,17 @@ interface AuthorizeWithPasswordParams {
   /** 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;
@@ -590,9 +651,29 @@ declare class AuthClient {
     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;
@@ -607,4 +688,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 AuthorizeWithPasswordParams, 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 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, 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

@@ -192,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",
@@ -707,7 +716,21 @@ 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",
+	/**
+	* 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
@@ -721,7 +744,13 @@ const ENDPOINTS = {
 	* `resetPassword` redeems that opaque token single-use and sets the new password.
 	*/
 	forgotPassword: "/v1/idp/forgot-password",
-	resetPassword: "/v1/idp/reset-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
@@ -811,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);
@@ -821,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),
@@ -982,6 +1042,7 @@ var AuthClient = class {
 		const response = await this.transport.request({
 			method: "POST",
 			url: this.config.baseUrl + ENDPOINTS.token,
+			...params.forwardedHeaders ? { headers: params.forwardedHeaders } : {},
 			body: {
 				grant_type: "authorization_code",
 				code: params.code,
@@ -993,6 +1054,27 @@ var AuthClient = class {
 		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) => {
@@ -1005,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",
@@ -1013,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",

package/package.json

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