Urządzenia Connection Manager — API v1 i MCP

Moduł Urządzenia zarządza sparowanymi instancjami menedżera połączeń nodea-cm (Connection Manager) — aplikacji desktopowej działającej jako zero-knowledge, szyfrowany end-to-end magazyn połączeń. API pozwala wylistować urządzenia, zmienić ich nazwę oraz je unieważnić. Dokument opisuje warstwę REST API v1 (/api/v1/vault-devices) oraz narzędzia MCP z tego modułu.

Uwierzytelnianie i zakresy (scopes)

API v1 uwierzytelnia się tokenem osobistym Passport przez nagłówek Authorization: Bearer <token>. Poziomy dostępu:

infra:read — listowanie urządzeń.
infra:write — zmiana nazwy urządzenia.
infra:delete — unieważnienie (revoke) urządzenia.

Moduł jest ungated — nie ma flagi Pennant (tak jak web /app/connection-manager). Limit zapytań: throttle:api-v1 = 240/min na użytkownika tokenu.

Zakres tego API vs. desktop

To API obsługuje wyłącznie zarządzanie urządzeniami (lista / nazwa / revoke). Cała logika enrollmentu i kryptografii — synchronizacja sejfu, klucze konta, VMK, recovery blob — należy do klienta desktopowego i jest wystawiona osobno pod /api/vault/* (guard vault, scope vault). API v1 nie modyfikuje stanu kryptograficznego urządzenia.

Własność, adresowanie i bezpieczeństwo

Model VaultDevice nie ma klasy polityki — każde zapytanie jest zawężone do user_id = użytkownik tokenu. Urządzenia adresuje się nieprzezroczystym device_id (UUID), nigdy wewnętrznym kluczem głównym. Cudze, nieznane lub już unieważnione (soft-deleted) urządzenie zwraca 404 (firstOrFail; domyślny scope SoftDeletes ukrywa revoke'owane wiersze).

Bezpieczeństwo: serializowane są wyłącznie nieprzezroczyste metadane. Blobów kryptograficznych — wrapped_vmk oraz device_public_key — NIGDY nie zwraca żadna odpowiedź; stan enrollmentu widoczny jest jedynie jako boolean has_wrapped_vmk.

Revoke (DELETE) odwzorowuje web dokładnie: VaultDevice::revokeAccess() soft-usuwa wiersz ORAZ unieważnia token dostępowy Passport, którym urządzenie ostatnio się uwierzytelniało (wraz z jego tokenami odświeżającymi). Dzięki temu skradzione lub odłączone urządzenie nie może dalej wołać /api/vault/* na jeszcze nieprzeterminowanym tokenie bearer. Operacja jest nieodwracalna — urządzenie trzeba sparować od nowa.

API v1 — endpointy

Metoda	Ścieżka	Scope	Opis
GET	/api/v1/vault-devices	infra:read	Lista sparowanych urządzeń użytkownika (bez paginacji; zbiór ograniczony liczbą fizycznych parowań, najnowsze pierwsze).
PATCH	/api/v1/vault-devices/{device}	infra:write	Zmiana nazwy urządzenia. Kosmetyczna — id, klucze i dostęp bez zmian.
DELETE	/api/v1/vault-devices/{device}	infra:delete	Unieważnienie urządzenia (soft-delete + revokacja tokenów Passport). Zwraca `204`.

Odpowiedź — VaultDeviceResource

Pola: device_id (UUID), name, has_wrapped_vmk (bool — czy urządzenie ukończyło enrollment), last_seen (ISO8601, nullable), created_at (ISO8601). Brak jakichkolwiek pól kryptograficznych.

PATCH — parametry ciała

name (string, wymagany, max 255) — nowa nazwa wyświetlana (jedyne mutowalne pole).

Kody błędów

401 — brak/niepoprawny token.
403 — brak wymaganego scope.
404 — nieznane, cudze lub już unieważnione urządzenie.
422 — walidacja (pusta/zbyt długa nazwa).

Przykłady — API

Lista urządzeń

curl -s https://app.nodea.io/api/v1/vault-devices \
  -H "Authorization: Bearer $NODEA_TOKEN" \
  -H "Accept: application/json"

Zmiana nazwy urządzenia

curl -s -X PATCH https://app.nodea.io/api/v1/vault-devices/9b1f2c3d-... \
  -H "Authorization: Bearer $NODEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "MacBook Pro (praca)" }'

Unieważnienie urządzenia

curl -s -X DELETE https://app.nodea.io/api/v1/vault-devices/9b1f2c3d-... \
  -H "Authorization: Bearer $NODEA_TOKEN" \
  -H "Accept: application/json"

MCP — narzędzia

Narzędzia MCP dzielą model uwierzytelniania i zakresów z API v1 (Bearer + scope sprawdzany w ensureScope). Moduł jest ungated (bez flagi funkcji). Urządzenia adresowane są po device_id (UUID); brakujący, cudzy i już unieważniony identyfikator zwracają ten sam błąd (brak enumeracji między najemcami). Odpowiedzi zawierają wyłącznie metadane — żadnych blobów kryptograficznych.

Narzędzie	Scope	Tryb	Opis
vault-devices-list	infra:read	read-only	Lista sparowanych urządzeń; `page`, `per_page` (max 50). Zwraca device_id/name/has_wrapped_vmk/last_seen/created_at. Urządzenia unieważnione nie są listowane.
vault-device-rename	infra:write	idempotentne	Zmiana nazwy; `device_id`, `name` (max 255). Kosmetyczna — id, klucze i dostęp bez zmian.
vault-device-revoke	infra:delete	destrukcyjne	Unieważnienie; `device_id` + wymagane `confirm: true`. Tokeny API urządzenia zostają natychmiast unieważnione; nieodwracalne (konieczne ponowne parowanie).

Przykład — MCP (JSON-RPC)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "vault-device-rename",
    "arguments": { "device_id": "9b1f2c3d-...uuid", "name": "MacBook Pro (praca)" }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "vault-device-revoke",
    "arguments": { "device_id": "9b1f2c3d-...uuid", "confirm": true }
  }
}

Urządzenia (Connection Manager) — API v1 i MCP | Dokumentacja Nodea