@learncard/ceramic-plugin 1.1.24 → 1.1.26

package/package.json

@@ -1,68 +1,70 @@
 {
-  "name": "@learncard/ceramic-plugin",
-  "version": "1.1.24",
-  "description": "",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/ceramic-plugin.esm.js",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/ceramic-plugin.esm.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "author": "Learning Economy Foundation (www.learningeconomy.io)",
-  "license": "MIT",
-  "homepage": "https://github.com/learningeconomy/LearnCard/tree/main/packages/plugins/ceramic/README.md",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/learningeconomy/LearnCard"
-  },
-  "bugs": {
-    "url": "https://github.com/learningeconomy/LearnCard/issues"
-  },
-  "devDependencies": {
-    "@types/jest": "^29.2.2",
-    "@types/lodash": "^4.14.191",
-    "@types/node": "^17.0.31",
-    "aqu": "0.4.3",
-    "esbuild": "^0.27.1",
-    "esbuild-jest": "^0.5.0",
-    "esbuild-plugin-copy": "^1.3.0",
-    "jest": "^29.3.0",
-    "shx": "^0.3.4",
-    "ts-jest": "^29.0.3",
-    "@learncard/didkit-plugin": "1.9.4"
-  },
-  "types": "./dist/index.d.ts",
-  "dependencies": {
-    "@ceramicnetwork/common": "2.13.0",
-    "@ceramicnetwork/http-client": "2.7.0",
-    "@ceramicnetwork/stream-tile": "2.9.0",
-    "@glazed/tile-loader": "0.2.1",
-    "did-jwt": "5.9.0",
-    "dids": "^3.2.0",
-    "hex-lite": "^1.5.0",
-    "key-did-provider-ed25519": "^2.0.0",
-    "key-did-resolver": "2.3.0",
-    "lodash": "^4.17.21",
-    "@learncard/core": "9.4.24",
-    "@learncard/types": "5.17.4"
-  },
-  "sideEffects": false,
-  "scripts": {
-    "build": "node ./scripts/build.mjs && shx cp ./scripts/mixedEntypoint.js ./dist/index.cjs && tsc --p tsconfig.json && shx cp ./dist/index.d.ts ./dist/index.d.cts",
-    "test": "jest --passWithNoTests",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --silent --ci --coverage --coverageReporters=\"text\" --coverageReporters=\"text-summary\""
-  }
-}
+    "name": "@learncard/ceramic-plugin",
+    "version": "1.1.26",
+    "description": "",
+    "type": "module",
+    "main": "./dist/index.cjs",
+    "module": "./dist/ceramic-plugin.esm.js",
+    "exports": {
+        ".": {
+            "development": "./src/index.ts",
+            "import": {
+                "types": "./dist/index.d.ts",
+                "default": "./dist/ceramic-plugin.esm.js"
+            },
+            "require": {
+                "types": "./dist/index.d.cts",
+                "default": "./dist/index.cjs"
+            }
+        }
+    },
+    "files": [
+        "dist",
+        "src"
+    ],
+    "scripts": {
+        "build": "node ./scripts/build.mjs && shx cp ./scripts/mixedEntypoint.js ./dist/index.cjs && tsc --p tsconfig.json && shx cp ./dist/index.d.ts ./dist/index.d.cts",
+        "test": "jest --passWithNoTests",
+        "test:watch": "jest --watch",
+        "test:coverage": "jest --silent --ci --coverage --coverageReporters=\"text\" --coverageReporters=\"text-summary\""
+    },
+    "author": "Learning Economy Foundation (www.learningeconomy.io)",
+    "license": "MIT",
+    "homepage": "https://github.com/learningeconomy/LearnCard/tree/main/packages/plugins/ceramic/README.md",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/learningeconomy/LearnCard"
+    },
+    "bugs": {
+        "url": "https://github.com/learningeconomy/LearnCard/issues"
+    },
+    "devDependencies": {
+        "@learncard/didkit-plugin": "1.9.6",
+        "@types/jest": "^29.2.2",
+        "@types/lodash": "^4.14.191",
+        "@types/node": "^17.0.31",
+        "aqu": "0.4.3",
+        "esbuild": "^0.27.1",
+        "esbuild-jest": "^0.5.0",
+        "esbuild-plugin-copy": "^1.3.0",
+        "jest": "^29.3.0",
+        "shx": "^0.3.4",
+        "ts-jest": "^29.0.3"
+    },
+    "types": "./dist/index.d.ts",
+    "dependencies": {
+        "@ceramicnetwork/common": "2.13.0",
+        "@ceramicnetwork/http-client": "2.7.0",
+        "@ceramicnetwork/stream-tile": "2.9.0",
+        "@glazed/tile-loader": "0.2.1",
+        "@learncard/core": "9.4.26",
+        "@learncard/types": "5.17.5",
+        "did-jwt": "5.9.0",
+        "dids": "^3.2.0",
+        "hex-lite": "^1.5.0",
+        "key-did-provider-ed25519": "^2.0.0",
+        "key-did-resolver": "2.3.0",
+        "lodash": "^4.17.21"
+    },
+    "sideEffects": false
+}

package/src/ceramic.ts

@@ -0,0 +1,189 @@
+import _ from 'lodash';
+import { DID, DIDResolutionResult } from 'dids';
+import type { JWE } from 'did-jwt';
+import { toUint8Array } from 'hex-lite';
+import KeyDidResolver from 'key-did-resolver';
+import { Ed25519Provider } from 'key-did-provider-ed25519';
+import { TileLoader } from '@glazed/tile-loader';
+import { CeramicClient } from '@ceramicnetwork/http-client';
+import { CreateOpts } from '@ceramicnetwork/common';
+import { TileDocument, TileMetadataArgs } from '@ceramicnetwork/stream-tile';
+import { LearnCard } from '@learncard/core';
+import { InputMetadata } from '@learncard/didkit-plugin';
+import { VCValidator, VC, VPValidator, VP, isStoredCredentialEnvelope } from '@learncard/types';
+
+import { streamIdToCeramicURI } from './helpers';
+import type {
+    CeramicEncryptionParams,
+    CeramicPlugin,
+    CeramicPluginDependentMethods,
+    CeramicArgs,
+} from './types';
+
+import { CeramicURIValidator } from './types';
+import { DEFAULT_CERAMIC_ARGS } from './defaults';
+
+/**
+ * @group Plugins
+ */
+export const getCeramicPlugin = async (
+    learnCard: LearnCard<any, any, CeramicPluginDependentMethods>,
+    { ceramicEndpoint, defaultContentFamily }: CeramicArgs = DEFAULT_CERAMIC_ARGS
+): Promise<CeramicPlugin> => {
+    const ceramic = new CeramicClient(ceramicEndpoint);
+
+    const learnCardResolver = async (
+        did: string,
+        _parsedDid: any,
+        _resolver: any,
+        options: InputMetadata
+    ): Promise<DIDResolutionResult> => learnCard.invoke.didResolver(did, options);
+
+    const resolver = { ...KeyDidResolver.getResolver(), web: learnCardResolver };
+
+    const did = new DID({ resolver });
+
+    ceramic.did = did;
+
+    // use wallet secret key
+    // TODO: this is repeating work already done in the wallet. understand what the Ed25519Provider is doing to determine
+    // if we can just pass wallet signing key here instead of creating a duplicate from same seed.
+    const key = learnCard.invoke.getKey();
+
+    const ceramicProvider = new Ed25519Provider(toUint8Array(key));
+    ceramic.did!.setProvider(ceramicProvider);
+
+    await ceramic.did!.authenticate();
+
+    const loader = new TileLoader({ ceramic });
+
+    const publishContentToCeramic = async (
+        content: any,
+        metadata: TileMetadataArgs = {},
+        options: CreateOpts = {},
+        encryption?: CeramicEncryptionParams
+    ) => {
+        if (!content) throw new Error('content is required');
+
+        // default to current authorized
+        if (!metadata.controllers) metadata.controllers = [ceramic.did!.id];
+
+        // use default
+        if (!metadata.family) metadata.family = defaultContentFamily;
+
+        // default to pinning
+        // TODO: expose
+        if (!('pin' in options)) options.pin = true;
+
+        if (encryption?.encrypt) {
+            learnCard.debug?.(
+                'learnCard.store.Ceramic.upload.publishContentToCeramic - encrypt enabled',
+                encryption
+            );
+
+            let recipients = encryption?.recipients || [];
+            if (encryption?.controllersCanDecrypt) {
+                recipients = [...recipients, ...metadata.controllers];
+            }
+            content = await ceramic?.did?.createDagJWE(content, _.uniq(recipients));
+        }
+
+        learnCard.debug?.(
+            'learnCard.store.Ceramic.upload.publishContentToCeramic - content to upload',
+            content,
+            metadata,
+            options
+        );
+
+        // assuming TileDocument for now
+        const doc = await TileDocument.create(ceramic, content, metadata, options);
+
+        return doc.id.toString();
+    };
+
+    const readContentFromCeramic = async (streamId: string): Promise<any> => {
+        const content = (await loader.load(streamId))?.content;
+        learnCard.debug?.('learnCard.read.get.readContentFromCeramic', content);
+        if (content?.ciphertext) {
+            try {
+                return await did.decryptDagJWE(content as JWE);
+            } catch (e) {
+                learnCard.debug?.(
+                    'learnCard.read.get.readContentFromCeramic - Could not decrypt credential - DID not authorized.',
+                    e
+                );
+                throw new Error('Could not decrypt credential - DID not authorized.');
+            }
+        }
+        return content;
+    };
+
+    const uploadCredential = async (
+        vc: VC | VP,
+        encryption?: CeramicEncryptionParams | undefined
+    ) => {
+        await VCValidator.or(VPValidator).parseAsync(vc);
+
+        return streamIdToCeramicURI(await publishContentToCeramic(vc, {}, {}, encryption));
+    };
+
+    const envelopeRejection = (envelope: { format: string }) =>
+        new Error(
+            `Ceramic does not support format-tagged credential envelopes (got format="${envelope.format}"). Use LearnCloud or the LearnCard Network store for non-W3C credentials (SD-JWT-VC, mDoc, etc.).`
+        );
+
+    return {
+        name: 'Ceramic',
+        displayName: 'Ceramic',
+        description:
+            'Uploads/resolves credentials using the Ceramic Network (https://ceramic.network/)',
+        store: {
+            upload: async (_learnCard, vc) => {
+                _learnCard.debug?.('learnCard.store.Ceramic.upload');
+                if (isStoredCredentialEnvelope(vc)) throw envelopeRejection(vc);
+                return uploadCredential(vc);
+            },
+            uploadEncrypted: async (_learnCard, vc, params) => {
+                _learnCard.debug?.('learnCard.store.Ceramic.uploadEncrypted');
+                if (isStoredCredentialEnvelope(vc)) throw envelopeRejection(vc);
+                return uploadCredential(vc, {
+                    encrypt: true,
+                    controllersCanDecrypt: true,
+                    ...(params ? { recipients: params.recipients } : {}),
+                });
+            },
+        },
+        read: {
+            get: async (_learnCard, uri) => {
+                _learnCard.debug?.('learnCard.read.Ceramic.get');
+
+                if (!uri) return undefined;
+
+                const verificationResult = await CeramicURIValidator.spa(uri);
+
+                if (!verificationResult.success) return undefined;
+
+                const streamId = verificationResult.data.split(':')[2];
+                try {
+                    return await VCValidator.or(VPValidator).parseAsync(
+                        await readContentFromCeramic(streamId)
+                    );
+                } catch (e) {
+                    _learnCard.debug?.(e);
+                    return undefined;
+                }
+            },
+        },
+        methods: {
+            publishContentToCeramic: async (
+                _learnCard,
+                cred,
+                encryption: CeramicEncryptionParams | undefined
+            ) => streamIdToCeramicURI(await publishContentToCeramic(cred, {}, {}, encryption)),
+            readContentFromCeramic: async (_learnCard, streamId: string) =>
+                readContentFromCeramic(streamId),
+            getCeramicClient: () => ceramic,
+            getDIDObject: () => ceramic.did!,
+        },
+    };
+};

package/src/defaults.ts

@@ -0,0 +1,6 @@
+import { CeramicArgs } from './types';
+
+export const DEFAULT_CERAMIC_ARGS: CeramicArgs = {
+    ceramicEndpoint: 'https://ceramic-node.welibrary.io:7007',
+    defaultContentFamily: 'SuperSkills',
+};

package/src/global.d.ts

@@ -0,0 +1,6 @@
+declare module 'hex-lite' {
+    function toUint8Array(hex: string): Uint8Array;
+    function fromUint8Array(array: Uint8Array): string;
+    function toBuffer(hex: string): ArrayBuffer;
+    function fromBuffer(buffer: ArrayBuffer): string;
+}

package/src/helpers.ts

@@ -0,0 +1,5 @@
+import { StreamID } from '@ceramicnetwork/streamid';
+
+import { CeramicURI } from './types';
+
+export const streamIdToCeramicURI = (id: string | StreamID): CeramicURI => `lc:ceramic:${id}`;

package/src/index.ts

@@ -0,0 +1,6 @@
+import { getCeramicPlugin } from './ceramic';
+export { getCeramicPlugin } from './ceramic';
+export * from './types';
+export * from './helpers';
+
+export default getCeramicPlugin;

package/src/types.ts

@@ -0,0 +1,61 @@
+import type { DID, CreateJWEOptions, DIDResolutionResult } from 'dids';
+import { z } from 'zod';
+import { CeramicClient } from '@ceramicnetwork/http-client';
+import { Plugin } from '@learncard/core';
+import { InputMetadata } from '@learncard/didkit-plugin';
+
+/** @group CeramicPlugin */
+export type CeramicArgs = {
+    ceramicEndpoint: string;
+    defaultContentFamily: string;
+};
+
+/** @group CeramicPlugin */
+export type CeramicURI = `lc:ceramic:${string}`;
+
+/** @group CeramicPlugin */
+export const CeramicURIValidator = z
+    .string()
+    .refine(
+        string => string.split(':').length === 3 && string.split(':')[0] === 'lc',
+        'URI must be of the form lc:${storage}:${url}'
+    )
+    .refine(
+        string => string.split(':')[1] === 'ceramic',
+        'URI must use storage type ceramic (i.e. must be lc:ceramic:${streamID})'
+    );
+
+/**
+ * Settings for toggling JWE Encryption before uploading to Ceramic.
+ * @group CeramicPlugin
+ * @param encrypt enable JWE encryption on upload.
+ * @param controllersCanDecrypt helper to add Ceramic controller DIDs to recipients who can decrypt the JWE credential.
+ * @param recipients DIDs who can decrypt the JWE credential.
+ * @param options additional CreateJWEOptions for encryption.
+ */
+export type CeramicEncryptionParams = {
+    encrypt: boolean;
+    controllersCanDecrypt?: boolean;
+    recipients?: string[] | undefined;
+    options?: CreateJWEOptions | undefined;
+};
+
+/** @group CeramicPlugin */
+export type CeramicPluginMethods = {
+    publishContentToCeramic: (
+        cred: any,
+        encryption: CeramicEncryptionParams | undefined
+    ) => Promise<CeramicURI>;
+    readContentFromCeramic: (streamId: string) => Promise<any>;
+    getCeramicClient: () => CeramicClient;
+    getDIDObject: () => DID;
+};
+
+/** @group CeramicPlugin */
+export type CeramicPluginDependentMethods = {
+    getKey: () => string;
+    didResolver: (did: string, inputMetadata?: InputMetadata) => Promise<DIDResolutionResult>;
+};
+
+/** @group CeramicPlugin */
+export type CeramicPlugin = Plugin<'Ceramic', 'read' | 'store', CeramicPluginMethods>;