BuildOnAI Key Server

Przegląd

Serwis HTTP, który robi dwie rzeczy:

1. Weryfikuje podpisane ed25519 zapytania. Wywołujący podpisuje (method, path, timestamp, nonce, body-hash) swoim kluczem prywatnym. Serwer trzyma odpowiadający klucz publiczny w pliku i odpowiada { valid: true | false }. Bezstanowo. Bez session store. Bez wystawiania tokenów. Bez zarządzania wygasaniem.
2. Wydaje sekrety na żądanie. Prywatne klucze SSH dla deployu/pushu, tokeny API dla wywołań wychodzących. Lista dozwolonych IP jako pierwsza brama; w trybie AUTH_MODE=enforce dochodzi podpis ed25519.

Zaprojektowany jako sidecar dla Consciousness Server i Cortex, ale działa samodzielnie dla każdego serwisu HTTP, który chce uwierzytelniania na bazie klucza bez stawiania Vaulta, OAuth czy issuera JWT.

Instalacja

git clone https://github.com/build-on-ai/buildonai-key-server.git
cd buildonai-key-server
cp auth/allowed-clients.json.example auth/allowed-clients.json
# edytuj auth/allowed-clients.json: dodaj IP klientów którzy będą się łączyć
docker compose up -d
curl http://localhost:3040/health

Rejestracja agenta (ed25519)

# Na hoście agenta:
ssh-keygen -t ed25519 -C "agent1@$(hostname)" \
  -f ~/.ssh/buildonai-agent1 -N ""

# Skopiuj klucz PUBLICZNY na hosta key-server:
scp ~/.ssh/buildonai-agent1.pub \
    operator@key-server-host:/opt/buildonai-key-server/keys/agents/agent1.pub

# Sprawdź czy serwer go widzi:
curl http://key-server-host:3040/api/agents/identity
# {"agents": ["agent1"]}

Klucz prywatny zostaje na hoście agenta. Nigdy go nie opuszcza. Odwołanie to rm keys/agents/agent1.pub — działa natychmiast, nie ma cache.

Pojęcia

Wiadomość kanoniczna

Agent, gated service i key-server muszą zrekonstruować te same bajty żeby podpisać i zweryfikować. Pięć pól łączonych literalnym \n (LF):

<METHOD>\n<PATH>\n<X-Timestamp>\n<X-Nonce>\nSHA256(body)

SHA256(body) jest hex-encoded. PATH to ścieżka requesta bez query string. Dla GET bez body, SHA256("") = e3b0c442...52b855.

Weryfikacja podpisanego zapytania

Gated service (Consciousness Server, Twoje API, Twój odbiorca webhooków) wyciąga cztery nagłówki + body hash z przychodzącego requesta i POST-uje je do /api/verify:

# Gated service przesyła headery agenta + body hash do /api/verify.
curl -s -X POST http://key-server-host:3040/api/verify \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "agent1",
    "method": "POST",
    "path": "/api/notes/create",
    "timestamp": "2026-05-31T10:00:00Z",
    "nonce": "a7b3c1d9e2f64a18b3c1d9e2f64a18b3",
    "signature": "base64-ed25519-sig-tutaj",
    "body_sha256": "e3b0c44298fc1c149afbf4c8996fb924..."
  }'
# {"valid": true}

Anti-replay

• Okno timestampu: now-300s do now+60s. Poza → odrzucone.
• Cache nonce'ów: każdy X-Nonce akceptowany najwyżej raz na 5 minut (Redis SET NX EX 300).
• Powiązanie z body: wiadomość kanoniczna zawiera SHA256(body) — przechwycony request nie da się odtworzyć z innym endpointem czy zmienionym body.

Układ vaulta

Układ na dysku pod keys/ jest celowo prosty — ls pokazuje co tam jest. Per-agent klucze publiczne ed25519 leżą w keys/agents/<AGENT>.pub. Klucze prywatne SSH w keys/ssh/<name>; tokeny API w keys/<service>/api-key.txt. chmod 600 na prywatne materiały.

Log audytu

Każde zapytanie — verify, vault read, sukces lub porażka — dodaje jedną linię do logs/audit.log plus wpis JSONL do logs/audit.jsonl. Self-rotation co 50 MB.

[2026-05-31T08:00:01Z] IP=10.0.0.20 ENDPOINT=/api/verify RESULT=VALID agent=agent1
[2026-05-31T08:00:03Z] IP=10.0.0.30 ENDPOINT=/api/verify RESULT=VALID agent=agent2
[2026-05-31T08:00:18Z] IP=10.0.0.30 ENDPOINT=/api/verify RESULT=INVALID reason=nonce_replayed
[2026-05-31T14:22:05Z] IP=10.0.0.99 ENDPOINT=/keys/ssh/git-deploy RESULT=FORBIDDEN IP_not_whitelisted
[2026-05-31T14:22:18Z] IP=10.0.0.20 ENDPOINT=/keys/ssh/../etc/passwd RESULT=REJECTED path_traversal_attempt

API

Siedem endpointów. Cała powierzchnia.

Model zagrożeń

Broni przed

• Replayem w tej samej sieci LAN — nonce + okno timestampu.
• Sfałszowanym pochodzeniem z obcego hosta — lista dozwolonych IP jako warstwa pierwsza.
• Przechwyconym-i-zreplayowanym pod innym endpointem — wiadomość kanoniczna wiąże method + path + body hash.
• Skompromitowanym agentem którego klucz prywatny jest w rękach atakującego — rm keys/agents/<AGENT>.pub na weryfikatorze. Działa natychmiast, bez cache.
• Przypadkowym commitem sekretów — dostarczany .gitignore wyklucza keys/, logs/ i prawdziwy auth/allowed-clients.json.

Nie broni przed (celowy zakres)

• Podsłuchem treści requesta w sieci. ed25519 to schemat podpisu, nie szyfrowanie. Owiń za TLS (Caddy, nginx) jeśli requesty przenoszą wrażliwe payloady.
• Atakującym z rootem na hoście. Może czytać klucze prywatne, vault kluczy publicznych i log audytu bezpośrednio z dysku.
• Wysokowolumenowym DoS-em na /api/verify. Serwer nie rate-limituje niczego; postaw go za reverse proxy jeśli niezaufani wywołujący mogą do niego dojść.

Dalsze kroki

• Consciousness Server →
• Zobacz na GitHub
• Profil bezpieczeństwa (SECURITY.md, EN) →
• Pełen protokół podpisywania →
• Operator guide AUTH_MODE →