omarchy/plugins/io.github.elevate08.qs-bitwarden-cli/docs/decisions/0002-grant-scope.md

2. Approval grants are scoped to a program, not a process

Date: 2026-08-27

Status

Accepted. Supersedes the grant-scoping rule in docs/ideas/ssh-agent.md ("Bounded approval grants"), which this decision deliberately relaxes.

Context

The design specified that an approval grant is "scoped to one key and one live client process", keyed on the peer PID together with that PID's start time and the executable path captured at grant time. PID reuse therefore cannot inherit a grant, and a re-exec invalidates it.

That rule was justified by a usability argument:

Approval strictly per signature is unusable for the workflows this feature exists to serve. A git rebase over twenty commits with gpg.format=ssh is twenty modal prompts; a fetch followed by a push is two.

Live testing against a real vault showed the rule does not achieve that. Git does not hold a connection to the agent across commits: it spawns a fresh ssh-keygen -Y sign process for every commit it signs. Every one of those has a different PID and a different start time, so a PID-scoped grant never matches. Approving "for this process" and then making a second signed commit prompted again, and a twenty-commit rebase would prompt twenty times whether a grant was taken or not.

So the grant, as specified, was close to inert: it helped only a single long-lived process making repeated signature requests, which is not a workflow this feature was built for. The button existed and did nothing useful.

Decision

A grant is scoped to one key and one program, for one user: it matches on the peer UID, the executable path captured at grant time, and the public key. PID and process start time are still captured and shown in the prompt, but no longer participate in matching.

The approval button says "Approve for this program", not "for this process", because that is what it now does.

Unchanged:

• The peer UID must equal the companion's effective UID. That is the one property the companion actually verifies, and it is not relaxed here.
• The window is still bounded by sshAgentApprovalWindowSec (default 120s, maximum 900s, 0 disables grants entirely).
• Grants still live only in the companion's memory, never touch disk, and never survive a restart.
• Every lifecycle event that dropped a grant before still drops it: expiry, lock, logout, account change, epoch change, disabling the feature, screen lock, suspend, revoke_grants, and per-grant revocation.
• A grant still replaces the prompt, not the final check. Epoch, lock state and key identity are rechecked immediately before the signing primitive.

Consequences

What this accepts. During an open window, any process running the same executable path, as the same user, can obtain a signature with that key without a prompt. Under PID scoping that was limited to one process.

Why that is tolerable here. The threat model this feature works within already states it "does not claim to protect an unlocked desktop from arbitrary code already running as the same user". A hostile same-UID process that wanted a signature under the old rule could simply execute /usr/bin/ssh-keygen itself and request one in its own right — it would face a prompt, but so would any first request under either rule. The scope change does not hand an attacker a capability they could not otherwise reach; it removes a distinction that cost the user twenty prompts and bought a boundary that a same-UID attacker was never obstructed by.

What genuinely widens. The window is now shared. If the user approves /usr/bin/ssh-keygen for two minutes to sign a rebase, a concurrent hostile invocation of that same binary during those two minutes signs without asking. Under PID scoping it would have prompted. This is a real reduction, and it is the price of the feature working at all.

Mitigations retained. The window defaults to 120 seconds rather than the 900-second maximum; grants are visible in the panel with their remaining time and revocable individually or all at once; and every live grant is destroyed by a lock, a screen lock, or a suspend.

If this proves too wide, the narrower option is to keep program scoping but additionally require that the requesting process's parent match the one that was approved — which would cover Git's per-commit children while excluding unrelated invocations. That was not done here because parent PIDs are as forgeable as any other /proc metadata and would add a check that reads as a security boundary without being one.

Alternatives considered

• Key-only grants for the window. Simplest, and matches what ssh-agent's own confirm timeout does. Rejected as wider than necessary: the program is cheap to match on and excludes unrelated binaries.
• Keep PID scoping and document the limit. Honest, but leaves a button in the UI that almost never does anything, which is its own kind of dishonesty.
• Drop grants from v1. Removes the machinery, but returns the twenty-prompt rebase the design explicitly called unusable.