# Security Policy
## Reporting a Vulnerability
If you discover a security vulnerability in tokensave, please report it responsibly:
- **Email:** enzinol@gmail.com
- **GitHub:** Open a [private security advisory](https://github.com/aovestdipaperino/tokensave/security/advisories/new)
Please do **not** open a public issue for security vulnerabilities. We aim to acknowledge reports within 48 hours and provide a fix or mitigation plan within 7 days.
## Supported Versions
| 3.4.x | Yes |
| 4.x-beta | Best-effort |
| < 3.4 | No |
## Security Model
### What tokensave stores
tokensave builds a **local** code graph stored in a SQLite database (`.tokensave/tokensave.db`) inside your project directory. The database contains:
- Symbol names, signatures, and docstrings
- File paths, sizes, and content hashes
- Call relationships and dependency edges
- FTS5 search index
It does **not** store raw source code. The database is local-only — there is no cloud sync, remote database, or server-side storage.
A second database (`~/.tokensave/global.db`) tracks which projects have been indexed, aggregate token-saved counts, and cost accounting data parsed from Claude Code session transcripts. It contains directory paths, counters, per-turn cost/token/category records, and JSONL parse offsets. No source code or conversation content is stored.
### Network access
tokensave makes **no inbound network connections**. It never binds a port or listens for traffic. The MCP server communicates exclusively over stdio.
Outbound connections are limited to:
| `api.github.com` | Check for new releases | None (public API) | Silently ignored |
| `github.com` | Download binary during `tokensave upgrade` | None (public releases) | Error shown to user |
| `tokensave-counter.enzinol.workers.dev` | Aggregate token-saved counter | None | Silently ignored |
| `raw.githubusercontent.com` | Fetch model pricing from [LiteLLM](https://github.com/BerriAI/litellm) | None (public file) | Falls back to embedded pricing |
All best-effort network calls use short timeouts (1-5 seconds) and never block the CLI or MCP server. The pricing fetch (5s timeout) only runs during `tokensave cost` and is cached for 24 hours at `~/.tokensave/pricing.json`.
### No credentials or secrets
tokensave does not require, store, or transmit any credentials, API keys, tokens, or passwords. All external API calls target public, unauthenticated endpoints.
### MCP server (read-only)
All 37 MCP tools are **read-only** analysis and query operations (marked `readOnlyHint: true`). The MCP server cannot:
- Modify, create, or delete files
- Execute shell commands or user-supplied code
- Access the network on behalf of the AI agent
### Self-update integrity
`tokensave upgrade` downloads pre-built binaries from [GitHub Releases](https://github.com/aovestdipaperino/tokensave/releases). The upgrade process:
- Stops the daemon before replacing the binary
- Downloads from the same release channel (stable/beta) currently installed
- Restarts the daemon after a successful upgrade
**Limitation:** Release artifacts are not currently signed with a cryptographic signature. The integrity guarantee relies on HTTPS transport security and GitHub's release infrastructure.
### Daemon privileges
The background daemon (`tokensave daemon`) runs with **standard user privileges**. It only watches project directories for file changes and triggers incremental syncs.
On Windows, installing the daemon as an autostart service requires a one-time UAC elevation prompt. The elevated operation is limited to service registration — the daemon itself runs as the current user.
### Unsafe code
The codebase contains minimal `unsafe` blocks, limited to Windows API calls for:
- Checking whether the process is running elevated (`OpenProcessToken`, `GetTokenInformation`)
- Launching an elevated process for service installation (`ShellExecuteExW`)
No unsafe code is used on macOS or Linux.
## Best Practices
- Add `.tokensave/` to your `.gitignore` to avoid committing the local database.
- If your project contains sensitive code, be aware that the database stores symbol names and signatures (though not source code).
- Keep tokensave updated (`tokensave upgrade`) to receive security fixes.
- Review the [CHANGELOG](CHANGELOG.md) before upgrading to understand what changed.
## Scope
The following are **not** security issues:
- The aggregate token counter sending a count to the public Cloudflare Worker endpoint (this is documented behavior and contains no identifying information beyond an approximate country derived from IP by Cloudflare)
- The database containing symbol names or file paths from your project (this is core functionality)
- The daemon running in the background after explicit opt-in (`tokensave daemon --enable-autostart`)