npm package: @squadzero/veil
Description: A TypeScript library for selective context access, visibility control & safety enforcement for LLMs
Latest version: 0.6.4

# Veil 🎭

**LLM visibility firewall** - Control what AI can access in your project.

[![npm](https://img.shields.io/npm/v/@squadzero/veil.svg)](https://www.npmjs.com/package/@squadzero/veil)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.6+-blue.svg)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## What It Does

- 🛡️ **Block dangerous commands** - Prevent `rm -rf /`, `wrangler deploy`, etc.
- 🔒 **Protect secrets** - Mask or deny access to API keys and tokens
- 📁 **Hide sensitive files** - Block reading/writing `.env`, `secrets/`, etc.
- 📝 **Audit logging** - Track all AI command attempts for review
- 💡 **Guide the AI** - Provide safe alternatives when blocking

---

## Quick Start

### 1. Install

```bash
npm install -g @squadzero/veil
veil install
source ~/.zshrc
```

### 2. Add VS Code Settings

```json
{
  "terminal.integrated.env.linux": { "VEIL_ENABLED": "1" },
  "terminal.integrated.env.osx": { "VEIL_ENABLED": "1" }
}
```

### 3. Create Rules

```typescript
// veil.config.ts
export default {
  cliRules: [
    {
      match: /^wrangler\s+deploy/,
      action: 'deny',
      reason: 'Use npm run deploy:stage instead',
      safeAlternatives: ['npm run deploy:stage']
    }
  ]
};
```

### 4. Test It

```bash
# Human terminal (outside VS Code) - passes through
wrangler deploy  # ✅ Works

# AI terminal (in VS Code) - blocked
wrangler deploy  # 🛡️ Blocked with alternatives
```

---

## MCP Integration

Add to `.vscode/mcp.json` for AI tool call interception:

```json
{
  "servers": {
    "veil": {
      "type": "stdio",
      "command": "npx",
      "args": ["@squadzero/veil", "mcp"],
      "cwd": "/path/to/workspace"
    }
  }
}
```

### Dynamic Config Loading

Veil automatically loads project-specific rules based on the working directory:

- When `cwd` is passed to a tool, Veil walks up from that directory to find `veil.config.ts`
- For file operations, rules are loaded from the file's parent directory
- Each project in a poly-repo can have its own `veil.config.ts`

```
/workspace
├── .vscode/mcp.json          # Single MCP config
├── project-a/
│   └── veil.config.ts        # Rules for project-a
└── project-b/
    └── veil.config.ts        # Rules for project-b
```

### MCP Tools

| Tool            | Description                           |
| --------------- | ------------------------------------- |
| `run_command`   | Execute commands with Veil validation |
| `check_command` | Pre-flight check without executing    |
| `get_env`       | Get env vars with masking/blocking    |
| `check_env`     | Check if env var is accessible        |
| `check_file`    | Check if file access is allowed       |
| `read_file`     | Read files with Veil validation       |
| `write_file`    | Write files with Veil validation      |
| `get_audit_log` | View audit trail of all operations    |

Most tools accept an optional `cwd` parameter to specify which project's rules to use.

### Audit Logging

Set environment variables to configure audit logging:

```bash
VEIL_AUDIT_LOG=.veil/audit.log  # Log file path (default)
VEIL_AUDIT_FORMAT=text          # 'text' or 'json'
```

---

## CLI Commands

| Command                | Description                            |
| ---------------------- | -------------------------------------- |
| `veil install`         | Add shell wrapper (AI-only by default) |
| `veil install --force` | Protect ALL terminals                  |
| `veil uninstall`       | Remove shell wrapper                   |
| `veil init`            | Create config with preset              |
| `veil check <target>`  | Test if something is blocked           |
| `veil mcp`             | Start MCP server                       |

---

## Documentation

| Guide                                          | Description                        |
| ---------------------------------------------- | ---------------------------------- |
| [Setup Guide](./docs/setup-guide.md)           | Complete installation instructions |
| [CLI Reference](./docs/cli-reference.md)       | All commands and options           |
| [API Reference](./docs/api-reference.md)       | TypeScript API docs                |
| [Presets & Rules](./docs/presets-and-rules.md) | Rule configuration                 |

---

## How It Works

```
Human Terminal          VS Code Terminal (AI)
      │                        │
      ▼                        ▼
  wrangler deploy         wrangler deploy
      │                        │
      │                  VEIL_ENABLED=1
      │                        │
      ▼                        ▼
  ✅ Executes            🛡️ veil-wrap
                               │
                               ▼
                         veil.config.ts
                               │
                    ┌──────────┴──────────┐
                    │                     │
                    ▼                     ▼
               ✅ Allowed            ❌ Blocked
                    │                     │
                    ▼                     ▼
                Executes         Shows alternatives
```

---

## License

MIT © [Squad-Zero](https://github.com/Squad-Zero)