Files
pn-new-crm/src/lib/services/webhooks.service.ts
Matt 4b5f85cb7d fix(audit): comprehensive 2026-05-15 audit fix wave + Documenso v2 polish
Bundles the prior session's 50-task fix sweep (Documenso v2 + EOI/signing-
progress redesign + env-to-admin migration + dev-mode banner) with the
2026-05-18 audit fix wave (3 CRITICAL, 14 HIGH, 28 MEDIUM, 6 LOW).

CRITICAL (3):
 - C-01 interest-berths INNER JOIN -> LEFT JOIN so hard-deleted berths
   no longer silently drop interest links
 - C-02 /setup added to PUBLIC_PATHS; fresh-deploy bootstrap loop fixed
 - C-03 generic PATCH /interests/[id] no longer accepts pipelineStage —
   callers must go through /stage with the override-guard chain

HIGH (14/15):
 - H-01 explicit ON DELETE on previously-implicit NO ACTION FKs across
   interests/documents/reservations/reminders/invoices (migration 0070)
 - H-02 login page reads ?redirect= param with same-origin guard
 - H-03 CRM invite token moves to URL fragment so it never lands in
   nginx access logs / Referer headers
 - H-04 Retry-After header on sign-in-by-identifier 429 (RFC 6585 §4)
 - H-05 toggleAccount writes an audit row
 - H-06 upsertSetting masks any value whose key ends with _encrypted
 - H-07 archiveClient cascade fires per-interest audit rows
 - H-08 createSalesTransporter applies SMTP_TIMEOUTS
 - H-09 AppShell stable children — viewport flip across breakpoint no
   longer destroys in-progress form drafts
 - H-10 portal documents page swaps Unicode glyph status icons for
   Lucide CheckCircle2/XCircle/Circle + aria-labels
 - H-12 list components swap alert(...) for toast.warning(...)
 - H-13 5 icon-only buttons gain aria-label
 - H-14 parseBody treats empty bodies as {}
 - H-15 admin layout renders a 403 panel instead of silent bounce
 - H-11 not applicable — mobile-search-overlay IS a mobile bottom-sheet

MEDIUM (28+):
 - M-MT01-05 defense-in-depth port_id/parent-id filters on UPDATE/DELETE
   WHEREs across custom-fields, notes (all 6 entity types x update +
   delete), client-contacts, yacht ownerClient lookup, webhook reads
 - M-D01 documents-hub realtime event-name typo (file:created -> uploaded)
 - M-EM01 portal-auth emails thread through portId
 - M-EM02 sendEmail accepts cc/bcc params
 - M-EM04 notification_digest catalog key
 - M-IN01 portal presigned download URLs use 4h TTL
 - M-IN02 OpenAI client lazy-instantiated
 - M-IN04 stale pdfme refs updated to pdf-lib AcroForm
 - M-IN05 umami.testConnection returns tagged union
 - M-L01 reservations tenure_type unified with berths
 - M-L02 report-generators canonicalize stage values
 - M-AU01 audit log placeholder copy fixed
 - M-AU04 outcome_set / outcome_cleared distinct audit verbs
 - M-NEW-2 activity feed entity name+type separator
 - M-R01 portal allowlist narrowed + portal_session backstop in proxy
 - M-SC02 companies archived partial index
 - M-SC04 audit_logs.searchText documented as DB-managed
 - M-S01 storage_s3_access_key_encrypted admin field
 - M-U01 audit log empty state uses <EmptyState>
 - M-U09 invoice delete dialog -> <AlertDialog>
 - M-U10 toast.success on ClientForm + InterestForm create/edit
 - M-U11 settings-form-card logo preview alt text
 - M-U14 mobile topbar title on clients/yachts/interests/berths
 - M-U15 Invoices in mobile More-sheet

LOW (6/8):
 - L-AU01 severity defaults for security-relevant verbs
 - L-AU02 +13 missing actions in admin audit filter
 - L-AU03 +7 missing entity types in admin audit filter
 - L-AU04 dead listAuditLogs stubbed
 - L-D02 CLAUDE.md Owner-wins chain tightened

Bonus — Document detail polish (#67 partial, 3/6 deliverables):
 - state-aware action button per signer
 - watcher Add UI with display-name resolution
 - cleanSignerName cleanup

Prior session work bundled in:
 - Documenso v2 webhook + envelope-ID normalization + sequential signing
 - SigningProgress UI redesign (avatars, per-signer state, timestamps)
 - env->admin settings registry + RegistryDrivenForm + encrypted creds
 - Embedded-signing card + Test connection + setup help
 - Dev-mode EMAIL_REDIRECT_TO banner
 - Pipeline rules admin page
 - Sales email config card
 - Audit log details Sheet
 - EOI tab: Finalising badge, absolute timestamps, sequential indicator
 - Notes pipeline_stage_at_creation (migration 0069)
 - Documenso numeric ID dual-key webhook (migration 0068)
 - Dimensions criterion copy (migration 0067)

Tests: 1374/1374 vitest pass. tsc clean. lint clean.

See docs/AUDIT-FIX-WAVE-2026-05-18.md for the full progress report and
the user-input items still pending.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-18 13:28:50 +02:00

398 lines
12 KiB
TypeScript

import { randomBytes } from 'node:crypto';
import { and, desc, eq, count } from 'drizzle-orm';
import { db } from '@/lib/db';
import { webhooks, webhookDeliveries } from '@/lib/db/schema/system';
import { createAuditLog, type AuditMeta } from '@/lib/audit';
import { encrypt, decrypt } from '@/lib/utils/encryption';
import { NotFoundError } from '@/lib/errors';
import { getQueue } from '@/lib/queue';
import type {
CreateWebhookInput,
UpdateWebhookInput,
ListDeliveriesInput,
} from '@/lib/validators/webhooks';
import type { WebhookEvent } from '@/lib/services/webhook-event-map';
// ─── Types ────────────────────────────────────────────────────────────────────
// ─── Helpers ─────────────────────────────────────────────────────────────────
/** Generates a 32-byte hex secret for signing webhook payloads. */
function generateSecret(): string {
return randomBytes(32).toString('hex');
}
/**
* Returns a masked representation of the plaintext secret.
* Shows the first 5 and last 3 characters: `wh_ab...xyz`
*/
function maskSecret(plaintext: string): string {
if (plaintext.length < 10) return '***';
return `${plaintext.slice(0, 5)}...${plaintext.slice(-3)}`;
}
// ─── Create ───────────────────────────────────────────────────────────────────
export async function createWebhook(
portId: string,
userId: string,
data: CreateWebhookInput,
meta: AuditMeta,
) {
const plaintextSecret = generateSecret();
const encryptedSecret = encrypt(plaintextSecret);
const [webhook] = await db
.insert(webhooks)
.values({
portId,
name: data.name,
url: data.url,
secret: encryptedSecret,
events: data.events,
isActive: data.isActive,
createdBy: userId,
})
.returning();
void createAuditLog({
userId: meta.userId,
portId,
action: 'create',
entityType: 'webhook',
entityId: webhook!.id,
newValue: { name: data.name, url: data.url, events: data.events },
ipAddress: meta.ipAddress,
userAgent: meta.userAgent,
});
// Return with plaintext secret - shown ONCE only on creation
return {
...webhook!,
secret: plaintextSecret,
secretMasked: maskSecret(plaintextSecret),
};
}
// ─── List ─────────────────────────────────────────────────────────────────────
export async function listWebhooks(portId: string) {
const rows = await db
.select()
.from(webhooks)
.where(eq(webhooks.portId, portId))
.orderBy(desc(webhooks.createdAt));
return rows.map((w) => {
let secretMasked = '***';
if (w.secret) {
try {
const plaintext = decrypt(w.secret);
secretMasked = maskSecret(plaintext);
} catch {
secretMasked = '***';
}
}
return { ...w, secret: undefined, secretMasked };
});
}
// ─── Get Single ───────────────────────────────────────────────────────────────
export async function getWebhook(portId: string, webhookId: string) {
// M-MT05: portId in the WHERE so the row never leaves the DB if it
// belongs to a different tenant — the prior JS-side .portId !== portId
// check fired AFTER the row was already loaded, which a future timing-
// or audit-side-channel could exploit.
const webhook = await db.query.webhooks.findFirst({
where: and(eq(webhooks.id, webhookId), eq(webhooks.portId, portId)),
});
if (!webhook) {
throw new NotFoundError('Webhook');
}
let secretMasked = '***';
if (webhook.secret) {
try {
const plaintext = decrypt(webhook.secret);
secretMasked = maskSecret(plaintext);
} catch {
secretMasked = '***';
}
}
return { ...webhook, secret: undefined, secretMasked };
}
// ─── Update ───────────────────────────────────────────────────────────────────
export async function updateWebhook(
portId: string,
webhookId: string,
data: UpdateWebhookInput,
meta: AuditMeta,
) {
// M-MT05: portId in WHERE — same reasoning as getWebhook.
const existing = await db.query.webhooks.findFirst({
where: and(eq(webhooks.id, webhookId), eq(webhooks.portId, portId)),
});
if (!existing) {
throw new NotFoundError('Webhook');
}
const [updated] = await db
.update(webhooks)
.set({ ...data, updatedAt: new Date() })
.where(and(eq(webhooks.id, webhookId), eq(webhooks.portId, portId)))
.returning();
void createAuditLog({
userId: meta.userId,
portId,
action: 'update',
entityType: 'webhook',
entityId: webhookId,
oldValue: {
name: existing.name,
url: existing.url,
events: existing.events,
isActive: existing.isActive,
},
newValue: data as Record<string, unknown>,
ipAddress: meta.ipAddress,
userAgent: meta.userAgent,
});
return { ...updated!, secret: undefined };
}
// ─── Delete ───────────────────────────────────────────────────────────────────
export async function deleteWebhook(portId: string, webhookId: string, meta: AuditMeta) {
// M-MT05: portId in WHERE — same reasoning as getWebhook.
const existing = await db.query.webhooks.findFirst({
where: and(eq(webhooks.id, webhookId), eq(webhooks.portId, portId)),
});
if (!existing) {
throw new NotFoundError('Webhook');
}
// CASCADE deletes webhook_deliveries
await db.delete(webhooks).where(and(eq(webhooks.id, webhookId), eq(webhooks.portId, portId)));
void createAuditLog({
userId: meta.userId,
portId,
action: 'delete',
entityType: 'webhook',
entityId: webhookId,
oldValue: { name: existing.name, url: existing.url },
ipAddress: meta.ipAddress,
userAgent: meta.userAgent,
});
}
// ─── Regenerate Secret ────────────────────────────────────────────────────────
export async function regenerateSecret(portId: string, webhookId: string, meta: AuditMeta) {
const existing = await db.query.webhooks.findFirst({
where: eq(webhooks.id, webhookId),
});
if (!existing || existing.portId !== portId) {
throw new NotFoundError('Webhook');
}
const plaintextSecret = generateSecret();
const encryptedSecret = encrypt(plaintextSecret);
await db
.update(webhooks)
.set({ secret: encryptedSecret, updatedAt: new Date() })
.where(and(eq(webhooks.id, webhookId), eq(webhooks.portId, portId)));
void createAuditLog({
userId: meta.userId,
portId,
action: 'update',
entityType: 'webhook',
entityId: webhookId,
metadata: { type: 'secret_regenerated' },
ipAddress: meta.ipAddress,
userAgent: meta.userAgent,
severity: 'warning',
});
// Return new plaintext secret - shown ONCE
return {
webhookId,
secret: plaintextSecret,
secretMasked: maskSecret(plaintextSecret),
};
}
// ─── List Deliveries ─────────────────────────────────────────────────────────
export async function listDeliveries(
portId: string,
webhookId: string,
query: ListDeliveriesInput,
) {
// Verify webhook belongs to port
const webhook = await db.query.webhooks.findFirst({
where: eq(webhooks.id, webhookId),
});
if (!webhook || webhook.portId !== portId) {
throw new NotFoundError('Webhook');
}
const { page, limit, status } = query;
const offset = (page - 1) * limit;
const filters = [eq(webhookDeliveries.webhookId, webhookId)];
if (status) {
filters.push(eq(webhookDeliveries.status, status));
}
const [countRow] = await db
.select({ total: count() })
.from(webhookDeliveries)
.where(and(...filters));
const total = countRow?.total ?? 0;
const data = await db
.select()
.from(webhookDeliveries)
.where(and(...filters))
.orderBy(desc(webhookDeliveries.createdAt))
.limit(limit)
.offset(offset);
return { data, total };
}
// ─── Redeliver a previously failed / dead-letter delivery ───────────────────
/**
* Clones a failed or dead-letter delivery into a fresh `pending` row and
* re-enqueues it. Multi-tenant safe: looks up the source delivery via
* its webhook → port. Idempotency: each redeliver creates a new row so
* the original record (and its failure response body) is preserved for
* audit. The new delivery's payload includes a `retried_from` marker
* that downstream receivers can use to recognise replays.
*/
export async function redeliverWebhookDelivery(
portId: string,
webhookId: string,
deliveryId: string,
meta: AuditMeta,
) {
const webhook = await db.query.webhooks.findFirst({
where: eq(webhooks.id, webhookId),
});
if (!webhook || webhook.portId !== portId) {
throw new NotFoundError('Webhook');
}
if (!webhook.isActive) {
throw new NotFoundError('Webhook is inactive');
}
const [source] = await db
.select()
.from(webhookDeliveries)
.where(and(eq(webhookDeliveries.id, deliveryId), eq(webhookDeliveries.webhookId, webhookId)))
.limit(1);
if (!source) throw new NotFoundError('Delivery');
const replayPayload = {
...(source.payload as Record<string, unknown>),
retried_from: deliveryId,
retried_at: new Date().toISOString(),
};
const [next] = await db
.insert(webhookDeliveries)
.values({
webhookId,
eventType: source.eventType,
payload: replayPayload,
status: 'pending',
})
.returning();
const queue = getQueue('webhooks');
await queue.add(
'deliver',
{
webhookId,
portId,
event: source.eventType,
deliveryId: next!.id,
payload: replayPayload,
},
{ jobId: `deliver:${next!.id}` },
);
void createAuditLog({
userId: meta.userId,
portId,
action: 'webhook_retried',
entityType: 'webhook_delivery',
entityId: next!.id,
metadata: { redeliveredFrom: deliveryId, originalStatus: source.status },
ipAddress: meta.ipAddress,
userAgent: meta.userAgent,
});
return { deliveryId: next!.id, status: 'queued' };
}
// ─── Send Test Webhook ────────────────────────────────────────────────────────
export async function sendTestWebhook(portId: string, webhookId: string, eventType: WebhookEvent) {
const webhook = await db.query.webhooks.findFirst({
where: eq(webhooks.id, webhookId),
});
if (!webhook || webhook.portId !== portId) {
throw new NotFoundError('Webhook');
}
// Create a pending delivery record
const [delivery] = await db
.insert(webhookDeliveries)
.values({
webhookId,
eventType,
payload: {
test: true,
event: eventType,
port_id: portId,
data: { message: 'This is a test webhook delivery' },
},
status: 'pending',
})
.returning();
// Enqueue the job
const queue = getQueue('webhooks');
await queue.add(
'deliver',
{
webhookId,
portId,
event: eventType,
deliveryId: delivery!.id,
payload: delivery!.payload,
},
{ jobId: `deliver:${delivery!.id}` },
);
return { deliveryId: delivery!.id, status: 'queued' };
}