@3sixty/api-tenant-processor 0.0.0-stage → 0.20.0-next.1

package/dist/es/utils/tenantIdHelper.js

@@ -0,0 +1,23 @@
+// Copyright 2025 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { RandomHelper } from "@3sixty/core";
+/**
+ * Helper class for tenant id related operations.
+ */
+export class TenantIdHelper {
+    /**
+     * Generates a new tenant ID.
+     * @returns A new tenant ID.
+     */
+    static generateTenantId() {
+        return RandomHelper.generateUuidV7("compact");
+    }
+    /**
+     * Generates a new API Key.
+     * @returns A new API Key.
+     */
+    static generateApiKey() {
+        return RandomHelper.generateUuidV7("compact");
+    }
+}
+//# sourceMappingURL=tenantIdHelper.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tenantIdHelper.js","sources":["../../../src/utils/tenantIdHelper.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C;;GAEG;AACH,MAAM,OAAO,cAAc;IAC1B;;;OAGG;IACI,MAAM,CAAC,gBAAgB;QAC7B,OAAO,YAAY,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;IAC/C,CAAC;IAED;;;OAGG;IACI,MAAM,CAAC,cAAc;QAC3B,OAAO,YAAY,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;IAC/C,CAAC;CACD","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { RandomHelper } from \"@3sixty/core\";\n\n/**\n * Helper class for tenant id related operations.\n */\nexport class TenantIdHelper {\n\t/**\n\t * Generates a new tenant ID.\n\t * @returns A new tenant ID.\n\t */\n\tpublic static generateTenantId(): string {\n\t\treturn RandomHelper.generateUuidV7(\"compact\");\n\t}\n\n\t/**\n\t * Generates a new API Key.\n\t * @returns A new API Key.\n\t */\n\tpublic static generateApiKey(): string {\n\t\treturn RandomHelper.generateUuidV7(\"compact\");\n\t}\n}\n"]}

package/dist/types/entities/tenant.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Class defining the storage for node tenants.
+ */
+export declare class Tenant {
+    /**
+     * The unique identifier for the tenant.
+     */
+    id: string;
+    /**
+     * The api key for the tenant.
+     */
+    apiKey: string;
+    /**
+     * The label of the tenant.
+     */
+    label: string;
+    /**
+     * The date the tenant was created.
+     */
+    dateCreated: string;
+    /**
+     * The date the tenant was modified.
+     */
+    dateModified: string;
+    /**
+     * The origin available to the public for accessing the API.
+     */
+    publicOrigin?: string;
+    /**
+     * The organization id for the tenant.
+     */
+    organizationId: string;
+    /**
+     * Optional list of organization aliases that can be used for legacy lookups, indexed format.
+     */
+    organizationIdLegacy?: string[];
+}

package/dist/types/entities/tenantV0.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Class defining the storage for node tenants.
+ */
+export declare class TenantV0 {
+    /**
+     * The unique identifier for the tenant.
+     */
+    id: string;
+    /**
+     * The api key for the tenant.
+     */
+    apiKey: string;
+    /**
+     * The label of the tenant.
+     */
+    label: string;
+    /**
+     * The date the tenant was created.
+     */
+    dateCreated: string;
+    /**
+     * The date the tenant was modified.
+     */
+    dateModified: string;
+    /**
+     * The origin available to the public for accessing the API.
+     */
+    publicOrigin?: string;
+}

package/dist/types/entities/tenantV1.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Class defining the storage for node tenants.
+ */
+export declare class TenantV1 {
+    /**
+     * The unique identifier for the tenant.
+     */
+    id: string;
+    /**
+     * The api key for the tenant.
+     */
+    apiKey: string;
+    /**
+     * The label of the tenant.
+     */
+    label: string;
+    /**
+     * The date the tenant was created.
+     */
+    dateCreated: string;
+    /**
+     * The date the tenant was modified.
+     */
+    dateModified: string;
+    /**
+     * The origin available to the public for accessing the API.
+     */
+    publicOrigin?: string;
+    /**
+     * The organization id for the tenant.
+     */
+    organizationId: string;
+    /**
+     * Optional list of organization aliases that can be used for legacy lookups, indexed format.
+     */
+    organizationIdLegacy?: string;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,26 @@
+export * from "./entities/tenant.js";
+export * from "./entities/tenantV0.js";
+export * from "./entities/tenantV1.js";
+export * from "./models/api/ITenantCreateRequest.js";
+export * from "./models/api/ITenantGetByApiKeyRequest.js";
+export * from "./models/api/ITenantGetByIdRequest.js";
+export * from "./models/api/ITenantGetByPublicOriginRequest.js";
+export * from "./models/api/ITenantGetResponse.js";
+export * from "./models/api/ITenantListRequest.js";
+export * from "./models/api/ITenantListResponse.js";
+export * from "./models/api/ITenantRemoveRequest.js";
+export * from "./models/api/ITenantUpdateRequest.js";
+export * from "./models/ISingleTenantProcessorConfig.js";
+export * from "./models/ISingleTenantProcessorConstructorOptions.js";
+export * from "./models/ITenantAdminServiceConfig.js";
+export * from "./models/ITenantAdminServiceConstructorOptions.js";
+export * from "./models/ITenantProcessorConfig.js";
+export * from "./models/ITenantProcessorConstructorOptions.js";
+export * from "./restEntryPoints.js";
+export * from "./schema.js";
+export * from "./singleTenantProcessor.js";
+export * from "./tenantAdminService.js";
+export * from "./tenantIdContextIdHandler.js";
+export * from "./tenantProcessor.js";
+export * from "./tenantRoutes.js";
+export * from "./utils/tenantIdHelper.js";

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

@@ -0,0 +1,9 @@
+/**
+ * Configuration for the single tenant processor
+ */
+export interface ISingleTenantProcessorConfig {
+    /**
+     * Include the stack with errors.
+     */
+    includeErrorStack?: boolean;
+}

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

@@ -0,0 +1,10 @@
+import type { ISingleTenantProcessorConfig } from "./ISingleTenantProcessorConfig.js";
+/**
+ * Options for the Single Tenant Processor constructor.
+ */
+export interface ISingleTenantProcessorConstructorOptions {
+    /**
+     * Configuration for the processor.
+     */
+    config?: ISingleTenantProcessorConfig;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Configuration for the tenant admin service.
+ */
+export interface ITenantAdminServiceConfig {
+    /**
+     * The time in milliseconds a tenant is kept in the in-memory lookup cache, counted from when it
+     * was read and not extended by use, set to 0 to disable caching. Entries are invalidated when a
+     * tenant is created, updated or removed through this service, but only in the process that made
+     * the change, so this is also the longest another node can serve a tenant that has been edited
+     * elsewhere.
+     * @default 30000
+     */
+    tenantCacheTtlMs?: number;
+    /**
+     * The maximum number of tenant lookups to hold in the in-memory cache.
+     * @default undefined (LfuCache default)
+     */
+    tenantCacheCapacity?: number;
+    /**
+     * Maximum time in milliseconds to wait for the tenant cache mutex during a cache population.
+     * @default undefined (LfuCache default)
+     */
+    tenantCacheMutexTimeoutMs?: number;
+}

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

@@ -0,0 +1,20 @@
+import type { ITenantAdminServiceConfig } from "./ITenantAdminServiceConfig.js";
+/**
+ * Options for the Tenant Admin Service constructor.
+ */
+export interface ITenantAdminServiceConstructorOptions {
+    /**
+     * The entity storage for the tenants.
+     * @default tenant
+     */
+    tenantEntityStorageType?: string;
+    /**
+     * The component type to use for firing tenant events.
+     * @default platform
+     */
+    platformComponentType?: string;
+    /**
+     * Configuration for the service.
+     */
+    config?: ITenantAdminServiceConfig;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Configuration for the tenant processor
+ */
+export interface ITenantProcessorConfig {
+    /**
+     * The key to look for in the header or query params for the api key.
+     * @default x-api-key
+     */
+    apiKeyName?: string;
+    /**
+     * The list of endpoint paths that should be checked for an api key header, can be regexp strings. Defaults to ["/login$"].
+     */
+    apiKeyEndpoints?: string[];
+    /**
+     * Include the stack with errors.
+     */
+    includeErrorStack?: boolean;
+}

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

@@ -0,0 +1,15 @@
+import type { ITenantProcessorConfig } from "./ITenantProcessorConfig.js";
+/**
+ * Options for the Tenant Processor constructor.
+ */
+export interface ITenantProcessorConstructorOptions {
+    /**
+     * The component used to resolve tenants, which also provides the lookup caching.
+     * @default tenant-admin
+     */
+    tenantAdminComponentType?: string;
+    /**
+     * Configuration for the processor.
+     */
+    config?: ITenantProcessorConfig;
+}

package/dist/types/models/api/ITenantCreateRequest.d.ts

@@ -0,0 +1,12 @@
+import type { ITenant } from "@3sixty/api-models";
+/**
+ * The tenant to create.
+ */
+export interface ITenantCreateRequest {
+    /**
+     * The tenant to create.
+     */
+    body: Omit<ITenant, "id" | "dateCreated" | "dateModified"> & {
+        id?: string;
+    };
+}

package/dist/types/models/api/ITenantGetByApiKeyRequest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The tenant to get by API key.
+ */
+export interface ITenantGetByApiKeyRequest {
+    /**
+     * The path parameters.
+     */
+    pathParams: {
+        /**
+         * The API key of the tenant to get.
+         */
+        apiKey: string;
+    };
+}

package/dist/types/models/api/ITenantGetByIdRequest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The tenant to get by id.
+ */
+export interface ITenantGetByIdRequest {
+    /**
+     * The path parameters.
+     */
+    pathParams: {
+        /**
+         * The id of the tenant to get.
+         */
+        id: string;
+    };
+}

package/dist/types/models/api/ITenantGetByPublicOriginRequest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The tenant to get by public origin.
+ */
+export interface ITenantGetByPublicOriginRequest {
+    /**
+     * The path parameters.
+     */
+    pathParams: {
+        /**
+         * The public origin of the tenant to get.
+         */
+        publicOrigin: string;
+    };
+}

package/dist/types/models/api/ITenantGetResponse.d.ts

@@ -0,0 +1,10 @@
+import type { ITenant } from "@3sixty/api-models";
+/**
+ * The tenant get response.
+ */
+export interface ITenantGetResponse {
+    /**
+     * The tenant.
+     */
+    body: ITenant;
+}

package/dist/types/models/api/ITenantListRequest.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The list of tenants.
+ */
+export interface ITenantListRequest {
+    /**
+     * The query parameters.
+     */
+    query: {
+        /**
+         * The condition for the query as JSON version of EntityCondition type.
+         */
+        conditions?: string;
+        /**
+         * The properties to include in the returned tenants, separated by commas.
+         * If not provided, all properties will be returned.
+         */
+        properties?: string;
+        /**
+         * The cursor to get the next chunk of tenants.
+         */
+        cursor?: string;
+        /**
+         * The number of tenants to return.
+         */
+        limit?: string;
+    };
+}

package/dist/types/models/api/ITenantListResponse.d.ts

@@ -0,0 +1,17 @@
+import type { ITenant } from "@3sixty/api-models";
+import type { HeaderTypes } from "@3sixty/web";
+/**
+ * The list of tenants.
+ */
+export interface ITenantListResponse {
+    /**
+     * The headers which can be used to include the cursor.
+     */
+    headers?: {
+        [HeaderTypes.Link]?: string | string[];
+    };
+    /**
+     * The list of tenants.
+     */
+    body: ITenant[];
+}

package/dist/types/models/api/ITenantRemoveRequest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The tenant to remove by id.
+ */
+export interface ITenantRemoveRequest {
+    /**
+     * The path parameters.
+     */
+    pathParams: {
+        /**
+         * The id of the tenant to remove.
+         */
+        id: string;
+    };
+}

package/dist/types/models/api/ITenantUpdateRequest.d.ts

@@ -0,0 +1,19 @@
+import type { ITenant } from "@3sixty/api-models";
+/**
+ * The tenant to update.
+ */
+export interface ITenantUpdateRequest {
+    /**
+     * The path parameters.
+     */
+    pathParams: {
+        /**
+         * The id of the tenant to update.
+         */
+        id: string;
+    };
+    /**
+     * The tenant to update.
+     */
+    body: Omit<ITenant, "id" | "dateCreated" | "dateModified">;
+}

package/dist/types/restEntryPoints.d.ts

@@ -0,0 +1,5 @@
+import type { IRestRouteEntryPoint } from "@3sixty/api-models";
+/**
+ * REST entry points for the tenant administration service.
+ */
+export declare const restEntryPoints: IRestRouteEntryPoint[];

package/dist/types/schema.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Initialize the schema for the node tenant processor, including the Tenant 1 to 2 migration
+ * step which converts organizationIdLegacy from a pipe-delimited string to an array of ids.
+ */
+export declare function initSchema(): void;

package/dist/types/singleTenantProcessor.d.ts

@@ -0,0 +1,41 @@
+import { type IBaseRoute, type IBaseRouteProcessor, type IHttpResponse, type IHttpServerRequest } from "@3sixty/api-models";
+import { type IContextIds } from "@3sixty/context";
+import type { ISingleTenantProcessorConstructorOptions } from "./models/ISingleTenantProcessorConstructorOptions.js";
+/**
+ * Injects the single-tenant organization ID into every request context and validates any organization query parameter.
+ */
+export declare class SingleTenantProcessor implements IBaseRouteProcessor {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of SingleTenantProcessor.
+     * @param options Options for the processor.
+     */
+    constructor(options?: ISingleTenantProcessorConstructorOptions);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * Cache the node organization ID from the engine context so it can be injected into each
+     * per-request context without requiring a separate ContextIdProcessor for Organization.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns A promise that resolves when the node organization ID has been cached.
+     */
+    start(nodeLoggingComponentType?: string): Promise<void>;
+    /**
+     * Pre process the REST request for the specified route.
+     * @param request The incoming request.
+     * @param response The outgoing response.
+     * @param route The route to process.
+     * @param contextIds The context IDs of the request.
+     * @param processorState The state handed through the processors.
+     * @returns A promise that resolves when the organization ID has been injected and any query parameter validated.
+     */
+    pre(request: IHttpServerRequest, response: IHttpResponse, route: IBaseRoute | undefined, contextIds: IContextIds, processorState: {
+        [id: string]: unknown;
+    }): Promise<void>;
+}

package/dist/types/tenantAdminService.d.ts

@@ -0,0 +1,109 @@
+import { type HealthApplicationCallback, type IHealth, type IHealthProviderComponent, type ITenant, type ITenantAdminComponent } from "@3sixty/api-models";
+import { type IContextIds } from "@3sixty/context";
+import { type EntityCondition } from "@3sixty/entity";
+import type { ITenantAdminServiceConstructorOptions } from "./models/ITenantAdminServiceConstructorOptions.js";
+/**
+ * Service for performing tenant administration operations.
+ */
+export declare class TenantAdminService implements ITenantAdminComponent, IHealthProviderComponent {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of TenantAdminService.
+     * @param options The options for the connector.
+     */
+    constructor(options?: ITenantAdminServiceConstructorOptions);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * Stop the service and release the tenant cache.
+     * @returns A promise that resolves when the service has stopped.
+     */
+    stop(): Promise<void>;
+    /**
+     * Get a tenant by its id.
+     * @param tenantId The id of the tenant.
+     * @returns The tenant.
+     * @throws Error if the tenant is not found.
+     */
+    get(tenantId: string): Promise<ITenant>;
+    /**
+     * Get a tenant by its api key.
+     * @param apiKey The api key of the tenant.
+     * @returns The tenant.
+     * @throws Error if the tenant is not found.
+     */
+    getByApiKey(apiKey: string): Promise<ITenant>;
+    /**
+     * Get a tenant by its public origin.
+     * @param publicOrigin The origin of the tenant.
+     * @returns The tenant.
+     * @throws Error if the tenant is not found.
+     */
+    getByPublicOrigin(publicOrigin: string): Promise<ITenant>;
+    /**
+     * Get a tenant by its organization id, optionally searching legacy ids.
+     * @param organizationId The organization id of the tenant.
+     * @param includeLegacy Whether to also search the legacy organization id array.
+     * @returns The tenant.
+     * @throws Error if the tenant is not found.
+     */
+    getTenantByOrganizationId(organizationId: string, includeLegacy?: boolean): Promise<ITenant>;
+    /**
+     * Create a tenant.
+     * @param tenant The tenant to store.
+     * @returns The tenant id.
+     */
+    create(tenant: Omit<ITenant, "id" | "dateCreated" | "dateModified"> & {
+        id?: string;
+    }): Promise<string>;
+    /**
+     * Update a tenant.
+     * @param tenant The tenant to update.
+     * @returns A promise that resolves when the tenant has been updated.
+     */
+    update(tenant: Partial<Omit<ITenant, "dateCreated" | "dateModified">>): Promise<void>;
+    /**
+     * Remove a tenant by its id.
+     * @param tenantId The id of the tenant.
+     * @returns Nothing.
+     */
+    remove(tenantId: string): Promise<void>;
+    /**
+     * Query tenants with pagination.
+     * @param conditions The conditions to filter the tenants.
+     * @param properties The properties to include in the returned tenants.
+     * @param cursor The cursor to start from.
+     * @param limit The maximum number of tenants to return.
+     * @returns The tenants and the next cursor if more tenants are available.
+     */
+    query(conditions?: EntityCondition<ITenant>, properties?: (keyof ITenant)[], cursor?: string, limit?: number): Promise<{
+        tenants: ITenant[];
+        cursor?: string;
+    }>;
+    /**
+     * Provision a temporary tenant for the application health cycle.
+     * @param contextIds Accumulated context IDs; receives the provisional tenant ID.
+     * @returns A promise that resolves when provisioning is complete.
+     */
+    healthApplicationInit(contextIds: IContextIds): Promise<void>;
+    /**
+     * Verify the provisioned tenant can be retrieved.
+     * The tenant ID is read from the active context set by the init pass.
+     * @param callback The callback to invoke when a deferred health result is ready.
+     * @returns The health entries for this component.
+     */
+    healthApplication(callback: HealthApplicationCallback): Promise<IHealth[] | undefined>;
+    /**
+     * Remove the temporary tenant provisioned during init.
+     * The tenant ID is read from the active context set by the init pass.
+     * Does nothing when no tenant ID is present.
+     * @returns A promise that resolves when teardown is complete.
+     */
+    healthApplicationTeardown(): Promise<void>;
+}

package/dist/types/tenantIdContextIdHandler.d.ts

@@ -0,0 +1,33 @@
+import type { IContextIdHandler } from "@3sixty/context";
+/**
+ * Context ID handler that treats a tenant ID as a compact base64url-encoded hex string.
+ */
+export declare class TenantIdContextIdHandler implements IContextIdHandler {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * The class name of the component.
+     * @returns The class name.
+     */
+    className(): string;
+    /**
+     * The short form of the tenant id is the base64 version to compact.
+     * @param value The full context id value.
+     * @returns Short form string.
+     */
+    short(value: string): string;
+    /**
+     * The long form version of the context ID, expanded from a short version.
+     * @param value The short form context ID value.
+     * @returns The long form version of the context ID.
+     */
+    long(value: string): string;
+    /**
+     * Guard the value ensuring length.
+     * @param value The value to guard.
+     * @throws GeneralError if the value is too short.
+     */
+    guard(value: string): void;
+}

package/dist/types/tenantProcessor.d.ts

@@ -0,0 +1,34 @@
+import { type IBaseRoute, type IBaseRouteProcessor, type IHttpResponse, type IHttpServerRequest } from "@3sixty/api-models";
+import { type IContextIds } from "@3sixty/context";
+import type { ITenantProcessorConstructorOptions } from "./models/ITenantProcessorConstructorOptions.js";
+/**
+ * Handles incoming api keys and maps them to tenant ids.
+ */
+export declare class TenantProcessor implements IBaseRouteProcessor {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of TenantProcessor.
+     * @param options Options for the processor.
+     */
+    constructor(options?: ITenantProcessorConstructorOptions);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * Pre process the REST request for the specified route.
+     * @param request The incoming request.
+     * @param response The outgoing response.
+     * @param route The route to process.
+     * @param contextIds The context IDs of the request.
+     * @param processorState The state handed through the processors.
+     * @returns A promise that resolves when the tenant context has been resolved and injected, or an error response set.
+     */
+    pre(request: IHttpServerRequest, response: IHttpResponse, route: IBaseRoute | undefined, contextIds: IContextIds, processorState: {
+        [id: string]: unknown;
+    }): Promise<void>;
+}