If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/gopasspw/gopass shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3d ago
• 13 active contributors
• Distributed ownership (top contributor 46% of recent commits)
• MIT licensed
• CI configured
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live gopasspw/gopass repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/gopasspw/gopass.

What it runs against: a local clone of gopasspw/gopass — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in gopasspw/gopass | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of gopasspw/gopass. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/gopasspw/gopass.git
#   cd gopass
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of gopasspw/gopass and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "gopasspw/gopass(\\.git)?\\b" \\
  && ok "origin remote is gopasspw/gopass" \\
  || miss "origin remote is not gopasspw/gopass (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f "ARCHITECTURE.md" \\
  && ok "ARCHITECTURE.md" \\
  || miss "missing critical file: ARCHITECTURE.md"
test -f ".github/copilot-instructions.md" \\
  && ok ".github/copilot-instructions.md" \\
  || miss "missing critical file: .github/copilot-instructions.md"
test -f "docs/backends.md" \\
  && ok "docs/backends.md" \\
  || miss "missing critical file: docs/backends.md"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/gopasspw/gopass"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

gopass is a CLI password manager for Unix/Linux/macOS/Windows that encrypts credentials with GPG (or alternative backends like age) and versions them in Git. It's a modern drop-in replacement for the standard pass tool, designed for distributed teams who need offline-capable, decentralized credential management without requiring a central server. Monolithic Go application with modular backends: internal/ contains core logic (crypto, storage engines in backends/), cmd/ holds CLI commands, internal/action/ implements business logic, and docs/backends/ documents pluggable encryption (GPG, age) and storage (Git, Fossil, CryptFS) backends. Main entry via cmd/gopass/main.go.

DevOps engineers, security teams, and distributed development organizations who need a CLI-first, Git-versioned password manager that works offline and integrates with CI/CD pipelines. Also used by individual power users who prefer command-line tools over browser extensions.

Production-ready and actively maintained. The project has comprehensive CI/CD via GitHub Actions (.github/workflows/), static analysis setup (golangci-lint, CodeQL, Grype), and follows semantic versioning. Recent commits are ongoing, and the codebase includes extensive docs (ARCHITECTURE.md, CONTRIBUTING.md, docs/adr/ for architectural decisions).

Low risk for core functionality, but moderate dependency surface: 40+ direct dependencies (filippo.io/age, ProtonMail/go-crypto, zalando/go-keyring, etc.). The project is community-maintained with multiple contributors, reducing single-person risk. GPG/cryptography dependencies (ProtonMail/go-crypto, golang.org/x/crypto) are well-vetted. Security scan workflows (Grype, CodeQL) are in place.

Active development with security-focused updates. Recent workflows include dependency scanning (Grype), OpenSSF scorecard integration, and architectural decision records (docs/adr/) documenting choices on template engines, hook systems, and shredding. Dependabot is configured for dependency updates.

Clone: git clone https://github.com/gopasspw/gopass.git && cd gopass. Build: make build (Makefile present). Install: make install or use Homebrew: brew install gopass. Verify: gopass --version.

Daily commands: Development: make build creates binary in build/. CLI usage: gopass init (setup store), gopass insert path/to/secret (add), gopass path/to/secret (retrieve). Browser integration via gopass-bridge (separate repo). Tests: make test, linting: make lint via golangci-lint.

• go.mod — Defines all Go dependencies including crypto (age, ProtonMail/go-crypto), CLI frameworks, and password generation libraries—essential for understanding security boundaries.
• ARCHITECTURE.md — Documents the high-level design of gopass, explaining how backends, storage, encryption, and RCS integration work together.
• .github/copilot-instructions.md — Captures architectural decisions and contribution guidelines that AI-assisted contributors must follow to maintain codebase consistency.
• docs/backends.md — Explains the pluggable backend system (age, GPG, cryptfs, gitfs, etc.)—critical for understanding how passwords are encrypted and stored.
• Makefile — Build and test orchestration; shows how to compile, test, and release gopass across multiple platforms.
• docs/security.md — Defines security guarantees, threat model, and cryptographic choices that developers must respect when modifying core logic.
• CONTRIBUTING.md — Contribution workflow, code style, and testing requirements that all PRs must follow.

Add a new backend encryption method

1. Study existing backend implementation (e.g., docs/backends/age.md or docs/backends/gpg.md) to understand the interface (docs/backends.md)
2. Create backend package following the abstraction pattern with Encrypt/Decrypt methods (docs/backends/age.md)
3. Register the backend in the storage initialization logic (docs/commands/init.md)
4. Add configuration documentation and examples (docs/config.md)
5. Add integration tests in the test suite (check Makefile for test targets) (Makefile)

Add a new CLI command

1. Review existing command structure in docs/commands/ (e.g., show.md, insert.md, generate.md) (docs/commands)
2. Implement command handler following gopass CLI conventions (docs/commands/gopass.md)
3. Update command routing and subcommand registration (docs/commands)
4. Add help text and documentation file in docs/commands/ (docs/commands)
5. Update shell completions (bash.completion and fish.completion) (bash.completion)

Add a new security or audit feature

1. Review existing audit command and security documentation (docs/commands/audit.md)
2. Check security model and threat boundaries in docs/security.md (docs/security.md)
3. Implement feature following cryptographic best practices (go.mod)
4. Add ADR (Architecture Decision Record) if major design choice (docs/adr)
5. Update code quality checks in .golangci.yml if new patterns introduced (.golangci.yml)

Add a new use case or workflow

1. Document the use case in docs/usecases/ with diagrams if applicable (docs/usecases)
2. Reference relevant commands (show.md, sync.md, otp.md, etc.) (docs/usecases/multi-store.md)
3. Add setup instructions and examples (docs/setup.md)
4. Update FAQ if covering common questions (docs/faq.md)

• Go 1.25 — Cross-platform compilation, strong standard library, minimal runtime dependencies, suitable for security-sensitive CLI tools.
• age (filippo.io/age) & ProtonMail/go-crypto — Modern, audited encryption libraries; age provides simple key derivation, ProtonMail/go-crypto enables GPG compatibility while supporting next-gen algorithms.
• Git/Fossil/jjfs backends — Enable distributed team workflows, revision history, and conflict resolution for shared password stores.
• Pluggable backend architecture — Allows users to choose encryption method (GPG, age, cryptfs) and storage system (Git, Fossil, plain filesystem) independently.
• HIBP integration (gopass-hibp) — Real-time weak password detection against Have I Been Pwned database for audit command.

• Pluggable backends over monolithic design

  • Why: Flexibility to support diverse team requirements (GPG legacy, age modern, filesystem encryption).
  • Consequence: Increased code complexity and test surface area; potential inconsistencies if backends diverge in behavior.

• Local encryption over server-side encryption

  • Why: Users retain complete cryptographic control; no trust in server infrastructure.
  • Consequence: Password derivation and encryption happen on user machine; slower for large stores but aligns with zero-knowledge model.

• Multi-store support via mounts

  • Why: Teams can organize passwords by project, team, or sensitivity without separate gopass installations.
  • Consequence: Adds configuration and initialization complexity; users must manage mount points and per-store keys.

• TOTP/OTP stored alongside passwords in same encrypted store

  • Why: Simplifies backup and restore workflow; all secrets in one location.
  • Consequence: TOTP secrets subject to same encryption/access controls; potential risk if GPG key compromised.

• Does not provide web UI or client-server architecture—CLI-only and local-first by design.
• Does not manage API tokens or OAuth credentials separately—treats all secrets uniformly.
• Does not guarantee post-quantum cryptography—current backends (age, GPG) are vulnerable to quantum computers.
• Does not auto-sync passwords without explicit user action or configured hooks—manual or hook-driven sync only.
• Does not provide cloud backup service—users responsible for backing up encrypted stores via RCS.

GPG setup required: if no GPG keys configured, gopass init will fail unless age backend is explicitly selected. Git configuration needed for versioning (email and name). D-Bus may be unavailable on headless systems, causing keyring failures—test with GOPASS_NOCLIP env var if clipboard issues arise. Shell completion requires manual setup (bash.completion file exists but not auto-installed). Windows path handling differs (uses native Windows backends, not Unix pipes).

• GPG (GNU Privacy Guard) Encryption — Default backend for credential encryption in gopass; understanding GPG keyrings and trust models is essential to troubleshoot init failures and multi-user scenarios
• Age Encryption — Modern alternative encryption backend (filippo.io/age) that gopass supports; simpler than GPG but requires understanding its recipient model vs GPG keys
• Git as a Versioned Credential Store — Core design pattern: gopass leverages Git for audit trails, branching, and team collaboration rather than a custom database; impacts merge conflict handling and history recovery
• Pluggable Backend Architecture — gopass defines interfaces (internal/backend/) allowing swappable crypto (GPG, age) and storage (Git, Fossil, CryptFS); new contributors must understand interface patterns to add backends
• Passphrase-Based Key Derivation (PBKDF2/Argon2) — Used when age backend derives keys from passphrases instead of GPG; affects security model and password strength requirements (docs/backends/age.md references this)
• D-Bus Integration (Linux) — gopass uses godbus/dbus/v5 to access OS keyrings and clipboard on Linux; understanding D-Bus is needed to debug credential caching and clipboard issues on headless systems
• YAML Path Navigation (caspr-io/yamlpath) — gopass supports nested YAML secrets and field extraction; the yamlpath library enables selecting specific fields from structured credential files (internal/action/edit.go likely uses this)

• zx2c4/pass — Original Unix password manager; gopass is a modern fork with team support and multi-backend flexibility
• bitwarden/cli — Alternative CLI password manager; Bitwarden-based with cloud sync, contrasts with gopass's decentralized Git-first model
• FiloSottile/age — Encryption backend used by gopass (filippo.io/age is the Go library); modern alternative to GPG that gopass supports
• gopasspw/gopass-bridge — Browser extension companion for gopass that enables GUI password filling without touching CLI
• gopasspw/gopass-hibp — Integrated HIBP breach checker (github.com/gopasspw/gopass-hibp is a dependency) for auditing compromised passwords

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for backend storage implementations

The repo supports multiple storage backends (age, cryptfs, fossilfs, gitfs, gpg, jjfs) documented in docs/backends/, but there's no evidence of comprehensive integration tests validating each backend's core operations (init, insert, retrieve, delete). This ensures backend implementations remain stable across refactors and new contributions.

• [ ] Create tests/integration/backends_test.go with test cases for each backend type in docs/backends/
• [ ] Test core operations: Initialize store, insert secret, retrieve secret, list entries, delete entry
• [ ] Verify backend-specific configuration from docs/backends/*.md is properly tested
• [ ] Add test fixtures for GPG keys, age identities, and git configs as needed

Add unit tests for the config command and configuration parsing

docs/commands/config.md indicates complex configuration management, but without seeing config_test.go in the documented structure, configuration parsing and validation likely lacks sufficient test coverage. This is critical for preventing regressions in user settings.

• [ ] Create tests for configuration file parsing in internal/config/ (inferred from docs structure)
• [ ] Add tests for config get/set operations documented in docs/commands/config.md
• [ ] Test validation of all configurable options and edge cases (invalid values, missing keys)
• [ ] Add tests for config precedence (defaults, environment variables, config file)

Implement GitHub Action workflow for testing all Go versions in go.mod range

The repo requires Go 1.25 but .github/workflows/build.yml likely tests only a single version. Adding a matrix strategy ensures gopass remains compatible across supported Go minor versions and catches version-specific issues early.

• [ ] Update .github/workflows/build.yml to add a Go version matrix (1.25, 1.26, etc.)
• [ ] Ensure tests run with -mod=mod to validate all dependency versions in go.mod
• [ ] Add conditional logic to report Go version compatibility issues in PR checks
• [ ] Verify build.yml doesn't duplicate testing already in golangci-lint.yml workflow

• Add missing unit tests in internal/backend/ for the fossil and CryptFS backends (docs/backends/fossilfs.md and docs/backends/cryptfs.md exist but test coverage gaps are likely). Start with internal/backend/fossilfs_test.go.
• Improve docs/commands/ completeness: only a few commands are documented (audit.md, cat.md, clone.md visible). Pick an undocumented command from cmd/gopass/ and add its docs/commands/COMMAND.md matching existing patterns.
• Add integration test for multi-backend scenarios in internal/config/: test switching between GPG→age encryption or Git→Fossil storage to verify migration/fallback paths. Reference existing *_test.go pattern.

Gopass demonstrates a strong security posture with OpenSSF Scorecard integration, CodeQL analysis, and comprehensive CI/CD security checks. The project is well-maintained with good security practices. However, key concerns include: (1) Supply chain risk from cloning external repositories without version pinning in Docker builds, (2) The complexity of the cryptographic dependency stack requires ongoing monitoring, (3) Clipboard handling

• Medium · Outdated Go Version in Dockerfile — Dockerfile (line 1). The Dockerfile specifies Go 1.25-alpine, which may have known vulnerabilities. The go.mod file declares 'go 1.25' but the specific patch version in the Docker image should be pinned and regularly updated. The base image hash is pinned but Go runtime patches should be verified. Fix: Regularly update the Alpine base image and verify Go patch versions. Consider using a more recent stable Go version if available, and implement automated dependency scanning in CI/CD.
• Medium · Multiple Cryptographic Dependencies Requiring Verification — go.mod (lines with crypto dependencies). The project uses multiple cryptographic libraries including ProtonMail/go-crypto, filippo.io/age, golang.org/x/crypto, and zeebo/blake3. While these are generally reputable, the complexity of the crypto stack increases the attack surface. ProtonMail/go-crypto v1.3.0 should be verified for known CVEs. Fix: Implement regular dependency scanning with tools like 'go list -json -m all | nancy sleuth' or 'gosec'. Monitor security advisories for all crypto dependencies. Consider periodic third-party security audits given the password manager nature of the application.
• Medium · External Repository Cloning in Docker Build — Dockerfile (lines 25-41). The Dockerfile clones external repositories (gopass-jsonapi, gopass-hibp, gopass-summon-provider) without version pinning or signature verification. This creates a supply chain risk where a compromised repository could inject malicious code during builds. Fix: Pin repository clones to specific commit hashes or tags. Implement git signature verification (git clone with --config transfer.fsckobjects=true). Consider vendoring dependencies instead of cloning at build time.
• Medium · Potential Clipboard Handling Vulnerability — go.mod (github.com/gopasspw/clipboard). The project includes clipboard functionality (gopasspw/clipboard dependency) for password operations. Clipboard operations can expose sensitive data in memory longer than necessary and may be accessible to other processes on the system. Fix: Implement secure clipboard handling with automatic clearing after timeout. Use syscall-level clipboard isolation where available. Document clipboard security assumptions in threat model. Consider implementing 'zero-copy' patterns for sensitive data.
• Low · CGO Disabled May Limit Security Features — Dockerfile (line 3). The Dockerfile sets CGO_ENABLED=0, which disables CGO. While this improves portability, it may disable certain cryptographic acceleration and security features that rely on native C libraries (e.g., system keyring integration). Fix: Document why CGO is disabled and evaluate whether enabling it selectively for security-critical operations is feasible. If CGO remains disabled, verify that fallback implementations are cryptographically sound.
• Low · Missing SBOM and Provenance Documentation — .github/workflows/ and general build process. While the project has good CI/CD practices (CodeQL, golangci-lint, Grype), there is no visible Software Bill of Materials (SBOM) or build provenance documentation. This makes supply chain verification difficult for users. Fix: Generate and publish SBOM using tools like syft or cyclonedx. Implement build provenance with tools like sigstore/cosign to provide cryptographic proof of build integrity. Include in release artifacts.
• Low · OTP and TOTP Implementation Should Be Audited — go.mod (github.com/pquerna/otp). The project uses pquerna/otp for OTP/TOTP functionality. Given the sensitive nature of password managers handling authentication codes, the implementation should be carefully audited. Fix: Review OTP implementation for constant-time comparisons and proper entropy handling. Verify that TOTP secrets are not logged. Consider periodic security audits of authentication-related code.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.