@learncard/open-badge-v2-plugin 1.1.25 → 1.1.27

package/README.md

@@ -2,38 +2,41 @@
 
 Wrap legacy Open Badges v2.0 (OBv2) assertions into self‑issued W3C Verifiable Credentials (VCs) so they can be stored, indexed, and used within the LearnCard ecosystem.
 
-- Name: `OpenBadgeV2`
-- Method: `wrapOpenBadgeV2(obv2Assertion: object | string): Promise<VC>`
-- Context added: `https://ctx.learncard.com/wrappers/obv2/1.0.0.json`
-- VC type produced: `LegacyOpenBadgeCredential`
+-   Name: `OpenBadgeV2`
+-   Method: `wrapOpenBadgeV2(obv2Assertion: object | string): Promise<VC>`
+-   Context added: `https://ctx.learncard.com/wrappers/obv2/1.0.0.json`
+-   VC type produced: `LegacyOpenBadgeCredential`
 
 ## Why this plugin?
 
 Many issuers still publish Open Badges v2.0 assertions (JSON), not VCs. This plugin provides a backwards‑compatibility bridge by wrapping the raw OBv2 assertion inside a signed VC you control, preserving the original badge payload under `legacyAssertion`.
 
 This enables:
-- Use of legacy badges anywhere a VC is expected (storage, indexing, sharing).
-- A stable LearnCard vocabulary for the wrapper (`LegacyOpenBadgeCredential`).
-- Consistent DID‑based signing and verification workflows.
+
+-   Use of legacy badges anywhere a VC is expected (storage, indexing, sharing).
+-   A stable LearnCard vocabulary for the wrapper (`LegacyOpenBadgeCredential`).
+-   Consistent DID‑based signing and verification workflows.
 
 ## What it produces
 
 A signed VC with these characteristics:
-- `@context`: `["https://www.w3.org/ns/credentials/v2", "https://ctx.learncard.com/wrappers/obv2/1.0.0.json"]`
-- `type`: `["VerifiableCredential", "LegacyOpenBadgeCredential"]`
-- `issuer`: your LearnCard DID
-- `validFrom`: `new Date().toISOString()`
-- `credentialSubject.id`: your LearnCard DID
-- `legacyAssertion`: the original OBv2 assertion JSON
+
+-   `@context`: `["https://www.w3.org/ns/credentials/v2", "https://ctx.learncard.com/wrappers/obv2/1.0.0.json"]`
+-   `type`: `["VerifiableCredential", "LegacyOpenBadgeCredential"]`
+-   `issuer`: your LearnCard DID
+-   `validFrom`: `new Date().toISOString()`
+-   `credentialSubject.id`: your LearnCard DID
+-   `legacyAssertion`: the original OBv2 assertion JSON
 
 Notes:
-- The wrapper signs the fact that “you attest to this legacy assertion,” not that you were the original OBv2 issuer.
-- Minimal OBv2 validation is performed: `id` (string), `type` includes `"Assertion"`, `issuedOn` (string).
+
+-   The wrapper signs the fact that “you attest to this legacy assertion,” not that you were the original OBv2 issuer.
+-   Minimal OBv2 validation is performed: `id` (string), `type` includes `"Assertion"`, `issuedOn` (string).
 
 ## Requirements
 
-- A LearnCard instance with the VC plugin installed (used to sign the VC).
-- Fetch available for remote inputs (Node 18+ or a polyfill like `undici`).
+-   A LearnCard instance with the VC plugin installed (used to sign the VC).
+-   Fetch available for remote inputs (Node 18+ or a polyfill like `undici`).
 
 ## Installation
 
@@ -41,7 +44,7 @@ This package is part of the monorepo. In external usage, install from npm (when
 
 ```bash
 # inside the monorepo
-pnpm nx run open-badge-v2-plugin:build
+bunx nx run open-badge-v2-plugin:build
 ```
 
 ## Usage
@@ -80,13 +83,13 @@ const vc = await learnCard.invoke.wrapOpenBadgeV2(ipfsUrl);
 
 ```ts
 const obv2 = {
-  '@context': 'https://w3id.org/openbadges/v2',
-  type: 'Assertion',
-  id: 'https://issuer.example.org/assertions/abc',
-  issuedOn: '2024-05-02T12:34:56Z',
-  recipient: { type: 'email', identity: 'user@example.org', hashed: false },
-  badge: 'https://issuer.example.org/badges/my-badge'
-  // ... any other OBv2 fields ...
+    '@context': 'https://w3id.org/openbadges/v2',
+    type: 'Assertion',
+    id: 'https://issuer.example.org/assertions/abc',
+    issuedOn: '2024-05-02T12:34:56Z',
+    recipient: { type: 'email', identity: 'user@example.org', hashed: false },
+    badge: 'https://issuer.example.org/badges/my-badge',
+    // ... any other OBv2 fields ...
 };
 
 const vc = await learnCard.invoke.wrapOpenBadgeV2(obv2);
@@ -105,36 +108,38 @@ const vc = await learnCard.invoke.wrapOpenBadgeV2(obv2String);
 wrapOpenBadgeV2(obv2Assertion: object | string): Promise<VC>
 ```
 
-- `obv2Assertion` may be:
-  - A raw OBv2 assertion object
-  - A URL string (http(s)://, ipfs://, ipns://) pointing to the assertion JSON
-  - A JSON string containing the assertion
+-   `obv2Assertion` may be:
+    -   A raw OBv2 assertion object
+    -   A URL string (http(s)://, ipfs://, ipns://) pointing to the assertion JSON
+    -   A JSON string containing the assertion
 
 Validation rules enforced:
-- `assertion.id` must be a non‑empty string
-- `assertion.type` must include `"Assertion"`
-- `assertion.issuedOn` must be a string
+
+-   `assertion.id` must be a non‑empty string
+-   `assertion.type` must include `"Assertion"`
+-   `assertion.issuedOn` must be a string
 
 ## JSON‑LD Context
 
 The wrapper vocabulary is published at:
 
-- `https://ctx.learncard.com/wrappers/obv2/1.0.0.json`
+-   `https://ctx.learncard.com/wrappers/obv2/1.0.0.json`
 
 It defines:
-- `LegacyOpenBadgeCredential`
-- `legacyAssertion` as `@type: @json` for embedding raw OBv2 JSON
+
+-   `LegacyOpenBadgeCredential`
+-   `legacyAssertion` as `@type: @json` for embedding raw OBv2 JSON
 
 ## Development
 
-- Build: `pnpm nx run open-badge-v2-plugin:build`
-- Source: `packages/plugins/open-badge-v2/src/`
-- Context file: `packages/learn-card-contexts/wrappers/obv2/1.0.0.json`
+-   Build: `bunx nx run open-badge-v2-plugin:build`
+-   Source: `packages/plugins/open-badge-v2/src/`
+-   Context file: `packages/learn-card-contexts/wrappers/obv2/1.0.0.json`
 
 ## Caveats
 
-- Wrapping does not retroactively convert OBv2 into a first‑party VC issued by the original badge issuer; it produces a VC signed by your DID that embeds the legacy assertion.
-- Always fetch and wrap assertions from trusted sources.
+-   Wrapping does not retroactively convert OBv2 into a first‑party VC issued by the original badge issuer; it produces a VC signed by your DID that embeds the legacy assertion.
+-   Always fetch and wrap assertions from trusted sources.
 
 ## License
 

package/package.json

@@ -1,58 +1,60 @@
 {
-  "name": "@learncard/open-badge-v2-plugin",
-  "version": "1.1.25",
-  "description": "OpenBadge v2 wrapper plugin for LearnCard. Wraps OBv2 assertions into self-issued VCs.",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/open-badge-v2-plugin.esm.js",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/open-badge-v2-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/open-badge-v2/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/crypto-plugin": "1.1.24",
-    "@learncard/vc-plugin": "1.5.4",
-    "@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/open-badge-v2-plugin",
+    "version": "1.1.27",
+    "description": "OpenBadge v2 wrapper plugin for LearnCard. Wraps OBv2 assertions into self-issued VCs.",
+    "type": "module",
+    "main": "./dist/index.cjs",
+    "module": "./dist/open-badge-v2-plugin.esm.js",
+    "exports": {
+        ".": {
+            "development": "./src/index.ts",
+            "import": {
+                "types": "./dist/index.d.ts",
+                "default": "./dist/open-badge-v2-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/open-badge-v2/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/crypto-plugin": "1.1.26",
+        "@learncard/vc-plugin": "1.5.6",
+        "@learncard/types": "5.17.5"
+    },
+    "sideEffects": false
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { openBadgeV2Plugin } from './plugin';
+export * from './types';

package/src/plugin.ts

@@ -0,0 +1,164 @@
+import { LearnCard } from '@learncard/core';
+import { UnsignedVC, VC } from '@learncard/types';
+
+import {
+    OpenBadgeV2Plugin,
+    OBV2_WRAPPER_CONTEXT_URL,
+    OpenBadgeV2PluginDependentMethods,
+} from './types';
+
+const VC_V2_CONTEXT = 'https://www.w3.org/ns/credentials/v2';
+
+const isUrl = (value: string): boolean =>
+    /^(https?:)?\/\//i.test(value) || value.startsWith('ipfs://') || value.startsWith('ipns://');
+
+const isValidAndSafeUrl = (url: string): void => {
+    try {
+        const parsedUrl = new URL(url);
+
+        // Only allow http, https, ipfs, ipns protocols
+        const allowedProtocols = ['https:', 'http:', 'ipfs:', 'ipns:'];
+        if (!allowedProtocols.includes(parsedUrl.protocol)) {
+            throw new Error(
+                `wrapOpenBadgeV2: Protocol '${parsedUrl.protocol}' is not allowed. Only HTTP(S), IPFS, and IPNS are supported`
+            );
+        }
+
+        // Skip internal network checks for IPFS/IPNS as they don't use traditional IP addresses
+        if (parsedUrl.protocol === 'ipfs:' || parsedUrl.protocol === 'ipns:') {
+            return;
+        }
+
+        // Block localhost and internal networks for HTTP(S)
+        const hostname = parsedUrl.hostname.toLowerCase();
+
+        // Block localhost variations
+        if (
+            hostname === 'localhost' ||
+            hostname === '127.0.0.1' ||
+            hostname === '0.0.0.0' ||
+            hostname === '::1'
+        ) {
+            throw new Error('wrapOpenBadgeV2: Access to localhost is not allowed');
+        }
+
+        // Block private IP ranges (RFC 1918)
+        if (
+            hostname.startsWith('10.') ||
+            hostname.startsWith('192.168.') ||
+            (hostname.startsWith('172.') && /^172\.(1[6-9]|2[0-9]|3[0-1])\./.test(hostname))
+        ) {
+            throw new Error('wrapOpenBadgeV2: Access to private IP ranges is not allowed');
+        }
+
+        // Block link-local addresses
+        if (hostname.startsWith('169.254.')) {
+            throw new Error('wrapOpenBadgeV2: Access to link-local addresses is not allowed');
+        }
+    } catch (error) {
+        if (error instanceof TypeError) {
+            throw new Error('wrapOpenBadgeV2: Invalid URL format');
+        }
+        throw error;
+    }
+};
+
+async function getObv2Assertion(input: object | string): Promise<Record<string, any>> {
+    if (typeof input === 'string') {
+        // Treat string as URL. If it looks like raw JSON, try to parse for developer ergonomics
+        const trimmed = input.trim();
+        if (!isUrl(trimmed) && (trimmed.startsWith('{') || trimmed.startsWith('['))) {
+            try {
+                return JSON.parse(trimmed);
+            } catch (e) {
+                throw new Error('wrapOpenBadgeV2: Provided string is not a valid URL or JSON');
+            }
+        }
+
+        // Validate URL for security
+        isValidAndSafeUrl(trimmed);
+
+        try {
+            // Add timeout to prevent hanging requests (10 seconds)
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), 10000);
+
+            const res = await fetch(trimmed, {
+                signal: controller.signal,
+            });
+
+            clearTimeout(timeoutId);
+
+            if (!res.ok)
+                throw new Error(`wrapOpenBadgeV2: Failed to fetch OBv2 assertion: ${res.status}`);
+
+            return await res.json();
+        } catch (error: any) {
+            if (error instanceof TypeError) {
+                throw new Error(
+                    `wrapOpenBadgeV2: Network error while fetching OBv2 assertion: ${error.message}`
+                );
+            }
+            if (error?.name === 'AbortError') {
+                throw new Error('wrapOpenBadgeV2: Request timed out after 10 seconds');
+            }
+            throw error;
+        }
+    }
+
+    // Add basic type validation before assertion
+    if (typeof input !== 'object' || input === null) {
+        throw new Error('wrapOpenBadgeV2: Input must be a valid object');
+    }
+
+    return input as Record<string, any>;
+}
+
+function validateObv2(obv2: Record<string, any>): void {
+    if (!obv2 || typeof obv2 !== 'object') throw new Error('wrapOpenBadgeV2: Missing assertion');
+
+    const id = obv2.id;
+    if (typeof id !== 'string' || !id.length)
+        throw new Error('wrapOpenBadgeV2: assertion.id is required');
+
+    const t = obv2.type;
+    const hasAssertionType =
+        (typeof t === 'string' && t === 'Assertion') ||
+        (Array.isArray(t) && t.includes('Assertion'));
+    if (!hasAssertionType)
+        throw new Error("wrapOpenBadgeV2: assertion.type must include 'Assertion'");
+
+    if (!obv2.issuedOn || typeof obv2.issuedOn !== 'string') {
+        throw new Error('wrapOpenBadgeV2: assertion.issuedOn (string) is required');
+    }
+}
+
+export const openBadgeV2Plugin = (
+    learnCard: LearnCard<any, 'id', OpenBadgeV2PluginDependentMethods>
+): OpenBadgeV2Plugin => ({
+    name: 'OpenBadgeV2',
+    displayName: 'OpenBadge v2 Wrapper',
+    description: 'Wrap legacy OpenBadge v2.0 assertions into self-issued Verifiable Credentials',
+    methods: {
+        wrapOpenBadgeV2: async (_learnCard, obv2Assertion: object | string): Promise<VC> => {
+            const issuerDid = learnCard.id.did();
+
+            const obv2 = await getObv2Assertion(obv2Assertion);
+            validateObv2(obv2);
+
+            const unsigned: UnsignedVC = {
+                '@context': [VC_V2_CONTEXT, OBV2_WRAPPER_CONTEXT_URL],
+                id: `urn:uuid:${_learnCard.invoke.crypto().randomUUID()}`,
+                type: ['VerifiableCredential', 'LegacyOpenBadgeCredential'],
+                issuer: issuerDid,
+                validFrom: new Date().toISOString(),
+                credentialSubject: {
+                    id: issuerDid,
+                },
+                legacyAssertion: obv2,
+            };
+
+            return learnCard.invoke.issueCredential(unsigned, { proofPurpose: 'assertionMethod' });
+        },
+    },
+});

package/src/types.ts

@@ -0,0 +1,23 @@
+import { Plugin } from '@learncard/core';
+import { VC } from '@learncard/types';
+import { VCPluginMethods } from '@learncard/vc-plugin';
+import { CryptoPluginMethods } from '@learncard/crypto-plugin';
+
+export type OpenBadgeV2PluginDependentMethods = VCPluginMethods & CryptoPluginMethods;
+
+export type OpenBadgeV2PluginMethods = {
+    /**
+     * Wrap a legacy OpenBadge v2.0 assertion (object or URL) into a self-issued VC
+     */
+    wrapOpenBadgeV2: (obv2Assertion: object | string) => Promise<VC>;
+};
+
+export type OpenBadgeV2Plugin = Plugin<
+    'OpenBadgeV2',
+    any,
+    OpenBadgeV2PluginMethods,
+    'id',
+    OpenBadgeV2PluginDependentMethods
+>;
+
+export const OBV2_WRAPPER_CONTEXT_URL = 'https://ctx.learncard.com/wrappers/obv2/1.0.0.json';

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Learning Economy Foundation <sdk@learningeconomy.io>
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.