@crombolo/next-integration 0.0.0-stage → 0.38.1

package/dist/route-handlers.js

@@ -0,0 +1,315 @@
+/**
+ * Route handlers a Next.js app mounts (story 208): Draft Mode on and off from
+ * the CMS's Preview button, revalidation from its webhook, a member's sign-in
+ * and sign-out with PKCE, media fetched with the member's token, and the CMS's
+ * changes for live reload in development (story 214).
+ *
+ * ```ts
+ * // web/app/api/crombolo/preview/route.ts
+ * export const GET = previewHandler(crombolo)
+ * ```
+ */
+import { draftMode } from 'next/headers';
+import { challengeFor, cookie, PREVIEW_COOKIE, randomToken, readCookie, SESSION_COOKIE, SIGN_IN_COOKIE, sameSecret, seal, sessionSecret, unseal, } from './session.js';
+/** Where member sign-in lives on the CMS. */
+export const MEMBER_SECURITY_PATH = '/crombolo/delivery/api/v1/security/member';
+const CLIENT_ID = 'umbraco-member';
+/** A path on this app, or `/`: never another site, so a link cannot send anyone away. */
+export function localPath(value) {
+    if (!value?.startsWith('/') || value.startsWith('//') || value.startsWith('/\\'))
+        return '/';
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what it refuses.
+    return /[\u0000-\u001f\u007f]/.test(value) ? '/' : value;
+}
+const secure = (request) => new URL(request.url).protocol === 'https:';
+function redirectTo(location, cookies = [], status = 307) {
+    const headers = new Headers({ location, 'cache-control': 'no-store' });
+    for (const value of cookies)
+        headers.append('set-cookie', value);
+    return new Response(null, { status, headers });
+}
+/**
+ * `GET ?path=…&token=…`, what the Preview button opens: the token is checked
+ * against the CMS, Draft Mode is turned on, and the editor lands on the page.
+ */
+export function previewHandler(crombolo) {
+    return async (request) => {
+        const url = new URL(request.url);
+        const token = url.searchParams.get('token');
+        const path = localPath(url.searchParams.get('path'));
+        if (!token)
+            return new Response('A preview token is required.', { status: 401 });
+        // There is no endpoint that checks a token; a route lookup with it answers 401 when it is bad.
+        const lookup = new URL(`${crombolo.options.url.replace(/\/+$/, '')}${crombolo.options.apiPath ?? '/crombolo/delivery/api/v2'}/route`);
+        lookup.searchParams.set('path', path);
+        if (crombolo.options.host)
+            lookup.searchParams.set('host', crombolo.options.host);
+        const checked = await fetch(lookup, {
+            headers: {
+                preview: 'true',
+                'preview-token': token,
+                accept: 'application/json',
+            },
+            cache: 'no-store',
+        });
+        if (checked.status === 401 || checked.status === 403)
+            return new Response('This preview link has expired. Press Preview again.', { status: 401 });
+        (await draftMode()).enable();
+        return redirectTo(path, [
+            cookie(PREVIEW_COOKIE, token, { secure: secure(request), maxAge: 60 * 60 }),
+        ]);
+    };
+}
+/** `GET ?path=…`: leaves Draft Mode and forgets the preview token. */
+export function exitPreviewHandler() {
+    return async (request) => {
+        ;
+        (await draftMode()).disable();
+        return redirectTo(localPath(new URL(request.url).searchParams.get('path')), [
+            cookie(PREVIEW_COOKIE, '', { secure: secure(request), maxAge: 0 }),
+        ]);
+    };
+}
+/**
+ * `POST` from a CMS webhook with `payload = "crombolo"`: checks the shared
+ * secret header and clears what holds the item and each of its ancestors.
+ */
+export function revalidateHandler(crombolo, options = {}) {
+    return async (request) => {
+        const secret = options.secret ?? process.env.CROMBOLO_REVALIDATE_SECRET;
+        if (!secret)
+            return new Response('CROMBOLO_REVALIDATE_SECRET is not set.', { status: 500 });
+        if (!(await sameSecret(request.headers.get(options.header ?? 'x-crombolo-secret'), secret)))
+            return new Response('Unauthorized', { status: 401 });
+        let body;
+        try {
+            body = (await request.json());
+        }
+        catch {
+            return new Response('Expected the webhook payload as JSON.', { status: 400 });
+        }
+        const keys = [body.Id, ...(Array.isArray(body.Ancestors) ? body.Ancestors : [])].filter((key) => typeof key === 'string' && /^[0-9a-f-]{36}$/i.test(key));
+        if (keys.length === 0)
+            return new Response('The payload names no item.', { status: 400 });
+        crombolo.revalidate(keys);
+        announceRevalidation(keys);
+        return Response.json({ revalidated: keys });
+    };
+}
+const sessionFrom = (answer) => ({
+    accessToken: answer.access_token,
+    ...(answer.refresh_token ? { refreshToken: answer.refresh_token } : {}),
+    expiresAt: Date.now() + (answer.expires_in ?? 300) * 1000,
+});
+/** Asks the CMS's token endpoint, by authorization code or refresh token. */
+export async function requestTokens(crombolo, form) {
+    const response = await fetch(`${crombolo.options.url.replace(/\/+$/, '')}${MEMBER_SECURITY_PATH}/token`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+        body: new URLSearchParams({ client_id: CLIENT_ID, ...form }),
+        cache: 'no-store',
+    });
+    if (!response.ok)
+        return undefined;
+    return sessionFrom((await response.json()));
+}
+/** Sign-in, its callback, and sign-out, for a member of the site. */
+export function memberHandlers(crombolo, options) {
+    const cms = crombolo.options.url.replace(/\/+$/, '');
+    const secretOf = () => sessionSecret(crombolo.options.secret ?? process.env.CROMBOLO_NEXT_SECRET);
+    return {
+        /** `GET ?returnTo=/path`: off to the CMS to sign in. */
+        async signIn(request) {
+            const state = randomToken();
+            const verifier = randomToken(48);
+            const pending = {
+                state,
+                verifier,
+                returnTo: localPath(new URL(request.url).searchParams.get('returnTo')),
+            };
+            const authorize = new URL(`${cms}${MEMBER_SECURITY_PATH}/authorize`);
+            authorize.search = new URLSearchParams({
+                client_id: CLIENT_ID,
+                redirect_uri: options.redirectUri,
+                response_type: 'code',
+                scope: 'openid offline_access',
+                code_challenge: await challengeFor(verifier),
+                code_challenge_method: 'S256',
+                state,
+            }).toString();
+            return redirectTo(authorize.toString(), [
+                cookie(SIGN_IN_COOKIE, await seal(pending, secretOf()), {
+                    secure: secure(request),
+                    maxAge: 10 * 60,
+                }),
+            ]);
+        },
+        /** `GET ?code=…&state=…`: the tokens, sealed into the session cookie. */
+        async callback(request) {
+            const url = new URL(request.url);
+            const pending = await unseal(readCookie(request.headers.get('cookie'), SIGN_IN_COOKIE), secretOf());
+            const code = url.searchParams.get('code');
+            const done = cookie(SIGN_IN_COOKIE, '', { secure: secure(request), maxAge: 0 });
+            if (!pending || !code || url.searchParams.get('state') !== pending.state)
+                return new Response('This sign-in has expired. Please sign in again.', {
+                    status: 400,
+                    headers: { 'set-cookie': done },
+                });
+            const session = await requestTokens(crombolo, {
+                grant_type: 'authorization_code',
+                code,
+                redirect_uri: options.redirectUri,
+                code_verifier: pending.verifier,
+            });
+            if (!session)
+                return new Response('Signing in did not complete. Please try again.', {
+                    status: 400,
+                    headers: { 'set-cookie': done },
+                });
+            return redirectTo(pending.returnTo, [
+                done,
+                cookie(SESSION_COOKIE, await seal(session, secretOf()), {
+                    secure: secure(request),
+                    maxAge: 60 * 60 * 24 * 30,
+                }),
+            ]);
+        },
+        /** `GET`: ends the member's tokens and their CMS session, then comes back. */
+        async signOut(request) {
+            const session = await unseal(readCookie(request.headers.get('cookie'), SESSION_COOKIE), secretOf());
+            if (session?.refreshToken)
+                await fetch(`${cms}${MEMBER_SECURITY_PATH}/revoke`, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+                    body: new URLSearchParams({ client_id: CLIENT_ID, token: session.refreshToken }),
+                    cache: 'no-store',
+                }).catch(() => undefined);
+            const signout = new URL(`${cms}${MEMBER_SECURITY_PATH}/signout`);
+            signout.search = new URLSearchParams({
+                post_logout_redirect_uri: options.postLogoutRedirectUri,
+            }).toString();
+            return redirectTo(signout.toString(), [
+                cookie(SESSION_COOKIE, '', { secure: secure(request), maxAge: 0 }),
+            ]);
+        },
+    };
+}
+/**
+ * `GET /media/…`: the CMS's media file, sent with the member's token when one
+ * is signed in, so protected media reaches who may read it. Mount it at
+ * `web/app/media/[...path]/route.ts`.
+ */
+export function mediaHandler(crombolo) {
+    const cms = crombolo.options.url.replace(/\/+$/, '');
+    return async (request) => {
+        const url = new URL(request.url);
+        const headers = new Headers();
+        for (const name of ['accept', 'if-none-match', 'if-modified-since', 'range'])
+            if (request.headers.has(name))
+                headers.set(name, request.headers.get(name));
+        const secret = crombolo.options.secret ?? process.env.CROMBOLO_NEXT_SECRET;
+        const session = secret && secret.length >= 32
+            ? await unseal(readCookie(request.headers.get('cookie'), SESSION_COOKIE), secret)
+            : undefined;
+        if (session && session.expiresAt > Date.now())
+            headers.set('authorization', `Bearer ${session.accessToken}`);
+        const answer = await fetch(`${cms}${url.pathname}${url.search}`, {
+            headers,
+            cache: 'no-store',
+            signal: request.signal,
+        });
+        const out = new Headers();
+        for (const name of [
+            'content-type',
+            'content-length',
+            'cache-control',
+            'etag',
+            'last-modified',
+            'content-range',
+            'accept-ranges',
+        ])
+            if (answer.headers.has(name))
+                out.set(name, answer.headers.get(name));
+        // An answer to a member's token is theirs alone.
+        if (headers.has('authorization'))
+            out.set('cache-control', 'private, no-store');
+        return new Response(answer.body, { status: answer.status, headers: out });
+    };
+}
+/** Where the CMS streams its changes in development. */
+export const CMS_LIVE_EVENTS_PATH = '/crombolo/dev/events';
+/**
+ * On the global object: Next.js may bundle this module once per route, and
+ * the revalidate route must reach the live route's listeners.
+ */
+const REVALIDATED = Symbol.for('crombolo.next.revalidated');
+function revalidationListeners() {
+    const holder = globalThis;
+    holder[REVALIDATED] ??= new Set();
+    return holder[REVALIDATED];
+}
+function announceRevalidation(keys) {
+    for (const listener of revalidationListeners())
+        listener(keys);
+}
+const encoder = new TextEncoder();
+/**
+ * `GET` for `<CromboloLiveReload />` in development: the CMS's change stream,
+ * and a `revalidated` event once this app has cleared what a webhook named, so
+ * a refresh after it shows the new content. 404 outside development.
+ */
+export function liveReloadHandler(crombolo) {
+    return async (request) => {
+        if (process.env.NODE_ENV !== 'development')
+            return new Response('Not Found', { status: 404 });
+        const upstream = await fetch(new URL(CMS_LIVE_EVENTS_PATH, crombolo.options.url), {
+            headers: { accept: 'text/event-stream' },
+            signal: request.signal,
+        }).catch(() => undefined);
+        if (!upstream?.ok || !upstream.body)
+            return new Response('The CMS is not streaming its changes.', { status: 502 });
+        const reader = upstream.body.getReader();
+        const decoder = new TextDecoder();
+        let listener;
+        const body = new ReadableStream({
+            async start(controller) {
+                listener = (keys) => controller.enqueue(encoder.encode(`event: revalidated\ndata: ${JSON.stringify({ keys })}\n\n`));
+                revalidationListeners().add(listener);
+                // Whole frames only, so a `revalidated` event never lands inside one of the CMS's.
+                let buffered = '';
+                try {
+                    for (;;) {
+                        const { done, value } = await reader.read();
+                        if (done)
+                            break;
+                        buffered += decoder.decode(value, { stream: true });
+                        const end = buffered.lastIndexOf('\n\n');
+                        if (end < 0)
+                            continue;
+                        controller.enqueue(encoder.encode(buffered.slice(0, end + 2)));
+                        buffered = buffered.slice(end + 2);
+                    }
+                }
+                catch {
+                    // The page left, or the CMS restarted; the browser reconnects either way.
+                }
+                finally {
+                    if (listener)
+                        revalidationListeners().delete(listener);
+                    try {
+                        controller.close();
+                    }
+                    catch { }
+                }
+            },
+            cancel() {
+                if (listener)
+                    revalidationListeners().delete(listener);
+                void reader.cancel().catch(() => { });
+            },
+        });
+        return new Response(body, {
+            headers: { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-store' },
+        });
+    };
+}

package/dist/session.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Cookies the integration keeps (story 208): a member's tokens and a sign-in in
+ * progress, sealed with AES-GCM under `CROMBOLO_NEXT_SECRET`, and the editor's
+ * preview token. Web Crypto only, so it runs in Node and at the edge alike.
+ */
+export declare const SESSION_COOKIE = "crombolo_member";
+export declare const SIGN_IN_COOKIE = "crombolo_sign_in";
+export declare const PREVIEW_COOKIE = "crombolo_preview";
+export interface MemberSession {
+    accessToken: string;
+    refreshToken?: string;
+    /** When the access token stops working, in milliseconds since the epoch. */
+    expiresAt: number;
+}
+export interface SignInState {
+    state: string;
+    verifier: string;
+    returnTo: string;
+}
+/** The secret sessions are sealed with; refused when shorter than 32 characters. */
+export declare function sessionSecret(secret: string | undefined): string;
+/** A value sealed so only a holder of the secret can read or forge it. */
+export declare function seal(value: unknown, secret: string): Promise<string>;
+/** The value back, or undefined when it was tampered with or sealed under another secret. */
+export declare function unseal<T>(sealed: string | undefined, secret: string): Promise<T | undefined>;
+/** A random value for PKCE and `state`. */
+export declare function randomToken(bytes?: number): string;
+/** PKCE's S256 challenge for a verifier. */
+export declare function challengeFor(verifier: string): Promise<string>;
+/** Whether two secrets match, taking the same time whatever they hold. */
+export declare function sameSecret(given: string | null, expected: string): Promise<boolean>;
+/** A cookie's value from a `Cookie` header. */
+export declare function readCookie(header: string | null, name: string): string | undefined;
+/** A `Set-Cookie` value: http-only, `SameSite=Lax`, and `Secure` unless on plain http. */
+export declare function cookie(name: string, value: string, options?: {
+    maxAge?: number;
+    secure?: boolean;
+    path?: string;
+}): string;

package/dist/session.js

@@ -0,0 +1,96 @@
+/**
+ * Cookies the integration keeps (story 208): a member's tokens and a sign-in in
+ * progress, sealed with AES-GCM under `CROMBOLO_NEXT_SECRET`, and the editor's
+ * preview token. Web Crypto only, so it runs in Node and at the edge alike.
+ */
+export const SESSION_COOKIE = 'crombolo_member';
+export const SIGN_IN_COOKIE = 'crombolo_sign_in';
+export const PREVIEW_COOKIE = 'crombolo_preview';
+/** The secret sessions are sealed with; refused when shorter than 32 characters. */
+export function sessionSecret(secret) {
+    if (!secret || secret.length < 32)
+        throw new Error('CROMBOLO_NEXT_SECRET must be set to at least 32 characters to keep members signed in.');
+    return secret;
+}
+const encoder = new TextEncoder();
+function base64url(bytes) {
+    let text = '';
+    for (const byte of bytes)
+        text += String.fromCharCode(byte);
+    return btoa(text).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
+}
+function fromBase64url(value) {
+    const text = atob(value.replaceAll('-', '+').replaceAll('_', '/'));
+    const bytes = new Uint8Array(text.length);
+    for (let i = 0; i < text.length; i++)
+        bytes[i] = text.charCodeAt(i);
+    return bytes;
+}
+async function keyFor(secret) {
+    const digest = await crypto.subtle.digest('SHA-256', encoder.encode(secret));
+    return crypto.subtle.importKey('raw', digest, 'AES-GCM', false, ['encrypt', 'decrypt']);
+}
+/** A value sealed so only a holder of the secret can read or forge it. */
+export async function seal(value, secret) {
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const sealed = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, await keyFor(secret), encoder.encode(JSON.stringify(value)));
+    return `${base64url(iv)}.${base64url(new Uint8Array(sealed))}`;
+}
+/** The value back, or undefined when it was tampered with or sealed under another secret. */
+export async function unseal(sealed, secret) {
+    if (!sealed)
+        return undefined;
+    const [iv, data] = sealed.split('.');
+    if (!iv || !data)
+        return undefined;
+    try {
+        const opened = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: fromBase64url(iv) }, await keyFor(secret), fromBase64url(data));
+        return JSON.parse(new TextDecoder().decode(opened));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A random value for PKCE and `state`. */
+export function randomToken(bytes = 32) {
+    return base64url(crypto.getRandomValues(new Uint8Array(bytes)));
+}
+/** PKCE's S256 challenge for a verifier. */
+export async function challengeFor(verifier) {
+    return base64url(new Uint8Array(await crypto.subtle.digest('SHA-256', encoder.encode(verifier))));
+}
+/** Whether two secrets match, taking the same time whatever they hold. */
+export async function sameSecret(given, expected) {
+    if (!given)
+        return false;
+    const [a, b] = await Promise.all([given, expected].map(async (v) => new Uint8Array(await crypto.subtle.digest('SHA-256', encoder.encode(v)))));
+    const left = a;
+    const right = b;
+    let difference = 0;
+    for (let i = 0; i < left.length; i++)
+        difference |= left[i] ^ right[i];
+    return difference === 0;
+}
+/** A cookie's value from a `Cookie` header. */
+export function readCookie(header, name) {
+    for (const part of (header ?? '').split(';')) {
+        const at = part.indexOf('=');
+        if (at > 0 && part.slice(0, at).trim() === name)
+            return decodeURIComponent(part.slice(at + 1).trim());
+    }
+    return undefined;
+}
+/** A `Set-Cookie` value: http-only, `SameSite=Lax`, and `Secure` unless on plain http. */
+export function cookie(name, value, options = {}) {
+    const parts = [
+        `${name}=${encodeURIComponent(value)}`,
+        `Path=${options.path ?? '/'}`,
+        'HttpOnly',
+        'SameSite=Lax',
+    ];
+    if (options.maxAge !== undefined)
+        parts.push(`Max-Age=${Math.max(0, Math.floor(options.maxAge))}`);
+    if (options.secure !== false)
+        parts.push('Secure');
+    return parts.join('; ');
+}

package/package.json

@@ -1,6 +1,88 @@
 {
   "name": "@crombolo/next-integration",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.38.1",
+  "description": "A Next.js App Router front end for a crombolo site: pages, metadata, preview, revalidation, members, images and content components.",
+  "license": "MIT",
+  "author": "Crombolo",
+  "homepage": "https://github.com/kineco-au/crombolo-cms#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kineco-au/crombolo-cms.git",
+    "directory": "packages/next-integration"
+  },
+  "bugs": {
+    "url": "https://github.com/kineco-au/crombolo-cms/issues"
+  },
+  "keywords": [
+    "crombolo",
+    "nextjs",
+    "headless"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./cache-16": {
+      "types": "./dist/cache-16.d.ts",
+      "import": "./dist/cache-16.js",
+      "default": "./dist/cache-16.js"
+    },
+    "./cache-15": {
+      "types": "./dist/cache-15.d.ts",
+      "import": "./dist/cache-15.js",
+      "default": "./dist/cache-15.js"
+    },
+    "./route-handlers": {
+      "types": "./dist/route-handlers.d.ts",
+      "import": "./dist/route-handlers.js",
+      "default": "./dist/route-handlers.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware.d.ts",
+      "import": "./dist/middleware.js",
+      "default": "./dist/middleware.js"
+    },
+    "./components": {
+      "types": "./dist/components.d.ts",
+      "import": "./dist/components.js",
+      "default": "./dist/components.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "default": "./dist/client.js"
+    },
+    "./image-loader": {
+      "types": "./dist/image-loader.d.ts",
+      "import": "./dist/image-loader.js",
+      "default": "./dist/image-loader.js"
+    }
+  },
+  "files": [
+    "dist",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "@crombolo/common": "0.38.1",
+    "@crombolo/delivery-client": "0.38.1"
+  },
+  "peerDependencies": {
+    "next": ">=15.5 <17",
+    "react": ">=19"
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "next": "16.4.3",
+    "react": "19.3.1",
+    "react-dom": "19.3.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.