@poly-x/core 0.1.0-alpha.9 → 0.1.1

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
@@ -818,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);
@@ -828,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),
@@ -989,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,
@@ -1033,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",
@@ -1041,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
@@ -476,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;
@@ -523,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;
@@ -615,7 +659,21 @@ declare class AuthClient {
   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;

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
@@ -476,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;
@@ -523,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;
@@ -615,7 +659,21 @@ declare class AuthClient {
   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;

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
@@ -817,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);
@@ -827,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),
@@ -988,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,
@@ -1032,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",
@@ -1040,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.9",
+  "version": "0.1.1",
   "description": "Framework-agnostic core of the PolyX SDK",
   "license": "MIT",
   "type": "module",