Download the PHP package zobayer/encapsula without Composer
On this page you can find all versions of the php package zobayer/encapsula. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download zobayer/encapsula
More information about zobayer/encapsula
Files in zobayer/encapsula
Package encapsula
Short Description Laravel API response encryption middleware with frontend decoding support.
License MIT
Homepage https://github.com/shudhuiami/Encapsula
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package encapsula
Encapsula
Laravel API response encryption middleware with frontend decoding support.
Encapsula encrypts JSON API responses at the middleware level using AES-256-GCM authenticated encryption. The frontend receives an encrypted payload envelope and decrypts it before use. This adds a layer of obfuscation to API responses visible in browser developer tools, while keeping integration simple for Laravel APIs and modern frontend applications.
Important: Encapsula does not replace HTTPS. TLS is still required for transport security. This package provides application-level payload encryption as an additional layer. Authenticated users can still access the decrypted data in their browser after the frontend decrypts it.
Packages
Encapsula has two package layers in the same repository:
| Package | Registry Link | Purpose | Path |
|---|---|---|---|
zobayer/encapsula |
https://packagist.org/packages/zobayer/encapsula | Laravel backend middleware for protected API responses | repository root |
encapsula-client |
https://www.npmjs.com/package/encapsula-client | JavaScript/TypeScript frontend decoder for Vue, React, Next.js, Nuxt, Vite, Axios, Fetch, and Node clients | packages/client |
For simple projects without npm, standalone copy-paste helpers are kept in frontend/.
Requirements
- PHP 8.2+
- Laravel 10, 11, 12, or 13
- OpenSSL extension with AES-256-GCM support
- Node.js/npm only if you want to use the optional frontend client package
Backend Installation
Install the Laravel package:
Quick Setup Command (recommended)
You can scaffold the required .env values with:
Common usages:
The service provider is auto-discovered. To register manually, add to config/app.php:
Publish Configuration
Set Encryption Key
Add to your .env file:
Enable/Disable Encryption
To disable encryption globally at runtime (feature flag):
Generate a key:
Optional: Override Algorithm
Optional: Session Key Handshake (no static frontend secret)
If you don't want to ship a long-lived ENCAPSULA_KEY in your frontend bundle, you can enable session mode.
In this mode, the frontend establishes a per-session AES key using ECDH (P-256) + HKDF-SHA256, and the backend stores it in the server session.
Backend .env:
Important:
- The handshake route must run under session middleware (default is
web). - You should add your own auth middleware to the handshake route via
config/encapsula.phpif needed. - After the handshake succeeds, subsequent responses encrypted by
encapsula.encryptwill use the session key.
Frontend Installation
For npm-based projects, install the client package:
Use this package in Vue, React, Next.js, Nuxt, Vite, Axios, Fetch, or Node-based frontend projects.
For non-npm projects, use the standalone helper files in:
Quick Start
1. Apply Middleware to Laravel Routes
2. Encrypted Response Format
When middleware is active, JSON responses are wrapped in an encrypted envelope:
3. Decode in Frontend with the npm Package
4. Axios Usage
5. Fetch Wrapper Usage
6. Node Usage
7. Vanilla JavaScript Usage
For projects without npm, copy the standalone helper from:
Example:
Configuration
After publishing (php artisan vendor:publish --tag=encapsula-config), edit config/encapsula.php:
| Option | Type | Default | Description |
|---|---|---|---|
enabled |
bool |
true |
Enable or disable response encryption globally. |
key_mode |
string |
'static' |
Key source: 'static' (single key) or 'session' (derived per session). |
key |
string |
env('ENCAPSULA_KEY') |
Base64-encoded 32-byte encryption key (used when key_mode=static). |
handshake.enabled |
bool |
false |
Enable the session handshake endpoint (required when key_mode=session). |
handshake.path |
string |
'/encapsula/handshake' |
Path for the handshake route. |
handshake.middleware |
array |
['web'] |
Middleware applied to handshake route (must include sessions). |
handshake.session_key |
string |
'encapsula.session_key' |
Session key name used to store derived base64 AES key. |
algorithm |
string |
'aes-256-gcm' |
OpenSSL cipher algorithm (ENCAPSULA_ALGORITHM). |
exclude |
array |
[] |
Route name patterns to skip encryption (e.g. 'login', 'health.*'). |
envelope.encrypted_field |
string |
'encrypted' |
Name of the boolean flag field in the envelope. |
envelope.payload_field |
string |
'payload' |
Name of the ciphertext field. |
envelope.iv_field |
string |
'iv' |
Name of the initialization vector field. |
envelope.tag_field |
string |
'tag' |
Name of the authentication tag field. |
envelope.algorithm_field |
string |
'alg' |
Name of the algorithm identifier field. |
Middleware Behavior
The middleware:
- Encrypts JSON responses (
Content-Type: application/json). - Skips redirects, streamed responses, binary/file downloads, empty responses, and non-JSON content.
- Skips routes matching the
excludepatterns. - Passes through unchanged when
enabledisfalseor no key is configured.
Security Limitations
- Not a replacement for HTTPS. Always use TLS for transport-layer security.
- Browser-side decryption means authenticated users can access decrypted data. This prevents casual inspection of network responses but does not hide data from the authenticated user.
- Frontend keys are visible in built frontend apps when they are shipped to the browser. If you want to avoid shipping a long-lived key, use the optional session handshake mode.
- Key management is the application's responsibility. Rotate keys carefully and consider a key rotation strategy for production.
- This is obfuscation, not access control. Use proper authorization (policies, gates, scopes) to restrict which data is returned by your API.
Development
License
MIT. See LICENSE for details.
All versions of encapsula with dependencies
illuminate/support Version ^10.0|^11.0|^12.0|^13.0
illuminate/validation Version ^10.0|^11.0|^12.0|^13.0