passwd CLAUDE.md

passwd

Monorepo with four npm packages + one desktop extension for passwd.team:

• passwd-lib — core library (auth, API client, types). Zero dependencies.
• passwd-mcp — MCP server for AI assistants. Depends on passwd-lib, @modelcontextprotocol/sdk, zod.
• passwd-mcpb — Desktop extension for Claude (.mcpb). All 8 tools including credential injection and MCP proxy. Depends on passwd-lib, @modelcontextprotocol/sdk, zod.
• passwd-cli — full CLI tool. Depends on passwd-lib, commander.
• passwd-agent-cli — agent-safe CLI (no command exposes raw credentials). Depends on passwd-lib, commander.

Build

npm install          # links workspaces
npm run build        # tsc -b (builds lib first, then mcp + cli)
npm run clean        # tsc -b --clean

Project structure

packages/
  passwd-lib/src/        types.ts, auth.ts, api.ts, index.ts (barrel)
  passwd-mcp/src/        index.ts (MCP server with 5 read-only tools)
  passwd-mcpb/src/       index.ts (desktop extension with 8 tools including run_with_credentials and MCP proxy)
  passwd-cli/src/        index.ts (commander), commands/*.ts, util/format.ts
  passwd-agent-cli/src/  index.ts (commander, 8 safe commands), commands/*.ts, util/

Key design decisions

• npm workspaces with TypeScript project references (composite: true, tsc -b)
• passwd-lib has zero npm dependencies — only Node.js built-ins
• Client-side filtering: the passwd API returns all secrets at once. Filtering/pagination is done in listSecrets(). MCP defaults to limit 50, CLI defaults to no limit.
• passwd get <id> --field password outputs raw value with no trailing newline (for $() piping)
• passwd exec --inject VAR=ID:FIELD fetches secrets in parallel, execs child with stdio: inherit
• Token storage uses VS Code pattern: one AES-256-GCM encryption key stored in platform keychain (macOS security CLI / Linux secret-tool via libsecret), account encryption-key. Encrypted token blobs stored as files at ~/.passwd/tokens-{hash}.json. Format: {v:1, iv, tag, data} hex-encoded. Keychain key created on first saveTokens(), shared across environments. deleteTokens() removes the file but not the key. Linux secret-tool store reads value via stdin (no process list exposure). No env var bypass — keychain is required. Zero npm dependencies maintained (node:crypto built-in).