@learncard/network-plugin 2.13.15 → 2.13.17

package/dist/plugin.d.ts

@@ -1,19 +1,39 @@
 import { LearnCard } from '@learncard/core';
 import { VerifyExtension } from '@learncard/vc-plugin';
 import { LearnCardNetworkPluginDependentMethods, LearnCardNetworkPlugin, VerifyBoostPlugin } from './types';
+/**
+ * Configuration for federation URL validation.
+ */
+export interface FederationConfig {
+    /**
+     * Explicit list of trusted hosts. If not provided, federation is open (any HTTPS host allowed).
+     * This is safe for client-side code where SSRF doesn't apply.
+     * Server-side code should provide an explicit allowlist.
+     */
+    trustedFederationHosts?: string[];
+    /**
+     * Allow localhost/127.0.0.1 for development.
+     * Auto-detected: defaults to true when serviceUrl is localhost, false otherwise.
+     */
+    allowLocalhostFederation?: boolean;
+    /**
+     * The origin of this plugin's service URL. When set, endpoints matching this origin
+     * skip validation (they're self-generated, not from external DID documents).
+     */
+    serviceOrigin?: string;
+}
 export * from './types';
 export type GuardianApprovalGetter = () => string | undefined | Promise<string | undefined>;
 /**
  * @group Plugins
  */
-export declare function getLearnCardNetworkPlugin(learnCard: LearnCard<any, 'id', LearnCardNetworkPluginDependentMethods>, url: string, apiTokenOrOptions?: {
-    guardianApprovalGetter?: GuardianApprovalGetter;
-    extraHeaders?: Record<string, string>;
-}): Promise<LearnCardNetworkPlugin>;
-export declare function getLearnCardNetworkPlugin(learnCard: LearnCard<any, any, LearnCardNetworkPluginDependentMethods>, url: string, apiToken: string, options?: {
+/** Options for the LearnCard Network Plugin */
+export interface LearnCardNetworkPluginOptions extends FederationConfig {
     guardianApprovalGetter?: GuardianApprovalGetter;
     extraHeaders?: Record<string, string>;
-}): Promise<LearnCardNetworkPlugin>;
+}
+export declare function getLearnCardNetworkPlugin(learnCard: LearnCard<any, 'id', LearnCardNetworkPluginDependentMethods>, url: string, apiTokenOrOptions?: LearnCardNetworkPluginOptions): Promise<LearnCardNetworkPlugin>;
+export declare function getLearnCardNetworkPlugin(learnCard: LearnCard<any, any, LearnCardNetworkPluginDependentMethods>, url: string, apiToken: string, options?: LearnCardNetworkPluginOptions): Promise<LearnCardNetworkPlugin>;
 /**
  * @group Plugins
  */

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAQvD,OAAO,EACH,sCAAsC,EACtC,sBAAsB,EACtB,iBAAiB,EAEpB,MAAM,SAAS,CAAC;AAwRjB,cAAc,SAAS,CAAC;AAExB,MAAM,MAAM,sBAAsB,GAAG,MAAM,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAE5F;;GAEG;AACH,wBAAsB,yBAAyB,CAC3C,SAAS,EAAE,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,sCAAsC,CAAC,EACvE,GAAG,EAAE,MAAM,EACX,iBAAiB,CAAC,EAAE;IAChB,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC,GACF,OAAO,CAAC,sBAAsB,CAAC,CAAC;AACnC,wBAAsB,yBAAyB,CAC3C,SAAS,EAAE,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,sCAAsC,CAAC,EACtE,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IACN,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC,GACF,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAgxEnC;;GAEG;AACH,eAAO,MAAM,oBAAoB,cAClB,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,eAAe,CAAC,4BACrB,MAAM,KACjC,OAAO,CAAC,iBAAiB,CA+G3B,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAQvD,OAAO,EACH,sCAAsC,EACtC,sBAAsB,EACtB,iBAAiB,EAEpB,MAAM,SAAS,CAAC;AAUjB;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC;;;OAGG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B;AA2XD,cAAc,SAAS,CAAC;AAExB,MAAM,MAAM,sBAAsB,GAAG,MAAM,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAE5F;;GAEG;AACH,+CAA+C;AAC/C,MAAM,WAAW,6BAA8B,SAAQ,gBAAgB;IACnE,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAED,wBAAsB,yBAAyB,CAC3C,SAAS,EAAE,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,sCAAsC,CAAC,EACvE,GAAG,EAAE,MAAM,EACX,iBAAiB,CAAC,EAAE,6BAA6B,GAClD,OAAO,CAAC,sBAAsB,CAAC,CAAC;AACnC,wBAAsB,yBAAyB,CAC3C,SAAS,EAAE,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,sCAAsC,CAAC,EACtE,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,6BAA6B,GACxC,OAAO,CAAC,sBAAsB,CAAC,CAAC;AA6xEnC;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAC7B,WAAW,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,eAAe,CAAC,EAC/C,0BAA0B,MAAM,KACjC,OAAO,CAAC,iBAAiB,CA8G3B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/network-plugin",
-    "version": "2.13.15",
+    "version": "2.13.17",
     "description": "",
     "type": "module",
     "main": "./dist/index.cjs",
@@ -39,10 +39,10 @@
         "url": "https://github.com/learningeconomy/LearnCard/issues"
     },
     "devDependencies": {
-        "@learncard/didkey-plugin": "^1.1.31",
-        "@learncard/didkit-plugin": "^1.9.11",
-        "@learncard/types": "5.18.2",
-        "@learncard/vc-plugin": "^1.5.11",
+        "@learncard/didkey-plugin": "^1.1.33",
+        "@learncard/didkit-plugin": "^1.9.13",
+        "@learncard/types": "5.18.3",
+        "@learncard/vc-plugin": "^1.5.13",
         "@types/node": "^17.0.31",
         "aqu": "0.4.3",
         "esbuild": "^0.27.1",
@@ -52,9 +52,9 @@
     },
     "types": "./dist/index.d.ts",
     "dependencies": {
-        "@learncard/core": "9.4.31",
-        "@learncard/helpers": "1.3.13",
-        "@learncard/network-brain-client": "2.5.52",
+        "@learncard/core": "9.4.33",
+        "@learncard/helpers": "1.4.1",
+        "@learncard/network-brain-client": "2.5.54",
         "mustache": "^4.2.0"
     },
     "sideEffects": false

package/src/plugin.ts

@@ -34,6 +34,135 @@ import {
     TrustedBoostRegistryEntry,
 } from './types';
 
+/**
+ * Trusted LearnCard domain suffixes for federation.
+ * Only dotted suffixes - the isLearnCardDomain check handles apex domains via
+ * `host === suffix.replace(/^\./, '')`. Bare entries would allow bypass
+ * (e.g., 'evillearncard.com'.endsWith('learncard.com') === true).
+ */
+const LEARNCARD_DOMAIN_SUFFIXES = ['.learncard.com', '.learncard.app', '.learncard.ai'];
+
+/**
+ * Configuration for federation URL validation.
+ */
+export interface FederationConfig {
+    /**
+     * Explicit list of trusted hosts. If not provided, federation is open (any HTTPS host allowed).
+     * This is safe for client-side code where SSRF doesn't apply.
+     * Server-side code should provide an explicit allowlist.
+     */
+    trustedFederationHosts?: string[];
+    /**
+     * Allow localhost/127.0.0.1 for development.
+     * Auto-detected: defaults to true when serviceUrl is localhost, false otherwise.
+     */
+    allowLocalhostFederation?: boolean;
+    /**
+     * The origin of this plugin's service URL. When set, endpoints matching this origin
+     * skip validation (they're self-generated, not from external DID documents).
+     */
+    serviceOrigin?: string;
+}
+
+/**
+ * Checks if a hostname matches any LearnCard domain suffix.
+ */
+const isLearnCardDomain = (host: string): boolean => {
+    return LEARNCARD_DOMAIN_SUFFIXES.some(
+        suffix => host === suffix.replace(/^\./, '') || host.endsWith(suffix)
+    );
+};
+
+/**
+ * Checks if a hostname is localhost or loopback.
+ */
+const isLocalhostHost = (host: string): boolean => {
+    const lower = host.toLowerCase();
+    return lower === 'localhost' || lower === '127.0.0.1';
+};
+
+/**
+ * Validates and normalizes a federation URL.
+ *
+ * This runs in the CLIENT plugin where SSRF risk is lower (the browser's same-origin
+ * policy provides protection). By default, federation is open to any HTTPS host.
+ * Server-side code should provide an explicit trustedFederationHosts list.
+ *
+ * Note: For local-service recipients, getInboxEndpointForDid returns a fixed
+ * `/api/inbox/receive` path. Only external DID doc serviceEndpoints preserve
+ * their original path.
+ *
+ * @param userProvidedUrl - The inbox endpoint URL (from DID doc or local service)
+ * @param config - Federation configuration with trusted hosts
+ * @returns The validated URL
+ * @throws Error if the URL is invalid or host is not trusted
+ */
+const validateFederationUrl = (userProvidedUrl: string, config: FederationConfig): string => {
+    let parsed: URL;
+    try {
+        parsed = new URL(userProvidedUrl);
+    } catch {
+        throw new Error(`Invalid federation endpoint URL: ${userProvidedUrl}`);
+    }
+
+    // If this endpoint matches our own service origin, skip validation entirely.
+    // These URLs are self-generated (e.g., from getInboxEndpointForDid when the recipient
+    // resolves to our local service), not from external DID documents.
+    if (config.serviceOrigin) {
+        const endpointOrigin = parsed.origin;
+        if (endpointOrigin === config.serviceOrigin) {
+            // Self-referential URL - return parsed.href so CodeQL sees URL sanitization
+            return parsed.href;
+        }
+    }
+
+    const host = parsed.hostname.toLowerCase();
+    const isLocalhost = isLocalhostHost(host);
+
+    // Handle localhost: check allowLocalhostFederation and convert https->http
+    if (isLocalhost) {
+        if (!config.allowLocalhostFederation) {
+            throw new Error(
+                `Localhost federation is disabled. Set allowLocalhostFederation: true for development.`
+            );
+        }
+        // Local dev typically doesn't have TLS - convert https to http
+        if (parsed.protocol === 'https:') {
+            parsed.protocol = 'http:';
+        }
+        // Return the validated/normalized URL
+        return parsed.href;
+    }
+
+    // Validate protocol - require HTTPS for non-localhost
+    if (parsed.protocol !== 'https:') {
+        throw new Error(`Federation requires HTTPS for non-localhost hosts: ${userProvidedUrl}`);
+    }
+
+    // If trustedFederationHosts is provided, use explicit allowlist mode
+    if (config.trustedFederationHosts !== undefined) {
+        const trustedHosts = new Set(config.trustedFederationHosts);
+        const allowAnyHost = trustedHosts.has('*');
+
+        // Check explicit list, LearnCard domains, or wildcard.
+        // Note: LearnCard domains are always trusted even with an explicit allowlist -
+        // this is intentional to ensure core federation always works.
+        if (!allowAnyHost && !isLearnCardDomain(host) && !trustedHosts.has(host)) {
+            throw new Error(
+                `Federation host '${host}' is not trusted. ` +
+                    `Add it to trustedFederationHosts or use '*' to allow any host.`
+            );
+        }
+    }
+    // If trustedFederationHosts is not provided, allow any HTTPS host (client-side default)
+    // This enables third-party did:web federation without requiring explicit opt-in
+
+    // Return the validated URL - CodeQL: at this point the URL has been validated
+    // as either matching our service origin, being localhost with permission, or
+    // being HTTPS with a trusted/allowed host
+    return parsed.href;
+};
+
 const uint8ArrayToBase64Url = (bytes: Uint8Array): string => {
     let binary = '';
     for (let i = 0; i < bytes.length; i += 1) binary += String.fromCharCode(bytes[i]!);
@@ -319,46 +448,52 @@ export type GuardianApprovalGetter = () => string | undefined | Promise<string |
 /**
  * @group Plugins
  */
+/** Options for the LearnCard Network Plugin */
+export interface LearnCardNetworkPluginOptions extends FederationConfig {
+    guardianApprovalGetter?: GuardianApprovalGetter;
+    extraHeaders?: Record<string, string>;
+}
+
 export async function getLearnCardNetworkPlugin(
     learnCard: LearnCard<any, 'id', LearnCardNetworkPluginDependentMethods>,
     url: string,
-    apiTokenOrOptions?: {
-        guardianApprovalGetter?: GuardianApprovalGetter;
-        extraHeaders?: Record<string, string>;
-    }
+    apiTokenOrOptions?: LearnCardNetworkPluginOptions
 ): Promise<LearnCardNetworkPlugin>;
 export async function getLearnCardNetworkPlugin(
     learnCard: LearnCard<any, any, LearnCardNetworkPluginDependentMethods>,
     url: string,
     apiToken: string,
-    options?: {
-        guardianApprovalGetter?: GuardianApprovalGetter;
-        extraHeaders?: Record<string, string>;
-    }
+    options?: LearnCardNetworkPluginOptions
 ): Promise<LearnCardNetworkPlugin>;
 export async function getLearnCardNetworkPlugin(
     learnCard: LearnCard<any, any, LearnCardNetworkPluginDependentMethods>,
     url: string,
-    apiTokenOrOptions?:
-        | string
-        | {
-              guardianApprovalGetter?: GuardianApprovalGetter;
-              extraHeaders?: Record<string, string>;
-          },
-    options?: {
-        guardianApprovalGetter?: GuardianApprovalGetter;
-        extraHeaders?: Record<string, string>;
-    }
+    apiTokenOrOptions?: string | LearnCardNetworkPluginOptions,
+    options?: LearnCardNetworkPluginOptions
 ): Promise<LearnCardNetworkPlugin> {
     const apiToken = typeof apiTokenOrOptions === 'string' ? apiTokenOrOptions : undefined;
-    const guardianApprovalGetter =
-        (typeof apiTokenOrOptions === 'object'
-            ? apiTokenOrOptions?.guardianApprovalGetter
-            : undefined) ?? options?.guardianApprovalGetter;
-
-    const extraHeaders =
-        (typeof apiTokenOrOptions === 'object' ? apiTokenOrOptions?.extraHeaders : undefined) ??
-        options?.extraHeaders;
+    const resolvedOptions: LearnCardNetworkPluginOptions =
+        (typeof apiTokenOrOptions === 'object' ? apiTokenOrOptions : options) ?? {};
+
+    const {
+        guardianApprovalGetter,
+        extraHeaders,
+        trustedFederationHosts,
+        allowLocalhostFederation,
+    } = resolvedOptions;
+
+    // Parse service URL to determine origin and auto-detect localhost
+    const serviceUrl = new URL(url);
+    const serviceIsLocalhost = isLocalhostHost(serviceUrl.hostname);
+
+    // Federation config for URL validation
+    // - serviceOrigin: skip validation for self-referential URLs
+    // - allowLocalhostFederation: auto-detect from service URL if not explicitly set
+    const federationConfig: FederationConfig = {
+        trustedFederationHosts,
+        allowLocalhostFederation: allowLocalhostFederation ?? serviceIsLocalhost,
+        serviceOrigin: serviceUrl.origin,
+    };
     // Initialize DID safely: in API-key mode there may be no local ID plane provider
     let did = '';
     try {
@@ -713,7 +848,11 @@ export async function getLearnCardNetworkPlugin(
                 return client.profileManager.updateProfileManager.mutate(manager);
             },
             deleteProfile: async () => {
-                if (!userData) throw new Error('Account does not exist!');
+                // Settle initialization before deletion so it cannot repopulate userData later.
+                await initialQuery;
+                // API tokens may grant profiles:delete without profiles:read. The server
+                // validates the profile and scope; a local read must not gate deletion.
+                if (!apiToken) await ensureUser();
 
                 const result = await client.profile.deleteProfile.mutate();
 
@@ -910,13 +1049,14 @@ export async function getLearnCardNetworkPlugin(
                         challenge: `inbox-federation-${crypto.randomUUID()}`,
                     });
 
-                    let receiveUrl = inboxEndpoint;
-
-                    if (receiveUrl.includes('localhost')) {
-                        receiveUrl = receiveUrl.replace('https://', 'http://');
-                    }
+                    // Validate the federation URL. For external DIDs, inboxEndpoint comes
+                    // from the DID doc's serviceEndpoint; for local-service DIDs, it's
+                    // a fixed /api/inbox/receive path from getInboxEndpointForDid.
+                    const receiveUrl = validateFederationUrl(inboxEndpoint, federationConfig);
 
                     const response = await fetch(receiveUrl, {
+                        // A redirect must not bypass endpoint validation or forward credentials.
+                        redirect: 'error',
                         method: 'POST',
                         headers: {
                             'Content-Type': 'application/json',
@@ -2645,7 +2785,9 @@ export async function getLearnCardNetworkPlugin(
 
             isServiceTrusted: async (_learnCard, serviceDid) => {
                 const trustedServices = await client.federation.getTrustedServices.query({});
-                return trustedServices.some(s => s.did === serviceDid);
+                return trustedServices.some(
+                    (service: { did: string }) => service.did === serviceDid
+                );
             },
 
             getTrustedServices: async () => {
@@ -2713,9 +2855,8 @@ export const getVerifyBoostPlugin = async (
                 const boostCredential = credential?.boostCredential;
                 try {
                     if (boostCredential) {
-                        const verifyBoostCredential = await learnCard.invoke.verifyCredential(
-                            boostCredential
-                        );
+                        const verifyBoostCredential =
+                            await learnCard.invoke.verifyCredential(boostCredential);
                         const boostCredentialErrors = verifyBoostCredential.errors ?? [];
                         if (verifyBoostCredential.status?.length) {
                             verificationCheck.status = [