fix: require auth for non-loopback remote daemons (#369)

* fix: require auth for non-loopback remote daemons

* fix: allow mapped loopback remote daemons

* refactor: use net blocklist for loopback checks

Author: thymikee

skills/agent-device/references/remote-tenancy.md

@@ -9,9 +9,6 @@ Open this file for remote daemon HTTP flows, including `--remote-config` launche
 - `agent-device open <app> --remote-config <path> --relaunch`
 - `AGENT_DEVICE_DAEMON_BASE_URL=...`
 - `AGENT_DEVICE_DAEMON_AUTH_TOKEN=...`
-- `curl ... agent_device.lease.allocate`
-- `curl ... agent_device.lease.heartbeat`
-- `curl ... agent_device.lease.release`
 - `agent-device --tenant ... --session-isolation tenant --run-id ... --lease-id ...`
 
 ## Most common mistake to avoid
@@ -33,14 +30,9 @@ agent-device open com.example.myapp --remote-config ./agent-device.remote.json -
 ## Lease flow example
 
 ```bash
-export AGENT_DEVICE_DAEMON_BASE_URL=http://mac-host.example:4310
+export AGENT_DEVICE_DAEMON_BASE_URL=<trusted-daemon-base-url>
 export AGENT_DEVICE_DAEMON_AUTH_TOKEN=<token>
 
-curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
-  -H "content-type: application/json" \
-  -H "Authorization: Bearer <token>" \
-  -d '{"jsonrpc":"2.0","id":"alloc-1","method":"agent_device.lease.allocate","params":{"tenantId":"acme","runId":"run-123","ttlMs":60000}}'
-
 agent-device \
   --tenant acme \
   --session-isolation tenant \
@@ -49,34 +41,20 @@ agent-device \
   session list --json
 ```
 
-Heartbeat and release example:
+Low-level lease operations exist for host-side automation, but do not point them at arbitrary hosts. The remote daemon executes device-control commands, so only use a trusted daemon base URL and an auth token managed by the same operator boundary.
 
-```bash
-curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
-  -H "content-type: application/json" \
-  -H "Authorization: Bearer <token>" \
-  -d '{"jsonrpc":"2.0","id":"hb-1","method":"agent_device.lease.heartbeat","params":{"leaseId":"<lease-id>","ttlMs":60000}}'
-
-curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
-  -H "content-type: application/json" \
-  -H "Authorization: Bearer <token>" \
-  -d '{"jsonrpc":"2.0","id":"rel-1","method":"agent_device.lease.release","params":{"leaseId":"<lease-id>"}}'
-```
+Lease lifecycle methods exposed by the daemon:
 
-Session-locked RPC command example:
-
-```bash
-curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
-  -H "content-type: application/json" \
-  -H "Authorization: Bearer <token>" \
-  -d '{"jsonrpc":"2.0","id":"cmd-1","method":"agent_device.command","params":{"session":"qa-ios","command":"snapshot","positionals":[],"meta":{"lockPolicy":"reject","lockPlatform":"ios","tenantId":"acme","runId":"run-123","leaseId":"<lease-id>"}}}'
-```
+- `agent_device.lease.allocate`
+- `agent_device.lease.heartbeat`
+- `agent_device.lease.release`
+- `agent_device.command`
 
 ## Transport prerequisites
 
 - Start the daemon in HTTP mode with `AGENT_DEVICE_DAEMON_SERVER_MODE=http|dual`.
 - Point the client at the remote host with `AGENT_DEVICE_DAEMON_BASE_URL=http(s)://host:port[/base-path]`.
-- Use `AGENT_DEVICE_DAEMON_AUTH_TOKEN` or `--daemon-auth-token` when the client should send the shared daemon token automatically.
+- For non-loopback remote hosts, set `AGENT_DEVICE_DAEMON_AUTH_TOKEN` or `--daemon-auth-token`. The client rejects non-loopback remote daemon URLs without auth.
 - Direct JSON-RPC callers can authenticate with request params, `Authorization: Bearer <token>`, or `x-agent-device-token`.
 - Prefer an auth hook such as `AGENT_DEVICE_HTTP_AUTH_HOOK` when the host needs caller validation or tenant injection.
 
@@ -117,4 +95,5 @@ The CLI sends `AGENT_DEVICE_DAEMON_AUTH_TOKEN` in both the JSON-RPC request toke
 - Missing tenant, run, or lease fields in tenant-isolation mode should fail as `INVALID_ARGS`.
 - Inactive or scope-mismatched leases should fail as `UNAUTHORIZED`.
 - Inspect logs on the remote host during remote debugging. Client-side `--debug` does not tail a local daemon log once `AGENT_DEVICE_DAEMON_BASE_URL` is set.
+- Do not point `AGENT_DEVICE_DAEMON_BASE_URL` at untrusted hosts. Remote daemon requests can launch apps and execute interaction commands.
 - Treat daemon auth tokens and lease identifiers as sensitive operational data.

src/__tests__/cli-diagnostics.test.ts

@@ -94,7 +94,9 @@ test('cli does not tail local daemon log when remote daemon base URL is set', as
   fs.writeFileSync(daemonPaths.logPath, 'REMOTE_TAIL_SENTINEL\n', 'utf8');
 
   const previousBaseUrl = process.env.AGENT_DEVICE_DAEMON_BASE_URL;
+  const previousAuthToken = process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN;
   process.env.AGENT_DEVICE_DAEMON_BASE_URL = 'http://remote-mac.example.test:7777/agent-device';
+  process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN = 'remote-secret';
 
   try {
     const result = await runCliCapture(
@@ -113,6 +115,8 @@ test('cli does not tail local daemon log when remote daemon base URL is set', as
   } finally {
     if (previousBaseUrl === undefined) delete process.env.AGENT_DEVICE_DAEMON_BASE_URL;
     else process.env.AGENT_DEVICE_DAEMON_BASE_URL = previousBaseUrl;
+    if (previousAuthToken === undefined) delete process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN;
+    else process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN = previousAuthToken;
     fs.rmSync(stateDir, { recursive: true, force: true });
   }
 });

src/daemon-client.ts

@@ -91,6 +91,10 @@ const IOS_RUNNER_XCODEBUILD_KILL_PATTERNS = [
   'xcodebuild .*AgentDeviceRunner\\.env\\.session-',
   'xcodebuild build-for-testing .*ios-runner/AgentDeviceRunner/AgentDeviceRunner\\.xcodeproj',
 ];
+const LOOPBACK_BLOCK_LIST = new net.BlockList();
+LOOPBACK_BLOCK_LIST.addSubnet('127.0.0.0', 8, 'ipv4');
+LOOPBACK_BLOCK_LIST.addAddress('::1', 'ipv6');
+LOOPBACK_BLOCK_LIST.addSubnet('::ffff:127.0.0.0', 104, 'ipv6');
 
 export async function sendToDaemon(req: Omit<DaemonRequest, 'token'>): Promise<DaemonResponse> {
   const requestId = req.meta?.requestId ?? createRequestId();
@@ -394,6 +398,7 @@ function resolveClientSettings(req: Omit<DaemonRequest, 'token'>): DaemonClientS
     req.flags?.daemonBaseUrl ?? process.env.AGENT_DEVICE_DAEMON_BASE_URL,
   );
   const remoteAuthToken = req.flags?.daemonAuthToken ?? process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN;
+  validateRemoteDaemonTrust(remoteBaseUrl, remoteAuthToken);
   const rawTransport = req.flags?.daemonTransport ?? process.env.AGENT_DEVICE_DAEMON_TRANSPORT;
   const transportPreference = resolveDaemonTransportPreference(rawTransport);
   if (remoteBaseUrl && transportPreference === 'socket') {
@@ -1113,6 +1118,35 @@ function resolveRemoteDaemonBaseUrl(raw: string | undefined): string | undefined
   return parsed.toString().replace(/\/+$/, '');
 }
 
+function validateRemoteDaemonTrust(
+  remoteBaseUrl: string | undefined,
+  remoteAuthToken: string | undefined,
+): void {
+  if (!remoteBaseUrl) return;
+  const hostname = new URL(remoteBaseUrl).hostname;
+  if (isLoopbackHostname(hostname)) return;
+  if (typeof remoteAuthToken === 'string' && remoteAuthToken.trim().length > 0) return;
+  throw new AppError(
+    'INVALID_ARGS',
+    'Remote daemon base URL for non-loopback hosts requires daemon authentication',
+    {
+      daemonBaseUrl: remoteBaseUrl,
+      hint: 'Provide --daemon-auth-token or AGENT_DEVICE_DAEMON_AUTH_TOKEN when using a non-loopback remote daemon URL.',
+    },
+  );
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  const normalized = hostname
+    .trim()
+    .toLowerCase()
+    .replace(/^\[(.*)\]$/, '$1');
+  if (normalized === 'localhost') return true;
+  if (net.isIPv4(normalized)) return LOOPBACK_BLOCK_LIST.check(normalized, 'ipv4');
+  if (net.isIPv6(normalized)) return LOOPBACK_BLOCK_LIST.check(normalized, 'ipv6');
+  return false;
+}
+
 function buildDaemonHttpUrl(baseUrl: string, route: 'health' | 'rpc'): string {
   // URL(base, relative) treats a base without trailing slash as a file path, so normalize to a directory-like base.
   const normalizedBase = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;

src/utils/__tests__/daemon-client.test.ts

@@ -344,6 +344,58 @@ test('sendToDaemon rejects socket transport when remote daemon base URL is set',
   }
 });
 
+test('sendToDaemon treats IPv4-mapped loopback remote daemon URLs as local', async () => {
+  const previousBaseUrl = process.env.AGENT_DEVICE_DAEMON_BASE_URL;
+  const previousAuthToken = process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN;
+  process.env.AGENT_DEVICE_DAEMON_BASE_URL = 'http://[::ffff:127.0.0.1]:4310/agent-device';
+  delete process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN;
+
+  try {
+    await assert.rejects(
+      async () =>
+        await sendToDaemon({
+          session: 'default',
+          command: 'remote-smoke',
+          positionals: [],
+          flags: { daemonTransport: 'socket' },
+          meta: { requestId: 'req-remote-mapped-loopback' },
+        }),
+      /only supports HTTP transport/,
+    );
+  } finally {
+    if (previousBaseUrl === undefined) delete process.env.AGENT_DEVICE_DAEMON_BASE_URL;
+    else process.env.AGENT_DEVICE_DAEMON_BASE_URL = previousBaseUrl;
+    if (previousAuthToken === undefined) delete process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN;
+    else process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN = previousAuthToken;
+  }
+});
+
+test('sendToDaemon requires auth for non-loopback remote daemon URLs', async () => {
+  const previousBaseUrl = process.env.AGENT_DEVICE_DAEMON_BASE_URL;
+  const previousAuthToken = process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN;
+  process.env.AGENT_DEVICE_DAEMON_BASE_URL = 'https://remote-mac.example.test/agent-device';
+  delete process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN;
+
+  try {
+    await assert.rejects(
+      async () =>
+        await sendToDaemon({
+          session: 'default',
+          command: 'remote-smoke',
+          positionals: [],
+          flags: {},
+          meta: { requestId: 'req-remote-auth' },
+        }),
+      /requires daemon authentication/,
+    );
+  } finally {
+    if (previousBaseUrl === undefined) delete process.env.AGENT_DEVICE_DAEMON_BASE_URL;
+    else process.env.AGENT_DEVICE_DAEMON_BASE_URL = previousBaseUrl;
+    if (previousAuthToken === undefined) delete process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN;
+    else process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN = previousAuthToken;
+  }
+});
+
 test('sendToDaemon uploads local install artifacts for remote daemons and passes upload id to RPC', async () => {
   const seenPaths: string[] = [];
   let uploadBodySize = 0;
@@ -553,7 +605,9 @@ test('sendToDaemon preserves explicit remote install paths without uploading', a
   }) as typeof http.request;
 
   const previousBaseUrl = process.env.AGENT_DEVICE_DAEMON_BASE_URL;
+  const previousAuthToken = process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN;
   process.env.AGENT_DEVICE_DAEMON_BASE_URL = 'http://remote-mac.example.test:7777/agent-device';
+  process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN = 'remote-secret';
 
   try {
     const response = await sendToDaemon({
@@ -572,6 +626,8 @@ test('sendToDaemon preserves explicit remote install paths without uploading', a
     (http as unknown as { request: typeof http.request }).request = originalHttpRequest;
     if (previousBaseUrl === undefined) delete process.env.AGENT_DEVICE_DAEMON_BASE_URL;
     else process.env.AGENT_DEVICE_DAEMON_BASE_URL = previousBaseUrl;
+    if (previousAuthToken === undefined) delete process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN;
+    else process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN = previousAuthToken;
   }
 });
 
@@ -630,7 +686,9 @@ test('sendToDaemon preserves install_source payload metadata for remote HTTP RPC
   }) as typeof http.request;
 
   const previousBaseUrl = process.env.AGENT_DEVICE_DAEMON_BASE_URL;
+  const previousAuthToken = process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN;
   process.env.AGENT_DEVICE_DAEMON_BASE_URL = 'http://remote-mac.example.test:7777/agent-device';
+  process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN = 'remote-secret';
 
   try {
     const response = await sendToDaemon({
@@ -663,6 +721,8 @@ test('sendToDaemon preserves install_source payload metadata for remote HTTP RPC
     (http as unknown as { request: typeof http.request }).request = originalHttpRequest;
     if (previousBaseUrl === undefined) delete process.env.AGENT_DEVICE_DAEMON_BASE_URL;
     else process.env.AGENT_DEVICE_DAEMON_BASE_URL = previousBaseUrl;
+    if (previousAuthToken === undefined) delete process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN;
+    else process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN = previousAuthToken;
   }
 });
 

website/docs/docs/commands.md

@@ -53,7 +53,7 @@ agent-device app-switcher
 - In `batch`, steps that omit `platform` still inherit the parent batch `--platform`; lock-mode defaults do not override that parent setting.
 - Tenant-scoped daemon runs can pass `--tenant`, `--session-isolation tenant`, `--run-id`, and `--lease-id` to enforce lease admission.
 - Remote daemon clients can pass `--daemon-base-url http(s)://host:port[/base-path]` to skip local daemon discovery/startup and call a remote HTTP daemon directly.
-- Use `--daemon-auth-token <token>` (or `AGENT_DEVICE_DAEMON_AUTH_TOKEN`) when the remote daemon expects the shared daemon token over HTTP; the client sends it in both the JSON-RPC request token and HTTP auth headers.
+- Use `--daemon-auth-token <token>` (or `AGENT_DEVICE_DAEMON_AUTH_TOKEN`) for non-loopback remote daemon URLs; the client sends it in both the JSON-RPC request token and HTTP auth headers.
 - `open <app> --remote-config <path> --relaunch` is the canonical remote Metro-backed launch flow for sandbox agents. The remote profile supplies the remote host + Metro settings, `open` prepares Metro locally when needed, derives platform runtime hints, and forwards them inline to the remote daemon before launch.
 - `metro prepare --remote-config <path>` remains available for inspection and debugging. It prints JSON runtime hints to stdout, `--json` wraps them in the standard `{ success, data }` envelope, and `--runtime-file <path>` persists the same payload when callers need an artifact.
 - Android React Native relaunch flows require an installed package name for `open --relaunch`; install/reinstall the APK first, then relaunch by package. `open <apk|aab> --relaunch` is rejected because runtime hints are written through the installed app sandbox.

website/docs/docs/configuration.md

@@ -48,10 +48,12 @@ Example:
   "device": "iPhone 16",
   "session": "qa-ios",
   "snapshotDepth": 3,
-  "daemonBaseUrl": "http://mac-host.example:4310/agent-device"
+  "daemonBaseUrl": "http://127.0.0.1:4310/agent-device"
 }
 ```
 
+For non-loopback remote daemon URLs, also set `daemonAuthToken` or `AGENT_DEVICE_DAEMON_AUTH_TOKEN`. The client rejects non-loopback remote daemon URLs without auth.
+
 Common keys include:
 - `stateDir`
 - `daemonBaseUrl`