SPB Git

Repository Public

webhooks.ts 8.1 KB 175 lines typescript

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
Files main
Menu

Theme