Przejdź do treści

Integracja z AP2: odczyt grantu DueReason jako mandatu Agent Payments Protocol

Jak podpisany grant DueReason mapuje się na ksztalt mandatu Agent Payments Protocol (AP2) od Google i czym jest funkcja toAp2Mandate() w SDK.

Aktualizacja · 6 min czytania

W skrócie

  • Agent Payments Protocol (AP2) od Google i grant DueReason rozwiązują ten sam problem - udowodnić, że agent ma prawo zrobić jedną konkretną, ograniczoną rzecz - tymi samymi elementami: podpisanym, ograniczonym w zakresie i czasie tokenem, który weryfikujący sprawdza wobec opublikowanego klucza, a nie hasłem ani stałym poświadczeniem API.
  • `toAp2Mandate` w `@duereason/sdk` to czysta, addytywna translacja: najpierw wywołuje istniejące `verifyGrant`, a dopiero gdy grant się zweryfikuje, przekształca te same roszczenia na pola mandatu AP2 (issuer, credentialSubject.scope, proof).
  • To wyłącznie interoperacyjność formatu grantu: nic w sposobie, w jaki DueReason wystawia albo weryfikuje grant, się nie zmienia, nie implementuje się żadnego transportu ani portfela AP2, i nie podłącza się żadnego kanału płatności. `mandate.proof` nadal wskazuje na oryginalny podpis DueReason.
  • Użyj tego, gdy coś, czego nie kontrolujesz - sprzedawca, procesor płatności, Credential Provider - mówi już w AP2 i musi odczytać zatwierdzenie DueReason bez uczenia się najpierw własnego formatu grantu DueReason.

Agent AI proszący o wydanie pieniędzy i agent AI proszący o wdrożenie kodu potrzebują tego samego dowodu, zanim ktokolwiek pozwoli mu działać: nie "ten wywołujący ma ważny klucz API", tylko "konkretna osoba zatwierdziła dokładnie tę akcję, na tę kwotę albo ten cel, zanim minął jej czas ważności, i oto kryptograficzny dowód kto i kiedy". DueReason dostarcza taki dowód jako podpisany grant od swojego pierwszego wydania. Agent Payments Protocol (AP2) od Google dostarcza wersję tego samego pomysłu, ograniczoną do płatności, jako publiczną, wersjonowaną specyfikację, wobec której buduje już kilku sprzedawców, portfeli i procesorów płatności. toAp2Mandate w @duereason/sdk odczytuje grant DueReason i zwraca to samo zatwierdzenie przekształcone na słownictwo AP2, więc system, który już rozumie mandaty AP2, nie musi najpierw uczyć się nazw roszczeń DueReason.

Jak wyglądają mandaty AP2

AP2 definiuje dwa typy mandatów podróżujące jako poświadczenia weryfikowalne SD-JWT: Checkout Mandate, dowodzący, że Shopping Agent ma prawo kupić konkretnie zestawiony checkout, i Payment Mandate, dowodzący, że ma prawo za niego zapłacić. Każdy nazywa swoją wersję schematu w roszczeniu vct (mandate.payment.1 dla zamkniętego Payment Mandate, mandate.payment.open.1 dla otwartej wersji podpisanej przez użytkownika, która ogranicza autonomicznego agenta ograniczeniami takimi jak zakres kwoty albo lista dozwolonych odbiorców), niesie roszczenie wiążące klucz cnf, gdy autoryzuje klucz agenta zamiast bezpośrednio człowieka, i zawsze jest weryfikowany wobec opublikowanego klucza, zanim cokolwiek w danych zostanie zaufane - dokładnie ta sama kolejność operacji, którą verifyGrant już wymusza dla grantu DueReason.

Co już ma grant DueReason

Grant DueReason to zwarty JWS, podpisany Ed25519, z roszczeniami iss (wystawca), org (organizacja), act (klucz zatwierdzonej akcji), sub (id żądania zatwierdzenia), ph (sha256 dokładnie zatwierdzonych danych), apv (kto zatwierdził, w kolejności), iat i exp. Każde pole, na którym zależy AP2 do weryfikacji - kto wystawił, co obejmuje zakres, kiedy wygasa, i podpis, który weryfikujący sprawdza wobec opublikowanego klucza - już tam jest pod własnymi nazwami DueReason; toAp2Mandate to mapowanie z jednego słownictwa na drugie, a nie nowa kryptografia.

Translacja

Wywołaj const mandate = await toAp2Mandate({ grant, payload, organization: "acme", action: "payment" }) z @duereason/sdk; każde pole zwróconego mandatu to bezpośrednia, bezstratna kopia roszczenia z grantu:

Pole Ap2MandateZ grantu
issueriss
issuanceDate / expirationDateiat / exp, jako ISO 8601
credentialSubject.idjti
credentialSubject.scope.organizationorg
credentialSubject.scope.actionact
credentialSubject.scope.approvalRequestIdsub
credentialSubject.scope.payloadHashph
credentialSubject.scope.approvedByapv
proof.jwsoryginalny grant, niezmieniony

toAp2Mandate najpierw wywołuje verifyGrant, z tymi samymi opcjami i tym samym GrantVerificationError przy wszystkim, co się nie zgadza; grant, który nie przejdzie weryfikacji, nigdy nie dociera do kroku translacji. Powstały Ap2Mandate niesie type: ["VerifiableCredential", "Ap2Mandate"] i wpisy @context, więc ogólny czytnik poświadczeń weryfikowalnych rozpoznaje ten kształt, ale jego proof odwołuje się do oryginalnego podpisu DueReason zamiast tworzyć nowy - weryfikujący natywny dla AP2 nadal musi pobrać wskazany grant i go zweryfikować (bezpośrednio albo przez POST /api/v1/grants/verify), zamiast ufać samemu kształtowi mandatu.

Czym to nie jest

To dostarcza wyłącznie interoperacyjność formatu grantu. Nie implementuje żadnej części transportu AP2 (ról Shopping Agent, Merchant, Credential Provider czy Merchant Payment Processor), nie rozmawia z portfelem ani siecią płatności i nie pozwala DueReason wystawiać grantu, który sam w sobie byłby ważnym, niezależnie podpisanym mandatem AP2 od pierwszego dnia - to wymagałoby własnego schematu podpisu AP2 (ES256 nad SD-JWT, a nie EdDSA JWS DueReason) i jest celowo osobną, niezbudowaną jeszcze decyzją. Nic w sposobie, w jaki DueReason wystawia albo weryfikuje własne granty, się nie zmienia: verifyGrant pozostaje nietknięty, a każdy istniejący executor sprawdzający grant dziś działa dokładnie tak jak wcześniej.

Kiedy po to sięgnąć

Sięgnij po toAp2Mandate, gdy coś poza twoją kontrolą już oczekuje słownictwa AP2 - integracja checkoutu sprzedawcy, krok weryfikacji procesora płatności, Credential Provider oceniający, czy przekazać poświadczenie płatności - a inaczej musiałbyś najpierw wytłumaczyć im własne roszczenia grantu DueReason. Jeśli twój własny executor jest jedyną rzeczą sprawdzającą grant, translacja nic nie daje: zweryfikuj grant bezpośrednio, tak jak opisuje przewodnik po weryfikacji grantu.

Pytania

Czy toAp2Mandate tworzy nowy, niezależnie ważny podpis AP2?
Nie. Zwrócony mandat ma proof odwołujący się do oryginalnego podpisu grantu DueReason; nie powstaje nowy podpis nad kształtem AP2. Weryfikujący nadal musi pobrać i sprawdzić wskazany grant, tak jak zawsze.
Czy to integruje kanał płatności, portfel albo transport AP2?
Nie. To czysta, lokalna funkcja translacji bez żadnych własnych wywołań sieciowych poza weryfikacją grantu, którą toAp2Mandate już wykonuje. Rozmowa z Shopping Agent, Merchant, Credential Provider czy Merchant Payment Processor jest poza zakresem tej funkcji.
Czy to zmienia sposób, w jaki DueReason wystawia albo weryfikuje granty?
Nie. verifyGrant pozostaje niezmienione; toAp2Mandate wywołuje je bez zmian i dopiero po zweryfikowaniu grantu przekształca roszczenia. Każda istniejąca integracja działa dokładnie tak jak przed powstaniem tej funkcji.
Czy DueReason może wystawić grant jako mandat AP2 bezpośrednio, zamiast translować go później?
Nie dzisiaj. Wymagałoby to podpisywania własnym schematem AP2 (SD-JWT, ES256) zamiast EdDSA JWS DueReason i jest osobną decyzją śledzoną wobec konkretnej potrzeby integracyjnej, a nie budowaną spekulacyjnie.

Przeczytaj pełną dokumentację grantu i API

Każde roszczenie w grancie, endpoint JWKS i eksport toAp2Mandate znajdziesz w dokumentacji API i README SDK.

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