Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

5.0 KB
Raw Blame
import type { IngressResponseContract } from '../../core/plugins/plugin.interfaces';

export interface AckRenderCtx {
  rawBody: string;
  timestamp: string; // epoch seconds, as a string for substitution
  id: string; // delivery id
}

export type AckResult = { status: number; body?: string; headers?: Record<string, string> };

/**
 * Renders the synchronous ack for an inbound route, computed entirely host-side. `spec` is the route's
 * `response.ack` (undefined → the default 202 'accepted'). The body may interpolate `{rawBody}`,
 * `{timestamp}`, `{id}` from the VERIFIED request. Substitutes only original template tokens, with
 * inserted values kept literal. Total: never throws; unexpected input falls back to the declared literal.
 */
export function renderAck(spec: IngressResponseContract['ack'] | undefined, ctx: AckRenderCtx): AckResult {
  if (!spec) return { status: 202, body: 'accepted' };
  const result: AckResult = { status: typeof spec.status === 'number' ? spec.status : 202 };
  // validateIngressManifest rejects a non-string body, a non-string header value and a non-integer
  // status, so these guards are the second line rather than the first: this function is documented
  // as total, and it is also reachable from a built-in manifest and from a test fixture that never
  // went through the loader. On a shape the loader would have refused, fall back rather than throw.
  if (typeof spec.body === 'string') {
    result.body = substitute(spec.body, ctx);
  }
  if (spec.headers && typeof spec.headers === 'object') {
    result.headers = Object.fromEntries(Object.entries(spec.headers).filter(([, v]) => typeof v === 'string'));
  }
  return result;
}

/**
 * Header names a route's declared ack may never write. Three groups, all plugin-authored and landing
 * on the gateway's own origin, so none of them may undo what the app sets for every response:
 *
 *  - `content-type`, decided by {@link ackContentType} immediately after;
 *  - the framing and encoding headers, which decide how the response is delimited and decoded. The
 *    host frames the ack itself and never compresses it, so a declared `Content-Encoding: gzip`
 *    describes bytes the ack does not carry and the provider's client fails to decode it, while a
 *    declared `Transfer-Encoding` makes Node re-frame a body it has already given a length, and a
 *    declared `Trailer` makes it refuse to write the response at all. `content-length` is inert,
 *    Express overwrites it, and is fenced with the rest rather than reasoned about separately;
 *  - the browser-facing protections that make a reflected ack body safe in the first place.
 *
 * Anything else a manifest declares still goes out verbatim.
 */
const RESERVED_ACK_HEADERS: ReadonlySet<string> = new Set([
  'content-type',
  'content-length',
  'transfer-encoding',
  'content-encoding',
  'trailer',
  'content-security-policy',
  'x-content-type-options',
  'x-frame-options',
  'strict-transport-security',
  'referrer-policy',
  'set-cookie',
  'access-control-allow-origin',
  'access-control-allow-credentials',
]);

/** The subset of a declared ack's headers that may reach the wire. Total. */
export function safeAckHeaders(headers: Record<string, string> | undefined): Record<string, string> {
  if (!headers) return {};
  return Object.fromEntries(
    Object.entries(headers).filter(
      ([name, value]) => typeof value === 'string' && !RESERVED_ACK_HEADERS.has(name.toLowerCase()),
    ),
  );
}

/**
 * Media types a route's declared ack Content-Type may actually put on the wire. Express types a bare
 * send() as text/html, which would make a reflected body (a GET challenge echo, an ack template
 * interpolating {rawBody}) XSS material on this origin. A declared type is therefore honored only when
 * a browser will not execute it, and anything else falls back to text/plain. `noSniff` (configure-app)
 * stops a browser re-sniffing an honored type as HTML. Providers that validate the ack need
 * application/json (Supabase Auth rejects a 200 or 202 that is not), and nothing needs more than that.
 */
const HONORED_ACK_MEDIA_TYPES = new Set(['application/json', 'text/plain']);

/**
 * The Content-Type to emit for an ack: the declared media type when allowlisted, else text/plain. Total.
 * Only the bare media type is returned. Express rewrites the charset of a string body to utf-8 anyway,
 * and a declared parameter list it cannot parse (`application/json;`) makes send() throw, which
 * answered 500 to a delivery that had already been persisted.
 */
export function ackContentType(headers: Record<string, string> | undefined): string {
  const declared = headers
    ? Object.entries(headers).find(([name]) => name.toLowerCase() === 'content-type')?.[1]
    : undefined;
  if (typeof declared !== 'string' || !declared) return 'text/plain';
  const mediaType = declared.split(';', 1)[0].trim().toLowerCase();
  return HONORED_ACK_MEDIA_TYPES.has(mediaType) ? mediaType : 'text/plain';
}

function substitute(template: string, ctx: AckRenderCtx): string {
  return template.replace(/\{(rawBody|timestamp|id)\}/g, (_, key: keyof AckRenderCtx) => ctx[key]);
}