hibp 15.2.1 → 16.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/API.md +433 -126
- package/CHANGELOG.md +44 -0
- package/MIGRATION.md +7 -5
- package/README.md +53 -27
- package/dist/browser/hibp.module.js +2 -2
- package/dist/esm/api/base-fetch.d.ts +3 -1
- package/dist/esm/api/base-fetch.js +20 -7
- package/dist/esm/api/base-fetch.js.map +1 -1
- package/dist/esm/api/haveibeenpwned/fetch-from-api.d.ts +1 -1
- package/dist/esm/api/haveibeenpwned/fetch-from-api.js +71 -24
- package/dist/esm/api/haveibeenpwned/fetch-from-api.js.map +1 -1
- package/dist/esm/api/haveibeenpwned/package-info.d.ts +1 -1
- package/dist/esm/api/haveibeenpwned/package-info.js +1 -1
- package/dist/esm/api/haveibeenpwned/post-to-api.d.ts +1 -0
- package/dist/esm/api/haveibeenpwned/post-to-api.js +31 -0
- package/dist/esm/api/haveibeenpwned/post-to-api.js.map +1 -0
- package/dist/esm/api/haveibeenpwned/responses.js +8 -7
- package/dist/esm/api/haveibeenpwned/responses.js.map +1 -1
- package/dist/esm/api/haveibeenpwned/types.d.ts +22 -2
- package/dist/esm/api/pwnedpasswords/fetch-from-api.js +4 -4
- package/dist/esm/api/pwnedpasswords/fetch-from-api.js.map +1 -1
- package/dist/esm/api/pwnedpasswords/responses.js +1 -1
- package/dist/esm/breach.d.ts +8 -1
- package/dist/esm/breach.js +8 -1
- package/dist/esm/breach.js.map +1 -1
- package/dist/esm/breached-account-range.d.ts +73 -0
- package/dist/esm/breached-account-range.js +60 -0
- package/dist/esm/breached-account-range.js.map +1 -0
- package/dist/esm/breached-account.d.ts +56 -45
- package/dist/esm/breached-account.js +4 -76
- package/dist/esm/breached-account.js.map +1 -1
- package/dist/esm/breached-domain.d.ts +2 -3
- package/dist/esm/breached-domain.js +2 -3
- package/dist/esm/breached-domain.js.map +1 -1
- package/dist/esm/breaches.d.ts +9 -2
- package/dist/esm/breaches.js +10 -5
- package/dist/esm/breaches.js.map +1 -1
- package/dist/esm/data-class-descriptions.d.ts +55 -0
- package/dist/esm/data-class-descriptions.js +39 -0
- package/dist/esm/data-class-descriptions.js.map +1 -0
- package/dist/esm/data-classes.js +2 -2
- package/dist/esm/data-classes.js.map +1 -1
- package/dist/esm/generate-dns-token.d.ts +67 -0
- package/dist/esm/generate-dns-token.js +48 -0
- package/dist/esm/generate-dns-token.js.map +1 -0
- package/dist/esm/hibp.d.ts +28 -18
- package/dist/esm/hibp.js +23 -18
- package/dist/esm/hibp.js.map +1 -1
- package/dist/esm/latest-breach.d.ts +1 -1
- package/dist/esm/latest-breach.js +2 -2
- package/dist/esm/latest-breach.js.map +1 -1
- package/dist/esm/paste-account.d.ts +8 -8
- package/dist/esm/paste-account.js +8 -8
- package/dist/esm/paste-account.js.map +1 -1
- package/dist/esm/pwned-password-range.d.ts +1 -1
- package/dist/esm/pwned-password-range.js +4 -4
- package/dist/esm/pwned-password-range.js.map +1 -1
- package/dist/esm/pwned-password.js +6 -6
- package/dist/esm/pwned-password.js.map +1 -1
- package/dist/esm/search.d.ts +57 -40
- package/dist/esm/search.js +3 -72
- package/dist/esm/search.js.map +1 -1
- package/dist/esm/send-email.d.ts +69 -0
- package/dist/esm/send-email.js +49 -0
- package/dist/esm/send-email.js.map +1 -0
- package/dist/esm/stealer-logs-by-email-domain.d.ts +8 -9
- package/dist/esm/stealer-logs-by-email-domain.js +8 -9
- package/dist/esm/stealer-logs-by-email-domain.js.map +1 -1
- package/dist/esm/stealer-logs-by-email.d.ts +4 -5
- package/dist/esm/stealer-logs-by-email.js +5 -6
- package/dist/esm/stealer-logs-by-email.js.map +1 -1
- package/dist/esm/stealer-logs-by-website-domain.d.ts +4 -5
- package/dist/esm/stealer-logs-by-website-domain.js +5 -6
- package/dist/esm/stealer-logs-by-website-domain.js.map +1 -1
- package/dist/esm/subscribed-domains.d.ts +2 -3
- package/dist/esm/subscribed-domains.js +3 -4
- package/dist/esm/subscribed-domains.js.map +1 -1
- package/dist/esm/subscription-status.d.ts +11 -6
- package/dist/esm/subscription-status.js +12 -7
- package/dist/esm/subscription-status.js.map +1 -1
- package/dist/esm/verify-dns-token.d.ts +60 -0
- package/dist/esm/verify-dns-token.js +41 -0
- package/dist/esm/verify-dns-token.js.map +1 -0
- package/package.json +55 -56
package/API.md
CHANGED
|
@@ -4,22 +4,34 @@
|
|
|
4
4
|
<dt><a href="#breach">breach(breachName, [options])</a> ⇒ <code><a href="#breach--object">Promise.<Breach></a></code> | <code>Promise.<null></code></dt>
|
|
5
5
|
<dd><p>Fetches data for a specific breach event.</p>
|
|
6
6
|
</dd>
|
|
7
|
-
<dt><a href="#
|
|
8
|
-
<dd><p>Fetches
|
|
9
|
-
|
|
10
|
-
<a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a
|
|
11
|
-
<code>apiKey</code> option here is not explicitly required, but direct requests made
|
|
7
|
+
<dt><a href="#breachedAccountRange">breachedAccountRange(prefix, [options])</a> ⇒ <code><a href="#breachedaccountrangeresult--object">Promise.<Array.<BreachedAccountRangeResult>></a></code> | <code>Promise.<null></code></dt>
|
|
8
|
+
<dd><p>Fetches breached email hash suffixes for a six-character SHA-1 email hash
|
|
9
|
+
prefix.</p>
|
|
10
|
+
<p>Requires a Pro or High RPM API key from <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>.
|
|
11
|
+
The <code>apiKey</code> option here is not explicitly required, but direct requests made
|
|
12
12
|
without it will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts
|
|
13
13
|
a valid API key on your behalf).</p>
|
|
14
|
+
<p>Compare suffixes locally against the intended email hash. Per the
|
|
15
|
+
haveibeenpwned.com terms of use, discard unrelated results immediately
|
|
16
|
+
without storing or further processing them.</p>
|
|
14
17
|
</dd>
|
|
15
|
-
<dt><a href="#
|
|
18
|
+
<dt><a href="#breachedAccount">breachedAccount(account, [options])</a> ⇒ <code><a href="#breach--object">Promise.<Array.<Breach>></a></code> | <code>Promise.<null></code></dt>
|
|
19
|
+
<dd><p>Fetches breach data for a specific account.</p>
|
|
20
|
+
<p>Results contain only <code>Name</code> by default; pass <code>truncate: false</code> for full
|
|
21
|
+
breaches.</p>
|
|
22
|
+
<p>Requires a Core, Pro, or High RPM API key from
|
|
23
|
+
<a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code> option here is not
|
|
24
|
+
explicitly required, but direct requests made without it will fail (unless
|
|
25
|
+
you specify a <code>baseUrl</code> to a proxy that inserts a valid API key on your
|
|
26
|
+
behalf).</p>
|
|
27
|
+
</dd>
|
|
28
|
+
<dt><a href="#breachedDomain">breachedDomain(domain, [options])</a> ⇒ <code><a href="#BreachedDomainsByEmailAlias">Promise.<BreachedDomainsByEmailAlias></a></code> | <code>Promise.<null></code></dt>
|
|
16
29
|
<dd><p>Fetches all breached email addresses for a domain.</p>
|
|
17
30
|
<p>The result maps email aliases (the local-part before the '@') to an array of
|
|
18
31
|
breach names. For example, querying <code>example.com</code> could return an object like
|
|
19
32
|
<code>{ "john": ["Adobe"], "jane": ["Adobe", "Gawker"] }</code>, corresponding to
|
|
20
33
|
<code>john@example.com</code> and <code>jane@example.com</code>.</p>
|
|
21
|
-
<p
|
|
22
|
-
<a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a> for the <code>breacheddomain</code> endpoint. The
|
|
34
|
+
<p>Requires a Core or Pro API key from <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The
|
|
23
35
|
<code>apiKey</code> option here is not explicitly required, but direct requests made
|
|
24
36
|
without it will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts
|
|
25
37
|
a valid API key on your behalf).</p>
|
|
@@ -27,19 +39,31 @@ a valid API key on your behalf).</p>
|
|
|
27
39
|
<dt><a href="#breaches">breaches([options])</a> ⇒ <code><a href="#breach--object">Promise.<Array.<Breach>></a></code></dt>
|
|
28
40
|
<dd><p>Fetches all breach events in the system.</p>
|
|
29
41
|
</dd>
|
|
42
|
+
<dt><a href="#dataClassDescriptions">dataClassDescriptions([options])</a> ⇒ <code><a href="#dataclassdescription--object">Promise.<Array.<DataClassDescription>></a></code> | <code>Promise.<null></code></dt>
|
|
43
|
+
<dd><p>Fetches all data class names and descriptions.</p>
|
|
44
|
+
</dd>
|
|
30
45
|
<dt><a href="#dataClasses">dataClasses([options])</a> ⇒ <code>Promise.<Array.<string>></code> | <code>Promise.<null></code></dt>
|
|
31
46
|
<dd><p>Fetches all data classes in the system.</p>
|
|
32
47
|
</dd>
|
|
48
|
+
<dt><a href="#generateDnsToken">generateDnsToken(domain, [options])</a> ⇒ <code><a href="#DnsToken">Promise.<DnsToken></a></code></dt>
|
|
49
|
+
<dd><p>Generates a domain-specific DNS verification token.</p>
|
|
50
|
+
<p>Publish <code>txtRecordValue</code> as a TXT record on the domain, then call
|
|
51
|
+
<code>verifyDnsToken</code> after DNS propagation.</p>
|
|
52
|
+
<p>Requires a Pro API key from <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code>
|
|
53
|
+
option here is not explicitly required, but direct requests made without it
|
|
54
|
+
will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts a valid API
|
|
55
|
+
key on your behalf).</p>
|
|
56
|
+
</dd>
|
|
33
57
|
<dt><a href="#latestBreach">latestBreach([options])</a> ⇒ <code><a href="#breach--object">Promise.<Breach></a></code> | <code>Promise.<null></code></dt>
|
|
34
58
|
<dd><p>Fetches the most recently added breach.</p>
|
|
35
59
|
</dd>
|
|
36
60
|
<dt><a href="#pasteAccount">pasteAccount(email, [options])</a> ⇒ <code><a href="#paste--object">Promise.<Array.<Paste>></a></code> | <code>Promise.<null></code></dt>
|
|
37
61
|
<dd><p>Fetches paste data for a specific account (email address).</p>
|
|
38
|
-
<p
|
|
39
|
-
<a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
62
|
+
<p>Requires a Core, Pro, or High RPM API key from
|
|
63
|
+
<a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code> option here is not
|
|
64
|
+
explicitly required, but direct requests made without it will fail (unless
|
|
65
|
+
you specify a <code>baseUrl</code> to a proxy that inserts a valid API key on your
|
|
66
|
+
behalf).</p>
|
|
43
67
|
</dd>
|
|
44
68
|
<dt><a href="#pwnedPasswordRange">pwnedPasswordRange(prefix, [options])</a> ⇒ <code><a href="#PwnedPasswordSuffixes">Promise.<PwnedPasswordSuffixes></a></code></dt>
|
|
45
69
|
<dd><p>Fetches the SHA-1 or NTLM hash suffixes for the given 5-character hash
|
|
@@ -63,61 +87,78 @@ provided account is not a valid email address, only breach data is queried
|
|
|
63
87
|
and the "pastes" field of the resulting object will always be null. This is
|
|
64
88
|
exactly how searching via the current web interface behaves, which this
|
|
65
89
|
convenience method is designed to mimic.</p>
|
|
66
|
-
<p
|
|
67
|
-
|
|
68
|
-
<
|
|
69
|
-
|
|
70
|
-
|
|
90
|
+
<p>Breaches contain only <code>Name</code> by default; pass <code>truncate: false</code> for full
|
|
91
|
+
breaches.</p>
|
|
92
|
+
<p>Requires a Core, Pro, or High RPM API key from
|
|
93
|
+
<a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code> option here is not
|
|
94
|
+
explicitly required, but direct requests made without it will fail (unless
|
|
95
|
+
you specify a <code>baseUrl</code> to a proxy that inserts a valid API key on your
|
|
96
|
+
behalf).</p>
|
|
97
|
+
</dd>
|
|
98
|
+
<dt><a href="#sendEmail">sendEmail(domain, emailAlias, [options])</a> ⇒ <code>Promise.<void></code></dt>
|
|
99
|
+
<dd><p>Requests a domain verification approval email.</p>
|
|
100
|
+
<p>Follow the link sent to the chosen alias at the domain to complete
|
|
101
|
+
verification.</p>
|
|
102
|
+
<p>Requires a Pro API key from <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code>
|
|
103
|
+
option here is not explicitly required, but direct requests made without it
|
|
104
|
+
will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts a valid API
|
|
105
|
+
key on your behalf).</p>
|
|
71
106
|
</dd>
|
|
72
107
|
<dt><a href="#stealerLogsByEmailDomain">stealerLogsByEmailDomain(emailDomain, [options])</a> ⇒ <code><a href="#StealerLogDomainsByEmailAlias">Promise.<StealerLogDomainsByEmailAlias></a></code> | <code>Promise.<null></code></dt>
|
|
73
108
|
<dd><p>Fetches all stealer log email aliases for an email domain.</p>
|
|
74
109
|
<p>The result maps email aliases (the local-part before the '@') to an array of
|
|
75
|
-
|
|
110
|
+
website domains found in stealer logs. For example, querying <code>example.com</code>
|
|
76
111
|
could return an object like <code>{ "andy": ["netflix.com"], "jane": ["netflix.com", "spotify.com"] }</code>, corresponding to <code>andy@example.com</code> and <code>jane@example.com</code>.</p>
|
|
77
|
-
<p
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
a valid API key on your behalf).</p>
|
|
112
|
+
<p>Requires a Pro API key from <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code>
|
|
113
|
+
option here is not explicitly required, but direct requests made without it
|
|
114
|
+
will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts a valid API
|
|
115
|
+
key on your behalf).</p>
|
|
82
116
|
</dd>
|
|
83
117
|
<dt><a href="#stealerLogsByEmail">stealerLogsByEmail(emailAddress, [options])</a> ⇒ <code>Promise.<Array.<string>></code> | <code>Promise.<null></code></dt>
|
|
84
118
|
<dd><p>Fetches all stealer log domains for an email address.</p>
|
|
85
119
|
<p>Returns an array of domains for which stealer logs contain entries for the
|
|
86
120
|
supplied email address.</p>
|
|
87
|
-
<p
|
|
88
|
-
|
|
89
|
-
<code>
|
|
90
|
-
|
|
91
|
-
a valid API key on your behalf).</p>
|
|
121
|
+
<p>Requires a Pro API key from <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code>
|
|
122
|
+
option here is not explicitly required, but direct requests made without it
|
|
123
|
+
will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts a valid API
|
|
124
|
+
key on your behalf).</p>
|
|
92
125
|
</dd>
|
|
93
126
|
<dt><a href="#stealerLogsByWebsiteDomain">stealerLogsByWebsiteDomain(websiteDomain, [options])</a> ⇒ <code>Promise.<Array.<string>></code> | <code>Promise.<null></code></dt>
|
|
94
127
|
<dd><p>Fetches all stealer log email addresses for a website domain.</p>
|
|
95
128
|
<p>The result is an array of strings representing email addresses found in
|
|
96
129
|
stealer logs for the specified website domain (e.g., "example.com").</p>
|
|
97
|
-
<p
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
that inserts a valid API key on your behalf).</p>
|
|
130
|
+
<p>Requires a Pro API key from <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code>
|
|
131
|
+
option here is not explicitly required, but direct requests made without it
|
|
132
|
+
will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts a valid API
|
|
133
|
+
key on your behalf).</p>
|
|
102
134
|
</dd>
|
|
103
135
|
<dt><a href="#subscribedDomains">subscribedDomains([options])</a> ⇒ <code><a href="#subscribeddomain--object">Promise.<Array.<SubscribedDomain>></a></code></dt>
|
|
104
136
|
<dd><p>Fetches all subscribed domains for your HIBP account.</p>
|
|
105
137
|
<p>Returns domains that have been successfully added to the Domain Search dashboard
|
|
106
138
|
after verifying control. Each domain includes metadata about breach counts and
|
|
107
139
|
the next renewal date, where available.</p>
|
|
108
|
-
<p
|
|
109
|
-
<a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a> for the <code>subscribeddomains</code> endpoint. The
|
|
140
|
+
<p>Requires a Core or Pro API key from <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The
|
|
110
141
|
<code>apiKey</code> option here is not explicitly required, but direct requests made
|
|
111
142
|
without it will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts
|
|
112
143
|
a valid API key on your behalf).</p>
|
|
113
144
|
</dd>
|
|
114
145
|
<dt><a href="#subscriptionStatus">subscriptionStatus([options])</a> ⇒ <code><a href="#subscriptionstatus--object">Promise.<SubscriptionStatus></a></code></dt>
|
|
115
146
|
<dd><p>Fetches the current status of your HIBP subscription (API key).</p>
|
|
116
|
-
<p
|
|
117
|
-
<a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
147
|
+
<p>Requires a Core, Pro, or High RPM API key from
|
|
148
|
+
<a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code> option here is not
|
|
149
|
+
explicitly required, but direct requests made without it will fail (unless
|
|
150
|
+
you specify a <code>baseUrl</code> to a proxy that inserts a valid API key on your
|
|
151
|
+
behalf).</p>
|
|
152
|
+
</dd>
|
|
153
|
+
<dt><a href="#verifyDnsToken">verifyDnsToken(domain, [options])</a> ⇒ <code>Promise.<void></code></dt>
|
|
154
|
+
<dd><p>Verifies a domain's published HIBP TXT record.</p>
|
|
155
|
+
<p>Generate the value with <code>generateDnsToken</code>, publish it at your DNS provider,
|
|
156
|
+
and allow time for DNS propagation first. The record can be removed after
|
|
157
|
+
verification succeeds.</p>
|
|
158
|
+
<p>Requires a Pro API key from <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code>
|
|
159
|
+
option here is not explicitly required, but direct requests made without it
|
|
160
|
+
will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts a valid API
|
|
161
|
+
key on your behalf).</p>
|
|
121
162
|
</dd>
|
|
122
163
|
</dl>
|
|
123
164
|
|
|
@@ -126,11 +167,23 @@ a valid API key on your behalf).</p>
|
|
|
126
167
|
<dl>
|
|
127
168
|
<dt><a href="#breach--object">Breach</a> : <code>object</code></dt>
|
|
128
169
|
<dd><p>An object representing a breach.</p>
|
|
170
|
+
<p><code>Attribution</code> and <code>DisclosureUrl</code> may be null. See the
|
|
171
|
+
<a href="https://haveibeenpwned.com/API/v3#BreachModel">breach model</a> and the
|
|
172
|
+
<a href="https://haveibeenpwned.com/api/v3/breaches">breach catalogue</a>.</p>
|
|
173
|
+
</dd>
|
|
174
|
+
<dt><a href="#BreachedAccountRangeResult">BreachedAccountRangeResult</a> : <code>Object</code></dt>
|
|
175
|
+
<dd><p>A breached email hash suffix and the breach names associated with it.</p>
|
|
129
176
|
</dd>
|
|
130
|
-
<dt><a href="#
|
|
177
|
+
<dt><a href="#BreachedDomainsByEmailAlias">BreachedDomainsByEmailAlias</a> : <code>Object.<string, Array.<string>></code></dt>
|
|
131
178
|
<dd><p>An object mapping an email alias (local-part before the '@') to the list of
|
|
132
179
|
breach names that alias has appeared in for the specified domain.</p>
|
|
133
180
|
</dd>
|
|
181
|
+
<dt><a href="#dataclassdescription--object">DataClassDescription</a> : <code>object</code></dt>
|
|
182
|
+
<dd><p>A data class name and its description.</p>
|
|
183
|
+
</dd>
|
|
184
|
+
<dt><a href="#DnsToken">DnsToken</a> : <code>object</code></dt>
|
|
185
|
+
<dd><p>The TXT record value to publish at your DNS provider.</p>
|
|
186
|
+
</dd>
|
|
134
187
|
<dt><a href="#Paste">Paste</a> : <code>object</code></dt>
|
|
135
188
|
<dd><p>An object representing a paste.</p>
|
|
136
189
|
</dd>
|
|
@@ -141,10 +194,13 @@ hash prefix) to how many times it occurred in the Pwned Passwords repository.</p
|
|
|
141
194
|
<dt><a href="#SearchResults">SearchResults</a> : <code>object</code></dt>
|
|
142
195
|
<dd><p>An object representing search results.</p>
|
|
143
196
|
</dd>
|
|
197
|
+
<dt><a href="#EmailAlias">EmailAlias</a> : <code>"admin"</code> | <code>"hostmaster"</code> | <code>"info"</code> | <code>"security"</code> | <code>"webmaster"</code></dt>
|
|
198
|
+
<dd><p>An administrative alias supported for domain verification emails.</p>
|
|
199
|
+
</dd>
|
|
144
200
|
<dt><a href="#StealerLogDomainsByEmailAlias">StealerLogDomainsByEmailAlias</a> : <code>Object.<string, Array.<string>></code></dt>
|
|
145
201
|
<dd><p>An object mapping an email alias (local-part before the '@') to the list of
|
|
146
|
-
|
|
147
|
-
email domain.</p>
|
|
202
|
+
website domains that alias has appeared against in stealer logs for the
|
|
203
|
+
specified email domain.</p>
|
|
148
204
|
</dd>
|
|
149
205
|
<dt><a href="#SubscribedDomain">SubscribedDomain</a> : <code>object</code></dt>
|
|
150
206
|
<dd><p>An object representing a subscribed domain.</p>
|
|
@@ -186,21 +242,67 @@ try {
|
|
|
186
242
|
// ...
|
|
187
243
|
}
|
|
188
244
|
```
|
|
245
|
+
<a name="breachedAccountRange"></a>
|
|
246
|
+
|
|
247
|
+
## breachedAccountRange(prefix, [options]) ⇒ <code><a href="#breachedaccountrangeresult--object">Promise.<Array.<BreachedAccountRangeResult>></a></code> \| <code>Promise.<null></code>
|
|
248
|
+
Fetches breached email hash suffixes for a six-character SHA-1 email hash
|
|
249
|
+
prefix.
|
|
250
|
+
|
|
251
|
+
Requires a Pro or High RPM API key from https://haveibeenpwned.com/API/Key.
|
|
252
|
+
The `apiKey` option here is not explicitly required, but direct requests made
|
|
253
|
+
without it will fail (unless you specify a `baseUrl` to a proxy that inserts
|
|
254
|
+
a valid API key on your behalf).
|
|
255
|
+
|
|
256
|
+
Compare suffixes locally against the intended email hash. Per the
|
|
257
|
+
haveibeenpwned.com terms of use, discard unrelated results immediately
|
|
258
|
+
without storing or further processing them.
|
|
259
|
+
|
|
260
|
+
**Kind**: global function
|
|
261
|
+
**Returns**: <code><a href="#breachedaccountrangeresult--object">Promise.<Array.<BreachedAccountRangeResult>></a></code> \| <code>Promise.<null></code> - a Promise
|
|
262
|
+
which resolves to an array of range results (or null if none were found), or
|
|
263
|
+
rejects with an Error
|
|
264
|
+
**See**: https://haveibeenpwned.com/API/v3#BreachesForHashRange
|
|
265
|
+
|
|
266
|
+
| Param | Type | Description |
|
|
267
|
+
| --- | --- | --- |
|
|
268
|
+
| prefix | <code>string</code> | the first six characters of a SHA-1 email hash (case-insensitive) |
|
|
269
|
+
| [options] | <code>object</code> | a configuration object |
|
|
270
|
+
| [options.apiKey] | <code>string</code> | an API key from https://haveibeenpwned.com/API/Key (default: undefined) |
|
|
271
|
+
| [options.baseUrl] | <code>string</code> | a custom base URL for the haveibeenpwned.com API endpoints (default: `https://haveibeenpwned.com/api/v3`) |
|
|
272
|
+
| [options.timeoutMs] | <code>number</code> | timeout for the request in milliseconds (default: none) |
|
|
273
|
+
| [options.signal] | <code>AbortSignal</code> | an AbortSignal to cancel the request (default: none) |
|
|
274
|
+
| [options.userAgent] | <code>string</code> | a custom string to send as the User-Agent field in the request headers (default: `hibp <version>`) |
|
|
275
|
+
|
|
276
|
+
**Example**
|
|
277
|
+
```js
|
|
278
|
+
try {
|
|
279
|
+
const data = await breachedAccountRange("6B5917", { apiKey: "my-api-key" });
|
|
280
|
+
const match = data?.find(
|
|
281
|
+
({ hashSuffix }) => hashSuffix === "C6C0AADE0C085843D66E4944E108C4A4CD",
|
|
282
|
+
);
|
|
283
|
+
// match?.websites: ["Adobe", "Gawker", "Stratfor"] in the documented example
|
|
284
|
+
} catch (err) {
|
|
285
|
+
// ...
|
|
286
|
+
}
|
|
287
|
+
```
|
|
189
288
|
<a name="breachedAccount"></a>
|
|
190
289
|
|
|
191
290
|
## breachedAccount(account, [options]) ⇒ <code><a href="#breach--object">Promise.<Array.<Breach>></a></code> \| <code>Promise.<null></code>
|
|
192
291
|
Fetches breach data for a specific account.
|
|
193
292
|
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
293
|
+
Results contain only `Name` by default; pass `truncate: false` for full
|
|
294
|
+
breaches.
|
|
295
|
+
|
|
296
|
+
Requires a Core, Pro, or High RPM API key from
|
|
297
|
+
https://haveibeenpwned.com/API/Key. The `apiKey` option here is not
|
|
298
|
+
explicitly required, but direct requests made without it will fail (unless
|
|
299
|
+
you specify a `baseUrl` to a proxy that inserts a valid API key on your
|
|
300
|
+
behalf).
|
|
199
301
|
|
|
200
302
|
**Kind**: global function
|
|
201
|
-
**Returns**: <code><a href="#breach--object">Promise.<Array.<Breach>></a></code> \| <code>Promise.<null></code> - a Promise which
|
|
202
|
-
|
|
203
|
-
an Error
|
|
303
|
+
**Returns**: <code><a href="#breach--object">Promise.<Array.<Breach>></a></code> \| <code>Promise.<null></code> - a Promise which
|
|
304
|
+
resolves to name-only breaches by default, full breaches with
|
|
305
|
+
`truncate: false`, or null if no breaches were found; rejects with an Error
|
|
204
306
|
|
|
205
307
|
| Param | Type | Description |
|
|
206
308
|
| --- | --- | --- |
|
|
@@ -264,7 +366,7 @@ try {
|
|
|
264
366
|
```
|
|
265
367
|
<a name="breachedDomain"></a>
|
|
266
368
|
|
|
267
|
-
## breachedDomain(domain, [options]) ⇒ [<code>Promise.<BreachedDomainsByEmailAlias></code>](#
|
|
369
|
+
## breachedDomain(domain, [options]) ⇒ [<code>Promise.<BreachedDomainsByEmailAlias></code>](#BreachedDomainsByEmailAlias) \| <code>Promise.<null></code>
|
|
268
370
|
Fetches all breached email addresses for a domain.
|
|
269
371
|
|
|
270
372
|
The result maps email aliases (the local-part before the '@') to an array of
|
|
@@ -272,14 +374,13 @@ breach names. For example, querying `example.com` could return an object like
|
|
|
272
374
|
`{ "john": ["Adobe"], "jane": ["Adobe", "Gawker"] }`, corresponding to
|
|
273
375
|
`john@example.com` and `jane@example.com`.
|
|
274
376
|
|
|
275
|
-
|
|
276
|
-
https://haveibeenpwned.com/API/Key for the `breacheddomain` endpoint. The
|
|
377
|
+
Requires a Core or Pro API key from https://haveibeenpwned.com/API/Key. The
|
|
277
378
|
`apiKey` option here is not explicitly required, but direct requests made
|
|
278
379
|
without it will fail (unless you specify a `baseUrl` to a proxy that inserts
|
|
279
380
|
a valid API key on your behalf).
|
|
280
381
|
|
|
281
382
|
**Kind**: global function
|
|
282
|
-
**Returns**: [<code>Promise.<BreachedDomainsByEmailAlias></code>](#
|
|
383
|
+
**Returns**: [<code>Promise.<BreachedDomainsByEmailAlias></code>](#BreachedDomainsByEmailAlias) \| <code>Promise.<null></code> - a Promise which
|
|
283
384
|
resolves to an object mapping aliases to breach name arrays (or null if no
|
|
284
385
|
results were found), or rejects with an Error
|
|
285
386
|
|
|
@@ -319,6 +420,7 @@ objects (an empty array if no breaches were found), or rejects with an Error
|
|
|
319
420
|
| --- | --- | --- |
|
|
320
421
|
| [options] | <code>object</code> | a configuration object |
|
|
321
422
|
| [options.domain] | <code>string</code> | a domain by which to filter the results (default: all domains) |
|
|
423
|
+
| [options.isSpamList] | <code>boolean</code> | true for only spam-list breaches, false for only non-spam-list breaches (default: no spam-list filter) |
|
|
322
424
|
| [options.baseUrl] | <code>string</code> | a custom base URL for the haveibeenpwned.com API endpoints (default: `https://haveibeenpwned.com/api/v3`) |
|
|
323
425
|
| [options.timeoutMs] | <code>number</code> | timeout for the request in milliseconds (default: none) |
|
|
324
426
|
| [options.signal] | <code>AbortSignal</code> | an AbortSignal to cancel the request (default: none) |
|
|
@@ -340,7 +442,38 @@ try {
|
|
|
340
442
|
**Example**
|
|
341
443
|
```js
|
|
342
444
|
try {
|
|
343
|
-
const data = await breaches({ domain: "adobe.com" });
|
|
445
|
+
const data = await breaches({ domain: "adobe.com", isSpamList: false });
|
|
446
|
+
if (data) {
|
|
447
|
+
// ...
|
|
448
|
+
} else {
|
|
449
|
+
// ...
|
|
450
|
+
}
|
|
451
|
+
} catch (err) {
|
|
452
|
+
// ...
|
|
453
|
+
}
|
|
454
|
+
```
|
|
455
|
+
<a name="dataClassDescriptions"></a>
|
|
456
|
+
|
|
457
|
+
## dataClassDescriptions([options]) ⇒ <code><a href="#dataclassdescription--object">Promise.<Array.<DataClassDescription>></a></code> \| <code>Promise.<null></code>
|
|
458
|
+
Fetches all data class names and descriptions.
|
|
459
|
+
|
|
460
|
+
**Kind**: global function
|
|
461
|
+
**Returns**: <code><a href="#dataclassdescription--object">Promise.<Array.<DataClassDescription>></a></code> \| <code>Promise.<null></code> - a Promise which
|
|
462
|
+
resolves to an array of data class objects (or null if no data classes were
|
|
463
|
+
found), or rejects with an Error
|
|
464
|
+
|
|
465
|
+
| Param | Type | Description |
|
|
466
|
+
| --- | --- | --- |
|
|
467
|
+
| [options] | <code>object</code> | a configuration object |
|
|
468
|
+
| [options.baseUrl] | <code>string</code> | a custom base URL for the haveibeenpwned.com API endpoints (default: `https://haveibeenpwned.com/api/v3`) |
|
|
469
|
+
| [options.timeoutMs] | <code>number</code> | timeout for the request in milliseconds (default: none) |
|
|
470
|
+
| [options.signal] | <code>AbortSignal</code> | an AbortSignal to cancel the request (default: none) |
|
|
471
|
+
| [options.userAgent] | <code>string</code> | a custom string to send as the User-Agent field in the request headers (default: `hibp <version>`) |
|
|
472
|
+
|
|
473
|
+
**Example**
|
|
474
|
+
```js
|
|
475
|
+
try {
|
|
476
|
+
const data = await dataClassDescriptions();
|
|
344
477
|
if (data) {
|
|
345
478
|
// ...
|
|
346
479
|
} else {
|
|
@@ -381,6 +514,45 @@ try {
|
|
|
381
514
|
// ...
|
|
382
515
|
}
|
|
383
516
|
```
|
|
517
|
+
<a name="generateDnsToken"></a>
|
|
518
|
+
|
|
519
|
+
## generateDnsToken(domain, [options]) ⇒ [<code>Promise.<DnsToken></code>](#DnsToken)
|
|
520
|
+
Generates a domain-specific DNS verification token.
|
|
521
|
+
|
|
522
|
+
Publish `txtRecordValue` as a TXT record on the domain, then call
|
|
523
|
+
`verifyDnsToken` after DNS propagation.
|
|
524
|
+
|
|
525
|
+
Requires a Pro API key from https://haveibeenpwned.com/API/Key. The `apiKey`
|
|
526
|
+
option here is not explicitly required, but direct requests made without it
|
|
527
|
+
will fail (unless you specify a `baseUrl` to a proxy that inserts a valid API
|
|
528
|
+
key on your behalf).
|
|
529
|
+
|
|
530
|
+
**Kind**: global function
|
|
531
|
+
**Returns**: [<code>Promise.<DnsToken></code>](#DnsToken) - a Promise which resolves to the TXT record
|
|
532
|
+
value, or rejects with an Error containing the upstream failure reason
|
|
533
|
+
**See**: https://haveibeenpwned.com/API/v3#VerifyDomainViaDns
|
|
534
|
+
|
|
535
|
+
| Param | Type | Description |
|
|
536
|
+
| --- | --- | --- |
|
|
537
|
+
| domain | <code>string</code> | the domain to verify (e.g., "example.com") |
|
|
538
|
+
| [options] | <code>object</code> | a configuration object |
|
|
539
|
+
| [options.apiKey] | <code>string</code> | an API key from https://haveibeenpwned.com/API/Key (default: undefined) |
|
|
540
|
+
| [options.baseUrl] | <code>string</code> | a custom base URL for the haveibeenpwned.com API endpoints (default: `https://haveibeenpwned.com/api/v3`) |
|
|
541
|
+
| [options.timeoutMs] | <code>number</code> | timeout for the request in milliseconds (default: none) |
|
|
542
|
+
| [options.signal] | <code>AbortSignal</code> | an AbortSignal to cancel the request (default: none) |
|
|
543
|
+
| [options.userAgent] | <code>string</code> | a custom string to send as the User-Agent field in the request headers (default: `hibp <version>`) |
|
|
544
|
+
|
|
545
|
+
**Example**
|
|
546
|
+
```js
|
|
547
|
+
try {
|
|
548
|
+
const { txtRecordValue } = await generateDnsToken("example.com", {
|
|
549
|
+
apiKey: "my-api-key",
|
|
550
|
+
});
|
|
551
|
+
// Publish txtRecordValue as a TXT record on example.com.
|
|
552
|
+
} catch (err) {
|
|
553
|
+
// ...
|
|
554
|
+
}
|
|
555
|
+
```
|
|
384
556
|
<a name="latestBreach"></a>
|
|
385
557
|
|
|
386
558
|
## latestBreach([options]) ⇒ [<code>Promise.<Breach></code>](#breach--object) \| <code>Promise.<null></code>
|
|
@@ -417,11 +589,11 @@ try {
|
|
|
417
589
|
## pasteAccount(email, [options]) ⇒ <code><a href="#paste--object">Promise.<Array.<Paste>></a></code> \| <code>Promise.<null></code>
|
|
418
590
|
Fetches paste data for a specific account (email address).
|
|
419
591
|
|
|
420
|
-
|
|
421
|
-
https://haveibeenpwned.com/API/Key
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
592
|
+
Requires a Core, Pro, or High RPM API key from
|
|
593
|
+
https://haveibeenpwned.com/API/Key. The `apiKey` option here is not
|
|
594
|
+
explicitly required, but direct requests made without it will fail (unless
|
|
595
|
+
you specify a `baseUrl` to a proxy that inserts a valid API key on your
|
|
596
|
+
behalf).
|
|
425
597
|
|
|
426
598
|
**Kind**: global function
|
|
427
599
|
**Returns**: <code><a href="#paste--object">Promise.<Array.<Paste>></a></code> \| <code>Promise.<null></code> - a Promise which resolves to an
|
|
@@ -567,11 +739,14 @@ and the "pastes" field of the resulting object will always be null. This is
|
|
|
567
739
|
exactly how searching via the current web interface behaves, which this
|
|
568
740
|
convenience method is designed to mimic.
|
|
569
741
|
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
`
|
|
742
|
+
Breaches contain only `Name` by default; pass `truncate: false` for full
|
|
743
|
+
breaches.
|
|
744
|
+
|
|
745
|
+
Requires a Core, Pro, or High RPM API key from
|
|
746
|
+
https://haveibeenpwned.com/API/Key. The `apiKey` option here is not
|
|
747
|
+
explicitly required, but direct requests made without it will fail (unless
|
|
748
|
+
you specify a `baseUrl` to a proxy that inserts a valid API key on your
|
|
749
|
+
behalf).
|
|
575
750
|
|
|
576
751
|
**Kind**: global function
|
|
577
752
|
**Returns**: [<code>Promise.<SearchResults></code>](#SearchResults) - a Promise which resolves to an object
|
|
@@ -621,21 +796,61 @@ try {
|
|
|
621
796
|
// ...
|
|
622
797
|
}
|
|
623
798
|
```
|
|
799
|
+
<a name="sendEmail"></a>
|
|
800
|
+
|
|
801
|
+
## sendEmail(domain, emailAlias, [options]) ⇒ <code>Promise.<void></code>
|
|
802
|
+
Requests a domain verification approval email.
|
|
803
|
+
|
|
804
|
+
Follow the link sent to the chosen alias at the domain to complete
|
|
805
|
+
verification.
|
|
806
|
+
|
|
807
|
+
Requires a Pro API key from https://haveibeenpwned.com/API/Key. The `apiKey`
|
|
808
|
+
option here is not explicitly required, but direct requests made without it
|
|
809
|
+
will fail (unless you specify a `baseUrl` to a proxy that inserts a valid API
|
|
810
|
+
key on your behalf).
|
|
811
|
+
|
|
812
|
+
**Kind**: global function
|
|
813
|
+
**Returns**: <code>Promise.<void></code> - a Promise which resolves without parsing the
|
|
814
|
+
response body when the approval email request succeeds, or rejects with an
|
|
815
|
+
Error containing the upstream failure reason
|
|
816
|
+
**See**: https://haveibeenpwned.com/API/v3#VerifyDomainViaEmail
|
|
817
|
+
|
|
818
|
+
| Param | Type | Description |
|
|
819
|
+
| --- | --- | --- |
|
|
820
|
+
| domain | <code>string</code> | the domain to verify (e.g., "example.com") |
|
|
821
|
+
| emailAlias | [<code>EmailAlias</code>](#EmailAlias) | the administrative alias to receive the email |
|
|
822
|
+
| [options] | <code>object</code> | a configuration object |
|
|
823
|
+
| [options.apiKey] | <code>string</code> | an API key from https://haveibeenpwned.com/API/Key (default: undefined) |
|
|
824
|
+
| [options.baseUrl] | <code>string</code> | a custom base URL for the haveibeenpwned.com API endpoints (default: `https://haveibeenpwned.com/api/v3`) |
|
|
825
|
+
| [options.timeoutMs] | <code>number</code> | timeout for the request in milliseconds (default: none) |
|
|
826
|
+
| [options.signal] | <code>AbortSignal</code> | an AbortSignal to cancel the request (default: none) |
|
|
827
|
+
| [options.userAgent] | <code>string</code> | a custom string to send as the User-Agent field in the request headers (default: `hibp <version>`) |
|
|
828
|
+
|
|
829
|
+
**Example**
|
|
830
|
+
```js
|
|
831
|
+
try {
|
|
832
|
+
await sendEmail("example.com", "security", {
|
|
833
|
+
apiKey: "my-api-key",
|
|
834
|
+
});
|
|
835
|
+
// Follow the link in the email sent to security@example.com.
|
|
836
|
+
} catch (err) {
|
|
837
|
+
// ...
|
|
838
|
+
}
|
|
839
|
+
```
|
|
624
840
|
<a name="stealerLogsByEmailDomain"></a>
|
|
625
841
|
|
|
626
842
|
## stealerLogsByEmailDomain(emailDomain, [options]) ⇒ [<code>Promise.<StealerLogDomainsByEmailAlias></code>](#StealerLogDomainsByEmailAlias) \| <code>Promise.<null></code>
|
|
627
843
|
Fetches all stealer log email aliases for an email domain.
|
|
628
844
|
|
|
629
845
|
The result maps email aliases (the local-part before the '@') to an array of
|
|
630
|
-
|
|
846
|
+
website domains found in stealer logs. For example, querying `example.com`
|
|
631
847
|
could return an object like `{ "andy": ["netflix.com"], "jane": ["netflix.com",
|
|
632
848
|
"spotify.com"] }`, corresponding to `andy@example.com` and `jane@example.com`.
|
|
633
849
|
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
a valid API key on your behalf).
|
|
850
|
+
Requires a Pro API key from https://haveibeenpwned.com/API/Key. The `apiKey`
|
|
851
|
+
option here is not explicitly required, but direct requests made without it
|
|
852
|
+
will fail (unless you specify a `baseUrl` to a proxy that inserts a valid API
|
|
853
|
+
key on your behalf).
|
|
639
854
|
|
|
640
855
|
**Kind**: global function
|
|
641
856
|
**Returns**: [<code>Promise.<StealerLogDomainsByEmailAlias></code>](#StealerLogDomainsByEmailAlias) \| <code>Promise.<null></code> - a Promise
|
|
@@ -673,11 +888,10 @@ Fetches all stealer log domains for an email address.
|
|
|
673
888
|
Returns an array of domains for which stealer logs contain entries for the
|
|
674
889
|
supplied email address.
|
|
675
890
|
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
`
|
|
679
|
-
|
|
680
|
-
a valid API key on your behalf).
|
|
891
|
+
Requires a Pro API key from https://haveibeenpwned.com/API/Key. The `apiKey`
|
|
892
|
+
option here is not explicitly required, but direct requests made without it
|
|
893
|
+
will fail (unless you specify a `baseUrl` to a proxy that inserts a valid API
|
|
894
|
+
key on your behalf).
|
|
681
895
|
|
|
682
896
|
**Kind**: global function
|
|
683
897
|
**Returns**: <code>Promise.<Array.<string>></code> \| <code>Promise.<null></code> - a Promise which resolves to an
|
|
@@ -730,11 +944,10 @@ Fetches all stealer log email addresses for a website domain.
|
|
|
730
944
|
The result is an array of strings representing email addresses found in
|
|
731
945
|
stealer logs for the specified website domain (e.g., "example.com").
|
|
732
946
|
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
that inserts a valid API key on your behalf).
|
|
947
|
+
Requires a Pro API key from https://haveibeenpwned.com/API/Key. The `apiKey`
|
|
948
|
+
option here is not explicitly required, but direct requests made without it
|
|
949
|
+
will fail (unless you specify a `baseUrl` to a proxy that inserts a valid API
|
|
950
|
+
key on your behalf).
|
|
738
951
|
|
|
739
952
|
**Kind**: global function
|
|
740
953
|
**Returns**: <code>Promise.<Array.<string>></code> \| <code>Promise.<null></code> - a Promise which resolves to an
|
|
@@ -788,8 +1001,7 @@ Returns domains that have been successfully added to the Domain Search dashboard
|
|
|
788
1001
|
after verifying control. Each domain includes metadata about breach counts and
|
|
789
1002
|
the next renewal date, where available.
|
|
790
1003
|
|
|
791
|
-
|
|
792
|
-
https://haveibeenpwned.com/API/Key for the `subscribeddomains` endpoint. The
|
|
1004
|
+
Requires a Core or Pro API key from https://haveibeenpwned.com/API/Key. The
|
|
793
1005
|
`apiKey` option here is not explicitly required, but direct requests made
|
|
794
1006
|
without it will fail (unless you specify a `baseUrl` to a proxy that inserts
|
|
795
1007
|
a valid API key on your behalf).
|
|
@@ -832,11 +1044,11 @@ try {
|
|
|
832
1044
|
## subscriptionStatus([options]) ⇒ [<code>Promise.<SubscriptionStatus></code>](#subscriptionstatus--object)
|
|
833
1045
|
Fetches the current status of your HIBP subscription (API key).
|
|
834
1046
|
|
|
835
|
-
|
|
836
|
-
https://haveibeenpwned.com/API/Key
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
|
|
1047
|
+
Requires a Core, Pro, or High RPM API key from
|
|
1048
|
+
https://haveibeenpwned.com/API/Key. The `apiKey` option here is not
|
|
1049
|
+
explicitly required, but direct requests made without it will fail (unless
|
|
1050
|
+
you specify a `baseUrl` to a proxy that inserts a valid API key on your
|
|
1051
|
+
behalf).
|
|
840
1052
|
|
|
841
1053
|
**Kind**: global function
|
|
842
1054
|
**Returns**: [<code>Promise.<SubscriptionStatus></code>](#subscriptionstatus--object) - a Promise which resolves to a
|
|
@@ -871,33 +1083,92 @@ try {
|
|
|
871
1083
|
// ...
|
|
872
1084
|
}
|
|
873
1085
|
```
|
|
1086
|
+
<a name="verifyDnsToken"></a>
|
|
1087
|
+
|
|
1088
|
+
## verifyDnsToken(domain, [options]) ⇒ <code>Promise.<void></code>
|
|
1089
|
+
Verifies a domain's published HIBP TXT record.
|
|
1090
|
+
|
|
1091
|
+
Generate the value with `generateDnsToken`, publish it at your DNS provider,
|
|
1092
|
+
and allow time for DNS propagation first. The record can be removed after
|
|
1093
|
+
verification succeeds.
|
|
1094
|
+
|
|
1095
|
+
Requires a Pro API key from https://haveibeenpwned.com/API/Key. The `apiKey`
|
|
1096
|
+
option here is not explicitly required, but direct requests made without it
|
|
1097
|
+
will fail (unless you specify a `baseUrl` to a proxy that inserts a valid API
|
|
1098
|
+
key on your behalf).
|
|
1099
|
+
|
|
1100
|
+
**Kind**: global function
|
|
1101
|
+
**Returns**: <code>Promise.<void></code> - a Promise which resolves without parsing the
|
|
1102
|
+
response body when verification succeeds, or rejects with an Error
|
|
1103
|
+
containing the upstream failure reason
|
|
1104
|
+
**See**: https://haveibeenpwned.com/API/v3#VerifyDomainViaDns
|
|
1105
|
+
|
|
1106
|
+
| Param | Type | Description |
|
|
1107
|
+
| --- | --- | --- |
|
|
1108
|
+
| domain | <code>string</code> | the domain to verify (e.g., "example.com") |
|
|
1109
|
+
| [options] | <code>object</code> | a configuration object |
|
|
1110
|
+
| [options.apiKey] | <code>string</code> | an API key from https://haveibeenpwned.com/API/Key (default: undefined) |
|
|
1111
|
+
| [options.baseUrl] | <code>string</code> | a custom base URL for the haveibeenpwned.com API endpoints (default: `https://haveibeenpwned.com/api/v3`) |
|
|
1112
|
+
| [options.timeoutMs] | <code>number</code> | timeout for the request in milliseconds (default: none) |
|
|
1113
|
+
| [options.signal] | <code>AbortSignal</code> | an AbortSignal to cancel the request (default: none) |
|
|
1114
|
+
| [options.userAgent] | <code>string</code> | a custom string to send as the User-Agent field in the request headers (default: `hibp <version>`) |
|
|
1115
|
+
|
|
1116
|
+
**Example**
|
|
1117
|
+
```js
|
|
1118
|
+
try {
|
|
1119
|
+
await verifyDnsToken("example.com", { apiKey: "my-api-key" });
|
|
1120
|
+
// ...
|
|
1121
|
+
} catch (err) {
|
|
1122
|
+
// ...
|
|
1123
|
+
}
|
|
1124
|
+
```
|
|
874
1125
|
<a name="Breach"></a>
|
|
875
1126
|
|
|
876
1127
|
## Breach : <code>object</code>
|
|
877
1128
|
An object representing a breach.
|
|
878
1129
|
|
|
1130
|
+
`Attribution` and `DisclosureUrl` may be null. See the
|
|
1131
|
+
[breach model](https://haveibeenpwned.com/API/v3#BreachModel) and the
|
|
1132
|
+
[breach catalogue](https://haveibeenpwned.com/api/v3/breaches).
|
|
1133
|
+
|
|
879
1134
|
**Kind**: global typedef
|
|
880
1135
|
**Properties**
|
|
881
1136
|
|
|
882
|
-
| Name | Type |
|
|
883
|
-
| --- | --- |
|
|
884
|
-
| Name | <code>string</code> |
|
|
885
|
-
| Title | <code>string</code> |
|
|
886
|
-
| Domain | <code>string</code> |
|
|
887
|
-
| BreachDate | <code>string</code> |
|
|
888
|
-
| AddedDate | <code>string</code> |
|
|
889
|
-
| ModifiedDate | <code>string</code> |
|
|
890
|
-
| PwnCount | <code>number</code> |
|
|
891
|
-
| Description | <code>string</code> |
|
|
892
|
-
| DataClasses | <code>Array.<string></code> |
|
|
893
|
-
| IsVerified | <code>boolean</code> |
|
|
894
|
-
| IsFabricated | <code>boolean</code> |
|
|
895
|
-
| IsSensitive | <code>boolean</code> |
|
|
896
|
-
| IsRetired | <code>boolean</code> |
|
|
897
|
-
| IsSpamList | <code>boolean</code> |
|
|
898
|
-
| IsMalware | <code>boolean</code> |
|
|
899
|
-
|
|
|
900
|
-
|
|
|
1137
|
+
| Name | Type | Description |
|
|
1138
|
+
| --- | --- | --- |
|
|
1139
|
+
| Name | <code>string</code> | |
|
|
1140
|
+
| Title | <code>string</code> | |
|
|
1141
|
+
| Domain | <code>string</code> | |
|
|
1142
|
+
| BreachDate | <code>string</code> | |
|
|
1143
|
+
| AddedDate | <code>string</code> | |
|
|
1144
|
+
| ModifiedDate | <code>string</code> | |
|
|
1145
|
+
| PwnCount | <code>number</code> | |
|
|
1146
|
+
| Description | <code>string</code> | |
|
|
1147
|
+
| DataClasses | <code>Array.<string></code> | |
|
|
1148
|
+
| IsVerified | <code>boolean</code> | |
|
|
1149
|
+
| IsFabricated | <code>boolean</code> | |
|
|
1150
|
+
| IsSensitive | <code>boolean</code> | |
|
|
1151
|
+
| IsRetired | <code>boolean</code> | |
|
|
1152
|
+
| IsSpamList | <code>boolean</code> | |
|
|
1153
|
+
| IsMalware | <code>boolean</code> | |
|
|
1154
|
+
| IsStealerLog | <code>boolean</code> | whether the breach is sourced from stealer logs |
|
|
1155
|
+
| IsSubscriptionFree | <code>boolean</code> | |
|
|
1156
|
+
| LogoPath | <code>string</code> | |
|
|
1157
|
+
| Attribution | <code>string</code> \| <code>null</code> | credit requested by the data provider, or null |
|
|
1158
|
+
| DisclosureUrl | <code>string</code> \| <code>null</code> | breach disclosure URL, or null |
|
|
1159
|
+
|
|
1160
|
+
<a name="BreachedAccountRangeResult"></a>
|
|
1161
|
+
|
|
1162
|
+
## BreachedAccountRangeResult : <code>Object</code>
|
|
1163
|
+
A breached email hash suffix and the breach names associated with it.
|
|
1164
|
+
|
|
1165
|
+
**Kind**: global typedef
|
|
1166
|
+
**Properties**
|
|
1167
|
+
|
|
1168
|
+
| Name | Type | Description |
|
|
1169
|
+
| --- | --- | --- |
|
|
1170
|
+
| hashSuffix | <code>string</code> | the remaining 34 characters of a SHA-1 email hash |
|
|
1171
|
+
| websites | <code>Array.<string></code> | breach names, not website domains or URLs |
|
|
901
1172
|
|
|
902
1173
|
<a name="BreachedDomainsByEmailAlias"></a>
|
|
903
1174
|
|
|
@@ -906,6 +1177,31 @@ An object mapping an email alias (local-part before the '@') to the list of
|
|
|
906
1177
|
breach names that alias has appeared in for the specified domain.
|
|
907
1178
|
|
|
908
1179
|
**Kind**: global typedef
|
|
1180
|
+
<a name="DataClassDescription"></a>
|
|
1181
|
+
|
|
1182
|
+
## DataClassDescription : <code>object</code>
|
|
1183
|
+
A data class name and its description.
|
|
1184
|
+
|
|
1185
|
+
**Kind**: global typedef
|
|
1186
|
+
**Properties**
|
|
1187
|
+
|
|
1188
|
+
| Name | Type | Description |
|
|
1189
|
+
| --- | --- | --- |
|
|
1190
|
+
| name | <code>string</code> | the data class name |
|
|
1191
|
+
| description | <code>string</code> | a description of the compromised data |
|
|
1192
|
+
|
|
1193
|
+
<a name="DnsToken"></a>
|
|
1194
|
+
|
|
1195
|
+
## DnsToken : <code>object</code>
|
|
1196
|
+
The TXT record value to publish at your DNS provider.
|
|
1197
|
+
|
|
1198
|
+
**Kind**: global typedef
|
|
1199
|
+
**Properties**
|
|
1200
|
+
|
|
1201
|
+
| Name | Type | Description |
|
|
1202
|
+
| --- | --- | --- |
|
|
1203
|
+
| txtRecordValue | <code>string</code> | the complete TXT record value |
|
|
1204
|
+
|
|
909
1205
|
<a name="Paste"></a>
|
|
910
1206
|
|
|
911
1207
|
## Paste : <code>object</code>
|
|
@@ -914,13 +1210,13 @@ An object representing a paste.
|
|
|
914
1210
|
**Kind**: global typedef
|
|
915
1211
|
**Properties**
|
|
916
1212
|
|
|
917
|
-
| Name | Type |
|
|
918
|
-
| --- | --- |
|
|
919
|
-
| Id | <code>string</code> |
|
|
920
|
-
| Source | <code>string</code> |
|
|
921
|
-
| Title | <code>string</code> |
|
|
922
|
-
| Date | <code>string</code> |
|
|
923
|
-
| EmailCount | <code>number</code> |
|
|
1213
|
+
| Name | Type | Description |
|
|
1214
|
+
| --- | --- | --- |
|
|
1215
|
+
| Id | <code>string</code> | |
|
|
1216
|
+
| Source | <code>string</code> | |
|
|
1217
|
+
| [Title] | <code>string</code> | omitted when the source has no title |
|
|
1218
|
+
| Date | <code>string</code> \| <code>null</code> | null when the source has no posting date |
|
|
1219
|
+
| EmailCount | <code>number</code> | |
|
|
924
1220
|
|
|
925
1221
|
<a name="PwnedPasswordSuffixes"></a>
|
|
926
1222
|
|
|
@@ -942,12 +1238,18 @@ An object representing search results.
|
|
|
942
1238
|
| breaches | [<code>Array.<Breach></code>](#breach--object) \| <code>null</code> |
|
|
943
1239
|
| pastes | [<code>Array.<Paste></code>](#Paste) \| <code>null</code> |
|
|
944
1240
|
|
|
1241
|
+
<a name="EmailAlias"></a>
|
|
1242
|
+
|
|
1243
|
+
## EmailAlias : <code>"admin"</code> \| <code>"hostmaster"</code> \| <code>"info"</code> \| <code>"security"</code> \| <code>"webmaster"</code>
|
|
1244
|
+
An administrative alias supported for domain verification emails.
|
|
1245
|
+
|
|
1246
|
+
**Kind**: global typedef
|
|
945
1247
|
<a name="StealerLogDomainsByEmailAlias"></a>
|
|
946
1248
|
|
|
947
1249
|
## StealerLogDomainsByEmailAlias : <code>Object.<string, Array.<string>></code>
|
|
948
1250
|
An object mapping an email alias (local-part before the '@') to the list of
|
|
949
|
-
|
|
950
|
-
email domain.
|
|
1251
|
+
website domains that alias has appeared against in stealer logs for the
|
|
1252
|
+
specified email domain.
|
|
951
1253
|
|
|
952
1254
|
**Kind**: global typedef
|
|
953
1255
|
<a name="SubscribedDomain"></a>
|
|
@@ -974,12 +1276,17 @@ An object representing the status of your HIBP subscription.
|
|
|
974
1276
|
**Kind**: global typedef
|
|
975
1277
|
**Properties**
|
|
976
1278
|
|
|
977
|
-
| Name | Type |
|
|
978
|
-
| --- | --- |
|
|
979
|
-
| SubscriptionName | <code>string</code> |
|
|
980
|
-
| Description | <code>string</code> |
|
|
981
|
-
| SubscribedUntil | <code>string</code> |
|
|
982
|
-
| Rpm | <code>number</code> |
|
|
983
|
-
| DomainSearchMaxBreachedAccounts | <code>number</code> |
|
|
984
|
-
|
|
|
1279
|
+
| Name | Type | Description |
|
|
1280
|
+
| --- | --- | --- |
|
|
1281
|
+
| SubscriptionName | <code>string</code> | |
|
|
1282
|
+
| Description | <code>string</code> | |
|
|
1283
|
+
| SubscribedUntil | <code>string</code> | |
|
|
1284
|
+
| Rpm | <code>number</code> | |
|
|
1285
|
+
| DomainSearchMaxBreachedAccounts | <code>number</code> | |
|
|
1286
|
+
| MaxBreachedDomains | <code>number</code> \| <code>null</code> | maximum domains that can be added; null means no limit |
|
|
1287
|
+
| IncludesStealerLogs | <code>boolean</code> | |
|
|
1288
|
+
| IncludesBulkDomainAdd | <code>boolean</code> | access to APIs for adding domains in bulk |
|
|
1289
|
+
| IncludesAutoSubdomainVerification | <code>boolean</code> | automatic verification of subdomains of a verified apex domain |
|
|
1290
|
+
| IncludesCustomerDomains | <code>boolean</code> | permission to add customer domains |
|
|
1291
|
+
| IncludesKAnon | <code>boolean</code> | access to email address searches using k-anonymity |
|
|
985
1292
|
|