dkimkit 0.0.0-stage → 0.7.0

package/docs/hosted-api.md

@@ -0,0 +1,192 @@
+# API reference
+
+A multi-tenant REST API for SaaS products whose customers send email from their own domains. Your backend registers a customer's domain. The API returns the DNS records to show that customer, or writes them through the customer's DNS provider. It then keeps checking until SendGrid verifies the domain, and calls your webhook when the status changes.
+
+```
+Your app ──POST /v1/domains──▶ API ──▶ SendGrid / Postmark / Mailgun / Amazon SES
+   ▲                            │
+   └──── signed webhooks ◀── worker ──▶ Cloudflare / Route 53 (tenant's DNS) + DNS polling
+```
+
+## Authentication and errors
+
+Send `Authorization: Bearer dk_live_…`. Each account is limited to 10 requests/second, with bursts up to 30. Over the limit you get `429` and a `Retry-After` header.
+
+Errors always have this shape:
+
+```json
+{ "error": { "type": "invalid_request", "message": "domain must be a valid domain name, like example.com.", "request_id": "…" } }
+```
+
+| Status | `type` | When |
+|---|---|---|
+| 400 | `invalid_request` | Validation failed. Unknown fields are rejected, so typos surface |
+| 401 | `unauthorized` | Missing or wrong API key |
+| 404 | `not_found` | Not found, or it belongs to another account |
+| 402 | `plan_limit_reached` | The account is at its `domain_limit`; the error includes `domain_limit` |
+| 409 | `conflict` | The domain is already registered; the error includes `existing_id` |
+| 429 | `rate_limited` | Slow down |
+| 502 | `provider_error` | The email provider, Cloudflare or AWS rejected the call; includes `provider`, `provider_status` and a `hint` |
+
+## Domains
+
+### `POST /v1/domains`
+
+```json
+{
+  "domain": "customer.com",
+  "tenant_id": "your-customer-id",
+  "metadata": { "plan": "pro" },
+  "subdomain": "em",
+  "sendgrid_subuser": "customer-sub",
+  "inbound": { "url": "https://api.yourapp.com/inbound", "hostname": "parse.customer.com", "spam_check": false, "send_raw": false },
+  "dns": { "provider": "cloudflare", "cloudflare_api_token": "…" },
+  "overwrite": false
+}
+```
+
+Only `domain` is required.
+- **`dns.provider`:** one of
+  - `manual` (default): you show the records to your customer.
+  - `cloudflare`: needs `cloudflare_api_token`.
+  - `route53`: needs `aws_access_key_id` and `aws_secret_access_key`. `aws_session_token` and `route53_hosted_zone_id` are optional.
+- **Credentials:** they are encrypted at rest and never returned. The API never falls back to the server's own credentials.
+- **`sendgrid_subuser`:** SendGrid accounts only: runs every SendGrid call for this domain as that subuser.
+- **`subdomain`:** the return-path / MAIL FROM label (SendGrid picks one by default, Postmark uses `pm-bounces`, Amazon SES `mail`; Mailgun doesn't use it).
+- **`inbound.hostname`:** defaults to `parse.<domain>`, except with Mailgun, which only receives on domains added to it, so the default is the domain itself (send from a subdomain such as `mg.customer.com`). Postmark receives one inbound domain per Postmark server. Amazon SES doesn't support inbound here yet.
+- **`overwrite`:** allows replacing existing CNAME/MX records that point elsewhere.
+
+The domain is created at the email provider during the request, so the `201` response already contains the records. Records may carry a `note`, for example advice to merge an SPF record into an existing one:
+
+```json
+{
+  "id": "dom_…", "object": "domain", "domain": "customer.com", "status": "pending",
+  "records": [
+    { "type": "CNAME", "name": "em1234.customer.com", "value": "u1234.wl.sendgrid.net", "purpose": "mail_cname", "status": "pending" },
+    { "type": "CNAME", "name": "s1._domainkey.customer.com", "value": "s1.domainkey.u1234.wl.sendgrid.net", "purpose": "dkim1", "status": "pending" },
+    { "type": "MX", "name": "parse.customer.com", "value": "mx.sendgrid.net", "priority": 10, "purpose": "inbound_mx", "status": "pending" }
+  ],
+  "dns": { "provider": "cloudflare", "credentials_set": true },
+  "validation": null, "conflicts": null, "last_error": null,
+  "next_check_at": "…", "verified_at": null, "expires_at": "…", "created_at": "…", "updated_at": "…"
+}
+```
+
+### Other endpoints
+
+| | |
+|---|---|
+| `GET /v1/domains?tenant_id=&status=&limit=&starting_after=` | Newest first. Responses carry `has_more` and `next_cursor` |
+| `GET /v1/domains/:id` | |
+| `PATCH /v1/domains/:id` | `tenant_id`, `metadata`, `inbound` (`null` removes it), `dns`, `overwrite`. Changes to DNS, inbound or overwrite restart checks |
+| `POST /v1/domains/:id/verify` | Check now. Also restarts a `failed` or `conflict` domain. Returns `202` |
+| `DELETE /v1/domains/:id?remote=true` | Remove the domain. With `remote=true`, also delete the domain and its inbound route at the email provider. Never deletes DNS records |
+| `GET /v1/domains/:id/events` | History of what happened to this domain |
+| `GET /v1/account`, `PATCH /v1/account` | `name`, `webhook_url`, `widget_origins`, and `email_provider` (credentials are write-only; see below) |
+| `GET /v1/usage?from=&to=&group_by=tenant` | Usage for billing; see [Usage and billing](#usage-and-billing) |
+| `POST /v1/account/rotate-api-key` | Returns a new key and invalidates the old one immediately |
+| `POST /v1/account/rotate-webhook-secret` | |
+| `PATCH /v1/account` `widget_origins` | Origins allowed to embed the widget |
+| `POST /v1/widget-sessions` | Mint a browser session for the [embeddable widget](widget.md): `{ domain_id }` or `{ tenant_id, … }` |
+
+### Email provider
+
+Each account uses one email provider. Set it, and its credentials, with `PATCH /v1/account`:
+
+```json
+{ "email_provider": { "provider": "postmark", "account_token": "…", "inbound_server_id": "123" } }
+```
+
+| `provider` | Fields |
+|---|---|
+| `sendgrid` | `api_key` (`sendgrid_api_key` at the top level also works) |
+| `postmark` | `account_token`; `inbound_server_id` to receive email |
+| `mailgun` | `api_key`, `region` (`us` or `eu`, default `us`) |
+| `ses` | `access_key_id`, `secret_access_key`, optional `session_token`, `region` |
+
+Fields you leave out keep their saved values, so you can rotate one key at a time. Credentials are encrypted and never returned; `GET /v1/account` shows `email_provider` and `email_credentials_set`. To switch provider, delete the account's domains first, since each domain lives at the provider that created it.
+
+### Lifecycle
+
+```
+pending ─▶ awaiting_dns ─▶ verifying ─▶ verified ──(daily re-check fails)──▶ awaiting_dns
+   │            │              │
+   └────────────┴──────────────┴──▶ conflict   (existing records point elsewhere; nothing written)
+                                └──▶ failed     (bad credentials, missing zone, or not verified within 72h)
+```
+
+- **Checking:** the worker checks at 30s, 1m, 2m, 5m, 10m, 15m, then every 30 minutes. Each check writes DNS if needed, looks for the records on the domain's authoritative nameservers, then asks SendGrid to validate.
+- **Verified domains:** these are re-checked every 24 hours.
+- **Credential and config problems:** these fail immediately with a hint in `last_error`. Network errors and 5xx responses are retried.
+- **Restarting:** fix the cause, then call `verify`, or `PATCH` the domain.
+
+## Usage and billing
+
+Usage is metered automatically. Each billable fact is stored once, under an id derived from what it is (for example `active_domain_day:dom_1:2026-10-25`). Recording it again, or several workers recording it at once, can't double-count. Usage rows keep a snapshot of the domain name and `tenant_id`, so deleting a domain doesn't erase its billing history.
+
+| Metric | Meaning |
+|---|---|
+| `active_domains` | Distinct domains that were verified on at least one day in the period. The usual number to bill on, like seats |
+| `active_domain_days` | The sum over days of verified domains, for prorated billing (e.g. bill `active_domain_days / days in month`) |
+| `domains_created` | Domains registered in the period |
+| `verifications` | Times a domain became verified, including after a lost verification |
+
+A domain counts as active on a day when it was verified at some point that day. That's recorded the moment it verifies, at each daily re-check, and by an hourly pass over all verified domains. Days are UTC.
+
+`GET /v1/usage` lets an account see its own usage. It defaults to the current month so far; `from`/`to` are inclusive `YYYY-MM-DD` dates, up to 366 days. Add `group_by=tenant` to break it down by your customers, which is useful if you pass the cost on to them:
+
+```json
+{
+  "object": "usage", "from": "2026-10-01", "to": "2026-10-25",
+  "active_domains": 3, "active_domain_days": 41, "domains_created": 4, "verifications": 3,
+  "current_domains": 4, "domain_limit": 25,
+  "by_tenant": [
+    { "tenant_id": "cus_a", "active_domains": 2, "active_domain_days": 30, "domains_created": 2, "verifications": 2 },
+    { "tenant_id": "cus_b", "active_domains": 1, "active_domain_days": 11, "domains_created": 2, "verifications": 1 }
+  ]
+}
+```
+
+Plans can cap how many domains an account has at once (the free plan allows 3). Over the cap, `POST /v1/domains` returns `402 plan_limit_reached` with an `upgrade_url`. In the widget, end users see a neutral "contact support" message instead.
+
+## Webhooks
+
+Set `webhook_url` on the account (it must be public `https`). Each event is POSTed as JSON with a snapshot of the domain:
+
+```json
+{ "id": "evt_…", "object": "event", "type": "domain.verified", "created_at": "…", "data": { "domain": { "id": "dom_…", "status": "verified", … } } }
+```
+
+**Event types:**
+- `domain.created`
+- `domain.dns_written`
+- `domain.verified`
+- `domain.verification_lost`
+- `domain.conflict`
+- `domain.failed` (with `data.reason`)
+- `domain.deleted`
+
+**Delivery:** a non-2xx response or a timeout (10s) is retried after 10s, 1m, 5m, 30m, 2h, 6h, 12h and 24h. Delivery is at least once and can arrive out of order. Deduplicate on `id` (also sent as `X-DKIMkit-Event-Id`), and trust `data.domain.updated_at` rather than arrival order.
+
+Verify each request with the raw body and the account's `webhook_secret`:
+
+```ts
+import { verifyWebhookSignature } from 'dkimkit';
+
+app.post('/webhooks/dkimkit', express.raw({ type: 'application/json' }), (req, res) => {
+  if (!verifyWebhookSignature(process.env.DKIMKIT_WEBHOOK_SECRET!, req.body.toString(), req.header('x-dkimkit-signature'))) {
+    return res.sendStatus(400);
+  }
+  const event = JSON.parse(req.body.toString());
+  // …
+  res.sendStatus(200);
+});
+```
+
+The signature header is `t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">`. Requests older than 5 minutes are rejected as replays.
+
+## Security notes
+
+- **Secrets at rest:** API keys are stored as SHA-256 hashes. Email provider credentials and DNS credentials are encrypted with AES-256-GCM using random IVs and authentication tags. None of them are ever returned by the API.
+- **Tenant isolation:** every query is scoped to the authenticated account, and other accounts' ids return `404`.
+- **Webhook targets:** URLs are checked when saved and again before every delivery. They must be https and must not resolve to loopback, private, link-local, CGNAT or multicast addresses. Redirects are not followed.

package/docs/library.md

@@ -0,0 +1,253 @@
+# Node.js library and CLI
+
+The `dkimkit` npm package runs the whole setup from your own code or terminal: it gets the records from your email provider, writes them to your DNS host, waits until they're live, has the provider verify the domain, and optionally sets up inbound email.
+
+It runs entirely on your machine with your own provider keys. It doesn't call {{APP_NAME}}'s servers, so there's no account, API key, plan or domain limit. Only your email and DNS providers' own rate limits apply. Want us to run it for you, with a dashboard, webhooks and an embeddable widget? Use the [hosted API](/docs/hosted-api) instead.
+
+| | Library and CLI | Hosted API |
+|---|---|---|
+| Runs | In your process | On {{APP_NAME}} |
+| Domains | No limit | Set by your plan |
+| Waits for DNS and verification | While your code runs | In the background, then sends a webhook |
+| Provider keys | Stay with you | Stored encrypted |
+| UI for your customers | Build your own | Embeddable widget |
+
+## Install
+
+```bash
+npm install dkimkit
+```
+
+Requires Node 20 or later. The package has no runtime dependencies and ships its own TypeScript types.
+
+## Quick start
+
+```ts
+import { setupDomain, createEmailProvider, createDnsProvider } from 'dkimkit';
+
+const email = createEmailProvider('sendgrid', { apiKey: process.env.SENDGRID_API_KEY });
+const dns = createDnsProvider('cloudflare', { cloudflareApiToken: process.env.CLOUDFLARE_API_TOKEN });
+
+const result = await setupDomain(email, dns, {
+  domain: 'example.com',
+  onEvent: (e) => console.log(e.type),
+});
+
+if (result.status === 'complete') console.log('example.com is authenticated');
+else console.log('Not finished yet:', result.status);
+```
+
+Every step is idempotent: existing provider domains and DNS records are reused. If a run ends with `dns-pending` or `validation-failed`, run it again later and it picks up where it stopped.
+
+## setupDomain(email, dns, options)
+
+Runs the full flow and resolves with a result once the domain is verified, or when it can't go further yet.
+
+1. **Domain.** Reuses the provider's existing authentication for the domain, or creates one.
+2. **Plan.** Compares the records the provider needs with what's already in DNS. Matching records are left alone. A record pointing somewhere else is a conflict, and nothing is written.
+3. **Apply.** Writes the new and changed records.
+4. **Propagation.** Polls the domain's authoritative nameservers until every record is visible.
+5. **Validation.** Asks the provider to verify, retrying because its resolvers can lag behind.
+6. **Inbound.** If you asked for it, registers the inbound webhook once the domain is verified.
+
+### Options
+
+| Option | Type | |
+|---|---|---|
+| `domain` | `string` | The domain to authenticate. Required |
+| `subdomain` | `string` | Return-path or MAIL FROM label. SendGrid picks one by default, Postmark uses `pm-bounces`, SES uses `mail`. Not used by Mailgun |
+| `inbound` | `{ hostname, url, spamCheck?, sendRaw? }` | Receive email at `hostname` and POST it to `url`. Not supported for Amazon SES |
+| `overwrite` | `boolean` | Replace CNAME and MX records that point elsewhere instead of stopping with a conflict |
+| `dryRun` | `boolean` | Plan only and write nothing to DNS. The provider may still create its domain entry, since that's the only way to get the records |
+| `confirm` | `(changes) => Promise<boolean>` | Called before writing DNS when there are changes. Return `false` to stop with status `aborted` |
+| `propagation` | `{ timeoutMs?, intervalMs?, lookup? }` | How long to wait for DNS. Defaults: 300000 ms, polling every 5000 ms |
+| `validation` | `{ attempts?, intervalMs? }` | Verification retries. Defaults: 6 attempts, 10000 ms apart |
+| `onEvent` | `(event) => void` | Progress, for logs or a live UI. See [Events](#events) |
+| `signal` | `AbortSignal` | Stops waiting and rejects with an `AbortError` |
+
+### Result
+
+```ts
+const result = await setupDomain(email, dns, { domain: 'example.com' });
+result.status;      // 'complete' | 'dns-pending' | 'validation-failed' | 'aborted' | 'dry-run'
+result.domain;      // { id, domain, valid, records, created }
+result.changes;     // the DNS plan: [{ record, action: 'create' | 'update' | 'noop' | 'conflict' }]
+result.pending;     // dns-pending: records that weren't visible before the timeout
+result.validation;  // the provider's last answer: { valid, results: [{ record, valid, reason? }] }
+result.inbound;     // 'created' | 'updated' | 'unchanged', when inbound was set up
+```
+
+| Status | Meaning |
+|---|---|
+| `complete` | Verified, and inbound set up if requested |
+| `dns-pending` | Records were written but aren't visible yet. Run again later |
+| `validation-failed` | Records are visible but the provider hasn't verified them yet. Run again later |
+| `aborted` | `confirm` returned `false`. Nothing was written |
+| `dry-run` | `dryRun` was set. `changes` shows what would be written |
+
+### Events
+
+`onEvent` is called as each step happens:
+
+| `type` | Fields |
+|---|---|
+| `domain` | `auth`: the provider's domain and the records it needs |
+| `plan` | `changes`: what will be created, updated, left alone, or conflicts |
+| `applied` | `changes`: what was written |
+| `propagation` | `pending`, `total`, `elapsedMs`, after each DNS check |
+| `validation` | `attempt`, `result`, after each verification attempt |
+| `inbound` | `hostname`, `url`, `action` |
+
+For example, to stream progress to your own UI per customer:
+
+```ts
+await setupDomain(email, dns, {
+  domain: tenant.domain,
+  inbound: { hostname: `parse.${tenant.domain}`, url: `https://app.example.com/inbound/${tenant.id}` },
+  onEvent: (e) => {
+    if (e.type === 'propagation') progress(tenant.id, `${e.total - e.pending.length} of ${e.total} records live`);
+    if (e.type === 'validation' && e.result.valid) progress(tenant.id, 'Verified');
+  },
+});
+```
+
+## checkStatus(email, domain, subdomain?)
+
+A read-only check that changes nothing. It finds the domain at the provider and asks it to re-validate:
+
+```ts
+import { checkStatus } from 'dkimkit';
+
+const { domain, validation } = await checkStatus(email, 'example.com');
+if (!domain) console.log('Not set up with this provider yet');
+else if (validation?.valid) console.log('Verified');
+else console.log('Not verified yet:', validation?.results.filter((r) => !r.valid));
+```
+
+## Email providers
+
+Create one with `createEmailProvider(name, credentials, options?)`:
+
+| Provider | Name | Credentials | Records |
+|---|---|---|---|
+| SendGrid | `sendgrid` | `apiKey`, with Sender Authentication and Inbound Parse access | 3 CNAMEs |
+| Postmark | `postmark` | `accountToken` (an account token, not a server token), and `inboundServerId` to receive email | DKIM TXT and Return-Path CNAME |
+| Mailgun | `mailgun` | `apiKey`, and `region`: `us` (default) or `eu` | SPF and DKIM TXT, tracking CNAME |
+| Amazon SES | `ses` | `accessKeyId`, `secretAccessKey`, optional `sessionToken`, and `region`, e.g. `us-east-1` | 3 DKIM CNAMEs, MAIL FROM MX and SPF |
+
+```ts
+const sendgrid = createEmailProvider('sendgrid', { apiKey }, { subuser: tenant.sendgridSubuser });
+const mailgun = createEmailProvider('mailgun', { apiKey, region: 'eu' });
+const ses = createEmailProvider('ses', { accessKeyId, secretAccessKey, region: 'us-east-1' });
+```
+
+The `subuser` option runs SendGrid calls on behalf of a subuser, which keeps each customer's domains in their own SendGrid subuser. Missing or invalid credentials throw a `ConfigError` before any request is made.
+
+Each provider also has its own class (`SendGridProvider`, `PostmarkProvider`, `MailgunProvider`, `SesProvider`) if you'd rather construct it directly.
+
+When a provider needs an SPF record and the name already has one, the provider is added to the existing record instead of creating a second one, which would make SPF fail.
+
+## DNS providers
+
+Create one with `createDnsProvider(name, config?)`:
+
+| DNS host | Name | Config |
+|---|---|---|
+| Cloudflare | `cloudflare` | `cloudflareApiToken` (or `CLOUDFLARE_API_TOKEN`), with Zone:Read and DNS:Edit on the zone |
+| Amazon Route 53 | `route53` | `aws: { accessKeyId, secretAccessKey, sessionToken? }`, or `awsProfile`, or the usual AWS environment variables. Optional `route53HostedZoneId` |
+| Any other host | `manual` | `onManualRecords(records)`: show the records to whoever adds them |
+
+Route 53 credentials need `route53:ListHostedZonesByName`, `route53:ListResourceRecordSets` and `route53:ChangeResourceRecordSets`. Records are merged into existing record sets in one atomic change, so an existing TXT record keeps its other values.
+
+### Records added by hand
+
+With `manual`, `setupDomain` hands the records to your callback and then waits for them to appear in DNS, so give whoever adds them enough time with `propagation.timeoutMs`:
+
+```ts
+import { createDnsProvider, describeRecord, detectDnsHost } from 'dkimkit';
+
+const host = await detectDnsHost('example.com');   // { name: 'GoDaddy', provider: null, nameservers: [...] }
+const dns = createDnsProvider('manual', {
+  onManualRecords: async (records) => {
+    console.log(`Add these records at ${host.name ?? 'your DNS host'}:`);
+    for (const r of records) console.log(' ', describeRecord(r));
+  },
+});
+const result = await setupDomain(email, dns, { domain: 'example.com', propagation: { timeoutMs: 30 * 60_000 } });
+```
+
+`detectDnsHost(domain)` recognizes common DNS hosts from the nameservers. Its `provider` is `cloudflare` or `route53` when records can be written automatically there, and `null` otherwise. It never throws.
+
+## Errors
+
+| Error | When | Useful fields |
+|---|---|---|
+| `ConfigError` | Missing or invalid credentials or options | `message` |
+| `DnsConflictError` | A record the provider needs already points somewhere else. Nothing was written | `conflicts`: the conflicting planned changes |
+| `ApiError` | An email or DNS provider rejected a request | `provider`, `status`, `body` |
+
+```ts
+import { ApiError, DnsConflictError, apiErrorHint } from 'dkimkit';
+
+try {
+  await setupDomain(email, dns, { domain: 'example.com' });
+} catch (err) {
+  if (err instanceof DnsConflictError) console.log(err.message);   // lists each conflict; pass overwrite: true to replace them
+  else if (err instanceof ApiError) console.log(err.message, apiErrorHint(err) ?? '');
+  else throw err;
+}
+```
+
+`apiErrorHint(err)` returns what to check when a provider rejects the credentials (401 or 403), such as the permissions a key needs.
+
+## Verifying webhooks
+
+If you also use the [hosted API](/docs/hosted-api#webhooks), the package verifies its webhook signatures:
+
+```ts
+import { verifyWebhookSignature } from 'dkimkit';
+
+const ok = verifyWebhookSignature(process.env.DKIMKIT_WEBHOOK_SECRET!, rawBody, req.headers['x-dkimkit-signature']);
+```
+
+Pass the raw request body, before any JSON parsing. Requests older than 5 minutes are rejected as replays.
+
+## CLI
+
+The same flow from a terminal, with no code:
+
+```bash
+export SENDGRID_API_KEY=SG.xxxx
+export CLOUDFLARE_API_TOKEN=xxxx
+
+npx dkimkit --domain example.com --inbound-url https://api.example.com/webhooks/inbound-email
+```
+
+It prints the DNS plan, asks before writing, then shows each step until the domain is verified.
+
+| Command | |
+|---|---|
+| `dkimkit --domain example.com` | Set up a domain |
+| `dkimkit status --domain example.com` | Show the provider's verification status without changing anything |
+| `dkimkit ui` | Open a local web interface for the same flow |
+
+| Option | |
+|---|---|
+| `-d, --domain` | Domain to authenticate |
+| `--provider` | `sendgrid` (default), `postmark`, `mailgun` or `ses` |
+| `--region` | Mailgun `us` or `eu`, or the Amazon SES region |
+| `--subdomain` | Return-path or MAIL FROM label |
+| `--dns` | `cloudflare`, `route53` or `manual`. Defaults to `cloudflare` when `CLOUDFLARE_API_TOKEN` is set |
+| `--inbound-url`, `--inbound-host` | Receive email and POST it to this URL. The host defaults to `parse.<domain>` (Mailgun: the domain itself) |
+| `--spam-check`, `--send-raw` | Inbound options |
+| `--overwrite` | Replace CNAME and MX records that point elsewhere |
+| `--dry-run` | Show the DNS plan without writing anything |
+| `--wait` | Seconds to wait for DNS to propagate (default 300) |
+| `--on-behalf-of` | Run as a SendGrid subuser |
+| `--aws-profile`, `--zone-id` | Route 53 profile and hosted zone |
+| `-y, --yes` | Write DNS without asking |
+| `--json` | Print the result as JSON, for scripts |
+
+Credentials come from the environment: `SENDGRID_API_KEY`, `POSTMARK_ACCOUNT_TOKEN` and `POSTMARK_INBOUND_SERVER_ID`, `MAILGUN_API_KEY` and `MAILGUN_REGION`, `AWS_REGION` for SES, `CLOUDFLARE_API_TOKEN`, and the usual AWS variables or `~/.aws/credentials` for Route 53 and SES.
+
+Exit codes: `0` done, `1` error, `2` not finished yet (DNS pending, not verified yet, or you declined the changes). Run the same command again to continue.

package/docs/self-hosting.md

@@ -0,0 +1,153 @@
+# Self-hosting and operations
+
+For whoever runs the service. This file is not published on the website.
+
+## Running the server
+
+```bash
+export ENCRYPTION_KEY=$(npx dkimkit-api generate-encryption-key)   # keep this safe; it decrypts stored credentials
+export DATABASE_URL=postgres://user:pass@db.internal/dkimkit   # or DATABASE_PATH=./data/dkimkit.db for SQLite
+
+SENDGRID_API_KEY=SG.xxx npx dkimkit-api create-account --name "Acme" --with-sendgrid-key
+# Account:  acct_…
+# API key:  dk_live_…        (shown once; only a hash is stored)
+
+npx dkimkit-api serve      # :8080, API and background worker in one process
+```
+
+Docker:
+
+```bash
+docker build -t dkimkit-api .
+docker run -p 8080:8080 -v dkimkit-data:/data -e ENCRYPTION_KEY=… dkimkit-api
+```
+
+| Variable | |
+|---|---|
+| `ENCRYPTION_KEY` | Required. 32 bytes, base64 or hex. AES-256-GCM key for stored SendGrid keys and DNS credentials |
+| `DATABASE_URL` | `postgres://…` connection string. Use this in production |
+| `DATABASE_PATH` | Used when `DATABASE_URL` is unset: SQLite file, default `./data/dkimkit.db` |
+| `PORT`, `HOST` | Default `8080`, `0.0.0.0` |
+| `WORKER_CONCURRENCY` | Domains checked in parallel, default 4 |
+| `RUN_WORKERS=false` | Serve the API only (run workers in another process on the same database) |
+| `ALLOW_PRIVATE_WEBHOOKS=true` | Development only: allow `http://` and private-network webhook URLs |
+| `PUBLIC_URL` | Public base URL (e.g. `https://dns.example.com`) used in widget links. Defaults to the request's host |
+
+## Storage
+
+| | SQLite (`DATABASE_PATH`) | Postgres (`DATABASE_URL`) |
+|---|---|---|
+| Good for | One server, development | Production, several API or worker instances |
+| Needs | Node 22.13+ (`node:sqlite`) | The `pg` package (an optional dependency, included in the Docker image) |
+
+Both create and upgrade their schema on startup, and that's safe when several instances start at once (Postgres uses an advisory lock). With Postgres you can run any number of API instances and workers against one database. Workers claim due jobs with `FOR UPDATE SKIP LOCKED`, so no domain is checked twice. A common setup is API instances with `RUN_WORKERS=false` behind a load balancer, plus one or two dedicated worker instances.
+
+The schema keeps the same shape on both backends: JSON columns are `TEXT` in SQLite and `JSONB` in Postgres, and timestamps are millisecond integers (`BIGINT` in Postgres). The column mapping lives in one place, `src/hosted/store.ts`. To add another backend, implement the `Store` interface there and run `test/store.test.ts` against it.
+
+## Accounts, limits and usage reports
+
+Invoice from the report for all accounts, and cap plans with a domain limit:
+
+```bash
+npx dkimkit-api usage-report --from 2026-10-01 --to 2026-10-31            # CSV, one row per account
+npx dkimkit-api usage-report --format json
+npx dkimkit-api set-domain-limit --account acct_… --limit 25              # or --unlimited
+SENDGRID_API_KEY=SG.xxx npx dkimkit-api create-account --name "Acme" --with-sendgrid-key   # operator-created account
+```
+
+The limit counts an account's current domains in any status. It's checked before anything is created at SendGrid, so a rejected request leaves nothing behind. Over the limit, `POST /v1/domains` returns `402 plan_limit_reached`. In the widget, end users see a neutral "contact support" message instead. Creates for a limited account run one at a time within a server process, so a bulk add can't overshoot. With several API instances the limit is soft: creates in different processes at the same instant can both pass.
+
+
+## Website and legal pages
+
+The service serves a public site when `PUBLIC_URL` is set: a landing page at `/`, `/pricing`, `/docs`, `/about`, `/contact`, `/terms`, `/privacy` and `/refunds`. Set these so the pages show the right details:
+
+| Variable | Used for |
+|---|---|
+| `APP_NAME` | Product name everywhere (default "DKIMkit") |
+| `LEGAL_NAME` | Who operates the service: your name or business name, on About and the legal pages |
+| `CONTACT_EMAIL` | Support and legal contact. Messages from the website's feedback form are emailed here (with the sign-in mailer) |
+| `LEGAL_COUNTRY` | Country whose law governs the terms (e.g. "India") |
+| `LEGAL_EFFECTIVE_DATE` | "Last updated" date on the legal pages (default: the build's date) |
+
+Until they're set, the pages show visible placeholders. The legal pages are drafts written for this product. Have them reviewed by someone qualified before relying on them.
+
+## Free plan before payments launch
+
+Without `BILLING_PROVIDER`, setting `FREE_DOMAINS` (e.g. `FREE_DOMAINS=10`) caps each account at that many domains, and the pricing page shows the free plan with pay as you go marked "coming soon". Raise one account's cap with `set-domain-limit`, which replaces the free plan's limit for that account. When billing is turned on, `FREE_DOMAINS` becomes the free threshold and must match the one in your payment provider.
+
+## Billing: payment provider
+
+Payments go through **[Dodo Payments](https://dodopayments.com)** by default. Dodo is a *merchant of record*: it is the legal seller to your customers, so it charges them, handles VAT, GST and sales tax worldwide, and pays you out. It accepts individual developers, including in India, without a registered company. Stripe is also supported (`BILLING_PROVIDER=stripe`) for when you have a company that Stripe accepts. The two are interchangeable behind a small provider interface (`src/hosted/billing.ts`).
+
+## Billing setup (Dodo Payments)
+
+Do this in **test mode** first (Dodo dashboard toggle), then repeat in live mode.
+
+1. **Meter.** In the Dodo dashboard, open Products → Meters and create:
+   - Event name: `active_domains` (must match `DODO_METER_EVENT`, default `active_domains`)
+   - Aggregation: **Max**, over property `active_domains`
+   - Measurement unit: `domains`
+2. **Product.** Create a subscription product with pricing type **Usage Based Billing**, billed monthly. Attach the meter with:
+   - Price per unit: **$2** (match `PRICE_PER_DOMAIN_CENTS`, default 200)
+   - Free threshold: **3** (match `FREE_DOMAINS`, default 3)
+
+   Copy the product id (`pdt_…`).
+3. **Webhook.** Developer → Webhooks → add an endpoint at `https://<your PUBLIC_URL>/billing/webhook` subscribed to the `subscription.*` events. Copy its signing secret (`whsec_…`).
+4. **API key.** Developer → API keys → create one.
+5. **Email for sign-in links**, sent through your own Resend or SendGrid account:
+   ```bash
+   PUBLIC_URL=https://dns.yourapp.com      # required for sign-up and billing
+   EMAIL_FROM=login@yourapp.com            # on a domain verified in Resend (or a verified SendGrid sender)
+   MAIL_RESEND_API_KEY=re_…                # a Resend key with sending access, or:
+   MAIL_SENDGRID_API_KEY=SG.…              # a SendGrid key with Mail Send permission
+   APP_NAME="Your Product"
+   ```
+   If both keys are set, Resend is used. Without `EMAIL_FROM` and a key, sign-in links are written to the log instead, which is handy in development.
+6. **Run:**
+   ```bash
+   BILLING_PROVIDER=dodo \
+   DODO_MODE=test \
+   DODO_API_KEY=… \
+   DODO_WEBHOOK_SECRET=whsec_… \
+   DODO_PRODUCT_ID=pdt_… \
+   npx dkimkit-api serve
+   ```
+   The startup log line shows `"billing": "dodo (test mode)"`. Switch to `DODO_MODE=live`, with live-mode keys, product and webhook secret, when you're ready to charge.
+
+`FREE_DOMAINS` and `PRICE_PER_DOMAIN_CENTS` only drive the dashboard's limits and estimates. What's charged is the product's price and free threshold in Dodo, so keep them in sync.
+
+## How usage reaches Dodo
+
+- **Hourly reporting:** every hour, the worker records an active day for each verified domain, then counts each paying account's distinct active domains in its current billing period. The period comes from the subscription's `previous_billing_date` and `next_billing_date` in Dodo's webhooks.
+- **Running totals:** when that count has grown, it sends one usage event to `POST /events/ingest` with the **running total** (`metadata.active_domains`). The meter's **Max** aggregation bills the period's highest total, and Dodo's free threshold makes the first 3 free. The count never decreases within a period, so its maximum is exactly the number of distinct active domains.
+- **No double billing:**
+  - Each event's `event_id` is `account:periodStart:total`, which Dodo treats as an idempotency key. Re-sending the same total is harmless.
+  - The total already reported is stored per account and period, so unchanged totals aren't re-sent.
+  - A renewal starts a new period, which is reported from zero.
+- **Timing:** Dodo accepts usage events up to 1 hour old. Events are timestamped when sent, so the hourly report always qualifies.
+
+## Webhook handling
+
+Dodo signs webhooks with the Standard Webhooks scheme. Each request is checked as follows:
+- **Signature:** an HMAC-SHA256 over `webhook-id.webhook-timestamp.body`, keyed with the base64 secret after its `whsec_` prefix, compared in constant time. Several `v1,` signatures are accepted during secret rotation.
+- **Freshness:** the timestamp must be within 5 minutes.
+- **Processed once:** each `webhook-id` is processed only once, since Dodo retries with the same id.
+- **Out-of-order events:** events older than the last one applied to an account are ignored, because delivery order isn't guaranteed. A cancellation for a subscription that has already been replaced doesn't downgrade the new one.
+
+| Dodo subscription status | Account |
+|---|---|
+| `active` | Pay as you go |
+| `past_due`, `on_hold` | Pay as you go, payment issue |
+| `cancelled`, `expired`, `failed`, `paused` | Free |
+| `pending` | Unchanged until it settles |
+
+## Stripe (alternative)
+
+With `BILLING_PROVIDER=stripe`, the same flow uses Stripe Checkout and Stripe's Customer Portal, and reports usage to a Stripe billing meter. Stripe's meter sums events, so this provider reports increments rather than running totals. `npx dkimkit-api stripe-setup` creates the meter, a graduated metered price (first 3 free) and the webhook endpoint. Set `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET` and `STRIPE_PRICE_ID`.
+
+## Limits and notes
+
+- **Caps across instances:** a cap is exact within one process, but two instances creating domains for the same account at the same instant can both pass it.
+- **Free accounts:** usage is metered for them too (visible in the dashboard), but only accounts with a payment method on file are reported to the provider.
+- **Not yet tested against a live Dodo account:** the integration follows Dodo's API reference and is tested against a simulated Dodo API. Before charging real customers, run one full checkout → usage → invoice cycle in test mode.