@veilgate/node

Node.js SDK for VeilGate. Three responsibilities:

1. Outgoing auth — attach bearer tokens or HMAC-sign server-to-server requests.
2. Decoy response headers — inject tarpit breadcrumbs into your API's outgoing responses so agents probing the API via raw HTTP find bait paths instead of real endpoints.
3. Signature verification — validate inbound HMAC signatures in tests or custom middleware.

Install

npm install @veilgate/node

Requires Node.js ≥ 18.

Usage

Bearer mode

import { bearerFetch } from "@veilgate/node";

const apiFetch = bearerFetch("vg_live_abc123");
const resp = await apiFetch("https://api.example.com/widgets");

Custom header or scheme:

const apiFetch = bearerFetch({ token: "abc123", header: "X-Api-Key", scheme: "" });

HMAC mode

import { hmacFetch } from "@veilgate/node";

const apiFetch = hmacFetch({
  clientId: "payments",
  secret: process.env.VG_SECRET!,
});

const resp = await apiFetch("https://api.example.com/charge", {
  method: "POST",
  body: JSON.stringify({ amount: 100 }),
  headers: { "Content-Type": "application/json" },
});

Decoy response middleware

Add tarpit breadcrumbs to every outgoing API response. Compatible with Express, Fastify, and raw Node http.Server — anything with res.setHeader().

import { decoyMiddleware } from "@veilgate/node";

// Express
const decoys = decoyMiddleware({ baseURL: "https://api.example.com" });
app.use(decoys);

// Runtime controls — no need to recreate the middleware
decoys.setEnabled(false);           // disable (e.g. internal health-check routes)
decoys.setEnabled(true);            // re-enable
decoys.update({ count: 5 });        // inject more paths per response
decoys.update({ baseURL: "https://new-api.example.com" }); // switch server (clears cache)
decoys.update({ paths: [          // static override — skips .well-known discovery
  { path: "/actuator/env", service: "spring-actuator" },
  { path: "/v1/secret/data/prod", service: "vault" },
]});

Agents probing the API will see response headers like:

Link: </actuator/env>; rel="help", </.env.local>; rel="related"
X-Api-Documentation: /swagger-ui.html
X-Debug-Endpoint: /api/internal/debug

Low-level decoy helpers

import { fetchDecoyPaths, decoyResponseHeaders } from "@veilgate/node";

// Fetch tarpit.paths from .well-known (60 s cache)
const paths = await fetchDecoyPaths("https://api.example.com");

// Build a header map from any path list
const headers = decoyResponseHeaders(paths, { count: 3 });
// → { Link: "...", "X-Api-Documentation": "...", "X-Debug-Endpoint": "..." }

// Attach to a raw Node response
for (const [name, value] of Object.entries(headers)) {
  res.setHeader(name, value);
}

API

bearerFetch(tokenOrOpts, fetchImpl?)

Returns a fetch-compatible function with a static bearer token attached. Does not override an existing Authorization header set by the caller.

Option	Type	Default	Description
token	string	—	Token value
header	string	"Authorization"	Header name
scheme	string	"Bearer"	Scheme prefix. Pass "" for raw-token mode

hmacFetch(opts, fetchImpl?)

Returns a fetch-compatible function that signs every request with HMAC-SHA256.

Option	Type	Default	Description
clientId	string	—	Sent in X-Veilgate-Client
secret	string	—	Shared HMAC secret
signatureHeader	string	"X-Veilgate-Signature"	Override signature header
clientHeader	string	"X-Veilgate-Client"	Override client-id header
replayWindow	number	300	Replay protection window in seconds

fetchDecoyPaths(baseURL?, fetchImpl?)

Fetches /__veilgate/.well-known and returns the tarpit.paths array. Results are cached for 60 seconds matching the server's Cache-Control: max-age=60. Returns an empty array on any error.

decoyResponseHeaders(paths, opts?)

Pure function. Builds a Record<string, string> of HTTP response headers from a path list. Headers produced:

Header	Condition
Link	Always (when linkHeader !== false). RFC 8288 rel types: help, related, about, describedby
X-Api-Documentation	When a path matching openapi/swagger is in the picked set
X-Debug-Endpoint	When a path matching debug/internal is in the picked set

Option	Type	Default	Description
count	number	3	Paths to inject
linkHeader	boolean	true	Emit Link header
serviceHeaders	boolean	true	Emit X-Api-Documentation / X-Debug-Endpoint

decoyMiddleware(opts?)

Returns a DecoyMiddlewareFn — callable as a standard middleware and extended with runtime controls.

Option	Type	Default	Description
baseURL	string	""	VeilGate server for .well-known discovery
paths	TarpitPathEntry[]	—	Static override; skips discovery
count	number	3	Paths per response
linkHeader	boolean	true	Emit Link header
serviceHeaders	boolean	true	Emit service-hinting headers
fetchImpl	typeof fetch	globalThis.fetch	Override for tests

Runtime methods on the returned function:

Method	Description
.setEnabled(boolean)	Enable or disable header injection without recreating the middleware
.update(Partial<DecoyOptions>)	Merge new options; clears discovery cache when baseURL or paths changes

signRequest(secret, method, path, body?, timestamp?)

Compute a t=<ts>,v1=<mac> signature string directly.

signHeaders(opts, method, path, body?, timestamp?)

Returns a { [header]: value } object ready to spread into your request headers.

verifySignature(signature, secret, method, path, body?, opts?)

Verify an inbound HMAC signature. Returns true only when the MAC is valid and the timestamp is within the replay window. Uses timingSafeEqual internally.

Signature Format

Canonical: <unix-ts>.<METHOD>.<path+query>.<hex(sha256(body))>
Signature: t=<ts>,v1=<hex(HMAC-SHA256(secret, canonical))>

License

MIT