@framers/agentos 0.10.26 → 0.10.27

package/dist/io/channels/telephony/providers/plivo.d.ts

@@ -22,17 +22,20 @@
  *
  * ## Webhook verification: HMAC-SHA256 + nonce (v3 scheme)
  *
- * Plivo's v3 webhook signature scheme:
- *
- * 1. Plivo generates a random `nonce` and includes it in the
- *    `X-Plivo-Signature-V3-Nonce` header.
- * 2. The signed data is: `{fullRequestURL}{nonce}` (concatenated, no separator).
- * 3. Compute `HMAC-SHA256(authToken, signedData)`.
- * 4. Base64-encode the HMAC digest.
- * 5. Compare the result with the `X-Plivo-Signature-V3` header.
- *
- * Note: Unlike Twilio's scheme, Plivo does NOT include the POST body in the
- * signed data -- only the URL and nonce. The nonce prevents replay attacks.
+ * Plivo's v3 signature covers the method, the URL, its query and the POST
+ * fields (see {@link computePlivoV3Signature}). The nonce arrives in
+ * `X-Plivo-Signature-V3-Nonce` and the signature in `X-Plivo-Signature-V3`
+ * (or `X-Plivo-Signature-Ma-V3`, signed with the main account's token), which
+ * may list several signatures separated by commas.
+ *
+ * Plivo's SDKs build the signed text differently in three places:
+ * plivo-python (`plivo/utils/signature_v3.py`) decodes the query one
+ * character per byte, writes JSON values with Python's `str()` and sorts by
+ * code point; plivo-node decodes the query as UTF-8, writes JSON values with
+ * `String()` and sorts by UTF-16 code unit. Plivo does not document which its
+ * servers match, so a signature over either text is accepted (see
+ * {@link PlivoCanonicalStyle}). For ASCII callbacks with string fields the two
+ * texts are the same.
  *
  * ## DTMF via `<GetDigits>` XML pattern
  *
@@ -78,6 +81,63 @@ export interface PlivoVoiceProviderConfig {
      */
     fetchImpl?: typeof fetch;
 }
+/** A webhook field's value: one string, a repeated field's values, or a nested object. */
+export type PlivoParamValue = string | string[] | PlivoParams;
+/** Webhook fields by name, as {@link computePlivoV3Signature} signs them. */
+export interface PlivoParams {
+    [key: string]: PlivoParamValue;
+}
+/**
+ * Which SDK's signed text to build.
+ *
+ * - `'python'`: as plivo-python 4.63 builds it on Python 3.12 and later. The
+ *   query is decoded one character per byte (`caf%C3%A9` reads `café`), JSON
+ *   values are written with `str()` (`True`, `None`, `1.0`, `1e-07`) and keys
+ *   and repeated values are sorted by code point, as `sorted()` does.
+ * - `'js'`: JavaScript's text, which is plivo-node's for flat bodies of
+ *   strings, numbers and booleans. The query is decoded as UTF-8, JSON values
+ *   are written with `String()` (`true`, `null`, `1`, `1e-7`) and sorting is by
+ *   UTF-16 code unit, JavaScript's default. plivo-node throws on a JSON null
+ *   and writes a nested object as `[object Object]`; this style writes `null`
+ *   and signs nested fields like plivo-python, so no field goes unsigned.
+ */
+export type PlivoCanonicalStyle = 'python' | 'js';
+/**
+ * Plivo's v3 webhook signature, computed as plivo-python
+ * (`plivo/utils/signature_v3.py`) computes it by default: base64 of
+ * HMAC-SHA256 with the auth token over `{base}.{nonce}`.
+ *
+ * - GET: `base` is the URL without its query, then `?` and the query as
+ *   sorted `key=value` pairs when there is one.
+ * - POST: `base` is the URL without its query; when the body has fields, `?`,
+ *   the sorted query (and `.` when there is a query), then every field as
+ *   `key` + `value` sorted by key. With no fields it is the GET form.
+ *
+ * @param method - The request method (GET or POST).
+ * @param url - The full URL Plivo requested.
+ * @param nonce - The `X-Plivo-Signature-V3-Nonce` header.
+ * @param authToken - The (sub)account auth token.
+ * @param params - The POST fields as text; ignored for GET. A JSON body's
+ *   values must already be written in `style` (as the provider's verifier
+ *   writes them).
+ * @param style - Which SDK's text to build: how the query is decoded and how
+ *   keys and repeated values are sorted (see {@link PlivoCanonicalStyle}).
+ * @returns The base64 signature.
+ * @throws RangeError when the fields sign to more than
+ *   {@link MAX_PLIVO_SIGNED_FIELDS_LENGTH} characters.
+ */
+export declare function computePlivoV3Signature(method: string, url: string, nonce: string, authToken: string, params?: PlivoParams, style?: PlivoCanonicalStyle): string;
+/**
+ * A finite float as Python's repr writes it: the shortest digits that read
+ * back to the same value (the digits JavaScript's toExponential() gives), in
+ * fixed notation with at least one fractional digit when the decimal point
+ * sits from 4 places left of the first digit up to 16 places right of it,
+ * otherwise as `d.ddde±XX`.
+ *
+ * @param value - The number.
+ * @returns Python's repr of the float.
+ */
+export declare function pythonFloatRepr(value: number): string;
 /**
  * Plivo voice call provider.
  *
@@ -110,25 +170,22 @@ export declare class PlivoVoiceProvider implements IVoiceCallProvider {
     /**
      * Verify an incoming Plivo webhook request using HMAC-SHA256 (v3 scheme).
      *
-     * ## Algorithm (step by step)
-     *
-     * 1. Extract the `X-Plivo-Signature-V3-Nonce` and `X-Plivo-Signature-V3` headers.
-     * 2. Build the signed data string: `{fullRequestURL}{nonce}`.
-     *    Note: the POST body is NOT included in the signed data (unlike Twilio).
-     * 3. Compute `HMAC-SHA256(authToken, signedData)`.
-     * 4. Base64-encode the digest.
-     * 5. Compare with the `X-Plivo-Signature-V3` header.
+     * Computes {@link computePlivoV3Signature} over the request's method, URL
+     * and fields (read by {@link readPlivoRequest}, as `parseWebhookEvent`
+     * reads them) in both SDKs' texts (see {@link PlivoCanonicalStyle}) and
+     * compares each in constant time with every signature listed in
+     * `X-Plivo-Signature-V3` and `X-Plivo-Signature-Ma-V3`.
      *
      * @param ctx - Raw webhook request context.
-     * @returns Verification result with `valid: true` if the signature matches.
+     * @returns Verification result with `valid: true` if a signature matches.
      */
     verifyWebhook(ctx: WebhookContext): WebhookVerificationResult;
     /**
-     * Parse a Plivo webhook body into normalized {@link NormalizedCallEvent}s.
+     * Parse a Plivo webhook into normalized {@link NormalizedCallEvent}s.
      *
-     * Plivo sends most webhooks with URL-encoded bodies, but some callbacks
-     * may arrive as JSON. This parser handles both formats by inspecting
-     * whether the body starts with `{` (JSON) or not (form-encoded).
+     * Fields come from {@link readPlivoRequest} and {@link plivoEventFields},
+     * as the signature check reads them: a GET callback's query, otherwise the
+     * URL-encoded or JSON body.
      *
      * Plivo uses two naming conventions for the same fields:
      * - PascalCase (`CallUUID`, `CallStatus`, `Digits`) in URL callbacks.

package/dist/io/channels/telephony/providers/plivo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plivo.d.ts","sourceRoot":"","sources":["../../../../../src/io/channels/telephony/providers/plivo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAIH,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACb,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EACV,cAAc,EACd,yBAAyB,EACzB,kBAAkB,EAEnB,MAAM,aAAa,CAAC;AAMrB;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAMD;;;;;;;;;;;;;GAaG;AACH,qBAAa,kBAAmB,YAAW,kBAAkB;IAC3D,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAU;IAEjC,wCAAwC;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAElD,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IAErC;;OAEG;gBACS,MAAM,EAAE,wBAAwB;IAW5C;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,yBAAyB;IAoB7D;;;;;;;;;;;;;;OAcG;IACH,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,kBAAkB;IAkE1D;;;;;;;;;OASG;IACG,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0BzE;;;;;;;;OAQG;IACG,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvD;;;;;;;OAOG;IACG,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAgBlD"}
+{"version":3,"file":"plivo.d.ts","sourceRoot":"","sources":["../../../../../src/io/channels/telephony/providers/plivo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AAIH,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACb,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EACV,cAAc,EACd,yBAAyB,EACzB,kBAAkB,EAEnB,MAAM,aAAa,CAAC;AAMrB;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAMD,0FAA0F;AAC1F,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,WAAW,CAAC;AAE9D,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAAC;CAChC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,IAAI,CAAC;AAgLlD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,WAAgB,EACxB,KAAK,GAAE,mBAA8B,GACpC,MAAM,CAWR;AAqSD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiBrD;AAsDD;;;;;;;;;;;;;GAaG;AACH,qBAAa,kBAAmB,YAAW,kBAAkB;IAC3D,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAU;IAEjC,wCAAwC;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAElD,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IAErC;;OAEG;gBACS,MAAM,EAAE,wBAAwB;IAW5C;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,yBAAyB;IA4C7D;;;;;;;;;;;;;;OAcG;IACH,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,kBAAkB;IA4D1D;;;;;;;;;OASG;IACG,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0BzE;;;;;;;;OAQG;IACG,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvD;;;;;;;OAOG;IACG,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAgBlD"}