Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -10,7 +10,8 @@
"./engine": "./src/engine.ts",
"./step-runner": "./src/step-runner.ts",
"./conditions": "./src/conditions.ts",
"./unsubscribe-token": "./src/unsubscribe-token.ts"
"./unsubscribe-token": "./src/unsubscribe-token.ts",
"./click-tracking-token": "./src/click-tracking-token.ts"
},
"scripts": {
"build": "pnpm run typecheck",
@@ -0,0 +1,28 @@
import { describe, expect, it } from "vitest";
import { buildTrackedClickUrl, signClickTarget, verifyClickTargetSignature } from "./click-tracking-token.js";
const secret = "0123456789abcdef0123456789abcdef0123456789abcdef";
describe("click tracking token", () => {
it("binds the target URL to the delivery id", () => {
const signature = signClickTarget({ deliveryId: "delivery_1", targetUrl: "https://example.test/path?a=1", secret });
expect(verifyClickTargetSignature({ deliveryId: "delivery_1", targetUrl: "https://example.test/path?a=1", signature, secret })).toBe(true);
expect(verifyClickTargetSignature({ deliveryId: "delivery_2", targetUrl: "https://example.test/path?a=1", signature, secret })).toBe(false);
expect(verifyClickTargetSignature({ deliveryId: "delivery_1", targetUrl: "https://evil.test/", signature, secret })).toBe(false);
});
it("fails closed for missing secrets and active URL schemes", () => {
expect(verifyClickTargetSignature({ deliveryId: "delivery_1", targetUrl: "https://example.test/", signature: "invalid", env: {} })).toBe(false);
expect(() => signClickTarget({ deliveryId: "delivery_1", targetUrl: "javascript:alert(1)", secret })).toThrow(TypeError);
});
it("builds a signed tracker URL", () => {
const tracked = new URL(buildTrackedClickUrl({ baseUrl: "https://app.example.test", deliveryId: "delivery_1", targetUrl: "https://example.test/a", secret }));
expect(tracked.pathname).toBe("/email/track-click/delivery_1");
expect(tracked.searchParams.get("u")).toBe("https://example.test/a");
expect(tracked.searchParams.get("s")).toBeTruthy();
});
});
@@ -0,0 +1,86 @@
import { createHmac, timingSafeEqual } from "node:crypto";
type EnvRecord = Record<string, string | undefined>;
const TOKEN_VERSION = "c1";
const MIN_SECRET_BYTES = 32;
const MAX_TARGET_URL_LENGTH = 4_096;
export class ClickTrackingSecretMissingError extends Error {
override readonly name = "ClickTrackingSecretMissingError";
constructor() {
super("MARKETING_TOKEN_SECRET env var is not set; cannot sign click tracking links.");
}
}
function getSecret(override?: string, env: EnvRecord = process.env): Buffer {
const raw = override ?? env.MARKETING_TOKEN_SECRET ?? env.LEAD_CONVERSION_SECRET;
if (!raw || Buffer.byteLength(raw, "utf8") < MIN_SECRET_BYTES) {
throw new ClickTrackingSecretMissingError();
}
return Buffer.from(raw, "utf8");
}
function canonicalPayload(deliveryId: string, targetUrl: string): string {
return `${TOKEN_VERSION}\0${deliveryId}\0${targetUrl}`;
}
export function isTrackableClickTarget(targetUrl: string): boolean {
if (!targetUrl || targetUrl.length > MAX_TARGET_URL_LENGTH) return false;
try {
const parsed = new URL(targetUrl);
return parsed.protocol === "https:" || parsed.protocol === "http:";
} catch {
return false;
}
}
export function signClickTarget(input: {
deliveryId: string;
targetUrl: string;
secret?: string;
env?: EnvRecord;
}): string {
if (!input.deliveryId || !isTrackableClickTarget(input.targetUrl)) {
throw new TypeError("signClickTarget requires a delivery id and an absolute HTTP(S) target URL.");
}
return createHmac("sha256", getSecret(input.secret, input.env))
.update(canonicalPayload(input.deliveryId, input.targetUrl))
.digest("base64url");
}
export function verifyClickTargetSignature(input: {
deliveryId: string;
targetUrl: string;
signature: string | null | undefined;
secret?: string;
env?: EnvRecord;
}): boolean {
if (!input.deliveryId || !input.signature || !/^[A-Za-z0-9_-]+$/u.test(input.signature) || !isTrackableClickTarget(input.targetUrl)) {
return false;
}
let expected: Buffer;
try {
expected = Buffer.from(signClickTarget(input), "base64url");
} catch {
return false;
}
const actual = Buffer.from(input.signature, "base64url");
return actual.length === expected.length && timingSafeEqual(actual, expected);
}
export function buildTrackedClickUrl(input: {
baseUrl: string;
deliveryId: string;
targetUrl: string;
secret?: string;
env?: EnvRecord;
}): string {
const signature = signClickTarget(input);
const url = new URL(`/email/track-click/${encodeURIComponent(input.deliveryId)}`, input.baseUrl);
url.searchParams.set("u", input.targetUrl);
url.searchParams.set("s", signature);
return url.toString();
}
@@ -44,3 +44,10 @@ export {
type SignUnsubscribeTokenInput,
type UnsubscribeTokenPayload,
} from "./unsubscribe-token.js";
export {
buildTrackedClickUrl,
ClickTrackingSecretMissingError,
isTrackableClickTarget,
signClickTarget,
verifyClickTargetSignature,
} from "./click-tracking-token.js";