@ti-engine/web-framework 1.19.0 → 1.20.0

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

@@ -0,0 +1,149 @@
+export = ConfigRegistry;
+export type ConfigValidationIssue = {
+    /**
+     * A JSON pointer / data path to the offending value (e.g. ".competencies.E1-1.name"), or "".
+     */
+    path: string;
+    /**
+     * Human-readable problem description.
+     */
+    message: string;
+    /**
+     * "schema" for JSON-Schema failures, or a validator-supplied code (default "semantic").
+     */
+    code: string;
+    /**
+     * Optional structured details (e.g. ajv params).
+     */
+    params?: Object;
+};
+export type ValidatorContext = {
+    /**
+     * Resolves the *pending* value of `key` when it is part of the
+     * current edit batch, otherwise its current committed value. Lets a validator check a sibling document's
+     * post-edit state — but calling this for the document being validated itself just returns the same incoming
+     * value already passed as the validator's first argument, not its prior state.
+     */
+    getConfig: (key: string) => Promise<any>;
+    /**
+     * Always resolves the current committed value of `key`,
+     * even when `key` is the document currently under validation. Use this to compare a document against its own
+     * previous state (e.g. detecting an edit that should have bumped a version marker).
+     */
+    getStoredConfig: (key: string) => Promise<any>;
+};
+export type SemanticValidator = (value: Object, context: ValidatorContext) => ConfigValidationIssue[] | Promise<ConfigValidationIssue[]>;
+/**
+ * @typedef {Object} ConfigValidationIssue
+ * @property {string} path A JSON pointer / data path to the offending value (e.g. ".competencies.E1-1.name"), or "".
+ * @property {string} message Human-readable problem description.
+ * @property {string} code "schema" for JSON-Schema failures, or a validator-supplied code (default "semantic").
+ * @property {Object} [params] Optional structured details (e.g. ajv params).
+ */
+/**
+ * The cross-document read context passed to every {@link SemanticValidator}, built fresh for each
+ * {@link ConfigService#applyEdits} call.
+ *
+ * @typedef {Object} ValidatorContext
+ * @property {(key: string) => Promise<*>} getConfig Resolves the *pending* value of `key` when it is part of the
+ *      current edit batch, otherwise its current committed value. Lets a validator check a sibling document's
+ *      post-edit state — but calling this for the document being validated itself just returns the same incoming
+ *      value already passed as the validator's first argument, not its prior state.
+ * @property {(key: string) => Promise<*>} getStoredConfig Always resolves the current committed value of `key`,
+ *      even when `key` is the document currently under validation. Use this to compare a document against its own
+ *      previous state (e.g. detecting an edit that should have bumped a version marker).
+ */
+/**
+ * @typedef {(value: Object, context: ValidatorContext) => ConfigValidationIssue[]|Promise<ConfigValidationIssue[]>} SemanticValidator
+ * A semantic validator receives the candidate value and a {@link ValidatorContext} and returns the issues it found
+ * (empty array = OK). May be async.
+ */
+/**
+ * Registry of editable configuration *documents* and the gate that validates a candidate value against a
+ * document's JSON Schema (ajv) plus its semantic validators. The framework stays domain-agnostic: an application
+ * registers its config documents (schemas, validators, defaults, editor metadata) at startup; this component knows
+ * only "validated, versioned JSON documents". Validation must pass *before* {@link ConfigStore#saveChangeSet}.
+ *
+ * @class ConfigRegistry
+ * @public
+ */
+declare class ConfigRegistry {
+    #private;
+    constructor();
+    /**
+     * Registers an editable configuration document.
+     *
+     * @method
+     * @param {string} configKey Stable identifier for the document (also the ConfigStore key).
+     * @param {Object} definition
+     * @param {Object} definition.schema A JSON Schema for the document.
+     * @param {SemanticValidator[]} [definition.validators] Cross-cutting/semantic checks beyond the schema.
+     * @param {Object} [definition.defaultValue] The bootstrap default (seeds an empty store).
+     * @param {Object} [definition.metadata] Editor metadata (label, editor type, group, risk class, …).
+     * @returns {ConfigRegistry} this (chainable)
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} On missing key/schema.
+     * @public
+     */
+    register(configKey: string, definition: {
+        schema: Object;
+        validators?: SemanticValidator[];
+        defaultValue?: Object;
+        metadata?: Object;
+    }): ConfigRegistry;
+    /**
+     * Adds a schema that is referenced (via `$ref`/`$id`) by document schemas but is not itself a document.
+     *
+     * @method
+     * @param {Object} schema
+     * @returns {ConfigRegistry} this (chainable)
+     * @public
+     */
+    addSchema(schema: Object): ConfigRegistry;
+    /**
+     * @method
+     * @param {string} configKey
+     * @returns {boolean}
+     * @public
+     */
+    has(configKey: string): boolean;
+    /**
+     * @method
+     * @returns {string[]} All registered configuration keys.
+     * @public
+     */
+    list(): string[];
+    /**
+     * @method
+     * @param {string} configKey
+     * @returns {Object|undefined} The editor metadata registered for the document.
+     * @public
+     */
+    metadataFor(configKey: string): Object | undefined;
+    /**
+     * @method
+     * @param {string} configKey
+     * @returns {Object|undefined} The bootstrap default value registered for the document.
+     * @public
+     */
+    getDefault(configKey: string): Object | undefined;
+    /**
+     * Validates a candidate value for a registered document: JSON Schema first, then the semantic validators.
+     * Resolves with `{ valid, errors }` (errors is an array of {@link ConfigValidationIssue}).
+     *
+     * @method
+     * @param {string} configKey
+     * @param {Object} value
+     * @param {ValidatorContext} [context] Passed to each semantic validator.
+     * @returns {Promise<{valid: boolean, errors: ConfigValidationIssue[]}>}
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} If the document is not registered.
+     * @public
+     */
+    validate(configKey: string, value: Object, context?: ValidatorContext): Promise<{
+        valid: boolean;
+        errors: ConfigValidationIssue[];
+    }>;
+}
+declare namespace ConfigRegistry {
+    export { instance };
+}
+declare const instance: ConfigRegistry;

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

@@ -0,0 +1,218 @@
+export = ConfigService;
+import type ConfigChangeNotifier from "#config-change-notifier";
+import type ConfigRegistry from "#config-registry";
+import type ConfigStore from "#config-store";
+/** @import ConfigChangeNotifier from "#config-change-notifier" */
+/** @import ConfigRegistry from "#config-registry" */
+/** @import ConfigStore from "#config-store" */
+/**
+ * Orchestrates validated, versioned configuration edits on top of {@link ConfigStore} and {@link ConfigRegistry}.
+ *
+ * Two layers:
+ *  - **Document level** — {@link ConfigService#applyEdits}: validate every affected document (schema + semantic,
+ *    with a cross-document {@link ValidatorContext} whose `getConfig` sees the *pending* values of the same edit —
+ *    letting a validator check a sibling document's post-edit state — while `getStoredConfig` always returns the
+ *    committed value, even for the document currently under validation) and, only if all pass, commit them as one
+ *    change-set. Validation failures return `{ ok:false, errors }` and write nothing; a version conflict from the
+ *    store surfaces as a rejection.
+ *  - **Entity level** — composite editors registered with `compose(docs)→view` / `decompose(edited, docs)→{key:value}`,
+ *    so the UI edits a domain entity (e.g. a "competency") that is projected from, and scattered back into, several
+ *    documents. {@link ConfigService#saveEditorEdit} decomposes the edit and routes it through `applyEdits`.
+ *
+ * @class ConfigService
+ * @public
+ */
+declare class ConfigService {
+    #private;
+    /**
+     * @constructor
+     * @param {Object} [options]
+     * @param {ConfigStore} [options.store] Defaults to the ConfigStore singleton.
+     * @param {ConfigRegistry} [options.registry] Defaults to the ConfigRegistry singleton.
+     * @param {ConfigChangeNotifier} [options.notifier] Defaults to the ConfigChangeNotifier singleton.
+     */
+    constructor(options?: {
+        store?: ConfigStore;
+        registry?: ConfigRegistry;
+        notifier?: ConfigChangeNotifier;
+    });
+    /**
+     * Validates and commits a set of document edits atomically. 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<{ok: true, changeSetID: string, versions: Object<string, number>} | {ok: false, errors: Object<string, Array>}>}
+     * @public
+     */
+    applyEdits(edits: Array<{
+        configKey: string;
+        value: Object;
+        expectedVersion: number;
+    }>, meta: {
+        adminID: string;
+        note?: string;
+    }): Promise<{
+        ok: true;
+        changeSetID: string;
+        versions: Record<string, number>;
+    } | {
+        ok: false;
+        errors: Record<string, any[]>;
+    }>;
+    /**
+     * Registers a composite editor over one or more documents.
+     *
+     * @method
+     * @param {string} editorKey
+     * @param {Object} definition
+     * @param {string[]} definition.documents The configKeys this editor spans.
+     * @param {(configs: Object) => *} definition.compose Maps `{ [configKey]: value }` → a view for the UI.
+     * @param {(editedView: *, currentDocs: Object) => Object.<string, Object>} definition.decompose Maps `(editedView, currentDocs)` → the
+     *        full new values for the documents that changed (`{ [configKey]: newValue }`).
+     * @param {Object} [definition.metadata]
+     * @returns {ConfigService} this (chainable)
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS}
+     * @public
+     */
+    registerEditor(editorKey: string, definition: {
+        documents: string[];
+        compose: (configs: Object) => any;
+        decompose: (editedView: any, currentDocs: Object) => Record<string, Object>;
+        metadata?: Object;
+    }): ConfigService;
+    /**
+     * @method
+     * @param {string} editorKey
+     * @returns {boolean}
+     * @public
+     */
+    hasEditor(editorKey: string): boolean;
+    /**
+     * @method
+     * @returns {string[]}
+     * @public
+     */
+    listEditors(): string[];
+    /**
+     * Loads the editor's documents and composes them into a view. Returns the view plus the current per-document
+     * versions, which the client must echo back on save for optimistic locking.
+     *
+     * @method
+     * @param {string} editorKey
+     * @returns {Promise<{rows: *, versions: Object<string, number>}>}
+     * @public
+     */
+    composeView(editorKey: string): Promise<{
+        rows: any;
+        versions: Record<string, number>;
+    }>;
+    /**
+     * Applies an edit made against a composite editor: decompose the edited view into per-document new values, then
+     * route through {@link ConfigService#applyEdits} (validate-all → atomic change-set). `expectedVersions` should be
+     * the versions returned by {@link ConfigService#composeView} when the edit started.
+     *
+     * @method
+     * @param {string} editorKey
+     * @param {*} editedView
+     * @param {Object} meta
+     * @param {Object<string, number>} [expectedVersions]
+     * @returns {Promise<Object>} The {@link ConfigService#applyEdits} result (or `{ ok:true, changeSetID:null }` if nothing changed).
+     * @public
+     */
+    saveEditorEdit(editorKey: string, editedView: any, meta: Object, expectedVersions?: Record<string, number>): Promise<Object>;
+    /**
+     * Restores a prior change-set through the validated path: rebuild edits from the change-set's historic snapshots
+     * and route them through {@link ConfigService#applyEdits} — so the restore is **re-validated against the current
+     * schemas/validators** (a snapshot valid when written may be invalid now) and emits `config:changed`. Returns the
+     * `applyEdits` result (`{ ok:false, errors }` if a snapshot no longer validates; nothing is written then).
+     *
+     * @method
+     * @param {string} changeSetID
+     * @param {Object} meta
+     * @param {string} meta.adminID
+     * @param {string} [meta.note]
+     * @returns {Promise<Object>}
+     * @public
+     */
+    restoreChangeSet(changeSetID: string, meta: {
+        adminID: string;
+        note?: string;
+    }): Promise<Object>;
+    /**
+     * @method
+     * @param {string} configKey
+     * @returns {Promise<Object|null>} The current envelope for a configuration document.
+     * @public
+     */
+    getCurrent(configKey: string): Promise<Object | null>;
+    /**
+     * @method
+     * @param {string} configKey
+     * @returns {Promise<Array<Object>>} The document's version history (ascending), each a full snapshot entry.
+     * @public
+     */
+    getHistory(configKey: string): Promise<Array<Object>>;
+    /**
+     * @method
+     * @param {string} changeSetID
+     * @returns {Promise<Object|null>} A single change-set record.
+     * @public
+     */
+    getChange(changeSetID: string): Promise<Object | null>;
+    /**
+     * @method
+     * @returns {Promise<Array<Object>>} The cross-document audit feed (change-sets, most-recent first).
+     * @public
+     */
+    listChanges(): Promise<Array<Object>>;
+    /**
+     * Builds a downloadable snapshot of the current live configuration — for every registered document, its repo file
+     * `path` (from registration metadata, if provided), current `version`, and `value`. This is the one-way export
+     * *out* of the store; an admin downloads it and commits the files to git. The store remains the live truth.
+     *
+     * @method
+     * @param {Object} [meta]
+     * @param {string} [meta.adminID]
+     * @returns {Promise<{exportedAt: string, exportedBy: (string|null), documents: Array<{configKey: string, path: (string|null), version: number, value: Object}>}>}
+     * @public
+     */
+    exportBundle(meta?: {
+        adminID?: string;
+    }): Promise<{
+        exportedAt: string;
+        exportedBy: (string | null);
+        documents: Array<{
+            configKey: string;
+            path: (string | null);
+            version: number;
+            value: Object;
+        }>;
+    }>;
+    /**
+     * Seeds a document's default value into the store only if it has never been written (idempotent bootstrap).
+     * Used by an application to bring its file defaults into the store at startup before serving live config.
+     *
+     * @method
+     * @param {string} configKey
+     * @param {Object} defaultValue
+     * @returns {Promise<Object>} The current envelope.
+     * @public
+     */
+    seedDefault(configKey: string, defaultValue: Object): Promise<Object>;
+    /**
+     * Subscribes a listener to `config:changed` events (delegates to the change notifier). Returns an unsubscribe fn.
+     *
+     * @method
+     * @param {(configs: Object) => void} listener
+     * @returns {() => void}
+     * @public
+     */
+    onConfigChanged(listener: (configs: Object) => void): () => void;
+}
+declare namespace ConfigService {
+    export { instance };
+}
+declare const instance: ConfigService;

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;