@trstudios/discord-notify 1.0.1 → 1.2.1

package/README.md

@@ -47,6 +47,7 @@ const result = await sendMail(
   {
     from: { address: "noreply@example.com", name: "Example" },
     to: [{ address: "someone@example.com" }],
+    bcc: [{ address: "audit@example.com" }], // optional, as is cc
     replyTo: { address: "help@example.com" },
     subject: "Your report is ready",
     html: "<p>…</p>",
@@ -76,6 +77,36 @@ if (!result.ok) {
 
 Use `"none"` for messages that contain secrets, such as sign-in codes, password resets and invite links. Anyone who can read the alert channel can read whatever an alert includes.
 
+### Check delivery and alerts
+
+`sendTestMail` sends a short test email through the same path as real mail. With `fail: true`, it uses a deliberately invalid token instead, so the send fails and the failure alert fires. That checks the alert path without changing any configuration.
+
+`secretMatches` compares a request header with a configured secret in constant time. It returns `false` when either value is missing.
+
+Here's an example route, shown with Next.js, protected by an admin secret. It sends only to an address from configuration:
+
+```ts
+import { secretMatches, sendTestMail } from "@trstudios/discord-notify";
+
+export async function POST(request: Request) {
+  if (!secretMatches(request.headers.get("x-admin-token"), process.env.ADMIN_TOKEN)) {
+    return Response.json({ error: "Not allowed" }, { status: 403 });
+  }
+  const to = process.env.TEST_EMAIL_TO;
+  if (!to) return Response.json({ error: "TEST_EMAIL_TO is not set" }, { status: 500 });
+
+  const result = await sendTestMail({
+    from: { address: "noreply@example.com", name: "Example" },
+    to: [{ address: to }],
+    source: "example.com",
+    fail: new URL(request.url).searchParams.get("fail") === "1",
+  });
+  return Response.json(result, { status: result.ok ? 200 : 502 });
+}
+```
+
+Never take the recipient from the request. Otherwise anyone holding the admin secret could use the route to send mail to arbitrary addresses.
+
 ## Safety notes
 
 - **No pings:** alerts are posted with mentions disabled, so text in a message can't ping `@everyone` or a role.
@@ -95,7 +126,7 @@ npm run typecheck
 1. Bump `version` in `package.json` and commit.
 2. Push a matching tag, for example `git tag v1.0.1 && git push origin v1.0.1`.
 
-GitHub Actions then stages the release on npm through Trusted Publishing, with provenance. A maintainer approves it on npmjs.com to publish it.
+GitHub Actions then publishes it to npm through Trusted Publishing, with provenance.
 
 ## License
 

package/dist/notify.d.ts

@@ -42,6 +42,8 @@ export interface Address {
 export interface Mail {
     from: Address;
     to: Address[];
+    cc?: Address[];
+    bcc?: Address[];
     replyTo?: Address;
     subject: string;
     text?: string;
@@ -83,4 +85,24 @@ export declare function failureAlert(mail: Mail, error: string, level: AlertCont
  * still answer its own request.
  */
 export declare function sendMail(mail: Mail, options?: SendOptions): Promise<SendResult>;
+/**
+ * Compares a secret from a request header with the expected value in constant
+ * time. Returns false when either is missing, so an unset secret never matches.
+ */
+export declare function secretMatches(given: string | null | undefined, expected: string | undefined): boolean;
+export interface TestMailOptions extends SendOptions {
+    from: Address;
+    /** Where the test goes. Take it from configuration, never from the request. */
+    to: Address[];
+    /**
+     * Send with a deliberately invalid token, so the send fails and the failure
+     * alert fires. Checks the alert path without changing any configuration.
+     */
+    fail?: boolean;
+}
+/**
+ * Sends a short test email through the same path as real mail, to check
+ * delivery (or, with `fail`, the failure alert). Never throws.
+ */
+export declare function sendTestMail(options: TestMailOptions): Promise<SendResult>;
 export {};

package/dist/notify.js

@@ -2,7 +2,8 @@
 // Server-side only: it reads secrets from the environment. Never import it from
 // browser or app bundles.
 //
-// No dependencies; needs a global fetch (Node 18+, Bun, Deno).
+// No dependencies; needs a global fetch and node:crypto (Node 18+, Bun, Deno).
+import { createHash, timingSafeEqual } from "node:crypto";
 // Discord's limits for one embed.
 const TITLE_MAX = 256;
 const FIELD_NAME_MAX = 256;
@@ -73,10 +74,13 @@ export function maskEmail(address) {
     return `${address[0]}***${address.slice(at)}`;
 }
 const formatAddress = (a) => (a.name ? `${a.name} <${a.address}>` : a.address);
+const recipients = (list) => list.map((a) => ({ email_address: { address: a.address, name: a.name } }));
 function zeptoBody(mail) {
     return {
         from: { address: mail.from.address, name: mail.from.name },
-        to: mail.to.map((a) => ({ email_address: { address: a.address, name: a.name } })),
+        to: recipients(mail.to),
+        cc: mail.cc?.length ? recipients(mail.cc) : undefined,
+        bcc: mail.bcc?.length ? recipients(mail.bcc) : undefined,
         reply_to: mail.replyTo ? [{ address: mail.replyTo.address, name: mail.replyTo.name }] : undefined,
         subject: mail.subject,
         textbody: mail.text,
@@ -102,10 +106,18 @@ export function failureAlert(mail, error, level, source) {
     const fields = { Source: source, Error: error };
     if (level === "none") {
         fields.To = mail.to.map((a) => maskEmail(a.address)).join(", ");
+        if (mail.cc?.length)
+            fields.Cc = mail.cc.map((a) => maskEmail(a.address)).join(", ");
+        if (mail.bcc?.length)
+            fields.Bcc = mail.bcc.map((a) => maskEmail(a.address)).join(", ");
         return { title: "Email failed to send", fields };
     }
     fields.From = formatAddress(mail.from);
     fields.To = mail.to.map(formatAddress).join(", ");
+    if (mail.cc?.length)
+        fields.Cc = mail.cc.map(formatAddress).join(", ");
+    if (mail.bcc?.length)
+        fields.Bcc = mail.bcc.map(formatAddress).join(", ");
     fields["Reply-To"] = mail.replyTo && formatAddress(mail.replyTo);
     fields.Subject = mail.subject;
     if (level === "summary")
@@ -169,3 +181,38 @@ export async function sendMail(mail, options = {}) {
     });
     return { ok: false, error };
 }
+// ---------------------------------------------------------------------------
+// Delivery checks
+// ---------------------------------------------------------------------------
+/**
+ * Compares a secret from a request header with the expected value in constant
+ * time. Returns false when either is missing, so an unset secret never matches.
+ */
+export function secretMatches(given, expected) {
+    if (!given || !expected)
+        return false;
+    const a = createHash("sha256").update(given).digest();
+    const b = createHash("sha256").update(expected).digest();
+    return timingSafeEqual(a, b);
+}
+/**
+ * Sends a short test email through the same path as real mail, to check
+ * delivery (or, with `fail`, the failure alert). Never throws.
+ */
+export async function sendTestMail(options) {
+    const { from, to, fail, ...send } = options;
+    const when = new Date().toISOString();
+    const what = fail ? "Failure alert test" : "Delivery test";
+    return sendMail({
+        from,
+        to,
+        subject: `${what}${send.source ? ` (${send.source})` : ""}: ${when}`,
+        text: fail
+            ? `This send used a deliberately invalid token, so it should fail and raise an alert.\n\nSent ${when}.`
+            : `If you can read this, email from ${from.address} is being delivered.\n\nSent ${when}.`,
+    }, {
+        alertContent: "summary",
+        ...send,
+        ...(fail && { token: "invalid-token-for-failure-test" }),
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trstudios/discord-notify",
-  "version": "1.0.1",
+  "version": "1.2.1",
   "description": "Discord alerts for server-side failures, with a ZeptoMail sender that reports failed sends. No dependencies.",
   "keywords": [
     "discord",