Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,56 @@
import { describe, expect, test } from "vitest";
import { verifyMailjetWebhookAuth, type MailjetWebhookAuthResult } from "./mailjet-webhook-auth.js";
const secret = "whsec_test_secret";
function basicHeader(username: string, password: string) {
return `Basic ${Buffer.from(`${username}:${password}`, "utf8").toString("base64")}`;
}
describe("verifyMailjetWebhookAuth", () => {
test("accepts a Basic-Auth header whose password matches the secret regardless of username", () => {
expect(verifyMailjetWebhookAuth({ secret, headers: { authorization: basicHeader("mailjet", secret) } })).toEqual({ ok: true });
expect(verifyMailjetWebhookAuth({ secret, headers: { authorization: basicHeader("anything", secret) } })).toEqual({ ok: true });
});
test("reads the Authorization header from a Headers instance case-insensitively", () => {
const headers = new Headers({ Authorization: basicHeader("mailjet", secret) });
expect(verifyMailjetWebhookAuth({ secret, headers })).toEqual({ ok: true });
});
test("returns missing-secret when no secret is configured", () => {
expect(verifyMailjetWebhookAuth({ secret: " ", headers: { authorization: basicHeader("mailjet", secret) } })).toEqual({
ok: false,
reason: "missing-secret",
});
expect(verifyMailjetWebhookAuth({ secret: undefined, headers: {} })).toEqual({ ok: false, reason: "missing-secret" });
});
test("returns missing-credentials when the Authorization header is absent", () => {
expect(verifyMailjetWebhookAuth({ secret, headers: {} })).toEqual({ ok: false, reason: "missing-credentials" });
});
test("returns malformed-credentials for non-Basic or undecodable headers", () => {
expect(verifyMailjetWebhookAuth({ secret, headers: { authorization: `Bearer ${secret}` } })).toEqual({ ok: false, reason: "malformed-credentials" });
expect(verifyMailjetWebhookAuth({ secret, headers: { authorization: "Basic not-base64!" } })).toEqual({ ok: false, reason: "malformed-credentials" });
// Decodes but carries no colon separator.
expect(verifyMailjetWebhookAuth({ secret, headers: { authorization: `Basic ${Buffer.from("nopassword", "utf8").toString("base64")}` } })).toEqual({
ok: false,
reason: "malformed-credentials",
});
});
test("returns credentials-mismatch for the wrong password", () => {
expect(verifyMailjetWebhookAuth({ secret, headers: { authorization: basicHeader("mailjet", "wrong-secret") } })).toEqual({
ok: false,
reason: "credentials-mismatch",
});
});
test("serializes failures without exposing the secret", () => {
const result: MailjetWebhookAuthResult = verifyMailjetWebhookAuth({ secret, headers: { authorization: basicHeader("mailjet", "wrong-secret") } });
const serialized = JSON.stringify(result);
expect(serialized).toBe(JSON.stringify({ ok: false, reason: "credentials-mismatch" }));
expect(serialized).not.toContain(secret);
});
});
@@ -0,0 +1,96 @@
import { timingSafeEqual } from "node:crypto";
/**
* Mailjet does not sign event/parse webhooks (there is no HMAC signature
* scheme on the payload). The supported way to authenticate inbound Mailjet
* webhooks is HTTP Basic Auth over HTTPS: the callback URL is configured as
* `https://mailjet:SECRET@host/...`, so Mailjet sends an
* `Authorization: Basic base64("mailjet:SECRET")` header. We validate the
* password portion against MAILJET_WEBHOOK_SECRET in constant time and ignore
* the username so operators can pick any.
*/
export type MailjetWebhookAuthFailureReason = "missing-secret" | "missing-credentials" | "malformed-credentials" | "credentials-mismatch";
export type MailjetWebhookAuthResult =
| {
ok: true;
}
| {
ok: false;
reason: MailjetWebhookAuthFailureReason;
};
export type VerifyMailjetWebhookAuthInput = {
secret: string | null | undefined;
headers: Headers | Record<string, string | string[] | null | undefined>;
};
export function verifyMailjetWebhookAuth({ secret, headers }: VerifyMailjetWebhookAuthInput): MailjetWebhookAuthResult {
if (!secret || secret.trim().length === 0) {
return { ok: false, reason: "missing-secret" };
}
const authorization = getHeader(headers, "authorization");
if (!authorization) {
return { ok: false, reason: "missing-credentials" };
}
const password = extractBasicAuthPassword(authorization);
if (password === undefined) {
return { ok: false, reason: "malformed-credentials" };
}
const provided = Buffer.from(password, "utf8");
const expected = Buffer.from(secret, "utf8");
if (provided.length !== expected.length || !timingSafeEqual(provided, expected)) {
return { ok: false, reason: "credentials-mismatch" };
}
return { ok: true };
}
function extractBasicAuthPassword(authorization: string): string | undefined {
const match = /^Basic\s+(.+)$/i.exec(authorization.trim());
if (!match) {
return undefined;
}
const encoded = match[1].trim();
if (!/^[A-Za-z0-9+/]+={0,2}$/.test(encoded) || encoded.length % 4 !== 0) {
return undefined;
}
const decoded = Buffer.from(encoded, "base64").toString("utf8");
const separatorIndex = decoded.indexOf(":");
if (separatorIndex === -1) {
return undefined;
}
return decoded.slice(separatorIndex + 1);
}
function getHeader(headers: VerifyMailjetWebhookAuthInput["headers"], name: string) {
if (headers instanceof Headers) {
return normalizeHeaderValue(headers.get(name));
}
const lowerName = name.toLowerCase();
for (const [key, value] of Object.entries(headers)) {
if (key.toLowerCase() === lowerName) {
return normalizeHeaderValue(value);
}
}
return undefined;
}
function normalizeHeaderValue(value: string | string[] | null | undefined) {
const normalized = Array.isArray(value) ? value.join(" ") : value;
if (typeof normalized !== "string") {
return undefined;
}
const trimmed = normalized.trim();
return trimmed.length > 0 && trimmed !== "undefined" ? trimmed : undefined;
}