Skip to content

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

TypeScript
40.6 KB
Raw Blame
import type { Request, Router } from 'express'
import { createHash } from 'node:crypto'
import { config } from '../../config.js'
import { type DbClient, pool, withTransaction } from '../../db.js'
import type { ExternalGfsAuthority } from '../../gfs/externalAuthority.js'
import { isValidHostSubjectId } from '../../gfs/hostSubject.js'
import { asyncHandler } from '../../http/asyncHandler.js'
import { requireAuthForControlUI } from '../../middleware/controlUIAuth.js'
import { rateLimitMiddleware } from '../../middleware/rateLimitMiddleware.js'
import {
  type ControlApiPermissionSubject,
  appendControlApiPermissionEventsInTransaction,
} from '../../services/tracing/controlApiPermissionEvents.js'

/**
 * gfs grant write API (Layer-1 operator seed + Layer-2 folder-owner delegation).
 *
 * Enforces the spec's no-escalation invariant (community.md §RBAC model /
 * §Inheritance #4 / §Delegation): a grantor may grant ONLY permissions it
 * itself holds — including `manage_acl` — and only on a resource within its own
 * subtree (i.e. where it holds `manage_acl` on R or an inheriting ancestor of
 * R). The cluster operator is the intrinsic root of trust and bypasses the
 * stored-grant check. Every mutation is appended to the hash-chained,
 * INSERT-only `gfs_audit` log.
 *
 * The allow() evaluation here is a faithful mirror of the gfsc decision logic
 * (gfs-controller/src/authz/resolve.ts `resolveDecision`) — keep the two in
 * lockstep; any divergence is a security bug.
 */

/** Minimal query surface — a pg client/pool satisfies this; tests inject a fake. */
export interface GrantsDb {
  query(text: string, values?: unknown[]): Promise<{ rows: unknown[]; rowCount?: number | null }>
}

const DEFAULT_DRIVE = 'main'
export const PERMISSIONS = ['read', 'write', 'delete', 'manage_acl', 'share'] as const
export type GfsPermission = (typeof PERMISSIONS)[number]
const MANAGED_FIRST_PARTY_HOST_PERMISSIONS = new Set<GfsPermission>(['read', 'write'])
const LEGACY_STANDALONE_HOST_SUBJECT_ID = '1st:mcp-host/standalone'
const SUBJECT_TYPES = ['operator', 'user', 'team', 'host', 'context'] as const
export type GfsSubjectType = (typeof SUBJECT_TYPES)[number]
export const UUID_RE =
  /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

export interface GfsSubject {
  type: GfsSubjectType
  id?: string
}

/** Canonical `type:id` key (operator carries no id → `operator:`). */
export function subjectKey(subject: GfsSubject): string {
  return `${subject.type}:${subject.id ?? ''}`
}

export class GfsGrantError extends Error {
  constructor(
    readonly status: number,
    readonly code: string,
    readonly invalidIndexes?: readonly number[]
  ) {
    super(code)
    this.name = 'GfsGrantError'
  }
}

/** The authenticated caller, reduced to the gfs authority it carries. */
export interface GfsCaller {
  /** Cluster operator — intrinsic full authority, no stored grant required. */
  isOperator: boolean
  /** Canonical subject keys the caller resolves to (self + groups). */
  subjects: Set<string>
  /** Audit actor key (`operator:` or `user:<uuid>`). */
  actorKey: string
  /** Effective admin for a linked Desktop operator; never the Desktop actor. */
  effectiveControlAdminId?: string
  /** Authenticated Desktop actor for brokered external requests. */
  desktopUserId?: string
  /** Broker authority attribution; independent of authorization_source evidence. */
  authoritySource?: 'user-session' | 'linked-admin'
  /** Persisted legacy/effective actor_on_behalf_of value. */
  actorOnBehalfOf?: string | null
}

export function callerAuditFields(caller: GfsCaller): {
  actorOnBehalfOf: string | null
  desktopUserId?: string
  authoritySource?: 'user-session' | 'linked-admin'
} {
  return {
    actorOnBehalfOf: caller.actorOnBehalfOf ?? null,
    ...(caller.desktopUserId ? { desktopUserId: caller.desktopUserId } : {}),
    ...(caller.authoritySource ? { authoritySource: caller.authoritySource } : {}),
  }
}

type RequestWithResolvedGfsSubjects = Request & {
  gfsSubjectKeys?: string[]
}

/**
 * Reduce the authenticated request to its gfs caller. Operators authenticate
 * via Control UI (`req.adminAuth`); folder owners delegate from Profile/Desktop
 * via an external user session (`req.externalAuth`). Team-membership enrichment
 * of a user's subject set is owned by P2-S02 (subjects.ts) and wired into
 * delegation in P2-S04; P2-S01 resolves the user's own `user:<uuid>` subject.
 */
export function resolveCaller(req: Request): GfsCaller {
  const admin = (req as { adminAuth?: { sub?: string } }).adminAuth
  if (admin?.sub) {
    return {
      isOperator: true,
      subjects: new Set(['operator:']),
      actorKey: 'operator:',
      actorOnBehalfOf: 'operator:',
    }
  }
  const authority = (req as { gfsAuthority?: ExternalGfsAuthority }).gfsAuthority
  if (authority?.kind === 'linked-admin') {
    return {
      isOperator: true,
      subjects: new Set(['operator:']),
      actorKey: 'operator:',
      effectiveControlAdminId: authority.controlAdminId,
      desktopUserId: authority.desktopUserId,
      authoritySource: 'linked-admin',
      actorOnBehalfOf: authority.controlAdminId,
    }
  }
  const external = (req as { externalAuth?: { userId?: string; teamId?: string | null } })
    .externalAuth
  if (external?.userId) {
    const key = `user:${external.userId}`
    const preResolved = (req as RequestWithResolvedGfsSubjects).gfsSubjectKeys
    const subjects = new Set(preResolved && preResolved.length > 0 ? preResolved : [key])
    subjects.add(key)
    if (external.teamId) subjects.add(`team:${external.teamId}`)
    return {
      isOperator: false,
      subjects,
      actorKey: key,
      desktopUserId: external.userId,
      authoritySource: 'user-session',
      actorOnBehalfOf: null,
    }
  }
  throw new GfsGrantError(401, 'unauthenticated')
}

interface GrantRow {
  subjectKey: string
  resourceId: string
  permissions: string[]
  inherit: boolean
}
interface ShareRow {
  subjectKey: string
  resourceId: string
  permissions: string[]
  includeDescendants: boolean
}

function subjectColumns(subjects: Set<string>): { types: string[]; ids: string[] } {
  const types: string[] = []
  const ids: string[] = []
  for (const key of subjects) {
    const sep = key.indexOf(':')
    if (sep < 0) continue
    types.push(key.slice(0, sep))
    ids.push(key.slice(sep + 1))
  }
  return { types, ids }
}

/** R plus all ancestors (R included), root last — mirrors permissionClient. */
export async function ancestorsOf(
  db: GrantsDb,
  drive: string,
  resourceId: string
): Promise<string[]> {
  const sql = `
    WITH RECURSIVE chain AS (
      SELECT resource_id, parent_resource_id, 0 AS depth
        FROM gfs_resources
       WHERE drive = $1 AND resource_id = $2::uuid AND deleted_at IS NULL
      UNION ALL
      SELECT r.resource_id, r.parent_resource_id, c.depth + 1
        FROM gfs_resources r
        JOIN chain c ON r.resource_id = c.parent_resource_id
       WHERE r.drive = $1 AND r.deleted_at IS NULL
    )
    SELECT resource_id FROM chain ORDER BY depth ASC`
  const result = await db.query(sql, [drive, resourceId])
  return (result.rows as { resource_id: string }[]).map(row => String(row.resource_id))
}

async function loadGrants(db: GrantsDb, drive: string, subjects: Set<string>): Promise<GrantRow[]> {
  // Filter by the caller's subjects IN SQL (mirrors gfsc grantsFor) — never fetch
  // the whole drive's grants and filter in JS. Keep subject_type and subject_id
  // as independent predicates so the (drive, subject_type, subject_id) index can
  // stay useful as the drive grows.
  if (subjects.size === 0) return []
  const { types, ids } = subjectColumns(subjects)
  if (types.length === 0) return []
  const result = await db.query(
    `WITH requested_subjects(subject_type, subject_id) AS (
       SELECT * FROM unnest($2::text[], $3::text[])
     )
     SELECT g.subject_type, g.subject_id, g.resource_id, g.permissions, g.inherit
       FROM gfs_grants g
       JOIN requested_subjects s
         ON s.subject_type = g.subject_type AND s.subject_id = g.subject_id
      WHERE g.drive = $1`,
    [drive, types, ids]
  )
  return (result.rows as Record<string, unknown>[]).map(r => ({
    subjectKey: `${String(r.subject_type)}:${String(r.subject_id ?? '')}`,
    resourceId: String(r.resource_id),
    permissions: (r.permissions as string[]) ?? [],
    inherit: Boolean(r.inherit),
  }))
}

async function loadShares(db: GrantsDb, drive: string, subjects: Set<string>): Promise<ShareRow[]> {
  if (subjects.size === 0) return []
  const { types, ids } = subjectColumns(subjects)
  if (types.length === 0) return []
  const result = await db.query(
    `WITH requested_subjects(subject_type, subject_id) AS (
       SELECT * FROM unnest($2::text[], $3::text[])
     )
     SELECT s0.subject_type, s0.subject_id, s0.resource_id, s0.permissions, s0.include_descendants
       FROM gfs_shares s0
       JOIN requested_subjects s
         ON s.subject_type = s0.subject_type AND s.subject_id = s0.subject_id
      WHERE s0.drive = $1`,
    [drive, types, ids]
  )
  return (result.rows as Record<string, unknown>[]).map(r => ({
    subjectKey: `${String(r.subject_type)}:${String(r.subject_id ?? '')}`,
    resourceId: String(r.resource_id),
    permissions: (r.permissions as string[]) ?? [],
    includeDescendants: Boolean(r.include_descendants),
  }))
}

/**
 * Does the caller hold `op` on `resourceId`? Faithful mirror of gfsc
 * `resolveDecision`: a grant on R itself, or on an inheriting ancestor; a share
 * on R, or on an ancestor with includeDescendants. Operator is intrinsic.
 */
function holds(
  op: GfsPermission,
  resourceId: string,
  ancestors: Set<string>,
  grants: GrantRow[],
  shares: ShareRow[]
): boolean {
  for (const g of grants) {
    if (!g.permissions.includes(op)) continue
    if (g.resourceId === resourceId) return true
    if (g.inherit && ancestors.has(g.resourceId)) return true
  }
  for (const s of shares) {
    if (!s.permissions.includes(op)) continue
    if (s.resourceId === resourceId) return true
    if (s.includeDescendants && ancestors.has(s.resourceId)) return true
  }
  return false
}

/**
 * Assert the caller may grant `permissions` to `target` on `resourceId`. Throws
 * GfsGrantError on any violation. Enforces: no-escalation (only bits held,
 * incl. manage_acl, within subtree); a folder owner may never make an agent
 * (`host`) a manager (`manage_acl`/`share`) — operator only.
 */
export async function assertMayGrant(
  db: GrantsDb,
  caller: GfsCaller,
  drive: string,
  resourceId: string,
  permissions: GfsPermission[],
  target: GfsSubject,
  opts: { isShare: boolean; allowLegacyRetirement?: boolean }
): Promise<void> {
  await assertMayGrantBatch(db, caller, drive, resourceId, permissions, [target], opts)
}

interface GrantAuthoritySnapshot {
  ancestors: Set<string>
  grants: GrantRow[]
  shares: ShareRow[]
}

async function loadGrantAuthority(
  db: GrantsDb,
  caller: GfsCaller,
  drive: string,
  resourceId: string
): Promise<GrantAuthoritySnapshot | null> {
  if (caller.isOperator) return null
  const { types, ids } = subjectColumns(caller.subjects)
  const result = await db.query(
    `WITH RECURSIVE chain AS (
       SELECT resource_id, parent_resource_id, 0 AS depth
         FROM gfs_resources
        WHERE drive = $1 AND resource_id = $2::uuid AND deleted_at IS NULL
       UNION ALL
       SELECT r.resource_id, r.parent_resource_id, c.depth + 1
         FROM gfs_resources r
         JOIN chain c ON r.resource_id = c.parent_resource_id
        WHERE r.drive = $1 AND r.deleted_at IS NULL
     ),
     requested_subjects(subject_type, subject_id) AS (
       SELECT * FROM unnest($3::text[], $4::text[])
     ),
     authority_grants AS (
       SELECT g.subject_type, g.subject_id, g.resource_id, g.permissions, g.inherit
         FROM gfs_grants g
         JOIN requested_subjects s
           ON s.subject_type = g.subject_type AND s.subject_id = g.subject_id
        WHERE g.drive = $1
     ),
     authority_shares AS (
       SELECT s0.subject_type, s0.subject_id, s0.resource_id, s0.permissions,
              s0.include_descendants
         FROM gfs_shares s0
         JOIN requested_subjects s
           ON s.subject_type = s0.subject_type AND s.subject_id = s0.subject_id
        WHERE s0.drive = $1
     )
     SELECT
       COALESCE(
         (SELECT jsonb_agg(c.resource_id ORDER BY c.depth ASC) FROM chain c),
         '[]'::jsonb
       ) AS ancestors,
       COALESCE(
         (SELECT jsonb_agg(jsonb_build_object(
            'subject_type', g.subject_type,
            'subject_id', g.subject_id,
            'resource_id', g.resource_id,
            'permissions', g.permissions,
            'inherit', g.inherit
          )) FROM authority_grants g),
         '[]'::jsonb
       ) AS grants,
       COALESCE(
         (SELECT jsonb_agg(jsonb_build_object(
            'subject_type', s.subject_type,
            'subject_id', s.subject_id,
            'resource_id', s.resource_id,
            'permissions', s.permissions,
            'include_descendants', s.include_descendants
          )) FROM authority_shares s),
         '[]'::jsonb
       ) AS shares`,
    [drive, resourceId, types, ids]
  )
  const row = (result.rows[0] ?? {}) as Record<string, unknown>
  const ancestorList = Array.isArray(row.ancestors) ? row.ancestors.map(String) : []
  const grantRows = Array.isArray(row.grants) ? (row.grants as Record<string, unknown>[]) : []
  const shareRows = Array.isArray(row.shares) ? (row.shares as Record<string, unknown>[]) : []
  return {
    ancestors: new Set(ancestorList),
    grants: grantRows.map(grant => ({
      subjectKey: `${String(grant.subject_type)}:${String(grant.subject_id ?? '')}`,
      resourceId: String(grant.resource_id),
      permissions: (grant.permissions as string[]) ?? [],
      inherit: Boolean(grant.inherit),
    })),
    shares: shareRows.map(share => ({
      subjectKey: `${String(share.subject_type)}:${String(share.subject_id ?? '')}`,
      resourceId: String(share.resource_id),
      permissions: (share.permissions as string[]) ?? [],
      includeDescendants: Boolean(share.include_descendants),
    })),
  }
}

function assertTargetPolicy(
  caller: GfsCaller,
  permissions: readonly GfsPermission[],
  target: GfsSubject,
  opts: { isShare: boolean; allowLegacyRetirement?: boolean }
): void {
  const isLegacyStandaloneSubject =
    target.type === 'host' && target.id === LEGACY_STANDALONE_HOST_SUBJECT_ID
  const isLegacyRetirement = isLegacyStandaloneSubject && opts.allowLegacyRetirement === true

  // The historical fleet-wide subject remains parseable so operators can
  // inventory, migrate, and revoke its stored rows. It must never receive a
  // new grant after the individual-Host cutover — single or bulk. Revocation
  // callers opt in explicitly via allowLegacyRetirement; every create and
  // delegation path remains fail-closed.
  if (isLegacyStandaloneSubject && !isLegacyRetirement) {
    throw new GfsGrantError(403, 'legacy_standalone_subject_reserved')
  }
  // Agent (host) restriction (spec §Delegation): manage_acl/share are never
  // grantable to a host by a folder owner — only the operator can. `share` as a
  // share-grant is for users/teams only, never a host. Caller authority is
  // adjudicated before the per-target permission envelope below.
  const grantsManagerBit = permissions.includes('manage_acl') || permissions.includes('share')
  if (!caller.isOperator && target.type === 'host' && grantsManagerBit) {
    throw new GfsGrantError(403, 'agent_manager_forbidden')
  }
  // HCC-issued first-party Host credentials intentionally carry data-plane
  // authority only. Enforce the same boundary on stored grants before the
  // operator bypass so a future token-policy regression cannot activate a
  // dormant destructive/governance grant. Third-party hosts retain their
  // existing grant compatibility; their runtime token scopes are constrained
  // independently by provisionerScopePolicy. Revocation (the only caller that
  // sets allowLegacyRetirement) is exempt: an over-privileged stored row from
  // before this envelope existed must remain deletable, never locked in.
  if (
    target.type === 'host' &&
    target.id?.startsWith('1st:') &&
    opts.allowLegacyRetirement !== true &&
    permissions.some(permission => !MANAGED_FIRST_PARTY_HOST_PERMISSIONS.has(permission))
  ) {
    throw new GfsGrantError(403, 'managed_agent_permission_forbidden')
  }
  if (opts.isShare && target.type === 'host' && !isLegacyRetirement) {
    throw new GfsGrantError(403, 'share_to_agent_forbidden')
  }
  // A non-operator may not grant/share TO the operator subject — the operator is
  // the intrinsic root of trust, never a delegation target. Without this a user
  // holding manage_acl could write a subject_type='operator' grant row (inert,
  // since operator authority is intrinsic, but it pollutes the store + audit).
  if (!caller.isOperator && target.type === 'operator') {
    throw new GfsGrantError(403, 'operator_grant_forbidden')
  }
}

function assertAuthorityMayGrant(
  snapshot: GrantAuthoritySnapshot | null,
  caller: GfsCaller,
  resourceId: string,
  permissions: readonly GfsPermission[],
  opts: { isShare: boolean }
): void {
  // Operator is the intrinsic root of trust — may grant any bit anywhere.
  if (caller.isOperator) return

  if (!snapshot || snapshot.ancestors.size === 0) {
    throw new GfsGrantError(403, opts.isShare ? 'not_sharer' : 'not_manager')
  }

  // Subtree confinement: the grantor must hold the authority bit on R (or an
  // inheriting ancestor) — `manage_acl` to write a folder grant, `share` to
  // write a URI share (spec §Permission bits). Holding it on R via the inherit
  // rule is exactly "R is within the grantor's subtree".
  const authorityBit: GfsPermission = opts.isShare ? 'share' : 'manage_acl'
  if (!holds(authorityBit, resourceId, snapshot.ancestors, snapshot.grants, snapshot.shares)) {
    throw new GfsGrantError(403, opts.isShare ? 'not_sharer' : 'not_manager')
  }
  // No-escalation: the grantor may only hand out bits it itself holds.
  for (const p of permissions) {
    if (!holds(p, resourceId, snapshot.ancestors, snapshot.grants, snapshot.shares)) {
      throw new GfsGrantError(403, 'escalation_rejected')
    }
  }
}

export async function assertMayGrantBatch(
  db: GrantsDb,
  caller: GfsCaller,
  drive: string,
  resourceId: string,
  permissions: readonly GfsPermission[],
  targets: readonly GfsSubject[],
  opts: { isShare: boolean; allowLegacyRetirement?: boolean }
): Promise<void> {
  for (const target of targets) {
    assertTargetPolicy(caller, permissions, target, opts)
  }
  const snapshot = await loadGrantAuthority(db, caller, drive, resourceId)
  assertAuthorityMayGrant(snapshot, caller, resourceId, permissions, opts)
}

/**
 * Plain access check: does `caller` hold `op` on `resourceId`? (Used by the
 * move/rename write path — P2-S05.) Operator is intrinsic; otherwise the same
 * allow() evaluation as assertMayGrant (own grant on R, or an inheriting
 * ancestor; share on R, or an includeDescendants ancestor). Returns false for a
 * missing resource — the caller decides whether that is 404 or forbidden.
 */
export async function checkAccess(
  db: GrantsDb,
  caller: GfsCaller,
  drive: string,
  resourceId: string,
  op: GfsPermission
): Promise<boolean> {
  if (caller.isOperator) return true
  const ancestorList = await ancestorsOf(db, drive, resourceId)
  if (ancestorList.length === 0) return false
  const ancestors = new Set(ancestorList)
  const [grants, shares] = await Promise.all([
    loadGrants(db, drive, caller.subjects),
    loadShares(db, drive, caller.subjects),
  ])
  return holds(op, resourceId, ancestors, grants, shares)
}

/**
 * All permission bits the caller holds on a resource — the "all bits" answer the
 * affordances panel needs. Loads ancestors/grants/shares ONCE and maps the pure
 * `holds()` over PERMISSIONS in memory (vs calling checkAccess per-bit, which
 * re-runs the same 3 queries N times serially). Same authority engine, 1/N the
 * queries.
 */
export async function heldPermissions(
  db: GrantsDb,
  caller: GfsCaller,
  drive: string,
  resourceId: string
): Promise<GfsPermission[]> {
  if (caller.isOperator) return [...PERMISSIONS]
  const ancestorList = await ancestorsOf(db, drive, resourceId)
  if (ancestorList.length === 0) return []
  const ancestors = new Set(ancestorList)
  const [grants, shares] = await Promise.all([
    loadGrants(db, drive, caller.subjects),
    loadShares(db, drive, caller.subjects),
  ])
  return PERMISSIONS.filter(op => holds(op, resourceId, ancestors, grants, shares))
}

/**
 * Append one INSERT-only audit row. Mirrors gfsc DbAuditSink content hashing;
 * the full prev_hash→row_hash chaining is completed in P4-S02, so prev_hash is
 * left null here (each row still carries a tamper-evident content row_hash).
 */
export async function auditMutation(
  db: GrantsDb,
  params: {
    actorKey: string
    targetKey: string
    op: string
    drive: string
    resourceId: string
    outcome: 'allowed' | 'denied'
    requestId?: string
    sourceIp?: string
    actorOnBehalfOf?: string | null
    desktopUserId?: string
    authoritySource?: 'user-session' | 'linked-admin'
  }
): Promise<string | null> {
  const gfsUri = `gfs://${params.drive}/${params.resourceId}`
  const rowHash = createHash('sha256')
    .update(
      [
        params.targetKey,
        params.op,
        gfsUri,
        params.outcome,
        params.actorOnBehalfOf === undefined ? params.actorKey : (params.actorOnBehalfOf ?? ''),
        params.desktopUserId ?? '',
        params.authoritySource ?? '',
        params.requestId ?? '',
      ].join(' ')
    )
    .digest('hex')
  const result = await db.query(
    `INSERT INTO gfs_audit
       (subject, actor_on_behalf_of, op, gfs_uri, outcome, source_ip, request_id,
        row_hash, desktop_user_id, authority_source)
     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::uuid, $10)
     RETURNING sequence_no::text AS id`,
    [
      params.targetKey,
      params.actorOnBehalfOf === undefined ? params.actorKey : params.actorOnBehalfOf,
      params.op,
      gfsUri,
      params.outcome,
      params.sourceIp ?? null,
      params.requestId ?? null,
      rowHash,
      params.desktopUserId ?? null,
      params.authoritySource ?? null,
    ]
  )
  const row = result.rows[0] as { id?: unknown } | undefined
  return row?.id === null || row?.id === undefined ? null : String(row.id)
}

export function parseSubject(value: unknown): GfsSubject {
  if (typeof value !== 'object' || value === null) {
    throw new GfsGrantError(400, 'subject_invalid')
  }
  const { type, id } = value as { type?: unknown; id?: unknown }
  if (typeof type !== 'string' || !SUBJECT_TYPES.includes(type as GfsSubjectType)) {
    throw new GfsGrantError(400, 'subject_invalid')
  }
  if (type === 'operator') {
    return { type: 'operator' }
  }
  if (typeof id !== 'string' || id.length === 0) {
    throw new GfsGrantError(400, 'subject_invalid')
  }
  // user/team subject ids are real UUIDs (users.id / team_members.team_id); reject
  // anything else so a typo can't persist an inert, never-matching grant row.
  if ((type === 'user' || type === 'team') && !UUID_RE.test(id)) {
    throw new GfsGrantError(400, 'subject_invalid')
  }
  const canonicalId = type === 'user' || type === 'team' ? id.toLowerCase() : id
  // host ids are canonical provisioner principals: 1st/3rd party plus a
  // Kubernetes namespace/name pair. Do not accept free-form host strings here:
  // grants written with a shape the token minter never issues become an inert
  // second source of truth and can mask security-review drift.
  if (type === 'host' && !isValidHostSubjectId(canonicalId)) {
    throw new GfsGrantError(400, 'subject_invalid')
  }
  return { type: type as GfsSubjectType, id: canonicalId }
}

export function assertMutationSubjectTransport(body: Record<string, unknown>): void {
  const hasSubject = Object.prototype.hasOwnProperty.call(body, 'subject')
  const hasSubjects = Object.prototype.hasOwnProperty.call(body, 'subjects')
  if (hasSubject === hasSubjects) {
    throw new GfsGrantError(400, 'subjects_invalid')
  }
}

export function normalizeMutationSubjects(
  body: Record<string, unknown>,
  opts: { isShare: boolean }
): GfsSubject[] {
  assertMutationSubjectTransport(body)
  const hasSubject = Object.prototype.hasOwnProperty.call(body, 'subject')
  if (hasSubject) return [parseSubject(body.subject)]

  if (!Array.isArray(body.subjects) || body.subjects.length < 1 || body.subjects.length > 100) {
    throw new GfsGrantError(400, 'subjects_invalid')
  }

  const normalized: GfsSubject[] = []
  const seen = new Set<string>()
  const invalidIndexes: number[] = []
  for (const [index, value] of body.subjects.entries()) {
    try {
      const subject = parseSubject(value)
      const pluralTypeAllowed = opts.isShare
        ? subject.type === 'user' || subject.type === 'team'
        : subject.type === 'user' || subject.type === 'team' || subject.type === 'host'
      const key = subjectKey(subject)
      if (!pluralTypeAllowed || seen.has(key)) {
        invalidIndexes.push(index)
        continue
      }
      seen.add(key)
      normalized.push(subject)
    } catch (error) {
      if (!(error instanceof GfsGrantError)) throw error
      invalidIndexes.push(index)
    }
  }
  if (invalidIndexes.length > 0) {
    throw new GfsGrantError(400, 'subjects_invalid', invalidIndexes)
  }
  return normalized
}

export function sendGfsGrantError(res: import('express').Response, error: GfsGrantError): void {
  res.status(error.status).json({
    error: error.code,
    message: error.message,
    ...(error.invalidIndexes ? { invalidIndexes: error.invalidIndexes } : {}),
  })
}

export function parsePermissions(value: unknown): GfsPermission[] {
  if (!Array.isArray(value) || value.length === 0) {
    throw new GfsGrantError(400, 'permissions_invalid')
  }
  const perms = value.map(p => {
    if (typeof p !== 'string' || !PERMISSIONS.includes(p as GfsPermission)) {
      throw new GfsGrantError(400, 'permissions_invalid')
    }
    return p as GfsPermission
  })
  return Array.from(new Set(perms))
}

export function driveOf(value: unknown): string {
  return typeof value === 'string' && value.length > 0 ? value : DEFAULT_DRIVE
}

export function permissionReadFilter(req: Request): { drive: string; resourceId: string } {
  const drive = typeof req.query.drive === 'string' ? req.query.drive : ''
  const resourceId = typeof req.query.resourceId === 'string' ? req.query.resourceId : ''
  if (!drive) throw new GfsGrantError(400, 'drive_required')
  if (!UUID_RE.test(resourceId)) throw new GfsGrantError(400, 'resource_invalid')
  return { drive, resourceId }
}

export function requestIdOf(req: Request): string | undefined {
  const id =
    (req as { gfsRequestId?: string; correlationId?: string }).gfsRequestId ??
    (req as { correlationId?: string }).correlationId
  return typeof id === 'string' && id.length > 0 ? id : undefined
}

type GfsPermissionEventOperator = {
  kind: 'control_admin' | 'platform_user'
  sub: string
}

function permissionEventOperator(req: Request, caller: GfsCaller): GfsPermissionEventOperator {
  if (caller.effectiveControlAdminId) {
    return { kind: 'control_admin', sub: caller.effectiveControlAdminId }
  }
  const adminSub = (req as { adminAuth?: { sub?: string } }).adminAuth?.sub
  if (adminSub) return { kind: 'control_admin', sub: adminSub }
  const userId = (req as { externalAuth?: { userId?: string } }).externalAuth?.userId
  if (userId) return { kind: 'platform_user', sub: userId }
  if (caller.actorKey.startsWith('user:') && caller.actorKey.length > 'user:'.length) {
    return { kind: 'platform_user', sub: caller.actorKey.slice('user:'.length) }
  }
  throw new GfsGrantError(401, 'unauthenticated')
}

function permissionEventSubject(subject: GfsSubject): ControlApiPermissionSubject {
  if (subject.type === 'user' && subject.id) return { kind: 'user', id: subject.id }
  if (subject.type === 'team' && subject.id) return { kind: 'team', id: subject.id }
  const principalKind =
    subject.type === 'operator' || subject.type === 'host' || subject.type === 'context'
      ? subject.type
      : 'service'
  return {
    kind: 'service',
    id: subjectKey(subject),
    principalKind,
  }
}

function permissionsDetailRef(permissions: readonly string[]): string {
  return `gfs_permissions/${[...new Set(permissions)].sort().join('.')}`
}

export async function appendGfsPermissionEvent(
  db: DbClient,
  params: {
    req: Request
    caller: GfsCaller
    subject: GfsSubject
    permissions: readonly string[]
    drive: string
    resourceId: string
    mutation: 'grant' | 'share'
    action: 'grant' | 'revoke'
    outcome: 'committed' | 'rejected'
    auditId: string | null
  }
): Promise<void> {
  await appendGfsPermissionEvents(db, {
    ...params,
    subjects: [params.subject],
    auditIds: [params.auditId],
  })
}

export async function appendGfsPermissionEvents(
  db: DbClient,
  params: {
    req: Request
    caller: GfsCaller
    subjects: readonly GfsSubject[]
    permissions: readonly string[]
    drive: string
    resourceId: string
    mutation: 'grant' | 'share'
    action: 'grant' | 'revoke'
    outcome: 'committed' | 'rejected'
    auditIds: readonly (string | null)[]
  }
): Promise<void> {
  const operator = permissionEventOperator(params.req, params.caller)
  await appendControlApiPermissionEventsInTransaction(db, {
    operatorSub: operator.sub,
    operatorKind: operator.kind,
    requestId: requestIdOf(params.req) ?? null,
    changes: params.subjects.map((subject, index) => ({
      action: params.action,
      resourceClass: params.mutation === 'grant' ? 'gfs_folder_grant' : 'gfs_share',
      resourceRef: `gfs://${params.drive}/${params.resourceId}`,
      subject: permissionEventSubject(subject),
      sourceAuditRef: params.auditIds[index] ? `gfs_audit:${params.auditIds[index]}` : null,
      status:
        params.outcome === 'rejected'
          ? `${params.mutation}_${params.action}_rejected`
          : `${params.mutation}_${params.action === 'grant' ? 'configured' : 'revoked'}`,
      detailRef: permissionsDetailRef(params.permissions),
      count: new Set(params.permissions).size,
      outcome: params.outcome,
      authorizationDecision: params.outcome === 'rejected' ? 'deny' : 'allow',
    })),
  })
}

export async function writeGfsGrantBatchInTransaction(
  db: DbClient,
  params: {
    req: Request
    caller: GfsCaller
    drive: string
    resourceId: string
    subjects: readonly GfsSubject[]
    permissions: readonly GfsPermission[]
    inherit: boolean
  }
): Promise<{ error: GfsGrantError | null }> {
  const auditIds: Array<string | null> = []
  let outcome: 'allowed' | 'denied' = 'allowed'
  let policyError: GfsGrantError | null = null
  try {
    await assertMayGrantBatch(
      db,
      params.caller,
      params.drive,
      params.resourceId,
      params.permissions,
      params.subjects,
      { isShare: false }
    )
  } catch (error) {
    if (!(error instanceof GfsGrantError)) throw error
    outcome = 'denied'
    policyError = error
  }

  if (!policyError) {
    const types = params.subjects.map(subject => subject.type)
    const ids = params.subjects.map(subject => subject.id ?? '')
    await db.query(
      `INSERT INTO gfs_grants
         (drive, resource_id, subject_type, subject_id, permissions, inherit, granted_by)
       SELECT $1, $2::uuid, input.subject_type, input.subject_id, $5::text[], $6, $7
         FROM unnest($3::text[], $4::text[]) AS input(subject_type, subject_id)
       ON CONFLICT (drive, resource_id, subject_type, subject_id)
       DO UPDATE SET permissions = EXCLUDED.permissions, inherit = EXCLUDED.inherit,
                     granted_by = EXCLUDED.granted_by, updated_at = now()`,
      [
        params.drive,
        params.resourceId,
        types,
        ids,
        params.permissions,
        params.inherit,
        params.caller.actorKey,
      ]
    )
  }

  for (const subject of params.subjects) {
    auditIds.push(
      await auditMutation(db, {
        actorKey: params.caller.actorKey,
        ...callerAuditFields(params.caller),
        targetKey: subjectKey(subject),
        op: `grant.put[${params.permissions.join(',')}]`,
        drive: params.drive,
        resourceId: params.resourceId,
        outcome,
        requestId: requestIdOf(params.req),
        sourceIp: params.req.ip,
      })
    )
  }
  await appendGfsPermissionEvents(db, {
    req: params.req,
    caller: params.caller,
    subjects: params.subjects,
    permissions: params.permissions,
    drive: params.drive,
    resourceId: params.resourceId,
    mutation: 'grant',
    action: 'grant',
    outcome: policyError ? 'rejected' : 'committed',
    auditIds,
  })
  return { error: policyError }
}

export function registerGfsGrantRoutes(router: Router): void {
  // Operator (Control UI) seeds Layer-1/2 folder grants. The no-escalation
  // engine (assertMayGrant) is caller-agnostic; the Profile/Desktop folder-owner
  // delegation surface (external user session) wires onto it when that UI lands.
  // Per-admin token bucket, same shape as the admin registry surfaces; auth runs
  // first, so adminAuth.sub is always present by the time the limiter keys.
  const grantsRateLimit = rateLimitMiddleware({
    bucketType: 'gfs_grants',
    maxPerMinute: config.adminGfsGrantsPerMin,
    getBucketKey: req => {
      const sub = (req as { adminAuth?: { sub?: string } }).adminAuth?.sub
      return sub ? `gfsgrants:${sub}` : null
    },
    onBackendUnavailable: 'process-memory',
  })
  router.get('/gfs/grants', requireAuthForControlUI, grantsRateLimit, asyncHandler(handleGrantRead))
  router.put(
    '/gfs/grants',
    requireAuthForControlUI,
    grantsRateLimit,
    asyncHandler(handleGrantWrite)
  )
  router.delete(
    '/gfs/grants/:id',
    requireAuthForControlUI,
    grantsRateLimit,
    asyncHandler(handleGrantDelete)
  )
}

export interface GfsGrantListItem {
  id: string
  drive: string
  resourceId: string
  subject: { type: string; id?: string }
  permissions: string[]
  inherit: boolean
}

/** One resource's grant rows in the canonical list shape (`id` powers revoke). */
export async function queryGrantItems(
  drive: string,
  resourceId: string
): Promise<GfsGrantListItem[]> {
  const result = await pool.query(
    `SELECT id, drive, resource_id, subject_type, subject_id, permissions, inherit
       FROM gfs_grants
      WHERE drive = $1 AND resource_id = $2::uuid
      ORDER BY created_at ASC, id ASC`,
    [drive, resourceId]
  )
  return (result.rows as Record<string, unknown>[]).map(row => {
    const subjectId = String(row.subject_id ?? '')
    return {
      id: String(row.id),
      drive: String(row.drive),
      resourceId: String(row.resource_id),
      subject: {
        type: String(row.subject_type),
        ...(subjectId ? { id: subjectId } : {}),
      },
      permissions: Array.isArray(row.permissions) ? row.permissions.map(String) : [],
      inherit: Boolean(row.inherit),
    }
  })
}

export async function handleGrantRead(
  req: Request,
  res: import('express').Response
): Promise<void> {
  try {
    const { drive, resourceId } = permissionReadFilter(req)
    res.status(200).json({ items: await queryGrantItems(drive, resourceId) })
  } catch (err) {
    if (err instanceof GfsGrantError) {
      sendGfsGrantError(res, err)
      return
    }
    throw err
  }
}

/**
 * Non-operator grants listing for the external (folder-owner) plane. The ACL of
 * a resource is delegation metadata naming third-party subjects, so viewing it
 * requires the same authority as changing it: `manage_acl` on the resource,
 * held directly or through an inheriting ancestor (view-ACL = manage-ACL).
 * A missing resource yields the same 403 — no existence oracle.
 */
export async function handleGrantListForCaller(
  req: Request,
  res: import('express').Response
): Promise<void> {
  try {
    const caller = resolveCaller(req)
    const { drive, resourceId } = permissionReadFilter(req)
    if (!caller.isOperator) {
      const held = await heldPermissions(pool, caller, drive, resourceId)
      if (!held.includes('manage_acl')) {
        throw new GfsGrantError(403, 'manage_acl_required')
      }
    }
    res.status(200).json({ items: await queryGrantItems(drive, resourceId) })
  } catch (err) {
    if (err instanceof GfsGrantError) {
      sendGfsGrantError(res, err)
      return
    }
    throw err
  }
}

export async function handleGrantWrite(
  req: Request,
  res: import('express').Response
): Promise<void> {
  try {
    const caller = resolveCaller(req)
    const body = (req.body ?? {}) as Record<string, unknown>
    const drive = driveOf(body.drive)
    const resourceId = String(body.resourceId ?? '')
    assertMutationSubjectTransport(body)
    if (!UUID_RE.test(resourceId)) {
      throw new GfsGrantError(400, 'resource_invalid')
    }
    const subjects = normalizeMutationSubjects(body, { isShare: false })
    const permissions = parsePermissions(body.permissions)
    const inherit = Boolean(body.inherit)
    const result = await withTransaction(db =>
      writeGfsGrantBatchInTransaction(db, {
        req,
        caller,
        drive,
        resourceId,
        subjects,
        permissions,
        inherit,
      })
    )
    if (result.error) {
      sendGfsGrantError(res, result.error)
      return
    }
    res.status(200).json({ ok: true, resourceId, updated: subjects, count: subjects.length })
  } catch (err) {
    if (err instanceof GfsGrantError) {
      sendGfsGrantError(res, err)
      return
    }
    throw err
  }
}

export async function handleGrantDelete(
  req: Request,
  res: import('express').Response
): Promise<void> {
  try {
    const caller = resolveCaller(req)
    const id = String(req.params.id)
    if (!UUID_RE.test(id)) {
      res.status(400).json({ error: 'grant_invalid' })
      return
    }
    const result = await withTransaction(async db => {
      const existing = await db.query(
        `SELECT drive, resource_id, subject_type, subject_id, permissions
           FROM gfs_grants WHERE id = $1::uuid
           FOR UPDATE`,
        [id]
      )
      if (existing.rows.length === 0) {
        return caller.isOperator ? { kind: 'not_found' as const } : { kind: 'hidden' as const }
      }
      const row = existing.rows[0] as {
        drive: string
        resource_id: string
        subject_type: string
        subject_id: string
        permissions: string[]
      }
      const subject = {
        type: row.subject_type as GfsSubjectType,
        id: row.subject_id || undefined,
      }
      // Revoking uses the same no-escalation gate as granting. A lower authority
      // cannot remove access that was seeded with permissions it does not hold.
      try {
        await assertMayGrant(
          db,
          caller,
          row.drive,
          String(row.resource_id),
          (row.permissions as GfsPermission[]) ?? ['manage_acl'],
          subject,
          { isShare: false, allowLegacyRetirement: true }
        )
      } catch (error) {
        if (!(error instanceof GfsGrantError)) throw error
        const auditId = await auditMutation(db, {
          actorKey: caller.actorKey,
          ...callerAuditFields(caller),
          targetKey: subjectKey(subject),
          op: 'grant.delete',
          drive: row.drive,
          resourceId: String(row.resource_id),
          outcome: 'denied',
          requestId: requestIdOf(req),
          sourceIp: req.ip,
        })
        await appendGfsPermissionEvent(db, {
          req,
          caller,
          subject,
          permissions: row.permissions,
          drive: row.drive,
          resourceId: String(row.resource_id),
          mutation: 'grant',
          action: 'revoke',
          outcome: 'rejected',
          auditId,
        })
        return { kind: 'denied' as const, error }
      }
      await db.query(`DELETE FROM gfs_grants WHERE id = $1::uuid`, [id])
      const auditId = await auditMutation(db, {
        actorKey: caller.actorKey,
        ...callerAuditFields(caller),
        targetKey: subjectKey(subject),
        op: 'grant.delete',
        drive: row.drive,
        resourceId: String(row.resource_id),
        outcome: 'allowed',
        requestId: requestIdOf(req),
        sourceIp: req.ip,
      })
      await appendGfsPermissionEvent(db, {
        req,
        caller,
        subject,
        permissions: row.permissions,
        drive: row.drive,
        resourceId: String(row.resource_id),
        mutation: 'grant',
        action: 'revoke',
        outcome: 'committed',
        auditId,
      })
      return { kind: 'ok' as const }
    })
    if (result.kind === 'not_found') {
      res.status(404).json({ error: 'grant_not_found' })
      return
    }
    if (result.kind === 'hidden') {
      res.status(403).json({ error: 'forbidden' })
      return
    }
    if (result.kind === 'denied') {
      res.status(result.error.status).json({ error: result.error.code })
      return
    }
    res.status(200).json({ ok: true })
  } catch (err) {
    if (err instanceof GfsGrantError) {
      res.status(err.status).json({ error: err.code })
      return
    }
    throw err
  }
}