@patchstack/connect 0.5.0 → 0.5.2

package/dist/protect/templates/generic-guard.cjs

@@ -1,6 +1,6 @@
 // Patchstack runtime protection — GENERIC guard (CommonJS). Managed by `patchstack-connect protect`.
 // Wire whichever helper fits your server into your request path, then run `protect --check`.
-const { createProtection } = require("@patchstack/connect/protect");
+const { createProtection, sentinelAnswer, VERIFY_HEADER } = require("@patchstack/connect/protect");
 // The fallback bundle is optional at RUNTIME. This file is imported on the app's own module path, so a
 // throw here is the app failing to boot rather than protection failing open — and a rules file can be
 // absent for ordinary reasons: a bundler that copied no JSON, a partial deploy, a half-written edit.
@@ -66,6 +66,12 @@ function psStepAside(err) {
 }
 function protectFetch(handler) {
   return async (request, ...rest) => {
+    // `protect --check --runtime` asks whether a request actually reaches this seam. The answer is
+    // derived from a challenge the verifying process mints per run, which rules out an app matching it
+    // by accident, and there is nothing to answer unless that process started this one. Without a
+    // challenge in the environment this is a header read.
+    const answered = await sentinelAnswer(request.headers.get(VERIFY_HEADER));
+    if (answered) return new Response(answered, { status: 200, headers: { "content-type": "text/plain" } });
     const active = await getProtection().catch(psStepAside);
     // The handler, and nothing around it: an exception the app throws is the app's, not a protection
     // failure, and must not be read as one or answered twice.
@@ -92,19 +98,37 @@ function patchstackMiddleware(req, res, next) {
     passedOn = true;
     next(err);
   };
-  getProtection().then(
-    (active) => active.node()(req, res, carryOn),
-    (err) => {
+  // `protect --check --runtime` asks whether a request actually reaches this seam. Answered here,
+  // before the protection is asked for and before the request is passed on, so no handler of the app's
+  // ever sees a verification request. The answer is derived from a challenge the verifying process mints
+  // per run, which rules out an app matching it by accident; without a challenge in the environment
+  // there is nothing to answer and the request is screened as normal.
+  const screen = () => {
+    getProtection().then(
+      (active) => active.node()(req, res, carryOn),
+      (err) => {
+        psStepAside(err);
+        carryOn();
+      },
+    ).catch((err) => {
+      // Not a failed build: the guard, or the app's own chain, threw after this point. Reported, and the
+      // request is carried on only if it never was — an error here must not take the process down and
+      // must not answer twice.
       psStepAside(err);
       carryOn();
-    },
-  ).catch((err) => {
-    // Not a failed build: the guard, or the app's own chain, threw after this point. Reported, and the
-    // request is carried on only if it never was — an error here must not take the process down and
-    // must not answer twice.
-    psStepAside(err);
-    carryOn();
-  });
+    });
+  };
+
+  sentinelAnswer(req.headers?.[VERIFY_HEADER]).then((answered) => {
+    if (answered) {
+      res.statusCode = 200;
+      res.setHeader("content-type", "text/plain");
+      res.end(answered);
+
+      return;
+    }
+    screen();
+  }, screen);
 }
 
 module.exports = { getProtection, protectFetch, patchstackMiddleware };

package/dist/protect/templates/generic-guard.js

@@ -1,7 +1,7 @@
 // Patchstack runtime protection — GENERIC guard (ESM). Managed by `patchstack-connect protect`.
 // Wire whichever helper fits your server into your request path, then run `protect --check`.
 import { readFileSync } from "node:fs";
-import { createProtection } from "@patchstack/connect/protect";
+import { createProtection, sentinelAnswer, VERIFY_HEADER } from "@patchstack/connect/protect";
 
 // The fallback bundle is optional at RUNTIME. This file is imported on the app's own module path, so a
 // throw here is the app failing to boot rather than protection failing open — and a rules file can be
@@ -68,6 +68,12 @@ function psStepAside(err) {
 // Web-Fetch: export default { fetch: protectFetch(originalFetch) }
 export function protectFetch(handler) {
   return async (request, ...rest) => {
+    // `protect --check --runtime` asks whether a request actually reaches this seam. The answer is
+    // derived from a challenge the verifying process mints per run, which rules out an app matching it
+    // by accident, and there is nothing to answer unless that process started this one. Without a
+    // challenge in the environment this is a header read.
+    const answered = await sentinelAnswer(request.headers.get(VERIFY_HEADER));
+    if (answered) return new Response(answered, { status: 200, headers: { "content-type": "text/plain" } });
     const active = await getProtection().catch(psStepAside);
     // The handler, and nothing around it: an exception the app throws is the app's, not a protection
     // failure, and must not be read as one or answered twice.
@@ -94,17 +100,35 @@ export function patchstackMiddleware(req, res, next) {
     passedOn = true;
     next(err);
   };
-  getProtection().then(
-    (active) => active.node()(req, res, carryOn),
-    (err) => {
+  // `protect --check --runtime` asks whether a request actually reaches this seam. Answered here,
+  // before the protection is asked for and before the request is passed on, so no handler of the app's
+  // ever sees a verification request. The answer is derived from a challenge the verifying process mints
+  // per run, which rules out an app matching it by accident; without a challenge in the environment
+  // there is nothing to answer and the request is screened as normal.
+  const screen = () => {
+    getProtection().then(
+      (active) => active.node()(req, res, carryOn),
+      (err) => {
+        psStepAside(err);
+        carryOn();
+      },
+    ).catch((err) => {
+      // Not a failed build: the guard, or the app's own chain, threw after this point. Reported, and the
+      // request is carried on only if it never was — an error here must not take the process down and
+      // must not answer twice.
       psStepAside(err);
       carryOn();
-    },
-  ).catch((err) => {
-    // Not a failed build: the guard, or the app's own chain, threw after this point. Reported, and the
-    // request is carried on only if it never was — an error here must not take the process down and
-    // must not answer twice.
-    psStepAside(err);
-    carryOn();
-  });
+    });
+  };
+
+  sentinelAnswer(req.headers?.[VERIFY_HEADER]).then((answered) => {
+    if (answered) {
+      res.statusCode = 200;
+      res.setHeader("content-type", "text/plain");
+      res.end(answered);
+
+      return;
+    }
+    screen();
+  }, screen);
 }

package/dist/protect/templates/generic-guard.ts

@@ -4,7 +4,7 @@
 // whichever helper below fits your server into your request path (see the plan the CLI printed),
 // then run `patchstack-connect protect --check` to confirm it's hooked up. The engine ships inside
 // @patchstack/connect — nothing else to install.
-import { createProtection } from "@patchstack/connect/protect";
+import { createProtection, sentinelAnswer, VERIFY_HEADER } from "@patchstack/connect/protect";
 import fallbackRules from "./rules.json";
 
 // Baked by `patchstack-connect protect` from .patchstackrc.json when available.
@@ -76,6 +76,12 @@ function psStepAside(err: unknown) {
 // Wrap your fetch handler:  export default { fetch: protectFetch(originalFetch) }
 export function protectFetch<H extends (request: Request, ...rest: unknown[]) => unknown>(handler: H): H {
   return (async (request: Request, ...rest: unknown[]) => {
+    // `protect --check --runtime` asks whether a request actually reaches this seam. The answer is
+    // derived from a challenge the verifying process mints per run, which rules out an app matching it
+    // by accident, and there is nothing to answer unless that process started this one. Without a
+    // challenge in the environment this is a header read.
+    const answered = await sentinelAnswer(request.headers.get(VERIFY_HEADER));
+    if (answered) return new Response(answered, { status: 200, headers: { "content-type": "text/plain" } });
     const protection = await getProtection().catch(psStepAside);
     // The handler, and nothing around it: an exception the app throws is the app's, not a protection
     // failure, and must not be read as one or answered twice.
@@ -103,17 +109,40 @@ export function patchstackMiddleware(req: unknown, res: unknown, next: (err?: un
     passedOn = true;
     next(err);
   };
-  getProtection().then(
-    (protection) => (protection.node() as (a: unknown, b: unknown, c: (e?: unknown) => void) => void)(req, res, carryOn),
-    (err) => {
+  // `protect --check --runtime` asks whether a request actually reaches this seam. Answered here,
+  // before the protection is asked for and before the request is passed on, so no handler of the app's
+  // ever sees a verification request. The answer is derived from a challenge the verifying process mints
+  // per run, which rules out an app matching it by accident; without a challenge in the environment
+  // there is nothing to answer and the request is screened as normal.
+  const screen = () => {
+    getProtection().then(
+      (protection) => (protection.node() as (a: unknown, b: unknown, c: (e?: unknown) => void) => void)(req, res, carryOn),
+      (err) => {
+        psStepAside(err);
+        carryOn();
+      },
+    ).catch((err) => {
+      // Not a failed build: the guard, or the app's own chain, threw after this point. Reported, and the
+      // request is carried on only if it never was — an error here must not take the process down and
+      // must not answer twice.
       psStepAside(err);
       carryOn();
-    },
-  ).catch((err) => {
-    // Not a failed build: the guard, or the app's own chain, threw after this point. Reported, and the
-    // request is carried on only if it never was — an error here must not take the process down and
-    // must not answer twice.
-    psStepAside(err);
-    carryOn();
-  });
+    });
+  };
+
+  // The two shapes this seam touches, named rather than asserted wholesale: a request whose headers it
+  // reads, and a response it answers on.
+  const inbound = req as { headers?: Record<string, unknown> };
+  const outbound = res as { statusCode: number; setHeader(name: string, value: string): void; end(body?: string): void };
+
+  sentinelAnswer(inbound.headers?.[VERIFY_HEADER]).then((answered) => {
+    if (answered) {
+      outbound.statusCode = 200;
+      outbound.setHeader("content-type", "text/plain");
+      outbound.end(answered);
+
+      return;
+    }
+    screen();
+  }, screen);
 }

package/dist/protect.cjs

@@ -142,6 +142,9 @@ var init_types = __esm({
 });
 
 // src/client.ts
+function claimTokenHeader(config) {
+  return typeof config.claimToken === "string" && config.claimToken !== "" ? { [CLAIM_TOKEN_HEADER]: config.claimToken } : {};
+}
 function buildEndpointUrl(base, siteUuid) {
   const trimmed = base.replace(/\/$/, "");
   return siteUuid !== void 0 && siteUuid !== null && siteUuid.length > 0 ? `${trimmed}/${encodeURIComponent(siteUuid)}` : trimmed;
@@ -177,7 +180,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)
@@ -236,7 +240,7 @@ function isTimeoutError(cause) {
   }
   return false;
 }
-var DEFAULT_ENDPOINT, DEFAULT_TIMEOUT_MS;
+var DEFAULT_ENDPOINT, DEFAULT_TIMEOUT_MS, CLAIM_TOKEN_HEADER;
 var init_client = __esm({
   "src/client.ts"() {
     "use strict";
@@ -244,6 +248,7 @@ var init_client = __esm({
     init_pulse_token();
     DEFAULT_ENDPOINT = "https://api.patchstack.com/monitor/pulse/manifest";
     DEFAULT_TIMEOUT_MS = 3e4;
+    CLAIM_TOKEN_HEADER = "X-Patchstack-Claim-Token";
   }
 });
 
@@ -478,6 +483,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,
@@ -487,7 +493,8 @@ async function resolveConfig(options) {
     endpoint,
     timeoutMs,
     environment,
-    widget: fromFile.widget !== false
+    widget: fromFile.widget !== false,
+    claimToken
   };
 }
 async function readSecretFile(cwd) {
@@ -1838,9 +1845,11 @@ var runtime_exports = {};
 __export(runtime_exports, {
   GUARD_PATH: () => GUARD_PATH,
   PulseRuleClient: () => PulseRuleClient,
+  VERIFY_HEADER: () => VERIFY_HEADER,
   createProtection: () => createProtection,
   createServerFnGuard: () => createServerFnGuard,
-  createSupabaseGuard: () => createSupabaseGuard
+  createSupabaseGuard: () => createSupabaseGuard,
+  sentinelAnswer: () => sentinelAnswer
 });
 module.exports = __toCommonJS(runtime_exports);
 
@@ -6323,6 +6332,33 @@ function createSupabaseGuard({ protection, supabaseUrl, fetchImpl = fetch }) {
   };
 }
 
+// src/protect/verify-sentinel.js
+var VERIFY_HEADER = "x-patchstack-verify";
+var CHALLENGE = "PATCHSTACK_VERIFY_CHALLENGE";
+function configuredChallenge() {
+  const value = typeof process !== "undefined" ? process.env?.[CHALLENGE] : void 0;
+  return typeof value === "string" && value.length >= 32 ? value : null;
+}
+function sameValue(a, b) {
+  if (typeof a !== "string" || typeof b !== "string" || a.length !== b.length) return false;
+  let differs = 0;
+  for (let i = 0; i < a.length; i += 1) differs |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return differs === 0;
+}
+async function sentinelAnswer(offered) {
+  const challenge = configuredChallenge();
+  if (challenge === null || !sameValue(challenge, typeof offered === "string" ? offered : null)) return null;
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle || typeof subtle.digest !== "function" || typeof TextEncoder === "undefined") return null;
+  try {
+    const bytes = new TextEncoder().encode(`patchstack-verify:${challenge}`);
+    const digest = await subtle.digest("SHA-256", bytes);
+    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
+  } catch {
+    return null;
+  }
+}
+
 // src/protect/runtime.js
 function createServerFnGuard({ protection }) {
   const guard = protection.fetchGuard();
@@ -7660,8 +7696,10 @@ function nodeRequestMeta(req, client) {
 0 && (module.exports = {
   GUARD_PATH,
   PulseRuleClient,
+  VERIFY_HEADER,
   createProtection,
   createServerFnGuard,
-  createSupabaseGuard
+  createSupabaseGuard,
+  sentinelAnswer
 });
 //# sourceMappingURL=protect.cjs.map