HarperFast / HarperFast/harper-pro

[Epic] SSH deploy-key management: locking, custody, and replication-result correctness

Open
#859 0 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
JavaScript
Stars
3
Forks
0
Avg merge
1d 21h
Merged PRs (30d)
80

Description

SSH deploy-key management (`add_ssh_key` / `update_ssh_key` / `delete_ssh_key` / `get_ssh_key` / `list_ssh_keys`) has accumulated a cluster of correctness defects with no owning epic. Five open issues, all confirmed by code reading and reproduction during the `deep-review` of #594, currently sit unparented and unprioritised. This epic gives them a home.

The common thread across nearly all of them: **`security/sshKeyOperations.ts` mutates node-wide shared state (`ssh/config`, `ssh/known_hosts`, the key files) with no lock, from more than one thread, and reports success regardless of what the peers did.** Fixing the individual symptoms without that serialization will keep producing new ones.

## In scope

- Name reservation and write atomicity for SSH key files (#693)
- Locking and integrity of the node-wide `ssh/config` and `ssh/known_hosts` files, including the unanchored `#name` regex and orphaned config blocks (#722)
- Secret-custody handling for SSH key material across peers with differing custody (#723)
- Ordering of durable writes, replication, and optional network I/O in the mutating operations (#724)
- Recoverability of a server-minted keypair's public half (#694)
- Visibility of `replicateOperation` peer failures in the operation response — today a write that landed on one node and nowhere else still returns `Added ssh key: `
- `cloneNode`'s SSH-key propagation where it consumes these operations

## Out of scope — route elsewhere

- **TLS certificates, CAs, and cert private keys** → [HarperFast/harper#1674 `[Epic] Certificate & key-management hardening`](https://github.com/HarperFast/harper/issues/1674). Both subsystems touch "keys", so route by which module owns the write: `security/sshKeyOperations.ts` and the `ssh/` directory belong here; `security/certificate.ts` and the certificate table belong there.
- **The secret-envelope / custody design itself** (`core/utility/secretEnvelope.ts`, `fileKeyCustody.ts`) beyond how SSH keys consume it. #723 covers the SSH-side consequence; a change to custody distribution is a core concern.
- **The deploy-by-reference feature work** this surfaced from — HarperFast/harper#1849, #1850, #1851, #1876, HarperFast/create-harper#118. This epic is the hardening of what shipped, not the roadmap around it.
- **Generic replication-response semantics.** The "peer failures are invisible in the success message" thread is listed in scope only as it applies to these operations; if it becomes a general ops-API change it belongs in core.

## Children

| Issue | Priority | What |
|---|---|---|
| #722 | P1 | Unlocked cross-thread writes corrupt `ssh/config`; a corrupt config disables every deploy key on the node |
| #723 | P1 | `generate=true` seals against the origin's custody; peers reject it, origin reports success, no plaintext exists anywhere |
| #724 | P1 | Durable writes precede an untimed `api.github.com` fetch, so a concurrent delete leaves a revoked key live on every peer |
| #693 | P2 | TOCTOU between the duplicate-name check and the key write |
| #694 | P3 | A minted `public_key` is unrecoverable if the generating response is lost |

## Note on #570

[#570](https://github.com/HarperFast/harper-pro/issues/570) (`add_ssh_key: server-side keygen via generate: true`) is the feature request these defects came out of. It shipped in #594 (merged 2026-08-20) and `generate` is on `main` today, so it is not a child of this epic — it should be closed as completed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Contributor guide

Open the contributing guide

Research direction

Start with security/sshKeyOperations.ts, the ssh/ directory, and cloneNode's SSH-key propagation; review child issues #722, #723, #724, #693, and #694 first. Trace the mutating operations and their replication responses, then use the reported reproductions to verify that locking, custody, write ordering, recovery, and peer-failure visibility are resolved across the epic.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js, typescript
Domain
backend, distributed-systems, security
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
28/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.