@caelo-cms/shared 0.10.48 → 0.10.50

package/src/platform-updates.ts

@@ -163,7 +163,15 @@ export const updatePolicySchema = z
     windowStart: z.string().regex(WALL_CLOCK, "expected HH:MM").nullable(),
     windowEnd: z.string().regex(WALL_CLOCK, "expected HH:MM").nullable(),
     windowTimezone: z.string().min(1).max(64).refine(isKnownTimeZone, "unknown time zone"),
+    /** Hours after publication before a non-security release installs automatically. */
     soakHours: z.number().int().min(0).max(720),
+    /**
+     * The same for a release whose signed manifest names a published GitHub
+     * Security Advisory (auto-update.ts `isSecurityRelease`). Shorter by
+     * default (2 h vs 24 h): the fix is public, so every hour unpatched is
+     * exposure, while two hours still let a broken release be pulled first.
+     */
+    securitySoakHours: z.number().int().min(0).max(720),
   })
   .strict()
   .refine((p) => (p.windowStart === null) === (p.windowEnd === null), {
@@ -171,6 +179,9 @@ export const updatePolicySchema = z
   })
   .refine((p) => p.mode !== "auto" || p.channel === "stable", {
     message: "automatic installs follow the stable channel only",
+  })
+  .refine((p) => p.securitySoakHours <= p.soakHours, {
+    message: "security fixes cannot wait longer than other releases",
   });
 export type UpdatePolicy = z.infer<typeof updatePolicySchema>;
 
@@ -179,6 +190,10 @@ export interface StoredUpdatePolicy extends UpdatePolicy {
   readonly paused: boolean;
   readonly pausedReason: string | null;
   readonly pausedAt: string | null;
+  /** End of the Owner's pause; null = until resumed (or not paused). */
+  readonly pausedUntil: string | null;
+  /** True when the Owner paused; false when the upgrader paused after a failure. */
+  readonly pausedByOwner: boolean;
   readonly updatedAt: string;
 }
 
@@ -238,6 +253,7 @@ export function autoInstallRefusal(
     | "autoPatch"
     | "autoMinor"
     | "paused"
+    | "pausedUntil"
     | "windowStart"
     | "windowEnd"
     | "windowTimezone"
@@ -246,7 +262,14 @@ export function autoInstallRefusal(
   at: Date,
 ): string | null {
   if (policy.mode !== "auto") return "automatic installs are switched off in the update policy";
-  if (policy.paused) return "automatic installs are paused after a failed install";
+  // An Owner pause with an end that has passed no longer holds (the
+  // scheduler lifts it on its next tick; this keeps the job consistent).
+  if (
+    policy.paused &&
+    (policy.pausedUntil === null || Date.parse(policy.pausedUntil) > at.getTime())
+  ) {
+    return "automatic installs are paused";
+  }
   if (candidate.channel !== "stable") return "only stable releases install automatically";
   if (candidate.contractMigrations) {
     return "the release carries destructive database changes; the Owner installs it by hand";
@@ -264,14 +287,15 @@ export function autoInstallRefusal(
 }
 
 /**
- * How long a verified Google sign-in authorizes one guarded action. Long
- * enough to read the confirmation dialog, short enough that an unattended
- * browser is useless soon after.
+ * How long a password confirmation authorizes one guarded action (#757). The
+ * admin confirms and acts in the same request, so the window only has to
+ * cover that request; anything longer would let an unattended browser reuse
+ * a confirmation the Owner made for an action that then failed.
  */
-export const STEP_UP_MAX_AGE_SECONDS = 600;
+export const STEP_UP_MAX_AGE_SECONDS = 60;
 
-/** What a step-up is for (`step_up_challenges.purpose`). */
-export const STEP_UP_PURPOSES = ["platform_update", "update_policy", "step_up_client"] as const;
+/** What a step-up is for (`sessions.step_up_purpose`). */
+export const STEP_UP_PURPOSES = ["platform_update", "update_policy"] as const;
 export type StepUpPurpose = (typeof STEP_UP_PURPOSES)[number];
 
 /**

package/src/redirect-emit-caddy.ts

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The redirect plan as a Caddyfile snippet (self-hosted, #587).
+ *
+ * The static generator writes it to `<build>/_redirects.caddy`; each public
+ * Caddy site block imports the file of the build it serves, and the Caddy
+ * container reloads itself when a deploy changes it (caddy-redirects.ts in
+ * @caelo-cms/provisioning). A redirect is answered by Caddy itself with no
+ * compute on the request path and no channel from the admin into Caddy. A
+ * snippet Caddy rejects leaves the previous config running.
+ *
+ * Shape: one `map` from the request path to the target and status, then one
+ * `redir` per status keyed on the mapped status. `map` is an exact,
+ * case-sensitive string lookup — unlike Caddy's `path` matcher, which is
+ * case-insensitive and would let `/About` shadow a live `/about`. One map
+ * keeps the config O(1) in directives however many rows the table holds.
+ * `redir` sorts before `try_files` / `file_server` / `handle`, so the
+ * directive order inside the site block does not matter.
+ */
+
+import type { RedirectPlan } from "./redirect-plan.js";
+import { trimTrailingSlashes } from "./url.js";
+
+/** The file name the generator writes the snippet to, at the build root. */
+export const CADDY_REDIRECTS_FILE = "_redirects.caddy";
+
+/**
+ * The `import` line for a site block serving `siteRoot`. The trailing `*`
+ * (Caddy's import globs allow exactly one) lets a site root without a build
+ * yet — fresh install, nothing published — import nothing instead of failing
+ * Caddy's start; Caddy only errors on a missing import without a wildcard.
+ * Every build the generator writes carries the file.
+ */
+export function caddyRedirectsImport(siteRoot: string): string {
+  return `import ${trimTrailingSlashes(siteRoot)}/${CADDY_REDIRECTS_FILE}*`;
+}
+
+const PLACEHOLDER_TARGET = "caelo_redirect_to";
+const PLACEHOLDER_STATUS = "caelo_redirect_status";
+
+/**
+ * Characters a Caddyfile token cannot carry literally: `{`/`}` start a
+ * placeholder, quotes and backticks delimit tokens. Stored paths are
+ * percent-encoded URLs, so these never occur in practice; a row that has
+ * them fails the build rather than becoming a different rule.
+ */
+const CADDY_UNSAFE = /[{}"`\\]/;
+
+/**
+ * Render the plan as a Caddyfile snippet for a site block.
+ *
+ * @example
+ *   emitCaddyRedirects({ redirects: [{ fromPath: "/old", matchPaths: ["/old", "/old/"],
+ *     location: "/new/", statusCode: 301, preserveQuery: true }], gone: [], shadowedByBuild: [] })
+ *   // map {path} {caelo_redirect_to} {caelo_redirect_status} {
+ *   //   /old /new/{?query} 301
+ *   //   /old/ /new/{?query} 301
+ *   // }
+ *   // @caelo_redirect_301 vars {caelo_redirect_status} 301
+ *   // redir @caelo_redirect_301 {caelo_redirect_to} 301
+ */
+export function emitCaddyRedirects(plan: RedirectPlan): string {
+  const lines = [
+    "# Auto-generated by Caelo static-generator from the redirects table. Do not edit.",
+  ];
+  if (plan.redirects.length === 0 && plan.gone.length === 0) return `${lines[0]}\n`;
+
+  lines.push(`map {path} {${PLACEHOLDER_TARGET}} {${PLACEHOLDER_STATUS}} {`);
+  for (const r of plan.redirects) {
+    assertCaddySafe(r.fromPath, r.location);
+    const target = r.preserveQuery ? `${r.location}{?query}` : r.location;
+    for (const path of r.matchPaths) lines.push(`\t${path} ${target} ${r.statusCode}`);
+  }
+  for (const g of plan.gone) {
+    assertCaddySafe(g.fromPath, "");
+    for (const path of g.matchPaths) lines.push(`\t${path} - 410`);
+  }
+  lines.push("}");
+
+  const statuses = [...new Set(plan.redirects.map((r) => r.statusCode))].sort();
+  for (const status of statuses) {
+    lines.push(`@caelo_redirect_${status} vars {${PLACEHOLDER_STATUS}} ${status}`);
+    lines.push(`redir @caelo_redirect_${status} {${PLACEHOLDER_TARGET}} ${status}`);
+  }
+  if (plan.gone.length > 0) {
+    // `handle` (not a bare `respond`): `respond` sorts after `handle`, so a
+    // catch-all `handle { file_server }` in the site block would win.
+    lines.push(`@caelo_gone vars {${PLACEHOLDER_STATUS}} 410`);
+    lines.push("handle @caelo_gone {", "\trespond 410", "}");
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function assertCaddySafe(fromPath: string, location: string): void {
+  for (const value of [fromPath, location]) {
+    if (CADDY_UNSAFE.test(value)) {
+      throw new Error(
+        `redirect-emit-caddy: the redirect for ${JSON.stringify(fromPath)} contains one of { } " \` \\ in ${JSON.stringify(value)}, which a Caddyfile cannot carry literally. Percent-encode the character in the stored path (e.g. '{' is '%7B') with bulk_create_redirects (upsert), then rebuild.`,
+      );
+    }
+  }
+}

package/src/redirect-emit-cloudfront.ts

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The redirect plan for CloudFront (provider `aws`, #587).
+ *
+ * CloudFront has no static redirect rules; the edge-native way is a
+ * CloudFront Function on viewer-request reading a CloudFront KeyValueStore.
+ * The function is a sub-millisecond lookup that runs at the edge before the
+ * S3 origin (no Lambda, no origin round-trip), and the store is updated by
+ * the deploy without republishing the function. S3 website routing rules are
+ * not an option: they are capped at 50 and need the website endpoint, while
+ * the stack serves S3 through an origin access identity.
+ *
+ * One key per request path the plan answers (`/old`, `/old/`), value a small
+ * JSON document. Store limits (CloudFront quotas, fixed): 5 MB per store,
+ * keys up to 512 bytes, values up to 1 KB. A plan that does not fit is
+ * refused with {@link CloudFrontKvsLimitError}; nothing is written.
+ */
+
+import type { RedirectPlan } from "./redirect-plan.js";
+
+/** CloudFront KeyValueStore limits. */
+export const CLOUDFRONT_KVS_MAX_TOTAL_BYTES = 5 * 1024 * 1024;
+export const CLOUDFRONT_KVS_MAX_KEY_BYTES = 512;
+export const CLOUDFRONT_KVS_MAX_VALUE_BYTES = 1024;
+
+/** One KeyValueStore entry. */
+export interface CloudFrontKvsEntry {
+  readonly key: string;
+  readonly value: string;
+}
+
+/**
+ * The value stored per path: `s` status, `l` Location, `q` 1 when the
+ * visitor's query string is appended. A 410 entry carries only `s`.
+ */
+export interface CloudFrontRedirectValue {
+  readonly s: number;
+  readonly l?: string;
+  readonly q?: 1;
+}
+
+/** The plan does not fit a CloudFront KeyValueStore; nothing was written. */
+export class CloudFrontKvsLimitError extends Error {
+  constructor(detail: string) {
+    super(
+      `redirect-emit-cloudfront: ${detail} Nothing was published and the live redirects are unchanged. Delete redirects nobody links to any more (find_redirects lists them, bulk_delete_redirects removes them), then publish again.`,
+    );
+    this.name = "CloudFrontKvsLimitError";
+  }
+}
+
+const utf8Length = (s: string): number => new TextEncoder().encode(s).length;
+
+/**
+ * The KeyValueStore entries for a plan, sorted by key.
+ *
+ * @throws {CloudFrontKvsLimitError} when a key, a value or the whole set is
+ *         over the store's limits.
+ */
+export function cloudFrontKeyValueEntries(plan: RedirectPlan): CloudFrontKvsEntry[] {
+  const entries: CloudFrontKvsEntry[] = [];
+  for (const r of plan.redirects) {
+    const value: CloudFrontRedirectValue = {
+      s: r.statusCode,
+      l: r.location,
+      ...(r.preserveQuery ? { q: 1 as const } : {}),
+    };
+    for (const key of r.matchPaths) entries.push({ key, value: JSON.stringify(value) });
+  }
+  for (const g of plan.gone) {
+    for (const key of g.matchPaths) entries.push({ key, value: JSON.stringify({ s: 410 }) });
+  }
+  entries.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+
+  let total = 0;
+  for (const e of entries) {
+    if (utf8Length(e.key) > CLOUDFRONT_KVS_MAX_KEY_BYTES) {
+      throw new CloudFrontKvsLimitError(
+        `the redirect path ${JSON.stringify(e.key)} is longer than the ${CLOUDFRONT_KVS_MAX_KEY_BYTES}-byte key limit.`,
+      );
+    }
+    if (utf8Length(e.value) > CLOUDFRONT_KVS_MAX_VALUE_BYTES) {
+      throw new CloudFrontKvsLimitError(
+        `the redirect target for ${JSON.stringify(e.key)} is longer than the ${CLOUDFRONT_KVS_MAX_VALUE_BYTES}-byte value limit.`,
+      );
+    }
+    total += utf8Length(e.key) + utf8Length(e.value);
+  }
+  if (total > CLOUDFRONT_KVS_MAX_TOTAL_BYTES) {
+    throw new CloudFrontKvsLimitError(
+      `the ${entries.length} redirect path(s) need ${total} bytes; a store holds ${CLOUDFRONT_KVS_MAX_TOTAL_BYTES}.`,
+    );
+  }
+  return entries;
+}
+
+/**
+ * Source of the viewer-request CloudFront Function (runtime
+ * `cloudfront-js-2.0`) that answers the store's entries. A path without an
+ * entry passes through to the origin unchanged.
+ *
+ * @param kvsId The KeyValueStore's id (the last segment of its ARN).
+ */
+export function cloudFrontRedirectFunctionCode(kvsId: string): string {
+  if (!/^[A-Za-z0-9-]+$/.test(kvsId)) {
+    throw new Error(`redirect-emit-cloudfront: ${JSON.stringify(kvsId)} is not a KeyValueStore id`);
+  }
+  return `import cf from 'cloudfront';
+
+// Generated by @caelo-cms/shared (redirect-emit-cloudfront.ts). Answers the
+// redirects table from the KeyValueStore the deploy writes (#587).
+const kvs = cf.kvs('${kvsId}');
+const REASON = {
+  301: 'Moved Permanently',
+  302: 'Found',
+  307: 'Temporary Redirect',
+  308: 'Permanent Redirect',
+};
+
+async function handler(event) {
+  const request = event.request;
+  let hit;
+  try {
+    hit = await kvs.get(request.uri, { format: 'json' });
+  } catch (e) {
+    // kvs.get throws for a key that is not in the store: no redirect.
+    return request;
+  }
+  if (hit.s === 410) {
+    return { statusCode: 410, statusDescription: 'Gone' };
+  }
+  let location = hit.l;
+  if (hit.q === 1) {
+    const query = request.rawQueryString();
+    if (query) location += '?' + query;
+  }
+  return {
+    statusCode: hit.s,
+    statusDescription: REASON[hit.s],
+    headers: { location: { value: location } },
+  };
+}
+`;
+}

package/src/redirect-emit-front-door.ts

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The redirect plan as Azure Front Door (Standard) rules-engine rules
+ * (provider `azure`, #587).
+ *
+ * Front Door's rules engine answers a `UrlRedirect` action at the edge,
+ * before the Blob static-website origin, so no compute sits on the request
+ * path. Each planned redirect is one rule: a `UrlPath` condition (Front Door
+ * matches the path WITHOUT its leading slash) and a `UrlRedirect` action.
+ *
+ * Limit (Front Door Standard and Premium, fixed): 100 rules per rule set and
+ * per route. A plan with more redirects is refused with
+ * {@link FrontDoorRuleLimitError} before anything is written — never a
+ * partial set. Front Door cannot answer a bare 410, so `gone` entries get
+ * the origin's 404. Writing the rules at deploy time is tracked in #750.
+ */
+
+import type { PlannedRedirect, RedirectPlan, RedirectStatusCode } from "./redirect-plan.js";
+
+/** Rules per rule set / per route on Front Door Standard and Premium. */
+export const FRONT_DOOR_MAX_RULES = 100;
+
+type FrontDoorRedirectType = "Moved" | "Found" | "TemporaryRedirect" | "PermanentRedirect";
+
+const REDIRECT_TYPE: Record<RedirectStatusCode, FrontDoorRedirectType> = {
+  301: "Moved",
+  302: "Found",
+  307: "TemporaryRedirect",
+  308: "PermanentRedirect",
+};
+
+/** One rule, in the shape of `azure-native` `cdn.Rule` arguments (ARM). */
+export interface FrontDoorRedirectRule {
+  readonly ruleName: string;
+  readonly order: number;
+  readonly matchProcessingBehavior: "Stop";
+  readonly conditions: readonly [
+    {
+      readonly name: "UrlPath";
+      readonly parameters: {
+        readonly typeName: "DeliveryRuleUrlPathMatchConditionParameters";
+        readonly operator: "Equal";
+        readonly negateCondition: false;
+        readonly matchValues: readonly string[];
+        readonly transforms: readonly [];
+      };
+    },
+  ];
+  readonly actions: readonly [
+    {
+      readonly name: "UrlRedirect";
+      readonly parameters: {
+        readonly typeName: "DeliveryRuleUrlRedirectActionParameters";
+        readonly redirectType: FrontDoorRedirectType;
+        readonly destinationProtocol: "MatchRequest";
+        readonly customPath: string;
+        readonly customQueryString?: string;
+        readonly customFragment?: string;
+      };
+    },
+  ];
+}
+
+/** The plan has more redirects than a Front Door route can hold. */
+export class FrontDoorRuleLimitError extends Error {
+  constructor(readonly redirectCount: number) {
+    super(
+      `Azure Front Door serves at most ${FRONT_DOOR_MAX_RULES} redirect rules per site (a fixed rules-engine limit); this site has ${redirectCount}. Nothing was published and the live redirects are unchanged. Delete redirects nobody links to any more (find_redirects lists them, bulk_delete_redirects removes them), then publish again. Larger sets on Azure are tracked in https://github.com/caelo-cms/caelo-cms/issues/750.`,
+    );
+    this.name = "FrontDoorRuleLimitError";
+  }
+}
+
+/**
+ * One rule per planned redirect, ordered as the plan.
+ *
+ * @throws {FrontDoorRuleLimitError} over {@link FRONT_DOOR_MAX_RULES}.
+ */
+export function frontDoorRedirectRules(plan: RedirectPlan): FrontDoorRedirectRule[] {
+  if (plan.redirects.length > FRONT_DOOR_MAX_RULES) {
+    throw new FrontDoorRuleLimitError(plan.redirects.length);
+  }
+  return plan.redirects.map((r, i) => toRule(r, i + 1));
+}
+
+function toRule(r: PlannedRedirect, order: number): FrontDoorRedirectRule {
+  const { path, query, fragment } = splitLocation(r.location);
+  return {
+    // Rule names: letters and digits only, starting with a letter.
+    ruleName: `caeloRedirect${order}`,
+    order,
+    matchProcessingBehavior: "Stop",
+    conditions: [
+      {
+        name: "UrlPath",
+        parameters: {
+          typeName: "DeliveryRuleUrlPathMatchConditionParameters",
+          operator: "Equal",
+          negateCondition: false,
+          matchValues: r.matchPaths.map((p) => p.slice(1)),
+          transforms: [],
+        },
+      },
+    ],
+    actions: [
+      {
+        name: "UrlRedirect",
+        parameters: {
+          typeName: "DeliveryRuleUrlRedirectActionParameters",
+          redirectType: REDIRECT_TYPE[r.statusCode],
+          destinationProtocol: "MatchRequest",
+          customPath: path,
+          // Without customQueryString Front Door keeps the visitor's query,
+          // which is the plan's preserveQuery semantics.
+          ...(query !== null ? { customQueryString: query } : {}),
+          ...(fragment !== null ? { customFragment: fragment } : {}),
+        },
+      },
+    ],
+  };
+}
+
+function splitLocation(location: string): {
+  path: string;
+  query: string | null;
+  fragment: string | null;
+} {
+  const hashAt = location.indexOf("#");
+  const beforeHash = hashAt === -1 ? location : location.slice(0, hashAt);
+  const fragment = hashAt === -1 ? null : location.slice(hashAt + 1);
+  const queryAt = beforeHash.indexOf("?");
+  return {
+    path: queryAt === -1 ? beforeHash : beforeHash.slice(0, queryAt),
+    // A target with only a fragment still replaces the visitor's query, as
+    // on every other provider (preserveQuery is false for it).
+    query: queryAt === -1 ? (fragment === null ? null : "") : beforeHash.slice(queryAt + 1),
+    fragment,
+  };
+}

package/src/redirect-emit-gcp.ts

@@ -0,0 +1,165 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The redirect plan as GCP URL-map path rules (provider `gcp`: GCS backend
+ * bucket behind the global external Application Load Balancer, #587).
+ *
+ * Why URL-map rules: the load balancer answers a `urlRedirect` path rule
+ * itself, at the edge, before the backend bucket is asked — no compute on
+ * the static request path (CLAUDE.md §11.B Tier 1). The alternatives do not
+ * exist on this stack: GCS has no per-object redirects, and the URL map's
+ * custom error responses can only point at a backend bucket, so a bucket
+ * 404 cannot be handed to the gateway for a `redirects.lookup`.
+ *
+ * Limits (https://cloud.google.com/load-balancing/docs/quotas, "URL maps",
+ * fixed — they cannot be raised): per path matcher at most 1,000 path
+ * rules and 1,000 predicates, where every path of a path rule is one
+ * predicate. Every host has exactly one path matcher, so the site host's
+ * redirects share that budget with its own routing rules (`/api/*`). A plan
+ * that does not fit is refused with {@link GcpUrlMapBudgetError} BEFORE
+ * anything changes — the load balancer keeps the previous rules, and the
+ * error names the counts and the ways out. Dropping redirects silently
+ * would turn linked URLs into 404s without anyone noticing. Going past the
+ * quota is tracked in #751.
+ *
+ * Rules this module owns are recognised by their `urlRedirect` (the stack's
+ * own rules route to a service), so re-applying a plan replaces exactly the
+ * previous plan's rules and keeps everything else in the path matcher.
+ */
+
+import type { PlannedRedirect, RedirectPlan, RedirectStatusCode } from "./redirect-plan.js";
+
+/** Path rules per path matcher (URL map quota, global external ALB). */
+export const GCP_URL_MAP_MAX_PATH_RULES = 1000;
+/** Predicates (paths across all path rules) per path matcher. */
+export const GCP_URL_MAP_MAX_PREDICATES = 1000;
+
+/** `urlRedirect.redirectResponseCode` per stored status. */
+const RESPONSE_CODE: Record<RedirectStatusCode, GcpRedirectResponseCode> = {
+  301: "MOVED_PERMANENTLY_DEFAULT",
+  302: "FOUND",
+  307: "TEMPORARY_REDIRECT",
+  308: "PERMANENT_REDIRECT",
+};
+
+export type GcpRedirectResponseCode =
+  | "MOVED_PERMANENTLY_DEFAULT"
+  | "FOUND"
+  | "SEE_OTHER"
+  | "TEMPORARY_REDIRECT"
+  | "PERMANENT_REDIRECT";
+
+/** A path rule of a URL map path matcher (Compute REST shape). */
+export interface GcpPathRule {
+  readonly paths: readonly string[];
+  readonly service?: string;
+  readonly urlRedirect?: {
+    readonly pathRedirect?: string;
+    readonly redirectResponseCode?: GcpRedirectResponseCode;
+    readonly stripQuery?: boolean;
+    readonly [key: string]: unknown;
+  };
+  readonly [key: string]: unknown;
+}
+
+/** A URL map path matcher (Compute REST shape; other fields kept as-is). */
+export interface GcpPathMatcher {
+  readonly name: string;
+  readonly pathRules?: readonly GcpPathRule[];
+  readonly routeRules?: readonly unknown[];
+  readonly [key: string]: unknown;
+}
+
+/** The plan does not fit the path matcher's quota; nothing was changed. */
+export class GcpUrlMapBudgetError extends Error {
+  constructor(
+    readonly redirectCount: number,
+    readonly predicatesNeeded: number,
+    readonly rulesNeeded: number,
+  ) {
+    super(
+      `The GCP load balancer serves at most ${GCP_URL_MAP_MAX_PREDICATES} redirect paths and ${GCP_URL_MAP_MAX_PATH_RULES} rules per site (a fixed URL-map quota); this site's ${redirectCount} redirect(s) need ${predicatesNeeded} paths and ${rulesNeeded} rules, counting the site's own routing. Nothing was published and the live redirects are unchanged. Next step: delete redirects nobody links to any more (find_redirects lists them, bulk_delete_redirects removes them) — every redirect whose old URL ends in '/' or not costs two paths, a file-like one ('/old.html') costs one — then publish again. Serving larger redirect sets on this provider is tracked in https://github.com/caelo-cms/caelo-cms/issues/751.`,
+    );
+    this.name = "GcpUrlMapBudgetError";
+  }
+}
+
+/**
+ * One `urlRedirect` path rule per planned redirect. 410 entries have no
+ * URL-map equivalent and answer the bucket's 404.
+ *
+ * @throws when a planned redirect cannot be expressed as a URL-map rule
+ *         (a `*` in the from path would turn it into a wildcard; a target
+ *         with a query or fragment cannot be a `pathRedirect`).
+ */
+export function gcpRedirectPathRules(plan: RedirectPlan): GcpPathRule[] {
+  return plan.redirects.map(toPathRule);
+}
+
+function toPathRule(r: PlannedRedirect): GcpPathRule {
+  if (r.matchPaths.some((p) => p.includes("*"))) {
+    throw new Error(
+      `redirect-emit-gcp: the redirect for ${JSON.stringify(r.fromPath)} contains '*', which a GCP URL map reads as a wildcard. Percent-encode it ('%2A') with bulk_create_redirects (upsert), then publish again.`,
+    );
+  }
+  if (!r.preserveQuery) {
+    throw new Error(
+      `redirect-emit-gcp: the redirect ${r.fromPath} → ${r.location} targets a URL with a query string or fragment, which a GCP URL-map redirect cannot carry. Point it at the page's path with bulk_create_redirects (upsert), then publish again.`,
+    );
+  }
+  return {
+    paths: [...r.matchPaths],
+    urlRedirect: {
+      pathRedirect: r.location,
+      redirectResponseCode: RESPONSE_CODE[r.statusCode],
+      // The visitor's query string rides along, like on every provider.
+      stripQuery: false,
+    },
+  };
+}
+
+/** Whether a path rule is one a redirect plan wrote (see module comment). */
+export function isGcpRedirectRule(rule: GcpPathRule): boolean {
+  return rule.urlRedirect !== undefined && rule.service === undefined;
+}
+
+/**
+ * The path matcher with its redirect rules replaced by the plan's. Rules
+ * that are not redirects stay first, in their order — `/api/*` keeps
+ * routing to the gateway. Path rules match the longest path, so the order
+ * between them does not change routing.
+ *
+ * @throws {GcpUrlMapBudgetError} when the result exceeds the quota.
+ */
+export function withGcpRedirects(matcher: GcpPathMatcher, plan: RedirectPlan): GcpPathMatcher {
+  if (matcher.routeRules && matcher.routeRules.length > 0) {
+    throw new Error(
+      `redirect-emit-gcp: path matcher ${JSON.stringify(matcher.name)} uses routeRules; a path matcher holds either pathRules or routeRules, and Caelo's stack writes pathRules. The URL map was changed outside the stack — restore it with the installer, then publish again.`,
+    );
+  }
+  const kept = (matcher.pathRules ?? []).filter((r) => !isGcpRedirectRule(r));
+  const redirects = gcpRedirectPathRules(plan);
+  const pathRules = [...kept, ...redirects];
+  const predicates = pathRules.reduce((n, r) => n + r.paths.length, 0);
+  if (predicates > GCP_URL_MAP_MAX_PREDICATES || pathRules.length > GCP_URL_MAP_MAX_PATH_RULES) {
+    throw new GcpUrlMapBudgetError(redirects.length, predicates, pathRules.length);
+  }
+  return { ...matcher, pathRules };
+}
+
+/**
+ * Check a plan against the budget a path matcher with `baseRules` leaves,
+ * without a URL map at hand (Stage runs it so an over-quota redirect set
+ * is reported before Confirm-publish).
+ *
+ * @throws {GcpUrlMapBudgetError} when the plan does not fit.
+ */
+export function assertGcpRedirectBudget(
+  plan: RedirectPlan,
+  baseRules: readonly GcpPathRule[],
+): void {
+  withGcpRedirects({ name: "budget-check", pathRules: baseRules }, plan);
+}
+
+/** The site's own routing in the `public` path matcher (stack + budget). */
+export const GCP_PUBLIC_BASE_PATHS: readonly string[] = ["/api/*"];