@stacknet/stacks 0.1.2 → 0.2.0

package/src/streaming/sse.ts

@@ -11,6 +11,22 @@ export interface SSEEvent {
   retry?: number;
 }
 
+/** Hard cap on the in-memory buffer used by `parseSSEStream`. A malicious
+ *  or malfunctioning upstream that never emits a newline would otherwise
+ *  grow the buffer until the process OOMs. 1 MiB is far beyond any real
+ *  SSE event. */
+const MAX_SSE_BUFFER_BYTES = 1024 * 1024;
+
+/** SSE framing uses newlines as field separators; any `\r` or `\n` in
+ *  `event`, `id`, or a string `data` value would let an untrusted caller
+ *  inject additional SSE frames that the receiver would process as if
+ *  they came from the server. Strip them. */
+function stripCRLF(value: string): string {
+  // Replace CR/LF/LS/PS with a single space so the field remains
+  // structurally valid without carrying a frame separator.
+  return value.replace(/[\r\n\u2028\u2029]/g, ' ');
+}
+
 /**
  * Parse SSE stream from a Response
  */
@@ -32,6 +48,11 @@ export async function* parseSSEStream(
       if (done) break;
 
       buffer += decoder.decode(value, { stream: true });
+      if (buffer.length > MAX_SSE_BUFFER_BYTES) {
+        throw new Error(
+          `SSE buffer exceeded ${MAX_SSE_BUFFER_BYTES} bytes without an event delimiter`,
+        );
+      }
       const lines = buffer.split('\n');
       buffer = lines.pop() || '';
 
@@ -86,6 +107,43 @@ export async function* parseSSEStream(
   }
 }
 
+/** Encode an SSE message safely — every field with CRLF stripped, data
+ *  multi-line payloads split into repeated `data:` lines per the spec.
+ *  Keeping this in one place lets both `createSSEResponse` and
+ *  `SSEWriter.write` share exactly the same sanitization rules. */
+function encodeEvent(event: SSEEvent): string {
+  let message = '';
+
+  if (event.event) {
+    message += `event: ${stripCRLF(event.event)}\n`;
+  }
+
+  if (event.id) {
+    message += `id: ${stripCRLF(event.id)}\n`;
+  }
+
+  if (event.retry !== undefined && Number.isFinite(event.retry)) {
+    // retry is numeric per the SSE spec — coerce defensively.
+    message += `retry: ${Math.floor(event.retry)}\n`;
+  }
+
+  const dataString =
+    typeof event.data === 'string'
+      ? event.data
+      : JSON.stringify(event.data);
+
+  // Per the SSE spec, data may span multiple lines — each line is a
+  // separate `data:` field. This also means an embedded newline in a
+  // string payload can't be used to smuggle a new frame: the blank
+  // line at the end of the event is produced by us, not the caller.
+  for (const dataLine of dataString.split(/\r?\n/)) {
+    message += `data: ${dataLine}\n`;
+  }
+
+  message += '\n';
+  return message;
+}
+
 /**
  * Create an SSE Response from an async iterable
  */
@@ -99,28 +157,7 @@ export function createSSEResponse(
     async start(controller) {
       try {
         for await (const event of stream) {
-          let message = '';
-
-          if (event.event) {
-            message += `event: ${event.event}\n`;
-          }
-
-          if (event.id) {
-            message += `id: ${event.id}\n`;
-          }
-
-          if (event.retry) {
-            message += `retry: ${event.retry}\n`;
-          }
-
-          const data =
-            typeof event.data === 'string'
-              ? event.data
-              : JSON.stringify(event.data);
-
-          message += `data: ${data}\n\n`;
-
-          controller.enqueue(encoder.encode(message));
+          controller.enqueue(encoder.encode(encodeEvent(event)));
         }
       } catch (error) {
         console.error('SSE stream error:', error);
@@ -178,23 +215,7 @@ export class SSEWriter {
    */
   write(event: SSEEvent): void {
     if (!this.controller) return;
-
-    let message = '';
-
-    if (event.event) {
-      message += `event: ${event.event}\n`;
-    }
-
-    if (event.id) {
-      message += `id: ${event.id}\n`;
-    }
-
-    const data =
-      typeof event.data === 'string' ? event.data : JSON.stringify(event.data);
-
-    message += `data: ${data}\n\n`;
-
-    this.controller.enqueue(this.encoder.encode(message));
+    this.controller.enqueue(this.encoder.encode(encodeEvent(event)));
   }
 
   /**
@@ -209,7 +230,11 @@ export class SSEWriter {
    */
   writeComment(comment: string): void {
     if (!this.controller) return;
-    this.controller.enqueue(this.encoder.encode(`: ${comment}\n\n`));
+    // Comments are a single `:` line followed by a blank line. Strip any
+    // CRLF so a caller can't close out the comment and smuggle a real
+    // event after it.
+    const safe = stripCRLF(comment);
+    this.controller.enqueue(this.encoder.encode(`: ${safe}\n\n`));
   }
 
   /**

package/src/types/agent.ts

@@ -98,6 +98,8 @@ export interface AgentFromPromptInput {
 
 export interface AgentsClientConfig {
   baseUrl?: string;
+  /** JWT auth token for authenticated requests */
+  authToken?: string;
   /**
    * Use the coprocessor API (/cpx/agent/agents) instead of legacy (/agents).
    * Defaults to true. Set to false for backwards compatibility.