@ti-engine/web-framework 1.21.0 → 1.24.0

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

@@ -191,6 +191,65 @@ declare class ConfigService {
             value: Object;
         }>;
     }>;
+    /**
+     * Compares a document's registered file default against the value currently in the store. This is how a
+     * configuration change shipped in a release becomes visible on a deployment that was seeded before it — the
+     * store seeds only once, so a later file change is otherwise invisible.
+     *
+     * @method
+     * @param {string} configKey
+     * @returns {Promise<{configKey: string, status: string, counts: Object, entries: Array, storedVersion: number, editable: boolean, label: string}>}
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} If the document is not registered.
+     * @public
+     */
+    getDrift(configKey: string): Promise<{
+        configKey: string;
+        status: string;
+        counts: Object;
+        entries: any[];
+        storedVersion: number;
+        editable: boolean;
+        label: string;
+    }>;
+    /**
+     * Drift summaries for every registered document. This still computes each document's full entry list internally
+     * (it delegates to {@link ConfigService#getDrift} per document) — the saving is in the response shape, not the
+     * computation: `entries` is omitted here to keep the payload small enough for a landing screen and a startup log,
+     * where only the counts are shown.
+     *
+     * @method
+     * @returns {Promise<Array<Object>>}
+     * @public
+     */
+    listDrift(): Promise<Array<Object>>;
+    /**
+     * Applies the registered file defaults for the given documents, as a single validated change-set.
+     * <br/>
+     * Routing through {@link ConfigService#applyEdits} is deliberate: the application is schema- and
+     * semantically validated, versioned, correlated into one change-set, added to the audit feed, and restorable —
+     * and, because a validator sees its siblings at their *pending* value, interdependent documents applied
+     * together validate against each other rather than against the stale stored state.
+     *
+     * @method
+     * @param {string[]} configKeys
+     * @param {Object} meta
+     * @param {string} meta.adminID
+     * @param {string} [meta.note]
+     * @returns {Promise<{ok: true, changeSetID: string, versions: Object}|{ok: false, errors: Object}>}
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} On bad input, an unknown key, or a key with no default.
+     * @public
+     */
+    applyDefaults(configKeys: string[], meta: {
+        adminID: string;
+        note?: string;
+    }): Promise<{
+        ok: true;
+        changeSetID: string;
+        versions: Object;
+    } | {
+        ok: false;
+        errors: 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.

package/types/components/local-user-directory.d.ts

@@ -0,0 +1,111 @@
+declare const _exports: {
+    ALGORITHM: string;
+    CACHE_KEY: string;
+    HASH_DEFAULTS: Readonly<{
+        N: 16384;
+        r: 8;
+        p: 1;
+        saltBytes: 16;
+        keyBytes: 64;
+    }>;
+    hashPassword: typeof hashPassword;
+    verifyPassword: typeof verifyPassword;
+    parseRecords: typeof parseRecords;
+    reconcile: typeof reconcile;
+    findByUsername: typeof findByUsername;
+};
+export = _exports;
+export type LocalUserRecord = {
+    userID: string;
+    username: string;
+    email: string;
+    name: string;
+    passwordHash: string;
+    disabled: boolean;
+};
+/**
+ * Hashes a password for storage in a local-users file. Synchronous because its only caller is the one-shot CLI,
+ * where blocking is free — never call it on a request path.
+ *
+ * @method
+ * @param {string} password
+ * @returns {string} The encoded hash: `scrypt$N$r$p$salt$hash`, base64 salt and key.
+ * @throws {TypeError} If `password` is empty or not a string — `verifyPassword` refuses empty passwords, so
+ *         hashing one here would only mint a hash that can never be logged into.
+ * @public
+ */
+declare function hashPassword(password: string): string;
+/**
+ * Verifies a password against an encoded hash. The cost parameters come from the stored string rather than the
+ * current defaults, so raising the defaults never invalidates an existing hash.
+ *
+ * @method
+ * @param {string} password
+ * @param {string} encoded
+ * @returns {Promise<boolean>} `false` for a malformed encoding or an absent password — never a throw, because a
+ *          bad stored value must read as "does not match", not as a server error on the login path.
+ * @public
+ */
+declare function verifyPassword(password: string, encoded: string): Promise<boolean>;
+/**
+ * Validates raw file content into records, reporting why any entry was excluded. Never throws: a malformed row is
+ * data, not a crash, so one bad entry cannot take an instance down.
+ *
+ * @method
+ * @param {*} raw
+ * @returns {{records: LocalUserRecord[], problems: string[]}}
+ * @public
+ */
+declare function parseRecords(raw: any): {
+    records: LocalUserRecord[];
+    problems: string[];
+};
+/**
+ * Writes the records as the complete directory, keyed by username, and reports what changed.
+ * <br/>
+ * The whole set is written rather than patched because the file is the source of truth: a username absent from
+ * `records` must disappear, which is what makes revocation-by-file-edit work. `@ti-engine/core/cache` exposes no
+ * delete, so a whole-object write is also the only way to remove a key.
+ * <br/>
+ * Usernames are attacker-influenceable (the local sign-in handler resolves them from request input), so both the write
+ * and every read below are guarded against `Object.prototype`'s reserved names rather than trusting plain bracket
+ * access:
+ * <br/>
+ * - `incoming` is built with a null prototype (`Object.create( null )`) so it inherits nothing. On an ordinary
+ *   `{}`, `incoming[ "__proto__" ] = record` would not create an own key at all — it would invoke the inherited
+ *   `__proto__` setter and silently repoint the object's own prototype to `record`, so the record never shows up
+ *   in `Object.keys`/`JSON.stringify` and is never persisted, without error. On a null-prototype object that
+ *   setter does not exist anywhere on the (empty) prototype chain, so the assignment falls back to creating a
+ *   perfectly ordinary own data property instead — confirmed empirically (see the test file) that this still
+ *   `JSON.stringify`s and round-trips normally.
+ * - Every classification read below checks ownership with `Object.prototype.hasOwnProperty.call(...)` rather than
+ *   relying on truthiness, because `stored` comes back from `readStored()` — ultimately a `JSON.parse` result —
+ *   with the ordinary `Object.prototype` chain. An unguarded `stored[ "constructor" ]` would resolve to the
+ *   inherited `Object` constructor function (always truthy) rather than "not present", misclassifying a
+ *   first-time `constructor`-named user as `updated` instead of `added`, and hiding its removal from `removed`.
+ *
+ * @method
+ * @param {LocalUserRecord[]} records
+ * @returns {Promise<{added: string[], updated: string[], removed: string[]}>}
+ * @public
+ */
+declare function reconcile(records: LocalUserRecord[]): Promise<{
+    added: string[];
+    updated: string[];
+    removed: string[];
+}>;
+/**
+ * Looks a user up by exact username.
+ * <br/>
+ * `username` here is attacker-influenceable — this is the function the local sign-in handler calls with the
+ * value a client typed into the username field. Checked with `Object.prototype.hasOwnProperty.call(...)` rather than
+ * `stored[ username ] || null`, because `stored` carries the ordinary `Object.prototype` chain and an unguarded
+ * bracket read would resolve `findByUsername( "constructor" )` to the inherited `Object` constructor function
+ * instead of `null`, violating the declared return type for nearly every real query.
+ *
+ * @method
+ * @param {string} username
+ * @returns {Promise<LocalUserRecord|null>}
+ * @public
+ */
+declare function findByUsername(username: string): Promise<LocalUserRecord | null>;

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

@@ -4,7 +4,7 @@ export = applyWebConfigEnvOverrides;
  * 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`,
+ * methods, the admin allowlist, the local auth users file path, 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.
  *