stream-chat 9.43.1 → 9.44.0

package/src/signing.ts

@@ -1,7 +1,8 @@
 import jwt from 'jsonwebtoken';
 import crypto from 'crypto';
+import zlib from 'zlib';
 import { decodeBase64, encodeBase64 } from './base64';
-import type { UR } from './types';
+import type { Event, UR } from './types';
 
 /**
  * Creates the JWT token that can be used for a UserSession
@@ -84,19 +85,206 @@ export function DevToken(userId: string) {
 }
 
 /**
+ * Constant-time HMAC-SHA256 verification of `signature` against the
+ * digest of `body` using `secret` as the key. The signature is always
+ * computed over the **uncompressed** JSON bytes, so callers that
+ * decoded a gzipped or base64-wrapped payload must pass the inflated
+ * bytes here.
  *
- * @param {string | Buffer} body the signed message
- * @param {string} secret the shared secret used to generate the signature (Stream API secret)
- * @param {string} signature the signature to validate
- * @return {boolean}
+ * The legacy `client.verifyWebhook` helper wraps this function, so
+ * callers that have already migrated to `verifyAndParseWebhook`,
+ * `parseSqs`, or `parseSns` rarely need to invoke this
+ * directly.
  */
-export function CheckSignature(body: string | Buffer, secret: string, signature: string) {
+export function verifySignature(
+  body: string | Buffer,
+  signature: string,
+  secret: string,
+): boolean {
   const key = Buffer.from(secret, 'utf8');
   const hash = crypto.createHmac('sha256', key).update(body).digest('hex');
-
   try {
     return crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(signature));
   } catch {
     return false;
   }
 }
+
+/**
+ * @deprecated Use {@link verifySignature} - same logic, parameters
+ * reordered to match the cross-SDK contract
+ * (`verifySignature(body, signature, secret)`).
+ */
+export function CheckSignature(body: string | Buffer, secret: string, signature: string) {
+  return verifySignature(body, signature, secret);
+}
+
+/**
+ * Canonical failure-mode messages for {@link InvalidWebhookError}.
+ *
+ * Customers that prefer exact-match filtering (security logging, retry
+ * policy) over substring matches can compare `err.message` to these
+ * constants instead of pattern-matching free-form text.
+ */
+export const InvalidWebhookErrorMessages = {
+  signatureMismatch: 'signature mismatch',
+  invalidBase64: 'invalid base64 encoding',
+  gzipFailed: 'gzip decompression failed',
+  invalidJson: 'invalid JSON payload',
+} as const;
+
+/**
+ * Thrown by {@link verifyAndParseWebhook} when the supplied `x-signature` does not
+ * match the HMAC of the uncompressed payload, and by all webhook helpers (including
+ * {@link parseSqs} / {@link parseSns}) when a gzip / base64 / JSON envelope is malformed.
+ *
+ * The message identifies which failure mode fired. See
+ * {@link InvalidWebhookErrorMessages} for the canonical strings.
+ */
+export class InvalidWebhookError extends Error {
+  public name = 'InvalidWebhookError';
+
+  constructor(message: string = InvalidWebhookErrorMessages.signatureMismatch) {
+    super(message);
+  }
+}
+
+/**
+ * Returns `body` as a `Buffer`, gzip-decompressed when its first two
+ * bytes match the gzip magic (`1f 8b`, per RFC 1952). When the body is
+ * plain JSON (no compression, or middleware already decompressed), the
+ * bytes are returned unchanged.
+ *
+ * Magic-byte detection (rather than relying on a header) keeps the
+ * same handler correct when middleware - Express, Next.js, AWS Lambda
+ * - auto-decompresses the request before your code sees it.
+ */
+export function gunzipPayload(rawBody: string | Buffer): Buffer {
+  const GZIP_MAGIC = Buffer.from([0x1f, 0x8b]);
+
+  const body = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody);
+  if (body.length >= 2 && body.subarray(0, 2).equals(GZIP_MAGIC)) {
+    try {
+      return zlib.gunzipSync(body);
+    } catch {
+      throw new InvalidWebhookError(InvalidWebhookErrorMessages.gzipFailed);
+    }
+  }
+  return body;
+}
+
+/**
+ * Reverses the SQS firehose envelope: the message `Body` is
+ * base64-decoded, then the result is gzip-decompressed when it begins
+ * with the gzip magic. Returns the raw JSON `Buffer` Stream signed.
+ *
+ * SQS bodies are always base64-encoded so they remain valid UTF-8 over
+ * the queue. The same call works whether or not Stream is currently
+ * compressing payloads for this app.
+ */
+export function decodeSqsPayload(body: string): Buffer {
+  // Reject anything that isn't canonical base64 up front. Node's base64
+  // decoder is permissive (silently strips characters outside the
+  // alphabet, accepts both standard and URL-safe variants), so we have
+  // to be strict here to avoid silently corrupting the body before the
+  // signature check runs.
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(body) || body.length % 4 !== 0) {
+    throw new InvalidWebhookError(InvalidWebhookErrorMessages.invalidBase64);
+  }
+  const decoded = Buffer.from(body, 'base64');
+  if (decoded.toString('base64').length !== body.length) {
+    throw new InvalidWebhookError(InvalidWebhookErrorMessages.invalidBase64);
+  }
+  return gunzipPayload(decoded);
+}
+
+/**
+ * Reverses an SNS HTTP notification envelope. When `notificationBody`
+ * is a JSON envelope (`{"Type":"Notification","Message":"..."}`), the
+ * inner `Message` field is extracted and run through the SQS pipeline
+ * (base64-decode, then gzip-if-magic). When the input is not a JSON
+ * envelope it is treated as the already-extracted `Message` string,
+ * so call sites that pre-unwrap continue to work.
+ */
+export function decodeSnsPayload(notificationBody: string): Buffer {
+  const inner = extractSnsMessage(notificationBody);
+  return decodeSqsPayload(inner ?? notificationBody);
+}
+
+function extractSnsMessage(notificationBody: string): string | null {
+  const trimmed = notificationBody.replace(/^[\s\uFEFF]+/, '');
+  if (!trimmed.startsWith('{')) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+  if (
+    parsed === null ||
+    typeof parsed !== 'object' ||
+    Array.isArray(parsed) ||
+    typeof (parsed as { Message?: unknown }).Message !== 'string'
+  ) {
+    return null;
+  }
+  return (parsed as { Message: string }).Message;
+}
+
+/**
+ * Parse a JSON-encoded webhook event into a typed {@link Event}. New
+ * event types Stream introduces still parse successfully - the runtime
+ * shape is the JSON Stream sent and the `type` field stays preserved.
+ */
+export function parseEvent(payload: Buffer | string): Event {
+  const text = Buffer.isBuffer(payload) ? payload.toString('utf8') : payload;
+  try {
+    return JSON.parse(text) as Event;
+  } catch {
+    throw new InvalidWebhookError(InvalidWebhookErrorMessages.invalidJson);
+  }
+}
+
+function verifyAndParse(payload: Buffer, signature: string, secret: string): Event {
+  if (!verifySignature(payload, signature, secret)) {
+    throw new InvalidWebhookError(InvalidWebhookErrorMessages.signatureMismatch);
+  }
+  return parseEvent(payload);
+}
+
+/**
+ * Decompress (when gzipped), verify the HMAC `signature`, and return
+ * the parsed {@link Event}.
+ *
+ * @param rawBody Raw HTTP request body bytes Stream signed
+ * @param signature Value of the `X-Signature` header
+ * @param secret Your app's API secret
+ * @throws {InvalidWebhookError} When the signature does not match or
+ *   the gzip envelope is malformed.
+ */
+export function verifyAndParseWebhook(
+  rawBody: string | Buffer,
+  signature: string,
+  secret: string,
+): Event {
+  return verifyAndParse(gunzipPayload(rawBody), signature, secret);
+}
+
+/**
+ * Decode the SQS message `Body` (base64, then gzip-if-magic) and return
+ * the parsed {@link Event}. Stream does not attach an application-level HMAC
+ * to SQS deliveries — use {@link verifyAndParseWebhook} for HTTP webhooks.
+ */
+export function parseSqs(messageBody: string): Event {
+  return parseEvent(decodeSqsPayload(messageBody));
+}
+
+/**
+ * Decode an SNS notification (unwrap the JSON envelope when needed; same
+ * inner format as SQS). No application-level HMAC verification.
+ */
+export function parseSns(notificationBody: string): Event {
+  return parseEvent(decodeSnsPayload(notificationBody));
+}

package/src/types.ts

@@ -1060,13 +1060,29 @@ export type ChannelOptions = {
   user_id?: string;
   watch?: boolean;
   /**
-   * Name of a predefined filter to use instead of filter_conditions.
-   * When provided, filter_conditions and sort parameters are ignored.
+   * Name of a predefined filter to use instead of sending raw
+   * `filter_conditions`.
+   *
+   * The backend resolves the filter template by name and interpolates it using
+   * `filter_values`.
+   *
+   * A regular `sort` can still be passed to `queryChannels()`, but backend
+   * precedence rules apply:
+   *
+   * - if the predefined filter has its own stored sort template, that stored
+   *   sort takes precedence and the request `sort` is ignored
+   * - if the predefined filter does not define a sort template, the request
+   *   `sort` can still be used
    */
   predefined_filter?: string;
   /**
-   * Values to interpolate into the predefined filter template placeholders.
-   * Only used when predefined_filter is provided.
+   * Values used to interpolate placeholders inside the predefined filter's
+   * `filter` template.
+   *
+   * Example: a template value like `{{user_id}}` can be resolved with
+   * `{ user_id: 'alice' }`.
+   *
+   * Only used when `predefined_filter` is provided.
    */
   filter_values?: Record<string, unknown>;
   /**
@@ -4755,38 +4771,129 @@ export type UpdateChannelsBatchResponse = {
 export type PredefinedFilterOperation = 'QueryChannels';
 
 export type PredefinedFilterSortParam = {
+  /**
+   * Field name to sort by.
+   *
+   * This may be a literal field name such as `created_at`, or a placeholder
+   * template such as `{{sort_field}}` that will be interpolated server-side.
+   */
   field: string;
+  /**
+   * Sort direction. `1` means ascending and `-1` means descending.
+   *
+   * The backend defaults this to `1` when omitted.
+   */
   direction?: AscDesc;
+  /**
+   * Optional server-side hint describing how the sort field value should be
+   * interpreted.
+   *
+   * This is mainly relevant for predefined-filter sort templates and is not
+   * part of the regular `queryChannels()` sort shape. Omitting it uses the
+   * backend default string behavior. Known backend values include:
+   *
+   * - `number`: cast custom-field values to numeric before sorting
+   * - `boolean`: cast custom-field values to boolean before sorting
+   *
+   * Other values are backend-defined. In most cases this should be omitted
+   * unless you are sorting by a custom field whose stored JSON value is not
+   * string-like.
+   */
   type?: string;
 };
 
-export type PredefinedFilter = {
+/**
+ * Stored predefined filter definition as returned by the server.
+ *
+ * `F` represents the raw filter template shape. It defaults to a generic record
+ * because predefined filters are server-managed templates and may include
+ * placeholders or app-specific structures.
+ */
+export type PredefinedFilter<
+  F extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  /**
+   * Unique predefined filter name within the app.
+   */
   name: string;
+  /**
+   * Operation this predefined filter is valid for.
+   */
   operation: PredefinedFilterOperation;
-  filter: Record<string, unknown>;
+  /**
+   * Filter template stored on the server.
+   *
+   * This is not necessarily the fully interpolated runtime filter; placeholder
+   * values such as `{{user_id}}` may still be present.
+   */
+  filter: F;
+  /**
+   * Server creation timestamp in ISO-8601 format.
+   */
   created_at: string;
+  /**
+   * Server update timestamp in ISO-8601 format.
+   */
   updated_at: string;
+  /**
+   * Optional human-readable description.
+   */
   description?: string;
+  /**
+   * Optional sort template stored with the predefined filter.
+   */
   sort?: PredefinedFilterSortParam[];
+  /**
+   * Query identifier generated by the backend for the filter/sort pattern.
+   *
+   * The exact value is backend-generated and primarily useful for correlating
+   * predefined filters with query analysis / query performance data.
+   */
   query_id?: number;
 };
 
-export type CreatePredefinedFilterOptions = {
+export type CreatePredefinedFilterOptions<
+  F extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  /**
+   * Unique predefined filter name.
+   */
   name: string;
+  /**
+   * Operation this predefined filter will be used with.
+   */
   operation: PredefinedFilterOperation;
-  filter: Record<string, unknown>;
+  /**
+   * Filter template to store on the server.
+   */
+  filter: F;
+  /**
+   * Optional human-readable description.
+   */
   description?: string;
+  /**
+   * Optional sort template stored with the predefined filter.
+   */
   sort?: PredefinedFilterSortParam[];
 };
 
-export type UpdatePredefinedFilterOptions = Omit<CreatePredefinedFilterOptions, 'name'>;
+export type UpdatePredefinedFilterOptions<
+  F extends Record<string, unknown> = Record<string, unknown>,
+> = Omit<CreatePredefinedFilterOptions<F>, 'name'>;
 
-export type PredefinedFilterResponse = APIResponse & {
-  predefined_filter: PredefinedFilter;
+export type PredefinedFilterResponse<
+  F extends Record<string, unknown> = Record<string, unknown>,
+> = APIResponse & {
+  predefined_filter: PredefinedFilter<F>;
 };
 
-export type ListPredefinedFiltersResponse = APIResponse & {
-  predefined_filters: PredefinedFilter[];
+/**
+ * Paginated response returned when listing predefined filters.
+ */
+export type ListPredefinedFiltersResponse<
+  F extends Record<string, unknown> = Record<string, unknown>,
+> = APIResponse & {
+  predefined_filters: PredefinedFilter<F>[];
   next?: string;
   prev?: string;
 };
@@ -4795,9 +4902,20 @@ export type ListPredefinedFiltersResponse = APIResponse & {
  * Contains the interpolated filter and sort from a predefined filter.
  * This is returned in the QueryChannels response when using a predefined filter.
  */
-export type ParsedPredefinedFilterResponse = {
+export type ParsedPredefinedFilterResponse<
+  F extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  /**
+   * Name of the predefined filter that was resolved.
+   */
   name: string;
-  filter: Record<string, unknown>;
+  /**
+   * Fully interpolated filter that the backend executed.
+   */
+  filter: F;
+  /**
+   * Fully interpolated sort parameters resolved from the predefined filter.
+   */
   sort?: PredefinedFilterSortParam[];
 };
 

package/src/utils.ts

@@ -479,7 +479,7 @@ export const deleteUserMessages = ({
           : (toDeletedMessage({ message, hardDelete, deletedAt }) as LocalMessage);
     }
 
-    if (message.quoted_message?.user?.id === user.id) {
+    if (messages[i].quoted_message && message.quoted_message?.user?.id === user.id) {
       messages[i].quoted_message =
         message.quoted_message.type === 'deleted'
           ? message.quoted_message