fix(setup): require an http or https RPC URL

Author: 0dillon

docs/superpowers/plans/2026-08-02-ledgerkeep-cli.md

@@ -1179,11 +1179,17 @@ function requireContractId(env: NodeJS.ProcessEnv, name: string): string {
 
 function requireUrl(env: NodeJS.ProcessEnv, name: string): string {
   const raw = requireString(env, name);
+  let parsed: URL;
   try {
-    new URL(raw);
+    parsed = new URL(raw);
   } catch {
     throw new ConfigError(`${name} is not a valid URL, got: ${raw}`);
   }
+  // The only consumer is the RPC client, which speaks http(s). Rejecting other
+  // schemes here gives a clear message instead of an SDK failure further in.
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new ConfigError(`${name} must be an http or https URL, got: ${raw}`);
+  }
   return raw;
 }
 

src/config.ts

@@ -50,11 +50,17 @@ function requireContractId(env: NodeJS.ProcessEnv, name: string): string {
 
 function requireUrl(env: NodeJS.ProcessEnv, name: string): string {
   const raw = requireString(env, name);
+  let parsed: URL;
   try {
-    new URL(raw);
+    parsed = new URL(raw);
   } catch {
     throw new ConfigError(`${name} is not a valid URL, got: ${raw}`);
   }
+  // The only consumer is the RPC client, which speaks http(s). Rejecting other
+  // schemes here gives a clear message instead of an SDK failure further in.
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new ConfigError(`${name} must be an http or https URL, got: ${raw}`);
+  }
   return raw;
 }
 

test/config.test.ts

@@ -44,8 +44,9 @@ describe("loadConfig", () => {
   it("does not open the keeper key file", () => {
     // Read-only commands run on machines that hold no key. Loading config must
     // not touch the path, so an unreadable path is not an error here.
-    const config = loadConfig(completeEnv({ LK_KEEPER_KEY: "/nonexistent/nope.key" }));
-    expect(config.keeperKeyPath).toBe("/nonexistent/nope.key");
+    const env = completeEnv({ LK_KEEPER_KEY: "/nonexistent/nope.key" });
+    expect(() => loadConfig(env)).not.toThrow();
+    expect(loadConfig(env).keeperKeyPath).toBe("/nonexistent/nope.key");
   });
 
   it("names the missing variable", () => {
@@ -89,6 +90,21 @@ describe("loadConfig", () => {
   it("rejects a malformed RPC URL", () => {
     expect(() => loadConfig(completeEnv({ LK_RPC_URL: "not a url" }))).toThrow(/not a valid URL/);
   });
+
+  it("rejects a URL whose scheme the RPC client cannot speak", () => {
+    // Parses fine, but nothing downstream could ever use it.
+    expect(() => loadConfig(completeEnv({ LK_RPC_URL: "file:///etc/passwd" }))).toThrow(
+      /must be an http or https URL/,
+    );
+    expect(() => loadConfig(completeEnv({ LK_RPC_URL: "ftp://example.com" }))).toThrow(
+      /must be an http or https URL/,
+    );
+  });
+
+  it("accepts a loopback http URL for a local quickstart", () => {
+    const config = loadConfig(completeEnv({ LK_RPC_URL: "http://localhost:8000/soroban/rpc" }));
+    expect(config.rpcUrl).toBe("http://localhost:8000/soroban/rpc");
+  });
 });
 
 describe("loadKeypair", () => {