@ti-engine/web-framework 1.32.0 → 1.34.0

package/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 This document will contain the list of changes made to the framework. The format is based on the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
 
+## Version 1.34.0
+
+* fix(web-app): give the login error element fallback text, so it can never render as an empty box. The message
+  has been unreadable since it was added (CA-95): `x-text-label` resolves
+  `interface.default.login.error-sign-in-failed` out of **this package's** `web-server-labels.json`, and a consuming
+  application configures exactly one labels path — its own — so the key does not resolve there. The directive then
+  falls back to the element's own text content, and the element was empty. The result was a red alert box with
+  nothing in it: visibly broken, and saying nothing to the person who had just failed to sign in. An application
+  that wants it localized adds the key to its own catalogue, which is the same arrangement the Profile and About
+  screens already use.
+* fix(web-app): drop the `error` query parameter from the address bar once the login screen has shown it, via the
+  new `tiToolbox.clearUrlParam( name )` (`history.replaceState`, so no history entry the visitor never navigated
+  to). It is a one-time message, not state: left in place, a refresh replays a sign-in failure that already
+  happened, a bookmark captures it, and the login screen cannot be returned to its blank state without editing the
+  URL by hand. The parameter itself stays, because a top-level browser navigation — an OAuth callback, or a
+  non-HTMX form post — cannot be answered with a body and still leave the visitor on the login page; a redirect is
+  the only way, and a redirect carries no payload. HTMX requests were never affected: they already receive the
+  error through the `ti:error` `HX-Trigger` and touch no query string.
+
+## Version 1.33.0
+
+* fix(web-handlers)!: refuse an OpenID Connect callback that cannot be completed through the normal error path
+  instead of answering `response.status(400).end()`. That was a bare status with an empty body: the visitor got a
+  blank page, nothing was logged, and the three distinct reasons a callback fails were collapsed into one
+  indistinguishable response. Whoever had to work out why had neither a message nor a log line to start from. A
+  refusal is now raised with an explicit `401`, so it presents exactly like every other sign-in failure — an
+  HTML `GET` lands back on the login page with `?error=<code>`, and an API client gets the standard payload.
+  Marked breaking because the status and body of a failed callback change; no caller should have been depending on
+  an empty 400, but a caller that was will see a `303` or a `401`.
+* feat(web-handlers): distinguish the three failure reasons in the log, with the fact that identifies each.
+  `E_WEB_INVALID_REQUEST_QUERY` when the provider returned no authorization code, naming the provider's own
+  `error` (usually `access_denied` — the visitor declined consent). `E_SEC_INVALID_EXPIRED_SESSION` when the
+  session carries no OAuth state, **naming the host the callback arrived on and why that matters**: a session
+  cookie is host-scoped, so a sign-in begun on one hostname and called back on another arrives with no cookie and
+  therefore nothing to verify against. A service reachable under more than one name produces exactly this — a
+  platform that assigns both a generated and a deterministic hostname, say — and so does a session that expired
+  while the visitor sat on the consent screen. `E_SEC_UNAUTHORIZED_ACCESS` when the state does not match the one
+  issued. The distinction is in the log rather than the response, because the visitor has no use for it and an
+  attacker probing the endpoint should not be handed it. **Nothing secret is logged** — never the authorization
+  code, the state values, the PKCE verifier or the nonce — and a test pins that.
+* fix(web-handlers): escape externally-supplied text before it reaches a log line or an error payload. The
+  previous two entries put two caller-controlled values into a `WARNING`: the provider's `error` query parameter
+  and the request's host headers. The callback endpoint is unprotected and accepts any query string, and query
+  parameters are percent-decoded before the handler sees them, so `%0A` arrives as a real newline. The console
+  appender writes one line per entry, which makes that newline the end of the line — everything after it reads as a
+  separate, entirely attacker-written entry, a forged `NOTICE - Sign-in succeeded for admin` sitting in the log
+  looking exactly like a real one. Every character outside printable ASCII is now rendered as a visible `\uXXXX`
+  escape and the value is capped at 100 characters, so a field stays diagnosable without being able to end the line
+  or flood the log. Escaping happens where the value enters rather than at each use, so nothing downstream can
+  reach the raw form. An allowlist of known OAuth error codes was the alternative and is worse: providers emit
+  non-standard codes, and the unfamiliar ones are precisely the ones worth reading. Raised by CodeRabbit on the
+  review of this branch.
+* fix(web-handlers)!: refuse a callback whose session holds a PKCE verifier but no expected state, rather than
+  skipping the comparison. The guard was `oidc.state && state !== oidc.state`, so an absent expected state
+  disabled the check entirely. Nothing in the framework produces such a session — `authenticationHandler` writes
+  the verifier and the state together — but an unverifiable callback is not a callback to trust, and a guard that
+  silently turns itself off when its own input is missing is the wrong shape. `openid-client` checks
+  `expectedState` as well; this keeps the refusal where it can be explained.
+
 ## Version 1.32.0
 
 * fix(authorization)!: `applyAdminRole` now reconciles the `admin` role in **both** directions — granted when the

package/bin/static/fragments/frame-login.html

@@ -12,12 +12,17 @@
         <!-- Login card -->
         <div class="ti-login-card">
             <!-- Error message -->
+            <!-- The element's own text is the FALLBACK the x-text-label directive falls back to, and it has to be
+                 here: this key lives in the framework's web-server-labels.json, and a consuming application
+                 configures exactly one labels path — its own — so the framework's catalogue is not loaded and the
+                 key does not resolve. An empty element therefore rendered an empty red box: visibly broken, saying
+                 nothing. An application that wants this localized adds the key to its own catalogue. -->
             <div id="ti-error"
                  class="ti-login-error"
                  x-data="tiLoginError"
                  x-bind:class="{ visible: hasError }"
                  role="alert"
-                 x-text-label="interface.default.login.error-sign-in-failed"></div>
+                 x-text-label="interface.default.login.error-sign-in-failed">Sign-in failed. Please try again.</div>
 
             <!--ti-auth-method:local-->
             <!-- Local auth form -->

package/bin/static/scripts/ti-framework.js

@@ -204,6 +204,32 @@ const configureToolbox = () => {
             return new URLSearchParams( window.location.search ).get( name );
         },
 
+        /**
+         * Removes a query parameter from the address bar without reloading or adding a history entry.
+         * <br/>
+         * For a parameter that carries a one-time message: once it has been read and shown, it has done its job, and
+         * leaving it in the URL means a refresh or a bookmark replays a failure that is no longer happening.
+         * `replaceState` rather than `pushState`, so the back button is not left stepping through states the visitor
+         * never navigated to.
+         *
+         * @method
+         * @param {string} name
+         * @public
+         */
+        clearUrlParam( name ) {
+            if ( !window.history || typeof window.history.replaceState !== "function" ) {
+                return;
+            }
+            const url = new URL( window.location.href );
+            if ( !url.searchParams.has( name ) ) {
+                return;
+            }
+            url.searchParams.delete( name );
+            // Keep a bare "?" off the end when the last parameter goes.
+            const search = url.searchParams.toString();
+            window.history.replaceState( null, "", url.pathname + ( search ? "?" + search : "" ) + url.hash );
+        },
+
         /**
          * Used to get the visible box of the document.
          *
@@ -1684,6 +1710,10 @@ const configureLoginError = () => {
         init() {
             const tiToolbox = Alpine.store( "tiToolbox" );
             this.hasError = Boolean( tiToolbox.getUrlParam( "error" ) );
+            // The parameter is a one-time message, not state. Read it, show it, drop it — otherwise a refresh (or a
+            // bookmark, or a shared link) replays a sign-in failure that already happened, and the login screen can
+            // never be returned to its blank state without editing the URL by hand.
+            tiToolbox.clearUrlParam( "error" );
         }
     };
 };

package/components/local-user-directory.js

@@ -233,7 +233,8 @@ function verifyPassword( password, encoded ) {
 // Usernames that JavaScript's object model treats specially, rejected here because the storage layer this
 // module writes through cannot represent all of them safely — reusing the exact trio ('__proto__',
 // 'constructor', 'prototype') this codebase already treats as reserved at every other prototype-pollution
-// boundary (see the CA-91 employee field-path guards in packages/competence). Verified empirically per name,
+// boundary (see the CA-91 employee field-path guards in the competence application, now its own repository).
+// Verified empirically per name,
 // not assumed uniformly:
 // - '__proto__' is the one that corrupted storage, in @ti-engine/core **before 1.11.0**.
 //   `cache.instance.setJSON` serializes through `tools.stringifyJSON` —

package/components/web-handlers.js

@@ -94,6 +94,39 @@ const resolveHttpCode = ( exception ) => {
     return exceptions.httpCode.C_500; // general, communication, or unknown → internal server error
 };
 
+/**
+ * Longest run of externally-supplied text to put in one log line. Long enough that a real OAuth error code or
+ * hostname survives whole, short enough that nobody can flood the log through one field.
+ *
+ * @type {number}
+ */
+const LOG_VALUE_MAX_LENGTH = 100;
+
+/**
+ * Renders a value that came from outside safe to interpolate into a log message or echo in an error payload.
+ * <br/>
+ * The console appender writes one line per entry, so a newline inside an interpolated value ends that line and
+ * everything after it reads as a separate, entirely attacker-written entry — a forged `NOTICE - sign-in succeeded`,
+ * say, sitting in the log looking exactly like a real one. Query parameters are percent-decoded before they reach
+ * us, so `%0A` arrives as a genuine line break.
+ * <br/>
+ * Every character outside printable ASCII becomes a visible `\uXXXX` escape rather than being dropped, so the value
+ * stays diagnosable — the point of logging it at all — while losing the ability to end the line. An allowlist of
+ * known OAuth error codes was the other option and is worse: providers emit non-standard codes, and the unfamiliar
+ * ones are precisely the ones worth reading.
+ *
+ * @method
+ * @param {*} value
+ * @returns {string}
+ * @private
+ */
+const sanitizeExternalValue = ( value ) => {
+    const escaped = String( value ?? "" ).replace( /[^\x20-\x7E]/g, ( character ) => {
+        return "\\u" + character.charCodeAt( 0 ).toString( 16 ).padStart( 4, "0" );
+    } );
+    return ( escaped.length > LOG_VALUE_MAX_LENGTH ) ? escaped.slice( 0, LOG_VALUE_MAX_LENGTH ) + "..." : escaped;
+};
+
 /**
  * Used to assemble the current URL of a request.
  *
@@ -356,7 +389,18 @@ module.exports.authenticationHandler = ( instance ) => {
 };
 
 /**
- * Used to handle the callback from the Google OpenID authentication.
+ * Used to handle the callback from an OpenID Connect provider.
+ * <br/>
+ * A callback that cannot be completed is refused through the normal error path — `next( … )` with an explicit
+ * `401` — so it presents exactly like every other sign-in failure: an HTML `GET` lands back on the login page with
+ * `?error=<code>`, and an API client gets the standard payload. It used to answer `response.status(400).end()`: a
+ * bare status with an empty body, no log line, and the three distinct reasons below collapsed into one blank page
+ * that said nothing to the person seeing it and nothing to whoever had to work out why.
+ * <br/>
+ * The three reasons are distinguished in the log rather than in the response, because the visitor has no use for
+ * the difference and an attacker probing the endpoint should not be handed it. Nothing secret is logged — never
+ * the authorization code, the state values, the PKCE verifier or the nonce — only the facts that identify which
+ * case this is.
  *
  * @method
  * @param {TiWebServer} instance
@@ -368,27 +412,54 @@ module.exports.authorizedOAuth2CallbackHandler = ( instance, authMethod ) => {
     return ( request, response, next ) => {
         const code = request.query.code;
         const state = request.query.state;
-        const oidc = request.session.oidc || {};
-        if ( !code || !oidc?.codeVerifier ) {
-            response.status( exceptions.httpCode.C_400 ).end();
-        } else if ( oidc.state && state !== oidc.state ) {
-            response.status( exceptions.httpCode.C_400 ).end();
-        } else {
-            instance.authorize( authMethod, new URL( request.originalUrl, getBaseUrl( request ) ), oidc ).then( ( user ) => {
-                return regenerateAndSaveSession( request, "/", ( session ) => {
-                    session.user = user.asJSON();
-                    session.language = user.language || instance.serviceConfig.language;
+        const oidc = request.session?.oidc || {};
+
+        // The provider did not return an authorization code. Usually the visitor declined consent, or the provider
+        // refused the request outright; either way it says so in `error`, which is the single most useful thing to
+        // record and is not sensitive.
+        if ( !code ) {
+            const providerError = sanitizeExternalValue( request.query.error || "none" );
+            logger.log( `Refusing an OpenID sign-in via '${ authMethod }': the provider returned no authorization code (error='${ providerError }').`, logger.logSeverity.WARNING );
+            next( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_QUERY, { detail: "The identity provider returned no authorization code.", providerError: providerError }, exceptions.httpCode.C_401 ) );
+            return;
+        }
 
-                    delete session.oidc;
+        // The session holds nothing to verify the callback against. This is the case that used to be hardest to
+        // diagnose, so the log names the likely cause: a session cookie is scoped to one host, so a sign-in begun
+        // on one hostname and called back on another arrives with no cookie and therefore no state. A service
+        // reachable under more than one name — a platform that assigns both a generated and a deterministic
+        // hostname, say — produces exactly this, and so does a session that expired while the visitor sat on the
+        // provider's consent screen.
+        if ( !oidc.codeVerifier ) {
+            logger.log( `Refusing an OpenID sign-in via '${ authMethod }': the session carries no OAuth state. The callback arrived on host '${ sanitizeExternalValue( request.get( "x-forwarded-host" ) || request.get( "host" ) || "unknown" ) }' — a session cookie is host-scoped, so check that the sign-in began on this same host and that the session had not expired.`, logger.logSeverity.WARNING );
+            next( exceptions.raise( exceptions.exceptionCode.E_SEC_INVALID_EXPIRED_SESSION, { detail: "The session carries no OAuth state for this callback." }, exceptions.httpCode.C_401 ) );
+            return;
+        }
 
-                    return authorization.applyAdminRole( instance.augmentSession( session, request ), instance.serviceConfig?.auth?.admins );
-                } );
-            } ).then( ( redirectTo ) => {
-                response.redirect( exceptions.httpCode.C_303, convertUriToString( redirectTo ) );
-            } ).catch( ( error ) => {
-                next( exceptions.raise( error, null, exceptions.httpCode.C_401 ) );
-            } );
+        // The state does not match the one issued for this session. A missing expected state is refused too rather
+        // than skipped: a session holding a verifier but no state is inconsistent, and an unverifiable callback is
+        // not a callback to trust. (`openid-client` checks `expectedState` as well; this keeps the refusal here,
+        // where it can be explained.)
+        if ( !oidc.state || state !== oidc.state ) {
+            logger.log( `Refusing an OpenID sign-in via '${ authMethod }': the callback's state does not match the one issued for this session.`, logger.logSeverity.WARNING );
+            next( exceptions.raise( exceptions.exceptionCode.E_SEC_UNAUTHORIZED_ACCESS, { detail: "The callback state does not match the one issued for this session." }, exceptions.httpCode.C_401 ) );
+            return;
         }
+
+        instance.authorize( authMethod, new URL( request.originalUrl, getBaseUrl( request ) ), oidc ).then( ( user ) => {
+            return regenerateAndSaveSession( request, "/", ( session ) => {
+                session.user = user.asJSON();
+                session.language = user.language || instance.serviceConfig.language;
+
+                delete session.oidc;
+
+                return authorization.applyAdminRole( instance.augmentSession( session, request ), instance.serviceConfig?.auth?.admins );
+            } );
+        } ).then( ( redirectTo ) => {
+            response.redirect( exceptions.httpCode.C_303, convertUriToString( redirectTo ) );
+        } ).catch( ( error ) => {
+            next( exceptions.raise( error, null, exceptions.httpCode.C_401 ) );
+        } );
     };
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/web-framework",
-  "version": "1.32.0",
+  "version": "1.34.0",
   "description": "A web-framework based on the ti-engine. It provides a customizable ready-to-use web-server microservice and a set of tools for creating web applications. NOTICE: This is still a work in progress and the full architecture, design, and functionality are not available!",
   "keywords": [
     "ti-engine",