@spacefast/common 0.0.12 → 0.0.17

package/dist/contracts/space-config.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { BRAND } from "../brand.js";
-import { runtimeRuleSchema } from "./access.js";
+import { serviceOrigin } from "../config/domains.js";
 import { normalizedSiteClass } from "./enums.js";
+import { GRANT_RESOURCE_PATTERN_LIMIT, normalizeGrantResourcePattern } from "./grants.js";
 export const SPACE_CONFIG_CANONICAL_FILE = "sf.jsonc";
 export const SPACE_CONFIG_ALIAS_FILES = [
     "spacefast.jsonc",
@@ -35,17 +35,19 @@ export const SPACE_CONFIG_CAPS = {
     injectSnippetBytes: 8 * 1024,
     /** Max snippets per `inject` array. */
     injectSnippets: 16,
-    /** Max `access.rules` entries in the file lane. */
-    accessRules: 100,
+    /** Max public WordPress sources exposed to repository builds. */
+    dataSources: 32,
     /** Max `theme` color token length. */
     themeColorChars: 64,
     /** Max `theme.logo` URL/path length. */
     themeLogoChars: 2000,
     /** Max `theme.name` display-name length. */
     themeNameChars: 120,
+    /** Max top-level `name` (space display name) length. Matches the stored column. */
+    nameChars: 255,
 };
 /** Published JSON Schema URL for `sf.jsonc` ($schema autocomplete). */
-export const SPACE_CONFIG_SCHEMA_URL = `${BRAND.websiteOrigin}/schemas/sf.json`;
+export const SPACE_CONFIG_SCHEMA_URL = `${serviceOrigin("www", "prod")}/schemas/sf.json`;
 // Pages theme tokens: visual values consumed by publish-rendered site pages.
 // Presentation only — never layout, behavior, or protocol.
 // Color grammar accepts hex/rgb(a)/hsl(a)/
@@ -138,11 +140,219 @@ export const spacePlacementConfigSchema = z
 })
     .strict()
     .describe("Placement controls for this space.");
-// SpaceConfig (internal-docs/platform.md "SpaceConfig"): the declarative
-// serving config — also the shape of `sf.jsonc` minus `$schema`/`space`.
+const RESERVED_DATA_SOURCE_NAMES = new Set(["__proto__", "constructor", "prototype"]);
+export const dataSourceNameSchema = z
+    .string()
+    .min(1)
+    .max(128)
+    .regex(/^[A-Za-z_][A-Za-z0-9_]*$/, {
+    message: "Use a non-reserved name that starts with a letter or underscore and contains only letters, numbers, and underscores.",
+})
+    .refine((name) => !RESERVED_DATA_SOURCE_NAMES.has(name), {
+    message: "Use a non-reserved name that starts with a letter or underscore and contains only letters, numbers, and underscores.",
+})
+    .describe("Stable source identifier: 1-128 letters, numbers, or underscores; starts with a letter or underscore; excludes __proto__, constructor, and prototype.")
+    .meta({ not: { enum: [...RESERVED_DATA_SOURCE_NAMES] } });
+const WORDPRESS_DATA_SOURCE_URL_MESSAGE = "WordPress data source URLs must use lowercase https:// with a valid DNS name, canonical dotted-decimal IPv4 address, or bracketed IPv6 address. Whitespace, controls, malformed percent encoding, encoded percent signs, slashes or backslashes, credentials, queries, fragments, trailing-dot hosts, and port 0 are not allowed.";
+const WORDPRESS_DATA_SOURCE_URL_PATTERN = /^https:\/\/[^/?#@%\\\s]+(?:\/[^?#\\\s]*)?$/u;
+const WORDPRESS_DATA_SOURCE_WHITESPACE_PATTERN = /\p{White_Space}/u;
+const DNS_LABEL_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+const IPV6_LITERAL_PATTERN = /^[0-9a-f:]+$/i;
+const DECIMAL_PORT_PATTERN = /^\d{1,5}$/;
+const IPV4_OCTET_PATTERN = /^(?:0|[1-9]\d{0,2})$/;
+function hasAsciiControlCharacter(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code <= 0x1f || (code >= 0x7f && code <= 0x9f))
+            return true;
+    }
+    return false;
+}
+function isCanonicalIpv4Address(value) {
+    const octets = value.split(".");
+    return (octets.length === 4 &&
+        octets.every((octet) => IPV4_OCTET_PATTERN.test(octet) && Number.parseInt(octet, 10) <= 255));
+}
+function isValidDnsHostname(value) {
+    if (value.length === 0 || value.length > 253 || value.endsWith("."))
+        return false;
+    const labels = value.split(".");
+    return labels.every((label) => label.length > 0 && label.length <= 63 && DNS_LABEL_PATTERN.test(label));
+}
+function parseWordPressAuthority(authority) {
+    if (!authority || authority.includes("@") || authority.includes("%"))
+        return null;
+    let rawHostname;
+    let rawPort = null;
+    let ipv6 = false;
+    if (authority.startsWith("[")) {
+        const closingBracket = authority.indexOf("]");
+        if (closingBracket <= 1 || authority.indexOf("]", closingBracket + 1) !== -1)
+            return null;
+        rawHostname = authority.slice(1, closingBracket);
+        const suffix = authority.slice(closingBracket + 1);
+        if (suffix) {
+            if (!suffix.startsWith(":"))
+                return null;
+            rawPort = suffix.slice(1);
+        }
+        ipv6 = true;
+    }
+    else {
+        if (authority.includes("[") || authority.includes("]"))
+            return null;
+        const firstColon = authority.indexOf(":");
+        if (firstColon !== authority.lastIndexOf(":"))
+            return null;
+        if (firstColon === -1) {
+            rawHostname = authority;
+        }
+        else {
+            rawHostname = authority.slice(0, firstColon);
+            rawPort = authority.slice(firstColon + 1);
+        }
+    }
+    if (!rawHostname || rawHostname.endsWith("."))
+        return null;
+    if (rawPort !== null) {
+        if (!DECIMAL_PORT_PATTERN.test(rawPort))
+            return null;
+        const port = Number.parseInt(rawPort, 10);
+        if (port === 0 || port > 65_535)
+            return null;
+    }
+    try {
+        const url = new URL(`https://${authority}/`);
+        if (ipv6) {
+            if (!IPV6_LITERAL_PATTERN.test(rawHostname))
+                return null;
+            if (!url.hostname.startsWith("[") || !url.hostname.endsWith("]"))
+                return null;
+        }
+        else {
+            const normalizedHostname = url.hostname;
+            if (normalizedHostname.startsWith("[") || normalizedHostname.endsWith("]"))
+                return null;
+            if (isCanonicalIpv4Address(normalizedHostname)) {
+                if (rawHostname !== normalizedHostname || !isCanonicalIpv4Address(rawHostname))
+                    return null;
+            }
+            else if (!isValidDnsHostname(normalizedHostname)) {
+                return null;
+            }
+        }
+        return url.origin;
+    }
+    catch {
+        return null;
+    }
+}
+function canonicalizeWordPressPath(rawPath) {
+    if (!rawPath)
+        return "";
+    // Reject encoded percents so validation has one authoritative decode layer.
+    // Encoded path separators are never valid in a WordPress source base path.
+    if (/%(?:25|2f|5c)/i.test(rawPath))
+        return null;
+    let decodedPath = rawPath;
+    if (rawPath.includes("%")) {
+        const encodedSegments = rawPath.split("/");
+        let nextPath;
+        try {
+            nextPath = decodeURIComponent(rawPath);
+            void encodeURIComponent(nextPath);
+        }
+        catch {
+            return null;
+        }
+        const decodedSegments = nextPath.split("/");
+        if (decodedSegments.some((segment, index) => (segment === "." || segment === "..") && encodedSegments[index] !== segment)) {
+            return null;
+        }
+        if (hasAsciiControlCharacter(nextPath) ||
+            nextPath.includes("\\") ||
+            WORDPRESS_DATA_SOURCE_WHITESPACE_PATTERN.test(nextPath.replaceAll(" ", ""))) {
+            return null;
+        }
+        decodedPath = nextPath;
+    }
+    const url = new URL("https://path.invalid/");
+    url.pathname = decodedPath;
+    return url.pathname === "/" ? "" : url.pathname.replace(/\/+$/, "");
+}
+function canonicalWordPressDataSourceUrl(value) {
+    if (!value.startsWith("https://") ||
+        hasAsciiControlCharacter(value) ||
+        WORDPRESS_DATA_SOURCE_WHITESPACE_PATTERN.test(value) ||
+        value.includes("\\") ||
+        value.includes("?") ||
+        value.includes("#")) {
+        return null;
+    }
+    const remainder = value.slice("https://".length);
+    const pathIndex = remainder.indexOf("/");
+    const authority = pathIndex === -1 ? remainder : remainder.slice(0, pathIndex);
+    const rawPath = pathIndex === -1 ? "" : remainder.slice(pathIndex);
+    const origin = parseWordPressAuthority(authority);
+    const pathname = canonicalizeWordPressPath(rawPath);
+    return origin && pathname !== null ? `${origin}${pathname}` : null;
+}
+export const wordpressDataSourceUrlSchema = z
+    .string()
+    .min(1)
+    .max(2048)
+    .refine((value) => !hasAsciiControlCharacter(value), {
+    message: WORDPRESS_DATA_SOURCE_URL_MESSAGE,
+})
+    .regex(WORDPRESS_DATA_SOURCE_URL_PATTERN, { message: WORDPRESS_DATA_SOURCE_URL_MESSAGE })
+    .url({ message: WORDPRESS_DATA_SOURCE_URL_MESSAGE })
+    .refine((value) => canonicalWordPressDataSourceUrl(value) !== null, {
+    message: WORDPRESS_DATA_SOURCE_URL_MESSAGE,
+})
+    .overwrite((value) => canonicalWordPressDataSourceUrl(value) ?? value)
+    .max(2048)
+    .describe("Canonical public WordPress URL: lowercase https:// scheme; IDNA-normalized DNS labels (1-63 characters each, 253 total, alphanumeric edges, alphanumeric or hyphen interior), canonical dotted-decimal IPv4, or bracketed hexadecimal IPv6; optional nonzero port and UTF-8 path. Percent escapes are validated and canonicalized; encoded percent signs, slashes, backslashes, controls, invalid UTF-8, whitespace other than encoded ASCII path spaces, credentials, queries, fragments, and trailing-dot hosts are rejected. Default port, host case, IDNs, dot segments, path encoding, and trailing path slashes are normalized before storage.");
+export const wordpressDataSourceSchema = z
+    .object({
+    kind: z.literal("wordpress"),
+    url: wordpressDataSourceUrlSchema,
+})
+    .strict()
+    .describe("A public WordPress site exposed to repository builds as a content source.");
+function hasNoReservedDataSourceRecordKeys(value) {
+    return !(typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.keys(value).some((name) => RESERVED_DATA_SOURCE_NAMES.has(name)));
+}
+export const spaceDataSourcesSchema = z
+    .unknown()
+    .refine(hasNoReservedDataSourceRecordKeys, { message: "dataSources contains a reserved name." })
+    .pipe(z
+    .record(dataSourceNameSchema, wordpressDataSourceSchema)
+    .refine((sources) => Object.keys(sources).length <= SPACE_CONFIG_CAPS.dataSources, {
+    message: `dataSources supports up to ${SPACE_CONFIG_CAPS.dataSources} entries.`,
+}))
+    .meta({
+    maxProperties: SPACE_CONFIG_CAPS.dataSources,
+    description: `Named public WordPress sources. Supports at most ${SPACE_CONFIG_CAPS.dataSources} entries.`,
+});
+function refineDefaultDataSource(config, ctx) {
+    if (config.defaultDataSource !== undefined &&
+        !Object.prototype.hasOwnProperty.call(config.dataSources ?? {}, config.defaultDataSource)) {
+        ctx.addIssue({
+            code: "custom",
+            message: "defaultDataSource must name a configured dataSources entry.",
+            path: ["defaultDataSource"],
+        });
+    }
+}
+// Shared SpaceConfig fields (internal-docs/platform.md "SpaceConfig"): the
+// declarative serving config also accepted by `sf.jsonc`. Cloud-only overlay
+// fields such as pre-build data sources are added to `spaceConfigSchema` below.
 // Meta caps are the spec parser-safety numbers (title 300, description 1000,
 // image 2000); plan policy may lower them but never raise them.
-export const spaceConfigSchema = z.object({
+const spaceConfigBaseSchema = z.object({
     index: z
         .union([z.string().min(1), z.literal(false)])
         .optional()
@@ -156,11 +366,11 @@ export const spaceConfigSchema = z.object({
         }),
     ])
         .optional()
-        .describe('Fallback document; "/index.html" means SPA. Default: nearest 404.html.'),
+        .describe('Fallback document. "/index.html" means SPA. Defaults to the nearest 404.html.'),
     cleanUrls: z
         .boolean()
         .optional()
-        .describe("Serve flat `<name>.html` files at their extensionless URL (/about serves about.html). Default: on, unless a 200-status SPA fallback is configured."),
+        .describe("Serve flat `<name>.html` files at their extensionless URL (`/about` serves `about.html`). Defaults to on, unless a 200-status SPA fallback is configured."),
     listing: z.boolean().optional().describe("Enable automatic directory listings."),
     meta: z
         .object({
@@ -254,46 +464,159 @@ export const spaceConfigSchema = z.object({
     })
         .optional(),
 });
+export const spaceConfigSchema = spaceConfigBaseSchema
+    .extend({
+    dataSources: spaceDataSourcesSchema
+        .optional()
+        .describe(`Named public WordPress sources exposed to repository builds; at most ${SPACE_CONFIG_CAPS.dataSources} entries.`),
+    defaultDataSource: dataSourceNameSchema
+        .optional()
+        .describe("Name of the configured source exposed through `WORDPRESS_URL`. It must match a `dataSources` entry. When omitted, the first source in bytewise name order is used."),
+})
+    .superRefine(refineDefaultDataSource);
+export function compareDataSourceNames(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+export function resolveDefaultDataSourceName(config) {
+    const names = Object.keys(config?.dataSources ?? {}).toSorted(compareDataSourceNames);
+    const configuredDefault = config?.defaultDataSource;
+    return configuredDefault &&
+        Object.prototype.hasOwnProperty.call(config?.dataSources ?? {}, configuredDefault)
+        ? configuredDefault
+        : (names[0] ?? null);
+}
 export function spaceSuperpowersEnabled(config) {
     const superpowers = config?.superpowers;
     return superpowers?.enabled !== false && superpowers?.disable_all_injection !== true;
 }
-// The declarative file-lane access/firewall block (internal-docs/
-// internal-docs/access-plan.html, "file" provenance): the SAME unified Rule shape
-// the policy document and the cloud lane use — no parallel contract. Rules
-// committed here compile at publish finalize and version + roll back WITH the
-// content version; live edits without a republish belong to the cloud lane
-// (`sf access`). The file lane lives ONLY in the config FILE — the API `config`
-// overlay never carries it (single-home, no drift).
-export const spaceAccessConfigSchema = z
-    .object({
-    rules: z
-        .array(runtimeRuleSchema)
-        .max(SPACE_CONFIG_CAPS.accessRules)
-        .default([])
-        .describe("Ordered unified access/firewall rules; first match wins."),
-})
-    .describe("Declarative access lane: rules compiled at publish that version and roll back with the site.");
 // The `sf.jsonc` FILE shape (internal-docs/platform.md "Space
 // Configuration Files"): SpaceConfig plus the editor `$schema` pointer and the
 // optional `space` link (slug or `spc_` id) resolved by CLI/publish flows.
-// Routing never lives here — redirects/rewrites/proxies/headers stay
-// exclusively in `_redirects`/`_headers` (one way per concern).
-// Client-side publish options (caching plan §6): consumed by the CLI/agent
-// publish tooling before upload, never by the runtime — like `$schema` and
-// `space`, this key lives only in the FILE shape and never reaches the space
-// `config` overlay.
-export const spacePublishOptionsSchema = z
+// Routing rules (`redirects`/`rewrites`/`headers`) are sf.jsonc keys too, but they belong
+// to the routing compiler, not to this shape: it resolves serving, they compile
+// into the canonical rules and merge behind `_redirects`/`_headers`.
+const spaceConfigPublicPatternSchema = z
+    .string()
+    .min(1)
+    .max(1025)
+    .transform((candidate, context) => {
+    const excluded = candidate.startsWith("!");
+    try {
+        const normalized = normalizeGrantResourcePattern(excluded ? candidate.slice(1) : candidate);
+        return excluded ? `!${normalized}` : normalized;
+    }
+    catch (error) {
+        context.addIssue({
+            code: "custom",
+            message: error instanceof Error ? error.message : "Invalid access.public resource pattern.",
+        });
+        return z.NEVER;
+    }
+});
+const spaceConfigFileAccessObjectSchema = z
+    .object({
+    public: z
+        .array(spaceConfigPublicPatternSchema)
+        .max(GRANT_RESOURCE_PATTERN_LIMIT)
+        .describe("Always-public live paths. Prefix exclusions with !; * and ** are whole-segment wildcards."),
+})
+    .strict()
+    .superRefine((value, context) => {
+    const seen = new Set();
+    let inclusionCount = 0;
+    value.public.forEach((pattern, index) => {
+        if (seen.has(pattern)) {
+            context.addIssue({
+                code: "custom",
+                path: ["public", index],
+                message: "access.public patterns must be unique.",
+            });
+        }
+        seen.add(pattern);
+        if (!pattern.startsWith("!"))
+            inclusionCount += 1;
+    });
+    if (value.public.length > 0 && inclusionCount === 0) {
+        context.addIssue({
+            code: "custom",
+            path: ["public"],
+            message: "access.public requires at least one inclusion pattern.",
+        });
+    }
+});
+export const spaceConfigFileAccessSchema = z
+    .union([
+    z
+        .literal("public")
+        .describe('Shorthand for { "public": ["/**"] }: the whole live space is public.')
+        .transform(() => ({ public: ["/**"] })),
+    spaceConfigFileAccessObjectSchema,
+])
+    .describe("File-only public access declaration. It is inactive until the space is claimed.");
+/**
+ * Zero: a transactional app with its own database.
+ *
+ * Both entries are required because Zero is never inferred. A runtime that owns
+ * a database must not spring into existence from a directory shape, so the only
+ * way to get one is to say so — and once said, a server or client that cannot
+ * be resolved fails the publish rather than degrading to static files.
+ */
+export const spaceRuntimeZeroSchema = z
     .object({
-    fingerprint: z
+    kind: z.literal("zero"),
+    server: z
+        .string()
+        .trim()
+        .min(1)
+        .describe("Path to the server entry module, relative to the published directory."),
+    client: z
+        .string()
+        .trim()
+        .min(1)
+        .describe("Path to the client entry module, relative to the published directory."),
+})
+    .describe("Zero: a transactional app with its own database, compiled at publish time.");
+/**
+ * Functions: the worker `sf publish` compiles.
+ *
+ * Every field beyond `kind` is optional because the normal case is detection: a
+ * project with `handler.ts` or an OpenNext build needs no configuration at all.
+ * These exist for the layouts detection cannot guess — a worker somewhere
+ * unusual, or a compatibility date the author wants pinned rather than
+ * defaulted.
+ */
+export const spaceRuntimeFunctionsSchema = z
+    .object({
+    kind: z.literal("functions"),
+    entry: z
+        .string()
+        .optional()
+        .describe("Path to the worker entry module, relative to the published directory. " +
+        "When absent, the server detects it automatically. Naming an entry that does not exist is an error, not a silent static publish."),
+    database: z
         .boolean()
+        .default(false)
+        .describe("Give the worker `env.DB`, a D1-shaped binding to this space's database. " +
+        "This capability is declared, not detected. A capability an author did not request is authority they cannot see. Reading it from minified build output is a guess. Defaults to off, so a worker reaches nothing until it says so."),
+    compatibilityDate: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
         .optional()
-        .describe("Publish-time asset fingerprinting: adds content-hashed immutable aliases " +
-        "(name.<sha256-8>.ext) for stable assets and rewrites exact HTML/CSS references. " +
-        "Originals keep serving unchanged. Default off."),
+        .describe("Runtime compatibility date this worker was written against. Pinning it makes rollback honest. Promoting an old version restores the semantics it was built with."),
 })
-    .describe("Client publish-time options consumed by the Spacefast CLI, not the runtime.");
-export const spaceConfigFileSchema = spaceConfigSchema.extend({
+    .describe("Functions: a worker compiled at publish time.");
+/**
+ * The one runtime declaration, discriminated on `kind`.
+ *
+ * One block, one kind — a version cannot express two runtimes at once, so the
+ * ambiguity never has to be resolved downstream. File-only on purpose: a
+ * runtime is a fact about the content of a version, so it rolls forward and
+ * back with the version instead of being set through the API config overlay.
+ */
+export const spaceRuntimeSchema = z
+    .discriminatedUnion("kind", [spaceRuntimeZeroSchema, spaceRuntimeFunctionsSchema])
+    .describe("Runtime this version's code runs on. Omit it for a static space. Functions is also detected from the published directory when it is not stated.");
+export const spaceConfigFileSchema = spaceConfigBaseSchema.extend({
     $schema: z
         .string()
         .optional()
@@ -303,8 +626,17 @@ export const spaceConfigFileSchema = spaceConfigSchema.extend({
         .min(1)
         .optional()
         .describe("Optional space link: a space slug or spc_ id this project publishes to."),
-    access: spaceAccessConfigSchema.optional(),
-    publish: spacePublishOptionsSchema.optional(),
+    // File-owned naming: the live version's config decides the display name, so
+    // it rolls forward and back with the version like every other content fact.
+    name: z
+        .string()
+        .trim()
+        .min(1)
+        .max(SPACE_CONFIG_CAPS.nameChars)
+        .optional()
+        .describe("Display name for this space. While set, the API refuses to rename the space."),
+    access: spaceConfigFileAccessSchema.optional(),
+    runtime: spaceRuntimeSchema.optional(),
 });
 /**
  * The published JSON Schema artifact for `sf.jsonc`, generated from the
@@ -312,12 +644,102 @@ export const spaceConfigFileSchema = spaceConfigSchema.extend({
  * autocomplete and validation.
  */
 export function spaceConfigJsonSchema() {
-    return stripHiddenSpaceConfigKeys({
+    const schema = stripHiddenSpaceConfigKeys({
         ...z.toJSONSchema(spaceConfigFileSchema, { target: "draft-7", io: "input" }),
         $id: SPACE_CONFIG_SCHEMA_URL,
         title: "Spacefast space configuration (sf.jsonc)",
     });
+    // `redirects`, `rewrites` and `headers` are real sf.jsonc keys, owned by the routing
+    // compiler rather than by the serving shape above — which is why they are
+    // described here instead of in the zod schema that resolves serving. An editor
+    // reading this file still has to know they exist, or the documented routing
+    // examples read as unknown keys.
+    return {
+        ...schema,
+        properties: {
+            ...schema.properties,
+            ...SPACE_CONFIG_ROUTING_SCHEMA_PROPERTIES,
+        },
+    };
 }
+const SPACE_CONFIG_ROUTING_SCHEMA_PROPERTIES = {
+    redirects: {
+        type: "array",
+        description: "Browser redirect rules. Same matcher grammar as _redirects, and _redirects rules match first.",
+        items: {
+            type: "object",
+            properties: {
+                source: {
+                    type: "string",
+                    minLength: 1,
+                    description: "Request path to match. * is a splat, :name captures a segment.",
+                },
+                destination: {
+                    type: "string",
+                    minLength: 1,
+                    description: "Path or absolute URL. :splat and :name from the source are substituted.",
+                },
+                status: {
+                    enum: [301, 302, 303, 307, 308],
+                    default: 302,
+                    description: "Redirect status. To serve other content under this URL, use rewrites.",
+                },
+            },
+            required: ["source", "destination"],
+            additionalProperties: false,
+        },
+    },
+    rewrites: {
+        type: "array",
+        description: "Rewrite and proxy rules: the URL stays, the content comes from the destination. _redirects rules match first, then redirects.",
+        items: {
+            type: "object",
+            properties: {
+                source: {
+                    type: "string",
+                    minLength: 1,
+                    description: "Request path to match. * is a splat, :name captures a segment.",
+                },
+                destination: {
+                    type: "string",
+                    minLength: 1,
+                    description: "Path to serve under this URL, or an absolute URL to proxy. :splat and :name from the source are substituted.",
+                },
+                cache: {
+                    const: "shared",
+                    description: "Let shared caches store the proxy response. Absolute-URL destinations only.",
+                },
+            },
+            required: ["source", "destination"],
+            additionalProperties: false,
+        },
+    },
+    headers: {
+        type: "array",
+        description: "Response headers to set on matching requests. A _headers rule wins on the same header name.",
+        items: {
+            type: "object",
+            properties: {
+                source: { type: "string", minLength: 1, description: "Request path to match." },
+                headers: {
+                    type: "array",
+                    minItems: 1,
+                    items: {
+                        type: "object",
+                        properties: {
+                            key: { type: "string", minLength: 1 },
+                            value: { type: "string" },
+                        },
+                        required: ["key", "value"],
+                        additionalProperties: false,
+                    },
+                },
+            },
+            required: ["source", "headers"],
+            additionalProperties: false,
+        },
+    },
+};
 /*
  * Hidden-feature discipline (internal-docs/build-pipeline-plan.md): the
  * `experimental_gutenberg` flag and its `inject` companion are ACCEPTED by the