From 3c49827ab4fcd2f092b37f0939ad88b439e400c5 Mon Sep 17 00:00:00 2001
From: Keming He <keminghe.career@gmail.com>
Date: Fri, 6 Feb 2026 14:42:45 -0500
Subject: [PATCH 1/2] feat(ssh-guide): add SSH authentication guide for Git and
 servers

closes #33

CHANGES
- SSH Authentication Guide (new)
  - Full workflow: check keys, generate Ed25519, add to ssh-agent
  - Use Case: Git hosting with URL rewriting (HTTPS URLs, SSH auth)
  - Use Case: Remote servers with ssh-copy-id and SCP file transfer
  - Troubleshooting: permission denied, agent persistence
- CONTRIBUTING.md
  - Add Prerequisites section requiring SSH and GPG setup
  - Bump version to v2.2.0
- SECURITY.md
  - Add Development Security section with CIA triad table
  - Bump version to v1.1.0
- README.md
  - Add SSH to workflows list
- human-guides/README.md
  - Add SSH guide to Use Cases list

IMPACT
- Contributors now required to have SSH and GPG configured
- Security guidance includes development workflow best practices
---
 CONTRIBUTING.md                              |   9 +-
 README.md                                    |   2 +-
 SECURITY.md                                  |  15 +-
 human-guides/README.md                       |   1 +
 human-guides/use-cases-gpg-commit-signing.md |   4 +-
 human-guides/use-cases-ssh-authentication.md | 288 +++++++++++++++++++
 6 files changed, 313 insertions(+), 6 deletions(-)
 create mode 100644 human-guides/use-cases-ssh-authentication.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 598dcfc..af933cc 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,6 +4,13 @@
 
 How to contribute to `common-devx` - adding skills, guides, and templates.
 
+## Prerequisites
+
+Before contributing, ensure you have:
+
+- SSH key configured for GitHub access (see [`use-cases-ssh-authentication.md`](./human-guides/use-cases-ssh-authentication.md))
+- GPG key configured for commit signing (see [`use-cases-gpg-commit-signing.md`](./human-guides/use-cases-gpg-commit-signing.md))
+
 ## Development Model
 
 This repository uses **trunk-based development**:
@@ -105,4 +112,4 @@ Open a [GitHub issue](https://github.com/KemingHe/common-devx/issues).
 
 ---
 
-> Contributing Guide v2.1.0 - KemingHe/common-devx
+> Contributing Guide v2.2.0 - KemingHe/common-devx
diff --git a/README.md b/README.md
index fed6b34..ffa3a33 100644
--- a/README.md
+++ b/README.md
@@ -28,7 +28,7 @@ Available skills: commit messages, issues, PRs, meeting memos, READMEs, and more
 
 Browse [`human-guides/`](./human-guides/README.md) for:
 
-- Git, shell, and GPG workflows (`use-cases-*.md`)
+- Git, shell, SSH, and GPG workflows (`use-cases-*.md`)
 - Diagnostic procedures (`diagnosis-*.md`)
 
 ### For Projects
diff --git a/SECURITY.md b/SECURITY.md
index 260f426..0732829 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,6 +1,6 @@
 # Security Policy
 
-> **Last Updated**: 2026-02-05 by Keming He
+> **Last Updated**: 2026-02-06 by Keming He
 
 Security considerations for using and contributing to common-devx.
 
@@ -25,6 +25,17 @@ When using skills from this repository:
 3. **Check for sensitive data** - Ensure no credentials, secrets, or PII are exposed
 4. **Validate links and paths** - Confirm references point to correct locations
 
+## Development Security
+
+Secure your development workflow with these practices:
+
+| CIA Component | Practice | Guide |
+| :--- | :--- | :--- |
+| **Confidentiality** | SSH key authentication | [`use-cases-ssh-authentication.md`](./human-guides/use-cases-ssh-authentication.md) |
+| **Integrity** | GPG commit signing | [`use-cases-gpg-commit-signing.md`](./human-guides/use-cases-gpg-commit-signing.md) |
+
+These guides apply to any Git-based workflow, not just this repository.
+
 ## Reporting Issues
 
 ### Content Problems
@@ -68,4 +79,4 @@ If you discover a security issue:
 
 ---
 
-> Security Policy v1.0.0 - KemingHe/common-devx
+> Security Policy v1.1.0 - KemingHe/common-devx
diff --git a/human-guides/README.md b/human-guides/README.md
index f53e154..ed9fadd 100644
--- a/human-guides/README.md
+++ b/human-guides/README.md
@@ -26,6 +26,7 @@ New types welcome - use descriptive prefixes that categorize the content.
 - [`use-cases-git.md`](./use-cases-git.md) - Git command-line workflows
 - [`use-cases-shell.md`](./use-cases-shell.md) - Shell operations
 - [`use-cases-gpg-commit-signing.md`](./use-cases-gpg-commit-signing.md) - GPG commit signing
+- [`use-cases-ssh-authentication.md`](./use-cases-ssh-authentication.md) - SSH authentication (Git + servers)
 
 ### Diagnosis
 
diff --git a/human-guides/use-cases-gpg-commit-signing.md b/human-guides/use-cases-gpg-commit-signing.md
index dc070f9..7dd2d36 100644
--- a/human-guides/use-cases-gpg-commit-signing.md
+++ b/human-guides/use-cases-gpg-commit-signing.md
@@ -152,7 +152,7 @@ Copy the entire output, including `-----BEGIN PGP PUBLIC KEY BLOCK-----` and `--
 
 1. Go to [**GitHub Settings**](https://github.com/settings/) > [**SSH and GPG keys**](https://github.com/settings/keys)
 2. Click **New GPG key**
-3. Paste your public key
+3. Title: descriptive name (e.g., "[Color] MacBook Pro [YYYY]")
 4. Click **Add GPG key**
 
 > [↑ Back to Table of Contents](#table-of-contents)
@@ -272,4 +272,4 @@ If the issue persists and you need to commit urgently, see [Skip Signing](#skip-
 
 ---
 
-> Use Cases - GPG Commit Signing v1.0.0 - KemingHe/common-devx
+> Use Cases - GPG Commit Signing v1.0.1 - KemingHe/common-devx
diff --git a/human-guides/use-cases-ssh-authentication.md b/human-guides/use-cases-ssh-authentication.md
new file mode 100644
index 0000000..8f11e9f
--- /dev/null
+++ b/human-guides/use-cases-ssh-authentication.md
@@ -0,0 +1,288 @@
+# Use Cases - SSH Authentication
+
+> **Last Updated**: 2026-02-06 by Keming He
+
+## Platform
+
+> [!IMPORTANT]
+>
+> This guide is for **macOS / Linux** users with POSIX-compatible shell (sh, bash, zsh).
+>
+> For **Windows** users: See [GitHub: Connecting to GitHub with SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh).
+
+Authenticate to Git hosting services and remote servers using SSH keys.
+
+## Table of Contents
+
+- [Use Cases - SSH Authentication](#use-cases---ssh-authentication)
+  - [Platform](#platform)
+  - [Table of Contents](#table-of-contents)
+  - [Why Use SSH Keys?](#why-use-ssh-keys)
+  - [Check for Existing Keys](#check-for-existing-keys)
+  - [Generate New Key](#generate-new-key)
+    - [Generate Key](#generate-key)
+    - [Add to ssh-agent](#add-to-ssh-agent)
+  - [Use Case: Git Hosting](#use-case-git-hosting)
+    - [Copy Public Key](#copy-public-key)
+    - [Add Key to GitHub](#add-key-to-github)
+    - [URL Rewriting](#url-rewriting)
+    - [Test Connection](#test-connection)
+  - [Use Case: Remote Servers](#use-case-remote-servers)
+    - [Add Key to Host](#add-key-to-host)
+    - [Connect](#connect)
+    - [File Transfer (SCP)](#file-transfer-scp)
+  - [Troubleshooting](#troubleshooting)
+    - [Permission Denied](#permission-denied)
+    - [Agent Issues](#agent-issues)
+
+## Why Use SSH Keys?
+
+- **Passwordless auth**: No prompts for git operations or server logins
+- **More secure**: Key-based authentication is stronger than passwords
+- **One setup, multiple uses**: Same key works for Git hosting, servers, and file transfer
+
+> [↑ Back to Table of Contents](#table-of-contents)
+
+---
+
+## Check for Existing Keys
+
+```shell
+ls -la ~/.ssh
+```
+
+Look for files like `id_ed25519` and `id_ed25519.pub` (or `id_rsa`/`id_rsa.pub`). If you have a key pair, you can skip to [Add to ssh-agent](#add-to-ssh-agent).
+
+> [↑ Back to Table of Contents](#table-of-contents)
+
+---
+
+## Generate New Key
+
+### Generate Key
+
+**Ed25519** (recommended - smaller, faster, more secure):
+
+```shell
+ssh-keygen -t ed25519 -C "your-email@example.com"
+```
+
+When prompted:
+
+1. Press **Enter** to accept the default file location (`~/.ssh/id_ed25519`)
+2. Enter a passphrase (optional but recommended)
+
+> [!TIP]
+>
+> **Passphrase adds security** - if your private key is compromised, the attacker still needs the passphrase. The ssh-agent caches it so you don't type it repeatedly.
+
+For legacy systems that don't support Ed25519:
+
+```shell
+ssh-keygen -t rsa -b 4096 -C "your-email@example.com"
+```
+
+### Add to ssh-agent
+
+The ssh-agent caches your key so you don't enter the passphrase repeatedly.
+
+```shell
+# Start agent (usually auto-started on macOS)
+eval "$(ssh-agent -s)"
+
+# Add key
+ssh-add ~/.ssh/id_ed25519
+
+# macOS - Use keychain for persistence across reboots
+ssh-add --apple-use-keychain ~/.ssh/id_ed25519
+
+# macOS - Add to `~/.ssh/config` so keys auto-load:
+# Host *
+#   AddKeysToAgent yes
+#   UseKeychain yes
+#   IdentityFile ~/.ssh/id_ed25519
+```
+
+> [↑ Back to Table of Contents](#table-of-contents)
+
+---
+
+## Use Case: Git Hosting
+
+### Copy Public Key
+
+```shell
+# Display public key (copy the output)
+cat ~/.ssh/id_ed25519.pub
+
+# macOS: copy directly to clipboard
+pbcopy < ~/.ssh/id_ed25519.pub
+```
+
+### Add Key to GitHub
+
+**GitHub**:
+
+1. Go to [**GitHub Settings**](https://github.com/settings/) > [**SSH and GPG keys**](https://github.com/settings/keys)
+2. Click **New SSH key**
+3. Title: descriptive name (e.g., "[Color] MacBook Pro [YYYY]")
+4. Key type: **Authentication Key**
+5. Paste your public key
+6. Click **Add SSH key**
+
+### URL Rewriting
+
+> [!TIP]
+>
+> **Use HTTPS URLs but authenticate via SSH** - clone commands from GitHub's UI work as-is, no manual URL conversion needed.
+
+```shell
+git config --global url."git@github.com:".insteadOf "https://github.com/"
+```
+
+With this config:
+
+```shell
+# This HTTPS URL from GitHub's UI...
+git clone https://github.com/username/repo.git
+
+# ...automatically uses SSH authentication
+# (Git rewrites it to git@github.com:username/repo.git)
+```
+
+### Test Connection
+
+```shell
+ssh -T git@github.com
+```
+
+Expected output:
+
+```shell
+Hi USERNAME! You've successfully authenticated, but GitHub does not provide shell access.
+```
+
+> [↑ Back to Table of Contents](#table-of-contents)
+
+---
+
+## Use Case: Remote Servers
+
+The same SSH key can authenticate to Linux servers, cloud VMs, and any SSH-enabled host.
+
+### Add Key to Host
+
+**Automatic** (recommended):
+
+```shell
+ssh-copy-id user@remote-host
+```
+
+This copies your public key to the remote host's `~/.ssh/authorized_keys`.
+
+**Manual** (if `ssh-copy-id` unavailable):
+
+```shell
+cat ~/.ssh/id_ed25519.pub | ssh user@remote-host "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"
+```
+
+### Connect
+
+```shell
+ssh user@remote-host
+```
+
+With a custom port:
+
+```shell
+ssh -p 2222 user@remote-host
+```
+
+### File Transfer (SCP)
+
+**Upload** file to remote:
+
+```shell
+scp local-file.txt user@remote-host:~/
+```
+
+**Download** file from remote:
+
+```shell
+scp user@remote-host:~/remote-file.txt ./
+```
+
+**Upload directory** (recursive):
+
+```shell
+scp -r local-dir/ user@remote-host:~/
+```
+
+> [↑ Back to Table of Contents](#table-of-contents)
+
+---
+
+## Troubleshooting
+
+### Permission Denied
+
+**Symptom**:
+
+```shell
+Permission denied (publickey).
+```
+
+**Causes and fixes**:
+
+1. **Key not added to target**:
+   - For Git: Check key is in GitHub/GitLab SSH settings
+   - For servers: Check `~/.ssh/authorized_keys` on remote host
+
+2. **Key not in ssh-agent**:
+
+   ```shell
+   ssh-add -l                        # List loaded keys
+   ssh-add ~/.ssh/id_ed25519         # Add if missing
+   ```
+
+3. **Wrong key being used**: Create `~/.ssh/config` to specify key per host:
+
+   ```text
+   Host github.com
+     IdentityFile ~/.ssh/id_ed25519
+   
+   Host work-server
+     HostName 192.168.1.100
+     User admin
+     IdentityFile ~/.ssh/id_work
+   ```
+
+### Agent Issues
+
+**Symptom**: Key not persisting across terminal sessions.
+
+**Fix**:
+
+```shell
+# Restart agent and re-add key
+eval "$(ssh-agent -s)"
+ssh-add ~/.ssh/id_ed25519
+
+# macOS: use keychain for persistence
+ssh-add --apple-use-keychain ~/.ssh/id_ed25519
+```
+
+**Auto-start on shell login**: Add to `~/.bashrc` or `~/.zshrc`:
+
+```shell
+if [ -z "$SSH_AUTH_SOCK" ]; then
+  eval "$(ssh-agent -s)"
+  ssh-add ~/.ssh/id_ed25519
+fi
+```
+
+> [↑ Back to Table of Contents](#table-of-contents)
+
+---
+
+> Use Cases - SSH Authentication v1.0.0 - KemingHe/common-devx

From c05cc68b13fbcb77f7ca47e51d721544ab1bb31c Mon Sep 17 00:00:00 2001
From: Keming He <keminghe.career@gmail.com>
Date: Fri, 6 Feb 2026 14:49:54 -0500
Subject: [PATCH 2/2] fix(guides): complete CIA table and correct GitHub upload
 steps

CHANGES
- SECURITY.md: add Availability row to CIA table (Git version control)
- GPG guide: add missing "paste public key" step in Add to GitHub
- SSH guide: update title example for consistency
---
 SECURITY.md                                  | 1 +
 human-guides/use-cases-gpg-commit-signing.md | 5 +++--
 human-guides/use-cases-ssh-authentication.md | 2 +-
 3 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/SECURITY.md b/SECURITY.md
index 0732829..a7236b8 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -33,6 +33,7 @@ Secure your development workflow with these practices:
 | :--- | :--- | :--- |
 | **Confidentiality** | SSH key authentication | [`use-cases-ssh-authentication.md`](./human-guides/use-cases-ssh-authentication.md) |
 | **Integrity** | GPG commit signing | [`use-cases-gpg-commit-signing.md`](./human-guides/use-cases-gpg-commit-signing.md) |
+| **Availability** | Git version control | [`use-cases-git.md`](./human-guides/use-cases-git.md) |
 
 These guides apply to any Git-based workflow, not just this repository.
 
diff --git a/human-guides/use-cases-gpg-commit-signing.md b/human-guides/use-cases-gpg-commit-signing.md
index 7dd2d36..80b8d52 100644
--- a/human-guides/use-cases-gpg-commit-signing.md
+++ b/human-guides/use-cases-gpg-commit-signing.md
@@ -152,8 +152,9 @@ Copy the entire output, including `-----BEGIN PGP PUBLIC KEY BLOCK-----` and `--
 
 1. Go to [**GitHub Settings**](https://github.com/settings/) > [**SSH and GPG keys**](https://github.com/settings/keys)
 2. Click **New GPG key**
-3. Title: descriptive name (e.g., "[Color] MacBook Pro [YYYY]")
-4. Click **Add GPG key**
+3. Title: descriptive name (e.g., "[Device Name] [YYYY]")
+4. Paste your public key into the **Key** field
+5. Click **Add GPG key**
 
 > [↑ Back to Table of Contents](#table-of-contents)
 
diff --git a/human-guides/use-cases-ssh-authentication.md b/human-guides/use-cases-ssh-authentication.md
index 8f11e9f..0bf7a37 100644
--- a/human-guides/use-cases-ssh-authentication.md
+++ b/human-guides/use-cases-ssh-authentication.md
@@ -125,7 +125,7 @@ pbcopy < ~/.ssh/id_ed25519.pub
 
 1. Go to [**GitHub Settings**](https://github.com/settings/) > [**SSH and GPG keys**](https://github.com/settings/keys)
 2. Click **New SSH key**
-3. Title: descriptive name (e.g., "[Color] MacBook Pro [YYYY]")
+3. Title: descriptive name (e.g., "[Device Name] [YYYY]")
 4. Key type: **Authentication Key**
 5. Paste your public key
 6. Click **Add SSH key**