ssh_tunnel_proxy 2.1.1 → 3.0.0

package/build/local-forward.js

@@ -0,0 +1,231 @@
+"use strict";
+/*
+ * local-forward.ts — ssh -L, as a first-class object.
+ *
+ * One handle owns one listening socket and every connection accepted on it. The
+ * handle can be opened, closed, and re-opened across transport restarts without
+ * the caller re-declaring it, which is what makes reconnection transparent.
+ *
+ * License: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalForwardHandle = void 0;
+const node_net_1 = require("node:net");
+const connection_1 = require("./connection");
+const errors_1 = require("./errors");
+const forward_spec_1 = require("./forward-spec");
+class LocalForwardHandle {
+    forwardId;
+    spec;
+    state = 'pending';
+    server;
+    lastError;
+    totalConnections = 0;
+    connections = new Map();
+    bridge;
+    idleTimeoutMs;
+    constructor(spec, bridge, idleTimeoutMs = 0) {
+        this.spec = spec;
+        this.forwardId = spec.id ?? (0, forward_spec_1.describeLocalForward)(spec);
+        this.bridge = bridge;
+        this.idleTimeoutMs = idleTimeoutMs;
+    }
+    getState() {
+        return this.state;
+    }
+    getStatus() {
+        return {
+            forwardId: this.forwardId,
+            direction: 'local',
+            state: this.state,
+            listen: { ...this.spec.listen },
+            target: { ...this.spec.target },
+            assignedPort: this.server?.address()?.port,
+            activeConnections: this.connections.size,
+            totalConnections: this.totalConnections,
+            error: this.lastError,
+        };
+    }
+    listConnections() {
+        return [...this.connections.values()].map((connection) => connection.getStatus());
+    }
+    /** Bind the local listener. Resolves once the port is actually listening. */
+    async open() {
+        if (this.state === 'active')
+            return this.getStatus();
+        // A flap can call open() while the previous listener is still bound
+        // (state opening/degraded/failed). Reusing it avoids leaking servers.
+        if (this.server?.listening) {
+            this.lastError = undefined;
+            this.transition('active');
+            return this.getStatus();
+        }
+        this.transition('opening');
+        const server = (0, node_net_1.createServer)({ allowHalfOpen: true }, (socket) => {
+            this.handleSocket(socket);
+        });
+        this.server = server;
+        try {
+            await new Promise((resolve, reject) => {
+                const onError = (err) => {
+                    server.removeListener('listening', onListening);
+                    reject((0, errors_1.asTunnelError)('LISTEN_FAILED', `Cannot bind ${this.spec.listen.host}:${this.spec.listen.port}`, err, { forwardId: this.forwardId }));
+                };
+                const onListening = () => {
+                    server.removeListener('error', onError);
+                    resolve();
+                };
+                server.once('error', onError);
+                server.once('listening', onListening);
+                server.listen(this.spec.listen.port, this.spec.listen.host);
+            });
+        }
+        catch (err) {
+            this.lastError = err instanceof Error ? err.message : String(err);
+            this.server = undefined;
+            try {
+                server.close();
+            }
+            catch {
+                /* already unusable */
+            }
+            this.transition('failed');
+            throw err;
+        }
+        // Post-bind errors are reported, not thrown: the listener stays usable.
+        server.on('error', (err) => {
+            this.lastError = err.message;
+            this.bridge.onError((0, errors_1.asTunnelError)('LISTEN_FAILED', `Listener error on ${this.forwardId}`, err, {
+                forwardId: this.forwardId,
+            }));
+        });
+        this.transition('active');
+        this.bridge.debug(`local forward active ${this.spec.listen.host}:${this.spec.listen.port} -> ${this.spec.target.host}:${this.spec.target.port}`);
+        return this.getStatus();
+    }
+    /**
+     * Mark the forward as degraded: the listener stays bound so callers do not see
+     * connection-refused during a reconnect, but new connections fail fast until
+     * the transport returns.
+     */
+    markDegraded(reason) {
+        if (this.state === 'closed' || this.state === 'closing')
+            return;
+        this.lastError = reason;
+        this.closeConnections();
+        this.transition('degraded');
+    }
+    markActive() {
+        if (this.state === 'degraded') {
+            this.lastError = undefined;
+            this.transition('active');
+        }
+    }
+    async close() {
+        if (this.state === 'closed')
+            return this.getStatus();
+        this.transition('closing');
+        this.closeConnections();
+        const server = this.server;
+        this.server = undefined;
+        if (server) {
+            await new Promise((resolve) => {
+                server.close(() => resolve());
+                // close() only waits for existing connections; ours are already gone.
+            });
+        }
+        this.transition('closed');
+        return this.getStatus();
+    }
+    closeConnections() {
+        for (const connection of [...this.connections.values()]) {
+            connection.close();
+        }
+        this.connections.clear();
+    }
+    handleSocket(socket) {
+        const limit = this.spec.maxConnections ?? 0;
+        if (limit > 0 && this.connections.size >= limit) {
+            this.bridge.onError(new errors_1.TunnelError('CONNECTION_LIMIT', `Forward ${this.forwardId} reached maxConnections=${limit}`, { forwardId: this.forwardId }));
+            socket.destroy();
+            return;
+        }
+        const sourceHost = socket.remoteAddress ?? this.spec.listen.host;
+        const sourcePort = socket.remotePort ?? 0;
+        const connection = new connection_1.ProxiedConnection({
+            forwardId: this.forwardId,
+            direction: 'local',
+            source: { host: sourceHost, port: sourcePort },
+            destination: { ...this.spec.target },
+            idleTimeoutMs: this.idleTimeoutMs,
+            onStateChange: (status, previous) => {
+                if (status.state === 'closed' || status.state === 'failed') {
+                    this.connections.delete(status.connectionId);
+                }
+                this.bridge.onConnectionChanged(status, previous);
+            },
+        });
+        // Adopt the socket immediately so every failure path below destroys it.
+        connection.adoptInbound(socket);
+        this.connections.set(connection.connectionId, connection);
+        this.totalConnections += 1;
+        if (this.state !== 'active') {
+            connection.fail(new errors_1.TunnelError('TRANSPORT_NOT_READY', `Forward ${this.forwardId} is ${this.state}`, {
+                forwardId: this.forwardId,
+                connectionId: connection.connectionId,
+            }));
+            return;
+        }
+        let client;
+        try {
+            client = this.bridge.requireClient(this.forwardId);
+        }
+        catch (err) {
+            connection.fail(err instanceof Error ? err : new Error(String(err)));
+            return;
+        }
+        connection.markOpening();
+        // Pause until the channel exists so no inbound bytes are dropped.
+        socket.pause();
+        const openTimer = setTimeout(() => {
+            if (connection.isClosed())
+                return;
+            const wrapped = new errors_1.TunnelError('CHANNEL_OPEN_FAILED', `forwardOut to ${this.spec.target.host}:${this.spec.target.port} timed out`, { forwardId: this.forwardId, connectionId: connection.connectionId });
+            this.bridge.onError(wrapped);
+            connection.fail(wrapped, 'channel');
+        }, 8000);
+        try {
+            client.forwardOut(sourceHost, sourcePort, this.spec.target.host, this.spec.target.port, (err, stream) => {
+                clearTimeout(openTimer);
+                if (connection.isClosed()) {
+                    if (stream && !stream.destroyed)
+                        stream.destroy();
+                    return;
+                }
+                if (err) {
+                    const wrapped = (0, errors_1.asTunnelError)('CHANNEL_OPEN_FAILED', `forwardOut to ${this.spec.target.host}:${this.spec.target.port} failed`, err, { forwardId: this.forwardId, connectionId: connection.connectionId });
+                    this.bridge.onError(wrapped);
+                    connection.fail(wrapped, 'channel');
+                    return;
+                }
+                connection.attach(socket, stream);
+                socket.resume();
+            });
+        }
+        catch (err) {
+            clearTimeout(openTimer);
+            const wrapped = (0, errors_1.asTunnelError)('TRANSPORT_NOT_READY', `forwardOut to ${this.spec.target.host}:${this.spec.target.port} failed`, err, { forwardId: this.forwardId, connectionId: connection.connectionId });
+            this.bridge.onError(wrapped);
+            connection.fail(wrapped, 'channel');
+        }
+    }
+    transition(next) {
+        if (this.state === next)
+            return;
+        const previous = this.state;
+        this.state = next;
+        this.bridge.onForwardChanged(this.getStatus(), previous);
+    }
+}
+exports.LocalForwardHandle = LocalForwardHandle;
+//# sourceMappingURL=local-forward.js.map

package/build/local-forward.js.map

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

package/build/model.d.ts

@@ -0,0 +1,126 @@
+export declare const MODEL_VERSION = "sshtunnel.v1";
+/** A TCP endpoint. `host` is an IP literal or DNS name, never a URL. */
+export interface Endpoint {
+    host: string;
+    port: number;
+}
+export declare const CREDENTIAL_SOURCES: readonly ["file", "env", "inline", "agent", "callback"];
+export type CredentialSource = (typeof CREDENTIAL_SOURCES)[number];
+/** Indirect reference to secret material; the model never carries the secret. */
+export interface CredentialRef {
+    source: CredentialSource;
+    value?: string;
+}
+/**
+ * Port authorization is an explicit caller policy. Local listen ports and
+ * remote target ports are separate decisions: one governs what this process may
+ * bind, the other governs what the SSH peer is asked to reach.
+ */
+export interface PortPolicy {
+    allowedPrivilegedPorts?: readonly number[];
+    allowedLocalListenPorts?: readonly number[];
+    allowedRemoteTargetPorts?: readonly number[];
+    allowedRemoteHosts?: readonly string[];
+}
+/** ssh -L : listen here, deliver to a host reachable from the SSH peer. */
+export interface LocalForward {
+    id?: string;
+    listen: Endpoint;
+    target: Endpoint;
+    exclusive?: boolean;
+    maxConnections?: number;
+}
+/** ssh -R : the peer listens, connections are delivered to a host reachable here. */
+export interface RemoteForward {
+    id?: string;
+    /** Bound on the SSH peer. `port: 0` asks the peer to assign one. */
+    bind: Endpoint;
+    /** Resolved by this machine. */
+    target: Endpoint;
+    maxConnections?: number;
+}
+export declare const REACHABILITY_VALUES: readonly ["direct", "zrok", "ngrok", "custom"];
+export type Reachability = (typeof REACHABILITY_VALUES)[number];
+/**
+ * How to reach an SSH listener that already exists. This library never
+ * provisions a relay; `reachability` is documentation metadata only.
+ */
+export interface SshTransport {
+    endpoint: Endpoint;
+    username: string;
+    privateKey?: CredentialRef;
+    passphrase?: CredentialRef;
+    password?: CredentialRef;
+    keepaliveIntervalMs?: number;
+    keepaliveCountMax?: number;
+    readyTimeoutMs?: number;
+    /** `sha256:...` values. Empty or omitted accepts any host key. */
+    hostKeyFingerprints?: readonly string[];
+    reachability?: Reachability;
+}
+export interface ReconnectPolicy {
+    enabled?: boolean;
+    /** 0 means unlimited. */
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    backoffMultiplier?: number;
+    /** 0.0 .. 1.0 */
+    jitterRatio?: number;
+}
+export interface TunnelConfig {
+    id?: string;
+    label?: string;
+    transport: SshTransport;
+    portPolicy?: PortPolicy;
+    reconnect?: ReconnectPolicy;
+    localForwards?: readonly LocalForward[];
+    remoteForwards?: readonly RemoteForward[];
+    metadata?: Record<string, string>;
+}
+export declare const TUNNEL_STATES: readonly ["idle", "connecting", "ready", "reconnecting", "closing", "closed", "failed"];
+export type TunnelState = (typeof TUNNEL_STATES)[number];
+export declare const FORWARD_STATES: readonly ["pending", "opening", "active", "degraded", "closing", "closed", "failed"];
+export type ForwardState = (typeof FORWARD_STATES)[number];
+export declare const CONNECTION_STATES: readonly ["accepted", "opening", "piped", "half_closed", "closed", "failed"];
+export type ConnectionState = (typeof CONNECTION_STATES)[number];
+export declare const FORWARD_DIRECTIONS: readonly ["local", "remote"];
+export type ForwardDirection = (typeof FORWARD_DIRECTIONS)[number];
+export interface ConnectionStatus {
+    connectionId: string;
+    forwardId: string;
+    direction: ForwardDirection;
+    state: ConnectionState;
+    source: Endpoint;
+    destination: Endpoint;
+    openedAtUnixMs: number;
+    closedAtUnixMs?: number;
+    bytesToTarget: number;
+    bytesFromTarget: number;
+    error?: string;
+}
+export interface ForwardStatus {
+    forwardId: string;
+    direction: ForwardDirection;
+    state: ForwardState;
+    listen: Endpoint;
+    target: Endpoint;
+    assignedPort?: number;
+    activeConnections: number;
+    totalConnections: number;
+    error?: string;
+}
+export interface TunnelStatus {
+    tunnelId: string;
+    state: TunnelState;
+    endpoint: Endpoint;
+    reconnectAttempt: number;
+    connectedAtUnixMs?: number;
+    forwards: ForwardStatus[];
+    error?: string;
+}
+export declare const DEFAULT_RECONNECT_POLICY: Required<ReconnectPolicy>;
+export declare const DEFAULT_KEEPALIVE_INTERVAL_MS = 10000;
+export declare const DEFAULT_KEEPALIVE_COUNT_MAX = 3;
+export declare const DEFAULT_READY_TIMEOUT_MS = 20000;
+//# sourceMappingURL=model.d.ts.map

package/build/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,aAAa,iBAAiB,CAAC;AAE5C,wEAAwE;AACxE,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,kBAAkB,yDAA0D,CAAC;AAC1F,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,uBAAuB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,wBAAwB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,2EAA2E;AAC3E,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,QAAQ,CAAC;IACjB,MAAM,EAAE,QAAQ,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qFAAqF;AACrF,MAAM,WAAW,aAAa;IAC5B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,IAAI,EAAE,QAAQ,CAAC;IACf,gCAAgC;IAChC,MAAM,EAAE,QAAQ,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,eAAO,MAAM,mBAAmB,gDAAiD,CAAC;AAClF,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yBAAyB;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,YAAY,CAAC;IACxB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,aAAa,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,cAAc,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,eAAO,MAAM,aAAa,yFAQhB,CAAC;AACX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,eAAO,MAAM,cAAc,sFAQjB,CAAC;AACX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,eAAO,MAAM,iBAAiB,8EAOpB,CAAC;AACX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE,eAAO,MAAM,kBAAkB,8BAA+B,CAAC;AAC/D,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,KAAK,EAAE,eAAe,CAAC;IACvB,MAAM,EAAE,QAAQ,CAAC;IACjB,WAAW,EAAE,QAAQ,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,QAAQ,CAAC;IACjB,MAAM,EAAE,QAAQ,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,eAAe,CAO9D,CAAC;AAEF,eAAO,MAAM,6BAA6B,QAAQ,CAAC;AACnD,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAC7C,eAAO,MAAM,wBAAwB,QAAQ,CAAC"}

package/build/model.js

@@ -0,0 +1,55 @@
+"use strict";
+/*
+ * model.ts — TypeScript projection of proto/sshtunnel/v1/tunnel.proto
+ *
+ * Hand-maintained rather than generated so the public API stays idiomatic
+ * TypeScript (string unions, optional fields, camelCase). The proto file
+ * remains the cross-language source of truth; `assertModelParity` in the test
+ * suite checks that every proto enum value has a TypeScript counterpart.
+ *
+ * License: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_READY_TIMEOUT_MS = exports.DEFAULT_KEEPALIVE_COUNT_MAX = exports.DEFAULT_KEEPALIVE_INTERVAL_MS = exports.DEFAULT_RECONNECT_POLICY = exports.FORWARD_DIRECTIONS = exports.CONNECTION_STATES = exports.FORWARD_STATES = exports.TUNNEL_STATES = exports.REACHABILITY_VALUES = exports.CREDENTIAL_SOURCES = exports.MODEL_VERSION = void 0;
+exports.MODEL_VERSION = 'sshtunnel.v1';
+exports.CREDENTIAL_SOURCES = ['file', 'env', 'inline', 'agent', 'callback'];
+exports.REACHABILITY_VALUES = ['direct', 'zrok', 'ngrok', 'custom'];
+exports.TUNNEL_STATES = [
+    'idle',
+    'connecting',
+    'ready',
+    'reconnecting',
+    'closing',
+    'closed',
+    'failed',
+];
+exports.FORWARD_STATES = [
+    'pending',
+    'opening',
+    'active',
+    'degraded',
+    'closing',
+    'closed',
+    'failed',
+];
+exports.CONNECTION_STATES = [
+    'accepted',
+    'opening',
+    'piped',
+    'half_closed',
+    'closed',
+    'failed',
+];
+exports.FORWARD_DIRECTIONS = ['local', 'remote'];
+exports.DEFAULT_RECONNECT_POLICY = {
+    enabled: true,
+    maxAttempts: 10,
+    initialDelayMs: 1000,
+    maxDelayMs: 30000,
+    backoffMultiplier: 2,
+    jitterRatio: 0.2,
+};
+exports.DEFAULT_KEEPALIVE_INTERVAL_MS = 10000;
+exports.DEFAULT_KEEPALIVE_COUNT_MAX = 3;
+exports.DEFAULT_READY_TIMEOUT_MS = 20000;
+//# sourceMappingURL=model.js.map

package/build/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAEU,QAAA,aAAa,GAAG,cAAc,CAAC;AAQ/B,QAAA,kBAAkB,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAU,CAAC;AAwC7E,QAAA,mBAAmB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAU,CAAC;AA2CrE,QAAA,aAAa,GAAG;IAC3B,MAAM;IACN,YAAY;IACZ,OAAO;IACP,cAAc;IACd,SAAS;IACT,QAAQ;IACR,QAAQ;CACA,CAAC;AAGE,QAAA,cAAc,GAAG;IAC5B,SAAS;IACT,SAAS;IACT,QAAQ;IACR,UAAU;IACV,SAAS;IACT,QAAQ;IACR,QAAQ;CACA,CAAC;AAGE,QAAA,iBAAiB,GAAG;IAC/B,UAAU;IACV,SAAS;IACT,OAAO;IACP,aAAa;IACb,QAAQ;IACR,QAAQ;CACA,CAAC;AAGE,QAAA,kBAAkB,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAU,CAAC;AAuClD,QAAA,wBAAwB,GAA8B;IACjE,OAAO,EAAE,IAAI;IACb,WAAW,EAAE,EAAE;IACf,cAAc,EAAE,IAAI;IACpB,UAAU,EAAE,KAAK;IACjB,iBAAiB,EAAE,CAAC;IACpB,WAAW,EAAE,GAAG;CACjB,CAAC;AAEW,QAAA,6BAA6B,GAAG,KAAK,CAAC;AACtC,QAAA,2BAA2B,GAAG,CAAC,CAAC;AAChC,QAAA,wBAAwB,GAAG,KAAK,CAAC"}

package/build/port-policy.d.ts

@@ -0,0 +1,43 @@
+import type { PortPolicy } from './model';
+export declare const MIN_PORT = 1;
+export declare const MAX_PORT = 65535;
+export declare const FIRST_UNPRIVILEGED_PORT = 1024;
+/** Which side of a forward a port belongs to. */
+export type PortRole = 'local-listen' | 'remote-target' | 'remote-bind';
+/**
+ * True when `port` is a syntactically valid TCP port number.
+ *
+ * Stricter than the v1 `validate_port_number`: fractional values, NaN and
+ * numbers parsed out of strings such as `"80abc"` are rejected rather than
+ * silently truncated.
+ */
+export declare function isValidPort(port: unknown): port is number;
+/**
+ * Parse a port from text with no coercion surprises.
+ * Returns `undefined` for anything that is not a bare decimal integer.
+ */
+export declare function parsePort(text: string): number | undefined;
+/** `port: 0` is legal only for a remote bind, where it means "peer assigns". */
+export declare function isValidBindPort(port: unknown): port is number;
+export interface PortCheckResult {
+    allowed: boolean;
+    reason?: string;
+}
+/**
+ * Evaluate a port against a policy for a given role.
+ *
+ * Policy semantics, in order:
+ *   1. The port must be a valid TCP port (a remote bind may also be 0).
+ *   2. A privileged port (< 1024) requires an explicit allowlist entry.
+ *   3. If a role-specific allowlist is non-empty, the port must appear in it.
+ *
+ * An absent or empty policy therefore permits any unprivileged port and no
+ * privileged port.
+ */
+export declare function checkPort(port: unknown, role: PortRole, policy?: PortPolicy): PortCheckResult;
+/** Throwing form of {@link checkPort}. */
+export declare function assertPortAllowed(port: unknown, role: PortRole, policy?: PortPolicy, forwardId?: string): number;
+/** A hostname or IP literal, syntactically. Does not resolve anything. */
+export declare function isValidHost(host: unknown): host is string;
+export declare function assertHostAllowed(host: unknown, policy?: PortPolicy, forwardId?: string): string;
+//# sourceMappingURL=port-policy.d.ts.map

package/build/port-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-policy.d.ts","sourceRoot":"","sources":["../src/port-policy.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,eAAO,MAAM,QAAQ,IAAI,CAAC;AAC1B,eAAO,MAAM,QAAQ,QAAQ,CAAC;AAC9B,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C,iDAAiD;AACjD,MAAM,MAAM,QAAQ,GAAG,cAAc,GAAG,eAAe,GAAG,aAAa,CAAC;AAExE;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,MAAM,CAOzD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK1D;AAED,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,MAAM,CAE7D;AAMD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,QAAQ,EACd,MAAM,GAAE,UAAe,GACtB,eAAe,CAoCjB;AAED,0CAA0C;AAC1C,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,QAAQ,EACd,MAAM,GAAE,UAAe,EACvB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAQR;AAED,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,MAAM,CAYzD;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,EACb,MAAM,GAAE,UAAe,EACvB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAaR"}

package/build/port-policy.js

@@ -0,0 +1,138 @@
+"use strict";
+/*
+ * port-policy.ts — pure port authorization.
+ *
+ * No sockets, no SSH, no filesystem, no network. Everything here is a total
+ * function over plain values, which is what makes it cheap to unit test.
+ *
+ * License: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIRST_UNPRIVILEGED_PORT = exports.MAX_PORT = exports.MIN_PORT = void 0;
+exports.isValidPort = isValidPort;
+exports.parsePort = parsePort;
+exports.isValidBindPort = isValidBindPort;
+exports.checkPort = checkPort;
+exports.assertPortAllowed = assertPortAllowed;
+exports.isValidHost = isValidHost;
+exports.assertHostAllowed = assertHostAllowed;
+const errors_1 = require("./errors");
+exports.MIN_PORT = 1;
+exports.MAX_PORT = 65535;
+exports.FIRST_UNPRIVILEGED_PORT = 1024;
+/**
+ * True when `port` is a syntactically valid TCP port number.
+ *
+ * Stricter than the v1 `validate_port_number`: fractional values, NaN and
+ * numbers parsed out of strings such as `"80abc"` are rejected rather than
+ * silently truncated.
+ */
+function isValidPort(port) {
+    return (typeof port === 'number' &&
+        Number.isInteger(port) &&
+        port >= exports.MIN_PORT &&
+        port <= exports.MAX_PORT);
+}
+/**
+ * Parse a port from text with no coercion surprises.
+ * Returns `undefined` for anything that is not a bare decimal integer.
+ */
+function parsePort(text) {
+    if (typeof text !== 'string')
+        return undefined;
+    if (!/^[0-9]{1,5}$/.test(text))
+        return undefined;
+    const port = Number(text);
+    return isValidPort(port) ? port : undefined;
+}
+/** `port: 0` is legal only for a remote bind, where it means "peer assigns". */
+function isValidBindPort(port) {
+    return port === 0 || isValidPort(port);
+}
+function inList(list, port) {
+    return Array.isArray(list) && list.includes(port);
+}
+/**
+ * Evaluate a port against a policy for a given role.
+ *
+ * Policy semantics, in order:
+ *   1. The port must be a valid TCP port (a remote bind may also be 0).
+ *   2. A privileged port (< 1024) requires an explicit allowlist entry.
+ *   3. If a role-specific allowlist is non-empty, the port must appear in it.
+ *
+ * An absent or empty policy therefore permits any unprivileged port and no
+ * privileged port.
+ */
+function checkPort(port, role, policy = {}) {
+    const allowZero = role === 'remote-bind';
+    if (allowZero ? !isValidBindPort(port) : !isValidPort(port)) {
+        return {
+            allowed: false,
+            reason: `${String(port)} is not a valid TCP port (${exports.MIN_PORT}-${exports.MAX_PORT}${allowZero ? ', or 0 for peer-assigned' : ''})`,
+        };
+    }
+    const value = port;
+    if (value !== 0 && value < exports.FIRST_UNPRIVILEGED_PORT) {
+        if (!inList(policy.allowedPrivilegedPorts, value)) {
+            return {
+                allowed: false,
+                reason: `privileged port ${value} requires an explicit allowedPrivilegedPorts entry`,
+            };
+        }
+    }
+    const roleList = role === 'local-listen'
+        ? policy.allowedLocalListenPorts
+        : role === 'remote-target'
+            ? policy.allowedRemoteTargetPorts
+            : undefined;
+    if (roleList && roleList.length > 0 && !roleList.includes(value)) {
+        return {
+            allowed: false,
+            reason: `port ${value} is not in the ${role} allowlist`,
+        };
+    }
+    return { allowed: true };
+}
+/** Throwing form of {@link checkPort}. */
+function assertPortAllowed(port, role, policy = {}, forwardId) {
+    const result = checkPort(port, role, policy);
+    if (!result.allowed) {
+        throw new errors_1.TunnelError('PORT_NOT_PERMITTED', `Rejected ${role} port: ${result.reason}`, {
+            forwardId,
+        });
+    }
+    return port;
+}
+/** A hostname or IP literal, syntactically. Does not resolve anything. */
+function isValidHost(host) {
+    if (typeof host !== 'string')
+        return false;
+    const value = host.trim();
+    if (value.length === 0 || value.length > 255)
+        return false;
+    if (value !== host)
+        return false;
+    if (value.includes('/') || value.includes(' '))
+        return false;
+    // Bracketed or bare IPv6
+    if (value.startsWith('[') && value.endsWith(']'))
+        return value.length > 2;
+    if (/^[0-9a-fA-F:]+$/.test(value) && value.includes(':'))
+        return true;
+    return /^[A-Za-z0-9_]([A-Za-z0-9_-]*[A-Za-z0-9_])?(\.[A-Za-z0-9_]([A-Za-z0-9_-]*[A-Za-z0-9_])?)*$/.test(value);
+}
+function assertHostAllowed(host, policy = {}, forwardId) {
+    if (!isValidHost(host)) {
+        throw new errors_1.TunnelError('INVALID_FORWARD_SPEC', `Invalid host: ${JSON.stringify(host)}`, {
+            forwardId,
+        });
+    }
+    const allowed = policy.allowedRemoteHosts;
+    if (allowed && allowed.length > 0 && !allowed.includes(host)) {
+        throw new errors_1.TunnelError('HOST_NOT_PERMITTED', `Host ${host} is not in allowedRemoteHosts`, {
+            forwardId,
+        });
+    }
+    return host;
+}
+//# sourceMappingURL=port-policy.js.map

package/build/port-policy.js.map

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