@ti-engine/web-framework 1.20.1 → 1.23.0

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

@@ -13,12 +13,19 @@ export type ApiConfig = {
 };
 export type SettingsAuth = {
     enabledMethods: string[];
-    local: Object;
+    local: SettingsAuthLocal;
     oauth2: {
         azure?: SettingsOAuth2Client;
         google?: SettingsOAuth2Client;
     };
 };
+export type SettingsAuthLocal = {
+    /**
+     * Path to the JSON file of local user records (see `TI_WEB_AUTH_LOCAL_USERS_PATH`).
+     * Local sign-in refuses everyone whenever this is absent, unreadable, or yields no usable records.
+     */
+    usersPath?: string;
+};
 export type SettingsOAuth2Client = {
     clientID?: string;
     clientSecret?: string;
@@ -179,6 +186,11 @@ declare class TiWebServer extends ServiceConsumer {
      * 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.
+     * <br/>
+     * **Refusing a login.** Throwing from this hook refuses the sign-in: the framework destroys the freshly regenerated
+     * session (so no usable session survives the refusal), the login handler raises `401`, and the error handler
+     * redirects the browser to the login page with the exception code in `?error=`. Throw when the authenticated
+     * identity cannot be mapped to an application principal; return the session unchanged to accept it.
      *
      * @method
      * @virtual
@@ -200,6 +212,12 @@ declare class TiWebServer extends ServiceConsumer {
     authenticate(authMethod: TiAuthMethod, authDetails?: Object): Promise<any>;
     /**
      * Used to set up user authorization according to the specified auth method.
+     * <br/>
+     * NOTE: This presupposes a successful, immediately preceding {@link TiWebServer#authenticate} call for the same
+     * credentials — it is **not** an independent authentication check. For the `local` method it builds the session
+     * user from the directory record named by `oidc.username`, verifying that the record exists and is not disabled
+     * but performing no password comparison of its own; the framework's own login route calls `authenticate` first.
+     * Calling this directly without that preceding step would mint a session for any known username.
      *
      * @method
      * @param {TiAuthMethod} authMethod

package/types/components/application-info.d.ts

@@ -0,0 +1,53 @@
+declare const _exports: {
+    buildApplicationInfo: typeof buildApplicationInfo;
+    readApplicationManifest: typeof readApplicationManifest;
+};
+export = _exports;
+import type { TiApplicationInfo } from "#definitions";
+/**
+ * Builds the normalized application-information descriptor that backs the framework "About" screen.
+ * <br/>
+ * The function is PURE — everything it needs is injected — so the whole resolution order (manifest → environment
+ * override) is unit-testable without touching the filesystem or `process.env`. The impure half, reading the
+ * consuming application's manifest, is {@link readApplicationManifest}.
+ * <br/>
+ * Resolution order for the three overridable fields is manifest first, environment last:
+ * - `TI_WEB_APP_NAME` overrides `manifest.displayName` / a display name derived from `manifest.name`;
+ * - `TI_WEB_APP_VERSION` overrides `manifest.version`;
+ * - `TI_WEB_APP_RELEASE_DATE` overrides `manifest.releaseDate`.
+ * <br/>
+ * The environment wins because it is how a container image stamps facts that its baked-in manifest cannot know —
+ * most importantly the build/release date, for which `package.json` has no standard field at all.
+ *
+ * @method
+ * @param {Object} [options]
+ * @param {Object} [options.manifest] A `package.json`-shaped object for the consuming application.
+ * @param {Object} [options.env] The environment source (injectable for testing).
+ * @param {Array<{name: string, version: string}>} [options.components] Framework component versions to list.
+ * @param {Object} [options.runtime] Runtime facts (node/platform/instance). Included verbatim when present; the
+ * caller decides whether the current session is allowed to see them.
+ * @returns {TiApplicationInfo}
+ * @public
+ */
+declare function buildApplicationInfo(options?: {
+    manifest?: Object;
+    env?: Object;
+    components?: Array<{
+        name: string;
+        version: string;
+    }>;
+    runtime?: Object;
+}): TiApplicationInfo;
+/**
+ * Reads the consuming application's `package.json`. This is the one impure function in this module.
+ * <br/>
+ * NOTE: A missing or malformed manifest resolves to an empty object rather than throwing — an informational screen
+ * must never be the reason a request fails, and {@link buildApplicationInfo} produces a usable (if sparse)
+ * descriptor from `{}`.
+ *
+ * @method
+ * @param {string} [directory=process.cwd()] The directory holding the manifest.
+ * @returns {Object}
+ * @public
+ */
+declare function readApplicationManifest(directory?: string): Object;

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

@@ -70,6 +70,13 @@ declare class AuthManager {
     authenticate(authMethod: TiAuthMethod, authDetails: Object): Promise<Object>;
     /**
      * Used to set up user authorization according to the specified authentication method.
+     * <br/>
+     * NOTE: This presupposes a successful, immediately preceding {@link AuthManager#authenticate} call for the
+     * same credentials and is NOT an independent authentication check on its own — for `LOCAL` it performs no
+     * password verification. It refuses an absent, disabled, or (for `LOCAL`) not-yet-usable-directory record,
+     * but a caller that invokes it without having just authenticated bypasses password verification entirely.
+     * The framework's own login route always calls `authenticate()` first (see `web-handlers.js`); this method
+     * is public on both `AuthManager` and `TiWebServer`, so any other caller must preserve that ordering itself.
      *
      * @method
      * @param {TiAuthMethod} authMethod

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

@@ -11,6 +11,112 @@ export type TiSession = {
     destroy: (callback: TiSessionCallback) => TiSession;
     save: (callback?: TiSessionCallback) => TiSession;
 };
+export type TiInfoItem = {
+    label: string;
+    value?: string;
+    /**
+     * Renders the value as a link to this target. Only `http:`, `https:` and `mailto:` are
+     * honoured — any other scheme is dropped client-side and the item degrades to plain text.
+     */
+    href?: string;
+    /**
+     * Span the full width of the section grid instead of one column.
+     */
+    wide?: boolean;
+    /**
+     * Render the value in the monospaced face (IDs, versions, hashes).
+     */
+    mono?: boolean;
+    /**
+     * Render the value as a dimmed hint rather than primary text.
+     */
+    muted?: boolean;
+};
+export type TiInfoSection = {
+    title: string;
+    /**
+     * Optional intro line under the section title.
+     */
+    description?: string;
+    /**
+     * Optional `ti-icon` variant name for the section head.
+     */
+    icon?: string;
+    /**
+     * Claim the full row of the two-up section grid instead of one column.
+     */
+    wide?: boolean;
+    /**
+     * A section with no items is dropped rather than rendered empty.
+     */
+    items: TiInfoItem[];
+};
+export type TiProfileIdentity = {
+    name: string;
+    /**
+     * Meta line under the name (e.g. `role family · specialization · unit`).
+     */
+    subtitle?: string;
+    /**
+     * Secondary line under the subtitle (e.g. the corporate e-mail).
+     */
+    caption?: string;
+    /**
+     * Stable seed for the deterministic avatar colour; defaults to the name.
+     */
+    avatarSeed?: string;
+    /**
+     * Small qualifier rendered inside the meta line.
+     */
+    badge?: {
+        text: string;
+        tone?: string;
+    };
+    /**
+     * Pills beside the name.
+     */
+    tags?: Array<{
+        text: string;
+        tone?: string;
+        dot?: boolean;
+        mono?: boolean;
+    }>;
+};
+export type TiProfileInfo = {
+    identity: TiProfileIdentity;
+    sections: TiInfoSection[];
+};
+export type TiApplicationInfo = {
+    /**
+     * Display name of the application.
+     */
+    name: string;
+    /**
+     * The npm package name it was resolved from.
+     */
+    packageName: string;
+    version: string;
+    releaseDate: string;
+    description: string;
+    license: string;
+    homepage: string;
+    author: string;
+    /**
+     * Framework component versions.
+     */
+    components: Array<{
+        name: string;
+        version: string;
+    }>;
+    /**
+     * Runtime facts (node/platform/instance), or `null` when withheld.
+     */
+    runtime: Object | null;
+    /**
+     * Application-contributed extra sections.
+     */
+    sections: TiInfoSection[];
+};
 /** @import { TiLocalizationLanguage } from "@ti-engine/core/localization" */
 /**
  * @callback TiSessionCallback
@@ -29,3 +135,63 @@ export type TiSession = {
  * @property {(callback: TiSessionCallback) => TiSession} destroy
  * @property {(callback?: TiSessionCallback) => TiSession} save
  */
+/**
+ * One label/value pair inside a {@link TiInfoSection}. Both strings are display-ready — already localized and
+ * already formatted by the server, since that is where the session language and the label catalogue live. The
+ * three flags are purely presentational; an empty `value` renders the screen's placeholder.
+ *
+ * @typedef {Object} TiInfoItem
+ * @property {string} label
+ * @property {string} [value]
+ * @property {string} [href] Renders the value as a link to this target. Only `http:`, `https:` and `mailto:` are
+ * honoured — any other scheme is dropped client-side and the item degrades to plain text.
+ * @property {boolean} [wide] Span the full width of the section grid instead of one column.
+ * @property {boolean} [mono] Render the value in the monospaced face (IDs, versions, hashes).
+ * @property {boolean} [muted] Render the value as a dimmed hint rather than primary text.
+ */
+/**
+ * A titled group of label/value pairs. The framework's Profile and About screens render an array of these
+ * generically, so an application contributes content without contributing layout.
+ *
+ * @typedef {Object} TiInfoSection
+ * @property {string} title
+ * @property {string} [description] Optional intro line under the section title.
+ * @property {string} [icon] Optional `ti-icon` variant name for the section head.
+ * @property {boolean} [wide] Claim the full row of the two-up section grid instead of one column.
+ * @property {TiInfoItem[]} items A section with no items is dropped rather than rendered empty.
+ */
+/**
+ * The identity header of the Profile screen — the avatar/name block and the pills beside it.
+ *
+ * @typedef {Object} TiProfileIdentity
+ * @property {string} name
+ * @property {string} [subtitle] Meta line under the name (e.g. `role family · specialization · unit`).
+ * @property {string} [caption] Secondary line under the subtitle (e.g. the corporate e-mail).
+ * @property {string} [avatarSeed] Stable seed for the deterministic avatar colour; defaults to the name.
+ * @property {{text: string, tone?: string}} [badge] Small qualifier rendered inside the meta line.
+ * @property {Array<{text: string, tone?: string, dot?: boolean, mono?: boolean}>} [tags] Pills beside the name.
+ */
+/**
+ * The descriptor backing the framework Profile screen.
+ *
+ * @typedef {Object} TiProfileInfo
+ * @property {TiProfileIdentity} identity
+ * @property {TiInfoSection[]} sections
+ */
+/**
+ * The descriptor backing the framework About screen. Produced by `buildApplicationInfo` and optionally extended by
+ * the application through {@link TiWebAppManager#getApplicationInfo}.
+ *
+ * @typedef {Object} TiApplicationInfo
+ * @property {string} name Display name of the application.
+ * @property {string} packageName The npm package name it was resolved from.
+ * @property {string} version
+ * @property {string} releaseDate
+ * @property {string} description
+ * @property {string} license
+ * @property {string} homepage
+ * @property {string} author
+ * @property {Array<{name: string, version: string}>} components Framework component versions.
+ * @property {Object|null} runtime Runtime facts (node/platform/instance), or `null` when withheld.
+ * @property {TiInfoSection[]} sections Application-contributed extra sections.
+ */

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.
  *