@patchstack/connect 0.5.0 → 0.5.1

package/AGENT-INSTALL.md

@@ -9,7 +9,7 @@ Every command at a glance — what it does, whether it reads your source, what i
 | Command | What it does | Reads your source? | Writes to your project | Sends over the network |
 |---|---|---|---|---|
 | `scan` | Provision (or reuse) the site and POST the dependency list for vulnerability matching. Also runs automatically via `setup` and the install/build hooks. | No — lockfile only; `node_modules/` is enumerated when no lockfile can be read (e.g. `bun.lockb`) or when the lockfiles present disagree. It also reads the `<title>` of the root `index.html` and the `name` in `package.json`, to report what the site is called | `.patchstackrc.json` (public: site UUID + settings); `.patchstackrc.local.json` (the API key, created owner-only) and a `.gitignore` entry for it — the CLI says so if it could not add one; the widget `<script>` tag in the root HTML shell — only after a successful post; the production marker in a code root shell — before the post, since it needs no site UUID | Package names + versions; this site's public address and name, where the project or build environment states them |
-| `setup` | One bounded command: `scan` → manage the widget → install + verify `protect` → wire the install/build scans. Never runs the project build. | No | Config, widget tag, production marker, guard files, `package.json` scripts | Package names + versions and the site's public address and name (via `scan`) |
+| `setup` | One bounded command: `scan` → manage the widget → install + verify `protect` → wire the install/build scans. Never runs the project build. | No | Config, widget tag, production marker, guard files, `package.json` scripts | Package names + versions and the site's public address and name (via `scan`); a claim token as a request header, only when you pass one |
 | `map` | Local, read-only attack-surface analysis (entry points → inputs → sinks → evidence-backed flows). Never run by another command. | **Yes** — via the app's own TypeScript | Nothing (only the file named by `--out`) | Nothing — **unless `--upload`**: structure only (routes, parameter names, the package behind each sink, file:line). Never source code or env values |
 | `protect` | Install the always-on runtime guard; auto-wire known stacks, or scaffold a generic guard + print a wiring plan. `--check` verifies the guard is wired (exit 1 if not); `--demo` seeds a broad sample rule set. Runs automatically **only** via `setup` — never by `scan`, `guide`, `status`, or `mark-build`. | No — writes guard files, does not analyze your code | Guard/framework files (e.g. `middleware.ts`, `src/patchstack/`) | Nothing |
 | `demo node-serialize` | Production-backed walkthrough: confirm the vulnerable package is present, scan, wait for live rule `18843`, install + verify the guard, print test requests. Does not install the package or start/restart the app. | No | Same files as `scan` + `protect` | `scan` payload; polls the public Pulse rules endpoint (never the printed test requests) |
@@ -85,6 +85,8 @@ This is a request, not a mechanism: nothing in the install depends on it. Do it
 
    This provisions or reuses the site, manages the widget, installs and verifies runtime protection, wires dependency-install and build scans, prints a dashboard link, and finishes with the same status shown by `guide`. Re-running it reuses existing configuration, widget tags, guards, and commands rather than duplicating them.
 
+   **If the request you were given includes a claim token**, pass it exactly as given: `npx @patchstack/connect setup --claim-token <token>`. The site is then created in the person's own Patchstack account and `setup` prints their dashboard link for it — there is no sign-in step to relay. The token comes only from the person's Patchstack dashboard; never invent one, never write it to a file, never print it back. If `setup` reports that the token had expired or was not recognised, the site is not connected: hand over the dashboard link it prints instead, and tell the person they can copy a fresh prompt from the dashboard.
+
    In a hosted builder, run setup with `PATCHSTACK_ENVIRONMENT=sandbox` scoped to the workspace process/command, ensure the CLI's on-disk edits are adopted into the platform's persisted project state, then restart any already-running preview/server process so it loads the guard. Do not persist `"environment": "sandbox"` in `.patchstackrc.json`: deployed builds use the same committed files and should default to `production`. A client-only SPA has no server request path to guard; do not call it protected unless `protect --check` succeeds after a real server or edge seam is wired.
 
    **Finish by telling the user to refresh their preview.** The widget's "Report a vulnerability" button loads with the page, so a preview that was already open still shows the HTML from before setup — the button is missing there until it reloads. Nothing in the CLI can reach the user's browser, so relaying this is your job. Phrase it as a check rather than a required step: a builder that hot reloads, or a preview server you restarted, may have refreshed it already.
@@ -149,6 +151,7 @@ It is server-only. Never put it in the widget tag, client bundles, or public env
 ## Rules
 
 - Never invent or guess a UUID — the scan provisions it, the widget silently no-ops on a fake one.
+- Never invent or guess a claim token either. One is only ever handed to you by the person, from their own Patchstack dashboard; pass it with `--claim-token` (or `PATCHSTACK_CLAIM_TOKEN`) and nowhere else — not into `.patchstackrc.json`, not into a committed file, not into your reply.
 - 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.

package/README.md

@@ -96,6 +96,8 @@ patchstack-connect --version                       Print the installed version
 Options (for scan, setup, and status):
   --site-uuid <uuid>      Override the configured site UUID
   --endpoint <url>        Override the API endpoint
+  --claim-token <token>   (scan, setup) Connect the site to the account that issued
+                          the token (from the dashboard's "Connect website" prompt)
   --dry-run               (scan only) Print the payload without posting
 
 Options (for demo and demo-guide):
@@ -107,7 +109,7 @@ Options (for demo and demo-guide):
 
 Precedence (highest wins):
 
-1. CLI flag (`--site-uuid`, `--endpoint`)
+1. CLI flag (`--site-uuid`, `--endpoint`, `--claim-token`)
 2. Environment variable
 3. `.patchstackrc.local.json` in the current directory (the credential)
 4. `.patchstackrc.json` in the current directory
@@ -118,6 +120,7 @@ Environment variables:
 - `PATCHSTACK_ENDPOINT` — override the API endpoint (default `https://api.patchstack.com/monitor/pulse/manifest`)
 - `PATCHSTACK_TIMEOUT_MS` — request timeout in milliseconds (default `30000`)
 - `PATCHSTACK_ENVIRONMENT` — manifest label: `production` (default) or `sandbox`
+- `PATCHSTACK_CLAIM_TOKEN` — connect the site straight to your account (see *Connecting straight to your account*)
 
 Two files, because one value is public and the other is not.
 
@@ -152,6 +155,17 @@ The credential's file is never committed, so CI needs `PATCHSTACK_API_KEY` in th
 
 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.
 
+### Connecting straight to your account
+
+The dashboard's "Connect website" prompt carries a **claim token**. Pass it to the first `setup` (or `scan`) and the site it provisions is created in your account, so there is no dashboard link to open afterwards:
+
+```bash
+npx @patchstack/connect setup --claim-token <token>
+# or: PATCHSTACK_CLAIM_TOKEN=<token> npx @patchstack/connect setup
+```
+
+The token names your account, not the project: it is never written to `.patchstackrc.json` or the credential file, it is sent to Patchstack as a request header rather than in the manifest body, and it stops working within a day. A token that has expired (or one Patchstack does not recognise) leaves the site exactly as a scan without one would — unconnected, with the dashboard link printed — and `scan` says so. Re-running `setup` with the same token against a site already in your account is a no-op that says the site is already connected; a site that belongs to a different account is left alone.
+
 ### Sandbox and production manifests
 
 Every `scan` sends an environment label with its dependency manifest. The default is `production`; sandboxed builders should set `PATCHSTACK_ENVIRONMENT=sandbox` in the sandbox process only. Patchstack stores and deduplicates manifests per environment, so an iterative workspace scan does not replace the last production manifest.
@@ -244,6 +258,8 @@ The name is what the dashboard calls the site. It is taken from `name` in `.patc
 
 You can see exactly what would be sent, without sending it, by running `npx @patchstack/connect scan --dry-run`: the preview it prints is the request body itself. Patchstack only applies either field to a site that does not have one yet: it never re-points a site whose address is real, and never replaces a name set in the dashboard.
 
+One thing travels outside that body: a claim token, when you pass one (`--claim-token` / `PATCHSTACK_CLAIM_TOKEN`), is sent as the `X-Patchstack-Claim-Token` request header so that the site is created in your account. Without one, no such header is sent.
+
 ### `scan --install-paths` (opt-in)
 
 Pass it and each entry also carries where that version is installed:

package/dist/cli.js

@@ -1291,6 +1291,25 @@ async function pulseFetch(config, url, init, fetchImpl = fetch) {
 // src/client.ts
 var DEFAULT_ENDPOINT = "https://api.patchstack.com/monitor/pulse/manifest";
 var DEFAULT_TIMEOUT_MS = 3e4;
+var CLAIM_TOKEN_HEADER = "X-Patchstack-Claim-Token";
+function claimTokenHeader(config) {
+  return typeof config.claimToken === "string" && config.claimToken !== "" ? { [CLAIM_TOKEN_HEADER]: config.claimToken } : {};
+}
+function claimOutcomeLines(claim2, config) {
+  if (typeof config.claimToken !== "string" || config.claimToken === "") return [];
+  if (claim2?.state === "claimed" || claim2?.state === "owned-by-you") {
+    const dashboard = typeof claim2.dashboard_url === "string" && claim2.dashboard_url !== "" ? [`Dashboard: ${claim2.dashboard_url}`] : [];
+    return [
+      claim2.state === "claimed" ? "Connected to your Patchstack account." : "This site is already connected to your Patchstack account.",
+      ...dashboard
+    ];
+  }
+  const why = claim2 === void 0 ? "Patchstack did not act on the claim token" : claim2.state === "owned-by-other" ? "this site belongs to a different Patchstack account" : claim2.reason === "expired" ? "the claim token has expired" : "Patchstack did not recognise the claim token";
+  return [
+    `Not connected to your account: ${why}.`,
+    "Open the dashboard link below to connect it, or copy a fresh prompt from the dashboard."
+  ];
+}
 function buildEndpointUrl(base, siteUuid) {
   const trimmed = base.replace(/\/$/, "");
   return siteUuid !== void 0 && siteUuid !== null && siteUuid.length > 0 ? `${trimmed}/${encodeURIComponent(siteUuid)}` : trimmed;
@@ -1454,7 +1473,8 @@ async function postManifest(config, payload) {
       headers: {
         "Content-Type": "application/json",
         Accept: "application/json",
-        "User-Agent": "@patchstack/connect"
+        "User-Agent": "@patchstack/connect",
+        ...claimTokenHeader(config)
       },
       body: JSON.stringify(buildManifestBody(config, payload)),
       signal: AbortSignal.timeout(timeoutMs)
@@ -1944,6 +1964,7 @@ async function resolveConfig(options) {
   const apiKeyRaw = fromEnv.apiKey ?? fromSecretFile.apiKey ?? fromFile.apiKey ?? null;
   const pulseAuthRaw = fromEnv.pulseAuth ?? fromSecretFile.pulseAuth ?? fromFile.pulseAuth ?? apiKeyRaw;
   const identity = options.detectSiteIdentity === true ? await resolveSiteIdentity(options.cwd, fromEnv, fromFile) : { url: null, name: null };
+  const claimToken = stated(options.cliClaimToken) ?? stated(process.env.PATCHSTACK_CLAIM_TOKEN);
   return {
     siteUuid: siteUuid === null || siteUuid.length === 0 ? null : siteUuid,
     apiKey: apiKeyRaw === null || apiKeyRaw.length === 0 ? null : apiKeyRaw,
@@ -1953,7 +1974,8 @@ async function resolveConfig(options) {
     endpoint,
     timeoutMs,
     environment,
-    widget: fromFile.widget !== false
+    widget: fromFile.widget !== false,
+    claimToken
   };
 }
 async function writeConfigFile(cwd, config) {
@@ -7214,6 +7236,10 @@ Options (for scan, setup, status, and uninstall):
                           same under a workspace that pins its own copy), so an
                           advisory can be matched to the copy your code actually
                           loads. Off by default; never source file paths
+  --claim-token <token>   (scan, setup) Connect the site to the Patchstack account
+                          that issued the token \u2014 it comes from the dashboard's
+                          "Connect website" prompt. PATCHSTACK_CLAIM_TOKEN works
+                          too. Never written to a file, never printed back
 
 Options (for mark-build):
   --dir <path>            Build output directory (default: auto-detect
@@ -7247,7 +7273,7 @@ Examples:
   npx @patchstack/connect demo node-serialize
   npx @patchstack/connect demo-guide node-serialize
 `;
-var VALUE_FLAGS = /* @__PURE__ */ new Set(["site-uuid", "endpoint", "dir", "url", "out"]);
+var VALUE_FLAGS = /* @__PURE__ */ new Set(["site-uuid", "endpoint", "dir", "url", "out", "claim-token"]);
 function parseArgs(argv) {
   const args = argv.slice(2);
   const positional = [];
@@ -7381,6 +7407,7 @@ async function runScan(args, options = {}) {
     cwd: process.cwd(),
     cliSiteUuid: getStringFlag(args.flags, "site-uuid"),
     cliEndpoint: getStringFlag(args.flags, "endpoint"),
+    cliClaimToken: getStringFlag(args.flags, "claim-token"),
     // The one command that reports them, so the one command that resolves them.
     detectSiteIdentity: true
   });
@@ -7421,6 +7448,9 @@ async function runScan(args, options = {}) {
   if (typeof body.name === "string") {
     console.log(`Reporting this app's name as "${body.name}".`);
   }
+  if (typeof config.claimToken === "string" && config.claimToken !== "") {
+    console.log("A claim token is set: the site will be connected to the Patchstack account that issued it.");
+  }
   if (dryRun) {
     console.log("");
     if (config.siteUuid === null) {
@@ -7475,14 +7505,21 @@ async function runScan(args, options = {}) {
   } else {
     console.log(`Server response: ${response.message ?? JSON.stringify(response)}`);
   }
+  const claimLines = claimOutcomeLines(response.claim, config);
+  if (claimLines.length > 0) {
+    console.log("");
+    for (const line of claimLines) console.log(line);
+  }
+  const connected = response.claim?.state === "claimed" || response.claim?.state === "owned-by-you";
   const effectiveUuid = config.siteUuid ?? response.uuid ?? null;
   if (config.widget && effectiveUuid !== null && effectiveUuid.length > 0) {
     reportSourceWidget(effectiveUuid);
   }
-  if (provisioning && response.uuid !== void 0 && response.uuid.length > 0) {
+  const linkUuid = response.uuid ?? config.siteUuid;
+  if (!connected && (provisioning || claimLines.length > 0) && linkUuid !== null && linkUuid !== void 0 && linkUuid.length > 0) {
     console.log("");
     console.log("Open this dashboard link to view vulnerability reports:");
-    console.log(`  ${buildClaimUrl(config.endpoint, response.uuid)}`);
+    console.log(`  ${buildClaimUrl(config.endpoint, linkUuid)}`);
     if (config.endpoint !== DEFAULT_ENDPOINT) {
       console.log("  (this URL inherits the endpoint override above)");
     }