auto_register

A sanitized, open-source starter for email-based account registration flows, OTP retrieval, OAuth/PKCE token exchange, token inventory management, and credential validation.

This repository is a best-practice refactor and documentation-first open-source extraction from a private automation project. It intentionally removes private infrastructure details, real credentials, and project-specific downstream integrations.

What this repo is

auto_register is a modular Python project for building registration pipelines that typically need:

• disposable or catch-all email addresses
• OTP polling from inbox providers
• browser-like HTTP requests
• OAuth + PKCE callback parsing and token exchange
• token file persistence
• inventory-driven replenishment
• periodic credential validation and cleanup

It is designed as a framework/starter repo, not as a hardcoded single-purpose script.

What was removed during sanitization

This public repo does not include:

• private mailbox credentials
• private domains
• private filesystem paths
• private downstream project names/locations
• private token archives
• personal server topology

Anything sensitive has been replaced with:

• environment variables
• generic placeholders
• example configs
• portable relative paths

Repository structure

auto_register/
├── README.md
├── requirements.txt
├── .gitignore
├── .env.example
├── domains.example.txt
├── ecosystem.config.example.js
├── docs/
│   ├── architecture.md
│   ├── flow-overview.md
│   ├── sanitization-notes.md
│   └── downstream-integration.md
├── src/
│   └── auto_register/
│       ├── __init__.py
│       ├── config.py
│       ├── models.py
│       ├── oauth.py
│       ├── storage.py
│       ├── utils.py
│       ├── providers/
│       │   ├── __init__.py
│       │   ├── base.py
│       │   ├── imap_provider.py
│       │   ├── mailtm_provider.py
│       │   └── mailgw_provider.py
│       ├── flows/
│       │   ├── __init__.py
│       │   ├── register_flow.py
│       │   └── validate_flow.py
│       └── cli/
│           ├── __init__.py
│           ├── register.py
│           └── validate.py
└── tests/
    └── test_config.py

Core ideas

1. Provider abstraction

Email backends are pluggable. The registration pipeline should not depend on a single inbox vendor.

2. Two-phase workflow

Registration and token acquisition are separated into two logical phases:

• Phase 1: create account
• Phase 2: new session / login / token exchange

This structure is cleaner architecturally and also makes the codebase easier to maintain and test.

3. Inventory-driven replenishment

Instead of endlessly creating credentials, the runner can maintain a healthy inventory size.

4. Validator as a separate service

Credential production and credential validation are independent concerns and should run separately.

Quick start

1. Clone

git clone git@github.com:leecaa/auto_register.git
cd auto_register

2. Create environment

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Configure

cp .env.example .env
cp domains.example.txt domains.txt

Edit .env with your own values.

4. Run register worker

PYTHONPATH=src python -m auto_register.cli.register --provider imap --once

5. Run validator

PYTHONPATH=src python -m auto_register.cli.validate --once

Environment variables

See .env.example for the full list.

Important ones:

• AUTO_REGISTER_AUTH_DIR
• AUTO_REGISTER_DOMAINS_FILE
• AUTO_REGISTER_IMAP_HOST
• AUTO_REGISTER_IMAP_PORT
• AUTO_REGISTER_IMAP_USER
• AUTO_REGISTER_IMAP_PASS
• AUTO_REGISTER_MAILTM_BASE
• AUTO_REGISTER_MAILGW_BASE
• AUTO_REGISTER_REQUEST_TIMEOUT

Design goals

• portable
• documented
• safe to publish
• easy to fork
• easy to swap providers
• easy to connect to a downstream credential consumer

Recommended next steps after forking

1. Replace example providers with your real providers.
2. Implement your own target registration flow in flows/register_flow.py.
3. Connect validation to your own downstream credential checker.
4. Add unit tests for provider behavior and callback parsing.
5. Set up PM2/systemd/Docker only after local testing passes.

Legal / policy note

This repository is provided as a general-purpose automation and architecture example. You are responsible for ensuring your use complies with the policies, terms, and laws applicable to your target systems.