Repository Public
1// Webhooks (pur, sans DOM) : catalogue des événements, types de l'API (docs/API.md §11), pré-vérification de l'URL de destination2// pour un message clair avant l'envoi (le serveur reste seul juge : il résout le DNS et revérifie à chaque livraison),3// forme d'une entrée « hôte:port » de la liste des destinations internes, exemples de vérification de signature (§11.4).45/** Événements auxquels un webhook peut s'abonner (même ordre que le serveur, `EVENT_TYPES`). */6export const EVENT_TYPES = [7 "message.received", "message.sent", "message.delivered", "message.deferred", "message.bounced", "message.failed", "message.read", "message.deleted",8 "draft.created", "address.created", "address.suspended", "rule.matched",9] as const10export type EventType = (typeof EVENT_TYPES)[number]11export const isEventType = (s: string): s is EventType => (EVENT_TYPES as readonly string[]).includes(s)12/** Clé i18n de l'explication d'un événement : `adm.webhooks.event.message_received`, etc. */13type Under<S extends string> = S extends `${infer A}.${infer B}` ? `${A}_${B}` : S14export const eventKey = <E extends EventType>(e: E) => `adm.webhooks.event.${e.replace(".", "_")}` as `adm.webhooks.event.${Under<E>}`1516export interface Webhook {17 id: string18 name: string19 url: string20 events: string[]21 address_ids: string[]22 include_content: boolean23 active: boolean24 owner: "key" | "admin"25 key_id: string | null26 created_at: string27 updated_at: string28 /** présent seulement à la création et après une rotation ; jamais conservé côté client */29 secret?: string30}31export type DeliveryStatus = "pending" | "retrying" | "delivered" | "failed"32export const DELIVERY_STATUSES: readonly DeliveryStatus[] = ["pending", "retrying", "delivered", "failed"]33export interface Delivery {34 id: string35 webhook_id: string36 event_id: string37 event_type: string38 status: DeliveryStatus39 attempt: number40 next_attempt_at: string | null41 last_status: number | null42 last_error: string | null43 delivered_at: string | null44 created_at: string45}46export interface TestResult {47 delivery: Delivery48 http_status: number | null49 error: string | null50}51export interface AllowEntry {52 host_port: string53 note: string54 created_at: string55}5657/** Ton d'une pastille d'état (l'état est toujours écrit en toutes lettres à côté). */58export const deliveryTone = (s: string): "ok" | "warn" | "danger" | "" => (s === "delivered" ? "ok" : s === "failed" ? "danger" : s === "retrying" ? "warn" : "")5960// ---------------------------------------------------------------- liste des destinations internes61/** Même forme que le serveur (`/api/admin/webhook-allowlist`) : hôte ou adresse IPv4, ou `[IPv6]`, puis `:port`. */62const HOST_PORT = /^(\[[0-9a-f:]+\]|[a-z0-9.-]{1,253}):(\d{1,5})$/63/** Entrée normalisée (minuscules, sans crochets) ou null si la forme est refusée. */64export function normalizeHostPort(raw: string): string | null {65 const s = raw.trim().toLowerCase()66 const m = HOST_PORT.exec(s)67 if (!m) return null68 const port = Number(m[2])69 if (port < 1 || port > 65535) return null70 return `${m[1].replace(/^\[|\]$/g, "")}:${port}`71}7273// ---------------------------------------------------------------- pré-vérification d'une URL74const v4 = (host: string): number[] | null => {75 const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host)76 if (!m) return null77 const p = m.slice(1).map(Number)78 return p.every((n) => n <= 255) ? p : null79}80/** Adresse IPv4 littérale non publique : boucle locale, privée (RFC 1918), lien local, CGNAT, multidiffusion, réservée. */81export function isPrivateV4(host: string): boolean {82 const p = v4(host)83 if (!p) return false84 const [a, b] = p85 return a === 0 || a === 10 || a === 127 || (a === 100 && b >= 64 && b <= 127) || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 192 && b === 0) || (a === 198 && (b === 18 || b === 19)) || a >= 22486}87/** Adresse IPv6 littérale manifestement locale : `::`, `::1`, lien local fe80::/10, locale unique fc00::/7, multidiffusion, IPv4 projetée privée. */88export function isPrivateV6(host: string): boolean {89 const h = host.toLowerCase()90 if (!h.includes(":")) return false91 if (h === "::" || h === "::1") return true92 if (/^fe[89ab][0-9a-f]:/.test(h) || /^f[cd][0-9a-f]{2}:/.test(h) || /^ff[0-9a-f]{2}:/.test(h)) return true93 const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/.exec(h)94 if (mapped) return isPrivateV4(mapped[1])95 // forme hexadécimale que produit l'analyseur d'URL : ::ffff:7f00:196 const hex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(h)97 if (hex) {98 const hi = parseInt(hex[1], 16)99 const lo = parseInt(hex[2], 16)100 return isPrivateV4(`${hi >> 8}.${hi & 255}.${lo >> 8}.${lo & 255}`)101 }102 return false103}104105export type UrlProblem =106 /** illisible, ou ni http ni https : le serveur répondrait 400 invalid_url */107 | "invalid"108 | "scheme"109 | "credentials"110 | "token"111 /** le serveur répondrait 403 forbidden_destination, sauf entrée dans la liste des destinations internes */112 | "not_https_443"113 | "private"114export interface UrlCheck {115 /** l'URL peut être envoyée au serveur (qui décide) */116 ok: boolean117 /** refus certain avant même l'envoi (forme de l'URL) */118 blocking: boolean119 problem: UrlProblem | null120 /** `hôte:port` tel que la liste des destinations internes doit le porter */121 hostPort: string | null122 allowlisted: boolean123}124125/**126 * Applique à une URL les règles de forme de la garde SSRF. Ce qui dépend du DNS (un nom qui résout vers une adresse127 * privée, un nom inconnu) ne peut pas être vu d'ici : seul le serveur le sait.128 */129export function checkWebhookUrl(raw: string, allowlist: readonly string[] = []): UrlCheck {130 const fail = (problem: UrlProblem, blocking: boolean, hostPort: string | null = null): UrlCheck => ({ ok: !blocking, blocking, problem, hostPort, allowlisted: false })131 let u: URL132 try {133 u = new URL(raw.trim())134 } catch {135 return fail("invalid", true)136 }137 if (u.protocol !== "https:" && u.protocol !== "http:") return fail("scheme", true)138 if (u.username || u.password) return fail("credentials", true)139 if (/sp[mx]_[a-z0-9]/i.test(raw)) return fail("token", true)140 const host = u.hostname.replace(/^\[|\]$/g, "").toLowerCase()141 if (!host) return fail("invalid", true)142 const port = u.port || (u.protocol === "https:" ? "443" : "80")143 const hostPort = `${host}:${port}`144 if (allowlist.some((a) => a.toLowerCase() === hostPort)) return { ok: true, blocking: false, problem: null, hostPort, allowlisted: true }145 if (u.protocol !== "https:" || port !== "443") return fail("not_https_443", false, hostPort)146 if (host === "localhost" || host.endsWith(".localhost") || isPrivateV4(host) || isPrivateV6(host)) return fail("private", false, hostPort)147 return { ok: true, blocking: false, problem: null, hostPort, allowlisted: false }148}149150// ---------------------------------------------------------------- vérification côté récepteur (docs/API.md §11.4)151export const SNIPPET_NODE = `import crypto from "node:crypto"152153function verify(secret, header, rawBody, toleranceSec = 300) {154 const m = /^t=(\\d+),v1=([0-9a-f]{64})$/.exec(header ?? "")155 if (!m) return false156 if (Math.abs(Date.now() / 1000 - Number(m[1])) > toleranceSec) return false157 const expected = crypto.createHmac("sha256", secret).update(\`\${m[1]}.\${rawBody}\`).digest()158 const given = Buffer.from(m[2], "hex")159 return given.length === expected.length && crypto.timingSafeEqual(given, expected)160}161162// express: app.post("/hook", express.raw({ type: "application/json" }), (req, res) => {163// if (!verify(SECRET, req.get("SPMail-Signature"), req.body.toString("utf8"))) return res.sendStatus(400)164// const event = JSON.parse(req.body); /* dedupe on event.id */ res.sendStatus(204) })165`166export const SNIPPET_PYTHON = `import hashlib, hmac, re, time167168def verify(secret: str, header: str, raw_body: bytes, tolerance: int = 300) -> bool:169 m = re.fullmatch(r"t=(\\d+),v1=([0-9a-f]{64})", header or "")170 if not m or abs(time.time() - int(m.group(1))) > tolerance:171 return False172 expected = hmac.new(secret.encode(), m.group(1).encode() + b"." + raw_body, hashlib.sha256).hexdigest()173 return hmac.compare_digest(expected, m.group(2))174`175