@portable/dkim

Signs and verifies DKIM signatures (RFC 6376), with RSA and Ed25519 keys (RFC 8463) and the algorithm rules of RFC 8301. Runs in browsers, Cloudflare Workers, Deno, Bun and Node 24+.

Replaces the DKIM parts of mailauth and the DKIM signer of nodemailer.

npm install @portable/dkim @portable/dns

import * as Dns from '@portable/dns';
import * as Dkim from '@portable/dkim';
 
const field = await Dkim.sign(message, {
  domain: 'example.com',
  selector: 'mail',
  privateKey: env.DKIM_PRIVATE_KEY,
});
const signed = field + message;
 
const results = await Dkim.verify(signed, {
  resolver: Dns.create(),
  signal: AbortSignal.timeout(10_000),
});
for (const r of results) {
  console.log(
    `dkim=${r.result} header.d=${r.domain} header.s=${r.selector}`,
  );
}

A message is a ReadableStream<Uint8Array>, a Uint8Array or a string, which is encoded as UTF-8. Bare LF line ends are read as CRLF, so a message stored with LF line ends signs and verifies the same as one with CRLF.

In Node, node:dns/promises works as the resolver and uses the system's DNS servers:

import dns from 'node:dns/promises';
 
await Dkim.verify(message, { resolver: dns });

Signing

sign resolves to the DKIM-Signature field, ending in CRLF, to put above the message's other fields. It always writes t= and never l=, and folds lines at 76 characters.

sign throws a TypeError or RangeError for an invalid option, such as a domain that isn't a host name, an RSA key under 1024 bits or a header list without From. It throws Dkim.InvalidInputError for a message without a From field.

Verifying

verify resolves to one result per DKIM-Signature field, in header order. A message without signatures gives an empty array. Each key is looked up once, while the body is read, and the body is read once whatever the number of signatures.

There is no default resolver, so you decide which servers see the lookups. It treats a resolver rejection with code ENOTFOUND, ENODATA or EBADNAME as no key, and any other rejection as temperror.

verify rejects only for invalid options, a message stream that fails, and an aborted signal.

Crypto

RSA and Ed25519 signing and verification use WebCrypto (crypto.subtle), which every supported runtime has. There are no crypto dependencies.

The body hash is different. crypto.subtle.digest can't hash incrementally, so by default the canonicalized body is collected and hashed with one call. MTAs usually limit a message to 25 to 50 MB, so the buffer is no larger than what a mail server already holds. A signer has to buffer the message anyway, because the DKIM-Signature field goes before the body and contains the body hash, so only verification would gain from streaming. If WebCrypto adds streaming digests, the default can switch to one without an API change.

To verify in constant memory, pass hasher, a function that takes the hash name and returns an incremental hash with update(bytes) and digest(). DKIM calls it with 'SHA-256', and sha256.create() from @noble/hashes returns one:

import { sha256 } from '@noble/hashes/sha2.js';
 
await Dkim.verify(request.body!, {
  resolver,
  hasher: () => sha256.create(),
});

Types

Why use this over mailauth and nodemailer

• It runs anywhere. mailauth and nodemailer use node:crypto, node:stream and Buffers, so they don't run in Workers or a browser.
• It follows the RFCs by default. mailauth's default mode accepts signatures that RFC 6376 rejects, such as a missing v=, a duplicate tag or rsa-sha1, and mailauth follows the RFC only with strict: true. mailauth's strict mode accepts the signatures sign makes, verify accepts the signatures of mailauth and nodemailer, and the two verifiers agree on 12 kinds of changed message.
• It refuses what it can't sign safely. nodemailer silently removes tag delimiters from the domain and sends the message unsigned when the key is unusable. sign throws for both.
• It has no dependencies outside @portable/*. mailauth pulls in libmime, punycode.js, tldts, joi and more.
• It verifies faster. In Node it verifies a 250 KB message about three times as fast as mailauth, and signs it about as fast as nodemailer, as the table below shows.

Operations per second from pnpm bench, higher is better, in Node 24.22.0, on Intel(R) Xeon(R) Processor @ 2.10GHz (4 cores). A dash means the library has no equivalent.

Sizes cover the imports in the usage example, or the equivalent imports of each library, bundled for the browser by scripts/bundle-size.ts. Runtime dependencies count every package installed with the published package. A library that uses Node built-ins needs polyfills in a browser and the nodejs_compat flag in Cloudflare Workers.

Differences to check when you switch:

• mailauth's resolver is one (name, type) function. verify takes an object with a resolveTxt method, such as node:dns/promises.
• mailauth reports problems with the key record as neutral, and verify reports them as permerror.
• mailauth's status.aligned and headerFrom have no equivalent, because alignment is DMARC's job (@portable/dmarc). Neither have info and mimeStructureStart.
• mailauth's dkimSign and nodemailer's keys sign with several keys in one call. Call sign once per key and prepend each field.
• mailauth's dkimSign reports problems in errors and warnings. sign throws instead.
• mailauth's maxBodyLength has no equivalent, because l= lets anyone append to the body.
• nodemailer's skipFields has no equivalent. Leave the names out of headers instead.
• nodemailer's hashAlgo has no equivalent. DKIM uses SHA-256 (RFC 8301).
• nodemailer's cacheDir and cacheTreshold have no equivalent. sign writes nothing to disk, and it keeps the canonicalized body in memory unless you pass an incremental hasher.