@cube-drone/marquee-markup 0.6.0 → 0.6.1

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/README.md CHANGED
@@ -143,7 +143,11 @@ contract as `marqueeFetch`.
143
143
 
144
144
  `SiteOptions` (for `buildSite`/`buildSiteFetch`) accepts `emoji`, `emojiDefaults`,
145
145
  `colorScheme`, `envelope`, `readable`, `plugins`, and `profile` with identical meanings,
146
- applied per-page.
146
+ applied per-page. It also takes **`confineMedia`** (`boolean`, default `false`): with it on,
147
+ a relative media target that resolves *outside* the site tree — a `../` escape like
148
+ `![x](../../photos/private.jpg)` — is refused rather than copied into the output. Leave it off
149
+ for trusted content (shared-asset dirs a level up are useful); turn it on when building from
150
+ documents you don't fully trust (see "Rendering untrusted content").
147
151
 
148
152
  ## Safety, stated plainly
149
153
 
@@ -155,6 +159,26 @@ applied per-page.
155
159
  - The only code execution surface is plugin `resolve()` in the fetch functions, and only for
156
160
  plugins you composed.
157
161
 
162
+ ### Rendering untrusted content
163
+
164
+ This package is built for **trusted** content — Hugo/mdBook-style blog and book generators,
165
+ where the author is you. Rendering itself is always safe (pure, fetchless, zero-JS output). But
166
+ two boundaries reach the outside world, and both matter the moment the *author* is a stranger:
167
+
168
+ - **Never run the `*Fetch` functions on untrusted input.** Their resolve phase fetches the
169
+ document's link targets, so a hostile document is a request generator: it can aim fetches at
170
+ your internal network (`localhost`, cloud-metadata addresses — SSRF), or list thousands of
171
+ links to turn your server into a reflected-DDoS cannon against a third party. The concurrency
172
+ cap bounds *your* load, not the victim's. Use the synchronous functions (`marquee`,
173
+ `buildSite`), which never fetch — known-provider embeds (YouTube, Spotify, media-by-extension)
174
+ still render from the URL alone; stranger-page cards degrade to plain links.
175
+ - **Set `confineMedia` on untrusted `buildSite` runs.** It copies referenced media from disk, so
176
+ without confinement a `../` target could pull a media file from outside the site tree.
177
+ - **Want link previews on untrusted content anyway?** Resolve them out-of-band, in a service you
178
+ control: cache by URL (so resubmitting a document can't re-attack), cap the count per document,
179
+ deny private/link-local addresses, and rate-limit per host — then pass the results in via the
180
+ resolve map, keeping render fetchless. `resolveTargets` is that seam.
181
+
158
182
  ## Reaching deeper
159
183
 
160
184
  Everything underneath is re-exported, so outgrowing the convenience never means switching
@@ -14,6 +14,11 @@ export interface SiteOptions {
14
14
  readable?: boolean;
15
15
  /** Turbolink expanders; defaults to the fetchless default set. */
16
16
  plugins?: TurbolinkPlugin[];
17
+ /** Keep relative media inside the site tree: reject `../` escapes that would
18
+ * copy files from outside it. Off by default - buildSite is a build tool
19
+ * over your own files, and shared-asset dirs a level up are useful - so turn
20
+ * it on when building from documents you don't fully trust. */
21
+ confineMedia?: boolean;
17
22
  /** Your emoji: slug -> replacement text or `{ image, alt? }`, layered
18
23
  * over the default table (profile.emoji wins over everything). */
19
24
  emoji?: Record<string, EmojiResolution>;
@@ -12,8 +12,8 @@
12
12
  // - Fonts ship as files, and only the faces the site's pages actually use.
13
13
  // Stylesheets and fonts are real cacheable files - this is a website, not a
14
14
  // single-file page (that's what marquee() is for).
15
- import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
16
- import { basename, join, resolve } from "node:path";
15
+ import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
16
+ import { basename, isAbsolute, join, relative, resolve } from "node:path";
17
17
  import { parse } from "@cube-drone/marquee-parser";
18
18
  import { bareWebProfile, escapeText, render, usedFontTokens, } from "@cube-drone/marquee-html-renderer";
19
19
  import { marqueeCss } from "@cube-drone/marquee-css";
@@ -21,6 +21,18 @@ import { standardEmoji } from "@cube-drone/marquee-emoji";
21
21
  import { externalFontFaces, fontFilePath } from "@cube-drone/marquee-fonts";
22
22
  import { composeTurbolinks, defaultPlugins, opengraphPlugin, resolveTargets, turbolinkStyles, turbolinkTargets, } from "@cube-drone/marquee-turbolink";
23
23
  import { docIsPage, envelopeCss, metaTitle, readabilityCss } from "./index.js";
24
+ /** True if `path` is at or below `root` - never a `../` escape. Resolves
25
+ * symlinks on both (so a link inside the tree can't point out), which needs
26
+ * the path to exist; callers pair it with `existsSync`. */
27
+ function isInside(root, path) {
28
+ try {
29
+ const rel = relative(realpathSync(root), realpathSync(path));
30
+ return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
31
+ }
32
+ catch {
33
+ return false;
34
+ }
35
+ }
24
36
  /** Synchronous, fetchless site build - turbolinks with nothing gathered
25
37
  * degrade to plain links. */
26
38
  export function buildSite(siteDirArg, outDirArg, opts = {}) {
@@ -75,7 +87,12 @@ function buildSiteCore(siteDirArg, outDirArg, opts, plugins, resolved) {
75
87
  media(target) {
76
88
  if (!/^[A-Za-z][A-Za-z0-9+.-]*:/.test(target)) {
77
89
  const path = resolve(siteDir, target.split(/[?#]/, 1)[0]);
78
- if (existsSync(path)) {
90
+ // Containment (opt-in): buildSite is a trusted build tool by default,
91
+ // and pointing at shared assets a level up (`../../example-media/`,
92
+ // as the borsalino example does) is a legitimate convenience. But
93
+ // over less-than-trusted .mq a `../` escape is an info-disclosure
94
+ // foot-gun, so `confineMedia` keeps media inside the site tree.
95
+ if ((opts.confineMedia !== true || isInside(siteDir, path)) && existsSync(path)) {
79
96
  // Kind-by-extension via the default profile (dummy https host -
80
97
  // only the extension matters to it).
81
98
  const base = bareWebProfile.media(`https://local/${basename(path)}`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cube-drone/marquee-markup",
3
- "version": "0.6.0",
3
+ "version": "0.6.1",
4
4
  "description": "Marquee, batteries included: parse + render to HTML in one motion, fonts and styles along for the ride, plus the `marquee` CLI",
5
5
  "license": "MPL-2.0",
6
6
  "repository": {
@@ -38,12 +38,12 @@
38
38
  "prepack": "npm run build"
39
39
  },
40
40
  "dependencies": {
41
- "@cube-drone/marquee-css": "^0.6.0",
42
- "@cube-drone/marquee-emoji": "^0.6.0",
43
- "@cube-drone/marquee-fonts": "^0.6.0",
44
- "@cube-drone/marquee-html-renderer": "^0.6.0",
45
- "@cube-drone/marquee-parser": "^0.6.0",
46
- "@cube-drone/marquee-turbolink": "^0.6.0"
41
+ "@cube-drone/marquee-css": "^0.6.1",
42
+ "@cube-drone/marquee-emoji": "^0.6.1",
43
+ "@cube-drone/marquee-fonts": "^0.6.1",
44
+ "@cube-drone/marquee-html-renderer": "^0.6.1",
45
+ "@cube-drone/marquee-parser": "^0.6.1",
46
+ "@cube-drone/marquee-turbolink": "^0.6.1"
47
47
  },
48
48
  "devDependencies": {
49
49
  "@types/node": "^24.0.0",
package/src/build-site.ts CHANGED
@@ -13,8 +13,8 @@
13
13
  // Stylesheets and fonts are real cacheable files - this is a website, not a
14
14
  // single-file page (that's what marquee() is for).
15
15
 
16
- import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
17
- import { basename, join, resolve } from "node:path";
16
+ import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
17
+ import { basename, isAbsolute, join, relative, resolve } from "node:path";
18
18
  import { parse } from "@cube-drone/marquee-parser";
19
19
  import {
20
20
  bareWebProfile,
@@ -52,6 +52,11 @@ export interface SiteOptions {
52
52
  readable?: boolean;
53
53
  /** Turbolink expanders; defaults to the fetchless default set. */
54
54
  plugins?: TurbolinkPlugin[];
55
+ /** Keep relative media inside the site tree: reject `../` escapes that would
56
+ * copy files from outside it. Off by default - buildSite is a build tool
57
+ * over your own files, and shared-asset dirs a level up are useful - so turn
58
+ * it on when building from documents you don't fully trust. */
59
+ confineMedia?: boolean;
55
60
  /** Your emoji: slug -> replacement text or `{ image, alt? }`, layered
56
61
  * over the default table (profile.emoji wins over everything). */
57
62
  emoji?: Record<string, EmojiResolution>;
@@ -62,6 +67,18 @@ export interface SiteOptions {
62
67
  profile?: Partial<Profile>;
63
68
  }
64
69
 
70
+ /** True if `path` is at or below `root` - never a `../` escape. Resolves
71
+ * symlinks on both (so a link inside the tree can't point out), which needs
72
+ * the path to exist; callers pair it with `existsSync`. */
73
+ function isInside(root: string, path: string): boolean {
74
+ try {
75
+ const rel = relative(realpathSync(root), realpathSync(path));
76
+ return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
77
+ } catch {
78
+ return false;
79
+ }
80
+ }
81
+
65
82
  export interface SiteReport {
66
83
  pages: string[];
67
84
  mediaFiles: number;
@@ -141,7 +158,12 @@ function buildSiteCore(
141
158
  media(target) {
142
159
  if (!/^[A-Za-z][A-Za-z0-9+.-]*:/.test(target)) {
143
160
  const path = resolve(siteDir, target.split(/[?#]/, 1)[0]!);
144
- if (existsSync(path)) {
161
+ // Containment (opt-in): buildSite is a trusted build tool by default,
162
+ // and pointing at shared assets a level up (`../../example-media/`,
163
+ // as the borsalino example does) is a legitimate convenience. But
164
+ // over less-than-trusted .mq a `../` escape is an info-disclosure
165
+ // foot-gun, so `confineMedia` keeps media inside the site tree.
166
+ if ((opts.confineMedia !== true || isInside(siteDir, path)) && existsSync(path)) {
145
167
  // Kind-by-extension via the default profile (dummy https host -
146
168
  // only the extension matters to it).
147
169
  const base = bareWebProfile.media(`https://local/${basename(path)}`);