Implement stealerLogsByEmailDomain module (#543)

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

Author: wKovacs64

.bundlewatch.config.json

@@ -50,9 +50,13 @@
       "path": "dist/esm/stealer-logs-by-email.js",
       "maxSize": "1 kB"
     },
+    {
+      "path": "dist/esm/stealer-logs-by-email-domain.js",
+      "maxSize": "1.2 kB"
+    },
     {
       "path": "dist/esm/stealer-logs-by-website-domain.js",
-      "maxSize": "1.1 kB"
+      "maxSize": "1 kB"
     },
     {
       "path": "dist/esm/subscribed-domains.js",

.changeset/add-stealer-logs-by-email-domain-module.md

@@ -0,0 +1,5 @@
+---
+'hibp': minor
+---
+
+Add `stealerLogsByEmailDomain` module.

API.md

@@ -69,6 +69,17 @@ convenience method is designed to mimic.</p>
 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="#stealerLogsByEmailDomain">stealerLogsByEmailDomain(emailDomain, [options])</a> ⇒ <code><a href="#StealerLogDomainsByEmailAlias">Promise.&lt;StealerLogDomainsByEmailAlias&gt;</a></code> | <code>Promise.&lt;null&gt;</code></dt>
+<dd><p>Fetches all stealer log email aliases for an email domain.</p>
+<p>The result maps email aliases (the local-part before the &#39;@&#39;) to an array of
+email domains found in stealer logs. For example, querying <code>example.com</code>
+could return an object like <code>{ &quot;andy&quot;: [&quot;netflix.com&quot;], &quot;jane&quot;: [&quot;netflix.com&quot;, &quot;spotify.com&quot;] }</code>, corresponding to <code>andy@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>stealerlogsbyemaildomain</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="#stealerLogsByEmail">stealerLogsByEmail(emailAddress, [options])</a> ⇒ <code>Promise.&lt;Array.&lt;string&gt;&gt;</code> | <code>Promise.&lt;null&gt;</code></dt>
 <dd><p>Fetches all stealer log domains for an email address.</p>
 <p>Returns an array of domains for which stealer logs contain entries for the
@@ -130,6 +141,11 @@ hash prefix) to how many times it occurred in the Pwned Passwords repository.</p
 <dt><a href="#SearchResults">SearchResults</a> : <code>object</code></dt>
 <dd><p>An object representing search results.</p>
 </dd>
+<dt><a href="#StealerLogDomainsByEmailAlias">StealerLogDomainsByEmailAlias</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
+email domains that alias has appeared in within stealer logs for the specified
+email domain.</p>
+</dd>
 <dt><a href="#SubscribedDomain">SubscribedDomain</a> : <code>object</code></dt>
 <dd><p>An object representing a subscribed domain.</p>
 </dd>
@@ -595,6 +611,49 @@ try {
   // ...
 }
 ```
+<a name="stealerLogsByEmailDomain"></a>
+
+## stealerLogsByEmailDomain(emailDomain, [options]) ⇒ [<code>Promise.&lt;StealerLogDomainsByEmailAlias&gt;</code>](#StealerLogDomainsByEmailAlias) \| <code>Promise.&lt;null&gt;</code>
+Fetches all stealer log email aliases for an email domain.
+
+The result maps email aliases (the local-part before the '@') to an array of
+email domains found in stealer logs. For example, querying `example.com`
+could return an object like `{ "andy": ["netflix.com"], "jane": ["netflix.com",
+"spotify.com"] }`, corresponding to `andy@example.com` and `jane@example.com`.
+
+🔑 `haveibeenpwned.com` requires an API key from
+https://haveibeenpwned.com/API/Key for the `stealerlogsbyemaildomain` 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;StealerLogDomainsByEmailAlias&gt;</code>](#StealerLogDomainsByEmailAlias) \| <code>Promise.&lt;null&gt;</code> - a Promise
+which resolves to an object mapping aliases to stealer log email domain arrays
+(or null if no results were found), or rejects with an Error  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| emailDomain | <code>string</code> | the email 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 stealerLogsByEmailDomain("example.com", { apiKey: "my-api-key" });
+  if (data) {
+    // { "andy": ["netflix.com"], "jane": ["netflix.com", "spotify.com"] }
+  } else {
+    // no results
+  }
+} catch (err) {
+  // ...
+}
+```
 <a name="stealerLogsByEmail"></a>
 
 ## stealerLogsByEmail(emailAddress, [options]) ⇒ <code>Promise.&lt;Array.&lt;string&gt;&gt;</code> \| <code>Promise.&lt;null&gt;</code>
@@ -868,6 +927,14 @@ An object representing search results.
 | breaches | [<code>Array.&lt;Breach&gt;</code>](#breach--object) \| <code>null</code> | 
 | pastes | [<code>Array.&lt;Paste&gt;</code>](#Paste) \| <code>null</code> | 
 
+<a name="StealerLogDomainsByEmailAlias"></a>
+
+## StealerLogDomainsByEmailAlias : <code>Object.&lt;string, Array.&lt;string&gt;&gt;</code>
+An object mapping an email alias (local-part before the '@') to the list of
+email domains that alias has appeared in within stealer logs for the specified
+email domain.
+
+**Kind**: global typedef  
 <a name="SubscribedDomain"></a>
 
 ## SubscribedDomain : <code>object</code>

README.md

@@ -40,6 +40,7 @@ browser.
 - Get a single breach event
 - Get all breaches for an account 🔑
 - Get all breached email addresses for a domain 🔑
+- Get all stealer log email aliases for an email domain 🔑
 - Get all breach events in the system
 - Get all data classes
 - Get all pastes for an account 🔑
@@ -75,6 +76,7 @@ The following modules are available:
 - [pwnedPasswordRange](API.md#pwnedpasswordrange)
 - [search](API.md#search)
 - [stealerLogsByEmail](API.md#stealerlogsbyemail)
+- [stealerLogsByEmailDomain](API.md#stealerlogsbyemaildomain)
 - [stealerLogsByWebsiteDomain](API.md#stealerlogsbywebsitedomain)
 - [subscribedDomains](API.md#subscribeddomains)
 - [subscriptionStatus](API.md#subscriptionstatus)

src/__tests__/hibp.test.ts

@@ -17,6 +17,7 @@ describe('hibp', () => {
         "pwnedPasswordRange": [Function],
         "search": [Function],
         "stealerLogsByEmail": [Function],
+        "stealerLogsByEmailDomain": [Function],
         "stealerLogsByWebsiteDomain": [Function],
         "subscribedDomains": [Function],
         "subscriptionStatus": [Function],

src/__tests__/stealer-logs-by-email-domain.test.ts

@@ -0,0 +1,99 @@
+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 { stealerLogsByEmailDomain } from '../stealer-logs-by-email-domain.js';
+
+describe('stealerLogsByEmailDomain', () => {
+  const STEALER_RESULTS = { andy: ['netflix.com'], jane: ['netflix.com', 'spotify.com'] };
+
+  describe('found', () => {
+    it('resolves with data from the remote API', () => {
+      server.use(
+        http.get('*', () => {
+          return new Response(JSON.stringify(STEALER_RESULTS));
+        }),
+      );
+
+      return expect(stealerLogsByEmailDomain('example.com', { apiKey: 'k' })).resolves.toEqual(
+        STEALER_RESULTS,
+      );
+    });
+  });
+
+  describe('not found', () => {
+    it('resolves with null', () => {
+      server.use(
+        http.get('*', () => {
+          return new Response(null, { status: NOT_FOUND.status });
+        }),
+      );
+
+      return expect(stealerLogsByEmailDomain('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(STEALER_RESULTS));
+        }),
+      );
+
+      return stealerLogsByEmailDomain('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(STEALER_RESULTS));
+        }),
+      );
+
+      return expect(stealerLogsByEmailDomain('example.com', { baseUrl })).resolves.toEqual(
+        STEALER_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(STEALER_RESULTS));
+        }),
+      );
+
+      return expect(
+        stealerLogsByEmailDomain('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(STEALER_RESULTS));
+        }),
+      );
+
+      return stealerLogsByEmailDomain('example.com', { userAgent });
+    });
+  });
+});

src/api/haveibeenpwned/types.ts

@@ -49,6 +49,8 @@ export interface SubscribedDomain {
 
 export type BreachedDomainsByEmailAlias = Record<string, string[]>;
 
+export type StealerLogDomainsByEmailAlias = Record<string, string[]>;
+
 //
 // Internal convenience types
 //
@@ -63,7 +65,8 @@ export type ApiData =
   | Breach[] // breachedaccount, breaches
   | BreachedDomainsByEmailAlias // breacheddomain
   | Paste[] // pasteaccount
-  | string[] // dataclasses
+  | string[] // dataclasses, stealerlogsbyemail, stealerlogsbywebsitedomain
+  | StealerLogDomainsByEmailAlias // stealerlogsbyemaildomain
   | SubscriptionStatus // subscription/status
   | SubscribedDomain[] // subscribeddomains
   | null; // most endpoints can return an empty response (404, but not an error)

src/hibp.ts

@@ -10,6 +10,7 @@ import { pwnedPassword } from './pwned-password.js';
 import { pwnedPasswordRange } from './pwned-password-range.js';
 import { search } from './search.js';
 import { stealerLogsByEmail } from './stealer-logs-by-email.js';
+import { stealerLogsByEmailDomain } from './stealer-logs-by-email-domain.js';
 import { stealerLogsByWebsiteDomain } from './stealer-logs-by-website-domain.js';
 import { subscribedDomains } from './subscribed-domains.js';
 import { subscriptionStatus } from './subscription-status.js';
@@ -37,6 +38,7 @@ export {
   pwnedPasswordRange,
   search,
   stealerLogsByEmail,
+  stealerLogsByEmailDomain,
   stealerLogsByWebsiteDomain,
   subscribedDomains,
   subscriptionStatus,
@@ -56,6 +58,7 @@ export interface HIBP {
   pwnedPasswordRange: typeof pwnedPasswordRange;
   search: typeof search;
   stealerLogsByEmail: typeof stealerLogsByEmail;
+  stealerLogsByEmailDomain: typeof stealerLogsByEmailDomain;
   stealerLogsByWebsiteDomain: typeof stealerLogsByWebsiteDomain;
   subscribedDomains: typeof subscribedDomains;
   subscriptionStatus: typeof subscriptionStatus;

src/stealer-logs-by-email-domain.ts

@@ -0,0 +1,84 @@
+import type { StealerLogDomainsByEmailAlias } 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
+ * email domains that alias has appeared in within stealer logs for the specified
+ * email domain.
+ *
+ * @typedef {Object.<string, string[]>} StealerLogDomainsByEmailAlias
+ */
+
+/**
+ * Fetches all stealer log email aliases for an email domain.
+ *
+ * The result maps email aliases (the local-part before the '@') to an array of
+ * email domains found in stealer logs. For example, querying `example.com`
+ * could return an object like `{ "andy": ["netflix.com"], "jane": ["netflix.com",
+ * "spotify.com"] }`, corresponding to `andy@example.com` and `jane@example.com`.
+ *
+ * 🔑 `haveibeenpwned.com` requires an API key from
+ * https://haveibeenpwned.com/API/Key for the `stealerlogsbyemaildomain` 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} emailDomain the email 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<StealerLogDomainsByEmailAlias> | Promise<null>)} a Promise
+ * which resolves to an object mapping aliases to stealer log email domain arrays
+ * (or null if no results were found), or rejects with an Error
+ * @example
+ * try {
+ *   const data = await stealerLogsByEmailDomain("example.com", { apiKey: "my-api-key" });
+ *   if (data) {
+ *     // { "andy": ["netflix.com"], "jane": ["netflix.com", "spotify.com"] }
+ *   } else {
+ *     // no results
+ *   }
+ * } catch (err) {
+ *   // ...
+ * }
+ */
+export function stealerLogsByEmailDomain(
+  emailDomain: 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<StealerLogDomainsByEmailAlias | null> {
+  const { apiKey, baseUrl, timeoutMs, userAgent } = options;
+  const endpoint = `/stealerlogsbyemaildomain/${encodeURIComponent(emailDomain)}`;
+
+  return fetchFromApi(endpoint, {
+    apiKey,
+    baseUrl,
+    timeoutMs,
+    userAgent,
+  }) as Promise<StealerLogDomainsByEmailAlias | null>;
+}