Výnimky, stavy a enumy
Každá výnimka dedí z RoundlyConsulting\Sentinel\Exceptions\SentinelException (RuntimeException), okrem HTTP výnimiek, ktoré dedia zo Symfony HttpException a vykreslia problem details podľa RFC 9457. Správy sú anglické, určené vývojárom (HTTP správy sú preložené), a nikdy neobsahujú materiál kľúčov ani zapečatené hodnoty.
| Výnimka | Kedy |
|---|---|
InvalidSealDefinitionException | Definícia pečate sa neskompiluje — problems() vypíše všetky problémy. |
SealingMisconfiguredException | Chyby zapojenia, fail closed: notSealable, unknownSeal (vypíše deklarované pečate), unknownRing, notAMacRing (volanie MAC na kruhu, ktorý používajú pečate, denník alebo podpisy HTTP), saveOverridden, writeOutsideSealedPath, keyChanged (uloženie, ktoré mení primárny kľúč zapečateného riadku), middlewareParameter, bindingsNotSubstituted, queryModelMismatch, missingColumn, unknownModel, invalidColumn, middlewareOption, whereNeedsOneModel. |
CanonicalizationException | Hodnota sa nedá kanonizovať — field() a reason() pomenujú pole a pravidlo, nikdy nie hodnotu. |
NoSigningKeyException | V kruhu nie je aktívny kľúč so súkromným materiálom; správa uvedie premenné kľúča kruhu a v testoch odkáže na WithSentinelKeys alebo Sentinel::fake(). |
UnknownKeyException | Kid neznámy v danom kruhu (aj kid iného kruhu). |
MacVerificationException | verifyMac() odmietol MAC — reason() vráti MacRejection, ring() a keyId() kruh a kid tak, ako boli zadané (kid pred zobrazením escapujte); nikdy neobsahuje MAC, správu ani materiál kľúča. |
KeyIntegrityException | Riadok kľúča v databáze nesúhlasí so svojou obálkou. |
InvalidKeyMaterialException | Materiál kľúča odmietnutý (kódovanie, dĺžka, slabé tajomstvo, nesúlad krivky, súkromný materiál pri importe len na overovanie, …). |
AlgorithmNotAllowedException | Algoritmus mimo allowlistu — notHmac, keď mac() narazí na podpisový kľúč Ed25519 či ECDSA. |
KeyDriverException | Odmietnutia v životnom cykle kľúča: readOnly, customDriver (rotácia kruhu, ktorý podpisuje kľúčom vlastného drivera), ringBusy (MySQL/MariaDB: iná rotácia kruhu držala zámok dlhšie než innodb_lock_wait_timeout), notStoredInDatabase, keyIdTaken, reasonRequired, invalidKeyId, invalidLabel. |
ConcurrentSealException | Prehraný súbeh (zápis sa vráti). |
SealingFailedException | Pečatenie alebo overenie neuloženého modelu (notPersisted — seal(), verify(), verifyAll(), isIntact()) / riadok zmizol počas pečatenia. |
TamperedModelException | verifyOrFail(), zamietnutý zápis, zamietnutá hromadná aktualizácia — result() / results(). |
SealingSuspensionNotAllowedException | withoutSealing() pri vypnutom allow_suspension. |
AcknowledgementDeniedException | Potvrdenie / odpečatenie / baseline zamietnuté: reason, reasonTooLong, actorRequired, unauthorized. |
LedgerIsAppendOnlyException | Eloquent update či delete záznamu denníka alebo kontrolného bodu. |
LedgerIntegrityException | LedgerReport::throwIfViolated() — findings() vráti porušenia. |
AnchorPublishException | Kotva odmietla kontrolný bod (diverged — drží taký, s ktorým databáza už nesúhlasí) alebo jej úložisko ohlásilo neúspešný zápis (notWritten); beh kontrolného bodu ju zachytí a nahlási AnchorPublishFailed. |
InvalidSentinelConfigurationException | Neplatná konfigurácia; vyhodí sa pri prvom použití a nikdy ju nenahradí predvolená hodnota — správa uvedie kľúč (pri booleane aj zadanú hodnotu). |
InvalidPurposeException | Účel nonce mimo povolenej abecedy. |
IdempotentResultException | idempotency()->run() vrátilo niečo, čo sa nedá uložiť ako JSON — callback prebehol, kľúč sa dokončí ako neprehrateľný. |
HTTP výnimky
| Výnimka | Status | code |
|---|---|---|
Http\Exceptions\SealVerificationFailedHttpException | middleware.verified_status (409) | — (všeobecná správa) |
IdempotencyKeyMissingException | 400 | idempotency_key_missing |
InvalidIdempotencyKeyException | 400 | invalid_idempotency_key |
IdempotencyKeyReusedException | 422 | idempotency_key_reused |
IdempotencyRequestInProgressException | 409 + Retry-After | idempotency_request_in_progress |
IdempotentResponseUnavailableException | 409 | idempotent_response_unavailable |
NonceRejectedException | 403 | nonce_rejected |
HttpSignatureException | 401 (+ Accept-Signature) | signature_rejected |
Telá problémov nesú type (ak je nakonfigurovaný), title, status, detail a code s Content-Type: application/problem+json; type je problems.type_base#code a title aj detail sú preložené. Rodina idempotencie zdieľa abstraktnú IdempotencyException — rejection() vráti IdempotencyRejection, retryAfterSeconds() hodnotu Retry-After — a HttpSignatureException má reason() a keyId().
Stavy overenia
Hodnoty VerificationStatus sú zmrazené; názvy prípadov sú tvary hodnôt v StudlyCase. isIntact() a isFailure() uplatňujú to isté pravidlo ako VerificationResult::isIntact() a preložené názvy sú v sentinel::statuses:
| Prípad | Hodnota | Neporušený? |
|---|---|---|
Intact | intact | áno |
Outdated | outdated | áno, pokiaľ nie je vypnuté verification.outdated_is_intact |
Unsealed | unsealed | áno (benevolentné pečate) |
Tampered | tampered | nie |
Missing | missing | nie |
Stale | stale | nie |
UnknownKey | unknown_key | nie |
RevokedKey | revoked_key | nie |
RetiredKey | retired_key | nie |
AlgorithmNotAllowed | algorithm_not_allowed | nie |
AlgorithmMismatch | algorithm_mismatch | nie |
Malformed | malformed | nie |
Unverifiable | unverifiable | nie |
Dôvody: mac, computed, canonicalization, ledger_entry (tampered); seal_deleted, never_sealed, unsealed (missing); newer_version, not_in_ledger, ledger_mismatch, entity_recreated (stale); ring_not_accepted, not_found, pending, integrity (unknown key); missing_attribute, missing_computed, error (unverifiable).
Enumy
Všetky žijú v RoundlyConsulting\Sentinel\Enums, sú zmrazené a používajú pomocníkov enums-for-laravel (values(), names(), labels(), options(), fromName(), tryFromName(), label(), is(), isIn(), …). Zmena hodnoty je hlavné vydanie:
| Enum | Prípady | Pomocníci |
|---|---|---|
Algorithm | HmacSha256, HmacSha384, HmacSha512, Ed25519, EcdsaP256Sha256, EcdsaP384Sha384 | isHmac(), isAsymmetric(), isHttpRegistered(), hashName(), hashLength(), hashAlgorithm(), cryptoAlgorithm() |
KeyStatus | Pending, Active, VerifyOnly, Retired, Revoked | canSign(), canVerify() |
KeyDestination | Config, Database | — |
SealEvent | Sealed, Resealed, Acknowledged, Baseline, Rotated, Deleted, Unsealed | isTombstone() |
VerificationContext | Api, Middleware, Retrieve, Command, Rule, Collection, Write | — |
Reaction | Throw, Report | — |
TamperedWritePolicy | Refuse, Reseal, Skip | — |
LedgerFindingKind | CheckpointGap, CheckpointInvalid, CheckpointMismatch, ChainBroken, AnchorAhead, AnchorMismatch, AnchorInvalid, AnchorUnreachable, EntryInvalid, OrphanEntry, EntityDeleted, SealRolledBack, SealMissing, Backlog | isViolation() |
IdempotencyRejection | Missing, Invalid, Reused, InProgress, Unavailable | status() |
IdempotencyOutcome | Proceed, Replay, InProgress, Reused, Unavailable | — |
SignatureRejection | Missing, Malformed, Ambiguous, MissingParameter, MissingComponent, UnsupportedComponent, UnsupportedAlgorithm, UnknownKey, RevokedKey, AlgorithmMismatch, AlgorithmNotAllowed, TagMismatch, NotYetValid, TooOld, Expired, DigestMismatch, UnsupportedDigest, InvalidSignature, Replayed | — |
MacRejection | UnknownKey, PendingKey, RetiredKey, RevokedKey, UnsupportedAlgorithm, AlgorithmNotAllowed, Malformed, Mismatch | — |
DigestAlgorithm | Sha256, Sha512 | hashAlgorithm() |
HealthStatus | Ok, Warning, Failure | — |
NonceKind | Issued, Seen | — |
PersistOperation | Save, Delete, Increment | — |
TypeKind | Auto, String, Integer, Decimal, Float, Boolean, DateTime, Date, Json, Binary, Null, Plaintext | hasScale(), isDeclarable() |
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 kryptomienOdoslaním daru súhlasíte s našimi podmienkami prijímania darov.
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.