@o3co/auth-provider-foundation 0.17.0 → 0.18.0-rc.1

package/keys/src/jws.d.ts

@@ -0,0 +1,7 @@
+/** A segment as its bytes encode: base64url without padding, and no bits a decoder drops. */
+export declare const canonical: (segment: string) => boolean;
+/**
+ * Whether a compact JWS is written in its one form. A decoder drops a last character's spare bits,
+ * so without this one token has many strings, and anything keyed by the string is slipped past.
+ */
+export declare const isCanonicalJws: (jws: string) => boolean;

package/keys/src/jws.js

@@ -0,0 +1,11 @@
+/** A segment as its bytes encode: base64url without padding, and no bits a decoder drops. */
+export const canonical = (segment) => /^[A-Za-z0-9_-]*$/.test(segment) &&
+    Buffer.from(segment, "base64url").toString("base64url") === segment;
+/**
+ * Whether a compact JWS is written in its one form. A decoder drops a last character's spare bits,
+ * so without this one token has many strings, and anything keyed by the string is slipped past.
+ */
+export const isCanonicalJws = (jws) => {
+    const segments = jws.split(".");
+    return segments.length === 3 && segments.every(canonical);
+};

package/keys/src/module.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@o3co/auth-provider-foundation/kernel").Module;
+export default _default;

package/keys/src/module.js

@@ -0,0 +1,31 @@
+import { routes } from "@o3co/auth-provider-foundation/http";
+import { contract, defineModule } from "@o3co/auth-provider-foundation/kernel";
+import { keys } from "./contract.js";
+import { jwksResponse } from "./jwks.js";
+import { readRing } from "./ring.js";
+import { section } from "./section.js";
+import { signer } from "./signer.js";
+const ring = contract("keys.ring");
+const keySetPath = "/.well-known/jwks.json";
+export default defineModule({ name: "keys", section }, (m) => [
+    m.provide(ring).by((c) => {
+        const read = readRing(c.section);
+        if ("unreadable" in read)
+            return c.refuse(`keys.${read.unreadable}`, "not readable as a key for alg");
+        return read;
+    }),
+    m.provide(keys).by(async (c) => ({
+        ...signer(await c.get(ring), c.clock.now),
+        keySetPath: () => keySetPath,
+    })),
+    m.contribute(routes).by(async (c) => {
+        const current = await c.get(ring);
+        return {
+            method: "GET",
+            path: keySetPath,
+            // Public keys a page may read from any listed origin.
+            cors: {},
+            handle: (request) => jwksResponse(current, c.clock.now(), request),
+        };
+    }),
+]);

package/keys/src/public.d.ts

@@ -0,0 +1,21 @@
+import { type KeyObject } from "node:crypto";
+export type Jwk = Readonly<Record<string, unknown>>;
+/** The asymmetric algorithms a public key may verify under. */
+export declare const verifyAlgorithms: readonly string[];
+/** A JWK the platform reads as a public key, kept as given; none with a private member, a `kid` that is no string, or a key member not in its one form. */
+export declare function publicJwk(jwk: Jwk): {
+    readonly jwk: Jwk;
+    readonly key: KeyObject;
+} | undefined;
+/** A public key written as PEM; none for anything else, a private key above all. */
+export declare function publicPem(pem: string): KeyObject | undefined;
+/**
+ * Whether a JWK may verify: its `use` is `sig` and its `key_ops` hold `verify` where named, and its
+ * kind and curve fit `alg` (and its own `alg` is `alg`), or, with no `alg`, any algorithm here.
+ */
+export declare function verifiesUnder(jwk: Jwk, alg?: string): boolean;
+/**
+ * The JWK rebuilt from its type's public members alone; none if it holds any other member but
+ * those describing it, or a member that is no string. Not read by the platform.
+ */
+export declare function publicMembers(jwk: unknown): Readonly<Record<string, string>> | undefined;

package/keys/src/public.js

@@ -0,0 +1,100 @@
+import { createPrivateKey, createPublicKey } from "node:crypto";
+import { canonical } from "./jws.js";
+/** The kind of key each asymmetric algorithm verifies with. */
+const fits = {
+    ...Object.fromEntries(["RS256", "RS384", "RS512", "PS256", "PS384", "PS512"].map((alg) => [
+        alg,
+        (jwk) => jwk.kty === "RSA",
+    ])),
+    ES256: (jwk) => jwk.kty === "EC" && jwk.crv === "P-256",
+    ES384: (jwk) => jwk.kty === "EC" && jwk.crv === "P-384",
+    ES512: (jwk) => jwk.kty === "EC" && jwk.crv === "P-521",
+    EdDSA: (jwk) => jwk.kty === "OKP" && (jwk.crv === "Ed25519" || jwk.crv === "Ed448"),
+};
+/** The asymmetric algorithms a public key may verify under. */
+export const verifyAlgorithms = Object.freeze(Object.keys(fits));
+/** The members of each public key type. A Map, so no inherited name is a type. */
+const membersOf = new Map([
+    ["EC", ["kty", "crv", "x", "y"]],
+    ["OKP", ["kty", "crv", "x"]],
+    ["RSA", ["kty", "n", "e"]],
+]);
+/** Members describing a key that carry no key material. */
+const describing = new Set(["kid", "alg", "use", "key_ops"]);
+/** Whether each key member is base64url as its bytes encode, so one key has one JWK. */
+const inOneForm = (jwk) => (membersOf.get(jwk.kty) ?? [])
+    .filter((member) => member !== "kty" && member !== "crv")
+    .every((member) => typeof jwk[member] !== "string" || canonical(jwk[member]));
+const privateMembers = ["d", "p", "q", "dp", "dq", "qi", "k", "oth"];
+/** A JWK the platform reads as a public key, kept as given; none with a private member, a `kid` that is no string, or a key member not in its one form. */
+export function publicJwk(jwk) {
+    if (privateMembers.some((member) => Object.hasOwn(jwk, member)))
+        return undefined;
+    if (jwk.kid !== undefined && typeof jwk.kid !== "string")
+        return undefined;
+    if (!inOneForm(jwk))
+        return undefined;
+    try {
+        return { jwk, key: createPublicKey({ key: jwk, format: "jwk" }) };
+    }
+    catch {
+        return undefined;
+    }
+}
+function isPrivate(pem) {
+    try {
+        createPrivateKey(pem);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A public key written as PEM; none for anything else, a private key above all. */
+export function publicPem(pem) {
+    // The platform reads a public key out of a private one, so a private key is refused first.
+    if (isPrivate(pem))
+        return undefined;
+    try {
+        return createPublicKey(pem);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether a JWK may verify: its `use` is `sig` and its `key_ops` hold `verify` where named, and its
+ * kind and curve fit `alg` (and its own `alg` is `alg`), or, with no `alg`, any algorithm here.
+ */
+export function verifiesUnder(jwk, alg) {
+    if (jwk.use !== undefined && jwk.use !== "sig")
+        return false;
+    if (jwk.key_ops !== undefined && !(Array.isArray(jwk.key_ops) && jwk.key_ops.includes("verify")))
+        return false;
+    if (alg === undefined)
+        return Object.values(fits).some((fit) => fit(jwk));
+    const fit = Object.hasOwn(fits, alg) ? fits[alg] : undefined;
+    return (fit?.(jwk) ?? false) && (jwk.alg === undefined || jwk.alg === alg);
+}
+/**
+ * The JWK rebuilt from its type's public members alone; none if it holds any other member but
+ * those describing it, or a member that is no string. Not read by the platform.
+ */
+export function publicMembers(jwk) {
+    if (typeof jwk !== "object" || jwk === null || Array.isArray(jwk))
+        return undefined;
+    const given = jwk;
+    const members = membersOf.get(given.kty);
+    if (!members)
+        return undefined;
+    if (Object.keys(given).some((m) => !members.includes(m) && !describing.has(m)))
+        return undefined;
+    const rebuilt = {};
+    for (const m of members) {
+        const value = given[m];
+        if (typeof value !== "string")
+            return undefined;
+        rebuilt[m] = value;
+    }
+    return inOneForm(rebuilt) ? rebuilt : undefined;
+}

package/keys/src/ring.d.ts

@@ -0,0 +1,19 @@
+import { type KeyObject } from "node:crypto";
+import type { Section } from "./section.js";
+export interface RingKey {
+    readonly kid: string;
+    readonly alg: string;
+    readonly key: KeyObject;
+    readonly expiresAt?: number;
+}
+export interface Ring {
+    readonly signing: RingKey;
+    /** Keys safe to publish: the signing key's public half (unless HS256), the previous keys and the next. */
+    readonly publicKeys: readonly RingKey[];
+}
+/** True once the key's expiry has passed; reads the clock only for keys that expire. */
+export declare function expired(key: RingKey, now: () => number): boolean;
+/** Returns the config path that cannot be read as a key of its alg, or the ring. */
+export declare function readRing(section: Section): Ring | {
+    readonly unreadable: string;
+};

package/keys/src/ring.js

@@ -0,0 +1,60 @@
+import { createPrivateKey, createPublicKey, createSecretKey } from "node:crypto";
+import { bytesOf } from "./secret.js";
+const keyTypes = {
+    EdDSA: (key) => key.asymmetricKeyType === "ed25519",
+    ES256: (key) => key.asymmetricKeyType === "ec" && key.asymmetricKeyDetails?.namedCurve === "prime256v1",
+    RS256: (key) => key.asymmetricKeyType === "rsa" && (key.asymmetricKeyDetails?.modulusLength ?? 0) >= 2048,
+};
+/** True once the key's expiry has passed; reads the clock only for keys that expire. */
+export function expired(key, now) {
+    return key.expiresAt !== undefined && key.expiresAt <= now();
+}
+function parsed(read) {
+    try {
+        return read();
+    }
+    catch {
+        return undefined;
+    }
+}
+function signingKey(signing) {
+    if (signing.alg === "HS256") {
+        return {
+            kid: signing.kid,
+            alg: "HS256",
+            key: createSecretKey(bytesOf(signing.secret, { hex: true }) ?? Buffer.alloc(0)),
+        };
+    }
+    // createPrivateKey refuses a public key, so what it reads is always private.
+    const key = parsed(() => createPrivateKey(signing["private-key"]));
+    if (!key || !keyTypes[signing.alg](key))
+        return undefined;
+    return { kid: signing.kid, alg: signing.alg, key };
+}
+/** Returns the config path that cannot be read as a key of its alg, or the ring. */
+export function readRing(section) {
+    const signing = signingKey(section.signing);
+    if (!signing)
+        return { unreadable: "signing.private-key" };
+    const publicKeys = signing.alg === "HS256" ? [] : [{ ...signing, key: createPublicKey(signing.key) }];
+    for (const [i, entry] of section.previous.entries()) {
+        // The provider's own previous key: a private PEM is taken too, for its public half.
+        const key = parsed(() => createPublicKey(entry["public-key"]));
+        if (!key || !keyTypes[entry.alg](key))
+            return { unreadable: `previous.${i}.public-key` };
+        publicKeys.push({
+            kid: entry.kid,
+            alg: entry.alg,
+            key,
+            expiresAt: Date.parse(entry["expires-at"]),
+        });
+    }
+    const coming = section.next;
+    if (coming !== undefined) {
+        const key = parsed(() => createPublicKey(coming["public-key"]));
+        if (!key || !keyTypes[coming.alg](key))
+            return { unreadable: "next.public-key" };
+        publicKeys.push({ kid: coming.kid, alg: coming.alg, key });
+    }
+    return { signing, publicKeys };
+}

package/keys/src/secret.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+/** A secret setting's bytes: hex where `hex` is taken and the value is whole bytes of hex, else strict base64; none when neither. */
+export declare function bytesOf(value: string, { hex }?: {
+    hex?: boolean | undefined;
+}): Buffer | undefined;
+/**
+ * The setting of a secret's bytes: strict base64 (or hex, where `hex` is taken) of `exactly` or
+ * `atLeast` that many bytes, of at least 8 byte values, never a `REPLACE-` sample. A refusal names
+ * the rule, never the value.
+ */
+export declare function secretBytes(size: {
+    readonly exactly: number;
+} | {
+    readonly atLeast: number;
+}, { hex }?: {
+    hex?: boolean | undefined;
+}): z.ZodString;

package/keys/src/secret.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+/** Standard base64 alone, padded: a lax decoder skips other characters and reads what is left. */
+const strictBase64 = /^(?:[A-Za-z0-9+/]{4})+(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$|^(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)$/;
+/** A key of fewer byte values is weak (all zero, a short repeated pattern); a random one is, with odds under 1e-36. */
+const fewestByteValues = 8;
+/** A secret setting's bytes: hex where `hex` is taken and the value is whole bytes of hex, else strict base64; none when neither. */
+export function bytesOf(value, { hex = false } = {}) {
+    if (hex && /^(?:[0-9a-fA-F]{2})+$/.test(value))
+        return Buffer.from(value, "hex");
+    return strictBase64.test(value) ? Buffer.from(value, "base64") : undefined;
+}
+/**
+ * The setting of a secret's bytes: strict base64 (or hex, where `hex` is taken) of `exactly` or
+ * `atLeast` that many bytes, of at least 8 byte values, never a `REPLACE-` sample. A refusal names
+ * the rule, never the value.
+ */
+export function secretBytes(size, { hex = false } = {}) {
+    return z.string().superRefine((value, ctx) => {
+        const refuse = (message) => ctx.addIssue({ code: "custom", message });
+        if (value.startsWith("REPLACE-"))
+            return refuse("a sample left in place: REPLACE- is never a secret");
+        const bytes = bytesOf(value, { hex });
+        if (!bytes)
+            return refuse(hex ? "not hex or base64" : "not base64");
+        if ("exactly" in size && bytes.length !== size.exactly)
+            return refuse(`${size.exactly} bytes`);
+        if ("atLeast" in size && bytes.length < size.atLeast)
+            return refuse(`at least ${size.atLeast} bytes`);
+        if (new Set(bytes).size < fewestByteValues) {
+            return refuse(`a weak key: fewer than ${fewestByteValues} byte values`);
+        }
+    });
+}

package/keys/src/section.d.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+declare const asymmetric: z.ZodEnum<{
+    RS256: "RS256";
+    ES256: "ES256";
+    EdDSA: "EdDSA";
+}>;
+export type AsymmetricAlg = z.output<typeof asymmetric>;
+export declare const section: z.ZodObject<{
+    signing: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kid: z.ZodString;
+        alg: z.ZodEnum<{
+            RS256: "RS256";
+            ES256: "ES256";
+            EdDSA: "EdDSA";
+        }>;
+        "private-key": z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kid: z.ZodString;
+        alg: z.ZodLiteral<"HS256">;
+        secret: z.ZodString;
+    }, z.core.$strict>], "alg">;
+    next: z.ZodOptional<z.ZodObject<{
+        kid: z.ZodString;
+        alg: z.ZodEnum<{
+            RS256: "RS256";
+            ES256: "ES256";
+            EdDSA: "EdDSA";
+        }>;
+        "public-key": z.ZodString;
+    }, z.core.$strict>>;
+    previous: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kid: z.ZodString;
+        alg: z.ZodEnum<{
+            RS256: "RS256";
+            ES256: "ES256";
+            EdDSA: "EdDSA";
+        }>;
+        "public-key": z.ZodString;
+        "expires-at": z.ZodISODateTime;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type Section = z.output<typeof section>;
+export {};

package/keys/src/section.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { secretBytes } from "./secret.js";
+const kid = z
+    .string()
+    .regex(/^[A-Za-z0-9._~-]{1,128}$/, "kid is 1 to 128 characters of letters, digits and . _ ~ -");
+const asymmetric = z.enum(["EdDSA", "ES256", "RS256"]);
+/** Written as PEM, so a placeholder or a key in another form is refused here, before it is read. */
+const privatePem = z.string().regex(/^\s*-----BEGIN [A-Z0-9 ]+-----/, "a PEM");
+const signingKid = kid.describe("The key id tokens signed with this key carry, unique in the ring.");
+const signingAlg = "The algorithm the provider signs with.";
+const signing = z.discriminatedUnion("alg", [
+    z.strictObject({
+        kid: signingKid,
+        alg: asymmetric.describe(signingAlg),
+        "private-key": privatePem.describe("The signing key, as a PKCS8 PEM."),
+    }),
+    z.strictObject({
+        kid: signingKid,
+        alg: z.literal("HS256").describe(signingAlg),
+        secret: secretBytes({ atLeast: 32 }, { hex: true }).describe("The HMAC secret for HS256: at least 32 bytes, in hex or base64, of at least 8 byte values."),
+    }),
+]);
+const previous = z.strictObject({
+    kid: kid.describe("The key id of a past signing key, unique in the ring."),
+    alg: asymmetric.describe("The algorithm the past key signed with."),
+    "public-key": z
+        .string()
+        .min(1)
+        .describe("The past key's public half, as PEM; a private PEM is taken too."),
+    "expires-at": z.iso
+        .datetime({ offset: true })
+        .describe("When tokens signed by the past key stop being accepted."),
+});
+const next = z.strictObject({
+    kid: kid.describe("The key id of the key that signs next, unique in the ring."),
+    alg: asymmetric.describe("The algorithm the next key will sign with."),
+    "public-key": z
+        .string()
+        .min(1)
+        .describe("The next key's public half, as PEM; a private PEM is taken too."),
+});
+export const section = z
+    .strictObject({
+    signing: signing.describe("The key the provider signs with now."),
+    next: next
+        .optional()
+        .describe("The key that signs next: published and verifying now, never signing, so verifiers know it before it signs."),
+    previous: z
+        .array(previous)
+        .default([])
+        .describe("Past signing keys that still verify tokens until each one's `expires-at`."),
+})
+    .refine((s) => new Set([s.signing.kid, ...s.previous.map((p) => p.kid)]).size === 1 + s.previous.length, { message: "duplicate kid", path: ["previous"] })
+    .refine((s) => s.next === undefined ||
+    ![s.signing.kid, ...s.previous.map((p) => p.kid)].includes(s.next.kid), { message: "duplicate kid", path: ["next"] });

package/keys/src/signer.d.ts

@@ -0,0 +1,3 @@
+import type { Keys } from "./contract.js";
+import { type Ring } from "./ring.js";
+export declare function signer(ring: Ring, now: () => number): Omit<Keys, "keySetPath">;

package/keys/src/signer.js

@@ -0,0 +1,61 @@
+import { CompactSign, compactVerify, decodeProtectedHeader, } from "jose";
+import { isCanonicalJws } from "./jws.js";
+import { expired } from "./ring.js";
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function headerOf(token) {
+    try {
+        return decodeProtectedHeader(token);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function verifiedPayload(token, key) {
+    try {
+        return (await compactVerify(token, key.key, { algorithms: [key.alg] })).payload;
+    }
+    catch {
+        return undefined;
+    }
+}
+function claimsOf(payload) {
+    try {
+        return JSON.parse(decoder.decode(payload));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function signer(ring, now) {
+    // An HS256 secret verifies its own tokens; an asymmetric signing key verifies through its public half.
+    const verifiers = ring.signing.alg === "HS256" ? [ring.signing, ...ring.publicKeys] : ring.publicKeys;
+    const byKid = new Map(verifiers.map((k) => [k.kid, k]));
+    return {
+        asymmetric: () => ring.signing.alg !== "HS256",
+        algorithm: () => ring.signing.alg,
+        sign: (claims, typ) => new CompactSign(encoder.encode(JSON.stringify(claims)))
+            .setProtectedHeader({ alg: ring.signing.alg, typ, kid: ring.signing.kid })
+            .sign(ring.signing.key),
+        verify: async (token, typ) => {
+            const header = isCanonicalJws(token) ? headerOf(token) : undefined;
+            if (!header)
+                return { kind: "invalid", reason: "malformed" };
+            if (header.typ !== typ)
+                return { kind: "invalid", reason: "typ" };
+            const key = typeof header.kid === "string" ? byKid.get(header.kid) : undefined;
+            if (!key)
+                return { kind: "invalid", reason: "kid_unknown" };
+            if (expired(key, now))
+                return { kind: "invalid", reason: "kid_expired" };
+            const payload = await verifiedPayload(token, key);
+            if (!payload)
+                return { kind: "invalid", reason: "signature" };
+            const claims = claimsOf(payload);
+            // Only a key holder can sign a payload that is not JSON; it is answered as a bad signature.
+            if (claims === undefined)
+                return { kind: "invalid", reason: "signature" };
+            return { kind: "valid", claims: Object.freeze(claims) };
+        },
+    };
+}

package/keys/src/testing.d.ts

@@ -0,0 +1,28 @@
+import type { z } from "zod";
+import type { section } from "./section.js";
+export type KeysSettings = z.input<typeof section>;
+/** The keys part of a test's configuration: a fresh Ed25519 signing key, unless the test sets one. */
+export declare function keysConfig(settings?: Partial<KeysSettings>): {
+    keys: {
+        signing: {
+            kid: string;
+            alg: "RS256" | "ES256" | "EdDSA";
+            "private-key": string;
+        } | {
+            kid: string;
+            alg: "HS256";
+            secret: string;
+        };
+        next?: {
+            kid: string;
+            alg: "RS256" | "ES256" | "EdDSA";
+            "public-key": string;
+        } | undefined;
+        previous?: {
+            kid: string;
+            alg: "RS256" | "ES256" | "EdDSA";
+            "public-key": string;
+            "expires-at": string;
+        }[] | undefined;
+    };
+};

package/keys/src/testing.js

@@ -0,0 +1,12 @@
+import { generateKeyPairSync } from "node:crypto";
+/** The keys part of a test's configuration: a fresh Ed25519 signing key, unless the test sets one. */
+export function keysConfig(settings = {}) {
+    const signing = settings.signing ?? {
+        kid: "test",
+        alg: "EdDSA",
+        "private-key": generateKeyPairSync("ed25519")
+            .privateKey.export({ format: "pem", type: "pkcs8" })
+            .toString(),
+    };
+    return { keys: { ...settings, signing } };
+}

package/mail/README.md

@@ -0,0 +1,45 @@
+# mail
+
+## Responsibilities
+- Owns the contract for sending mail: the sending side gives a purpose, one address, values, and optionally a locale and an expiry.
+- Collects the purposes sending sides declare and the templates (wording per purpose); refuses boot when a declared purpose has no template.
+- Prepares each message for every sender: copies and checks it, renders it, checks the rendered result.
+- Holds the address rule, a plain-text template part, and the logging-only sender.
+
+## Not here
+- The list of purposes and what they mean: the sending side's vocabulary.
+- Any wording: templates, contributed apart.
+- Delivery over a network, and its limits: the sender (an adapter).
+
+## Offers
+- `mail` contract: send (purpose, to, values, locale, expiry) → sent / limited.
+- Purpose declarations (`mailPurposes`) and templates (`mailTemplates`: values, locale → subject, text), both keyed by purpose. A deployment changes the wording by replacing the module that contributes the template.
+- `isAddress`: whether a string is one address mail takes; a sender checks its own configured addresses by it.
+- `canonicalAddress`: an address in one form to compare by, the domain in IDNA's ASCII form, lowercase, the local part as given.
+- `plainText`: one wording (English by default) for every locale, `{name}` replaced by that value as it is.
+- `preparer`, for senders: called at build, it gives the function that turns a message into what may be sent, or refuses.
+- Composition definition: the logging-only sender. It logs the purpose, a per-process keyed hash of the address, and the value names.
+- Operator section (logging-only sender): `accept-unsent`, default false; set true to accept that nothing is sent.
+- Contract tests, the module they compose with, and test configuration builders (`./testing`). A sender's harness may make its remote side answer with a limit or fail, saying words no failure may carry.
+
+## Invariants
+- One address per send; anything else (a list, a line break, a display name) is a TypeError.
+- An address is at most 254 bytes in UTF-8 and holds no space, control or format character, route operator (`%`, `!`) or encoded word, else a TypeError. Letters beyond ASCII are allowed.
+- Its domain reads one way, else a TypeError: IDNA's ASCII form of it is letters, digits, hyphens and dots, each `xn--` label in it decodes to other letters and encodes back to itself, and the domain is that form or its Unicode form, case aside.
+- Values that are not a plain object of strings, a locale that is not a string, and an undeclared purpose are TypeErrors.
+- A template whose subject is not one line, or whose text holds control characters other than line feed and tab, is a TypeError.
+- A message whose expiry has come is unavailable and is not sent.
+- Failures are unavailable or limited, never with the remote side's words.
+- The plain-text part refuses a missing value and a value that breaks a line, and never reads a placeholder inside a value.
+- The logging-only sender refuses boot unless `accept-unsent` is set, is not safe on multiple instances, and logs no address and no value.
+
+## Data
+- None stored; the logging-only sender's hash key lives for the process.
+
+## Depends on
+- `kernel`
+
+## Vocabulary
+- purpose: a name the sending side gives a kind of message; templates are chosen by it.
+- template: the wording of one purpose, contributed apart from the sending side so a deployment can replace it.
+- sender: the implementation of the contract that delivers.

package/mail/config.example

@@ -0,0 +1,3 @@
+mail {
+	accept-unsent = true
+}

package/mail/src/address.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Whether `to` is one address mail takes: at most 254 bytes in UTF-8 (RFC 5321), letters beyond
+ * ASCII allowed. A sender checks its own configured addresses by it too.
+ */
+export declare function isAddress(to: unknown): to is string;
+/** One form for comparing addresses: the domain in IDNA's ASCII form, lowercase, the local part as given; none for a string that is no address. */
+export declare function canonicalAddress(to: string): string | undefined;

package/mail/src/address.js

@@ -0,0 +1,45 @@
+import { domainToASCII, domainToUnicode } from "node:url";
+// No space, control or format character, and no route operator (`%`, `!`).
+const part = String.raw `[^\s\p{Cc}\p{Cf}@,;:<>()[\]"\\%!]+`;
+const address = new RegExp(`^${part}@${part}$`, "u");
+/** An encoded word (RFC 2047), which a mail reader decodes into other text. */
+const encodedWord = /=\?.*\?=/;
+/** Letters, digits and hyphens, in labels between dots. */
+const ldh = /^[a-z0-9-]+(\.[a-z0-9-]+)*$/;
+/** An `xn--` label decodes to other letters and encodes back to itself; some Node versions pass one that does not. */
+function aLabelHolds(label) {
+    if (!label.startsWith("xn--"))
+        return true;
+    const unicode = domainToUnicode(label);
+    return unicode !== label && domainToASCII(unicode) === label;
+}
+/**
+ * A domain read one way: its IDNA ASCII form is LDH with every A-label holding, and it is that form
+ * or its Unicode form, case aside. IDNA drops what follows `/`, `?` or `#` and maps full-width
+ * letters, so sending the ASCII form would otherwise reach a domain other than the one checked.
+ */
+function readsAsItself(domain) {
+    const ascii = domainToASCII(domain);
+    const own = domain.toLowerCase();
+    if (!ldh.test(ascii) || !ascii.split(".").every(aLabelHolds))
+        return false;
+    return own === ascii || own === domainToUnicode(ascii);
+}
+/**
+ * Whether `to` is one address mail takes: at most 254 bytes in UTF-8 (RFC 5321), letters beyond
+ * ASCII allowed. A sender checks its own configured addresses by it too.
+ */
+export function isAddress(to) {
+    if (typeof to !== "string" || !to.isWellFormed())
+        return false;
+    if (Buffer.byteLength(to) > 254 || !address.test(to) || encodedWord.test(to))
+        return false;
+    return readsAsItself(to.slice(to.indexOf("@") + 1));
+}
+/** One form for comparing addresses: the domain in IDNA's ASCII form, lowercase, the local part as given; none for a string that is no address. */
+export function canonicalAddress(to) {
+    if (!isAddress(to))
+        return undefined;
+    const at = to.lastIndexOf("@");
+    return `${to.slice(0, at)}@${domainToASCII(to.slice(at + 1))}`;
+}