Security, Hardware Keys & Smartcards

Security and cryptographic isolation form the foundation of sshs3. The application is engineered around the principles of Zero Private Key Extraction, strict memory sandboxing, and Zero Trust identity verification.

1. Zero Private Key Extraction Architecture

A critical security principle of sshs3 is that private cryptographic keys are never extracted, loaded, or exposed inside JavaScript, Node.js, or Chromium heaps:

2. Visual Touch-Presence Banner

Authenticating with a FIDO2 hardware token (ed25519-sk, ecdsa-sk) requires physical user presence:

┌────────────────────────────────────────────────────────────────────────┐
│ 🔑 Touch your security key to authenticate...                          │
└────────────────────────────────────────────────────────────────────────┘

In standard command-line tools, terminal sessions appear to hang while the user is unaware that a security key is flashing under their desk. sshs3 detects OpenSSH user presence events in real time and illuminates an animated banner the exact millisecond user touch is requested, dismissing it immediately once presence is registered.

Technical Internals: Stderr Pattern Matching & IPC Dispatch

SSHPtyManager and OpenSshSftpProcess inspect process stderr streams in real time for OpenSSH prompt markers: Confirm user presence for key... Upon detection, an IPC_CHANNELS.PRESENCE_PROMPT event dispatches to React to mount the visual touch banner. Once the signature completes or OpenSSH exits, IPC_CHANNELS.PRESENCE_CLEAR dismisses the banner automatically.

3. Ephemeral PIN Caching Policies & AppAgent

To protect smartcards and PIN-protected hardware keys against unauthorized physical access while preventing user fatigue, sshs3 provides three distinct policies under Settings → Security & Smartcard:

Global (App Lifetime) & External Terminal Superpowers

Under Global PIN caching, sshs3 unlocks seamless Single Sign-On:

• Stable Socket: The agent listens on a dedicated Unix socket ($XDG_RUNTIME_DIR/sshs3/agent.sock with 0700 permissions).
• Lock / Unlock Action: Click Lock All Now in the top toolbar to flush all loaded keys immediately (ssh-add -D). Click Unlock Now to reload keys upon PIN entry.
• FIDO2 verify-required PIN Caching: For FIDO2 keys requiring PIN + touch per signature, the PIN entered during unlock is cached in process memory (never on disk) so subsequent connections only require a physical touch. If a touch signature fails, the cached PIN is invalidated immediately to prevent authenticator lockouts.
• Local Shells & External CLI: External terminal windows, VS Code, and local tabs automatically receive the SSH_AUTH_SOCK environment variable. Furthermore, sshs3 injects a temporary local-only block into your ~/.ssh/config:

# BEGIN sshs3-agent (local only -- regenerated by sshs3 while cards are unlocked, never synced)
  Host prod-db
      IdentityAgent /run/user/1000/sshs3/agent.sock
      IdentityFile <public key file of the unlocked card>
      IdentitiesOnly yes
      PKCS11Provider none
  # END sshs3-agent

When sshs3 shuts down, the block is cleaned up and the socket destroyed.

Card or Key Not Plugged In

sshs3 checks that the smartcard or security key is present before it asks for a PIN. Unlock at startup stays silent when nothing is plugged in. When a terminal, an SFTP connection, Remote Profile Sync or a Team Vault needs the token, an Insert your smartcard / security key dialog waits for it and gives way to the PIN dialog as soon as the token is detected. Cancel (or Esc) stops the operation without asking for a PIN.

PIN caching is strictly memory-only and is wiped on reboot or application exit. If the application crashes, stale sockets are cleaned up automatically on the next launch.

Security Architecture: Slot Separation (Authentication 9A vs. Signing 9C)

PIV smartcards typically expose multiple slots: an authentication slot (9A) and a digital signature slot (9C). Standard OpenSSH ssh-add -s loads all exposed slots indiscriminately. sshs3 inspects the card's X.509 certificates first:

• Only certificates bearing the digitalSignature Key Usage and clientAuth Extended Key Usage are offered for SSH authentication.
• Dedicated signing keys (with nonRepudiation) are excluded and removed from the active agent to prevent accidental key exposure during SSH handshakes.

Technical Architecture: Secure PIN Delivery via AskpassServer

AskpassServer (src/main/smartcard/AskpassServer.ts) runs an isolated Unix domain socket with strict 0700 filesystem permissions. When OpenSSH executes with SSH_ASKPASS_REQUIRE=force, helper scripts communicate directly with AskpassServer using process memory IPC. Plaintext PINs are never written to disk or configuration files.

4. Troubleshooting & Diagnostics