@twin.org/node-core 0.0.2-next.16 → 0.0.2-next.18

package/dist/esm/index.mjs

@@ -1,5 +1,5 @@
 import { PasswordHelper } from '@twin.org/api-auth-entity-storage-service';
-import { I18n, Is, Coerce, Converter, RandomHelper, Urn, GeneralError, ErrorHelper, EnvHelper } from '@twin.org/core';
+import { I18n, Is, Coerce, Converter, RandomHelper, Urn, GeneralError, EnvHelper } from '@twin.org/core';
 import { 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';
@@ -9,6 +9,7 @@ import { VaultConnectorFactory, VaultKeyType } from '@twin.org/vault-models';
 import { WalletConnectorFactory } from '@twin.org/wallet-models';
 import { readFile, stat, readdir } from 'node:fs/promises';
 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';
@@ -17,6 +18,15 @@ import { Engine } from '@twin.org/engine';
 import { FileStateStorage } from '@twin.org/engine-core';
 import { EngineCoreFactory } from '@twin.org/engine-models';
 
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+const ATTESTATION_VERIFICATION_METHOD_ID = "attestation-assertion";
+const IMMUTABLE_PROOF_VERIFICATION_METHOD_ID = "immutable-proof-assertion";
+const BLOB_STORAGE_ENCRYPTION_KEY_ID = "blob-encryption";
+const SYNCHRONISED_STORAGE_BLOB_STORAGE_ENCRYPTION_KEY_ID = "synchronised-storage-blob-encryption";
+const VC_AUTHENTICATION_VERIFICATION_METHOD_ID = "node-authentication-assertion";
+const AUTH_SIGNING_KEY_ID = "auth-signing";
+
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 /**
@@ -40,20 +50,19 @@ const NodeFeatures = {
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-/* eslint-disable no-console */
 /**
  * Initialise the locales for the application.
  * @param localesDirectory The directory containing the locales.
  */
 async function initialiseLocales(localesDirectory) {
     const localesFile = path.resolve(path.join(localesDirectory, "en.json"));
-    console.info("Locales File:", localesFile);
+    CLIDisplay.value("Locales File", localesFile);
     if (await fileExists(localesFile)) {
         const enLangContent = await readFile(localesFile, "utf8");
         I18n.addDictionary("en", JSON.parse(enLangContent));
     }
     else {
-        console.warn(`Locales file not found: ${localesFile}`);
+        CLIDisplay.error(`Locales file not found: ${localesFile}`);
     }
 }
 /**
@@ -188,10 +197,16 @@ async function bootstrap(engineCore, context, envVars) {
     await bootstrapNodeUser(engineCore, context, envVars, features);
     await bootstrapAuth(engineCore, context, envVars);
     await bootstrapBlobEncryption(engineCore, context, envVars);
-    await addVerificationMethod(engineCore, context, "attestation", envVars.attestationVerificationMethodId);
-    await addVerificationMethod(engineCore, context, "immutable proof", envVars.immutableProofVerificationMethodId);
+    const defaultAttestationConnectorType = engineCore.getRegisteredInstanceTypeOptional("attestationConnector");
+    if (!Is.empty(defaultAttestationConnectorType)) {
+        await addVerificationMethod(engineCore, context, "attestation", envVars.attestationVerificationMethodId ?? ATTESTATION_VERIFICATION_METHOD_ID);
+    }
+    const defaultImmutableProofComponentType = engineCore.getRegisteredInstanceTypeOptional("immutableProofComponent");
+    if (!Is.empty(defaultImmutableProofComponentType)) {
+        await addVerificationMethod(engineCore, context, "immutable proof", envVars.immutableProofVerificationMethodId ?? IMMUTABLE_PROOF_VERIFICATION_METHOD_ID);
+    }
     if (Coerce.boolean(envVars.vcAuthenticationEnabled) ?? false) {
-        await addVerificationMethod(engineCore, context, "verifiable credential authentication", envVars.vcAuthenticationVerificationMethodId);
+        await addVerificationMethod(engineCore, context, "verifiable credential authentication", envVars.vcAuthenticationVerificationMethodId ?? VC_AUTHENTICATION_VERIFICATION_METHOD_ID);
     }
     await bootstrapSynchronisedStorage(engineCore, context, envVars);
 }
@@ -467,7 +482,7 @@ async function bootstrapBlobEncryption(engineCore, context, envVars, features) {
         // Create a new key for encrypting blobs
         const defaultVaultConnectorType = engineCore.getRegisteredInstanceType("vaultConnector");
         const vaultConnector = VaultConnectorFactory.get(defaultVaultConnectorType);
-        const keyName = `${context.state.nodeIdentity}/${envVars.blobStorageEncryptionKeyId}`;
+        const keyName = `${context.state.nodeIdentity}/${envVars.blobStorageEncryptionKeyId ?? BLOB_STORAGE_ENCRYPTION_KEY_ID}`;
         let existingKey;
         try {
             existingKey = await vaultConnector.getKey(keyName);
@@ -507,7 +522,7 @@ async function bootstrapAuth(engineCore, context, envVars, features) {
         // Create a new JWT signing key and a user login for the node
         const defaultVaultConnectorType = engineCore.getRegisteredInstanceType("vaultConnector");
         const vaultConnector = VaultConnectorFactory.get(defaultVaultConnectorType);
-        const keyName = `${context.state.nodeIdentity}/${envVars.authSigningKeyId}`;
+        const keyName = `${context.state.nodeIdentity}/${envVars.authSigningKeyId ?? AUTH_SIGNING_KEY_ID}`;
         let existingKey;
         try {
             existingKey = await vaultConnector.getKey(keyName);
@@ -532,11 +547,11 @@ async function bootstrapAuth(engineCore, context, envVars, features) {
 async function bootstrapSynchronisedStorage(engineCore, context, envVars, features) {
     if (Coerce.boolean(envVars.synchronisedStorageEnabled) ?? false) {
         // If this is a trusted node we need to add the blob encryption key pair
-        if (Is.stringValue(envVars.synchronisedStorageBlobStorageEncryptionKeyId) &&
-            Is.stringBase64(envVars.synchronisedStorageBlobStorageKey)) {
+        if (Is.stringBase64(envVars.synchronisedStorageBlobStorageKey)) {
             const defaultVaultConnectorType = engineCore.getRegisteredInstanceType("vaultConnector");
             const vaultConnector = VaultConnectorFactory.get(defaultVaultConnectorType);
-            const keyName = envVars.synchronisedStorageBlobStorageEncryptionKeyId;
+            const keyName = envVars.synchronisedStorageBlobStorageEncryptionKeyId ??
+                SYNCHRONISED_STORAGE_BLOB_STORAGE_ENCRYPTION_KEY_ID;
             let existingKey;
             try {
                 existingKey = await vaultConnector.getKey(keyName);
@@ -604,12 +619,6 @@ async function buildEngineConfiguration(envVars) {
         envVars.storageFileRoot = path.resolve(envVars.storageFileRoot);
         envVars.stateFilename = path.join(envVars.storageFileRoot, envVars.stateFilename);
     }
-    envVars.attestationVerificationMethodId ??= "attestation-assertion";
-    envVars.immutableProofVerificationMethodId ??= "immutable-proof-assertion";
-    envVars.blobStorageEnableEncryption ??= "false";
-    envVars.blobStorageEncryptionKeyId ??= "blob-encryption";
-    envVars.synchronisedStorageBlobStorageEncryptionKeyId ??= "synchronised-storage-blob-encryption";
-    envVars.vcAuthenticationVerificationMethodId ??= "node-authentication-assertion";
     const coreConfig = {
         debug: Coerce.boolean(envVars.debug) ?? false,
         types: {}
@@ -672,9 +681,10 @@ async function configureEntityStorage(coreConfig, envVars) {
             options: {
                 config: {
                     region: envVars.awsDynamodbRegion ?? "",
-                    accessKeyId: envVars.awsDynamodbAccessKeyId ?? "",
-                    secretAccessKey: envVars.awsDynamodbSecretAccessKey ?? "",
-                    endpoint: envVars.awsDynamodbEndpoint ?? ""
+                    authMode: envVars.awsDynamodbAuthMode,
+                    accessKeyId: envVars.awsDynamodbAccessKeyId,
+                    secretAccessKey: envVars.awsDynamodbSecretAccessKey,
+                    endpoint: envVars.awsDynamodbEndpoint
                 },
                 tablePrefix: envVars.entityStorageTablePrefix
             }
@@ -831,9 +841,10 @@ async function configureBlobStorage(coreConfig, envVars) {
                 config: {
                     region: envVars.awsS3Region ?? "",
                     bucketName: envVars.awsS3BucketName ?? "",
-                    accessKeyId: envVars.awsS3AccessKeyId ?? "",
-                    secretAccessKey: envVars.awsS3SecretAccessKey ?? "",
-                    endpoint: envVars.awsS3Endpoint ?? ""
+                    authMode: envVars.awsS3AuthMode,
+                    accessKeyId: envVars.awsS3AccessKeyId,
+                    secretAccessKey: envVars.awsS3SecretAccessKey,
+                    endpoint: envVars.awsS3Endpoint
                 },
                 storagePrefix: envVars.blobStoragePrefix
             }
@@ -890,7 +901,7 @@ async function configureBlobStorage(coreConfig, envVars) {
             options: {
                 config: {
                     vaultKeyId: (envVars.blobStorageEnableEncryption ?? false)
-                        ? envVars.blobStorageEncryptionKeyId
+                        ? (envVars.blobStorageEncryptionKeyId ?? BLOB_STORAGE_ENCRYPTION_KEY_ID)
                         : undefined
                 }
             }
@@ -1030,10 +1041,11 @@ async function configureMessaging(coreConfig, envVars) {
                 type: MessagingEmailConnectorType.Aws,
                 options: {
                     config: {
-                        region: envVars.awsS3Region ?? "",
-                        accessKeyId: envVars.awsS3AccessKeyId ?? "",
-                        secretAccessKey: envVars.awsS3SecretAccessKey ?? "",
-                        endpoint: envVars.awsS3Endpoint ?? ""
+                        region: envVars.awsSesRegion ?? "",
+                        authMode: envVars.awsSesAuthMode,
+                        accessKeyId: envVars.awsSesAccessKeyId,
+                        secretAccessKey: envVars.awsSesSecretAccessKey,
+                        endpoint: envVars.awsSesEndpoint
                     }
                 }
             });
@@ -1048,10 +1060,11 @@ async function configureMessaging(coreConfig, envVars) {
                 type: MessagingSmsConnectorType.Aws,
                 options: {
                     config: {
-                        region: envVars.awsS3Region ?? "",
-                        accessKeyId: envVars.awsS3AccessKeyId ?? "",
-                        secretAccessKey: envVars.awsS3SecretAccessKey ?? "",
-                        endpoint: envVars.awsS3Endpoint ?? ""
+                        region: envVars.awsSesRegion ?? "",
+                        authMode: envVars.awsSesAuthMode,
+                        accessKeyId: envVars.awsSesAccessKeyId,
+                        secretAccessKey: envVars.awsSesSecretAccessKey,
+                        endpoint: envVars.awsSesEndpoint
                     }
                 }
             });
@@ -1068,8 +1081,9 @@ async function configureMessaging(coreConfig, envVars) {
                 options: {
                     config: {
                         region: envVars.awsSesRegion ?? "",
-                        accessKeyId: envVars.awsSesAccessKeyId ?? "",
-                        secretAccessKey: envVars.awsSesSecretAccessKey ?? "",
+                        authMode: envVars.awsSesAuthMode,
+                        accessKeyId: envVars.awsSesAccessKeyId,
+                        secretAccessKey: envVars.awsSesSecretAccessKey,
                         endpoint: envVars.awsSesEndpoint,
                         applicationsSettings: Is.json(envVars.awsMessagingPushNotificationApplications)
                             ? JSON.parse(envVars.awsMessagingPushNotificationApplications)
@@ -1199,7 +1213,7 @@ async function configureVerifiableStorage(coreConfig, envVars) {
             type: ImmutableProofComponentType.Service,
             options: {
                 config: {
-                    verificationMethodId: envVars.immutableProofVerificationMethodId
+                    verificationMethodId: envVars.immutableProofVerificationMethodId ?? IMMUTABLE_PROOF_VERIFICATION_METHOD_ID
                 }
             }
         });
@@ -1304,7 +1318,7 @@ async function configureAttestation(coreConfig, envVars) {
             type: AttestationComponentType.Service,
             options: {
                 config: {
-                    verificationMethodId: envVars.attestationVerificationMethodId
+                    verificationMethodId: envVars.attestationVerificationMethodId ?? ATTESTATION_VERIFICATION_METHOD_ID
                 }
             }
         });
@@ -1395,7 +1409,9 @@ async function configureVerifiableCredentialAuthentication(coreConfig, envVars)
         coreConfig.types.authenticationGeneratorComponent.push({
             type: AuthenticationGeneratorComponentType.VerifiableCredential,
             options: {
-                config: { verificationMethodId: envVars.vcAuthenticationVerificationMethodId ?? "" }
+                config: {
+                    verificationMethodId: envVars.vcAuthenticationVerificationMethodId ?? VC_AUTHENTICATION_VERIFICATION_METHOD_ID
+                }
             },
             features: ["verifiable-credential"]
         });
@@ -1523,7 +1539,8 @@ async function configureSynchronisedStorage(coreConfig, envVars) {
             options: {
                 config: {
                     verifiableStorageKeyId: verifiableStorageKeyId ?? "",
-                    blobStorageEncryptionKeyId: envVars.synchronisedStorageBlobStorageEncryptionKeyId,
+                    blobStorageEncryptionKeyId: envVars.synchronisedStorageBlobStorageEncryptionKeyId ??
+                        SYNCHRONISED_STORAGE_BLOB_STORAGE_ENCRYPTION_KEY_ID,
                     entityUpdateIntervalMinutes: Coerce.number(envVars.synchronisedStorageEntityUpdateIntervalMinutes),
                     consolidationIntervalMinutes: Coerce.number(envVars.synchronisedStorageConsolidationIntervalMinutes),
                     consolidationBatchSize: Coerce.number(envVars.synchronisedStorageConsolidationBatchSize),
@@ -1576,9 +1593,8 @@ async function configureDataSpaceConnector(coreConfig, envVars) {
             type: DataSpaceConnectorComponentType.Service,
             options: {
                 config: {
-                    dataSpaceConnectorAppDescriptors: Is.arrayValue(envVars.dataSpaceConnectorApps)
-                        ? envVars.dataSpaceConnectorApps
-                        : undefined
+                    retainActivityLogsFor: Coerce.number(envVars.dataSpaceConnectorRetainActivityLogsFor),
+                    activityLogsCleanUpInterval: Coerce.number(envVars.dataSpaceConnectorActivityLogsCleanUpInterval)
                 }
             }
         });
@@ -1624,10 +1640,9 @@ async function configureDlt(coreConfig, envVars) {
  * @param serverInfo The server information.
  * @param openApiSpecPath The path to the open api spec.
  * @param favIconPath The path to the favicon.
- * @returns The the config for the core and the server.
+ * @returns The config for the core and the server.
  */
 async function buildEngineServerConfiguration(envVars, coreEngineConfig, serverInfo, openApiSpecPath, favIconPath) {
-    envVars.authSigningKeyId ??= "auth-signing";
     const webServerOptions = {
         port: Coerce.number(envVars.port),
         host: Coerce.string(envVars.host),
@@ -1743,7 +1758,7 @@ async function buildEngineServerConfiguration(envVars, coreEngineConfig, serverI
             type: AuthenticationComponentType.EntityStorage,
             options: {
                 config: {
-                    signingKeyName: envVars.authSigningKeyId
+                    signingKeyName: envVars.authSigningKeyId ?? AUTH_SIGNING_KEY_ID
                 }
             }
         });
@@ -1751,7 +1766,7 @@ async function buildEngineServerConfiguration(envVars, coreEngineConfig, serverI
             type: RestRouteProcessorType.AuthHeader,
             options: {
                 config: {
-                    signingKeyName: envVars.authSigningKeyId
+                    signingKeyName: envVars.authSigningKeyId ?? AUTH_SIGNING_KEY_ID
                 }
             }
         });
@@ -1759,7 +1774,7 @@ async function buildEngineServerConfiguration(envVars, coreEngineConfig, serverI
             type: SocketRouteProcessorType.AuthHeader,
             options: {
                 config: {
-                    signingKeyName: envVars.authSigningKeyId
+                    signingKeyName: envVars.authSigningKeyId ?? AUTH_SIGNING_KEY_ID
                 }
             }
         });
@@ -1779,15 +1794,111 @@ async function buildEngineServerConfiguration(envVars, coreEngineConfig, serverI
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-/* eslint-disable no-console */
+/**
+ * Handles the configuration of the extensions.
+ * @param envVars The environment variables for the node.
+ * @param nodeEngineConfig The node engine config.
+ * @returns The config for the core and the server.
+ */
+async function extensionsConfiguration(envVars, nodeEngineConfig) {
+    if (Is.stringValue(envVars.extensions)) {
+        const extensions = envVars.extensions.split(",");
+        for (const extension of extensions) {
+            let initialiseConfigMethod;
+            try {
+                CLIDisplay.value(I18n.formatMessage("node.extensionLoading"), extension);
+                initialiseConfigMethod = await ModuleHelper.getModuleMethod(extension, "extensionInitialise");
+            }
+            catch (err) {
+                throw new GeneralError("node", "extensionLoadingError", { extension }, err);
+            }
+            if (Is.function(initialiseConfigMethod)) {
+                await initialiseConfigMethod(envVars, nodeEngineConfig);
+            }
+        }
+    }
+    return nodeEngineConfig;
+}
+/**
+ * Handles the initialisation of the extensions when the engine has been constructed.
+ * @param envVars The environment variables for the node.
+ * @param engineCore The engine core instance.
+ * @returns Nothing.
+ */
+async function extensionsInitialiseEngine(envVars, engineCore) {
+    if (Is.stringValue(envVars.extensions)) {
+        const extensions = envVars.extensions.split(",");
+        for (const extension of extensions) {
+            let initialiseEngineMethod;
+            try {
+                engineCore.logInfo(I18n.formatMessage("node.extensionInitialisingEngine", { extension }));
+                initialiseEngineMethod =
+                    await ModuleHelper.getModuleMethod(extension, "extensionInitialiseEngine");
+            }
+            catch { }
+            if (Is.function(initialiseEngineMethod)) {
+                await initialiseEngineMethod(engineCore);
+            }
+        }
+    }
+}
+/**
+ * Handles the initialisation of the extensions when the engine server has been constructed.
+ * @param envVars The environment variables for the node.
+ * @param engineCore The engine core instance.
+ * @param engineServer The engine server instance.
+ * @returns Nothing.
+ */
+async function extensionsInitialiseEngineServer(envVars, engineCore, engineServer) {
+    if (Is.stringValue(envVars.extensions)) {
+        const extensions = envVars.extensions.split(",");
+        for (const extension of extensions) {
+            let initialiseEngineServerMethod;
+            try {
+                engineCore.logInfo(I18n.formatMessage("node.extensionInitialisingEngineServer", { extension }));
+                initialiseEngineServerMethod =
+                    await ModuleHelper.getModuleMethod(extension, "extensionInitialiseEngineServer");
+            }
+            catch { }
+            if (Is.function(initialiseEngineServerMethod)) {
+                await initialiseEngineServerMethod(engineCore, engineServer);
+            }
+        }
+    }
+}
+/**
+ * Handles the shutdown of the extensions.
+ * @param envVars The environment variables for the node.
+ * @param engineCore The engine core instance.
+ * @returns Nothing.
+ */
+async function shutdownExtensions(envVars, engineCore) {
+    if (Is.stringValue(envVars.extensions)) {
+        const extensions = envVars.extensions.split(",");
+        for (const extension of extensions) {
+            let shutdownMethod;
+            try {
+                engineCore.logInfo(I18n.formatMessage("node.extensionShutdown", { extension }));
+                shutdownMethod = await ModuleHelper.getModuleMethod(extension, "extensionShutdown");
+            }
+            catch { }
+            if (Is.function(shutdownMethod)) {
+                await shutdownMethod();
+            }
+        }
+    }
+}
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
 /**
  * Start the engine server.
  * @param nodeOptions Optional run options for the engine server.
- * @param engineServerConfig The configuration for the engine server.
+ * @param nodeEngineConfig The configuration for the engine server.
  * @param envVars The environment variables.
  * @returns The engine server.
  */
-async function start(nodeOptions, engineServerConfig, envVars) {
+async function start(nodeOptions, nodeEngineConfig, envVars) {
     const entityStorageConnectorType = envVars.entityStorageConnectorType?.split(",") ?? [];
     const blobStorageConnectorType = envVars.blobStorageConnectorType?.split(",") ?? [];
     // If the blob storage or entity storage is configured with file connectors
@@ -1802,7 +1913,7 @@ async function start(nodeOptions, engineServerConfig, envVars) {
     }
     // Create the engine instance using file state storage unless one is configured in options
     const engine = new Engine({
-        config: engineServerConfig,
+        config: nodeEngineConfig,
         stateStorage: nodeOptions?.stateStorage ?? new FileStateStorage(envVars.stateFilename ?? ""),
         customBootstrap: async (core, engineContext) => bootstrap(core, engineContext, envVars)
     });
@@ -1810,14 +1921,16 @@ async function start(nodeOptions, engineServerConfig, envVars) {
     const server = new EngineServer({ engineCore: engine });
     // Extend the engine.
     if (Is.function(nodeOptions?.extendEngine)) {
-        console.info("Extending Engine");
+        engine.logInfo(I18n.formatMessage("node.extendingEngine"));
         await nodeOptions.extendEngine(engine);
     }
+    await extensionsInitialiseEngine(envVars, engine);
     // Extend the engine server.
     if (Is.function(nodeOptions?.extendEngineServer)) {
-        console.info("Extending Engine Server");
+        engine.logInfo(I18n.formatMessage("node.extendingEngineServer"));
         await nodeOptions?.extendEngineServer(server);
     }
+    await extensionsInitialiseEngineServer(envVars, engine, server);
     // Need to register the engine with the factory so that background tasks
     // can clone it to spawn new instances.
     EngineCoreFactory.register("engine", () => engine);
@@ -1826,14 +1939,17 @@ async function start(nodeOptions, engineServerConfig, envVars) {
     if (canContinue) {
         return {
             engine,
-            server
+            server,
+            shutdown: async () => {
+                await server.stop();
+                await shutdownExtensions(envVars, engine);
+            }
         };
     }
 }
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-/* eslint-disable no-console */
 /**
  * Run the TWIN Node server.
  * @param nodeOptions Optional configuration options for running the server.
@@ -1844,50 +1960,59 @@ async function run(nodeOptions) {
         nodeOptions ??= {};
         const serverInfo = {
             name: nodeOptions?.serverName ?? "TWIN Node Server",
-            version: nodeOptions?.serverVersion ?? "0.0.2-next.16" // x-release-please-version
+            version: nodeOptions?.serverVersion ?? "0.0.2-next.18" // x-release-please-version
         };
-        console.log(`\u001B[4m🌩️  ${serverInfo.name} v${serverInfo.version}\u001B[24m\n`);
+        CLIDisplay.header(serverInfo.name, serverInfo.version, "🌩️ ");
         if (!Is.stringValue(nodeOptions?.executionDirectory)) {
             nodeOptions.executionDirectory = getExecutionDirectory();
         }
-        console.info("Execution Directory:", nodeOptions.executionDirectory);
+        CLIDisplay.value("Execution Directory", nodeOptions.executionDirectory);
         nodeOptions.localesDirectory =
             nodeOptions?.localesDirectory ??
                 path.resolve(path.join(nodeOptions.executionDirectory, "dist", "locales"));
-        console.info("Locales Directory:", nodeOptions.localesDirectory);
+        CLIDisplay.value("Locales Directory", nodeOptions.localesDirectory);
         await initialiseLocales(nodeOptions.localesDirectory);
         if (Is.empty(nodeOptions?.openApiSpecFile)) {
             const specFile = path.resolve(path.join(nodeOptions.executionDirectory ?? "", "docs", "open-api", "spec.json"));
-            console.info("Default OpenAPI Spec File:", specFile);
+            CLIDisplay.value("Default OpenAPI Spec File", specFile);
             if (await fileExists(specFile)) {
                 nodeOptions ??= {};
                 nodeOptions.openApiSpecFile = specFile;
             }
         }
+        else {
+            CLIDisplay.value("OpenAPI Spec File", nodeOptions.openApiSpecFile);
+        }
         if (Is.empty(nodeOptions?.favIconFile)) {
             const favIconFile = path.resolve(path.join(nodeOptions.executionDirectory ?? "", "static", "favicon.png"));
-            console.info("Default Favicon File:", favIconFile);
+            CLIDisplay.value("Default Favicon File", favIconFile);
             if (await fileExists(favIconFile)) {
                 nodeOptions ??= {};
                 nodeOptions.favIconFile = favIconFile;
             }
         }
+        else {
+            CLIDisplay.value("Favicon File", nodeOptions.favIconFile);
+        }
         nodeOptions.envPrefix ??= "TWIN_NODE_";
-        console.info("Environment Prefix:", nodeOptions.envPrefix);
+        CLIDisplay.value("Environment Variable Prefix", nodeOptions.envPrefix);
         overrideModuleImport(nodeOptions.executionDirectory ?? "");
-        const { engineServerConfig, nodeEnvVars: envVars } = await buildConfiguration(process.env, nodeOptions, serverInfo);
-        console.info();
-        const startResult = await start(nodeOptions, engineServerConfig, envVars);
+        const { nodeEngineConfig, nodeEnvVars: envVars } = await buildConfiguration(
+        // This is the only location in the code base that should access process.env directly
+        // eslint-disable-next-line no-restricted-syntax
+        process.env, nodeOptions, serverInfo);
+        CLIDisplay.break();
+        const startResult = await start(nodeOptions, nodeEngineConfig, envVars);
         if (!Is.empty(startResult)) {
             for (const signal of ["SIGHUP", "SIGINT", "SIGTERM"]) {
                 process.on(signal, async () => {
-                    await startResult.server.stop();
+                    await startResult.shutdown();
                 });
             }
         }
     }
     catch (err) {
-        console.error(ErrorHelper.formatErrors(err).join("\n"));
+        CLIDisplay.error(err);
         // eslint-disable-next-line unicorn/no-process-exit
         process.exit(1);
     }
@@ -1904,7 +2029,7 @@ async function buildConfiguration(processEnv, options, serverInfo) {
     let defaultEnvOnly = false;
     if (Is.empty(options?.envFilenames)) {
         const envFile = path.resolve(path.join(options.executionDirectory ?? "", ".env"));
-        console.info("Default Environment File:", envFile);
+        CLIDisplay.value("Default Environment File", envFile);
         options ??= {};
         options.envFilenames = [envFile];
         defaultEnvOnly = true;
@@ -1932,18 +2057,18 @@ async function buildConfiguration(processEnv, options, serverInfo) {
             const filePath = envVars[key].slice(6).trim();
             const embeddedFile = path.resolve(path.join(options.executionDirectory ?? "", filePath));
             if (envVars[key].startsWith("@text:")) {
-                console.info(`Expanding Environment Variable: ${key} from text file: ${embeddedFile}`);
+                CLIDisplay.value(`Expanding Environment Variable: ${key} from text file`, embeddedFile);
                 envVars[key] = await loadTextFile(embeddedFile);
             }
             else if (envVars[key].startsWith("@json:")) {
-                console.info(`Expanding Environment Variable: ${key} from JSON file: ${embeddedFile}`);
+                CLIDisplay.value(`Expanding Environment Variable: ${key} from JSON file`, embeddedFile);
                 envVars[key] = await loadJsonFile(embeddedFile);
             }
         }
     }
     // Extend the environment variables with any additional custom configuration.
     if (Is.function(options?.extendEnvVars)) {
-        console.info("Extending Environment Variables");
+        CLIDisplay.task("Extending Environment Variables");
         await options.extendEnvVars(envVars);
     }
     // Build the engine configuration from the environment variables.
@@ -1952,22 +2077,23 @@ async function buildConfiguration(processEnv, options, serverInfo) {
     // Merge any custom configuration provided in the options.
     if (Is.arrayValue(options?.configFilenames)) {
         for (const configFile of options.configFilenames) {
-            console.info("Loading Configuration File:", configFile);
+            CLIDisplay.value("Loading Configuration File", configFile);
             const configFilePath = path.resolve(path.join(options.executionDirectory ?? "", configFile));
             const config = await loadJsonFile(configFilePath);
             Object.assign(engineServerConfig, config);
         }
     }
     if (Is.objectValue(options?.config)) {
-        console.info("Merging Custom Configuration");
+        CLIDisplay.task("Merging Custom Configuration");
         Object.assign(engineServerConfig, options.config);
     }
     // Merge any custom configuration provided in the options.
     if (Is.function(options?.extendConfig)) {
-        console.info("Extending Configuration");
-        await options.extendConfig(engineServerConfig);
+        CLIDisplay.task("Extending Configuration");
+        await options.extendConfig(envVars, engineServerConfig);
     }
-    return { engineServerConfig, nodeEnvVars: envVars };
+    const nodeEngineConfig = await extensionsConfiguration(envVars, engineServerConfig);
+    return { nodeEngineConfig, nodeEnvVars: envVars };
 }
 /**
  * Override module imports to use local files where possible.
@@ -2004,4 +2130,4 @@ function overrideModuleImport(executionDirectory) {
     });
 }
 
-export { NodeFeatures, bootstrap, bootstrapAuth, bootstrapBlobEncryption, bootstrapImmutableProofMethod, bootstrapNodeIdentity, bootstrapNodeUser, bootstrapSynchronisedStorage, buildConfiguration, buildEngineConfiguration, buildEngineServerConfiguration, directoryExists, fileExists, getExecutionDirectory, getFeatures, getFiles, getSubFolders, initialiseLocales, loadJsonFile, loadTextFile, overrideModuleImport, run, start };
+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 };

package/dist/types/builders/engineServerEnvBuilder.d.ts

@@ -9,6 +9,6 @@ import type { IEngineServerEnvironmentVariables } from "../models/IEngineServerE
  * @param serverInfo The server information.
  * @param openApiSpecPath The path to the open api spec.
  * @param favIconPath The path to the favicon.
- * @returns The the config for the core and the server.
+ * @returns The config for the core and the server.
  */
 export declare function buildEngineServerConfiguration(envVars: IEngineServerEnvironmentVariables, coreEngineConfig: IEngineCoreConfig, serverInfo: IServerInfo, openApiSpecPath?: string, favIconPath?: string): Promise<IEngineServerConfig>;

package/dist/types/builders/extensionsBuilder.d.ts

@@ -0,0 +1,32 @@
+import type { IEngineCore, IEngineServer } from "@twin.org/engine-models";
+import type { INodeEngineConfig } from "../models/INodeEngineConfig";
+import type { INodeEnvironmentVariables } from "../models/INodeEnvironmentVariables";
+/**
+ * Handles the configuration of the extensions.
+ * @param envVars The environment variables for the node.
+ * @param nodeEngineConfig The node engine config.
+ * @returns The config for the core and the server.
+ */
+export declare function extensionsConfiguration(envVars: INodeEnvironmentVariables, nodeEngineConfig: INodeEngineConfig): Promise<INodeEngineConfig>;
+/**
+ * Handles the initialisation of the extensions when the engine has been constructed.
+ * @param envVars The environment variables for the node.
+ * @param engineCore The engine core instance.
+ * @returns Nothing.
+ */
+export declare function extensionsInitialiseEngine(envVars: INodeEnvironmentVariables, engineCore: IEngineCore): Promise<void>;
+/**
+ * Handles the initialisation of the extensions when the engine server has been constructed.
+ * @param envVars The environment variables for the node.
+ * @param engineCore The engine core instance.
+ * @param engineServer The engine server instance.
+ * @returns Nothing.
+ */
+export declare function extensionsInitialiseEngineServer(envVars: INodeEnvironmentVariables, engineCore: IEngineCore, engineServer: IEngineServer): Promise<void>;
+/**
+ * Handles the shutdown of the extensions.
+ * @param envVars The environment variables for the node.
+ * @param engineCore The engine core instance.
+ * @returns Nothing.
+ */
+export declare function shutdownExtensions(envVars: INodeEnvironmentVariables, engineCore: IEngineCore): Promise<void>;

package/dist/types/defaults.d.ts

@@ -0,0 +1,6 @@
+export declare const ATTESTATION_VERIFICATION_METHOD_ID = "attestation-assertion";
+export declare const IMMUTABLE_PROOF_VERIFICATION_METHOD_ID = "immutable-proof-assertion";
+export declare const BLOB_STORAGE_ENCRYPTION_KEY_ID = "blob-encryption";
+export declare const SYNCHRONISED_STORAGE_BLOB_STORAGE_ENCRYPTION_KEY_ID = "synchronised-storage-blob-encryption";
+export declare const VC_AUTHENTICATION_VERIFICATION_METHOD_ID = "node-authentication-assertion";
+export declare const AUTH_SIGNING_KEY_ID = "auth-signing";

package/dist/types/index.d.ts

@@ -1,10 +1,14 @@
 export * from "./bootstrap";
 export * from "./builders/engineEnvBuilder";
 export * from "./builders/engineServerEnvBuilder";
+export * from "./builders/extensionsBuilder";
+export * from "./defaults";
 export * from "./models/IEngineEnvironmentVariables";
 export * from "./models/IEngineServerEnvironmentVariables";
+export * from "./models/INodeEngineConfig";
 export * from "./models/INodeEnvironmentVariables";
 export * from "./models/INodeOptions";
+export * from "./models/nodeExtensionMethods";
 export * from "./models/nodeFeatures";
 export * from "./node";
 export * from "./server";