@caelo-cms/shared 0.11.9 → 0.11.11

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.
Files changed (94) hide show
  1. package/certs/aws-rds-global.pem +2888 -0
  2. package/certs/cloudsql-global.pem +1897 -0
  3. package/dist/body-cap.d.ts +35 -0
  4. package/dist/body-cap.d.ts.map +1 -0
  5. package/dist/body-cap.js +63 -0
  6. package/dist/body-cap.js.map +1 -0
  7. package/dist/change-journal.d.ts.map +1 -1
  8. package/dist/change-journal.js +3 -0
  9. package/dist/change-journal.js.map +1 -1
  10. package/dist/client-address.d.ts +69 -0
  11. package/dist/client-address.d.ts.map +1 -0
  12. package/dist/client-address.js +99 -0
  13. package/dist/client-address.js.map +1 -0
  14. package/dist/context.d.ts +8 -0
  15. package/dist/context.d.ts.map +1 -1
  16. package/dist/database-tls.d.ts +64 -0
  17. package/dist/database-tls.d.ts.map +1 -0
  18. package/dist/database-tls.js +95 -0
  19. package/dist/database-tls.js.map +1 -0
  20. package/dist/database-url.d.ts +19 -15
  21. package/dist/database-url.d.ts.map +1 -1
  22. package/dist/database-url.js +37 -1
  23. package/dist/database-url.js.map +1 -1
  24. package/dist/index.d.ts +7 -0
  25. package/dist/index.d.ts.map +1 -1
  26. package/dist/index.js +7 -0
  27. package/dist/index.js.map +1 -1
  28. package/dist/interim-forwarded-host.d.ts +15 -0
  29. package/dist/interim-forwarded-host.d.ts.map +1 -0
  30. package/dist/interim-forwarded-host.js +16 -0
  31. package/dist/interim-forwarded-host.js.map +1 -0
  32. package/dist/json-security-headers.d.ts +23 -0
  33. package/dist/json-security-headers.d.ts.map +1 -0
  34. package/dist/json-security-headers.js +53 -0
  35. package/dist/json-security-headers.js.map +1 -0
  36. package/dist/live-events.d.ts.map +1 -1
  37. package/dist/live-events.js +6 -3
  38. package/dist/live-events.js.map +1 -1
  39. package/dist/media.d.ts +8 -0
  40. package/dist/media.d.ts.map +1 -1
  41. package/dist/media.js +11 -0
  42. package/dist/media.js.map +1 -1
  43. package/dist/pool-budget.d.ts +54 -8
  44. package/dist/pool-budget.d.ts.map +1 -1
  45. package/dist/pool-budget.js +60 -8
  46. package/dist/pool-budget.js.map +1 -1
  47. package/dist/redirect-emit-gcp.d.ts +16 -8
  48. package/dist/redirect-emit-gcp.d.ts.map +1 -1
  49. package/dist/redirect-emit-gcp.js +22 -11
  50. package/dist/redirect-emit-gcp.js.map +1 -1
  51. package/dist/release-manifest.d.ts +18 -2
  52. package/dist/release-manifest.d.ts.map +1 -1
  53. package/dist/release-manifest.js +32 -4
  54. package/dist/release-manifest.js.map +1 -1
  55. package/dist/session-cookie.d.ts +88 -0
  56. package/dist/session-cookie.d.ts.map +1 -0
  57. package/dist/session-cookie.js +151 -0
  58. package/dist/session-cookie.js.map +1 -0
  59. package/dist/staging-plugin-stub.d.ts +28 -0
  60. package/dist/staging-plugin-stub.d.ts.map +1 -0
  61. package/dist/staging-plugin-stub.js +34 -0
  62. package/dist/staging-plugin-stub.js.map +1 -0
  63. package/dist/version.d.ts +2 -2
  64. package/dist/version.d.ts.map +1 -1
  65. package/dist/version.js +1 -1
  66. package/dist/version.js.map +1 -1
  67. package/package.json +2 -1
  68. package/src/body-cap.test.ts +44 -0
  69. package/src/body-cap.ts +83 -0
  70. package/src/change-journal.ts +5 -0
  71. package/src/client-address.test.ts +90 -0
  72. package/src/client-address.ts +111 -0
  73. package/src/context.ts +8 -0
  74. package/src/database-tls.test.ts +83 -0
  75. package/src/database-tls.ts +99 -0
  76. package/src/database-url.test.ts +73 -11
  77. package/src/database-url.ts +57 -1
  78. package/src/index.ts +7 -0
  79. package/src/interim-forwarded-host.ts +16 -0
  80. package/src/json-security-headers.test.ts +31 -0
  81. package/src/json-security-headers.ts +53 -0
  82. package/src/live-events.ts +6 -3
  83. package/src/media.test.ts +27 -0
  84. package/src/media.ts +13 -0
  85. package/src/pool-budget.test.ts +52 -10
  86. package/src/pool-budget.ts +82 -9
  87. package/src/redirect-emit-gcp.ts +24 -11
  88. package/src/redirect-emit.test.ts +6 -5
  89. package/src/release-manifest.ts +33 -4
  90. package/src/session-cookie.test.ts +96 -0
  91. package/src/session-cookie.ts +163 -0
  92. package/src/staging-plugin-stub.test.ts +23 -0
  93. package/src/staging-plugin-stub.ts +37 -0
  94. package/src/version.ts +1 -1
@@ -0,0 +1,151 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+ /**
3
+ * The one cookie the API gateway reads from a visitor's browser:
4
+ * `__session`, a container of named entries (#1343).
5
+ *
6
+ * ## Why one cookie, and why this name
7
+ *
8
+ * Firebase Hosting forwards exactly one cookie over a rewrite to Cloud Run,
9
+ * the one named `__session`, and strips every other
10
+ * (docs/dev/firebase-hosting-behaviour.md, section 1). On gcp-firebase a
11
+ * gateway cookie by any other name is set in the browser and never comes
12
+ * back. Every provider uses the same container (CLAUDE.md §11.B: one shape
13
+ * per tier), so no provider has a code path of its own and a site moved
14
+ * between providers keeps its visitors' state.
15
+ *
16
+ * ## Shape
17
+ *
18
+ * The cookie value is a URI-encoded `URLSearchParams` string, one parameter
19
+ * per entry: `<key>=<expiresAt>.<value>`. Known keys are in
20
+ * {@link SESSION_ENTRY}; each belongs to one owner, which writes, reads and
21
+ * verifies its own entry's value:
22
+ *
23
+ * - `vid` the visitor id (gateway, only with consent, #677)
24
+ * - `login` the visitor's login session (gateway, for the auth plugin)
25
+ * - `staging` reserved for the staging gate's session (E13 (a), #763)
26
+ *
27
+ * A component that updates one entry keeps every other entry it received,
28
+ * so entries of different owners never clash.
29
+ *
30
+ * ## What is and is not protected
31
+ *
32
+ * The container itself is not signed: `expiresAt` is metadata that sets the
33
+ * browser's Max-Age and lets the reader drop an entry that has run out.
34
+ * Changing it buys a client nothing it could not do anyway (keep or drop its
35
+ * own cookie). Every entry VALUE must carry its own integrity check, made
36
+ * and checked by its owner (the gateway HMAC-signs `vid` and `login` with
37
+ * its cookie secret and bounds their age itself).
38
+ */
39
+ /** The cookie name, the only one Firebase Hosting passes through a rewrite. */
40
+ export const SESSION_COOKIE_NAME = "__session";
41
+ /** The entries the container holds, by owner. */
42
+ export const SESSION_ENTRY = {
43
+ /** The gateway's visitor id, set only with the visitor's consent (#677). */
44
+ visitorId: "vid",
45
+ /** The gateway's signed visitor login session (auth plugin). */
46
+ login: "login",
47
+ /** Reserved for the staging gate's session cookie (E13 (a), #763). */
48
+ staging: "staging",
49
+ };
50
+ /**
51
+ * The only keys the container holds. An unknown key is visitor input with
52
+ * no owner: reading leaves it out, so the container never grows past these
53
+ * three and a gateway write can never overflow it (PR #1354 review). A new
54
+ * owner adds its key to {@link SESSION_ENTRY}.
55
+ */
56
+ const KNOWN_KEYS = new Set(Object.values(SESSION_ENTRY));
57
+ /** Values the entries' owners write: signed tokens, no separators of ours. */
58
+ const ENTRY_VALUE = /^[A-Za-z0-9._~-]{1,512}$/;
59
+ /** The raw `__session` value of a `Cookie` header, or null. */
60
+ function rawSessionCookie(cookieHeader) {
61
+ if (!cookieHeader)
62
+ return null;
63
+ for (const part of cookieHeader.split(/;\s*/)) {
64
+ const eq = part.indexOf("=");
65
+ if (eq > 0 && part.slice(0, eq).trim() === SESSION_COOKIE_NAME) {
66
+ return part.slice(eq + 1).trim();
67
+ }
68
+ }
69
+ return null;
70
+ }
71
+ /**
72
+ * Parse the request's `__session` container.
73
+ *
74
+ * Visitor-controlled input: a malformed container, entry or value, a key
75
+ * not in {@link SESSION_ENTRY} and a repeated key are left out rather than
76
+ * failing the request, and an entry past its `expiresAt` is left out too.
77
+ * The caller still verifies each value it uses.
78
+ *
79
+ * @param cookieHeader the request's `Cookie` header.
80
+ * @param nowSeconds the current time, unix seconds.
81
+ */
82
+ export function readSessionCookie(cookieHeader, nowSeconds) {
83
+ const out = new Map();
84
+ const raw = rawSessionCookie(cookieHeader);
85
+ if (!raw)
86
+ return out;
87
+ let decoded;
88
+ try {
89
+ decoded = decodeURIComponent(raw);
90
+ }
91
+ catch {
92
+ return out;
93
+ }
94
+ for (const [key, entry] of new URLSearchParams(decoded)) {
95
+ if (!KNOWN_KEYS.has(key) || out.has(key))
96
+ continue;
97
+ const dot = entry.indexOf(".");
98
+ const expRaw = entry.slice(0, dot);
99
+ const value = entry.slice(dot + 1);
100
+ if (dot <= 0 || !/^\d{1,12}$/.test(expRaw) || !ENTRY_VALUE.test(value))
101
+ continue;
102
+ const expiresAt = Number(expRaw);
103
+ if (expiresAt <= nowSeconds)
104
+ continue;
105
+ out.set(key, { value, expiresAt });
106
+ }
107
+ return out;
108
+ }
109
+ /**
110
+ * Serialise entries into a `__session` cookie value (URI-encoded).
111
+ *
112
+ * @throws on a key or value {@link readSessionCookie} would not read back:
113
+ * an owner writing one is a bug, not visitor input.
114
+ */
115
+ export function sessionCookieValue(entries) {
116
+ const params = new URLSearchParams();
117
+ for (const [key, e] of [...entries].sort(([a], [b]) => a.localeCompare(b))) {
118
+ if (!KNOWN_KEYS.has(key))
119
+ throw new Error(`session cookie: unknown entry key "${key}"`);
120
+ if (!ENTRY_VALUE.test(e.value))
121
+ throw new Error(`session cookie: invalid value for "${key}"`);
122
+ if (!Number.isInteger(e.expiresAt) || e.expiresAt <= 0) {
123
+ throw new Error(`session cookie: invalid expiresAt for "${key}"`);
124
+ }
125
+ params.append(key, `${e.expiresAt}.${e.value}`);
126
+ }
127
+ return encodeURIComponent(params.toString());
128
+ }
129
+ /**
130
+ * The `Set-Cookie` header that stores `entries` as the `__session`
131
+ * container, or expires it when no entry is left.
132
+ *
133
+ * HttpOnly and SameSite=Lax always; Secure when `secure` (every deployed
134
+ * environment — plain-http local development cannot keep a Secure cookie).
135
+ * Max-Age follows the longest-lived entry.
136
+ */
137
+ export function sessionSetCookieHeader(entries, opts) {
138
+ const flags = entries.size === 0
139
+ ? [`${SESSION_COOKIE_NAME}=`, "Path=/", "HttpOnly", "SameSite=Lax", "Max-Age=0"]
140
+ : [
141
+ `${SESSION_COOKIE_NAME}=${sessionCookieValue(entries)}`,
142
+ "Path=/",
143
+ "HttpOnly",
144
+ "SameSite=Lax",
145
+ `Max-Age=${Math.max(1, Math.max(...[...entries.values()].map((e) => e.expiresAt)) - opts.nowSeconds)}`,
146
+ ];
147
+ if (opts.secure)
148
+ flags.push("Secure");
149
+ return flags.join("; ");
150
+ }
151
+ //# sourceMappingURL=session-cookie.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"session-cookie.js","sourceRoot":"","sources":["../src/session-cookie.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,28 @@
1
+ /**
2
+ * What a staged page's plugin call gets until staging has its own gateway
3
+ * (#1326 interim, #1329/#1330; epic #763 N4).
4
+ *
5
+ * The live gateway takes plugin posts only from a live-site Origin, and
6
+ * staging is never one: unreviewed module JS on staging must not write
7
+ * into live data. A plain 403 would make every staged page with a plugin
8
+ * component log "Failed to load resource" in the browser console, which the
9
+ * Stage quality audit counts as a page error and which would then block
10
+ * Publish live. So the two places a staged page's `/api/plugin/*` call can
11
+ * reach answer it with this instead, without dispatching anything:
12
+ *
13
+ * - the API gateway, for a POST whose Origin is the staging host
14
+ * (gcp-firebase, self-hosted: staging's `/api` reaches the live gateway);
15
+ * - the audit's loopback origin (admin-core `quality/staged-origin.ts`,
16
+ * gcp / aws / azure), which no longer forwards plugin calls to live.
17
+ *
18
+ * HTTP 200 with `ok: false`: the browser logs nothing, and the component
19
+ * takes its ordinary "no data" / "failed" path (plugin-component-kit
20
+ * `postPluginJson` callers all read `ok`).
21
+ */
22
+ /** The error kind a staged page's plugin call answers with. */
23
+ export declare const STAGING_PREVIEW_ERROR_KIND = "StagingPreview";
24
+ /** The JSON body of that answer. */
25
+ export declare const STAGING_PLUGIN_STUB_BODY: string;
26
+ /** Whether `pathname` is a plugin operation call (`/api/plugin/…`). */
27
+ export declare function isPluginCallPath(pathname: string): boolean;
28
+ //# sourceMappingURL=staging-plugin-stub.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"staging-plugin-stub.d.ts","sourceRoot":"","sources":["../src/staging-plugin-stub.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,+DAA+D;AAC/D,eAAO,MAAM,0BAA0B,mBAAmB,CAAC;AAE3D,oCAAoC;AACpC,eAAO,MAAM,wBAAwB,QAGnC,CAAC;AAEH,uEAAuE;AACvE,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE1D"}
@@ -0,0 +1,34 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+ /**
3
+ * What a staged page's plugin call gets until staging has its own gateway
4
+ * (#1326 interim, #1329/#1330; epic #763 N4).
5
+ *
6
+ * The live gateway takes plugin posts only from a live-site Origin, and
7
+ * staging is never one: unreviewed module JS on staging must not write
8
+ * into live data. A plain 403 would make every staged page with a plugin
9
+ * component log "Failed to load resource" in the browser console, which the
10
+ * Stage quality audit counts as a page error and which would then block
11
+ * Publish live. So the two places a staged page's `/api/plugin/*` call can
12
+ * reach answer it with this instead, without dispatching anything:
13
+ *
14
+ * - the API gateway, for a POST whose Origin is the staging host
15
+ * (gcp-firebase, self-hosted: staging's `/api` reaches the live gateway);
16
+ * - the audit's loopback origin (admin-core `quality/staged-origin.ts`,
17
+ * gcp / aws / azure), which no longer forwards plugin calls to live.
18
+ *
19
+ * HTTP 200 with `ok: false`: the browser logs nothing, and the component
20
+ * takes its ordinary "no data" / "failed" path (plugin-component-kit
21
+ * `postPluginJson` callers all read `ok`).
22
+ */
23
+ /** The error kind a staged page's plugin call answers with. */
24
+ export const STAGING_PREVIEW_ERROR_KIND = "StagingPreview";
25
+ /** The JSON body of that answer. */
26
+ export const STAGING_PLUGIN_STUB_BODY = JSON.stringify({
27
+ ok: false,
28
+ error: { kind: STAGING_PREVIEW_ERROR_KIND },
29
+ });
30
+ /** Whether `pathname` is a plugin operation call (`/api/plugin/…`). */
31
+ export function isPluginCallPath(pathname) {
32
+ return pathname.startsWith("/api/plugin/");
33
+ }
34
+ //# sourceMappingURL=staging-plugin-stub.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"staging-plugin-stub.js","sourceRoot":"","sources":["../src/staging-plugin-stub.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,+DAA+D;AAC/D,MAAM,CAAC,MAAM,0BAA0B,GAAG,gBAAgB,CAAC;AAE3D,oCAAoC;AACpC,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC,SAAS,CAAC;IACrD,EAAE,EAAE,KAAK;IACT,KAAK,EAAE,EAAE,IAAI,EAAE,0BAA0B,EAAE;CAC5C,CAAC,CAAC;AAEH,uEAAuE;AACvE,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,OAAO,QAAQ,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AAC7C,CAAC"}
package/dist/version.d.ts CHANGED
@@ -19,7 +19,7 @@
19
19
  * Format: SemVer 2.0.0. Pre-1.0 minor bumps are breaking; post-1.0
20
20
  * follow standard SemVer.
21
21
  */
22
- export declare const CAELO_VERSION = "0.11.9";
22
+ export declare const CAELO_VERSION = "0.11.11";
23
23
  /**
24
24
  * Deprecated alias for back-compat — early P17 work spelled this
25
25
  * `CALEO_VERSION` (typo of "Caelo"). New code should import
@@ -31,7 +31,7 @@ export declare const CAELO_VERSION = "0.11.9";
31
31
  *
32
32
  * @deprecated use CAELO_VERSION
33
33
  */
34
- export declare const CALEO_VERSION = "0.11.9";
34
+ export declare const CALEO_VERSION = "0.11.11";
35
35
  /**
36
36
  * Parsed shape — major/minor/patch + optional pre-release tag.
37
37
  * Stable interface for callers that need to feature-gate (rare —
@@ -1 +1 @@
1
- {"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,eAAO,MAAM,aAAa,WAAW,CAAC;AAEtC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,WAAgB,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAsB,GAAG,YAAY,CAYtE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAkBvE"}
1
+ {"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,eAAO,MAAM,aAAa,YAAY,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,YAAgB,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAsB,GAAG,YAAY,CAYtE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAkBvE"}
package/dist/version.js CHANGED
@@ -20,7 +20,7 @@
20
20
  * Format: SemVer 2.0.0. Pre-1.0 minor bumps are breaking; post-1.0
21
21
  * follow standard SemVer.
22
22
  */
23
- export const CAELO_VERSION = "0.11.9";
23
+ export const CAELO_VERSION = "0.11.11";
24
24
  /**
25
25
  * Deprecated alias for back-compat — early P17 work spelled this
26
26
  * `CALEO_VERSION` (typo of "Caelo"). New code should import
@@ -1 +1 @@
1
- {"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG,QAAQ,CAAC;AAEtC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAC;AAgB3C,MAAM,UAAU,YAAY,CAAC,MAAc,aAAa;IACtD,MAAM,CAAC,GAAG,iCAAiC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtD,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,EAAE,CAAC,CAAC;IACnD,CAAC;IACD,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC;QACvC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC;QACvC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC;QACvC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI;QACxB,GAAG;KACJ,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,OAAe;IAC5D,MAAM,KAAK,GAAG,CAAC,CAAS,EAAuB,EAAE;QAC/C,IAAI,CAAC;YACH,OAAO,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC,CAAC;IACF,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IACzB,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAU,EAAE,CAAC;QACrD,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,UAAU;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAC/C,IAAI,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,UAAU;QAAE,OAAO,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC;IACrE,OAAO,KAAK,CAAC;AACf,CAAC"}
1
+ {"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAC;AAgB3C,MAAM,UAAU,YAAY,CAAC,MAAc,aAAa;IACtD,MAAM,CAAC,GAAG,iCAAiC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtD,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,EAAE,CAAC,CAAC;IACnD,CAAC;IACD,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC;QACvC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC;QACvC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC;QACvC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI;QACxB,GAAG;KACJ,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,OAAe;IAC5D,MAAM,KAAK,GAAG,CAAC,CAAS,EAAuB,EAAE;QAC/C,IAAI,CAAC;YACH,OAAO,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC,CAAC;IACF,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IACzB,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAU,EAAE,CAAC;QACrD,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,UAAU;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAC/C,IAAI,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,UAAU;QAAE,OAAO,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC;IACrE,OAAO,KAAK,CAAC;AACf,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@caelo-cms/shared",
3
- "version": "0.11.9",
3
+ "version": "0.11.11",
4
4
  "private": false,
5
5
  "license": "MPL-2.0",
6
6
  "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.",
@@ -33,6 +33,7 @@
33
33
  "files": [
34
34
  "dist/",
35
35
  "src/",
36
+ "certs/",
36
37
  "README.md",
37
38
  "package.json"
38
39
  ],
@@ -0,0 +1,44 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+
3
+ /** readBodyWithCap stops at the first byte over the cap and never exceeds the hard ceiling. */
4
+
5
+ import { describe, expect, it } from "bun:test";
6
+ import { HARD_MAX_BODY_BYTES, readBodyWithCap } from "./body-cap.js";
7
+
8
+ function post(body: BodyInit, headers: Record<string, string> = {}): Request {
9
+ return new Request("http://service.internal/x", { method: "POST", body, headers });
10
+ }
11
+
12
+ describe("readBodyWithCap", () => {
13
+ it("returns a body within the cap", async () => {
14
+ const r = await readBodyWithCap(post("hello"), 10);
15
+ expect(r.ok).toBe(true);
16
+ if (r.ok) expect(new TextDecoder().decode(r.body)).toBe("hello");
17
+ });
18
+
19
+ it("refuses a declared Content-Length over the cap without reading", async () => {
20
+ const r = await readBodyWithCap(post("x", { "content-length": "999" }), 10);
21
+ expect(r).toEqual({ ok: false, bytes: 999, limit: 10 });
22
+ });
23
+
24
+ it("refuses a streamed body that grows over the cap", async () => {
25
+ const stream = new ReadableStream<Uint8Array>({
26
+ start(c) {
27
+ c.enqueue(new Uint8Array(8));
28
+ c.enqueue(new Uint8Array(8));
29
+ c.close();
30
+ },
31
+ });
32
+ const r = await readBodyWithCap(post(stream), 10);
33
+ expect(r.ok).toBe(false);
34
+ });
35
+
36
+ it("clamps a caller's cap to the hard ceiling", async () => {
37
+ const declared = String(HARD_MAX_BODY_BYTES + 1);
38
+ const r = await readBodyWithCap(
39
+ post("x", { "content-length": declared }),
40
+ HARD_MAX_BODY_BYTES * 4,
41
+ );
42
+ expect(r).toEqual({ ok: false, bytes: HARD_MAX_BODY_BYTES + 1, limit: HARD_MAX_BODY_BYTES });
43
+ });
44
+ });
@@ -0,0 +1,83 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+
3
+ /**
4
+ * P13 — request body size cap, shared by the public services (the visitor
5
+ * gateway and the MCP-Auth-Proxy's OAuth endpoints). Pure Web APIs.
6
+ *
7
+ * Default 64 KB ceiling; the gateway's per-plugin manifest override
8
+ * (`gateway.maxBodyBytes`) can raise it up to a 1 MB hard ceiling. Handlers
9
+ * don't need to worry about hostile payloads — anything over the cap is
10
+ * rejected before they see it.
11
+ *
12
+ * Bun's `req.text()` / `req.json()` will happily buffer multi-MB bodies;
13
+ * we instead read the stream manually with a running counter so the
14
+ * connection short-circuits at the first byte over the cap.
15
+ */
16
+
17
+ /** Cap applied when the caller names none. */
18
+ export const DEFAULT_MAX_BODY_BYTES = 64 * 1024;
19
+ /** No caller may raise the cap above this. */
20
+ export const HARD_MAX_BODY_BYTES = 1024 * 1024;
21
+
22
+ /** The body, read in full within the cap. */
23
+ export interface BodyCapResult {
24
+ readonly ok: true;
25
+ readonly body: ArrayBuffer;
26
+ readonly bytes: number;
27
+ }
28
+
29
+ /** The body went over the cap; reading stopped there. */
30
+ export interface BodyCapTooLarge {
31
+ readonly ok: false;
32
+ readonly bytes: number;
33
+ readonly limit: number;
34
+ }
35
+
36
+ /**
37
+ * Read req.body up to `limit` bytes. If the body exceeds the limit, abort
38
+ * the read and return `{ok: false}` so the handler can emit 413.
39
+ */
40
+ export async function readBodyWithCap(
41
+ req: Request,
42
+ limit: number = DEFAULT_MAX_BODY_BYTES,
43
+ ): Promise<BodyCapResult | BodyCapTooLarge> {
44
+ const cap = Math.min(limit, HARD_MAX_BODY_BYTES);
45
+ // Cheap pre-check on Content-Length when present.
46
+ const contentLength = req.headers.get("content-length");
47
+ if (contentLength) {
48
+ const declared = Number.parseInt(contentLength, 10);
49
+ if (Number.isFinite(declared) && declared > cap) {
50
+ return { ok: false, bytes: declared, limit: cap };
51
+ }
52
+ }
53
+
54
+ if (!req.body) {
55
+ return { ok: true, body: new ArrayBuffer(0), bytes: 0 };
56
+ }
57
+
58
+ const reader = req.body.getReader();
59
+ const chunks: Uint8Array[] = [];
60
+ let total = 0;
61
+ try {
62
+ while (true) {
63
+ const { done, value } = await reader.read();
64
+ if (done) break;
65
+ total += value.byteLength;
66
+ if (total > cap) {
67
+ await reader.cancel(); // signal upstream to stop sending
68
+ return { ok: false, bytes: total, limit: cap };
69
+ }
70
+ chunks.push(value);
71
+ }
72
+ } finally {
73
+ reader.releaseLock();
74
+ }
75
+
76
+ const buf = new Uint8Array(total);
77
+ let offset = 0;
78
+ for (const c of chunks) {
79
+ buf.set(c, offset);
80
+ offset += c.byteLength;
81
+ }
82
+ return { ok: true, body: buf.buffer as ArrayBuffer, bytes: total };
83
+ }
@@ -287,11 +287,16 @@ export const JOURNAL_EXEMPT_TABLES: Readonly<Record<string, string>> = {
287
287
  plugin_private_file_chunks:
288
288
  "the bytes of plugin_private_files rows, journaled through the file row",
289
289
  public_projection_outbox: "the outbox of the cms_public projection, drained by its publisher",
290
+ projection_releases:
291
+ "#1329: the frozen release state of a deploy run, written once by the deploy ops and read only by the projection publisher",
292
+ projection_release_pointers:
293
+ "#1329: which frozen release each public database serves, moved by the deploy ops; a move marks the projection's outbox",
290
294
  platform_update_agent: RUNTIME,
291
295
  platform_update_notifications: RUNTIME,
292
296
  platform_update_policy: "the Owner's update policy, read by the update scheduler",
293
297
  platform_update_requests: "update requests, run by the upgrader job",
294
298
  platform_update_scheduler: RUNTIME,
299
+ scheduled_tasks: RUNTIME,
295
300
 
296
301
  import_runs: "site-import runs; reach editors as the op-classified `crawl` topic",
297
302
  import_pages: "crawled pages of a site import, before they become pages",
@@ -0,0 +1,90 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+
3
+ /**
4
+ * The visitor's address per deployment topology (client-address.ts). Each case
5
+ * builds X-Forwarded-For the way the provider's proxies do: whatever the
6
+ * client sent, then the entries the infrastructure appends.
7
+ */
8
+
9
+ import { describe, expect, it } from "bun:test";
10
+ import {
11
+ ClientAddressError,
12
+ clientAddress,
13
+ forwardedClientIp,
14
+ TRUSTED_PROXY_HOPS_ENV,
15
+ trustedProxyHopsFromEnv,
16
+ } from "./client-address.js";
17
+
18
+ const VISITOR = "198.51.100.7";
19
+ const FORGED = "6.6.6.6";
20
+
21
+ function req(xff?: string): Request {
22
+ return new Request("http://gateway.internal/api/plugin/x/y", {
23
+ headers: xff === undefined ? {} : { "x-forwarded-for": xff },
24
+ });
25
+ }
26
+
27
+ describe("trustedProxyHopsFromEnv", () => {
28
+ it("reads a non-negative integer", () => {
29
+ expect(trustedProxyHopsFromEnv({ [TRUSTED_PROXY_HOPS_ENV]: "2" })).toBe(2);
30
+ expect(trustedProxyHopsFromEnv({ [TRUSTED_PROXY_HOPS_ENV]: "0" })).toBe(0);
31
+ });
32
+
33
+ it("refuses a missing value instead of picking one, naming the fix", () => {
34
+ expect(() => trustedProxyHopsFromEnv({})).toThrow(ClientAddressError);
35
+ expect(() => trustedProxyHopsFromEnv({})).toThrow(/cms-provision upgrade/);
36
+ expect(() => trustedProxyHopsFromEnv({ [TRUSTED_PROXY_HOPS_ENV]: " " })).toThrow(
37
+ ClientAddressError,
38
+ );
39
+ });
40
+
41
+ it("refuses anything but a non-negative integer", () => {
42
+ for (const bad of ["-1", "1.5", "two", "2x"]) {
43
+ expect(() => trustedProxyHopsFromEnv({ [TRUSTED_PROXY_HOPS_ENV]: bad })).toThrow(
44
+ /not a non-negative integer/,
45
+ );
46
+ }
47
+ });
48
+ });
49
+
50
+ describe("forwardedClientIp", () => {
51
+ it("counts from the end and trims", () => {
52
+ expect(forwardedClientIp(`${FORGED} , ${VISITOR},34.1.2.3`, 2)).toBe(VISITOR);
53
+ expect(forwardedClientIp(VISITOR, 1)).toBe(VISITOR);
54
+ });
55
+
56
+ it("is null when the header is shorter than the hop count, or absent", () => {
57
+ expect(forwardedClientIp(VISITOR, 2)).toBeNull();
58
+ expect(forwardedClientIp(null, 1)).toBeNull();
59
+ expect(forwardedClientIp("", 1)).toBeNull();
60
+ expect(forwardedClientIp(VISITOR, 0)).toBeNull();
61
+ });
62
+ });
63
+
64
+ describe("clientAddress per topology", () => {
65
+ it("gcp — the LB appends <client>,<LB IP>: the visitor, never the LB, never a forged entry", () => {
66
+ const lb = "34.120.0.1";
67
+ expect(clientAddress(req(`${VISITOR}, ${lb}`), 2, null)).toBe(VISITOR);
68
+ // A client-sent header stays in front of what the LB appends.
69
+ expect(clientAddress(req(`${FORGED}, ${VISITOR}, ${lb}`), 2, null)).toBe(VISITOR);
70
+ // Two visitors behind the same LB stay apart (the last-hop rule pooled them).
71
+ expect(clientAddress(req(`203.0.113.9, ${lb}`), 2, null)).not.toBe(
72
+ clientAddress(req(`${VISITOR}, ${lb}`), 2, null),
73
+ );
74
+ });
75
+
76
+ it("gcp-firebase / self-hosted / azure — one appended entry: forged prefixes are ignored", () => {
77
+ expect(clientAddress(req(VISITOR), 1, null)).toBe(VISITOR);
78
+ expect(clientAddress(req(`${FORGED}, ${VISITOR}`), 1, null)).toBe(VISITOR);
79
+ });
80
+
81
+ it("no proxy (local dev) — the TCP peer, whatever the header says", () => {
82
+ expect(clientAddress(req(FORGED), 0, VISITOR)).toBe(VISITOR);
83
+ expect(() => clientAddress(req(), 0, null)).toThrow(ClientAddressError);
84
+ });
85
+
86
+ it("fails loudly when a request lacks what the topology always appends", () => {
87
+ expect(() => clientAddress(req(VISITOR), 2, null)).toThrow(/fewer than 2 X-Forwarded-For/);
88
+ expect(() => clientAddress(req(), 1, VISITOR)).toThrow(ClientAddressError);
89
+ });
90
+ });
@@ -0,0 +1,111 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+
3
+ /**
4
+ * The client's address, as the infrastructure in front of a public service
5
+ * vouches for it — one rule for every Caelo service that faces the internet
6
+ * (the visitor data gateway, apps/api-gateway; the MCP-Auth-Proxy,
7
+ * apps/mcp-auth-proxy). Pure Web APIs, no runtime dependency.
8
+ *
9
+ * Every proxy on the path APPENDS to `X-Forwarded-For`; everything before
10
+ * the entries our own infrastructure appended came from the client and can
11
+ * be forged. So the client address is not "the first entry" (forgeable) and
12
+ * not blindly "the last entry" either (behind a load balancer that is the
13
+ * load balancer, for every client): it is the entry `hops` places from the
14
+ * end, where `hops` is how many entries the deployment's proxies append,
15
+ * counting the client's own. That number is a property of the topology in
16
+ * front of each service, so the provisioner sets it per provider and service
17
+ * (`CAELO_TRUSTED_PROXY_HOPS`, packages/provisioning/src/stack-contract.ts):
18
+ *
19
+ * - gcp: external Application LB appends `<client>,<LB IP>` and
20
+ * the service's ingress is internal-and-LB only → 2.
21
+ * - gcp-firebase: Cloud Run's front end appends the address it got the
22
+ * connection from → 1 (behind the Firebase Hosting
23
+ * rewrite that is the Hosting CDN edge, see the gateway's
24
+ * client-ip.ts).
25
+ * - self-hosted: Caddy (no `trusted_proxies`) replaces the header with
26
+ * the peer address; the service is reachable only on the
27
+ * Compose network → 1.
28
+ * - azure: Container Apps ingress appends the peer → 1.
29
+ * - 0: nothing in front (local dev): the TCP peer address.
30
+ *
31
+ * The MCP-Auth-Proxy is reached the same way as the gateway on every
32
+ * provider (on gcp-firebase directly on its run.app URL, on gcp through the
33
+ * load balancer), so the same counts apply to it.
34
+ */
35
+
36
+ /** The env var carrying the deployment's trusted proxy hop count. */
37
+ export const TRUSTED_PROXY_HOPS_ENV = "CAELO_TRUSTED_PROXY_HOPS";
38
+
39
+ /**
40
+ * The service cannot tell who the client is: the hop count is missing or
41
+ * invalid, or a request arrived with fewer forwarded entries than the
42
+ * deployment's proxies always append. Both are deployment errors; the
43
+ * message names the fix.
44
+ */
45
+ export class ClientAddressError extends Error {
46
+ override readonly name = "ClientAddressError";
47
+ }
48
+
49
+ /**
50
+ * The trusted proxy hop count from `env`.
51
+ *
52
+ * @throws ClientAddressError when it is unset or not a non-negative integer —
53
+ * guessing would either pool every client into one rate-limit bucket or
54
+ * let a client pick its own.
55
+ */
56
+ export function trustedProxyHopsFromEnv(env: Readonly<Record<string, string | undefined>>): number {
57
+ const raw = env[TRUSTED_PROXY_HOPS_ENV];
58
+ if (raw === undefined || raw.trim() === "") {
59
+ throw new ClientAddressError(
60
+ `${TRUSTED_PROXY_HOPS_ENV} is not set, so this service cannot tell which X-Forwarded-For entry is the client. Cloud and self-hosted installs: run \`cms-provision upgrade\` (the provisioner sets it per provider). Local dev without a proxy: set it to 0.`,
61
+ );
62
+ }
63
+ if (!/^\d+$/.test(raw.trim())) {
64
+ throw new ClientAddressError(
65
+ `${TRUSTED_PROXY_HOPS_ENV}="${raw}" is not a non-negative integer (the number of X-Forwarded-For entries the proxies in front of this service append, counting the client's).`,
66
+ );
67
+ }
68
+ return Number.parseInt(raw.trim(), 10);
69
+ }
70
+
71
+ /**
72
+ * The entry `hops` places from the end of `xForwardedFor` (1 = the last), or
73
+ * null when the header has fewer entries than that.
74
+ *
75
+ * @example
76
+ * forwardedClientIp("6.6.6.6, 198.51.100.7, 34.1.2.3", 2) // → "198.51.100.7"
77
+ */
78
+ export function forwardedClientIp(xForwardedFor: string | null, hops: number): string | null {
79
+ if (hops < 1 || !xForwardedFor) return null;
80
+ const entries = xForwardedFor
81
+ .split(",")
82
+ .map((s) => s.trim())
83
+ .filter(Boolean);
84
+ return entries[entries.length - hops] ?? null;
85
+ }
86
+
87
+ /**
88
+ * The client address of `req` under `hops`.
89
+ *
90
+ * @param peerAddress the TCP peer (Bun `server.requestIP`); used only when
91
+ * `hops` is 0.
92
+ * @throws ClientAddressError when the request does not carry what the
93
+ * configured topology always adds.
94
+ */
95
+ export function clientAddress(req: Request, hops: number, peerAddress: string | null): string {
96
+ if (hops === 0) {
97
+ if (!peerAddress) {
98
+ throw new ClientAddressError(
99
+ `${TRUSTED_PROXY_HOPS_ENV}=0 (no proxy) but the connection's peer address is unknown.`,
100
+ );
101
+ }
102
+ return peerAddress;
103
+ }
104
+ const ip = forwardedClientIp(req.headers.get("x-forwarded-for"), hops);
105
+ if (!ip) {
106
+ throw new ClientAddressError(
107
+ `the request carries fewer than ${hops} X-Forwarded-For entries, but ${TRUSTED_PROXY_HOPS_ENV}=${hops} says the proxies in front of this service always append that many. Either a request reached the service around its proxy, or ${TRUSTED_PROXY_HOPS_ENV} does not match the deployment.`,
108
+ );
109
+ }
110
+ return ip;
111
+ }
package/src/context.ts CHANGED
@@ -37,6 +37,14 @@ export interface ExecutionContext {
37
37
  * only while exactly this artifact is the active, granted one.
38
38
  */
39
39
  readonly pluginArtifactDigest?: string;
40
+ /**
41
+ * #650 — the public origin of the static build a plugin's render-time
42
+ * call belongs to. `pages.resolve_public_urls` builds URLs on it
43
+ * instead of the stored site base URL, so a Stage with its own staging
44
+ * host gets staging URLs from plugins too. Set by the plugin host from
45
+ * the render invocation only.
46
+ */
47
+ readonly renderSiteBaseUrl?: string;
40
48
  /**
41
49
  * P10.5: parent attribution for subagent invocations. When the
42
50
  * `spawn_subagent` tool calls runChatTurn for the child, it carries