@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.11

package/dist/email/templates/safe-html.js

@@ -0,0 +1,235 @@
+"use strict";
+// =============================================================================
+// Safe HTML — escaping as the default path (issue #123, epic #109)
+// =============================================================================
+//
+// Email templates interpolate USER-CONTROLLED DATA into a document that is
+// then delivered to somebody else's inbox: display names chosen by the user,
+// email addresses, role labels, allowlist entries. Unescaped, that is HTML
+// injection with a delivery mechanism attached — and unlike an injection into
+// our own web app, the payload lands somewhere we do not control, cannot patch,
+// and cannot even observe.
+//
+// -----------------------------------------------------------------------------
+// THE MECHANISM, AND WHY IT IS A TAGGED TEMPLATE RATHER THAN A FUNCTION
+// -----------------------------------------------------------------------------
+//
+// #123 lists the options; this file is the one it recommends. The rule that
+// matters is not "escape user data" — everybody agrees with that — it is
+// WHICH ACTION IS THE ONE YOU GET BY DEFAULT.
+//
+// 1. **CHOSEN — a tagged template literal.** `html`<p>${name}</p>`` escapes
+//    every interpolation on the way in. Writing the template naturally is
+//    writing it safely; the author does not have to remember anything, and
+//    there is no per-interpolation decision to get wrong on the day the file
+//    is edited in a hurry. Emitting raw markup requires reaching for
+//    `SafeHtml.unsafeFromTrustedString`, which is longer to type, contains the
+//    word `unsafe`, and greps out of the tree in one command. The unsafe path
+//    is the one that costs effort — that is the whole design.
+//
+// 2. **REJECTED — `escapeHtml()` at every call site, enforced by review.**
+//    This is the status quo the reference implementation uses, and its failure
+//    mode is silent: a missing call produces working, correct-looking output
+//    for every name that contains no angle bracket, which is essentially all
+//    of them in development. The bug ships and is discovered by whoever sends
+//    themselves a display name of `<script>`. #123 makes the same point about
+//    #115's no-plaintext-egress rule: a rule enforced by structure holds, a
+//    rule enforced by review holds until someone is busy.
+//
+// 3. **REJECTED — sanitising the finished HTML document.** Wrong layer and
+//    wrong direction. A sanitiser has to guess which markup was intended by
+//    the template and which arrived in a display name; it cannot, because by
+//    then they are the same string. Escaping at interpolation time is the only
+//    point where that distinction still exists.
+//
+// -----------------------------------------------------------------------------
+// HOW THE TYPE SYSTEM CARRIES THE GUARANTEE
+// -----------------------------------------------------------------------------
+//
+// `SafeHtml` is a NOMINAL type: a class with a private field and a private
+// constructor. A plain `string` is not assignable to it, an object literal
+// shaped like it is not assignable to it, and it cannot be constructed from
+// outside this file except through the two named factories below. That is what
+// lets `renderLayout({ bodyHtml })` (layout.ts) take `SafeHtml` rather than
+// `string` — a body assembled by string concatenation does not typecheck, so
+// the compiler, not a reviewer, is what stops it.
+//
+// Fragments compose: interpolating a `SafeHtml` into another `html` template
+// inserts it verbatim rather than double-escaping it, so conditional blocks
+// and lists are built the obvious way.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SafeHtml = void 0;
+exports.escapeHtml = escapeHtml;
+exports.html = html;
+exports.safeUrl = safeUrl;
+/**
+ * HTML-escape a string for interpolation into email HTML.
+ *
+ * Prefer the {@link html} tag, which calls this for you. This is exported
+ * because #123 names it in the template contract and because it is
+ * occasionally needed on its own — building an attribute value inside a
+ * fragment that is already `SafeHtml`, for instance.
+ *
+ * `&` MUST BE REPLACED FIRST. Escaping it after `<` would turn the `&lt;` this
+ * function had just produced into `&amp;lt;`, which renders as the literal
+ * text `&lt;` in the recipient's client.
+ *
+ * The apostrophe is escaped as the numeric `&#39;` rather than `&apos;`: the
+ * named form is HTML5-only, and some mail clients still parse bodies with
+ * HTML4/XHTML rules where it is undefined.
+ *
+ * @extensionPoint hook
+ * @stability stable
+ */
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/**
+ * A fragment of markup that is known to be safe to emit verbatim.
+ *
+ * NOT AN INTERFACE, AND NOT A BRANDED STRING ALIAS, deliberately. The private
+ * `value` field makes this nominally typed: TypeScript's structural assignment
+ * cannot produce one from a `string` or from an object literal, so the only
+ * ways to obtain a `SafeHtml` are the {@link html} tag (which escapes) and
+ * {@link SafeHtml.unsafeFromTrustedString} (which does not, and says so).
+ *
+ * The constructor is private so that `new SafeHtml(userInput)` is not a third,
+ * unnamed escape hatch sitting next to the two documented ones.
+ *
+ * @extensionPoint hook
+ * @stability stable
+ */
+class SafeHtml {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+    /**
+     * Wrap a string that is ALREADY safe markup, emitting it with no escaping.
+     *
+     * THIS IS THE ESCAPE HATCH, and it is verbose on purpose — the argument in
+     * the header block is that the unsafe action should cost more keystrokes
+     * than the safe one, and be greppable in a security review
+     * (`grep -rn unsafeFromTrustedString`).
+     *
+     * The ONLY acceptable argument is markup that is literal in the source, or
+     * built entirely from literals. If any part of the string came from the
+     * database, a request body, an OAuth profile, or a settings blob, this call
+     * is a vulnerability — use the {@link html} tag instead, which handles the
+     * composition case natively by interpolating `SafeHtml` fragments verbatim.
+     */
+    static unsafeFromTrustedString(trusted) {
+        return new SafeHtml(trusted);
+    }
+    /**
+     * The empty fragment.
+     *
+     * Exists so a conditional block reads `cond ? html`...` : SafeHtml.EMPTY`
+     * rather than tempting the author into `cond ? html`...` : ''`, which would
+     * not typecheck, or into typing the whole body as `string`, which would
+     * defeat the mechanism.
+     */
+    static EMPTY = new SafeHtml('');
+    /** The underlying markup. */
+    toString() {
+        return this.value;
+    }
+}
+exports.SafeHtml = SafeHtml;
+/**
+ * Coerce one interpolated value to markup.
+ *
+ * `null` and `undefined` render as nothing rather than as the strings "null"
+ * and "undefined". Mailing a recipient the word "undefined" is a worse outcome
+ * than a missing clause, and optional template data is common enough
+ * (`inviterName`, `triggeredBy`) that the alternative would push a `?? ''`
+ * onto every such interpolation — another thing to remember, which is the
+ * habit this module exists to remove.
+ *
+ * Arrays are flattened and concatenated with no separator, so a list of
+ * `SafeHtml` rows interpolates as a block without a join at the call site.
+ */
+function renderValue(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (value instanceof SafeHtml)
+        return value.toString();
+    if (Array.isArray(value))
+        return value.map(renderValue).join('');
+    return escapeHtml(String(value));
+}
+/**
+ * Tagged template literal that escapes every interpolation.
+ *
+ * ```ts
+ * const body = html`<p>Hello, ${user.displayName}.</p>${optionalBlock}`;
+ * ```
+ *
+ * `user.displayName` is escaped; `optionalBlock`, being `SafeHtml`, is emitted
+ * verbatim. That asymmetry is the entire contract: values are data, fragments
+ * are markup, and the type decides which without the author choosing.
+ *
+ * NOTE THE ONE THING THIS DOES NOT DO: it escapes for HTML, and HTML escaping
+ * is not sufficient inside a `javascript:` URL or a `<style>`/`<script>` body.
+ * Email templates contain neither — layout.ts explains why there is no
+ * `<style>` block — and URLs go through {@link safeUrl}, which rejects every
+ * scheme that could carry code.
+ *
+ * @extensionPoint hook
+ * @stability stable
+ */
+function html(strings, ...values) {
+    let out = strings[0] ?? '';
+    for (let i = 0; i < values.length; i++) {
+        out += renderValue(values[i]) + (strings[i + 1] ?? '');
+    }
+    return SafeHtml.unsafeFromTrustedString(out);
+}
+/**
+ * Schemes a link in an email may use.
+ *
+ * An allowlist, not a denylist of `javascript:`/`data:`: the set of URL
+ * schemes is open-ended and a denylist is one obscure scheme away from being
+ * wrong, whereas the set of schemes a transactional email legitimately needs
+ * is these three and has been for decades.
+ */
+const ALLOWED_URL_SCHEMES = new Set(['http:', 'https:', 'mailto:']);
+/**
+ * Validate a URL for use in an `href`, returning `null` if it is unusable.
+ *
+ * WHY THIS EXISTS SEPARATELY FROM ESCAPING: {@link escapeHtml} stops a value
+ * from breaking OUT of an attribute, which is the injection this module is
+ * mainly about. It does nothing about a value that stays inside the attribute
+ * and is hostile there — `javascript:...` is perfectly well-formed once
+ * escaped. Escaping and scheme-checking are two different jobs and only one of
+ * them can be done by the `html` tag, which cannot know it is looking at a URL.
+ *
+ * RELATIVE URLS ARE REJECTED TOO, and that is not incidental strictness. An
+ * email has no document base to resolve against, so a relative href is already
+ * broken for every recipient — catching it here turns a dead link in somebody's
+ * inbox into a visible absence at render time.
+ *
+ * Returns `null` rather than a placeholder such as `#`: callers (see the CTA
+ * handling in layout.ts) drop the link entirely, because a button that
+ * silently goes nowhere is harder to diagnose than a button that is not there.
+ *
+ * @extensionPoint hook
+ * @stability stable
+ */
+function safeUrl(value) {
+    try {
+        const parsed = new URL(value);
+        return ALLOWED_URL_SCHEMES.has(parsed.protocol) ? value : null;
+    }
+    catch {
+        // Not parseable as an absolute URL. Includes the relative-URL case above.
+        return null;
+    }
+}
+//# sourceMappingURL=safe-html.js.map

package/dist/email/templates/safe-html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-html.js","sourceRoot":"","sources":["../../../src/email/templates/safe-html.ts"],"names":[],"mappings":"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"}

package/dist/email/templates/test-email.email.d.ts

@@ -0,0 +1,46 @@
+import type { EmailProviderKind } from '../email-settings.schema';
+import { type EmailRenderContext } from './render-context';
+import { type RenderedEmail } from './email-template.types';
+/**
+ * Everything the test message renders.
+ *
+ * NOTE THE ABSENT CLOCK: `sentAt` is passed in rather than read from
+ * `new Date()` inside the template. A template that reads the clock is not a pure
+ * function of its input, which makes its output untestable without freezing
+ * time and makes "what exactly did we send?" unanswerable after the fact.
+ * Every template in this module follows the same rule.
+ *
+ * @stability experimental
+ */
+export interface TestEmailData {
+    /** Address the admin typed into the test form. Echoed back as a check. */
+    recipientEmail: string;
+    /** Transport that actually carried this message. The key diagnostic fact. */
+    providerKind: EmailProviderKind;
+    /** When the send was initiated. Rendered as UTC — see `formatTimestamp`. */
+    sentAt: Date;
+    /**
+     * Who pressed the button, if known — display name or email.
+     *
+     * Optional because the caller may not have it, not because it is
+     * decorative: on a system with several admins, "who triggered this" is the
+     * difference between a test and an unexplained message in an inbox.
+     */
+    triggeredBy?: string;
+    /**
+     * Absolute URL of the admin email settings page, for the CTA.
+     *
+     * PASSED IN, NOT BUILT HERE. A template that knows the web app's route table
+     * is a template that breaks silently when a route moves, and it would have
+     * to know `APP_URL` too — configuration a pure renderer has no business
+     * reading. #124 has both and supplies the finished URL.
+     */
+    settingsUrl?: string;
+}
+/**
+ * Render the test message.
+ *
+ * @stability experimental
+ */
+export declare function testEmail(data: TestEmailData, ctx?: EmailRenderContext): RenderedEmail;
+//# sourceMappingURL=test-email.email.d.ts.map

package/dist/email/templates/test-email.email.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-email.email.d.ts","sourceRoot":"","sources":["../../../src/email/templates/test-email.email.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAGlE,OAAO,EAA6B,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtF,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,wBAAwB,CAAC;AAwBhC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,cAAc,EAAE,MAAM,CAAC;IAEvB,6EAA6E;IAC7E,YAAY,EAAE,iBAAiB,CAAC;IAEhC,4EAA4E;IAC5E,MAAM,EAAE,IAAI,CAAC;IAEb;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAoCD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,CAAC,EAAE,kBAAkB,GAAG,aAAa,CA2FtF"}

package/dist/email/templates/test-email.email.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.testEmail = testEmail;
+const email_transport_1 = require("../transports/email-transport");
+const layout_1 = require("./layout");
+const render_context_1 = require("./render-context");
+const email_template_types_1 = require("./email-template.types");
+/**
+ * ISO 8601, in UTC, with the `Z` left on.
+ *
+ * NOT LOCALISED, deliberately. The server does not know the reader's time
+ * zone, and a locale-formatted timestamp with no offset ("31/08/2026, 14:05")
+ * is ambiguous in exactly the situation this email exists for — correlating a
+ * message against a log line or a delivery record, both of which are UTC.
+ * An unfamiliar format the reader can match against a log beats a familiar one
+ * they cannot.
+ */
+function formatTimestamp(value) {
+    return value.toISOString();
+}
+/**
+ * One row of the diagnostic fact table.
+ *
+ * `value` is interpolated through the `html` tag, so it is escaped — which
+ * matters here because `triggeredBy` is a display name that came from an OAuth
+ * profile and `recipientEmail` came straight off an admin form.
+ */
+function factRow(label, value) {
+    return (0, layout_1.html) `<tr>
+    <td
+      style="padding:6px 16px 6px 0;font-size:14px;line-height:20px;color:#4b5563;white-space:nowrap;vertical-align:top;"
+    >
+      ${label}
+    </td>
+    <td style="padding:6px 0;font-size:14px;line-height:20px;color:#1f2937;vertical-align:top;">
+      <strong>${value}</strong>
+    </td>
+  </tr>`;
+}
+/**
+ * Render the test message.
+ *
+ * @stability experimental
+ */
+function testEmail(data, ctx) {
+    const context = (0, render_context_1.resolveEmailRenderContext)(ctx);
+    const appName = context.appName;
+    const providerLabel = (0, email_transport_1.labelOfEmailTransport)(data.providerKind);
+    const timestamp = formatTimestamp(data.sentAt);
+    // The timestamp is IN THE SUBJECT, which looks like clutter and is not.
+    // Gmail and Outlook both thread on identical subject lines, so a second test
+    // send collapses into the first one's conversation and is easy to miss
+    // entirely — turning "I fixed the config and retried, nothing arrived" into
+    // a false negative at the exact moment the admin is trying to tell whether
+    // their change worked. Distinct subjects keep each attempt a separate row.
+    const subject = `Test email from ${appName} (${timestamp})`;
+    const facts = [
+        factRow('Provider', providerLabel),
+        factRow('Sent at', timestamp),
+        factRow('Delivered to', data.recipientEmail),
+    ];
+    if (data.triggeredBy) {
+        facts.push(factRow('Requested by', data.triggeredBy));
+    }
+    const bodyHtml = (0, layout_1.html) `
+    <p style="margin:0 0 16px 0;">
+      Your email configuration works. This message was sent by the
+      <strong>Send test email</strong> button on the admin email settings page,
+      and its arrival confirms the whole path — settings, credentials,
+      transport and delivery.
+    </p>
+    <p style="margin:0 0 8px 0;">Details of this send:</p>
+    <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="margin:0 0 20px 0;">
+      ${facts}
+    </table>
+    <p style="margin:0;font-size:13px;line-height:20px;color:#4b5563;">
+      Nobody else received this message, and no further email is sent as a
+      result of it.
+    </p>
+  `;
+    const htmlDocument = (0, layout_1.renderLayout)({
+        title: 'Your email configuration works',
+        // The preheader repeats the transport rather than the good news, because
+        // the inbox list is where an admin comparing two test sends is looking.
+        previewText: `Test message delivered via ${providerLabel} at ${timestamp}.`,
+        bodyHtml,
+        ctaLabel: data.settingsUrl ? 'Open email settings' : undefined,
+        ctaUrl: data.settingsUrl,
+    }, context);
+    // Hand-written, not stripped from the markup above. Same facts, same order,
+    // shaped for a reader with no HTML — see the note above `plainText` in
+    // layout.ts.
+    const factLines = [
+        `  Provider:      ${providerLabel}`,
+        `  Sent at:       ${timestamp}`,
+        `  Delivered to:  ${data.recipientEmail}`,
+    ];
+    if (data.triggeredBy) {
+        factLines.push(`  Requested by:  ${data.triggeredBy}`);
+    }
+    // Split so the leading element is a literal: `PlainTextOptions.lines` is a
+    // non-empty tuple, and an array literal whose length TypeScript cannot see
+    // (because of the spread) widens to `string[]` and stops satisfying it. That
+    // is the type doing its job — it is refusing an argument that might be empty.
+    const restLines = [
+        'Its arrival confirms the whole path: settings, credentials, transport and delivery.',
+        '',
+        'Details of this send:',
+        ...factLines,
+        '',
+        'Nobody else received this message, and no further email is sent as a result of it.',
+    ];
+    const text = (0, layout_1.plainText)({
+        title: 'Your email configuration works',
+        lines: [
+            'This message was sent by the "Send test email" button on the admin email settings page.',
+            ...restLines,
+        ],
+        ctaLabel: data.settingsUrl ? 'Open email settings' : undefined,
+        ctaUrl: data.settingsUrl,
+    }, context);
+    return {
+        subject,
+        html: htmlDocument,
+        text,
+        headers: { ...email_template_types_1.TRANSACTIONAL_EMAIL_HEADERS },
+    };
+}
+//# sourceMappingURL=test-email.email.js.map

package/dist/email/templates/test-email.email.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-email.email.js","sourceRoot":"","sources":["../../../src/email/templates/test-email.email.ts"],"names":[],"mappings":"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"}

package/dist/email/templates/user-welcome.email.d.ts

@@ -0,0 +1,47 @@
+import { type EmailRenderContext } from './render-context';
+import { type RenderedEmail } from './email-template.types';
+/**
+ * Everything the welcome message renders.
+ *
+ * NO CLOCK AND NO CONFIGURATION READ, per the rule stated on `TestEmailData`:
+ * a template is a pure function of this object. The absolute `appUrl` is
+ * supplied by the caller for the same reason — a template that built it would
+ * have to know both `APP_URL` and the web app's route table.
+ *
+ * @stability experimental
+ */
+export interface UserWelcomeEmailData {
+    /** The address the account was created under. Stated back as the fact it is. */
+    recipientEmail: string;
+    /**
+     * Display name from the OAuth profile, when the provider supplied one.
+     *
+     * Optional because Google does not guarantee it. Interpolated through the
+     * `html` tag, so it is ESCAPED — this string came from a third party's
+     * profile and is the most obviously attacker-influenced value in the
+     * payload.
+     */
+    recipientName?: string;
+    /**
+     * Roles the new account was given, as stored (`viewer`, `admin`).
+     *
+     * Rendered because "what can I actually do here?" is the only question a
+     * welcome message is uniquely placed to answer. May be empty — a seeding
+     * failure would produce that — in which case the sentence is omitted rather
+     * than rendered as an empty list.
+     */
+    roles: string[];
+    /**
+     * Absolute URL of the application root, for the CTA. Optional: with no
+     * `APP_URL` configured there is no honest link to offer, and the layout
+     * omits the button rather than rendering one that goes nowhere.
+     */
+    appUrl?: string;
+}
+/**
+ * Render the welcome message.
+ *
+ * @stability experimental
+ */
+export declare function userWelcomeEmail(data: UserWelcomeEmailData, ctx?: EmailRenderContext): RenderedEmail;
+//# sourceMappingURL=user-welcome.email.d.ts.map

package/dist/email/templates/user-welcome.email.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-welcome.email.d.ts","sourceRoot":"","sources":["../../../src/email/templates/user-welcome.email.ts"],"names":[],"mappings":"AACA,OAAO,EAA6B,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtF,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,wBAAwB,CAAC;AA0BhC;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACnC,gFAAgF;IAChF,cAAc,EAAE,MAAM,CAAC;IAEvB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAEhB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAiBD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,EAAE,GAAG,CAAC,EAAE,kBAAkB,GAAG,aAAa,CAwFpG"}

package/dist/email/templates/user-welcome.email.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.userWelcomeEmail = userWelcomeEmail;
+const layout_1 = require("./layout");
+const render_context_1 = require("./render-context");
+const email_template_types_1 = require("./email-template.types");
+/**
+ * Role names as a reader should see them.
+ *
+ * Stored names are lower-case identifiers (`admin`); an email is product copy,
+ * not a database dump. Shared with `role-changed.email.ts` would be the
+ * obvious move and is deliberately NOT made: these are two independent pieces
+ * of copy and a shared formatter is how one template's wording change silently
+ * edits another's.
+ */
+function formatRoles(roles) {
+    return roles
+        .map((role) => role.charAt(0).toUpperCase() + role.slice(1))
+        .join(', ');
+}
+/**
+ * Render the welcome message.
+ *
+ * @stability experimental
+ */
+function userWelcomeEmail(data, ctx) {
+    const context = (0, render_context_1.resolveEmailRenderContext)(ctx);
+    const appName = context.appName;
+    const greetingName = data.recipientName?.trim();
+    const roleList = data.roles.length > 0 ? formatRoles(data.roles) : null;
+    // No timestamp in the subject, unlike the test email. That one is sent
+    // repeatedly at an admin's request and must not thread; this one is sent
+    // exactly once per account, so there is nothing for it to collapse into.
+    const subject = `Welcome to ${appName}`;
+    const greeting = greetingName
+        ? (0, layout_1.html) `<p style="margin:0 0 16px 0;">Hello ${greetingName},</p>`
+        : layout_1.SafeHtml.EMPTY;
+    const rolesParagraph = roleList
+        ? (0, layout_1.html) `<p style="margin:0 0 16px 0;">
+        Your account has been given the <strong>${roleList}</strong> role. If
+        that is not the access you expected, ask an administrator to change it
+        — you will get an email when they do.
+      </p>`
+        : layout_1.SafeHtml.EMPTY;
+    const bodyHtml = (0, layout_1.html) `
+    ${greeting}
+    <p style="margin:0 0 16px 0;">
+      Your account on ${appName} has been created and is ready to use. You are
+      signed in with <strong>${data.recipientEmail}</strong>, and that is the
+      address to use every time you sign in.
+    </p>
+    ${rolesParagraph}
+    <p style="margin:0;font-size:13px;line-height:20px;color:#4b5563;">
+      This message is sent once, when an account is first created. You can turn
+      it off — along with the other notifications this application sends — in
+      your notification settings.
+    </p>
+  `;
+    const htmlDocument = (0, layout_1.renderLayout)({
+        title: `Welcome to ${appName}`,
+        // The preheader names the account rather than repeating the subject, which
+        // the inbox list already shows immediately to its left.
+        previewText: `Your account for ${data.recipientEmail} is ready.`,
+        bodyHtml,
+        ctaLabel: data.appUrl ? `Open ${appName}` : undefined,
+        ctaUrl: data.appUrl,
+    }, context);
+    // Hand-written, same facts in the same order. Not stripped from the markup
+    // above — see the note above `plainText` in layout.ts for why no such
+    // function exists in this module.
+    const lines = [];
+    if (greetingName) {
+        lines.push(`Hello ${greetingName},`, '');
+    }
+    lines.push(`Your account on ${appName} has been created and is ready to use.`, `You are signed in with ${data.recipientEmail}, and that is the address to use every time you sign in.`);
+    if (roleList) {
+        lines.push('', `Your account has been given the ${roleList} role. If that is not the access you expected,`, 'ask an administrator to change it — you will get an email when they do.');
+    }
+    lines.push('', 'This message is sent once, when an account is first created. You can turn it off,', 'along with the other notifications this application sends, in your notification settings.');
+    const text = (0, layout_1.plainText)({
+        title: `Welcome to ${appName}`,
+        // Split so the leading element is a literal: `PlainTextOptions.lines` is a
+        // non-empty tuple, and an array whose length TypeScript cannot see widens
+        // to `string[]` and stops satisfying it.
+        lines: [lines[0], ...lines.slice(1)],
+        ctaLabel: data.appUrl ? `Open ${appName}` : undefined,
+        ctaUrl: data.appUrl,
+    }, context);
+    return {
+        subject,
+        html: htmlDocument,
+        text,
+        headers: { ...email_template_types_1.TRANSACTIONAL_EMAIL_HEADERS },
+    };
+}
+//# sourceMappingURL=user-welcome.email.js.map

package/dist/email/templates/user-welcome.email.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-welcome.email.js","sourceRoot":"","sources":["../../../src/email/templates/user-welcome.email.ts"],"names":[],"mappings":"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"}

package/dist/email/testing/conformance.d.ts

@@ -0,0 +1,61 @@
+import type { ConformanceFinding, ConformanceSuite } from '../../testing/index';
+declare module '../../testing/index' {
+    interface PlatformConformanceSuiteOptions {
+        /** The email slice's suite: its options, or `false` to opt out. Registered by importing `@marinoscar/platform-api/email/testing`. */
+        email?: EmailConformanceOptions | false;
+    }
+}
+/**
+ * Options of the `email` suite.
+ *
+ * @stability experimental
+ */
+export interface EmailConformanceOptions {
+    /** Sample data for the app's own templates, by name, rendered by checks 2 and 3. */
+    readonly samples?: Readonly<Record<string, unknown>>;
+    /** Set when the app passed `registerDefaultTemplates: false`: check 1 is skipped. */
+    readonly withoutDefaultTemplates?: boolean;
+}
+/**
+ * Check 1: every platform template is registered.
+ *
+ * @param registered - the registered names.
+ * @returns one finding per missing platform template.
+ *
+ * @stability experimental
+ */
+export declare function checkPlatformEmailTemplates(registered: readonly string[]): ConformanceFinding[];
+/**
+ * Checks 2 and 3: each sampled template renders a complete message and
+ * escapes markup from its data.
+ *
+ * @param samples - sample data by template name.
+ * @returns one finding per problem.
+ *
+ * @stability experimental
+ */
+export declare function checkEmailTemplateRendering(samples: Readonly<Record<string, unknown>>): ConformanceFinding[];
+/**
+ * Check 4: neither the stored settings nor the admin response declares a
+ * secret-bearing field.
+ *
+ * @returns one finding per offending field.
+ *
+ * @stability experimental
+ */
+export declare function checkEmailSettingsSchemas(): ConformanceFinding[];
+/**
+ * The `email` conformance suite. Registered when
+ * `@marinoscar/platform-api/email/testing` is imported.
+ *
+ * @example
+ * ```ts
+ * import '@marinoscar/platform-api/email/testing';
+ * runPlatformConformance({ sourceRoots: [API_SOURCE_ROOT], suites: { email: { samples: { 'example-digest': digest } } } });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare const emailConformanceSuite: ConformanceSuite<EmailConformanceOptions>;
+//# sourceMappingURL=conformance.d.ts.map

package/dist/email/testing/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../../../src/email/testing/conformance.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAmB,kBAAkB,EAAqB,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAKpH,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,+BAA+B;QACvC,qIAAqI;QACrI,KAAK,CAAC,EAAE,uBAAuB,GAAG,KAAK,CAAC;KACzC;CACF;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,oFAAoF;IACpF,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,qFAAqF;IACrF,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;CAC5C;AAqBD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,kBAAkB,EAAE,CAK/F;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,kBAAkB,EAAE,CAsB5G;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,IAAI,kBAAkB,EAAE,CAShE;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,EAAE,gBAAgB,CAAC,uBAAuB,CA2C3E,CAAC"}