@ti-engine/web-framework 1.19.0 → 1.20.0

package/types/bin/web-server.d.ts

@@ -0,0 +1,373 @@
+export = TiWebServer;
+import ServiceConsumer = require("@ti-engine/core/service-consumer");
+export type NodeServer = import("node:http").Server;
+export type TiWebServiceConfiguration = ServiceConfiguration;
+export type TiWebApplicationConfig = {
+    classPath: string;
+};
+export type ApiConfig = {
+    endpointEnabled: boolean;
+    inventory: ApiInventory;
+    requestTimeout: number;
+};
+export type SettingsAuth = {
+    enabledMethods: string[];
+    local: Object;
+    oauth2: {
+        azure?: SettingsOAuth2Client;
+        google?: SettingsOAuth2Client;
+    };
+};
+export type SettingsOAuth2Client = {
+    clientID?: string;
+    clientSecret?: string;
+    callbackUrl?: string;
+    discoveryUrl?: string;
+    isPublic?: boolean;
+    tokenEndpointAuthMethod?: TiTokenEndpointAuthMethod;
+};
+export type SettingsStaticCache = {
+    /**
+     * The `max-age` for `/static` responses, in SECONDS (not a duration string). `0` means every use is revalidated.
+     */
+    maxAge: number;
+    /**
+     * Whether to add `immutable`. Only correct when the `/static` filenames are content-addressed.
+     */
+    immutable: boolean;
+    /**
+     * Path prefixes under `/static` that are served long-lived and `immutable` regardless of the two settings above.
+     */
+    immutablePaths: string[];
+};
+export type SettingsCookies = {
+    secret: string;
+    path: string;
+    httpOnly: boolean;
+    sameSite: "lax" | "strict" | "none";
+    maxAge: number;
+};
+export type ApiInventory = Record<string, Record<string, ServiceAddress>>;
+import type { TiAuthMethod, TiTokenEndpointAuthMethod } from "#auth-manager";
+import type { TiSession } from "#definitions";
+import type User from "#user";
+import type TiWebAppManager from "#web-app-manager";
+import type { ServiceAddress, ServiceConfiguration } from "@ti-engine/core/definitions";
+/** @import { TiAuthMethod, TiTokenEndpointAuthMethod } from "#auth-manager" */
+/** @import { TiSession } from "#definitions" */
+/** @import User from "#user" */
+/** @import TiWebAppManager from "#web-app-manager" */
+/** @import { ServiceAddress, ServiceConfiguration } from "@ti-engine/core/definitions" */
+/**
+ * Default unprotected static-asset route matchers. The path segments are matched with `(?:[^/]+\/)*` rather than
+ * `(?:.+\/)*`: the inner `[^/]+` cannot also consume the "/" delimiter, so the pattern is unambiguous and matches
+ * in linear time. The previous `.+` form was ambiguous and backtracked exponentially on hostile request paths such
+ * as `/static/a/a/…/a/x` (no trailing extension) — and these matchers run against the raw request path in
+ * {@link TiWebServer#isUnprotectedRoute} BEFORE authentication, so that was a pre-auth denial-of-service vector
+ * (CodeQL js/redos). The matched language for realistic asset paths is unchanged.
+ *
+ * @type {RegExp}
+ */
+declare const RE_STATIC_UNPROTECTED: RegExp;
+/**
+ * Default unprotected `/.well-known/` route matcher. See {@link RE_STATIC_UNPROTECTED} for the ReDoS rationale.
+ *
+ * @type {RegExp}
+ */
+declare const RE_WELL_KNOWN_UNPROTECTED: RegExp;
+/**
+ * A web server microservice based on the ti-engine.
+ * <br/>
+ * Note: The web server is fully functional and already comes with all the necessary fundamentals and security features. However, it is designed to be extended
+ * with custom logic and functionality to fit your specific needs. Here is a list of methods that you can override to customize the web server behavior:
+ * - {@link TiWebServer#defineWebApplicationRoutes} Override this to define custom web application routes. Remember to call the base method if you want to preserve the default behavior as well (recommended).
+ * - {@link TiWebServer#defineUnprotectedRoutes} Override this to define unprotected routes. Remember to call the base method if you want to preserve the default behavior as well (recommended).
+ * - {@link TiWebServer#verifySession} Override this to implement custom session verification logic.
+ *
+ * @class TiWebServer
+ * @extends ServiceConsumer
+ * @public
+ */
+declare class TiWebServer extends ServiceConsumer {
+    #private;
+    /**
+     * @constructor
+     * @param {string} serviceDomainName The service domain name for this service instance.
+     * @param {TiWebServiceConfiguration} serviceConfig The JSON configuration for this service. Note that the configuration provided will be merged with the default web server configuration, and it will override any conflicting properties.
+     * @throws {TiException.E_GEN_JS_INTERNAL_ERROR} If the web application manager cannot be loaded.
+     */
+    constructor(serviceDomainName: string, serviceConfig: TiWebServiceConfiguration);
+    /**
+     * Property returning the service configuration JSON.
+     *
+     * @property
+     * @returns {TiWebServiceConfiguration}
+     * @override
+     * @public
+     */
+    get serviceConfig(): TiWebServiceConfiguration;
+    /**
+     * Property returning if the web server is currently shutting down.
+     *
+     * @property
+     * @returns {boolean}
+     * @public
+     */
+    get isShuttingDown(): boolean;
+    /**
+     * Property returning the list of static content directories.
+     *
+     * @property
+     * @returns {string[]}
+     * @public
+     */
+    get staticContentPaths(): string[];
+    /**
+     * Property returning the server URL.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get serverUrl(): string;
+    /**
+     * Property returning the {@link TiWebAppManager} instance.
+     *
+     * @property
+     * @returns {TiWebAppManager}
+     * @public
+     */
+    get webAppManager(): TiWebAppManager;
+    /**
+     * Starts the web server.
+     *
+     * @method
+     * @returns {Promise}
+     * @override
+     * @public
+     */
+    onStart(): Promise<any>;
+    /**
+     * Shuts down the web server.
+     *
+     * @method
+     * @returns {Promise}
+     * @override
+     * @public
+     */
+    onStop(): Promise<any>;
+    /**
+     * Used to report health status of the service instance for external monitoring.
+     * This is a scheduled job that will be executed at SERVICE_HEALTH_CHECK_INTERVAL time.
+     *
+     * @method
+     * @override
+     * @public
+     */
+    reportHealthy(): void;
+    /**
+     * Used to verify the session of a request.
+     *
+     * @method
+     * @param {TiSession} session
+     * @returns {boolean}
+     * @public
+     */
+    verifySession(session: TiSession): boolean;
+    /**
+     * Hook for the application to augment the freshly-authenticated session (e.g. derive domain roles from an
+     * identity store or the org chart). Runs synchronously, once per login, before the framework's additive `admin`
+     * role is applied. The default is a no-op. Any test-user role injection is an override of whatever the app derives.
+     *
+     * @method
+     * @virtual
+     * @param {TiSession} session
+     * @param {Object} [request] Optional Express request object that can be used to read body/cookies/query data.
+     * @returns {TiSession}
+     * @public
+     */
+    augmentSession(session: TiSession, request?: Object): TiSession;
+    /**
+     * Used to authenticate a user via the specified auth method.
+     *
+     * @method
+     * @param {TiAuthMethod} authMethod
+     * @param {Object} [authDetails={}]
+     * @returns {Promise}
+     * @public
+     */
+    authenticate(authMethod: TiAuthMethod, authDetails?: Object): Promise<any>;
+    /**
+     * Used to set up user authorization according to the specified auth method.
+     *
+     * @method
+     * @param {TiAuthMethod} authMethod
+     * @param {URL} currentUrl
+     * @param {Object} oidc
+     * @returns {Promise<User>}
+     * @public
+     */
+    authorize(authMethod: TiAuthMethod, currentUrl: URL, oidc: Object): Promise<User>;
+    /**
+     * Used to get a service mapping if such exists.
+     *
+     * @method
+     * @param {string} serviceVersion
+     * @param {string} serviceName
+     * @returns {ServiceAddress}
+     * @public
+     */
+    getServiceAddress(serviceVersion: string, serviceName: string): ServiceAddress;
+    /**
+     * Used to check if the specified hostname is allowed to access the web server.
+     *
+     * @method
+     * @param {string} hostname
+     * @returns {boolean}
+     * @public
+     */
+    isAllowedHost(hostname: string): boolean;
+    /**
+     * Used to check if the specified route is unprotected (i.e., does not require authentication). The default unprotected routes are:
+     * - /
+     * - /static/...
+     * - /.well-known/...
+     * - /not-found
+     * - /app
+     * - /app/enter
+     * - /app/config
+     * - /logout
+     * - /login/:method
+     * <br/>
+     * NOTE: You can define custom unprotected routes by overriding the {@link TiWebServer#defineUnprotectedRoutes} method.
+     *
+     * @method
+     * @param {string} route
+     * @returns {boolean}
+     * @public
+     */
+    isUnprotectedRoute(route: string): boolean;
+    /**
+     * Used to define the web application routes.
+     * <br/>
+     * NOTE: Override this to define custom web application routes. Remember to call the base method if you want to preserve the default behavior as well.
+     *
+     * @method
+     * @virtual
+     * @public
+     */
+    defineWebApplicationRoutes(): void;
+    /**
+     * Used to define the unprotected routes (i.e., routes that do not require authentication).
+     * <br/>
+     * NOTE: Override this to define custom unprotected routes. Remember to call the base method if you want to preserve the default behavior as well.
+     *
+     * @method
+     * @virtual
+     * @public
+     */
+    defineUnprotectedRoutes(): void;
+    /**
+     * Registers a custom application route on the underlying Express app.
+     * <br/>
+     * NOTE: Call this from a {@link TiWebServer#defineWebApplicationRoutes} override AFTER invoking the base method,
+     * so the framework's own routes keep priority and any catch-all route you add resolves last (it will still be
+     * registered before the framework's own `*splat` 404 handler). It is only valid once the Express app exists —
+     * i.e., from within {@link TiWebServer#defineWebApplicationRoutes}, which {@link TiWebServer#onStart} invokes.
+     *
+     * @method
+     * @param {string} method One of the supported routing verbs: get, post, put, patch, delete, options, head, all.
+     * @param {string|RegExp} path The route path or pattern.
+     * @param {...Function} handlers One or more Express route handlers/middleware.
+     * @returns {TiWebServer} This instance, to allow chaining.
+     * @public
+     */
+    registerRoute(method: string, path: string | RegExp, ...handlers: Function[]): TiWebServer;
+    /**
+     * Adds a pattern to the unprotected-routes list — routes that bypass the authentication gate. A string is
+     * matched exactly against the request path; a RegExp is tested against it. Consulted at request time by
+     * {@link TiWebServer#isUnprotectedRoute}.
+     * <br/>
+     * NOTE: Call this from a {@link TiWebServer#defineUnprotectedRoutes} override AFTER invoking the base method, to
+     * extend (rather than replace) the defaults.
+     *
+     * @method
+     * @param {string|RegExp} pattern The exact path (string) or path matcher (RegExp) to treat as unprotected.
+     * @returns {TiWebServer} This instance, to allow chaining.
+     * @public
+     */
+    addUnprotectedRoute(pattern: string | RegExp): TiWebServer;
+    /**
+     * Resolves a `staticCache` configuration block into the policy the `/static` mounts apply, filling in
+     * {@link TiWebServer.#STATIC_CACHE_DEFAULTS} per key and rejecting values that cannot be honored. Pure: problems
+     * are returned as `warnings` rather than logged, so the caller decides how to surface them and a test can assert
+     * on them. Static and exposed for unit testing — not part of the customization surface.
+     * <br/>
+     * `maxAge` is a whole number of SECONDS, mapping 1:1 onto the `Cache-Control` directive — express's `"1y"`-style
+     * duration strings are NOT accepted, and are reported rather than silently reinterpreted as milliseconds.
+     * <br/>
+     * `immutable` is dropped (with a warning) when `maxAge` is 0, because a response that is stale on arrival yet
+     * promises never to change is a contradiction. Dropping it fails safe: the misconfiguration costs a revalidation,
+     * not a year of unreachable assets.
+     *
+     * @method
+     * @static
+     * @param {SettingsStaticCache} [staticCache] The configured block, if any.
+     * @returns {{maxAge: number, immutable: boolean, immutablePaths: string[], warnings: string[]}}
+     * @public
+     */
+    static resolveStaticCachePolicy(staticCache?: SettingsStaticCache): {
+        maxAge: number;
+        immutable: boolean;
+        immutablePaths: string[];
+        warnings: string[];
+    };
+    /**
+     * Builds the `Cache-Control` value for one static file: the long-lived immutable policy when its served path sits
+     * under a configured `immutablePaths` prefix (matched case-sensitively, so a case mismatch falls back to the safe
+     * side), otherwise the policy's own `maxAge`/`immutable`. A `maxAge` of 0 is emitted as an explicit
+     * `must-revalidate` rather than a bare `max-age=0`, matching what the sibling `web-content` package serves.
+     * Pure and static; exposed for unit testing — not part of the customization surface.
+     *
+     * @method
+     * @static
+     * @param {string} rootPath The directory this `/static` mount serves.
+     * @param {string} filePath The absolute path of the file being served.
+     * @param {Object} policy A policy as returned by {@link TiWebServer.resolveStaticCachePolicy}.
+     * @returns {string}
+     * @public
+     */
+    static staticCacheControlFor(rootPath: string, filePath: string, policy: Object): string;
+    /**
+     * Normalizes an HTTP method to a lower-case Express routing verb, or returns null if it is not a supported,
+     * registrable verb. Anything that is not a string is rejected outright rather than coerced — otherwise a value
+     * whose `toString()` happens to yield a verb (`[ "get" ]`, `new String( "get" )`) would register a route and
+     * bypass the `E_GEN_INVALID_ARGUMENT_TYPE` that {@link TiWebServer#registerRoute} raises for a bad method.
+     * Pure and static; exposed for unit testing — not part of the customization surface.
+     *
+     * @method
+     * @static
+     * @param {string} method
+     * @returns {string|null}
+     * @public
+     */
+    static normalizeRegistrableMethod(method: string): string | null;
+    /**
+     * Tests a request path against a list of unprotected-route patterns (string exact-match or RegExp test),
+     * returning true on the first match. A RegExp's `lastIndex` is reset defensively so a stateful 'g'/'y' flag
+     * cannot cause a match to be skipped. Pure and static; shared by {@link TiWebServer#isUnprotectedRoute} and
+     * exposed for unit testing — not part of the customization surface.
+     *
+     * @method
+     * @static
+     * @param {Array<string|RegExp>} patterns
+     * @param {string} pathOnly The request path with any query string already stripped.
+     * @returns {boolean}
+     * @public
+     */
+    static isRouteInList(patterns: Array<string | RegExp>, pathOnly: string): boolean;
+}
+declare namespace TiWebServer {
+    export { RE_STATIC_UNPROTECTED };
+    export { RE_WELL_KNOWN_UNPROTECTED };
+}

package/types/components/admin-config-handlers.d.ts

@@ -0,0 +1,11 @@
+export declare var listEditors: (service: ConfigService) => ExpressHandler;
+export declare var composeView: (service: any) => (request: any, response: any, next: any) => void;
+export declare var saveEditorEdit: (service: any) => (request: any, response: any, next: any) => void;
+export declare var getCurrent: (service: any) => (request: any, response: any, next: any) => void;
+export declare var getHistory: (service: any) => (request: any, response: any, next: any) => void;
+export declare var listChanges: (service: any) => (request: any, response: any, next: any) => void;
+export declare var getChange: (service: any) => (request: any, response: any, next: any) => void;
+export declare var restoreChangeSet: (service: any) => (request: any, response: any, next: any) => void;
+export declare var exportBundle: (service: any) => (request: any, response: any, next: any) => void;
+import type ConfigService from "#config-service";
+import type { ExpressHandler } from "#web-handlers";

package/types/components/auth-manager.d.ts

@@ -0,0 +1,125 @@
+export = AuthManager;
+import User = require("#user");
+import type { SettingsAuth } from "#web-server";
+export type TiAuthMethod = string;
+/** @import { SettingsAuth } from "#web-server" */
+/**
+ * Enum for specifying the authentication method.
+ *
+ * @readonly
+ * @enum {string}
+ * @typedef {string} TiAuthMethod
+ */
+declare const authMethodEnum: import("@ti-engine/core/definitions").TiEnumOf<{
+    LOCAL: string[];
+    OPENID_AZURE: string[];
+    OPENID_GOOGLE: string[];
+}>;
+export type TiTokenEndpointAuthMethod = string;
+/**
+ * The AuthManager class is used to manage authentication and authorization.
+ *
+ * @class AuthManager
+ * @public
+ */
+declare class AuthManager {
+    #private;
+    /**
+     * @constructor
+     * @param {SettingsAuth} settings
+     */
+    constructor(settings: SettingsAuth);
+    /**
+     * Used to initialize the authentication manager.
+     *
+     * @method
+     * @returns {Promise}
+     * @public
+     */
+    initialize(): Promise<any>;
+    /**
+     * Used to check whether the specified authentication method is enabled.
+     *
+     * @method
+     * @param {TiAuthMethod} authMethod
+     * @returns {boolean}
+     * @public
+     */
+    isAuthEnabled(authMethod: TiAuthMethod): boolean;
+    /**
+     * Returns the list of currently enabled authentication methods, reflecting any OpenID providers dropped by
+     * {@link AuthManager#initialize} for being enabled but unconfigured. Callers (e.g. the login-page renderer)
+     * use this to present only the methods a user can actually complete.
+     *
+     * @method
+     * @returns {TiAuthMethod[]}
+     * @public
+     */
+    getEnabledMethods(): TiAuthMethod[];
+    /**
+     * Used to authenticate a user via the specified authentication method.
+     *
+     * @method
+     * @param {TiAuthMethod} authMethod
+     * @param {Object} authDetails
+     * @returns {Promise<Object>}
+     * @throws {TiException.E_SEC_UNRECOGNIZED_AUTH_METHOD} If the authentication method is not recognized or enabled.
+     * @throws {TiException.E_GEN_NOT_INITIALIZED} If the auth manager was not properly initialized.
+     * @public
+     */
+    authenticate(authMethod: TiAuthMethod, authDetails: Object): Promise<Object>;
+    /**
+     * Used to set up user authorization according to the specified authentication method.
+     *
+     * @method
+     * @param {TiAuthMethod} authMethod
+     * @param {URL} currentUrl
+     * @param {Object} oidc
+     * @returns {Promise<User>}
+     * @throws {TiException.E_SEC_UNRECOGNIZED_AUTH_METHOD} If the authentication method is not recognized.
+     * @public
+     */
+    authorize(authMethod: TiAuthMethod, currentUrl: URL, oidc: Object): Promise<User>;
+    /**
+     * Used to get the callback URL for the specified OAuth2 authentication method.
+     *
+     * @method
+     * @param {TiAuthMethod} authMethod
+     * @returns {string}
+     * @throws {TiException.E_SEC_UNRECOGNIZED_AUTH_METHOD} If the requested OAuth2 method is not recognized or enabled.
+     * @public
+     */
+    getOAuth2CallbackUrl(authMethod: TiAuthMethod): string;
+    /**
+     * Used to get the local route path of the callback for the specified OAuth2 authentication method.
+     * <br/>
+     * A callback can legitimately be configured either as a path or as the full absolute URL registered with the
+     * identity provider. The absolute form is what the provider expects as the redirect URI, but it is not a usable
+     * Express route pattern, so this reduces whatever is configured to the path the server must actually listen on.
+     *
+     * @method
+     * @param {TiAuthMethod} authMethod
+     * @returns {string|null} The route path, or null if the configured callback yields no usable path.
+     * @throws {TiException.E_SEC_UNRECOGNIZED_AUTH_METHOD} If the requested OAuth2 method is not recognized or enabled.
+     * @public
+     */
+    getOAuth2CallbackPath(authMethod: TiAuthMethod): string | null;
+    /**
+     * Reduces a configured OAuth2 callback value to the local route path it corresponds to. Accepts an absolute URL
+     * ('https://host/login/azure-callback'), a protocol-relative URL, or a path with or without its leading slash,
+     * and strips any query string or fragment. Pure and static; exposed for unit testing.
+     * <br/>
+     * NOTE: This exists because Express 5 parses a route pattern with path-to-regexp v8, where ':' opens a parameter
+     * name — so an absolute URL used verbatim as a route path throws 'Missing parameter name' at startup.
+     *
+     * @method
+     * @static
+     * @param {string} callbackUrl
+     * @returns {string|null} The route path, or null if no usable path can be derived.
+     * @public
+     */
+    static toCallbackPath(callbackUrl: string): string | null;
+}
+declare namespace AuthManager {
+    export { authMethodEnum as authMethod };
+}

package/types/components/authorization.d.ts

@@ -0,0 +1,54 @@
+declare const _exports: {
+    ADMIN_ROLE: string;
+    isAdminIdentity: typeof isAdminIdentity;
+    applyAdminRole: typeof applyAdminRole;
+    hasAnyRole: typeof hasAnyRole;
+    isAccessAllowed: typeof isAccessAllowed;
+    requireRole: typeof requireRole;
+    requireAdmin: (request: Object, response: Object, next: Function) => void;
+};
+export = _exports;
+/**
+ * Returns `true` if the user matches any entry in the admin allowlist. An entry may match the user's `userID`,
+ * `username`, or `email` (case-insensitive).
+ *
+ * @param {Object} user A session user (`{ userID, username, email, roles, ... }`).
+ * @param {string[]} admins The configured allowlist of admin identifiers.
+ * @returns {boolean}
+ */
+declare function isAdminIdentity(user: Object, admins: string[]): boolean;
+/**
+ * Adds the `admin` role to the session user (additively, no duplicates) when the user is in the allowlist.
+ * Safe to call with an empty/missing allowlist or session — it is then a no-op. Returns the session for chaining.
+ *
+ * @param {Object} session
+ * @param {string[]} [admins]
+ * @returns {Object} The (possibly modified) session.
+ */
+declare function applyAdminRole(session: Object, admins?: string[]): Object;
+/**
+ * @param {Object} session
+ * @param {Array<string|number>} roles
+ * @returns {boolean} `true` if the session user holds any of the given roles.
+ */
+declare function hasAnyRole(session: Object, roles: Array<string | number>): boolean;
+/**
+ * Pure access decision for a resource (e.g. an HTML fragment) that declares a set of required roles. A resource with
+ * no required roles (`null` / `undefined` / empty) is public — any (authenticated) user may access it; otherwise the
+ * user must hold at least one of the required roles. Roles are treated opaquely, so this works equally for numeric
+ * application role codes and the string `admin` role — there is no implicit hierarchy (an `admin`-gated resource is
+ * reachable only by holders of the `admin` role, never by a high numeric role). Backs {@link TiWebAppManager#verifyAccess}.
+ *
+ * @param {Array<string|number>} [requiredRoles] The roles permitted to access the resource; empty/absent = public.
+ * @param {Array<string|number>} [userRoles] The roles held by the current session user.
+ * @returns {boolean}
+ */
+declare function isAccessAllowed(requiredRoles?: Array<string | number>, userRoles?: Array<string | number>): boolean;
+/**
+ * Express middleware factory that admits a request only if its session user holds at least one of the given roles.
+ * Responds `401` when unauthenticated (no session user) and `403` when authenticated but lacking the role.
+ *
+ * @param {...(string|number)} roles
+ * @returns {(request: Object, response: Object, next: Function) => void}
+ */
+declare function requireRole(...roles: (string | number)[]): (request: Object, response: Object, next: Function) => void;

package/types/components/config-change-notifier.d.ts

@@ -0,0 +1,73 @@
+export = ConfigChangeNotifier;
+export type ConfigChangeEvent = {
+    changeSetID: string;
+    /**
+     * The configuration documents affected by the change.
+     */
+    configKeys: string[];
+    /**
+     * Who committed the change.
+     */
+    adminID: string;
+    /**
+     * ISO timestamp.
+     */
+    timestamp: string;
+};
+/**
+ * @typedef {Object} ConfigChangeEvent
+ * @property {string} changeSetID
+ * @property {string[]} configKeys The configuration documents affected by the change.
+ * @property {string} adminID Who committed the change.
+ * @property {string} timestamp ISO timestamp.
+ */
+declare const CONFIG_CHANGED = "config:changed";
+/**
+ * Notifies subscribers that configuration changed, so they can react (e.g. invalidate an in-memory cache, or push a
+ * live update to an admin UI). This is the **in-process** implementation of a deliberately transport-agnostic
+ * contract — `publish(event)` (fire-and-forget) and `subscribe(listener) → unsubscribe`.
+ *
+ * **Designed for an eventual switch to a reusable core pub/sub.** Cross-instance propagation is out of scope for v1
+ * (the store-backed model already makes a committed change visible to every instance via the shared Redis cache;
+ * this emitter exists to invalidate optional *in-memory* caches and drive live UI within a process). When a Redis
+ * (or other) pub/sub primitive lands in `@ti-engine/core`, a drop-in implementation of this same contract can be
+ * provided and injected into {@link ConfigService} — no change to publishers or subscribers. To keep that swap
+ * behavior-safe, **delivery here is already asynchronous** (matching cross-instance transports); subscribers must
+ * not assume synchronous delivery, and the event payload is plain serializable JSON so it survives a wire transport.
+ *
+ * @class ConfigChangeNotifier
+ * @public
+ */
+declare class ConfigChangeNotifier {
+    #private;
+    constructor();
+    /**
+     * Publishes a configuration-change event to all subscribers. Fire-and-forget; delivery is asynchronous.
+     *
+     * @method
+     * @param {ConfigChangeEvent} event
+     * @returns {ConfigChangeEvent} The (frozen) event that will be delivered.
+     * @public
+     */
+    publish(event: ConfigChangeEvent): ConfigChangeEvent;
+    /**
+     * Subscribes a listener to configuration-change events.
+     *
+     * @method
+     * @param {(event: ConfigChangeEvent) => void} listener
+     * @returns {() => void} An unsubscribe function.
+     * @public
+     */
+    subscribe(listener: (event: ConfigChangeEvent) => void): () => void;
+    /**
+     * @method
+     * @returns {number} The current number of subscribers.
+     * @public
+     */
+    subscriberCount(): number;
+}
+declare namespace ConfigChangeNotifier {
+    export { instance };
+    export { CONFIG_CHANGED };
+}
+declare const instance: ConfigChangeNotifier;