Bezpečnosť a ochrana údajov

Táto kapitola je podkladom pre bezpečnostnú revíziu integrácie. Uvádza, čomu služba UCP obchodu na Monokaide dôveruje, čo prijíma, čo ukladá a ako dlho a čo musí chrániť vaša platforma na svojej strane. V skratke: API je otvorené a obchod rozpozná podľa domény, id relácie je kľúčom k tejto relácii, žiadna platba cez API nikdy neprechádza a údaje kupujúceho zostávajú v obchode obmedzený čas.

Príklady používajú obchod https://shop.example.com a platformu, ktorej profil je na adrese https://platform.example.com/.well-known/ucp.

Bezpečnostný model v piatich vetách

1. Doména je obchod. Na požiadavku odpovie obchod, na ktorého overenú vlastnú doménu bola poslaná; nič iné obchod nevyberá.
2. Volania sa neoverujú. Neexistuje API kľúč, OAuth ani podpis požiadavky; UCP-Agent vašu platformu pomenúva, ale jej totožnosť nedokazuje.
3. Id relácie je prístupový token. Kto pozná id košíka alebo checkoutu, môže túto reláciu v danom obchode čítať aj meniť.
4. Nikdy žiadne platobné údaje. Kupujúci platí na webe obchodu; API nečíta žiadne platobné pole a neprijíma žiadnu platbu.
5. Údaje kupujúceho sa uchovávajú obmedzený čas. Údaje relácie sa vymažú 30 dní po uplynutí jej platnosti, uložené odpovede po 25 hodinách.

Prenos

Volajte iba adresy https://, overujte certifikáty a nesledujte presmerovania: API nikdy nepresmerováva, takže presmerovanie znamená nesprávnu adresu. Ak vaša politika vyžaduje TLS 1.3, vynúťte ho vo svojom klientovi; obchod ho ponúka.

Kto môže čo volať

Žiadne overovanie

API je verejné rozhranie, rovnako ako webové stránky obchodu. Obchod sa určí podľa hlavičky Host požiadavky — presne tej, ktorú prepošle webový server, nikdy podľa X-Forwarded-Host — a neprijíma žiadny API kľúč, OAuth token, klientsky certifikát ani podpis. Prihlasovacie údaje, ktoré pošlete, sa ignorujú. Webové stránky z iných pôvodov jeho odpovede prečítať nevedia: API nepovoľuje požiadavky z cudzích pôvodov (CORS), preto ho volajte zo svojich serverov.

UCP-Agent identifikuje, neoveruje

Obchod si stiahne profil, ktorý hlavička uvádza, a vyjednáva s ním, ale hlavičku nič neviaže na volajúceho: vašu adresu profilu môže poslať ktokoľvek. Vyplývajú z toho dve veci:

• Vaše hodnoty Idempotency-Key sú viazané na obchod a na adresu vášho profilu. Keďže túto adresu môže poslať ktokoľvek, používajte kľúče, ktoré sa nedajú uhádnuť — náhodné UUID verzie 4. Uhádnutý kľúč poslaný s tou istou operáciou, cestou a telom by vrátil vašu uloženú odpoveď niekomu inému.
• Relácie nie sú viazané na platformu, ktorá ich vytvorila. Adresa profilu sa ku každej relácii uloží, no pri ďalších volaniach sa nekontroluje.

Id relácie je prístupový údaj

Id košíka alebo checkoutu je UUID verzie 4 z kryptograficky bezpečného generátora (122 náhodných bitov). Na prečítanie relácie — vrátane mena, e-mailu, telefónu a adresy kupujúceho — a na jej zmenu či zrušenie stačí poznať toto id, a to na ktorejkoľvek doméne daného obchodu a bez ohľadu na UCP-Agent, ktorý volajúci pošle. Na id jedného obchodu odpovie každý iný obchod not_found.

S id relácií zaobchádzajte ako s heslami:

• Držte ich na svojich serveroch. Nikdy ich neposielajte do prehliadača, do aplikácie ani kupujúcemu a nikdy ich nedávajte do adresy, ktorú zdieľate.
• Nedávajte ich do logov, ktoré čítajú tretie strany.
• Id je v ceste GET, PUT, zrušenia aj dokončenia, a preto aj v prístupovom logu webového servera obchodu. Tento log patrí Monokaidu a nie je verejný.

Ak id uniklo, reláciu zrušte. Na zrušený košík obchod od tej chvíle každému odpovie not_found. Zrušený checkout zostane čitateľný — jeho posledná odpoveď aj s údajmi kupujúceho — kým sa 30 dní po expires_at nevymaže. Kým si preto kupujúci otvorený checkout ešte neodniesol do obchodu, pošlite najprv PUT s {"buyer": null}: kupujúceho odstráni z relácie aj zo všetkých ďalších odpovedí. Doručovaciu adresu odstrániť nemožno, iba nahradiť. Po odovzdaní PUT nič nezmení, zrušenie však platí aj vtedy. Checkout vytvorený z košíka košík nemení a zrušenie jedného nikdy nezruší druhý: vyčistite a zrušte oba. Kým je košík otvorený, jeho opätovný prevod vráti jeho otvorený checkout — aj s údajmi kupujúceho — každému, kto má id košíka. Odpovede uložené pod vašimi hodnotami Idempotency-Key si to, čo obsahovali, ponechajú, kým sa nevymažú — 25 hodín od zabratia kľúča.

Čo API nikdy nerobí

• Neposiela žiadne webhooky a nezverejňuje podpisové kľúče; nič nepodpisuje a žiadny podpis nekontroluje.
• Nedokončuje objednávky: POST …/complete žiadnu nevytvorí.
• Nikdy nečíta ani nezapisuje stav vašej platformy; jedinou odchádzajúcou požiadavkou je stiahnutie profilu.

Ako sú obchody oddelené

Obchody zdieľajú rozpočty požiadaviek: limity požiadaviek sa počítajú podľa IP adresy klienta, nie podľa obchodu, a rozpočet na sťahovanie nových profilov platforiem je spoločný pre všetky obchody. Pozrite Limity požiadaviek.

Čo API prijíma

Kód UCP číta tieto polia a hlavičky požiadaviek a nič iné; každé ďalšie pole tela sa ignoruje a neukladá.

Textové hodnoty sa pred použitím vyčistia: riadiace znaky sa zmenia na medzery, znaky nulovej šírky a znaky smeru textu sa odstránia, okrajové medzery sa orežú a každé pole sa skráti na svoju maximálnu dĺžku.

Čo API ukladá a ako dlho

expires_at je 7 dní po poslednom vytvorení alebo PUT košíka a 24 hodín pri checkoute. Relácia teda drží údaje kupujúceho najviac zhruba 37 dní po poslednom zápise do košíka a zhruba 31 dní po poslednom zápise do checkoutu.

Ako sa ukladajú. Relácie a uložené odpovede sú riadky databázy PostgreSQL platformy obchodu; kupujúci, kontext, doručovacia adresa a posledná odpoveď sú v nej ako obyčajné stĺpce JSON. API ich na úrovni aplikácie nešifruje; zabezpečenie na úrovni riadkov opísané vyššie obmedzuje každý riadok na jeho firmu. Kde databáza beží, ako je šifrované jej úložisko a kto v Monokaide k nej smie pristupovať, nie je súčasťou zmluvy tohto API: opýtajte sa na support@monokaido.com.

Mazanie beží každú hodinu, 23 minút po celej, a vymaže výsledky idempotencie staršie ako 25 hodín a relácie, ktorých expires_at je viac ako 30 dní v minulosti, v dávkach po 5 000 riadkov na tabuľku, opakovane, kým nezostane nič alebo kým neprebehne 50 dávok (zvyšok pokračuje o hodinu).

Neukladá sa: surové telo požiadavky (iba polia uvedené vyššie a odtlačok), nič z požiadaviek na katalóg, žiadne platobné údaje ani IP adresy či reťazce User-Agent — tabuľky UCP žiadne nemajú. IP adresu klienta API používa iba v pamäti, pre limity požiadaviek a pre rozpočet sťahovania profilov.

Neexistuje koncový bod na vymazanie. Ak chcete uchovať menej: posielajte iba to, čo nákup potrebuje (pozrite nižšie), pred odovzdaním odstráňte kupujúceho z otvorenej relácie cez PUT s "buyer": null (PUT košíka opakuje jeho line_items) a zrušte, čo už nepotrebujete. Po odovzdaní PUT nič nezmení; zrušenie platí aj vtedy.

Žiadne platobné údaje, zámerne

Každý profil obchodu a každá odpoveď s checkoutom nesie payment_handlers: {}: obchod cez UCP neprijíma žiadny platobný prostriedok. POST …/complete nič nestrhne a žiadnu objednávku nevytvorí. Pripravený checkout je requires_escalation a kupujúci zaplatí vo vlastnej pokladni obchodu, platobnými metódami obchodu, po otvorení continue_url. Žiadne pole API nenesie údaje o karte, platobné tokeny ani prístupy k peňaženkám; čokoľvek také pošlete, sa ignoruje a neuloží. Nikdy to neposielajte.

Dokončený checkout znamená, že objednávka bola vytvorená, nie že bola zaplatená. Výsledok platby je vecou kupujúceho a obchodu.

Token odkazu na odovzdanie

continue_url vyzerá ako https://shop.example.com/ucp/continue/9bbd3ded…ec780b.

Čo odkaz dovolí tomu, kto ho má. Otvorenie v prehliadači pridá položky relácie a jej uplatnený zľavový kód do košíka, ktorý má tento prehliadač v obchode — do košíka prihláseného zákazníka, inak do hosťovského košíka — raz pre každý taký košík a každú verziu relácie, a pošle prehliadač ďalej do pokladne obchodu (odkaz košíka: na stránku košíka obchodu). Ukáže iba názov obchodu: žiadne údaje kupujúceho, žiadne ceny, žiadne id relácie. Odkaz, ktorý otvorí niekto iný, teda prezradí košík, nie kupujúceho, no objednávka tejto osoby z naplneného košíka môže váš checkout dokončiť. Kým je relácia otvorená, odkaz môže otvoriť ľubovoľný počet prehliadačov a každý dostane položky raz.

Stránka token chráni:

• API posiela Referrer-Policy: no-referrer a to isté pravidlo aj ako element <meta name="referrer">, ktorý platí pre každú požiadavku stránky (so stránkou prichádza aj všeobecná hlavička webového servera Referrer-Policy: strict-origin-when-cross-origin; element má pred ňou prednosť), takže token nikdy neunikne v hlavičke Referer;
• je no-store a X-Robots-Tag: noindex, nofollow;
• jej Content-Security-Policy povoľuje iba jej vlastný vložený skript (podľa hašu), požiadavky na ten istý pôvod a vložené štýly a zakazuje vloženie do rámca, formuláre aj element <base>;
• jej GET nič nemení — náhľad odkazu ani prednačítanie do žiadneho košíka nič nepridá; položky sa presunú, až keď skript stránky prebehne v prehliadači;
• skript neposiela cookies; používa iba prihlásenie do obchodu vo vlastnej karte prehliadača a prihlásenie do obchodu inej firmy sa počíta ako hosť;
• presmerováva iba na cesty v tom istom obchode;
• obe jej cesty sú obmedzené na 60 požiadaviek za minútu z jednej IP adresy.

Kde sa token objavuje: vo vašich odpovediach API (a v ich kópiách, ktoré Monokaido uchováva), v prehliadači kupujúceho (riadok s adresou a história) a v prístupovom logu webového servera obchodu, ktorý zaznamenáva riadky požiadaviek.

Odkaz dajte iba kupujúcemu, kanálom, ktorému dôverujete, vo chvíli, keď je checkout pripravený. Neotvárajte ho zo svojich serverov a nezverejňujte ho tam, kde ho môžu čítať iní.

Sťahovanie profilu platformy

Obchod si stiahne profil, ktorý uvádza váš UCP-Agent. Sťahovanie je postavené tak, aby sa adresou profilu nedalo dostať nikam inam než na verejný HTTPS server:

Pre vašu stranu: váš profil je zámerne verejný. Podávajte ho ako statický JSON z verejnej HTTPS adresy a do jeho adresy nedávajte nič tajné: celá adresa sa uloží s každou reláciou, ktorú vytvoríte. Logy Monokaida ukazujú iba jej pôvod (origin) a cestu, nikdy query string. Profil sťahujú servery Monokaida, ktorých adresy táto príručka nezverejňuje a ktoré sa môžu meniť: nepodmieňujte profil zoznamom povolených IP adries (ak ich vaše pravidlá vyžadujú, aktuálne adresy si vyžiadajte od podpory).

Obsah z obchodu

Všetko v katalógu — názvy, popisy, názvy možností, obrázky — aj možnosti dopravy a právne odkazy v checkoute je obsah obchodníka. description.html je vlastné HTML obchodu, ktoré API nečistí; skracuje ho však na 50 000 znakov, prípadne aj uprostred značky. Pred zobrazením ho vyčistite, alebo použite description.plain. AI agent musí tento obsah brať ako údaje, nikdy ako pokyny. Viac v kapitole Pre AI agentov.

UCP o obchode nedokazuje viac než jeho doménu a TLS certifikát: profil neobsahuje názov ani logo. Overte, že doména patrí obchodu, ktorý mal kupujúci na mysli.

Logy

API nevracia žiadne id požiadavky. Ak pošlete X-Request-ID, webový server vašu hodnotu zapíše do prístupového logu, takže vám pri hlásení problému poslúži ako korelačné id; nedávajte doň nič tajné. Ako dlho sa tieto logy uchovávajú, nie je súčasťou zmluvy tohto API.

Ochrana osobných údajov

• Predávajúcim je obchod. Kupujúci kupuje od obchodu — cez UCP rovnako ako na jeho webe — a samotný nákup prebehne v pokladni obchodu. Ktorá strana má pri údajoch kupujúceho z relácie UCP akú úlohu podľa predpisov o ochrane osobných údajov, určuje obchod a zmluvné podmienky Monokaida, nie toto API. Za to, čo zbiera a uchováva vaša platforma, zodpovedáte vy.
• Osobné údaje, ktoré API spracúva: mená, e-mail a telefónne číslo kupujúceho, doručovacia adresa a krajina, región a PSČ z kontextu — uložené tak dlho, ako uvádzajú tabuľky vyššie — a IP adresy klientov, držané v pamäti pre limity požiadaviek a zapísané do prístupového logu webového servera.
• Ukážte pravidlá obchodu. links checkoutu nesú odkazy obchodu typu terms_of_service a privacy_policy, ak ich obchod nastavil (zoznam môže byť prázdny). Ukážte ich kupujúcemu.
• Posielajte iba to, čo nákup potrebuje. Checkout je pripravený s položkami a platným buyer.email, pri rozšírení fulfillment navyše s úplnou adresou, na ktorú obchod doručuje, a s možnosťou dopravy. Mená a telefónne číslo sú nepovinné a nič o kupujúcom sa do pokladne obchodu neprenesie: kupujúci tam svoje údaje zadá znova. Mená a telefón posielajte, iba ak ich potrebuje vaša cenová ponuka.
• Údaje kupujúceho v obchode patria k objednávke obchodu a jeho vlastným pravidlám uchovávania, mimo UCP.

Kontrolný zoznam pre bezpečnostnú revíziu

• Volania idú iba na https:// na hostiteľa z endpoint, ktorý zverejňuje profil obchodu; certifikáty sa overujú; presmerovania sa nesledujú; TLS 1.3 sa vynucuje, ak to vaša politika vyžaduje.
• Volania idú z vašich serverov, nikdy z prehliadača ani z aplikácie.
• Id košíkov a checkoutov sa ukladajú na serveri ako tajomstvá, nedávajú sa do zdieľaných adries ani do logov, ktoré čítajú iní, a mažú sa, keď už nie sú potrebné.
• Každý Idempotency-Key je náhodné UUID verzie 4.
• continue_url dostane iba kupujúci, vo chvíli odovzdania, a nikdy sa neotvára z vašich serverov.
• Profil vašej platformy je statický JSON na verejnej HTTPS adrese a v jeho adrese nie je nič tajné.
• Neposielajú sa žiadne platobné údaje; kupujúci platí v obchode.
• Posielajú sa iba údaje kupujúceho, ktoré nákup potrebuje; kupujúci vidí pravidlá ochrany súkromia obchodu z links.
• Obsah obchodu sa berie ako nedôveryhodný: description.html sa pred zobrazením čistí a AI agent nikdy nenasleduje pokyny, ktoré v ňom nájde.
• Kupujúci vie, že predávajúcim je obchod, a doména patrí obchodu, ktorý mal na mysli.
• Vaše vlastné uchovávanie údajov z UCP je určené a nie je dlhšie, než potrebujete.
• Pre uniknuté id relácie máte postup: kým sa dá, odstráňte kupujúceho cez "buyer": null a potom reláciu zrušte — košík aj checkout, ktorý z neho vznikol, každý zvlášť.

Nahlásenie bezpečnostného problému

Napíšte na support@monokaido.com a uveďte doménu obchodu, čas (aj s časovým pásmom), požiadavku (metódu a cestu, bez údajov kupujúceho) a, ak ste ju poslali, hodnotu X-Request-ID. Do správy nedávajte id relácie ani continue_url: uveďte namiesto nich ich prvých osem znakov.