singularity-forge/docs/SECURITY.md

# Security

## Auth Model and Trust Boundaries

SF never manages Anthropic OAuth directly. The safe paths are:

- **API key** — user sets `ANTHROPIC_API_KEY` or configures it in auth.json. SF reads it; never generates or exchanges it.
- **Cloud providers** — Bedrock, Vertex, Azure via their own credential chains.
- **Explicit local runtime adapters** — only when intentionally configured, SF may delegate to a local provider/runtime adapter. SF does not mint, replay, or reuse subscription credentials.

**Prohibited patterns:**
- SF-managed Anthropic OAuth flow for subscription accounts
- Reusing user Claude subscription credentials inside SF's own API client
- Making a provider believe requests come from a different first-party client than the one actually making them

## Write Gate

`src/resources/extensions/sf/bootstrap/write-gate.ts` enforces a phase-aware write boundary:

- During **queue mode** (pre-dispatch planning): only `.sf/` writes and read-only tool calls are permitted. All other file writes are blocked.
- **QUEUE_SAFE_TOOLS** allowlist: `read`, `grep`, `find`, `ls`, `ask_user_questions`, planning tools, web research tools.
- **BASH_READ_ONLY_RE**: regex allowlist of commands safe to run during write-restricted phases (`cat`, `git log`, `npm run test|lint|typecheck`, `jq`, etc.).
- Write-gate violations are logged and surfaced to the user; they do not crash the session.

## Protected Files

The following files require human review before any automated modification (per `docs/SPEC_FIRST_TDD.md`):

- `ADR-*.md` — architecture decision records
- `SPEC.md`, `ARCHITECTURE.md`, `AGENTS.md`
- `docs/SECURITY.md`, `docs/RELIABILITY.md`

SF will not autonomously overwrite these. Any proposed change to a protected file is surfaced as a diff for human acceptance.

## Secret Scanning

Pre-commit hook via `npm run secret-scan:install-hook`. Blocks commits containing patterns matching API keys, tokens, and credentials. Install with:

```bash
npm run secret-scan:install-hook
```

## Dependency Risk

- `npm audit` runs in CI on every push.
- No `--ignore-scripts` bypass: postinstall scripts are reviewed before adding new dependencies.
- Rust N-API bindings (`packages/native/`) undergo separate native-build review for ABI safety.

## Sandbox Model

SF agents execute inside the Pi RPC child process. The write gate and tool allowlist are the primary sandbox. There is no OS-level sandbox (no container or seccomp) in the default local deployment.

**Headless unsupervised mode** (`--no-supervised`): SF exits with code 10 (blocked) rather than auto-responding to any interactive tool call. This is the safe default for CI pipelines where no human is available to respond.