@bkazemi/verily 0.4.0 → 0.6.0

package/dist/server/domain.d.ts

@@ -1,11 +1,25 @@
 import { type ArtifactProvider } from '../core/index.js';
-export interface DomainProviderOptions {
-    /** Shown as "Verify with …". */
-    name?: string;
-    /** Replaces the transport. For `dnsProvider()` that is only ever the resolver. */
+export interface DnsOptions {
+    /** Replaces the transport, which is only ever asked for the resolver. */
     fetch?: typeof fetch;
     timeoutMs?: number;
 }
+export interface DomainProviderOptions extends DnsOptions {
+    /** Shown as "Verify with …". */
+    name?: string;
+}
+/** What a domain publishes for Verily, as one lookup found it. */
+export interface Published {
+    /** The lookup that was run, which is also a link a reader can open. */
+    lookup: string;
+    /** The text of every TXT record at `_verily.<domain>` that could be read. */
+    values: string[];
+    /**
+     * Whether the resolver validated the answer with DNSSEC. Only a domain that signs its
+     * zone gets this, and without it the answer is as good as the resolver's own lookup.
+     */
+    dnssec: boolean;
+}
 export interface WellKnownProviderOptions extends DomainProviderOptions {
     /**
      * Domains this instance will read, lowercase. Omitted means any public host, which is
@@ -22,8 +36,8 @@ export interface WellKnownProviderOptions extends DomainProviderOptions {
     maxBytes?: number;
 }
 /**
- * Proves a domain by a record in its DNS. The holder publishes the local subject's address
- * in a TXT record at `_verily.<domain>` and names the domain; this looks the record up and
+ * Proves a domain by a record in its DNS. The holder publishes the local subject's address,
+ * or a string minted for them where the subject has none, in a TXT record at `_verily.<domain>` and names the domain; this looks the record up and
  * checks the address is there. It reaches a domain that serves no page of its own, or only
  * forwards somewhere else, which a link back never can.
  *
@@ -32,14 +46,66 @@ export interface WellKnownProviderOptions extends DomainProviderOptions {
  * nothing is said about a parent or a subdomain. A domain changes hands like an account,
  * and takes the record with it or drops it.
  *
- * Like a link back, the proof is a standing statement and not a per-flow token, so
- * freshness comes from `recheck()` looking it up again. A lookup that could not be made is
+ * Like a link back, the proof is a standing statement, so freshness comes from `recheck()`
+ * looking it up again and a renewal asks for the record already there. A lookup that could not be made is
  * unread, never absent.
  */
 export declare function dnsProvider(options?: DomainProviderOptions): ArtifactProvider;
 /**
- * Proves a domain by a file it serves. The holder puts the local subject's address on a
- * line of `/.well-known/verily.txt` and names the domain; this reads the file and checks
+ * Everything a domain publishes at `_verily.<domain>`, and whether the resolver validated
+ * it. One name carries every statement a domain makes here, told apart by how each begins:
+ * a subject's address or a minted proof, a signing key, a verifier.
+ *
+ * Throws `Refused` where the lookup gave no answer. A name with no records is an answer.
+ */
+export declare function published(domain: string, options?: DnsOptions): Promise<Published>;
+/**
+ * What a verifier publishes at `_verily.<its host>` to name a signing key: one record for
+ * each key. A reader holding a signed record and nothing else can then ask the verifier's
+ * domain, and not the verifier's server, whether the key that signed it is the domain's.
+ */
+export declare function keyRecord(fingerprint: string): string;
+/** What a site publishes at `_verily.<its host>` to name the verifier that speaks for it. */
+export declare function verifierRecord(host: string): string;
+/**
+ * The fingerprints of the signing keys a domain names in its DNS. A signed record names the
+ * key that signed it and the verifier's address, so a key found here is one the domain in
+ * that address answers for, for as long as the domain is kept and whatever became of the
+ * server. Check the signature with `verifySigned()` first: this says whose a key is, and
+ * nothing about what it signed.
+ */
+export declare function dnsKeys(domain: string, options?: DnsOptions): Promise<Omit<Published, 'values'> & {
+    ids: string[];
+}>;
+/**
+ * The hosts of the verifiers a site's domain names in its DNS. A record's local side is
+ * the verifier's word for what the site told it, so a verifier named here is one the site
+ * itself chose, which a reader can find out without visiting the site.
+ */
+export declare function dnsVerifiers(domain: string, options?: DnsOptions): Promise<Omit<Published, 'values'> & {
+    hosts: string[];
+}>;
+/**
+ * The fingerprints a domain's records name, in the upper case a key's id is kept in. A
+ * fingerprint is hexadecimal, so however it was typed it names the same key.
+ */
+export declare function namedKeys(values: string[]): string[];
+/**
+ * The verifier hosts a domain's records name, lowercase as a host compares, each with the
+ * record as it is published: that text is what a reader finds at the lookup.
+ */
+export declare function namedVerifiers(values: string[]): {
+    host: string;
+    record: string;
+}[];
+/**
+ * The name a URL's host is looked up under, or nothing where it is not a public domain: an
+ * address literal, a single label, a name inside the network.
+ */
+export declare function domainOf(url: string): string | undefined;
+/**
+ * Proves a domain by a file it serves. The holder puts the local subject's address, or a
+ * string minted for them where the subject has none, on a line of `/.well-known/verily.txt` and names the domain; this reads the file and checks
  * the line is there. It is for a holder who can add a file to a site and cannot reach its
  * DNS or its pages' markup.
  *

package/dist/server/domain.js

@@ -23,9 +23,13 @@ const label = '_verily';
 const path = '/.well-known/verily.txt';
 /** The TXT record type, as the resolver numbers it. */
 const txt = 16;
+/** What a signing key's record says, before the key's fingerprint. */
+const keyPrefix = 'verily-key=';
+/** What a site's record says, before the host of the verifier it chose. */
+const verifierPrefix = 'verily-verifier=';
 /**
- * Proves a domain by a record in its DNS. The holder publishes the local subject's address
- * in a TXT record at `_verily.<domain>` and names the domain; this looks the record up and
+ * Proves a domain by a record in its DNS. The holder publishes the local subject's address,
+ * or a string minted for them where the subject has none, in a TXT record at `_verily.<domain>` and names the domain; this looks the record up and
  * checks the address is there. It reaches a domain that serves no page of its own, or only
  * forwards somewhere else, which a link back never can.
  *
@@ -34,12 +38,18 @@ const txt = 16;
  * nothing is said about a parent or a subdomain. A domain changes hands like an account,
  * and takes the record with it or drops it.
  *
- * Like a link back, the proof is a standing statement and not a per-flow token, so
- * freshness comes from `recheck()` looking it up again. A lookup that could not be made is
+ * Like a link back, the proof is a standing statement, so freshness comes from `recheck()`
+ * looking it up again and a renewal asks for the record already there. A lookup that could not be made is
  * unread, never absent.
  */
 export function dnsProvider(options = {}) {
-    const request = options.fetch ?? fetch;
+    const prove = async ({ artifact, expect }) => {
+        const domain = looked(artifact);
+        const { values, dnssec } = await published(domain, options);
+        if (!values.includes(expect))
+            throw new Refused(`No TXT record at ${label}.${domain} has this value`);
+        return { account: account(domain), ...(dnssec ? { dnssec } : {}) };
+    };
     return {
         ...shared(options),
         method: 'dns',
@@ -53,47 +63,126 @@ export function dnsProvider(options = {}) {
             const domain = named(artifact);
             return domain ? lookup(domain) : artifact;
         },
-        async verify({ artifact, expect }) {
-            const domain = looked(artifact);
-            // Why the resolver could not be asked is about the network this runs in.
-            const response = await request(lookup(domain), {
-                redirect: 'manual',
-                headers: { Accept: 'application/dns-json', 'User-Agent': 'Verily-V0' },
-                signal: AbortSignal.timeout(options.timeoutMs ?? 15000),
-            }).catch(() => {
-                throw new Refused('DNS could not be read');
-            });
-            let answer;
-            try {
-                if (!response.ok)
-                    throw new Refused('DNS could not be read');
-                const { bytes, truncated } = await readBounded(response, 64 * 1024);
-                if (truncated)
-                    throw new Refused('DNS could not be read');
-                answer = parsed(new TextDecoder().decode(bytes));
-            }
-            finally {
-                await discard(response);
-            }
-            // A cut-off answer may have left out the record that would have matched.
-            if (!isRecord(answer) || answer.TC === true)
-                throw new Refused('DNS could not be read');
-            // The name not existing is an answer; anything else that is not success is no answer.
-            if (answer.Status !== 0 && answer.Status !== 3)
-                throw new Refused('DNS could not be read');
-            const records = Array.isArray(answer.Answer) ? answer.Answer : [];
-            if (!records.some((record) => isRecord(record) &&
-                record.type === txt &&
-                typeof record.data === 'string' &&
-                text(record.data) === expect))
-                throw new Refused(`No TXT record at ${label}.${domain} names this subject`);
-            return account(domain);
-        },
+        verify: async (input) => (await prove(input)).account,
+        // The resolver says whether it validated the answer, which is worth keeping with it.
+        prove,
+    };
+}
+/**
+ * Everything a domain publishes at `_verily.<domain>`, and whether the resolver validated
+ * it. One name carries every statement a domain makes here, told apart by how each begins:
+ * a subject's address or a minted proof, a signing key, a verifier.
+ *
+ * Throws `Refused` where the lookup gave no answer. A name with no records is an answer.
+ */
+export async function published(domain, options = {}) {
+    if (!valid(domain))
+        throw new Refused('Not a domain this can look up');
+    // Why the resolver could not be asked is about the network this runs in.
+    const response = await (options.fetch ?? fetch)(lookup(domain), {
+        redirect: 'manual',
+        headers: { Accept: 'application/dns-json', 'User-Agent': 'Verily-V0' },
+        signal: AbortSignal.timeout(options.timeoutMs ?? 15000),
+    }).catch(() => {
+        throw new Refused('DNS could not be read');
+    });
+    let answer;
+    try {
+        if (!response.ok)
+            throw new Refused('DNS could not be read');
+        const { bytes, truncated } = await readBounded(response, 64 * 1024);
+        if (truncated)
+            throw new Refused('DNS could not be read');
+        answer = parsed(new TextDecoder().decode(bytes));
+    }
+    finally {
+        await discard(response);
+    }
+    // A cut-off answer may have left out the record that would have matched.
+    if (!isRecord(answer) || answer.TC === true)
+        throw new Refused('DNS could not be read');
+    // The name not existing is an answer; anything else that is not success is no answer.
+    if (answer.Status !== 0 && answer.Status !== 3)
+        throw new Refused('DNS could not be read');
+    const records = Array.isArray(answer.Answer) ? answer.Answer : [];
+    return {
+        lookup: lookup(domain),
+        values: records
+            .map((record) => isRecord(record) && record.type === txt && typeof record.data === 'string'
+            ? text(record.data)
+            : undefined)
+            .filter((value) => value !== undefined),
+        // The resolver sets this only where every record in the answer validated.
+        dnssec: answer.AD === true,
     };
 }
 /**
- * Proves a domain by a file it serves. The holder puts the local subject's address on a
- * line of `/.well-known/verily.txt` and names the domain; this reads the file and checks
+ * What a verifier publishes at `_verily.<its host>` to name a signing key: one record for
+ * each key. A reader holding a signed record and nothing else can then ask the verifier's
+ * domain, and not the verifier's server, whether the key that signed it is the domain's.
+ */
+export function keyRecord(fingerprint) {
+    return `${keyPrefix}${fingerprint}`;
+}
+/** What a site publishes at `_verily.<its host>` to name the verifier that speaks for it. */
+export function verifierRecord(host) {
+    return `${verifierPrefix}${host.toLowerCase()}`;
+}
+/**
+ * The fingerprints of the signing keys a domain names in its DNS. A signed record names the
+ * key that signed it and the verifier's address, so a key found here is one the domain in
+ * that address answers for, for as long as the domain is kept and whatever became of the
+ * server. Check the signature with `verifySigned()` first: this says whose a key is, and
+ * nothing about what it signed.
+ */
+export async function dnsKeys(domain, options = {}) {
+    const { values, ...found } = await published(named(domain) ?? domain, options);
+    return { ...found, ids: namedKeys(values) };
+}
+/**
+ * The hosts of the verifiers a site's domain names in its DNS. A record's local side is
+ * the verifier's word for what the site told it, so a verifier named here is one the site
+ * itself chose, which a reader can find out without visiting the site.
+ */
+export async function dnsVerifiers(domain, options = {}) {
+    const { values, ...found } = await published(named(domain) ?? domain, options);
+    return { ...found, hosts: namedVerifiers(values).map(({ host }) => host) };
+}
+/**
+ * The fingerprints a domain's records name, in the upper case a key's id is kept in. A
+ * fingerprint is hexadecimal, so however it was typed it names the same key.
+ */
+export function namedKeys(values) {
+    return stated(values, keyPrefix).map((id) => id.toUpperCase());
+}
+/**
+ * The verifier hosts a domain's records name, lowercase as a host compares, each with the
+ * record as it is published: that text is what a reader finds at the lookup.
+ */
+export function namedVerifiers(values) {
+    return values
+        .filter((value) => value.startsWith(verifierPrefix))
+        .map((record) => ({ host: record.slice(verifierPrefix.length).trim().toLowerCase(), record }))
+        .filter(({ host }) => host);
+}
+/** What follows a prefix in each record that begins with it. */
+function stated(values, prefix) {
+    return values
+        .filter((value) => value.startsWith(prefix))
+        .map((value) => value.slice(prefix.length).trim())
+        .filter(Boolean);
+}
+/**
+ * The name a URL's host is looked up under, or nothing where it is not a public domain: an
+ * address literal, a single label, a name inside the network.
+ */
+export function domainOf(url) {
+    const host = URL.parse(url)?.hostname.toLowerCase().replace(/\.$/, '');
+    return host !== undefined && valid(host) ? host : undefined;
+}
+/**
+ * Proves a domain by a file it serves. The holder puts the local subject's address, or a
+ * string minted for them where the subject has none, on a line of `/.well-known/verily.txt` and names the domain; this reads the file and checks
  * the line is there. It is for a holder who can add a file to a site and cannot reach its
  * DNS or its pages' markup.
  *
@@ -110,7 +199,7 @@ export function wellKnownProvider(options = {}) {
         ...shared(options),
         method: 'wellknown',
         instructions: (expect) => [
-            'Serve a plain text file at this path on your domain, with this address on a line of its own, then enter the domain below.',
+            'Serve a plain text file at this path on your domain, with this on a line of its own, then enter the domain below.',
             { code: path },
             { code: expect },
         ],
@@ -144,7 +233,7 @@ export function wellKnownProvider(options = {}) {
                 if (truncated)
                     lines.pop();
                 if (!lines.some((line) => line.trim() === expect))
-                    throw new Refused(truncated ? 'File is too large to read' : 'File has no line naming this subject');
+                    throw new Refused(truncated ? 'File is too large to read' : 'File has no line with this value');
             }
             finally {
                 await discard(response);
@@ -161,12 +250,12 @@ function shared(options) {
         artifact: 'location',
         field: 'Your domain',
         input: 'text',
-        // The subject's own address is the entire claim, so there is nothing per-flow to mint.
-        expect(local) {
-            if (!local.profileUrl)
-                throw new Error('A domain proof needs a local subject with a profileUrl to name');
-            return local.profileUrl;
-        },
+        // The subject's own address is the entire claim, where it has one. A subject with no
+        // page a reader could open has nothing to name, and is proved by a minted string.
+        expect: (local) => local.profileUrl,
+        // DNS and a well-known path are read by anyone, unasked. A subject with no public page
+        // is one its site keeps private, so the string says nothing of the site either.
+        mint: (secret) => `verily-proof=${secret}`,
         // A domain is where it says it is, so a record of one already says where to look.
         known: (account) => (account.kind === 'domain' ? account.id : undefined),
     };

package/dist/server/index.d.ts

@@ -7,7 +7,7 @@ export { discordProvider } from './discord.js';
 export { youtubeProvider } from './youtube.js';
 export { githubGistProvider } from './github-gist.js';
 export { linkProvider, githubLinkProvider, type LinkProviderOptions } from './link.js';
-export { dnsProvider, wellKnownProvider, type DomainProviderOptions, type WellKnownProviderOptions, } from './domain.js';
+export { dnsProvider, wellKnownProvider, dnsKeys, dnsVerifiers, keyRecord, verifierRecord, type DnsOptions, type DomainProviderOptions, type Published, type WellKnownProviderOptions, } from './domain.js';
 export { pgpProvider } from './pgp.js';
 export { generateSigningKey, signer } from './signing.js';
 export { emailProvider, type EmailImage, type EmailMessage, type EmailProviderOptions, } from './email.js';