@astrasyncai/verification-gateway 5.18.0 → 5.19.0

package/dist/bin/astrasync-guard.js

@@ -24,9 +24,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/cli/guard.ts
-var fs = __toESM(require("fs"));
-var os = __toESM(require("os"));
-var path = __toESM(require("path"));
+var fs2 = __toESM(require("fs"));
+var os2 = __toESM(require("os"));
+var path2 = __toESM(require("path"));
 var readline = __toESM(require("readline"));
 
 // ../../node_modules/js-yaml/dist/js-yaml.mjs
@@ -3129,115 +3129,115 @@ function validatePolicy(policy) {
   }
   return { valid: errors.length === 0, errors };
 }
-function validatePurpose(purpose, path2) {
+function validatePurpose(purpose, path3) {
   const errors = [];
   if (!purpose || typeof purpose !== "object") {
-    return [{ path: path2, message: "purpose must be an object" }];
+    return [{ path: path3, message: "purpose must be an object" }];
   }
   const p = purpose;
   if (typeof p.id !== "string" || !p.id) {
-    errors.push({ path: `${path2}.id`, message: "id is required and must be a non-empty string" });
+    errors.push({ path: `${path3}.id`, message: "id is required and must be a non-empty string" });
   }
   if (typeof p.allowed !== "boolean") {
-    errors.push({ path: `${path2}.allowed`, message: "allowed is required and must be a boolean" });
+    errors.push({ path: `${path3}.allowed`, message: "allowed is required and must be a boolean" });
   }
   if (p.targets !== void 0 && !isStringArray(p.targets)) {
-    errors.push({ path: `${path2}.targets`, message: "targets must be an array of strings" });
+    errors.push({ path: `${path3}.targets`, message: "targets must be an array of strings" });
   }
   if (p.blockedPatterns !== void 0 && !isStringArray(p.blockedPatterns)) {
     errors.push({
-      path: `${path2}.blockedPatterns`,
+      path: `${path3}.blockedPatterns`,
       message: "blockedPatterns must be an array of strings"
     });
   }
   if (p.requiresApproval !== void 0 && typeof p.requiresApproval !== "boolean") {
     errors.push({
-      path: `${path2}.requiresApproval`,
+      path: `${path3}.requiresApproval`,
       message: "requiresApproval must be a boolean"
     });
   }
   return errors;
 }
-function validateScope(scope, path2) {
+function validateScope(scope, path3) {
   const errors = [];
   if (typeof scope !== "object" || scope === null) {
-    return [{ path: path2, message: "scope must be an object" }];
+    return [{ path: path3, message: "scope must be an object" }];
   }
   const s = scope;
   for (const field of ["allowedDomains", "blockedDomains", "blockedResources"]) {
     if (s[field] !== void 0 && !isStringArray(s[field])) {
-      errors.push({ path: `${path2}.${field}`, message: `${field} must be an array of strings` });
+      errors.push({ path: `${path3}.${field}`, message: `${field} must be an array of strings` });
     }
   }
   return errors;
 }
-function validateLimits(limits, path2) {
+function validateLimits(limits, path3) {
   const errors = [];
   if (typeof limits !== "object" || limits === null) {
-    return [{ path: path2, message: "limits must be an object" }];
+    return [{ path: path3, message: "limits must be an object" }];
   }
   const l = limits;
   if (l.autonomousThreshold !== void 0 && typeof l.autonomousThreshold !== "number") {
     errors.push({
-      path: `${path2}.autonomousThreshold`,
+      path: `${path3}.autonomousThreshold`,
       message: "autonomousThreshold must be a number"
     });
   }
   if (l.maxTransactionAmount !== void 0 && typeof l.maxTransactionAmount !== "number") {
     errors.push({
-      path: `${path2}.maxTransactionAmount`,
+      path: `${path3}.maxTransactionAmount`,
       message: "maxTransactionAmount must be a number"
     });
   }
   if (typeof l.autonomousThreshold === "number" && typeof l.maxTransactionAmount === "number" && l.autonomousThreshold > l.maxTransactionAmount) {
     errors.push({
-      path: `${path2}.autonomousThreshold`,
+      path: `${path3}.autonomousThreshold`,
       message: "autonomousThreshold (Autonomous Limit) must be <= maxTransactionAmount (Hard Limit)"
     });
   }
   if (l.maxRequestsPerHour !== void 0 && typeof l.maxRequestsPerHour !== "number") {
     errors.push({
-      path: `${path2}.maxRequestsPerHour`,
+      path: `${path3}.maxRequestsPerHour`,
       message: "maxRequestsPerHour must be a number"
     });
   }
   if (l.currency !== void 0 && typeof l.currency !== "string") {
-    errors.push({ path: `${path2}.currency`, message: "currency must be a string" });
+    errors.push({ path: `${path3}.currency`, message: "currency must be a string" });
   }
   return errors;
 }
-function validateRiskThresholds(thresholds, path2) {
+function validateRiskThresholds(thresholds, path3) {
   const errors = [];
   if (typeof thresholds !== "object" || thresholds === null) {
-    return [{ path: path2, message: "riskThresholds must be an object" }];
+    return [{ path: path3, message: "riskThresholds must be an object" }];
   }
   const t = thresholds;
   for (const range of ["autoAllow", "requireApproval", "autoBlock"]) {
     if (!t[range] || typeof t[range] !== "object") {
       errors.push({
-        path: `${path2}.${range}`,
+        path: `${path3}.${range}`,
         message: `${range} is required and must be an object with min and max`
       });
       continue;
     }
     const r = t[range];
     if (typeof r.min !== "number" || typeof r.max !== "number") {
-      errors.push({ path: `${path2}.${range}`, message: `${range} must have numeric min and max` });
+      errors.push({ path: `${path3}.${range}`, message: `${range} must have numeric min and max` });
     } else if (r.min > r.max) {
-      errors.push({ path: `${path2}.${range}`, message: `${range}.min must be <= ${range}.max` });
+      errors.push({ path: `${path3}.${range}`, message: `${range}.min must be <= ${range}.max` });
     }
   }
   if (isValidThresholdShape(t)) {
     const thresholdObj = t;
     if (thresholdObj.autoAllow.max + 1 !== thresholdObj.requireApproval.min) {
       errors.push({
-        path: `${path2}`,
+        path: `${path3}`,
         message: `Gap between autoAllow.max (${thresholdObj.autoAllow.max}) and requireApproval.min (${thresholdObj.requireApproval.min}). Ranges must be contiguous.`
       });
     }
     if (thresholdObj.requireApproval.max + 1 !== thresholdObj.autoBlock.min) {
       errors.push({
-        path: `${path2}`,
+        path: `${path3}`,
         message: `Gap between requireApproval.max (${thresholdObj.requireApproval.max}) and autoBlock.min (${thresholdObj.autoBlock.min}). Ranges must be contiguous.`
       });
     }
@@ -3597,8 +3597,8 @@ ${category.label}
   async runAndSave(outputPath) {
     const policy = await this.run();
     const yaml2 = toYaml(policy);
-    const fs2 = await import("fs");
-    fs2.writeFileSync(outputPath, yaml2, "utf-8");
+    const fs3 = await import("fs");
+    fs3.writeFileSync(outputPath, yaml2, "utf-8");
     this.print(`
 Policy saved to ${outputPath}`);
     this.print("   AstraSync Local Guard is now protecting your agent.\n");
@@ -3713,7 +3713,7 @@ Policy saved to ${outputPath}`);
 };
 
 // src/version.ts
-var SDK_VERSION = "5.18.0";
+var SDK_VERSION = "5.19.0";
 
 // src/http.ts
 var SDK_USER_AGENT = `astrasync-sdk/${SDK_VERSION}`;
@@ -4772,7 +4772,12 @@ function getCacheKey(request2, counterpartyId) {
     // its start_checkout quote was served the cached quote-leg grant (no
     // settlementOutcome) and never reached the backend. Same F-A1-07 bug class.
     request2.commercePhase || "",
-    request2.checkoutSessionId || ""
+    request2.checkoutSessionId || "",
+    // 5.19.0: a route_config purpose claim is checked server-side against
+    // the stored rule for this method + path, so it changes the verdict.
+    request2.purposeSource || "",
+    request2.requestMethod || "",
+    request2.requestPath || ""
   ].join("|");
 }
 function getCachedResult(request2, counterpartyId) {
@@ -4946,6 +4951,11 @@ async function callVerifyAccessAPI(config, request2) {
   if (requestData.buyerEmail) body.buyerEmail = requestData.buyerEmail;
   if (requestData.commerceArtifacts) body.commerceArtifacts = requestData.commerceArtifacts;
   if (requestData.attemptId) body.attemptId = requestData.attemptId;
+  if (requestData.purposeSource) body.purposeSource = requestData.purposeSource;
+  if (requestData.agentArtifacts) body.agentArtifacts = requestData.agentArtifacts;
+  if (requestData.metadata) body.metadata = requestData.metadata;
+  if (requestData.requestMethod) body.requestMethod = requestData.requestMethod;
+  if (requestData.requestPath) body.requestPath = requestData.requestPath;
   if (requestData.considerationSet) body.considerationSet = requestData.considerationSet;
   body.sdkVersion = SDK_VERSION;
   if (requestData.callerMetadata || requestData.clientIp || requestData.userAgent) {
@@ -5135,9 +5145,18 @@ async function verify(config, request2, options) {
   if (!apiResponse.access?.allowed) {
     const aggregatedFailures = apiResponse.access?.failures;
     const idVerifiedFromBackend = apiResponse.verificationContext?.idVerified === true && !aggregatedFailures?.some((f) => REJECTED_IDENTITY_DIMENSIONS.has(f.dimension));
+    const denyAgent = idVerifiedFromBackend && apiResponse.agent ? {
+      astraId: apiResponse.agent.astraId,
+      name: apiResponse.agent.name,
+      trustScore: apiResponse.agent.trustScore,
+      trustLevel: getTrustLevel(apiResponse.agent.trustScore),
+      blockchainAnchored: apiResponse.agent.blockchainStatus === "anchored",
+      status: apiResponse.agent.agentStatus
+    } : void 0;
     const result2 = {
       identityVerified: idVerifiedFromBackend,
       policyAllowed: false,
+      ...denyAgent && { agent: denyAgent },
       // 3.6.0: the server now emits top-level denialReasons on every deny
       // path — prefer it verbatim; the failure-message reconstruction remains
       // as the fallback for older backends.
@@ -5283,6 +5302,9 @@ var MAX_TOTAL_BYTES = 16 * 1024;
 // src/adapters/commerce-detect.ts
 var MAX_BODY_BYTES = 64 * 1024;
 
+// src/adapters/routes-cache.ts
+var DEFAULT_ROUTES_REFRESH_MS = 5 * 60 * 1e3;
+
 // src/edge-config.ts
 var DEFAULT_EDGE_CONFIG = Object.freeze({
   version: 1,
@@ -5524,9 +5546,6 @@ var BeaconBuffer = class {
 };
 var beaconBuffer = new BeaconBuffer();
 
-// src/adapters/express.ts
-var DEFAULT_ROUTES_REFRESH_MS = 5 * 60 * 1e3;
-
 // src/adapters/nextjs.ts
 var DEFAULT_ROUTES_REFRESH_MS2 = 5 * 60 * 1e3;
 
@@ -5612,6 +5631,25 @@ var import_jose2 = require("jose");
 // src/idempotency/index.ts
 var DEFAULT_IDEMPOTENCY_TTL_MS = 24 * 60 * 60 * 1e3;
 
+// src/ucp/approval-events.ts
+var MemorySeenEvents = class {
+  constructor(max = 1e4) {
+    this.max = max;
+    this.ids = /* @__PURE__ */ new Set();
+  }
+  async has(eventId) {
+    return this.ids.has(eventId);
+  }
+  async add(eventId) {
+    if (this.ids.size >= this.max) {
+      const first = this.ids.values().next().value;
+      if (first !== void 0) this.ids.delete(first);
+    }
+    this.ids.add(eventId);
+  }
+};
+var defaultSeen = new MemorySeenEvents();
+
 // src/payments/kyapay.ts
 var import_jose4 = require("jose");
 
@@ -5651,7 +5689,9 @@ function toDecision(result) {
   if (result.identityVerified && result.policyAllowed) {
     return {
       recommendation: "ALLOW",
-      reason: result.agent?.trustScore ? `Verified (trust score ${result.agent.trustScore})` : "Verified",
+      // 5.19.0: the score is on `trustScore` for the merchant; `reason` is
+      // text a merchant may relay to the agent, so it never embeds the number.
+      reason: "Verified",
       trustScore: result.agent?.trustScore,
       sessionId: "sessionId" in result ? result.sessionId : void 0
     };
@@ -6574,29 +6614,29 @@ function loadEnrolment(paths) {
     [paths.machineDevice, "machine"],
     [paths.userDevice, "user"]
   ];
-  for (const [path2, scope] of candidates) {
-    if (!(0, import_fs6.existsSync)(path2)) continue;
+  for (const [path3, scope] of candidates) {
+    if (!(0, import_fs6.existsSync)(path3)) continue;
     try {
-      const parsed = JSON.parse((0, import_fs6.readFileSync)(path2, "utf-8"));
+      const parsed = JSON.parse((0, import_fs6.readFileSync)(path3, "utf-8"));
       if (isEnrolment(parsed)) return { enrolment: parsed, scope };
     } catch {
     }
-    return { corrupt: true, path: path2 };
+    return { corrupt: true, path: path3 };
   }
   return null;
 }
-function writeFileMode(path2, content, mode) {
-  (0, import_fs6.mkdirSync)((0, import_path5.dirname)(path2), { recursive: true, mode: 448 });
-  (0, import_fs6.writeFileSync)(path2, content, { encoding: "utf-8", mode });
+function writeFileMode(path3, content, mode) {
+  (0, import_fs6.mkdirSync)((0, import_path5.dirname)(path3), { recursive: true, mode: 448 });
+  (0, import_fs6.writeFileSync)(path3, content, { encoding: "utf-8", mode });
   try {
-    (0, import_fs6.chmodSync)(path2, mode);
+    (0, import_fs6.chmodSync)(path3, mode);
   } catch {
   }
 }
 function saveEnrolment(paths, enrolment, scope) {
-  const path2 = scope === "machine" ? paths.machineDevice : paths.userDevice;
-  writeFileMode(path2, JSON.stringify(enrolment, null, 2), scope === "machine" ? 420 : 384);
-  return path2;
+  const path3 = scope === "machine" ? paths.machineDevice : paths.userDevice;
+  writeFileMode(path3, JSON.stringify(enrolment, null, 2), scope === "machine" ? 420 : 384);
+  return path3;
 }
 function readCachedPolicies(paths) {
   const out = [];
@@ -6918,12 +6958,12 @@ var MANAGED_SETTINGS_LOCATIONS = {
     win32: "%ProgramData%\\OpenAI\\Codex\\requirements.toml"
   }
 };
-function managedHookCommand(target, os2) {
+function managedHookCommand(target, os3) {
   const bin = target === "claude" ? "astrasync-claude-hook" : "astrasync-codex-hook";
-  if (os2 === "win32") return `"C:\\Program Files\\nodejs\\${bin}.cmd"`;
+  if (os3 === "win32") return `"C:\\Program Files\\nodejs\\${bin}.cmd"`;
   return `/usr/local/bin/${bin}`;
 }
-function buildClaudeManagedSettings(os2) {
+function buildClaudeManagedSettings(os3) {
   return {
     allowManagedHooksOnly: true,
     env: { ASTRASYNC_FLEET_REQUIRED: "1" },
@@ -6931,7 +6971,7 @@ function buildClaudeManagedSettings(os2) {
       PreToolUse: [
         {
           matcher: HOOK_MATCHER,
-          hooks: [{ type: "command", command: managedHookCommand("claude", os2), timeout: 10 }]
+          hooks: [{ type: "command", command: managedHookCommand("claude", os3), timeout: 10 }]
         }
       ]
     },
@@ -6941,11 +6981,11 @@ function buildClaudeManagedSettings(os2) {
 function tomlString(value) {
   return JSON.stringify(value);
 }
-function buildCodexRequirementsToml(os2) {
-  const command = os2 === "win32" ? `set ASTRASYNC_FLEET_REQUIRED=1&& ${managedHookCommand("codex", os2)}` : `ASTRASYNC_FLEET_REQUIRED=1 ${managedHookCommand("codex", os2)}`;
+function buildCodexRequirementsToml(os3) {
+  const command = os3 === "win32" ? `set ASTRASYNC_FLEET_REQUIRED=1&& ${managedHookCommand("codex", os3)}` : `ASTRASYNC_FLEET_REQUIRED=1 ${managedHookCommand("codex", os3)}`;
   return [
     "# AstraSync Local Guard \u2014 managed hook (generated by `astrasync guard managed-settings --codex`)",
-    `# Install at: ${MANAGED_SETTINGS_LOCATIONS.codex[os2]}`,
+    `# Install at: ${MANAGED_SETTINGS_LOCATIONS.codex[os3]}`,
     "allow_managed_hooks_only = true",
     "",
     "[features]",
@@ -6965,14 +7005,14 @@ function buildCodexRequirementsToml(os2) {
 function buildManagedSettingsFiles(targets) {
   const out = [];
   for (const target of targets) {
-    for (const os2 of ["darwin", "linux", "win32"]) {
-      const content = target === "claude" ? `${JSON.stringify(buildClaudeManagedSettings(os2), null, 2)}
-` : buildCodexRequirementsToml(os2);
+    for (const os3 of ["darwin", "linux", "win32"]) {
+      const content = target === "claude" ? `${JSON.stringify(buildClaudeManagedSettings(os3), null, 2)}
+` : buildCodexRequirementsToml(os3);
       out.push({
         target,
-        os: os2,
-        installPath: MANAGED_SETTINGS_LOCATIONS[target][os2],
-        fileName: `${target}-${os2}-${target === "claude" ? "managed-settings.json" : "requirements.toml"}`,
+        os: os3,
+        installPath: MANAGED_SETTINGS_LOCATIONS[target][os3],
+        fileName: `${target}-${os3}-${target === "claude" ? "managed-settings.json" : "requirements.toml"}`,
         content
       });
     }
@@ -7151,10 +7191,170 @@ function createLocalCert(hosts, days = 30) {
 ${b64}
 -----END CERTIFICATE-----
 `,
-    key: privateKey.export({ type: "pkcs8", format: "pem" }).toString()
+    key: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+    spkiSha256: import_node_crypto5.default.createHash("sha256").update(spki).digest("base64")
   };
 }
 
+// src/fleet/open-browser.ts
+var import_node_child_process = require("child_process");
+var import_node_fs = __toESM(require("fs"));
+var import_node_os = __toESM(require("os"));
+var import_node_path = __toESM(require("path"));
+function isWsl(env = process.env, platform2 = process.platform, readVersion = () => import_node_fs.default.readFileSync("/proc/version", "utf8")) {
+  if (platform2 !== "linux") return false;
+  if (env.WSL_DISTRO_NAME) return true;
+  try {
+    return /microsoft/i.test(readVersion());
+  } catch {
+    return false;
+  }
+}
+var MAC_PATHS = [
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+  "/Applications/Chromium.app/Contents/MacOS/Chromium"
+];
+var LINUX_NAMES = [
+  "google-chrome",
+  "google-chrome-stable",
+  "chromium",
+  "chromium-browser",
+  "microsoft-edge"
+];
+var WSL_WINDOWS_PATHS = [
+  "/mnt/c/Program Files/Google/Chrome/Application/chrome.exe",
+  "/mnt/c/Program Files (x86)/Google/Chrome/Application/chrome.exe",
+  "/mnt/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe",
+  "/mnt/c/Program Files/Microsoft/Edge/Application/msedge.exe"
+];
+function findChromium(env = process.env, platform2 = process.platform, exists = (p) => import_node_fs.default.existsSync(p), wsl = isWsl(env, platform2), listDir = (dir) => import_node_fs.default.readdirSync(dir)) {
+  let candidates;
+  if (platform2 === "darwin") {
+    candidates = MAC_PATHS;
+  } else if (platform2 === "win32") {
+    const bases = [
+      env.ProgramFiles,
+      env["ProgramFiles(x86)"],
+      env.LOCALAPPDATA ?? env.LocalAppData
+    ].filter((b) => !!b);
+    candidates = [
+      ...bases.map((b) => import_node_path.default.win32.join(b, "Google", "Chrome", "Application", "chrome.exe")),
+      ...bases.map((b) => import_node_path.default.win32.join(b, "Microsoft", "Edge", "Application", "msedge.exe"))
+    ];
+  } else {
+    const dirs = (env.PATH ?? "").split(":").filter(Boolean);
+    candidates = LINUX_NAMES.flatMap((n) => dirs.map((d) => import_node_path.default.posix.join(d, n)));
+    const cache2 = env.PLAYWRIGHT_BROWSERS_PATH ?? (env.HOME ? `${env.HOME}/.cache/ms-playwright` : "");
+    if (cache2) {
+      let builds = [];
+      try {
+        builds = listDir(cache2).filter((d) => /^chromium-\d+$/.test(d));
+      } catch {
+      }
+      builds.sort((a, b) => Number(b.split("-")[1]) - Number(a.split("-")[1]));
+      for (const b of builds)
+        candidates.push(
+          import_node_path.default.posix.join(cache2, b, "chrome-linux64", "chrome"),
+          import_node_path.default.posix.join(cache2, b, "chrome-linux", "chrome")
+        );
+    }
+    if (wsl) candidates = [...candidates, ...WSL_WINDOWS_PATHS];
+  }
+  return candidates.find((c) => exists(c)) ?? null;
+}
+function isWindowsExeFromWsl(browserPath) {
+  return /^\/mnt\/[a-z]\//i.test(browserPath) && /\.exe$/i.test(browserPath);
+}
+function browserName(browserPath) {
+  const b = browserPath.toLowerCase();
+  if (b.includes("edge")) return "Edge";
+  if (b.includes("chromium")) return "Chromium";
+  return "Chrome";
+}
+function profileDirFor(proxyPort) {
+  return import_node_path.default.join(import_node_os.default.tmpdir(), `astrasync-agent-browser-${proxyPort}`);
+}
+function windowsProfileDir(profileDir) {
+  if (/^\/mnt\/[a-z]\//i.test(profileDir)) {
+    try {
+      return (0, import_node_child_process.execFileSync)("wslpath", ["-w", profileDir], { encoding: "utf8" }).trim();
+    } catch {
+    }
+  }
+  return `C:\\Temp\\${import_node_path.default.basename(profileDir)}`;
+}
+function certFlag(certSpki) {
+  return `--ignore-certificate-errors-spki-list=${certSpki}`;
+}
+var CERT_FLAG_NOTE = "Chrome shows a warning bar about the --ignore-certificate-errors-spki-list flag. That is expected (it trusts only this proxy's certificate); close the bar.";
+function launchBrowser(browserPath, proxyPort, url, certSpki, profileDir = profileDirFor(proxyPort), onError) {
+  const dir = isWindowsExeFromWsl(browserPath) ? windowsProfileDir(profileDir) : profileDir;
+  const child = (0, import_node_child_process.spawn)(
+    browserPath,
+    [
+      `--proxy-server=http://127.0.0.1:${proxyPort}`,
+      certFlag(certSpki),
+      `--user-data-dir=${dir}`,
+      "--no-first-run",
+      "--new-window",
+      url
+    ],
+    { detached: true, stdio: "ignore" }
+  );
+  child.on("error", (err) => onError?.(err));
+  child.unref();
+  return child;
+}
+function browserCommand(platform2, port, url, certSpki, wsl = false) {
+  const proxy = `--proxy-server="http://127.0.0.1:${port}" ${certFlag(certSpki)}`;
+  if (platform2 === "win32" || wsl) {
+    return `& "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" ${proxy} --user-data-dir="$env:TEMP\\astrasync-agent-${port}" '${url}'`;
+  }
+  const exe = platform2 === "darwin" ? '"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"' : "google-chrome";
+  return `${exe} ${proxy} --user-data-dir="\${TMPDIR:-/tmp}/astrasync-agent-${port}" '${url}'`;
+}
+function browserCommandLines(platform2, port, url, certSpki, wsl = isWsl(process.env, platform2)) {
+  if (wsl) {
+    return [
+      "  In PowerShell (Windows):",
+      `    ${browserCommand("win32", port, url, certSpki)}`,
+      "  Or inside WSL (with Chromium installed):",
+      `    ${browserCommand("linux", port, url, certSpki)}`,
+      `  ${CERT_FLAG_NOTE}`
+    ];
+  }
+  return [`  ${browserCommand(platform2, port, url, certSpki)}`, `  ${CERT_FLAG_NOTE}`];
+}
+function openThroughProxy(opts) {
+  const log = opts.log ?? ((l) => console.log(l));
+  const platform2 = opts.platform ?? process.platform;
+  const env = opts.env ?? process.env;
+  const wsl = opts.wsl ?? isWsl(env, platform2);
+  const found = opts.find ? opts.find() : findChromium(env, platform2, void 0, wsl);
+  if (!found) {
+    log("No Chrome/Edge/Chromium found. Start one through the proxy with:");
+    for (const l of browserCommandLines(platform2, opts.port, opts.url, opts.certSpki, wsl)) log(l);
+    return false;
+  }
+  (opts.launch ?? launchBrowser)(
+    found,
+    opts.port,
+    opts.url,
+    opts.certSpki,
+    profileDirFor(opts.port),
+    (err) => log(`Couldn't start ${browserName(found)}: ${err.message}`)
+  );
+  log(`Opened ${browserName(found)} through the proxy.`);
+  log(CERT_FLAG_NOTE);
+  if (wsl && isWindowsExeFromWsl(found)) {
+    log(
+      "If the Windows browser can't reach the proxy, install Chromium inside WSL (e.g. npx playwright install chromium)."
+    );
+  }
+  return true;
+}
+
 // src/fleet/browse-proxy.ts
 var HOP_BY_HOP = /* @__PURE__ */ new Set([
   "connection",
@@ -7171,10 +7371,33 @@ function cleanHeaders(h) {
   for (const [k, v] of Object.entries(h)) if (!HOP_BY_HOP.has(k) && v !== void 0) out[k] = v;
   return out;
 }
+function helpPage(port, certSpki) {
+  const proxy = `http://127.0.0.1:${port}`;
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>AstraSync device proxy</title>
+<style>body{font:16px/1.5 system-ui,sans-serif;max-width:40rem;margin:2rem auto;padding:0 1rem}code{background:#f2f2f2;padding:0 .25rem}</style>
+</head><body>
+<h1>AstraSync device proxy</h1>
+<p>This is AstraSync's Local Guard device proxy. It only works as a browser proxy &mdash; it isn't a page to open.</p>
+<h2>Open the sign-in link</h2>
+<ul>
+<li>Run <code>astrasync guard browse --open</code> &mdash; it opens a browser that goes through this proxy.</li>
+<li>Or start Chrome, Edge or Chromium with <code>--proxy-server=${proxy} ${certFlag(certSpki)}</code> and a separate profile (<code>--user-data-dir=&lt;an empty folder&gt;</code>), then open the sign-in link in it.</li>
+</ul>
+<p>Chrome shows a warning bar about that flag. That is expected &mdash; it trusts only this proxy&apos;s certificate &mdash; so close the bar.</p>
+<p>Keep <code>astrasync guard browse</code> running while you use the session.</p>
+</body></html>
+`;
+}
 async function startBrowseProxy(opts) {
   const hosts = new Set(opts.hosts.map((h) => h.toLowerCase()));
   const deviceHeader = `Device ${opts.deviceCredential}`;
-  const { cert, key } = createLocalCert([...hosts]);
+  const { cert, key, spkiSha256 } = createLocalCert([...hosts]);
+  const sockets = /* @__PURE__ */ new Set();
+  const track = (s) => {
+    sockets.add(s);
+    s.once("close", () => sockets.delete(s));
+  };
   function forward(req, res, target) {
     const headers = cleanHeaders(req.headers);
     headers["x-astra-device"] = deviceHeader;
@@ -7226,6 +7449,7 @@ async function startBrowseProxy(opts) {
       },
       onConnect
     ) : import_node_net.default.connect(target.port, target.host, onConnect);
+    track(upstream);
     upstream.on("error", () => socket.destroy());
     socket.on("error", () => upstream.destroy());
   }
@@ -7257,6 +7481,16 @@ async function startBrowseProxy(opts) {
     });
   });
   const server = import_node_http.default.createServer((req, res) => {
+    if ((req.url ?? "").startsWith("/")) {
+      if (req.url === "/favicon.ico") {
+        res.writeHead(404).end();
+        return;
+      }
+      const listening = server.address()?.port ?? 0;
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      res.end(helpPage(listening, spkiSha256));
+      return;
+    }
     let url;
     try {
       url = new URL(req.url ?? "");
@@ -7349,18 +7583,22 @@ async function startBrowseProxy(opts) {
       upstream.pipe(socket);
       socket.pipe(upstream);
     });
+    track(upstream);
     upstream.on("error", () => socket.destroy());
     socket.on("error", () => upstream.destroy());
   });
+  server.on("connection", track);
   await new Promise((resolve) => server.listen(opts.port ?? 0, "127.0.0.1", resolve));
   const port = server.address().port;
   return {
     port,
+    certSpki: spkiSha256,
     close: () => new Promise((resolve) => {
       inner.close();
       plainInner.close();
       server.close(() => resolve());
       server.closeAllConnections?.();
+      for (const s of sockets) s.destroy();
     })
   };
 }
@@ -7447,6 +7685,18 @@ async function runBrowse(paths, opts) {
     log(
       `Device proxy: http://127.0.0.1:${proxy.port}  (adds this machine's credential for ${hosts.join(", ")})`
     );
+    if (!opts.open) {
+      log("Open it in a browser through the proxy:");
+      for (const l of browserCommandLines(
+        opts.platform ?? process.platform,
+        proxy.port,
+        openUrl,
+        proxy.certSpki,
+        opts.wsl
+      ))
+        log(l);
+      log("  (or re-run with --open)");
+    }
     log("Playwright:");
     log(
       `  chromium.launch({ proxy: { server: 'http://127.0.0.1:${proxy.port}' } }) + newContext({ ignoreHTTPSErrors: true })`
@@ -7486,7 +7736,7 @@ async function cmdSetup() {
 }
 async function cmdUpgrade() {
   const policyPath = process.argv[4] || DEFAULT_POLICY_PATH;
-  if (!fs.existsSync(policyPath)) {
+  if (!fs2.existsSync(policyPath)) {
     console.error(`No policy file found at ${policyPath}`);
     console.error('Run "astrasync guard setup" first to create a policy.');
     process.exit(1);
@@ -7514,13 +7764,13 @@ async function cmdUpgrade() {
         prompt: (message) => prompt.question(message),
         print: (message) => console.log(message),
         writeConfig: async (filePath, content) => {
-          const dir = path.dirname(filePath);
-          if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-          fs.writeFileSync(filePath, content, "utf-8");
+          const dir = path2.dirname(filePath);
+          if (!fs2.existsSync(dir)) fs2.mkdirSync(dir, { recursive: true });
+          fs2.writeFileSync(filePath, content, "utf-8");
         },
         readConfig: async (filePath) => {
           try {
-            return fs.readFileSync(filePath, "utf-8");
+            return fs2.readFileSync(filePath, "utf-8");
           } catch {
             return null;
           }
@@ -7541,13 +7791,13 @@ async function cmdStart() {
   let gatewayConfig;
   const upgraded = await isUpgraded(DEFAULT_CONFIG_DIR, async (p) => {
     try {
-      return fs.readFileSync(p, "utf-8");
+      return fs2.readFileSync(p, "utf-8");
     } catch {
       return null;
     }
   });
   if (upgraded) {
-    const config = JSON.parse(fs.readFileSync(`${DEFAULT_CONFIG_DIR}/config`, "utf-8"));
+    const config = JSON.parse(fs2.readFileSync(`${DEFAULT_CONFIG_DIR}/config`, "utf-8"));
     gatewayConfig = {
       mode: config.mode,
       apiBaseUrl: config.platformUrl ? `${config.platformUrl}/api/v1` : void 0,
@@ -7555,7 +7805,7 @@ async function cmdStart() {
     };
     console.log(`[AstraSync] Starting in ${config.mode} mode (agent: ${config.agentId})`);
   } else {
-    if (!fs.existsSync(policyPath)) {
+    if (!fs2.existsSync(policyPath)) {
       console.error(`No policy file found at ${policyPath}`);
       console.error('Run "astrasync guard setup" first.');
       process.exit(1);
@@ -7592,7 +7842,7 @@ async function cmdStatus() {
   const policyPath = process.argv[4] || DEFAULT_POLICY_PATH;
   const upgraded = await isUpgraded(DEFAULT_CONFIG_DIR, async (p) => {
     try {
-      return fs.readFileSync(p, "utf-8");
+      return fs2.readFileSync(p, "utf-8");
     } catch {
       return null;
     }
@@ -7602,7 +7852,7 @@ async function cmdStatus() {
     console.log(`  ${line}`);
   }
   if (upgraded) {
-    const config = JSON.parse(fs.readFileSync(`${DEFAULT_CONFIG_DIR}/config`, "utf-8"));
+    const config = JSON.parse(fs2.readFileSync(`${DEFAULT_CONFIG_DIR}/config`, "utf-8"));
     console.log(`  Mode:     ${config.mode}`);
     console.log(`  Agent:    ${config.agentId}`);
     console.log(`  Platform: ${config.platformUrl}`);
@@ -7610,7 +7860,7 @@ async function cmdStatus() {
   } else {
     console.log("  Mode:     local (free tier)");
   }
-  if (fs.existsSync(policyPath)) {
+  if (fs2.existsSync(policyPath)) {
     const parsed = parseFile(policyPath);
     if (parsed.validation.valid && parsed.policy) {
       const p = parsed.policy;
@@ -7635,7 +7885,7 @@ async function cmdCheck() {
     (a) => !a.startsWith("--") && a !== "guard" && a !== "check" && a !== process.argv[0] && a !== process.argv[1]
   ) || DEFAULT_POLICY_PATH;
   const trigger = process.argv.find((a) => a.startsWith("--trigger="))?.split("=")[1] || "pre-push";
-  if (!fs.existsSync(policyPath)) {
+  if (!fs2.existsSync(policyPath)) {
     console.log("[AstraSync] No policy file \u2014 skipping check");
     process.exit(0);
   }
@@ -7647,9 +7897,9 @@ async function cmdCheck() {
   }
   let enforcement = "warn";
   const configPath = `${DEFAULT_CONFIG_DIR}/config`;
-  if (fs.existsSync(configPath)) {
+  if (fs2.existsSync(configPath)) {
     try {
-      const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+      const config = JSON.parse(fs2.readFileSync(configPath, "utf-8"));
       enforcement = config.gitTriggerEnforcement || "warn";
     } catch {
     }
@@ -7712,8 +7962,8 @@ async function cmdUninstallHooks() {
   }
 }
 function resolveClaudeHookCommand() {
-  const sibling = path.join(__dirname, "astrasync-claude-hook.js");
-  if (fs.existsSync(sibling)) {
+  const sibling = path2.join(__dirname, "astrasync-claude-hook.js");
+  if (fs2.existsSync(sibling)) {
     return `"${process.execPath}" "${sibling}"`;
   }
   return "astrasync-claude-hook";
@@ -7729,19 +7979,19 @@ function parseClaudeCodeFlags() {
   };
 }
 function claudeCodePaths(project) {
-  const root = project ? process.cwd() : os.homedir();
+  const root = project ? process.cwd() : os2.homedir();
   return {
-    settingsPath: path.join(root, ".claude", "settings.json"),
-    astrasyncDir: path.join(root, ".astrasync")
+    settingsPath: path2.join(root, ".claude", "settings.json"),
+    astrasyncDir: path2.join(root, ".astrasync")
   };
 }
 async function cmdInstallClaudeCode() {
   const flags = parseClaudeCodeFlags();
   const { settingsPath, astrasyncDir } = claudeCodePaths(flags.project);
-  const policyPath = flags.policyOverride || path.join(astrasyncDir, "policy.yaml");
-  const guardJsonPath = path.join(astrasyncDir, "guard.json");
+  const policyPath = flags.policyOverride || path2.join(astrasyncDir, "policy.yaml");
+  const guardJsonPath = path2.join(astrasyncDir, "guard.json");
   console.log("\nAstraSync Local Guard for Claude Code \u2014 install\n");
-  if (fs.existsSync(policyPath)) {
+  if (fs2.existsSync(policyPath)) {
     console.log(`  Policy:   using existing ${policyPath}`);
     if (ensureGuardSelfProtection(policyPath)) {
       console.log("            added guard self-protection patterns to file.write");
@@ -7749,7 +7999,7 @@ async function cmdInstallClaudeCode() {
   } else if (flags.wizard) {
     const prompt = createPrompt();
     try {
-      fs.mkdirSync(path.dirname(policyPath), { recursive: true });
+      fs2.mkdirSync(path2.dirname(policyPath), { recursive: true });
       const wizard = new SetupWizard(prompt);
       await wizard.runAndSave(policyPath);
     } finally {
@@ -7758,17 +8008,17 @@ async function cmdInstallClaudeCode() {
     ensureGuardSelfProtection(policyPath);
     console.log(`  Policy:   created via wizard at ${policyPath}`);
   } else {
-    fs.mkdirSync(path.dirname(policyPath), { recursive: true });
-    fs.writeFileSync(policyPath, toYaml(buildDefaultClaudeCodePolicy()), "utf-8");
+    fs2.mkdirSync(path2.dirname(policyPath), { recursive: true });
+    fs2.writeFileSync(policyPath, toYaml(buildDefaultClaudeCodePolicy()), "utf-8");
     console.log(`  Policy:   default coding-agent policy written to ${policyPath}`);
     console.log("            (re-run with --wizard for the interactive setup instead)");
   }
-  if (!fs.existsSync(guardJsonPath)) {
+  if (!fs2.existsSync(guardJsonPath)) {
     const guardSettings = {
       posture: flags.active ? "active" : "passive",
       governMcp: false
     };
-    fs.writeFileSync(guardJsonPath, `${JSON.stringify(guardSettings, null, 2)}
+    fs2.writeFileSync(guardJsonPath, `${JSON.stringify(guardSettings, null, 2)}
 `, "utf-8");
     console.log(
       `  Guard:    ${guardJsonPath} (posture: ${guardSettings.posture}, governMcp: false)`
@@ -7798,7 +8048,7 @@ async function cmdInstallClaudeCode() {
   }
   console.log("\n  Next steps:");
   console.log("    1. Start a NEW Claude Code session (settings load at startup).");
-  console.log(`    2. Watch decisions: tail -f ${path.join(astrasyncDir, "traces")}/*.jsonl`);
+  console.log(`    2. Watch decisions: tail -f ${path2.join(astrasyncDir, "traces")}/*.jsonl`);
   console.log(`    3. When the traces look right, set "posture": "active" in ${guardJsonPath}`);
   console.log("       to enforce (denies block, approvals use Claude Code's own prompt).");
   console.log('    4. To govern MCP tools too, set "governMcp": true and add');
@@ -7828,26 +8078,26 @@ async function cmdUninstallClaudeCode() {
   );
 }
 function resolveCodexHookCommand() {
-  const sibling = path.join(__dirname, "astrasync-codex-hook.js");
-  if (fs.existsSync(sibling)) {
+  const sibling = path2.join(__dirname, "astrasync-codex-hook.js");
+  if (fs2.existsSync(sibling)) {
     return `"${process.execPath}" "${sibling}"`;
   }
   return "astrasync-codex-hook";
 }
 function codexPaths(project) {
-  const root = project ? process.cwd() : os.homedir();
+  const root = project ? process.cwd() : os2.homedir();
   return {
-    hooksPath: path.join(root, ".codex", "hooks.json"),
-    astrasyncDir: path.join(root, ".astrasync")
+    hooksPath: path2.join(root, ".codex", "hooks.json"),
+    astrasyncDir: path2.join(root, ".astrasync")
   };
 }
 async function cmdInstallCodex() {
   const flags = parseClaudeCodeFlags();
   const { hooksPath, astrasyncDir } = codexPaths(flags.project);
-  const policyPath = flags.policyOverride || path.join(astrasyncDir, "policy.yaml");
-  const guardJsonPath = path.join(astrasyncDir, "guard.json");
+  const policyPath = flags.policyOverride || path2.join(astrasyncDir, "policy.yaml");
+  const guardJsonPath = path2.join(astrasyncDir, "guard.json");
   console.log("\nAstraSync Local Guard for Codex CLI \u2014 install\n");
-  if (fs.existsSync(policyPath)) {
+  if (fs2.existsSync(policyPath)) {
     console.log(`  Policy:   using existing ${policyPath} (shared across adapters)`);
     if (ensureGuardSelfProtection(policyPath)) {
       console.log("            added guard self-protection patterns to file.write");
@@ -7855,7 +8105,7 @@ async function cmdInstallCodex() {
   } else if (flags.wizard) {
     const prompt = createPrompt();
     try {
-      fs.mkdirSync(path.dirname(policyPath), { recursive: true });
+      fs2.mkdirSync(path2.dirname(policyPath), { recursive: true });
       const wizard = new SetupWizard(prompt);
       await wizard.runAndSave(policyPath);
     } finally {
@@ -7864,17 +8114,17 @@ async function cmdInstallCodex() {
     ensureGuardSelfProtection(policyPath);
     console.log(`  Policy:   created via wizard at ${policyPath}`);
   } else {
-    fs.mkdirSync(path.dirname(policyPath), { recursive: true });
-    fs.writeFileSync(policyPath, toYaml(buildDefaultClaudeCodePolicy()), "utf-8");
+    fs2.mkdirSync(path2.dirname(policyPath), { recursive: true });
+    fs2.writeFileSync(policyPath, toYaml(buildDefaultClaudeCodePolicy()), "utf-8");
     console.log(`  Policy:   default coding-agent policy written to ${policyPath}`);
     console.log("            (re-run with --wizard for the interactive setup instead)");
   }
-  if (!fs.existsSync(guardJsonPath)) {
+  if (!fs2.existsSync(guardJsonPath)) {
     const guardSettings = {
       posture: flags.active ? "active" : "passive",
       governMcp: false
     };
-    fs.writeFileSync(guardJsonPath, `${JSON.stringify(guardSettings, null, 2)}
+    fs2.writeFileSync(guardJsonPath, `${JSON.stringify(guardSettings, null, 2)}
 `, "utf-8");
     console.log(
       `  Guard:    ${guardJsonPath} (posture: ${guardSettings.posture}, governMcp: false)`
@@ -7893,7 +8143,7 @@ async function cmdInstallCodex() {
   }
   console.log("\n  Next steps:");
   console.log("    1. Start a NEW Codex session (hooks load at startup; /hooks to inspect).");
-  console.log(`    2. Watch decisions: tail -f ${path.join(astrasyncDir, "traces")}/*.jsonl`);
+  console.log(`    2. Watch decisions: tail -f ${path2.join(astrasyncDir, "traces")}/*.jsonl`);
   console.log(`    3. When the traces look right, set "posture": "active" in ${guardJsonPath}.`);
   console.log("       Denies block; approvals fall through to Codex's own prompt \u2014");
   console.log("       except in dontAsk/bypassPermissions modes, where they deny.");
@@ -7918,13 +8168,13 @@ function printCodexStatus() {
     const { hooksPath, astrasyncDir } = codexPaths(scope === "project");
     let hookInstalled = false;
     try {
-      const content = fs.readFileSync(hooksPath, "utf-8");
+      const content = fs2.readFileSync(hooksPath, "utf-8");
       hookInstalled = content.includes(ASTRASYNC_CODEX_HOOK_MARKER);
     } catch {
     }
     if (hookInstalled) {
-      const policyPath = path.join(astrasyncDir, "policy.yaml");
-      const policy = fs.existsSync(policyPath) ? `policy: ${policyPath}` : "policy: missing";
+      const policyPath = path2.join(astrasyncDir, "policy.yaml");
+      const policy = fs2.existsSync(policyPath) ? `policy: ${policyPath}` : "policy: missing";
       console.log(`  Codex CLI (${scope}): hook installed, ${policy}`);
     }
   }
@@ -7934,24 +8184,24 @@ function printClaudeCodeStatus() {
     const { settingsPath, astrasyncDir } = claudeCodePaths(scope === "project");
     let hookInstalled = false;
     try {
-      const content = fs.readFileSync(settingsPath, "utf-8");
+      const content = fs2.readFileSync(settingsPath, "utf-8");
       hookInstalled = content.includes(ASTRASYNC_HOOK_MARKER);
     } catch {
     }
-    const policyPath = path.join(astrasyncDir, "policy.yaml");
-    const guardJsonPath = path.join(astrasyncDir, "guard.json");
+    const policyPath = path2.join(astrasyncDir, "policy.yaml");
+    const guardJsonPath = path2.join(astrasyncDir, "guard.json");
     let posture = "";
-    if (fs.existsSync(guardJsonPath)) {
+    if (fs2.existsSync(guardJsonPath)) {
       try {
-        const settings = JSON.parse(fs.readFileSync(guardJsonPath, "utf-8"));
+        const settings = JSON.parse(fs2.readFileSync(guardJsonPath, "utf-8"));
         posture = settings.posture ? `, posture: ${settings.posture}` : "";
       } catch {
         posture = ", guard.json unreadable";
       }
     }
-    if (hookInstalled || fs.existsSync(policyPath)) {
+    if (hookInstalled || fs2.existsSync(policyPath)) {
       const hook = hookInstalled ? "hook installed" : "hook NOT installed";
-      const policy = fs.existsSync(policyPath) ? `policy: ${policyPath}` : "policy: missing";
+      const policy = fs2.existsSync(policyPath) ? `policy: ${policyPath}` : "policy: missing";
       console.log(`  Claude Code (${scope}): ${hook}, ${policy}${posture}`);
     }
   }
@@ -7997,14 +8247,21 @@ async function cmdFleetStatus() {
 async function cmdBrowse() {
   try {
     const port = flagValue("--port");
-    const { proxy } = await runBrowse(fleetPaths(), {
+    const open = process.argv.includes("--open");
+    const { proxy, openUrl } = await runBrowse(fleetPaths(), {
       checkpoint: flagValue("--checkpoint") ?? "",
       slug: flagValue("--slug") ?? "",
       upstream: flagValue("--upstream"),
       port: port ? Number(port) : void 0,
-      extraHosts: flagValue("--host") ? [flagValue("--host")] : []
+      extraHosts: flagValue("--host") ? [flagValue("--host")] : [],
+      open
     });
+    if (open) openThroughProxy({ port: proxy.port, url: openUrl, certSpki: proxy.certSpki });
+    let stopping = false;
     const stop = async () => {
+      if (stopping) process.exit(0);
+      stopping = true;
+      setTimeout(() => process.exit(0), 2e3).unref();
       await proxy.close();
       process.exit(0);
     };
@@ -8039,7 +8296,7 @@ async function cmdGitRoute() {
 }
 async function cmdGitCredential() {
   const action = process.argv[process.argv.indexOf("git-credential") + 1] ?? "";
-  const input = fs.readFileSync(0, "utf-8");
+  const input = fs2.readFileSync(0, "utf-8");
   process.stdout.write(runGitCredential(action, input));
 }
 async function cmdManagedSettings() {
@@ -8143,8 +8400,9 @@ async function main() {
         "  browse                 Sign an agent in to your dashboard from this machine and"
       );
       console.log(
-        "                         run its device proxy (--checkpoint <url> --slug <agent>)"
+        "                         run its device proxy (--checkpoint <url> --slug <agent>;"
       );
+      console.log("                          --open to start a browser through the proxy)");
       console.log("  enroll <token>         Enrol this machine in your organisation fleet");
       console.log("                         (--api-base-url <url>, --system for machine scope)");
       console.log("  fleet-status           Show fleet enrolment, signed policy and heartbeat");