@revenexx/integrations-node-sdk 1.11.0 → 1.14.0

package/dist/allowedTargets.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The per-run allow-list of the SSRF guard (PO-828): the exact `ip:port` pairs a
+ * run may reach although the address is private — its own tenant's VPN routes,
+ * served by the relay at a private overlay address (an RFC 1918 or IPv6
+ * unique-local one — no other address may be listed).
+ *
+ * **The global symbol is the contract, not this module.** Every node bundle carries
+ * its own copy of this package, so a module-level setter would reach only the copy
+ * that happened to be imported by the host. The trusted host instead defines one
+ * property on `globalThis`, before any node bundle is imported, and every copy reads
+ * that same property:
+ *
+ * ```ts
+ * Object.defineProperty(globalThis, Symbol.for('revenexx.ssrf.allowedTargets'), {
+ *   value: Object.freeze([...targets]),
+ *   writable: false, configurable: false, enumerable: false,
+ * });
+ * ```
+ *
+ * The host may do that itself (the runtimes do, without depending on this package)
+ * or call {@link installAllowedTargets}, which does exactly that.
+ *
+ * A property that is not shaped that way is read as no list at all. Non-writable and
+ * non-configurable is what makes the list impossible to widen after the host set it;
+ * a property that lacks either was not set by a host following the contract, and a
+ * guard that honoured it would let whoever set it decide what is private.
+ */
+export declare const ALLOWED_TARGETS_SYMBOL: unique symbol;
+/** Test seam: how many times a list has been validated. Not re-exported from the package. */
+export declare const allowListStats: {
+    validations: number;
+};
+/**
+ * Read the list off `holder` — `globalThis` in production, a fresh object in the
+ * tests that need a shape the one-shot global cannot be given twice. Anything but a
+ * frozen array of valid entries on a non-writable, non-configurable data property
+ * reads as the empty list: fail closed, never partly.
+ */
+export declare function readAllowedTargets(holder: object): readonly string[];
+/** {@link isAllowedTarget} against the list on `holder`. */
+export declare function isAllowedTargetOn(holder: object, ip: string, port: number): boolean;
+/** {@link installAllowedTargets} onto `holder`. */
+export declare function installAllowedTargetsOn(holder: object, targets: readonly string[]): void;
+/**
+ * Install the per-run allow-list on `globalThis`. For the trusted host, before any
+ * node bundle is imported; one-shot — a second call throws, as does an entry that is
+ * not `"<ip>:<port>"` (IPv4 dotted) or `"[v6]:<port>"`, or whose address is not an
+ * RFC 1918 or IPv6 unique-local one.
+ *
+ * Install it even when the list is empty. A process that never installs one leaves
+ * the property free for the first code that runs to define it — node code included.
+ *
+ * Promised behaviour: specs/ssrf-guard.md (AC-26 to AC-31).
+ */
+export declare function installAllowedTargets(targets: readonly string[]): void;
+/**
+ * The per-run allow-list as the host installed it, or an empty list when none is
+ * installed or the property is malformed (see {@link ALLOWED_TARGETS_SYMBOL}).
+ */
+export declare function allowedTargets(): readonly string[];
+/**
+ * Whether the run may reach `ip` on `port` although the address is private: `true`
+ * only when exactly that pair is on the allow-list. The port is part of the target —
+ * `10.31.0.7:8080` on the list does not allow `10.31.0.7:22`. For a caller that opens
+ * its own socket; `safeFetch` and `assertPublicUrl` already consult it.
+ */
+export declare function isAllowedTarget(ip: string, port: number): boolean;

package/dist/{chunk-XO73F62E.js → chunk-CA6JVLLF.js}

@@ -92,6 +92,53 @@ function parsePackageMeta(raw) {
     icon: icon !== "" ? icon : void 0
   };
 }
+var SLUG_PATTERN = "^[a-z][a-z0-9-]{0,62}$";
+var NAMESPACED_SLUG_PATTERN = "^[a-z][a-z0-9-]{0,62}:[a-z][a-z0-9-]{0,62}$";
+var SEMVER_PATTERN = "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.-]+)?$";
+var CONFIG_KEY_PATTERN = "^[a-zA-Z][a-zA-Z0-9-]*$";
+var PATTERN_HINT = {
+  [SLUG_PATTERN]: 'lowercase kebab-case, such as "not-found"',
+  [NAMESPACED_SLUG_PATTERN]: '"<namespace>:<name>" in lowercase kebab-case, such as "core:http-request"',
+  [SEMVER_PATTERN]: 'a semantic version, such as "1.0.0"',
+  [CONFIG_KEY_PATTERN]: 'a letter, then letters, digits or "-", such as "postalCode"'
+};
+function nodeManifestProblems(nodes) {
+  const problems = [];
+  for (const [index, node] of nodes.entries()) {
+    const who = `node ${index + 1} (${typeof node.slug === "string" ? node.slug : "no slug"})`;
+    const check = (path, value, pattern) => {
+      if (value === void 0 || typeof value === "string" && new RegExp(pattern).test(value)) return;
+      problems.push(
+        `${who}: ${path} ${JSON.stringify(value)} is refused by the registry \u2014 it must match ${pattern} (${PATTERN_HINT[pattern]}).`
+      );
+    };
+    check("slug", node.slug, NAMESPACED_SLUG_PATTERN);
+    check("version", node.version, SEMVER_PATTERN);
+    for (const [i, port] of (node.outputs ?? []).entries()) {
+      check(`outputs[${i}].name`, port.name, SLUG_PATTERN);
+      check(`outputs[${i}].sourceFromConfig`, port.sourceFromConfig, SLUG_PATTERN);
+      check(`outputs[${i}].fallback.name`, port.fallback?.name, SLUG_PATTERN);
+    }
+    const checkField = (field, at) => {
+      check(`${at}.key`, field.key, CONFIG_KEY_PATTERN);
+      for (const [j, key] of (field.dependsOn ?? []).entries()) check(`${at}.dependsOn[${j}]`, key, CONFIG_KEY_PATTERN);
+      check(`${at}.showIf.key`, field.showIf?.key, CONFIG_KEY_PATTERN);
+      const types = field.credentialType;
+      if (Array.isArray(types)) {
+        for (const [j, type] of types.entries()) check(`${at}.credentialType[${j}]`, type, NAMESPACED_SLUG_PATTERN);
+      } else {
+        check(`${at}.credentialType`, types, NAMESPACED_SLUG_PATTERN);
+      }
+      walk(field.properties, `${at}.properties`);
+      if (field.items) checkField(field.items, `${at}.items`);
+    };
+    const walk = (fields, path) => {
+      for (const [i, field] of (fields ?? []).entries()) checkField(field, `${path}[${i}]`);
+    };
+    walk(node.config, "config");
+  }
+  return problems;
+}
 function buildManifest(nodes, credentials = [], templates = []) {
   const manifest = {
     manifestVersion: MANIFEST_VERSION,
@@ -118,5 +165,10 @@ export {
   MANIFEST_VERSION,
   packageIconProblem,
   parsePackageMeta,
+  SLUG_PATTERN,
+  NAMESPACED_SLUG_PATTERN,
+  SEMVER_PATTERN,
+  CONFIG_KEY_PATTERN,
+  nodeManifestProblems,
   buildManifest
 };

package/dist/cli.cjs

@@ -147,6 +147,53 @@ function parsePackageMeta(raw) {
     icon: icon !== "" ? icon : void 0
   };
 }
+var SLUG_PATTERN = "^[a-z][a-z0-9-]{0,62}$";
+var NAMESPACED_SLUG_PATTERN = "^[a-z][a-z0-9-]{0,62}:[a-z][a-z0-9-]{0,62}$";
+var SEMVER_PATTERN = "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.-]+)?$";
+var CONFIG_KEY_PATTERN = "^[a-zA-Z][a-zA-Z0-9-]*$";
+var PATTERN_HINT = {
+  [SLUG_PATTERN]: 'lowercase kebab-case, such as "not-found"',
+  [NAMESPACED_SLUG_PATTERN]: '"<namespace>:<name>" in lowercase kebab-case, such as "core:http-request"',
+  [SEMVER_PATTERN]: 'a semantic version, such as "1.0.0"',
+  [CONFIG_KEY_PATTERN]: 'a letter, then letters, digits or "-", such as "postalCode"'
+};
+function nodeManifestProblems(nodes) {
+  const problems = [];
+  for (const [index, node] of nodes.entries()) {
+    const who = `node ${index + 1} (${typeof node.slug === "string" ? node.slug : "no slug"})`;
+    const check = (path, value, pattern) => {
+      if (value === void 0 || typeof value === "string" && new RegExp(pattern).test(value)) return;
+      problems.push(
+        `${who}: ${path} ${JSON.stringify(value)} is refused by the registry \u2014 it must match ${pattern} (${PATTERN_HINT[pattern]}).`
+      );
+    };
+    check("slug", node.slug, NAMESPACED_SLUG_PATTERN);
+    check("version", node.version, SEMVER_PATTERN);
+    for (const [i, port] of (node.outputs ?? []).entries()) {
+      check(`outputs[${i}].name`, port.name, SLUG_PATTERN);
+      check(`outputs[${i}].sourceFromConfig`, port.sourceFromConfig, SLUG_PATTERN);
+      check(`outputs[${i}].fallback.name`, port.fallback?.name, SLUG_PATTERN);
+    }
+    const checkField = (field, at) => {
+      check(`${at}.key`, field.key, CONFIG_KEY_PATTERN);
+      for (const [j, key] of (field.dependsOn ?? []).entries()) check(`${at}.dependsOn[${j}]`, key, CONFIG_KEY_PATTERN);
+      check(`${at}.showIf.key`, field.showIf?.key, CONFIG_KEY_PATTERN);
+      const types = field.credentialType;
+      if (Array.isArray(types)) {
+        for (const [j, type] of types.entries()) check(`${at}.credentialType[${j}]`, type, NAMESPACED_SLUG_PATTERN);
+      } else {
+        check(`${at}.credentialType`, types, NAMESPACED_SLUG_PATTERN);
+      }
+      walk(field.properties, `${at}.properties`);
+      if (field.items) checkField(field.items, `${at}.items`);
+    };
+    const walk = (fields, path) => {
+      for (const [i, field] of (fields ?? []).entries()) checkField(field, `${path}[${i}]`);
+    };
+    walk(node.config, "config");
+  }
+  return problems;
+}
 function buildManifest(nodes, credentials = [], templates = []) {
   const manifest = {
     manifestVersion: MANIFEST_VERSION,
@@ -213,6 +260,8 @@ async function runManifest() {
     console.warn(`\u26A0 ${w} This will be an error in the next major version.`);
   }
   const manifest = buildManifest(mod.NODES, credentials, templates);
+  const nameProblems = nodeManifestProblems(manifest.nodes);
+  if (nameProblems.length > 0) fail(nameProblems.join("\n"));
   const outDir = (0, import_node_path2.resolve)(projectRoot, "dist");
   const outFile = (0, import_node_path2.resolve)(outDir, "manifest.json");
   fs2.mkdirSync(outDir, { recursive: true });

package/dist/cli.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import {
   buildManifest,
+  nodeManifestProblems,
   outputWarnings,
   packageIconProblem,
   parsePackageMeta
-} from "./chunk-XO73F62E.js";
+} from "./chunk-CA6JVLLF.js";
 
 // src/cli.ts
 import * as fs2 from "fs";
@@ -112,6 +113,8 @@ async function runManifest() {
     console.warn(`\u26A0 ${w} This will be an error in the next major version.`);
   }
   const manifest = buildManifest(mod.NODES, credentials, templates);
+  const nameProblems = nodeManifestProblems(manifest.nodes);
+  if (nameProblems.length > 0) fail(nameProblems.join("\n"));
   const outDir = resolve2(projectRoot, "dist");
   const outFile = resolve2(outDir, "manifest.json");
   fs2.mkdirSync(outDir, { recursive: true });

package/dist/errors.d.ts

@@ -3,3 +3,24 @@ export declare class NodeError extends Error {
     readonly meta?: Record<string, unknown>;
     constructor(code: string, message: string, meta?: Record<string, unknown>);
 }
+/**
+ * The two codes a step fails with when the VPN route it was configured with
+ * cannot be used (PO-825). Both are failures of the world around the run, not of
+ * the data a record carried, and neither is retried by the platform.
+ *
+ * - `VPN_UNAVAILABLE` — the connection exists but is not `active`;
+ *   message `VPN connection <name> is <status>`.
+ * - `VPN_ROUTE_MISSING` — the connection or the route no longer exists;
+ *   message `VPN route <connection>/<route> no longer exists`.
+ */
+export declare const VPN_UNAVAILABLE: 'VPN_UNAVAILABLE';
+export declare const VPN_ROUTE_MISSING: 'VPN_ROUTE_MISSING';
+/** Every VPN failure code, for a reader that has to recognise one. */
+export declare const VPN_ERROR_CODES: readonly ["VPN_UNAVAILABLE", "VPN_ROUTE_MISSING"];
+/** One of {@link VPN_ERROR_CODES}. */
+export type VpnErrorCode = (typeof VPN_ERROR_CODES)[number];
+/**
+ * Whether `code` is a VPN failure code, narrowing it. `VPN_ERROR_CODES.includes`
+ * does not accept a plain `string`, which is what `NodeError.code` is.
+ */
+export declare function isVpnErrorCode(code: string): code is VpnErrorCode;