keksi 0.0.0-stage → 0.1.2

package/README.md

@@ -1,3 +1,167 @@
-# Temporary Holding Version
+# keksi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lean cookie consent for Astro, SvelteKit and other server-rendered sites. Built around Finnish and EU law, with
+texts in English, Finnish and Swedish.
+
+keksi loads the trackers itself, and only after consent. You don't add their script tags: you put their ids in the
+config, so there's nothing to block.
+
+- Google Analytics 4, Google Ads, Meta Pixel and YouTube. The short list is deliberate.
+- About 5 KB gzipped, inline. No extra requests, no dependencies.
+- Rendered on the server. Works on static pages, with no layout shift.
+- The cookie policy table is generated from the same data.
+
+## Setup
+
+```sh
+pnpm add keksi
+```
+
+```ts
+// keksi.config.ts
+import { defineConfig } from 'keksi';
+
+export default defineConfig({
+  ga: 'G-XXXXXXX',
+  googleAds: 'AW-123456789',
+  meta: '1234567890',
+  youtube: true,
+  policyUrl: '/evasteet',
+});
+```
+
+**Astro:** add the component right after `<body>` in your layout.
+
+```astro
+---
+import { Keksi } from 'keksi/astro';
+import config from '../../keksi.config';
+---
+<body>
+  <Keksi config={config} />
+  ...
+</body>
+```
+
+**SvelteKit:** add the hook. It renders keksi outside the Svelte root and keeps it out of the client bundle.
+
+```ts
+// src/hooks.server.ts
+import { keksiHandle } from 'keksi/sveltekit';
+import config from '../keksi.config';
+
+export const handle = keksiHandle(config);
+```
+
+Any element with `data-keksi-open` reopens the settings. Put one in the footer:
+
+```html
+<button type="button" data-keksi-open>Evästeasetukset</button>
+```
+
+**Necessary cookies** from your framework or own code, such as a session, are listed under "Necessary". Find them
+with the scanner, which visits the site without consent:
+
+```sh
+npx keksi scan https://staging.example.fi
+```
+
+It writes `keksi.cookies.json`, with purposes for common cookies filled in. Write the rest, then import the file:
+
+```ts
+import necessary from './keksi.cookies.json' with { type: 'json' };
+
+export default defineConfig({ ga: 'G-XXXXXXX', necessary });
+```
+
+Rerunning keeps your purposes. `keksi scan <url> --check` fails when there are new entries, for CI. The scanner only
+lists; it never blocks anything. Cookies set after login aren't visited, so add those by hand.
+
+**Cookie policy page:** `<CookieTable config={config} />` from `keksi/astro`, or `cookieTable(config)` for an HTML
+string.
+
+## Tracking events
+
+`gtag()` and `fbq()` are always defined, so you can call them anytime:
+
+```ts
+gtag('event', 'generate_lead');
+fbq('track', 'Lead');
+```
+
+- Calls made before consent are queued. They're sent only if the visitor consents on that page.
+- Google gets Consent Mode v2 signals (basic mode).
+- GA4 and Meta Pixel track single-page navigation themselves.
+
+## YouTube
+
+```html
+<keksi-youtube video="aqz-KE-bpKQ" label="Esittelyvideo" poster="/img/poster.jpg"></keksi-youtube>
+```
+
+- Shows a placeholder until the visitor clicks it, then loads that one video from `youtube-nocookie.com`.
+- With marketing consent, videos load directly.
+- `poster` is optional and should be self-hosted. Thumbnails from YouTube would contact Google before consent.
+
+## API
+
+```ts
+window.keksi.consent; // { analytics, marketing } or null
+window.keksi.open();
+window.keksi.save({ marketing: true });
+window.keksi.acceptAll();
+window.keksi.rejectAll();
+document.addEventListener('keksi:change', (e) => e.detail);
+```
+
+## Testing
+
+```ts
+import { consentCookie, watchTracking } from 'keksi/playwright';
+
+test('nothing tracks before consent', async ({ page }) => {
+  const tracking = watchTracking(page, config, { allow: ['session'] });
+  await page.goto('/');
+  await page.waitForLoadState('networkidle');
+  await tracking.check(); // throws on tracker requests or stored data
+});
+
+// Skip the banner in other tests
+await context.addCookies([consentCookie(config, baseURL, { analytics: true })]);
+```
+
+## Customizing
+
+- **Styles** have zero specificity, so your CSS wins. Variables: `--keksi-bg`, `--keksi-fg`, `--keksi-line`,
+  `--keksi-radius`, `--keksi-focus`.
+- **Language:** follows the page's language, otherwise Finnish. Pass `lang` to set it.
+- **Texts:** `texts: { fi: { intro: '…' } }`.
+- **CSP:** pass `nonce`.
+- **Other frameworks:** `renderKeksi(config, { lang })` returns the HTML to put after `<body>`.
+- **Consent cookie:** `cookie: { name, domain, days }`. Kept for 365 days by default.
+
+## Legal basis
+
+| Requirement | Basis | keksi |
+|---|---|---|
+| No non-essential storage before consent | Act 917/2014 §205 | Trackers load only after consent |
+| Purpose, duration and third parties disclosed | §205, CJEU *Planet49* | Providers on the banner, cookies and durations in settings and on the policy page |
+| Separate choices, rejecting as easy as accepting | GDPR Art. 4(11), 7; Traficom 2024 | A switch per category, "Reject all" on the banner |
+| Withdrawal is easy and has real effect | GDPR Art. 7(3) | Deletes the category's cookies and localStorage on your domain, then reloads |
+| Consent can be demonstrated | GDPR Art. 7(1) | Consent cookie with id, time and version. Adding or removing a provider asks again |
+| Transfers outside the EU disclosed | GDPR Art. 13(1)(f) | DPF transfer stated per provider |
+
+Cookies that Google and Meta set on their own domains can't be deleted from your site. The policy page lists them as
+third-party cookies.
+
+## Development
+
+```sh
+pnpm install
+pnpm build      # prints the runtime size
+pnpm test
+pnpm test:e2e   # Astro and SvelteKit examples
+```
+
+To add a provider: add its data to `src/providers.ts`, a config key with the same id to `KeksiConfig`, and its
+loading to `load()` in `src/runtime.ts`.

package/astro/CookieTable.astro

@@ -0,0 +1,15 @@
+---
+import { cookieTable, type KeksiConfig, type Locale } from 'keksi';
+
+interface Props {
+  config: KeksiConfig;
+  lang?: Locale;
+  headingLevel?: 2 | 3 | 4;
+}
+
+const { config, headingLevel } = Astro.props;
+const locale = Astro.currentLocale?.slice(0, 2);
+const lang = Astro.props.lang ?? (['fi', 'sv', 'en'].includes(locale!) ? (locale as Locale) : 'fi');
+---
+
+<Fragment set:html={cookieTable(config, { lang, headingLevel })} />

package/astro/Keksi.astro

@@ -0,0 +1,16 @@
+---
+import { renderKeksi, type KeksiConfig, type Locale } from 'keksi';
+
+interface Props {
+  config: KeksiConfig;
+  /** Defaults to Astro's current locale, then `fi`. */
+  lang?: Locale;
+  nonce?: string;
+}
+
+const { config, nonce } = Astro.props;
+const locale = Astro.currentLocale?.slice(0, 2);
+const lang = Astro.props.lang ?? (['fi', 'sv', 'en'].includes(locale!) ? (locale as Locale) : 'fi');
+---
+
+<Fragment set:html={renderKeksi(config, { lang, nonce })} />

package/astro/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Keksi } from './Keksi.astro';
+export { default as CookieTable } from './CookieTable.astro';

package/astro/index.js

@@ -0,0 +1,2 @@
+export { default as Keksi } from './Keksi.astro';
+export { default as CookieTable } from './CookieTable.astro';

package/dist/cli.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+
+// src/providers.ts
+var GOOGLE = { company: "Google Ireland Limited", privacyPolicy: "https://policies.google.com/privacy", transfer: "dpf" };
+var META = { company: "Meta Platforms Ireland Limited", privacyPolicy: "https://www.facebook.com/privacy/policy/", transfer: "dpf" };
+var providers = [
+  {
+    id: "ga",
+    name: "Google Analytics",
+    ...GOOGLE,
+    category: "analytics",
+    purpose: {
+      fi: "K\xE4vij\xE4tilastot: k\xE4vij\xE4m\xE4\xE4r\xE4t, liikenteen l\xE4hteet ja sivujen k\xE4ytt\xF6.",
+      sv: "Bes\xF6ksstatistik: antal bes\xF6kare, trafikk\xE4llor och hur sidorna anv\xE4nds.",
+      en: "Visitor statistics: visitor numbers, traffic sources and page usage."
+    },
+    cookies: [
+      { name: "_ga", duration: "2y" },
+      { name: "_ga_*", duration: "2y" }
+    ],
+    hosts: ["google-analytics.com", "analytics.google.com", "googletagmanager.com"]
+  },
+  {
+    id: "googleAds",
+    name: "Google Ads",
+    ...GOOGLE,
+    category: "marketing",
+    purpose: {
+      fi: "Mainonnan tehon mittaaminen (konversiot) ja mainosten kohdentaminen sivuston k\xE4vij\xF6ille.",
+      sv: "M\xE4tning av annonsernas effekt (konverteringar) och riktad annonsering till bes\xF6kare.",
+      en: "Measuring ad performance (conversions) and showing ads to site visitors."
+    },
+    cookies: [
+      { name: "_gcl_au", duration: "90d" },
+      { name: "_gcl_aw", duration: "90d" },
+      { name: "_gcl_dc", duration: "90d" },
+      { name: "_gcl_gs", duration: "90d" },
+      { name: "_gac_*", duration: "90d" },
+      { name: "_gcl_ls", duration: "persistent", storage: "localStorage" },
+      { name: "IDE", duration: "13mo", host: "doubleclick.net" },
+      { name: "DSID", duration: "14d", host: "doubleclick.net" },
+      { name: "test_cookie", duration: "15min", host: "doubleclick.net" }
+    ],
+    hosts: ["googletagmanager.com", "googleadservices.com", "doubleclick.net", "googlesyndication.com"]
+  },
+  {
+    id: "meta",
+    name: "Meta Pixel",
+    ...META,
+    category: "marketing",
+    purpose: {
+      fi: "Mainonnan tehon mittaaminen ja mainosten kohdentaminen Facebookissa ja Instagramissa.",
+      sv: "M\xE4tning av annonsernas effekt och riktad annonsering p\xE5 Facebook och Instagram.",
+      en: "Measuring ad performance and targeting ads on Facebook and Instagram."
+    },
+    cookies: [
+      { name: "_fbp", duration: "90d" },
+      { name: "_fbc", duration: "90d" },
+      { name: "fr", duration: "90d", host: "facebook.com" }
+    ],
+    hosts: ["facebook.net", "facebook.com"]
+  },
+  {
+    id: "youtube",
+    name: "YouTube",
+    ...GOOGLE,
+    category: "marketing",
+    purpose: {
+      fi: "Upotettujen videoiden toistaminen. YouTube voi k\xE4ytt\xE4\xE4 tietoja mainontaan.",
+      sv: "Uppspelning av inb\xE4ddade videor. YouTube kan anv\xE4nda uppgifterna f\xF6r annonsering.",
+      en: "Playing embedded videos. YouTube may use the data for advertising."
+    },
+    cookies: [
+      { name: "YSC", duration: "session", host: "youtube.com" },
+      { name: "VISITOR_INFO1_LIVE", duration: "6mo", host: "youtube.com" },
+      { name: "VISITOR_PRIVACY_METADATA", duration: "6mo", host: "youtube.com" },
+      { name: "__Secure-YNID", duration: "6mo", host: "youtube.com" },
+      { name: "__Secure-ROLLOUT_TOKEN", duration: "6mo", host: "youtube.com" },
+      { name: "PREF", duration: "8mo", host: "youtube.com" },
+      { name: "yt-remote-*, ytidb::*, yt-player-*", duration: "persistent", host: "youtube-nocookie.com", storage: "localStorage" }
+    ],
+    hosts: ["youtube.com", "youtube-nocookie.com", "ytimg.com", "googlevideo.com"]
+  }
+];
+
+// src/scan.ts
+var known = (purpose, fi, sv) => ({ en: purpose, fi, sv });
+var SESSION = known("Keeps you signed in.", "Pit\xE4\xE4 sinut kirjautuneena.", "H\xE5ller dig inloggad.");
+var CSRF = known("Protects forms against forgery.", "Suojaa lomakkeita v\xE4\xE4renn\xF6ksilt\xE4.", "Skyddar formul\xE4r mot f\xF6rfalskning.");
+var SECURITY = known(
+  "Protects the site against bots and attacks.",
+  "Suojaa sivustoa boteilta ja hy\xF6kk\xE4yksilt\xE4.",
+  "Skyddar webbplatsen mot botar och attacker."
+);
+var purposes = {
+  NEXT_LOCALE: known("Remembers your language.", "Muistaa valitsemasi kielen.", "Kommer ih\xE5g ditt spr\xE5k."),
+  "next-auth.session-token": SESSION,
+  "__Secure-next-auth.session-token": SESSION,
+  "authjs.session-token": SESSION,
+  "__Secure-authjs.session-token": SESSION,
+  "next-auth.csrf-token": CSRF,
+  "__Host-next-auth.csrf-token": CSRF,
+  "authjs.csrf-token": CSRF,
+  "__Host-authjs.csrf-token": CSRF,
+  "next-auth.callback-url": known("Returns you to the right page after signing in.", "Palauttaa oikealle sivulle kirjautumisen j\xE4lkeen.", "\xC5terf\xF6r dig till r\xE4tt sida efter inloggning."),
+  __cf_bm: SECURITY,
+  cf_clearance: SECURITY,
+  _cfuvid: SECURITY,
+  PHPSESSID: SESSION,
+  "connect.sid": SESSION,
+  session: SESSION,
+  csrftoken: CSRF,
+  _csrf: CSRF,
+  "sveltekit:*": known("Restores scroll position and page state when you navigate back.", "Palauttaa vierityskohdan ja sivun tilan, kun palaat takaisin.", "\xC5terst\xE4ller scrollposition och sidans l\xE4ge n\xE4r du g\xE5r tillbaka.")
+};
+var trackerNames = providers.flatMap((p) => p.cookies.flatMap((c) => c.name.split(", ")));
+var trackerHosts = providers.flatMap((p) => p.hosts);
+var matches = (patterns, name) => patterns.some((p) => p.endsWith("*") ? name.startsWith(p.slice(0, -1)) : name === p);
+function purposeOf(name) {
+  const k = Object.keys(purposes).find((p) => matches([p], name));
+  return k ? purposes[k] : void 0;
+}
+function durationOf(expires, now = Date.now() / 1e3) {
+  if (expires < 0) return "session";
+  const minutes = (expires - now) / 60;
+  const days = minutes / 1440;
+  if (days >= 365) return `${Math.round(days / 365)}y`;
+  if (days >= 30) return `${Math.round(days / 30.4)}mo`;
+  if (days >= 1) return `${Math.round(days)}d`;
+  return `${Math.max(1, Math.round(minutes))}min`;
+}
+async function scan(url2, { pages = 20, cookieName = "keksi" } = {}) {
+  const { chromium } = await import("@playwright/test");
+  const browser = await chromium.launch();
+  const origin = new URL(url2).origin;
+  const host = new URL(url2).hostname;
+  const found2 = /* @__PURE__ */ new Map();
+  try {
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    const queue = [new URL(url2).href];
+    const seen = new Set(queue);
+    for (let i = 0; i < queue.length && i < pages; i++) {
+      await page.goto(queue[i], { waitUntil: "networkidle", timeout: 3e4 }).catch(() => {
+      });
+      const { links, local, session } = await page.evaluate(() => ({
+        links: [...document.querySelectorAll("a[href]")].map((a) => a.href),
+        local: Object.keys(localStorage),
+        session: Object.keys(sessionStorage)
+      }));
+      for (const key2 of local) found2.set(`l:${key2}`, { name: key2, duration: "persistent", storage: "localStorage" });
+      for (const key2 of session) found2.set(`s:${key2}`, { name: key2, duration: "session", storage: "sessionStorage" });
+      for (const link of links) {
+        const u = new URL(link);
+        u.hash = "";
+        if (u.origin === origin && !seen.has(u.href) && !/\.(pdf|zip|jpe?g|png|webp|svg|mp4)$/i.test(u.pathname)) {
+          seen.add(u.href);
+          queue.push(u.href);
+        }
+      }
+    }
+    for (const c of await context.cookies()) {
+      const domain = c.domain.replace(/^\./, "");
+      const own = host === domain || host.endsWith(`.${domain}`);
+      found2.set(`c:${c.name}`, { name: c.name, duration: durationOf(c.expires), ...own ? {} : { host: domain } });
+    }
+  } finally {
+    await browser.close();
+  }
+  return [...found2.values()].filter((c) => c.name !== cookieName && !matches(trackerNames, c.name)).filter((c) => !c.host || !trackerHosts.some((t) => c.host === t || c.host.endsWith(`.${t}`))).map((c) => ({ ...c, purpose: purposeOf(c.name) ?? { en: "", fi: "", sv: "" } }));
+}
+var key = (c) => `${c.storage ?? "cookie"}:${c.name}`;
+function merge(existing2, found2) {
+  const old = new Map(existing2.map((c) => [key(c), c]));
+  const now = new Set(found2.map(key));
+  const added2 = found2.filter((c) => !old.has(key(c)));
+  const missing2 = existing2.filter((c) => !now.has(key(c)));
+  const list2 = [
+    ...existing2.map((c) => {
+      const f = found2.find((x) => key(x) === key(c));
+      return f ? { ...c, duration: f.duration } : c;
+    }),
+    ...added2
+  ];
+  return { list: list2, added: added2, missing: missing2 };
+}
+
+// src/cli.ts
+var HELP = `Usage: keksi scan <url> [options]
+
+Lists the cookies and storage your site sets without consent, for the "Necessary" section.
+
+Options:
+  --out <file>     Output file (default: keksi.cookies.json)
+  --pages <n>      Most pages to visit (default: 20)
+  --cookie <name>  Consent cookie name, if changed (default: keksi)
+  --check          Write nothing; exit 1 if the file is missing entries
+`;
+var { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    out: { type: "string", default: "keksi.cookies.json" },
+    pages: { type: "string", default: "20" },
+    cookie: { type: "string", default: "keksi" },
+    check: { type: "boolean", default: false },
+    help: { type: "boolean", short: "h", default: false }
+  }
+});
+var [command, url] = positionals;
+if (values.help || command !== "scan" || !url) {
+  process.stdout.write(HELP);
+  process.exit(values.help ? 0 : 1);
+}
+var existing = existsSync(values.out) ? JSON.parse(readFileSync(values.out, "utf8")) : [];
+var found = await scan(url, { pages: Number(values.pages), cookieName: values.cookie });
+var { list, added, missing } = merge(existing, found);
+var label = (c) => `${c.name}${c.storage ? ` (${c.storage})` : ""}`;
+var blank = (c) => !c.purpose || typeof c.purpose === "object" && !Object.values(c.purpose).some(Boolean);
+for (const c of added) console.log(`+ ${label(c)}`);
+for (const c of missing) console.log(`? ${label(c)}: not seen, remove it unless it's set after login or on unscanned pages`);
+if (values.check) {
+  if (added.length) {
+    console.error(`${values.out} is missing ${added.length} entr${added.length === 1 ? "y" : "ies"}. Run keksi scan ${url}`);
+    process.exit(1);
+  }
+  console.log(`${values.out} is up to date.`);
+} else {
+  writeFileSync(values.out, `${JSON.stringify(list, null, 2)}
+`);
+  const todo = list.filter(blank);
+  console.log(`Wrote ${list.length} entr${list.length === 1 ? "y" : "ies"} to ${values.out}.`);
+  if (todo.length) console.log(`Add a purpose for: ${todo.map(label).join(", ")}`);
+}

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+import { type Texts } from './i18n.js';
+import type { Category, KeksiConfig, Locale, Provider, RuntimeData } from './types.js';
+export declare function defineConfig(config: KeksiConfig): KeksiConfig;
+export declare function activeProviders(config: KeksiConfig): Provider[];
+export declare function categoriesOf(config: KeksiConfig): Category[];
+export declare function textsFor(config: KeksiConfig, locale: Locale): Texts;
+/** Changes when a provider is added or removed, which asks everyone again. Ids and texts can change freely. */
+export declare function version(config: KeksiConfig): string;
+export declare function runtimeData(config: KeksiConfig, locale: Locale): RuntimeData;

package/dist/i18n.d.ts

@@ -0,0 +1,41 @@
+import type { Locale } from './types.js';
+declare const fi: {
+    title: string;
+    intro: string;
+    transfer: string;
+    more: string;
+    accept: string;
+    reject: string;
+    settings: string;
+    settingsTitle: string;
+    save: string;
+    close: string;
+    alwaysOn: string;
+    necessary: string;
+    necessaryInfo: string;
+    analytics: string;
+    analyticsInfo: string;
+    marketing: string;
+    marketingInfo: string;
+    providers: string;
+    thisSite: string;
+    consentPurpose: string;
+    privacyPolicy: string;
+    dpf: string;
+    name: string;
+    duration: string;
+    purpose: string;
+    setBy: string;
+    session: string;
+    persistent: string;
+    y: string;
+    mo: string;
+    d: string;
+    min: string;
+    ytText: string;
+    ytButton: string;
+    ytOpen: string;
+};
+export type Texts = typeof fi;
+export declare const texts: Record<Locale, Texts>;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { defineConfig, version } from './config.js';
+export { cookieTable, renderKeksi, type CookieTableOptions, type RenderOptions } from './render.js';
+export { providers } from './providers.js';
+export type { KeksiApi } from './runtime.js';
+export type { Texts } from './i18n.js';
+export type * from './types.js';