Security & Resources

This section details two important fields in blocklet.yml: signatures and resource. The signatures field is critical for establishing a chain of trust and verifying the integrity of the blocklet's metadata. The resource field provides a mechanism for a blocklet to define, export, and consume shared assets and data types, enabling greater modularity and interoperability within the ecosystem.

Signatures#

The signatures array provides a cryptographic guarantee that the blocklet's metadata has been approved by a series of signers (e.g., the developer, the registry) and has not been tampered with. This multi-signature mechanism is fundamental to the security and trustworthiness of blocklets.

Signature Verification Process#

The verification process works as a chain. Each signature is verified sequentially, starting from the last one added. When a new signature is created, it signs the current state of the blocklet's metadata, including all previous signatures. This creates an auditable chain of trust.

To allow for a workflow where a registry adds information (like distribution URLs) after the developer has signed, the schema includes appended and excludes fields. A signer can declare which fields they are adding in the appended array. When a previous signature is verified, any fields listed in subsequent appended arrays are ignored, ensuring the original signature remains valid.

Signature Schema#

Each object within the signatures array must conform to the following structure:

Property	Type	Description
type	string	The signature type (e.g., 'ED25519'). Required.
name	string	A human-readable name for the signature (e.g., 'developer', 'registry'). Required.
signer	string	The DID of the entity that created the signature. Required.
pk	string	The public key associated with the signer's DID. Required.
created	string	The ISO 8601 timestamp of when the signature was created. Required.
sig	string	The cryptographic signature itself. Required.
excludes	string[]	An optional array of top-level field names to exclude from the signed payload for this specific signature.
appended	string[]	An optional array of top-level field names that were added by this signer. These fields will be automatically excluded from verification by preceding signers.
delegatee	string	The DID of the delegatee, if using a delegation token.
delegateePk	string	The public key of the delegatee.
delegation	string	The JWT representing the delegation permission (e.g., 'publish_blocklet').

Delegated Publishing (CI/CD)#

The delegatee, delegateePk, and delegation fields are designed for scenarios like automated publishing from a CI/CD pipeline. Instead of storing the developer's primary wallet in the CI environment, the developer can issue a short-lived delegation token (JWT) granting a temporary key the permission to sign on their behalf. The signature is created by the delegatee key, but the signer field still holds the developer's DID, maintaining the chain of trust.

Example#

In this example, the developer signs the metadata first. They use appended to declare that fields like dist and stats will be added later by the registry. The registry then adds its own signature. A verification client would know to ignore the dist, stats, and logoUrl fields when checking the developer's original signature.

Resources#

The resource field allows a blocklet to declare the types of resources it provides or consumes, and to bundle other blocklets as resources. This is particularly useful for creating composable applications where one blocklet might provide a 'database' or 'storage' resource that other blocklets can use.

Resource Schema#

The resource object has the following properties:

Property	Type	Description
exportApi	string	A path to a file that exports the blocklet's resource API.
bundles	ResourceBundle[]	An array of other blocklets that are bundled as resources.
types	ResourceType[]	An array of resource types that this blocklet can provide or consume, with a maximum of 10 types.

ResourceBundle Object#

Property	Type	Description
did	string	The DID of the resource blocklet being bundled. Required.
type	string	The type of resource this bundle represents. Required.
public	boolean	Indicates if the resource is publicly accessible.

ResourceType Object#

Property	Type	Description
type	string	A unique identifier for the resource type (e.g., 'database', 'file-storage'). Required.
description	string	A human-readable description of the resource type.

Example#

In this example, the blocklet declares that it offers a resource of type image-storage. It also bundles another blocklet (identified by its DID) as a non-public storage-engine to fulfill this role.

Understanding how to correctly configure signatures and resources is key to building secure and modular blocklets. Now that you are familiar with the blocklet.yml specification, you can explore the API Reference to see how the @blocklet/meta library helps you work with these configurations programmatically.