@secondlayer/sdk 6.9.0 → 6.10.0

package/README.md

@@ -27,6 +27,13 @@ require an `sk-sl_` API key, created in the platform console at
 https://secondlayer.tools/platform/api-keys. (Public Streams bulk dumps —
 `client.dumps`, `events.replay` — need no key.)
 
+**API keys.** Each `sk-sl_` key has a `product`. An **`account`** key (dashboard
+default) grants both `streams:read` and `index:read` and is the only key that can
+mint new keys; **`streams`** / **`index`** keys are scoped, read-only, and cannot
+mint. Mint scoped keys programmatically with `sl.apiKeys.create({ product })`
+(needs an account/owner key) — the returned `key` is shown once and inherits your
+plan's tier.
+
 ## Mental model
 
 - `sl.streams` reads raw ordered L1 events from Stacks Streams.

package/dist/index.d.ts

@@ -731,6 +731,7 @@ type StackingEnvelope = {
 	stacking: IndexStackingAction[]
 	next_cursor: string | null
 	tip: IndexTip
+	reorgs: never[]
 	/** Present only when the PoX-4 decoder is disabled, explaining an empty feed. */
 	notes?: string
 };
@@ -1053,6 +1054,23 @@ type StreamsEventsStreamParams = {
 	maxEmptyPolls?: number
 	signal?: AbortSignal
 };
+type StreamsEventsSubscribeParams = {
+	/** Resume strictly after this cursor; omit to live-tail from the tip. */
+	fromCursor?: string | null
+	types?: readonly StreamsEventType[]
+	notTypes?: readonly StreamsEventType[]
+	contractId?: StreamsFilterValue
+	sender?: StreamsFilterValue
+	recipient?: StreamsFilterValue
+	assetIdentifier?: string
+	/** Abort to unsubscribe (the returned function does the same). */
+	signal?: AbortSignal
+	/** Called for each pushed event, in order. */
+	onEvent: (event: StreamsEvent) => void | Promise<void>
+	/** Called on a connection error; the subscription auto-reconnects from the
+	*  last delivered cursor unless the signal has aborted. */
+	onError?: (err: unknown) => void
+};
 /**
 * The checkpoint the SDK computes for a batch. Persist `cursor` inside the same
 * transaction as your projection writes, then resume from it via `fromCursor`.
@@ -1158,6 +1176,11 @@ type StreamsDumpsManifest = {
 		to_block: number
 	}
 	files: StreamsDumpFile[]
+	/** ed25519 signature over the manifest's canonical bytes. Absent on legacy
+	*  unsigned manifests. Verified by `list()` when `verifyDumpsManifest` is on. */
+	signature?: string
+	/** Short id of the signing public key. */
+	key_id?: string
 };
 type StreamsDumps = {
 	/** Fetch and parse the latest dumps manifest. */
@@ -1197,6 +1220,13 @@ type StreamsClient = {
 		* `maxEmptyPolls` stops it.
 		*/
 		stream(params?: StreamsEventsStreamParams): AsyncIterable<StreamsEvent>
+		/**
+		* Subscribe to the real-time SSE push surface. Calls `onEvent` for each new
+		* canonical event as the server pushes it (chain cadence, not poll-bounded),
+		* and verifies each frame's inline ed25519 signature when the client was
+		* created with `verify`. Returns an unsubscribe function.
+		*/
+		subscribe(params: StreamsEventsSubscribeParams): () => void
 	}
 	blocks: {
 		events(heightOrHash: number | string): Promise<StreamsEventsListEnvelope>
@@ -1333,6 +1363,12 @@ type CreateStreamsClientOptions = {
 	verify?: boolean | {
 		publicKey: string
 	}
+	/**
+	* Verify the bulk dumps manifest's ed25519 signature in `client.dumps.list()`
+	* before trusting any file sha256 (default off). Uses the same key source as
+	* `verify`. Default off until historical manifests carry signatures.
+	*/
+	verifyDumpsManifest?: boolean
 };
 declare function createStreamsClient(options: CreateStreamsClientOptions): StreamsClient;
 declare class AuthError extends Error {
@@ -1739,10 +1775,40 @@ type WebhookHeaderInput = HeaderLookup | StandardWebhooksHeaders | Record<string
 * ```
 */
 declare function verifyWebhookSignature(rawBody: string, headers: WebhookHeaderInput, secret: string, toleranceSeconds?: number): boolean;
+/**
+* Verify the universal Secondlayer authenticity signature that every delivery
+* carries, regardless of body format (`raw`, `cloudevents`, `standard-webhooks`,
+* …). This is the format-agnostic alternative to {@link verifyWebhookSignature}:
+* instead of a per-subscription HMAC secret, it checks an ed25519 signature over
+* `${webhook-id}.${rawBody}` against Secondlayer's published public key — so one
+* key proves authenticity for any format.
+*
+* @param rawBody    The raw request body string (never re-stringify the parsed
+*                   JSON — whitespace/key-order changes break the signature).
+* @param headers    Request headers — plain object, Fetch `Headers`, or a
+*                   lookup callback. Reads `webhook-id` + `x-secondlayer-signature`.
+* @param publicKeyPem Secondlayer's published ed25519 public key (SPKI PEM).
+* @returns true when the signature header is present and verifies.
+*
+* @example
+* ```ts
+* import { verifySecondlayerSignature } from "@secondlayer/sdk";
+*
+* app.post("/webhook", async (c) => {
+*   const raw = await c.req.text();
+*   if (!verifySecondlayerSignature(raw, c.req.raw.headers, SECONDLAYER_PUBLIC_KEY)) {
+*     return c.text("Invalid signature", 401);
+*   }
+*   // ... process raw ...
+*   return c.body(null, 204);
+* });
+* ```
+*/
+declare function verifySecondlayerSignature(rawBody: string, headers: WebhookHeaderInput, publicKeyPem: string): boolean;
 /** Make a cvToValue result JSON-serializable: Clarity (u)ints decode to bigint,
 *  which JSON.stringify can't handle — convert recursively to strings. */
 declare function toJsonSafe(value: unknown): unknown;
 /** Decode a hex-encoded Clarity value to JSON-safe JS (uints as strings,
 *  buffers as `0x…` hex, tuples as objects). Returns the input hex on failure. */
 declare function decodeClarityValue(hex: string): unknown;
-export { verifyWebhookSignature, trigger, toJsonSafe, isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, getSubgraph, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decodeClarityValue, createStreamsClient, VersionConflictError, ValidationError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, TransactionsWalkParams, TransactionsListParams, TransactionsEnvelope, TransactionEnvelope, Subscriptions, SubscriptionSummary2 as SubscriptionSummary, SubscriptionStatus, SubscriptionRuntime, SubscriptionKind, SubscriptionFormat, SubscriptionDetail2 as SubscriptionDetail, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphOperationStatus, SubgraphAgentSchema3 as SubgraphAgentSchema, StreamsUsage, StreamsTip, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorgContext, StreamsReorg, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, StackingWalkParams, StackingListParams, StackingEnvelope, SecondLayerOptions, SecondLayer, ScopedKeyProduct, RotateSecretResponse2 as RotateSecretResponse, ReplayResult2 as ReplayResult, RateLimitError, Pox4CallsParams, NftTransfersWalkParams, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload, NftTransferEvent, NftTransfer, MempoolWalkParams, MempoolTransactionEnvelope, MempoolListParams, MempoolEnvelope, IndexUsage, IndexTransaction, IndexTip, IndexStackingAction, IndexPostCondition, IndexMempoolTransaction, IndexEventType, IndexEvent, IndexContractCall, IndexCanonicalBlock, IndexBlock, Index, FtTransfersWalkParams, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, EventsWalkParams, EventsListParams, EventsEnvelope, DeliveryRow2 as DeliveryRow, DecodedStxTransferPayload, DecodedStxTransfer, DecodedStxMintPayload, DecodedStxMint, DecodedStxLockPayload, DecodedStxLock, DecodedStxBurnPayload, DecodedStxBurn, DecodedPrintValue, DecodedPrintPayload, DecodedPrint, DecodedNftTransferPayload, DecodedNftTransfer, DecodedNftMintPayload, DecodedNftMint, DecodedNftBurnPayload, DecodedNftBurn, DecodedFtTransferPayload, DecodedFtTransfer, DecodedFtMintPayload, DecodedFtMint, DecodedFtBurnPayload, DecodedFtBurn, DecodedEventRow, DecodedEventColumns, DeadRow2 as DeadRow, Datasets, DatasetRow, CursorListParams, CursorEnvelope, Cursor, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, CreateApiKeyResponse, CreateApiKeyParams, ContractsListParams, ContractsEnvelope, Contracts, ContractSummary, ContractConformance, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, ContextSnapshot, ContextAccount, ChainTriggerType, ChainTrigger, CanonicalWalkParams, CanonicalListParams, CanonicalEnvelope, CURSOR_SLUGS, BlocksWalkParams, BlocksListParams, BlocksEnvelope, BlockEnvelope, AuthError, ApiKeys, ApiError, ActiveSubgraphOperation };
+export { verifyWebhookSignature, verifySecondlayerSignature, trigger, toJsonSafe, isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, getSubgraph, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decodeClarityValue, createStreamsClient, VersionConflictError, ValidationError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, TransactionsWalkParams, TransactionsListParams, TransactionsEnvelope, TransactionEnvelope, Subscriptions, SubscriptionSummary2 as SubscriptionSummary, SubscriptionStatus, SubscriptionRuntime, SubscriptionKind, SubscriptionFormat, SubscriptionDetail2 as SubscriptionDetail, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphOperationStatus, SubgraphAgentSchema3 as SubgraphAgentSchema, StreamsUsage, StreamsTip, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorgContext, StreamsReorg, StreamsEventsSubscribeParams, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, StackingWalkParams, StackingListParams, StackingEnvelope, SecondLayerOptions, SecondLayer, ScopedKeyProduct, RotateSecretResponse2 as RotateSecretResponse, ReplayResult2 as ReplayResult, RateLimitError, Pox4CallsParams, NftTransfersWalkParams, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload, NftTransferEvent, NftTransfer, MempoolWalkParams, MempoolTransactionEnvelope, MempoolListParams, MempoolEnvelope, IndexUsage, IndexTransaction, IndexTip, IndexStackingAction, IndexPostCondition, IndexMempoolTransaction, IndexEventType, IndexEvent, IndexContractCall, IndexCanonicalBlock, IndexBlock, Index, FtTransfersWalkParams, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, EventsWalkParams, EventsListParams, EventsEnvelope, DeliveryRow2 as DeliveryRow, DecodedStxTransferPayload, DecodedStxTransfer, DecodedStxMintPayload, DecodedStxMint, DecodedStxLockPayload, DecodedStxLock, DecodedStxBurnPayload, DecodedStxBurn, DecodedPrintValue, DecodedPrintPayload, DecodedPrint, DecodedNftTransferPayload, DecodedNftTransfer, DecodedNftMintPayload, DecodedNftMint, DecodedNftBurnPayload, DecodedNftBurn, DecodedFtTransferPayload, DecodedFtTransfer, DecodedFtMintPayload, DecodedFtMint, DecodedFtBurnPayload, DecodedFtBurn, DecodedEventRow, DecodedEventColumns, DeadRow2 as DeadRow, Datasets, DatasetRow, CursorListParams, CursorEnvelope, Cursor, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, CreateApiKeyResponse, CreateApiKeyParams, ContractsListParams, ContractsEnvelope, Contracts, ContractSummary, ContractConformance, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, ContextSnapshot, ContextAccount, ChainTriggerType, ChainTrigger, CanonicalWalkParams, CanonicalListParams, CanonicalEnvelope, CURSOR_SLUGS, BlocksWalkParams, BlocksListParams, BlocksEnvelope, BlockEnvelope, AuthError, ApiKeys, ApiError, ActiveSubgraphOperation };

package/dist/index.js

@@ -891,7 +891,7 @@ class Index extends BaseClient {
 }
 
 // src/streams/client.ts
-import { ed25519 } from "@secondlayer/shared";
+import { ed25519 as ed255192 } from "@secondlayer/shared";
 
 // src/streams/errors.ts
 class AuthError extends Error {
@@ -1078,6 +1078,7 @@ async function* streamStreamsEvents(opts) {
 
 // src/streams/dumps.ts
 import { createHash } from "node:crypto";
+import { verifyStreamsBulkManifestSignature } from "@secondlayer/shared/streams-bulk-manifest";
 function createStreamsDumps(opts) {
   const baseUrl = opts.baseUrl?.replace(/\/+$/, "");
   function requireBaseUrl() {
@@ -1095,7 +1096,17 @@ function createStreamsDumps(opts) {
     if (!res.ok) {
       throw new StreamsServerError(`Could not fetch dumps manifest (${res.status}).`, res.status);
     }
-    return await res.json();
+    const manifest = await res.json();
+    if (opts.verifyManifest) {
+      if (!opts.loadPublicKeyPem) {
+        throw new StreamsSignatureError("Manifest verification is on but no signing key source is configured.");
+      }
+      const publicKeyPem = await opts.loadPublicKeyPem();
+      if (!verifyStreamsBulkManifestSignature(manifest, publicKeyPem)) {
+        throw new StreamsSignatureError("Dumps manifest signature is missing or invalid.");
+      }
+    }
+    return manifest;
   }
   async function download(file) {
     const res = await opts.fetchImpl(fileUrl(file));
@@ -1112,6 +1123,135 @@ function createStreamsDumps(opts) {
   return { list, fileUrl, download };
 }
 
+// src/streams/subscribe.ts
+import { ed25519 } from "@secondlayer/shared";
+function subscribeStreamsEvents(opts) {
+  const { params } = opts;
+  const controller = new AbortController;
+  const external = params.signal;
+  if (external) {
+    if (external.aborted)
+      controller.abort();
+    else
+      external.addEventListener("abort", () => controller.abort(), {
+        once: true
+      });
+  }
+  let cursor = params.fromCursor ?? null;
+  const reconnectDelayMs = opts.reconnectDelayMs ?? 1000;
+  const run = async () => {
+    while (!controller.signal.aborted) {
+      try {
+        const url = `${opts.baseUrl}/v1/streams/events/stream${buildQuery({
+          from_cursor: cursor ?? undefined,
+          types: params.types,
+          not_types: params.notTypes,
+          contract_id: params.contractId,
+          sender: params.sender,
+          recipient: params.recipient,
+          asset_identifier: params.assetIdentifier
+        })}`;
+        const res = await opts.fetchImpl(url, {
+          headers: {
+            Authorization: `Bearer ${opts.apiKey}`,
+            Accept: "text/event-stream"
+          },
+          signal: controller.signal
+        });
+        if (!res.ok) {
+          throw new StreamsServerError(`Streams SSE returned ${res.status}.`, res.status);
+        }
+        if (!res.body) {
+          throw new StreamsServerError("Streams SSE response has no body.", 0);
+        }
+        for await (const frame of parseSseFrames(res.body, controller.signal)) {
+          if (frame.event === "ping" || !frame.data)
+            continue;
+          let parsed;
+          try {
+            parsed = JSON.parse(frame.data);
+          } catch {
+            continue;
+          }
+          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.");
+            }
+          }
+          cursor = parsed.event.cursor ?? cursor;
+          await params.onEvent(parsed.event);
+        }
+      } catch (err) {
+        if (controller.signal.aborted)
+          return;
+        params.onError?.(err);
+        await sleep(reconnectDelayMs, controller.signal);
+      }
+    }
+  };
+  run();
+  return () => controller.abort();
+}
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal.aborted)
+      return resolve();
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function* parseSseFrames(body, signal) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder;
+  let buffer = "";
+  try {
+    while (!signal.aborted) {
+      const { value, done } = await reader.read();
+      if (done)
+        break;
+      buffer += decoder.decode(value, { stream: true });
+      let sep = buffer.indexOf(`
+
+`);
+      while (sep !== -1) {
+        yield parseFrame(buffer.slice(0, sep));
+        buffer = buffer.slice(sep + 2);
+        sep = buffer.indexOf(`
+
+`);
+      }
+    }
+  } finally {
+    try {
+      await reader.cancel();
+    } catch {}
+  }
+}
+function parseFrame(raw) {
+  let event;
+  const data = [];
+  for (const line of raw.split(`
+`)) {
+    if (line.startsWith("data:")) {
+      data.push(line.slice(line.startsWith("data: ") ? 6 : 5));
+    } else if (line.startsWith("event:")) {
+      event = line.slice(line.startsWith("event: ") ? 7 : 6).trim();
+    }
+  }
+  return { event, data: data.length > 0 ? data.join(`
+`) : undefined };
+}
+
 // src/streams/client.ts
 function cursorTuple(cursor) {
   if (!cursor)
@@ -1171,10 +1311,6 @@ 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 dumps = createStreamsDumps({
-    baseUrl: options.dumpsBaseUrl,
-    fetchImpl
-  });
   let keyPromise = null;
   function loadKey() {
     if (keyPromise)
@@ -1182,8 +1318,9 @@ function createStreamsClient(options) {
     keyPromise = (async () => {
       if (typeof verify === "object") {
         return {
-          keyId: ed25519.ed25519KeyId(verify.publicKey),
-          publicKey: ed25519.loadEd25519PublicKey(verify.publicKey)
+          keyId: ed255192.ed25519KeyId(verify.publicKey),
+          publicKeyPem: verify.publicKey,
+          publicKey: ed255192.loadEd25519PublicKey(verify.publicKey)
         };
       }
       const res = await fetchImpl(`${baseUrl}/public/streams/signing-key`);
@@ -1195,12 +1332,19 @@ function createStreamsClient(options) {
         throw new StreamsSignatureError("Signing key response missing key.");
       }
       return {
-        keyId: body.key_id ?? ed25519.ed25519KeyId(body.public_key_pem),
-        publicKey: ed25519.loadEd25519PublicKey(body.public_key_pem)
+        keyId: body.key_id ?? ed255192.ed25519KeyId(body.public_key_pem),
+        publicKeyPem: body.public_key_pem,
+        publicKey: ed255192.loadEd25519PublicKey(body.public_key_pem)
       };
     })();
     return keyPromise;
   }
+  const dumps = createStreamsDumps({
+    baseUrl: options.dumpsBaseUrl,
+    fetchImpl,
+    verifyManifest: options.verifyDumpsManifest ?? false,
+    loadPublicKeyPem: async () => (await loadKey()).publicKeyPem
+  });
   async function request(path) {
     const response = await fetchImpl(`${baseUrl}${path}`, {
       headers: { Authorization: `Bearer ${options.apiKey}` }
@@ -1225,7 +1369,7 @@ function createStreamsClient(options) {
           throw new StreamsSignatureError(`Response signed with key '${responseKeyId}' not served by the signing-key endpoint.`);
         }
       }
-      if (!ed25519.verifyEd25519(text, signature, key.publicKey)) {
+      if (!ed255192.verifyEd25519(text, signature, key.publicKey)) {
         throw new StreamsSignatureError;
       }
     }
@@ -1310,6 +1454,16 @@ function createStreamsClient(options) {
           fetchEvents
         });
       },
+      subscribe(params) {
+        return subscribeStreamsEvents({
+          baseUrl,
+          apiKey: options.apiKey,
+          fetchImpl,
+          verify: Boolean(verify),
+          loadKey,
+          params
+        });
+      },
       async replay(params) {
         const fromCursor = params.from === "genesis" ? null : params.from ?? null;
         const fromBlock = fromCursor ? cursorTuple(fromCursor)[0] : 0;
@@ -1763,6 +1917,7 @@ import {
   STREAMS_EVENT_TYPES
 } from "@secondlayer/shared";
 // src/webhooks.ts
+import { verifySecondlayerSignatureValues } from "@secondlayer/shared/crypto/secondlayer-webhook";
 import {
   verify
 } from "@secondlayer/shared/crypto/standard-webhooks";
@@ -1805,8 +1960,14 @@ function verifyWebhookSignature(rawBody, headers, secret, toleranceSeconds = 300
     "webhook-signature": signature
   }, secret, { toleranceSeconds });
 }
+function verifySecondlayerSignature(rawBody, headers, publicKeyPem) {
+  const id = pickHeader(headers, "webhook-id");
+  const signature = pickHeader(headers, "x-secondlayer-signature");
+  return verifySecondlayerSignatureValues(rawBody, id, signature, publicKeyPem);
+}
 export {
   verifyWebhookSignature,
+  verifySecondlayerSignature,
   trigger,
   toJsonSafe,
   isStxTransfer,
@@ -1852,5 +2013,5 @@ export {
   ApiError
 };
 
-//# debugId=209F8CDE1560C10F64756E2164756E21
+//# debugId=30831F6F187A1F5A64756E2164756E21
 //# sourceMappingURL=index.js.map