AliasForge Studio

A local desktop workstation for synthetic email datasets and authorized email QA. The original browser prototype is preserved in legacy/.

Open the application

• macOS Apple Silicon: open release/mac-arm64/AliasForge Studio.app.
• Windows x64: extract release/AliasForge Studio-1.0.0-win.zip, then open AliasForge Studio.exe.
• The builds are unsigned development distributions. Public distribution requires platform signing/notarization. Windows execution must be verified on a Windows machine.

The app starts its own local service. No terminal or separate server is needed for a packaged build.

Build from source

Use Node.js 22.13 or newer and npm.

npm ci
npm run build
npm start

Electron downloads its development runtime on first launch when needed. Internet access is needed to install dependencies, not to generate synthetic datasets.

npm run preview       # Browser preview at http://127.0.0.1:4317
npm run typecheck
npm run lint
npm test
npm run package:mac
npm run package:win

Set PORT to change the browser-preview port. Set ALIASFORGE_DATA_DIR to choose the preview data directory. Packaged desktop data lives in the OS application-data directory; development Electron uses .data/desktop/data, and browser preview uses .data/browser. Do not run multiple independent services against the same data directory.

Main workflows

1. New job: synthetic identities, custom patterns, verified-domain plus aliases, or CSV/TXT/JSON import.
2. Review configuration and start. Pause/resume uses atomic SQLite checkpoints. Interrupted jobs are recovered as PAUSED.
3. Search, filter, sort, favorite, inspect, revalidate or select records in the virtualized table. Pages contain up to 500 records.
4. Export all, filtered or selected records as CSV, JSON, TXT or HTML; export session timelines as JSON/HTML. Every export has a SHA-256 checksum.
5. Add DNS TXT ownership proofs in Secure Vault. Create a vault password to store TLS SMTP or Resend credentials. A connection test checks authentication; a record test sends one explicitly authorized message.
6. Options changes density and export defaults. Help contains searchable Bengali/English instructions. Configuration provides worker, batch, retry, retention and vault-lock settings.

Keyboard: Ctrl/Cmd+N new job, Ctrl/Cmd+K commands, Ctrl/Cmd+F dataset search, Ctrl/Cmd+E export, Ctrl/Cmd+, configuration, F1 Help, Escape close dialog.

Security and confidence

• Synthetic addresses use reserved domains. Real-domain generation requires an ownership TXT proof.
• Credentials use scrypt and AES-256-GCM, with an additional Electron OS-keychain envelope when available. Passwords and decrypted credentials are never returned to the renderer or stored in localStorage.
• Vault passwords cannot be recovered. Store yours securely. Keys are cleared on explicit lock, idle expiry or application exit.
• The HTTP API binds only to 127.0.0.1. It checks Host, Origin, same-site requests and an HttpOnly session cookie. Electron enables sandboxing and context isolation and disables Node integration and external window navigation.
• Syntax validity, MX availability and provider message acceptance are different statuses. None is claimed to establish inbox delivery.
• Provider tests re-check both sender and recipient DNS proofs, use a single message and enforce a cooldown. SMTP supports public IPv4 endpoints on TLS ports 465/587. API testing supports Resend.
• Local database records and exports are not encrypted. Credential secrets are encrypted. Protect the device and its backups appropriately.
• CSV formula-like cells receive a leading apostrophe. Choose JSON/TXT to preserve address text exactly.

Limits

• Up to 1,000,000 records per job; CSV/TXT imports up to 100 MB, JSON up to 20 MB. CSV/TXT are streamed; JSON is parsed within its size limit.
• Up to four workers, 100 unfinished jobs, and 500 jobs shown in history. DNS checks use bounded timeouts, cache and retry backoff.
• Revalidation and clipboard operations are limited to 1,000 records per operation. Use chunked export for large datasets.
• Common unquoted email syntax is supported. Local-part case is preserved; provider-specific mailbox equivalence is not treated as a duplicate.
• Consumer Gmail mailbox ownership and OAuth account linking are not implemented. Dot aliases cannot be used without an applicable ownership mechanism. Verified custom domains use plus aliases when supported by their provider.
• No bulk messaging, delivery receipts/webhooks, automatic inbox inspection, cloud sync or PDF export. HTML reports can be printed by the user's browser.
• Retention deletion is explicit: System Audit > Apply retention policy. Automatic persistence is always enabled; it is not a toggle that can disable checkpoints.
• Real SMTP/Resend credentials were not provided, so live provider authentication/sending could not be verified end-to-end. Tests never send an unsolicited email.

Code layout

• src/: React UI, six main screens, dialogs, bilingual Help and design tokens.
• shared/types.ts: typed data and configuration contracts.
• server/db.ts: SQLite WAL schema, migration version and indexes.
• server/worker.ts: deterministic generation, streaming import and atomic checkpoints.
• server/service.ts: job lifecycle, exports, provider authorization and maintenance.
• server/http.ts: loopback HTTP commands, streaming upload/download and SSE events.
• server/vault.ts: encrypted credential vault, password rotation and idle lock.
• desktop/main.mjs: Electron lifecycle, sandbox, native menu and keychain integration.
• tests/: integration, boundary, encryption, export and million-record scale tests.
• docs/ARCHITECTURE.md: initial audit and architecture.

API contracts

All API calls require the local session cookie issued with the renderer document. Mutating requests require the exact local Origin. JSON command bodies are capped at 1 MB; uploads use a separate streaming endpoint.

Endpoint	Behavior
GET /api/overview	Jobs, settings, real telemetry and desktop capability
GET /api/events	Server-sent data/telemetry events
POST /api/jobs	Validate configuration and persist a queued job
POST /api/jobs/:id/action	Pause, resume, cancel, rerun or delete
GET /api/jobs/:id/records	Indexed, filtered, sorted pages
POST /api/jobs/:id/record-action	Scoped favorite, delete, deduplication and revalidation
POST /api/upload?format=csv	Stream an import and return a server-generated ID
POST /api/exports	Stream a dataset/report file and return checksum metadata
GET /api/exports/:id/download	Download a generated file
POST /api/vault/unlock, /lock, /password	Vault lifecycle
POST /api/credentials, /api/credentials/:id/test	Encrypted connection storage and authorized testing
POST /api/domains, /api/domains/:id	Create and verify DNS ownership challenges
POST /api/settings, /api/maintenance	Validated preferences and confirmed maintenance

Errors use { "error": "Actionable message" }. Export creation responds only after the file is finished. Job progress and records are committed in the same database transaction.