@carlonicora/nextjs-jsonapi 3.28.2 → 4.0.1

package/src/next-config/csp.ts

@@ -0,0 +1,128 @@
+// Runtime imports: none. next.config.js loads this at RUNTIME under `next start`
+// in an image installed with --prod, so it may import only Node built-ins.
+
+export type CspDirective =
+  "script-src" | "style-src" | "img-src" | "font-src" | "connect-src" | "frame-src" | "worker-src";
+
+/**
+ * Third-party services an app may load. Each one adds its hosts to the
+ * directives it needs; nothing is allowed unless the app names it.
+ *
+ * - `stripe`: the billing feature (`@carlonicora/nextjs-jsonapi/billing`).
+ * - `googleMaps`: `FormPlaceAutocomplete` (Places API) and Maps JS/static tiles.
+ * - `turnstile`: Cloudflare Turnstile widgets (contact and waitlist forms).
+ * - `discord`: Discord avatars shown for users who log in with Discord.
+ * - `googleFonts`: fonts linked at runtime from Google Fonts. Not needed for
+ *   `next/font/google`, which self-hosts at build time.
+ */
+export type CspService = "stripe" | "googleMaps" | "turnstile" | "discord" | "googleFonts";
+
+export interface CspOptions {
+  services?: CspService[];
+  csp?: Partial<Record<CspDirective, string[]>>;
+}
+
+const SERVICE_SOURCES: Record<CspService, Partial<Record<CspDirective, string[]>>> = {
+  stripe: {
+    "script-src": ["https://js.stripe.com"],
+    "img-src": ["https://*.stripe.com"],
+    "connect-src": ["https://api.stripe.com"],
+    "frame-src": ["https://js.stripe.com", "https://hooks.stripe.com"],
+  },
+  googleMaps: {
+    "script-src": ["https://maps.googleapis.com"],
+    "img-src": ["https://maps.googleapis.com", "https://maps.gstatic.com"],
+    "connect-src": ["https://maps.googleapis.com", "https://places.googleapis.com"],
+  },
+  turnstile: {
+    "script-src": ["https://challenges.cloudflare.com"],
+    "connect-src": ["https://challenges.cloudflare.com"],
+    "frame-src": ["https://challenges.cloudflare.com"],
+  },
+  discord: {
+    "img-src": ["https://cdn.discordapp.com"],
+  },
+  googleFonts: {
+    "style-src": ["https://fonts.googleapis.com"],
+    "font-src": ["https://fonts.gstatic.com"],
+  },
+};
+
+function listImageSources(env: NodeJS.ProcessEnv): string[] {
+  return env.IMAGE_SOURCES ? env.IMAGE_SOURCES.split(",").map((s) => s.trim()) : [];
+}
+
+// Build CSP directives
+// Note: 'unsafe-inline' and 'unsafe-eval' needed for Next.js dev mode and some runtime features
+// In production, consider using nonces for stricter CSP
+export function buildCsp(options: CspOptions, env: NodeJS.ProcessEnv): string {
+  const apiUrl = env.NEXT_PUBLIC_API_URL || "";
+  const imageSources = listImageSources(env);
+  const services = options.services ?? [];
+
+  // Each fetch directive: what Next itself needs, then the named services, then
+  // the app's extras, then the sources derived from the env.
+  const fetchDirectives: Record<CspDirective, { base: string[]; fromEnv: string[] }> = {
+    // Scripts: self, and unsafe-inline/eval for Next.js
+    "script-src": { base: ["'self'", "'unsafe-inline'", "'unsafe-eval'"], fromEnv: [] },
+    // Styles: self and unsafe-inline for styled-components/emotion
+    "style-src": { base: ["'self'", "'unsafe-inline'"], fromEnv: [] },
+    // Images: self, data URIs, blobs, and configured image sources
+    "img-src": { base: ["'self'", "data:", "blob:"], fromEnv: imageSources },
+    // Fonts: self
+    "font-src": { base: ["'self'"], fromEnv: [] },
+    // Connect: self, API (http + ws for socket.io), and storage (for uploads)
+    "connect-src": {
+      base: ["'self'"],
+      fromEnv: [
+        apiUrl,
+        // Add WebSocket URL for socket.io (convert http->ws, https->wss)
+        apiUrl.replace(/^http/, "ws"),
+        env.NEXT_PUBLIC_ADDRESS || "",
+        ...imageSources,
+      ],
+    },
+    // Frames: self
+    "frame-src": { base: ["'self'"], fromEnv: [] },
+    // Worker sources: self and blob (for Web Workers with dynamic imports)
+    "worker-src": { base: ["'self'", "blob:"], fromEnv: [] },
+  };
+
+  const directive = (name: CspDirective): string => {
+    const { base, fromEnv } = fetchDirectives[name];
+    const fromServices = services.flatMap((service) => SERVICE_SOURCES[service][name] ?? []);
+    const sources = [...base, ...fromServices, ...(options.csp?.[name] ?? []), ...fromEnv].filter(
+      (source) => source !== "",
+    );
+    return [name, ...new Set(sources)].join(" ");
+  };
+
+  return [
+    "default-src 'self'",
+    directive("script-src"),
+    directive("style-src"),
+    directive("img-src"),
+    directive("font-src"),
+    directive("connect-src"),
+    directive("frame-src"),
+    // Frame ancestors: deny embedding (equivalent to X-Frame-Options: DENY)
+    "frame-ancestors 'none'",
+    // Form actions: only self
+    "form-action 'self'",
+    // Base URI: only self
+    "base-uri 'self'",
+    // Object sources: none (no plugins)
+    "object-src 'none'",
+    directive("worker-src"),
+    // Upgrade insecure requests in production.
+    //
+    // NOT under E2E_BUILD: the e2e harness runs a PRODUCTION build (for speed)
+    // and serves it over plain http on a custom hostname. With this directive
+    // the browser rewrites every /_next/static asset to https, which nothing is
+    // listening on — every chunk fails with ERR_SSL_PROTOCOL_ERROR, the page
+    // never hydrates, and each spec sees only server-rendered markup.
+    env.NODE_ENV === "production" && env.E2E_BUILD !== "true" ? "upgrade-insecure-requests" : "",
+  ]
+    .filter(Boolean)
+    .join("; ");
+}

package/src/next-config/headers.ts

@@ -0,0 +1,61 @@
+// Runtime imports: relative only. See csp.ts.
+import { buildCsp, type CspOptions } from "./csp";
+
+export interface SecurityHeaderOptions extends CspOptions {
+  permissionsPolicy?: { camera?: "none" | "self" };
+}
+
+export interface HeaderRule {
+  source: string;
+  headers: { key: string; value: string }[];
+}
+
+export function buildSecurityHeaders(options: SecurityHeaderOptions, env: NodeJS.ProcessEnv): HeaderRule[] {
+  const camera = options.permissionsPolicy?.camera === "none" ? "" : "self";
+
+  return [
+    {
+      // Apply to all routes
+      source: "/:path*",
+      headers: [
+        // Content Security Policy - prevents XSS attacks
+        {
+          key: "Content-Security-Policy",
+          value: buildCsp(options, env),
+        },
+        // X-Frame-Options - prevents clickjacking (backup for older browsers)
+        {
+          key: "X-Frame-Options",
+          value: "DENY",
+        },
+        // X-Content-Type-Options - prevents MIME sniffing
+        {
+          key: "X-Content-Type-Options",
+          value: "nosniff",
+        },
+        // Strict-Transport-Security - enforces HTTPS (1 year, include subdomains).
+        // Omitted under E2E_BUILD for the same reason as upgrade-insecure-requests:
+        // the suite speaks plain http, and an HSTS pin would force https on every
+        // later request to this host from the same browser profile.
+        ...(env.E2E_BUILD === "true"
+          ? []
+          : [
+              {
+                key: "Strict-Transport-Security",
+                value: "max-age=31536000; includeSubDomains",
+              },
+            ]),
+        // Referrer-Policy - controls referrer information
+        {
+          key: "Referrer-Policy",
+          value: "strict-origin-when-cross-origin",
+        },
+        // Permissions-Policy - restricts browser features
+        {
+          key: "Permissions-Policy",
+          value: `camera=(${camera}), microphone=(), geolocation=()`,
+        },
+      ],
+    },
+  ];
+}

package/src/next-config/index.ts

@@ -0,0 +1,114 @@
+// Shared next.config for the nja fleet. Apps wrap the result with their own
+// plugins: `withNextIntl(withMDX(createNextConfig({...})))`.
+//
+// next.config.js is loaded at RUNTIME by `next start`, and the production image
+// installs with --prod. This entry may therefore import only Node built-ins at
+// runtime: never next-intl, @next/mdx, serwist or any devDependency. `next` is
+// imported for its types only.
+import type { NextConfig } from "next";
+import { buildCsp, type CspDirective, type CspService } from "./csp";
+import { buildSecurityHeaders } from "./headers";
+
+export { buildCsp };
+export type { CspDirective, CspService };
+
+export interface NjaNextConfigOptions {
+  devOrigins: string[];
+  /** Third-party services the app loads; each adds its own hosts to the CSP. Nothing is allowed by default. */
+  services?: CspService[];
+  /** Extra CSP sources per directive, for hosts no named service covers. */
+  csp?: Partial<Record<CspDirective, string[]>>;
+  env?: Record<string, string>;
+  imageMinimumCacheTTL?: number;
+  permissionsPolicy?: { camera?: "none" | "self" };
+  mdx?: boolean;
+  serwist?: boolean;
+  securityHeaders?: boolean;
+  authInterrupts?: boolean;
+  reactCompiler?: boolean;
+  rewrites?: NextConfig["rewrites"];
+  extend?: (config: NextConfig) => NextConfig;
+}
+
+type RemotePattern = { protocol: "http" | "https"; hostname: string; port?: string };
+
+function parseImageSources(env: NodeJS.ProcessEnv): RemotePattern[] {
+  return env.IMAGE_SOURCES
+    ? env.IMAGE_SOURCES.split(",").map((url) => {
+        const { hostname, protocol, port } = new URL(url.trim());
+        return {
+          protocol: protocol.replace(":", "") as RemotePattern["protocol"],
+          hostname,
+          port: port || undefined,
+        };
+      })
+    : [];
+}
+
+export function createNextConfig(options: NjaNextConfigOptions): NextConfig {
+  const env = process.env;
+  const reactCompiler = options.reactCompiler === true;
+
+  const config: NextConfig = {
+    // The e2e stack (scripts/e2e.sh) runs a PRODUCTION build of this app while a
+    // `next dev` server may still be running against the same worktree. `next
+    // build` and `next dev` share `.next`, so a build performed underneath a live
+    // dev server clobbers it and that dev server then 404s every route. Giving
+    // the e2e build its own directory keeps the two independent. E2E_BUILD must
+    // be set for `next build` AND for `next start`, or `start` looks in `.next`
+    // and serves someone else's output.
+    ...(env.E2E_BUILD === "true" ? { distDir: ".next-e2e" } : {}),
+    cacheComponents: true,
+    partialPrefetching: true,
+    reactCompiler,
+    experimental: {
+      serverActions: {
+        bodySizeLimit: "5mb",
+      },
+      // Required by `unauthorized()` (next/navigation), which ServerSession.checkPermission
+      // calls to deny access. Without this flag the function throws a plain Error instead of
+      // rendering the nearest unauthorized.tsx.
+      authInterrupts: options.authInterrupts ?? true,
+      turbopackGc: true,
+      turbopackLazyDynamicImports: true,
+      ...(reactCompiler ? { turbopackRustReactCompiler: true } : {}),
+    },
+    allowedDevOrigins: options.devOrigins,
+    pageExtensions: options.mdx ? ["ts", "tsx", "mdx"] : ["ts", "tsx"],
+    images: {
+      minimumCacheTTL: options.imageMinimumCacheTTL ?? 60,
+      remotePatterns: parseImageSources(env),
+      dangerouslyAllowLocalIP: true,
+    },
+    poweredByHeader: false,
+    reactStrictMode: false,
+    env: {
+      NEXT_PUBLIC_API_URL: env.NEXT_PUBLIC_API_URL ?? "",
+      NEXT_PUBLIC_ADDRESS: env.NEXT_PUBLIC_ADDRESS ?? "",
+      NEXT_PUBLIC_VAPID_PUBLIC_KEY: env.NEXT_PUBLIC_VAPID_PUBLIC_KEY ?? "",
+      NEXT_PUBLIC_GOOGLE_MAPS_API_KEY: env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY ?? "",
+      ...options.env,
+    },
+    // Inlined replacement for @serwist/turbopack's withSerwist wrapper, which
+    // does nothing but append these two entries. Requiring the package here
+    // instead CRASHES production: it is a devDependency, next.config.js is loaded
+    // at RUNTIME by `next start`, and the web-production image installs with
+    // --prod. Do not re-add a require of any devDependency to this file.
+    ...(options.serwist ? { serverExternalPackages: ["esbuild", "esbuild-wasm"] } : {}),
+    // Next 16 builds AND serves dev with Turbopack, so this is what pins yjs to a
+    // single instance in both modes.
+    turbopack: {
+      resolveAlias: {
+        yjs: "./node_modules/yjs",
+      },
+    },
+  };
+
+  if (options.securityHeaders !== false) {
+    config.headers = async () => buildSecurityHeaders(options, process.env);
+  }
+
+  if (options.rewrites) config.rewrites = options.rewrites;
+
+  return options.extend ? options.extend(config) : config;
+}

package/src/server/JsonApiServer.ts

@@ -83,7 +83,9 @@ export async function ServerJsonApiGet(params: {
   language: string;
 }): Promise<ApiResponseInterface> {
   runServerBootstrapper();
-  const token = await getServerToken();
+  // A cached GET never sends the token, so it must not read the cookie either:
+  // the read would make a public page dynamic.
+  const token = params.classKey.cache ? undefined : await getServerToken();
 
   const apiResponse = await serverRequest({
     method: "GET",

package/src/server/ServerSession.ts

@@ -1,9 +1,37 @@
-import { cookies } from "next/headers";
+import { cookies, headers } from "next/headers";
 import { redirect } from "next/navigation";
+import { userAgent } from "next/server";
 import { ungzip } from "pako";
 import { Action, checkPermissionsFromServer, ModuleWithPermissions } from "../permissions";
+import { getRoleId } from "../roles/config";
+import { VIEWPORT_COOKIE_NAME } from "../utils/use-mobile";
+
+export interface SessionSnapshot {
+  isLogged: boolean;
+  isAdministrator: boolean;
+  token?: string;
+  sidebarOpen: boolean;
+  isMobile: boolean;
+}
 
 export class ServerSession {
+  static async read(): Promise<SessionSnapshot> {
+    const cookieStore = await cookies();
+    const headerStore = await headers();
+
+    const token = cookieStore.get("token")?.value || undefined;
+    const roles = cookieStore.get("roles")?.value;
+    const viewportCookie = cookieStore.get(VIEWPORT_COOKIE_NAME)?.value;
+
+    return {
+      isLogged: !!token,
+      isAdministrator: !!roles && roles.includes(getRoleId().Administrator),
+      token,
+      sidebarOpen: cookieStore.get("sidebar_state")?.value !== "false",
+      isMobile: viewportCookie ? viewportCookie === "1" : userAgent({ headers: headerStore }).device.type === "mobile",
+    };
+  }
+
   static async isLogged() {
     const cookieStore = await cookies();
     const token = cookieStore.get("token");

package/src/server/__tests__/JsonApiServer.test.ts

@@ -0,0 +1,41 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  getServerToken: vi.fn(),
+  serverRequest: vi.fn(),
+  translateResponse: vi.fn(),
+}));
+
+vi.mock("../token", () => ({ getServerToken: mocks.getServerToken }));
+vi.mock("../request", () => ({ serverRequest: mocks.serverRequest }));
+vi.mock("../../core/utils/translateResponse", () => ({ translateResponse: mocks.translateResponse }));
+
+import { configureServerJsonApi, ServerJsonApiGet } from "../JsonApiServer";
+
+describe("ServerJsonApiGet", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    configureServerJsonApi({ apiUrl: "http://api.test" });
+    mocks.getServerToken.mockResolvedValue("secret-token");
+    mocks.serverRequest.mockResolvedValue({ data: undefined, ok: true, status: 200, statusText: "OK" });
+    mocks.translateResponse.mockResolvedValue({});
+  });
+
+  it("does not read the token cookie for a cached GET", async () => {
+    await ServerJsonApiGet({ classKey: { name: "help", cache: "help" } as any, endpoint: "/help", language: "en" });
+
+    expect(mocks.getServerToken).not.toHaveBeenCalled();
+    expect(mocks.serverRequest).toHaveBeenCalledWith(
+      expect.objectContaining({ method: "GET", url: "http://api.test/help", cache: "help", token: undefined }),
+    );
+  });
+
+  it("reads the token cookie for an uncached GET", async () => {
+    await ServerJsonApiGet({ classKey: { name: "users" } as any, endpoint: "/users", language: "en" });
+
+    expect(mocks.getServerToken).toHaveBeenCalledTimes(1);
+    expect(mocks.serverRequest).toHaveBeenCalledWith(
+      expect.objectContaining({ method: "GET", url: "http://api.test/users", token: "secret-token" }),
+    );
+  });
+});

package/src/server/__tests__/ServerSession.read.test.ts

@@ -0,0 +1,67 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => {
+  const state = {
+    cookies: {} as Record<string, string>,
+    deviceType: undefined as string | undefined,
+  };
+  return {
+    state,
+    cookies: vi.fn(async () => ({
+      get: (name: string) => (name in state.cookies ? { name, value: state.cookies[name] } : undefined),
+    })),
+    headers: vi.fn(async () => new Headers()),
+    userAgent: vi.fn(() => ({ device: { type: state.deviceType } })),
+  };
+});
+
+vi.mock("next/headers", () => ({ cookies: mocks.cookies, headers: mocks.headers }));
+vi.mock("next/server", () => ({ userAgent: mocks.userAgent }));
+vi.mock("next/navigation", () => ({ redirect: vi.fn() }));
+
+import { configureRoles } from "../../roles/config";
+import { ServerSession } from "../ServerSession";
+
+describe("ServerSession.read", () => {
+  beforeEach(() => {
+    configureRoles({ Administrator: "role-admin", CompanyAdministrator: "role-company-admin" });
+    mocks.state.cookies = {};
+    mocks.state.deviceType = undefined;
+  });
+
+  it("reads a logged-in administrator on a desktop with the sidebar closed", async () => {
+    mocks.state.cookies = {
+      token: "t1",
+      roles: "role-admin,role-x",
+      sidebar_state: "false",
+      viewport_mobile: "0",
+    };
+
+    await expect(ServerSession.read()).resolves.toEqual({
+      isLogged: true,
+      isAdministrator: true,
+      token: "t1",
+      sidebarOpen: false,
+      isMobile: false,
+    });
+  });
+
+  it("falls back to the user agent when the viewport cookie is missing", async () => {
+    mocks.state.cookies = { token: "t1" };
+    mocks.state.deviceType = "mobile";
+
+    const snapshot = await ServerSession.read();
+
+    expect(snapshot.isMobile).toBe(true);
+  });
+
+  it("reads a logged-out visitor", async () => {
+    await expect(ServerSession.read()).resolves.toEqual({
+      isLogged: false,
+      isAdministrator: false,
+      token: undefined,
+      sidebarOpen: true,
+      isMobile: false,
+    });
+  });
+});

package/src/server/__tests__/cache.test.ts

@@ -0,0 +1,48 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const nextCache = vi.hoisted(() => ({
+  cacheLife: vi.fn(),
+  cacheTag: vi.fn(),
+  revalidateTag: vi.fn(),
+  updateTag: vi.fn(),
+}));
+
+vi.mock("next/cache", () => nextCache);
+
+import { CACHE_PROFILES, invalidateCacheTag, invalidateCacheTags, updateCacheTag } from "../cache";
+
+describe("cache helpers", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("updateCacheTag calls updateTag", async () => {
+    await updateCacheTag("help");
+
+    expect(nextCache.updateTag).toHaveBeenCalledWith("help");
+    expect(nextCache.revalidateTag).not.toHaveBeenCalled();
+  });
+
+  it('invalidateCacheTag defaults to "max"', async () => {
+    await invalidateCacheTag("help");
+
+    expect(nextCache.revalidateTag).toHaveBeenCalledWith("help", "max");
+  });
+
+  it("invalidateCacheTag passes an explicit profile through", async () => {
+    await invalidateCacheTag("help", "hours");
+
+    expect(nextCache.revalidateTag).toHaveBeenCalledWith("help", "hours");
+  });
+
+  it("invalidateCacheTags revalidates every tag", async () => {
+    await invalidateCacheTags(["a", "b"]);
+
+    expect(nextCache.revalidateTag).toHaveBeenNthCalledWith(1, "a", "max");
+    expect(nextCache.revalidateTag).toHaveBeenNthCalledWith(2, "b", "max");
+  });
+
+  it("exports the built-in cacheLife profile names", () => {
+    expect([...CACHE_PROFILES]).toEqual(["seconds", "minutes", "hours", "days", "weeks", "max", "default"]);
+  });
+});

package/src/server/__tests__/cachedGet.test.ts

@@ -0,0 +1,125 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const nextCache = vi.hoisted(() => ({
+  cacheLife: vi.fn(),
+  cacheTag: vi.fn(),
+  revalidateTag: vi.fn(),
+  updateTag: vi.fn(),
+}));
+
+vi.mock("next/cache", () => nextCache);
+
+import { cachedServerGet, statusFromDigest } from "../cachedGet";
+
+function okResponse(body: unknown) {
+  return { ok: true, status: 200, statusText: "OK", json: async () => body };
+}
+
+describe("cachedServerGet", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("calls cacheLife for a profile name", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(okResponse({ data: [] })));
+
+    await cachedServerGet({ url: "http://api.test/help", cache: "hours", language: "en" });
+
+    expect(nextCache.cacheLife).toHaveBeenCalledWith("hours");
+    expect(nextCache.cacheTag).not.toHaveBeenCalled();
+  });
+
+  it("tags non-profile values and applies the default life", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(okResponse({ data: [] })));
+
+    await cachedServerGet({ url: "http://api.test/help", cache: "help", language: "en" });
+
+    expect(nextCache.cacheTag).toHaveBeenCalledWith("help");
+    expect(nextCache.cacheLife).toHaveBeenCalledWith("max");
+  });
+
+  it("never sends Authorization", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(okResponse({ data: [] }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    await cachedServerGet({
+      url: "http://api.test/help",
+      cache: "help",
+      language: "it",
+      companyId: "company-1",
+      additionalHeaders: { "x-extra": "1" },
+    });
+
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe("http://api.test/help");
+    expect(init.method).toBe("GET");
+    expect(init.headers).not.toHaveProperty("Authorization");
+    expect(init.headers["x-language"]).toBe("it");
+    expect(init.headers["x-companyid"]).toBe("company-1");
+    expect(init.headers["x-extra"]).toBe("1");
+    expect(init).not.toHaveProperty("next");
+  });
+
+  it("returns the parsed body on success", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(okResponse({ data: { id: "1" } })));
+
+    const response = await cachedServerGet({ url: "http://api.test/help", cache: "help", language: "en" });
+
+    expect(response).toEqual({ data: { data: { id: "1" } }, ok: true, status: 200, statusText: "OK" });
+  });
+
+  it("does not cache a failed response", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi
+        .fn()
+        .mockResolvedValue({ ok: false, status: 500, statusText: "Internal Server Error", json: async () => ({}) }),
+    );
+
+    const error = await cachedServerGet({ url: "http://api.test/help", cache: "help", language: "en" }).catch(
+      (e: unknown) => e,
+    );
+
+    expect(error).toBeInstanceOf(Error);
+    expect((error as any).digest).toBe("HTTP_500");
+    expect((error as any).status).toBe(500);
+  });
+
+  it("throws a 503 when the API cannot be reached", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new TypeError("fetch failed")));
+
+    const error = await cachedServerGet({ url: "http://api.test/help", cache: "help", language: "en" }).catch(
+      (e: unknown) => e,
+    );
+
+    expect(error).toBeInstanceOf(Error);
+    expect((error as any).digest).toBe("HTTP_503");
+    expect((error as any).status).toBe(503);
+  });
+});
+
+describe("statusFromDigest", () => {
+  it("reads the status from an HTTP digest", () => {
+    expect(statusFromDigest({ digest: "HTTP_404" })).toBe(404);
+  });
+
+  it("reads the status from a sanitised production error", () => {
+    const sanitised = Object.assign(new Error("An error occurred in the Server Components render."), {
+      digest: "HTTP_500",
+    });
+    expect(statusFromDigest(sanitised)).toBe(500);
+  });
+
+  it("returns undefined for a hashed digest", () => {
+    expect(statusFromDigest({ digest: "123456" })).toBeUndefined();
+  });
+
+  it("returns undefined for values without a digest", () => {
+    expect(statusFromDigest(undefined)).toBeUndefined();
+    expect(statusFromDigest(new Error("x"))).toBeUndefined();
+  });
+});