@mcp/auth-vault

🧩 Branch template — czysta wersja do klonowania i adaptacji.
Brak testów specyficznych dla Q-ekosystemu, brak danych wrażliwych.
Własne serwisy konfigurujesz przez add_service — wystarczą selektory CSS.

MCP server for secure credential management, browser-based login automation, SSH key vault, TOTP/2FA auto-solving, and audit logging.

Status:  active    |    License: MIT    |    Version: 0.2.0

Overview

Auth Vault stores encrypted credentials, secrets, and SSH keys (AES-256-GCM), automates browser login flows via Playwright, auto-solves TOTP-based 2FA challenges, and tracks sensitive actions via an audit log. It provides both an MCP interface (for AI clients) and a Web UI dashboard (for manual management).

Related MCP server: secure-vault-mcp

Features

• Encrypted vault — credentials, secrets, and SSH keys stored with AES-256-GCM

• SSH Key Vault — generate, store, retrieve, and export SSH keys (Ed25519, RSA-2048/4096)

• SSH Config generation — export SSH config fragments and key files

• Browser automation — Playwright-based login with form filling

• CAPTCHA detection — automatic detection of CAPTCHA challenges during login

• Trusted devices — device fingerprinting with trusted device management

• TOTP/2FA auto-solve — RFC 6238 implementation, generates and submits 2FA codes

• TOTP rotation detection — suggests code refresh when window is near expiry

• QR code support — generate QR for Google Authenticator setup

• Secrets management — API keys, bearer tokens, access/refresh tokens

• Password generator — strong random passwords and diceware passphrases (OpenSSL-backed)

• Audit logging — JSONL audit log with auto-rotation for sensitive actions

• Vault health monitoring — integrity checks (credentials, secrets, ssh indexes)

• Discovery API — metadata overview of all vault contents without decryption

• Tailscale-only access — binds to Tailscale IP by default, blocks external traffic

• Two service modes — STDIO (MCP standard) and SSE (HTTP for persistent connections)

Quick Start

Prerequisites

• Node.js 22+

• Playwright Chromium (installed via postinstall)

• Tailscale (recommended for SSE mode)

Setup

# Install dependencies
npm install

# Build TypeScript
npm run build

# Configure environment
cp .env.example .env
# Edit .env: set VAULT_ENCRYPTION_KEY (64 hex chars) or leave empty for auto-generated

Configuration

All configuration via .env file or environment variables:

Usage

STDIO Mode (default for MCP clients)

node dist/index.js

SSE Mode (HTTP server for persistent connections)

# Set AUTH_SSE_PORT=5501 in .env, then:
node dist/index.js

Web UI Dashboard

node dist/web/server.js
# Dashboard at http://<tailscale-ip>:5600/

CLI Commands

npm run add-creds     # Add credentials interactively
npm run add-secret    # Add a secret interactively
npm run list-creds    # List stored credentials
npm run list-secrets  # List stored secrets
npm run get-creds     # Get credential details

# SSH keys
npm run add-ssh-key       # Add an existing SSH key interactively
npm run generate-ssh-key  # Generate a new SSH key pair and store it
npm run list-ssh-keys     # List stored SSH keys
npm run get-ssh-key       # Get SSH key details

REST API

Credentials

Secrets

SSH Keys

Audit & Health

MCP Tools

Tools are exposed under the mcp_auth_vault_* namespace:

• Credentials: store_credentials, get_credentials, list_credentials, delete_credentials, get_credentials_for_service, attach_totp, generate_totp, generate_totp_by_service, totp_qr

• Secrets: store_secret, get_secret, list_secrets, delete_secret, update_secret, audit_secret_expiry

• SSH: store_ssh_key, get_ssh_key, list_ssh_keys, delete_ssh_key, generate_ssh_key, export_ssh_config, export_ssh_key_file, get_ssh_fingerprint, extract_ssh_public_key, update_ssh_key

• Services: get_service, list_services, add_service

• Login: auth_login, login_status, submit_totp, logout

• Audit: list_audit_actions, log_audit_action, vault_integrity_check, vault_health_summary

Systemd Services

# MCP SSE server (port 5501)
systemctl status mcp-auth-vault

# Web UI dashboard (port 5500)
systemctl status mcp-auth-vault-web

Both services restart automatically on failure and enable at boot.

Security

• AES-256-GCM encryption for all stored credentials and secrets

• Tailscope-restricted — SSE mode blocks non-Tailscale connections

• Encryption key persisted in .env — if lost, data cannot be recovered

• Headless browser — no visible UI during automated logins

Project Structure

src/
├── index.ts              # MCP server entry (STDIO + SSE)
├── config.ts             # Zod-validated configuration
├── credentials/
│   ├── totp.ts           # TOTP (RFC 6238) implementation
│   ├── qr.ts             # QR code generation + TOTP secret generator
│   ├── vault.ts          # Encrypted credential store
│   └── types.ts          # Credential type definitions
├── secrets/
│   ├── manager.ts        # Encrypted secrets store
│   └── types.ts          # Secret type definitions
├── browser/
│   └── manager.ts        # Playwright session management
├── services/
│   └── definitions.ts    # Login templates (Google, etc.)
├── web/
│   ├── server.ts         # Web UI HTTP server + REST API
│   └── dashboard.ts      # HTML dashboard template
├── tools/
│   ├── credentials.ts    # MCP tool definitions for credentials
│   ├── secrets.ts        # MCP tool definitions for secrets
│   ├── services.ts       # MCP tool definitions for services
│   └── login.ts          # MCP tool definitions for login
└── cli/
    ├── add-credentials.ts
    └── add-secret.ts

Tech Stack

• Runtime: Node.js 24, TypeScript ESM

• MCP: @modelcontextprotocol/sdk v1.16

• Encryption: Node.js crypto (AES-256-GCM)

• Browser: Playwright (Chromium)

• Config: Zod validation

• UI: Vanilla JS (no framework)

• QR: qrcode npm package

License

MIT