feat: add auth.format for formatting credentials

Author: Phillip9587

README.md

@@ -37,6 +37,11 @@ otherwise an object with `name` and `pass` properties.
 Parse a basic auth authorization header string. This will return an object
 with `name` and `pass` properties, or `undefined` if the string is invalid.
 
+### auth.format(credentials)
+
+Format a credentials object with `name` and `pass` properties as a basic
+auth authorization header string.
+
 ## Example
 
 Pass a Node.js request object to the module export. If parsing fails
@@ -60,6 +65,18 @@ var auth = require('basic-auth');
 var user = auth.parse(req.getHeader('Proxy-Authorization'));
 ```
 
+A credentials object can be formatted with `auth.format` as
+basic auth header string.
+
+<!-- eslint-disable no-unused-vars, no-undef -->
+
+```js
+var auth = require('basic-auth');
+var credentials = { name: 'foo', pass: 'bar' };
+var authHeader = auth.format(credentials);
+// => "Basic Zm9vOmJhcg=="
+```
+
 ### With vanilla node.js http server
 
 ```js

package.json

@@ -18,6 +18,7 @@
     "dist/"
   ],
   "scripts": {
+    "bench": "vitest bench",
     "build": "ts-scripts build",
     "format": "ts-scripts format",
     "lint": "ts-scripts lint",

src/format.bench.ts

@@ -0,0 +1,27 @@
+import { bench, describe } from 'vitest';
+import { format } from './index';
+
+describe('format', () => {
+  bench('format with simple credentials', () => {
+    const credentials = { name: 'user', pass: 'password' };
+    format(credentials);
+  });
+
+  bench('format with long credentials', () => {
+    const credentials = {
+      name: 'verylongusernameforbasicauth',
+      pass: 'verylongpasswordwithmanycharactersforbenchmark',
+    };
+    format(credentials);
+  });
+
+  bench('format with unicode credentials', () => {
+    const credentials = { name: 'jürgen', pass: 'pässwörd' };
+    format(credentials);
+  });
+
+  bench('format with special characters', () => {
+    const credentials = { name: 'user@domain', pass: 'p@ss!word#123' };
+    format(credentials);
+  });
+});

src/format.spec.ts

@@ -0,0 +1,124 @@
+import { describe, it, assert } from 'vitest';
+import { format } from './index';
+
+describe('format(credentials)', function () {
+  describe('arguments', function () {
+    describe('credentials', function () {
+      it('should be required', function () {
+        assert.throws(
+          () => (format as any)(),
+          /argument credentials is required/,
+        );
+      });
+
+      it('should accept credentials', function () {
+        const header = format({ name: 'foo', pass: 'bar' });
+        assert.strictEqual(header, 'Basic Zm9vOmJhcg==');
+      });
+
+      it('should reject null', function () {
+        assert.throws(
+          format.bind(null, null as any),
+          /argument credentials is required/,
+        );
+      });
+
+      it('should reject a number', function () {
+        assert.throws(
+          format.bind(null, 42 as any),
+          /argument credentials is required/,
+        );
+      });
+
+      it('should reject a string', function () {
+        assert.throws(
+          format.bind(null, '' as any),
+          /argument credentials is required/,
+        );
+      });
+
+      it('should reject an object without name', function () {
+        assert.throws(
+          format.bind(null, { pass: 'bar' } as any),
+          /argument credentials is required to have name and pass properties/,
+        );
+      });
+
+      it('should reject an object without pass', function () {
+        assert.throws(
+          format.bind(null, { name: 'foo' } as any),
+          /argument credentials is required to have name and pass properties/,
+        );
+      });
+
+      it('should reject an object with non-string name', function () {
+        assert.throws(
+          format.bind(null, { name: 42, pass: 'bar' } as any),
+          /argument credentials is required to have name and pass properties/,
+        );
+      });
+
+      it('should reject an object with non-string pass', function () {
+        assert.throws(
+          format.bind(null, { name: 'foo', pass: 42 } as any),
+          /argument credentials is required to have name and pass properties/,
+        );
+      });
+
+      it('should reject userid containing colon', function () {
+        assert.throws(
+          format.bind(null, { name: 'foo:bar', pass: 'baz' }),
+          /must not contain a colon or control characters/,
+        );
+      });
+
+      it('should reject control chars in userid', function () {
+        assert.throws(
+          format.bind(null, { name: 'foo\u0000bar', pass: 'baz' }),
+          /must not contain a colon or control characters/,
+        );
+      });
+
+      it('should reject control chars in password', function () {
+        assert.throws(
+          format.bind(null, { name: 'foo', pass: 'bar\u007f' }),
+          /must not contain control characters/,
+        );
+      });
+    });
+  });
+
+  describe('with valid credentials', function () {
+    it('should return header', function () {
+      const header = format({ name: 'foo', pass: 'bar' });
+      assert.strictEqual(header, 'Basic Zm9vOmJhcg==');
+    });
+  });
+
+  describe('with empty password', function () {
+    it('should throw', function () {
+      assert.throws(
+        format.bind(null, { name: 'foo', pass: '' }),
+        /argument credentials.name and credentials.pass must not be empty/,
+      );
+    });
+  });
+
+  describe('with empty userid', function () {
+    it('should throw', function () {
+      assert.throws(
+        format.bind(null, { name: '', pass: 'pass' }),
+        /argument credentials.name and credentials.pass must not be empty/,
+      );
+    });
+  });
+
+  describe('with empty userid and pass', function () {
+    it('should throw', function () {
+      assert.throws(
+        format.bind(null, { name: '', pass: '' }),
+        /argument credentials.name and credentials.pass must not be empty/,
+      );
+    });
+  });
+});

src/index.ts

@@ -47,6 +47,55 @@ export function parse(string: string): Credentials | undefined {
   return new CredentialsImpl(userPass[1], userPass[2]);
 }
 
+/**
+ * Format Basic Authorization Header
+ *
+ * @param {Credentials} credentials
+ * @return {string}
+ * @public
+ */
+export function format(credentials: Credentials): string {
+  if (!credentials) {
+    throw new TypeError('argument credentials is required');
+  }
+
+  if (typeof credentials !== 'object') {
+    throw new TypeError('argument credentials is required to be an object');
+  }
+
+  if (
+    typeof credentials.name !== 'string' ||
+    typeof credentials.pass !== 'string'
+  ) {
+    throw new TypeError(
+      'argument credentials is required to have name and pass properties',
+    );
+  }
+
+  if (credentials.name.length === 0 || credentials.pass.length === 0) {
+    throw new TypeError(
+      'argument credentials.name and credentials.pass must not be empty',
+    );
+  }
+
+  if (
+    credentials.name.includes(':') ||  // RFC 7617 disallows colon in username
+    CONTROL_CHARS_REGEXP.test(credentials.name)
+  ) {
+    throw new TypeError(
+      'argument credentials.name must not contain a colon or control characters',
+    );
+  }
+
+  if (CONTROL_CHARS_REGEXP.test(credentials.pass)) {
+    throw new TypeError(
+      'argument credentials.pass must not contain control characters',
+    );
+  }
+
+  return 'Basic ' + encodeBase64(credentials.name + ':' + credentials.pass);
+}
+
 /**
  * RegExp for basic auth credentials
  *
@@ -71,14 +120,27 @@ const CREDENTIALS_REGEXP =
 const USER_PASS_REGEXP = /^([^:]*):(.*)$/;
 
 /**
- * Decode base64 string.
+ * RegExp for RFC 5234 CTL characters (US-ASCII 0-31 and 127).
  * @private
  */
+const CONTROL_CHARS_REGEXP = /[\x00-\x1F\x7F]/;
 
+/**
+ * Decode base64 string.
+ * @private
+ */
 function decodeBase64(str: string): string {
   return Buffer.from(str, 'base64').toString();
 }
 
+/**
+ * Encode string to base64.
+ * @private
+ */
+function encodeBase64(str: string): string {
+  return Buffer.from(str, 'utf-8').toString('base64');
+}
+
 class CredentialsImpl implements Credentials {
   name: string;
   pass: string;