@learncard/init 2.4.3 → 2.4.5

package/src/initializers/learnCardFromSeed.ts

@@ -0,0 +1,93 @@
+import { generateLearnCard } from '@learncard/core';
+import { DynamicLoaderPlugin } from '@learncard/dynamic-loader-plugin';
+import { CryptoPlugin } from '@learncard/crypto-plugin';
+import { DidMethod, getDidKitPlugin } from '@learncard/didkit-plugin';
+import { getDidKeyPlugin } from '@learncard/didkey-plugin';
+import { getEncryptionPlugin } from '@learncard/encryption-plugin';
+import { getVCPlugin } from '@learncard/vc-plugin';
+import { getVCTemplatesPlugin } from '@learncard/vc-templates-plugin';
+import { getLearnCloudPlugin } from '@learncard/learn-cloud-plugin';
+import { expirationPlugin } from '@learncard/expiration-plugin';
+import { getEthereumPlugin } from '@learncard/ethereum-plugin';
+
+import { getVpqrPlugin } from '@learncard/vpqr-plugin';
+import { getCHAPIPlugin } from '@learncard/chapi-plugin';
+import { getLearnCardPlugin } from '@learncard/learn-card-plugin';
+import { getOpenID4VCPlugin } from '@learncard/openid4vc-plugin';
+import { getSdJwtVcPlugin } from '@learncard/sd-jwt-vc-plugin';
+
+import { LearnCardFromSeed } from '../types/LearnCard';
+import { defaultEthereumArgs } from '../defaults';
+
+/**
+ * Generates a LearnCard Wallet from a 64 character seed string
+ *
+ * @group Init Functions
+ */
+export const learnCardFromSeed = async ({
+    seed,
+
+    cloud: {
+        url = 'https://cloud.learncard.com/trpc',
+        unencryptedFields = [],
+        unencryptedCustomFields = [],
+        automaticallyAssociateDids = true,
+    } = {},
+    didkit,
+    allowRemoteContexts = false,
+    ethereumConfig = defaultEthereumArgs,
+    openid4vc,
+    debug,
+}: LearnCardFromSeed['args']): Promise<LearnCardFromSeed['returnValue']> => {
+    const dynamicLc = await (await generateLearnCard({ debug })).addPlugin(DynamicLoaderPlugin);
+
+    const cryptoLc = await dynamicLc.addPlugin(CryptoPlugin);
+
+    const getDidkit = async (): Promise<typeof getDidKitPlugin> => {
+        if (didkit === 'node') {
+            const mod = await import('@learncard/didkit-plugin-node');
+            return mod.getDidKitPlugin as typeof getDidKitPlugin;
+        }
+        return getDidKitPlugin;
+    };
+
+    const didkitLc = await cryptoLc.addPlugin(
+        await (
+            await getDidkit()
+        )(didkit === 'node' ? undefined : didkit, allowRemoteContexts)
+    );
+
+    const didkeyLc = await didkitLc.addPlugin(
+        await getDidKeyPlugin<DidMethod>(didkitLc, seed, 'key')
+    );
+
+    const encryptionLc = await didkeyLc.addPlugin(await getEncryptionPlugin(didkeyLc));
+
+    const vcLc = await encryptionLc.addPlugin(getVCPlugin(encryptionLc));
+
+    const templateLc = await vcLc.addPlugin(getVCTemplatesPlugin());
+
+    const cloudLc = await templateLc.addPlugin(
+        await getLearnCloudPlugin(
+            templateLc,
+            url,
+            unencryptedFields,
+            unencryptedCustomFields,
+            automaticallyAssociateDids
+        )
+    );
+
+    const expirationLc = await cloudLc.addPlugin(expirationPlugin(cloudLc));
+
+    const ethLc = await expirationLc.addPlugin(getEthereumPlugin(expirationLc, ethereumConfig));
+
+    const vpqrLc = await ethLc.addPlugin(getVpqrPlugin(ethLc));
+
+    const chapiLc = await vpqrLc.addPlugin(await getCHAPIPlugin());
+
+    const sdJwtVcLc = await chapiLc.addPlugin(getSdJwtVcPlugin(chapiLc));
+
+    const lcLc = await sdJwtVcLc.addPlugin(getLearnCardPlugin(sdJwtVcLc));
+
+    return lcLc.addPlugin(getOpenID4VCPlugin(lcLc, openid4vc));
+};

package/src/initializers/networkLearnCardFromApiKey.ts

@@ -0,0 +1,69 @@
+import { generateLearnCard } from '@learncard/core';
+import { DynamicLoaderPlugin } from '@learncard/dynamic-loader-plugin';
+import { CryptoPlugin } from '@learncard/crypto-plugin';
+import { getDidKitPlugin } from '@learncard/didkit-plugin';
+import { getVCPlugin } from '@learncard/vc-plugin';
+import { getVCTemplatesPlugin } from '@learncard/vc-templates-plugin';
+import { expirationPlugin } from '@learncard/expiration-plugin';
+import { getVpqrPlugin } from '@learncard/vpqr-plugin';
+import { getCHAPIPlugin } from '@learncard/chapi-plugin';
+import { getVerifyBoostPlugin, getLearnCardNetworkPlugin } from '@learncard/network-plugin';
+import { getLearnCardPlugin } from '@learncard/learn-card-plugin';
+
+import { NetworkLearnCardFromApiKey } from '../types/LearnCard';
+
+/**
+ * Generates a Network LearnCard Wallet from an API key (no local seed required)
+ *
+ * @group Init Functions
+ */
+export const networkLearnCardFromApiKey = async ({
+    apiKey,
+    network: _network,
+    trustedBoostRegistry = 'https://raw.githubusercontent.com/learningeconomy/registries/main/learncard/trusted-app-registry.json',
+    guardianApprovalGetter,
+    extraHeaders,
+    didkit,
+    allowRemoteContexts = false,
+    debug,
+}: NetworkLearnCardFromApiKey['args']): Promise<NetworkLearnCardFromApiKey['returnValue']> => {
+    const network = typeof _network === 'boolean' ? 'https://network.learncard.com/trpc' : _network;
+
+    const dynamicLc = await (await generateLearnCard({ debug })).addPlugin(DynamicLoaderPlugin);
+
+    const cryptoLc = await dynamicLc.addPlugin(CryptoPlugin);
+
+    const getDidkit = async (): Promise<typeof getDidKitPlugin> => {
+        if (didkit === 'node') {
+            const mod = await import('@learncard/didkit-plugin-node');
+            return mod.getDidKitPlugin as typeof getDidKitPlugin;
+        }
+        return getDidKitPlugin;
+    };
+
+    const didkitLc = await cryptoLc.addPlugin(
+        await (
+            await getDidkit()
+        )(didkit === 'node' ? undefined : didkit, allowRemoteContexts)
+    );
+
+    const vcLc = await didkitLc.addPlugin(getVCPlugin(didkitLc));
+
+    const templateLc = await vcLc.addPlugin(getVCTemplatesPlugin());
+
+    const expirationLc = await templateLc.addPlugin(expirationPlugin(templateLc));
+
+    const vpqrLc = await expirationLc.addPlugin(getVpqrPlugin(expirationLc));
+
+    const chapiLc = await vpqrLc.addPlugin(await getCHAPIPlugin());
+
+    const boostVerificationLc = await chapiLc.addPlugin(
+        await getVerifyBoostPlugin(chapiLc, trustedBoostRegistry)
+    );
+
+    const lcLc = await boostVerificationLc.addPlugin(getLearnCardPlugin(boostVerificationLc));
+
+    return lcLc.addPlugin(
+        await getLearnCardNetworkPlugin(lcLc, network, apiKey, { guardianApprovalGetter, extraHeaders })
+    );
+};

package/src/initializers/networkLearnCardFromSeed.ts

@@ -0,0 +1,108 @@
+import { generateLearnCard } from '@learncard/core';
+import { DynamicLoaderPlugin } from '@learncard/dynamic-loader-plugin';
+import { CryptoPlugin } from '@learncard/crypto-plugin';
+import { DidMethod, getDidKitPlugin } from '@learncard/didkit-plugin';
+import { getDidKeyPlugin } from '@learncard/didkey-plugin';
+import { getEncryptionPlugin } from '@learncard/encryption-plugin';
+import { getVCPlugin } from '@learncard/vc-plugin';
+import { getVCTemplatesPlugin } from '@learncard/vc-templates-plugin';
+import { getLearnCloudPlugin } from '@learncard/learn-cloud-plugin';
+import { expirationPlugin } from '@learncard/expiration-plugin';
+import { getEthereumPlugin } from '@learncard/ethereum-plugin';
+
+import { getVpqrPlugin } from '@learncard/vpqr-plugin';
+import { getCHAPIPlugin } from '@learncard/chapi-plugin';
+import { getVerifyBoostPlugin, getLearnCardNetworkPlugin } from '@learncard/network-plugin';
+import { getLearnCardPlugin } from '@learncard/learn-card-plugin';
+import { getOpenID4VCPlugin } from '@learncard/openid4vc-plugin';
+import { getSdJwtVcPlugin } from '@learncard/sd-jwt-vc-plugin';
+
+import { NetworkLearnCardFromSeed } from '../types/LearnCard';
+import { defaultEthereumArgs } from '../defaults';
+
+/**
+ * Generates a Network LearnCard Wallet from a 64 character seed string
+ *
+ * @group Init Functions
+ */
+export const networkLearnCardFromSeed = async ({
+    seed,
+    network: _network,
+    trustedBoostRegistry = 'https://raw.githubusercontent.com/learningeconomy/registries/main/learncard/trusted-app-registry.json',
+    guardianApprovalGetter,
+    extraHeaders,
+
+    cloud: {
+        url = 'https://cloud.learncard.com/trpc',
+        unencryptedFields = [],
+        unencryptedCustomFields = [],
+        automaticallyAssociateDids = true,
+    } = {},
+    didkit,
+    allowRemoteContexts = false,
+    ethereumConfig = defaultEthereumArgs,
+    openid4vc,
+    debug,
+}: NetworkLearnCardFromSeed['args']): Promise<NetworkLearnCardFromSeed['returnValue']> => {
+    const network = typeof _network === 'boolean' ? 'https://network.learncard.com/trpc' : _network;
+
+    const dynamicLc = await (await generateLearnCard({ debug })).addPlugin(DynamicLoaderPlugin);
+
+    const cryptoLc = await dynamicLc.addPlugin(CryptoPlugin);
+
+    const getDidkit = async (): Promise<typeof getDidKitPlugin> => {
+        if (didkit === 'node') {
+            const mod = await import('@learncard/didkit-plugin-node');
+            return mod.getDidKitPlugin as typeof getDidKitPlugin;
+        }
+        return getDidKitPlugin;
+    };
+
+    const didkitLc = await cryptoLc.addPlugin(
+        await (
+            await getDidkit()
+        )(didkit === 'node' ? undefined : didkit, allowRemoteContexts)
+    );
+
+    const didkeyLc = await didkitLc.addPlugin(
+        await getDidKeyPlugin<DidMethod>(didkitLc, seed, 'key')
+    );
+
+    const encryptionLc = await didkeyLc.addPlugin(await getEncryptionPlugin(didkeyLc));
+
+    const vcLc = await encryptionLc.addPlugin(getVCPlugin(encryptionLc));
+
+    const templateLc = await vcLc.addPlugin(getVCTemplatesPlugin());
+
+    const cloudLc = await templateLc.addPlugin(
+        await getLearnCloudPlugin(
+            templateLc,
+            url,
+            unencryptedFields,
+            unencryptedCustomFields,
+            automaticallyAssociateDids
+        )
+    );
+
+    const expirationLc = await cloudLc.addPlugin(expirationPlugin(cloudLc));
+
+    const ethLc = await expirationLc.addPlugin(getEthereumPlugin(expirationLc, ethereumConfig));
+
+    const vpqrLc = await ethLc.addPlugin(getVpqrPlugin(ethLc));
+
+    const chapiLc = await vpqrLc.addPlugin(await getCHAPIPlugin());
+
+    const boostVerificationLc = await chapiLc.addPlugin(
+        await getVerifyBoostPlugin(chapiLc, trustedBoostRegistry)
+    );
+
+    const sdJwtVcLc = await boostVerificationLc.addPlugin(getSdJwtVcPlugin(boostVerificationLc));
+
+    const lcLc = await sdJwtVcLc.addPlugin(getLearnCardPlugin(sdJwtVcLc));
+
+    const networkLc = await lcLc.addPlugin(
+        await getLearnCardNetworkPlugin(lcLc, network, { guardianApprovalGetter, extraHeaders })
+    );
+
+    return networkLc.addPlugin(getOpenID4VCPlugin(networkLc, openid4vc));
+};

package/src/types/LearnCard.ts

@@ -0,0 +1,244 @@
+import { LearnCard } from '@learncard/core';
+import { InitInput } from '@learncard/types';
+
+import { CryptoPluginType } from '@learncard/crypto-plugin';
+import { DIDKitPlugin, DidMethod } from '@learncard/didkit-plugin';
+import { DidKeyPlugin } from '@learncard/didkey-plugin';
+import { DynamicLoaderPluginType } from '@learncard/dynamic-loader-plugin';
+import { VCPlugin } from '@learncard/vc-plugin';
+import { VCTemplatePlugin } from '@learncard/vc-templates-plugin';
+import { LearnCloudPlugin } from '@learncard/learn-cloud-plugin';
+import { ExpirationPlugin } from '@learncard/expiration-plugin';
+import { EthereumPlugin, EthereumConfig } from '@learncard/ethereum-plugin';
+import { VpqrPlugin } from '@learncard/vpqr-plugin';
+import { CHAPIPlugin } from '@learncard/chapi-plugin';
+import { VCAPIPlugin } from '@learncard/vc-api-plugin';
+import { LearnCardPlugin } from '@learncard/learn-card-plugin';
+import { VerifyBoostPlugin, LearnCardNetworkPlugin } from '@learncard/network-plugin';
+import { DidWebPlugin } from '@learncard/did-web-plugin';
+import { EncryptionPluginType } from '@learncard/encryption-plugin';
+import { OpenID4VCPlugin, OpenID4VCPluginConfig } from '@learncard/openid4vc-plugin';
+import { SdJwtVcPlugin } from '@learncard/sd-jwt-vc-plugin';
+
+import { InitFunction, GenericInitFunction } from './helpers';
+
+export type GuardianApprovalGetter = () => string | undefined | Promise<string | undefined>;
+
+/** @group LearnCard */
+export type LearnCardConfig = {
+    cloud?: {
+        url?: string;
+        unencryptedFields?: string[];
+        unencryptedCustomFields?: string[];
+        automaticallyAssociateDids?: boolean;
+    };
+    didkit: InitInput | Promise<InitInput> | 'node';
+    allowRemoteContexts?: boolean;
+    ethereumConfig: EthereumConfig;
+    /**
+     * Optional configuration for the OpenID4VC holder plugin
+     * (OID4VCI + OID4VP + SIOPv2). The plugin is wired automatically
+     * into seed-based wallet shapes; this hook lets hosts customise
+     * the network policy (e.g., a trust-pinned fetch, a custom DID
+     * resolver for verifying Request Objects, X.509 trust roots).
+     * Omitting this works for the common case.
+     */
+    openid4vc?: OpenID4VCPluginConfig;
+    debug?: typeof console.log;
+};
+
+/** @group Init Functions */
+export type EmptyLearnCard = InitFunction<
+    {},
+    'didkit' | 'debug' | 'allowRemoteContexts',
+    LearnCard<
+        [
+            DynamicLoaderPluginType,
+            CryptoPluginType,
+            DIDKitPlugin,
+            ExpirationPlugin,
+            VCTemplatePlugin,
+            CHAPIPlugin,
+            LearnCardPlugin
+        ]
+    >
+>;
+
+/** @group Init Functions */
+export type LearnCardFromSeed = InitFunction<
+    { seed: string },
+    keyof LearnCardConfig,
+    LearnCard<
+        [
+            DynamicLoaderPluginType,
+            CryptoPluginType,
+            DIDKitPlugin,
+            DidKeyPlugin<DidMethod>,
+            EncryptionPluginType,
+            VCPlugin,
+            VCTemplatePlugin,
+            LearnCloudPlugin,
+            ExpirationPlugin,
+            EthereumPlugin,
+            VpqrPlugin,
+            CHAPIPlugin,
+            SdJwtVcPlugin,
+            LearnCardPlugin,
+            OpenID4VCPlugin
+        ]
+    >
+>;
+
+/** @group Init Functions */
+export type NetworkLearnCardFromSeed = InitFunction<
+    {
+        seed: string;
+        network: true | string;
+        trustedBoostRegistry?: string;
+        guardianApprovalGetter?: GuardianApprovalGetter;
+        extraHeaders?: Record<string, string>;
+    },
+    keyof LearnCardConfig,
+    LearnCard<
+        [
+            DynamicLoaderPluginType,
+            CryptoPluginType,
+            DIDKitPlugin,
+            DidKeyPlugin<DidMethod>,
+            EncryptionPluginType,
+            VCPlugin,
+            VCTemplatePlugin,
+            LearnCloudPlugin,
+            ExpirationPlugin,
+            EthereumPlugin,
+            VpqrPlugin,
+            CHAPIPlugin,
+            VerifyBoostPlugin,
+            SdJwtVcPlugin,
+            LearnCardPlugin,
+            LearnCardNetworkPlugin,
+            OpenID4VCPlugin
+        ]
+    >
+>;
+
+/** @group Init Functions */
+export type NetworkLearnCardFromApiKey = InitFunction<
+    {
+        apiKey: string;
+        network: true | string;
+        trustedBoostRegistry?: string;
+        guardianApprovalGetter?: GuardianApprovalGetter;
+        extraHeaders?: Record<string, string>;
+    },
+    'didkit' | 'allowRemoteContexts' | 'debug',
+    LearnCard<
+        [
+            DynamicLoaderPluginType,
+            CryptoPluginType,
+            DIDKitPlugin,
+            VCPlugin,
+            VCTemplatePlugin,
+            ExpirationPlugin,
+            VpqrPlugin,
+            CHAPIPlugin,
+            VerifyBoostPlugin,
+            LearnCardPlugin,
+            LearnCardNetworkPlugin
+        ]
+    >
+>;
+
+/** @group Init Functions */
+export type DidWebLearnCardFromSeed = InitFunction<
+    { seed: string; didWeb: string; trustedBoostRegistry?: string },
+    keyof LearnCardConfig,
+    LearnCard<
+        [
+            DynamicLoaderPluginType,
+            CryptoPluginType,
+            DIDKitPlugin,
+            DidKeyPlugin<DidMethod>,
+            EncryptionPluginType,
+            VCPlugin,
+            VCTemplatePlugin,
+            LearnCloudPlugin,
+            ExpirationPlugin,
+            EthereumPlugin,
+            VpqrPlugin,
+            CHAPIPlugin,
+            SdJwtVcPlugin,
+            LearnCardPlugin,
+            DidWebPlugin,
+            OpenID4VCPlugin
+        ]
+    >
+>;
+
+/** @group Init Functions */
+export type DidWebNetworkLearnCardFromSeed = InitFunction<
+    {
+        seed: string;
+        network: true | string;
+        didWeb: string;
+        trustedBoostRegistry?: string;
+        guardianApprovalGetter?: GuardianApprovalGetter;
+        extraHeaders?: Record<string, string>;
+    },
+    keyof LearnCardConfig,
+    LearnCard<
+        [
+            DynamicLoaderPluginType,
+            CryptoPluginType,
+            DIDKitPlugin,
+            DidKeyPlugin<DidMethod>,
+            EncryptionPluginType,
+            VCPlugin,
+            VCTemplatePlugin,
+            LearnCloudPlugin,
+            ExpirationPlugin,
+            EthereumPlugin,
+            VpqrPlugin,
+            CHAPIPlugin,
+            VerifyBoostPlugin,
+            SdJwtVcPlugin,
+            LearnCardPlugin,
+            DidWebPlugin,
+            LearnCardNetworkPlugin,
+            OpenID4VCPlugin
+        ]
+    >
+>;
+
+/** @group Init Functions */
+export type LearnCardFromVcApi = InitFunction<
+    { vcApi: true | string; did?: string },
+    'debug',
+    LearnCard<
+        [
+            CryptoPluginType,
+            VCAPIPlugin,
+            ExpirationPlugin,
+            VCTemplatePlugin,
+            CHAPIPlugin,
+            LearnCardPlugin
+        ]
+    >
+>;
+
+/** @group Init Functions */
+export type CustomLearnCard = InitFunction<{ custom: true }, 'debug', LearnCard<[]>>;
+
+/** @group Init Functions */
+export type InitLearnCard = GenericInitFunction<
+    [
+        EmptyLearnCard,
+        LearnCardFromSeed,
+        NetworkLearnCardFromSeed,
+        DidWebLearnCardFromSeed,
+        DidWebNetworkLearnCardFromSeed,
+        LearnCardFromVcApi,
+        CustomLearnCard,
+        NetworkLearnCardFromApiKey
+    ]
+>;

package/src/types/didkit-plugin-node-ambient.d.ts

@@ -0,0 +1,6 @@
+declare module '@learncard/didkit-plugin-node' {
+  export const getDidKitPlugin: (
+    input?: unknown,
+    allowRemoteContexts?: boolean
+  ) => Promise<import('@learncard/didkit-plugin').DIDKitPlugin>;
+}

package/src/types/helpers.ts

@@ -0,0 +1,17 @@
+import { LearnCardConfig } from './LearnCard';
+import { LearnCard } from '@learncard/core';
+
+export type InitFunction<
+    Args extends Record<string, any> = Record<string, any>,
+    Config extends keyof LearnCardConfig | undefined = keyof LearnCardConfig,
+    ReturnValue extends LearnCard<any, any> = LearnCard<any, any>
+> = {
+    args: Args &
+    (undefined extends Config ? {} : Partial<Pick<LearnCardConfig, NonNullable<Config>>>);
+    returnValue: ReturnValue;
+};
+
+export type GenericInitFunction<InitFunctions extends InitFunction<any, any, any>[]> = {
+    args: InitFunctions[number]['args'];
+    returnValue: Promise<InitFunctions[number]['returnValue']>;
+};

package/dist/node-esm.mjs

@@ -1,32 +0,0 @@
-// Node ESM entrypoint (resolved via the `node.import` export condition).
-//
-// Node consumers are deliberately routed to the CommonJS bundle (`index.cjs`,
-// which switches between the dev / minified prod CJS builds via NODE_ENV).
-// We load it with `createRequire` rather than a static `import ... from
-// './index.cjs'`.
-//
-// Why: a static ESM import of a CJS file is the one shape that breaks bundlers.
-// When a bundler (e.g. Vite/Astro SSR) transforms this module — which it does
-// for symlinked workspace deps — it follows the static import into `index.cjs`
-// and tries to transform that CommonJS file as ESM, throwing
-// `module is not defined`. `createRequire` keeps the CJS loading opaque to the
-// bundler's ESM transform and hands it to Node's native CommonJS loader, where
-// `module` / `require` are defined. Runtime behavior for Node consumers is
-// unchanged (same CJS bundle, same didkit backend); bundler-transformed
-// symlinked consumers no longer need `ssr.external` / `optimizeDeps` guards.
-import { createRequire } from 'node:module';
-
-const require = createRequire(import.meta.url);
-const init = require('./index.cjs');
-
-export const customLearnCard = init.customLearnCard;
-export const didWebLearnCardFromSeed = init.didWebLearnCardFromSeed;
-export const didWebNetworkLearnCardFromSeed = init.didWebNetworkLearnCardFromSeed;
-export const emptyLearnCard = init.emptyLearnCard;
-export const initLearnCard = init.initLearnCard;
-export const learnCardFromApiUrl = init.learnCardFromApiUrl;
-export const learnCardFromSeed = init.learnCardFromSeed;
-export const networkLearnCardFromApiKey = init.networkLearnCardFromApiKey;
-export const networkLearnCardFromSeed = init.networkLearnCardFromSeed;
-
-export default init;