can you document `verify` method further?

So if one record fails verification, do all? What does the object look like? Is result always an object?

No, DKIM.verifySignature() only verifies one signature at a time. You'll want to use DKIM.verify( message, callback ) (unless you want to verify a specific signature), which verifies all DKIM signatures found in the message, and returns an array of results. The result array of DKIM.verify() contains verification results of the shape

{
  verified: Boolean,
  status: DKIM.NONE | DKIM.OK | DKIM.TEMPFAIL | DKIM.PERMFAIL,
  error: Error?,
  signature: DKIM.Signature?,
  key: DKIM.Key?
}

which should allow you to select / filter / etc. for the signatures you're interested in.

For DKIM.verifySignature() it's a bit different – it only verifies one specific signature (which requirers all other DKIM headers to be filtered), and takes the arguments

( body: Buffer, headers: Array<String>, callback: Function )

and it's result is of the same shape as above. This method is mainly for internal use.

Is there a way to just get a true/false on an email if it passes DKIM? Do we have to do it like the test where you iterate over every result and ensure result.verified is true?

Short answers: Nope-ish, yes.

There currently is no method to get a simple true / false for DKIM signatures of a message, as a message can have multiple signatures, and each of them can fail in various ways (general error, NONE, TEMPFAIL, PERMFAIL).

This library merely aims to facilitate parsing & checking of DKIM keys & signatures etc., but the decision of which signatures and verification states to honour, rely and act upon is up the consumer. If you're just interested in a simple boolean, the following would be the simplest it can offer at this time:

DKIM.verify( message, ( error, results ) => {

  if( error ) {
    // This should only happen should something go fundamentally wrong,
    // for example because of the lack of an internet connection, lack of key / signature,
    // or Key / Signature syntax errors
  }

  // Whether all signatures check out
  var verified = results.every(( result ) => {
    return result.verified
  })

})

All of these things you touched on do need some improvement, and I'll probably work on dkim in the coming days / weeks to make it easier to work with and improve the documentation.

jhermsmeier / node-dkim

can you document `verify` method further? #6