Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/db/src/public-api.server.ts
T
2026-07-08 16:15:37 +02:00

644 lines
22 KiB
TypeScript

import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
import { getDbClient } from "./client.server.js";
import type {
InboxLead,
Prisma,
PublicIncomingWebhookEndpoint,
PublicWebhookAuthMode,
PublicWebhookDeliveryLog,
PublicWebhookDeliveryStatus,
PublicWebhookIngestionLog,
PublicWebhookSubscription,
} from "./prisma-browser.js";
export const PUBLIC_API_SECRET_HASH_VERSION = 1;
export const DEFAULT_PUBLIC_API_SECRET_HASH_SECRET = "public-api-secret-v1";
export const PUBLIC_WEBHOOK_MAX_DELIVERY_ATTEMPTS = 5;
export const PUBLIC_WEBHOOK_AUTO_DISABLE_FAILURES = 10;
export type PublicApiSecretMetadata = {
hash: string;
prefix: string;
lastFour: string;
};
export type PublicWebhookEndpointWithSecret = PublicIncomingWebhookEndpoint & {
plaintextSecret: string | null;
};
export type PublicWebhookSubscriptionWithSecret = PublicWebhookSubscription & {
plaintextSecret: string;
};
export type CreatePublicIncomingWebhookEndpointInput = {
tenantId: string;
slug: string;
name: string;
authMode: PublicWebhookAuthMode;
apiKeyId?: string | null;
payloadMapping?: Prisma.InputJsonValue;
autoMatchRules?: Prisma.InputJsonValue;
isDemoData?: boolean;
};
export type CreatePublicWebhookSubscriptionInput = {
tenantId: string;
name: string;
targetUrl: string;
eventTypes: readonly string[];
createdByUserId?: string | null;
isDemoData?: boolean;
};
export type PublicWebhookPayload = Prisma.InputJsonValue;
export type IngestPublicLeadWebhookInput = {
tenantId: string;
endpoint: Pick<PublicIncomingWebhookEndpoint, "id" | "slug" | "authMode" | "payloadMapping" | "autoMatchRules">;
payload: PublicWebhookPayload;
requestId?: string | null;
sourceIp?: string | null;
};
export type IngestPublicLeadWebhookResult = {
lead: InboxLead;
log: PublicWebhookIngestionLog;
matchedKontaktId: string | null;
automationExecutionIds: string[];
};
export type EnqueuePublicWebhookEventInput = {
tenantId: string;
eventType: string;
payload: PublicWebhookPayload;
sourceEventId?: string | null;
};
export type EnqueuePublicWebhookEventResult = {
deliveries: PublicWebhookDeliveryLog[];
};
export type DeliverPublicWebhookInput = {
deliveryId: string;
tenantId: string;
payload: PublicWebhookPayload;
fetcher?: typeof fetch;
hashSecret?: string | null;
};
export type PublicWebhookDeliveryHeaders = {
"Content-Type": "application/json";
"X-HiveGrid-Event": string;
"X-HiveGrid-Delivery": string;
"X-HiveGrid-Idempotency-Key": string;
"X-HiveGrid-Timestamp": string;
"X-HiveGrid-Signature": string;
};
type PublicApiClient = ReturnType<typeof getDbClient>;
export function generatePublicApiSecret(): string {
return `hgwh_${randomBytes(32).toString("base64url")}`;
}
export function derivePublicWebhookSigningSecret(input: { tenantId: string; subscriptionId: string }, hashSecret?: string | null): string {
const secret = normalizePublicApiSecretHashSecret(hashSecret);
const digest = createHmac("sha256", secret).update(`${input.tenantId}:${input.subscriptionId}`).digest("base64url");
return `hgwh_${digest}`;
}
export function derivePublicApiSecretMetadata(secret: string, hashSecret?: string | null): PublicApiSecretMetadata {
const normalizedSecret = normalizePublicApiSecretHashSecret(hashSecret);
return {
hash: createHmac("sha256", normalizedSecret).update(secret).digest("hex"),
prefix: secret.slice(0, 10),
lastFour: secret.slice(-4),
};
}
export function verifyPublicApiSecret(secret: string, expectedHash: string | null | undefined, hashSecret?: string | null): boolean {
if (!expectedHash) {
return false;
}
const actual = derivePublicApiSecretMetadata(secret, hashSecret).hash;
return safeEqual(actual, expectedHash);
}
export async function createPublicIncomingWebhookEndpoint(
input: CreatePublicIncomingWebhookEndpointInput,
client: PublicApiClient = getDbClient(),
hashSecret?: string | null,
): Promise<PublicWebhookEndpointWithSecret> {
const plaintextSecret = input.authMode === "api_key" ? null : generatePublicApiSecret();
const metadata = plaintextSecret ? derivePublicApiSecretMetadata(plaintextSecret, hashSecret) : null;
const endpoint = await client.publicIncomingWebhookEndpoint.create({
data: {
tenantId: input.tenantId,
slug: input.slug,
name: input.name,
authMode: input.authMode,
apiKeyId: input.apiKeyId ?? null,
tokenHash: input.authMode === "url_token" ? metadata?.hash : null,
tokenPrefix: input.authMode === "url_token" ? metadata?.prefix : null,
tokenLastFour: input.authMode === "url_token" ? metadata?.lastFour : null,
hmacSecretHash: input.authMode === "hmac" ? metadata?.hash : null,
hmacSecretPrefix: input.authMode === "hmac" ? metadata?.prefix : null,
hmacSecretLastFour: input.authMode === "hmac" ? metadata?.lastFour : null,
payloadMapping: input.payloadMapping ?? {},
autoMatchRules: input.autoMatchRules ?? {},
isDemoData: input.isDemoData ?? false,
},
});
return { ...endpoint, plaintextSecret };
}
export async function findPublicIncomingWebhookEndpoint(
input: { tenantId: string; slug: string },
client: PublicApiClient = getDbClient(),
): Promise<PublicIncomingWebhookEndpoint | null> {
return client.publicIncomingWebhookEndpoint.findFirst({
where: {
tenantId: input.tenantId,
slug: input.slug,
archivedAt: null,
},
});
}
export async function createPublicWebhookIngestionLog(
data: Prisma.PublicWebhookIngestionLogUncheckedCreateInput,
client: PublicApiClient = getDbClient(),
): Promise<PublicWebhookIngestionLog> {
return client.publicWebhookIngestionLog.create({ data });
}
export async function ingestPublicLeadWebhook(
input: IngestPublicLeadWebhookInput,
client: PublicApiClient = getDbClient(),
): Promise<IngestPublicLeadWebhookResult> {
const payloadHash = hashJsonValue(input.payload);
const extracted = extractLeadFields(input.payload, input.endpoint.payloadMapping);
return client.$transaction(async (tx) => {
await tx.$executeRaw`SELECT set_config('app.tenant_id', ${input.tenantId}, true)`;
const matchedKontaktId = await findMatchingKontaktId(tx, input.tenantId, extracted.email, extracted.telefon);
const lead = await tx.inboxLead.create({
data: {
tenantId: input.tenantId,
quelle: "custom",
quelleDetail: {
source: "public_api_webhook",
endpointId: input.endpoint.id,
endpointSlug: input.endpoint.slug,
requestId: input.requestId ?? null,
},
sourceOrigin: `public_api:${input.endpoint.slug}`,
status: "new",
vorname: extracted.vorname,
nachname: extracted.nachname,
email: extracted.email,
telefon: extracted.telefon,
message: extracted.message,
rohdaten: input.payload,
verknuepfterKontaktId: matchedKontaktId,
},
});
const automationExecutionIds = await createWebhookAutomationExecutions(tx, {
tenantId: input.tenantId,
endpointId: input.endpoint.id,
endpointSlug: input.endpoint.slug,
leadId: lead.id,
payload: input.payload,
payloadHash,
sourceEventId: input.requestId,
});
const log = await tx.publicWebhookIngestionLog.create({
data: {
tenantId: input.tenantId,
endpointId: input.endpoint.id,
endpointSlug: input.endpoint.slug,
authMode: input.endpoint.authMode,
requestId: input.requestId ?? null,
sourceIp: input.sourceIp ?? null,
status: 201,
result: "lead_created",
payloadHash,
payloadPreview: createPayloadPreview(input.payload),
leadId: lead.id,
matchedKontaktId,
automationRunId: automationExecutionIds[0] ?? null,
},
});
return { lead, log, matchedKontaktId, automationExecutionIds };
});
}
export async function createPublicWebhookSubscription(
input: CreatePublicWebhookSubscriptionInput,
client: PublicApiClient = getDbClient(),
hashSecret?: string | null,
): Promise<PublicWebhookSubscriptionWithSecret> {
const id = randomUUID();
const plaintextSecret = derivePublicWebhookSigningSecret({ tenantId: input.tenantId, subscriptionId: id }, hashSecret);
const metadata = derivePublicApiSecretMetadata(plaintextSecret, hashSecret);
const subscription = await client.publicWebhookSubscription.create({
data: {
id,
tenantId: input.tenantId,
name: input.name,
targetUrl: input.targetUrl,
eventTypes: [...new Set(input.eventTypes.filter(Boolean))],
signingSecretHash: metadata.hash,
signingSecretPrefix: metadata.prefix,
signingSecretLastFour: metadata.lastFour,
createdByUserId: input.createdByUserId ?? null,
isDemoData: input.isDemoData ?? false,
},
});
return { ...subscription, plaintextSecret };
}
export async function enqueuePublicWebhookEvent(
input: EnqueuePublicWebhookEventInput,
client: PublicApiClient = getDbClient(),
): Promise<EnqueuePublicWebhookEventResult> {
const payloadHash = hashJsonValue(input.payload);
const subscriptions = await client.publicWebhookSubscription.findMany({
where: {
tenantId: input.tenantId,
status: "active",
archivedAt: null,
},
});
const matching = subscriptions.filter((subscription) => subscriptionMatchesEvent(subscription.eventTypes, input.eventType));
const deliveries = await Promise.all(
matching.map((subscription) =>
client.publicWebhookDeliveryLog.create({
data: {
tenantId: input.tenantId,
subscriptionId: subscription.id,
eventType: input.eventType,
targetUrl: subscription.targetUrl,
status: "queued",
idempotencyKey: buildPublicWebhookIdempotencyKey({
subscriptionId: subscription.id,
eventType: input.eventType,
sourceEventId: input.sourceEventId,
payloadHash,
}),
payloadHash,
},
}),
),
);
return { deliveries };
}
export async function markPublicWebhookDeliveryResult(
input: {
deliveryId: string;
tenantId: string;
ok: boolean;
httpStatus?: number | null;
error?: string | null;
responsePreview?: Prisma.InputJsonValue;
now?: Date;
},
client: PublicApiClient = getDbClient(),
): Promise<PublicWebhookDeliveryLog> {
const now = input.now ?? new Date();
return client.$transaction(async (tx) => {
const delivery = await tx.publicWebhookDeliveryLog.findFirst({
where: { id: input.deliveryId, tenantId: input.tenantId },
include: { subscription: true },
});
if (!delivery) {
throw new Error("Public webhook delivery not found");
}
if (input.ok) {
await tx.publicWebhookSubscription.update({
where: { id: delivery.subscriptionId },
data: { failureCount: 0, lastDeliveredAt: now, lastErrorAt: null },
});
return tx.publicWebhookDeliveryLog.update({
where: { id: delivery.id },
data: { status: "success", httpStatus: input.httpStatus ?? null, error: null, responsePreview: input.responsePreview ?? undefined, sentAt: now, nextAttemptAt: null },
});
}
const nextAttempt = delivery.attempt + 1;
const nextFailureCount = delivery.subscription.failureCount + 1;
const exhaustedDelivery = nextAttempt > delivery.maxAttempts;
const shouldDisable = nextFailureCount >= PUBLIC_WEBHOOK_AUTO_DISABLE_FAILURES;
const nextStatus: PublicWebhookDeliveryStatus = shouldDisable ? "disabled" : exhaustedDelivery ? "failed" : "retrying";
const nextAttemptAt = nextStatus === "retrying" ? planPublicWebhookRetry({ attempt: delivery.attempt, now }) : null;
await tx.publicWebhookSubscription.update({
where: { id: delivery.subscriptionId },
data: {
failureCount: nextFailureCount,
lastErrorAt: now,
...(shouldDisable ? { status: "paused", autoDisabledAt: now, pausedAt: now } : {}),
},
});
return tx.publicWebhookDeliveryLog.update({
where: { id: delivery.id },
data: {
status: nextStatus,
httpStatus: input.httpStatus ?? null,
error: input.error ?? null,
responsePreview: input.responsePreview ?? undefined,
nextAttemptAt,
attempt: exhaustedDelivery || shouldDisable ? delivery.attempt : nextAttempt,
},
});
});
}
export async function deliverPublicWebhook(
input: DeliverPublicWebhookInput,
client: PublicApiClient = getDbClient(),
): Promise<PublicWebhookDeliveryLog> {
const delivery = await client.publicWebhookDeliveryLog.findFirst({
where: { id: input.deliveryId, tenantId: input.tenantId },
include: { subscription: true },
});
if (!delivery) {
throw new Error("Public webhook delivery not found");
}
if (delivery.subscription.status !== "active" || delivery.status === "success" || delivery.status === "disabled") {
return delivery;
}
await client.publicWebhookDeliveryLog.update({
where: { id: delivery.id },
data: { status: "delivering" },
});
const headers = createPublicWebhookDeliveryHeadersForSubscription({
subscription: delivery.subscription,
eventType: delivery.eventType,
deliveryId: delivery.id,
idempotencyKey: delivery.idempotencyKey,
payload: input.payload,
hashSecret: input.hashSecret,
});
try {
const response = await (input.fetcher ?? fetch)(delivery.targetUrl, {
method: "POST",
headers,
body: stableStringify(input.payload),
});
const responsePreview = await readWebhookResponsePreview(response);
return markPublicWebhookDeliveryResult(
{
deliveryId: delivery.id,
tenantId: delivery.tenantId,
ok: response.ok,
httpStatus: response.status,
error: response.ok ? null : `Webhook target returned HTTP ${response.status}.`,
responsePreview,
},
client,
);
} catch (error) {
return markPublicWebhookDeliveryResult(
{
deliveryId: delivery.id,
tenantId: delivery.tenantId,
ok: false,
error: error instanceof Error ? error.name : "WebhookDeliveryError",
},
client,
);
}
}
export function createPublicWebhookDeliveryHeaders(input: {
eventType: string;
deliveryId: string;
idempotencyKey: string;
payload: PublicWebhookPayload;
signingSecret: string;
timestamp?: Date;
}): PublicWebhookDeliveryHeaders {
const timestamp = Math.floor((input.timestamp ?? new Date()).getTime() / 1000).toString();
const body = stableStringify(input.payload);
const signature = createHmac("sha256", input.signingSecret).update(`${timestamp}.${body}`).digest("hex");
return {
"Content-Type": "application/json",
"X-HiveGrid-Event": input.eventType,
"X-HiveGrid-Delivery": input.deliveryId,
"X-HiveGrid-Idempotency-Key": input.idempotencyKey,
"X-HiveGrid-Timestamp": timestamp,
"X-HiveGrid-Signature": `sha256=${signature}`,
};
}
export function createPublicWebhookDeliveryHeadersForSubscription(input: {
subscription: Pick<PublicWebhookSubscription, "id" | "tenantId">;
eventType: string;
deliveryId: string;
idempotencyKey: string;
payload: PublicWebhookPayload;
hashSecret?: string | null;
timestamp?: Date;
}): PublicWebhookDeliveryHeaders {
return createPublicWebhookDeliveryHeaders({
eventType: input.eventType,
deliveryId: input.deliveryId,
idempotencyKey: input.idempotencyKey,
payload: input.payload,
signingSecret: derivePublicWebhookSigningSecret(
{ tenantId: input.subscription.tenantId, subscriptionId: input.subscription.id },
input.hashSecret,
),
timestamp: input.timestamp,
});
}
export function verifyPublicWebhookHmacWithPresentedSecret(input: {
body: string;
timestamp: string | null;
signature: string | null;
presentedSecret: string | null;
secretHash: string | null;
hashSecret?: string | null;
}): boolean {
if (!input.timestamp || !input.signature || !input.presentedSecret || !verifyPublicApiSecret(input.presentedSecret, input.secretHash, input.hashSecret)) {
return false;
}
const expected = `sha256=${createHmac("sha256", input.presentedSecret).update(`${input.timestamp}.${input.body}`).digest("hex")}`;
return safeEqual(expected, input.signature);
}
export function buildPublicWebhookIdempotencyKey(input: {
subscriptionId: string;
eventType: string;
sourceEventId?: string | null;
payloadHash: string;
}): string {
return [input.subscriptionId, input.eventType, input.sourceEventId || input.payloadHash].join(":");
}
export function planPublicWebhookRetry(input: { attempt: number; now?: Date; baseDelayMs?: number }): Date {
const baseDelayMs = input.baseDelayMs ?? 60_000;
const delayMs = baseDelayMs * 2 ** Math.max(input.attempt - 1, 0);
return new Date((input.now ?? new Date()).getTime() + delayMs);
}
export function hashJsonValue(value: PublicWebhookPayload): string {
return createHash("sha256").update(stableStringify(value)).digest("hex");
}
function normalizePublicApiSecretHashSecret(secret: string | undefined | null): string {
const normalized = secret?.trim();
return normalized || DEFAULT_PUBLIC_API_SECRET_HASH_SECRET;
}
function safeEqual(actual: string, expected: string): boolean {
const actualBuffer = Buffer.from(actual);
const expectedBuffer = Buffer.from(expected);
return actualBuffer.length === expectedBuffer.length && timingSafeEqual(actualBuffer, expectedBuffer);
}
function extractLeadFields(payload: PublicWebhookPayload, mapping: Prisma.JsonValue): { vorname: string | null; nachname: string | null; email: string | null; telefon: string | null; message: string | null } {
const object = isRecord(payload) ? payload : {};
const map = isRecord(mapping) ? mapping : {};
return {
vorname: readMappedString(object, map, "vorname", ["vorname", "firstName", "first_name", "contact.firstName"]),
nachname: readMappedString(object, map, "nachname", ["nachname", "lastName", "last_name", "contact.lastName"]),
email: normalizeEmail(readMappedString(object, map, "email", ["email", "contact.email", "from.email"])),
telefon: readMappedString(object, map, "telefon", ["telefon", "phone", "telephone", "contact.phone"]),
message: readMappedString(object, map, "message", ["message", "nachricht", "text", "body"]),
};
}
function readMappedString(object: Record<string, unknown>, mapping: Record<string, unknown>, key: string, fallbacks: readonly string[]): string | null {
const mapped = typeof mapping[key] === "string" ? getPath(object, mapping[key]) : undefined;
const value = mapped ?? fallbacks.map((path) => getPath(object, path)).find((item) => typeof item === "string" && item.trim());
return typeof value === "string" && value.trim() ? value.trim().slice(0, 2_000) : null;
}
function getPath(object: Record<string, unknown>, path: string): unknown {
let current: unknown = object;
for (const part of path.split(".")) {
if (!isRecord(current)) {
return undefined;
}
current = current[part];
}
return current;
}
async function findMatchingKontaktId(
tx: Prisma.TransactionClient,
tenantId: string,
email: string | null,
telefon: string | null,
): Promise<string | null> {
if (email) {
const match = await tx.kontaktEmail.findFirst({
where: { tenantId, email },
select: { kontaktId: true },
});
if (match) return match.kontaktId;
}
if (telefon) {
const match = await tx.kontaktTelefon.findFirst({
where: { tenantId, telefon },
select: { kontaktId: true },
});
if (match) return match.kontaktId;
}
return null;
}
async function createWebhookAutomationExecutions(
tx: Prisma.TransactionClient,
input: { tenantId: string; endpointId: string; endpointSlug: string; leadId: string; payload: PublicWebhookPayload; payloadHash: string; sourceEventId?: string | null },
): Promise<string[]> {
const rules = await tx.automationRule.findMany({
where: { tenantId: input.tenantId, triggerKey: "webhook.received", enabled: true, status: "active", archivedAt: null },
select: { id: true, name: true },
});
const executions = await Promise.all(
rules.map((rule) =>
tx.automationExecution.create({
data: {
tenantId: input.tenantId,
ruleId: rule.id,
triggerKey: "webhook.received",
triggerPayload: {
source: "external_event",
endpointId: input.endpointId,
endpointSlug: input.endpointSlug,
leadId: input.leadId,
payload: input.payload,
},
status: "queued",
idempotencyKey: [input.tenantId, rule.id, "webhook.received", input.sourceEventId || input.payloadHash].join(":"),
summaryText: `Webhook ${input.endpointSlug} queued automation ${rule.name}`,
},
}),
),
);
return executions.map((execution) => execution.id);
}
function subscriptionMatchesEvent(eventTypes: Prisma.JsonValue, eventType: string): boolean {
if (!Array.isArray(eventTypes)) {
return false;
}
return eventTypes.includes("*") || eventTypes.includes(eventType);
}
function createPayloadPreview(payload: PublicWebhookPayload): Prisma.InputJsonValue {
if (!isRecord(payload)) {
return payload;
}
const entries = Object.entries(payload).slice(0, 20).map(([key, value]) => [key, previewValue(value)]);
return Object.fromEntries(entries);
}
function previewValue(value: unknown): Prisma.InputJsonValue {
if (typeof value === "string") return value.slice(0, 500);
if (typeof value === "number" || typeof value === "boolean") return value;
if (value === null) return "null";
if (Array.isArray(value)) return value.slice(0, 10).map(previewValue);
if (isRecord(value)) return Object.fromEntries(Object.entries(value).slice(0, 10).map(([key, item]) => [key, previewValue(item)]));
return String(value);
}
async function readWebhookResponsePreview(response: Response): Promise<Prisma.InputJsonValue> {
const text = await response.text().catch(() => "");
return {
status: response.status,
body: text.slice(0, 1_000),
};
}
function normalizeEmail(value: string | null): string | null {
return value ? value.trim().toLowerCase() : null;
}
function stableStringify(value: unknown): string {
if (value === null || typeof value !== "object") {
return JSON.stringify(value);
}
if (Array.isArray(value)) {
return `[${value.map(stableStringify).join(",")}]`;
}
const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b));
return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`).join(",")}}`;
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}