@ftisindia/create-app 0.1.6 → 0.2.0

package/template/src/modules/forms/application/services/handlers/webhook-delivery.transport.ts

@@ -0,0 +1,319 @@
+import { lookup as dnsLookup } from 'node:dns/promises';
+import * as http from 'node:http';
+import * as https from 'node:https';
+import { isIP } from 'node:net';
+
+interface LookupAddress {
+  address: string;
+  family: 4 | 6;
+}
+
+interface WebhookDeliveryOptions {
+  headers: Record<string, string>;
+  body: string;
+  timeoutMs: number;
+  lookup?: typeof dnsLookup;
+}
+
+interface WebhookDeliveryResponse {
+  status: number;
+  statusText: string;
+}
+
+const DEFAULT_HTTPS_PORT = 443;
+const DEFAULT_HTTP_PORT = 80;
+
+export async function deliverWebhookRequest(
+  rawUrl: string,
+  options: WebhookDeliveryOptions,
+): Promise<WebhookDeliveryResponse> {
+  const url = parseWebhookUrl(rawUrl);
+  const endpoint = await resolveWebhookEndpoint(url, options.lookup ?? dnsLookup);
+
+  return sendPinnedRequest(url, endpoint, options);
+}
+
+function parseWebhookUrl(rawUrl: string): URL {
+  let url: URL;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new Error('Webhook URL is invalid.');
+  }
+
+  if (url.username || url.password) {
+    throw new Error('Webhook URL must not include credentials.');
+  }
+
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new Error('Webhook URL must use http or https.');
+  }
+
+  return url;
+}
+
+async function resolveWebhookEndpoint(url: URL, lookup: typeof dnsLookup): Promise<LookupAddress> {
+  const hostname = normalizeHostname(url.hostname);
+  const literalFamily = isIP(hostname);
+  const addresses: LookupAddress[] =
+    literalFamily === 0
+      ? (await lookup(hostname, { all: true, verbatim: false })).map((entry) => ({
+          address: entry.address,
+          family: entry.family === 6 ? 6 : 4,
+        }))
+      : [{ address: hostname, family: literalFamily as 4 | 6 }];
+
+  if (addresses.length === 0) {
+    throw new Error('Webhook hostname did not resolve to an address.');
+  }
+
+  const normalized = addresses.map((entry) => ({
+    address: normalizeHostname(entry.address),
+    family: entry.family,
+  }));
+  const allowLocalNetwork = process.env.NODE_ENV !== 'production';
+  const unsafe = normalized.filter((entry) => isReservedAddress(entry.address));
+
+  if (!allowLocalNetwork && unsafe.length > 0) {
+    throw new Error(
+      `Webhook destination resolves to a private or reserved address (${unsafe[0]!.address}).`,
+    );
+  }
+
+  if (url.protocol === 'http:') {
+    if (!allowLocalNetwork) {
+      throw new Error('Webhook http destinations are allowed only outside production.');
+    }
+    if (normalized.some((entry) => !isLoopbackAddress(entry.address))) {
+      throw new Error('Webhook http destinations must resolve only to loopback addresses.');
+    }
+  }
+
+  return normalized[0]!;
+}
+
+function sendPinnedRequest(
+  url: URL,
+  endpoint: LookupAddress,
+  options: WebhookDeliveryOptions,
+): Promise<WebhookDeliveryResponse> {
+  const transport = url.protocol === 'https:' ? https : http;
+  const requestOptions: https.RequestOptions = {
+    protocol: url.protocol,
+    hostname: endpoint.address,
+    family: endpoint.family,
+    port: url.port ? Number(url.port) : defaultPort(url),
+    method: 'POST',
+    path: `${url.pathname}${url.search}`,
+    headers: { ...options.headers, host: url.host },
+    timeout: options.timeoutMs,
+  };
+
+  const servername = normalizeHostname(url.hostname);
+  if (url.protocol === 'https:' && isIP(servername) === 0) {
+    requestOptions.servername = servername;
+  }
+
+  return new Promise((resolve, reject) => {
+    const req = transport.request(requestOptions, (res) => {
+      const status = res.statusCode ?? 0;
+      const statusText = res.statusMessage ?? '';
+      res.resume();
+      res.once('end', () => resolve({ status, statusText }));
+    });
+
+    req.once('timeout', () => {
+      req.destroy(new Error('Webhook request timed out.'));
+    });
+    req.once('error', reject);
+    req.end(options.body);
+  });
+}
+
+function defaultPort(url: URL): number {
+  return url.protocol === 'https:' ? DEFAULT_HTTPS_PORT : DEFAULT_HTTP_PORT;
+}
+
+function normalizeHostname(hostname: string): string {
+  return hostname.replace(/^\[/u, '').replace(/\]$/u, '').toLowerCase();
+}
+
+function isLoopbackAddress(address: string): boolean {
+  const family = isIP(address);
+  if (family === 4) {
+    const value = ipv4ToNumber(address);
+    return value !== null && inIpv4Range(value, '127.0.0.0', 8);
+  }
+
+  if (family === 6) {
+    const value = ipv6ToBigInt(address);
+    return value === 1n;
+  }
+
+  return false;
+}
+
+function isReservedAddress(address: string): boolean {
+  const family = isIP(address);
+  if (family === 4) {
+    const value = ipv4ToNumber(address);
+    if (value === null) {
+      return true;
+    }
+
+    return IPV4_RESERVED_RANGES.some(([base, prefix]) => inIpv4Range(value, base, prefix));
+  }
+
+  if (family === 6) {
+    return isReservedIpv6(address);
+  }
+
+  return true;
+}
+
+const IPV4_RESERVED_RANGES: Array<[base: string, prefix: number]> = [
+  ['0.0.0.0', 8],
+  ['10.0.0.0', 8],
+  ['100.64.0.0', 10],
+  ['127.0.0.0', 8],
+  ['169.254.0.0', 16],
+  ['172.16.0.0', 12],
+  ['192.0.0.0', 24],
+  ['192.0.2.0', 24],
+  ['192.168.0.0', 16],
+  ['198.18.0.0', 15],
+  ['198.51.100.0', 24],
+  ['203.0.113.0', 24],
+  ['224.0.0.0', 4],
+  ['240.0.0.0', 4],
+];
+
+function ipv4ToNumber(address: string): number | null {
+  const parts = address.split('.');
+  if (parts.length !== 4) {
+    return null;
+  }
+
+  let value = 0;
+  for (const part of parts) {
+    if (!/^\d+$/u.test(part)) {
+      return null;
+    }
+    const byte = Number(part);
+    if (byte < 0 || byte > 255) {
+      return null;
+    }
+    value = (value << 8) + byte;
+  }
+
+  return value >>> 0;
+}
+
+function inIpv4Range(value: number, base: string, prefix: number): boolean {
+  const baseValue = ipv4ToNumber(base);
+  if (baseValue === null) {
+    return false;
+  }
+
+  const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+  return (value & mask) === (baseValue & mask);
+}
+
+function isReservedIpv6(address: string): boolean {
+  const value = ipv6ToBigInt(address);
+  if (value === null) {
+    return true;
+  }
+
+  const mappedIpv4 = ipv4MappedAddress(value);
+  if (mappedIpv4 !== null) {
+    return IPV4_RESERVED_RANGES.some(([base, prefix]) => inIpv4Range(mappedIpv4, base, prefix));
+  }
+
+  return IPV6_RESERVED_RANGES.some(([base, prefix]) => inIpv6Range(value, base, prefix));
+}
+
+const IPV6_RESERVED_RANGES: Array<[base: string, prefix: number]> = [
+  ['::', 128],
+  ['::1', 128],
+  ['::', 8],
+  ['64:ff9b::', 96],
+  ['100::', 64],
+  ['2001:2::', 48],
+  ['2001:10::', 28],
+  ['2001:db8::', 32],
+  ['2002::', 16],
+  ['fc00::', 7],
+  ['fe80::', 10],
+  ['ff00::', 8],
+];
+
+function ipv4MappedAddress(value: bigint): number | null {
+  const mappedPrefix = 0xffffn << 32n;
+  const prefix = value >> 32n;
+  if (prefix !== mappedPrefix >> 32n) {
+    return null;
+  }
+
+  return Number(value & 0xffffffffn);
+}
+
+function inIpv6Range(value: bigint, base: string, prefix: number): boolean {
+  const baseValue = ipv6ToBigInt(base);
+  if (baseValue === null) {
+    return false;
+  }
+
+  const mask = prefix === 0 ? 0n : ((1n << BigInt(prefix)) - 1n) << BigInt(128 - prefix);
+  return (value & mask) === (baseValue & mask);
+}
+
+function ipv6ToBigInt(address: string): bigint | null {
+  let normalized = address.toLowerCase();
+  const zoneIndex = normalized.indexOf('%');
+  if (zoneIndex !== -1) {
+    normalized = normalized.slice(0, zoneIndex);
+  }
+
+  if (normalized.includes('.')) {
+    const lastColon = normalized.lastIndexOf(':');
+    const embedded = ipv4ToNumber(normalized.slice(lastColon + 1));
+    if (lastColon === -1 || embedded === null) {
+      return null;
+    }
+    const high = ((embedded >>> 16) & 0xffff).toString(16);
+    const low = (embedded & 0xffff).toString(16);
+    normalized = `${normalized.slice(0, lastColon)}:${high}:${low}`;
+  }
+
+  const halves = normalized.split('::');
+  if (halves.length > 2) {
+    return null;
+  }
+
+  const head = splitIpv6Half(halves[0] ?? '');
+  const tail = splitIpv6Half(halves[1] ?? '');
+  const missing = halves.length === 2 ? 8 - head.length - tail.length : 0;
+  if (missing < 0 || (halves.length === 1 && head.length !== 8)) {
+    return null;
+  }
+
+  const parts = [...head, ...Array.from({ length: missing }, () => '0'), ...tail];
+  if (parts.length !== 8) {
+    return null;
+  }
+
+  let value = 0n;
+  for (const part of parts) {
+    if (!/^[\da-f]{1,4}$/u.test(part)) {
+      return null;
+    }
+    value = (value << 16n) + BigInt(Number.parseInt(part, 16));
+  }
+
+  return value;
+}
+
+function splitIpv6Half(half: string): string[] {
+  return half.length === 0 ? [] : half.split(':');
+}

package/template/src/modules/forms/application/services/handlers/webhook.handler.ts

@@ -1,41 +1,89 @@
 import { createHmac } from 'node:crypto';
 import { Injectable } from '@nestjs/common';
+import type { Prisma } from '@prisma/client';
 import type { OutboxJobHandler, OutboxJobRecord } from '@ftisindia/form-builder';
+import { PrismaService } from '../../../../../database/prisma/prisma.service';
+import { deliverWebhookRequest } from './webhook-delivery.transport';
 
 /**
- * Generic webhook delivery. Payload contract: { url: string, body?: object,
- * secret?: string }. When a secret is set, the request carries
- * `x-forms-signature: sha256=<hmac-sha256(rawBody)>` so receivers can verify
- * authenticity. Non-2xx responses and timeouts throw, which the dispatcher
- * turns into a retry with backoff (then parks as FAILED after max attempts).
+ * Generic webhook delivery. Payload contract: { url: string, rawBody: string,
+ * signature?: string }. The engine computes the optional signature before
+ * enqueueing so the shared secret is not copied into the outbox payload.
+ * Non-2xx responses and timeouts throw, which the dispatcher turns into a
+ * retry with backoff (then parks as FAILED after max attempts).
  */
 @Injectable()
 export class WebhookOutboxHandler implements OutboxJobHandler {
   readonly type = 'webhook';
 
+  constructor(private readonly prisma: PrismaService) {}
+
   async handle(job: OutboxJobRecord): Promise<void> {
-    const { url, body, secret } = job.payload as {
+    const { url, rawBody, body, signature, secret } = job.payload as {
       url?: unknown;
+      rawBody?: unknown;
       body?: unknown;
+      signature?: unknown;
+      /** Backward-compatible support for jobs enqueued before secrets moved out of payloads. */
       secret?: unknown;
     };
     if (typeof url !== 'string' || url.length === 0) {
       throw new Error('Webhook job payload requires a "url" string.');
     }
-    const rawBody = JSON.stringify(body ?? {});
-    const headers: Record<string, string> = { 'content-type': 'application/json' };
-    if (typeof secret === 'string' && secret.length > 0) {
-      headers['x-forms-signature'] =
-        'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
+    const requestBody = typeof rawBody === 'string' ? rawBody : JSON.stringify(body ?? {});
+    const headers: Record<string, string> = {
+      'content-type': 'application/json',
+    };
+    if (job.idempotencyKey) {
+      headers['x-forms-idempotency-key'] = job.idempotencyKey;
+    }
+    let resolvedSignature: string | undefined;
+    if (typeof signature === 'string' && signature.length > 0) {
+      resolvedSignature = signature;
+    } else if (typeof secret === 'string' && secret.length > 0) {
+      resolvedSignature =
+        'sha256=' + createHmac('sha256', secret).update(requestBody).digest('hex');
+      await this.sanitizeLegacyPayload(job, url, requestBody, resolvedSignature);
     }
-    const response = await fetch(url, {
-      method: 'POST',
+    if (resolvedSignature) {
+      headers['x-forms-signature'] = resolvedSignature;
+    }
+    const response = await deliverWebhookRequest(url, {
       headers,
-      body: rawBody,
-      signal: AbortSignal.timeout(10_000),
+      body: requestBody,
+      timeoutMs: 10_000,
     });
-    if (!response.ok) {
+    if (response.status >= 300 && response.status < 400) {
+      throw new Error(`Webhook redirects are not allowed (status ${response.status}).`);
+    }
+    if (response.status < 200 || response.status >= 300) {
       throw new Error(`Webhook endpoint responded with status ${response.status}.`);
     }
   }
+
+  private async sanitizeLegacyPayload(
+    job: OutboxJobRecord,
+    url: string,
+    rawBody: string,
+    signature: string,
+  ): Promise<void> {
+    const claimedBy = typeof job.claimedBy === 'string' ? job.claimedBy : '';
+    if (!claimedBy) {
+      throw new Error('Webhook job is missing a claim token.');
+    }
+
+    const result = await this.prisma.formOutboxJob.updateMany({
+      where: { id: job.id, status: 'PROCESSING', claimedBy },
+      data: {
+        payload: {
+          url,
+          rawBody,
+          signature,
+        } satisfies Prisma.InputJsonValue,
+      },
+    });
+    if (result.count !== 1) {
+      throw new Error('Webhook job lease was lost before legacy payload cleanup.');
+    }
+  }
 }

package/template/src/modules/forms/application/services/outbox-dispatcher.service.ts

@@ -7,6 +7,8 @@ import { AuditService } from '../../../audit/application/services/audit.service'
 import { RequestContextService } from '../../../request-context/application/services/request-context.service';
 import { PrismaOutboxStore } from '../../infrastructure/stores/prisma-outbox.store';
 
+const DEFAULT_PROCESSING_HEARTBEAT_MS = 60_000;
+
 /**
  * In-process outbox poller (ecosystem guide §3/§8.3). Every claimed job runs
  * inside requestContext.run({ source: 'worker', jobId, orgId, userId,
@@ -15,9 +17,9 @@ import { PrismaOutboxStore } from '../../infrastructure/stores/prisma-outbox.sto
  * originating request. Successful delivery writes an audit row.
  *
  * Deterministic in tests: FORMS_OUTBOX_ENABLED=false disables the timer and
- * runOnce() drives a single cycle by hand. Single-instance by design — a
- * multi-node deployment should swap the store's claim for SKIP LOCKED or a
- * real queue (BullMQ) without touching the engine.
+ * runOnce() drives a single cycle by hand. The default Prisma store claims
+ * jobs with row-level locks; apps that outgrow the starter poller can swap
+ * this boundary for a queue-backed implementation without touching handlers.
  */
 @Injectable()
 export class OutboxDispatcherService implements OnApplicationBootstrap, OnModuleDestroy {
@@ -53,6 +55,8 @@ export class OutboxDispatcherService implements OnApplicationBootstrap, OnModule
   }
 
   async runOnce(): Promise<DispatchCycleResult> {
+    const heartbeatMs =
+      this.config.get<number>('forms.outboxHeartbeatMs') ?? DEFAULT_PROCESSING_HEARTBEAT_MS;
     return runDispatchCycle(this.store, this.handlers, {
       wrapJob: (job, run) =>
         this.requestContext.run(
@@ -64,25 +68,43 @@ export class OutboxDispatcherService implements OnApplicationBootstrap, OnModule
             requestId: job.originRequestId ?? undefined,
           },
           async () => {
-            const outcome = await run();
-            if (outcome === 'done') {
-              try {
-                await this.audit.write(this.prisma, {
-                  orgId: job.orgId ?? null,
-                  actorUserId: job.actorUserId ?? null,
-                  action: 'forms.outbox.delivered',
-                  targetType: 'FormOutboxJob',
-                  targetId: job.id,
-                  metadata: { type: job.type, attempts: job.attempts + 1 },
-                });
-              } catch (error) {
+            const claimedBy = typeof job.claimedBy === 'string' ? job.claimedBy : '';
+            const heartbeat = setInterval(() => {
+              if (!claimedBy) {
+                return;
+              }
+              void this.store.touchProcessing(job.id, claimedBy).catch((error: unknown) => {
                 this.logger.warn(
-                  `Outbox delivery audit failed for job ${job.id}.`,
+                  `Outbox heartbeat failed for job ${job.id}.`,
                   error instanceof Error ? error.stack : String(error),
                 );
+              });
+            }, heartbeatMs);
+            heartbeat.unref?.();
+
+            try {
+              const outcome = await run();
+              if (outcome === 'done') {
+                try {
+                  await this.audit.write(this.prisma, {
+                    orgId: job.orgId ?? null,
+                    actorUserId: job.actorUserId ?? null,
+                    action: 'forms.outbox.delivered',
+                    targetType: 'FormOutboxJob',
+                    targetId: job.id,
+                    metadata: { type: job.type, attempts: job.attempts + 1 },
+                  });
+                } catch (error) {
+                  this.logger.warn(
+                    `Outbox delivery audit failed for job ${job.id}.`,
+                    error instanceof Error ? error.stack : String(error),
+                  );
+                }
               }
+              return outcome;
+            } finally {
+              clearInterval(heartbeat);
             }
-            return outcome;
           },
         ),
     });
@@ -97,7 +119,7 @@ export class OutboxDispatcherService implements OnApplicationBootstrap, OnModule
       const result = await this.runOnce();
       if (result.claimed > 0) {
         this.logger.log(
-          `Outbox cycle: claimed ${result.claimed}, done ${result.done}, retried ${result.retried}, failed ${result.failed}.`,
+          `Outbox cycle: claimed ${result.claimed}, done ${result.done}, retried ${result.retried}, failed ${result.failed}, stale ${result.stale}.`,
         );
       }
     } catch (error) {

package/template/src/modules/forms/forms.module.ts

@@ -43,6 +43,7 @@ import { FormsFilesController } from './presentation/forms-files.controller';
 import { FormsSubmissionsController } from './presentation/forms-submissions.controller';
 import { FormsUploadInterceptor } from './presentation/forms-upload.interceptor';
 import { PublicFormsController } from './presentation/public-forms.controller';
+import { FORMS_CAPTCHA_VERIFIER } from './forms.tokens';
 
 /**
  * The forms glue module — the ONLY place that binds the framework-free
@@ -75,6 +76,7 @@ import { PublicFormsController } from './presentation/public-forms.controller';
     PrismaFileStore,
     PrismaActionLogStore,
     FormsSettingsReader,
+    { provide: FORMS_CAPTCHA_VERIFIER, useValue: undefined },
     // Engine registries — singletons; core field types registered up front.
     {
       provide: FieldTypeRegistry,