The Ceramic Plugin adds support for storing and retrieving credentials on . 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 and Planes.
Install
pnpm i @learncard/ceramic-plugin
Uploading to Ceramic
To upload a credential to Ceramic, you may use the :
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 :
// 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 (). JOSE encryption is implemented with ECDH-ES+XC20PKW on the x25519curve with a key length of 256. This is handled by the library from the .
Note: Additional metadata is not, by default, encrypted.
Reading from Ceramic
To read a credential from Ceramic, you may use the :
const vc = await learnCard.read.get(uri);
Getting the Ceramic Client
To get access to the Ceramic Client, use the getCeramicClient method:
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
};
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);
You can also use publishContentToCeramic to upload VPs! Try:
Ceramic's getmethod will decrypt any JWE encrypted credentials (see ) when reading, using the learnCard's DID (learnCard.id.did()). If the learnCard's DID is not a recipient of the JWE, reading the credential will fail.