Integracja klienta

beanguard-client to biblioteka Spring Boot, którą dodajesz do własnej aplikacji, aby pobierała, odszyfrowywała i egzekwowała treść licencji wydanej przez Twój beanguard-server.

Chcesz zobaczyć to w działaniu, zanim wpięsz to we własną aplikację? beanguard-demo to uruchamialny przykład — pobiera licencję, pokazuje jej status i pozwala ją odświeżyć, przedłużyć albo przenieść.

Zależność Maven

<dependency>
    <groupId>dev.beanguard</groupId>
    <artifactId>beanguard-client</artifactId>
    <version>0.1.5</version>
</dependency>

beanguard-client rejestruje się jako autokonfiguracja Spring Boot — nie wymaga żadnej dodatkowej adnotacji @Enable* w Twojej aplikacji.

Implementacja BeanGuardConfiguration

Cała konfiguracja połączenia z serwerem i tożsamość licencyjna Twojej aplikacji pochodzą z jednego beana implementującego BeanGuardConfiguration:

package com.example.myapp.licence;

import dev.beanguard.client.config.BeanGuardConfiguration;
import dev.beanguard.client.config.LicenceKeys;
import dev.beanguard.client.config.ServerConfig;
import org.springframework.stereotype.Component;

import java.util.Optional;

@Component
public class MyBeanGuardConfiguration implements BeanGuardConfiguration {

    @Override
    public ServerConfig getServerConfig() {
        return new ServerConfig(
            "https://api.beanguard.dev",
            "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...", // LICENCE_PUBLIC_KEY z panelu admina
            "dGhpcyBpcyBhIHNlY3JldCBrZXkgZm9yIEFFUy0yNTY=" // LICENCE_SECRET_KEY z panelu admina
        );
    }

    @Override
    public Optional<LicenceKeys> getLicenceKeys() {
        return Optional.of(new LicenceKeys(
            "11111111-1111-1111-1111-111111111111", // klucz licencji
            "my-licence-secret" // sekret licencji
        ));
    }

    @Override
    public Optional<String> loadLicence() {
        // odczytaj ostatnio zapisaną licencję, np. z pliku lub bazy Twojej aplikacji
        return Optional.empty();
    }

    @Override
    public void saveLicence(String licence) {
        // zapisz odebraną licencję, żeby przetrwała restart bez połączenia z serwerem
    }
}

getServerConfig() — adres Twojego beanguard-server, klucz publiczny RSA (LICENCE_PUBLIC_KEY) i sekret AES (LICENCE_SECRET_KEY) wygenerowane w panelu admina, zakładka Ustawienia → Klucze kryptograficzne.
getLicenceKeys() — klucz i sekret konkretnej licencji Twojego klienta. Zwróć Optional.empty(), jeśli licencja jeszcze nie została przypisana.
loadLicence() / saveLicence() — lokalny cache ostatniej odebranej licencji, żeby aplikacja działała nawet przy chwilowym braku połączenia z serwerem.

Nie umieszczaj tej klasy w pakiecie dev.beanguard.*. Jeśli chcesz chronić klucze ProGuardem przed dekompilacją, zobacz Ochronę kluczy ProGuardem.

Odczyt statusu licencji

Gdy BeanGuardConfiguration jest obecny w kontekście, autokonfiguracja rejestruje LicenceRegistry — licencja jest pobierana przy starcie aplikacji i odświeżana co godzinę:

import dev.beanguard.client.registries.LicenceRegistry;
import dev.beanguard.client.registries.LicenceStatus;
import org.springframework.stereotype.Component;

@Component
class LicenceBanner {

    private final LicenceRegistry licenceRegistry;

    LicenceBanner(LicenceRegistry licenceRegistry) {
        this.licenceRegistry = licenceRegistry;
    }

    boolean isLicenceValid() {
        return licenceRegistry.getStatus() == LicenceStatus.LOADED;
    }
}

LicenceStatus przyjmuje wartości NOT_LOADED, MISSING_KEY, WRONG_KEY, WRONG_SECRET, EXPIRED, LOADED — wykorzystaj je np. do pokazania banera „licencja wygasła" w swojej aplikacji.

Przeniesienie licencji na inną maszynę

Aby przenieść istniejącą licencję na nową maszynę (reinstalacja lub utracony sekret), użyj beana BeanGuardServer. Proces ma dwa kroki:

import dev.beanguard.api.models.licence.LicenceTransferInitResponse;
import dev.beanguard.api.models.licence.LicenceTransferStatusResponse;
import dev.beanguard.client.server.BeanGuardServer;

// 1. Rozpocznij transfer - serwer wysyła właścicielowi licencji e-mail z linkiem potwierdzającym.
LicenceTransferInitResponse init = beanGuardServer.initiateLicenceTransfer(licenceKey);
// Zachowaj init.transferToken() i init.expiresAt() do zakończenia transferu.

// 2. Odpytuj, aż właściciel otworzy link.
LicenceTransferStatusResponse status = beanGuardServer.getLicenceTransferStatus(init.transferToken());
switch (status.status()) {
    case "CONFIRMED" -> {
        // status.secret() to nowy sekret - zapisz go razem z kluczem licencji,
        // a następnie wywołaj licenceRegistry.refreshLicence().
    }
    case "EXPIRED" -> { /* zacznij od nowa przez initiateLicenceTransfer */ }
    default -> { /* PENDING - sprawdź ponownie później */ }
}

Transfer potwierdza właściciel licencji, a nie maszyna, która go rozpoczęła: link potwierdzający trafia wyłącznie na adres e-mail z licencji, a transferToken służy tylko do odpytywania. Pierwsze odpytanie po potwierdzeniu przez właściciela zmienia sekret licencji i go zwraca; sekret można odebrać tylko raz, więc zapisz go od razu (kolejne odpytanie zwróci błąd). Dotychczasowy sekret działa do tego momentu. Rozpoczęcie transferu dla nieznanego klucza lub w czasie TRANSFER_INIT_COOLDOWN_SECONDS od poprzedniego żądania wygląda jak sukces, ale nie wysyła maila, więc odpytanie takiego tokenu zwróci błąd.

Obie metody rzucają BeanGuardServerException, gdy serwer odrzuci żądanie (np. nieznany klucz licencji lub token transferu). Zapisanie oczekującego transferu i nowego sekretu leży po stronie Twojej aplikacji, ponieważ BeanGuardConfiguration tylko odczytuje klucze licencji - działający przykład znajdziesz w beanguard-demo.

Do egzekwowania limitów i funkcji z licencji na poziomie metod służą adnotacje — zobacz Adnotacje licencyjne.