@hahnfeld/msrelay-provider 0.1.1 → 0.1.4

package/README.md

@@ -45,48 +45,24 @@ This plugin provides a tunnel — it makes a local port reachable via a stable H
 openacp plugin install @hahnfeld/msrelay-provider
 ```
 
-The install wizard prompts for:
+The install wizard walks you through the full Azure setup — showing the `az` CLI commands for each step and prompting for the values. You'll need the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) installed.
 
-1. Azure Relay namespace (e.g., `myrelay.servicebus.windows.net`)
-2. Hybrid Connection name (e.g., `bot-endpoint`)
-3. SAS policy name and key (with `Listen` permission)
-4. Local port to forward to (3978 for Bot Framework, 21420 for OpenACP API server, or any custom port)
+The wizard covers:
 
-## Azure Setup
+1. Creating a Relay namespace
+2. Creating a Hybrid Connection (with client authorization disabled)
+3. Creating a listen-only SAS policy
+4. Retrieving the SAS key
+5. Choosing a local port to forward to
 
-Before installing the plugin, provision these Azure resources:
+On reinstall, existing values are pre-filled so you can press Enter to keep them. The SAS key is masked and can be kept without re-entering.
 
-```bash
-# 1. Create Relay namespace
-az relay namespace create \
-  --resource-group <rg> --name <namespace> --location westus2
-
-# 2. Create Hybrid Connection
-az relay hyco create \
-  --resource-group <rg> --namespace-name <namespace> --name my-connection
-
-# 3. Disable client authorization (required if callers can't send SAS headers —
-#    e.g., Bot Framework, external webhooks, third-party services)
-az relay hyco update \
-  --resource-group <rg> --namespace-name <namespace> \
-  --name my-connection --requires-client-authorization false
-
-# 4. Create listen-only SAS policy (least privilege)
-az relay hyco authorization-rule create \
-  --resource-group <rg> --namespace-name <namespace> \
-  --hybrid-connection-name my-connection \
-  --name ListenOnly --rights Listen
-
-# 5. Retrieve the key
-az relay hyco authorization-rule keys list \
-  --resource-group <rg> --namespace-name <namespace> \
-  --hybrid-connection-name my-connection --name ListenOnly
-```
+After setup, the wizard tests connectivity by opening a real WebSocket to Azure Relay.
 
-The resulting endpoint URL is:
+The resulting public endpoint URL is:
 
 ```
-https://<namespace>.servicebus.windows.net/my-connection
+https://<namespace>.servicebus.windows.net/<connection>
 ```
 
 Point your external callers (Bot Framework messaging endpoint, webhook URLs, etc.) at this URL.
@@ -113,13 +89,13 @@ openacp plugin configure @hahnfeld/msrelay-provider
 | Command | Description |
 |---------|-------------|
 | `/relay` | Show connection status, uptime, request/error counts |
-| `/relay auth` | Validate SAS key by generating a test token |
+| `/relay auth` | Test connectivity by connecting to Azure Relay |
 
 ## Development
 
 ```bash
 pnpm install
-pnpm test          # Run tests (28 tests)
+pnpm test          # Run tests (42 tests)
 pnpm build         # Compile TypeScript
 pnpm dev           # Watch mode
 pnpm lint          # Type-check without emitting

package/dist/plugin.js

@@ -10,20 +10,41 @@ function isValidNamespace(v) {
 function isValidConnectionName(v) {
     return /^[a-zA-Z0-9._-]+$/.test(v);
 }
-/** Test SAS key by generating a token. No network call — just validates the key format. */
-function testSasToken(namespace, connectionName, keyName, keyValue) {
-    try {
-        const hycoHttps = require("hyco-https");
-        const uri = hycoHttps.createRelayListenUri(namespace, connectionName);
-        const token = hycoHttps.createRelayToken(uri, keyName, keyValue);
-        if (token && typeof token === "string") {
-            return { ok: true };
+/** Test connectivity by opening a real WebSocket to Azure Relay. */
+function testRelayConnection(namespace, connectionName, keyName, keyValue, timeoutMs = 10_000) {
+    return new Promise((resolve) => {
+        try {
+            const hycoHttps = require("hyco-https");
+            const uri = hycoHttps.createRelayListenUri(namespace, connectionName);
+            const server = hycoHttps.createRelayedServer({ server: uri, token: () => hycoHttps.createRelayToken(uri, keyName, keyValue) }, () => { });
+            let settled = false;
+            const settle = (result) => {
+                if (!settled) {
+                    settled = true;
+                    try {
+                        server.close();
+                    }
+                    catch { /* ignore */ }
+                    resolve(result);
+                }
+            };
+            const timer = setTimeout(() => {
+                settle({ ok: false, error: "Connection timed out — check namespace, connection name, and network access" });
+            }, timeoutMs);
+            server.on("listening", () => {
+                clearTimeout(timer);
+                settle({ ok: true });
+            });
+            server.on("error", (err) => {
+                clearTimeout(timer);
+                settle({ ok: false, error: `Connection failed: ${err.message}` });
+            });
+            server.listen();
+        }
+        catch (err) {
+            resolve({ ok: false, error: `Setup failed: ${err.message}` });
         }
-        return { ok: false, error: "Token generation returned empty result" };
-    }
-    catch (err) {
-        return { ok: false, error: `Token generation failed: ${err.message}` };
-    }
+    });
 }
 /** Format elapsed time as human-readable duration. */
 function formatUptime(startedAt) {
@@ -64,7 +85,7 @@ export function createRelayPlugin() {
     let provider = null;
     return {
         name: "@hahnfeld/msrelay-provider",
-        version: "0.1.1",
+        version: "0.1.4",
         description: "Azure Relay Hybrid Connections tunnel provider — private HTTP tunneling via Azure backbone",
         essential: false,
         permissions: [
@@ -77,30 +98,54 @@ export function createRelayPlugin() {
         // ─── Interactive Install Wizard ──────────────────────────────────────
         async install(ctx) {
             const { terminal, settings } = ctx;
-            terminal.note("This plugin uses Azure Relay Hybrid Connections to expose local ports\n" +
-                "through Azure's private backbone (ExpressRoute). No public internet exposure.\n" +
-                "\n" +
-                "Prerequisites:\n" +
-                "  1. Azure Relay namespace (e.g., myrelay.servicebus.windows.net)\n" +
-                "  2. Hybrid Connection with client authorization DISABLED\n" +
-                "  3. SAS key with Listen permission\n" +
+            // Load existing config for pre-filling on reinstall
+            const existing = await settings.getAll();
+            terminal.note("This wizard walks you through setting up Azure Relay Hybrid Connections.\n" +
+                "It exposes local ports through Azure's private backbone — no public\n" +
+                "internet exposure, no inbound ports.\n" +
                 "\n" +
-                "See SPEC.md Section 12 for Azure CLI setup commands.", "Azure Relay Setup");
+                "You'll need the Azure CLI installed (az). Each step shows the command\n" +
+                "to run. If you've already provisioned these resources, just enter the\n" +
+                "existing values when prompted.", "Azure Relay Setup");
             // ── Step 1: Relay Namespace ──
-            const namespace = await terminal.text({
-                message: "Azure Relay namespace (e.g., myrelay.servicebus.windows.net):",
+            terminal.note("Create a Relay namespace (if you don't have one):\n" +
+                "\n" +
+                "  az relay namespace create \\\n" +
+                "    --resource-group <resource-group> \\\n" +
+                "    --name <choose-a-name> \\\n" +
+                "    --location westus2\n" +
+                "\n" +
+                "The namespace becomes <name>.servicebus.windows.net", "Step 1: Create Relay Namespace");
+            const namespaceInput = await terminal.text({
+                message: "Azure Relay namespace (e.g., myrelay or myrelay.servicebus.windows.net):",
+                defaultValue: existing.relayNamespace ?? undefined,
                 validate: (v) => {
-                    const trimmed = v.trim();
-                    if (!trimmed)
+                    if (!v.trim())
                         return "Namespace is required";
-                    if (!isValidNamespace(trimmed))
-                        return "Must be <name>.servicebus.windows.net";
                     return undefined;
                 },
             });
-            // ── Step 2: Hybrid Connection Name ──
+            const ns = namespaceInput.trim().endsWith(".servicebus.windows.net")
+                ? namespaceInput.trim()
+                : `${namespaceInput.trim()}.servicebus.windows.net`;
+            if (!isValidNamespace(ns)) {
+                terminal.log.warning(`"${ns}" doesn't look like a valid namespace — continuing anyway`);
+            }
+            const nsName = ns.replace(".servicebus.windows.net", "");
+            // ── Step 2: Hybrid Connection ──
+            terminal.note("Create a Hybrid Connection with client authorization disabled:\n" +
+                "\n" +
+                `  az relay hyco create \\\n` +
+                `    --resource-group <resource-group> \\\n` +
+                `    --namespace-name ${nsName} \\\n` +
+                `    --name <choose-a-name> \\\n` +
+                `    --requires-client-authorization false\n` +
+                "\n" +
+                "IMPORTANT: --requires-client-authorization cannot be changed after\n" +
+                "creation. If you need to change it, delete and recreate the connection.", "Step 2: Create Hybrid Connection");
             const connectionName = await terminal.text({
                 message: "Hybrid Connection name (e.g., bot-endpoint):",
+                defaultValue: existing.hybridConnectionName ?? undefined,
                 validate: (v) => {
                     const trimmed = v.trim();
                     if (!trimmed)
@@ -110,38 +155,72 @@ export function createRelayPlugin() {
                     return undefined;
                 },
             });
-            // ── Step 3: SAS Key Name ──
+            const hc = connectionName.trim();
+            // ── Step 3: SAS Policy ──
+            terminal.note("Create a listen-only SAS authorization rule:\n" +
+                "\n" +
+                `  az relay hyco authorization-rule create \\\n` +
+                `    --resource-group <resource-group> \\\n` +
+                `    --namespace-name ${nsName} \\\n` +
+                `    --hybrid-connection-name ${hc} \\\n` +
+                `    --name ListenOnly --rights Listen\n` +
+                "\n" +
+                "Use a listen-only policy — this plugin only needs Listen permission.\n" +
+                "Do not use RootManageSharedAccessKey.", "Step 3: Create SAS Policy");
             const keyName = await terminal.text({
                 message: "SAS policy name:",
-                defaultValue: "ListenOnly",
+                defaultValue: existing.sasKeyName ?? "ListenOnly",
                 validate: (v) => {
                     if (!v.trim())
-                        return "Key name is required";
+                        return "Policy name is required";
                     return undefined;
                 },
             });
-            // ── Step 4: SAS Key Value ──
-            const keyValue = await terminal.text({
-                message: "SAS key value:",
+            const sasName = keyName.trim();
+            // ── Step 4: SAS Key ──
+            terminal.note("Get the SAS key with this command:\n" +
+                "\n" +
+                `  az relay hyco authorization-rule keys list \\\n` +
+                `    --resource-group <resource-group> \\\n` +
+                `    --namespace-name ${nsName} \\\n` +
+                `    --hybrid-connection-name ${hc} \\\n` +
+                `    --name ${sasName} \\\n` +
+                `    --query primaryKey -o tsv\n` +
+                "\n" +
+                "Copy the output — that's your SAS key value.", "Step 4: Get SAS Key");
+            const hasExistingKey = !!(existing.sasKeyValue);
+            let keyValue = await terminal.password({
+                message: hasExistingKey
+                    ? "SAS key value — press Enter to keep current:"
+                    : "SAS key value (paste the primaryKey):",
                 validate: (v) => {
-                    if (!v.trim())
+                    if (!(v ?? "").trim() && !hasExistingKey)
                         return "Key value is required";
                     return undefined;
                 },
             });
-            // ── Step 5: Port ──
-            terminal.log.info("");
+            if (!(keyValue ?? "").trim() && hasExistingKey) {
+                keyValue = existing.sasKeyValue;
+            }
+            // ── Step 6: Port ──
             terminal.note("This tunnel can point to any local port. Common choices:\n" +
                 "\n" +
                 "  3978  — Teams adapter (Microsoft Bot Framework default)\n" +
                 "  21420 — OpenACP API server\n" +
                 "\n" +
-                "You can change this later with: openacp plugin configure @hahnfeld/msrelay-provider", "Port Selection");
+                "You can change this later with:\n" +
+                "  openacp plugin configure @hahnfeld/msrelay-provider", "Step 5: Port Selection");
+            const existingPort = existing.port;
             const envPort = process.env.PORT ? Number(process.env.PORT) : null;
             const portChoice = await terminal.select({
                 message: "Which port should the tunnel expose?",
                 options: [
-                    ...(envPort ? [{ value: String(envPort), label: `${envPort} (from PORT env var)`, hint: "Current environment" }] : []),
+                    ...(existingPort && existingPort !== 3978 && existingPort !== 21420
+                        ? [{ value: String(existingPort), label: `${existingPort} (current config)`, hint: "Previously configured" }]
+                        : []),
+                    ...(envPort && envPort !== existingPort
+                        ? [{ value: String(envPort), label: `${envPort} (from PORT env var)`, hint: "Current environment" }]
+                        : []),
                     { value: "3978", label: "3978", hint: "Teams adapter (Bot Framework default)" },
                     { value: "21420", label: "21420", hint: "OpenACP API server" },
                     { value: "custom", label: "Other port" },
@@ -151,6 +230,7 @@ export function createRelayPlugin() {
             if (portChoice === "custom") {
                 const portStr = await terminal.text({
                     message: "Local port to expose:",
+                    defaultValue: existingPort ? String(existingPort) : undefined,
                     validate: (v) => {
                         const trimmed = v.trim();
                         if (!trimmed)
@@ -166,39 +246,42 @@ export function createRelayPlugin() {
             else {
                 port = Number(portChoice);
             }
-            // ── Step 6: Connectivity Test (optional) ──
+            // ── Step 7: Connectivity Test (optional) ──
             const wantTest = await terminal.confirm({
-                message: "Test connectivity now? (Attempts to connect to the Relay for 10s)",
-                initialValue: false,
+                message: "Test connectivity now? (connects to Azure Relay for up to 10s)",
+                initialValue: true,
             });
             if (wantTest) {
                 const spin = terminal.spinner();
-                spin.start("Testing SAS token generation...");
-                const tokenResult = testSasToken(namespace.trim(), connectionName.trim(), keyName.trim(), keyValue.trim());
-                if (tokenResult.ok) {
-                    spin.stop("SAS token generated successfully");
+                spin.start("Connecting to Azure Relay...");
+                const result = await testRelayConnection(ns, hc, sasName, keyValue.trim());
+                if (result.ok) {
+                    spin.stop("Connected to Azure Relay successfully");
                 }
                 else {
-                    spin.fail(tokenResult.error);
+                    spin.fail(result.error);
                     terminal.log.warning("Installation will continue — you can test connectivity later with /relay auth");
                 }
             }
-            // ── Step 7: Save ──
+            // ── Step 8: Save ──
             await settings.setAll({
                 enabled: true,
                 port,
-                relayNamespace: namespace.trim(),
-                hybridConnectionName: connectionName.trim(),
-                sasKeyName: keyName.trim(),
+                relayNamespace: ns,
+                hybridConnectionName: hc,
+                sasKeyName: sasName,
                 sasKeyValue: keyValue.trim(),
             });
             terminal.log.success("Azure Relay provider configured!");
             terminal.log.info("");
-            terminal.note(`Namespace:  ${namespace.trim()}\n` +
-                `Connection: ${connectionName.trim()}\n` +
-                `SAS policy: ${keyName.trim()}\n` +
+            terminal.note(`Namespace:  ${ns}\n` +
+                `Connection: ${hc}\n` +
+                `SAS policy: ${sasName}\n` +
                 `Port:       ${port}\n` +
-                `Public URL: https://${namespace.trim()}/${connectionName.trim()}`, "Configuration Summary");
+                `Public URL: https://${ns}/${hc}\n` +
+                "\n" +
+                "Point your Bot Framework messaging endpoint (or webhook URLs) at\n" +
+                "the public URL above.", "Configuration Summary");
         },
         // ─── Configure (post-install changes) ────────────────────────────────
         async configure(ctx) {
@@ -270,7 +353,7 @@ export function createRelayPlugin() {
                         break;
                     }
                     case "sasKeyValue": {
-                        const val = await terminal.text({
+                        const val = await terminal.password({
                             message: "SAS key value:",
                             validate: (v) => {
                                 if (!v.trim())
@@ -308,10 +391,10 @@ export function createRelayPlugin() {
                     }
                     case "auth": {
                         const spin = terminal.spinner();
-                        spin.start("Testing SAS token generation...");
-                        const result = testSasToken(current.relayNamespace, current.hybridConnectionName, current.sasKeyName, current.sasKeyValue);
+                        spin.start("Connecting to Azure Relay...");
+                        const result = await testRelayConnection(current.relayNamespace, current.hybridConnectionName, current.sasKeyName, current.sasKeyValue);
                         if (result.ok) {
-                            spin.stop("SAS token generated successfully");
+                            spin.stop("Connected to Azure Relay successfully");
                         }
                         else {
                             spin.fail(result.error);
@@ -394,9 +477,9 @@ export function createRelayPlugin() {
                     const raw = args.raw.trim();
                     if (raw === "auth") {
                         const cfg = config;
-                        const result = testSasToken(cfg.relayNamespace, cfg.hybridConnectionName, cfg.sasKeyName, cfg.sasKeyValue);
+                        const result = await testRelayConnection(cfg.relayNamespace, cfg.hybridConnectionName, cfg.sasKeyName, cfg.sasKeyValue);
                         if (result.ok) {
-                            return { type: "text", text: "SAS token generation: OK" };
+                            return { type: "text", text: "Azure Relay connectivity: OK" };
                         }
                         return { type: "error", message: result.error };
                     }

package/dist/provider.js

@@ -171,19 +171,17 @@ export class AzureRelayProvider {
                     onUnexpectedClose();
                 }
             });
-            server.listen((err) => {
+            // hyco-https listen() takes no arguments — readiness is signaled
+            // via the 'listening' event when the control channel WebSocket opens.
+            server.on("listening", () => {
                 clearTimeout(timeout);
-                if (err) {
-                    this.server = null;
-                    settle(() => reject(new Error(`Azure Relay listen failed: ${err.message}`)));
-                    return;
-                }
                 this.publicUrl = `https://${relayNamespace}/${hybridConnectionName}`;
                 if (!this.metrics.startedAt) {
                     this.metrics.startedAt = new Date();
                 }
                 settle(() => resolve(this.publicUrl));
             });
+            server.listen();
         });
     }
     /**
@@ -236,12 +234,18 @@ export class AzureRelayProvider {
             this.sendError(relayRes, 400, "Bad Request", `Invalid request URL: ${rawUrl}`);
             return;
         }
+        // Azure Relay prepends the Hybrid Connection name to the path.
+        // e.g., /bot-endpoint/api/messages → /api/messages
+        const prefix = `/${this.config.hybridConnectionName}`;
+        const forwardPath = rawUrl.startsWith(prefix)
+            ? (rawUrl.slice(prefix.length) || "/")
+            : rawUrl;
         const forwardHeaders = stripHopByHop(relayReq.headers);
         forwardHeaders["host"] = `localhost:${this.localPort}`;
         const localReq = httpRequest({
             hostname: "localhost",
             port: this.localPort,
-            path: rawUrl,
+            path: forwardPath,
             method: relayReq.method,
             headers: forwardHeaders,
             timeout: LOCAL_FORWARD_TIMEOUT_MS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hahnfeld/msrelay-provider",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "Azure Relay Hybrid Connections tunnel provider plugin for OpenACP",
   "type": "module",
   "main": "dist/index.js",