@caelo-cms/shared 0.10.37 → 0.10.39

package/dist/staging-gate.js

@@ -0,0 +1,337 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * Issue #650 — the access gate in front of `staging.<domain>`.
+ *
+ * One pure module shared by the two sides of the gate:
+ *
+ *  - the admin, which issues "Open staging" tokens and shows the Owner the
+ *    crawler credentials (basic auth, secret header) it derives here;
+ *  - the gateway (gcp-firebase), which verifies every staging request
+ *    against the same rules before it proxies to the staged build.
+ *
+ * Every secret is derived from ONE shared key, the `staging-gate-secret`
+ * in Secret Manager (`CAELO_STAGING_GATE_SECRET` on admin + gateway):
+ *
+ *  - Crawler credentials are `HMAC(key, kind + nonce)`. The database keeps
+ *    only the random nonce, so a database read alone reveals no credential,
+ *    and rotating a credential is writing a new nonce — no redeploy, no
+ *    Secret Manager write from the admin at runtime.
+ *  - "Open staging" tokens and the session cookie they turn into are
+ *    `purpose.expiry.HMAC(key, purpose + expiry)`: stateless, short-lived,
+ *    and useless for any other purpose.
+ *
+ * Every comparison of a presented secret is constant-time. WebCrypto only,
+ * so the module runs unchanged in Bun, Node and the admin's SvelteKit build.
+ */
+/** Cookie the gateway sets on `staging.<domain>` after "Open staging". */
+export const STAGING_SESSION_COOKIE = "caelo_staging_access";
+/** Path on the staging host that turns an "Open staging" token into the session cookie. */
+export const STAGING_ACCESS_PATH = "/_caelo/staging-access";
+/** How long an "Open staging" link stays usable. Short: it travels in a URL. */
+export const STAGING_OPEN_TOKEN_TTL_SECONDS = 120;
+/** How long the staging session cookie keeps an operator's browser in. */
+export const STAGING_SESSION_TTL_SECONDS = 12 * 60 * 60;
+/** Default name of the secret request header crawlers can send. */
+export const DEFAULT_STAGING_HEADER_NAME = "X-Caelo-Staging-Key";
+const ENCODER = new TextEncoder();
+async function hmacBytes(secret, message) {
+    const key = await crypto.subtle.importKey("raw", ENCODER.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return new Uint8Array(await crypto.subtle.sign("HMAC", key, ENCODER.encode(message)));
+}
+function base64Url(bytes) {
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/**
+ * Constant-time string comparison. Inputs of different length compare
+ * unequal without an early exit on the first differing byte; the length
+ * itself is not secret (every derived credential has a fixed length).
+ */
+export function constantTimeEqual(a, b) {
+    const x = ENCODER.encode(a);
+    const y = ENCODER.encode(b);
+    const other = x.length === y.length ? y : x;
+    let diff = x.length === y.length ? 0 : 1;
+    for (let i = 0; i < x.length; i++)
+        diff |= (x[i] ?? 0) ^ (other[i] ?? 0);
+    return diff === 0;
+}
+/** A fresh random nonce for a credential rotation (24 random bytes, base64url). */
+export function newStagingCredentialNonce() {
+    const bytes = new Uint8Array(24);
+    crypto.getRandomValues(bytes);
+    return base64Url(bytes);
+}
+/**
+ * The crawler credential (basic-auth password or secret header value) for
+ * `nonce`. 32 URL-safe characters (192 bits).
+ *
+ * @example
+ *   await deriveStagingCredential(gateSecret, "basic-auth", settings.basicAuthNonce)
+ */
+export async function deriveStagingCredential(secret, kind, nonce) {
+    const mac = await hmacBytes(secret, `caelo-staging-credential:${kind}:${nonce}`);
+    return base64Url(mac.slice(0, 24));
+}
+/**
+ * A signed, expiring token: `<purpose>.<expiresAtSeconds>.<mac>`. `open` is
+ * the one-time-ish link the admin hands the browser; `session` is the cookie
+ * the gateway sets in exchange.
+ */
+export async function signStagingToken(secret, purpose, expiresAtSeconds) {
+    const exp = Math.floor(expiresAtSeconds);
+    const mac = base64Url(await hmacBytes(secret, `caelo-staging:${purpose}:${exp}`));
+    return `${purpose}.${exp}.${mac}`;
+}
+/** True when `token` is a valid, unexpired token for `purpose`. */
+export async function verifyStagingToken(secret, token, purpose, nowSeconds) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return false;
+    const [p, expRaw, mac] = parts;
+    if (p !== purpose || !/^\d{1,12}$/.test(expRaw))
+        return false;
+    const exp = Number(expRaw);
+    const expected = base64Url(await hmacBytes(secret, `caelo-staging:${purpose}:${exp}`));
+    // Compare before checking expiry so the timing does not tell an expired
+    // token from a forged one.
+    const valid = constantTimeEqual(mac, expected);
+    return valid && exp > nowSeconds;
+}
+// ─── IP allowlist ─────────────────────────────────────────────────────
+function parseIpv4(s) {
+    const parts = s.split(".");
+    if (parts.length !== 4)
+        return null;
+    const out = [];
+    for (const p of parts) {
+        if (!/^\d{1,3}$/.test(p))
+            return null;
+        const n = Number(p);
+        if (n > 255)
+            return null;
+        out.push(n);
+    }
+    return out;
+}
+function parseIpv6(s) {
+    let text = s;
+    let tail = [];
+    const lastColon = text.lastIndexOf(":");
+    if (text.includes(".")) {
+        const v4 = parseIpv4(text.slice(lastColon + 1));
+        if (!v4)
+            return null;
+        tail = v4;
+        text = `${text.slice(0, lastColon + 1)}0:0`;
+    }
+    const halves = text.split("::");
+    if (halves.length > 2)
+        return null;
+    const groups = (h) => (h === "" ? [] : h.split(":"));
+    const head = groups(halves[0] ?? "");
+    const rest = halves.length === 2 ? groups(halves[1] ?? "") : [];
+    const fill = 8 - head.length - rest.length;
+    if (halves.length === 1 ? head.length !== 8 : fill < 1)
+        return null;
+    const all = [...head, ...Array(halves.length === 2 ? fill : 0).fill("0"), ...rest];
+    const bytes = [];
+    for (const g of all) {
+        if (!/^[0-9a-fA-F]{1,4}$/.test(g))
+            return null;
+        const n = Number.parseInt(g, 16);
+        bytes.push(n >> 8, n & 0xff);
+    }
+    if (tail.length === 4)
+        bytes.splice(12, 4, ...tail);
+    return bytes;
+}
+/** Parse an IP address into bytes; an IPv4-mapped IPv6 address becomes IPv4. */
+function parseIp(raw) {
+    const s = raw.trim().replace(/^\[|\]$/g, "");
+    if (s.includes(":")) {
+        const v6 = parseIpv6(s.split("%")[0] ?? "");
+        if (!v6)
+            return null;
+        const mapped = v6.slice(0, 10).every((b) => b === 0) && v6[10] === 0xff && v6[11] === 0xff;
+        return mapped ? v6.slice(12) : v6;
+    }
+    return parseIpv4(s);
+}
+/** A parsed CIDR, or null when `cidr` is not one. A bare address is a host route. */
+export function parseCidr(cidr) {
+    const [addr, len, extra] = cidr.trim().split("/");
+    if (addr === undefined || extra !== undefined)
+        return null;
+    const bytes = parseIp(addr);
+    if (!bytes)
+        return null;
+    const max = bytes.length * 8;
+    if (len === undefined)
+        return { bytes, bits: max };
+    if (!/^\d{1,3}$/.test(len))
+        return null;
+    const bits = Number(len);
+    return bits <= max ? { bytes, bits } : null;
+}
+/** True when `ip` lies inside `cidr` (same address family only). */
+export function ipMatchesCidr(ip, cidr) {
+    const addr = parseIp(ip);
+    const net = parseCidr(cidr);
+    if (!addr || !net || addr.length !== net.bytes.length)
+        return false;
+    let bits = net.bits;
+    for (let i = 0; i < addr.length && bits > 0; i++) {
+        const take = Math.min(8, bits);
+        const mask = (0xff << (8 - take)) & 0xff;
+        if (((addr[i] ?? 0) & mask) !== ((net.bytes[i] ?? 0) & mask))
+            return false;
+        bits -= take;
+    }
+    return true;
+}
+// ─── request decision ─────────────────────────────────────────────────
+/** `Authorization: Basic …` → user + password, or null. */
+export function parseBasicAuthorization(header) {
+    if (!header)
+        return null;
+    const m = /^Basic\s+([A-Za-z0-9+/=]+)\s*$/i.exec(header);
+    if (!m?.[1])
+        return null;
+    let decoded;
+    try {
+        decoded = new TextDecoder().decode(Uint8Array.from(atob(m[1]), (c) => c.charCodeAt(0)));
+    }
+    catch {
+        return null;
+    }
+    const i = decoded.indexOf(":");
+    if (i < 0)
+        return null;
+    return { user: decoded.slice(0, i), password: decoded.slice(i + 1) };
+}
+/** The value of cookie `name` in a `Cookie` header, or null. */
+export function readCookie(header, name) {
+    if (!header)
+        return null;
+    for (const part of header.split(/;\s*/)) {
+        const eq = part.indexOf("=");
+        if (eq > 0 && part.slice(0, eq).trim() === name)
+            return part.slice(eq + 1).trim();
+    }
+    return null;
+}
+/**
+ * Decide one staging request. Any enabled mode that the request satisfies
+ * lets it in; every check runs (no short-circuit on the first secret
+ * comparison), so the response time does not reveal which mode failed.
+ */
+export async function decideStagingAccess(args) {
+    const { settings, secret, request } = args;
+    const granted = [];
+    if (settings.cookieEnabled) {
+        const token = readCookie(request.cookieHeader, STAGING_SESSION_COOKIE);
+        if (token && (await verifyStagingToken(secret, token, "session", args.nowSeconds))) {
+            granted.push("cookie");
+        }
+    }
+    if (settings.basicAuthEnabled && settings.basicAuthNonce) {
+        const presented = parseBasicAuthorization(request.authorizationHeader);
+        const expected = await deriveStagingCredential(secret, "basic-auth", settings.basicAuthNonce);
+        const userOk = constantTimeEqual(presented?.user ?? "", settings.basicAuthUser);
+        const passOk = constantTimeEqual(presented?.password ?? "", expected);
+        if (presented && userOk && passOk)
+            granted.push("basic-auth");
+    }
+    if (settings.headerEnabled && settings.headerNonce) {
+        const presented = request.header(settings.headerName) ?? "";
+        const expected = await deriveStagingCredential(secret, "header", settings.headerNonce);
+        if (constantTimeEqual(presented, expected) && presented !== "")
+            granted.push("header");
+    }
+    const ip = request.clientIp;
+    if (ip && settings.ipAllowlist.some((c) => ipMatchesCidr(ip, c)))
+        granted.push("ip");
+    const via = granted[0];
+    if (via)
+        return { allowed: true, via, satisfied: granted };
+    return { allowed: false, status: settings.basicAuthEnabled ? 401 : 403 };
+}
+/**
+ * Where "Open staging" may send the browser after setting the cookie: a
+ * same-origin path only (never `//host` or a scheme), else `/`.
+ *
+ * The result is always ASCII (safe as a `Location` header value).
+ *
+ * Control characters are refused outright, not only CR/LF: the WHATWG URL
+ * parser deletes tabs and newlines before it parses a Location, so
+ * `/<TAB>/evil.example` would otherwise become `//evil.example` in the
+ * browser — an open redirect off the staging host.
+ */
+export function safeStagingNextPath(next) {
+    if (next === null || !next.startsWith("/") || next.startsWith("//"))
+        return "/";
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: matching control characters is the point
+    if (next.includes("\\") || /[\u0000-\u001f\u007f]/.test(next))
+        return "/";
+    // Serialise through the URL parser: non-ASCII is percent-encoded (a raw
+    // `/日本/` is not a valid header value and would fail the redirect), and
+    // the origin check is the parser's own verdict, not ours.
+    const base = "https://staging.invalid";
+    const url = new URL(next, base);
+    if (url.origin !== base)
+        return "/";
+    return `${url.pathname}${url.search}${url.hash}`;
+}
+// ─── the staging host setting ─────────────────────────────────────────
+/**
+ * The staging host an install gets when the operator names none:
+ * `staging.<install domain>`.
+ */
+export function defaultStagingHost(domain) {
+    return `staging.${domain.trim().toLowerCase().replace(/\.$/, "")}`;
+}
+/**
+ * Longest host a Cloud Run domain mapping accepts — the gcp-firebase
+ * gateway is mapped to the staging host, so a longer one would be stored,
+ * rendered into every staged build and then never answer.
+ * https://cloud.google.com/run/docs/mapping-custom-domains#limitations
+ */
+export const CLOUD_RUN_DOMAIN_MAPPING_MAX_HOST_LENGTH = 64;
+const FQDN = /^(?=.{4,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+/** Lower-case, trailing-dot-free form of a host the operator typed. */
+export function normalizeStagingHost(host) {
+    return host.trim().toLowerCase().replace(/\.$/, "");
+}
+/**
+ * Why `host` cannot be the staging host, or null when it can. It must be a
+ * bare fully-qualified domain name (no scheme, port or path) and must not be
+ * the live site's host or an admin host — staging would otherwise shadow
+ * the site or the admin it is served next to. On gcp-firebase (`provider`)
+ * it must also fit a Cloud Run domain mapping
+ * ({@link CLOUD_RUN_DOMAIN_MAPPING_MAX_HOST_LENGTH} characters).
+ *
+ * @example
+ *   stagingHostProblem("preview.example.com", { liveHosts: ["example.com"], adminHosts: ["admin.example.com"] })
+ *   // → null
+ */
+export function stagingHostProblem(host, reserved, opts = {}) {
+    const h = normalizeStagingHost(host);
+    if (!FQDN.test(h)) {
+        return `"${host}" is not a valid host name — use a bare domain such as staging.example.com (no https://, port or path)`;
+    }
+    if (opts.provider === "gcp-firebase" && h.length > CLOUD_RUN_DOMAIN_MAPPING_MAX_HOST_LENGTH) {
+        return `"${h}" is ${h.length} characters long; on gcp-firebase the staging host is served through a Cloud Run domain mapping, which accepts at most ${CLOUD_RUN_DOMAIN_MAPPING_MAX_HOST_LENGTH} — pick a shorter host (e.g. stg.<your domain>, or a shorter domain you own)`;
+    }
+    const norm = (list) => list.map(normalizeStagingHost).filter(Boolean);
+    if (norm(reserved.liveHosts).includes(h)) {
+        return `"${h}" is the live site's host — staging needs a host of its own (e.g. staging.${h})`;
+    }
+    if (norm(reserved.adminHosts).includes(h)) {
+        return `"${h}" is the admin's host — pick another host for staging`;
+    }
+    return null;
+}
+//# sourceMappingURL=staging-gate.js.map

package/dist/staging-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staging-gate.js","sourceRoot":"","sources":["../src/staging-gate.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -19,7 +19,7 @@
  * Format: SemVer 2.0.0. Pre-1.0 minor bumps are breaking; post-1.0
  * follow standard SemVer.
  */
-export declare const CAELO_VERSION = "0.10.37";
+export declare const CAELO_VERSION = "0.10.39";
 /**
  * Deprecated alias for back-compat — early P17 work spelled this
  * `CALEO_VERSION` (typo of "Caelo"). New code should import
@@ -31,7 +31,7 @@ export declare const CAELO_VERSION = "0.10.37";
  *
  * @deprecated use CAELO_VERSION
  */
-export declare const CALEO_VERSION = "0.10.37";
+export declare const CALEO_VERSION = "0.10.39";
 /**
  * Parsed shape — major/minor/patch + optional pre-release tag.
  * Stable interface for callers that need to feature-gate (rare —

package/dist/version.js

@@ -20,7 +20,7 @@
  * Format: SemVer 2.0.0. Pre-1.0 minor bumps are breaking; post-1.0
  * follow standard SemVer.
  */
-export const CAELO_VERSION = "0.10.37";
+export const CAELO_VERSION = "0.10.39";
 /**
  * Deprecated alias for back-compat — early P17 work spelled this
  * `CALEO_VERSION` (typo of "Caelo"). New code should import

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caelo-cms/shared",
-  "version": "0.10.37",
+  "version": "0.10.39",
   "private": false,
   "license": "MPL-2.0",
   "description": "Shared Zod schemas + types + the two-pass HTML composer used by every Caelo CMS workspace package. Stable enough for plugin authors and embedders to depend on directly.",

package/src/ai-tools.ts

@@ -25,6 +25,7 @@ import {
   slugSchema,
 } from "./content.js";
 import { pluginPreviewSelectionSchema } from "./plugin-preview.js";
+import { redirectTargetPathSchema } from "./redirect-target.js";
 
 /**
  * v0.6.2 — `position` argument shared across the three `add_module_to_*`
@@ -905,7 +906,7 @@ export const bulkCreateRedirectsToolInput = z
         z
           .object({
             fromPath: z.string().min(1).max(500),
-            toPath: z.string().min(1).max(500),
+            toPath: redirectTargetPathSchema,
             statusCode: z
               .union([
                 z.literal(301),

package/src/index.ts

@@ -39,12 +39,14 @@ export * from "./plugin-preview.js";
 export * from "./preview-compose.js";
 export * from "./preview-scanner.js";
 export * from "./proposal-status.js";
+export * from "./redirect-target.js";
 export * from "./responsive-images.js";
 export * from "./result.js";
 export * from "./safe-keys.js";
 export * from "./seo.js";
 export * from "./skills.js";
 export * from "./snapshots.js";
+export * from "./staging-gate.js";
 export * from "./static-cache-policy.js";
 export * from "./strip-cdata.js";
 export * from "./structured-sets.js";

package/src/redirect-target.test.ts

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { redirectTargetIssue, redirectTargetPathSchema } from "./redirect-target.js";
+
+describe("redirectTargetIssue (#657)", () => {
+  it.each([
+    "/",
+    "/a/b",
+    "/a/b?c=d#e",
+    "/blog/2024/hello-world",
+    "/de/preise",
+    "/files/report.pdf",
+    "/caf%C3%A9",
+    "/über-uns",
+    "/a//b",
+    "/wiki/Special:Search",
+    "/foo:bar",
+    "/a?next=https://example.com",
+  ])("accepts the same-site path %p", (path) => {
+    expect(redirectTargetIssue(path)).toBeNull();
+  });
+
+  it("rejects a path without a leading slash and says external targets are unsupported", () => {
+    const issue = redirectTargetIssue("https://example.com/x");
+    expect(issue).toContain("must start with '/'");
+    expect(issue).toContain("external (other-domain) redirect targets are not supported");
+    expect(redirectTargetIssue("pricing")).toContain("must start with '/'");
+  });
+
+  it.each(["//evil.example/x", "//evil.example", "///evil.example/x"])(
+    "rejects the protocol-relative %p and suggests a single-slash path",
+    (path) => {
+      const issue = redirectTargetIssue(path);
+      expect(issue).toContain("protocol-relative");
+      expect(issue).toContain("'/evil.example");
+    },
+  );
+
+  it("rejects backslashes, which browsers normalise to '/' (\\/\\host == //host)", () => {
+    expect(redirectTargetIssue("/\\evil.example/x")).toContain("backslash");
+  });
+
+  it.each(["/\t/evil.example", "/x\ny", "/a b", "/a\u0000b"])(
+    "rejects whitespace/control characters in %p",
+    (path) => {
+      expect(redirectTargetIssue(path)).toContain("whitespace or control characters");
+    },
+  );
+
+  it.each([
+    ["/https://example.com/x", "/x"],
+    ["/http://example.com/a/b?c=d#e", "/a/b?c=d#e"],
+    ["/HTTPS://Example.com/", "/"],
+  ])("rejects the embedded URL %p and suggests its path %p", (path, suggested) => {
+    const issue = redirectTargetIssue(path);
+    expect(issue).toContain("embeds a full URL");
+    expect(issue).toContain(`use its path '${suggested}'`);
+    expect(issue).toContain("external (other-domain) redirect targets are not supported");
+  });
+
+  it.each(["/https:/example.com/x", "/https:example.com", "/http:"])(
+    "rejects a mangled web-scheme first segment %p without a misleading suggestion",
+    (path) => {
+      const issue = redirectTargetIssue(path);
+      expect(issue).toContain("embeds a full URL");
+      expect(issue).not.toContain("use its path");
+    },
+  );
+
+  it.each(["/ftp://files.example/x", "/javascript://x", "/custom+scheme://x"])(
+    "rejects any scheme followed by '//' (%p)",
+    (path) => {
+      expect(redirectTargetIssue(path)).toContain("embeds a full URL");
+    },
+  );
+});
+
+describe("redirectTargetPathSchema", () => {
+  it("parses a valid target and carries the actionable message on failure", () => {
+    expect(redirectTargetPathSchema.parse("/a/b?c=d#e")).toBe("/a/b?c=d#e");
+    const r = redirectTargetPathSchema.safeParse("/https://example.com/x");
+    expect(r.success).toBe(false);
+    expect(r.error?.issues[0]?.message).toContain("use its path '/x'");
+  });
+
+  it("keeps the length bounds", () => {
+    expect(redirectTargetPathSchema.safeParse("").success).toBe(false);
+    expect(redirectTargetPathSchema.safeParse(`/${"a".repeat(500)}`).success).toBe(false);
+  });
+});

package/src/redirect-target.ts

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The one validator for a redirect's TARGET (`toPath`) — issue #657.
+ *
+ * Caelo redirects only ever point at a path on the same site: the
+ * `redirects` table has no external-URL field, and every surface that
+ * serves the table (the admin's 404 fallback, the generator's
+ * `_redirects` / `_redirects.caddy`, the per-provider emitters) writes
+ * `toPath` verbatim into a `Location` header. "Starts with `/`" is not
+ * enough for that to stay on-site:
+ *
+ *   - `//host/x` (and `/\host/x`, which browsers normalise to `//`) is a
+ *     protocol-relative URL — the browser leaves the site for `host`.
+ *     That turns any redirect into an open redirect.
+ *   - `/https://example.com/x` is a same-site path whose first segment is
+ *     `https:`; the browser lands on `https://<site>/https://example.com/x`,
+ *     which is never what the author meant (they pasted a full URL).
+ *   - Whitespace / control characters: browsers strip tab/CR/LF inside a
+ *     URL, so `/\t/host` collapses to `//host`; the `_redirects` formats
+ *     are whitespace-delimited and the emitters already refuse them.
+ *
+ * Every write path (redirects.create / create_many, page delete with
+ * `disposition: 'redirect'`, the AI tool schemas, the import composer)
+ * and every serving path (static generator, admin 404 fallback) calls
+ * this, so a value rejected at write time can never be served either.
+ */
+
+import { z } from "zod";
+
+/** Max length of a stored redirect path (matches the op schemas). */
+const REDIRECT_PATH_MAX_LENGTH = 500;
+
+/** A URL scheme token (RFC 3986 §3.1) followed by `:`. */
+const SCHEME_PREFIX = /^([A-Za-z][A-Za-z0-9+.-]*):/;
+
+/** Schemes that are never a meaningful first path segment. A pasted
+ *  `/https:/x` (slashes collapsed by a form or a CSV tool) is the same
+ *  mistake as `/https://x`, so these are rejected even without `//`. */
+const WEB_SCHEMES = new Set(["http", "https"]);
+
+const EXTERNAL_NOT_SUPPORTED =
+  "Redirects can only target a path on this site (e.g. '/pricing'); external (other-domain) redirect targets are not supported. If the destination is a page on this site, pass only its path.";
+
+/**
+ * Return why `toPath` is not a safe same-site redirect target, or `null`
+ * when it is. The message is written for the AI: it names the problem
+ * and what to pass instead.
+ *
+ * @example
+ *   redirectTargetIssue("/blog/new?x=1#top")    // null
+ *   redirectTargetIssue("//evil.example/x")     // "... protocol-relative ..."
+ *   redirectTargetIssue("/https://a.example/x") // "... use '/x' ..."
+ */
+export function redirectTargetIssue(toPath: string): string | null {
+  const shown = JSON.stringify(toPath);
+  if (!toPath.startsWith("/")) {
+    return `toPath ${shown} must start with '/'. ${EXTERNAL_NOT_SUPPORTED}`;
+  }
+  if (/[\s\p{Cc}]/u.test(toPath)) {
+    return `toPath ${shown} contains whitespace or control characters. Percent-encode them (a space is '%20') or remove them.`;
+  }
+  if (toPath.includes("\\")) {
+    return `toPath ${shown} contains a backslash; browsers treat '\\' as '/', so it can turn into a link to another host. Use forward slashes only.`;
+  }
+  if (toPath.startsWith("//")) {
+    return `toPath ${shown} starts with '//', which browsers read as a protocol-relative URL to another host (an open redirect), not as a path on this site. Use a single leading slash, e.g. '/${trimLeadingSlashes(toPath)}'. ${EXTERNAL_NOT_SUPPORTED}`;
+  }
+  const scheme = SCHEME_PREFIX.exec(toPath.slice(1));
+  if (scheme) {
+    const rest = toPath.slice(1 + scheme[0].length);
+    const name = (scheme[1] ?? "").toLowerCase();
+    if (rest.startsWith("/") || WEB_SCHEMES.has(name)) {
+      const suggestion = pathOfEmbeddedUrl(toPath.slice(1));
+      const hint = suggestion ? ` If that URL is on this site, use its path '${suggestion}'.` : "";
+      return `toPath ${shown} embeds a full URL ('${scheme[1]}:…') after the leading '/'; browsers resolve it as a path on this site, not as that URL.${hint} ${EXTERNAL_NOT_SUPPORTED}`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Zod schema for a redirect target. Use this — not a bare
+ * `z.string().regex(/^\//)` — wherever a redirect target enters the
+ * system, so the rule above holds on every path.
+ */
+export const redirectTargetPathSchema = z
+  .string()
+  .min(1)
+  .max(REDIRECT_PATH_MAX_LENGTH)
+  .superRefine((value, ctx) => {
+    const issue = redirectTargetIssue(value);
+    if (issue) ctx.addIssue({ code: "custom", message: issue });
+  });
+
+function trimLeadingSlashes(s: string): string {
+  let i = 0;
+  while (i < s.length && s.charCodeAt(i) === 47 /* '/' */) i += 1;
+  return s.slice(i);
+}
+
+/** `https://a.example/x?y#z` → `/x?y#z`; null when unparseable. */
+function pathOfEmbeddedUrl(url: string): string | null {
+  // Only a well-formed `scheme://host` URL has a path worth suggesting;
+  // `https:/x` would parse as host `x` and suggest a misleading '/'.
+  if (!/^https?:\/\/[^/]/i.test(url)) return null;
+  try {
+    const u = new URL(url);
+    if (u.protocol !== "http:" && u.protocol !== "https:") return null;
+    return `${u.pathname}${u.search}${u.hash}`;
+  } catch {
+    return null;
+  }
+}