localvault 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7a7a9c4bee5e2c661610323979b91de29205e4316213bde33496d7785f09d8e
-  data.tar.gz: aa0a9d9c4e1387cecc27f7f5de8b67ac7d843f603d3940bd3b5d726f95d2f433
+  metadata.gz: b181487cbbb186078cda14748801f5272f55349217358a9d9d93e47e079fb0c6
+  data.tar.gz: 66ffd265de195800930cd7da63da0359d9df62e0a69c8f6b9e519d8d643b62e7
 SHA512:
-  metadata.gz: c39e166b61c0021798884390112dddd051b23c5569ab0d41ec0dc420d0d0e472bff487e8fda5f9dd6bb47c7c1b2de99644fd3463cf9d334634b78dfc4f0f95f3
-  data.tar.gz: e3f4423241183217c1a08ea2ee5eae7aeccb167f698b94aedfbe730551b02a1567ed864f0406a84ea425cfc8233dde59221a4380f63d318512e2c1449f294c9d
+  metadata.gz: e360a9858c992f4f257393ee6a0dad05c4f993624a7b59545048f85f7050c1ba7a9ec0cc2b22c8ad48a704f4a70ef66b1e749075aa83c88e145717f649a67c4b
+  data.tar.gz: a84fb0edbf9fddb7b7bd4324354798003ae0caa95dfed899a75ca00fbb019db7441de5301ac135dccd11944ea2ad07efec1844456f849cc6e7bee50779067f9d

data/LICENSE

@@ -1,21 +1,19 @@
-MIT License
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
 
-Copyright (c) 2026 Nauman Tariq
+   Copyright 2026 Nauman Tariq / InventList (inventlist.com)
 
-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:
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+       http://www.apache.org/licenses/LICENSE-2.0
 
-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.
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   See http://www.apache.org/licenses/LICENSE-2.0 for the full license text.

data/README.md

@@ -75,6 +75,15 @@ localvault exec -- node app.js
 | `vaults` | List all vaults |
 | `unlock` | Output a session token for passphrase-free access |
 | `reset [NAME]` | Destroy all secrets and reinitialize with a new passphrase |
+| `login TOKEN` | Log in to InventList (auto-keygen + publish public key) |
+| `sync push` | Push vault to InventList cloud |
+| `sync pull` | Pull vault from InventList cloud |
+| `sync status` | Show sync state for all vaults |
+| `team init` | Initialize a vault as a team vault (sets you as owner) |
+| `team add @handle` | Add a teammate (with optional `--scope`) |
+| `team remove @handle` | Remove a teammate (with optional `--rotate` or `--scope`) |
+| `team list` | Show who has access to a synced vault |
+| `team rotate` | Re-encrypt vault with new passphrase (no member changes) |
 | `version` | Print version |
 
 All vault commands accept `--vault NAME` (or `-v NAME`) to target a specific vault. Defaults to `default`.
@@ -147,6 +156,59 @@ localvault reset
 
 Works on named vaults too: `localvault reset production`. All secrets are gone — there is no recovery.
 
+## Cloud Sync
+
+Sync vaults across devices via [InventList](https://inventlist.com). Your secrets stay encrypted — the server never sees plaintext.
+
+```bash
+# Log in (auto-generates keypair + publishes public key)
+localvault login YOUR_TOKEN
+
+# Push a vault to the cloud
+localvault sync push
+
+# Pull on another device
+localvault sync pull
+
+# Check sync status
+localvault sync status
+```
+
+## Team Sharing
+
+Share vault access with teammates using X25519 key slots. Three modes: personal sync (just you), direct share (one-time handoff), and team sync (ongoing shared access with scoping).
+
+```bash
+# Initialize a vault as a team vault (you become the owner)
+localvault team init -v production
+
+# Add a teammate with full access
+localvault team add @bob -v production
+
+# Add a teammate with scoped access (only specific keys)
+localvault team add @carol -v production --scope platepose DATABASE_URL
+
+# See who has access
+localvault team list -v production
+# => @alice  (owner)
+# => @bob    (full vault)
+# => @carol  (scopes: platepose, DATABASE_URL)
+
+# Remove access
+localvault team remove @bob -v production
+
+# Remove a specific scope (keeps other scopes)
+localvault team remove @carol -v production --scope DATABASE_URL
+
+# Remove + re-encrypt with new passphrase (full revocation)
+localvault team remove @bob -v production --rotate
+
+# Re-key without removing anyone (periodic rotation)
+localvault team rotate -v production
+```
+
+When a teammate pulls a vault they have a key slot for, it auto-unlocks via their identity key. Scoped members see only their authorized keys — they don't know other keys exist.
+
 ## 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.
@@ -186,7 +248,7 @@ See [MCP for AI Agents](https://inventlist.com/sites/localvault/series/localvaul
 |-------|-----------|---------|
 | Key derivation | **Argon2id** (64 MB, 2 iterations) | Passphrase to master key |
 | Encryption | **XSalsa20-Poly1305** | Authenticated encryption of secrets |
-| Key exchange | **X25519** | Future: shared vaults |
+| Key exchange | **X25519** | Team key slots + vault sharing |
 
 - Every encryption uses a random 24-byte nonce
 - Authentication tag prevents tampering (Poly1305)
@@ -205,7 +267,7 @@ See [MCP for AI Agents](https://inventlist.com/sites/localvault/series/localvaul
 │   └── production/
 │       ├── meta.yml
 │       └── secrets.enc
-└── keys/                   # Future: shared vault keys
+└── keys/                   # X25519 identity keypair for sync + team access
 ```
 
 - Secrets are stored as a single encrypted JSON blob per vault

data/lib/localvault/api_client.rb

@@ -3,7 +3,19 @@ require "uri"
 require "json"
 
 module LocalVault
+  # HTTP client for the InventList API (vault sync, sharing, public keys).
+  #
+  # All requests use Bearer token auth. Timeouts: 10s open, 30s read/write.
+  # Network and timeout errors are wrapped as ApiError so callers get a
+  # consistent exception type.
+  #
+  # @example
+  #   client = ApiClient.new(token: "tok-...", base_url: "https://inventlist.com")
+  #   client.me                         # => {"user" => {"handle" => "nauman"}}
+  #   client.push_vault("prod", blob)   # => {"name" => "prod", ...}
+  #   client.pull_vault("prod")         # => raw binary blob
   class ApiClient
+    # Raised on HTTP errors, network failures, and timeouts.
     class ApiError < StandardError
       attr_reader :status
 
@@ -15,39 +27,67 @@ module LocalVault
 
     BASE_PATH = "/api/v1"
 
+    # Create a new API client.
+    #
+    # @param token [String] Bearer token for authentication
+    # @param base_url [String, nil] API base URL (defaults to Config.api_url)
     def initialize(token:, base_url: nil)
       @token    = token
       @base_url = base_url || Config.api_url
     end
 
-    # GET /api/v1/me
+    # Fetch the authenticated user's profile.
+    #
+    # @return [Hash] user data (e.g. {"user" => {"handle" => "nauman"}})
+    # @raise [ApiError] on HTTP or network failure
     def me
       get("/me")
     end
 
-    # GET /api/v1/users/:handle/public_key
+    # Fetch a user's X25519 public key by handle.
+    #
+    # @param handle [String] the user's InventList handle
+    # @return [Hash] key data (e.g. {"public_key" => "base64..."})
+    # @raise [ApiError] on HTTP or network failure
     def get_public_key(handle)
       get("/users/#{URI.encode_uri_component(handle)}/public_key")
     end
 
-    # PUT /api/v1/profile/public_key
+    # Upload the current user's X25519 public key to InventList.
+    #
+    # @param public_key_b64 [String] base64-encoded X25519 public key
+    # @return [Hash] confirmation response
+    # @raise [ApiError] on HTTP or network failure
     def publish_public_key(public_key_b64)
       put("/profile/public_key", { public_key: public_key_b64 })
     end
 
-    # GET /api/v1/vault_shares/pending
+    # List vault shares pending acceptance by the current user.
+    #
+    # @return [Hash] shares data (e.g. {"shares" => [...]})
+    # @raise [ApiError] on HTTP or network failure
     def pending_shares
       get("/vault_shares/pending")
     end
 
-    # GET /api/v1/vault_shares/sent?vault_name=NAME
+    # List vault shares sent by the current user, optionally filtered by vault.
+    #
+    # @param vault_name [String, nil] filter by vault name (all shares if nil)
+    # @return [Hash] shares data (e.g. {"shares" => [...]})
+    # @raise [ApiError] on HTTP or network failure
     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
+    # Create a new vault share for a recipient.
+    #
+    # @param vault_name [String] name of the vault being shared
+    # @param recipient_handle [String] InventList handle of the recipient
+    # @param encrypted_payload [String] base64-encoded encrypted secrets from ShareCrypto
+    # @return [Hash] created share data
+    # @raise [ApiError] on HTTP or network failure
     def create_share(vault_name:, recipient_handle:, encrypted_payload:)
       post("/vault_shares", {
         vault_name:        vault_name,
@@ -56,42 +96,74 @@ module LocalVault
       })
     end
 
-    # PATCH /api/v1/vault_shares/:id/accept
+    # Accept a pending vault share.
+    #
+    # @param id [Integer, String] the share ID to accept
+    # @return [Hash] updated share data
+    # @raise [ApiError] on HTTP or network failure
     def accept_share(id)
       patch("/vault_shares/#{URI.encode_uri_component(id.to_s)}/accept", {})
     end
 
-    # DELETE /api/v1/vault_shares/:id
+    # Revoke (delete) a vault share.
+    #
+    # @param id [Integer, String] the share ID to revoke
+    # @return [Hash] confirmation response
+    # @raise [ApiError] on HTTP or network failure
     def revoke_share(id)
       delete("/vault_shares/#{URI.encode_uri_component(id.to_s)}")
     end
 
-    # GET /api/v1/teams/:handle/members/public_keys
+    # Fetch public keys for all members of a team.
+    #
+    # @param team_handle [String] the team's InventList handle
+    # @return [Hash] member keys (e.g. {"members" => [{"handle" => "...", "public_key" => "..."}]})
+    # @raise [ApiError] on HTTP or network failure
     def team_public_keys(team_handle)
       get("/teams/#{URI.encode_uri_component(team_handle)}/members/public_keys")
     end
 
-    # GET /api/v1/sites/:slug/crew/public_keys
+    # Fetch public keys for all crew members of a site.
+    #
+    # @param site_slug [String] the site's slug
+    # @return [Hash] crew keys (e.g. {"members" => [{"handle" => "...", "public_key" => "..."}]})
+    # @raise [ApiError] on HTTP or network failure
     def crew_public_keys(site_slug)
       get("/sites/#{URI.encode_uri_component(site_slug)}/crew/public_keys")
     end
 
-    # GET /api/v1/vaults
+    # List all vaults stored in the cloud for the authenticated user.
+    #
+    # @return [Hash] vaults data (e.g. {"vaults" => [{"name" => "prod", ...}]})
+    # @raise [ApiError] on HTTP or network failure
     def list_vaults
       get("/vaults")
     end
 
-    # PUT /api/v1/vaults/:name — sends raw binary blob, returns JSON
+    # Upload a vault bundle to the cloud (raw binary).
+    #
+    # @param name [String] vault name
+    # @param blob [String] packed SyncBundle binary blob
+    # @return [Hash] confirmation with vault metadata
+    # @raise [ApiError] on HTTP or network failure
     def push_vault(name, blob)
       request_binary(:put, "/vaults/#{URI.encode_uri_component(name)}", blob)
     end
 
-    # GET /api/v1/vaults/:name — returns raw binary blob
+    # Download a vault bundle from the cloud (raw binary).
+    #
+    # @param name [String] vault name
+    # @return [String] raw binary blob for SyncBundle.unpack
+    # @raise [ApiError] on HTTP or network failure (404 if vault not found)
     def pull_vault(name)
       request_raw(:get, "/vaults/#{URI.encode_uri_component(name)}")
     end
 
-    # DELETE /api/v1/vaults/:name
+    # Delete a vault from the cloud.
+    #
+    # @param name [String] vault name to delete
+    # @return [Hash] confirmation response
+    # @raise [ApiError] on HTTP or network failure
     def delete_vault(name)
       delete("/vaults/#{URI.encode_uri_component(name)}")
     end

data/lib/localvault/cli/keys.rb

@@ -5,6 +5,11 @@ module LocalVault
     class Keys < Thor
       desc "generate", "Generate an X25519 keypair for vault sharing"
       method_option :force, type: :boolean, default: false, desc: "Overwrite existing keypair"
+      # Generate a new X25519 keypair for vault sharing.
+      #
+      # Creates a private/public key pair in the LocalVault config directory.
+      # Refuses to overwrite an existing keypair unless +--force+ is passed.
+      # After generating, run +localvault keys publish+ to upload the public key.
       def generate
         if Identity.exists? && !options[:force]
           $stdout.puts "Keypair already exists at #{Config.keys_path}"
@@ -24,6 +29,11 @@ module LocalVault
       end
 
       desc "publish", "Upload your public key to InventList"
+      # Publish your X25519 public key to InventList.
+      #
+      # Requires a keypair (run +localvault keys generate+ first) and an active
+      # connection (run +localvault connect+ first). Once published, other users
+      # can share vaults with you.
       def publish
         unless Identity.exists?
           $stderr.puts "Error: No keypair found. Run: localvault keys generate"
@@ -44,6 +54,10 @@ module LocalVault
       end
 
       desc "show", "Display your public key"
+      # Print your base64-encoded X25519 public key to stdout.
+      #
+      # Useful for manual key exchange or verification. Requires a keypair
+      # to exist (run +localvault keys generate+ first).
       def show
         unless Identity.exists?
           $stderr.puts "Error: No keypair found. Run: localvault keys generate"

data/lib/localvault/cli/sync.rb

@@ -5,6 +5,12 @@ module LocalVault
   class CLI
     class Sync < Thor
       desc "push [NAME]", "Push a vault to InventList cloud sync"
+      # Push a local vault to InventList cloud sync.
+      #
+      # Packs the vault's meta and encrypted secrets into a SyncBundle and uploads
+      # it. Preserves existing key slots from the remote and bootstraps an owner
+      # slot if the current identity has no slot yet. Defaults to the configured
+      # default vault if no name is given.
       def push(vault_name = nil)
         return unless logged_in?
 
@@ -16,10 +22,36 @@ module LocalVault
           return
         end
 
-        key_slots = load_existing_key_slots(vault_name)
-        key_slots = bootstrap_owner_slot(key_slots, store)
+        # Load remote state to determine vault mode
+        remote_data = load_remote_bundle_data(vault_name)
+        handle = Config.inventlist_handle
+
+        if remote_data && remote_data[:owner]
+          # Team vault — check push authorization
+          owner = remote_data[:owner]
+          key_slots = remote_data[:key_slots] || {}
+          has_scoped = key_slots.values.any? { |s| s.is_a?(Hash) && s["scopes"].is_a?(Array) }
+          my_slot = key_slots[handle]
+          am_scoped = my_slot.is_a?(Hash) && my_slot["scopes"].is_a?(Array)
+
+          if am_scoped
+            $stderr.puts "Error: You have scoped access to vault '#{vault_name}'. Only the owner (@#{owner}) can push."
+            return
+          end
+
+          if has_scoped && owner != handle
+            $stderr.puts "Error: Vault '#{vault_name}' has scoped members. Only the owner (@#{owner}) can push."
+            return
+          end
+
+          # Authorized — push as v3, preserve key_slots
+          key_slots = bootstrap_owner_slot(key_slots, store)
+          blob = SyncBundle.pack_v3(store, owner: owner, key_slots: key_slots)
+        else
+          # Personal vault — push as v1
+          blob = SyncBundle.pack(store)
+        end
 
-        blob   = SyncBundle.pack(store, key_slots: key_slots)
         client = ApiClient.new(token: Config.token)
         client.push_vault(vault_name, blob)
 
@@ -30,6 +62,12 @@ module LocalVault
 
       desc "pull [NAME]", "Pull a vault from InventList cloud sync"
       method_option :force, type: :boolean, default: false, desc: "Overwrite existing local vault"
+      # Pull a vault from InventList cloud sync to the local filesystem.
+      #
+      # Downloads the SyncBundle, writes meta.yml and secrets.enc locally, and
+      # attempts automatic unlock via key slot. Refuses to overwrite an existing
+      # local vault unless +--force+ is passed. Defaults to the configured default
+      # vault if no name is given.
       def pull(vault_name = nil)
         return unless logged_in?
 
@@ -72,6 +110,10 @@ module LocalVault
       end
 
       desc "status", "Show sync status for all vaults"
+      # Display sync status for all local and remote vaults.
+      #
+      # Shows a table with vault name, status (synced / remote only / local only),
+      # and last sync timestamp. Compares local vaults against the cloud inventory.
       def status
         return unless logged_in?
 
@@ -115,8 +157,13 @@ module LocalVault
 
       private
 
-      # Try to decrypt the master key from a key slot matching the current identity.
-      # On success, caches the master key in SessionCache. Returns true/false.
+      # Try to decrypt via key slot matching the current identity.
+      #
+      # For full-access members (scopes: nil): decrypts enc_key to get the master key.
+      # For scoped members (scopes: [...]): decrypts enc_key to get the per-member key,
+      # then decrypts the per-member blob and writes it as the local vault's secrets.
+      #
+      # On success, caches the key in SessionCache. Returns true/false.
       def try_unlock_via_key_slot(vault_name, key_slots)
         return false unless key_slots.is_a?(Hash) && !key_slots.empty?
         return false unless Identity.exists?
@@ -127,25 +174,56 @@ module LocalVault
         slot = key_slots[handle]
         return false unless slot.is_a?(Hash) && slot["enc_key"].is_a?(String)
 
-        master_key = KeySlot.decrypt(slot["enc_key"], Identity.private_key_bytes)
+        decrypted_key = KeySlot.decrypt(slot["enc_key"], Identity.private_key_bytes)
 
-        # Verify the key actually works by trying to decrypt
-        vault = Vault.new(name: vault_name, master_key: master_key)
-        vault.all
+        if slot["scopes"].is_a?(Array) && slot["blob"].is_a?(String)
+          # Scoped member: decrypt per-member blob and write as local vault
+          blob_encrypted = Base64.strict_decode64(slot["blob"])
+          filtered_json = Crypto.decrypt(blob_encrypted, decrypted_key)
+          # Verify it's valid JSON
+          JSON.parse(filtered_json)
+
+          # Re-encrypt the filtered secrets with the member key as local "master key"
+          store = Store.new(vault_name)
+          store.write_encrypted(Crypto.encrypt(filtered_json, decrypted_key))
+
+          SessionCache.set(vault_name, decrypted_key)
+        else
+          # Full-access member: decrypted_key IS the master key
+          vault = Vault.new(name: vault_name, master_key: decrypted_key)
+          vault.all  # verify
 
-        SessionCache.set(vault_name, master_key)
+          SessionCache.set(vault_name, decrypted_key)
+        end
         true
-      rescue KeySlot::DecryptionError, Crypto::DecryptionError
+      rescue KeySlot::DecryptionError, Crypto::DecryptionError, ArgumentError, JSON::ParserError
         false
       end
 
       def logged_in?
         return true if Config.token
 
-        $stderr.puts "Error: Not logged in. Run: localvault login TOKEN"
+        $stderr.puts "Error: Not logged in."
+        $stderr.puts
+        $stderr.puts "  localvault login YOUR_TOKEN"
+        $stderr.puts
+        $stderr.puts "Get your token at: https://inventlist.com/settings"
+        $stderr.puts "New to InventList? Sign up free at https://inventlist.com"
+        $stderr.puts "Docs: https://inventlist.com/sites/localvault/series/localvault"
         false
       end
 
+      # Load the full unpacked remote bundle data (owner, key_slots, etc).
+      # Returns nil if no remote blob exists.
+      def load_remote_bundle_data(vault_name)
+        client = ApiClient.new(token: Config.token)
+        blob = client.pull_vault(vault_name)
+        return nil unless blob.is_a?(String) && !blob.empty?
+        SyncBundle.unpack(blob)
+      rescue ApiClient::ApiError, SyncBundle::UnpackError
+        nil
+      end
+
       # Load key_slots from the last pushed blob (if any).
       # Returns {} if no remote blob or if it's a v1 bundle.
       def load_existing_key_slots(vault_name)