add structured logging and update token binding logic

Author: KMilej

ApproovApplication.js

@@ -14,7 +14,8 @@ if (envResult.error && envResult.error.code !== 'ENOENT') {
 const PORT = parsePort(process.env.PORT, 8080);
 const APPROOV_HEADER = 'Approov-Token';
 const AUTH_HEADER = 'Authorization';
-const DIGEST_HEADER = 'Content-Digest';
+const SESSION_ID_HEADER = 'SessionId';
+const REQUIRED_SECRET_PLACEHOLDER = 'approov_base64url_secret_here';
 const APPROOV_SECRET = loadApproovSecret();
 
 let approovEnabled = true;
@@ -27,10 +28,20 @@ const PROTECTED_PATHS = new Set([
   '/token-double-binding',
 ]);
 
+const APPROOV_ERROR_CODES = {
+  MISSING_TOKEN: 'missing_approov_token',
+  TOKEN_VERIFICATION_FAILED: 'token_verification_failed',
+  TOKEN_MISSING_EXPIRATION: 'token_missing_expiration',
+  TOKEN_EXPIRED: 'token_expired',
+  MISSING_BINDING_HEADER: 'missing_binding_header',
+  BINDING_MISMATCH: 'binding_mismatch',
+};
+
 const app = express();
 app.disable('x-powered-by');
 app.use(cors());
 
+app.use(requestLoggingMiddleware);
 app.use(approovAuthMiddleware);
 
 app.get('/', (req, res) => {
@@ -78,10 +89,10 @@ app.get('/token-binding', (req, res) => {
 
 app.get('/token-double-binding', (req, res) => {
   const authorization = req.get(AUTH_HEADER);
-  const contentDigest = req.get(DIGEST_HEADER);
+  const sessionId = req.get(SESSION_ID_HEADER);
   const payload = infoPayload("Protected endpoint '/token-double-binding'; dual token binding enforced.");
   payload.authorizationHeaderPresent = hasText(authorization);
-  payload.contentDigestHeaderPresent = hasText(contentDigest);
+  payload.sessionIdHeaderPresent = hasText(sessionId);
   res.json(payload);
 });
 
@@ -104,27 +115,45 @@ function approovAuthMiddleware(req, res, next) {
   }
 
   if (!PROTECTED_PATHS.has(req.path)) {
+    req.approovSummary = 'approov_not_required';
+    req.approovRequiredHeaders = [];
     return next();
   }
 
+  req.approovRequiredHeaders = requiredHeadersFor(req.path, approovEnabled, tokenBindingEnabled);
+
   if (!approovEnabled) {
+    req.approovSummary = 'approov_disabled';
     return next();
   }
 
   try {
     const rawToken = trimOrNull(req.get(APPROOV_HEADER));
     const claims = verifyApproovToken(rawToken);
 
-    if (tokenBindingEnabled && needsBindingCheck(req.path)) {
-      const bindingValue = extractBindingValue(req.path, req);
-      if (!hasText(bindingValue)) {
-        throw new ApproovAuthError('Missing binding header value.');
+    if (tokenBindingEnabled) {
+      const bindingHeaders = bindingHeadersFor(req.path);
+      if (bindingHeaders.length > 0) {
+        const bindingValue = extractBindingValue(req, bindingHeaders);
+        if (!hasText(bindingValue)) {
+          throw new ApproovAuthError(
+            APPROOV_ERROR_CODES.MISSING_BINDING_HEADER,
+            'Missing binding header value.'
+          );
+        }
+        if (!isBindingValid(bindingValue, claims)) {
+          throw new ApproovAuthError(
+            APPROOV_ERROR_CODES.BINDING_MISMATCH,
+            'Approov token binding mismatch.'
+          );
+        }
       }
-      verifyTokenBinding(bindingValue, claims);
     }
 
+    req.approovSummary = 'approov_ok';
     return next();
   } catch (err) {
+    setApproovFailureSummary(req, err);
     logAuthFailure(err);
     return unauthorized(res);
   }
@@ -133,7 +162,7 @@ function approovAuthMiddleware(req, res, next) {
 // Token validation logic: signature check, expiration, and binding (when enabled).
 function verifyApproovToken(token) {
   if (!hasText(token)) {
-    throw new ApproovAuthError('Approov token missing.');
+    throw new ApproovAuthError(APPROOV_ERROR_CODES.MISSING_TOKEN, 'Approov token missing.');
   }
 
   let claims;
@@ -143,47 +172,77 @@ function verifyApproovToken(token) {
       ignoreExpiration: true,
     });
   } catch (err) {
-    throw new ApproovAuthError('Approov token verification failed.');
+    throw new ApproovAuthError(
+      APPROOV_ERROR_CODES.TOKEN_VERIFICATION_FAILED,
+      'Approov token verification failed.'
+    );
   }
 
   const exp = Number(claims.exp);
   if (!Number.isFinite(exp)) {
-    throw new ApproovAuthError('Approov token missing expiration.');
+    throw new ApproovAuthError(
+      APPROOV_ERROR_CODES.TOKEN_MISSING_EXPIRATION,
+      'Approov token missing expiration.'
+    );
   }
   if (exp * 1000 <= Date.now()) {
-    throw new ApproovAuthError('Approov token expired.');
+    throw new ApproovAuthError(APPROOV_ERROR_CODES.TOKEN_EXPIRED, 'Approov token expired.');
   }
 
   return claims;
 }
 
-function verifyTokenBinding(bindingValue, claims) {
+function isBindingValid(bindingValue, claims) {
   const expected = typeof claims.pay === 'string' ? claims.pay.trim() : '';
   if (!hasText(expected)) {
-    throw new ApproovAuthError('Approov token missing binding payload.');
+    return false;
   }
 
   const computed = hashBase64(bindingValue);
-  if (computed !== expected) {
-    throw new ApproovAuthError('Approov token binding mismatch.');
-  }
+  return timingSafeEquals(expected, computed);
 }
 
-function extractBindingValue(path, req) {
-  if (path === '/token-binding') {
-    return trimOrNull(req.get(AUTH_HEADER));
+function extractBindingValue(req, bindingHeaders) {
+  if (bindingHeaders.length === 0) {
+    return null;
   }
 
-  const authorization = trimOrNull(req.get(AUTH_HEADER));
-  const digest = trimOrNull(req.get(DIGEST_HEADER));
-  if (!hasText(authorization) || !hasText(digest)) {
+  const values = [];
+  for (const header of bindingHeaders) {
+    const value = trimOrNull(req.get(header));
+    if (!hasText(value)) {
+      return null;
+    }
+    values.push(value);
+  }
+
+  if (values.length === 0) {
     return null;
   }
-  return authorization + digest;
+
+  return values.join('');
+}
+
+function bindingHeadersFor(path) {
+  if (path === '/token-binding') {
+    return [AUTH_HEADER];
+  }
+  if (path === '/token-double-binding') {
+    return [AUTH_HEADER, SESSION_ID_HEADER];
+  }
+  return [];
 }
 
-function needsBindingCheck(path) {
-  return path === '/token-binding' || path === '/token-double-binding';
+function requiredHeadersFor(path, approovState, bindingState) {
+  if (!PROTECTED_PATHS.has(path) || !approovState) {
+    return [];
+  }
+
+  const headers = [APPROOV_HEADER];
+  if (bindingState) {
+    headers.push(...bindingHeadersFor(path));
+  }
+  return headers;
 }
 
 function enableApproov() {
@@ -212,7 +271,8 @@ function infoPayload(details) {
 
 function loadApproovSecret() {
   const raw = process.env.APPROOV_BASE64URL_SECRET;
-  if (!hasText(raw)) {
+  if (!hasText(raw) || raw.trim() === REQUIRED_SECRET_PLACEHOLDER) {
+    console.error('[Approov] Required secret is not set');
     throw new Error('APPROOV_BASE64URL_SECRET environment variable is not set.');
   }
 
@@ -223,6 +283,7 @@ function loadApproovSecret() {
     }
     return decoded;
   } catch (err) {
+    console.error('[Approov] Required secret is invalid');
     throw new Error('APPROOV_BASE64URL_SECRET must be base64url encoded.');
   }
 }
@@ -231,18 +292,77 @@ function hashBase64(value) {
   return crypto.createHash('sha256').update(value, 'utf8').digest('base64');
 }
 
+function timingSafeEquals(expected, actual) {
+  const expectedBuffer = Buffer.from(expected, 'utf8');
+  const actualBuffer = Buffer.from(actual, 'utf8');
+  if (expectedBuffer.length !== actualBuffer.length) {
+    return false;
+  }
+  return crypto.timingSafeEqual(expectedBuffer, actualBuffer);
+}
+
 function unauthorized(res) {
   res.status(401).json({});
 }
 
 function logAuthFailure(err) {
   if (err instanceof ApproovAuthError) {
-    console.warn(`[Approov] ${err.message}`);
+    console.warn(`[Approov] ${err.code}: ${err.message}`);
     return;
   }
   console.warn('[Approov] Unexpected authentication error.', err);
 }
 
+function requestLoggingMiddleware(req, res, next) {
+  res.on('finish', () => {
+    if (res.statusCode !== 200 && res.statusCode !== 401) {
+      return;
+    }
+
+    const summary = typeof req.approovSummary === 'string'
+      ? req.approovSummary
+      : res.statusCode === 401
+        ? 'approov_failed:unauthorized'
+        : 'request_completed';
+    const requiredHeaders = Array.isArray(req.approovRequiredHeaders)
+      ? req.approovRequiredHeaders
+      : requiredHeadersFor(req.path, approovEnabled, tokenBindingEnabled);
+    logRequestCompleted(req, res, summary, requiredHeaders);
+  });
+
+  next();
+}
+
+function logRequestCompleted(req, res, summary, requiredHeaders) {
+  const payload = {
+    summary,
+    method: req.method,
+    path: req.path,
+    status: res.statusCode,
+    ip: req.ip,
+    port: req.socket?.localPort ?? PORT,
+    approovEnabled,
+    tokenBindingEnabled,
+    required_headers: requiredHeaders,
+  };
+  console.log(`[${formatTimestamp(new Date())}] http.request.completed ${JSON.stringify(payload)}`);
+}
+
+function formatTimestamp(date) {
+  const pad = (value) => String(value).padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(
+    date.getHours()
+  )}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+
+function setApproovFailureSummary(req, err) {
+  if (err instanceof ApproovAuthError && hasText(err.code)) {
+    req.approovSummary = `approov_failed:${err.code}`;
+    return;
+  }
+  req.approovSummary = 'approov_failed:unexpected_error';
+}
+
 function hasText(value) {
   return typeof value === 'string' && value.trim() !== '';
 }
@@ -257,8 +377,9 @@ function parsePort(value, fallback) {
 }
 
 class ApproovAuthError extends Error {
-  constructor(message) {
+  constructor(code, message) {
     super(message);
     this.name = 'ApproovAuthError';
+    this.code = code;
   }
 }

README.md

@@ -7,7 +7,22 @@ This project provides a server-side example of Approov token verification for a
 - `/token-binding` - requires a valid Approov token which is bound to a header value.
 - `/token-double-binding` - requires a valid Approov token which is bound to two header values.
 
-In this example, Approov protection is enforced by [app.use(approovAuthMiddleware)](https://github.com/approov/quickstart-nodejs-express-token-check/blob/refactor/nodejs-express-quickstart/ApproovApplication.js#L101-L131). The middleware reads the `Approov-Token` header, validates signature and expiry via [verifyApproovToken](https://github.com/approov/quickstart-nodejs-express-token-check/blob/refactor/nodejs-express-quickstart/ApproovApplication.js#L134-L158), and (when required) enforces token binding via [verifyTokenBinding](https://github.com/approov/quickstart-nodejs-express-token-check/blob/refactor/nodejs-express-quickstart/ApproovApplication.js#L160-L170). Protected routes are selected via [PROTECTED_PATHS](https://github.com/approov/quickstart-nodejs-express-token-check/blob/refactor/nodejs-express-quickstart/ApproovApplication.js#L24-L28).
+In this example, Approov token check is implemented in `ApproovApplication.js`. The responsibilities break down as follows:
+
+1. **JWT Approov Token validation (signature + expiry)** is implemented in [verifyApproovToken](https://github.com/approov/quickstart-nodejs-express-token-check/blob/refactor/nodejs-express-quickstart/ApproovApplication.js#L162-L193)
+It verifies the HS256 signature (via `jwt.verify`) and rejects tokens that are missing or past `exp`.
+
+2. **Token binding (pay + hash)** is handled by [isBindingValid](https://github.com/approov/quickstart-nodejs-express-token-check/blob/refactor/nodejs-express-quickstart/ApproovApplication.js#L195-L203) and [hashBase64](ApproovApplication.js#L291-L293)
+It computes `base64(sha256(binding_value))` and compares it to `pay` using `timingSafeEquals`.
+
+3. **Middleware enforcement** is done by [approovAuthMiddleware](https://github.com/approov/quickstart-nodejs-express-token-check/blob/refactor/nodejs-express-quickstart/ApproovApplication.js#L111-L160)
+Requests without valid token/binding are rejected with 401.
+
+4. **Binding value selection (what gets hashed)** is in [extractBindingValue + bindingHeadersFor](https://github.com/approov/quickstart-nodejs-express-token-check/blob/refactor/nodejs-express-quickstart/ApproovApplication.js#L205-L234) It uses the headers configured in `bindingHeadersFor` (currently `Authorization` for single binding, or `Authorization` + `SessionId` for double binding).
+
+5. **Protected route requirements** are defined in [PROTECTED_PATHS](https://github.com/approov/quickstart-nodejs-express-token-check/blob/refactor/nodejs-express-quickstart/ApproovApplication.js#L24-L29) and [requiredHeadersFor](https://github.com/approov/quickstart-nodejs-express-token-check/blob/refactor/nodejs-express-quickstart/ApproovApplication.js#L236-L246)
+
+6. **Protected routes are registered** in the Express route declarations ([app.get/app.post](https://github.com/approov/quickstart-nodejs-express-token-check/blob/refactor/nodejs-express-quickstart/ApproovApplication.js#L47-L97))
 
 ## Approov Token Verification Flow
 
@@ -29,8 +44,8 @@ In this example, Approov protection is enforced by [app.use(approovAuthMiddlewar
    The protected API then computes the same hash from the incoming request and verifies that it matches the `pay` claim, preventing token reuse or replay attacks. For local testing, you can also generate example tokens with a binding using the Approov CLI.
 
 5. **Request Decision:**   
-   If all checks pass → the request is trusted and processed `200 OK`.   
-   If validation fails → the server responds with `401 Unauthorized`.
+      If all checks pass → the request is trusted and processed `200 OK`.   
+      If validation fails → the server responds with `401 Unauthorized`.
 
 ## Requirements:
 
@@ -78,7 +93,7 @@ bash test.sh
 This script:
 - Verifies that the `approov` and `curl` commands are installed.
 - Checks Approov status by calling `/approov-state` (enabled vs disabled).
-- Runs endpoint tests against `/unprotected` (no token), `/token-check` (valid/invalid Approov tokens), `/token-binding` (token bound to `Authorization`), and `/token-double-binding` (token bound to `Authorization` + `Content-Digest`).
+- Runs endpoint tests against `/unprotected` (no token), `/token-check` (valid/invalid Approov tokens), `/token-binding` (token bound to `Authorization`), and `/token-double-binding` (token bound to `Authorization` + `SessionId`).
 - Logs full request/response details to `.config/logs/<timestamp>.log`.
 
 #### *1. Unprotected Endpoint (No Approov)*
@@ -175,16 +190,16 @@ Cache-Control: no-cache
 - The client sends three headers on authenticated API calls:
     - `Approov-Token`
     - `Authorization`
-    - `Content-Digest` It is combined with the `Authorization` header to create a stronger binding.
+    - `SessionId` It is combined with the `Authorization` header to create a stronger binding.
 - Both are included in the hash inside the Approov token. This means the server verifies a single hash that covers both authentication credentials.
 - **Use case:** Stronger protection then single binding by tying both headers together.
 
 ***The following example shows how the API responds when an Approov token with two bindings is required.***
 
-*Generate a valid Approov token bound to the `Authorization` and `Content-Digest` headers:*
+*Generate a valid Approov token bound to the `Authorization` and `SessionId` headers:*
 
 ```bash
-approov token -setDataHashInToken ExampleAuthToken==ContentDigest== -genExample example.com
+approov token -setDataHashInToken ExampleAuthToken==123 -genExample example.com
 ```
 
 *Use the generated token with two bindings in the Approov-Token and Authorization headers when calling the `/token-double-binding` endpoint.*
@@ -193,7 +208,7 @@ approov token -setDataHashInToken ExampleAuthToken==ContentDigest== -genExample
 curl -iX GET http://localhost:8080/token-double-binding \
      -H "Approov-Token: valid_approov_token_here" \
      -H "Authorization: ExampleAuthToken==" \
-     -H "Content-Digest: ContentDigest=="
+     -H "SessionId: 123"
 ```
 
 The response will be `200 OK` for this request.
@@ -206,7 +221,7 @@ Cache-Control: no-cache
 
 *If you use an invalid or missing header or token, the server will respond with `401 Unauthorized`.*
 
-## Enable or Disable Approov Protection
+## Enable or Disable Approov Protection      
 
 When the example server is running on `localhost:8080`, you can toggle Approov protection with these commands:
 
@@ -240,4 +255,4 @@ If you encounter any problems while following this guide, or have any other conc
 * [Approov Customer Stories](https://approov.io/customer)
 * [Approov Support](https://approov.io/info/technical-support)
 * [About Us](https://approov.io/company)
-* [Contact Us](https://approov.io/info/contact)
+* [Contact Us](https://approov.io/info/contact)