\n\n# Riposte\n\n**On-premise email sync service - Cloud-API alternative**\n\nRiposte provides a unified API for multiple email providers (Gmail, Microsoft, future IMAP) with 90% cost savings compared to Cloud-APIs. All data stays on your infrastructure.\n\n## π Quick Start\n\n```bash\n# Scaffold your configuration (riposte/sync.config.json + riposte/.env.example)\nnpx riposte-init\n\n# Launch the daemon with the admin portal\nnpx riposte-run\n\n# Skip the admin portal\nnpx riposte-run --no-admin\n```\n\nThat's it! Your email sync service is running at:\n\n- **API Server**: http://localhost:8080\n- **Admin Portal**: Auto-selected port printed on startup (for example http://localhost:3001)\n\n## Installation at a glance\n\nRiposte follows a three-step flow so you always know what comes next:\n\n1. **Initialize** β Run `npx riposte-init` to auto-detect local services, scaffold `riposte/sync.config.json`/`.env.example`, and hand off deeper customization to the admin onboarding wizard.\n2. **Launch** β Start the runtime with `npx riposte-run` and watch the structured logs confirm database, queue, and migration health.\n3. **Admin** β Visit the onboarding flow at the admin portal URL shown after startup. It now behaves like a linear checklist: choose Google or Microsoft first, paste credentials with the exact scopes we flag, wire databases/queues, and (optionally) authorize a pilot account before copying the API call examples into your app.\n\nEach stage is documented in the [installation guide](docs/INSTALLATION.md), which expands on prerequisites, troubleshooting tips, and day-two operations once you are live.\n\n## π¦ Installation Options\n\n### What ships in the npm tarball?\n\nRunning `npm publish --dry-run` (or `npm pack`) lists every file that would be\nincluded in the release. You will see a number of entries under\n`admin-dist/.next/standalone/node_modules/β¦`. Those files come from the\nNext.js \"standalone\" build that powers the bundled admin portal. They are not a\ncopy of your development `node_modules`; instead they are the trimmed runtime\ndependencies that Next.js inlines alongside `server.js` so the `riposte-admin`\nCLI can boot without relying on an external installation. The build script\nalready deletes caches and other transient output, so the additional files are\nexpected and safe to publish.\n\n### Option 1: Global Installation (Recommended)\n\n```bash\nnpm install -g @riposte.co/server\nriposte-init\nriposte-run\n```\n\n### Option 2: Local Installation\n\n```bash\nnpm install @riposte.co/server\nnpx riposte-init\nnpx riposte-run\n```\n\n### Option 3: Development Setup\n\n```bash\ngit clone \ncd riposte\nnpm install\nnpm run setup\nnpm start\n```\n\n## βοΈ Configuration\n\n### Quick Start (SQLite + In-Memory)\n\n- **Database**: SQLite file (`./riposte.db`)\n- **Cache**: In-memory\n- **Queues**: In-memory\n- **Perfect for**: Trying out, development, small deployments\n\n### Production Setup (PostgreSQL + Redis)\n\n- **Database**: PostgreSQL\n- **Cache**: Redis\n- **Queues**: Redis\n- **Perfect for**: Production, horizontal scaling\n\n### Database Configuration & Migrations\n\n- Set `DATABASE_URL` (or `TEST_DATABASE_URL`) to `file:./path/to.db` or any `sqlite:` URL to run with SQLite.\n- Set the same variable to a PostgreSQL connection string (for example `postgresql://user:pass@localhost:5432/riposte`) to run with Postgres.\n- The service automatically creates SQLite database files when using `file:` URLs.\n- Generate a new migration with `npm run db:generate `. The command compares the current schema to your\n target database and writes the SQL files under `drizzle/sqlite` or `drizzle/postgres` as appropriate.\n- Run migrations with `npm run db:migrate`. The script picks the correct migration directory (`drizzle/sqlite` or `drizzle/postgres`) based on the active provider.\n- Generated migrations live under `drizzle/sqlite` or `drizzle/postgres` depending on the dialect selected when running `drizzle-kit`.\n- Riposte now auto-applies pending migrations during startup. Set `AUTO_APPLY_MIGRATIONS=false` (or\n `riposte.migrations.autoApply` to `false` in `sync.config.json`) if you prefer to run the migration script\n manually.\n\n### Authentication screen\n\nRiposte now ships with a built-in authentication screen that runs alongside your deployment at `/auth/authorize`. The product creates short-lived sessions and returns links that you can hand to end usersβno external services required. The screen detects the correct provider based on the email address, renders a consent experience, and drives the entire PKCE exchange on the server.\n\nTerminology to avoid confusion:\n- Provider callback URI: The OAuth callback URL registered with Google or Microsoft that Riposte listens on to receive the authorization code (e.g., `http://localhost:8080/providers/gmail/callback`). Configure this under `riposte.oauth..redirectUri` or the matching environment variable.\n- App redirect URL: The user-facing URL in your product where the browser should land after Riposte finishes authentication (e.g., `https://app.example.com/connect/success`). Configure this under `riposte.app.redirectUrl` or pass it when creating an auth session.\n\nOnce the provider completes the handshake, Riposte exchanges the code for tokens, associates the account with the originating session, and redirects the browser to your app redirect URL.\n\nCustomize the experience under `riposte.authScreen` inside `riposte/sync.config.json`. All of the values live in source control so you can review branding changes just like any other configuration update:\n\n```jsonc\n{\n \"riposte\": {\n \"authScreen\": {\n \"enabled\": true,\n \"publicUrl\": \"https://mail.example.com\",\n \"brandName\": \"Acme Support\",\n \"logoText\": \"AS\",\n \"title\": \"Connect your email\",\n \"subtitle\": \"We will securely connect your inbox for {{brand}}.\",\n \"supportEmail\": \"support@example.com\",\n \"submitButtonLabel\": \"Continue\",\n \"customCssFile\": \"./branding/auth-screen.css\",\n \"cors\": {\n \"origin\": \"*\",\n },\n },\n },\n}\n```\n\nPoint `customCssFile` at a stylesheet to control colors, fonts, or layout. The file is reloaded whenever it changes so you can iterate quickly in development. When `enabled` is set to `false` the server returns `503` for new session requests to make it clear that the experience has been turned off.\n\nBy default the screen is accessible from any origin. Set `riposte.authScreen.cors.origin` to a specific origin (or list of origins) if you need to lock it down for production embeds.\n\n## π§ͺ Live provider smoke tests\n\nThe repository includes a Vitest suite that exercises real providers end-to-end. Enable it locally by setting `RUN_LIVE_PROVIDER_TESTS=true` and pointing the harness at one or more seeded accounts via either `PROVIDER_TEST_RUNS` (JSON array) or the simpler `PROVIDER_TEST_SENDER_ID`/`PROVIDER_TEST_RECIPIENT_IDS` flags described in `product/src/__tests__/integration/live-provider.integration.test.ts`.\n\nWhen calendar access is provisioned for the connected account the harness now validates basic calendar CRUD in addition to email send/receive. Specify `PROVIDER_TEST_CALENDAR_ID` to force the test to use a specific calendar; otherwise the first calendar returned by the provider will be used. Temporary events are deleted automatically even if an assertion fails.\n\n## π Licensing\n\nRiposte now enforces a license key for deployments that connect more than 100 accounts. Without a valid license the server will refuse new authorizations once 100 accounts are connected. A valid license lifts that limit (or applies a custom max if specified) and is verified with an Ed25519 signature at startup.\n\n### Configure license verification\n\nSet the following environment variable (typically inside `riposte/.env`):\n\n| Variable | Description |\n| --------------------- | -------------------------------------------- |\n| `RIPOSTE_LICENSE_KEY` | The signed license string issued by Riposte. |\n\nThe verifier ships with a baked-in Ed25519 public key (`product/src/common/license-authority.ts`). Riposte ignores runtime overrides unless the process runs under `NODE_ENV=test` so operators cannot self-issue licenses by swapping keys. Unit tests rely on that test-only escape hatch to inject ephemeral key pairs.\n\n> **Note:** If no valid license is configured the server logs a warning at startup and enforces the 100-account cap automatically.\n\n### Generate a signing key pair\n\nUse the bundled helper to create an Ed25519 key pair for signing licenses:\n\n```bash\nnpm run license -- keypair --output ./license-keys\n# or omit --output to print keys to the console only\n```\n\nThe command prints:\n\n- `riposte-license-private-key.pem` (PKCS8 private key for signing)\n- `riposte-license-public-key.pem` (SPKI public key)\n- Base64url versions of the public key for reference\n\nAfter generating a new pair, update `product/src/common/license-authority.ts` and `license/canonical-public-key.raw` with the printed base64url raw public key. Distribute the corresponding private key securely for license issuance; it should never be committed to git.\n\n### Sign a license key\n\nCreate licenses with custom expirations and limits using the same helper:\n\n```bash\nnpm run license -- sign \\\n --expires 2025-12-31 \\\n --max-accounts 1000 \\\n --name \"Acme Corp\" \\\n --id enterprise-2025 \\\n --private-key-path ./license-keys/riposte-license-private-key.pem\n```\n\nKey details:\n\n- `--expires` accepts ISO-8601 dates or relative durations such as `180d` or `2y`.\n- `--max-accounts` is optional; omit it for unlimited accounts on that license.\n- `--name` and `--id` embed metadata that appears in server logs when the license is loaded.\n- Provide the private key via `--private-key`, `--private-key-path`, or the environment variables `RIPOSTE_LICENSE_PRIVATE_KEY(_PATH)`.\n\nThe command prints the signed license payload and the final `RIPOSTE_LICENSE_KEY` value to distribute.\n\n## π Migration\n\nWhen you're ready to scale from SQLite to PostgreSQL:\n\n```bash\nriposte-migrate --to postgresql\n```\n\nThis will:\n\n1. Back up your SQLite data\n2. Update configuration to PostgreSQL\n3. Restart the service\n4. Validate the migration\n\n## ποΈ Architecture\n\n### Core Components\n\n- **API Server**: Fastify-based REST API (port 8080)\n- **Admin Portal**: Next.js web interface served from its own HTTP listener (auto-selected port, printed on startup)\n- **Database**: SQLite (dev) or PostgreSQL (prod)\n- **Cache/Queues**: In-memory (dev) or Redis (prod)\n\n### Supported Providers\n\n- **Gmail**: Full sync, labels, drafts, send\n- **Microsoft**: Full sync, folders, drafts, send\n- **IMAP**: Mailbox sync and raw message access (bring your own IMAP server)\n\n#### IMAP provider setup\n\nIMAP support is designed for legacy mailboxes that expose username/password or app-specific password credentials. Because IMAP\ndoes not provide OAuth, credentials are stored as provider tokens. To enable IMAP:\n\n1. Install the optional runtime dependencies in the environment where Riposte runs:\n\n ```bash\n npm install imapflow mailparser\n ```\n\n2. Create an account in the `ProviderAuthToken` table (via the admin UI or directly through the database) using a JSON payload in\n the `accessToken` field. Example:\n\n ```json\n {\n \"host\": \"imap.example.com\",\n \"port\": 993,\n \"secure\": true,\n \"username\": \"user@example.com\",\n \"password\": \"app-specific-password\",\n \"mailbox\": \"INBOX\"\n }\n ```\n\n Additional `tls` options (for example `{\"rejectUnauthorized\": false}`) can be provided if your server uses a self-signed\n certificate.\n\n3. Queue a historical sync or use the `/sync` endpoints to pull messages. IMAP support currently focuses on read-only\n synchronization and raw message retrieval. Sending, label management, and calendar/contacts are not yet implemented for IMAP\n accounts.\n\n### Key Features\n\n- **Real-time sync**: Push notifications + polling\n- **Rate limiting**: Global queue with provider limits\n- **Horizontal scaling**: Redis-based distributed system\n- **Data sovereignty**: Everything stays on-premise\n- **Cost savings**: 90% cheaper than Cloud-APIs\n\n## π Business Value\n\n### Cost Comparison\n\n- **Cloud-APIs**: $1.50 per connected account\n- **Riposte**: $99/month unlimited accounts\n- **Savings**: 90% cost reduction\n\n### Target Market\n\n- **SMBs**: Priced out of Cloud-APIs\n- **Enterprises**: Want cost savings + data control\n- **Agencies**: Managing multiple clients\n- **Developers**: Building CRMs, ATSs, etc.\n\n## π§ Development\n\n### Prerequisites\n\n- Node.js 18+\n- npm or yarn\n- PostgreSQL (for production)\n- Redis (for production)\n- [Optional] [`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3) when running against SQLite (install with `npm install better-sqlite3`)\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone \ncd riposte\n\n# Install dependencies\nnpm install\n\n# Set up development environment\nnpm run setup\n\n# Start development server\nnpm run dev\n```\n\n### Notifications\n\nEach provider can use either webhook deliveries or polling to detect mailbox changes. Configure the preference in the `notifications` section of your `sync.config.json` (or via the corresponding environment variables). Gmail defaults to webhooks, while Microsoft starts in polling mode so the integration works without hosting a public webhook endpoint. Switch Microsoft to webhooks by setting `notifications.providers.microsoft.mode` to `\"webhook\"` once you have a reachable HTTPS callback.\n\nThe built-in polling engine runs automatically for every provider configured with `mode: \"polling\"`. Tune its behaviour under `notifications.polling`:\n\n```jsonc\n{\n \"notifications\": {\n \"polling\": {\n \"intervalMs\": 60000, // How often Riposte polls each account\n \"batchSize\": 25, // Messages fetched per account during a cycle\n \"initialLookbackMs\": 900000, // Look back window for the very first poll (in ms)\n \"maxAccountsPerCycle\": 10, // Accounts processed per polling loop\n },\n },\n}\n```\n\nOverride the same values via environment variables:\n\n```\nNOTIFICATIONS_POLLING_INTERVAL_MS=60000\nNOTIFICATIONS_POLLING_BATCH_SIZE=25\nNOTIFICATIONS_POLLING_INITIAL_LOOKBACK_MS=900000\nNOTIFICATIONS_POLLING_MAX_ACCOUNTS=10\n```\n\nWhenever a new account connects we enqueue an immediate polling run so you receive `message.received` events without waiting for the next interval.\n\n### Building for Production\n\n```bash\n# Build everything\nnpm run build\n\n# Start production server\nnpm start\n```\n\n## π API Documentation\n\nOnce running, visit:\n\n- **Swagger UI**: http://localhost:8080/docs\n- **API Reference**: http://localhost:8080/documentation/json\n\n## π‘οΈ Security\n\n- **API Key Authentication**: All endpoints require API key\n- **Data Encryption**: Sensitive data encrypted at rest\n- **On-premise Only**: No external data sharing\n- **Token Management**: Secure OAuth token storage\n\n## π Monitoring\n\n- **Health Check**: `GET /healthz`\n- **Metrics**: Built-in performance monitoring\n- **Logs**: Structured logging with Pino\n- **Alerts**: Configurable error notifications\n\n## π€ Support\n\nFor support and questions:\n\n- **Documentation**: See `/docs` endpoint\n- **Issues**: Contact support team\n- **Updates**: `npm update riposte`\n\n## π License\n\nUNLICENSED - Proprietary software\n\n---\n\n**Riposte** - The Cloud-API alternative that saves you 90% on email integration costs.\n","readmeFilename":"README.md"}
![\"Riposte](\"assets/riposte-text.svg\")