@spacefast/common 0.0.11 → 0.0.13

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 { 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,8 +35,8 @@ 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. */
@@ -128,19 +128,230 @@ export const spaceBuildSettingsSchema = z
 // (enums.ts) rather than declaring a second "shared"/"dedicated" enum —
 // space placement mode and normalized site class are the same axis.
 export const spacePlacementModeSchema = normalizedSiteClass;
+// No region knob: a space binds to the site it was placed on at creation and
+// the only placement change that relocates it is shared -> dedicated. Data
+// location is chosen once, at creation, and never changes.
 export const spacePlacementConfigSchema = z
     .object({
-    region: z.string().trim().min(1).optional(),
     mode: spacePlacementModeSchema.optional(),
     burstable: z.boolean().optional(),
 })
     .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 rejectReservedDataSourceRecordKeys(value) {
+    if (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.keys(value).some((name) => RESERVED_DATA_SOURCE_NAMES.has(name))) {
+        return null;
+    }
+    return value;
+}
+export const spaceDataSourcesSchema = z
+    .preprocess(rejectReservedDataSourceRecordKeys, 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()
@@ -252,26 +463,31 @@ 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. 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.
@@ -291,7 +507,88 @@ export const spacePublishOptionsSchema = z
         "Originals keep serving unchanged. Default off."),
 })
     .describe("Client publish-time options consumed by the Spacefast CLI, not the runtime.");
-export const spaceConfigFileSchema = spaceConfigSchema.extend({
+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;
+    }
+});
+export const spaceConfigFileAccessSchema = 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.",
+        });
+    }
+})
+    .describe("File-only public access declaration. It is inactive until the Space is claimed.");
+/**
+ * Overrides for the worker `sf publish` compiles.
+ *
+ * Every field 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 spaceFunctionsOptionsSchema = z
+    .object({
+    entry: z
+        .string()
+        .optional()
+        .describe("Path to the worker entry module, relative to the published directory. " +
+        "Detected automatically when absent; naming one that does not exist is an error " +
+        "rather than a silent static publish."),
+    database: z
+        .boolean()
+        .default(false)
+        .describe("Give the worker `env.DB`, a D1-shaped binding to this space's database. " +
+        "Declared rather than detected: a capability an author did not ask for is " +
+        "authority they cannot see, and reading it out of minified build output " +
+        "would be a guess. Off by default, so a worker reaches nothing until it says so."),
+    compatibilityDate: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .optional()
+        .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("Overrides for the worker compiled at publish time.");
+export const spaceConfigFileSchema = spaceConfigBaseSchema.extend({
     $schema: z
         .string()
         .optional()
@@ -301,8 +598,9 @@ 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(),
+    access: spaceConfigFileAccessSchema.optional(),
+    functions: spaceFunctionsOptionsSchema.optional(),
 });
 /**
  * The published JSON Schema artifact for `sf.jsonc`, generated from the