@caelo-cms/shared 0.11.18 → 0.11.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/change-journal.d.ts +1 -1
- package/dist/change-journal.d.ts.map +1 -1
- package/dist/change-journal.js +5 -0
- package/dist/change-journal.js.map +1 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/dist/install-ai-mode.d.ts +25 -0
- package/dist/install-ai-mode.d.ts.map +1 -0
- package/dist/install-ai-mode.js +17 -0
- package/dist/install-ai-mode.js.map +1 -0
- package/dist/markup-structure.d.ts +7 -0
- package/dist/markup-structure.d.ts.map +1 -1
- package/dist/markup-structure.js +7 -3
- package/dist/markup-structure.js.map +1 -1
- package/dist/redirect-emit-caddy.d.ts +10 -0
- package/dist/redirect-emit-caddy.d.ts.map +1 -1
- package/dist/redirect-emit-caddy.js +13 -0
- package/dist/redirect-emit-caddy.js.map +1 -1
- package/dist/redirect-plan.d.ts +11 -0
- package/dist/redirect-plan.d.ts.map +1 -1
- package/dist/redirect-plan.js +14 -0
- package/dist/redirect-plan.js.map +1 -1
- package/dist/staged-site.d.ts.map +1 -1
- package/dist/staged-site.js +9 -0
- package/dist/staged-site.js.map +1 -1
- package/dist/static-files.d.ts +107 -0
- package/dist/static-files.d.ts.map +1 -0
- package/dist/static-files.js +274 -0
- package/dist/static-files.js.map +1 -0
- package/dist/version.d.ts +2 -2
- package/dist/version.js +1 -1
- package/package.json +1 -1
- package/src/change-journal.ts +6 -0
- package/src/index.ts +2 -0
- package/src/install-ai-mode.ts +35 -0
- package/src/markup-structure.test.ts +8 -0
- package/src/markup-structure.ts +14 -3
- package/src/redirect-emit-caddy.ts +18 -0
- package/src/redirect-plan.test.ts +12 -0
- package/src/redirect-plan.ts +15 -0
- package/src/staged-site.ts +13 -0
- package/src/static-files.test.ts +238 -0
- package/src/static-files.ts +311 -0
- package/src/version.ts +1 -1
package/src/redirect-plan.ts
CHANGED
|
@@ -202,6 +202,21 @@ export function redirectsToUnservedPaths(
|
|
|
202
202
|
});
|
|
203
203
|
}
|
|
204
204
|
|
|
205
|
+
/**
|
|
206
|
+
* #1447 — every spelling of a path the redirects table can hold a row for.
|
|
207
|
+
* A row answers its path with and without the trailing slash (see the module
|
|
208
|
+
* comment), and a table imported from a CMS with `/`-terminated URLs stores
|
|
209
|
+
* the slash form, so a lookup by one spelling misses the row that answers it.
|
|
210
|
+
*
|
|
211
|
+
* @example
|
|
212
|
+
* redirectFromPathSpellings("/old/") // → ["/old", "/old/"]
|
|
213
|
+
* redirectFromPathSpellings("/") // → ["/"]
|
|
214
|
+
*/
|
|
215
|
+
export function redirectFromPathSpellings(path: string): readonly string[] {
|
|
216
|
+
const bare = stripTrailingSlash(path);
|
|
217
|
+
return bare === "/" ? [bare] : [bare, `${bare}/`];
|
|
218
|
+
}
|
|
219
|
+
|
|
205
220
|
function normaliseRows(rows: readonly RedirectTableRow[]): NormalisedRow[] {
|
|
206
221
|
const byBare = new Map<string, NormalisedRow>();
|
|
207
222
|
const out: NormalisedRow[] = [];
|
package/src/staged-site.ts
CHANGED
|
@@ -30,6 +30,7 @@ import {
|
|
|
30
30
|
IMMUTABLE_CACHE_CONTROL,
|
|
31
31
|
isContentHashedPath,
|
|
32
32
|
} from "./static-cache-policy.js";
|
|
33
|
+
import { STATIC_FILE_CONTENT_TYPES } from "./static-files.js";
|
|
33
34
|
|
|
34
35
|
/** The two cloud slots a Stage alternates between. */
|
|
35
36
|
export const STAGING_SLOTS = ["a", "b"] as const;
|
|
@@ -163,6 +164,8 @@ export function contentTypeFor(key: string): string {
|
|
|
163
164
|
return "font/woff";
|
|
164
165
|
case ".txt":
|
|
165
166
|
return "text/plain; charset=utf-8";
|
|
167
|
+
case ".csv":
|
|
168
|
+
return "text/csv; charset=utf-8";
|
|
166
169
|
case ".xml":
|
|
167
170
|
return "application/xml; charset=utf-8";
|
|
168
171
|
default:
|
|
@@ -190,6 +193,16 @@ export function cacheControlForContentType(contentType: string, key: string): st
|
|
|
190
193
|
if (key === "robots.txt" || key === "sitemap.xml") {
|
|
191
194
|
return "public, max-age=300";
|
|
192
195
|
}
|
|
196
|
+
// #1461 — a static file keeps its URL when its text changes, so it must
|
|
197
|
+
// not linger like an asset. `_…` paths are the build's own.
|
|
198
|
+
if (
|
|
199
|
+
!key.startsWith("_") &&
|
|
200
|
+
(STATIC_FILE_CONTENT_TYPES as readonly string[]).includes(
|
|
201
|
+
contentType.split(";")[0]?.trim() ?? "",
|
|
202
|
+
)
|
|
203
|
+
) {
|
|
204
|
+
return "public, max-age=300";
|
|
205
|
+
}
|
|
193
206
|
return "public, max-age=3600";
|
|
194
207
|
}
|
|
195
208
|
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
// SPDX-License-Identifier: MPL-2.0
|
|
2
|
+
|
|
3
|
+
import { describe, expect, it } from "bun:test";
|
|
4
|
+
import { emitCaddyStaticFileHeaders } from "./redirect-emit-caddy.js";
|
|
5
|
+
import { cacheControlForContentType, contentTypeFor, isSafeStagedPath } from "./staged-site.js";
|
|
6
|
+
import {
|
|
7
|
+
formatStaticFilesManifest,
|
|
8
|
+
parseStaticFilesManifest,
|
|
9
|
+
STATIC_FILE_MAX_BYTES,
|
|
10
|
+
staticFileBodyIssue,
|
|
11
|
+
staticFileCollisions,
|
|
12
|
+
staticFileContentTypeHeader,
|
|
13
|
+
staticFileIssues,
|
|
14
|
+
staticFilePathIssue,
|
|
15
|
+
staticFileTypeIssue,
|
|
16
|
+
} from "./static-files.js";
|
|
17
|
+
|
|
18
|
+
describe("staticFilePathIssue", () => {
|
|
19
|
+
it.each([
|
|
20
|
+
"/bot/ips.json",
|
|
21
|
+
"/ads.txt",
|
|
22
|
+
"/llms.txt",
|
|
23
|
+
"/data/export.csv",
|
|
24
|
+
"/feed/items.xml",
|
|
25
|
+
"/BingSiteAuth.xml",
|
|
26
|
+
"/.well-known/security.txt",
|
|
27
|
+
"/.well-known/assetlinks.json",
|
|
28
|
+
"/.well-known/apple-app-site-association",
|
|
29
|
+
"/.well-known/nested/thing.json",
|
|
30
|
+
"/plain-name",
|
|
31
|
+
])("accepts %s", (path) => {
|
|
32
|
+
expect(staticFilePathIssue(path)).toBeNull();
|
|
33
|
+
expect(isSafeStagedPath(path.slice(1))).toBe(true);
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
it.each([
|
|
37
|
+
["no leading slash", "bot/ips.json"],
|
|
38
|
+
["a folder", "/bot/"],
|
|
39
|
+
["the root", "/"],
|
|
40
|
+
["the assets folder", "/_assets/x.json"],
|
|
41
|
+
["the platform folder", "/_caelo/x.json"],
|
|
42
|
+
["any underscore folder", "/_redirects"],
|
|
43
|
+
["Firebase's reserved folder", "/__/x.json"],
|
|
44
|
+
["the gateway", "/api/x.json"],
|
|
45
|
+
["the gateway, other case", "/API/x.json"],
|
|
46
|
+
["robots.txt", "/robots.txt"],
|
|
47
|
+
["robots.txt, other case", "/ROBOTS.txt"],
|
|
48
|
+
["the sitemap", "/sitemap.xml"],
|
|
49
|
+
["the routing manifest", "/routing-manifest.json"],
|
|
50
|
+
["a hidden file", "/.env"],
|
|
51
|
+
["a hidden folder", "/.git/config"],
|
|
52
|
+
["a hidden file below a folder", "/bot/.htaccess"],
|
|
53
|
+
["only the well-known folder", "/.well-known"],
|
|
54
|
+
["remote MCP's OAuth metadata", "/.well-known/oauth-protected-resource"],
|
|
55
|
+
["remote MCP's metadata, deeper", "/.well-known/oauth-authorization-server/api/mcp/oauth"],
|
|
56
|
+
["certificate issuance", "/.well-known/acme-challenge/token"],
|
|
57
|
+
["a traversal", "/bot/../robots.txt"],
|
|
58
|
+
["an empty segment", "/bot//ips.json"],
|
|
59
|
+
["a query", "/bot/ips.json?x=1"],
|
|
60
|
+
["a space", "/bot/my file.json"],
|
|
61
|
+
["HTML", "/verify.html"],
|
|
62
|
+
["an HTML variant", "/verify.HTM"],
|
|
63
|
+
["JavaScript", "/app.js"],
|
|
64
|
+
["an ES module", "/app.mjs"],
|
|
65
|
+
["CSS", "/site.css"],
|
|
66
|
+
["SVG", "/logo.svg"],
|
|
67
|
+
["an icon", "/favicon.ico"],
|
|
68
|
+
["a very long path", `/${"a".repeat(201)}`],
|
|
69
|
+
])("refuses %s", (_what, path) => {
|
|
70
|
+
expect(staticFilePathIssue(path)).not.toBeNull();
|
|
71
|
+
});
|
|
72
|
+
});
|
|
73
|
+
|
|
74
|
+
describe("staticFileTypeIssue", () => {
|
|
75
|
+
it("takes the declared type where the extension agrees", () => {
|
|
76
|
+
expect(staticFileTypeIssue("/a.json", "application/json")).toBeNull();
|
|
77
|
+
expect(staticFileTypeIssue("/a.xml", "text/xml")).toBeNull();
|
|
78
|
+
expect(staticFileTypeIssue("/a.xml", "application/xml")).toBeNull();
|
|
79
|
+
expect(staticFileTypeIssue("/.well-known/x", "application/json")).toBeNull();
|
|
80
|
+
});
|
|
81
|
+
|
|
82
|
+
it("refuses a type the extension contradicts", () => {
|
|
83
|
+
expect(staticFileTypeIssue("/a.json", "text/plain")).toContain("application/json");
|
|
84
|
+
});
|
|
85
|
+
|
|
86
|
+
it("refuses every type outside the allow-list, a path without extension included", () => {
|
|
87
|
+
for (const type of ["text/html", "application/javascript", "text/css", "image/svg+xml"]) {
|
|
88
|
+
expect(staticFileTypeIssue("/x", type)).toContain("cannot be served");
|
|
89
|
+
}
|
|
90
|
+
});
|
|
91
|
+
});
|
|
92
|
+
|
|
93
|
+
describe("staticFileBodyIssue", () => {
|
|
94
|
+
it("accepts plain data", () => {
|
|
95
|
+
expect(staticFileBodyIssue("application/json", '{"ips":["192.0.2.1"]}')).toBeNull();
|
|
96
|
+
expect(staticFileBodyIssue("text/plain", "Contact: mailto:security@example.com\n")).toBeNull();
|
|
97
|
+
expect(staticFileBodyIssue("text/csv", "a,b\n1,2\n")).toBeNull();
|
|
98
|
+
expect(staticFileBodyIssue("application/xml", "<users><user>a</user></users>")).toBeNull();
|
|
99
|
+
});
|
|
100
|
+
|
|
101
|
+
it("refuses an empty file, invalid JSON and a NUL", () => {
|
|
102
|
+
expect(staticFileBodyIssue("text/plain", "")).toContain("empty");
|
|
103
|
+
expect(staticFileBodyIssue("application/json", "{oops")).toContain("not valid JSON");
|
|
104
|
+
expect(staticFileBodyIssue("text/plain", "a\0b")).toContain("NUL");
|
|
105
|
+
});
|
|
106
|
+
|
|
107
|
+
it("counts bytes, not characters, against the cap", () => {
|
|
108
|
+
expect(staticFileBodyIssue("text/plain", "a".repeat(STATIC_FILE_MAX_BYTES))).toBeNull();
|
|
109
|
+
expect(staticFileBodyIssue("text/plain", "ä".repeat(STATIC_FILE_MAX_BYTES / 2 + 1))).toContain(
|
|
110
|
+
"bytes",
|
|
111
|
+
);
|
|
112
|
+
});
|
|
113
|
+
|
|
114
|
+
it.each([
|
|
115
|
+
["an XHTML script", '<a><script xmlns="http://www.w3.org/1999/xhtml">x()</script></a>'],
|
|
116
|
+
["an SVG", '<svg xmlns="http://www.w3.org/2000/svg"><script>x()</script></svg>'],
|
|
117
|
+
["MathML", '<math xmlns="http://www.w3.org/1998/Math/MathML"/>'],
|
|
118
|
+
["a stylesheet", '<?xml-stylesheet href="x.xsl" type="text/xsl"?><a/>'],
|
|
119
|
+
["a doctype", '<!DOCTYPE a [<!ENTITY x "y">]><a>&x;</a>'],
|
|
120
|
+
["an escaped namespace", '<a xmlns:h="http://www.w3.org/1999/xhtml"><h:script/></a>'],
|
|
121
|
+
["single quotes", "<a xmlns:h='http://evil'><h:script/></a>"],
|
|
122
|
+
])("refuses XML with %s, as both XML types", (_what, body) => {
|
|
123
|
+
expect(staticFileBodyIssue("application/xml", body)).toContain("run as a page");
|
|
124
|
+
expect(staticFileBodyIssue("text/xml", body)).toContain("run as a page");
|
|
125
|
+
});
|
|
126
|
+
});
|
|
127
|
+
|
|
128
|
+
describe("the escaped-namespace check", () => {
|
|
129
|
+
it("takes a namespace without references, and an ampersand outside one", () => {
|
|
130
|
+
const body = '<a xmlns="urn:x" xmlns:b="urn:y"><b:c>1 & 2</b:c></a>';
|
|
131
|
+
expect(staticFileBodyIssue("application/xml", body)).toBeNull();
|
|
132
|
+
});
|
|
133
|
+
|
|
134
|
+
it("finds spaces around the equals sign", () => {
|
|
135
|
+
const body = '<a xmlns:h = "http://x"/>';
|
|
136
|
+
expect(staticFileBodyIssue("text/xml", body)).toContain("run as a page");
|
|
137
|
+
});
|
|
138
|
+
|
|
139
|
+
it("stays fast on a body built to make it backtrack (CodeQL js/polynomial-redos)", () => {
|
|
140
|
+
const started = performance.now();
|
|
141
|
+
expect(staticFileBodyIssue("application/xml", "xmlns:".repeat(40_000))).toBeNull();
|
|
142
|
+
expect(performance.now() - started).toBeLessThan(500);
|
|
143
|
+
});
|
|
144
|
+
});
|
|
145
|
+
|
|
146
|
+
describe("staticFileCollisions", () => {
|
|
147
|
+
const none = { pagePaths: [], redirectFromPaths: [], filePaths: [] };
|
|
148
|
+
|
|
149
|
+
it("finds nothing on a free path", () => {
|
|
150
|
+
expect(
|
|
151
|
+
staticFileCollisions("/bot/ips.json", { ...none, pagePaths: ["/bot", "/bot/x"] }),
|
|
152
|
+
).toEqual([]);
|
|
153
|
+
});
|
|
154
|
+
|
|
155
|
+
it("finds a page at the path, with or without its trailing slash", () => {
|
|
156
|
+
expect(staticFileCollisions("/about", { ...none, pagePaths: ["/about"] })).toHaveLength(1);
|
|
157
|
+
expect(staticFileCollisions("/about", { ...none, pagePaths: ["/about/"] })).toHaveLength(1);
|
|
158
|
+
});
|
|
159
|
+
|
|
160
|
+
it("finds a page below an extension-less file", () => {
|
|
161
|
+
expect(staticFileCollisions("/docs", { ...none, pagePaths: ["/docs/intro"] })).toEqual([
|
|
162
|
+
"the page /docs/intro sits below /docs",
|
|
163
|
+
]);
|
|
164
|
+
});
|
|
165
|
+
|
|
166
|
+
it("finds a redirect from the path", () => {
|
|
167
|
+
expect(
|
|
168
|
+
staticFileCollisions("/old.json", { ...none, redirectFromPaths: ["/old.json"] }),
|
|
169
|
+
).toHaveLength(1);
|
|
170
|
+
});
|
|
171
|
+
|
|
172
|
+
it("finds a file that needs this path as a folder, and the reverse", () => {
|
|
173
|
+
expect(staticFileCollisions("/a", { ...none, filePaths: ["/a/b.json"] })).toHaveLength(1);
|
|
174
|
+
expect(staticFileCollisions("/a/b.json", { ...none, filePaths: ["/a"] })).toHaveLength(1);
|
|
175
|
+
});
|
|
176
|
+
|
|
177
|
+
it("does not count the file itself", () => {
|
|
178
|
+
expect(staticFileCollisions("/a.json", { ...none, filePaths: ["/a.json"] })).toEqual([]);
|
|
179
|
+
});
|
|
180
|
+
});
|
|
181
|
+
|
|
182
|
+
describe("staticFileIssues", () => {
|
|
183
|
+
it("reports the path and the body together, so one fix round is enough", () => {
|
|
184
|
+
const issues = staticFileIssues({
|
|
185
|
+
path: "/x.html",
|
|
186
|
+
contentType: "application/json",
|
|
187
|
+
body: "{",
|
|
188
|
+
purpose: "test",
|
|
189
|
+
});
|
|
190
|
+
expect(issues).toHaveLength(2);
|
|
191
|
+
});
|
|
192
|
+
});
|
|
193
|
+
|
|
194
|
+
describe("how the files are served", () => {
|
|
195
|
+
it("serves every allowed type with a UTF-8 charset", () => {
|
|
196
|
+
expect(staticFileContentTypeHeader("application/json")).toBe("application/json; charset=utf-8");
|
|
197
|
+
expect(contentTypeFor("data/export.csv")).toBe("text/csv; charset=utf-8");
|
|
198
|
+
});
|
|
199
|
+
|
|
200
|
+
it("gives a text file five minutes, like robots.txt, and leaves the build's own files alone", () => {
|
|
201
|
+
expect(cacheControlForContentType("text/plain; charset=utf-8", "ads.txt")).toBe(
|
|
202
|
+
"public, max-age=300",
|
|
203
|
+
);
|
|
204
|
+
expect(cacheControlForContentType("text/csv; charset=utf-8", "a/b.csv")).toBe(
|
|
205
|
+
"public, max-age=300",
|
|
206
|
+
);
|
|
207
|
+
expect(cacheControlForContentType("application/xml; charset=utf-8", "a.xml")).toBe(
|
|
208
|
+
"public, max-age=300",
|
|
209
|
+
);
|
|
210
|
+
expect(cacheControlForContentType("application/json; charset=utf-8", "bot/ips.json")).toBe(
|
|
211
|
+
"public, max-age=60",
|
|
212
|
+
);
|
|
213
|
+
expect(cacheControlForContentType("text/plain; charset=utf-8", "_assets/x.license.txt")).toBe(
|
|
214
|
+
"public, max-age=3600",
|
|
215
|
+
);
|
|
216
|
+
});
|
|
217
|
+
|
|
218
|
+
it("round-trips the build's sidecar and refuses a body it did not write", () => {
|
|
219
|
+
const files = [{ path: "bot/ips.json", contentType: "application/json; charset=utf-8" }];
|
|
220
|
+
expect(parseStaticFilesManifest(formatStaticFilesManifest(files))).toEqual(files);
|
|
221
|
+
expect(() => parseStaticFilesManifest("{}")).toThrow();
|
|
222
|
+
});
|
|
223
|
+
|
|
224
|
+
it("emits one Caddy header rule per file", () => {
|
|
225
|
+
expect(
|
|
226
|
+
emitCaddyStaticFileHeaders([
|
|
227
|
+
{
|
|
228
|
+
path: ".well-known/apple-app-site-association",
|
|
229
|
+
contentType: "application/json; charset=utf-8",
|
|
230
|
+
},
|
|
231
|
+
{ path: "a.xml", contentType: "text/xml; charset=utf-8" },
|
|
232
|
+
]),
|
|
233
|
+
).toBe(
|
|
234
|
+
'@caelo_static_0 path /.well-known/apple-app-site-association\nheader @caelo_static_0 Content-Type "application/json; charset=utf-8"\n' +
|
|
235
|
+
'@caelo_static_1 path /a.xml\nheader @caelo_static_1 Content-Type "text/xml; charset=utf-8"\n',
|
|
236
|
+
);
|
|
237
|
+
});
|
|
238
|
+
});
|
|
@@ -0,0 +1,311 @@
|
|
|
1
|
+
// SPDX-License-Identifier: MPL-2.0
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Issue #1461 — small static files on the site's domain: `/bot/ips.json`,
|
|
5
|
+
* `/.well-known/security.txt`, `/ads.txt`. The rules every surface shares
|
|
6
|
+
* (the ops, the generator and the publishers), so a file that passes here
|
|
7
|
+
* is one every provider serves the same way.
|
|
8
|
+
*
|
|
9
|
+
* Plain data only. HTML, JavaScript, CSS and SVG are refused for good: a
|
|
10
|
+
* file of those types would be the way around "no raw HTML on pages" and
|
|
11
|
+
* the module and plugin rules (CLAUDE.md §2). XML is data too, but a browser
|
|
12
|
+
* runs what an XML document carries in the XHTML or SVG namespace or through
|
|
13
|
+
* a stylesheet, so {@link staticFileBodyIssue} refuses those bodies. A header
|
|
14
|
+
* could not do that job on every provider: plain GCP serves object metadata,
|
|
15
|
+
* and a CSP there would be an infrastructure change per path.
|
|
16
|
+
*
|
|
17
|
+
* Docs: docs/dev/static-files.md.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
import { z } from "zod";
|
|
21
|
+
|
|
22
|
+
/** The Content-Types a static file may have (without charset). */
|
|
23
|
+
export const STATIC_FILE_CONTENT_TYPES = [
|
|
24
|
+
"application/json",
|
|
25
|
+
"text/plain",
|
|
26
|
+
"text/csv",
|
|
27
|
+
"application/xml",
|
|
28
|
+
"text/xml",
|
|
29
|
+
] as const;
|
|
30
|
+
|
|
31
|
+
/** One allowed Content-Type. */
|
|
32
|
+
export type StaticFileContentType = (typeof STATIC_FILE_CONTENT_TYPES)[number];
|
|
33
|
+
|
|
34
|
+
/** Largest body of one file, in UTF-8 bytes. Every byte lives in a snapshot row. */
|
|
35
|
+
export const STATIC_FILE_MAX_BYTES = 256 * 1024;
|
|
36
|
+
|
|
37
|
+
/** Most files one site may have. Every file is a header rule on Firebase and in Caddy. */
|
|
38
|
+
export const STATIC_FILE_MAX_COUNT = 50;
|
|
39
|
+
|
|
40
|
+
/** Most files one write may carry. */
|
|
41
|
+
export const STATIC_FILE_MAX_BATCH = 20;
|
|
42
|
+
|
|
43
|
+
/** Longest path, in characters. */
|
|
44
|
+
export const STATIC_FILE_MAX_PATH_LENGTH = 200;
|
|
45
|
+
|
|
46
|
+
/** Longest `purpose` text. */
|
|
47
|
+
export const STATIC_FILE_MAX_PURPOSE_LENGTH = 500;
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* The build's sidecar naming its static files and their Content-Types. The
|
|
51
|
+
* publishers that serve a file's type from a header rule (Firebase Hosting,
|
|
52
|
+
* Caddy) read it; the others take the type from the upload.
|
|
53
|
+
*/
|
|
54
|
+
export const STATIC_FILES_MANIFEST_FILE = "_static-files.json";
|
|
55
|
+
|
|
56
|
+
/** One file as {@link STATIC_FILES_MANIFEST_FILE} lists it. */
|
|
57
|
+
export interface StaticFileManifestEntry {
|
|
58
|
+
/** Build-relative path, no leading slash (`bot/ips.json`). */
|
|
59
|
+
readonly path: string;
|
|
60
|
+
/** The Content-Type header the file is served with. */
|
|
61
|
+
readonly contentType: string;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
const manifestSchema = z.object({
|
|
65
|
+
version: z.literal(1),
|
|
66
|
+
files: z.array(z.object({ path: z.string().min(1), contentType: z.string().min(1) })),
|
|
67
|
+
});
|
|
68
|
+
|
|
69
|
+
/** The sidecar's body for `files`. */
|
|
70
|
+
export function formatStaticFilesManifest(files: readonly StaticFileManifestEntry[]): string {
|
|
71
|
+
return JSON.stringify({ version: 1, files }, null, 2);
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Parse the sidecar.
|
|
76
|
+
*
|
|
77
|
+
* @throws when the body is not one the generator wrote: a build whose files
|
|
78
|
+
* would lose their Content-Type must not be deployed.
|
|
79
|
+
*/
|
|
80
|
+
export function parseStaticFilesManifest(body: string): readonly StaticFileManifestEntry[] {
|
|
81
|
+
return manifestSchema.parse(JSON.parse(body)).files;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** The Content-Type header for a stored type. All bodies are UTF-8. */
|
|
85
|
+
export function staticFileContentTypeHeader(type: StaticFileContentType): string {
|
|
86
|
+
return `${type}; charset=utf-8`;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** The extensions a path may carry, with the types each one may be served as. */
|
|
90
|
+
const TYPES_OF_EXTENSION: Readonly<Record<string, readonly StaticFileContentType[]>> = {
|
|
91
|
+
".json": ["application/json"],
|
|
92
|
+
".txt": ["text/plain"],
|
|
93
|
+
".csv": ["text/csv"],
|
|
94
|
+
".xml": ["application/xml", "text/xml"],
|
|
95
|
+
};
|
|
96
|
+
|
|
97
|
+
const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._~-]*$/;
|
|
98
|
+
|
|
99
|
+
/** Files the build writes at the site root. */
|
|
100
|
+
const RESERVED_ROOT_FILES: ReadonlySet<string> = new Set([
|
|
101
|
+
"robots.txt",
|
|
102
|
+
"sitemap.xml",
|
|
103
|
+
"routing-manifest.json",
|
|
104
|
+
"cdn_manifest.json",
|
|
105
|
+
"render-deps.json",
|
|
106
|
+
]);
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* `/.well-known/` names the platform answers itself: remote MCP's OAuth
|
|
110
|
+
* metadata (the load balancer routes `oauth-*` to the MCP-Auth-Proxy on gcp,
|
|
111
|
+
* CLAUDE.md §11.B) and certificate issuance.
|
|
112
|
+
*/
|
|
113
|
+
const RESERVED_WELL_KNOWN = /^(?:oauth-|openid-configuration$|acme-challenge$)/;
|
|
114
|
+
|
|
115
|
+
/** The extension of the last path segment, lower-cased, or "" when it has none. */
|
|
116
|
+
function extensionOf(path: string): string {
|
|
117
|
+
const name = path.slice(path.lastIndexOf("/") + 1);
|
|
118
|
+
const dot = name.lastIndexOf(".");
|
|
119
|
+
return dot <= 0 ? "" : name.slice(dot).toLowerCase();
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Why `path` cannot hold a static file, or null when it can. Pure: the
|
|
124
|
+
* collisions with pages, redirects and other files need data, see
|
|
125
|
+
* {@link staticFileCollisions}.
|
|
126
|
+
*/
|
|
127
|
+
export function staticFilePathIssue(path: string): string | null {
|
|
128
|
+
if (path.length > STATIC_FILE_MAX_PATH_LENGTH) {
|
|
129
|
+
return `the path is longer than ${STATIC_FILE_MAX_PATH_LENGTH} characters`;
|
|
130
|
+
}
|
|
131
|
+
if (!path.startsWith("/") || path.endsWith("/")) {
|
|
132
|
+
return 'write it as a full file path, starting with "/" and not ending in "/", like /bot/ips.json';
|
|
133
|
+
}
|
|
134
|
+
const segments = path.slice(1).split("/");
|
|
135
|
+
const first = segments[0] ?? "";
|
|
136
|
+
if (first.toLowerCase() === "api" || first.startsWith("_")) {
|
|
137
|
+
return `"/${first}" is reserved for the site's own files and services; choose another folder`;
|
|
138
|
+
}
|
|
139
|
+
if (segments.length === 1 && RESERVED_ROOT_FILES.has(first.toLowerCase())) {
|
|
140
|
+
return `"${path}" is written by every build; a static file cannot replace it`;
|
|
141
|
+
}
|
|
142
|
+
const named = first === ".well-known" ? segments.slice(1) : segments;
|
|
143
|
+
if (named.length === 0) {
|
|
144
|
+
return "name a file inside /.well-known/, like /.well-known/security.txt";
|
|
145
|
+
}
|
|
146
|
+
if (first === ".well-known" && RESERVED_WELL_KNOWN.test(named[0] ?? "")) {
|
|
147
|
+
return `"${path}" is answered by the platform itself (sign-in and certificates)`;
|
|
148
|
+
}
|
|
149
|
+
const bad = named.find((s) => !SEGMENT.test(s));
|
|
150
|
+
if (bad !== undefined) {
|
|
151
|
+
return `"${bad}" cannot be part of a path: use letters, digits, "-", "_", "." and "~", and start each part with a letter or digit (only /.well-known/ starts with a dot)`;
|
|
152
|
+
}
|
|
153
|
+
const ext = extensionOf(path);
|
|
154
|
+
if (ext !== "" && TYPES_OF_EXTENSION[ext] === undefined) {
|
|
155
|
+
return `a file ending in "${ext}" cannot be served: use ${Object.keys(TYPES_OF_EXTENSION).join(", ")} or no extension. HTML, JavaScript, CSS and SVG belong in pages and modules`;
|
|
156
|
+
}
|
|
157
|
+
return null;
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/**
|
|
161
|
+
* Why `contentType` does not fit `path`, or null. The two must agree: a
|
|
162
|
+
* host that goes by the extension then serves the declared type too. A path
|
|
163
|
+
* without an extension takes any allowed type.
|
|
164
|
+
*/
|
|
165
|
+
export function staticFileTypeIssue(path: string, contentType: string): string | null {
|
|
166
|
+
if (!(STATIC_FILE_CONTENT_TYPES as readonly string[]).includes(contentType)) {
|
|
167
|
+
return `"${contentType}" cannot be served: use one of ${STATIC_FILE_CONTENT_TYPES.join(", ")}`;
|
|
168
|
+
}
|
|
169
|
+
const ext = extensionOf(path);
|
|
170
|
+
if (ext === "") return null;
|
|
171
|
+
const allowed = TYPES_OF_EXTENSION[ext];
|
|
172
|
+
if (allowed === undefined || (allowed as readonly string[]).includes(contentType)) return null;
|
|
173
|
+
return `a path ending in "${ext}" is served as ${allowed.join(" or ")}, not ${contentType}. Change the type or the path`;
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
/** The body's size in UTF-8 bytes. */
|
|
177
|
+
export function staticFileByteLength(body: string): number {
|
|
178
|
+
return new TextEncoder().encode(body).byteLength;
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
/**
|
|
182
|
+
* Namespaces and constructs that make a browser treat an XML document as a
|
|
183
|
+
* page or run a stylesheet over it.
|
|
184
|
+
*/
|
|
185
|
+
const ACTIVE_XML =
|
|
186
|
+
/www\.w3\.org\/1999\/xhtml|www\.w3\.org\/2000\/svg|www\.w3\.org\/1998\/Math\/MathML|<\?xml-stylesheet|<!DOCTYPE|<!ENTITY/i;
|
|
187
|
+
|
|
188
|
+
/**
|
|
189
|
+
* True when an `xmlns` value is spelled with character references, which
|
|
190
|
+
* would hide the namespace from {@link ACTIVE_XML}. A scan, not a regex: the
|
|
191
|
+
* body is up to the caller, and each step resumes where the last one stopped,
|
|
192
|
+
* so the cost stays linear in the body.
|
|
193
|
+
*/
|
|
194
|
+
function hasEscapedNamespace(body: string): boolean {
|
|
195
|
+
const lower = body.toLowerCase();
|
|
196
|
+
const isSpace = (c: string | undefined): boolean =>
|
|
197
|
+
c === " " || c === "\t" || c === "\n" || c === "\r";
|
|
198
|
+
let at = lower.indexOf("xmlns");
|
|
199
|
+
while (at !== -1) {
|
|
200
|
+
let i = at + "xmlns".length;
|
|
201
|
+
if (body[i] === ":") {
|
|
202
|
+
while (i < body.length && body[i] !== "=" && !isSpace(body[i])) i += 1;
|
|
203
|
+
}
|
|
204
|
+
while (isSpace(body[i])) i += 1;
|
|
205
|
+
if (body[i] === "=") {
|
|
206
|
+
i += 1;
|
|
207
|
+
while (isSpace(body[i])) i += 1;
|
|
208
|
+
const quote = body[i];
|
|
209
|
+
if (quote === '"' || quote === "'") {
|
|
210
|
+
const end = body.indexOf(quote, i + 1);
|
|
211
|
+
const stop = end === -1 ? body.length : end;
|
|
212
|
+
const amp = body.indexOf("&", i + 1);
|
|
213
|
+
if (amp !== -1 && amp < stop) return true;
|
|
214
|
+
i = stop;
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
at = lower.indexOf("xmlns", i);
|
|
218
|
+
}
|
|
219
|
+
return false;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* Why `body` cannot be served as `contentType`, or null. Checks the size,
|
|
224
|
+
* that JSON parses, and that XML stays data (see the file header).
|
|
225
|
+
*/
|
|
226
|
+
export function staticFileBodyIssue(contentType: string, body: string): string | null {
|
|
227
|
+
if (body.length === 0) return "the file is empty";
|
|
228
|
+
const bytes = staticFileByteLength(body);
|
|
229
|
+
if (bytes > STATIC_FILE_MAX_BYTES) {
|
|
230
|
+
return `the file has ${bytes} bytes; a static file may have at most ${STATIC_FILE_MAX_BYTES} (${STATIC_FILE_MAX_BYTES / 1024} KiB)`;
|
|
231
|
+
}
|
|
232
|
+
if (body.includes("\0")) return "the file contains a NUL character, so it is not a text file";
|
|
233
|
+
if (contentType === "application/json") {
|
|
234
|
+
try {
|
|
235
|
+
JSON.parse(body);
|
|
236
|
+
} catch (e) {
|
|
237
|
+
return `the file is not valid JSON: ${e instanceof Error ? e.message : String(e)}`;
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
if (contentType === "application/xml" || contentType === "text/xml") {
|
|
241
|
+
if (ACTIVE_XML.test(body) || hasEscapedNamespace(body)) {
|
|
242
|
+
return "the XML carries a DOCTYPE, a stylesheet or an XHTML, SVG or MathML namespace, which a browser would run as a page. Send plain data XML, or build it as a page";
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
return null;
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
const withoutTrailingSlash = (path: string): string =>
|
|
249
|
+
path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
|
|
250
|
+
|
|
251
|
+
/**
|
|
252
|
+
* What stands in the way of a file at `path`, one sentence per collision. A
|
|
253
|
+
* file cannot share a URL with a page or a redirect, and because it is a
|
|
254
|
+
* real file on disk and in a bucket it cannot sit where another path needs
|
|
255
|
+
* a folder, or below another file.
|
|
256
|
+
*
|
|
257
|
+
* @param args.pagePaths URL paths of the pages (`/about`, `/about/`).
|
|
258
|
+
* @param args.redirectFromPaths URL paths that redirect.
|
|
259
|
+
* @param args.filePaths URL paths of the other static files.
|
|
260
|
+
*/
|
|
261
|
+
export function staticFileCollisions(
|
|
262
|
+
path: string,
|
|
263
|
+
args: {
|
|
264
|
+
readonly pagePaths: Iterable<string>;
|
|
265
|
+
readonly redirectFromPaths: Iterable<string>;
|
|
266
|
+
readonly filePaths: Iterable<string>;
|
|
267
|
+
},
|
|
268
|
+
): string[] {
|
|
269
|
+
const out: string[] = [];
|
|
270
|
+
for (const raw of args.pagePaths) {
|
|
271
|
+
const page = withoutTrailingSlash(raw);
|
|
272
|
+
if (page === path) out.push(`a page already serves ${path}`);
|
|
273
|
+
else if (page.startsWith(`${path}/`)) out.push(`the page ${page} sits below ${path}`);
|
|
274
|
+
}
|
|
275
|
+
for (const raw of args.redirectFromPaths) {
|
|
276
|
+
if (withoutTrailingSlash(raw) === path) out.push(`a redirect starts at ${path}`);
|
|
277
|
+
}
|
|
278
|
+
for (const other of args.filePaths) {
|
|
279
|
+
if (other === path) continue;
|
|
280
|
+
if (other.startsWith(`${path}/`)) out.push(`the file ${other} sits below ${path}`);
|
|
281
|
+
else if (path.startsWith(`${other}/`)) {
|
|
282
|
+
out.push(`the file ${other} stands where ${path} needs a folder`);
|
|
283
|
+
}
|
|
284
|
+
}
|
|
285
|
+
return out;
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
/** Zod shape of one file in a write. The rules with a message live in the functions above. */
|
|
289
|
+
export const staticFileInputSchema = z
|
|
290
|
+
.object({
|
|
291
|
+
/** Full path on the site, like `/bot/ips.json`. */
|
|
292
|
+
path: z.string().min(2).max(STATIC_FILE_MAX_PATH_LENGTH),
|
|
293
|
+
contentType: z.enum(STATIC_FILE_CONTENT_TYPES),
|
|
294
|
+
/** The file's text, UTF-8. */
|
|
295
|
+
body: z.string().min(1),
|
|
296
|
+
/** Why this file exists and who reads it (CLAUDE.md §1A). */
|
|
297
|
+
purpose: z.string().trim().min(1).max(STATIC_FILE_MAX_PURPOSE_LENGTH),
|
|
298
|
+
})
|
|
299
|
+
.strict();
|
|
300
|
+
|
|
301
|
+
/** One file in a write. */
|
|
302
|
+
export type StaticFileInput = z.infer<typeof staticFileInputSchema>;
|
|
303
|
+
|
|
304
|
+
/** Every problem of one file that needs no data, as sentences. */
|
|
305
|
+
export function staticFileIssues(file: StaticFileInput): string[] {
|
|
306
|
+
const pathIssue = staticFilePathIssue(file.path);
|
|
307
|
+
return [
|
|
308
|
+
pathIssue ?? staticFileTypeIssue(file.path, file.contentType),
|
|
309
|
+
staticFileBodyIssue(file.contentType, file.body),
|
|
310
|
+
].filter((i): i is string => i !== null);
|
|
311
|
+
}
|