Cursor

mkdir -p ~/.truefoundry && umask 077 && cat > ~/.truefoundry/cursor-hooks.env <<'EOF'
TFY_API_KEY=your-truefoundry-api-key
TFY_GATEWAY_URL=https://<your-gateway-host>
EOF

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.truefoundry" | Out-Null
Set-Content -Path "$env:USERPROFILE\.truefoundry\cursor-hooks.env" -Encoding ascii -Value @(
  'TFY_API_KEY=your-truefoundry-api-key'
  'TFY_GATEWAY_URL=https://<your-gateway-host>'
)
icacls "$env:USERPROFILE\.truefoundry\cursor-hooks.env" /inheritance:r /grant:r "${env:USERNAME}:(F)" | Out-Null

#!/usr/bin/env bash
# TrueFoundry AI Gateway guardrails for Cursor.
# Cursor cannot call a URL directly, so this script forwards the action to the gateway and prints
# the reply unchanged - the gateway already replies in the format Cursor expects.
#
# Guardrails are passed as arguments, one name per argument, so each action uses its own:
#   "beforeSubmitPrompt": [{ "command": "./hooks/tfy-guardrails.sh security/prompt-pii" }]
set -uo pipefail

CONFIG_FILE="${TFY_HOOK_CONFIG:-$HOME/.truefoundry/cursor-hooks.env}"

PAYLOAD="$(cat)"

# Cursor is launched from the desktop and does NOT see your terminal environment, so settings come
# from a config file. Read it every time: reading it only when the key is missing would leave the
# URL unset for anyone who already exports TFY_API_KEY. Values already in the environment still
# win, so capture them before reading the file.
ENV_API_KEY="${TFY_API_KEY:-}"
ENV_GATEWAY_URL="${TFY_GATEWAY_URL:-}"
ENV_LOG_FILE="${TFY_HOOK_LOG:-}"

if [[ -r "$CONFIG_FILE" ]]; then
  # shellcheck source=/dev/null
  source "$CONFIG_FILE"
fi

API_KEY="${ENV_API_KEY:-${TFY_API_KEY:-}}"
GATEWAY_URL="${ENV_GATEWAY_URL:-${TFY_GATEWAY_URL:-}}"
LOG_FILE="${ENV_LOG_FILE:-${TFY_HOOK_LOG:-}}"

# Exit code 2 is how Cursor is told to stop the action. Using it for our own failures means a
# broken setup reliably stops the action instead of depending on failClosed in hooks.json.
fail() {
  printf 'tfy-guardrails: %s\n' "$1" >&2
  exit 2
}

[[ -n "$API_KEY" ]] || fail "TFY_API_KEY not set; add it to $CONFIG_FILE or export it"
[[ -n "$GATEWAY_URL" ]] || fail "TFY_GATEWAY_URL not set; add it to $CONFIG_FILE or export it"

# Build the guardrail header from the arguments. Sending none would let the action through
# unchecked, and the reply would look exactly like a clean pass - stop the action instead.
GUARDRAILS=''
for fqn in "$@"; do
  [[ "$fqn" =~ ^[A-Za-z0-9._/-]+$ ]] || fail "invalid guardrail name: $fqn"
  GUARDRAILS+="${GUARDRAILS:+,}\"$fqn\""
done
[[ -n "$GUARDRAILS" ]] || fail "no guardrails listed for this action in hooks.json"
GUARDRAILS="[$GUARDRAILS]"

# --max-time stays under the hooks.json timeout so a slow gateway produces this clean stop rather
# than Cursor killing the script. --fail-with-body treats any non-2xx reply as a failure: a
# guardrail decision always comes back as 200, so a 4xx/5xx means nothing was ever checked.
RESPONSE="$(printf '%s' "$PAYLOAD" | curl -sS --max-time 20 --fail-with-body \
  -X POST "$GATEWAY_URL/hooks/cursor" \
  -H "x-tfy-api-key: $API_KEY" \
  -H 'content-type: application/json' \
  -H "x-tfy-hook-guardrails: $GUARDRAILS" \
  --data-binary @-)" || fail "gateway error or unreachable at $GATEWAY_URL: ${RESPONSE:-no response}"

# An empty reply is not valid hook output; stop the action rather than leaving it to failClosed.
[[ -n "$RESPONSE" ]] || fail "empty response from $GATEWAY_URL"

if [[ -n "$LOG_FILE" ]]; then
  {
    printf '>>> %s\n' "$PAYLOAD"
    printf '=== guardrails %s\n' "$GUARDRAILS"
    printf '<<< %s\n\n' "$RESPONSE"
  } >>"$LOG_FILE"
fi

printf '%s' "$RESPONSE"

# TrueFoundry AI Gateway guardrails for Cursor.
# Cursor cannot call a URL directly, so this script forwards the action to the gateway and prints
# the reply unchanged - the gateway already replies in the format Cursor expects.
#
# Guardrails are passed as arguments, one name per argument, so each action uses its own:
#   "beforeSubmitPrompt": [{ "command": "powershell -NoProfile -ExecutionPolicy Bypass -File ./hooks/tfy-guardrails.ps1 security/prompt-pii" }]
$ErrorActionPreference = 'Stop'

# Exit code 2 is how Cursor is told to stop the action. Using it for our own failures means a
# broken setup reliably stops the action instead of depending on failClosed in hooks.json.
function Deny($message) {
  [Console]::Error.WriteLine("tfy-guardrails: $message")
  exit 2
}
trap { Deny $_.Exception.Message }

$configFile = if ($env:TFY_HOOK_CONFIG) { $env:TFY_HOOK_CONFIG }
              else { Join-Path $env:USERPROFILE '.truefoundry\cursor-hooks.env' }

$payload = [Console]::In.ReadToEnd()

# Cursor is launched from the desktop and does NOT see your terminal environment, so settings come
# from a config file. Anything already in the environment wins, so read that first.
$apiKey     = $env:TFY_API_KEY
$gatewayUrl = $env:TFY_GATEWAY_URL
$logFile    = $env:TFY_HOOK_LOG

if (Test-Path -LiteralPath $configFile) {
  foreach ($line in Get-Content -LiteralPath $configFile) {
    if ($line -match '^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$') {
      $name  = $Matches[1]
      $value = $Matches[2].Trim().Trim('"').Trim("'")
      if ($name -eq 'TFY_API_KEY'     -and -not $apiKey)     { $apiKey     = $value }
      if ($name -eq 'TFY_GATEWAY_URL' -and -not $gatewayUrl) { $gatewayUrl = $value }
      if ($name -eq 'TFY_HOOK_LOG'    -and -not $logFile)    { $logFile    = $value }
    }
  }
}

if (-not $apiKey)     { Deny "TFY_API_KEY not set; add it to $configFile" }
if (-not $gatewayUrl) { Deny "TFY_GATEWAY_URL not set; add it to $configFile" }

# Build the guardrail header from the arguments. Sending none would let the action through
# unchecked, and the reply would look exactly like a clean pass - stop the action instead.
$names = @($args)
foreach ($name in $names) {
  if ($name -notmatch '^[A-Za-z0-9._/-]+$') { Deny "invalid guardrail name: $name" }
}
if ($names.Count -eq 0) { Deny 'no guardrails listed for this action in hooks.json' }
$guardrails = '[' + (($names | ForEach-Object { '"' + $_ + '"' }) -join ',') + ']'

# Any non-2xx reply throws and is treated as a failure: a guardrail decision always comes back as
# 200, so a 4xx/5xx means nothing was ever checked. The timeout stays under the hooks.json timeout
# so a slow gateway produces this clean stop rather than Cursor killing the script.
try {
  $response = Invoke-WebRequest -Uri "$gatewayUrl/hooks/cursor" -Method Post -UseBasicParsing `
    -TimeoutSec 20 -ContentType 'application/json' `
    -Headers @{ 'x-tfy-api-key' = $apiKey; 'x-tfy-hook-guardrails' = $guardrails } `
    -Body ([Text.Encoding]::UTF8.GetBytes($payload))
} catch {
  Deny "gateway error or unreachable at $gatewayUrl - $($_.Exception.Message)"
}

$body = $response.Content
# An empty reply is not valid hook output; stop the action rather than leaving it to failClosed.
if ([string]::IsNullOrWhiteSpace($body)) { Deny "empty response from $gatewayUrl" }

if ($logFile) {
  Add-Content -LiteralPath $logFile -Value ">>> $payload", "=== guardrails $guardrails", "<<< $body", ''
}

[Console]::Out.Write($body)

{
  "version": 1,
  "hooks": {
    "beforeSubmitPrompt": [
      { "command": "./hooks/tfy-guardrails.sh security/guardrail1", "timeout": 30, "failClosed": true }
    ],
    "beforeReadFile": [
      { "command": "./hooks/tfy-guardrails.sh security/guardrail2", "timeout": 30, "failClosed": true }
    ],
    "beforeTabFileRead": [
      { "command": "./hooks/tfy-guardrails.sh security/guardrail3", "timeout": 30, "failClosed": true }
    ],
    "subagentStart": [
      { "command": "./hooks/tfy-guardrails.sh security/guardrail4", "timeout": 30, "failClosed": true }
    ],
    "beforeShellExecution": [
      { "command": "./hooks/tfy-guardrails.sh security/guardrail5", "timeout": 30, "failClosed": true }
    ],
    "preToolUse": [
      { "command": "./hooks/tfy-guardrails.sh security/guardrail6", "timeout": 30, "failClosed": true }
    ],
    "postToolUse": [
      { "command": "./hooks/tfy-guardrails.sh security/guardrail7", "timeout": 30, "failClosed": true }
    ]
  }
}

{
  "version": 1,
  "hooks": {
    "beforeSubmitPrompt": [
      { "command": "powershell -NoProfile -ExecutionPolicy Bypass -File ./hooks/tfy-guardrails.ps1 security/guardrail1", "timeout": 30, "failClosed": true }
    ],
    "beforeReadFile": [
      { "command": "powershell -NoProfile -ExecutionPolicy Bypass -File ./hooks/tfy-guardrails.ps1 security/guardrail2", "timeout": 30, "failClosed": true }
    ],
    "beforeTabFileRead": [
      { "command": "powershell -NoProfile -ExecutionPolicy Bypass -File ./hooks/tfy-guardrails.ps1 security/guardrail3", "timeout": 30, "failClosed": true }
    ],
    "subagentStart": [
      { "command": "powershell -NoProfile -ExecutionPolicy Bypass -File ./hooks/tfy-guardrails.ps1 security/guardrail4", "timeout": 30, "failClosed": true }
    ],
    "beforeShellExecution": [
      { "command": "powershell -NoProfile -ExecutionPolicy Bypass -File ./hooks/tfy-guardrails.ps1 security/guardrail5", "timeout": 30, "failClosed": true }
    ],
    "preToolUse": [
      { "command": "powershell -NoProfile -ExecutionPolicy Bypass -File ./hooks/tfy-guardrails.ps1 security/guardrail6", "timeout": 30, "failClosed": true }
    ],
    "postToolUse": [
      { "command": "powershell -NoProfile -ExecutionPolicy Bypass -File ./hooks/tfy-guardrails.ps1 security/guardrail7", "timeout": 30, "failClosed": true }
    ]
  }
}

echo '{"hook_event_name":"beforeReadFile","file_path":"/tmp/x","content":"reach me at a@b.com"}' \
  | ~/.cursor/hooks/tfy-guardrails.sh security/email-regex; echo " exit=$?"

'{"hook_event_name":"beforeReadFile","file_path":"C:/tmp/x","content":"reach me at a@b.com"}' |
  powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\.cursor\hooks\tfy-guardrails.ps1" security/email-regex
"exit=$LASTEXITCODE"