@twin.org/node-core 0.0.2-next.9 → 0.0.3-next.10

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

@@ -6,6 +6,10 @@ export interface IEngineEnvironmentVariables {
      * Start the engine in debug mode.
      */
     debug?: string;
+    /**
+     * Start the engine in silent mode.
+     */
+    silent?: string;
     /**
      * The root directory for storing items like state file.
      */
@@ -14,6 +18,14 @@ export interface IEngineEnvironmentVariables {
      * The name of the state file.
      */
     stateFilename?: string;
+    /**
+     * Does the node have a unique ID, defaults to true.
+     */
+    nodeIdentityEnabled?: string;
+    /**
+     * Is multi-tenant support enabled, defaults to false.
+     */
+    tenantEnabled?: string;
     /**
      * The type of the entity storage to create, comma separate for more than one connector.
      * values: file, memory, aws-dynamodb, azure-cosmosdb, gcp-firestoredb, scylladb, mysql, mongodb, postgresql
@@ -27,6 +39,10 @@ export interface IEngineEnvironmentVariables {
      * A prefix for all the table in entity-storage, can be empty.
      */
     entityStorageTablePrefix?: string;
+    /**
+     * AWS DynamoDB auth mode, either credentials or pod.
+     */
+    awsDynamodbAuthMode?: string;
     /**
      * AWS Dynamo DB access key id.
      */
@@ -43,6 +59,10 @@ export interface IEngineEnvironmentVariables {
      * AWS Dynamo DB secret access key.
      */
     awsDynamodbSecretAccessKey?: string;
+    /**
+     * AWS Dynamo DB connection timeout.
+     */
+    awsDynamodbConnectionTimeoutMs?: string;
     /**
      * Azure Cosmos DB key.
      */
@@ -184,35 +204,34 @@ export interface IEngineEnvironmentVariables {
      * The id of the encryption key for the blob storage.
      */
     blobStorageEncryptionKeyId?: string;
-    /**
-     * A symmetric encryption key for the blob storage, should be ChaCha20Poly1305 in base64 format.
-     * If encryption is enabled but a key is not provided one will be generated.
-     */
-    blobStorageSymmetricEncryptionKey?: string;
     /**
      * A prefix for all the blobs in blob-storage, can be empty.
      */
     blobStoragePrefix?: string;
     /**
-     * AWS S3 access key id.
+     * AWS S3 region.
      */
-    awsS3AccessKeyId?: string;
+    awsS3Region?: string;
     /**
      * AWS S3 bucket name.
      */
     awsS3BucketName?: string;
     /**
-     * AWS S3 endpoint.
+     * AWS S3 auth mode, either credentials or pod, defaults to credentials.
      */
-    awsS3Endpoint?: string;
+    awsS3AuthMode?: string;
     /**
-     * AWS S3 region.
+     * AWS S3 access key id.
      */
-    awsS3Region?: string;
+    awsS3AccessKeyId?: string;
     /**
      * AWS S3 secret access key.
      */
     awsS3SecretAccessKey?: string;
+    /**
+     * AWS S3 endpoint.
+     */
+    awsS3Endpoint?: string;
     /**
      * Azure Storage account key.
      */
@@ -258,13 +277,9 @@ export interface IEngineEnvironmentVariables {
      */
     hashicorpVaultEndpoint?: string;
     /**
-     * The type of background task connector, can be a comma separated list: console, entity-storage.
+     * The type of logging task connector, can be a comma separated list: console, entity-storage.
      */
     loggingConnector?: string;
-    /**
-     * The type of background task connector: entity-storage.
-     */
-    backgroundTaskConnector?: string;
     /**
      * The type of event bus connector: local.
      */
@@ -274,25 +289,45 @@ export interface IEngineEnvironmentVariables {
      */
     eventBusComponent?: string;
     /**
-     * The type of messaging email connector: entity-storage, aws.
+     * Are the messaging components enabled, defaults to false.
      */
-    messagingEmailConnector?: string;
+    messagingEnabled?: string;
     /**
-     * The type of messaging sms connector: entity-storage, aws.
+     * AWS SES region.
      */
-    messagingSmsConnector?: string;
+    awsSesRegion?: string;
     /**
-     * The type of messaging push notification connector: entity-storage, aws.
+     * AWS SES auth mode, either credentials or pod, defaults to credentials.
      */
-    messagingPushNotificationConnector?: string;
+    awsSesAuthMode?: string;
+    /**
+     * AWS SES secret access key.
+     */
+    awsSesSecretAccessKey?: string;
+    /**
+     * AWS SES access key id.
+     */
+    awsSesAccessKeyId?: string;
+    /**
+     * AWS SES endpoint.
+     */
+    awsSesEndpoint?: string;
     /**
      * The applications for the push notifications JSON stringified array of IAwsApplicationSettings.
      */
     awsMessagingPushNotificationApplications?: string;
     /**
-     * The type of messaging component: service.
+     * The type of messaging email connector: entity-storage, aws.
+     */
+    messagingEmailConnector?: string;
+    /**
+     * The type of messaging sms connector: entity-storage, aws.
      */
-    messagingComponent?: string;
+    messagingSmsConnector?: string;
+    /**
+     * The type of messaging push notification connector: entity-storage, aws.
+     */
+    messagingPushNotificationConnector?: string;
     /**
      * The type of telemetry connector: entity-storage.
      */
@@ -313,6 +348,10 @@ export interface IEngineEnvironmentVariables {
      * The type of identity connector: entity-storage, iota.
      */
     identityConnector?: string;
+    /**
+     * The index of the wallet address to use, defaults to 0.
+     */
+    identityWalletAddressIndex?: string;
     /**
      * The type of identity resolver connector: entity-storage, iota.
      */
@@ -369,6 +408,10 @@ export interface IEngineEnvironmentVariables {
      * The identity verification method id to use with attestation.
      */
     attestationVerificationMethodId?: string;
+    /**
+     * Is the data processing enabled, defaults to false.
+     */
+    dataProcessingEnabled?: string;
     /**
      * The type of the default data converters, can be a comma separated list: json, xml.
      */
@@ -377,6 +420,18 @@ export interface IEngineEnvironmentVariables {
      * The type of the default data extractor, can be a comma separated list: json-path.
      */
     dataExtractorConnectors?: string;
+    /**
+     * Is the auditable item graph enabled, defaults to false.
+     */
+    auditableItemGraphEnabled?: string;
+    /**
+     * Is the auditable item stream enabled, defaults to false.
+     */
+    auditableItemStreamEnabled?: string;
+    /**
+     * Is the document management enabled, defaults to false.
+     */
+    documentManagementEnabled?: string;
     /**
      * Is the synchronised storage enabled, defaults to false.
      */
@@ -387,14 +442,9 @@ export interface IEngineEnvironmentVariables {
     synchronisedStorageTrustedUrl?: string;
     /**
      * The key for the smart contract which contains the verifiable storage pointer store for synchronised storage.
-     * This only required if using a custom verifiable storage item, otherwise it will default the the network name.
+     * This only required if using a custom verifiable storage item, otherwise it will default to the network name.
      */
     synchronisedStorageVerifiableStorageKeyId?: string;
-    /**
-     * The identity verification method id to use with synchronised storage for signing/verifying changesets.
-     * Defaults to synchronised-storage-assertion.
-     */
-    synchronisedStorageVerificationMethodId?: string;
     /**
      * The key from the vault which is used to encrypt the synchronised storage blobs.
      * Only required for trusted nodes, as regular nodes will request from the trusted nodes.
@@ -431,17 +481,66 @@ export interface IEngineEnvironmentVariables {
      */
     federatedCatalogueEnabled?: string;
     /**
-     * Federated catalog TTL for the cache.
+     * Federated catalog filters, command separated list of filters to add.
+     */
+    federatedCatalogueFilters?: string;
+    /**
+     * Is the trust management enabled, defaults to false.
+     */
+    trustEnabled?: string;
+    /**
+     * The trust generators to add to the factory, comma separated list.
      */
-    federatedCatalogueCacheTtlMs?: number;
+    trustGenerators?: string;
     /**
-     * Federated catalog clearing house approver list, stringified array of DIDs.
+     * The trust verifiers to add to the factory, comma separated list.
      */
-    federatedCatalogueClearingHouseApproverList?: string;
+    trustVerifiers?: string;
+    /**
+     * The verification method to use for trust identities.
+     * Defaults to node-authentication-assertion.
+     */
+    trustVerificationMethodId?: string;
     /**
      * Is the rights management enabled, defaults to false.
      */
     rightsManagementEnabled?: string;
+    /**
+     * What is the base callback url for rights management negotiations e.g. https://my-node/rights-management.
+     */
+    rightsManagementBaseCallbackUrl?: string;
+    /**
+     * The rights management policy information sources to add to the factory.
+     */
+    rightsManagementPolicyInformationSources?: string;
+    /**
+     * The rights management policy negotiators sources to add to the factory.
+     */
+    rightsManagementPolicyNegotiators?: string;
+    /**
+     * The rights management policy requesters to add to the factory.
+     */
+    rightsManagementPolicyRequesters?: string;
+    /**
+     * The rights management policy execution actions to add to the factory.
+     */
+    rightsManagementPolicyExecutionActions?: string;
+    /**
+     * The rights management policy enforcement processors to add to the factory.
+     */
+    rightsManagementPolicyEnforcementProcessors?: string;
+    /**
+     * The rights management policy arbiters to add to the factory.
+     */
+    rightsManagementPolicyArbiters?: string;
+    /**
+     * The rights management data access handlers to add to the factory.
+     */
+    rightsManagementDataAccessHandlers?: string;
+    /**
+     * Are background tasks enabled, defaults to false.
+     */
+    backgroundTasksEnabled?: string;
     /**
      * Is the task scheduler enabled, defaults to false.
      */
@@ -451,8 +550,26 @@ export interface IEngineEnvironmentVariables {
      */
     dataSpaceConnectorEnabled?: string;
     /**
-     * The application configuration for the data space connector.
-     * Use the @json: prefix to specify the path to the JSON configuration file.
+     * The length of time to retain the activity logs for in minutes, set to -1 to keep forever.
+     * @default 10
+     */
+    dataSpaceConnectorRetainActivityLogsFor?: string;
+    /**
+     * The interval for cleaning up the activity logs.
+     * @default 60
+     */
+    dataSpaceConnectorActivityLogsCleanUpInterval?: string;
+    /**
+     * Enable verifiable credential authentication for the API.
+     */
+    vcAuthenticationEnabled?: string;
+    /**
+     * Verifiable credential assertion for node to node communication.
+     * Defaults to node-authentication-assertion.
+     */
+    vcAuthenticationVerificationMethodId?: string;
+    /**
+     * A comma separated list of additional node extensions to load, the initialiseExtension method will be called for each extension.
      */
-    dataSpaceConnectorApps?: string;
+    extensions?: string;
 }

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

@@ -1,7 +1,8 @@
+import type { IEngineEnvironmentVariables } from "./IEngineEnvironmentVariables.js";
 /**
  * The engine server environment variables.
  */
-export interface IEngineServerEnvironmentVariables {
+export interface IEngineServerEnvironmentVariables extends IEngineEnvironmentVariables {
     /**
      * The port to serve the API from.
      */
@@ -43,7 +44,15 @@ export interface IEngineServerEnvironmentVariables {
      */
     mimeTypeProcessors?: string;
     /**
-     * Disable Node Identity route processors.
+     * Include the body in the REST logging output, useful for debugging.
      */
-    disableNodeIdentity?: string;
+    routeLoggingIncludeBody?: string;
+    /**
+     * Include the full base 64 output in the REST logging output, useful for debugging.
+     */
+    routeLoggingFullBase64?: string;
+    /**
+     * List of properties to obfuscate in the REST logging output, comma separated.
+     */
+    routeLoggingObfuscateProperties?: string;
 }

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

@@ -0,0 +1,18 @@
+import type { ModuleProtocol } from "./moduleProtocol.js";
+/**
+ * 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/INodeEngineConfig.d.ts

@@ -0,0 +1,6 @@
+import type { IEngineServerConfig } from "@twin.org/engine-server-types";
+/**
+ * The config for the node.
+ */
+export interface INodeEngineConfig extends IEngineServerConfig {
+}

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

@@ -0,0 +1,14 @@
+import type { IEngineState } from "@twin.org/engine-models";
+/**
+ * The engine state for the node.
+ */
+export interface INodeEngineState extends IEngineState {
+    /**
+     * The identity for the node.
+     */
+    nodeId?: string;
+    /**
+     * The tenant id for the node.
+     */
+    nodeTenantId?: string;
+}

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

@@ -1,29 +1,31 @@
-import type { IEngineEnvironmentVariables } from "./IEngineEnvironmentVariables";
-import type { IEngineServerEnvironmentVariables } from "./IEngineServerEnvironmentVariables";
+import type { IEngineServerEnvironmentVariables } from "./IEngineServerEnvironmentVariables.js";
 /**
  * The environment variables for the node.
  */
-export interface INodeEnvironmentVariables extends IEngineEnvironmentVariables, IEngineServerEnvironmentVariables {
+export interface INodeEnvironmentVariables extends IEngineServerEnvironmentVariables {
     /**
-     * The features that are enabled on the node.
-     * @default [NodeFeatures.NodeIdentity]
+     * Maximum size in MB for HTTPS extensions downloads.
+     * @default 10
      */
-    features?: string;
+    extensionsMaxSizeMb?: number;
     /**
-     * The identity of the node which, if empty and node-identity feature is enabled it will be generated.
+     * Whether to clear the extensions cache on startup.
+     * @default false
      */
-    identity?: string;
+    extensionsClearCache?: boolean;
     /**
-     * The mnemonic for the identity, if empty and node-identity feature is enabled it will be randomly generated.
+     * Custom directory for extensions cache storage.
+     * @default ".tmp"
      */
-    mnemonic?: string;
+    extensionsCacheDirectory?: string;
     /**
-     * If the node-user feature is enabled, this will be the name of the user.
-     * @default admin@node
+     * TTL in hours for HTTPS extensions cache.
+     * @default 24
      */
-    username?: string;
+    extensionsCacheTtlHours?: number;
     /**
-     * If the node-user feature is enabled, this will be the password of the user, if empty it will be randomly generated.
+     * Force refresh of all cached extensions.
+     * @default false
      */
-    password?: string;
+    extensionsForceRefresh?: boolean;
 }

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

@@ -1,6 +1,7 @@
 import type { IEngineCore, IEngineServer, IEngineStateStorage } from "@twin.org/engine-models";
 import type { IEngineConfig } from "@twin.org/engine-types";
-import type { INodeEnvironmentVariables } from "./INodeEnvironmentVariables";
+import type { INodeEngineConfig } from "./INodeEngineConfig.js";
+import type { INodeEnvironmentVariables } from "./INodeEnvironmentVariables.js";
 /**
  * The options when running the node.
  */
@@ -14,12 +15,18 @@ export interface INodeOptions {
      * The version of the server, defaults to the current version.
      */
     serverVersion?: string;
+    /**
+     * Additional environment variables to set.
+     */
+    envVars?: {
+        [key: string]: string;
+    };
     /**
      * Additional environment variable filenames to load, defaults to .env.
      */
     envFilenames?: string[];
     /**
-     * The prefix for environment variables, defaults to "TWIN_NODE_".
+     * The prefix for environment variables, defaults to "TWIN_".
      */
     envPrefix?: string;
     /**
@@ -56,7 +63,7 @@ export interface INodeOptions {
     /**
      * Method to extend the engine configuration with any additional custom configuration.
      */
-    extendConfig?: (config: IEngineConfig) => Promise<void>;
+    extendConfig?: (envVars: INodeEnvironmentVariables, config: INodeEngineConfig) => Promise<void>;
     /**
      * Method to extend the engine with any additional options.
      */
@@ -70,4 +77,8 @@ export interface INodeOptions {
      * If not provided, a default file-based state storage will be used.
      */
     stateStorage?: IEngineStateStorage;
+    /**
+     * Disables process.exit calls on fatal errors and throws instead.
+     */
+    disableProcessExitOnFailure?: 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/cliCommandParamType.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Type for the properties in commands.
+ */
+export type CliCommandParamType = string | number | 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/models/nodeExtensionMethods.d.ts

@@ -0,0 +1,27 @@
+import type { IEngineCore, IEngineServer } from "@twin.org/engine-models";
+import type { INodeEngineConfig } from "./INodeEngineConfig.js";
+import type { INodeEnvironmentVariables } from "./INodeEnvironmentVariables.js";
+/**
+ * The type for the initialise method of an extension module.
+ * @param envVars The environment variables for the node.
+ * @param nodeEngineConfig The node engine config.
+ */
+export type NodeExtensionInitialiseMethod = (envVars: INodeEnvironmentVariables, nodeEngineConfig: INodeEngineConfig) => Promise<void>;
+/**
+ * The type for the initialise engine method of an extension module.
+ * This is called when the engine has been constructed but not yet started.
+ * @param engineCore The engine core instance.
+ */
+export type NodeExtensionInitialiseEngineMethod = (engineCore: IEngineCore) => Promise<void>;
+/**
+ * The type for the initialise engine server method of an extension module.
+ * This is called when the engine server has been constructed but not yet started.
+ * @param engineCore The engine core instance.
+ * @param engineServer The engine server instance.
+ */
+export type NodeExtensionInitialiseEngineServerMethod = (engineCore: IEngineCore, engineServer: IEngineServer) => Promise<void>;
+/**
+ * The type for the shutdown method of an extension module.
+ * This is called when the engine is shutting down.
+ */
+export type NodeExtensionShutdownMethod = () => Promise<void>;

package/dist/types/node.d.ts

@@ -1,13 +1,22 @@
 import type { IServerInfo } from "@twin.org/api-models";
+import type { Engine } from "@twin.org/engine";
+import type { EngineServer } from "@twin.org/engine-server";
 import type { IEngineServerConfig } from "@twin.org/engine-server-types";
-import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables";
-import type { INodeOptions } from "./models/INodeOptions";
+import type { INodeEngineConfig } from "./models/INodeEngineConfig.js";
+import type { INodeEngineState } from "./models/INodeEngineState.js";
+import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables.js";
+import type { INodeOptions } from "./models/INodeOptions.js";
 /**
  * Run the TWIN Node server.
  * @param nodeOptions Optional configuration options for running the server.
- * @returns A promise that resolves when the server is started.
+ * @param args Optional command line arguments.
+ * @returns A promise that resolves when the server is started containing a shutdown method.
  */
-export declare function run(nodeOptions?: INodeOptions): Promise<void>;
+export declare function run(nodeOptions?: INodeOptions, args?: string[]): Promise<{
+    engine: Engine<IEngineServerConfig, INodeEngineState>;
+    server: EngineServer;
+    shutdown: () => Promise<void>;
+} | undefined>;
 /**
  * Build the configuration for the TWIN Node server.
  * @param processEnv The environment variables from the process.
@@ -22,10 +31,15 @@ export declare function buildConfiguration(processEnv: {
     nodeEnvVars: INodeEnvironmentVariables & {
         [id: string]: string | unknown;
     };
-    engineServerConfig: IEngineServerConfig;
+    nodeEngineConfig: INodeEngineConfig;
+    availableContextIdKeys: {
+        key: string;
+        requiredHandlerFeatures: string[];
+    }[];
 }>;
 /**
- * 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;

package/dist/types/start.d.ts

@@ -0,0 +1,25 @@
+import { Engine } from "@twin.org/engine";
+import { EngineServer } from "@twin.org/engine-server";
+import type { IEngineServerConfig } from "@twin.org/engine-server-types";
+import type { ICliCommand } from "./models/ICliCommand.js";
+import type { INodeEngineConfig } from "./models/INodeEngineConfig.js";
+import type { INodeEngineState } from "./models/INodeEngineState.js";
+import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables.js";
+import type { INodeOptions } from "./models/INodeOptions.js";
+/**
+ * Start the engine server.
+ * @param nodeOptions Optional run options for the engine server.
+ * @param nodeEngineConfig The configuration for the engine server.
+ * @param envVars The environment variables.
+ * @param cliCommand The constructed CLI command (optional).
+ * @param availableContextIdKeys The context ID keys available for operation.
+ * @returns The engine server.
+ */
+export declare function start(nodeOptions: INodeOptions | undefined, nodeEngineConfig: INodeEngineConfig, envVars: INodeEnvironmentVariables, cliCommand?: ICliCommand, availableContextIdKeys?: {
+    key: string;
+    requiredHandlerFeatures: string[];
+}[]): Promise<{
+    engine: Engine<IEngineServerConfig, INodeEngineState>;
+    server: EngineServer;
+    shutdown: () => Promise<void>;
+} | undefined>;