Dane uwierzytelniające (Credentials)
Moduł credentials pozwala operatorowi raz zdefiniować konfigurację danych uwierzytelniających
i odwoływać się do niej z wielu miejsc. Zamiast wpisywać ten sam klucz API w ustawieniach asystenta
AI, mechanizmu wektoryzacji wyszukiwarki i newslettera, tworzysz jedną konfigurację Primary LLM i
wskazujesz ją w każdym z tych ustawień. Zmieniasz klucz raz — każde miejsce, które z niego korzysta,
dostaje nową wartość bez dalszych zmian.
Pola z sekretami (klucze API, hasła) są szyfrowane w bazie, na granicy API dostępne tylko do zapisu (nigdy nie są zwracane jawnym tekstem), maskowane przy każdym odczycie i ukrywane w dzienniku audytu. Każde utworzenie, zmiana i usunięcie jest audytowane przez Command Bus.
Dla właścicieli produktu i operatorów
Czym jest konfiguracja danych uwierzytelniających
Konfiguracja to nazwana instancja typu konfiguracji, z własnym kodem. Od razu dostępne są dwa typy:
- LLM — dostawcy GPT (OpenAI), Gemini (Google), Claude (Anthropic), DeepSeek i
OpenAI-compatible (custom endpoint) — dowolny punkt końcowy zgodny z OpenAI. Pola: API Key
(sekret, wymagane), Model (wymagane), Base URL (opcjonalne; wymagane dla dostawcy
zgodnego z OpenAI). Base URL musi być bezwzględnym adresem
http://albohttps://— każda inna wartość jest odrzucana przy zapisie. To główny adres API, pod który trafia żądanie (<Base URL>/chat/completions), np.https://api.deepseek.com,https://openrouter.ai/api/v1albo samodzielnie hostowanyhttp://localhost:11434/v1. Jest używany w konfiguracjach OpenAI, DeepSeek i zgodnych z OpenAI (gdy jest pusty — publiczny adres OpenAI albohttps://api.deepseek.com); Anthropic i Google zawsze używają swoich publicznych adresów. - Email adapter — dostawcy SMTP, Amazon SES i SendGrid. Każdy dostawca ma własny
zestaw pól z dokładnie jednym sekretem (SMTP
password, SESsecretAccessKey, SendGridapiKey).
Inne moduły dodają własne typy, gdy są włączone — na przykład dane dostępowe rejestru GUS REGON
modułu organizations i miejsca dostarczania feedów modułu product_feeds.
Wybrany typ i dostawca decydują, jakie pola pokazuje formularz.
Tworzenie konfiguracji
- Otwórz Credentials na pasku bocznym panelu (widoczne z uprawnieniem
credentials:read). - Kliknij New configuration.
- Wybierz Type (np. LLM) i Provider (np. Claude). Formularz pokaże pola tego dostawcy.
- Wypełnij Name (np.
Primary LLM) i Code (stały identyfikator, np.primary-llm— do niego odwołują się ustawienia), a potem pozostałe pola (API Key, Model, …). - Kliknij Save. Konfiguracja pojawia się na liście; każdy sekret jest pokazywany jako set — nigdy jako wartość.
Edycja działa tak samo. Przy edycji typ i dostawca są zablokowane (nie można ich zmienić — utwórz nową konfigurację). Pozostawienie pustego pola sekretu zachowuje zapisany sekret; wpisanie nowej wartości go zastępuje.
Wyjątkiem jest pole, które określa, dokąd wysyłane są sekrety — Base URL konfiguracji LLM albo
Host serwera SMTP. Po jego zmianie każdy zapisany sekret konfiguracji trzeba wpisać ponownie w tym
samym zapisie: formularz oznacza pola sekretów i o tym informuje, a zapis bez nich jest odrzucany z
422 CREDENTIAL_SECRET_REENTRY_REQUIRED i niczego nie zmienia. Zapisany sekret jest wysyłany wyłącznie
tam, dokąd miał trafiać w chwili wpisania.
Korzystanie z konfiguracji w ustawieniu
Niektóre ustawienia są typu „credential reference” i są ograniczone do jednego typu konfiguracji. Takie ustawienie wyświetla się jako lista wyboru pasujących konfiguracji z przyciskiem Preview:
- Otwórz Settings i znajdź ustawienie z odwołaniem do danych uwierzytelniających (np. LLM credentials asystenta AI).
- Wybierz konfigurację z listy — dostępne są tylko konfiguracje właściwego typu.
- Kliknij Preview, aby bez opuszczania strony zobaczyć wskazaną konfigurację w trybie tylko do odczytu (z zamaskowanymi sekretami).
Aby wykorzystać konfigurację wielokrotnie, wskaż tę samą konfigurację w kilku ustawieniach. Gdy raz zmienisz klucz w konfiguracji, wszystkie te ustawienia dostaną nową wartość.
Bezpieczeństwo
- Usunięcie jest blokowane, dopóki istnieje odwołanie. Próba usunięcia konfiguracji, którą nadal wskazuje jakieś ustawienie, kończy się jasnym komunikatem z listą ustawień, które trzeba najpierw odłączyć.
- Osierocone konfiguracje (których typ nie jest już dostępny) są pokazywane tylko do odczytu („unavailable”) i nigdy nie powodują awarii ekranu.
- Jawna wartość sekretu nigdy nie opuszcza serwera — lista, szczegóły i podgląd maskują sekrety; odszyfrowuje je, w pamięci i tylko na potrzeby użycia, wyłącznie kod korzystający z nich po stronie serwera.
Dla programistów
Model
Typ konfiguracji to opis rejestrowany w kodzie (a nie wiersze w bazie):
interface ConfigurationTypeDescriptor {
code: string; // 'llm' | 'email_adapter' | …
label: string;
ownerModule: string;
providers: ProviderVariant[];
}
interface ProviderVariant { code: string; label: string; fields: FieldDefinition[]; }
interface FieldDefinition {
key: string;
label: string;
kind: 'string' | 'number' | 'boolean' | 'select';
required: boolean;
secret: boolean; // secret ⇒ encrypted at rest, masked on read
options?: { value: string; label: string }[];
placeholder?: string;
format?: 'url'; // validated as an absolute http(s) URL
endpoint?: boolean; // says where the secrets are sent (default: format === 'url')
}
Pole, dla którego isCredentialEndpointField zwraca prawdę (endpoint albo domyślnie pole z
format: 'url'), wiąże sekrety konfiguracji ze swoją wartością: zmiana tego pola wymaga ponownego
wpisania każdego zapisanego sekretu, inaczej zapis jest odrzucany z
CREDENTIAL_SECRET_REENTRY_REQUIRED (details.fields wymienia klucze sekretów). Zadeklaruj
endpoint: true dla pola z hostem lub adresem, które nie jest adresem URL — tak robi dostawca SMTP
dla host — oraz endpoint: false dla pola URL, które nie określa, dokąd trafiają sekrety.
Zapisana konfiguracja przechowuje typeCode, providerCode i zbiór wartości values (sekrety jako
zaszyfrowane struktury AES-256-GCM, pozostałe pola jako zwykłe wartości proste) w tabeli
credential_configurations (@GlobalEntity, wspólnej dla całej platformy).
Rdzeń modułu nie zależy od konkretnych typów: odczytuje opis tylko po to, by wyświetlić pola,
wyprowadzić walidację zapisu i ustalić, które pola są sekretami. Nigdy nie zawiera osobnej logiki dla
konkretnego typeCode / providerCode — znaczenie dostawcy zna kod, który z konfiguracji korzysta.
Rejestracja nowego typu (punkt rozszerzenia)
Typ rejestruje się w kompozycji dowolnego modułu, przy starcie, przez port
configurationTypeRegistry (ConfigurationTypeRegistryPort w @endora-commerce/contracts) —
bez zmiany rdzenia modułu credentials (bezpieczne także dla modułów nakładkowych). Zadeklaruj tę
krawędź w manifeście — w dependencies albo jako wpis nonBindingDependencies rodzaju
contributes-to wskazujący configurationTypeRegistry, jak robi to organizations; tak rejestrują
swoje typy organizations i product_feeds:
import type { ConfigurationTypeRegistryPort } from '@endora-commerce/contracts';
ctx.onBoot(() => {
lazyPort<ConfigurationTypeRegistryPort>(ctx, 'configurationTypeRegistry').register({
code: 'sms_gateway',
label: 'SMS Gateway',
ownerModule: 'my_module',
providers: [
{
code: 'twilio',
label: 'Twilio',
fields: [
{ key: 'accountSid', label: 'Account SID', kind: 'string', required: true, secret: false },
{ key: 'authToken', label: 'Auth Token', kind: 'string', required: true, secret: true },
],
},
],
});
});
Typ od razu pojawia się na liście typów w panelu (GET /api/v1/admin/credentials/types) i można
tworzyć jego konfiguracje.
Typ wartości ustawienia credential_ref
Aby ustawienie mogło wskazywać konfigurację, zadeklaruj je w manifeście ustawień modułu:
{
code: 'prompt_actions.llm_credentials',
name: 'LLM credentials',
valueType: 'credential_ref',
configurationType: 'llm', // only configurations of this type are selectable
defaultValue: '', // empty ⇒ not configured
}
configurationType jest wymagane w ustawieniach credential_ref, a w pozostałych — zabronione.
Zapisywaną wartością jest po prostu kod konfiguracji.
Odczyt wskazanej konfiguracji (po stronie korzystającego kodu)
Odczyt to wywołanie usługi po stronie serwera (nigdy odpowiedź HTTP) — jedyna ścieżka zwracająca odszyfrowane sekrety, wyłącznie do użycia w pamięci:
const code = await settings.get('prompt_actions.llm_credentials'); // → 'primary-llm'
const cred = code ? await credentials.resolve(code) : { status: 'not_configured' };
if (cred.status !== 'ok') throw new Error('LLM not configured'); // fail closed
callProvider(cred.providerCode, cred.values.apiKey, cred.values.model);
resolve zwraca wynik w postaci unii rozłącznej:
{ status: 'ok', typeCode, providerCode, values }— sekrety odszyfrowane;{ status: 'not_configured' }— odwołanie nie jest ustawione albo jest puste;{ status: 'unavailable', reason: 'missing' | 'inert_type' }— usunięty kod albo niezarejestrowany typ.
Korzystający kod nigdy nie dostaje przez sieć konfiguracji innego typu ani jawnej wartości sekretu.
Spójność przy usuwaniu
CredentialsService.delete najpierw wywołuje SettingsService.listReferencesToConfiguration(code)
(jedyny sposób, w jaki moduł credentials sięga do ustawień). Niepusty wynik blokuje usunięcie z
409 CREDENTIAL_IN_USE i zwraca { referencedBy: [{ settingCode, salesChannelCode? }] }.
Sekrety i konfiguracja
Sekrety są szyfrowane wspólnym mechanizmem platformy (AES-256-GCM) z kluczem z istniejącej zmiennej
środowiskowej SETTINGS_SECRET_ENCRYPTION_KEY — nie trzeba przygotowywać nowego sekretu. Zapis
sekretu bez klucza jest odrzucany (SETTING_SECRET_KEY_MISSING); przy starcie pojawia się
ostrzeżenie, jeśli klucz nie jest ustawiony.
Uprawnienia
credentials:read— podgląd konfiguracji i katalogu typów (z zamaskowanymi sekretami).credentials:write— tworzenie, edycja i usuwanie konfiguracji, łącznie z zapisem sekretów.