Proton Pass Agent

Proton Pass agent

Run commands that may invoke pass-cli run through an isolated, automatically restored Proton Pass agent session.

scripts/run.sh --reason "Resolve credentials for the requested database inspection" -- \
  <credentialed-command>

The command itself does not need modification. The helper temporarily places a skill-local pass-cli wrapper first in PATH, so nested pass-cli run calls use the agent session. Other pass-cli subcommands delegate unchanged to the original CLI.

Setup

1. Install and log in to Proton Pass CLI.
2. Create a Proton Pass agent with the shortest practical expiration and viewer access only to required vaults or items. Agent and access changes are mutations: show the exact name, expiration, resources, and role, then obtain fresh user approval.
3. Save only the raw agent PAT in the token file. Never paste it into chat, logs, command arguments, documentation, or Git.

Default private state:

${XDG_STATE_HOME:-$HOME/.local/state}/proton-pass-agent/
├── agent.pat       # regular user-owned file, mode 0600
└── session/        # isolated filesystem-backed CLI session

Override locations when needed:

The state directory is created with mode 0700. The token file must already exist, must not be a symlink, and must be owned by the current user with mode 0600.

Behavior

• Every invocation requires a specific, non-secret audit reason of at most 300 characters.
• flock serializes session validation and login; ordinary reads may still run concurrently.
• Failed session validation triggers a forced cleanup, PAT login, and a second validation.
• The PAT is passed only in the login process environment and is never exported to the credentialed child command.
• The owner's normal Proton Pass session is not reused or replaced.
• Agent PATs expire after at most one year; agent CLI sessions last two hours and are recreated while the PAT remains valid.
• Access to newly created vaults is not automatic. Grant it only after fresh approval.

Tests

tests/test_wrapper.sh