@ti-engine/web-framework 1.19.1 → 1.20.1

package/types/components/config-store.d.ts

@@ -0,0 +1,128 @@
+export = ConfigStore;
+/**
+ * A versioned, change-set-aware configuration store backed by the common memory cache (RedisJSON).
+ * <br/>
+ * Each editable configuration is a *document* identified by a `configKey`. Every committed edit:
+ *  - bumps the document's monotonic `version`,
+ *  - writes a full **snapshot** to history (enabling restore),
+ *  - and is correlated with the other documents written in the same logical edit via a shared **change-set** id,
+ *    so a multi-document edit (and its restore) is treated as one unit even though storage is per-document.
+ * <br/>
+ * Optimistic locking: callers pass the `expectedVersion` they edited from; the save is rejected if any document
+ * moved on in the meantime. This component is storage-only — schema/semantic validation is a separate pipeline
+ * that must run *before* {@link ConfigStore#saveChangeSet}.
+ * <br/>
+ * NOTE: true cross-document atomicity is not provided (the cache exposes per-key commands only). All locks are
+ * checked *before* any write, so the common conflict case is safe; a mid-write process failure can leave a
+ * partially-applied change-set, detectable via the change-set record. Hardening (a Lua/MULTI write) is deferred.
+ *
+ * @class ConfigStore
+ * @public
+ */
+declare class ConfigStore {
+    #private;
+    /**
+     * Returns the current envelope `{ value, version, updatedAt, updatedBy, changeSetID }` for a configuration
+     * document, or `null` if it has never been written.
+     *
+     * @method
+     * @param {string} configKey
+     * @returns {Promise<Object|null>}
+     * @public
+     */
+    getCurrent(configKey: string): Promise<Object | null>;
+    /**
+     * Writes the default value as version 1 only if the document does not yet exist (idempotent bootstrap).
+     * Resolves with the current envelope either way.
+     *
+     * @method
+     * @param {string} configKey
+     * @param {Object} defaultValue
+     * @returns {Promise<Object>}
+     * @public
+     */
+    seedIfEmpty(configKey: string, defaultValue: Object): Promise<Object>;
+    /**
+     * Commits an edit spanning one or more documents as a single change-set. All optimistic-lock checks run before
+     * any write. Each edit: `{ configKey, value, expectedVersion }`.
+     *
+     * @method
+     * @param {Array<{configKey: string, value: Object, expectedVersion: number}>} edits
+     * @param {Object} meta
+     * @param {string} meta.adminID
+     * @param {string} [meta.note]
+     * @returns {Promise<{changeSetID: string, versions: Object<string, number>}>}
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} On bad input or a version conflict (see `details`).
+     * @public
+     */
+    saveChangeSet(edits: Array<{
+        configKey: string;
+        value: Object;
+        expectedVersion: number;
+    }>, meta: {
+        adminID: string;
+        note?: string;
+    }): Promise<{
+        changeSetID: string;
+        versions: Record<string, number>;
+    }>;
+    /**
+     * Returns all history entries for a document, ascending by version.
+     *
+     * @method
+     * @param {string} configKey
+     * @returns {Promise<Array<Object>>}
+     * @public
+     */
+    listHistory(configKey: string): Promise<Array<Object>>;
+    /**
+     * Returns a single history snapshot entry for a document version, or `null`.
+     *
+     * @method
+     * @param {string} configKey
+     * @param {number} version
+     * @returns {Promise<Object|null>}
+     * @public
+     */
+    getVersion(configKey: string, version: number): Promise<Object | null>;
+    /**
+     * Returns a change-set record by id, or `null`.
+     *
+     * @method
+     * @param {string} changeSetID
+     * @returns {Promise<Object|null>}
+     * @public
+     */
+    getChangeSet(changeSetID: string): Promise<Object | null>;
+    /**
+     * Returns every change-set record, most-recent first (the cross-document audit feed).
+     *
+     * @method
+     * @returns {Promise<Array<Object>>}
+     * @public
+     */
+    listChangeSets(): Promise<Array<Object>>;
+    /**
+     * Restores every document in a prior change-set to that change-set's snapshot, committing it as a *new*
+     * change-set (restore is never destructive — it moves forward to a past state).
+     *
+     * @method
+     * @param {string} changeSetID
+     * @param {Object} meta
+     * @param {string} meta.adminID
+     * @param {string} [meta.note]
+     * @returns {Promise<{changeSetID: string, versions: Object<string, number>}>}
+     * @public
+     */
+    restoreChangeSet(changeSetID: string, meta: {
+        adminID: string;
+        note?: string;
+    }): Promise<{
+        changeSetID: string;
+        versions: Record<string, number>;
+    }>;
+}
+declare namespace ConfigStore {
+    var _a: Readonly<ConfigStore>;
+    export { _a as instance };
+}

package/types/components/definitions.types.d.ts

@@ -0,0 +1,31 @@
+import type { TiLocalizationLanguage } from "@ti-engine/core/localization";
+export type TiSessionCallback = (error?: Error | null) => void;
+export type TiSession = {
+    id: string;
+    user?: Object;
+    language?: TiLocalizationLanguage;
+    cookie?: Object;
+    oidc?: Object;
+    csrfToken?: string;
+    regenerate: (callback: TiSessionCallback) => TiSession;
+    destroy: (callback: TiSessionCallback) => TiSession;
+    save: (callback?: TiSessionCallback) => TiSession;
+};
+/** @import { TiLocalizationLanguage } from "@ti-engine/core/localization" */
+/**
+ * @callback TiSessionCallback
+ * @param {Error|null} [error]
+ * @returns {void}
+ */
+/**
+ * @typedef {Object} TiSession
+ * @property {string} id
+ * @property {Object} [user]
+ * @property {TiLocalizationLanguage} [language]
+ * @property {Object} [cookie]
+ * @property {Object} [oidc]
+ * @property {string} [csrfToken]
+ * @property {(callback: TiSessionCallback) => TiSession} regenerate
+ * @property {(callback: TiSessionCallback) => TiSession} destroy
+ * @property {(callback?: TiSessionCallback) => TiSession} save
+ */

package/types/components/session-store.d.ts

@@ -0,0 +1,56 @@
+export = SessionStore;
+import session = require("express-session");
+import type { SessionData } from "express-session";
+import type { TiException } from "@ti-engine/core/exceptions";
+/**
+ * A session store for the web server using the standard 'cache' module of the ti-engine.
+ * <br/>
+ * NOTE: This implementation is compatible with the 'express-session' module.
+ *
+ * @class SessionStore
+ * @public
+ */
+declare class SessionStore extends session.Store {
+    /**
+     * @constructor
+     */
+    constructor();
+    /**
+     * Used to store a user session in the cache.
+     *
+     * @method
+     * @param {string} sessionID
+     * @param {SessionData} session
+     * @param {(error?: Error|TiException|null) => void} callback
+     * @public
+     */
+    set(sessionID: string, session: SessionData, callback: (error?: Error | TiException | null) => void): void;
+    /**
+     * Used to retrieve a user session from the cache.
+     *
+     * @method
+     * @param {string} sessionID
+     * @param {(error?: Error|TiException|null, session?: SessionData|null) => void} callback
+     * @public
+     */
+    get(sessionID: string, callback: (error?: Error | TiException | null, session?: SessionData | null) => void): void;
+    /**
+     * Used to remove a user session from the cache.
+     *
+     * @method
+     * @param {string} sessionID
+     * @param {(error?: Error|TiException|null) => void} callback
+     * @public
+     */
+    destroy(sessionID: string, callback: (error?: Error | TiException | null) => void): void;
+    /**
+     * Used to update the expiration time of a user session in the cache.
+     *
+     * @method
+     * @param {string} sessionID
+     * @param {SessionData} session
+     * @param {(error?: Error|TiException|null) => void} callback
+     * @public
+     */
+    touch(sessionID: string, session: SessionData, callback: (error?: Error | TiException | null) => void): void;
+}

package/types/components/user.d.ts

@@ -0,0 +1,83 @@
+export = User;
+import type { TiLocalizationLanguage } from "@ti-engine/core/localization";
+/** @import { TiLocalizationLanguage } from "@ti-engine/core/localization" */
+/**
+ * Represents a user in the system.
+ *
+ * @class User
+ * @public
+ */
+declare class User {
+    #private;
+    /**
+     * @constructor
+     * @param {Object} userData
+     * @param {string} userData.userID
+     * @param {string} [userData.username]
+     * @param {string} [userData.email]
+     * @param {string} [userData.name]
+     * @param {TiLocalizationLanguage} [userData.language]
+     * @param {string[]} [userData.roles]
+     * @param {string[]} [userData.permissions]
+     * @param {Object} [userData.details]
+     */
+    constructor(userData?: {
+        userID: string;
+        username?: string;
+        email?: string;
+        name?: string;
+        language?: TiLocalizationLanguage;
+        roles?: string[];
+        permissions?: string[];
+        details?: Object;
+    });
+    /**
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get userID(): string;
+    /**
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get username(): string;
+    /**
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get email(): string;
+    /**
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get name(): string;
+    /**
+     * @property
+     * @returns {TiLocalizationLanguage}
+     * @public
+     */
+    get language(): TiLocalizationLanguage;
+    /**
+     * @method
+     * @returns {*}
+     * @public
+     */
+    getDetail(key: any): any;
+    /**
+     * @method
+     * @param {string} key
+     * @param {*} value
+     * @public
+     */
+    setDetail(key: string, value: any): void;
+    /**
+     * @method
+     * @returns {Object}
+     * @public
+     */
+    asJSON(): Object;
+}

package/types/components/web-config-env.d.ts

@@ -0,0 +1,17 @@
+export = applyWebConfigEnvOverrides;
+/**
+ * Applies TI_WEB_* environment-variable overrides onto an (already-merged) web server configuration object.
+ * Each override is applied ONLY when its environment variable is defined, so an absent variable leaves the
+ * configured/default value untouched (fully backward compatible). This gives ti-engine web servers 12-factor,
+ * container-friendly control over network binding, TLS, the session cookie secret, the enabled authentication
+ * methods, the admin allowlist, the trusted request origins, and the `/static` cache policy without editing config files. Note `TI_WEB_AUTH_METHODS`,
+ * `TI_WEB_AUTH_ADMINS`, `TI_WEB_TRUSTED_ORIGINS`, and `TI_WEB_STATIC_IMMUTABLE_PATHS` fully REPLACE their config arrays (`auth.enabledMethods` / `auth.admins` / `trustedOrigins` / `staticCache.immutablePaths`) rather than
+ * merging — the config-file merge is by-index and cannot cleanly override an array.
+ *
+ * @method
+ * @param {Object} config The web server configuration to augment (mutated in place and returned).
+ * @param {Object} [env=process.env] The environment source (injectable for testing).
+ * @returns {Object} The same config object, with any present overrides applied.
+ * @public
+ */
+declare function applyWebConfigEnvOverrides(config: Object, env?: Object): Object;

package/types/components/web-handlers.d.ts

@@ -0,0 +1,23 @@
+export declare var onShutDownHandler: (instance: TiWebServer) => ExpressHandler;
+export declare var resourceProtectionHandler: (instance: TiWebServer) => ExpressHandler;
+export declare var authenticationHandler: (instance: TiWebServer) => ExpressHandler;
+export declare var authorizedOAuth2CallbackHandler: (instance: TiWebServer, authMethod: TiAuthMethod) => ExpressHandler;
+export declare var logoutHandler: () => ExpressHandler;
+export declare var healthHandler: () => ExpressHandler;
+export declare var userInformationHandler: () => ExpressHandler;
+export declare var httpRedirectHandler: (instance: TiWebServer) => ExpressHandler;
+export declare var serviceCallHandler: (instance: TiWebServer) => ExpressHandler;
+export declare var invalidRouteHandler: () => ExpressHandler;
+export declare var defaultErrorHandler: () => ExpressErrorHandler;
+export declare var nonceGenerationHandler: () => ExpressHandler;
+export declare var cspHeaderHandler: () => ExpressHandler;
+export declare var webAppHandler: (instance: TiWebServer) => ExpressHandler;
+export declare var originRefererValidationHandler: (instance: any) => ExpressHandler;
+export declare var csrfInitHandler: (instance: TiWebServer) => ExpressHandler;
+export declare var csrfProtectionHandler: () => ExpressHandler;
+import type { TiAuthMethod } from "#auth-manager";
+import type TiWebServer from "#web-server";
+export type ExpressRequest = import("express").Request;
+export type ExpressResponse = import("express").Response;
+export type ExpressHandler = (request: ExpressRequest, response: ExpressResponse, next: (error: Error | null) => void) => void;
+export type ExpressErrorHandler = (error: Error, request: ExpressRequest, response: ExpressResponse, next: (error: Error | null) => void) => void;