fix(email): make team org invites more transactional (#732)

* fix(email): make team org invites more transactional

Use org-branded sender and subject instead of the default
"Best from ClassroomIO" marketing identity. Include the inviter
name in the body, remove promotional emojis, and thread optional
subject overrides through the email job pipeline.

Co-authored-by: Rotimi Best <[email protected]>

* fix(email): escape invite fields and sanitize email headers

Address Greptile review: escape inviter/org/role values in the team
invite template, sanitize display names in buildEmailFromName, and
strip control characters from dynamic subjects.

Co-authored-by: Rotimi Best <[email protected]>

* fix(email): use RFC 5322 backslash escaping in display names

Co-authored-by: Rotimi Best <[email protected]>

* test(email): add vitest coverage for email header helpers

Cover escapeHtml, sanitizeEmailDisplayName, sanitizeEmailSubject, and
buildEmailFromName. Collapse repeated whitespace when stripping control
characters from header values.

Co-authored-by: Rotimi Best <[email protected]>

* fix(email): strip all ASCII control chars from email headers

Co-authored-by: Rotimi Best <[email protected]>

---------

Co-authored-by: Cursor Agent <[email protected]>
Co-authored-by: Rotimi Best <[email protected]>

packages/email/package.json

@@ -10,7 +10,9 @@
   "scripts": {
     "build": "tsc && tsc-alias",
     "dev": "tsc --watch",
-    "format": "prettier --write \"src/**/*.ts\""
+    "format": "prettier --write \"src/**/*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "exports": {
     ".": {
@@ -42,6 +44,7 @@
     "prettier": "^3.2.5",
     "tsc-alias": "^1.8.16",
     "tsx": "^4.7.1",
-    "typescript": "^5.5.2"
+    "typescript": "^5.5.2",
+    "vitest": "^1.2.2"
   }
 }

packages/email/src/emails/invite-teacher.ts

@@ -3,26 +3,38 @@ import * as z from 'zod';
 import { defineEmail } from '../send';
 import { getDefaultTemplate } from '../templates';
 import { ZEmailBranding } from '../core/branding';
+import { escapeHtml } from '../utils/functions/email-helpers';
 
 export const inviteTeacherEmail = defineEmail({
   id: 'inviteTeacher',
-  subject: 'Join us on ClassroomIO 😃',
+  subject: 'You have been invited to join an organization on ClassroomIO',
   schema: z.object({
     email: z.string().email(),
     orgName: z.string().min(1),
     orgSiteName: z.string().min(1),
     roleName: z.string().min(1),
+    inviterName: z.string().min(1).optional(),
     expiresAt: z.string().min(1),
     inviteLink: z.url(),
     branding: ZEmailBranding
   }),
   render: (fields) => {
+    const orgName = escapeHtml(fields.orgName);
+    const roleName = escapeHtml(fields.roleName);
+    const inviterName = fields.inviterName ? escapeHtml(fields.inviterName) : undefined;
+    const inviteLink = escapeHtml(fields.inviteLink);
+    const expiresAt = escapeHtml(fields.expiresAt);
+
+    const invitationLine = inviterName
+      ? `<p><strong>${inviterName}</strong> invited you to join <strong>${orgName}</strong> on ClassroomIO as ${roleName}.</p>`
+      : `<p>You have been invited to join <strong>${orgName}</strong> on ClassroomIO as ${roleName}.</p>`;
+
     const content = `
-      <p>Hey there,</p>
-      <p>You have been invited to join ${fields.orgName} on ClassroomIO as ${fields.roleName} 🎉🎉🎉.</p>
-      <p>This invite expires on ${fields.expiresAt} (UTC).</p>
+      <p>Hi there,</p>
+      ${invitationLine}
+      <p>This invite expires on ${expiresAt} (UTC).</p>
       <div>
-        <a class="button" href="${fields.inviteLink}">Accept Invitation</a>
+        <a class="button" href="${inviteLink}">Accept Invitation</a>
       </div>
     `;
 

packages/email/src/index.ts

@@ -30,7 +30,7 @@ export type { EmailId, EmailSchemaFor } from './utils/types';
 
 // Re-export low-level utilities
 export { deliverEmail } from './send';
-export { buildEmailFromName } from './utils/functions/email-helpers';
+export { buildEmailFromName, escapeHtml, sanitizeEmailSubject } from './utils/functions/email-helpers';
 export { getDefaultTemplate } from './templates/default';
 export { buildEmailBranding, resolveThemeColor, ZEmailBranding } from './core/branding';
 export { buildSessionIcs, type SessionIcsInput } from './ics';

packages/email/src/utils/functions/email-helpers.ts

@@ -1,6 +1,36 @@
 import { FromData } from '../types';
 import { EMAIL_FROM } from '../constants';
 
+const EMAIL_HEADER_CONTROL_CHARS = /[\x00-\x1F\x7F]/g;
+
+function stripEmailHeaderControlChars(value: string): string {
+  return value.replace(EMAIL_HEADER_CONTROL_CHARS, ' ').replace(/\s+/g, ' ').trim();
+}
+
+/** Strip control chars and backslash-escape quotes for RFC 5322 quoted display names. */
+export function sanitizeEmailDisplayName(name: string): string {
+  const normalized = stripEmailHeaderControlChars(name);
+  if (!normalized) {
+    return '';
+  }
+
+  return normalized.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+/** Strip control chars that could break or inject email headers. */
+export function sanitizeEmailSubject(subject: string): string {
+  return stripEmailHeaderControlChars(subject);
+}
+
+export function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
 // format: "ClassroomIO Developers (via ClassroomIO.com)" <[email protected]>
 export function extractNameAndEmail(str: string): FromData | undefined {
   // Use regular expressions to match the name and email
@@ -28,5 +58,10 @@ export function buildEmailFromName(name?: string): string {
     return EMAIL_FROM;
   }
 
-  return `"${name}" <${fromData.email}>`;
+  const displayName = sanitizeEmailDisplayName(name);
+  if (!displayName) {
+    return EMAIL_FROM;
+  }
+
+  return `"${displayName}" <${fromData.email}>`;
 }

packages/email/tests/email-helpers.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildEmailFromName,
+  escapeHtml,
+  sanitizeEmailDisplayName,
+  sanitizeEmailSubject
+} from '../src/utils/functions/email-helpers';
+
+const DEFAULT_FROM = '"Best from ClassroomIO" <[email protected]>';
+
+describe('escapeHtml', () => {
+  it('escapes HTML metacharacters', () => {
+    expect(escapeHtml(`Tom & Jerry's "Lab"`)).toBe('Tom &amp; Jerry&#39;s &quot;Lab&quot;');
+    expect(escapeHtml('<img src=x onerror=alert(1)>')).toBe('&lt;img src=x onerror=alert(1)&gt;');
+  });
+});
+
+describe('sanitizeEmailDisplayName', () => {
+  it('strips control characters and trims whitespace', () => {
+    expect(sanitizeEmailDisplayName('  Acme\r\nAcademy\u0000  ')).toBe('Acme Academy');
+    expect(sanitizeEmailDisplayName('Acme\x01Academy\x7F')).toBe('Acme Academy');
+  });
+
+  it('backslash-escapes embedded quotes per RFC 5322 quoted-strings', () => {
+    expect(sanitizeEmailDisplayName('Alice "Admin" Academy')).toBe('Alice \\"Admin\\" Academy');
+  });
+
+  it('escapes backslashes before quotes', () => {
+    expect(sanitizeEmailDisplayName('Acme\\Corp "East"')).toBe('Acme\\\\Corp \\"East\\"');
+  });
+});
+
+describe('sanitizeEmailSubject', () => {
+  it('strips control characters and trims whitespace', () => {
+    expect(sanitizeEmailSubject('  Invite to Acme\r\n\rAcademy\u0000  ')).toBe('Invite to Acme Academy');
+    expect(sanitizeEmailSubject('Invite\x01to\x7FAcme')).toBe('Invite to Acme');
+  });
+
+  it('preserves quotes in subject text', () => {
+    expect(sanitizeEmailSubject('Join "Acme" today')).toBe('Join "Acme" today');
+  });
+});
+
+describe('buildEmailFromName', () => {
+  it('returns the default sender when name is missing or empty after sanitization', () => {
+    expect(buildEmailFromName()).toBe(DEFAULT_FROM);
+    expect(buildEmailFromName('')).toBe(DEFAULT_FROM);
+    expect(buildEmailFromName('\r\n\u0000')).toBe(DEFAULT_FROM);
+  });
+
+  it('wraps a plain display name in a quoted From header', () => {
+    expect(buildEmailFromName('Acme Academy (via ClassroomIO.com)')).toBe(
+      '"Acme Academy (via ClassroomIO.com)" <[email protected]>'
+    );
+  });
+
+  it('sanitizes embedded quotes in the display name', () => {
+    expect(buildEmailFromName('Alice "Admin" Academy (via ClassroomIO.com)')).toBe(
+      '"Alice \\"Admin\\" Academy (via ClassroomIO.com)" <[email protected]>'
+    );
+  });
+});

packages/email/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/**/*.test.ts']
+  }
+});

packages/jobs/src/payloads/emails.ts

@@ -12,6 +12,8 @@ export const ZSendTemplateEmailPayload = z.object({
   fields: z.record(z.string(), z.unknown()).default({}),
   from: z.string().optional(),
   replyTo: z.string().optional(),
+  /** Override the template's default subject (e.g. org-scoped transactional mail). */
+  subject: z.string().min(1).optional(),
   /** Optional iCalendar (.ics) body attached as a text/calendar part. */
   ics: z.string().optional()
 });

packages/storybook/src/templates/email/fixtures.ts

@@ -36,8 +36,8 @@ const COURSE_WELCOME_CONTENT = `
 `;
 
 const INVITE_TEACHER_CONTENT = `
-  <p>Hey there,</p>
-  <p>You have been invited to join <strong>Acme Coding School</strong> on ClassroomIO as <strong>Admin</strong> 🎉🎉🎉.</p>
+  <p>Hi there,</p>
+  <p><strong>Sarah Johnson</strong> invited you to join <strong>Acme Coding School</strong> on ClassroomIO as <strong>Admin</strong>.</p>
   <p>This invite expires on <strong>Jul 15, 2026</strong> (UTC).</p>
   <div><a class="button" href="#">Accept Invitation</a></div>
 `;