Repository navigation
feat(age): add hello capability negotiation to the age agent - #3634
Conversation
|
I gave it a quick look and this looks great. Let me know when it's ready, then I'll do a proper review. |
a57c830 to
067d4d6
Compare
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>
8797fcf to
0587739
Compare
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>
There was a problem hiding this comment.
This looks like dead code. Should we remove it?
There was a problem hiding this comment.
If it's unused we should remove it.
| 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 |
There was a problem hiding this comment.
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.
| } | ||
| plaintext, err := a.decrypt(ciphertext) | ||
| if err != nil { | ||
| if err.Error() == "agent is locked" { |
There was a problem hiding this comment.
We shouldn't compare error strings. Instead we should use a custom error and compare it with errors.Is.
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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 { |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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{ |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Simplified. The previous version optimized performance by building a lookup table upfront, but it was admittedly a bit complex
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>
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>
Implements Option 2 of #3624: a stateless, voluntary
hellocapability 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