Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

19.9 KB
Raw Blame
import * as Predicate from "effect/Predicate";
import * as NodeHttp from "node:http";
import * as NodeFS from "node:fs";
import * as NodeOS from "node:os";
import * as NodePath from "node:path";

import * as NodeServices from "@effect/platform-node/NodeServices";
import * as NetService from "@akeru/shared/Net";
import { assert, describe, expect, it } from "@effect/vitest";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Cause from "effect/Cause";
import * as Runtime from "effect/Runtime";
import * as Exit from "effect/Exit";
import * as TestConsole from "effect/testing/TestConsole";
import { Command } from "effect/unstable/cli";

import * as EnvironmentAuth from "../auth/EnvironmentAuth.ts";
import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
import { cli } from "../bin.ts";
import * as ServerConfig from "../config.ts";
import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
import { SqlitePersistenceMemory } from "../persistence/Layers/Sqlite.ts";
import {
  persistedServerRuntimeState,
  persistServerRuntimeState,
  type PersistedServerRuntimeState,
} from "../serverRuntimeState.ts";
import {
  AdminAlreadyPairedError,
  DevServerNotProxiableError,
  InvalidPublicUrlError,
  issueAdminPairingLink,
  PairStdoutIsTerminal,
  parsePublicPairingBaseUrl,
  resolveDirectPairingBaseUrl,
  resolveTailscaleLocalTarget,
} from "./pair.ts";

const CliRuntimeLayer = Layer.mergeAll(NodeServices.layer, NetService.layer);

const baseState = {
  version: 1,
  pid: 123,
  port: 3_773,
  origin: "http://127.0.0.1:3773",
  startedAt: "2026-06-20T00:00:00.000Z",
} as const satisfies PersistedServerRuntimeState;

describe("pair base URL selection", () => {
  it("pairs through the dev web origin when the server fronts a dev server", () => {
    expect(resolveDirectPairingBaseUrl({ ...baseState, devUrl: "http://localhost:5733/" })).toBe(
      "http://localhost:5733/",
    );
  });

  it("pairs through the bound host when there is no dev server", () => {
    expect(resolveDirectPairingBaseUrl({ ...baseState, host: "100.64.0.7" })).toBe(
      "http://100.64.0.7:3773",
    );
    expect(resolveDirectPairingBaseUrl(baseState)).toBe("http://localhost:3773");
  });
});

describe("pair public URL", () => {
  it("accepts an http or https origin", () => {
    expect(parsePublicPairingBaseUrl("https://akeru.example.com")).toBe(
      "https://akeru.example.com",
    );
    expect(parsePublicPairingBaseUrl("https://akeru.example.com:8443/")).toBe(
      "https://akeru.example.com:8443",
    );
    expect(parsePublicPairingBaseUrl("http://192.168.1.10:3773")).toBe("http://192.168.1.10:3773");
  });

  it("rejects anything that is not a bare http or https origin", () => {
    for (const raw of [
      "akeru.example.com",
      "ftp://akeru.example.com",
      "javascript:alert(1)",
      "https://user:[email protected]",
      "https://akeru.example.com/akeru",
      "https://akeru.example.com/?token=abc",
    ]) {
      expect(parsePublicPairingBaseUrl(raw)).toBeInstanceOf(InvalidPublicUrlError);
    }
  });
});

const InMemoryEnvironmentAuthLayer = EnvironmentAuth.layer.pipe(
  Layer.provide(SqlitePersistenceMemory),
  Layer.provide(ServerSecretStore.layer),
  Layer.provide(ServerEnvironment.identityLayer),
  Layer.provide(ServerConfig.layerTest(process.cwd(), { prefix: "t3-pair-admin-test-" })),
  Layer.provide(NodeServices.layer),
);

describe("pair admin link", () => {
  it.effect("is offered until a person pairs an admin client, then refused", () =>
    Effect.gen(function* () {
      const environmentAuth = yield* EnvironmentAuth.EnvironmentAuth;
      const noOverrides = { ttl: Option.none(), label: Option.none() };

      // CLI bearer sessions for bots and scripts do not close the admin bootstrap.
      yield* environmentAuth.issueSession({ label: "script" });
      const issued = yield* issueAdminPairingLink(noOverrides);
      expect(issued.scopes).toContain("access:write");

      yield* environmentAuth.exchangeBootstrapCredentialForAccessToken(
        issued.credential,
        undefined,
        { deviceType: "mobile" },
      );
      const refused = yield* issueAdminPairingLink(noOverrides).pipe(Effect.flip);

      expect(refused).toBeInstanceOf(AdminAlreadyPairedError);
    }).pipe(Effect.provide(InMemoryEnvironmentAuthLayer)),
  );
});

describe("first admin pairing", () => {
  it.effect("revokes admin links issued before it", () =>
    Effect.gen(function* () {
      const environmentAuth = yield* EnvironmentAuth.EnvironmentAuth;
      const noOverrides = { ttl: Option.none(), label: Option.none() };
      const first = yield* issueAdminPairingLink(noOverrides);
      const second = yield* issueAdminPairingLink(noOverrides);
      const startup = yield* environmentAuth.issueStartupPairingCredential();
      const standard = yield* environmentAuth.createPairingLink();

      yield* environmentAuth.exchangeBootstrapCredentialForAccessToken(
        first.credential,
        undefined,
        { deviceType: "mobile" },
      );

      for (const credential of [second.credential, startup.credential]) {
        const refused = yield* environmentAuth
          .exchangeBootstrapCredentialForAccessToken(credential, undefined, {
            deviceType: "mobile",
          })
          .pipe(Effect.flip);

        expect(refused._tag).toBe("ServerAuthInvalidCredentialError");
      }

      // Standard links for adding devices stay valid.
      yield* environmentAuth.exchangeBootstrapCredentialForAccessToken(
        standard.credential,
        undefined,
        { deviceType: "mobile" },
      );
    }).pipe(Effect.provide(InMemoryEnvironmentAuthLayer)),
  );
});

describe("pair tailscale local target", () => {
  it("proxies the dev web port for dev servers", () => {
    expect(resolveTailscaleLocalTarget({ ...baseState, devUrl: "http://localhost:5733/" })).toEqual(
      { localPort: 5_733 },
    );
    // A dev server on a non-loopback interface must be proxied at that
    // interface; tailscale serve defaults to 127.0.0.1 otherwise.
    expect(
      resolveTailscaleLocalTarget({ ...baseState, devUrl: "http://192.168.1.10:5733/" }),
    ).toEqual({ localPort: 5_733, localHost: "192.168.1.10" });
    // URL.hostname keeps IPv6 brackets, so the serve target stays valid.
    expect(
      resolveTailscaleLocalTarget({ ...baseState, devUrl: "http://[fd7a:115c::1]:5733/" }),
    ).toEqual({ localPort: 5_733, localHost: "[fd7a:115c::1]" });
  });

  it("rejects HTTPS dev URLs, which tailscale serve cannot proxy", () => {
    expect(
      resolveTailscaleLocalTarget({ ...baseState, devUrl: "https://localhost:5733/" }),
    ).toBeInstanceOf(DevServerNotProxiableError);
  });

  it("proxies the backend port directly otherwise", () => {
    expect(resolveTailscaleLocalTarget(baseState)).toEqual({ localPort: 3_773 });
    expect(resolveTailscaleLocalTarget({ ...baseState, host: "0.0.0.0" })).toEqual({
      localPort: 3_773,
    });
    expect(resolveTailscaleLocalTarget({ ...baseState, host: "192.168.1.42" })).toEqual({
      localPort: 3_773,
      localHost: "192.168.1.42",
    });
  });
});

const runCli = (args: ReadonlyArray<string>) => Command.runWith(cli, { version: "0.0.0" })(args);

const runCliCaptured = (args: ReadonlyArray<string>) =>
  provideCliTestLayers(
    Effect.gen(function* () {
      const exit = yield* Effect.exit(runCli(args));

      const errorLines = (yield* TestConsole.errorLines).filter((line): line is string =>
        Predicate.isString(line),
      );

      return { exit, errorLines };
    }),
  );

const provideCliTestLayers = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
  Effect.provide(effect, Layer.mergeAll(CliRuntimeLayer, TestConsole.layer));

// Console output accumulates across CLI runs within a test, and each
// Console.log call is one entry — so the latest command's output is the last
// entry, even when it spans many lines.
const captureStdout = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
  provideCliTestLayers(
    Effect.gen(function* () {
      yield* effect;

      return (
        (yield* TestConsole.logLines).findLast((line): line is string =>
          Predicate.isString(line),
        ) ?? ""
      );
    }),
  );

const testDescriptor = {
  environmentId: "pair-test-environment",
  label: "pair-test",
  platform: { os: "linux", arch: "x64" },
  serverVersion: "0.0.1",
  capabilities: { repositoryIdentity: true },
};

const withDescriptorServer = <A, E, R>(run: (origin: string) => Effect.Effect<A, E, R>) =>
  Effect.acquireUseRelease(
    Effect.callback<NodeHttp.Server>((resume) => {
      const server = NodeHttp.createServer((request, response) => {
        if (request.url === "/.well-known/t3/environment") {
          response.writeHead(200, { "content-type": "application/json" });
          response.end(JSON.stringify(testDescriptor));

          return;
        }

        response.writeHead(404);
        response.end();
      });

      server.listen(0, "127.0.0.1", () => resume(Effect.succeed(server)));
    }),
    (server) => {
      const address = server.address();

      if (address === null || Predicate.isString(address)) {
        return Effect.die(new Error("Expected a TCP address"));
      }

      return run(`http://127.0.0.1:${String(address.port)}`);
    },
    (server) => Effect.sync(() => server.close()),
  );

describe("akeru pair", () => {
  it.effect("mints a token and prints a QR pairing URL for a live server", () =>
    withDescriptorServer((origin) =>
      Effect.gen(function* () {
        const baseDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-pair-test-"));
        const port = Number(new URL(origin).port);
        const statePath = NodePath.join(baseDir, "userdata", "server-runtime.json");
        yield* persistServerRuntimeState({
          path: statePath,
          state: yield* persistedServerRuntimeState({
            config: { host: "127.0.0.1", devUrl: undefined },
            port,
          }),
        });

        const output = yield* captureStdout(runCli(["pair", "--base-dir", baseDir])).pipe(
          Effect.provideService(PairStdoutIsTerminal, true),
        );

        assert.include(output, `Pairing with pair-test (${origin})`);
        assert.include(output, `Pairing URL: ${origin}/pair#token=`);
        assert.isTrue(output.includes("█") || output.includes("▀") || output.includes("▄"));
        // Loopback origins are not reachable from a phone; the output must say so.
        assert.include(output, "only reachable from this machine");

        const token = /#token=([A-Z2-9]+)/.exec(output)?.[1];
        assert.isString(token);

        // The token must be in the same store the running server reads.
        const listed = yield* captureStdout(
          runCli(["auth", "pairing", "list", "--base-dir", baseDir, "--json"]),
        );

        const credentials = JSON.parse(listed) as ReadonlyArray<{ readonly label?: string }>;
        assert.equal(credentials.length, 1);
        assert.equal(credentials[0]?.label, "akeru pair");
      }),
    ).pipe(Effect.provide(NodeServices.layer)),
  );

  it.effect("prints the QR code only on a terminal and never with --no-qr", () =>
    withDescriptorServer((origin) =>
      Effect.gen(function* () {
        const baseDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-pair-qr-test-"));
        yield* persistServerRuntimeState({
          path: NodePath.join(baseDir, "userdata", "server-runtime.json"),
          state: yield* persistedServerRuntimeState({
            config: { host: "127.0.0.1", devUrl: undefined },
            port: Number(new URL(origin).port),
          }),
        });
        const hasQrCode = (output: string) => /[█▀▄]/.test(output);

        const onTerminal = yield* captureStdout(runCli(["pair", "--base-dir", baseDir])).pipe(
          Effect.provideService(PairStdoutIsTerminal, true),
        );

        const optedOut = yield* captureStdout(
          runCli(["pair", "--base-dir", baseDir, "--no-qr"]),
        ).pipe(Effect.provideService(PairStdoutIsTerminal, true));

        const piped = yield* captureStdout(runCli(["pair", "--base-dir", baseDir])).pipe(
          Effect.provideService(PairStdoutIsTerminal, false),
        );

        assert.isTrue(hasQrCode(onTerminal));

        for (const output of [optedOut, piped]) {
          assert.isFalse(hasQrCode(output));
          // The full URL with its token is always printed, QR code or not.
          assert.match(output, /Pairing URL: http:\/\/127\.0\.0\.1:\d+\/pair#token=[A-Z2-9]+/);
        }
      }),
    ).pipe(Effect.provide(NodeServices.layer)),
  );

  it.effect("builds the pairing URL on --public-url for a loopback server behind a tunnel", () =>
    withDescriptorServer((origin) =>
      Effect.gen(function* () {
        const baseDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-pair-public-test-"));
        yield* persistServerRuntimeState({
          path: NodePath.join(baseDir, "userdata", "server-runtime.json"),
          state: yield* persistedServerRuntimeState({
            config: { host: "127.0.0.1", devUrl: undefined },
            port: Number(new URL(origin).port),
          }),
        });

        const output = yield* captureStdout(
          runCli(["pair", "--base-dir", baseDir, "--public-url", "https://akeru.example.com"]),
        );

        assert.match(output, /Pairing URL: https:\/\/akeru\.example\.com\/pair#token=[A-Z2-9]+/);
        assert.notInclude(output, "only reachable from this machine");
      }),
    ).pipe(Effect.provide(NodeServices.layer)),
  );

  it.effect("refuses a non-http --public-url and --public-url with --tailscale", () =>
    Effect.gen(function* () {
      const baseDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-pair-public-bad-"));

      const badScheme = yield* runCliCaptured([
        "pair",
        "--base-dir",
        baseDir,
        "--public-url",
        "ftp://example.com",
      ]);

      const both = yield* runCliCaptured([
        "pair",
        "--base-dir",
        baseDir,
        "--public-url",
        "https://example.com",
        "--tailscale",
      ]);

      for (const { exit, errorLines } of [badScheme, both]) {
        if (!Exit.isFailure(exit)) assert.fail("expected the command to fail");
        assert.equal(exit.cause.reasons.filter(Cause.isFailReason).length, 1);
        assert.isFalse(Runtime.getErrorReported(Cause.squash(exit.cause)));
        assert.isAbove(errorLines.length, 0);
      }

      assert.include(badScheme.errorLines.at(-1) ?? "", "must use http or https");
      assert.include(both.errorLines.at(-1) ?? "", "not both");
    }).pipe(Effect.provide(NodeServices.layer)),
  );

  it.effect("mints an admin-scope link with --admin and says so", () =>
    withDescriptorServer((origin) =>
      Effect.gen(function* () {
        const baseDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-pair-admin-cli-"));
        yield* persistServerRuntimeState({
          path: NodePath.join(baseDir, "userdata", "server-runtime.json"),
          state: yield* persistedServerRuntimeState({
            config: { host: "127.0.0.1", devUrl: undefined },
            port: Number(new URL(origin).port),
          }),
        });

        const output = yield* captureStdout(runCli(["pair", "--base-dir", baseDir, "--admin"]));

        const listed = yield* captureStdout(
          runCli(["auth", "pairing", "list", "--base-dir", baseDir, "--json"]),
        );

        assert.include(output, "grants admin scope");
        assert.match(output, /Pairing URL: http:\/\/127\.0\.0\.1:\d+\/pair#token=[A-Z2-9]+/);

        const credentials = JSON.parse(listed) as ReadonlyArray<{
          readonly label?: string;
          readonly scopes: ReadonlyArray<string>;
        }>;

        assert.equal(credentials.length, 1);
        assert.equal(credentials[0]?.label, "akeru pair --admin");
        assert.include(credentials[0]?.scopes ?? [], "access:write");
      }),
    ).pipe(Effect.provide(NodeServices.layer)),
  );

  it.effect("pairs through the recorded dev web URL for dev servers", () =>
    withDescriptorServer((origin) =>
      Effect.gen(function* () {
        const baseDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-pair-dev-test-"));
        const port = Number(new URL(origin).port);
        const statePath = NodePath.join(baseDir, "dev", "server-runtime.json");
        yield* persistServerRuntimeState({
          path: statePath,
          state: yield* persistedServerRuntimeState({
            config: { host: undefined, devUrl: new URL("http://localhost:5733") },
            port,
          }),
        });

        const output = yield* captureStdout(runCli(["pair", "--base-dir", baseDir]));

        assert.include(output, "Pairing URL: http://localhost:5733/pair#token=");
      }),
    ).pipe(Effect.provide(NodeServices.layer)),
  );

  it.effect("directs to akeru serve when no server is running", () =>
    Effect.gen(function* () {
      const baseDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-pair-none-test-"));

      const { exit, errorLines } = yield* runCliCaptured(["pair", "--base-dir", baseDir]);

      if (!Exit.isFailure(exit)) assert.fail("expected the command to fail");
      assert.equal(exit.cause.reasons.filter(Cause.isFailReason).length, 1);
      assert.isFalse(Runtime.getErrorReported(Cause.squash(exit.cause)));
      const rendered = errorLines.at(-1) ?? "";
      assert.include(rendered, "No running Akeru Bot server found.");
      assert.include(rendered, "npx akeru-bot serve");
    }).pipe(Effect.provide(NodeServices.layer)),
  );

  it.effect("ignores runtime state whose recorded pid is no longer alive", () =>
    withDescriptorServer((origin) =>
      Effect.gen(function* () {
        const baseDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-pair-pid-test-"));
        const statePath = NodePath.join(baseDir, "userdata", "server-runtime.json");

        // The origin answers (another server reused the port), but the pid
        // that wrote this state file is dead — pairing must not mint a token
        // into the dead server's database.
        const state = yield* persistedServerRuntimeState({
          config: { host: "127.0.0.1", devUrl: undefined },
          port: Number(new URL(origin).port),
        });

        yield* persistServerRuntimeState({
          path: statePath,
          // pid 2**22 + 1 exceeds any default Linux/macOS pid range.
          state: { ...state, pid: 4_194_305 },
        });

        const { exit, errorLines } = yield* runCliCaptured(["pair", "--base-dir", baseDir]);

        if (!Exit.isFailure(exit)) assert.fail("expected the command to fail");
        assert.isFalse(Runtime.getErrorReported(Cause.squash(exit.cause)));
        assert.isAbove(errorLines.length, 0);
        // Expected errors print their message only; stack frames belong to defects.
        const rendered = errorLines.at(-1) ?? "";
        assert.include(rendered, "No running Akeru Bot server found.");
        assert.notMatch(rendered, /\n\s+at /);
      }),
    ).pipe(Effect.provide(NodeServices.layer)),
  );

  it.effect("ignores stale runtime state pointing at a dead server", () =>
    Effect.gen(function* () {
      const baseDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-pair-stale-test-"));
      const statePath = NodePath.join(baseDir, "userdata", "server-runtime.json");
      // A port from the dynamic range with nothing listening: the probe fails
      // fast with ECONNREFUSED and discovery moves on.
      yield* persistServerRuntimeState({
        path: statePath,
        state: yield* persistedServerRuntimeState({
          config: { host: "127.0.0.1", devUrl: undefined },
          port: 1,
        }),
      });

      const error = yield* provideCliTestLayers(
        runCli(["pair", "--base-dir", baseDir]).pipe(Effect.flip),
      );

      assert.isFalse(Runtime.getErrorReported(error));

      const rendered = String(
        Predicate.isObjectOrArray(error) && "cause" in error ? error.cause : error,
      );

      assert.include(rendered, "No running Akeru Bot server found.");
    }).pipe(Effect.provide(NodeServices.layer)),
  );
});