dkimkit 0.6.1 → 0.7.0

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

@@ -55,7 +55,7 @@ npx dkimkit-api set-domain-limit --account acct_… --limit 25              # or
 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.
+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
@@ -66,12 +66,16 @@ The service serves a public site when `PUBLIC_URL` is set: a landing page at `/`
 |---|---|
 | `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 |
+| `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`).
@@ -91,14 +95,15 @@ Do this in **test mode** first (Dodo dashboard toggle), then repeat in live mode
    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:
+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            # a verified sender in your SendGrid account
-   MAIL_SENDGRID_API_KEY=SG.…              # needs Mail Send permission
+   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"
    ```
-   Without `EMAIL_FROM`/`MAIL_SENDGRID_API_KEY`, sign-in links are written to the log instead, which is handy in development.
+   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 \
@@ -143,6 +148,6 @@ With `BILLING_PROVIDER=stripe`, the same flow uses Stripe Checkout and Stripe's
 
 ## Limits and notes
 
-- **Soft caps:** two domain creations at the same instant can both pass a cap.
+- **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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dkimkit",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "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",