@twin.org/api-service 0.0.3-next.28 → 0.0.3-next.29

package/dist/es/hostingService.js

@@ -2,7 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0.
 import { HttpUrlHelper } from "@twin.org/api-models";
 import { ContextIdKeys, ContextIdStore } from "@twin.org/context";
-import { ComponentFactory, Guards, Is } from "@twin.org/core";
+import { BaseError, ComponentFactory, Converter, GeneralError, Guards, Is, ObjectHelper, RandomHelper, Uint8ArrayHelper } from "@twin.org/core";
+import { VaultConnectorFactory, VaultEncryptionType } from "@twin.org/vault-models";
 /**
  * The hosting service for the server.
  */
@@ -11,11 +12,33 @@ export class HostingService {
      * Runtime name for the class.
      */
     static CLASS_NAME = "HostingService";
+    /**
+     * The prefix to use for encrypted query parameters when encrypting/decrypting.
+     * This is used to identify which query parameters have been encrypted.
+     * The actual key used in the query will be "x-enc-{originalKey}".
+     * @internal
+     */
+    static _KEY_PREFIX = "x-enc-";
+    /**
+     * The default name for the tenant token query parameter.
+     * @internal
+     */
+    static _DEFAULT_TENANT_TOKEN_NAME = "tenant-token";
+    /**
+     * The default name for the parameter encryption key query parameter.
+     * @internal
+     */
+    static _DEFAULT_PARAM_ENCRYPTION_KEY_NAME = "param-encryption";
     /**
      * The tenant admin component.
      * @internal
      */
-    _tenantAdminComponent;
+    _tenantAdminComponentType;
+    /**
+     * The vault connector type.
+     * @internal
+     */
+    _vaultConnectorType;
     /**
      * The local origin URL e.g. "http://localhost:3000".
      * @internal
@@ -26,6 +49,21 @@ export class HostingService {
      * @internal
      */
     _publicOrigin;
+    /**
+     * The name of the key to retrieve from the vault for encryption/decryption of parameters.
+     * @internal
+     */
+    _paramEncryptionKeyName;
+    /**
+     * The query param name carrying the encrypted tenant token.
+     * @internal
+     */
+    _tenantTokenName;
+    /**
+     * The node identity, captured at start.
+     * @internal
+     */
+    _nodeId;
     /**
      * Create a new instance of HostingService.
      * @param options The options to create the service.
@@ -34,9 +72,14 @@ export class HostingService {
         Guards.object(HostingService.CLASS_NAME, "options", options);
         Guards.object(HostingService.CLASS_NAME, "options.config", options.config);
         Guards.stringValue(HostingService.CLASS_NAME, "options.config.localOrigin", options.config.localOrigin);
-        this._tenantAdminComponent = ComponentFactory.getIfExists(options?.tenantAdminComponentType ?? "tenant-admin");
+        this._tenantAdminComponentType = options?.tenantAdminComponentType ?? "tenant-admin";
+        this._vaultConnectorType = options?.vaultConnectorType ?? "vault";
         this._localOrigin = options.config.localOrigin;
         this._publicOrigin = options.config.publicOrigin;
+        this._paramEncryptionKeyName =
+            options.config.paramEncryptionKeyName ?? HostingService._DEFAULT_PARAM_ENCRYPTION_KEY_NAME;
+        this._tenantTokenName =
+            options.config.tenantTokenName ?? HostingService._DEFAULT_TENANT_TOKEN_NAME;
     }
     /**
      * Returns the class name of the component.
@@ -45,6 +88,15 @@ export class HostingService {
     className() {
         return HostingService.CLASS_NAME;
     }
+    /**
+     * The component needs to be started when the node is initialized.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns Nothing.
+     */
+    async start(nodeLoggingComponentType) {
+        const contextIds = await ContextIdStore.getContextIds();
+        this._nodeId = contextIds?.[ContextIdKeys.Node];
+    }
     /**
      * Get the public origin for the hosting.
      * @param serverRequestUrl The url of the current server request if there is one.
@@ -75,10 +127,11 @@ export class HostingService {
      */
     async getTenantOrigin(tenantId) {
         Guards.stringHexLength(HostingService.CLASS_NAME, "tenantId", tenantId, 32);
-        if (Is.empty(this._tenantAdminComponent)) {
+        const tenantAdminComponent = ComponentFactory.getIfExists(this._tenantAdminComponentType);
+        if (Is.empty(tenantAdminComponent)) {
             return undefined;
         }
-        const tenant = await this._tenantAdminComponent.get(tenantId);
+        const tenant = await tenantAdminComponent.get(tenantId);
         return tenant?.publicOrigin;
     }
     /**
@@ -90,5 +143,155 @@ export class HostingService {
         const publicOrigin = await this.getPublicOrigin(url);
         return HttpUrlHelper.replaceOrigin(url, publicOrigin);
     }
+    /**
+     * Add encrypted key/value pairs to a URL's query string.
+     * Existing query parameters on the URL are preserved; the provided params are
+     * merged in and then encrypted before being written back to the URL.
+     * @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 addEncryptedParamsToUrl(url, params) {
+        const urlObj = new URL(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();
+    }
+    /**
+     * 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 getDecryptedParamsFromQueryParams(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 the tenant id and append it as a query parameter to the given URL.
+     * @param url The URL to append the encrypted tenant token to.
+     * @param tenantId The tenant identifier to encrypt and add.
+     * @returns The URL with the encrypted tenant token added as a query parameter.
+     */
+    async addTenantTokenToUrl(url, tenantId) {
+        return this.addEncryptedParamsToUrl(url, { [this._tenantTokenName]: tenantId });
+    }
+    /**
+     * Get the tenant token from the query parameters.
+     * @param queryParams The HTTP request query containing the parameters.
+     * @returns The tenant token if it exists.
+     */
+    async getTenantTokenFromQueryParams(queryParams) {
+        const decrypted = await this.getDecryptedParamsFromQueryParams(queryParams, [
+            this._tenantTokenName
+        ]);
+        return decrypted[this._tenantTokenName];
+    }
+    /**
+     * Encrypt query parameters using the hosting component's encryption mechanism.
+     * @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[`${HostingService._KEY_PREFIX}${key}`] = encryptedValue;
+                delete httpRequestQuery[key];
+            }
+        }
+    }
+    /**
+     * Decrypt query parameters using the hosting component's encryption mechanism.
+     * @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(HostingService._KEY_PREFIX)) {
+                const originalKey = key.slice(HostingService._KEY_PREFIX.length);
+                if (keys.includes(originalKey)) {
+                    const decryptedValue = await this.decryptParam(httpRequestQuery[key]);
+                    httpRequestQuery[originalKey] = decryptedValue;
+                    delete httpRequestQuery[key];
+                }
+            }
+        }
+    }
+    /**
+     * Encrypt a parameter value using the hosting component's encryption mechanism.
+     * @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(HostingService.CLASS_NAME, "paramValue", paramValue);
+        const vaultConnector = VaultConnectorFactory.getIfExists(this._vaultConnectorType);
+        if (Is.empty(vaultConnector) || Is.empty(this._nodeId)) {
+            throw new GeneralError(HostingService.CLASS_NAME, "encryptionUnavailable");
+        }
+        try {
+            // Add a salt to the encryption to ensure that the same value encrypted multiple times will yield different results,
+            // preventing rainbow table attacks.
+            const salt = RandomHelper.generate(8);
+            const encryptedParamValue = await vaultConnector.encrypt(`${this._nodeId}/${this._paramEncryptionKeyName}`, VaultEncryptionType.ChaCha20Poly1305, Uint8ArrayHelper.concat([salt, Converter.utf8ToBytes(paramValue)]));
+            if (!Is.uint8Array(encryptedParamValue)) {
+                throw new GeneralError(HostingService.CLASS_NAME, "encryptionFailed");
+            }
+            return Converter.bytesToBase64Url(encryptedParamValue);
+        }
+        catch (err) {
+            throw new GeneralError(HostingService.CLASS_NAME, "encryptionFailed", undefined, BaseError.fromError(err));
+        }
+    }
+    /**
+     * Decrypt a parameter value using the hosting component's encryption mechanism.
+     * @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(HostingService.CLASS_NAME, "encryptedValue", encryptedValue);
+        const vaultConnector = VaultConnectorFactory.getIfExists(this._vaultConnectorType);
+        if (Is.empty(vaultConnector) || Is.empty(this._nodeId)) {
+            throw new GeneralError(HostingService.CLASS_NAME, "decryptionUnavailable");
+        }
+        try {
+            const encryptedBytes = Converter.base64UrlToBytes(encryptedValue);
+            const decryptedBytes = await vaultConnector.decrypt(`${this._nodeId}/${this._paramEncryptionKeyName}`, VaultEncryptionType.ChaCha20Poly1305, encryptedBytes);
+            if (!Is.uint8Array(decryptedBytes)) {
+                throw new GeneralError(HostingService.CLASS_NAME, "decryptionFailed");
+            }
+            // The decrypted value is expected to have the salt as the first 8 bytes, which we need to remove before returning the original value.
+            return Converter.bytesToUtf8(decryptedBytes.slice(8));
+        }
+        catch (err) {
+            throw new GeneralError(HostingService.CLASS_NAME, "decryptionFailed", undefined, BaseError.fromError(err));
+        }
+    }
 }
 //# sourceMappingURL=hostingService.js.map

package/dist/es/hostingService.js.map

@@ -1 +1 @@
-{"version":3,"file":"hostingService.js","sourceRoot":"","sources":["../../src/hostingService.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EACN,aAAa,EAGb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AAI9D;;GAEG;AACH,MAAM,OAAO,cAAc;IAC1B;;OAEG;IACI,MAAM,CAAU,UAAU,oBAAoC;IAErE;;;OAGG;IACc,qBAAqB,CAAyB;IAE/D;;;OAGG;IACc,YAAY,CAAS;IAEtC;;;OAGG;IACc,aAAa,CAAU;IAExC;;;OAGG;IACH,YAAY,OAA0C;QACrD,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,UAAU,aAAmB,OAAO,CAAC,CAAC;QACnE,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,UAAU,oBAA0B,OAAO,CAAC,MAAM,CAAC,CAAC;QACjF,MAAM,CAAC,WAAW,CACjB,cAAc,CAAC,UAAU,gCAEzB,OAAO,CAAC,MAAM,CAAC,WAAW,CAC1B,CAAC;QACF,IAAI,CAAC,qBAAqB,GAAG,gBAAgB,CAAC,WAAW,CACxD,OAAO,EAAE,wBAAwB,IAAI,cAAc,CACnD,CAAC;QACF,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC;QAC/C,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC;IAClD,CAAC;IAED;;;OAGG;IACI,SAAS;QACf,OAAO,cAAc,CAAC,UAAU,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,eAAe,CAAC,gBAAyB;QACrD,6EAA6E;QAC7E,kDAAkD;QAClD,MAAM,UAAU,GAAG,MAAM,cAAc,CAAC,aAAa,EAAE,CAAC;QACxD,MAAM,QAAQ,GAAG,UAAU,EAAE,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QACpD,IAAI,kBAAkB,CAAC;QACvB,IAAI,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9B,kBAAkB,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;QAC3D,CAAC;QAED,MAAM,mBAAmB,GAAG,EAAE,CAAC,WAAW,CAAC,gBAAgB,CAAC;YAC3D,CAAC,CAAC,aAAa,CAAC,aAAa,CAAC,gBAAgB,CAAC;YAC/C,CAAC,CAAC,SAAS,CAAC;QAEb,iDAAiD;QACjD,wDAAwD;QACxD,oDAAoD;QACpD,iCAAiC;QACjC,OAAO,kBAAkB,IAAI,IAAI,CAAC,aAAa,IAAI,mBAAmB,IAAI,IAAI,CAAC,YAAY,CAAC;IAC7F,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,eAAe,CAAC,QAAgB;QAC5C,MAAM,CAAC,eAAe,CAAC,cAAc,CAAC,UAAU,cAAoB,QAAQ,EAAE,EAAE,CAAC,CAAC;QAElF,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,EAAE,CAAC;YAC1C,OAAO,SAAS,CAAC;QAClB,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC9D,OAAO,MAAM,EAAE,YAAY,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,cAAc,CAAC,GAAW;QACtC,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;QACrD,OAAO,aAAa,CAAC,aAAa,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IACvD,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport {\n\tHttpUrlHelper,\n\ttype IHostingComponent,\n\ttype ITenantAdminComponent\n} from \"@twin.org/api-models\";\nimport { ContextIdKeys, ContextIdStore } from \"@twin.org/context\";\nimport { ComponentFactory, Guards, Is } from \"@twin.org/core\";\nimport { nameof } from \"@twin.org/nameof\";\nimport type { IHostingServiceConstructorOptions } from \"./models/IHostingServiceConstructorOptions.js\";\n\n/**\n * The hosting service for the server.\n */\nexport class HostingService implements IHostingComponent {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<HostingService>();\n\n\t/**\n\t * The tenant admin component.\n\t * @internal\n\t */\n\tprivate readonly _tenantAdminComponent?: ITenantAdminComponent;\n\n\t/**\n\t * The local origin URL e.g. \"http://localhost:3000\".\n\t * @internal\n\t */\n\tprivate readonly _localOrigin: string;\n\n\t/**\n\t * The APIs public base URL e.g. \"https://api.example.com:1234\".\n\t * @internal\n\t */\n\tprivate readonly _publicOrigin?: string;\n\n\t/**\n\t * Create a new instance of HostingService.\n\t * @param options The options to create the service.\n\t */\n\tconstructor(options: IHostingServiceConstructorOptions) {\n\t\tGuards.object(HostingService.CLASS_NAME, nameof(options), options);\n\t\tGuards.object(HostingService.CLASS_NAME, nameof(options.config), options.config);\n\t\tGuards.stringValue(\n\t\t\tHostingService.CLASS_NAME,\n\t\t\tnameof(options.config.localOrigin),\n\t\t\toptions.config.localOrigin\n\t\t);\n\t\tthis._tenantAdminComponent = ComponentFactory.getIfExists(\n\t\t\toptions?.tenantAdminComponentType ?? \"tenant-admin\"\n\t\t);\n\t\tthis._localOrigin = options.config.localOrigin;\n\t\tthis._publicOrigin = options.config.publicOrigin;\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 HostingService.CLASS_NAME;\n\t}\n\n\t/**\n\t * Get the public origin for the hosting.\n\t * @param serverRequestUrl The url of the current server request if there is one.\n\t * @returns The public origin.\n\t */\n\tpublic async getPublicOrigin(serverRequestUrl?: string): Promise<string> {\n\t\t// If there is a tenant admin component, and the context has a tenant id set.\n\t\t// set if the tenant has a specific public origin.\n\t\tconst contextIds = await ContextIdStore.getContextIds();\n\t\tconst tenantId = contextIds?.[ContextIdKeys.Tenant];\n\t\tlet tenantPublicOrigin;\n\t\tif (Is.stringValue(tenantId)) {\n\t\t\ttenantPublicOrigin = await this.getTenantOrigin(tenantId);\n\t\t}\n\n\t\tconst serverRequestOrigin = Is.stringValue(serverRequestUrl)\n\t\t\t? HttpUrlHelper.extractOrigin(serverRequestUrl)\n\t\t\t: undefined;\n\n\t\t// If there is a tenant public origin, return it.\n\t\t// If not and the config has a public origin, return it.\n\t\t// Otherwise, use the server request URL if provided\n\t\t// else fallback to local origin.\n\t\treturn tenantPublicOrigin ?? this._publicOrigin ?? serverRequestOrigin ?? this._localOrigin;\n\t}\n\n\t/**\n\t * Get the public origin for the tenant if one exists.\n\t * @param tenantId The tenant identifier.\n\t * @returns The public origin for the tenant.\n\t */\n\tpublic async getTenantOrigin(tenantId: string): Promise<string | undefined> {\n\t\tGuards.stringHexLength(HostingService.CLASS_NAME, nameof(tenantId), tenantId, 32);\n\n\t\tif (Is.empty(this._tenantAdminComponent)) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst tenant = await this._tenantAdminComponent.get(tenantId);\n\t\treturn tenant?.publicOrigin;\n\t}\n\n\t/**\n\t * Build a public url based on the public origin and the url provided.\n\t * @param url The url to build upon the public origin.\n\t * @returns The full url based on the public origin.\n\t */\n\tpublic async buildPublicUrl(url: string): Promise<string> {\n\t\tconst publicOrigin = await this.getPublicOrigin(url);\n\t\treturn HttpUrlHelper.replaceOrigin(url, publicOrigin);\n\t}\n}\n"]}
+{"version":3,"file":"hostingService.js","sourceRoot":"","sources":["../../src/hostingService.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport {\n\tHttpUrlHelper,\n\ttype IHostingComponent,\n\ttype IHttpRequestQuery,\n\ttype ITenantAdminComponent\n} from \"@twin.org/api-models\";\nimport { ContextIdKeys, ContextIdStore } from \"@twin.org/context\";\nimport {\n\tBaseError,\n\tComponentFactory,\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 { VaultConnectorFactory, VaultEncryptionType } from \"@twin.org/vault-models\";\nimport type { IHostingServiceConstructorOptions } from \"./models/IHostingServiceConstructorOptions.js\";\n\n/**\n * The hosting service for the server.\n */\nexport class HostingService implements IHostingComponent {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<HostingService>();\n\n\t/**\n\t * The prefix to use for encrypted query parameters when encrypting/decrypting.\n\t * This is used to identify which query parameters have been encrypted.\n\t * The actual key used in the query will be \"x-enc-{originalKey}\".\n\t * @internal\n\t */\n\tprivate static readonly _KEY_PREFIX = \"x-enc-\";\n\n\t/**\n\t * The default name for the tenant token query parameter.\n\t * @internal\n\t */\n\tprivate static readonly _DEFAULT_TENANT_TOKEN_NAME: string = \"tenant-token\";\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 tenant admin component.\n\t * @internal\n\t */\n\tprivate readonly _tenantAdminComponentType?: string;\n\n\t/**\n\t * The vault connector type.\n\t * @internal\n\t */\n\tprivate readonly _vaultConnectorType?: string;\n\n\t/**\n\t * The local origin URL e.g. \"http://localhost:3000\".\n\t * @internal\n\t */\n\tprivate readonly _localOrigin: string;\n\n\t/**\n\t * The APIs public base URL e.g. \"https://api.example.com:1234\".\n\t * @internal\n\t */\n\tprivate readonly _publicOrigin?: string;\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 * The query param name carrying the encrypted tenant token.\n\t * @internal\n\t */\n\tprivate readonly _tenantTokenName: 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 HostingService.\n\t * @param options The options to create the service.\n\t */\n\tconstructor(options: IHostingServiceConstructorOptions) {\n\t\tGuards.object(HostingService.CLASS_NAME, nameof(options), options);\n\t\tGuards.object(HostingService.CLASS_NAME, nameof(options.config), options.config);\n\t\tGuards.stringValue(\n\t\t\tHostingService.CLASS_NAME,\n\t\t\tnameof(options.config.localOrigin),\n\t\t\toptions.config.localOrigin\n\t\t);\n\t\tthis._tenantAdminComponentType = options?.tenantAdminComponentType ?? \"tenant-admin\";\n\t\tthis._vaultConnectorType = options?.vaultConnectorType ?? \"vault\";\n\t\tthis._localOrigin = options.config.localOrigin;\n\t\tthis._publicOrigin = options.config.publicOrigin;\n\t\tthis._paramEncryptionKeyName =\n\t\t\toptions.config.paramEncryptionKeyName ?? HostingService._DEFAULT_PARAM_ENCRYPTION_KEY_NAME;\n\t\tthis._tenantTokenName =\n\t\t\toptions.config.tenantTokenName ?? HostingService._DEFAULT_TENANT_TOKEN_NAME;\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 HostingService.CLASS_NAME;\n\t}\n\n\t/**\n\t * The component needs to be started when the node is initialized.\n\t * @param nodeLoggingComponentType The node logging component type.\n\t * @returns Nothing.\n\t */\n\tpublic async start(nodeLoggingComponentType?: string): Promise<void> {\n\t\tconst contextIds = await ContextIdStore.getContextIds();\n\t\tthis._nodeId = contextIds?.[ContextIdKeys.Node];\n\t}\n\n\t/**\n\t * Get the public origin for the hosting.\n\t * @param serverRequestUrl The url of the current server request if there is one.\n\t * @returns The public origin.\n\t */\n\tpublic async getPublicOrigin(serverRequestUrl?: string): Promise<string> {\n\t\t// If there is a tenant admin component, and the context has a tenant id set.\n\t\t// set if the tenant has a specific public origin.\n\t\tconst contextIds = await ContextIdStore.getContextIds();\n\t\tconst tenantId = contextIds?.[ContextIdKeys.Tenant];\n\t\tlet tenantPublicOrigin;\n\t\tif (Is.stringValue(tenantId)) {\n\t\t\ttenantPublicOrigin = await this.getTenantOrigin(tenantId);\n\t\t}\n\n\t\tconst serverRequestOrigin = Is.stringValue(serverRequestUrl)\n\t\t\t? HttpUrlHelper.extractOrigin(serverRequestUrl)\n\t\t\t: undefined;\n\n\t\t// If there is a tenant public origin, return it.\n\t\t// If not and the config has a public origin, return it.\n\t\t// Otherwise, use the server request URL if provided\n\t\t// else fallback to local origin.\n\t\treturn tenantPublicOrigin ?? this._publicOrigin ?? serverRequestOrigin ?? this._localOrigin;\n\t}\n\n\t/**\n\t * Get the public origin for the tenant if one exists.\n\t * @param tenantId The tenant identifier.\n\t * @returns The public origin for the tenant.\n\t */\n\tpublic async getTenantOrigin(tenantId: string): Promise<string | undefined> {\n\t\tGuards.stringHexLength(HostingService.CLASS_NAME, nameof(tenantId), tenantId, 32);\n\n\t\tconst tenantAdminComponent = ComponentFactory.getIfExists<ITenantAdminComponent>(\n\t\t\tthis._tenantAdminComponentType\n\t\t);\n\n\t\tif (Is.empty(tenantAdminComponent)) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst tenant = await tenantAdminComponent.get(tenantId);\n\t\treturn tenant?.publicOrigin;\n\t}\n\n\t/**\n\t * Build a public url based on the public origin and the url provided.\n\t * @param url The url to build upon the public origin.\n\t * @returns The full url based on the public origin.\n\t */\n\tpublic async buildPublicUrl(url: string): Promise<string> {\n\t\tconst publicOrigin = await this.getPublicOrigin(url);\n\t\treturn HttpUrlHelper.replaceOrigin(url, publicOrigin);\n\t}\n\n\t/**\n\t * Add encrypted key/value pairs to a URL's query string.\n\t * Existing query parameters on the URL are preserved; the provided params are\n\t * merged in and then encrypted before being written back to the URL.\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 addEncryptedParamsToUrl(url: string, params: IHttpRequestQuery): Promise<string> {\n\t\tconst urlObj = new URL(url);\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 * 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 getDecryptedParamsFromQueryParams(\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 the tenant id and append it as a query parameter to the given URL.\n\t * @param url The URL to append the encrypted tenant token to.\n\t * @param tenantId The tenant identifier to encrypt and add.\n\t * @returns The URL with the encrypted tenant token added as a query parameter.\n\t */\n\tpublic async addTenantTokenToUrl(url: string, tenantId: string): Promise<string> {\n\t\treturn this.addEncryptedParamsToUrl(url, { [this._tenantTokenName]: tenantId });\n\t}\n\n\t/**\n\t * Get the tenant token from the query parameters.\n\t * @param queryParams The HTTP request query containing the parameters.\n\t * @returns The tenant token if it exists.\n\t */\n\tpublic async getTenantTokenFromQueryParams(\n\t\tqueryParams: IHttpRequestQuery | undefined\n\t): Promise<string | undefined> {\n\t\tconst decrypted = await this.getDecryptedParamsFromQueryParams(queryParams, [\n\t\t\tthis._tenantTokenName\n\t\t]);\n\t\treturn decrypted[this._tenantTokenName];\n\t}\n\n\t/**\n\t * Encrypt query parameters using the hosting component's encryption mechanism.\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[`${HostingService._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 using the hosting component's encryption mechanism.\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(HostingService._KEY_PREFIX)) {\n\t\t\t\tconst originalKey = key.slice(HostingService._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 using the hosting component's encryption mechanism.\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(HostingService.CLASS_NAME, nameof(paramValue), paramValue);\n\n\t\tconst vaultConnector = VaultConnectorFactory.getIfExists(this._vaultConnectorType);\n\t\tif (Is.empty(vaultConnector) || Is.empty(this._nodeId)) {\n\t\t\tthrow new GeneralError(HostingService.CLASS_NAME, \"encryptionUnavailable\");\n\t\t}\n\n\t\ttry {\n\t\t\t// Add a salt to the encryption to ensure that the same value encrypted multiple times will yield different results,\n\t\t\t// preventing rainbow table attacks.\n\t\t\tconst salt = RandomHelper.generate(8);\n\n\t\t\tconst encryptedParamValue = await 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(HostingService.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\tHostingService.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 using the hosting component's encryption mechanism.\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(HostingService.CLASS_NAME, nameof(encryptedValue), encryptedValue);\n\n\t\tconst vaultConnector = VaultConnectorFactory.getIfExists(this._vaultConnectorType);\n\t\tif (Is.empty(vaultConnector) || Is.empty(this._nodeId)) {\n\t\t\tthrow new GeneralError(HostingService.CLASS_NAME, \"decryptionUnavailable\");\n\t\t}\n\n\t\ttry {\n\t\t\tconst encryptedBytes = Converter.base64UrlToBytes(encryptedValue);\n\t\t\tconst decryptedBytes = await 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(HostingService.CLASS_NAME, \"decryptionFailed\");\n\t\t\t}\n\n\t\t\t// The decrypted value is expected to have the salt as the first 8 bytes, which we need to remove before returning the original value.\n\t\t\treturn Converter.bytesToUtf8(decryptedBytes.slice(8));\n\t\t} catch (err) {\n\t\t\tthrow new GeneralError(\n\t\t\t\tHostingService.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"]}

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

@@ -1 +1 @@
-{"version":3,"file":"IHostingServiceConfig.js","sourceRoot":"","sources":["../../../src/models/IHostingServiceConfig.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 hosting service.\n */\nexport interface IHostingServiceConfig {\n\t/**\n\t * The local origin, must be provided as a fallback e.g. http://localhost:1234.\n\t */\n\tlocalOrigin: string;\n\n\t/**\n\t * The APIs public base URL e.g. \"https://api.example.com:1234\".\n\t */\n\tpublicOrigin?: string;\n}\n"]}
+{"version":3,"file":"IHostingServiceConfig.js","sourceRoot":"","sources":["../../../src/models/IHostingServiceConfig.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 hosting service.\n */\nexport interface IHostingServiceConfig {\n\t/**\n\t * The local origin, must be provided as a fallback e.g. http://localhost:1234.\n\t */\n\tlocalOrigin: string;\n\n\t/**\n\t * The APIs public base URL e.g. \"https://api.example.com:1234\".\n\t */\n\tpublicOrigin?: string;\n\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 * The query param name to look for the encrypted tenant token.\n\t * @default tenant-token\n\t */\n\ttenantTokenName?: string;\n}\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"IHostingServiceConstructorOptions.js","sourceRoot":"","sources":["../../../src/models/IHostingServiceConstructorOptions.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IHostingServiceConfig } from \"./IHostingServiceConfig.js\";\n\n/**\n * Options for the IHostingService constructor.\n */\nexport interface IHostingServiceConstructorOptions {\n\t/**\n\t * The tenant admin component type.\n\t * @default tenant-admin\n\t */\n\ttenantAdminComponentType?: string;\n\n\t/**\n\t * The configuration for the service.\n\t */\n\tconfig: IHostingServiceConfig;\n}\n"]}
+{"version":3,"file":"IHostingServiceConstructorOptions.js","sourceRoot":"","sources":["../../../src/models/IHostingServiceConstructorOptions.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IHostingServiceConfig } from \"./IHostingServiceConfig.js\";\n\n/**\n * Options for the IHostingService constructor.\n */\nexport interface IHostingServiceConstructorOptions {\n\t/**\n\t * The tenant admin component type.\n\t * @default tenant-admin\n\t */\n\ttenantAdminComponentType?: string;\n\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: IHostingServiceConfig;\n}\n"]}

package/dist/types/hostingService.d.ts

@@ -1,4 +1,4 @@
-import { type IHostingComponent } from "@twin.org/api-models";
+import { type IHostingComponent, type IHttpRequestQuery } from "@twin.org/api-models";
 import type { IHostingServiceConstructorOptions } from "./models/IHostingServiceConstructorOptions.js";
 /**
  * The hosting service for the server.
@@ -18,6 +18,12 @@ export declare class HostingService implements IHostingComponent {
      * @returns The class name of the component.
      */
     className(): string;
+    /**
+     * The component needs to be started when the node is initialized.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns Nothing.
+     */
+    start(nodeLoggingComponentType?: string): Promise<void>;
     /**
      * Get the public origin for the hosting.
      * @param serverRequestUrl The url of the current server request if there is one.
@@ -36,4 +42,59 @@ export declare class HostingService implements IHostingComponent {
      * @returns The full url based on the public origin.
      */
     buildPublicUrl(url: string): Promise<string>;
+    /**
+     * Add encrypted key/value pairs to a URL's query string.
+     * Existing query parameters on the URL are preserved; the provided params are
+     * merged in and then encrypted before being written back to the URL.
+     * @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.
+     */
+    addEncryptedParamsToUrl(url: string, params: IHttpRequestQuery): Promise<string>;
+    /**
+     * 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.
+     */
+    getDecryptedParamsFromQueryParams(queryParams: IHttpRequestQuery | undefined, keys: string[]): Promise<IHttpRequestQuery>;
+    /**
+     * Encrypt the tenant id and append it as a query parameter to the given URL.
+     * @param url The URL to append the encrypted tenant token to.
+     * @param tenantId The tenant identifier to encrypt and add.
+     * @returns The URL with the encrypted tenant token added as a query parameter.
+     */
+    addTenantTokenToUrl(url: string, tenantId: string): Promise<string>;
+    /**
+     * Get the tenant token from the query parameters.
+     * @param queryParams The HTTP request query containing the parameters.
+     * @returns The tenant token if it exists.
+     */
+    getTenantTokenFromQueryParams(queryParams: IHttpRequestQuery | undefined): Promise<string | undefined>;
+    /**
+     * Encrypt query parameters using the hosting component's encryption mechanism.
+     * @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 using the hosting component's encryption mechanism.
+     * @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 using the hosting component's encryption mechanism.
+     * @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 using the hosting component's encryption mechanism.
+     * @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>;
 }

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

@@ -10,4 +10,14 @@ export interface IHostingServiceConfig {
      * The APIs public base URL e.g. "https://api.example.com:1234".
      */
     publicOrigin?: string;
+    /**
+     * The name of the key to retrieve from the vault for encryption/decryption of parameters.
+     * @default param-encryption
+     */
+    paramEncryptionKeyName?: string;
+    /**
+     * The query param name to look for the encrypted tenant token.
+     * @default tenant-token
+     */
+    tenantTokenName?: string;
 }

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

@@ -8,6 +8,11 @@ export interface IHostingServiceConstructorOptions {
      * @default tenant-admin
      */
     tenantAdminComponentType?: string;
+    /**
+     * The vault connector type.
+     * @default vault
+     */
+    vaultConnectorType?: string;
     /**
      * The configuration for the service.
      */

package/docs/changelog.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.0.3-next.29](https://github.com/twinfoundation/twin-api/compare/api-service-v0.0.3-next.28...api-service-v0.0.3-next.29) (2026-05-01)
+
+
+### Features
+
+* hosting service ([#109](https://github.com/twinfoundation/twin-api/issues/109)) ([985bf1f](https://github.com/twinfoundation/twin-api/commit/985bf1f5c07b09ecb800df7120bc2422ac7a6d25))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.28 to 0.0.3-next.29
+
 ## [0.0.3-next.28](https://github.com/twinfoundation/twin-api/compare/api-service-v0.0.3-next.27...api-service-v0.0.3-next.28) (2026-04-30)
 
 

package/docs/reference/classes/HostingService.md

@@ -54,6 +54,32 @@ The class name of the component.
 
 ***
 
+### start() {#start}
+
+> **start**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
+
+The component needs to be started when the node is initialized.
+
+#### Parameters
+
+##### nodeLoggingComponentType?
+
+`string`
+
+The node logging component type.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IHostingComponent.start`
+
+***
+
 ### getPublicOrigin() {#getpublicorigin}
 
 > **getPublicOrigin**(`serverRequestUrl?`): `Promise`\<`string`\>
@@ -129,3 +155,243 @@ The full url based on the public origin.
 #### Implementation of
 
 `IHostingComponent.buildPublicUrl`
+
+***
+
+### addEncryptedParamsToUrl() {#addencryptedparamstourl}
+
+> **addEncryptedParamsToUrl**(`url`, `params`): `Promise`\<`string`\>
+
+Add encrypted key/value pairs to a URL's query string.
+Existing query parameters on the URL are preserved; the provided params are
+merged in and then encrypted before being written back to the URL.
+
+#### Parameters
+
+##### url
+
+`string`
+
+The base URL to add parameters to.
+
+##### params
+
+`IHttpRequestQuery`
+
+The key/value pairs to encrypt and append.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The URL with the encrypted parameters added.
+
+#### Implementation of
+
+`IHostingComponent.addEncryptedParamsToUrl`
+
+***
+
+### getDecryptedParamsFromQueryParams() {#getdecryptedparamsfromqueryparams}
+
+> **getDecryptedParamsFromQueryParams**(`queryParams`, `keys`): `Promise`\<`IHttpRequestQuery`\>
+
+Decrypt specified keys from a query parameter object and return their plain-text values.
+
+#### Parameters
+
+##### queryParams
+
+`IHttpRequestQuery` \| `undefined`
+
+The HTTP request query containing the encrypted parameters.
+
+##### keys
+
+`string`[]
+
+The keys to decrypt.
+
+#### Returns
+
+`Promise`\<`IHttpRequestQuery`\>
+
+A map of the decrypted key/value pairs that were present.
+
+#### Implementation of
+
+`IHostingComponent.getDecryptedParamsFromQueryParams`
+
+***
+
+### addTenantTokenToUrl() {#addtenanttokentourl}
+
+> **addTenantTokenToUrl**(`url`, `tenantId`): `Promise`\<`string`\>
+
+Encrypt the tenant id and append it as a query parameter to the given URL.
+
+#### Parameters
+
+##### url
+
+`string`
+
+The URL to append the encrypted tenant token to.
+
+##### tenantId
+
+`string`
+
+The tenant identifier to encrypt and add.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The URL with the encrypted tenant token added as a query parameter.
+
+#### Implementation of
+
+`IHostingComponent.addTenantTokenToUrl`
+
+***
+
+### getTenantTokenFromQueryParams() {#gettenanttokenfromqueryparams}
+
+> **getTenantTokenFromQueryParams**(`queryParams`): `Promise`\<`string` \| `undefined`\>
+
+Get the tenant token from the query parameters.
+
+#### Parameters
+
+##### queryParams
+
+`IHttpRequestQuery` \| `undefined`
+
+The HTTP request query containing the parameters.
+
+#### Returns
+
+`Promise`\<`string` \| `undefined`\>
+
+The tenant token if it exists.
+
+#### Implementation of
+
+`IHostingComponent.getTenantTokenFromQueryParams`
+
+***
+
+### encryptQueryParams() {#encryptqueryparams}
+
+> **encryptQueryParams**(`httpRequestQuery`, `keys`): `Promise`\<`void`\>
+
+Encrypt query parameters using the hosting component's encryption mechanism.
+
+#### Parameters
+
+##### httpRequestQuery
+
+`IHttpRequestQuery` \| `undefined`
+
+The HTTP request query containing the parameters to encrypt.
+
+##### keys
+
+`string`[]
+
+The keys of the parameters to encrypt.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the query parameters have been encrypted.
+
+#### Implementation of
+
+`IHostingComponent.encryptQueryParams`
+
+***
+
+### decryptQueryParams() {#decryptqueryparams}
+
+> **decryptQueryParams**(`httpRequestQuery`, `keys`): `Promise`\<`void`\>
+
+Decrypt query parameters using the hosting component's encryption mechanism.
+
+#### Parameters
+
+##### httpRequestQuery
+
+`IHttpRequestQuery` \| `undefined`
+
+The HTTP request query containing the encrypted values.
+
+##### keys
+
+`string`[]
+
+The keys of the parameters to decrypt.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the query parameters have been decrypted.
+
+#### Implementation of
+
+`IHostingComponent.decryptQueryParams`
+
+***
+
+### encryptParam() {#encryptparam}
+
+> **encryptParam**(`paramValue`): `Promise`\<`string`\>
+
+Encrypt a parameter value using the hosting component's encryption mechanism.
+
+#### Parameters
+
+##### paramValue
+
+`string`
+
+The value of the parameter to encrypt.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+A promise that resolves to the encrypted value of the parameter.
+
+#### Implementation of
+
+`IHostingComponent.encryptParam`
+
+***
+
+### decryptParam() {#decryptparam}
+
+> **decryptParam**(`encryptedValue`): `Promise`\<`string`\>
+
+Decrypt a parameter value using the hosting component's encryption mechanism.
+
+#### Parameters
+
+##### encryptedValue
+
+`string`
+
+The encrypted value of the parameter.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+A promise that resolves to the decrypted value of the parameter.
+
+#### Implementation of
+
+`IHostingComponent.decryptParam`

package/docs/reference/interfaces/IHostingServiceConfig.md

@@ -17,3 +17,31 @@ The local origin, must be provided as a fallback e.g. http://localhost:1234.
 > `optional` **publicOrigin?**: `string`
 
 The APIs public base URL e.g. "https://api.example.com:1234".
+
+***
+
+### paramEncryptionKeyName? {#paramencryptionkeyname}
+
+> `optional` **paramEncryptionKeyName?**: `string`
+
+The name of the key to retrieve from the vault for encryption/decryption of parameters.
+
+#### Default
+
+```ts
+param-encryption
+```
+
+***
+
+### tenantTokenName? {#tenanttokenname}
+
+> `optional` **tenantTokenName?**: `string`
+
+The query param name to look for the encrypted tenant token.
+
+#### Default
+
+```ts
+tenant-token
+```

package/docs/reference/interfaces/IHostingServiceConstructorOptions.md

@@ -18,6 +18,20 @@ tenant-admin
 
 ***
 
+### vaultConnectorType? {#vaultconnectortype}
+
+> `optional` **vaultConnectorType?**: `string`
+
+The vault connector type.
+
+#### Default
+
+```ts
+vault
+```
+
+***
+
 ### config {#config}
 
 > **config**: [`IHostingServiceConfig`](IHostingServiceConfig.md)

package/locales/en.json

@@ -1 +1,10 @@
-{}
+{
+	"error": {
+		"hostingService": {
+			"encryptionUnavailable": "Encryption is unavailable because no vault connector is configured",
+			"decryptionUnavailable": "Decryption is unavailable because no vault connector is configured",
+			"encryptionFailed": "An error occurred during encryption",
+			"decryptionFailed": "An error occurred during decryption"
+		}
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/api-service",
-	"version": "0.0.3-next.28",
+	"version": "0.0.3-next.29",
 	"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.28",
+		"@twin.org/api-models": "0.0.3-next.29",
 		"@twin.org/context": "next",
 		"@twin.org/core": "next",
 		"@twin.org/nameof": "next",
+		"@twin.org/vault-models": "next",
 		"@twin.org/web": "next"
 	},
 	"main": "./dist/es/index.js",