@juspay/neurolink 13.8.16 → 13.8.18

package/dist/utils/attachmentPolicy.js

@@ -0,0 +1,327 @@
+/**
+ * Attachment policy — one answer for every SDK loader that turns a
+ * caller-supplied string into bytes.
+ *
+ * Two primitives, both policy-aware:
+ *
+ *   - {@link readAttachmentFile}: realpath containment in `allowedRoots`
+ *     (when configured), `O_NOFOLLOW` open on the real path, regular files
+ *     only, size-capped read that notices a file growing under it.
+ *   - {@link downloadAttachment}: `safeDownloadWithMeta` with the policy's
+ *     URL switches — HTTPS-only and public hosts by default, redirects
+ *     re-validated per hop, caller headers never replayed across one.
+ *
+ * The policy itself is resolved by {@link resolveAttachmentPolicy} from the
+ * constructor's `attachments` config and the `NEUROLINK_ATTACHMENT_*`
+ * variables, and travels on the per-call options (`attachmentPolicy`). A
+ * loader that is reached without one — a host calling `WebLoader` directly, a
+ * processor used on its own — falls back to the environment-derived default,
+ * so the operator switches apply everywhere.
+ *
+ * @module utils/attachmentPolicy
+ */
+import { constants as fsConstants } from "node:fs";
+import { open, realpath } from "node:fs/promises";
+import { basename, delimiter as pathDelimiter, isAbsolute, relative, resolve as resolvePath, sep, } from "node:path";
+import { logger } from "./logger.js";
+import { redactUrlForError } from "./logSanitize.js";
+import { defaultRedirectHops, safeDownloadWithMeta } from "./safeFetch.js";
+const POLICY_KIND = "neurolink-attachment-policy";
+/** Bytes read per `handle.read()` while draining a file under its cap. */
+const READ_CHUNK_BYTES = 1024 * 1024;
+const ENV_ROOTS = "NEUROLINK_ATTACHMENT_ROOTS";
+const ENV_ALLOW_INSECURE = "NEUROLINK_ATTACHMENT_ALLOW_INSECURE_URLS";
+const ENV_ALLOW_PRIVATE = "NEUROLINK_ATTACHMENT_ALLOW_PRIVATE_NETWORK";
+const ENV_FOLLOW_REDIRECTS = "NEUROLINK_ATTACHMENT_FOLLOW_REDIRECTS";
+const ENV_MAX_BYTES = "NEUROLINK_ATTACHMENT_MAX_BYTES";
+/**
+ * An error the loaders throw when the policy refuses an attachment. Carries a
+ * stable `code`; the message names the option that would allow the read.
+ */
+export class AttachmentRefusedError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "AttachmentRefusedError";
+        this.code = code;
+    }
+}
+function envFlag(name) {
+    const raw = process.env[name];
+    if (raw === undefined) {
+        return undefined;
+    }
+    const value = raw.trim().toLowerCase();
+    if (value === "" || value === "0" || value === "false" || value === "no") {
+        return false;
+    }
+    return true;
+}
+function envRoots() {
+    const raw = process.env[ENV_ROOTS];
+    if (raw === undefined || raw.trim() === "") {
+        return undefined;
+    }
+    // `path.delimiter` is `:` on POSIX and `;` on Windows; accept both so a
+    // value copied between platforms still parses.
+    const roots = raw
+        .split(/[;:]/)
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    if (pathDelimiter === ";" && roots.length > 0) {
+        // On Windows a drive letter also contains `:`; re-split on `;` only.
+        return raw
+            .split(";")
+            .map((part) => part.trim())
+            .filter((part) => part.length > 0);
+    }
+    return roots.length > 0 ? roots : undefined;
+}
+function envMaxBytes() {
+    const raw = process.env[ENV_MAX_BYTES];
+    if (raw === undefined || raw.trim() === "") {
+        return undefined;
+    }
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : undefined;
+}
+/**
+ * Resolve the policy an instance runs under. An explicit config field wins
+ * over its environment variable; the defaults are the safe ones.
+ */
+export function resolveAttachmentPolicy(config) {
+    const roots = config?.allowedRoots ?? envRoots();
+    const resolvedRoots = roots && roots.length > 0
+        ? roots.map((root) => resolvePath(root))
+        : undefined;
+    const maxBytes = config?.maxBytes !== undefined && config.maxBytes > 0
+        ? Math.floor(config.maxBytes)
+        : envMaxBytes();
+    return Object.freeze({
+        kind: POLICY_KIND,
+        allowedRoots: resolvedRoots ? Object.freeze(resolvedRoots) : undefined,
+        allowInsecureUrls: config?.allowInsecureUrls ?? envFlag(ENV_ALLOW_INSECURE) ?? false,
+        allowPrivateNetwork: config?.allowPrivateNetwork ?? envFlag(ENV_ALLOW_PRIVATE) ?? false,
+        followRedirects: config?.followRedirects ?? envFlag(ENV_FOLLOW_REDIRECTS) ?? true,
+        maxBytes,
+    });
+}
+/** Runtime guard for a policy that travelled on an untyped options bag. */
+export function isAttachmentPolicy(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.kind === POLICY_KIND);
+}
+/**
+ * The policy stamped on a call's options, or the environment-derived default.
+ * Accepts any options bag so loaders deep in the file pipeline can read it off
+ * whatever reached them.
+ */
+export function getAttachmentPolicy(carrier) {
+    const stamped = carrier?.attachmentPolicy;
+    return isAttachmentPolicy(stamped) ? stamped : resolveAttachmentPolicy();
+}
+/** The lower of a loader's own cap and the policy's global cap. */
+export function effectiveAttachmentCap(policy, loaderCap) {
+    return policy.maxBytes !== undefined
+        ? Math.min(loaderCap, policy.maxBytes)
+        : loaderCap;
+}
+// ---------------------------------------------------------------------------
+// Local files
+// ---------------------------------------------------------------------------
+let warnedUnrestrictedRoots = false;
+/**
+ * Reset the one-time "no roots configured" warning. Test hook.
+ * @internal
+ */
+export function resetAttachmentRootsWarning() {
+    warnedUnrestrictedRoots = false;
+}
+function warnUnrestrictedOnce(label) {
+    if (warnedUnrestrictedRoots) {
+        return;
+    }
+    warnedUnrestrictedRoots = true;
+    logger.warn(`[NeuroLink] Reading a local ${label} with no attachment roots configured. ` +
+        "Any readable file on this host can be attached by naming its path. " +
+        "If paths come from untrusted callers, set `attachments.allowedRoots` " +
+        `on the NeuroLink instance or the ${ENV_ROOTS} environment variable.`);
+}
+function isUnder(candidate, root) {
+    const rel = relative(root, candidate);
+    return (rel === "" ||
+        (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel)));
+}
+/**
+ * Check `filePath` against the policy's roots and return the real path to
+ * open. Without roots the real path is still resolved (so the later
+ * `O_NOFOLLOW` open behaves identically for a symlinked input), and the
+ * one-time warning fires.
+ *
+ * @throws {AttachmentRefusedError} `ATTACHMENT_OUTSIDE_ROOTS`
+ */
+export async function resolveAttachmentPath(filePath, policy, label) {
+    const lexical = resolvePath(filePath);
+    const roots = policy.allowedRoots;
+    if (!roots || roots.length === 0) {
+        warnUnrestrictedOnce(label);
+        // Without roots there is no boundary whose shape a message could leak, so
+        // the OS error (ENOENT, EACCES, ELOOP) surfaces unchanged for callers to map.
+        return await realpath(lexical);
+    }
+    const denied = () => new AttachmentRefusedError("ATTACHMENT_OUTSIDE_ROOTS", `Access denied: ${label} "${basename(filePath)}" is outside the configured attachment roots (attachments.allowedRoots / ${ENV_ROOTS})`);
+    const realRoots = (await Promise.all(roots.map(async (root) => {
+        try {
+            return [root, await realpath(root)];
+        }
+        catch {
+            return [root];
+        }
+    }))).flat();
+    // Lexical check first, so a path outside every root is refused before the
+    // file system is consulted and the answer for a missing file and a
+    // forbidden one is the same.
+    if (!realRoots.some((root) => isUnder(lexical, root))) {
+        throw denied();
+    }
+    let real;
+    try {
+        real = await realpath(lexical);
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT" || code === "ENOTDIR") {
+            throw error;
+        }
+        throw denied();
+    }
+    if (!realRoots.some((root) => isUnder(real, root))) {
+        throw denied();
+    }
+    return real;
+}
+/**
+ * Read the whole file, refusing one that outgrew `limit` since it was
+ * measured: reads one byte past the limit, so growth is seen, not buffered.
+ */
+async function readWithinLimit(handle, limit) {
+    const chunks = [];
+    let total = 0;
+    while (total <= limit) {
+        const chunk = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, limit + 1 - total));
+        const { bytesRead } = await handle.read(chunk, 0, chunk.length, total);
+        if (bytesRead === 0) {
+            break;
+        }
+        chunks.push(chunk.subarray(0, bytesRead));
+        total += bytesRead;
+    }
+    if (total > limit) {
+        return null;
+    }
+    return Buffer.concat(chunks, total);
+}
+/**
+ * Read a local attachment under the policy.
+ *
+ * Containment is judged on the real path (see {@link resolveAttachmentPath});
+ * the open is `O_NOFOLLOW | O_NONBLOCK` on that real path so a symlink swapped
+ * in after the check is refused by the kernel and a FIFO cannot park a worker;
+ * the descriptor is then stat'd (regular files only, size under the cap) and
+ * drained under the same cap.
+ *
+ * @throws {AttachmentRefusedError} with `ATTACHMENT_OUTSIDE_ROOTS`,
+ *   `ATTACHMENT_NOT_A_FILE` or `ATTACHMENT_TOO_LARGE`; other file-system
+ *   errors (ENOENT, EACCES, ELOOP, …) propagate unchanged.
+ */
+export async function readAttachmentFile(filePath, options) {
+    const policy = options.policy ?? resolveAttachmentPolicy();
+    const limit = effectiveAttachmentCap(policy, options.maxBytes);
+    const real = await resolveAttachmentPath(filePath, policy, options.label);
+    const handle = await open(real, fsConstants.O_RDONLY |
+        (fsConstants.O_NOFOLLOW ?? 0) |
+        (fsConstants.O_NONBLOCK ?? 0));
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile()) {
+            throw new AttachmentRefusedError("ATTACHMENT_NOT_A_FILE", `Not a file: ${options.label} "${basename(filePath)}"`);
+        }
+        if (stat.size > limit) {
+            throw new AttachmentRefusedError("ATTACHMENT_TOO_LARGE", `${options.label} "${basename(filePath)}" is ${stat.size} bytes; the limit is ${limit} bytes`);
+        }
+        const buffer = await readWithinLimit(handle, limit);
+        if (buffer === null) {
+            throw new AttachmentRefusedError("ATTACHMENT_TOO_LARGE", `${options.label} "${basename(filePath)}" grew past the ${limit}-byte limit while being read`);
+        }
+        return { buffer, realPath: real };
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+// ---------------------------------------------------------------------------
+// URLs
+// ---------------------------------------------------------------------------
+/**
+ * Quick scheme check that names the switch, so a refused `http://` URL tells
+ * the caller what to set rather than only that HTTPS is required.
+ *
+ * @throws {AttachmentRefusedError} `ATTACHMENT_URL_REFUSED`
+ */
+export function assertAttachmentUrlScheme(url, policy, label) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new AttachmentRefusedError("ATTACHMENT_URL_REFUSED", `${label}: "${redactUrlForError(url)}" is not a valid URL`);
+    }
+    if (parsed.protocol === "https:") {
+        return;
+    }
+    if (parsed.protocol === "http:") {
+        if (policy.allowInsecureUrls) {
+            return;
+        }
+        throw new AttachmentRefusedError("ATTACHMENT_URL_REFUSED", `${label}: plain http:// URLs are refused by default (${redactUrlForError(url)}). ` +
+            `Set attachments.allowInsecureUrls on the NeuroLink instance or ${ENV_ALLOW_INSECURE}=1 to allow them.`);
+    }
+    throw new AttachmentRefusedError("ATTACHMENT_URL_REFUSED", `${label}: only http(s) URLs can be fetched; got "${parsed.protocol}//"`);
+}
+/**
+ * Download a caller-supplied URL under the policy. Builds on
+ * `safeDownloadWithMeta`: DNS-pinned connection, bounded body, redirects only
+ * when the policy allows and then re-validated per hop with the caller's
+ * headers dropped.
+ *
+ * @throws {AttachmentRefusedError} `ATTACHMENT_URL_REFUSED` when the URL is
+ *   refused by the policy or the SSRF guard; transport and HTTP errors
+ *   propagate as plain errors from `safeDownloadWithMeta`.
+ */
+export async function downloadAttachment(url, options) {
+    const policy = options.policy ?? resolveAttachmentPolicy();
+    assertAttachmentUrlScheme(url, policy, options.label);
+    try {
+        return await safeDownloadWithMeta(url, {
+            maxBytes: effectiveAttachmentCap(policy, options.maxBytes),
+            label: options.label,
+            headers: options.headers,
+            timeoutMs: options.timeoutMs,
+            signal: options.signal,
+            method: options.method,
+            maxRedirects: defaultRedirectHops(policy.followRedirects),
+            allowInsecure: policy.allowInsecureUrls,
+            allowPrivateNetwork: policy.allowPrivateNetwork,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (/rejected:|blocked range|is permitted|internal host|single-label/.test(message)) {
+            throw new AttachmentRefusedError("ATTACHMENT_URL_REFUSED", `${options.label}: ${message}. ` +
+                `Private, loopback and link-local targets need attachments.allowPrivateNetwork (${ENV_ALLOW_PRIVATE}=1); ` +
+                `plain http needs attachments.allowInsecureUrls (${ENV_ALLOW_INSECURE}=1).`, error);
+        }
+        throw error;
+    }
+}

package/dist/utils/dotenvBootstrap.d.ts

@@ -1,25 +1,54 @@
 /**
- * Implicit `.env` bootstrap, shared by the SDK entry point and the CLI.
+ * Implicit `.env` bootstrap for the CLI, and an explicit one for SDK hosts.
  *
- * Both sites used to call dotenv's `config()` with no options beyond
- * `quiet`, and a direct `config()` call does NOT read `DOTENV_CONFIG_PATH`
- * — only dotenv's own `dotenv/config` preload entry does. So the strip this
- * repo documents and uses to vet suites,
+ * Who loads `.env`:
  *
- *     env -i HOME=… PATH=… CI=true DOTENV_CONFIG_PATH=/dev/null …
+ * - The **CLI** loads `<cwd>/.env` at startup (or `DOTENV_CONFIG_PATH`),
+ *   because a terminal session in a project directory is the use case the
+ *   file exists for. `NEUROLINK_DOTENV=0` turns that off.
+ * - The **SDK** does not. Importing a library must not read the working
+ *   directory: a dependency that runs inside an untrusted checkout would
+ *   otherwise pick up that checkout's `.env`. A host that wants the old
+ *   behaviour calls `loadDotenv()` itself, or starts the process with
+ *   `NEUROLINK_DOTENV=1` in the real environment (the variable cannot come
+ *   from the file it enables).
  *
- * stripped nothing the moment a suite imported the built SDK: importing
- * `dist/index.js` loads `src/lib/neurolink.ts`, which loaded `.env` from the
- * working directory regardless. A credential the strip was supposed to
- * remove was present at every read site, and a suite that only passes
- * because of it looks identical to one that does not need it. See #1744;
- * the CI-only failure in #1735 is what surfaced it.
+ * What is refused even when a file is loaded. dotenv never overrides a
+ * variable that is already set, but it sets every one that is not — and
+ * among those are the variables that decide *where* a request goes: the
+ * provider `*_BASE_URL` / `*_ENDPOINT(S)` overrides, `NEUROLINK_*_DIR`
+ * directories, and `DOTENV_CONFIG_PATH`. A `.env` that supplies one of them
+ * can redirect a key exported in the shell to a host of its choosing. So,
+ * for exactly those names, the file has to be trustworthy: owned by the
+ * current user and not group/world-writable. Otherwise they are deleted
+ * again and named on stderr. When they are kept, a one-line notice says
+ * which ones the file set.
  *
- * Honouring the variable here makes that strip real. It is additive: with
- * `DOTENV_CONFIG_PATH` unset — which is every existing caller, SDK consumers
- * included — this does exactly what it did before, loading `.env` from the
- * current working directory. Only a caller that explicitly sets the variable
- * sees a difference, and what it then sees is dotenv's own documented
- * meaning for it.
+ * `DOTENV_CONFIG_PATH` is honoured because a direct `config()` call does not
+ * read it on its own (only dotenv's `dotenv/config` preload does), and the
+ * test strip `DOTENV_CONFIG_PATH=/dev/null` depends on it (#1744).
  */
-export declare function loadProcessDotenv(): Promise<void>;
+import type { DotenvBootstrapOptions, DotenvBootstrapResult } from "../types/index.js";
+/** `0` / `false` disables every implicit load; `1` / `true` opts the SDK in. */
+export declare const DOTENV_TOGGLE_ENV = "NEUROLINK_DOTENV";
+/**
+ * Names whose value decides where traffic or file access goes. Built from
+ * the provider descriptors at load time as well (see
+ * `collectDescriptorEndpointEnvNames`); this pattern is the floor that
+ * holds even when the descriptors cannot be imported.
+ */
+export declare const ENDPOINT_OVERRIDE_ENV_PATTERN: RegExp;
+/** True when `NEUROLINK_DOTENV` explicitly opts an SDK import into loading. */
+export declare function isSdkDotenvOptIn(): boolean;
+/**
+ * Load `.env` into `process.env` under the rules in this module's header and
+ * report what happened. Never throws: a missing dotenv module degrades to
+ * "nothing loaded".
+ */
+export declare function loadProcessDotenv(options?: DotenvBootstrapOptions): Promise<DotenvBootstrapResult>;
+/**
+ * Explicit opt-in for SDK hosts that want `.env` loaded the way the CLI does,
+ * with the same endpoint-override checks. Call it before constructing
+ * `NeuroLink`.
+ */
+export declare function loadDotenv(options?: DotenvBootstrapOptions): Promise<DotenvBootstrapResult>;

package/dist/utils/dotenvBootstrap.js

@@ -1,46 +1,187 @@
 /**
- * Implicit `.env` bootstrap, shared by the SDK entry point and the CLI.
+ * Implicit `.env` bootstrap for the CLI, and an explicit one for SDK hosts.
  *
- * Both sites used to call dotenv's `config()` with no options beyond
- * `quiet`, and a direct `config()` call does NOT read `DOTENV_CONFIG_PATH`
- * — only dotenv's own `dotenv/config` preload entry does. So the strip this
- * repo documents and uses to vet suites,
+ * Who loads `.env`:
  *
- *     env -i HOME=… PATH=… CI=true DOTENV_CONFIG_PATH=/dev/null …
+ * - The **CLI** loads `<cwd>/.env` at startup (or `DOTENV_CONFIG_PATH`),
+ *   because a terminal session in a project directory is the use case the
+ *   file exists for. `NEUROLINK_DOTENV=0` turns that off.
+ * - The **SDK** does not. Importing a library must not read the working
+ *   directory: a dependency that runs inside an untrusted checkout would
+ *   otherwise pick up that checkout's `.env`. A host that wants the old
+ *   behaviour calls `loadDotenv()` itself, or starts the process with
+ *   `NEUROLINK_DOTENV=1` in the real environment (the variable cannot come
+ *   from the file it enables).
  *
- * stripped nothing the moment a suite imported the built SDK: importing
- * `dist/index.js` loads `src/lib/neurolink.ts`, which loaded `.env` from the
- * working directory regardless. A credential the strip was supposed to
- * remove was present at every read site, and a suite that only passes
- * because of it looks identical to one that does not need it. See #1744;
- * the CI-only failure in #1735 is what surfaced it.
+ * What is refused even when a file is loaded. dotenv never overrides a
+ * variable that is already set, but it sets every one that is not — and
+ * among those are the variables that decide *where* a request goes: the
+ * provider `*_BASE_URL` / `*_ENDPOINT(S)` overrides, `NEUROLINK_*_DIR`
+ * directories, and `DOTENV_CONFIG_PATH`. A `.env` that supplies one of them
+ * can redirect a key exported in the shell to a host of its choosing. So,
+ * for exactly those names, the file has to be trustworthy: owned by the
+ * current user and not group/world-writable. Otherwise they are deleted
+ * again and named on stderr. When they are kept, a one-line notice says
+ * which ones the file set.
  *
- * Honouring the variable here makes that strip real. It is additive: with
- * `DOTENV_CONFIG_PATH` unset — which is every existing caller, SDK consumers
- * included — this does exactly what it did before, loading `.env` from the
- * current working directory. Only a caller that explicitly sets the variable
- * sees a difference, and what it then sees is dotenv's own documented
- * meaning for it.
+ * `DOTENV_CONFIG_PATH` is honoured because a direct `config()` call does not
+ * read it on its own (only dotenv's `dotenv/config` preload does), and the
+ * test strip `DOTENV_CONFIG_PATH=/dev/null` depends on it (#1744).
  */
-export async function loadProcessDotenv() {
+import { statSync } from "node:fs";
+import { homedir } from "node:os";
+import * as path from "node:path";
+/** `0` / `false` disables every implicit load; `1` / `true` opts the SDK in. */
+export const DOTENV_TOGGLE_ENV = "NEUROLINK_DOTENV";
+/**
+ * Names whose value decides where traffic or file access goes. Built from
+ * the provider descriptors at load time as well (see
+ * `collectDescriptorEndpointEnvNames`); this pattern is the floor that
+ * holds even when the descriptors cannot be imported.
+ */
+export const ENDPOINT_OVERRIDE_ENV_PATTERN = /_BASE_URL$|_ENDPOINTS?$|^NEUROLINK_.*_DIR$|^DOTENV_CONFIG_PATH$/;
+function isDisabled() {
+    const value = process.env[DOTENV_TOGGLE_ENV];
+    return value === "0" || value === "false";
+}
+/** True when `NEUROLINK_DOTENV` explicitly opts an SDK import into loading. */
+export function isSdkDotenvOptIn() {
+    const value = process.env[DOTENV_TOGGLE_ENV];
+    return value === "1" || value === "true";
+}
+async function collectDescriptorEndpointEnvNames() {
+    const names = new Set();
+    try {
+        const { PROVIDER_DESCRIPTORS } = await import("../factories/providerDescriptors.js");
+        for (const descriptor of PROVIDER_DESCRIPTORS) {
+            const { baseURL, baseURLFallbacks, extraRequired } = descriptor.envVars;
+            if (baseURL) {
+                names.add(baseURL);
+            }
+            for (const name of baseURLFallbacks ?? []) {
+                names.add(name);
+            }
+            for (const name of extraRequired ?? []) {
+                if (/ENDPOINT|URL|HOST/.test(name)) {
+                    names.add(name);
+                }
+            }
+        }
+    }
+    catch {
+        // The pattern above still covers every shipped name.
+    }
+    return names;
+}
+function inspectDotenvFile(envPath) {
+    const relativeToHome = path.relative(homedir(), envPath);
+    const outsideHome = relativeToHome.startsWith("..") || path.isAbsolute(relativeToHome);
+    try {
+        const stat = statSync(envPath);
+        const uid = typeof process.getuid === "function" ? process.getuid() : null;
+        if (uid !== null && stat.uid !== uid) {
+            return {
+                trustworthy: false,
+                reason: "the file is not owned by the current user",
+                outsideHome,
+            };
+        }
+        if (process.platform !== "win32" && (stat.mode & 0o022) !== 0) {
+            return {
+                trustworthy: false,
+                reason: "the file is group- or world-writable",
+                outsideHome,
+            };
+        }
+        return { trustworthy: true, outsideHome };
+    }
+    catch (error) {
+        return {
+            trustworthy: false,
+            reason: `the file could not be inspected (${error instanceof Error ? error.message : String(error)})`,
+            outsideHome,
+        };
+    }
+}
+/**
+ * Load `.env` into `process.env` under the rules in this module's header and
+ * report what happened. Never throws: a missing dotenv module degrades to
+ * "nothing loaded".
+ */
+export async function loadProcessDotenv(options = {}) {
+    const notify = options.notify ??
+        ((line) => {
+            process.stderr.write(`${line}\n`);
+        });
+    const empty = (reason) => ({
+        loaded: false,
+        supplied: [],
+        endpointOverrides: [],
+        refused: [],
+        ...(reason ? { reason } : {}),
+    });
+    if (isDisabled()) {
+        return empty(`${DOTENV_TOGGLE_ENV} disables .env loading`);
+    }
     try {
         // Suppress dotenv v17's stdout banner — it pollutes CLI JSON output.
-        // Redundant next to the explicit `quiet` below, which is what actually
-        // silences a direct `config()` call; kept because both call sites set it
-        // and something downstream may still read it.
         process.env.DOTENV_CONFIG_QUIET = process.env.DOTENV_CONFIG_QUIET ?? "true";
         const { config } = await import("dotenv");
-        const path = process.env.DOTENV_CONFIG_PATH;
+        const configuredPath = process.env.DOTENV_CONFIG_PATH;
+        const envPath = path.resolve(process.cwd(), configuredPath && configuredPath.length > 0 ? configuredPath : ".env");
+        const before = new Set(Object.keys(process.env));
         // Pass `path` only when set: `{ path: undefined }` is not the same as
-        // omitting it for every dotenv version, and the default must stay
-        // byte-for-byte what it was.
-        config(path ? { quiet: true, path } : { quiet: true });
+        // omitting it for every dotenv version.
+        const outcome = configuredPath
+            ? config({ quiet: true, path: configuredPath })
+            : config({ quiet: true });
+        const parsed = outcome.parsed ?? {};
+        const supplied = Object.keys(parsed).filter((name) => !before.has(name) && process.env[name] !== undefined);
+        const result = {
+            loaded: outcome.error === undefined,
+            path: envPath,
+            supplied,
+            endpointOverrides: [],
+            refused: [],
+        };
+        if (supplied.length === 0) {
+            return result;
+        }
+        const descriptorNames = await collectDescriptorEndpointEnvNames();
+        const endpointOverrides = supplied.filter((name) => ENDPOINT_OVERRIDE_ENV_PATTERN.test(name) || descriptorNames.has(name));
+        result.endpointOverrides = endpointOverrides;
+        if (endpointOverrides.length === 0) {
+            return result;
+        }
+        const verdict = inspectDotenvFile(envPath);
+        const names = endpointOverrides.join(", ");
+        if (!verdict.trustworthy) {
+            for (const name of endpointOverrides) {
+                delete process.env[name];
+            }
+            result.refused = endpointOverrides;
+            result.endpointOverrides = [];
+            result.reason = verdict.reason;
+            notify(`[neurolink] Refused ${endpointOverrides.length} endpoint override(s) from ${envPath} because ${verdict.reason}: ${names}. Export them in your shell to use them.`);
+            return result;
+        }
+        notify(`[neurolink] .env at ${envPath} set endpoint override(s): ${names}${verdict.outsideHome
+            ? " (the file is outside your home directory; make sure you trust this project)"
+            : ""}`);
+        return result;
     }
     catch {
-        // dotenv ships as a normal runtime dependency (see package.json), so this
-        // branch should not be reachable in a standard install. It stays as a
-        // defensive fallback for an install that has pruned or bundled
-        // dependencies unusually, so a missing module degrades to "no .env
-        // loaded" instead of crashing the SDK/CLI entry point.
+        // dotenv ships as a runtime dependency, so this is only reachable in an
+        // install that pruned or bundled dependencies unusually. A missing module
+        // degrades to "no .env loaded" instead of crashing the entry point.
+        return empty("dotenv is not available");
     }
 }
+/**
+ * Explicit opt-in for SDK hosts that want `.env` loaded the way the CLI does,
+ * with the same endpoint-override checks. Call it before constructing
+ * `NeuroLink`.
+ */
+export async function loadDotenv(options = {}) {
+    return loadProcessDotenv({ caller: "sdk", ...options });
+}