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

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,15 @@
+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;
+    /**
+     * Configuration for the service.
+     */
+    config?: ITenantAdminServiceConfig;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Configuration for the TenantOverrideProcessor.
+ */
+export interface ITenantOverrideProcessorConfig {
+    /**
+     * Include the stack with errors.
+     */
+    includeErrorStack?: boolean;
+    /**
+     * The scope value that grants escalated privilege for cross-tenant access. Defaults to "global-admin".
+     */
+    escalatedPrivilegeScope?: string;
+}

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

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

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/tenantOverrideProcessor.d.ts

@@ -0,0 +1,44 @@
+import { type IBaseRoute, type IBaseRouteProcessor, type IHttpResponse, type IHttpServerRequest } from "@3sixty/api-models";
+import { type IContextIds } from "@3sixty/context";
+import type { ITenantOverrideProcessorConstructorOptions } from "./models/ITenantOverrideProcessorConstructorOptions.js";
+/**
+ * Processes the overrideTenant query parameter for routes that allow tenant override.
+ * Requires the caller to hold the escalated privilege scope. Runs after AuthHeaderProcessor so
+ * authentication is always resolved in the caller's own partition first.
+ */
+export declare class TenantOverrideProcessor implements IBaseRouteProcessor {
+    /**
+     * The query parameter name used to supply the override tenant ID.
+     */
+    static readonly OVERRIDE_TENANT_PARAM: string;
+    /**
+     * The scope string required to perform a tenant override.
+     */
+    static readonly DEFAULT_ESCALATED_PRIVILEGE_SCOPE: string;
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of TenantOverrideProcessor.
+     * @param options Options for the processor.
+     */
+    constructor(options?: ITenantOverrideProcessorConstructorOptions);
+    /**
+     * 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 override has been applied or skipped.
+     */
+    pre(request: IHttpServerRequest, response: IHttpResponse, route: IBaseRoute | undefined, contextIds: IContextIds, processorState: {
+        [id: string]: unknown;
+    }): Promise<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>;
+}

package/dist/types/tenantRoutes.d.ts

@@ -0,0 +1,78 @@
+import { type ICreatedResponse, type IHttpRequestContext, type INoContentResponse, type IRestRoute, type ITag } from "@3sixty/api-models";
+import type { ITenantCreateRequest } from "./models/api/ITenantCreateRequest.js";
+import type { ITenantGetByApiKeyRequest } from "./models/api/ITenantGetByApiKeyRequest.js";
+import type { ITenantGetByIdRequest } from "./models/api/ITenantGetByIdRequest.js";
+import type { ITenantGetByPublicOriginRequest } from "./models/api/ITenantGetByPublicOriginRequest.js";
+import type { ITenantGetResponse } from "./models/api/ITenantGetResponse.js";
+import type { ITenantListRequest } from "./models/api/ITenantListRequest.js";
+import type { ITenantListResponse } from "./models/api/ITenantListResponse.js";
+import type { ITenantRemoveRequest } from "./models/api/ITenantRemoveRequest.js";
+import type { ITenantUpdateRequest } from "./models/api/ITenantUpdateRequest.js";
+/**
+ * The tag to associate with the routes.
+ */
+export declare const tagsTenants: ITag[];
+/**
+ * The REST routes for tenant management.
+ * @param baseRouteName Prefix to prepend to the paths.
+ * @param componentName The name of the component to use in the routes stored in the ComponentFactory.
+ * @returns The generated routes.
+ */
+export declare function generateRestRoutesTenants(baseRouteName: string, componentName: string): IRestRoute[];
+/**
+ * Get the list of tenants.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function tenantList(httpRequestContext: IHttpRequestContext, componentName: string, request: ITenantListRequest): Promise<ITenantListResponse>;
+/**
+ * Get the tenant by id.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function tenantById(httpRequestContext: IHttpRequestContext, componentName: string, request: ITenantGetByIdRequest): Promise<ITenantGetResponse>;
+/**
+ * Get the tenant by api key.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function tenantByApiKey(httpRequestContext: IHttpRequestContext, componentName: string, request: ITenantGetByApiKeyRequest): Promise<ITenantGetResponse>;
+/**
+ * Get the tenant by public origin.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function tenantByPublicOrigin(httpRequestContext: IHttpRequestContext, componentName: string, request: ITenantGetByPublicOriginRequest): Promise<ITenantGetResponse>;
+/**
+ * Remove the tenant by id.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function tenantRemove(httpRequestContext: IHttpRequestContext, componentName: string, request: ITenantRemoveRequest): Promise<INoContentResponse>;
+/**
+ * Create the tenant.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @param baseRouteName The base route name for the tenant.
+ * @returns The response object with additional http response properties.
+ */
+export declare function tenantCreate(httpRequestContext: IHttpRequestContext, componentName: string, request: ITenantCreateRequest, baseRouteName: string): Promise<ICreatedResponse>;
+/**
+ * Update the tenant.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function tenantUpdate(httpRequestContext: IHttpRequestContext, componentName: string, request: ITenantUpdateRequest): Promise<INoContentResponse>;

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

@@ -0,0 +1,15 @@
+/**
+ * Helper class for tenant id related operations.
+ */
+export declare class TenantIdHelper {
+    /**
+     * Generates a new tenant ID.
+     * @returns A new tenant ID.
+     */
+    static generateTenantId(): string;
+    /**
+     * Generates a new API Key.
+     * @returns A new API Key.
+     */
+    static generateApiKey(): string;
+}