DEV Community: Houzelle

Multi-tenant DKIM in Haraka: two signatures on one message

Houzelle — Mon, 10 Aug 2026 07:52:24 +0000

In my previous post
I described a catch-all email forwarder built on Haraka, and I waved at the
bring-your-own-domain case with one lazy sentence: "a small additive
queue_outbound hook that reuses the DKIM signing stream."

That sentence hid the hardest part of the whole system. This post is the part I
skipped: how to DKIM-sign outbound mail for hundreds of customer domains,
with per-tenant keys living in a database, from a single Haraka instance. It's
what powers custom domains on Tomatoes.run.

Why one signature isn't enough

Forwarding mail means rewriting the envelope sender (SRS) so SPF passes on
your domain. Fine. So you DKIM-sign with d=example.com and call it a day.

Then a customer points mail.theircompany.com at you, and DMARC breaks.

The reason is alignment. DMARC doesn't check the envelope — it checks the
domain in the visible From: header, and demands that either SPF or DKIM
pass for that domain. After SRS, your envelope says example.com while the
header still says theircompany.com. Nothing aligns with the header domain, so
DMARC fails even though both SPF and DKIM technically "pass".

You need a signature whose d= is the customer's domain. And you still need the
first one, for the SRS return-path. So: two signatures on one message.

Step 1 — mark the message on the way in

DKIM signing happens late, at queue time. The decision about which domain to
sign for is made much earlier, when you know the recipient. So you stash it on
the transaction:

// Tell haraka-plugin-dkim this is a relayed message: it signs with the
// envelope domain (SRS-rewritten to ours), not the original From — we
// have no key for that one.
txn.notes.forward = true;

// Custom domain? Ask for a SECOND signature with d=<their domain>.
// Our own catch-all subdomains (you.example.com) are excluded: they're
// already covered by the envelope signature.
const rcptHost = rcpt.slice(rcpt.lastIndexOf('@') + 1);
if (rcptHost !== cfg.domain && !rcptHost.endsWith(`.${cfg.domain}`)) {
  txn.notes.sign_domain = rcptHost;
}

The exclusion matters. Signing d=you.example.com would need a key per
subdomain, and there's no point: the envelope signature on the parent domain
already aligns for those.

Step 2 — add the second signature at queue_outbound

Here's the trick, and it depends on plugin order. Your custom hook must run
after haraka-plugin-dkim (order is set in config/plugins), so the first
signature already exists and you're purely additive.

const { DKIMSignStream } = require('haraka-plugin-dkim/lib/dkim');

exports.hook_queue_outbound = function (next, connection) {
  const txn = connection.transaction;
  const domain = txn && txn.notes.sign_domain;
  if (!domain || !DKIMSignStream) return next();

  this.fetch_dkim(domain, (err, key) => {
    if (err || !key) return next();  // no key provisioned -> ship it anyway

    let done = false;
    const finish = (e) => {
      if (done) return;            // never call next() twice
      done = true;
      try { txn.message_stream.unpipe(); } catch (_) {}
      return next();
    };

    const stream = new DKIMSignStream(
      { domain, selector: key.selector, private_key: key.privateKey,
        headers: DKIM_SIGN_HEADERS, body_canon: 'relaxed' },
      txn.header,
      (e, dkimHeader) => {
        if (e) return finish(e);
        if (dkimHeader) txn.add_header('DKIM-Signature', dkimHeader);
        return finish();
      }
    );
    txn.message_stream.pipe(stream, {});
  });
};

Two details worth stealing:

Reuse DKIMSignStream instead of reimplementing signing. It's an internal path of haraka-plugin-dkim, so I require it inside a try/catch and leave the binding null on failure. If upstream reshuffles its files, custom signing quietly stops — mail still flows, signed with the envelope domain. A missing feature beats a crashed MX.
The done flag is not paranoia. A stream that both errors and fires its callback would call next() twice, and Haraka will happily queue the message twice. Guard it.

Step 3 — per-tenant keys

Each verified domain gets an RSA keypair at signup: public half goes in the
customer's DNS as <selector>._domainkey, private half into Postgres.

Haraka fetches it through a read-only internal endpoint, authenticated with the
same shared secret as the rest of the internal API:

// POST /internal/email/dkim  { domain } -> { selector, privateKey } | { key: null }
const d = await prisma.domain.findFirst({
  where: { domain: domain.toLowerCase(), verifiedAt: { not: null } },
  select: { dkimSelector: true, dkimPrivateKey: true },
});
if (!d?.dkimSelector || !d?.dkimPrivateKey) return json({ key: null });

Note verifiedAt: { not: null } — an unverified domain never gets a key served,
which is the same gate that stops the MX from becoming an open relay.

Keys are cached in-process with a TTL, because otherwise every single message
costs an HTTP round-trip plus a DB read.

The part I find most interesting: opposite failure modes

Both of these talk to the same internal API. They fail in opposite
directions, on purpose.

Recipient validation fails closed. At hook_rcpt, if the API is
unreachable, you answer DENYSOFT — a 4xx tempfail. SMTP is store-and-forward,
so the sender retries for days; a few minutes of downtime loses nothing. Accept
optimistically here and you're an open relay.

catch (err) { return next(DENYSOFT); }   // never accept what you can't validate

Signing fails open. At hook_queue_outbound, every error path just calls
next(). API down, key missing, stream throws, module moved — the message goes
out anyway, already signed with the envelope domain.

if (err) { plugin.logwarn(...); return next(); }   // ship it

The asymmetry is the whole design. Failing closed on validation protects
everyone else from you relaying spam. Failing closed on signing would protect
nobody — it would just silently stop your customer's mail over a degraded
optional feature. Match the failure direction to who gets hurt.

Gotchas and things I'm still unsure about

Being honest about the rough edges, because this is the stuff that costs you a
weekend:

Piping message_stream a second time at queue time is the part I trust least. The first signature already consumed the stream; this hook attaches another consumer to it. It works in my testing and the unpipe() in finish() keeps it tidy, but I'd call it "validated on my traffic", not "battle-tested at scale". If you know a cleaner way to get two signatures out of Haraka, the comments are open — that's half my reason for writing this.
Negative results aren't cached. A verified domain with no key provisioned hits the API on every message. Easy fix, still on my list.
The signed-headers list is duplicated between the plugin constant and config/dkim.ini [sign]. Two places, one meaning, guaranteed to drift.
Private keys sit in Postgres, on the same trust boundary as forwarding addresses. Defensible for a small operation, and honestly the thing I'd move to a KMS first if this grew.
DMARC is about the header From, not the envelope. If you remember one sentence from this post, that's the one — almost every forwarding deliverability bug I've hit traces back to forgetting it.

This runs in production as Tomatoes.run, a
France/EU-hosted take on per-service email aliases — every address on your
subdomain works instantly, and Premium users can bring their own domain (so
leaving is just repointing an MX record). If you've done multi-tenant DKIM
differently, I genuinely want to hear it. 🍅

Catch-all email aliasing: a different address for every service (Haraka + SRS + DKIM)

Houzelle — Tue, 28 Jul 2026 07:21:53 +0000

Most people use the same email address everywhere. One breach and it leaks for
years. The known fix is a different alias per service — but every tool I tried
made me create each alias upfront. I wanted the opposite: a subdomain where
every address just works, and the alias is born the moment the first email
arrives.

This post is the engineering behind that: how to run a catch-all subdomain
mail flow without becoming an open relay, and how to forward mail without
nuking your deliverability (SPF, SRS, DKIM, DMARC). It's what powers
Tomatoes.run in production, but the ideas apply to
any forwarding setup.

The core idea: decide at RCPT time, not at signup

Instead of a table of pre-created aliases, you give each user a personal
subdomain — you.example.com — and treat every local-part as potentially
valid: amazon@you.example.com, github@you.example.com, anything. The
validity decision happens when the mail is received, not when an alias is
created.

The stack:

Haraka (Node.js SMTP server) as the MX.
A small internal HTTP API (Next.js route) that owns the forward / reject / tempfail decision.
Postgres for users, aliases and metadata only — message content is never stored, it's forwarded immediately.

inbound mail ──> Haraka (MX) ──hook_rcpt──> internal API ──> decision
                                                              │
                        forward ◄─ rewrite envelope (SRS) ────┘
                        + DKIM sign ──> outbound queue ──> user's real inbox

Challenge 1 — a catch-all that isn't an open relay

The scary part of "accept any recipient" is accidentally relaying spam. The
trick is to be optimistic only for addresses you own, and fail closed for
everything else.

In Haraka's hook_rcpt:

exports.hook_rcpt = async function (next, connection, params) {
  const rcpt = params[0];
  const domain = rcpt.host.toLowerCase();

  // Our own catch-all subdomains: accept optimistically, resolve later.
  if (domain.endsWith('.example.com')) return next(OK);

  // Custom domains (bring-your-own): must be verified. Ask the API,
  // with a short-TTL cache to avoid a round-trip per RCPT.
  try {
    const known = await isVerifiedDomain(domain); // API + cache
    return next(known ? OK : DENY);
  } catch (err) {
    // API down? DENYSOFT (4xx) — the sender retries, we lose nothing,
    // and we never relay something we couldn't validate. Fail CLOSED.
    return next(DENYSOFT);
  }
};

Two things matter here:

DENYSOFT (a 4xx tempfail), not DENY, when the validating API is unreachable. SMTP is store-and-forward: the sending server retries for days. A few minutes of downtime loses zero mail, and you never blindly accept.
The custom-domain gate is what keeps you off "open relay" lists. No verification, no acceptance.

Challenge 2 — forwarding breaks SPF, so rewrite the envelope (SRS)

Naive forwarding looks like this: mail comes in for you, you resend it to the
user's real inbox keeping the original MAIL FROM. The receiving MX checks
SPF on that MAIL FROM domain… and sees your server sending on behalf of
someone else's domain → SPF fail → spam folder or reject.

The fix is SRS (Sender Rewriting Scheme): rewrite the envelope sender to
your own domain, encoded so bounces can be reversed back to the original
sender.

// forward:  bob@gmail.com  ->  SRS0=hash=tt=gmail.com=bob@example.com
const bounce = srs.forward(originalMailFrom, 'example.com');

// on a bounce hitting SRS0=... @example.com, reverse it back:
const original = srs.reverse(bounceRecipient); // -> bob@gmail.com

Now SPF is checked against your domain, which does authorize your server.
The hash makes the token tamper-proof and reversible, so DSNs still reach the
real sender. Keep the SRS secret stable — rotating it invalidates in-flight
bounce addresses.

Challenge 3 — DKIM-sign outbound, per domain

Even with SPF happy, unsigned forwarded mail is suspicious. So the outbound
message is DKIM-signed with your domain (d=example.com).

The interesting case is bring-your-own-domain. When a user adds their own
domain, you generate an RSA keypair, store the private key, and publish the
public key as their DNS TXT record. Outbound mail for that user then gets
signed twice:

d=example.com on the SRS return-path (envelope alignment), and
d=theircustomdomain.com on the visible From: (author-domain alignment),

so DMARC passes on the domain that actually appears in the headers. Two
signatures, one message — a small additive queue_outbound hook that reuses the
DKIM signing stream.

Challenge 4 — the "no pre-creation" magic

Back at the API, the decision endpoint is where the product logic lives:

// POST /internal/email/receive  { alias, domain, sender, ... }
// returns one of: forward | reject | tempfail

Unknown-but-valid recipient → auto-create the alias on first email and forward. The alias simply appears in the dashboard; the user never created it.
Free-plan cap reached → reject new aliases (existing ones keep working).
Disabled alias → reject, so leaked addresses go silent at the server edge.
Only metadata is recorded (sender, date, size, status). The body is streamed straight through, never persisted.

That single "decide at receive time" inversion is what removes the
create-an-alias-first step entirely.

Gotchas worth knowing

tempfail vs reject semantics: use 4xx when you might be wrong (dependency down), 5xx only when the address is genuinely invalid/blocked.
DMARC alignment is about the header From, not the envelope — hence the per-domain DKIM signature above.
Catch-all + spam: every address existing means every address can be spammed. Per-alias disable (server-side reject) is the escape hatch.
Don't store content. It's less liability and, honestly, a better privacy story — you only ever hold metadata.

This runs in production as Tomatoes.run, a
France/EU-hosted take on per-service email aliases (independent, GDPR by
design). If you've fought SPF/DKIM/SRS on forwarding before, I'd love your war
stories in the comments — deliverability is a rabbit hole and I'm still digging. 🍅