retrace-sdk 0.16.1 → 0.16.2

package/dist/config.d.ts

@@ -12,10 +12,18 @@ export interface Config {
      *  holds an open socket and always surfaces upload errors); "ws" forces WebSocket. */
     transport: "auto" | "ws" | "http";
     /** Replay safety. When a deterministic replay hits a cassette MISS (no recorded entry for a
-     *  call), the SDK otherwise falls through to a REAL provider call (live cost + non-determinism).
-     *  With strictReplay=true the SDK throws instead (fail-closed). Default false: warn + fall through.
-     *  Env: RETRACE_STRICT_REPLAY. */
+     *  call), the SDK can either throw (fail-closed) or fall through to a REAL provider call (live cost
+     *  + non-determinism, driven by a server-supplied cassette). Default TRUE (fail-closed): the SDK
+     *  throws on a miss. Set strictReplay:false (or RETRACE_STRICT_REPLAY=false) to opt back into the
+     *  legacy warn + fall-through behavior. Env: RETRACE_STRICT_REPLAY. */
     strictReplay: boolean;
+    /** C2: honor SERVER-INITIATED resume/replay commands — dashboard-driven cascade replay that
+     *  re-executes YOUR registered (resumable) function in THIS process with server-supplied input and
+     *  cassette. Default FALSE: the SDK ignores those frames unless you explicitly opt in, because
+     *  acting on them means trusting the server (and the transport) to invoke code in your environment
+     *  with attacker-influenceable arguments. Recording, and server-side forking, are unaffected.
+     *  Env: RETRACE_ALLOW_REMOTE_REPLAY. */
+    allowRemoteReplay: boolean;
     /** Called with a STRUCTURED signal when the server signals credits_exhausted | rate_limited |
      *  halt | error. Branch on `signal.code`; use `signal.retryable`/`signal.fatal` to decide
      *  behavior. Defaults to a throttled console warning so signals are never silently dropped. */

package/dist/config.js

@@ -11,7 +11,8 @@ const config = {
     sampleRate: parseFloat(env.RETRACE_SAMPLE_RATE || "1"),
     sampleSeed: env.RETRACE_SAMPLE_SEED || undefined,
     transport: (["auto", "ws", "http"].includes(env.RETRACE_TRANSPORT || "") ? env.RETRACE_TRANSPORT : "auto"),
-    strictReplay: ["true", "1"].includes((env.RETRACE_STRICT_REPLAY || "").toLowerCase()),
+    strictReplay: !["false", "0", "no"].includes((env.RETRACE_STRICT_REPLAY || "").toLowerCase()),
+    allowRemoteReplay: ["true", "1", "yes"].includes((env.RETRACE_ALLOW_REMOTE_REPLAY || "").toLowerCase()),
     maxStepsPerRun: env.RETRACE_MAX_STEPS_PER_RUN ? parseInt(env.RETRACE_MAX_STEPS_PER_RUN, 10) : undefined,
     maxTokensPerRun: env.RETRACE_MAX_TOKENS_PER_RUN ? parseInt(env.RETRACE_MAX_TOKENS_PER_RUN, 10) : undefined,
     maxUsdPerRun: env.RETRACE_MAX_USD_PER_RUN ? parseFloat(env.RETRACE_MAX_USD_PER_RUN) : undefined,
@@ -20,6 +21,32 @@ const config = {
     environment: env.RETRACE_ENVIRONMENT || undefined,
 };
 config.wsUrl = config.baseUrl.replace("https://", "wss://").replace("http://", "ws://");
+function isLoopbackHost(host) {
+    const h = host.toLowerCase().replace(/^\[|\]$/g, "");
+    return h === "localhost" || h === "127.0.0.1" || h === "::1" || h.endsWith(".localhost");
+}
+/**
+ * C3: refuse cleartext transports for non-loopback hosts. Over http:// → ws:// the one-time auth
+ * frame sends the API key in plaintext AND every server command frame (resume/replay/halt) is
+ * injectable on the wire — which is the transport half of the C2 command-injection chain. https://
+ * (and http://localhost for local dev) are allowed; anything else hard-errors before any bytes,
+ * including the API key, leave the process.
+ */
+function assertSecureBaseUrl(baseUrl) {
+    let u;
+    try {
+        u = new URL(baseUrl);
+    }
+    catch {
+        throw new Error(`Retrace: invalid base URL ${JSON.stringify(baseUrl)} (set RETRACE_BASE_URL or configure({ baseUrl }) to an https:// URL).`);
+    }
+    if (u.protocol === "https:")
+        return;
+    if (u.protocol === "http:" && isLoopbackHost(u.hostname))
+        return; // local dev only
+    throw new Error(`Retrace: refusing insecure base URL ${JSON.stringify(baseUrl)}. Use https:// (http:// is allowed only for localhost). ` +
+        "Over cleartext the API key is transmitted in plaintext and server replay/resume command frames can be injected on the wire.");
+}
 export function configure(opts) {
     if (opts.apiKey && (!opts.apiKey.startsWith("rt_") || opts.apiKey.startsWith("rt_live_") || opts.apiKey.startsWith("rt_test_"))) {
         throw new Error("Invalid Retrace API key. Keys must start with 'rt_'. Get yours at https://retraceai.tech/settings");
@@ -28,6 +55,7 @@ export function configure(opts) {
     if (opts.baseUrl && !opts.wsUrl) {
         config.wsUrl = config.baseUrl.replace("https://", "wss://").replace("http://", "ws://");
     }
+    assertSecureBaseUrl(config.baseUrl);
     // Eagerly install provider interceptors so clients constructed AFTER configure() are patched.
     // @google/genai binds generateContent as an own instance property, and our accessor only wraps
     // instances built after install — so install must precede client construction. Fire-and-forget;
@@ -42,6 +70,9 @@ export function requireApiKey() {
     if (!config.apiKey) {
         throw new Error("Retrace API key required. Call configure({ apiKey: 'rt_...' }) or set RETRACE_API_KEY. Get yours at https://retraceai.tech/settings");
     }
+    // Validate the transport is encrypted before the key is ever used on the wire (covers env-only
+    // config that never called configure()).
+    assertSecureBaseUrl(config.baseUrl);
     return config.apiKey;
 }
 export function getConfig() {

package/dist/telemetry.js

@@ -14,7 +14,7 @@ import { getConfig } from "./config.js";
 const ANON_ID = Math.random().toString(16).slice(2, 18);
 const DISABLED = new Set(["0", "false", "no", "off"]);
 // Keep in sync with package.json version.
-const SDK_VERSION = "0.16.1";
+const SDK_VERSION = "0.16.2";
 function enabled() {
     return !DISABLED.has((process.env.RETRACE_TELEMETRY ?? "1").trim().toLowerCase());
 }

package/dist/transport.js

@@ -2,7 +2,7 @@ import { getConfig } from "./config.js";
 import { classifyServerSignal } from "./errors.js";
 // Client identifier sent on every request so the backend can attribute SDK usage/version.
 // Keep in sync with package.json on release.
-const CLIENT_ID = "typescript-sdk/0.16.1";
+const CLIENT_ID = "typescript-sdk/0.16.2";
 // ─── Runtime-agnostic WebSocket ──────────────────────────────────────────────
 // Prefer the global Web `WebSocket` (Node 20+, Bun, Deno, browsers, and every edge runtime); fall
 // back to the OPTIONAL `ws` package only on older Node that lacks a global. Both expose the standard
@@ -103,19 +103,29 @@ export class WSTransport {
                     else if (msg.type === "error") {
                         this.surfaceSignal(classifyServerSignal("error", msg.error));
                     }
-                    else if (msg.type === "resume") {
-                        import("./resume.js").then(({ parseResumeMessage, handleResume }) => {
-                            const cmd = parseResumeMessage(msg);
-                            if (cmd)
-                                handleResume(cmd);
-                        });
-                    }
-                    else if (msg.type === "replay") {
-                        import("./replay.js").then(({ parseReplayMessage, handleReplay }) => {
-                            const cmd = parseReplayMessage(msg);
-                            if (cmd)
-                                handleReplay(cmd);
-                        });
+                    else if (msg.type === "resume" || msg.type === "replay") {
+                        // C2: server-initiated re-execution invokes the user's registered function in THIS process
+                        // with server-supplied input/args/cassette. Off by default — only act on these frames when
+                        // the developer explicitly opted in, so a compromised/misrouted server (or an injected
+                        // frame) can't drive code execution here.
+                        if (!getConfig().allowRemoteReplay) {
+                            this.throttledSignalWarn(`remote_blocked:${msg.type}`, `[retrace] ignoring server "${msg.type}" command — remote-controlled re-execution is disabled. Set allowRemoteReplay:true (or RETRACE_ALLOW_REMOTE_REPLAY=true) to opt in.`);
+                            return;
+                        }
+                        if (msg.type === "resume") {
+                            import("./resume.js").then(({ parseResumeMessage, handleResume }) => {
+                                const cmd = parseResumeMessage(msg);
+                                if (cmd)
+                                    handleResume(cmd);
+                            });
+                        }
+                        else {
+                            import("./replay.js").then(({ parseReplayMessage, handleReplay }) => {
+                                const cmd = parseReplayMessage(msg);
+                                if (cmd)
+                                    handleReplay(cmd);
+                            });
+                        }
                     }
                     else if (msg.type === "halt") {
                         const reason = msg.data?.reason || "Guardrail triggered";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retrace-sdk",
-  "version": "0.16.1",
+  "version": "0.16.2",
   "description": "The execution replay engine for AI agents. Record, replay, fork, and share agent executions.",
   "type": "module",
   "main": "dist/index.js",