feat: add the addPadding option to pwnedPassword and pwnedPasswordRange (#421)

Author: wKovacs64

.changeset/wicked-insects-melt.md

@@ -0,0 +1,5 @@
+---
+'hibp': minor
+---
+
+Add `addPadding` option to `pwnedPassword` and `pwnedPasswordRange` modules. See https://www.troyhunt.com/enhancing-pwned-passwords-privacy-with-padding/ for more information.

src/__tests__/pwned-password-range.test.ts

@@ -19,4 +19,18 @@ describe('pwnedPasswordRange', () => {
       });
     });
   });
+
+  describe('addPadding option', () => {
+    it('causes Add-Padding header to be included in the request', async () => {
+      expect.assertions(1);
+      server.use(
+        http.get('*', ({ request }) => {
+          expect(request.headers.get('Add-Padding')).toBe('true');
+          return new Response(EXAMPLE_PASSWORD_HASHES);
+        }),
+      );
+
+      await pwnedPasswordRange('5BAA6', { addPadding: true });
+    });
+  });
 });

src/__tests__/pwned-password.test.ts

@@ -27,4 +27,18 @@ describe('pwnedPassword', () => {
       return expect(pwnedPassword('kjfhsdksjf454145jkhk!!!')).resolves.toBe(0);
     });
   });
+
+  describe('addPadding option', () => {
+    it('causes Add-Padding header to be included in the request', async () => {
+      expect.assertions(1);
+      server.use(
+        http.get('*', ({ request }) => {
+          expect(request.headers.get('Add-Padding')).toBe('true');
+          return new Response(EXAMPLE_PASSWORD_HASHES);
+        }),
+      );
+
+      await pwnedPassword('password', { addPadding: true });
+    });
+  });
 });

src/api/pwnedpasswords/fetch-from-api.ts

@@ -15,6 +15,8 @@ import { BAD_REQUEST } from './responses.js';
  * pwnedpasswords.com API endpoints (default: `https://api.pwnedpasswords.com`)
  * @param {string} [options.userAgent] a custom string to send as the User-Agent
  * field in the request headers (default: `hibp <version>`)
+ * @param {boolean} [options.addPadding] ask the remote API to add padding to
+ * the response to obscure the password prefix (default: `false`)
  * @returns {Promise<string>} a Promise which resolves to the data resulting
  * from the query, or rejects with an Error
  */
@@ -23,17 +25,13 @@ export async function fetchFromApi(
   {
     baseUrl = 'https://api.pwnedpasswords.com',
     userAgent,
-  }: { baseUrl?: string; userAgent?: string } = {},
+    addPadding = false,
+  }: { baseUrl?: string; userAgent?: string; addPadding?: boolean } = {},
 ): Promise<string> {
   const config = Object.assign(
     {},
-    userAgent
-      ? {
-          headers: {
-            'User-Agent': userAgent,
-          },
-        }
-      : {},
+    userAgent ? { headers: { 'User-Agent': userAgent } } : {},
+    addPadding ? { headers: { 'Add-Padding': 'true' } } : {},
   );
   const url = `${baseUrl.replace(/\/$/g, '')}${endpoint}`;
   const response = await fetch(url, config);

src/pwned-password-range.ts

@@ -25,6 +25,8 @@ export type PwnedPasswordSuffixes = Record<string, number>;
  * pwnedpasswords.com API endpoints (default: `https://api.pwnedpasswords.com`)
  * @param {string} [options.userAgent] a custom string to send as the User-Agent
  * field in the request headers (default: `hibp <version>`)
+ * @param {boolean} [options.addPadding] ask the remote API to add padding to
+ * the response to obscure the password prefix (default: `false`)
  * @returns {Promise<PwnedPasswordSuffixes>} a Promise which resolves to an
  * object mapping the `suffix` that when matched with the prefix composes the
  * complete hash, to the `count` of how many times it appears in the breached
@@ -54,7 +56,7 @@ export type PwnedPasswordSuffixes = Record<string, number>;
  */
 export async function pwnedPasswordRange(
   prefix: string,
-  options: { baseUrl?: string; userAgent?: string } = {},
+  options: { baseUrl?: string; userAgent?: string; addPadding?: boolean } = {},
 ): Promise<PwnedPasswordSuffixes> {
   const data = await fetchFromApi(
     `/range/${encodeURIComponent(prefix)}`,

src/pwned-password.ts

@@ -12,6 +12,8 @@ import { pwnedPasswordRange } from './pwned-password-range.js';
  * pwnedpasswords.com API endpoints (default: `https://api.pwnedpasswords.com`)
  * @param {string} [options.userAgent] a custom string to send as the User-Agent
  * field in the request headers (default: `hibp <version>`)
+ * @param {boolean} [options.addPadding] ask the remote API to add padding to
+ * the response to obscure the password prefix (default: `false`)
  * @returns {Promise<number>} a Promise which resolves to the number of times
  * the password has been exposed in a breach, or rejects with an Error
  * @example
@@ -30,7 +32,7 @@ import { pwnedPasswordRange } from './pwned-password-range.js';
  */
 export async function pwnedPassword(
   password: string,
-  options: { baseUrl?: string; userAgent?: string } = {},
+  options: { baseUrl?: string; userAgent?: string; addPadding?: boolean } = {},
 ): Promise<number> {
   /* eslint-disable */
   // @ts-expect-error: JSSHA types are busted