@spacefast/common 0.2.2 → 0.4.1

package/dist/contracts/space-config.js

@@ -1,8 +1,6 @@
 import { z } from "zod";
-import { serviceOrigin } from "../config/domains.js";
 import { normalizeSlug } from "../utils/slug.js";
-import { defaultPlanNameSchema, planCatalogSchema } from "./commerce.js";
-import { GRANT_RESOURCE_PATTERN_LIMIT, identityConnectionPublicKeySchema, normalizeGrantResourcePattern, } from "./grants.js";
+import { GRANT_RESOURCE_PATTERN_LIMIT, identityConnectionPublicKeySchema, normalizeGrantResourcePattern, } from "./grants-core.js";
 export const SPACE_CONFIG_CANONICAL_FILE = "sf.jsonc";
 export const SPACE_CONFIG_ALIAS_FILES = [
     "spacefast.jsonc",
@@ -74,16 +72,16 @@ export const SPACE_CONFIG_CAPS = {
     /** Max `system.api.allowedOrigins` entries. */
     systemApiAllowedOrigins: 32,
     /** Max `system.tokenIssuers` entries. */
-    systemTokenIssuers: 16,
+    systemTokenIssuers: 1,
     /** Max `system.tokenIssuers[].issuer` length. */
     systemIssuerChars: 512,
     /** Max `system.tokenIssuers[].keys` entries. */
-    systemIssuerKeys: 16,
+    systemIssuerKeys: 5,
     /** Max `system.tokenIssuers[].keys[].kid` length. */
     systemKeyIdChars: 64,
     /** Exact raw Ed25519 public-key length after base64url encoding. */
     systemPublicKeyChars: 43,
-    /** Max `system.tokenIssuers[].proof` length. */
+    /** Max `system.tokenIssuers[].proofs[]` length. */
     systemProofChars: 4096,
     /** Max `system.subscriptions` entries. */
     systemSubscriptions: 32,
@@ -92,8 +90,15 @@ export const SPACE_CONFIG_CAPS = {
     /** Max length of a `system.subscriptions[].events` name. */
     systemEventChars: 128,
 };
-/** Published JSON Schema URL for `sf.jsonc` ($schema autocomplete). */
-export const SPACE_CONFIG_SCHEMA_URL = `${serviceOrigin("www", "prod")}/schemas/sf.json`;
+/**
+ * Published JSON Schema URL for `sf.jsonc` ($schema autocomplete).
+ *
+ * A format identifier, not a brand string: the `$schema` an editor resolves is
+ * one document at one URL for every space, so it is compiled in rather than
+ * resolved through the hostname registry. The literal is checked against that
+ * registry in `config/domains.test.ts`.
+ */
+export const SPACE_CONFIG_SCHEMA_URL = "https://spacefast.com/schemas/sf.json";
 // Pages theme tokens: presentation only, never layout, behavior, or protocol.
 // The color grammar accepts hex, rgb(a), hsl(a), and named CSS colors, and
 // rejects anything that could escape a style context.
@@ -168,9 +173,8 @@ export const spaceBuildSettingsSchema = z
 })
     .strict()
     .describe("Remote build settings used by repository builds.");
-// Every space gets its own site, so there is nothing to place between: no mode,
-// no region knob. `burstable` says whether the space's site may burst provider
-// PHP workers. Data location is chosen once, at creation, and never changes.
+// Placement controls whether the Space's site may burst provider PHP workers.
+// Data location is chosen once, at creation, and never changes.
 export const spacePlacementConfigSchema = z
     .object({
     burstable: z.boolean().optional(),
@@ -484,11 +488,8 @@ const spaceConfigBaseSchema = z.object({
         .boolean()
         .optional()
         .describe("Accepted serving flag; runtime enforcement ships separately."),
-    // Undescribed on purpose (hidden, experimental): enables the finalize-time
-    // build pipeline. Accepted without diagnostics.
-    experimental_gutenberg: z.boolean().optional(),
-    // Hidden, experimental: static HTML snippets, honored only when
-    // `experimental_gutenberg` is true. Byte caps are enforced by the shared
+    // Hidden, experimental: static HTML snippets injected into served pages,
+    // honored whenever they are present. Byte caps are enforced by the shared
     // validator (inject_snippet_too_large / inject_invalid).
     inject: z
         .object({
@@ -847,18 +848,49 @@ export const systemHostnamesSchema = z
         .describe("Apex hostname for the white-label surface."),
 })
     .strict();
+const systemHttpsOriginSchema = systemHttpsUrlSchema
+    .refine((value) => {
+    try {
+        const url = new URL(value);
+        return (url.protocol === "https:" &&
+            !url.username &&
+            !url.password &&
+            !url.search &&
+            !url.hash &&
+            url.pathname === "/" &&
+            SYSTEM_HOSTNAME_PATTERN.test(url.hostname));
+    }
+    catch {
+        return false;
+    }
+}, "must be an HTTPS origin without credentials, path, query, or fragment")
+    .transform((value) => new URL(value).origin);
 export const systemApiSchema = z
     .object({
-    origin: systemHttpsUrlSchema
+    origin: systemHttpsOriginSchema
+        .refine((value) => new URL(value).port === "", "custom API origins use the default HTTPS port")
         .optional()
         .describe("https origin the partner API is served from."),
     allowedOrigins: z
-        .array(systemHttpsUrlSchema)
+        .array(systemHttpsOriginSchema)
         .max(SPACE_CONFIG_CAPS.systemApiAllowedOrigins)
         .optional()
         .describe("https origins permitted to call the partner API (CORS)."),
 })
     .strict();
+export const systemTokenIssuerKeysSchema = z
+    .array(identityConnectionPublicKeySchema)
+    .min(1)
+    .max(SPACE_CONFIG_CAPS.systemIssuerKeys)
+    .refine((keys) => new Set(keys.map((key) => key.kid)).size === keys.length, {
+    message: "Key IDs must be unique.",
+})
+    .describe("Public verification keys, addressed by unique key ID.");
+export const systemTokenIssuerProofsSchema = z
+    .array(z.string().trim().min(1).max(SPACE_CONFIG_CAPS.systemProofChars))
+    .min(1)
+    .max(SPACE_CONFIG_CAPS.systemIssuerKeys)
+    .describe("Signed challenge JWTs, one per new key, to activate the issuer or rotate keys. Read audience and challenge from manifestStatus.");
 export const systemTokenIssuerSchema = z
     .object({
     issuer: z
@@ -867,18 +899,8 @@ export const systemTokenIssuerSchema = z
         .min(1)
         .max(SPACE_CONFIG_CAPS.systemIssuerChars)
         .describe("Issuer identifier (the iss claim tokens must carry)."),
-    keys: z
-        .array(identityConnectionPublicKeySchema)
-        .min(1)
-        .max(SPACE_CONFIG_CAPS.systemIssuerKeys)
-        .describe("Public verification keys, addressed by key id."),
-    proof: z
-        .string()
-        .trim()
-        .min(1)
-        .max(SPACE_CONFIG_CAPS.systemProofChars)
-        .optional()
-        .describe("Ownership proof that completes the two-publish issuer activation."),
+    keys: systemTokenIssuerKeysSchema,
+    proofs: systemTokenIssuerProofsSchema.optional(),
 })
     .strict();
 export const systemSubscriptionSchema = z
@@ -891,6 +913,13 @@ export const systemSubscriptionSchema = z
         .describe("Event names delivered to this subscription."),
 })
     .strict();
+/**
+ * Metering is the host's, not the format's: what a plan is, what it costs and
+ * which quotas it carries is Spacefast's commerce model. The manifest's plan
+ * catalog is therefore declared in `./space-config-spacefast.js`, which extends
+ * this object — parse an sf.jsonc that may declare plans through
+ * `spacefastSpaceConfigFileSchema` there, never through the schema below.
+ */
 export const spaceSystemManifestSchema = z
     .object({
     presentation: systemPresentationSchema.optional(),
@@ -900,35 +929,14 @@ export const spaceSystemManifestSchema = z
         .array(systemTokenIssuerSchema)
         .max(SPACE_CONFIG_CAPS.systemTokenIssuers)
         .optional()
-        .describe("Trusted token issuers registered for the tenant."),
+        .describe("One trusted token issuer for the tenant. Omit this field or declare an empty array to revoke it."),
     subscriptions: z
         .array(systemSubscriptionSchema)
         .max(SPACE_CONFIG_CAPS.systemSubscriptions)
         .optional()
         .describe("Event subscriptions (webhooks) the tenant declares."),
-    plans: planCatalogSchema
-        .optional()
-        .describe("Per-tenant plan catalog: plan name → { features, quotas.spaces, quotaPolicy }. Feature keys validated against the live vocabulary; plan names are arbitrary."),
-    defaultPlan: defaultPlanNameSchema
-        .optional()
-        .describe("Plan unassigned principals fall back to. Must be a key in `plans`."),
 })
     .strict()
-    .superRefine((manifest, ctx) => {
-    if (manifest.defaultPlan === undefined) {
-        return;
-    }
-    // A defaultPlan is only meaningful against a declared catalog: it must name a
-    // plan the same manifest declares, or gate resolution would fall back to a
-    // plan that does not exist.
-    if (manifest.plans === undefined || !(manifest.defaultPlan in manifest.plans)) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ["defaultPlan"],
-            message: "defaultPlan must be one of the plan names declared in `plans`.",
-        });
-    }
-})
     .describe("Control-plane manifest for a tenant's designated system space. Parsed and reconciled by the control plane; ignored by other spaces.");
 export const spaceConfigFileSchema = spaceConfigBaseSchema.extend({
     $schema: z
@@ -956,29 +964,6 @@ export const spaceConfigFileSchema = spaceConfigBaseSchema.extend({
         .optional()
         .describe("Control-plane system-space manifest. Honored only for a tenant's designated system space; other spaces' declarations are ignored."),
 });
-/**
- * The published JSON Schema artifact for `sf.jsonc`, generated from the
- * zod file schema. Served at SPACE_CONFIG_SCHEMA_URL so editors and agents get
- * autocomplete and validation.
- */
-export function spaceConfigJsonSchema() {
-    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, not by the serving shape above, so they are described
-    // here. Without them an editor reads the documented routing examples as
-    // unknown keys.
-    return {
-        ...schema,
-        properties: {
-            ...schema.properties,
-            ...SPACE_CONFIG_ROUTING_SCHEMA_PROPERTIES,
-        },
-    };
-}
 // The `!` and `name=:capture` of a `_redirects` line, shared by both rule
 // sections and by `config::strict::public_json_schema`.
 const SPACE_CONFIG_ROUTING_FORCE_SCHEMA = {
@@ -989,10 +974,16 @@ const SPACE_CONFIG_ROUTING_FORCE_SCHEMA = {
 const SPACE_CONFIG_ROUTING_QUERY_SCHEMA = {
     type: "object",
     description: 'Query parameters the request must carry, as parameter name to capture name: { "id": "id" } is the name=:capture token id=:id.',
-    propertyNames: { pattern: "^[A-Za-z][A-Za-z0-9_-]*$" },
+    propertyNames: { pattern: "^[A-Za-z_][A-Za-z0-9_-]*$" },
     additionalProperties: { type: "string", pattern: "^[A-Za-z][A-Za-z0-9_]*$" },
 };
-const SPACE_CONFIG_ROUTING_SCHEMA_PROPERTIES = {
+/**
+ * Routing keys as JSON Schema. `redirects`, `rewrites` and `headers` are real
+ * sf.jsonc keys owned by the routing compiler rather than by the serving shape
+ * above, so a generated schema has to describe them separately or an editor
+ * reads the documented routing examples as unknown keys.
+ */
+export const SPACE_CONFIG_ROUTING_SCHEMA_PROPERTIES = {
     redirects: {
         type: "array",
         description: "Browser redirect rules. Same matcher grammar as _redirects, and _redirects rules match first.",
@@ -1096,15 +1087,14 @@ const SPACE_CONFIG_ROUTING_SCHEMA_PROPERTIES = {
     },
 };
 /*
- * `experimental_gutenberg` and its `inject` companion are ACCEPTED by the parser
- * but never published: the bare key names alone would document the feature to
- * every editor and agent reading a schema artifact. Every generator that derives
- * a public artifact from the SpaceConfig zod shape (the sf.jsonc JSON Schema,
- * the www publish-spec, the SDK OpenAPI documents) must run it through this
- * stripper. The published schemas set no additionalProperties constraint, so
- * configs using the hidden keys still validate. `inject` is removed only when it
- * carries the SpaceConfig static-placement shape, so unrelated properties of the
- * same name survive.
+ * `inject` is ACCEPTED by the parser but never published: the bare key name
+ * alone would document the feature to every editor and agent reading a schema
+ * artifact. Every generator that derives a public artifact from the SpaceConfig
+ * zod shape (the sf.jsonc JSON Schema, the www publish-spec, the SDK OpenAPI
+ * documents) must run it through this stripper. The published schemas set no
+ * additionalProperties constraint, so configs using the hidden key still
+ * validate. `inject` is removed only when it carries the SpaceConfig
+ * static-placement shape, so unrelated properties of the same name survive.
  */
 export function stripHiddenSpaceConfigKeys(schema) {
     if (Array.isArray(schema)) {
@@ -1115,12 +1105,7 @@ export function stripHiddenSpaceConfigKeys(schema) {
     }
     return Object.fromEntries(Object.entries(schema).map(([key, entry]) => {
         if (key === "properties" && entry && typeof entry === "object" && !Array.isArray(entry)) {
-            const kept = Object.fromEntries(Object.entries(entry).filter(([name, value]) => {
-                if (name === "experimental_gutenberg") {
-                    return false;
-                }
-                return !(name === "inject" && isHiddenInjectSchema(value));
-            }));
+            const kept = Object.fromEntries(Object.entries(entry).filter(([name, value]) => !(name === "inject" && isHiddenInjectSchema(value))));
             return [key, stripHiddenSpaceConfigKeys(kept)];
         }
         return [key, stripHiddenSpaceConfigKeys(entry)];