Download the PHP package crumbls/sealcraft without Composer

Sealcraft

KMS-backed, field-level encryption for Laravel. Runs alongside Laravel's built-in Crypt -- it does not replace it.

• Laravel: 11, 12, 13
• PHP: 8.2+
• Providers: AWS KMS, GCP Cloud KMS, Azure Key Vault, HashiCorp Vault Transit, Local (dev/test), Null (testing)
• Ciphers: AES-256-GCM (default), XChaCha20-Poly1305 (via libsodium)
• One-command onboarding: php artisan sealcraft:install && php artisan sealcraft:verify
• Full documentation: https://www.crumbls.com/documentation/sealcraft

What this is

Sealcraft encrypts specific database columns with short-lived Data Encryption Keys (DEKs) that are wrapped by a long-lived Key Encryption Key (KEK) inside a cloud KMS. Use it when a particular column needs KMS-backed key custody, documented rotation, per-tenant isolation, or cryptographic destruction on demand.

Sealcraft does not replace Laravel's Crypt facade or encrypted cast. Those keep doing what they do best -- sessions, cookies, signed URLs, queue payloads, and casual field encryption where APP_KEY custody is acceptable. Most apps that adopt Sealcraft still use Crypt everywhere else.

Use cases

• Healthcare (HIPAA-adjacent): patient SSN/DOB/diagnosis, telehealth notes, insurance IDs -- including right-to-be-forgotten via one-shot crypto-shred of the patient's DEK.
• Financial services: bank account numbers, ABA routing, tax IDs, payout destination details on a marketplace.
• Multi-tenant SaaS: one DEK per tenant so a stolen DB dump means one-per-tenant unwrap attempts, not a single APP_KEY unlocking every customer. Per-tenant crypto-shred on cancellation.
• Identity / auth: stored OAuth refresh tokens, third-party API keys, MFA backup codes, KYC documents (passport / DL / national ID).
• Legal / compliance: privileged communications, protected-identity fields, GDPR Article 17 fulfillment across warehouses and backups via crypto-shred.
• Consumer apps: encrypted notes, journals, personal vaults where users expect that an internal DB reader alone cannot see content.
• B2B SaaS: CRM PII in strict-privacy jurisdictions, HR data (salaries, DOB, home addresses), sensitive contract metadata.

How it works: a plaintext DEK is unwrapped on demand, cached in memory for the request, and the primary DEK reference is best-effort zeroed at request termination. PHP's string immutability and copy-on-write semantics mean transient copies created inside cipher and KMS provider calls may persist until garbage collection; the zeroing guarantee covers the single in-memory cache slot only. Rotating the KEK rewraps one DB row per tenant; column ciphertext never changes.

When NOT to use this

• Sessions, cookies, signed URLs, queue payloads. Those are Laravel Crypt's job; Sealcraft is not designed for them.
• You need WHERE encrypted_col = ? queries. Searchable / blind-indexed encryption is out of scope for v1. Plan is to integrate CipherSweet-style blind indexing in v2.
• Single-tenant app with no compliance story. Laravel's built-in encrypted cast is fine -- you won't get your money's worth out of the extra operational surface.
• You can't run a KMS and don't want to. Sealcraft's local file provider is for development only and refuses to run in production without an explicit opt-in flag.

Install

sealcraft:install publishes config, publishes the migration, and runs migrate. sealcraft:verify round-trips a synthetic DEK through your configured provider and cipher so you know the deploy is actually wired up. Both commands are idempotent.

If you need to run the steps manually (for example in a CI pipeline that runs migrations separately), the low-level form still works:

Provider SDKs are optional — install only what you use:

Quick start

Model integration

That's it. Reads and writes transparently encrypt. Null values stay null.

Structured columns — encrypt JSON leaves while preserving shape

Need to keep a column queryable as a JSON tree (so admin tools, analytics, or schema validators can see keys and structure) while protecting the inner values? Use the EncryptedJson cast.

On disk, the column stays valid JSON — every leaf string is individually encrypted under the same DEK as the row's scalar encrypted columns, while keys, nesting, and non-string scalars (ints, floats, bools, nulls) remain readable. On read, leaves that carry a cipher prefix are decrypted; strings without a prefix pass through unchanged so columns can mix plaintext shape data with encrypted leaves.

AWS KMS

.env:

GCP Cloud KMS

Bind your token resolver in a service provider (ADC, workload identity, etc.):

Azure Key Vault

Azure's wrapKey/unwrapKey don't accept AAD natively. The default synthetic strategy prepends an HMAC-SHA256 of the canonical context over the DEK and verifies it on unwrap — defense-in-depth equivalent to AWS/GCP. Switch to cipher_only if you can accept relying solely on cipher-layer AAD plus Key Vault RBAC.

Bind the token resolver and (for synthetic AAD) an HMAC key resolver:

HashiCorp Vault Transit

Local (dev/test only)

Refuses to load in production unless SEALCRAFT_LOCAL_ALLOW_PRODUCTION=true.

Encryption contexts

Every DEK is bound to an encryption context — a (type, id) pair plus optional scalar attributes. The context canonicalizes to stable UTF-8 bytes (NFC-normalized, byte-sorted keys, escaped separators, 4KB cap) and is used as AAD at the cipher layer, and, where the provider supports it, at the wrap layer too. A cross-context decrypt attempt fails authentication.

Configure a model's context with a single $sealcraft array:

Only the keys that differ from defaults need to be set.

Per-group (default) — one DEK per tenant / user / patient

Every row sharing a context value uses one DEK. KEK rotation rewraps one row per context. Best for multi-tenant SaaS.

Per-row — one DEK per record

Each row carries its own sealcraft_key column (auto-populated UUID) and gets its own DEK. Best for vault-style rows where each row is an independent security boundary.

Add sealcraft_key string(191) nullable index to your model's migration.

Delegated context — user "passes" their key to related models

A record delegates its context to a parent so all of a user's data across multiple tables shares one DEK. This is the HIPAA primitive for one-shot crypto-shred.

Per-column override — one model, multiple contexts

Most models use one context for all encrypted columns. When you need to split — for example, a patient record where most fields belong to the patient but one field belongs to the employer who issued it — pass type= and column= as cast parameters:

The two context bindings are independent — shredding the patient destroys ssn and history but leaves work_notes readable until the employer context is shredded separately.

The legacy form — four separate properties ($sealcraftStrategy, $sealcraftContextType, $sealcraftContextColumn, $sealcraftRowKeyColumn) — still works. The $sealcraft array is the recommended form going forward.

Changing context (tenant moves, record re-owned)

Changing the context column on an existing row is a security-sensitive event. Sealcraft's default is to auto-reencrypt on save:

Two events fire:

• ContextReencrypting (pre, cancellable via return false)
• ContextReencrypted (post, for audit log)

Set SEALCRAFT_AUTO_REENCRYPT=false to require explicit migration via sealcraft:reencrypt-context instead — the trait throws InvalidContextException on any uncoordinated context change. Wire the events to your SIEM regardless.

Right-to-be-forgotten: crypto-shred

Permanent destruction of a user's data without DELETE-ing anything:

Or:

After shred, every ciphertext ever wrapped under that context becomes cryptographically unrecoverable. Reads raise ContextShreddedException (a separate exception from DecryptionFailedException, so apps can render a "record destroyed at user request" message instead of a 500). Writes to a shredded context also fail with ContextShreddedException, preventing accidental resurrection.

The DekShredded event fires on success — wire it to your compliance audit log.

Key rotation playbook

KEK rotation (rotate the wrapping key)

Fast. No data is re-encrypted. Just rewraps each DataKey under the current KEK version.

Run during normal operation — the existing DataKey's stored KEK version keeps older data decryptable during the rotation window.

DEK rotation (rotate the data key itself)

Slower. Synchronously decrypts every row under the old DEK, re-encrypts under a new DEK, then retires the old DEK. Run during a maintenance window (the command assumes no concurrent writes for the affected context).

The command acquires a DB-level advisory lock before re-encrypting rows, so two concurrent rotate-dek invocations on the same context will not race — the second fails immediately with a clear error. The lock does not block normal application writes. A concurrent application write during rotation can land under the old DEK after the command has already processed that row, leaving it unreadable once the old DEK is retired. Preventing this is the caller's responsibility; the DekRotationStarting event is fired immediately before re-encryption begins and can be used to wire a write-gating listener if your deployment requires true write-quiescence.

Provider migration (move from one KMS to another)

Operational commands

All destructive commands support --dry-run.

Operational caveats

• Per-row strategy: empty row-keys are a hard error. If a saved row has NULL or empty in its row-key column (default sealcraft_key), sealcraftContext() throws InvalidContextException instead of minting a throwaway UUID. Silently minting would orphan a fresh DEK on every read and guarantee decryption failure, since the original ciphertext was bound to a different (also throwaway) context.
• Backfill before turning encryption on. When adopting the per-row strategy on an existing table, run php artisan sealcraft:backfill-row-keys "App\\Models\\Patient" to populate row-keys on legacy rows. The command is idempotent, supports --chunk and --dry-run, and bypasses model events so it is safe to run on tables that may already contain ciphertext.
• New rows are handled automatically. A creating hook on the trait ensures every newly INSERTed per-row model carries a row-key, even if no encrypted attribute is touched during fill.

Configuration reference

See config/sealcraft.php after publishing. Key knobs:

• default_provider — KEK provider name
• default_cipher — aes-256-gcm (default) or xchacha20
• dek_strategy — per_group (default) or per_row
• context_column, context_type — defaults for per-group models
• auto_reencrypt_on_context_change — true (default) or false
• rate_limit.unwrap_per_minute — per-context unwrap throttle (0 = disabled)

Events

Subscribe in a service provider to send to your SIEM / audit pipeline:

Performance

• Cache hit: O(1) array lookup in process memory, zero network calls
• Cache miss: one KEK provider unwrap (~10-100ms network) + one DB query to find the DataKey row
• Per-group strategy: one unwrap per tenant per request regardless of how many rows or columns you read for that tenant
• Per-row strategy: one unwrap per distinct row you read

Shred, rotation, and audit commands iterate with chunkById so they scale to 10k+ tenants.

Threat model

What Sealcraft protects against:

• Database-at-rest theft. Attackers with a stolen DB dump (or backup tape, or replica snapshot) see only ciphertext. The KEK is in the KMS, not the DB; the DEK is never persisted in plaintext.
• Cross-context ciphertext replay. An attacker who swaps ciphertext from one tenant onto another tenant's row gets an authentication failure at decrypt time — the AAD binding catches it.
• KMS enumeration. The per-context unwrap rate limit blunts attacks that try to bulk-enumerate wrapped DEKs through a compromised KMS network path.
• Right-to-be-forgotten requests. Crypto-shred instantly makes a user's data unrecoverable without requiring row-level deletion across every table (backups, audit logs, warehouses, replicas).

What Sealcraft does NOT protect against:

• Live application compromise. If an attacker executes code inside your Laravel process, they can call KeyManager just like any other service. Plaintext DEKs live in request memory by design; there is no TEE or HSM-fronted plaintext boundary.
• KMS compromise combined with DB access. If an attacker both steals the DB and owns your KMS credentials, they can unwrap DEKs. AAD binding narrows the blast radius (they still need the matching context), but it's not a complete mitigation.
• Plaintext in logs, cache, queues, or error reports. Sealcraft only encrypts DB columns. Anything you pass through dd(), Log::info(), queue payloads, or a stack trace is your responsibility. Don't log PHI.
• Key custody policy. Sealcraft manages wrapping/unwrapping; it doesn't decide who can access the KEK in your KMS. Lock that down with IAM, managed identities, least-privilege policies, and approval workflows.

Compliance notes

HIPAA and PCI-DSS expect encryption-at-rest with defensible key management — which is what envelope encryption plus a KMS gives you. Sealcraft is the key-management and cipher machinery; you still own the rest:

• Authorization and access control (who can read a row)
• PHI scrubbing in logs, stack traces, error reports, and non-sealcraft columns
• Business associate agreements (BAAs) with your KMS vendor
• Backup encryption and backup-site key management
• Incident response and breach notification procedures

Crypto-shred is necessary but not sufficient for GDPR erasure — you may still need to scrub names/emails/IDs from audit logs, telemetry, and data warehouses.

Migrating from APP_KEY / encrypted cast

The short version: back up the DB, write a one-off migration that reads each encrypted column via Crypt::decrypt, re-assigns via the Encrypted cast, and saves. Do it during a maintenance window. Keep APP_KEY around for at least one full backup cycle in case of rollback.

Testing

Integration tests for AWS KMS use mocked KmsClient; GCP, Azure, and Vault Transit use Http::fake. No live cloud credentials required.

Documentation

Full reference documentation — installation, configuration, every provider, every encryption-context strategy, every artisan command, troubleshooting, and ADRs — is published at:

https://www.crumbls.com/documentation/sealcraft

The Markdown sources live under docs/ in this repository and are versioned per release.

Contributing

Issues and PRs welcome. Run composer format and composer test before submitting.

License

MIT — see LICENSE.md.

Security disclosures

See SECURITY.md.