@pidgeon-ai/sdk 1.28.0 → 1.30.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ the two would publish a release for every unrelated product deploy.
 Semver applies to **this package's own surface** — the exported names, the
 call shapes, the result shape — not to the API behind it.
 
+## 1.30.0 — `authentication.signature`
+
+A message carries `authentication.signature`: `pass` when it came from
+another Pidgeon address directly and its signed sender verified against the
+sending domain's key, null otherwise. Additive.
+
+## 1.29.0 — The signed-sender records
+
+Every domain's DNS records (`domainsGet`, `domainsCreate`, `domainsVerify`)
+gain two optional ones: `signing`, a TXT at `_post`, and `signing_host`, a
+CNAME at `post`. With both connected, mail from the domain carries a
+signature receivers can check against the domain's published keys. Every
+record gains `optional`, true for these two; they have their own `status`
+and never count towards whether the domain is configured. Additive.
+
 ## 1.28.0 — DNS hosts for subdomains, and why a record is waiting
 
 Every DNS record (`domainsGet`, `domainsCreate`, `domainsVerify`) gains

package/dist/index.d.cts

@@ -489,12 +489,16 @@ type Message = {
         [key: string]: string;
     };
     /**
-     * What the receiving transport said about the sending domain. Null means it did not report, not that the check failed — normal on outbound, and on inbound it is the difference between unknown and forged.
+     * What the receiving transport said about the sending domain. Null means it did not report, not that the check failed — normal on outbound, and on inbound it is the difference between unknown and forged. A `From:` is the sending domain's own word when `dmarc` or `signature` is `pass`.
      */
     authentication: {
         spf: string | null;
         dkim: string | null;
         dmarc: string | null;
+        /**
+         * `pass` when the message came from another Pidgeon address directly, and its signed sender verified against the sending domain's published key. Null on mail that came through SMTP, which DMARC speaks for instead.
+         */
+        signature: string | null;
     };
     /**
      * Who this message says it is from. A Pidgeon sender declares it on every message it sends; mail from ordinary email has only the address.
@@ -705,12 +709,16 @@ type AwaitedMessage = {
             [key: string]: string;
         };
         /**
-         * What the receiving transport said about the sending domain. Null means it did not report, not that the check failed — normal on outbound, and on inbound it is the difference between unknown and forged.
+         * What the receiving transport said about the sending domain. Null means it did not report, not that the check failed — normal on outbound, and on inbound it is the difference between unknown and forged. A `From:` is the sending domain's own word when `dmarc` or `signature` is `pass`.
          */
         authentication: {
             spf: string | null;
             dkim: string | null;
             dmarc: string | null;
+            /**
+             * `pass` when the message came from another Pidgeon address directly, and its signed sender verified against the sending domain's published key. Null on mail that came through SMTP, which DMARC speaks for instead.
+             */
+            signature: string | null;
         };
         /**
          * Who this message says it is from. A Pidgeon sender declares it on every message it sends; mail from ordinary email has only the address.
@@ -1302,7 +1310,7 @@ type DomainDetail = {
         priority: number | null;
         status: 'connected' | 'waiting' | 'incorrect' | 'not_required';
         /**
-         * Why `status` is what it is. `published`: correct in public DNS, waiting on the mail provider to confirm (DKIM; usually under an hour). `wrong_name`: our value is at `found_at` instead, often the zone typed twice. Null before the first check.
+         * Why `status` is what it is. `published`: correct in public DNS, waiting on the mail provider to confirm (DKIM; usually under an hour), or on its certificate (`signing_host`; usually ten minutes). `wrong_name`: our value is at `found_at` instead, often the zone typed twice. Null before the first check.
          */
         state: 'connected' | 'published' | 'missing' | 'wrong_value' | 'wrong_name' | 'not_required' | null;
         found: string | null;
@@ -1310,6 +1318,10 @@ type DomainDetail = {
          * Where `found` was read, when that was not `fqdn`.
          */
         found_at: string | null;
+        /**
+         * Not needed for mail: `signing` and `signing_host`, which let receivers check a signed sender from this domain. Its own `status`; never counted towards whether the domain is configured.
+         */
+        optional: boolean;
         description: string;
         checked_at: string | null;
     }>;
@@ -1338,7 +1350,7 @@ type DnsRecord = {
     priority: number | null;
     status: 'connected' | 'waiting' | 'incorrect' | 'not_required';
     /**
-     * Why `status` is what it is. `published`: correct in public DNS, waiting on the mail provider to confirm (DKIM; usually under an hour). `wrong_name`: our value is at `found_at` instead, often the zone typed twice. Null before the first check.
+     * Why `status` is what it is. `published`: correct in public DNS, waiting on the mail provider to confirm (DKIM; usually under an hour), or on its certificate (`signing_host`; usually ten minutes). `wrong_name`: our value is at `found_at` instead, often the zone typed twice. Null before the first check.
      */
     state: 'connected' | 'published' | 'missing' | 'wrong_value' | 'wrong_name' | 'not_required' | null;
     found: string | null;
@@ -1346,6 +1358,10 @@ type DnsRecord = {
      * Where `found` was read, when that was not `fqdn`.
      */
     found_at: string | null;
+    /**
+     * Not needed for mail: `signing` and `signing_host`, which let receivers check a signed sender from this domain. Its own `status`; never counted towards whether the domain is configured.
+     */
+    optional: boolean;
     description: string;
     checked_at: string | null;
 };
@@ -1376,7 +1392,7 @@ type Verification = {
         priority: number | null;
         status: 'connected' | 'waiting' | 'incorrect' | 'not_required';
         /**
-         * Why `status` is what it is. `published`: correct in public DNS, waiting on the mail provider to confirm (DKIM; usually under an hour). `wrong_name`: our value is at `found_at` instead, often the zone typed twice. Null before the first check.
+         * Why `status` is what it is. `published`: correct in public DNS, waiting on the mail provider to confirm (DKIM; usually under an hour), or on its certificate (`signing_host`; usually ten minutes). `wrong_name`: our value is at `found_at` instead, often the zone typed twice. Null before the first check.
          */
         state: 'connected' | 'published' | 'missing' | 'wrong_value' | 'wrong_name' | 'not_required' | null;
         found: string | null;
@@ -1384,6 +1400,10 @@ type Verification = {
          * Where `found` was read, when that was not `fqdn`.
          */
         found_at: string | null;
+        /**
+         * Not needed for mail: `signing` and `signing_host`, which let receivers check a signed sender from this domain. Its own `status`; never counted towards whether the domain is configured.
+         */
+        optional: boolean;
         description: string;
         checked_at: string | null;
     }>;

package/dist/index.d.ts

@@ -489,12 +489,16 @@ type Message = {
         [key: string]: string;
     };
     /**
-     * What the receiving transport said about the sending domain. Null means it did not report, not that the check failed — normal on outbound, and on inbound it is the difference between unknown and forged.
+     * What the receiving transport said about the sending domain. Null means it did not report, not that the check failed — normal on outbound, and on inbound it is the difference between unknown and forged. A `From:` is the sending domain's own word when `dmarc` or `signature` is `pass`.
      */
     authentication: {
         spf: string | null;
         dkim: string | null;
         dmarc: string | null;
+        /**
+         * `pass` when the message came from another Pidgeon address directly, and its signed sender verified against the sending domain's published key. Null on mail that came through SMTP, which DMARC speaks for instead.
+         */
+        signature: string | null;
     };
     /**
      * Who this message says it is from. A Pidgeon sender declares it on every message it sends; mail from ordinary email has only the address.
@@ -705,12 +709,16 @@ type AwaitedMessage = {
             [key: string]: string;
         };
         /**
-         * What the receiving transport said about the sending domain. Null means it did not report, not that the check failed — normal on outbound, and on inbound it is the difference between unknown and forged.
+         * What the receiving transport said about the sending domain. Null means it did not report, not that the check failed — normal on outbound, and on inbound it is the difference between unknown and forged. A `From:` is the sending domain's own word when `dmarc` or `signature` is `pass`.
          */
         authentication: {
             spf: string | null;
             dkim: string | null;
             dmarc: string | null;
+            /**
+             * `pass` when the message came from another Pidgeon address directly, and its signed sender verified against the sending domain's published key. Null on mail that came through SMTP, which DMARC speaks for instead.
+             */
+            signature: string | null;
         };
         /**
          * Who this message says it is from. A Pidgeon sender declares it on every message it sends; mail from ordinary email has only the address.
@@ -1302,7 +1310,7 @@ type DomainDetail = {
         priority: number | null;
         status: 'connected' | 'waiting' | 'incorrect' | 'not_required';
         /**
-         * Why `status` is what it is. `published`: correct in public DNS, waiting on the mail provider to confirm (DKIM; usually under an hour). `wrong_name`: our value is at `found_at` instead, often the zone typed twice. Null before the first check.
+         * Why `status` is what it is. `published`: correct in public DNS, waiting on the mail provider to confirm (DKIM; usually under an hour), or on its certificate (`signing_host`; usually ten minutes). `wrong_name`: our value is at `found_at` instead, often the zone typed twice. Null before the first check.
          */
         state: 'connected' | 'published' | 'missing' | 'wrong_value' | 'wrong_name' | 'not_required' | null;
         found: string | null;
@@ -1310,6 +1318,10 @@ type DomainDetail = {
          * Where `found` was read, when that was not `fqdn`.
          */
         found_at: string | null;
+        /**
+         * Not needed for mail: `signing` and `signing_host`, which let receivers check a signed sender from this domain. Its own `status`; never counted towards whether the domain is configured.
+         */
+        optional: boolean;
         description: string;
         checked_at: string | null;
     }>;
@@ -1338,7 +1350,7 @@ type DnsRecord = {
     priority: number | null;
     status: 'connected' | 'waiting' | 'incorrect' | 'not_required';
     /**
-     * Why `status` is what it is. `published`: correct in public DNS, waiting on the mail provider to confirm (DKIM; usually under an hour). `wrong_name`: our value is at `found_at` instead, often the zone typed twice. Null before the first check.
+     * Why `status` is what it is. `published`: correct in public DNS, waiting on the mail provider to confirm (DKIM; usually under an hour), or on its certificate (`signing_host`; usually ten minutes). `wrong_name`: our value is at `found_at` instead, often the zone typed twice. Null before the first check.
      */
     state: 'connected' | 'published' | 'missing' | 'wrong_value' | 'wrong_name' | 'not_required' | null;
     found: string | null;
@@ -1346,6 +1358,10 @@ type DnsRecord = {
      * Where `found` was read, when that was not `fqdn`.
      */
     found_at: string | null;
+    /**
+     * Not needed for mail: `signing` and `signing_host`, which let receivers check a signed sender from this domain. Its own `status`; never counted towards whether the domain is configured.
+     */
+    optional: boolean;
     description: string;
     checked_at: string | null;
 };
@@ -1376,7 +1392,7 @@ type Verification = {
         priority: number | null;
         status: 'connected' | 'waiting' | 'incorrect' | 'not_required';
         /**
-         * Why `status` is what it is. `published`: correct in public DNS, waiting on the mail provider to confirm (DKIM; usually under an hour). `wrong_name`: our value is at `found_at` instead, often the zone typed twice. Null before the first check.
+         * Why `status` is what it is. `published`: correct in public DNS, waiting on the mail provider to confirm (DKIM; usually under an hour), or on its certificate (`signing_host`; usually ten minutes). `wrong_name`: our value is at `found_at` instead, often the zone typed twice. Null before the first check.
          */
         state: 'connected' | 'published' | 'missing' | 'wrong_value' | 'wrong_name' | 'not_required' | null;
         found: string | null;
@@ -1384,6 +1400,10 @@ type Verification = {
          * Where `found` was read, when that was not `fqdn`.
          */
         found_at: string | null;
+        /**
+         * Not needed for mail: `signing` and `signing_host`, which let receivers check a signed sender from this domain. Its own `status`; never counted towards whether the domain is configured.
+         */
+        optional: boolean;
         description: string;
         checked_at: string | null;
     }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pidgeon-ai/sdk",
-  "version": "1.28.0",
+  "version": "1.30.0",
   "description": "Email inboxes for AI agents — TypeScript SDK for Pidgeon: create addresses, send, receive and reply.",
   "keywords": [
     "email",