@framers/agentos-ext-channel-email 0.3.0 → 0.4.2

package/dist/messageText.js

@@ -5,11 +5,12 @@
  * object as a body and reads the file its `path` names, or fetches the address its `href` names, into the message,
  * and it writes an object header value marked `prepared` into the message as it is, line breaks included. A model
  * writes the tools' arguments and the channel's blocks as JSON, so such an object reaches the service whatever the
- * TypeScript types say.
+ * TypeScript types say. A subject is then put on one line, as nodemailer writes one, so Resend is given the same.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.requireText = requireText;
 exports.optionalText = optionalText;
+exports.oneLine = oneLine;
 /**
  * Returns `value` when it is a string, and otherwise throws a `TypeError` that names `field` and never the value.
  *
@@ -35,4 +36,19 @@ function optionalText(field, value) {
         return value;
     throw new TypeError(`The ${field} was refused: give it as a string or leave it out`);
 }
+/**
+ * A line break, CR LF counted as one, or another character a subject cannot hold on one line: a control character other
+ * than the tab, or a Unicode line or paragraph separator.
+ */
+const BREAKS_A_LINE = /\r\n|[\x00-\x08\x0a-\x1f\x7f-\x9f\u2028\u2029]/g;
+/**
+ * `text` on one line, each line break or other control character but the tab written as a space. nodemailer writes a
+ * line break in a subject as a space, and `EmailService` gives Resend the subject it gives nodemailer, so a subject is
+ * sent alike through both transports, whoever wrote it: a caller, or the original a reply answers.
+ *
+ * @param text The subject as given.
+ */
+function oneLine(text) {
+    return text.replace(BREAKS_A_LINE, ' ');
+}
 //# sourceMappingURL=messageText.js.map

package/dist/messageText.js.map

@@ -1 +1 @@
-{"version":3,"file":"messageText.js","sourceRoot":"","sources":["../src/messageText.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAQH,kCAGC;AASD,oCAIC;AAtBD;;;;;GAKG;AACH,SAAgB,WAAW,CAAC,KAAa,EAAE,KAAc;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,IAAI,SAAS,CAAC,OAAO,KAAK,mCAAmC,CAAC,CAAC;AACvE,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,YAAY,CAAC,KAAa,EAAE,KAAc;IACxD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,IAAI,SAAS,CAAC,OAAO,KAAK,mDAAmD,CAAC,CAAC;AACvF,CAAC"}
+{"version":3,"file":"messageText.js","sourceRoot":"","sources":["../src/messageText.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAQH,kCAGC;AASD,oCAIC;AAeD,0BAEC;AAvCD;;;;;GAKG;AACH,SAAgB,WAAW,CAAC,KAAa,EAAE,KAAc;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,IAAI,SAAS,CAAC,OAAO,KAAK,mCAAmC,CAAC,CAAC;AACvE,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,YAAY,CAAC,KAAa,EAAE,KAAc;IACxD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,IAAI,SAAS,CAAC,OAAO,KAAK,mDAAmD,CAAC,CAAC;AACvF,CAAC;AAED;;;GAGG;AACH,MAAM,aAAa,GAAG,iDAAiD,CAAC;AAExE;;;;;;GAMG;AACH,SAAgB,OAAO,CAAC,IAAY;IAClC,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;AAC1C,CAAC"}

package/dist/preferences/RecipientCapability.d.ts

@@ -0,0 +1,100 @@
+import type { EmailPreferencesDb } from './database.js';
+/** What a token names: the recipient it was issued for and the scope it acts on. */
+export interface RecipientGrant {
+    /** The recipient, such as an account id. */
+    readonly recipient: string;
+    /** The scope, such as one kind of mail. */
+    readonly scope: string;
+}
+/** The options of one `issue`. */
+export interface RecipientCapabilityIssueOptions {
+    /** When the token stops working, in epoch milliseconds. A token issued without it works until it is revoked. */
+    readonly expiresAt?: number;
+}
+/** The options of a `SqlRecipientCapability`. */
+export interface SqlRecipientCapabilityOptions {
+    /** The clock `find` reads an expiry against and `revoke` records, in epoch milliseconds: `Date.now` unless given. */
+    readonly now?: () => number;
+}
+/**
+ * Opaque tokens that each name a recipient and a scope, kept as their SHA-256 alone. A token carries neither: only
+ * `find` maps it to them, and the store holds nothing a token can be recovered from.
+ */
+export interface RecipientCapability {
+    /**
+     * Issues the token for a nonce, such as a message's id: base64url of HMAC-SHA256 over the nonce under the key, 43
+     * characters. Issuing again with the same nonce and key, for the same recipient, scope and expiry, answers the same
+     * token and writes nothing; for another recipient, scope or expiry it throws, and the first token keeps its recipient
+     * and scope. A nonce whose token was revoked throws for every recipient, scope and expiry, so a message that needs a
+     * working token after `revoke` takes a new nonce.
+     *
+     * @param recipient The recipient: 1 to 512 characters, with no U+0000 and no lone surrogate.
+     * @param scope The scope, under the same rule.
+     * @param nonce The nonce, under the same rule: one message, one nonce, never another message's.
+     * @param key The key, 32 bytes or more, kept secret by the caller.
+     * @param options The token's expiry, if it has one.
+     * @returns The token.
+     */
+    issue(recipient: string, scope: string, nonce: string, key: Uint8Array, options?: RecipientCapabilityIssueOptions): Promise<string>;
+    /**
+     * The recipient and the scope the token was issued for, or `null` for a token that is malformed, unknown, revoked or
+     * past its expiry. The token is found by its SHA-256 and compared in constant time; a malformed token reaches no
+     * database.
+     *
+     * @param token The token as the link carried it.
+     */
+    find(token: string): Promise<RecipientGrant | null>;
+    /**
+     * Ends every token issued for the recipient, in every scope. Each token's row stays, marked revoked, so its nonce is
+     * never issued again; a token issued afterwards from a new nonce works.
+     *
+     * @param recipient The recipient: 1 to 512 characters, with no U+0000 and no lone surrogate.
+     * @returns How many tokens it ended: a token ended by an earlier revoke is not counted again.
+     */
+    revoke(recipient: string): Promise<number>;
+}
+/**
+ * The token for a nonce under a key: base64url of HMAC-SHA256, 43 characters.
+ *
+ * @param nonce The nonce, as UTF-8.
+ * @param key The key's bytes.
+ */
+export declare function capabilityToken(nonce: string, key: Uint8Array): string;
+/**
+ * What the store keeps of a token: its SHA-256 in lower-case hexadecimal.
+ *
+ * @param token The token, as UTF-8.
+ */
+export declare function capabilityTokenHash(token: string): string;
+/**
+ * The recipient capabilities' table, `<prefix>_capabilities`, and the index `revoke` reads, for a host's migration: one
+ * row a token, its SHA-256 the key, with the recipient, the scope, an optional expiry and the time the token was
+ * revoked, if it was. Both statements are `IF NOT EXISTS`, so they can run at each start, and they run on SQLite and on
+ * PostgreSQL. A row refuses its nonce for as long as it stays: a host that deletes rows, by its own foreign key with
+ * `ON DELETE CASCADE` or by hand, never issues their nonces again, and a host that cannot promise that calls `revoke`
+ * with each deletion and keeps the rows.
+ *
+ * @param prefix A lower-case letter followed by at most 39 lower-case letters, digits or underscores.
+ * @throws RangeError when the prefix does not fit.
+ */
+export declare function recipientCapabilityDdl(prefix: string): string;
+/**
+ * Recipient capabilities on a host's SQL database, in the table `recipientCapabilityDdl` makes under the same prefix.
+ * Each argument is checked before any statement, and an error from the database reaches the caller as it was thrown.
+ */
+export declare class SqlRecipientCapability implements RecipientCapability {
+    private readonly db;
+    private readonly table;
+    private readonly now;
+    /**
+     * @param db The database: `@framers/sql-storage-adapter`'s adapter, or any handle of `EmailPreferencesDb`'s shape.
+     * @param prefix The prefix the table was made under.
+     * @param options The clock that expiries are read against and revokes record.
+     * @throws RangeError when the prefix does not fit.
+     */
+    constructor(db: EmailPreferencesDb, prefix: string, options?: SqlRecipientCapabilityOptions);
+    issue(recipient: string, scope: string, nonce: string, key: Uint8Array, options?: RecipientCapabilityIssueOptions): Promise<string>;
+    find(token: string): Promise<RecipientGrant | null>;
+    revoke(recipient: string): Promise<number>;
+}
+//# sourceMappingURL=RecipientCapability.d.ts.map

package/dist/preferences/RecipientCapability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecipientCapability.d.ts","sourceRoot":"","sources":["../../src/preferences/RecipientCapability.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGxD,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,kCAAkC;AAClC,MAAM,WAAW,+BAA+B;IAC9C,gHAAgH;IAChH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,iDAAiD;AACjD,MAAM,WAAW,6BAA6B;IAC5C,qHAAqH;IACrH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;;OAaG;IACH,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,UAAU,EACf,OAAO,CAAC,EAAE,+BAA+B,GACxC,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnB;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAEpD;;;;;;OAMG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5C;AAQD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEzD;AAuDD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAY7D;AAED;;;GAGG;AACH,qBAAa,sBAAuB,YAAW,mBAAmB;IAW9D,OAAO,CAAC,QAAQ,CAAC,EAAE;IAVrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC;;;;;OAKG;gBAEgB,EAAE,EAAE,kBAAkB,EACvC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,6BAAkC;IAMvC,KAAK,CACT,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,UAAU,EACf,OAAO,CAAC,EAAE,+BAA+B,GACxC,OAAO,CAAC,MAAM,CAAC;IA4BZ,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAgBnD,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CASjD"}

package/dist/preferences/RecipientCapability.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqlRecipientCapability = void 0;
+exports.capabilityToken = capabilityToken;
+exports.capabilityTokenHash = capabilityTokenHash;
+exports.recipientCapabilityDdl = recipientCapabilityDdl;
+/**
+ * @fileoverview Recipient capabilities: opaque tokens that each name one recipient and one scope, such as the link in a
+ * message that lets its reader stop one kind of mail without signing in. A token is base64url of HMAC-SHA256 over the
+ * caller's nonce under the caller's key, so a message retried with the same nonce carries the same token, and only the
+ * token's SHA-256 is stored, beside the recipient and the scope. A token works until its recipient's tokens are
+ * revoked, or until the expiry its issuer set. A revoked token's row stays, marked revoked, so its nonce is never issued
+ * again: a revoked link never works again, and never comes to name another recipient or scope.
+ */
+const node_crypto_1 = require("node:crypto");
+const database_js_1 = require("./database.js");
+/** A token: 43 base64url characters, 32 bytes without padding. */
+const TOKEN = /^[A-Za-z0-9_-]{43}$/;
+/** The shortest key `issue` takes, HMAC-SHA256's output length; RFC 2104 section 3 discourages shorter keys. */
+const KEY_BYTES = 32;
+/**
+ * The token for a nonce under a key: base64url of HMAC-SHA256, 43 characters.
+ *
+ * @param nonce The nonce, as UTF-8.
+ * @param key The key's bytes.
+ */
+function capabilityToken(nonce, key) {
+    return (0, node_crypto_1.createHmac)('sha256', key).update(nonce, 'utf8').digest('base64url');
+}
+/**
+ * What the store keeps of a token: its SHA-256 in lower-case hexadecimal.
+ *
+ * @param token The token, as UTF-8.
+ */
+function capabilityTokenHash(token) {
+    return (0, node_crypto_1.createHash)('sha256').update(token, 'utf8').digest('hex');
+}
+/** Returns the key when it holds 32 bytes or more, and otherwise throws a `TypeError` that never holds the key. */
+function requireKey(key) {
+    if (key instanceof Uint8Array && key.byteLength >= KEY_BYTES)
+        return key;
+    throw new TypeError(`The key was refused: give it as ${KEY_BYTES} bytes or more, such as a Buffer`);
+}
+/** The expiry `issue`'s options set, or `null` for none; anything but a whole number of milliseconds is refused. */
+function requireExpiry(options) {
+    if (options === undefined)
+        return null;
+    if (typeof options !== 'object' || options === null) {
+        throw new TypeError('The options were refused: give them as an object or leave them out');
+    }
+    const expiresAt = options.expiresAt;
+    if (expiresAt === undefined)
+        return null;
+    if (typeof expiresAt === 'number' && Number.isSafeInteger(expiresAt))
+        return expiresAt;
+    throw new TypeError('The expiry was refused: give it as a whole number of epoch milliseconds or leave it out');
+}
+/** A stored expiry as a number, or `null` for none: PostgreSQL answers a BIGINT as text. */
+function expiryOf(value) {
+    return value === null || value === undefined ? null : Number(value);
+}
+/**
+ * The time a revoke records: the clock's reading in whole epoch milliseconds, or 0 when it answers no such number. A
+ * revoke must mark its rows whatever the clock says: SQLite stores a NaN as NULL, which would leave the tokens working.
+ */
+function revokedAtOf(reading) {
+    const at = typeof reading === 'number' ? Math.trunc(reading) : Number.NaN;
+    return Number.isSafeInteger(at) ? at : 0;
+}
+/** Whether two strings are equal, compared in time that does not depend on where they differ. */
+function equalInConstantTime(left, right) {
+    const a = Buffer.from(left, 'utf8');
+    const b = Buffer.from(right, 'utf8');
+    return a.length === b.length && (0, node_crypto_1.timingSafeEqual)(a, b);
+}
+/** Whether a stored row was revoked: any value in `revoked_at`, which PostgreSQL answers as text. */
+function isRevoked(row) {
+    return row.revoked_at !== null && row.revoked_at !== undefined;
+}
+/**
+ * The recipient capabilities' table, `<prefix>_capabilities`, and the index `revoke` reads, for a host's migration: one
+ * row a token, its SHA-256 the key, with the recipient, the scope, an optional expiry and the time the token was
+ * revoked, if it was. Both statements are `IF NOT EXISTS`, so they can run at each start, and they run on SQLite and on
+ * PostgreSQL. A row refuses its nonce for as long as it stays: a host that deletes rows, by its own foreign key with
+ * `ON DELETE CASCADE` or by hand, never issues their nonces again, and a host that cannot promise that calls `revoke`
+ * with each deletion and keeps the rows.
+ *
+ * @param prefix A lower-case letter followed by at most 39 lower-case letters, digits or underscores.
+ * @throws RangeError when the prefix does not fit.
+ */
+function recipientCapabilityDdl(prefix) {
+    const table = `${(0, database_js_1.requirePrefix)(prefix)}_capabilities`;
+    return [
+        `CREATE TABLE IF NOT EXISTS ${table} (`,
+        '  token_hash TEXT PRIMARY KEY,',
+        '  recipient TEXT NOT NULL,',
+        '  scope TEXT NOT NULL,',
+        '  expires_at BIGINT,',
+        '  revoked_at BIGINT',
+        ');',
+        `CREATE INDEX IF NOT EXISTS ${table}_recipient ON ${table} (recipient);`,
+    ].join('\n');
+}
+/**
+ * Recipient capabilities on a host's SQL database, in the table `recipientCapabilityDdl` makes under the same prefix.
+ * Each argument is checked before any statement, and an error from the database reaches the caller as it was thrown.
+ */
+class SqlRecipientCapability {
+    /**
+     * @param db The database: `@framers/sql-storage-adapter`'s adapter, or any handle of `EmailPreferencesDb`'s shape.
+     * @param prefix The prefix the table was made under.
+     * @param options The clock that expiries are read against and revokes record.
+     * @throws RangeError when the prefix does not fit.
+     */
+    constructor(db, prefix, options = {}) {
+        this.db = db;
+        this.table = `${(0, database_js_1.requirePrefix)(prefix)}_capabilities`;
+        this.now = options.now ?? Date.now;
+    }
+    async issue(recipient, scope, nonce, key, options) {
+        (0, database_js_1.requireName)('recipient', recipient);
+        (0, database_js_1.requireName)('scope', scope);
+        (0, database_js_1.requireName)('nonce', nonce);
+        const expiresAt = requireExpiry(options);
+        const token = capabilityToken(nonce, requireKey(key));
+        const tokenHash = capabilityTokenHash(token);
+        const inserted = await this.db.run(`INSERT INTO ${this.table} (token_hash, recipient, scope, expires_at) VALUES (?, ?, ?, ?) ` +
+            'ON CONFLICT (token_hash) DO NOTHING', [tokenHash, recipient, scope, expiresAt]);
+        if (inserted.changes === 1)
+            return token;
+        // The nonce was issued before, or a handle that reports no `changes` wrote it: the stored row decides.
+        const row = await this.db.get(`SELECT recipient, scope, expires_at, revoked_at FROM ${this.table} WHERE token_hash = ?`, [tokenHash]);
+        if (row === null || row === undefined) {
+            throw new Error('The token was not stored: its row was deleted while it was issued');
+        }
+        if (isRevoked(row)) {
+            throw new Error('The token was refused: its nonce was revoked under this key; give the message a new nonce');
+        }
+        if (row.recipient === recipient && row.scope === scope && expiryOf(row.expires_at) === expiresAt)
+            return token;
+        throw new Error('The token was refused: its nonce was issued under this key for another recipient, scope or expiry');
+    }
+    async find(token) {
+        if (typeof token !== 'string' || !TOKEN.test(token))
+            return null;
+        const tokenHash = capabilityTokenHash(token);
+        const row = await this.db.get(`SELECT token_hash, recipient, scope, expires_at, revoked_at FROM ${this.table} WHERE token_hash = ?`, [tokenHash]);
+        if (row === null || row === undefined || typeof row.token_hash !== 'string')
+            return null;
+        if (!equalInConstantTime(row.token_hash, tokenHash))
+            return null;
+        if (isRevoked(row))
+            return null;
+        const expiresAt = expiryOf(row.expires_at);
+        // Written so that a clock that answers NaN ends the token rather than keeping it.
+        if (expiresAt !== null && !(this.now() < expiresAt))
+            return null;
+        return { recipient: row.recipient, scope: row.scope };
+    }
+    async revoke(recipient) {
+        const name = (0, database_js_1.requireName)('recipient', recipient);
+        // The rows stay, so `issue` can refuse their nonces; only the live ones are marked and counted.
+        const result = await this.db.run(`UPDATE ${this.table} SET revoked_at = ? WHERE recipient = ? AND revoked_at IS NULL`, [revokedAtOf(this.now()), name]);
+        return result.changes ?? 0;
+    }
+}
+exports.SqlRecipientCapability = SqlRecipientCapability;
+//# sourceMappingURL=RecipientCapability.js.map

package/dist/preferences/RecipientCapability.js.map

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

package/dist/preferences/SuppressionStore.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview The suppression record: the addresses a host must not mail, by scope, each named by the SHA-256 of the
+ * address that the host computes, so the record never holds an address. A host's senders read it before a send, and
+ * the handler of its provider's events writes it when a message bounces, draws a complaint or meets the provider's own
+ * suppression list. A second record of an address writes nothing, so a provider's repeated event is harmless.
+ */
+import type { EmailPreferencesDb } from './database.js';
+/** The reasons an address is suppressed, in the order the README lists them. */
+export declare const SUPPRESSION_REASONS: readonly ["bounce", "complaint", "suppressed", "manual"];
+/**
+ * Why an address is suppressed: `bounce` (a message to it bounced), `complaint` (its reader reported a message as
+ * spam), `suppressed` (the provider refused a message because the address was already on its own list) or `manual`
+ * (an operator, or the person, asked).
+ */
+export type SuppressionReason = (typeof SUPPRESSION_REASONS)[number];
+/** The scope of a host that keeps one list: every reader and writer of the record passes it. */
+export declare const DEFAULT_SUPPRESSION_SCOPE = "mail";
+/**
+ * The addresses a host must not mail, by scope. A scope is one list, such as all of a host's mail or one sending
+ * domain's, and most hosts keep one, `DEFAULT_SUPPRESSION_SCOPE`. An address is named by its hash, the SHA-256 of the
+ * address as 64 lower-case hexadecimal characters, which the host computes the same way wherever it reads or writes the
+ * record, such as over the address lower-cased. Anything else is refused with a `TypeError`, so an address passed by
+ * mistake is never stored and never answered as not suppressed.
+ */
+export interface SuppressionStore {
+    /**
+     * Whether the address is suppressed in the scope.
+     *
+     * @param scope The list: 1 to 512 characters, with no U+0000 and no lone surrogate.
+     * @param addressHash The SHA-256 of the address as 64 lower-case hexadecimal characters.
+     */
+    isSuppressed(scope: string, addressHash: string): Promise<boolean>;
+    /**
+     * Records the address as suppressed in the scope, with the reason and the day, and no end. A second record of the
+     * address in the scope writes nothing and leaves the first as it was, whatever its reason or day.
+     *
+     * @param scope The list: 1 to 512 characters, with no U+0000 and no lone surrogate.
+     * @param addressHash The SHA-256 of the address as 64 lower-case hexadecimal characters.
+     * @param reason Why the address is suppressed.
+     * @param day The calendar day of the event, `YYYY-MM-DD`.
+     * @returns `true` when this call recorded the address, `false` when the scope held it already.
+     */
+    suppress(scope: string, addressHash: string, reason: SuppressionReason, day: string): Promise<boolean>;
+}
+/**
+ * The suppression record's table, `<prefix>_suppressions`, for a host's migration: one row an address and scope, with
+ * the reason and the day, `CREATE TABLE IF NOT EXISTS` so it can run at each start. It runs on SQLite and on
+ * PostgreSQL.
+ *
+ * @param prefix A lower-case letter followed by at most 39 lower-case letters, digits or underscores.
+ * @throws RangeError when the prefix does not fit.
+ */
+export declare function suppressionStoreDdl(prefix: string): string;
+/**
+ * The suppression record on a host's SQL database, in the table `suppressionStoreDdl` makes under the same prefix. A
+ * record is one `INSERT ... ON CONFLICT DO NOTHING`, so two hosts recording one address at once leave one row. Each
+ * argument is checked before any statement, and an error from the database reaches the caller as it was thrown: no
+ * failure is answered as `false`.
+ */
+export declare class SqlSuppressionStore implements SuppressionStore {
+    private readonly db;
+    private readonly table;
+    /**
+     * @param db The database: `@framers/sql-storage-adapter`'s adapter, or any handle of `EmailPreferencesDb`'s shape.
+     * @param prefix The prefix the table was made under.
+     * @throws RangeError when the prefix does not fit.
+     */
+    constructor(db: EmailPreferencesDb, prefix: string);
+    isSuppressed(scope: string, addressHash: string): Promise<boolean>;
+    suppress(scope: string, addressHash: string, reason: SuppressionReason, day: string): Promise<boolean>;
+}
+//# sourceMappingURL=SuppressionStore.d.ts.map

package/dist/preferences/SuppressionStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SuppressionStore.d.ts","sourceRoot":"","sources":["../../src/preferences/SuppressionStore.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGxD,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,0DAA2D,CAAC;AAE5F;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE,gGAAgG;AAChG,eAAO,MAAM,yBAAyB,SAAS,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnE;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxG;AAwCD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAW1D;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,gBAAgB;IASxD,OAAO,CAAC,QAAQ,CAAC,EAAE;IARrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B;;;;OAIG;gBAEgB,EAAE,EAAE,kBAAkB,EACvC,MAAM,EAAE,MAAM;IAKV,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASlE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAS7G"}

package/dist/preferences/SuppressionStore.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqlSuppressionStore = exports.DEFAULT_SUPPRESSION_SCOPE = exports.SUPPRESSION_REASONS = void 0;
+exports.suppressionStoreDdl = suppressionStoreDdl;
+const database_js_1 = require("./database.js");
+/** The reasons an address is suppressed, in the order the README lists them. */
+exports.SUPPRESSION_REASONS = ['bounce', 'complaint', 'suppressed', 'manual'];
+/** The scope of a host that keeps one list: every reader and writer of the record passes it. */
+exports.DEFAULT_SUPPRESSION_SCOPE = 'mail';
+/** The SHA-256 of an address in lower-case hexadecimal. */
+const ADDRESS_HASH = /^[0-9a-f]{64}$/;
+/** A calendar day, `YYYY-MM-DD`. */
+const DAY = /^(\d{4})-(\d{2})-(\d{2})$/;
+/**
+ * Returns the hash when it is 64 lower-case hexadecimal characters, and otherwise throws a `TypeError` that never holds
+ * the value.
+ */
+function requireAddressHash(value) {
+    if (typeof value === 'string' && ADDRESS_HASH.test(value))
+        return value;
+    throw new TypeError('The address hash was refused: give the SHA-256 of the address as 64 lower-case hexadecimal characters');
+}
+/** Returns the reason when it is one of `SUPPRESSION_REASONS`, and otherwise throws a `TypeError`. */
+function requireReason(value) {
+    if (typeof value === 'string' && exports.SUPPRESSION_REASONS.includes(value)) {
+        return value;
+    }
+    throw new TypeError('The reason was refused: give bounce, complaint, suppressed or manual');
+}
+/** Returns the day when it is a calendar date written `YYYY-MM-DD`, and otherwise throws a `TypeError`. */
+function requireDay(value) {
+    if (typeof value === 'string') {
+        const parts = DAY.exec(value);
+        // A date that does not exist, such as the 30th of February, comes back from Date.UTC as another day.
+        if (parts !== null &&
+            new Date(Date.UTC(Number(parts[1]), Number(parts[2]) - 1, Number(parts[3]))).toISOString().slice(0, 10) === value) {
+            return value;
+        }
+    }
+    throw new TypeError('The day was refused: give a calendar date as YYYY-MM-DD');
+}
+/**
+ * The suppression record's table, `<prefix>_suppressions`, for a host's migration: one row an address and scope, with
+ * the reason and the day, `CREATE TABLE IF NOT EXISTS` so it can run at each start. It runs on SQLite and on
+ * PostgreSQL.
+ *
+ * @param prefix A lower-case letter followed by at most 39 lower-case letters, digits or underscores.
+ * @throws RangeError when the prefix does not fit.
+ */
+function suppressionStoreDdl(prefix) {
+    const table = `${(0, database_js_1.requirePrefix)(prefix)}_suppressions`;
+    return [
+        `CREATE TABLE IF NOT EXISTS ${table} (`,
+        '  scope TEXT NOT NULL,',
+        '  address_hash TEXT NOT NULL,',
+        '  reason TEXT NOT NULL,',
+        '  suppressed_on TEXT NOT NULL,',
+        '  PRIMARY KEY (scope, address_hash)',
+        ');',
+    ].join('\n');
+}
+/**
+ * The suppression record on a host's SQL database, in the table `suppressionStoreDdl` makes under the same prefix. A
+ * record is one `INSERT ... ON CONFLICT DO NOTHING`, so two hosts recording one address at once leave one row. Each
+ * argument is checked before any statement, and an error from the database reaches the caller as it was thrown: no
+ * failure is answered as `false`.
+ */
+class SqlSuppressionStore {
+    /**
+     * @param db The database: `@framers/sql-storage-adapter`'s adapter, or any handle of `EmailPreferencesDb`'s shape.
+     * @param prefix The prefix the table was made under.
+     * @throws RangeError when the prefix does not fit.
+     */
+    constructor(db, prefix) {
+        this.db = db;
+        this.table = `${(0, database_js_1.requirePrefix)(prefix)}_suppressions`;
+    }
+    async isSuppressed(scope, addressHash) {
+        const params = [(0, database_js_1.requireName)('scope', scope), requireAddressHash(addressHash)];
+        const row = await this.db.get(`SELECT 1 AS hit FROM ${this.table} WHERE scope = ? AND address_hash = ?`, params);
+        return row !== null && row !== undefined;
+    }
+    async suppress(scope, addressHash, reason, day) {
+        const params = [(0, database_js_1.requireName)('scope', scope), requireAddressHash(addressHash), requireReason(reason), requireDay(day)];
+        const result = await this.db.run(`INSERT INTO ${this.table} (scope, address_hash, reason, suppressed_on) VALUES (?, ?, ?, ?) ` +
+            'ON CONFLICT (scope, address_hash) DO NOTHING', params);
+        return result.changes === 1;
+    }
+}
+exports.SqlSuppressionStore = SqlSuppressionStore;
+//# sourceMappingURL=SuppressionStore.js.map

package/dist/preferences/SuppressionStore.js.map

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

package/dist/preferences/database.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview What the preference stores need of a database, and the checks of the table prefix and the names they
+ * take. Nothing here imports a database driver: the host passes its own handle.
+ */
+/**
+ * What `SqlSuppressionStore` and `SqlRecipientCapability` need of a database: a statement that answers the number of
+ * rows it changed, and a query that answers its first row, both with `?` placeholders and positional parameters.
+ * `@framers/sql-storage-adapter`'s `StorageAdapter` has this shape on SQLite and on PostgreSQL, and so does the handle
+ * its `transaction` gives a callback, so a store made on that handle writes inside the transaction.
+ */
+export interface EmailPreferencesDb {
+    /** Runs one statement; `changes` is the number of rows it inserted, updated or deleted. */
+    run(sql: string, params?: unknown[]): Promise<{
+        changes?: number;
+    }>;
+    /** Runs one query and answers its first row, or `null` (or `undefined`) when it has none. */
+    get<T>(sql: string, params?: unknown[]): Promise<T | null | undefined>;
+}
+/**
+ * Returns the prefix when it is a lower-case letter followed by at most 39 lower-case letters, digits or underscores,
+ * and otherwise throws a `RangeError`. The prefix is written into the SQL as it is, so nothing else passes.
+ *
+ * @param prefix The table prefix the caller gave.
+ */
+export declare function requirePrefix(prefix: unknown): string;
+/**
+ * Returns `value` when it is a string of 1 to 512 characters that a text column holds as it is, with no U+0000 and no
+ * lone surrogate, and otherwise throws a `TypeError` that names `field` and never the value.
+ *
+ * @param field The argument's name, such as `scope`.
+ * @param value The value the caller gave.
+ */
+export declare function requireName(field: string, value: unknown): string;
+//# sourceMappingURL=database.d.ts.map

package/dist/preferences/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/preferences/database.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,2FAA2F;IAC3F,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpE,6FAA6F;IAC7F,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACxE;AAKD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAKrD;AAUD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAKjE"}

package/dist/preferences/database.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * @fileoverview What the preference stores need of a database, and the checks of the table prefix and the names they
+ * take. Nothing here imports a database driver: the host passes its own handle.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requirePrefix = requirePrefix;
+exports.requireName = requireName;
+/** A table prefix: a lower-case letter, then at most 39 lower-case letters, digits or underscores. */
+const PREFIX = /^[a-z][a-z0-9_]{0,39}$/;
+/**
+ * Returns the prefix when it is a lower-case letter followed by at most 39 lower-case letters, digits or underscores,
+ * and otherwise throws a `RangeError`. The prefix is written into the SQL as it is, so nothing else passes.
+ *
+ * @param prefix The table prefix the caller gave.
+ */
+function requirePrefix(prefix) {
+    if (typeof prefix === 'string' && PREFIX.test(prefix))
+        return prefix;
+    throw new RangeError('The table prefix was refused: give a lower-case letter followed by at most 39 lower-case letters, digits or underscores');
+}
+/**
+ * What a text column cannot hold as given: U+0000, which PostgreSQL's text refuses, and a lone surrogate, which UTF-8
+ * cannot encode, so a driver writes something else in its place (node-postgres writes U+FFFD): the row would name
+ * another value, and two values would meet in one. With the `u` flag a surrogate pair is one code point and does not
+ * match.
+ */
+const UNSTORABLE = /\u0000|[\uD800-\uDFFF]/u;
+/**
+ * Returns `value` when it is a string of 1 to 512 characters that a text column holds as it is, with no U+0000 and no
+ * lone surrogate, and otherwise throws a `TypeError` that names `field` and never the value.
+ *
+ * @param field The argument's name, such as `scope`.
+ * @param value The value the caller gave.
+ */
+function requireName(field, value) {
+    if (typeof value === 'string' && value.length > 0 && value.length <= 512 && !UNSTORABLE.test(value))
+        return value;
+    throw new TypeError(`The ${field} was refused: give it as a string of 1 to 512 characters with no U+0000 and no lone surrogate`);
+}
+//# sourceMappingURL=database.js.map

package/dist/preferences/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../../src/preferences/database.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAwBH,sCAKC;AAiBD,kCAKC;AApCD,sGAAsG;AACtG,MAAM,MAAM,GAAG,wBAAwB,CAAC;AAExC;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,MAAe;IAC3C,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IACrE,MAAM,IAAI,UAAU,CAClB,yHAAyH,CAC1H,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,GAAG,yBAAyB,CAAC;AAE7C;;;;;;GAMG;AACH,SAAgB,WAAW,CAAC,KAAa,EAAE,KAAc;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAClH,MAAM,IAAI,SAAS,CACjB,OAAO,KAAK,+FAA+F,CAC5G,CAAC;AACJ,CAAC"}

package/dist/preferences/index.d.ts

@@ -0,0 +1,15 @@
+export type { EmailPreferencesDb } from './database.js';
+export { DEFAULT_SUPPRESSION_SCOPE, SUPPRESSION_REASONS, SqlSuppressionStore, suppressionStoreDdl } from './SuppressionStore.js';
+export type { SuppressionReason, SuppressionStore } from './SuppressionStore.js';
+export { SqlRecipientCapability, recipientCapabilityDdl } from './RecipientCapability.js';
+export type { RecipientCapability, RecipientCapabilityIssueOptions, RecipientGrant, SqlRecipientCapabilityOptions, } from './RecipientCapability.js';
+/**
+ * Both tables' DDL under one prefix, the suppression record's then the recipient capabilities', for a host whose one
+ * migration makes both. A host whose tables come from different migrations runs `suppressionStoreDdl` and
+ * `recipientCapabilityDdl` where each belongs.
+ *
+ * @param prefix A lower-case letter followed by at most 39 lower-case letters, digits or underscores.
+ * @throws RangeError when the prefix does not fit.
+ */
+export declare function emailPreferencesDdl(prefix: string): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/preferences/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/preferences/index.ts"],"names":[],"mappings":"AAOA,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjI,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAC1F,YAAY,EACV,mBAAmB,EACnB,+BAA+B,EAC/B,cAAc,EACd,6BAA6B,GAC9B,MAAM,0BAA0B,CAAC;AAElC;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D"}