@twin.org/node-core 0.0.2-next.24 → 0.0.2-next.26

package/dist/esm/index.mjs

@@ -1,19 +1,20 @@
 import { PasswordHelper } from '@twin.org/api-auth-entity-storage-service';
-import { I18n, Is, Coerce, Converter, RandomHelper, Urn, GeneralError, EnvHelper } from '@twin.org/core';
-import { PasswordGenerator, Bip39 } from '@twin.org/crypto';
+import { I18n, Is, Converter, GeneralError, BaseError, Coerce, RandomHelper, Urn, EnvHelper } from '@twin.org/core';
+import { Sha256, PasswordGenerator, Bip39 } from '@twin.org/crypto';
 import { AuthenticationComponentType, InformationComponentType, RestRouteProcessorType, SocketRouteProcessorType, AuthenticationAdminComponentType } from '@twin.org/engine-server-types';
 import { WalletConnectorType, IdentityConnectorType, EntityStorageConnectorType, BlobStorageConnectorType, BlobStorageComponentType, VaultConnectorType, DltConfigType, LoggingConnectorType, LoggingComponentType, BackgroundTaskConnectorType, TaskSchedulerComponentType, EventBusConnectorType, EventBusComponentType, TelemetryConnectorType, TelemetryComponentType, MessagingEmailConnectorType, MessagingSmsConnectorType, MessagingPushNotificationConnectorType, MessagingAdminComponentType, MessagingComponentType, FaucetConnectorType, EngineTypeHelper, NftConnectorType, NftComponentType, VerifiableStorageConnectorType, VerifiableStorageComponentType, ImmutableProofComponentType, IdentityComponentType, IdentityResolverConnectorType, IdentityResolverComponentType, IdentityProfileConnectorType, IdentityProfileComponentType, AttestationConnectorType, AttestationComponentType, DataProcessingComponentType, DataConverterConnectorType, DataExtractorConnectorType, AuditableItemGraphComponentType, AuditableItemStreamComponentType, DocumentManagementComponentType, AuthenticationGeneratorComponentType, RightsManagementPapComponentType, RightsManagementPmpComponentType, RightsManagementPipComponentType, RightsManagementPxpComponentType, RightsManagementPdpComponentType, RightsManagementPepComponentType, RightsManagementPnpComponentType, RightsManagementPnapComponentType, RightsManagementDapComponentType, RightsManagementDarpComponentType, SynchronisedStorageComponentType, FederatedCatalogueComponentType, DataSpaceConnectorComponentType } from '@twin.org/engine-types';
 import { EntityStorageConnectorFactory } from '@twin.org/entity-storage-models';
 import { IdentityProfileConnectorFactory, IdentityConnectorFactory, IdentityResolverConnectorFactory, DocumentHelper } from '@twin.org/identity-models';
 import { VaultConnectorFactory, VaultKeyType } from '@twin.org/vault-models';
 import { WalletConnectorFactory } from '@twin.org/wallet-models';
-import { readFile, stat, readdir } from 'node:fs/promises';
+import { execSync } from 'node:child_process';
+import { readFile, stat, readdir, mkdir, writeFile, rename } from 'node:fs/promises';
+import { get } from 'node:https';
 import path from 'node:path';
 import { CLIDisplay } from '@twin.org/cli-core';
-import { PolicyNegotiationPointClient, DataAccessPointClient } from '@twin.org/rights-management-rest-client';
-import { addDefaultRestPaths, addDefaultSocketPaths, EngineServer } from '@twin.org/engine-server';
 import { ModuleHelper } from '@twin.org/modules';
-import { execSync } from 'node:child_process';
+import { PolicyNegotiationPointRestClient, DataAccessPointRestClient } from '@twin.org/rights-management-rest-client';
+import { addDefaultRestPaths, addDefaultSocketPaths, EngineServer } from '@twin.org/engine-server';
 import * as dotenv from 'dotenv';
 import { Engine } from '@twin.org/engine';
 import { FileStateStorage } from '@twin.org/engine-core';
@@ -49,6 +50,35 @@ const NodeFeatures = {
     NodeWallet: "node-wallet"
 };
 
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The protocol types for modules.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const ModuleProtocol = {
+    /**
+     * Local module (starts with . or / or file://).
+     */
+    Local: "local",
+    /**
+     * NPM package (starts with npm:).
+     */
+    Npm: "npm",
+    /**
+     * HTTPS URL (starts with https://).
+     */
+    Https: "https",
+    /**
+     * HTTP URL (starts with http://).
+     */
+    Http: "http",
+    /**
+     * Default/standard module resolution.
+     */
+    Default: "default"
+};
+
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 /**
@@ -182,6 +212,280 @@ function getFeatures(env) {
     }
     return features;
 }
+/**
+ * Parse the protocol from a module name.
+ * @param moduleName The module name to parse.
+ * @returns The parsed protocol information.
+ */
+function parseModuleProtocol(moduleName) {
+    const trimmed = moduleName.trim();
+    if (trimmed.startsWith("npm:")) {
+        return {
+            protocol: ModuleProtocol.Npm,
+            identifier: trimmed.slice(4),
+            original: trimmed
+        };
+    }
+    if (trimmed.startsWith("https://")) {
+        return {
+            protocol: ModuleProtocol.Https,
+            identifier: trimmed,
+            original: trimmed
+        };
+    }
+    if (trimmed.startsWith("http://")) {
+        return {
+            protocol: ModuleProtocol.Http,
+            identifier: trimmed,
+            original: trimmed
+        };
+    }
+    if (trimmed.startsWith("file://")) {
+        return {
+            protocol: ModuleProtocol.Local,
+            identifier: trimmed,
+            original: trimmed
+        };
+    }
+    if (ModuleHelper.isLocalModule(trimmed)) {
+        return {
+            protocol: ModuleProtocol.Local,
+            identifier: trimmed,
+            original: trimmed
+        };
+    }
+    return {
+        protocol: ModuleProtocol.Default,
+        identifier: trimmed,
+        original: trimmed
+    };
+}
+/**
+ * Hash a URL to create a safe filename.
+ * @param url The URL to hash.
+ * @returns A hashed filename safe for the filesystem.
+ */
+function hashUrl(url) {
+    const urlBytes = Converter.utf8ToBytes(url);
+    const hashBytes = Sha256.sum256(urlBytes);
+    const hash = Converter.bytesToHex(hashBytes);
+    const ext = path.extname(new URL(url).pathname);
+    return `${hash}${ext}`;
+}
+/**
+ * Get the extensions cache directory.
+ * @param executionDirectory The execution directory.
+ * @param protocol The protocol type for subdirectory organization.
+ * @param cacheDirectory The cache directory base path.
+ * @returns The cache directory path.
+ */
+function getExtensionsCacheDir(executionDirectory, protocol, cacheDirectory) {
+    // Resolve to absolute path to ensure consistent behavior
+    const absoluteDir = path.resolve(executionDirectory);
+    const baseDir = cacheDirectory ?? ".tmp";
+    return path.join(absoluteDir, baseDir, "extensions", protocol);
+}
+/**
+ * Handle the npm: protocol by installing the package if needed.
+ * @param packageName The npm package name (without npm: prefix).
+ * @param executionDirectory The execution directory.
+ * @param cacheDirectory The cache directory base path.
+ * @returns The resolved path to the installed module.
+ */
+async function handleNpmProtocol(packageName, executionDirectory, cacheDirectory) {
+    const cacheDir = getExtensionsCacheDir(executionDirectory, ModuleProtocol.Npm, cacheDirectory);
+    // Extract just the package name (without version) for the directory
+    // e.g. "picocolors@1.0.0" becomes "picocolors"
+    // e.g. "@scope/package@1.0.0" becomes "@scope/package"
+    const lastAtIndex = packageName.lastIndexOf("@");
+    const packageNameOnly = lastAtIndex > 0 ? packageName.slice(0, lastAtIndex) : packageName;
+    const packageDir = path.join(cacheDir, "node_modules", packageNameOnly);
+    const packageJsonPath = path.join(packageDir, "package.json");
+    const exists = await fileExists(packageJsonPath);
+    if (exists) {
+        const mainFile = await resolvePackageEntryPoint(packageDir, packageNameOnly);
+        const modulePath = path.join(packageDir, mainFile);
+        return {
+            resolvedPath: modulePath,
+            cached: true
+        };
+    }
+    await mkdir(cacheDir, { recursive: true });
+    CLIDisplay.task(I18n.formatMessage("node.extensionNpmInstalling"), packageName);
+    try {
+        // Always pipe stdio to comply with env access restrictions in tests/lint
+        const stdio = "pipe";
+        execSync(`npm install ${packageName} --prefix "${cacheDir}" --no-save --no-package-lock`, {
+            cwd: cacheDir,
+            stdio
+        });
+    }
+    catch (err) {
+        throw new GeneralError("node", "extensionNpmInstallFailed", {
+            package: packageName
+        }, BaseError.fromError(err));
+    }
+    const mainFile = await resolvePackageEntryPoint(packageDir, packageNameOnly);
+    const modulePath = path.join(packageDir, mainFile);
+    return {
+        resolvedPath: modulePath,
+        cached: false
+    };
+}
+/**
+ * Check if a cached file has expired based on TTL and force refresh settings.
+ * @param metadataPath Path to the cache metadata file.
+ * @param ttlHours Time to live in hours.
+ * @param forceRefresh Whether to force refresh regardless of TTL.
+ * @returns True if the cache is expired or should be refreshed.
+ */
+async function isCacheExpired(metadataPath, ttlHours, forceRefresh) {
+    if (forceRefresh) {
+        return true;
+    }
+    try {
+        const metadata = await loadJsonFile(metadataPath);
+        const ttlMillis = ttlHours * 60 * 60 * 1000;
+        const expireTime = metadata.downloadedAt + ttlMillis;
+        return Date.now() > expireTime;
+    }
+    catch {
+        // If metadata doesn't exist or is corrupted, consider expired
+        return true;
+    }
+}
+/**
+ * Handle the https: protocol by downloading the module if needed.
+ * @param url The HTTPS URL to download from.
+ * @param executionDirectory The execution directory.
+ * @param maxSizeMb The maximum size in MB for the download.
+ * @param cacheDirectory The cache directory base path.
+ * @param ttlHours TTL in hours for cache expiration.
+ * @param forceRefresh Whether to force refresh the cache.
+ * @returns The resolved path to the downloaded module.
+ */
+async function handleHttpsProtocol(url, executionDirectory, maxSizeMb, cacheDirectory, ttlHours, forceRefresh) {
+    const effectiveTtlHours = ttlHours ?? 24;
+    const effectiveForceRefresh = forceRefresh ?? false;
+    const cacheDir = getExtensionsCacheDir(executionDirectory, ModuleProtocol.Https, cacheDirectory);
+    const filename = hashUrl(url);
+    const cachedPath = path.join(cacheDir, filename);
+    const metadataPath = `${cachedPath}.meta`;
+    const exists = await fileExists(cachedPath);
+    if (exists) {
+        const expired = await isCacheExpired(metadataPath, effectiveTtlHours, effectiveForceRefresh);
+        if (!expired) {
+            return {
+                resolvedPath: cachedPath,
+                cached: true
+            };
+        }
+        if (effectiveForceRefresh) {
+            CLIDisplay.warning(I18n.formatMessage("node.extensionForceRefresh", { url }));
+        }
+        else {
+            CLIDisplay.task(I18n.formatMessage("node.extensionCacheExpired", { url }));
+        }
+    }
+    CLIDisplay.warning(I18n.formatMessage("node.extensionSecurityWarning", { url }));
+    CLIDisplay.task(I18n.formatMessage("node.extensionHttpsDownloading"), url);
+    await mkdir(cacheDir, { recursive: true });
+    const maxSizeBytes = maxSizeMb * 1024 * 1024;
+    let downloadedSize = 0;
+    const chunks = [];
+    try {
+        await new Promise((resolve, reject) => {
+            get(url, response => {
+                if (response.statusCode !== 200) {
+                    reject(new GeneralError("node", "extensionDownloadFailed", {
+                        url,
+                        status: response.statusCode ?? 0
+                    }));
+                    return;
+                }
+                response.on("data", (chunk) => {
+                    downloadedSize += chunk.length;
+                    if (downloadedSize > maxSizeBytes) {
+                        response.destroy();
+                        reject(new GeneralError("node", "extensionSizeLimitExceeded", {
+                            size: downloadedSize,
+                            limit: maxSizeBytes
+                        }));
+                        return;
+                    }
+                    chunks.push(chunk);
+                });
+                response.on("end", () => {
+                    resolve();
+                });
+                response.on("error", err => {
+                    reject(BaseError.fromError(err));
+                });
+            }).on("error", err => {
+                reject(BaseError.fromError(err));
+            });
+        });
+    }
+    catch (err) {
+        throw new GeneralError("node", "extensionDownloadFailed", {
+            url
+        }, BaseError.fromError(err));
+    }
+    const tempPath = `${cachedPath}.tmp`;
+    await writeFile(tempPath, Buffer.concat(chunks));
+    // Atomic move from temp to final location
+    await rename(tempPath, cachedPath);
+    // Save metadata for TTL tracking
+    const metadata = {
+        downloadedAt: Date.now(),
+        url,
+        size: Buffer.concat(chunks).length
+    };
+    await writeFile(metadataPath, JSON.stringify(metadata, null, 2));
+    return {
+        resolvedPath: cachedPath,
+        cached: false
+    };
+}
+/**
+ * Resolve the main entry point from a package directory using Node.js resolution with fallback.
+ * Uses require.resolve() when possible for standard Node.js behavior, with manual fallback.
+ * @param packagePath The absolute path to the package directory.
+ * @param packageName The package name for require.resolve().
+ * @param fallback The fallback file name if no entry point is found.
+ * @returns The resolved entry point file name (relative to package directory).
+ */
+async function resolvePackageEntryPoint(packagePath, packageName, fallback = "index.js") {
+    try {
+        // Try require.resolve() first - handles exports, main, module automatically
+        const resolvedPath = require.resolve(packageName, { paths: [path.dirname(packagePath)] });
+        // Convert absolute path back to relative filename within package
+        const relativePath = path.relative(packagePath, resolvedPath);
+        return relativePath ?? fallback;
+    }
+    catch {
+        // Fallback to manual package.json parsing if require.resolve fails
+        try {
+            const packageJsonPath = path.join(packagePath, "package.json");
+            const packageJsonContent = await loadJsonFile(packageJsonPath);
+            // Future: Could expand exports field support here
+            return packageJsonContent.module ?? packageJsonContent.main ?? fallback;
+        }
+        catch {
+            return fallback;
+        }
+    }
+}
+/**
+ * Convert a file path to an import-compatible URL for cross-platform module loading.
+ * On Windows, adds the 'file://' protocol prefix required for dynamic imports.
+ * On other platforms, returns the path unchanged.
+ * @param filePath The absolute file path to convert.
+ * @returns A URL string compatible with dynamic import().
+ */
+function createModuleImportUrl(filePath) {
+    return process.platform === "win32" ? `file://${filePath}` : filePath;
+}
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
@@ -1494,7 +1798,7 @@ async function configureRightsManagement(coreConfig, envVars) {
                     offers: Is.arrayValue(envVars.rightsManagementOffers)
                         ? envVars.rightsManagementOffers
                         : [],
-                    negotiationComponentCreator: async (url) => new PolicyNegotiationPointClient({ endpoint: url })
+                    negotiationComponentCreator: async (url) => new PolicyNegotiationPointRestClient({ endpoint: url })
                 }
             }
         });
@@ -1511,7 +1815,7 @@ async function configureRightsManagement(coreConfig, envVars) {
             type: RightsManagementDarpComponentType.Service,
             options: {
                 config: {
-                    dataAccessComponentCreator: async (url) => new DataAccessPointClient({ endpoint: url })
+                    dataAccessComponentCreator: async (url) => new DataAccessPointRestClient({ endpoint: url })
                 }
             }
         });
@@ -1973,7 +2277,7 @@ async function run(nodeOptions) {
         nodeOptions ??= {};
         const serverInfo = {
             name: nodeOptions?.serverName ?? "TWIN Node Server",
-            version: nodeOptions?.serverVersion ?? "0.0.2-next.24" // x-release-please-version
+            version: nodeOptions?.serverVersion ?? "0.0.2-next.26" // x-release-please-version
         };
         CLIDisplay.header(serverInfo.name, serverInfo.version, "🌩️ ");
         if (!Is.stringValue(nodeOptions?.executionDirectory)) {
@@ -2111,10 +2415,13 @@ async function buildConfiguration(processEnv, options, serverInfo) {
     return { nodeEngineConfig, nodeEnvVars: envVars };
 }
 /**
- * Override module imports to use local files where possible.
+ * Override module imports to support protocol-based loading (npm:, https:) and local files.
  * @param executionDirectory The execution directory for resolving local module paths.
+ * @param envVars The environment variables containing extension configuration (optional, uses defaults if not provided).
  */
-function overrideModuleImport(executionDirectory) {
+function overrideModuleImport(executionDirectory, envVars) {
+    const maxSizeMb = Coerce.number(envVars?.extensionsMaxSizeMb) ?? 10;
+    const cacheDirectory = envVars?.extensionsCacheDirectory;
     ModuleHelper.overrideImport(async (moduleName) => {
         if (moduleCache[moduleName]) {
             return {
@@ -2122,58 +2429,80 @@ function overrideModuleImport(executionDirectory) {
                 useDefault: false
             };
         }
-        // If the module path for example when dynamically loading
-        // modules looks like a local file then we try to resolve
-        // using the local file system
-        const isLocal = ModuleHelper.isLocalModule(moduleName);
-        if (isLocal) {
-            // See if we can just resolve the filename locally
-            let localFilename = path.resolve(moduleName);
-            let exists = await fileExists(localFilename);
-            if (!exists) {
-                // Doesn't exist in the current directory, try the execution directory
-                localFilename = path.resolve(executionDirectory, moduleName);
-                exists = await fileExists(localFilename);
-            }
-            if (exists) {
-                // If the module exists then we can load it, otherwise
-                // we fallback to regular handling to see if that can import it
-                const module = await import(process.platform === "win32" ? `file://${localFilename}` : localFilename);
-                moduleCache[moduleName] = module;
-                return {
-                    module,
-                    useDefault: false
-                };
+        const parsed = parseModuleProtocol(moduleName);
+        let resolvedPath;
+        switch (parsed.protocol) {
+            case ModuleProtocol.Npm: {
+                const result = await handleNpmProtocol(parsed.identifier, executionDirectory, cacheDirectory);
+                resolvedPath = result.resolvedPath;
+                break;
             }
-        }
-        try {
-            // Try and load from node_modules manually
-            // This is needed for some environments where
-            // the module resolution doesn't work as expected
-            const npmRoot = execSync("npm root").toString().trim().replace(/\\/g, "/");
-            const packageJson = await loadJsonFile(path.resolve(npmRoot, moduleName, "package.json"));
-            const mainFile = packageJson?.module ?? packageJson?.main ?? "index.js";
-            const modulePath = path.resolve(npmRoot, moduleName, mainFile);
-            const exists = await fileExists(modulePath);
-            if (exists) {
-                const module = await import(process.platform === "win32" ? `file://${modulePath}` : modulePath);
-                moduleCache[moduleName] = module;
-                return {
-                    module,
-                    useDefault: false
-                };
+            case ModuleProtocol.Https: {
+                const result = await handleHttpsProtocol(parsed.identifier, executionDirectory, maxSizeMb, cacheDirectory, envVars?.extensionsCacheTtlHours, envVars?.extensionsForceRefresh);
+                resolvedPath = result.resolvedPath;
+                break;
+            }
+            case ModuleProtocol.Http: {
+                throw new GeneralError("node", "insecureProtocol", { protocol: ModuleProtocol.Http });
+            }
+            case ModuleProtocol.Local: {
+                let localFilename = path.resolve(moduleName);
+                let exists = await fileExists(localFilename);
+                if (!exists) {
+                    localFilename = path.resolve(executionDirectory, moduleName);
+                    exists = await fileExists(localFilename);
+                }
+                if (exists) {
+                    resolvedPath = localFilename;
+                }
+                break;
+            }
+            case ModuleProtocol.Default: {
+                try {
+                    const npmRoot = execSync("npm root").toString().trim().replace(/\\/g, "/");
+                    const packagePath = path.resolve(npmRoot, moduleName);
+                    const mainFile = await resolvePackageEntryPoint(packagePath, moduleName);
+                    const modulePath = path.resolve(packagePath, mainFile);
+                    const exists = await fileExists(modulePath);
+                    if (exists) {
+                        resolvedPath = modulePath;
+                        break;
+                    }
+                }
+                catch {
+                    // Continue to fallback resolution
+                }
+                // Fallback: resolve from npm protocol cache directory (installed via handleNpmProtocol)
+                try {
+                    const cacheNpmRoot = path.resolve(getExtensionsCacheDir(executionDirectory, ModuleProtocol.Npm, cacheDirectory), "node_modules");
+                    const packagePath = path.resolve(cacheNpmRoot, moduleName);
+                    const mainFile = await resolvePackageEntryPoint(packagePath, moduleName);
+                    const modulePath = path.resolve(packagePath, mainFile);
+                    const exists = await fileExists(modulePath);
+                    if (exists) {
+                        resolvedPath = modulePath;
+                    }
+                }
+                catch {
+                    // No cached resolution either; fall through
+                }
+                break;
             }
         }
-        catch {
-            // We just fallback to default handling if not possible
+        // Common module loading and caching logic
+        if (resolvedPath) {
+            const module = await import(createModuleImportUrl(resolvedPath));
+            moduleCache[moduleName] = module;
+            return {
+                module,
+                useDefault: false
+            };
         }
-        // We don't appear to be able to manually resolve this module
-        // So we let the default handling take care of it
-        // This will allow built-in modules and regular node_modules to load as normal
         return {
+            module: undefined,
             useDefault: true
         };
     });
 }
 
-export { ATTESTATION_VERIFICATION_METHOD_ID, AUTH_SIGNING_KEY_ID, BLOB_STORAGE_ENCRYPTION_KEY_ID, IMMUTABLE_PROOF_VERIFICATION_METHOD_ID, NodeFeatures, SYNCHRONISED_STORAGE_BLOB_STORAGE_ENCRYPTION_KEY_ID, VC_AUTHENTICATION_VERIFICATION_METHOD_ID, bootstrap, bootstrapAuth, bootstrapBlobEncryption, bootstrapImmutableProofMethod, bootstrapNodeIdentity, bootstrapNodeUser, bootstrapSynchronisedStorage, buildConfiguration, buildEngineConfiguration, buildEngineServerConfiguration, directoryExists, extensionsConfiguration, extensionsInitialiseEngine, extensionsInitialiseEngineServer, fileExists, getExecutionDirectory, getFeatures, getFiles, getSubFolders, initialiseLocales, loadJsonFile, loadTextFile, overrideModuleImport, run, shutdownExtensions, start };
+export { ATTESTATION_VERIFICATION_METHOD_ID, AUTH_SIGNING_KEY_ID, BLOB_STORAGE_ENCRYPTION_KEY_ID, IMMUTABLE_PROOF_VERIFICATION_METHOD_ID, ModuleProtocol, NodeFeatures, SYNCHRONISED_STORAGE_BLOB_STORAGE_ENCRYPTION_KEY_ID, VC_AUTHENTICATION_VERIFICATION_METHOD_ID, bootstrap, bootstrapAuth, bootstrapBlobEncryption, bootstrapImmutableProofMethod, bootstrapNodeIdentity, bootstrapNodeUser, bootstrapSynchronisedStorage, buildConfiguration, buildEngineConfiguration, buildEngineServerConfiguration, createModuleImportUrl, directoryExists, extensionsConfiguration, extensionsInitialiseEngine, extensionsInitialiseEngineServer, fileExists, getExecutionDirectory, getExtensionsCacheDir, getFeatures, getFiles, getSubFolders, handleHttpsProtocol, handleNpmProtocol, hashUrl, initialiseLocales, isCacheExpired, loadJsonFile, loadTextFile, overrideModuleImport, parseModuleProtocol, resolvePackageEntryPoint, run, shutdownExtensions, start };

package/dist/types/index.d.ts

@@ -3,11 +3,15 @@ export * from "./builders/engineEnvBuilder";
 export * from "./builders/engineServerEnvBuilder";
 export * from "./builders/extensionsBuilder";
 export * from "./defaults";
+export * from "./models/ICacheMetadata";
 export * from "./models/IEngineEnvironmentVariables";
 export * from "./models/IEngineServerEnvironmentVariables";
+export * from "./models/IModuleProtocol";
 export * from "./models/INodeEngineConfig";
 export * from "./models/INodeEnvironmentVariables";
 export * from "./models/INodeOptions";
+export * from "./models/IProtocolHandlerResult";
+export * from "./models/moduleProtocol";
 export * from "./models/nodeExtensionMethods";
 export * from "./models/nodeFeatures";
 export * from "./node";

package/dist/types/models/ICacheMetadata.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Metadata for cached HTTPS extensions.
+ */
+export interface ICacheMetadata {
+    /**
+     * Timestamp when the file was downloaded.
+     */
+    downloadedAt: number;
+    /**
+     * Original URL of the cached file.
+     */
+    url: string;
+    /**
+     * Size of the cached file in bytes.
+     */
+    size: number;
+}

package/dist/types/models/IModuleProtocol.d.ts

@@ -0,0 +1,18 @@
+import type { ModuleProtocol } from "./moduleProtocol";
+/**
+ * The parsed module protocol information.
+ */
+export interface IModuleProtocol {
+    /**
+     * The protocol type.
+     */
+    protocol: ModuleProtocol;
+    /**
+     * The identifier after the protocol (or the original if no protocol).
+     */
+    identifier: string;
+    /**
+     * The original module string.
+     */
+    original: string;
+}

package/dist/types/models/INodeEnvironmentVariables.d.ts

@@ -25,4 +25,29 @@ export interface INodeEnvironmentVariables extends IEngineServerEnvironmentVaria
      * If the node-user feature is enabled, this will be the password of the user, if empty it will be randomly generated.
      */
     password?: string;
+    /**
+     * Maximum size in MB for HTTPS extensions downloads.
+     * @default 10
+     */
+    extensionsMaxSizeMb?: number;
+    /**
+     * Whether to clear the extensions cache on startup.
+     * @default false
+     */
+    extensionsClearCache?: boolean;
+    /**
+     * Custom directory for extensions cache storage.
+     * @default ".tmp"
+     */
+    extensionsCacheDirectory?: string;
+    /**
+     * TTL in hours for HTTPS extensions cache.
+     * @default 24
+     */
+    extensionsCacheTtlHours?: number;
+    /**
+     * Force refresh of all cached extensions.
+     * @default false
+     */
+    extensionsForceRefresh?: boolean;
 }

package/dist/types/models/IProtocolHandlerResult.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The result from a protocol handler.
+ */
+export interface IProtocolHandlerResult {
+    /**
+     * The resolved path to the module file.
+     */
+    resolvedPath: string;
+    /**
+     * Whether the module was cached.
+     */
+    cached: boolean;
+}

package/dist/types/models/moduleProtocol.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The protocol types for modules.
+ */
+export declare const ModuleProtocol: {
+    /**
+     * Local module (starts with . or / or file://).
+     */
+    readonly Local: "local";
+    /**
+     * NPM package (starts with npm:).
+     */
+    readonly Npm: "npm";
+    /**
+     * HTTPS URL (starts with https://).
+     */
+    readonly Https: "https";
+    /**
+     * HTTP URL (starts with http://).
+     */
+    readonly Http: "http";
+    /**
+     * Default/standard module resolution.
+     */
+    readonly Default: "default";
+};
+/**
+ * The protocol type for a module.
+ */
+export type ModuleProtocol = (typeof ModuleProtocol)[keyof typeof ModuleProtocol];

package/dist/types/node.d.ts

@@ -25,7 +25,8 @@ export declare function buildConfiguration(processEnv: {
     nodeEngineConfig: INodeEngineConfig;
 }>;
 /**
- * Override module imports to use local files where possible.
+ * Override module imports to support protocol-based loading (npm:, https:) and local files.
  * @param executionDirectory The execution directory for resolving local module paths.
+ * @param envVars The environment variables containing extension configuration (optional, uses defaults if not provided).
  */
-export declare function overrideModuleImport(executionDirectory: string): void;
+export declare function overrideModuleImport(executionDirectory: string, envVars?: INodeEnvironmentVariables): void;