deepline 0.3.88 → 0.3.89

package/dist/bundling-sources/shared_libs/monitors/callback-security.ts

@@ -0,0 +1,333 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+const PARALLEL_WEBHOOK_SIGNATURE_TOLERANCE_MS = 5 * 60 * 1000;
+const STANDARD_WEBHOOK_SECRET_PREFIX = 'whsec_';
+
+type WebhookVerificationOk = {
+  ok: true;
+  mode: 'verified' | 'unsigned_non_prod';
+};
+
+type WebhookVerificationFailure = {
+  ok: false;
+  status: 401 | 500;
+  code: string;
+  message: string;
+};
+
+export type WebhookVerificationResult =
+  | WebhookVerificationOk
+  | WebhookVerificationFailure;
+
+export type ProviderCallbackBindingValidationFailure = {
+  ok: false;
+  status: 409;
+  code: 'provider_callback_binding_mismatch';
+  message: string;
+  fields: string[];
+};
+
+export type ProviderCallbackBindingValidationResult =
+  | { ok: true }
+  | ProviderCallbackBindingValidationFailure;
+
+function normalizedEnvFlag(value: string | undefined) {
+  return value?.trim().toLowerCase();
+}
+
+function readRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function readString(value: unknown) {
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed || null;
+}
+
+function readStringAtPath(record: Record<string, unknown>, path: string) {
+  const value = path.split('.').reduce<unknown>((current, part) => {
+    if (!current || typeof current !== 'object' || Array.isArray(current)) {
+      return undefined;
+    }
+    return (current as Record<string, unknown>)[part];
+  }, record);
+  return readString(value);
+}
+
+function addString(
+  values: Set<string>,
+  value: string | number | null | undefined,
+) {
+  const string = readString(value);
+  if (string) values.add(string);
+}
+
+function genericWebhookIdsFromPayload(payload: Record<string, unknown>) {
+  const values = new Set<string>();
+  for (const path of [
+    'webhook_id',
+    'webhookId',
+    'hook_id',
+    'hookId',
+    'webhook.id',
+    'data.webhook_id',
+    'data.webhookId',
+    'data.hook_id',
+    'data.hookId',
+    'result.webhook_id',
+    'result.webhookId',
+    'result.data.webhook_id',
+    'result.data.webhookId',
+  ]) {
+    addString(values, readStringAtPath(payload, path));
+  }
+
+  const events = Array.isArray(payload.events) ? payload.events : [];
+  for (const item of events) {
+    const event = readRecord(item);
+    addString(values, readStringAtPath(event, 'webhook_id'));
+    addString(values, readStringAtPath(event, 'webhookId'));
+  }
+
+  return values;
+}
+
+function isTheirstackWebhookBindingPayload(payload: Record<string, unknown>) {
+  return Boolean(
+    readString(payload.id) &&
+    readString(payload.search_id) &&
+    readString(payload.event_type) &&
+    readString(payload.url),
+  );
+}
+
+function theirstackWebhookIdsFromPayload(payload: Record<string, unknown>) {
+  const values = new Set<string>();
+  addString(values, payload.webhook_id as string | number | null | undefined);
+  addString(values, payload.webhookId as string | number | null | undefined);
+  if (isTheirstackWebhookBindingPayload(payload)) {
+    addString(values, payload.id as string | number | null | undefined);
+  }
+  return values;
+}
+
+function theirstackSavedSearchIdsFromPayload(payload: Record<string, unknown>) {
+  const values = new Set<string>();
+  addString(values, payload.search_id as string | number | null | undefined);
+  addString(
+    values,
+    payload.saved_search_id as string | number | null | undefined,
+  );
+  return values;
+}
+
+function mismatchedFields(input: {
+  expected: string | null;
+  actual: Set<string>;
+  field: string;
+}) {
+  if (!input.expected || input.actual.size === 0) return [];
+  return [...input.actual].some((value) => value !== input.expected)
+    ? [input.field]
+    : [];
+}
+
+export function theirstackSavedSearchIdFromProviderBinding(
+  providerBinding: Record<string, unknown>,
+) {
+  const upstreamResponse = readRecord(providerBinding.upstream_response);
+  const savedSearch = readRecord(upstreamResponse.saved_search);
+  const webhook = readRecord(upstreamResponse.webhook);
+  return (
+    readString(savedSearch.id) ??
+    readString(readRecord(savedSearch.data).id) ??
+    readString(webhook.search_id) ??
+    readString(readRecord(webhook.data).search_id)
+  );
+}
+
+export function validateProviderCallbackBinding(input: {
+  provider: string;
+  payload: Record<string, unknown>;
+  providerBinding: Record<string, unknown>;
+  upstreamWebhookId?: string | null;
+}): ProviderCallbackBindingValidationResult {
+  const fields =
+    input.provider === 'theirstack'
+      ? [
+          ...mismatchedFields({
+            expected: input.upstreamWebhookId ?? null,
+            actual: theirstackWebhookIdsFromPayload(input.payload),
+            field: 'webhook_id',
+          }),
+          ...mismatchedFields({
+            expected: theirstackSavedSearchIdFromProviderBinding(
+              input.providerBinding,
+            ),
+            actual: theirstackSavedSearchIdsFromPayload(input.payload),
+            field: 'search_id',
+          }),
+        ]
+      : mismatchedFields({
+          expected: input.upstreamWebhookId ?? null,
+          actual: genericWebhookIdsFromPayload(input.payload),
+          field: 'webhook_id',
+        });
+
+  if (fields.length === 0) {
+    return { ok: true };
+  }
+
+  return {
+    ok: false,
+    status: 409,
+    code: 'provider_callback_binding_mismatch',
+    message:
+      'Callback payload provider identifiers do not match the authenticated Deepline monitor binding.',
+    fields: Array.from(new Set(fields)),
+  };
+}
+
+function shouldRequireParallelWebhookSignature() {
+  const explicit = normalizedEnvFlag(
+    process.env.DEEPLINE_REQUIRE_PARALLEL_WEBHOOK_SIGNATURE,
+  );
+  if (explicit === 'true' || explicit === '1' || explicit === 'yes') {
+    return true;
+  }
+  if (explicit === 'false' || explicit === '0' || explicit === 'no') {
+    return false;
+  }
+  return process.env.NODE_ENV === 'production';
+}
+
+function parallelWebhookSigningSecret() {
+  return (
+    process.env.DEEPLINE_PARALLEL_WEBHOOK_SECRET?.trim() ||
+    process.env.PARALLEL_WEBHOOK_SECRET?.trim() ||
+    null
+  );
+}
+
+function signingKey(secret: string) {
+  if (secret.startsWith(STANDARD_WEBHOOK_SECRET_PREFIX)) {
+    return Buffer.from(
+      secret.slice(STANDARD_WEBHOOK_SECRET_PREFIX.length),
+      'base64',
+    );
+  }
+  return secret;
+}
+
+function readStandardWebhookHeader(headers: Headers, name: string) {
+  return (
+    headers.get(name) ?? headers.get(`svix-${name.replace('webhook-', '')}`)
+  );
+}
+
+function parseTimestampMs(value: string) {
+  const trimmed = value.trim();
+  if (/^\d+$/.test(trimmed)) {
+    const numeric = Number(trimmed);
+    if (!Number.isFinite(numeric)) return null;
+    return numeric > 10_000_000_000 ? numeric : numeric * 1000;
+  }
+  const parsed = Date.parse(trimmed);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function readSignatures(header: string) {
+  return header
+    .split(/\s+/)
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .flatMap((part) => {
+      const [version, signature] = part.split(',', 2);
+      return version === 'v1' && signature ? [signature] : [];
+    });
+}
+
+function signaturesEqual(expectedBase64: string, actualBase64: string) {
+  const expected = Buffer.from(expectedBase64, 'base64');
+  const actual = Buffer.from(actualBase64, 'base64');
+  if (expected.length === 0 || actual.length === 0) return false;
+  if (expected.length !== actual.length) return false;
+  return timingSafeEqual(expected, actual);
+}
+
+export function verifyParallelWebhookRequest(input: {
+  headers: Headers;
+  rawBody: string;
+  nowMs?: number;
+}): WebhookVerificationResult {
+  const secret = parallelWebhookSigningSecret();
+  if (!secret) {
+    if (shouldRequireParallelWebhookSignature()) {
+      return {
+        ok: false,
+        status: 500,
+        code: 'parallel_webhook_secret_missing',
+        message: 'Parallel webhook signing secret is not configured.',
+      };
+    }
+    return { ok: true, mode: 'unsigned_non_prod' };
+  }
+
+  const webhookId = readStandardWebhookHeader(input.headers, 'webhook-id');
+  const webhookTimestamp = readStandardWebhookHeader(
+    input.headers,
+    'webhook-timestamp',
+  );
+  const webhookSignature = readStandardWebhookHeader(
+    input.headers,
+    'webhook-signature',
+  );
+
+  if (!webhookId || !webhookTimestamp || !webhookSignature) {
+    return {
+      ok: false,
+      status: 401,
+      code: 'parallel_webhook_signature_missing',
+      message: 'Parallel webhook signature headers are missing.',
+    };
+  }
+
+  const timestampMs = parseTimestampMs(webhookTimestamp);
+  const nowMs = input.nowMs ?? Date.now();
+  if (
+    timestampMs === null ||
+    Math.abs(nowMs - timestampMs) > PARALLEL_WEBHOOK_SIGNATURE_TOLERANCE_MS
+  ) {
+    return {
+      ok: false,
+      status: 401,
+      code: 'parallel_webhook_timestamp_invalid',
+      message: 'Parallel webhook timestamp is outside the accepted window.',
+    };
+  }
+
+  const signedPayload = `${webhookId}.${webhookTimestamp}.${input.rawBody}`;
+  const expectedSignature = createHmac('sha256', signingKey(secret))
+    .update(signedPayload)
+    .digest('base64');
+  const signatures = readSignatures(webhookSignature);
+  if (
+    signatures.length === 0 ||
+    !signatures.some((signature) =>
+      signaturesEqual(expectedSignature, signature),
+    )
+  ) {
+    return {
+      ok: false,
+      status: 401,
+      code: 'parallel_webhook_signature_invalid',
+      message: 'Parallel webhook signature is invalid.',
+    };
+  }
+
+  return { ok: true, mode: 'verified' };
+}

package/dist/bundling-sources/shared_libs/monitors/cursor-page.ts

@@ -0,0 +1,42 @@
+/**
+ * Public cursor-page contract for API collections.
+ *
+ * Cursors are owned by the backing store (Convex in the common case). Treat
+ * them as opaque: return `next_cursor` verbatim and accept it verbatim on the
+ * next request. Do not wrap it with an offset or attempt to decode it.
+ */
+export type CursorPage<T> = {
+  items: T[];
+  returned: number;
+  has_more: boolean;
+  next_cursor: string | null;
+  total?: number;
+};
+
+export function cursorPage<T>(input: {
+  items: T[];
+  nextCursor?: string | null;
+  total?: number;
+}): CursorPage<T> {
+  const nextCursor = input.nextCursor?.trim() || null;
+  return {
+    items: input.items,
+    returned: input.items.length,
+    has_more: nextCursor !== null,
+    next_cursor: nextCursor,
+    ...(typeof input.total === 'number' ? { total: input.total } : {}),
+  };
+}
+
+/**
+ * Parses an opaque cursor query parameter without assigning it meaning.
+ * Returns null only for an oversized value so routes can give callers a
+ * deterministic 400 before passing unbounded input to their datastore.
+ */
+export function readOpaqueCursor(
+  value: string | null,
+): string | undefined | null {
+  const cursor = value?.trim();
+  if (!cursor) return undefined;
+  return cursor.length <= 8_192 ? cursor : null;
+}

package/dist/bundling-sources/shared_libs/monitors/deactivation-reasons.ts

@@ -49,6 +49,22 @@ export const MONITOR_DEACTIVATION_REASONS: readonly MonitorDeactivationReasonDef
       resolution:
         'Add credits. Monitors are reactivated automatically once the balance is positive again.',
     },
+    {
+      id: 'monthly_cap_exceeded',
+      owner: 'policy',
+      summary:
+        'Deactivated because the organization reached its monthly monitor spending cap.',
+      resolution:
+        'Raise or reset the monthly cap, then explicitly reactivate the monitors you want restored.',
+    },
+    {
+      id: 'billing_failure',
+      owner: 'policy',
+      summary:
+        'Deactivated because monitor event billing was denied.',
+      resolution:
+        'Resolve the billing restriction, then explicitly reactivate the monitors you want restored.',
+    },
     {
       id: 'entitlement_expired',
       owner: 'policy',

package/dist/bundling-sources/shared_libs/monitors/framework-managed-payload-fields.ts

@@ -0,0 +1,71 @@
+import type { ProviderMonitorCapabilityDefinition } from './provider-monitor-capability';
+
+// ---------------------------------------------------------------------------
+// Framework-managed monitor payload fields.
+//
+// When a monitor payload schema is DERIVED from the provider's OpenAPI request
+// body (see `deriveMonitorPayloadSchemaFromDeployAction`), some accepted request
+// fields are set by the Deepline monitor framework at deploy time, not by the
+// customer. Those fields must be stripped from the customer-facing payload
+// schema so `monitors deploy` neither asks for nor accepts them.
+//
+// This policy is PROVIDER-AGNOSTIC on purpose: the excluded set is computed from
+// the capability's own `runtime` config, so any future OpenAPI-backed monitor
+// provider inherits the exact same behavior with zero provider-specific code.
+// The only provider-specific input is the capability authoring file itself.
+//
+// Two framework-managed fields exist today:
+//
+//   - `webhook_url`: the per-monitor callback URL. The framework mints Deepline's
+//     callback URL and injects it into the create-radar request via the
+//     capability's `webhookRegistration.injectCallbackUrl` descriptor. This
+//     applies whenever the capability delivers inbound over a per-monitor webhook
+//     (`runtime.inbound === 'webhook'` with
+//     `webhookRegistrationStrategy === 'per_monitor_create_url'`). Account-level
+//     webhooks (`account_marker`) register no per-monitor URL, so `webhook_url`
+//     is not framework-managed for them.
+//
+//   - `custom_fields`: the correlation marker object. `mergeCustomFields`
+//     (provider-monitor-adapters.ts) stamps the Deepline monitor key + org
+//     correlation markers into `custom_fields` on every provider-native monitor
+//     deploy payload. It is always framework-managed for
+//     `provider_native_monitor` capabilities.
+//
+// The concrete field NAMES (`webhook_url`, `custom_fields`) are the request-body
+// keys the upstream OpenAPI uses for these two managed concepts. They are named
+// constants here, keyed to the framework concept, not to any one provider.
+// ---------------------------------------------------------------------------
+
+/** OpenAPI request field carrying the per-monitor callback URL. */
+export const FRAMEWORK_CALLBACK_URL_PAYLOAD_FIELD = 'webhook_url';
+
+/** OpenAPI request field carrying Deepline correlation markers. */
+export const FRAMEWORK_CORRELATION_MARKER_PAYLOAD_FIELD = 'custom_fields';
+
+/**
+ * The payload fields the monitor framework manages (injects) for a capability,
+ * derived entirely from its `runtime` config. Any request-body field in this set
+ * is excluded from a derived customer-facing payload schema.
+ */
+export function frameworkManagedPayloadFields(
+  runtime: ProviderMonitorCapabilityDefinition['runtime'],
+): Set<string> {
+  const managed = new Set<string>();
+
+  // Per-monitor webhook capabilities have the callback URL injected by the
+  // framework via the webhook-registration descriptor.
+  if (
+    runtime.inbound === 'webhook' &&
+    runtime.webhookRegistrationStrategy === 'per_monitor_create_url'
+  ) {
+    managed.add(FRAMEWORK_CALLBACK_URL_PAYLOAD_FIELD);
+  }
+
+  // Provider-native monitors always carry Deepline correlation markers in
+  // `custom_fields`, stamped by mergeCustomFields at deploy time.
+  if (runtime.kind === 'provider_native_monitor') {
+    managed.add(FRAMEWORK_CORRELATION_MARKER_PAYLOAD_FIELD);
+  }
+
+  return managed;
+}

package/dist/bundling-sources/shared_libs/monitors/generated/provider-monitor-callback-admission-targets.ts

@@ -0,0 +1,16 @@
+// Generated by scripts/generate-integration-artifacts.ts. Do not edit.
+// Convex-safe declaration of monitor capabilities that authenticate inbound
+// callbacks with an opaque callback token. Provider monitor declarations own
+// this contract; do not add provider allowlists to Convex migrations.
+export const GENERATED_PROVIDER_MONITOR_CALLBACK_TOKEN_ADMISSION_TARGETS = {
+  "deepline_native.company_radar": { provider: "deepline_native" },
+  "deepline_native.contact_radar": { provider: "deepline_native" },
+  "deepline_native.industry_radar": { provider: "deepline_native" },
+  "findymail.signal_monitor": { provider: "findymail" },
+  "heyreach.campaign_events": { provider: "heyreach" },
+  "rb2b.visitor_events": { provider: "rb2b" },
+  "smartlead.campaign_events": { provider: "smartlead" },
+  "vector.visitor_events": { provider: "vector" },
+} as const satisfies Record<string, { provider: string }>;
+
+export type GeneratedProviderMonitorCallbackTokenAdmissionTarget = keyof typeof GENERATED_PROVIDER_MONITOR_CALLBACK_TOKEN_ADMISSION_TARGETS;