@twin.org/node-core 0.0.1-next.10

package/dist/types/bootstrap.d.ts

@@ -0,0 +1,59 @@
+import type { IEngineCore, IEngineCoreContext, IEngineState } from "@twin.org/engine-models";
+import type { IEngineServerConfig } from "@twin.org/engine-server-types";
+import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables";
+import { NodeFeatures } from "./models/nodeFeatures";
+/**
+ * Bootstrap the application.
+ * @param engineCore The engine core for the node.
+ * @param context The context for the node.
+ * @param envVars The environment variables for the node.
+ */
+export declare function bootstrap(engineCore: IEngineCore, context: IEngineCoreContext<IEngineServerConfig, IEngineState>, envVars: INodeEnvironmentVariables): Promise<void>;
+/**
+ * Bootstrap the node creating any necessary resources.
+ * @param engineCore The engine core for the node.
+ * @param context The context for the node.
+ * @param envVars The environment variables for the node.
+ * @param features The features that are enabled on the node. The features that are enabled on the node.
+ */
+export declare function bootstrapNodeIdentity(engineCore: IEngineCore, context: IEngineCoreContext<IEngineServerConfig, IEngineState>, envVars: INodeEnvironmentVariables, features: NodeFeatures[]): Promise<void>;
+/**
+ * Bootstrap the user.
+ * @param engineCore The engine core for the node.
+ * @param context The context for the node.
+ * @param envVars The environment variables for the node.
+ * @param features The features that are enabled on the node.
+ */
+export declare function bootstrapNodeUser(engineCore: IEngineCore, context: IEngineCoreContext<IEngineServerConfig, IEngineState>, envVars: INodeEnvironmentVariables, features: NodeFeatures[]): Promise<void>;
+/**
+ * Bootstrap the attestation verification methods.
+ * @param engineCore The engine core for the node.
+ * @param context The context for the node.
+ * @param envVars The environment variables for the node.
+ * @param features The features that are enabled on the node.
+ */
+export declare function bootstrapAttestationMethod(engineCore: IEngineCore, context: IEngineCoreContext<IEngineServerConfig, IEngineState>, envVars: INodeEnvironmentVariables, features: NodeFeatures[]): Promise<void>;
+/**
+ * Bootstrap the immutable proof verification methods.
+ * @param engineCore The engine core for the node.
+ * @param context The context for the node.
+ * @param envVars The environment variables for the node.
+ * @param features The features that are enabled on the node.
+ */
+export declare function bootstrapImmutableProofMethod(engineCore: IEngineCore, context: IEngineCoreContext<IEngineServerConfig, IEngineState>, envVars: INodeEnvironmentVariables, features: NodeFeatures[]): Promise<void>;
+/**
+ * Bootstrap the keys for blob encryption.
+ * @param engineCore The engine core for the node.
+ * @param context The context for the node.
+ * @param envVars The environment variables for the node.
+ * @param features The features that are enabled on the node.
+ */
+export declare function bootstrapBlobEncryption(engineCore: IEngineCore, context: IEngineCoreContext<IEngineServerConfig, IEngineState>, envVars: INodeEnvironmentVariables, features: NodeFeatures[]): Promise<void>;
+/**
+ * Bootstrap the JWT signing key.
+ * @param engineCore The engine core for the node.
+ * @param context The context for the node.
+ * @param envVars The environment variables for the node.
+ * @param features The features that are enabled on the node.
+ */
+export declare function bootstrapAuth(engineCore: IEngineCore, context: IEngineCoreContext<IEngineServerConfig, IEngineState>, envVars: INodeEnvironmentVariables, features: NodeFeatures[]): Promise<void>;

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

@@ -0,0 +1,8 @@
+import { type IEngineConfig } from "@twin.org/engine-types";
+import type { IEngineEnvironmentVariables } from "../models/IEngineEnvironmentVariables";
+/**
+ * Build the engine core configuration from environment variables.
+ * @param envVars The environment variables.
+ * @returns The config for the core.
+ */
+export declare function buildEngineConfiguration(envVars: IEngineEnvironmentVariables): IEngineConfig;

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

@@ -0,0 +1,13 @@
+import type { IServerInfo } from "@twin.org/api-models";
+import type { IEngineCoreConfig } from "@twin.org/engine-models";
+import { type IEngineServerConfig } from "@twin.org/engine-server-types";
+import type { IEngineServerEnvironmentVariables } from "../models/IEngineServerEnvironmentVariables";
+/**
+ * Handles the configuration of the server.
+ * @param envVars The environment variables for the engine server.
+ * @param coreEngineConfig The core engine config.
+ * @param serverInfo The server information.
+ * @param openApiSpecPath The path to the open api spec.
+ * @returns The the config for the core and the server.
+ */
+export declare function buildEngineServerConfiguration(envVars: IEngineServerEnvironmentVariables, coreEngineConfig: IEngineCoreConfig, serverInfo: IServerInfo, openApiSpecPath?: string): IEngineServerConfig;

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./bootstrap";
+export * from "./builders/engineEnvBuilder";
+export * from "./models/IEngineEnvironmentVariables";
+export * from "./models/IEngineServerEnvironmentVariables";
+export * from "./models/INodeEnvironmentVariables";
+export * from "./models/INodeOptions";
+export * from "./models/nodeFeatures";
+export * from "./node";
+export * from "./server";
+export * from "./utils";

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

@@ -0,0 +1,389 @@
+/**
+ * The engine core environment variables.
+ */
+export interface IEngineEnvironmentVariables {
+    /**
+     * Start the engine in debug mode.
+     */
+    debug?: string;
+    /**
+     * The root directory for storing items like state file.
+     */
+    storageFileRoot?: string;
+    /**
+     * The name of the state file.
+     */
+    stateFilename?: string;
+    /**
+     * The type of the default entity storage: file, memory, aws-dynamodb, azure-cosmosdb, gcp-firestoredb, scylladb, mysql, mongodb, postgresql.
+     */
+    entityStorageConnectorType?: string;
+    /**
+     * A prefix for all the table in entity-storage, can be empty.
+     */
+    entityStorageTablePrefix?: string;
+    /**
+     * Enable the file entity storage connector.
+     */
+    entityFileEnable?: string;
+    /**
+     * Enable the memory entity storage connector.
+     */
+    entityMemoryEnable?: string;
+    /**
+     * AWS Dynamo DB access key id.
+     */
+    awsDynamodbAccessKeyId?: string;
+    /**
+     * AWS Dynamo DB Endpoint if running local instance.
+     */
+    awsDynamodbEndpoint?: string;
+    /**
+     * AWS Dynamo DB region.
+     */
+    awsDynamodbRegion?: string;
+    /**
+     * AWS Dynamo DB secret access key.
+     */
+    awsDynamodbSecretAccessKey?: string;
+    /**
+     * Azure Cosmos DB key.
+     */
+    azureCosmosdbKey?: string;
+    /**
+     * Azure Cosmos DB container id.
+     */
+    azureCosmosdbContainerId?: string;
+    /**
+     * Azure Cosmos DB database id.
+     */
+    azureCosmosdbDatabaseId?: string;
+    /**
+     * Azure Cosmos DB endpoint.
+     */
+    azureCosmosdbEndpoint?: string;
+    /**
+     * GCP Firestore collection name.
+     */
+    gcpFirestoreCollectionName?: string;
+    /**
+     * GCP Firestore credentials.
+     */
+    gcpFirestoreCredentials?: string;
+    /**
+     * GCP Firestore database id.
+     */
+    gcpFirestoreDatabaseId?: string;
+    /**
+     * GCP Firestore endpoint.
+     */
+    gcpFirestoreApiEndpoint?: string;
+    /**
+     * GCP Firestore project id.
+     */
+    gcpFirestoreProjectId?: string;
+    /**
+     * ScyllaDB hosts as comma separated string.
+     */
+    scylladbHosts?: string;
+    /**
+     * ScyllaDB keyspace.
+     */
+    scylladbKeyspace?: string;
+    /**
+     * ScyllaDB local data center.
+     */
+    scylladbLocalDataCenter?: string;
+    /**
+     * MySQL host.
+     */
+    mySqlHost?: string;
+    /**
+     * MySQL port.
+     */
+    mySqlPort?: number;
+    /**
+     * MySQL username.
+     */
+    mySqlUser?: string;
+    /**
+     * MySQL password.
+     */
+    mySqlPassword?: string;
+    /**
+     * MySQL Database.
+     */
+    mySqlDatabase?: string;
+    /**
+     * MongoDB host.
+     */
+    mongoDbHost?: string;
+    /**
+     * MongoDB port.
+     */
+    mongoDbPort?: number;
+    /**
+     * MongoDB username.
+     */
+    mongoDbUser?: string;
+    /**
+     * MongoDB password.
+     */
+    mongoDbPassword?: string;
+    /**
+     * MongoDB Database.
+     */
+    mongoDbDatabase?: string;
+    /**
+     * PostgreSQl host.
+     */
+    postgreSqlHost?: string;
+    /**
+     * PostgreSQl port.
+     */
+    postgreSqlPort?: number;
+    /**
+     * PostgreSQl username.
+     */
+    postgreSqlUser?: string;
+    /**
+     * PostgreSQl password.
+     */
+    postgreSqlPassword?: string;
+    /**
+     * PostgreSQl Database.
+     */
+    postgreSqlDatabase?: string;
+    /**
+     * The security token for accessing IPFS API.
+     */
+    ipfsBearerToken?: string;
+    /**
+     * The url for accessing IPFS API.
+     */
+    ipfsApiUrl?: string;
+    /**
+     * The type of the default blob storage: memory, file, ipfs, aws-s3, azure-storage, gcp-storage.
+     */
+    blobStorageConnectorType?: string;
+    /**
+     * Enable encryption for the blob storage.
+     */
+    blobStorageEnableEncryption?: string;
+    /**
+     * The encryption key for the blob storage.
+     */
+    blobStorageEncryptionKey?: string;
+    /**
+     * A prefix for all the blobs in blob-storage, can be empty.
+     */
+    blobStoragePrefix?: string;
+    /**
+     * Enable the file blob storage connector.
+     */
+    blobFileEnable?: string;
+    /**
+     * Enable the memory blob storage connector.
+     */
+    blobMemoryEnable?: string;
+    /**
+     * AWS S3 access key id.
+     */
+    awsS3AccessKeyId?: string;
+    /**
+     * AWS S3 bucket name.
+     */
+    awsS3BucketName?: string;
+    /**
+     * AWS S3 endpoint.
+     */
+    awsS3Endpoint?: string;
+    /**
+     * AWS S3 region.
+     */
+    awsS3Region?: string;
+    /**
+     * AWS S3 secret access key.
+     */
+    awsS3SecretAccessKey?: string;
+    /**
+     * Azure Storage account key.
+     */
+    azureStorageAccountKey?: string;
+    /**
+     * Azure Storage account name.
+     */
+    azureStorageAccountName?: string;
+    /**
+     * Azure Storage container.
+     */
+    azureStorageContainerName?: string;
+    /**
+     * Azure Storage endpoint.
+     */
+    azureStorageEndpoint?: string;
+    /**
+     * GCP Storage bucket.
+     */
+    gcpStorageBucketName?: string;
+    /**
+     * GCP Storage credentials.
+     */
+    gcpStorageCredentials?: string;
+    /**
+     * GCP Storage endpoint.
+     */
+    gcpStorageEndpoint?: string;
+    /**
+     * GCP Storage project id.
+     */
+    gcpStorageProjectId?: string;
+    /**
+     * The type of the default vault connector: entity-storage, hashicorp.
+     */
+    vaultConnector?: string;
+    /**
+     * Hashicorp Vault token.
+     */
+    hashicorpVaultToken?: string;
+    /**
+     * Hashicorp Vault endpoint.
+     */
+    hashicorpVaultEndpoint?: string;
+    /**
+     * The type of background 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.
+     */
+    eventBusConnector?: string;
+    /**
+     * The type of event bus component: service.
+     */
+    eventBusComponent?: string;
+    /**
+     * The type of messaging email connector: entity-storage, aws.
+     */
+    messagingEmailConnector?: string;
+    /**
+     * The type of messaging sms connector: entity-storage, aws.
+     */
+    messagingSmsConnector?: string;
+    /**
+     * The type of messaging push notification connector: entity-storage, aws.
+     */
+    messagingPushNotificationConnector?: string;
+    /**
+     * The applications for the push notifications JSON stringified array of IAwsApplicationSettings.
+     */
+    awsMessagingPushNotificationApplications?: string;
+    /**
+     * The type of messaging component: service.
+     */
+    messagingComponent?: string;
+    /**
+     * The type of telemetry connector: entity-storage.
+     */
+    telemetryConnector?: string;
+    /**
+     * The type of faucet connector: entity-storage, iota.
+     */
+    faucetConnector?: string;
+    /**
+     * The type of wallet connector: entity-storage, iota.
+     */
+    walletConnector?: string;
+    /**
+     * The type of NFT connector: entity-storage, iota.
+     */
+    nftConnector?: string;
+    /**
+     * The type of identity connector: entity-storage, iota.
+     */
+    identityConnector?: string;
+    /**
+     * The type of identity resolver connector: entity-storage, iota.
+     */
+    identityResolverConnector?: string;
+    /**
+     * The type of verifiable storage connector: entity-storage, iota.
+     */
+    verifiableStorageConnector?: string;
+    /**
+     * IOTA Faucet Endpoint.
+     */
+    iotaFaucetEndpoint?: string;
+    /**
+     * IOTA Node Endpoint.
+     */
+    iotaNodeEndpoint?: string;
+    /**
+     * IOTA network.
+     */
+    iotaNetwork?: string;
+    /**
+     * IOTA coin type.
+     */
+    iotaCoinType?: string;
+    /**
+     * IOTA Explorer Endpoint.
+     */
+    iotaExplorerEndpoint?: string;
+    /**
+     * IOTA Gas Station Endpoint.
+     */
+    iotaGasStationEndpoint?: string;
+    /**
+     * IOTA Gas Station Authentication Token.
+     */
+    iotaGasStationAuthToken?: string;
+    /**
+     * Universal Resolver Endpoint.
+     */
+    universalResolverEndpoint?: string;
+    /**
+     * The type of identity profile connector: entity-storage.
+     */
+    identityProfileConnector?: string;
+    /**
+     * The identity verification method id to use with immutable proofs.
+     */
+    immutableProofVerificationMethodId?: string;
+    /**
+     * The type of attestation connector: entity-storage, iota.
+     */
+    attestationConnector?: string;
+    /**
+     * The identity verification method id to use with attestation.
+     */
+    attestationVerificationMethodId?: string;
+    /**
+     * The type of the default data converters, can be a comma separated list: json, xml.
+     */
+    dataConverterConnectors?: string;
+    /**
+     * The type of the default data extractor, can be a comma separated list: json-path.
+     */
+    dataExtractorConnectors?: string;
+    /**
+     * Federated catalog TTL for the cache.
+     */
+    federatedCatalogueCacheTtlMs?: number;
+    /**
+     * Federated catalog clearing house approver list, stringified array of DIDs.
+     */
+    federatedCatalogueClearingHouseApproverList?: string;
+    /**
+     * Is the rights management enabled, defaults to false.
+     */
+    rightsManagementEnabled?: string;
+    /**
+     * Is the task scheduler enabled, defaults to true.
+     */
+    taskSchedulerEnabled?: string;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * The engine server environment variables.
+ */
+export interface IEngineServerEnvironmentVariables {
+    /**
+     * The port to serve the API from.
+     */
+    port?: string;
+    /**
+     * The host to serve the API from.
+     */
+    host?: string;
+    /**
+     * The CORS origins to allow, defaults to *.
+     */
+    corsOrigins?: string;
+    /**
+     * The CORS methods to allow, defaults to GET, POST, PUT, DELETE, OPTIONS.
+     */
+    httpMethods?: string;
+    /**
+     * The CORS headers to allow.
+     */
+    httpAllowedHeaders?: string;
+    /**
+     * The CORS headers to expose.
+     */
+    httpExposedHeaders?: string;
+    /**
+     * The type of auth processor to use on the API: entity-storage.
+     */
+    authProcessorType?: string;
+    /**
+     * The id of the key in the vault to use for signing in auth operations.
+     */
+    authSigningKeyId?: string;
+    /**
+     * Additional MIME type processors to include, comma separated.
+     */
+    mimeTypeProcessors?: string;
+    /**
+     * Disable Node Identity route processors.
+     */
+    disableNodeIdentity?: string;
+}

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

@@ -0,0 +1,29 @@
+import type { IEngineEnvironmentVariables } from "./IEngineEnvironmentVariables";
+import type { IEngineServerEnvironmentVariables } from "./IEngineServerEnvironmentVariables";
+/**
+ * The environment variables for the node.
+ */
+export interface INodeEnvironmentVariables extends IEngineEnvironmentVariables, IEngineServerEnvironmentVariables {
+    /**
+     * The features that are enabled on the node.
+     * @default [NodeFeatures.NodeIdentity]
+     */
+    features?: string;
+    /**
+     * The identity of the node which, if empty and node-identity feature is enabled it will be generated.
+     */
+    identity?: string;
+    /**
+     * The mnemonic for the identity, if empty and node-identity feature is enabled it will be randomly generated.
+     */
+    mnemonic?: string;
+    /**
+     * If the node-user feature is enabled, this will be the name of the user.
+     * @default admin@node
+     */
+    username?: string;
+    /**
+     * If the node-user feature is enabled, this will be the password of the user, if empty it will be randomly generated.
+     */
+    password?: string;
+}

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

@@ -0,0 +1,69 @@
+import type { IEngineCore, IEngineServer, IEngineStateStorage } from "@twin.org/engine-models";
+import type { IEngineConfig } from "@twin.org/engine-types";
+import type { INodeEnvironmentVariables } from "./INodeEnvironmentVariables";
+/**
+ * The options when running the node.
+ */
+export interface INodeOptions {
+    /**
+     * The name of the server, defaults to "TWIN Node Server".
+     * @default "TWIN Node Server"
+     */
+    serverName?: string;
+    /**
+     * The version of the server, defaults to the current version.
+     */
+    serverVersion?: string;
+    /**
+     * Additional environment variable filenames to load, defaults to .env.
+     */
+    envFilenames?: string[];
+    /**
+     * The prefix for environment variables, defaults to "TWIN_NODE_".
+     */
+    envPrefix?: string;
+    /**
+     * A list of JSON files to load as configuration files.
+     * The files will be loaded in the order they are provided, and the last one will
+     * override any previous values.
+     */
+    configFilenames?: string[];
+    /**
+     * Provides the ability to have some initial custom configuration for the engine.
+     * This will be merged with any configuration loaded from the environment variables.
+     */
+    config?: IEngineConfig;
+    /**
+     * The directory to override the execution location, defaults to process directory.
+     */
+    executionDirectory?: string;
+    /**
+     * The directory to override the locales directory, defaults to the locales directory.
+     */
+    localesDirectory?: string;
+    /**
+     * The path to the OpenAPI spec file, defaults to docs/open-api/spec.json.
+     */
+    openApiSpecFile?: string;
+    /**
+     * Method to extend the engine environment variables with any additional custom configuration.
+     */
+    extendEnvVars?: (envVars: INodeEnvironmentVariables) => Promise<void>;
+    /**
+     * Method to extend the engine configuration with any additional custom configuration.
+     */
+    extendConfig?: (config: IEngineConfig) => Promise<void>;
+    /**
+     * Method to extend the engine with any additional options.
+     */
+    extendEngine?: (engine: IEngineCore) => Promise<void>;
+    /**
+     * Method to extend the engine server with any additional options.
+     */
+    extendEngineServer?: (engineServer: IEngineServer) => Promise<void>;
+    /**
+     * The state storage to use for the engine.
+     * If not provided, a default file-based state storage will be used.
+     */
+    stateStorage?: IEngineStateStorage;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * The features that can be enabled on the node.
+ */
+export declare const NodeFeatures: {
+    /**
+     * NodeIdentity - generates an identity for the node if not provided in config.
+     */
+    readonly NodeIdentity: "node-identity";
+    /**
+     * NodeUser - generates a user for the node if not provided in config.
+     */
+    readonly NodeUser: "node-user";
+};
+/**
+ * The features that can be enabled on the node.
+ */
+export type NodeFeatures = (typeof NodeFeatures)[keyof typeof NodeFeatures];

package/dist/types/node.d.ts

@@ -0,0 +1,26 @@
+import type { IServerInfo } from "@twin.org/api-models";
+import type { IEngineServerConfig } from "@twin.org/engine-server-types";
+import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables";
+import type { INodeOptions } from "./models/INodeOptions";
+/**
+ * Run the TWIN Node server.
+ * @param nodeOptions Optional configuration options for running the server.
+ * @returns A promise that resolves when the server is started.
+ */
+export declare function run(nodeOptions?: INodeOptions): Promise<void>;
+/**
+ * Build the configuration for the TWIN Node server.
+ * @param processEnv The environment variables from the process.
+ * @param options The options for running the server.
+ * @param serverInfo The server information.
+ * @returns A promise that resolves to the engine server configuration, environment prefix, environment variables,
+ * and options.
+ */
+export declare function buildConfiguration(processEnv: {
+    [id: string]: string;
+}, options: INodeOptions, serverInfo: IServerInfo): Promise<{
+    nodeEnvVars: INodeEnvironmentVariables & {
+        [id: string]: string | unknown;
+    };
+    engineServerConfig: IEngineServerConfig;
+}>;

package/dist/types/server.d.ts

@@ -0,0 +1,17 @@
+import { Engine } from "@twin.org/engine";
+import { type IEngineState } from "@twin.org/engine-models";
+import { 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";
+/**
+ * Start the engine server.
+ * @param nodeOptions Optional run options for the engine server.
+ * @param engineServerConfig The configuration for the engine server.
+ * @param envVars The environment variables.
+ * @returns The engine server.
+ */
+export declare function start(nodeOptions: INodeOptions | undefined, engineServerConfig: IEngineServerConfig, envVars: INodeEnvironmentVariables): Promise<{
+    engine: Engine<IEngineServerConfig, IEngineState>;
+    server: EngineServer;
+} | undefined>;