@guard-rail/core 0.10.0 → 0.11.0

package/README.md

@@ -496,6 +496,54 @@ the outline ignores the pointer so your overlaid content stays fully clickable,
 and the handle is the only thing that opens the editor (it also won't trigger a
 surrounding `<Link>`).
 
+### Theming
+
+The chrome is a real stylesheet (`guardrail.css`) that the package imports itself —
+there is nothing to link by hand, and no inline styles, so it works under a strict
+Content-Security-Policy. Every color is a CSS variable, so restyling it is a plain
+`:root` rule in your own CSS:
+
+```css
+:root {
+  --gr-accent: #7c3aed;
+  --gr-field-outline: #7c3aed;
+  --gr-overlay-bg: #1e1b4b;
+  --gr-overlay-fg: #e0e7ff;
+}
+```
+
+No `!important` and no selector tricks: Guardrail's defaults are declared with zero
+specificity, so your `:root` rule wins whichever stylesheet loads first.
+
+There are two layers. Change a **base** color to retheme everything, or set an
+**overlay** color to restyle only the floating surfaces (the sign-in bar, toolbar,
+edit popups, drawers and image picker). The overlay variables default to the base
+ones, so you only set what you want to differ.
+
+| Variable | What it colors |
+|---|---|
+| `--gr-overlay-bg` | Background of the sign-in bar, popups, drawers and picker |
+| `--gr-overlay-bg-glass` | Background of the toolbar and the inline editing bar (translucent) |
+| `--gr-overlay-fg` | Text on all of the above |
+| `--gr-overlay-border` | Their borders |
+| `--gr-field-outline` | The dashed outline around an editable field |
+| `--gr-field-outline-active` | The solid outline while a field is being edited |
+| `--gr-accent`, `--gr-accent-soft`, `--gr-accent-text`, `--gr-on-accent` | Highlights, and text on an accent background |
+| `--gr-primary-bg`, `--gr-primary-fg` | Primary buttons |
+| `--gr-danger`, `--gr-label`, `--gr-badge-bg`, `--gr-badge-fg` | Errors, small labels, the "pending" badge |
+| `--gr-scrim`, `--gr-scrim-modal` | The dimmed backdrop behind drawers and the picker |
+| `--gr-bg`, `--gr-bg-glass`, `--gr-fg`, `--gr-fg2`, `--gr-muted`, `--gr-subtle`, `--gr-border`, `--gr-border-strong`, `--gr-border-soft`, `--gr-input-bg`, `--gr-soft`, `--gr-shadow` | The base palette the overlay variables fall back to, plus inputs and secondary text |
+
+Set any of them inside `@media (prefers-color-scheme: dark)` if you want a
+different value in dark mode — the chrome follows the visitor's OS setting. The
+outline around an editable text field is `[data-gr-field="text"]` (and
+`[data-gr-editing]` while it's being edited), so you can restyle or hide it with a
+rule of your own; to hide it, set `--gr-field-outline: transparent`. Every class
+Guardrail adds is prefixed `gr-`.
+
+If your setup doesn't bundle CSS imported from a package, import it yourself once,
+in your root layout: `import "@guard-rail/core/styles.css";`.
+
 ## Extending the toolbar
 
 The bundled toolbar (edit indicator, Team, Exit edit mode) has one extension point:
@@ -618,8 +666,9 @@ By default it only reads. It checks:
 | Flag | What it adds |
 |---|---|
 | `--fix` | Repairs what can be repaired in local files: copies missing migrations, adds a `GUARDRAIL_SITE_URL` note to `.env.example` / `.env.local`, adds baseline security headers to `next.config`. It never changes secrets or Supabase dashboard settings, and re-running it is safe. Add `--push` to also run `supabase db push`. |
-| `--app-url=http://localhost:3000` | Also checks the response headers of a running copy of your site. |
+| `--app-url=http://localhost:3000` | Also checks the response headers of a running copy of your site, including that Guardrail's stylesheet reached the page and that its Content-Security-Policy lets Guardrail's uploads and images through. |
 | `--e2e` | Runs an end-to-end suite against the database. It creates a throwaway user, a few rows and a test image, then exercises sign-in, claiming an invitation, row-level security (an editor can write their own site and nobody else's; visitors can read but not write), the last-admin guard, rate limiting and image uploads, and deletes everything it made. It asks before touching a database that isn't local (`--yes` skips the question), and needs the service-role key. |
+| `--csp` | Prints a starter `Content-Security-Policy-Report-Only` header built from your `SUPABASE_URL` and exits. |
 | `--offline` | Skips the advisory lookup (the only network call besides your own Supabase project). Package names and versions are what's sent otherwise, as with `pnpm audit`; offline, Next.js is checked against a built-in list that may be out of date. |
 | `--production` | Treats production-only requirements as failures instead of warnings. |
 | `--strict` / `--json` | Exit non-zero on warnings too; machine-readable output for CI. |
@@ -737,6 +786,42 @@ Run `pnpm exec guardrail-doctor --production` to check everything below.
 - **Add security headers** in `next.config`: at least a `Content-Security-Policy`
   with `frame-ancestors 'self'` (so the editing chrome can't be framed by another
   site), `Strict-Transport-Security`, and `X-Content-Type-Options: nosniff`.
+  `guardrail-doctor --fix` adds this baseline. For a policy that also restricts
+  scripts and styles, see "Content Security Policy" below.
+
+### Content Security Policy
+
+Guardrail works under a strict policy — no `'unsafe-inline'` for styles and no
+nonce. Its chrome is a stylesheet, and it renders no inline scripts and uses no
+`eval`. A strict policy only has to allow the two places the browser talks to
+Supabase directly:
+
+| Directive | Allow | Why |
+|---|---|---|
+| `connect-src` | `'self'` and your Supabase origin | image uploads are sent straight from the browser to Supabase storage |
+| `img-src` | `'self'` and your Supabase origin | uploaded images and the media picker's thumbnails load from storage |
+| `style-src` | `'self'` | nothing more |
+| `frame-ancestors` | `'self'` | so the editing chrome can't be framed by another site |
+
+Everything else — reads, saves, sign-in — goes through your own server, i.e.
+`'self'`. If you build the header in code, `guardrailCspDirectives()` returns
+these for you to merge into your own:
+
+```ts
+import { guardrailCspDirectives, cspString } from "@guard-rail/core";
+
+const gr = guardrailCspDirectives({ supabaseUrl: process.env.SUPABASE_URL });
+// gr["connect-src"] -> ["'self'", "https://abc.supabase.co"]
+// cspString(gr)     -> "style-src 'self'; img-src 'self' https://abc.supabase.co; …"
+```
+
+To get started, `pnpm exec guardrail-doctor --csp` prints a starter
+`Content-Security-Policy-Report-Only` header built from your `SUPABASE_URL`: send it
+report-only first, tune it for what your own site loads (analytics, fonts,
+embeds), then enforce it. Once the site is running,
+`pnpm exec guardrail-doctor --app-url=https://your-site.com` checks that the live
+policy lets Guardrail's uploads and images through. A script nonce, if you use
+one, is set by your site (Next.js does it from a proxy); Guardrail doesn't need it.
 
 ## Known limitations
 

package/dist/cli/doctor.js

@@ -14,6 +14,7 @@ import { createRequire } from "node:module";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { GR_SCHEMA, GR_MEMBERS_TABLE } from "../core/defs.js";
+import { cspString, guardrailCspDirectives } from "../core/csp.js";
 const NEXT_MIN_PATCHED = {
   15: [15, 5, 28],
   16: [16, 4, 1]
@@ -66,6 +67,9 @@ Options:
                      versions of next, @supabase/* and @guard-rail/core are
                      checked against its published security advisories (only
                      package names and versions are sent, as \`pnpm audit\` does).
+  --csp              Print a starter Content-Security-Policy-Report-Only header
+                     for this site (built from SUPABASE_URL) and exit. Add it
+                     report-only first, watch the reports, then enforce.
   --production       Treat production-only requirements (like
                      GUARDRAIL_SITE_URL) as failures rather than warnings.
   --strict           Exit non-zero on warnings too.
@@ -101,7 +105,7 @@ function parseFlags(argv) {
       unknown.push(arg);
     }
   }
-  const known = /* @__PURE__ */ new Set(["fix", "push", "e2e", "yes", "production", "strict", "json", "offline", "help", "h"]);
+  const known = /* @__PURE__ */ new Set(["fix", "push", "e2e", "yes", "production", "strict", "json", "offline", "csp", "help", "h"]);
   for (const f of flags) if (!known.has(f)) unknown.push(`--${f}`);
   for (const k of Object.keys(values)) if (k !== "app-url") unknown.push(`--${k}`);
   return { flags, values, unknown };
@@ -575,7 +579,71 @@ async function checkDatabase(ctx, sb) {
   info("Admin guard (can't delete the last admin)", "Verified by --e2e; it's a trigger, which can't be probed read-only.");
   return true;
 }
-async function checkLiveSite(appUrl) {
+function parseCsp(value) {
+  const out = {};
+  for (const part of value.split(";")) {
+    const [name, ...sources] = part.trim().split(/\s+/);
+    if (name) out[name.toLowerCase()] = sources;
+  }
+  return out;
+}
+function effectiveSources(csp, name) {
+  return csp[name] ?? csp["default-src"] ?? null;
+}
+function allowsOrigin(sources, origin) {
+  if (sources === null) return true;
+  const target = new URL(origin);
+  return sources.some((raw) => {
+    const src = raw.toLowerCase();
+    if (src === "*") return true;
+    if (src === `${target.protocol}`) return true;
+    if (src === origin.toLowerCase()) return true;
+    const wild = src.match(/^(https?:)\/\/\*\.(.+?)(?::(\d+))?$/);
+    if (wild) {
+      const [, scheme, domain, port] = wild;
+      return scheme === target.protocol && target.hostname.endsWith(`.${domain}`) && (!port || port === target.port);
+    }
+    return false;
+  });
+}
+function starterPolicy(supabaseUrl) {
+  const gr = guardrailCspDirectives(supabaseUrl ? { supabaseUrl } : {});
+  return cspString({
+    "default-src": ["'self'"],
+    "script-src": ["'self'", "'nonce-REPLACE_PER_REQUEST'", "'strict-dynamic'"],
+    "style-src": gr["style-src"],
+    "img-src": [...gr["img-src"], "data:"],
+    "connect-src": gr["connect-src"],
+    "font-src": ["'self'", "data:"],
+    "object-src": ["'none'"],
+    "base-uri": ["'self'"],
+    "form-action": ["'self'"],
+    "frame-ancestors": gr["frame-ancestors"]
+  });
+}
+function printStarterCsp(ctx) {
+  console.log(`Starter Content-Security-Policy
+
+Content-Security-Policy-Report-Only: ${starterPolicy(ctx.url)}
+
+How to use it
+  - Send it as Content-Security-Policy-Report-Only first. Browsers report what it
+    would block without blocking anything; tune it for the things your site
+    loads itself (analytics, fonts, embeds), then switch the header name to
+    Content-Security-Policy.
+  - Guardrail needs nothing beyond 'self' for styles and scripts. Its stylesheet is
+    a real file and it renders no inline scripts, so it needs no 'unsafe-inline' and no
+    nonce. The only extras are your Supabase origin in connect-src (image
+    uploads) and img-src (the media picker's thumbnails).${ctx.url ? "" : "\n    (Set SUPABASE_URL and run this again to include your Supabase origin.)"}
+  - script-src above uses a per-request nonce, which Next.js sets from a proxy
+    (see "Content Security Policy" in the Next.js docs). With only a static header
+    in next.config you can't use a nonce \u2014 use 'self' 'unsafe-inline' for scripts
+    instead, which is a weaker policy but still a useful one.
+  - guardrailCspDirectives() from @guard-rail/core returns Guardrail's directives
+    if you build the header in code.
+`);
+}
+async function checkLiveSite(appUrl, ctx) {
   group("Live site");
   let res;
   try {
@@ -606,6 +674,69 @@ async function checkLiveSite(appUrl) {
   const setCookie = typeof h.getSetCookie === "function" ? h.getSetCookie() : [];
   const session = setCookie.filter((c) => /^sb-.*-auth-token/i.test(c));
   if (session.length) fail("A session cookie was set for an anonymous request", session.map((c) => c.split("=")[0]).join(", "));
+  if (res.status === 200) {
+    const html = await res.text().catch(() => "");
+    const MARKER = /--gr-bg\b|\.gr-banner\b/;
+    const inline = [...html.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)].map((m) => m[1]).join("\n");
+    let found = MARKER.test(inline);
+    const hrefs = [...html.matchAll(/<link\b[^>]*rel=["']stylesheet["'][^>]*>/gi)].map((m) => m[0].match(/href=["']([^"']+)["']/i)?.[1]).filter((x) => Boolean(x)).slice(0, 8);
+    for (const href of hrefs) {
+      if (found) break;
+      try {
+        const css = await fetch(new URL(href, appUrl), { signal: AbortSignal.timeout(8e3) });
+        if (css.ok && MARKER.test(await css.text())) found = true;
+      } catch {
+      }
+    }
+    if (found) pass("Guardrail's stylesheet is on the page");
+    else if (hrefs.length === 0 && !/<style/i.test(html)) skip("Guardrail's stylesheet", "The page has no stylesheets to inspect.");
+    else {
+      warn(
+        "Guardrail's stylesheet isn't on the page",
+        "Its editing chrome would render unstyled. The package imports its own CSS, which your bundler may not be picking up.",
+        'Import it once in your root layout: import "@guard-rail/core/styles.css";'
+      );
+    }
+  }
+  const enforced = h.get("content-security-policy");
+  const reportOnly = h.get("content-security-policy-report-only");
+  const policy = enforced ?? reportOnly;
+  if (!policy) {
+    warn(
+      "No Content-Security-Policy",
+      "Nothing limits where scripts and styles can load from, so an injected script would run.",
+      "Run: pnpm exec guardrail-doctor --csp   (prints a starter report-only policy)"
+    );
+    return;
+  }
+  const parsed = parseCsp(policy);
+  const label = enforced ? "" : " (report-only)";
+  if (!parsed["default-src"] && !parsed["script-src"]) {
+    info(`Content-Security-Policy only sets ${Object.keys(parsed).join(", ") || "nothing"}`, "It doesn't restrict scripts. Run: pnpm exec guardrail-doctor --csp for a fuller starter.");
+    return;
+  }
+  const style = effectiveSources(parsed, "style-src");
+  if (style && style.map((x) => x.toLowerCase()).includes("'unsafe-inline'")) {
+    info(`style-src allows 'unsafe-inline'${label}`, "Guardrail no longer needs it \u2014 its chrome is a stylesheet. Remove it unless something else on the site does.");
+  } else {
+    pass(`Policy${label} doesn't need 'unsafe-inline' for Guardrail's styles`);
+  }
+  if (ctx.url) {
+    let supabase;
+    try {
+      supabase = new URL(ctx.url).origin;
+    } catch {
+    }
+    if (supabase && supabase !== new URL(appUrl).origin) {
+      for (const [directive, why] of [
+        ["connect-src", "image uploads go straight from the browser to Supabase storage"],
+        ["img-src", "uploaded images and the media picker's thumbnails load from Supabase storage"]
+      ]) {
+        if (allowsOrigin(effectiveSources(parsed, directive), supabase)) pass(`${directive}${label} allows ${supabase}`);
+        else warn(`${directive}${label} blocks ${supabase}`, `Needed because ${why}.`, `Add ${supabase} to ${directive}.`);
+      }
+    }
+  }
 }
 const TINY_PNG = Buffer.from(
   "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
@@ -839,6 +970,10 @@ ${USAGE}`);
     anonKey: env.SUPABASE_ANON_KEY,
     serviceKey: env.SUPABASE_SERVICE_ROLE_KEY ?? env.SERVICE_KEY
   };
+  if (flags.has("csp")) {
+    printStarterCsp(ctx);
+    return 0;
+  }
   const json = flags.has("json");
   if (!json) console.log("Guardrail doctor");
   if (flags.has("fix")) {
@@ -876,7 +1011,7 @@ ${paint(1, "Fixes")}`);
   checkFiles(ctx);
   const sb = await loadSupabase();
   const dbReachable = await checkDatabase(ctx, sb);
-  if (values["app-url"]) await checkLiveSite(values["app-url"]);
+  if (values["app-url"]) await checkLiveSite(values["app-url"], ctx);
   if (flags.has("e2e")) {
     group("End-to-end");
     if (!dbReachable || !sb) {