Sentinel For Laravel Laravel Package

Getting Started

• Require the package and confirm the transitive crypto dependency resolves to crypto-for-laravel ^1.2.0:

  composer require <vendor>/<package>
  composer show <vendor>/crypto-for-laravel
  

• Publish any package config and generate/store the master key material outside version control:

  php artisan vendor:publish --tag=<package>-config
  php artisan <package>:key-generate   # if provided
  

• Look first at:
  • config/<package>.php — key source, default context/info strings, cipher choices.
  • The package facade/contract — usually the encrypt/decrypt or derive-subkey entry point.
  • The README's “basic usage” example — verify it matches the installed version.
• First use case: derive a purpose-specific subkey, encrypt one value, then decrypt it in a test:

  $ciphertext = Package::encryptString('secret', context: 'user-pii');
  $plaintext  = Package::decryptString($ciphertext, context: 'user-pii');
  

• Run the package's frozen format-vector tests after install; 1.2.2 promises byte-identical HKDF output, so existing vectors should pass unchanged.

Implementation Patterns

• Context/purpose separation. Use distinct HKDF info/context strings per domain (user-pii, payment-token, queue-payload). Treat them like namespaced keys; this is the main day-to-day leverage point.
• Envelope encryption. Keep the long-lived master key static, derive short-lived data-encryption keys via HKDF for each record or batch, and store the derived-key metadata alongside the ciphertext.
• Eloquent casts. Wrap encrypted attributes in a custom cast that supplies a model-specific context:

  protected $casts = [
      'ssn' => EncryptedWithContext::class.':user-pii',
  ];
  

• Queued jobs. Derive subkeys inside the job from the configured master key; never serialize raw keys or plaintext into the queue payload. Ensure workers have the same key environment as the web tier.
• Key rotation workflow. Prefix ciphertexts with a key/version identifier. On read, select the correct master key version; on write, always use the current version. Re-encrypt lazily or via a backfill job.
• Integration with Laravel encryption. If the package wraps or replaces Illuminate\Encryption\Encrypter, bind it in a service provider and keep the Crypt facade contract stable for existing call sites.
• Testing. Use a fixed test master key and assert against frozen vectors. For 1.2.2, assert that derived subkeys match the pre-upgrade vectors byte-for-byte.

Gotchas and Tips

• 1.2.2 is a safe maintenance upgrade. HKDF subkeys now come from crypto-for-laravel's Hash\Hkdf; output is byte-identical and RFC 5869 vectors are unchanged. No re-encryption or migration is needed.
• Dependency constraint. The package now requires crypto-for-laravel ^1.2.0. Update the lockfile and run the full suite, especially frozen format-vector tests, before deploying.
• Do not change HKDF parameters casually. Altering info, salt, hash algorithm, or output length will break decryption of previously stored ciphertext. Version the format if a change is unavoidable.
• Avoid context collisions. Reusing the same info string across unrelated features collapses your key separation. Centralize context constants and review them in code review.
• Key handling. Keep master keys in a secret manager or environment, not in config committed to source control. php artisan config:cache is fine, but changing .env requires clearing cached config.
• Debugging. Never dump master keys, derived subkeys, or plaintext in logs or exception messages. Compare against frozen vectors and check composer show if decryption fails after an upgrade.
• Extension points. Use custom key providers or context resolvers rather than forking the package. For multi-tenant apps, derive per-tenant contexts from a stable tenant identifier.
• Deployment checks. Confirm OPcache/autoload state after Composer updates, and ensure all app servers and queue workers run the same package and crypto versions.