barakopress 0.2.0

package/src/routes/revalidate.ts

@@ -0,0 +1,157 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { revalidateTag } from "next/cache";
+import { NextResponse, type NextRequest } from "next/server";
+import type { PressConfig } from "../config.js";
+
+/*
+ * The endpoint that makes the cache correct.
+ *
+ * barakoCMS fires a signed webhook when content changes and this drops the cache tag, so the next
+ * request renders fresh. It is the only writer to the cache and it is reachable by anyone who
+ * finds the URL, so the order of the checks matters as much as the checks.
+ *
+ * The signing recipe is barakoCMS docs/webhooks.md:
+ *
+ *   X-Barako-Timestamp   unix seconds when it was signed
+ *   X-Barako-Signature   "sha256=" + lowercase hex HMAC-SHA256 over "<timestamp>.<raw body>"
+ *   X-Barako-Delivery    the delivery log row id
+ *
+ * Four things are load-bearing:
+ *
+ *   1. The signature covers the RAW body bytes. Parse the JSON first and you have re-serialised
+ *      it into a different string that will never verify.
+ *   2. Constant-time compare, or a few thousand requests recover the expected signature.
+ *   3. An old timestamp is refused, so a captured delivery cannot be replayed forever.
+ *   4. Cheap checks come first. Reading an unbounded body into memory before authenticating lets
+ *      an anonymous caller spend this server's memory, so the length is checked first and the
+ *      read is capped.
+ */
+
+const TOLERANCE_SECONDS = 300;
+
+/** A signed delivery is small. Anything larger did not come from the CMS. */
+const MAX_BODY_BYTES = 64 * 1024;
+
+export interface RevalidateOptions {
+    /** Defaults to REVALIDATE_SECRET. */
+    secret?: string;
+    /** Seconds a signature stays valid. Shorter is safer; the sender's clock has to be close. */
+    toleranceSeconds?: number;
+    maxBodyBytes?: number;
+}
+
+/** Constant-time compare that does not leak length through an early return either. */
+function sameSignature(a: string, b: string): boolean {
+    const left = Buffer.from(a, "utf8");
+    const right = Buffer.from(b, "utf8");
+    if (left.length !== right.length) return false;
+    return timingSafeEqual(left, right);
+}
+
+/*
+ * A replayed delivery is honoured once.
+ *
+ * A captured signature stays valid for the whole tolerance window, and each accepted purge costs
+ * a re-render of every cached page. Remembering what has already been honoured turns "unlimited
+ * work for five minutes" into "one". In-process, which is the same scope as the cache it
+ * protects: another instance has its own cache and would do its own single purge anyway.
+ */
+function makeReplayGuard(windowSeconds: number) {
+    const seen = new Map<string, number>();
+    return function alreadyHonoured(signature: string): boolean {
+        const now = Date.now() / 1000;
+        for (const [sig, at] of seen) if (now - at > windowSeconds) seen.delete(sig);
+        if (seen.has(signature)) return true;
+        seen.set(signature, now);
+        return false;
+    };
+}
+
+export function createRevalidateRoute(config: PressConfig, options: RevalidateOptions = {}) {
+    const tolerance = options.toleranceSeconds ?? TOLERANCE_SECONDS;
+    const maxBody = options.maxBodyBytes ?? MAX_BODY_BYTES;
+    const alreadyHonoured = makeReplayGuard(tolerance);
+
+    async function POST(request: NextRequest) {
+        const secret = options.secret ?? process.env.REVALIDATE_SECRET;
+        if (!secret) {
+            // Refuse rather than accept unsigned. An unconfigured deployment that quietly accepts
+            // anything is an open cache-purge endpoint, which is a free denial of service.
+            console.error("revalidate: no secret configured, refusing every delivery");
+            return NextResponse.json({ error: "not configured" }, { status: 503 });
+        }
+
+        const timestamp = request.headers.get("x-barako-timestamp");
+        const signature = request.headers.get("x-barako-signature");
+        if (!timestamp || !signature) {
+            return NextResponse.json({ error: "unsigned" }, { status: 401 });
+        }
+
+        const sent = Number(timestamp);
+        if (!Number.isFinite(sent)) {
+            return NextResponse.json({ error: "bad timestamp" }, { status: 401 });
+        }
+        if (Math.abs(Date.now() / 1000 - sent) > tolerance) {
+            // Also catches a receiver whose clock has drifted, which looks identical from here.
+            return NextResponse.json({ error: "stale" }, { status: 401 });
+        }
+
+        // Length before content: the last check that costs nothing.
+        const declared = Number(request.headers.get("content-length") ?? "0");
+        if (Number.isFinite(declared) && declared > maxBody) {
+            return NextResponse.json({ error: "too large" }, { status: 413 });
+        }
+
+        const raw = Buffer.from(await request.arrayBuffer());
+        if (raw.byteLength > maxBody) {
+            // A chunked request declares no length, so the read is bounded again here.
+            return NextResponse.json({ error: "too large" }, { status: 413 });
+        }
+
+        const material = Buffer.concat([Buffer.from(`${timestamp}.`, "utf8"), raw]);
+        const expected = "sha256=" + createHmac("sha256", secret).update(material).digest("hex");
+        if (!sameSignature(expected, signature)) {
+            return NextResponse.json({ error: "bad signature" }, { status: 401 });
+        }
+
+        if (alreadyHonoured(signature)) {
+            // Honest 200: the purge this delivery asked for has already happened, so the CMS has
+            // no reason to retry. A 401 here would make a legitimate retry look like an attack.
+            return NextResponse.json({ revalidated: true, repeated: true });
+        }
+
+        /*
+         * No cache warming here, deliberately.
+         *
+         * An earlier version fetched the main pages after purging, on the theory that Next serves
+         * one stale response after a purge and this server should absorb it. Measured against a
+         * CMS that logs every read, those fetches caused zero reads and re-rendered nothing:
+         * `{ expire: 0 }` already makes the next request a blocking miss, and a page that was
+         * never in the warm list was equally fresh for its first reader.
+         *
+         * It could not have worked in the shipped stack anyway. Caddy sets X-Forwarded-Proto, so
+         * the origin resolved to https against the plain HTTP server inside this container, and
+         * the failure was swallowed without a log line. Three requests per delivery, latency on
+         * the response, and triple the work an attacker gets from one captured signature, for
+         * nothing.
+         */
+        revalidateTag(config.cacheTag, { expire: 0 });
+
+        // The delivery id is echoed only after the signature verified, so an anonymous caller
+        // cannot put text of their choosing into this server's log.
+        const delivery = request.headers.get("x-barako-delivery") ?? "unknown";
+        console.log(`revalidate: dropped tag "${config.cacheTag}" for delivery ${delivery}`);
+        return NextResponse.json({ revalidated: true, tag: config.cacheTag, delivery });
+    }
+
+    /*
+     * GET answers "is this wired up" without a signed request, and reveals nothing: not whether a
+     * secret is set, not the tag, not the last delivery. A health check that leaks configuration
+     * is how someone learns what to forge.
+     */
+    async function GET() {
+        return NextResponse.json({ ok: true });
+    }
+
+    return { POST, GET };
+}

package/src/routes/robots.ts

@@ -0,0 +1,20 @@
+import type { MetadataRoute } from "next";
+import type { PressConfig } from "../config.js";
+
+/*
+ * Generated, because the Sitemap line has to be an absolute URL and the domain is per deployment.
+ * A relative Sitemap: is ignored.
+ *
+ * The URL comes from config rather than process.env read at module scope. That distinction is the
+ * whole bug it fixes: this route is prerendered at build, so an env read baked the build
+ * machine's value in permanently, and production advertised a localhost sitemap that no cache
+ * purge could ever correct.
+ */
+export function createRobots(config: PressConfig) {
+    return function robots(): MetadataRoute.Robots {
+        return {
+            rules: { userAgent: "*", allow: "/" },
+            sitemap: `${config.site.url}/sitemap.xml`,
+        };
+    };
+}

package/src/routes/sitemap.ts

@@ -0,0 +1,35 @@
+import type { MetadataRoute } from "next";
+import type { PressConfig } from "../config.js";
+import { listPosts } from "../cms.js";
+
+/*
+ * Built from the same cached read as every other page, so it costs nothing in the steady state
+ * and cannot disagree with what the site serves.
+ *
+ * A post whose SEO block says noIndex is left out: the CMS resolves that flag per entry and its
+ * own sitemap honours it, so a site that ignored it here would contradict the CMS on the one
+ * signal an editor set deliberately.
+ */
+export function createSitemap(config: PressConfig) {
+    return async function sitemap(): Promise<MetadataRoute.Sitemap> {
+        let indexable: Awaited<ReturnType<typeof listPosts>>["posts"] = [];
+        try {
+            const { posts } = await listPosts(config, { pageSize: config.pageSizes.sitemap });
+            indexable = posts.filter((p) => !p.seo?.noIndex);
+        } catch {
+            // A sitemap that throws is worse than a short one: it fails the build when
+            // prerendered, and serves a crawler a 500 at runtime.
+            indexable = [];
+        }
+
+        return [
+            { url: config.site.url, changeFrequency: "daily", priority: 1 },
+            ...indexable.map((p) => ({
+                url: `${config.site.url}${config.routes.post}/${p.slug}`,
+                lastModified: p.publishedAt ? new Date(p.publishedAt) : undefined,
+                changeFrequency: "monthly" as const,
+                priority: 0.7,
+            })),
+        ];
+    };
+}

package/src/screens/archive.tsx

@@ -0,0 +1,79 @@
+import Link from "next/link";
+import { notFound } from "next/navigation";
+import type { PressConfig } from "../config.js";
+import { getTerm, listPostsBy, type Post } from "../cms.js";
+import { renderMarkdown } from "../markdown.js";
+import { Card } from "./blog-index.js";
+
+type SlugParams = { params: Promise<{ slug: string }> };
+
+/*
+ * Posts by author, or by category.
+ *
+ * One screen for both, because they differ only in which type is resolved and which reference is
+ * filtered on, and both of those are in the config. A site with no author type simply never
+ * mounts the route; the factory still refuses cleanly if it is mounted anyway.
+ */
+export function createArchive(config: PressConfig, which: "author" | "category") {
+    return async function ArchivePage({ params }: SlugParams) {
+        if (!config.types[which]) notFound();
+
+        const { slug } = await params;
+        const [term, posts] = await Promise.all([
+            getTerm(config, which, slug),
+            listPostsBy(config, which, slug),
+        ]);
+        if (!term || !posts) notFound();
+
+        return (
+            <>
+                <p className="meta">
+                    <Link href="/">Back</Link>
+                </p>
+                <h1>{term.name}</h1>
+
+                {term.description && (
+                    <div
+                        className="prose"
+                        dangerouslySetInnerHTML={{ __html: renderMarkdown(term.description) }}
+                    />
+                )}
+
+                {which === "author" && term.website && (
+                    <p className="meta">
+                        <a href={term.website} rel="noopener noreferrer">
+                            {term.website}
+                        </a>
+                    </p>
+                )}
+
+                <h2 style={{ marginTop: "2.5rem" }}>
+                    {posts.length} {posts.length === 1 ? "post" : "posts"}
+                </h2>
+
+                {posts.map((p: Post) => (
+                    <Card key={p.id} config={config} post={p} />
+                ))}
+            </>
+        );
+    };
+}
+
+/** Slugs for a static export of an archive route. */
+export function createArchiveStaticParams(config: PressConfig, which: "author" | "category") {
+    return async function generateStaticParams(): Promise<{ slug: string }[]> {
+        const type = config.types[which];
+        if (!type) return [];
+
+        const { list } = await import("../delivery.js");
+        try {
+            const res = await list(config, type, { pageSize: 100 });
+            return res.items
+                .map((c) => c.slug ?? "")
+                .filter(Boolean)
+                .map((slug) => ({ slug }));
+        } catch {
+            return [];
+        }
+    };
+}

package/src/screens/blog-index.tsx

@@ -0,0 +1,122 @@
+import Link from "next/link";
+import type { PressConfig } from "../config.js";
+import { formatDate, listPosts, type Post } from "../cms.js";
+
+/*
+ * The post list.
+ *
+ * A factory rather than a component, because a Next route is a file and a package cannot write
+ * files into someone else's app. The consumer's page.tsx is:
+ *
+ *     import { createBlogIndex } from "barakopress";
+ *     import { config } from "@/press.config";
+ *     export default createBlogIndex(config);
+ *     export const revalidate = 300;
+ *
+ * `Card` is exported too, so a site that wants its own list but the engine's card can have one
+ * without copying the markup.
+ */
+
+export function Card({
+    config,
+    post,
+    featured = false,
+}: {
+    config: PressConfig;
+    post: Post;
+    featured?: boolean;
+}) {
+    return (
+        <article className={featured ? "card featured-card" : "card"}>
+            {featured && <span className="chip">Featured</span>}
+            <h2>
+                <Link href={`${config.routes.post}/${post.slug}`}>{post.title}</Link>
+            </h2>
+            <p className="meta">
+                {post.publishedAt && (
+                    <time dateTime={post.publishedAt}>{formatDate(config, post.publishedAt)}</time>
+                )}
+                {post.author && config.routes.author && (
+                    <>
+                        {" by "}
+                        <Link href={`${config.routes.author}/${post.author.slug}`}>
+                            {post.author.name}
+                        </Link>
+                    </>
+                )}
+                {post.category && config.routes.category && (
+                    <>
+                        {" in "}
+                        <Link href={`${config.routes.category}/${post.category.slug}`}>
+                            {post.category.name}
+                        </Link>
+                    </>
+                )}
+            </p>
+            {post.excerpt && <p className="excerpt">{post.excerpt}</p>}
+            {post.tags.length > 0 && (
+                <p className="tags">
+                    {post.tags.map((t) => (
+                        <span key={t} className="tag">
+                            {t}
+                        </span>
+                    ))}
+                </p>
+            )}
+        </article>
+    );
+}
+
+export function createBlogIndex(config: PressConfig) {
+    return async function BlogIndex() {
+        let posts: Post[] = [];
+        let failure: string | null = null;
+
+        try {
+            ({ posts } = await listPosts(config));
+        } catch (e) {
+            // An unreachable CMS is the likeliest thing to be wrong, so it gets a readable page
+            // rather than a stack trace. This render is not cached, so the next request retries.
+            failure = e instanceof Error ? e.message : String(e);
+        }
+
+        const featured = posts.filter((p) => p.featured);
+        const rest = posts.filter((p) => !p.featured);
+
+        return (
+            <>
+                <header className="masthead">
+                    <h1>{config.site.name}</h1>
+                    {config.site.tagline && <p className="tagline">{config.site.tagline}</p>}
+                </header>
+
+                {failure && (
+                    <div className="notice error">
+                        <p>
+                            <strong>This page could not be loaded.</strong>
+                        </p>
+                        <p>Please try again shortly.</p>
+                    </div>
+                )}
+
+                {!failure && posts.length === 0 && (
+                    <div className="notice">
+                        <p>
+                            <strong>Nothing published yet.</strong>
+                        </p>
+                        <p>
+                            Only published entries of a type opted into public delivery appear here.
+                        </p>
+                    </div>
+                )}
+
+                {featured.map((p) => (
+                    <Card key={p.id} config={config} post={p} featured />
+                ))}
+                {rest.map((p) => (
+                    <Card key={p.id} config={config} post={p} />
+                ))}
+            </>
+        );
+    };
+}

package/src/screens/blog-post.tsx

@@ -0,0 +1,110 @@
+import { notFound } from "next/navigation";
+import type { Metadata } from "next";
+import type { PressConfig } from "../config.js";
+import { getPost, getPostPreview, listPosts } from "../cms.js";
+import { PostView } from "./post-view.js";
+
+type SlugParams = { params: Promise<{ slug: string }> };
+type PreviewParams = SlugParams & { searchParams: Promise<{ preview?: string }> };
+
+/*
+ * The post page, in two shapes.
+ *
+ * `createBlogPost` reads only `params`, so it can be prerendered and works under
+ * `output: "export"`. `createBlogPostPreview` also reads `searchParams` for a preview token,
+ * which forces dynamic rendering: a static export refuses it outright with "couldn't be rendered
+ * statically because it used searchParams". A static site takes the first and gives up draft
+ * preview, which is the honest trade and the reason these are two exports rather than a flag.
+ */
+
+export function createBlogPost(config: PressConfig) {
+    return async function PostPage({ params }: SlugParams) {
+        const { slug } = await params;
+        const post = await getPost(config, slug);
+        if (!post) notFound();
+        return <PostView config={config} post={post} />;
+    };
+}
+
+export function createBlogPostPreview(config: PressConfig) {
+    return async function PostPreviewPage({ params, searchParams }: PreviewParams) {
+        const { slug } = await params;
+        const { preview } = await searchParams;
+
+        // A token routes to the uncached read, so a draft never enters the shared cache.
+        const post = preview ? await getPostPreview(config, slug, preview) : await getPost(config, slug);
+        if (!post) notFound();
+
+        return <PostView config={config} post={post} preview={Boolean(preview)} />;
+    };
+}
+
+/*
+ * Metadata from the API's resolved `seo` block rather than assembled here.
+ *
+ * A type opted into SEO fields returns title, description, canonical, social image and noIndex on
+ * every public response, with the title already falling back to the entry's title. So this maps,
+ * and an editor changing the meta description in the console changes the page.
+ */
+export function createPostMetadata(config: PressConfig) {
+    return async function generateMetadata({ params }: SlugParams): Promise<Metadata> {
+        const { slug } = await params;
+        const post = await getPost(config, slug);
+        if (!post) return { title: "Not found" };
+
+        const seo = post.seo;
+        const title = seo?.title ?? post.title;
+        const description = seo?.description ?? post.excerpt;
+        const image = seo?.imageUrl ?? post.coverImage;
+
+        return {
+            title,
+            description,
+            alternates: seo?.canonicalUrl ? { canonical: seo.canonicalUrl } : undefined,
+            robots: seo?.noIndex ? { index: false, follow: false } : undefined,
+            openGraph: {
+                title,
+                description,
+                type: "article",
+                publishedTime: post.publishedAt,
+                images: image ? [image] : undefined,
+            },
+            twitter: {
+                card: image ? "summary_large_image" : "summary",
+                title,
+                description,
+                images: image ? [image] : undefined,
+            },
+        };
+    };
+}
+
+/*
+ * Slugs for a static export, paged to the end rather than to one hardcoded limit.
+ *
+ * Every consumer of an export-mode site needs this, and every one that hand-writes it caps the
+ * page size and silently drops the posts past it. Doing it once here is the difference between an
+ * engine and a snippet in a README.
+ */
+export function createPostStaticParams(config: PressConfig) {
+    return async function generateStaticParams(): Promise<{ slug: string }[]> {
+        const slugs: { slug: string }[] = [];
+        const pageSize = 100;
+
+        for (let page = 1; page <= 200; page++) {
+            let batch;
+            try {
+                batch = await listPosts(config, { page, pageSize });
+            } catch {
+                // A build with no CMS reachable produces no routes. Under `output: "export"` Next
+                // then refuses the build, which is the correct outcome: a static site with no
+                // content is not something to ship quietly.
+                break;
+            }
+            for (const p of batch.posts) if (p.slug) slugs.push({ slug: p.slug });
+            if (!batch.hasNextPage) break;
+        }
+
+        return slugs;
+    };
+}

package/src/screens/post-view.tsx

@@ -0,0 +1,84 @@
+import Link from "next/link";
+import type { PressConfig } from "../config.js";
+import { formatDate, type Post } from "../cms.js";
+import { renderMarkdown } from "../markdown.js";
+
+/*
+ * The rendering, shared by the static screen and the preview screen.
+ *
+ * It is its own component because reading `searchParams` forces a route to render dynamically,
+ * and a site built with `output: "export"` is refused outright for it. Preview needs the query
+ * string; a published post does not. Splitting the fetch from the render is what lets one set of
+ * markup serve a static site and a server-rendered one.
+ *
+ * Every link is built from `config.routes`, so a site that mounts posts at /writing gets /writing
+ * links here, in the feed and in the sitemap, instead of three files disagreeing.
+ */
+export function PostView({
+    config,
+    post,
+    preview = false,
+}: {
+    config: PressConfig;
+    post: Post;
+    preview?: boolean;
+}) {
+    return (
+        <article>
+            {preview && (
+                <div className="notice preview-banner">
+                    Preview. This is how the post will look. It is not published, and it is served
+                    uncached so nothing here reaches another reader.
+                </div>
+            )}
+
+            <p className="meta">
+                <Link href="/">Back</Link>
+            </p>
+
+            <h1>{post.title}</h1>
+
+            <p className="meta">
+                {post.publishedAt && (
+                    <time dateTime={post.publishedAt}>{formatDate(config, post.publishedAt)}</time>
+                )}
+                {post.author && config.routes.author && (
+                    <>
+                        {" by "}
+                        <Link href={`${config.routes.author}/${post.author.slug}`}>
+                            {post.author.name}
+                        </Link>
+                    </>
+                )}
+                {post.author && !config.routes.author && <>{` by ${post.author.name}`}</>}
+                {post.category && config.routes.category && (
+                    <>
+                        {" in "}
+                        <Link href={`${config.routes.category}/${post.category.slug}`}>
+                            {post.category.name}
+                        </Link>
+                    </>
+                )}
+            </p>
+
+            {post.coverImage && (
+                // Not next/image: the CMS resizes on request with ?w=, so the optimiser would be a
+                // second resizer in front of the first.
+                // eslint-disable-next-line @next/next/no-img-element
+                <img className="cover" src={post.coverImage} alt={post.coverImageAlt ?? ""} />
+            )}
+
+            <div className="prose" dangerouslySetInnerHTML={{ __html: renderMarkdown(post.body) }} />
+
+            {post.tags.length > 0 && (
+                <p className="tags">
+                    {post.tags.map((t) => (
+                        <span key={t} className="tag">
+                            {t}
+                        </span>
+                    ))}
+                </p>
+            )}
+        </article>
+    );
+}