Add breachedDomain module (#538)

* feat: Add breachedDomain module

Co-authored-by: justin.r.hall <justin.r.hall@gmail.com>

* Refactor: Rename BreachedDomainResults to BreachedDomainsByEmailAlias

Co-authored-by: justin.r.hall <justin.r.hall@gmail.com>

* Increase maxSize for breached-domain.js in bundlewatch config

Co-authored-by: justin.r.hall <justin.r.hall@gmail.com>

* reorder ApiData members

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>

Author: wKovacs64

.bundlewatch.config.json

@@ -14,6 +14,10 @@
       "path": "dist/esm/breached-account.js",
       "maxSize": "1.2 kB"
     },
+    {
+      "path": "dist/esm/breached-domain.js",
+      "maxSize": "1.2 kB"
+    },
     {
       "path": "dist/esm/breaches.js",
       "maxSize": "1 kB"

.changeset/plain-cats-invite.md

@@ -0,0 +1,6 @@
+---
+"hibp": minor
+---
+
+Add `breachedDomain` module.
+

API.md

@@ -12,6 +12,18 @@
 without it will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts
 a valid API key on your behalf).</p>
 </dd>
+<dt><a href="#breachedDomain">breachedDomain(domain, [options])</a> ⇒ <code><a href="#breach--objectedDomainsByEmailAlias">Promise.&lt;BreachedDomainsByEmailAlias&gt;</a></code> | <code>Promise.&lt;null&gt;</code></dt>
+<dd><p>Fetches all breached email addresses for a domain.</p>
+<p>The result maps email aliases (the local-part before the &#39;@&#39;) to an array of
+breach names. For example, querying <code>example.com</code> could return an object like
+<code>{ &quot;john&quot;: [&quot;Adobe&quot;], &quot;jane&quot;: [&quot;Adobe&quot;, &quot;Gawker&quot;] }</code>, corresponding to
+<code>john@example.com</code> and <code>jane@example.com</code>.</p>
+<p>🔑 <code>haveibeenpwned.com</code> requires an API key from
+<a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a> for the <code>breacheddomain</code> endpoint. The
+<code>apiKey</code> option here is not explicitly required, but direct requests made
+without it will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts
+a valid API key on your behalf).</p>
+</dd>
 <dt><a href="#breaches">breaches([options])</a> ⇒ <code><a href="#breach--object">Promise.&lt;Array.&lt;Breach&gt;&gt;</a></code></dt>
 <dd><p>Fetches all breach events in the system.</p>
 </dd>
@@ -73,6 +85,10 @@ a valid API key on your behalf).</p>
 <dt><a href="#breach--object">Breach</a> : <code>object</code></dt>
 <dd><p>An object representing a breach.</p>
 </dd>
+<dt><a href="#breach--objectedDomainsByEmailAlias">BreachedDomainsByEmailAlias</a> : <code>Object.&lt;string, Array.&lt;string&gt;&gt;</code></dt>
+<dd><p>An object mapping an email alias (local-part before the &#39;@&#39;) to the list of
+breach names that alias has appeared in for the specified domain.</p>
+</dd>
 <dt><a href="#Paste">Paste</a> : <code>object</code></dt>
 <dd><p>An object representing a paste.</p>
 </dd>
@@ -194,6 +210,49 @@ try {
   // ...
 }
 ```
+<a name="breachedDomain"></a>
+
+## breachedDomain(domain, [options]) ⇒ [<code>Promise.&lt;BreachedDomainsByEmailAlias&gt;</code>](#breach--objectedDomainsByEmailAlias) \| <code>Promise.&lt;null&gt;</code>
+Fetches all breached email addresses for a domain.
+
+The result maps email aliases (the local-part before the '@') to an array of
+breach names. For example, querying `example.com` could return an object like
+`{ "john": ["Adobe"], "jane": ["Adobe", "Gawker"] }`, corresponding to
+`john@example.com` and `jane@example.com`.
+
+🔑 `haveibeenpwned.com` requires an API key from
+https://haveibeenpwned.com/API/Key for the `breacheddomain` endpoint. The
+`apiKey` option here is not explicitly required, but direct requests made
+without it will fail (unless you specify a `baseUrl` to a proxy that inserts
+a valid API key on your behalf).
+
+**Kind**: global function  
+**Returns**: [<code>Promise.&lt;BreachedDomainsByEmailAlias&gt;</code>](#breach--objectedDomainsByEmailAlias) \| <code>Promise.&lt;null&gt;</code> - a Promise which
+resolves to an object mapping aliases to breach name arrays (or null if no
+results were found), or rejects with an Error  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| domain | <code>string</code> | the domain to query (e.g., "example.com") |
+| [options] | <code>object</code> | a configuration object |
+| [options.apiKey] | <code>string</code> | an API key from https://haveibeenpwned.com/API/Key (default: undefined) |
+| [options.baseUrl] | <code>string</code> | a custom base URL for the haveibeenpwned.com API endpoints (default: `https://haveibeenpwned.com/api/v3`) |
+| [options.timeoutMs] | <code>number</code> | timeout for the request in milliseconds (default: none) |
+| [options.userAgent] | <code>string</code> | a custom string to send as the User-Agent field in the request headers (default: `hibp <version>`) |
+
+**Example**  
+```js
+try {
+  const data = await breachedDomain("example.com", { apiKey: "my-api-key" });
+  if (data) {
+    // { "john": ["Adobe"], "jane": ["Adobe", "Gawker"] }
+  } else {
+    // no results
+  }
+} catch (err) {
+  // ...
+}
+```
 <a name="breaches"></a>
 
 ## breaches([options]) ⇒ <code><a href="#breach--object">Promise.&lt;Array.&lt;Breach&gt;&gt;</a></code>
@@ -573,6 +632,13 @@ An object representing a breach.
 | IsSubscriptionFree | <code>boolean</code> | 
 | LogoPath | <code>string</code> | 
 
+<a name="BreachedDomainsByEmailAlias"></a>
+
+## BreachedDomainsByEmailAlias : <code>Object.&lt;string, Array.&lt;string&gt;&gt;</code>
+An object mapping an email alias (local-part before the '@') to the list of
+breach names that alias has appeared in for the specified domain.
+
+**Kind**: global typedef  
 <a name="Paste"></a>
 
 ## Paste : <code>object</code>

README.md

@@ -39,6 +39,7 @@ browser.
 - Get the most recently added breach
 - Get a single breach event
 - Get all breaches for an account 🔑
+- Get all breached email addresses for a domain 🔑
 - Get all breach events in the system
 - Get all data classes
 - Get all pastes for an account 🔑
@@ -65,6 +66,7 @@ The following modules are available:
 - [breach](API.md#breach)
 - [breachedAccount](API.md#breachedaccount)
 - [breaches](API.md#breaches)
+- [breachedDomain](API.md#breacheddomain)
 - [dataClasses](API.md#dataclasses)
 - [latestBreach](API.md#latestbreach)
 - [pasteAccount](API.md#pasteaccount)

src/__tests__/breached-domain.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest';
+import { http } from 'msw';
+import { server } from '../../mocks/server.js';
+import { NOT_FOUND } from '../api/haveibeenpwned/responses.js';
+import { breachedDomain } from '../breached-domain.js';
+
+describe('breachedDomain', () => {
+  const DOMAIN_RESULTS = { alias1: ['Adobe'], alias2: ['Adobe', 'Gawker'] };
+
+  describe('found', () => {
+    it('resolves with data from the remote API', () => {
+      server.use(
+        http.get('*', () => {
+          return new Response(JSON.stringify(DOMAIN_RESULTS));
+        }),
+      );
+
+      return expect(breachedDomain('example.com', { apiKey: 'k' })).resolves.toEqual(
+        DOMAIN_RESULTS,
+      );
+    });
+  });
+
+  describe('not found', () => {
+    it('resolves with null', () => {
+      server.use(
+        http.get('*', () => {
+          return new Response(null, { status: NOT_FOUND.status });
+        }),
+      );
+
+      return expect(breachedDomain('example.com')).resolves.toBeNull();
+    });
+  });
+
+  describe('apiKey option', () => {
+    it('sets the hibp-api-key header', async () => {
+      expect.assertions(1);
+      const apiKey = 'my-api-key';
+      server.use(
+        http.get('*', ({ request }) => {
+          expect(request.headers.get('hibp-api-key')).toBe(apiKey);
+          return new Response(JSON.stringify(DOMAIN_RESULTS));
+        }),
+      );
+
+      return breachedDomain('example.com', { apiKey });
+    });
+  });
+
+  describe('baseUrl option', () => {
+    it('is the beginning of the final URL', () => {
+      const baseUrl = 'https://my-hibp-proxy:8080';
+      server.use(
+        http.get(new RegExp(`^${baseUrl}`), () => {
+          return new Response(JSON.stringify(DOMAIN_RESULTS));
+        }),
+      );
+
+      return expect(breachedDomain('example.com', { baseUrl })).resolves.toEqual(DOMAIN_RESULTS);
+    });
+  });
+
+  describe('timeoutMs option', () => {
+    it('aborts the request after the given value', () => {
+      expect.assertions(1);
+      const timeoutMs = 1;
+      server.use(
+        http.get('*', async () => {
+          await new Promise((resolve) => {
+            setTimeout(resolve, timeoutMs + 1);
+          });
+          return new Response(JSON.stringify(DOMAIN_RESULTS));
+        }),
+      );
+
+      return expect(breachedDomain('example.com', { timeoutMs })).rejects.toMatchInlineSnapshot(
+        `[TimeoutError: The operation was aborted due to timeout]`,
+      );
+    });
+  });
+
+  describe('userAgent option', () => {
+    it('is passed on as a request header', () => {
+      expect.assertions(1);
+      const userAgent = 'Custom UA';
+      server.use(
+        http.get('*', ({ request }) => {
+          expect(request.headers.get('User-Agent')).toBe(userAgent);
+          return new Response(JSON.stringify(DOMAIN_RESULTS));
+        }),
+      );
+
+      return breachedDomain('example.com', { userAgent });
+    });
+  });
+});

src/__tests__/hibp.test.ts

@@ -8,6 +8,7 @@ describe('hibp', () => {
         "RateLimitError": [Function],
         "breach": [Function],
         "breachedAccount": [Function],
+        "breachedDomain": [Function],
         "breaches": [Function],
         "dataClasses": [Function],
         "latestBreach": [Function],

src/api/haveibeenpwned/types.ts

@@ -39,6 +39,8 @@ export interface SubscriptionStatus {
   IncludesStealerLogs: boolean;
 }
 
+export type BreachedDomainsByEmailAlias = Record<string, string[]>;
+
 //
 // Internal convenience types
 //
@@ -51,6 +53,7 @@ export interface SubscriptionStatus {
 export type ApiData =
   | Breach // breach
   | Breach[] // breachedaccount, breaches
+  | BreachedDomainsByEmailAlias // breacheddomain
   | Paste[] // pasteaccount
   | string[] // dataclasses
   | SubscriptionStatus // subscription/status

src/breached-domain.ts

@@ -0,0 +1,83 @@
+import type { BreachedDomainsByEmailAlias } from './api/haveibeenpwned/types.js';
+import { fetchFromApi } from './api/haveibeenpwned/fetch-from-api.js';
+
+/**
+ * An object mapping an email alias (local-part before the '@') to the list of
+ * breach names that alias has appeared in for the specified domain.
+ *
+ * @typedef {Object.<string, string[]>} BreachedDomainsByEmailAlias
+ */
+
+/**
+ * Fetches all breached email addresses for a domain.
+ *
+ * The result maps email aliases (the local-part before the '@') to an array of
+ * breach names. For example, querying `example.com` could return an object like
+ * `{ "john": ["Adobe"], "jane": ["Adobe", "Gawker"] }`, corresponding to
+ * `john@example.com` and `jane@example.com`.
+ *
+ * 🔑 `haveibeenpwned.com` requires an API key from
+ * https://haveibeenpwned.com/API/Key for the `breacheddomain` endpoint. The
+ * `apiKey` option here is not explicitly required, but direct requests made
+ * without it will fail (unless you specify a `baseUrl` to a proxy that inserts
+ * a valid API key on your behalf).
+ *
+ * @param {string} domain the domain to query (e.g., "example.com")
+ * @param {object} [options] a configuration object
+ * @param {string} [options.apiKey] an API key from
+ * https://haveibeenpwned.com/API/Key (default: undefined)
+ * @param {string} [options.baseUrl] a custom base URL for the
+ * haveibeenpwned.com API endpoints (default:
+ * `https://haveibeenpwned.com/api/v3`)
+ * @param {number} [options.timeoutMs] timeout for the request in milliseconds
+ * (default: none)
+ * @param {string} [options.userAgent] a custom string to send as the User-Agent
+ * field in the request headers (default: `hibp <version>`)
+ * @returns {(Promise<BreachedDomainsByEmailAlias> | Promise<null>)} a Promise which
+ * resolves to an object mapping aliases to breach name arrays (or null if no
+ * results were found), or rejects with an Error
+ * @example
+ * try {
+ *   const data = await breachedDomain("example.com", { apiKey: "my-api-key" });
+ *   if (data) {
+ *     // { "john": ["Adobe"], "jane": ["Adobe", "Gawker"] }
+ *   } else {
+ *     // no results
+ *   }
+ * } catch (err) {
+ *   // ...
+ * }
+ */
+export function breachedDomain(
+  domain: string,
+  options: {
+    /**
+     * an API key from https://haveibeenpwned.com/API/Key (default: undefined)
+     */
+    apiKey?: string;
+    /**
+     * a custom base URL for the haveibeenpwned.com API endpoints (default:
+     * `https://haveibeenpwned.com/api/v3`)
+     */
+    baseUrl?: string;
+    /**
+     * timeout for the request in milliseconds (default: none)
+     */
+    timeoutMs?: number;
+    /**
+     * a custom string to send as the User-Agent field in the request headers
+     * (default: `hibp <version>`)
+     */
+    userAgent?: string;
+  } = {},
+): Promise<BreachedDomainsByEmailAlias | null> {
+  const { apiKey, baseUrl, timeoutMs, userAgent } = options;
+  const endpoint = `/breacheddomain/${encodeURIComponent(domain)}`;
+
+  return fetchFromApi(endpoint, {
+    apiKey,
+    baseUrl,
+    timeoutMs,
+    userAgent,
+  }) as Promise<BreachedDomainsByEmailAlias | null>;
+}

src/hibp.ts

@@ -1,6 +1,7 @@
 import { RateLimitError } from './api/haveibeenpwned/fetch-from-api.js';
 import { breach } from './breach.js';
 import { breachedAccount } from './breached-account.js';
+import { breachedDomain } from './breached-domain.js';
 import { breaches } from './breaches.js';
 import { dataClasses } from './data-classes.js';
 import { latestBreach } from './latest-breach.js';
@@ -24,6 +25,7 @@ export type * from './api/haveibeenpwned/types.js';
 export {
   breach,
   breachedAccount,
+  breachedDomain,
   breaches,
   dataClasses,
   latestBreach,
@@ -39,6 +41,7 @@ export {
 export interface HIBP {
   breach: typeof breach;
   breachedAccount: typeof breachedAccount;
+  breachedDomain: typeof breachedDomain;
   breaches: typeof breaches;
   dataClasses: typeof dataClasses;
   latestBreach: typeof latestBreach;