@promigence/sdk 0.1.0-beta.12

package/dist/cjs/ca-guard.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__caGuardInternals = exports.guardCertChain = exports.CompromisedKeyError = void 0;
+exports.compromisedKeyCause = compromisedKeyCause;
+exports.chainHasCompromisedKey = chainHasCompromisedKey;
+exports.makeCertChainGuard = makeCertChainGuard;
+exports.guardedFetchDispatcher = guardedFetchDispatcher;
+const crypto = require("node:crypto");
+const tls = require("node:tls");
+const DISTRUSTED_SPKI_SHA256 = new Set([
+    "ebed6475c2c2d80fcb199f3fe8dd6e6b3ce60b77eb15d4e42c3dec0c6f5b5105",
+    "49dd353dc2b919a3770645117d0e60c16115e7d1bc259eefe734b00ea434fe5f",
+    "e0254c7fcdc265e2f0f8a428dabb75ab4ae039b4872d62f5ee57f0877d5a8a41",
+    "5c0660a2b164910d8ff589c18e14552e9e0ec237dcefe2cb736d41a4811f81a0",
+    "43bffa19d6ef651451f6841e019931e96f6f2eaeff28ab4b6f1ce4576de2717b",
+    "63ecefee431d49523bc1136c4e72d0206a477086caf606cd5cf025686c109cf8",
+    "ec4ffa1ad0ac88081314b7aaffef6a91f97cd57291bb5ba686c5415f5eb4f6b6",
+    "92c063d67e8f14db71d288e11266ffdaf69cbf115f7bab14f3bc2f68d25e0e30",
+]);
+const MAX_CHAIN_DEPTH = 10;
+const COMPROMISED_KEY_MESSAGE = "The server's certificate chain uses a key that is publicly known to be compromised, so the connection was refused.";
+class CompromisedKeyError extends Error {
+    constructor() {
+        super(COMPROMISED_KEY_MESSAGE);
+        this.name = "CompromisedKeyError";
+    }
+}
+exports.CompromisedKeyError = CompromisedKeyError;
+function compromisedKeyCause(err) {
+    try {
+        let e = err;
+        for (let i = 0; i < 4; i++) {
+            if (typeof e !== "object" || e === null)
+                return undefined;
+            if (e instanceof CompromisedKeyError)
+                return e;
+            e = e.cause;
+        }
+    }
+    catch {
+    }
+    return undefined;
+}
+const TEST_HASHES = new Set();
+let parseCount = 0;
+function spkiSha256(raw) {
+    parseCount++;
+    try {
+        const der = new crypto.X509Certificate(raw).publicKey.export({ type: "spki", format: "der" });
+        return crypto.createHash("sha256").update(der).digest("hex");
+    }
+    catch {
+        return undefined;
+    }
+}
+const SPKI_BY_FINGERPRINT = new Map();
+const SPKI_CACHE_MAX = 512;
+function certSpkiSha256(node, raw) {
+    const fp = node.fingerprint256;
+    if (typeof fp !== "string" || fp === "")
+        return spkiSha256(raw);
+    const hit = SPKI_BY_FINGERPRINT.get(fp);
+    if (hit !== undefined)
+        return hit;
+    const hash = spkiSha256(raw);
+    if (hash === undefined)
+        return undefined;
+    if (SPKI_BY_FINGERPRINT.size >= SPKI_CACHE_MAX) {
+        for (const oldest of SPKI_BY_FINGERPRINT.keys()) {
+            SPKI_BY_FINGERPRINT.delete(oldest);
+            break;
+        }
+    }
+    SPKI_BY_FINGERPRINT.set(fp, hash);
+    return hash;
+}
+function chainHasCompromisedKey(cert) {
+    try {
+        let node = cert;
+        const seen = new Set();
+        for (let depth = 0; node && depth < MAX_CHAIN_DEPTH; depth++) {
+            if (seen.has(node))
+                break;
+            seen.add(node);
+            const raw = node.raw;
+            if (raw !== undefined && raw.length > 0) {
+                const hash = certSpkiSha256(node, raw);
+                if (hash !== undefined && DISTRUSTED_SPKI_SHA256.has(hash))
+                    return true;
+            }
+            const issuer = node.issuerCertificate;
+            if (issuer === undefined || issuer === node)
+                break;
+            node = issuer;
+        }
+    }
+    catch {
+        return false;
+    }
+    return false;
+}
+function makeCertChainGuard(prev = tls.checkServerIdentity) {
+    return (host, cert) => {
+        const prevResult = prev(host, cert);
+        if (prevResult)
+            return prevResult;
+        return chainHasCompromisedKey(cert) ? new CompromisedKeyError() : undefined;
+    };
+}
+exports.guardCertChain = makeCertChainGuard();
+const DISPATCHER_KEYS = [Symbol.for("undici.globalDispatcher.1"), Symbol.for("undici.globalDispatcher.2")];
+let guardedAgent;
+function isNode() {
+    try {
+        const v = typeof process === "object" ? process.versions : undefined;
+        return Boolean(v?.["node"]) && !v?.["bun"] && !v?.["deno"];
+    }
+    catch {
+        return false;
+    }
+}
+function undiciAgentCtor() {
+    for (const key of DISPATCHER_KEYS) {
+        const d = globalThis[key];
+        const ctor = d?.constructor;
+        if (typeof ctor === "function" && ctor.name === "Agent")
+            return ctor;
+    }
+    return undefined;
+}
+function guardedFetchDispatcher() {
+    if (guardedAgent !== undefined)
+        return guardedAgent === null ? undefined : guardedAgent;
+    guardedAgent = null;
+    try {
+        if (!isNode())
+            return undefined;
+        const Agent = undiciAgentCtor();
+        if (Agent === undefined)
+            return undefined;
+        const agent = new Agent({ connect: { checkServerIdentity: exports.guardCertChain } });
+        if (agent !== null && typeof agent.dispatch === "function") {
+            guardedAgent = agent;
+            return agent;
+        }
+    }
+    catch {
+    }
+    return undefined;
+}
+exports.__caGuardInternals = {
+    distrustedCount() {
+        return DISTRUSTED_SPKI_SHA256.size;
+    },
+    has(hashHex) {
+        return DISTRUSTED_SPKI_SHA256.has(hashHex);
+    },
+    addForTest(hashHex) {
+        DISTRUSTED_SPKI_SHA256.add(hashHex);
+        TEST_HASHES.add(hashHex);
+    },
+    testHashes() {
+        return [...TEST_HASHES];
+    },
+    parses() {
+        return parseCount;
+    },
+    cacheSize() {
+        return SPKI_BY_FINGERPRINT.size;
+    },
+    resetAgent() {
+        guardedAgent = undefined;
+    },
+};

package/dist/cjs/caller.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `setCaller` — first-party attribution of SDK traffic.
+ *
+ * A caller is a short label naming the framework, harness or adapter driving this SDK: `cli`,
+ * `harbor`, `inspect`, or whatever you set yourself. It rides on one request header and on the
+ * `user-agent`, so we can see which integrations are actually used and build the next one where
+ * it is wanted.
+ *
+ * ## Nothing is ever auto-detected
+ *
+ * This module does not look at your process, your packages, your paths or your code, and it
+ * never will. There is no scan of `node_modules`, no walk of the module cache, no read of
+ * `argv`, no inspection of the process tree — nothing that could turn "which framework is this?"
+ * into a report about a customer's machine. Scanning a customer's process and phoning home about
+ * what is installed there is a reputational risk we are not taking, and a label we guessed would
+ * be worth less than one we were given. We only ever report a label we ship ourselves or one the
+ * customer sets on purpose.
+ *
+ * What is sent: a name, and optionally a version. That is the whole payload.
+ *
+ * ## Precedence (highest first)
+ *
+ *   1. `caller` in the client options
+ *   2. `setCaller(name, version)`
+ *   3. `PROMIGENCE_CALLER` (`name` or `name/version`)
+ *   4. the default an adapter package set with `setCaller(name, version, { default: true })`
+ *   5. none — and none is the default, so an SDK nobody configured sends no label at all
+ *
+ * ## Validation
+ *
+ * `name` must match `^[a-z0-9][a-z0-9._-]{0,31}$` after trimming and lower-casing; `version` must
+ * match `^[A-Za-z0-9.+_~-]{0,31}$`. Anything else is dropped silently — an invalid name sends no
+ * label, an invalid version sends the name alone. Telemetry never raises, never logs to stdout
+ * and never stops a request: the work is what matters, the label is not.
+ */
+/** The request header the label rides on. */
+export declare const CALLER_HEADER = "promigence-caller";
+/** `PROMIGENCE_CALLER=harbor` or `PROMIGENCE_CALLER=harbor/0.1.0`. */
+export declare const CALLER_ENV = "PROMIGENCE_CALLER";
+export declare const CALLER_NAME_RE: RegExp;
+export declare const CALLER_VERSION_RE: RegExp;
+export declare const RESERVED_CALLERS: readonly string[];
+/**
+ * The token for `name` (+ `version`), or `undefined` when the name is not a valid label.
+ * An invalid version is dropped on its own, leaving the name.
+ */
+export declare function callerToken(name: string, version?: string): string | undefined;
+/** `harbor` or `harbor/0.1.0` as one string (the env var, the `caller` option). */
+export declare function parseCallerToken(raw: string | undefined): string | undefined;
+/**
+ * Name the framework or harness driving this SDK.
+ *
+ * ```ts
+ * import { setCaller } from "promigence";
+ * setCaller("my-harness", "2.1.0");
+ * ```
+ *
+ * `{ default: true }` is for a package that ships an integration: it sets the label only for a
+ * customer who has not set one of their own, and `PROMIGENCE_CALLER` still wins over it.
+ *
+ * An unusable name is ignored. This never throws.
+ */
+export declare function setCaller(name: string, version?: string, options?: {
+    default?: boolean;
+}): void;
+/** The label that would be sent, ignoring any per-client `caller` option. */
+export declare function getCaller(): string | undefined;
+/** Everything unset again (tests). */
+export declare function clearCaller(): void;
+/** The label one client sends: its own option first, then everything `getCaller` considers. */
+export declare function resolveCaller(explicit?: string): string | undefined;
+/** `promigence/0.1.0 node/22.0.0` + ` (harbor/0.1.0)`, when there is a label to add. */
+export declare function userAgentWithCaller(userAgent: string, caller: string | undefined): string;

package/dist/cjs/caller.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESERVED_CALLERS = exports.CALLER_VERSION_RE = exports.CALLER_NAME_RE = exports.CALLER_ENV = exports.CALLER_HEADER = void 0;
+exports.callerToken = callerToken;
+exports.parseCallerToken = parseCallerToken;
+exports.setCaller = setCaller;
+exports.getCaller = getCaller;
+exports.clearCaller = clearCaller;
+exports.resolveCaller = resolveCaller;
+exports.userAgentWithCaller = userAgentWithCaller;
+exports.CALLER_HEADER = "promigence-caller";
+exports.CALLER_ENV = "PROMIGENCE_CALLER";
+exports.CALLER_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,31}$/;
+exports.CALLER_VERSION_RE = /^[A-Za-z0-9.+_~-]{0,31}$/;
+exports.RESERVED_CALLERS = [
+    "cli", "harbor", "inspect", "e2b-compat", "computesdk", "mcp",
+];
+let globalCaller;
+let defaultCaller;
+function callerToken(name, version) {
+    const n = typeof name === "string" ? name.trim().toLowerCase() : "";
+    if (!exports.CALLER_NAME_RE.test(n))
+        return undefined;
+    const v = typeof version === "string" ? version.trim() : "";
+    if (!v || !exports.CALLER_VERSION_RE.test(v))
+        return n;
+    return `${n}/${v}`;
+}
+function parseCallerToken(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    const t = raw.trim();
+    if (!t)
+        return undefined;
+    const slash = t.indexOf("/");
+    return slash < 0 ? callerToken(t) : callerToken(t.slice(0, slash), t.slice(slash + 1));
+}
+function setCaller(name, version, options) {
+    const token = callerToken(name, version);
+    if (options?.default)
+        defaultCaller = token;
+    else
+        globalCaller = token;
+}
+function getCaller() {
+    return globalCaller ?? parseCallerToken(process.env[exports.CALLER_ENV]) ?? defaultCaller;
+}
+function clearCaller() {
+    globalCaller = undefined;
+    defaultCaller = undefined;
+}
+function resolveCaller(explicit) {
+    return parseCallerToken(explicit) ?? getCaller();
+}
+function userAgentWithCaller(userAgent, caller) {
+    return caller ? `${userAgent} (${caller})` : userAgent;
+}