Przejdź do treści

Weryfikacja grantu DueReason bez Node: przepis w Pythonie

Zweryfikuj grant DueReason w Pythonie lub dowolnym języku bez Node: pobierz JWKS, sprawdź podpis EdDSA, ważność i hash danych, krok po kroku.

Aktualizacja · 7 min czytania

W skrócie

  • Grant to podpisany JWS, który executor może sprawdzić całkowicie offline wobec kluczy opublikowanych przez organizację; nic w tej weryfikacji nie wymaga SDK w TypeScripcie ani samego Node.
  • Pięć sprawdzeń jest takich samych w każdym języku: rozbierz token na trzy części, zweryfikuj podpis Ed25519 wobec opublikowanego JWKS, sprawdź, że grant nie wygasł i dotyczy twojej organizacji, a na koniec policz hash danych i porównaj go z roszczeniem ph.
  • Przetestowany, skomentowany port verifyGrant z @duereason/sdk na Pythona leży w katalogu examples SDK jako przepis do skopiowania i dostosowania, a nie opublikowany pakiet.
  • Niezależnie od języka, zasada jest ta sama: wykonaj akcję tylko gdy każde sprawdzenie przejdzie, i zgłoś wynik później, żeby grantu nie dało się użyć dwa razy.

Najmocniejsza część zatwierdzenia w DueReason dzieje się po tym, jak ktoś kliknie zatwierdź: system, który faktycznie płaci fakturę, wdraża kod albo zmienia dostęp, sam sprawdza, że zatwierdzenie dotyczy dokładnie tego, co zaraz zrobi. To sprawdzenie to podpisany token (grant) weryfikowany wobec klucza publicznego i nie wymaga do tego ani Node, ani SDK w TypeScripcie. Jeśli twój executor to skrypt bash do wdrożeń, pipeline w Pythonie albo cokolwiek innego, co nie może łatwo dociągnąć zależności w JavaScripcie, możesz zweryfikować grant w około pięćdziesięciu liniach kodu wobec tych samych opublikowanych kluczy.

Czym jest grant

Grant to zwarty JWS (trzy segmenty base64url rozdzielone kropkami): nagłówek z nazwą algorytmu podpisu (EdDSA) i identyfikatorem klucza (kid), który go podpisał, treść roszczeń i sam podpis Ed25519. Roszczenia niosą org (slug twojej organizacji), act (klucz akcji, na przykład payment), exp (kiedy grant wygasa) oraz ph, czyli hex sha256 małymi literami dokładnie tych danych, które zostały zatwierdzone. Weryfikacja grantu oznacza sprawdzenie tego wszystkiego, zanim działasz, nigdy po.

Krok 1: pobierz JWKS organizacji

Każda organizacja publikuje swoje aktualne i niedawno wycofane klucze podpisujące pod adresem https://duereason.com/.well-known/duereason/{organizacja}/jwks.json, czyli standardowy JWK Set: obiekt JSON z tablicą keys, każda pozycja { kty: "OKP", crv: "Ed25519", x, kid, alg: "EdDSA", use: "sig" }. Ten endpoint nie wymaga klucza API; w długo działającym executorze przechowuj odpowiedź w cache przez kilka minut i pobieraj ją ponownie, gdy zobaczysz nieznane kid, żeby rotacja klucza nigdy nie uwięziła grantu w locie.

Krok 2: rozbierz token i sprawdź nagłówek

Rozdziel grant po .; poprawny ma dokładnie trzy niepuste segmenty zawierające wyłącznie znaki base64url. Zdekoduj base64url i sparsuj jako JSON pierwszy segment jako nagłówek, i odrzuć wszystko, czego alg nie jest dokładnie EdDSA, czego typ nie jest dokładnie duereason-grant+jwt, albo co nie ma niepustego kid. Ten krok sam w sobie odrzuca tokeny podpisane złym algorytmem albo niosące nieoczekiwane rozszerzenie crit, zanim w ogóle dotkniesz biblioteki kryptograficznej.

Krok 3: zweryfikuj podpis Ed25519

Znajdź w pobranym JWKS klucz JWK, którego kid pasuje do tego z nagłówka; jeśli żaden nie pasuje, odrzuć grant od razu — klucz, którego twoja organizacja nigdy nie opublikowała, nie weryfikuje niczego. Zdekoduj pole x tego klucza JWK (surowy 32-bajtowy klucz publiczny Ed25519, zakodowany base64url) i użyj go do zweryfikowania podpisu (trzeci segment, też base64url, dokładnie 64 bajty dla Ed25519) nad bajtami ASCII {segment nagłówka}.{segment roszczeń}, połączonymi dosłowną kropką. Pakiet cryptography w Pythonie robi to w dwóch liniach przez Ed25519PublicKey.from_public_bytes i .verify(); większość języków ma odpowiednik, bo Ed25519 nie wymaga schematu dopełnienia ani parametrów krzywej poza samym surowym kluczem publicznym.

Krok 4: sprawdź ważność, organizację i akcję

Dopiero gdy podpis się zweryfikuje, możesz zaufać treści roszczeń na tyle, by je odczytać. Zdekoduj i sparsuj ją, potwierdź, że każde wymagane roszczenie (iss, org, sub, jti, act, ph, apv, iat, exp) jest obecne i ma właściwy typ, a potem odrzuć grant, którego exp jest w przeszłości, którego org nie jest twoje, albo — gdy twój executor sprawdza konkretną akcję — którego act się nie zgadza. To proste porównania; chodzi o to, by wykonać je w tej kolejności, po sprawdzeniu podpisu, tak żeby sfałszowany albo zmieniony token nigdy nie dotarł do nich z roszczeniami, którym miałbyś jakikolwiek powód ufać.

Krok 5: policz ponownie hash danych

Powiązanie, które powstrzymuje zmienioną kwotę albo zmieniony cel wdrożenia, to ostatnie sprawdzenie: policz ponownie sha256 kanonicznego JSON-a dokładnie tych danych, które zaraz wykonasz (klucze obiektu posortowane, bez dodatkowych spacji, liczby i stringi sformatowane tak, jak normalnie robi to JSON), i porównaj go, jako string hex małymi literami, z ph z roszczeń. Grant, który weryfikuje się idealnie, ale którego ph nie pasuje do danych przed tobą, został zatwierdzony dla czegoś innego; odrzuć go tak samo jak zły podpis.

Skrypt referencyjny

Przetestowany, okomentowany port verifyGrant z @duereason/sdk na Pythona, implementujący dokładnie te pięć kroków z tymi samymi powodami odmowy (malformed, unknown_key, bad_signature, expired, wrong_organization, wrong_action, payload_mismatch), leży w drzewie źródłowym SDK jako duereason/sdk/examples/python/verify_grant.py, razem z plikiem testów sprawdzającym poprawny grant, zmienione dane, wygasły grant i sfałszowany podpis. Zależy tylko od biblioteki standardowej Pythona oraz szeroko używanego pakietu cryptography do sprawdzenia Ed25519; to kod przykładowy do skopiowania do własnego executora i dostosowania, a nie utrzymywany pakiet publikowany w PyPI, więc przypnij go i przeglądaj tak, jak każdy kod, który u siebie wendorujesz.

Niezależnie od języka

Pięć powyższych sprawdzeń przekłada się wprost na Go, Rust, Ruby albo zwykły openssl w wierszu poleceń: pobierz JWKS, sparsuj nagłówek, zweryfikuj podpis Ed25519 nad header.claims, sprawdź exp/org/act i porównaj ph z kanonicznym sha256 danych. Nic z tego nie wymaga biblioteki specyficznej dla DueReason; wymaga tokenu w kształcie JWS, klucza publicznego i funkcji hash, którą każdy język już ma.

Pytania

Czy potrzebuję klucza API, żeby pobrać JWKS?
Nie. Endpoint JWKS jest publiczny (musi być, żeby jakikolwiek executor mógł zweryfikować grant offline) i nie przyjmuje ani nie wymaga uwierzytelnienia.
Czy mogę pominąć sprawdzenie podpisu i tylko porównać hash danych?
Nie. Bez sprawdzenia podpisu każdy, kto zgadnie albo zaobserwuje kształt twoich danych, mógłby zbudować token z pasującym ph i bez żadnego ważnego zatwierdzenia za sobą. Podpis dowodzi, że roszczenia wystawił DueReason, a nie ktoś inny.
Co jeśli mój język nie ma biblioteki Ed25519?
Ed25519 jest szeroko wspierany: OpenSSL od wersji 1.1.1, cryptography w Pythonie, crypto/ed25519 w Go, ed25519-dalek w Rust i rbnacl w Ruby wszystkie to implementują. Jeśli naprawdę go nie masz, wywołaj zamiast tego POST /api/v1/grants/verify i pozwól, żeby sprawdzenie wykonał serwer DueReason.
Czy weryfikacja grantu go zużywa?
Nie. Weryfikacja jest tylko do odczytu i można ją powtarzać. Zgłoś wykonanie później (POST /approvals/{id}/executions); DueReason przyjmuje pierwsze zgłoszenie dla grantu, a każdemu kolejnemu odpowiada already_executed — i to właśnie to faktycznie zapobiega użyciu grantu dwa razy.
Czy skrypt w Pythonie jest zsynchronizowany z SDK w TypeScripcie?
Odzwierciedla sprawdzenia z verifyGrant w @duereason/sdk i jest dostarczany z testami na podobnych danych testowych. Traktuj go jako wzorzec do dostosowania, a nie pakiet z własnym cyklem wydań; sprawdź go ponownie wobec SDK, jeśli polegasz na nim przez dłuższy czas.

Przeczytaj pełne API i opis grantu

Każde roszczenie w grancie, endpoint JWKS, przykład weryfikacji w Node.js i powody błędów widoczne dla executora znajdziesz w dokumentacji API.

Czytaj dokumentację API

Źródła

Poradnik wyjaśnia przepisy tak, jak je rozumiemy; nie jest poradą prawną. Sprawdź tekst urzędowy i prawo krajowe, które może dodać obowiązki.

Zacznij z DueReason

Załóż bezpłatne konto, wypróbuj na żywo albo porozmawiaj z nami o swoim procesie.

Otrzymuj nowości o produkcie