Kanonický formát

Toto sú presné bajty, ktoré Sentinel chráni MAC alebo podpisuje. Formát je zmrazený: každá zmena vyjde ako sentinel.seal/2 popri verzii 1, overovače si ponechajú kód pre každý starší formát a súbor testovacích vektorov so známou odpoveďou zastaví build pri akejkoľvek odchýlke. Záleží na tom preto, lebo pečať sa dá overiť aj mimo Sentinelu — skriptom audítora, v inom jazyku — a pečať zapísaná na SQLite sa overí na PostgreSQL aj MySQL.

Pečatí sa to, čo drží databáza

Hodnoty atribútov sa z databázy čítajú vždy v surovom tvare drivera — pri pečatení cez SELECT … FOR UPDATE v pečatiacej transakcii po zápise aplikácie, pri overovaní novým dopytom alebo zo surových pôvodných atribútov načítaného modelu. Pokryté sú teda aj predvolené hodnoty databázy, triggery a generované stĺpce a zápis aj spätné načítanie sú zo svojej podstaty totožné: preusporiadanie jsonb, doplnenie numeric, afinita REAL v SQLite, reprezentácia booleanov ani zaokrúhľovanie dátumov nikdy nespôsobia planý poplach.

Normalizácia podľa tagu

Každé pravidlo radšej odmietne výnimkou CanonicalizationException, než by hádalo. Null si ponechá deklarovaný tag, takže null ≠ '' ≠ '0' ≠ 0 ≠ false:

Tag	Kanonická hodnota	Odmietne
`str`	Presné bajty; musia byť platné UTF-8.	neplatné UTF-8 (invalid_utf8) — deklarujte binary()
`int`	Desiatkové číslo bez + a úvodných núl; -0 → 0; ľubovoľná dĺžka sa zachová presne.	čokoľvek iné (not_integer)
`dec:N`	Znamienko + celá časť + . + presne N číslic; float sa zmení na najkratšie presné číslice, nikdy nie exponent; -0.00 → 0.00.	viac než N nenulových desatinných číslic (not_representable), NaN/INF, reťazce s exponentom
`flt:N`	Zaokrúhlené half-even na N, oddeľovač ., bez oddeľovača tisícov (stratové z definície).	NaN/INF
`bool`	'1' / '0'	čokoľvek okrem bool, 0/1, t/f, true/false (not_boolean)
`dt`	Hodnota bez zóny sa berie tak, ako je zapísaná (Y-m-d\TH:i:s.uuuuuu); hodnota s posunom sa prevedie na UTC (…\Z). Tieto dva tvary sa nikdy nezhodujú.	nečitateľné (invalid_datetime)
`date`	Y-m-d pre dátum alebo polnoc; iný čas sa zachová v tvare dt.	invalid_date
`json`	JCS dekódovanej hodnoty (veľké celé čísla ako reťazce, hĺbka ≤ 64).	neplatný JSON (invalid_json), hĺbka > 64
`bin`	base64url	—
`auto`	int → int, bool → bool, string → str, null → null.	float (float_requires_declaration)

Dokument pečate

{"alg":"hmac-sha256","at":"2026-10-02T18:30:00.000000Z","ctx":"","f":[["a:amount","dec:2","10.50"],["a:paid","bool","1"],["a:status","str","paid"],["c:lines","json","[{\"qty\":1,\"sku\":\"A-1\"}]"]],"id":"42","kid":"default-20261002-k3f9qa","prev":null,"ring":"default","scope":"","seal":"financial","table":"invoices","type":"App\\Models\\Invoice","v":"sentinel.seal/1","ver":"7"}

Členy (všetky reťazce alebo null, kľúče v poradí JCS): alg, at (sealed_at v UTC s mikrosekundami), ctx (sentinel.context), f (n-tice polí zoradené podľa názvu), id, kid, ring, prev (base64url SHA-256 z MAC predošlej pečate, alebo null), scope, seal, table (bez prefixu), type (morph trieda), v = sentinel.seal/1 a ver.
Vstupom MAC sú UTF-8 bajty tohto JCS textu — RFC 8785 s presnými celými číslami namiesto zaokrúhľovania nad 2⁵³.
Doménová separácia viaže riadok, model, tabuľku, pečať, scope tenanta, kontext aplikácie, verziu aj reťaz; ostatné dokumenty majú vlastné v (sentinel.seal-attributes/1, sentinel.ledger/1, sentinel.checkpoint/1, sentinel.field/1, sentinel.anchor/1) a reťazce HKDF info sa líšia podľa účelu.
Neviaže sa: názov pripojenia, ktorý je citlivý na premenovanie — pri databáze na tenanta použite scope().

Značky polí

Každá značka poľa je prvých 16 bajtov HMAC-SHA-256 nad identitou a hodnotou poľa, zakódovaných v base64url a uložených ako field_tags. Vznikajú len pri kľúčoch HMAC so zapnutými značkami polí; asymetrické pečate ukladajú null. Pri neplatnom MAC sú zmenenými atribútmi názvy, ktorých prepočítaná značka sa líši. Úprava značiek len zavádza diagnostiku — žiadne rozhodnutie sa na nich nezakladá: či sa posunuli len vypočítané hodnoty, dokazuje samostatný MAC atribútov.

Prejavte lásku k open source

Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.

Ďalšie spôsoby podpory vrátane kryptomien

Odoslaním daru súhlasíte s našimi podmienkami prijímania darov.

Podporte našu open-source prácu Pridajte sa k nám na Patreone

Chcete to zabudovať do svojho produktu?

Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.

Ponuka do 48 hodín Prezrieť všetky balíky