From ca9a7af7e46fe92bf46645397b6d3ae5b455524a Mon Sep 17 00:00:00 2001
From: redjx <i@redj.ru>
Date: Wed, 25 Feb 2026 16:22:32 +0000
Subject: [PATCH] docs: SSH onboarding through Vault CA

---
 README.md | 102 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 101 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 434539c..c1a1a00 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,103 @@
 # git-ssh-setup
 
-SSH onboarding через Vault CA
\ No newline at end of file
+Автоматическая настройка SSH-доступа к `git.lokeo.ru` через Vault SSH Certificate Authority.
+
+## Как это работает
+
+```
+Сотрудник                    Vault                  Authentik              Forgejo
+    │                          │                       │                     │
+    ├─ vault login (OIDC) ────►├──── redirect ────────►│                     │
+    │◄─── vault token ────────┤◄─── auth ok ──────────┤                     │
+    │                          │                       │                     │
+    ├─ vault write (sign) ────►│                       │                     │
+    │◄─── SSH certificate ────┤                       │                     │
+    │                          │                       │                     │
+    ├─ git push ──────────────────────────────────────────────────────────►│
+    │  (cert auto-verified)    │                       │                     │
+```
+
+- **Vault** подписывает SSH-ключ сотрудника, выдавая сертификат (TTL 1 час)
+- **Forgejo** доверяет CA Vault — проверяет сертификат при SSH-подключении
+- **Authentik** — OIDC-провайдер для авторизации в Vault
+- **Скрипт** автоматически обновляет сертификат при каждом `git push/pull`
+
+## Быстрый старт
+
+### Требования
+
+- [Vault CLI](https://developer.hashicorp.com/vault/install)
+- `jq` (`sudo apt install jq` / `brew install jq`)
+- SSH-ключ ed25519 (скрипт сгенерирует, если нет)
+
+### Установка
+
+```bash
+curl -sL https://git.lokeo.ru/infra/git-ssh-setup/raw/branch/main/setup.sh | bash
+```
+
+Или вручную:
+
+```bash
+git clone https://git.lokeo.ru/infra/git-ssh-setup.git
+cd git-ssh-setup
+bash setup.sh
+```
+
+### Что делает setup.sh
+
+1. Проверяет зависимости (vault, jq, ssh-keygen)
+2. Генерирует SSH-ключ, если отсутствует
+3. Устанавливает `vault-ssh-renew.sh` в `~/.local/bin/`
+4. Настраивает `~/.ssh/config` с автообновлением сертификата
+5. Добавляет `VAULT_ADDR` в shell rc
+6. Выполняет первый OIDC-логин и получает сертификат
+
+### После установки
+
+```bash
+# Клонировать репозиторий
+git clone ssh://git@git.lokeo.ru:222/org/repo.git
+
+# Пушить
+git push origin main
+
+# Сертификат обновляется автоматически
+```
+
+## Ручное использование
+
+```bash
+export VAULT_ADDR=https://vault.lokeo.ru
+
+# Логин через Authentik (откроется браузер)
+vault login -method=oidc role=reader
+
+# Подписать ключ
+vault write -field=signed_key \
+    ssh-client-signer/sign/git-user \
+    public_key=@~/.ssh/id_ed25519.pub \
+    valid_principals="$(vault token lookup -format=json | jq -r '.data.display_name')" \
+    > ~/.ssh/id_ed25519-cert.pub
+
+# Проверить сертификат
+ssh-keygen -Lf ~/.ssh/id_ed25519-cert.pub
+```
+
+## Сроки действия
+
+| Что | TTL |
+|-----|-----|
+| SSH-сертификат | 1 час |
+| Vault token | 8 часов |
+| Обновление | автоматически при git-операции |
+
+## Troubleshooting
+
+**«vault: command not found»** — установи [Vault CLI](https://developer.hashicorp.com/vault/install)
+
+**«OIDC-логин не удался»** — проверь доступность `https://vault.lokeo.ru` и `https://auth.lokeo.ru`
+
+**«Не удалось подписать ключ»** — vault token истёк, выполни `vault login -method=oidc role=reader`
+
+**«Permission denied (publickey)»** — сертификат не совпадает с username в Forgejo. Проверь `valid_principals` в сертификате: `ssh-keygen -Lf ~/.ssh/id_ed25519-cert.pub`