mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-16 02:40:39 +09:00
Fix SSH callback URL selection for LAN and private networks (#4799)
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - Agents can run on remote hosts via SSH environments > - When a remote agent needs to call back to the Paperclip API, it needs a reachable URL > - But the runtime API URL candidate builder did not account for private network topologies where the server is only reachable via LAN or VPN addresses > - Agents on SSH hosts were failing to connect because the callback URL pointed to localhost or an unreachable address > - This PR fixes callback URL selection to honor `PAPERCLIP_API_URL`, prefer LAN-reachable candidates, filter unreachable link-local addresses, and include interface hosts in onboarding invite URLs > - The benefit is SSH-based agents can reliably reach the Paperclip API on private networks without manual URL configuration ## What Changed - `runtime-api.ts`: Added `PAPERCLIP_API_URL` as a first-priority candidate in `buildRuntimeApiCandidateUrls`; extracted `collectReachableInterfaceHosts` to enumerate non-loopback, non-link-local network interface IPs with IPv4 preference - `server/src/index.ts`: Export `PAPERCLIP_API_URL` from the server environment so it is available to callback candidate resolution - `server/src/routes/access.ts`: Include LAN interface hosts in onboarding invite connection candidates - `server/src/config.ts`: Attempted auto-allowing LAN interface hosts, then reverted to the per-instance allowlist approach (both commits included for history clarity) ## Verification - `pnpm test` — all existing and new tests pass, including new tests for LAN candidate ordering and link-local filtering - `pnpm typecheck` — clean - Manual: start a Paperclip server on a machine with a LAN IP, create an SSH environment pointing to another host on the same LAN, verify the agent's callback URL uses the LAN IP rather than localhost ## Risks - Low-medium. The candidate list now includes more addresses (all non-loopback LAN interfaces). These are candidates for the agent to try, not an allowlist — the server's allowed hostnames still gate which origins are accepted. Ordering change (LAN preferred over loopback) could affect existing setups where localhost was intentionally preferred. ## Model Used Codex GPT 5.4 high via Paperclip. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge
This commit is contained in:
Devin Foley
GitHub
parent
9b99d30330
commit
367d4cab72
7 changed files with 221 additions and 14 deletions
|
|
@ -1,4 +1,6 @@
|
|||
import os from "node:os";
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { vi } from "vitest";
|
||||
import type { Request } from "express";
|
||||
import { buildInviteOnboardingTextDocument } from "../routes/access.js";
|
||||
|
||||
|
|
@ -114,4 +116,68 @@ describe("buildInviteOnboardingTextDocument", () => {
|
|||
expect(text).toContain("Message from inviter");
|
||||
expect(text).toContain("prioritize flaky test triage first");
|
||||
});
|
||||
|
||||
it("includes LAN candidates when the advertised host is tailnet-only", () => {
|
||||
const networkSpy = vi.spyOn(os, "networkInterfaces").mockReturnValue({
|
||||
en0: [
|
||||
{
|
||||
address: "fe80::1",
|
||||
family: "IPv6",
|
||||
internal: false,
|
||||
netmask: "ffff:ffff:ffff:ffff::",
|
||||
cidr: "fe80::1/64",
|
||||
mac: "00:00:00:00:00:00",
|
||||
scopeid: 1,
|
||||
},
|
||||
{
|
||||
address: "192.168.6.178",
|
||||
family: "IPv4",
|
||||
internal: false,
|
||||
netmask: "255.255.252.0",
|
||||
cidr: "192.168.6.178/22",
|
||||
mac: "00:00:00:00:00:00",
|
||||
},
|
||||
],
|
||||
utun0: [
|
||||
{
|
||||
address: "203.0.113.42",
|
||||
family: "IPv4",
|
||||
internal: false,
|
||||
netmask: "255.255.255.255",
|
||||
cidr: "203.0.113.42/32",
|
||||
mac: "00:00:00:00:00:00",
|
||||
},
|
||||
],
|
||||
});
|
||||
|
||||
try {
|
||||
const req = buildReq("paperclip.example.test:3103");
|
||||
const invite = {
|
||||
id: "invite-4",
|
||||
companyId: "company-1",
|
||||
inviteType: "company_join",
|
||||
allowedJoinTypes: "agent",
|
||||
tokenHash: "hash",
|
||||
defaultsPayload: null,
|
||||
expiresAt: new Date("2026-03-05T00:00:00.000Z"),
|
||||
invitedByUserId: null,
|
||||
revokedAt: null,
|
||||
acceptedAt: null,
|
||||
createdAt: new Date("2026-03-04T00:00:00.000Z"),
|
||||
updatedAt: new Date("2026-03-04T00:00:00.000Z"),
|
||||
} as const;
|
||||
|
||||
const text = buildInviteOnboardingTextDocument(req, "token-999", invite as any, {
|
||||
deploymentMode: "authenticated",
|
||||
deploymentExposure: "private",
|
||||
bindHost: "0.0.0.0",
|
||||
allowedHostnames: ["paperclip.example.test", "203.0.113.42"],
|
||||
});
|
||||
|
||||
expect(text).toContain("http://192.168.6.178:3103");
|
||||
expect(text).not.toContain("http://[fe80::1]:3103");
|
||||
} finally {
|
||||
networkSpy.mockRestore();
|
||||
}
|
||||
});
|
||||
});
|
||||
|
|
|
|||
|
|
@ -30,14 +30,14 @@ afterEach(() => {
|
|||
|
||||
describe("buildPaperclipEnv", () => {
|
||||
it("prefers an explicit PAPERCLIP_RUNTIME_API_URL", () => {
|
||||
process.env.PAPERCLIP_RUNTIME_API_URL = "http://100.104.161.29:3102";
|
||||
process.env.PAPERCLIP_RUNTIME_API_URL = "http://203.0.113.42:3102";
|
||||
process.env.PAPERCLIP_API_URL = "http://localhost:4100";
|
||||
process.env.PAPERCLIP_LISTEN_HOST = "127.0.0.1";
|
||||
process.env.PAPERCLIP_LISTEN_PORT = "3101";
|
||||
|
||||
const env = buildPaperclipEnv({ id: "agent-1", companyId: "company-1" });
|
||||
|
||||
expect(env.PAPERCLIP_API_URL).toBe("http://100.104.161.29:3102");
|
||||
expect(env.PAPERCLIP_API_URL).toBe("http://203.0.113.42:3102");
|
||||
});
|
||||
|
||||
it("falls back to PAPERCLIP_API_URL when no runtime URL is configured", () => {
|
||||
|
|
@ -52,6 +52,7 @@ describe("buildPaperclipEnv", () => {
|
|||
});
|
||||
|
||||
it("uses runtime listen host/port when explicit URL is not set", () => {
|
||||
delete process.env.PAPERCLIP_RUNTIME_API_URL;
|
||||
delete process.env.PAPERCLIP_API_URL;
|
||||
process.env.PAPERCLIP_LISTEN_HOST = "0.0.0.0";
|
||||
process.env.PAPERCLIP_LISTEN_PORT = "3101";
|
||||
|
|
@ -63,6 +64,7 @@ describe("buildPaperclipEnv", () => {
|
|||
});
|
||||
|
||||
it("formats IPv6 hosts safely in fallback URL generation", () => {
|
||||
delete process.env.PAPERCLIP_RUNTIME_API_URL;
|
||||
delete process.env.PAPERCLIP_API_URL;
|
||||
process.env.PAPERCLIP_LISTEN_HOST = "::1";
|
||||
process.env.PAPERCLIP_LISTEN_PORT = "3101";
|
||||
|
|
|
|||
|
|
@ -1,5 +1,9 @@
|
|||
import { describe, expect, it } from "vitest";
|
||||
import { buildRuntimeApiCandidateUrls, choosePrimaryRuntimeApiUrl } from "../runtime-api.js";
|
||||
import {
|
||||
buildRuntimeApiCandidateUrls,
|
||||
choosePrimaryRuntimeApiUrl,
|
||||
collectReachableInterfaceHosts,
|
||||
} from "../runtime-api.js";
|
||||
|
||||
describe("runtime API discovery", () => {
|
||||
it("prefers the explicit public base URL for the primary runtime URL", () => {
|
||||
|
|
@ -56,7 +60,23 @@ describe("runtime API discovery", () => {
|
|||
"http://198.51.100.10:3102",
|
||||
"http://runtime-host.example.test:3102",
|
||||
"http://203.0.113.42:3102",
|
||||
"http://[fe80::1]:3102",
|
||||
]);
|
||||
});
|
||||
|
||||
it("tries the preferred API URL before derived callback candidates", () => {
|
||||
expect(
|
||||
buildRuntimeApiCandidateUrls({
|
||||
preferredApiUrl: "https://agent-entry.example.test/base/path",
|
||||
authPublicBaseUrl: "https://paperclip.example.test/app",
|
||||
allowedHostnames: ["198.51.100.10"],
|
||||
bindHost: "0.0.0.0",
|
||||
port: 3102,
|
||||
networkInterfacesMap: {},
|
||||
}),
|
||||
).toEqual([
|
||||
"https://agent-entry.example.test",
|
||||
"https://paperclip.example.test",
|
||||
"https://198.51.100.10:3102",
|
||||
]);
|
||||
});
|
||||
|
||||
|
|
@ -74,4 +94,54 @@ describe("runtime API discovery", () => {
|
|||
"http://host.docker.internal:3102",
|
||||
]);
|
||||
});
|
||||
|
||||
it("prefers usable interface hosts and skips link-local addresses", () => {
|
||||
expect(
|
||||
collectReachableInterfaceHosts({
|
||||
networkInterfacesMap: {
|
||||
en0: [
|
||||
{
|
||||
address: "fe80::1",
|
||||
family: "IPv6",
|
||||
internal: false,
|
||||
netmask: "ffff:ffff:ffff:ffff::",
|
||||
cidr: "fe80::1/64",
|
||||
mac: "00:00:00:00:00:00",
|
||||
scopeid: 1,
|
||||
},
|
||||
{
|
||||
address: "192.168.6.178",
|
||||
family: "IPv4",
|
||||
internal: false,
|
||||
netmask: "255.255.252.0",
|
||||
cidr: "192.168.6.178/22",
|
||||
mac: "00:00:00:00:00:00",
|
||||
},
|
||||
{
|
||||
address: "fd7a:115c:a1e0::8a3a:a11d",
|
||||
family: "IPv6",
|
||||
internal: false,
|
||||
netmask: "ffff:ffff:ffff::",
|
||||
cidr: "fd7a:115c:a1e0::8a3a:a11d/48",
|
||||
mac: "00:00:00:00:00:00",
|
||||
scopeid: 0,
|
||||
},
|
||||
],
|
||||
en1: [
|
||||
{
|
||||
address: "169.254.10.20",
|
||||
family: "IPv4",
|
||||
internal: false,
|
||||
netmask: "255.255.0.0",
|
||||
cidr: "169.254.10.20/16",
|
||||
mac: "00:00:00:00:00:00",
|
||||
},
|
||||
],
|
||||
},
|
||||
}),
|
||||
).toEqual([
|
||||
"192.168.6.178",
|
||||
"fd7a:115c:a1e0::8a3a:a11d",
|
||||
]);
|
||||
});
|
||||
});
|
||||
|
|
|
|||
|
|
@ -1,4 +1,10 @@
|
|||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
const ORIGINAL_PAPERCLIP_API_URL = process.env.PAPERCLIP_API_URL;
|
||||
const ORIGINAL_PAPERCLIP_RUNTIME_API_URL = process.env.PAPERCLIP_RUNTIME_API_URL;
|
||||
const ORIGINAL_PAPERCLIP_RUNTIME_API_CANDIDATES_JSON = process.env.PAPERCLIP_RUNTIME_API_CANDIDATES_JSON;
|
||||
const ORIGINAL_PAPERCLIP_LISTEN_HOST = process.env.PAPERCLIP_LISTEN_HOST;
|
||||
const ORIGINAL_PAPERCLIP_LISTEN_PORT = process.env.PAPERCLIP_LISTEN_PORT;
|
||||
|
||||
const {
|
||||
createAppMock,
|
||||
|
|
@ -265,6 +271,26 @@ describe("startServer PAPERCLIP_API_URL handling", () => {
|
|||
delete process.env.PAPERCLIP_API_URL;
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
if (ORIGINAL_PAPERCLIP_API_URL === undefined) delete process.env.PAPERCLIP_API_URL;
|
||||
else process.env.PAPERCLIP_API_URL = ORIGINAL_PAPERCLIP_API_URL;
|
||||
|
||||
if (ORIGINAL_PAPERCLIP_RUNTIME_API_URL === undefined) delete process.env.PAPERCLIP_RUNTIME_API_URL;
|
||||
else process.env.PAPERCLIP_RUNTIME_API_URL = ORIGINAL_PAPERCLIP_RUNTIME_API_URL;
|
||||
|
||||
if (ORIGINAL_PAPERCLIP_RUNTIME_API_CANDIDATES_JSON === undefined) {
|
||||
delete process.env.PAPERCLIP_RUNTIME_API_CANDIDATES_JSON;
|
||||
} else {
|
||||
process.env.PAPERCLIP_RUNTIME_API_CANDIDATES_JSON = ORIGINAL_PAPERCLIP_RUNTIME_API_CANDIDATES_JSON;
|
||||
}
|
||||
|
||||
if (ORIGINAL_PAPERCLIP_LISTEN_HOST === undefined) delete process.env.PAPERCLIP_LISTEN_HOST;
|
||||
else process.env.PAPERCLIP_LISTEN_HOST = ORIGINAL_PAPERCLIP_LISTEN_HOST;
|
||||
|
||||
if (ORIGINAL_PAPERCLIP_LISTEN_PORT === undefined) delete process.env.PAPERCLIP_LISTEN_PORT;
|
||||
else process.env.PAPERCLIP_LISTEN_PORT = ORIGINAL_PAPERCLIP_LISTEN_PORT;
|
||||
});
|
||||
|
||||
it("uses the externally set PAPERCLIP_API_URL when provided", async () => {
|
||||
process.env.PAPERCLIP_API_URL = "http://custom-api:3100";
|
||||
|
||||
|
|
@ -272,6 +298,10 @@ describe("startServer PAPERCLIP_API_URL handling", () => {
|
|||
|
||||
expect(started.apiUrl).toBe("http://custom-api:3100");
|
||||
expect(process.env.PAPERCLIP_API_URL).toBe("http://custom-api:3100");
|
||||
expect(JSON.parse(process.env.PAPERCLIP_RUNTIME_API_CANDIDATES_JSON ?? "[]")).toEqual(
|
||||
expect.arrayContaining(["http://custom-api:3100"]),
|
||||
);
|
||||
expect(JSON.parse(process.env.PAPERCLIP_RUNTIME_API_CANDIDATES_JSON ?? "[]")[0]).toBe("http://custom-api:3100");
|
||||
});
|
||||
|
||||
it("falls back to host-based URL when PAPERCLIP_API_URL is not set", async () => {
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue