Note: This SDK uses the free public API from XposedOrNot.com - a free service to check if your email has been compromised in data breaches. Visit the XposedOrNot website to learn more about the service and check your email manually.

Table of Contents

• Features
• Installation
• Quick Start
• API Reference
  • checkEmail
  • checkPassword
  • getBreaches
  • getBreachAnalytics
  • getDomainBreaches
• Plus API (API Key)
• Error Handling
• Rate Limits
• TypeScript Support
• Contributing
• License

Features

• Simple API - Easy-to-use methods for checking email breaches
• Password Check - k-anonymity password exposure check (your password never leaves your machine)
• Plus API Support - Detailed breach data and domain monitoring with an API key
• Full TypeScript Support - Complete type definitions included
• Detailed Analytics - Get breach details, risk scores, and metrics
• Error Handling - Custom error classes for different scenarios
• Configurable - Timeout, retries, and custom options
• Rate-Limit Friendly - Built-in 1 request/second spacing on the free API, plus automatic retries
• Secure - HTTPS enforced, input validation, no sensitive data logging

Installation

npm install xposedornot

yarn add xposedornot

pnpm add xposedornot

Requirements

• Node.js 18.0.0 or higher

Quick Start

import { XposedOrNot } from 'xposedornot';

const xon = new XposedOrNot();

// Check if an email has been breached
const result = await xon.checkEmail('[email protected]');

if (result.found) {
  console.log(`Email found in ${result.breaches.length} breaches:`);
  result.breaches.forEach(breach => console.log(`  - ${breach}`));
} else {
  console.log('Good news! Email not found in any known breaches.');
}

// Check if a password has been exposed (hashed locally, never transmitted)
const password = await xon.checkPassword('hunter2');
console.log(password.found ? `Exposed ${password.count} times!` : 'Not found in breaches.');

API Reference

Constructor

const xon = new XposedOrNot(config?: XposedOrNotConfig);

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | - | API key from console.xposedornot.com for Plus API access | | baseUrl | string | 'https://api.xposedornot.com' | API base URL | | timeout | number | 30000 | Request timeout in milliseconds | | retries | number | 3 | Number of retries after a failed request | | headers | Record<string, string> | {} | Custom headers for all requests |

Methods

checkEmail(email, options?)

Check if an email address has been exposed in any data breaches.

const result = await xon.checkEmail('[email protected]');

// Result type:
// {
//   email: string;
//   found: boolean;
//   breaches: string[];
// }

Options:

| Option | Type | Description | |--------|------|-------------| | includeDetails | boolean | Include detailed breach information (free API only) |

When the client is configured with an apiKey, this method automatically uses the Plus API and additionally populates result.details with rich per-breach objects (BreachInfo[]: breach date, exposed record count, password risk, and more).

checkPassword(password)

Check if a password has been exposed in data breaches, using k-anonymity.

SECURITY: Your password is NEVER sent over the network. It is hashed locally with Keccak-512 and only the first 10 characters of the hash are sent to the API, so your actual password never leaves your machine.

const result = await xon.checkPassword('hunter2');

// Result type:
// {
//   anon: string;                                  // hash prefix that was sent
//   found: boolean;
//   count: number;                                 // times seen in breaches
//   characteristics: {                             // null if not found
//     digits: number;
//     alphabets: number;
//     special: number;
//     length: number;
//   } | null;
// }

if (result.found) {
  console.log(`Exposed ${result.count} times - do not use this password!`);
}

getBreaches(options?)

Get a list of all known data breaches.

// Get all breaches
const breaches = await xon.getBreaches();

// Filter by domain
const adobeBreaches = await xon.getBreaches({ domain: 'adobe.com' });

// Get specific breach by ID
const linkedIn = await xon.getBreaches({ breachId: 'linkedin' });

Options:

| Option | Type | Description | |--------|------|-------------| | domain | string | Filter breaches by domain | | breachId | string | Get a specific breach by ID |

Returns: Array of Breach objects with properties:

• breachID - Unique identifier
• breachedDate - Date of the breach
• domain - Associated domain
• industry - Industry category
• exposedData - Types of data exposed
• exposedRecords - Number of records exposed
• verified - Whether the breach is verified
• And more...

getBreachAnalytics(email, options?)

Get detailed breach analytics for an email address.

const result = await xon.getBreachAnalytics('[email protected]');

if (result.found && result.analytics) {
  console.log('Exposed breaches:', result.analytics.ExposedBreaches);
  console.log('Breach summary:', result.analytics.BreachesSummary);
  console.log('Breach metrics:', result.analytics.BreachMetrics);
  console.log('Paste exposures:', result.analytics.ExposedPastes);
}

Options:

| Option | Type | Description | |--------|------|-------------| | token | string | Token for accessing sensitive data |

getDomainBreaches()

Get breach information for domains verified against your API key. Requires an apiKey with verified domains configured at console.xposedornot.com; throws AuthenticationError otherwise.

const xon = new XposedOrNot({ apiKey: process.env.XON_API_KEY });
const result = await xon.getDomainBreaches();

console.log(`Exposed records: ${result.breachesDetails.length}`);
for (const record of result.breachesDetails) {
  console.log(`  ${record.email} - ${record.breach}`);
}

// Also available: result.yearlyMetrics, result.domainSummary,
// result.breachSummary, result.top10Breaches, result.detailedBreachInfo

Plus API (API Key)

The free API works without any configuration. For detailed breach data, higher rate limits, and domain monitoring, get an API key at console.xposedornot.com and pass it to the client:

const xon = new XposedOrNot({ apiKey: process.env.XON_API_KEY });

// checkEmail now returns detailed breach info via the Plus API
const result = await xon.checkEmail('[email protected]');
result.details?.forEach(breach => {
  console.log(`${breach.breach_id}: ${breach.xposed_records} records (${breach.password_risk})`);
});

// Domain monitoring becomes available
const domains = await xon.getDomainBreaches();

Commercial plans are available at plus.xposedornot.com.

Error Handling

The library provides custom error classes for different scenarios:

import {
  XposedOrNot,
  XposedOrNotError,
  RateLimitError,
  ValidationError,
  NetworkError,
  TimeoutError,
} from 'xposedornot';

const xon = new XposedOrNot();

try {
  const result = await xon.checkEmail('invalid-email');
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Invalid input:', error.message);
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited. Retry after:', error.retryAfter);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  } else if (error instanceof TimeoutError) {
    console.error('Request timed out');
  } else if (error instanceof XposedOrNotError) {
    console.error('API error:', error.message, error.code);
  }
}

Error Types

| Error Class | Description | |-------------|-------------| | XposedOrNotError | Base error class | | ValidationError | Invalid input (e.g., malformed email) | | RateLimitError | API rate limit exceeded | | NotFoundError | Resource not found | | AuthenticationError | Authentication failed | | NetworkError | Network connectivity issues | | TimeoutError | Request timed out | | ServerError | Server error (5xx) | | ApiError | General API error |

Rate Limits

The free XposedOrNot API is limited to 1 request per second, plus hourly and daily limits. The client automatically spaces free-API requests at least one second apart and retries rate-limited requests with exponential backoff.

When an apiKey is configured, client-side spacing is disabled - Plus API tier-based limits are enforced server-side. For higher rate limits, commercial plans are available at plus.xposedornot.com.

TypeScript Support

This library is written in TypeScript and includes full type definitions:

import type {
  Breach,
  BreachInfo,
  CheckEmailResult,
  BreachAnalyticsResult,
  PasswordCheckResult,
  DomainBreachesResult,
  XposedOrNotConfig,
} from 'xposedornot';

CommonJS Usage

const { XposedOrNot } = require('xposedornot');

const xon = new XposedOrNot();

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/XposedOrNot/XposedOrNot-JS.git
cd XposedOrNot-JS

# Install dependencies
npm install

# Run tests
npm run test:run

# Build
npm run build

# Lint
npm run lint

Projects Using This

Using xposedornot in your project? Let us know!

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• API Status: XposedOrNot Status

Show Your Support

If you find this package useful, give it a ⭐ on GitHub!

License

MIT - see the LICENSE file for details.

Links

• XposedOrNot Website
• API Documentation
• npm Package
• GitHub Repository
• XposedOrNot API Repository