@ti-engine/web-framework 1.32.0 → 1.33.0

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 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.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/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.33.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",