@poly-x/core 0.1.0-alpha.0

package/dist/index.mjs

@@ -0,0 +1,902 @@
+//#region src/errors.ts
+/**
+* The typed error taxonomy shared by every @poly-x package (FR-DX-5).
+* Every failure a consumer can see is one of these classes — branchable by
+* `instanceof` or `code`, and safe to serialize: `toJSON()` redacts key
+* material and tokens (FR-DX-3).
+*/
+const KEY_PATTERN = /\b(?:pk|sk)_(?:test|live)_[A-Za-z0-9_-]{6,}/g;
+const BEARER_PATTERN = /\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi;
+const JWT_PATTERN = /\b[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g;
+function redactSensitive(text) {
+	return text.replace(KEY_PATTERN, "[REDACTED]").replace(BEARER_PATTERN, "Bearer [REDACTED]").replace(JWT_PATTERN, "[REDACTED]");
+}
+function redactDeep(value) {
+	if (typeof value === "string") return redactSensitive(value);
+	if (Array.isArray(value)) return value.map(redactDeep);
+	if (value && typeof value === "object") {
+		const result = {};
+		for (const [key, entry] of Object.entries(value)) result[key] = redactDeep(entry);
+		return result;
+	}
+	return value;
+}
+var PolyXError = class extends Error {
+	code;
+	requestId;
+	meta;
+	constructor(message, options) {
+		super(redactSensitive(message), { cause: options.cause });
+		this.name = new.target.name;
+		this.code = options.code;
+		this.requestId = options.requestId;
+		this.meta = options.meta;
+	}
+	toJSON() {
+		return {
+			name: this.name,
+			code: this.code,
+			message: this.message,
+			...this.requestId ? { requestId: this.requestId } : {},
+			...this.meta ? { meta: redactDeep(this.meta) } : {}
+		};
+	}
+};
+var PolyXConfigError = class extends PolyXError {
+	constructor(message, options) {
+		super(message, {
+			code: options?.code ?? "CONFIG_ERROR",
+			...options
+		});
+	}
+};
+/** Not signed in. `refreshable: true` means a silent refresh may recover it. */
+var UnauthenticatedError = class extends PolyXError {
+	refreshable;
+	constructor(message, options) {
+		super(message, options);
+		this.refreshable = options.refreshable;
+	}
+};
+/** Terminal session end (expiry / invalid refresh) — re-authentication required. */
+var SessionExpiredError = class extends PolyXError {
+	shouldRelogin = true;
+	constructor(message, options) {
+		super(message, options);
+	}
+};
+/** Session (or its whole family, on refresh-token reuse) was revoked. */
+var SessionRevokedError = class extends PolyXError {
+	shouldRelogin = true;
+	constructor(message, options) {
+		super(message, options);
+	}
+};
+var ForbiddenError = class extends PolyXError {};
+var ValidationError = class extends PolyXError {
+	errors;
+	constructor(message, options) {
+		super(message, {
+			code: options.code ?? "VALIDATION_ERROR",
+			...options
+		});
+		this.errors = options.errors;
+	}
+};
+var RateLimitedError = class extends PolyXError {
+	retryAfterSeconds;
+	constructor(message, options) {
+		super(message, {
+			code: options.code ?? "RATE_LIMITED",
+			...options
+		});
+		this.retryAfterSeconds = options.retryAfterSeconds;
+	}
+};
+/** Platform unreachable, 5xx, timeout, or an unrecognizable response. */
+var UpstreamError = class extends PolyXError {};
+//#endregion
+//#region src/keys.ts
+/**
+* PolyX key parsing (FR-CFG-3/4). Format draft v1 — the cross-repo contract
+* poly-x v4 (FR-KEY-2) implements; test vectors live in test/fixtures/keys.ts
+* and are mirrored into poly-x's tests:
+*
+*   {kind}_{env}_{base64url("v1|" + deploymentHost + "|" + random)}
+*
+* The deployment host is the issuing PolyX deployment's authority plus optional
+* path prefix, no scheme (e.g. "poly.fintra.ai/poly-x") — there is no single
+* SaaS PolyX, so the key locates its own backend (discovery D8).
+*/
+const KEY_SHAPE = /^(pk|sk)_(test|live)_([A-Za-z0-9_-]+)$/;
+const SUPPORTED_FORMAT_VERSIONS = /* @__PURE__ */ new Set(["v1"]);
+function decodeBase64Url(payload) {
+	const base64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+	const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+	try {
+		return atob(padded);
+	} catch {
+		throw new PolyXConfigError("PolyX key payload is not valid base64url.", { code: "KEY_MALFORMED" });
+	}
+}
+function parsePolyXKey(raw) {
+	if (typeof raw !== "string" || raw.length === 0) throw new PolyXConfigError("PolyX key is missing. Provide the key from your App instance.", { code: "KEY_MISSING" });
+	const match = KEY_SHAPE.exec(raw);
+	if (!match) throw new PolyXConfigError("PolyX key has an unrecognized prefix. Expected a key starting with pk_test_, pk_live_, sk_test_ or sk_live_.", { code: "KEY_MALFORMED" });
+	const [, kind, env, payload] = match;
+	const segments = decodeBase64Url(payload).split("|");
+	const formatVersion = segments[0] ?? "";
+	if (!SUPPORTED_FORMAT_VERSIONS.has(formatVersion)) throw new PolyXConfigError(`PolyX key has an unsupported format version ("${formatVersion || "none"}"). Upgrade @poly-x/core or re-issue the key.`, { code: "KEY_UNSUPPORTED_VERSION" });
+	if (segments.length !== 3) throw new PolyXConfigError("PolyX key payload is incomplete.", { code: "KEY_MALFORMED" });
+	const host = segments[1] ?? "";
+	if (host.length === 0) throw new PolyXConfigError("PolyX key does not carry an issuing deployment host.", { code: "KEY_MALFORMED" });
+	return {
+		kind,
+		env,
+		host,
+		formatVersion,
+		raw
+	};
+}
+//#endregion
+//#region src/config.ts
+/**
+* Effective SDK configuration (FR-CFG-4/5/6): the key locates its deployment;
+* an explicit baseUrl override wins (proxies, container-internal hostnames,
+* deployment migrations); secret keys are refused in browser contexts
+* (FR-CFG-1/2).
+*/
+function detectContext() {
+	const globals = globalThis;
+	return globals.window !== void 0 && globals.document !== void 0 ? "browser" : "server";
+}
+function normalizeBaseUrl(url) {
+	return url.replace(/\/+$/, "");
+}
+function resolveConfig(input) {
+	const context = input.context ?? detectContext();
+	const key = parsePolyXKey(input.key);
+	if (key.kind === "sk" && context === "browser") throw new PolyXConfigError("A PolyX secret key was passed to a browser-side package. Secret keys belong on your server only — use the publishable key (pk_…) in the browser.", { code: "SECRET_KEY_IN_BROWSER" });
+	let baseUrl;
+	if (input.baseUrl !== void 0) {
+		try {
+			new URL(input.baseUrl);
+		} catch {
+			throw new PolyXConfigError("The baseUrl override is not a valid URL.", { code: "BASE_URL_INVALID" });
+		}
+		baseUrl = normalizeBaseUrl(input.baseUrl);
+	} else baseUrl = `https://${normalizeBaseUrl(key.host)}`;
+	return {
+		key,
+		kind: key.kind,
+		env: key.env,
+		baseUrl,
+		context
+	};
+}
+//#endregion
+//#region src/contract/error-mapping.ts
+/**
+* Maps poly-auth's standardized error contract onto the SDK taxonomy — the
+* backward-compat shim's error half (FR-DX-2/3). Discriminator codes verified
+* 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"]);
+const EXPIRED_CODES = /* @__PURE__ */ new Set([
+	"SESSION_EXPIRED",
+	"REFRESH_TOKEN_REQUIRED",
+	"REFRESH_TOKEN_INVALID",
+	"REFRESH_TOKEN_EXPIRED"
+]);
+const FORBIDDEN_CODES = /* @__PURE__ */ new Set([
+	"TENANT_MEMBERSHIP_DENIED",
+	"ACCOUNT_ARCHIVED",
+	"NO_ACCESS"
+]);
+function asPlatformBody(body) {
+	return body && typeof body === "object" ? body : {};
+}
+function mapPlatformError(response) {
+	const { status, requestId } = response;
+	const body = asPlatformBody(response.body);
+	const message = typeof body.message === "string" ? body.message : `PolyX request failed (${status})`;
+	const code = typeof body.code === "string" ? body.code : void 0;
+	const common = { requestId };
+	if (code && REVOKED_CODES.has(code)) return new SessionRevokedError(message, {
+		code,
+		...common
+	});
+	if (code && EXPIRED_CODES.has(code)) return new SessionExpiredError(message, {
+		code,
+		...common
+	});
+	if (code === "ACCESS_TOKEN_EXPIRED") return new UnauthenticatedError(message, {
+		code,
+		refreshable: true,
+		...common
+	});
+	if (code === "TOKEN_REQUIRED") return new UnauthenticatedError(message, {
+		code,
+		refreshable: false,
+		...common
+	});
+	if (code && FORBIDDEN_CODES.has(code)) return new ForbiddenError(message, {
+		code,
+		...common
+	});
+	if (status === 400 || status === 422) return new ValidationError(message, {
+		code: code ?? "BAD_REQUEST",
+		errors: Array.isArray(body.errors) ? body.errors : [],
+		...common
+	});
+	if (status === 429) {
+		const header = response.headers?.["retry-after"];
+		return new RateLimitedError(message, {
+			retryAfterSeconds: header !== void 0 && /^\d+$/.test(header) ? Number(header) : void 0,
+			...common
+		});
+	}
+	if (status === 401) return new UnauthenticatedError(message, {
+		code: code ?? "UNAUTHENTICATED",
+		refreshable: false,
+		...common
+	});
+	if (status === 403) return new ForbiddenError(message, {
+		code: code ?? "FORBIDDEN",
+		...common
+	});
+	if (status >= 500) return new UpstreamError(message, {
+		code: code ?? "UPSTREAM_ERROR",
+		meta: { status },
+		...common
+	});
+	return new UpstreamError("PolyX returned a response this SDK version does not recognize.", {
+		code: "UNRECOGNIZED_RESPONSE",
+		meta: { status },
+		...common
+	});
+}
+//#endregion
+//#region src/transport/index.ts
+const DEFAULT_RETRY_POLICY = {
+	maxAttempts: 3,
+	retryDelayMs: 250
+};
+const DEFAULT_TIMEOUT_MS = 15e3;
+function isTransientStatus(status) {
+	return status >= 500;
+}
+//#endregion
+//#region src/transport/fetch.ts
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function parseBody(response) {
+	const text = await response.text();
+	if (text.length === 0) return void 0;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+function headersToRecord(headers) {
+	const record = {};
+	headers.forEach((value, key) => {
+		record[key.toLowerCase()] = value;
+	});
+	return record;
+}
+/** Default transport: global fetch + timeout + bounded transient-only retries. */
+var FetchTransport = class {
+	retry;
+	constructor(retry = {}) {
+		this.retry = {
+			...DEFAULT_RETRY_POLICY,
+			...retry
+		};
+	}
+	async request(request) {
+		const timeoutMs = request.timeoutMs ?? 15e3;
+		let lastNetworkError;
+		for (let attempt = 1; attempt <= this.retry.maxAttempts; attempt += 1) {
+			let response;
+			try {
+				response = await fetch(request.url, {
+					method: request.method,
+					headers: {
+						...request.body !== void 0 ? { "content-type": "application/json" } : {},
+						...request.headers
+					},
+					body: request.body !== void 0 ? JSON.stringify(request.body) : void 0,
+					signal: AbortSignal.timeout(timeoutMs)
+				});
+			} catch (error) {
+				lastNetworkError = error;
+				if (attempt < this.retry.maxAttempts) {
+					await sleep(this.retry.retryDelayMs * 2 ** (attempt - 1));
+					continue;
+				}
+				throw new UpstreamError("PolyX deployment is unreachable.", {
+					code: "NETWORK_ERROR",
+					meta: {
+						url: request.url,
+						attempts: attempt
+					},
+					cause: error
+				});
+			}
+			const result = {
+				status: response.status,
+				headers: headersToRecord(response.headers),
+				body: await parseBody(response)
+			};
+			if (isTransientStatus(result.status) && attempt < this.retry.maxAttempts) {
+				await sleep(this.retry.retryDelayMs * 2 ** (attempt - 1));
+				continue;
+			}
+			return result;
+		}
+		throw new UpstreamError("PolyX request could not be completed.", {
+			code: "NETWORK_ERROR",
+			cause: lastNetworkError
+		});
+	}
+};
+//#endregion
+//#region src/transport/mock.ts
+/**
+* Fixture-driven transport with the exact contract of FetchTransport — the
+* seam mock mode (FR-DX-4) plugs in. Unmatched requests fail loudly so fixture
+* bugs surface instead of hanging tests.
+*/
+var MockTransport = class {
+	routes;
+	constructor(routes) {
+		this.routes = routes.map((route) => ({
+			...route,
+			used: 0
+		}));
+	}
+	request(request) {
+		const pathname = new URL(request.url).pathname;
+		const route = this.routes.find((candidate) => candidate.method === request.method && candidate.path === pathname && (candidate.times === void 0 || candidate.used < candidate.times));
+		if (!route) return Promise.reject(/* @__PURE__ */ new Error(`MockTransport: no mock route for ${request.method} ${pathname}`));
+		route.used += 1;
+		if (route.networkError) return Promise.reject(new UpstreamError("PolyX deployment is unreachable.", {
+			code: "NETWORK_ERROR",
+			meta: {
+				url: request.url,
+				mock: true
+			}
+		}));
+		const response = route.response ?? {
+			status: 200,
+			body: void 0
+		};
+		return Promise.resolve({
+			status: response.status,
+			headers: Object.fromEntries(Object.entries(response.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value])),
+			body: response.body
+		});
+	}
+};
+//#endregion
+//#region src/session/state.ts
+const INITIAL_STATE = { status: "resolving" };
+function reduce(state, event) {
+	switch (event.type) {
+		case "hydrated":
+			if (state.status !== "resolving") return state;
+			return event.session ? {
+				status: "authenticated",
+				session: event.session
+			} : {
+				status: "signed-out",
+				reason: "signed-out"
+			};
+		case "established": return {
+			status: "authenticated",
+			session: event.session
+		};
+		case "refresh-started":
+			if (state.status !== "authenticated") return state;
+			return {
+				status: "refreshing",
+				session: state.session
+			};
+		case "refresh-succeeded":
+			if (state.status !== "refreshing") return state;
+			return {
+				status: "authenticated",
+				session: event.session
+			};
+		case "refresh-failed-transient":
+			if (state.status !== "refreshing") return state;
+			return {
+				status: "authenticated",
+				session: state.session
+			};
+		case "expired":
+			if (state.status !== "authenticated" && state.status !== "refreshing") return state;
+			return {
+				status: "signed-out",
+				reason: "expired"
+			};
+		case "revoked":
+			if (state.status !== "authenticated" && state.status !== "refreshing") return state;
+			return {
+				status: "signed-out",
+				reason: "revoked"
+			};
+		case "signed-out": return {
+			status: "signed-out",
+			reason: "signed-out"
+		};
+		default: return state;
+	}
+}
+//#endregion
+//#region src/session/seams.ts
+var InMemorySessionStore = class {
+	stored = null;
+	load() {
+		return Promise.resolve(this.stored);
+	}
+	save(stored) {
+		this.stored = stored;
+		return Promise.resolve();
+	}
+	clear() {
+		this.stored = null;
+		return Promise.resolve();
+	}
+};
+/**
+* A shared in-process bus. Two engines given the same instance simulate two
+* tabs on one channel. Delivers to every subscriber including the publisher;
+* the engine's transitions are idempotent so an echo is a harmless no-op.
+*/
+var InMemorySessionChannel = class {
+	listeners = /* @__PURE__ */ new Set();
+	publish(event) {
+		for (const listener of [...this.listeners]) listener(event);
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+};
+/** Per-key promise chain: fn runs after the prior holder settles (either way). */
+var InMemoryLock = class {
+	chains = /* @__PURE__ */ new Map();
+	runExclusive(key, fn) {
+		const run = (this.chains.get(key) ?? Promise.resolve()).then(fn, fn);
+		this.chains.set(key, run.then(() => void 0, () => void 0));
+		return run;
+	}
+};
+var SystemClock = class {
+	now() {
+		return Date.now();
+	}
+	setTimer(fn, delayMs) {
+		return setTimeout(fn, delayMs);
+	}
+	clearTimer(handle) {
+		clearTimeout(handle);
+	}
+};
+//#endregion
+//#region src/session/engine.ts
+/**
+* SessionEngine (F003): the one owner of session lifecycle — hydrate,
+* establish, single-flight refresh, sign-out, cross-tab mirroring, and
+* server-authoritative proactive-refresh scheduling. Network calls are
+* injected (`refreshTokens`) so core stays endpoint-agnostic; custody,
+* cross-tab, lock, and clock are seams (in-memory defaults provided).
+*/
+const REFRESH_LOCK_KEY = "session.refresh";
+const DEFAULT_SKEW_MS = 6e4;
+var SessionEngine = class {
+	state = INITIAL_STATE;
+	subscribers = /* @__PURE__ */ new Set();
+	store;
+	channel;
+	lock;
+	clock;
+	refreshTokens;
+	skewMs;
+	onSignOut;
+	unsubscribeChannel;
+	refreshTimer = null;
+	/** Bumped by establish/sign-out so an in-flight refresh can detect supersession. */
+	generation = 0;
+	constructor(options) {
+		this.store = options.store ?? new InMemorySessionStore();
+		this.channel = options.channel ?? new InMemorySessionChannel();
+		this.lock = options.lock ?? new InMemoryLock();
+		this.clock = options.clock ?? new SystemClock();
+		this.refreshTokens = options.refreshTokens;
+		this.skewMs = options.refreshSkewMs ?? DEFAULT_SKEW_MS;
+		this.onSignOut = options.onSignOut;
+		this.unsubscribeChannel = this.channel.subscribe((event) => {
+			this.applySignOut(event.reason, false);
+		});
+	}
+	getState() {
+		return this.state;
+	}
+	subscribe(listener) {
+		this.subscribers.add(listener);
+		return () => this.subscribers.delete(listener);
+	}
+	/** Restore a persisted session (or resolve to signed-out). Call once at startup. */
+	async hydrate() {
+		const stored = await this.store.load();
+		this.dispatch({
+			type: "hydrated",
+			session: stored?.session ?? null
+		});
+		if (stored) this.scheduleRefresh(stored);
+	}
+	/** Establish a session from freshly-issued or externally-exchanged tokens (FR-SES-1/2). */
+	async establishSession(stored) {
+		this.generation += 1;
+		await this.store.save(stored);
+		this.dispatch({
+			type: "established",
+			session: stored.session
+		});
+		this.scheduleRefresh(stored);
+	}
+	/** Current access token, refreshing first if it is at/near expiry (FR-SES-4). */
+	async getAccessToken() {
+		const stored = await this.store.load();
+		if (stored && !this.isStale(stored.tokens)) return stored.tokens.accessToken;
+		return (await this.refresh()).accessToken;
+	}
+	async signOut() {
+		await this.applySignOut("signed-out", true);
+	}
+	/** Release the cross-tab subscription (call on teardown). */
+	dispose() {
+		this.unsubscribeChannel();
+		this.cancelScheduledRefresh();
+	}
+	isStale(tokens) {
+		return this.clock.now() >= tokens.accessTokenExpiresAt - this.skewMs;
+	}
+	refresh() {
+		return this.lock.runExclusive(REFRESH_LOCK_KEY, async () => {
+			const gen = this.generation;
+			const current = await this.store.load();
+			if (!current) throw new UnauthenticatedError("No session to refresh.", {
+				code: "UNAUTHENTICATED",
+				refreshable: false
+			});
+			if (!this.isStale(current.tokens)) return current.tokens;
+			this.dispatch({ type: "refresh-started" });
+			let next;
+			try {
+				next = await this.refreshTokens(current);
+			} catch (error) {
+				if (this.generation === gen) this.handleRefreshError(error);
+				throw error;
+			}
+			if (this.generation !== gen) {
+				if (this.state.status === "signed-out") throw new UnauthenticatedError("Session ended during refresh.", {
+					code: "UNAUTHENTICATED",
+					refreshable: false
+				});
+				return (await this.store.load())?.tokens ?? next.tokens;
+			}
+			await this.store.save(next);
+			this.dispatch({
+				type: "refresh-succeeded",
+				session: next.session
+			});
+			this.scheduleRefresh(next);
+			return next.tokens;
+		});
+	}
+	handleRefreshError(error) {
+		if (error instanceof SessionRevokedError) {
+			this.applySignOut("revoked", true);
+			return;
+		}
+		if (error instanceof SessionExpiredError) {
+			this.applySignOut("expired", true);
+			return;
+		}
+		if (error instanceof UpstreamError || error instanceof Error) this.dispatch({ type: "refresh-failed-transient" });
+	}
+	async applySignOut(reason, broadcast) {
+		if (this.state.status === "signed-out") return;
+		this.generation += 1;
+		this.cancelScheduledRefresh();
+		await this.store.clear();
+		this.dispatch(signOutEvent(reason));
+		if (broadcast) this.channel.publish({
+			type: "signed-out",
+			reason
+		});
+		this.onSignOut?.(reason);
+	}
+	scheduleRefresh(stored) {
+		this.cancelScheduledRefresh();
+		const delay = stored.tokens.accessTokenExpiresAt - this.skewMs - this.clock.now();
+		this.refreshTimer = this.clock.setTimer(() => {
+			this.refresh().catch(() => void 0);
+		}, Math.max(0, delay));
+	}
+	cancelScheduledRefresh() {
+		if (this.refreshTimer !== null) {
+			this.clock.clearTimer(this.refreshTimer);
+			this.refreshTimer = null;
+		}
+	}
+	dispatch(event) {
+		const next = reduce(this.state, event);
+		if (next === this.state) return;
+		this.state = next;
+		for (const listener of [...this.subscribers]) listener(next);
+	}
+};
+function signOutEvent(reason) {
+	if (reason === "expired") return { type: "expired" };
+	if (reason === "revoked") return { type: "revoked" };
+	return { type: "signed-out" };
+}
+function createSessionEngine(options) {
+	return new SessionEngine(options);
+}
+//#endregion
+//#region src/auth/pkce.ts
+/**
+* PKCE (RFC 7636) via Web Crypto — `crypto.subtle` / `crypto.getRandomValues`
+* are universal (browser + Node ≥20), so core needs no runtime-specific import.
+*/
+function base64UrlEncode(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** S256 code challenge for a given verifier (exported for RFC test-vector coverage). */
+async function computeChallenge(verifier) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+	return base64UrlEncode(new Uint8Array(digest));
+}
+async function generatePkce() {
+	const bytes = /* @__PURE__ */ new Uint8Array(32);
+	crypto.getRandomValues(bytes);
+	const verifier = base64UrlEncode(bytes);
+	return {
+		verifier,
+		challenge: await computeChallenge(verifier),
+		method: "S256"
+	};
+}
+function randomState() {
+	const bytes = /* @__PURE__ */ new Uint8Array(16);
+	crypto.getRandomValues(bytes);
+	return base64UrlEncode(bytes);
+}
+//#endregion
+//#region src/auth/endpoints.ts
+/**
+* Every PolyX auth endpoint path in one place — the cross-repo contract surface
+* with poly-x. Paths are relative to the deployment base URL (which already
+* carries any deployment path prefix, e.g. `/poly-x`).
+*
+* Verified against poly-auth routes 2026-07-07: the IdP has no refresh grant;
+* refresh is the legacy `/auth/refresh-token`.
+*/
+const ENDPOINTS = {
+	authorize: "/v1/idp/authorize",
+	token: "/v1/idp/token",
+	refresh: "/v1/auth/refresh-token",
+	logout: "/v1/idp/logout",
+	orgResolve: "/v1/idp/org-resolve"
+};
+//#endregion
+//#region src/auth/outcomes.ts
+function asRecord$1(value) {
+	return value && typeof value === "object" ? value : {};
+}
+function parseTenants(value) {
+	if (!Array.isArray(value)) return [];
+	return value.map((raw) => {
+		const t = asRecord$1(raw);
+		return {
+			tenantId: String(t.tenantId ?? ""),
+			organizationCode: typeof t.organizationCode === "string" ? t.organizationCode : void 0,
+			slug: typeof t.slug === "string" ? t.slug : void 0,
+			name: typeof t.name === "string" ? t.name : void 0
+		};
+	});
+}
+function parseAuthorizeOutcome(status, body) {
+	const b = asRecord$1(body);
+	const statusField = typeof b.status === "string" ? b.status : void 0;
+	if (status === 403) return { type: "no_access" };
+	if (status === 401) return { type: "login_required" };
+	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 (statusField === "login_required" || b.code === "LOGIN_REQUIRED") return { type: "login_required" };
+	return { type: "login_required" };
+}
+//#endregion
+//#region src/auth/normalize.ts
+const FALLBACK_TTL_MS = 5 * 6e4;
+function decodeJwtExp(token) {
+	const parts = token.split(".");
+	if (parts.length < 2 || !parts[1]) return null;
+	try {
+		const b64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+		const padded = b64 + "=".repeat((4 - b64.length % 4) % 4);
+		const payload = JSON.parse(atob(padded));
+		return typeof payload.exp === "number" ? payload.exp * 1e3 : null;
+	} catch {
+		return null;
+	}
+}
+function toTokenSet(accessToken, refreshToken, now) {
+	return {
+		accessToken,
+		refreshToken,
+		accessTokenExpiresAt: decodeJwtExp(accessToken) ?? now + FALLBACK_TTL_MS
+	};
+}
+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. */
+function normalizeExchange(body, now) {
+	const data = asRecord(asRecord(body).data);
+	const user = asRecord(data.user);
+	const userId = String(user._id ?? user.id ?? "");
+	if (userId.length === 0) throw new Error("PolyX token response is missing a user identity.");
+	const claims = {
+		userId,
+		organizationId: data.tenantId != null ? String(data.tenantId) : void 0,
+		roles: [],
+		permissions: []
+	};
+	return {
+		tokens: toTokenSet(String(data.accessToken ?? ""), stringOrUndefined(data.refreshToken), now),
+		session: { claims }
+	};
+}
+/** `POST /auth/refresh-token` → StoredSession. No user in the response, so claims carry forward. */
+function normalizeRefresh(body, current, now) {
+	const b = asRecord(body);
+	return {
+		tokens: toTokenSet(String(b.accessToken ?? ""), stringOrUndefined(b.refreshToken) ?? current.tokens.refreshToken, now),
+		session: current.session
+	};
+}
+function stringOrUndefined(value) {
+	return typeof value === "string" ? value : void 0;
+}
+//#endregion
+//#region src/auth/pkce-store.ts
+var InMemoryPkceStore = class {
+	entries = /* @__PURE__ */ new Map();
+	save(entry) {
+		this.entries.set(entry.state, entry);
+		return Promise.resolve();
+	}
+	take(state) {
+		const entry = this.entries.get(state) ?? null;
+		if (entry) this.entries.delete(state);
+		return Promise.resolve(entry);
+	}
+};
+//#endregion
+//#region src/auth/client.ts
+var AuthClient = class {
+	config;
+	transport;
+	clock;
+	constructor(options) {
+		this.config = options.config;
+		this.transport = options.transport;
+		this.clock = options.clock ?? new SystemClock();
+	}
+	buildAuthorizeUrl(params) {
+		const url = new URL(this.config.baseUrl + ENDPOINTS.authorize);
+		url.searchParams.set("response_type", "code");
+		url.searchParams.set("client", this.config.key.raw);
+		url.searchParams.set("redirect_uri", params.redirectUri);
+		url.searchParams.set("state", params.state);
+		url.searchParams.set("code_challenge", params.challenge);
+		url.searchParams.set("code_challenge_method", "S256");
+		if (params.organizationCode) url.searchParams.set("organizationCode", params.organizationCode);
+		if (params.prompt) url.searchParams.set("prompt", params.prompt);
+		return url.toString();
+	}
+	/** Probe the warm hop (GET /idp/authorize) and return the typed outcome. */
+	async completeAuthorize(params) {
+		const response = await this.transport.request({
+			method: "GET",
+			url: this.buildAuthorizeUrl(params)
+		});
+		if (response.status >= 500) throw this.toError(response);
+		return parseAuthorizeOutcome(response.status, response.body);
+	}
+	async exchangeCode(params) {
+		const response = await this.transport.request({
+			method: "POST",
+			url: this.config.baseUrl + ENDPOINTS.token,
+			body: {
+				grant_type: "authorization_code",
+				code: params.code,
+				code_verifier: params.codeVerifier,
+				redirect_uri: params.redirectUri,
+				client: this.config.key.raw
+			}
+		});
+		if (response.status !== 200) throw this.toError(response);
+		return normalizeExchange(response.body, this.clock.now());
+	}
+	/** The `RefreshTokens` function the SessionEngine (F003) injects. */
+	createRefresher() {
+		return async (current) => {
+			const response = await this.transport.request({
+				method: "POST",
+				url: this.config.baseUrl + ENDPOINTS.refresh,
+				body: current.tokens.refreshToken ? { refreshToken: current.tokens.refreshToken } : {}
+			});
+			if (response.status !== 200) throw this.toError(response);
+			return normalizeRefresh(response.body, current, this.clock.now());
+		};
+	}
+	async logout(scope = "device") {
+		const response = await this.transport.request({
+			method: "POST",
+			url: this.config.baseUrl + ENDPOINTS.logout,
+			body: { scope }
+		});
+		if (response.status >= 400) throw this.toError(response);
+	}
+	async resolveOrg(email) {
+		const response = await this.transport.request({
+			method: "POST",
+			url: this.config.baseUrl + ENDPOINTS.orgResolve,
+			body: { email }
+		});
+		if (response.status !== 200) throw this.toError(response);
+		const body = response.body ?? {};
+		return {
+			resolved: body.resolved === true,
+			organizationCode: typeof body.organizationCode === "string" ? body.organizationCode : void 0
+		};
+	}
+	toError(response) {
+		return mapPlatformError({
+			status: response.status,
+			body: response.body,
+			headers: response.headers
+		});
+	}
+};
+//#endregion
+//#region src/index.ts
+/**
+* @poly-x/core — framework-agnostic guts of the PolyX SDK.
+*/
+const PACKAGE_NAME = "@poly-x/core";
+const version = "0.0.0";
+//#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 };