@skyramp/mcp 0.4.4 → 0.5.0-rc.10

package/node_modules/playwright/lib/mcp/skyramp/dataSafetyGuard.js

@@ -0,0 +1,822 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var dataSafetyGuard_exports = {};
+__export(dataSafetyGuard_exports, {
+  DataSafetyGuard: () => DataSafetyGuard,
+  TEARDOWN_DELETE_TIMEOUT_MS: () => TEARDOWN_DELETE_TIMEOUT_MS,
+  blockReason: () => blockReason,
+  compileOffLimits: () => compileOffLimits,
+  matchesOffLimits: () => matchesOffLimits,
+  parseDataSafetyConfig: () => parseDataSafetyConfig,
+  renderCappedList: () => renderCappedList,
+  teardownCredentialHeaders: () => teardownCredentialHeaders,
+  writeLedgerFile: () => writeLedgerFile
+});
+module.exports = __toCommonJS(dataSafetyGuard_exports);
+var import_fs = __toESM(require("fs"));
+const MODES = ["strict", "readonly", "off"];
+const TEARDOWN_DELETE_TIMEOUT_MS = 1e4;
+function writeLedgerFile(file, json) {
+  const temp = `${file}.${process.pid}.tmp`;
+  try {
+    import_fs.default.writeFileSync(temp, json);
+    import_fs.default.renameSync(temp, file);
+  } catch (e) {
+    import_fs.default.rmSync(temp, { force: true });
+    throw e;
+  }
+}
+const SAFE_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS"]);
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const NUMERIC_RE = /^\d+$/;
+const OBJECTID_RE = /^[0-9a-f]{24}$/i;
+const AUTH_PATH_RE = /\/(login|logout|signin|sign-in|signup|sign-up|auth|oauth|token|sessions?)(\/|$)/i;
+const AUTH_TOKEN_SEGMENT_RE = /^(login|logout|signin|sign-in|signup|sign-up|auth|oauth|token|sessions?)$/i;
+const GRAPHQL_PATH_RE = /(^|\/)(graphql(\.json)?|gql)(\/|$)/i;
+function isAuthExemptPath(pathName) {
+  const segs = pathName.split("/").filter(Boolean);
+  if (!segs.length)
+    return false;
+  const last = segs[segs.length - 1];
+  if (AUTH_TOKEN_SEGMENT_RE.test(last))
+    return true;
+  return segs.length === 2 && AUTH_TOKEN_SEGMENT_RE.test(segs[0]);
+}
+const READONLY_LOGIN_STEP_RE = /^(login|logout|signin|sign-in|sign_in|signout|sign-out|sign_out|authenticate)$/i;
+const READONLY_AUTH_WORD_RE = /^(token|refresh|session|sessions|callback|authorize|auth|mfa|otp|2fa|totp)$/i;
+const READONLY_AUTH_PREFIX_RE = /^(api|v\d+(\.\d+)?|auth|oauth2?|connect|openid-connect|login-actions|sso|identity|idp|user|users|account|accounts|login|session|sessions|token)$/i;
+function isReadonlyAuthPath(pathName) {
+  const segs = pathName.split("/").filter(Boolean);
+  if (!segs.length || segs.some(isIdShaped))
+    return false;
+  const last = segs[segs.length - 1];
+  if (READONLY_LOGIN_STEP_RE.test(last))
+    return true;
+  if (!READONLY_AUTH_WORD_RE.test(last))
+    return false;
+  return segs.length === 1 || READONLY_AUTH_PREFIX_RE.test(segs[segs.length - 2]);
+}
+const ID_FIELDS = ["id", "uuid", "_id", "pk"];
+const UNSAFE_ID_RE = /[/\\?#\x00-\x20\x7f]/;
+const UNSAFE_ID_ENCODED_RE = /%2f|%5c|%2e/i;
+const MAX_ID_LENGTH = 512;
+function isValidId(id) {
+  if (id === "" || id === "." || id === "..")
+    return false;
+  if (id.length > MAX_ID_LENGTH)
+    return false;
+  if (UNSAFE_ID_RE.test(id) || UNSAFE_ID_ENCODED_RE.test(id))
+    return false;
+  return true;
+}
+function isIdShaped(seg) {
+  return NUMERIC_RE.test(seg) || UUID_RE.test(seg) || OBJECTID_RE.test(seg);
+}
+const MAX_EXTRACT_DEPTH = 20;
+const UNSAFE_NUMERIC_ID = Symbol("unsafe-numeric-id");
+function extractCreatedId(parsed, depth = 0, derivedIdFields = []) {
+  if (depth > MAX_EXTRACT_DEPTH)
+    return null;
+  if (Array.isArray(parsed))
+    return parsed.length === 1 ? extractCreatedId(parsed[0], depth + 1, derivedIdFields) : null;
+  if (parsed && typeof parsed === "object") {
+    const obj = parsed;
+    for (const f of [...ID_FIELDS, ...derivedIdFields]) {
+      const v = obj[f];
+      if (v === void 0 || v === null)
+        continue;
+      if (typeof v === "string")
+        return v;
+      if (typeof v === "number")
+        return Number.isSafeInteger(v) ? String(v) : UNSAFE_NUMERIC_ID;
+      if (typeof v === "object" && !Array.isArray(v)) {
+        const found = extractCreatedId(v, depth + 1, derivedIdFields);
+        if (found !== null)
+          return found;
+      }
+    }
+    if (depth < 2) {
+      for (const key of ["data", "result"]) {
+        const nested = obj[key];
+        if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+          const found = extractCreatedId(nested, depth + 1, derivedIdFields);
+          if (found !== null)
+            return found;
+        }
+      }
+    }
+    return null;
+  }
+  return null;
+}
+function collectionDerivedIdFields(collectionPathname) {
+  const segs = collectionPathname.split("/").filter(Boolean);
+  const collection = segs[segs.length - 1] ?? "";
+  if (collection.length < 3 || !/s$/i.test(collection) || !/^[a-z][a-z0-9_-]*$/i.test(collection))
+    return [];
+  const singular = collection.slice(0, -1).toLowerCase();
+  return [`${singular}_id`, `${singular}Id`];
+}
+function renderCappedList(items, tailWord, cap = 10) {
+  const shown = items.slice(0, cap);
+  const remaining = items.length - shown.length;
+  const lines = [...shown];
+  if (remaining > 0)
+    lines.push(`\u2026and ${remaining} more ${tailWord}`);
+  return lines.join("\n");
+}
+function globToRegExp(glob) {
+  const DOUBLE_STAR = "\0";
+  const escaped = glob.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, DOUBLE_STAR).replace(/\*/g, "[^/]*").replace(/\u0000/g, ".*");
+  return new RegExp(`^${escaped}$`, "i");
+}
+function compileOffLimits(patterns) {
+  const compiled = patterns.map(compileOffLimitsPattern);
+  return (url) => compiled.some((re) => re.test(url));
+}
+function matchesOffLimits(url, patterns) {
+  return compileOffLimits(patterns)(url);
+}
+function isUnmatchablePattern(pattern) {
+  return !pattern.includes("://") && !pattern.startsWith("*");
+}
+function compileOffLimitsPattern(pattern) {
+  if (isUnmatchablePattern(pattern))
+    process.stderr.write(`[skyramp] Data safety: offLimits pattern "${pattern}" has no scheme/host and will match nothing \u2014 patterns match the full URL (e.g. "**/admin/**")
+`);
+  if (pattern.endsWith("/**")) {
+    const root = pattern.slice(0, -3);
+    return new RegExp(`(?:${globToRegExp(pattern).source})|(?:${globToRegExp(root).source})`, "i");
+  }
+  return globToRegExp(pattern);
+}
+function warnInvalidConfig(reason, outcome) {
+  process.stderr.write(`[skyramp] Data safety: invalid config (${reason}) \u2014 ${outcome}
+`);
+}
+function validateConfig(parsed) {
+  if (!parsed || typeof parsed !== "object") {
+    warnInvalidConfig("config is not an object", "failing closed to mode=strict");
+    return freezeConfig({ mode: "strict", offLimits: [] });
+  }
+  const p = parsed;
+  const errors = [];
+  let mode;
+  if (MODES.includes(p.mode)) {
+    mode = p.mode;
+  } else {
+    mode = "strict";
+    warnInvalidConfig(`mode must be "strict", "readonly" or "off", got ${JSON.stringify(p.mode)}`, "failing closed to mode=strict");
+  }
+  let offLimits = [];
+  if (typeof p.offLimits === "string") {
+    offLimits = [p.offLimits];
+    warnInvalidConfig("offLimits must be an array of strings, got one string", "using it as one pattern");
+  } else if (Array.isArray(p.offLimits)) {
+    offLimits = p.offLimits.filter((x) => typeof x === "string");
+    if (offLimits.length !== p.offLimits.length)
+      errors.push(`offLimits has ${p.offLimits.length - offLimits.length} entries that are not strings`);
+  } else if (p.offLimits !== void 0 && p.offLimits !== null) {
+    errors.push("offLimits must be an array of strings");
+  }
+  const unmatchable = offLimits.filter(isUnmatchablePattern);
+  if (unmatchable.length)
+    errors.push(`offLimits patterns match the full URL; start each with a scheme (https://) or *: ${unmatchable.map((x) => JSON.stringify(x)).join(", ")}`);
+  let ledgerDir;
+  if (typeof p.ledgerDir === "string" && p.ledgerDir.length > 0)
+    ledgerDir = p.ledgerDir;
+  else if (p.ledgerDir !== void 0 && p.ledgerDir !== null)
+    errors.push("ledgerDir must be a non-empty string");
+  const startupError = errors.length ? `Data safety config is invalid: ${errors.join("; ")}.` : void 0;
+  if (startupError)
+    warnInvalidConfig(errors.join("; "), "every tool call will fail until the config is fixed");
+  return freezeConfig({ mode, offLimits, ...ledgerDir ? { ledgerDir } : {}, ...startupError ? { startupError } : {} });
+}
+function freezeConfig(config) {
+  return Object.freeze({ ...config, offLimits: Object.freeze([...config.offLimits]) });
+}
+function parseDataSafetyConfig(options, envValue) {
+  if (options !== void 0)
+    return validateConfig(options);
+  if (!envValue)
+    return freezeConfig({ mode: "off", offLimits: [] });
+  const bareMode = envValue.trim().toLowerCase();
+  if (MODES.includes(bareMode))
+    return freezeConfig({ mode: bareMode, offLimits: [] });
+  let parsed;
+  try {
+    parsed = JSON.parse(envValue);
+  } catch (e) {
+    warnInvalidConfig(`malformed SKYRAMP_DATA_SAFETY JSON: ${String(e)}`, "failing closed to mode=strict");
+    return freezeConfig({ mode: "strict", offLimits: [] });
+  }
+  return validateConfig(parsed);
+}
+class DataSafetyGuard {
+  /**
+   * nextLedgerPath, when given, names a fresh ledger file for each new
+   * session after resetSession() — so a ledger in a caller-read directory
+   * keeps the finished session's record instead of being overwritten.
+   */
+  constructor(config, ledgerPath, _setupCompleted, _nextLedgerPath) {
+    this._setupCompleted = _setupCompleted;
+    this._nextLedgerPath = _nextLedgerPath;
+    // Ownership is URL-scoped: (origin, entity pathname) pairs derived from the
+    // ledgered entityUrls. A bare id is never owned globally — order id 7 must
+    // not grant DELETE /api/users/7, a different origin, or an id a third-party
+    // beacon happened to return (ledger poisoning is contained to the beacon's
+    // own URL).
+    this._ownedEntities = [];
+    this._blocks = [];
+    this._pendingNotices = [];
+    this._entries = [];
+    // 2xx/3xx POST responses where no entity id could be identified — teardown
+    // cannot delete what the ledger never recorded, so this is the audit trail
+    // for entities that may have been created but are otherwise untracked.
+    this._unparsedCreates = [];
+    // Only warn once — a broken ledger path must not spam stderr on every
+    // single request for the rest of the session.
+    this._persistWarned = false;
+    this._persistFailed = false;
+    this._teardownStarted = false;
+    // The credential headers each create was sent with, so teardown can
+    // authenticate the way the app did (a JS-set Authorization header never
+    // reaches the context's cookie jar). Memory only, by design: the ledger
+    // is written to disk, zipped and uploaded, and must never carry a secret.
+    this._teardownHeaders = /* @__PURE__ */ new Map();
+    // Entity URLs (origin + normalized path) that answered 2xx during the
+    // recording. A 404 on teardown means "already gone" only for a URL known
+    // to exist; otherwise it can mean the guard built the wrong delete URL.
+    this._confirmedEntities = /* @__PURE__ */ new Set();
+    // Entries whose teardown DELETE timed out: the server may have deleted
+    // them, which a later 404 must say.
+    this._timedOutDeletes = /* @__PURE__ */ new Set();
+    this.config = Object.isFrozen(config) ? config : freezeConfig(config);
+    this._ledgerPath = ledgerPath;
+    this._offLimits = this.config.offLimits.map(compileOffLimitsPattern);
+  }
+  /** Where the crash-safe ledger is persisted right now. */
+  get ledgerPath() {
+    return this._ledgerPath;
+  }
+  /** Grant session ownership of one entity URL (origin + path scoped). Only a ledger entry grants it. */
+  _addOwnedEntity(entityUrl) {
+    const parsed = tryParseUrl(entityUrl);
+    if (parsed)
+      this._ownedEntities.push({ origin: parsed.origin, pathname: normalizePathname(parsed.pathname) });
+  }
+  get ledger() {
+    return this._entries;
+  }
+  /** Move a ledger entry to another source action, or drop its source action (undefined). */
+  setSourceAction(entry, actionId) {
+    if (!this._entries.includes(entry))
+      return;
+    if (actionId)
+      entry.sourceActionId = actionId;
+    else
+      delete entry.sourceActionId;
+    this._persist();
+  }
+  get unparsedCreates() {
+    return this._unparsedCreates;
+  }
+  /**
+   * requestHeaders: the create request's headers. Only the credential ones
+   * (teardownCredentialHeaders) are kept, in memory, for that entity's
+   * teardown DELETE.
+   */
+  recordResponse(method, url, status, locationHeader, body, contentType, context, requestHeaders) {
+    if (this.config.mode !== "strict")
+      return;
+    if (method.toUpperCase() !== "POST")
+      return;
+    const is2xx = status >= 200 && status < 300;
+    const is3xx = status >= 300 && status < 400;
+    if (!is2xx && !is3xx)
+      return;
+    const pathName = safePathname(url);
+    if (isAuthExemptPath(pathName)) {
+      this.recordUnparsedCreate(url, status, contentType, "auth-exempt");
+      return;
+    }
+    if (GRAPHQL_PATH_RE.test(pathName))
+      return;
+    let entityUrl = null;
+    let id = null;
+    let idSource = null;
+    let unparsedRule;
+    if (locationHeader) {
+      try {
+        const resolved = new URL(locationHeader, url);
+        const requestUrl = new URL(url);
+        if (resolved.origin === requestUrl.origin) {
+          const resolvedPath = normalizePathname(resolved.pathname);
+          const requestPath = normalizePathname(requestUrl.pathname);
+          if (resolvedPath.length > requestPath.length && resolvedPath.startsWith(requestPath + "/")) {
+            const segs = resolvedPath.split("/").filter(Boolean);
+            const lastSeg = segs[segs.length - 1] ?? null;
+            if (lastSeg && isValidId(lastSeg) && isIdShaped(lastSeg)) {
+              resolved.search = "";
+              resolved.hash = "";
+              entityUrl = resolved.toString();
+              id = lastSeg;
+              idSource = "locationHeader";
+            }
+          }
+        }
+      } catch {
+      }
+    }
+    if (is2xx && (!entityUrl || !id) && body) {
+      let parsedBody;
+      let bodyParsed = true;
+      try {
+        parsedBody = JSON.parse(body);
+      } catch {
+        bodyParsed = false;
+      }
+      if (bodyParsed) {
+        let rawId = null;
+        try {
+          const extracted = extractCreatedId(parsedBody, 0, collectionDerivedIdFields(pathName));
+          if (extracted === UNSAFE_NUMERIC_ID)
+            unparsedRule = "unsafe-numeric-id";
+          else
+            rawId = extracted;
+        } catch {
+        }
+        if (rawId !== null && isValidId(rawId)) {
+          try {
+            const collection = new URL(url);
+            collection.search = "";
+            collection.hash = "";
+            const candidate = `${collection.toString().replace(/\/+$/, "")}/${rawId}`;
+            if (isSingleChildPath(new URL(candidate), collection)) {
+              entityUrl = candidate;
+              id = rawId;
+              idSource = "responseBody";
+            }
+          } catch {
+          }
+        }
+      }
+    }
+    if (entityUrl && id && idSource) {
+      this._addOwnedEntity(entityUrl);
+      const entry = {
+        entityUrl,
+        id,
+        method: "POST",
+        createdAt: Date.now(),
+        deleteEndpoint: entityUrl,
+        phase: context.phase,
+        ...context.actionId ? { sourceActionId: context.actionId } : {},
+        idSource,
+        resourceType: context.resourceType,
+        responseStatus: status,
+        // The raw header, only for the branch that used it — a Location the
+        // guard IGNORED (collection-shaped, cross-origin, non-id last
+        // segment) must not leak onto a body-sourced entry.
+        ...idSource === "locationHeader" && locationHeader ? { locationHeader } : {}
+      };
+      this._entries.push(entry);
+      const credentials = teardownCredentialHeaders(requestHeaders);
+      if (credentials)
+        this._teardownHeaders.set(entry, credentials);
+      this._persist();
+      return;
+    }
+    this.recordUnparsedCreate(url, status, contentType, unparsedRule);
+  }
+  /**
+   * Audit a 2xx POST whose created entity could not be identified (or, with
+   * status 0, a create attempt whose route-time fetch never completed — the
+   * request may or may not have reached the server). Deduped on url+status.
+   */
+  recordUnparsedCreate(url, status, contentType, rule) {
+    const existing = this._unparsedCreates.find((u) => u.url === url && u.status === status);
+    if (existing)
+      existing.count = (existing.count ?? 1) + 1;
+    else
+      this._unparsedCreates.push({ url, status, contentType: contentType ?? void 0, count: 1, rule });
+    this._persist();
+  }
+  /**
+   * A non-POST response the recording saw. A 2xx at exactly a ledgered
+   * delete URL, query string included, confirms that URL is the entity's
+   * real address (the page read, changed or deleted it there), so teardown
+   * can trust a later 404. A response with another query
+   * (`/api/items/7?workspace=3`) confirms nothing: on a query-scoped API the
+   * query-less delete URL can name no entity at all.
+   */
+  noteEntityResponse(method, url, status) {
+    if (this.config.mode !== "strict" || method.toUpperCase() === "POST" || status < 200 || status >= 300 || !this._entries.length)
+      return;
+    const key = entityKey(url);
+    if (key && this._entries.some((e) => entityKey(e.deleteEndpoint) === key))
+      this._confirmedEntities.add(key);
+  }
+  /**
+   * True when a request is a strict-mode ledgerable create — the routing
+   * layer captures these bodies synchronously (route.fetch → fulfill) so the
+   * created id can never be lost to a renderer-side navigation racing the
+   * deferred response.text() read.
+   */
+  shouldCaptureCreateBody(method, url) {
+    if (this.config.mode !== "strict" || method.toUpperCase() !== "POST")
+      return false;
+    const pathName = safePathname(url);
+    return !isAuthExemptPath(pathName) && !GRAPHQL_PATH_RE.test(pathName);
+  }
+  classify(method, url, postData) {
+    const m = method.toUpperCase();
+    if (this._offLimits.some((re) => re.test(url)))
+      return "BLOCK_DENYLISTED";
+    if (this.config.mode === "off")
+      return "ALLOW";
+    if (SAFE_METHODS.has(m))
+      return "ALLOW";
+    const target = tryParseUrl(url);
+    if (!target || target.origin === "null")
+      return "BLOCK_FOREIGN_MUTATION";
+    const pathName = target.pathname;
+    if (this.config.mode === "readonly")
+      return m === "POST" && isReadonlyAuthPath(pathName) ? "ALLOW" : "BLOCK_FOREIGN_MUTATION";
+    if (m === "POST") {
+      const foreignSegment = this._foreignEntitySegment(target, pathName);
+      if (isAuthExemptPath(pathName) && !foreignSegment)
+        return "ALLOW";
+      if (AUTH_PATH_RE.test(pathName))
+        return "BLOCK_FOREIGN_MUTATION";
+      if (GRAPHQL_PATH_RE.test(pathName))
+        return isGraphQLMutation(postData) ? "BLOCK_FOREIGN_MUTATION" : "ALLOW";
+      return foreignSegment ? "BLOCK_FOREIGN_MUTATION" : "ALLOW";
+    }
+    const owned = this._isOwnedPath(target.origin, target.pathname);
+    return owned ? "ALLOW" : "BLOCK_FOREIGN_MUTATION";
+  }
+  /**
+   * Detect 3xx responses whose redirect target would have been blocked.
+   * Pre-flight interception of redirect hops is NOT supported by the browser
+   * stack — the network layer auto-follows redirects without re-entering
+   * route handlers (see crNetworkManager.ts:339 "We do not support
+   * intercepting redirects") — so this is detection-only mitigation: the hop
+   * already happened, but the incident lands in notices + ledger blocks
+   * instead of vanishing. 307/308 preserve the request method; 301/302/303
+   * downgrade to GET, so for those only an offLimits target can flag.
+   */
+  noteRedirect(method, url, status, locationHeader) {
+    if (status < 300 || status >= 400 || !locationHeader)
+      return;
+    let target;
+    try {
+      target = new URL(locationHeader, url).toString();
+    } catch {
+      this.recordBlock({
+        url: locationHeader,
+        method: method.toUpperCase(),
+        verdict: "BLOCK_FOREIGN_MUTATION",
+        rule: "post-hoc: unresolvable redirect Location \u2014 hop could not be audited"
+      });
+      return;
+    }
+    const redirectedMethod = status === 307 || status === 308 ? method.toUpperCase() : "GET";
+    const verdict = this.classify(redirectedMethod, target);
+    if (verdict === "ALLOW")
+      return;
+    const why = blockReason(verdict, this.config.mode);
+    this.recordBlock({
+      url: target,
+      method: redirectedMethod,
+      verdict,
+      rule: `post-hoc: redirect (${status} from ${url}) \u2014 ${why}; redirect hops cannot be blocked pre-flight`
+    });
+  }
+  /** URL-scoped ownership: pathname equals a ledgered entity path or is nested under it, same origin. */
+  _isOwnedPath(origin, pathname) {
+    const target = normalizePathname(pathname);
+    return this._ownedEntities.some((o) => o.origin === origin && (target === o.pathname || target.startsWith(o.pathname + "/")));
+  }
+  /**
+   * First path segment that looks like an entity id but is not session-owned.
+   * An id segment counts as owned only in the context of its own entity URL:
+   * the URL prefix up to (and including) the segment must match a ledgered
+   * entityUrl on the same origin — never a bare-id match on another
+   * collection or origin.
+   *
+   * Id-like is numeric | UUID | ObjectId ONLY. An opaque slug is not
+   * id-like even after a plural-looking collection segment: that would
+   * over-block ordinary collection-level actions on slug-addressed
+   * collections (`POST
+   * /api/orders/bulk/cancel`, `/api/teams/members/add`, `/api/settings/
+   * notifications/mark-read` — none of these touch any specific entity), and
+   * a PUT/PATCH/DELETE on a genuinely slug-addressed entity already fails
+   * closed via positive ownership below regardless. Residual accepted gap:
+   * an opaque/slug id in a POST path (`/api/posts/my-first-post/comments`,
+   * `/api/u/aB3xQ/disable`) is not detectable by shape alone — PUT/PATCH/
+   * DELETE on that entity still blocks unless the session owns it.
+   */
+  _foreignEntitySegment(target, pathName) {
+    let prefix = "";
+    const segs = pathName.split("/").filter(Boolean);
+    for (const seg of segs) {
+      prefix += "/" + seg;
+      if (!isIdShaped(seg))
+        continue;
+      if (!this._isOwnedPath(target.origin, prefix))
+        return seg;
+    }
+    return null;
+  }
+  /**
+   * Identical blocks (same method+url+verdict+rule — e.g. an agent
+   * retrying the same blocked request, or a page firing it in a loop) dedupe
+   * into one BlockRecord with an incrementing count instead of spamming the
+   * ledger and the notice text with N copies of the same line. A repeat of
+   * an already-notified block is re-queued (same object, already-bumped
+   * count) so it's still called out again on the next notice read.
+   */
+  recordBlock(rec) {
+    const existing = this._blocks.find((b) => b.method === rec.method && b.url === rec.url && b.verdict === rec.verdict && b.rule === rec.rule);
+    if (existing) {
+      existing.count = (existing.count ?? 1) + 1;
+      if (!this._pendingNotices.includes(existing))
+        this._pendingNotices.push(existing);
+    } else {
+      const withCount = { ...rec, count: 1 };
+      this._blocks.push(withCount);
+      this._pendingNotices.push(withCount);
+    }
+    this._persist();
+  }
+  get blocks() {
+    return this._blocks;
+  }
+  /**
+   * Render at most 10 distinct blocked-request lines (each carrying a
+   * "(×N)" suffix once count > 1), plus a non-counted tail line naming how
+   * many more distinct blocks are pending — the tail deliberately does not
+   * start with the "Blocked by data safety: " prefix testbot counts report
+   * lines by (renderCappedList's contract: the tail is never one of the
+   * counted lines).
+   */
+  consumeBlockNotices() {
+    if (!this._pendingNotices.length)
+      return "";
+    const advice = this.config.mode === "readonly" ? "Do not retry; this environment is read-only." : "Do not retry; use scratch entities you create in this session.";
+    const lines = this._pendingNotices.map((b) => {
+      const countSuffix = b.count && b.count > 1 ? ` (\xD7${b.count})` : "";
+      return `Blocked by data safety: ${b.method} ${b.url} \u2014 ${b.rule}${countSuffix}. ${advice}`;
+    });
+    this._pendingNotices = [];
+    return `
+
+### Data safety
+${renderCappedList(lines, "distinct blocked requests \u2014 see dataSafetyLedger.json.")}`;
+  }
+  ledgerJson(setupCompleted) {
+    return JSON.stringify({ ledgerVersion: 1, mode: this.config.mode, setupCompleted, entries: this._entries, blocks: this._blocks, unparsedCreates: this._unparsedCreates }, null, 2);
+  }
+  /** Write the ledger now, before any event — proof the guard is live for a caller that reads ledgerDir. */
+  flush() {
+    this._persist();
+  }
+  /**
+   * A successful export ends the data-safety session: the next recording in
+   * the same process must not inherit this one's entries, blocks, or owned
+   * entities (cross-recording ledger contamination), and the persisted ledger
+   * file is rewritten to match.
+   */
+  resetSession() {
+    this._entries = [];
+    this._blocks = [];
+    this._pendingNotices = [];
+    this._ownedEntities = [];
+    this._unparsedCreates = [];
+    this._teardownHeaders.clear();
+    this._confirmedEntities.clear();
+    this._timedOutDeletes.clear();
+    this._teardownStarted = false;
+    if (this._nextLedgerPath) {
+      this._ledgerPath = this._nextLedgerPath();
+      return;
+    }
+    this._persist();
+  }
+  /**
+   * Teardown ran for this session (it had entries). Its records are gone, so
+   * the recording can no longer be relabelled, for example by finishing
+   * setup after the fact.
+   */
+  get teardownStarted() {
+    return this._teardownStarted;
+  }
+  /** The last ledger write failed; ensureLedgerWritable() rewrites it in full. */
+  get persistFailed() {
+    return this._persistFailed;
+  }
+  /** Entries not yet confirmed torn down — what a retry would still attempt. */
+  get pendingTeardownCount() {
+    return this._entries.filter((e) => !e.tornDown).length;
+  }
+  async teardown(request) {
+    const result = { deleted: [], leftovers: [] };
+    if (this.config.mode !== "strict")
+      return result;
+    if (this._entries.length)
+      this._teardownStarted = true;
+    for (const entry of [...this._entries].reverse()) {
+      if (entry.tornDown === true)
+        continue;
+      try {
+        const headers = this._teardownHeaders.get(entry);
+        const response = await request.delete(entry.deleteEndpoint, { maxRedirects: 0, timeout: TEARDOWN_DELETE_TIMEOUT_MS, ...headers ? { headers } : {} });
+        const status = response.status();
+        if (status >= 200 && status < 300) {
+          entry.tornDown = true;
+          result.deleted.push(entry);
+        } else if (status === 404 && this._deleteUrlKnownRight(entry)) {
+          entry.tornDown = true;
+          result.deleted.push(entry);
+        } else if (status === 404) {
+          result.leftovers.push({ entry, status: "not-found", ...this._timedOutDeletes.has(entry) ? { error: "an earlier DELETE timed out, so the server may already have deleted it" } : {} });
+        } else if (status >= 300 && status < 400) {
+          const location = response.headers?.()["location"];
+          result.leftovers.push({ entry, status, error: `redirected to ${location ?? "(no Location header)"} \u2014 not followed (maxRedirects: 0)` });
+        } else {
+          result.leftovers.push({ entry, status });
+        }
+      } catch (e) {
+        if (e instanceof Error && e.name === "TimeoutError") {
+          this._timedOutDeletes.add(entry);
+          result.leftovers.push({ entry, status: "error", timedOut: true, error: `${this._safeErrorText(entry, e)} \u2014 the server may have processed it` });
+        } else {
+          result.leftovers.push({ entry, status: "error", error: this._safeErrorText(entry, e) });
+        }
+      }
+      if (entry.tornDown)
+        this._persist();
+    }
+    return result;
+  }
+  /**
+   * A delete URL is known to be right when exactly that URL answered 2xx
+   * during the recording, whatever the id's source: a Location header names
+   * the right URL, but an expired session or credentials that were not
+   * replayed can still answer 404 while the record stays live. The id must
+   * be id-shaped as well: a 404 on a slug-like id is the wrong-URL signal.
+   */
+  _deleteUrlKnownRight(entry) {
+    return isIdShaped(entry.id) && this._confirmedEntities.has(entityKey(entry.deleteEndpoint) ?? "");
+  }
+  /**
+   * The error text of a failed teardown DELETE, safe to show the agent and
+   * to put in a manifest. Playwright appends a call log that prints every
+   * request header, so cut it off, then redact any replayed credential
+   * value that is still in the text.
+   */
+  _safeErrorText(entry, e) {
+    let text = String(e);
+    const callLog = text.indexOf("\nCall log:");
+    if (callLog !== -1)
+      text = text.slice(0, callLog);
+    for (const value of Object.values(this._teardownHeaders.get(entry) ?? {})) {
+      if (value)
+        text = text.split(value).join("<redacted>");
+    }
+    return text.trim();
+  }
+  /**
+   * Write the ledger now and fail if it cannot be written. A caller that
+   * reads ledgerDir has no other record (the staged engine never exports),
+   * so recording must not start without the file.
+   */
+  ensureLedgerWritable() {
+    if (this.config.startupError)
+      throw new Error(this.config.startupError);
+    try {
+      if (this.config.ledgerDir)
+        import_fs.default.mkdirSync(this.config.ledgerDir, { recursive: true });
+      writeLedgerFile(this._ledgerPath, this.ledgerJson(this._setupCompleted()));
+      this._persistFailed = false;
+      this._persistWarned = false;
+    } catch (e) {
+      throw new Error(`Data safety cannot write its ledger to ledgerDir ${this.config.ledgerDir ?? this._ledgerPath}: ${String(e)}`);
+    }
+  }
+  _persist() {
+    try {
+      writeLedgerFile(this._ledgerPath, this.ledgerJson(this._setupCompleted()));
+      this._persistFailed = false;
+      this._persistWarned = false;
+    } catch (e) {
+      this._persistFailed = true;
+      if (!this._persistWarned) {
+        this._persistWarned = true;
+        process.stderr.write(`[skyramp] Data safety: could not persist ledger to ${this._ledgerPath}: ${String(e)}
+`);
+      }
+    }
+  }
+}
+function blockReason(verdict, mode) {
+  if (verdict === "BLOCK_DENYLISTED")
+    return "matches an off-limits pattern";
+  return mode === "readonly" ? "mutation (mode=readonly)" : `foreign entity mutation (mode=${mode})`;
+}
+const CREDENTIAL_HEADER_RE = /^(authorization|proxy-authorization)$|auth|token|session|api[-_]?key|[-_]key$|csrf|xsrf/i;
+const NOT_CREDENTIAL_HEADER_RE = /idempotency/i;
+function teardownCredentialHeaders(headers) {
+  if (!headers)
+    return void 0;
+  const kept = Object.entries(headers).filter(([name]) => name.toLowerCase() !== "cookie" && CREDENTIAL_HEADER_RE.test(name) && !NOT_CREDENTIAL_HEADER_RE.test(name));
+  return kept.length ? Object.fromEntries(kept.map(([name, value]) => [name.toLowerCase(), value])) : void 0;
+}
+function isSingleChildPath(entity, collection) {
+  if (entity.origin !== collection.origin)
+    return false;
+  const parent = normalizePathname(collection.pathname);
+  const child = normalizePathname(entity.pathname);
+  const prefix = parent === "/" ? "/" : parent + "/";
+  return child.startsWith(prefix) && child.length > prefix.length && !child.slice(prefix.length).includes("/");
+}
+function tryParseUrl(url) {
+  try {
+    return new URL(url);
+  } catch {
+    return null;
+  }
+}
+function entityKey(url) {
+  const parsed = tryParseUrl(url);
+  return parsed ? parsed.origin + normalizePathname(parsed.pathname) + parsed.search : void 0;
+}
+function normalizePathname(pathname) {
+  const stripped = pathname.replace(/\/+$/, "");
+  return stripped || "/";
+}
+function safePathname(url) {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return url;
+  }
+}
+function isGraphQLMutation(postData) {
+  if (!postData)
+    return true;
+  try {
+    const body = JSON.parse(postData);
+    const elements = Array.isArray(body) ? body : [body];
+    if (!elements.length)
+      return true;
+    for (const el of elements) {
+      if (!el || typeof el !== "object" || typeof el.query !== "string")
+        return true;
+      if (/\bmutation\b/.test(el.query))
+        return true;
+    }
+    return false;
+  } catch {
+    return true;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DataSafetyGuard,
+  TEARDOWN_DELETE_TIMEOUT_MS,
+  blockReason,
+  compileOffLimits,
+  matchesOffLimits,
+  parseDataSafetyConfig,
+  renderCappedList,
+  teardownCredentialHeaders,
+  writeLedgerFile
+});