varfetch 0.1.0

package/LICENSE

@@ -0,0 +1,190 @@
+EUROPEAN UNION PUBLIC LICENCE v. 1.2
+EUPL © the European Union 2007, 2016
+
+This European Union Public Licence (the ‘EUPL’) applies to the Work (as defined below) which is provided under the
+terms of this Licence. Any use of the Work, other than as authorised under this Licence is prohibited (to the extent such
+use is covered by a right of the copyright holder of the Work).
+The Work is provided under the terms of this Licence when the Licensor (as defined below) has placed the following
+notice immediately following the copyright notice for the Work:
+                          Licensed under the EUPL
+or has expressed by any other means his willingness to license under the EUPL.
+
+1.Definitions
+In this Licence, the following terms have the following meaning:
+— ‘The Licence’:this Licence.
+— ‘The Original Work’:the work or software distributed or communicated by the Licensor under this Licence, available
+as Source Code and also as Executable Code as the case may be.
+— ‘Derivative Works’:the works or software that could be created by the Licensee, based upon the Original Work or
+modifications thereof. This Licence does not define the extent of modification or dependence on the Original Work
+required in order to classify a work as a Derivative Work; this extent is determined by copyright law applicable in
+the country mentioned in Article 15.
+— ‘The Work’:the Original Work or its Derivative Works.
+— ‘The Source Code’:the human-readable form of the Work which is the most convenient for people to study and
+modify.
+— ‘The Executable Code’:any code which has generally been compiled and which is meant to be interpreted by
+a computer as a program.
+— ‘The Licensor’:the natural or legal person that distributes or communicates the Work under the Licence.
+— ‘Contributor(s)’:any natural or legal person who modifies the Work under the Licence, or otherwise contributes to
+the creation of a Derivative Work.
+— ‘The Licensee’ or ‘You’:any natural or legal person who makes any usage of the Work under the terms of the
+Licence.
+— ‘Distribution’ or ‘Communication’:any act of selling, giving, lending, renting, distributing, communicating,
+transmitting, or otherwise making available, online or offline, copies of the Work or providing access to its essential
+functionalities at the disposal of any other natural or legal person.
+
+2.Scope of the rights granted by the Licence
+The Licensor hereby grants You a worldwide, royalty-free, non-exclusive, sublicensable licence to do the following, for
+the duration of copyright vested in the Original Work:
+— use the Work in any circumstance and for all usage,
+— reproduce the Work,
+— modify the Work, and make Derivative Works based upon the Work,
+— communicate to the public, including the right to make available or display the Work or copies thereof to the public
+and perform publicly, as the case may be, the Work,
+— distribute the Work or copies thereof,
+— lend and rent the Work or copies thereof,
+— sublicense rights in the Work or copies thereof.
+Those rights can be exercised on any media, supports and formats, whether now known or later invented, as far as the
+applicable law permits so.
+In the countries where moral rights apply, the Licensor waives his right to exercise his moral right to the extent allowed
+by law in order to make effective the licence of the economic rights here above listed.
+The Licensor grants to the Licensee royalty-free, non-exclusive usage rights to any patents held by the Licensor, to the
+extent necessary to make use of the rights granted on the Work under this Licence.
+
+3.Communication of the Source Code
+The Licensor may provide the Work either in its Source Code form, or as Executable Code. If the Work is provided as
+Executable Code, the Licensor provides in addition a machine-readable copy of the Source Code of the Work along with
+each copy of the Work that the Licensor distributes or indicates, in a notice following the copyright notice attached to
+the Work, a repository where the Source Code is easily and freely accessible for as long as the Licensor continues to
+distribute or communicate the Work.
+
+4.Limitations on copyright
+Nothing in this Licence is intended to deprive the Licensee of the benefits from any exception or limitation to the
+exclusive rights of the rights owners in the Work, of the exhaustion of those rights or of other applicable limitations
+thereto.
+
+5.Obligations of the Licensee
+The grant of the rights mentioned above is subject to some restrictions and obligations imposed on the Licensee. Those
+obligations are the following:
+
+Attribution right: The Licensee shall keep intact all copyright, patent or trademarks notices and all notices that refer to
+the Licence and to the disclaimer of warranties. The Licensee must include a copy of such notices and a copy of the
+Licence with every copy of the Work he/she distributes or communicates. The Licensee must cause any Derivative Work
+to carry prominent notices stating that the Work has been modified and the date of modification.
+
+Copyleft clause: If the Licensee distributes or communicates copies of the Original Works or Derivative Works, this
+Distribution or Communication will be done under the terms of this Licence or of a later version of this Licence unless
+the Original Work is expressly distributed only under this version of the Licence — for example by communicating
+‘EUPL v. 1.2 only’. The Licensee (becoming Licensor) cannot offer or impose any additional terms or conditions on the
+Work or Derivative Work that alter or restrict the terms of the Licence.
+
+Compatibility clause: If the Licensee Distributes or Communicates Derivative Works or copies thereof based upon both
+the Work and another work licensed under a Compatible Licence, this Distribution or Communication can be done
+under the terms of this Compatible Licence. For the sake of this clause, ‘Compatible Licence’ refers to the licences listed
+in the appendix attached to this Licence. Should the Licensee's obligations under the Compatible Licence conflict with
+his/her obligations under this Licence, the obligations of the Compatible Licence shall prevail.
+
+Provision of Source Code: When distributing or communicating copies of the Work, the Licensee will provide
+a machine-readable copy of the Source Code or indicate a repository where this Source will be easily and freely available
+for as long as the Licensee continues to distribute or communicate the Work.
+Legal Protection: This Licence does not grant permission to use the trade names, trademarks, service marks, or names
+of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the copyright notice.
+
+6.Chain of Authorship
+The original Licensor warrants that the copyright in the Original Work granted hereunder is owned by him/her or
+licensed to him/her and that he/she has the power and authority to grant the Licence.
+Each Contributor warrants that the copyright in the modifications he/she brings to the Work are owned by him/her or
+licensed to him/her and that he/she has the power and authority to grant the Licence.
+Each time You accept the Licence, the original Licensor and subsequent Contributors grant You a licence to their contributions
+to the Work, under the terms of this Licence.
+
+7.Disclaimer of Warranty
+The Work is a work in progress, which is continuously improved by numerous Contributors. It is not a finished work
+and may therefore contain defects or ‘bugs’ inherent to this type of development.
+For the above reason, the Work is provided under the Licence on an ‘as is’ basis and without warranties of any kind
+concerning the Work, including without limitation merchantability, fitness for a particular purpose, absence of defects or
+errors, accuracy, non-infringement of intellectual property rights other than copyright as stated in Article 6 of this
+Licence.
+This disclaimer of warranty is an essential part of the Licence and a condition for the grant of any rights to the Work.
+
+8.Disclaimer of Liability
+Except in the cases of wilful misconduct or damages directly caused to natural persons, the Licensor will in no event be
+liable for any direct or indirect, material or moral, damages of any kind, arising out of the Licence or of the use of the
+Work, including without limitation, damages for loss of goodwill, work stoppage, computer failure or malfunction, loss
+of data or any commercial damage, even if the Licensor has been advised of the possibility of such damage. However,
+the Licensor will be liable under statutory product liability laws as far such laws apply to the Work.
+
+9.Additional agreements
+While distributing the Work, You may choose to conclude an additional agreement, defining obligations or services
+consistent with this Licence. However, if accepting obligations, You may act only on your own behalf and on your sole
+responsibility, not on behalf of the original Licensor or any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against such Contributor by
+the fact You have accepted any warranty or additional liability.
+
+10.Acceptance of the Licence
+The provisions of this Licence can be accepted by clicking on an icon ‘I agree’ placed under the bottom of a window
+displaying the text of this Licence or by affirming consent in any other similar way, in accordance with the rules of
+applicable law. Clicking on that icon indicates your clear and irrevocable acceptance of this Licence and all of its terms
+and conditions.
+Similarly, you irrevocably accept this Licence and all of its terms and conditions by exercising any rights granted to You
+by Article 2 of this Licence, such as the use of the Work, the creation by You of a Derivative Work or the Distribution
+or Communication by You of the Work or copies thereof.
+
+11.Information to the public
+In case of any Distribution or Communication of the Work by means of electronic communication by You (for example,
+by offering to download the Work from a remote location) the distribution channel or media (for example, a website)
+must at least provide to the public the information requested by the applicable law regarding the Licensor, the Licence
+and the way it may be accessible, concluded, stored and reproduced by the Licensee.
+
+12.Termination of the Licence
+The Licence and the rights granted hereunder will terminate automatically upon any breach by the Licensee of the terms
+of the Licence.
+Such a termination will not terminate the licences of any person who has received the Work from the Licensee under
+the Licence, provided such persons remain in full compliance with the Licence.
+
+13.Miscellaneous
+Without prejudice of Article 9 above, the Licence represents the complete agreement between the Parties as to the
+Work.
+If any provision of the Licence is invalid or unenforceable under applicable law, this will not affect the validity or
+enforceability of the Licence as a whole. Such provision will be construed or reformed so as necessary to make it valid
+and enforceable.
+The European Commission may publish other linguistic versions or new versions of this Licence or updated versions of
+the Appendix, so far this is required and reasonable, without reducing the scope of the rights granted by the Licence.
+New versions of the Licence will be published with a unique version number.
+All linguistic versions of this Licence, approved by the European Commission, have identical value. Parties can take
+advantage of the linguistic version of their choice.
+
+14.Jurisdiction
+Without prejudice to specific agreement between parties,
+— any litigation resulting from the interpretation of this License, arising between the European Union institutions,
+bodies, offices or agencies, as a Licensor, and any Licensee, will be subject to the jurisdiction of the Court of Justice
+of the European Union, as laid down in article 272 of the Treaty on the Functioning of the European Union,
+— any litigation arising between other parties and resulting from the interpretation of this License, will be subject to
+the exclusive jurisdiction of the competent court where the Licensor resides or conducts its primary business.
+
+15.Applicable Law
+Without prejudice to specific agreement between parties,
+— this Licence shall be governed by the law of the European Union Member State where the Licensor has his seat,
+resides or has his registered office,
+— this licence shall be governed by Belgian law if the Licensor has no seat, residence or registered office inside
+a European Union Member State.
+
+
+                                                         Appendix
+
+‘Compatible Licences’ according to Article 5 EUPL are:
+— GNU General Public License (GPL) v. 2, v. 3
+— GNU Affero General Public License (AGPL) v. 3
+— Open Software License (OSL) v. 2.1, v. 3.0
+— Eclipse Public License (EPL) v. 1.0
+— CeCILL v. 2.0, v. 2.1
+— Mozilla Public Licence (MPL) v. 2
+— GNU Lesser General Public Licence (LGPL) v. 2.1, v. 3
+— Creative Commons Attribution-ShareAlike v. 3.0 Unported (CC BY-SA 3.0) for works other than software
+— European Union Public Licence (EUPL) v. 1.1, v. 1.2
+— Québec Free and Open-Source Licence — Reciprocity (LiLiQ-R) or Strong Reciprocity (LiLiQ-R+).
+
+The European Commission may update this Appendix to later versions of the above licences without producing
+a new version of the EUPL, as long as they provide the rights granted in Article 2 of this Licence and protect the
+covered Source Code from exclusive appropriation.
+All other changes or additions to this Appendix require the production of a new EUPL version.

package/README.md

@@ -0,0 +1,48 @@
+# varfetch
+
+Fire a configured HTTP request, with `{{variable}}` values in its path, query, headers and body, and map the JSON response onto named variables. No dependencies, ESM, Node 18+.
+
+It is the small, database-free core of a "connector" feature: the application stores connectors and requests however it likes (a database, a config file) and passes them to `fireRequest`.
+
+```js
+import { fireRequest } from 'varfetch';
+
+const connector = {
+  baseUrl: 'https://api.example.org',
+  auth: { type: 'bearer', token: '...' },          // none | bearer | api_key | basic | custom
+  headers: [{ key: 'Accept-Language', value: 'fi' }],
+};
+
+const request = {
+  method: 'GET',
+  path: '/api/v1/date/{{date}}',
+  query: [{ key: 'cycles', value: 'false' }],
+  mappings: [
+    { jsonPath: '$.holyDay.name', variable: 'holyday' },
+    { jsonPath: '$.holyDay.texts.gospel.reference', variable: 'gospel' },
+  ],
+};
+
+const result = await fireRequest({ connector, request, variables: { date: '2026-10-11' } });
+// { ok: true, status: 200, values: { holyday: '...', gospel: '...' }, body: {...} }
+```
+
+## What it does
+
+- **Interpolation:** `{{name}}` in path, query values, header values, auth values and body. Missing variables become an empty string.
+- **JSON path:** `$`, `$.a.b`, `$.items[0].name`, `$['key']`. Own properties only.
+- **Mapping:** each mapping writes a string (or JSON text for objects and arrays) to a variable; `skipIfNull` (default true) leaves unresolved paths out.
+- **SSRF guard:** every URL, redirects included, is resolved and checked. Loopback, private, link-local, CGNAT, reserved and multicast addresses are blocked unless you allow them: `network: { allow: ['10.1.0.0/16', 'anno.internal:3000'], deny: ['*.blocked.example'] }`. `deny` wins over `allow`. The check happens before the connection and does not defend against DNS rebinding.
+- **Limits:** 10 s timeout and 5 MiB response by default (`timeoutMs`, `maxBytes`), at most 5 redirects, credentials and other connector headers are not forwarded to another origin.
+
+Variable values are put into the path as given. A value containing `/`, `?` or `#` changes the URL, so run untrusted values through `encodeURIComponent`, or use them in a query parameter, which is encoded for you.
+
+## API
+
+`fireRequest({ connector, request, variables, network, fetch, timeoutMs, maxBytes })` returns `{ ok, status?, values, body?, error? }` and never throws.
+
+Building blocks: `buildRequest(connector, request, variables)`, `buildAuthHeaders`, `mapResponse(mappings, body)`, `interpolate`, `interpolatePairs`, `extractVariableNames`, `evaluateJsonPath`, `checkUrlAllowed(url, { allow, deny })`, `parsePattern`. Types are in `src/index.d.ts`.
+
+## License
+
+EUPL-1.2.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "varfetch",
+  "version": "0.1.0",
+  "description": "Fire configured HTTP requests with {{variable}} interpolation, an SSRF guard and JSON path mapping of the response onto named variables.",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": ["src", "LICENSE", "README.md"],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": ["http", "variables", "api", "connector", "ssrf", "jsonpath"],
+  "author": "Juha Itäleino <jsilvanus@gmail.com>",
+  "license": "EUPL-1.2",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jsilvanus/varfetch.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jsilvanus/varfetch/issues"
+  },
+  "homepage": "https://github.com/jsilvanus/varfetch#readme"
+}

package/src/fire.js

@@ -0,0 +1,101 @@
+import { buildRequest, mapResponse } from './request.js';
+import { checkUrlAllowed } from './network-guard.js';
+
+const MAX_REDIRECTS = 5;
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+
+/**
+ * Send a request and map the response onto variables.
+ *
+ * Every URL is checked with the SSRF guard, redirects included (they are
+ * followed here, up to 5, instead of by fetch).
+ *
+ * @param {object} args
+ * @param {import('./index.js').Connector} args.connector
+ * @param {import('./index.js').RequestDef} args.request
+ * @param {Record<string, unknown>} [args.variables] values for {{name}}
+ * @param {{ allow?: string[], deny?: string[] }} [args.network] extra guard patterns, see network-guard.js
+ * @param {typeof fetch} [args.fetch]
+ * @param {number} [args.timeoutMs] default 10000
+ * @param {number} [args.maxBytes] response size limit, default 5 MiB
+ * @returns {Promise<import('./index.js').FireResult>}
+ */
+export async function fireRequest({ connector, request, variables = {}, network = {}, fetch: fetchImpl = fetch, timeoutMs, maxBytes = DEFAULT_MAX_BYTES }) {
+  let built;
+  try {
+    built = buildRequest(connector, request, variables);
+  } catch (err) {
+    return { ok: false, values: {}, error: `Invalid request: ${err.message}` };
+  }
+
+  const timeout = timeoutMs ?? request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const signal = AbortSignal.timeout(timeout);
+
+  try {
+    let url = built.url;
+    let method = built.method;
+    let body = built.body;
+    let headers = built.headers;
+    let response;
+
+    for (let hop = 0; ; hop++) {
+      const guard = await checkUrlAllowed(url, network);
+      if (!guard.allowed) return { ok: false, values: {}, error: guard.reason };
+
+      response = await fetchImpl(url, { method, headers, body, redirect: 'manual', signal });
+      const location = response.status >= 300 && response.status < 400 ? response.headers.get('location') : null;
+      if (!location) break;
+      if (hop >= MAX_REDIRECTS) return { ok: false, values: {}, status: response.status, error: 'Too many redirects' };
+
+      const next = new URL(location, url);
+      if (next.origin !== url.origin) {
+        // Credentials and every other connector header stay with the original origin.
+        headers = Object.fromEntries(Object.entries(headers).filter(([name]) => /^(content-type|accept)$/i.test(name)));
+      }
+      if (response.status === 303 || ((response.status === 301 || response.status === 302) && method === 'POST')) {
+        method = 'GET';
+        body = undefined;
+      }
+      url = next;
+    }
+
+    const text = await readLimited(response, maxBytes);
+    if (!response.ok) return { ok: false, status: response.status, values: {}, error: `HTTP ${response.status}` };
+
+    const contentType = response.headers.get('content-type') || '';
+    const wantsJson = request.responseType === 'json' || ((request.responseType ?? 'auto') === 'auto' && /json/i.test(contentType));
+    let parsed = text;
+    if (wantsJson) {
+      try {
+        parsed = text ? JSON.parse(text) : null;
+      } catch {
+        return { ok: false, status: response.status, values: {}, error: 'Response is not valid JSON' };
+      }
+    }
+    return { ok: true, status: response.status, values: mapResponse(request.mappings, parsed), body: parsed };
+  } catch (err) {
+    const message = err?.name === 'TimeoutError' ? `Timed out after ${timeout} ms` : err?.message ?? String(err);
+    return { ok: false, values: {}, error: message };
+  }
+}
+
+async function readLimited(response, maxBytes) {
+  const declared = Number(response.headers.get('content-length'));
+  if (declared > maxBytes) throw new Error(`Response larger than ${maxBytes} bytes`);
+  if (!response.body) return '';
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > maxBytes) {
+      await reader.cancel();
+      throw new Error(`Response larger than ${maxBytes} bytes`);
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}

package/src/index.d.ts

@@ -0,0 +1,75 @@
+export type Variables = Record<string, unknown>;
+export interface Pair { key: string; value: string }
+
+export type Auth =
+  | { type: 'none' }
+  | { type: 'bearer'; token: string }
+  | { type: 'api_key'; headerName: string; value: string }
+  | { type: 'basic'; username: string; password?: string }
+  | { type: 'custom'; headers: Record<string, string> };
+
+export interface Connector {
+  baseUrl: string;
+  auth?: Auth;
+  /** Extra headers sent with every request of this connector. */
+  headers?: Pair[];
+}
+
+export interface Mapping {
+  /** `$`, `$.a.b`, `$.items[0].name` or `$['key']`. */
+  jsonPath: string;
+  /** Name of the variable that receives the value. */
+  variable: string;
+  /** Default true: leave the variable out when the path does not resolve. */
+  skipIfNull?: boolean;
+}
+
+export interface RequestDef {
+  method?: string;
+  /** May contain {{name}}. */
+  path?: string;
+  query?: Pair[];
+  bodyType?: 'none' | 'json' | 'text';
+  body?: string;
+  responseType?: 'auto' | 'json' | 'text';
+  mappings?: Mapping[];
+  timeoutMs?: number;
+}
+
+export interface NetworkRules { allow?: string[]; deny?: string[] }
+
+export interface FireResult {
+  ok: boolean;
+  status?: number;
+  /** Variable name to value; non-string values are JSON text. */
+  values: Record<string, string | null>;
+  /** Parsed JSON, or the text for a non-JSON response. */
+  body?: unknown;
+  error?: string;
+}
+
+export function interpolate(text: string, variables?: Variables): string;
+export function interpolatePairs(pairs: Pair[] | undefined, variables?: Variables): Pair[];
+export function extractVariableNames(text: string): string[];
+export function evaluateJsonPath(data: unknown, path: string): unknown;
+export function parsePattern(pattern: string): { kind: 'host' | 'ip' | 'cidr'; value: string; port: number | null };
+export function checkUrlAllowed(
+  url: URL,
+  options?: NetworkRules & { lookup?: (host: string, opts: { all: true; verbatim: true }) => Promise<Array<{ address: string; family: number }>> },
+): Promise<{ allowed: boolean; reason?: string }>;
+export function buildAuthHeaders(auth: Auth | undefined, variables?: Variables): Record<string, string>;
+export function buildRequest(
+  connector: Connector,
+  request: RequestDef,
+  variables?: Variables,
+): { url: URL; method: string; headers: Record<string, string>; body?: string };
+export function mapResponse(mappings: Mapping[] | undefined, body: unknown): Record<string, string | null>;
+export function fireRequest(args: {
+  connector: Connector;
+  request: RequestDef;
+  variables?: Variables;
+  network?: NetworkRules;
+  fetch?: typeof fetch;
+  timeoutMs?: number;
+  maxBytes?: number;
+}): Promise<FireResult>;

package/src/index.js

@@ -0,0 +1,5 @@
+export { interpolate, interpolatePairs, extractVariableNames } from './interpolate.js';
+export { evaluateJsonPath } from './json-path.js';
+export { checkUrlAllowed, parsePattern } from './network-guard.js';
+export { buildRequest, buildAuthHeaders, mapResponse } from './request.js';
+export { fireRequest } from './fire.js';

package/src/interpolate.js

@@ -0,0 +1,37 @@
+/**
+ * {{name}} interpolation. Pure: reads whatever a variable currently holds.
+ */
+
+const VAR_RE = /\{\{\s*([\p{L}_][\p{L}\p{N}_-]*)\s*\}\}/gu;
+
+/**
+ * Replace every {{name}} in a string with its value from `variables`.
+ * A missing variable renders as an empty string.
+ * @param {string} text
+ * @param {Record<string, unknown>} [variables]
+ */
+export function interpolate(text, variables) {
+  if (typeof text !== 'string' || !text.includes('{{')) return text;
+  return text.replace(VAR_RE, (_match, name) => {
+    const value = variables?.[name];
+    return value === undefined || value === null ? '' : String(value);
+  });
+}
+
+/**
+ * Interpolate the value of each `{ key, value }` pair (headers and query parameters).
+ * @param {Array<{ key: string, value: string }>} pairs
+ * @param {Record<string, unknown>} [variables]
+ */
+export function interpolatePairs(pairs, variables) {
+  if (!Array.isArray(pairs)) return [];
+  return pairs.map(({ key, value }) => ({ key, value: interpolate(value, variables) }));
+}
+
+/** Unique {{name}} references of a string, in order of first use. */
+export function extractVariableNames(text) {
+  if (typeof text !== 'string') return [];
+  const names = new Set();
+  for (const match of text.matchAll(VAR_RE)) names.add(match[1]);
+  return [...names];
+}

package/src/json-path.js

@@ -0,0 +1,38 @@
+/**
+ * Minimal JSONPath subset: `$` (whole body), dot access (`$.foo.bar`), numeric
+ * index (`$.items[0].name`) and quoted keys (`$['weird key']`). No wildcards,
+ * filters or recursive descent.
+ *
+ * @param {unknown} data parsed JSON body
+ * @param {string} path
+ * @returns {unknown} the value, or undefined when the path does not resolve
+ */
+export function evaluateJsonPath(data, path) {
+  if (!path || path === '$') return data;
+
+  let current = data;
+  for (const token of tokenize(path)) {
+    if (current === undefined || current === null) return undefined;
+    // Own properties only, so paths like `$.constructor` or `$.__proto__` resolve to nothing.
+    if (!Object.prototype.hasOwnProperty.call(Object(current), token)) return undefined;
+    current = current[token];
+  }
+  return current;
+}
+
+function tokenize(path) {
+  let rest = path.trim();
+  if (rest.startsWith('$')) rest = rest.slice(1);
+  if (rest.startsWith('.')) rest = rest.slice(1);
+
+  const tokens = [];
+  const re = /([^[.\]]+)|\[(\d+)\]|\['([^']*)'\]|\["([^"]*)"\]/g;
+  let m;
+  while ((m = re.exec(rest)) !== null) {
+    if (m[1] !== undefined) tokens.push(m[1]);
+    else if (m[2] !== undefined) tokens.push(Number(m[2]));
+    else if (m[3] !== undefined) tokens.push(m[3]);
+    else if (m[4] !== undefined) tokens.push(m[4]);
+  }
+  return tokens;
+}

package/src/network-guard.js

@@ -0,0 +1,163 @@
+/**
+ * Outbound request SSRF guard.
+ *
+ * Without it, a connector's base URL is user-controlled and the server would
+ * fetch whatever it points at (cloud metadata endpoints, internal services).
+ *
+ * Defaults: block loopback, private, link-local, CGNAT, reserved and multicast
+ * addresses. The check runs on the DNS-resolved addresses, not only on the
+ * hostname string, so a public-looking name that resolves to a private IP is
+ * caught too. Callers add their own `allow` and `deny` patterns on top.
+ *
+ * Evaluation order (first match wins):
+ *   1. scheme other than http/https -> blocked, no override
+ *   2. a `deny` pattern matches     -> blocked
+ *   3. an `allow` pattern matches   -> allowed
+ *   4. resolves to a restricted address -> blocked
+ *   5. otherwise                    -> allowed
+ *
+ * Pattern syntax:
+ *   - exact hostname:       "api.example.com" or "api.example.com:8443"
+ *   - wildcard subdomain:   "*.example.com"
+ *   - exact IP:             "127.0.0.1" or "127.0.0.1:11434"
+ *   - CIDR:                 "10.0.0.0/8" or "[fc00::]/7"
+ *   - bracketed IPv6 + port "[::1]:11434"
+ * A pattern without a port matches that host or IP on any port.
+ *
+ * The addresses are resolved once, before the fetch. This does not defend
+ * against DNS rebinding between the check and the connection.
+ */
+import { BlockList, isIP } from 'node:net';
+import { lookup as dnsLookup } from 'node:dns/promises';
+
+const DEFAULT_BLOCKED_V4 = [
+  ['0.0.0.0', 8],       // "this network" / unspecified
+  ['10.0.0.0', 8],      // private
+  ['100.64.0.0', 10],   // carrier-grade NAT
+  ['127.0.0.0', 8],     // loopback
+  ['169.254.0.0', 16],  // link-local — includes cloud metadata (169.254.169.254)
+  ['172.16.0.0', 12],   // private
+  ['192.0.0.0', 24],    // IETF protocol assignments
+  ['192.168.0.0', 16],  // private
+  ['198.18.0.0', 15],   // benchmarking
+  ['224.0.0.0', 4],     // multicast
+  ['240.0.0.0', 4],     // reserved
+];
+const DEFAULT_BLOCKED_V6 = [
+  ['::1', 128],   // loopback
+  ['::', 128],    // unspecified
+  ['fc00::', 7],  // unique local (ULA)
+  ['fe80::', 10], // link-local
+  ['ff00::', 8],  // multicast
+  // No explicit IPv4-mapped (::ffff:x.x.x.x) rule needed: net.BlockList
+  // already matches a mapped address checked as 'ipv6' against the
+  // corresponding plain-IPv4 rule above checked as 'ipv4' — adding an
+  // explicit ::ffff:0:0/96 rule here double-counts that and, empirically,
+  // corrupts unrelated 'ipv4' checks against the same BlockList instance.
+];
+
+const defaultBlockList = new BlockList();
+for (const [addr, prefix] of DEFAULT_BLOCKED_V4) defaultBlockList.addSubnet(addr, prefix, 'ipv4');
+for (const [addr, prefix] of DEFAULT_BLOCKED_V6) defaultBlockList.addSubnet(addr, prefix, 'ipv6');
+
+function isDefaultRestricted(address, family) {
+  return defaultBlockList.check(address, family === 6 ? 'ipv6' : 'ipv4');
+}
+
+/** Parse a rule pattern into { kind: 'host'|'ip'|'cidr', value, port|null }. */
+export function parsePattern(pattern) {
+  let value = pattern.trim();
+  let port = null;
+
+  if (value.startsWith('[')) {
+    const close = value.indexOf(']');
+    if (close !== -1) {
+      const host = value.slice(1, close);
+      const rest = value.slice(close + 1);
+      const portMatch = rest.match(/^:(\d+)$/);
+      value = host;
+      if (portMatch) port = Number(portMatch[1]);
+    }
+  } else {
+    const lastColon = value.lastIndexOf(':');
+    if (lastColon > -1) {
+      const maybePort = value.slice(lastColon + 1);
+      const maybeHost = value.slice(0, lastColon);
+      // Only treat trailing ":N" as a port if the remainder isn't itself a
+      // bare (colon-bearing) IPv6 literal.
+      if (/^\d+$/.test(maybePort) && !maybeHost.includes(':')) {
+        value = maybeHost;
+        port = Number(maybePort);
+      }
+    }
+  }
+
+  if (value.includes('/')) return { kind: 'cidr', value, port };
+  if (isIP(value)) return { kind: 'ip', value, port };
+  return { kind: 'host', value: value.toLowerCase(), port };
+}
+
+function hostMatches(pattern, hostname) {
+  if (pattern.startsWith('*.')) {
+    const suffix = pattern.slice(2);
+    return hostname === suffix || hostname.endsWith(`.${suffix}`);
+  }
+  return pattern === hostname;
+}
+
+function ruleMatches(pattern, { hostname, addresses, port }) {
+  const parsed = parsePattern(pattern);
+  if (parsed.port != null && parsed.port !== port) return false;
+
+  if (parsed.kind === 'host') return hostMatches(parsed.value, hostname);
+  if (parsed.kind === 'ip') return addresses.some((a) => a.address === parsed.value);
+
+  // CIDR
+  try {
+    const [net, prefixStr] = parsed.value.split('/');
+    const prefix = Number(prefixStr);
+    const family = isIP(net) === 6 ? 'ipv6' : 'ipv4';
+    const bl = new BlockList();
+    bl.addSubnet(net, prefix, family);
+    return addresses.some((a) => bl.check(a.address, a.family === 6 ? 'ipv6' : 'ipv4'));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {URL} url
+ * @param {{ allow?: string[], deny?: string[], lookup?: typeof dnsLookup }} [options]
+ * @returns {Promise<{ allowed: boolean, reason?: string }>}
+ */
+export async function checkUrlAllowed(url, { allow = [], deny = [], lookup = dnsLookup } = {}) {
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    return { allowed: false, reason: `Unsupported protocol: ${url.protocol}` };
+  }
+
+  // WHATWG URL keeps brackets around an IPv6 literal in .hostname ("[::1]").
+  const hostname = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+  const port = Number(url.port) || (url.protocol === 'https:' ? 443 : 80);
+
+  let addresses;
+  try {
+    addresses = await lookup(hostname, { all: true, verbatim: true });
+  } catch {
+    addresses = [];
+  }
+  if (addresses.length === 0) {
+    return { allowed: false, reason: `Could not resolve host: ${hostname}` };
+  }
+
+  const match = { hostname, addresses, port };
+  if (deny.some((pattern) => ruleMatches(pattern, match))) {
+    return { allowed: false, reason: 'Blocked by network policy' };
+  }
+  if (allow.some((pattern) => ruleMatches(pattern, match))) {
+    return { allowed: true };
+  }
+  if (addresses.some((a) => isDefaultRestricted(a.address, a.family))) {
+    return { allowed: false, reason: 'Blocked: target resolves to a private/internal/reserved address' };
+  }
+  return { allowed: true };
+}

package/src/request.js

@@ -0,0 +1,85 @@
+import { interpolate, interpolatePairs } from './interpolate.js';
+import { evaluateJsonPath } from './json-path.js';
+
+/**
+ * Headers a connector's auth settings add.
+ * `auth` is `{ type: 'none' }`, `{ type: 'bearer', token }`, `{ type: 'api_key', headerName, value }`,
+ * `{ type: 'basic', username, password }` or `{ type: 'custom', headers: { name: value } }`.
+ * Values are interpolated, so `{{token}}` works.
+ */
+export function buildAuthHeaders(auth, variables) {
+  if (!auth) return {};
+  switch (auth.type) {
+    case 'bearer':
+      return auth.token ? { Authorization: `Bearer ${interpolate(auth.token, variables)}` } : {};
+    case 'api_key':
+      return auth.headerName ? { [auth.headerName]: interpolate(auth.value ?? '', variables) } : {};
+    case 'basic': {
+      if (!auth.username) return {};
+      const raw = `${interpolate(auth.username, variables)}:${interpolate(auth.password ?? '', variables)}`;
+      return { Authorization: `Basic ${Buffer.from(raw).toString('base64')}` };
+    }
+    case 'custom':
+      return auth.headers && typeof auth.headers === 'object'
+        ? Object.fromEntries(Object.entries(auth.headers).map(([name, value]) => [name, interpolate(String(value), variables)]))
+        : {};
+    default:
+      return {};
+  }
+}
+
+/**
+ * Build the URL, method, headers and body of a request without sending it.
+ * Path, query, headers and body are interpolated with `variables`.
+ *
+ * Variable values are put into the path as given, so a value containing `/`,
+ * `?` or `#` changes the URL. Pass untrusted values through `encodeURIComponent`
+ * yourself, or write `{{name}}` into a query parameter, which is encoded for you.
+ *
+ * @param {import('./index.js').Connector} connector
+ * @param {import('./index.js').RequestDef} request
+ * @param {Record<string, unknown>} [variables]
+ */
+export function buildRequest(connector, request, variables = {}) {
+  const base = connector.baseUrl.replace(/\/+$/, '');
+  const path = interpolate(request.path || '', variables);
+  const url = new URL(base + (path.startsWith('/') ? path : `/${path}`));
+  for (const { key, value } of interpolatePairs(request.query, variables)) {
+    if (key) url.searchParams.append(key, value ?? '');
+  }
+
+  const headers = {
+    ...Object.fromEntries(interpolatePairs(connector.headers, variables).filter((p) => p.key).map(({ key, value }) => [key, value])),
+    ...buildAuthHeaders(connector.auth, variables),
+  };
+
+  const method = (request.method || 'GET').toUpperCase();
+  let body;
+  if (request.bodyType && request.bodyType !== 'none' && request.body && method !== 'GET' && method !== 'HEAD') {
+    body = interpolate(request.body, variables);
+    const hasContentType = Object.keys(headers).some((name) => name.toLowerCase() === 'content-type');
+    if (!hasContentType) headers['Content-Type'] = request.bodyType === 'json' ? 'application/json' : 'text/plain';
+  }
+
+  return { url, method, headers, body };
+}
+
+/**
+ * Map a response body onto variables with the request's mappings.
+ * A non-string value is stored as JSON text. With `skipIfNull` (default true) an
+ * unresolved path leaves the variable out; otherwise it is `null`.
+ *
+ * @param {import('./index.js').Mapping[]} mappings
+ * @param {unknown} body parsed JSON, or the response text
+ * @returns {Record<string, string | null>}
+ */
+export function mapResponse(mappings, body) {
+  const values = {};
+  for (const mapping of mappings ?? []) {
+    const extracted = evaluateJsonPath(body, mapping.jsonPath);
+    const missing = extracted === undefined || extracted === null;
+    if (missing && mapping.skipIfNull !== false) continue;
+    values[mapping.variable] = missing ? null : typeof extracted === 'string' ? extracted : JSON.stringify(extracted);
+  }
+  return values;
+}