LibreChat/packages/api/src/admin/code.ts
Marco Beretta 9adabde72e
Some checks are pending
Backend Unit Tests / Build packages (push) Waiting to run
Backend Unit Tests / Codegraph select (push) Waiting to run
Backend Unit Tests / TypeScript type checks (push) Blocked by required conditions
Backend Unit Tests / Circular dependency checks (push) Waiting to run
Backend Unit Tests / Tests: api (shard 1/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 2/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 3/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: data-provider (push) Blocked by required conditions
Backend Unit Tests / Tests: data-schemas (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 1/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 2/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 3/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 4/4) (push) Blocked by required conditions
Codegraph E2E Votes / vote (full suite) (push) Waiting to run
Docker Dev Branch Images Build / publish (push) Waiting to run
Frontend Unit Tests / Client build recovery regression (push) Waiting to run
Frontend Unit Tests / Codegraph select (push) Waiting to run
Frontend Unit Tests / Build packages (push) Waiting to run
Frontend Unit Tests / TypeScript type checks (client) (push) Blocked by required conditions
Frontend Unit Tests / Tests: @librechat/chat (push) Blocked by required conditions
Frontend Unit Tests / Tests: @librechat/client (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 1/2) (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 2/2) (push) Blocked by required conditions
Frontend Unit Tests / Vite build verification (push) Blocked by required conditions
Sync Locize Translations & Create Translation PR / Sync Translation Keys with Locize (push) Waiting to run
Sync Locize Translations & Create Translation PR / Create Translation PR on Version Published (push) Blocked by required conditions
🗂️ feat: Audit MCP, Code Worker, Langfuse, Skill Credential, Passkey and Audit Log Access (#17054)
* fix: Remove Group Dependents Before Deleting the Group

* feat: Audit Code Worker Pairing and Langfuse Connection Changes

* feat: Audit Skill Sync Credential Changes

* feat: Audit Passkey Enrolment and Removal

* feat: Audit Audit Log Reads and CSV Exports

* feat: Audit Audit Log Retention Purges

* feat: Audit MCP Server Create, Update and Delete

* fix: Keep Purge Result When the Purge Audit Write Fails

* test: Cover Admin Integration Audit Scenarios

* fix: Tighten Admin Integration Audit Scope and Group Cleanup Order

* fix: Run Security Fences Before Awaiting Audit Writes

* fix: Move MCP Post-Commit Audit Ordering Into the Auditor and Audit Verify Reads

* fix: Fail Closed When Recording Audit Log Access

* fix: Audit Group Deletion Before the Cascade and Restore Dependents on Failure

* fix: Restore Only Config Overrides When Group Deletion Fails

* fix: Audit Worker Pairing and Export Before the Work and Append Failures

* fix: Record Group Deletion as Pending Without Delaying Revocation

* fix: Skip Config Restore When a Concurrent Delete Removed the Group

* fix: Restore Group Config When the Existence Recheck Fails

* fix: Keep Group Config Restricted When Delete State Is Unknown

* fix: Record Worker Pairing and Revocation as Pending Until Confirmed

* fix: Deliver the Pairing Code Before the Terminal Audit Write

* test: Assert Pairing Code Delivery Precedes the Terminal Audit Write

* fix: Send Revocation and Group Deletion Responses Before the Terminal Audit Write

* fix: Snapshot Group Config Before the Destructive Cascade Step

* refactor: Type the Group Config Snapshot Dependency Without Mongoose Shapes

* fix: Fence Shared MCP Users Before the Deletion Audit and Correlate Audit Attempts

* fix: Diff MCP Server Audits Against the Committed Config

* fix: Read the Committed MCP Config at Commit Time for the Audit Diff

* refactor: Start the Committed MCP Config Read Inside the Auditor

* fix: Audit Langfuse Patches When Activation Fails and Surface Failed Group Config Restores

* fix: Record Member Removals When Group Deletion Completes After a Failed Restore

* test: Serve the Committed Config on the MCP Update Audit Reread

* fix: Audit the Group Returned by the Compensating Deletion

* fix: Keep Member Removal Audits Fail-Open During Group Deletion

* fix: Retry ACL Cleanup After a Compensating Group Deletion

* fix: Mark Unavailable Audit Detail and Order Member Removals After the Pending Deletion

* fix: Guard Synchronous Committed-Config Read Failures in the MCP Auditor

* fix: Return the Persisted MCP Config and Audit Commits That Outlive Cache Invalidation

* style: Sort Imports in MCP Audit Files

* style: Sort Imports After Restack

* fix: Audit MCP Commits That Outlive Any Post-Write Step and Pend Audit Exports Until Complete

* test: Provide the Fail-Closed Setting in the Code Route Mock

* fix: Refresh MCP Read Caches When a Repository Step Fails After the Write

* fix: Finish Audit Exports on Response Completion and Keep Error Details Out of Messages and Logs

* fix: Watch Response Completion Before the Truncation Footer Write

* fix: Skip Audit for No-op MCP Deletes and Close Remaining Post-Failure Audit Gaps

* fix: Keep Causes Out of Structured Logs and Treat a Lost Compensating Delete as Not Found

* fix: Mark Failed MCP Post-Commit Steps and Null Langfuse Activation in Audits
2026-10-15 00:30:26 +02:00

307 lines
11 KiB
TypeScript

import { EModelEndpoint, isSecureCodeEnvironmentControlURL } from 'librechat-data-provider';
import type { AppConfig } from '@librechat/data-schemas';
import type { Response } from 'express';
import type { GetAppConfigOptions } from '~/app/service';
import type { ServerRequest } from '~/types/http';
import type { RecordAuditEntry } from './audit';
import { getCodeApiTenantId } from '~/auth/codeapi';
import { createAdminAuditEmitter } from './audit';
const CODE_BRIDGE_REQUEST_TIMEOUT_MS = 10_000;
type AgentsEndpointConfig = NonNullable<AppConfig['endpoints']>[EModelEndpoint.agents];
type StatefulCodeSessionsConfig = NonNullable<
NonNullable<AgentsEndpointConfig>['statefulCodeSessions']
>;
type ConfiguredCodeEnvironment = NonNullable<StatefulCodeSessionsConfig['environments']>[number];
type FetchImpl = (
input: Parameters<typeof fetch>[0],
init?: Parameters<typeof fetch>[1],
) => ReturnType<typeof fetch>;
interface CodePairingResponse {
protocolVersion: number;
workerId: string;
code: string;
expiresAt: string;
}
interface CodeRevocationResponse {
protocolVersion: number;
revoked: true;
}
export interface AdminCodeEnvironmentDeps {
getAppConfig: (options: GetAppConfigOptions) => Promise<AppConfig>;
resolveTenantId?: (req: ServerRequest) => string;
readSecret?: (name: string) => string | undefined;
fetchImpl?: FetchImpl;
/** Optional audit emission for pairing and revocation; fail-open unless `auditFailClosed`. */
recordAuditEntry?: RecordAuditEntry;
auditFailClosed?: boolean;
}
function environmentId(req: ServerRequest): string {
const params = req.params as { environmentId?: string };
return params.environmentId?.trim() ?? '';
}
function findEnvironment(appConfig: AppConfig, id: string): ConfiguredCodeEnvironment | undefined {
return appConfig.endpoints?.[EModelEndpoint.agents]?.statefulCodeSessions?.environments?.find(
(environment) => environment.id === id,
);
}
function pairingConfig(environment: ConfiguredCodeEnvironment):
| {
workerId: string;
tokenEnv: string;
}
| undefined {
if (environment.type !== 'attached' || environment.owner !== 'deployment') {
return undefined;
}
const pairing = environment.pairing;
if (pairing?.workerId == null) {
return undefined;
}
return { workerId: pairing.workerId, tokenEnv: pairing.tokenEnv };
}
function bridgeUrl(environment: ConfiguredCodeEnvironment, path: string): string {
return `${environment.baseURL.trim().replace(/\/+$/, '')}${path}`;
}
function validPairingResponse(value: unknown, workerId: string): value is CodePairingResponse {
if (typeof value !== 'object' || value == null) return false;
const response = value as Partial<CodePairingResponse>;
const expiresAt = typeof response.expiresAt === 'string' ? Date.parse(response.expiresAt) : NaN;
return (
response.protocolVersion === 1 &&
response.workerId === workerId &&
typeof response.code === 'string' &&
/^[A-Za-z0-9_-]{32}$/.test(response.code) &&
Number.isFinite(expiresAt) &&
expiresAt > Date.now()
);
}
function validRevocationResponse(value: unknown): value is CodeRevocationResponse {
if (typeof value !== 'object' || value == null) return false;
const response = value as Partial<CodeRevocationResponse>;
return response.protocolVersion === 1 && response.revoked === true;
}
export function createAdminCodeEnvironmentHandlers(deps: AdminCodeEnvironmentDeps): {
createPairing: (req: ServerRequest, res: Response) => Promise<Response>;
revokeWorker: (req: ServerRequest, res: Response) => Promise<Response>;
} {
const fetchImpl = deps.fetchImpl ?? fetch;
const resolveTenantId = deps.resolveTenantId ?? getCodeApiTenantId;
const emitAudit = createAdminAuditEmitter({
recordAuditEntry: deps.recordAuditEntry,
failClosed: deps.auditFailClosed,
logPrefix: '[adminCode]',
});
/** Revoking a worker removes access, and terminal entries record an outcome that already
* happened, so an audit outage blocks neither. */
const emitRevocationAudit = createAdminAuditEmitter({
recordAuditEntry: deps.recordAuditEntry,
logPrefix: '[adminCode]',
});
const readSecret =
deps.readSecret ??
((name: string) =>
Object.prototype.hasOwnProperty.call(process.env, name) ? process.env[name] : undefined);
async function resolve(
req: ServerRequest,
res: Response,
): Promise<
| {
id: string;
environment: ConfiguredCodeEnvironment;
pairing: { workerId: string; tokenEnv: string };
token: string;
}
| Response
> {
const id = environmentId(req);
/** Pairing credentials are deployment control-plane state. Resolve only
* YAML-backed configuration; writable database overrides must never
* choose tokenEnv or the outbound destination. */
const appConfig = await deps.getAppConfig({ baseOnly: true });
const environment = findEnvironment(appConfig, id);
if (environment == null) {
return res.status(404).json({ error: 'Code environment was not found' });
}
const pairing = pairingConfig(environment);
if (pairing == null) {
return res.status(409).json({ error: 'Code environment does not support pairing' });
}
if (!isSecureCodeEnvironmentControlURL(environment.baseURL)) {
return res.status(409).json({ error: 'Code environment pairing requires secure transport' });
}
const token = readSecret(pairing.tokenEnv)?.trim();
if (!token) {
return res.status(503).json({ error: 'Code environment pairing is not configured' });
}
return { id, environment, pairing, token };
}
async function createPairing(req: ServerRequest, res: Response): Promise<Response> {
const resolved = await resolve(req, res);
if ('statusCode' in resolved) return resolved;
let tenantId: string;
try {
tenantId = resolveTenantId(req);
} catch {
return res.status(503).json({ error: 'Code environment tenant context is unavailable' });
}
/**
* Recorded as `pending` before the bridge mints the one-time code, so no audit latency
* sits between minting and delivering it and a rejected pairing is never counted as
* granted; `success` is appended once the bridge response validates and `failure`
* otherwise. Workers belong to the deployment's YAML environments, so entries go to
* the platform chain.
*/
const pairingEvent = {
action: 'code_worker.paired' as const,
severity: 'warning' as const,
target: { type: 'code_worker', id: resolved.pairing.workerId, name: resolved.id },
tenantId: undefined,
};
const pairingMetadata = { environmentId: resolved.id, boundTenantId: tenantId };
await emitAudit(req, { ...pairingEvent, outcome: 'pending', metadata: pairingMetadata });
const pairingFailed = async (code: string) => {
await emitRevocationAudit(req, {
...pairingEvent,
outcome: 'failure',
metadata: { ...pairingMetadata, code },
});
};
try {
const response = await fetchImpl(bridgeUrl(resolved.environment, '/bridge/pairings'), {
method: 'POST',
headers: {
Authorization: `Bearer ${resolved.token}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
workerId: resolved.pairing.workerId,
binding: {
tenantId,
principal: { type: 'deployment', id: resolved.id },
},
}),
redirect: 'error',
signal: AbortSignal.timeout(CODE_BRIDGE_REQUEST_TIMEOUT_MS),
});
if (!response.ok) {
await pairingFailed('bridge_rejected');
return res.status(502).json({
error: 'Code API rejected the pairing request',
upstreamStatus: response.status,
});
}
const payload = (await response.json()) as unknown;
if (!validPairingResponse(payload, resolved.pairing.workerId)) {
await pairingFailed('invalid_response');
return res.status(502).json({ error: 'Code API returned an invalid pairing response' });
}
/** The code is delivered first: it expires, so audit latency must not sit in front of it. */
res.status(200).json({
environmentId: resolved.id,
workerId: payload.workerId,
code: payload.code,
expiresAt: payload.expiresAt,
});
await emitRevocationAudit(req, { ...pairingEvent, metadata: pairingMetadata });
return res;
} catch (error) {
const timedOut = error instanceof Error && error.name === 'TimeoutError';
await pairingFailed(timedOut ? 'timeout' : 'request_failed');
return res.status(timedOut ? 504 : 502).json({
error: timedOut ? 'Code API pairing request timed out' : 'Code API pairing request failed',
});
}
}
async function revokeWorker(req: ServerRequest, res: Response): Promise<Response> {
const resolved = await resolve(req, res);
if ('statusCode' in resolved) return resolved;
/**
* Recorded as `pending` without being awaited, so audit latency never delays the
* revocation; later entries wait for it to keep the chain ordered. `success` is
* appended once the bridge acknowledges and `failure` otherwise.
*/
const revokeEvent = {
action: 'code_worker.revoked' as const,
severity: 'warning' as const,
target: { type: 'code_worker', id: resolved.pairing.workerId, name: resolved.id },
tenantId: undefined,
};
const revokeMetadata = { environmentId: resolved.id };
const attempt = emitRevocationAudit(req, {
...revokeEvent,
outcome: 'pending',
metadata: revokeMetadata,
});
const revokeSettled = async (outcome: 'success' | 'failure', code?: string) => {
await attempt;
await emitRevocationAudit(req, {
...revokeEvent,
outcome,
metadata: code ? { ...revokeMetadata, code } : revokeMetadata,
});
};
const revokeFailed = (code: string) => revokeSettled('failure', code);
try {
const workerId = encodeURIComponent(resolved.pairing.workerId);
const response = await fetchImpl(
bridgeUrl(resolved.environment, `/bridge/workers/${workerId}/revoke`),
{
method: 'POST',
headers: {
Authorization: `Bearer ${resolved.token}`,
'Content-Type': 'application/json',
},
body: '{}',
redirect: 'error',
signal: AbortSignal.timeout(CODE_BRIDGE_REQUEST_TIMEOUT_MS),
},
);
if (!response.ok) {
await revokeFailed('bridge_rejected');
return res.status(502).json({
error: 'Code API rejected the revocation request',
upstreamStatus: response.status,
});
}
const payload = (await response.json()) as unknown;
if (!validRevocationResponse(payload)) {
await revokeFailed('invalid_response');
return res.status(502).json({ error: 'Code API returned an invalid revocation response' });
}
res.status(200).json({
environmentId: resolved.id,
workerId: resolved.pairing.workerId,
revoked: true,
});
await revokeSettled('success');
return res;
} catch (error) {
const timedOut = error instanceof Error && error.name === 'TimeoutError';
await revokeFailed(timedOut ? 'timeout' : 'request_failed');
return res.status(timedOut ? 504 : 502).json({
error: timedOut
? 'Code API revocation request timed out'
: 'Code API revocation request failed',
});
}
}
return { createPairing, revokeWorker };
}