cookiecrumbs 0.2.0

package/dist/config/src/webhooks.js

@@ -0,0 +1,309 @@
+// Standard Webhooks (https://www.standardwebhooks.com) — the one implementation shared by the
+// cc-worker dispatcher, the CLI (`cookiecrumbs verify-webhook`), the sample receiver in
+// docs/platform/samples/webhook-receiver.mjs and the tests.
+//
+//   webhook-id:        the delivery id (public.webhook_deliveries.id)
+//   webhook-timestamp: unix seconds
+//   webhook-signature: `v1,<base64>` (space separated when several keys are valid)
+//
+// The signature is HMAC-SHA256 over `${id}.${timestamp}.${body}`, keyed with the *raw bytes* of the
+// secret: a `whsec_`-prefixed secret is the base64 of those bytes, anything else is used as UTF-8.
+//
+// No imports: SHA-256, HMAC and base64 are implemented here so the module runs unchanged in Node,
+// Deno, the edge runtime and the browser, and so a customer can copy the verifier into any project.
+export const WEBHOOK_SIGNATURE_VERSION = "v1";
+/** Standard Webhooks recommends five minutes of clock tolerance. */
+export const WEBHOOK_TOLERANCE_SECONDS = 300;
+export const WEBHOOK_SECRET_PREFIX = "whsec_";
+export const WEBHOOK_ID_HEADER = "webhook-id";
+export const WEBHOOK_TIMESTAMP_HEADER = "webhook-timestamp";
+export const WEBHOOK_SIGNATURE_HEADER = "webhook-signature";
+// ---------------------------------------------------------------------------
+// SHA-256
+// ---------------------------------------------------------------------------
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+const rotr = (x, n) => ((x >>> n) | (x << (32 - n))) >>> 0;
+/** SHA-256 of `data`, as 32 bytes. */
+export function sha256(data) {
+    const h = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+    const len = data.length;
+    const padded = new Uint8Array((((len + 8) >> 6) + 1) * 64);
+    padded.set(data);
+    padded[len] = 0x80;
+    const view = new DataView(padded.buffer);
+    // length in bits, as a 64-bit big-endian number
+    view.setUint32(padded.length - 8, Math.floor(len / 0x20000000) >>> 0);
+    view.setUint32(padded.length - 4, ((len % 0x20000000) * 8) >>> 0);
+    const w = new Uint32Array(64);
+    for (let off = 0; off < padded.length; off += 64) {
+        for (let i = 0; i < 16; i++)
+            w[i] = view.getUint32(off + i * 4);
+        for (let i = 16; i < 64; i++) {
+            const x = w[i - 15];
+            const y = w[i - 2];
+            const s0 = (rotr(x, 7) ^ rotr(x, 18) ^ (x >>> 3)) >>> 0;
+            const s1 = (rotr(y, 17) ^ rotr(y, 19) ^ (y >>> 10)) >>> 0;
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+        }
+        let a = h[0];
+        let b = h[1];
+        let c = h[2];
+        let d = h[3];
+        let e = h[4];
+        let f = h[5];
+        let g = h[6];
+        let hh = h[7];
+        for (let i = 0; i < 64; i++) {
+            const s1 = (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) >>> 0;
+            const ch = ((e & f) ^ (~e & g)) >>> 0;
+            const t1 = (hh + s1 + ch + K[i] + w[i]) >>> 0;
+            const s0 = (rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) >>> 0;
+            const maj = ((a & b) ^ (a & c) ^ (b & c)) >>> 0;
+            const t2 = (s0 + maj) >>> 0;
+            hh = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        h[0] = (h[0] + a) >>> 0;
+        h[1] = (h[1] + b) >>> 0;
+        h[2] = (h[2] + c) >>> 0;
+        h[3] = (h[3] + d) >>> 0;
+        h[4] = (h[4] + e) >>> 0;
+        h[5] = (h[5] + f) >>> 0;
+        h[6] = (h[6] + g) >>> 0;
+        h[7] = (h[7] + hh) >>> 0;
+    }
+    const out = new Uint8Array(32);
+    const ov = new DataView(out.buffer);
+    for (let i = 0; i < 8; i++)
+        ov.setUint32(i * 4, h[i]);
+    return out;
+}
+/** HMAC-SHA256 (RFC 2104), as 32 bytes. */
+export function hmacSha256(key, message) {
+    const block = new Uint8Array(64);
+    if (key.length > 64)
+        block.set(sha256(key));
+    else
+        block.set(key);
+    const inner = new Uint8Array(64 + message.length);
+    const outer = new Uint8Array(64 + 32);
+    for (let i = 0; i < 64; i++) {
+        inner[i] = block[i] ^ 0x36;
+        outer[i] = block[i] ^ 0x5c;
+    }
+    inner.set(message, 64);
+    outer.set(sha256(inner), 64);
+    return sha256(outer);
+}
+// ---------------------------------------------------------------------------
+// base64 / utf-8 / hex helpers (no Buffer, no atob)
+// ---------------------------------------------------------------------------
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+export function toBase64(bytes) {
+    let out = "";
+    for (let i = 0; i < bytes.length; i += 3) {
+        const b0 = bytes[i];
+        const b1 = bytes[i + 1];
+        const b2 = bytes[i + 2];
+        out += B64[b0 >> 2];
+        out += B64[((b0 & 3) << 4) | ((b1 ?? 0) >> 4)];
+        out += b1 === undefined ? "=" : B64[((b1 & 15) << 2) | ((b2 ?? 0) >> 6)];
+        out += b2 === undefined ? "=" : B64[b2 & 63];
+    }
+    return out;
+}
+export function fromBase64(text) {
+    const clean = text.replace(/[\s=]/g, "").replace(/-/g, "+").replace(/_/g, "/");
+    const out = new Uint8Array(Math.floor((clean.length * 6) / 8));
+    let acc = 0;
+    let bits = 0;
+    let n = 0;
+    for (const ch of clean) {
+        const v = B64.indexOf(ch);
+        if (v < 0)
+            throw new Error("invalid base64");
+        acc = (acc << 6) | v;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[n++] = (acc >> bits) & 0xff;
+        }
+    }
+    return out.subarray(0, n);
+}
+export const toHex = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+const utf8 = (s) => new TextEncoder().encode(s);
+/** Length-independent, value-constant-time comparison of two ASCII strings. */
+export function timingSafeEqual(a, b) {
+    const x = utf8(a);
+    const y = utf8(b);
+    let diff = x.length ^ y.length;
+    const n = Math.max(x.length, y.length);
+    for (let i = 0; i < n; i++)
+        diff |= (x[i] ?? 0) ^ (y[i] ?? 0);
+    return diff === 0;
+}
+// ---------------------------------------------------------------------------
+// Secrets
+// ---------------------------------------------------------------------------
+/** The HMAC key of a secret: base64 body for `whsec_…`, raw UTF-8 otherwise. */
+export function webhookSecretKey(secret) {
+    const s = (secret ?? "").trim();
+    if (!s)
+        throw new Error("webhook secret is empty");
+    return s.startsWith(WEBHOOK_SECRET_PREFIX) ? fromBase64(s.slice(WEBHOOK_SECRET_PREFIX.length)) : utf8(s);
+}
+/**
+ * A new `whsec_` + base64(32 random bytes) secret. Uses the platform CSPRNG; throws when the runtime
+ * has none (the database generates the real secrets — this exists for tests and local receivers).
+ */
+export function generateWebhookSecret(bytes = 32) {
+    const c = globalThis.crypto;
+    if (!c?.getRandomValues)
+        throw new Error("no CSPRNG available in this runtime");
+    return WEBHOOK_SECRET_PREFIX + toBase64(c.getRandomValues(new Uint8Array(bytes)));
+}
+function unixSeconds(t) {
+    if (t === undefined || t === null || t === "")
+        return String(Math.floor(Date.now() / 1000));
+    if (t instanceof Date)
+        return String(Math.floor(t.getTime() / 1000));
+    const n = typeof t === "number" ? t : Number(t);
+    if (!Number.isFinite(n))
+        throw new Error(`invalid timestamp: ${String(t)}`);
+    // Anything past the year 33658 in seconds is really milliseconds.
+    return String(Math.floor(n > 1e12 ? n / 1000 : n));
+}
+export function signWebhook(input) {
+    const id = String(input.id ?? "");
+    if (!id)
+        throw new Error("webhook id is required");
+    const timestamp = unixSeconds(input.timestamp);
+    const body = input.body ?? "";
+    const signedContent = `${id}.${timestamp}.${body}`;
+    const mac = hmacSha256(webhookSecretKey(input.secret), utf8(signedContent));
+    const signature = `${WEBHOOK_SIGNATURE_VERSION},${toBase64(mac)}`;
+    return {
+        id,
+        timestamp,
+        signature,
+        signedContent,
+        headers: {
+            "content-type": "application/json; charset=utf-8",
+            [WEBHOOK_ID_HEADER]: id,
+            [WEBHOOK_TIMESTAMP_HEADER]: timestamp,
+            [WEBHOOK_SIGNATURE_HEADER]: signature,
+        },
+    };
+}
+function headerValue(headers, name) {
+    if (!headers)
+        return null;
+    const anyH = headers;
+    if (typeof anyH.get === "function") {
+        const v = anyH.get(name);
+        return v == null ? null : String(v);
+    }
+    const rec = headers;
+    for (const key of Object.keys(rec)) {
+        if (key.toLowerCase() !== name)
+            continue;
+        const v = rec[key];
+        if (v == null)
+            return null;
+        return Array.isArray(v) ? (v.length ? String(v[0]) : null) : String(v);
+    }
+    return null;
+}
+/**
+ * Verifies a Standard Webhooks request. Returns a result object rather than throwing so a receiver
+ * can log the reason and answer 400 without a try/catch.
+ */
+export function verifyWebhook(input) {
+    const id = headerValue(input.headers, WEBHOOK_ID_HEADER);
+    const ts = headerValue(input.headers, WEBHOOK_TIMESTAMP_HEADER);
+    const sigHeader = headerValue(input.headers, WEBHOOK_SIGNATURE_HEADER);
+    if (!id)
+        return { ok: false, reason: "missing_id", message: `No ${WEBHOOK_ID_HEADER} header.` };
+    if (!ts)
+        return { ok: false, reason: "missing_timestamp", message: `No ${WEBHOOK_TIMESTAMP_HEADER} header.` };
+    if (!sigHeader)
+        return { ok: false, reason: "missing_signature", message: `No ${WEBHOOK_SIGNATURE_HEADER} header.` };
+    const seconds = Number(ts);
+    if (!Number.isFinite(seconds) || !/^\d{1,15}$/.test(ts.trim())) {
+        return { ok: false, reason: "invalid_timestamp", message: `${WEBHOOK_TIMESTAMP_HEADER} must be unix seconds.` };
+    }
+    const tolerance = input.toleranceSeconds ?? WEBHOOK_TOLERANCE_SECONDS;
+    if (tolerance > 0) {
+        const nowSeconds = Math.floor((input.now ?? Date.now()) / 1000);
+        if (seconds < nowSeconds - tolerance) {
+            return { ok: false, reason: "timestamp_too_old", message: `Timestamp is ${nowSeconds - seconds} s old (tolerance ${tolerance} s).` };
+        }
+        if (seconds > nowSeconds + tolerance) {
+            return { ok: false, reason: "timestamp_too_new", message: `Timestamp is ${seconds - nowSeconds} s in the future (tolerance ${tolerance} s).` };
+        }
+    }
+    let expected;
+    try {
+        const mac = hmacSha256(webhookSecretKey(input.secret), utf8(`${id}.${ts}.${input.body ?? ""}`));
+        expected = toBase64(mac);
+    }
+    catch (e) {
+        return { ok: false, reason: "invalid_secret", message: e.message };
+    }
+    const parts = sigHeader.split(/\s+/).filter(Boolean);
+    let sawV1 = false;
+    let matched = false;
+    for (const part of parts) {
+        const comma = part.indexOf(",");
+        if (comma < 0)
+            continue;
+        if (part.slice(0, comma) !== WEBHOOK_SIGNATURE_VERSION)
+            continue;
+        sawV1 = true;
+        // No early exit: every v1 candidate is compared so the timing does not leak which one matched.
+        if (timingSafeEqual(part.slice(comma + 1), expected))
+            matched = true;
+    }
+    if (!sawV1)
+        return { ok: false, reason: "no_v1_signature", message: `${WEBHOOK_SIGNATURE_HEADER} carries no v1 signature.` };
+    if (!matched)
+        return { ok: false, reason: "signature_mismatch", message: "The v1 signature does not match the body." };
+    return { ok: true, id, timestamp: seconds, signature: `${WEBHOOK_SIGNATURE_VERSION},${expected}` };
+}
+/** The 12 CookieCrumbs event types (mirrors private.webhook_event_types() in migration 0036). */
+export const WEBHOOK_EVENT_TYPES = [
+    "scan.completed",
+    "scan.failed",
+    "tracker.new",
+    "issue.opened",
+    "issue.resolved",
+    "alert.raised",
+    "config.published",
+    "version.promoted",
+    "export.completed",
+    "declaration.updated",
+    "install.broken",
+    "plan.changed",
+];
+export function isWebhookEnvelope(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    return typeof v.id === "string" && typeof v.type === "string" && typeof v.created_at === "string" && typeof v.org_id === "string" && "data" in v;
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "cookiecrumbs",
+  "version": "0.2.0",
+  "description": "CookieCrumbs command line: push and pull banner configuration as code, publish versions, run hosted scans in CI, manage sites, services, schedules, issues, domains and templates, export consent logs and declarations",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "CookieCrumbs <hello@cookiecrumbs.eu> (https://cookiecrumbs.eu)",
+  "homepage": "https://cookiecrumbs.eu/docs/cli.html",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SimonCmd/CookieCrumbs.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/SimonCmd/CookieCrumbs/issues",
+    "email": "hello@cookiecrumbs.eu"
+  },
+  "keywords": [
+    "cookiecrumbs",
+    "cookie-consent",
+    "consent-management",
+    "cookie-banner",
+    "gdpr",
+    "eprivacy",
+    "consent-mode",
+    "tracker-scanner",
+    "cli",
+    "ci"
+  ],
+  "type": "module",
+  "bin": {
+    "cookiecrumbs": "./dist/cli/src/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "pretest": "npm run build",
+    "test": "tsx --test test/*.test.ts"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "commander": "^13.1.0",
+    "jiti": "^2.4.0",
+    "picocolors": "^1.1.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@cookiecrumbs/config": "0.2.0",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}