@bkazemi/verily 0.3.0 → 0.5.0

package/README.md

@@ -145,7 +145,7 @@ import { init } from '@bkazemi/verily'; // also registers <verily-badge>
 const client = init({ backendUrl: '/api/verily' });
 ```
 
-Without one, serve `node_modules/@bkazemi/verily/dist/verily.js` yourself, or load it from a CDN such as `https://cdn.jsdelivr.net/npm/@bkazemi/verily@0.3.0/dist/verily.js`. The script defines a global `Verily`.
+Without one, serve `node_modules/@bkazemi/verily/dist/verily.js` yourself, or load it from a CDN such as `https://cdn.jsdelivr.net/npm/@bkazemi/verily@0.5.0/dist/verily.js`. The script defines a global `Verily`.
 
 Then place the badge wherever the account appears:
 
@@ -208,6 +208,8 @@ import {
   githubGistProvider,
   linkProvider,
   githubLinkProvider,
+  dnsProvider,
+  wellKnownProvider,
   pgpProvider,
 } from '@bkazemi/verily';
 ```
@@ -220,10 +222,12 @@ import {
 | `githubGistProvider()` | publishing a public gist containing a line Verily gives them.                                                | None.                                   |
 | `linkProvider()`       | adding a `rel="me"` link to their profile on a page they control.                                            | The local account needs a `profileUrl`. |
 | `githubLinkProvider()` | putting their profile URL in the website field of their GitHub profile, then entering their GitHub username. | The local account needs a `profileUrl`. |
+| `dnsProvider()`        | adding a TXT record to their domain's DNS, then entering the domain.                                         | None.                                   |
+| `wellKnownProvider()`  | serving a text file at a fixed path on their domain, then entering the domain.                               | None.                                   |
 | `pgpProvider()`        | signing a line Verily gives them with their OpenPGP key, then pasting it and the key.                        | None.                                   |
 | `emailProvider()`      | pressing a button, or entering a code, that Verily mails to their address.                                   | A function that sends one message.      |
 
-All methods except the sign-ins and the mailed code let the user publish the proof in their own time and come back. A proof that does not check out can be put right and handed back on the same step, up to five times, so a mistyped address never means publishing or signing again. Gists and link-backs can be taken down later, so Verily re-reads them on a schedule. A PGP signature is kept by Verily and published at `<baseUrl>/connections/<id>/proof`.
+All methods except the sign-ins and the mailed code let the user publish the proof in their own time and come back. A proof that does not check out can be put right and handed back on the same step, up to five times, so a mistyped address never means publishing or signing again. Gists, link-backs, DNS records and files can be taken down later, so Verily re-reads them on a schedule. A PGP signature is kept by Verily and published at `<baseUrl>/connections/<id>/proof`.
 
 **Several at once.** List more than one, and `/verify` offers each method as its own button:
 
@@ -239,6 +243,8 @@ Proving the same account a second way adds that proof to the existing record ins
 
 **Link-backs.** Many people already have one, since GitHub and Mastodon mark profile links `rel="me"`. By default the page may be on any public host, and the account is named by the page's address. This mode needs Node, because Verily checks every connection it makes to stop the page's address from pointing inside your network. Pass `hosts` to read only certain hosts (required on Cloudflare Workers), and `profile` to name the account by handle, as `githubLinkProvider()` does for github.com. If you pass your own `fetch`, it replaces that network check, so it must enforce the same rule itself. Only real `<a>` and `<link>` elements in HTML pages, or a `Link:` header, count; [`src/server/link.ts`](src/server/link.ts) has the exact rules.
 
+**Domains.** `dnsProvider()` proves a domain that serves no page of its own, or only forwards elsewhere. The user adds a TXT record named `_verily` whose value is their `profileUrl`, and enters the domain. Verily looks up `_verily.<domain>` through `https://dns.google/resolve`, a fixed resolver, so it runs on Cloudflare Workers, and the evidence links to that lookup for a reader to repeat. `wellKnownProvider()` reads `https://<domain>/.well-known/verily.txt` instead and looks for the `profileUrl` on a line of its own. It fetches a host the user names, so it follows the link-back's rules: Node, or `hosts`. Both name the account by the exact domain entered, and say nothing about its subdomains. Where the resolver validated the DNS answer with DNSSEC, the proof records it and the evidence says so; a domain that does not sign its zone is proved all the same, on the resolver's own lookup. `recheck()` updates the flag at each read. A local account with no `profileUrl` has no address to publish, so the user is given a random value, `verily-proof=…`, instead. It names neither the account nor your site, since DNS is public, and a renewal asks for the same value, so the record is added once. List both and a domain proved one way picks up the other if it is already there.
+
 **Your own method.** A provider is an object, and [`src/core/index.ts`](src/core/index.ts) documents each shape. An artifact provider may also set `field` and `input` to name what it asks for, `resolve` to turn something short such as a username into the address to read, and `known` to say where to look for an account already on record, which is what lets a proof be found without asking. A sign-in provider's `authorizationUrl` is passed `account` on a renewal or visibility change, so it can ask for that account by name.
 
 If you start flows by calling `service.start()` yourself, pass `true` as its last argument only where you have shown the request came from the user's own page, as a same-origin POST does. Without it the flow reads nothing at its start and always ends on an approval.
@@ -289,13 +295,13 @@ A static site only needs the script and the badge markup; the backend runs somew
 
 1. Clone this repository, run `npm ci`, and copy `wrangler.example.jsonc` to `wrangler.jsonc`. Fill in your account, origin and owner details.
 2. Run `wrangler secret put` for `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` and `OWNER_KEY`, then `npm run cloudflare:deploy`.
-3. On the backend's site, sign in with `OWNER_KEY`, verify, and approve a **public** connection. Its id is listed at `/api/verily/mine`.
+3. On the backend's site, sign in with `OWNER_KEY`, verify, and approve a **public** connection. Its id is listed at `/mine`.
 4. Add the script and the badge to your site:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@bkazemi/verily@0.3.0/dist/verily.js" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/@bkazemi/verily@0.5.0/dist/verily.js" defer></script>
 <verily-badge
-  backend-url="https://your-backend.example/api/verily"
+  backend-url="https://your-backend.example"
   connection-id="CONNECTION_ID"
 ></verily-badge>
 ```
@@ -349,7 +355,7 @@ The authorize and return URLs the instance's operator registers for you are `<pr
 ```html
 <script src="/assets/verily.js" defer></script>
 <verily-connect
-  backend-url="https://verily.example/api/verily"
+  backend-url="https://verily.example"
   handoff-url="/api/verily/handoff"
 ></verily-connect>
 ```
@@ -361,7 +367,7 @@ Once a user has a link, show their badge in place of the pill, and give it the s
 ```html
 <verily-badge
   connections="[...the records, as JSON...]"
-  backend-url="https://verily.example/api/verily"
+  backend-url="https://verily.example"
   handoff-url="/api/verily/handoff"
 ></verily-badge>
 ```
@@ -462,6 +468,43 @@ A signed record proves what the verifier claimed and when (`issuedAt`). It does
 
 The Cloudflare Worker signs by default, with a key it makes and stores itself. Set the `SIGNING_KEY` secret to supply your own, or `SIGNING` to `off` to sign nothing.
 
+## What DNS says of the verifier
+
+Two TXT records let a reader check the verifier against DNS instead of taking its word. Both sit at `_verily.<domain>`, the name the domain method uses, and neither is required.
+
+| Record                                  | Published on          | Says                                                    |
+| --------------------------------------- | --------------------- | ------------------------------------------------------- |
+| `verily-key=<fingerprint>`              | the verifier's domain | this OpenPGP key signs the verifier's records.          |
+| `verily-verifier=<the verifier's host>` | a site's domain       | this verifier speaks for the site's accounts and pages. |
+
+**The signing key.** A signed record is checked against keys the verifier's own server lists, so a reader has nowhere else to confirm them and nothing once the server is gone. Publish one `verily-key=` record for each key, current and retired, on the host in `baseUrl`. `GET <baseUrl>/keys` returns the exact records under `dns`. A reader then confirms the key against the domain, for as long as the domain is kept:
+
+```ts
+import { dnsKeys, signedBy, verifySigned } from '@bkazemi/verily';
+
+const record = await verifySigned(file, keys); // keys saved with the file, or from /keys
+const named = await dnsKeys(new URL(record.evidenceUrl).hostname);
+
+named.ids.includes(await signedBy(file)); // the verifier's domain names the key that signed it
+named.dnssec; // whether the resolver validated that answer
+```
+
+**The site's verifier.** A record's local side is the verifier's statement of what the site told it. On the site's own pages that is enough, since the site put the badge there. On a shared evidence link or a saved signed record, nothing shows the site chose this verifier. A site whose verifier is on another domain publishes `verily-verifier=<host>` on the domain of its `profileUrl`, with the port if `baseUrl` has one. `dnsVerifiers(domain)` reads it back. A verifier on the site's own domain, or a subdomain of it, needs no record and none is looked for.
+
+Set `dns: true` and the instance reads both through `https://dns.google/resolve`, the resolver the domain method asks:
+
+```ts
+createVerily({
+  // ...
+  dns: true, // or { fetch, timeoutMs }
+});
+```
+
+- The evidence page and `<baseUrl>/check` say the signing key is named in the verifier's DNS, with a link to the lookup, once it is. The answer is kept for ten minutes.
+- When a link is approved, the site's domain is looked up. If it names this verifier, the record's local side carries the lookup as `artifactUrl` and the record as `expect`, the evidence reads "Stated by … whose DNS names this verifier" and links to the lookup, and the signed record includes it. `recheck()` reads each site again every `recheckMs`, one lookup for all of a site's records. A record loses the proof when the site stops naming the verifier, or when the lookup has gone unread for `freshnessMs`; its status is unaffected either way.
+
+The Cloudflare Worker sets `dns: true`.
+
 ## Operations
 
 Verification lasts 30 days, flows 10 minutes, and sharing links 7 days. Change them with `validityMs`, `flowTtlMs` and `shareTtlMs`. Evidence is never cached.
@@ -483,7 +526,7 @@ setInterval(
 ```
 
 - **`prune()`** deletes expired flows, and deletes expired or revoked records after 90 days. A retired record is kept until it is removed.
-- **`recheck()`** re-reads gists and link-backs that are due, up to 5 per run (its `budget` argument). Each proof is re-read every 24 hours (`recheckMs`) and stays current for 7 days after its last successful read (`freshnessMs`); after that it shows as unconfirmed until a read succeeds. A failed read changes nothing. For PGP, it asks the keyserver whether the key has been revoked, and revokes the connection if so.
+- **`recheck()`** re-reads gists, link-backs, DNS records and files that are due, up to 5 per run (its `budget` argument). Each proof is re-read every 24 hours (`recheckMs`) and stays current for 7 days after its last successful read (`freshnessMs`); after that it shows as unconfirmed until a read succeeds. A failed read changes nothing. For PGP, it asks the keyserver whether the key has been revoked, and revokes the connection if so.
 
 **If you never call `recheck()`, set `freshnessMs: Infinity`.** Otherwise connections proved by gist, link-back or PGP lapse after a week.
 

package/dist/browser/connect-dialog.js

@@ -1,4 +1,4 @@
-import { externalLink, externalName } from '../core/index.js';
+import { externalId, externalLink, externalName } from '../core/index.js';
 import { accountCard, linkMark, node, outward, stampLink, styles } from './evidence-dialog.js';
 import { providerMark } from './provider-mark.js';
 import { version } from '../version.js';
@@ -433,7 +433,7 @@ renew) {
         const logo = providerMark(flow.provider.id, flow.provider.method);
         const external = accountCard(logo
             ? [logo, document.createTextNode(flow.provider.name)]
-            : [document.createTextNode(flow.provider.name)], externalName(flow.external), flow.external.kind === 'mailbox' ? undefined : flow.external.id, externalLink(flow.external));
+            : [document.createTextNode(flow.provider.name)], externalName(flow.external), externalId(flow.external), externalLink(flow.external));
         const parts = [subjectCard(flow.local), linkMark(), external];
         const choice = node('fieldset');
         const visibilityText = {

package/dist/browser/evidence-dialog.js

@@ -1,4 +1,4 @@
-import { attestationLabel, externalLink, externalName, lastProved, localSide, proofTitle, statusLabel, } from '../core/index.js';
+import { attestationLabel, externalId, externalLink, externalName, lastProved, localSide, proofTitle, statusLabel, } from '../core/index.js';
 import { markStyles, verificationMark } from './mark.js';
 import { providerMark } from './provider-mark.js';
 import { onSignatureResult, signature, standing } from './signed.js';
@@ -117,7 +117,7 @@ export function linkMark() {
  * Additional methods sit beneath the main one, indented under it.
  */
 function attestationNote(attestation, names, additional = false) {
-    const label = attestationLabel(attestation.method, names);
+    const label = attestationLabel(attestation.method, names, attestation);
     if (!label)
         return [];
     const note = node('div', additional ? '+ ' : '', `muted ${additional ? 'additional' : 'method'}`);
@@ -384,8 +384,8 @@ function externalCard(evidence, manage, later = () => { }) {
     // The mark and the name, or just the name. A mark that falls back to writing the name
     // would print it twice here, since this heading writes it either way.
     logo ? [logo, document.createTextNode(provider)] : [document.createTextNode(provider)], externalName(evidence.external), 
-    // A mailbox's address is its name already, so there is no second identifier.
-    evidence.external.kind === 'mailbox' ? undefined : evidence.external.id, externalLink(evidence.external), 
+    // A mailbox's address or a domain is its name already, so there is no second identifier.
+    externalId(evidence.external), externalLink(evidence.external), 
     // Status first, then how it was shown, then when. The proof explains the state
     // above it, so it cannot sit before that state has been given.
     summary, ...attestationNote(main, names), ...evidence.attestations.external.slice(1).flatMap((a) => attestationNote(a, names, true)), 

package/dist/browser/index.js

@@ -1,3 +1,4 @@
+import { routePath } from '../core/routes.js';
 import { badgeShown, quietBadge, renderBadge, renderBadgeMessage, renderBadgePending, renderConnectPill, } from './badge.js';
 import { openConnectDialog, } from './connect-dialog.js';
 import { openEvidenceDialog } from './evidence-dialog.js';
@@ -249,7 +250,10 @@ export function init({ backendUrl, handoffUrl }) {
     const base = new URL(backendUrl, location.href);
     if (!['https:', 'http:'].includes(base.protocol))
         throw new Error('Invalid backend URL');
-    base.pathname = base.pathname.replace(/\/$/, '');
+    // Where the backend's routes begin, with no slash to end it: a backend mounted at the
+    // root of its origin has a path of `/` however it is written, and its routes are not
+    // under `//`.
+    const root = base.href.replace(/\/$/, '');
     /**
      * A backend on another origin: an instance this site is registered with. Its cookies
      * are another site's on this page, so the dialog carries what they would have. The
@@ -268,7 +272,7 @@ export function init({ backendUrl, handoffUrl }) {
         const vouched = handed.ok ? await handed.json() : undefined;
         if (!record(vouched) || typeof vouched.token !== 'string')
             throw new Error('Verily request unavailable');
-        const traded = await fetch(`${base.href}/site/session`, {
+        const traded = await fetch(`${root}/site/session`, {
             method: 'POST',
             credentials: 'omit',
             cache: 'no-store',
@@ -285,11 +289,12 @@ export function init({ backendUrl, handoffUrl }) {
         if (!remote)
             return request(path, data);
         const binding = flow && bindings.get(flow);
-        const response = await fetch(`${base.href}${path}`, {
+        const response = await fetch(`${root}${path}`, {
             credentials: 'omit',
             cache: 'no-store',
             method: data ? 'POST' : 'GET',
             headers: {
+                Accept: 'application/json',
                 Authorization: `Bearer ${await (session ??= openSession())}`,
                 ...(binding ? { 'X-Verily-Flow': binding } : {}),
                 ...(data ? { 'Content-Type': 'application/json' } : {}),
@@ -306,16 +311,16 @@ export function init({ backendUrl, handoffUrl }) {
         return answer;
     }
     async function request(path, data) {
-        const response = await fetch(`${base.href}${path}`, {
+        const response = await fetch(`${root}${path}`, {
             credentials: 'same-origin',
             cache: 'no-store',
-            ...(data
-                ? {
-                    method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
-                    body: JSON.stringify(data),
-                }
-                : {}),
+            // Says what is wanted back, whatever is sent. A header any page may send to another
+            // origin without asking first, so a badge on a static site reads as it did.
+            headers: {
+                Accept: 'application/json',
+                ...(data ? { 'Content-Type': 'application/json' } : {}),
+            },
+            ...(data ? { method: 'POST', body: JSON.stringify(data) } : {}),
         });
         if (!response.ok)
             throw new Error('Verily request unavailable');
@@ -324,20 +329,20 @@ export function init({ backendUrl, handoffUrl }) {
     /** The connect flow as the dialog drives it, every answer checked before it is drawn. */
     const flows = {
         async methods() {
-            const data = await ask('/methods');
+            const data = await ask(routePath('methods'));
             if (!record(data) || !record(data.local) || !Array.isArray(data.methods))
                 throw new Error('Invalid methods response');
             if (typeof data.local.profileUrl === 'string')
                 safeUrl(data.local.profileUrl);
             return data;
         },
-        start: async (provider, method, renew) => flowView(await ask('/sessions', renew
+        start: async (provider, method, renew) => flowView(await ask(routePath('start'), renew
             ? { kind: 'renew', connectionId: renew, provider, method }
             : { kind: 'connect', provider, method })),
-        read: async (id) => flowView(await ask(`/flows/${encodeURIComponent(id)}?format=json`, undefined, id)),
-        submit: async (id, artifact) => flowView(await ask(`/flows/${encodeURIComponent(id)}/submit`, { artifact }, id)),
+        read: async (id) => flowView(await ask(routePath('flow', id), undefined, id)),
+        submit: async (id, artifact) => flowView(await ask(routePath('submit', id), { artifact }, id)),
         async approve(id, visibility, cancel) {
-            const data = await ask(`/flows/${encodeURIComponent(id)}/approve`, { action: cancel ? 'cancel' : 'approve', visibility }, id);
+            const data = await ask(routePath('approve', id), { action: cancel ? 'cancel' : 'approve', visibility }, id);
             if (!record(data))
                 throw new Error('Invalid approval response');
             return data.outcome === 'complete' && typeof data.connectionId === 'string'
@@ -368,7 +373,7 @@ export function init({ backendUrl, handoffUrl }) {
                         }, base.origin);
                     };
                     window.addEventListener('message', receive);
-                    popup.location.href = `${base.href}/site/enter`;
+                    popup.location.href = `${root}/site/enter`;
                 },
             }
             : {}),
@@ -396,7 +401,7 @@ export function init({ backendUrl, handoffUrl }) {
             pill.setAttribute('aria-haspopup', 'dialog');
             pill.onclick = async () => {
                 if (typeof HTMLDialogElement === 'undefined' && !remote) {
-                    location.href = `${base.href}/verify`;
+                    location.href = `${root}/verify`;
                     return;
                 }
                 const result = await client.openConnect(element);
@@ -546,7 +551,7 @@ export function init({ backendUrl, handoffUrl }) {
             // On another origin this is vouched for afresh, as each opening of the dialog is.
             if (remote)
                 session = undefined;
-            return ask(`/connections/${encodeURIComponent(id)}/disconnect`, {});
+            return ask(routePath('disconnect', id), {});
         },
         /**
          * Says how the holder would have an account listed, or retires it. Names one record
@@ -555,10 +560,10 @@ export function init({ backendUrl, handoffUrl }) {
         mark(id, as) {
             if (remote)
                 session = undefined;
-            return ask(`/connections/${encodeURIComponent(id)}/mark`, { as });
+            return ask(routePath('mark', id), { as });
         },
-        issueShare: (id) => request(`/connections/${encodeURIComponent(id)}/share`, {}),
-        revokeShare: (id) => request(`/connections/${encodeURIComponent(id)}/share-revoke`, {}),
+        issueShare: (id) => request(routePath('share', id), {}),
+        revokeShare: (id) => request(routePath('shareRevoke', id), {}),
     };
     return client;
 }
@@ -643,6 +648,7 @@ function validAttestation(attestation) {
         typeof attestation.confirmedAt === 'number' &&
         Number.isFinite(attestation.confirmedAt) &&
         (attestation.expect === undefined || typeof attestation.expect === 'string') &&
+        (attestation.dnssec === undefined || typeof attestation.dnssec === 'boolean') &&
         // Rendered as a link later, so only http(s) may ever reach an href.
         (attestation.artifactUrl === undefined || httpUrl(attestation.artifactUrl)));
 }
@@ -669,7 +675,7 @@ function validEvidence(value) {
         validAttestations(value.attestations) &&
         (value.local.kind === undefined || typeof value.local.kind === 'string') &&
         (value.external.kind === undefined ||
-            ['account', 'key', 'page', 'mailbox'].includes(String(value.external.kind))) &&
+            ['account', 'key', 'page', 'mailbox', 'domain'].includes(String(value.external.kind))) &&
         (value.revokedAt === undefined ||
             (typeof value.revokedAt === 'number' && Number.isFinite(value.revokedAt))) &&
         ['verified', 'unconfirmed', 'expired', 'retired', 'revoked'].includes(String(value.status)) &&

package/dist/browser/provider-mark.js

@@ -53,7 +53,7 @@ function key() {
         'M9.4 6.6l1.6 1.6',
     ]);
 }
-/** A globe, drawn here like the key, for a link back from a page on the open web. */
+/** A globe, drawn here like the key, for a page or a domain on the open web. */
 function globe() {
     return lines([
         'M8 1.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13Z',
@@ -94,6 +94,8 @@ export function providerMark(provider, method) {
         openpgp: key,
         email: envelope,
     };
-    // A site names its own link-back providers, so those fall back on the method's mark.
-    return marks[provider]?.() ?? (method === 'backlink' ? globe() : undefined);
+    // A site names its own link-back providers, so those fall back on the method's mark,
+    // which a domain shown by its DNS or by a file shares.
+    return (marks[provider]?.() ??
+        (['backlink', 'dns', 'wellknown'].includes(method ?? '') ? globe() : undefined));
 }

package/dist/core/index.d.ts

@@ -37,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;
@@ -54,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';
 /**
@@ -74,9 +76,24 @@ export interface Attestation {
     hosted?: boolean;
     /** What a reader should expect to find at artifactUrl, such as a challenge token. */
     expect?: string;
+    /**
+     * Set where the method publishes something of the subject's, as its address, and this
+     * subject had nothing for it to publish: `expect` is then a string minted for the holder
+     * and names nobody. Such a proof holds whatever the subject's address becomes, where one
+     * that published an address is a proof of that address alone.
+     */
+    minted?: boolean;
+    /**
+     * Set where the proof was read from DNS and the resolver said it had validated the answer
+     * with DNSSEC. Without it the answer is only as good as the resolver's own lookup, which
+     * somebody on the path between it and the domain's name servers could have answered.
+     */
+    dnssec?: boolean;
     /**
      * When this side was last confirmed. For `declared` and `oauth` that is the moment it
      * was established; artifact methods drift out of date and are reconfirmed on a schedule.
+     * A `declared` side that carries a proof is the site's own DNS naming this verifier, and
+     * is reconfirmed like any other.
      */
     confirmedAt: number;
 }
@@ -141,6 +158,15 @@ export interface Flow {
      * unguessable and per-flow, so an artifact made for one flow cannot complete another.
      */
     expect?: string;
+    /** Whether `expect` was minted for a method that had nothing of the subject's to state. */
+    minted?: boolean;
+    /** Whether the proof was read from a DNS answer the resolver validated with DNSSEC. */
+    dnssec?: boolean;
+    /**
+     * How the local side is recorded once the flow is approved, where the site's own DNS was
+     * found to name this verifier. Absent means the site's word alone.
+     */
+    stated?: Attestation;
     /**
      * What the holder handed back: an address to read, or the proof itself. On a flow still
      * waiting it is what they last handed back and had refused, kept so they can put it right.
@@ -230,12 +256,26 @@ export interface Limit {
     count: number;
     expiresAt: number;
 }
+/**
+ * When a site's DNS was last asked whether it names this verifier, by the maintenance run
+ * and nothing else. It is what orders the sites in a run, so it is kept for as long as the
+ * site has a record here and never expires by itself: an order that could lapse would
+ * start again from the same few sites.
+ */
+export interface SiteRead {
+    /** The site's domain. */
+    id: string;
+    readAt: number;
+    /** Whether that read got an answer. One that did not is asked again sooner. */
+    answered: boolean;
+}
 export interface Records {
     connections: Connection;
     flows: Flow;
     shares: Share;
     audit: Audit;
     limits: Limit;
+    sites: SiteRead;
 }
 export interface Transaction {
     get<K extends keyof Records>(kind: K, id: string): Promise<Records[K] | undefined>;
@@ -286,9 +326,18 @@ export interface ArtifactProvider {
      * says the far side points at this exact subject, so the subject's own address is the
      * whole of what is proved and a per-flow token could not be part of it. Absent means the
      * backend mints an unguessable string instead, which is what a method wants when any
-     * fresh artifact will do. Throw when the subject cannot be proved this way at all.
+     * fresh artifact will do. So does returning nothing, for a subject that gives the method
+     * nothing to state: one with no address has no address to point at. Throw when the
+     * subject cannot be proved this way at all.
      */
-    expect?(local: LocalAccount): string;
+    expect?(local: LocalAccount): string | undefined;
+    /**
+     * Words the string the backend mints, given its unguessable part. The default names the
+     * site, so the holder can see what they are agreeing to before they publish. A method
+     * that publishes where anyone can look without being told where, as DNS is, may not want
+     * the site said there at all.
+     */
+    mint?(secret: string): string;
     /**
      * Where the proof lives. `location` means the holder publishes it somewhere only they
      * can write and hands back an address, so the address is half of what is proved.
@@ -331,6 +380,14 @@ export interface ArtifactProvider {
         artifact: string;
         expect: string;
     }): Promise<ExternalAccount>;
+    /**
+     * The same check, for a method that learns more than whose the proof is. Where a method
+     * has one, this is what the backend calls, and `verify` gives the account it found.
+     */
+    prove?(input: {
+        artifact: string;
+        expect: string;
+    }): Promise<Proved>;
     /**
      * Whether the holder has since withdrawn the identity itself, wherever such a statement
      * is published. This revokes the connection, so it must be something the holder stated
@@ -338,6 +395,12 @@ export interface ArtifactProvider {
      */
     withdrawn?(account: ExternalAccount, artifact: string): Promise<boolean>;
 }
+/** Whose a proof is, with what the method learned of how far the read can be trusted. */
+export interface Proved {
+    account: ExternalAccount;
+    /** Whether the DNS answer the proof was read from was validated with DNSSEC. */
+    dnssec?: boolean;
+}
 /**
  * Proves control by sending a message somewhere only the holder can read and having them
  * answer it: by pressing the link it carries, or by reading its code back. It is
@@ -455,6 +518,7 @@ export interface Evidence {
     signedUrl?: string;
 }
 export * from './signed.js';
+export * from './routes.js';
 /**
  * How long a published proof stays good without being read again. An artifact method is
  * only true while the artifact is still there, and the holder can delete it without
@@ -508,12 +572,18 @@ export declare function externalName(external: ExternalAccount): string;
  * judgement, which is the reason for publishing it rather than a verdict about it.
  *
  * An unrecognised method returns nothing, so a renderer omits the line instead of
- * describing a proof it does not understand.
+ * describing a proof it does not understand. Given the attestation, the words also say
+ * what its proof adds: that a DNS answer was validated, or that a site's DNS was read.
  */
 export declare function attestationLabel(method: string, names: {
     site: string;
     provider: string;
-}): string | undefined;
+}, proof?: Pick<Attestation, 'artifactUrl' | 'dnssec'>): 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

@@ -21,6 +21,7 @@ export function providerMethod(provider) {
     return provider.method ?? 'oauth';
 }
 export * from './signed.js';
+export * from './routes.js';
 /**
  * How long a published proof stays good without being read again. An artifact method is
  * only true while the artifact is still there, and the holder can delete it without
@@ -113,18 +114,32 @@ export function externalName(external) {
  * judgement, which is the reason for publishing it rather than a verdict about it.
  *
  * An unrecognised method returns nothing, so a renderer omits the line instead of
- * describing a proof it does not understand.
+ * describing a proof it does not understand. Given the attestation, the words also say
+ * what its proof adds: that a DNS answer was validated, or that a site's DNS was read.
  */
-export function attestationLabel(method, names) {
+export function attestationLabel(method, names, proof = {}) {
+    const dnssec = proof.dnssec ? ', validated by DNSSEC' : '';
     return {
-        declared: `Stated by ${names.site}`,
+        // A site's word carries a proof only where its own DNS was read naming this verifier.
+        declared: proof.artifactUrl
+            ? `Stated by ${names.site}, whose DNS names this verifier${dnssec}`
+            : `Stated by ${names.site}`,
         oauth: `Signed in with ${names.provider}`,
         gist: `Published a proof on ${names.provider}`,
         backlink: `Linked back to ${names.site}`,
+        dns: `Published a proof in its DNS${dnssec}`,
+        wellknown: 'Published a proof 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/routes.d.ts

@@ -0,0 +1,57 @@
+export declare const routes: {
+    readonly methods: {
+        readonly method: "GET";
+        readonly path: "/methods";
+    };
+    readonly start: {
+        readonly method: "POST";
+        readonly path: "/sessions";
+    };
+    readonly flow: {
+        readonly method: "GET";
+        readonly path: "/flows/:id";
+        readonly format: "json";
+    };
+    readonly submit: {
+        readonly method: "POST";
+        readonly path: "/flows/:id/submit";
+    };
+    readonly approve: {
+        readonly method: "POST";
+        readonly path: "/flows/:id/approve";
+    };
+    readonly disconnect: {
+        readonly method: "POST";
+        readonly path: "/connections/:id/disconnect";
+        readonly manages: true;
+    };
+    readonly mark: {
+        readonly method: "POST";
+        readonly path: "/connections/:id/mark";
+        readonly manages: true;
+    };
+    readonly share: {
+        readonly method: "POST";
+        readonly path: "/connections/:id/share";
+        readonly manages: true;
+        readonly dialog: false;
+    };
+    readonly shareRevoke: {
+        readonly method: "POST";
+        readonly path: "/connections/:id/share-revoke";
+        readonly manages: true;
+        readonly dialog: false;
+    };
+};
+export type RouteName = keyof typeof routes;
+/** The address of a route, for the record or flow it acts on where it names one. */
+export declare function routePath(name: RouteName, id?: string): string;
+/** The route a request is for, by its method and its path beneath the mount. */
+export declare function routeOf(method: string, path: string): RouteName | undefined;
+/**
+ * The route a dialog's request is for, or nothing where it is not one a dialog makes: a
+ * route no dialog calls, or a page asked for without the query that makes it JSON.
+ */
+export declare function dialogRoute(method: string, path: string, query: URLSearchParams): RouteName | undefined;
+/** Whether any dialog route is at a path, whatever the method: what a preflight asks about. */
+export declare function dialogPath(path: string): boolean;