Trust, security and accessibility

/**
 * Code Kit: security and cache headers.
 * Implements checks: sec-hsts, sec-nosniff, sec-frame-deny, sec-referrer-policy,
 *                    sec-permissions-policy, sec-csp, perf-immutable-assets
 *
 * Every value is a typed argument. This module reads no environment variables.
 */

export type SecurityHeaderOptions = {
  /** Extra origins allowed to serve scripts. Keep this list empty if you can. */
  scriptSrc?: string[];
  /** Extra origins the page may connect to (fetch, XHR, WebSocket, beacon). */
  connectSrc?: string[];
  /** Extra origins allowed to serve images. */
  imgSrc?: string[];
  /** Extra origins allowed to serve fonts. */
  fontSrc?: string[];
  /** Extra origins allowed as form action targets, e.g. a hosted checkout. */
  formAction?: string[];
  /** Extra origins allowed to be framed by this site, e.g. an embedded player. */
  frameSrc?: string[];
  /**
   * Emit `Content-Security-Policy-Report-Only` instead of the enforcing header.
   * Use this for one deploy when tightening an existing policy.
   */
  reportOnly?: boolean;
  /** Endpoint that receives CSP violation reports. */
  reportUri?: string;
  /**
   * Nonce-based script policy. Requires middleware that generates a per-request
   * nonce, which forces dynamic rendering. Off by default because a
   * static-first site cannot pay that cost. See the comment on `scriptSrcValue`.
   */
  nonce?: string;
  /** `max-age` for HSTS in seconds. Default: two years. */
  hstsMaxAge?: number;
};

export type HeaderRule = { key: string; value: string };

const DEFAULT_HSTS_MAX_AGE = 63_072_000; // 2 years

/**
 * Script policy.
 *
 * Next.js App Router streams the RSC payload through inline
 * `self.__next_f.push(...)` scripts. Allowing them requires one of:
 *
 *   1. a per-request nonce, which means reading headers in the root layout and
 *      giving up static prerendering on every route, or
 *   2. per-page hashes, which change on every build and cannot be expressed in
 *      a static header, or
 *   3. `'unsafe-inline'`.
 *
 * A static-first site takes option 3 and compensates elsewhere: no external
 * script origins, `object-src 'none'`, `base-uri 'self'`, and a locked
 * `form-action`. That combination still blocks the common injection paths
 * (remote script loading, base-tag hijacking, form exfiltration, plugin
 * execution). Document the tradeoff rather than pretending it away.
 */
function scriptSrcValue(opts: SecurityHeaderOptions): string {
  const sources = ["'self'", ...(opts.scriptSrc ?? [])];
  if (opts.nonce) {
    // Nonce mode: 'strict-dynamic' lets nonced loaders pull their own chunks.
    return [`'nonce-${opts.nonce}'`, "'strict-dynamic'", "https:", ...sources].join(" ");
  }
  return [...sources, "'unsafe-inline'"].join(" ");
}

export function contentSecurityPolicy(opts: SecurityHeaderOptions = {}): string {
  const directives: Array<[string, string[]]> = [
    ["default-src", ["'self'"]],
    ["script-src", [scriptSrcValue(opts)]],
    // Tailwind v4 with `experimental.inlineCss` emits a <style> tag per route.
    ["style-src", ["'self'", "'unsafe-inline'"]],
    ["img-src", ["'self'", "data:", "blob:", ...(opts.imgSrc ?? [])]],
    ["font-src", ["'self'", "data:", ...(opts.fontSrc ?? [])]],
    ["connect-src", ["'self'", ...(opts.connectSrc ?? [])]],
    ["frame-src", [...(opts.frameSrc ?? ["'none'"])]],
    ["frame-ancestors", ["'none'"]],
    ["form-action", ["'self'", ...(opts.formAction ?? [])]],
    ["base-uri", ["'self'"]],
    ["object-src", ["'none'"]],
    ["worker-src", ["'self'", "blob:"]],
    ["manifest-src", ["'self'"]],
    ["upgrade-insecure-requests", []],
  ];

  if (opts.reportUri) directives.push(["report-uri", [opts.reportUri]]);

  return directives
    .map(([name, values]) => (values.length ? `${name} ${values.join(" ")}` : name))
    .join("; ");
}

export function securityHeaders(opts: SecurityHeaderOptions = {}): HeaderRule[] {
  const hstsMaxAge = opts.hstsMaxAge ?? DEFAULT_HSTS_MAX_AGE;
  return [
    {
      key: "Strict-Transport-Security",
      value: `max-age=${hstsMaxAge}; includeSubDomains; preload`,
    },
    { key: "X-Content-Type-Options", value: "nosniff" },
    { key: "X-Frame-Options", value: "DENY" },
    { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
    {
      key: "Permissions-Policy",
      value: [
        "camera=()",
        "microphone=()",
        "geolocation=()",
        "payment=()",
        "usb=()",
        "magnetometer=()",
        "gyroscope=()",
        "accelerometer=()",
        "interest-cohort=()",
      ].join(", "),
    },
    { key: "Cross-Origin-Opener-Policy", value: "same-origin" },
    { key: "Cross-Origin-Resource-Policy", value: "same-origin" },
    { key: "X-DNS-Prefetch-Control", value: "on" },
    {
      key: opts.reportOnly
        ? "Content-Security-Policy-Report-Only"
        : "Content-Security-Policy",
      value: contentSecurityPolicy(opts),
    },
  ];
}

export const IMMUTABLE_ASSET_EXTENSIONS = [
  "ico",
  "png",
  "jpg",
  "jpeg",
  "gif",
  "webp",
  "avif",
  "svg",
  "woff",
  "woff2",
  "ttf",
  "otf",
] as const;

/**
 * Cache rules. Static assets get a year and `immutable`, which is only safe
 * because every asset URL carries a version query string. The manifest gets a
 * day. Feeds get an hour with a matching `s-maxage` so the CDN and the browser
 * agree.
 */
export function cacheHeaderRules() {
  return [
    {
      source: `/:path*.(${IMMUTABLE_ASSET_EXTENSIONS.join("|")})`,
      headers: [
        { key: "Cache-Control", value: "public, max-age=31536000, immutable" },
      ],
    },
    {
      source: "/manifest.webmanifest",
      headers: [
        { key: "Cache-Control", value: "public, max-age=86400, s-maxage=86400" },
      ],
    },
    {
      source: "/:path*(feed.xml|rss.xml)",
      headers: [
        {
          key: "Cache-Control",
          value: "public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400",
        },
      ],
    },
    {
      source: "/:path*(llms.txt|llms-full.txt)",
      headers: [
        {
          key: "Cache-Control",
          value: "public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400",
        },
        { key: "Content-Type", value: "text/plain; charset=utf-8" },
      ],
    },
  ];
}