authfyio-nextjs 0.2.3

package/README.md

@@ -0,0 +1,90 @@
+# authfyio-nextjs
+
+Next.js SDK for Authfyio. Ships middleware for the App Router edge runtime, a server-side session reader for Route Handlers and Server Components, and typed helpers that sit directly on top of `authfyio-backend`.
+
+## Install
+
+```bash
+npm install authfyio-nextjs
+```
+
+Next.js 14+ (App Router) and Node 20+.
+
+## Middleware (edge)
+
+Protect routes globally with one import. The middleware verifies the `__session` JWT at the edge — no database or origin round-trip.
+
+```ts
+// middleware.ts
+import type { NextRequest } from 'next/server';
+import { requireSessionMiddleware } from 'authfyio-nextjs';
+
+export async function middleware(req: NextRequest) {
+  return await requireSessionMiddleware(req, {
+    baseUrl: process.env.AF_API_BASE_URL!,
+    issuer: process.env.AF_JWT_ISSUER,
+    redirectTo: '/sign-in',
+  });
+}
+
+export const config = {
+  matcher: ['/app/:path*', '/api/private/:path*'],
+};
+```
+
+Unauthenticated requests to matched routes are redirected to `redirectTo` (or return a `401` for `/api/*` paths). The signed-in user's claims are forwarded as `x-af-user-id` and `x-af-env-id` headers so downstream handlers can read them without re-verifying.
+
+## Server Components & Route Handlers
+
+```ts
+// app/api/me/route.ts
+import { NextResponse } from 'next/server';
+import { getSessionFromNextRequest } from 'authfyio-nextjs';
+
+export async function GET(req: Request) {
+  const session = await getSessionFromNextRequest(req, {
+    baseUrl: process.env.AF_API_BASE_URL!,
+    issuer: process.env.AF_JWT_ISSUER,
+  });
+  if (!session) return NextResponse.json({ error: 'unauthenticated' }, { status: 401 });
+
+  return NextResponse.json({ userId: session.sub });
+}
+```
+
+## API
+
+### `requireSessionMiddleware(req, options)`
+
+| Option       | Type     | Required | Description                                                                                            |
+| ------------ | -------- | -------- | ------------------------------------------------------------------------------------------------------ |
+| `baseUrl`    | `string` | yes      | Instance API base URL.                                                                                 |
+| `issuer`     | `string` | no       | Expected `iss`. Strongly recommended in production.                                                    |
+| `audience`   | `string` | no       | Expected `aud`, if set.                                                                                |
+| `redirectTo` | `string` | no       | Where to send unauthenticated requests. When omitted, returns `401` with a JSON body.                  |
+| `publicPaths` | `string[]` | no    | Skip session enforcement for these paths (e.g. `['/health']`).                                         |
+
+### `getSessionFromNextRequest(req, options)`
+
+Pulls the `__session` cookie out of the request, verifies it, and returns the claims. Returns `null` when no cookie is present. Throws on an invalid token.
+
+## Environment variables
+
+Minimum set to wire up:
+
+```bash
+AF_API_BASE_URL=https://auth.example.com
+AF_JWT_ISSUER=https://auth.example.com/
+```
+
+## How it integrates with `authfyio-react`
+
+Browser-side: `authfyio-react` reads `__session` from cookies, exposes it via hooks, and refreshes it automatically.
+
+Edge/server-side: `authfyio-nextjs` re-verifies the same cookie in middleware and Server Components for defence-in-depth — a compromised browser cookie is rejected at the edge because JWKS verification still runs.
+
+You will almost always install both in a Next.js app.
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,43 @@
+import { type SessionClaims } from './session.js';
+export type AuthOptions = {
+    /**
+     * Base URL of the instance API (JWKS source). Defaults to
+     * https://api.authfyio.com or `process.env.AF_API_BASE_URL` if set.
+     */
+    baseUrl?: string;
+    /** Optional expected issuer. Matches `AF_JWT_ISSUER` on the API side. */
+    issuer?: string;
+    /** Optional expected audience. */
+    audience?: string;
+};
+export type AuthObject = {
+    userId: string | null;
+    sessionId: string | null;
+    orgId: string | null;
+    orgRole: string | null;
+    environmentId: string | null;
+    isSignedIn: boolean;
+    getToken: () => string | null;
+    claims: SessionClaims | null;
+};
+/**
+ * Server-side auth helper for Next.js App Router.
+ * Reads `__session` from the incoming cookie, verifies it via JWKS, and
+ * returns a flat object your server components / server actions / route
+ * handlers can use.
+ *
+ * When the middleware has already verified the request (see
+ * `authfyioMiddleware`), we prefer the decoded claims it forwarded via
+ * headers (`x-af-user-id`, `x-af-session-id`, `x-af-environment-id`). That
+ * avoids a second JWKS verification per request.
+ *
+ * Usage:
+ *     import { auth } from 'authfyio-nextjs';
+ *     export default async function Page() {
+ *       const { userId, isSignedIn } = await auth({ baseUrl: process.env.AF_API_BASE_URL! });
+ *       if (!isSignedIn) redirect('/sign-in');
+ *       return <p>Hi {userId}</p>;
+ *     }
+ */
+export declare function auth(opts?: AuthOptions): Promise<AuthObject>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAEpE,MAAM,MAAM,WAAW,GAAG;IACxB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,IAAI,CAAC,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CA2CtE"}

package/dist/auth.js

@@ -0,0 +1,77 @@
+import { cookies, headers } from 'next/headers';
+import { resolveBaseUrl } from './next.js';
+import { verifySessionJwt } from './session.js';
+/**
+ * Server-side auth helper for Next.js App Router.
+ * Reads `__session` from the incoming cookie, verifies it via JWKS, and
+ * returns a flat object your server components / server actions / route
+ * handlers can use.
+ *
+ * When the middleware has already verified the request (see
+ * `authfyioMiddleware`), we prefer the decoded claims it forwarded via
+ * headers (`x-af-user-id`, `x-af-session-id`, `x-af-environment-id`). That
+ * avoids a second JWKS verification per request.
+ *
+ * Usage:
+ *     import { auth } from 'authfyio-nextjs';
+ *     export default async function Page() {
+ *       const { userId, isSignedIn } = await auth({ baseUrl: process.env.AF_API_BASE_URL! });
+ *       if (!isSignedIn) redirect('/sign-in');
+ *       return <p>Hi {userId}</p>;
+ *     }
+ */
+export async function auth(opts = {}) {
+    const hdr = await headers();
+    const forwardedUserId = hdr.get('x-af-user-id');
+    const forwardedSessionId = hdr.get('x-af-session-id');
+    const forwardedEnvId = hdr.get('x-af-environment-id');
+    const cookieJar = await cookies();
+    const token = cookieJar.get('__session')?.value ?? null;
+    // Middleware has already verified — trust headers, skip JWKS round-trip.
+    if (forwardedUserId && forwardedSessionId && forwardedEnvId && token) {
+        return {
+            userId: forwardedUserId,
+            sessionId: forwardedSessionId,
+            orgId: hdr.get('x-af-org-id'),
+            orgRole: hdr.get('x-af-org-role'),
+            environmentId: forwardedEnvId,
+            isSignedIn: true,
+            getToken: () => token,
+            claims: null,
+        };
+    }
+    if (!token)
+        return emptyAuth();
+    try {
+        const claims = await verifySessionJwt(token, {
+            jwksUrl: `${resolveBaseUrl(opts)}/.well-known/jwks.json`,
+            issuer: opts.issuer,
+            audience: opts.audience,
+        });
+        return {
+            userId: claims.sub,
+            sessionId: claims.sid,
+            orgId: claims.org ?? null,
+            orgRole: claims.org_role ?? null,
+            environmentId: claims.env,
+            isSignedIn: true,
+            getToken: () => token,
+            claims,
+        };
+    }
+    catch {
+        return emptyAuth();
+    }
+}
+function emptyAuth() {
+    return {
+        userId: null,
+        sessionId: null,
+        orgId: null,
+        orgRole: null,
+        environmentId: null,
+        isSignedIn: false,
+        getToken: () => null,
+        claims: null,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './session.js';
+export * from './next.js';
+export * from './middleware.js';
+export * from './route-matcher.js';
+export * from './next-middleware.js';
+export * from './auth.js';
+export { createAuthfyioProxy, type AuthfyioProxyOptions } from './proxy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from './session.js';
+export * from './next.js';
+export * from './middleware.js';
+export * from './route-matcher.js';
+export * from './next-middleware.js';
+export * from './auth.js';
+export { createAuthfyioProxy } from './proxy.js';

package/dist/middleware.d.ts

@@ -0,0 +1,12 @@
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import { type AuthfyioNextOptions } from './next.js';
+export type RequireSessionMiddlewareOptions = AuthfyioNextOptions & {
+    /**
+     * If unauthorized, redirect here (e.g. "/sign-in").
+     * If omitted, returns 401.
+     */
+    redirectTo?: string;
+};
+export declare function requireSessionMiddleware(req: NextRequest, opts: RequireSessionMiddlewareOptions): Promise<NextResponse<unknown>>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAA6B,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAEhF,MAAM,MAAM,+BAA+B,GAAG,mBAAmB,GAAG;IAClE;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,wBAAsB,wBAAwB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,+BAA+B,kCAwBrG"}

package/dist/middleware.js

@@ -0,0 +1,27 @@
+import { NextResponse } from 'next/server';
+import { getSessionFromNextRequest } from './next.js';
+export async function requireSessionMiddleware(req, opts) {
+    try {
+        const session = await getSessionFromNextRequest(req, opts);
+        if (session) {
+            const res = NextResponse.next();
+            res.headers.set('x-af-user-id', session.sub);
+            res.headers.set('x-af-session-id', session.sid);
+            res.headers.set('x-af-environment-id', session.env);
+            return res;
+        }
+    }
+    catch {
+        // treat as unauthorized
+    }
+    if (opts.redirectTo) {
+        const url = req.nextUrl.clone();
+        url.pathname = opts.redirectTo;
+        url.searchParams.set('next', req.nextUrl.pathname);
+        return NextResponse.redirect(url);
+    }
+    return new NextResponse(JSON.stringify({ error: 'unauthorized' }), {
+        status: 401,
+        headers: { 'content-type': 'application/json' },
+    });
+}

package/dist/next-middleware.d.ts

@@ -0,0 +1,51 @@
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import { type AuthfyioNextOptions } from './next.js';
+import type { RouteMatcher } from './route-matcher.js';
+export type MiddlewareAuthContext = {
+    userId: string | null;
+    sessionId: string | null;
+    orgId: string | null;
+    orgRole: string | null;
+    environmentId: string | null;
+    isSignedIn: boolean;
+    /** Return a NextResponse.redirect to your sign-in page, preserving the caller path. */
+    redirectToSignIn: (signInUrl?: string) => NextResponse;
+    /** Return a 401 JSON response for API routes. */
+    unauthorized: () => NextResponse;
+};
+export type AuthfyioMiddlewareOptions = AuthfyioNextOptions & {
+    /** Default redirect target when protected route hits + user is signed out. */
+    signInUrl?: string;
+    /**
+     * Route matcher declaring which paths REQUIRE authentication. If omitted,
+     * the middleware verifies opportunistically but never blocks — protect
+     * via `auth.protect()` inside your handler instead.
+     */
+    isProtectedRoute?: RouteMatcher;
+    /**
+     * Optional custom handler — called with the verified auth context plus the
+     * request. Return `undefined` to continue with the default behavior, or any
+     * NextResponse to short-circuit.
+     */
+    handler?: (auth: MiddlewareAuthContext, req: NextRequest) => NextResponse | Promise<NextResponse | undefined> | undefined;
+};
+/**
+ * Next.js middleware that verifies `__session` on every request, forwards
+ * decoded claims as headers so `auth()` in server components can skip
+ * re-verification, and optionally guards routes selected by an
+ * `isProtectedRoute` matcher.
+ *
+ * Usage:
+ *     // middleware.ts
+ *     import { authfyioMiddleware, createRouteMatcher } from 'authfyio-nextjs';
+ *     const isProtected = createRouteMatcher(['/dashboard(.*)', '/api/private(.*)']);
+ *     export default authfyioMiddleware({
+ *       baseUrl: process.env.AF_API_BASE_URL!,
+ *       isProtectedRoute: isProtected,
+ *       signInUrl: '/sign-in',
+ *     });
+ *     export const config = { matcher: ['/((?!_next|.*\\..*).*)'] };
+ */
+export declare function authfyioMiddleware(opts: AuthfyioMiddlewareOptions): (req: NextRequest) => Promise<NextResponse>;
+//# sourceMappingURL=next-middleware.d.ts.map

package/dist/next-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next-middleware.d.ts","sourceRoot":"","sources":["../src/next-middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAA6B,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,UAAU,EAAE,OAAO,CAAC;IACpB,uFAAuF;IACvF,gBAAgB,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,YAAY,CAAC;IACvD,iDAAiD;IACjD,YAAY,EAAE,MAAM,YAAY,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG,mBAAmB,GAAG;IAC5D,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,YAAY,CAAC;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,qBAAqB,EAAE,GAAG,EAAE,WAAW,KAAK,YAAY,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;CAC3H,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,IAClD,KAAK,WAAW,KAAG,OAAO,CAAC,YAAY,CAAC,CA4CvD"}

package/dist/next-middleware.js

@@ -0,0 +1,65 @@
+import { NextResponse } from 'next/server';
+import { getSessionFromNextRequest } from './next.js';
+/**
+ * Next.js middleware that verifies `__session` on every request, forwards
+ * decoded claims as headers so `auth()` in server components can skip
+ * re-verification, and optionally guards routes selected by an
+ * `isProtectedRoute` matcher.
+ *
+ * Usage:
+ *     // middleware.ts
+ *     import { authfyioMiddleware, createRouteMatcher } from 'authfyio-nextjs';
+ *     const isProtected = createRouteMatcher(['/dashboard(.*)', '/api/private(.*)']);
+ *     export default authfyioMiddleware({
+ *       baseUrl: process.env.AF_API_BASE_URL!,
+ *       isProtectedRoute: isProtected,
+ *       signInUrl: '/sign-in',
+ *     });
+ *     export const config = { matcher: ['/((?!_next|.*\\..*).*)'] };
+ */
+export function authfyioMiddleware(opts) {
+    return async (req) => {
+        const claims = await getSessionFromNextRequest(req, opts).catch(() => null);
+        const ctx = {
+            userId: claims?.sub ?? null,
+            sessionId: claims?.sid ?? null,
+            orgId: claims?.org ?? null,
+            orgRole: claims?.org_role ?? null,
+            environmentId: claims?.env ?? null,
+            isSignedIn: !!claims,
+            redirectToSignIn: (signInUrl) => {
+                const url = req.nextUrl.clone();
+                url.pathname = signInUrl ?? opts.signInUrl ?? '/sign-in';
+                url.searchParams.set('redirect_url', req.nextUrl.pathname + req.nextUrl.search);
+                return NextResponse.redirect(url);
+            },
+            unauthorized: () => new NextResponse(JSON.stringify({ error: 'unauthorized' }), {
+                status: 401,
+                headers: { 'content-type': 'application/json' },
+            }),
+        };
+        if (opts.handler) {
+            const custom = await opts.handler(ctx, req);
+            if (custom)
+                return custom;
+        }
+        if (opts.isProtectedRoute && opts.isProtectedRoute(req) && !ctx.isSignedIn) {
+            // API routes get JSON 401; pages get a redirect.
+            if (req.nextUrl.pathname.startsWith('/api/'))
+                return ctx.unauthorized();
+            return ctx.redirectToSignIn();
+        }
+        // Forward claim headers so the server-side `auth()` helper can skip JWKS.
+        const res = NextResponse.next();
+        if (claims) {
+            res.headers.set('x-af-user-id', claims.sub);
+            res.headers.set('x-af-session-id', claims.sid);
+            res.headers.set('x-af-environment-id', claims.env);
+            if (claims.org)
+                res.headers.set('x-af-org-id', claims.org);
+            if (claims.org_role)
+                res.headers.set('x-af-org-role', claims.org_role);
+        }
+        return res;
+    };
+}

package/dist/next.d.ts

@@ -0,0 +1,23 @@
+import type { NextRequest } from 'next/server';
+import { type SessionClaims } from './session.js';
+/**
+ * Canonical Authfyio API URL. Customers using the hosted SaaS shouldn't
+ * have to set `AF_API_BASE_URL` — the default points at production. Override
+ * this only when self-hosting or pointing at a staging instance.
+ */
+export declare const DEFAULT_API_BASE_URL = "https://api.authfyio.com";
+export type AuthfyioNextOptions = {
+    /**
+     * Base URL of the instance API. Defaults to https://api.authfyio.com
+     * (the hosted SaaS). You only need to set this for self-hosted instances
+     * or staging.
+     */
+    baseUrl?: string;
+    issuer?: string;
+    audience?: string;
+};
+export declare function resolveBaseUrl(opts: AuthfyioNextOptions): string;
+export declare function getJwksUrl(opts: AuthfyioNextOptions): string;
+export declare function getSessionJwtFromNextRequest(req: NextRequest): string | null;
+export declare function getSessionFromNextRequest(req: NextRequest, opts: AuthfyioNextOptions): Promise<SessionClaims | null>;
+//# sourceMappingURL=next.d.ts.map

package/dist/next.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.d.ts","sourceRoot":"","sources":["../src/next.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,6BAA6B,CAAC;AAE/D,MAAM,MAAM,mBAAmB,GAAG;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,wBAAgB,cAAc,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAEhE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,mBAAmB,UAEnD;AAED,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAE5E;AAED,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAQ/B"}

package/dist/next.js

@@ -0,0 +1,26 @@
+import { verifySessionJwt } from './session.js';
+/**
+ * Canonical Authfyio API URL. Customers using the hosted SaaS shouldn't
+ * have to set `AF_API_BASE_URL` — the default points at production. Override
+ * this only when self-hosting or pointing at a staging instance.
+ */
+export const DEFAULT_API_BASE_URL = 'https://api.authfyio.com';
+export function resolveBaseUrl(opts) {
+    return (opts.baseUrl ?? process.env.AF_API_BASE_URL ?? DEFAULT_API_BASE_URL).replace(/\/+$/, '');
+}
+export function getJwksUrl(opts) {
+    return `${resolveBaseUrl(opts)}/.well-known/jwks.json`;
+}
+export function getSessionJwtFromNextRequest(req) {
+    return req.cookies.get('__session')?.value ?? null;
+}
+export async function getSessionFromNextRequest(req, opts) {
+    const token = getSessionJwtFromNextRequest(req);
+    if (!token)
+        return null;
+    return await verifySessionJwt(token, {
+        jwksUrl: getJwksUrl(opts),
+        issuer: opts.issuer,
+        audience: opts.audience,
+    });
+}

package/dist/proxy.d.ts

@@ -0,0 +1,34 @@
+import { NextResponse } from 'next/server';
+export type AuthfyioProxyOptions = {
+    /**
+     * Upstream base URL. Defaults to `process.env.AF_API_BASE_URL` or
+     * `https://api.authfyio.com`.
+     */
+    baseUrl?: string;
+};
+type RouteContext = {
+    params: Promise<{
+        path: string[];
+    }>;
+};
+/**
+ * Builds a set of route handlers bound to a specific upstream URL. Use this
+ * when you self-host the API or run multiple environments — pass the
+ * appropriate `baseUrl` per environment.
+ */
+export declare function createAuthfyioProxy(opts?: AuthfyioProxyOptions): {
+    GET: (req: Request, ctx: RouteContext) => Promise<NextResponse<unknown>>;
+    POST: (req: Request, ctx: RouteContext) => Promise<NextResponse<unknown>>;
+    PUT: (req: Request, ctx: RouteContext) => Promise<NextResponse<unknown>>;
+    PATCH: (req: Request, ctx: RouteContext) => Promise<NextResponse<unknown>>;
+    DELETE: (req: Request, ctx: RouteContext) => Promise<NextResponse<unknown>>;
+    OPTIONS: (req: Request, ctx: RouteContext) => Promise<NextResponse<unknown>>;
+};
+export declare const GET: (req: Request, ctx: RouteContext) => Promise<NextResponse<unknown>>;
+export declare const POST: (req: Request, ctx: RouteContext) => Promise<NextResponse<unknown>>;
+export declare const PUT: (req: Request, ctx: RouteContext) => Promise<NextResponse<unknown>>;
+export declare const PATCH: (req: Request, ctx: RouteContext) => Promise<NextResponse<unknown>>;
+export declare const DELETE: (req: Request, ctx: RouteContext) => Promise<NextResponse<unknown>>;
+export declare const OPTIONS: (req: Request, ctx: RouteContext) => Promise<NextResponse<unknown>>;
+export {};
+//# sourceMappingURL=proxy.d.ts.map

package/dist/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA8C3C,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,KAAK,YAAY,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC;AAiG5D;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,oBAAyB;eAC3C,OAAO,OAAO,YAAY;gBAA1B,OAAO,OAAO,YAAY;eAA1B,OAAO,OAAO,YAAY;iBAA1B,OAAO,OAAO,YAAY;kBAA1B,OAAO,OAAO,YAAY;mBAA1B,OAAO,OAAO,YAAY;EASjD;AAID,eAAO,MAAM,GAAG,QAbQ,OAAO,OAAO,YAAY,mCAaf,CAAC;AACpC,eAAO,MAAM,IAAI,QAdO,OAAO,OAAO,YAAY,mCAcb,CAAC;AACtC,eAAO,MAAM,GAAG,QAfQ,OAAO,OAAO,YAAY,mCAef,CAAC;AACpC,eAAO,MAAM,KAAK,QAhBM,OAAO,OAAO,YAAY,mCAgBX,CAAC;AACxC,eAAO,MAAM,MAAM,QAjBK,OAAO,OAAO,YAAY,mCAiBT,CAAC;AAC1C,eAAO,MAAM,OAAO,QAlBI,OAAO,OAAO,YAAY,mCAkBP,CAAC"}

package/dist/proxy.js

@@ -0,0 +1,149 @@
+import { NextResponse } from 'next/server';
+import { DEFAULT_API_BASE_URL } from './next.js';
+/**
+ * Same-origin reverse proxy for the Authfyio instance API. Customers mount
+ * this at `/api/af/[...path]/route.ts` so the React SDK's browser fetches
+ * stay on the customer's own origin — that's what makes the `__session` and
+ * `__client` cookies set by `api.authfyio.com` actually arrive at the
+ * customer's app.
+ *
+ * Without this proxy, cookies set on `api.authfyio.com` are scoped to that
+ * eTLD+1 and the browser refuses to send them to `myapp.com` (or
+ * `localhost:3000`). With this proxy, every Set-Cookie from upstream is
+ * re-emitted on the customer's origin with the `Domain=` attribute stripped,
+ * so the cookies land where the React SDK can use them.
+ *
+ * Usage:
+ *
+ *     // app/api/af/[...path]/route.ts
+ *     export {
+ *       GET, POST, PUT, PATCH, DELETE, OPTIONS,
+ *     } from 'authfyio-nextjs/proxy';
+ *
+ * The proxy resolves the upstream URL from `process.env.AF_API_BASE_URL`,
+ * falling back to `https://api.authfyio.com`. Override at call site by
+ * importing `createAuthfyioProxy({ baseUrl })` instead.
+ */
+const FORWARD_REQUEST_HEADERS = new Set([
+    'accept',
+    'accept-language',
+    'authorization',
+    'content-type',
+    'cookie',
+    'user-agent',
+    'x-authfyio-publishable-key',
+]);
+const STRIP_RESPONSE_HEADERS = new Set([
+    'transfer-encoding',
+    'content-encoding',
+    'content-length',
+    'connection',
+]);
+function resolveUpstream(opts) {
+    return (opts.baseUrl ?? process.env.AF_API_BASE_URL ?? DEFAULT_API_BASE_URL).replace(/\/+$/, '');
+}
+async function forward(req, ctx, opts) {
+    const upstreamBase = resolveUpstream(opts);
+    const { path } = await ctx.params;
+    const search = new URL(req.url).search;
+    // Special-case: OAuth bridge. The Authfyio API's OAuth callback
+    // 302s the browser to `${customer_origin}/api/af/oauth-finish?ott=…&to=…`.
+    // We exchange the one-time token for cookies (server-to-server POST
+    // with cookie: omitted), re-emit the Set-Cookie headers on our origin,
+    // and 302 the user to the `to` path so the browser lands at the app's
+    // intended destination already authenticated.
+    if (path[0] === 'oauth-finish') {
+        return await oauthFinish(req, upstreamBase);
+    }
+    const target = `${upstreamBase}/${path.map(encodeURIComponent).join('/')}${search}`;
+    const headers = {};
+    req.headers.forEach((value, key) => {
+        if (FORWARD_REQUEST_HEADERS.has(key.toLowerCase()))
+            headers[key] = value;
+    });
+    // Backstop the publishable-key header from the customer's server env.
+    // Browser fetch() requests with `credentials: 'include'` carry the
+    // header set by the React SDK, but top-level navigations (anchor
+    // clicks for OAuth /authorize, magic-link /verify GETs) don't. Without
+    // this, those requests would lose tenant identity on every page-level
+    // jump and the API would fall back to the env-pinned default.
+    if (!headers['x-authfyio-publishable-key']) {
+        const envKey = process.env.NEXT_PUBLIC_AUTHFYIO_PUBLISHABLE_KEY ?? process.env.AUTHFYIO_PUBLISHABLE_KEY;
+        if (envKey)
+            headers['x-authfyio-publishable-key'] = envKey;
+    }
+    const init = { method: req.method, headers, redirect: 'manual' };
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+        init.body = await req.arrayBuffer();
+    }
+    const upstream = await fetch(target, init);
+    const body = await upstream.arrayBuffer();
+    const res = new NextResponse(body, { status: upstream.status });
+    upstream.headers.forEach((value, key) => {
+        const k = key.toLowerCase();
+        if (STRIP_RESPONSE_HEADERS.has(k))
+            return;
+        if (k === 'set-cookie')
+            return;
+        res.headers.set(key, value);
+    });
+    // Re-emit Set-Cookie with Domain= stripped so the browser scopes the
+    // cookies to the customer's origin instead of api.authfyio.com.
+    const setCookies = upstream.headers.getSetCookie?.() ??
+        upstream.headers.get('set-cookie')?.split(/,(?=\s*\w+=)/) ??
+        [];
+    for (const raw of setCookies) {
+        res.headers.append('set-cookie', raw.replace(/;\s*Domain=[^;]+/i, ''));
+    }
+    return res;
+}
+async function oauthFinish(req, upstreamBase) {
+    const url = new URL(req.url);
+    const ott = url.searchParams.get('ott');
+    const to = url.searchParams.get('to') || '/';
+    if (!ott) {
+        return new NextResponse('missing_ott', { status: 400 });
+    }
+    const upstream = await fetch(`${upstreamBase}/v1/auth/oauth/redeem`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ ott }),
+        redirect: 'manual',
+    });
+    if (!upstream.ok) {
+        return new NextResponse(`oauth_redeem_failed_${upstream.status}`, { status: upstream.status });
+    }
+    // Build the 302 response to the customer's `to` URL with the
+    // upstream cookies re-emitted (Domain stripped) on our origin.
+    const res = NextResponse.redirect(new URL(to, req.url), 302);
+    const setCookies = upstream.headers.getSetCookie?.() ??
+        upstream.headers.get('set-cookie')?.split(/,(?=\s*\w+=)/) ??
+        [];
+    for (const raw of setCookies) {
+        res.headers.append('set-cookie', raw.replace(/;\s*Domain=[^;]+/i, ''));
+    }
+    return res;
+}
+/**
+ * Builds a set of route handlers bound to a specific upstream URL. Use this
+ * when you self-host the API or run multiple environments — pass the
+ * appropriate `baseUrl` per environment.
+ */
+export function createAuthfyioProxy(opts = {}) {
+    const handler = (req, ctx) => forward(req, ctx, opts);
+    return {
+        GET: handler,
+        POST: handler,
+        PUT: handler,
+        PATCH: handler,
+        DELETE: handler,
+        OPTIONS: handler,
+    };
+}
+const defaultProxy = createAuthfyioProxy();
+export const GET = defaultProxy.GET;
+export const POST = defaultProxy.POST;
+export const PUT = defaultProxy.PUT;
+export const PATCH = defaultProxy.PATCH;
+export const DELETE = defaultProxy.DELETE;
+export const OPTIONS = defaultProxy.OPTIONS;

package/dist/route-matcher.d.ts

@@ -0,0 +1,17 @@
+import type { NextRequest } from 'next/server';
+export type RouteMatcher = (req: NextRequest) => boolean;
+/**
+ * Returns a function that matches incoming Next.js requests against a list
+ * of route patterns.
+ *
+ * Patterns can be:
+ *   * Exact paths: '/about'
+ *   * Wildcards: '/admin(.*)' → matches '/admin', '/admin/users', etc.
+ *   * Parameter segments: '/users/:id' → '/users/42'
+ *   * RegExp objects: /^\/api\/.+/
+ *
+ * String patterns are compiled once into a RegExp that anchors at start AND
+ * end to prevent accidental prefix matches.
+ */
+export declare function createRouteMatcher(patterns: Array<string | RegExp>): RouteMatcher;
+//# sourceMappingURL=route-matcher.d.ts.map

package/dist/route-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-matcher.d.ts","sourceRoot":"","sources":["../src/route-matcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC;AAEzD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,YAAY,CASjF"}

package/dist/route-matcher.js

@@ -0,0 +1,45 @@
+/**
+ * Returns a function that matches incoming Next.js requests against a list
+ * of route patterns.
+ *
+ * Patterns can be:
+ *   * Exact paths: '/about'
+ *   * Wildcards: '/admin(.*)' → matches '/admin', '/admin/users', etc.
+ *   * Parameter segments: '/users/:id' → '/users/42'
+ *   * RegExp objects: /^\/api\/.+/
+ *
+ * String patterns are compiled once into a RegExp that anchors at start AND
+ * end to prevent accidental prefix matches.
+ */
+export function createRouteMatcher(patterns) {
+    const compiled = patterns.map((p) => (p instanceof RegExp ? p : compileStringPattern(p)));
+    return (req) => {
+        const pathname = req.nextUrl.pathname;
+        for (const re of compiled) {
+            if (re.test(pathname))
+                return true;
+        }
+        return false;
+    };
+}
+function compileStringPattern(pattern) {
+    // Escape regex metacharacters, then translate our allowed wildcards:
+    //   :param → [^/]+
+    //   (.*)   → left as-is (greedy wildcard, already regex)
+    //   *      → [^/]*
+    let src = pattern;
+    // Preserve explicit "(.*)" — user already opted into a full regex group.
+    // Split on "(.*)" so the escaper doesn't mangle the parens.
+    const parts = src.split(/(\(\.\*\))/g);
+    src = parts
+        .map((seg) => {
+        if (seg === '(.*)')
+            return '.*';
+        return seg
+            .replace(/[\\^$+?.()|[\]{}]/g, '\\$&')
+            .replace(/\*/g, '[^/]*')
+            .replace(/:([A-Za-z0-9_]+)/g, '[^/]+');
+    })
+        .join('');
+    return new RegExp(`^${src}\\/?$`);
+}

package/dist/session.d.ts

@@ -0,0 +1,19 @@
+export type SessionClaims = {
+    sid: string;
+    sub: string;
+    env: string;
+    org?: string;
+    org_role?: string;
+    iat?: number;
+    exp?: number;
+    iss?: string;
+    aud?: string | string[];
+};
+export type VerifySessionJwtOptions = {
+    jwksUrl: string;
+    issuer?: string;
+    audience?: string;
+    clockToleranceSeconds?: number;
+};
+export declare function verifySessionJwt(token: string, opts: VerifySessionJwtOptions): Promise<SessionClaims>;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,aAAa,CAAC,CAQ3G"}

package/dist/session.js

@@ -0,0 +1,10 @@
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+export async function verifySessionJwt(token, opts) {
+    const jwks = createRemoteJWKSet(new URL(opts.jwksUrl));
+    const { payload } = await jwtVerify(token, jwks, {
+        issuer: opts.issuer,
+        audience: opts.audience,
+        clockTolerance: opts.clockToleranceSeconds,
+    });
+    return payload;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "authfyio-nextjs",
+  "version": "0.2.3",
+  "description": "Next.js helpers for Authfyio — middleware, route matchers, server-side auth(), built-in cookie-bridge proxy.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./proxy": {
+      "types": "./dist/proxy.d.ts",
+      "default": "./dist/proxy.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "next": ">=14"
+  },
+  "dependencies": {
+    "jose": "^5.9.6"
+  },
+  "keywords": [
+    "authfyio",
+    "auth",
+    "authentication",
+    "nextjs",
+    "middleware",
+    "jwt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://authfyio.com/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/authfyio/authfyio.git"
+  }
+}