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.tsindex 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: Dbapply: 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.tsindex 000000000,bd7b8f1ab..94c726acdmode 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.tsindex 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 = getOrlabelNames: ['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.tsindex 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 maydiff --cc control-api/src/routes/gfs/proxy.tsindex 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(rres.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.tsindex 000000000,76368b8ea..8c497f4f0mode 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.tsindex 5c15fd7d0,000000000..7701ddcfcmode 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.tsindex 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-ccandidate => 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.tsindex 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.tsindex 000000000,19c41394a..58087ce1amode 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.tsindex 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 (useconst 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.tsindex 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 GfsClientthrow 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.tsxindex 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.tsindex 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 useGfsBrowserControllerconst [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] : nullconst 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.tsxindex 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) returntry {+ 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) returntry {- 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 ? (<divclassName="da-gfs-loading"role="status"diff --cc external-rest-api/src/app.tsindex 2ceaeba2f,a21a58c0e..c606c899a--- a/external-rest-api/src/app.ts+++ b/external-rest-api/src/app.ts@@@ -19,23 -20,14 +20,28 @@@ import { createUserApprovalDecisionsRouimport { 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.tsindex 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: stringdesktopAppName: stringdesktopReleaseBaseUrl: 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: sreturn 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.tsindex 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: numberbody: unknown@@@ -186,7 -222,7 +222,8 @@@ export async function controlApiStreamRuserSessionToken?: stringextraHeaders?: 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 = nullconst raw = await readResponseText(response)try {diff --cc external-rest-api/src/routes/gfs.tsindex 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.tsindex 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.tsindex 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 GfsServingHandlerconst 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.