@patchstack/connect 0.3.25 → 0.3.26

package/AGENT-INSTALL.md

@@ -76,12 +76,13 @@ 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. The credentials are the opposite, and `scan` writes both of them for you — **there is no manual step, and you should never invent or ask the user for these values**:
+   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 credential is the opposite, and `scan` writes it for you — **there is no manual step, and you should never invent or ask the user for this value**:
 
-- `apiKey` (also `PATCHSTACK_API_KEY`, WP format `{secret}-{oauth.id}`) — authenticates block-log reporting through the connector `POST /api/logs/log`, so "Threats blocked" fills in the dashboard.
-- `pulseAuth` (also `PATCHSTACK_PULSE_AUTH`) — authenticates Pulse ingest: the manifest, the attack-surface map and package removal. Exchanged for a short-lived token rather than sent directly. Falls back to `apiKey` when absent, so older projects keep working.
+- `apiKey` (also `PATCHSTACK_API_KEY`, WP format `{secret}-{oauth.id}`) — one credential for both paths. It authenticates **Pulse ingest** (manifest, attack-surface map, package removal), where it is exchanged for a short-lived token rather than sent directly, and **block-log reporting** through the connector `POST /api/logs/log`, so "Threats blocked" fills in the dashboard.
 
-Both are server-only. Never put either in the widget tag, client bundles, or public env vars (`NEXT_PUBLIC_*`, etc.). Prefer `PATCHSTACK_API_KEY` / `PATCHSTACK_PULSE_AUTH` in production; `.patchstackrc.json` is fine for local DX. If a credential is lost, `npx @patchstack/connect login` recovers it via dashboard approval — do not delete the file and re-provision, which would create a second site. 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.
+It is server-only. Never put it 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. If it is lost, `npx @patchstack/connect login` recovers it via dashboard approval — do not delete the file and re-provision, which would create a second site. 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.
+
+   A `pulseAuth` field is still honoured if a project has one, and `PATCHSTACK_PULSE_AUTH` still overrides it, for deployments that authenticate Pulse ingest with a different credential from block-logs. Do not add either yourself: they are unnecessary when the two share one credential, which is the default.
 
 4. **Install and verify runtime protection:**
 
@@ -102,7 +103,7 @@ Both are server-only. Never put either in the widget tag, client bundles, or pub
 - The CLI never opens the dashboard link and never asks for Patchstack credentials.
 - Label hosted workspace scans with `PATCHSTACK_ENVIRONMENT=sandbox` in that process only. Leave production builds unset (the default is `production`) and never commit a sandbox label into files shared with production.
 - If a step fails, stop and report it. Don't proceed with placeholders.
-- In CI where `.patchstackrc.json` can't be committed, set `PATCHSTACK_SITE_UUID` and `PATCHSTACK_PULSE_AUTH` as env vars instead. Precedence: CLI flag → env var → `.patchstackrc.json`. `login` is interactive and refuses to run in CI, so CI always takes its credential from the environment.
+- In CI where `.patchstackrc.json` can't be committed, set `PATCHSTACK_SITE_UUID` and `PATCHSTACK_API_KEY` as env vars instead. Precedence: CLI flag → env var → `.patchstackrc.json`. `login` is interactive and refuses to run in CI, so CI always takes its credential from the environment.
 
 ## Verifying the install
 
@@ -119,6 +120,46 @@ These are **two independent states** — never conflate them:
 
 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."
 
+## Recovering a lost credential — `login`
+
+Use this when the project **already has a site** but its credential is gone or rejected: `.patchstackrc.json` was deleted or never committed, the repo was cloned without it, a container was recycled, or ingest started failing with 401.
+
+> **Do not "fix" a missing credential by deleting `.patchstackrc.json` and running `scan` again.** That provisions a **second site**, and the original — with all its history and its widget tag already live on the deployed page — is orphaned. `login` recovers the existing one.
+
+### What it does
+
+```
+npx @patchstack/connect login
+
+  Your code:  WDJB-MJHT
+  Approve at: https://api.patchstack.com/monitor/pulse/device?code=WDJB-MJHT
+
+  Waiting for approval…  ✓ Credential restored
+```
+
+The command asks Patchstack for a short code, prints a link, and polls until the site's **owner approves it in the dashboard**. On approval it writes the new credential into `.patchstackrc.json` and exits. The link opens the approval page with the code already filled in, so the person only has to confirm.
+
+### What you must do, as the agent
+
+1. **Run the command and surface the link and code to the user verbatim.** They must open it themselves — approval requires their signed-in Patchstack account, which you do not have and must not ask for.
+2. **Leave the command running.** It polls until approved or the code expires (10 minutes). Do not kill it and retry; each run issues a different code and invalidates the one already on screen.
+3. **Report the outcome.** On success, tell them the credential was restored *and* that the previous one no longer works — see the warning below.
+
+You cannot complete this alone. It is deliberately a human-in-the-loop step: starting the flow proves nothing about who is running it, so the only authorisation is an owner approving in the browser.
+
+### Consequences to tell the user about
+
+**Approving rotates the credential — the old one stops working immediately.** Anywhere it was configured needs the new value: CI secrets, hosting-platform env vars, preview environments, other developers' checkouts. Say this before they approve, not after.
+
+### When it will not work
+
+| Situation | What happens | What to do |
+|---|---|---|
+| Site was never claimed | `409` — no owner exists to approve | Ask the user to claim the site in the dashboard first, or, if the site is disposable, delete `.patchstackrc.json` and `scan` to provision a fresh one |
+| Running in CI | Refuses to start | CI takes its credential from `PATCHSTACK_PULSE_AUTH`; `login` is for a developer machine |
+| No `siteUuid` configured | Refuses to start | There is no site to recover — run `scan` |
+| Code expired | Poll ends after 10 minutes | Run the command again for a new code |
+
 ## 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.

package/README.md

@@ -119,22 +119,23 @@ Environment variables:
 {
   "siteUuid": "550e8400-e29b-41d4-a716-446655440000",
   "apiKey": "…",
-  "pulseAuth": "…",
   "widget": true
 }
 ```
 
 `"widget"` is optional and defaults to `true`; set it to `false` to stop the connector from managing the disclosure-widget tag (see *The disclosure widget*).
 
-**You do not write `apiKey` or `pulseAuth` yourself.** The first `scan` provisions the site and the connector saves both, so setup needs no manual step. They hold the same value today and exist as separate fields so Pulse ingest and block-log reporting can diverge later.
+**You do not write `apiKey` yourself.** The first `scan` provisions the site and the connector saves it, so setup needs no manual step.
 
 The site UUID identifies the site and is **not** a secret — the disclosure widget ships the same UUID in client-side HTML.
 
-`apiKey` and `pulseAuth` **are** secrets. `apiKey` authenticates block-log reporting; `pulseAuth` authenticates Pulse ingest (manifest, attack-surface map, package removal) and is exchanged for a short-lived token rather than sent directly. Keep both out of the widget tag, client bundles and public env vars (`NEXT_PUBLIC_*`). For deploys, prefer `PATCHSTACK_API_KEY` and `PATCHSTACK_PULSE_AUTH` in the platform's secret store over the committed file.
+`apiKey` **is** a secret. One credential authenticates both paths: Pulse ingest (manifest, attack-surface map, package removal), where it is exchanged for a short-lived token rather than sent directly, and block-log reporting. Keep it out of the widget tag, client bundles and public env vars (`NEXT_PUBLIC_*`). For deploys, prefer `PATCHSTACK_API_KEY` in the platform's secret store over the committed file.
 
-If a credential is ever lost, `npx @patchstack/connect login` recovers it — approval happens in the dashboard and rotates the credential.
+If it is ever lost, `npx @patchstack/connect login` recovers it — approval happens in the dashboard and rotates the credential.
 
-In CI setups where the file isn't committed, set `PATCHSTACK_SITE_UUID` and `PATCHSTACK_PULSE_AUTH`. Precedence is CLI flag → env var → `.patchstackrc.json`.
+In CI setups where the file isn't committed, set `PATCHSTACK_SITE_UUID` and `PATCHSTACK_API_KEY`. Precedence is CLI flag → env var → `.patchstackrc.json`.
+
+A `pulseAuth` field is still read if present, and `PATCHSTACK_PULSE_AUTH` still overrides, for deployments that authenticate Pulse ingest with a different credential from block-logs. Neither is written by default, and neither is needed when the two share one.
 
 ### Sandbox and production manifests
 

package/dist/cli.js

@@ -1457,13 +1457,9 @@ async function persistSiteUuid(cwd, siteUuid) {
   return writeConfigFile(cwd, { ...existing, siteUuid });
 }
 async function persistApiKey(cwd, apiKey) {
-  const existing = await readConfigFile(cwd);
+  const { pulseAuth: _dropped, ...existing } = await readConfigFile(cwd);
   return writeConfigFile(cwd, { ...existing, apiKey });
 }
-async function persistPulseAuth(cwd, pulseAuth) {
-  const existing = await readConfigFile(cwd);
-  return writeConfigFile(cwd, { ...existing, pulseAuth });
-}
 async function readConfigFile(cwd) {
   const target = path6.join(cwd, CONFIG_FILENAME);
   let raw;
@@ -3004,7 +3000,6 @@ async function login(config, onPrompt, deps = {}) {
     if (typeof apiKey !== "string" || apiKey.length === 0) {
       return { status: "failed", message: "Patchstack approved the request but returned no credential." };
     }
-    await persistPulseAuth(process.cwd(), apiKey);
     await persistApiKey(process.cwd(), apiKey);
     return { status: "approved", userCode, verificationUri };
   }
@@ -3741,7 +3736,7 @@ function classifyServerSurface(cwd, endpointCount, deploymentShapes, ts) {
 }
 function surfaceNote(surface) {
   if (surface.state === "server-runtime-detected") {
-    return "serverSurface: a server runtime was recognized in the analysed source (see its evidence). Request-path protection applies to this app.";
+    return "serverSurface: a server runtime was recognized in the analysed source (see its evidence). Request-path shielding is APPLICABLE to these paths \u2014 this is not a statement that a guard is installed, fetching rules, or enforcing them.";
   }
   if (surface.state === "static-build-detected") {
     return "serverSurface: a static build was identified and no server runtime was recognized in the analysed source. This is NOT deployment attestation \u2014 it describes the source, not what is deployed, and a serverless function added at the platform level would not appear here. Advisories against this app are dependency and bundle concerns rather than request-path risk.";
@@ -5497,11 +5492,14 @@ Usage:
                                                      what's missing, with tailored commands), then
                                                      print the full setup guide. --full prints the
                                                      guide even when setup is complete
-  patchstack-connect login  [options]                Recover this site's Patchstack credential when
-                                                     .patchstackrc.json has been lost. Prints a short
-                                                     code to approve in the dashboard; approving
-                                                     rotates the credential, so the old one stops
-                                                     working
+  patchstack-connect login  [options]                Recover this site's credential when
+                                                     .patchstackrc.json has been lost. Prints a link
+                                                     for the site's OWNER to approve in the dashboard,
+                                                     then waits (10 min). Use this instead of deleting
+                                                     .patchstackrc.json and re-scanning, which would
+                                                     provision a second site. Approving ROTATES the
+                                                     credential: CI, deploys and other machines using
+                                                     the old one must be updated. Not usable in CI
   patchstack-connect help                            Print this message
 
 Options (for scan, setup, status, and uninstall):
@@ -5520,7 +5518,7 @@ 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_PULSE_AUTH   Credential for authenticated Pulse ingest (defaults to PATCHSTACK_API_KEY)
+  PATCHSTACK_PULSE_AUTH   Only if Pulse ingest uses a different credential from block-logs
   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)
@@ -5607,10 +5605,15 @@ async function runLogin(args) {
   Your code:  ${userCode}`);
     console.log(`  Approve at: ${verificationUri}
 `);
-    console.log("  Waiting for approval\u2026");
+    console.log("  Open that link and approve it as the site's owner. Approving issues a new");
+    console.log("  credential and stops the current one working \u2014 CI, deploys and any other");
+    console.log("  machine using it will need the new value.\n");
+    console.log("  Waiting for approval (the code expires in 10 minutes)\u2026");
   });
   if (result.status === "approved") {
-    console.log("\n  \u2713 Credential restored and saved to .patchstackrc.json.\n");
+    console.log("\n  \u2713 Credential restored and saved to .patchstackrc.json.");
+    console.log("    The previous credential no longer works. Update it anywhere else it was set:");
+    console.log("    CI secrets, hosting env vars, preview environments, other checkouts.\n");
     return 0;
   }
   console.error(`
@@ -5745,7 +5748,6 @@ async function runScan(args, options = {}) {
   }
   if (typeof response.api_key === "string" && response.api_key.length > 0) {
     const target = await persistApiKey(process.cwd(), response.api_key);
-    await persistPulseAuth(process.cwd(), response.api_key);
     console.log(`Saved API key to ${target} (authenticates Pulse ingest and block-log reporting; keep out of the public widget).`);
   }
   if (response.stored) {