@poly-x/core 0.1.0-alpha.0

package/dist/index.d.cts

@@ -0,0 +1,491 @@
+//#region src/keys.d.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).
+ */
+type KeyKind = "pk" | "sk";
+type KeyEnv = "test" | "live";
+interface ParsedKey {
+  kind: KeyKind;
+  env: KeyEnv;
+  host: string;
+  formatVersion: string;
+  raw: string;
+}
+declare function parsePolyXKey(raw: string): ParsedKey;
+//#endregion
+//#region src/config.d.ts
+type RuntimeContext = "browser" | "server";
+interface ResolveConfigInput {
+  key: string;
+  /** Wins over the key-embedded host. */
+  baseUrl?: string;
+  /** Defaults to runtime auto-detection. */
+  context?: RuntimeContext;
+}
+interface ResolvedConfig {
+  key: ParsedKey;
+  kind: KeyKind;
+  env: KeyEnv;
+  baseUrl: string;
+  context: RuntimeContext;
+}
+declare function resolveConfig(input: ResolveConfigInput): ResolvedConfig;
+//#endregion
+//#region src/errors.d.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).
+ */
+declare function redactSensitive(text: string): string;
+interface PolyXErrorOptions {
+  code: string;
+  requestId?: string;
+  /** Arbitrary diagnostic context; redacted on serialization. */
+  meta?: Record<string, unknown>;
+  cause?: unknown;
+}
+declare class PolyXError extends Error {
+  readonly code: string;
+  readonly requestId?: string;
+  readonly meta?: Record<string, unknown>;
+  constructor(message: string, options: PolyXErrorOptions);
+  toJSON(): Record<string, unknown>;
+}
+declare class PolyXConfigError extends PolyXError {
+  constructor(message: string, options?: Partial<PolyXErrorOptions>);
+}
+/** Not signed in. `refreshable: true` means a silent refresh may recover it. */
+declare class UnauthenticatedError extends PolyXError {
+  readonly refreshable: boolean;
+  constructor(message: string, options: PolyXErrorOptions & {
+    refreshable: boolean;
+  });
+}
+/** Terminal session end (expiry / invalid refresh) — re-authentication required. */
+declare class SessionExpiredError extends PolyXError {
+  readonly shouldRelogin = true;
+  constructor(message: string, options: PolyXErrorOptions);
+}
+/** Session (or its whole family, on refresh-token reuse) was revoked. */
+declare class SessionRevokedError extends PolyXError {
+  readonly shouldRelogin = true;
+  constructor(message: string, options: PolyXErrorOptions);
+}
+declare class ForbiddenError extends PolyXError {}
+interface FieldError {
+  field: string;
+  message: string;
+}
+declare class ValidationError extends PolyXError {
+  readonly errors: FieldError[];
+  constructor(message: string, options: Partial<PolyXErrorOptions> & {
+    errors: FieldError[];
+  });
+}
+declare class RateLimitedError extends PolyXError {
+  readonly retryAfterSeconds?: number;
+  constructor(message: string, options: Partial<PolyXErrorOptions> & {
+    retryAfterSeconds?: number;
+  });
+}
+/** Platform unreachable, 5xx, timeout, or an unrecognizable response. */
+declare class UpstreamError extends PolyXError {}
+//#endregion
+//#region src/contract/error-mapping.d.ts
+interface PlatformResponseLike {
+  status: number;
+  body: unknown;
+  headers?: Record<string, string>;
+  requestId?: string;
+}
+declare function mapPlatformError(response: PlatformResponseLike): PolyXError;
+//#endregion
+//#region src/transport/index.d.ts
+/**
+ * The transport seam (FR-DX-4): everything in the SDK talks HTTP through this
+ * interface, so mock mode swaps the transport — not the code under test.
+ *
+ * Contract: `request` resolves with a TransportResponse for ANY HTTP outcome
+ * (mapping to taxonomy errors is the caller's job, via mapPlatformError) and
+ * rejects with UpstreamError only for network-level failures (unreachable,
+ * timeout) after bounded transient retries.
+ */
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+interface TransportRequest {
+  method: HttpMethod;
+  url: string;
+  headers?: Record<string, string>;
+  body?: unknown;
+  timeoutMs?: number;
+}
+interface TransportResponse {
+  status: number;
+  headers: Record<string, string>;
+  body: unknown;
+}
+interface Transport {
+  request(request: TransportRequest): Promise<TransportResponse>;
+}
+interface RetryPolicy {
+  /** Total attempts including the first (default 3). */
+  maxAttempts: number;
+  /** Base backoff between attempts, doubled each retry (default 250ms). */
+  retryDelayMs: number;
+}
+declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+declare const DEFAULT_TIMEOUT_MS = 15000;
+declare function isTransientStatus(status: number): boolean;
+//#endregion
+//#region src/transport/fetch.d.ts
+/** Default transport: global fetch + timeout + bounded transient-only retries. */
+declare class FetchTransport implements Transport {
+  private readonly retry;
+  constructor(retry?: Partial<RetryPolicy>);
+  request(request: TransportRequest): Promise<TransportResponse>;
+}
+//#endregion
+//#region src/transport/mock.d.ts
+interface MockRoute {
+  method: HttpMethod;
+  /** Matched against the request URL's pathname. */
+  path: string;
+  response?: {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+  };
+  /** Simulate an unreachable deployment instead of an HTTP response. */
+  networkError?: boolean;
+  /** Consume this route at most N times (default: unlimited). */
+  times?: number;
+}
+/**
+ * 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.
+ */
+declare class MockTransport implements Transport {
+  private readonly routes;
+  constructor(routes: MockRoute[]);
+  request(request: TransportRequest): Promise<TransportResponse>;
+}
+//#endregion
+//#region src/session/types.d.ts
+/**
+ * Session value types (F003). Claims are the *verified* identity/permission
+ * data the authorization surface (a later feature) reads; tokens are custody
+ * material held by the SessionStore seam, never exposed to consumer UI.
+ */
+interface TokenSet {
+  accessToken: string;
+  /** May be absent when custody keeps it httpOnly / server-side only. */
+  refreshToken?: string;
+  /** Epoch milliseconds when the access token expires, per the server. */
+  accessTokenExpiresAt: number;
+}
+interface SessionClaims {
+  userId: string;
+  organizationId?: string;
+  roles: readonly string[];
+  permissions: readonly string[];
+}
+interface Session {
+  claims: SessionClaims;
+}
+/** What the SessionStore persists: custody material + the derived session. */
+interface StoredSession {
+  tokens: TokenSet;
+  session: Session;
+}
+//#endregion
+//#region src/session/state.d.ts
+type SignedOutReason = "expired" | "revoked" | "signed-out";
+type SessionState = {
+  status: "resolving";
+} | {
+  status: "authenticated";
+  session: Session;
+} | {
+  status: "refreshing";
+  session: Session;
+} | {
+  status: "signed-out";
+  reason: SignedOutReason;
+};
+type SessionEvent = {
+  type: "hydrated";
+  session: Session | null;
+} | {
+  type: "established";
+  session: Session;
+} | {
+  type: "refresh-started";
+} | {
+  type: "refresh-succeeded";
+  session: Session;
+} | {
+  type: "refresh-failed-transient";
+} | {
+  type: "expired";
+} | {
+  type: "revoked";
+} | {
+  type: "signed-out";
+};
+declare const INITIAL_STATE: SessionState;
+declare function reduce(state: SessionState, event: SessionEvent): SessionState;
+//#endregion
+//#region src/session/seams.d.ts
+/** Token + session custody. */
+interface SessionStore {
+  load(): Promise<StoredSession | null>;
+  save(stored: StoredSession): Promise<void>;
+  clear(): Promise<void>;
+}
+/**
+ * Cross-tab coordination. v1 broadcasts sign-out/expiry/revocation only —
+ * FR-SES-7 is "logout or hard expiry in one tab reflects everywhere" (login
+ * propagation needs shared custody and is out of scope for core).
+ */
+interface SessionChannelEvent {
+  type: "signed-out";
+  reason: SignedOutReason;
+}
+interface SessionChannel {
+  publish(event: SessionChannelEvent): void;
+  subscribe(listener: (event: SessionChannelEvent) => void): () => void;
+}
+/** Exclusive section for single-flight refresh coordination. */
+interface Lock {
+  runExclusive<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}
+/** Opaque timer handle — the engine holds it and hands it back, never inspects it. */
+type TimerHandle = unknown;
+interface Clock {
+  now(): number;
+  setTimer(fn: () => void, delayMs: number): TimerHandle;
+  clearTimer(handle: TimerHandle): void;
+}
+declare class InMemorySessionStore implements SessionStore {
+  private stored;
+  load(): Promise<StoredSession | null>;
+  save(stored: StoredSession): Promise<void>;
+  clear(): Promise<void>;
+}
+/**
+ * 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.
+ */
+declare class InMemorySessionChannel implements SessionChannel {
+  private readonly listeners;
+  publish(event: SessionChannelEvent): void;
+  subscribe(listener: (event: SessionChannelEvent) => void): () => void;
+}
+/** Per-key promise chain: fn runs after the prior holder settles (either way). */
+declare class InMemoryLock implements Lock {
+  private readonly chains;
+  runExclusive<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}
+declare class SystemClock implements Clock {
+  now(): number;
+  setTimer(fn: () => void, delayMs: number): TimerHandle;
+  clearTimer(handle: TimerHandle): void;
+}
+//#endregion
+//#region src/session/engine.d.ts
+type RefreshTokens = (current: StoredSession) => Promise<StoredSession>;
+interface SessionEngineOptions {
+  refreshTokens: RefreshTokens;
+  store?: SessionStore;
+  channel?: SessionChannel;
+  lock?: Lock;
+  clock?: Clock;
+  /** Refresh this many ms before the access token's expiry. Default 60s. */
+  refreshSkewMs?: number;
+  /** Invoked on every sign-out transition (consumer customizes the UX). */
+  onSignOut?: (reason: SignedOutReason) => void;
+}
+declare class SessionEngine {
+  private state;
+  private readonly subscribers;
+  private readonly store;
+  private readonly channel;
+  private readonly lock;
+  private readonly clock;
+  private readonly refreshTokens;
+  private readonly skewMs;
+  private readonly onSignOut?;
+  private readonly unsubscribeChannel;
+  private refreshTimer;
+  /** Bumped by establish/sign-out so an in-flight refresh can detect supersession. */
+  private generation;
+  constructor(options: SessionEngineOptions);
+  getState(): SessionState;
+  subscribe(listener: (state: SessionState) => void): () => void;
+  /** Restore a persisted session (or resolve to signed-out). Call once at startup. */
+  hydrate(): Promise<void>;
+  /** Establish a session from freshly-issued or externally-exchanged tokens (FR-SES-1/2). */
+  establishSession(stored: StoredSession): Promise<void>;
+  /** Current access token, refreshing first if it is at/near expiry (FR-SES-4). */
+  getAccessToken(): Promise<string>;
+  signOut(): Promise<void>;
+  /** Release the cross-tab subscription (call on teardown). */
+  dispose(): void;
+  private isStale;
+  private refresh;
+  private handleRefreshError;
+  private applySignOut;
+  private scheduleRefresh;
+  private cancelScheduledRefresh;
+  private dispatch;
+}
+declare function createSessionEngine(options: SessionEngineOptions): SessionEngine;
+//#endregion
+//#region src/auth/pkce.d.ts
+/**
+ * PKCE (RFC 7636) via Web Crypto — `crypto.subtle` / `crypto.getRandomValues`
+ * are universal (browser + Node ≥20), so core needs no runtime-specific import.
+ */
+interface PkcePair {
+  verifier: string;
+  challenge: string;
+  method: "S256";
+}
+/** S256 code challenge for a given verifier (exported for RFC test-vector coverage). */
+declare function computeChallenge(verifier: string): Promise<string>;
+declare function generatePkce(): Promise<PkcePair>;
+declare function randomState(): string;
+//#endregion
+//#region src/auth/endpoints.d.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`.
+ */
+declare const ENDPOINTS: {
+  readonly authorize: "/v1/idp/authorize";
+  readonly token: "/v1/idp/token";
+  readonly refresh: "/v1/auth/refresh-token";
+  readonly logout: "/v1/idp/logout";
+  readonly orgResolve: "/v1/idp/org-resolve";
+};
+//#endregion
+//#region src/auth/outcomes.d.ts
+/**
+ * The three membership outcomes (+ login-required) as one typed union
+ * (FR-SSO-3): consumers never branch on raw platform codes. Parsed from the
+ * `GET /idp/authorize` response.
+ */
+interface TenantOption {
+  tenantId: string;
+  organizationCode?: string;
+  slug?: string;
+  name?: string;
+}
+type AuthorizeOutcome = {
+  type: "authorized";
+  code: string;
+  state: string;
+  redirectUri?: string;
+} | {
+  type: "select_tenant";
+  state: string;
+  tenants: TenantOption[];
+} | {
+  type: "no_access";
+} | {
+  type: "login_required";
+};
+declare function parseAuthorizeOutcome(status: number, body: unknown): AuthorizeOutcome;
+//#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. */
+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;
+//#endregion
+//#region src/auth/pkce-store.d.ts
+/**
+ * PKCE-transaction custody: the verifier + redirect must survive the round-trip
+ * to the PolyX login and back to the callback, keyed by `state`. In-memory
+ * default here; `@poly-x/react` supplies a `sessionStorage`-backed store (F005)
+ * so the transaction survives a full-page redirect.
+ */
+interface PkceEntry {
+  state: string;
+  verifier: string;
+  redirectUri: string;
+  createdAt: number;
+}
+interface PkceStore {
+  save(entry: PkceEntry): Promise<void>;
+  /** Retrieve and remove (single-use) the entry for a state value. */
+  take(state: string): Promise<PkceEntry | null>;
+}
+declare class InMemoryPkceStore implements PkceStore {
+  private readonly entries;
+  save(entry: PkceEntry): Promise<void>;
+  take(state: string): Promise<PkceEntry | null>;
+}
+//#endregion
+//#region src/auth/client.d.ts
+interface AuthClientOptions {
+  config: ResolvedConfig;
+  transport: Transport;
+  clock?: Clock;
+}
+interface BuildAuthorizeUrlParams {
+  redirectUri: string;
+  state: string;
+  challenge: string;
+  organizationCode?: string;
+  /** `none` = silent warm-hop probe (no login UI). */
+  prompt?: "none";
+}
+interface ExchangeCodeParams {
+  code: string;
+  codeVerifier: string;
+  redirectUri: string;
+}
+declare class AuthClient {
+  private readonly config;
+  private readonly transport;
+  private readonly clock;
+  constructor(options: AuthClientOptions);
+  buildAuthorizeUrl(params: BuildAuthorizeUrlParams): string;
+  /** Probe the warm hop (GET /idp/authorize) and return the typed outcome. */
+  completeAuthorize(params: BuildAuthorizeUrlParams): Promise<AuthorizeOutcome>;
+  exchangeCode(params: ExchangeCodeParams): Promise<StoredSession>;
+  /** The `RefreshTokens` function the SessionEngine (F003) injects. */
+  createRefresher(): RefreshTokens;
+  logout(scope?: "device" | "everywhere"): Promise<void>;
+  resolveOrg(email: string): Promise<{
+    resolved: boolean;
+    organizationCode?: string;
+  }>;
+  private toError;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * @poly-x/core — framework-agnostic guts of the PolyX SDK.
+ */
+declare const PACKAGE_NAME = "@poly-x/core";
+declare const version = "0.0.0";
+//#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 };