feat: implementation of catreplay claim (#17)

birme · web-flow · commit efe3c4e10a31 · 2025-03-19T23:29:56.000+01:00
* feat: implementation of catreplay claim

* chore: documented new errors
diff --git a/readme.md b/readme.md
@@ -45,7 +45,7 @@ Features:
 | Expiration (`exp`)                                        | Yes      |
 | Not Before (`nbf`)                                        | Yes      |
 | CWT ID (`cti`)                                            | Yes      |
-| Common Access Token Replay (`catreplay`)                  | No       |
+| Common Access Token Replay (`catreplay`)                  | Yes      |
 | Common Access Token Probability of Rejection (`catpor`)   | No       |
 | Common Access Token Version (`catv`)                      | No       |
 | Common Access Token Network IP (`catnip`)                 | No       |
@@ -307,6 +307,53 @@ class MyLogger implements ITokenLogger {
 }
 ```
 
+## Token Reuse Detection
+
+Enforcing and detecting invalid token reuse when `catreplay` claim has a value of 2 is an implementation-defined process.
+
+You provide a custom callback function to the HTTP validator. This callback is provided with the Common Access Token, store and logger. Pseudo code as an example.
+
+```javascript
+class MyLogger implements ITokenLogger {
+  async logToken(token: CommonAccessToken): Promise<void> {
+    if (!this.db.connected) {
+      await this.db.connect();
+    }
+    this.db.insert(token);
+  }
+  async getLogsForToken(token: CommonAccessToken): Promise<LogList[]> {
+    return await this.db.find({ cti: token.cti });
+  }
+}
+
+const reuseDetection = async (
+  cat: CommonAccessToken,
+  store?: ICTIStore,
+  logger?: ITokenLogger
+) => {
+  if (logger) {
+    const logs = await logger.getLogsForToken(cat);
+    return tokenLogsInPeriod(logs, 5) > 10; // two many uses within a 5 second period
+  }
+}
+
+const httpValidator = new HttpValidator({
+  keys: [
+    {
+      kid: 'Symmetric256',
+      key: Buffer.from(
+        '403697de87af64611c1d32a05dab0fe1fcb715a86ab435f1ec99192d79569388',
+        'hex'
+      )
+    }
+  ],
+  issuer: 'eyevinn',
+  store: new MyLogger(),
+  reuseDetection
+});
+...
+```
+
 ## Development
 
 <!--Add clear instructions on how to start development of the project here -->
diff --git a/src/errors.ts b/src/errors.ts
@@ -80,3 +80,21 @@ export class RenewalClaimError extends Error {
     super(reason);
   }
 }
+
+/**
+ * Error thrown when trying to replay a token that is not allowed to be replayed
+ */
+export class ReplayNotAllowedError extends Error {
+  constructor(count: number) {
+    super(`Replay not allowed: ${count}`);
+  }
+}
+
+/**
+ * Error thrown when a token is detected for invalid reuse
+ */
+export class InvalidReuseDetected extends Error {
+  constructor() {
+    super(`Invalid reuse detected`);
+  }
+}
diff --git a/src/validators/http.test.ts b/src/validators/http.test.ts
@@ -1,8 +1,13 @@
 import { createRequest, createResponse } from 'node-mocks-http';
 import { HttpValidator, NoTokenFoundError } from './http';
-import { CAT, MemoryCTIStore } from '..';
+import {
+  CAT,
+  CommonAccessToken,
+  ICTIStore,
+  ITokenLogger,
+  MemoryCTIStore
+} from '..';
 import { CommonAccessTokenRenewal } from '../catr';
-import { CloudFrontResponse } from 'aws-lambda';
 
 describe('HTTP Request CAT Validator', () => {
   test('fail to validate token in CTA-Common-Access-Token header with wrong signature', async () => {
@@ -626,6 +631,7 @@ describe('HTTP Request CAT Validator with store', () => {
     expect(result.claims!.cti).toBe('0b71');
     expect(result.count).toBe(1);
     const result2 = await httpValidator.validateHttpRequest(request, response);
+    expect(result2.status).toBe(200);
     expect(result2.count).toBe(2);
 
     const cfResult = await httpValidator.validateCloudFrontRequest({
@@ -695,4 +701,136 @@ describe('HTTP Request CAT Validator with store', () => {
     expect(result.claims!.cti).toBe('0b71');
     expect(result.count).toBeUndefined();
   });
+
+  test('pass if a token has a claim that allows replay and it has been used multiple times', async () => {
+    const base64encoded = await generator.generateFromJson(
+      {
+        iss: 'eyevinn',
+        catreplay: 0
+      },
+      {
+        type: 'mac',
+        alg: 'HS256',
+        kid: 'Symmetric256',
+        generateCwtId: true
+      }
+    );
+    const httpValidator = new HttpValidator({
+      keys: [
+        {
+          kid: 'Symmetric256',
+          key: Buffer.from(
+            '403697de87af64611c1d32a05dab0fe1fcb715a86ab435f1ec99192d79569388',
+            'hex'
+          )
+        }
+      ],
+      issuer: 'eyevinn',
+      store: new MemoryCTIStore()
+    });
+    const request = createRequest({
+      method: 'GET',
+      headers: {
+        'CTA-Common-Access-Token': base64encoded
+      }
+    });
+    const result = await httpValidator.validateHttpRequest(request);
+    expect(result.status).toBe(200);
+    const result2 = await httpValidator.validateHttpRequest(request);
+    expect(result2.status).toBe(200);
+  });
+
+  test('fail if a token has a claim that does not allow replay and it has been used multiple times', async () => {
+    const base64encoded = await generator.generateFromJson(
+      {
+        iss: 'eyevinn',
+        catreplay: 1
+      },
+      {
+        type: 'mac',
+        alg: 'HS256',
+        kid: 'Symmetric256',
+        generateCwtId: true
+      }
+    );
+    const httpValidator = new HttpValidator({
+      keys: [
+        {
+          kid: 'Symmetric256',
+          key: Buffer.from(
+            '403697de87af64611c1d32a05dab0fe1fcb715a86ab435f1ec99192d79569388',
+            'hex'
+          )
+        }
+      ],
+      issuer: 'eyevinn',
+      store: new MemoryCTIStore()
+    });
+    const request = createRequest({
+      method: 'GET',
+      headers: {
+        'CTA-Common-Access-Token': base64encoded
+      }
+    });
+    const result = await httpValidator.validateHttpRequest(request);
+    expect(result.status).toBe(200);
+    const result2 = await httpValidator.validateHttpRequest(request);
+    expect(result2.status).toBe(401);
+  });
+
+  test('can provide a simple reuse detection algorithm', async () => {
+    const base64encoded = await generator.generateFromJson(
+      {
+        iss: 'eyevinn',
+        catreplay: 2
+      },
+      {
+        type: 'mac',
+        alg: 'HS256',
+        kid: 'Symmetric256',
+        generateCwtId: true
+      }
+    );
+
+    const simpleReuseDetection = async (
+      cat: CommonAccessToken,
+      store?: ICTIStore,
+      logger?: ITokenLogger
+    ) => {
+      if (store) {
+        const count = await store.getTokenCount(cat);
+        // Consider reuse if same token has been used more than 2 times
+        // (this is a very naive example)
+        return count > 2;
+      }
+      return true;
+    };
+    const httpValidator = new HttpValidator({
+      keys: [
+        {
+          kid: 'Symmetric256',
+          key: Buffer.from(
+            '403697de87af64611c1d32a05dab0fe1fcb715a86ab435f1ec99192d79569388',
+            'hex'
+          )
+        }
+      ],
+      issuer: 'eyevinn',
+      store: new MemoryCTIStore(),
+      reuseDetection: simpleReuseDetection
+    });
+
+    const request = createRequest({
+      method: 'GET',
+      headers: {
+        'CTA-Common-Access-Token': base64encoded
+      }
+    });
+    const result = await httpValidator.validateHttpRequest(request);
+    expect(result.status).toBe(200);
+    const result2 = await httpValidator.validateHttpRequest(request);
+    expect(result2.status).toBe(200);
+    const result3 = await httpValidator.validateHttpRequest(request);
+    expect(result3.status).toBe(401);
+  });
 });
diff --git a/src/validators/http.ts b/src/validators/http.ts
@@ -1,9 +1,11 @@
 import { IncomingMessage, OutgoingMessage } from 'node:http';
-import { CAT } from '..';
+import { CAT, CommonAccessToken } from '..';
 import {
   InvalidAudienceError,
   InvalidIssuerError,
+  InvalidReuseDetected,
   KeyNotFoundError,
+  ReplayNotAllowedError,
   TokenExpiredError,
   UriNotAllowedError
 } from '../errors';
@@ -61,6 +63,14 @@ export interface HttpValidatorOptions {
    * Logger for logging token usage
    */
   logger?: ITokenLogger;
+  /**
+   * Callback for reuse detection
+   */
+  reuseDetection?: (
+    cat: CommonAccessToken,
+    store?: ICTIStore,
+    logger?: ITokenLogger
+  ) => Promise<boolean>;
 }
 
 /**
@@ -228,6 +238,22 @@ export class HttpValidator {
           // CAT is acceptable
           if (cat && this.store) {
             count = await this.store.storeToken(cat);
+            if (cat.claims.catreplay !== undefined) {
+              if (cat.claims.catreplay === 1) {
+                if (count > 1) {
+                  throw new ReplayNotAllowedError(count);
+                }
+              } else if (
+                cat.claims.catreplay === 2 &&
+                this.opts.reuseDetection
+              ) {
+                if (
+                  await this.opts.reuseDetection(cat, this.store, this.logger)
+                ) {
+                  throw new InvalidReuseDetected();
+                }
+              }
+            }
           }
           if (cat && this.logger) {
             await this.logger.logToken(cat);
@@ -294,7 +320,9 @@ export class HttpValidator {
           err instanceof InvalidAudienceError ||
           err instanceof KeyNotFoundError ||
           err instanceof TokenExpiredError ||
-          err instanceof UriNotAllowedError
+          err instanceof UriNotAllowedError ||
+          err instanceof ReplayNotAllowedError ||
+          err instanceof InvalidReuseDetected
         ) {
           return {
             status: 401,
