Riebeckite
Menu
Color mode

Security model

Riebeckite is a static-site-oriented framework for a trusted site owner, a trusted local content repository, and trusted installed Themes and Plugins. It preserves Obsidian-compatible Markdown features, including raw HTML.

This page describes the security contract that Plugin authors and site owners should rely on.

Trust boundaries

Surface Trust level Contract
Site configuration, Theme code, and installed Plugin code Trusted site-owner controlled code May produce HTML, CSS, JavaScript, endpoints, assets, client entries, and generated files. Review Plugins like application code before installing them.
Local Markdown content and frontmatter Trusted content Markdown may contain raw HTML. Riebeckite parses and emits that HTML; it does not sanitize tags, attributes, URL schemes, inline event handlers, iframes, SVG, or scripts.
Plugin-generated article HTML, slots, and standalone page bodies Trusted generated HTML Core and HonoX render these strings into the document. Plugins must escape untrusted text and validate context-specific URLs before creating HTML.
External URLs and embed providers Context-specific external input Each Plugin owns the policy for its URL context: links, images, iframes, API endpoints, webhook sources, and diagram servers are not interchangeable.
Plugin endpoint requests Untrusted browser/network input HonoX mounts declared endpoints and snapshots request data. Endpoint handlers must validate method-specific bodies, content type, size, query values, auth, CORS, and rate limits where needed.
Browser-side data Untrusted unless it came from trusted serialized config Treat query strings, location, postMessage data, form input, and remote responses as untrusted in client code.

Markdown and HTML pipeline

The Core pipeline intentionally enables raw HTML:

  • Markdown is converted with remark-rehype using allowDangerousHtml: true.
  • Raw HTML is parsed by rehype-raw.
  • HTML is serialized with rehype-stringify using allowDangerousHtml: true.

This is not a sanitizer. It is a compatibility and authoring feature for trusted vaults. If a site builds content from untrusted users, sanitize or reject that content before it enters Riebeckite.

escapeHtml, escapeHtmlAttribute, and escapeScriptJson are escaping utilities for Plugin-generated strings. They do not make arbitrary HTML safe, and they do not validate URL schemes.

Plugin responsibilities

Plugins that generate HTML must:

  • escape text and attribute values derived from external or browser input;
  • use escapeScriptJson for JSON embedded in <script>;
  • validate URLs for the exact context where they are used;
  • avoid putting secrets in publicConfig, client entries, generated HTML, or logs;
  • validate endpoint request bodies and fail closed;
  • document any external network or browser-loaded provider they introduce.

inspectGeneratedHtml is a final-page inspection hook for diagnostics. It is not a security scanner and should not be treated as a sanitizer.

Current built-in policies

  • Rich embeds accept only https: provider URLs. Known providers are converted to controlled iframe URLs, and generic iframes require an explicit host allow-list.
  • Webmention source fetching accepts only HTTP(S), rejects credentials, limits redirects and body size, and rejects private hosts by default.
  • Analytics collector URLs must be site-relative or HTTP(S), and the Cloudflare worker integration validates JSON shape and body size.
  • Autocard metadata links and images are escaped and restricted to relative, http:, or https: URLs.
  • Diagram and media Plugins may cause the browser to load configured external providers. Treat those provider URLs as trusted configuration.

Vulnerability reporting

Please report vulnerabilities through GitHub Security Advisories or by opening a private report with enough detail to reproduce the issue. Do not include secrets, private content, or production tokens in reports.

History

1 changesCollapseExpand
1 + ---
2 + title: Security model
3 + sidebar:
4 + label: Security
5 + order: 80
6 + ---
7 + # Security model
8 +
9 + Riebeckite is a static-site-oriented framework for a trusted site owner, a trusted local content repository, and trusted installed Themes and Plugins. It preserves Obsidian-compatible Markdown features, including raw HTML.
10 +
11 + This page describes the security contract that Plugin authors and site owners should rely on.
12 +
13 + ## Trust boundaries
14 +
15 + | Surface | Trust level | Contract |
16 + | --- | --- | --- |
17 + | Site configuration, Theme code, and installed Plugin code | Trusted site-owner controlled code | May produce HTML, CSS, JavaScript, endpoints, assets, client entries, and generated files. Review Plugins like application code before installing them. |
18 + | Local Markdown content and frontmatter | Trusted content | Markdown may contain raw HTML. Riebeckite parses and emits that HTML; it does not sanitize tags, attributes, URL schemes, inline event handlers, iframes, SVG, or scripts. |
19 + | Plugin-generated article HTML, slots, and standalone page bodies | Trusted generated HTML | Core and HonoX render these strings into the document. Plugins must escape untrusted text and validate context-specific URLs before creating HTML. |
20 + | External URLs and embed providers | Context-specific external input | Each Plugin owns the policy for its URL context: links, images, iframes, API endpoints, webhook sources, and diagram servers are not interchangeable. |
21 + | Plugin endpoint requests | Untrusted browser/network input | HonoX mounts declared endpoints and snapshots request data. Endpoint handlers must validate method-specific bodies, content type, size, query values, auth, CORS, and rate limits where needed. |
22 + | Browser-side data | Untrusted unless it came from trusted serialized config | Treat query strings, location, postMessage data, form input, and remote responses as untrusted in client code. |
23 +
24 + ## Markdown and HTML pipeline
25 +
26 + The Core pipeline intentionally enables raw HTML:
27 +
28 + - Markdown is converted with `remark-rehype` using `allowDangerousHtml: true`.
29 + - Raw HTML is parsed by `rehype-raw`.
30 + - HTML is serialized with `rehype-stringify` using `allowDangerousHtml: true`.
31 +
32 + This is not a sanitizer. It is a compatibility and authoring feature for trusted vaults. If a site builds content from untrusted users, sanitize or reject that content before it enters Riebeckite.
33 +
34 + `escapeHtml`, `escapeHtmlAttribute`, and `escapeScriptJson` are escaping utilities for Plugin-generated strings. They do not make arbitrary HTML safe, and they do not validate URL schemes.
35 +
36 + ## Plugin responsibilities
37 +
38 + Plugins that generate HTML must:
39 +
40 + - escape text and attribute values derived from external or browser input;
41 + - use `escapeScriptJson` for JSON embedded in `<script>`;
42 + - validate URLs for the exact context where they are used;
43 + - avoid putting secrets in `publicConfig`, client entries, generated HTML, or logs;
44 + - validate endpoint request bodies and fail closed;
45 + - document any external network or browser-loaded provider they introduce.
46 +
47 + `inspectGeneratedHtml` is a final-page inspection hook for diagnostics. It is not a security scanner and should not be treated as a sanitizer.
48 +
49 + ## Current built-in policies
50 +
51 + - Rich embeds accept only `https:` provider URLs. Known providers are converted to controlled iframe URLs, and generic iframes require an explicit host allow-list.
52 + - Webmention source fetching accepts only HTTP(S), rejects credentials, limits redirects and body size, and rejects private hosts by default.
53 + - Analytics collector URLs must be site-relative or HTTP(S), and the Cloudflare worker integration validates JSON shape and body size.
54 + - Autocard metadata links and images are escaped and restricted to relative, `http:`, or `https:` URLs.
55 + - Diagram and media Plugins may cause the browser to load configured external providers. Treat those provider URLs as trusted configuration.
56 +
57 + ## Vulnerability reporting
58 +
59 + Please report vulnerabilities through GitHub Security Advisories or by opening a private report with enough detail to reproduce the issue. Do not include secrets, private content, or production tokens in reports.
60 +