Database schema

Six publish-only, forward-only migrations (no down(), timestamp-injected when published, never auto-loaded). No package table uses soft deletes and no model is swappable — security state is persisted only through these models and the engine.

Seals, ledger and checkpoints live on each sealable model’s connection and share its transaction. Hosts with sealables on several connections publish and run 0002–0004 per connection and list them in ledger.connections.

Upgrading from a pre-release build

Migration 0004_create_sentinel_seals_table was edited in place to add the nullable attributes_mac column (the MAC of the attribute document, for seals with computed fields); there is no new migration. If you ran an earlier pre-release copy, re-publish the migrations and re-run 0004, or add the column to sentinel_seals yourself — string('attributes_mac', 192)->nullable() — before the next sealed write. Installs from the current migrations already have it.

Models

Read them for reporting (Seal::query()->where('key_id', $kid)->count()), never write them: the engine owns every write, and the MACs, chain and envelopes catch edits. Every package timestamp is cast with Casts\UtcDateTime (UTC, microseconds, CarbonImmutable), so the application’s time zone never leaks into stored or MAC’d times.

Factories

• KeyFactory — ->hmac(), ->ed25519(), ->ecdsaP256(), ->verifyOnly(), ->revoked(), ->retired(), ->pending(), ->ring(), all with valid envelopes.
• SealFactory — ->forSealable(Model $m, string $seal), structurally valid but unsigned: for Malformed and negative tests.
• LedgerEntryFactory — ->forSealable(Model $m, string $seal), ->tombstone(SealEvent $event = SealEvent::Deleted); plus CheckpointFactory.
• IdempotencyKeyFactory — ->processing(), ->completed(), ->expired().
• NonceFactory — ->issued(), ->seen(), ->consumed(), ->expired().

Retention

Protecting the tables

Sentinel detects changes to these tables too, but database grants make tampering harder in the first place. The application user needs INSERT and SELECT on sentinel_ledger and sentinel_checkpoints, only UPDATE (checkpoint_id) on the ledger, and the one row-lock privilege each engine asks for, because sentinel:checkpoint locks the checkpoint tail with SELECT … FOR UPDATE. Never DELETE. Keep the anchor store’s credentials away from the database’s.

-- PostgreSQL
GRANT SELECT, INSERT ON sentinel_ledger, sentinel_checkpoints TO app;
GRANT UPDATE (checkpoint_id) ON sentinel_ledger TO app;
GRANT UPDATE (seq) ON sentinel_checkpoints TO app;

-- MySQL
GRANT SELECT, INSERT ON app_db.sentinel_ledger TO 'app'@'%';
GRANT SELECT, INSERT ON app_db.sentinel_checkpoints TO 'app'@'%';
GRANT UPDATE (checkpoint_id) ON app_db.sentinel_ledger TO 'app'@'%';
GRANT LOCK TABLES ON app_db.* TO 'app'@'%';