@secondlayer/sdk 6.24.1 → 6.25.1

package/dist/index.d.ts

@@ -1741,10 +1741,21 @@ type CreateStreamsClientOptions = {
 	*/
 	dumpsBaseUrl?: string
 	/**
-	* Verify the ed25519 `X-Signature` on every response (default off). Pass
-	* `true` to fetch the server's public key from
-	* `/public/streams/signing-key`, or `{ publicKey }` to pin a known PEM. A
-	* failed or missing signature throws `StreamsSignatureError`.
+	* Verify the ed25519 `X-Signature` on every REST response and per-frame SSE
+	* signature. Three states:
+	* - **default (omitted)** — *lenient*: verify when the server signs (the
+	*   hosted API signs every response), and pass through when no signature is
+	*   present (e.g. a self-hosted instance with no `STREAMS_SIGNING_PRIVATE_KEY`).
+	*   So verification is on by default against the hosted API without breaking
+	*   unsigned self-host deployments. An *invalid* signature always throws.
+	* - **`true`** (or `{ publicKey }` to pin a known PEM) — *strict*: a missing
+	*   OR invalid signature throws `StreamsSignatureError`. Use this when you
+	*   require a portable, non-repudiable attestation and won't accept unsigned
+	*   data (it also closes the lenient mode's strip-the-header downgrade).
+	* - **`false`** — off.
+	*
+	* The key is fetched once from `/public/streams/signing-key` (cached; a
+	* rotated `X-Signature-KeyId` triggers one refresh) unless a PEM is pinned.
 	*/
 	verify?: boolean | {
 		publicKey: string
@@ -2293,8 +2304,13 @@ type WebhookHeaderInput = HeaderLookup | StandardWebhooksHeaders | Record<string
 *
 * The signed content is `${id}.${timestamp}.${rawBody}` HMAC-SHA256 with the
 * signing secret. Secrets returned by `sl subscriptions create` (or
-* `rotate-secret`) carry a `whsec_` prefix and are base64-decoded after the
-* prefix is stripped, matching the Svix / Standard Webhooks convention.
+* `rotate-secret`) are a bare 64-character hex string used directly as the
+* HMAC key (its UTF-8 bytes) — this helper handles that. A `whsec_`-prefixed
+* base64 secret (the Svix convention) is also accepted and base64-decoded after
+* the prefix is stripped. Note: because the issued secret is bare hex (no
+* `whsec_` prefix), a generic Svix / Standard Webhooks library will base64-
+* decode it and derive the wrong key — verify with this helper (or with
+* {@link verifySecondlayerSignature}, the format-agnostic ed25519 path).
 *
 * @param rawBody         The raw request body as a string. NEVER pass
 *                        `JSON.stringify(req.body)` — re-stringifying drops
@@ -2308,9 +2324,10 @@ type WebhookHeaderInput = HeaderLookup | StandardWebhooksHeaders | Record<string
 *                        a header value by name. Header name matching is
 *                        case-insensitive.
 * @param secret          The signing secret returned by
-*                        `sl subscriptions create` / `rotateSecret`. Pass it
-*                        through verbatim — the helper handles the `whsec_`
-*                        prefix.
+*                        `sl subscriptions create` / `rotateSecret` (a bare
+*                        64-char hex string). Pass it through verbatim — the
+*                        helper accepts both bare hex and `whsec_`-prefixed
+*                        base64 secrets.
 * @param toleranceSeconds Max age of `webhook-timestamp` in seconds. Default
 *                         300 (5 min) per the Standard Webhooks spec.
 * @returns true if every header is present, the timestamp is within

package/dist/index.js

@@ -1319,10 +1319,16 @@ function subscribeStreamsEvents(opts) {
           }
           if (!parsed.event)
             continue;
-          if (opts.verify) {
-            const key = await opts.loadKey();
-            if (!parsed.sig || !ed25519.verifyEd25519(JSON.stringify(parsed.event), parsed.sig, key.publicKey)) {
-              throw new StreamsSignatureError("Streams SSE frame signature is missing or invalid.");
+          if (opts.verify !== "off") {
+            if (!parsed.sig) {
+              if (opts.verify === "strict") {
+                throw new StreamsSignatureError("Streams SSE frame signature is missing.");
+              }
+            } else {
+              const key = await opts.loadKey();
+              if (!ed25519.verifyEd25519(JSON.stringify(parsed.event), parsed.sig, key.publicKey)) {
+                throw new StreamsSignatureError("Streams SSE frame signature is invalid.");
+              }
             }
           }
           cursor = parsed.event.cursor ?? cursor;
@@ -1454,7 +1460,8 @@ async function mapStreamsError(response) {
 function createStreamsClient(options) {
   const baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_STREAMS_BASE_URL);
   const fetchImpl = options.fetchImpl ?? ((input, init) => fetch(input, init));
-  const verify = options.verify ?? false;
+  const verify = options.verify;
+  const verifyMode = verify === false ? "off" : verify === undefined ? "lenient" : "strict";
   let keyPromise = null;
   function loadKey() {
     if (keyPromise)
@@ -1496,25 +1503,28 @@ function createStreamsClient(options) {
     if (!response.ok)
       await mapStreamsError(response);
     const text = await response.text();
-    if (verify) {
+    if (verifyMode !== "off") {
       const signature = response.headers.get("X-Signature");
       if (!signature) {
-        throw new StreamsSignatureError("Response is missing X-Signature.");
-      }
-      const responseKeyId = response.headers.get("X-Signature-KeyId");
-      let key = await loadKey();
-      if (responseKeyId && responseKeyId !== key.keyId) {
-        if (typeof verify === "object") {
-          throw new StreamsSignatureError(`Response signed with key '${responseKeyId}', expected pinned key '${key.keyId}'.`);
+        if (verifyMode === "strict") {
+          throw new StreamsSignatureError("Response is missing X-Signature.");
         }
-        keyPromise = null;
-        key = await loadKey();
-        if (responseKeyId !== key.keyId) {
-          throw new StreamsSignatureError(`Response signed with key '${responseKeyId}' not served by the signing-key endpoint.`);
+      } else {
+        const responseKeyId = response.headers.get("X-Signature-KeyId");
+        let key = await loadKey();
+        if (responseKeyId && responseKeyId !== key.keyId) {
+          if (typeof verify === "object") {
+            throw new StreamsSignatureError(`Response signed with key '${responseKeyId}', expected pinned key '${key.keyId}'.`);
+          }
+          keyPromise = null;
+          key = await loadKey();
+          if (responseKeyId !== key.keyId) {
+            throw new StreamsSignatureError(`Response signed with key '${responseKeyId}' not served by the signing-key endpoint.`);
+          }
+        }
+        if (!ed255192.verifyEd25519(text, signature, key.publicKey)) {
+          throw new StreamsSignatureError;
         }
-      }
-      if (!ed255192.verifyEd25519(text, signature, key.publicKey)) {
-        throw new StreamsSignatureError;
       }
     }
     return JSON.parse(text);
@@ -1618,7 +1628,7 @@ function createStreamsClient(options) {
           baseUrl,
           apiKey: options.apiKey,
           fetchImpl,
-          verify: Boolean(verify),
+          verify: verifyMode,
           loadKey,
           params
         });
@@ -2505,5 +2515,5 @@ export {
   ApiError
 };
 
-//# debugId=83F19CEB4B72C83564756E2164756E21
+//# debugId=9B0B41D8F5C2671064756E2164756E21
 //# sourceMappingURL=index.js.map