From 8f6efaf6edf71b576f09c42aba67162f5cb8d172 Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Sun, 6 Sep 2026 15:04:43 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=9B=82=20feat:=20Add=20Configurable=20BYO?= =?UTF-8?q?M=20Enrollment=20Policy=20(#15673)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- librechat.example.yaml | 8 + packages/api/src/code/enrollment.spec.ts | 27 ++ packages/api/src/code/enrollment.ts | 26 ++ .../src/code/environments.integration.spec.ts | 68 ++--- packages/api/src/code/http.spec.ts | 244 ++++++++++-------- packages/api/src/code/http.ts | 24 +- .../specs/config-schemas.spec.ts | 22 ++ packages/data-provider/src/config.ts | 13 + 8 files changed, 297 insertions(+), 135 deletions(-) create mode 100644 packages/api/src/code/enrollment.spec.ts create mode 100644 packages/api/src/code/enrollment.ts diff --git a/librechat.example.yaml b/librechat.example.yaml index 843a6dfd81..1ae4800d4e 100644 --- a/librechat.example.yaml +++ b/librechat.example.yaml @@ -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: diff --git a/packages/api/src/code/enrollment.spec.ts b/packages/api/src/code/enrollment.spec.ts new file mode 100644 index 0000000000..1b216c1b44 --- /dev/null +++ b/packages/api/src/code/enrollment.spec.ts @@ -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); + }); +}); diff --git a/packages/api/src/code/enrollment.ts b/packages/api/src/code/enrollment.ts new file mode 100644 index 0000000000..86f1bf8aec --- /dev/null +++ b/packages/api/src/code/enrollment.ts @@ -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); +} diff --git a/packages/api/src/code/environments.integration.spec.ts b/packages/api/src/code/environments.integration.spec.ts index 4672c1a30c..e869a35a12 100644 --- a/packages/api/src/code/environments.integration.spec.ts +++ b/packages/api/src/code/environments.integration.spec.ts @@ -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); diff --git a/packages/api/src/code/http.spec.ts b/packages/api/src/code/http.spec.ts index b0a16caffe..33b1eb0ddb 100644 --- a/packages/api/src/code/http.spec.ts +++ b/packages/api/src/code/http.spec.ts @@ -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( diff --git a/packages/api/src/code/http.ts b/packages/api/src/code/http.ts index 3c99ed3364..1c1610e331 100644 --- a/packages/api/src/code/http.ts +++ b/packages/api/src/code/http.ts @@ -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 { 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) { diff --git a/packages/data-provider/specs/config-schemas.spec.ts b/packages/data-provider/specs/config-schemas.spec.ts index 4e6eb14049..d9f14ead77 100644 --- a/packages/data-provider/specs/config-schemas.spec.ts +++ b/packages/data-provider/specs/config-schemas.spec.ts @@ -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: { diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts index f7a7989e49..89b3865cae 100644 --- a/packages/data-provider/src/config.ts +++ b/packages/data-provider/src/config.ts @@ -1147,6 +1147,10 @@ export const codeEnvironmentUserSettingsSchema = z export type CodeEnvironmentUserSettings = z.infer; +export type CodeWorkerEnrollmentPolicy = NonNullable< + NonNullable['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