Ceramic
The Ceramic Plugin adds support for storing and retrieving credentials on Ceramic. It exposes the ability to publish and read from Ceramic, as well as providing access to a Ceramic client object with a did attached to it.
This plugin implements the Read and Store Planes.
Install
pnpm i @learncard/ceramic-plugin
Uploading to Ceramic
To upload a credential to Ceramic, you may use the Store Plane:
const uri = await learnCard.store.Ceramic.upload(vc);
Uploading to Ceramic with Encryption
To upload a credential to Ceramic using encryption, you may use the Store Plane:
// Encrypted, only the controller(s) can decrypt
const uri = await learnCard.store.Ceramic.uploadEncrypted(vc);
Ceramic's uploadEncrypted method encrypts VCs as JWEs with the controller's DID and other specified recipients (see below for advanced encryption options). JOSE encryption is implemented with ECDH-ES+XC20PKW
on the x25519
curve with a key length of 256
. This is handled by the did-jwt library from the Decentralized Identity Foundation.
Note: Additional metadata is not, by default, encrypted.
Reading from Ceramic
To read a credential from Ceramic, you may use the Read Plane:
const vc = await learnCard.read.get(uri);
Getting the Ceramic Client
To get access to the Ceramic Client, use the getCeramicClient
method:
const ceramic = learnCard.invoke.getCeramicClient();
Advanced Encryption Settings
As indicated above, when using learnCard.store.Ceramic.uploadEncrypted(vc),
uploaded VCs are encrypted using default settings.
Upload & Get Encrypted Credential:
const user = await initLearnCard({ seed: '123', debug: console.log })
const malicious = await initLearnCard({ seed: '666', debug: console.log });
const uvc = user.invoke.getTestVc();
const vc = await user.invoke.issueCredential(uvc);
const streamId = await user.store.Ceramic.uploadEncrypted(vc);
// Should properly retrieve credential! β
await user.read.get(streamId);
// Should error - Could not decrypt credential - DID not authorized. β
await malicious.read.get(streamId);
Upload & Get Shared Encrypted Credential:
In addition to encrypting VCs for the controller, you can pass additional params of the following shape, to learnCard.store.Ceramic.uploadEncrypted(vc, params):
// params in uploadEncrypted(vc, params):
type EncryptionParams = {
recipients: string[]; // DIDs who can also decrypt the credential, in addition to the controller
};
You can play with the following examples in the LearnCard CLI:
const user = await initLearnCard({ seed: '123', debug: console.log })
const malicious = await initLearnCard({ seed: '666', debug: console.log });
const friend = await initLearnCard({ seed: '808', debug: console.log });
const sharedStreamId = await user.store.Ceramic.uploadEncrypted(vc, { recipients: [friend.id.did()] });
// Should properly retrieve credential! β
await user.read.get(sharedStreamId);
// Should properly retrieve credential! β
await friend.read.get(sharedStreamId);
// Should error - Could not decrypt credential - DID not authorized. β
await malicious.read.get(sharedStreamId);
Upload & Get One-Way Encrypted Credential:
To manually set encryption settings, you should directly use learnCard.invoke.publishContentToCeramic(vc, encryption)
and pass in your encryption
params:
Ceramic's specific encryption param is of the following shape:
export type CeramicEncryptionParams = {
encrypt: boolean; // Enables / disables JWE encryption
controllersCanDecrypt?: boolean; // Adds the controller DIDs to the recipients list
recipients?: string[] | undefined; // Specifies which DIDs can decrypt the credential
options?: CreateJWEOptions | undefined; // Additional options, https://did.js.org/docs/api/modules/dids#createjweoptions
};
const user = await initLearnCard({ seed: '123', debug: console.log })
const malicious = await initLearnCard({ seed: '666', debug: console.log });
const friend = await initLearnCard({ seed: '808', debug: console.log });
const unidirectionalStreamId = await user.invoke.publishContentToCeramic(vc, { encrypt: true, controllersCanDecrypt: false, recipients: [friend.id.did()] });
// Should properly retrieve credential! β
await friend.read.get(unidirectionalStreamId);
// Should error - Could not decrypt credential - DID not authorized. β
await user.read.get(unidirectionalStreamId);
// Should error - Could not decrypt credential - DID not authorized. β
await malicious.read.get(unidirectionalStreamId);
Last updated
Was this helpful?