Blocklet/Component Signature
This section describes the Express.js middleware provided by the Blocklet SDK for verifying digital signatures on requests. These middlewares are crucial for securing inter-service communication within the Blocklet Server ecosystem, ensuring that incoming requests from other Blocklets or components are authentic and untampered.
For a general overview of all available middlewares, refer to the Middleware Reference section.
verifyBlockletSig Middleware#
The verifyBlockletSig middleware is designed to validate requests originating from other Blocklets. It checks for specific x-blocklet- prefixed headers to ensure the authenticity and integrity of the request.
Usage#
To use this middleware, integrate it into your Express.js route definitions. It should be applied to routes that expect signed requests from other Blocklets.
import express from 'express';
import { middleware as sdkMiddleware } from '@blocklet/sdk';
const app = express();
// Example route that requires a Blocklet signature
app.post('/api/blocklet-data', sdkMiddleware.verifyBlockletSig, (req, res) => {
// If we reach here, the Blocklet signature is valid
res.json({ message: 'Blocklet data received and verified' });
});
// Start your Express server
app.listen(3000, () => {
console.log('Server listening on port 3000');
});Parameters#
This middleware takes standard Express.js middleware parameters:
Name | Type | Description |
|---|---|---|
|
| The Express request object. |
|
| The Express response object. |
|
| The callback function to pass control to the next middleware. |
Error Handling#
If the x-blocklet-sig header is missing, the middleware responds with a 400 Bad Request status. If the signature verification fails (e.g., due to an invalid signature or expired timestamp), it responds with a 401 Unauthorized status.
Example Error Response (400 Bad Request)
{
"error": "Bad Request"
}Example Error Response (401 Unauthorized)
{
"error": "verify sig failed"
}component.verifySig Middleware#
The component.verifySig middleware functions similarly to verifyBlockletSig but is intended for more general component-to-component communication within the Blocklet Server environment. It relies on x-component- prefixed headers for signature verification.
Usage#
Integrate this middleware into your Express.js routes where you expect signed requests from other Blocklet Server components.
import express from 'express';
import { middleware as sdkMiddleware } from '@blocklet/sdk';
const app = express();
// Example route that requires a component signature
app.post('/api/component-event', sdkMiddleware.component.verifySig, (req, res) => {
// If we reach here, the component signature is valid
res.json({ message: 'Component event received and verified' });
});
// Start your Express server
app.listen(3000, () => {
console.log('Server listening on port 3000');
});Parameters#
This middleware also takes standard Express.js middleware parameters:
Name | Type | Description |
|---|---|---|
|
| The Express request object. |
|
| The Express response object. |
|
| The callback function to pass control to the next middleware. |
Error Handling#
If the x-component-sig header is missing, the middleware responds with a 400 Bad Request status. If the signature verification fails, it responds with a 401 Unauthorized status.
Example Error Response (400 Bad Request)
{
"error": "Bad Request"
}Example Error Response (401 Unauthorized)
{
"error": "verify sig failed"
}How Signature Verification Works#
Both verifyBlockletSig and component.verifySig utilize the underlying getVerifyData and verify utility functions from the Blocklet SDK. The process involves extracting specific HTTP headers to reconstruct the original data payload and then verifying it against the provided signature using cryptographic methods.
Here's a high-level overview of the signature verification flow:
Key Headers Involved:
x-{type}-sig: The digital signature of the request payload.x-{type}-sig-pk: The public key used to sign the request. This is optional and typically used when verifying a signature from an unknown or dynamic DID.x-{type}-sig-version: The version of the signature algorithm used. This allows for backward compatibility and future updates. VersionV0is a legacy format, while newer versions include more structured data for verification.x-{type}-sig-iat: The 'issued at' timestamp (in seconds since epoch) when the signature was created. Used for freshness checks.x-{type}-sig-exp: The 'expiration' timestamp (in seconds since epoch) when the signature becomes invalid. Used to prevent replay attacks.
The type placeholder in the headers will be either blocklet for verifyBlockletSig or component for component.verifySig.
The data payload that gets signed and verified depends on the sigVersion:
- For
sigVersion>V0: The data includesiat,exp,body(parsed JSON),query(parsed from URL and request object),method(lowercase HTTP method), andurl(pathname only). - For
sigVersion==V0(Legacy): The data includes the rawbodyandqueryobjects as received.
These middlewares are essential for building secure and trustworthy Blocklet applications that communicate reliably within the Blocklet Server ecosystem.
Now that you understand how to verify signatures from other Blocklets and components, you might want to explore other security-related middlewares like CSRF Protection or delve into Authentication for user-facing requests.