@trillboards/edge-sdk 0.2.20 → 0.2.24

package/dist/enterpriseNetwork.d.ts

@@ -0,0 +1,130 @@
+import * as http from 'http';
+import * as https from 'https';
+import * as net from 'net';
+import * as tls from 'tls';
+import type { Duplex } from 'stream';
+import { type TrustAnchorReadOptions, type TrustAnchorResolution } from './enterpriseTrust';
+import { type ProxyReadOptions, type ProxyResolution } from './enterpriseProxy';
+import { TransportFailure } from './transportFailure';
+export interface NetworkPosture {
+    trust: TrustAnchorResolution;
+    /** Proxy decision for the API base, which is the one an operator cares about. */
+    proxy: ProxyResolution;
+    /** The two lines an operator should see at startup and in `diagnose`. */
+    lines: string[];
+}
+export interface EnterpriseNetworkOptions extends TrustAnchorReadOptions, ProxyReadOptions {
+}
+/**
+ * Cached `resolveProxyForUrl`. The cache exists because resolving costs a
+ * subprocess on Windows and macOS and the answer is a per-machine constant that
+ * changes on the timescale of an IT ticket, not a request.
+ *
+ * The cache is keyed on the TARGET only, so it is valid exactly while the
+ * environment is a process-wide constant — which it is in production and is
+ * NOT when a caller injects one. An injected `env`/`platform`/`exec` therefore
+ * bypasses the cache in both directions: it neither reads a decision taken
+ * under a different environment nor publishes its own for someone else to
+ * read. Without that, two agents built with different proxies in the same
+ * process silently share the first one's answer.
+ */
+export declare function resolveProxyCached(targetUrl: string, opts?: EnterpriseNetworkOptions): ProxyResolution;
+/** Drop every cached network decision. Used by tests and by `diagnose`. */
+export declare function resetEnterpriseNetworkCaches(): void;
+/**
+ * Re-read the trust store after a certificate failure, at most once a minute.
+ *
+ * The point of the whole runtime-resolution design: an operator on the phone
+ * with IT gets the root installed, and the connector picks it up on the next
+ * cadence tick instead of needing a restart nobody is present to perform.
+ * Returns whether a re-read was actually armed, so the caller can say so.
+ */
+export declare function refreshTrustAnchorsAfterFailure(now?: number): boolean;
+/**
+ * The shape `http.Agent` calls `createConnection` with. `stream` is typed as a
+ * `Duplex` in @types/node because a custom agent may return any duplex; ours is
+ * always a socket.
+ */
+type AgentConnectCallback = (err: Error | null, stream: Duplex) => void;
+type ConnectCallback = (err: Error | null, socket?: net.Socket) => void;
+/**
+ * An `https.Agent` that decides, per connection, whether to tunnel.
+ *
+ * Per-connection and not per-agent because `NO_PROXY` is a per-host rule: one
+ * process talks to `api.trillboards.com` (proxied) and `127.0.0.1:9379` (never
+ * proxied), and a single agent has to get both right.
+ */
+export declare class EnterpriseHttpsAgent extends https.Agent {
+    private readonly netOptions;
+    constructor(options: https.AgentOptions, netOptions?: EnterpriseNetworkOptions);
+    createConnection(options: http.ClientRequestArgs, cb?: AgentConnectCallback): Duplex | null | undefined;
+}
+interface ProxyConnectArgs {
+    target: {
+        host: string;
+        port: number;
+        servername: string;
+    };
+    proxyUrl: string;
+    proxySource: string;
+    tlsOptions: tls.ConnectionOptions;
+    callback: ConnectCallback;
+    /** Override the CONNECT deadline. Tests only; production uses the constant. */
+    connectTimeoutMs?: number;
+}
+/**
+ * Open a CONNECT tunnel and start TLS inside it.
+ *
+ * Hand-rolled because the SDK ships with no third-party HTTP dependency at all
+ * (`package.json` has jpeg-js/jsqr/pngjs and nothing network-facing) and is
+ * bundled into a self-contained tree; adding `proxy-agent` would pull a
+ * dependency graph into a signed customer artifact for ~90 lines of protocol.
+ *
+ * `rejectUnauthorized` is never touched here. The tunnel changes WHO carries
+ * the bytes; it does not change who we are willing to believe at the other end.
+ */
+export declare function connectThroughProxy(args: ProxyConnectArgs): void;
+/**
+ * Build (without installing) the agent for a set of resolved anchors.
+ * Exposed so a test can hold one without touching process globals.
+ */
+export declare function createEnterpriseAgent(anchors: TrustAnchorResolution, netOptions?: EnterpriseNetworkOptions, base?: https.AgentOptions): EnterpriseHttpsAgent;
+/**
+ * The process-wide agent. Built on first use and reused forever after — an
+ * agent owns a socket pool, so returning a fresh one per call would defeat
+ * keep-alive and leak a pool per request.
+ */
+export declare function getEnterpriseAgent(netOptions?: EnterpriseNetworkOptions): EnterpriseHttpsAgent;
+/** What the connector resolved, for a startup line and for `diagnose`. */
+export declare function describeNetworkPosture(apiBaseUrl: string, netOptions?: EnterpriseNetworkOptions): NetworkPosture;
+/**
+ * Install the enterprise agent as `https.globalAgent` and report what it found.
+ *
+ * Idempotent. Returns the posture so the caller can print it — printing is the
+ * caller's job because the CLI, the supervisor and `diagnose` each have their
+ * own output channel.
+ */
+export declare function installEnterpriseNetworking(apiBaseUrl: string, netOptions?: EnterpriseNetworkOptions): NetworkPosture;
+/** Undo the install. Tests only — production installs once and never removes it. */
+export declare function uninstallEnterpriseNetworking(original?: https.Agent): void;
+/**
+ * The one place a caught transport error becomes a diagnosis.
+ *
+ * Also arms a trust-store re-read when the failure was a trust failure, so the
+ * recovery path described in `enterpriseTrust` actually fires.
+ */
+export declare function diagnoseTransportError(err: unknown, targetUrl: string): TransportFailure;
+/**
+ * Rewrite request options so a PLAIN-HTTP target goes through the proxy.
+ *
+ * http through a forward proxy is absolute-form, not a tunnel: connect to the
+ * proxy and put the whole URL in the request line. Returns the options
+ * unchanged when no proxy applies. `https` never comes through here — it goes
+ * through the agent above.
+ */
+export declare function applyHttpProxy(url: string, options: http.RequestOptions, netOptions?: EnterpriseNetworkOptions): {
+    options: http.RequestOptions;
+    proxyUrl: string | null;
+};
+export {};
+//# sourceMappingURL=enterpriseNetwork.d.ts.map

package/dist/enterpriseNetwork.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enterpriseNetwork.d.ts","sourceRoot":"","sources":["../src/enterpriseNetwork.ts"],"names":[],"mappings":"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"}