@bkazemi/verily 0.2.0 → 0.4.0

package/dist/core/index.d.ts

@@ -2,9 +2,16 @@ export type Visibility = 'public' | 'unlisted';
 /**
  * `unconfirmed` is a published proof that has not been read lately. It is not disproved,
  * and turns back to `verified` the moment the proof reads again. `expired` is an approval
- * that ran out, which only the holder renewing it undoes.
+ * that ran out, which only the holder renewing it undoes. `retired` is an account its
+ * holder said is finished: the record is kept as it stood at its last proof and never
+ * reads as verified again, unless that proof is made afresh.
  */
-export type Status = 'verified' | 'unconfirmed' | 'expired' | 'revoked';
+export type Status = 'verified' | 'unconfirmed' | 'expired' | 'retired' | 'revoked';
+/**
+ * How the holder would have an account listed: the one to lead with, or one they still
+ * control and no longer use. The holder's own statement, and no part of what was verified.
+ */
+export type Mark = 'preferred' | 'unused';
 /** What a site links: one of its accounts, a single page, or the site itself. */
 export type LocalKind = 'account' | 'page' | 'site';
 /** id is private and must never be reassigned. reference is durable and public-safe. */
@@ -30,9 +37,11 @@ export interface ExternalAccount {
      * A page is an address that was read and nothing more: a method that only fetches a
      * document learns what it says, never whose account the address is. A mailbox is an
      * account in all but how it is written: its domain issued it and can hand it to somebody
-     * else, but its address is already its whole name and it has no profile to link to.
+     * else, but its address is already its whole name and it has no profile to link to. A
+     * domain is likewise issued and can be handed over, and is named by itself: what was
+     * shown is control of the name, whatever is or is not served at it.
      */
-    kind?: 'account' | 'key' | 'page' | 'mailbox';
+    kind?: 'account' | 'key' | 'page' | 'mailbox' | 'domain';
     handle: string;
     /** Where a reader goes to see the subject. For a mailbox, its `mailto:` address. */
     profileUrl: string;
@@ -47,7 +56,7 @@ export interface ExternalAccount {
  * source could improve on it. A sign-in and a mailed code happen once, between the holder
  * and this backend. The rest publish an artifact a reader can fetch.
  */
-export type Method = 'declared' | 'oauth' | 'gist' | 'backlink' | 'signature' | 'code';
+export type Method = 'declared' | 'oauth' | 'gist' | 'backlink' | 'dns' | 'wellknown' | 'signature' | 'code';
 /** Who vouches for one side: this backend from its own records, or the account's provider. */
 export type Attester = 'backend' | 'provider';
 /**
@@ -106,6 +115,13 @@ export interface Connection {
     attestations?: Attestations;
     /** The proof itself, for a method whose artifact this backend publishes rather than reads. */
     proof?: string;
+    /** Set and cleared by the holder. Absent is an ordinary current account. */
+    mark?: Mark;
+    /**
+     * When the holder said the account is finished. From then the record is frozen at its
+     * last proof: never renewed by another method, never reread, never verified.
+     */
+    retiredAt?: number;
 }
 export interface Flow {
     id: string;
@@ -426,10 +442,17 @@ export interface Evidence {
     visibilityApprovedAt: number;
     expiresAt: number;
     revokedAt?: number;
+    /**
+     * What the holder says of the account, and when they said it was finished. Both are the
+     * holder's statements, beside the attestations and never among them: nothing checked them.
+     */
+    mark?: Mark;
+    retiredAt?: number;
     evidenceUrl: string;
     /**
      * Where this record can be had signed, on a verifier that signs. Only a public record
-     * that stands has a signed form: once saved, a signed record cannot be taken back.
+     * that stands, or one retired, has a signed form: once saved, a signed record cannot be
+     * taken back.
      */
     signedUrl?: string;
 }
@@ -452,6 +475,11 @@ export declare function status(connection: Connection, now: number, freshness?:
  * reverses the moment it reads again.
  */
 export declare function fresh(attestation: Attestation, now: number, freshness?: number): boolean;
+/**
+ * The date a retired record stands on: when its account was last proved. A sign-in was
+ * proved when it happened, and a published proof when it was last read.
+ */
+export declare function lastProved(evidence: Pick<Evidence, 'authenticatedAt' | 'attestations'>): number;
 /**
  * The word for a record's state. Evidence can be read after it was issued, so an approval
  * that has run out since reads as expired whatever status it was issued with.
@@ -488,6 +516,11 @@ export declare function attestationLabel(method: string, names: {
     site: string;
     provider: string;
 }): string | undefined;
+/**
+ * A subject's second identifier, shown beneath its name, or nothing where the name is
+ * already all of it: a mailbox's address and a domain are each their own id.
+ */
+export declare function externalId(external: ExternalAccount): string | undefined;
 /**
  * Where a subject's name may link, or nothing where it has no page of its own. A mailbox's
  * address is `mailto:`, which opens a message to it and shows a reader nothing.

package/dist/core/index.js

@@ -35,6 +35,9 @@ export const freshnessMs = 7 * 86400000;
 export function status(connection, now, freshness = freshnessMs) {
     if (connection.revokedAt !== undefined)
         return 'revoked';
+    // Frozen at its last proof, so neither its expiry nor its freshness is read again.
+    if (connection.retiredAt !== undefined)
+        return 'retired';
     if (now >= connection.expiresAt)
         return 'expired';
     const main = connection.attestations?.external[0];
@@ -53,6 +56,14 @@ export function fresh(attestation, now, freshness = freshnessMs) {
         freshness === Infinity ||
         now < attestation.confirmedAt + freshness);
 }
+/**
+ * The date a retired record stands on: when its account was last proved. A sign-in was
+ * proved when it happened, and a published proof when it was last read.
+ */
+export function lastProved(evidence) {
+    const main = evidence.attestations.external[0];
+    return main.artifactUrl ? main.confirmedAt : evidence.authenticatedAt;
+}
 /**
  * The word for a record's state. Evidence can be read after it was issued, so an approval
  * that has run out since reads as expired whatever status it was issued with.
@@ -60,6 +71,9 @@ export function fresh(attestation, now, freshness = freshnessMs) {
 export function statusLabel(evidence, now) {
     if (evidence.status === 'revoked')
         return 'Revoked';
+    // Before expiry: a retired record's approval has long run out, and that is not its state.
+    if (evidence.status === 'retired')
+        return 'Retired';
     if (evidence.status === 'expired' || evidence.expiresAt <= now)
         return 'Expired';
     return evidence.status === 'unconfirmed' ? 'Unconfirmed' : 'Verified';
@@ -107,10 +121,19 @@ export function attestationLabel(method, names) {
         oauth: `Signed in with ${names.provider}`,
         gist: `Published a proof on ${names.provider}`,
         backlink: `Linked back to ${names.site}`,
+        dns: `Named ${names.site} in a DNS record`,
+        wellknown: `Named ${names.site} in a file it serves`,
         signature: 'Proved with a signature',
         code: 'Entered a code sent to this address',
     }[method];
 }
+/**
+ * A subject's second identifier, shown beneath its name, or nothing where the name is
+ * already all of it: a mailbox's address and a domain are each their own id.
+ */
+export function externalId(external) {
+    return external.kind === 'mailbox' || external.kind === 'domain' ? undefined : external.id;
+}
 /**
  * Where a subject's name may link, or nothing where it has no page of its own. A mailbox's
  * address is `mailto:`, which opens a message to it and shows a reader nothing.

package/dist/core/signed.d.ts

@@ -11,15 +11,29 @@ export interface VerifierKey {
     publicKey: string;
 }
 /**
- * What a signature covers: the record as it stood at `issuedAt`. Whether it still stands
- * is a live fact no signature holds, so its status is left out and `evidenceUrl` is where
- * to ask.
+ * What either version says of a record. The holder's mark is left out: it is about how
+ * their accounts are listed, and no part of what was verified.
  */
-export type SignedDocument = Omit<Evidence, 'status' | 'revokedAt' | 'signedUrl'> & {
+type Signable = Omit<Evidence, 'status' | 'revokedAt' | 'signedUrl' | 'mark' | 'retiredAt'> & {
     type: 'verily-evidence';
-    version: 1;
     issuedAt: number;
 };
+/**
+ * What a signature covers: the record as it stood at `issuedAt`. Whether it still stands
+ * is a live fact no signature holds, so version 1 leaves its status out, means the record
+ * stood when it was signed, and gives `evidenceUrl` as where to ask.
+ *
+ * Version 2 is a retired record, which did not stand when it was signed and says so. It is
+ * a version of its own because a reader of version 1 ignores fields it does not know, and
+ * would read a retired record signed as version 1 as one that stood.
+ */
+export type SignedDocument = (Signable & {
+    version: 1;
+}) | (Signable & {
+    version: 2;
+    status: 'retired';
+    retiredAt: number;
+});
 /**
  * A record that can be checked away from the verifier that served it: the document as
  * text under an OpenPGP cleartext signature, which `gpg --verify` reads as it is.
@@ -47,3 +61,4 @@ export declare function signedBy(signed: unknown): Promise<string | undefined>;
  * of it, so the fingerprint a record names is the one a list holds.
  */
 export declare function verifySigned(signed: unknown, keys: VerifierKey[]): Promise<SignedDocument | undefined>;
+export {};

package/dist/core/signed.js

@@ -100,8 +100,11 @@ export async function verifySigned(signed, keys) {
             await signatures[0].verified;
             const document = JSON.parse(data);
             return document?.type === 'verily-evidence' &&
-                document.version === 1 &&
-                typeof document.issuedAt === 'number'
+                typeof document.issuedAt === 'number' &&
+                (document.version === 1 ||
+                    (document.version === 2 &&
+                        document.status === 'retired' &&
+                        typeof document.retiredAt === 'number'))
                 ? document
                 : undefined;
         }

package/dist/server/domain.d.ts

@@ -0,0 +1,51 @@
+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. */
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+export interface WellKnownProviderOptions extends DomainProviderOptions {
+    /**
+     * Domains this instance will read, lowercase. Omitted means any public host, which is
+     * the point of the method and needs Node: see `linkProvider()`.
+     */
+    hosts?: string[];
+    /**
+     * Replaces the transport, and with it the check that keeps an instance reading any host
+     * out of the network it runs in. Pass one only where it enforces that itself, such as
+     * through an egress proxy, or where `hosts` already confines it.
+     */
+    fetch?: typeof fetch;
+    /** How much of the file is read before giving up on finding the line. */
+    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
+ * 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.
+ *
+ * What it establishes is that whoever wrote the record could write that domain's DNS. That
+ * is the domain's holder or somebody they delegated to, and it is the exact name proved:
+ * 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
+ * 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
+ * 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.
+ *
+ * The domain names the host that is fetched, so the read is the web key directory's: HTTPS
+ * on the default port, a public address, no redirect followed, a deadline and a bounded
+ * read. Only `text/plain` is read, because a line in anything else may be an example of a
+ * line and not one.
+ */
+export declare function wellKnownProvider(options?: WellKnownProviderOptions): ArtifactProvider;

package/dist/server/domain.js

@@ -0,0 +1,285 @@
+import { MIMEType } from 'node:util';
+import { Refused, } from '../core/index.js';
+import { discard, readBounded } from './body.js';
+import { transport } from './public-fetch.js';
+/**
+ * Domain suffixes that must never be fetched. The holder names the domain, so it names the
+ * host, and these are the names that can resolve to something inside the network running
+ * this. Reserved suffixes that resolve nowhere are left alone: asking about them is
+ * pointless rather than dangerous, and they are what tests use.
+ */
+const reserved = ['local', 'internal', 'localhost', 'home', 'lan', 'corp', 'intranet'];
+const name = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
+/**
+ * The one resolver every lookup goes to. Fixed, because the holder chooses the name and
+ * nothing else: a resolver they could choose would answer whatever they liked. It is asked
+ * over HTTPS because a Worker has no resolver of its own, and at an address that answers a
+ * plain GET with JSON, so the lookup that was run is also a link a reader can open.
+ */
+const resolver = 'https://dns.google/resolve';
+/** The label the record is published under, so it sits apart from the domain's own records. */
+const label = '_verily';
+/** Where on a domain the file is served. */
+const path = '/.well-known/verily.txt';
+/** The TXT record type, as the resolver numbers it. */
+const txt = 16;
+/**
+ * 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
+ * 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.
+ *
+ * What it establishes is that whoever wrote the record could write that domain's DNS. That
+ * is the domain's holder or somebody they delegated to, and it is the exact name proved:
+ * 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
+ * unread, never absent.
+ */
+export function dnsProvider(options = {}) {
+    const request = options.fetch ?? fetch;
+    return {
+        ...shared(options),
+        method: 'dns',
+        instructions: (expect) => [
+            'Add a TXT record to your domain’s DNS with this name and value, then enter the domain below.',
+            { code: label },
+            { code: expect },
+            'A new record can take a few minutes to be seen.',
+        ],
+        resolve(artifact) {
+            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);
+        },
+    };
+}
+/**
+ * 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
+ * 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.
+ *
+ * The domain names the host that is fetched, so the read is the web key directory's: HTTPS
+ * on the default port, a public address, no redirect followed, a deadline and a bounded
+ * read. Only `text/plain` is read, because a line in anything else may be an example of a
+ * line and not one.
+ */
+export function wellKnownProvider(options = {}) {
+    const request = transport(options);
+    const hosts = options.hosts?.map((host) => host.toLowerCase());
+    const maxBytes = options.maxBytes ?? 64 * 1024;
+    return {
+        ...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.',
+            { code: path },
+            { code: expect },
+        ],
+        resolve(artifact) {
+            const domain = named(artifact);
+            return domain ? `https://${domain}${path}` : artifact;
+        },
+        async verify({ artifact, expect }) {
+            const domain = served(artifact);
+            if (hosts && !hosts.includes(domain))
+                throw new Refused('Not a host this instance reads');
+            const response = await request(`https://${domain}${path}`, {
+                // Workers refuse 'error', so a redirect comes back as a response and is refused below.
+                redirect: 'manual',
+                headers: { Accept: 'text/plain', 'User-Agent': 'Verily-V0' },
+                signal: AbortSignal.timeout(options.timeoutMs ?? 15000),
+            }).catch(() => {
+                throw new Refused('File could not be reached');
+            });
+            try {
+                // The holder named this domain, so a redirect would take the check somewhere else.
+                if (response.type === 'opaqueredirect' || (response.status >= 300 && response.status < 400))
+                    throw new Refused('File redirects, and a redirect is not followed');
+                if (!response.ok)
+                    throw new Refused('File unavailable');
+                if (mediaType(response.headers.get('content-type')) !== 'text/plain')
+                    throw new Refused('File is not plain text');
+                const { bytes, truncated } = await readBounded(response, maxBytes);
+                const lines = new TextDecoder().decode(bytes).split(/\r?\n/);
+                // The last line of a file cut short may be the start of some longer address.
+                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');
+            }
+            finally {
+                await discard(response);
+            }
+            return account(domain);
+        },
+    };
+}
+/** What both methods say of themselves: they name the same thing, and differ in how. */
+function shared(options) {
+    return {
+        id: 'domain',
+        name: options.name ?? 'Domain',
+        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;
+        },
+        // 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),
+    };
+}
+/**
+ * A domain, named by itself. The id is the name as DNS compares it: lowercase, and in
+ * punycode where it was typed in another script.
+ */
+function account(domain) {
+    return { id: domain, kind: 'domain', handle: domain, profileUrl: `https://${domain}/` };
+}
+/**
+ * The domain a holder typed, or nothing where it is not one. Taken bare or as the address
+ * of its front page, since both are how a domain is written, and never with a path: a path
+ * is somebody's page, and this proves no page.
+ */
+function named(typed) {
+    const trimmed = typed.trim();
+    if (trimmed.length > 300)
+        return undefined;
+    const url = URL.parse(/^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`);
+    if (!url || url.username || url.password || url.port || url.search || url.hash)
+        return undefined;
+    if (url.pathname !== '/')
+        return undefined;
+    const domain = url.hostname.toLowerCase().replace(/\.$/, '');
+    return valid(domain) ? domain : undefined;
+}
+/** A dotted public-looking name, as DNS limits one, and not an address literal. */
+function valid(domain) {
+    return (domain.length <= 253 - label.length - 1 &&
+        name.test(domain) &&
+        domain.split('.').every((part) => part.length <= 63) &&
+        !/^[\d.]+$/.test(domain) &&
+        !reserved.includes(domain.split('.').pop()));
+}
+/** The lookup for a domain's record: the address that is fetched, and kept as the proof's. */
+function lookup(domain) {
+    return `${resolver}?name=${label}.${domain}&type=TXT`;
+}
+/**
+ * The domain a lookup address asks about, once it is exactly a lookup this would make. The
+ * address comes back from the holder or from a record, and anything else is somewhere this
+ * has no business fetching.
+ */
+function looked(artifact) {
+    const url = artifact.length <= 600 ? URL.parse(artifact) : null;
+    const asked = url?.searchParams.get('name') ?? '';
+    const domain = asked.startsWith(`${label}.`) ? asked.slice(label.length + 1) : '';
+    if (!url || !valid(domain) || url.href !== lookup(domain))
+        throw new Refused('Not a domain this can look up');
+    return domain;
+}
+/** The domain a file address is on, once it is exactly where this would read one. */
+function served(artifact) {
+    const url = artifact.length <= 600 ? URL.parse(artifact) : null;
+    const domain = url?.hostname.toLowerCase() ?? '';
+    if (!url || !valid(domain) || url.href !== `https://${domain}${path}`)
+        throw new Refused('Not a domain this can read');
+    return domain;
+}
+/**
+ * A TXT record's text. A record is one or more strings joined end to end, and a resolver
+ * writes them either already joined or each in quotes with a backslash before anything
+ * awkward. One this cannot read is no text at all, since a guess could read as a match.
+ */
+function text(data) {
+    if (!data.startsWith('"'))
+        return data.trim();
+    let out = '';
+    let at = 0;
+    while (at < data.length) {
+        if (data[at] === ' ') {
+            at++;
+            continue;
+        }
+        if (data[at] !== '"')
+            return undefined;
+        at++;
+        while (at < data.length && data[at] !== '"') {
+            if (data[at] === '\\') {
+                const code = /^\d{3}/.exec(data.slice(at + 1))?.[0];
+                out += code ? String.fromCharCode(Number(code)) : (data[at + 1] ?? '');
+                at += code ? 4 : 2;
+            }
+            else
+                out += data[at++];
+        }
+        if (data[at] !== '"')
+            return undefined;
+        at++;
+    }
+    return out.trim();
+}
+function parsed(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A `Content-Type`'s essence, or nothing where it is missing or malformed. */
+function mediaType(header) {
+    if (header === null)
+        return undefined;
+    try {
+        return new MIMEType(header).essence;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object';
+}

package/dist/server/index.d.ts

@@ -7,6 +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 { pgpProvider } from './pgp.js';
 export { generateSigningKey, signer } from './signing.js';
 export { emailProvider, type EmailImage, type EmailMessage, type EmailProviderOptions, } from './email.js';