🧳 feat: Register Principal-Owned Code Environments (#15365)

* feat: add principal-owned code environments

* fix: address code environment CI coverage

* fix: expose principal code environments in endpoint config

* fix: reject missing code environment bodies

* fix: harden code environment lifecycle

* fix: revalidate principal code environments

* fix: synchronize code environment authorization

* fix: bind code environments to current principals

* fix: fail closed on code ACL cache errors

* fix: prevent code environment override shadowing

* fix: preserve principal environment defaults

* fix: suppress revoked code environment aliases

* fix: fail closed on environment augmentation

* fix: narrow code environment defaults

* fix: isolate code environment fallback

* style: sort code config imports
This commit is contained in:
Danny Avila 2026-08-30 19:33:19 -04:00 • committed by GitHub
parent 0389a92452
commit fcae1025c0
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
48 changed files with 2178 additions and 35 deletions

View file

@ -0,0 +1,336 @@
import { EModelEndpoint } from 'librechat-data-provider';
import type { AppConfig } from '@librechat/data-schemas';
import { mergeAccessibleCodeEnvironments } from './config';
describe('mergeAccessibleCodeEnvironments', () => {
test('adds principal environments without allowing them to shadow deployment entries', async () => {
const appConfig = {
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
allowedEnvironments: ['conversation'],
environments: [
{
id: 'deployment-vm',
name: 'Deployment VM',
type: 'attached',
baseURL: 'https://deployment.example',
owner: 'deployment',
pairing: { workerId: 'deployment-worker', tokenEnv: 'CODE_ADMIN_TOKEN' },
},
],
},
},
},
} as unknown as AppConfig;
const listAccessibleConfigurations = jest.fn().mockResolvedValue([
{
id: 'personal-vm',
name: 'Personal VM',
type: 'attached',
baseURL: 'https://retired.example',
controlPlaneId: 'deployment-vm',
owner: 'principal',
},
{
id: 'deployment-vm',
name: 'Shadow Attempt',
type: 'attached',
baseURL: 'https://shadow.example',
controlPlaneId: 'deployment-vm',
owner: 'principal',
},
]);
const result = await mergeAccessibleCodeEnvironments({
appConfig,
deploymentConfig: appConfig,
actor: { userId: '68b2f0c498f24c1e78fa0001', role: 'USER', idOnTheSource: null },
registry: {
listAccessibleConfigurations,
listRegisteredIds: jest.fn().mockResolvedValue(['personal-vm', 'deployment-vm']),
},
});
expect(result).not.toBe(appConfig);
expect(result.endpoints?.agents?.statefulCodeSessions?.environments).toEqual([
expect.objectContaining({ id: 'deployment-vm', baseURL: 'https://deployment.example' }),
expect.objectContaining({ id: 'personal-vm', baseURL: 'https://deployment.example' }),
]);
expect(appConfig.endpoints?.agents?.statefulCodeSessions?.environments).toHaveLength(1);
});
test('fails closed when a principal environment references a retired control plane', async () => {
const appConfig = {
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
allowedEnvironments: ['conversation'],
environments: [],
},
},
},
} as unknown as AppConfig;
const listAccessibleConfigurations = jest.fn().mockResolvedValue([
{
id: 'personal-vm',
name: 'Personal VM',
type: 'attached',
baseURL: 'https://retired.example',
controlPlaneId: 'retired-plane',
owner: 'principal',
},
]);
const result = await mergeAccessibleCodeEnvironments({
appConfig,
deploymentConfig: appConfig,
actor: { userId: '68b2f0c498f24c1e78fa0001', role: 'USER', idOnTheSource: null },
registry: {
listAccessibleConfigurations,
listRegisteredIds: jest.fn().mockResolvedValue(['personal-vm']),
},
});
expect(result).toBe(appConfig);
});
test('resolves principal aliases only against the YAML deployment config', async () => {
const deploymentConfig = {
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
environments: [
{
id: 'approved-plane',
name: 'Approved Plane',
type: 'attached',
baseURL: 'https://approved.example',
owner: 'deployment',
pairing: { workerId: 'approved-worker', tokenEnv: 'CODE_ADMIN_TOKEN' },
},
],
},
},
},
} as unknown as AppConfig;
const appConfig = {
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
environments: [
{
id: 'approved-plane',
name: 'Override Plane',
type: 'attached',
baseURL: 'https://override.example',
owner: 'deployment',
pairing: { workerId: 'override-worker', tokenEnv: 'OVERRIDE_TOKEN' },
},
],
},
},
},
} as unknown as AppConfig;
const input = {
appConfig,
deploymentConfig,
actor: { userId: '68b2f0c498f24c1e78fa0001', role: 'USER', idOnTheSource: null },
registry: {
listRegisteredIds: jest.fn().mockResolvedValue(['personal-vm']),
listAccessibleConfigurations: jest.fn().mockResolvedValue([
{
id: 'personal-vm',
name: 'Personal VM',
type: 'attached',
baseURL: 'https://persisted.example',
controlPlaneId: 'approved-plane',
owner: 'principal',
},
]),
},
};
const result = await mergeAccessibleCodeEnvironments(input);
const environments = result.endpoints?.agents?.statefulCodeSessions?.environments;
expect(environments?.find((environment) => environment.id === 'personal-vm')?.baseURL).toBe(
'https://approved.example',
);
});
test('replaces a merged override that shadows an accessible principal environment', async () => {
const deploymentConfig = {
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
environments: [
{
id: 'approved-plane',
name: 'Approved Plane',
type: 'attached',
baseURL: 'https://approved.example',
owner: 'deployment',
pairing: { workerId: 'approved-worker', tokenEnv: 'CODE_ADMIN_TOKEN' },
},
],
},
},
},
} as unknown as AppConfig;
const appConfig = {
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
environments: [
{
id: 'personal-vm',
name: 'Shadow Override',
type: 'attached',
baseURL: 'https://shadow.example',
owner: 'deployment',
default: true,
pairing: { workerId: 'shadow-worker', tokenEnv: 'SHADOW_TOKEN' },
},
],
},
},
},
} as unknown as AppConfig;
const result = await mergeAccessibleCodeEnvironments({
appConfig,
deploymentConfig,
actor: { userId: '68b2f0c498f24c1e78fa0001', role: 'USER', idOnTheSource: null },
registry: {
listRegisteredIds: jest.fn().mockResolvedValue(['personal-vm']),
listAccessibleConfigurations: jest.fn().mockResolvedValue([
{
id: 'personal-vm',
name: 'Personal VM',
type: 'attached',
baseURL: 'https://persisted.example',
controlPlaneId: 'approved-plane',
owner: 'principal',
},
]),
},
});
const environments = result.endpoints?.agents?.statefulCodeSessions?.environments;
expect(environments).toEqual([
expect.objectContaining({
id: 'personal-vm',
name: 'Personal VM',
baseURL: 'https://approved.example',
owner: 'principal',
default: true,
}),
]);
});
test('suppresses a registered environment shadow after its ACL is revoked', async () => {
const appConfig = {
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
environments: [
{
id: 'revoked-vm',
name: 'Revoked Shadow',
type: 'attached',
baseURL: 'https://shadow.example',
owner: 'deployment',
default: true,
pairing: { workerId: 'shadow-worker', tokenEnv: 'SHADOW_TOKEN' },
},
{
id: 'unrelated-override',
name: 'Unrelated Override',
type: 'attached',
baseURL: 'https://unrelated.example',
owner: 'deployment',
pairing: { workerId: 'other-worker', tokenEnv: 'OTHER_TOKEN' },
},
],
},
},
},
} as unknown as AppConfig;
const result = await mergeAccessibleCodeEnvironments({
appConfig,
deploymentConfig: {
endpoints: {
[EModelEndpoint.agents]: { statefulCodeSessions: { environments: [] } },
},
} as unknown as AppConfig,
actor: { userId: '68b2f0c498f24c1e78fa0001', role: 'USER', idOnTheSource: null },
registry: {
listAccessibleConfigurations: jest.fn().mockResolvedValue([]),
listRegisteredIds: jest.fn().mockResolvedValue(['revoked-vm']),
},
});
expect(result.endpoints?.agents?.statefulCodeSessions?.environments).toEqual([
expect.objectContaining({ id: 'unrelated-override', default: true }),
]);
});
test('preserves unrelated restrictions while failing closed to deployment environments', async () => {
const deploymentEnvironment = {
id: 'approved-plane',
name: 'Approved Plane',
type: 'attached' as const,
baseURL: 'https://approved.example',
owner: 'deployment' as const,
default: true,
pairing: { workerId: 'approved-worker', tokenEnv: 'CODE_ADMIN_TOKEN' },
};
const deploymentConfig = {
interfaceConfig: { schedules: true },
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: { environments: [deploymentEnvironment] },
},
},
} as unknown as AppConfig;
const appConfig = {
interfaceConfig: { schedules: false },
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
environments: [
{
id: 'principal-shadow',
name: 'Principal Shadow',
type: 'attached',
baseURL: 'https://shadow.example',
owner: 'deployment',
default: true,
pairing: { workerId: 'shadow-worker', tokenEnv: 'SHADOW_TOKEN' },
},
],
},
},
},
} as unknown as AppConfig;
const result = await mergeAccessibleCodeEnvironments({
appConfig,
deploymentConfig,
actor: { userId: '68b2f0c498f24c1e78fa0001', role: 'USER', idOnTheSource: null },
registry: {
listAccessibleConfigurations: jest
.fn()
.mockRejectedValue(new Error('authorization unavailable')),
listRegisteredIds: jest.fn().mockResolvedValue(['principal-shadow']),
},
});
expect(result.interfaceConfig?.schedules).toBe(false);
expect(result.endpoints?.agents?.statefulCodeSessions?.environments).toEqual([
deploymentEnvironment,
]);
});
});

View file

@ -0,0 +1,141 @@
import { logger } from '@librechat/data-schemas';
import { EModelEndpoint } from 'librechat-data-provider';
import type { AppConfig } from '@librechat/data-schemas';
import type {
AccessibleCodeEnvironmentConfiguration,
CodeEnvironmentPrincipalContext,
} from './environments';
type ConfigurationRegistry = {
listAccessibleConfigurations: (
actor: CodeEnvironmentPrincipalContext,
) => Promise<AccessibleCodeEnvironmentConfiguration[]>;
listRegisteredIds: () => Promise<string[]>;
};
function retainDeploymentCodeEnvironments(
appConfig: AppConfig,
deploymentConfig: AppConfig,
): AppConfig {
const agents = appConfig.endpoints?.[EModelEndpoint.agents];
const sessions = agents?.statefulCodeSessions;
if (sessions == null) return appConfig;
return {
...appConfig,
endpoints: {
...appConfig.endpoints,
[EModelEndpoint.agents]: {
...agents,
statefulCodeSessions: {
...sessions,
environments:
deploymentConfig.endpoints?.[EModelEndpoint.agents]?.statefulCodeSessions
?.environments ?? [],
},
},
},
};
}
export async function mergeAccessibleCodeEnvironments({
appConfig,
deploymentConfig,
actor,
registry,
}: {
appConfig: AppConfig;
deploymentConfig: AppConfig;
actor: CodeEnvironmentPrincipalContext;
registry: ConfigurationRegistry;
}): Promise<AppConfig> {
const agents = appConfig.endpoints?.[EModelEndpoint.agents];
const sessions = agents?.statefulCodeSessions;
if (sessions == null) return appConfig;
let accessible: AccessibleCodeEnvironmentConfiguration[];
let registeredIds: string[];
try {
[accessible, registeredIds] = await Promise.all([
registry.listAccessibleConfigurations(actor),
registry.listRegisteredIds(),
]);
} catch (error) {
logger.error(
'[mergeAccessibleCodeEnvironments] Unable to authorize principal environments; retaining deployment environments:',
error,
);
return retainDeploymentCodeEnvironments(appConfig, deploymentConfig);
}
const deploymentSessions =
deploymentConfig.endpoints?.[EModelEndpoint.agents]?.statefulCodeSessions;
const deploymentEnvironments = new Map(
deploymentSessions?.environments
?.filter(
(environment) =>
environment.owner === 'deployment' &&
environment.type === 'attached' &&
environment.pairing != null,
)
.map((environment) => [environment.id, environment]) ?? [],
);
const registeredAliasIds = new Set(
registeredIds.filter((environmentId) => !deploymentEnvironments.has(environmentId)),
);
const principalEnvironments = accessible.flatMap(
({ controlPlaneId, baseURL: _persistedBaseURL, ...environment }) => {
const controlPlane = deploymentEnvironments.get(controlPlaneId);
if (controlPlane == null || deploymentEnvironments.has(environment.id)) return [];
return [{ ...environment, baseURL: controlPlane.baseURL }];
},
);
const principalEnvironmentIds = new Set(
principalEnvironments.map((environment) => environment.id),
);
const shadowedDefaultIds = new Set(
(sessions.environments ?? [])
.filter(
(environment) =>
environment.default === true && principalEnvironmentIds.has(environment.id),
)
.map((environment) => environment.id),
);
const effectivePrincipalEnvironments = principalEnvironments.map((environment) =>
shadowedDefaultIds.has(environment.id)
? { ...environment, default: true as const }
: environment,
);
const existingEnvironments = sessions.environments ?? [];
const filteredEnvironments = existingEnvironments.filter(
(environment) => !registeredAliasIds.has(environment.id),
);
if (
effectivePrincipalEnvironments.length === 0 &&
filteredEnvironments.length === existingEnvironments.length
) {
return appConfig;
}
const mergedEnvironments = [...filteredEnvironments, ...effectivePrincipalEnvironments];
if (
mergedEnvironments.length > 0 &&
!mergedEnvironments.some(
(environment) => 'default' in environment && environment.default === true,
)
) {
mergedEnvironments[0] = { ...mergedEnvironments[0], default: true };
}
return {
...appConfig,
endpoints: {
...appConfig.endpoints,
[EModelEndpoint.agents]: {
...agents,
statefulCodeSessions: {
...sessions,
environments: mergedEnvironments,
},
},
},
};
}

View file

@ -0,0 +1,369 @@
import mongoose, { Types } from 'mongoose';
import { MongoMemoryServer } from 'mongodb-memory-server';
import { createMethods, createModels } from '@librechat/data-schemas';
import { AccessRoleIds, PrincipalType, ResourceType } from 'librechat-data-provider';
import { AccessControlService } from '~/acl/accessControlService';
import { createCodeEnvironmentRegistry } from './environments';
function createSharedCache() {
const values = new Map<string, unknown>();
return {
get: jest.fn(async (key: string) => values.get(key)),
set: jest.fn(async (key: string, value: unknown) => {
values.set(key, value);
return true;
}),
};
}
describe('code environment registry', () => {
let mongoServer: MongoMemoryServer;
beforeAll(async () => {
mongoServer = await MongoMemoryServer.create();
await mongoose.connect(mongoServer.getUri());
createModels(mongoose);
await Promise.all(Object.values(mongoose.models).map((model) => model.init()));
await createMethods(mongoose).seedDefaultRoles();
});
afterAll(async () => {
await mongoose.disconnect();
await mongoServer.stop();
});
beforeEach(async () => {
await mongoose.connection.dropDatabase();
await createMethods(mongoose).seedDefaultRoles();
});
test('discovers a registered environment only for its owner principal', async () => {
const registry = createCodeEnvironmentRegistry(mongoose);
const ownerId = new Types.ObjectId();
const strangerId = new Types.ObjectId();
const created = await registry.register({
actor: { userId: ownerId, role: 'USER', idOnTheSource: null },
environment: {
id: 'danny-vm',
name: "Danny's VM",
type: 'attached',
baseURL: 'https://code.example.com',
controlPlaneId: 'shared-code-api',
},
});
expect(mongoose.models.CodeEnvironment.schema.path('controlPlaneId')).toBeDefined();
expect(created).toEqual({
resourceId: expect.any(String),
id: 'danny-vm',
name: "Danny's VM",
type: 'attached',
});
await expect(registry.listRegisteredIds()).resolves.toEqual(['danny-vm']);
await expect(
registry.listAccessible({ userId: ownerId, role: 'USER', idOnTheSource: null }),
).resolves.toEqual([created]);
await expect(
registry.listAccessible({ userId: strangerId, role: 'USER', idOnTheSource: null }),
).resolves.toEqual([]);
await expect(
registry.listAccessibleConfigurations({
userId: ownerId,
role: 'USER',
idOnTheSource: null,
}),
).resolves.toEqual([
{
id: 'danny-vm',
name: "Danny's VM",
type: 'attached',
baseURL: 'https://code.example.com',
controlPlaneId: 'shared-code-api',
owner: 'principal',
},
]);
});
test('discovers environments granted through role and group principals', async () => {
const registry = createCodeEnvironmentRegistry(mongoose);
const methods = createMethods(mongoose);
const access = new AccessControlService(mongoose);
const ownerId = new Types.ObjectId();
const teammateId = new Types.ObjectId();
const group = await methods.createGroup({
name: 'Code Team',
source: 'local',
memberIds: [teammateId.toString()],
});
const roleEnvironment = await registry.register({
actor: { userId: ownerId, role: 'USER', idOnTheSource: null },
environment: {
id: 'role-vm',
name: 'Role VM',
type: 'attached',
baseURL: 'https://code.example.com',
controlPlaneId: 'shared-code-api',
},
});
const groupEnvironment = await registry.register({
actor: { userId: ownerId, role: 'USER', idOnTheSource: null },
environment: {
id: 'group-vm',
name: 'Group VM',
type: 'attached',
baseURL: 'https://code.example.com',
controlPlaneId: 'shared-code-api',
},
});
await access.grantPermission({
principalType: PrincipalType.ROLE,
principalId: 'CODE_USER',
resourceType: ResourceType.CODE_ENVIRONMENT,
resourceId: roleEnvironment.resourceId,
accessRoleId: AccessRoleIds.CODE_ENVIRONMENT_VIEWER,
grantedBy: ownerId,
});
await access.grantPermission({
principalType: PrincipalType.GROUP,
principalId: group._id,
resourceType: ResourceType.CODE_ENVIRONMENT,
resourceId: groupEnvironment.resourceId,
accessRoleId: AccessRoleIds.CODE_ENVIRONMENT_VIEWER,
grantedBy: ownerId,
});
await expect(
registry.listAccessible({
userId: teammateId,
role: 'CODE_USER',
idOnTheSource: null,
}),
).resolves.toEqual([roleEnvironment, groupEnvironment]);
});
test('removes creator-owned environment records and grants when the user is deleted', async () => {
const registry = createCodeEnvironmentRegistry(mongoose);
const methods = createMethods(mongoose);
const ownerId = new Types.ObjectId();
const environment = await registry.register({
actor: { userId: ownerId, role: 'USER', idOnTheSource: null },
environment: {
id: 'departing-user-vm',
name: 'Departing user VM',
type: 'attached',
baseURL: 'https://code.example.com',
controlPlaneId: 'shared-code-api',
},
});
await expect(methods.deleteUserCodeEnvironments(ownerId)).resolves.toBe(1);
await expect(
registry.listAccessible({ userId: ownerId, role: 'USER', idOnTheSource: null }),
).resolves.toEqual([]);
await expect(
mongoose.models.AclEntry.countDocuments({
resourceType: ResourceType.CODE_ENVIRONMENT,
resourceId: environment.resourceId,
}),
).resolves.toBe(0);
});
test('invalidates shared configuration caches after registration', async () => {
const cache = createSharedCache();
const firstWorker = createCodeEnvironmentRegistry(mongoose, { configurationCache: cache });
const secondWorker = createCodeEnvironmentRegistry(mongoose, { configurationCache: cache });
const ownerId = new Types.ObjectId();
const actor = { userId: ownerId, role: 'USER', idOnTheSource: null };
await expect(firstWorker.listAccessibleConfigurations(actor)).resolves.toEqual([]);
await secondWorker.register({
actor,
environment: {
id: 'shared-cache-vm',
name: 'Shared cache VM',
type: 'attached',
baseURL: 'https://code.example.com',
controlPlaneId: 'shared-code-api',
},
});
await expect(firstWorker.listAccessibleConfigurations(actor)).resolves.toEqual([
expect.objectContaining({ id: 'shared-cache-vm' }),
]);
});
test('caches registered environment ids behind the shared tenant revision', async () => {
const cache = createSharedCache();
const firstWorker = createCodeEnvironmentRegistry(mongoose, { configurationCache: cache });
const secondWorker = createCodeEnvironmentRegistry(mongoose, { configurationCache: cache });
const distinct = jest.spyOn(mongoose.models.CodeEnvironment, 'distinct');
const ownerId = new Types.ObjectId();
await expect(firstWorker.listRegisteredIds()).resolves.toEqual([]);
await expect(firstWorker.listRegisteredIds()).resolves.toEqual([]);
expect(distinct).toHaveBeenCalledTimes(1);
await secondWorker.register({
actor: { userId: ownerId, role: 'USER', idOnTheSource: null },
environment: {
id: 'revision-cached-vm',
name: 'Revision Cached VM',
type: 'attached',
baseURL: 'https://code.example.com',
controlPlaneId: 'shared-code-api',
},
});
await expect(firstWorker.listRegisteredIds()).resolves.toEqual(['revision-cached-vm']);
expect(distinct).toHaveBeenCalledTimes(2);
distinct.mockRestore();
});
test('invalidates shared configuration caches after ACL revocation', async () => {
const cache = createSharedCache();
const registry = createCodeEnvironmentRegistry(mongoose, { configurationCache: cache });
const ownerId = new Types.ObjectId();
const teammateId = new Types.ObjectId();
const environment = await registry.register({
actor: { userId: ownerId, role: 'USER', idOnTheSource: null },
environment: {
id: 'revoked-vm',
name: 'Revoked VM',
type: 'attached',
baseURL: 'https://code.example.com',
controlPlaneId: 'shared-code-api',
},
});
const access = new AccessControlService(mongoose);
await access.grantPermission({
principalType: PrincipalType.USER,
principalId: teammateId,
resourceType: ResourceType.CODE_ENVIRONMENT,
resourceId: environment.resourceId,
accessRoleId: AccessRoleIds.CODE_ENVIRONMENT_VIEWER,
grantedBy: ownerId,
});
const teammate = { userId: teammateId, role: 'USER', idOnTheSource: null };
await expect(registry.listAccessibleConfigurations(teammate)).resolves.toHaveLength(1);
await mongoose.models.AclEntry.deleteMany({
principalType: PrincipalType.USER,
principalId: teammateId,
resourceType: ResourceType.CODE_ENVIRONMENT,
resourceId: environment.resourceId,
});
await registry.invalidateAccessibleConfigurations();
await expect(registry.listAccessibleConfigurations(teammate)).resolves.toEqual([]);
});
test('does not reuse revoked access when cache invalidation fails', async () => {
const cache = createSharedCache();
const registry = createCodeEnvironmentRegistry(mongoose, { configurationCache: cache });
const ownerId = new Types.ObjectId();
const teammateId = new Types.ObjectId();
const environment = await registry.register({
actor: { userId: ownerId, role: 'USER', idOnTheSource: null },
environment: {
id: 'fail-closed-vm',
name: 'Fail Closed VM',
type: 'attached',
baseURL: 'https://code.example.com',
controlPlaneId: 'shared-code-api',
},
});
const access = new AccessControlService(mongoose);
await access.grantPermission({
principalType: PrincipalType.USER,
principalId: teammateId,
resourceType: ResourceType.CODE_ENVIRONMENT,
resourceId: environment.resourceId,
accessRoleId: AccessRoleIds.CODE_ENVIRONMENT_VIEWER,
grantedBy: ownerId,
});
const teammate = { userId: teammateId, role: 'USER', idOnTheSource: null };
await expect(registry.listAccessibleConfigurations(teammate)).resolves.toHaveLength(1);
await mongoose.models.AclEntry.deleteMany({
principalType: PrincipalType.USER,
principalId: teammateId,
resourceType: ResourceType.CODE_ENVIRONMENT,
resourceId: environment.resourceId,
});
cache.set.mockRejectedValueOnce(new Error('redis unavailable'));
await expect(registry.invalidateAccessibleConfigurations()).rejects.toThrow(
'redis unavailable',
);
await expect(registry.listAccessibleConfigurations(teammate)).resolves.toEqual([]);
});
test('does not reuse cached access after group membership changes', async () => {
const cache = createSharedCache();
const registry = createCodeEnvironmentRegistry(mongoose, { configurationCache: cache });
const methods = createMethods(mongoose);
const ownerId = new Types.ObjectId();
const teammateId = new Types.ObjectId();
const group = await methods.createGroup({
name: 'Temporary Code Team',
source: 'local',
memberIds: [teammateId.toString()],
});
const environment = await registry.register({
actor: { userId: ownerId, role: 'USER', idOnTheSource: null },
environment: {
id: 'temporary-group-vm',
name: 'Temporary Group VM',
type: 'attached',
baseURL: 'https://code.example.com',
controlPlaneId: 'shared-code-api',
},
});
const access = new AccessControlService(mongoose);
await access.grantPermission({
principalType: PrincipalType.GROUP,
principalId: group._id,
resourceType: ResourceType.CODE_ENVIRONMENT,
resourceId: environment.resourceId,
accessRoleId: AccessRoleIds.CODE_ENVIRONMENT_VIEWER,
grantedBy: ownerId,
});
const teammate = { userId: teammateId, role: 'USER', idOnTheSource: null };
await expect(registry.listAccessibleConfigurations(teammate)).resolves.toHaveLength(1);
await methods.updateGroupById(group._id, { memberIds: [] });
await expect(registry.listAccessibleConfigurations(teammate)).resolves.toEqual([]);
});
test('rolls registration back when shared cache invalidation fails', async () => {
const registry = createCodeEnvironmentRegistry(mongoose, {
configurationCache: {
get: jest.fn(),
set: jest.fn().mockRejectedValue(new Error('redis unavailable')),
},
});
const ownerId = new Types.ObjectId();
await expect(
registry.register({
actor: { userId: ownerId, role: 'USER', idOnTheSource: null },
environment: {
id: 'rolled-back-vm',
name: 'Rolled Back VM',
type: 'attached',
baseURL: 'https://code.example.com',
controlPlaneId: 'shared-code-api',
},
}),
).rejects.toThrow('redis unavailable');
await expect(
mongoose.models.CodeEnvironment.countDocuments({ environmentId: 'rolled-back-vm' }),
).resolves.toBe(0);
await expect(
mongoose.models.AclEntry.countDocuments({ resourceType: ResourceType.CODE_ENVIRONMENT }),
).resolves.toBe(0);
});
});

View file

@ -0,0 +1,316 @@
import { Types } from 'mongoose';
import { createHash, randomUUID } from 'node:crypto';
import { createMethods, getTenantId, logger } from '@librechat/data-schemas';
import {
AccessRoleIds,
PermissionBits,
PrincipalType,
ResourceType,
isSecureCodeEnvironmentControlURL,
} from 'librechat-data-provider';
import type { ResolvedPrincipal } from '~/types/principal';
import { AccessControlService } from '~/acl/accessControlService';
export type CodeEnvironmentPrincipalContext = {
userId: string | Types.ObjectId;
role?: string | null;
idOnTheSource?: string | null;
principals?: ResolvedPrincipal[];
};
export type CodeEnvironmentSummary = {
resourceId: string;
id: string;
name: string;
type: 'managed' | 'attached';
};
export type CodeEnvironmentRegistration = {
id: string;
name: string;
type: 'managed' | 'attached';
baseURL: string;
controlPlaneId: string;
workerId?: string;
};
export type AccessibleCodeEnvironmentConfiguration = {
id: string;
name: string;
type: 'managed' | 'attached';
baseURL: string;
controlPlaneId: string;
owner: 'principal';
};
type CachedAccessibleCodeEnvironmentConfiguration = AccessibleCodeEnvironmentConfiguration & {
resourceId: string;
};
const ENVIRONMENT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
const WORKER_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
const CONFIGURATION_CACHE_TTL_MS = 5_000;
const CONFIGURATION_CACHE_REVISION_PREFIX = 'revision';
const CONFIGURATION_CACHE_REGISTERED_PREFIX = 'registered';
const CONFIGURATION_CACHE_USER_PREFIX = 'user';
type CodeEnvironmentConfigurationCache = {
get: (key: string) => Promise<unknown>;
set: (key: string, value: unknown, ttl?: number) => Promise<unknown>;
};
type CodeEnvironmentRegistryOptions = {
/** Shared cache only. Omit this dependency when Redis is unavailable so ACL reads stay live. */
configurationCache?: CodeEnvironmentConfigurationCache;
};
export class CodeEnvironmentValidationError extends Error {
constructor(message: string) {
super(message);
this.name = 'CodeEnvironmentValidationError';
}
}
function normalizeRegistration(input: CodeEnvironmentRegistration): CodeEnvironmentRegistration {
const id = input.id.trim();
const name = input.name.trim();
const baseURL = input.baseURL.trim().replace(/\/+$/, '');
const controlPlaneId = input.controlPlaneId.trim();
const workerId = input.workerId?.trim();
if (!ENVIRONMENT_ID_PATTERN.test(id)) {
throw new CodeEnvironmentValidationError('Code environment id is invalid');
}
if (name.length < 1 || name.length > 100) {
throw new CodeEnvironmentValidationError(
'Code environment name must contain between 1 and 100 characters',
);
}
if (!isSecureCodeEnvironmentControlURL(baseURL)) {
throw new CodeEnvironmentValidationError('Code environment control requires secure transport');
}
if (!ENVIRONMENT_ID_PATTERN.test(controlPlaneId)) {
throw new CodeEnvironmentValidationError('Code environment control plane id is invalid');
}
if (workerId != null && !WORKER_ID_PATTERN.test(workerId)) {
throw new CodeEnvironmentValidationError('Code environment worker id is invalid');
}
return { ...input, id, name, baseURL, controlPlaneId, workerId };
}
function toSummary(environment: {
_id: Types.ObjectId;
environmentId: string;
name: string;
type: 'managed' | 'attached';
}): CodeEnvironmentSummary {
return {
resourceId: environment._id.toString(),
id: environment.environmentId,
name: environment.name,
type: environment.type,
};
}
export function createCodeEnvironmentRegistry(
mongoose: typeof import('mongoose'),
options: CodeEnvironmentRegistryOptions = {},
): {
register: (params: {
actor: CodeEnvironmentPrincipalContext;
environment: CodeEnvironmentRegistration;
}) => Promise<CodeEnvironmentSummary>;
listAccessible: (actor: CodeEnvironmentPrincipalContext) => Promise<CodeEnvironmentSummary[]>;
listAccessibleConfigurations: (
actor: CodeEnvironmentPrincipalContext,
) => Promise<AccessibleCodeEnvironmentConfiguration[]>;
listRegisteredIds: () => Promise<string[]>;
invalidateAccessibleConfigurations: (tenantId?: string) => Promise<void>;
} {
const methods = createMethods(mongoose);
const access = new AccessControlService(mongoose);
const configurationCache = options.configurationCache;
function tenantCacheKey(tenantId?: string): string {
return encodeURIComponent(tenantId ?? getTenantId() ?? '__default__');
}
function revisionKey(tenantId?: string): string {
return `${CONFIGURATION_CACHE_REVISION_PREFIX}:${tenantCacheKey(tenantId)}`;
}
async function invalidateAccessibleConfigurations(tenantId?: string): Promise<void> {
if (configurationCache == null) return;
await configurationCache.set(revisionKey(tenantId), randomUUID());
}
async function listRegisteredIds(): Promise<string[]> {
if (configurationCache == null) return await methods.listCodeEnvironmentIds();
const tenant = tenantCacheKey();
const revision = String((await configurationCache.get(revisionKey())) ?? '0');
const key = `${CONFIGURATION_CACHE_REGISTERED_PREFIX}:${tenant}:${revision}`;
const cached = await configurationCache.get(key);
if (
Array.isArray(cached) &&
cached.every((environmentId) => typeof environmentId === 'string')
) {
return cached;
}
const environmentIds = await methods.listCodeEnvironmentIds();
const currentRevision = String((await configurationCache.get(revisionKey())) ?? '0');
if (currentRevision !== revision) {
return await listRegisteredIds();
}
await configurationCache.set(key, environmentIds, CONFIGURATION_CACHE_TTL_MS);
return environmentIds;
}
async function register({
actor,
environment: input,
}: {
actor: CodeEnvironmentPrincipalContext;
environment: CodeEnvironmentRegistration;
}): Promise<CodeEnvironmentSummary> {
const environment = normalizeRegistration(input);
const created = await methods.createCodeEnvironment({
environmentId: environment.id,
name: environment.name,
type: environment.type,
baseURL: environment.baseURL,
controlPlaneId: environment.controlPlaneId,
workerId: environment.workerId,
createdBy: new Types.ObjectId(actor.userId),
});
try {
const permission = await access.grantPermission({
principalType: PrincipalType.USER,
principalId: actor.userId,
resourceType: ResourceType.CODE_ENVIRONMENT,
resourceId: created._id,
accessRoleId: AccessRoleIds.CODE_ENVIRONMENT_OWNER,
grantedBy: actor.userId,
});
if (permission == null) {
throw new Error('Unable to grant code environment ownership');
}
const summary = toSummary(created);
await invalidateAccessibleConfigurations();
return summary;
} catch (error) {
const cleanup = await Promise.allSettled([
access.removeAllPermissions({
resourceType: ResourceType.CODE_ENVIRONMENT,
resourceId: created._id,
}),
methods.deleteCodeEnvironmentById(created._id),
]);
for (const result of cleanup) {
if (result.status === 'rejected') {
logger.error('[codeEnvironments] registration rollback failed:', result.reason);
}
}
throw error;
}
}
async function findAccessibleResourceIds(principals: ResolvedPrincipal[]) {
return await access.findAccessibleResourcesForPrincipals({
principalsList: principals,
resourceType: ResourceType.CODE_ENVIRONMENT,
requiredPermissions: PermissionBits.VIEW,
});
}
async function findAccessible(actor: CodeEnvironmentPrincipalContext) {
const principals = actor.principals ?? (await methods.getUserPrincipals(actor));
const ids = await findAccessibleResourceIds(principals);
return await methods.findCodeEnvironmentsByIds(ids);
}
async function listAccessible(
actor: CodeEnvironmentPrincipalContext,
): Promise<CodeEnvironmentSummary[]> {
const environments = await findAccessible(actor);
return environments.map(toSummary);
}
async function listAccessibleConfigurations(
actor: CodeEnvironmentPrincipalContext,
): Promise<AccessibleCodeEnvironmentConfiguration[]> {
const principals = actor.principals ?? (await methods.getUserPrincipals(actor));
const principalFingerprint = createHash('sha256')
.update(
principals
.map(
({ principalType, principalId }) => `${principalType}:${principalId?.toString() ?? ''}`,
)
.sort()
.join('\n'),
)
.digest('base64url');
const toPublicConfiguration = ({
resourceId: _resourceId,
...configuration
}: CachedAccessibleCodeEnvironmentConfiguration): AccessibleCodeEnvironmentConfiguration =>
configuration;
const load = async (): Promise<CachedAccessibleCodeEnvironmentConfiguration[]> => {
const ids = await findAccessibleResourceIds(principals);
const environments = await methods.findCodeEnvironmentsByIds(ids);
return environments.map((environment) => ({
resourceId: environment._id.toString(),
id: environment.environmentId,
name: environment.name,
type: environment.type,
baseURL: environment.baseURL,
controlPlaneId: environment.controlPlaneId,
owner: 'principal',
}));
};
if (configurationCache == null) return (await load()).map(toPublicConfiguration);
const tenant = tenantCacheKey();
const revision = String((await configurationCache.get(revisionKey())) ?? '0');
const key =
`${CONFIGURATION_CACHE_USER_PREFIX}:${tenant}:${actor.userId.toString()}:` +
`${principalFingerprint}:${revision}`;
const cached = await configurationCache.get(key);
if (
Array.isArray(cached) &&
cached.every(
(configuration) =>
configuration != null &&
typeof configuration === 'object' &&
typeof (configuration as { resourceId?: unknown }).resourceId === 'string',
)
) {
// The cache accelerates configuration lookup, not authorization. Re-check the current
// ACL on every use so a failed revision write can delay grants but can never preserve a
// revocation. Entries written before resourceId was cached are deliberately treated as
// misses during rolling upgrades.
const accessibleIds = new Set(
(await findAccessibleResourceIds(principals)).map((id) => id.toString()),
);
return (cached as CachedAccessibleCodeEnvironmentConfiguration[])
.filter(({ resourceId }) => accessibleIds.has(resourceId))
.map(toPublicConfiguration);
}
const configurations = await load();
const currentRevision = String((await configurationCache.get(revisionKey())) ?? '0');
if (currentRevision !== revision) {
return await listAccessibleConfigurations(actor);
}
await configurationCache.set(key, configurations, CONFIGURATION_CACHE_TTL_MS);
return configurations.map(toPublicConfiguration);
}
return {
register,
listAccessible,
listAccessibleConfigurations,
listRegisteredIds,
invalidateAccessibleConfigurations,
};
}

View file

@ -0,0 +1,177 @@
import { EModelEndpoint } from 'librechat-data-provider';
import type { AppConfig } from '@librechat/data-schemas';
import { CodeEnvironmentValidationError } from './environments';
import { createCodeEnvironmentHttpHandlers } from './http';
function response() {
const res = {
statusCode: 200,
body: undefined as unknown,
status(code: number) {
this.statusCode = code;
return this;
},
json(body: unknown) {
this.body = body;
return this;
},
};
return res;
}
describe('code environment HTTP handlers', () => {
test('returns 400 when registration has no request body', async () => {
const register = jest.fn();
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn(),
registry: { register, listAccessible: jest.fn() },
});
const res = response();
await handlers.register(
{ user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' }, body: null } as never,
res as never,
);
expect(res.statusCode).toBe(400);
expect(register).not.toHaveBeenCalled();
});
test('registers against an operator-configured control plane and ignores client URLs', async () => {
const register = jest.fn().mockResolvedValue({
resourceId: '68b2f0c498f24c1e78fa0111',
id: 'personal-vm',
name: 'Personal VM',
type: 'attached',
});
const appConfig = {
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
allowedEnvironments: ['user'],
environments: [
{
id: 'shared-code-api',
name: 'Shared Code API',
type: 'attached',
baseURL: 'https://code.librechat.example',
owner: 'deployment',
pairing: { workerId: 'deployment-worker', tokenEnv: 'CODE_ADMIN_TOKEN' },
},
],
},
},
},
} as AppConfig;
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue(appConfig),
registry: { register, listAccessible: jest.fn() },
createEnvironmentId: () => 'personal-vm',
});
const req = {
user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
body: {
name: 'Personal VM',
controlPlaneId: 'shared-code-api',
workerId: 'attacker-worker',
baseURL: 'https://attacker.example',
},
};
const res = response();
await handlers.register(req as never, res as never);
expect(res.statusCode).toBe(201);
expect(register).toHaveBeenCalledWith({
actor: {
userId: '68b2f0c498f24c1e78fa0001',
role: 'USER',
idOnTheSource: null,
},
environment: {
id: 'personal-vm',
name: 'Personal VM',
type: 'attached',
baseURL: 'https://code.librechat.example',
controlPlaneId: 'shared-code-api',
workerId: 'deployment-worker',
},
});
});
test('returns a generic 500 for operational registration failures', async () => {
const register = jest.fn().mockRejectedValue(new Error('mongo connection details'));
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue({
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
environments: [
{
id: 'shared-code-api',
name: 'Shared Code API',
type: 'attached',
baseURL: 'https://code.librechat.example',
owner: 'deployment',
pairing: { workerId: 'deployment-worker' },
},
],
},
},
},
} as AppConfig),
registry: { register, listAccessible: jest.fn() },
});
const res = response();
await handlers.register(
{
user: { id: '68b2f0c498f24c1e78fa0001' },
body: { name: 'Personal VM', controlPlaneId: 'shared-code-api' },
} as never,
res as never,
);
expect(res.statusCode).toBe(500);
expect(res.body).toEqual({ error: 'Code environment registration failed' });
});
test('returns 400 for validated registration input failures', async () => {
const register = jest
.fn()
.mockRejectedValue(new CodeEnvironmentValidationError('Code environment id is invalid'));
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue({
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
environments: [
{
id: 'shared-code-api',
name: 'Shared Code API',
type: 'attached',
baseURL: 'https://code.librechat.example',
owner: 'deployment',
pairing: { workerId: 'deployment-worker' },
},
],
},
},
},
} as AppConfig),
registry: { register, listAccessible: jest.fn() },
});
const res = response();
await handlers.register(
{
user: { id: '68b2f0c498f24c1e78fa0001' },
body: { name: 'Personal VM', controlPlaneId: 'shared-code-api' },
} as never,
res as never,
);
expect(res.statusCode).toBe(400);
expect(res.body).toEqual({ error: 'Code environment id is invalid' });
});
});

View file

@ -0,0 +1,129 @@
import { nanoid } from 'nanoid';
import { EModelEndpoint } from 'librechat-data-provider';
import { logger, type AppConfig } from '@librechat/data-schemas';
import type { Response } from 'express';
import type {
CodeEnvironmentPrincipalContext,
CodeEnvironmentRegistration,
CodeEnvironmentSummary,
} from './environments';
import type { GetAppConfigOptions } from '~/app/service';
import type { ServerRequest } from '~/types/http';
import { CodeEnvironmentValidationError } from './environments';
type Registry = {
register: (params: {
actor: CodeEnvironmentPrincipalContext;
environment: CodeEnvironmentRegistration;
}) => Promise<CodeEnvironmentSummary>;
listAccessible: (actor: CodeEnvironmentPrincipalContext) => Promise<CodeEnvironmentSummary[]>;
};
type StatefulCodeConfig = NonNullable<
NonNullable<AppConfig['endpoints']>[EModelEndpoint.agents]
>['statefulCodeSessions'];
type ConfiguredCodeEnvironment = NonNullable<
NonNullable<StatefulCodeConfig>['environments']
>[number];
export interface CodeEnvironmentHttpDeps {
getAppConfig: (options: GetAppConfigOptions) => Promise<AppConfig>;
registry: Registry;
createEnvironmentId?: () => string;
}
function actor(req: ServerRequest): CodeEnvironmentPrincipalContext | null {
if (!req.user?.id) return null;
return {
userId: req.user.id,
role: req.user.role ?? null,
idOnTheSource: req.user.idOnTheSource ?? null,
};
}
function configuredControlPlane(
appConfig: AppConfig,
controlPlaneId: string,
): ConfiguredCodeEnvironment | undefined {
return appConfig.endpoints?.[EModelEndpoint.agents]?.statefulCodeSessions?.environments?.find(
(environment) =>
environment.id === controlPlaneId &&
environment.type === 'attached' &&
environment.owner === 'deployment' &&
environment.pairing != null,
);
}
export function createCodeEnvironmentHttpHandlers(deps: CodeEnvironmentHttpDeps): {
list: (req: ServerRequest, res: Response) => Promise<Response>;
register: (req: ServerRequest, res: Response) => Promise<Response>;
} {
const createEnvironmentId = deps.createEnvironmentId ?? (() => `code-${nanoid(20)}`);
async function list(req: ServerRequest, res: Response): Promise<Response> {
const principal = actor(req);
if (principal == null) {
return res.status(401).json({ error: 'Authentication required' });
}
const environments = await deps.registry.listAccessible(principal);
return res.status(200).json({ environments });
}
async function register(req: ServerRequest, res: Response): Promise<Response> {
const principal = actor(req);
if (principal == null) {
return res.status(401).json({ error: 'Authentication required' });
}
const body =
typeof req.body === 'object' && req.body != null
? (req.body as unknown as Record<string, unknown>)
: {};
const name = typeof body.name === 'string' ? body.name.trim() : '';
const controlPlaneId =
typeof body.controlPlaneId === 'string' ? body.controlPlaneId.trim() : '';
if (!name || !controlPlaneId) {
return res.status(400).json({
error: 'name and controlPlaneId are required',
});
}
/** Control-plane destinations are deployment policy. Client-provided URLs
* are deliberately ignored to prevent an authenticated SSRF primitive. */
const appConfig = await deps.getAppConfig({ baseOnly: true });
const controlPlane = configuredControlPlane(appConfig, controlPlaneId);
if (controlPlane == null) {
return res.status(404).json({ error: 'Code control plane was not found' });
}
try {
const environment = await deps.registry.register({
actor: principal,
environment: {
id: createEnvironmentId(),
name,
type: 'attached',
baseURL: controlPlane.baseURL,
controlPlaneId,
workerId: controlPlane.pairing?.workerId,
},
});
return res.status(201).json({ environment });
} catch (error) {
const duplicate =
typeof error === 'object' &&
error != null &&
'code' in error &&
(error as { code?: number }).code === 11000;
if (duplicate) {
return res.status(409).json({ error: 'Code environment already exists' });
}
if (error instanceof CodeEnvironmentValidationError) {
return res.status(400).json({ error: error.message });
}
logger.error('[codeEnvironments] registration failed:', error);
return res.status(500).json({ error: 'Code environment registration failed' });
}
}
return { list, register };
}

View file

@ -0,0 +1,3 @@
export * from './environments';
export * from './http';
export * from './config';