@aglyn/tenant-data-admin 1.0.0-beta.143

package/src/lib/server/email-unsubscribe-link.d.ts

@@ -0,0 +1,174 @@
+/**
+ * @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 shared secret, or empty when the deployment has none.
+ *
+ * `CRON_SECRET` is the documented fallback, matching what the campaign sender
+ * and the unsubscribe handler already resolve. Read per call rather than at
+ * module load: these run in serverless handlers where the module may be
+ * evaluated during a build, long before the runtime env exists.
+ */
+export declare function unsubscribeLinkSecret(): string;
+/**
+ * The signed subject for an unsubscribe link.
+ *
+ * ## Two signed forms, and why the campaign id is additive
+ *
+ * Every email already sitting in an inbox carries a two-part signature over
+ * `hostId:email`, and those links must go on working forever — an unsubscribe
+ * link that stops honoring itself is the one bug in this area with a legal
+ * edge on it. So the campaign is appended only when it is present, and the
+ * verifier chooses which form to check by whether the link carries a `cid`.
+ *
+ * SIGNED rather than passed alongside. An unsigned `cid` would be an
+ * attribution anybody holding one valid link could point at any campaign they
+ * liked — a small forgery, and a completely gratuitous one, since the
+ * campaign is already known at the moment the link is minted.
+ */
+export declare function unsubscribeSignatureSubject(hostId: string, email: string, campaignId?: string, topicId?: string): string;
+/** HMAC for unsubscribe links; env-gated on the shared secret. */
+export declare function unsubscribeSignature(hostId: string, email: string, secret: string, campaignId?: string, topicId?: string): string;
+/**
+ * Whether a signature is this link's.
+ *
+ * Which form is checked is decided by the LINK, not by the signature: a link
+ * carrying no `cid` is checked against the two-part form and a link carrying
+ * one against the three-part form. There is no fallback between them, 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` onto a two-part link: the three-part check then fails.
+ *
+ * `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 declare function unsubscribeSignatureMatches(args: {
+    hostId: string;
+    email: string;
+    campaignId?: string;
+    signature: string;
+    secret: string;
+}): boolean;
+/**
+ * The purpose component that distinguishes a CONFIRMATION subject.
+ *
+ * See {@link confirmSignatureSubject}. Exported because the plugin's verifier
+ * imports it rather than restating the literal.
+ */
+export declare const CONFIRM_SUBJECT_PREFIX = "confirm";
+/**
+ * The signed subject for a double opt-in confirmation link.
+ *
+ * ## Why it is not one of the three forms above
+ *
+ * A confirmation names a host, an address and a topic, and it has NO
+ * campaign — nobody is unsubscribing from a message, they are joining a
+ * stream. The forms above refuse exactly that combination: a topic with no
+ * campaign would leave an empty middle component, and `host:email::t` is the
+ * same string as a three-part subject whose campaign id is `:t`.
+ *
+ * So it gets a leading PURPOSE component. That is a fourth form of the same
+ * scheme, not a second scheme: the digest, the secret and the comparison are
+ * unchanged.
+ *
+ * ## The one collision, and the guard for it
+ *
+ * `confirm:H:E:T` is byte-identical to the four-part unsubscribe subject
+ * `A:B:C:D` when the site's id is literally `confirm`, which would let one
+ * signature verify as both. Ids are not ours to constrain after the fact, so
+ * the subject is refused for that host rather than the collision being
+ * reasoned about: the cost is one unusable document id, and the alternative
+ * is a signature that means two things.
+ *
+ * @returns the subject, or `''` for a combination it cannot sign
+ *          unambiguously. Empty rather than a partial subject, so
+ *          {@link confirmSignature} yields no signature rather than one over
+ *          the empty string — which would verify for every other caller that
+ *          also produced one.
+ */
+export declare function confirmSignatureSubject(hostId: string, email: string, topicId: string): string;
+/** HMAC for a confirmation link; empty for an unsignable subject. */
+export declare function confirmSignature(hostId: string, email: string, topicId: string, secret: string): string;
+/**
+ * The absolute confirmation URL for one address and one topic.
+ *
+ * Minted where the signup happens, because the message carrying it is sent
+ * from there — and that message is TRANSACTIONAL, not marketing: the person
+ * just asked for this, so asking them to confirm it is the transaction they
+ * started. It carries no unsubscribe header for the same reason a receipt
+ * does not.
+ *
+ * Empty when there is no secret or no origin, for the reason
+ * {@link buildUnsubscribeUrl} gives: a link pointing at nothing is worse than
+ * no link, because the recipient believes they have confirmed.
+ */
+export declare function buildConfirmUrl(input: {
+    siteBase: string;
+    hostId: string;
+    email: string;
+    topicId: string;
+    /** Defaults to {@link unsubscribeLinkSecret} — the same signing secret. */
+    secret?: string;
+}): string;
+/**
+ * The absolute unsubscribe URL for one recipient of one site's mail.
+ *
+ * @returns the URL, or empty string when there is no secret to sign with or
+ *          no origin to resolve against. Empty rather than a half-built URL:
+ *          a caller can tell it does not have a link, and a link pointing at
+ *          nothing is worse than an absent header, because the recipient
+ *          believes they have unsubscribed.
+ */
+export declare function buildUnsubscribeUrl(input: {
+    siteBase: string;
+    hostId: string;
+    email: string;
+    /** The campaign this link rides in, when there is one. */
+    campaignId?: string;
+    /** The topic the message belonged to, when it belonged to one. */
+    topicId?: string;
+    /**
+     * Which of the two URLs over this one signature to build.
+     *
+     * `one-click` is what the `List-Unsubscribe` header names: a mailbox
+     * provider POSTs it with no human present and expects the act to have
+     * happened when it reads the 200, so it points at the route whose POST
+     * writes immediately and must never point at a page somebody has to submit.
+     * `preferences` is the link a PERSON clicks in the footer, where the topic
+     * this message belonged to is one of the things they can stop instead of
+     * all of it. Defaults to `one-click`, which is what a sender with no topic
+     * — every non-campaign marketing path — wants.
+     */
+    surface?: 'one-click' | 'preferences';
+    /** Defaults to {@link unsubscribeLinkSecret}. */
+    secret?: string;
+}): string;
+/**
+ * The signature of a payload for one purpose, base64url — or `''` when there
+ * is no secret, no purpose or no payload to sign, so a caller can tell it has
+ * no link rather than one that verifies for anybody.
+ */
+export declare function signedLinkSignature(purpose: string, payload: string, secret?: string): string;
+/** Whether a signature is this payload's, for this purpose, in constant time. */
+export declare function signedLinkSignatureMatches(args: {
+    purpose: string;
+    payload: string;
+    signature: string;
+    /** Defaults to {@link unsubscribeLinkSecret}. */
+    secret?: string;
+}): boolean;

package/src/lib/server/email-unsubscribe-link.js

@@ -0,0 +1,236 @@
+/**
+ * @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 UNSUBSCRIBE LINK — one signer, one URL shape, one verifier.
+ *
+ * A signed `/api/email/unsubscribe` URL was minted in exactly one place, the
+ * campaign sender, and verified in another, the unsubscribe handler. Two
+ * copies of an HMAC subject is a shape that only stays correct while nobody
+ * adds a third caller — and the marketing gate is the third caller, so the
+ * subject moved here and both existing sides now read it from one place.
+ *
+ * ## The address is lowercased in the subject AND in the URL
+ *
+ * This is the property that makes one derivation work rather than two that
+ * agree by luck. The campaign sender lowercases every address far upstream,
+ * so its links have always carried a lowercase address and its signature has
+ * always covered one; the handler's verifier does not lowercase, and did not
+ * need to. Marketing mail reaches addresses that no upstream step
+ * normalized — a checkout's `customerEmail`, a form payload's `email` — so a
+ * link minted over `Bob@Example.com` would sign the lowercase form and put
+ * the mixed-case form on the URL, and the verifier would answer 403 to a
+ * recipient pressing Unsubscribe.
+ *
+ * So {@link buildUnsubscribeUrl} writes the lowercased address into the query
+ * as well as into the subject, and the two agree by construction rather than
+ * by every caller remembering.
+ */ import { createHmac, timingSafeEqual } from "crypto";
+/**
+ * The shared secret, or empty when the deployment has none.
+ *
+ * `CRON_SECRET` is the documented fallback, matching what the campaign sender
+ * and the unsubscribe handler already resolve. Read per call rather than at
+ * module load: these run in serverless handlers where the module may be
+ * evaluated during a build, long before the runtime env exists.
+ */ export function unsubscribeLinkSecret() {
+    return process.env.EMAIL_UNSUBSCRIBE_SECRET || process.env.CRON_SECRET || '';
+}
+/**
+ * The signed subject for an unsubscribe link.
+ *
+ * ## Two signed forms, and why the campaign id is additive
+ *
+ * Every email already sitting in an inbox carries a two-part signature over
+ * `hostId:email`, and those links must go on working forever — an unsubscribe
+ * link that stops honoring itself is the one bug in this area with a legal
+ * edge on it. So the campaign is appended only when it is present, and the
+ * verifier chooses which form to check by whether the link carries a `cid`.
+ *
+ * SIGNED rather than passed alongside. An unsigned `cid` would be an
+ * attribution anybody holding one valid link could point at any campaign they
+ * liked — a small forgery, and a completely gratuitous one, since the
+ * campaign is already known at the moment the link is minted.
+ */ export function unsubscribeSignatureSubject(hostId, email, campaignId, topicId) {
+    const address = String(email != null ? email : '').trim().toLowerCase();
+    /*
+   * A colon in either id is refused outright, because the forms are joined
+   * with one. A four-part `host:email:c:t` is byte-identical to a three-part
+   * subject whose campaign id is `c:t`, so one signature would verify two
+   * different parameter tuples and a topic link could be re-presented as a
+   * campaign link with the topic spliced in. It costs nothing real: ids come
+   * from `createResourceUid()`, whose alphabet has no colon.
+   *
+   * A topic with no campaign DROPS the topic rather than producing a
+   * four-part subject with an empty middle, which would make
+   * `host:email::t` and a campaign id of `:t` the same string. The sender
+   * always has a campaign, so this is a guard rather than a path.
+   */ const campaign = String(campaignId != null ? campaignId : '');
+    const topic = String(topicId != null ? topicId : '');
+    if (campaign.includes(':') || topic.includes(':')) return '';
+    if (topic && campaign) return `${hostId}:${address}:${campaign}:${topic}`;
+    if (campaign) return `${hostId}:${address}:${campaign}`;
+    return `${hostId}:${address}`;
+}
+/** HMAC for unsubscribe links; env-gated on the shared secret. */ export function unsubscribeSignature(hostId, email, secret, campaignId, topicId) {
+    const subject = unsubscribeSignatureSubject(hostId, email, campaignId, topicId);
+    // An unsignable subject yields no signature rather than a signature over the
+    // empty string, which would verify for every caller that also passed one.
+    if (!subject) return '';
+    return createHmac('sha256', secret).update(subject).digest('hex');
+}
+/**
+ * Whether a signature is this link's.
+ *
+ * Which form is checked is decided by the LINK, not by the signature: a link
+ * carrying no `cid` is checked against the two-part form and a link carrying
+ * one against the three-part form. There is no fallback between them, 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` onto a two-part link: the three-part check then fails.
+ *
+ * `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 unsubscribeSignatureMatches(args) {
+    const expected = unsubscribeSignature(args.hostId, args.email, args.secret, args.campaignId || undefined);
+    return expected.length === args.signature.length && timingSafeEqual(new Uint8Array(Buffer.from(expected)), new Uint8Array(Buffer.from(args.signature)));
+}
+/**
+ * The purpose component that distinguishes a CONFIRMATION subject.
+ *
+ * See {@link confirmSignatureSubject}. Exported because the plugin's verifier
+ * imports it rather than restating the literal.
+ */ export const CONFIRM_SUBJECT_PREFIX = 'confirm';
+/**
+ * The signed subject for a double opt-in confirmation link.
+ *
+ * ## Why it is not one of the three forms above
+ *
+ * A confirmation names a host, an address and a topic, and it has NO
+ * campaign — nobody is unsubscribing from a message, they are joining a
+ * stream. The forms above refuse exactly that combination: a topic with no
+ * campaign would leave an empty middle component, and `host:email::t` is the
+ * same string as a three-part subject whose campaign id is `:t`.
+ *
+ * So it gets a leading PURPOSE component. That is a fourth form of the same
+ * scheme, not a second scheme: the digest, the secret and the comparison are
+ * unchanged.
+ *
+ * ## The one collision, and the guard for it
+ *
+ * `confirm:H:E:T` is byte-identical to the four-part unsubscribe subject
+ * `A:B:C:D` when the site's id is literally `confirm`, which would let one
+ * signature verify as both. Ids are not ours to constrain after the fact, so
+ * the subject is refused for that host rather than the collision being
+ * reasoned about: the cost is one unusable document id, and the alternative
+ * is a signature that means two things.
+ *
+ * @returns the subject, or `''` for a combination it cannot sign
+ *          unambiguously. Empty rather than a partial subject, so
+ *          {@link confirmSignature} yields no signature rather than one over
+ *          the empty string — which would verify for every other caller that
+ *          also produced one.
+ */ export function confirmSignatureSubject(hostId, email, topicId) {
+    const address = String(email != null ? email : '').trim().toLowerCase();
+    const host = String(hostId != null ? hostId : '');
+    const topic = String(topicId != null ? topicId : '');
+    if (!host || !address || !topic) return '';
+    if (host === CONFIRM_SUBJECT_PREFIX) return '';
+    if (host.includes(':') || topic.includes(':')) return '';
+    return `${CONFIRM_SUBJECT_PREFIX}:${host}:${address}:${topic}`;
+}
+/** HMAC for a confirmation link; empty for an unsignable subject. */ export function confirmSignature(hostId, email, topicId, secret) {
+    const subject = confirmSignatureSubject(hostId, email, topicId);
+    if (!subject || !secret) return '';
+    return createHmac('sha256', secret).update(subject).digest('hex');
+}
+/**
+ * The absolute confirmation URL for one address and one topic.
+ *
+ * Minted where the signup happens, because the message carrying it is sent
+ * from there — and that message is TRANSACTIONAL, not marketing: the person
+ * just asked for this, so asking them to confirm it is the transaction they
+ * started. It carries no unsubscribe header for the same reason a receipt
+ * does not.
+ *
+ * Empty when there is no secret or no origin, for the reason
+ * {@link buildUnsubscribeUrl} gives: a link pointing at nothing is worse than
+ * no link, because the recipient believes they have confirmed.
+ */ export function buildConfirmUrl(input) {
+    var _input_secret, _input_siteBase, _input_email;
+    const secret = (_input_secret = input.secret) != null ? _input_secret : unsubscribeLinkSecret();
+    const siteBase = String((_input_siteBase = input.siteBase) != null ? _input_siteBase : '').replace(/\/+$/, '');
+    const address = String((_input_email = input.email) != null ? _input_email : '').trim().toLowerCase();
+    const signature = confirmSignature(input.hostId, address, input.topicId, secret);
+    if (!siteBase || !signature) return '';
+    return `${siteBase}/api/email/confirm` + `?hostId=${encodeURIComponent(input.hostId)}` + `&email=${encodeURIComponent(address)}` + `&tid=${encodeURIComponent(input.topicId)}` + `&sig=${signature}`;
+}
+/**
+ * The absolute unsubscribe URL for one recipient of one site's mail.
+ *
+ * @returns the URL, or empty string when there is no secret to sign with or
+ *          no origin to resolve against. Empty rather than a half-built URL:
+ *          a caller can tell it does not have a link, and a link pointing at
+ *          nothing is worse than an absent header, because the recipient
+ *          believes they have unsubscribed.
+ */ export function buildUnsubscribeUrl(input) {
+    var _input_secret, _input_siteBase, _input_email;
+    const secret = (_input_secret = input.secret) != null ? _input_secret : unsubscribeLinkSecret();
+    const siteBase = String((_input_siteBase = input.siteBase) != null ? _input_siteBase : '').replace(/\/+$/, '');
+    const address = String((_input_email = input.email) != null ? _input_email : '').trim().toLowerCase();
+    if (!secret || !siteBase || !input.hostId || !address) return '';
+    const signature = unsubscribeSignature(input.hostId, address, secret, input.campaignId, input.topicId);
+    if (!signature) return '';
+    const route = input.surface === 'preferences' ? '/api/email/preferences' : '/api/email/unsubscribe';
+    return `${siteBase}${route}` + `?hostId=${encodeURIComponent(input.hostId)}` + `&email=${encodeURIComponent(address)}` + `&sig=${signature}` + (input.campaignId ? `&cid=${encodeURIComponent(input.campaignId)}` : '') + (input.topicId ? `&tid=${encodeURIComponent(input.topicId)}` : '');
+}
+/*==========================================
+ * A SIGNED LINK OF A SENDER'S OWN (AGL-2981).
+ *
+ * The forms above are the platform's own unsubscribe and confirmation
+ * links, each a subject over a site and an address. A sender that mails
+ * from somewhere else — a plugin sending from a person's own mailbox, whose
+ * link carries its own facts — signs its link here instead, over a payload
+ * of its own and under a PURPOSE of its own.
+ *
+ * The purpose is not a prefix of the subject, which is how the confirmation
+ * form had to guard a collision by hand. It selects the KEY: every purpose's
+ * links are signed with an HMAC key derived from the shared secret and the
+ * purpose, so a signature minted for one purpose verifies for no other and
+ * for none of the platform's own forms above, whatever the payloads spell.
+ * The secret, the digest and the constant-time comparison are the same.
+ *==========================================*/ /** The key one purpose's links are signed with: derived from the secret, bound to the purpose. */ function signedLinkKey(purpose, secret) {
+    return createHmac('sha256', secret).update(`aglyn-signed-link:${purpose}`).digest();
+}
+/**
+ * The signature of a payload for one purpose, base64url — or `''` when there
+ * is no secret, no purpose or no payload to sign, so a caller can tell it has
+ * no link rather than one that verifies for anybody.
+ */ export function signedLinkSignature(purpose, payload, secret = unsubscribeLinkSecret()) {
+    const name = String(purpose != null ? purpose : '').trim();
+    const body = String(payload != null ? payload : '');
+    if (!secret || !name || !body) return '';
+    return createHmac('sha256', signedLinkKey(name, secret)).update(body).digest('base64url');
+}
+/** Whether a signature is this payload's, for this purpose, in constant time. */ export function signedLinkSignatureMatches(args) {
+    var _args_secret, _args_signature;
+    const expected = signedLinkSignature(args.purpose, args.payload, (_args_secret = args.secret) != null ? _args_secret : unsubscribeLinkSecret());
+    const presented = String((_args_signature = args.signature) != null ? _args_signature : '');
+    return expected.length > 0 && expected.length === presented.length && timingSafeEqual(new Uint8Array(Buffer.from(expected)), new Uint8Array(Buffer.from(presented)));
+}
+
+//# sourceMappingURL=email-unsubscribe-link.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/email-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 UNSUBSCRIBE LINK — one signer, one URL shape, one verifier.\n *\n * A signed `/api/email/unsubscribe` URL was minted in exactly one place, the\n * campaign sender, and verified in another, the unsubscribe handler. Two\n * copies of an HMAC subject is a shape that only stays correct while nobody\n * adds a third caller — and the marketing gate is the third caller, so the\n * subject moved here and both existing sides now read it from one place.\n *\n * ## The address is lowercased in the subject AND in the URL\n *\n * This is the property that makes one derivation work rather than two that\n * agree by luck. The campaign sender lowercases every address far upstream,\n * so its links have always carried a lowercase address and its signature has\n * always covered one; the handler's verifier does not lowercase, and did not\n * need to. Marketing mail reaches addresses that no upstream step\n * normalized — a checkout's `customerEmail`, a form payload's `email` — so a\n * link minted over `Bob@Example.com` would sign the lowercase form and put\n * the mixed-case form on the URL, and the verifier would answer 403 to a\n * recipient pressing Unsubscribe.\n *\n * So {@link buildUnsubscribeUrl} writes the lowercased address into the query\n * as well as into the subject, and the two agree by construction rather than\n * by every caller remembering.\n */\n\nimport { createHmac, timingSafeEqual } from 'crypto'\n\n/**\n * The shared secret, or empty when the deployment has none.\n *\n * `CRON_SECRET` is the documented fallback, matching what the campaign sender\n * and the unsubscribe handler already resolve. Read per call rather than at\n * module load: these run in serverless handlers where the module may be\n * evaluated during a build, long before the runtime env exists.\n */\nexport function unsubscribeLinkSecret(): string {\n  return process.env.EMAIL_UNSUBSCRIBE_SECRET || process.env.CRON_SECRET || ''\n}\n\n/**\n * The signed subject for an unsubscribe link.\n *\n * ## Two signed forms, and why the campaign id is additive\n *\n * Every email already sitting in an inbox carries a two-part signature over\n * `hostId:email`, and those links must go on working forever — an unsubscribe\n * link that stops honoring itself is the one bug in this area with a legal\n * edge on it. So the campaign is appended only when it is present, and the\n * verifier chooses which form to check by whether the link carries a `cid`.\n *\n * SIGNED rather than passed alongside. An unsigned `cid` would be an\n * attribution anybody holding one valid link could point at any campaign they\n * liked — a small forgery, and a completely gratuitous one, since the\n * campaign is already known at the moment the link is minted.\n */\nexport function unsubscribeSignatureSubject(\n  hostId: string,\n  email: string,\n  campaignId?: string,\n  topicId?: string,\n): string {\n  const address = String(email ?? '')\n    .trim()\n    .toLowerCase()\n  /*\n   * A colon in either id is refused outright, because the forms are joined\n   * with one. A four-part `host:email:c:t` is byte-identical to a three-part\n   * subject whose campaign id is `c:t`, so one signature would verify two\n   * different parameter tuples and a topic link could be re-presented as a\n   * campaign link with the topic spliced in. It costs nothing real: ids come\n   * from `createResourceUid()`, whose alphabet has no colon.\n   *\n   * A topic with no campaign DROPS the topic rather than producing a\n   * four-part subject with an empty middle, which would make\n   * `host:email::t` and a campaign id of `:t` the same string. The sender\n   * always has a campaign, so this is a guard rather than a path.\n   */\n  const campaign = String(campaignId ?? '')\n  const topic = String(topicId ?? '')\n  if (campaign.includes(':') || topic.includes(':')) return ''\n  if (topic && campaign) return `${hostId}:${address}:${campaign}:${topic}`\n  if (campaign) return `${hostId}:${address}:${campaign}`\n  return `${hostId}:${address}`\n}\n\n/** HMAC for unsubscribe links; env-gated on the shared secret. */\nexport function unsubscribeSignature(\n  hostId: string,\n  email: string,\n  secret: string,\n  campaignId?: string,\n  topicId?: string,\n): string {\n  const subject = unsubscribeSignatureSubject(hostId, email, campaignId, topicId)\n  // An unsignable subject yields no signature rather than a signature over the\n  // empty string, which would verify for every caller that also passed one.\n  if (!subject) return ''\n  return createHmac('sha256', secret).update(subject).digest('hex')\n}\n\n/**\n * Whether a signature is this link's.\n *\n * Which form is checked is decided by the LINK, not by the signature: a link\n * carrying no `cid` is checked against the two-part form and a link carrying\n * one against the three-part form. There is no fallback between them, and\n * that is what stops this being a downgrade — an attacker cannot take a\n * three-part link, drop the `cid` and have it verify, because the two-part\n * check over the same `hostId:email` produces a different digest. Nor can\n * they bolt a `cid` onto a two-part link: the three-part check then fails.\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 unsubscribeSignatureMatches(args: {\n  hostId: string\n  email: string\n  campaignId?: string\n  signature: string\n  secret: string\n}): boolean {\n  const expected = unsubscribeSignature(\n    args.hostId,\n    args.email,\n    args.secret,\n    args.campaignId || undefined,\n  )\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 * The purpose component that distinguishes a CONFIRMATION subject.\n *\n * See {@link confirmSignatureSubject}. Exported because the plugin's verifier\n * imports it rather than restating the literal.\n */\nexport const CONFIRM_SUBJECT_PREFIX = 'confirm'\n\n/**\n * The signed subject for a double opt-in confirmation link.\n *\n * ## Why it is not one of the three forms above\n *\n * A confirmation names a host, an address and a topic, and it has NO\n * campaign — nobody is unsubscribing from a message, they are joining a\n * stream. The forms above refuse exactly that combination: a topic with no\n * campaign would leave an empty middle component, and `host:email::t` is the\n * same string as a three-part subject whose campaign id is `:t`.\n *\n * So it gets a leading PURPOSE component. That is a fourth form of the same\n * scheme, not a second scheme: the digest, the secret and the comparison are\n * unchanged.\n *\n * ## The one collision, and the guard for it\n *\n * `confirm:H:E:T` is byte-identical to the four-part unsubscribe subject\n * `A:B:C:D` when the site's id is literally `confirm`, which would let one\n * signature verify as both. Ids are not ours to constrain after the fact, so\n * the subject is refused for that host rather than the collision being\n * reasoned about: the cost is one unusable document id, and the alternative\n * is a signature that means two things.\n *\n * @returns the subject, or `''` for a combination it cannot sign\n *          unambiguously. Empty rather than a partial subject, so\n *          {@link confirmSignature} yields no signature rather than one over\n *          the empty string — which would verify for every other caller that\n *          also produced one.\n */\nexport function confirmSignatureSubject(\n  hostId: string,\n  email: string,\n  topicId: string,\n): string {\n  const address = String(email ?? '')\n    .trim()\n    .toLowerCase()\n  const host = String(hostId ?? '')\n  const topic = String(topicId ?? '')\n  if (!host || !address || !topic) return ''\n  if (host === CONFIRM_SUBJECT_PREFIX) return ''\n  if (host.includes(':') || topic.includes(':')) return ''\n  return `${CONFIRM_SUBJECT_PREFIX}:${host}:${address}:${topic}`\n}\n\n/** HMAC for a confirmation link; empty for an unsignable subject. */\nexport function confirmSignature(\n  hostId: string,\n  email: string,\n  topicId: string,\n  secret: string,\n): string {\n  const subject = confirmSignatureSubject(hostId, email, topicId)\n  if (!subject || !secret) return ''\n  return createHmac('sha256', secret).update(subject).digest('hex')\n}\n\n/**\n * The absolute confirmation URL for one address and one topic.\n *\n * Minted where the signup happens, because the message carrying it is sent\n * from there — and that message is TRANSACTIONAL, not marketing: the person\n * just asked for this, so asking them to confirm it is the transaction they\n * started. It carries no unsubscribe header for the same reason a receipt\n * does not.\n *\n * Empty when there is no secret or no origin, for the reason\n * {@link buildUnsubscribeUrl} gives: a link pointing at nothing is worse than\n * no link, because the recipient believes they have confirmed.\n */\nexport function buildConfirmUrl(input: {\n  siteBase: string\n  hostId: string\n  email: string\n  topicId: string\n  /** Defaults to {@link unsubscribeLinkSecret} — the same signing secret. */\n  secret?: string\n}): string {\n  const secret = input.secret ?? unsubscribeLinkSecret()\n  const siteBase = String(input.siteBase ?? '').replace(/\\/+$/, '')\n  const address = String(input.email ?? '')\n    .trim()\n    .toLowerCase()\n  const signature = confirmSignature(\n    input.hostId,\n    address,\n    input.topicId,\n    secret,\n  )\n  if (!siteBase || !signature) return ''\n  return (\n    `${siteBase}/api/email/confirm` +\n    `?hostId=${encodeURIComponent(input.hostId)}` +\n    `&email=${encodeURIComponent(address)}` +\n    `&tid=${encodeURIComponent(input.topicId)}` +\n    `&sig=${signature}`\n  )\n}\n\n/**\n * The absolute unsubscribe URL for one recipient of one site's mail.\n *\n * @returns the URL, or empty string when there is no secret to sign with or\n *          no origin to resolve against. Empty rather than a half-built URL:\n *          a caller can tell it does not have a link, and a link pointing at\n *          nothing is worse than an absent header, because the recipient\n *          believes they have unsubscribed.\n */\nexport function buildUnsubscribeUrl(input: {\n  siteBase: string\n  hostId: string\n  email: string\n  /** The campaign this link rides in, when there is one. */\n  campaignId?: string\n  /** The topic the message belonged to, when it belonged to one. */\n  topicId?: string\n  /**\n   * Which of the two URLs over this one signature to build.\n   *\n   * `one-click` is what the `List-Unsubscribe` header names: a mailbox\n   * provider POSTs it with no human present and expects the act to have\n   * happened when it reads the 200, so it points at the route whose POST\n   * writes immediately and must never point at a page somebody has to submit.\n   * `preferences` is the link a PERSON clicks in the footer, where the topic\n   * this message belonged to is one of the things they can stop instead of\n   * all of it. Defaults to `one-click`, which is what a sender with no topic\n   * — every non-campaign marketing path — wants.\n   */\n  surface?: 'one-click' | 'preferences'\n  /** Defaults to {@link unsubscribeLinkSecret}. */\n  secret?: string\n}): string {\n  const secret = input.secret ?? unsubscribeLinkSecret()\n  const siteBase = String(input.siteBase ?? '').replace(/\\/+$/, '')\n  const address = String(input.email ?? '')\n    .trim()\n    .toLowerCase()\n  if (!secret || !siteBase || !input.hostId || !address) return ''\n  const signature = unsubscribeSignature(\n    input.hostId,\n    address,\n    secret,\n    input.campaignId,\n    input.topicId,\n  )\n  if (!signature) return ''\n  const route =\n    input.surface === 'preferences'\n      ? '/api/email/preferences'\n      : '/api/email/unsubscribe'\n  return (\n    `${siteBase}${route}` +\n    `?hostId=${encodeURIComponent(input.hostId)}` +\n    `&email=${encodeURIComponent(address)}` +\n    `&sig=${signature}` +\n    (input.campaignId ? `&cid=${encodeURIComponent(input.campaignId)}` : '') +\n    (input.topicId ? `&tid=${encodeURIComponent(input.topicId)}` : '')\n  )\n}\n\n/*==========================================\n * A SIGNED LINK OF A SENDER'S OWN (AGL-2981).\n *\n * The forms above are the platform's own unsubscribe and confirmation\n * links, each a subject over a site and an address. A sender that mails\n * from somewhere else — a plugin sending from a person's own mailbox, whose\n * link carries its own facts — signs its link here instead, over a payload\n * of its own and under a PURPOSE of its own.\n *\n * The purpose is not a prefix of the subject, which is how the confirmation\n * form had to guard a collision by hand. It selects the KEY: every purpose's\n * links are signed with an HMAC key derived from the shared secret and the\n * purpose, so a signature minted for one purpose verifies for no other and\n * for none of the platform's own forms above, whatever the payloads spell.\n * The secret, the digest and the constant-time comparison are the same.\n *==========================================*/\n\n/** The key one purpose's links are signed with: derived from the secret, bound to the purpose. */\nfunction signedLinkKey(purpose: string, secret: string): Buffer {\n  return createHmac('sha256', secret).update(`aglyn-signed-link:${purpose}`).digest()\n}\n\n/**\n * The signature of a payload for one purpose, base64url — or `''` when there\n * is no secret, no purpose or no payload to sign, so a caller can tell it has\n * no link rather than one that verifies for anybody.\n */\nexport function signedLinkSignature(\n  purpose: string,\n  payload: string,\n  secret: string = unsubscribeLinkSecret(),\n): string {\n  const name = String(purpose ?? '').trim()\n  const body = String(payload ?? '')\n  if (!secret || !name || !body) return ''\n  return createHmac('sha256', signedLinkKey(name, secret)).update(body).digest('base64url')\n}\n\n/** Whether a signature is this payload's, for this purpose, in constant time. */\nexport function signedLinkSignatureMatches(args: {\n  purpose: string\n  payload: string\n  signature: string\n  /** Defaults to {@link unsubscribeLinkSecret}. */\n  secret?: string\n}): boolean {\n  const expected = signedLinkSignature(args.purpose, args.payload, args.secret ?? unsubscribeLinkSecret())\n  const presented = String(args.signature ?? '')\n  return (\n    expected.length > 0 &&\n    expected.length === presented.length &&\n    timingSafeEqual(new Uint8Array(Buffer.from(expected)), new Uint8Array(Buffer.from(presented)))\n  )\n}\n"],"names":["createHmac","timingSafeEqual","unsubscribeLinkSecret","process","env","EMAIL_UNSUBSCRIBE_SECRET","CRON_SECRET","unsubscribeSignatureSubject","hostId","email","campaignId","topicId","address","String","trim","toLowerCase","campaign","topic","includes","unsubscribeSignature","secret","subject","update","digest","unsubscribeSignatureMatches","args","expected","undefined","length","signature","Uint8Array","Buffer","from","CONFIRM_SUBJECT_PREFIX","confirmSignatureSubject","host","confirmSignature","buildConfirmUrl","input","siteBase","replace","encodeURIComponent","buildUnsubscribeUrl","route","surface","signedLinkKey","purpose","signedLinkSignature","payload","name","body","signedLinkSignatureMatches","presented"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;CAwBC,GAED,SAASA,UAAU,EAAEC,eAAe,QAAQ,SAAQ;AAEpD;;;;;;;CAOC,GACD,OAAO,SAASC;IACd,OAAOC,QAAQC,GAAG,CAACC,wBAAwB,IAAIF,QAAQC,GAAG,CAACE,WAAW,IAAI;AAC5E;AAEA;;;;;;;;;;;;;;;CAeC,GACD,OAAO,SAASC,4BACdC,MAAc,EACdC,KAAa,EACbC,UAAmB,EACnBC,OAAgB;IAEhB,MAAMC,UAAUC,OAAOJ,gBAAAA,QAAS,IAC7BK,IAAI,GACJC,WAAW;IACd;;;;;;;;;;;;GAYC,GACD,MAAMC,WAAWH,OAAOH,qBAAAA,aAAc;IACtC,MAAMO,QAAQJ,OAAOF,kBAAAA,UAAW;IAChC,IAAIK,SAASE,QAAQ,CAAC,QAAQD,MAAMC,QAAQ,CAAC,MAAM,OAAO;IAC1D,IAAID,SAASD,UAAU,OAAO,GAAGR,OAAO,CAAC,EAAEI,QAAQ,CAAC,EAAEI,SAAS,CAAC,EAAEC,OAAO;IACzE,IAAID,UAAU,OAAO,GAAGR,OAAO,CAAC,EAAEI,QAAQ,CAAC,EAAEI,UAAU;IACvD,OAAO,GAAGR,OAAO,CAAC,EAAEI,SAAS;AAC/B;AAEA,gEAAgE,GAChE,OAAO,SAASO,qBACdX,MAAc,EACdC,KAAa,EACbW,MAAc,EACdV,UAAmB,EACnBC,OAAgB;IAEhB,MAAMU,UAAUd,4BAA4BC,QAAQC,OAAOC,YAAYC;IACvE,6EAA6E;IAC7E,0EAA0E;IAC1E,IAAI,CAACU,SAAS,OAAO;IACrB,OAAOrB,WAAW,UAAUoB,QAAQE,MAAM,CAACD,SAASE,MAAM,CAAC;AAC7D;AAEA;;;;;;;;;;;;;;CAcC,GACD,OAAO,SAASC,4BAA4BC,IAM3C;IACC,MAAMC,WAAWP,qBACfM,KAAKjB,MAAM,EACXiB,KAAKhB,KAAK,EACVgB,KAAKL,MAAM,EACXK,KAAKf,UAAU,IAAIiB;IAErB,OACED,SAASE,MAAM,KAAKH,KAAKI,SAAS,CAACD,MAAM,IACzC3B,gBACE,IAAI6B,WAAWC,OAAOC,IAAI,CAACN,YAC3B,IAAII,WAAWC,OAAOC,IAAI,CAACP,KAAKI,SAAS;AAG/C;AAEA;;;;;CAKC,GACD,OAAO,MAAMI,yBAAyB,UAAS;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BC,GACD,OAAO,SAASC,wBACd1B,MAAc,EACdC,KAAa,EACbE,OAAe;IAEf,MAAMC,UAAUC,OAAOJ,gBAAAA,QAAS,IAC7BK,IAAI,GACJC,WAAW;IACd,MAAMoB,OAAOtB,OAAOL,iBAAAA,SAAU;IAC9B,MAAMS,QAAQJ,OAAOF,kBAAAA,UAAW;IAChC,IAAI,CAACwB,QAAQ,CAACvB,WAAW,CAACK,OAAO,OAAO;IACxC,IAAIkB,SAASF,wBAAwB,OAAO;IAC5C,IAAIE,KAAKjB,QAAQ,CAAC,QAAQD,MAAMC,QAAQ,CAAC,MAAM,OAAO;IACtD,OAAO,GAAGe,uBAAuB,CAAC,EAAEE,KAAK,CAAC,EAAEvB,QAAQ,CAAC,EAAEK,OAAO;AAChE;AAEA,mEAAmE,GACnE,OAAO,SAASmB,iBACd5B,MAAc,EACdC,KAAa,EACbE,OAAe,EACfS,MAAc;IAEd,MAAMC,UAAUa,wBAAwB1B,QAAQC,OAAOE;IACvD,IAAI,CAACU,WAAW,CAACD,QAAQ,OAAO;IAChC,OAAOpB,WAAW,UAAUoB,QAAQE,MAAM,CAACD,SAASE,MAAM,CAAC;AAC7D;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASc,gBAAgBC,KAO/B;QACgBA,eACSA,iBACDA;IAFvB,MAAMlB,UAASkB,gBAAAA,MAAMlB,MAAM,YAAZkB,gBAAgBpC;IAC/B,MAAMqC,WAAW1B,QAAOyB,kBAAAA,MAAMC,QAAQ,YAAdD,kBAAkB,IAAIE,OAAO,CAAC,QAAQ;IAC9D,MAAM5B,UAAUC,QAAOyB,eAAAA,MAAM7B,KAAK,YAAX6B,eAAe,IACnCxB,IAAI,GACJC,WAAW;IACd,MAAMc,YAAYO,iBAChBE,MAAM9B,MAAM,EACZI,SACA0B,MAAM3B,OAAO,EACbS;IAEF,IAAI,CAACmB,YAAY,CAACV,WAAW,OAAO;IACpC,OACE,GAAGU,SAAS,kBAAkB,CAAC,GAC/B,CAAC,QAAQ,EAAEE,mBAAmBH,MAAM9B,MAAM,GAAG,GAC7C,CAAC,OAAO,EAAEiC,mBAAmB7B,UAAU,GACvC,CAAC,KAAK,EAAE6B,mBAAmBH,MAAM3B,OAAO,GAAG,GAC3C,CAAC,KAAK,EAAEkB,WAAW;AAEvB;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASa,oBAAoBJ,KAuBnC;QACgBA,eACSA,iBACDA;IAFvB,MAAMlB,UAASkB,gBAAAA,MAAMlB,MAAM,YAAZkB,gBAAgBpC;IAC/B,MAAMqC,WAAW1B,QAAOyB,kBAAAA,MAAMC,QAAQ,YAAdD,kBAAkB,IAAIE,OAAO,CAAC,QAAQ;IAC9D,MAAM5B,UAAUC,QAAOyB,eAAAA,MAAM7B,KAAK,YAAX6B,eAAe,IACnCxB,IAAI,GACJC,WAAW;IACd,IAAI,CAACK,UAAU,CAACmB,YAAY,CAACD,MAAM9B,MAAM,IAAI,CAACI,SAAS,OAAO;IAC9D,MAAMiB,YAAYV,qBAChBmB,MAAM9B,MAAM,EACZI,SACAQ,QACAkB,MAAM5B,UAAU,EAChB4B,MAAM3B,OAAO;IAEf,IAAI,CAACkB,WAAW,OAAO;IACvB,MAAMc,QACJL,MAAMM,OAAO,KAAK,gBACd,2BACA;IACN,OACE,GAAGL,WAAWI,OAAO,GACrB,CAAC,QAAQ,EAAEF,mBAAmBH,MAAM9B,MAAM,GAAG,GAC7C,CAAC,OAAO,EAAEiC,mBAAmB7B,UAAU,GACvC,CAAC,KAAK,EAAEiB,WAAW,GAClBS,CAAAA,MAAM5B,UAAU,GAAG,CAAC,KAAK,EAAE+B,mBAAmBH,MAAM5B,UAAU,GAAG,GAAG,EAAC,IACrE4B,CAAAA,MAAM3B,OAAO,GAAG,CAAC,KAAK,EAAE8B,mBAAmBH,MAAM3B,OAAO,GAAG,GAAG,EAAC;AAEpE;AAEA;;;;;;;;;;;;;;;4CAe4C,GAE5C,gGAAgG,GAChG,SAASkC,cAAcC,OAAe,EAAE1B,MAAc;IACpD,OAAOpB,WAAW,UAAUoB,QAAQE,MAAM,CAAC,CAAC,kBAAkB,EAAEwB,SAAS,EAAEvB,MAAM;AACnF;AAEA;;;;CAIC,GACD,OAAO,SAASwB,oBACdD,OAAe,EACfE,OAAe,EACf5B,SAAiBlB,uBAAuB;IAExC,MAAM+C,OAAOpC,OAAOiC,kBAAAA,UAAW,IAAIhC,IAAI;IACvC,MAAMoC,OAAOrC,OAAOmC,kBAAAA,UAAW;IAC/B,IAAI,CAAC5B,UAAU,CAAC6B,QAAQ,CAACC,MAAM,OAAO;IACtC,OAAOlD,WAAW,UAAU6C,cAAcI,MAAM7B,SAASE,MAAM,CAAC4B,MAAM3B,MAAM,CAAC;AAC/E;AAEA,+EAA+E,GAC/E,OAAO,SAAS4B,2BAA2B1B,IAM1C;QACkEA,cACxCA;IADzB,MAAMC,WAAWqB,oBAAoBtB,KAAKqB,OAAO,EAAErB,KAAKuB,OAAO,GAAEvB,eAAAA,KAAKL,MAAM,YAAXK,eAAevB;IAChF,MAAMkD,YAAYvC,QAAOY,kBAAAA,KAAKI,SAAS,YAAdJ,kBAAkB;IAC3C,OACEC,SAASE,MAAM,GAAG,KAClBF,SAASE,MAAM,KAAKwB,UAAUxB,MAAM,IACpC3B,gBAAgB,IAAI6B,WAAWC,OAAOC,IAAI,CAACN,YAAY,IAAII,WAAWC,OAAOC,IAAI,CAACoB;AAEtF"}

package/src/lib/server/erase-person.d.ts

@@ -0,0 +1,116 @@
+/**
+ * @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 PluginPersonErasureReport } from '@aglyn/aglyn/plugin-manager/plugin-person-erasure';
+export interface ErasePersonOptions {
+    orgId: string;
+    /** Any spelling; normalized before anything is looked up. */
+    email: unknown;
+    /** Injectable for tests; defaults to the admin app's Firestore. */
+    firestore?: any;
+    /** Injectable for tests; defaults to `Date.now()`. */
+    now?: number;
+}
+/**
+ * Counts, never identities: this is what the request document and the
+ * audit row record, and both are read by people who must not learn the
+ * address from them.
+ */
+export interface ErasePersonCounts {
+    /** Sites in the workspace the sweep walked. */
+    hosts: number;
+    /** Suppression rows written, one per site. */
+    hostsSuppressed: number;
+    /** Contact documents deleted — the row every site shared. */
+    contacts: number;
+    /** Companies whose contact count moved down. */
+    companyLinks: number;
+    /** Deals whose `contactId` was removed. */
+    deals: number;
+    tasks: number;
+    activities: number;
+    /** `hosts/{hostId}/leads/{personKey}` rows deleted. */
+    leads: number;
+    /** Audience-list member rows deleted, across every list. */
+    listMemberships: number;
+    /** Orders with the buyer's identity removed; the record stays. */
+    orders: number;
+    /** Bookings with the person's identity removed; the record stays. */
+    bookings: number;
+    /** Delivery-log messages deleted under the address. */
+    emailDeliveries: number;
+    /**
+     * Each plugin's share (AGL-2981), by plugin id: its eraser's own counts,
+     * or `null` for an eraser that failed — its data may remain.
+     */
+    plugins: Record<string, PluginPersonErasureReport | null>;
+}
+export type ErasePersonResult = ({
+    ok: true;
+} & ErasePersonCounts) | {
+    ok: false;
+    skippedReason: 'invalid-email';
+};
+/**
+ * Remove one person from one workspace (AGL-2623).
+ *
+ * `planContactDetach` is deliberately not consulted: the CRM's delete is a
+ * detach that leaves the row for the other holders, and this is the act
+ * that must not. The contact document goes whole — every site's facet,
+ * every consent entry, every attribution — and with it everything the
+ * workspace keeps beside the person.
+ *
+ * ## Order
+ *
+ *   1. **Suppress first.** One row per site on the per-site suppression
+ *      list, before any delete: a form filled in while the sweep runs must
+ *      already find the door closed, or the sweep deletes a row that the
+ *      capture re-creates a moment later.
+ *   2. The plugins' share: every eraser registered on
+ *      `plugin-person-erasure`, handed the address, its key and the ids of
+ *      the contacts about to go, while those documents still exist.
+ *   3. The contact and its satellites — company counts, deals unlinked,
+ *      tasks and activities deleted — by the contact's id, then the
+ *      document itself.
+ *   4. Leads, list memberships, orders and bookings by the address, on
+ *      every site of the workspace.
+ *   5. The delivery log, last: it is filed under the address alone, and the
+ *      tombstone it leaves is what keeps a later import from refilling it.
+ *
+ * ## What is anonymized rather than deleted
+ *
+ * An order is the merchant's record of a sale and a booking of an
+ * appointment; the amounts, the line items and the tax are theirs to keep
+ * and the law expects them kept. The person is taken OFF those records —
+ * name, email, phone, addresses — and a stamp says when. A deal is the
+ * team's own pipeline record and is unlinked. Everything else that names
+ * the person is about the person and is deleted.
+ *
+ * ## What is not reached, and why
+ *
+ * A form submission keeps the address inside `fields`, under whatever the
+ * form called it — there is no key to query by and a scan of every
+ * submission on every site is unbounded. A site member's login is their
+ * own account. A subscription carries the address it bills, and a live one
+ * cannot be anonymized without breaking its receipts. Each is named to the
+ * admin by the dialog so they can finish by hand.
+ *
+ * Every sweep is best-effort against the others: a failure in one is
+ * logged and counted as zero, and the request's counts say what happened.
+ * The caller decides whether zero contacts on a person it could see is a
+ * failure to retry.
+ */
+export declare function erasePerson(options: ErasePersonOptions): Promise<ErasePersonResult>;