@glasstrace/sdk 1.1.1 → 1.1.3

package/README.md

@@ -4,7 +4,14 @@ Server-side debugging SDK for AI coding agents. Captures traces,
 errors, and runtime context from your Node.js application and delivers
 them to coding agents through an MCP server and live dashboard.
 
-> **Status: Pre-release** -- not yet published to npm.
+> **Status:** Stable, published as [`@glasstrace/sdk`](https://www.npmjs.com/package/@glasstrace/sdk) on npm.
+>
+> ```bash
+> npm install @glasstrace/sdk
+> ```
+>
+> See [CHANGELOG.md](https://github.com/Erik-1259/glasstrace-sdk/blob/main/packages/sdk/CHANGELOG.md)
+> for the release history.
 
 See the [monorepo README](../../README.md) for the full API overview,
 including the [Coexistence with Other OTel Tools](../../README.md#coexistence-with-other-otel-tools)
@@ -156,6 +163,42 @@ GLASSTRACE_SUPPRESS_ACTION_NUDGE=1
 The nudge never fires in production (detected via `NODE_ENV` or
 `VERCEL_ENV`) unless `GLASSTRACE_FORCE_ENABLE=true` is also set.
 
+## Capturing error response bodies
+
+When debugging a 4xx or 5xx, the response body is often the most useful
+signal — it carries the validation message, the tRPC error envelope, or
+the upstream error code. The SDK can attach the body to the span as
+`glasstrace.error.response_body`, but only under a strict three-gate
+policy designed to prevent accidental leakage of customer data:
+
+1. **Account opt-in.** The capture is gated on the
+   `errorResponseBodies` flag in your account's capture configuration,
+   which the SDK fetches at init time. The flag defaults to `false`, so
+   no body is ever attached unless your account has explicitly enabled
+   it.
+2. **HTTP error status.** The body is only attached when the span's
+   HTTP status is in `[400..599]`. A successful response (2xx/3xx)
+   never leaks even if an upstream adapter populated the internal
+   attribute.
+3. **Adapter-supplied body.** The exporter does not read response
+   bodies itself. An adapter (e.g., a future tRPC handler wrapper) sets
+   the body on `glasstrace.internal.response_body`; the exporter
+   promotes it to the public `glasstrace.error.response_body` attribute
+   only when the gates above pass.
+
+Before promotion, the body is sanitized to redact common secret
+patterns — Bearer tokens, JWT-shaped tokens, Glasstrace API keys
+(`gt_dev_*` / `gt_anon_*`), AWS access-key prefixes (`AKIA…` /
+`ASIA…`), and generic `apikey`/`secret`/`password`/`token` key-value
+pairs — and truncated to 4096 UTF-8 bytes with a `...[truncated]`
+marker appended when truncation fires. Truncation respects codepoint
+boundaries so multi-byte characters are never split mid-sequence.
+
+If your account does not enable the flag, the SDK ships zero response
+body data. If your account enables the flag but a span never carries
+the internal attribute (no adapter set it), the public attribute is
+still absent. The default is "off, twice".
+
 ## Browser-extension discovery
 
 `glasstrace init` writes a small static file at
@@ -306,6 +349,40 @@ edge code, but every runtime function that produces or consumes them is
 Node-only, so the practical signal is the same: reach for these from
 your build pipeline, not from a request handler.
 
+#### Why is X Node-only?
+
+Two mechanisms together produce the runtime split:
+
+1. **Conditional exports in `packages/sdk/package.json`** make
+   `@glasstrace/sdk/node` resolvable only under Node's `node` export
+   condition. Workerd, Vercel Edge, browsers, and any other runtime
+   that does not set the `node` condition fail at module resolution
+   rather than at evaluation. That is what keeps any given symbol off
+   the edge surface once it lives under `/node`.
+2. **The edge-bundle gate** (`packages/sdk/scripts/check-edge-bundle.mjs`)
+   then guarantees the *opposite* direction: the main edge bundle
+   (`dist/edge-entry.*`) is scanned for any reference to the Node
+   `process` global or any Node built-in specifier (`node:fs`, bare
+   `fs`, `fs/promises`, and so on), and the build fails if any are
+   found. So a symbol that reaches for `process` or a Node built-in
+   cannot accidentally end up on the edge side.
+
+The gate is scope-aware about shadowing — a local binding named
+`process` does not trip it — but it is deliberately not
+control-flow-aware: a `process.env.X` read or a static `require("fs")`
+keeps a symbol on the Node-only side even when the read is wrapped in
+`typeof process !== "undefined"` or in a `try { ... } catch` guard. A
+`typeof` guard means "this module reaches for `process`", and an
+edge-safe module should not reach for `process` at all.
+
+This is by design. Per the SDK-033 strict-gate policy, the contract
+"this bundle passes the gate" must imply "this bundle is safe in any
+edge runtime", and that implication only holds if the gate refuses
+guards rather than trusting them. If you need a symbol that is currently
+on the Node-only side to become edge-safe, the right move is to remove
+the `process` and Node built-in reaches from the symbol's transitive
+closure, not to add a runtime guard.
+
 ## Security
 
 The SDK transmits your API key exclusively via the `Authorization: Bearer`

package/dist/{chunk-DIM4JRXM.js → chunk-2M57EO6U.js}

@@ -1,6 +1,6 @@
 import {
   NEXT_CONFIG_NAMES
-} from "./chunk-7SZQN6IU.js";
+} from "./chunk-NB7GJE4S.js";
 
 // src/cli/monorepo.ts
 import * as fs from "node:fs";
@@ -239,4 +239,4 @@ export {
   findNextJsApps,
   parsePnpmWorkspaceYaml
 };
-//# sourceMappingURL=chunk-DIM4JRXM.js.map
+//# sourceMappingURL=chunk-2M57EO6U.js.map

package/dist/{chunk-Y26HJUPD.js → chunk-FGDS33I2.js}

@@ -33,16 +33,17 @@ import {
   performInit,
   recordSpansDropped,
   recordSpansExported
-} from "./chunk-MXDZHFJQ.js";
+} from "./chunk-JKI4OCFV.js";
 import {
   isAnonymousMode,
   isProductionDisabled,
   resolveConfig
 } from "./chunk-VUZCLMIX.js";
 import {
+  atomicWriteFileSync,
   getOrCreateAnonKey,
   readAnonKey
-} from "./chunk-P22UQ2OJ.js";
+} from "./chunk-TWTWRJ25.js";
 import {
   GLASSTRACE_ATTRIBUTE_NAMES,
   deriveSessionId
@@ -137,6 +138,126 @@ function classifyFetchTarget(url) {
   return "unknown";
 }
 
+// src/error-response-body.ts
+var ERROR_RESPONSE_BODY_MAX_BYTES = 4096;
+var ERROR_RESPONSE_BODY_TRUNCATION_MARKER = "...[truncated]";
+var REDACTED = "[REDACTED]";
+var ERROR_STATUS_MIN = 400;
+var ERROR_STATUS_MAX = 599;
+function isHttpErrorStatus(status) {
+  let numeric;
+  if (typeof status === "number") {
+    numeric = status;
+  } else if (typeof status === "string" && status.length > 0) {
+    numeric = Number(status);
+  } else {
+    return false;
+  }
+  if (!Number.isFinite(numeric)) return false;
+  return numeric >= ERROR_STATUS_MIN && numeric <= ERROR_STATUS_MAX;
+}
+var REDACTION_PATTERNS = [
+  // Order matters: redact specific token shapes BEFORE the generic
+  // key=value catcher so a literal `Bearer eyJ…` collapses into a single
+  // [REDACTED] and the JWT regex does not separately match the suffix.
+  {
+    name: "bearer",
+    // Case-insensitive on the scheme: HTTP frameworks and proxies
+    // round-trip the auth scheme with inconsistent casing
+    // (`Bearer`, `bearer`, `BEARER`), and a real token leaks just as
+    // badly under any of them.
+    pattern: /\bBearer\s+[A-Za-z0-9._\-+/=]+/gi
+  },
+  {
+    name: "jwt",
+    // Three base64url segments separated by dots. Real JWTs encode at
+    // minimum a small JSON header in the first segment, which alone is
+    // typically ≥10 chars after base64url; a 16-char floor avoids false
+    // positives on dotted text like a stack-trace frame
+    // (`react.dom.server`) while still catching every real JWT we have
+    // seen in the wild. Anchored with word boundaries on both sides so
+    // a 3-dot semantic version like "next@15.4.1.2" does not match.
+    pattern: /\b[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g
+  },
+  {
+    name: "glasstrace-api-key",
+    // gt_dev_* and gt_anon_* keys are >=24 chars of [A-Za-z0-9].
+    pattern: /\bgt_(?:dev|anon)_[A-Za-z0-9]{16,}\b/g
+  },
+  {
+    name: "aws-access-key",
+    // 20-char prefix-fixed identifier.
+    pattern: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g
+  },
+  {
+    name: "key-value-secret-quoted",
+    // Quoted-string variant: (key) [:=] "<value>". The value runs to
+    // the next unescaped closing quote so a multi-word secret like
+    // `password="my secret phrase"` is fully consumed instead of
+    // splitting at the first space and leaving the tail visible.
+    // The leading `(?<![A-Za-z0-9_])` prevents matching inside
+    // identifiers like `passwordless`. The trailing `"?` after the
+    // keyword absorbs the closing quote in JSON-style `"apikey":
+    // "value"` so the colon is still seen as the separator.
+    pattern: /(?<![A-Za-z0-9_])(?:api[_-]?key|apikey|secret|password|token)"?\s*[:=]\s*"(?:[^"\\]|\\.)*"/gi
+  },
+  {
+    name: "key-value-secret-bare",
+    // Unquoted variant: (key) [:=] <bare-value>. The bare value
+    // capture stops at common JSON/text delimiters so we redact only
+    // the value, not surrounding structure. Listed AFTER the quoted
+    // variant so a quoted value's surrounding `"` are consumed by
+    // the first pattern and we never fall through here for a quoted
+    // secret.
+    pattern: /(?<![A-Za-z0-9_])(?:api[_-]?key|apikey|secret|password|token)"?\s*[:=]\s*[^\s,;}\]"]+/gi
+  }
+];
+function sanitizeErrorResponseBody(body) {
+  let out = body;
+  for (const { pattern } of REDACTION_PATTERNS) {
+    out = out.replace(pattern, REDACTED);
+  }
+  return out;
+}
+function truncateErrorResponseBody(body) {
+  const encoder = new TextEncoder();
+  const encoded = encoder.encode(body);
+  if (encoded.byteLength <= ERROR_RESPONSE_BODY_MAX_BYTES) {
+    return body;
+  }
+  let cut = ERROR_RESPONSE_BODY_MAX_BYTES;
+  let scan = cut - 1;
+  while (scan >= 0 && (encoded[scan] & 192) === 128) {
+    scan -= 1;
+  }
+  if (scan >= 0) {
+    const leading = encoded[scan];
+    let expected = 1;
+    if ((leading & 128) === 0) {
+      expected = 1;
+    } else if ((leading & 224) === 192) {
+      expected = 2;
+    } else if ((leading & 240) === 224) {
+      expected = 3;
+    } else if ((leading & 248) === 240) {
+      expected = 4;
+    }
+    if (scan + expected > cut) {
+      cut = scan;
+    }
+  }
+  const decoder = new TextDecoder("utf-8", { fatal: false });
+  const sliced = encoded.subarray(0, cut);
+  const decoded = decoder.decode(sliced);
+  return decoded + ERROR_RESPONSE_BODY_TRUNCATION_MARKER;
+}
+function prepareErrorResponseBody(body) {
+  if (body.length === 0) return null;
+  if (body.trim().length === 0) return null;
+  const sanitized = sanitizeErrorResponseBody(body);
+  return truncateErrorResponseBody(sanitized);
+}
+
 // src/enriching-exporter.ts
 var ATTR = GLASSTRACE_ATTRIBUTE_NAMES;
 var API_KEY_PENDING = "pending";
@@ -365,7 +486,14 @@ var GlasstraceExporter = class {
       if (this.getConfig().errorResponseBodies) {
         const responseBody = attrs["glasstrace.internal.response_body"];
         if (typeof responseBody === "string") {
-          extra[ATTR.ERROR_RESPONSE_BODY] = responseBody.slice(0, 500);
+          const enrichedStatus = extra[ATTR.HTTP_STATUS_CODE];
+          const effectiveStatus = typeof enrichedStatus === "number" ? enrichedStatus : statusCode;
+          if (isHttpErrorStatus(effectiveStatus)) {
+            const prepared = prepareErrorResponseBody(responseBody);
+            if (prepared !== null) {
+              extra[ATTR.ERROR_RESPONSE_BODY] = prepared;
+            }
+          }
         }
       }
       const spanAny = span;
@@ -3931,7 +4059,7 @@ function registerHeartbeatShutdownHook(config, anonKey, sdkVersion) {
 }
 
 // src/runtime-state.ts
-import { writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { mkdirSync } from "node:fs";
 import { join } from "node:path";
 var _projectRoot = null;
 var _sdkVersion = "unknown";
@@ -3983,12 +4111,10 @@ function writeStateNow() {
     };
     const dir = join(_projectRoot, ".glasstrace");
     const filePath = join(dir, "runtime-state.json");
-    const tmpPath = join(dir, "runtime-state.json.tmp");
     mkdirSync(dir, { recursive: true, mode: 448 });
-    writeFileSync(tmpPath, JSON.stringify(runtimeState, null, 2) + "\n", {
+    atomicWriteFileSync(filePath, JSON.stringify(runtimeState, null, 2) + "\n", {
       mode: 384
     });
-    renameSync(tmpPath, filePath);
   } catch (err) {
     sdkLog(
       "warn",
@@ -4027,7 +4153,7 @@ function registerGlasstrace(options) {
     setCoreState(CoreState.REGISTERING);
     startRuntimeStateWriter({
       projectRoot: process.cwd(),
-      sdkVersion: "1.1.1"
+      sdkVersion: "1.1.3"
     });
     const config = resolveConfig(options);
     if (config.verbose) {
@@ -4193,8 +4319,8 @@ async function backgroundInit(config, anonKeyForInit, generation) {
   if (config.verbose) {
     console.info("[glasstrace] Background init firing.");
   }
-  const healthReport = collectHealthReport("1.1.1");
-  const initResult = await performInit(config, anonKeyForInit, "1.1.1", healthReport);
+  const healthReport = collectHealthReport("1.1.3");
+  const initResult = await performInit(config, anonKeyForInit, "1.1.3", healthReport);
   if (generation !== registrationGeneration) return;
   const currentState = getCoreState();
   if (currentState === CoreState.SHUTTING_DOWN || currentState === CoreState.SHUTDOWN) {
@@ -4217,7 +4343,7 @@ async function backgroundInit(config, anonKeyForInit, generation) {
   }
   maybeInstallConsoleCapture();
   if (didLastInitSucceed()) {
-    startHeartbeat(config, anonKeyForInit, "1.1.1", generation, (newApiKey, accountId) => {
+    startHeartbeat(config, anonKeyForInit, "1.1.3", generation, (newApiKey, accountId) => {
       setAuthState(AuthState.CLAIMING);
       emitLifecycleEvent("auth:claim_started", { accountId });
       setResolvedApiKey(newApiKey);
@@ -4566,4 +4692,4 @@ export {
   withGlasstraceConfig,
   captureError
 };
-//# sourceMappingURL=chunk-Y26HJUPD.js.map
+//# sourceMappingURL=chunk-FGDS33I2.js.map