@twin.org/api-service 0.0.3-next.43 → 0.0.3-next.45

package/docs/reference/interfaces/IPlatformServiceConstructorOptions.md

@@ -0,0 +1,25 @@
+# Interface: IPlatformServiceConstructorOptions
+
+Options for the Platform Service constructor.
+
+## Properties
+
+### tenantEntityStorageType? {#tenantentitystoragetype}
+
+> `optional` **tenantEntityStorageType?**: `string`
+
+The entity storage for the tenants.
+
+#### Default
+
+```ts
+tenant
+```
+
+***
+
+### config? {#config}
+
+> `optional` **config?**: [`IPlatformServiceConfig`](IPlatformServiceConfig.md)
+
+Configuration for the service.

package/docs/reference/variables/restEntryPoints.md

@@ -1,3 +1,5 @@
 # Variable: restEntryPoints
 
 > `const` **restEntryPoints**: `IRestRouteEntryPoint`[]
+
+REST entry points for the information and health services.

package/locales/en.json

@@ -1,11 +1,5 @@
 {
 	"error": {
-		"urlTransformerService": {
-			"encryptionUnavailable": "Encryption is unavailable because no nodeId is configured",
-			"decryptionUnavailable": "Decryption is unavailable because no nodeId is configured",
-			"encryptionFailed": "An error occurred during encryption",
-			"decryptionFailed": "An error occurred during decryption"
-		},
 		"healthService": {
 			"componentHealthCheckFailed": "Health check failed for component \"{className}\""
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/api-service",
-	"version": "0.0.3-next.43",
+	"version": "0.0.3-next.45",
 	"description": "Information and hosting service implementations with generated REST route handlers.",
 	"repository": {
 		"type": "git",
@@ -14,10 +14,11 @@
 		"node": ">=20.0.0"
 	},
 	"dependencies": {
-		"@twin.org/api-models": "0.0.3-next.43",
+		"@twin.org/api-models": "0.0.3-next.45",
 		"@twin.org/context": "next",
 		"@twin.org/core": "next",
 		"@twin.org/engine-models": "next",
+		"@twin.org/entity-storage-models": "next",
 		"@twin.org/logging-models": "next",
 		"@twin.org/nameof": "next",
 		"@twin.org/vault-models": "next",

package/dist/es/models/IUrlTransformerServiceConfig.js

@@ -1,4 +0,0 @@
-// Copyright 2024 IOTA Stiftung.
-// SPDX-License-Identifier: Apache-2.0.
-export {};
-//# sourceMappingURL=IUrlTransformerServiceConfig.js.map

package/dist/es/models/IUrlTransformerServiceConfig.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"IUrlTransformerServiceConfig.js","sourceRoot":"","sources":["../../../src/models/IUrlTransformerServiceConfig.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Configuration for the URL transformer service.\n */\nexport interface IUrlTransformerServiceConfig {\n\t/**\n\t * The name of the key to retrieve from the vault for encryption/decryption of parameters.\n\t * @default param-encryption\n\t */\n\tparamEncryptionKeyName?: string;\n\n\t/**\n\t * A dictionary mapping logical token identifiers to their URL query parameter names.\n\t * For example: tenant => tenant-token maps the logical id \"tenant\" to the\n\t * query param \"tenant-token\". When an id is not present the id itself is used as\n\t * the param name.\n\t */\n\tqueryParamNames?: { [id: string]: string };\n}\n"]}

package/dist/es/models/IUrlTransformerServiceConstructorOptions.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=IUrlTransformerServiceConstructorOptions.js.map

package/dist/es/models/IUrlTransformerServiceConstructorOptions.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"IUrlTransformerServiceConstructorOptions.js","sourceRoot":"","sources":["../../../src/models/IUrlTransformerServiceConstructorOptions.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IUrlTransformerServiceConfig } from \"./IUrlTransformerServiceConfig.js\";\n\n/**\n * Options for the UrlTransformerService constructor.\n */\nexport interface IUrlTransformerServiceConstructorOptions {\n\t/**\n\t * The vault connector type.\n\t * @default vault\n\t */\n\tvaultConnectorType?: string;\n\n\t/**\n\t * The configuration for the service.\n\t */\n\tconfig?: IUrlTransformerServiceConfig;\n}\n"]}

package/dist/es/urlTransformerService.js

@@ -1,256 +0,0 @@
-import { ContextIdKeys, ContextIdStore } from "@twin.org/context";
-import { BaseError, Converter, GeneralError, Guards, Is, ObjectHelper, RandomHelper, Uint8ArrayHelper } from "@twin.org/core";
-import { VaultConnectorFactory, VaultEncryptionType } from "@twin.org/vault-models";
-/**
- * The URL transformer service for encrypting and decrypting URL parameters.
- */
-export class UrlTransformerService {
-    /**
-     * Runtime name for the class.
-     */
-    static CLASS_NAME = "UrlTransformerService";
-    /**
-     * The prefix to use for encrypted query parameters.
-     * @internal
-     */
-    static _KEY_PREFIX = "x-enc-";
-    /**
-     * The default name for the parameter encryption key query parameter.
-     * @internal
-     */
-    static _DEFAULT_PARAM_ENCRYPTION_KEY_NAME = "param-encryption";
-    /**
-     * The vault connector.
-     * @internal
-     */
-    _vaultConnector;
-    /**
-     * The name of the key to retrieve from the vault for encryption/decryption of parameters.
-     * @internal
-     */
-    _paramEncryptionKeyName;
-    /**
-     * Maps logical token ids to their URL query parameter names.
-     * @internal
-     */
-    _queryParamNames;
-    /**
-     * The node identity, captured at start.
-     * @internal
-     */
-    _nodeId;
-    /**
-     * Create a new instance of UrlTransformerService.
-     * @param options The options to create the service.
-     */
-    constructor(options) {
-        this._vaultConnector = VaultConnectorFactory.get(options?.vaultConnectorType ?? "vault");
-        this._paramEncryptionKeyName =
-            options?.config?.paramEncryptionKeyName ??
-                UrlTransformerService._DEFAULT_PARAM_ENCRYPTION_KEY_NAME;
-        this._queryParamNames = options?.config?.queryParamNames ?? {};
-    }
-    /**
-     * Returns the class name of the component.
-     * @returns The class name of the component.
-     */
-    className() {
-        return UrlTransformerService.CLASS_NAME;
-    }
-    /**
-     * The component needs to be started when the node is initialized.
-     * @returns Nothing.
-     */
-    async start() {
-        const contextIds = await ContextIdStore.getContextIds();
-        this._nodeId = contextIds?.[ContextIdKeys.Node];
-    }
-    /**
-     * Encrypt a named token value and append it as a query parameter to the given URL.
-     * @param url The URL to append the encrypted token to.
-     * @param id The logical token identifier (e.g. "tenant").
-     * @param value The value to encrypt and add.
-     * @returns The URL with the encrypted token added as a query parameter.
-     */
-    async addEncryptedQueryParamToUrl(url, id, value) {
-        const paramName = this._queryParamNames[id] ?? id;
-        return this.addEncryptedToUrl(url, { [paramName]: value });
-    }
-    /**
-     * Get a named token value from the query parameters.
-     * @param queryParams The HTTP request query containing the parameters.
-     * @param id The logical token identifier (e.g. "tenant").
-     * @returns The decrypted token value if it exists.
-     */
-    async getEncryptedQueryParam(queryParams, id) {
-        const paramName = this._queryParamNames[id] ?? id;
-        const decrypted = await this.getDecryptedFromQueryParams(queryParams, [paramName]);
-        return decrypted[paramName];
-    }
-    /**
-     * Add encrypted key/value pairs to a URL's query string.
-     * @param url The base URL to add parameters to.
-     * @param params The key/value pairs to encrypt and append.
-     * @returns The URL with the encrypted parameters added.
-     */
-    async addEncryptedToUrl(url, params) {
-        let urlObj;
-        try {
-            urlObj = new URL(url);
-        }
-        catch {
-            return url;
-        }
-        const query = {};
-        for (const [key, value] of urlObj.searchParams.entries()) {
-            query[key] = value;
-        }
-        const keysToEncrypt = Object.keys(params);
-        for (const [key, value] of Object.entries(params)) {
-            query[key] = value;
-        }
-        await this.encryptQueryParams(query, keysToEncrypt);
-        urlObj.search = "";
-        for (const [key, value] of Object.entries(query)) {
-            urlObj.searchParams.set(key, value);
-        }
-        return urlObj.toString();
-    }
-    /**
-     * Get an encrypted value from a URL's query string.
-     * @param url The URL to extract the encrypted value from.
-     * @param id The logical identifier for the value to retrieve (e.g. "tenant").
-     * @returns The decrypted value if it exists.
-     */
-    async getEncryptedFromUrl(url, id) {
-        let urlObj;
-        try {
-            urlObj = new URL(url);
-        }
-        catch {
-            return undefined;
-        }
-        const name = this.getParamName(id);
-        if (!Is.stringValue(name)) {
-            return undefined;
-        }
-        if (urlObj.searchParams.has(name)) {
-            const encryptedValue = urlObj.searchParams.get(name);
-            if (Is.stringValue(encryptedValue)) {
-                return this.decryptParam(encryptedValue);
-            }
-            return undefined;
-        }
-    }
-    /**
-     * Decrypt specified keys from a query parameter object and return their plain-text values.
-     * @param queryParams The HTTP request query containing the encrypted parameters.
-     * @param keys The keys to decrypt.
-     * @returns A map of the decrypted key/value pairs that were present.
-     */
-    async getDecryptedFromQueryParams(queryParams, keys) {
-        const queryParamsClone = ObjectHelper.clone(queryParams) ?? {};
-        await this.decryptQueryParams(queryParamsClone, keys);
-        const result = {};
-        for (const key of keys) {
-            if (Is.stringValue(queryParamsClone[key])) {
-                result[key] = queryParamsClone[key];
-            }
-        }
-        return result;
-    }
-    /**
-     * Encrypt query parameters.
-     * @param httpRequestQuery The HTTP request query containing the parameters to encrypt.
-     * @param keys The keys of the parameters to encrypt.
-     * @returns A promise that resolves when the query parameters have been encrypted.
-     */
-    async encryptQueryParams(httpRequestQuery, keys) {
-        if (Is.empty(httpRequestQuery)) {
-            return;
-        }
-        for (const key of keys) {
-            if (Is.stringValue(httpRequestQuery[key])) {
-                const encryptedValue = await this.encryptParam(httpRequestQuery[key]);
-                httpRequestQuery[`${UrlTransformerService._KEY_PREFIX}${key}`] = encryptedValue;
-                delete httpRequestQuery[key];
-            }
-        }
-    }
-    /**
-     * Decrypt query parameters.
-     * @param httpRequestQuery The HTTP request query containing the encrypted values.
-     * @param keys The keys of the parameters to decrypt.
-     * @returns A promise that resolves when the query parameters have been decrypted.
-     */
-    async decryptQueryParams(httpRequestQuery, keys) {
-        if (Is.empty(httpRequestQuery)) {
-            return;
-        }
-        for (const key of Object.keys(httpRequestQuery)) {
-            if (key.startsWith(UrlTransformerService._KEY_PREFIX)) {
-                const originalKey = key.slice(UrlTransformerService._KEY_PREFIX.length);
-                if (keys.includes(originalKey)) {
-                    const decryptedValue = await this.decryptParam(httpRequestQuery[key]);
-                    httpRequestQuery[originalKey] = decryptedValue;
-                    delete httpRequestQuery[key];
-                }
-            }
-        }
-    }
-    /**
-     * Encrypt a parameter value.
-     * @param paramValue The value of the parameter to encrypt.
-     * @returns A promise that resolves to the encrypted value of the parameter.
-     */
-    async encryptParam(paramValue) {
-        Guards.stringValue(UrlTransformerService.CLASS_NAME, "paramValue", paramValue);
-        if (Is.empty(this._nodeId)) {
-            throw new GeneralError(UrlTransformerService.CLASS_NAME, "encryptionUnavailable");
-        }
-        try {
-            const salt = RandomHelper.generate(8);
-            const encryptedParamValue = await this._vaultConnector.encrypt(`${this._nodeId}/${this._paramEncryptionKeyName}`, VaultEncryptionType.ChaCha20Poly1305, Uint8ArrayHelper.concat([salt, Converter.utf8ToBytes(paramValue)]));
-            if (!Is.uint8Array(encryptedParamValue)) {
-                throw new GeneralError(UrlTransformerService.CLASS_NAME, "encryptionFailed");
-            }
-            return Converter.bytesToBase64Url(encryptedParamValue);
-        }
-        catch (err) {
-            throw new GeneralError(UrlTransformerService.CLASS_NAME, "encryptionFailed", undefined, BaseError.fromError(err));
-        }
-    }
-    /**
-     * Decrypt a parameter value.
-     * @param encryptedValue The encrypted value of the parameter.
-     * @returns A promise that resolves to the decrypted value of the parameter.
-     */
-    async decryptParam(encryptedValue) {
-        Guards.stringValue(UrlTransformerService.CLASS_NAME, "encryptedValue", encryptedValue);
-        if (Is.empty(this._nodeId)) {
-            throw new GeneralError(UrlTransformerService.CLASS_NAME, "decryptionUnavailable");
-        }
-        try {
-            const encryptedBytes = Converter.base64UrlToBytes(encryptedValue);
-            const decryptedBytes = await this._vaultConnector.decrypt(`${this._nodeId}/${this._paramEncryptionKeyName}`, VaultEncryptionType.ChaCha20Poly1305, encryptedBytes);
-            if (!Is.uint8Array(decryptedBytes)) {
-                throw new GeneralError(UrlTransformerService.CLASS_NAME, "decryptionFailed");
-            }
-            return Converter.bytesToUtf8(decryptedBytes.slice(8));
-        }
-        catch (err) {
-            throw new GeneralError(UrlTransformerService.CLASS_NAME, "decryptionFailed", undefined, BaseError.fromError(err));
-        }
-    }
-    /**
-     * Get the parameter name for a given key.
-     * @param key The key of the parameter.
-     * @returns The parameter name.
-     */
-    getParamName(key) {
-        return Is.stringValue(this._queryParamNames[key])
-            ? `${UrlTransformerService._KEY_PREFIX}${this._queryParamNames[key]}`
-            : undefined;
-    }
-}
-//# sourceMappingURL=urlTransformerService.js.map

package/dist/es/urlTransformerService.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"urlTransformerService.js","sourceRoot":"","sources":["../../src/urlTransformerService.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IHttpRequestQuery, IUrlTransformerComponent } from \"@twin.org/api-models\";\nimport { ContextIdKeys, ContextIdStore } from \"@twin.org/context\";\nimport {\n\tBaseError,\n\tConverter,\n\tGeneralError,\n\tGuards,\n\tIs,\n\tObjectHelper,\n\tRandomHelper,\n\tUint8ArrayHelper\n} from \"@twin.org/core\";\nimport { nameof } from \"@twin.org/nameof\";\nimport {\n\ttype IVaultConnector,\n\tVaultConnectorFactory,\n\tVaultEncryptionType\n} from \"@twin.org/vault-models\";\nimport type { IUrlTransformerServiceConstructorOptions } from \"./models/IUrlTransformerServiceConstructorOptions.js\";\n\n/**\n * The URL transformer service for encrypting and decrypting URL parameters.\n */\nexport class UrlTransformerService implements IUrlTransformerComponent {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<UrlTransformerService>();\n\n\t/**\n\t * The prefix to use for encrypted query parameters.\n\t * @internal\n\t */\n\tprivate static readonly _KEY_PREFIX = \"x-enc-\";\n\n\t/**\n\t * The default name for the parameter encryption key query parameter.\n\t * @internal\n\t */\n\tprivate static readonly _DEFAULT_PARAM_ENCRYPTION_KEY_NAME: string = \"param-encryption\";\n\n\t/**\n\t * The vault connector.\n\t * @internal\n\t */\n\tprivate readonly _vaultConnector: IVaultConnector;\n\n\t/**\n\t * The name of the key to retrieve from the vault for encryption/decryption of parameters.\n\t * @internal\n\t */\n\tprivate readonly _paramEncryptionKeyName: string;\n\n\t/**\n\t * Maps logical token ids to their URL query parameter names.\n\t * @internal\n\t */\n\tprivate readonly _queryParamNames: { [id: string]: string };\n\n\t/**\n\t * The node identity, captured at start.\n\t * @internal\n\t */\n\tprivate _nodeId?: string;\n\n\t/**\n\t * Create a new instance of UrlTransformerService.\n\t * @param options The options to create the service.\n\t */\n\tconstructor(options?: IUrlTransformerServiceConstructorOptions) {\n\t\tthis._vaultConnector = VaultConnectorFactory.get(options?.vaultConnectorType ?? \"vault\");\n\t\tthis._paramEncryptionKeyName =\n\t\t\toptions?.config?.paramEncryptionKeyName ??\n\t\t\tUrlTransformerService._DEFAULT_PARAM_ENCRYPTION_KEY_NAME;\n\t\tthis._queryParamNames = options?.config?.queryParamNames ?? {};\n\t}\n\n\t/**\n\t * Returns the class name of the component.\n\t * @returns The class name of the component.\n\t */\n\tpublic className(): string {\n\t\treturn UrlTransformerService.CLASS_NAME;\n\t}\n\n\t/**\n\t * The component needs to be started when the node is initialized.\n\t * @returns Nothing.\n\t */\n\tpublic async start(): Promise<void> {\n\t\tconst contextIds = await ContextIdStore.getContextIds();\n\t\tthis._nodeId = contextIds?.[ContextIdKeys.Node];\n\t}\n\n\t/**\n\t * Encrypt a named token value and append it as a query parameter to the given URL.\n\t * @param url The URL to append the encrypted token to.\n\t * @param id The logical token identifier (e.g. \"tenant\").\n\t * @param value The value to encrypt and add.\n\t * @returns The URL with the encrypted token added as a query parameter.\n\t */\n\tpublic async addEncryptedQueryParamToUrl(\n\t\turl: string,\n\t\tid: string,\n\t\tvalue: string\n\t): Promise<string> {\n\t\tconst paramName = this._queryParamNames[id] ?? id;\n\t\treturn this.addEncryptedToUrl(url, { [paramName]: value });\n\t}\n\n\t/**\n\t * Get a named token value from the query parameters.\n\t * @param queryParams The HTTP request query containing the parameters.\n\t * @param id The logical token identifier (e.g. \"tenant\").\n\t * @returns The decrypted token value if it exists.\n\t */\n\tpublic async getEncryptedQueryParam(\n\t\tqueryParams: IHttpRequestQuery | undefined,\n\t\tid: string\n\t): Promise<string | undefined> {\n\t\tconst paramName = this._queryParamNames[id] ?? id;\n\t\tconst decrypted = await this.getDecryptedFromQueryParams(queryParams, [paramName]);\n\t\treturn decrypted[paramName];\n\t}\n\n\t/**\n\t * Add encrypted key/value pairs to a URL's query string.\n\t * @param url The base URL to add parameters to.\n\t * @param params The key/value pairs to encrypt and append.\n\t * @returns The URL with the encrypted parameters added.\n\t */\n\tpublic async addEncryptedToUrl(url: string, params: IHttpRequestQuery): Promise<string> {\n\t\tlet urlObj: URL;\n\t\ttry {\n\t\t\turlObj = new URL(url);\n\t\t} catch {\n\t\t\treturn url;\n\t\t}\n\n\t\tconst query: IHttpRequestQuery = {};\n\t\tfor (const [key, value] of urlObj.searchParams.entries()) {\n\t\t\tquery[key] = value;\n\t\t}\n\t\tconst keysToEncrypt = Object.keys(params);\n\t\tfor (const [key, value] of Object.entries(params)) {\n\t\t\tquery[key] = value;\n\t\t}\n\t\tawait this.encryptQueryParams(query, keysToEncrypt);\n\t\turlObj.search = \"\";\n\t\tfor (const [key, value] of Object.entries(query)) {\n\t\t\turlObj.searchParams.set(key, value);\n\t\t}\n\t\treturn urlObj.toString();\n\t}\n\n\t/**\n\t * Get an encrypted value from a URL's query string.\n\t * @param url The URL to extract the encrypted value from.\n\t * @param id The logical identifier for the value to retrieve (e.g. \"tenant\").\n\t * @returns The decrypted value if it exists.\n\t */\n\tpublic async getEncryptedFromUrl(url: string, id: string): Promise<string | undefined> {\n\t\tlet urlObj: URL;\n\t\ttry {\n\t\t\turlObj = new URL(url);\n\t\t} catch {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst name = this.getParamName(id);\n\t\tif (!Is.stringValue(name)) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tif (urlObj.searchParams.has(name)) {\n\t\t\tconst encryptedValue = urlObj.searchParams.get(name);\n\t\t\tif (Is.stringValue(encryptedValue)) {\n\t\t\t\treturn this.decryptParam(encryptedValue);\n\t\t\t}\n\t\t\treturn undefined;\n\t\t}\n\t}\n\n\t/**\n\t * Decrypt specified keys from a query parameter object and return their plain-text values.\n\t * @param queryParams The HTTP request query containing the encrypted parameters.\n\t * @param keys The keys to decrypt.\n\t * @returns A map of the decrypted key/value pairs that were present.\n\t */\n\tpublic async getDecryptedFromQueryParams(\n\t\tqueryParams: IHttpRequestQuery | undefined,\n\t\tkeys: string[]\n\t): Promise<IHttpRequestQuery> {\n\t\tconst queryParamsClone = ObjectHelper.clone(queryParams) ?? {};\n\t\tawait this.decryptQueryParams(queryParamsClone, keys);\n\t\tconst result: IHttpRequestQuery = {};\n\t\tfor (const key of keys) {\n\t\t\tif (Is.stringValue(queryParamsClone[key])) {\n\t\t\t\tresult[key] = queryParamsClone[key];\n\t\t\t}\n\t\t}\n\t\treturn result;\n\t}\n\n\t/**\n\t * Encrypt query parameters.\n\t * @param httpRequestQuery The HTTP request query containing the parameters to encrypt.\n\t * @param keys The keys of the parameters to encrypt.\n\t * @returns A promise that resolves when the query parameters have been encrypted.\n\t */\n\tpublic async encryptQueryParams(\n\t\thttpRequestQuery: IHttpRequestQuery | undefined,\n\t\tkeys: string[]\n\t): Promise<void> {\n\t\tif (Is.empty(httpRequestQuery)) {\n\t\t\treturn;\n\t\t}\n\n\t\tfor (const key of keys) {\n\t\t\tif (Is.stringValue(httpRequestQuery[key])) {\n\t\t\t\tconst encryptedValue = await this.encryptParam(httpRequestQuery[key]);\n\t\t\t\thttpRequestQuery[`${UrlTransformerService._KEY_PREFIX}${key}`] = encryptedValue;\n\t\t\t\tdelete httpRequestQuery[key];\n\t\t\t}\n\t\t}\n\t}\n\n\t/**\n\t * Decrypt query parameters.\n\t * @param httpRequestQuery The HTTP request query containing the encrypted values.\n\t * @param keys The keys of the parameters to decrypt.\n\t * @returns A promise that resolves when the query parameters have been decrypted.\n\t */\n\tpublic async decryptQueryParams(\n\t\thttpRequestQuery: IHttpRequestQuery | undefined,\n\t\tkeys: string[]\n\t): Promise<void> {\n\t\tif (Is.empty(httpRequestQuery)) {\n\t\t\treturn;\n\t\t}\n\t\tfor (const key of Object.keys(httpRequestQuery)) {\n\t\t\tif (key.startsWith(UrlTransformerService._KEY_PREFIX)) {\n\t\t\t\tconst originalKey = key.slice(UrlTransformerService._KEY_PREFIX.length);\n\n\t\t\t\tif (keys.includes(originalKey)) {\n\t\t\t\t\tconst decryptedValue = await this.decryptParam(httpRequestQuery[key]);\n\t\t\t\t\thttpRequestQuery[originalKey] = decryptedValue;\n\t\t\t\t\tdelete httpRequestQuery[key];\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\t/**\n\t * Encrypt a parameter value.\n\t * @param paramValue The value of the parameter to encrypt.\n\t * @returns A promise that resolves to the encrypted value of the parameter.\n\t */\n\tpublic async encryptParam(paramValue: string): Promise<string> {\n\t\tGuards.stringValue(UrlTransformerService.CLASS_NAME, nameof(paramValue), paramValue);\n\n\t\tif (Is.empty(this._nodeId)) {\n\t\t\tthrow new GeneralError(UrlTransformerService.CLASS_NAME, \"encryptionUnavailable\");\n\t\t}\n\n\t\ttry {\n\t\t\tconst salt = RandomHelper.generate(8);\n\n\t\t\tconst encryptedParamValue = await this._vaultConnector.encrypt(\n\t\t\t\t`${this._nodeId}/${this._paramEncryptionKeyName}`,\n\t\t\t\tVaultEncryptionType.ChaCha20Poly1305,\n\t\t\t\tUint8ArrayHelper.concat([salt, Converter.utf8ToBytes(paramValue)])\n\t\t\t);\n\n\t\t\tif (!Is.uint8Array(encryptedParamValue)) {\n\t\t\t\tthrow new GeneralError(UrlTransformerService.CLASS_NAME, \"encryptionFailed\");\n\t\t\t}\n\n\t\t\treturn Converter.bytesToBase64Url(encryptedParamValue);\n\t\t} catch (err) {\n\t\t\tthrow new GeneralError(\n\t\t\t\tUrlTransformerService.CLASS_NAME,\n\t\t\t\t\"encryptionFailed\",\n\t\t\t\tundefined,\n\t\t\t\tBaseError.fromError(err)\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Decrypt a parameter value.\n\t * @param encryptedValue The encrypted value of the parameter.\n\t * @returns A promise that resolves to the decrypted value of the parameter.\n\t */\n\tpublic async decryptParam(encryptedValue: string): Promise<string> {\n\t\tGuards.stringValue(UrlTransformerService.CLASS_NAME, nameof(encryptedValue), encryptedValue);\n\n\t\tif (Is.empty(this._nodeId)) {\n\t\t\tthrow new GeneralError(UrlTransformerService.CLASS_NAME, \"decryptionUnavailable\");\n\t\t}\n\n\t\ttry {\n\t\t\tconst encryptedBytes = Converter.base64UrlToBytes(encryptedValue);\n\t\t\tconst decryptedBytes = await this._vaultConnector.decrypt(\n\t\t\t\t`${this._nodeId}/${this._paramEncryptionKeyName}`,\n\t\t\t\tVaultEncryptionType.ChaCha20Poly1305,\n\t\t\t\tencryptedBytes\n\t\t\t);\n\n\t\t\tif (!Is.uint8Array(decryptedBytes)) {\n\t\t\t\tthrow new GeneralError(UrlTransformerService.CLASS_NAME, \"decryptionFailed\");\n\t\t\t}\n\n\t\t\treturn Converter.bytesToUtf8(decryptedBytes.slice(8));\n\t\t} catch (err) {\n\t\t\tthrow new GeneralError(\n\t\t\t\tUrlTransformerService.CLASS_NAME,\n\t\t\t\t\"decryptionFailed\",\n\t\t\t\tundefined,\n\t\t\t\tBaseError.fromError(err)\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Get the parameter name for a given key.\n\t * @param key The key of the parameter.\n\t * @returns The parameter name.\n\t */\n\tpublic getParamName(key: string): string | undefined {\n\t\treturn Is.stringValue(this._queryParamNames[key])\n\t\t\t? `${UrlTransformerService._KEY_PREFIX}${this._queryParamNames[key]}`\n\t\t\t: undefined;\n\t}\n}\n"]}

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

@@ -1,19 +0,0 @@
-/**
- * Configuration for the URL transformer service.
- */
-export interface IUrlTransformerServiceConfig {
-    /**
-     * The name of the key to retrieve from the vault for encryption/decryption of parameters.
-     * @default param-encryption
-     */
-    paramEncryptionKeyName?: string;
-    /**
-     * A dictionary mapping logical token identifiers to their URL query parameter names.
-     * For example: tenant => tenant-token maps the logical id "tenant" to the
-     * query param "tenant-token". When an id is not present the id itself is used as
-     * the param name.
-     */
-    queryParamNames?: {
-        [id: string]: string;
-    };
-}

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

@@ -1,15 +0,0 @@
-import type { IUrlTransformerServiceConfig } from "./IUrlTransformerServiceConfig.js";
-/**
- * Options for the UrlTransformerService constructor.
- */
-export interface IUrlTransformerServiceConstructorOptions {
-    /**
-     * The vault connector type.
-     * @default vault
-     */
-    vaultConnectorType?: string;
-    /**
-     * The configuration for the service.
-     */
-    config?: IUrlTransformerServiceConfig;
-}

package/dist/types/urlTransformerService.d.ts

@@ -1,94 +0,0 @@
-import type { IHttpRequestQuery, IUrlTransformerComponent } from "@twin.org/api-models";
-import type { IUrlTransformerServiceConstructorOptions } from "./models/IUrlTransformerServiceConstructorOptions.js";
-/**
- * The URL transformer service for encrypting and decrypting URL parameters.
- */
-export declare class UrlTransformerService implements IUrlTransformerComponent {
-    /**
-     * Runtime name for the class.
-     */
-    static readonly CLASS_NAME: string;
-    /**
-     * Create a new instance of UrlTransformerService.
-     * @param options The options to create the service.
-     */
-    constructor(options?: IUrlTransformerServiceConstructorOptions);
-    /**
-     * Returns the class name of the component.
-     * @returns The class name of the component.
-     */
-    className(): string;
-    /**
-     * The component needs to be started when the node is initialized.
-     * @returns Nothing.
-     */
-    start(): Promise<void>;
-    /**
-     * Encrypt a named token value and append it as a query parameter to the given URL.
-     * @param url The URL to append the encrypted token to.
-     * @param id The logical token identifier (e.g. "tenant").
-     * @param value The value to encrypt and add.
-     * @returns The URL with the encrypted token added as a query parameter.
-     */
-    addEncryptedQueryParamToUrl(url: string, id: string, value: string): Promise<string>;
-    /**
-     * Get a named token value from the query parameters.
-     * @param queryParams The HTTP request query containing the parameters.
-     * @param id The logical token identifier (e.g. "tenant").
-     * @returns The decrypted token value if it exists.
-     */
-    getEncryptedQueryParam(queryParams: IHttpRequestQuery | undefined, id: string): Promise<string | undefined>;
-    /**
-     * Add encrypted key/value pairs to a URL's query string.
-     * @param url The base URL to add parameters to.
-     * @param params The key/value pairs to encrypt and append.
-     * @returns The URL with the encrypted parameters added.
-     */
-    addEncryptedToUrl(url: string, params: IHttpRequestQuery): Promise<string>;
-    /**
-     * Get an encrypted value from a URL's query string.
-     * @param url The URL to extract the encrypted value from.
-     * @param id The logical identifier for the value to retrieve (e.g. "tenant").
-     * @returns The decrypted value if it exists.
-     */
-    getEncryptedFromUrl(url: string, id: string): Promise<string | undefined>;
-    /**
-     * Decrypt specified keys from a query parameter object and return their plain-text values.
-     * @param queryParams The HTTP request query containing the encrypted parameters.
-     * @param keys The keys to decrypt.
-     * @returns A map of the decrypted key/value pairs that were present.
-     */
-    getDecryptedFromQueryParams(queryParams: IHttpRequestQuery | undefined, keys: string[]): Promise<IHttpRequestQuery>;
-    /**
-     * Encrypt query parameters.
-     * @param httpRequestQuery The HTTP request query containing the parameters to encrypt.
-     * @param keys The keys of the parameters to encrypt.
-     * @returns A promise that resolves when the query parameters have been encrypted.
-     */
-    encryptQueryParams(httpRequestQuery: IHttpRequestQuery | undefined, keys: string[]): Promise<void>;
-    /**
-     * Decrypt query parameters.
-     * @param httpRequestQuery The HTTP request query containing the encrypted values.
-     * @param keys The keys of the parameters to decrypt.
-     * @returns A promise that resolves when the query parameters have been decrypted.
-     */
-    decryptQueryParams(httpRequestQuery: IHttpRequestQuery | undefined, keys: string[]): Promise<void>;
-    /**
-     * Encrypt a parameter value.
-     * @param paramValue The value of the parameter to encrypt.
-     * @returns A promise that resolves to the encrypted value of the parameter.
-     */
-    encryptParam(paramValue: string): Promise<string>;
-    /**
-     * Decrypt a parameter value.
-     * @param encryptedValue The encrypted value of the parameter.
-     * @returns A promise that resolves to the decrypted value of the parameter.
-     */
-    decryptParam(encryptedValue: string): Promise<string>;
-    /**
-     * Get the parameter name for a given key.
-     * @param key The key of the parameter.
-     * @returns The parameter name.
-     */
-    getParamName(key: string): string | undefined;
-}