feat: authenticated remote Intercom gateway

broker/access-credential.test.ts

@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import test from "node:test";
+import { ACCESS_CREDENTIAL_ENV, loadRemoteAccessCredential, writeRemoteSessionCredential } from "./access-credential.ts";
+
+function withTempFile(content: unknown, run: (path: string) => void): void {
+  const root = mkdtempSync(join(tmpdir(), "agent-intercom-credential-"));
+  const path = join(root, "credential.json");
+  writeFileSync(path, JSON.stringify(content), { mode: 0o600 });
+  try {
+    run(path);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+test("loads a private one-use enrollment credential from the configured path", () => {
+  withTempFile({ enrollmentToken: "one-use-secret" }, (path) => {
+    assert.deepEqual(loadRemoteAccessCredential({ [ACCESS_CREDENTIAL_ENV]: path }), {
+      path,
+      access: { enrollmentToken: "one-use-secret" },
+      enrollment: true,
+    });
+  });
+});
+
+test("atomically replaces enrollment material with assigned reconnect state", () => {
+  withTempFile({ enrollmentToken: "one-use-secret" }, (path) => {
+    writeRemoteSessionCredential(path, "assigned-session", {
+      origin: "remote",
+      remoteHostId: "ika-dev-v3",
+      parentSessionId: "local-root",
+      rootSessionId: "local-root",
+      generation: 1,
+      canDelegate: false,
+      depth: 1,
+      maxDepth: 1,
+      maxChildren: 0,
+      sessionCredential: "reconnect-secret",
+    });
+    assert.deepEqual(JSON.parse(readFileSync(path, "utf8")), {
+      version: 1,
+      sessionCredential: "reconnect-secret",
+      sessionId: "assigned-session",
+      generation: 1,
+    });
+    assert.equal(statSync(path).mode & 0o777, 0o600);
+    assert.deepEqual(loadRemoteAccessCredential({ [ACCESS_CREDENTIAL_ENV]: path })?.access, {
+      sessionCredential: "reconnect-secret",
+      sessionId: "assigned-session",
+      generation: 1,
+    });
+  });
+});
+
+test("credential parsing fails closed", () => {
+  withTempFile({ sessionCredential: "secret", sessionId: "id", generation: 1 }, (path) => {
+    assert.throws(() => loadRemoteAccessCredential({ [ACCESS_CREDENTIAL_ENV]: path }), /Invalid Agent Intercom access credential/);
+  });
+});

broker/access-credential.ts

@@ -0,0 +1,76 @@
+import { readFileSync } from "fs";
+import { writeDurableJson } from "../durable-json.ts";
+import type { RemoteAccessMetadata, RemoteRegistrationAccess } from "../types.ts";
+
+export const ACCESS_CREDENTIAL_ENV = "AGENT_INTERCOM_ACCESS_CREDENTIAL_PATH";
+export const ACCESS_CREDENTIAL_VERSION = 1;
+
+export interface EnrollmentCredentialFile {
+  version?: typeof ACCESS_CREDENTIAL_VERSION;
+  enrollmentToken: string;
+}
+
+export interface SessionCredentialFile {
+  version: typeof ACCESS_CREDENTIAL_VERSION;
+  sessionCredential: string;
+  sessionId: string;
+  generation: number;
+}
+
+export interface LoadedRemoteAccessCredential {
+  path: string;
+  access: RemoteRegistrationAccess;
+  enrollment: boolean;
+}
+
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && !value.includes("\0");
+}
+
+export function loadRemoteAccessCredential(env: NodeJS.ProcessEnv = process.env): LoadedRemoteAccessCredential | undefined {
+  const path = env[ACCESS_CREDENTIAL_ENV]?.trim();
+  if (!path) return undefined;
+  const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`Invalid Agent Intercom access credential at ${path}`);
+  }
+  const credential = parsed as Record<string, unknown>;
+  if (nonEmptyString(credential.enrollmentToken)) {
+    return { path, access: { enrollmentToken: credential.enrollmentToken }, enrollment: true };
+  }
+  if (
+    credential.version === ACCESS_CREDENTIAL_VERSION
+    && nonEmptyString(credential.sessionCredential)
+    && nonEmptyString(credential.sessionId)
+    && typeof credential.generation === "number"
+    && Number.isSafeInteger(credential.generation)
+    && credential.generation > 0
+  ) {
+    return {
+      path,
+      access: {
+        sessionCredential: credential.sessionCredential,
+        sessionId: credential.sessionId,
+        generation: credential.generation,
+      },
+      enrollment: false,
+    };
+  }
+  throw new Error(`Invalid Agent Intercom access credential at ${path}`);
+}
+
+export function writeRemoteSessionCredential(
+  path: string,
+  sessionId: string,
+  metadata: RemoteAccessMetadata,
+): void {
+  if (!metadata.sessionCredential) {
+    throw new Error("Remote enrollment response omitted the session credential");
+  }
+  writeDurableJson(path, {
+    version: ACCESS_CREDENTIAL_VERSION,
+    sessionCredential: metadata.sessionCredential,
+    sessionId,
+    generation: metadata.generation,
+  } satisfies SessionCredentialFile);
+}