Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import {
logger,
AUDIT_ACTIONS,
AUDIT_CATEGORIES,
AUDIT_OUTCOMES,
AUDIT_SEVERITIES,
AUDIT_ACTOR_TYPES,
MAX_AUDIT_EXPORT_ROWS,
MAX_AUDIT_LOG_LIMIT,
MAX_AUDIT_VERIFY_ROWS,
} from '@librechat/data-schemas';
import type {
AdminAuditLogEntry,
AuditAction,
AuditActorType,
AuditCategory,
AuditChainVerification,
AuditLogFilters,
AuditLogPage,
AuditOutcome,
AuditSeverity,
} from '@librechat/data-schemas';
import type { AuditMetadata } from '@librechat/data-schemas';
import type { Response } from 'express';
import type { ServerRequest } from '~/types/http';
import type { RecordAuditEntry } from './audit';
import { getSafeErrorMetadata } from '~/utils/errors';
import { createAdminAuditEmitter } from './audit';
const FORMULA_PREFIX = /^[=+\-@\t\r]/;
/** UTF-8 BOM, written first so Excel recognizes the encoding on import. Spelled
* as a Unicode escape so readers can see the constant in editors that hide the
* zero-width glyph. */
const CSV_BOM = '';
const VALID_ACTIONS = new Set<string>(AUDIT_ACTIONS);
const VALID_CATEGORIES = new Set<string>(AUDIT_CATEGORIES);
const VALID_OUTCOMES = new Set<string>(AUDIT_OUTCOMES);
const VALID_SEVERITIES = new Set<string>(AUDIT_SEVERITIES);
const VALID_ACTOR_TYPES = new Set<string>(AUDIT_ACTOR_TYPES);
/**
* Accepts `YYYY-MM-DD` (interpreted as UTC by the downstream Date parse) or a
* full ISO 8601 / RFC 3339 timestamp that includes either `Z` or a `±HH:MM`
* offset. Local-time strings without a zone are rejected so every input maps to
* an unambiguous instant.
*/
const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2}))?$/;
const DATE_ONLY_RE = /^\d{4}-\d{2}-\d{2}$/;
const OBJECT_ID_RE = /^[a-fA-F0-9]{24}$/;
export interface AdminAuditLogDeps {
listAuditLogPage: (
tenantId: string | undefined,
filters: AuditLogFilters,
) => Promise<AuditLogPage>;
findAuditLogEntry: (
tenantId: string | undefined,
id: string,
) => Promise<AdminAuditLogEntry | null>;
streamAuditLogEntries: (
tenantId: string | undefined,
filters: Omit<AuditLogFilters, 'offset' | 'limit' | 'cursor'>,
onEntry: (entry: AdminAuditLogEntry) => void | Promise<void>,
options?: { isCancelled?: () => boolean; maxRows?: number },
) => Promise<{ count: number; truncated: boolean }>;
verifyAuditChain: (
tenantId: string | undefined,
options?: { isCancelled?: () => boolean; maxRows?: number },
) => Promise<AuditChainVerification>;
/** Optional audit emission for reads and exports; fail-open unless `auditFailClosed`. */
recordAuditEntry?: RecordAuditEntry;
auditFailClosed?: boolean;
}
interface CallerContext {
userId: string;
role: string;
tenantId?: string;
}
function resolveCaller(req: ServerRequest): CallerContext | null {
const user = req.user;
if (!user) return null;
const userId = user._id?.toString() ?? user.id;
if (!userId || !user.role) return null;
return { userId, role: user.role, tenantId: user.tenantId };
}
function asStringArray(v: unknown): string[] | undefined {
if (v == null) return undefined;
if (Array.isArray(v)) return v.filter((x): x is string => typeof x === 'string');
if (typeof v === 'string') return [v];
return undefined;
}
type ParseResult<T> = { ok: true; value: T } | { ok: false; error: string };
/** Parses a repeatable enum filter (`?action=a&action=b`) against a whitelist. */
function parseEnumArray<T extends string>(
raw: unknown,
valid: Set<string>,
label: string,
): ParseResult<T[] | undefined> {
const arr = asStringArray(raw);
if (!arr || arr.length === 0) return { ok: true, value: undefined };
const invalid = arr.find((a) => !valid.has(a));
if (invalid != null) return { ok: false, error: `Unknown ${label}: ${invalid}` };
return { ok: true, value: arr as T[] };
}
function parseEnum<T extends string>(
raw: unknown,
valid: Set<string>,
label: string,
): ParseResult<T | undefined> {
if (raw == null || raw === '') return { ok: true, value: undefined };
if (typeof raw !== 'string') return { ok: false, error: `${label} must be a string` };
if (!valid.has(raw)) return { ok: false, error: `Unknown ${label}: ${raw}` };
return { ok: true, value: raw as T };
}
/**
* Parses a filter date. `boundary` controls how a bare `YYYY-MM-DD` is widened:
* `start` leaves it at 00:00:00.000Z (default for `from`), `end` snaps it to
* 23:59:59.999Z so `to=2025-01-15` includes everything on January 15 instead of
* cutting off at midnight. Full ISO timestamps are honored exactly.
*/
function parseIsoDate(
raw: unknown,
boundary: 'start' | 'end' = 'start',
): ParseResult<Date | undefined> {
if (raw == null || raw === '') return { ok: true, value: undefined };
if (typeof raw !== 'string') return { ok: false, error: 'Date must be a string' };
if (!ISO_DATE_RE.test(raw)) return { ok: false, error: 'Date must be ISO 8601' };
const d = new Date(raw);
if (Number.isNaN(d.getTime())) return { ok: false, error: 'Invalid date' };
/**
* `new Date('2025-02-31')` (and the timestamp form `2025-02-31T00:00:00Z`)
* silently normalizes to March 3 rather than throwing. Validate the literal
* calendar tokens — independent of any time/zone, so legitimate offset shifts
* are unaffected — so an out-of-range day is rejected instead of quietly
* shifting the queried window.
*/
const [year, month, day] = raw.slice(0, 10).split('-').map(Number);
const lastDayOfMonth = new Date(Date.UTC(year, month, 0)).getUTCDate();
if (month < 1 || month > 12 || day < 1 || day > lastDayOfMonth) {
return { ok: false, error: 'Invalid date' };
}
if (boundary === 'end' && DATE_ONLY_RE.test(raw)) {
d.setUTCHours(23, 59, 59, 999);
}
return { ok: true, value: d };
}
function parseIntInRange(
raw: unknown,
label: string,
min: number,
max?: number,
): ParseResult<number | undefined> {
if (raw == null || raw === '') return { ok: true, value: undefined };
const n = typeof raw === 'number' ? raw : Number.parseInt(String(raw), 10);
if (!Number.isFinite(n)) return { ok: false, error: `${label} must be a number` };
if (n < min) return { ok: false, error: `${label} must be >= ${min}` };
if (max != null && n > max) return { ok: false, error: `${label} must be <= ${max}` };
return { ok: true, value: Math.floor(n) };
}
function pickString(raw: unknown, maxLen = 256): string | undefined {
if (typeof raw !== 'string') return undefined;
const trimmed = raw.trim();
if (!trimmed) return undefined;
return trimmed.slice(0, maxLen);
}
function escapeCsvCell(value: string): string {
if (value === '') return '';
const guarded = FORMULA_PREFIX.test(value) ? `'${value}` : value;
if (/[",\n\r]/.test(guarded)) {
return `"${guarded.replace(/"/g, '""')}"`;
}
return guarded;
}
function stringifyMetaValue(value: unknown): string {
if (value == null) return '';
if (typeof value === 'string') return value;
if (typeof value === 'number' || typeof value === 'boolean') return String(value);
return '';
}
const CSV_COLUMNS: ReadonlyArray<{ label: string; value: (e: AdminAuditLogEntry) => string }> = [
{ label: 'Timestamp', value: (e) => e.timestamp },
{ label: 'Category', value: (e) => e.category },
{ label: 'Action', value: (e) => e.action },
{ label: 'Outcome', value: (e) => e.outcome },
{ label: 'Severity', value: (e) => e.severity },
{ label: 'Actor type', value: (e) => e.actor.type },
{ label: 'Actor', value: (e) => e.actor.name },
{ label: 'Actor ID', value: (e) => e.actor.id ?? '' },
{ label: 'Target type', value: (e) => e.target.type },
{ label: 'Target', value: (e) => e.target.name ?? '' },
{ label: 'Target ID', value: (e) => e.target.id ?? '' },
{ label: 'Capability', value: (e) => stringifyMetaValue(e.metadata?.capability) },
{ label: 'Details', value: (e) => (e.metadata ? JSON.stringify(e.metadata) : '') },
{ label: 'IP', value: (e) => e.context?.ip ?? '' },
{ label: 'Request ID', value: (e) => e.context?.requestId ?? '' },
{ label: 'Seq', value: (e) => String(e.integrity.seq) },
{ label: 'Hash', value: (e) => e.integrity.hash },
];
function formatCsvHeader(): string {
return CSV_COLUMNS.map((c) => escapeCsvCell(c.label)).join(',');
}
function formatCsvRow(entry: AdminAuditLogEntry): string {
return CSV_COLUMNS.map((c) => escapeCsvCell(c.value(entry))).join(',');
}
type ParsedFilters = Omit<AuditLogFilters, 'offset' | 'limit' | 'cursor'>;
interface AuditLogQuery {
search?: string;
category?: string | string[];
action?: string | string[];
outcome?: string | string[];
severity?: string | string[];
actorType?: string;
actorQuery?: string;
targetType?: string;
targetQuery?: string;
capability?: string;
from?: string;
to?: string;
limit?: string;
offset?: string;
cursor?: string;
}
function parseFilters(query: AuditLogQuery): ParseResult<ParsedFilters> {
const from = parseIsoDate(query.from, 'start');
if (!from.ok) return { ok: false, error: `from: ${from.error}` };
const to = parseIsoDate(query.to, 'end');
if (!to.ok) return { ok: false, error: `to: ${to.error}` };
if (from.value && to.value && from.value > to.value) {
return { ok: false, error: '`from` must be earlier than `to`' };
}
const category = parseEnumArray<AuditCategory>(query.category, VALID_CATEGORIES, 'category');
if (!category.ok) return { ok: false, error: category.error };
const action = parseEnumArray<AuditAction>(query.action, VALID_ACTIONS, 'action');
if (!action.ok) return { ok: false, error: action.error };
const outcome = parseEnumArray<AuditOutcome>(query.outcome, VALID_OUTCOMES, 'outcome');
if (!outcome.ok) return { ok: false, error: outcome.error };
const severity = parseEnumArray<AuditSeverity>(query.severity, VALID_SEVERITIES, 'severity');
if (!severity.ok) return { ok: false, error: severity.error };
const actorType = parseEnum<AuditActorType>(query.actorType, VALID_ACTOR_TYPES, 'actorType');
if (!actorType.ok) return { ok: false, error: actorType.error };
return {
ok: true,
value: {
search: pickString(query.search, 200),
category: category.value,
action: action.value,
outcome: outcome.value,
severity: severity.value,
actorType: actorType.value,
actorQuery: pickString(query.actorQuery, 128),
targetType: pickString(query.targetType, 128),
targetQuery: pickString(query.targetQuery, 128),
capability: pickString(query.capability, 256),
from: from.value,
to: to.value,
},
};
}
/**
* Describes a filter set for the audit trail without storing what was searched
* for: enum and date filters are recorded as given, free-text filters (which can
* carry names or email addresses) only by name.
*/
function describeFilters(filters: ParsedFilters): AuditMetadata {
const metadata: AuditMetadata = {};
const lists: Array<[string, string[] | undefined]> = [
['category', filters.category],
['action', filters.action],
['outcome', filters.outcome],
['severity', filters.severity],
];
for (const [key, values] of lists) {
if (values?.length) metadata[key] = [...values].sort().join(',');
}
if (filters.actorType) metadata.actorType = filters.actorType;
if (filters.from) metadata.from = filters.from.toISOString();
if (filters.to) metadata.to = filters.to.toISOString();
const freeText = (
['search', 'actorQuery', 'targetQuery', 'targetType', 'capability'] as const
).filter((key) => filters[key] != null);
if (freeText.length > 0) metadata.freeTextFilters = freeText.join(',');
return metadata;
}
export function createAdminAuditLogHandlers(deps: AdminAuditLogDeps): {
listAuditLog: (req: ServerRequest, res: Response) => Promise<Response>;
getAuditLogEntry: (req: ServerRequest, res: Response) => Promise<Response>;
verifyAuditLog: (req: ServerRequest, res: Response) => Promise<Response>;
exportAuditLogCsv: (req: ServerRequest, res: Response) => Promise<Response | void>;
} {
const { listAuditLogPage, findAuditLogEntry, streamAuditLogEntries, verifyAuditChain } = deps;
const emitAudit = createAdminAuditEmitter({
recordAuditEntry: deps.recordAuditEntry,
failClosed: deps.auditFailClosed,
logPrefix: '[adminAuditLog]',
});
/** Follow-up entries describe an attempt that already happened, so they never fail the caller. */
const emitFollowUp = createAdminAuditEmitter({
recordAuditEntry: deps.recordAuditEntry,
logPrefix: '[adminAuditLog]',
});
async function listAuditLogHandler(req: ServerRequest, res: Response) {
try {
const caller = resolveCaller(req);
if (!caller) return res.status(401).json({ error: 'Authentication required' });
const query = req.query as AuditLogQuery;
const filters = parseFilters(query);
if (!filters.ok) return res.status(400).json({ error: filters.error });
const limit = parseIntInRange(query.limit, 'limit', 1, MAX_AUDIT_LOG_LIMIT);
if (!limit.ok) return res.status(400).json({ error: limit.error });
const offset = parseIntInRange(query.offset, 'offset', 0);
if (!offset.ok) return res.status(400).json({ error: offset.error });
const cursor = parseIntInRange(query.cursor, 'cursor', 1);
if (!cursor.ok) return res.status(400).json({ error: cursor.error });
const page = await listAuditLogPage(caller.tenantId, {
...filters.value,
offset: offset.value,
limit: limit.value,
cursor: cursor.value,
});
await emitAudit(req, {
action: 'audit.read',
target: { type: 'audit_log' },
metadata: describeFilters(filters.value),
});
return res.status(200).json(page);
} catch (err) {
logger.error('[adminAuditLog] list error:', getSafeErrorMetadata(err));
return res.status(500).json({ error: 'Failed to fetch audit log' });
}
}
async function getAuditLogEntryHandler(req: ServerRequest, res: Response) {
try {
const caller = resolveCaller(req);
if (!caller) return res.status(401).json({ error: 'Authentication required' });
const { id } = req.params as { id?: string };
if (!id || !OBJECT_ID_RE.test(id)) {
return res.status(400).json({ error: 'Invalid id' });
}
const entry = await findAuditLogEntry(caller.tenantId, id);
if (!entry) return res.status(404).json({ error: 'Not found' });
await emitAudit(req, {
action: 'audit.read',
target: { type: 'audit_log', id },
});
return res.status(200).json({ entry });
} catch (err) {
logger.error('[adminAuditLog] get error:', getSafeErrorMetadata(err));
return res.status(500).json({ error: 'Failed to fetch audit log entry' });
}
}
async function verifyAuditLogHandler(req: ServerRequest, res: Response) {
try {
const caller = resolveCaller(req);
if (!caller) return res.status(401).json({ error: 'Authentication required' });
let clientAborted = false;
const markAborted = () => {
clientAborted = true;
};
res.once('close', markAborted);
req.once('aborted', markAborted);
try {
const result = await verifyAuditChain(caller.tenantId, {
isCancelled: () => clientAborted,
maxRows: MAX_AUDIT_VERIFY_ROWS,
});
if (clientAborted) return res;
await emitAudit(req, {
action: 'audit.read',
target: { type: 'audit_log' },
metadata: { operation: 'verify' },
});
return res.status(200).json(result);
} finally {
res.removeListener('close', markAborted);
req.removeListener('aborted', markAborted);
}
} catch (err) {
logger.error('[adminAuditLog] verify error:', getSafeErrorMetadata(err));
return res.status(500).json({ error: 'Failed to verify audit log integrity' });
}
}
async function exportAuditLogCsvHandler(req: ServerRequest, res: Response) {
let exportRecorded = false;
let exportFailed: ((code: string) => Promise<void>) | undefined;
try {
const caller = resolveCaller(req);
if (!caller) return res.status(401).json({ error: 'Authentication required' });
const filters = parseFilters(req.query as AuditLogQuery);
if (!filters.ok) return res.status(400).json({ error: filters.error });
/**
* The socket-`close` listener is the canonical signal — it fires on client
* TCP RST as well as on graceful end. `req.aborted` (deprecated) is kept as
* a belt-and-braces fallback for Node versions that emit it before the
* response sees `close`.
*/
let clientAborted = false;
const markAborted = () => {
clientAborted = true;
};
res.once('close', markAborted);
req.once('aborted', markAborted);
const isCancelled = () => clientAborted;
/** Recorded as pending before any row is streamed, so an export is never unaudited; `success` follows once the stream ends. */
const exportEvent = {
action: 'audit.exported' as const,
severity: 'warning' as const,
target: { type: 'audit_log' },
metadata: { format: 'csv', ...describeFilters(filters.value) },
};
await emitAudit(req, { ...exportEvent, outcome: 'pending' });
exportRecorded = true;
exportFailed = (code: string) =>
emitFollowUp(req, {
...exportEvent,
outcome: 'failure',
metadata: { ...exportEvent.metadata, code },
});
const filenameStamp = new Date().toISOString().slice(0, 10);
res.setHeader('Content-Type', 'text/csv; charset=utf-8');
res.setHeader('Content-Disposition', `attachment; filename="audit-log-${filenameStamp}.csv"`);
res.setHeader('Cache-Control', 'no-store');
/**
* Wait for `drain` when the socket buffer is full so we never queue an
* unbounded amount of CSV in Node memory for slow consumers. Race against
* `close` so a destroyed socket can't strand the handler on a `drain` that
* will never fire.
*/
const writeChunk = (chunk: string): Promise<void> => {
if (clientAborted) return Promise.resolve();
if (res.write(chunk)) return Promise.resolve();
return new Promise<void>((resolve) => {
const onDrain = () => {
res.removeListener('close', onClose);
resolve();
};
const onClose = () => {
res.removeListener('drain', onDrain);
resolve();
};
res.once('drain', onDrain);
res.once('close', onClose);
});
};
await writeChunk(CSV_BOM);
await writeChunk(formatCsvHeader());
await writeChunk('\r\n');
const { truncated, count } = await streamAuditLogEntries(
caller.tenantId,
filters.value,
async (entry) => {
if (clientAborted) return;
await writeChunk(formatCsvRow(entry));
await writeChunk('\r\n');
},
{ isCancelled, maxRows: MAX_AUDIT_EXPORT_ROWS },
);
res.removeListener('close', markAborted);
req.removeListener('aborted', markAborted);
if (clientAborted) {
await exportFailed('client_aborted');
}
if (!clientAborted) {
/** `end()` only queues the last bytes, so success waits for the response to finish. */
const settled = new Promise<boolean>((resolve) => {
if (res.destroyed) {
resolve(false);
return;
}
res.once('finish', () => resolve(true));
res.once('close', () => resolve(res.writableFinished === true));
});
/**
* `truncated` is true only when rows existed beyond the cap (an exact-cap
* match is reported as complete). Surfacing this is a compliance
* requirement — a silently truncated export reads as a complete record.
* Emit an explicit trailing marker and log it; callers should narrow the
* date range for the full set.
*/
if (truncated) {
logger.warn('[adminAuditLog] CSV export truncated at row cap', {
maxRows: MAX_AUDIT_EXPORT_ROWS,
});
await writeChunk(
`# TRUNCATED: export capped at ${MAX_AUDIT_EXPORT_ROWS} rows — narrow the from/to range to export the complete set\r\n`,
);
}
res.end();
if (await settled) {
await emitFollowUp(req, {
...exportEvent,
metadata: { ...exportEvent.metadata, rows: count, truncated },
});
} else {
await exportFailed('client_aborted');
}
}
} catch (err) {
logger.error('[adminAuditLog] export error:', getSafeErrorMetadata(err));
if (exportRecorded) {
await exportFailed?.('export_failed');
}
if (!res.headersSent) {
return res.status(500).json({ error: 'Failed to export audit log' });
}
res.end();
}
}
return {
listAuditLog: listAuditLogHandler,
getAuditLogEntry: getAuditLogEntryHandler,
verifyAuditLog: verifyAuditLogHandler,
exportAuditLogCsv: exportAuditLogCsvHandler,
};
}