Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { type Response as ExpressResponse, type NextFunction, type Request, Router } from 'express'
import { type RateLimitInfo, ipKeyGenerator, rateLimit } from 'express-rate-limit'
import { createHash, randomUUID } from 'node:crypto'
import {
GFS_DELETE_SCOPE,
GFS_READ_SCOPE,
GFS_WRITE_SCOPE,
signGfsToken,
} from '../../auth/gfsToken.js'
import { config } from '../../config.js'
import { pool } from '../../db.js'
import {
type ExternalGfsAuthority,
type RequestWithExternalGfsAuthority,
attachExternalGfsAuthority,
attachExternalGfsUserLifecycle,
} from '../../gfs/externalAuthority.js'
import { isValidHostSubjectId, makeHostSubjectId } from '../../gfs/hostSubject.js'
import { DbResolveStore } from '../../gfs/resolve.js'
import {
DbChildrenStore,
GfsTreeError,
clampLimit,
decodeCursor,
encodeCursor,
listChildrenPaged,
} from '../../gfs/tree.js'
import { asyncHandler } from '../../http/asyncHandler.js'
import {
type ExternalGfsOperationClass,
externalGfsClassRlPerMin,
externalGfsPreResolutionRateLimit,
externalGfsResolvedActorBucketKey,
externalGfsResolvedOperationRateLimit,
externalGfsSourceIp,
externalGfsTokenUserBucketKey,
reportEdgeBackstopDenial,
} from '../../middleware/externalGfsRateLimit.js'
import {
type ExternalAuthedRequest,
requireValidExternalSessionToken,
} from '../../middleware/externalSessionAuth.js'
import {
type GfsUploadAdmissionRequest,
createObservedGfsUploadPartBody,
gfsUploadAdmission,
} from '../../middleware/gfsUploadAdmission.js'
import { rateLimitMiddleware } from '../../middleware/rateLimitMiddleware.js'
import { rootLogger } from '../../observability/logger.js'
import { getUserAgents } from '../../services/directory/index.js'
import {
GfsGrantError,
UUID_RE,
driveOf,
handleGrantDelete,
handleGrantListForCaller,
handleGrantWrite,
heldPermissions,
resolveCaller,
sendGfsGrantError,
} from '../gfs/grants.js'
import { handlePatch } from '../gfs/resources.js'
import { handleShareDelete, handleShareListForCaller, handleShareWrite } from '../gfs/shares.js'
import { GFS_DEFAULT_DRIVE, parseRequestedGfsScopes } from '../gfs/token.js'
// A gfs:// URI is `gfs://<drive>/<path-or-rid>`; cap it so an oversized value is
// rejected here, not forwarded to gfsc as an unbounded request.
const MAX_GFS_URI_LEN = 2048
const ACCESSIBLE_RESOURCE_DEFAULT_LIMIT = 100
const GFS_UPLOAD_RESPONSE_HEADERS = [
'content-type',
'content-length',
'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',
] as const
type ExternalGfsRequest = ExternalAuthedRequest & {
gfsSubjectKeys?: string[]
gfsRequestId?: string
gfsAuthority?: ExternalGfsAuthority
}
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
function attachExternalGfsRequestId(
req: import('express').Request,
res: import('express').Response,
next: NextFunction
): void {
const raw = req.header('x-request-id')?.trim()
const requestId =
raw && UUID_ANY_RE.test(raw)
? raw.toLowerCase()
: ((req as { correlationId?: string }).correlationId ?? randomUUID())
;(req as ExternalGfsRequest).gfsRequestId = requestId
res.setHeader('x-request-id', requestId)
next()
}
/** Name of each in-process edge backstop, reported as the `guard` log field. */
type ExternalGfsEdgeGuard =
| 'ingress'
| 'token'
| 'resource'
| 'proxy-read'
| 'resource-mutation'
| 'grants-read'
| 'grants-mutation'
| 'shares-read'
| 'shares-mutation'
function externalGfsRateKey(value: string): string {
return createHash('sha256').update(value).digest('hex')
}
/**
* These key factories back the recognised in-process edge guards. The durable
* Postgres limiter remains the source of cross-replica enforcement and emits
* the public quota headers. These guards are deliberately direct
* express-rate-limit middleware so CodeQL can prove every external GFS route
* is bounded before auth, authority resolution, or route-specific work.
*
* The token and actor guards count under the same key as their Postgres
* bucket, so both limiters log one hashedKey for one actor. The ingress guard
* has no Postgres twin: it masks IPv6 to a /56 with ipKeyGenerator, while the
* Postgres per-IP buckets key on the full address.
*/
function externalGfsIngressRateKey(req: import('express').Request): string {
return `external-gfs:ingress:${externalGfsRateKey(ipKeyGenerator(externalGfsSourceIp(req)))}`
}
// Mounted after requireValidExternalSessionToken and the pre-resolution gate,
// which answers 401 without a user; a missing user here is a routing defect.
function externalGfsTokenRateKey(req: import('express').Request): string {
const userId = (req as ExternalGfsRequest).externalAuth?.userId
if (!userId) throw new Error('external GFS token backstop ran without an authenticated user')
return externalGfsTokenUserBucketKey(userId)
}
// Mounted after attachExternalGfsAuthority and the resolved-operation gate,
// which answers 401 without an authority; a missing one is a routing defect.
function externalGfsActorRateKey(operationClass: Exclude<ExternalGfsOperationClass, 'token'>) {
return (req: import('express').Request): string => {
const authority = (req as ExternalGfsRequest).gfsAuthority
if (!authority) {
throw new Error(`external GFS ${operationClass} backstop ran without a resolved authority`)
}
return externalGfsResolvedActorBucketKey(operationClass, authority)
}
}
function authorityOf(req: ExternalGfsRequest): ExternalGfsAuthority {
const authority = req.gfsAuthority
if (!authority) throw new GfsGrantError(401, 'unauthenticated')
return authority
}
type ExternalGfsUploadRequest = GfsUploadAdmissionRequest & {
gfsUploadDrive?: string
}
function requireCanonicalUploadDrive(
req: ExternalGfsUploadRequest,
res: import('express').Response,
next: NextFunction
): void {
const rawDrive = typeof req.query.drive === 'string' ? req.query.drive : ''
const drive = rawDrive.trim()
if (!drive || drive !== rawDrive) {
res.status(400).json({ error: 'drive_required' })
return
}
if (req.method === 'POST' && req.path === '/external/gfs/uploads') {
const bodyDrive = (req.body as { drive?: unknown } | undefined)?.drive
if (bodyDrive !== drive) {
res.status(400).json({ error: 'drive_mismatch' })
return
}
}
req.gfsUploadDrive = drive
next()
}
function canonicalUploadDrive(req: ExternalGfsUploadRequest): string {
const drive = req.gfsUploadDrive
if (!drive) throw new Error('canonical upload drive middleware was not applied')
return drive
}
function ridOf(resourceId: string): string {
return resourceId.replace(/-/g, '').toLowerCase()
}
function toIsoTimestamp(value: unknown): string {
if (value instanceof Date) return value.toISOString()
if (typeof value === 'string' && value.length > 0) {
const parsed = new Date(value)
return Number.isNaN(parsed.getTime()) ? value : parsed.toISOString()
}
throw new Error('gfs_resources.updated_at is required')
}
function subjectColumns(subjects: Set<string>): { types: string[]; ids: string[] } {
const types: string[] = []
const ids: string[] = []
for (const key of subjects) {
const sep = key.indexOf(':')
if (sep < 0) continue
types.push(key.slice(0, sep))
ids.push(key.slice(sep + 1))
}
return { types, ids }
}
async function externalCallerSubjects(req: ExternalAuthedRequest): Promise<Set<string>> {
const authority = authorityOf(req as ExternalGfsRequest)
if (authority.kind === 'linked-admin') return new Set(['operator:'])
const claims = req.externalAuth!
const subjects = new Set<string>([`user:${claims.userId}`])
if (claims.teamId) subjects.add(`team:${claims.teamId}`)
const result = await pool.query(
`SELECT team_id FROM team_members WHERE user_id = $1 AND status = 'active'`,
[claims.userId]
)
for (const row of result.rows as { team_id: unknown }[]) {
subjects.add(`team:${String(row.team_id)}`)
}
return subjects
}
async function attachExternalGfsCallerSubjects(
req: import('express').Request,
_res: import('express').Response,
next: NextFunction
): Promise<void> {
const externalReq = req as ExternalGfsRequest
externalReq.gfsSubjectKeys = [...(await externalCallerSubjects(externalReq))]
next()
}
/**
* Indexes of well-formed host subjects in `values` that are NOT in
* `allowedHostIds`. Malformed entries (wrong shape, invalid host id) are
* deliberately skipped so `handleGrantWrite` keeps sole ownership of the
* `subjects_invalid` + `invalidIndexes` contract; only a syntactically valid
* host that simply is not the caller's is adjudicated here.
*/
export function foreignHostSubjectIndexes(
values: readonly unknown[],
allowedHostIds: ReadonlySet<string>
): number[] {
const foreign: number[] = []
for (const [index, value] of values.entries()) {
if (typeof value !== 'object' || value === null) continue
const { type, id } = value as { type?: unknown; id?: unknown }
if (type !== 'host' || typeof id !== 'string' || !isValidHostSubjectId(id)) continue
if (!allowedHostIds.has(id)) foreign.push(index)
}
return foreign
}
/**
* User-plane eligibility: a folder owner may delegate only to agents in their
* own directory. The allowed set is derived from the SAME authorization
* boundary the agent catalog uses — `getUserAgents` (DB-only, no Kubernetes in
* the mutation path) — mapped to the exact `1st:<hostsNamespace>/<name>` ids
* `buildAgentDirectoryEntry` emits. Consequences: `3rd:` hosts and the legacy
* fleet-wide sentinel are foreign for every user; sentinel retirement stays on
* the DELETE `allowLegacyRetirement` path; an authorized-but-not-yet-reconciled
* agent is grantable (inert row, consistent with catalog semantics). The admin
* (operator) plane never runs this guard.
*/
async function assertHostTargetsWithinCallerAgents(
req: import('express').Request,
res: import('express').Response,
next: NextFunction
): Promise<void> {
const externalReq = req as ExternalGfsRequest
if (authorityOf(externalReq).kind === 'linked-admin') {
next()
return
}
const body = (externalReq.body ?? {}) as Record<string, unknown>
const plural = Array.isArray(body.subjects)
const values = plural
? (body.subjects as unknown[])
: Object.prototype.hasOwnProperty.call(body, 'subject')
? [body.subject]
: []
const probe = foreignHostSubjectIndexes(values, new Set())
if (probe.length === 0) {
// No well-formed host targets at all — nothing for this guard to decide.
next()
return
}
const { agentNames } = await getUserAgents(externalReq.externalAuth!.userId)
// makeHostSubjectId returns null for a name that cannot form a canonical
// host subject; such an agent is not grantable and never appears in the
// catalog either, so skipping it mirrors buildAgentDirectoryEntry exactly.
const allowed = new Set(
agentNames
.map(name => makeHostSubjectId('1st', config.hostsNamespace, name))
.filter((id): id is string => id !== null)
)
const foreign = foreignHostSubjectIndexes(values, allowed)
if (foreign.length > 0) {
sendGfsGrantError(
res,
new GfsGrantError(403, 'foreign_agent_forbidden', plural ? foreign : undefined)
)
return
}
next()
}
/**
* End-user (folder-owner) gfs surface on the `/external` plane — the Session-JWT
* plane (external-rest-api ← desktop-app / profile-ui) of the platform's defined
* JWT scheme. NO new auth is introduced: the user session is verified by the
* existing `requireValidExternalSessionToken` (sets `req.externalAuth`), the gfs
* token is minted by the existing `signGfsToken` (same platform keypair / aud /
* verifier as operator + host tokens — only `sub = users.id`), and grant/share
* reuse the EXISTING `handleGrantWrite`/`handleShareWrite` whose `resolveCaller`
* already yields the `user:<id>` caller and whose `assertMayGrant` enforces
* no-escalation. gfsc re-checks the permission store on every op, so the user
* token is only an upper bound.
*
* This mirrors `routes/external/sharedFilesystems.ts` (user-session-gated proxy)
* and `routes/external/auth.ts` `/external/rpc/token` (session → downstream token).
*/
export function createExternalGfsRouter(): Router {
const router = Router()
// The durable externalGfs* guards below are the authoritative distributed
// limiter. These direct express-rate-limit guards provide a recognisable
// routing-boundary backstop so static analysis can prove every
// auth/authority/handler path is metered. The all-route ingress guard is
// deliberately wider than the product quotas; the per-class guards and
// distributed buckets retain the narrower security budgets. Edge rejects
// still expose a bounded Retry-After body/header so Desktop can recover
// without treating the backstop as an opaque 500.
//
// The express-rate-limit MemoryStore window starts at the first hit for a
// key, while the Postgres limiters in externalGfsRateLimit.ts use windows
// aligned to floor(now / 60_000). A burst that straddles a minute boundary
// can stay under the limit in each clock window and still exceed this one,
// so a backstop can be the first, and sometimes the only, denier for such a
// burst. That is why its denials report here rather than via reportDecision.
//
// express-rate-limit sets req.rateLimit before it calls the handler, with
// the key it counted and the window's reset time. `used` includes denied
// requests, so `used === limit + 1` is the first denial in the window.
const edgeRateLimitHandler =
(guard: ExternalGfsEdgeGuard) =>
(req: Request, res: ExpressResponse): void => {
const info = (req as Request & { rateLimit?: RateLimitInfo }).rateLimit
if (info === undefined || info.resetTime === undefined) {
throw new Error(`external GFS ${guard} backstop denied without rate limit state`)
}
const retryAfterSeconds = Math.max(
1,
Math.ceil((info.resetTime.getTime() - Date.now()) / 1000)
)
reportEdgeBackstopDenial({
req,
guard,
key: info.key,
retryAfterSeconds,
// Only the ingress and token backstops are mounted before
// attachExternalGfsAuthority; the other seven run after it.
authorityResolutionAvoided: guard === 'ingress' || guard === 'token',
firstDenialInWindow: info.used === info.limit + 1,
})
res.status(429).json({ error: 'Too Many Requests', retryAfterSeconds })
}
const resourceRateKey = externalGfsActorRateKey('resource')
const proxyReadRateKey = externalGfsActorRateKey('proxy-read')
const resourceMutationRateKey = externalGfsActorRateKey('resource-mutation')
const grantsReadRateKey = externalGfsActorRateKey('grants-read')
const grantsMutationRateKey = externalGfsActorRateKey('grants-mutation')
const sharesReadRateKey = externalGfsActorRateKey('shares-read')
const sharesMutationRateKey = externalGfsActorRateKey('shares-mutation')
const externalGfsIngressRateLimit = rateLimit({
windowMs: 60_000,
limit: config.externalGfsIngressRlPerMin,
standardHeaders: 'draft-7',
legacyHeaders: false,
keyGenerator: externalGfsIngressRateKey,
handler: edgeRateLimitHandler('ingress'),
})
const externalGfsTokenRouteRateLimit = rateLimit({
windowMs: 60_000,
limit: config.externalGfsTokenUserRlPerMin,
standardHeaders: 'draft-7',
legacyHeaders: false,
keyGenerator: externalGfsTokenRateKey,
handler: edgeRateLimitHandler('token'),
})
const externalGfsResourceRouteRateLimit = rateLimit({
windowMs: 60_000,
limit: externalGfsClassRlPerMin('resource'),
standardHeaders: 'draft-7',
legacyHeaders: false,
keyGenerator: resourceRateKey,
handler: edgeRateLimitHandler('resource'),
})
const externalGfsProxyReadRouteRateLimit = rateLimit({
windowMs: 60_000,
limit: externalGfsClassRlPerMin('proxy-read'),
standardHeaders: 'draft-7',
legacyHeaders: false,
keyGenerator: proxyReadRateKey,
handler: edgeRateLimitHandler('proxy-read'),
})
const externalGfsMutationRouteRateLimit = rateLimit({
windowMs: 60_000,
limit: externalGfsClassRlPerMin('resource-mutation'),
standardHeaders: 'draft-7',
legacyHeaders: false,
keyGenerator: resourceMutationRateKey,
handler: edgeRateLimitHandler('resource-mutation'),
})
const externalGfsGrantsReadRouteRateLimit = rateLimit({
windowMs: 60_000,
limit: externalGfsClassRlPerMin('grants-read'),
standardHeaders: 'draft-7',
legacyHeaders: false,
keyGenerator: grantsReadRateKey,
handler: edgeRateLimitHandler('grants-read'),
})
const externalGfsGrantsMutationRouteRateLimit = rateLimit({
windowMs: 60_000,
limit: externalGfsClassRlPerMin('grants-mutation'),
standardHeaders: 'draft-7',
legacyHeaders: false,
keyGenerator: grantsMutationRateKey,
handler: edgeRateLimitHandler('grants-mutation'),
})
const externalGfsSharesReadRouteRateLimit = rateLimit({
windowMs: 60_000,
limit: externalGfsClassRlPerMin('shares-read'),
standardHeaders: 'draft-7',
legacyHeaders: false,
keyGenerator: sharesReadRateKey,
handler: edgeRateLimitHandler('shares-read'),
})
const externalGfsSharesMutationRouteRateLimit = rateLimit({
windowMs: 60_000,
limit: externalGfsClassRlPerMin('shares-mutation'),
standardHeaders: 'draft-7',
legacyHeaders: false,
keyGenerator: sharesMutationRateKey,
handler: edgeRateLimitHandler('shares-mutation'),
})
// The source-IP guard intentionally precedes authentication and authority
// lookup. The authenticated external-rest-api boundary overwrites XFF with
// its trust-proxy-derived client address; externalGfsSourceIp accepts only
// that valid first IP, so a raw caller cannot select a bucket.
router.use('/external/gfs', externalGfsIngressRateLimit)
// Every gfs user route is on the Session-JWT plane: the user session token
// (x-user-session-token, forwarded by external-rest-api) is required.
router.use('/external/gfs', requireValidExternalSessionToken)
router.use('/external/gfs', attachExternalGfsRequestId)
// This boundary deliberately precedes attachExternalGfsAuthority. A rate
// rejection therefore performs no operator-link lookup or route-specific
// database/handler work; see externalGfsRateLimit.ts for the complete
// session/IP and effective-actor operation-class matrix.
router.use('/external/gfs', externalGfsPreResolutionRateLimit)
// ACL listing is still a privileged manage_acl operation, but it must not
// consume the smaller mutation budget: opening the Manage dialog performs
// several list/refetch reads before one visible grant/share action. Keep
// those reads in a distinct actor bucket from mutations. GET /grants and
// GET /shares share this one bucket, so its limit is the sum of the two
// read budgets; the per-class Postgres buckets and express backstops still
// cap each route at its own budget.
const externalGrantsReadRateLimit = rateLimitMiddleware({
bucketType: 'gfs_grants_external_read',
maxPerMinute: config.externalGfsGrantsReadRlPerMin + config.externalGfsSharesReadRlPerMin,
getBucketKey: req => {
const authority = (req as RequestWithExternalGfsAuthority).gfsAuthority
if (authority?.kind === 'linked-admin') {
return `gfsgrants-ext-read:linked-admin:${authority.controlAdminId}`
}
if (authority?.kind === 'user-session') {
return `gfsgrants-ext-read:user:${authority.desktopUserId}`
}
return 'gfsgrants-ext-read:__no_authority__'
},
// Like the Postgres buckets above, an uncountable request is refused
// rather than admitted unmetered (#764).
onBackendUnavailable: 'closed',
})
// Keep the existing mutation bucket identity for compatibility with
// telemetry and abuse controls; its budget is the shared mutation budget
// (externalGfsOperationRlPerMin, 90/min by default). Only read/list calls
// move to the separate read bucket above.
const externalGrantsMutationRateLimit = rateLimitMiddleware({
bucketType: 'gfs_grants_external',
maxPerMinute: config.externalGfsOperationRlPerMin,
getBucketKey: req => {
const authority = (req as RequestWithExternalGfsAuthority).gfsAuthority
if (authority?.kind === 'linked-admin') {
return `gfsgrants-ext:linked-admin:${authority.controlAdminId}`
}
if (authority?.kind === 'user-session') {
return `gfsgrants-ext:user:${authority.desktopUserId}`
}
return 'gfsgrants-ext:__no_authority__'
},
onBackendUnavailable: 'closed',
})
// ── token mint (mirror /external/rpc/token, but a gfs token sub=users.id) ──
router.post(
'/external/gfs/token',
externalGfsTokenRouteRateLimit,
asyncHandler(attachExternalGfsUserLifecycle),
asyncHandler(async (req: ExternalAuthedRequest, res) => {
const claims = req.externalAuth!
const body = (req.body ?? {}) as { drive?: unknown; scopes?: unknown }
const drive =
typeof body.drive === 'string' && body.drive.length > 0 ? body.drive : GFS_DEFAULT_DRIVE
const scopes = parseRequestedGfsScopes(body.scopes)
if (scopes === null) {
res.status(400).json({ error: 'invalid_gfs_scopes' })
return
}
// pathBindings: [] — the permission store is the source of truth; gfsc
// re-checks it on every op (same as the operator/human mint).
const { token, expiresInSeconds } = signGfsToken({
subject: claims.userId,
drive,
scopes,
pathBindings: [],
...(claims.authGeneration === undefined ? {} : { authGeneration: claims.authGeneration }),
principalType: 'user',
})
res.status(200).json({ token, expiresInSeconds })
})
)
// Indexed upload-v2 relay. Part PUTs stay a Node stream all the way from
// external-rest-api to the writer GFSC; lifecycle requests use the same
// writer-scoped token and never fall back to the legacy JSON/base64 path.
router.get(
'/external/gfs/capabilities',
gfsUploadAdmission,
asyncHandler(async (req: ExternalGfsUploadRequest, res) => {
// Capabilities describe the protocol, not a drive-scoped session. Keep
// an optional drive for token routing when supplied, but a global probe
// must remain valid without query parameters.
const rawQueryDrive = req.query.drive
if (rawQueryDrive !== undefined) {
if (
typeof rawQueryDrive !== 'string' ||
rawQueryDrive.length === 0 ||
rawQueryDrive !== rawQueryDrive.trim()
) {
res.status(400).json({ error: 'drive_invalid' })
return
}
}
const drive = rawQueryDrive === undefined ? GFS_DEFAULT_DRIVE : rawQueryDrive
await proxyUploadToGfsc(req, res, drive, 'GET', '/v1/capabilities')
})
)
router.post(
'/external/gfs/uploads',
requireCanonicalUploadDrive,
gfsUploadAdmission,
asyncHandler(async (req: ExternalGfsUploadRequest, res) => {
await proxyUploadToGfsc(req, res, canonicalUploadDrive(req), 'POST', '/v1/uploads')
})
)
router.head(
'/external/gfs/uploads/:id',
requireCanonicalUploadDrive,
gfsUploadAdmission,
asyncHandler(async (req: ExternalGfsUploadRequest, res) => {
if (!UUID_RE.test(String(req.params.id))) {
res.status(400).json({ error: 'resource_invalid' })
return
}
await proxyUploadToGfsc(
req,
res,
canonicalUploadDrive(req),
'HEAD',
`/v1/uploads/${encodeURIComponent(req.params.id)}`
)
})
)
router.get(
'/external/gfs/uploads/:id/status',
requireCanonicalUploadDrive,
gfsUploadAdmission,
asyncHandler(async (req: ExternalGfsUploadRequest, res) => {
if (!UUID_RE.test(String(req.params.id))) {
res.status(400).json({ error: 'resource_invalid' })
return
}
await proxyUploadToGfsc(
req,
res,
canonicalUploadDrive(req),
'GET',
`/v1/uploads/${encodeURIComponent(req.params.id)}/status`,
{
limit: typeof req.query.limit === 'string' ? req.query.limit : undefined,
cursor: typeof req.query.cursor === 'string' ? req.query.cursor : undefined,
}
)
})
)
router.put(
'/external/gfs/uploads/:id/parts/:part',
requireCanonicalUploadDrive,
gfsUploadAdmission,
asyncHandler(async (req: ExternalGfsUploadRequest, res) => {
const id = String(req.params.id)
const part = String(req.params.part)
if (!UUID_RE.test(id) || !/^[0-9]+$/.test(part)) {
res.status(400).json({ error: 'resource_invalid' })
return
}
await proxyUploadToGfsc(
req,
res,
canonicalUploadDrive(req),
'PUT',
`/v1/uploads/${encodeURIComponent(id)}/parts/${part}`
)
})
)
for (const action of ['pause', 'resume', 'complete'] as const) {
router.post(
`/external/gfs/uploads/:id/${action}`,
requireCanonicalUploadDrive,
gfsUploadAdmission,
asyncHandler(async (req: ExternalGfsUploadRequest, res) => {
if (!UUID_RE.test(String(req.params.id))) {
res.status(400).json({ error: 'resource_invalid' })
return
}
await proxyUploadToGfsc(
req,
res,
canonicalUploadDrive(req),
'POST',
`/v1/uploads/${encodeURIComponent(req.params.id)}/${action}`
)
})
)
}
router.delete(
'/external/gfs/uploads/:id',
requireCanonicalUploadDrive,
gfsUploadAdmission,
asyncHandler(async (req: ExternalGfsUploadRequest, res) => {
if (!UUID_RE.test(String(req.params.id))) {
res.status(400).json({ error: 'resource_invalid' })
return
}
await proxyUploadToGfsc(
req,
res,
canonicalUploadDrive(req),
'DELETE',
`/v1/uploads/${encodeURIComponent(req.params.id)}`
)
})
)
// Public token mint above is deliberately user-only. Effective linked-admin
// authority is resolved only for the internal broker routes below.
router.use('/external/gfs', asyncHandler(attachExternalGfsAuthority))
router.use('/external/gfs', externalGfsResolvedOperationRateLimit)
// ── delegation: reuse the EXISTING grant/share handlers (caller-agnostic) ──
// resolveCaller(req) reads req.externalAuth → user:<id> plus all active team
// memberships resolved here; assertMayGrant enforces no-escalation (a user may
// grant only bits it holds, within its subtree).
// The grants list is delegation metadata naming third-party subjects, so
// reading it requires the same manage_acl authority as mutating it
// (view-ACL = manage-ACL); handleGrantListForCaller enforces that.
router.get(
'/external/gfs/grants',
externalGfsGrantsReadRouteRateLimit,
externalGrantsReadRateLimit,
asyncHandler(attachExternalGfsCallerSubjects),
asyncHandler(handleGrantListForCaller)
)
router.put(
'/external/gfs/grants',
externalGfsGrantsMutationRouteRateLimit,
externalGrantsMutationRateLimit,
asyncHandler(attachExternalGfsCallerSubjects),
asyncHandler(assertHostTargetsWithinCallerAgents),
asyncHandler(handleGrantWrite)
)
router.delete(
'/external/gfs/grants/:id',
externalGfsGrantsMutationRouteRateLimit,
externalGrantsMutationRateLimit,
asyncHandler(attachExternalGfsCallerSubjects),
asyncHandler(handleGrantDelete)
)
router.post(
'/external/gfs/shares',
externalGfsSharesMutationRouteRateLimit,
externalGrantsMutationRateLimit,
asyncHandler(attachExternalGfsCallerSubjects),
asyncHandler(handleShareWrite)
)
router.get(
'/external/gfs/shares',
externalGfsSharesReadRouteRateLimit,
externalGrantsReadRateLimit,
asyncHandler(attachExternalGfsCallerSubjects),
asyncHandler(handleShareListForCaller)
)
router.delete(
'/external/gfs/shares/:id',
externalGfsSharesMutationRouteRateLimit,
externalGrantsMutationRateLimit,
asyncHandler(attachExternalGfsCallerSubjects),
asyncHandler(handleShareDelete)
)
// ── affordances: which bits does the caller hold on a resource? ──
// Drives the Desktop delegation panel (delegationAffordances). Reuses the
// EXISTING checkAccess (same allow() engine as assertMayGrant). Read-only.
router.get(
'/external/gfs/resources/:id/affordances',
externalGfsResourceRouteRateLimit,
asyncHandler(attachExternalGfsCallerSubjects),
asyncHandler(async (req: ExternalAuthedRequest, res) => {
const caller = resolveCaller(req)
const drive = driveOf(req.query.drive)
const resourceId = String(req.params.id)
if (!UUID_RE.test(resourceId)) {
res.status(400).json({ error: 'resource_invalid' })
return
}
// One store load → all held bits (vs checkAccess per-bit). Same engine.
const held = await heldPermissions(pool, caller, drive, resourceId)
res.status(200).json({ held, isOperator: caller.isOperator })
})
)
router.patch(
'/external/gfs/resources/:id',
externalGfsMutationRouteRateLimit,
asyncHandler(attachExternalGfsCallerSubjects),
asyncHandler(handlePatch)
)
router.post(
'/external/gfs/resources/:id/children',
externalGfsMutationRouteRateLimit,
asyncHandler(async (req: ExternalAuthedRequest, res) => {
const rid = String(req.params.id)
if (!UUID_RE.test(rid)) {
res.status(400).json({ error: 'resource_invalid' })
return
}
await proxyMutationToGfsc(
req,
res,
driveOf(req.query.drive ?? (req.body as { drive?: unknown } | undefined)?.drive),
'POST',
`/v1/resources/${encodeURIComponent(ridOf(rid))}/children`,
GFS_WRITE_SCOPE
)
})
)
router.put(
'/external/gfs/resources/:id/content',
externalGfsMutationRouteRateLimit,
asyncHandler(async (req: ExternalAuthedRequest, res) => {
const rid = String(req.params.id)
if (!UUID_RE.test(rid)) {
res.status(400).json({ error: 'resource_invalid' })
return
}
await proxyMutationToGfsc(
req,
res,
driveOf(req.query.drive ?? (req.body as { drive?: unknown } | undefined)?.drive),
'PUT',
`/v1/resources/${encodeURIComponent(ridOf(rid))}/content`,
GFS_WRITE_SCOPE
)
})
)
router.delete(
'/external/gfs/resources/:id',
externalGfsMutationRouteRateLimit,
asyncHandler(async (req: ExternalAuthedRequest, res) => {
const rid = String(req.params.id)
if (!UUID_RE.test(rid)) {
res.status(400).json({ error: 'resource_invalid' })
return
}
await proxyMutationToGfsc(
req,
res,
driveOf(req.query.drive ?? (req.body as { drive?: unknown } | undefined)?.drive),
'DELETE',
`/v1/resources/${encodeURIComponent(ridOf(rid))}`,
GFS_DELETE_SCOPE
)
})
)
router.get(
'/external/gfs/resources',
externalGfsResourceRouteRateLimit,
asyncHandler(async (req: ExternalAuthedRequest, res) => {
const drive = driveOf(req.query.drive)
const authority = authorityOf(req as ExternalGfsRequest)
if (authority.kind === 'linked-admin') {
const root = await new DbResolveStore(pool).getByPath(drive, '/')
if (!root) {
res.status(404).json({
ok: false,
error: { code: 'drive_not_seeded', message: 'drive root is not seeded' },
})
return
}
try {
const page = await listChildrenPaged(new DbChildrenStore(pool), drive, root.resourceId, {
limit: req.query.limit,
cursor: typeof req.query.cursor === 'string' ? req.query.cursor : undefined,
})
res.status(200).json({
ok: true,
data: { ...page, rootResourceId: root.resourceId, view: 'operator' },
})
} catch (error) {
if (error instanceof GfsTreeError) {
res.status(400).json({ ok: false, error: { code: error.code, message: error.message } })
return
}
throw error
}
return
}
const subjects = await externalCallerSubjects(req)
const { types, ids } = subjectColumns(subjects)
if (types.length === 0) {
res.status(200).json({ ok: true, data: { items: [], nextCursor: null } })
return
}
let after: { n: string; i: string } | undefined
try {
after = typeof req.query.cursor === 'string' ? decodeCursor(req.query.cursor) : undefined
} catch (err) {
if (err instanceof GfsTreeError) {
res.status(400).json({ ok: false, error: { code: err.code, message: err.message } })
return
}
throw err
}
const limit =
req.query.limit == null ? ACCESSIBLE_RESOURCE_DEFAULT_LIMIT : clampLimit(req.query.limit)
const result = await pool.query(
`WITH requested_subjects(subject_type, subject_id) AS (
SELECT * FROM unnest($2::text[], $3::text[])
),
accessible AS (
SELECT g.resource_id, g.permissions, g.inherit AS covers_descendants, 'grant'::text AS source
FROM gfs_grants g
JOIN requested_subjects s
ON s.subject_type = g.subject_type AND s.subject_id = g.subject_id
WHERE g.drive = $1 AND 'read' = ANY(g.permissions)
UNION ALL
SELECT sh.resource_id, sh.permissions, sh.include_descendants AS covers_descendants, 'share'::text AS source
FROM gfs_shares sh
JOIN requested_subjects s
ON s.subject_type = sh.subject_type AND s.subject_id = sh.subject_id
WHERE sh.drive = $1 AND 'read' = ANY(sh.permissions)
)
SELECT r.resource_id,
r.drive,
r.parent_resource_id,
r.name,
r.kind,
r.path_cache,
r.version,
r.bytes,
r.updated_at,
array_remove(array_agg(DISTINCT a.source), NULL) AS sources,
array_remove(array_agg(DISTINCT p.permission), NULL) AS permissions,
bool_or(a.covers_descendants) AS covers_descendants
FROM accessible a
JOIN gfs_resources r
ON r.drive = $1 AND r.resource_id = a.resource_id AND r.deleted_at IS NULL
LEFT JOIN LATERAL unnest(a.permissions) AS p(permission) ON true
WHERE ($4::text IS NULL OR (r.name, r.resource_id) > ($4, $5::uuid))
GROUP BY r.resource_id, r.drive, r.parent_resource_id, r.name, r.kind, r.path_cache, r.version, r.bytes, r.updated_at
ORDER BY r.name, r.resource_id
LIMIT $6`,
[drive, types, ids, after?.n ?? null, after?.i ?? null, limit + 1]
)
const rows = result.rows as Array<{
resource_id: string
drive: string
parent_resource_id: string | null
name: string
kind: 'file' | 'directory'
path_cache: string | null
version: number
bytes: number
updated_at: unknown
sources: string[]
permissions: string[]
covers_descendants: boolean
}>
const page = rows.length > limit ? rows.slice(0, limit) : rows
const last = page[page.length - 1]
res.status(200).json({
ok: true,
data: {
items: page.map(row => {
const rid = ridOf(String(row.resource_id))
return {
resourceId: String(row.resource_id),
rid,
gfsUri: `gfs://${row.drive}/${rid}`,
drive: row.drive,
parentResourceId: row.parent_resource_id ? String(row.parent_resource_id) : null,
name: String(row.name),
kind: row.kind,
path: row.path_cache,
version: Number(row.version ?? 0),
bytes: Number(row.bytes ?? 0),
updatedAt: toIsoTimestamp(row.updated_at),
sources: row.sources ?? [],
permissions: row.permissions ?? [],
coversDescendants: Boolean(row.covers_descendants),
}
}),
nextCursor:
rows.length > limit && last ? encodeCursor(last.name, String(last.resource_id)) : null,
},
})
})
)
// ── read: resolve / list-children / download — proxied to gfsc with a freshly
// minted USER read token (sub=users.id). gfsc authorizes against the store
// (deny-by-default), so a user only reads what it is granted. GET only. ──
router.get(
'/external/gfs/resolve',
externalGfsResourceRouteRateLimit,
asyncHandler(async (req: ExternalAuthedRequest, res) => {
const uri = typeof req.query.uri === 'string' ? req.query.uri : ''
if (!uri) {
res.status(400).json({ error: 'uri_required' })
return
}
if (uri.length > MAX_GFS_URI_LEN) {
res.status(400).json({ error: 'uri_too_long' })
return
}
await proxyReadToGfsc(
req,
res,
driveOf(req.query.drive),
`/v1/resolve?uri=${encodeURIComponent(uri)}`
)
})
)
router.get(
'/external/gfs/resources/:id/children',
externalGfsResourceRouteRateLimit,
asyncHandler(async (req: ExternalAuthedRequest, res) => {
const rid = String(req.params.id)
if (!UUID_RE.test(rid)) {
res.status(400).json({ error: 'resource_invalid' })
return
}
const drive = driveOf(req.query.drive)
const q = new URLSearchParams()
q.set('drive', drive)
if (typeof req.query.limit === 'string') q.set('limit', req.query.limit)
if (typeof req.query.cursor === 'string') q.set('cursor', req.query.cursor)
await proxyReadToGfsc(
req,
res,
drive,
`/v1/resources/${encodeURIComponent(rid)}/children?${q.toString()}`
)
})
)
router.get(
'/external/gfs/proxy/:rid',
externalGfsProxyReadRouteRateLimit,
asyncHandler(async (req: ExternalAuthedRequest, res) => {
const rid = String(req.params.rid)
if (!UUID_RE.test(rid)) {
res.status(400).json({ error: 'resource_invalid' })
return
}
await proxyReadToGfsc(
req,
res,
driveOf(req.query.drive),
`/v1/resources/${encodeURIComponent(rid)}/content`
)
})
)
return router
}
/**
* Mint a short-lived USER read token (sub=users.id, gfs.read) and forward a GET
* to gfsc, streaming the response back. Mirrors `routes/gfs/proxy.ts` but the
* principal is the user, not the operator — gfsc re-checks the store, so this
* grants nothing the user is not already entitled to.
*/
async function proxyReadToGfsc(
req: ExternalAuthedRequest,
res: import('express').Response,
drive: string,
gfscPath: string
): Promise<void> {
const authority = authorityOf(req as ExternalGfsRequest)
const { token } = signGfsToken({
subject: authority.tokenSubject,
drive,
scopes: [GFS_READ_SCOPE],
...(authority.authGeneration === undefined ? {} : { authGeneration: authority.authGeneration }),
principalType: authority.kind === 'linked-admin' ? 'control-admin' : 'user',
...(authority.kind === 'linked-admin'
? {
brokeredAuthority: {
desktopUserId: authority.desktopUserId,
controlAdminId: authority.controlAdminId,
authoritySource: authority.authoritySource,
linkLineageId: authority.linkLineageId,
linkGeneration: authority.linkGeneration,
desktopUserGeneration: authority.desktopUserGeneration,
},
}
: {}),
})
const target = `${config.gfscBaseUrl.replace(/\/+$/, '')}${gfscPath}`
let upstream: Response
// Header-only deadline: bound the wait for gfsc to START responding, but never
// the streamed download body — a large/slow read must not be truncated
// mid-stream by the mutation budget. Cleared once headers arrive.
const readDeadline = new AbortController()
const readTimer = setTimeout(() => readDeadline.abort(), config.gfscProxyTimeoutMs)
try {
upstream = await fetch(target, {
method: 'GET',
headers: {
authorization: `Bearer ${token}`,
'x-request-id': (req as ExternalGfsRequest).gfsRequestId!,
},
signal: readDeadline.signal,
})
} catch (err) {
const timedOut =
readDeadline.signal.aborted || (err instanceof Error && err.name === 'TimeoutError')
rootLogger.error(
{ err, gfscPath, timeoutMs: config.gfscProxyTimeoutMs },
timedOut
? 'gfs external read proxy: gfsc fetch timed out'
: 'gfs external read proxy: gfsc fetch failed'
)
res.status(timedOut ? 504 : 502).json({ error: timedOut ? 'gfsc_timeout' : 'gfsc_unreachable' })
return
} finally {
clearTimeout(readTimer)
}
if (upstream.status >= 400) {
// Error envelopes are small JSON: buffer, LOG, forward verbatim (a gfsc 5xx on a
// read was invisible at this hop before). Success bodies keep streaming below.
const errorBody = await upstream.text()
if (upstream.status >= 500) {
rootLogger.error(
{ gfscPath, status: upstream.status, body: errorBody.slice(0, 2048) },
'gfs external read proxy: gfsc upstream error'
)
}
res.status(upstream.status)
const ct = upstream.headers.get('content-type')
if (ct) res.setHeader('content-type', ct)
res.send(errorBody)
return
}
res.status(upstream.status)
for (const h of ['content-type', 'content-disposition', 'content-length']) {
const v = upstream.headers.get(h)
if (v) res.setHeader(h, v)
}
if (!upstream.body) {
res.end()
return
}
const reader = upstream.body.getReader()
try {
for (;;) {
const { done, value } = await reader.read()
if (done) break
if (value) res.write(Buffer.from(value))
}
res.end()
} catch (err) {
// Mid-stream gfsc read failure (pod restart, network abort). Surface it —
// never swallow silently. If headers are already committed we can only end
// the (now-truncated) response; the logged error is the operator's trace.
rootLogger.error({ err, gfscPath }, 'gfs external read proxy: gfsc upstream stream error')
if (!res.headersSent) res.status(502).json({ error: 'gfsc upstream error' })
else res.end()
}
}
async function proxyMutationToGfsc(
req: ExternalAuthedRequest,
res: import('express').Response,
drive: string,
method: 'POST' | 'PUT' | 'DELETE',
gfscPath: string,
scope: typeof GFS_WRITE_SCOPE | typeof GFS_DELETE_SCOPE
): Promise<void> {
const authority = authorityOf(req as ExternalGfsRequest)
const { token } = signGfsToken({
subject: authority.tokenSubject,
drive,
scopes: [scope],
...(authority.authGeneration === undefined ? {} : { authGeneration: authority.authGeneration }),
principalType: authority.kind === 'linked-admin' ? 'control-admin' : 'user',
...(authority.kind === 'linked-admin'
? {
brokeredAuthority: {
desktopUserId: authority.desktopUserId,
controlAdminId: authority.controlAdminId,
authoritySource: authority.authoritySource,
linkLineageId: authority.linkLineageId,
linkGeneration: authority.linkGeneration,
desktopUserGeneration: authority.desktopUserGeneration,
},
}
: {}),
})
const target = `${config.gfscWriteBaseUrl.replace(/\/+$/, '')}${gfscPath}`
const headers: Record<string, string> = { 'content-type': 'application/json' }
headers['author' + 'ization'] = ['Bearer', token].join(' ')
headers['x-request-id'] = (req as ExternalGfsRequest).gfsRequestId!
let upstream: Response
// A TOTAL deadline (not the header-only one the streaming read proxies use):
// a mutation response is a small JSON body, so bounding the whole fetch+read
// exchange is correct — the read proxies stream large bodies and must clear the
// timer after headers, but here we want the whole exchange bounded. Without a
// timeout a hung gfsc pinned the desktop upload indefinitely (#281/H1).
const deadline = AbortSignal.timeout(config.gfscProxyTimeoutMs)
try {
upstream = await fetch(target, {
method,
headers,
body: JSON.stringify(req.body ?? {}),
signal: deadline,
})
} catch (err) {
const timedOut = deadline.aborted || (err instanceof Error && err.name === 'TimeoutError')
rootLogger.error(
{ err, gfscPath, method, timeoutMs: config.gfscProxyTimeoutMs },
timedOut
? 'gfs external mutation proxy: gfsc fetch timed out'
: 'gfs external mutation proxy: gfsc fetch failed'
)
res.status(timedOut ? 504 : 502).json({ error: timedOut ? 'gfsc_timeout' : 'gfsc_unreachable' })
return
}
// The same deadline also bounds this response-body read. If gfsc sent headers
// and then stalled the body, text() rejects — classify it (504/502) instead of
// letting it reject uncaught into a generic 500. Read BEFORE committing status,
// so a read failure can still set the right code.
let text: string
try {
text = await upstream.text()
} catch (err) {
const timedOut =
deadline.aborted ||
(err instanceof Error && (err.name === 'TimeoutError' || err.name === 'AbortError'))
rootLogger.error(
{ err, gfscPath, method, status: upstream.status, timeoutMs: config.gfscProxyTimeoutMs },
'gfs external mutation proxy: gfsc response body read failed'
)
res.status(timedOut ? 504 : 502).json({ error: timedOut ? 'gfsc_timeout' : 'gfsc_unreachable' })
return
}
res.status(upstream.status)
const contentType = upstream.headers.get('content-type')
if (contentType) res.setHeader('content-type', contentType)
// Never silent: surface a gfsc 4xx/5xx at this hop (the base64 RangeError 500 was
// invisible here before) while forwarding the body verbatim.
if (upstream.status >= 500) {
rootLogger.error(
{ gfscPath, method, status: upstream.status, body: text.slice(0, 2048) },
'gfs external mutation proxy: gfsc upstream error'
)
} else if (upstream.status >= 400) {
rootLogger.warn(
{ gfscPath, method, status: upstream.status, body: text.slice(0, 2048) },
'gfs external mutation proxy: gfsc upstream client error'
)
}
res.send(text)
}
async function proxyUploadToGfsc(
req: ExternalGfsUploadRequest,
res: import('express').Response,
drive: string,
method: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE',
gfscPath: string,
query?: Record<string, string | undefined>
): Promise<void> {
const claims = req.externalAuth!
const { token } = signGfsToken({
subject: claims.userId,
drive,
scopes: [GFS_WRITE_SCOPE],
// GFSC resolves user authority against users.lifecycle_version on every
// request. The session generation must cross this relay boundary or a
// valid external session is rejected as an un-fenced user token.
authGeneration: claims.authGeneration,
principalType: 'user',
})
const targetUrl = new URL(`${config.gfscWriteBaseUrl.replace(/\/+$/, '')}${gfscPath}`)
for (const [key, value] of Object.entries(query ?? {})) {
if (value !== undefined && value !== '') targetUrl.searchParams.set(key, value)
}
const target = targetUrl.toString()
const rawPart = method === 'PUT' && /\/parts\/[0-9]+$/.test(gfscPath)
const headers: Record<string, string> = { authorization: `Bearer ${token}` }
if (rawPart) {
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') headers[name] = value
}
headers['content-length'] = String(req.gfsUploadDeclaredBytes)
} else if (method !== 'GET' && method !== 'HEAD') {
headers['content-type'] = 'application/json'
}
const controller = new AbortController()
let timedOut = false
const timer = setTimeout(
() => {
timedOut = true
controller.abort()
},
Math.max(config.gfscProxyTimeoutMs, 600_000)
)
let clientAborted = false
const abortForClientDisconnect = (): void => {
clientAborted = true
controller.abort()
}
req.once('aborted', abortForClientDisconnect)
const declaredBytes = req.gfsUploadDeclaredBytes
if (rawPart && (!Number.isSafeInteger(declaredBytes) || !declaredBytes)) {
throw new Error('upload admission did not provide a declared byte count')
}
const observedPart = rawPart
? createObservedGfsUploadPartBody(req, declaredBytes as number, config.gfsUploadMaxPartBytes)
: null
const init: RequestInit & { duplex?: 'half' } = {
method,
headers,
body:
method === 'GET' || method === 'HEAD'
? undefined
: rawPart
? (observedPart!.body as unknown as BodyInit)
: JSON.stringify(req.body ?? {}),
signal: controller.signal,
}
if (rawPart) init.duplex = 'half'
let upstream: Response
try {
upstream = await fetch(target, init)
} catch (error) {
const validationError = observedPart?.validationError()
if (validationError) {
res.status(validationError.status).json({ error: validationError.code })
return
}
if (clientAborted) return
rootLogger.error(
{ err: error, gfscPath, method },
timedOut ? 'gfs external upload proxy timed out' : 'gfs external upload proxy failed'
)
res.status(timedOut ? 504 : 502).json({ error: timedOut ? 'gfsc_timeout' : 'gfsc_unreachable' })
return
} finally {
clearTimeout(timer)
req.off('aborted', abortForClientDisconnect)
}
if (upstream.status >= 400) {
const body = await upstream.text()
if (upstream.status >= 500)
rootLogger.error(
{ gfscPath, method, status: upstream.status, body: body.slice(0, 2048) },
'gfs external upload upstream error'
)
res.status(upstream.status)
for (const name of GFS_UPLOAD_RESPONSE_HEADERS) {
const value = upstream.headers.get(name)
if (value) res.setHeader(name, value)
}
res.send(body)
return
}
res.status(upstream.status)
for (const name of GFS_UPLOAD_RESPONSE_HEADERS) {
const value = upstream.headers.get(name)
if (value) res.setHeader(name, value)
}
if (!upstream.body) {
res.end()
return
}
try {
for await (const chunk of upstream.body as unknown as AsyncIterable<Uint8Array>)
res.write(Buffer.from(chunk))
res.end()
} catch (error) {
rootLogger.error({ err: error, gfscPath, method }, 'gfs external upload response stream failed')
if (!res.headersSent) res.status(502).json({ error: 'gfsc upstream error' })
else res.end()
}
}