Connect page: owner-approved private local listeners

backend/__tests__/unit/routes/agentBinding.grantConfinement.test.js

@@ -53,11 +53,12 @@ const seed = async (sandbox, runtime = { runtimeType: 'wrapper', model: 'claude-
   const owner = await User.create({ username: `o${tag % 1e6}`, email: `o${tag}@x.com`, password: 'x'.repeat(12) });
   global.__CALLER_ID = String(owner._id);
   const bot = await User.create({
-    username: `b${tag % 1e6}`, email: `b${tag}@agents.commonly.local`, password: 'x'.repeat(12),
+    username: AGENT_NAME, email: `${AGENT_NAME}@agents.commonly.local`, password: 'x'.repeat(12),
     isBot: true,
     botMetadata: { agentName: AGENT_NAME, instanceId: 'default', machineId: 'machine-a' },
   });
-  const pod = await Pod.create({ name: `p${tag}`, createdBy: owner._id, members: [owner._id, bot._id] });
+  const pod = await Pod.create({ name: `p${tag}`, createdBy: owner._id,
+    joinPolicy: 'invite-only', members: [owner._id, bot._id] });
   const environment = {
     version: 1,
     model: 'claude-opus-5',

backend/__tests__/unit/routes/registry.runtimeTokenOwnership.test.js

@@ -58,6 +58,13 @@ jest.mock('../../../services/agentIdentityService', () => ({
   ensureAgentInPod: jest.fn().mockResolvedValue(undefined),
 }));
 
+// This suite measures sole-installer authority; private-listener pod
+// eligibility has its own service suite with real installations and members.
+jest.mock('../../../services/privateListenerPolicy', () => ({
+  privateListenerIdentityAllowed: jest.fn().mockResolvedValue(true),
+  isPrivateListenerEnvironment: jest.fn((environment) => environment?.sandbox?.trust === 'private'),
+}));
+
 const mockIsAdmin = jest.fn().mockResolvedValue(false);
 jest.mock('../../../routes/registry/helpers', () => ({
   getUserId: jest.fn((req) => req.userId),

backend/middleware/agentRuntimeAuth.ts

@@ -10,6 +10,7 @@ import AgentCredential from '../models/AgentCredential';
 import { markByoConnectionAttempt } from '../services/onboardingMarks';
 import { isSpawnCredential } from '../services/spawnCredentialService';
 import { machineHasLiveAuthorization } from '../services/machineService';
+import { isPrivateListenerEnvironment, privateListenerIdentityAllowed } from '../services/privateListenerPolicy';
 
 // eslint-disable-next-line global-require
 const { hash } = require('../utils/secret') as { hash: (value: string) => string };
@@ -176,6 +177,13 @@ export default async function agentRuntimeAuth(req: Request, res: Response, next
       if (installations.length === 0) {
         return res.status(401).json({ message: 'Agent not installed' });
       }
+      if (installations.some((installation: any) => isPrivateListenerEnvironment(
+        installation.config instanceof Map
+          ? installation.config.get('environment')
+          : installation.config?.environment,
+      )) && !await privateListenerIdentityAllowed(agentName, instanceId, installations[0].installedBy)) {
+        return res.status(403).json({ code: 'private_listener_paused', message: 'Private listener pod is no longer owner-only' });
+      }
       const installationPodIds = installations
         .map((inst) => inst?.podId?.toString())
         .filter(Boolean) as string[];
@@ -244,6 +252,13 @@ export default async function agentRuntimeAuth(req: Request, res: Response, next
       instanceId: installation.instanceId || 'default',
       status: 'active',
     });
+    if (allActiveInstallations.some((row: any) => isPrivateListenerEnvironment(
+      row.config instanceof Map ? row.config.get('environment') : row.config?.environment,
+    )) && !await privateListenerIdentityAllowed(
+      installation.agentName, installation.instanceId || 'default', installation.installedBy,
+    )) {
+      return res.status(403).json({ code: 'private_listener_paused', message: 'Private listener pod is no longer owner-only' });
+    }
 
     req.agentInstallation = installation as never;
     req.agentInstallations = allActiveInstallations as never[];

backend/routes/agentBinding.ts

@@ -22,6 +22,7 @@ import {
 import { ownsRuntimeIdentity, OwnershipFailure, describeRuntimeIdentityBlockers } from '../services/runtimeIdentityOwnership';
 import { logAgentInstallRefusal } from '../middleware/logAgentInstallRefusal';
 import { machineHasLiveAuthorization } from '../services/machineService';
+import { privateListenerIdentityAllowed } from '../services/privateListenerPolicy';
 
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const auth = require('../middleware/auth');
@@ -216,6 +217,9 @@ router.post('/adopt', bindingRateLimit, daemonAuth('agents:adopt'), async (req:
         code: ownership.failure,
       });
     }
+    if (!await privateListenerIdentityAllowed(agentName, instanceId, machine.ownerUserId)) {
+      return res.status(403).json({ code: 'private_listener_not_allowed', message: 'Private listener pod is no longer owner-only' });
+    }
     // The CAS: only an UNBOUND identity transitions. matchedCount 0 with an
     // existing identity means someone else holds the binding → 409.
     const result = await User.updateOne(
@@ -268,6 +272,10 @@ router.post('/request', logAgentInstallRefusal('/api/agent-binding/request', 'wr
       return res.status(403).json(await ownershipRefusal(req.user?.id, agentName, instanceId, ownership.failure));
     }
 
+    if (requestedMachineId && !await privateListenerIdentityAllowed(agentName, instanceId, req.user?.id)) {
+      return res.status(403).json({ code: 'private_listener_not_allowed', message: 'Private listener pod is no longer owner-only' });
+    }
+
     // An agent Commonly runs in-process (the person's hosted agent) can't also
     // run on a machine: its daemon would be refused at the runtime-token mint,
     // so the page said "requested" and nothing ever ran. Refused here, with the
@@ -433,9 +441,13 @@ router.get('/assigned', bindingRateLimit, daemonAuth('agents:adopt'), async (req
       ],
     }).select('_id botMetadata.agentName botMetadata.instanceId botMetadata.machineId botMetadata.requestedMachineId botMetadata.reconnectRequestedAt').lean() as AssignedIdentity[];
 
-    const grantServers = await grantServersForIdentities(identities, byIdentity);
+    const allowed = await Promise.all(identities.map((identity) => privateListenerIdentityAllowed(
+      normalize(identity.botMetadata?.agentName), normalize(identity.botMetadata?.instanceId) || 'default', machine.ownerUserId,
+    )));
+    const safeIdentities = identities.filter((_identity, index) => allowed[index]);
+    const grantServers = await grantServersForIdentities(safeIdentities, byIdentity);
 
-    const agents = identities.flatMap((identity: AssignedIdentity) => {
+    const agents = safeIdentities.flatMap((identity: AssignedIdentity) => {
       const meta = identity.botMetadata || {};
       const key = seatEnvironmentKey(meta.agentName, meta.instanceId);
       const entry = byIdentity.get(key);
@@ -502,6 +514,10 @@ router.post('/runtime-token', bindingRateLimit, daemonAuth('agents:adopt'), asyn
       });
     }
 
+    if (!await privateListenerIdentityAllowed(agentName, instanceId, machine.ownerUserId)) {
+      return res.status(403).json({ code: 'private_listener_not_allowed', message: 'Private listener pod is no longer owner-only' });
+    }
+
     const agentUser = await User.findOne({
       isBot: true, 'botMetadata.agentName': agentName, 'botMetadata.instanceId': instanceId,
     });

backend/routes/agentsRuntime.ts

@@ -534,6 +534,10 @@ router.get('/installations', phase4RateLimit, agentRuntimeAuth, async (req: any,
 
     const installationList = installations.map((inst: any) => {
       const pod = podMap[String(inst?.podId)] || {};
+      const environment = inst?.config instanceof Map
+        ? inst.config.get('environment') : inst?.config?.environment;
+      const privateWorkspace = environment?.sandbox?.trust === 'private'
+        ? environment?.workspace?.path : null;
       return {
         podId: String(inst?.podId || ''),
         podName: pod.name || null,
@@ -545,6 +549,9 @@ router.get('/installations', phase4RateLimit, agentRuntimeAuth, async (req: any,
         // Known runtime kinds (such as a connect-page `webhook`) stay null.
         // Expose only this non-secret discriminator, never the full config.
         runtimeAdapter: adapterForRuntimeBinding(inst?.config?.runtime),
+        ...(typeof privateWorkspace === 'string' && privateWorkspace.trim()
+          ? { listenerEnvironment: { workspace: { path: privateWorkspace }, sandbox: { trust: 'private' } } }
+          : {}),
         type: 'installation',
       };
     });

backend/routes/registry/agent-config.ts

@@ -3,8 +3,9 @@
 const express = require('express');
 const auth = require('../../middleware/auth');
 const { AgentInstallation } = require('../../models/AgentRegistry');
-const AgentProfile = require('../../models/AgentProfile');
+const User = require('../../models/User');
 const AgentIdentityService = require('../../services/agentIdentityService');
+const AgentProfile = require('../../models/AgentProfile');
 const Pod = require('../../models/Pod');
 const {
   writeWorkspaceIdentityFile,
@@ -24,12 +25,17 @@ const {
 const {
   normalizeToolPolicy,
   normalizeContextPolicy,
+  revokeRuntimeTokensForAgent,
 } = require('./tokens');
 const { validateEnvironmentMcpEntries } = require('../../utils/environmentSpecValidation');
 const { ownsRuntimeIdentity, webhookUrlRefusal } = require('../../services/runtimeIdentityOwnership');
 const { configWriteRefusal, runtimeKeepingType } = require('../../services/configWriteGuard');
 const { assertAgentRuntimeMayJoinPod } = require('../../services/outsiderGrantAgentJoinPolicy');
 const { hostedEngineInEffect } = require('../../services/hostedEngine');
+const {
+  isPrivateListenerEnvironment, privateListenerConfigurationValid,
+  privateListenerPodAllowed, privateListenerIdentityAllowed,
+} = require('../../services/privateListenerPolicy');
 
 const agentConfigRouter = express.Router();
 
@@ -172,6 +178,19 @@ agentConfigRouter.patch('/pods/:podId/agents/:name', auth, async (req: any, res:
           fields: environmentErrors,
         });
       }
+      if (isPrivateListenerEnvironment(config.environment)) {
+        const existingConfig = normalizeConfigMap(installation.config) || {};
+        const runtimeType = config.runtime?.runtimeType || existingConfig.runtime?.runtimeType;
+        const eligible = privateListenerConfigurationValid(config.environment)
+          && await privateListenerPodAllowed(podId, userId, name.toLowerCase(), normalizedInstanceId)
+          && await privateListenerIdentityAllowed(name.toLowerCase(), normalizedInstanceId, userId, true);
+        if (!eligible || !['wrapper', 'webhook'].includes(runtimeType)) {
+          return res.status(403).json({
+            code: 'private_listener_not_allowed',
+            error: 'Full computer access requires an invite-only pod with only you and this listener, and an absolute repo path',
+          });
+        }
+      }
     }
 
     // Being this row's installer is not enough to point its push webhook
@@ -208,6 +227,17 @@ agentConfigRouter.patch('/pods/:podId/agents/:name', auth, async (req: any, res:
               ...(existingConfig.environment?.sandbox || {}), ...environmentControls.sandbox,
             } } : {}) };
         }
+        const requestedTrust = config.environment?.sandbox?.trust;
+        if ((requestedTrust === 'private' || requestedTrust === 'public')
+          && existingConfig.environment && typeof existingConfig.environment === 'object') {
+          const nextEnvironment = { ...existingConfig.environment, ...config.environment };
+          if (isPrivateListenerEnvironment(existingConfig.environment)
+            && !isPrivateListenerEnvironment(nextEnvironment)
+            && !Object.prototype.hasOwnProperty.call(config.environment, 'workspace')) {
+            delete nextEnvironment.workspace;
+          }
+          nextConfig.environment = nextEnvironment;
+        }
         if (config.runtime && typeof config.runtime === 'object') {
           nextConfig.runtime = runtimeKeepingType(config.runtime, existingConfig, { mayChangeType: isInstanceAdmin });
         }
@@ -370,6 +400,29 @@ agentConfigRouter.patch('/pods/:podId/agents/:name', auth, async (req: any, res:
       }
     }
 
+    const downgradesPrivateListener = config?.environment !== undefined
+      && !isPrivateListenerEnvironment(config.environment)
+      && installationsToUpdate.some((entry: any) => isPrivateListenerEnvironment(
+        normalizeConfigMap(entry.config)?.environment,
+      ));
+    const revokePrivateListenerTokens = async () => {
+      // A running one-command listener cached its private environment at boot.
+      // Reload the User on each pass: a concurrent mint may have saved a new
+      // token on that row since the previous pass.
+      const resolvedType = AgentIdentityService.resolveAgentType(name.toLowerCase());
+      const username = AgentIdentityService.buildAgentUsername(resolvedType, normalizedInstanceId);
+      const agentUser = await User.findOne({ username, isBot: true });
+      await revokeRuntimeTokensForAgent({
+        agentUser, agentName: name.toLowerCase(), instanceId: normalizedInstanceId,
+      });
+    };
+    if (downgradesPrivateListener) {
+      // The first pass stops the running private listener before the public
+      // config is visible. The second catches any mint that passed its private
+      // eligibility read while this config write was in flight.
+      await revokePrivateListenerTokens();
+    }
+
     // The User row is the name source for chat and the pod roster. An explicit
     // rename must update that portable identity, not only per-pod projections.
     let renamedIdentity;
@@ -393,6 +446,7 @@ agentConfigRouter.patch('/pods/:podId/agents/:name', auth, async (req: any, res:
         // eslint-disable-next-line no-await-in-loop
         await targetInstallation.save();
       }
+      if (downgradesPrivateListener) await revokePrivateListenerTokens();
 
       if (
         status

backend/routes/registry/agent-tokens.ts

@@ -35,16 +35,22 @@ const auth = require('../../middleware/auth');
 const Pod = require('../../models/Pod');
 const User = require('../../models/User');
 const AgentCredential = require('../../models/AgentCredential');
+const { AgentInstallation } = require('../../models/AgentRegistry');
 const AgentIdentityService = require('../../services/agentIdentityService');
 const {
   getUserId,
   isGlobalAdminUser,
   resolveInstallation,
   resolveRuntimeInstanceId,
   serializeRuntimeTokens,
+  normalizeConfigMap,
 } = require('./helpers');
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const { ownsRuntimeIdentity, runtimeCredentialRefusal } = require('../../services/runtimeIdentityOwnership');
+const {
+  isPrivateListenerEnvironment,
+  privateListenerIdentityAllowed,
+} = require('../../services/privateListenerPolicy');
 const {
   normalizeScopes,
   revokeRuntimeTokenEverywhere,
@@ -196,6 +202,12 @@ agentTokensRouter.post('/pods/:podId/agents/:name/runtime-tokens', tokenRouteLim
 
     const refusal = await credentialRefusal(userId, installation.agentName || name, normalizedInstanceId);
     if (refusal) return res.status(403).json(refusal);
+    if (!await privateListenerIdentityAllowed(installation.agentName || name, normalizedInstanceId, userId)) {
+      return res.status(403).json({ code: 'private_listener_not_allowed', error: 'Private listener pod is no longer owner-only' });
+    }
+    const wasPrivateListener = isPrivateListenerEnvironment(
+      normalizeConfigMap(installation.config)?.environment,
+    );
 
     const resolvedType = AgentIdentityService.resolveAgentType(name);
     const agentUser = await AgentIdentityService.getOrCreateAgentUser(resolvedType, {
@@ -226,6 +238,31 @@ agentTokensRouter.post('/pods/:podId/agents/:name/runtime-tokens', tokenRouteLim
       installation,
       { ownerUserId: userId },
     );
+    if (wasPrivateListener) {
+      // A downgrade may revoke old tokens, then pause while its public config
+      // is saved. A mint that read private trust before that pause must not
+      // outlive the downgrade. The matching post-save revoke catches mints
+      // that finish before the save; this recheck catches mints that finish
+      // afterward. Both sides are needed across backend workers.
+      const current = await AgentInstallation.findById(installation._id).select('config').lean();
+      const stillPrivate = isPrivateListenerEnvironment(
+        normalizeConfigMap(current?.config)?.environment,
+      );
+      if (!stillPrivate || !await privateListenerIdentityAllowed(
+        installation.agentName || name, normalizedInstanceId, userId, true,
+      )) {
+        const freshAgentUser = await User.findById(agentUser._id);
+        await revokeRuntimeTokensForAgent({
+          agentUser: freshAgentUser,
+          agentName: installation.agentName || name,
+          instanceId: normalizedInstanceId,
+        });
+        return res.status(403).json({
+          code: 'private_listener_not_allowed',
+          error: 'Private listener pod is no longer owner-only',
+        });
+      }
+    }
     return res.json(issued);
   } catch (error) {
     if ((error as { code?: string })?.code === 'in_process_agent_no_token') {