@thenewlabs/entangle-utils 2.11.2 → 2.11.3

package/dist/index.d.ts

@@ -4,5 +4,6 @@ export * from './validation.js';
 export * from './counters.js';
 export * from './stream-counters.js';
 export * from './version.js';
+export * from './user-agent.js';
 export * from './output.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -4,5 +4,6 @@ export * from './validation.js';
 export * from './counters.js';
 export * from './stream-counters.js';
 export * from './version.js';
+export * from './user-agent.js';
 export * from './output.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}

package/dist/user-agent.d.ts

@@ -0,0 +1,27 @@
+/** Project URL appended so an operator seeing the UA in a log can identify it. */
+export declare const USER_AGENT_URL = "https://github.com/thenewlabs/entangle";
+/** Product token for the component making the request. Add a member per new outbound caller. */
+export type UserAgentProduct = 'entangle-serve' | 'entangle-connect' | 'entangle-relay' | 'entangle';
+/**
+ * Build the UA for `product` at the CALLING package's version. Pass the calling module's
+ * `import.meta.url`; as with `packageVersion()`, the manifest is expected one level up, which
+ * holds for any module directly under `src/` (tsx dev) or `dist/` (tsc output).
+ *
+ * In a standalone bundle the runtime manifest lookup CANNOT be trusted: `import.meta.url` is
+ * empty under the CJS output format, and even once a bundler rewrites it, it points at the
+ * bundle — so `../package.json` resolves to whichever package happens to sit above the output
+ * directory rather than to the calling package. That is how a bundled `locus` came to announce
+ * `entangle-serve/0.1.0` (the Locus root manifest) instead of serve's own 2.15.1. The injected
+ * map therefore WINS over the runtime read, which stays as the tsx/tsc-build path.
+ *
+ * e.g. `entangle-serve/2.15.1 (+https://github.com/thenewlabs/entangle)`
+ */
+export declare function buildUserAgent(product: UserAgentProduct, callerModuleUrl: string): string;
+/**
+ * Headers object for a Node `ws` client or `fetch`. Lowercase key: HTTP/1.1 header names are
+ * case-insensitive, and `ws` merges its own defaults case-sensitively.
+ */
+export declare function userAgentHeaders(product: UserAgentProduct, callerModuleUrl: string): {
+    'user-agent': string;
+};
+//# sourceMappingURL=user-agent.d.ts.map

package/dist/user-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-agent.d.ts","sourceRoot":"","sources":["../src/user-agent.ts"],"names":[],"mappings":"AAgBA,kFAAkF;AAClF,eAAO,MAAM,cAAc,2CAA2C,CAAC;AAEvE,gGAAgG;AAChG,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,gBAAgB,GAAG,UAAU,CAAC;AAsCrG;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,CAGzF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,gBAAgB,EACzB,eAAe,EAAE,MAAM,GACtB;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,CAE1B"}

package/dist/user-agent.js

@@ -0,0 +1,64 @@
+/**
+ * The `User-Agent` every entangle component puts on its OWN outbound requests.
+ *
+ * Node sets no `User-Agent` by default — neither global `fetch` (undici) nor the `ws` client
+ * send one, unlike a browser. Relays and reverse proxies in front of them log the header as
+ * "-", and intrusion-prevention layers (CrowdSec et al.) treat a stream of UA-less requests as
+ * bot traffic and ban the source IP. `serve`'s registration WebSocket reconnects on a backoff
+ * loop, so a single unhappy relay produced exactly that pattern against `/agent/register`.
+ *
+ * The string is product + version only. It MUST NOT carry capIds, tokens, secrets, machine ids
+ * or paths: the relay is blind by design, and the header is the one part of a connection it
+ * always sees in cleartext. Distinguishing the products (`entangle-serve` vs `entangle-connect`)
+ * tells a relay operator which component is calling without telling them anything about who.
+ */
+import { packageVersion } from './version.js';
+/** Project URL appended so an operator seeing the UA in a log can identify it. */
+export const USER_AGENT_URL = 'https://github.com/thenewlabs/entangle';
+function buildTimeVersion(product) {
+    // `typeof` first and short-circuit: the identifier is undeclared outside a bundle, where any
+    // other reference to it would throw a ReferenceError at module load.
+    if (typeof ENTANGLE_BUILD_UA_VERSIONS !== 'object' || ENTANGLE_BUILD_UA_VERSIONS === null) {
+        return undefined;
+    }
+    const version = ENTANGLE_BUILD_UA_VERSIONS[product];
+    return typeof version === 'string' ? version : undefined;
+}
+/**
+ * Coerce a version to a single safe HTTP token, falling back to 'unknown'. Guards the two ways
+ * a bundle can degrade — a missing manifest yields `undefined`, and a lookup against an empty
+ * `import.meta` yields `''` — so the header is never `product/` or `product/undefined`. Also
+ * rejects whitespace and control characters, which would split or inject a header.
+ */
+function safeVersion(raw) {
+    if (typeof raw !== 'string')
+        return 'unknown';
+    const version = raw.trim();
+    return version !== '' && /^[\x21-\x7e]+$/.test(version) ? version : 'unknown';
+}
+/**
+ * Build the UA for `product` at the CALLING package's version. Pass the calling module's
+ * `import.meta.url`; as with `packageVersion()`, the manifest is expected one level up, which
+ * holds for any module directly under `src/` (tsx dev) or `dist/` (tsc output).
+ *
+ * In a standalone bundle the runtime manifest lookup CANNOT be trusted: `import.meta.url` is
+ * empty under the CJS output format, and even once a bundler rewrites it, it points at the
+ * bundle — so `../package.json` resolves to whichever package happens to sit above the output
+ * directory rather than to the calling package. That is how a bundled `locus` came to announce
+ * `entangle-serve/0.1.0` (the Locus root manifest) instead of serve's own 2.15.1. The injected
+ * map therefore WINS over the runtime read, which stays as the tsx/tsc-build path.
+ *
+ * e.g. `entangle-serve/2.15.1 (+https://github.com/thenewlabs/entangle)`
+ */
+export function buildUserAgent(product, callerModuleUrl) {
+    const version = safeVersion(buildTimeVersion(product) ?? packageVersion(callerModuleUrl));
+    return `${product}/${version} (+${USER_AGENT_URL})`;
+}
+/**
+ * Headers object for a Node `ws` client or `fetch`. Lowercase key: HTTP/1.1 header names are
+ * case-insensitive, and `ws` merges its own defaults case-sensitively.
+ */
+export function userAgentHeaders(product, callerModuleUrl) {
+    return { 'user-agent': buildUserAgent(product, callerModuleUrl) };
+}
+//# sourceMappingURL=user-agent.js.map

package/dist/user-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-agent.js","sourceRoot":"","sources":["../src/user-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,kFAAkF;AAClF,MAAM,CAAC,MAAM,cAAc,GAAG,wCAAwC,CAAC;AAmBvE,SAAS,gBAAgB,CAAC,OAAyB;IACjD,6FAA6F;IAC7F,qEAAqE;IACrE,IAAI,OAAO,0BAA0B,KAAK,QAAQ,IAAI,0BAA0B,KAAK,IAAI,EAAE,CAAC;QAC1F,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,OAAO,GAAI,0BAAsD,CAAC,OAAO,CAAC,CAAC;IACjF,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3D,CAAC;AAED;;;;;GAKG;AACH,SAAS,WAAW,CAAC,GAAuB;IAC1C,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC9C,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,OAAO,OAAO,KAAK,EAAE,IAAI,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAChF,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,OAAyB,EAAE,eAAuB;IAC/E,MAAM,OAAO,GAAG,WAAW,CAAC,gBAAgB,CAAC,OAAO,CAAC,IAAI,cAAc,CAAC,eAAe,CAAC,CAAC,CAAC;IAC1F,OAAO,GAAG,OAAO,IAAI,OAAO,MAAM,cAAc,GAAG,CAAC;AACtD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAyB,EACzB,eAAuB;IAEvB,OAAO,EAAE,YAAY,EAAE,cAAc,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC;AACpE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thenewlabs/entangle-utils",
-  "version": "2.11.2",
+  "version": "2.11.3",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,7 +20,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@thenewlabs/entangle-protocol": "^2.11.0",
+    "@thenewlabs/entangle-protocol": "^2.12.0",
     "dotenv": "^17.4.2",
     "pino": "^10.3.1"
   },