🛂 feat: Add Configurable BYOM Enrollment Policy (#15673)

This commit is contained in:
Danny Avila 2026-09-06 15:04:43 -04:00 • committed by GitHub
parent 84851d8655
commit 8f6efaf6ed
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 297 additions and 135 deletions

View file

@ -566,6 +566,14 @@ endpoints:
# # (optional) Limit the workspace scopes users may select. Omit to allow all three.
# statefulCodeSessions:
# allowedEnvironments: ["user", "agent-user", "conversation"]
# # Personal BYOM enrollment. Requires allowPrincipalWorkers on a control plane.
# # Omitted values default to enabled and five registered environments per user.
# # Principal config overrides may tighten, but cannot raise, this ceiling.
# # Lowering the limit, or disabling enrollment, does not revoke existing machines.
# # This counts registered environments across control planes, not online workers.
# principalWorkers:
# enabled: true
# maxPerUser: 25
# # Route an agent to an operator-managed Code API or to a Code API whose
# # `remote-bridge` backend leases work to an outbound @librechat/code worker.
# environments:

View file

@ -0,0 +1,27 @@
import { resolveCodeWorkerEnrollmentLimit } from './enrollment';
describe('personal worker enrollment policy', () => {
test.each([
[undefined, undefined, 5],
[{ maxPerUser: 100 }, undefined, 100],
[{ maxPerUser: 100 }, { maxPerUser: 20 }, 20],
[{ maxPerUser: 10 }, { maxPerUser: 100 }, 10],
[undefined, { maxPerUser: 100 }, 5],
[{ enabled: false }, { enabled: true }, 0],
[{ enabled: true }, { enabled: false }, 0],
[{ maxPerUser: 0 }, { maxPerUser: 100 }, 0],
[{ maxPerUser: 100 }, { maxPerUser: 0 }, 0],
[{ maxPerUser: -1 }, undefined, 0],
[{ maxPerUser: Infinity }, undefined, 0],
[undefined, { maxPerUser: NaN }, 0],
[undefined, { maxPerUser: 1.5 }, 0],
[{ maxPerUser: Number.MAX_SAFE_INTEGER + 1 }, undefined, 0],
])('resolves deployment %j and principal %j to %i', (deployment, effective, expected) => {
expect(resolveCodeWorkerEnrollmentLimit(deployment, effective)).toBe(expected);
});
test('supports a caller fallback without replacing an explicit deployment policy', () => {
expect(resolveCodeWorkerEnrollmentLimit(undefined, undefined, 3)).toBe(3);
expect(resolveCodeWorkerEnrollmentLimit({ maxPerUser: 10 }, undefined, 3)).toBe(10);
});
});

View file

@ -0,0 +1,26 @@
import type { CodeWorkerEnrollmentPolicy } from 'librechat-data-provider';
/** A principal override can restrict enrollment, never expand deployment authority.
* Missing effective fields inherit the deployment policy. Invalid programmatic
* limits fail closed, even when the caller did not pass through config validation.
*/
export function resolveCodeWorkerEnrollmentLimit(
deployment?: CodeWorkerEnrollmentPolicy,
effective?: CodeWorkerEnrollmentPolicy,
fallback = 5,
): number {
if (deployment?.enabled === false || effective?.enabled === false) {
return 0;
}
const ceiling = deployment?.maxPerUser ?? fallback;
const requested = effective?.maxPerUser ?? ceiling;
if (
!Number.isSafeInteger(ceiling) ||
!Number.isSafeInteger(requested) ||
ceiling < 0 ||
requested < 0
) {
return 0;
}
return Math.min(ceiling, requested);
}

View file

@ -280,39 +280,45 @@ describe('code environment registry', () => {
singleSpy.mockRestore();
});
test('atomically limits concurrent environment registrations for one owner', async () => {
await mongoose.models.CodeEnvironment.createCollection();
await expect(mongoose.models.CodeEnvironment.collection.indexes()).resolves.toEqual([
expect.objectContaining({ name: '_id_' }),
]);
const registry = createCodeEnvironmentRegistry(mongoose);
const ownerId = new Types.ObjectId();
test.each([2, 12])(
'atomically limits concurrent registrations to %i across replicas',
async (maxOwned) => {
await mongoose.models.CodeEnvironment.createCollection();
await expect(mongoose.models.CodeEnvironment.collection.indexes()).resolves.toEqual([
expect.objectContaining({ name: '_id_' }),
]);
const registries = [
createCodeEnvironmentRegistry(mongoose),
createCodeEnvironmentRegistry(mongoose),
];
const ownerId = new Types.ObjectId();
const results = await Promise.allSettled(
['quota-one', 'quota-two', 'quota-three'].map((id) =>
registry.register({
actor: { userId: ownerId, role: 'USER', idOnTheSource: null },
environment: {
id,
name: id,
type: 'attached',
baseURL: 'https://code.example.com',
controlPlaneId: 'shared-code-api',
},
maxOwned: 2,
} as never),
),
);
const results = await Promise.allSettled(
Array.from({ length: maxOwned + 4 }, (_, index) =>
registries[index % registries.length].register({
actor: { userId: ownerId, role: 'USER', idOnTheSource: null },
environment: {
id: `quota-${index}`,
name: `quota-${index}`,
type: 'attached',
baseURL: 'https://code.example.com',
controlPlaneId: 'shared-code-api',
},
maxOwned,
} as never),
),
);
expect(results.filter(({ status }) => status === 'fulfilled')).toHaveLength(2);
expect(results.filter(({ status }) => status === 'rejected')).toHaveLength(1);
expect(results.find(({ status }) => status === 'rejected')).toMatchObject({
reason: { name: 'CodeEnvironmentLimitError' },
});
await expect(
mongoose.models.CodeEnvironment.countDocuments({ createdBy: ownerId }),
).resolves.toBe(2);
});
expect(results.filter(({ status }) => status === 'fulfilled')).toHaveLength(maxOwned);
expect(results.filter(({ status }) => status === 'rejected')).toHaveLength(4);
expect(results.find(({ status }) => status === 'rejected')).toMatchObject({
reason: { name: 'CodeEnvironmentLimitError' },
});
await expect(
mongoose.models.CodeEnvironment.countDocuments({ createdBy: ownerId }),
).resolves.toBe(maxOwned);
},
);
test('keeps a user-bound worker private even if its ACL is granted to a role', async () => {
const registry = createCodeEnvironmentRegistry(mongoose);

View file

@ -330,109 +330,151 @@ describe('code environment HTTP handlers', () => {
});
});
test('pairs a generated worker to the authenticated user and persists its private route', async () => {
const register = jest.fn().mockResolvedValue({
resourceId: '68b2f0c498f24c1e78fa0111',
id: 'code-generated',
name: 'Personal VM',
type: 'attached',
});
const fetchImpl = jest.fn().mockResolvedValue({
ok: true,
json: jest.fn().mockResolvedValue({
protocolVersion: 1,
workerId: 'code-generated',
code: 'a'.repeat(32),
expiresAt: new Date(Date.now() + 60_000).toISOString(),
}),
});
const appConfig = {
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
allowedEnvironments: ['user'],
environments: [
{
id: 'shared-code-api',
name: 'Shared Code API',
type: 'attached',
baseURL: 'https://code.librechat.example/v1',
owner: 'deployment',
pairing: {
allowPrincipalWorkers: true,
tokenEnv: 'CODE_ADMIN_TOKEN',
},
},
],
},
},
},
} as AppConfig;
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn().mockResolvedValue(appConfig),
registry: { register, listAccessible: jest.fn(), remove: jest.fn() },
createEnvironmentId: () => 'code-generated',
readSecret: jest.fn(() => 'administrator-token'),
resolveTenantId: jest.fn(() => 'tenant-1'),
principalAuthEnabled: jest.fn(() => true),
principalAuthReady: jest.fn(),
fetchImpl,
});
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.pair(req as never, res as never);
expect(res.statusCode).toBe(201);
expect(fetchImpl).toHaveBeenCalledWith(
'https://code.librechat.example/v1/bridge/pairings',
expect.objectContaining({
method: 'POST',
headers: expect.objectContaining({ Authorization: 'Bearer administrator-token' }),
body: JSON.stringify({
workerId: 'code-generated',
binding: {
tenantId: 'tenant-1',
principal: { type: 'user', id: '68b2f0c498f24c1e78fa0001' },
},
}),
}),
);
expect(register).toHaveBeenCalledWith({
actor: {
userId: '68b2f0c498f24c1e78fa0001',
role: 'USER',
idOnTheSource: null,
},
maxOwned: 5,
environment: {
test.each([
[undefined, undefined, 5],
[{ maxPerUser: 100 }, { maxPerUser: 100 }, 100],
[{ maxPerUser: 100 }, { maxPerUser: 20 }, 20],
[{ maxPerUser: 10 }, { maxPerUser: 100 }, 10],
[{ enabled: false }, { enabled: true }, 0],
[{ maxPerUser: 10 }, { maxPerUser: 0 }, 0],
])(
'pairs with deployment %j and effective policy %j (limit %i)',
async (deployment, effective, limit) => {
const register = jest.fn().mockResolvedValue({
resourceId: '68b2f0c498f24c1e78fa0111',
id: 'code-generated',
name: 'Personal VM',
type: 'attached' as const,
baseURL: 'https://code.librechat.example/v1',
workerId: 'code-generated',
controlPlaneId: 'shared-code-api',
revocationTokenEnv: 'CODE_ADMIN_TOKEN',
workerPrincipal: { type: 'user', id: '68b2f0c498f24c1e78fa0001' },
},
});
expect(res.body).toEqual({
environment: expect.objectContaining({ id: 'code-generated' }),
pairing: expect.objectContaining({
workerId: 'code-generated',
code: 'a'.repeat(32),
endpoint: 'https://code.librechat.example/v1',
}),
});
});
type: 'attached',
});
const fetchImpl = jest.fn().mockResolvedValue({
ok: true,
json: jest.fn().mockResolvedValue({
protocolVersion: 1,
workerId: 'code-generated',
code: 'a'.repeat(32),
expiresAt: new Date(Date.now() + 60_000).toISOString(),
}),
});
const appConfig = {
endpoints: {
[EModelEndpoint.agents]: {
statefulCodeSessions: {
allowedEnvironments: ['user'],
environments: [
{
id: 'shared-code-api',
name: 'Shared Code API',
type: 'attached',
baseURL: 'https://code.librechat.example/v1',
owner: 'deployment',
pairing: {
allowPrincipalWorkers: true,
tokenEnv: 'CODE_ADMIN_TOKEN',
},
},
],
},
},
},
} as AppConfig;
const handlers = createCodeEnvironmentHttpHandlers({
getAppConfig: jest.fn(
async (options) =>
({
...appConfig,
endpoints: {
...appConfig.endpoints,
agents: {
...appConfig.endpoints?.agents,
statefulCodeSessions: {
...appConfig.endpoints?.agents?.statefulCodeSessions,
principalWorkers: options?.baseOnly ? deployment : effective,
},
},
},
}) as AppConfig,
),
registry: {
register,
listAccessible: jest.fn().mockResolvedValue([{ id: 'existing-machine' }]),
remove: jest.fn(),
},
createEnvironmentId: () => 'code-generated',
readSecret: jest.fn(() => 'administrator-token'),
resolveTenantId: jest.fn(() => 'tenant-1'),
principalAuthEnabled: jest.fn(() => true),
principalAuthReady: jest.fn(),
fetchImpl,
});
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.pair(req as never, res as never);
if (limit === 0) {
expect(res.statusCode).toBe(403);
expect(fetchImpl).not.toHaveBeenCalled();
expect(register).not.toHaveBeenCalled();
const discovery = response();
await handlers.list(req as never, discovery as never);
expect(discovery.statusCode).toBe(200);
expect(discovery.body).toEqual({
environments: [{ id: 'existing-machine' }],
controlPlanes: [],
});
return;
}
expect(res.statusCode).toBe(201);
expect(fetchImpl).toHaveBeenCalledWith(
'https://code.librechat.example/v1/bridge/pairings',
expect.objectContaining({
method: 'POST',
headers: expect.objectContaining({ Authorization: 'Bearer administrator-token' }),
body: JSON.stringify({
workerId: 'code-generated',
binding: {
tenantId: 'tenant-1',
principal: { type: 'user', id: '68b2f0c498f24c1e78fa0001' },
},
}),
}),
);
expect(register).toHaveBeenCalledWith({
actor: {
userId: '68b2f0c498f24c1e78fa0001',
role: 'USER',
idOnTheSource: null,
},
maxOwned: limit,
environment: {
id: 'code-generated',
name: 'Personal VM',
type: 'attached' as const,
baseURL: 'https://code.librechat.example/v1',
workerId: 'code-generated',
controlPlaneId: 'shared-code-api',
revocationTokenEnv: 'CODE_ADMIN_TOKEN',
workerPrincipal: { type: 'user', id: '68b2f0c498f24c1e78fa0001' },
},
});
expect(res.body).toEqual({
environment: expect.objectContaining({ id: 'code-generated' }),
pairing: expect.objectContaining({
workerId: 'code-generated',
code: 'a'.repeat(32),
endpoint: 'https://code.librechat.example/v1',
}),
});
},
);
test('revokes an upstream pairing when the atomic owner quota is exhausted', async () => {
const fetchImpl = jest.fn(

View file

@ -37,6 +37,7 @@ import {
CodeEnvironmentSettingsValidationError,
validateCodeEnvironmentUserSettings,
} from './settings';
import { resolveCodeWorkerEnrollmentLimit } from './enrollment';
import { getAppConfigOptionsFromUser } from '~/app/service';
type Registry = {
@ -196,7 +197,6 @@ export function createCodeEnvironmentHttpHandlers(deps: CodeEnvironmentHttpDeps)
const principalAuthEnabled = deps.principalAuthEnabled ?? isCodeApiJwtAuthEnabled;
const principalAuthReady = deps.principalAuthReady ?? assertCodeApiJwtSigningReady;
const principalIsActive = deps.principalIsActive ?? (async () => true);
const maxPrincipalEnvironments = deps.maxPrincipalEnvironments ?? 5;
async function list(req: ServerRequest, res: Response): Promise<Response> {
const principal = actor(req);
@ -205,10 +205,11 @@ export function createCodeEnvironmentHttpHandlers(deps: CodeEnvironmentHttpDeps)
}
let details: AccessibleCodeEnvironmentDetails;
let appConfig: AppConfig;
let deploymentConfig: AppConfig;
try {
const principals = await deps.registry.resolvePrincipals?.(principal);
const resolvedPrincipal = principals == null ? principal : { ...principal, principals };
[details, appConfig] = await Promise.all([
[details, appConfig, deploymentConfig] = await Promise.all([
deps.registry.listAccessibleDetails?.(resolvedPrincipal) ??
Promise.all([
deps.registry.listAccessible(resolvedPrincipal),
@ -220,6 +221,7 @@ export function createCodeEnvironmentHttpHandlers(deps: CodeEnvironmentHttpDeps)
failClosed: true,
skipRuntimeAugmentation: true,
}),
deps.getAppConfig({ baseOnly: true }),
]);
} catch (error) {
logger.error('[codeEnvironments] discovery policy resolution failed:', error);
@ -241,7 +243,15 @@ export function createCodeEnvironmentHttpHandlers(deps: CodeEnvironmentHttpDeps)
settings: configuration?.settings,
};
}),
controlPlanes: principalAuthEnabled() ? principalControlPlanes(appConfig) : [],
controlPlanes:
principalAuthEnabled() &&
resolveCodeWorkerEnrollmentLimit(
deploymentConfig.endpoints?.agents?.statefulCodeSessions?.principalWorkers,
appConfig.endpoints?.agents?.statefulCodeSessions?.principalWorkers,
deps.maxPrincipalEnvironments,
) > 0
? principalControlPlanes(appConfig)
: [],
});
}
@ -395,6 +405,14 @@ export function createCodeEnvironmentHttpHandlers(deps: CodeEnvironmentHttpDeps)
if (authorizedControlPlane == null || controlPlane == null) {
return res.status(404).json({ error: 'Principal code control plane was not found' });
}
const maxPrincipalEnvironments = resolveCodeWorkerEnrollmentLimit(
deploymentConfig.endpoints?.agents?.statefulCodeSessions?.principalWorkers,
effectiveConfig.endpoints?.agents?.statefulCodeSessions?.principalWorkers,
deps.maxPrincipalEnvironments,
);
if (maxPrincipalEnvironments === 0) {
return res.status(403).json({ error: 'Personal code worker enrollment is disabled' });
}
const tokenEnv = controlPlane.pairing?.tokenEnv;
const token = tokenEnv != null ? readSecret(tokenEnv)?.trim() : undefined;
if (!token) {

View file

@ -449,6 +449,28 @@ describe('agentsEndpointSchema', () => {
expect(result.success).toBe(true);
});
it.each([0, 5, 1000])('accepts a personal worker ceiling of %i', (maxPerUser) => {
const principalWorkers = { enabled: true, maxPerUser };
const result = agentsEndpointSchema.parse({
statefulCodeSessions: { allowedEnvironments: ['user'], principalWorkers },
});
expect(result.statefulCodeSessions?.principalWorkers).toEqual(principalWorkers);
});
it.each([-1, 0.5, Infinity, Number.MAX_SAFE_INTEGER + 1])(
'rejects invalid personal worker ceiling %s',
(maxPerUser) => {
expect(
agentsEndpointSchema.safeParse({
statefulCodeSessions: {
allowedEnvironments: ['user'],
principalWorkers: { maxPerUser },
},
}).success,
).toBe(false);
},
);
it('accepts uniquely named execution environments with exactly one default', () => {
const result = agentsEndpointSchema.safeParse({
statefulCodeSessions: {

View file

@ -1147,6 +1147,10 @@ export const codeEnvironmentUserSettingsSchema = z
export type CodeEnvironmentUserSettings = z.infer<typeof codeEnvironmentUserSettingsSchema>;
export type CodeWorkerEnrollmentPolicy = NonNullable<
NonNullable<z.infer<typeof agentsEndpointSchema>['statefulCodeSessions']>['principalWorkers']
>;
export const agentsEndpointSchema = baseEndpointSchema
.omit({ baseURL: true })
.merge(
@ -1187,6 +1191,15 @@ export const agentsEndpointSchema = baseEndpointSchema
statefulCodeSessions: z
.object({
allowedEnvironments: z.array(z.enum(STATEFUL_CODE_ENVIRONMENTS)).min(1),
/** Server-only personal worker enrollment policy. Effective principal
* policy may tighten, but never raise, the deployment ceiling. */
principalWorkers: z
.object({
enabled: z.boolean().optional(),
/** Defaults to five. Zero disables enrollment; existing machines remain usable. */
maxPerUser: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER).optional(),
})
.optional(),
/** Operator-managed execution environments. Attached entries route to a
* Code API deployment backed by an outbound librechat-code worker. */
environments: z