dkimkit 0.0.0-stage → 0.6.1

package/docs/billing.md

@@ -0,0 +1,43 @@
+# Plans and billing
+
+Start free, and pay only for what you use once you grow past the free allowance.
+
+| | Free | Pay as you go |
+|---|---|---|
+| Price | Free, no card needed | First {{FREE_DOMAINS}} active domains free, then **{{PRICE}} per active domain per month** |
+| Domains | Up to {{FREE_DOMAINS}} | Unlimited |
+| Features | API, embeddable widget, Cloudflare, Route 53 and manual DNS, webhooks, usage reports | Everything in Free |
+
+## What counts as an active domain
+
+A domain is **active** in a billing period if it was verified on at least one day of that period. Each domain counts once per period, however many days it was active.
+
+- A domain verified on the 3rd and deleted on the 10th counts once that month.
+- Deleting a domain doesn't remove it from a period it was already active in.
+- Domains that never verify, for example because the DNS records were never added, aren't counted.
+
+**Example:** you have 8 active domains this month. The first {{FREE_DOMAINS}} are free, so you pay for the rest, at {{PRICE}} each.
+
+## Upgrading
+
+Sign in to your [dashboard](/dashboard) and choose **Add payment method**. You'll go to our payment partner's secure checkout page. Once it's done, the domain cap is lifted immediately.
+
+On the free plan, creating more than {{FREE_DOMAINS}} domains returns `402 plan_limit_reached` from the API, with an `upgrade_url` that points to your dashboard. Your existing domains keep working either way.
+
+## Your bill
+
+You're billed monthly for the active domains in the previous period. Your dashboard shows this period's active domains and the estimated amount so far, and the [usage API](/docs/hosted-api#usage-and-billing) gives the same numbers, broken down by your own customers if you like.
+
+## Cancelling
+
+Cancel any time from **Manage billing** in the dashboard. Your existing domains keep working, and you go back to the free plan's limit for new domains. You're billed only for domains active during the period before you cancelled.
+
+## If a payment fails
+
+We keep your plan active while the payment is retried, and the dashboard asks you to update your payment method. If the payment can't be collected, the subscription ends and the account returns to the free plan.
+
+## Payments and tax
+
+Payments are processed by [Dodo Payments](https://dodopayments.com), our merchant of record. Dodo is the seller on your invoice, charges your payment method, and handles VAT, GST and sales tax for your country. Your card details go to Dodo and never reach our servers. Invoices and payment methods are available from **Manage billing** in the dashboard.
+
+Questions about a charge? See our [refund policy](/refunds) or [contact us](/contact).

package/docs/getting-started.md

@@ -0,0 +1,57 @@
+# Getting started
+
+{{APP_NAME}} authenticates your customers' sending domains with SendGrid, Postmark, Mailgun or Amazon SES. It creates the DNS records, writes them for your customers or shows them what to add, keeps checking until your email provider verifies the domain, and tells your app when each domain is ready. This guide takes you from sign-up to your first verified domain.
+
+## 1. Create an account
+
+[Sign up](/dashboard) with your email address. We email you a link; there's no password.{{#billing}} You start on the free plan, which includes {{FREE_DOMAINS}} domains.{{/billing}}
+
+## 2. Connect your email provider
+
+In the dashboard under **Settings**, choose your email provider and enter its credentials:
+
+| Provider | What to enter |
+|---|---|
+| SendGrid | An API key with full **Sender Authentication** access, plus **Inbound Parse** to receive email |
+| Postmark | An **account** API token (Account → API Tokens), plus a server ID if you want to receive email |
+| Mailgun | A private API key and your account's region (US or EU) |
+| Amazon SES | An IAM access key with SES permissions (create, get and delete identities, set MAIL FROM) and your SES region |
+
+Credentials are encrypted at rest and never shown again. Each account uses one provider; to switch, delete your domains first.
+
+Each provider asks for slightly different DNS records, and we handle the differences. For example, if a domain already has an SPF record, we add the provider to it rather than creating a second SPF record, which would break SPF.
+
+## 3. Create an API key
+
+Choose **Create new API key** in the dashboard and copy it. It's shown once. Use it from your backend as a bearer token:
+
+```bash
+export API_KEY=dk_live_…
+curl {{PUBLIC_URL}}/v1/account -H "Authorization: Bearer $API_KEY"
+```
+
+## 4. Register a domain
+
+```bash
+curl -X POST {{PUBLIC_URL}}/v1/domains \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"domain": "customer.com", "tenant_id": "cus_42", "dns": {"provider": "manual"}}'
+```
+
+The response includes the DNS records your customer needs to add. Then you have two options:
+
+- **Show the records:** show them in your app, so your customer can add them at their DNS host. We detect when they're live.
+- **Write them for the customer:** pass `"dns": {"provider": "cloudflare", "cloudflare_api_token": "…"}`, or the Route 53 equivalent, and we add the records to their DNS ourselves.
+
+Or skip building UI entirely and use the [embeddable widget](/docs/widget), which walks your customers through it, including connecting Cloudflare or Route 53.
+
+## 5. Find out when it's verified
+
+Check `GET /v1/domains/{id}`, or better, set a **Webhook URL** in the dashboard and we'll POST a signed `domain.verified` event as soon as your email provider confirms the domain. We keep checking in the background, and re-check verified domains daily so you hear about it if a record is later removed.
+
+## Next steps
+
+- [API reference](/docs/hosted-api): every endpoint, the domain lifecycle, errors and webhooks
+- [Embeddable widget](/docs/widget): let your customers connect their own DNS inside your app
+{{#billing}}- [Plans and billing](/docs/billing): pricing and what counts as an active domain{{/billing}}

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/self-hosting.md

@@ -0,0 +1,148 @@
+# 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. The limit is soft: two creates 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 |
+| `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.
+
+## 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 SendGrid account:
+   ```bash
+   PUBLIC_URL=https://dns.yourapp.com      # required for sign-up and billing
+   EMAIL_FROM=login@yourapp.com            # a verified sender in your SendGrid account
+   MAIL_SENDGRID_API_KEY=SG.…              # needs Mail Send permission
+   APP_NAME="Your Product"
+   ```
+   Without `EMAIL_FROM`/`MAIL_SENDGRID_API_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
+
+- **Soft caps:** two domain creations at the same instant can both pass a cap.
+- **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.

package/docs/widget.md

@@ -0,0 +1,121 @@
+# Embeddable widget
+
+A drop-in UI that lets your users connect their own domain for sending email from inside your app. It runs on the [hosted API](hosted-api.md). The widget:
+- asks for the domain, or uses one you already registered;
+- detects where the domain's DNS is hosted;
+- either connects Cloudflare or Route 53 and writes the records automatically, or shows the exact records to paste at any other provider;
+- tracks progress until the domain is verified.
+
+```
+Your backend ── POST /v1/widget-sessions (secret key) ──▶ API ──▶ client_secret (wss_…, 1 hour)
+Your frontend ── <script src=".../widget.js"> + DKIMkit.mount(el, { session }) ──▶ iframe on the API's origin
+```
+
+## 1. Allow your app's origin (once)
+
+```bash
+curl -X PATCH https://dns.example.com/v1/account \
+  -H "Authorization: Bearer $DKIMKIT_API_KEY" -H "Content-Type: application/json" \
+  -d '{"widget_origins": ["https://app.yourproduct.com", "http://localhost:3000"]}'
+```
+
+Only these origins can embed the widget. `http://` is accepted only for `localhost`.
+
+## 2. Create a session on your backend
+
+Never send your API key to the browser. Create a short-lived session for the signed-in user instead:
+
+```ts
+// POST /api/email-domain/session (your route; requires the user to be signed in)
+const res = await fetch('https://dns.example.com/v1/widget-sessions', {
+  method: 'POST',
+  headers: { Authorization: `Bearer ${process.env.DKIMKIT_API_KEY}`, 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    tenant_id: currentUser.workspaceId,       // the user enters their domain in the widget
+    inbound_url: 'https://api.yourproduct.com/inbound-email',  // optional
+    metadata: { plan: currentUser.plan },     // optional, never shown to the user
+  }),
+});
+const { client_secret } = await res.json();
+return { session: client_secret };
+```
+
+There are two ways to create a session:
+- **`{ tenant_id, … }`:** the user types their domain in the widget. The domain is created with `tenant_id`, `metadata`, `subdomain`, `sendgrid_subuser` and `inbound_url` (its hostname becomes `parse.<domain>`). If the same tenant comes back with the same domain, the widget resumes it. If another tenant already registered that domain, the widget refuses without revealing anything about it.
+- **`{ domain_id }`:** for a domain you already created with `POST /v1/domains`.
+
+Sessions last 1 hour by default (`expires_in`: 60 to 86400 seconds). Each session is tied to one domain and can't read or change anything else.
+
+## 3. Mount it
+
+```html
+<div id="email-domain"></div>
+<script src="https://dns.example.com/widget.js"></script>
+<script>
+  const { session } = await fetch('/api/email-domain/session', { method: 'POST' }).then((r) => r.json());
+  DKIMkit.mount('#email-domain', {
+    session,
+    onReady: (domain) => {},                 // domain is null until the user enters one
+    onStatusChange: (domain) => {},          // pending → awaiting_dns → verifying → verified, or conflict / failed
+    onVerified: (domain) => showToast(`${domain.domain} is ready`),
+    onError: (error) => {},                  // { type: 'session_expired', message }
+    appearance: { accent: '#4f46e5', mode: 'light', radius: 8 },
+  });
+</script>
+```
+
+React:
+
+```tsx
+function EmailDomainSetup({ session }: { session: string }) {
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const widget = window.DKIMkit.mount(ref.current!, { session, onVerified: () => refetch() });
+    return () => widget.unmount();
+  }, [session]);
+  return <div ref={ref} />;
+}
+```
+
+`mount` returns `{ iframe, unmount }`. The iframe resizes itself to fit its content.
+
+**Appearance:**
+- `accent`: `#rrggbb`. Button text switches between black and white for contrast.
+- `mode`: `light` (default), `dark`, or `auto`. `auto` follows the operating system; light is the default because matching your page matters more than the OS setting.
+- `radius`: 0–24.
+
+If you load `widget.js` some other way (a bundler or a module import), pass `apiOrigin: 'https://dns.example.com'`.
+
+**Caching:** `widget.js` is served with a 5-minute cache, so updates to the loader take up to 5 minutes to reach browsers.
+
+## What your users see
+
+1. **Domain:** only for tenant sessions.
+2. **Setup method:** chosen based on where the domain's DNS is hosted, which the widget detects from its nameservers.
+   - **Cloudflare or Route 53:** "Your DNS is hosted at Cloudflare. Connect it." The user creates a scoped token, or an IAM key with a minimal policy. The API checks the credentials against the zone before saving them, so a wrong token gets a clear error immediately.
+   - **GoDaddy, Namecheap and other recognized hosts:** "Add the records in your GoDaddy account." The records are shown with host names in the form registrars expect (`em1234`, `s1._domainkey`, `@`), each with a copy button.
+3. **Progress:** each record shows *Waiting* or *Found*, with a "Check now" button. The user can close the page while checks continue in the background, and your webhooks still fire.
+4. **Conflicts:** if existing records with the same names point elsewhere, the user sees which ones and can choose "Replace them". Records with other names are never touched.
+5. **Done:** the domain is verified.
+
+## Security model
+
+- **Credential isolation.** The widget is an iframe served from the API's origin. The Cloudflare tokens and AWS keys your users type go straight to the API, encrypted at rest. They never pass through your page's JavaScript or your servers.
+- **Session tokens, not API keys, in the browser.** `wss_…` tokens are stored as hashes, expire, cover one domain, and are rejected by the account API. The reverse holds too: your API key doesn't work on widget endpoints.
+- **Clickjacking.** The frame sends `Content-Security-Policy: frame-ancestors <your widget_origins>`, so other sites can't embed it to trick users into typing credentials. An expired or invalid session sends `frame-ancestors 'none'`.
+- **Locked-down frame.** `default-src 'none'`, a per-response nonce on the script, `connect-src 'self'`, no referrer, and theme parameters validated before they reach the page.
+- **Messaging.** The frame only exchanges `postMessage` with a parent whose origin is in `widget_origins`, and the loader only accepts messages from its own iframe on the API origin. Messages carry the end-user view of the domain: no ids, metadata, webhook URLs or credentials.
+- **End-user errors are sanitized.** Email-provider and configuration failures, which are yours to fix, appear to users as a generic message. The full error is in `last_error` on the API and in your `domain.failed` webhook.
+
+## Widget endpoints
+
+These are called by the iframe with `Authorization: Bearer wss_…`. You normally don't call them yourself.
+
+| | |
+|---|---|
+| `GET /v1/widget/session` | Session state: `needs_domain`, `domain` (end-user view), `dns_host` |
+| `POST /v1/widget/domain` | `{ domain }`, for tenant sessions |
+| `POST /v1/widget/connect` | `{ provider: 'cloudflare' \| 'route53' \| 'manual', … }`. Credentials are verified before they're saved |
+| `POST /v1/widget/verify` | Check now |
+| `POST /v1/widget/resolve-conflicts` | The user approves replacing conflicting records |
+| `GET /widget.js`, `GET /widget/frame` | The loader and the iframe page |

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "dkimkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.1",
+  "description": "DKIMkit: authenticate sending domains with SendGrid, Postmark, Mailgun or Amazon SES. DNS records written or shown, propagation tracked, verified automatically.",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "bin": {
+    "dkimkit": "dist/src/cli.js",
+    "dkimkit-api": "dist/src/hosted/cli.js"
+  },
+  "files": [
+    "dist/src",
+    "web",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc && node --test \"dist/test/**/*.test.js\"",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "cloudflare",
+    "dkim",
+    "dns",
+    "domain-authentication",
+    "email",
+    "inbound-parse",
+    "mailgun",
+    "postmark",
+    "sendgrid",
+    "ses",
+    "spf"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "@types/pg": "^8.23.1",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./hosted": {
+      "types": "./dist/src/hosted/index.d.ts",
+      "default": "./dist/src/hosted/index.js"
+    },
+    "./hosted/sqlite": {
+      "types": "./dist/src/hosted/sqlite-store.d.ts",
+      "default": "./dist/src/hosted/sqlite-store.js"
+    },
+    "./hosted/postgres": {
+      "types": "./dist/src/hosted/postgres-store.d.ts",
+      "default": "./dist/src/hosted/postgres-store.js"
+    }
+  },
+  "optionalDependencies": {
+    "pg": "^8.23.1"
+  }
+}