localvault 0.9.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 671f50a3af0358b5344e1ee94f39cee7b74c7d45c5a55fce9e42da3b1f5b3ffc
+  data.tar.gz: a7f41141bff442117b919c5aba3864d51830aedf32ca8ef0ee025bd15bd5ea57
+SHA512:
+  metadata.gz: bde2aaed764d7317de96dda2f962a569fe4a9ae9084e14971ee7a0f838d9c2c0a698bf0f3c0ba151f6179b16522ca61a368f5b881b9491d5db7ab74ec8f50e43
+  data.tar.gz: dfdeb12993ae4236e98b8b19424b9b03d60f29f842c4586f5f31b4dfeef13e44791e04f0b53d50fb14fb2794bc2939b69eedb71c1029b614a907868a27df0958

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nauman Tariq
+
+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
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,227 @@
+# LocalVault
+
+Zero-infrastructure secrets manager. Encrypted secrets stored locally, unlocked with a passphrase.
+
+No servers. No cloud. No config files to leak. Just encrypted files on disk.
+
+Part of [InventList Tools](https://inventlist.com/tools/localvault) — free, open-source developer utilities for indie builders.
+
+## Install
+
+### Homebrew (macOS)
+
+```bash
+brew install inventlist/tap/localvault
+```
+
+### RubyGems
+
+```bash
+gem install localvault
+```
+
+**Requires libsodium:**
+
+```bash
+# macOS
+brew install libsodium
+
+# Ubuntu/Debian
+sudo apt-get install libsodium-dev
+
+# Fedora
+sudo dnf install libsodium-devel
+```
+
+## Quick Start
+
+```bash
+# Create a vault (prompts for passphrase)
+localvault init
+
+# Store any sensitive values — API keys, tokens, credentials, database URLs
+localvault set OPENAI_API_KEY "sk-proj-..."
+localvault set STRIPE_SECRET_KEY "sk_live_..."
+localvault set GITHUB_TOKEN "ghp_..."
+
+# Retrieve a secret (pipeable)
+localvault get OPENAI_API_KEY
+
+# List all keys
+localvault list
+
+# Export as shell variables
+localvault env
+# => export GITHUB_TOKEN="ghp_..."
+# => export OPENAI_API_KEY="sk-proj-..."
+# => export STRIPE_SECRET_KEY="sk_live_..."
+
+# Run a command with secrets injected
+localvault exec -- rails server
+localvault exec -- node app.js
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `init [NAME]` | Create a vault (prompts for passphrase with confirmation) |
+| `set KEY VALUE` | Store a secret |
+| `get KEY` | Retrieve a secret (raw value, pipeable) |
+| `list` | List all keys |
+| `delete KEY` | Remove a secret |
+| `env` | Export all secrets as `export KEY="value"` lines |
+| `exec -- CMD` | Run a command with all secrets as env vars |
+| `vaults` | List all vaults |
+| `unlock` | Output a session token for passphrase-free access |
+| `reset [NAME]` | Destroy all secrets and reinitialize with a new passphrase |
+| `version` | Print version |
+
+All vault commands accept `--vault NAME` (or `-v NAME`) to target a specific vault. Defaults to `default`.
+
+## Session Caching
+
+Avoid typing your passphrase repeatedly:
+
+```bash
+# Unlock once per terminal session
+eval $(localvault unlock)
+
+# All subsequent commands skip the passphrase prompt
+localvault get API_KEY
+localvault list
+localvault exec -- rails server
+```
+
+The session token is stored in `LOCALVAULT_SESSION` and contains the derived master key (base64-encoded). It lives only in your shell's memory and disappears when the terminal closes.
+
+## Multiple Vaults
+
+Separate secrets by project, environment, or service — each vault has its own passphrase and encryption:
+
+```bash
+# Create separate vaults
+localvault init production
+localvault init staging
+localvault init x          # all X / Twitter API credentials
+
+# Use --vault to target a specific vault
+localvault set API_KEY "sk-prod-xxx" --vault production
+localvault set API_KEY "sk-staging-xxx" --vault staging
+
+# Store multiple X accounts in one vault using handle-prefixed keys
+localvault set MYHANDLE_API_KEY        "..." --vault x
+localvault set MYHANDLE_API_SECRET     "..." --vault x
+localvault set MYHANDLE_ACCESS_TOKEN   "..." --vault x
+localvault set MYHANDLE_ACCESS_SECRET  "..." --vault x
+localvault set MYHANDLE_BEARER_TOKEN   "..." --vault x
+
+localvault set MYBRAND_API_KEY         "..." --vault x
+localvault set MYBRAND_ACCESS_TOKEN    "..." --vault x
+
+# List all vaults
+localvault vaults
+# => default (default)
+# => production
+# => staging
+# => x
+
+# Unlock a specific vault for a session
+eval $(localvault unlock --vault x)
+localvault exec --vault x -- ruby scripts/post.rb
+```
+
+## Resetting a Vault
+
+Forgot your passphrase? Use `reset` to destroy all secrets and start fresh with a new one:
+
+```bash
+localvault reset
+# WARNING: This will permanently delete all secrets in vault 'default'.
+# This cannot be undone.
+# Type 'default' to confirm: default
+# New passphrase:
+# Confirm passphrase:
+# Vault 'default' has been reset.
+```
+
+Works on named vaults too: `localvault reset production`. All secrets are gone — there is no recovery.
+
+## MCP Server (AI Agents)
+
+LocalVault includes an MCP server so AI coding agents can read and manage secrets via the Model Context Protocol — without ever seeing your passphrase.
+
+```bash
+# Unlock your vault first
+eval $(localvault unlock)
+```
+
+Then add to your MCP config (`.mcp.json`, `.cursor/mcp.json`, etc.):
+
+```json
+{
+  "mcpServers": {
+    "localvault": {
+      "command": "localvault",
+      "args": ["mcp"],
+      "env": {
+        "LOCALVAULT_SESSION": "<your-session-token>"
+      }
+    }
+  }
+}
+```
+
+If you've already run `eval $(localvault unlock)` in your terminal, the agent inherits the session automatically — no need to paste the token.
+
+**Available tools:** `get_secret`, `list_secrets`, `set_secret`, `delete_secret`
+
+See [MCP Setup Guide](docs/site-docs/mcp-setup.md) for Claude Code and Cursor configuration details.
+
+## Security
+
+### Crypto Stack
+
+| Layer | Algorithm | Purpose |
+|-------|-----------|---------|
+| Key derivation | **Argon2id** (64 MB, 2 iterations) | Passphrase to master key |
+| Encryption | **XSalsa20-Poly1305** | Authenticated encryption of secrets |
+| Key exchange | **X25519** | Future: shared vaults |
+
+- Every encryption uses a random 24-byte nonce
+- Authentication tag prevents tampering (Poly1305)
+- Argon2id is memory-hard, resistant to GPU/ASIC attacks
+- All crypto via [libsodium](https://doc.libsodium.org/) (RbNaCl bindings)
+
+### Storage Layout
+
+```
+~/.localvault/
+├── config.yml              # Default vault name
+├── vaults/
+│   ├── default/
+│   │   ├── meta.yml        # Salt, creation date, version
+│   │   └── secrets.enc     # Encrypted JSON blob
+│   └── production/
+│       ├── meta.yml
+│       └── secrets.enc
+└── keys/                   # Future: shared vault keys
+```
+
+- Secrets are stored as a single encrypted JSON blob per vault
+- Atomic writes (temp file + rename) prevent corruption
+- Salt is stored in plaintext metadata (this is standard and safe)
+- The master key is never written to disk
+
+## Development
+
+```bash
+git clone https://github.com/inventlist/localvault.git
+cd localvault
+bundle install
+bundle exec rake test
+```
+
+## License
+
+MIT

data/bin/localvault

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+# Support both development (require_relative) and installed (load path) usage
+begin
+  require_relative "../lib/localvault"
+  require_relative "../lib/localvault/cli"
+rescue LoadError
+  require "localvault"
+  require "localvault/cli"
+end
+
+LocalVault::CLI.start(ARGV)

data/lib/localvault/api_client.rb

@@ -0,0 +1,125 @@
+require "net/http"
+require "uri"
+require "json"
+
+module LocalVault
+  class ApiClient
+    class ApiError < StandardError
+      attr_reader :status
+
+      def initialize(msg, status: nil)
+        super(msg)
+        @status = status
+      end
+    end
+
+    BASE_PATH = "/api/v1"
+
+    def initialize(token:, base_url: nil)
+      @token    = token
+      @base_url = base_url || Config.api_url
+    end
+
+    # GET /api/v1/users/:handle/public_key
+    def get_public_key(handle)
+      get("/users/#{handle}/public_key")
+    end
+
+    # PUT /api/v1/profile/public_key
+    def publish_public_key(public_key_b64)
+      put("/profile/public_key", { public_key: public_key_b64 })
+    end
+
+    # GET /api/v1/vault_shares/pending
+    def pending_shares
+      get("/vault_shares/pending")
+    end
+
+    # GET /api/v1/vault_shares/sent?vault_name=NAME
+    def sent_shares(vault_name: nil)
+      path = "/vault_shares/sent"
+      path += "?vault_name=#{URI.encode_uri_component(vault_name)}" if vault_name
+      get(path)
+    end
+
+    # POST /api/v1/vault_shares
+    def create_share(vault_name:, recipient_handle:, encrypted_payload:)
+      post("/vault_shares", {
+        vault_name:        vault_name,
+        recipient_handle:  recipient_handle,
+        encrypted_payload: encrypted_payload
+      })
+    end
+
+    # PATCH /api/v1/vault_shares/:id/accept
+    def accept_share(id)
+      patch("/vault_shares/#{id}/accept", {})
+    end
+
+    # DELETE /api/v1/vault_shares/:id
+    def revoke_share(id)
+      delete("/vault_shares/#{id}")
+    end
+
+    # GET /api/v1/teams/:handle/members/public_keys
+    def team_public_keys(team_handle)
+      get("/teams/#{team_handle}/members/public_keys")
+    end
+
+    # GET /api/v1/sites/:slug/crew/public_keys
+    def crew_public_keys(site_slug)
+      get("/sites/#{site_slug}/crew/public_keys")
+    end
+
+    private
+
+    def get(path)
+      request(:get, path)
+    end
+
+    def post(path, body)
+      request(:post, path, body)
+    end
+
+    def put(path, body)
+      request(:put, path, body)
+    end
+
+    def patch(path, body = nil)
+      request(:patch, path, body)
+    end
+
+    def delete(path)
+      request(:delete, path)
+    end
+
+    def request(method, path, body = nil)
+      uri  = URI("#{@base_url}#{BASE_PATH}#{path}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+
+      req_class = {
+        get:    Net::HTTP::Get,
+        post:   Net::HTTP::Post,
+        put:    Net::HTTP::Put,
+        patch:  Net::HTTP::Patch,
+        delete: Net::HTTP::Delete
+      }.fetch(method)
+
+      req = req_class.new(uri.request_uri)
+      req["Authorization"] = "Bearer #{@token}"
+      req["Content-Type"]  = "application/json"
+      req["Accept"]        = "application/json"
+      req.body = JSON.generate(body) if body
+
+      res = http.request(req)
+      unless res.is_a?(Net::HTTPSuccess)
+        err = begin JSON.parse(res.body)["error"] rescue nil end
+        raise ApiError.new(err || "HTTP #{res.code}", status: res.code.to_i)
+      end
+      JSON.parse(res.body)
+    rescue Errno::ECONNREFUSED, SocketError => e
+      raise ApiError.new("Cannot connect to #{@base_url}: #{e.message}")
+    end
+  end
+end

data/lib/localvault/cli/keys.rb

@@ -0,0 +1,56 @@
+require "thor"
+
+module LocalVault
+  class CLI
+    class Keys < Thor
+      desc "generate", "Generate an X25519 keypair for vault sharing"
+      method_option :force, type: :boolean, default: false, desc: "Overwrite existing keypair"
+      def generate
+        if Identity.exists? && !options[:force]
+          $stdout.puts "Keypair already exists at #{Config.keys_path}"
+          $stdout.puts "Use --force to overwrite."
+          return
+        end
+
+        Config.ensure_directories!
+        Identity.generate!(force: options[:force])
+        $stdout.puts "Keypair generated:"
+        $stdout.puts "  Private: #{Identity.priv_key_path}"
+        $stdout.puts "  Public:  #{Identity.pub_key_path}"
+        $stdout.puts
+        $stdout.puts "Run 'localvault keys publish' to upload your public key to InventList."
+      rescue RuntimeError => e
+        $stderr.puts "Error: #{e.message}"
+      end
+
+      desc "publish", "Upload your public key to InventList"
+      def publish
+        unless Identity.exists?
+          $stderr.puts "Error: No keypair found. Run: localvault keys generate"
+          return
+        end
+
+        unless Config.token
+          $stderr.puts "Error: Not connected. Run: localvault connect --token TOKEN --handle HANDLE"
+          return
+        end
+
+        client = ApiClient.new(token: Config.token)
+        client.publish_public_key(Identity.public_key)
+        $stdout.puts "Public key published to InventList (@#{Config.inventlist_handle})."
+        $stdout.puts "Others can now share vaults with you."
+      rescue ApiClient::ApiError => e
+        $stderr.puts "Error: #{e.message}"
+      end
+
+      desc "show", "Display your public key"
+      def show
+        unless Identity.exists?
+          $stderr.puts "Error: No keypair found. Run: localvault keys generate"
+          return
+        end
+        $stdout.puts Identity.public_key
+      end
+    end
+  end
+end

data/lib/localvault/cli/team.rb

@@ -0,0 +1,37 @@
+require "thor"
+
+module LocalVault
+  class CLI
+    class Team < Thor
+      desc "list [VAULT]", "Show who has access to a vault"
+      def list(vault_name = nil)
+        unless Config.token
+          $stderr.puts "Error: Not connected. Run: localvault connect --token TOKEN --handle HANDLE"
+          return
+        end
+
+        vault_name ||= Config.default_vault
+        client = ApiClient.new(token: Config.token)
+        result = client.sent_shares(vault_name: vault_name)
+        shares = (result["shares"] || []).reject { |s| s["status"] == "revoked" }
+
+        if shares.empty?
+          $stdout.puts "No active shares for vault '#{vault_name}'."
+          return
+        end
+
+        $stdout.puts "Vault: #{vault_name} — #{shares.size} share(s)"
+        $stdout.puts
+        $stdout.printf("%-8s  %-20s  %-10s  %-12s\n", "ID", "Recipient", "Status", "Shared")
+        $stdout.puts("-" * 56)
+        shares.each do |s|
+          date = s["created_at"]&.slice(0, 10) || ""
+          $stdout.printf("%-8s  %-20s  %-10s  %-12s\n",
+            s["id"].to_s, "@#{s["recipient_handle"]}", s["status"], date)
+        end
+      rescue ApiClient::ApiError => e
+        $stderr.puts "Error: #{e.message}"
+      end
+    end
+  end
+end