agent-vault-cli 0.1.0

package/.cursor/skills/npm-publish/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: npm-publish
+description: Guide for bumping package versions and publishing to npm via CI/CD. Use when the user asks about publishing, releasing, version bumping, or deploying to npm.
+---
+
+# NPM Publish Workflow
+
+This project uses GitHub Actions CI/CD to automatically publish to npm when a version tag is pushed.
+
+## Quick Publish
+
+```bash
+# 1. Bump the version (updates package.json and creates a git tag)
+npm version patch   # 0.1.0 -> 0.1.1
+npm version minor   # 0.1.0 -> 0.2.0
+npm version major   # 0.1.0 -> 1.0.0
+
+# 2. Push to trigger CI/CD
+git push && git push --tags
+```
+
+The CI pipeline will automatically:
+- Run tests on multiple platforms (Ubuntu, macOS) and Node versions (18, 20)
+- Build the project
+- Publish to npm if all tests pass
+
+## Version Types
+
+| Command | Use When | Example |
+|---------|----------|---------|
+| `npm version patch` | Bug fixes, small updates | 0.1.0 → 0.1.1 |
+| `npm version minor` | New features, backwards compatible | 0.1.0 → 0.2.0 |
+| `npm version major` | Breaking changes | 0.1.0 → 1.0.0 |
+
+## Pre-release Versions
+
+```bash
+npm version prerelease --preid=alpha  # 0.1.0 -> 0.1.1-alpha.0
+npm version prerelease --preid=beta   # 0.1.0 -> 0.1.1-beta.0
+npm version prerelease --preid=rc     # 0.1.0 -> 0.1.1-rc.0
+```
+
+## Setup (One-time)
+
+Add `NPM_TOKEN` to GitHub repository secrets:
+1. Generate token at https://www.npmjs.com/settings/[username]/tokens
+2. Add to GitHub repo: Settings → Secrets and variables → Actions → New repository secret
+3. Name: `NPM_TOKEN`, Value: [your token]
+
+## Troubleshooting
+
+**CI fails to publish?**
+- Verify `NPM_TOKEN` is set in GitHub secrets
+- Check if version already exists on npm
+- Review GitHub Actions logs
+
+**Need to skip CI tests?**
+- Not recommended, but you can manually publish: `npm publish --access public`

package/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI/CD
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+      
+      - name: Install system dependencies for keytar
+        run: sudo apt-get update && sudo apt-get install -y libsecret-1-dev
+      
+      - name: Install dependencies with yarn
+        run: PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 yarn install --frozen-lockfile || PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 yarn install
+        timeout-minutes: 10
+      
+      - name: Build
+        run: yarn build
+      
+      - name: Run unit tests only
+        run: yarn test --run tests/crypto.test.ts tests/security.test.ts
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          registry-url: 'https://registry.npmjs.org'
+      
+      - name: Install system dependencies for keytar
+        run: sudo apt-get update && sudo apt-get install -y libsecret-1-dev
+      
+      - name: Install dependencies with yarn
+        run: PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 yarn install --frozen-lockfile || PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 yarn install
+        timeout-minutes: 10
+      
+      - name: Build
+        run: yarn build
+      
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,164 @@
+# Agent Vault CLI
+
+**Your AI agent can log into websites. Your credentials never touch the LLM.**
+
+Whether you're using personal accounts or dedicated agent credentials, they go straight from your keychain to the browser — never through the agent, never to the API.
+
+```
+Without Agent Vault:
+User → "login with alice@example.com / MySecret123" → Agent → LLM API
+                                                               ↓
+                                                      Credentials in:
+                                                      • API logs
+                                                      • Conversation history
+                                                      • Training data (maybe)
+
+With Agent Vault:
+Agent → "log in" → Vault → Browser
+                     ↓
+        Agent sees: "success" or "failed"
+        Credentials: never leave your keychain
+```
+
+> ⚠️ **Early development** — API may change. Feedback welcome.
+
+## Demo Video
+
+> 🎬 **Want to see it in action?** Check out our [demo video creation guide](./demo/QUICKSTART.md) to record your own!
+
+<!-- Add your demo video/gif here after recording -->
+
+## Quick Start
+
+```bash
+npm install -g @agent-vault/cli
+```
+
+**1. Register credentials** (you do this once, interactively):
+
+```bash
+vault register --cdp "ws://localhost:9222" \
+  --username-selector "#email" \
+  --password-selector "#password"
+```
+
+**2. Let your agent log in** (credentials never exposed):
+
+```bash
+vault login --cdp "ws://localhost:9222"
+```
+
+That's it. The agent calls `vault login`, gets back "success" or "failed", and continues with an authenticated session.
+
+---
+
+## How It Works
+
+The agent provides a browser (CDP endpoint). The vault:
+
+1. Connects directly to the browser
+2. Reads the current origin from the page (not from the agent)
+3. Looks up credentials for that origin in your OS keychain
+4. Fills the form and submits
+
+The agent never handles, sees, or transmits credentials.
+
+---
+
+## Why Not Use Existing Tools?
+
+**MCP credential tools** (1Password MCP, authenticator_mcp, etc.) return credentials to the agent:
+
+```
+Vault → MCP Server → Returns credential → Agent has credential → LLM context
+```
+
+They solve "don't commit secrets to git." They don't solve "don't expose secrets to the LLM."
+
+**Password manager extensions** keep credentials out of the LLM, but don't work in headless browsers — and that's where most production agents run.
+
+Agent Vault works in headless. Credentials go directly from keychain to browser, no extension UI required.
+
+---
+
+## What This Does (and Doesn't) Prevent
+
+| Threat | Prevented? |
+|--------|------------|
+| Credentials slip into prompt/context | ✅ Yes |
+| Credentials in LLM API logs | ✅ Yes |
+| Credentials in conversation history | ✅ Yes |
+| Credentials in error messages | ✅ Yes |
+| Malicious agent inspects DOM/network | ❌ No |
+
+This solves the 95% case: **credentials shouldn't be in prompts, logs, or API calls by default.**
+
+The 5% case (active interception by a malicious agent) requires intentional attack code and leaves traces. Different threat model, different mitigations.
+
+---
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `vault register` | Save credentials for a site (interactive) |
+| `vault login` | Fill credentials for current page |
+| `vault list` | Show registered sites |
+| `vault delete --origin <url>` | Remove credentials |
+| `vault config set/get/list/unset` | Manage defaults |
+
+Config stored in `~/.agent-vault/config.json`.
+
+---
+
+## Agent Integration Example
+
+```python
+# Your agent code
+browser_navigate("https://github.com/login")
+shell("vault login --cdp ws://localhost:9222")  # Returns success/failure
+# Continue with authenticated session
+```
+
+---
+
+## Security Model
+
+| Action | Agent provides | Agent sees credentials? |
+|--------|----------------|------------------------|
+| Register | CDP endpoint + selectors | Never (you enter them) |
+| Login | CDP endpoint only | Never (vault reads keychain) |
+
+---
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run dev    # watch mode
+npm test
+```
+
+### Creating Demo Videos
+
+Want to create a demo video? We have scripts for that!
+
+```bash
+# Interactive guided demo (recommended)
+npm run demo:interactive
+
+# Automated demo
+npm run demo:auto
+
+# Create video with Remotion
+npm run demo:video
+```
+
+See [demo/GUIDE.md](./demo/GUIDE.md) for complete instructions.
+
+---
+
+## License
+
+MIT