Skip to content
91 changes: 78 additions & 13 deletions apps/server/src/peer/PeerLinks.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@
import * as NodeFS from "node:fs";
// @effect-diagnostics-next-line nodeBuiltinImport:off - A peer with a certificate this machine does not trust.
import * as NodeHttps from "node:https";
import { NodeHttpServer } from "@effect/platform-node";
import { NodeHttpClient, NodeHttpServer } from "@effect/platform-node";
import * as Undici from "@effect/platform-node/Undici";
import { type ExecutionEnvironmentDescriptor, OrchestratorMcpFailure } from "@t3tools/contracts";
import { expect, it } from "@effect/vitest";
import * as Context from "effect/Context";
Expand Down Expand Up @@ -89,8 +90,9 @@ const serveB = (descriptor: ExecutionEnvironmentDescriptor) =>
const makeA = (
descriptor: ExecutionEnvironmentDescriptor,
secrets?: typeof ServerSecretStore.layer,
machine?: Layer.Layer<never>,
) =>
layerLinkingEnvironment(descriptor, secrets).pipe(
layerLinkingEnvironment(descriptor, secrets, undefined, machine).pipe(
Layer.build,
Effect.map((context) => ({
links: Context.get(context, PeerLinks.PeerLinks),
Expand Down Expand Up @@ -123,6 +125,18 @@ const serveApart = (descriptor: ExecutionEnvironmentDescriptor) =>
Effect.flatMap((server) => serveB(descriptor).pipe(Effect.provideContext(server))),
);

/** Connections to `host` reach 127.0.0.1 instead, as a LAN route would reach the peer. */
const layerRouteHostToLoopback = (host: string) => {
const connect = Undici.buildConnector({});
return NodeHttpClient.layerUndiciOptions({
connect: (options, callback) =>
connect(
{ ...options, hostname: options.hostname === host ? "127.0.0.1" : options.hostname },
callback,
),
});
};

it.effect("routes peer reads to readers and sees uncommitted link updates", () =>
Effect.gen(function* () {
const context = yield* layerLinkingEnvironment(
Expand Down Expand Up @@ -701,7 +715,7 @@ it.effect("tells the agent to link again once the peer revokes the link or it ex
);

it.effect(
"refuses to link itself, plain http off this machine and the tailnet, or a peer that cannot hold a linked agent to its limits",
"refuses to link itself, plain http that could leave the private network, or a peer that cannot hold a linked agent to its limits",
() =>
Effect.scoped(
Effect.gen(function* () {
Expand All @@ -721,24 +735,32 @@ it.effect(
.pipe(Effect.flip);
expect(unfenced.reason).toBe("incompatible");

// Plain http to a LAN address would carry the code and token in clear.
const lan = yield* a.links
// Plain http to a public address would carry the code and token in clear.
const exposed = yield* a.links
.link({
url: "http://192.168.1.20:3773",
url: "http://203.0.113.7:3773",
pairingCode: pairing.credential,
access: "auto",
})
.pipe(Effect.flip);
expect(lan.message).toContain("plain http");
const lanAlternate = yield* a.links
expect(exposed.message).toContain("plain http");
const exposedAlternate = yield* a.links
.link({
url: b.url,
alternateUrls: ["http://192.168.1.20:3773"],
alternateUrls: ["http://203.0.113.7:3773"],
pairingCode: pairing.credential,
access: "auto",
})
.pipe(Effect.flip);
expect(lanAlternate.message).toContain("plain http");
expect(exposedAlternate.message).toContain("plain http");
// So could a name, whatever it looks like: a search domain or unicast
// DNS can resolve it to a public address.
for (const url of ["http://box:3773", "http://box.local:3773"]) {
const named = yield* a.links
.link({ url, pairingCode: pairing.credential, access: "auto" })
.pipe(Effect.flip);
expect(named.message).toContain("plain http");
}

yield* Ref.set(b.descriptor, laptop);
const self = yield* a.links
Expand All @@ -751,6 +773,49 @@ it.effect(
).pipe(Effect.provide(NodeHttpServer.layerTest)),
);

it.effect(
"links over plain http on a private network, but never moves a link made over an encrypted address onto it",
() =>
Effect.scoped(
Effect.gen(function* () {
const b = yield* serveB(box);
const lan = `http://192.168.1.20:${new URL(b.url).port}`;
const a = yield* makeA(laptop, undefined, layerRouteHostToLoopback("192.168.1.20"));

// The address `t3 pair` prints for a server on a LAN.
const linked = yield* a.links.link({
url: lan,
pairingCode: (yield* b.auth.issuePairingCredential()).credential,
access: "auto",
});
expect(linked.urls).toEqual([lan]);
yield* probe(a);
expect((yield* Ref.get(b.bearers)).length).toBeGreaterThan(0);

// Linked through an address that encrypts, the token never falls back
// to the LAN one, whether the address was typed or the machine picked.
// An address alone never moves a link, so the typed one starts afresh.
yield* a.links.unlink(box.environmentId);
const typed = yield* a.links.link({
url: lan,
alternateUrls: [b.url],
pairingCode: (yield* b.auth.issuePairingCredential()).credential,
access: "auto",
});
expect(typed.urls).toEqual([b.url]);
const picked = yield* a.links.link({
url: lan,
alternateUrls: [b.url],
pairingCode: (yield* b.auth.issuePairingCredential()).credential,
access: "auto",
expectedEnvironmentId: box.environmentId,
});
expect(picked.urls).toEqual([b.url]);
expect((yield* a.links.resolve(box.environmentId)).url).toBe(b.url);
}),
).pipe(Effect.provide(NodeHttpServer.layerTest)),
);

it.effect(
"linking a picked machine skips an address that answers as another, and never signs in there",
() =>
Expand Down Expand Up @@ -809,7 +874,7 @@ it.effect("linking a picked machine that answers nowhere names it and links noth
const failed = yield* a.links
.link({
url: impostor.url,
alternateUrls: ["http://192.168.1.20:3773"],
alternateUrls: ["http://203.0.113.7:3773"],
pairingCode: "unused",
access: "auto",
expectedEnvironmentId: box.environmentId,
Expand All @@ -819,15 +884,15 @@ it.effect("linking a picked machine that answers nowhere names it and links noth
expect(failed.reason).toBe("unreachable");
expect(failed.answeredAs).toBe("Impostor");
expect(failed.message).toBe(
`This environment could not reach Box: ${new URL(impostor.url).origin} answered as another environment, Impostor. http://192.168.1.20:3773 is plain http, which would send the link's credentials unencrypted. Use its https address, or its Tailscale address.`,
`This environment could not reach Box: ${new URL(impostor.url).origin} answered as another environment, Impostor. http://203.0.113.7:3773 is plain http to an address that is not a private IP, so the link's credentials could travel unencrypted across the internet. Use its https address, its Tailscale address, or its IP address on your local network.`,
);
expect(yield* a.links.list).toEqual([]);
expect(yield* linkedSessions(impostor)).toEqual([]);

// Every address refused: the message says why.
const refused = yield* a.links
.link({
url: "http://192.168.1.20:3773",
url: "http://203.0.113.7:3773",
pairingCode: "unused",
access: "auto",
expectedEnvironmentId: box.environmentId,
Expand Down
5 changes: 4 additions & 1 deletion apps/server/src/peer/PeerLinks.testkit.ts
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,8 @@ export type ServedPeer = Effect.Success<ReturnType<typeof servePeer>>;

/**
* The environment that links: its own database and secret store, reaching
* peers over plain HTTP. Provide it to anything built on its links.
* peers over plain HTTP. Provide it to anything built on its links. `machine`
* replaces what this machine provides, such as its network.
*/
export const layerLinkingEnvironment = <E = never>(
descriptor: ExecutionEnvironmentDescriptor,
Expand All @@ -194,9 +195,11 @@ export const layerLinkingEnvironment = <E = never>(
SqlClient.SqlClient,
E | Layer.Error<typeof Sqlite.layerMemory>
> = Sqlite.layerMemory,
machine: Layer.Layer<never> = Layer.empty,
) =>
PeerMcpClient.layer.pipe(
Layer.provideMerge(PeerLinks.layer),
Layer.provide(machine),
Layer.provideMerge(ServerSettings.layerTest({ linkedEnvironmentsEnabled: true })),
Layer.provideMerge(database),
Layer.provide(Layer.mergeAll(secrets, FetchHttpClient.layer)),
Expand Down
45 changes: 31 additions & 14 deletions apps/server/src/peer/PeerLinks.ts
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ import { isLocalLoopbackHost, isTailnetHost } from "@t3tools/shared/hostClassifi
import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
import * as ServerSettings from "../serverSettings.ts";
import { isPrivateNetworkAddress } from "../startupAccess.ts";

const PeerHttpApi = HttpApi.make(EnvironmentHttpApi.identifier)
.add(EnvironmentHttpApi.groups.metadata)
Expand Down Expand Up @@ -159,10 +160,17 @@ const failStorage = (cause: unknown) =>
),
);

/** Whether credentials sent to `url` cross the network unencrypted. */
const sendsInClear = (url: string | URL) => {
const { protocol, hostname } = new URL(url);
return protocol === "http:" && !isLocalLoopbackHost(hostname) && !isTailnetHost(hostname);
};

/**
* The base URL a peer is reached at, normalised to its origin. The pairing
* code and then the link's token travel to it, so plain http is accepted only
* where the network already encrypts: this machine, or a Tailscale address.
* code and then the link's token travel to it, so plain http off this machine
* and the tailnet is accepted only to a private IP, as a LAN server pairs
* over. A name is refused: DNS could resolve it to a public address.
*/
const peerOrigin = (url: string) => {
const parsed = URL.parse(url);
Expand All @@ -175,21 +183,25 @@ const peerOrigin = (url: string) => {
}),
);
}
if (
parsed.protocol === "http:" &&
!isLocalLoopbackHost(parsed.hostname) &&
!isTailnetHost(parsed.hostname)
) {
if (sendsInClear(parsed) && !isPrivateNetworkAddress(parsed.hostname)) {
return Effect.fail(
new PeerLinkError({
reason: "unreachable",
message: `${parsed.origin} is plain http, which would send the link's credentials unencrypted. Use its https address, or its Tailscale address.`,
message: `${parsed.origin} is plain http to an address that is not a private IP, so the link's credentials could travel unencrypted across the internet. Use its https address, its Tailscale address, or its IP address on your local network.`,
}),
);
}
return Effect.succeed(parsed.origin);
};

/**
* The origins a link made over `primary` keeps. As with a paired client's
* token, a link's token goes over plain http only when the link was made over
* it, so one made over https, loopback or the tailnet never travels in clear.
*/
const keptOrigins = (primary: string, origins: ReadonlyArray<string>) =>
sendsInClear(primary) ? origins : origins.filter((origin) => !sendsInClear(origin));

/** The system error under a failed connection, such as ECONNREFUSED or ENOTFOUND. */
const connectionCode = (cause: unknown) =>
[cause, Predicate.hasProperty(cause, "cause") ? cause.cause : undefined]
Expand Down Expand Up @@ -437,9 +449,9 @@ const make = Effect.gen(function* () {

/**
* The addresses that answer as `environmentId`, in the order given, with
* what the first one answered. Addresses this environment would not send
* credentials to are skipped; when none answers as it, the failure says why
* for each.
* the one to link through and what it answered. Addresses this environment
* would not send credentials to are skipped; when none answers as it, the
* failure says why for each.
*/
const answeringAs = Effect.fn("PeerLinks.answeringAs")(function* (
urls: ReadonlyArray<string>,
Expand Down Expand Up @@ -473,7 +485,8 @@ const make = Effect.gen(function* () {
const matching = checked.flatMap((result) =>
Result.isSuccess(result) ? [result.success] : [],
);
const first = matching[0];
// Plain http is the fallback when no address that encrypts answers.
const first = matching.find((found) => !sendsInClear(found.origin)) ?? matching[0];
if (first === undefined) {
const failures = checked.flatMap((result) =>
Result.isFailure(result) ? [result.failure] : [],
Expand All @@ -486,15 +499,19 @@ const make = Effect.gen(function* () {
});
}
// Each address is kept once, even when two spellings share an origin.
const origins = [...new Set(matching.map((found) => found.origin))];
const origins = keptOrigins(first.origin, [...new Set(matching.map((found) => found.origin))]);
return { primary: first.origin, peer: first.descriptor, origins };
});

/** The peer at `url`, with every address checked for credentials first. */
const answeringAt = Effect.fn("PeerLinks.answeringAt")(function* (urls: ReadonlyArray<string>) {
const origins = yield* Effect.forEach(urls, peerOrigin);
const primary = origins[0]!;
return { primary, peer: yield* probe(primary), origins };
const peer = yield* probe(primary);
if (sendsInClear(primary) && origins.length > 1) {
return yield* answeringAs(origins, peer.environmentId, peer.label);
}
return { primary, peer, origins: keptOrigins(primary, origins) };
});

const linkWith = Effect.fn("PeerLinks.link")(function* (
Expand Down
5 changes: 5 additions & 0 deletions docs/user/remote-access.md
Original file line number Diff line number Diff line change
Expand Up @@ -469,6 +469,11 @@ an address you trust: the code is sent there.
- A link stays valid while agents use it. One unused for 30 days expires, as
does one to a machine on an older T3 Code after 30 days; link again with a
new pairing code.
- On a LAN or other private network, a link can use the machine's plain
`http://` IP address, as pairing does. A machine picked from the list is
linked over its https, Tailscale or T3 Connect address instead whenever one
answers. Plain http to a public address or to a hostname is refused, apart
from `localhost` and Tailscale (`.ts.net`) names.

An agent can also hand a task to a linked machine with `delegate_task`: it runs
there as an ordinary thread, in the project with the same repository (or the
Expand Down
Loading