Security & Resources

Security and resource management are crucial for creating trustworthy and interoperable Blocklets. The blocklet.yml specification provides two key fields for this purpose: signatures to ensure the integrity and authenticity of the metadata, and resource to define and bundle shared assets for composition with other Blocklets.

This section covers the specification for these fields and introduces the utility functions provided by @blocklet/meta to work with them.

Signatures#

The signatures field contains an array of digital signatures that create a verifiable chain of trust for the Blocklet's metadata. This mechanism prevents unauthorized modifications and confirms the identity of the publishers, such as the developer and the Blocklet Store. Each signature in the chain cryptographically signs the core metadata along with any subsequent signatures, ensuring that the entire history of modifications is tamper-proof.

Multi-Signature Process Flow#

The typical multi-signature workflow during the publishing process involves the developer signing the initial metadata, followed by the Blocklet Store verifying it, adding distribution information, and appending its own signature.


Specification#

The signatures field is an array of signature objects. Each object has the following structure:

blocklet.yml

signatures:
  - type: 'ED25519'
    name: 'dev'
    signer: 'z8qa...'
    pk: 'z28n...'
    created: '2023-10-27T10:00:00.000Z'
    sig: 'z24e...'
    excludes: []
  - type: 'ED25519'
    name: 'store'
    signer: 'z8qR...'
    pk: 'z29c...'
    created: '2023-10-27T10:05:00.000Z'
    sig: 'z25a...'
    appended:
      - 'dist'
      - 'stats'
type
string
required
The cryptographic algorithm used for the signature (e.g., 'ED25519').
name
string
required
A human-readable name for the signature's role (e.g., 'dev', 'store').
signer
string
required
The DID of the entity that created the signature.
pk
string
required
The public key corresponding to the signer's DID.
created
string
required
The ISO 8601 timestamp when the signature was created.
sig
string
required
The base58-encoded signature string.
excludes
string[]
An array of top-level field names to exclude from the metadata before signing.
appended
string[]
An array of top-level field names that were added to the metadata by this signer. This is used by the next signer to correctly verify the previous signature.
delegatee
string
The DID of the delegatee if the signature was made through delegation.
delegateePk
string
The public key of the delegatee.
delegation
string
The delegation token (JWT) authorizing the `delegatee` to sign on behalf of the `signer`.

Resource Management#

The resource field allows a Blocklet to declare shared data types it can export and to bundle resources from other Blocklets. This is fundamental to enabling a composable and interoperable ecosystem where Blocklets can share data and functionality seamlessly.

Specification#

blocklet.yml

resource:
  exportApi: '/api/resources'
  types:
    - type: 'posts'
      description: 'A collection of blog posts.'
    - type: 'images'
      description: 'A gallery of images.'
  bundles:
    - did: 'z2qa...'
      type: 'user-profiles'
      public: true
resource
object

Contains properties for defining exportable types and bundled resources.

3 subfields

The @blocklet/meta library provides a suite of functions to handle the security aspects of a Blocklet's metadata and communications. For full details, see the Security Utilities API Reference.

Verifying Metadata Signatures#

The verifyMultiSig function is the primary tool for ensuring the integrity of a blocklet.yml file. It processes the signatures array, verifying each signature in the chain to confirm that the metadata has not been tampered with and was signed by the declared entities.

verifyMultiSig Example

import verifyMultiSig from '@blocklet/meta/lib/verify-multi-sig';
import { TBlockletMeta } from '@blocklet/meta/lib/types';

async function checkMetadata(meta: TBlockletMeta) {
  const isValid = await verifyMultiSig(meta);
  if (isValid) {
    console.log('Blocklet metadata is authentic and untampered.');
  } else {
    console.error('WARNING: Blocklet metadata verification failed!');
  }
}

Signing and Verifying API Responses#

For securing communications between Blocklets or between a Blocklet and a client, you can use the signResponse and verifyResponse functions. These helpers use a wallet object to cryptographically sign and verify any JSON-serializable data, ensuring data integrity and sender authenticity.

signResponse Example

import { signResponse, verifyResponse } from '@blocklet/meta/lib/security';
import { fromRandom } from '@ocap/wallet';

async function secureCommunicate() {
  const wallet = fromRandom(); // Your Blocklet's wallet
  const data = { message: 'hello world', timestamp: Date.now() };

  // Signing
  const signedData = signResponse(data, wallet);
  console.log('Signed Data:', signedData);

  // Verifying
  const isVerified = await verifyResponse(signedData, wallet);
  console.log('Verification result:', isVerified); // true
}
Monetization
API Reference