@poly-x/next 0.1.0 → 0.2.0

package/dist/server.d.cts

@@ -1,4 +1,5 @@
-import { AuthClient, StoredSession } from "@poly-x/core";
+import { n as readSessionCookie, t as DEFAULT_SESSION_COOKIE } from "./session-cookie-AEnY4PVW.cjs";
+import { AuthClient, PolyXError, SessionClaims, StoredSession } from "@poly-x/core";
 
 //#region src/config.d.ts
 interface NextServerConfig {
@@ -15,6 +16,23 @@ interface NextServerConfig {
    * that doesn't forward `x-forwarded-proto`).
    */
   cookieSecure?: boolean;
+  /**
+   * The origin the browser actually reaches this app on, used to build `redirect_uri`.
+   * Set when the deployment knows its own address. `POLYX_PUBLIC_ORIGIN`.
+   */
+  publicOrigin?: string;
+  /**
+   * Honour `x-forwarded-host` / `x-forwarded-proto` when deriving the public origin.
+   * OPT-IN: `X-Forwarded-Host` is attacker-controllable when the app is reachable
+   * directly, so enable this only behind a trusted proxy. `POLYX_TRUST_FORWARDED_ORIGIN`.
+   */
+  trustForwardedOrigin?: boolean;
+  /**
+   * Base URL of the realtime service (poly-alert) that issues socket handshake tickets.
+   * `POLYX_REALTIME_URL`. Without it, `realtimeTicket` reports unavailable and apps stay
+   * on the superseded `subscriptionCredential` path.
+   */
+  realtimeBaseUrl?: string;
 }
 declare function resolveNextConfig(overrides?: Partial<NextServerConfig>): NextServerConfig;
 //#endregion
@@ -38,7 +56,6 @@ interface CookieAdapter {
 }
 //#endregion
 //#region src/server-session.d.ts
-declare const DEFAULT_SESSION_COOKIE = "polyx_session";
 interface ServerSessionOptions {
   authClient: AuthClient;
   secret: string;
@@ -60,6 +77,28 @@ declare class ServerSession {
   constructor(options: ServerSessionOptions);
   establishFromCode(code: string, codeVerifier: string, redirectUri: string, forwardedHeaders?: Record<string, string>): Promise<StoredSession>;
   read(): Promise<StoredSession | null>;
+  /**
+   * Re-seal the session with an updated **display** subset — name, email, avatar (ADR-0006).
+   *
+   * Needed because `normalizeRefresh` carries claims forward unchanged: the display claims are
+   * derived once, at login, and never again. So after a profile save the session still describes
+   * the person as they were when they signed in, and every surface reading `useUser()` shows the
+   * old name and photo until they sign out and back in (FR-PROF-5).
+   *
+   * Deliberately narrow. `userId` and `organizationId` are authorization-relevant and are **not**
+   * writable here — a profile save must never become a route to changing who the session is for,
+   * whatever the platform echoes back. Only the three display fields move.
+   *
+   * Returns `false` rather than throwing when the session cannot be re-sealed (an oversized
+   * cookie, a missing session): the caller's own operation has usually already succeeded
+   * upstream, and failing it because the *display* copy could not be updated would report a
+   * successful save as a failure.
+   */
+  updateDisplayClaims(patch: {
+    displayName?: string;
+    email?: string;
+    avatarUrl?: string;
+  }): Promise<boolean>;
   /** Rotate the tokens; clears the cookie (returns null) on a terminal refresh failure. */
   refresh(): Promise<StoredSession | null>;
   /**
@@ -84,13 +123,239 @@ interface AuthContext {
   claims: StoredSession["session"]["claims"] | null;
 }
 //#endregion
+//#region src/session-context.d.ts
+/** Why the platform profile is absent even though the session is valid. */
+type ProfileStatus = "ok" /** The platform could not be reached, or answered 5xx. The user is still signed in. */ | "unavailable" /** The session has no workspace, and poly-auth requires one to resolve a profile. */ | "no_organization";
+interface SessionContext {
+  isSignedIn: boolean;
+  userId: string | null;
+  organizationId?: string;
+  claims: SessionClaims | null;
+  /** The platform user profile, or `null` when it could not be resolved. */
+  user: Record<string, unknown> | null;
+  /**
+   * Present only when signed in. `"ok"` means `user` is populated; anything else says
+   * why it is not — so an app never mistakes a transient outage for a signed-out user.
+   */
+  profileStatus?: ProfileStatus;
+}
+interface SessionContextOptions extends Partial<NextServerConfig> {
+  /** Skip the platform profile fetch and return identity + claims only. */
+  skipProfile?: boolean;
+}
+/**
+ * Read who is signed in, including the platform profile.
+ *
+ * Safe in a Server Component: it reads the session and never writes it. The access
+ * credential is used to call the platform and is never part of the result (FR-SESS-5).
+ */
+declare function getSessionContext(options?: SessionContextOptions): Promise<SessionContext>;
+//#endregion
+//#region src/auth-event.d.ts
+/**
+ * One-shot auth events that survive a navigation (F017 / FR-CLIENT-5).
+ *
+ * Sign-in and sign-out are full-page navigations, so anything an app queues before them —
+ * a toast, an analytics call — is destroyed when the page unloads. Odin built ~80 lines of
+ * cookie plumbing to show "Logged in successfully"; this absorbs the shape.
+ *
+ * A cookie rather than a query parameter on the redirect target: the destination may
+ * redirect again before it renders (a route gate sending an unauthorised user elsewhere,
+ * for one), which drops the query and the event with it. A cookie survives the chain.
+ *
+ * It carries no secret — it exists to be read by page script, which is why it is
+ * deliberately NOT httpOnly. Never put anything in it that the browser should not see.
+ */
+/** The cookie the SDK publishes a one-shot auth event in. Readable by script, by design. */
+declare const AUTH_EVENT_COOKIE = "polyx_auth_event";
+type AuthEventKind = "signed-in" | "signed-out";
+/** Serialize the `Set-Cookie` value for a one-shot event. */
+declare function buildAuthEventCookie(kind: AuthEventKind, secure: boolean): string;
+//#endregion
+//#region src/public-origin.d.ts
+/**
+ * Public-origin resolution (F016 / FR-ORIG-1…3).
+ *
+ * The SDK derives its OAuth `redirect_uri` from the incoming request. Self-hosted behind
+ * a proxy or in a container, `request.url` is the BIND address — odin saw
+ * `https://0.0.0.0:3000` — so the platform is handed a redirect URI nobody registered and
+ * rejects it. Odin carries 62 lines of workaround for exactly this; alara carries a
+ * diagnostic logger to explain the resulting confusion.
+ *
+ * Forwarded headers are honoured only when the deployment OPTS IN. `X-Forwarded-Host` is
+ * attacker-controllable whenever the app is reachable directly, so trusting it by default
+ * would let a caller steer the redirect URI. Behind a trusted proxy the same header is set
+ * by infrastructure and is precisely what we need.
+ */
+interface PublicOriginOptions {
+  /**
+   * Explicit public origin (e.g. `https://app.example.com`). Wins over any derivation.
+   * Set via `POLYX_PUBLIC_ORIGIN` when the deployment knows its own address.
+   */
+  publicOrigin?: string;
+  /**
+   * Honour `x-forwarded-host` / `x-forwarded-proto`. Opt-in: only enable when a trusted
+   * proxy sets these and the app is not reachable directly. `POLYX_TRUST_FORWARDED_ORIGIN`.
+   */
+  trustForwardedOrigin?: boolean;
+}
+/**
+ * Resolve the origin the browser actually reached this app on.
+ *
+ * Precedence: explicit configuration → forwarded headers (only when trusted) → the
+ * request URL. Every step falls through on malformed input rather than emitting a broken
+ * origin, because a broken `redirect_uri` fails at the platform with a message about
+ * credentials rather than configuration.
+ */
+declare function resolvePublicOrigin(request: Request, options?: PublicOriginOptions): string;
+//#endregion
+//#region src/handler.d.ts
+/**
+ * URL segment → handler key. The segments are kebab-case (what a developer types in a
+ * path); the handler keys are camelCase (what the object exposes). Keeping the map
+ * explicit means a new handler cannot be reached by an unintended segment spelling.
+ */
+declare const POLYX_ACTIONS: {
+  readonly signin: "signin";
+  readonly authenticate: "authenticate";
+  readonly "forgot-password": "forgotPassword";
+  readonly "reset-password": "resetPassword";
+  readonly callback: "callback";
+  readonly refresh: "refresh";
+  readonly signout: "signout";
+  readonly session: "session";
+  readonly "subscription-credential": "subscriptionCredential";
+  readonly "realtime-ticket": "realtimeTicket";
+  readonly profile: "profile";
+};
+type PolyXActionSegment = keyof typeof POLYX_ACTIONS;
+/** What Next passes as the second argument to a catch-all route handler. */
+interface PolyXRouteContext {
+  params: Promise<Record<string, string | string[] | undefined>>;
+}
+type PolyXRouteHandler = (request: Request, context: PolyXRouteContext) => Promise<Response>;
+interface PolyXMountedHandlers {
+  GET: PolyXRouteHandler;
+  POST: PolyXRouteHandler;
+}
+/**
+ * Mount every SDK auth route from one declaration:
+ *
+ * ```ts
+ * // app/api/polyx/[...polyx]/route.ts
+ * export const { GET, POST } = createPolyXHandler();
+ * ```
+ *
+ * `handlers` is injectable for tests; production callers pass only the config.
+ */
+declare function createPolyXHandler(config?: AuthHandlersConfig, handlers?: AuthHandlers): PolyXMountedHandlers;
+//#endregion
+//#region src/data-proxy.d.ts
+interface DataProxyOptions extends Partial<NextServerConfig> {
+  /**
+   * Absolute base URL of the backend to forward to. A function is resolved per request,
+   * so a missing environment variable reports as a clear 500 rather than baking an empty
+   * base in at module load.
+   */
+  upstream: string | (() => string);
+  /** Names this proxy in misconfiguration messages, e.g. "Billing". */
+  label?: string;
+}
+/** What Next passes as the second argument to a catch-all route handler. */
+interface DataProxyContext {
+  params: Promise<Record<string, string | string[] | undefined>>;
+}
+type DataProxyHandler = (request: Request, context: DataProxyContext) => Promise<Response>;
+interface MountedDataProxy {
+  GET: DataProxyHandler;
+  POST: DataProxyHandler;
+  PUT: DataProxyHandler;
+  PATCH: DataProxyHandler;
+  DELETE: DataProxyHandler;
+  HEAD: DataProxyHandler;
+}
+/**
+ * Mount an authenticated proxy to one declared backend:
+ *
+ * ```ts
+ * // app/api/billing/proxy/[...path]/route.ts
+ * export const { GET, POST, PUT, PATCH, DELETE } = createDataProxy({
+ *   upstream: process.env.BILLING_URL!,
+ *   label: "Billing",
+ * });
+ * ```
+ *
+ * The client keeps calling a same-origin path; the credential is attached on this side of
+ * it and never reaches page scripts.
+ */
+declare function createDataProxy(options: DataProxyOptions): MountedDataProxy;
+//#endregion
 //#region src/cookie-codec.d.ts
-declare function sealSession(session: StoredSession, secret: string): Promise<string>;
+/**
+ * Browsers cap a single cookie at roughly 4096 bytes for the whole `Set-Cookie` pair —
+ * name, value and attributes together — and enforce it by DISCARDING the cookie without
+ * an error. For a session cookie that failure is invisible and badly misleading: the
+ * platform authenticates, the handler answers 200, and the user is bounced back to
+ * sign-in on the next request because the cookie was never stored.
+ *
+ * poly-x-sdk/ADR-0006 measured a live Odin session at 2628 bytes and recorded the missing
+ * guard as an open follow-up; a per-tenant flag that inflates the JWT is enough to cross
+ * the line. We fail loudly here instead.
+ */
+declare const SESSION_COOKIE_MAX_BYTES = 4096;
+/** Bytes the whole `Set-Cookie` pair will occupy for this value under this cookie name. */
+declare function sealedCookieByteLength(value: string, cookieName?: string): number;
+/**
+ * Thrown when a sealed session would exceed what a browser will store. Never includes the
+ * session itself — the claims that caused the overflow are exactly the data we must not log.
+ */
+declare class SessionCookieTooLargeError extends PolyXError {
+  readonly bytes: number;
+  readonly limit: number;
+  constructor(bytes: number, limit: number, cookieName: string);
+}
+interface SealSessionOptions {
+  /** The cookie name the value will be stored under; counted against the browser budget. */
+  cookieName?: string;
+}
+declare function sealSession(session: StoredSession, secret: string, options?: SealSessionOptions): Promise<string>;
 declare function openSession(token: string, secret: string): Promise<StoredSession | null>;
 //#endregion
 //#region src/server.d.ts
 /** Read the current session — safe in Server Components (no cookie write). */
 declare function auth(overrides?: Partial<NextServerConfig>): Promise<AuthContext>;
+/** What a server-side refresh reports back. */
+interface RefreshResult {
+  isSignedIn: boolean;
+  /**
+   * SERVER-SIDE ONLY. This is the credential the BFF attaches to upstream calls; it
+   * must never be returned to the browser (FR-SESS-5). `null` when signed out.
+   */
+  accessToken: string | null;
+  claims: AuthContext["claims"];
+}
+interface RefreshSessionOptions extends Partial<NextServerConfig> {
+  /**
+   * The inbound request, when there is one. Used only to derive the cookie `Secure`
+   * attribute from the transport. Pass it whenever available — without it we fall back
+   * to `cookieSecure` and then fail secure, which would drop the cookie over plain http.
+   */
+  request?: Request;
+}
+/**
+ * Refresh the current session from server code (F013 / FR-SESS-1).
+ *
+ * Before this existed there was no supported way to do it, so both live integrations
+ * did something worse: the server issued an HTTP request to its OWN
+ * `/api/polyx/refresh` route and then re-parsed the returned `Set-Cookie` header to
+ * recover the new token. That is a network round trip through the app's own edge to do
+ * something already possible in-process, and the header re-parse is fragile.
+ *
+ * Terminal-vs-transient classification lives in `ServerSession.refresh()` and is not
+ * duplicated here: a revoked family or an unstorable session signs the user out, and a
+ * transient upstream failure propagates so the caller can fail closed.
+ */
+declare function refreshSession(options?: RefreshSessionOptions): Promise<RefreshResult>;
 interface AuthHandlersConfig extends Partial<NextServerConfig> {
   /** Where to send the user after a successful sign-in. Default `/`. */
   afterSignInPath?: string;
@@ -135,6 +400,21 @@ interface AuthHandlers {
    * only to open the live-authz subscription.
    */
   subscriptionCredential(request: Request): Promise<Response>;
+  /**
+   * Obtain a single-use, seconds-lived ticket for opening a realtime connection
+   * (F019 / FR-RT-2). Supersedes `subscriptionCredential`: a leaked ticket is worth one
+   * connection, whereas the session token it used to hand out is worth an hour against
+   * every API.
+   */
+  realtimeTicket(request: Request): Promise<Response>;
+  /**
+   * Read (`GET`) and update (`POST`) the signed-in person's own profile (v0.4 / FR-CUSTODY-1).
+   *
+   * The identity acted on is taken from the sealed session and nothing else: there is no user
+   * id in the path or the body, so a caller cannot aim this at somebody else's profile
+   * (FR-CUSTODY-4 / D24). Editing another person is administration and lives in the console.
+   */
+  profile(request: Request): Promise<Response>;
 }
 /** The JSON the `forgotPassword` handler returns — always uniform (no enumeration). */
 type ForgotPasswordResult = {
@@ -175,9 +455,27 @@ type AuthenticateResult = {
   status: "no_access";
 } | {
   status: "invalid_credentials";
+} /** Credentials were correct, but the sealed session exceeds what a browser will store. */ | {
+  status: "session_too_large";
+  bytes: number;
+  limit: number;
+} /** The APP is misconfigured (unregistered redirect URI, unknown client, wrong deployment). */ | {
+  status: "configuration_error";
+  code: string;
+  message?: string;
+}
+/**
+ * RESERVED (FR-STEP-1…4). The platform wants a second proof of identity. No deployment
+ * produces this today; it is modelled so enabling MFA later is additive rather than a
+ * breaking change across three packages.
+ */
+| {
+  status: "verification_required";
+  challengeId: string;
+  factorTypes: readonly string[];
 } | {
   status: "invalid_request";
 };
 declare function createAuthHandlers(handlersConfig?: AuthHandlersConfig): AuthHandlers;
 //#endregion
-export { type AuthContext, AuthHandlers, AuthHandlersConfig, AuthenticateResult, type CookieAdapter, type CookieSetOptions, DEFAULT_SESSION_COOKIE, ForgotPasswordResult, type NextServerConfig, ResetPasswordResult, ServerSession, auth, createAuthHandlers, openSession, resolveNextConfig, sealSession };
+export { AUTH_EVENT_COOKIE, type AuthContext, type AuthEventKind, AuthHandlers, AuthHandlersConfig, AuthenticateResult, type CookieAdapter, type CookieSetOptions, DEFAULT_SESSION_COOKIE, type DataProxyContext, type DataProxyHandler, type DataProxyOptions, ForgotPasswordResult, type MountedDataProxy, type NextServerConfig, POLYX_ACTIONS, type PolyXActionSegment, type PolyXMountedHandlers, type PolyXRouteContext, type PolyXRouteHandler, type ProfileStatus, type PublicOriginOptions, RefreshResult, RefreshSessionOptions, ResetPasswordResult, SESSION_COOKIE_MAX_BYTES, ServerSession, type SessionContext, type SessionContextOptions, SessionCookieTooLargeError, auth, buildAuthEventCookie, createAuthHandlers, createDataProxy, createPolyXHandler, getSessionContext, openSession, readSessionCookie, refreshSession, resolveNextConfig, resolvePublicOrigin, sealSession, sealedCookieByteLength };