@emplugins/emprivacy 2.0.0 → 2.1.0

package/docs/TESTING.md

@@ -2,7 +2,7 @@
 
 # Testing EmPrivacy before deploy
 
-Testing is split into **automated** checks (CI-friendly) and **manual** checks that require a running EmDash site, because the plugin integrates with EmDash’s runtime, KV, storage, admin Block Kit, and public page pipeline.
+Testing is split into **automated** checks (CI-friendly) and **manual** checks that require a running EmDash site.
 
 ## Automated (in this repo)
 
@@ -10,30 +10,34 @@ Testing is split into **automated** checks (CI-friendly) and **manual** checks t
 |--------|-------------------|
 | `pnpm run typecheck` | TypeScript types against `emdash` APIs |
 | `pnpm run build` | Bundles ESM + declarations (`dist/`) |
-| `pnpm test` | Unit tests for **pure** helpers in `src/config.ts` (validation, normalization, URL list parsing, JSON escaping) |
+| `pnpm test` | Config validation, security helpers (embed/script allowlists, CSRF Origin/Sec-Fetch-Site, cookie TTL, SRI), i18n, theme hex, vendor list (no token leak; GTM=marketing), JSON escaping |
 
-These scripts do **not** start EmDash or exercise `page:fragments`, admin routes, or the consent cookie in a browser. They catch regressions in config/save validation and packaging early.
+These scripts do **not** start EmDash or drive a browser.
 
 ## Manual integration QA (required before production)
 
-Use a **staging** EmDash Astro app on **`emdash@^0.38.0`** with `emprivacyPlugin()` in **`plugins: []`** (native, not `sandboxed`), layout wires (`EmDashHead` / body components with page context), and the same EmDash version you plan to ship.
-
-Work through the checklist from the main [README](../README.md) (also copied below). Record pass/fail and browser + EmDash versions.
+Use a **staging** EmDash Astro app on **`emdash@^0.38.0`** with `emprivacyPlugin()` in **`plugins: []`**, layout wires (`EmDashHead` / body components with page context), and the same EmDash version you plan to ship.
 
 ### Core flows
 
-1. **Banner** — Incognito window: banner appears when there is no `emprivacy_cc` cookie or when **Policy / consent version** in admin does not match the cookie’s `v` field.
-2. **Re-open consent** — After dismissing the banner, confirm a **cookie button** appears (bottom-left). Click it: the same options appear; **Save choices** (or Accept/Reject) reloads the page. After reload, **Network** should list analytics scripts only if analytics is on; turn analytics off, save, reload, and those scripts should not run. If you use **Cloudflare Web Analytics** in admin, after consent confirm `beacon.min.js` loads and the tag includes `data-cf-beacon` with your token.
-3. **Strict defaults** — With strict mode on, deny non-essential and confirm configured analytics/marketing URLs do **not** appear in Network until the user accepts (or enables those categories in Customize).
-4. **Persistence** — After accept, reload: banner stays closed; scripts load according to saved choices (Network tab).
-5. **Admin** — EmPrivacy settings page loads, **Save** persists; public banner text and links match what you saved (after refresh / new request).
-6. **Optional server log** — Enable “Log consent…”; submit consent; confirm a row appears under recent records and `POST /_emdash/api/plugins/emprivacy/record` succeeds (200, `{ ok: true }`) in Network.
-7. **Optional Google Consent Mode** — Enable in admin; verify a denied-default snippet exists in `<head>` before interaction, and updates after choice (see [Google’s Consent Mode docs](https://support.google.com/tagmanager/answer/13695607)).
+1. **Banner** — Incognito: banner appears with no `emprivacy_cc` cookie, when **Policy / consent version** does not match `v`, or when a legacy cookie lacks `f`.
+2. **Categories** — Customize shows Essential (locked on), Functional, Analytics, Marketing. Reject non-essential: no configured analytics/marketing scripts in Network; embeds stay placeholders.
+3. **Re-open** — Cookie button (bottom-left). Save reloads. Turning a category off removes those scripts after reload.
+4. **Presets** — For the platform you ship, confirm the expected host loads only after the correct category (Analytics for most presets; **Marketing** for GTM). Custom/marketing scripts must respect any host allowlist.
+5. **Evil embed plant** — In DevTools, add a placeholder with `data-src="https://evil.example/x"` and grant marketing; assert no iframe is created.
+6. **Embed unlock** — “Allow embeds and load” opens preferences; it must not silently flip categories.
+7. **Embeds** — With `@emdash-cms/plugin-embeds` and EmPrivacy last (or site-level `blockComponents`): a YouTube block is a placeholder first; after allowing the embed category, the iframe `src` is `https://www.youtube-nocookie.com/embed/…`. A junk/javascript URL never becomes an iframe.
+8. **API** — After a choice, `window.emprivacy.get()` returns state; `window.emprivacy.has("analytics")` matches Network.
+9. **i18n** — A `de` (or `fr`) page shows translated buttons when that locale is active.
+10. **Policy pages** — `/privacy` does not show the first-visit overlay when that setting is on; the cookie button still works.
+11. **Admin** — Save persists; **What this site uses** matches vendors; tokens do not appear there or at `/_emdash/api/plugins/emprivacy/vendors`.
+12. **Optional server log** — POST requires matching Origin or `Sec-Fetch-Site: same-origin`; Origin mismatch is 403. Body includes `functional`.
+13. **Optional Google Consent Mode** — Denied defaults in `<head>` before interaction, including `functionality_storage`.
 
 ### Regression triggers
 
-- Bump EmDash minor: re-run manual QA (plugin APIs and admin routing can change).
-- Bump this plugin’s **npm semver** after changing hooks or cookie shape: re-check banner and cookie JSON. Release numbering policy: [RELEASES.md](./RELEASES.md).
+- Bump EmDash minor: re-run manual QA.
+- Cookie JSON or embed allowlist changes: re-check banner, `window.emprivacy`, and a YouTube block.
 
 ## CI suggestion
 
@@ -44,10 +48,4 @@ pnpm run build
 pnpm test
 ```
 
-## Future improvements (not in v1)
-
-- **Integration tests** against EmDash’s native plugin loader + mock `PluginContext` (heavy; depends on EmDash test utilities if exposed).
-- **E2E** (Playwright) against a minimal EmDash fixture app in CI (slower, higher maintenance).
-
 For most teams, **automated unit tests + staging manual QA** is the right balance.
-

package/package.json

@@ -1,18 +1,20 @@
 {
   "//": "SPDX-License-Identifier: MIT",
   "name": "@emplugins/emprivacy",
-  "version": "2.0.0",
-  "description": "Cookie consent and privacy notices for EmDash (GDPR, CCPA/CIPA-oriented configuration)",
+  "version": "2.1.0",
+  "description": "Cookie consent, gated embeds, and privacy notices for EmDash (GDPR, CCPA/CIPA-oriented configuration)",
   "type": "module",
   "main": "dist/index.mjs",
   "exports": {
     ".": {
       "import": "./dist/index.mjs",
       "types": "./dist/index.d.mts"
-    }
+    },
+    "./astro": "./src/astro/index.ts"
   },
   "files": [
     "dist",
+    "src/astro",
     "README.md",
     "LICENSE",
     "docs/DEVELOPMENT.md",
@@ -40,14 +42,14 @@
     "emdash": "^0.38.0"
   },
   "dependencies": {
-    "zod": "4.5.4"
+    "zod": "4.6.5"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.27.11",
+    "@changesets/cli": "^3.0.3",
     "emdash": "0.38.0",
-    "tsdown": "^0.20.3",
+    "tsdown": "^0.23.0",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "vitest": "^5.0.1"
   },
   "repository": {
     "type": "git",
@@ -64,7 +66,7 @@
   "pnpm": {
     "overrides": {
       "kysely": "0.29.6",
-      "zod": "4.5.4"
+      "zod": "4.6.5"
     }
   },
   "scripts": {

package/src/astro/GatedEmbed.astro

@@ -0,0 +1,70 @@
+---
+// SPDX-License-Identifier: MIT
+import { resolveEmbed } from "./embed-resolve.js";
+
+interface Props {
+	node: {
+		_type?: string;
+		id?: string;
+		poster?: string;
+		title?: string;
+	};
+}
+
+const { node } = Astro.props;
+const resolved = resolveEmbed(node ?? {});
+---
+
+{
+	resolved ? (
+		<div
+			class="emprivacy-embed"
+			data-emprivacy-embed={resolved.kind}
+			data-src={resolved.src}
+			data-mode={resolved.mode}
+			data-label={resolved.label}
+		>
+			{resolved.poster ? (
+				<img class="emprivacy-embed-poster" src={resolved.poster} alt="" width="480" height="270" />
+			) : null}
+			<p class="emprivacy-embed-copy">{resolved.label} is blocked until you allow the matching cookie category.</p>
+			<button type="button" class="emprivacy-embed-btn" data-emprivacy-embed-load>
+				Allow embeds and load
+			</button>
+		</div>
+	) : (
+		<p class="emprivacy-embed-invalid">This embed could not be displayed.</p>
+	)
+}
+
+<style>
+	.emprivacy-embed {
+		display: grid;
+		gap: 0.75rem;
+		place-items: center;
+		padding: 1.25rem;
+		border: 1px solid color-mix(in srgb, currentColor 20%, transparent);
+		border-radius: 8px;
+		background: color-mix(in srgb, currentColor 6%, transparent);
+		text-align: center;
+		aspect-ratio: 16 / 9;
+	}
+	.emprivacy-embed-poster {
+		max-width: 100%;
+		height: auto;
+		border-radius: 6px;
+	}
+	.emprivacy-embed-copy,
+	.emprivacy-embed-invalid {
+		margin: 0;
+		max-width: 36rem;
+	}
+	.emprivacy-embed-btn {
+		border-radius: 6px;
+		border: 1px solid currentColor;
+		background: transparent;
+		color: inherit;
+		padding: 0.5rem 0.85rem;
+		cursor: pointer;
+	}
+</style>

package/src/astro/embed-resolve.ts

@@ -0,0 +1,227 @@
+// SPDX-License-Identifier: MIT
+
+/**
+ * Validate official EmDash embed block payloads and produce a first-party
+ * placeholder plan. Never returns a URL we did not construct or allowlist.
+ */
+
+export const EMBED_BLOCK_TYPES = [
+	"youtube",
+	"vimeo",
+	"tweet",
+	"bluesky",
+	"mastodon",
+	"linkPreview",
+	"gist",
+] as const;
+
+export type EmbedBlockType = (typeof EMBED_BLOCK_TYPES)[number];
+
+export type EmbedRenderMode = "iframe" | "link";
+
+export interface ResolvedEmbed {
+	kind: EmbedBlockType;
+	mode: EmbedRenderMode;
+	/** https iframe src or link href — always produced by this module */
+	src: string;
+	label: string;
+	poster: string | null;
+}
+
+const YT_ID = /^[A-Za-z0-9_-]{11}$/;
+const VIMEO_ID = /^\d{6,12}$/;
+const TWEET_ID = /^\d{5,20}$/;
+const BSKY_RKEY = /^[a-z0-9]{1,32}$/i;
+const BSKY_HANDLE = /^[a-z0-9.-]{1,253}$/i;
+const GIST_ID = /^[a-f0-9]{8,64}$/i;
+const GIST_USER = /^[A-Za-z0-9-]{1,39}$/;
+
+const YT_HOSTS = new Set(["youtube.com", "www.youtube.com", "m.youtube.com", "youtu.be", "www.youtube-nocookie.com", "youtube-nocookie.com"]);
+const VIMEO_HOSTS = new Set(["vimeo.com", "www.vimeo.com", "player.vimeo.com"]);
+const TWEET_HOSTS = new Set(["twitter.com", "www.twitter.com", "x.com", "www.x.com", "mobile.twitter.com"]);
+const BSKY_HOSTS = new Set(["bsky.app", "www.bsky.app"]);
+const GIST_HOSTS = new Set(["gist.github.com"]);
+const POSTER_HOSTS = new Set(["i.ytimg.com", "img.youtube.com", "i.vimeocdn.com"]);
+
+function hasUnsafeChars(s: string): boolean {
+	return /[\u0000-\u001F\u007F\s]/.test(s);
+}
+
+export function parseHttpsUrl(raw: string): URL | null {
+	const t = raw.trim();
+	if (!t || t.length > 2048 || hasUnsafeChars(t)) return null;
+	if (/%0d|%0a|%09|%0b|%0c|%20/i.test(t)) return null;
+	try {
+		const u = new URL(t);
+		if (u.protocol !== "https:") return null;
+		if (u.username || u.password) return null;
+		if (u.hostname === "localhost" || u.hostname.endsWith(".localhost")) return null;
+		return u;
+	} catch {
+		return null;
+	}
+}
+
+function hostOf(u: URL): string {
+	return u.hostname.toLowerCase();
+}
+
+function youtubeId(raw: string): string | null {
+	const t = raw.trim();
+	if (YT_ID.test(t)) return t;
+	const u = parseHttpsUrl(t);
+	if (!u || !YT_HOSTS.has(hostOf(u))) return null;
+	if (hostOf(u) === "youtu.be") {
+		const id = u.pathname.replace(/^\//, "").split("/")[0] ?? "";
+		return YT_ID.test(id) ? id : null;
+	}
+	const v = u.searchParams.get("v");
+	if (v && YT_ID.test(v)) return v;
+	const parts = u.pathname.split("/").filter(Boolean);
+	const embedIdx = parts.indexOf("embed");
+	if (embedIdx >= 0) {
+		const id = parts[embedIdx + 1] ?? "";
+		return YT_ID.test(id) ? id : null;
+	}
+	const shortsIdx = parts.indexOf("shorts");
+	if (shortsIdx >= 0) {
+		const id = parts[shortsIdx + 1] ?? "";
+		return YT_ID.test(id) ? id : null;
+	}
+	return null;
+}
+
+function vimeoId(raw: string): string | null {
+	const t = raw.trim();
+	if (VIMEO_ID.test(t)) return t;
+	const u = parseHttpsUrl(t);
+	if (!u || !VIMEO_HOSTS.has(hostOf(u))) return null;
+	const parts = u.pathname.split("/").filter(Boolean);
+	const last = parts[parts.length - 1] ?? "";
+	const videoIdx = parts.indexOf("video");
+	if (videoIdx >= 0) {
+		const id = parts[videoIdx + 1] ?? "";
+		return VIMEO_ID.test(id) ? id : null;
+	}
+	return VIMEO_ID.test(last) ? last : null;
+}
+
+function tweetId(raw: string): string | null {
+	const t = raw.trim();
+	if (TWEET_ID.test(t)) return t;
+	const u = parseHttpsUrl(t);
+	if (!u || !TWEET_HOSTS.has(hostOf(u))) return null;
+	const m = /\/status(?:es)?\/(\d{5,20})(?:\/|$)/i.exec(u.pathname);
+	return m?.[1] ?? null;
+}
+
+function blueskyHref(raw: string): string | null {
+	const u = parseHttpsUrl(raw);
+	if (!u || !BSKY_HOSTS.has(hostOf(u))) return null;
+	const m = /^\/profile\/([^/]+)\/post\/([^/]+)\/?$/.exec(u.pathname);
+	if (!m) return null;
+	const handle = m[1] ?? "";
+	const rkey = m[2] ?? "";
+	if (!BSKY_HANDLE.test(handle) || !BSKY_RKEY.test(rkey)) return null;
+	return `https://bsky.app/profile/${handle}/post/${rkey}`;
+}
+
+function gistHref(raw: string): string | null {
+	const u = parseHttpsUrl(raw);
+	if (!u || !GIST_HOSTS.has(hostOf(u))) return null;
+	const parts = u.pathname.split("/").filter(Boolean);
+	if (parts.length < 2) return null;
+	const user = parts[0] ?? "";
+	const id = (parts[1] ?? "").replace(/\.js$/i, "");
+	if (!GIST_USER.test(user) || !GIST_ID.test(id)) return null;
+	return `https://gist.github.com/${user}/${id}`;
+}
+
+function mastodonHref(raw: string): string | null {
+	const u = parseHttpsUrl(raw);
+	if (!u) return null;
+	// Any Mastodon instance is an arbitrary host — never iframe it.
+	if (!/^\/@[^/]+\/\d+\/?$/.test(u.pathname) && !/^\/users\/[^/]+\/statuses\/\d+\/?$/.test(u.pathname)) {
+		return null;
+	}
+	return `https://${hostOf(u)}${u.pathname.replace(/\/$/, "")}`;
+}
+
+function posterUrl(raw: unknown, kind: EmbedBlockType, mediaId: string | null): string | null {
+	if (kind === "youtube" && mediaId && YT_ID.test(mediaId)) {
+		return `https://i.ytimg.com/vi/${mediaId}/hqdefault.jpg`;
+	}
+	if (typeof raw !== "string") return null;
+	const u = parseHttpsUrl(raw);
+	if (!u || !POSTER_HOSTS.has(hostOf(u))) return null;
+	return u.href;
+}
+
+export function isEmbedBlockType(s: string): s is EmbedBlockType {
+	return (EMBED_BLOCK_TYPES as readonly string[]).includes(s);
+}
+
+export function resolveEmbed(node: {
+	_type?: unknown;
+	id?: unknown;
+	poster?: unknown;
+	title?: unknown;
+}): ResolvedEmbed | null {
+	if (!node || typeof node._type !== "string" || !isEmbedBlockType(node._type)) return null;
+	if (typeof node.id !== "string") return null;
+	const kind = node._type;
+	const rawId = node.id.trim();
+	if (!rawId || rawId.length > 2048) return null;
+
+	if (kind === "youtube") {
+		const id = youtubeId(rawId);
+		if (!id) return null;
+		return {
+			kind,
+			mode: "iframe",
+			src: `https://www.youtube-nocookie.com/embed/${id}`,
+			label: "YouTube",
+			poster: posterUrl(node.poster, kind, id),
+		};
+	}
+	if (kind === "vimeo") {
+		const id = vimeoId(rawId);
+		if (!id) return null;
+		return {
+			kind,
+			mode: "iframe",
+			src: `https://player.vimeo.com/video/${id}`,
+			label: "Vimeo",
+			poster: posterUrl(node.poster, kind, id),
+		};
+	}
+	if (kind === "tweet") {
+		const id = tweetId(rawId);
+		if (!id) return null;
+		return {
+			kind,
+			mode: "link",
+			src: `https://x.com/i/web/status/${id}`,
+			label: "Post on X",
+			poster: null,
+		};
+	}
+	if (kind === "bluesky") {
+		const href = blueskyHref(rawId);
+		if (!href) return null;
+		return { kind, mode: "link", src: href, label: "Bluesky post", poster: null };
+	}
+	if (kind === "mastodon") {
+		const href = mastodonHref(rawId);
+		if (!href) return null;
+		return { kind, mode: "link", src: href, label: "Mastodon post", poster: null };
+	}
+	if (kind === "gist") {
+		const href = gistHref(rawId);
+		if (!href) return null;
+		return { kind, mode: "link", src: href, label: "GitHub Gist", poster: null };
+	}
+	const href = parseHttpsUrl(rawId);
+	if (!href) return null;
+	return { kind: "linkPreview", mode: "link", src: href.href, label: href.hostname, poster: null };
+}

package/src/astro/index.ts

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: MIT
+
+/**
+ * Portable Text renderers that replace official EmDash embed blocks with
+ * consent-gated placeholders. Import from `@emplugins/emprivacy/astro`.
+ *
+ * Later plugins in `plugins: []` win. To force these wrappers regardless of
+ * registration order, pass `blockComponents` to `<PortableText />`.
+ */
+
+import GatedEmbed from "./GatedEmbed.astro";
+
+export const blockComponents = {
+	youtube: GatedEmbed,
+	vimeo: GatedEmbed,
+	tweet: GatedEmbed,
+	bluesky: GatedEmbed,
+	mastodon: GatedEmbed,
+	linkPreview: GatedEmbed,
+	gist: GatedEmbed,
+};
+
+export { GatedEmbed };
+export { blockComponents as emprivacyEmbedComponents };