@prairielearn/signed-token 1.0.0

package/README.md

@@ -0,0 +1,24 @@
+# `@prairielearn/signed-token`
+
+A package for generating signed tokens. Useful for CSRF tokens or generally to round-trip trusted data through an untrusted client.
+
+## Usage
+
+```ts
+import {
+  generateSignedToken,
+  getCheckedSignedTokenData,
+  checkSignedToken,
+} from '@prairielearn/signed-token';
+
+const token = generateSignedToken({ foo: 'bar' }, 'SECRET_KEY');
+
+console.log(getCheckedSignedTokenData(token, 'SECRET_KEY', { maxAge: 60 * 1000 }));
+// { foo: 'bar' }
+
+console.log(checkSignedToken(token, { foo: 'bar' }, 'SECRET_KEY', { maxAge: 60 * 1000 }));
+// true
+
+console.log(checkSignedToken(token, { foo: 'baz' }, 'SECRET_KEY', { maxAge: 60 * 1000 }));
+// false
+```

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+interface CheckOptions {
+    maxAge?: number;
+}
+export declare function generateSignedToken(data: any, secretKey: string): string;
+export declare function getCheckedSignedTokenData(token: string, secretKey: string, options?: CheckOptions): any;
+export declare function checkSignedToken(token: string, data: any, secretKey: string, options?: CheckOptions): boolean;
+export {};

package/dist/index.js

@@ -0,0 +1,110 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkSignedToken = exports.getCheckedSignedTokenData = exports.generateSignedToken = void 0;
+const base64url_1 = __importDefault(require("base64url"));
+const debug_1 = __importDefault(require("debug"));
+const lodash_1 = __importDefault(require("lodash"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const debug = (0, debug_1.default)('prairielearn:csrf');
+const sep = '.';
+function generateSignedToken(data, secretKey) {
+    debug(`generateSignedToken(): data = ${JSON.stringify(data)}`);
+    debug(`generateSignedToken(): secretKey = ${secretKey}`);
+    const dataJSON = JSON.stringify(data);
+    const dataString = base64url_1.default.encode(dataJSON);
+    const dateString = new Date().getTime().toString(36);
+    const checkString = dateString + sep + dataString;
+    const signature = node_crypto_1.default.createHmac('sha256', secretKey).update(checkString).digest('hex');
+    const encodedSignature = base64url_1.default.encode(signature);
+    debug(`generateSignedToken(): ${JSON.stringify({
+        dataString,
+        dateString,
+        checkString,
+        encodedSignature,
+    })}`);
+    const token = encodedSignature + sep + checkString;
+    debug(`generateSignedToken(): token = ${token}`);
+    return token;
+}
+exports.generateSignedToken = generateSignedToken;
+function getCheckedSignedTokenData(token, secretKey, options = {}) {
+    debug(`getCheckedSignedTokenData(): token = ${token}`);
+    debug(`getCheckedSignedTokenData(): secretKey = ${secretKey}`);
+    debug(`getCheckedSignedTokenData(): options = ${JSON.stringify(options)}`);
+    if (!lodash_1.default.isString(token)) {
+        debug(`getCheckedSignedTokenData(): FAIL - token is not string`);
+        return null;
+    }
+    // break token apart into the three components
+    const match = token.split(sep);
+    if (match == null) {
+        debug(`getCheckedSignedTokenData(): FAIL - could not split token`);
+        return null;
+    }
+    const tokenSignature = match[0];
+    const tokenDateString = match[1];
+    const tokenDataString = match[2];
+    // check the signature
+    const checkString = tokenDateString + sep + tokenDataString;
+    const checkSignature = node_crypto_1.default.createHmac('sha256', secretKey).update(checkString).digest('hex');
+    const encodedCheckSignature = base64url_1.default.encode(checkSignature);
+    if (encodedCheckSignature !== tokenSignature) {
+        debug(`getCheckedSignedTokenData(): FAIL - signature mismatch: checkSig=${encodedCheckSignature} != tokenSig=${tokenSignature}`);
+        return null;
+    }
+    // check the age if we have the maxAge parameter
+    if (options.maxAge != null) {
+        let tokenDate;
+        try {
+            tokenDate = new Date(parseInt(tokenDateString, 36));
+        }
+        catch (e) {
+            debug(`getCheckedSignedTokenData(): FAIL - could not parse date: ${tokenDateString}`);
+            return null;
+        }
+        const currentTime = Date.now();
+        const elapsedTime = currentTime - tokenDate.getTime();
+        if (elapsedTime > options.maxAge) {
+            debug(`getCheckedSignedTokenData(): FAIL - too old: elapsedTime=${elapsedTime} > maxAge=${options.maxAge}`);
+            return null;
+        }
+    }
+    // get the data
+    let tokenDataJSON, tokenData;
+    try {
+        tokenDataJSON = base64url_1.default.decode(tokenDataString);
+    }
+    catch (e) {
+        debug(`getCheckedSignedTokenData(): FAIL - could not base64 decode: ${tokenDateString}`);
+        return null;
+    }
+    try {
+        tokenData = JSON.parse(tokenDataJSON);
+    }
+    catch (e) {
+        debug(`getCheckedSignedTokenData(): FAIL - could not parse JSON: ${tokenDataJSON}`);
+        return null;
+    }
+    debug(`getCheckedSignedTokenData(): tokenData = ${tokenData}`);
+    return tokenData;
+}
+exports.getCheckedSignedTokenData = getCheckedSignedTokenData;
+function checkSignedToken(token, data, secretKey, options = {}) {
+    debug(`checkSignedToken(): token = ${token}`);
+    debug(`checkSignedToken(): data = ${JSON.stringify(data)}`);
+    debug(`checkSignedToken(): secretKey = ${secretKey}`);
+    debug(`checkSignedToken(): options = ${JSON.stringify(options)}`);
+    debug(`checkSignedToken(): data = ${JSON.stringify(data)}`);
+    const tokenData = getCheckedSignedTokenData(token, secretKey, options);
+    debug(`checkSignedToken(): tokenData = ${JSON.stringify(tokenData)}`);
+    if (tokenData == null)
+        return false;
+    if (!lodash_1.default.isEqual(data, tokenData))
+        return false;
+    return true;
+}
+exports.checkSignedToken = checkSignedToken;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@prairielearn/signed-token",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PrairieLearn/PrairieLearn.git",
+    "directory": "packages/signed-token"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch --preserveWatchOutput"
+  },
+  "devDependencies": {
+    "@prairielearn/tsconfig": "*",
+    "@types/debug": "^4.1.7",
+    "@types/node": "^18.14.2",
+    "mocha": "^10.2.0",
+    "typescript": "^4.9.5"
+  },
+  "dependencies": {
+    "base64url": "^3.0.1",
+    "debug": "^4.3.4",
+    "lodash": "^4.17.21"
+  }
+}

package/src/index.ts

@@ -0,0 +1,122 @@
+import base64url from 'base64url';
+import debugModule from 'debug';
+import _ from 'lodash';
+import crypto from 'node:crypto';
+
+const debug = debugModule('prairielearn:csrf');
+const sep = '.';
+
+interface CheckOptions {
+  maxAge?: number;
+}
+
+export function generateSignedToken(data: any, secretKey: string) {
+  debug(`generateSignedToken(): data = ${JSON.stringify(data)}`);
+  debug(`generateSignedToken(): secretKey = ${secretKey}`);
+  const dataJSON = JSON.stringify(data);
+  const dataString = base64url.encode(dataJSON);
+  const dateString = new Date().getTime().toString(36);
+  const checkString = dateString + sep + dataString;
+  const signature = crypto.createHmac('sha256', secretKey).update(checkString).digest('hex');
+  const encodedSignature = base64url.encode(signature);
+  debug(
+    `generateSignedToken(): ${JSON.stringify({
+      dataString,
+      dateString,
+      checkString,
+      encodedSignature,
+    })}`
+  );
+  const token = encodedSignature + sep + checkString;
+  debug(`generateSignedToken(): token = ${token}`);
+  return token;
+}
+
+export function getCheckedSignedTokenData(
+  token: string,
+  secretKey: string,
+  options: CheckOptions = {}
+) {
+  debug(`getCheckedSignedTokenData(): token = ${token}`);
+  debug(`getCheckedSignedTokenData(): secretKey = ${secretKey}`);
+  debug(`getCheckedSignedTokenData(): options = ${JSON.stringify(options)}`);
+  if (!_.isString(token)) {
+    debug(`getCheckedSignedTokenData(): FAIL - token is not string`);
+    return null;
+  }
+
+  // break token apart into the three components
+  const match = token.split(sep);
+  if (match == null) {
+    debug(`getCheckedSignedTokenData(): FAIL - could not split token`);
+    return null;
+  }
+  const tokenSignature = match[0];
+  const tokenDateString = match[1];
+  const tokenDataString = match[2];
+
+  // check the signature
+  const checkString = tokenDateString + sep + tokenDataString;
+  const checkSignature = crypto.createHmac('sha256', secretKey).update(checkString).digest('hex');
+  const encodedCheckSignature = base64url.encode(checkSignature);
+  if (encodedCheckSignature !== tokenSignature) {
+    debug(
+      `getCheckedSignedTokenData(): FAIL - signature mismatch: checkSig=${encodedCheckSignature} != tokenSig=${tokenSignature}`
+    );
+    return null;
+  }
+
+  // check the age if we have the maxAge parameter
+  if (options.maxAge != null) {
+    let tokenDate;
+    try {
+      tokenDate = new Date(parseInt(tokenDateString, 36));
+    } catch (e) {
+      debug(`getCheckedSignedTokenData(): FAIL - could not parse date: ${tokenDateString}`);
+      return null;
+    }
+    const currentTime = Date.now();
+    const elapsedTime = currentTime - tokenDate.getTime();
+    if (elapsedTime > options.maxAge) {
+      debug(
+        `getCheckedSignedTokenData(): FAIL - too old: elapsedTime=${elapsedTime} > maxAge=${options.maxAge}`
+      );
+      return null;
+    }
+  }
+
+  // get the data
+  let tokenDataJSON, tokenData;
+  try {
+    tokenDataJSON = base64url.decode(tokenDataString);
+  } catch (e) {
+    debug(`getCheckedSignedTokenData(): FAIL - could not base64 decode: ${tokenDateString}`);
+    return null;
+  }
+  try {
+    tokenData = JSON.parse(tokenDataJSON);
+  } catch (e) {
+    debug(`getCheckedSignedTokenData(): FAIL - could not parse JSON: ${tokenDataJSON}`);
+    return null;
+  }
+  debug(`getCheckedSignedTokenData(): tokenData = ${tokenData}`);
+  return tokenData;
+}
+
+export function checkSignedToken(
+  token: string,
+  data: any,
+  secretKey: string,
+  options: CheckOptions = {}
+) {
+  debug(`checkSignedToken(): token = ${token}`);
+  debug(`checkSignedToken(): data = ${JSON.stringify(data)}`);
+  debug(`checkSignedToken(): secretKey = ${secretKey}`);
+  debug(`checkSignedToken(): options = ${JSON.stringify(options)}`);
+  debug(`checkSignedToken(): data = ${JSON.stringify(data)}`);
+  const tokenData = getCheckedSignedTokenData(token, secretKey, options);
+  debug(`checkSignedToken(): tokenData = ${JSON.stringify(tokenData)}`);
+  if (tokenData == null) return false;
+  if (!_.isEqual(data, tokenData)) return false;
+  return true;
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@prairielearn/tsconfig",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+  },
+}