@poly-x/next 0.1.0-alpha.1 → 0.1.0-alpha.11

package/dist/proxy.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-require("./server-session-YbnXBt3c.cjs");
+require("./server-session-BpRaJCz9.cjs");
 let next_server = require("next/server");
 //#region src/proxy.ts
 /**

package/dist/proxy.mjs

@@ -1,4 +1,4 @@
-import "./server-session-B3zJ7CS8.mjs";
+import "./server-session-DedPwl4b.mjs";
 import { NextResponse } from "next/server";
 //#region src/proxy.ts
 /**

package/dist/{server-session-YbnXBt3c.cjs → server-session-BpRaJCz9.cjs}

@@ -1,12 +1,20 @@
 let _poly_x_core = require("@poly-x/core");
 //#region src/cookie-adapter.ts
-/** Default attributes for the session cookie (ADR-0004 secure custody). */
-const SESSION_COOKIE_OPTIONS = {
-	httpOnly: true,
-	secure: true,
-	sameSite: "lax",
-	path: "/"
-};
+/**
+* Attributes for the session cookie (ADR-0004 secure custody). `secure` is decided at
+* write time from the actual transport: a `Secure` cookie is silently dropped by the
+* browser over plain http, so http/localhost dev must set `secure:false` while https
+* always sets `secure:true`. This is not a downgrade — `Secure` carries no meaning on
+* http; setting it there just breaks the session. httpOnly/sameSite/path are unchanged.
+*/
+function buildSessionCookieOptions(secure) {
+	return {
+		httpOnly: true,
+		secure,
+		sameSite: "lax",
+		path: "/"
+	};
+}
 //#endregion
 //#region src/cookie-codec.ts
 const IV_BYTES = 12;
@@ -69,11 +77,13 @@ var ServerSession = class {
 	secret;
 	cookies;
 	cookieName;
+	secure;
 	constructor(options) {
 		this.authClient = options.authClient;
 		this.secret = options.secret;
 		this.cookies = options.cookies;
 		this.cookieName = options.cookieName ?? "polyx_session";
+		this.secure = options.secure ?? true;
 	}
 	async establishFromCode(code, codeVerifier, redirectUri) {
 		const stored = await this.authClient.exchangeCode({
@@ -105,12 +115,30 @@ var ServerSession = class {
 			throw error;
 		}
 	}
+	/**
+	* End the session upstream, then locally. `device` revokes this session; `everywhere`
+	* revokes every session for the user (FR-SSO-5).
+	*
+	* Order is load-bearing: revocation is authenticated with the access token sealed in the
+	* cookie, so the cookie must be read before it is dropped. The upstream call is
+	* best-effort — an unreachable platform must not strand the user half-signed-in — but the
+	* call itself is real: the ecosystem logout the SDK used before resolves its session from
+	* a browser cookie, which a server-to-server fetch never carries, so it silently revoked
+	* nothing and answered 200.
+	*/
+	async revoke(scope = "device") {
+		const current = await this.read();
+		if (current) try {
+			await this.authClient.revokeSession(current.tokens.accessToken, scope);
+		} catch {}
+		this.clear();
+	}
 	clear() {
 		this.cookies.delete(this.cookieName);
 	}
 	async write(session) {
 		const sealed = await sealSession(session, this.secret);
-		this.cookies.set(this.cookieName, sealed, SESSION_COOKIE_OPTIONS);
+		this.cookies.set(this.cookieName, sealed, buildSessionCookieOptions(this.secure));
 	}
 };
 function toAuthContext(session) {

package/dist/{server-session-B3zJ7CS8.mjs → server-session-DedPwl4b.mjs}

@@ -1,12 +1,20 @@
 import { SessionExpiredError, SessionRevokedError } from "@poly-x/core";
 //#region src/cookie-adapter.ts
-/** Default attributes for the session cookie (ADR-0004 secure custody). */
-const SESSION_COOKIE_OPTIONS = {
-	httpOnly: true,
-	secure: true,
-	sameSite: "lax",
-	path: "/"
-};
+/**
+* Attributes for the session cookie (ADR-0004 secure custody). `secure` is decided at
+* write time from the actual transport: a `Secure` cookie is silently dropped by the
+* browser over plain http, so http/localhost dev must set `secure:false` while https
+* always sets `secure:true`. This is not a downgrade — `Secure` carries no meaning on
+* http; setting it there just breaks the session. httpOnly/sameSite/path are unchanged.
+*/
+function buildSessionCookieOptions(secure) {
+	return {
+		httpOnly: true,
+		secure,
+		sameSite: "lax",
+		path: "/"
+	};
+}
 //#endregion
 //#region src/cookie-codec.ts
 const IV_BYTES = 12;
@@ -69,11 +77,13 @@ var ServerSession = class {
 	secret;
 	cookies;
 	cookieName;
+	secure;
 	constructor(options) {
 		this.authClient = options.authClient;
 		this.secret = options.secret;
 		this.cookies = options.cookies;
 		this.cookieName = options.cookieName ?? "polyx_session";
+		this.secure = options.secure ?? true;
 	}
 	async establishFromCode(code, codeVerifier, redirectUri) {
 		const stored = await this.authClient.exchangeCode({
@@ -105,12 +115,30 @@ var ServerSession = class {
 			throw error;
 		}
 	}
+	/**
+	* End the session upstream, then locally. `device` revokes this session; `everywhere`
+	* revokes every session for the user (FR-SSO-5).
+	*
+	* Order is load-bearing: revocation is authenticated with the access token sealed in the
+	* cookie, so the cookie must be read before it is dropped. The upstream call is
+	* best-effort — an unreachable platform must not strand the user half-signed-in — but the
+	* call itself is real: the ecosystem logout the SDK used before resolves its session from
+	* a browser cookie, which a server-to-server fetch never carries, so it silently revoked
+	* nothing and answered 200.
+	*/
+	async revoke(scope = "device") {
+		const current = await this.read();
+		if (current) try {
+			await this.authClient.revokeSession(current.tokens.accessToken, scope);
+		} catch {}
+		this.clear();
+	}
 	clear() {
 		this.cookies.delete(this.cookieName);
 	}
 	async write(session) {
 		const sealed = await sealSession(session, this.secret);
-		this.cookies.set(this.cookieName, sealed, SESSION_COOKIE_OPTIONS);
+		this.cookies.set(this.cookieName, sealed, buildSessionCookieOptions(this.secure));
 	}
 };
 function toAuthContext(session) {

package/dist/server.cjs

@@ -1,8 +1,15 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_server_session = require("./server-session-YbnXBt3c.cjs");
+const require_server_session = require("./server-session-BpRaJCz9.cjs");
 let _poly_x_core = require("@poly-x/core");
 let next_headers = require("next/headers");
 //#region src/config.ts
+/** Parse a boolean-ish env var; undefined when unset/unrecognized (→ auto-derive). */
+function parseBoolEnv(value) {
+	if (value === void 0) return void 0;
+	const v = value.trim().toLowerCase();
+	if (v === "true" || v === "1") return true;
+	if (v === "false" || v === "0") return false;
+}
 function resolveNextConfig(overrides = {}) {
 	const publishableKey = overrides.publishableKey ?? process.env.NEXT_PUBLIC_POLYX_PUBLISHABLE_KEY;
 	const secret = overrides.secret ?? process.env.POLYX_SESSION_SECRET;
@@ -12,7 +19,8 @@ function resolveNextConfig(overrides = {}) {
 		publishableKey,
 		secret,
 		baseUrl: overrides.baseUrl ?? process.env.POLYX_BASE_URL,
-		signInUrl: overrides.signInUrl ?? process.env.NEXT_PUBLIC_POLYX_SIGN_IN_URL
+		signInUrl: overrides.signInUrl ?? process.env.NEXT_PUBLIC_POLYX_SIGN_IN_URL,
+		cookieSecure: overrides.cookieSecure ?? parseBoolEnv(process.env.POLYX_COOKIE_SECURE)
 	};
 }
 function buildServerAuthClient(config) {
@@ -36,6 +44,8 @@ function buildServerAuthClient(config) {
 */
 const VERIFIER_COOKIE = "polyx_pkce";
 const VERIFIER_MAX_AGE = 600;
+/** poly-auth's own floor (Joi: min 6, max 128) — reject early rather than round-trip. */
+const MIN_PASSWORD_LENGTH = 6;
 function adapt(store) {
 	return {
 		get: (name) => store.get(name)?.value,
@@ -46,6 +56,22 @@ function adapt(store) {
 async function requestCookies() {
 	return adapt(await (0, next_headers.cookies)());
 }
+/**
+* Decide the cookie `Secure` attribute for this request. An explicit `cookieSecure`
+* (from `POLYX_COOKIE_SECURE` or code) wins; otherwise derive from the transport —
+* `x-forwarded-proto` (proxied TLS) then the request URL — and fail secure if unknown.
+* A Secure cookie is dropped by the browser over http, so http/localhost must be false.
+*/
+function resolveCookieSecure(request, config) {
+	if (config.cookieSecure !== void 0) return config.cookieSecure;
+	const forwarded = request.headers.get("x-forwarded-proto");
+	if (forwarded) return forwarded.split(",")[0].trim() === "https";
+	try {
+		return new URL(request.url).protocol === "https:";
+	} catch {
+		return true;
+	}
+}
 /** Read the current session — safe in Server Components (no cookie write). */
 async function auth(overrides) {
 	const config = resolveNextConfig(overrides);
@@ -58,16 +84,18 @@ async function auth(overrides) {
 function createAuthHandlers(handlersConfig = {}) {
 	const callbackPath = handlersConfig.callbackPath ?? "/api/polyx/callback";
 	const afterSignInPath = handlersConfig.afterSignInPath ?? "/";
-	function newSession(store, config) {
+	function newSession(store, config, secure) {
 		return new require_server_session.ServerSession({
 			authClient: buildServerAuthClient(config),
 			secret: config.secret,
-			cookies: store
+			cookies: store,
+			secure
 		});
 	}
 	return {
 		async signin(request) {
 			const config = resolveNextConfig(handlersConfig);
+			const secure = resolveCookieSecure(request, config);
 			const redirectUri = `${new URL(request.url).origin}${callbackPath}`;
 			const { verifier, challenge } = await (0, _poly_x_core.generatePkce)();
 			const state = (0, _poly_x_core.randomState)();
@@ -77,7 +105,7 @@ function createAuthHandlers(handlersConfig = {}) {
 				redirectUri
 			}), {
 				httpOnly: true,
-				secure: true,
+				secure,
 				sameSite: "lax",
 				path: "/",
 				maxAge: VERIFIER_MAX_AGE
@@ -89,8 +117,128 @@ function createAuthHandlers(handlersConfig = {}) {
 			});
 			return Response.redirect(url, 302);
 		},
+		async authenticate(request) {
+			const config = resolveNextConfig(handlersConfig);
+			const secure = resolveCookieSecure(request, config);
+			const redirectUri = `${new URL(request.url).origin}${callbackPath}`;
+			const client = buildServerAuthClient(config);
+			let payload;
+			try {
+				payload = await request.json();
+			} catch {
+				return Response.json({ status: "invalid_request" }, { status: 400 });
+			}
+			const email = typeof payload.email === "string" ? payload.email : "";
+			const password = typeof payload.password === "string" ? payload.password : "";
+			if (!email || !password) return Response.json({ status: "invalid_request" }, { status: 400 });
+			const organizationCode = typeof payload.organizationCode === "string" ? payload.organizationCode : void 0;
+			const tenantId = typeof payload.tenantId === "string" ? payload.tenantId : void 0;
+			const newPassword = typeof payload.newPassword === "string" ? payload.newPassword : void 0;
+			const confirmPassword = typeof payload.confirmPassword === "string" ? payload.confirmPassword : void 0;
+			/** One authorize attempt, mapped to the wire response (sealing the session on success). */
+			async function attempt(withPassword) {
+				const { verifier, challenge } = await (0, _poly_x_core.generatePkce)();
+				const outcome = await client.authorizeWithPassword({
+					email,
+					password: withPassword,
+					redirectUri,
+					state: (0, _poly_x_core.randomState)(),
+					challenge,
+					organizationCode,
+					tenantId
+				});
+				switch (outcome.type) {
+					case "authorized":
+						await newSession(adapt(await (0, next_headers.cookies)()), config, secure).establishFromCode(outcome.code, verifier, redirectUri);
+						return Response.json({
+							status: "success",
+							redirectTo: afterSignInPath
+						});
+					case "select_tenant": return Response.json({
+						status: "select_tenant",
+						tenants: outcome.tenants,
+						state: outcome.state
+					});
+					case "password_change_required": return Response.json({
+						status: "password_change_required",
+						userId: outcome.userId
+					}, { status: 403 });
+					case "no_access": return Response.json({ status: "no_access" }, { status: 403 });
+					default: return Response.json({ status: "invalid_credentials" }, { status: 401 });
+				}
+			}
+			if (newPassword === void 0) return attempt(password);
+			if (newPassword.length < MIN_PASSWORD_LENGTH) return Response.json({
+				status: "weak_password",
+				minLength: MIN_PASSWORD_LENGTH
+			}, { status: 400 });
+			if (newPassword !== confirmPassword) return Response.json({ status: "password_mismatch" }, { status: 400 });
+			const { challenge } = await (0, _poly_x_core.generatePkce)();
+			const proof = await client.authorizeWithPassword({
+				email,
+				password,
+				redirectUri,
+				state: (0, _poly_x_core.randomState)(),
+				challenge,
+				organizationCode,
+				tenantId
+			});
+			if (proof.type !== "password_change_required") return Response.json({ status: "invalid_credentials" }, { status: 401 });
+			await client.setPassword({
+				userId: proof.userId,
+				newPassword,
+				confirmPassword,
+				ticket: proof.ticket
+			});
+			return attempt(newPassword);
+		},
+		async forgotPassword(request) {
+			const config = resolveNextConfig(handlersConfig);
+			let payload;
+			try {
+				payload = await request.json();
+			} catch {
+				return Response.json({ status: "invalid_request" }, { status: 400 });
+			}
+			const email = typeof payload.email === "string" ? payload.email.trim() : "";
+			if (!email) return Response.json({ status: "invalid_request" }, { status: 400 });
+			try {
+				await buildServerAuthClient(config).requestPasswordReset({ email });
+			} catch {}
+			return Response.json({ status: "accepted" });
+		},
+		async resetPassword(request) {
+			const config = resolveNextConfig(handlersConfig);
+			let payload;
+			try {
+				payload = await request.json();
+			} catch {
+				return Response.json({ status: "invalid_request" }, { status: 400 });
+			}
+			const token = typeof payload.token === "string" ? payload.token : "";
+			const newPassword = typeof payload.newPassword === "string" ? payload.newPassword : "";
+			const confirmPassword = typeof payload.confirmPassword === "string" ? payload.confirmPassword : void 0;
+			if (!token) return Response.json({ status: "invalid_request" }, { status: 400 });
+			if (newPassword.length < MIN_PASSWORD_LENGTH) return Response.json({
+				status: "weak_password",
+				minLength: MIN_PASSWORD_LENGTH
+			}, { status: 400 });
+			if (confirmPassword !== void 0 && newPassword !== confirmPassword) return Response.json({ status: "password_mismatch" }, { status: 400 });
+			switch (await buildServerAuthClient(config).resetPassword({
+				token,
+				newPassword
+			})) {
+				case "ok": return Response.json({ status: "success" });
+				case "weak_password": return Response.json({
+					status: "weak_password",
+					minLength: MIN_PASSWORD_LENGTH
+				}, { status: 400 });
+				default: return Response.json({ status: "invalid_or_expired" }, { status: 400 });
+			}
+		},
 		async callback(request) {
 			const config = resolveNextConfig(handlersConfig);
+			const secure = resolveCookieSecure(request, config);
 			const url = new URL(request.url);
 			const code = url.searchParams.get("code");
 			const state = url.searchParams.get("state");
@@ -101,21 +249,35 @@ function createAuthHandlers(handlersConfig = {}) {
 			if (!code || !state || !raw) return Response.redirect(home, 302);
 			const tx = JSON.parse(raw);
 			if (tx.state !== state) return Response.redirect(home, 302);
-			await newSession(adapt(store), config).establishFromCode(code, tx.verifier, tx.redirectUri);
+			await newSession(adapt(store), config, secure).establishFromCode(code, tx.verifier, tx.redirectUri);
 			return Response.redirect(home, 302);
 		},
-		async refresh() {
+		async refresh(request) {
 			const config = resolveNextConfig(handlersConfig);
-			const session = await newSession(await requestCookies(), config).refresh();
+			const secure = resolveCookieSecure(request, config);
+			const session = await newSession(await requestCookies(), config, secure).refresh();
 			return Response.json({ isSignedIn: session !== null }, { status: session ? 200 : 401 });
 		},
+		/**
+		* End the session: revoke it upstream (bearer-authenticated, using the sealed token)
+		* and unseal the cookie. `?scope=everywhere` signs the user out of every device.
+		*
+		* Content-negotiated so both callers work: a plain link/form navigation gets the 302 it
+		* expects, while `Accept: application/json` (what `<UserButton/>` sends) gets JSON and
+		* decides its own destination client-side. Deliberately no server-side redirect target
+		* — a caller-supplied one would be an open redirect on the auth path, and the client
+		* already knows where it wants to land.
+		*/
 		async signout(request) {
 			const config = resolveNextConfig(handlersConfig);
-			newSession(adapt(await (0, next_headers.cookies)()), config).clear();
-			try {
-				await buildServerAuthClient(config).logout("device");
-			} catch {}
+			const secure = resolveCookieSecure(request, config);
+			const scope = new URL(request.url).searchParams.get("scope") === "everywhere" ? "everywhere" : "device";
+			await newSession(adapt(await (0, next_headers.cookies)()), config, secure).revoke(scope);
+			if (request.headers.get("accept")?.includes("application/json")) return Response.json({ signedOut: true });
 			return Response.redirect(new URL(request.url).origin + "/", 302);
+		},
+		async session() {
+			return Response.json(await auth(handlersConfig));
 		}
 	};
 }

package/dist/server.d.cts

@@ -8,6 +8,13 @@ interface NextServerConfig {
   baseUrl?: string;
   /** Hosted sign-in page URL the signin route redirects to. */
   signInUrl?: string;
+  /**
+   * Force the session/verifier cookie `Secure` attribute. Leave undefined (default) to
+   * derive it from the request transport (https → true, http/localhost → false). Set via
+   * `POLYX_COOKIE_SECURE=true|false` only for edge cases (e.g. a TLS-terminating proxy
+   * that doesn't forward `x-forwarded-proto`).
+   */
+  cookieSecure?: boolean;
 }
 declare function resolveNextConfig(overrides?: Partial<NextServerConfig>): NextServerConfig;
 //#endregion
@@ -37,17 +44,36 @@ interface ServerSessionOptions {
   secret: string;
   cookies: CookieAdapter;
   cookieName?: string;
+  /**
+   * Whether to set the `Secure` attribute on the session cookie. Defaults to `true`
+   * (fail secure). Handlers derive it from the request transport so http/localhost dev
+   * works (a Secure cookie is dropped over http). See buildSessionCookieOptions.
+   */
+  secure?: boolean;
 }
 declare class ServerSession {
   private readonly authClient;
   private readonly secret;
   private readonly cookies;
   private readonly cookieName;
+  private readonly secure;
   constructor(options: ServerSessionOptions);
   establishFromCode(code: string, codeVerifier: string, redirectUri: string): Promise<StoredSession>;
   read(): Promise<StoredSession | null>;
   /** Rotate the tokens; clears the cookie (returns null) on a terminal refresh failure. */
   refresh(): Promise<StoredSession | null>;
+  /**
+   * End the session upstream, then locally. `device` revokes this session; `everywhere`
+   * revokes every session for the user (FR-SSO-5).
+   *
+   * Order is load-bearing: revocation is authenticated with the access token sealed in the
+   * cookie, so the cookie must be read before it is dropped. The upstream call is
+   * best-effort — an unreachable platform must not strand the user half-signed-in — but the
+   * call itself is real: the ecosystem logout the SDK used before resolves its session from
+   * a browser cookie, which a server-to-server fetch never carries, so it silently revoked
+   * nothing and answered 200.
+   */
+  revoke(scope?: "device" | "everywhere"): Promise<void>;
   clear(): void;
   private write;
 }
@@ -73,10 +99,77 @@ interface AuthHandlersConfig extends Partial<NextServerConfig> {
 }
 interface AuthHandlers {
   signin(request: Request): Promise<Response>;
+  /**
+   * The embedded `<SignIn/>` BFF endpoint: reads `{email, password}` (+ optional
+   * `organizationCode`/`tenantId`), runs the password authorize entirely
+   * server-side, and — on success — seals the httpOnly session before returning.
+   * The browser never sees the code, the tokens, or the credentials after POST.
+   */
+  authenticate(request: Request): Promise<Response>;
+  /**
+   * The `<ForgotPassword/>` BFF endpoint: reads `{email}`, adds this app's publishable
+   * key, and asks poly-auth to email a reset link server-side. Always relays a uniform
+   * `accepted` — it never reveals whether the account exists.
+   */
+  forgotPassword(request: Request): Promise<Response>;
+  /**
+   * The `<ResetPassword/>` BFF endpoint: reads `{token, newPassword}` and redeems the
+   * opaque single-use token. `success` on completion; `invalid_or_expired` otherwise.
+   */
+  resetPassword(request: Request): Promise<Response>;
   callback(request: Request): Promise<Response>;
   refresh(request: Request): Promise<Response>;
   signout(request: Request): Promise<Response>;
+  /**
+   * The client's view of the session: the same `AuthContext` `auth()` returns in a Server
+   * Component, as JSON. This is what makes client components work under BFF custody, where
+   * the browser holds no token and so cannot derive a session for itself — the hooks read
+   * server truth instead. Never carries a token.
+   */
+  session(request: Request): Promise<Response>;
 }
+/** The JSON the `forgotPassword` handler returns — always uniform (no enumeration). */
+type ForgotPasswordResult = {
+  status: "accepted";
+} | {
+  status: "invalid_request";
+};
+/** The JSON the `resetPassword` handler returns — the `<ResetPassword/>` form branches on `status`. */
+type ResetPasswordResult = {
+  status: "success";
+} | {
+  status: "weak_password";
+  minLength: number;
+} | {
+  status: "password_mismatch";
+} | {
+  status: "invalid_or_expired";
+} | {
+  status: "invalid_request";
+};
+/** The JSON the `authenticate` handler returns — the `<SignIn/>` form branches on `status`. */
+type AuthenticateResult = {
+  status: "success";
+  redirectTo: string;
+} | {
+  status: "select_tenant";
+  tenants: unknown[];
+  state: string;
+} | {
+  status: "password_change_required";
+  userId: string;
+} | {
+  status: "weak_password";
+  minLength: number;
+} | {
+  status: "password_mismatch";
+} | {
+  status: "no_access";
+} | {
+  status: "invalid_credentials";
+} | {
+  status: "invalid_request";
+};
 declare function createAuthHandlers(handlersConfig?: AuthHandlersConfig): AuthHandlers;
 //#endregion
-export { type AuthContext, AuthHandlers, AuthHandlersConfig, type CookieAdapter, type CookieSetOptions, DEFAULT_SESSION_COOKIE, type NextServerConfig, ServerSession, auth, createAuthHandlers, openSession, resolveNextConfig, sealSession };
+export { type AuthContext, AuthHandlers, AuthHandlersConfig, AuthenticateResult, type CookieAdapter, type CookieSetOptions, DEFAULT_SESSION_COOKIE, ForgotPasswordResult, type NextServerConfig, ResetPasswordResult, ServerSession, auth, createAuthHandlers, openSession, resolveNextConfig, sealSession };

package/dist/server.d.mts

@@ -8,6 +8,13 @@ interface NextServerConfig {
   baseUrl?: string;
   /** Hosted sign-in page URL the signin route redirects to. */
   signInUrl?: string;
+  /**
+   * Force the session/verifier cookie `Secure` attribute. Leave undefined (default) to
+   * derive it from the request transport (https → true, http/localhost → false). Set via
+   * `POLYX_COOKIE_SECURE=true|false` only for edge cases (e.g. a TLS-terminating proxy
+   * that doesn't forward `x-forwarded-proto`).
+   */
+  cookieSecure?: boolean;
 }
 declare function resolveNextConfig(overrides?: Partial<NextServerConfig>): NextServerConfig;
 //#endregion
@@ -37,17 +44,36 @@ interface ServerSessionOptions {
   secret: string;
   cookies: CookieAdapter;
   cookieName?: string;
+  /**
+   * Whether to set the `Secure` attribute on the session cookie. Defaults to `true`
+   * (fail secure). Handlers derive it from the request transport so http/localhost dev
+   * works (a Secure cookie is dropped over http). See buildSessionCookieOptions.
+   */
+  secure?: boolean;
 }
 declare class ServerSession {
   private readonly authClient;
   private readonly secret;
   private readonly cookies;
   private readonly cookieName;
+  private readonly secure;
   constructor(options: ServerSessionOptions);
   establishFromCode(code: string, codeVerifier: string, redirectUri: string): Promise<StoredSession>;
   read(): Promise<StoredSession | null>;
   /** Rotate the tokens; clears the cookie (returns null) on a terminal refresh failure. */
   refresh(): Promise<StoredSession | null>;
+  /**
+   * End the session upstream, then locally. `device` revokes this session; `everywhere`
+   * revokes every session for the user (FR-SSO-5).
+   *
+   * Order is load-bearing: revocation is authenticated with the access token sealed in the
+   * cookie, so the cookie must be read before it is dropped. The upstream call is
+   * best-effort — an unreachable platform must not strand the user half-signed-in — but the
+   * call itself is real: the ecosystem logout the SDK used before resolves its session from
+   * a browser cookie, which a server-to-server fetch never carries, so it silently revoked
+   * nothing and answered 200.
+   */
+  revoke(scope?: "device" | "everywhere"): Promise<void>;
   clear(): void;
   private write;
 }
@@ -73,10 +99,77 @@ interface AuthHandlersConfig extends Partial<NextServerConfig> {
 }
 interface AuthHandlers {
   signin(request: Request): Promise<Response>;
+  /**
+   * The embedded `<SignIn/>` BFF endpoint: reads `{email, password}` (+ optional
+   * `organizationCode`/`tenantId`), runs the password authorize entirely
+   * server-side, and — on success — seals the httpOnly session before returning.
+   * The browser never sees the code, the tokens, or the credentials after POST.
+   */
+  authenticate(request: Request): Promise<Response>;
+  /**
+   * The `<ForgotPassword/>` BFF endpoint: reads `{email}`, adds this app's publishable
+   * key, and asks poly-auth to email a reset link server-side. Always relays a uniform
+   * `accepted` — it never reveals whether the account exists.
+   */
+  forgotPassword(request: Request): Promise<Response>;
+  /**
+   * The `<ResetPassword/>` BFF endpoint: reads `{token, newPassword}` and redeems the
+   * opaque single-use token. `success` on completion; `invalid_or_expired` otherwise.
+   */
+  resetPassword(request: Request): Promise<Response>;
   callback(request: Request): Promise<Response>;
   refresh(request: Request): Promise<Response>;
   signout(request: Request): Promise<Response>;
+  /**
+   * The client's view of the session: the same `AuthContext` `auth()` returns in a Server
+   * Component, as JSON. This is what makes client components work under BFF custody, where
+   * the browser holds no token and so cannot derive a session for itself — the hooks read
+   * server truth instead. Never carries a token.
+   */
+  session(request: Request): Promise<Response>;
 }
+/** The JSON the `forgotPassword` handler returns — always uniform (no enumeration). */
+type ForgotPasswordResult = {
+  status: "accepted";
+} | {
+  status: "invalid_request";
+};
+/** The JSON the `resetPassword` handler returns — the `<ResetPassword/>` form branches on `status`. */
+type ResetPasswordResult = {
+  status: "success";
+} | {
+  status: "weak_password";
+  minLength: number;
+} | {
+  status: "password_mismatch";
+} | {
+  status: "invalid_or_expired";
+} | {
+  status: "invalid_request";
+};
+/** The JSON the `authenticate` handler returns — the `<SignIn/>` form branches on `status`. */
+type AuthenticateResult = {
+  status: "success";
+  redirectTo: string;
+} | {
+  status: "select_tenant";
+  tenants: unknown[];
+  state: string;
+} | {
+  status: "password_change_required";
+  userId: string;
+} | {
+  status: "weak_password";
+  minLength: number;
+} | {
+  status: "password_mismatch";
+} | {
+  status: "no_access";
+} | {
+  status: "invalid_credentials";
+} | {
+  status: "invalid_request";
+};
 declare function createAuthHandlers(handlersConfig?: AuthHandlersConfig): AuthHandlers;
 //#endregion
-export { type AuthContext, AuthHandlers, AuthHandlersConfig, type CookieAdapter, type CookieSetOptions, DEFAULT_SESSION_COOKIE, type NextServerConfig, ServerSession, auth, createAuthHandlers, openSession, resolveNextConfig, sealSession };
+export { type AuthContext, AuthHandlers, AuthHandlersConfig, AuthenticateResult, type CookieAdapter, type CookieSetOptions, DEFAULT_SESSION_COOKIE, ForgotPasswordResult, type NextServerConfig, ResetPasswordResult, ServerSession, auth, createAuthHandlers, openSession, resolveNextConfig, sealSession };