@twin.org/api-tenant-processor 0.0.3-next.27 → 0.0.3-next.28

package/dist/es/index.js

@@ -20,4 +20,5 @@ export * from "./tenantIdContextIdHandler.js";
 export * from "./tenantProcessor.js";
 export * from "./tenantRoutes.js";
 export * from "./utils/tenantIdHelper.js";
+export * from "./utils/tenantUrlHelper.js";
 //# sourceMappingURL=index.js.map

package/dist/es/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sCAAsC,CAAC;AACrD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,uCAAuC,CAAC;AACtD,cAAc,iDAAiD,CAAC;AAChE,cAAc,oCAAoC,CAAC;AACnD,cAAc,oCAAoC,CAAC;AACnD,cAAc,qCAAqC,CAAC;AACpD,cAAc,sCAAsC,CAAC;AACrD,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,mDAAmD,CAAC;AAClE,cAAc,oCAAoC,CAAC;AACnD,cAAc,gDAAgD,CAAC;AAC/D,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./entities/tenant.js\";\nexport * from \"./models/api/ITenantCreateRequest.js\";\nexport * from \"./models/api/ITenantGetByApiKeyRequest.js\";\nexport * from \"./models/api/ITenantGetByIdRequest.js\";\nexport * from \"./models/api/ITenantGetByPublicOriginRequest.js\";\nexport * from \"./models/api/ITenantGetResponse.js\";\nexport * from \"./models/api/ITenantListRequest.js\";\nexport * from \"./models/api/ITenantListResponse.js\";\nexport * from \"./models/api/ITenantRemoveRequest.js\";\nexport * from \"./models/api/ITenantUpdateRequest.js\";\nexport * from \"./models/ITenantAdminServiceConfig.js\";\nexport * from \"./models/ITenantAdminServiceConstructorOptions.js\";\nexport * from \"./models/ITenantProcessorConfig.js\";\nexport * from \"./models/ITenantProcessorConstructorOptions.js\";\nexport * from \"./schema.js\";\nexport * from \"./tenantAdminService.js\";\nexport * from \"./tenantIdContextIdHandler.js\";\nexport * from \"./tenantProcessor.js\";\nexport * from \"./tenantRoutes.js\";\nexport * from \"./utils/tenantIdHelper.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sCAAsC,CAAC;AACrD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,uCAAuC,CAAC;AACtD,cAAc,iDAAiD,CAAC;AAChE,cAAc,oCAAoC,CAAC;AACnD,cAAc,oCAAoC,CAAC;AACnD,cAAc,qCAAqC,CAAC;AACpD,cAAc,sCAAsC,CAAC;AACrD,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,mDAAmD,CAAC;AAClE,cAAc,oCAAoC,CAAC;AACnD,cAAc,gDAAgD,CAAC;AAC/D,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./entities/tenant.js\";\nexport * from \"./models/api/ITenantCreateRequest.js\";\nexport * from \"./models/api/ITenantGetByApiKeyRequest.js\";\nexport * from \"./models/api/ITenantGetByIdRequest.js\";\nexport * from \"./models/api/ITenantGetByPublicOriginRequest.js\";\nexport * from \"./models/api/ITenantGetResponse.js\";\nexport * from \"./models/api/ITenantListRequest.js\";\nexport * from \"./models/api/ITenantListResponse.js\";\nexport * from \"./models/api/ITenantRemoveRequest.js\";\nexport * from \"./models/api/ITenantUpdateRequest.js\";\nexport * from \"./models/ITenantAdminServiceConfig.js\";\nexport * from \"./models/ITenantAdminServiceConstructorOptions.js\";\nexport * from \"./models/ITenantProcessorConfig.js\";\nexport * from \"./models/ITenantProcessorConstructorOptions.js\";\nexport * from \"./schema.js\";\nexport * from \"./tenantAdminService.js\";\nexport * from \"./tenantIdContextIdHandler.js\";\nexport * from \"./tenantProcessor.js\";\nexport * from \"./tenantRoutes.js\";\nexport * from \"./utils/tenantIdHelper.js\";\nexport * from \"./utils/tenantUrlHelper.js\";\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"ITenantProcessorConfig.js","sourceRoot":"","sources":["../../../src/models/ITenantProcessorConfig.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Configuration for the tenant processor\n */\nexport interface ITenantProcessorConfig {\n\t/**\n\t * The key to look for in the header or query params for the api key.\n\t * @default x-api-key\n\t */\n\tapiKeyName?: string;\n}\n"]}
+{"version":3,"file":"ITenantProcessorConfig.js","sourceRoot":"","sources":["../../../src/models/ITenantProcessorConfig.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Configuration for the tenant processor\n */\nexport interface ITenantProcessorConfig {\n\t/**\n\t * The key to look for in the header or query params for the api key.\n\t * @default x-api-key\n\t */\n\tapiKeyName?: string;\n\n\t/**\n\t * The name of the symmetric key in the vault used to encrypt/decrypt tenant tokens.\n\t * @default tenant-token-encryption\n\t */\n\tsigningKeyName?: string;\n\n\t/**\n\t * The query param name to look for the encrypted tenant token.\n\t * @default tenantToken\n\t */\n\ttenantTokenName?: string;\n}\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"ITenantProcessorConstructorOptions.js","sourceRoot":"","sources":["../../../src/models/ITenantProcessorConstructorOptions.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { ITenantProcessorConfig } from \"./ITenantProcessorConfig.js\";\n\n/**\n * Options for the Tenant Processor constructor.\n */\nexport interface ITenantProcessorConstructorOptions {\n\t/**\n\t * The entity storage for the tenants.\n\t * @default tenant\n\t */\n\ttenantEntityStorageType?: string;\n\n\t/**\n\t * Configuration for the processor.\n\t */\n\tconfig?: ITenantProcessorConfig;\n}\n"]}
+{"version":3,"file":"ITenantProcessorConstructorOptions.js","sourceRoot":"","sources":["../../../src/models/ITenantProcessorConstructorOptions.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { ITenantProcessorConfig } from \"./ITenantProcessorConfig.js\";\n\n/**\n * Options for the Tenant Processor constructor.\n */\nexport interface ITenantProcessorConstructorOptions {\n\t/**\n\t * The entity storage for the tenants.\n\t * @default tenant\n\t */\n\ttenantEntityStorageType?: string;\n\n\t/**\n\t * The vault connector used to decrypt tenant tokens. Only resolved when\n\t * `config.signingKeyName` is set.\n\t * @default vault\n\t */\n\tvaultConnectorType?: string;\n\n\t/**\n\t * Configuration for the processor.\n\t */\n\tconfig?: ITenantProcessorConfig;\n}\n"]}

package/dist/es/tenantProcessor.js

@@ -1,10 +1,12 @@
 // Copyright 2025 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 import { HttpErrorHelper } from "@twin.org/api-models";
-import { ContextIdKeys } from "@twin.org/context";
+import { ContextIdHelper, ContextIdKeys, ContextIdStore } from "@twin.org/context";
 import { BaseError, Is, UnauthorizedError } from "@twin.org/core";
 import { EntityStorageConnectorFactory } from "@twin.org/entity-storage-models";
+import { VaultConnectorFactory } from "@twin.org/vault-models";
 import { HttpStatusCode } from "@twin.org/web";
+import { TenantUrlHelper } from "./utils/tenantUrlHelper.js";
 /**
  * Handles incoming api keys and maps them to tenant ids.
  */
@@ -28,6 +30,27 @@ export class TenantProcessor {
      * @internal
      */
     _apiKeyName;
+    /**
+     * The query param name carrying the encrypted tenant token.
+     * @internal
+     */
+    _tenantTokenName;
+    /**
+     * The vault connector used to decrypt tenant tokens.
+     * Only set when `signingKeyName` is configured.
+     * @internal
+     */
+    _vaultConnector;
+    /**
+     * The name of the symmetric key in the vault used to decrypt tenant tokens.
+     * @internal
+     */
+    _signingKeyName;
+    /**
+     * The node identity, captured at start.
+     * @internal
+     */
+    _nodeId;
     /**
      * Create a new instance of NodeTenantProcessor.
      * @param options Options for the processor.
@@ -35,6 +58,15 @@ export class TenantProcessor {
     constructor(options) {
         this._entityStorageConnector = EntityStorageConnectorFactory.get(options?.tenantEntityStorageType ?? "tenant");
         this._apiKeyName = options?.config?.apiKeyName ?? TenantProcessor.DEFAULT_API_KEY_NAME;
+        this._tenantTokenName =
+            options?.config?.tenantTokenName ?? TenantUrlHelper.DEFAULT_TENANT_TOKEN_NAME;
+        // Vault is resolved only when a connector type is explicitly passed, following
+        if (Is.stringValue(options?.vaultConnectorType)) {
+            this._vaultConnector = VaultConnectorFactory.get(options.vaultConnectorType);
+        }
+        if (Is.stringValue(options?.config?.signingKeyName)) {
+            this._signingKeyName = options.config.signingKeyName;
+        }
     }
     /**
      * Returns the class name of the component.
@@ -43,6 +75,21 @@ export class TenantProcessor {
     className() {
         return TenantProcessor.CLASS_NAME;
     }
+    /**
+     * The processor needs to be started when the application is initialized so that
+     * the node identity is available for vault key resolution. Only required when
+     * the encrypted-token path is wired (i.e. `signingKeyName` is configured).
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns Nothing.
+     */
+    async start(nodeLoggingComponentType) {
+        if (Is.empty(this._vaultConnector) || Is.empty(this._signingKeyName)) {
+            return;
+        }
+        const contextIds = await ContextIdStore.getContextIds();
+        ContextIdHelper.guard(contextIds, ContextIdKeys.Node);
+        this._nodeId = contextIds[ContextIdKeys.Node];
+    }
     /**
      * Pre process the REST request for the specified route.
      * @param request The incoming request.
@@ -52,37 +99,96 @@ export class TenantProcessor {
      * @param processorState The state handed through the processors.
      */
     async pre(request, response, route, contextIds, processorState) {
-        if (!Is.empty(route) && !(route.skipTenant ?? false)) {
-            const apiKey = request.headers?.[this._apiKeyName] ?? request.query?.[this._apiKeyName];
-            let errorResponse;
-            if (Is.stringValue(apiKey)) {
-                try {
-                    const nodeTenant = await this._entityStorageConnector.get(apiKey, "apiKey");
-                    if (Is.empty(nodeTenant)) {
-                        errorResponse = new UnauthorizedError(TenantProcessor.CLASS_NAME, "apiKeyNotFound", {
-                            key: apiKey
-                        });
-                    }
-                    else {
-                        contextIds[ContextIdKeys.Tenant] = nodeTenant.id;
-                        if (Is.stringValue(nodeTenant.publicOrigin)) {
-                            processorState.publicOrigin = nodeTenant.publicOrigin;
-                        }
-                    }
-                }
-                catch (err) {
-                    errorResponse = BaseError.fromError(err);
+        const tenantToken = request.query?.[this._tenantTokenName];
+        const tokenDecodable = Is.stringValue(tenantToken) &&
+            !Is.empty(this._vaultConnector) &&
+            Is.stringValue(this._signingKeyName);
+        // skipTenant routes (cross-node trust JWT routes) bypass api-key resolution
+        // accept an encrypted ?tenantToken= query param so cross-tenant catalogue/DSP/PNP routing reaches the publisher's tenant context
+        if (Is.empty(route) || (route.skipTenant ?? false)) {
+            if (tokenDecodable) {
+                const errorResponse = await this.resolveByTenantToken(tenantToken, contextIds, processorState);
+                if (!Is.empty(errorResponse)) {
+                    HttpErrorHelper.buildResponse(response, errorResponse, HttpStatusCode.unauthorized);
                 }
             }
-            else {
-                errorResponse = new UnauthorizedError(TenantProcessor.CLASS_NAME, "missingApiKey", {
-                    keyName: this._apiKeyName
+            return;
+        }
+        const apiKey = request.headers?.[this._apiKeyName] ?? request.query?.[this._apiKeyName];
+        let errorResponse;
+        if (Is.stringValue(apiKey)) {
+            errorResponse = await this.resolveByApiKey(apiKey, contextIds, processorState);
+        }
+        else if (tokenDecodable) {
+            errorResponse = await this.resolveByTenantToken(tenantToken, contextIds, processorState);
+        }
+        else {
+            errorResponse = new UnauthorizedError(TenantProcessor.CLASS_NAME, "missingApiKey", {
+                keyName: this._apiKeyName
+            });
+        }
+        if (!Is.empty(errorResponse)) {
+            HttpErrorHelper.buildResponse(response, errorResponse, HttpStatusCode.unauthorized);
+        }
+    }
+    /**
+     * Resolve the tenant context from an api key.
+     * @param apiKey The api key sent by the caller.
+     * @param contextIds The context IDs of the request.
+     * @param processorState The state handed through the processors.
+     * @returns An error to surface, or undefined on success.
+     * @internal
+     */
+    async resolveByApiKey(apiKey, contextIds, processorState) {
+        try {
+            const nodeTenant = await this._entityStorageConnector.get(apiKey, "apiKey");
+            if (Is.empty(nodeTenant)) {
+                return new UnauthorizedError(TenantProcessor.CLASS_NAME, "apiKeyNotFound", {
+                    key: apiKey
+                });
+            }
+            contextIds[ContextIdKeys.Tenant] = nodeTenant.id;
+            if (Is.stringValue(nodeTenant.publicOrigin)) {
+                processorState.publicOrigin = nodeTenant.publicOrigin;
+            }
+        }
+        catch (err) {
+            return BaseError.fromError(err);
+        }
+    }
+    /**
+     * Resolve the tenant context from an encrypted tenant token query param.
+     * @param tenantToken The encrypted tenant token.
+     * @param contextIds The context IDs of the request.
+     * @param processorState The state handed through the processors.
+     * @returns An error to surface, or undefined on success.
+     * @internal
+     */
+    async resolveByTenantToken(tenantToken, contextIds, processorState) {
+        let tenantId;
+        try {
+            tenantId = await TenantUrlHelper.decrypt(tenantToken, this._vaultConnector, `${this._nodeId}/${this._signingKeyName}`);
+        }
+        catch {
+            return new UnauthorizedError(TenantProcessor.CLASS_NAME, "tenantTokenInvalid", {
+                token: tenantToken
+            });
+        }
+        try {
+            const nodeTenant = await this._entityStorageConnector.get(tenantId);
+            if (Is.empty(nodeTenant)) {
+                return new UnauthorizedError(TenantProcessor.CLASS_NAME, "tenantTokenNotFound", {
+                    tenantId
                 });
             }
-            if (!Is.empty(errorResponse)) {
-                HttpErrorHelper.buildResponse(response, errorResponse, HttpStatusCode.unauthorized);
+            contextIds[ContextIdKeys.Tenant] = nodeTenant.id;
+            if (Is.stringValue(nodeTenant.publicOrigin)) {
+                processorState.publicOrigin = nodeTenant.publicOrigin;
             }
         }
+        catch (err) {
+            return BaseError.fromError(err);
+        }
     }
 }
 //# sourceMappingURL=tenantProcessor.js.map

package/dist/es/tenantProcessor.js.map

@@ -1 +1 @@
-{"version":3,"file":"tenantProcessor.js","sourceRoot":"","sources":["../../src/tenantProcessor.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EACN,eAAe,EAKf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,aAAa,EAAoB,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAAE,SAAS,EAAe,EAAE,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC/E,OAAO,EACN,6BAA6B,EAE7B,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAI/C;;GAEG;AACH,MAAM,OAAO,eAAe;IAC3B;;;OAGG;IACI,MAAM,CAAU,oBAAoB,GAAW,WAAW,CAAC;IAElE;;OAEG;IACI,MAAM,CAAU,UAAU,qBAAqC;IAEtE;;;OAGG;IACc,uBAAuB,CAAkC;IAE1E;;;OAGG;IACc,WAAW,CAAS;IAErC;;;OAGG;IACH,YAAY,OAA4C;QACvD,IAAI,CAAC,uBAAuB,GAAG,6BAA6B,CAAC,GAAG,CAC/D,OAAO,EAAE,uBAAuB,IAAI,QAAQ,CAC5C,CAAC;QACF,IAAI,CAAC,WAAW,GAAG,OAAO,EAAE,MAAM,EAAE,UAAU,IAAI,eAAe,CAAC,oBAAoB,CAAC;IACxF,CAAC;IAED;;;OAGG;IACI,SAAS;QACf,OAAO,eAAe,CAAC,UAAU,CAAC;IACnC,CAAC;IAED;;;;;;;OAOG;IACI,KAAK,CAAC,GAAG,CACf,OAA2B,EAC3B,QAAuB,EACvB,KAA6B,EAC7B,UAAuB,EACvB,cAAyC;QAEzC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,EAAE,CAAC;YACtD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YACxF,IAAI,aAAiC,CAAC;YAEtC,IAAI,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC5B,IAAI,CAAC;oBACJ,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,uBAAuB,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;oBAE5E,IAAI,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;wBAC1B,aAAa,GAAG,IAAI,iBAAiB,CAAC,eAAe,CAAC,UAAU,EAAE,gBAAgB,EAAE;4BACnF,GAAG,EAAE,MAAM;yBACX,CAAC,CAAC;oBACJ,CAAC;yBAAM,CAAC;wBACP,UAAU,CAAC,aAAa,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC,EAAE,CAAC;wBACjD,IAAI,EAAE,CAAC,WAAW,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;4BAC7C,cAAc,CAAC,YAAY,GAAG,UAAU,CAAC,YAAY,CAAC;wBACvD,CAAC;oBACF,CAAC;gBACF,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACd,aAAa,GAAG,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;gBAC1C,CAAC;YACF,CAAC;iBAAM,CAAC;gBACP,aAAa,GAAG,IAAI,iBAAiB,CAAC,eAAe,CAAC,UAAU,EAAE,eAAe,EAAE;oBAClF,OAAO,EAAE,IAAI,CAAC,WAAW;iBACzB,CAAC,CAAC;YACJ,CAAC;YAED,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC;gBAC9B,eAAe,CAAC,aAAa,CAAC,QAAQ,EAAE,aAAa,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;YACrF,CAAC;QACF,CAAC;IACF,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport {\n\tHttpErrorHelper,\n\ttype IBaseRoute,\n\ttype IBaseRouteProcessor,\n\ttype IHttpResponse,\n\ttype IHttpServerRequest\n} from \"@twin.org/api-models\";\nimport { ContextIdKeys, type IContextIds } from \"@twin.org/context\";\nimport { BaseError, type IError, Is, UnauthorizedError } from \"@twin.org/core\";\nimport {\n\tEntityStorageConnectorFactory,\n\ttype IEntityStorageConnector\n} from \"@twin.org/entity-storage-models\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { HttpStatusCode } from \"@twin.org/web\";\nimport type { Tenant } from \"./entities/tenant.js\";\nimport type { ITenantProcessorConstructorOptions } from \"./models/ITenantProcessorConstructorOptions.js\";\n\n/**\n * Handles incoming api keys and maps them to tenant ids.\n */\nexport class TenantProcessor implements IBaseRouteProcessor {\n\t/**\n\t * The default name for the api key header.\n\t * @internal\n\t */\n\tpublic static readonly DEFAULT_API_KEY_NAME: string = \"x-api-key\";\n\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<TenantProcessor>();\n\n\t/**\n\t * The entity storage for api keys.\n\t * @internal\n\t */\n\tprivate readonly _entityStorageConnector: IEntityStorageConnector<Tenant>;\n\n\t/**\n\t * The key in the header to look for the api key.\n\t * @internal\n\t */\n\tprivate readonly _apiKeyName: string;\n\n\t/**\n\t * Create a new instance of NodeTenantProcessor.\n\t * @param options Options for the processor.\n\t */\n\tconstructor(options?: ITenantProcessorConstructorOptions) {\n\t\tthis._entityStorageConnector = EntityStorageConnectorFactory.get(\n\t\t\toptions?.tenantEntityStorageType ?? \"tenant\"\n\t\t);\n\t\tthis._apiKeyName = options?.config?.apiKeyName ?? TenantProcessor.DEFAULT_API_KEY_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 TenantProcessor.CLASS_NAME;\n\t}\n\n\t/**\n\t * Pre process the REST request for the specified route.\n\t * @param request The incoming request.\n\t * @param response The outgoing response.\n\t * @param route The route to process.\n\t * @param contextIds The context IDs of the request.\n\t * @param processorState The state handed through the processors.\n\t */\n\tpublic async pre(\n\t\trequest: IHttpServerRequest,\n\t\tresponse: IHttpResponse,\n\t\troute: IBaseRoute | undefined,\n\t\tcontextIds: IContextIds,\n\t\tprocessorState: { [id: string]: unknown }\n\t): Promise<void> {\n\t\tif (!Is.empty(route) && !(route.skipTenant ?? false)) {\n\t\t\tconst apiKey = request.headers?.[this._apiKeyName] ?? request.query?.[this._apiKeyName];\n\t\t\tlet errorResponse: IError | undefined;\n\n\t\t\tif (Is.stringValue(apiKey)) {\n\t\t\t\ttry {\n\t\t\t\t\tconst nodeTenant = await this._entityStorageConnector.get(apiKey, \"apiKey\");\n\n\t\t\t\t\tif (Is.empty(nodeTenant)) {\n\t\t\t\t\t\terrorResponse = new UnauthorizedError(TenantProcessor.CLASS_NAME, \"apiKeyNotFound\", {\n\t\t\t\t\t\t\tkey: apiKey\n\t\t\t\t\t\t});\n\t\t\t\t\t} else {\n\t\t\t\t\t\tcontextIds[ContextIdKeys.Tenant] = nodeTenant.id;\n\t\t\t\t\t\tif (Is.stringValue(nodeTenant.publicOrigin)) {\n\t\t\t\t\t\t\tprocessorState.publicOrigin = nodeTenant.publicOrigin;\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t} catch (err) {\n\t\t\t\t\terrorResponse = BaseError.fromError(err);\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\terrorResponse = new UnauthorizedError(TenantProcessor.CLASS_NAME, \"missingApiKey\", {\n\t\t\t\t\tkeyName: this._apiKeyName\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tif (!Is.empty(errorResponse)) {\n\t\t\t\tHttpErrorHelper.buildResponse(response, errorResponse, HttpStatusCode.unauthorized);\n\t\t\t}\n\t\t}\n\t}\n}\n"]}
+{"version":3,"file":"tenantProcessor.js","sourceRoot":"","sources":["../../src/tenantProcessor.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport {\n\tHttpErrorHelper,\n\ttype IBaseRoute,\n\ttype IBaseRouteProcessor,\n\ttype IHttpResponse,\n\ttype IHttpServerRequest\n} from \"@twin.org/api-models\";\nimport {\n\tContextIdHelper,\n\tContextIdKeys,\n\tContextIdStore,\n\ttype IContextIds\n} from \"@twin.org/context\";\nimport { BaseError, type IError, Is, UnauthorizedError } from \"@twin.org/core\";\nimport {\n\tEntityStorageConnectorFactory,\n\ttype IEntityStorageConnector\n} from \"@twin.org/entity-storage-models\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { type IVaultConnector, VaultConnectorFactory } from \"@twin.org/vault-models\";\nimport { HttpStatusCode } from \"@twin.org/web\";\nimport type { Tenant } from \"./entities/tenant.js\";\nimport type { ITenantProcessorConstructorOptions } from \"./models/ITenantProcessorConstructorOptions.js\";\nimport { TenantUrlHelper } from \"./utils/tenantUrlHelper.js\";\n\n/**\n * Handles incoming api keys and maps them to tenant ids.\n */\nexport class TenantProcessor implements IBaseRouteProcessor {\n\t/**\n\t * The default name for the api key header.\n\t * @internal\n\t */\n\tpublic static readonly DEFAULT_API_KEY_NAME: string = \"x-api-key\";\n\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<TenantProcessor>();\n\n\t/**\n\t * The entity storage for api keys.\n\t * @internal\n\t */\n\tprivate readonly _entityStorageConnector: IEntityStorageConnector<Tenant>;\n\n\t/**\n\t * The key in the header to look for the api key.\n\t * @internal\n\t */\n\tprivate readonly _apiKeyName: 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 vault connector used to decrypt tenant tokens.\n\t * Only set when `signingKeyName` is configured.\n\t * @internal\n\t */\n\tprivate readonly _vaultConnector?: IVaultConnector;\n\n\t/**\n\t * The name of the symmetric key in the vault used to decrypt tenant tokens.\n\t * @internal\n\t */\n\tprivate readonly _signingKeyName?: 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 NodeTenantProcessor.\n\t * @param options Options for the processor.\n\t */\n\tconstructor(options?: ITenantProcessorConstructorOptions) {\n\t\tthis._entityStorageConnector = EntityStorageConnectorFactory.get(\n\t\t\toptions?.tenantEntityStorageType ?? \"tenant\"\n\t\t);\n\t\tthis._apiKeyName = options?.config?.apiKeyName ?? TenantProcessor.DEFAULT_API_KEY_NAME;\n\t\tthis._tenantTokenName =\n\t\t\toptions?.config?.tenantTokenName ?? TenantUrlHelper.DEFAULT_TENANT_TOKEN_NAME;\n\n\t\t// Vault is resolved only when a connector type is explicitly passed, following\n\t\tif (Is.stringValue(options?.vaultConnectorType)) {\n\t\t\tthis._vaultConnector = VaultConnectorFactory.get(options.vaultConnectorType);\n\t\t}\n\t\tif (Is.stringValue(options?.config?.signingKeyName)) {\n\t\t\tthis._signingKeyName = options.config.signingKeyName;\n\t\t}\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 TenantProcessor.CLASS_NAME;\n\t}\n\n\t/**\n\t * The processor needs to be started when the application is initialized so that\n\t * the node identity is available for vault key resolution. Only required when\n\t * the encrypted-token path is wired (i.e. `signingKeyName` is configured).\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\tif (Is.empty(this._vaultConnector) || Is.empty(this._signingKeyName)) {\n\t\t\treturn;\n\t\t}\n\t\tconst contextIds = await ContextIdStore.getContextIds();\n\t\tContextIdHelper.guard(contextIds, ContextIdKeys.Node);\n\t\tthis._nodeId = contextIds[ContextIdKeys.Node];\n\t}\n\n\t/**\n\t * Pre process the REST request for the specified route.\n\t * @param request The incoming request.\n\t * @param response The outgoing response.\n\t * @param route The route to process.\n\t * @param contextIds The context IDs of the request.\n\t * @param processorState The state handed through the processors.\n\t */\n\tpublic async pre(\n\t\trequest: IHttpServerRequest,\n\t\tresponse: IHttpResponse,\n\t\troute: IBaseRoute | undefined,\n\t\tcontextIds: IContextIds,\n\t\tprocessorState: { [id: string]: unknown }\n\t): Promise<void> {\n\t\tconst tenantToken = request.query?.[this._tenantTokenName];\n\t\tconst tokenDecodable =\n\t\t\tIs.stringValue(tenantToken) &&\n\t\t\t!Is.empty(this._vaultConnector) &&\n\t\t\tIs.stringValue(this._signingKeyName);\n\n\t\t// skipTenant routes (cross-node trust JWT routes) bypass api-key resolution\n\t\t// accept an encrypted ?tenantToken= query param so cross-tenant catalogue/DSP/PNP routing reaches the publisher's tenant context\n\t\tif (Is.empty(route) || (route.skipTenant ?? false)) {\n\t\t\tif (tokenDecodable) {\n\t\t\t\tconst errorResponse = await this.resolveByTenantToken(\n\t\t\t\t\ttenantToken,\n\t\t\t\t\tcontextIds,\n\t\t\t\t\tprocessorState\n\t\t\t\t);\n\t\t\t\tif (!Is.empty(errorResponse)) {\n\t\t\t\t\tHttpErrorHelper.buildResponse(response, errorResponse, HttpStatusCode.unauthorized);\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\n\t\tconst apiKey = request.headers?.[this._apiKeyName] ?? request.query?.[this._apiKeyName];\n\t\tlet errorResponse: IError | undefined;\n\n\t\tif (Is.stringValue(apiKey)) {\n\t\t\terrorResponse = await this.resolveByApiKey(apiKey, contextIds, processorState);\n\t\t} else if (tokenDecodable) {\n\t\t\terrorResponse = await this.resolveByTenantToken(tenantToken, contextIds, processorState);\n\t\t} else {\n\t\t\terrorResponse = new UnauthorizedError(TenantProcessor.CLASS_NAME, \"missingApiKey\", {\n\t\t\t\tkeyName: this._apiKeyName\n\t\t\t});\n\t\t}\n\n\t\tif (!Is.empty(errorResponse)) {\n\t\t\tHttpErrorHelper.buildResponse(response, errorResponse, HttpStatusCode.unauthorized);\n\t\t}\n\t}\n\n\t/**\n\t * Resolve the tenant context from an api key.\n\t * @param apiKey The api key sent by the caller.\n\t * @param contextIds The context IDs of the request.\n\t * @param processorState The state handed through the processors.\n\t * @returns An error to surface, or undefined on success.\n\t * @internal\n\t */\n\tprivate async resolveByApiKey(\n\t\tapiKey: string,\n\t\tcontextIds: IContextIds,\n\t\tprocessorState: { [id: string]: unknown }\n\t): Promise<IError | undefined> {\n\t\ttry {\n\t\t\tconst nodeTenant = await this._entityStorageConnector.get(apiKey, \"apiKey\");\n\n\t\t\tif (Is.empty(nodeTenant)) {\n\t\t\t\treturn new UnauthorizedError(TenantProcessor.CLASS_NAME, \"apiKeyNotFound\", {\n\t\t\t\t\tkey: apiKey\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tcontextIds[ContextIdKeys.Tenant] = nodeTenant.id;\n\t\t\tif (Is.stringValue(nodeTenant.publicOrigin)) {\n\t\t\t\tprocessorState.publicOrigin = nodeTenant.publicOrigin;\n\t\t\t}\n\t\t} catch (err) {\n\t\t\treturn BaseError.fromError(err);\n\t\t}\n\t}\n\n\t/**\n\t * Resolve the tenant context from an encrypted tenant token query param.\n\t * @param tenantToken The encrypted tenant token.\n\t * @param contextIds The context IDs of the request.\n\t * @param processorState The state handed through the processors.\n\t * @returns An error to surface, or undefined on success.\n\t * @internal\n\t */\n\tprivate async resolveByTenantToken(\n\t\ttenantToken: string,\n\t\tcontextIds: IContextIds,\n\t\tprocessorState: { [id: string]: unknown }\n\t): Promise<IError | undefined> {\n\t\tlet tenantId: string;\n\t\ttry {\n\t\t\ttenantId = await TenantUrlHelper.decrypt(\n\t\t\t\ttenantToken,\n\t\t\t\tthis._vaultConnector as IVaultConnector,\n\t\t\t\t`${this._nodeId}/${this._signingKeyName}`\n\t\t\t);\n\t\t} catch {\n\t\t\treturn new UnauthorizedError(TenantProcessor.CLASS_NAME, \"tenantTokenInvalid\", {\n\t\t\t\ttoken: tenantToken\n\t\t\t});\n\t\t}\n\n\t\ttry {\n\t\t\tconst nodeTenant = await this._entityStorageConnector.get(tenantId);\n\n\t\t\tif (Is.empty(nodeTenant)) {\n\t\t\t\treturn new UnauthorizedError(TenantProcessor.CLASS_NAME, \"tenantTokenNotFound\", {\n\t\t\t\t\ttenantId\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tcontextIds[ContextIdKeys.Tenant] = nodeTenant.id;\n\t\t\tif (Is.stringValue(nodeTenant.publicOrigin)) {\n\t\t\t\tprocessorState.publicOrigin = nodeTenant.publicOrigin;\n\t\t\t}\n\t\t} catch (err) {\n\t\t\treturn BaseError.fromError(err);\n\t\t}\n\t}\n}\n"]}

package/dist/es/utils/tenantUrlHelper.js

@@ -0,0 +1,65 @@
+// Copyright 2025 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { Converter, GeneralError, Guards } from "@twin.org/core";
+import { VaultEncryptionType } from "@twin.org/vault-models";
+/**
+ * Helper for building and parsing URLs that carry an encrypted tenant token query param.
+ * The token is the ChaCha20Poly1305-encrypted UTF-8 bytes of a tenant id, base64url-encoded
+ * for URL safety.
+ */
+export class TenantUrlHelper {
+    /**
+     * The default query param name for the encrypted tenant token.
+     */
+    static DEFAULT_TENANT_TOKEN_NAME = "tenantToken";
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "TenantUrlHelper";
+    /**
+     * Encrypt a tenant id and append it as an opaque query param to the supplied URL.
+     * @param url The URL to append the token to.
+     * @param tenantId The tenant id to encrypt into the token.
+     * @param vaultConnector The vault connector providing the symmetric key.
+     * @param keyName The fully-qualified vault key name (e.g. `${nodeId}/tenant-token-encryption`).
+     * @param tenantTokenName The query param name. Defaults to `tenantToken`.
+     * @returns The URL with the encrypted tenant token appended.
+     */
+    static async encrypt(url, tenantId, vaultConnector, keyName, tenantTokenName) {
+        Guards.stringValue(TenantUrlHelper.CLASS_NAME, "url", url);
+        Guards.stringValue(TenantUrlHelper.CLASS_NAME, "tenantId", tenantId);
+        Guards.object(TenantUrlHelper.CLASS_NAME, "vaultConnector", vaultConnector);
+        Guards.stringValue(TenantUrlHelper.CLASS_NAME, "keyName", keyName);
+        try {
+            const encrypted = await vaultConnector.encrypt(keyName, VaultEncryptionType.ChaCha20Poly1305, Converter.utf8ToBytes(tenantId));
+            const token = Converter.bytesToBase64Url(encrypted);
+            const paramName = tenantTokenName ?? TenantUrlHelper.DEFAULT_TENANT_TOKEN_NAME;
+            const separator = url.includes("?") ? "&" : "?";
+            return `${url}${separator}${paramName}=${token}`;
+        }
+        catch (err) {
+            throw new GeneralError(TenantUrlHelper.CLASS_NAME, "encryptFailed", undefined, err);
+        }
+    }
+    /**
+     * Decrypt an encrypted tenant token back into the original tenant id.
+     * @param token The base64url-encoded encrypted tenant token.
+     * @param vaultConnector The vault connector providing the symmetric key.
+     * @param keyName The fully-qualified vault key name used to encrypt the token.
+     * @returns The decrypted tenant id.
+     */
+    static async decrypt(token, vaultConnector, keyName) {
+        Guards.stringValue(TenantUrlHelper.CLASS_NAME, "token", token);
+        Guards.object(TenantUrlHelper.CLASS_NAME, "vaultConnector", vaultConnector);
+        Guards.stringValue(TenantUrlHelper.CLASS_NAME, "keyName", keyName);
+        try {
+            const encrypted = Converter.base64UrlToBytes(token);
+            const decrypted = await vaultConnector.decrypt(keyName, VaultEncryptionType.ChaCha20Poly1305, encrypted);
+            return Converter.bytesToUtf8(decrypted);
+        }
+        catch (err) {
+            throw new GeneralError(TenantUrlHelper.CLASS_NAME, "decryptFailed", undefined, err);
+        }
+    }
+}
+//# sourceMappingURL=tenantUrlHelper.js.map

package/dist/es/utils/tenantUrlHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenantUrlHelper.js","sourceRoot":"","sources":["../../../src/utils/tenantUrlHelper.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAEjE,OAAO,EAAwB,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAEnF;;;;GAIG;AACH,MAAM,OAAO,eAAe;IAC3B;;OAEG;IACI,MAAM,CAAU,yBAAyB,GAAW,aAAa,CAAC;IAEzE;;OAEG;IACI,MAAM,CAAU,UAAU,qBAAqC;IAEtE;;;;;;;;OAQG;IACI,MAAM,CAAC,KAAK,CAAC,OAAO,CAC1B,GAAW,EACX,QAAgB,EAChB,cAA+B,EAC/B,OAAe,EACf,eAAwB;QAExB,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC,UAAU,SAAe,GAAG,CAAC,CAAC;QACjE,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC,UAAU,cAAoB,QAAQ,CAAC,CAAC;QAC3E,MAAM,CAAC,MAAM,CACZ,eAAe,CAAC,UAAU,oBAE1B,cAAc,CACd,CAAC;QACF,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC,UAAU,aAAmB,OAAO,CAAC,CAAC;QAEzE,IAAI,CAAC;YACJ,MAAM,SAAS,GAAG,MAAM,cAAc,CAAC,OAAO,CAC7C,OAAO,EACP,mBAAmB,CAAC,gBAAgB,EACpC,SAAS,CAAC,WAAW,CAAC,QAAQ,CAAC,CAC/B,CAAC;YACF,MAAM,KAAK,GAAG,SAAS,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC;YACpD,MAAM,SAAS,GAAG,eAAe,IAAI,eAAe,CAAC,yBAAyB,CAAC;YAC/E,MAAM,SAAS,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;YAChD,OAAO,GAAG,GAAG,GAAG,SAAS,GAAG,SAAS,IAAI,KAAK,EAAE,CAAC;QAClD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,MAAM,IAAI,YAAY,CAAC,eAAe,CAAC,UAAU,EAAE,eAAe,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;QACrF,CAAC;IACF,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,KAAK,CAAC,OAAO,CAC1B,KAAa,EACb,cAA+B,EAC/B,OAAe;QAEf,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC,UAAU,WAAiB,KAAK,CAAC,CAAC;QACrE,MAAM,CAAC,MAAM,CACZ,eAAe,CAAC,UAAU,oBAE1B,cAAc,CACd,CAAC;QACF,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC,UAAU,aAAmB,OAAO,CAAC,CAAC;QAEzE,IAAI,CAAC;YACJ,MAAM,SAAS,GAAG,SAAS,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;YACpD,MAAM,SAAS,GAAG,MAAM,cAAc,CAAC,OAAO,CAC7C,OAAO,EACP,mBAAmB,CAAC,gBAAgB,EACpC,SAAS,CACT,CAAC;YACF,OAAO,SAAS,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,MAAM,IAAI,YAAY,CAAC,eAAe,CAAC,UAAU,EAAE,eAAe,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;QACrF,CAAC;IACF,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Converter, GeneralError, Guards } from \"@twin.org/core\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { type IVaultConnector, VaultEncryptionType } from \"@twin.org/vault-models\";\n\n/**\n * Helper for building and parsing URLs that carry an encrypted tenant token query param.\n * The token is the ChaCha20Poly1305-encrypted UTF-8 bytes of a tenant id, base64url-encoded\n * for URL safety.\n */\nexport class TenantUrlHelper {\n\t/**\n\t * The default query param name for the encrypted tenant token.\n\t */\n\tpublic static readonly DEFAULT_TENANT_TOKEN_NAME: string = \"tenantToken\";\n\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<TenantUrlHelper>();\n\n\t/**\n\t * Encrypt a tenant id and append it as an opaque query param to the supplied URL.\n\t * @param url The URL to append the token to.\n\t * @param tenantId The tenant id to encrypt into the token.\n\t * @param vaultConnector The vault connector providing the symmetric key.\n\t * @param keyName The fully-qualified vault key name (e.g. `${nodeId}/tenant-token-encryption`).\n\t * @param tenantTokenName The query param name. Defaults to `tenantToken`.\n\t * @returns The URL with the encrypted tenant token appended.\n\t */\n\tpublic static async encrypt(\n\t\turl: string,\n\t\ttenantId: string,\n\t\tvaultConnector: IVaultConnector,\n\t\tkeyName: string,\n\t\ttenantTokenName?: string\n\t): Promise<string> {\n\t\tGuards.stringValue(TenantUrlHelper.CLASS_NAME, nameof(url), url);\n\t\tGuards.stringValue(TenantUrlHelper.CLASS_NAME, nameof(tenantId), tenantId);\n\t\tGuards.object<IVaultConnector>(\n\t\t\tTenantUrlHelper.CLASS_NAME,\n\t\t\tnameof(vaultConnector),\n\t\t\tvaultConnector\n\t\t);\n\t\tGuards.stringValue(TenantUrlHelper.CLASS_NAME, nameof(keyName), keyName);\n\n\t\ttry {\n\t\t\tconst encrypted = await vaultConnector.encrypt(\n\t\t\t\tkeyName,\n\t\t\t\tVaultEncryptionType.ChaCha20Poly1305,\n\t\t\t\tConverter.utf8ToBytes(tenantId)\n\t\t\t);\n\t\t\tconst token = Converter.bytesToBase64Url(encrypted);\n\t\t\tconst paramName = tenantTokenName ?? TenantUrlHelper.DEFAULT_TENANT_TOKEN_NAME;\n\t\t\tconst separator = url.includes(\"?\") ? \"&\" : \"?\";\n\t\t\treturn `${url}${separator}${paramName}=${token}`;\n\t\t} catch (err) {\n\t\t\tthrow new GeneralError(TenantUrlHelper.CLASS_NAME, \"encryptFailed\", undefined, err);\n\t\t}\n\t}\n\n\t/**\n\t * Decrypt an encrypted tenant token back into the original tenant id.\n\t * @param token The base64url-encoded encrypted tenant token.\n\t * @param vaultConnector The vault connector providing the symmetric key.\n\t * @param keyName The fully-qualified vault key name used to encrypt the token.\n\t * @returns The decrypted tenant id.\n\t */\n\tpublic static async decrypt(\n\t\ttoken: string,\n\t\tvaultConnector: IVaultConnector,\n\t\tkeyName: string\n\t): Promise<string> {\n\t\tGuards.stringValue(TenantUrlHelper.CLASS_NAME, nameof(token), token);\n\t\tGuards.object<IVaultConnector>(\n\t\t\tTenantUrlHelper.CLASS_NAME,\n\t\t\tnameof(vaultConnector),\n\t\t\tvaultConnector\n\t\t);\n\t\tGuards.stringValue(TenantUrlHelper.CLASS_NAME, nameof(keyName), keyName);\n\n\t\ttry {\n\t\t\tconst encrypted = Converter.base64UrlToBytes(token);\n\t\t\tconst decrypted = await vaultConnector.decrypt(\n\t\t\t\tkeyName,\n\t\t\t\tVaultEncryptionType.ChaCha20Poly1305,\n\t\t\t\tencrypted\n\t\t\t);\n\t\t\treturn Converter.bytesToUtf8(decrypted);\n\t\t} catch (err) {\n\t\t\tthrow new GeneralError(TenantUrlHelper.CLASS_NAME, \"decryptFailed\", undefined, err);\n\t\t}\n\t}\n}\n"]}

package/dist/types/index.d.ts

@@ -18,3 +18,4 @@ export * from "./tenantIdContextIdHandler.js";
 export * from "./tenantProcessor.js";
 export * from "./tenantRoutes.js";
 export * from "./utils/tenantIdHelper.js";
+export * from "./utils/tenantUrlHelper.js";

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

@@ -7,4 +7,14 @@ export interface ITenantProcessorConfig {
      * @default x-api-key
      */
     apiKeyName?: string;
+    /**
+     * The name of the symmetric key in the vault used to encrypt/decrypt tenant tokens.
+     * @default tenant-token-encryption
+     */
+    signingKeyName?: string;
+    /**
+     * The query param name to look for the encrypted tenant token.
+     * @default tenantToken
+     */
+    tenantTokenName?: string;
 }

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

@@ -8,6 +8,12 @@ export interface ITenantProcessorConstructorOptions {
      * @default tenant
      */
     tenantEntityStorageType?: string;
+    /**
+     * The vault connector used to decrypt tenant tokens. Only resolved when
+     * `config.signingKeyName` is set.
+     * @default vault
+     */
+    vaultConnectorType?: string;
     /**
      * Configuration for the processor.
      */

package/dist/types/tenantProcessor.d.ts

@@ -19,6 +19,14 @@ export declare class TenantProcessor implements IBaseRouteProcessor {
      * @returns The class name of the component.
      */
     className(): string;
+    /**
+     * The processor needs to be started when the application is initialized so that
+     * the node identity is available for vault key resolution. Only required when
+     * the encrypted-token path is wired (i.e. `signingKeyName` is configured).
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns Nothing.
+     */
+    start(nodeLoggingComponentType?: string): Promise<void>;
     /**
      * Pre process the REST request for the specified route.
      * @param request The incoming request.

package/dist/types/utils/tenantUrlHelper.d.ts

@@ -0,0 +1,34 @@
+import { type IVaultConnector } from "@twin.org/vault-models";
+/**
+ * Helper for building and parsing URLs that carry an encrypted tenant token query param.
+ * The token is the ChaCha20Poly1305-encrypted UTF-8 bytes of a tenant id, base64url-encoded
+ * for URL safety.
+ */
+export declare class TenantUrlHelper {
+    /**
+     * The default query param name for the encrypted tenant token.
+     */
+    static readonly DEFAULT_TENANT_TOKEN_NAME: string;
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Encrypt a tenant id and append it as an opaque query param to the supplied URL.
+     * @param url The URL to append the token to.
+     * @param tenantId The tenant id to encrypt into the token.
+     * @param vaultConnector The vault connector providing the symmetric key.
+     * @param keyName The fully-qualified vault key name (e.g. `${nodeId}/tenant-token-encryption`).
+     * @param tenantTokenName The query param name. Defaults to `tenantToken`.
+     * @returns The URL with the encrypted tenant token appended.
+     */
+    static encrypt(url: string, tenantId: string, vaultConnector: IVaultConnector, keyName: string, tenantTokenName?: string): Promise<string>;
+    /**
+     * Decrypt an encrypted tenant token back into the original tenant id.
+     * @param token The base64url-encoded encrypted tenant token.
+     * @param vaultConnector The vault connector providing the symmetric key.
+     * @param keyName The fully-qualified vault key name used to encrypt the token.
+     * @returns The decrypted tenant id.
+     */
+    static decrypt(token: string, vaultConnector: IVaultConnector, keyName: string): Promise<string>;
+}

package/docs/changelog.md

@@ -1,6 +1,20 @@
 # Changelog
 
-## [0.0.3-next.27](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.26...api-tenant-processor-v0.0.3-next.27) (2026-04-23)
+## [0.0.3-next.28](https://github.com/twinfoundation/twin-api/compare/api-tenant-processor-v0.0.3-next.27...api-tenant-processor-v0.0.3-next.28) (2026-04-30)
+
+
+### Features
+
+* tenantToken decoder on skipTenant routes + BaseRestClient query-string preservation ([#108](https://github.com/twinfoundation/twin-api/issues/108)) ([1435357](https://github.com/twinfoundation/twin-api/commit/1435357034b41130fc97238c728265e48f746f1e))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.27 to 0.0.3-next.28
+
+## [0.0.3-next.27](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.26...api-tenant-processor-v0.0.3-next.27) (2026-04-23)
 
 
 ### Miscellaneous Chores
@@ -14,7 +28,7 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.26 to 0.0.3-next.27
 
-## [0.0.3-next.26](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.25...api-tenant-processor-v0.0.3-next.26) (2026-04-22)
+## [0.0.3-next.26](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.25...api-tenant-processor-v0.0.3-next.26) (2026-04-22)
 
 
 ### Miscellaneous Chores
@@ -28,7 +42,7 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.25 to 0.0.3-next.26
 
-## [0.0.3-next.25](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.24...api-tenant-processor-v0.0.3-next.25) (2026-04-14)
+## [0.0.3-next.25](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.24...api-tenant-processor-v0.0.3-next.25) (2026-04-14)
 
 
 ### Miscellaneous Chores
@@ -42,7 +56,7 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.24 to 0.0.3-next.25
 
-## [0.0.3-next.24](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.23...api-tenant-processor-v0.0.3-next.24) (2026-04-14)
+## [0.0.3-next.24](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.23...api-tenant-processor-v0.0.3-next.24) (2026-04-14)
 
 
 ### Miscellaneous Chores
@@ -56,7 +70,7 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.23 to 0.0.3-next.24
 
-## [0.0.3-next.23](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.22...api-tenant-processor-v0.0.3-next.23) (2026-04-14)
+## [0.0.3-next.23](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.22...api-tenant-processor-v0.0.3-next.23) (2026-04-14)
 
 
 ### Miscellaneous Chores
@@ -70,7 +84,7 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.22 to 0.0.3-next.23
 
-## [0.0.3-next.22](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.21...api-tenant-processor-v0.0.3-next.22) (2026-03-27)
+## [0.0.3-next.22](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.21...api-tenant-processor-v0.0.3-next.22) (2026-03-27)
 
 
 ### Miscellaneous Chores
@@ -84,7 +98,7 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.21 to 0.0.3-next.22
 
-## [0.0.3-next.21](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.20...api-tenant-processor-v0.0.3-next.21) (2026-03-11)
+## [0.0.3-next.21](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.20...api-tenant-processor-v0.0.3-next.21) (2026-03-11)
 
 
 ### Miscellaneous Chores
@@ -98,12 +112,12 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.20 to 0.0.3-next.21
 
-## [0.0.3-next.20](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.19...api-tenant-processor-v0.0.3-next.20) (2026-02-09)
+## [0.0.3-next.20](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.19...api-tenant-processor-v0.0.3-next.20) (2026-02-09)
 
 
 ### Features
 
-* location encoding ([#79](https://github.com/twinfoundation/api/issues/79)) ([c684465](https://github.com/twinfoundation/api/commit/c684465f2a871376152472bdecb6aa230b1101a1))
+* location encoding ([#79](https://github.com/iotaledger/twin-api/issues/79)) ([c684465](https://github.com/iotaledger/twin-api/commit/c684465f2a871376152472bdecb6aa230b1101a1))
 
 
 ### Dependencies
@@ -112,7 +126,7 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.19 to 0.0.3-next.20
 
-## [0.0.3-next.19](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.18...api-tenant-processor-v0.0.3-next.19) (2026-02-06)
+## [0.0.3-next.19](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.18...api-tenant-processor-v0.0.3-next.19) (2026-02-06)
 
 
 ### Miscellaneous Chores
@@ -126,12 +140,12 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.18 to 0.0.3-next.19
 
-## [0.0.3-next.18](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.17...api-tenant-processor-v0.0.3-next.18) (2026-02-04)
+## [0.0.3-next.18](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.17...api-tenant-processor-v0.0.3-next.18) (2026-02-04)
 
 
 ### Features
 
-* tenant api and scopes ([#75](https://github.com/twinfoundation/api/issues/75)) ([c663141](https://github.com/twinfoundation/api/commit/c663141091e8974d769f8f9904ecdab009ebd083))
+* tenant api and scopes ([#75](https://github.com/iotaledger/twin-api/issues/75)) ([c663141](https://github.com/iotaledger/twin-api/commit/c663141091e8974d769f8f9904ecdab009ebd083))
 
 
 ### Dependencies
@@ -140,7 +154,7 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.17 to 0.0.3-next.18
 
-## [0.0.3-next.17](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.16...api-tenant-processor-v0.0.3-next.17) (2026-01-26)
+## [0.0.3-next.17](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.16...api-tenant-processor-v0.0.3-next.17) (2026-01-26)
 
 
 ### Miscellaneous Chores
@@ -154,12 +168,12 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.16 to 0.0.3-next.17
 
-## [0.0.3-next.16](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.15...api-tenant-processor-v0.0.3-next.16) (2026-01-26)
+## [0.0.3-next.16](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.15...api-tenant-processor-v0.0.3-next.16) (2026-01-26)
 
 
 ### Features
 
-* public base url ([#70](https://github.com/twinfoundation/api/issues/70)) ([5b958cd](https://github.com/twinfoundation/api/commit/5b958cd91e8a38cdae2835ff5f2356c7e48d37c3))
+* public base url ([#70](https://github.com/iotaledger/twin-api/issues/70)) ([5b958cd](https://github.com/iotaledger/twin-api/commit/5b958cd91e8a38cdae2835ff5f2356c7e48d37c3))
 
 
 ### Dependencies
@@ -168,7 +182,7 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.15 to 0.0.3-next.16
 
-## [0.0.3-next.15](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.14...api-tenant-processor-v0.0.3-next.15) (2026-01-22)
+## [0.0.3-next.15](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.14...api-tenant-processor-v0.0.3-next.15) (2026-01-22)
 
 
 ### Miscellaneous Chores
@@ -182,7 +196,7 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.14 to 0.0.3-next.15
 
-## [0.0.3-next.14](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.13...api-tenant-processor-v0.0.3-next.14) (2026-01-20)
+## [0.0.3-next.14](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.13...api-tenant-processor-v0.0.3-next.14) (2026-01-20)
 
 
 ### Miscellaneous Chores
@@ -196,7 +210,7 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.13 to 0.0.3-next.14
 
-## [0.0.3-next.13](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.12...api-tenant-processor-v0.0.3-next.13) (2026-01-19)
+## [0.0.3-next.13](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.12...api-tenant-processor-v0.0.3-next.13) (2026-01-19)
 
 
 ### Miscellaneous Chores
@@ -210,7 +224,7 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.12 to 0.0.3-next.13
 
-## [0.0.3-next.12](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.11...api-tenant-processor-v0.0.3-next.12) (2026-01-12)
+## [0.0.3-next.12](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.11...api-tenant-processor-v0.0.3-next.12) (2026-01-12)
 
 
 ### Miscellaneous Chores
@@ -224,12 +238,12 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.11 to 0.0.3-next.12
 
-## [0.0.3-next.11](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.10...api-tenant-processor-v0.0.3-next.11) (2026-01-08)
+## [0.0.3-next.11](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.10...api-tenant-processor-v0.0.3-next.11) (2026-01-08)
 
 
 ### Bug Fixes
 
-* duplicate api keys ([#61](https://github.com/twinfoundation/api/issues/61)) ([5519c2d](https://github.com/twinfoundation/api/commit/5519c2d077d9b3d4b5fc7d5f073ef67cd000a367))
+* duplicate api keys ([#61](https://github.com/iotaledger/twin-api/issues/61)) ([5519c2d](https://github.com/iotaledger/twin-api/commit/5519c2d077d9b3d4b5fc7d5f073ef67cd000a367))
 
 
 ### Dependencies
@@ -238,7 +252,7 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.10 to 0.0.3-next.11
 
-## [0.0.3-next.10](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.9...api-tenant-processor-v0.0.3-next.10) (2026-01-05)
+## [0.0.3-next.10](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.9...api-tenant-processor-v0.0.3-next.10) (2026-01-05)
 
 
 ### Miscellaneous Chores
@@ -252,24 +266,24 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.9 to 0.0.3-next.10
 
-## [0.0.3-next.9](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.8...api-tenant-processor-v0.0.3-next.9) (2026-01-05)
+## [0.0.3-next.9](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.8...api-tenant-processor-v0.0.3-next.9) (2026-01-05)
 
 
 ### Features
 
-* add context id features ([#42](https://github.com/twinfoundation/api/issues/42)) ([0186055](https://github.com/twinfoundation/api/commit/0186055c48afde842a4254b4df9ac9249c40fe40))
-* add livez endpoint ([#57](https://github.com/twinfoundation/api/issues/57)) ([ef007db](https://github.com/twinfoundation/api/commit/ef007db8201736dd3053211f849ffd03baaa485e))
-* add tests for tenant id handler ([c868e7e](https://github.com/twinfoundation/api/commit/c868e7e5831e13df39b8994c40834e51f69fa0b9))
-* check tenant id in auth if set ([937ba0c](https://github.com/twinfoundation/api/commit/937ba0cd790038556a7b2af251e52b43cb059df4))
-* check tenant id in auth if set ([66f7337](https://github.com/twinfoundation/api/commit/66f73374d3cf4c1c85ea96ec74bb30712fb84dd7))
-* reduce short form tenant id length ([bcda377](https://github.com/twinfoundation/api/commit/bcda377daed03b21fd1c6ffe47bad4a45d96602b))
+* add context id features ([#42](https://github.com/iotaledger/twin-api/issues/42)) ([0186055](https://github.com/iotaledger/twin-api/commit/0186055c48afde842a4254b4df9ac9249c40fe40))
+* add livez endpoint ([#57](https://github.com/iotaledger/twin-api/issues/57)) ([ef007db](https://github.com/iotaledger/twin-api/commit/ef007db8201736dd3053211f849ffd03baaa485e))
+* add tests for tenant id handler ([c868e7e](https://github.com/iotaledger/twin-api/commit/c868e7e5831e13df39b8994c40834e51f69fa0b9))
+* check tenant id in auth if set ([937ba0c](https://github.com/iotaledger/twin-api/commit/937ba0cd790038556a7b2af251e52b43cb059df4))
+* check tenant id in auth if set ([66f7337](https://github.com/iotaledger/twin-api/commit/66f73374d3cf4c1c85ea96ec74bb30712fb84dd7))
+* reduce short form tenant id length ([bcda377](https://github.com/iotaledger/twin-api/commit/bcda377daed03b21fd1c6ffe47bad4a45d96602b))
 
 
 ### Bug Fixes
 
-* do not check x-api-key for health resourcr ([#54](https://github.com/twinfoundation/api/issues/54)) ([897a747](https://github.com/twinfoundation/api/commit/897a747a57ed76ee37035f7ea3d40953df3f5fb0))
-* remove extraneous type ([f85c52c](https://github.com/twinfoundation/api/commit/f85c52c55caa3a7a64f6f675842f0ea59289a5d9))
-* use base64Url for tenant id short form so it doesn't include slash ([7210771](https://github.com/twinfoundation/api/commit/72107718650acd05440ce9d9bf10905e6052281c))
+* do not check x-api-key for health resourcr ([#54](https://github.com/iotaledger/twin-api/issues/54)) ([897a747](https://github.com/iotaledger/twin-api/commit/897a747a57ed76ee37035f7ea3d40953df3f5fb0))
+* remove extraneous type ([f85c52c](https://github.com/iotaledger/twin-api/commit/f85c52c55caa3a7a64f6f675842f0ea59289a5d9))
+* use base64Url for tenant id short form so it doesn't include slash ([7210771](https://github.com/iotaledger/twin-api/commit/72107718650acd05440ce9d9bf10905e6052281c))
 
 
 ### Dependencies
@@ -278,12 +292,12 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.8 to 0.0.3-next.9
 
-## [0.0.3-next.8](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.7...api-tenant-processor-v0.0.3-next.8) (2025-12-17)
+## [0.0.3-next.8](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.7...api-tenant-processor-v0.0.3-next.8) (2025-12-17)
 
 
 ### Bug Fixes
 
-* do not check x-api-key for health resourcr ([#54](https://github.com/twinfoundation/api/issues/54)) ([897a747](https://github.com/twinfoundation/api/commit/897a747a57ed76ee37035f7ea3d40953df3f5fb0))
+* do not check x-api-key for health resourcr ([#54](https://github.com/iotaledger/twin-api/issues/54)) ([897a747](https://github.com/iotaledger/twin-api/commit/897a747a57ed76ee37035f7ea3d40953df3f5fb0))
 
 
 ### Dependencies
@@ -292,7 +306,7 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.7 to 0.0.3-next.8
 
-## [0.0.3-next.7](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.6...api-tenant-processor-v0.0.3-next.7) (2025-11-26)
+## [0.0.3-next.7](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.6...api-tenant-processor-v0.0.3-next.7) (2025-11-26)
 
 
 ### Miscellaneous Chores
@@ -306,13 +320,13 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.6 to 0.0.3-next.7
 
-## [0.0.3-next.6](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.5...api-tenant-processor-v0.0.3-next.6) (2025-11-20)
+## [0.0.3-next.6](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.5...api-tenant-processor-v0.0.3-next.6) (2025-11-20)
 
 
 ### Features
 
-* check tenant id in auth if set ([937ba0c](https://github.com/twinfoundation/api/commit/937ba0cd790038556a7b2af251e52b43cb059df4))
-* check tenant id in auth if set ([66f7337](https://github.com/twinfoundation/api/commit/66f73374d3cf4c1c85ea96ec74bb30712fb84dd7))
+* check tenant id in auth if set ([937ba0c](https://github.com/iotaledger/twin-api/commit/937ba0cd790038556a7b2af251e52b43cb059df4))
+* check tenant id in auth if set ([66f7337](https://github.com/iotaledger/twin-api/commit/66f73374d3cf4c1c85ea96ec74bb30712fb84dd7))
 
 
 ### Dependencies
@@ -321,7 +335,7 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.5 to 0.0.3-next.6
 
-## [0.0.3-next.5](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.4...api-tenant-processor-v0.0.3-next.5) (2025-11-14)
+## [0.0.3-next.5](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.4...api-tenant-processor-v0.0.3-next.5) (2025-11-14)
 
 
 ### Miscellaneous Chores
@@ -335,20 +349,20 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.4 to 0.0.3-next.5
 
-## [0.0.3-next.4](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.3...api-tenant-processor-v0.0.3-next.4) (2025-11-14)
+## [0.0.3-next.4](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.3...api-tenant-processor-v0.0.3-next.4) (2025-11-14)
 
 
 ### Features
 
-* add context id features ([#42](https://github.com/twinfoundation/api/issues/42)) ([0186055](https://github.com/twinfoundation/api/commit/0186055c48afde842a4254b4df9ac9249c40fe40))
-* add tests for tenant id handler ([c868e7e](https://github.com/twinfoundation/api/commit/c868e7e5831e13df39b8994c40834e51f69fa0b9))
-* reduce short form tenant id length ([bcda377](https://github.com/twinfoundation/api/commit/bcda377daed03b21fd1c6ffe47bad4a45d96602b))
+* add context id features ([#42](https://github.com/iotaledger/twin-api/issues/42)) ([0186055](https://github.com/iotaledger/twin-api/commit/0186055c48afde842a4254b4df9ac9249c40fe40))
+* add tests for tenant id handler ([c868e7e](https://github.com/iotaledger/twin-api/commit/c868e7e5831e13df39b8994c40834e51f69fa0b9))
+* reduce short form tenant id length ([bcda377](https://github.com/iotaledger/twin-api/commit/bcda377daed03b21fd1c6ffe47bad4a45d96602b))
 
 
 ### Bug Fixes
 
-* remove extraneous type ([f85c52c](https://github.com/twinfoundation/api/commit/f85c52c55caa3a7a64f6f675842f0ea59289a5d9))
-* use base64Url for tenant id short form so it doesn't include slash ([7210771](https://github.com/twinfoundation/api/commit/72107718650acd05440ce9d9bf10905e6052281c))
+* remove extraneous type ([f85c52c](https://github.com/iotaledger/twin-api/commit/f85c52c55caa3a7a64f6f675842f0ea59289a5d9))
+* use base64Url for tenant id short form so it doesn't include slash ([7210771](https://github.com/iotaledger/twin-api/commit/72107718650acd05440ce9d9bf10905e6052281c))
 
 
 ### Dependencies
@@ -357,17 +371,17 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.3 to 0.0.3-next.4
 
-## [0.0.3-next.3](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.2...api-tenant-processor-v0.0.3-next.3) (2025-11-14)
+## [0.0.3-next.3](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.2...api-tenant-processor-v0.0.3-next.3) (2025-11-14)
 
 
 ### Features
 
-* add tests for tenant id handler ([c868e7e](https://github.com/twinfoundation/api/commit/c868e7e5831e13df39b8994c40834e51f69fa0b9))
+* add tests for tenant id handler ([c868e7e](https://github.com/iotaledger/twin-api/commit/c868e7e5831e13df39b8994c40834e51f69fa0b9))
 
 
 ### Bug Fixes
 
-* use base64Url for tenant id short form so it doesn't include slash ([7210771](https://github.com/twinfoundation/api/commit/72107718650acd05440ce9d9bf10905e6052281c))
+* use base64Url for tenant id short form so it doesn't include slash ([7210771](https://github.com/iotaledger/twin-api/commit/72107718650acd05440ce9d9bf10905e6052281c))
 
 
 ### Dependencies
@@ -376,17 +390,17 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.2 to 0.0.3-next.3
 
-## [0.0.3-next.2](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.1...api-tenant-processor-v0.0.3-next.2) (2025-11-12)
+## [0.0.3-next.2](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.1...api-tenant-processor-v0.0.3-next.2) (2025-11-12)
 
 
 ### Features
 
-* reduce short form tenant id length ([bcda377](https://github.com/twinfoundation/api/commit/bcda377daed03b21fd1c6ffe47bad4a45d96602b))
+* reduce short form tenant id length ([bcda377](https://github.com/iotaledger/twin-api/commit/bcda377daed03b21fd1c6ffe47bad4a45d96602b))
 
 
 ### Bug Fixes
 
-* remove extraneous type ([f85c52c](https://github.com/twinfoundation/api/commit/f85c52c55caa3a7a64f6f675842f0ea59289a5d9))
+* remove extraneous type ([f85c52c](https://github.com/iotaledger/twin-api/commit/f85c52c55caa3a7a64f6f675842f0ea59289a5d9))
 
 
 ### Dependencies
@@ -395,12 +409,12 @@
   * dependencies
     * @twin.org/api-models bumped from 0.0.3-next.1 to 0.0.3-next.2
 
-## [0.0.3-next.1](https://github.com/twinfoundation/api/compare/api-tenant-processor-v0.0.3-next.0...api-tenant-processor-v0.0.3-next.1) (2025-11-10)
+## [0.0.3-next.1](https://github.com/iotaledger/twin-api/compare/api-tenant-processor-v0.0.3-next.0...api-tenant-processor-v0.0.3-next.1) (2025-11-10)
 
 
 ### Features
 
-* add context id features ([#42](https://github.com/twinfoundation/api/issues/42)) ([0186055](https://github.com/twinfoundation/api/commit/0186055c48afde842a4254b4df9ac9249c40fe40))
+* add context id features ([#42](https://github.com/iotaledger/twin-api/issues/42)) ([0186055](https://github.com/iotaledger/twin-api/commit/0186055c48afde842a4254b4df9ac9249c40fe40))
 
 
 ### Dependencies

package/docs/reference/classes/TenantProcessor.md

@@ -54,6 +54,34 @@ The class name of the component.
 
 ***
 
+### start() {#start}
+
+> **start**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
+
+The processor needs to be started when the application is initialized so that
+the node identity is available for vault key resolution. Only required when
+the encrypted-token path is wired (i.e. `signingKeyName` is configured).
+
+#### Parameters
+
+##### nodeLoggingComponentType?
+
+`string`
+
+The node logging component type.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IBaseRouteProcessor.start`
+
+***
+
 ### pre() {#pre}
 
 > **pre**(`request`, `response`, `route`, `contextIds`, `processorState`): `Promise`\<`void`\>

package/docs/reference/classes/TenantUrlHelper.md

@@ -0,0 +1,111 @@
+# Class: TenantUrlHelper
+
+Helper for building and parsing URLs that carry an encrypted tenant token query param.
+The token is the ChaCha20Poly1305-encrypted UTF-8 bytes of a tenant id, base64url-encoded
+for URL safety.
+
+## Constructors
+
+### Constructor
+
+> **new TenantUrlHelper**(): `TenantUrlHelper`
+
+#### Returns
+
+`TenantUrlHelper`
+
+## Properties
+
+### DEFAULT\_TENANT\_TOKEN\_NAME {#default_tenant_token_name}
+
+> `readonly` `static` **DEFAULT\_TENANT\_TOKEN\_NAME**: `string` = `"tenantToken"`
+
+The default query param name for the encrypted tenant token.
+
+***
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### encrypt() {#encrypt}
+
+> `static` **encrypt**(`url`, `tenantId`, `vaultConnector`, `keyName`, `tenantTokenName?`): `Promise`\<`string`\>
+
+Encrypt a tenant id and append it as an opaque query param to the supplied URL.
+
+#### Parameters
+
+##### url
+
+`string`
+
+The URL to append the token to.
+
+##### tenantId
+
+`string`
+
+The tenant id to encrypt into the token.
+
+##### vaultConnector
+
+`IVaultConnector`
+
+The vault connector providing the symmetric key.
+
+##### keyName
+
+`string`
+
+The fully-qualified vault key name (e.g. `${nodeId}/tenant-token-encryption`).
+
+##### tenantTokenName?
+
+`string`
+
+The query param name. Defaults to `tenantToken`.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The URL with the encrypted tenant token appended.
+
+***
+
+### decrypt() {#decrypt}
+
+> `static` **decrypt**(`token`, `vaultConnector`, `keyName`): `Promise`\<`string`\>
+
+Decrypt an encrypted tenant token back into the original tenant id.
+
+#### Parameters
+
+##### token
+
+`string`
+
+The base64url-encoded encrypted tenant token.
+
+##### vaultConnector
+
+`IVaultConnector`
+
+The vault connector providing the symmetric key.
+
+##### keyName
+
+`string`
+
+The fully-qualified vault key name used to encrypt the token.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The decrypted tenant id.

package/docs/reference/index.md

@@ -7,6 +7,7 @@
 - [TenantIdContextIdHandler](classes/TenantIdContextIdHandler.md)
 - [TenantProcessor](classes/TenantProcessor.md)
 - [TenantIdHelper](classes/TenantIdHelper.md)
+- [TenantUrlHelper](classes/TenantUrlHelper.md)
 
 ## Interfaces
 

package/docs/reference/interfaces/ITenantProcessorConfig.md

@@ -15,3 +15,31 @@ The key to look for in the header or query params for the api key.
 ```ts
 x-api-key
 ```
+
+***
+
+### signingKeyName? {#signingkeyname}
+
+> `optional` **signingKeyName?**: `string`
+
+The name of the symmetric key in the vault used to encrypt/decrypt tenant tokens.
+
+#### Default
+
+```ts
+tenant-token-encryption
+```
+
+***
+
+### tenantTokenName? {#tenanttokenname}
+
+> `optional` **tenantTokenName?**: `string`
+
+The query param name to look for the encrypted tenant token.
+
+#### Default
+
+```ts
+tenantToken
+```

package/docs/reference/interfaces/ITenantProcessorConstructorOptions.md

@@ -18,6 +18,21 @@ tenant
 
 ***
 
+### vaultConnectorType? {#vaultconnectortype}
+
+> `optional` **vaultConnectorType?**: `string`
+
+The vault connector used to decrypt tenant tokens. Only resolved when
+`config.signingKeyName` is set.
+
+#### Default
+
+```ts
+vault
+```
+
+***
+
 ### config? {#config}
 
 > `optional` **config?**: [`ITenantProcessorConfig`](ITenantProcessorConfig.md)

package/locales/en.json

@@ -2,7 +2,13 @@
 	"error": {
 		"tenantProcessor": {
 			"missingApiKey": "API key header or query param \"{keyName}\" is missing or invalid.",
-			"apiKeyNotFound": "No node tenant found for API key \"{key}\"."
+			"apiKeyNotFound": "No node tenant found for API key \"{key}\".",
+			"tenantTokenInvalid": "The tenant token \"{token}\" could not be decrypted or is malformed.",
+			"tenantTokenNotFound": "No node tenant found for the decrypted tenant token \"{tenantId}\"."
+		},
+		"tenantUrlHelper": {
+			"encryptFailed": "Encryption of tenant URL token failed.",
+			"decryptFailed": "Decryption of tenant URL token failed."
 		},
 		"tenantAdminService": {
 			"apiKeyAlreadyInUse": "The provided API key is already in use by another tenant.",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/api-tenant-processor",
-	"version": "0.0.3-next.27",
+	"version": "0.0.3-next.28",
 	"description": "Tenant resolution services and route handlers that derive tenant context from API keys.",
 	"repository": {
 		"type": "git",
@@ -14,12 +14,13 @@
 		"node": ">=20.0.0"
 	},
 	"dependencies": {
-		"@twin.org/api-models": "0.0.3-next.27",
+		"@twin.org/api-models": "0.0.3-next.28",
 		"@twin.org/context": "next",
 		"@twin.org/core": "next",
 		"@twin.org/entity": "next",
 		"@twin.org/entity-storage-models": "next",
 		"@twin.org/nameof": "next",
+		"@twin.org/vault-models": "next",
 		"@twin.org/web": "next"
 	},
 	"main": "./dist/es/index.js",