mailauth/docs/dkim.md

Email authentication library for Node.js

# DKIM Verification Result Reference

This document describes the result object returned by `dkimVerify()`.

## Overview

The `dkimVerify` function verifies all DKIM-Signature headers in an email message and returns an object containing verification results for each signature.

```javascript
const { dkimVerify } = require('mailauth/lib/dkim/verify');

const result = await dkimVerify(message);
// result.results is an array of signature verification results
```

## Top-Level Result Object

| Field | Type | Description |
|-------|------|-------------|
| `headerFrom` | `string[]` | Array of email addresses from the From header |
| `envelopeFrom` | `string\|false` | Email address from Return-Path header or sender option |
| `results` | `object[]` | Array of verification results for each DKIM signature |

## Signature Result Object

Each entry in the `results` array has the following structure:

| Field | Type | Presence | Description |
|-------|------|----------|-------------|
| `id` | `string` | Always | SHA256 hash of signature value, or UUID if no signature |
| `signingDomain` | `string` | Signature exists | Domain from `d=` tag |
| `selector` | `string` | Signature exists | DKIM selector from `s=` tag |
| `signature` | `string` | Signature exists | Base64-encoded signature value from `b=` tag |
| `algo` | `string` | Signature exists | Signing algorithm (e.g., `"rsa-sha256"`, `"ed25519-sha256"`) |
| `format` | `string` | Signature exists | Canonicalization format from `c=` tag (e.g., `"relaxed/relaxed"`) |
| `bodyHash` | `string` | Signature exists | Calculated body hash (base64) |
| `bodyHashExpecting` | `string` | Signature exists | Expected body hash from `bh=` tag |
| `signingHeaders` | `object` | Signature exists | Signing header details (see below) |
| `status` | `object` | Always | Verification status (see below) |
| `signTime` | `string\|null` | Always | ISO 8601 timestamp from `t=` tag, or null |
| `expiresAfter` | `string\|null` | Always | ISO 8601 expiration from `x=` tag, or null |
| `signatureTimeValid` | `boolean` | Always | Whether signature is within validity window |
| `sourceBodyLength` | `number` | Body processed | Original body length in bytes |
| `canonBodyLength` | `number` | Body processed | Canonicalized bytes actually hashed |
| `canonBodyLengthTotal` | `number` | Body processed | Total canonicalized body length |
| `canonBodyLengthLimited` | `boolean` | Signature exists | Whether body length is limited by `l=` tag |
| `canonBodyLengthLimit` | `number` | `l=` tag present | Maximum body length from `l=` tag |
| `mimeStructureStart` | `number` | MIME detected | Position where MIME boundary structure starts |
| `publicKey` | `string` | Key retrieved | PEM-formatted public key |
| `modulusLength` | `number` | RSA key | RSA key length in bits |
| `rr` | `string` | DNS lookup done | Raw DNS TXT record value |
| `info` | `string` | Always | Formatted Authentication-Results header value |

### signingHeaders Object

| Field | Type | Description |
|-------|------|-------------|
| `keys` | `string[]` | List of header field names that were signed |
| `headers` | `string[]` | Raw header lines that were signed |
| `canonicalizedHeader` | `string` | Base64-encoded canonicalized header data |

### status Object

| Field | Type | Presence | Description |
|-------|------|----------|-------------|
| `result` | `string` | Always | Verification result code (see below) |
| `comment` | `string` | On error/info | Human-readable explanation |
| `aligned` | `string\|false` | DKIM signatures | DMARC-aligned domain, or false |
| `header` | `object` | Always | Signature header info |
| `policy` | `object` | Policy result | Policy violation details |
| `underSized` | `number` | Body limited | Number of unsigned bytes |

#### status.header Object

| Field | Type | Description |
|-------|------|-------------|
| `i` | `string\|false` | Signing domain with @ prefix (e.g., `"@example.com"`) |
| `s` | `string` | DKIM selector |
| `a` | `string` | Algorithm |
| `b` | `string` | First 8 characters of signature value |

## Result Values

| Result | Description |
|--------|-------------|
| `pass` | Signature verified successfully |
| `fail` | Signature verification failed (bad signature) |
| `neutral` | Signature could not be verified (missing key, expired, body hash mismatch) |
| `policy` | Signature failed policy check (e.g., weak key) |
| `temperror` | Temporary error (DNS failure) |
| `none` | Message not signed |

## Comment Values

Common values for `status.comment`:

| Comment | Description |
|---------|-------------|
| `"body hash did not verify"` | Calculated body hash does not match `bh=` tag |
| `"bad signature"` | Cryptographic signature verification failed |
| `"invalid expiration"` | Expiration timestamp is before signing timestamp |
| `"expired"` | Signature has expired (past `x=` timestamp) |
| `"no key"` | No DKIM key found in DNS |
| `"unknown key version"` | Unsupported key version in DNS record |
| `"unknown key type"` | Unsupported key type in DNS record |
| `"invalid public key"` | Public key in DNS record is malformed |
| `"DNS failure: {code}"` | DNS lookup failed with error code |
| `"message not signed"` | No DKIM-Signature headers found |

## Example Output

### Successful Verification

```json
{
  "headerFrom": ["sender@example.com"],
  "envelopeFrom": "sender@example.com",
  "results": [
    {
      "id": "a1b2c3d4e5f6...",
      "signingDomain": "example.com",
      "selector": "selector1",
      "signature": "dGhpcyBpcyBhIHNpZ25hdHVyZQ==",
      "algo": "rsa-sha256",
      "format": "relaxed/relaxed",
      "bodyHash": "YWJjZGVmZ2hpamtsbW5vcA==",
      "bodyHashExpecting": "YWJjZGVmZ2hpamtsbW5vcA==",
      "signingHeaders": {
        "keys": ["from", "to", "subject", "date"],
        "headers": ["From: sender@example.com", "..."],
        "canonicalizedHeader": "..."
      },
      "status": {
        "result": "pass",
        "aligned": "example.com",
        "header": {
          "i": "@example.com",
          "s": "selector1",
          "a": "rsa-sha256",
          "b": "dGhpcyBp"
        }
      },
      "signTime": "2024-01-15T10:30:00.000Z",
      "expiresAfter": null,
      "signatureTimeValid": true,
      "sourceBodyLength": 1024,
      "canonBodyLength": 1020,
      "canonBodyLengthTotal": 1020,
      "canonBodyLengthLimited": false,
      "publicKey": "-----BEGIN PUBLIC KEY-----\n...",
      "modulusLength": 2048,
      "rr": "v=DKIM1; k=rsa; p=...",
      "info": "dkim=pass header.i=@example.com header.s=selector1 header.a=rsa-sha256 header.b=\"dGhpcyBp\""
    }
  ]
}
```

### Failed Verification

```json
{
  "headerFrom": ["sender@example.com"],
  "envelopeFrom": "sender@example.com",
  "results": [
    {
      "id": "a1b2c3d4e5f6...",
      "signingDomain": "example.com",
      "selector": "selector1",
      "status": {
        "result": "neutral",
        "comment": "no key",
        "header": {
          "i": "@example.com",
          "s": "selector1",
          "a": "rsa-sha256",
          "b": "dGhpcyBp"
        }
      },
      "info": "dkim=neutral (no key) header.i=@example.com header.s=selector1 header.a=rsa-sha256 header.b=\"dGhpcyBp\""
    }
  ]
}
```

### Unsigned Message

```json
{
  "headerFrom": ["sender@example.com"],
  "envelopeFrom": "sender@example.com",
  "results": [
    {
      "status": {
        "result": "none",
        "comment": "message not signed"
      },
      "info": "dkim=none (message not signed)"
    }
  ]
}
```