Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { Router } from 'express'
import type { NextFunction, Request, Response } from 'express'
import { type AugmentedRequest, ipKeyGenerator, rateLimit } from 'express-rate-limit'
import { randomUUID } from 'node:crypto'
import { isIP } from 'node:net'
import { Readable } from 'node:stream'
import { pipeline } from 'node:stream/promises'
import { config } from '../config.js'
import { ControlApiError, controlApiRequest, controlApiStreamRequest } from '../controlApiClient.js'
import { type AuthedRequest, extractAuthToken, requireAuth } from '../middleware/auth.js'
type GfsRouterOptions = {
edgeRequestLimit?: number
edgeLimits?: ExternalGfsEdgeLimits
}
/**
* End-user gfs (Global File System) surface — the user side of the delegation UI
* (Desktop / profile). Pure passthrough on the Session-JWT plane: every route
* requires the user session (requireAuth) and forwards to control-api
* `/external/gfs/*` with the user session token. No auth is invented here — the
* control-api side mints/verifies via the existing JWT scheme. Mirrors
* `routes/contextSharedFilesystems.ts` + `routes/rpc.ts`.
*/
// 5xx included so control-api's gfsc failure codes reach the desktop verbatim:
// Preserve the GFS transport contract at this boundary. The client retry policy
// distinguishes transient 408/425/5xx responses from terminal 507 storage
// exhaustion, so collapsing an unlisted status into the process-wide 500 handler
// would change the meaning of a writer response. The 4xx allowlist remains
// explicit; every 5xx is safe to forward because it is already a ControlApiError
// produced by the authenticated control-plane request.
const PROPAGATED = new Set([400, 401, 403, 404, 408, 409, 410, 411, 412, 413, 422, 425, 429, 507])
const STREAM_HEADERS = [
'content-type',
'content-length',
'content-disposition',
'cache-control',
'location',
'upload-offset',
'upload-length',
'upload-part-bytes',
'upload-part-count',
'upload-active-parts',
'upload-state',
'upload-expires',
'upload-part-number',
'upload-part-offset',
'upload-part-length',
'upload-checksum',
'retry-after',
'x-ratelimit-limit',
'x-ratelimit-remaining',
'x-gfs-ratelimit-scope',
]
const CONTROL_API_ERROR_HEADERS = [
'retry-after',
'ratelimit',
'ratelimit-policy',
'x-ratelimit-limit',
'x-ratelimit-remaining',
'x-ratelimit-reset',
'x-request-id',
] as const
const UUID_ANY_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
const EXTERNAL_GFS_EDGE_WINDOW_MS = 60_000
function retryAfterSecondsFromHeader(value: unknown): number {
const raw = Array.isArray(value) ? value[0] : value
if (typeof raw === 'number' && Number.isSafeInteger(raw) && raw > 0) return raw
const text = typeof raw === 'string' ? raw.trim() : ''
const seconds = Number(text)
if (Number.isSafeInteger(seconds) && seconds > 0) return seconds
const retryAt = Date.parse(text)
if (Number.isFinite(retryAt)) return Math.max(1, Math.ceil((retryAt - Date.now()) / 1000))
return 1
}
export type ExternalGfsEdgeLimits = {
aggregatePerMin: number
authenticatedIpPerMin: number
tokenIpPerMin: number
}
/**
* Derive the coarse edge backstop from the number of users expected to share
* one trusted proxy address. The values deliberately scale the edge only:
* Control API PG buckets still enforce the 10/min token and 30/min
* session/actor product budgets across replicas.
*/
const DEFAULT_EXTERNAL_GFS_EDGE_LIMITS: ExternalGfsEdgeLimits = {
aggregatePerMin: config.externalGfsEdgeAggregateRlPerMin,
authenticatedIpPerMin: config.externalGfsEdgeAuthenticatedIpRlPerMin,
tokenIpPerMin: config.externalGfsEdgeTokenIpRlPerMin,
}
type GfsAuthedRequest = AuthedRequest & { gfsRequestId?: string }
type GfsRequestOptions = {
query?: Record<string, string | undefined>
body?: unknown
userSessionToken?: string
extraHeaders?: Record<string, string>
}
function attachGfsRequestId(req: Request, res: Response, next: NextFunction): void {
const raw = req.header('x-request-id')?.trim()
const requestId = raw && UUID_ANY_RE.test(raw) ? raw.toLowerCase() : randomUUID()
;(req as GfsAuthedRequest).gfsRequestId = requestId
res.setHeader('x-request-id', requestId)
next()
}
function withGfsRequestId(req: GfsAuthedRequest, options: GfsRequestOptions): GfsRequestOptions {
// The control-api is behind profile-control-funnel, which appends its own
// peer to X-Forwarded-For. Preserve the external-rest API's proxy-attested
// client address as the first value so the control-api's pre-resolution
// limiter can enforce its approved per-source-IP bucket. This overwrites
// any caller-supplied value; only req.ip (after this service's trust-proxy
// policy) is propagated across the authenticated service boundary.
const clientIp = req.ip?.trim()
const forwardedClientIp = clientIp && isIP(clientIp) !== 0 ? clientIp : undefined
return {
...options,
extraHeaders: {
...options.extraHeaders,
'x-request-id': req.gfsRequestId!,
...(forwardedClientIp ? { 'x-forwarded-for': forwardedClientIp } : {}),
},
}
}
function gfsControlApiRequest<T>(
req: GfsAuthedRequest,
method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
path: string,
options: GfsRequestOptions
): Promise<T> {
return controlApiRequest<T>(method, path, withGfsRequestId(req, options))
}
function forwardControlApiError(error: unknown, res: Response, next: NextFunction): void {
const shouldPropagate =
error instanceof ControlApiError &&
(PROPAGATED.has(error.status) || (error.status >= 500 && error.status <= 599))
if (shouldPropagate) {
// The internal client has already filtered this map. Keep the allowlist at
// this last hop too so a hand-constructed/mocked ControlApiError cannot
// accidentally turn arbitrary internal response headers into public ones.
for (const name of CONTROL_API_ERROR_HEADERS) {
const value = error.headers?.[name]
if (value) res.setHeader(name, value)
}
const body =
error.body && typeof error.body === 'object' ? error.body : { error: String(error.message) }
for (const header of STREAM_HEADERS) {
const value = error.headers?.[header]
if (value) res.setHeader(header, value)
}
res.status(error.status).json(body)
return
}
next(error)
}
export function createGfsRouter(options: GfsRouterOptions = {}): Router {
const router = Router()
const edgeLimits = options?.edgeLimits ?? DEFAULT_EXTERNAL_GFS_EDGE_LIMITS
const edgeLimiter = (
limit: number,
bucket: string,
options?: { keyGenerator?: (req: Request) => string }
) =>
rateLimit({
windowMs: EXTERNAL_GFS_EDGE_WINDOW_MS,
limit,
standardHeaders: 'draft-7',
legacyHeaders: false,
identifier: `gfs-edge-${bucket}`,
...(options?.keyGenerator ? { keyGenerator: options.keyGenerator } : {}),
handler: (_req, res) => {
const retryAfterSeconds = retryAfterSecondsFromHeader(res.getHeader('Retry-After'))
res.status(429).json({
error: 'Too Many Requests',
rateLimitLayer: 'external-rest-edge',
rateLimitBucket: bucket,
retryAfterSeconds,
})
},
})
// Keep direct, recognised edge guards at this service as well as the
// cross-replica Control API buckets. They run before JWT work and prevent a
// client from using the proxy hop to make auth or downstream requests
// unbounded. The aggregate and authenticated class buckets are deliberately
// sized for a shared NAT address; the token bucket remains tighter. The
// narrower buckets run first so their rejected requests do not consume
// broader capacity. The Control API owns the authoritative per-user/session/
// actor budgets.
router.use('/me/gfs', attachGfsRequestId)
router.use('/me/gfs/token', edgeLimiter(edgeLimits.tokenIpPerMin, 'token-ip'))
router.use('/me/gfs', edgeLimiter(edgeLimits.authenticatedIpPerMin, 'authenticated-ip'))
router.use(
'/me/gfs',
edgeLimiter(edgeLimits.aggregatePerMin, 'aggregate-ip', {
// This is intentionally a process-wide backstop, not another per-IP
// bucket. The authenticated-IP limiter above owns client fairness;
// keeping a constant key makes distributed source-IP floods observable
// at this edge instead of allowing the aggregate budget to be bypassed.
keyGenerator: () => 'gfs-edge-aggregate',
})
)
router.use('/me/gfs', requireAuth)
// Coarse per-process guard for the public Express edge (and a CodeQL-visible
// middleware on every new route). The authoritative replica-safe request,
// weighted-byte, and active-request budgets are enforced again in
// control-api with PostgreSQL before GFSC body forwarding.
const edgeRequestLimit = options.edgeRequestLimit ?? config.gfsUploadRequestPerMinute
const uploadEdgeRateLimit = rateLimit({
windowMs: 60_000,
limit: edgeRequestLimit,
legacyHeaders: false,
standardHeaders: false,
skipFailedRequests: false,
skipSuccessfulRequests: false,
passOnStoreError: true,
keyGenerator: request => {
const req = request as AuthedRequest
const sourceIp = req.ip || req.socket.remoteAddress || 'unknown'
const normalizedIp = sourceIp === 'unknown' ? sourceIp : ipKeyGenerator(sourceIp)
return `${req.auth?.userId || '__no_user__'}:${normalizedIp}`
},
handler: (request, res, _next, optionsUsed) => {
const info = (request as AugmentedRequest).rateLimit
const resetAt = info?.resetTime?.getTime() ?? Date.now() + optionsUsed.windowMs
const retryAfterSeconds = Math.max(1, Math.ceil((resetAt - Date.now()) / 1000))
res.setHeader('Retry-After', String(retryAfterSeconds))
res.setHeader('X-RateLimit-Limit', String(info?.limit ?? edgeRequestLimit))
res.setHeader('X-GFS-RateLimit-Scope', 'public_edge_requests')
res.setHeader('X-RateLimit-Remaining', '0')
res.status(429).json({
error: 'gfs_upload_rate_limited',
limit: 'public_edge_requests',
retryAfterSeconds,
})
},
})
// Resumable v2 relay. JSON lifecycle calls remain bounded metadata requests;
// a part PUT passes the IncomingMessage directly to control-api so neither
// external-rest-api nor control-api materializes the part in memory.
router.get('/me/gfs/capabilities', uploadEdgeRateLimit, (req: AuthedRequest, res, next) => {
void proxyUploadStream(req, res, next, 'GET', '/external/gfs/capabilities')
})
router.post('/me/gfs/uploads', uploadEdgeRateLimit, (req: AuthedRequest, res, next) => {
void proxyUploadStream(req, res, next, 'POST', '/external/gfs/uploads')
})
router.head('/me/gfs/uploads/:id', uploadEdgeRateLimit, (req: AuthedRequest, res, next) => {
void proxyUploadStream(
req,
res,
next,
'HEAD',
`/external/gfs/uploads/${encodeURIComponent(req.params.id)}`
)
})
router.get('/me/gfs/uploads/:id/status', uploadEdgeRateLimit, (req: AuthedRequest, res, next) => {
void proxyUploadStream(
req,
res,
next,
'GET',
`/external/gfs/uploads/${encodeURIComponent(req.params.id)}/status`
)
})
router.put(
'/me/gfs/uploads/:id/parts/:part',
uploadEdgeRateLimit,
(req: AuthedRequest, res, next) => {
void proxyUploadStream(
req,
res,
next,
'PUT',
`/external/gfs/uploads/${encodeURIComponent(req.params.id)}/parts/${encodeURIComponent(req.params.part)}`
)
}
)
for (const action of ['pause', 'resume', 'complete'] as const) {
router.post(
`/me/gfs/uploads/:id/${action}`,
uploadEdgeRateLimit,
(req: AuthedRequest, res, next) => {
void proxyUploadStream(
req,
res,
next,
'POST',
`/external/gfs/uploads/${encodeURIComponent(req.params.id)}/${action}`
)
}
)
}
router.delete('/me/gfs/uploads/:id', uploadEdgeRateLimit, (req: AuthedRequest, res, next) => {
void proxyUploadStream(
req,
res,
next,
'DELETE',
`/external/gfs/uploads/${encodeURIComponent(req.params.id)}`
)
})
router.post('/me/gfs/token', async (req: AuthedRequest, res, next) => {
try {
const data = await gfsControlApiRequest(req, 'POST', '/external/gfs/token', {
userSessionToken: extractAuthToken(req),
body: req.body ?? {},
})
res.status(200).json(data)
} catch (error) {
forwardControlApiError(error, res, next)
}
})
router.get('/me/gfs/resolve', async (req: AuthedRequest, res, next) => {
try {
const data = await gfsControlApiRequest(req, 'GET', '/external/gfs/resolve', {
userSessionToken: extractAuthToken(req),
query: { uri: typeof req.query.uri === 'string' ? req.query.uri : undefined },
})
res.status(200).json(data)
} catch (error) {
forwardControlApiError(error, res, next)
}
})
router.get('/me/gfs/resources', async (req: AuthedRequest, res, next) => {
try {
const data = await gfsControlApiRequest(req, 'GET', '/external/gfs/resources', {
userSessionToken: extractAuthToken(req),
query: {
drive: typeof req.query.drive === 'string' ? req.query.drive : undefined,
limit: typeof req.query.limit === 'string' ? req.query.limit : undefined,
cursor: typeof req.query.cursor === 'string' ? req.query.cursor : undefined,
},
})
res.status(200).json(data)
} catch (error) {
forwardControlApiError(error, res, next)
}
})
router.get('/me/gfs/resources/:id/children', async (req: AuthedRequest, res, next) => {
try {
const data = await gfsControlApiRequest(
req,
'GET',
`/external/gfs/resources/${encodeURIComponent(req.params.id)}/children`,
{
userSessionToken: extractAuthToken(req),
query: {
drive: typeof req.query.drive === 'string' ? req.query.drive : undefined,
limit: typeof req.query.limit === 'string' ? req.query.limit : undefined,
cursor: typeof req.query.cursor === 'string' ? req.query.cursor : undefined,
},
}
)
res.status(200).json(data)
} catch (error) {
forwardControlApiError(error, res, next)
}
})
router.get('/me/gfs/resources/:id/affordances', async (req: AuthedRequest, res, next) => {
try {
const data = await gfsControlApiRequest(
req,
'GET',
`/external/gfs/resources/${encodeURIComponent(req.params.id)}/affordances`,
{
userSessionToken: extractAuthToken(req),
query: { drive: typeof req.query.drive === 'string' ? req.query.drive : undefined },
}
)
res.status(200).json(data)
} catch (error) {
forwardControlApiError(error, res, next)
}
})
router.patch('/me/gfs/resources/:id', async (req: AuthedRequest, res, next) => {
try {
const data = await gfsControlApiRequest(
req,
'PATCH',
`/external/gfs/resources/${encodeURIComponent(req.params.id)}`,
{
userSessionToken: extractAuthToken(req),
query: { drive: typeof req.query.drive === 'string' ? req.query.drive : undefined },
body: req.body ?? {},
}
)
res.status(200).json(data)
} catch (error) {
forwardControlApiError(error, res, next)
}
})
router.post('/me/gfs/resources/:id/children', async (req: AuthedRequest, res, next) => {
try {
const data = await gfsControlApiRequest(
req,
'POST',
`/external/gfs/resources/${encodeURIComponent(req.params.id)}/children`,
{
userSessionToken: extractAuthToken(req),
query: { drive: typeof req.query.drive === 'string' ? req.query.drive : undefined },
body: req.body ?? {},
}
)
res.status(201).json(data)
} catch (error) {
forwardControlApiError(error, res, next)
}
})
router.put('/me/gfs/resources/:id/content', async (req: AuthedRequest, res, next) => {
try {
const data = await gfsControlApiRequest(
req,
'PUT',
`/external/gfs/resources/${encodeURIComponent(req.params.id)}/content`,
{
userSessionToken: extractAuthToken(req),
query: { drive: typeof req.query.drive === 'string' ? req.query.drive : undefined },
body: req.body ?? {},
}
)
res.status(200).json(data)
} catch (error) {
forwardControlApiError(error, res, next)
}
})
router.delete('/me/gfs/resources/:id', async (req: AuthedRequest, res, next) => {
try {
const data = await gfsControlApiRequest(
req,
'DELETE',
`/external/gfs/resources/${encodeURIComponent(req.params.id)}`,
{
userSessionToken: extractAuthToken(req),
query: { drive: typeof req.query.drive === 'string' ? req.query.drive : undefined },
body: req.body ?? {},
}
)
res.status(200).json(data)
} catch (error) {
forwardControlApiError(error, res, next)
}
})
router.get('/me/gfs/proxy/:rid', async (req: AuthedRequest, res, next) => {
try {
const upstream = await controlApiStreamRequest(
'GET',
`/external/gfs/proxy/${encodeURIComponent(req.params.rid)}`,
withGfsRequestId(req, {
userSessionToken: extractAuthToken(req),
query: { drive: typeof req.query.drive === 'string' ? req.query.drive : undefined },
})
)
res.status(upstream.status)
for (const header of STREAM_HEADERS) {
const value = upstream.headers.get(header)
if (value) res.setHeader(header, value)
}
if (!upstream.body) {
res.end()
return
}
await pipeline(
Readable.fromWeb(
upstream.body as unknown as import('node:stream/web').ReadableStream<Uint8Array>
),
res
)
} catch (error) {
forwardControlApiError(error, res, next)
}
})
// Delegation (folder-owner): grant/share as the user. control-api's
// assertMayGrant enforces no-escalation against the user's own held bits.
// The grants list requires manage_acl on the resource (view-ACL = manage-ACL,
// enforced by control-api's handleGrantListForCaller); its item `id` is what
// powers per-row revoke in the Manage modal.
router.get('/me/gfs/grants', async (req: AuthedRequest, res, next) => {
try {
const data = await gfsControlApiRequest(req, 'GET', '/external/gfs/grants', {
userSessionToken: extractAuthToken(req),
query: {
drive: typeof req.query.drive === 'string' ? req.query.drive : undefined,
resourceId: typeof req.query.resourceId === 'string' ? req.query.resourceId : undefined,
},
})
res.status(200).json(data)
} catch (error) {
forwardControlApiError(error, res, next)
}
})
router.put('/me/gfs/grants', async (req: AuthedRequest, res, next) => {
try {
const data = await gfsControlApiRequest(req, 'PUT', '/external/gfs/grants', {
userSessionToken: extractAuthToken(req),
body: req.body ?? {},
})
res.status(200).json(data)
} catch (error) {
forwardControlApiError(error, res, next)
}
})
router.delete('/me/gfs/grants/:id', async (req: AuthedRequest, res, next) => {
try {
const data = await gfsControlApiRequest(
req,
'DELETE',
`/external/gfs/grants/${encodeURIComponent(req.params.id)}`,
{ userSessionToken: extractAuthToken(req) }
)
res.status(200).json(data)
} catch (error) {
forwardControlApiError(error, res, next)
}
})
router.post('/me/gfs/shares', async (req: AuthedRequest, res, next) => {
try {
const data = await gfsControlApiRequest(req, 'POST', '/external/gfs/shares', {
userSessionToken: extractAuthToken(req),
body: req.body ?? {},
})
res.status(200).json(data)
} catch (error) {
forwardControlApiError(error, res, next)
}
})
router.get('/me/gfs/shares', async (req: AuthedRequest, res, next) => {
try {
const data = await gfsControlApiRequest(req, 'GET', '/external/gfs/shares', {
userSessionToken: extractAuthToken(req),
query: {
drive: typeof req.query.drive === 'string' ? req.query.drive : undefined,
resourceId: typeof req.query.resourceId === 'string' ? req.query.resourceId : undefined,
},
})
res.status(200).json(data)
} catch (error) {
forwardControlApiError(error, res, next)
}
})
router.delete('/me/gfs/shares/:id', async (req: AuthedRequest, res, next) => {
try {
const data = await gfsControlApiRequest(
req,
'DELETE',
`/external/gfs/shares/${encodeURIComponent(req.params.id)}`,
{ userSessionToken: extractAuthToken(req) }
)
res.status(200).json(data)
} catch (error) {
forwardControlApiError(error, res, next)
}
})
return router
}
async function proxyUploadStream(
req: AuthedRequest,
res: Response,
next: NextFunction,
method: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE',
path: string
): Promise<void> {
try {
const extraHeaders: Record<string, string> = {}
for (const name of [
'content-type',
'upload-part-number',
'upload-offset',
'upload-chunk-length',
'upload-checksum',
]) {
const value = req.headers[name]
if (typeof value === 'string') extraHeaders[name] = value
}
const isPart = method === 'PUT' && /\/parts\/[0-9]+$/.test(path)
if (isPart) {
const contentLength = String(req.headers['content-length'] || '')
const chunkLength = String(req.headers['upload-chunk-length'] || '')
if (!/^[0-9]+$/.test(contentLength) || !/^[0-9]+$/.test(chunkLength)) {
res.status(411).json({ error: 'upload_content_length_required' })
return
}
const declaredBytes = Number(contentLength)
if (
!Number.isSafeInteger(declaredBytes) ||
declaredBytes < 1 ||
declaredBytes > config.gfsUploadMaxPartBytes
) {
res.status(413).json({ error: 'payload_too_large' })
return
}
if (Number(chunkLength) !== declaredBytes) {
res.status(400).json({ error: 'upload_length_mismatch' })
return
}
extraHeaders['content-length'] = contentLength
}
extraHeaders['x-gfs-upload-source-ip'] = req.ip || req.socket.remoteAddress || 'unknown'
const body =
method === 'GET' || method === 'HEAD'
? undefined
: isPart
? req
: JSON.stringify(req.body ?? {})
const upstream = await controlApiStreamRequest(method, path, {
userSessionToken: extractAuthToken(req),
// Preserve the bounded status cursor contract across the relay. Dropping
// these query parameters makes every resume request fetch page one and
// can silently truncate a session with more than 256 parts.
query: {
// Drive syntax, body/query agreement, ownership, and authorization are
// validated once by control-api before admission/token minting. The
// relay must not make a security decision from a user-controlled drive
// value or maintain a second, divergent drive policy.
drive: typeof req.query.drive === 'string' ? req.query.drive : undefined,
limit: typeof req.query.limit === 'string' ? req.query.limit : undefined,
cursor: typeof req.query.cursor === 'string' ? req.query.cursor : undefined,
},
extraHeaders,
body,
})
res.status(upstream.status)
for (const header of STREAM_HEADERS) {
const value = upstream.headers.get(header)
if (value) res.setHeader(header, value)
}
if (!upstream.body) {
res.end()
return
}
await pipeline(
Readable.fromWeb(
upstream.body as unknown as import('node:stream/web').ReadableStream<Uint8Array>
),
res
)
} catch (error) {
forwardControlApiError(error, res, next)
}
}