@learncard/vc-api-plugin 1.1.24 → 1.1.26

package/README.md

@@ -9,25 +9,26 @@
 The LearnCard Core is a pluggable, open-source, universal digital wallet to enable any individual or organization to seamlessly **issue, earn, store, share, and spend currency and credentials** built for the future of education and work.
 
 ## Documentation
+
 All LearnCard documentation can be found at:
 https://docs.learncard.com
 
 ## Install
 
 ```bash
-pnpm i @learncard/core
+bun add @learncard/core
 ```
 
 ## Usage
 
 ### Instantiation
 
-Instantiate a wallet using `initLearnCard`. This method accepts a unique identifier string that is 
+Instantiate a wallet using `initLearnCard`. This method accepts a unique identifier string that is
 up to 64 characters long. If it is less than 64 characters, `initLearnCard` will pad the start of
 the string with 0's until it is 64 characters long.
 
 ```js
-import { initLearnCard } from "@learncard/core";
+import { initLearnCard } from '@learncard/core';
 
 const wallet = await initLearnCard({ seed: 'a'.repeat(64) });
 ```
@@ -35,6 +36,7 @@ const wallet = await initLearnCard({ seed: 'a'.repeat(64) });
 ### Issuing/Verifying Credentials and Presentations
 
 #### Issue a credential
+
 ```js
 // Grab a test VC, or create your own!
 const unsignedVc = await wallet.invoke.getTestVc();
@@ -43,6 +45,7 @@ const vc = await wallet.invoke.issueCredential(unsignedVc);
 ```
 
 #### Verify a credential
+
 ```js
 const result = await wallet.invoke.verifyCredential(vc, {}, true);
 
@@ -53,11 +56,13 @@ else console.log('This credential is valid!');
 ```
 
 #### Issue a presentation
+
 ```js
 const vp = await wallet.invoke.issuePresentation(vc);
 ```
 
 #### Verify a presentation
+
 ```js
 const result = await wallet.invoke.verifyPresentation(vp);
 
@@ -74,14 +79,14 @@ else console.log('This presentation is valid!');
 To maintain co-ownership of credentials, it is best to store credentials in a public place, and then
 store references to that public place. While this is not the only way to store credentials (and is
 also definitely not a silver bullet! E.g. credentials containing private data), it is the opinion of
-this library that it should be used by default. As a result, instantiating a wallet, will 
-automatically connect you to WeLibrary's ceramic node, and allow you to publish and retrieve 
+this library that it should be used by default. As a result, instantiating a wallet, will
+automatically connect you to WeLibrary's ceramic node, and allow you to publish and retrieve
 credentials there using IDX.
 
 #### Publish Credential
 
 After signing a VC, you may choose to publish that credential to Ceramic. Doing so will return a
-stream ID, which you may share to the recipient. That stream ID can then be used to resolve the 
+stream ID, which you may share to the recipient. That stream ID can then be used to resolve the
 issued credential. This means both the issuer and recipient may store the _stream ID_ instead of the
 credential itself.
 
@@ -126,6 +131,7 @@ const vcs = await Promise.all(uris.map(async uri => wallet.read.get(uri)));
 ```
 
 ## Contributing
+
 Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
 
 Please make sure to update tests as appropriate.
@@ -134,7 +140,6 @@ Please make sure to update tests as appropriate.
 
 **[Learning Economy Foundation (LEF)](https://www.learningeconomy.io)** is a 501(c)(3) non-profit organization leveraging global standards and web3 protocols to bring quality skills and equal opportunity to every human on earth, and address the persistent inequities that exist around the globe in education and employment. We help you build the future of education and work with:
 
-
 ## License
 
 MIT © [Learning Economy Foundation](https://github.com/Learning-Economy-Foundation)

package/package.json

@@ -1,56 +1,58 @@
 {
-  "name": "@learncard/vc-api-plugin",
-  "version": "1.1.24",
-  "description": "",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/vc-api-plugin.esm.js",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/vc-api-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/vc-api/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/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": {
-    "@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/vc-api-plugin",
+    "version": "1.1.26",
+    "description": "",
+    "type": "module",
+    "main": "./dist/index.cjs",
+    "module": "./dist/vc-api-plugin.esm.js",
+    "exports": {
+        ".": {
+            "development": "./src/index.ts",
+            "import": {
+                "types": "./dist/index.d.ts",
+                "default": "./dist/vc-api-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/vc-api/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/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": {
+        "@learncard/core": "9.4.26",
+        "@learncard/types": "5.17.5"
+    },
+    "sideEffects": false
+}

package/src/helpers.ts

@@ -0,0 +1,14 @@
+/**
+ * Sends a POST request via fetch
+ */
+export const post = async (url: string, data: Record<string, any>): Promise<Response> =>
+    fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(data),
+    });
+
+/**
+ * Returns whether or not an HTTP status code is successful
+ */
+export const isSuccessful = (status: number) => status.toString().startsWith('2');

package/src/index.ts

@@ -0,0 +1,125 @@
+import {
+    UnsignedVCValidator,
+    VCValidator,
+    UnsignedVPValidator,
+    VPValidator,
+    VerificationCheckValidator,
+} from '@learncard/types';
+
+import { VCAPIPlugin } from './types';
+import { isSuccessful, post } from './helpers';
+
+export * from './types';
+
+/**
+ * @group Plugins
+ */
+export const getVCAPIPlugin = async ({
+    url: _url,
+    did: _did,
+}: {
+    url: string;
+    did?: string;
+}): Promise<VCAPIPlugin> => {
+    const url = _url.endsWith('/') ? _url.slice(0, -1) : _url;
+    let did = _did;
+
+    if (!did) {
+        const res = await fetch(`${url}/did`);
+
+        if (res.status === 200) did = await res.text();
+    }
+
+    if (!did) throw new Error('Could not retrieve did from VC API! Please suppy a did.');
+
+    return {
+        name: 'VC API',
+        displayName: 'VC API',
+        description:
+            'Handles issuing and signing credentials/presentations using an external VC API',
+        id: {
+            did: () => did!,
+            keypair: () => {
+                throw new Error('Cannot get keypair when using VC API');
+            },
+        },
+        methods: {
+            getSubjectDid: () => did!,
+            issueCredential: async (_learnCard, credential, options) => {
+                await UnsignedVCValidator.parseAsync(credential);
+
+                const response = await post(`${url}/credentials/issue`, { credential, options });
+
+                if (!isSuccessful(response.status)) {
+                    throw new Error(`API Error: ${response.status} ${response.statusText}`);
+                }
+
+                return VCValidator.parseAsync(await response.json());
+            },
+            verifyCredential: async (_learnCard, verifiableCredential, options) => {
+                await VCValidator.parseAsync(verifiableCredential);
+
+                const response = await post(`${url}/credentials/verify`, {
+                    verifiableCredential,
+                    options,
+                });
+
+                if (!isSuccessful(response.status)) {
+                    throw new Error(`API Error: ${response.status} ${response.statusText}`);
+                }
+
+                return VerificationCheckValidator.parseAsync(await response.json());
+            },
+            issuePresentation: async (_learnCard, presentation, options) => {
+                await UnsignedVPValidator.parseAsync(presentation);
+
+                const response = await post(`${url}/presentations/issue`, {
+                    presentation,
+                    options,
+                });
+
+                if (!isSuccessful(response.status)) {
+                    throw new Error(`API Error: ${response.status} ${response.statusText}`);
+                }
+
+                return VPValidator.parseAsync(await response.json());
+            },
+            verifyPresentation: async (_learnCard, verifiablePresentation, options) => {
+                await VPValidator.parseAsync(verifiablePresentation);
+
+                const response = await post(`${url}/presentations/verify`, {
+                    verifiablePresentation,
+                    options,
+                });
+
+                if (!isSuccessful(response.status)) {
+                    throw new Error(`API Error: ${response.status} ${response.statusText}`);
+                }
+
+                return VerificationCheckValidator.parseAsync(await response.json());
+            },
+            getTestVc: (_learnCard, subject = 'did:example:d23dd687a7dc6787646f2eb98d0') => {
+                return {
+                    '@context': ['https://www.w3.org/2018/credentials/v1'],
+                    id: 'http://example.org/credentials/3731',
+                    type: ['VerifiableCredential'],
+                    issuer: did!,
+                    issuanceDate: '2020-08-19T21:41:50Z',
+                    credentialSubject: { id: subject },
+                };
+            },
+            getTestVp: async (_learnCard, _credential) => {
+                const credential =
+                    _credential ||
+                    (await _learnCard.invoke.issueCredential(_learnCard.invoke.getTestVc()));
+
+                return {
+                    '@context': ['https://www.w3.org/2018/credentials/v1'],
+                    type: ['VerifiablePresentation'],
+                    holder: did,
+                    verifiableCredential: credential,
+                };
+            },
+        },
+    };
+};

package/src/types.ts

@@ -0,0 +1,29 @@
+import { UnsignedVC, UnsignedVP, VC, VP, VerificationCheck } from '@learncard/types';
+import { Plugin } from '@learncard/core';
+
+/** @group VC-API Plugin */
+export type APIOptions = {
+    created?: string;
+    challenge?: string;
+    domain?: string;
+};
+
+/** @group VC-API Plugin */
+export type VCAPIPluginMethods = {
+    getSubjectDid: (type: string) => string;
+    issueCredential: (credential: UnsignedVC, signingOptions?: APIOptions) => Promise<VC>;
+    verifyCredential: (
+        credential: VC,
+        options?: Omit<APIOptions, 'created'>
+    ) => Promise<VerificationCheck>;
+    issuePresentation: (presentation: UnsignedVP, signingOptions?: APIOptions) => Promise<VP>;
+    verifyPresentation: (
+        presentation: VP,
+        options?: Omit<APIOptions, 'created'>
+    ) => Promise<VerificationCheck>;
+    getTestVc: (subject?: string) => UnsignedVC;
+    getTestVp: (credential?: VC) => Promise<UnsignedVP>;
+};
+
+/** @group VC-API Plugin */
+export type VCAPIPlugin = Plugin<'VC API', 'id', VCAPIPluginMethods>;