# Prompt Guard

Prompt Guard is a local, deterministic preflight for terminal prompts. It finds
high-confidence credentials and personal identifiers, replaces them before a
prompt is sent, and can write a metadata-only JSONL receipt.

It does not send text to a model or cloud service. Findings contain category,
severity, and character offsets, but never the matched value. Receipts hash only
the already-redacted output.

## Install

Install the `prompt-guard` launcher into the user's existing `bin` directory:

```powershell
.\scripts\install-prompt-guard.ps1
```

After installation, `prompt-guard` is available from any terminal already using
`%USERPROFILE%\bin` in `PATH`.

## PowerShell

Redact the current clipboard and replace it with the safe result:

```powershell
.\scripts\prompt-guard.ps1 -Clipboard
```

Redact piped text:

```powershell
Get-Content .\prompt.txt -Raw | .\scripts\prompt-guard.ps1
```

Check without returning the prompt. Exit code `2` means protected data was
found:

```powershell
Get-Content .\prompt.txt -Raw | .\scripts\prompt-guard.ps1 -Check
```

Write an optional metadata-only receipt:

```powershell
.\scripts\prompt-guard.ps1 -Clipboard -ReceiptPath .\artifacts\prompt-guard.jsonl
```

The Node CLI accepts stdin or `--file`. It intentionally does not accept prompt
text as a command-line argument because process arguments can be logged:

```powershell
Get-Clipboard | node .\scripts\prompt-guard.js
node .\scripts\prompt-guard.js --check --file .\prompt.txt
```

Send the redacted prompt directly to a one-shot CLI. Place Prompt Guard options
before `--exec`; everything after the executable is passed to that program:

```powershell
Get-Clipboard | node .\scripts\prompt-guard.js --exec ollama run clay
Get-Content .\prompt.txt -Raw |
  .\scripts\prompt-guard.ps1 -Executable codex -CommandArguments @("exec", "-")
```

## Terminal Boundary

The AetherDesk terminal uses the same core scanner:

- Severity 8-10 findings, including API keys, passwords, private keys, payment
  cards, Social Security numbers, and labeled student IDs, are blocked before
  execution.
- Lower-severity PII is removed from terminal history, command records,
  governance input, and command echo. The original command is still sent to the
  local shell so redaction does not silently change command behavior.
- To intentionally use protected data, put it in an environment variable and
  reference the variable instead of typing the literal value.

This protects the AetherDesk terminal and prompts passed through the wrapper. It
cannot intercept arbitrary native terminals or third-party interactive CLIs
that bypass those entry points.

## Local Model Boundary

`POST /api/ai/chat` applies Prompt Guard after the complete model prompt is
assembled and immediately before the request reaches Ollama. This includes both
the user's request and the attached terminal tail. Protected values are replaced
with typed placeholders, and the response contains only a metadata summary in
`prompt_guard`.

OpenClaw terminal packets apply the same policy before reflecting an operator
prompt in packet responses.

## Gate

Run the focused gate:

```powershell
node .\scripts\prompt-guard-check.js
```

The existing lint and pre-push gate now runs it automatically:

```powershell
npm run lint:check
npm run prepush:check
```
