Update SSH Agent deep dive with architecture of v2#828
Conversation
Deploying contributing-docs with
|
| Latest commit: |
f11e692
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://3813f4bd.contributing-docs.pages.dev |
| Branch Preview URL: | https://dn-pm-32892-update-ssh-agent.contributing-docs.pages.dev |
🤖 Bitwarden Claude Code ReviewOverall Assessment: APPROVE Reviewed this documentation-only PR that adds a new SSH Agent v2 architecture deep dive, restructures the Code Review Details
|
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| from the vault and sent to the agent. The agent server is started and it’s keystore populated with | ||
| the new keys. | ||
|
|
||
| The Bitwarden SSH Agent server spawns a thread to handle any each new client connection. Each |
There was a problem hiding this comment.
🎨 SUGGESTED: A few grammar typos in the new prose worth cleaning up.
Details
- Line 22: "it's keystore" → "its keystore" (possessive)
- Line 25: "spawns a thread to handle any each new client connection" → "spawns a thread to handle each new client connection"
- Line 76: "is a the orchestrator" → "is the orchestrator"
- Line 106: "based on it's authorization policy" → "based on its authorization policy"
These are not caught by spellcheck since each word is individually valid.
| # SSH Keys and SSH Agent | ||
|
|
||
| This section contains pages that build an understanding of what SSH keys are, what an SSH Agent is, | ||
| and how the Bitwarden SSH Agent is architected and implemented. |
There was a problem hiding this comment.
❓ QUESTION: The sidebar for this section is autogenerated and ordered alphabetically, so pages will appear as bitwarden-ssh-agent-architecture → what-are-ssh-keys → what-is-an-ssh-agent. That surfaces the advanced architecture doc before the introductory pages, which inverts the "keys → agent → architecture" progression this index describes. Was that ordering intentional, or would sidebar_position frontmatter help present them in reading order?
withinfocus
left a comment
withinfocus
left a comment
There was a problem hiding this comment.
I wasn't able to see this until now but it seems we have not gotten the word out sufficiently on where documentation should go -- see https://bitwarden.atlassian.net/wiki/spaces/EN/pages/1774977070/Documentation+Patterns. There is essentially a moratorium on expanding these deep dive pages and they should exist "close to code" so that they can aid other engineers and AI more directly. This being in GitHub will also empower you to render your diagrams natively.
I don't know how heavily linked this is, but the page(s) should leave entirely or be more of a launch point, and deep dives that do remain are more of a necessary evil when the spread of a feature goes beyond a single repo.
| @@ -0,0 +1,4 @@ | |||
| # SSH Keys and SSH Agent | |||
|
|
|||
| This section contains pages that build an understanding of what SSH keys are, what an SSH Agent is, | |||
There was a problem hiding this comment.
⛏️ Please remove all the "this section" language -- it's implied. Go right into the content.
| @@ -0,0 +1,188 @@ | |||
| # Bitwarden SSH Agent architecture | |||
There was a problem hiding this comment.
❓ Per my other comments, why can't this just be one SSH agent architecture page? I don't think we need the reorganization and it would be prudent to go the other way and be simpler.
| ::: | ||
|
|
||
| ## What are SSH Keys? | ||
| # What are SSH keys? |
There was a problem hiding this comment.
❌ Explaining what an SSH key is, briefly, was acceptable as preamble to the prior main content but ... does not need to be something we explain ourselves. You can get rid of key and agent explanation.
| @@ -0,0 +1,188 @@ | |||
| # Bitwarden SSH Agent architecture | |||
|
|
|||
|  | |||
There was a problem hiding this comment.
❌ We use Mermaid for all documentation diagrams (via code) now.
3 participants
🎟️ Tracking
https://bitwarden.atlassian.net/browse/PM-32892
📔 Objective
With the v2 of the SSH Agent, we completely re-architected it to be our own native solution and not depend on bitwarden-russh fork.
The existing deep dive on the subject is mostly generalized background information for on SSH key and agent mechanics.
This change preserves those pages and adds a new architecture doc for the v2 of the agent, complete with detailed architecture diagrams.