@sendora/sdk 1.1.0 → 2.1.0

package/src/types.ts

@@ -296,6 +296,112 @@ export interface MessagePage {
   next: string | null;
 }
 
+/** The body POST /v1/inbound/search takes. */
+export interface InboundSearchBody {
+  streamId?: string | undefined;
+  from?: string | undefined;
+  recipient?: string | undefined;
+  mailboxHash?: string | undefined;
+  receivedFrom?: string | undefined;
+  receivedTo?: string | undefined;
+  limit?: number | undefined;
+  after?: string | undefined;
+}
+
+/** The filters of a search over received mail; every one is optional. */
+export interface InboundSearch {
+  /** Messages received on this inbound stream of the server. */
+  streamId?: string | undefined;
+  /** Messages from this address, in the envelope or the From header. */
+  from?: string | undefined;
+  /** Messages sent to this address of yours. */
+  recipient?: string | undefined;
+  /** Messages whose address carried this text after the plus sign. */
+  mailboxHash?: string | undefined;
+  /** Accepted at or after this time. */
+  receivedFrom?: Date | string | undefined;
+  /** Accepted before this time. */
+  receivedTo?: Date | string | undefined;
+  /** Page size, 1 to 100; 50 when left out. */
+  limit?: number | undefined;
+  /** The `next` value of the previous page. */
+  after?: string | undefined;
+}
+
+/** An attachment of a received message, described; its bytes are `sendora.inbound.attachment`. */
+export interface InboundMessageAttachment {
+  attachmentId: string;
+  /** Its place among the message's attachments, from 0. */
+  position: number;
+  /** The filename, sanitised; null once the content is gone. */
+  name: string | null;
+  /** The type the sender declared; every download is served as application/octet-stream. */
+  contentType: string | null;
+  /** The Content-ID an HTML body refers to with `cid:`. */
+  contentId: string | null;
+  size: number;
+  /** True for a part shown in the body rather than offered as a file. */
+  inline: boolean;
+}
+
+/** A received message as the list shows it. */
+export interface InboundMessage {
+  inboundMessageId: string;
+  /** The inbound stream that received it. */
+  streamId: string;
+  /** When the message was accepted from the sending server. */
+  receivedAt: string;
+  /** The address of yours the message was sent to. */
+  envelopeRecipient: string;
+  /** The text after the plus sign in that address, when the sender used one. */
+  mailboxHash: string | null;
+  sizeBytes: number;
+  attachmentCount: number;
+  hasText: boolean;
+  hasHtml: boolean;
+  /** What the parser met, from a closed set; null when the message parsed clean. */
+  parseIssue: string | null;
+  authentication: InboundAuthentication;
+  /** False once the stream's content window has passed; only the reference remains. */
+  contentAvailable: boolean;
+  /** When the content goes. */
+  contentExpiresAt: string;
+  /** The From header; null without it or once the content is gone. */
+  from: InboundAddress | null;
+  subject: string | null;
+  /** The sender's Date header as ISO 8601, when it was a real moment. */
+  date: string | null;
+}
+
+/** The received message with everything but the attachment bytes. */
+export interface InboundMessageDetail extends InboundMessage {
+  /** The envelope sender; null for a bounce, or once the content is gone. */
+  envelope: { sender: string | null } | null;
+  replyTo: InboundAddress[];
+  /** Up to 100 entries; `toCount` is the whole number. */
+  to: InboundAddress[];
+  toCount: number;
+  cc: InboundAddress[];
+  ccCount: number;
+  messageIdHeader: string | null;
+  inReplyTo: string | null;
+  references: string[];
+  /** Every header in order; null once the content is gone. */
+  headers: InboundHeader[] | null;
+  /** The plain-text body; null without one or once the content is gone. */
+  text: string | null;
+  /** The HTML body as received; null without one or once the content is gone. */
+  html: string | null;
+  attachments: InboundMessageAttachment[];
+}
+
+/** One page of received messages, newest first. */
+export interface InboundPage {
+  messages: InboundMessage[];
+  /** Pass as `after` for the next page; null on the last. */
+  next: string | null;
+}
+
 /** Cursor paging for the lists that page. */
 export interface PageQuery {
   /** Page size, 1 to 1000; 100 when left out. */
@@ -480,13 +586,13 @@ export interface BroadcastPage {
 /** What `broadcasts.list` takes. */
 export type BroadcastList = PageQuery;
 
-/** The body POST /v1/tokens takes. */
+/** The body POST /v1/tokens and POST /v1/servers/{id}/tokens take. */
 export interface CreateTokenRequest {
   /** 1 to 100 characters, for people to tell tokens apart. */
   name: string;
 }
 
-/** A token of the server; its value is shown only when it is created. */
+/** A key of a server; its value is shown only when it is created. */
 export interface Token {
   tokenId: string;
   name: string;
@@ -496,7 +602,7 @@ export interface Token {
   revokedAt: string | null;
 }
 
-/** A token just created, with its value, shown this once. */
+/** A key just created, with its value, shown this once. */
 export interface CreatedToken extends Token {
   token: string;
 }
@@ -505,6 +611,37 @@ export interface TokenList {
   tokens: Token[];
 }
 
+/** A server of the account: an isolation boundary with its own keys, streams, log, suppressions and webhooks. */
+export interface Server {
+  /** The id every server key, stream and message of the server refers to. */
+  serverId: string;
+  /** The name given at creation, unique within the account. */
+  name: string;
+  createdAt: string;
+}
+
+/** A server just created, with its first key, whose value is shown this once. */
+export interface CreatedServer extends Server {
+  /** The server's first key, named default; its value is never shown again. */
+  token: CreatedToken;
+}
+
+export interface ServerList {
+  servers: Server[];
+}
+
+/** The body POST /v1/servers takes. */
+export interface CreateServerRequest {
+  /** 1 to 100 characters, unique within the account. */
+  name: string;
+}
+
+/** The body PATCH /v1/servers/{id} takes. */
+export interface UpdateServerRequest {
+  /** 1 to 100 characters, unique within the account. */
+  name: string;
+}
+
 /** The events a webhook can receive. */
 export type WebhookEventName =
   | 'delivered'
@@ -543,6 +680,19 @@ export interface Webhook {
   /** How the inbound event carries a received message: the parsed message, or a reference. */
   inboundContent: InboundContent;
   createdAt: string;
+  /** The live secrets, oldest first; every delivery is signed with each of them, the newest first in Sendora-Signature. */
+  secrets: WebhookSecret[];
+}
+
+/** A live signing secret of a webhook by id and age; its value was shown once when it was created. */
+export interface WebhookSecret {
+  secretId: string;
+  createdAt: string;
+}
+
+/** A secret just created, with its value, shown this once. */
+export interface CreatedWebhookSecret extends WebhookSecret {
+  secret: string;
 }
 
 /** A webhook just created, with its signing secret, shown this once. */
@@ -567,6 +717,8 @@ export interface Delivery {
   event: WebhookEventName;
   /** Null for an event about usage rather than a message. */
   messageId: string | null;
+  /** The received message an inbound event is about; null for every other event. */
+  inboundMessageId: string | null;
   status: DeliveryStatus;
   attempts: number;
   /** When the next attempt is due, while pending. */
@@ -598,7 +750,7 @@ export interface CreateDomainRequest {
 }
 
 /** A DNS record the domain needs and whether it has been seen. */
-export interface DnsRecord<Type extends 'CNAME' | 'TXT'> {
+export interface DnsRecord<Type extends 'CNAME' | 'TXT' | 'MX'> {
   type: Type;
   /** The name to create the record under. */
   host: string;
@@ -635,6 +787,43 @@ export interface DomainList {
   domains: SendingDomain[];
 }
 
+/** The body POST /v1/inbound/domains takes. */
+export interface CreateInboundDomainRequest {
+  /** An inbound stream of the server. */
+  streamId: string;
+  /** The domain to receive on, such as post.example.se. */
+  domain: string;
+}
+
+/** A domain on an inbound stream and the two records it needs. */
+export interface InboundDomain {
+  inboundDomainId: string;
+  /** The inbound stream the domain delivers to. */
+  streamId: string;
+  /** The domain, lower-cased and IDNA-encoded. */
+  domain: string;
+  /** True while both records are seen; only then is mail to the domain accepted. */
+  verified: boolean;
+  createdAt: string;
+  /** When the records were last looked up. */
+  lastCheckedAt: string | null;
+  /** When a verified domain lost its records. Mail to it is deferred for 72 hours from then and refused after, until the records are back. */
+  unverifiedAt: string | null;
+  /** The MX record that brings the domain's mail to Sendora, at any priority. */
+  mx: DnsRecord<'MX'>;
+  /** The TXT record that proves the claim; it carries a token only you were shown. */
+  txt: DnsRecord<'TXT'>;
+}
+
+/** The domain as it stands after a check, and what each lookup found. */
+export interface VerifiedInboundDomain extends InboundDomain {
+  check: { mx: RecordCheck; txt: RecordCheck };
+}
+
+export interface InboundDomainList {
+  domains: InboundDomain[];
+}
+
 /** What every event about a message carries. */
 export interface MessageEventFields {
   /** The delivery id. Deliveries arrive at least once, so key your handling on it. */
@@ -831,7 +1020,7 @@ export interface InboundEventContent {
 /**
  * A message received on an inbound stream. The content fields are present
  * for a webhook with `inboundContent: 'full'` and absent for
- * `reference`; `'contentOmitted' in event` tells them apart.
+ * `reference`; `event.contentOmitted !== undefined` tells them apart.
  */
 export type InboundEvent = InboundEventFields &
   (InboundEventContent | { contentOmitted?: undefined });

package/src/version.ts

@@ -1,2 +1,2 @@
 /** The package version, sent as the User-Agent; a test holds it equal to package.json. */
-export const SDK_VERSION = '1.1.0';
+export const SDK_VERSION = '2.1.0';

package/src/webhook-verify.ts

@@ -33,11 +33,13 @@ const decoder = new TextDecoder();
 
 /**
  * Checks a webhook request came from Sendora and answers its event, typed
- * by `event`. The header is `Sendora-Signature: t=<unix seconds>,v1=<hex>`,
- * the hex an HMAC-SHA256 with your secret over `<t>.<raw body>`; the
- * timestamp is inside the signed text, so a captured request cannot be
- * replayed after the tolerance. Throws `SendoraError` with
- * `invalid_signature` or `stale_signature`.
+ * by `event`. The header is `Sendora-Signature: t=<unix seconds>,v1=<hex>[,v1=<hex>]`,
+ * one hex per live secret of the webhook, each an HMAC-SHA256 with that
+ * secret over `<t>.<raw body>`; the one your secret produces is enough, so
+ * a secret being rolled in verifies as well as the old one. The timestamp
+ * is inside the signed text, so a captured request cannot be replayed
+ * after the tolerance. Throws `SendoraError` with `invalid_signature` or
+ * `stale_signature`.
  *
  * @example
  * const event = await verifyWebhook({
@@ -72,36 +74,55 @@ export async function verifyWebhook(input: VerifyWebhookInput): Promise<WebhookE
     false,
     ['verify'],
   );
-  if (!(await crypto.subtle.verify('HMAC', key, signature.mac, signed))) {
-    throw invalidSignature('The signature does not match the body.');
+  // Every signature is checked, so the time taken says nothing about which one matched.
+  let matched = false;
+  for (const mac of signature.macs) {
+    matched = (await crypto.subtle.verify('HMAC', key, mac, signed)) || matched;
+  }
+  if (!matched) {
+    throw invalidSignature('No signature in the header matches the body under this secret.');
   }
   return parseEvent(decoder.decode(body));
 }
 
+/** The timestamp and every `v1` value, one per live secret of the webhook. */
 function parseSignature(header: string | null | undefined): {
   timestamp: number;
-  mac: Uint8Array<ArrayBuffer>;
+  macs: Uint8Array<ArrayBuffer>[];
 } {
   if (typeof header !== 'string' || header === '') {
     throw invalidSignature('The request carries no Sendora-Signature header.');
   }
-  const parts = new Map<string, string>();
+  let timestamp: number | undefined;
+  const macs: Uint8Array<ArrayBuffer>[] = [];
   for (const part of header.split(',')) {
     const separator = part.indexOf('=');
-    if (separator > 0) {
-      parts.set(part.slice(0, separator).trim(), part.slice(separator + 1).trim());
+    if (separator <= 0) {
+      continue;
+    }
+    const name = part.slice(0, separator).trim();
+    const value = part.slice(separator + 1).trim();
+    if (name === 't') {
+      timestamp = Number(value);
+    } else if (name === 'v1') {
+      if (!MAC_HEX.test(value)) {
+        throw invalidSignature('The Sendora-Signature header is malformed.');
+      }
+      macs.push(bytesOf(value));
     }
   }
-  const timestamp = Number(parts.get('t'));
-  const hex = parts.get('v1');
-  if (!Number.isInteger(timestamp) || hex === undefined || !MAC_HEX.test(hex)) {
+  if (timestamp === undefined || !Number.isInteger(timestamp) || macs.length === 0) {
     throw invalidSignature('The Sendora-Signature header is malformed.');
   }
-  const mac = new Uint8Array(hex.length / 2);
-  for (let i = 0; i < mac.length; i += 1) {
-    mac[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return { timestamp, macs };
+}
+
+function bytesOf(hex: string): Uint8Array<ArrayBuffer> {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i += 1) {
+    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
   }
-  return { timestamp, mac };
+  return bytes;
 }
 
 function parseEvent(text: string): WebhookEvent {

package/src/webhooks.ts

@@ -2,6 +2,7 @@ import { paginate } from './pagination.ts';
 import type { Transport } from './transport.ts';
 import type {
   CreatedWebhook,
+  CreatedWebhookSecret,
   CreateWebhookRequest,
   Delivery,
   DeliveryPage,
@@ -74,6 +75,34 @@ export class WebhooksResource {
     });
   }
 
+  /**
+   * Adds a second live secret and answers its value once. Every delivery
+   * then carries one signature per live secret, the newest first, so
+   * switch your receiver to the new secret and delete the old one; a third
+   * is refused with `secret_limit`.
+   *
+   *
+   * const { secret, secretId } = await sendora.webhooks.createSecret(webhookId);
+   */
+  createSecret(webhookId: string, options: RequestOptions = {}): Promise<CreatedWebhookSecret> {
+    return this.#transport.request<CreatedWebhookSecret>({
+      method: 'POST',
+      path: `/v1/webhooks/${encodeURIComponent(webhookId)}/secrets`,
+      idempotent: false,
+      signal: options.signal,
+    });
+  }
+
+  /** Deletes a secret; deliveries are no longer signed with it. The last live secret is refused (`last_secret`). */
+  deleteSecret(webhookId: string, secretId: string, options: RequestOptions = {}): Promise<void> {
+    return this.#transport.request<undefined>({
+      method: 'DELETE',
+      path: `/v1/webhooks/${encodeURIComponent(webhookId)}/secrets/${encodeURIComponent(secretId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
   /**
    * One page of the events handed to the webhook, newest first, with the
    * outcome of the last attempt; `status` narrows to `pending`,