Skip to content

feat(age): add hello capability negotiation to the age agent - #3634

Merged
dominikschulz merged 5 commits into
gopasspw:masterfrom
yzx9:age-agent-hello
Oct 7, 2026
Merged

dominikschulz merged 5 commits into
gopasspw:masterfrom
yzx9:age-agent-hello

Conversation

@yzx9

@yzx9 yzx9 commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Implements Option 2 of #3624: a stateless, voluntary hello capability exchange for the age agent protocol.

Compatibility follows the issue's fallback contract: a pre-hello (legacy) agent returns ERR, and clients determine legacy behavior solely from the existence of the error rather than its content. As a result, old and new agents and clients continue to interoperate unchanged.

Closes #3624

@dominikschulz

Copy link
Copy Markdown
Member

I gave it a quick look and this looks great. Let me know when it's ready, then I'll do a proper review.

@yzx9
yzx9 force-pushed the age-agent-hello branch 8 times, most recently from a57c830 to 067d4d6 Compare October 7, 2026 02:05
Internal packages cannot import the ldflags-injected version variable
from package main, and runtime/debug build info cannot serve as a
substitute: its Main.Version is "(devel)" in release builds and the main
module never appears in Deps, so debug.ModuleVersion only resolves
dependency versions reliably. main stashes the version in the exported
Version variable at startup; an empty value means unknown (test builds,
library embedders). ModuleVersion() wraps the lookup: the stash is
authoritative, the build-info module version is a fallback.

The first consumer (the age agent hello version token) follows in the
next commit.

Assisted-by: Claude-Code:GLM-5.3

Signed-off-by: Zexin Yuan <git@yzx9.xyz>
@yzx9
yzx9 force-pushed the age-agent-hello branch 2 times, most recently from 8797fcf to 0587739 Compare October 7, 2026 06:14
Strings echoed to the terminal from untrusted origins - concretely the
age agent's hello payload, which comes from whatever process owns the
agent socket, a third party the protocol explicitly welcomes - would
reach fmt's %s verbatim: control characters are not filtered, so ESC/OSC
sequences could drive the terminal, and a hostile payload can be
arbitrarily large (the response line limit is 16 MiB).

Add two orthogonal fmt.Stringer wrappers to internal/out so every sink
(terminals, debug logs, anything else that formats) renders them safely
with zero plumbing in the print functions: Untrusted strips C0/C1
control characters, neutralizing escape sequences into inert text;
Truncated bounds the rendered length at a rune boundary, shaped after
io.LimitedReader and composable over any Stringer. Untrusted accepts a
bare string on purpose: stripping is only semantically safe on raw
bytes - a legitimate Stringer may intentionally emit ANSI - so the types
keep the two operations in their safe domains.

Assisted-by: Claude-Code:GLM-5.3

Signed-off-by: Zexin Yuan <git@yzx9.xyz>
@yzx9
yzx9 force-pushed the age-agent-hello branch from 0587739 to 5c5440f Compare October 7, 2026 06:14

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks like dead code. Should we remove it?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If it's unused we should remove it.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

@yzx9
yzx9 force-pushed the age-agent-hello branch from 5c5440f to e34efd7 Compare October 7, 2026 06:28
@yzx9
yzx9 marked this pull request as ready for review October 7, 2026 06:28

@dominikschulz dominikschulz left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! 👍

Comment thread docs/backends/age-agent-protocol.md Outdated
currently opens a fresh connection per command (with one exception: it
fetches `status` and `hello` over a single connection), but clients are
free to reuse connections.
- The maximum request line length is 16 MiB: the `decrypt` command carries

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this mean the effective upper limit for age encrypted secrets (using the agent) is 12 MB?

That should be fine for most use-cases, but I think there might be some edge cases that exceed this limit.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was designed to be configurable

> hello
< OK <capbilities> maxline=16777216 version=1.19.0
                   ^
                   16,777,216 bytes = 16 mb

We currently use 16 MB (#3529). As discussed in #3508, for edge cases that may exceed this limit, we should implement a chunked API

}
plaintext, err := a.decrypt(ciphertext)
if err != nil {
if err.Error() == "agent is locked" {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We shouldn't compare error strings. Instead we should use a custom error and compare it with errors.Is.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got it. One more issue: a lot of the codebase still relies on those string literals, since checks on both sides of the agent detect them directly. If needed, I can open a follow-up PR to clean up those agent-related strings

https://github.com/search?q=repo%3Agopasspw%2Fgopass+%22agent+is+locked%22&type=code

https://github.com/search?q=repo%3Agopasspw%2Fgopass+%22agent+is+stopped%22&type=code

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed. If you want to follow up on this that would be fantastic. But don't feel obliged.

if err != nil {
if err.Error() == "agent is locked" {
fmt.Fprintln(conn, "ERR agent is locked")
} else {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using else in Go is not idiomatic. Sometimes it's necessary, but I prefer to return early if possible. In this case that will actually add one or two lines, but I think it's still more readable:

if err != nil {
  if errors.Is(err, ErrAgentLocked) {
    fmt.Println ...
    return true
   }
   fmt.Println(ERR failed to decrypt ...)
  return true
}
return true

Note: The second-to-last return true is not strictly necessary but it guards against mistakes when modifying this later.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If it's unused we should remove it.


// agentHandlers maps the advertised wire commands to their
// implementations. The hello capability list is DERIVED from these keys.
var agentHandlers = map[string]agentHandler{

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The way you are setting up the map and calling the handlers is uncommon. I guess it will work, but is there are reason why you can't make the capabilities() method and member of the Agent struct and return the concrete instance methods from there?

If there is a good reason to keep it as-is, I'm fine. But if it can be simplified I'd prefer that.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplified. The previous version optimized performance by building a lookup table upfront, but it was admittedly a bit complex

@yzx9
yzx9 force-pushed the age-agent-hello branch from e34efd7 to 4ffa6e2 Compare October 7, 2026 14:45
Client.Remove had a client-side implementation since the agent's
introduction, but the agent never implemented the remove command and no
caller ever invoked the method. Delete it rather than keep the illusion
of a supported command.

Assisted-by: Claude-Code:GLM-5.3

Signed-off-by: Zexin Yuan <git@yzx9.xyz>
@yzx9
yzx9 force-pushed the age-agent-hello branch from 4ffa6e2 to 494d320 Compare October 7, 2026 15:03
yzx9 added 2 commits October 7, 2026 23:14
Implements a stateless, voluntary hello exchange: the agent advertises
its capability set, and pre-hello agents keep working unchanged.

- agent: dispatch via a handler table of bound methods returned by an
  Agent method; dispatch and the advertised capability list derive from
  the same table, so they cannot drift apart. Adds the hello command
  (command tokens + maxline + diagnostic version tokens). The session
  and ssh-identity commands dispatch through the same table and are
  advertised like every other command.
- client: Capabilities() performs the handshake; ANY error (connection
  failure or an ERR from a pre-hello agent) means legacy and callers keep
  the pre-hello behaviour - judged by the error's existence, never its
  text. Response reads are bounded by the agent's own line limit,
  duplicate tokens resolve first-wins, and Info() fetches status and
  capabilities over a single connection.
- gopass age agent status: extracted to a testable method, now reports
  the agent version and capabilities (or a legacy note), with
  agent-supplied strings stripped of terminal control characters before
  display.
- tryStartAgent: logs agent capabilities behind the existing
  debug.IsEnabled() gate so the hot path pays no round trip unless
  debugging.
- version sourcing: the hello version token and the client hello
  argument read internal/buildinfo.ModuleVersion.
- changelog: record the capability negotiation under Unreleased.

Invariants frozen by tests: unknown commands yield a single-line ERR,
change no state and do not close the connection.

Assisted-by: Claude-Code:GLM-5.3

Signed-off-by: Zexin Yuan <git@yzx9.xyz>
Adds a complete specification of the agent's line protocol as its own
document (docs/backends/age-agent-protocol.md): transport and framing,
socket location rules per platform, per-command syntax, responses and
errors, the lock state model including auto-lock semantics, the
error-handling contract (judge by ERR presence, never by text), the
hello capability exchange with its legacy-detection rule, and an example
session. The token grammar and the client version argument may still
change. age.md keeps a short overview and links to the specification.

Assisted-by: Claude-Code:GLM-5.3

Signed-off-by: Zexin Yuan <git@yzx9.xyz>
@yzx9
yzx9 force-pushed the age-agent-hello branch from 494d320 to 7f6e382 Compare October 7, 2026 15:17
@dominikschulz
dominikschulz merged commit a8505c6 into gopasspw:master Oct 7, 2026
10 checks passed
@yzx9
yzx9 deleted the age-agent-hello branch October 8, 2026 03:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[RFC] age: define agent protocol capability negotiation

2 participants

⌂ 换网址