@poly-x/next 0.1.1 → 0.3.0

package/README.md

@@ -4,57 +4,200 @@ PolyX authentication for the Next.js App Router. Everything in `@poly-x/react`,
 plus a server side: tokens live **AES-GCM-encrypted in an httpOnly cookie on your
 own domain** — browser JavaScript never sees them.
 
-## Install
+## Adopt it in three files
+
+Install, set two environment values, add three files. None of them contains
+security logic.
 
 ```bash
 npm install @poly-x/next
 ```
 
-Set two env vars: `NEXT_PUBLIC_POLYX_PUBLISHABLE_KEY` (the `pk_…` key) and
-`POLYX_SESSION_SECRET` (used to encrypt the session cookie).
+```bash
+NEXT_PUBLIC_POLYX_PUBLISHABLE_KEY=pk_test_…   # your app's publishable key
+POLYX_SESSION_SECRET=…                        # encrypts the session cookie
+```
 
-## Client
+**1. Mount the routes.** One declaration mounts every action:
 
-The client entry re-exports `@poly-x/react` — `PolyXProvider`, hooks, `<SignIn>`,
-`<Protected>`, and friends:
+```ts
+// app/api/polyx/[...polyx]/route.ts
+import { createPolyXHandler } from "@poly-x/next/server";
 
-```tsx
-import { PolyXProvider } from "@poly-x/next";
+export const { GET, POST } = createPolyXHandler();
+```
+
+**2. Gate your routes** (Next 16 `proxy.ts`; `middleware.ts` on ≤15):
+
+```ts
+// proxy.ts
+import { proxy } from "@poly-x/next/proxy";
+
+export default proxy({ protectedRoutes: ["/dashboard"] });
 ```
 
-## Server
+**3. Declare each backend you call.** Because the browser holds no token, calls to
+your own API are proxied server-side — you declare the upstream, the SDK attaches
+the credential, refreshes it on expiry and retries once:
 
-Read the session in a Server Component or route handler (read-only — Server
-Components can't set cookies):
+```ts
+// app/api/billing/proxy/[...path]/route.ts
+import { createDataProxy } from "@poly-x/next/server";
+
+export const { GET, POST, PUT, PATCH, DELETE } = createDataProxy({
+  upstream: process.env.BILLING_URL!,
+  label: "Billing",
+});
+```
+
+Point your existing client at `/api/billing/proxy` instead of the upstream. No
+call sites change beyond the base URL.
+
+## Reading the session
+
+**Server** — `auth()` is read-only, so it is safe in a Server Component:
 
 ```ts
 import { auth } from "@poly-x/next/server";
 
-export default async function Page() {
+export async function currentUserId(): Promise<string | null> {
   const { isSignedIn, userId } = await auth();
-  // …
+  return isSignedIn ? userId : null;
 }
 ```
 
-Mount the route handlers that own every cookie write (login / callback / refresh
-/ signout):
+For the full profile from the platform, use `getSessionContext()`. It distinguishes
+"the directory is briefly unavailable" from "signed out", so a transient outage
+never signs your users out:
 
 ```ts
-// app/api/polyx/[...action]/route.ts
-import { createAuthHandlers } from "@poly-x/next/server";
-export const { signin: GET } = createAuthHandlers();
+import { getSessionContext } from "@poly-x/next/server";
+
+export async function loadProfile() {
+  const ctx = await getSessionContext();
+  if (ctx.isSignedIn && ctx.profileStatus === "unavailable") {
+    // still signed in — the profile just could not be loaded right now
+    return null;
+  }
+  return ctx.user;
+}
+```
+
+**Client** — the hooks work with no provider under this custody model:
+
+```tsx
+"use client";
+import { useAuth, useUser } from "@poly-x/next";
+
+export function Profile() {
+  const { isLoaded, isSignedIn, signOut, refresh } = useAuth();
+  const user = useUser();
+  if (!isLoaded) return null;
+  if (!isSignedIn) return <a href="/sign-in">Sign in</a>;
+  return (
+    <div>
+      <span>{user?.email}</span>
+      <button onClick={() => void refresh()}>Re-check permissions</button>
+      <button onClick={() => void signOut({ redirectTo: "/sign-in" })}>Sign out</button>
+    </div>
+  );
+}
 ```
 
-Gate routes with the proxy (Next 16 `proxy.ts`; `middleware.ts` on ≤15):
+`signOut()` performs the full-page navigation this custody model requires — a
+client-side redirect would leave the httpOnly cookie in place and your route gate
+would bounce the user straight back in. Do not hand-roll it.
+
+`refresh()` re-reads authorization and resolves `true` only when the claims
+actually changed; pair it with `useLiveAuthz` to re-guard a tab without a reload.
+
+`consumeAuthEvent()` returns `"signed-in" | "signed-out" | null` once after the
+navigation, for a toast or an analytics call that would otherwise be destroyed
+when the page unloads.
+
+## Styles
+
+If you render `<SignIn>` or `<UserButton>`, import the stylesheet **before** your
+Tailwind entry. Cascade-layer order is fixed at first declaration, so importing it
+later silently loses to your utilities:
 
 ```ts
-import { proxy } from "@poly-x/next/proxy";
-export const proxy = proxyHandler; // from proxy({ protectedRoutes: ["/dashboard"] })
+// app/layout.tsx
+import "@poly-x/next/styles.css";
+import "./globals.css";
 ```
 
+## When something goes wrong
+
+| Symptom | Cause |
+|---|---|
+| `401` from a proxied call, no upstream request made | No session, or the cookie would not unseal (rotated `POLYX_SESSION_SECRET`). |
+| `401` from a proxied call to a path you did not declare | Only declared upstreams receive a credential. |
+| `{ status: "configuration_error", code: "REDIRECT_URI_NOT_ALLOWED" }` | The redirect URI the SDK sent is not registered. Behind a proxy set `POLYX_PUBLIC_ORIGIN`, or enable `POLYX_TRUST_FORWARDED_ORIGIN` — `request.url` is the bind address. The server log names the URI actually used. |
+| `{ status: "session_too_large" }` | The sealed session exceeds the ~4096-byte browser cookie limit. Usually a tenant configured to embed full permissions in the JWT. |
+| Sign-in returns 200 but the user is never signed in | Upgrade to ≥ 0.1.1 — earlier versions wrote an oversized cookie the browser silently discarded. |
+
+## Profile self-service
+
+`createPolyXHandler()` also mounts `/api/polyx/profile`, which backs
+`<UserProfile>` — nothing extra to wire. It reads and updates **only** the
+signed-in person's own profile: the identity comes from the sealed session, never
+from the request, so it cannot be aimed at anyone else.
+
+The submitted body is rebuilt from an allow-list rather than forwarded. The
+platform's update applies whatever recognised fields it receives — including
+`email`, `password` and `role` — so relaying a browser's multipart verbatim would
+turn a profile form into a way to change a credential or grant a role. Only the
+six profile fields ever leave the server.
+
+## Cross-application sign-on and switching workspace
+
+`createPolyXHandler()` also mounts `/api/polyx/hop` and `/api/polyx/hop-complete`. You do not
+call these directly — `@poly-x/react`'s `useWarmHop()` and `switchWorkspace()` drive them.
+
+**The attempt is made by the browser, and it has to be.** The platform recognises a returning
+person from an ecosystem cookie set on *its own* domain. Your server does not have that cookie,
+so a server-side attempt is told "sign-in required" every single time — correctly, and
+indistinguishably from someone who genuinely is signed out. The feature would look implemented
+and never once work.
+
+So the routes bracket a browser-made request rather than making one:
+
+- **`hop`** mints the PKCE pair, keeps the verifier in an httpOnly cookie, and returns only a
+  URL. It makes no request of its own.
+- **`hop-complete`** takes the `code` the browser received and exchanges it here. The code is
+  safe for a page to hold precisely because the verifier that redeems it never left your server.
+
+Because of that, calling `completeAuthorize()` from server code **throws**
+(`WARM_HOP_ON_SERVER`) rather than returning the plausible answer.
+
+Register your `/api/polyx/callback` on the App even though nothing redirects to it during a
+hop — the platform validates `redirect_uri` on both the authorize and the exchange.
+
+> **Warm hop needs https end to end** (or a `localhost` dev setup). The platform issues its
+> ecosystem cookie with `Secure`, and a browser silently discards a `Secure` cookie delivered
+> over http. Nothing reports this: sign-in still succeeds, the `Set-Cookie` header is still
+> there, and every hop afterwards reports "sign-in required" — indistinguishable from someone
+> who is genuinely signed out. `localhost` is the one host browsers exempt.
+
+### The boundary, stated plainly
+
+**This works between applications that share the ecosystem cookie's domain.** Browsers block
+third-party cookies by default, so an application on an unrelated domain cannot see that cookie
+and will fall back to ordinary sign-in. That is a browser policy, not a limitation we can
+configure away — solving it needs a different mechanism entirely. Nothing here claims otherwise.
+
+Switching workspace is unaffected by that boundary: it happens inside one application.
+
 ## Exports
 
-`@poly-x/next` (client) · `@poly-x/next/server` (`auth`, `createAuthHandlers`,
-`ServerSession`) · `@poly-x/next/proxy` (`proxy`).
+- `@poly-x/next` — the client surface (re-exports `@poly-x/react`): `PolyXProvider`,
+  `useAuth`, `useUser`, `useSession`, `useLiveAuthz`, `consumeAuthEvent`, `<SignIn>`,
+  `<UserButton>`, `<UserProfile>`, `<Protected>`.
+- `@poly-x/next/server` — `createPolyXHandler`, `createDataProxy`, `auth`,
+  `getSessionContext`, `refreshSession`, `createAuthHandlers`, `ServerSession`,
+  `sealSession` / `openSession`, `SESSION_COOKIE_MAX_BYTES`, `resolvePublicOrigin`.
+- `@poly-x/next/proxy` — `proxy`, `DEFAULT_SESSION_COOKIE`, `readSessionCookie`
+  (edge-safe: no server-only imports).
 
 MIT licensed.

package/dist/index.cjs

@@ -2,7 +2,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/index.ts
 const PACKAGE_NAME = "@poly-x/next";
-const version = "0.0.0";
+/** The published version of this package, injected at build time. */
+const version = "0.3.0";
 //#endregion
 exports.PACKAGE_NAME = PACKAGE_NAME;
 exports.version = version;

package/dist/index.d.cts

@@ -2,6 +2,7 @@ export * from "@poly-x/react";
 
 //#region src/index.d.ts
 declare const PACKAGE_NAME = "@poly-x/next";
-declare const version = "0.0.0";
+/** The published version of this package, injected at build time. */
+declare const version: string;
 //#endregion
 export { PACKAGE_NAME, version };

package/dist/index.d.mts

@@ -2,6 +2,7 @@ export * from "@poly-x/react";
 
 //#region src/index.d.ts
 declare const PACKAGE_NAME = "@poly-x/next";
-declare const version = "0.0.0";
+/** The published version of this package, injected at build time. */
+declare const version: string;
 //#endregion
 export { PACKAGE_NAME, version };

package/dist/index.mjs

@@ -2,6 +2,7 @@
 export * from "@poly-x/react";
 //#region src/index.ts
 const PACKAGE_NAME = "@poly-x/next";
-const version = "0.0.0";
+/** The published version of this package, injected at build time. */
+const version = "0.3.0";
 //#endregion
 export { PACKAGE_NAME, version };

package/dist/proxy.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-require("./server-session-Df9HXl_5.cjs");
+const require_session_cookie = require("./session-cookie-BQD10B3D.cjs");
 let next_server = require("next/server");
 //#region src/proxy.ts
 /**
@@ -8,17 +8,37 @@ let next_server = require("next/server");
 * gates on the session cookie's *presence* (a fast edge check) and redirects
 * signed-out users to sign-in; `auth()` does the real decrypt server-side.
 */
-function isProtected(pathname, routes) {
-	return routes.some((route) => typeof route === "string" ? pathname.startsWith(route) : route.test(pathname));
+/**
+* Make a matcher that gives the same answer every time it is called.
+*
+* `RegExp.prototype.test` advances `lastIndex` when the pattern carries `g` or `y`, so testing the
+* SAME regex object repeatedly alternates true/false/true. This middleware holds the consumer's
+* patterns for the lifetime of the process and tests them once per request — so a consumer writing
+* `/^\/admin/g`, an easy habit, would have their protected routes gated on every OTHER request.
+* That fails **open**, intermittently, and is close to undebuggable from the outside.
+*
+* The stateful flags are stripped into a fresh regex here, once at construction: no per-request
+* allocation, and the consumer's own object is left untouched (they may be using it elsewhere, and
+* resetting its `lastIndex` behind their back would be its own surprise).
+*/
+function toMatcher(route) {
+	if (typeof route === "string") return (pathname) => pathname.startsWith(route);
+	if (!route.global && !route.sticky) return (pathname) => route.test(pathname);
+	const stateless = new RegExp(route.source, route.flags.replace(/[gy]/g, ""));
+	return (pathname) => stateless.test(pathname);
 }
 function proxy(config) {
 	const cookieName = config.cookieName ?? "polyx_session";
 	const signInPath = config.signInPath ?? "/api/polyx/signin";
+	const matchers = config.protectedRoutes.map(toMatcher);
+	const isProtected = (pathname) => matchers.some((match) => match(pathname));
 	return (request) => {
-		if (!isProtected(request.nextUrl.pathname, config.protectedRoutes)) return next_server.NextResponse.next();
+		if (!isProtected(request.nextUrl.pathname)) return next_server.NextResponse.next();
 		if (request.cookies.get(cookieName)?.value) return next_server.NextResponse.next();
 		return next_server.NextResponse.redirect(new URL(signInPath, request.url));
 	};
 }
 //#endregion
+exports.DEFAULT_SESSION_COOKIE = require_session_cookie.DEFAULT_SESSION_COOKIE;
 exports.proxy = proxy;
+exports.readSessionCookie = require_session_cookie.readSessionCookie;

package/dist/proxy.d.cts

@@ -1,3 +1,4 @@
+import { n as readSessionCookie, t as DEFAULT_SESSION_COOKIE } from "./session-cookie-AEnY4PVW.cjs";
 import { NextRequest, NextResponse } from "next/server";
 
 //#region src/proxy.d.ts
@@ -10,4 +11,4 @@ interface ProxyConfig {
 }
 declare function proxy(config: ProxyConfig): (request: NextRequest) => NextResponse;
 //#endregion
-export { ProxyConfig, proxy };
+export { DEFAULT_SESSION_COOKIE, ProxyConfig, proxy, readSessionCookie };

package/dist/proxy.d.mts

@@ -1,3 +1,4 @@
+import { n as readSessionCookie, t as DEFAULT_SESSION_COOKIE } from "./session-cookie-AEnY4PVW.mjs";
 import { NextRequest, NextResponse } from "next/server";
 
 //#region src/proxy.d.ts
@@ -10,4 +11,4 @@ interface ProxyConfig {
 }
 declare function proxy(config: ProxyConfig): (request: NextRequest) => NextResponse;
 //#endregion
-export { ProxyConfig, proxy };
+export { DEFAULT_SESSION_COOKIE, ProxyConfig, proxy, readSessionCookie };

package/dist/proxy.mjs

@@ -1,4 +1,4 @@
-import "./server-session-pY-nzh5x.mjs";
+import { n as readSessionCookie, t as DEFAULT_SESSION_COOKIE } from "./session-cookie-C23WspJZ.mjs";
 import { NextResponse } from "next/server";
 //#region src/proxy.ts
 /**
@@ -7,17 +7,35 @@ import { NextResponse } from "next/server";
 * gates on the session cookie's *presence* (a fast edge check) and redirects
 * signed-out users to sign-in; `auth()` does the real decrypt server-side.
 */
-function isProtected(pathname, routes) {
-	return routes.some((route) => typeof route === "string" ? pathname.startsWith(route) : route.test(pathname));
+/**
+* Make a matcher that gives the same answer every time it is called.
+*
+* `RegExp.prototype.test` advances `lastIndex` when the pattern carries `g` or `y`, so testing the
+* SAME regex object repeatedly alternates true/false/true. This middleware holds the consumer's
+* patterns for the lifetime of the process and tests them once per request — so a consumer writing
+* `/^\/admin/g`, an easy habit, would have their protected routes gated on every OTHER request.
+* That fails **open**, intermittently, and is close to undebuggable from the outside.
+*
+* The stateful flags are stripped into a fresh regex here, once at construction: no per-request
+* allocation, and the consumer's own object is left untouched (they may be using it elsewhere, and
+* resetting its `lastIndex` behind their back would be its own surprise).
+*/
+function toMatcher(route) {
+	if (typeof route === "string") return (pathname) => pathname.startsWith(route);
+	if (!route.global && !route.sticky) return (pathname) => route.test(pathname);
+	const stateless = new RegExp(route.source, route.flags.replace(/[gy]/g, ""));
+	return (pathname) => stateless.test(pathname);
 }
 function proxy(config) {
 	const cookieName = config.cookieName ?? "polyx_session";
 	const signInPath = config.signInPath ?? "/api/polyx/signin";
+	const matchers = config.protectedRoutes.map(toMatcher);
+	const isProtected = (pathname) => matchers.some((match) => match(pathname));
 	return (request) => {
-		if (!isProtected(request.nextUrl.pathname, config.protectedRoutes)) return NextResponse.next();
+		if (!isProtected(request.nextUrl.pathname)) return NextResponse.next();
 		if (request.cookies.get(cookieName)?.value) return NextResponse.next();
 		return NextResponse.redirect(new URL(signInPath, request.url));
 	};
 }
 //#endregion
-export { proxy };
+export { DEFAULT_SESSION_COOKIE, proxy, readSessionCookie };