@tinvar/mail 0.0.0-stage → 0.4.1

package/src/context.js

@@ -0,0 +1,60 @@
+import { createContext, useContext } from 'react';
+import { DEFAULT_THEME, MailPolicyError } from './policy.js';
+
+/**
+ * What one render of one email is: whether this pass draws the HTML part or
+ * the plain-text one, the link policy PHP sent with the message, and the
+ * document the layout fills in -- its language, title and background, which
+ * renderEmail() writes into the <html> and <head> it puts around the body.
+ *
+ * A context, made afresh by each renderEmail() call, never module state: one
+ * renderer process draws every tenant's mail, and nothing of one message --
+ * its origin, its branding, its reader's name -- may be left where the next
+ * message's render would find it.
+ *
+ * The layout's dark palette goes there too, when it has one (ADR 0116):
+ * renderEmail() writes its `prefers-color-scheme` rule into the head, and
+ * every kit component marks what it colours with a class that rule names.
+ *
+ * @typedef {{ lang: string, title: string, background: string, dark: typeof DEFAULT_THEME | null }} MailDocument
+ * @typedef {{ text: boolean, policy: import('./policy.js').MailPolicy, document: MailDocument }} MailRender
+ */
+
+/** @type {import('react').Context<MailRender | null>} */
+export const RenderContext = createContext(/** @type {MailRender | null} */ (null));
+
+/** @type {import('react').Context<typeof DEFAULT_THEME>} */
+export const ThemeContext = createContext(DEFAULT_THEME);
+
+/**
+ * The render in hand. A kit component drawn outside renderEmail() has no
+ * policy to hold its links to, so it refuses rather than draw them unchecked.
+ *
+ * @returns {MailRender}
+ */
+export function useMailRender() {
+  const render = useContext(RenderContext);
+  if (render === null) {
+    throw new MailPolicyError(
+      '@tinvar/mail components render only inside renderEmail(), which holds their links.',
+    );
+  }
+  return render;
+}
+
+export function useTheme() {
+  return useContext(ThemeContext);
+}
+
+/**
+ * The class names a component marks an element with, so the dark palette's
+ * rule recolours it -- or none, when the layout has no dark palette and the
+ * markup should carry nothing it does not use.
+ *
+ * @param {MailRender} render
+ * @param {...string} tones e.g. 'text', 'surface', 'border'
+ * @returns {string | undefined}
+ */
+export function tones(render, ...tones) {
+  return render.document.dark === null ? undefined : tones.map((tone) => `tm-${tone}`).join(' ');
+}

package/src/index.d.ts

@@ -0,0 +1,127 @@
+import type { ReactElement, ReactNode } from 'react';
+
+/** Why a value was refused: a link, an image, a theme value or a prop the kit cannot draw safely. */
+export declare class MailPolicyError extends Error {}
+
+/** The colours and fonts a layout draws with: hex colours, plain font stacks. */
+export interface MailTheme {
+  background: string;
+  surface: string;
+  border: string;
+  text: string;
+  secondary: string;
+  muted: string;
+  accent: string;
+  button: string;
+  buttonText: string;
+  code: string;
+  codeText: string;
+  font: string;
+  mono: string;
+}
+
+/** Meridian's light palette, which a layout uses unless given a theme. */
+export declare const DEFAULT_THEME: Readonly<MailTheme>;
+
+/** Meridian's dark palette, which a layout given `dark` draws where the client prefers dark. */
+export declare const DEFAULT_DARK_THEME: Readonly<MailTheme>;
+
+/** A file the message carries, as PHP told the render: never its bytes. */
+export interface MailAttachment {
+  name: string;
+  type: string;
+  bytes: number;
+}
+
+/** What a render may link to and load images from: PHP's LinkPolicy, as the mail frame carries it. */
+export interface MailLinks {
+  origin: string | null;
+  images: readonly string[];
+  /** Origins a tracking image may load from, its query and all. */
+  tracking?: readonly string[];
+  /** The content ids of the images the message carries inline. */
+  inline?: readonly string[];
+  /** The files the message carries to be opened. */
+  attachments?: readonly MailAttachment[];
+}
+
+/** `href`, if a reader may follow it: https, on the message's origin, or mailto:. Throws otherwise. */
+export declare function safeHref(href: unknown, policy: Pick<MailLinks, 'origin'>): string;
+
+/** `src`, if a mail client may load it: on the message's origin or an allowed one, with no query, or `cid:` an inline image. Throws otherwise. */
+export declare function safeImageSrc(src: unknown, policy: MailLinks): string;
+
+/** `src`, if it is on an origin named for tracking images. Throws otherwise. */
+export declare function safeTrackerSrc(src: unknown, policy: Pick<MailLinks, 'tracking'>): string;
+
+export interface LayoutProps {
+  children?: ReactNode;
+  /** The line an inbox shows after the subject; hidden in the message. */
+  preview?: string;
+  /** Who the message is from, in its header. */
+  brand: string;
+  /** A hosted PNG, on the message's origin (MER-36.3). */
+  logoUrl?: string | null;
+  /** Why the reader is getting it: "Why am I getting this?" (MER-36.3). */
+  reason?: string | null;
+  /** Where the reader asks to stop these emails (MER-36.3). */
+  unsubscribeUrl?: string | null;
+  /** The words of that link; "Unsubscribe from these emails" unless given. */
+  unsubscribeLabel?: string;
+  /** The sender's postal address (MER-36.3). */
+  address?: string | null;
+  /** This message's branding, over the default: never shared with another message's render. */
+  theme?: Partial<MailTheme> | null;
+  /** What a client that prefers dark draws: true for the default dark palette, or colours over it. */
+  dark?: boolean | Partial<MailTheme> | null;
+  /** The message's language tag; `en` unless given. */
+  lang?: string;
+  /** The document's <title>; the brand unless given. */
+  title?: string;
+}
+
+export declare function Layout(props: LayoutProps): ReactElement;
+
+export declare function Heading(props: { children?: ReactNode; level?: 1 | 2 | 3 }): ReactElement;
+
+export declare function Text(props: { children?: ReactNode; muted?: boolean }): ReactElement;
+
+export declare function Link(props: { href: string; children?: ReactNode }): ReactElement;
+
+/** A button, and its URL written out beneath it unless `fallback` is false. */
+export declare function Button(props: {
+  href: string;
+  children?: ReactNode;
+  fallback?: boolean;
+}): ReactElement;
+
+export declare function Rows(props: { rows: ReadonlyArray<readonly [ReactNode, ReactNode]> }): ReactElement;
+
+export declare function Table(props: {
+  head?: ReadonlyArray<ReactNode>;
+  rows: ReadonlyArray<ReadonlyArray<ReactNode>>;
+  align?: ReadonlyArray<'left' | 'right' | 'center'>;
+}): ReactElement;
+
+export declare function Code(props: { children?: ReactNode }): ReactElement;
+
+/** A rule between parts of the message; in the text part, `---` and a blank line, as a string. */
+export declare function Divider(): ReactElement | string;
+
+export declare function List(props: { items: ReadonlyArray<ReactNode> }): ReactElement;
+
+/** One pixel from an origin the Email names for tracking, its query and all; nothing in the text part. */
+export declare function Tracker(props: { src: string }): ReactElement | null;
+
+/** What the message carries to be opened, by name and size, as PHP told the render. */
+export declare function Attachments(props: { label?: string }): ReactElement | null;
+
+/** An image from the message's origin or an allowed one, or `cid:` one it carries inline, 8 to 1200 pixels each way; nothing in the text part when its alt is empty. */
+export declare function Image(props: {
+  src: string;
+  alt: string;
+  width: number;
+  height: number;
+}): ReactElement | null;
+
+export declare function Section(props: { children?: ReactNode }): ReactElement;

package/src/index.js

@@ -0,0 +1,31 @@
+// @tinvar/mail: the framework's email kit (ADR 0086).
+//
+// Components a template is built from, drawn by the renderer into an HTML
+// part mail clients read and a plain-text part with every link spelled out;
+// renderEmail() and createMailRenderer() from '@tinvar/mail/render' draw
+// them, in the ssr environment.
+
+export {
+  Attachments,
+  Button,
+  Code,
+  Divider,
+  Heading,
+  Image,
+  Layout,
+  Link,
+  List,
+  Rows,
+  Section,
+  Table,
+  Text,
+  Tracker,
+} from './components.js';
+export {
+  DEFAULT_DARK_THEME,
+  DEFAULT_THEME,
+  MailPolicyError,
+  safeHref,
+  safeImageSrc,
+  safeTrackerSrc,
+} from './policy.js';

package/src/policy.js

@@ -0,0 +1,317 @@
+// What an email may link to, load, and be styled with.
+//
+// An email is opened by a mail client that runs no script but follows
+// links, loads images and honours CSS, often before the reader has looked:
+// a `javascript:` or `data:` link, an image from an address that learns who
+// opened the message, or a style that fetches one, are each a way out of
+// the message the application meant to send. So the kit's components hold
+// every href, src and style value they write to these rules as they
+// render, and PHP holds the HTML to the same rules again before it sends
+// it (Tinvar\Mail\LinkPolicy, Tinvar\Mail\SafeMailHtml) -- the renderer is
+// not trusted to have done so.
+
+/** Why a value was refused: what was given, and the rule it broke. */
+export class MailPolicyError extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message);
+    this.name = 'MailPolicyError';
+  }
+}
+
+/** Whitespace and control characters, which no URL the kit writes holds: a browser drops some inside a scheme. */
+const UNSAFE_CHARACTERS = /[\s\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
+
+/**
+ * An http origin on this machine -- localhost and below it, or a loopback
+ * address: the one plain-HTTP origin allowed, for an app served by `tinvar serve`.
+ */
+const LOOPBACK_ORIGIN =
+  /^http:\/\/(?:(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)*localhost|127(?:\.\d{1,3}){3}|\[::1\])(?::[1-9]\d{0,4})?$/;
+
+/** An https origin: a host and perhaps a port, no user, path, query or fragment. */
+const HTTPS_ORIGIN = /^https:\/\/(?:[^/:?#@[\]\s]+|\[[0-9a-f:.]+\])(?::[1-9]\d{0,4})?$/i;
+
+/**
+ * The policy a render was given: the message's canonical origin, from PHP's
+ * CanonicalOrigins (or an app's own on loopback), any further origins
+ * images may load from, the origins a tracking image may load from query
+ * and all, the content ids of the images the message carries inline, and
+ * the names, types and sizes of the files it carries (ADR 0116). Checked
+ * as it is read, so a malformed one refuses the render rather than letting
+ * everything, or nothing, through by accident.
+ *
+ * @typedef {{ name: string, type: string, bytes: number }} MailAttachment
+ * @typedef {{ origin: string | null, images: readonly string[], tracking: readonly string[], inline: readonly string[], attachments: readonly MailAttachment[] }} MailPolicy
+ *
+ * @param {unknown} links the frame's `links`, as PHP's LinkPolicy::toFrame() wrote it
+ * @returns {MailPolicy}
+ */
+export function policyOf(links) {
+  if (links === undefined || links === null) {
+    return Object.freeze({
+      origin: null,
+      images: Object.freeze([]),
+      tracking: Object.freeze([]),
+      inline: Object.freeze([]),
+      attachments: Object.freeze([]),
+    });
+  }
+  if (typeof links !== 'object' || Array.isArray(links)) {
+    throw new MailPolicyError("An email's link policy must be an object: { origin, images }.");
+  }
+  const {
+    origin = null,
+    images = [],
+    tracking = [],
+    inline = [],
+    attachments = [],
+  } = /** @type {{ origin?: unknown, images?: unknown, tracking?: unknown, inline?: unknown, attachments?: unknown }} */ (
+    links
+  );
+  if (origin !== null && (typeof origin !== 'string' || !isOrigin(origin))) {
+    throw new MailPolicyError(
+      `'${String(origin)}' is not an origin: https://host[:port], or http on loopback.`,
+    );
+  }
+  if (
+    !Array.isArray(images) ||
+    images.some((image) => typeof image !== 'string' || !HTTPS_ORIGIN.test(image))
+  ) {
+    throw new MailPolicyError('Images may only be allowed from https origins: https://host[:port].');
+  }
+  if (
+    !Array.isArray(tracking) ||
+    tracking.some((tracker) => typeof tracker !== 'string' || !HTTPS_ORIGIN.test(tracker))
+  ) {
+    throw new MailPolicyError(
+      'A tracking image may only be allowed from https origins: https://host[:port].',
+    );
+  }
+  if (!Array.isArray(inline) || inline.some((id) => typeof id !== 'string' || !CONTENT_ID.test(id))) {
+    throw new MailPolicyError("An inline image's content id is letters, digits, '.', '_' or '-'.");
+  }
+  if (
+    !Array.isArray(attachments) ||
+    attachments.some(
+      (file) =>
+        typeof file !== 'object' ||
+        file === null ||
+        typeof file.name !== 'string' ||
+        typeof file.type !== 'string' ||
+        !Number.isInteger(file.bytes) ||
+        file.bytes < 0,
+    )
+  ) {
+    throw new MailPolicyError("An email's attachments are described as { name, type, bytes }.");
+  }
+
+  return Object.freeze({
+    origin,
+    images: Object.freeze([...images]),
+    tracking: Object.freeze([...tracking]),
+    inline: Object.freeze([...inline]),
+    attachments: Object.freeze(
+      attachments.map((file) => Object.freeze({ name: file.name, type: file.type, bytes: file.bytes })),
+    ),
+  });
+}
+
+/** A content id, as a `cid:` URL names it unescaped. */
+const CONTENT_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+/** @param {string} origin */
+function isOrigin(origin) {
+  return HTTPS_ORIGIN.test(origin) || LOOPBACK_ORIGIN.test(origin);
+}
+
+/**
+ * Whether `url` is on `origin`: the origin itself, or a path, query or
+ * fragment after it -- never `https://shop.test.evil.example`, which merely
+ * starts with it.
+ *
+ * @param {string} url
+ * @param {string} origin
+ */
+function isOn(url, origin) {
+  const lower = url.toLowerCase();
+  const base = origin.toLowerCase();
+  if (!lower.startsWith(base)) return false;
+  const next = lower.charAt(base.length);
+  return next === '' || next === '/' || next === '?' || next === '#';
+}
+
+/**
+ * A link a reader may follow: any https URL, a URL on the message's own
+ * origin (http on loopback in dev), or a `mailto:` an address. Never
+ * `javascript:`, `data:`, `vbscript:`, a relative path -- which a mail
+ * client resolves against nothing the app controls -- or plain http
+ * elsewhere, which hands whatever the link carries to the network.
+ *
+ * @param {unknown} href
+ * @param {{ origin: string | null }} policy
+ * @returns {string} the href, unchanged
+ */
+export function safeHref(href, policy) {
+  if (typeof href !== 'string' || href === '' || UNSAFE_CHARACTERS.test(href)) {
+    throw new MailPolicyError(
+      `An email link must be a URL with no spaces or control characters; got '${String(href)}'.`,
+    );
+  }
+  if (/^mailto:/i.test(href)) {
+    if (/^mailto:[^@\s<>"(),;:\\[\]]+@[^@\s<>"(),;:\\[\]?]+(?:\?[^\s<>"]*)?$/i.test(href)) return href;
+    throw new MailPolicyError(`'${href}' is not a mailto: link to one address.`);
+  }
+  if (/^https:\/\/[^/?#\s]/i.test(href) && parses(href, 'https:')) return href;
+  if (policy.origin !== null && isOn(href, policy.origin) && parses(href, null)) return href;
+
+  throw new MailPolicyError(
+    `'${href}' cannot be linked to from an email: links are https, on the message's own origin, or mailto:.`,
+  );
+}
+
+/**
+ * An image a mail client may load: from the message's own origin or one the
+ * application allowed, with no query or fragment; or one the message
+ * carries inline, by a content id it declared (`cid:logo`).
+ *
+ * An image is fetched by the client when the message is opened, so an
+ * address that learns per recipient who opened what is a tracking pixel
+ * whatever its size; a static asset on the app's own origin is not. So an
+ * image is never from anywhere else unless the app says so, and never
+ * carries a query -- where a per-recipient id would go. A tracking image is
+ * Tracker's, from an origin named for it alone (safeTrackerSrc()).
+ *
+ * @param {unknown} src
+ * @param {{ origin: string | null, images: readonly string[], inline?: readonly string[] }} policy
+ * @returns {string}
+ */
+export function safeImageSrc(src, policy) {
+  if (typeof src === 'string' && /^cid:/i.test(src)) {
+    if ((policy.inline ?? []).includes(src.slice(4))) return src;
+    throw new MailPolicyError(`'${src}' names no image this message carries inline.`);
+  }
+  if (typeof src !== 'string' || src === '' || UNSAFE_CHARACTERS.test(src) || /[?#]/.test(src)) {
+    throw new MailPolicyError(
+      `An email image must be a URL with no spaces, query or fragment; got '${String(src)}'.`,
+    );
+  }
+  const allowed = [...(policy.origin === null ? [] : [policy.origin]), ...policy.images];
+  if (allowed.some((origin) => isOn(src, origin) && src.length > origin.length) && parses(src, null))
+    return src;
+
+  throw new MailPolicyError(
+    `'${src}' cannot be loaded by an email: images come from the message's own origin, or one the application allows.`,
+  );
+}
+
+/**
+ * A tracking image's URL: on an origin the application named for tracking
+ * (ADR 0116), where -- and only where -- an image may carry a query. Never
+ * a fragment, which no image needs.
+ *
+ * @param {unknown} src
+ * @param {{ tracking?: readonly string[] }} policy
+ * @returns {string}
+ */
+export function safeTrackerSrc(src, policy) {
+  if (typeof src !== 'string' || src === '' || UNSAFE_CHARACTERS.test(src) || src.includes('#')) {
+    throw new MailPolicyError(`A tracking image is a URL with no spaces or fragment; got '${String(src)}'.`);
+  }
+  const allowed = policy.tracking ?? [];
+  if (allowed.some((origin) => isOn(src, origin) && src.length > origin.length) && parses(src, 'https:'))
+    return src;
+
+  throw new MailPolicyError(
+    `'${src}' cannot be loaded as a tracking image: name its origin in the Email's tracking origins.`,
+  );
+}
+
+/** @param {string} url @param {string | null} protocol */
+function parses(url, protocol) {
+  try {
+    const parsed = new URL(url);
+    return (
+      (protocol === null || parsed.protocol === protocol) && parsed.username === '' && parsed.password === ''
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** A colour the theme may set: hex, nothing CSS could read as more than one value. */
+const COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+/** A font stack: names, quotes, spaces, commas and hyphens -- no `;`, `(` or `:`. */
+const FONT = /^[A-Za-z0-9 ,'"-]{1,200}$/;
+
+/**
+ * The colours and fonts a layout draws with, Meridian's light palette unless
+ * the app gives its own. Inline hex values: mail clients ignore classes and
+ * CSS variables (MER-36.1).
+ */
+export const DEFAULT_THEME = Object.freeze({
+  background: '#F7F7F5',
+  surface: '#FFFFFF',
+  border: '#E6E5E1',
+  text: '#111110',
+  secondary: '#5B5A56',
+  muted: '#72716C',
+  accent: '#2E63F0',
+  button: '#111110',
+  buttonText: '#FFFFFF',
+  code: '#111110',
+  codeText: '#D9D8D3',
+  font: "Inter, -apple-system, 'Segoe UI', Helvetica, Arial, sans-serif",
+  mono: "'Geist Mono', ui-monospace, Menlo, Consolas, monospace",
+});
+
+/**
+ * Meridian's dark palette, which a layout given `dark` switches to where the
+ * reader's client asks for dark (ADR 0116): by a `prefers-color-scheme`
+ * rule in the head, over the inline light colours, which a client that
+ * reads no <style> keeps.
+ */
+export const DEFAULT_DARK_THEME = Object.freeze({
+  ...DEFAULT_THEME,
+  background: '#111110',
+  surface: '#1A1A18',
+  border: '#2E2D2A',
+  text: '#EDEDEA',
+  secondary: '#B5B4AE',
+  muted: '#8F8E88',
+  accent: '#7FA2FF',
+  button: '#EDEDEA',
+  buttonText: '#111110',
+  code: '#0B0B0A',
+  codeText: '#D9D8D3',
+});
+
+/**
+ * The theme a layout was given, over the default, each value checked: a
+ * tenant's branding arrives as props, and a colour of `red;background:
+ * url(https://tracker.example/x)` would be a style that loads something.
+ *
+ * @param {unknown} theme
+ * @param {typeof DEFAULT_THEME} [base] what it is over: the light default unless given
+ * @returns {typeof DEFAULT_THEME}
+ */
+export function themeOf(theme, base = DEFAULT_THEME) {
+  if (theme === undefined || theme === null) return base;
+  if (typeof theme !== 'object' || Array.isArray(theme)) {
+    throw new MailPolicyError('An email theme must be an object of colours and fonts.');
+  }
+  /** @type {Record<string, string>} */
+  const merged = { ...base };
+  for (const [key, value] of Object.entries(theme)) {
+    if (value === undefined) continue;
+    if (!Object.hasOwn(DEFAULT_THEME, key)) {
+      throw new MailPolicyError(`'${key}' is not something an email theme sets.`);
+    }
+    const ok = typeof value === 'string' && (key === 'font' || key === 'mono' ? FONT : COLOR).test(value);
+    if (!ok) throw new MailPolicyError(`The email theme's ${key} cannot be '${String(value)}'.`);
+    merged[key] = value;
+  }
+
+  return /** @type {typeof DEFAULT_THEME} */ (Object.freeze(merged));
+}

package/src/preview.d.ts

@@ -0,0 +1,21 @@
+import type { Plugin } from 'vite';
+
+export interface MailPreviewOptions {
+  /** The module whose `renderMail(frame)` draws the app's emails, as createMailRenderer() makes it. */
+  templates: string;
+  /** A module whose default export takes the preview's origin and answers sample props by template name. */
+  previews: string;
+  /** The Vite environment both are loaded in; `ssr` unless given. */
+  environment?: string;
+  /** Where under the dev server's base the preview is served; `__mail` unless given. */
+  path?: string;
+}
+
+/** Sample props for each template, given the origin the preview is served on. */
+export type MailPreviews = (origin: string) => Record<string, object>;
+
+/** Throws where NODE_ENV, TINVAR_ENV or APP_ENV says production. */
+export declare function assertDevelopment(env?: Record<string, string | undefined>): void;
+
+/** The dev server's email preview; no part of a build, and refused in production. */
+export declare function mailPreview(options: MailPreviewOptions): Plugin;