Repository Public
1// /api/v1 — webhooks : garde SSRF, signature, événements réels (reçu, envoyé, remis, lu, supprimé), filtre par adresse,2// nouvelles tentatives avec recul, rejeu, et persistance des files à travers un redémarrage du serveur.3import assert from "node:assert/strict"4import { after, before, test } from "node:test"5import { ApiKey, Client, Receiver, expectV1, haltServer, reauth, restartServer, sleep, sql, startServer, stopServer, until } from "../harness"6import { signPayload, verifySignature } from "../../server/src/webhooks"7import { addr, mkKey, mkMailbox, purgeAll, sendAndWait, sess, setupAdmin, type Box } from "./v1-helpers"89let admin: Client10let W1: Box, W2: Box11let alias = ""12const ALIAS = addr("hooks")13let kw: ApiKey, k2: ApiKey14const rx = new Receiver(), rxContent = new Receiver(), rxAlias = new Receiver()15let hook: any, secret = ""1617async function rejects(p: Promise<unknown>, status: number, code?: string) {18 await assert.rejects(p, (e: any) => e.status === status && (!code || e.code === code))19}20const allow = async (r: Receiver) => { await reauth(admin); await admin.call("POST", "/api/admin/webhook-allowlist", { host_port: `127.0.0.1:${r.port}`, note: "récepteur de test" }) }21const waitHit = (r: Receiver, pred: (h: any) => boolean, what: string, timeout = 30000) => until(async () => r.hits.find((h) => h.json && pred(h.json)), what, timeout)2223before(async () => {24 await startServer()25 admin = await setupAdmin()26 ;[W1, W2] = await Promise.all([mkMailbox(admin, "w1"), mkMailbox(admin, "w2")])27 alias = (await sess(admin, "POST", "/aliases", { address: ALIAS, mailbox: W1.address })).id28 kw = await mkKey(admin, { scopes: ["mail.webhooks.manage", "mail.send", "mail.read", "mail.modify", "mail.delete"], addresses: [W1.addressId] })29 k2 = await mkKey(admin, { scopes: ["mail.send", "mail.read", "mail.webhooks.manage"], addresses: [W2.addressId] })30 await Promise.all([rx.start(), rxContent.start(), rxAlias.start()])31})32after(async () => {33 await Promise.all([rx.stop(), rxContent.stop(), rxAlias.stop()])34 await purgeAll(admin)35 await stopServer()36})3738test("garde SSRF : adresses privées, noms résolvant en privé, schémas, identifiants ; liste d'autorisation explicite par hôte:port", async () => {39 const mk = (url: string) => kw.call("POST", "/webhooks", { name: "x", url, events: ["message.received"] })40 for (const url of [rx.url, "http://127.0.0.1/h", "https://[::ffff:7f00:1]/h", "https://[0:0:0:0:0:ffff:10.0.0.1]/h", "https://[64:ff9b::7f00:1]/h", "https://2130706433/h", "https://0x7f.1/h", "https://127.0.0.1/h", "https://10.67.0.1:8080/h", "https://10.0.0.5/h", "https://192.168.2.1/h", "https://172.16.0.1/h", "https://169.254.169.254/latest/meta-data/", "https://[::1]/h", "https://[fd00::1]/h", "https://[::ffff:127.0.0.1]/h", "https://100.64.0.1/h", "https://0.0.0.0/h", "https://localhost/h", "https://localtest.me/h", "http://example.org/h", "https://example.org:8443/h"])41 await expectV1(mk(url), 403, "forbidden_destination")42 for (const url of ["ftp://example.org/h", "file:///etc/passwd", "https://user:pw@example.org/h", "not a url", "javascript:alert(1)"]) await expectV1(mk(url), 400, "invalid_url")43 await expectV1(kw.call("POST", "/webhooks", { name: "x", url: "https://example.org/h", events: ["message.exploded"] }), 400, "invalid_request")44 // la liste d'autorisation est gérée par un administrateur réauthentifié, et porte sur un hôte:port exact45 await sql`update sessions set reauth_at = null`46 await rejects(admin.call("POST", "/api/admin/webhook-allowlist", { host_port: `127.0.0.1:${rx.port}` }), 403, "reauth_required")47 await allow(rx)48 await allow(rxContent)49 await allow(rxAlias)50 assert.equal((await admin.call("GET", "/api/admin/webhook-allowlist")).length, 3)51 await expectV1(mk(`http://127.0.0.1:${rx.port + 1 === rxContent.port || rx.port + 1 === rxAlias.port ? 9 : rx.port + 1}/h`), 403, "forbidden_destination")52 hook = await kw.call("POST", "/webhooks", { name: "principal", url: rx.url, events: ["message.received", "message.sent", "message.delivered", "message.bounced", "message.read", "message.deleted", "draft.created"] })53 secret = hook.secret54 assert.match(secret, /^whsec_/)55 assert.equal(hook.include_content, false)56 // le secret n'est montré qu'une fois ; il est scellé en base57 assert.equal((await kw.call("GET", `/webhooks/${hook.id}`)).secret, undefined)58 assert.ok(!JSON.stringify(await sql`select * from webhooks`).includes(secret))59 // cloisonnement : une autre clé ne voit ni ne touche ce webhook60 await expectV1(k2.call("GET", `/webhooks/${hook.id}`), 404, "not_found")61 await expectV1(k2.call("DELETE", `/webhooks/${hook.id}`), 404, "not_found")62 assert.deepEqual((await k2.call("GET", "/webhooks")).data, [])63 // filtre d'adresses hors de la liste de la clé : refusé ; contenu : scope mail.read exigé64 await expectV1(kw.call("POST", "/webhooks", { name: "x", url: rx.url, events: ["message.received"], address_ids: [W2.addressId] }), 403, "address_not_allowed")65 const noRead = await mkKey(admin, { scopes: ["mail.webhooks.manage"], addresses: [W1.addressId] })66 await expectV1(noRead.call("POST", "/webhooks", { name: "x", url: rx.url, events: ["message.received"], include_content: true }), 403, "insufficient_scope")67})6869test("signature HMAC et fenêtre de 5 minutes (fonction de référence)", () => {70 const body = JSON.stringify({ id: "evt_x", type: "message.received" })71 const t = 1_800_000_00072 const h = signPayload("whsec_test", body, t)73 assert.match(h, /^t=1800000000,v1=[0-9a-f]{64}$/)74 assert.equal(verifySignature("whsec_test", h, body, 300, t + 299), true)75 assert.equal(verifySignature("whsec_test", h, body, 300, t + 301), false, "rejeu après 5 minutes")76 assert.equal(verifySignature("whsec_test", h, body, 300, t - 301), false)77 assert.equal(verifySignature("whsec_autre", h, body, 300, t), false)78 assert.equal(verifySignature("whsec_test", h, body + " ", 300, t), false, "corps altéré")79 assert.equal(verifySignature("whsec_test", h.replace("t=1800000000", "t=1800000001"), body, 300, t), false, "horodatage altéré")80 assert.equal(verifySignature("whsec_test", "v1=abc", body, 300, t), false)81})8283test("événements réels : reçu, envoyé, remis, lu, supprimé — signés, sans contenu par défaut", async () => {84 // second webhook, administrateur, avec contenu ; troisième, limité à l'alias85 const withContent = await sess(admin, "POST", "/webhooks", { name: "contenu", url: rxContent.url, events: ["message.received"], include_content: true })86 assert.equal(withContent.owner, "admin")87 const onlyAlias = await sess(admin, "POST", "/webhooks", { name: "alias", url: rxAlias.url, events: ["message.received"], address_ids: [alias] })8889 await sendAndWait(k2, { from: W2.address, to: [W1.address], subject: "Sujet confidentiel 1", text: "corps confidentiel" })90 const hit = await waitHit(rx, (j) => j.type === "message.received" && j.address === W1.address, "message.received")91 // en-têtes et signature92 assert.equal(verifySignature(secret, String(hit.headers["spmail-signature"]), hit.body), true)93 assert.equal(hit.headers["spmail-event-type"], "message.received")94 assert.equal(hit.headers["spmail-event-id"], hit.json.id)95 assert.equal(hit.headers["spmail-delivery-attempt"], "1")96 assert.match(hit.json.id, /^evt_/)97 // charge : identifiants et adresses seulement — ni sujet, ni aperçu, ni corps98 assert.deepEqual(Object.keys(hit.json).sort(), ["address", "data", "id", "mailbox", "occurred_at", "type"])99 assert.deepEqual(Object.keys(hit.json.data).sort(), ["address", "cc", "delivered_to", "folders", "from", "has_attachment", "message_id", "received_at", "size", "thread_id", "to"])100 assert.deepEqual(hit.json.data.from, [W2.address])101 assert.deepEqual(hit.json.data.folders, ["inbox"])102 assert.ok(!hit.body.includes("confidentiel"))103 assert.equal((await kw.call("GET", `/messages/${hit.json.data.message_id}`)).subject, "Sujet confidentiel 1")104 // avec include_content : sujet et aperçu en plus105 const c = await waitHit(rxContent, (j) => j.type === "message.received" && j.data.subject === "Sujet confidentiel 1", "message.received avec contenu")106 assert.match(c.json.data.preview, /corps confidentiel/)107 // le webhook filtré sur l'alias n'a rien reçu pour l'adresse principale ; il reçoit ce qui est remis à l'alias108 await sendAndWait(k2, { from: W2.address, to: [ALIAS], subject: "pour l'alias", text: "x" })109 const a = await waitHit(rxAlias, (j) => j.type === "message.received", "message.received filtré")110 assert.equal(a.json.address, ALIAS)111 assert.deepEqual(a.json.data.delivered_to, [ALIAS])112 await waitHit(rx, (j) => j.type === "message.received" && j.address === ALIAS, "le webhook de la boîte entière voit aussi l'alias")113 assert.equal(rxAlias.hits.filter((h) => h.json?.address === W1.address).length, 0)114115 // envoi par la clé : message.sent puis message.delivered, avec l'état par destinataire116 const o = await sendAndWait(kw, { from: W1.address, to: [W2.address], subject: "sortant", text: "x" })117 const sent = await waitHit(rx, (j) => j.type === "message.sent" && j.data.outbound_id === o.id, "message.sent")118 assert.equal(sent.json.data.status, "sent")119 const delivered = await waitHit(rx, (j) => j.type === "message.delivered" && j.data.outbound_id === o.id, "message.delivered")120 assert.deepEqual(delivered.json.data.recipients.map((r: any) => [r.address, r.status]), [[W2.address, "delivered"]])121 assert.match(delivered.json.data.recipients[0].smtp_reply, /^250/)122 // rejet : message.bounced123 const b = await sendAndWait(kw, { from: W1.address, to: [addr("nobody-here")], subject: "rejeté", text: "x" })124 await waitHit(rx, (j) => j.type === "message.bounced" && j.data.outbound_id === b.id, "message.bounced")125 // brouillon126 const d = await kw.res("POST", "/messages/send", { from: W1.address, to: [W2.address], subject: "brouillon", text: "x", draft: true })127 // (la clé n'a pas mail.drafts : refus, donc aucun événement)128 assert.equal(d.status, 403)129130 // lu puis supprimé (corbeille), puis supprimé définitivement131 const mid = hit.json.data.message_id132 await kw.call("PATCH", `/messages/${mid}`, { unread: false })133 await waitHit(rx, (j) => j.type === "message.read" && j.data.message_id === mid, "message.read")134 await kw.call("DELETE", `/messages/${mid}`, {})135 const del = await waitHit(rx, (j) => j.type === "message.deleted" && j.data.message_id === mid, "message.deleted (corbeille)")136 assert.equal(del.json.data.permanent, false)137 await kw.call("DELETE", `/messages/${mid}?permanent=true`, { confirm: "permanently-delete" })138 await waitHit(rx, (j) => j.type === "message.deleted" && j.data.message_id === mid && j.data.permanent === true, "message.deleted (définitif)")139 // chaque événement n'a été livré qu'une fois à ce webhook140 const ids = rx.hits.map((h) => h.json.id)141 assert.equal(new Set(ids).size, ids.length)142 // la clé de la boîte W2 ne voit aucun événement de W1 ; GET /events ne rend jamais de contenu143 const evW2 = (await k2.call("GET", "/events?limit=100")).data144 assert.ok(evW2.length > 0 && evW2.every((e: any) => e.mailbox === W2.address))145 const evW1 = (await kw.call("GET", "/events?limit=100")).data146 assert.ok(evW1.some((e: any) => e.type === "message.read") && !JSON.stringify(evW1).includes("confidentiel"))147 const p1 = await kw.call("GET", "/events?limit=2")148 const p2 = await kw.call("GET", `/events?limit=2&cursor=${p1.next_cursor}`)149 assert.ok(p2.data.length > 0 && p2.data.every((e: any) => !p1.data.some((x: any) => x.id === e.id)))150 await sess(admin, "DELETE", `/webhooks/${withContent.id}`)151 await sess(admin, "DELETE", `/webhooks/${onlyAlias.id}`)152})153154test("une clé limitée à un alias ne reçoit par webhook que les événements de cet alias", async () => {155 const r = new Receiver()156 await r.start()157 await allow(r)158 const ka = await mkKey(admin, { scopes: ["mail.webhooks.manage", "mail.read"], addresses: [alias] })159 const h = await ka.call("POST", "/webhooks", { name: "alias seul", url: r.url, events: ["message.received"] })160 await sendAndWait(k2, { from: W2.address, to: [W1.address], subject: "principal bis", text: "x" })161 await sendAndWait(k2, { from: W2.address, to: [ALIAS], subject: "alias bis", text: "x" })162 await waitHit(r, (j) => j.type === "message.received" && j.address === ALIAS, "événement de l'alias")163 await until(async () => (await kw.call("GET", "/messages?folder=inbox&limit=50")).data.some((m: any) => m.subject === "principal bis"), "message principal arrivé")164 await sleep(1500)165 assert.deepEqual([...new Set(r.hits.map((x) => x.json.address))], [ALIAS])166 // une clé révoquée ne reçoit plus rien167 await admin.call("DELETE", `/api/admin/api-keys/${ka.id}`)168 const n = r.hits.length169 await sendAndWait(k2, { from: W2.address, to: [ALIAS], subject: "alias ter", text: "x" })170 await until(async () => rx.hits.filter((x) => x.json?.type === "message.received" && x.json.address === ALIAS).length >= 3, "événement vu par le webhook principal")171 await sleep(1000)172 assert.equal(r.hits.length, n)173 await r.stop()174 void h175})176177test("échec du récepteur : nouvelles tentatives avec recul, puis abandon ; rejeu manuel ; redirection non suivie ; test", async () => {178 // deux réponses 500 puis 200 : livré à la troisième tentative (recul de test : 2 s, 2 s)179 rx.hits.length = 0180 rx.script = [500, 500]181 const t0 = Date.now()182 await sendAndWait(k2, { from: W2.address, to: [W1.address], subject: "tentatives", text: "x" })183 const ok = await until(async () => {184 const d = (await kw.call("GET", `/webhooks/${hook.id}/deliveries?status=delivered&limit=5`)).data.find((x: any) => x.attempt === 3)185 return d186 }, "livraison à la 3e tentative", 30000)187 assert.ok(Date.now() - t0 >= 3500, "le recul a été respecté")188 const same = rx.hits.filter((h) => h.json.id === ok.event_id)189 assert.deepEqual(same.map((h) => h.headers["spmail-delivery-attempt"]), ["1", "2", "3"])190 assert.ok(same.every((h) => verifySignature(secret, String(h.headers["spmail-signature"]), h.body)))191 // trois échecs : abandon (failed), visible dans les livraisons et dans les métriques192 rx.script = [500, 503, 500]193 await sendAndWait(k2, { from: W2.address, to: [W1.address], subject: "abandon", text: "x" })194 const failed = await until(async () => (await kw.call("GET", `/webhooks/${hook.id}/deliveries?status=failed`)).data[0], "abandon après 3 tentatives", 30000)195 assert.equal(failed.attempt, 3)196 assert.equal(failed.last_status, 500)197 assert.equal(failed.last_error, "http_500")198 assert.ok((await admin.call("GET", "/api/admin/metrics")).webhook_backlog.failed.count >= 1)199 // rejeu manuel : même événement, livré200 const before = rx.hits.length201 const re = await kw.call("POST", `/webhook-deliveries/${failed.id}/replay`, {})202 assert.equal(re.status, "pending")203 await expectV1(k2.call("POST", `/webhook-deliveries/${failed.id}/replay`, {}), 404, "not_found")204 await until(async () => (await kw.call("GET", `/webhooks/${hook.id}/deliveries?status=delivered&limit=50`)).data.find((x: any) => x.id === failed.id), "rejeu livré")205 assert.equal(rx.hits[rx.hits.length - 1].json.id, failed.event_id)206 assert.ok(rx.hits.length > before)207 // redirection : jamais suivie, comptée comme un échec208 rx.script = [302]209 const t = await kw.call("POST", `/webhooks/${hook.id}/test`, {})210 assert.equal(t.http_status, 302)211 assert.equal(t.error, "redirect_not_followed")212 assert.equal(t.delivery.status, "retrying")213 // test manuel : événement webhook.test signé214 const n = rx.hits.length215 await until(async () => rx.hits.length > n && rx.hits[rx.hits.length - 1].json.type === "webhook.test", "nouvelle tentative du test")216 const t2 = await kw.call("POST", `/webhooks/${hook.id}/test`, {})217 assert.equal(t2.delivery.status, "delivered")218 assert.equal(t2.http_status, 200)219 // pagination des livraisons220 const p1 = await kw.call("GET", `/webhooks/${hook.id}/deliveries?limit=3`)221 const p2 = await kw.call("GET", `/webhooks/${hook.id}/deliveries?limit=3&cursor=${p1.next_cursor}`)222 assert.ok(p1.has_more && p2.data.every((d: any) => !p1.data.some((x: any) => x.id === d.id)))223 // rotation du secret : l'ancien ne vérifie plus224 const rot = await kw.call("PATCH", `/webhooks/${hook.id}`, { rotate_secret: true })225 assert.ok(rot.secret && rot.secret !== secret)226 await kw.call("POST", `/webhooks/${hook.id}/test`, {})227 const last = rx.hits[rx.hits.length - 1]228 assert.equal(verifySignature(secret, String(last.headers["spmail-signature"]), last.body), false)229 assert.equal(verifySignature(rot.secret, String(last.headers["spmail-signature"]), last.body), true)230 secret = rot.secret231 await sql`update sessions set reauth_at = null`232 await expectV1(sess(admin, "PATCH", `/webhooks/${hook.id}`, { rotate_secret: true }), 403, "reauth_required")233 // désactivé : plus aucune livraison234 await kw.call("PATCH", `/webhooks/${hook.id}`, { active: false })235 const m = rx.hits.length236 await sendAndWait(k2, { from: W2.address, to: [W1.address], subject: "webhook inactif", text: "x" })237 await sleep(2500)238 assert.equal(rx.hits.length, m)239 await kw.call("PATCH", `/webhooks/${hook.id}`, { active: true })240})241242test("persistance : message programmé et livraison de webhook en attente survivent à l'arrêt du serveur", async () => {243 rx.hits.length = 0244 // 1. un message programmé dans 7 secondes245 const sched = await kw.call("POST", "/messages/send", { from: W1.address, to: [W2.address], subject: "programmé avant l'arrêt", text: "x", send_at: new Date(Date.now() + 7000).toISOString() })246 assert.equal(sched.status, "scheduled")247 // 2. une livraison de webhook en échec, à retenter dans 2 secondes248 rx.script = [500]249 const t = await kw.call("POST", `/webhooks/${hook.id}/test`, {})250 assert.equal(t.delivery.status, "retrying")251 // 3. un message arrive juste avant l'arrêt : son événement doit sortir après le redémarrage s'il n'a pas eu le temps avant252 await haltServer()253 const [o] = await sql`select status from outbound_messages where id = ${sched.id}`254 const [d] = await sql`select status, attempt from webhook_deliveries where id = ${t.delivery.id}`255 assert.equal(o.status, "scheduled")256 assert.deepEqual([d.status, d.attempt], ["retrying", 1])257 const hitsWhileDown = rx.hits.length258 await sleep(8000) // les deux échéances passent pendant que le serveur est arrêté259 assert.equal(rx.hits.length, hitsWhileDown, "rien ne se passe sans serveur")260 assert.equal((await sql`select status from outbound_messages where id = ${sched.id}`)[0].status, "scheduled")261 await restartServer()262 // après le redémarrage, les deux reprennent depuis la base263 const done = await until(async () => { const x = await kw.call("GET", `/messages/outbound/${sched.id}`); return x.status === "delivered" ? x : null }, "message programmé remis après redémarrage", 30000)264 assert.equal(done.attempts, 1, "soumis une seule fois")265 await until(async () => (await k2.call("GET", "/messages?folder=inbox&limit=50")).data.some((m: any) => m.subject === "programmé avant l'arrêt"), "réception du message programmé")266 const redelivered = await until(async () => (await kw.call("GET", `/webhooks/${hook.id}/deliveries?status=delivered&limit=50`)).data.find((x: any) => x.id === t.delivery.id), "livraison de webhook reprise", 30000)267 assert.equal(redelivered.attempt, 2)268 assert.ok(rx.hits.some((h) => h.json.id === t.delivery.event_id && h.headers["spmail-delivery-attempt"] === "2"))269 // le veilleur de réception reprend à son état persistant : aucun ancien message n'est réémis270 await waitHit(rx, (j) => j.type === "message.sent" && j.data.outbound_id === sched.id, "message.sent après redémarrage")271 await sleep(2500)272 const received = rx.hits.filter((h) => h.json.type === "message.received")273 assert.equal(received.length, 0, "aucun message.received rejoué pour les anciens messages")274 assert.equal((await sql`select resyncs from mailbox_sync where mailbox_id = ${W1.id}`)[0].resyncs, 0)275 // sans travailleurs (SPMAIL_WORKERS=off) : l'API répond, rien n'est traité276 await restartServer({ SPMAIL_WORKERS: "off" })277 assert.equal((await (await fetch(`http://localhost:${process.env.SPMAIL_TEST_PORT ?? 8741}/api/v1/health`)).json()).workers, "off")278 const off = await kw.call("POST", "/messages/send", { from: W1.address, to: [W2.address], subject: "sans travailleurs", text: "x", send_at: new Date(Date.now() + 1500).toISOString() })279 await sleep(4000)280 assert.equal((await kw.call("GET", `/messages/outbound/${off.id}`)).status, "scheduled")281 await kw.call("DELETE", `/messages/scheduled/${off.id}`)282 await restartServer()283})284