Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

merge: sync GFS upload with current dev

Alfredo Lopezc774535b4945
diff --cc control-api/src/db.ts
index 2bf7dfede,4d5199213..632a1498f
--- a/control-api/src/db.ts
+++ b/control-api/src/db.ts
@@@ -5469,17 -5846,29 +5851,41 @@@ export const CONTROL_API_MIGRATIONS: Db
apply: reconcilePluginWorkloadSdkRuntimeContracts,
},
{
- version: '0091_gfs_upload_sessions',
+ version: '0091_gfs_desktop_operator_links',
+ apply: applyGfsDesktopOperatorLinksSchema,
+ },
+ {
+ version: '0092_gfs_audit_actor_correlation',
+ apply: applyGfsAuditActorCorrelationSchema,
+ },
+ {
+ version: '0093_gfs_desktop_operator_link_generations',
+ apply: evolveGfsDesktopOperatorLinksToGenerations,
+ },
+ {
+ version: '0094_desktop_user_retirement_lifecycle',
+ apply: applyDesktopUserRetirementLifecycleSchema,
+ },
+ {
+ version: '0095_gfs_lifecycle_authority_projection',
+ apply: applyGfsLifecycleAuthorityProjectionSchema,
+ },
+ {
+ version: '0096_control_admin_session_version_default',
+ apply: applyControlAdminSessionVersionDefaultSchema,
+ },
++ {
++ version: '0097_gfs_upload_sessions',
+ apply: applyGfsUploadSessionSchema,
+ },
+ {
- version: '0092_gfs_upload_cleanup_receipt',
++ version: '0098_gfs_upload_cleanup_receipt',
+ apply: applyGfsUploadCleanupSchema,
+ },
+ {
- version: '0093_gfs_upload_finalizing_recovery',
++ version: '0099_gfs_upload_finalizing_recovery',
+ apply: applyGfsUploadFinalizingSchema,
+ },
]
async function consolidateWorkflowAllowedUsersToTriggers(db: DbClient): Promise<void> {
diff --cc control-api/src/middleware/externalGfsRateLimit.ts
index 000000000,bd7b8f1ab..94c726acd
mode 000000,100644..100644
--- a/control-api/src/middleware/externalGfsRateLimit.ts
+++ b/control-api/src/middleware/externalGfsRateLimit.ts
@@@ -1,0 -1,351 +1,377 @@@
+ import type { NextFunction, Request, Response } from 'express'
+ import { createHash } from 'node:crypto'
+ import { isIP } from 'node:net'
+ import { config } from '../config.js'
+ import type { ExternalGfsAuthority } from '../gfs/externalAuthority.js'
+ import { rootLogger } from '../observability/logger.js'
+ import {
+ externalGfsRateLimitDurationSeconds,
+ externalGfsRateLimitRequestsTotal,
+ } from '../observability/metrics.js'
+ import { type RateLimitCheck, checkAndIncrement } from '../services/rateLimiterService.js'
+
+ /**
+ * The external Desktop GFS surface has a small, explicit operation matrix.
+ * Keeping the classifier here makes a newly added handler fail review/tests
+ * until it is assigned to a bounded class; there is no route-level default
+ * that can silently bypass the authority-resolution DoS boundary.
+ */
+ export type ExternalGfsOperationClass =
+ | 'token'
+ | 'resource'
+ | 'proxy-read'
+ | 'resource-mutation'
+ | 'grants-read'
+ | 'grants-mutation'
+ | 'shares-read'
+ | 'shares-mutation'
+
+ export type ExternalGfsOperation = {
+ operationClass: ExternalGfsOperationClass
+ route: string
+ }
+
+ type ExternalGfsRateLimitPhase = 'pre-resolution' | 'resolved-operation'
+ type Bucket = { key: string; maxPerMinute: number }
+
+ type ExternalGfsAuthedRequest = Request & {
+ externalAuth?: { userId?: string }
+ gfsAuthority?: ExternalGfsAuthority
+ }
+
+ const GFS_PREFIX = '/external/gfs'
+
+ function pathWithinExternalGfs(req: Request): string {
+ // At this router's middleware layer Express has already removed the route
+ // prefix from req.path, while req.baseUrl retains it. This reconstruction
+ // works both when the router is mounted beneath /api/v1 in production and
+ // when it is mounted directly in a focused route test.
+ const mountedPath = `${req.baseUrl ?? ''}${req.path ?? ''}`
+ const marker = mountedPath.lastIndexOf(GFS_PREFIX)
+ if (marker >= 0) return mountedPath.slice(marker + GFS_PREFIX.length) || '/'
+
+ const originalPath = String(req.originalUrl ?? '').split('?', 1)[0]
+ const originalMarker = originalPath.lastIndexOf(GFS_PREFIX)
+ if (originalMarker >= 0) return originalPath.slice(originalMarker + GFS_PREFIX.length) || '/'
+
+ return req.path || '/'
+ }
+
+ /** Map every external GFS handler to exactly one approved rate class. */
+ export function externalGfsOperationFor(
+ req: Pick<Request, 'method' | 'baseUrl' | 'path' | 'originalUrl'>
+ ): ExternalGfsOperation | null {
+ const path = pathWithinExternalGfs(req as Request)
+ const method = req.method.toUpperCase()
+
+ if (method === 'POST' && path === '/token') {
+ return { operationClass: 'token', route: `${GFS_PREFIX}/token` }
+ }
+ if (path === '/resolve' && method === 'GET') {
+ return { operationClass: 'resource', route: `${GFS_PREFIX}/resolve` }
+ }
++ // Indexed resumable-upload routes are part of the same public GFS boundary.
++ // Keep capability/status probes in the read budget and create/part/lifecycle
++ // mutations in the operation budget so the pre-resolution gate cannot turn a
++ // newly added upload handler into an unmetered path.
++ if (path === '/capabilities' && method === 'GET') {
++ return { operationClass: 'resource', route: `${GFS_PREFIX}/capabilities` }
++ }
++ if (path === '/uploads' && method === 'POST') {
++ return { operationClass: 'resource-mutation', route: `${GFS_PREFIX}/uploads` }
++ }
++ if (/^\/uploads\/[^/]+$/.test(path)) {
++ return method === 'HEAD'
++ ? { operationClass: 'resource', route: `${GFS_PREFIX}/uploads/:id` }
++ : method === 'DELETE'
++ ? { operationClass: 'resource-mutation', route: `${GFS_PREFIX}/uploads/:id` }
++ : null
++ }
++ if (/^\/uploads\/[^/]+\/status$/.test(path) && method === 'GET') {
++ return { operationClass: 'resource', route: `${GFS_PREFIX}/uploads/:id/status` }
++ }
++ if (/^\/uploads\/[^/]+\/parts\/[0-9]+$/.test(path) && method === 'PUT') {
++ return { operationClass: 'resource-mutation', route: `${GFS_PREFIX}/uploads/:id/parts/:part` }
++ }
++ if (/^\/uploads\/[^/]+\/(pause|resume|complete)$/.test(path) && method === 'POST') {
++ return { operationClass: 'resource-mutation', route: `${GFS_PREFIX}/uploads/:id/:action` }
++ }
+ if (path === '/resources' && method === 'GET') {
+ return { operationClass: 'resource', route: `${GFS_PREFIX}/resources` }
+ }
+ if (/^\/resources\/[^/]+\/affordances$/.test(path) && method === 'GET') {
+ return { operationClass: 'resource', route: `${GFS_PREFIX}/resources/:id/affordances` }
+ }
+ if (/^\/resources\/[^/]+\/children$/.test(path)) {
+ return method === 'GET'
+ ? { operationClass: 'resource', route: `${GFS_PREFIX}/resources/:id/children` }
+ : method === 'POST'
+ ? { operationClass: 'resource-mutation', route: `${GFS_PREFIX}/resources/:id/children` }
+ : null
+ }
+ if (/^\/resources\/[^/]+\/content$/.test(path) && method === 'PUT') {
+ return { operationClass: 'resource-mutation', route: `${GFS_PREFIX}/resources/:id/content` }
+ }
+ if (/^\/resources\/[^/]+$/.test(path)) {
+ return method === 'PATCH' || method === 'DELETE'
+ ? { operationClass: 'resource-mutation', route: `${GFS_PREFIX}/resources/:id` }
+ : null
+ }
+ if (/^\/proxy\/[^/]+$/.test(path) && method === 'GET') {
+ return { operationClass: 'proxy-read', route: `${GFS_PREFIX}/proxy/:rid` }
+ }
+ if (path === '/grants' && method === 'GET') {
+ return { operationClass: 'grants-read', route: `${GFS_PREFIX}/grants` }
+ }
+ if (path === '/grants' && method === 'PUT') {
+ return { operationClass: 'grants-mutation', route: `${GFS_PREFIX}/grants` }
+ }
+ if (/^\/grants\/[^/]+$/.test(path) && method === 'DELETE') {
+ return { operationClass: 'grants-mutation', route: `${GFS_PREFIX}/grants/:id` }
+ }
+ if (path === '/shares' && method === 'GET') {
+ return { operationClass: 'shares-read', route: `${GFS_PREFIX}/shares` }
+ }
+ if (path === '/shares' && method === 'POST') {
+ return { operationClass: 'shares-mutation', route: `${GFS_PREFIX}/shares` }
+ }
+ if (/^\/shares\/[^/]+$/.test(path) && method === 'DELETE') {
+ return { operationClass: 'shares-mutation', route: `${GFS_PREFIX}/shares/:id` }
+ }
+ return null
+ }
+
+ function digest(value: string): string {
+ return createHash('sha256').update(value).digest('hex')
+ }
+
+ function authenticatedSessionDigest(req: Request): string | null {
+ const token = req.header('x-user-session-token')?.trim()
+ return token ? digest(token) : null
+ }
+
+ /**
+ * Source address forwarded by the authenticated external-rest-api boundary.
+ *
+ * The first XFF element is accepted only when it is an IP literal. This is
+ * intentionally exported for the recognisable edge limiter as well as the
+ * durable Postgres buckets below: the two guards must meter the same trusted
+ * client identity, never a caller-selected header fragment.
+ */
+ export function externalGfsSourceIp(req: Request): string {
+ // The app-level /external gate accepts only the authenticated
+ // external-rest-api service. That service overwrites X-Forwarded-For with
+ // its proxy-attested client address; profile-control-funnel then appends its
+ // pod peer. Read the validated first element so the pre-resolution IP bucket
+ // remains per client rather than collapsing every Desktop installation into
+ // the funnel's address. Direct/test callers fall back to Express's normal
+ // proxy-aware address.
+ const forwardedIp = req.header('x-forwarded-for')?.split(',', 1)[0]?.trim()
+ const ip =
+ forwardedIp && isIP(forwardedIp) !== 0
+ ? forwardedIp
+ : req.ip || req.socket.remoteAddress || '__unknown_peer__'
+ return ip
+ }
+
+ function sourceIpDigest(req: Request): string {
+ return digest(externalGfsSourceIp(req))
+ }
+
+ function operationLimit(operationClass: ExternalGfsOperationClass): number {
+ return operationClass === 'resource' ||
+ operationClass === 'proxy-read' ||
+ operationClass === 'grants-read' ||
+ operationClass === 'shares-read'
+ ? config.externalGfsReadRlPerMin
+ : config.externalGfsOperationRlPerMin
+ }
+
+ function applyRateLimitHeaders(
+ res: Response,
+ result: RateLimitCheck,
+ maxPerMinute: number
+ ): number {
+ const retryAfterSeconds = Math.max(1, Math.ceil((result.resetMs - Date.now()) / 1000))
+ res.setHeader('Retry-After', String(retryAfterSeconds))
+ res.setHeader('X-RateLimit-Limit', String(maxPerMinute))
+ res.setHeader('X-RateLimit-Remaining', '0')
+ res.setHeader('X-RateLimit-Reset', String(Math.floor(result.resetMs / 1000)))
+ return retryAfterSeconds
+ }
+
+ function applyAllowedRateHeaders(
+ res: Response,
+ result: RateLimitCheck,
+ maxPerMinute: number
+ ): void {
+ res.setHeader('X-RateLimit-Limit', String(maxPerMinute))
+ res.setHeader('X-RateLimit-Remaining', String(result.remaining))
+ res.setHeader('X-RateLimit-Reset', String(Math.floor(result.resetMs / 1000)))
+ }
+
+ function reportDecision(input: {
+ bucket: Bucket
+ operation: ExternalGfsOperation
+ phase: ExternalGfsRateLimitPhase
+ outcome: 'allowed' | 'denied'
+ latencyMs: number
+ authorityResolutionAvoided: boolean
+ }): void {
+ const labels = {
+ operation_class: input.operation.operationClass,
+ route: input.operation.route,
+ outcome: input.outcome,
+ phase: input.phase,
+ authority_resolution_avoided: input.authorityResolutionAvoided ? 'true' : 'false',
+ }
+ externalGfsRateLimitRequestsTotal.inc(labels)
+ externalGfsRateLimitDurationSeconds.observe(labels, input.latencyMs / 1_000)
+
+ // The hash gives operators a join key for a single limiter identity without
+ // exposing session tokens, source IPs, or stable internal IDs in logs.
+ const fields = {
+ event: 'external_gfs_rate_limit',
+ operationClass: input.operation.operationClass,
+ route: input.operation.route,
+ outcome: input.outcome,
+ phase: input.phase,
+ hashedKey: digest(input.bucket.key),
+ latencyMs: input.latencyMs,
+ authorityResolutionAvoided: input.authorityResolutionAvoided,
+ }
+ if (input.outcome === 'denied') {
+ rootLogger.warn(fields, 'external GFS rate limit denied')
+ } else {
+ rootLogger.debug(fields, 'external GFS rate limit checked')
+ }
+ }
+
+ async function enforceBuckets(input: {
+ req: Request
+ res: Response
+ operation: ExternalGfsOperation
+ phase: ExternalGfsRateLimitPhase
+ buckets: readonly Bucket[]
+ }): Promise<boolean> {
+ for (const bucket of input.buckets) {
+ const startedAt = performance.now()
+ const result = await checkAndIncrement(bucket.key, bucket.maxPerMinute)
+ const latencyMs = performance.now() - startedAt
+ const allowed = result.allowed
+ reportDecision({
+ bucket,
+ operation: input.operation,
+ phase: input.phase,
+ outcome: allowed ? 'allowed' : 'denied',
+ latencyMs,
+ authorityResolutionAvoided: input.phase === 'pre-resolution' && !allowed,
+ })
+ if (!allowed) {
+ const retryAfterSeconds = applyRateLimitHeaders(input.res, result, bucket.maxPerMinute)
+ input.res.status(429).json({ error: 'Too Many Requests', retryAfterSeconds })
+ return false
+ }
+ applyAllowedRateHeaders(input.res, result, bucket.maxPerMinute)
+ }
+ return true
+ }
+
+ /**
+ * First rate gate: runs immediately after the external Session-JWT check and
+ * before attachExternalGfsAuthority can touch the link resolver or any
+ * authority database path. Token mint intentionally remains user-only, so its
+ * stable per-user + per-IP limits are complete at this phase.
+ */
+ export function externalGfsPreResolutionRateLimit(
+ req: Request,
+ res: Response,
+ next: NextFunction
+ ): void {
+ void (async () => {
+ const operation = externalGfsOperationFor(req)
+ if (!operation) {
+ // Do not let an unclassified path fall through to the global authority
+ // resolver. Besides preserving the ordinary external API 404 shape, this
+ // makes the route matrix exhaustive at the authority boundary: a new
+ // handler must be classified before it can reach any DB-backed work.
+ res.status(404).json({ error: 'Not Found' })
+ return
+ }
+ const externalReq = req as ExternalGfsAuthedRequest
+ const desktopUserId = externalReq.externalAuth?.userId
+ const sessionDigest = authenticatedSessionDigest(req)
+ if (!desktopUserId || !sessionDigest) {
+ res.status(401).json({ error: 'Unauthorized' })
+ return
+ }
+
+ const buckets: Bucket[] =
+ operation.operationClass === 'token'
+ ? [
+ {
+ key: `gfs-ext:pre:token:user:${desktopUserId}`,
+ maxPerMinute: config.externalGfsTokenUserRlPerMin,
+ },
+ {
+ key: `gfs-ext:pre:token:ip:${sourceIpDigest(req)}`,
+ maxPerMinute: config.externalGfsTokenIpRlPerMin,
+ },
+ ]
+ : [
+ {
+ key: `gfs-ext:pre:${operation.operationClass}:session:${sessionDigest}`,
+ maxPerMinute: operationLimit(operation.operationClass),
+ },
+ {
+ key: `gfs-ext:pre:${operation.operationClass}:ip:${sourceIpDigest(req)}`,
+ maxPerMinute: operationLimit(operation.operationClass),
+ },
+ {
+ key: `gfs-ext:pre:ip:${sourceIpDigest(req)}`,
+ maxPerMinute: config.externalGfsIpRlPerMin,
+ },
+ ]
+
+ if (await enforceBuckets({ req, res, operation, phase: 'pre-resolution', buckets })) next()
+ })().catch(next)
+ }
+
+ /**
+ * Second rate gate: runs only after the server-derived authority is attached.
+ * It is keyed by the effective actor and operation class, so refreshing or
+ * reminting a public user token cannot evade the brokered-operation budget.
+ */
+ export function externalGfsResolvedOperationRateLimit(
+ req: Request,
+ res: Response,
+ next: NextFunction
+ ): void {
+ void (async () => {
+ const operation = externalGfsOperationFor(req)
+ if (!operation || operation.operationClass === 'token') {
+ next()
+ return
+ }
+ const authority = (req as ExternalGfsAuthedRequest).gfsAuthority
+ if (!authority) {
+ res.status(401).json({ error: 'unauthenticated' })
+ return
+ }
+ const bucket: Bucket = {
+ key: `gfs-ext:resolved:${operation.operationClass}:actor:${authority.kind}:${authority.tokenSubject}`,
+ maxPerMinute: operationLimit(operation.operationClass),
+ }
+ if (
+ await enforceBuckets({
+ req,
+ res,
+ operation,
+ phase: 'resolved-operation',
+ buckets: [bucket],
+ })
+ ) {
+ next()
+ }
+ })().catch(next)
+ }
diff --cc control-api/src/observability/metrics.ts
index 1ee73efc2,cb77feecf..65a65fbc4
--- a/control-api/src/observability/metrics.ts
+++ b/control-api/src/observability/metrics.ts
@@@ -254,24 -254,42 +254,60 @@@ export const rateLimitHitsTotal = getOr
labelNames: ['bucket_type', 'result'] as const as Array<'bucket_type' | 'result'>,
})
+export const gfsUploadAdmissionRequestsTotal = getOrCreateCounter({
+ name: 'gfs_upload_admission_requests_total',
+ help: 'Upload-v2 edge admission decisions by bounded limit family and result.',
+ labelNames: ['limit', 'result'] as const as Array<'limit' | 'result'>,
+})
+
+export const gfsUploadAdmissionBytesTotal = getOrCreateCounter({
+ name: 'gfs_upload_admission_bytes_total',
+ help: 'Declared upload-v2 part bytes admitted or rejected before GFSC forwarding.',
+ labelNames: ['result'] as const as Array<'result'>,
+})
+
+export const gfsUploadAdmissionActiveRequests = getOrCreateGauge({
+ name: 'gfs_upload_admission_active_requests',
+ help: 'Current upload-v2 requests holding replica-safe PostgreSQL admission slots.',
+ labelNames: [] as string[],
+})
+
+ // ─── External GFS rate-boundary metrics ────────────────────────────────────
+ //
+ // The rate-limit bucket key is deliberately *not* a Prometheus label: even a
+ // one-way digest is unbounded cardinality and would turn the metrics endpoint
+ // into a durable identity side channel. The middleware emits the digest in its
+ // structured event instead, while these metrics retain the bounded route and
+ // operation dimensions needed for alerting.
+ export const externalGfsRateLimitRequestsTotal = getOrCreateCounter({
+ name: 'external_gfs_rate_limit_requests_total',
+ help: 'External GFS rate-boundary decisions by operation class, route, phase, and outcome.',
+ labelNames: [
+ 'operation_class',
+ 'route',
+ 'outcome',
+ 'phase',
+ 'authority_resolution_avoided',
+ ] as const as Array<
+ 'operation_class' | 'route' | 'outcome' | 'phase' | 'authority_resolution_avoided'
+ >,
+ })
+
+ export const externalGfsRateLimitDurationSeconds = getOrCreateHistogram({
+ name: 'external_gfs_rate_limit_duration_seconds',
+ help: 'External GFS rate-boundary decision latency by bounded operation dimensions.',
+ labelNames: [
+ 'operation_class',
+ 'route',
+ 'outcome',
+ 'phase',
+ 'authority_resolution_avoided',
+ ] as const as Array<
+ 'operation_class' | 'route' | 'outcome' | 'phase' | 'authority_resolution_avoided'
+ >,
+ buckets: [0.001, 0.0025, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1],
+ })
+
// ─── Workflow-run archival cron metrics (DB-first, replaces CRD reaper) ──
export const workflowRunsArchiveRunsTotal = getOrCreateCounter({
name: 'workflow_runs_archive_runs_total',
diff --cc control-api/src/routes/external/gfs.ts
index c03065872,5907d9d68..096eb6500
--- a/control-api/src/routes/external/gfs.ts
+++ b/control-api/src/routes/external/gfs.ts
@@@ -64,40 -60,64 +85,96 @@@ const GFS_UPLOAD_RESPONSE_HEADERS =
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()
+ }
+
+ 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.
+ */
+ function externalGfsIngressRateKey(req: import('express').Request): string {
+ return `external-gfs:ingress:${externalGfsRateKey(ipKeyGenerator(externalGfsSourceIp(req)))}`
+ }
+
+ function externalGfsTokenRateKey(req: import('express').Request): string {
+ const userId = (req as ExternalGfsRequest).externalAuth?.userId ?? '__missing_user__'
+ return `external-gfs:token:user:${externalGfsRateKey(userId)}`
+ }
+
+ function externalGfsActorRateKey(operationClass: string) {
+ return (req: import('express').Request): string => {
+ const externalReq = req as ExternalGfsRequest
+ const authority = externalReq.gfsAuthority
+ const actor = authority
+ ? `${authority.kind}:${authority.tokenSubject}`
+ : `session:${externalReq.externalAuth?.userId ?? '__missing_user__'}`
+ return `external-gfs:${operationClass}:actor:${externalGfsRateKey(actor)}`
+ }
+ }
+
+ 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()
}
@@@ -274,138 -427,11 +484,143 @@@ export function createExternalGfsRouter
})
)
+ // 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
diff --cc control-api/src/routes/gfs/proxy.ts
index 36a335589,53db78953..867574779
--- a/control-api/src/routes/gfs/proxy.ts
+++ b/control-api/src/routes/gfs/proxy.ts
@@@ -69,10 -35,18 +69,19 @@@ export function registerGfsProxyRoute(r
res.status(401).json({ error: 'unauthorized' })
return
}
+ const authGeneration = req.adminAuth?.sessionVersion
+ if (
+ typeof authGeneration !== 'number' ||
+ !Number.isSafeInteger(authGeneration) ||
+ authGeneration < 1
+ ) {
+ res.status(401).json({ error: 'unauthorized' })
+ return
+ }
- const scope =
- req.method === 'GET' || req.method === 'HEAD'
+ const scope = UPLOAD_PATH.test(req.url || '')
+ ? GFS_WRITE_SCOPE
+ : req.method === 'GET' || req.method === 'HEAD'
? GFS_READ_SCOPE
: req.method === 'POST' || req.method === 'PUT'
? GFS_WRITE_SCOPE
@@@ -86,17 -60,17 +95,23 @@@
}
const subPath = req.url === '/' ? '' : req.url
- const target = `${gfscBaseUrlFor(req.method).replace(/\/+$/, '')}${subPath}`
+ const target = `${gfscBaseUrlFor(req.method, subPath).replace(/\/+$/, '')}${subPath}`
- const { token } = signGfsToken({ subject, drive: DEFAULT_DRIVE, scopes: [scope] })
+ const { token } = signGfsToken({
+ subject,
+ drive: DEFAULT_DRIVE,
+ scopes: [scope],
+ authGeneration,
+ principalType: 'control-admin',
+ })
const headers: Record<string, string> = {}
headers['author' + 'ization'] = ['Bearer', token].join(' ')
- if (req.method !== 'GET' && req.method !== 'HEAD') {
+ const isUploadPart = req.method === 'PUT' && UPLOAD_PART_PATH.test(subPath)
+ if (isUploadPart) {
+ for (const name of STREAM_REQUEST_HEADERS) {
+ const value = req.headers[name]
+ if (typeof value === 'string') headers[name] = value
+ }
+ } else if (req.method !== 'GET' && req.method !== 'HEAD') {
headers['content-type'] = 'application/json'
}
diff --cc control-api/test/db.controlAdminSessionVersionDefaultMigration.test.ts
index 000000000,76368b8ea..8c497f4f0
mode 000000,100644..100644
--- a/control-api/test/db.controlAdminSessionVersionDefaultMigration.test.ts
+++ b/control-api/test/db.controlAdminSessionVersionDefaultMigration.test.ts
@@@ -1,0 -1,34 +1,36 @@@
+ import { describe, expect, it, vi } from 'vitest'
+
+ vi.mock('pg', () => ({
+ Pool: vi.fn(function MockPool() {
+ return { connect: vi.fn(), query: vi.fn() }
+ }),
+ }))
+
+ describe('0096_control_admin_session_version_default migration', () => {
+ it('runs after the lifecycle projection and makes the authorization epoch one-based', async () => {
+ const { CONTROL_API_MIGRATIONS } = await import('../src/db.js')
+ const versions = CONTROL_API_MIGRATIONS.map(migration => migration.version)
+ const sessionVersionMigration = versions.indexOf('0031_control_admin_session_version')
+ const lifecycleProjectionMigration = versions.indexOf('0095_gfs_lifecycle_authority_projection')
+ const defaultMigration = versions.indexOf('0096_control_admin_session_version_default')
+ expect(sessionVersionMigration).toBeGreaterThanOrEqual(0)
+ expect(lifecycleProjectionMigration).toBeGreaterThan(sessionVersionMigration)
+ expect(defaultMigration).toBeGreaterThan(lifecycleProjectionMigration)
- expect(defaultMigration).toBe(versions.length - 1)
++ // Later feature migrations may follow this dev migration. Its contract is
++ // the ordering relative to the lifecycle projection, not being globally
++ // last in a branch that also carries another feature's migrations.
+
+ const migration = CONTROL_API_MIGRATIONS.find(
+ candidate => candidate.version === '0096_control_admin_session_version_default'
+ )
+ const query = vi.fn().mockResolvedValue({ rows: [], rowCount: 0 })
+ await migration!.apply({ query })
+ const sql = String(query.mock.calls[0]?.[0])
+
+ expect(sql).toContain('SET session_version = 1')
+ expect(sql).toContain('ALTER COLUMN session_version SET DEFAULT 1')
+ expect(sql).toContain('ALTER COLUMN session_version SET NOT NULL')
+ expect(sql).toContain('control_admin_session_version_positive')
+ expect(sql).toContain('CHECK (session_version >= 1)')
+ })
+ })
diff --cc control-api/test/db.gfsUploadSessionMigration.test.ts
index 5c15fd7d0,000000000..7701ddcfc
mode 100644,000000..100644
--- a/control-api/test/db.gfsUploadSessionMigration.test.ts
+++ b/control-api/test/db.gfsUploadSessionMigration.test.ts
@@@ -1,74 -1,0 +1,74 @@@
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+
+function runtimeAccessProfile(): Map<string, string> {
+ const source = readFileSync(
+ new URL('../../deploy/scripts/control-api-runtime-access-profiles.tsv', import.meta.url),
+ 'utf8'
+ )
+ return new Map(
+ source
+ .split('\n')
+ .filter(line => line && !line.startsWith('#'))
+ .map(line => line.split('\t') as [string, string])
+ )
+}
+
- describe('0091_gfs_upload_sessions', () => {
++describe('0097_gfs_upload_sessions', () => {
+ it('is additive and keeps the protocol ceiling separate from the product policy', () => {
+ const schema = readFileSync(
+ new URL('../src/services/gfsUploadSchema.ts', import.meta.url),
+ 'utf8'
+ )
+ const source = readFileSync(new URL('../src/db.ts', import.meta.url), 'utf8')
+
- expect(source).toContain("version: '0091_gfs_upload_sessions'")
++ expect(source).toContain("version: '0097_gfs_upload_sessions'")
+ expect(schema).toContain('CREATE TABLE IF NOT EXISTS gfs_upload_sessions')
+ expect(schema).toContain('CREATE TABLE IF NOT EXISTS gfs_upload_parts')
+ expect(schema).toContain('expected_bytes BETWEEN 0 AND 1073741824')
+ expect(schema).toContain('part_bytes BETWEEN 1048576 AND 16777216')
+ expect(schema).toContain('part_count BETWEEN 0 AND 1024')
+ expect(schema).toContain('UNIQUE (owner_subject, drive, idempotency_key)')
+ expect(schema).toContain('UNIQUE (upload_id, offset_bytes)')
+ expect(schema).toContain(
+ 'REVOKE ALL PRIVILEGES ON TABLE gfs_upload_sessions, gfs_upload_parts FROM PUBLIC'
+ )
+ expect(schema).toContain(
+ 'REVOKE ALL PRIVILEGES ON TABLE gfs_upload_sessions, gfs_upload_parts FROM gfs_controller_reader'
+ )
+ expect(schema).toContain(
+ 'GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE gfs_upload_sessions, gfs_upload_parts TO gfs_controller'
+ )
+ expect(schema).not.toMatch(/DROP\s+(TABLE|COLUMN)/i)
+ expect(schema).not.toContain('209715200')
+ })
+
+ it('classifies every upload relation as inaccessible to control_api_runtime', () => {
+ const schema = readFileSync(
+ new URL('../src/services/gfsUploadSchema.ts', import.meta.url),
+ 'utf8'
+ )
+ const uploadRelations = [
+ ...schema.matchAll(/CREATE TABLE IF NOT EXISTS (gfs_upload_[a-z0-9_]+)/g),
+ ]
+ .map(([, relation]) => relation)
+ .sort()
+ const profile = runtimeAccessProfile()
+
+ expect(uploadRelations).toEqual(['gfs_upload_parts', 'gfs_upload_sessions'])
+ expect(uploadRelations.map(relation => [relation, profile.get(relation)])).toEqual([
+ ['gfs_upload_parts', 'none'],
+ ['gfs_upload_sessions', 'none'],
+ ])
+ })
+
+ it('registers the additive finalizing recovery migration', () => {
+ const source = readFileSync(new URL('../src/db.ts', import.meta.url), 'utf8')
+ const schema = readFileSync(
+ new URL('../src/services/gfsUploadSchema.ts', import.meta.url),
+ 'utf8'
+ )
- expect(source).toContain("version: '0093_gfs_upload_finalizing_recovery'")
++ expect(source).toContain("version: '0099_gfs_upload_finalizing_recovery'")
+ expect(schema).toContain('finalizing_started_at TIMESTAMPTZ')
+ })
+})
diff --cc control-api/test/db.pluginWorkloadSdkTraceValidatorMigration.test.ts
index 85dbcc49b,4de6cce99..63d2429a2
--- a/control-api/test/db.pluginWorkloadSdkTraceValidatorMigration.test.ts
+++ b/control-api/test/db.pluginWorkloadSdkTraceValidatorMigration.test.ts
@@@ -23,13 -23,13 +23,20 @@@ describe('Plugin Workload SDK runtime-c
candidate => candidate.version === '0090_plugin_workload_sdk_runtime_contract_reconciliation'
)
expect(migration).toBeDefined()
+ const credentialTicketIndex = CONTROL_API_MIGRATIONS.findIndex(
+ candidate => candidate.version === '0089_plugin_workload_sdk_credential_ticket_runtime_access'
+ )
+ expect(credentialTicketIndex).toBeGreaterThanOrEqual(0)
+ expect(CONTROL_API_MIGRATIONS[credentialTicketIndex + 1]?.version).toBe(
+ '0090_plugin_workload_sdk_runtime_contract_reconciliation'
+ )
+ const migrationIndex = CONTROL_API_MIGRATIONS.findIndex(
+ candidate => candidate.version === migration?.version
+ )
+ const previousMigration = CONTROL_API_MIGRATIONS[migrationIndex - 1]
+ expect(previousMigration?.version).toBe(
+ '0089_plugin_workload_sdk_credential_ticket_runtime_access'
+ )
clientQuery.mockImplementation(async (sql: string) => {
if (sql.includes('SELECT version FROM schema_migrations')) {
diff --cc control-api/test/db.realPostgresMigration.integration.test.ts
index db0c3a715,bb1d46864..783c365c8
--- a/control-api/test/db.realPostgresMigration.integration.test.ts
+++ b/control-api/test/db.realPostgresMigration.integration.test.ts
@@@ -410,9 -470,129 +470,131 @@@ describeRealPostgres('control-api real
)
}
expectPrivileges([...(controlApiRelations.gfs_blob_manifests ?? new Set())], [])
+ expectPrivileges([...(controlApiRelations.gfs_upload_parts ?? new Set())], [])
+ expectPrivileges([...(controlApiRelations.gfs_upload_sessions ?? new Set())], [])
+ const linkUserId = randomUUID()
+ const linkAdminId = randomUUID()
+ const linkRuntimeClient = await dbPool.connect()
+ try {
+ await linkRuntimeClient.query('BEGIN')
+ await linkRuntimeClient.query(
+ `INSERT INTO users (id, email, name)
+ VALUES ($1, $2, 'GFS desktop operator privilege test')`,
+ [linkUserId, `gfs-link-${linkUserId}@example.test`]
+ )
+ await linkRuntimeClient.query(
+ `INSERT INTO control_admin_users (
+ id, username, password_hash, role, status
+ ) VALUES ($1, $2, 'gfs-link-test-hash', 'admin', 'active')`,
+ [linkAdminId, `gfs-link-${linkAdminId}`]
+ )
+
+ const privilegeState = await linkRuntimeClient.query<{
+ privilege_name: string
+ allowed: boolean
+ }>(
+ `SELECT privilege.privilege_name,
+ has_table_privilege(
+ 'control_api_runtime',
+ 'public.gfs_desktop_operator_links',
+ privilege.privilege_name
+ ) AS allowed
+ FROM (VALUES
+ ('SELECT'), ('INSERT'), ('UPDATE'), ('DELETE'),
+ ('TRUNCATE'), ('REFERENCES'), ('TRIGGER')
+ ) privilege(privilege_name)
+ ORDER BY privilege.privilege_name`
+ )
+ expect(privilegeState.rows).toEqual([
+ { privilege_name: 'DELETE', allowed: false },
+ { privilege_name: 'INSERT', allowed: true },
+ { privilege_name: 'REFERENCES', allowed: false },
+ { privilege_name: 'SELECT', allowed: true },
+ { privilege_name: 'TRIGGER', allowed: false },
+ { privilege_name: 'TRUNCATE', allowed: false },
+ { privilege_name: 'UPDATE', allowed: true },
+ ])
+
+ await linkRuntimeClient.query('SET LOCAL ROLE control_api_runtime')
+ await linkRuntimeClient.query(
+ `INSERT INTO gfs_desktop_operator_links
+ (id, lineage_id, generation, user_id, control_admin_id, state, source, created_by, row_version)
+ VALUES (gen_random_uuid(), gen_random_uuid(), 1, $1, $2, 'active', 'initial_setup', $2, 1)`,
+ [linkUserId, linkAdminId]
+ )
+ const linked = await linkRuntimeClient.query<{ user_id: string; control_admin_id: string }>(
+ `SELECT user_id::text, control_admin_id::text
+ FROM gfs_desktop_operator_links
+ WHERE user_id = $1`,
+ [linkUserId]
+ )
+ expect(linked.rows).toEqual([{ user_id: linkUserId, control_admin_id: linkAdminId }])
+
+ const lifecycle = await linkRuntimeClient.query<{
+ lifecycle_state: string
+ lifecycle_version: string
+ }>(
+ `SELECT lifecycle_state, lifecycle_version::text AS lifecycle_version
+ FROM users
+ WHERE id = $1`,
+ [linkUserId]
+ )
+ expect(lifecycle.rows).toEqual([{ lifecycle_state: 'active', lifecycle_version: '1' }])
+
+ await linkRuntimeClient.query(
+ `UPDATE gfs_desktop_operator_links
+ SET state = 'revoked', revoked_at = NOW(), revoked_by_type = 'control_admin',
+ revoked_by_id = $2, revoked_by_control_admin_id = $2,
+ revoked_by_desktop_user_id = NULL,
+ revocation_reason = 'privilege-test', row_version = row_version + 1
+ WHERE user_id = $1`,
+ [linkUserId, linkAdminId]
+ )
+
+ const operation = await linkRuntimeClient.query<{ id: string }>(
+ `INSERT INTO desktop_user_retirement_operations(
+ actor_type,
+ actor_control_admin_id,
+ target_user_id,
+ idempotency_key_hash,
+ request_fingerprint,
+ reason,
+ request_id
+ )
+ VALUES ('control_admin', $1, $2, repeat('a', 64), repeat('b', 64), 'privilege-test', 'request-1')
+ RETURNING id::text AS id`,
+ [linkAdminId, linkUserId]
+ )
+ await linkRuntimeClient.query(
+ `UPDATE desktop_user_retirement_operations
+ SET status = 'completed',
+ outcome = 'retired',
+ lifecycle_version = 2,
+ lifecycle_operation_id = id,
+ completed_at = NOW()
+ WHERE id = $1::uuid`,
+ [operation.rows[0]!.id]
+ )
+
+ await linkRuntimeClient.query('SAVEPOINT deny_link_truncate')
+ await expect(
+ linkRuntimeClient.query('TRUNCATE TABLE gfs_desktop_operator_links')
+ ).rejects.toThrow(/permission denied/)
+ await linkRuntimeClient.query('ROLLBACK TO SAVEPOINT deny_link_truncate')
+
+ await linkRuntimeClient.query('SAVEPOINT deny_link_delete')
+ await expect(
+ linkRuntimeClient.query(`DELETE FROM gfs_desktop_operator_links WHERE user_id = $1`, [
+ linkUserId,
+ ])
+ ).rejects.toThrow(/permission denied/)
+ await linkRuntimeClient.query('ROLLBACK TO SAVEPOINT deny_link_delete')
+ } finally {
+ await linkRuntimeClient.query('ROLLBACK')
+ linkRuntimeClient.release()
+ }
+
const maintenanceRelations = await relationPrivileges(dbPool, 'trace_maintenance_runtime')
const expectedMaintenanceRelations: Record<string, string[]> = {
administrative_events: ['SELECT'],
diff --cc control-api/test/middleware.externalGfsRateLimit.test.ts
index 000000000,19c41394a..58087ce1a
mode 000000,100644..100644
--- a/control-api/test/middleware.externalGfsRateLimit.test.ts
+++ b/control-api/test/middleware.externalGfsRateLimit.test.ts
@@@ -1,0 -1,429 +1,461 @@@
+ import { beforeEach, describe, expect, it, vi } from 'vitest'
+ import express from 'express'
+ import { createHash } from 'node:crypto'
+ import request from 'supertest'
+ import {
+ externalGfsOperationFor,
+ externalGfsPreResolutionRateLimit,
+ externalGfsResolvedOperationRateLimit,
+ externalGfsSourceIp,
+ } from '../src/middleware/externalGfsRateLimit.js'
+
+ const checkAndIncrement = vi.hoisted(() => vi.fn())
+ const metrics = vi.hoisted(() => ({
+ externalGfsRateLimitRequestsTotal: { inc: vi.fn() },
+ externalGfsRateLimitDurationSeconds: { observe: vi.fn() },
+ }))
+ const logger = vi.hoisted(() => ({
+ rootLogger: { debug: vi.fn(), warn: vi.fn() },
+ }))
+
+ vi.mock('../src/config.js', () => ({
+ config: {
+ externalGfsIngressRlPerMin: 1800,
+ externalGfsTokenUserRlPerMin: 10,
+ externalGfsTokenIpRlPerMin: 600,
+ externalGfsIpRlPerMin: 1200,
+ externalGfsReadRlPerMin: 120,
+ externalGfsOperationRlPerMin: 30,
+ },
+ }))
+ vi.mock('../src/services/rateLimiterService.js', () => ({
+ checkAndIncrement: (...args: unknown[]) => checkAndIncrement(...args),
+ }))
+ vi.mock('../src/observability/metrics.js', () => metrics)
+ vi.mock('../src/observability/logger.js', () => logger)
+
+ const DESKTOP_USER_ID = '11111111-aaaa-4aaa-8aaa-111111111111'
+ const CONTROL_ADMIN_ID = '22222222-bbbb-4bbb-8bbb-222222222222'
+ const RESOURCE_ID = '33333333-cccc-4ccc-8ccc-333333333333'
+
+ function allowed(limit = 30, remaining = limit - 1) {
+ return {
+ allowed: true,
+ remaining,
+ resetMs: Date.now() + 60_000,
+ windowStartMs: Date.now(),
+ count: limit - remaining,
+ }
+ }
+
+ function denied(limit = 30) {
+ return {
+ allowed: false,
+ remaining: 0,
+ resetMs: Date.now() + 30_000,
+ windowStartMs: Date.now(),
+ count: limit + 1,
+ }
+ }
+
+ function buildApp() {
+ const resolver = vi.fn()
+ const handler = vi.fn()
+ const app = express()
+
+ app.use('/external/gfs', (req, _res, next) => {
+ ;(req as typeof req & { externalAuth?: { userId: string } }).externalAuth = {
+ userId: DESKTOP_USER_ID,
+ }
+ next()
+ })
+ app.use('/external/gfs', externalGfsPreResolutionRateLimit)
+ app.use('/external/gfs', (req, _res, next) => {
+ resolver()
+ ;(
+ req as typeof req & {
+ gfsAuthority?: {
+ kind: 'linked-admin'
+ tokenSubject: string
+ desktopUserId: string
+ controlAdminId: string
+ authoritySource: 'initial_setup'
+ }
+ }
+ ).gfsAuthority = {
+ kind: 'linked-admin',
+ tokenSubject: CONTROL_ADMIN_ID,
+ desktopUserId: DESKTOP_USER_ID,
+ controlAdminId: CONTROL_ADMIN_ID,
+ authoritySource: 'initial_setup',
+ }
+ next()
+ })
+ app.use('/external/gfs', externalGfsResolvedOperationRateLimit)
+ app.use('/external/gfs', (_req, res) => {
+ handler()
+ res.status(204).end()
+ })
+
+ return { app, resolver, handler }
+ }
+
+ describe('external GFS rate boundary', () => {
+ beforeEach(() => {
+ checkAndIncrement.mockReset()
+ checkAndIncrement.mockResolvedValue(allowed())
+ metrics.externalGfsRateLimitRequestsTotal.inc.mockReset()
+ metrics.externalGfsRateLimitDurationSeconds.observe.mockReset()
+ logger.rootLogger.debug.mockReset()
+ logger.rootLogger.warn.mockReset()
+ })
+
+ it.each([
+ ['POST', '/token', 'token', '/external/gfs/token'],
++ ['GET', '/capabilities', 'resource', '/external/gfs/capabilities'],
++ ['POST', '/uploads', 'resource-mutation', '/external/gfs/uploads'],
++ [
++ 'HEAD',
++ `/uploads/${RESOURCE_ID}`,
++ 'resource',
++ '/external/gfs/uploads/:id',
++ ],
++ [
++ 'GET',
++ `/uploads/${RESOURCE_ID}/status`,
++ 'resource',
++ '/external/gfs/uploads/:id/status',
++ ],
++ [
++ 'PUT',
++ `/uploads/${RESOURCE_ID}/parts/0`,
++ 'resource-mutation',
++ '/external/gfs/uploads/:id/parts/:part',
++ ],
++ [
++ 'POST',
++ `/uploads/${RESOURCE_ID}/complete`,
++ 'resource-mutation',
++ '/external/gfs/uploads/:id/:action',
++ ],
++ [
++ 'DELETE',
++ `/uploads/${RESOURCE_ID}`,
++ 'resource-mutation',
++ '/external/gfs/uploads/:id',
++ ],
+ ['GET', '/resolve', 'resource', '/external/gfs/resolve'],
+ ['GET', '/resources', 'resource', '/external/gfs/resources'],
+ [
+ 'GET',
+ `/resources/${RESOURCE_ID}/children`,
+ 'resource',
+ '/external/gfs/resources/:id/children',
+ ],
+ [
+ 'GET',
+ `/resources/${RESOURCE_ID}/affordances`,
+ 'resource',
+ '/external/gfs/resources/:id/affordances',
+ ],
+ ['GET', `/proxy/${RESOURCE_ID}`, 'proxy-read', '/external/gfs/proxy/:rid'],
+ ['PATCH', `/resources/${RESOURCE_ID}`, 'resource-mutation', '/external/gfs/resources/:id'],
+ [
+ 'POST',
+ `/resources/${RESOURCE_ID}/children`,
+ 'resource-mutation',
+ '/external/gfs/resources/:id/children',
+ ],
+ [
+ 'PUT',
+ `/resources/${RESOURCE_ID}/content`,
+ 'resource-mutation',
+ '/external/gfs/resources/:id/content',
+ ],
+ ['DELETE', `/resources/${RESOURCE_ID}`, 'resource-mutation', '/external/gfs/resources/:id'],
+ ['GET', '/grants', 'grants-read', '/external/gfs/grants'],
+ ['PUT', '/grants', 'grants-mutation', '/external/gfs/grants'],
+ ['DELETE', `/grants/${RESOURCE_ID}`, 'grants-mutation', '/external/gfs/grants/:id'],
+ ['GET', '/shares', 'shares-read', '/external/gfs/shares'],
+ ['POST', '/shares', 'shares-mutation', '/external/gfs/shares'],
+ ['DELETE', `/shares/${RESOURCE_ID}`, 'shares-mutation', '/external/gfs/shares/:id'],
+ ] as const)('classifies %s /external/gfs%s as %s', (method, path, operationClass, route) => {
+ expect(
+ externalGfsOperationFor({
+ method,
+ baseUrl: '/external/gfs',
+ path,
+ originalUrl: `/external/gfs${path}`,
+ })
+ ).toEqual({ operationClass, route })
+ })
+
+ it('keeps unclassified paths outside the authority resolver', async () => {
+ const { app, resolver, handler } = buildApp()
+
+ const response = await request(app)
+ .post('/external/gfs/unclassified')
+ .set('x-user-session-token', 'session-one')
+
+ expect(response.status).toBe(404)
+ expect(response.body).toEqual({ error: 'Not Found' })
+ expect(checkAndIncrement).not.toHaveBeenCalled()
+ expect(resolver).not.toHaveBeenCalled()
+ expect(handler).not.toHaveBeenCalled()
+ })
+
+ it('rejects before resolution and handler work when the pre-resolution session bucket is exhausted', async () => {
+ checkAndIncrement.mockResolvedValueOnce(denied(120))
+ const { app, resolver, handler } = buildApp()
+
+ const response = await request(app)
+ .get('/external/gfs/resources')
+ .set('x-user-session-token', 'session-one')
+
+ expect(response.status).toBe(429)
+ expect(response.headers['x-ratelimit-limit']).toBe('120')
+ expect(checkAndIncrement).toHaveBeenCalledWith(
+ expect.stringMatching(/^gfs-ext:pre:resource:session:[0-9a-f]{64}$/),
+ 120
+ )
+ expect(resolver).not.toHaveBeenCalled()
+ expect(handler).not.toHaveBeenCalled()
+ expect(metrics.externalGfsRateLimitRequestsTotal.inc).toHaveBeenCalledWith(
+ expect.objectContaining({
+ operation_class: 'resource',
+ route: '/external/gfs/resources',
+ outcome: 'denied',
+ phase: 'pre-resolution',
+ authority_resolution_avoided: 'true',
+ })
+ )
+ expect(metrics.externalGfsRateLimitDurationSeconds.observe).toHaveBeenCalledWith(
+ expect.objectContaining({ phase: 'pre-resolution', outcome: 'denied' }),
+ expect.any(Number)
+ )
+ expect(logger.rootLogger.warn).toHaveBeenCalledWith(
+ expect.objectContaining({
+ operationClass: 'resource',
+ route: '/external/gfs/resources',
+ outcome: 'denied',
+ phase: 'pre-resolution',
+ hashedKey: expect.stringMatching(/^[0-9a-f]{64}$/),
+ latencyMs: expect.any(Number),
+ authorityResolutionAvoided: true,
+ }),
+ 'external GFS rate limit denied'
+ )
+ })
+
+ it('enforces the fixed 10/min user ceiling before minting a GFS token', async () => {
+ checkAndIncrement.mockResolvedValueOnce(denied(10))
+ const { app, resolver, handler } = buildApp()
+
+ const response = await request(app)
+ .post('/external/gfs/token')
+ .set('x-user-session-token', 'session-one')
+
+ expect(response.status).toBe(429)
+ expect(response.headers['x-ratelimit-limit']).toBe('10')
+ expect(checkAndIncrement).toHaveBeenCalledWith(`gfs-ext:pre:token:user:${DESKTOP_USER_ID}`, 10)
+ expect(resolver).not.toHaveBeenCalled()
+ expect(handler).not.toHaveBeenCalled()
+ })
+
+ it('enforces the fixed 600/min token source-IP ceiling after an allowed token user bucket', async () => {
+ checkAndIncrement.mockResolvedValueOnce(allowed(600, 599)).mockResolvedValueOnce(denied(600))
+ const { app, resolver, handler } = buildApp()
+
+ const response = await request(app)
+ .post('/external/gfs/token')
+ .set('x-user-session-token', 'session-one')
+
+ expect(response.status).toBe(429)
+ expect(response.headers['x-ratelimit-limit']).toBe('600')
+ expect(checkAndIncrement).toHaveBeenNthCalledWith(
+ 1,
+ `gfs-ext:pre:token:user:${DESKTOP_USER_ID}`,
+ 10
+ )
+ expect(checkAndIncrement).toHaveBeenNthCalledWith(
+ 2,
+ expect.stringMatching(/^gfs-ext:pre:token:ip:[0-9a-f]{64}$/),
+ 600
+ )
+ expect(resolver).not.toHaveBeenCalled()
+ expect(handler).not.toHaveBeenCalled()
+ })
+
+ it('uses the authenticated external-rest client IP before the funnel-appended peer address', async () => {
+ checkAndIncrement.mockResolvedValueOnce(allowed(9)).mockResolvedValueOnce(denied())
+ const { app } = buildApp()
+ const clientIp = '203.0.113.42'
+ const clientIpDigest = createHash('sha256').update(clientIp).digest('hex')
+
+ const response = await request(app)
+ .post('/external/gfs/token')
+ .set('x-user-session-token', 'session-one')
+ .set('x-forwarded-for', `${clientIp}, 10.42.0.18`)
+
+ expect(response.status).toBe(429)
+ expect(checkAndIncrement).toHaveBeenNthCalledWith(
+ 2,
+ `gfs-ext:pre:token:ip:${clientIpDigest}`,
+ 600
+ )
+ })
+
+ it('uses only a valid first forwarded IP and rejects a spoofed first fragment', () => {
+ const requestWithSpoofedForwarding = {
+ header: (name: string) =>
+ name.toLowerCase() === 'x-forwarded-for' ? 'not-an-ip, 198.51.100.99' : undefined,
+ ip: '203.0.113.41',
+ socket: { remoteAddress: '10.42.0.18' },
+ } as unknown as import('express').Request
+
+ expect(externalGfsSourceIp(requestWithSpoofedForwarding)).toBe('203.0.113.41')
+ })
+
+ it('uses distinct session, source-IP, and effective-actor buckets for each operation class', async () => {
+ const { app } = buildApp()
+
+ await request(app).get('/external/gfs/resources').set('x-user-session-token', 'session-one')
+ await request(app)
+ .get(`/external/gfs/proxy/${RESOURCE_ID}`)
+ .set('x-user-session-token', 'session-two')
+
+ const keys = checkAndIncrement.mock.calls.map(call => String(call[0]))
+ const limits = checkAndIncrement.mock.calls.map(call => Number(call[1]))
+ expect(keys).toContainEqual(
+ expect.stringMatching(/^gfs-ext:pre:resource:session:[0-9a-f]{64}$/)
+ )
+ expect(keys).toContainEqual(expect.stringMatching(/^gfs-ext:pre:resource:ip:[0-9a-f]{64}$/))
+ expect(keys).toContainEqual(expect.stringMatching(/^gfs-ext:pre:ip:[0-9a-f]{64}$/))
+ expect(keys).toContain(`gfs-ext:resolved:resource:actor:linked-admin:${CONTROL_ADMIN_ID}`)
+ expect(keys).toContainEqual(
+ expect.stringMatching(/^gfs-ext:pre:proxy-read:session:[0-9a-f]{64}$/)
+ )
+ expect(keys).toContainEqual(expect.stringMatching(/^gfs-ext:pre:proxy-read:ip:[0-9a-f]{64}$/))
+ expect(keys).toContain(`gfs-ext:resolved:proxy-read:actor:linked-admin:${CONTROL_ADMIN_ID}`)
+ expect(limits.filter(limit => limit === 120).length).toBe(6)
+ expect(limits.filter(limit => limit === 1200).length).toBe(2)
+ expect(limits.filter(limit => limit === 30).length).toBe(0)
+ })
+
+ it('keeps read and mutation budgets independent at every limiter phase', async () => {
+ const { app } = buildApp()
+
+ await request(app).get('/external/gfs/resources').set('x-user-session-token', 'session-read')
+ await request(app)
+ .patch(`/external/gfs/resources/${RESOURCE_ID}`)
+ .set('x-user-session-token', 'session-mutation')
+
+ const calls = checkAndIncrement.mock.calls.map(call => [String(call[0]), Number(call[1])])
+ expect(calls).toContainEqual([expect.stringMatching(/^gfs-ext:pre:resource:session:/), 120])
+ expect(calls).toContainEqual([
+ expect.stringMatching(/^gfs-ext:pre:resource-mutation:session:/),
+ 30,
+ ])
+ expect(calls).toContainEqual([expect.stringMatching(/^gfs-ext:resolved:resource:actor:/), 120])
+ expect(calls).toContainEqual([
+ expect.stringMatching(/^gfs-ext:resolved:resource-mutation:actor:/),
+ 30,
+ ])
+ expect(calls.filter(([, limit]) => limit === 1200)).toHaveLength(2)
+ })
+
+ it('assigns ACL listing to the read budget and ACL writes to the mutation budget', async () => {
+ const { app } = buildApp()
+
+ await request(app).get('/external/gfs/grants').set('x-user-session-token', 'session-acl-read')
+ await request(app).put('/external/gfs/grants').set('x-user-session-token', 'session-acl-write')
+ await request(app).get('/external/gfs/shares').set('x-user-session-token', 'session-acl-read')
+ await request(app).post('/external/gfs/shares').set('x-user-session-token', 'session-acl-write')
+
+ const calls = checkAndIncrement.mock.calls.map(call => [String(call[0]), Number(call[1])])
+ expect(calls).toContainEqual([expect.stringMatching(/^gfs-ext:pre:grants-read:session:/), 120])
+ expect(calls).toContainEqual([
+ expect.stringMatching(/^gfs-ext:resolved:grants-read:actor:/),
+ 120,
+ ])
+ expect(calls).toContainEqual([
+ expect.stringMatching(/^gfs-ext:pre:grants-mutation:session:/),
+ 30,
+ ])
+ expect(calls).toContainEqual([
+ expect.stringMatching(/^gfs-ext:resolved:grants-mutation:actor:/),
+ 30,
+ ])
+ expect(calls).toContainEqual([expect.stringMatching(/^gfs-ext:pre:shares-read:session:/), 120])
+ expect(calls).toContainEqual([
+ expect.stringMatching(/^gfs-ext:resolved:shares-read:actor:/),
+ 120,
+ ])
+ expect(calls).toContainEqual([
+ expect.stringMatching(/^gfs-ext:pre:shares-mutation:session:/),
+ 30,
+ ])
+ expect(calls).toContainEqual([
+ expect.stringMatching(/^gfs-ext:resolved:shares-mutation:actor:/),
+ 30,
+ ])
+ })
+
+ it('enforces the 1200/min aggregate IP ceiling after the 120/min read buckets', async () => {
+ checkAndIncrement.mockImplementation((key: string, limit: number) => {
+ if (key.startsWith('gfs-ext:pre:ip:')) return denied(1200)
+ return allowed(limit, limit - 1)
+ })
+ const { app, resolver, handler } = buildApp()
+
+ const response = await request(app)
+ .get('/external/gfs/resources')
+ .set('x-user-session-token', 'session-one')
+
+ expect(response.status).toBe(429)
+ expect(response.headers['x-ratelimit-limit']).toBe('1200')
+ expect(checkAndIncrement).toHaveBeenNthCalledWith(
+ 1,
+ expect.stringMatching(/^gfs-ext:pre:resource:session:[0-9a-f]{64}$/),
+ 120
+ )
+ expect(checkAndIncrement).toHaveBeenNthCalledWith(
+ 2,
+ expect.stringMatching(/^gfs-ext:pre:resource:ip:[0-9a-f]{64}$/),
+ 120
+ )
+ expect(checkAndIncrement).toHaveBeenNthCalledWith(
+ 3,
+ expect.stringMatching(/^gfs-ext:pre:ip:[0-9a-f]{64}$/),
+ 1200
+ )
+ expect(resolver).not.toHaveBeenCalled()
+ expect(handler).not.toHaveBeenCalled()
+ })
+
+ it('keeps the resolved actor bucket stable when a Desktop session is renewed', async () => {
+ checkAndIncrement.mockImplementation((key: string) =>
+ key.startsWith('gfs-ext:resolved:resource:actor:') ? denied() : allowed()
+ )
+ const { app, resolver, handler } = buildApp()
+
+ const first = await request(app)
+ .get('/external/gfs/resources')
+ .set('x-user-session-token', 'session-before-renewal')
+ const second = await request(app)
+ .get('/external/gfs/resources')
+ .set('x-user-session-token', 'session-after-renewal')
+
+ expect(first.status).toBe(429)
+ expect(second.status).toBe(429)
+ const resolvedKeys = checkAndIncrement.mock.calls
+ .map(call => String(call[0]))
+ .filter(key => key.startsWith('gfs-ext:resolved:resource:actor:'))
+ expect(resolvedKeys).toEqual([
+ `gfs-ext:resolved:resource:actor:linked-admin:${CONTROL_ADMIN_ID}`,
+ `gfs-ext:resolved:resource:actor:linked-admin:${CONTROL_ADMIN_ID}`,
+ ])
+ expect(resolver).toHaveBeenCalledTimes(2)
+ expect(handler).not.toHaveBeenCalled()
+ })
+ })
diff --cc control-api/test/routes.externalGfs.test.ts
index f29fc5f4b,b7fdd7950..5767eeaad
--- a/control-api/test/routes.externalGfs.test.ts
+++ b/control-api/test/routes.externalGfs.test.ts
@@@ -34,26 -36,31 +36,47 @@@ vi.mock('../src/config.js', () => (
gfscBaseUrl: 'http://gfsc.gfs.svc:8087',
gfscWriteBaseUrl: 'http://gfsc-writer.gfs.svc:8087',
gfscProxyTimeoutMs: 300_000,
+ gfsUploadMaxPartBytes: 16 * 1024 * 1024,
// The eligibility guard maps caller agent names to 1st:<hostsNamespace>/<name>.
hostsNamespace: 'mcp-host',
+ desktopGfsOperatorLinkingEnabled: false,
+ externalGfsIngressRlPerMin: 1800,
+ externalGfsTokenUserRlPerMin: 10,
+ externalGfsTokenIpRlPerMin: 600,
+ externalGfsIpRlPerMin: 1200,
+ externalGfsReadRlPerMin: 120,
+ externalGfsOperationRlPerMin: 30,
+ },
+ }))
+ vi.mock('../src/services/gfsDesktopOperatorLinkService.js', () => ({
+ gfsDesktopOperatorLinkService: {
+ resolveActiveLink: (...a: unknown[]) => mockResolveActiveLink(...a),
+ isDesktopUserActive: (...a: unknown[]) => mockIsDesktopUserActive(...a),
+ },
+ GfsDesktopOperatorLinkError: class GfsDesktopOperatorLinkError extends Error {
+ constructor(
+ readonly code: string,
+ message: string
+ ) {
+ super(message)
+ }
},
}))
+vi.mock('../src/middleware/gfsUploadAdmission.js', async importOriginal => {
+ const actual = await importOriginal<typeof import('../src/middleware/gfsUploadAdmission.js')>()
+ return {
+ ...actual,
+ gfsUploadAdmission: (
+ req: { headers: Record<string, unknown>; gfsUploadDeclaredBytes?: number },
+ _res: unknown,
+ next: () => void
+ ) => {
+ const value = Number(req.headers['content-length'])
+ if (Number.isSafeInteger(value) && value > 0) req.gfsUploadDeclaredBytes = value
+ next()
+ },
+ }
+})
vi.mock('../src/db.js', () => ({
pool: { query: (...a: unknown[]) => mockQuery(...a) },
withTransaction: (...a: unknown[]) => mockWithTransaction(...a),
@@@ -262,128 -432,285 +448,407 @@@ describe('POST /external/gfs/token (use
const res = await request(app).post('/external/gfs/token').send({})
expect(res.status).toBe(401)
})
+
+ it('stays user-only and never resolves linked authority even when linking is enabled', async () => {
+ auth()
+ ;(config as { desktopGfsOperatorLinkingEnabled: boolean }).desktopGfsOperatorLinkingEnabled =
+ true
+ mockResolveActiveLink.mockResolvedValue(ACTIVE_LINK)
+
+ const res = await request(await buildApp())
+ .post('/external/gfs/token')
+ .set('x-user-session-token', 'sess')
+ .send({ scopes: ['gfs.read'] })
+
+ expect(res.status).toBe(200)
+ expect(mockResolveActiveLink).not.toHaveBeenCalled()
+ expect(mockSignGfsToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ subject: U1,
+ principalType: 'user',
+ })
+ )
+ expect(mockSignGfsToken.mock.calls[0]?.[0]).not.toHaveProperty('brokeredAuthority')
+ })
+ })
+
+ describe('linked Desktop operator authority contract', () => {
+ function linked(): void {
+ auth()
+ ;(config as { desktopGfsOperatorLinkingEnabled: boolean }).desktopGfsOperatorLinkingEnabled =
+ true
+ mockResolveActiveLink.mockResolvedValue(ACTIVE_LINK)
+ }
+
+ it('mints only an internal effective-admin token and forwards the same request id to gfsc', async () => {
+ linked()
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn().mockResolvedValue(
+ new Response(JSON.stringify({ ok: true, data: { resourceId: R } }), {
+ status: 201,
+ headers: { 'content-type': 'application/json' },
+ })
+ )
+ )
+
+ const res = await request(await buildApp())
+ .post(`/external/gfs/resources/${R}/children?drive=main`)
+ .set('x-user-session-token', 'sess')
+ .set('x-request-id', REQUEST_ID)
+ .send({ name: 'operator-folder', kind: 'directory' })
+
+ expect(res.status).toBe(201)
+ expect(res.headers['x-request-id']).toBe(REQUEST_ID)
+ expect(mockSignGfsToken).toHaveBeenCalledWith({
+ subject: CONTROL_ADMIN_ID,
+ drive: 'main',
+ scopes: ['gfs.write'],
+ authGeneration: 1,
+ principalType: 'control-admin',
+ brokeredAuthority: {
+ desktopUserId: U1,
+ controlAdminId: CONTROL_ADMIN_ID,
+ authoritySource: 'linked-admin',
+ linkLineageId: ACTIVE_LINK.lineageId,
+ linkGeneration: ACTIVE_LINK.generation,
+ desktopUserGeneration: ACTIVE_LINK.desktopUserGeneration,
+ },
+ })
+ const fetchOptions = (vi.mocked(fetch).mock.calls[0]?.[1] ?? {}) as RequestInit
+ expect(new Headers(fetchOptions.headers).get('x-request-id')).toBe(REQUEST_ID)
+ })
+
+ it('uses the existing root tree primitive for a full operator root view', async () => {
+ linked()
+ mockQuery.mockImplementation(async (text: string) => {
+ const lifecycle = activeSessionLifecycleResult(text)
+ if (lifecycle) return lifecycle
+ if (text.includes('parent_resource_id IS NULL')) {
+ return {
+ rows: [{ resource_id: R, drive: 'main', name: '', kind: 'directory', path_cache: '/' }],
+ }
+ }
+ if (text.includes('parent_resource_id = $2::uuid')) {
+ return {
+ rows: [
+ {
+ resource_id: R2,
+ name: 'all-operator-visible',
+ kind: 'directory',
+ path_cache: '/all-operator-visible',
+ bytes: 0,
+ version: 1,
+ },
+ ],
+ }
+ }
+ return { rows: [] }
+ })
+
+ const res = await request(await buildApp())
+ .get('/external/gfs/resources?drive=main')
+ .set('x-user-session-token', 'sess')
+
+ expect(res.status).toBe(200)
+ expect(res.body).toEqual({
+ ok: true,
+ data: {
+ items: [expect.objectContaining({ resourceId: R2, name: 'all-operator-visible' })],
+ nextCursor: null,
+ rootResourceId: R,
+ view: 'operator',
+ },
+ })
+ expect(mockQuery.mock.calls.some(call => String(call[0]).includes('team_members'))).toBe(false)
+ })
+
+ it('persists Desktop actor, effective admin, authority source, and request id separately', async () => {
+ linked()
+ dbReturning([])
+
+ const res = await request(await buildApp())
+ .put('/external/gfs/grants')
+ .set('x-user-session-token', 'sess')
+ .set('x-request-id', REQUEST_ID)
+ .send({
+ resourceId: R,
+ subject: { type: 'user', id: U2 },
+ permissions: ['read'],
+ inherit: false,
+ })
+
+ expect(res.status).toBe(200)
+ const audit = mockQuery.mock.calls.find(call =>
+ String(call[0]).includes('INSERT INTO gfs_audit')
+ )
+ expect(audit?.[1]).toEqual([
+ `user:${U2}`,
+ CONTROL_ADMIN_ID,
+ 'grant.put[read]',
+ `gfs://main/${R}`,
+ 'allowed',
+ expect.anything(),
+ REQUEST_ID,
+ expect.stringMatching(/^[0-9a-f]{64}$/),
+ U1,
+ 'linked-admin',
+ ])
+ expect(mockAppendPermissionEvents).toHaveBeenCalledWith(
+ expect.anything(),
+ expect.objectContaining({ operatorKind: 'control_admin', operatorSub: CONTROL_ADMIN_ID })
+ )
+ })
+
+ it.each([
+ ['get', '/external/gfs/resources'],
+ ['get', '/external/gfs/resolve?uri=gfs%3A%2F%2Fmain%2Ffoo'],
+ ['get', `/external/gfs/resources/${R}/children`],
+ ['get', `/external/gfs/resources/${R}/affordances`],
+ ['get', `/external/gfs/proxy/${R}`],
+ ['get', `/external/gfs/grants?drive=main&resourceId=${R}`],
+ ['put', '/external/gfs/grants'],
+ ['delete', `/external/gfs/grants/${R}`],
+ ['get', `/external/gfs/shares?drive=main&resourceId=${R}`],
+ ['post', '/external/gfs/shares'],
+ ['delete', `/external/gfs/shares/${R}`],
+ ['patch', `/external/gfs/resources/${R}`],
+ ['post', `/external/gfs/resources/${R}/children`],
+ ['put', `/external/gfs/resources/${R}/content`],
+ ['delete', `/external/gfs/resources/${R}`],
+ ] as const)('fails closed before route-specific work for %s %s', async (method, path) => {
+ auth()
+ ;(config as { desktopGfsOperatorLinkingEnabled: boolean }).desktopGfsOperatorLinkingEnabled =
+ true
+ const { GfsDesktopOperatorLinkError } =
+ await import('../src/services/gfsDesktopOperatorLinkService.js')
+ mockResolveActiveLink.mockRejectedValue(
+ new GfsDesktopOperatorLinkError('control_admin_inactive', 'sensitive state')
+ )
+
+ const res = await request(await buildApp())
+ [method](path)
+ .set('x-user-session-token', 'sess')
+ .send({})
+
+ expect(res.status).toBe(403)
+ expect(res.body).toEqual({ error: 'gfs_operator_link_invalid' })
+ // The boundary rate limiter is deliberately the only DB-backed work that
+ // precedes the authority resolver. A resolver failure must not invoke a
+ // route handler or any of its database queries.
+ expect(
+ mockQuery.mock.calls.every(call => /rate_limit_buckets|lifecycle_state/.test(String(call[0])))
+ ).toBe(true)
+ expect(mockSignGfsToken).not.toHaveBeenCalled()
+ })
+
+ it('returns 404 for an unclassified GFS path without resolving authority', async () => {
+ auth()
+ ;(config as { desktopGfsOperatorLinkingEnabled: boolean }).desktopGfsOperatorLinkingEnabled =
+ true
+ mockResolveActiveLink.mockResolvedValue(ACTIVE_LINK)
+
+ const res = await request(await buildApp())
+ .post('/external/gfs/not-classified')
+ .set('x-user-session-token', 'sess')
+ .send({})
+
+ expect(res.status).toBe(404)
+ expect(res.body).toEqual({ error: 'Not Found' })
+ expect(mockResolveActiveLink).not.toHaveBeenCalled()
+ expect(mockQuery.mock.calls).toHaveLength(1)
+ expect(mockQuery.mock.calls[0]?.[0]).toContain('lifecycle_state')
+ })
+
+ it('returns a bounded retry body and header when the express edge backstop is exhausted', async () => {
+ const previous = config.externalGfsIngressRlPerMin
+ config.externalGfsIngressRlPerMin = 1
+ try {
+ auth()
+ const app = await buildApp()
+ await request(app)
+ .get('/external/gfs/not-classified')
+ .set('x-user-session-token', 'sess')
+ .expect(404)
+ const res = await request(app)
+ .get('/external/gfs/not-classified')
+ .set('x-user-session-token', 'sess')
+ expect(res.status).toBe(429)
+ expect(res.headers['retry-after']).toMatch(/^\d+$/)
+ expect(res.body).toEqual({
+ error: 'Too Many Requests',
+ retryAfterSeconds: expect.any(Number),
+ })
+ } finally {
+ config.externalGfsIngressRlPerMin = previous
+ }
+ })
+
+ it('rejects a pre-resolution rate limit before resolver or route work', async () => {
+ auth()
+ ;(config as { desktopGfsOperatorLinkingEnabled: boolean }).desktopGfsOperatorLinkingEnabled =
+ true
+ mockResolveActiveLink.mockResolvedValue(ACTIVE_LINK)
+ mockQuery.mockImplementation(async (text: string) => {
+ const lifecycle = activeSessionLifecycleResult(text)
+ if (lifecycle) return lifecycle
+ if (text.includes('rate_limit_buckets')) return { rows: [{ count: 121 }] }
+ throw new Error(`unexpected route query: ${text}`)
+ })
+
+ const res = await request(await buildApp())
+ .get('/external/gfs/resources')
+ .set('x-user-session-token', 'sess')
+
+ expect(res.status).toBe(429)
+ expect(res.body.error).toBe('Too Many Requests')
+ expect(res.headers['x-ratelimit-limit']).toBe('120')
+ expect(mockResolveActiveLink).not.toHaveBeenCalled()
+ expect(mockSignGfsToken).not.toHaveBeenCalled()
+ expect(mockQuery.mock.calls).toHaveLength(2)
+ expect(mockQuery.mock.calls[0]?.[0]).toContain('lifecycle_state')
+ expect(mockQuery.mock.calls[1]?.[1]?.[0]).toMatch(/^gfs-ext:pre:resource:session:[0-9a-f]{64}$/)
+ })
+
+ it('does not resolve or elevate when the feature flag is off', async () => {
+ auth()
+ mockResolveActiveLink.mockResolvedValue(ACTIVE_LINK)
+ mockQuery.mockImplementation(
+ async (text: string) => activeSessionLifecycleResult(text) ?? { rows: [] }
+ )
+
+ const res = await request(await buildApp())
+ .get('/external/gfs/resources')
+ .set('x-user-session-token', 'sess')
+
+ expect(res.status).toBe(200)
+ expect(res.body.data).toEqual({ items: [], nextCursor: null })
+ expect(mockResolveActiveLink).not.toHaveBeenCalled()
+ })
})
+describe('indexed upload relay canonical drive', () => {
+ it('allows a drive-independent capability probe while still rejecting mismatched creates', async () => {
+ auth()
+ const fetchMock = vi.fn(
+ async () =>
+ new Response(JSON.stringify({ upload: { resumableV2: { enabled: true } } }), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ })
+ )
+ vi.stubGlobal('fetch', fetchMock)
+ const app = await buildApp()
++ const nested = (app as any)._router?.stack?.find((layer: any) => layer.name === 'router')
+
+ const missing = await request(app)
+ .get('/external/gfs/capabilities')
+ .set('x-user-session-token', 'sess')
+ const mismatched = await request(app)
+ .post('/external/gfs/uploads?drive=archive')
+ .set('x-user-session-token', 'sess')
+ .send({ drive: 'main', operation: 'create' })
+
++
+ expect(missing.status).toBe(200)
+ expect(missing.body).toMatchObject({ upload: { resumableV2: { enabled: true } } })
+ expect(mismatched.status).toBe(400)
+ expect(mismatched.body).toEqual({ error: 'drive_mismatch' })
+ expect(mockSignGfsToken).toHaveBeenCalledWith({
+ subject: U1,
+ drive: 'main',
+ scopes: ['gfs.write'],
+ })
+ expect(fetchMock).toHaveBeenCalledTimes(1)
+ })
+
+ it('rejects malformed canonical drive values before admission or token minting', async () => {
+ auth()
+ const fetchMock = vi.fn()
+ vi.stubGlobal('fetch', fetchMock)
+ const malformed = ['', ' archive', 'archive ', '\tarchive', 'archive\n']
+
+ for (const drive of malformed) {
+ const app = await buildApp()
+ const response = await request(app)
+ .get(`/external/gfs/capabilities?drive=${encodeURIComponent(drive)}`)
+ .set('x-user-session-token', 'sess')
+ expect(response.status).toBe(400)
+ expect(response.body).toEqual({ error: 'drive_invalid' })
+ }
+
+ const arrayValue = await request(await buildApp())
+ .get('/external/gfs/capabilities?drive=archive&drive=main')
+ .set('x-user-session-token', 'sess')
+ expect(arrayValue.status).toBe(400)
+ expect(arrayValue.body).toEqual({ error: 'drive_invalid' })
+ })
+
+ it('signs and forwards every lifecycle request from one non-main canonical drive', async () => {
+ auth()
+ const uploadId = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'
+ const fetchMock = vi.fn(async (_url: string, init: RequestInit) => {
+ if (init.body && typeof init.body !== 'string') {
+ for await (const _chunk of init.body as unknown as AsyncIterable<Uint8Array>) {
+ /* drain the streaming part */
+ }
+ }
+ return new Response(JSON.stringify({ ok: true, data: { drive: 'archive' } }), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ })
+ })
+ vi.stubGlobal('fetch', fetchMock)
+ const app = await buildApp()
+ const withAuth = (builder: request.Test) => builder.set('x-user-session-token', 'sess')
+
+ await withAuth(request(app).get('/external/gfs/capabilities?drive=archive')).expect(200)
+ await withAuth(request(app).post('/external/gfs/uploads?drive=archive'))
+ .send({ drive: 'archive', operation: 'create' })
+ .expect(200)
+ await withAuth(request(app).head(`/external/gfs/uploads/${uploadId}?drive=archive`)).expect(200)
+ await withAuth(
+ request(app).get(`/external/gfs/uploads/${uploadId}/status?drive=archive&limit=256`)
+ ).expect(200)
+ await withAuth(
+ request(app)
+ .put(`/external/gfs/uploads/${uploadId}/parts/0?drive=archive`)
+ .set('content-type', 'application/offset+octet-stream')
+ .set('upload-part-number', '0')
+ .set('upload-offset', '0')
+ .set('upload-chunk-length', '4')
+ .set('upload-checksum', 'sha256 dGVzdA==')
+ )
+ .send(Buffer.from('test'))
+ .expect(200)
+ for (const action of ['pause', 'resume', 'complete']) {
+ await withAuth(request(app).post(`/external/gfs/uploads/${uploadId}/${action}?drive=archive`))
+ .send({})
+ .expect(200)
+ }
+ await withAuth(request(app).delete(`/external/gfs/uploads/${uploadId}?drive=archive`)).expect(
+ 200
+ )
+
+ expect(fetchMock).toHaveBeenCalledTimes(9)
+ expect(mockSignGfsToken).toHaveBeenCalledTimes(9)
+ for (const [input] of mockSignGfsToken.mock.calls) {
+ expect(input).toEqual({ subject: U1, drive: 'archive', scopes: ['gfs.write'] })
+ }
+ expect(fetchMock.mock.calls.map(call => String(call[0]))).toEqual([
+ 'http://gfsc-writer.gfs.svc:8087/v1/capabilities',
+ 'http://gfsc-writer.gfs.svc:8087/v1/uploads',
+ `http://gfsc-writer.gfs.svc:8087/v1/uploads/${uploadId}`,
+ `http://gfsc-writer.gfs.svc:8087/v1/uploads/${uploadId}/status?limit=256`,
+ `http://gfsc-writer.gfs.svc:8087/v1/uploads/${uploadId}/parts/0`,
+ `http://gfsc-writer.gfs.svc:8087/v1/uploads/${uploadId}/pause`,
+ `http://gfsc-writer.gfs.svc:8087/v1/uploads/${uploadId}/resume`,
+ `http://gfsc-writer.gfs.svc:8087/v1/uploads/${uploadId}/complete`,
+ `http://gfsc-writer.gfs.svc:8087/v1/uploads/${uploadId}`,
+ ])
+ })
+})
+
describe('PUT /external/gfs/grants (user delegation via existing engine)', () => {
it('honors a user-session grant when the caller holds manage_acl (no-escalation OK)', async () => {
auth()
diff --cc desktop-app/src/gfs/uriHandler.ts
index 61c97f941,1a294c535..6a87efaa7
--- a/desktop-app/src/gfs/uriHandler.ts
+++ b/desktop-app/src/gfs/uriHandler.ts
@@@ -519,20 -531,49 +537,56 @@@ export class GfsClient
throw surfaceGfsGrantError(error)
}
}
-
+ /** List direct URI shares on one resource. This route is never inferred from grants. */
+ async listShares(
+ input: { resourceId: string; drive?: string },
+ token: string
+ ): Promise<GfsShareListItem[]> {
+ const q = new URLSearchParams()
+ q.set('drive', input.drive ?? DEFAULT_DRIVE)
+ q.set('resourceId', input.resourceId)
+ let payload: { items: GfsShareListItem[] }
+ try {
+ payload = await this.transport.requestJson<{ items: GfsShareListItem[] }>(
+ 'GET',
+ joinUrl(this.transport.baseUrl, '/api/v1/me/gfs/shares?' + q.toString()),
+ { token }
+ )
+ } catch (error) {
+ throw surfaceGfsGrantError(error)
+ }
+ if (!payload || typeof payload !== 'object' || !Array.isArray(payload.items)) {
+ throw new GfsUriError('unexpected gfs shares response: missing items array')
+ }
+ return payload.items
+ }
+
+ /** Revoke a direct URI share by the UUID learned from listShares. */
+ async revokeShare(shareId: string, token: string): Promise<void> {
+ if (!ACL_ID_RE.test(shareId)) {
+ throw new GfsUriError(`share id must be a UUID: ${JSON.stringify(shareId)}`)
+ }
+ await this.transport.requestJson(
+ 'DELETE',
+ joinUrl(this.transport.baseUrl, `/api/v1/me/gfs/shares/${encodeURIComponent(shareId)}`),
+ { token }
+ )
+ }
+
- async createResource(input: GfsCreateInput, session: string): Promise<GfsResourceView> {
- return createGfsResource(this.transport, input, session)
+ async createResource(
+ input: GfsCreateInput,
+ session: string,
+ signal?: AbortSignal
+ ): Promise<GfsResourceView> {
+ return createGfsResource(this.transport, input, session, signal)
}
- async replaceFile(input: GfsReplaceInput, session: string): Promise<GfsResourceView> {
- return replaceGfsFile(this.transport, input, session)
+ async replaceFile(
+ input: GfsReplaceInput,
+ session: string,
+ signal?: AbortSignal
+ ): Promise<GfsResourceView> {
+ return replaceGfsFile(this.transport, input, session, signal)
}
async renameResource(
diff --cc desktop-app/ui/src/hooks/domain/__tests__/useGfsBrowserController.test.tsx
index b6e2e816f,2464f1850..d922bac18
--- a/desktop-app/ui/src/hooks/domain/__tests__/useGfsBrowserController.test.tsx
+++ b/desktop-app/ui/src/hooks/domain/__tests__/useGfsBrowserController.test.tsx
@@@ -128,34 -160,14 +160,35 @@@ function Probe({ grantsListEnabled = fa
)
}
+function UploadProbe() {
+ const ctrl = useGfsBrowserController()
+ return (
+ <>
+ <div data-testid="upload-state">{ctrl.uploadSnapshot?.state ?? 'none'}</div>
+ <button
+ type="button"
+ onClick={() =>
+ void ctrl.startFileUpload({
+ parentResourceId: 'parent-rid',
+ name: 'legacy.bin',
+ filePath: '/tmp/legacy.bin',
+ })
+ }
+ >
+ start upload
+ </button>
+ </>
+ )
+}
+
- function Harness({ children }: { children: ReactNode }) {
+ function Harness({ children, queryClient }: { children: ReactNode; queryClient?: QueryClient }) {
const [me, setMe] = useState<AuthContextValue['me']>(userA)
+ const [envKey, setEnvKey] = useState('env-a')
const [client] = useState(
- () => new QueryClient({ defaultOptions: { queries: { retry: false } } })
+ () => queryClient ?? new QueryClient({ defaultOptions: { queries: { retry: false } } })
)
return (
- <AuthContext.Provider value={authValue(me)}>
+ <AuthContext.Provider value={authValue(me, envKey)}>
<QueryClientProvider client={client}>
{children}
<button type="button" onClick={() => setMe(userB)}>
@@@ -209,113 -429,263 +450,367 @@@ describe('useGfsBrowserController', ()
screen.getByRole('button', { name: 'switch team' }).click()
})
- await waitFor(() => expect(screen.getByTestId('current').textContent).toBe('none'))
+ await waitFor(() => expect(screen.getByTestId('view').textContent).toBe('shared'))
+ expect(screen.getByTestId('operator-root').textContent).toBe('no')
+ expect(screen.getByTestId('current').textContent).toBe('none')
+ expect(screen.getByTestId('crumbs').textContent).toBe('')
+ expect(screen.getByTestId('accessible-count').textContent).toBe('1')
+ })
+
+ it('fails closed when operator mode omits a valid rootResourceId', async () => {
+ Object.defineProperty(window, 'clerum', {
+ configurable: true,
+ value: {
+ gfs: {
+ listAccessible: vi.fn(async () => ({
+ items: [],
+ nextCursor: null,
+ view: 'operator' as const,
+ })),
+ resolve: vi.fn(),
+ listChildren: vi.fn(async () => ({ items: [], nextCursor: null })),
+ affordances: vi.fn(),
+ },
+ },
+ })
+
+ render(<Probe />, { wrapper: Harness })
+
+ await waitFor(() =>
+ expect(screen.getByTestId('accessible-error').textContent).toContain('operator_root_missing')
+ )
+ expect(screen.getByTestId('current').textContent).toBe('none')
+ })
+
+ it('downgrades a revoked operator link to ordinary user scope through fresh discovery', async () => {
+ const rootResourceId = '11111111-1111-1111-1111-111111111111'
+ const ordinaryResource = {
+ resourceId: '33333333-3333-4333-8333-333333333333',
+ rid: '33333333333343338333333333333333',
+ gfsUri: 'gfs://main/33333333333343338333333333333333',
+ name: 'Shared report.md',
+ kind: 'file' as const,
+ path: '/Shared report.md',
+ version: 1,
+ bytes: 12,
+ permissions: ['read'],
+ }
+ let state: 'operator' | 'revoking' | 'ordinary' = 'operator'
+ const listAccessible = vi.fn(async () => {
+ if (state === 'revoking') {
+ state = 'ordinary'
+ throw new Error('403 operator_link_inactive')
+ }
+ if (state === 'ordinary') return { items: [ordinaryResource], nextCursor: null }
+ return { items: [], nextCursor: null, rootResourceId, view: 'operator' as const }
+ })
+ Object.defineProperty(window, 'clerum', {
+ configurable: true,
+ value: {
+ gfs: {
+ listAccessible,
+ resolve: vi.fn(),
+ listChildren: vi.fn(async () => ({ items: [], nextCursor: null })),
+ affordances: vi.fn(async () => ({
+ held: ['read', 'write'],
+ canDelegate: true,
+ grantableBits: ['read', 'write'],
+ canCreateShare: true,
+ })),
+ },
+ },
+ })
+
+ render(<Probe />, { wrapper: Harness })
+ await waitFor(() => expect(screen.getByTestId('operator-root').textContent).toBe('yes'))
+
+ state = 'revoking'
+ await act(async () => {
+ screen.getByRole('button', { name: 'reset browser' }).click()
+ })
+ await waitFor(() => expect(screen.getByTestId('access-state').textContent).toBe('active'))
+ await waitFor(() => expect(screen.getByTestId('view').textContent).toBe('shared'))
+ expect(screen.getByTestId('current').textContent).toBe('none')
+ await waitFor(() => expect(screen.getByTestId('accessible-count').textContent).toBe('1'))
+ expect(screen.getByTestId('operator-root').textContent).toBe('no')
+ expect(listAccessible).toHaveBeenCalledTimes(3)
+ })
+
+ it('fails closed after a second lifecycle denial instead of retrying forever', async () => {
+ const rootResourceId = '11111111-1111-1111-1111-111111111111'
+ let deny = false
+ const listAccessible = vi.fn(async () => {
+ if (deny) throw new Error('403 operator_link_inactive')
+ return { items: [], nextCursor: null, rootResourceId, view: 'operator' as const }
+ })
+ Object.defineProperty(window, 'clerum', {
+ configurable: true,
+ value: {
+ gfs: {
+ listAccessible,
+ resolve: vi.fn(),
+ listChildren: vi.fn(async () => ({ items: [], nextCursor: null })),
+ affordances: vi.fn(async () => ({
+ held: ['read'],
+ canDelegate: false,
+ grantableBits: [],
+ canCreateShare: false,
+ })),
+ },
+ },
+ })
+
+ render(<Probe />, { wrapper: Harness })
+ await waitFor(() => expect(screen.getByTestId('operator-root').textContent).toBe('yes'))
+
+ deny = true
+ await act(async () => {
+ screen.getByRole('button', { name: 'reset browser' }).click()
+ })
+
+ await waitFor(() => expect(screen.getByTestId('access-state').textContent).toBe('revoked'))
+ expect(listAccessible).toHaveBeenCalledTimes(3)
+ })
+
+ it('keeps the browser session active when ACL listing is denied by resource policy', async () => {
+ const rootResourceId = '11111111-1111-1111-1111-111111111111'
+ const listGrants = vi.fn(async () => {
+ throw new Error('403 Forbidden: manage_acl_required')
+ })
+ Object.defineProperty(window, 'clerum', {
+ configurable: true,
+ value: {
+ gfs: {
+ listAccessible: vi.fn(async () => ({
+ items: [],
+ nextCursor: null,
+ rootResourceId,
+ view: 'operator' as const,
+ })),
+ resolve: vi.fn(),
+ listChildren: vi.fn(async () => ({ items: [], nextCursor: null })),
+ affordances: vi.fn(async () => ({
+ held: ['read'],
+ canDelegate: false,
+ grantableBits: [],
+ canCreateShare: false,
+ })),
+ listGrants,
+ listShares: vi.fn(async () => []),
+ },
+ },
+ })
+
+ const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+ const removeQueries = vi.spyOn(queryClient, 'removeQueries')
+ render(<Probe grantsListEnabled />, {
+ wrapper: ({ children }) => <Harness queryClient={queryClient}>{children}</Harness>,
+ })
+ await waitFor(() => expect(screen.getByTestId('operator-root').textContent).toBe('yes'))
+ await waitFor(() => expect(listGrants).toHaveBeenCalled())
+ await act(async () => {
+ await Promise.resolve()
+ await Promise.resolve()
+ })
+ expect(removeQueries).not.toHaveBeenCalled()
+ expect(screen.getByTestId('access-state').textContent).toBe('active')
+ expect(screen.getByTestId('current').textContent).toBe(rootResourceId)
+ })
+
+ it('keeps the browser session active when a resource children listing returns a generic 403', async () => {
+ const resource = {
+ resourceId: 'shared-folder',
+ rid: 'sharedfolder',
+ gfsUri: 'gfs://main/sharedfolder',
+ drive: 'main',
+ parentResourceId: null,
+ name: 'Shared folder',
+ kind: 'directory' as const,
+ path: '/Shared folder',
+ version: 1,
+ bytes: 0,
+ sources: ['grant'],
+ permissions: ['read'],
+ coversDescendants: true,
+ }
+ const listChildren = vi.fn(async () => {
+ throw new Error('403 Forbidden')
+ })
+ Object.defineProperty(window, 'clerum', {
+ configurable: true,
+ value: {
+ gfs: {
+ listAccessible: vi.fn(async () => ({ items: [resource], nextCursor: null })),
+ resolve: vi.fn(),
+ listChildren,
+ affordances: vi.fn(async () => ({
+ held: ['read'],
+ canDelegate: false,
+ grantableBits: [],
+ canCreateShare: false,
+ })),
+ },
+ },
+ })
+
+ render(<Probe />, { wrapper: Harness })
+ await waitFor(() =>
+ expect(screen.getByRole('button', { name: 'open Shared folder' })).toBeTruthy()
+ )
+
+ await act(async () => {
+ screen.getByRole('button', { name: 'open Shared folder' }).click()
+ })
+
+ await waitFor(() =>
+ expect(listChildren).toHaveBeenCalledWith('shared-folder', 'main', undefined)
+ )
+ expect(screen.getByTestId('access-state').textContent).toBe('active')
+ expect(screen.getByTestId('current').textContent).toBe('shared-folder')
+ })
+
+ it.each([
+ ['403 Forbidden: resource policy denied', '403 Forbidden: resource policy denied'],
+ ['401 Unauthorized', '401 Unauthorized'],
+ ] as const)('keeps the URI operation scoped for %s', async (_label, message) => {
+ const resolve = vi.fn(async () => {
+ throw new Error(message)
+ })
+ Object.defineProperty(window, 'clerum', {
+ configurable: true,
+ value: {
+ gfs: {
+ listAccessible: vi.fn(async () => ({ items: [], nextCursor: null })),
+ resolve,
+ listChildren: vi.fn(async () => ({ items: [], nextCursor: null })),
+ affordances: vi.fn(async () => ({
+ held: ['read'],
+ canDelegate: false,
+ grantableBits: [],
+ canCreateShare: false,
+ })),
+ },
+ },
+ })
+
+ render(<Probe />, { wrapper: Harness })
+ await act(async () => {
+ screen.getByRole('button', { name: 'open' }).click()
+ })
+ await waitFor(() => expect(resolve).toHaveBeenCalledWith('gfs://main/root'))
+
+ expect(screen.getByTestId('access-state').textContent).toBe(
+ message.startsWith('401') ? 'revoked' : 'active'
+ )
+ expect(screen.getByTestId('open-error').textContent).toBe(
+ message.startsWith('401') ? 'none' : message
+ )
})
+ it('finishes a completed legacy receipt without polling it as a v2 session', async () => {
+ const startFileUpload = vi.fn(async () => ({
+ uploadId: 'legacy-resource-id',
+ drive: 'main',
+ operation: 'create' as const,
+ expectedBytes: 12,
+ partBytes: 12,
+ partCount: 1,
+ state: 'completed',
+ contiguousBytes: 12,
+ committedBytes: 12,
+ committedPartCount: 1,
+ activePartCount: 0,
+ expiresAt: new Date().toISOString(),
+ resultResourceId: 'legacy-resource-id',
+ resultVersion: 1,
+ }))
+ const getUploadSnapshot = vi.fn()
+ Object.defineProperty(window, 'clerum', {
+ configurable: true,
+ value: {
+ gfs: {
+ listAccessible: vi.fn(async () => ({ items: [], nextCursor: null })),
+ startFileUpload,
+ getUploadSnapshot,
+ },
+ },
+ })
+
+ render(<UploadProbe />, { wrapper: Harness })
+ await act(async () => {
+ screen.getByRole('button', { name: 'start upload' }).click()
+ })
+
+ await waitFor(() => expect(screen.getByTestId('upload-state').textContent).toBe('completed'))
+ expect(startFileUpload).toHaveBeenCalledWith(
+ 'parent-rid',
+ 'legacy.bin',
+ '/tmp/legacy.bin',
+ 'main',
+ undefined
+ )
+ expect(getUploadSnapshot).not.toHaveBeenCalled()
+ })
+
+ it('rehydrates a scoped persisted upload after the renderer mounts', async () => {
+ const listUploadSessions = vi.fn(async () => [
+ {
+ uploadId: 'terminal-upload',
+ fileName: 'done.bin',
+ fileSize: 12,
+ name: 'done.bin',
+ drive: 'main',
+ status: 'failed' as const,
+ target: { operation: 'create' as const, parentRid: 'parent-rid' },
+ },
+ {
+ uploadId: 'persisted-upload',
+ fileName: 'resume.bin',
+ fileSize: 12,
+ name: 'resume.bin',
+ drive: 'main',
+ status: 'suspended_auth' as const,
+ target: { operation: 'create' as const, parentRid: 'parent-rid' },
+ },
+ ])
+ const getUploadSnapshot = vi.fn(async () => ({
+ state: 'suspended_auth' as const,
+ session: {
+ uploadId: 'persisted-upload',
+ state: 'paused',
+ expectedBytes: 12,
+ committedBytes: 8,
+ },
+ uploadedBytes: 8,
+ totalBytes: 12,
+ }))
+ Object.defineProperty(window, 'clerum', {
+ configurable: true,
+ value: {
+ gfs: {
+ listUploadSessions,
+ getUploadSnapshot,
+ listAccessible: vi.fn(async () => ({ items: [], nextCursor: null })),
+ listChildren: vi.fn(async () => ({ items: [], nextCursor: null })),
+ affordances: vi.fn(async () => ({
+ held: [],
+ canDelegate: false,
+ grantableBits: [],
+ canCreateShare: false,
+ })),
+ },
+ },
+ })
+
+ render(<UploadProbe />, { wrapper: Harness })
+
+ await waitFor(() =>
+ expect(screen.getByTestId('upload-state').textContent).toBe('suspended_auth')
+ )
+ expect(listUploadSessions).toHaveBeenCalledWith('main')
+ expect(getUploadSnapshot).toHaveBeenCalledWith('persisted-upload', 'main')
+ })
+
it('refreshes cached affordances after permissions change outside Desktop', async () => {
let held = ['read']
const affordances = vi.fn(async () => ({
diff --cc desktop-app/ui/src/hooks/domain/useGfsBrowserController.ts
index aa37ccd11,e9e37bd62..c2773b7aa
--- a/desktop-app/ui/src/hooks/domain/useGfsBrowserController.ts
+++ b/desktop-app/ui/src/hooks/domain/useGfsBrowserController.ts
@@@ -108,10 -210,12 +233,15 @@@ export function useGfsBrowserController
const [crumbs, setCrumbs] = useState<GfsCrumb[]>([])
const [openError, setOpenError] = useState<string | null>(null)
const [resolving, setResolving] = useState(false)
+ const [uploadSnapshot, setUploadSnapshot] = useState<GfsUploadSnapshot | null>(null)
+ const uploadIdRef = useRef<string | null>(null)
- const previousSessionScopeRef = useRef<string | null>(null)
+ const uploadRehydrateGenerationRef = useRef(0)
+ // This is deliberately session-local. A 403 never becomes a persisted client
+ // capability decision: a later server-backed request is the only way out.
+ const [accessState, setAccessState] = useState<GfsBrowserAccessState>('active')
+ const previousSessionScopeRef = useRef<string | null>(null)
+ const operatorViewRef = useRef(false)
+ const operatorRecoveryAttemptedRef = useRef(false)
const current = crumbs.length ? crumbs[crumbs.length - 1] : null
const currentIsDirectory = current?.kind === 'directory'
@@@ -592,18 -737,18 +925,24 @@@
refreshGrants,
revokeGrant: (grantId: string) => revokeGrantMutation.mutateAsync(grantId),
revoking: revokeGrantMutation.isPending,
+ shares,
+ sharesError: sharesQuery.error,
+ loadingShares: sharesQuery.isFetching,
+ refreshShares,
+ revokeShare: (shareId: string) => revokeShareMutation.mutateAsync(shareId),
+ revokingShare: revokeShareMutation.isPending,
createShare,
createFolder: (name: string) => createFolderMutation.mutateAsync(name),
- createFile: (parentResourceId: string, name: string, encodedData: string) =>
- createFileMutation.mutateAsync({ parentResourceId, name, encodedData }),
- replaceFile: (resourceId: string, encodedData: string, ifMatch?: number) =>
- replaceFileMutation.mutateAsync({ resourceId, encodedData, ifMatch }),
+ createFile: (parentResourceId: string, name: string, filePath: string) =>
+ createFileMutation.mutateAsync({ parentResourceId, name, filePath }),
+ replaceFile: (resourceId: string, filePath: string, ifMatch?: number) =>
+ replaceFileMutation.mutateAsync({ resourceId, filePath, ifMatch }),
+ uploadSnapshot,
+ startFileUpload,
+ startFileReplace,
+ pauseUpload,
+ resumeUpload,
+ cancelUpload,
renameResource: (resourceId: string, name: string, ifMatch?: number) =>
renameResourceMutation.mutateAsync({ resourceId, name, ifMatch }),
deleteResource: (resourceId: string, ifMatch?: number) =>
diff --cc desktop-app/ui/src/pages/FilesPage.tsx
index 5ecd54f24,b70d583c8..5c8dbc81b
--- a/desktop-app/ui/src/pages/FilesPage.tsx
+++ b/desktop-app/ui/src/pages/FilesPage.tsx
@@@ -114,7 -145,7 +125,8 @@@ export function FilesPage({ pushToast,
const [filePreview, setFilePreview] = useState<GfsPreviewResource | null>(null)
const [dragActive, setDragActive] = useState(false)
const [droppedUploadCount, setDroppedUploadCount] = useState(0)
+ const [uploadFileName, setUploadFileName] = useState<string | null>(null)
+ const [mutationFailure, setMutationFailure] = useState<GfsBrowserFailure | null>(null)
const uploadInputRef = useRef<HTMLInputElement | null>(null)
const replaceInputRef = useRef<HTMLInputElement | null>(null)
const ctrl = useGfsBrowserController({ grantsListEnabled: manageOpen })
@@@ -346,30 -447,12 +434,31 @@@
) => {
if (!file || !parentResourceId) return
try {
+ assertGfsFileUploadSize(file.size)
const name = await normalizeGfsResourceName(file.name)
- await ctrl.createFile(parentResourceId, name, await fileToEncodedData(file))
+ setMutationFailure(null)
- pushToast?.(`Uploaded ${name}`, 'success')
+ setUploadFileName(name)
+ const filePath = window.clerum.gfs.getPathForFile(file)
+ if (!filePath) throw new Error('Could not resolve the selected local file')
+ // Keep the renderer usable while an older main/preload pair is being
+ // replaced. The resumable IPC path is always preferred; this bounded
+ // compatibility branch uses the existing one-shot API and therefore
+ // retains that API's own size/feature ceiling.
+ if (typeof startFileUpload === 'function') {
+ const result = await startFileUpload({ parentResourceId, name, filePath })
+ if (result.state === 'completed') {
+ pushToast?.(`Uploaded ${name}`, 'success')
+ setUploadFileName(null)
+ } else if (result.state === 'paused')
+ pushToast?.(`Upload paused. Resume ${name} from this page.`, 'info')
+ } else {
+ await ctrl.createFile(parentResourceId, name, filePath)
+ pushToast?.(`Uploaded ${name}`, 'success')
+ setUploadFileName(null)
+ }
} catch (uploadError) {
+ setUploadFileName(null)
- pushToast?.(uploadError instanceof Error ? uploadError.message : String(uploadError), 'error')
+ surfaceContentMutationError(uploadError)
}
}
@@@ -425,32 -516,11 +514,30 @@@
const handleReplaceCurrentFile = async (file: File | null | undefined) => {
if (!file || !current) return
try {
- await ctrl.replaceFile(current.resourceId, await fileToEncodedData(file), current.version)
+ assertGfsFileUploadSize(file.size)
+ setMutationFailure(null)
- pushToast?.(`Replaced ${current.name}`, 'success')
+ setUploadFileName(current.name)
+ const filePath = window.clerum.gfs.getPathForFile(file)
+ if (!filePath) throw new Error('Could not resolve the selected local file')
+ if (typeof startFileReplace === 'function') {
+ const result = await startFileReplace({
+ resourceId: current.resourceId,
+ filePath,
+ ifMatch: current.version,
+ })
+ if (result.state === 'completed') {
+ pushToast?.(`Replaced ${current.name}`, 'success')
+ setUploadFileName(null)
+ } else if (result.state === 'paused')
+ pushToast?.(`Replace paused. Resume ${current.name} from this page.`, 'info')
+ } else {
+ await ctrl.replaceFile(current.resourceId, filePath, current.version)
+ pushToast?.(`Replaced ${current.name}`, 'success')
+ setUploadFileName(null)
+ }
} catch (replaceError) {
+ setUploadFileName(null)
- pushToast?.(
- replaceError instanceof Error ? replaceError.message : String(replaceError),
- 'error'
- )
+ surfaceContentMutationError(replaceError)
}
}
@@@ -596,84 -768,39 +785,116 @@@
) : null}
{accessibleNotice ? <StatusBanner tone="info" text={accessibleNotice} /> : null}
- {visibleError ? <StatusBanner tone="error" text={visibleError} /> : null}
+
+ {mutationFailure ? (
+ <div
+ data-testid={`gfs-mutation-error-${mutationFailure.kind}`}
+ role="alert"
+ aria-label={mutationFailure.title}
+ >
+ <StatusBanner
+ tone="error"
+ text={`${mutationFailure.title}. ${mutationFailure.message}`}
+ />
+ </div>
+ ) : null}
+
+ {visibleFailure ? (
+ <div
+ data-testid={`gfs-error-${visibleFailure.kind}`}
+ role="alert"
+ aria-label={visibleFailure.title}
+ >
+ <EmptyState title={visibleFailure.title} body={visibleFailure.message} />
+ {accessRevoked ? (
+ <Button
+ data-testid="gfs-retry-access-action"
+ onClick={() => ctrl.retryAccess()}
+ size="sm"
+ variant="outline"
+ >
+ Retry file access
+ </Button>
+ ) : null}
+ </div>
- ) : visibleLoading ? (
++ ) : null}
+
+ {uploadSnapshot &&
+ [
+ 'initiated',
+ 'uploading',
+ 'paused',
+ 'suspended_auth',
+ 'finalizing',
+ 'canceling',
+ 'failed',
+ ].includes(uploadSnapshot.state) ? (
+ <section
+ className="da-gfs-upload-status"
+ data-testid="gfs-upload-row"
+ data-upload-file-name={uploadFileName || undefined}
+ aria-label={
+ uploadFileName ? `GFS upload progress for ${uploadFileName}` : 'GFS upload progress'
+ }
+ aria-live="polite"
+ >
+ <div className="da-gfs-upload-status__head">
+ <strong>
+ {uploadSnapshot.state === 'paused'
+ ? 'Upload paused'
+ : uploadSnapshot.state === 'suspended_auth'
+ ? 'Upload suspended after sign-in changed'
+ : uploadSnapshot.state === 'failed'
+ ? 'Upload needs attention'
+ : uploadSnapshot.state === 'finalizing'
+ ? 'Finalizing upload'
+ : uploadSnapshot.state === 'canceling'
+ ? 'Canceling upload'
+ : 'Uploading file'}
+ </strong>
+ <span>
+ {formatSharedFileSize(uploadSnapshot.uploadedBytes)} /{' '}
+ {formatSharedFileSize(uploadSnapshot.totalBytes)}
+ </span>
+ </div>
+ <progress
+ aria-label={
+ uploadFileName
+ ? `GFS upload progress for ${uploadFileName}`
+ : 'GFS upload progress'
+ }
+ aria-valuemin={0}
+ aria-valuemax={Math.max(uploadSnapshot.totalBytes, 1)}
+ aria-valuenow={Math.min(
+ uploadSnapshot.uploadedBytes,
+ Math.max(uploadSnapshot.totalBytes, 1)
+ )}
+ max={Math.max(uploadSnapshot.totalBytes, 1)}
+ value={Math.min(
+ uploadSnapshot.uploadedBytes,
+ Math.max(uploadSnapshot.totalBytes, 1)
+ )}
+ />
+ <div className="da-gfs-upload-status__actions">
+ {uploadSnapshot.state === 'paused' || uploadSnapshot.state === 'suspended_auth' ? (
+ <Button size="sm" variant="outline" onClick={() => void resumeUpload()}>
+ Resume
+ </Button>
+ ) : uploadSnapshot.state === 'uploading' || uploadSnapshot.state === 'initiated' ? (
+ <Button size="sm" variant="outline" onClick={() => void pauseUpload()}>
+ Pause
+ </Button>
+ ) : null}
+ {uploadSnapshot.state !== 'canceling' && uploadSnapshot.state !== 'finalizing' ? (
+ <Button size="sm" variant="text" onClick={() => void cancelUpload()}>
+ Cancel upload
+ </Button>
+ ) : null}
+ </div>
+ </section>
+ ) : null}
+
+ {visibleLoading ? (
<div
className="da-gfs-loading"
role="status"
diff --cc external-rest-api/src/app.ts
index 2ceaeba2f,a21a58c0e..c606c899a
--- a/external-rest-api/src/app.ts
+++ b/external-rest-api/src/app.ts
@@@ -19,23 -20,14 +20,28 @@@ import { createUserApprovalDecisionsRou
import { createWorkflowApprovalMediumsRouter } from './routes/workflowApprovalMediums.js'
import { createExternalWorkflowsRouter } from './routes/workflows.js'
+// Upload v2 part bodies are streamed octets and must not pass through the
+// global JSON parser (which would buffer/reject the binary payload).
+// Match the route shape, not only a valid UUID. Control API owns the UUID
+// validation and must receive malformed IDs as upload requests; otherwise a
+// binary body can be consumed by the global JSON parser and produce a parser
+// error before the canonical 4xx path is reached.
+const GFS_UPLOAD_PART_PATH = /^\/api\/v1\/me\/gfs\/uploads\/[^/]+\/parts\/[0-9]+$/i
+
export function createApp() {
const app = express()
+ // The deployment admits traffic only from the cloudflared ingress namespace
+ // (see deploy/base/profiles/networkpolicies.yaml). That single trusted hop
+ // overwrites the client address before this process, so req.ip is the stable
+ // limiter identity. Direct service exposure would invalidate this contract
+ // and must be rejected by deployment policy rather than by accepting a
+ // caller-controlled X-Forwarded-For chain here.
app.set('trust proxy', 1)
+ // Capture the proxy-attested client once at the external boundary. The
+ // control-api receives it through the authenticated service channel so its
+ // non-GFS edge buckets do not collapse every Desktop client onto the funnel
+ // pod address.
+ app.use(withExternalRequestContext)
app.use(
cors({
origin: config.corsOrigin === '*' ? true : config.corsOrigin,
diff --cc external-rest-api/src/config.ts
index 22b20a5ff,d7fd08f7b..c0004d9df
--- a/external-rest-api/src/config.ts
+++ b/external-rest-api/src/config.ts
@@@ -14,8 -14,9 +14,11 @@@ type Config =
desktopRpcProxyBaseUrl: string
desktopAppName: string
desktopReleaseBaseUrl: string
+ gfsUploadRequestPerMinute: number
+ gfsUploadMaxPartBytes: number
+ externalGfsEdgeAggregateRlPerMin: number
+ externalGfsEdgeAuthenticatedIpRlPerMin: number
+ externalGfsEdgeTokenIpRlPerMin: number
}
function required(name: string): string {
@@@ -44,12 -45,14 +47,18 @@@ function positiveIntegerFromEnv(name: s
return value
}
+function boundedIntegerFromEnv(name: string, defaultValue: number, maxValue: number): number {
+ const value = positiveIntegerFromEnv(name, defaultValue)
+ if (value > maxValue) throw new Error(`${name} must be an integer between 1 and ${maxValue}`)
+ return value
+}
+
+ function boundedPositiveIntegerFromEnv(name: string, defaultValue: number, max: number): number {
+ const value = positiveIntegerFromEnv(name, defaultValue)
- if (value > max) {
- throw new Error(`${name} must be <= ${max}`)
- }
++ if (value > max) throw new Error(`${name} must be <= ${max}`)
+ return value
+ }
+
/**
* Parse a CORS-origin env value. A bare `*` stays the literal `'*'` (handled
* specially in app.ts). Anything else is split on commas into a trimmed,
@@@ -134,17 -178,10 +184,21 @@@ export const config: Config =
process.env.EXTERNAL_REST_API_DESKTOP_RELEASE_BASE_URL ||
'https://github.com/evenfire-ai/evenfire/releases'
).replace(/\/+$/, ''),
+ // Coarse per-instance edge guard. The replica-safe principal/IP request and
+ // weighted-byte budgets live in control-api's PostgreSQL admission layer.
+ gfsUploadRequestPerMinute: positiveIntegerFromEnv(
+ 'EXTERNAL_REST_API_GFS_UPLOAD_REQUESTS_PER_MINUTE',
+ 120
+ ),
+ gfsUploadMaxPartBytes: boundedIntegerFromEnv(
+ 'EXTERNAL_REST_API_GFS_UPLOAD_MAX_PART_BYTES',
+ 16 * 1024 * 1024,
+ 16 * 1024 * 1024
+ ),
+ // Coherent GFS-only tiers: token IP <= client IP < process aggregate. The
+ // Control API's distributed 10/min token and 30/min session/actor budgets
+ // remain authoritative.
+ ...externalGfsEdgeRateLimits,
}
if (process.env.NODE_ENV === 'production' && config.corsOrigin === '*') {
diff --cc external-rest-api/src/controlApiClient.ts
index 3670b8794,04bee12c8..f224322ea
--- a/external-rest-api/src/controlApiClient.ts
+++ b/external-rest-api/src/controlApiClient.ts
@@@ -1,7 -1,26 +1,26 @@@
import { config } from './config.js'
+ import { currentExternalClientIp } from './requestContext.js'
-type RequestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+type RequestMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+ function addExternalClientIdentity(headers: Record<string, string>): void {
+ const clientIp = currentExternalClientIp()
+ if (clientIp) headers['x-external-client-ip'] = clientIp
+ }
+
+ // Response headers are an API contract only where a caller can safely act on
+ // them. In particular, never relay Set-Cookie, server identity, CORS, or
+ // arbitrary proxy headers from the internal control-api boundary.
+ const FORWARDABLE_RESPONSE_HEADERS = [
+ 'retry-after',
+ 'ratelimit',
+ 'ratelimit-policy',
+ 'x-ratelimit-limit',
+ 'x-ratelimit-remaining',
+ 'x-ratelimit-reset',
+ 'x-request-id',
+ ] as const
+
export class ControlApiError extends Error {
status: number
body: unknown
@@@ -186,7 -222,7 +222,8 @@@ export async function controlApiStreamR
userSessionToken?: string
extraHeaders?: Record<string, string>
signal?: AbortSignal
+ body?: unknown
+ throwOnHttpError?: boolean
}
): Promise<Response> {
const headers: Record<string, string> = {
@@@ -204,13 -241,8 +242,13 @@@
method,
headers,
signal: options?.signal,
- })
+ body: options?.body as BodyInit | null | undefined,
+ }
+ if (options?.body && typeof options.body === 'object' && Symbol.asyncIterator in options.body) {
+ fetchInit.duplex = 'half'
+ }
+ const response = await fetch(buildUrl(path, options?.query), fetchInit)
- if (!response.ok) {
+ if (!response.ok && options?.throwOnHttpError !== false) {
let parsed: unknown = null
const raw = await readResponseText(response)
try {
diff --cc external-rest-api/src/routes/gfs.ts
index 7c1bea9fc,90e0acb24..5afb57513
--- a/external-rest-api/src/routes/gfs.ts
+++ b/external-rest-api/src/routes/gfs.ts
@@@ -1,16 -1,15 +1,19 @@@
import { Router } from 'express'
--import type { NextFunction, Response } from 'express'
-import type { Request } from 'express'
-import { rateLimit } from 'express-rate-limit'
++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
@@@ -21,161 -20,167 +24,297 @@@
*/
// 5xx included so control-api's gfsc failure codes reach the desktop verbatim:
-// 504 gfsc_timeout, 502 gfsc_unreachable, plus 500/503 forwarded from gfsc. Without
-// them forwardControlApiError falls through to the global handler, which collapses
-// every 5xx to a generic 500 and the documented codes become unobservable at the
-// client (a wedged gfsc looks identical to an internal bug).
-const PROPAGATED = new Set([400, 401, 403, 404, 409, 410, 412, 422, 429, 500, 502, 503, 504])
-const STREAM_HEADERS = ['content-type', 'content-length', 'content-disposition']
+// 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 {
- if (error instanceof ControlApiError && PROPAGATED.has(error.status)) {
+ 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?.get(header)
++ const value = error.headers?.[header]
+ if (value) res.setHeader(header, value)
+ }
res.status(error.status).json(body)
return
}
next(error)
}
-export function createGfsRouter(options?: { edgeLimits?: ExternalGfsEdgeLimits }): Router {
+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 controlApiRequest('POST', '/external/gfs/token', {
+ const data = await gfsControlApiRequest(req, 'POST', '/external/gfs/token', {
userSessionToken: extractAuthToken(req),
body: req.body ?? {},
})
diff --cc external-rest-api/test/routes.gfs.test.ts
index e105bc32d,a90d4a7ec..9b812bf20
--- a/external-rest-api/test/routes.gfs.test.ts
+++ b/external-rest-api/test/routes.gfs.test.ts
@@@ -9,10 -9,10 +9,15 @@@ const { ControlApiError, clientMock }
message: string,
public status: number,
public body: unknown,
- public headers?: Headers
- public headers: Record<string, string> = {}
++ headers: Record<string, string> | Headers = {}
) {
super(message)
++ this.headers =
++ headers instanceof Headers
++ ? Object.fromEntries(headers.entries())
++ : headers
}
++ public headers: Record<string, string>
}
return {
ControlApiError,
@@@ -28,11 -28,13 +33,18 @@@ vi.mock('../src/controlApiClient.js', (
const authTokenMock = vi.hoisted(() => ({ verifyToken: vi.fn() }))
vi.mock('../src/authToken.js', () => authTokenMock)
- function buildApp(edgeRequestLimit = 120) {
+ const REQUEST_ID = '11111111-2222-4333-8444-555555555555'
+ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
-function buildApp(edgeLimits?: ExternalGfsEdgeLimits) {
++function buildApp(options: number | ExternalGfsEdgeLimits = 120) {
const app = express()
+ app.set('trust proxy', 1)
app.use(express.json())
- app.use(createGfsRouter({ edgeRequestLimit }))
- app.use(createGfsRouter(edgeLimits ? { edgeLimits } : undefined))
++ app.use(
++ createGfsRouter(
++ typeof options === 'number' ? { edgeRequestLimit: options } : { edgeLimits: options }
++ )
++ )
return app
}
diff --cc gfs-controller/src/api/serve.ts
index f5ada831d,49cb12317..4b9cd1537
--- a/gfs-controller/src/api/serve.ts
+++ b/gfs-controller/src/api/serve.ts
@@@ -1,36 -1,29 +1,37 @@@
import { randomUUID } from "node:crypto";
import type { IncomingMessage, ServerResponse } from "node:http";
- import type { GfsMetrics } from "../metrics";
- import type { AuthzContext } from "../authz/permissionClient";
- import type { AuditSink } from "../authz/audit";
+ import type { GfsVerifiedClaims } from "../auth/verify";
import type { AccessibleResourcePage } from "../authz/accessibleStore";
+ import type { AuditSink } from "../authz/audit";
+ import { type AuthzContext, auditAttribution } from "../authz/permissionClient";
import type { GfsPermission } from "../authz/resolve";
+ import { GfsSubjectResolutionDeniedError } from "../authz/subjectResolver";
import { checkTokenCeiling } from "../authz/tokenCeiling";
- import type { GfsVerifiedClaims } from "../auth/verify";
import type { GfsWriteService } from "../db/writeStore";
+ import type { GfsMetrics } from "../metrics";
-import { PathError, normalizeResourceId } from "../storage/paths";
+import type {
+ GfsUploadPartGeometry,
+ GfsUploadSessionService,
+ UploadPartStatus,
+ UploadPrincipal,
+ UploadSessionReceipt,
+} from "../upload/uploadSession";
+import { normalizeResourceId, PathError } from "../storage/paths";
+ import { type CopyRouteDeps, executeCopyRoute } from "./copyRoute";
+ import { ok, toResponse } from "./envelope";
+ import { GfsError } from "./errors";
import {
BlobReader,
+ ResourceStore,
downloadResource,
listChildren,
- ResourceStore,
statResource,
toView,
} from "./read";
- import { ok, toResponse } from "./envelope";
- import { executeCopyRoute, type CopyRouteDeps } from "./copyRoute";
import { executeRenameRoute } from "./renameRoute";
- import { GfsError } from "./errors";
-import { ResourceNameError, normalizeResourceName } from "./resourceName";
-import { WriteError, planWrite } from "./write";
+import { normalizeResourceName, ResourceNameError } from "./resourceName";
+import { planWrite, WriteError } from "./write";
+import { disabledGfsUploadV2Capability } from "../upload/protocol";
/**
* Strip control characters (CR/LF/tab, C0 controls, DEL) and bound the length of
@@@ -247,20 -237,28 +258,33 @@@ export class GfsServingHandler
const resolveMatch = RESOLVE_RE.exec(url.pathname);
const accessibleMatch = ACCESSIBLE_RE.exec(url.pathname);
const copyMatch = COPY_RE.exec(url.pathname);
- if (!resourceMatch && !resolveMatch && !accessibleMatch && !copyMatch) return false;
+ const capabilitiesMatch = CAPABILITIES_RE.exec(url.pathname);
+ const uploadCollectionMatch = UPLOAD_COLLECTION_RE.exec(url.pathname);
+ const uploadItemMatch = UPLOAD_ITEM_RE.exec(url.pathname);
+ if (!resourceMatch && !resolveMatch && !accessibleMatch && !copyMatch && !capabilitiesMatch && !uploadCollectionMatch && !uploadItemMatch) return false;
const method = req.method ?? "GET";
- const isWrite = method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE";
+ const isWrite =
+ method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE";
const copyWrite = method === "POST" && copyMatch && this.deps.writeService && this.deps.copy;
- const renameWrite = method === "PATCH" && resourceMatch?.[2] === undefined
- && this.deps.writeService && this.deps.audit && this.deps.rename;
- const resourceWrite = isWrite && this.deps.writeService && resourceMatch
- && (method === "DELETE" || Boolean(this.deps.audit));
+ const renameWrite =
+ method === "PATCH" &&
+ resourceMatch?.[2] === undefined &&
+ this.deps.writeService &&
+ this.deps.audit &&
+ this.deps.rename;
+ const resourceWrite =
+ isWrite &&
+ this.deps.writeService &&
+ resourceMatch &&
+ (method === "DELETE" || Boolean(this.deps.audit));
+ const uploadRoute = Boolean(uploadCollectionMatch || uploadItemMatch);
- if ((capabilitiesMatch && method !== "GET") || (copyMatch && !copyWrite) || (method === "PATCH" && !renameWrite) || (method !== "GET" && !resourceWrite && !copyWrite && !capabilitiesMatch && !uploadRoute)) {
+ if (
++ (capabilitiesMatch && method !== "GET") ||
+ (copyMatch && !copyWrite) ||
+ (method === "PATCH" && !renameWrite) ||
- (method !== "GET" && !resourceWrite && !copyWrite)
++ (method !== "GET" && !resourceWrite && !copyWrite && !capabilitiesMatch && !uploadRoute)
+ ) {
// This 404 can be written before a request body was consumed (e.g. a
// POST with a body to an unsupported verb/route) — same socket-poisoning
// risk as the catch path below, so it carries the same close semantics.