Skip to content

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

TypeScript
98.1 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import express from 'express'
import { ipKeyGenerator } from 'express-rate-limit'
import { createHash } from 'node:crypto'
import { readFileSync } from 'node:fs'
import request from 'supertest'
// The MOCKED config object (defined below); mutating gfscProxyTimeoutMs drives a
// real deadline abort in the read-proxy timeout test.
import { config } from '../src/config.js'
// Real (unmocked) modules: the route imports these same instances, so a spy or
// a counter read here observes exactly what the edge backstops emit.
import { rootLogger } from '../src/observability/logger.js'
import { externalGfsRateLimitRequestsTotal } from '../src/observability/metrics.js'

/**
 * Unit tests for the end-user gfs surface on the /external (Session-JWT) plane.
 * Proves the user path reuses the EXISTING JWT scheme: the token mint calls the
 * existing `signGfsToken` with `sub = users.id`, and delegation flows through the
 * existing `handleGrantWrite` (user caller via resolveCaller, no-escalation via
 * assertMayGrant). No new auth is introduced.
 */

const mockVerifyExternalSessionToken = vi.fn()
const mockSignGfsToken = vi.hoisted(() => vi.fn())
const mockQuery = vi.hoisted(() => vi.fn())
const mockAppendPermissionEvents = vi.hoisted(() => vi.fn())
const mockWithTransaction = vi.hoisted(() => vi.fn())
const mockResolveActiveLink = vi.hoisted(() => vi.fn())
const mockIsDesktopUserActive = vi.hoisted(() => vi.fn())

vi.mock('../src/utils/auth/externalSessionAuthToken.js', () => ({
  verifyExternalSessionToken: (...a: unknown[]) => mockVerifyExternalSessionToken(...a),
}))
vi.mock('../src/auth/gfsToken.js', () => ({
  GFS_DELETE_SCOPE: 'gfs.delete',
  GFS_READ_SCOPE: 'gfs.read',
  GFS_WRITE_SCOPE: 'gfs.write',
  GFS_SCOPES: ['gfs.read', 'gfs.write', 'gfs.delete', 'gfs.manage_acl', 'gfs.share'],
  signGfsToken: (...a: unknown[]) => mockSignGfsToken(...a),
}))
vi.mock('../src/config.js', () => ({
  config: {
    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,
    externalGfsResourceReadRlPerMin: 120,
    externalGfsProxyReadRlPerMin: 60,
    externalGfsGrantsReadRlPerMin: 45,
    externalGfsSharesReadRlPerMin: 35,
    externalGfsOperationRlPerMin: 30,
    // Operator GFS route budgets; production defaults from src/config.ts.
    adminGfsGrantsPerMin: 150,
    adminGfsSharesPerMin: 150,
    adminGfsLegacyGrantReportPerMin: 150,
  },
}))
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) },
  rateLimitPool: { query: (...a: unknown[]) => mockQuery(...a) },
  withTransaction: (...a: unknown[]) => mockWithTransaction(...a),
}))
vi.mock('../src/services/tracing/controlApiPermissionEvents.js', () => ({
  appendControlApiPermissionEventsInTransaction: (...a: unknown[]) =>
    mockAppendPermissionEvents(...a),
}))
// grants.ts/shares.ts/token.ts import requireAuthForControlUI, which at module
// load derives the admin JWT key — irrelevant to the /external (Session-JWT)
// surface and unused by these routes. Stub it so the import chain is key-free.
vi.mock('../src/middleware/controlUIAuth.js', () => ({
  requireAuthForControlUI: (_req: unknown, _res: unknown, next: () => void) => next(),
}))

// user/team subject ids are real UUIDs (validated by parseSubject); the caller
// session + delegation target use valid UUIDs so the fixtures match production.
const U1 = '11111111-aaaa-4aaa-8aaa-111111111111'
const U2 = '22222222-bbbb-4bbb-8bbb-222222222222'
const T1 = '33333333-cccc-4ccc-8ccc-333333333333'
const T2 = '44444444-dddd-4ddd-8ddd-444444444444'
const H1 = '1st:mcp-host/agent-a'
const CORRELATION_ID = '55555555-eeee-4eee-8eee-555555555555'
const SESSION = {
  userId: U1,
  email: '[email protected]',
  teamId: T1,
  role: 'member' as const,
  authGeneration: 1,
  exp: Math.floor(Date.now() / 1000) + 3600,
}
const R = '11111111-1111-1111-1111-111111111111'
const R2 = '22222222-2222-2222-2222-222222222222'
const R_RID = R.replace(/-/g, '')
const CONTROL_ADMIN_ID = '66666666-eeee-4eee-8eee-666666666666'
const REQUEST_ID = '77777777-eeee-4eee-8eee-777777777777'
const ACTIVE_LINK = {
  desktopUserId: U1,
  controlAdminId: CONTROL_ADMIN_ID,
  source: 'initial_setup' as const,
  lineageId: '88888888-eeee-4eee-8eee-888888888888',
  generation: 1,
  desktopUserGeneration: 1,
  controlAdminGeneration: 1,
  createdAt: new Date('2026-08-10T00:00:00.000Z'),
}

async function buildApp() {
  const { createExternalGfsRouter } = await import('../src/routes/external/gfs.js')
  const { correlationIdMiddleware } = await import('../src/middleware/correlationId.js')
  const app = express()
  app.use(express.json())
  app.use(correlationIdMiddleware)
  app.use(createExternalGfsRouter())
  return app
}

async function buildOperatorShareApp() {
  const { registerGfsShareRoutes } = await import('../src/routes/gfs/shares.js')
  const app = express()
  app.use(express.json())
  app.use((req, _res, next) => {
    ;(req as typeof req & { adminAuth: { sub: string } }).adminAuth = {
      sub: 'operator-share-test',
    }
    next()
  })
  const router = express.Router()
  registerGfsShareRoutes(router)
  app.use(router)
  return app
}

// Admin (Control UI) grants plane — the SAME grant surface the external plane
// reuses, but mounted behind its OWN operator rate limiter (bucketType
// `gfs_grants`, key `gfsgrants:<sub>`). Used to prove the two planes never share
// a rate-limit bucket for the same subject id.
async function buildAdminGrantsApp(sub: string) {
  const { registerGfsGrantRoutes } = await import('../src/routes/gfs/grants.js')
  const app = express()
  app.use(express.json())
  app.use((req, _res, next) => {
    ;(req as typeof req & { adminAuth: { sub: string } }).adminAuth = { sub }
    next()
  })
  const router = express.Router()
  registerGfsGrantRoutes(router)
  app.use(router)
  return app
}

beforeEach(() => {
  mockVerifyExternalSessionToken.mockReset()
  mockSignGfsToken.mockReset()
  mockQuery.mockReset()
  mockAppendPermissionEvents.mockReset()
  mockWithTransaction.mockReset()
  mockResolveActiveLink.mockReset()
  mockIsDesktopUserActive.mockReset()
  mockResolveActiveLink.mockResolvedValue(null)
  mockIsDesktopUserActive.mockResolvedValue(true)
  mockQuery.mockImplementation(async (text: string) => {
    if (text.includes('SELECT lifecycle_state, lifecycle_version')) {
      return { rows: [{ lifecycle_state: 'active', lifecycle_version: 1 }] }
    }
    return limiterRow(text) ?? { rows: [] }
  })
  mockWithTransaction.mockImplementation(
    async (work: (db: { query: typeof mockQuery }) => Promise<unknown>) =>
      work({ query: mockQuery })
  )
  mockAppendPermissionEvents.mockResolvedValue(null)
  mockSignGfsToken.mockReturnValue({ token: 'gfs-user-token', expiresInSeconds: 300 })
  ;(config as { gfscProxyTimeoutMs: number }).gfscProxyTimeoutMs = 300_000
  ;(config as { desktopGfsOperatorLinkingEnabled: boolean }).desktopGfsOperatorLinkingEnabled =
    false
})
afterEach(() => vi.unstubAllGlobals())

const auth = () => mockVerifyExternalSessionToken.mockReturnValue(SESSION)

function activeSessionLifecycleResult(
  text: string
): { rows: [{ lifecycle_state: string; lifecycle_version: number }] } | null {
  return text.includes('SELECT lifecycle_state, lifecycle_version')
    ? { rows: [{ lifecycle_state: 'active', lifecycle_version: 1 }] }
    : null
}

/**
 * The limiter upsert as a reachable Postgres answers it: the first request of
 * the window. The external GFS limiter fails closed on a missing row, so every
 * mock that does not script the limiter must still answer it.
 */
function limiterRow(text: string): { rows: [{ count: number }] } | null {
  return text.includes('rate_limit_buckets') ? { rows: [{ count: 1 }] } : null
}

function combinedAuthorityRow(
  grants: Record<string, unknown>[],
  values?: unknown[]
): { rows: Array<{ ancestors: string[]; grants: Record<string, unknown>[]; shares: never[] }> } {
  const subjectTypes = (values?.[2] as string[]) ?? []
  const subjectIds = (values?.[3] as string[]) ?? []
  const wanted = new Set(subjectTypes.map((type, i) => `${type}:${subjectIds[i] ?? ''}`))
  return {
    rows: [
      {
        ancestors: [String(values?.[1])],
        grants: grants.filter(grant =>
          wanted.has(`${String(grant.subject_type)}:${String(grant.subject_id ?? '')}`)
        ),
        shares: [],
      },
    ],
  }
}

/** Route the grant engine's queries by SQL shape. */
function dbReturning(
  grants: Record<string, unknown>[],
  opts: {
    callerAgentNames?: string[]
    grantListRows?: Record<string, unknown>[]
    rateLimitCount?: number
    /** Per-bucket count, keyed by the bucket key; wins over rateLimitCount. */
    rateLimitCountFor?: (bucketKey: string) => number
  } = {}
) {
  // The external-plane eligibility guard resolves the caller's own agents via
  // getUserAgents (user_agents table). Default matches H1's name so existing
  // host-grant fixtures represent an in-directory agent.
  const callerAgentNames = opts.callerAgentNames ?? ['agent-a']
  mockQuery.mockImplementation(async (text: string, values?: unknown[]) => {
    const lifecycle = activeSessionLifecycleResult(text)
    if (lifecycle) return lifecycle
    if (text.includes('FROM user_agents')) {
      return { rows: callerAgentNames.map(name => ({ agent_name: name })) }
    }
    if (text.includes('rate_limit_buckets')) {
      const count = opts.rateLimitCountFor
        ? opts.rateLimitCountFor(String(values?.[0]))
        : (opts.rateLimitCount ?? 1)
      return { rows: [{ count }] }
    }
    if (text.includes('ORDER BY created_at ASC, id ASC')) {
      return { rows: opts.grantListRows ?? [] }
    }
    if (text.includes('authority_grants AS') && text.includes('authority_shares AS')) {
      return combinedAuthorityRow(grants, values)
    }
    if (text.includes('WITH RECURSIVE chain'))
      return { rows: [{ resource_id: String(values?.[1]) }] }
    if (text.includes('FROM gfs_grants')) {
      // Faithfully model the SQL subject filter on subject_type + subject_id.
      const subjectTypes = (values?.[1] as string[]) ?? []
      const subjectIds = (values?.[2] as string[]) ?? []
      const wanted = new Set(subjectTypes.map((type, i) => `${type}:${subjectIds[i] ?? ''}`))
      return {
        rows: grants.filter(g =>
          wanted.has(`${String(g.subject_type)}:${String(g.subject_id ?? '')}`)
        ),
      }
    }
    if (text.includes('FROM gfs_shares')) return { rows: [] }
    if (text.includes('INSERT INTO gfs_grants')) return { rows: [] }
    if (text.includes('INSERT INTO gfs_audit')) return { rows: [{ id: 'audit-1' }] }
    return { rows: [] }
  })
}

const sha256 = (value: string): string => createHash('sha256').update(value).digest('hex')

/**
 * Sum of the edge-backstop denial counter, narrowed to `labels` when given.
 * The registry is process-wide, so callers compare a before/after delta.
 */
async function edgeBackstopDenials(
  labels: Partial<Record<'operation_class' | 'route' | 'authority_resolution_avoided', string>> = {}
): Promise<number> {
  const { values } = await externalGfsRateLimitRequestsTotal.get()
  return values
    .filter(
      sample =>
        sample.labels.phase === 'edge-backstop' &&
        sample.labels.outcome === 'denied' &&
        (Object.keys(labels) as Array<keyof typeof labels>).every(
          name => sample.labels[name] === labels[name]
        )
    )
    .reduce((sum, sample) => sum + sample.value, 0)
}

describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)', () => {
  it('allows a mixed GFS journey beyond the former 30/min ingress cap', async () => {
    auth()
    const app = await buildApp()

    for (let attempt = 0; attempt < 31; attempt += 1) {
      const response = await request(app)
        .post('/external/gfs/not-classified')
        .set('x-user-session-token', 'sess')
      expect(response.status).toBe(404)
    }

    expect(mockVerifyExternalSessionToken).toHaveBeenCalledTimes(31)
    expect(mockResolveActiveLink).not.toHaveBeenCalled()
    expect(mockQuery.mock.calls).toHaveLength(31)
    expect(mockQuery.mock.calls.every(call => String(call[0]).includes('lifecycle_state'))).toBe(
      true
    )
  })

  it('enforces the configurable ingress backstop before session or authority work', async () => {
    const previousIngressLimit = (config as { externalGfsIngressRlPerMin: number })
      .externalGfsIngressRlPerMin
    ;(config as { externalGfsIngressRlPerMin: number }).externalGfsIngressRlPerMin = 3
    try {
      auth()
      const app = await buildApp()

      for (let attempt = 0; attempt < 3; attempt += 1) {
        const response = await request(app)
          .post('/external/gfs/not-classified')
          .set('x-user-session-token', 'sess')
        expect(response.status).toBe(404)
      }

      const exhausted = await request(app)
        .post('/external/gfs/not-classified')
        .set('x-user-session-token', 'sess')

      expect(exhausted.status).toBe(429)
      expect(mockVerifyExternalSessionToken).toHaveBeenCalledTimes(3)
      expect(mockResolveActiveLink).not.toHaveBeenCalled()
      expect(mockQuery.mock.calls).toHaveLength(3)
      expect(mockQuery.mock.calls.every(call => String(call[0]).includes('lifecycle_state'))).toBe(
        true
      )
    } finally {
      ;(config as { externalGfsIngressRlPerMin: number }).externalGfsIngressRlPerMin =
        previousIngressLimit
    }
  })

  it('enforces the recognised 10/min token route limit per authenticated user', async () => {
    auth()
    const app = await buildApp()

    for (let attempt = 0; attempt < 10; attempt += 1) {
      await request(app)
        .post('/external/gfs/token')
        .set('x-user-session-token', 'sess')
        .send({})
        .expect(200)
    }

    const exhausted = await request(app)
      .post('/external/gfs/token')
      .set('x-user-session-token', 'sess')
      .send({})

    expect(exhausted.status).toBe(429)
    expect(mockSignGfsToken).toHaveBeenCalledTimes(10)
  })

  it('uses the dedicated resource read route ceiling without widening mutation ceilings', async () => {
    const previousReadLimit = config.externalGfsResourceReadRlPerMin
    const previousOperationLimit = config.externalGfsOperationRlPerMin
    config.externalGfsResourceReadRlPerMin = 2
    config.externalGfsOperationRlPerMin = 2
    try {
      auth()
      dbReturning([])
      const app = await buildApp()

      for (let attempt = 0; attempt < 2; attempt += 1) {
        await request(app)
          .get('/external/gfs/resources')
          .set('x-user-session-token', 'read-session')
          .expect(200)
      }
      const exhaustedRead = await request(app)
        .get('/external/gfs/resources')
        .set('x-user-session-token', 'read-session')
      expect(exhaustedRead.status).toBe(429)
      expect(
        exhaustedRead.headers['ratelimit-limit'] ?? exhaustedRead.headers['x-ratelimit-limit']
      ).toBe('2')

      // A mutation has its own class budget; exhausting reads must not consume it.
      const mutation = await request(app)
        .patch(`/external/gfs/resources/${R}`)
        .set('x-user-session-token', 'mutation-0')
        .send({ name: 'rename' })
      expect(mutation.status).not.toBe(429)
    } finally {
      config.externalGfsResourceReadRlPerMin = previousReadLimit
      config.externalGfsOperationRlPerMin = previousOperationLimit
    }
  })

  // The three edge-backstop cases below mock every Postgres bucket as allowing
  // (dbReturning → count 1), so each 429 can only come from an express backstop.
  it('reports a resource edge-backstop denial on the rate metric and log', async () => {
    const previousReadLimit = config.externalGfsResourceReadRlPerMin
    config.externalGfsResourceReadRlPerMin = 2
    const warn = vi.spyOn(rootLogger, 'warn').mockImplementation(() => {})
    try {
      auth()
      dbReturning([])
      const app = await buildApp()
      const labels = {
        operation_class: 'resource',
        route: '/external/gfs/resources',
        authority_resolution_avoided: 'false',
      }
      const allBefore = await edgeBackstopDenials()
      const labelledBefore = await edgeBackstopDenials(labels)

      for (let attempt = 0; attempt < 2; attempt += 1) {
        await request(app)
          .get('/external/gfs/resources')
          .set('x-user-session-token', 'read-session')
          .expect(200)
      }
      // Liveness witness for the silence below: the guard ran and allowed twice.
      expect(warn).not.toHaveBeenCalled()
      expect(await edgeBackstopDenials()).toBe(allBefore)

      const exhausted = await request(app)
        .get('/external/gfs/resources')
        .set('x-user-session-token', 'read-session')

      expect(exhausted.status).toBe(429)
      expect(exhausted.body).toEqual({
        error: 'Too Many Requests',
        retryAfterSeconds: expect.any(Number),
      })
      const retryAfterSeconds = exhausted.body.retryAfterSeconds as number
      expect(retryAfterSeconds).toBeGreaterThanOrEqual(1)
      expect(warn).toHaveBeenCalledTimes(1)
      expect(warn.mock.calls[0]).toEqual([
        {
          event: 'external_gfs_rate_limit',
          phase: 'edge-backstop',
          guard: 'resource',
          operationClass: 'resource',
          route: '/external/gfs/resources',
          hashedKey: sha256(`gfs-ext:resolved:resource:actor:user-session:${U1}`),
          retryAfterSeconds,
          outcome: 'denied',
          authorityResolutionAvoided: false,
        },
        'external GFS edge backstop denied',
      ])
      expect(JSON.stringify(warn.mock.calls)).not.toContain(U1)
      expect((await edgeBackstopDenials(labels)) - labelledBefore).toBe(1)
      expect((await edgeBackstopDenials()) - allBefore).toBe(1)
    } finally {
      warn.mockRestore()
      config.externalGfsResourceReadRlPerMin = previousReadLimit
    }
  })

  it('reports an ingress edge-backstop denial on a path outside the operation matrix', async () => {
    const previousIngressLimit = config.externalGfsIngressRlPerMin
    config.externalGfsIngressRlPerMin = 1
    const warn = vi.spyOn(rootLogger, 'warn').mockImplementation(() => {})
    const sourceIp = '203.0.113.9'
    try {
      auth()
      const app = await buildApp()
      const labels = {
        operation_class: 'unclassified',
        route: 'unclassified',
        authority_resolution_avoided: 'true',
      }
      const allBefore = await edgeBackstopDenials()
      const labelledBefore = await edgeBackstopDenials(labels)

      await request(app)
        .get('/external/gfs/not-classified')
        .set('x-user-session-token', 'sess')
        .set('x-forwarded-for', sourceIp)
        .expect(404)
      // Liveness witness for the silence below: the guard ran and allowed once.
      expect(warn).not.toHaveBeenCalled()
      expect(await edgeBackstopDenials()).toBe(allBefore)

      const exhausted = await request(app)
        .get('/external/gfs/not-classified')
        .set('x-user-session-token', 'sess')
        .set('x-forwarded-for', sourceIp)

      expect(exhausted.status).toBe(429)
      const retryAfterSeconds = exhausted.body.retryAfterSeconds as number
      expect(retryAfterSeconds).toBeGreaterThanOrEqual(1)
      // The ingress guard runs before authentication, so no session was checked.
      expect(mockVerifyExternalSessionToken).toHaveBeenCalledTimes(1)
      expect(warn).toHaveBeenCalledTimes(1)
      expect(warn.mock.calls[0]).toEqual([
        {
          event: 'external_gfs_rate_limit',
          phase: 'edge-backstop',
          guard: 'ingress',
          operationClass: 'unclassified',
          route: 'unclassified',
          hashedKey: sha256(`external-gfs:ingress:${sha256(ipKeyGenerator(sourceIp))}`),
          retryAfterSeconds,
          outcome: 'denied',
          authorityResolutionAvoided: true,
        },
        'external GFS edge backstop denied',
      ])
      expect(JSON.stringify(warn.mock.calls)).not.toContain(sourceIp)
      expect((await edgeBackstopDenials(labels)) - labelledBefore).toBe(1)
      expect((await edgeBackstopDenials()) - allBefore).toBe(1)
    } finally {
      warn.mockRestore()
      config.externalGfsIngressRlPerMin = previousIngressLimit
    }
  })

  it('reports a grants-mutation edge-backstop denial on the rate metric and log', async () => {
    const previousOperationLimit = config.externalGfsOperationRlPerMin
    config.externalGfsOperationRlPerMin = 2
    const warn = vi.spyOn(rootLogger, 'warn').mockImplementation(() => {})
    try {
      auth()
      // The caller holds manage_acl + read on R, so each delegation succeeds.
      dbReturning([
        {
          subject_type: 'user',
          subject_id: U1,
          resource_id: R,
          permissions: ['manage_acl', 'read'],
          inherit: false,
        },
      ])
      const app = await buildApp()
      const grant = { resourceId: R, subject: { type: 'user', id: U2 }, permissions: ['read'] }
      const labels = {
        operation_class: 'grants-mutation',
        route: '/external/gfs/grants',
        authority_resolution_avoided: 'false',
      }
      const allBefore = await edgeBackstopDenials()
      const labelledBefore = await edgeBackstopDenials(labels)

      for (let attempt = 0; attempt < 2; attempt += 1) {
        await request(app)
          .put('/external/gfs/grants')
          .set('x-user-session-token', 'sess')
          .send(grant)
          .expect(200)
      }
      // Liveness witness for the silence below: the guard ran and allowed twice.
      expect(warn).not.toHaveBeenCalled()
      expect(await edgeBackstopDenials()).toBe(allBefore)

      const exhausted = await request(app)
        .put('/external/gfs/grants')
        .set('x-user-session-token', 'sess')
        .send(grant)

      expect(exhausted.status).toBe(429)
      const retryAfterSeconds = exhausted.body.retryAfterSeconds as number
      expect(retryAfterSeconds).toBeGreaterThanOrEqual(1)
      expect(warn).toHaveBeenCalledTimes(1)
      expect(warn.mock.calls[0]).toEqual([
        {
          event: 'external_gfs_rate_limit',
          phase: 'edge-backstop',
          guard: 'grants-mutation',
          operationClass: 'grants-mutation',
          route: '/external/gfs/grants',
          hashedKey: sha256(`gfs-ext:resolved:grants-mutation:actor:user-session:${U1}`),
          retryAfterSeconds,
          outcome: 'denied',
          authorityResolutionAvoided: false,
        },
        'external GFS edge backstop denied',
      ])
      expect(JSON.stringify(warn.mock.calls)).not.toContain(U1)
      expect((await edgeBackstopDenials(labels)) - labelledBefore).toBe(1)
      expect((await edgeBackstopDenials()) - allBefore).toBe(1)
    } finally {
      warn.mockRestore()
      config.externalGfsOperationRlPerMin = previousOperationLimit
    }
  })

  it('L5: a Postgres denial and a backstop denial for one actor log the same hashedKey', async () => {
    const previousReadLimit = config.externalGfsResourceReadRlPerMin
    config.externalGfsResourceReadRlPerMin = 2
    const warn = vi.spyOn(rootLogger, 'warn').mockImplementation(() => {})
    try {
      auth()
      let denyResolvedBucket = true
      dbReturning([], {
        rateLimitCountFor: key =>
          denyResolvedBucket && key.startsWith('gfs-ext:resolved:') ? 3 : 1,
      })
      const app = await buildApp()
      const read = () =>
        request(app).get('/external/gfs/resources').set('x-user-session-token', 'read-session')

      // The resolved Postgres bucket runs before the route backstop, so this
      // denial leaves the backstop's counter untouched.
      expect((await read()).status).toBe(429)
      denyResolvedBucket = false
      await read().expect(200)
      await read().expect(200)
      expect((await read()).status).toBe(429)

      const fields = warn.mock.calls.map(
        ([logged]) => logged as { phase: string; hashedKey: string }
      )
      const postgres = fields.filter(logged => logged.phase === 'resolved-operation')
      const backstop = fields.filter(logged => logged.phase === 'edge-backstop')
      expect(postgres).toHaveLength(1)
      expect(backstop).toHaveLength(1)
      expect(backstop[0].hashedKey).toBe(postgres[0].hashedKey)
      expect(postgres[0].hashedKey).toBe(
        sha256(`gfs-ext:resolved:resource:actor:user-session:${U1}`)
      )
    } finally {
      warn.mockRestore()
      config.externalGfsResourceReadRlPerMin = previousReadLimit
    }
  })

  it('L10: logs the first backstop denial per key and window, and counts every denial', async () => {
    const previousReadLimit = config.externalGfsResourceReadRlPerMin
    config.externalGfsResourceReadRlPerMin = 2
    const warn = vi.spyOn(rootLogger, 'warn').mockImplementation(() => {})
    try {
      auth()
      dbReturning([])
      const app = await buildApp()
      const labels = {
        operation_class: 'resource',
        route: '/external/gfs/resources',
        authority_resolution_avoided: 'false',
      }
      const before = await edgeBackstopDenials(labels)
      const read = () =>
        request(app).get('/external/gfs/resources').set('x-user-session-token', 'read-session')

      await read().expect(200)
      await read().expect(200)
      const statuses: number[] = []
      for (let attempt = 0; attempt < 50; attempt += 1) statuses.push((await read()).status)

      expect(statuses).toEqual(Array.from({ length: 50 }, () => 429))
      expect((await edgeBackstopDenials(labels)) - before).toBe(50)
      // Liveness witness: the one line that is logged is the backstop's.
      expect(warn).toHaveBeenCalledTimes(1)
      expect(warn.mock.calls[0]).toEqual([
        expect.objectContaining({ phase: 'edge-backstop', guard: 'resource' }),
        'external GFS edge backstop denied',
      ])
    } finally {
      warn.mockRestore()
      config.externalGfsResourceReadRlPerMin = previousReadLimit
    }
  })

  it('L22: reports the exact seconds left in the backstop window', async () => {
    const previousReadLimit = config.externalGfsResourceReadRlPerMin
    config.externalGfsResourceReadRlPerMin = 1
    const warn = vi.spyOn(rootLogger, 'warn').mockImplementation(() => {})
    const windowOpenedAt = Date.now()
    vi.useFakeTimers({ toFake: ['Date'], now: windowOpenedAt })
    try {
      auth()
      dbReturning([])
      const app = await buildApp()
      const read = () =>
        request(app).get('/external/gfs/resources').set('x-user-session-token', 'read-session')

      await read().expect(200)
      // 42.6 s remain in the 60 s window, so the client is told 43.
      vi.setSystemTime(windowOpenedAt + 17_400)
      const exhausted = await read()

      expect(exhausted.status).toBe(429)
      expect(exhausted.body).toEqual({ error: 'Too Many Requests', retryAfterSeconds: 43 })
      expect(warn).toHaveBeenCalledTimes(1)
      expect(warn.mock.calls[0]?.[0]).toEqual(expect.objectContaining({ retryAfterSeconds: 43 }))
    } finally {
      vi.useRealTimers()
      warn.mockRestore()
      config.externalGfsResourceReadRlPerMin = previousReadLimit
    }
  })

  type BudgetKey =
    | 'externalGfsIngressRlPerMin'
    | 'externalGfsTokenUserRlPerMin'
    | 'externalGfsResourceReadRlPerMin'
    | 'externalGfsProxyReadRlPerMin'
    | 'externalGfsGrantsReadRlPerMin'
    | 'externalGfsSharesReadRlPerMin'
    | 'externalGfsOperationRlPerMin'
  const SOURCE_IP = '203.0.113.9'
  const actorKey = (operationClass: string) =>
    sha256(`gfs-ext:resolved:${operationClass}:actor:user-session:${U1}`)
  const grantBody = { resourceId: R, subject: { type: 'user', id: U2 }, permissions: ['read'] }
  const shareBody = { resourceId: R, permissions: ['read'] }
  const edgeGuards: Array<{
    guard: string
    budget: BudgetKey
    method: 'get' | 'post' | 'put' | 'patch'
    path: string
    body?: Record<string, unknown>
    operationClass: string
    route: string
    authorityResolutionAvoided: boolean
    hashedKey: string
  }> = [
    {
      guard: 'ingress',
      budget: 'externalGfsIngressRlPerMin',
      method: 'get',
      path: '/external/gfs/not-classified',
      operationClass: 'unclassified',
      route: 'unclassified',
      authorityResolutionAvoided: true,
      hashedKey: sha256(`external-gfs:ingress:${sha256(ipKeyGenerator(SOURCE_IP))}`),
    },
    {
      guard: 'token',
      budget: 'externalGfsTokenUserRlPerMin',
      method: 'post',
      path: '/external/gfs/token',
      body: {},
      operationClass: 'token',
      route: '/external/gfs/token',
      authorityResolutionAvoided: true,
      hashedKey: sha256(`gfs-ext:pre:token:user:${U1}`),
    },
    {
      guard: 'resource',
      budget: 'externalGfsResourceReadRlPerMin',
      method: 'get',
      path: '/external/gfs/resources',
      operationClass: 'resource',
      route: '/external/gfs/resources',
      authorityResolutionAvoided: false,
      hashedKey: actorKey('resource'),
    },
    {
      guard: 'proxy-read',
      budget: 'externalGfsProxyReadRlPerMin',
      method: 'get',
      path: `/external/gfs/proxy/${R}`,
      operationClass: 'proxy-read',
      route: '/external/gfs/proxy/:rid',
      authorityResolutionAvoided: false,
      hashedKey: actorKey('proxy-read'),
    },
    {
      guard: 'resource-mutation',
      budget: 'externalGfsOperationRlPerMin',
      method: 'patch',
      path: `/external/gfs/resources/${R}`,
      body: { name: 'rename' },
      operationClass: 'resource-mutation',
      route: '/external/gfs/resources/:id',
      authorityResolutionAvoided: false,
      hashedKey: actorKey('resource-mutation'),
    },
    {
      guard: 'grants-read',
      budget: 'externalGfsGrantsReadRlPerMin',
      method: 'get',
      path: `/external/gfs/grants?resourceId=${R}`,
      operationClass: 'grants-read',
      route: '/external/gfs/grants',
      authorityResolutionAvoided: false,
      hashedKey: actorKey('grants-read'),
    },
    {
      guard: 'grants-mutation',
      budget: 'externalGfsOperationRlPerMin',
      method: 'put',
      path: '/external/gfs/grants',
      body: grantBody,
      operationClass: 'grants-mutation',
      route: '/external/gfs/grants',
      authorityResolutionAvoided: false,
      hashedKey: actorKey('grants-mutation'),
    },
    {
      guard: 'shares-read',
      budget: 'externalGfsSharesReadRlPerMin',
      method: 'get',
      path: `/external/gfs/shares?resourceId=${R}`,
      operationClass: 'shares-read',
      route: '/external/gfs/shares',
      authorityResolutionAvoided: false,
      hashedKey: actorKey('shares-read'),
    },
    {
      guard: 'shares-mutation',
      budget: 'externalGfsOperationRlPerMin',
      method: 'post',
      path: '/external/gfs/shares',
      body: shareBody,
      operationClass: 'shares-mutation',
      route: '/external/gfs/shares',
      authorityResolutionAvoided: false,
      hashedKey: actorKey('shares-mutation'),
    },
  ]

  it('L11: the table covers every edge guard the router mounts', async () => {
    const source = readFileSync(new URL('../src/routes/external/gfs.ts', import.meta.url), 'utf-8')
    const mounted = [...source.matchAll(/edgeRateLimitHandler\('([a-z-]+)'/g)].map(m => m[1])
    expect(mounted).toHaveLength(9)
    expect([...mounted].sort()).toEqual(edgeGuards.map(row => row.guard).sort())
  })

  it.each(edgeGuards)(
    'L11: the $guard backstop denies at its limit and reports once on the metric and log',
    async row => {
      const previousLimit = config[row.budget]
      config[row.budget] = 1
      const warn = vi.spyOn(rootLogger, 'warn').mockImplementation(() => {})
      // A handler that reaches gfsc gets an inert answer; the status of the
      // allowed request is irrelevant here, only that it is not a 429.
      vi.stubGlobal(
        'fetch',
        vi.fn(async () => new Response('{}', { status: 200 }))
      )
      try {
        auth()
        dbReturning([])
        const app = await buildApp()
        const labels = {
          operation_class: row.operationClass,
          route: row.route,
          authority_resolution_avoided: String(row.authorityResolutionAvoided),
        }
        const before = await edgeBackstopDenials(labels)
        const send = () => {
          const pending = request(app)
            [row.method](row.path)
            .set('x-user-session-token', 'sess')
            .set('x-forwarded-for', SOURCE_IP)
          return row.body === undefined ? pending : pending.send(row.body)
        }

        const allowed = await send()
        expect(allowed.status).not.toBe(429)
        // Liveness witness for the silence: the guard admitted one request.
        expect(await edgeBackstopDenials(labels)).toBe(before)

        const denied = await send()
        expect(denied.status).toBe(429)
        expect((await edgeBackstopDenials(labels)) - before).toBe(1)
        expect(warn).toHaveBeenCalledTimes(1)
        expect(warn.mock.calls[0]).toEqual([
          {
            event: 'external_gfs_rate_limit',
            phase: 'edge-backstop',
            guard: row.guard,
            operationClass: row.operationClass,
            route: row.route,
            hashedKey: row.hashedKey,
            retryAfterSeconds: denied.body.retryAfterSeconds,
            outcome: 'denied',
            authorityResolutionAvoided: row.authorityResolutionAvoided,
          },
          'external GFS edge backstop denied',
        ])
      } finally {
        warn.mockRestore()
        config[row.budget] = previousLimit
      }
    }
  )

  it.each([
    ['grants', `/external/gfs/grants?resourceId=${R}`],
    ['shares', `/external/gfs/shares?resourceId=${R}`],
  ])(
    'L12: GET /%s shares one grants/shares read bucket whose limit is the sum of both budgets',
    async (_name, path) => {
      // 45 + 35 in the mocked config: the per-class buckets still cap each
      // route at its own budget, so only the shared bucket carries the sum.
      const sharedLimit =
        config.externalGfsGrantsReadRlPerMin + config.externalGfsSharesReadRlPerMin
      expect(sharedLimit).toBe(80)
      auth()
      let sharedCount = sharedLimit
      const sharedKeys: string[] = []
      dbReturning([], {
        rateLimitCountFor: key => {
          if (!key.startsWith('gfsgrants-ext-read:')) return 1
          sharedKeys.push(key)
          return sharedCount
        },
      })
      const app = await buildApp()
      const send = () => request(app).get(path).set('x-user-session-token', 'sess')

      const atLimit = await send()
      expect(atLimit.status).not.toBe(429)
      expect(atLimit.headers['x-ratelimit-limit']).toBe('80')

      sharedCount = sharedLimit + 1
      const overLimit = await send()
      expect(overLimit.status).toBe(429)
      expect(overLimit.headers['x-ratelimit-limit']).toBe('80')
      // Witness: both requests reached the shared bucket under the one key.
      expect(sharedKeys).toEqual([`gfsgrants-ext-read:user:${U1}`, `gfsgrants-ext-read:user:${U1}`])
    }
  )

  it('mints a gfs token for the user with the EXISTING signGfsToken (sub=users.id)', async () => {
    auth()
    const app = await buildApp()
    const res = await request(app)
      .post('/external/gfs/token')
      .set('x-user-session-token', 'sess')
      .send({ scopes: ['gfs.read', 'gfs.write'] })
    expect(res.status).toBe(200)
    expect(res.body.token).toBe('gfs-user-token')
    expect(mockSignGfsToken).toHaveBeenCalledWith({
      subject: U1,
      drive: 'main',
      scopes: ['gfs.read', 'gfs.write'],
      pathBindings: [],
      authGeneration: 1,
      principalType: 'user',
    })
  })

  it('denies token minting for a retired Desktop user before signing a user-plane token', async () => {
    auth()
    mockIsDesktopUserActive.mockResolvedValue(false)
    const app = await buildApp()

    const res = await request(app)
      .post('/external/gfs/token')
      .set('x-user-session-token', 'sess')
      .send({})

    expect(res.status).toBe(403)
    expect(res.body).toEqual({ error: 'desktop_user_retired' })
    expect(mockSignGfsToken).not.toHaveBeenCalled()
  })

  it('defaults to gfs.read when no scopes requested', async () => {
    auth()
    const app = await buildApp()
    const res = await request(app)
      .post('/external/gfs/token')
      .set('x-user-session-token', 'sess')
      .send({})
    expect(res.status).toBe(200)
    expect(mockSignGfsToken.mock.calls[0][0].scopes).toEqual(['gfs.read'])
  })

  it('rejects invalid scopes with 400 (no token minted)', async () => {
    auth()
    const app = await buildApp()
    const res = await request(app)
      .post('/external/gfs/token')
      .set('x-user-session-token', 'sess')
      .send({ scopes: ['gfs.bogus'] })
    expect(res.status).toBe(400)
    expect(mockSignGfsToken).not.toHaveBeenCalled()
  })

  it('401 without a session token (Session-JWT plane gate)', async () => {
    mockVerifyExternalSessionToken.mockReturnValue(null)
    const app = await buildApp()
    const res = await request(app).post('/external/gfs/token').send({})
    expect(res.status).toBe(401)
  })

  it('stays user-only and never resolves linked authority even when linking is enabled', async () => {
    auth()
    ;(config as { desktopGfsOperatorLinkingEnabled: boolean }).desktopGfsOperatorLinkingEnabled =
      true
    mockResolveActiveLink.mockResolvedValue(ACTIVE_LINK)

    const res = await request(await buildApp())
      .post('/external/gfs/token')
      .set('x-user-session-token', 'sess')
      .send({ scopes: ['gfs.read'] })

    expect(res.status).toBe(200)
    expect(mockResolveActiveLink).not.toHaveBeenCalled()
    expect(mockSignGfsToken).toHaveBeenCalledWith(
      expect.objectContaining({
        subject: U1,
        principalType: 'user',
      })
    )
    expect(mockSignGfsToken.mock.calls[0]?.[0]).not.toHaveProperty('brokeredAuthority')
  })
})

describe('linked Desktop operator authority contract', () => {
  function linked(): void {
    auth()
    ;(config as { desktopGfsOperatorLinkingEnabled: boolean }).desktopGfsOperatorLinkingEnabled =
      true
    mockResolveActiveLink.mockResolvedValue(ACTIVE_LINK)
  }

  it('mints only an internal effective-admin token and forwards the same request id to gfsc', async () => {
    linked()
    vi.stubGlobal(
      'fetch',
      vi.fn().mockResolvedValue(
        new Response(JSON.stringify({ ok: true, data: { resourceId: R } }), {
          status: 201,
          headers: { 'content-type': 'application/json' },
        })
      )
    )

    const res = await request(await buildApp())
      .post(`/external/gfs/resources/${R}/children?drive=main`)
      .set('x-user-session-token', 'sess')
      .set('x-request-id', REQUEST_ID)
      .send({ name: 'operator-folder', kind: 'directory' })

    expect(res.status).toBe(201)
    expect(res.headers['x-request-id']).toBe(REQUEST_ID)
    expect(mockSignGfsToken).toHaveBeenCalledWith({
      subject: CONTROL_ADMIN_ID,
      drive: 'main',
      scopes: ['gfs.write'],
      authGeneration: 1,
      principalType: 'control-admin',
      brokeredAuthority: {
        desktopUserId: U1,
        controlAdminId: CONTROL_ADMIN_ID,
        authoritySource: 'linked-admin',
        linkLineageId: ACTIVE_LINK.lineageId,
        linkGeneration: ACTIVE_LINK.generation,
        desktopUserGeneration: ACTIVE_LINK.desktopUserGeneration,
      },
    })
    const fetchOptions = (vi.mocked(fetch).mock.calls[0]?.[1] ?? {}) as RequestInit
    expect(new Headers(fetchOptions.headers).get('x-request-id')).toBe(REQUEST_ID)
  })

  it('uses the existing root tree primitive for a full operator root view', async () => {
    linked()
    mockQuery.mockImplementation(async (text: string) => {
      const lifecycle = activeSessionLifecycleResult(text)
      const limiter = limiterRow(text)
      if (limiter) return limiter
      if (lifecycle) return lifecycle
      if (text.includes('parent_resource_id IS NULL')) {
        return {
          rows: [
            {
              resource_id: R,
              drive: 'main',
              name: '',
              kind: 'directory',
              path_cache: '/',
              updated_at: new Date('2026-01-01T00:00:00.000Z'),
            },
          ],
        }
      }
      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,
              updated_at: new Date('2026-01-01T00:00:00.000Z'),
            },
          ],
        }
      }
      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',
            updatedAt: '2026-01-01T00:00:00.000Z',
          }),
        ],
        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) ?? limiterRow(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 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'],
      authGeneration: 1,
      principalType: 'user',
    })
    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'],
        authGeneration: 1,
        principalType: 'user',
      })
    }
    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 and preserves false when inherit is omitted', async () => {
    auth()
    // The user holds manage_acl + read on R directly → may grant read.
    dbReturning([
      {
        subject_type: 'user',
        subject_id: U1,
        resource_id: R,
        permissions: ['manage_acl', 'read'],
        inherit: false,
      },
    ])
    const app = await buildApp()
    const res = await request(app)
      .put('/external/gfs/grants')
      .set('x-user-session-token', 'sess')
      .send({
        resourceId: R,
        subject: { type: 'user', id: U2 },
        permissions: ['read'],
      })
    expect(res.status).toBe(200)
    expect(res.body.ok).toBe(true)
    // The INSERT recorded the caller as the user (granted_by user:user-1).
    const insert = mockQuery.mock.calls.find(c => String(c[0]).includes('INSERT INTO gfs_grants'))
    expect(insert?.[1]?.[5]).toBe(false)
    expect(insert?.[1]?.[6]).toBe(`user:${U1}`)
    const audit = mockQuery.mock.calls.find(c => String(c[0]).includes('INSERT INTO gfs_audit'))
    expect(audit?.[1]?.[1]).toBeNull()
    expect(audit?.[1]?.[8]).toBe(U1)
    expect(audit?.[1]?.[9]).toBe('user-session')
    expect(mockAppendPermissionEvents).toHaveBeenCalledWith(
      expect.anything(),
      expect.objectContaining({
        operatorSub: U1,
        operatorKind: 'platform_user',
        changes: [
          expect.objectContaining({
            action: 'grant',
            resourceClass: 'gfs_folder_grant',
            outcome: 'committed',
          }),
        ],
      })
    )
  })

  it('honors grants held through any active team, not only the session teamId', async () => {
    auth()
    const teamGrants = [
      {
        subject_type: 'team',
        subject_id: T2,
        resource_id: R,
        permissions: ['manage_acl', 'read'],
        inherit: false,
      },
    ]
    mockQuery.mockImplementation(async (text: string, values?: unknown[]) => {
      const lifecycle = activeSessionLifecycleResult(text)
      const limiter = limiterRow(text)
      if (limiter) return limiter
      if (lifecycle) return lifecycle
      if (text.includes('FROM team_members')) return { rows: [{ team_id: T2 }] }
      if (text.includes('authority_grants AS') && text.includes('authority_shares AS')) {
        return combinedAuthorityRow(teamGrants, values)
      }
      if (text.includes('WITH RECURSIVE chain'))
        return { rows: [{ resource_id: String(values?.[1]) }] }
      if (text.includes('FROM gfs_grants')) {
        const subjectTypes = (values?.[1] as string[]) ?? []
        const subjectIds = (values?.[2] as string[]) ?? []
        const wanted = new Set(subjectTypes.map((type, i) => `${type}:${subjectIds[i] ?? ''}`))
        return {
          rows: teamGrants.filter(row => wanted.has(`${row.subject_type}:${row.subject_id}`)),
        }
      }
      if (text.includes('FROM gfs_shares')) return { rows: [] }
      if (text.includes('INSERT INTO gfs_grants')) return { rows: [] }
      if (text.includes('INSERT INTO gfs_audit')) return { rows: [{ id: 'audit-2' }] }
      return { rows: [] }
    })

    const app = await buildApp()
    const res = await request(app)
      .put('/external/gfs/grants')
      .set('x-user-session-token', 'sess')
      .send({
        resourceId: R,
        subject: { type: 'user', id: U2 },
        permissions: ['read'],
        inherit: false,
      })

    expect(res.status).toBe(200)
    const insert = mockQuery.mock.calls.find(c => String(c[0]).includes('INSERT INTO gfs_grants'))
    expect(insert?.[1]?.[6]).toBe(`user:${U1}`)
  })

  it('rejects a non-UUID user subject id → 400 subject_invalid', async () => {
    auth()
    dbReturning([
      {
        subject_type: 'user',
        subject_id: U1,
        resource_id: R,
        permissions: ['manage_acl', 'read'],
        inherit: false,
      },
    ])
    const app = await buildApp()
    const res = await request(app)
      .put('/external/gfs/grants')
      .set('x-user-session-token', 'sess')
      .send({ resourceId: R, subject: { type: 'user', id: 'not-a-uuid' }, permissions: ['read'] })
    expect(res.status).toBe(400)
    expect(res.body.error).toBe('subject_invalid')
  })

  it('rejects a user granting TO the operator subject → 403 operator_grant_forbidden', async () => {
    auth()
    dbReturning([
      {
        subject_type: 'user',
        subject_id: U1,
        resource_id: R,
        permissions: ['manage_acl', 'read'],
        inherit: false,
      },
    ])
    const app = await buildApp()
    const res = await request(app)
      .put('/external/gfs/grants')
      .set('x-user-session-token', 'sess')
      .send({ resourceId: R, subject: { type: 'operator' }, permissions: ['read'], inherit: false })
    expect(res.status).toBe(403)
    expect(res.body.error).toBe('operator_grant_forbidden')
  })

  it('rejects escalation: user grants a bit it does NOT hold → 403', async () => {
    auth()
    // User holds manage_acl + read, but NOT write → cannot grant write.
    dbReturning([
      {
        subject_type: 'user',
        subject_id: U1,
        resource_id: R,
        permissions: ['manage_acl', 'read'],
        inherit: false,
      },
    ])
    const app = await buildApp()
    const res = await request(app)
      .put('/external/gfs/grants')
      .set('x-user-session-token', 'sess')
      .send({
        resourceId: R,
        subject: { type: 'user', id: U2 },
        permissions: ['write'],
        inherit: false,
      })
    expect(res.status).toBe(403)
    expect(res.body.error).toBe('escalation_rejected')
    expect(mockAppendPermissionEvents).toHaveBeenCalledWith(
      expect.anything(),
      expect.objectContaining({
        changes: [expect.objectContaining({ outcome: 'rejected', authorizationDecision: 'deny' })],
      })
    )
  })
})

describe('POST /external/gfs/shares (user delegation via existing engine)', () => {
  it('persists the typed audit and normalized administrative event in the same transaction', async () => {
    auth()
    dbReturning([
      {
        subject_type: 'user',
        subject_id: U1,
        resource_id: R,
        permissions: ['share', 'read'],
        inherit: false,
      },
    ])
    const app = await buildApp()
    const res = await request(app)
      .post('/external/gfs/shares')
      .set('x-user-session-token', 'sess')
      .send({
        resourceId: R,
        subject: { type: 'user', id: U2 },
        permissions: ['read'],
        includeDescendants: false,
      })

    expect(res.status).toBe(200)
    expect(res.body).toEqual({
      ok: true,
      resourceId: R,
      updated: [{ type: 'user', id: U2 }],
      count: 1,
    })
    expect(
      mockQuery.mock.calls.some(call => String(call[0]).includes('INSERT INTO gfs_shares'))
    ).toBe(true)
    expect(mockAppendPermissionEvents).toHaveBeenCalledWith(
      expect.anything(),
      expect.objectContaining({
        operatorSub: U1,
        changes: [
          expect.objectContaining({
            resourceClass: 'gfs_share',
            outcome: 'committed',
            detailRef: 'gfs_permissions/read',
          }),
        ],
      })
    )
  })

  it.each([
    ['operator', { type: 'operator' }],
    ['context', { type: 'context', id: 'run-context' }],
  ])('preserves singular %s shares for an operator caller', async (_label, subject) => {
    dbReturning([])
    const app = await buildOperatorShareApp()

    const res = await request(app)
      .post('/gfs/shares')
      .send({
        resourceId: R,
        subject,
        permissions: ['read'],
        includeDescendants: false,
      })

    expect(res.status).toBe(200)
    expect(res.body).toEqual({ ok: true, resourceId: R, updated: [subject], count: 1 })
    const mutations = mockQuery.mock.calls.filter(call =>
      String(call[0]).includes('INSERT INTO gfs_shares')
    )
    expect(mutations).toHaveLength(1)
    expect(mutations[0]?.[1]?.[2]).toEqual([subject.type])
    expect(mutations[0]?.[1]?.[3]).toEqual(['id' in subject ? subject.id : ''])
  })

  it('preserves the singular host share rejection for an operator caller', async () => {
    dbReturning([])
    const app = await buildOperatorShareApp()

    const res = await request(app)
      .post('/gfs/shares')
      .send({
        resourceId: R,
        subject: { type: 'host', id: H1 },
        permissions: ['read'],
        includeDescendants: false,
      })

    expect(res.status).toBe(403)
    expect(res.body).toEqual({
      error: 'share_to_agent_forbidden',
      message: 'share_to_agent_forbidden',
    })
    expect(
      mockQuery.mock.calls.some(call => String(call[0]).includes('INSERT INTO gfs_shares'))
    ).toBe(false)
    expect(mockAppendPermissionEvents).toHaveBeenCalledWith(
      expect.anything(),
      expect.objectContaining({
        operatorSub: 'operator-share-test',
        operatorKind: 'control_admin',
        changes: [
          expect.objectContaining({
            outcome: 'rejected',
            authorizationDecision: 'deny',
            subject: { kind: 'service', id: `host:${H1}`, principalKind: 'host' },
          }),
        ],
      })
    )
  })
})

describe('GET /external/gfs/shares (delegation metadata parity)', () => {
  it('lists shares for an ordinary user with manage_acl and hides inaccessible/missing resources', async () => {
    auth()
    const item = {
      id: 'aaaaaaaa-0000-4000-8000-000000000001',
      drive: 'main',
      resource_id: R,
      subject_type: 'user',
      subject_id: U2,
      permissions: ['read'],
      include_descendants: true,
    }
    dbReturning(
      [
        {
          subject_type: 'user',
          subject_id: U1,
          resource_id: R,
          permissions: ['manage_acl'],
          inherit: false,
        },
      ],
      { grantListRows: [item] }
    )

    const allowed = await request(await buildApp())
      .get(`/external/gfs/shares?drive=main&resourceId=${R}`)
      .set('x-user-session-token', 'sess')
    expect(allowed.status).toBe(200)
    expect(allowed.body.items).toEqual([
      expect.objectContaining({
        id: item.id,
        resourceId: R,
        subject: { type: 'user', id: U2 },
        includeDescendants: true,
      }),
    ])

    mockQuery.mockReset()
    dbReturning([])
    const hidden = await request(await buildApp())
      .get(`/external/gfs/shares?drive=main&resourceId=${R2}`)
      .set('x-user-session-token', 'sess')
    expect(hidden.status).toBe(403)
    expect(hidden.body.error).toBe('manage_acl_required')
  })
})

describe('authenticated bulk grant/share transport', () => {
  const authority = (permissions: string[]) =>
    dbReturning([
      {
        subject_type: 'user',
        subject_id: U1,
        resource_id: R,
        permissions,
        inherit: false,
      },
    ])

  it('keeps singular grant responses compatible with the ordered result envelope', async () => {
    auth()
    authority(['manage_acl', 'read'])
    const app = await buildApp()

    const res = await request(app)
      .put('/external/gfs/grants')
      .set('x-user-session-token', 'sess')
      .send({
        resourceId: R,
        subject: { type: 'user', id: U2 },
        permissions: ['read'],
        inherit: false,
      })

    expect(res.status).toBe(200)
    expect(res.body).toEqual({
      ok: true,
      resourceId: R,
      updated: [{ type: 'user', id: U2 }],
      count: 1,
    })
  })

  it('bulk grants user, team, and canonical host subjects in input order with one mutation', async () => {
    auth()
    authority(['manage_acl', 'read'])
    const app = await buildApp()
    const subjects = [
      { type: 'user', id: U2 },
      { type: 'team', id: T2 },
      { type: 'host', id: H1 },
    ]

    const res = await request(app)
      .put('/external/gfs/grants')
      .set('x-user-session-token', 'sess')
      .set('x-correlation-id', CORRELATION_ID)
      .send({ resourceId: R, subjects, permissions: ['read'], inherit: true })

    expect(res.status).toBe(200)
    expect(res.body).toEqual({ ok: true, resourceId: R, updated: subjects, count: 3 })
    const mutations = mockQuery.mock.calls.filter(call =>
      String(call[0]).includes('INSERT INTO gfs_grants')
    )
    expect(mutations).toHaveLength(1)

    const audits = mockQuery.mock.calls.filter(call =>
      String(call[0]).includes('INSERT INTO gfs_audit')
    )
    expect(audits.map(call => call[1]?.[0])).toEqual([`user:${U2}`, `team:${T2}`, `host:${H1}`])
    expect(audits.map(call => call[1]?.[6])).toEqual([
      CORRELATION_ID,
      CORRELATION_ID,
      CORRELATION_ID,
    ])
    expect(mockAppendPermissionEvents).toHaveBeenCalledTimes(1)
    expect(mockAppendPermissionEvents).toHaveBeenCalledWith(
      expect.anything(),
      expect.objectContaining({
        requestId: CORRELATION_ID,
        changes: [
          expect.objectContaining({ subject: { kind: 'user', id: U2 }, outcome: 'committed' }),
          expect.objectContaining({ subject: { kind: 'team', id: T2 }, outcome: 'committed' }),
          expect.objectContaining({
            subject: { kind: 'service', id: `host:${H1}`, principalKind: 'host' },
            outcome: 'committed',
          }),
        ],
      })
    )
  })

  it('bulk shares user and team subjects in input order with one mutation', async () => {
    auth()
    authority(['share', 'read'])
    const app = await buildApp()
    const subjects = [
      { type: 'team', id: T2 },
      { type: 'user', id: U2 },
    ]

    const res = await request(app)
      .post('/external/gfs/shares')
      .set('x-user-session-token', 'sess')
      .send({ resourceId: R, subjects, permissions: ['read'], includeDescendants: true })

    expect(res.status).toBe(200)
    expect(res.body).toEqual({ ok: true, resourceId: R, updated: subjects, count: 2 })
    expect(
      mockQuery.mock.calls.filter(call => String(call[0]).includes('INSERT INTO gfs_shares'))
    ).toHaveLength(1)
    expect(mockAppendPermissionEvents).toHaveBeenCalledTimes(1)
    expect(mockAppendPermissionEvents.mock.calls[0]?.[1]?.changes).toHaveLength(2)
  })

  it.each([
    ['grant', 'put', '/external/gfs/grants', 'INSERT INTO gfs_grants', ['manage_acl', 'read']],
    ['share', 'post', '/external/gfs/shares', 'INSERT INTO gfs_shares', ['share', 'read']],
  ] as const)(
    'canonicalizes uppercase UUID subjects throughout a successful %s mutation',
    async (_label, method, path, mutationSql, heldPermissions) => {
      auth()
      authority([...heldPermissions])
      const app = await buildApp()

      const res = await request(app)
        [method](path)
        .set('x-user-session-token', 'sess')
        .send({
          resourceId: R,
          subjects: [
            { type: 'user', id: U2.toUpperCase() },
            { type: 'team', id: T2.toUpperCase() },
          ],
          permissions: ['read'],
        })

      expect(res.status).toBe(200)
      expect(res.body).toEqual({
        ok: true,
        resourceId: R,
        updated: [
          { type: 'user', id: U2 },
          { type: 'team', id: T2 },
        ],
        count: 2,
      })
      const mutation = mockQuery.mock.calls.find(call => String(call[0]).includes(mutationSql))
      expect(mutation?.[1]?.[3]).toEqual([U2, T2])
      const audits = mockQuery.mock.calls.filter(call =>
        String(call[0]).includes('INSERT INTO gfs_audit')
      )
      expect(audits.map(call => call[1]?.[0])).toEqual([`user:${U2}`, `team:${T2}`])
    }
  )

  it.each([
    ['grant', 'put', '/external/gfs/grants', 'INSERT INTO gfs_grants', ['manage_acl', 'read']],
    ['share', 'post', '/external/gfs/shares', 'INSERT INTO gfs_shares', ['share', 'read']],
  ] as const)(
    'rejects a mixed-case duplicate %s batch with the common structured error',
    async (_label, method, path, mutationSql, heldPermissions) => {
      auth()
      authority([...heldPermissions])
      const app = await buildApp()

      const res = await request(app)
        [method](path)
        .set('x-user-session-token', 'sess')
        .send({
          resourceId: R,
          subjects: [
            { type: 'user', id: U2 },
            { type: 'user', id: U2.toUpperCase() },
          ],
          permissions: ['read'],
        })

      expect(res.status).toBe(400)
      expect(res.body).toEqual({
        error: 'subjects_invalid',
        message: 'subjects_invalid',
        invalidIndexes: [1],
      })
      expect(mockQuery.mock.calls.some(call => String(call[0]).includes(mutationSql))).toBe(false)
      expect(mockAppendPermissionEvents).not.toHaveBeenCalled()
    }
  )

  it.each([
    ['grant with neither field', 'put', '/external/gfs/grants', {}],
    [
      'grant with both fields',
      'put',
      '/external/gfs/grants',
      { subject: { type: 'user', id: U2 }, subjects: [{ type: 'team', id: T2 }] },
    ],
    ['share with neither field', 'post', '/external/gfs/shares', {}],
    [
      'share with both fields',
      'post',
      '/external/gfs/shares',
      { subject: { type: 'user', id: U2 }, subjects: [{ type: 'team', id: T2 }] },
    ],
  ] as const)(
    'gives subject transport precedence for %s even when resourceId is invalid',
    async (_label, method, path, subjectFields) => {
      auth()
      mockQuery.mockImplementation(
        async (text: string) =>
          activeSessionLifecycleResult(text) ?? limiterRow(text) ?? { rows: [] }
      )
      const app = await buildApp()

      const res = await request(app)
        [method](path)
        .set('x-user-session-token', 'sess')
        .send({ resourceId: 'not-a-uuid', ...subjectFields, permissions: ['read'] })

      expect(res.status).toBe(400)
      expect(res.body).toEqual({ error: 'subjects_invalid', message: 'subjects_invalid' })
      expect(
        mockQuery.mock.calls.some(call => /INSERT INTO gfs_(?:grants|shares)/.test(String(call[0])))
      ).toBe(false)
      expect(mockAppendPermissionEvents).not.toHaveBeenCalled()
    }
  )

  it.each([
    ['grant', 'put', '/external/gfs/grants'],
    ['share', 'post', '/external/gfs/shares'],
  ] as const)(
    'serializes an invalid resource consistently for %s writes',
    async (_label, method, path) => {
      auth()
      mockQuery.mockImplementation(
        async (text: string) =>
          activeSessionLifecycleResult(text) ?? limiterRow(text) ?? { rows: [] }
      )
      const app = await buildApp()

      const res = await request(app)
        [method](path)
        .set('x-user-session-token', 'sess')
        .send({
          resourceId: 'not-a-uuid',
          subject: { type: 'user', id: U2 },
          permissions: ['read'],
        })

      expect(res.status).toBe(400)
      expect(res.body).toEqual({ error: 'resource_invalid', message: 'resource_invalid' })
      expect(
        mockQuery.mock.calls.some(call => /INSERT INTO gfs_(?:grants|shares)/.test(String(call[0])))
      ).toBe(false)
      expect(mockAppendPermissionEvents).not.toHaveBeenCalled()
    }
  )

  it.each([
    ['operator', { type: 'operator' }],
    ['context', { type: 'context', id: 'run-context' }],
  ])('rejects plural %s grants before mutation', async (_label, unsupported) => {
    auth()
    authority(['manage_acl', 'read'])
    const app = await buildApp()

    const res = await request(app)
      .put('/external/gfs/grants')
      .set('x-user-session-token', 'sess')
      .send({
        resourceId: R,
        subjects: [{ type: 'user', id: U2 }, unsupported],
        permissions: ['read'],
      })

    expect(res.status).toBe(400)
    expect(res.body).toMatchObject({ error: 'subjects_invalid', invalidIndexes: [1] })
    expect(
      mockQuery.mock.calls.some(call => String(call[0]).includes('INSERT INTO gfs_grants'))
    ).toBe(false)
    expect(mockAppendPermissionEvents).not.toHaveBeenCalled()
  })

  it.each([
    ['host', { type: 'host', id: H1 }],
    ['operator', { type: 'operator' }],
    ['context', { type: 'context', id: 'run-context' }],
  ])('rejects a %s in plural shares before mutation', async (_label, unsupported) => {
    auth()
    authority(['share', 'read'])
    const app = await buildApp()

    const res = await request(app)
      .post('/external/gfs/shares')
      .set('x-user-session-token', 'sess')
      .send({
        resourceId: R,
        subjects: [{ type: 'user', id: U2 }, unsupported],
        permissions: ['read'],
      })

    expect(res.status).toBe(400)
    expect(res.body).toMatchObject({ error: 'subjects_invalid', invalidIndexes: [1] })
    expect(
      mockQuery.mock.calls.some(call => String(call[0]).includes('INSERT INTO gfs_shares'))
    ).toBe(false)
    expect(mockAppendPermissionEvents).not.toHaveBeenCalled()
  })

  it('denies an entire mixed grant batch without mutation and records correlated denial evidence', async () => {
    auth()
    authority(['manage_acl'])
    const app = await buildApp()

    const res = await request(app)
      .put('/external/gfs/grants')
      .set('x-user-session-token', 'sess')
      .set('x-correlation-id', CORRELATION_ID)
      .send({
        resourceId: R,
        subjects: [
          { type: 'user', id: U2 },
          { type: 'host', id: H1 },
        ],
        permissions: ['manage_acl'],
      })

    expect(res.status).toBe(403)
    expect(res.body.error).toBe('agent_manager_forbidden')
    expect(
      mockQuery.mock.calls.some(call => String(call[0]).includes('INSERT INTO gfs_grants'))
    ).toBe(false)
    const audits = mockQuery.mock.calls.filter(call =>
      String(call[0]).includes('INSERT INTO gfs_audit')
    )
    expect(audits.map(call => [call[1]?.[0], call[1]?.[4], call[1]?.[6]])).toEqual([
      [`user:${U2}`, 'denied', CORRELATION_ID],
      [`host:${H1}`, 'denied', CORRELATION_ID],
    ])
    expect(mockAppendPermissionEvents).toHaveBeenCalledTimes(1)
    expect(mockAppendPermissionEvents.mock.calls[0]?.[1]?.changes).toEqual([
      expect.objectContaining({ outcome: 'rejected', authorizationDecision: 'deny' }),
      expect.objectContaining({ outcome: 'rejected', authorizationDecision: 'deny' }),
    ])
  })

  it('denies an entire plural grant batch when a managed first-party host exceeds read/write', async () => {
    auth()
    // The caller holds every requested bit, so the only thing standing between
    // this batch and a mutation is the managed first-party host permission cap.
    authority(['manage_acl', 'read', 'delete'])
    const app = await buildApp()

    const res = await request(app)
      .put('/external/gfs/grants')
      .set('x-user-session-token', 'sess')
      .set('x-correlation-id', CORRELATION_ID)
      .send({
        resourceId: R,
        subjects: [
          { type: 'user', id: U2 },
          { type: 'host', id: H1 },
        ],
        permissions: ['read', 'delete'],
      })

    expect(res.status).toBe(403)
    expect(res.body.error).toBe('managed_agent_permission_forbidden')
    expect(
      mockQuery.mock.calls.some(call => String(call[0]).includes('INSERT INTO gfs_grants'))
    ).toBe(false)
  })

  it('does not publish staged mutation or audit effects when event persistence fails', async () => {
    auth()
    authority(['manage_acl', 'read'])
    const attempted: string[] = []
    const committed: string[] = []
    mockWithTransaction.mockImplementation(
      async (
        work: (db: {
          query: (text: string, values?: unknown[]) => Promise<{ rows: unknown[] }>
        }) => Promise<unknown>
      ) => {
        const staged: string[] = []
        const result = await work({
          query: async (text: string, values?: unknown[]) => {
            if (text.includes('INSERT INTO gfs_grants')) staged.push('grant')
            if (text.includes('INSERT INTO gfs_audit')) staged.push('audit')
            attempted.push(...staged.slice(attempted.length))
            return mockQuery(text, values)
          },
        })
        committed.push(...staged)
        return result
      }
    )
    mockAppendPermissionEvents.mockRejectedValueOnce(new Error('permission event write failed'))
    const app = await buildApp()

    const res = await request(app)
      .put('/external/gfs/grants')
      .set('x-user-session-token', 'sess')
      .send({
        resourceId: R,
        subjects: [
          { type: 'user', id: U2 },
          { type: 'team', id: T2 },
        ],
        permissions: ['read'],
      })

    expect(res.status).toBe(500)
    expect(attempted).toContain('grant')
    expect(attempted).toContain('audit')
    expect(committed).toEqual([])
  })
})

describe('GET /external/gfs/resources/:id/affordances', () => {
  it('returns the bits the caller holds + isOperator:false', async () => {
    auth()
    dbReturning([
      {
        subject_type: 'user',
        subject_id: U1,
        resource_id: R,
        permissions: ['read', 'manage_acl'],
        inherit: false,
      },
    ])
    const app = await buildApp()
    const res = await request(app)
      .get(`/external/gfs/resources/${R}/affordances`)
      .set('x-user-session-token', 'sess')
    expect(res.status).toBe(200)
    expect(res.body.isOperator).toBe(false)
    expect(new Set(res.body.held)).toEqual(new Set(['read', 'manage_acl']))
  })

  it('includes permissions held through any active team, not only the session teamId', async () => {
    auth()
    mockQuery.mockImplementation(async (text: string, values?: unknown[]) => {
      const lifecycle = activeSessionLifecycleResult(text)
      const limiter = limiterRow(text)
      if (limiter) return limiter
      if (lifecycle) return lifecycle
      if (text.includes('FROM team_members')) return { rows: [{ team_id: T2 }] }
      if (text.includes('WITH RECURSIVE chain'))
        return { rows: [{ resource_id: String(values?.[1]) }] }
      if (text.includes('FROM gfs_grants')) {
        const subjectTypes = (values?.[1] as string[]) ?? []
        const subjectIds = (values?.[2] as string[]) ?? []
        const wanted = new Set(subjectTypes.map((type, i) => `${type}:${subjectIds[i] ?? ''}`))
        const rows = [
          {
            subject_type: 'team',
            subject_id: T2,
            resource_id: R,
            permissions: ['read', 'manage_acl'],
            inherit: false,
          },
        ]
        return { rows: rows.filter(row => wanted.has(`${row.subject_type}:${row.subject_id}`)) }
      }
      if (text.includes('FROM gfs_shares')) return { rows: [] }
      return { rows: [] }
    })

    const app = await buildApp()
    const res = await request(app)
      .get(`/external/gfs/resources/${R}/affordances`)
      .set('x-user-session-token', 'sess')

    expect(res.status).toBe(200)
    expect(res.body.isOperator).toBe(false)
    expect(new Set(res.body.held)).toEqual(new Set(['read', 'manage_acl']))
  })
})

describe('user resource mutations via gfsc proxy', () => {
  it('rejects non-session tokens on external mutation routes before minting a GFS token', async () => {
    mockVerifyExternalSessionToken.mockReturnValue(null)
    const fetchMock = vi.fn()
    vi.stubGlobal('fetch', fetchMock)
    const app = await buildApp()
    const res = await request(app)
      .post(`/external/gfs/resources/${R}/children`)
      .set('x-user-session-token', 'operator-jwt')
      .send({ name: 'docs', kind: 'directory' })

    expect(res.status).toBe(401)
    expect(mockSignGfsToken).not.toHaveBeenCalled()
    expect(fetchMock).not.toHaveBeenCalled()
  })

  it('rejects a mutation with no session header before minting or proxying', async () => {
    mockVerifyExternalSessionToken.mockReturnValue(null)
    const fetchMock = vi.fn()
    vi.stubGlobal('fetch', fetchMock)
    const app = await buildApp()
    const res = await request(app).delete(`/external/gfs/resources/${R}`).send({ ifMatch: 1 })

    expect(res.status).toBe(401)
    expect(mockSignGfsToken).not.toHaveBeenCalled()
    expect(fetchMock).not.toHaveBeenCalled()
  })

  it('creates a child with a user gfs.write token', async () => {
    auth()
    const fetchMock = vi.fn(
      async () =>
        new Response(JSON.stringify({ ok: true, data: { resourceId: R2 } }), {
          status: 201,
          headers: { 'content-type': 'application/json' },
        })
    )
    vi.stubGlobal('fetch', fetchMock)
    const app = await buildApp()
    const res = await request(app)
      .post(`/external/gfs/resources/${R}/children`)
      .set('x-user-session-token', 'sess')
      .send({ name: 'docs', kind: 'directory' })

    expect(res.status).toBe(201)
    expect(mockSignGfsToken).toHaveBeenCalledWith({
      subject: U1,
      drive: 'main',
      scopes: ['gfs.write'],
      authGeneration: 1,
      principalType: 'user',
    })
    expect(fetchMock).toHaveBeenCalledWith(
      'http://gfsc-writer.gfs.svc:8087/v1/resources/' + R_RID + '/children',
      {
        method: 'POST',
        headers: expect.objectContaining({ 'content-type': 'application/json' }),
        body: JSON.stringify({ name: 'docs', kind: 'directory' }),
        signal: expect.any(AbortSignal),
      }
    )
  })

  it('deletes a resource with a user gfs.delete token', async () => {
    auth()
    const fetchMock = vi.fn(
      async () =>
        new Response(JSON.stringify({ ok: true, data: { deleted: true } }), {
          status: 200,
          headers: { 'content-type': 'application/json' },
        })
    )
    vi.stubGlobal('fetch', fetchMock)
    const app = await buildApp()
    const res = await request(app)
      .delete(`/external/gfs/resources/${R}`)
      .set('x-user-session-token', 'sess')
      .send({ ifMatch: 3 })

    expect(res.status).toBe(200)
    expect(mockSignGfsToken).toHaveBeenCalledWith({
      subject: U1,
      drive: 'main',
      scopes: ['gfs.delete'],
      authGeneration: 1,
      principalType: 'user',
    })
    expect(fetchMock).toHaveBeenCalledWith(
      'http://gfsc-writer.gfs.svc:8087/v1/resources/' + R_RID,
      {
        method: 'DELETE',
        headers: expect.objectContaining({ 'content-type': 'application/json' }),
        body: JSON.stringify({ ifMatch: 3 }),
        signal: expect.any(AbortSignal),
      }
    )
  })

  it('returns 504 gfsc_timeout when the gfsc mutation fetch times out', async () => {
    auth()
    const fetchMock = vi.fn(async () => {
      const err = new Error('The operation was aborted due to timeout')
      err.name = 'TimeoutError'
      throw err
    })
    vi.stubGlobal('fetch', fetchMock)
    const app = await buildApp()
    const res = await request(app)
      .post(`/external/gfs/resources/${R}/children`)
      .set('x-user-session-token', 'sess')
      .send({ name: 'docs', kind: 'file', contentBase64: 'AAAA' })
    expect(res.status).toBe(504)
    expect(res.body).toEqual({ error: 'gfsc_timeout' })
  })

  it('returns 504 when gfsc sends mutation headers then stalls the response body', async () => {
    // The response-body read is bounded by the same deadline; a stall after
    // headers must classify as 504 (via the guarded text()), not reject uncaught
    // into a generic 500. The mock wires the deadline signal to the body stream
    // the way undici does, then never sends bytes.
    auth()
    ;(config as { gfscProxyTimeoutMs: number }).gfscProxyTimeoutMs = 20
    const fetchMock = vi.fn((_url: string, init: { signal: AbortSignal }) =>
      Promise.resolve(
        new Response(
          new ReadableStream({
            pull(controller) {
              init.signal.addEventListener('abort', () => controller.error(init.signal.reason))
            },
          }),
          { status: 200, headers: { 'content-type': 'application/json' } }
        )
      )
    )
    vi.stubGlobal('fetch', fetchMock)
    const app = await buildApp()
    const res = await request(app)
      .post(`/external/gfs/resources/${R}/children`)
      .set('x-user-session-token', 'sess')
      .send({ name: 'docs', kind: 'file', contentBase64: 'AAAA' })

    expect(res.status).toBe(504)
    expect(res.body).toEqual({ error: 'gfsc_timeout' })
  })

  it('forwards a gfsc 5xx on a user mutation verbatim (never a silent 500)', async () => {
    auth()
    const fetchMock = vi.fn(
      async () =>
        new Response(JSON.stringify({ ok: false, error: { code: 'internal' } }), {
          status: 500,
          headers: { 'content-type': 'application/json' },
        })
    )
    vi.stubGlobal('fetch', fetchMock)
    const app = await buildApp()
    const res = await request(app)
      .post(`/external/gfs/resources/${R}/children`)
      .set('x-user-session-token', 'sess')
      .send({ name: 'docs', kind: 'file', contentBase64: 'AAAA' })
    expect(res.status).toBe(500)
    expect(res.body).toEqual({ ok: false, error: { code: 'internal' } })
  })
})

describe('GET /external/gfs/resources', () => {
  it('lists readable direct user resources and active-team resources as Desktop entry points', async () => {
    auth()
    mockQuery.mockImplementation(async (text: string, values?: unknown[]) => {
      const lifecycle = activeSessionLifecycleResult(text)
      const limiter = limiterRow(text)
      if (limiter) return limiter
      if (lifecycle) return lifecycle
      if (text.includes('FROM team_members')) return { rows: [{ team_id: T1 }] }
      if (text.includes('FROM gfs_grants') && text.includes('JOIN requested_subjects')) {
        expect(values?.[1]).toEqual(['user', 'team'])
        expect(values?.[2]).toEqual([U1, T1])
        return {
          rows: [
            {
              resource_id: R,
              drive: 'main',
              parent_resource_id: null,
              name: 'team-folder-tree',
              kind: 'directory',
              path_cache: '/team-folder-tree',
              version: 1,
              bytes: 0,
              updated_at: new Date('2026-01-01T00:00:00.000Z'),
              sources: ['grant'],
              permissions: ['read'],
              covers_descendants: true,
            },
            {
              resource_id: R2,
              drive: 'main',
              parent_resource_id: R,
              name: 'external-file.pdf',
              kind: 'file',
              path_cache: '/other-org/external-file.pdf',
              version: 2,
              bytes: 128,
              updated_at: new Date('2026-06-01T12:00:00.000Z'),
              sources: ['share'],
              permissions: ['read'],
              covers_descendants: false,
            },
          ],
        }
      }
      return { rows: [] }
    })
    const app = await buildApp()
    const res = await request(app)
      .get('/external/gfs/resources')
      .set('x-user-session-token', 'sess')
    expect(res.status).toBe(200)
    expect(res.body.ok).toBe(true)
    expect(res.body.data.items).toEqual([
      expect.objectContaining({
        resourceId: R,
        name: 'team-folder-tree',
        kind: 'directory',
        sources: ['grant'],
        coversDescendants: true,
        updatedAt: '2026-01-01T00:00:00.000Z',
      }),
      expect.objectContaining({
        resourceId: R2,
        name: 'external-file.pdf',
        kind: 'file',
        sources: ['share'],
        coversDescendants: false,
        updatedAt: '2026-06-01T12:00:00.000Z',
      }),
    ])
  })
})

describe('per-agent delegation surface (guard + list + rate limit)', () => {
  const authority = (permissions: string[], opts: Parameters<typeof dbReturning>[1] = {}) =>
    dbReturning(
      [
        {
          subject_type: 'user',
          subject_id: U1,
          resource_id: R,
          permissions,
          inherit: false,
        },
      ],
      opts
    )
  const putGrants = (app: express.Express, body: Record<string, unknown>) =>
    request(app)
      .put('/external/gfs/grants')
      .set('x-user-session-token', 'sess')
      .send({ resourceId: R, permissions: ['read'], inherit: true, ...body })

  it('rejects a single valid-but-foreign host without indexes and writes nothing', async () => {
    auth()
    authority(['manage_acl', 'read'], { callerAgentNames: ['other-agent'] })
    const app = await buildApp()
    const res = await putGrants(app, { subject: { type: 'host', id: H1 } })
    expect(res.status).toBe(403)
    expect(res.body.error).toBe('foreign_agent_forbidden')
    expect(res.body.invalidIndexes).toBeUndefined()
    expect(
      mockQuery.mock.calls.filter(call => String(call[0]).includes('INSERT INTO gfs_grants'))
    ).toHaveLength(0)
  })

  it('rejects a plural body with the foreign host indexes and writes nothing', async () => {
    auth()
    authority(['manage_acl', 'read'], { callerAgentNames: ['agent-b'] })
    const app = await buildApp()
    const res = await putGrants(app, {
      subjects: [
        { type: 'user', id: U2 },
        { type: 'host', id: H1 },
        { type: 'host', id: '1st:mcp-host/agent-b' },
      ],
    })
    expect(res.status).toBe(403)
    expect(res.body.error).toBe('foreign_agent_forbidden')
    expect(res.body.invalidIndexes).toEqual([1])
    expect(
      mockQuery.mock.calls.filter(call => String(call[0]).includes('INSERT INTO gfs_grants'))
    ).toHaveLength(0)
  })

  it('leaves malformed host ids to the subjects_invalid contract', async () => {
    auth()
    authority(['manage_acl', 'read'], { callerAgentNames: [] })
    const app = await buildApp()
    const res = await putGrants(app, { subjects: [{ type: 'host', id: 'not-a-host' }] })
    expect(res.status).toBe(400)
    expect(res.body.error).toBe('subjects_invalid')
  })

  it('lists id-bearing grant rows for a manage_acl holder', async () => {
    auth()
    authority(['manage_acl'], {
      grantListRows: [
        {
          id: 'aaaa1111-0000-4000-8000-000000000001',
          drive: 'main',
          resource_id: R,
          subject_type: 'host',
          subject_id: H1,
          permissions: ['read', 'write'],
          inherit: true,
        },
      ],
    })
    const app = await buildApp()
    const res = await request(app)
      .get('/external/gfs/grants')
      .query({ drive: 'main', resourceId: R })
      .set('x-user-session-token', 'sess')
    expect(res.status).toBe(200)
    expect(res.body).toEqual({
      items: [
        {
          id: 'aaaa1111-0000-4000-8000-000000000001',
          drive: 'main',
          resourceId: R,
          subject: { type: 'host', id: H1 },
          permissions: ['read', 'write'],
          inherit: true,
        },
      ],
    })
  })

  it('denies the grants list to a caller without manage_acl', async () => {
    auth()
    authority(['read', 'write'])
    const app = await buildApp()
    const res = await request(app)
      .get('/external/gfs/grants')
      .query({ drive: 'main', resourceId: R })
      .set('x-user-session-token', 'sess')
    expect(res.status).toBe(403)
    expect(res.body.error).toBe('manage_acl_required')
  })

  it('answers an unknown resource with the same 403 (no existence oracle)', async () => {
    auth()
    dbReturning([])
    const app = await buildApp()
    const res = await request(app)
      .get('/external/gfs/grants')
      .query({ drive: 'main', resourceId: R2 })
      .set('x-user-session-token', 'sess')
    expect(res.status).toBe(403)
    expect(res.body.error).toBe('manage_acl_required')
  })

  it('rate limits the grants mutation class before authority resolution', async () => {
    auth()
    authority(['manage_acl', 'read'], { rateLimitCount: 31 })
    const app = await buildApp()
    const res = await putGrants(app, { subject: { type: 'user', id: U2 } })
    expect(res.status).toBe(429)
    expect(res.body.error).toBe('Too Many Requests')
    expect(res.body.retryAfterSeconds).toBeGreaterThanOrEqual(1)
    const bucketCall = mockQuery.mock.calls.find(
      call =>
        String(call[0]).includes('rate_limit_buckets') &&
        String(call[1]?.[0]).startsWith('gfs-ext:pre:grants-mutation:session:')
    )
    expect(bucketCall?.[1]?.[0]).toMatch(/^gfs-ext:pre:grants-mutation:session:[0-9a-f]{64}$/)
  })

  it('keys the external delegation plane in a bucket DISTINCT from the admin plane for the same subject', async () => {
    // Same subject id (U1) is driven through BOTH planes; each plane's own
    // production getBucketKey closure runs and its bucket key is captured from
    // the rate_limit_buckets INSERT ([bucketKey, windowStartMs] → values[0]).
    // The PK of rate_limit_buckets is (bucket_key, window_start_ms), so distinct
    // keys are distinct token buckets — exhausting one can never throttle the
    // other for the same subject.
    auth()
    authority(['manage_acl', 'read'])
    const externalApp = await buildApp()
    await putGrants(externalApp, { subject: { type: 'user', id: U2 } })
    const externalKey = mockQuery.mock.calls.find(
      call =>
        String(call[0]).includes('rate_limit_buckets') &&
        String(call[1]?.[0]).startsWith('gfsgrants-ext:')
    )?.[1]?.[0]

    // Admin (operator) grants plane keyed off adminAuth.sub === U1 (same id).
    mockQuery.mockClear()
    const adminApp = await buildAdminGrantsApp(U1)
    await request(adminApp).get('/gfs/grants').query({ drive: 'main', resourceId: R })
    const adminKey = mockQuery.mock.calls.find(call =>
      String(call[0]).includes('rate_limit_buckets')
    )?.[1]?.[0]

    // Both planes emitted a bucket key for the same subject…
    expect(externalKey).toBe(`gfsgrants-ext:user:${U1}`)
    expect(adminKey).toBe(`gfsgrants:${U1}`)
    // …and they are DISTINCT buckets (never collide). The `-ext` separator means
    // the external key does not fall under the admin `gfsgrants:` namespace.
    expect(externalKey).not.toBe(adminKey)
    expect(String(externalKey).startsWith('gfsgrants-ext:')).toBe(true)
    expect(String(adminKey).startsWith('gfsgrants-ext:')).toBe(false)
    expect(String(adminKey).startsWith('gfsgrants:')).toBe(true)
  })

  it('keeps external ACL reads in a distinct read bucket from mutation delegation', async () => {
    auth()
    authority(['manage_acl', 'read'])
    const app = await buildApp()
    await request(app)
      .get('/external/gfs/grants')
      .query({ drive: 'main', resourceId: R })
      .set('x-user-session-token', 'sess')

    const readKey = mockQuery.mock.calls.find(
      call =>
        String(call[0]).includes('rate_limit_buckets') &&
        String(call[1]?.[0]).startsWith('gfsgrants-ext-read:')
    )?.[1]?.[0]

    expect(readKey).toBe(`gfsgrants-ext-read:user:${U1}`)
    expect(String(readKey).startsWith('gfsgrants-ext:')).toBe(false)
  })

  it('adjudicates only well-formed foreign hosts in foreignHostSubjectIndexes', async () => {
    const { foreignHostSubjectIndexes } = await import('../src/routes/external/gfs.js')
    const allowed = new Set([H1])
    expect(
      foreignHostSubjectIndexes(
        [
          { type: 'host', id: H1 },
          { type: 'host', id: '3rd:sandbox-recipes/tool' },
          { type: 'host', id: '1st:mcp-host/standalone' },
          { type: 'user', id: U2 },
          { type: 'host', id: 'garbage' },
          null,
        ],
        allowed
      )
    ).toEqual([1, 2])
  })
})

describe('user read proxy via gfsc (GET /external/gfs/proxy/:rid)', () => {
  const readPath = `/external/gfs/proxy/${R}`

  it('streams a 200 body and forwards content headers with a read gfs.read token', async () => {
    auth()
    const fetchMock = vi.fn(
      async () =>
        new Response('file-bytes-here', {
          status: 200,
          headers: {
            'content-type': 'text/plain',
            'content-length': '15',
            'content-disposition': 'attachment; filename="f.bin"',
          },
        })
    )
    vi.stubGlobal('fetch', fetchMock)
    const app = await buildApp()
    const res = await request(app).get(readPath).set('x-user-session-token', 'sess')

    expect(res.status).toBe(200)
    expect(res.headers['content-type']).toBe('text/plain')
    expect(res.headers['content-length']).toBe('15')
    expect(res.headers['content-disposition']).toBe('attachment; filename="f.bin"')
    expect(res.text).toBe('file-bytes-here')
    expect(mockSignGfsToken).toHaveBeenCalledWith({
      subject: U1,
      drive: 'main',
      scopes: ['gfs.read'],
      authGeneration: 1,
      principalType: 'user',
    })
    expect(fetchMock).toHaveBeenCalledWith(
      `http://gfsc.gfs.svc:8087/v1/resources/${R}/content`,
      expect.objectContaining({ method: 'GET', signal: expect.any(AbortSignal) })
    )
  })

  it('returns 504 gfsc_timeout on a REAL header-deadline abort (AbortError, signal.aborted)', async () => {
    auth()
    ;(config as { gfscProxyTimeoutMs: number }).gfscProxyTimeoutMs = 20
    const fetchMock = vi.fn(
      (_url: string, init: { signal: AbortSignal }) =>
        new Promise((_resolve, reject) => {
          init.signal.addEventListener('abort', () => reject(init.signal.reason))
        })
    )
    vi.stubGlobal('fetch', fetchMock)
    const app = await buildApp()
    const res = await request(app).get(readPath).set('x-user-session-token', 'sess')

    expect(res.status).toBe(504)
    expect(res.body).toEqual({ error: 'gfsc_timeout' })
    expect(fetchMock.mock.calls[0][1].signal.aborted).toBe(true)
  })

  it('returns 502 gfsc_unreachable when the gfsc read fetch fails', async () => {
    auth()
    const fetchMock = vi.fn(async () => {
      throw new Error('connect ECONNREFUSED')
    })
    vi.stubGlobal('fetch', fetchMock)
    const app = await buildApp()
    const res = await request(app).get(readPath).set('x-user-session-token', 'sess')

    expect(res.status).toBe(502)
    expect(res.body).toEqual({ error: 'gfsc_unreachable' })
  })

  it('forwards a gfsc 5xx error body verbatim (never a silent 500)', async () => {
    auth()
    const fetchMock = vi.fn(
      async () =>
        new Response(JSON.stringify({ ok: false, error: { code: 'internal', message: 'boom' } }), {
          status: 500,
          headers: { 'content-type': 'application/json' },
        })
    )
    vi.stubGlobal('fetch', fetchMock)
    const app = await buildApp()
    const res = await request(app).get(readPath).set('x-user-session-token', 'sess')

    expect(res.status).toBe(500)
    expect(res.body).toEqual({ ok: false, error: { code: 'internal', message: 'boom' } })
  })
})