@ulexid/nextjs 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# @ulexid/nextjs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Version `0.1.1` — [Ulexid Documentation](https://docs.ulexid.com)
+
+Next.js App Router and Middleware helpers for [Ulexid](https://www.ulexid.com).
+
+```bash
+npm install @ulexid/nextjs
+```
+
+## License
+
+Proprietary (`UNLICENSED`). Copyright (c) Ulexid. All rights reserved.

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `@ulexid/nextjs` — Next.js App Router Route Handlers & Edge Middleware for ulex.
+ *
+ * Built against standard Web `Request` / `Response` (`NextRequest` extends
+ * `Request`, `NextResponse` extends `Response`) so it works across Next.js 14,
+ * 15, and 16 in both Edge and Node.js runtimes with zero framework lock-in.
+ *
+ * Security properties:
+ * - PKCE `S256` state + verifier is AES-256-GCM sealed inside a short-lived
+ *   `HttpOnly; SameSite=Lax` cookie (`__ulex_pkce`) derived from `cookieSecret`.
+ * - Session tokens are stored in `HttpOnly; SameSite=Lax` cookies (`__ulex_session`)
+ *   and cryptographically verified against the tenant JWKS via `@ulexid/node`.
+ * - Open-redirect protection restricts `returnTo` to relative same-origin paths.
+ */
+import { UlexClient, type FetchLike } from '@ulexid/js';
+import { UlexServerClient, type VerifiedAccessToken } from '@ulexid/node';
+export declare const ULEX_SESSION_COOKIE = "__ulex_session";
+export declare const ULEX_PKCE_COOKIE = "__ulex_pkce";
+export interface UlexNextConfig {
+    readonly issuer: string;
+    readonly clientId: string;
+    readonly clientSecret?: string;
+    /** Exact registered OAuth callback URL, e.g. `https://app.acme.com/api/auth/callback`. */
+    readonly redirectUri: string;
+    /** At least 32 characters; used to AES-256-GCM seal transient PKCE state cookies. */
+    readonly cookieSecret: string;
+    readonly scopes?: readonly string[];
+    readonly audience?: string | readonly string[];
+    readonly postLoginRedirect?: string;
+    readonly postLogoutRedirect?: string;
+    /** Defaults to `true` when `redirectUri` starts with `https://`. */
+    readonly secureCookies?: boolean;
+    readonly fetch?: FetchLike;
+}
+export interface UlexNextSession {
+    readonly accessToken: string;
+    readonly verified: VerifiedAccessToken;
+}
+export declare function parseCookieHeader(cookieHeader: string | null): Record<string, string>;
+export declare function createUlexNextClients(config: UlexNextConfig): {
+    oauth: UlexClient;
+    server: UlexServerClient;
+};
+/**
+ * Verifies the `__ulex_session` cookie (or `Authorization: Bearer` header) on an
+ * incoming Next.js `Request` / `NextRequest` against the tenant JWKS.
+ */
+export declare function getUlexSession(request: Request, config: UlexNextConfig, serverOverride?: UlexServerClient): Promise<UlexNextSession | null>;
+/**
+ * Creates Next.js App Router `GET` route handlers for:
+ * - `/api/auth/login` (`handlers.login`)
+ * - `/api/auth/callback` (`handlers.callback`)
+ * - `/api/auth/logout` (`handlers.logout`)
+ * - `/api/auth/me` (`handlers.me`)
+ */
+export declare function createAuthRouteHandlers(config: UlexNextConfig): {
+    login(request: Request): Promise<Response>;
+    callback(request: Request): Promise<Response>;
+    logout(request: Request): Promise<Response>;
+    me(request: Request): Promise<Response>;
+};
+export interface AuthMiddlewareOptions extends UlexNextConfig {
+    /** Path prefixes that do NOT require authentication (e.g. `['/', '/api/auth', '/pricing']`). */
+    readonly publicPaths?: readonly string[];
+    /** Path to redirect unauthenticated browser requests to (default: `'/api/auth/login'`). */
+    readonly loginPath?: string;
+}
+/**
+ * Edge-compatible middleware helper: returns `null` when the request is public or
+ * carries a valid ulex session, or returns a `302` redirect / `401` JSON `Response`
+ * when unauthenticated.
+ */
+export declare function createUlexMiddleware(options: AuthMiddlewareOptions): (request: Request) => Promise<Response | null>;

package/dist/index.js

@@ -0,0 +1,261 @@
+/**
+ * `@ulexid/nextjs` — Next.js App Router Route Handlers & Edge Middleware for ulex.
+ *
+ * Built against standard Web `Request` / `Response` (`NextRequest` extends
+ * `Request`, `NextResponse` extends `Response`) so it works across Next.js 14,
+ * 15, and 16 in both Edge and Node.js runtimes with zero framework lock-in.
+ *
+ * Security properties:
+ * - PKCE `S256` state + verifier is AES-256-GCM sealed inside a short-lived
+ *   `HttpOnly; SameSite=Lax` cookie (`__ulex_pkce`) derived from `cookieSecret`.
+ * - Session tokens are stored in `HttpOnly; SameSite=Lax` cookies (`__ulex_session`)
+ *   and cryptographically verified against the tenant JWKS via `@ulexid/node`.
+ * - Open-redirect protection restricts `returnTo` to relative same-origin paths.
+ */
+import { generatePkcePair, generateState, UlexClient, } from '@ulexid/js';
+import { UlexServerClient, } from '@ulexid/node';
+export const ULEX_SESSION_COOKIE = '__ulex_session';
+export const ULEX_PKCE_COOKIE = '__ulex_pkce';
+function toBase64Url(bytes) {
+    return Buffer.from(bytes).toString('base64url');
+}
+function fromBase64Url(encoded) {
+    return new Uint8Array(Buffer.from(encoded, 'base64url'));
+}
+async function deriveAesKey(secret) {
+    if (secret.length < 32) {
+        throw new RangeError('`cookieSecret` must be at least 32 characters long.');
+    }
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(secret));
+    return globalThis.crypto.subtle.importKey('raw', digest, { name: 'AES-GCM' }, false, [
+        'encrypt',
+        'decrypt',
+    ]);
+}
+async function sealJson(payload, secret) {
+    const key = await deriveAesKey(secret);
+    const iv = new Uint8Array(12);
+    globalThis.crypto.getRandomValues(iv);
+    const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+    const ciphertext = await globalThis.crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, plaintext);
+    return `${toBase64Url(iv)}.${toBase64Url(new Uint8Array(ciphertext))}`;
+}
+async function unsealJson(token, secret) {
+    const dot = token.indexOf('.');
+    if (dot <= 0)
+        return null;
+    try {
+        const key = await deriveAesKey(secret);
+        const iv = fromBase64Url(token.slice(0, dot));
+        const ciphertext = fromBase64Url(token.slice(dot + 1));
+        const plaintext = await globalThis.crypto.subtle.decrypt({ name: 'AES-GCM', iv: iv }, key, ciphertext);
+        return JSON.parse(new TextDecoder().decode(plaintext));
+    }
+    catch {
+        return null;
+    }
+}
+export function parseCookieHeader(cookieHeader) {
+    if (!cookieHeader)
+        return {};
+    const out = {};
+    for (const part of cookieHeader.split(';')) {
+        const eq = part.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const k = part.slice(0, eq).trim();
+        const v = part.slice(eq + 1).trim();
+        if (k)
+            out[k] = decodeURIComponent(v);
+    }
+    return out;
+}
+function serializeCookie(name, value, opts) {
+    const parts = [
+        `${name}=${encodeURIComponent(value)}`,
+        `Path=${opts.path ?? '/'}`,
+        `Max-Age=${opts.maxAge}`,
+        'HttpOnly',
+        'SameSite=Lax',
+    ];
+    if (opts.secure)
+        parts.push('Secure');
+    return parts.join('; ');
+}
+function sanitizeRelativeReturnTo(raw, fallback) {
+    if (!raw)
+        return fallback;
+    // Block protocol-relative `//evil.com`, absolute URLs, and backslash tricks.
+    if (!raw.startsWith('/') || raw.startsWith('//') || raw.includes('\\')) {
+        return fallback;
+    }
+    return raw;
+}
+export function createUlexNextClients(config) {
+    const oauth = new UlexClient({
+        issuer: config.issuer,
+        clientId: config.clientId,
+        redirectUri: config.redirectUri,
+        fetch: config.fetch,
+    });
+    const server = new UlexServerClient({
+        issuer: config.issuer,
+        clientId: config.clientId,
+        clientSecret: config.clientSecret,
+        audience: config.audience,
+        fetch: config.fetch,
+    });
+    return { oauth, server };
+}
+/**
+ * Verifies the `__ulex_session` cookie (or `Authorization: Bearer` header) on an
+ * incoming Next.js `Request` / `NextRequest` against the tenant JWKS.
+ */
+export async function getUlexSession(request, config, serverOverride) {
+    const authHeader = request.headers.get('authorization');
+    let rawToken;
+    if (authHeader?.toLowerCase().startsWith('bearer ')) {
+        rawToken = authHeader.slice(7).trim();
+    }
+    else {
+        const cookies = parseCookieHeader(request.headers.get('cookie'));
+        rawToken = cookies[ULEX_SESSION_COOKIE];
+    }
+    if (!rawToken)
+        return null;
+    const server = serverOverride ?? createUlexNextClients(config).server;
+    try {
+        const verified = await server.verifyAccessToken(rawToken);
+        return { accessToken: rawToken, verified };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Creates Next.js App Router `GET` route handlers for:
+ * - `/api/auth/login` (`handlers.login`)
+ * - `/api/auth/callback` (`handlers.callback`)
+ * - `/api/auth/logout` (`handlers.logout`)
+ * - `/api/auth/me` (`handlers.me`)
+ */
+export function createAuthRouteHandlers(config) {
+    const { oauth, server } = createUlexNextClients(config);
+    const secure = config.secureCookies ?? config.redirectUri.startsWith('https://');
+    const defaultPostLogin = config.postLoginRedirect ?? '/';
+    return {
+        async login(request) {
+            const reqUrl = new URL(request.url);
+            const returnTo = sanitizeRelativeReturnTo(reqUrl.searchParams.get('returnTo'), defaultPostLogin);
+            const organization = reqUrl.searchParams.get('organization') ?? undefined;
+            const loginHint = reqUrl.searchParams.get('login_hint') ?? undefined;
+            const pkce = await generatePkcePair();
+            const state = generateState();
+            const authorizeUrl = oauth.buildAuthorizeUrl({
+                codeChallenge: pkce.challenge,
+                state,
+                redirectUri: config.redirectUri,
+                scopes: config.scopes ?? ['openid', 'profile', 'email'],
+                organization,
+                loginHint,
+            });
+            const sealed = await sealJson({
+                state,
+                verifier: pkce.verifier,
+                returnTo,
+                exp: Math.floor(Date.now() / 1000) + 600,
+            }, config.cookieSecret);
+            const headers = new Headers({ location: authorizeUrl });
+            headers.append('set-cookie', serializeCookie(ULEX_PKCE_COOKIE, sealed, { maxAge: 600, secure }));
+            return new Response(null, { status: 302, headers });
+        },
+        async callback(request) {
+            const reqUrl = new URL(request.url);
+            const code = reqUrl.searchParams.get('code');
+            const state = reqUrl.searchParams.get('state');
+            if (!code || !state) {
+                return Response.json({ error: { code: 'invalid_callback', message: 'Missing `code` or `state` query parameter.' } }, { status: 400 });
+            }
+            const cookies = parseCookieHeader(request.headers.get('cookie'));
+            const rawPkce = cookies[ULEX_PKCE_COOKIE];
+            if (!rawPkce) {
+                return Response.json({ error: { code: 'missing_pkce_cookie', message: 'Missing PKCE verification cookie.' } }, { status: 400 });
+            }
+            const unsealed = await unsealJson(rawPkce, config.cookieSecret);
+            if (!unsealed || unsealed.state !== state || unsealed.exp < Math.floor(Date.now() / 1000)) {
+                return Response.json({ error: { code: 'invalid_state', message: 'Expired or mismatched OAuth `state`.' } }, { status: 400 });
+            }
+            const tokenSet = await oauth.exchangeAuthorizationCode({
+                code,
+                codeVerifier: unsealed.verifier,
+                redirectUri: config.redirectUri,
+                clientSecret: config.clientSecret,
+            });
+            // Cryptographically verify the issued access token before setting session cookie.
+            await server.verifyAccessToken(tokenSet.access_token);
+            const targetUrl = new URL(sanitizeRelativeReturnTo(unsealed.returnTo, defaultPostLogin), reqUrl.origin);
+            const headers = new Headers({ location: targetUrl.toString() });
+            headers.append('set-cookie', serializeCookie(ULEX_SESSION_COOKIE, tokenSet.access_token, {
+                maxAge: tokenSet.expires_in,
+                secure,
+            }));
+            headers.append('set-cookie', serializeCookie(ULEX_PKCE_COOKIE, '', { maxAge: 0, secure }));
+            return new Response(null, { status: 302, headers });
+        },
+        async logout(request) {
+            const reqUrl = new URL(request.url);
+            const postLogout = config.postLogoutRedirect ?? `${reqUrl.origin}/`;
+            const logoutUrl = oauth.buildLogoutUrl({ postLogoutRedirectUri: postLogout });
+            const headers = new Headers({ location: logoutUrl });
+            headers.append('set-cookie', serializeCookie(ULEX_SESSION_COOKIE, '', { maxAge: 0, secure }));
+            headers.append('set-cookie', serializeCookie(ULEX_PKCE_COOKIE, '', { maxAge: 0, secure }));
+            return new Response(null, { status: 302, headers });
+        },
+        async me(request) {
+            const session = await getUlexSession(request, config, server);
+            if (!session) {
+                return Response.json({ authenticated: false, user: null }, { status: 401 });
+            }
+            const user = await oauth.getUserInfo(session.accessToken);
+            return Response.json({
+                authenticated: true,
+                sub: session.verified.sub,
+                orgId: session.verified.orgId ?? null,
+                scopes: session.verified.scopes,
+                user,
+            });
+        },
+    };
+}
+/**
+ * Edge-compatible middleware helper: returns `null` when the request is public or
+ * carries a valid ulex session, or returns a `302` redirect / `401` JSON `Response`
+ * when unauthenticated.
+ */
+export function createUlexMiddleware(options) {
+    const { server } = createUlexNextClients(options);
+    const publicPaths = options.publicPaths ?? ['/api/auth'];
+    const loginPath = options.loginPath ?? '/api/auth/login';
+    return async function ulexMiddleware(request) {
+        const url = new URL(request.url);
+        const isPublic = publicPaths.some((prefix) => prefix === '/'
+            ? url.pathname === '/'
+            : url.pathname === prefix || url.pathname.startsWith(`${prefix}/`));
+        if (isPublic) {
+            return null;
+        }
+        const session = await getUlexSession(request, options, server);
+        if (session) {
+            return null;
+        }
+        if (url.pathname.startsWith('/api/')) {
+            return Response.json({ error: { code: 'unauthenticated', message: 'Authentication required.' } }, { status: 401 });
+        }
+        const loginUrl = new URL(loginPath, url.origin);
+        loginUrl.searchParams.set('returnTo', `${url.pathname}${url.search}`);
+        return new Response(null, {
+            status: 302,
+            headers: { location: loginUrl.toString() },
+        });
+    };
+}

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@ulexid/nextjs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "license": "UNLICENSED",
+  "type": "module",
+  "description": "Official Next.js App Router route handlers, encrypted HttpOnly PKCE/session cookies, and Edge/Server middleware for Ulexid.",
+  "homepage": "https://www.ulexid.com",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@ulexid/js": "0.1.1",
+    "@ulexid/node": "0.1.1"
+  }
+}