@bkazemi/verily 0.1.0

package/dist/server/openpgp.js

@@ -0,0 +1,158 @@
+/**
+ * The few questions Verily asks of OpenPGP, answered by OpenPGP.js: whether a cleartext
+ * signature was made by a given key, whether a key carries its own revocation, and which
+ * names the key signed for itself. The format's rules on when a valid signature still does
+ * not count — expiry, subkey back-signatures, key flags, critical subpackets — are the
+ * library's, since they are exactly what a partial reader gets wrong.
+ */
+import { config as defaults, enums, readCleartextMessage, readKey as readOpenpgpKey, verify as verifyMessage, } from 'openpgp';
+import { Refused } from '../core/index.js';
+/** A key or signature arrives as text from a stranger, so every input is bounded first. */
+const maxArmorBytes = 65536;
+/**
+ * SHA-1 is refused for every signature, not only for messages as the library's defaults
+ * have it: chosen prefix collisions against it are practical, and a binding or a user id
+ * certification is as much a statement worth forging as the message is.
+ */
+const config = {
+    ...defaults,
+    rejectHashAlgorithms: new Set([
+        ...defaults.rejectHashAlgorithms,
+        enums.hash.sha1,
+        enums.hash.md5,
+        enums.hash.ripemd,
+    ]),
+    rejectMessageHashAlgorithms: new Set([
+        ...defaults.rejectMessageHashAlgorithms,
+        enums.hash.sha1,
+        enums.hash.md5,
+        enums.hash.ripemd,
+    ]),
+};
+export class Malformed extends Refused {
+    constructor(what, options) {
+        super(`Malformed OpenPGP ${what}`, options);
+    }
+}
+/**
+ * The one armored block of the named kind out of text that may hold others: a holder
+ * pastes the signed message and the key together, and the library reads only the first
+ * block it meets.
+ */
+function block(text, begin, end, what) {
+    if (text.length > maxArmorBytes)
+        throw new Malformed(what);
+    const start = text.indexOf(`-----BEGIN PGP ${begin}-----`);
+    const stop = text.indexOf(`-----END PGP ${end}-----`, start);
+    if (start < 0 || stop < 0)
+        throw new Malformed(what);
+    return text.slice(start, stop + `-----END PGP ${end}-----`.length);
+}
+async function malformed(what, read) {
+    try {
+        return await read();
+    }
+    catch (error) {
+        throw error instanceof Malformed ? error : new Malformed(what, { cause: error });
+    }
+}
+/** The public key in armored text, wherever in the text its block is. */
+export function readCertificate(armored) {
+    return malformed('key', async () => {
+        const key = await readOpenpgpKey({
+            armoredKey: block(armored, 'PUBLIC KEY BLOCK', 'PUBLIC KEY BLOCK', 'key'),
+            config,
+        });
+        if (key.isPrivate())
+            throw new Malformed('key');
+        return key;
+    });
+}
+/** A public key as bare packets, which is how a web key directory serves one. */
+export function readKey(data) {
+    if (data.byteLength > maxArmorBytes)
+        return Promise.reject(new Malformed('key'));
+    return malformed('key', async () => {
+        const key = await readOpenpgpKey({ binaryKey: data, config });
+        if (key.isPrivate())
+            throw new Malformed('key');
+        return key;
+    });
+}
+/** The signed message in armored text, wherever in the text its block is. */
+export function readCleartext(armored) {
+    return malformed('signed message', () => readCleartextMessage({
+        cleartextMessage: block(armored, 'SIGNED MESSAGE', 'SIGNATURE', 'signed message'),
+        config,
+    }));
+}
+/** The key's fingerprint, in the upper case it is read aloud in. */
+export function fingerprint(certificate) {
+    return certificate.getFingerprint().toUpperCase();
+}
+/**
+ * Whether the key says of itself that it is no longer to be used. A revocation only counts
+ * when the key signed it, which is what lets it travel over any channel at all: a hostile
+ * keyserver can withhold one, but it cannot manufacture one.
+ */
+export async function revoked(certificate) {
+    return certificate.isRevoked(undefined, undefined, undefined, config);
+}
+/**
+ * The names this key has signed for itself and not withdrawn, in the order they were
+ * published. A user id is only ever the holder's own claim about where to find them, but
+ * it is a claim the key made, and without checking that, anyone could append a name to a
+ * copy of a published key and have it read back as though its holder had written it.
+ *
+ * It says nothing about whether the address works or who reads it. That is not something a
+ * key can establish about itself, and this does not pretend otherwise.
+ */
+export async function identities(certificate) {
+    const found = [];
+    for (const user of certificate.users) {
+        if (!user.userID)
+            continue;
+        try {
+            await user.verify(undefined, config);
+            found.push(user.userID.userID);
+        }
+        catch {
+            // Never signed by this key, withdrawn, or expired.
+        }
+    }
+    return found;
+}
+/**
+ * Whether this key made this message, under a signature that says it signed a document, and
+ * with a key fit to make it today: not expired, not revoked, and where a subkey made it, one
+ * the primary key bound for signing and that signed back.
+ *
+ * Today, and not when the signature says it was made. The library judges a signature by the
+ * key as it stood at the signature's own creation time, which is right for an archive and
+ * wrong here: that time is the signer's to write, so a key that expired years ago could sign
+ * a fresh line dated to when it was valid.
+ */
+export async function signed(certificate, message) {
+    const documents = [enums.signature.binary, enums.signature.text];
+    const { signatures } = await verifyMessage({
+        message,
+        verificationKeys: certificate,
+        config,
+    });
+    for (const { keyID, signature, verified } of signatures) {
+        try {
+            const [packet] = (await signature).packets;
+            if (!documents.includes(packet.signatureType))
+                continue;
+            if (!(await verified))
+                continue;
+            await certificate.getSigningKey(keyID, new Date(), undefined, config);
+            return true;
+        }
+        catch {
+            // Made by another key, not valid, or by a key not fit to sign today. Another
+            // signature on the message may still be this key's.
+        }
+    }
+    return false;
+}

package/dist/server/pgp.d.ts

@@ -0,0 +1,29 @@
+import { type ArtifactProvider } from '../core/index.js';
+/**
+ * Proves control of an OpenPGP key by having the holder sign the flow's line with it.
+ *
+ * A key has no provider. Nobody operates it, nobody can hand it to somebody else, and there
+ * is no account table anywhere to consult: the fingerprint is the identity. That makes this
+ * the one method where the proof needs no registration, no credentials, and no third party
+ * at all, and where the address the proof came from means nothing. So the holder hands over
+ * the proof itself and this backend publishes it, rather than pointing at somewhere to read.
+ *
+ * Two questions are asked of the network and neither answer is trusted, because both are
+ * rechecked against the key this backend already holds. Has this key been withdrawn, which
+ * only the key can say and a keyserver can only carry; and is there an address on it that
+ * somebody other than its holder stands behind.
+ *
+ * The second question has two sources. A keyserver that confirms addresses publishes one
+ * only after somebody reading mail there asked it to. A web key directory is stronger
+ * still: the domain that owns the mailbox publishes the key itself, at an address derived
+ * from the mailbox, so nobody outside that domain is being taken at their word.
+ */
+export declare function pgpProvider(options?: {
+    keyserver?: string;
+    /**
+     * Replaces the transport for both the keyserver and the web key directory, and with it
+     * the check that keeps directory reads out of the network this runs in. Pass one only
+     * where it enforces that itself, such as through an egress proxy.
+     */
+    fetch?: typeof fetch;
+}): ArtifactProvider;

package/dist/server/pgp.js

@@ -0,0 +1,198 @@
+import { Refused } from '../core/index.js';
+import { fingerprint, identities, readCertificate, readCleartext, readKey, revoked, signed, } from './openpgp.js';
+import { discard, readBounded } from './body.js';
+import { pinnable, publicFetch } from './public-fetch.js';
+import { wkdUrls } from './wkd.js';
+/** How much of a served key is read. Enough for a key and its signatures, and no more. */
+const maxKeyBytes = 65536;
+/**
+ * Proves control of an OpenPGP key by having the holder sign the flow's line with it.
+ *
+ * A key has no provider. Nobody operates it, nobody can hand it to somebody else, and there
+ * is no account table anywhere to consult: the fingerprint is the identity. That makes this
+ * the one method where the proof needs no registration, no credentials, and no third party
+ * at all, and where the address the proof came from means nothing. So the holder hands over
+ * the proof itself and this backend publishes it, rather than pointing at somewhere to read.
+ *
+ * Two questions are asked of the network and neither answer is trusted, because both are
+ * rechecked against the key this backend already holds. Has this key been withdrawn, which
+ * only the key can say and a keyserver can only carry; and is there an address on it that
+ * somebody other than its holder stands behind.
+ *
+ * The second question has two sources. A keyserver that confirms addresses publishes one
+ * only after somebody reading mail there asked it to. A web key directory is stronger
+ * still: the domain that owns the mailbox publishes the key itself, at an address derived
+ * from the mailbox, so nobody outside that domain is being taken at their word.
+ */
+export function pgpProvider(options = {}) {
+    const request = options.fetch ?? fetch;
+    // The keyserver is the operator's choice; a directory's host is a stranger's, named by
+    // an address on their key, so where it resolves is checked on the connection itself.
+    // Off Node that cannot be done, and the directory is skipped rather than read unguarded:
+    // it only ever upgrades a fingerprint to an address.
+    const directory = options.fetch ?? (pinnable() ? publicFetch() : undefined);
+    const keyserver = new URL(options.keyserver ?? 'https://keys.openpgp.org');
+    if (keyserver.protocol !== 'https:')
+        throw new Error('Keyserver must be HTTPS');
+    /**
+     * The key as the keyserver has it, with everything that arrived with it pointed back at
+     * the key already held. Nothing in the served copy is believed for having been served.
+     */
+    async function served(held) {
+        const response = await request(new URL(`/vks/v1/by-fingerprint/${fingerprint(held)}`, keyserver).href, {
+            headers: { Accept: 'application/pgp-keys' },
+            // Workers refuse 'error'. A redirect comes back as a response that is not ok.
+            redirect: 'manual',
+            signal: AbortSignal.timeout(15000),
+        });
+        let text;
+        try {
+            // Never uploaded, or since deleted. There is nowhere for anything to be published,
+            // which is not the same as nothing having been published anywhere.
+            if (response.status === 404)
+                return undefined;
+            if (!response.ok)
+                throw new Error('Keyserver unavailable');
+            text = new TextDecoder().decode((await readBounded(response, maxKeyBytes)).bytes);
+        }
+        finally {
+            await discard(response);
+        }
+        const copy = await readCertificate(text);
+        // The packets come from the keyserver, and are only ever checked against this key: the
+        // fingerprint is a hash of the key itself, so a copy under it holds the same one.
+        return fingerprint(copy) === fingerprint(held) ? copy : undefined;
+    }
+    /**
+     * A key published at a mailbox's own well-known address. Fetched from a host named by a
+     * stranger's key, so it is a GET to a fixed path on an https origin at a public address
+     * and nothing else: no redirects to follow, a deadline, and a bounded read.
+     */
+    async function published(url) {
+        if (!directory)
+            return undefined;
+        const response = await directory(url, {
+            headers: { Accept: 'application/octet-stream' },
+            redirect: 'manual',
+            signal: AbortSignal.timeout(10000),
+        });
+        let body;
+        try {
+            if (!response.ok)
+                return undefined;
+            body = (await readBounded(response, maxKeyBytes)).bytes;
+        }
+        finally {
+            await discard(response);
+        }
+        const text = new TextDecoder().decode(body.subarray(0, 40));
+        // The scheme says packets. Some hosts serve armour anyway, and both are the same key.
+        return text.includes('-----BEGIN')
+            ? readCertificate(new TextDecoder().decode(body))
+            : readKey(body);
+    }
+    /**
+     * Whether the domain owning one of this key's addresses publishes this very key for it.
+     * The address is in the url, so an answer carrying our fingerprint is that domain saying
+     * the mailbox and the key belong together. Only addresses the key signed for are asked
+     * about, and only a couple of them, since each one costs requests to somebody else's host.
+     */
+    async function byDomain(held) {
+        for (const name of (await identities(held)).slice(0, 2)) {
+            const mailbox = address(name);
+            for (const url of wkdUrls(mailbox)) {
+                try {
+                    const key = await published(url);
+                    if (key && fingerprint(key) === fingerprint(held))
+                        return mailbox;
+                }
+                catch {
+                    // Unreachable, redirected, or not a key. The next place, then nothing.
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * An address, but only where two parties who cannot stand in for each other have both
+     * said it: the key signed for it, and either a keyserver that confirms addresses or the
+     * mailbox's own domain publishes the key under it.
+     *
+     * Either one alone is worth nothing. Minting a key that signs for `support@bank.example`
+     * takes seconds, so a self-signed address printed beside a real proof would read as
+     * established when nobody had established anything. A keyserver saying it alone is no
+     * better, since a served packet is not evidence until the held key has signed it.
+     *
+     * Together they still say only that somebody could read that mailbox on the day they
+     * confirmed it. That is why the fingerprint is carried alongside and never replaced.
+     */
+    async function confirmed(held) {
+        let copy;
+        try {
+            copy = await served(held);
+        }
+        catch {
+            // Unreachable. Nothing is concluded from it, and the other source is still asked.
+            copy = undefined;
+        }
+        const [name] = copy ? await identities(copy) : [];
+        // The keyserver is asked first because it is one request and answers directly. The
+        // directory is the stronger answer, and is what covers a key uploaded nowhere.
+        return name ? address(name) : await byDomain(held);
+    }
+    return {
+        id: 'openpgp',
+        name: 'OpenPGP',
+        method: 'signature',
+        artifact: 'document',
+        instructions: (expect) => [
+            'Sign the line with your key:',
+            { code: `printf '%s\\n' '${expect}' | gpg --clearsign` },
+            'Export the key that signed it:',
+            { code: 'gpg --armor --export YOUR_KEY_ID' },
+            'Paste the signed message below, then the key.',
+            `Your key shows as its fingerprint. To show an email address instead, confirm it at ${keyserver.host} or publish your key in that domain's web key directory.`,
+        ],
+        async verify({ artifact, expect }) {
+            const certificate = await readCertificate(artifact);
+            const message = await readCleartext(artifact);
+            if (!(await signed(certificate, message)))
+                throw new Refused('Signature does not check out');
+            // The line must stand on its own. A token buried inside a longer sentence was signed
+            // too, but it was not necessarily agreed to, and the holder is agreeing to a sentence.
+            if (!message
+                .getText()
+                .split('\n')
+                .some((line) => line.trim() === expect))
+                throw new Refused('Signed message does not contain the line');
+            return {
+                id: fingerprint(certificate),
+                kind: 'key',
+                // What a reader recognises is an address, not forty hex digits. It is shown only
+                // where it was confirmed, and the fingerprint stands in wherever it was not.
+                handle: (await confirmed(certificate)) ?? short(fingerprint(certificate)),
+                profileUrl: new URL(`/search?q=0x${fingerprint(certificate)}`, keyserver).href,
+            };
+        },
+        async withdrawn(account, artifact) {
+            const held = await readCertificate(artifact);
+            if (fingerprint(held) !== account.id)
+                return false;
+            const copy = await served(held);
+            // A revocation counts because the key signed it, not because it was handed over.
+            return copy ? revoked(copy) : false;
+        },
+    };
+}
+/**
+ * The address out of a user id, which is written `Some Name <somebody@example.test>`. The
+ * address is the part that was confirmed; the name beside it is decoration anybody could
+ * have typed, and showing them together would invite reading the name as established too.
+ */
+function address(userId) {
+    return (userId.match(/<([^>]{1,200})>/)?.[1] ?? userId).trim().slice(0, 200);
+}
+/** The last sixteen digits, in the groups of four that fingerprints are read in. */
+function short(fingerprint) {
+    return (fingerprint.slice(-16).match(/.{4}/g) ?? []).join(' ');
+}

package/dist/server/public-fetch.d.ts

@@ -0,0 +1,23 @@
+/** What a name resolved to, as `dns.lookup(name, { all: true })` gives it. */
+export type Resolve = (host: string) => Promise<{
+    address: string;
+    family: number;
+}[]>;
+export type Fetch = (url: string, init: RequestInit) => Promise<Response>;
+/**
+ * A fetch that only ever connects to public addresses. Checking the name before fetching
+ * is not enough: whoever runs its DNS can answer the check with a public address and the
+ * fetch with an internal one. So the check runs inside the connection's own lookup, and
+ * the socket connects to exactly the address that passed. A name with any internal
+ * address among its answers is refused outright rather than raced, and an address written
+ * into the URL, which no lookup sees, is checked before connecting.
+ *
+ * Node only, since it needs a say in how the socket resolves; the request itself is
+ * undici's `fetch`, the one Node's own is built on, so the response is read and checked as
+ * `fetch` reads it. A redirect is never followed, and is reported as an error.
+ *
+ * `allowed` decides which addresses may be connected to, and is only for tests.
+ */
+export declare function publicFetch(resolve?: Resolve, allowed?: (address: string) => boolean): Fetch;
+/** Whether this runtime is Node, the only one that lets `publicFetch()` pin its lookup. */
+export declare function pinnable(): boolean;

package/dist/server/public-fetch.js

@@ -0,0 +1,62 @@
+/**
+ * A fetch that only ever connects to public addresses. Checking the name before fetching
+ * is not enough: whoever runs its DNS can answer the check with a public address and the
+ * fetch with an internal one. So the check runs inside the connection's own lookup, and
+ * the socket connects to exactly the address that passed. A name with any internal
+ * address among its answers is refused outright rather than raced, and an address written
+ * into the URL, which no lookup sees, is checked before connecting.
+ *
+ * Node only, since it needs a say in how the socket resolves; the request itself is
+ * undici's `fetch`, the one Node's own is built on, so the response is read and checked as
+ * `fetch` reads it. A redirect is never followed, and is reported as an error.
+ *
+ * `allowed` decides which addresses may be connected to, and is only for tests.
+ */
+export function publicFetch(resolve = system, allowed) {
+    let dispatcher;
+    return async (url, init) => {
+        const { Agent, fetch } = await import('undici');
+        const { isIP } = await import('node:net');
+        const permitted = allowed ?? (await import('./addresses.js')).publicAddress;
+        const host = new URL(url).hostname.replace(/^\[(.*)\]$/, '$1');
+        if (isIP(host) && !permitted(host))
+            throw new Error('Not an address this can read');
+        // Every connection this pools is made through that lookup.
+        dispatcher ??= new Agent({ connect: { lookup: pinned(resolve, permitted) } });
+        try {
+            const response = await fetch(url, {
+                ...init,
+                redirect: 'error',
+                dispatcher,
+            });
+            return response;
+        }
+        catch (error) {
+            // `fetch` reports every network failure as "fetch failed", with the reason beneath.
+            throw error instanceof TypeError && error.cause instanceof Error ? error.cause : error;
+        }
+    };
+}
+/** A lookup that answers only with addresses that are all permitted, or not at all. */
+function pinned(resolve, permitted) {
+    return (hostname, options, callback) => {
+        resolve(hostname).then((addresses) => {
+            if (!addresses.length || !addresses.every(({ address }) => permitted(address))) {
+                callback(new Error('Not an address this can read'), '', 0);
+                return;
+            }
+            if (options.all)
+                callback(null, addresses);
+            else
+                callback(null, addresses[0].address, addresses[0].family);
+        }, (error) => callback(error, '', 0));
+    };
+}
+/** Whether this runtime is Node, the only one that lets `publicFetch()` pin its lookup. */
+export function pinnable() {
+    return globalThis.navigator?.userAgent?.startsWith('Node.js/') ?? false;
+}
+const system = async (host) => {
+    const { lookup } = await import('node:dns/promises');
+    return lookup(host, { all: true, verbatim: true });
+};

package/dist/server/resend.d.ts

@@ -0,0 +1,13 @@
+import type { EmailMessage } from './email.js';
+/**
+ * A `send` for `emailProvider()` that goes through Resend's HTTP API. It needs nothing but
+ * `fetch` and a key, so it runs wherever this library does, a Worker included. A message Resend did not accept rejects,
+ * which fails the flow that asked for it, and what Resend said is dropped with the rest
+ * of the response: it can name the key's account and is nobody's to read.
+ */
+export declare function resendSender(options: {
+    apiKey: string;
+    /** The sender, as `Name <address>` or an address, on a domain verified with Resend. */
+    from: string;
+    fetch?: typeof fetch;
+}): (message: EmailMessage) => Promise<void>;

package/dist/server/resend.js

@@ -0,0 +1,37 @@
+/**
+ * A `send` for `emailProvider()` that goes through Resend's HTTP API. It needs nothing but
+ * `fetch` and a key, so it runs wherever this library does, a Worker included. A message Resend did not accept rejects,
+ * which fails the flow that asked for it, and what Resend said is dropped with the rest
+ * of the response: it can name the key's account and is nobody's to read.
+ */
+export function resendSender(options) {
+    const request = options.fetch ?? fetch;
+    return async ({ to, subject, text, html, images }) => {
+        const response = await request('https://api.resend.com/emails', {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${options.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                from: options.from,
+                to: [to],
+                subject,
+                text,
+                html,
+                // Attached under a content id, which is what makes Resend send an image inline.
+                attachments: images.map((image) => ({
+                    filename: image.filename,
+                    content: image.content,
+                    content_type: image.contentType,
+                    content_id: image.contentId,
+                })),
+            }),
+            redirect: 'manual',
+            signal: AbortSignal.timeout(15000),
+        });
+        await response.body?.cancel();
+        if (!response.ok)
+            throw new Error('Mail was not accepted');
+    };
+}