Skip to content

feat: implement asset sorting and persistence in AssetView - #437

Merged
nyakang merged 5 commits into
nyakang:mainfrom
litcc:feat/agent-forward-config
Aug 14, 2026
Merged

feat: implement asset sorting and persistence in AssetView#437
nyakang merged 5 commits into
nyakang:mainfrom
litcc:feat/agent-forward-config

Conversation

@litcc

@litcc litcc commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

Summary

This PR adds configurable SSH Agent authentication and Agent forwarding
support to NyaTerm.

The SSH Agent endpoint used for login authentication is fully decoupled
from Agent forwarding. Agent forwarding now supports multiple external
SSH Agents and can combine them with NyaTerm's saved private keys. The
identities exposed to remote processes are controlled by a unified
fingerprint allowlist or an explicit AllowAll policy.

Background

Previously, SSH Agent authentication and forwarding shared a single
endpoint, which did not support the following use cases:

  • Configuring multiple local Agent endpoints;
  • Using a primary SSH Agent together with a GPG Agent's SSH-compatible
    socket;
  • Forwarding private keys saved in NyaTerm;
  • Applying one fingerprint allowlist to both external Agent identities
    and saved private keys;
  • Using hardware-backed keys while selectively authorizing saved private
    keys.

Main Changes

SSH Agent Configuration

  • Add an optional auth_agent_endpoint for SSH Agent login
    authentication.
  • Add an independent agent_forwarding_config for Agent forwarding.
  • Support the following endpoint types:
    • Automatic platform detection;
    • Environment variables;
    • Unix domain sockets;
    • Windows Pageant;
    • Windows OpenSSH Agent.
  • Login authentication can use only one Agent endpoint.
  • Agent forwarding supports multiple external Agent endpoints with an
    explicit ordering.

Agent Forwarding Sources and Policies

Agent forwarding supports the following sources:

  • External SSH Agent endpoints;
  • Private keys saved in NyaTerm;
  • Both source types together.

Both source types use the same identity policy:

  • Fingerprint allowlist;
  • AllowAll.

Security behavior:

  • Agent forwarding is disabled by default;
  • An empty allowlist exposes no identities to remote processes;
  • Switching to AllowAll requires explicit risk confirmation;
  • Private key material is never sent to remote servers;
  • Hardware-backed keys remain managed by the external Agent. NyaTerm
    communicates with them only through the SSH Agent protocol.

Agent Broker

Add an SSH Agent forwarding broker responsible for:

  • Merging identities from multiple external Agents and NyaTerm's saved
    private keys;
  • Deduplicating identities by SSH public-key blob;
  • Applying fingerprint policies before exposing identities;
  • Routing signing requests to the correct identity provider;
  • Supporting RSA, ECDSA, Ed25519, and certificate-based signing for
    saved private keys;
  • Isolating unavailable external Agent endpoints;
  • Returning endpoint-specific errors to the frontend;
  • Preserving deterministic endpoint and identity ordering;
  • Limiting Agent frame size, identity count, channel count, and signing
    concurrency;
  • Enforcing first-frame, idle, identity enumeration, and signing
    timeouts;
  • Invalidating cached identities when saved keys change;
  • Rejecting unsupported or unsafe Agent protocol requests.

To preserve extension behavior for external Agents, raw protocol relay is
used only when all of the following conditions are met:

  • Exactly one external Agent endpoint is configured;
  • NyaTerm saved-key forwarding is disabled;
  • The policy is AllowAll.

All other configurations use the Agent Broker so that identity filtering
and signing routing can be enforced.

Runtime Behavior

  • When forwarding is disabled, NyaTerm does not create a local
    forwarding Agent connection and does not send an auth-agent-req
    request to the server.
  • SSH Agent login authentication and Agent forwarding are independent.
  • ProxyJump hosts do not implicitly enable Agent forwarding.
  • Tunnel and SFTP connections do not implicitly create Agent forwarding
    channels.
  • Forwarding configuration is applied only to the final interactive SSH
    target.

Configuration Migration

Existing configurations remain readable and are migrated in one
direction:

  • agent_endpointauth_agent_endpoint;
  • agent_forwardingagent_forwarding_config.

An existing agent_forwarding: true value is migrated to:

  • Forwarding enabled;
  • The legacy external Agent endpoint;
  • The AllowAll policy;
  • NyaTerm saved-key forwarding disabled.

Legacy fields are not serialized again after migration. No additional
V1/V2 dual-model configuration is introduced.

UI and IPC

  • Configure the login Agent endpoint separately in the authentication
    section.
  • Add forwarding source toggles.
  • Add, remove, and reorder multiple forwarding endpoints.
  • Display endpoint types supported by the current platform.
  • Add a fingerprint-based identity selector.
  • Display endpoint errors and identity truncation warnings.
  • Show a risk confirmation dialog when switching to AllowAll.
  • Add English, Simplified Chinese, Traditional Chinese, and Korean
    translations.
  • Add the get_ssh_agent_forwarding_identities Tauri command.
  • Return only fingerprints, comments, source information, and endpoint
    errors from identity preview IPC; private key material is never
    returned.

Persistence and Synchronization

  • Update connection importers and connection serialization logic.
  • Treat Agent endpoint and forwarding configuration as device-local
    configuration.
  • Remove Agent endpoints unsupported by the target platform when
    restoring a cross-platform backup.
  • Preserve NyaTerm's existing encryption-at-rest policy for saved private
    keys.
  • Update portable snapshot and storage-related tests.

Documentation

Update the SSH connection documentation to explain:

  • The difference between login authentication and Agent forwarding;
  • Multiple Agent endpoint configuration;
  • External Agent and saved-key sources;
  • Fingerprint allowlists and AllowAll;
  • Agent protocol restrictions;
  • Device-local configuration rules;
  • Cross-platform backup behavior;
  • Agent forwarding security risks.

Validation

The following validation has been performed:

  • Agent Broker protocol, identity merging, signing routing, timeout,
    limit, and fault-isolation tests;
  • SSH Agent configuration, endpoint validation, and legacy migration
    tests;
  • Connection command validation tests;
  • Portable snapshot tests;
  • cargo check --all-targets;
  • pnpm lint;
  • pnpm i18n:check;
  • pnpm build;
  • Real-world testing on macOS arm64 and Windows arm64, including Windows
    OpenSSH Agent authentication and NyaTerm saved private-key
    authentication.

Known Issue

The Windows arm64 test environment is a local, non-domain Windows
account. As a result, the Pageant integration test currently fails in
the vendored Pageant transport implementation.

The relevant dependencies are vendored, so this PR does not make
unrelated upstream library changes. The issue is being tracked
separately:

The Pageant issue is independent of the SSH Agent forwarding
architecture implemented in this PR.

litcc added 5 commits August 13, 2026 17:27
- decouple authentication endpoints from forwarding configuration
- support multiple external Agent endpoints and NyaTerm stored keys
- add shared fingerprint allowlist and AllowAll policies
- add Agent broker with protocol limits, signing controls, timeouts, and key-change invalidation
- migrate legacy Agent forwarding settings
- update runtime IPC, import/snapshot handling, UI, i18n, documentation, tests
…config

# Conflicts:
#	src-tauri/src/cmd/connection.rs
#	src-tauri/src/config/connection.rs
#	src-tauri/src/config/mod.rs
…config

# Conflicts:
#	src-tauri/src/core/portable_snapshot/tests.rs
Repository owner deleted a comment from gitguardian Bot Aug 14, 2026
@nyakang
nyakang merged commit 4874176 into nyakang:main Aug 14, 2026
1 check passed
@litcc
litcc deleted the feat/agent-forward-config branch August 20, 2026 15:04
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.

2 participants