Metadata-Version: 2.4
Name: idverify
Version: 0.1.0
Summary: ID verification library — OCR, MRZ parsing, screenshot detection, and age gate for government IDs
Author-email: Maou <daddymaouu@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/daddymaou/idverify
Project-URL: Repository, https://github.com/daddymaou/idverify
Project-URL: Documentation, https://github.com/daddymaou/idverify#readme
Project-URL: Issues, https://github.com/daddymaou/idverify/issues
Keywords: id,verification,mrz,ocr,passport,drivers-license,identity
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pytesseract>=0.3.10
Requires-Dist: Pillow>=10.0.0
Requires-Dist: opencv-python>=4.8.0
Requires-Dist: mrz>=0.2.0
Requires-Dist: exifread>=3.0.0
Requires-Dist: numpy>=1.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# idverify

> ID verification library — OCR, MRZ parsing, screenshot detection, and age gate for government IDs.

Built by [ᗰᗩOᑌ](https://maou.name.ng) · [GitHub](https://github.com/daddymaou/idverify)

## Install

```bash
pip install idverify
```

## Usage

```python
from idverify import verify_id, check_age

with open('./passport.jpg', 'rb') as f:
    buffer = f.read()

# Full verification
result = verify_id(buffer)
print(result.status)                 # "valid" | "expired" | "invalid"
print(result.documentType)           # "passport" | "drivers_license" | ...
print(result.checksum)               # "passed" | "failed" | "not_applicable"
print(result.screenshotDetected)     # False

# Age gate only (no birthdate exposed)
age = check_age(buffer)
print(age.over18)  # True
print(age.over21)  # False
```

## API

### `verify_id(buffer: bytes) -> VerificationResult`

Accepts an image buffer (PNG, JPG, WebP). Returns:

| Field | Type | Description |
|---|---|---|
| `id` | `str` | Unique scan UUID |
| `documentType` | `str` | passport / drivers_license / national_id / unknown |
| `issuingCountry` | `str` | ISO country code |
| `expiryDate` | `str \| None` | YYYY-MM-DD |
| `status` | `str` | valid / expired / invalid |
| `checksum` | `str` | passed / failed / not_applicable |
| `screenshotDetected` | `bool` | EXIF-based detection |
| `confidence` | `int` | 0–100 |
| `over18` | `bool \| None` | None if DOB not found |
| `over21` | `bool \| None` | None if DOB not found |

### `check_age(buffer: bytes) -> AgeGateResult`

Returns `{ over18: bool, over21: bool }` without exposing the full birthdate.

## How it works

1. **Preprocessing** — OpenCV resizes, grayscales, normalizes, and sharpens the image
2. **OCR** — pytesseract extracts all text
3. **MRZ parsing** — looks for Machine Readable Zone lines, validates checksums with the `mrz` package
4. **Fallback extraction** — regex-based date and country parsing if no MRZ found
5. **Screenshot detection** — exifread checks for camera EXIF metadata (Make, Model)
6. **Age gate** — calculates age from DOB without returning the raw date

## Requirements

- Python 3.9+
- Tesseract OCR installed on your system

### Install Tesseract

| OS | Command |
|---|---|
| **macOS** | `brew install tesseract` |
| **Ubuntu/Debian** | `sudo apt-get install tesseract-ocr` |
| **Windows** | Download from [UB-Mannheim/tesseract](https://github.com/UB-Mannheim/tesseract/wiki) |

## License

MIT
