diff --git a/apps/api/src/modules/mail/index.ts b/apps/api/src/modules/mail/index.ts index c0503b6..548d26d 100644 --- a/apps/api/src/modules/mail/index.ts +++ b/apps/api/src/modules/mail/index.ts @@ -130,7 +130,7 @@ export const mailModule: KcModule = { const params: unknown[] = [b.host, b.port, b.secureMode, b.username, b.folder, b.enabled ? 1 : 0, a.user.id]; if (b.password !== undefined) { sets.push('secrets_enc = ?'); params.push(b.password ? encrypt(JSON.stringify({ password: b.password })) : null); } // Verbindungsdaten geändert: nächster Abruf beginnt wieder beim aktuellen Postfachstand (kein Bestand wird nachverarbeitet) - if (b.host || b.username || b.password) { sets.push('last_uid = NULL'); } + if (b.host || b.username || b.password) { sets.push('last_uid = NULL', 'uid_validity = NULL', 'failed_uid = NULL', 'failed_attempts = 0'); } await run(`UPDATE imap_settings SET ${sets.join(', ')} WHERE id = 1`, params); await audit({ actorType: 'user', actorId: a.user.id, action: 'email.imap.update', resourceType: 'imap_settings', resourceId: '1', correlationId: req.correlationId, ip: clientIp(req), after: { ...b, password: b.password !== undefined ? (b.password ? '***' : null) : undefined } }); return { ok: true }; diff --git a/apps/api/src/modules/tickets/index.ts b/apps/api/src/modules/tickets/index.ts index f7bcc70..ba979ce 100644 --- a/apps/api/src/modules/tickets/index.ts +++ b/apps/api/src/modules/tickets/index.ts @@ -33,7 +33,7 @@ const TICKET_SQL = `SELECT t.*, g.name AS org_name, g.customer_number, u.name AS const messageView = (m: any, atts: any[] = []) => ({ id: m.id, authorId: m.author_id, authorName: m.author_name, authorKind: m.author_kind, body: m.body, internalNote: !!m.internal_note, createdAt: m.created_at, attachments: atts.filter((a) => a.message_id === m.id).map((a) => ({ id: a.id, filename: a.filename, contentType: a.content_type, sizeBytes: a.size_bytes })) }); const notify = (event: string, extra: Record, key: string, correlationId: string) => enqueue('discord.notify', { event, ...extra }, { idempotencyKey: key, correlationId }); -const mailTo = (to: string, template: string, vars: Record, key: string, correlationId: string) => enqueue('mail.template', { to, key: template, vars }, { idempotencyKey: key, correlationId }); +const mailTo = (to: string, template: string, vars: Record, key: string, correlationId: string, replyTicketId?: string) => enqueue('mail.template', { to, key: template, vars, replyTicketId }, { idempotencyKey: key, correlationId }); /** Meldet neue Nachrichten/Status auf CUSTOMER-sichtbare Zeilen; interne Notizen werden für Kunden ausgefiltert. */ async function loadTicket(id: string, forCustomer: boolean) { @@ -72,7 +72,7 @@ export const ticketsModule: KcModule = { await audit({ actorType: 'user', actorId: a.user.id, orgId: b.orgId, action: 'ticket.create', resourceType: 'ticket', resourceId: id, correlationId: req.correlationId, ip: clientIp(req), after: { number, subject: b.subject } }); if (!staff) { await notify('ticket.created', { number, subject: b.subject.slice(0, 100) }, `ticket.created:${id}`, req.correlationId); - await mailTo(a.user.email, 'ticket_created', { name: a.user.name, number, subject: b.subject, ticketLink: ticketLink(id) }, `mail:ticket.created:${id}`, req.correlationId); + await mailTo(a.user.email, 'ticket_created', { name: a.user.name, number, subject: b.subject, ticketLink: ticketLink(id) }, `mail:ticket.created:${id}`, req.correlationId, id); await enqueue('discord.ticket_sync', { ticketId: id, body: b.body, authorLabel: 'Kunde' }, { idempotencyKey: `discord:ticket.created:${id}`, correlationId: req.correlationId }); } return { id, number, messageId }; @@ -123,7 +123,7 @@ export const ticketsModule: KcModule = { let emailed = false; if (!b.internalNote && staff && b.notifyEmail) { const creator = await one('SELECT email, name FROM users WHERE id = ?', [t.created_by]); - if (creator) { await mailTo(creator.email, 'ticket_message', { name: creator.name, number: t.number, subject: t.subject, ticketLink: ticketLink(id) }, `mail:ticket.message:${id}:${Date.now()}`, req.correlationId); emailed = true; } + if (creator) { await mailTo(creator.email, 'ticket_message', { name: creator.name, number: t.number, subject: t.subject, ticketLink: ticketLink(id) }, `mail:ticket.message:${id}:${Date.now()}`, req.correlationId, id); emailed = true; } } return { ok: true, messageId, emailed }; }); @@ -195,29 +195,35 @@ export const ticketsModule: KcModule = { }); // ---- Posteingang: eingehende Mails, die der IMAP-Abruf keinem Ticket zuordnen konnte ----------- - const inboxView = (m: any) => ({ id: m.id, fromEmail: m.from_email, fromName: m.from_name, subject: m.subject, bodyText: m.body_text, receivedAt: m.received_at, status: m.status, ticketId: m.ticket_id, ticketNumber: m.ticket_number ?? null }); + // suggested*: nur Hinweise aus Betreff/Absender (fälschbar) – das Personal entscheidet, automatisch wird nichts zugeordnet (#107) + const inboxView = (m: any) => ({ id: m.id, fromEmail: m.from_email, fromName: m.from_name, subject: m.subject, bodyText: m.body_text, receivedAt: m.received_at, status: m.status, ticketId: m.ticket_id, ticketNumber: m.ticket_number ?? null, + suggestedTicketNumber: m.suggested_ticket_number ?? null, suggestedOrgId: m.suggested_org_id ?? null, processingError: m.processing_error ?? null }); app.get('/admin/inbox', async (req) => { requirePermission(req, 'tickets.read'); const q = z.object({ status: z.enum(['unmatched', 'matched', 'created', 'ignored']).optional() }).parse(req.query); - const rows = await query('SELECT im.*, t.number AS ticket_number FROM inbox_messages im LEFT JOIN tickets t ON t.id = im.ticket_id WHERE (? IS NULL OR im.status = ?) ORDER BY im.received_at DESC LIMIT 200', [q.status ?? null, q.status ?? null]); + const rows = await query(`SELECT im.*, t.number AS ticket_number, st.number AS suggested_ticket_number, + (SELECT m.org_id FROM memberships m WHERE m.user_id = im.suggested_user_id ORDER BY (m.role = 'owner') DESC LIMIT 1) AS suggested_org_id + FROM inbox_messages im LEFT JOIN tickets t ON t.id = im.ticket_id LEFT JOIN tickets st ON st.id = im.suggested_ticket_id + WHERE (? IS NULL OR im.status = ?) ORDER BY im.received_at DESC LIMIT 200`, [q.status ?? null, q.status ?? null]); return rows.map(inboxView); }); /** Unbekannter Absender wird einem Kunden zugeordnet: neues Ticket, Autor ist der (erste) Ansprechpartner des Kunden. */ app.post('/admin/inbox/:id/assign', async (req) => { const a = requirePermission(req, 'tickets.write'); const { id } = z.object({ id: z.string().uuid() }).parse(req.params); const b = z.object({ orgId: z.string().uuid() }).parse(req.body); - const msg = await one('SELECT * FROM inbox_messages WHERE id = ?', [id]); if (!msg) throw notFound(); - if (msg.status !== 'unmatched') throw conflict('Diese Nachricht wurde bereits bearbeitet.', 'ALREADY_HANDLED'); const owner = await one("SELECT user_id FROM memberships WHERE org_id = ? ORDER BY (role = 'owner') DESC LIMIT 1", [b.orgId]); if (!owner) throw badRequest('Für diesen Kunden ist kein Ansprechpartner hinterlegt.', 'NO_MEMBER'); const ticketId = randomUUID(); - const number = await tx(async (c) => { + // Status unter Zeilensperre prüfen und im selben Schritt setzen: zwei gleichzeitige Klicks erzeugen kein zweites Ticket + const { number, msg } = await tx(async (c) => { + const msg = await one('SELECT * FROM inbox_messages WHERE id = ? FOR UPDATE', [id], c); if (!msg) throw notFound(); + if (msg.status !== 'unmatched') throw conflict('Diese Nachricht wurde bereits bearbeitet.', 'ALREADY_HANDLED'); const n = await nextNumber(c); await run('INSERT INTO tickets (id, number, org_id, subject, status, priority, created_by) VALUES (?,?,?,?,?,?,?)', [ticketId, n, b.orgId, msg.subject || '(kein Betreff)', 'pending_staff', 'normal', owner.user_id], c); await run('INSERT INTO ticket_messages (id, ticket_id, author_id, author_kind, body) VALUES (?,?,?,?,?)', [randomUUID(), ticketId, owner.user_id, 'customer', msg.body_text || '(kein Text)'], c); - return n; + await run("UPDATE inbox_messages SET status = 'created', ticket_id = ? WHERE id = ?", [ticketId, id], c); + return { number: n, msg }; }); - await run("UPDATE inbox_messages SET status = 'created', ticket_id = ? WHERE id = ?", [ticketId, id]); await audit({ actorType: 'user', actorId: a.user.id, orgId: b.orgId, action: 'inbox.assign', resourceType: 'inbox_message', resourceId: id, correlationId: req.correlationId, ip: clientIp(req), after: { ticketId, number } }); await notify('ticket.created', { number, subject: (msg.subject || '').slice(0, 100) }, `mail-in-assign:${id}`, req.correlationId); return { ticketId, number }; @@ -226,21 +232,22 @@ export const ticketsModule: KcModule = { app.post('/admin/inbox/:id/link', async (req) => { const a = requirePermission(req, 'tickets.write'); const { id } = z.object({ id: z.string().uuid() }).parse(req.params); const b = z.object({ ticketNumber: z.string().trim().min(1).max(20) }).parse(req.body); - const msg = await one('SELECT * FROM inbox_messages WHERE id = ?', [id]); if (!msg) throw notFound(); - if (msg.status !== 'unmatched') throw conflict('Diese Nachricht wurde bereits bearbeitet.', 'ALREADY_HANDLED'); const t = await one('SELECT * FROM tickets WHERE number = ?', [b.ticketNumber]); if (!t) throw badRequest('Ticket nicht gefunden.', 'TICKET_NOT_FOUND'); - await run('INSERT INTO ticket_messages (id, ticket_id, author_id, author_kind, body) VALUES (?,?,?,?,?)', [randomUUID(), t.id, t.created_by, 'customer', msg.body_text || '(kein Text)']); - await run("UPDATE tickets SET status = 'pending_staff', last_message_at = UTC_TIMESTAMP(3), resolved_at = NULL, closed_at = NULL WHERE id = ?", [t.id]); - await run("UPDATE inbox_messages SET status = 'matched', ticket_id = ? WHERE id = ?", [t.id, id]); + await tx(async (c) => { + const msg = await one('SELECT * FROM inbox_messages WHERE id = ? FOR UPDATE', [id], c); if (!msg) throw notFound(); + if (msg.status !== 'unmatched') throw conflict('Diese Nachricht wurde bereits bearbeitet.', 'ALREADY_HANDLED'); + await run('INSERT INTO ticket_messages (id, ticket_id, author_id, author_kind, body) VALUES (?,?,?,?,?)', [randomUUID(), t.id, t.created_by, 'customer', msg.body_text || '(kein Text)'], c); + await run("UPDATE tickets SET status = 'pending_staff', last_message_at = UTC_TIMESTAMP(3), resolved_at = NULL, closed_at = NULL WHERE id = ?", [t.id], c); + await run("UPDATE inbox_messages SET status = 'matched', ticket_id = ? WHERE id = ?", [t.id, id], c); + }); await audit({ actorType: 'user', actorId: a.user.id, orgId: t.org_id, action: 'inbox.link', resourceType: 'inbox_message', resourceId: id, correlationId: req.correlationId, ip: clientIp(req), after: { ticketId: t.id } }); await notify('ticket.message', { number: t.number }, `mail-in-link:${id}`, req.correlationId); return { ok: true }; }); app.post('/admin/inbox/:id/ignore', async (req) => { const a = requirePermission(req, 'tickets.write'); const { id } = z.object({ id: z.string().uuid() }).parse(req.params); - const msg = await one('SELECT status FROM inbox_messages WHERE id = ?', [id]); if (!msg) throw notFound(); - if (msg.status !== 'unmatched') throw conflict('Diese Nachricht wurde bereits bearbeitet.', 'ALREADY_HANDLED'); - await run("UPDATE inbox_messages SET status = 'ignored' WHERE id = ?", [id]); + const r = await run("UPDATE inbox_messages SET status = 'ignored' WHERE id = ? AND status = 'unmatched'", [id]); + if (r.affectedRows === 0) { if (!(await one('SELECT 1 AS x FROM inbox_messages WHERE id = ?', [id]))) throw notFound(); throw conflict('Diese Nachricht wurde bereits bearbeitet.', 'ALREADY_HANDLED'); } await audit({ actorType: 'user', actorId: a.user.id, action: 'inbox.ignore', resourceType: 'inbox_message', resourceId: id, correlationId: req.correlationId, ip: clientIp(req) }); return { ok: true }; }); diff --git a/apps/api/test/mailbox.test.ts b/apps/api/test/mailbox.test.ts new file mode 100644 index 0000000..c87f74e --- /dev/null +++ b/apps/api/test/mailbox.test.ts @@ -0,0 +1,50 @@ +import { beforeAll, describe, expect, it } from 'vitest'; +import { randomUUID } from 'node:crypto'; +import { one, query, run } from '../src/core/db.js'; +import { processMessage } from '../../worker/src/mailbox.js'; +import { ticketReplyMessageId } from '@kc/platform/ticketmail'; +import { makeUser } from './helpers.js'; + +const log = () => undefined; +const mail = (h: Record, body = 'Hallo') => Buffer.from(Object.entries({ Date: new Date().toUTCString(), 'Message-ID': `<${randomUUID()}@ext.example>`, ...h }).map(([k, v]) => `${k}: ${v}`).join('\r\n') + '\r\n\r\n' + body); +let org: string; let ticketId: string; let ticketNumber: string; + +beforeAll(async () => { + org = randomUUID(); await run("INSERT INTO organizations (id, customer_number, name, customer_type) VALUES (?, 'K-MAIL1', 'Mail AG', 'business')", [org]); + const u = await makeUser({ email: 'kunde@mail.example' }); await run("INSERT INTO memberships (org_id, user_id, role) VALUES (?,?,'owner')", [org, u]); + ticketId = randomUUID(); ticketNumber = 'T-77001'; + await run("INSERT INTO tickets (id, number, org_id, subject, status, priority, created_by) VALUES (?,?,?,?, 'pending_customer', 'normal', ?)", [ticketId, ticketNumber, org, 'Problem', u]); +}); +const msgs = () => query('SELECT body FROM ticket_messages WHERE ticket_id = ?', [ticketId]); + +describe('IMAP-Posteingang (#107)', () => { + it('gefälschter Absender + Ticketnummer im Betreff hängt NICHTS an, landet mit Vorschlag im Posteingang', async () => { + await processMessage(1001, 9, mail({ From: 'kunde@mail.example', To: 'support@x', Subject: `Re: ${ticketNumber} Problem` }, 'gefälscht'), log); + expect(await msgs()).toHaveLength(0); + const r = await one('SELECT status, suggested_ticket_id, suggested_user_id FROM inbox_messages WHERE uid = 1001'); + expect(r!.status).toBe('unmatched'); expect(r!.suggested_ticket_id).toBe(ticketId); expect(r!.suggested_user_id).toBeTruthy(); + }); + it('Antwort mit signiertem Bezug vom Kunden wird angehängt; Wiederholung derselben UID erzeugt keine Dublette', async () => { + const ref = ticketReplyMessageId(ticketId, 'support@flexible-domains.de'); + const src = mail({ From: 'Kunde ', To: 'support@x', Subject: 'Re: Ihr Ticket', 'In-Reply-To': ref, References: ref }, 'echte Antwort'); + await processMessage(1002, 9, src, log); + await processMessage(1002, 9, src, log); // erneuter Lauf (z. B. nach Abbruch) – keine zweite Nachricht + expect((await msgs()).map((m) => m.body)).toEqual(['echte Antwort']); + expect((await one('SELECT status FROM tickets WHERE id = ?', [ticketId]))!.status).toBe('pending_staff'); + }); + it('gültiger Bezug, aber fremder Absender oder manipulierte Signatur → Posteingang', async () => { + const ref = ticketReplyMessageId(ticketId, 'support@flexible-domains.de'); + await processMessage(1003, 9, mail({ From: 'angreifer@evil.example', Subject: 'Re', 'In-Reply-To': ref }), log); + const forged = ref.replace(/\.([A-Za-z0-9_-]{22})\./, '.AAAAAAAAAAAAAAAAAAAAAA.'); + await processMessage(1004, 9, mail({ From: 'kunde@mail.example', Subject: 'Re', 'In-Reply-To': forged }), log); + expect((await msgs())).toHaveLength(1); + expect((await query("SELECT uid FROM inbox_messages WHERE uid IN (1003,1004) AND status = 'unmatched'"))).toHaveLength(2); + }); + it('gesperrter Kunde: auch mit gültigem Bezug keine automatische Antwort', async () => { + await run("UPDATE organizations SET status = 'suspended' WHERE id = ?", [org]); + const ref = ticketReplyMessageId(ticketId, 'support@flexible-domains.de'); + await processMessage(1005, 9, mail({ From: 'kunde@mail.example', Subject: 'Re', 'In-Reply-To': ref }), log); + expect((await msgs())).toHaveLength(1); + await run("UPDATE organizations SET status = 'active' WHERE id = ?", [org]); + }); +}); diff --git a/apps/web/src/app/(app)/admin/posteingang/page.tsx b/apps/web/src/app/(app)/admin/posteingang/page.tsx index 0345e12..191f845 100644 --- a/apps/web/src/app/(app)/admin/posteingang/page.tsx +++ b/apps/web/src/app/(app)/admin/posteingang/page.tsx @@ -4,13 +4,14 @@ import Link from 'next/link'; import { api, errMsg } from '@/lib/api'; import { Alert, Empty, fmt } from '@/components/ui'; -interface Msg { id: string; fromEmail: string; fromName: string | null; subject: string | null; bodyText: string | null; receivedAt: string; status: 'unmatched' | 'matched' | 'created' | 'ignored'; ticketId: string | null; ticketNumber: string | null } +interface Msg { id: string; fromEmail: string; fromName: string | null; subject: string | null; bodyText: string | null; receivedAt: string; status: 'unmatched' | 'matched' | 'created' | 'ignored'; ticketId: string | null; ticketNumber: string | null; suggestedTicketNumber: string | null; suggestedOrgId: string | null; processingError: string | null } interface Cust { id: string; name: string; customerNumber: string } const STATUS_LABEL: Record = { unmatched: 'Unzugeordnet', matched: 'An Ticket angehängt', created: 'Ticket erstellt', ignored: 'Ignoriert' }; /** Eine unzugeordnete Mail: Kunde zuweisen (legt neues Ticket an), an bestehendes Ticket anhängen, oder ignorieren. */ function UnmatchedRow({ m, custs, onDone, onError }: { m: Msg; custs: Cust[]; onDone: (t: string) => void; onError: (m: string) => void }) { - const [org, setOrg] = useState(''); const [ticketNumber, setTicketNumber] = useState(''); const [busy, setBusy] = useState(false); const [open, setOpen] = useState(false); + // Vorschläge aus Betreff/Absender nur vorausfüllen – bestätigen muss immer das Personal (Absender ist nicht nachgewiesen) + const [org, setOrg] = useState(m.suggestedOrgId ?? ''); const [ticketNumber, setTicketNumber] = useState(m.suggestedTicketNumber ?? ''); const [busy, setBusy] = useState(false); const [open, setOpen] = useState(false); async function assign() { if (!org) return; setBusy(true); try { const r = await api<{ number: string }>('POST', `/admin/inbox/${m.id}/assign`, { orgId: org }); onDone(`Ticket ${r.number} angelegt.`); } @@ -29,6 +30,8 @@ function UnmatchedRow({ m, custs, onDone, onError }: { m: Msg; custs: Cust[]; on return (
{m.subject || '(kein Betreff)'}

Von: {m.fromName ? `${m.fromName} <${m.fromEmail}>` : m.fromEmail} · {fmt(m.receivedAt)}

+ {(m.suggestedTicketNumber || m.suggestedOrgId) &&

Vorschlag aus Betreff/Absender vorausgefüllt. Der Absender ist nicht nachgewiesen (keine Antwort auf eine Kundencenter-Mail) – bitte prüfen, bevor Sie zuordnen.

} + {m.processingError &&

Automatische Verarbeitung fehlgeschlagen: {m.processingError}

} {open &&
{m.bodyText || '(kein Text)'}
}
diff --git a/apps/worker/src/discord.ts b/apps/worker/src/discord.ts index fd1c102..1ecb5e5 100644 --- a/apps/worker/src/discord.ts +++ b/apps/worker/src/discord.ts @@ -150,7 +150,7 @@ async function handleThreadMessage(msg: Message, log: (m: string) => void): Prom await pool.query("UPDATE tickets SET status = 'pending_customer', last_message_at = UTC_TIMESTAMP(3), resolved_at = NULL, closed_at = NULL WHERE id = ?", [t.ticket_id]); await audit({ actorType: 'user', actorId: staff.id, orgId: t.org_id, action: 'ticket.message', resourceType: 'ticket', resourceId: t.ticket_id, after: { internalNote: false, via: 'discord' } }); const creator = await pool.query('SELECT email, name FROM users WHERE id = ?', [t.created_by]).then(([r]: any) => r[0]); - if (creator) await enqueue('mail.template', { to: creator.email, key: 'ticket_message', vars: { name: creator.name, number: t.number, subject: t.subject, ticketLink: ticketLink(t.ticket_id) } }, { idempotencyKey: `mail:discord-staff:${msg.id}` }); + if (creator) await enqueue('mail.template', { to: creator.email, key: 'ticket_message', vars: { name: creator.name, number: t.number, subject: t.subject, ticketLink: ticketLink(t.ticket_id) }, replyTicketId: t.ticket_id }, { idempotencyKey: `mail:discord-staff:${msg.id}` }); log(`Discord: Support-Antwort zu Ticket ${t.number} übernommen.`); return; } diff --git a/apps/worker/src/jobs.ts b/apps/worker/src/jobs.ts index 3f8b37f..505a518 100644 --- a/apps/worker/src/jobs.ts +++ b/apps/worker/src/jobs.ts @@ -26,8 +26,8 @@ const handlers: Record = { const r = await notifyAdmin(text, String(p.event).startsWith('ticket.') ? 'tickets' : 'admin'); if (r === 'skipped') return 'übersprungen: Discord nicht konfiguriert'; }, - 'mail.template': async (p: { to: string; key: string; vars: Record }) => { - const status = await sendTemplateMail(p.to, p.key, p.vars); + 'mail.template': async (p: { to: string; key: string; vars: Record; replyTicketId?: string }) => { + const status = await sendTemplateMail(p.to, p.key, p.vars, { replyTicketId: p.replyTicketId }); if (status === 'failed') throw new Error('Mailversand fehlgeschlagen (siehe Protokoll unter Einstellungen > E-Mail)'); if (status === 'no_template') throw new Error(`Unbekannte Mailvorlage: ${p.key}`); return status === 'not_configured' ? 'übersprungen: SMTP nicht konfiguriert' : status === 'disabled' ? 'übersprungen: Vorlage deaktiviert' : 'gesendet'; diff --git a/apps/worker/src/mailbox.ts b/apps/worker/src/mailbox.ts index 48513fc..e73b6ac 100644 --- a/apps/worker/src/mailbox.ts +++ b/apps/worker/src/mailbox.ts @@ -1,7 +1,9 @@ import { randomUUID } from 'node:crypto'; import { ImapFlow } from 'imapflow'; import { simpleParser } from 'mailparser'; -import { pool } from '@kc/platform/db'; +import type { PoolConnection } from 'mysql2/promise'; +import { one, pool, run, tx } from '@kc/platform/db'; +import { ticketFromReplyHeaders } from '@kc/platform/ticketmail'; import { decrypt } from '@kc/platform/crypto'; import { enqueue } from '@kc/platform/jobs'; import { hasFeature } from '@kc/platform/license'; @@ -10,19 +12,20 @@ import { hasFeature } from '@kc/platform/license'; function htmlToText(html: string): string { return html.replace(/<(script|style)[^>]*>[\s\S]*?<\/\1>/gi, ' ').replace(//gi, '\n').replace(/<\/p>/gi, '\n\n').replace(/<[^>]+>/g, ' ').replace(/ /g, ' ').replace(/[ \t]+/g, ' ').replace(/\n{3,}/g, '\n\n').trim(); } -async function nextTicketNumber(): Promise { - await pool.query("UPDATE number_sequences SET next_value = LAST_INSERT_ID(next_value + 1) WHERE name = 'ticket'"); - const [r] = await pool.query('SELECT LAST_INSERT_ID() AS n') as any; - return `T-${r[0].n}`; -} -const notify = (event: string, extra: Record, key: string) => enqueue('discord.notify', { event, ...extra }, { idempotencyKey: key }); +const notify = (event: string, extra: Record, key: string, c?: PoolConnection) => enqueue('discord.notify', { event, ...extra }, { idempotencyKey: key }, c); +/** Nach so vielen erfolglosen Versuchen wird eine Nachricht nur noch als „nicht verarbeitbar“ im Posteingang abgelegt. */ +const MAX_ATTEMPTS = 5; /** - * Ruft das konfigurierte IMAP-Postfach ab und ordnet neue Mails Tickets zu: - * 1. Betreff enthält eine Ticketnummer (T-123) UND Absender gehört zum Kunden dieses Tickets → als Nachricht angehängt. - * 2. Sonst, wenn der Absender ein bekannter aktiver Kunde ist → neues Ticket unter seinem Kundenkonto. - * 3. Sonst → landet unzugeordnet im Posteingang, Personal weist manuell zu (siehe /admin/inbox). - * Beim ersten Aktivieren (last_uid ist NULL) wird kein Bestand verarbeitet, nur ab dann neu Eingehendes. + * Ruft das konfigurierte IMAP-Postfach ab und ordnet neue Mails Tickets zu (#107): + * 1. Antwort mit gültigem, signiertem Bezug auf eine Ticket-Mail (In-Reply-To/References, siehe ticketmail.ts) UND + * Absender ist aktives Mitglied des (aktiven) Kunden dieses Tickets → als Kundenantwort angehängt. + * 2. Alles andere (auch bekannte Absender, Ticketnummer nur im Betreff) → Posteingang zur manuellen Zuordnung, mit + * Vorschlag (Ticket/Kunde). Absenderadresse und Betreff sind fälschbar und gelten nicht als Identitätsnachweis. + * Erstlauf (last_uid NULL) oder geänderte UIDVALIDITY: kein Bestand wird verarbeitet, nur ab dann neu Eingehendes. + * Schlägt eine Nachricht fehl, bleibt last_uid VOR ihr stehen und sie wird beim nächsten Lauf wiederholt + * (höchstens MAX_ATTEMPTS-mal, danach als nicht verarbeitbar im Posteingang abgelegt). Doppelte Verarbeitung + * verhindert der eindeutige Schlüssel (uid_validity, uid). */ export async function checkMailbox(log: (m: string) => void): Promise { const [rows] = await pool.query('SELECT * FROM imap_settings WHERE id = 1') as any; @@ -35,20 +38,37 @@ export async function checkMailbox(log: (m: string) => void): Promise { await client.connect(); const lock = await client.getMailboxLock(s.folder || 'INBOX'); try { - const mailbox = client.mailbox as { uidNext: number }; - if (s.last_uid == null) { - await pool.query('UPDATE imap_settings SET last_uid = ?, last_checked_at = UTC_TIMESTAMP(3), last_error = NULL WHERE id = 1', [Math.max(0, mailbox.uidNext - 1)]); - log('IMAP: Erstlauf, Bestand wird nicht verarbeitet (nur neu Eingehendes ab jetzt).'); + const mailbox = client.mailbox as { uidNext: number; uidValidity: bigint | number }; + const uidValidity = Number(mailbox.uidValidity); + if (s.last_uid == null || (s.uid_validity != null && Number(s.uid_validity) !== uidValidity)) { + const reason = s.last_uid == null ? 'Erstlauf' : 'UIDVALIDITY des Postfachs hat sich geändert'; + await pool.query('UPDATE imap_settings SET last_uid = ?, uid_validity = ?, failed_uid = NULL, failed_attempts = 0, last_checked_at = UTC_TIMESTAMP(3), last_error = NULL WHERE id = 1', [Math.max(0, mailbox.uidNext - 1), uidValidity]); + log(`IMAP: ${reason}, Bestand wird nicht verarbeitet (nur neu Eingehendes ab jetzt).`); return; } - let maxUid = s.last_uid; - for await (const msg of client.fetch(`${s.last_uid + 1}:*`, { source: true }, { uid: true })) { - if (msg.uid <= s.last_uid) continue; // Server liefert bei leerem Bereich mitunter die letzte bekannte Nachricht - maxUid = Math.max(maxUid, msg.uid); - try { await processMessage(msg.uid, msg.source as Buffer, log); } - catch (e) { log(`IMAP: Nachricht UID ${msg.uid} konnte nicht verarbeitet werden: ${(e as Error).message}`); } + if (s.uid_validity == null) await pool.query('UPDATE imap_settings SET uid_validity = ? WHERE id = 1', [uidValidity]); + let lastUid = Number(s.last_uid); + let failedUid: number | null = s.failed_uid == null ? null : Number(s.failed_uid); + let attempts = Number(s.failed_attempts ?? 0); + let error: string | null = null; + for await (const msg of client.fetch(`${lastUid + 1}:*`, { source: true }, { uid: true })) { + if (msg.uid <= lastUid) continue; // Server liefert bei leerem Bereich mitunter die letzte bekannte Nachricht + try { + await processMessage(msg.uid, uidValidity, msg.source as Buffer, log); + } catch (e) { + const m = String((e as Error).message).slice(0, 400); + attempts = failedUid === msg.uid ? attempts + 1 : 1; failedUid = msg.uid; + if (attempts < MAX_ATTEMPTS) { + error = `Nachricht UID ${msg.uid} nicht verarbeitet (Versuch ${attempts}/${MAX_ATTEMPTS}): ${m}`; + log(`IMAP: ${error}`); + break; // last_uid bleibt vor dieser Nachricht stehen → nächster Lauf wiederholt sie + } + await storeUnprocessable(msg.uid, uidValidity, msg.source as Buffer, m).catch((e2) => log(`IMAP: Ablage von UID ${msg.uid} fehlgeschlagen: ${(e2 as Error).message}`)); + log(`IMAP: Nachricht UID ${msg.uid} nach ${attempts} Versuchen als nicht verarbeitbar im Posteingang abgelegt: ${m}`); + } + lastUid = msg.uid; failedUid = null; attempts = 0; } - await pool.query('UPDATE imap_settings SET last_uid = ?, last_checked_at = UTC_TIMESTAMP(3), last_error = NULL WHERE id = 1', [maxUid]); + await pool.query('UPDATE imap_settings SET last_uid = ?, failed_uid = ?, failed_attempts = ?, last_checked_at = UTC_TIMESTAMP(3), last_error = ? WHERE id = 1', [lastUid, failedUid, attempts, error]); } finally { lock.release(); } await client.logout(); } catch (e) { @@ -60,63 +80,61 @@ export async function checkMailbox(log: (m: string) => void): Promise { } const TICKET_NUMBER = /\bT-(\d+)\b/i; -async function processMessage(uid: number, source: Buffer, log: (m: string) => void): Promise { +const isDuplicate = (e: unknown) => (e as { code?: string }).code === 'ER_DUP_ENTRY'; +interface Parsed { fromEmail: string; fromName: string | null; subject: string | null; bodyText: string; receivedAt: Date; messageId: string | null; inReplyTo?: string; references?: string | string[] } +async function parse(source: Buffer): Promise { const parsed = await simpleParser(source); const fromAddr = parsed.from?.value?.[0]; - const fromEmail = (fromAddr?.address ?? '').toLowerCase().slice(0, 254); - if (!fromEmail) { log(`IMAP: Nachricht UID ${uid} ohne lesbare Absenderadresse, übersprungen.`); return; } - const fromName = (fromAddr?.name ?? '').slice(0, 200) || null; - const subject = (parsed.subject ?? '').slice(0, 500) || null; - const bodyText = (parsed.text ?? (parsed.html ? htmlToText(parsed.html as string) : '')).slice(0, 20000); - const receivedAt = parsed.date ?? new Date(); - const messageId = (parsed.messageId ?? '').slice(0, 998) || null; - const id = randomUUID(); + return { + fromEmail: (fromAddr?.address ?? '').toLowerCase().slice(0, 254), fromName: (fromAddr?.name ?? '').slice(0, 200) || null, + subject: (parsed.subject ?? '').slice(0, 500) || null, bodyText: (parsed.text ?? (parsed.html ? htmlToText(parsed.html as string) : '')).slice(0, 20000), + receivedAt: parsed.date ?? new Date(), messageId: (parsed.messageId ?? '').slice(0, 998) || null, inReplyTo: parsed.inReplyTo, references: parsed.references, + }; +} - // 1) Ticketnummer im Betreff + Absender gehört zum Kunden dieses Tickets - const m = subject ? TICKET_NUMBER.exec(subject) : null; - if (m) { - const [tRows] = await pool.query('SELECT * FROM tickets WHERE number = ?', [`T-${m[1]}`]) as any; - const ticket = tRows[0]; - if (ticket) { - const [uRows] = await pool.query("SELECT id FROM users WHERE email = ? AND status = 'active'", [fromEmail]) as any; - const user = uRows[0]; - if (user) { - const [memRows] = await pool.query('SELECT 1 AS x FROM memberships WHERE user_id = ? AND org_id = ?', [user.id, ticket.org_id]) as any; - if (memRows[0]) { - await pool.query('INSERT INTO ticket_messages (id, ticket_id, author_id, author_kind, body) VALUES (?,?,?,?,?)', [randomUUID(), ticket.id, user.id, 'customer', bodyText || '(kein Text)']); - await pool.query("UPDATE tickets SET status = 'pending_staff', last_message_at = UTC_TIMESTAMP(3), resolved_at = NULL, closed_at = NULL WHERE id = ?", [ticket.id]); - await pool.query('INSERT INTO inbox_messages (id, uid, message_id, from_email, from_name, subject, body_text, received_at, status, ticket_id, matched_user_id) VALUES (?,?,?,?,?,?,?,?,?,?,?)', - [id, uid, messageId, fromEmail, fromName, subject, bodyText, receivedAt, 'matched', ticket.id, user.id]); - await notify('ticket.message', { number: ticket.number }, `mail-in:${id}`); - log(`IMAP: Nachricht von ${fromEmail} zu Ticket ${ticket.number} hinzugefügt.`); +/** Verarbeitet eine Nachricht vollständig in EINER Transaktion (Inbox-Zeile, Ticketnachricht, Status, Benachrichtigung). */ +export async function processMessage(uid: number, uidValidity: number, source: Buffer, log: (m: string) => void): Promise { + const p = await parse(source); + const id = randomUUID(); + const inboxRow = (c: PoolConnection, status: string, extra: { ticketId?: string | null; userId?: string | null; suggestedTicketId?: string | null; suggestedUserId?: string | null } = {}) => + run('INSERT INTO inbox_messages (id, uid, uid_validity, message_id, from_email, from_name, subject, body_text, received_at, status, ticket_id, matched_user_id, suggested_ticket_id, suggested_user_id) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)', + [id, uid, uidValidity, p.messageId, p.fromEmail || '(unbekannt)', p.fromName, p.subject, p.bodyText, p.receivedAt, status, extra.ticketId ?? null, extra.userId ?? null, extra.suggestedTicketId ?? null, extra.suggestedUserId ?? null], c); + try { + await tx(async (c) => { + // 1) Signierter Antwort-Bezug + Absender ist aktives Mitglied des aktiven Kunden dieses Tickets + const replyTicketId = ticketFromReplyHeaders(p.inReplyTo, p.references); + if (replyTicketId && p.fromEmail) { + const t = await one("SELECT t.id, t.number, t.org_id FROM tickets t JOIN organizations o ON o.id = t.org_id AND o.status = 'active' WHERE t.id = ? FOR UPDATE", [replyTicketId], c); + const u = t && await one("SELECT u.id FROM users u JOIN memberships m ON m.user_id = u.id AND m.org_id = ? WHERE u.email = ? AND u.status = 'active' AND u.kind = 'customer'", [t.org_id, p.fromEmail], c); + if (t && u) { + await inboxRow(c, 'matched', { ticketId: t.id, userId: u.id }); // zuerst: Dublette bricht hier ab, bevor etwas angehängt wird + await run('INSERT INTO ticket_messages (id, ticket_id, author_id, author_kind, body) VALUES (?,?,?,?,?)', [randomUUID(), t.id, u.id, 'customer', p.bodyText || '(kein Text)'], c); + await run("UPDATE tickets SET status = 'pending_staff', last_message_at = UTC_TIMESTAMP(3), resolved_at = NULL, closed_at = NULL WHERE id = ?", [t.id], c); + await notify('ticket.message', { number: t.number }, `mail-in:${id}`, c); + log(`IMAP: Antwort zu Ticket ${t.number} angehängt (signierter Antwort-Bezug).`); return; } } - } + // 2) Kein Nachweis → Posteingang, mit Vorschlag für das Personal + const m = p.subject ? TICKET_NUMBER.exec(p.subject) : null; + const sugTicket = m ? await one('SELECT id FROM tickets WHERE number = ?', [`T-${m[1]}`], c) : undefined; + const sugUser = p.fromEmail ? await one("SELECT id FROM users WHERE email = ? AND status = 'active' AND kind = 'customer'", [p.fromEmail], c) : undefined; + await inboxRow(c, 'unmatched', { suggestedTicketId: replyTicketId ?? sugTicket?.id ?? null, suggestedUserId: sugUser?.id ?? null }); + log(`IMAP: Nachricht UID ${uid} liegt zur Zuordnung im Posteingang${sugTicket || sugUser ? ' (mit Vorschlag)' : ''}.`); + }); + } catch (e) { + if (isDuplicate(e)) { log(`IMAP: Nachricht UID ${uid} wurde bereits verarbeitet, übersprungen.`); return; } + throw e; } - - // 2) Bekannter aktiver Kunde ohne (verifizierten) Ticketbezug → neues Ticket - const [uRows2] = await pool.query("SELECT id FROM users WHERE email = ? AND status = 'active' AND kind = 'customer'", [fromEmail]) as any; - const user2 = uRows2[0]; - if (user2) { - const [memRows2] = await pool.query("SELECT org_id FROM memberships WHERE user_id = ? ORDER BY (role = 'owner') DESC LIMIT 1", [user2.id]) as any; - const org = memRows2[0]; - if (org) { - const ticketId = randomUUID(); - const number = await nextTicketNumber(); - await pool.query('INSERT INTO tickets (id, number, org_id, subject, status, priority, created_by) VALUES (?,?,?,?,?,?,?)', - [ticketId, number, org.org_id, subject || '(kein Betreff)', 'pending_staff', 'normal', user2.id]); - await pool.query('INSERT INTO ticket_messages (id, ticket_id, author_id, author_kind, body) VALUES (?,?,?,?,?)', [randomUUID(), ticketId, user2.id, 'customer', bodyText || '(kein Text)']); - await pool.query('INSERT INTO inbox_messages (id, uid, message_id, from_email, from_name, subject, body_text, received_at, status, ticket_id, matched_user_id) VALUES (?,?,?,?,?,?,?,?,?,?,?)', - [id, uid, messageId, fromEmail, fromName, subject, bodyText, receivedAt, 'created', ticketId, user2.id]); - await notify('ticket.created', { number, subject: (subject || '').slice(0, 100) }, `mail-in:${id}`); - log(`IMAP: Neues Ticket ${number} aus Mail von ${fromEmail} angelegt.`); - return; - } - } - - // 3) Unbekannter oder nicht zuordenbarer Absender → Posteingang zur manuellen Zuordnung - await pool.query('INSERT INTO inbox_messages (id, uid, message_id, from_email, from_name, subject, body_text, received_at, status) VALUES (?,?,?,?,?,?,?,?,?)', - [id, uid, messageId, fromEmail, fromName, subject, bodyText, receivedAt, 'unmatched']); - log(`IMAP: Nachricht von ${fromEmail} konnte niemandem zugeordnet werden, liegt im Posteingang.`); +} + +/** Letzter Ausweg nach MAX_ATTEMPTS Fehlversuchen: Rohdaten so weit wie möglich als unzugeordnete Nachricht ablegen. */ +async function storeUnprocessable(uid: number, uidValidity: number, source: Buffer, error: string): Promise { + const head = source.subarray(0, 20000).toString('utf8'); + const from = /^From:\s*(.*)$/im.exec(head)?.[1]?.slice(0, 254) ?? '(unbekannt)'; + const subject = /^Subject:\s*(.*)$/im.exec(head)?.[1]?.slice(0, 500) ?? null; + try { + await run("INSERT INTO inbox_messages (id, uid, uid_validity, from_email, subject, body_text, received_at, status, processing_error) VALUES (?,?,?,?,?,?,UTC_TIMESTAMP(3),'unmatched',?)", + [randomUUID(), uid, uidValidity, from, subject, '(Nachricht konnte nicht automatisch gelesen werden – bitte im Postfach ansehen)', error]); + } catch (e) { if (!isDuplicate(e)) throw e; } } diff --git a/migrations/039_imap_hardening.sql b/migrations/039_imap_hardening.sql new file mode 100644 index 0000000..47ec329 --- /dev/null +++ b/migrations/039_imap_hardening.sql @@ -0,0 +1,13 @@ +-- IMAP-Posteingang absichern (#107): UIDVALIDITY, Wiederholung fehlgeschlagener Nachrichten, Dubletten-Schutz, +-- und Zuordnungsvorschläge für Mails, deren Absender nicht nachweisbar ist (nur Hinweis, keine automatische Zuordnung). +ALTER TABLE imap_settings + ADD COLUMN uid_validity BIGINT UNSIGNED NULL AFTER last_uid, + ADD COLUMN failed_uid BIGINT UNSIGNED NULL AFTER uid_validity, + ADD COLUMN failed_attempts INT NOT NULL DEFAULT 0 AFTER failed_uid; + +ALTER TABLE inbox_messages + ADD COLUMN uid_validity BIGINT UNSIGNED NULL AFTER uid, + ADD COLUMN suggested_ticket_id CHAR(36) NULL REFERENCES tickets(id), + ADD COLUMN suggested_user_id CHAR(36) NULL REFERENCES users(id), + ADD COLUMN processing_error VARCHAR(500) NULL, + ADD UNIQUE KEY uq_inbox_uid (uid_validity, uid); diff --git a/packages/platform/src/mail.ts b/packages/platform/src/mail.ts index 20df951..7caa4e8 100644 --- a/packages/platform/src/mail.ts +++ b/packages/platform/src/mail.ts @@ -2,6 +2,7 @@ import nodemailer from 'nodemailer'; import { one, run } from './db.js'; import { decrypt } from './crypto.js'; import { config } from './config.js'; +import { ticketReplyMessageId } from './ticketmail.js'; export interface SmtpConfig { host: string; port: number; secureMode: 'none' | 'starttls' | 'tls'; username: string | null; fromName: string | null; fromEmail: string } export type MailCategory = 'kundencenter' | 'stoerungsticket' | 'rechnungen'; @@ -30,7 +31,7 @@ async function transportFor(cfg: SmtpConfig) { } /** Versand mit Protokoll. Ohne SMTP-Konfiguration wird nur "not_configured" protokolliert (Inhalt bewusst nicht gespeichert). */ -export async function sendMail(to: string, template: string, subject: string, text: string, opts: { category?: MailCategory; html?: string } = {}): Promise<'sent' | 'failed' | 'not_configured'> { +export async function sendMail(to: string, template: string, subject: string, text: string, opts: { category?: MailCategory; html?: string; replyTicketId?: string } = {}): Promise<'sent' | 'failed' | 'not_configured'> { const cfg = await loadSmtpConfig(); if (!cfg) { await run('INSERT INTO mail_log (to_email, template, status) VALUES (?,?,?)', [to, template, 'not_configured']); @@ -39,7 +40,9 @@ export async function sendMail(to: string, template: string, subject: string, te try { const transport = await transportFor(cfg); const from = await fromFor(cfg, opts.category); - await transport.sendMail({ from: from.name ? `"${from.name.replace(/"/g, "'")}" <${from.email}>` : from.email, to, subject, text, html: opts.html }); + // Ticket-Mails: signierte Message-ID, damit Antworten per In-Reply-To/References sicher zugeordnet werden (#107) + const messageId = opts.replyTicketId ? ticketReplyMessageId(opts.replyTicketId, from.email) : undefined; + await transport.sendMail({ from: from.name ? `"${from.name.replace(/"/g, "'")}" <${from.email}>` : from.email, to, subject, text, html: opts.html, messageId }); await run('INSERT INTO mail_log (to_email, template, status) VALUES (?,?,?)', [to, template, 'sent']); return 'sent'; } catch (e) { @@ -92,11 +95,11 @@ export function renderTemplateHtml(tpl: string, vars: Record): s } /** Sendet anhand einer in der Datenbank hinterlegten Vorlage (Einstellungen > E-Mail > Vorlagen). Der Absender richtet sich nach dem Bereich der Vorlage (Kundencenter/Störungsticket/Rechnungen). */ -export async function sendTemplateMail(to: string, key: string, vars: Record): Promise<'sent' | 'failed' | 'not_configured' | 'disabled' | 'no_template'> { +export async function sendTemplateMail(to: string, key: string, vars: Record, opts: { replyTicketId?: string } = {}): Promise<'sent' | 'failed' | 'not_configured' | 'disabled' | 'no_template'> { const t = await one('SELECT * FROM mail_templates WHERE `key` = ?', [key]); if (!t) return 'no_template'; if (!t.enabled) return 'disabled'; - return sendMail(to, key, renderTemplateText(t.subject, vars), renderTemplateText(t.body, vars), { category: t.category as MailCategory, html: renderTemplateHtml(t.body, vars) }); + return sendMail(to, key, renderTemplateText(t.subject, vars), renderTemplateText(t.body, vars), { category: t.category as MailCategory, html: renderTemplateHtml(t.body, vars), replyTicketId: opts.replyTicketId }); } export const baseUrl = config.baseUrl; diff --git a/packages/platform/src/sequences.ts b/packages/platform/src/sequences.ts new file mode 100644 index 0000000..4ad6ee5 --- /dev/null +++ b/packages/platform/src/sequences.ts @@ -0,0 +1,10 @@ +import type { PoolConnection } from 'mysql2/promise'; +import { one, run } from './db.js'; + +/** Nächster Wert eines Nummernkreises (number_sequences). LAST_INSERT_ID() ist an die Sitzung gebunden – deshalb + * UPDATE und SELECT zwingend auf DERSELBEN Verbindung (über den Pool könnten sie auf verschiedenen landen und eine + * fremde oder veraltete Nummer liefern). Am besten in der Transaktion, die die Nummer auch verwendet. */ +export async function nextSequence(c: PoolConnection, name: string): Promise { + await run('UPDATE number_sequences SET next_value = LAST_INSERT_ID(next_value + 1) WHERE name = ?', [name], c); + return Number((await one('SELECT LAST_INSERT_ID() AS n', [], c))!.n); +} diff --git a/packages/platform/src/ticketmail.ts b/packages/platform/src/ticketmail.ts new file mode 100644 index 0000000..a715ed8 --- /dev/null +++ b/packages/platform/src/ticketmail.ts @@ -0,0 +1,29 @@ +import { createHmac, randomBytes } from 'node:crypto'; +import { config } from './config.js'; +import { safeEqual } from './crypto.js'; + +/** + * Fälschungssicherer Antwort-Bezug für Ticket-Mails (#107). Ausgehende Ticket-Mails bekommen eine Message-ID mit + * Ticket-ID und HMAC (Schlüssel = KC_SECRET_KEY). Mailprogramme übernehmen sie in In-Reply-To/References der + * Antwort. Nur so belegt eine eingehende Mail, dass der Absender die Ticket-Mail tatsächlich erhalten hat – + * Absenderadresse und Ticketnummer im Betreff sind frei fälschbar und reichen NICHT für eine automatische Zuordnung. + */ +const tag = (ticketId: string): string => createHmac('sha256', config.secretKey).update(`ticket-reply:${ticketId}`).digest('base64url').slice(0, 22); + +export function ticketReplyMessageId(ticketId: string, fromEmail: string): string { + const domain = (fromEmail.split('@')[1] || 'kundencenter.invalid').replace(/[^A-Za-z0-9.-]/g, ''); + return ``; +} + +const REF = /kc\.t\.([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.([A-Za-z0-9_-]{22})\./gi; +/** Ticket-ID aus In-Reply-To/References, wenn der HMAC stimmt; sonst null. */ +export function ticketFromReplyHeaders(...values: (string | string[] | undefined | null)[]): string | null { + for (const v of values.flat()) { + if (!v) continue; + for (const m of v.matchAll(REF)) { + const id = m[1]!.toLowerCase(); + if (safeEqual(tag(id), m[2]!)) return id; + } + } + return null; +}