@patchstack/connect 0.3.21 → 0.3.23

package/AGENT-INSTALL.md

@@ -73,7 +73,7 @@ This versioned reference ships inside `@patchstack/connect` and documents each s
    <script src="https://cdn.patchstack.com/patchstack-widget.js" data-site-uuid="<SITE_UUID>" defer></script>
    ```
 
-   Framework-specific placement patterns: https://cdn.patchstack.com/llm.html. The site UUID is public by design — it ships in client-side HTML and is not a secret. If the project must not carry the widget, persist `"widget": false` in `.patchstackrc.json`; otherwise the next scan re-adds it.
+   Framework-specific placement patterns: https://cdn.patchstack.com/llm.html. The site UUID is public by design — it ships in client-side HTML and is not a secret. The `apiKey` (also `PATCHSTACK_API_KEY`, WP format `{secret}-{oauth.id}`) is the opposite: server-only, used to authenticate block-log reporting through the existing connector `POST /api/logs/log` so "Threats blocked" fills in the dashboard. Never put `apiKey` in the widget tag, client bundles, or public env vars (`NEXT_PUBLIC_*`, etc.). Prefer `PATCHSTACK_API_KEY` in production; `.patchstackrc.json` is fine for local DX. Opt out of reporting with `PATCHSTACK_TELEMETRY=off`. If the project must not carry the widget, persist `"widget": false` in `.patchstackrc.json`; otherwise the next scan re-adds it.
 
 4. **Install and verify runtime protection:**
 
@@ -98,10 +98,19 @@ This versioned reference ships inside `@patchstack/connect` and documents each s
 
 ## Verifying the install
 
-- `npx @patchstack/connect status` re-prints the site UUID and dashboard URL.
+- `npx @patchstack/connect status` re-prints the site UUID and dashboard URL, and checks whether the site still exists on Patchstack (`Site status: active / removed / could not be verified`).
 - `npx @patchstack/connect protect --check` verifies the runtime guard is connected to the request path.
 - Load the site in a browser — the "Report a vulnerability" button should appear.
 
+## Answering "is Patchstack installed?" / "is Patchstack removed?"
+
+These are **two independent states** — never conflate them:
+
+1. **The site record on Patchstack** (remote). Deleting the site in the dashboard or through the widget's uninstall flow removes it. Reporting stops and the widget stops rendering, but nothing in the project changes.
+2. **The local integration** (this repo): the widget `<script>` tag, `.patchstackrc.json`, the `@patchstack/connect` dependency, the runtime guard files, and the build hooks.
+
+Local files alone cannot tell you whether the site was removed from Patchstack. Run `npx @patchstack/connect status` and read the `Site status` line, then answer with both states. For example, when the site was removed but the local files remain, say: *"The site itself was removed from Patchstack — reporting has stopped and the widget no longer renders. The local integration code (widget tag, `.patchstackrc.json`, the dependency) is still in the project; want me to remove it?"* — not "Patchstack is still installed."
+
 ## Uninstalling
 
 Remove only the pieces that are actually present — check for each first. If none are present, Patchstack isn't installed; report that and stop. If the user asked to remove only one piece (e.g. "just the widget"), remove only that piece.
@@ -111,7 +120,9 @@ Remove only the pieces that are actually present — check for each first. If no
 3. **Remove runtime protection before uninstalling the package.** Delete the connector-managed guard/rules files and remove only their managed imports, middleware registrations, tunnel code, and `#region patchstack…` blocks from the framework/server files. Preserve unrelated middleware and application code. Run `rg "patchstack|x-ps-target"` (or the available equivalent) afterwards and inspect every remaining source hit.
 4. **Remove the hooks from `package.json` scripts.** If a hook was chained (e.g. `"postbuild": "existing-command && patchstack-connect mark-build"`), remove only the `patchstack-connect …` part and keep the rest; if removal leaves a script empty, delete the key.
 5. **Uninstall the package** with the manager matching the lockfile: `npm uninstall` / `pnpm remove` / `yarn remove` / `bun remove` `@patchstack/connect`. Don't hand-edit `node_modules` or the lockfile.
-6. **Delete `.patchstackrc.json`** and remove `PATCHSTACK_SITE_UUID` (and public-prefixed variants like `NEXT_PUBLIC_PATCHSTACK_SITE_UUID`) from env files and CI variables.
+6. **Delete `.patchstackrc.json`** and remove `PATCHSTACK_SITE_UUID`, `PATCHSTACK_API_KEY` (and public-prefixed variants like `NEXT_PUBLIC_PATCHSTACK_SITE_UUID`) from env files and CI variables.
 7. **Commit** the changes. Reporting stops immediately. The `window.__PATCHSTACK_PROD__` flag that `mark-build` injected lives only in build output, never in source — the next build simply won't contain it (rebuild if build output is committed).
 
 Local removal does not delete the site record on Patchstack's side. An unclaimed site is an anonymous record that stops receiving reports; a claimed site is removed by the user in their dashboard at https://app.patchstack.com. There is no CLI command for account-side deletion — do not invent one, and never attempt to authenticate or remove the site on the user's behalf.
+
+The reverse also holds: removing the site on Patchstack's side (dashboard delete or the widget's uninstall flow) does not touch these local files — they must still be removed with the steps above. `npx @patchstack/connect status` shows `Site status: removed from Patchstack` in that state.

package/dist/cli.js

@@ -946,6 +946,31 @@ function buildClaimUrl(endpoint, siteUuid) {
   const origin = new URL(endpoint).origin;
   return `${origin}/monitor/claim?site=${encodeURIComponent(siteUuid)}`;
 }
+function buildSettingsUrl(endpoint, siteUuid) {
+  const origin = new URL(endpoint).origin;
+  return `${origin}/monitor/widget/settings/${encodeURIComponent(siteUuid)}`;
+}
+async function fetchSiteStatus(config) {
+  if (config.siteUuid === null) return "unknown";
+  const url = new URL(buildSettingsUrl(config.endpoint, config.siteUuid));
+  url.searchParams.set("t", Date.now().toString());
+  try {
+    const response = await fetch(url.toString(), {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+        "Cache-Control": "no-cache",
+        "User-Agent": "@patchstack/connect"
+      },
+      signal: AbortSignal.timeout(config.timeoutMs)
+    });
+    if (response.status === 404) return "removed";
+    if (response.ok) return "active";
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
+}
 async function postManifest(config, payload) {
   const url = buildEndpointUrl(config.endpoint, config.siteUuid);
   const timeoutMs = config.timeoutMs;
@@ -1247,8 +1272,10 @@ async function resolveConfig(options) {
       "CONFIG_MISSING"
     );
   }
+  const apiKeyRaw = fromEnv.apiKey ?? fromFile.apiKey ?? null;
   return {
     siteUuid: siteUuid === null || siteUuid.length === 0 ? null : siteUuid,
+    apiKey: apiKeyRaw === null || apiKeyRaw.length === 0 ? null : apiKeyRaw,
     endpoint,
     timeoutMs,
     environment,
@@ -1265,6 +1292,10 @@ async function persistSiteUuid(cwd, siteUuid) {
   const existing = await readConfigFile(cwd);
   return writeConfigFile(cwd, { ...existing, siteUuid });
 }
+async function persistApiKey(cwd, apiKey) {
+  const existing = await readConfigFile(cwd);
+  return writeConfigFile(cwd, { ...existing, apiKey });
+}
 async function readConfigFile(cwd) {
   const target = path6.join(cwd, CONFIG_FILENAME);
   let raw;
@@ -1306,6 +1337,7 @@ function readEnv() {
   const environmentRaw = process.env.PATCHSTACK_ENVIRONMENT;
   return {
     siteUuid: process.env.PATCHSTACK_SITE_UUID ?? void 0,
+    apiKey: process.env.PATCHSTACK_API_KEY ?? void 0,
     endpoint: process.env.PATCHSTACK_ENDPOINT ?? void 0,
     timeoutMs,
     environment: environmentRaw !== void 0 && environmentRaw.length > 0 ? environmentRaw : void 0
@@ -2858,7 +2890,9 @@ Usage:
                                                      Never runs the project build
   patchstack-connect init   <site-uuid>              Optional: pre-seed .patchstackrc.json
                                                      with an existing site UUID
-  patchstack-connect status [options]                Show current configuration
+  patchstack-connect status [options]                Show current configuration and whether the
+                                                     site still exists on Patchstack (active /
+                                                     removed)
   patchstack-connect mark-build [options]            Stamp built HTML with a production flag +
                                                      build fingerprint, and ensure the widget
                                                      tag in built pages (run as a postbuild step)
@@ -2899,6 +2933,9 @@ Options (for demo and demo-guide):
 
 Environment:
   PATCHSTACK_SITE_UUID    Site UUID
+  PATCHSTACK_API_KEY      WP-format site API key for block-log reporting (never put in the widget)
+  PATCHSTACK_TELEMETRY    Set to off to disable block-log reporting
+  PATCHSTACK_API_BASE     API origin for /oauth/token and /api/logs/log (default: https://api.patchstack.com)
   PATCHSTACK_ENDPOINT     API endpoint (default: https://api.patchstack.com/monitor/pulse/manifest)
   PATCHSTACK_TIMEOUT_MS   Request timeout in ms (default: 30000)
   PATCHSTACK_ENVIRONMENT  Manifest environment: production | sandbox (default: production)
@@ -3022,6 +3059,10 @@ async function runScan(args, options = {}) {
     const target = await persistSiteUuid(process.cwd(), response.uuid);
     console.log(`Provisioned site ${response.uuid}. Saved UUID to ${target}.`);
   }
+  if (typeof response.api_key === "string" && response.api_key.length > 0) {
+    const target = await persistApiKey(process.cwd(), response.api_key);
+    console.log(`Saved API key to ${target} (for block-log reporting via /api/logs/log; keep out of the public widget).`);
+  }
   if (response.stored) {
     console.log(`Stored manifest #${response.manifest_id} (checksum ${response.checksum}).`);
   } else if (response.reason === "duplicate") {
@@ -3290,6 +3331,26 @@ async function runStatus(args) {
   console.log(`Environment: ${config.environment}`);
   if (config.siteUuid !== null) {
     console.log(`Dashboard URL: ${buildClaimUrl(config.endpoint, config.siteUuid)}`);
+    switch (await fetchSiteStatus(config)) {
+      case "active":
+        console.log("Site status:   active on Patchstack");
+        break;
+      case "removed":
+        console.log("Site status:   removed from Patchstack");
+        console.log(
+          "  The site record no longer exists (deleted from the dashboard or via the"
+        );
+        console.log(
+          "  widget uninstall flow). The local integration files are still in this"
+        );
+        console.log(
+          '  project \u2014 see "Uninstalling" in AGENT-INSTALL.md to remove them.'
+        );
+        break;
+      case "unknown":
+        console.log("Site status:   could not be verified (Patchstack unreachable)");
+        break;
+    }
   }
   return 0;
 }