v0.1.0 — Encrypted file vault with CLI and MCP server

.gitattributes

@@ -0,0 +1,2 @@
+# Ensure consistent line endings across platforms
+* text=auto eol=lf

.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main, feat/*]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        node-version: [22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Test
+        run: npm test
+
+      - name: Format check
+        run: npm run format:check

.prettierrc

@@ -0,0 +1,8 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "endOfLine": "lf"
+}

CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-04-22
+
+Initial release. A working encrypted file vault with CLI and MCP server.
+
+### Added
+
+- **CLI** with full command suite: `init`, `unlock`, `lock`, `status`, `write`, `read`, `delete`, `list`, `search`, `grep`, `key add/list/revoke`, `audit`, `mcp`
+- **MCP server** exposing 5 tools to AI agents: `vault_read_file`, `vault_create_file`, `vault_list_dir`, `vault_grep_search`, `vault_file_search`
+- **age encryption** for all file content — no custom cryptography
+- **Multi-key access** — add backup passphrases, revoke compromised keys without re-encrypting
+- **Session-based unlock** — passphrase unlocks the vault for 30 minutes; MCP server reads session state on demand
+- **SQLite metadata store** — file metadata (names, sizes, dates, tags) queryable while locked
+- **Audit logging** — every operation recorded with timestamp, type, and target path (never content)
+- **Security hardening** — path traversal prevention, output sanitization, restrictive file permissions
+- **Cross-platform support** — macOS, Linux, Windows
+- **Documentation** — README, quickstart guide, CLI reference, MCP tools reference, security model
+- **CI** — GitHub Actions workflow running build, lint, and tests on all 3 platforms
+- **154 tests** — unit tests for every module plus end-to-end integration tests

LICENSE

@@ -2,6 +2,11 @@ MIT License
 
 Copyright (c) 2026 ThingsAI.io
 
+EXPERIMENTAL SOFTWARE — This project is in early development. It is provided
+as-is with no guarantees of stability, backward compatibility, or fitness for
+any particular purpose. Use at your own risk. Do not use as your sole storage
+for important data.
+
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights

README.md

@@ -1,2 +1,127 @@
-# workspace-vault
-A secure vault to store private files that GitHub custom agents can use to read/write private content separately from the current workspace
+# Workspace Vault
+
+> **⚠️ Experimental** — This project is in early development and provided as-is. APIs, file formats, and encryption schemes may change between versions. Do not rely on this for production use or as your only copy of important files. Always keep backups of your original data.
+
+An encrypted file vault with CLI and MCP server that gives AI agents controlled access to your private files.
+
+Files are encrypted at rest using [age](https://age-encryption.org/). You control when the vault is unlocked. Your agent works with files through standard operations — read, write, search, list — and when the session ends, everything locks again.
+
+## Quickstart
+
+```bash
+# Install
+npm install -g workspace-vault
+
+# Initialize a vault (you'll set a passphrase)
+vault init
+
+# Store a file
+vault write contracts/nda.pdf --from ~/Documents/nda.pdf
+
+# Unlock so your agent can access files
+vault unlock
+
+# Check status
+vault status
+```
+
+### Connect to your AI agent
+
+After `vault init`, add this to your MCP client config:
+
+**VS Code / Copilot** (`.vscode/mcp.json`):
+```json
+{
+  "servers": {
+    "workspace-vault": {
+      "command": "vault",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+**Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "workspace-vault": {
+      "command": "vault",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+That's it. Your agent can now read, write, search, and list vault files — as long as you've unlocked the vault.
+
+## How it works
+
+1. **You** initialize the vault and set a passphrase
+2. **You** store files into the vault (they're encrypted immediately)
+3. **You** unlock the vault when you want your agent to have access
+4. **Your agent** reads, writes, and searches files through MCP tools
+5. The vault **auto-locks** after 30 minutes (configurable) or when you run `vault lock`
+
+The agent never sees the passphrase. It never self-authorizes. All access is audited.
+
+## Documentation
+
+- **[Quickstart Guide](docs/quickstart.md)** — full setup walkthrough
+- **[CLI Reference](docs/cli.md)** — all commands and options
+- **[MCP Tools Reference](docs/mcp.md)** — tools available to AI agents
+- **[Security Model](spec/security.md)** — encryption, threat model, design decisions
+
+## CLI overview
+
+```
+vault init [path]           Initialize a new vault
+vault unlock                Unlock the vault (passphrase prompt)
+vault lock                  Lock the vault
+vault status                Show vault status
+
+vault write <path>          Write a file (--from <file> or stdin)
+vault read <path>           Read and decrypt a file
+vault delete <path>         Delete a file
+vault list [path]           List files (works while locked)
+vault search <query>        Search by filename or tag
+vault grep <pattern>        Search file contents (requires unlock)
+
+vault key add               Add a new passphrase key
+vault key list              List authorized keys
+vault key revoke <key-id>   Revoke a key
+
+vault audit                 View the audit log
+vault mcp                   Start the MCP server
+```
+
+## MCP tools
+
+| Tool | Description | Requires unlock |
+|------|-------------|:---:|
+| `vault_read_file` | Read and decrypt a file | Yes |
+| `vault_create_file` | Create an encrypted file | Yes |
+| `vault_grep_search` | Search file contents by pattern | Yes |
+| `vault_list_dir` | List files and metadata | No |
+| `vault_file_search` | Search by filename or tag | No |
+
+## Security
+
+- Files are encrypted at rest with [age](https://age-encryption.org/) — no custom cryptography
+- The master key exists in memory only during active sessions
+- Multi-key support: add backup keys, revoke compromised ones without re-encrypting
+- All operations are recorded in an audit log (no content is ever logged)
+- Path traversal and injection attacks are blocked at the boundary
+
+See [spec/security.md](spec/security.md) for the full security model.
+
+## Requirements
+
+- Node.js 22+
+- macOS, Linux, or Windows
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+This software is experimental and provided "as is", without warranty of any kind. Use at your own risk.