@akira-tl/forgerelay 0.6.0 → 0.6.2

package/dist/composite-workspaces.js

@@ -0,0 +1,197 @@
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export class CompositeWorkspaceRegistry {
+    stateDir;
+    statePath;
+    records = new Map();
+    constructor(stateDir) {
+        this.stateDir = stateDir;
+        this.statePath = join(stateDir, "composite-workspaces.json");
+        this.load();
+    }
+    has(workspaceId) {
+        return this.records.has(workspaceId);
+    }
+    create(name) {
+        const normalized = normalizeName(name);
+        const existing = [...this.records.values()].find((record) => record.name === normalized);
+        if (existing)
+            return this.touch(existing.id);
+        const now = new Date().toISOString();
+        const record = {
+            id: `cws_${randomBytes(5).toString("hex")}`,
+            kind: "composite",
+            name: normalized,
+            members: [],
+            createdAt: now,
+            lastUsedAt: now,
+        };
+        this.records.set(record.id, record);
+        this.persist();
+        return cloneRecord(record);
+    }
+    get(workspaceId) {
+        const record = this.records.get(workspaceId);
+        if (!record)
+            throw new Error(`Unknown Composite Workspace ${workspaceId}.`);
+        return cloneRecord(record);
+    }
+    open(workspaceId) {
+        return this.touch(workspaceId);
+    }
+    list() {
+        return [...this.records.values()]
+            .map(cloneRecord)
+            .sort((left, right) => right.lastUsedAt.localeCompare(left.lastUsedAt));
+    }
+    addMember(workspaceId, input) {
+        const record = this.requireRecord(workspaceId);
+        const name = normalizeMemberName(input.name);
+        const purpose = input.purpose.trim();
+        if (!purpose)
+            throw new Error("Composite Workspace member purpose must not be empty.");
+        const existing = record.members.find((member) => member.name === name);
+        if (existing) {
+            if (existing.purpose === purpose && existing.workspaceId === input.workspaceId) {
+                return cloneRecord(record);
+            }
+            throw new Error(`Composite Workspace ${workspaceId} already has member ${name} with a different definition.`);
+        }
+        record.members.push({ name, purpose, workspaceId: input.workspaceId });
+        record.lastUsedAt = new Date().toISOString();
+        this.persist();
+        return cloneRecord(record);
+    }
+    updateMember(workspaceId, memberName, input) {
+        const record = this.requireRecord(workspaceId);
+        const currentName = normalizeMemberName(memberName);
+        const index = record.members.findIndex((member) => member.name === currentName);
+        if (index < 0)
+            throw new Error(`Composite Workspace ${workspaceId} has no member ${currentName}.`);
+        const current = record.members[index];
+        const nextName = input.name === undefined ? current.name : normalizeMemberName(input.name);
+        const nextPurpose = input.purpose === undefined ? current.purpose : input.purpose.trim();
+        if (!nextPurpose)
+            throw new Error("Composite Workspace member purpose must not be empty.");
+        const nextWorkspaceId = input.workspaceId ?? current.workspaceId;
+        if (nextName !== current.name &&
+            record.members.some((member, memberIndex) => memberIndex !== index && member.name === nextName)) {
+            throw new Error(`Composite Workspace ${workspaceId} already has member ${nextName}.`);
+        }
+        if (nextName === current.name &&
+            nextPurpose === current.purpose &&
+            nextWorkspaceId === current.workspaceId) {
+            return cloneRecord(record);
+        }
+        record.members[index] = {
+            name: nextName,
+            purpose: nextPurpose,
+            workspaceId: nextWorkspaceId,
+        };
+        record.lastUsedAt = new Date().toISOString();
+        this.persist();
+        return cloneRecord(record);
+    }
+    removeMember(workspaceId, memberName) {
+        const record = this.requireRecord(workspaceId);
+        const name = normalizeMemberName(memberName);
+        const index = record.members.findIndex((member) => member.name === name);
+        if (index < 0)
+            throw new Error(`Composite Workspace ${workspaceId} has no member ${name}.`);
+        record.members.splice(index, 1);
+        record.lastUsedAt = new Date().toISOString();
+        this.persist();
+        return cloneRecord(record);
+    }
+    member(workspaceId, memberName) {
+        const record = this.requireRecord(workspaceId);
+        const name = normalizeMemberName(memberName);
+        const member = record.members.find((entry) => entry.name === name);
+        if (!member)
+            throw new Error(`Composite Workspace ${workspaceId} has no member ${name}.`);
+        return { ...member };
+    }
+    dissolve(workspaceId) {
+        const record = this.requireRecord(workspaceId);
+        this.records.delete(workspaceId);
+        this.persist();
+        return cloneRecord(record);
+    }
+    touch(workspaceId) {
+        const record = this.requireRecord(workspaceId);
+        record.lastUsedAt = new Date().toISOString();
+        this.persist();
+        return cloneRecord(record);
+    }
+    requireRecord(workspaceId) {
+        const record = this.records.get(workspaceId);
+        if (!record)
+            throw new Error(`Unknown Composite Workspace ${workspaceId}.`);
+        return record;
+    }
+    load() {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(this.statePath, "utf8"));
+        }
+        catch (error) {
+            if (isMissingFile(error))
+                return;
+            throw new Error(`Failed to load Composite Workspace state: ${errorMessage(error)}`);
+        }
+        if (parsed?.version !== 1 || !Array.isArray(parsed.workspaces)) {
+            throw new Error("Composite Workspace state has an unsupported format.");
+        }
+        for (const record of parsed.workspaces) {
+            if (!record?.id?.startsWith("cws_") || record.kind !== "composite")
+                continue;
+            this.records.set(record.id, {
+                ...record,
+                members: Array.isArray(record.members) ? record.members.map((member) => ({ ...member })) : [],
+            });
+        }
+    }
+    persist() {
+        mkdirSync(this.stateDir, { recursive: true });
+        const state = {
+            version: 1,
+            workspaces: [...this.records.values()].map(cloneRecord),
+        };
+        const tempPath = `${this.statePath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+        try {
+            writeFileSync(tempPath, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+            renameSync(tempPath, this.statePath);
+        }
+        finally {
+            rmSync(tempPath, { force: true });
+        }
+    }
+}
+function normalizeName(name) {
+    const value = name.trim();
+    if (!value)
+        throw new Error("Composite Workspace name must not be empty.");
+    if (value.length > 120)
+        throw new Error("Composite Workspace name must be at most 120 characters.");
+    return value;
+}
+function normalizeMemberName(name) {
+    const value = name.trim();
+    if (!/^[a-z][a-z0-9_-]{0,31}$/.test(value)) {
+        throw new Error("Composite Workspace member name must match /^[a-z][a-z0-9_-]{0,31}$/.");
+    }
+    return value;
+}
+function cloneRecord(record) {
+    return {
+        ...record,
+        members: record.members.map((member) => ({ ...member })),
+    };
+}
+function isMissingFile(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/config.js

@@ -3,7 +3,7 @@ import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { expandHomePath } from "./roots.js";
 import { mergeHookConfigs, parseHookConfig } from "./hooks.js";
-import { forgerelayAgentsDir, forgerelaySkillsDir, loadForgeRelayFiles, } from "./user-config.js";
+import { forgerelayAgentsDir, forgerelaySkillsDir, generateInstanceId, loadForgeRelayFiles, } from "./user-config.js";
 const DEFAULT_OAUTH_ACCESS_TOKEN_TTL_SECONDS = 60 * 60;
 const DEFAULT_OAUTH_REFRESH_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60;
 const DEFAULT_ARTIFACT_MAX_FILE_BYTES = 100 * 1024 * 1024;
@@ -211,6 +211,7 @@ function resolvePublicDeployment(env, fileConfig, host, port) {
 }
 export function loadConfig(env = process.env) {
     const files = loadForgeRelayFiles(env);
+    const instanceId = files.auth.instanceId?.trim() || generateInstanceId();
     const host = env.HOST ?? files.config.host ?? "127.0.0.1";
     const port = parsePort(env.PORT ?? files.config.port);
     const publicDeployment = resolvePublicDeployment(env, files.config, host, port);
@@ -224,6 +225,8 @@ export function loadConfig(env = process.env) {
         ...(files.config.allowedHosts ?? []),
     ];
     return {
+        instanceId,
+        configDir: files.dir,
         host,
         port,
         oauth: parseOAuthConfig(env, files.auth.ownerToken),

package/dist/oauth/router.js

@@ -7,7 +7,7 @@ import { revocationHandler } from "@modelcontextprotocol/sdk/server/auth/handler
 import { metadataHandler } from "@modelcontextprotocol/sdk/server/auth/handlers/metadata.js";
 import { oauthAuthorizationServerMetadataPath, publicEndpointUrl, } from "./public-url.js";
 export function createForgeRelayAuthRouter(options) {
-    const { provider, issuerUrl, resourceServerUrl, scopesSupported, resourceName } = options;
+    const { provider, cliAuthenticationProvider, instanceId, issuerUrl, resourceServerUrl, scopesSupported, resourceName, } = options;
     const authorizationEndpoint = publicEndpointUrl(issuerUrl, "authorize");
     const tokenEndpoint = publicEndpointUrl(issuerUrl, "token");
     const registrationEndpoint = provider.clientsStore.registerClient
@@ -35,6 +35,26 @@ export function createForgeRelayAuthRouter(options) {
         resource_name: resourceName,
     };
     const router = express.Router();
+    if (cliAuthenticationProvider) {
+        router.post("/auth/cli", express.json({ limit: "4kb" }), (req, res) => {
+            const ownerToken = typeof req.body?.owner_token === "string" ? req.body.owner_token : undefined;
+            const refreshToken = typeof req.body?.refresh_token === "string" ? req.body.refresh_token : undefined;
+            if ((ownerToken ? 1 : 0) + (refreshToken ? 1 : 0) !== 1) {
+                res.status(400).json({ error: "invalid_request" });
+                return;
+            }
+            const tokens = ownerToken
+                ? cliAuthenticationProvider.issueCliTokens(ownerToken)
+                : cliAuthenticationProvider.exchangeCliRefreshToken(refreshToken);
+            if (!tokens) {
+                res.status(401).json({ error: "invalid_grant" });
+                return;
+            }
+            res.setHeader("Cache-Control", "no-store");
+            res.setHeader("Pragma", "no-cache");
+            res.status(200).json({ ...tokens, ...(instanceId ? { instance_id: instanceId } : {}) });
+        });
+    }
     router.use("/authorize", authorizationHandler({ provider }));
     router.use("/token", tokenHandler({ provider }));
     if (provider.clientsStore.registerClient) {

package/dist/oauth-provider.js

@@ -3,6 +3,7 @@ import { AccessDeniedError, InvalidGrantError, InvalidRequestError, InvalidToken
 import { checkResourceAllowed, resourceUrlFromServerUrl } from "@modelcontextprotocol/sdk/shared/auth-utils.js";
 import { SqliteOAuthClientsStore, SqliteOAuthStore } from "./oauth-store.js";
 const CODE_TTL_MS = 5 * 60 * 1000;
+const CLI_CLIENT_ID = "forgerelay-cli";
 function randomToken() {
     return randomBytes(32).toString("base64url");
 }
@@ -85,6 +86,15 @@ export class SingleUserOAuthProvider {
         this.config = config;
         this.resourceServerUrl = resourceUrlFromServerUrl(resourceServerUrl);
         this.oauthStore = new SqliteOAuthStore(stateDir);
+        this.oauthStore.ensureClient({
+            client_id: CLI_CLIENT_ID,
+            client_id_issued_at: Math.floor(Date.now() / 1000),
+            client_name: "ForgeRelay CLI",
+            redirect_uris: [],
+            token_endpoint_auth_method: "none",
+            grant_types: ["refresh_token"],
+            response_types: [],
+        });
         this.clientsStore = new SqliteOAuthClientsStore(this.oauthStore, config.allowedRedirectHosts);
     }
     async authorize(client, params, res) {
@@ -145,11 +155,10 @@ export class SingleUserOAuthProvider {
         return this.issueTokens(client.client_id, record.params.scopes ?? this.config.scopes, record.params.resource);
     }
     async exchangeRefreshToken(client, refreshToken, scopes, resource) {
-        const refreshTokenHash = hashToken(refreshToken);
-        const record = this.oauthStore.getRefreshToken(refreshTokenHash);
-        if (!record || record.clientId !== client.client_id || record.expiresAt < Math.floor(Date.now() / 1000)) {
+        const refresh = this.validRefreshToken(refreshToken, client.client_id);
+        if (!refresh)
             throw new InvalidGrantError("Invalid refresh token");
-        }
+        const { refreshTokenHash, record } = refresh;
         if (resource && !checkResourceAllowed({ requestedResource: resource, configuredResource: this.resourceServerUrl })) {
             throw new InvalidGrantError("Invalid resource");
         }
@@ -159,6 +168,17 @@ export class SingleUserOAuthProvider {
         }
         return this.issueTokens(client.client_id, requestedScopes, resource ?? (record.resource ? new URL(record.resource) : undefined), refreshTokenHash);
     }
+    issueCliTokens(ownerToken) {
+        if (!safeEquals(ownerToken, this.config.ownerToken))
+            return undefined;
+        return this.issueTokens(CLI_CLIENT_ID, this.config.scopes, this.resourceServerUrl);
+    }
+    exchangeCliRefreshToken(refreshToken) {
+        const refresh = this.validRefreshToken(refreshToken, CLI_CLIENT_ID);
+        if (!refresh)
+            return undefined;
+        return this.issueTokens(CLI_CLIENT_ID, refresh.record.scopes, refresh.record.resource ? new URL(refresh.record.resource) : this.resourceServerUrl, refresh.refreshTokenHash);
+    }
     async verifyAccessToken(token) {
         const record = this.oauthStore.getAccessToken(hashToken(token));
         if (!record || record.expiresAt < Math.floor(Date.now() / 1000)) {
@@ -181,6 +201,14 @@ export class SingleUserOAuthProvider {
         this.codes.clear();
         this.oauthStore.close();
     }
+    validRefreshToken(refreshToken, clientId) {
+        const refreshTokenHash = hashToken(refreshToken);
+        const record = this.oauthStore.getRefreshToken(refreshTokenHash);
+        if (!record || record.clientId !== clientId || record.expiresAt < Math.floor(Date.now() / 1000)) {
+            return undefined;
+        }
+        return { refreshTokenHash, record };
+    }
     pruneExpiredAuthorizationCodes(nowMs = Date.now()) {
         for (const [code, record] of this.codes) {
             if (record.expiresAtMs < nowMs)

package/dist/oauth-store.js

@@ -25,6 +25,15 @@ export class SqliteOAuthStore {
             .get(clientId);
         return row ? JSON.parse(row.client_json) : undefined;
     }
+    ensureClient(client) {
+        const existing = this.getClient(client.client_id);
+        if (existing)
+            return existing;
+        this.database.sqlite
+            .prepare("insert into oauth_clients (client_id, client_json, issued_at) values (?, ?, ?)")
+            .run(client.client_id, JSON.stringify(client), client.client_id_issued_at);
+        return client;
+    }
     registerClient(client, allowedRedirectHosts) {
         if (!client.redirect_uris.every((uri) => redirectHostAllowed(String(uri), allowedRedirectHosts))) {
             throw new InvalidRequestError("Client redirect_uri is not allowed for this ForgeRelay server");

package/dist/remote-auth.js

@@ -0,0 +1,110 @@
+import { readFileSync } from "node:fs";
+import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport, StreamableHTTPError, } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { publicEndpointUrl } from "./oauth/public-url.js";
+const REMOTE_AUTH_TIMEOUT_MS = 15_000;
+const packageVersion = readForgeRelayVersion();
+export function normalizeRemoteServiceTarget(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new Error("Missing remote service target.");
+    const url = new URL(trimmed.includes("://") ? trimmed : `http://${trimmed}`);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`Unsupported remote service protocol: ${url.protocol}`);
+    }
+    if (url.username || url.password) {
+        throw new Error("Remote service target must not contain credentials.");
+    }
+    if (url.search || url.hash) {
+        throw new Error("Remote service target must not contain a query or fragment.");
+    }
+    url.pathname = url.pathname.replace(/\/+$/, "");
+    return url.toString().replace(/\/$/, "");
+}
+export function defaultRemoteAlias(target) {
+    const hostname = new URL(target).hostname;
+    return hostname.replace(/^\[|\]$/g, "");
+}
+export async function authenticateRemote(targetInput, ownerToken) {
+    const target = normalizeRemoteServiceTarget(targetInput);
+    return exchangeCliCredential(target, { owner_token: ownerToken });
+}
+export async function refreshRemoteAuthentication(remote, endpointInput = remote.target) {
+    const refreshed = await exchangeCliCredential(normalizeRemoteServiceTarget(endpointInput), { refresh_token: remote.refreshToken });
+    if (refreshed.instanceId !== remote.instanceId) {
+        throw new Error(`Remote instance changed from ${remote.instanceId} to ${refreshed.instanceId}; refusing to update stored credentials.`);
+    }
+    return {
+        ...remote,
+        accessToken: refreshed.accessToken,
+        refreshToken: refreshed.refreshToken,
+        accessTokenExpiresAt: refreshed.accessTokenExpiresAt,
+        scope: refreshed.scope,
+    };
+}
+export function isRemoteMcpUnauthorized(error) {
+    return error instanceof UnauthorizedError ||
+        (error instanceof StreamableHTTPError && error.code === 401);
+}
+export async function withRemoteMcpClient(remote, endpointInput, operation) {
+    const endpoint = normalizeRemoteServiceTarget(endpointInput);
+    const client = new Client({ name: "forgerelay-cli", version: packageVersion });
+    const transport = new StreamableHTTPClientTransport(publicEndpointUrl(endpoint, "mcp"), {
+        requestInit: {
+            headers: { Authorization: `Bearer ${remote.accessToken}` },
+        },
+    });
+    try {
+        await client.connect(transport);
+        return await operation(client);
+    }
+    finally {
+        await client.close().catch(() => undefined);
+    }
+}
+export async function verifyRemoteMcp(remote, endpointInput = remote.target) {
+    await withRemoteMcpClient(remote, endpointInput, async () => undefined);
+}
+async function exchangeCliCredential(target, credential) {
+    const response = await fetch(publicEndpointUrl(target, "auth/cli"), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(credential),
+        signal: AbortSignal.timeout(REMOTE_AUTH_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        let reason = response.statusText || `HTTP ${response.status}`;
+        try {
+            const body = await response.json();
+            if (typeof body.error === "string" && body.error)
+                reason = body.error;
+        }
+        catch {
+            // Keep the status-derived error without exposing the submitted secret.
+        }
+        throw new Error(`Remote authentication failed: ${reason}`);
+    }
+    const body = await response.json();
+    if (typeof body.instance_id !== "string" || !body.instance_id.trim()) {
+        throw new Error("Remote authentication response did not include an instance id.");
+    }
+    if (typeof body.access_token !== "string" || typeof body.refresh_token !== "string") {
+        throw new Error("Remote authentication response did not include the required tokens.");
+    }
+    return {
+        instanceId: body.instance_id,
+        target,
+        accessToken: body.access_token,
+        refreshToken: body.refresh_token,
+        accessTokenExpiresAt: Math.floor(Date.now() / 1000) + (body.expires_in ?? 0),
+        ...(body.scope ? { scope: body.scope } : {}),
+    };
+}
+function readForgeRelayVersion() {
+    const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    if (typeof packageJson.version !== "string" || packageJson.version.length === 0) {
+        throw new Error("Unable to read ForgeRelay package version.");
+    }
+    return packageJson.version;
+}

package/dist/remote-transport.js

@@ -0,0 +1,196 @@
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { createConnection, createServer } from "node:net";
+const SSH_START_TIMEOUT_MS = 15_000;
+const SSH_COMMAND_TIMEOUT_MS = 15_000;
+const SSH_STOP_TIMEOUT_MS = 2_000;
+export function parseSshRoute(value) {
+    const route = value.split(",").map((entry) => entry.trim()).filter(Boolean);
+    if (route.length === 0)
+        throw new Error("SSH route must contain at least one target.");
+    for (const entry of route) {
+        if (entry.startsWith("-") || /\s/.test(entry)) {
+            throw new Error(`Invalid SSH route target: ${entry}`);
+        }
+    }
+    return route;
+}
+export function defaultSshRouteAlias(route) {
+    const finalTarget = route.at(-1);
+    if (!finalTarget)
+        throw new Error("SSH route must contain a final target.");
+    const at = finalTarget.lastIndexOf("@");
+    return (at >= 0 ? finalTarget.slice(at + 1) : finalTarget).trim();
+}
+export async function readRemoteOwnerToken(sshRoute) {
+    const { prefix, target } = sshDestinationArgs(sshRoute);
+    const result = await runSshCommand([
+        ...prefix,
+        target,
+        "forgerelay",
+        "auth",
+        "__owner-token",
+    ]);
+    const token = result.stdout.trim();
+    if (!token)
+        throw new Error("SSH owner-token command returned an empty token.");
+    return token;
+}
+export async function withRemoteServiceEndpoint(target, sshRoute, operation) {
+    if (!sshRoute)
+        return operation(target);
+    const url = new URL(target);
+    if (url.protocol === "https:") {
+        throw new Error("SSH-routed HTTPS service targets are not supported because loopback forwarding breaks TLS hostname verification; use the remote ForgeRelay HTTP loopback endpoint through SSH or direct HTTPS.");
+    }
+    const remotePort = url.port || "80";
+    const localPort = await allocateLoopbackPort();
+    const { prefix, target: sshTarget } = sshDestinationArgs(sshRoute);
+    const forwardSpec = `127.0.0.1:${localPort}:${url.hostname}:${remotePort}`;
+    const tunnel = spawn("ssh", [
+        ...prefix,
+        "-v",
+        "-N",
+        "-T",
+        "-o",
+        "ExitOnForwardFailure=yes",
+        "-L",
+        forwardSpec,
+        sshTarget,
+    ], {
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    let forwardingReady = false;
+    const readyMarker = `Local forwarding listening on 127.0.0.1 port ${localPort}`;
+    const stderr = collectStream(tunnel.stderr, (value) => {
+        if (value.includes(readyMarker))
+            forwardingReady = true;
+    });
+    let spawnError;
+    tunnel.once("error", (error) => {
+        spawnError = error;
+    });
+    try {
+        await waitForLoopbackPort(tunnel, localPort, stderr, () => spawnError, () => forwardingReady);
+        const mapped = new URL(url);
+        mapped.hostname = "127.0.0.1";
+        mapped.port = String(localPort);
+        try {
+            return await operation(mapped.toString().replace(/\/$/, ""));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Remote service request through SSH tunnel failed: ${message}`, { cause: error });
+        }
+    }
+    finally {
+        await stopTunnel(tunnel);
+    }
+}
+function sshDestinationArgs(sshRoute) {
+    if (sshRoute.length === 0)
+        throw new Error("SSH route must contain a final target.");
+    const target = sshRoute[sshRoute.length - 1];
+    const jumps = sshRoute.slice(0, -1);
+    return {
+        prefix: jumps.length > 0 ? ["-J", jumps.join(",")] : [],
+        target,
+    };
+}
+async function allocateLoopbackPort() {
+    const server = createServer();
+    server.listen(0, "127.0.0.1");
+    await once(server, "listening");
+    const address = server.address();
+    if (!address || typeof address === "string") {
+        server.close();
+        throw new Error("Unable to allocate a local SSH forwarding port.");
+    }
+    const port = address.port;
+    await new Promise((resolve, reject) => {
+        server.close((error) => error ? reject(error) : resolve());
+    });
+    return port;
+}
+async function waitForLoopbackPort(process, port, stderr, spawnError, forwardingReady) {
+    const deadline = Date.now() + SSH_START_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        const error = spawnError();
+        if (error)
+            throw new Error(`Unable to start SSH tunnel: ${error.message}`);
+        if (process.exitCode !== null) {
+            throw new Error(formatSshFailure("SSH tunnel exited before forwarding was ready", process.exitCode, stderr()));
+        }
+        if (forwardingReady() && await canConnect(port))
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 40));
+    }
+    throw new Error("SSH tunnel did not become ready before the connection timeout.");
+}
+function canConnect(port) {
+    return new Promise((resolve) => {
+        const socket = createConnection({ host: "127.0.0.1", port });
+        socket.once("connect", () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.once("error", () => resolve(false));
+    });
+}
+async function runSshCommand(args) {
+    const child = spawn("ssh", args, {
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    const stdout = collectStream(child.stdout);
+    const stderr = collectStream(child.stderr);
+    const timeout = setTimeout(() => child.kill("SIGKILL"), SSH_COMMAND_TIMEOUT_MS);
+    let code;
+    let signal;
+    try {
+        [code, signal] = await once(child, "close");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Unable to start SSH command: ${message}`);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+    if (code !== 0) {
+        const suffix = signal ? ` (${signal})` : "";
+        throw new Error(formatSshFailure(`SSH command failed${suffix}`, code, stderr()));
+    }
+    return { stdout: stdout(), stderr: stderr() };
+}
+function collectStream(stream, observe) {
+    let value = "";
+    stream.setEncoding?.("utf8");
+    stream.on("data", (chunk) => {
+        value += String(chunk);
+        observe?.(value);
+        if (value.length > 16_384)
+            value = value.slice(-16_384);
+    });
+    return () => value;
+}
+async function stopTunnel(process) {
+    if (process.exitCode !== null)
+        return;
+    const closed = once(process, "close").then(() => true).catch(() => true);
+    process.kill("SIGTERM");
+    const timedOut = new Promise((resolve) => setTimeout(() => resolve(false), SSH_STOP_TIMEOUT_MS));
+    if (await Promise.race([closed, timedOut]))
+        return;
+    if (process.exitCode !== null)
+        return;
+    const killed = once(process, "close").then(() => undefined).catch(() => undefined);
+    process.kill("SIGKILL");
+    const killTimedOut = new Promise((resolve) => setTimeout(resolve, SSH_STOP_TIMEOUT_MS));
+    await Promise.race([killed, killTimedOut]);
+}
+function formatSshFailure(prefix, code, stderr) {
+    const detail = stderr.trim();
+    return `${prefix} (exit ${code ?? "unknown"})${detail ? `: ${detail}` : ""}`;
+}