@bkazemi/verily 0.4.0 → 0.5.0

package/dist/server/service.d.ts

@@ -1,4 +1,5 @@
 import { type Attestations, type Connection, type Evidence, type ExternalAccount, type Flow, type LocalAccount, type Mark, type Provider, type SignedDocument, type SignedEvidence, type Storage, type VerifierKey, type Visibility } from '../core/index.js';
+import { type DnsOptions, type Published } from './domain.js';
 export declare const secret: () => string;
 export declare const hash: (value: string) => string;
 export declare class Unavailable extends Error {
@@ -45,6 +46,17 @@ export interface ServiceOptions {
     signingKey?: string | (() => Promise<string>);
     /** Public keys this instance signed with before, so what they signed still checks. */
     retiredKeys?: VerifierKey[];
+    /**
+     * Reads what DNS says of this verifier, through the one resolver `dnsProvider()` asks.
+     * Two statements are looked for, both TXT records at `_verily.<domain>`. On this
+     * verifier's own domain, `verily-key=<fingerprint>` names a signing key, and the pages
+     * that name the key then link to that lookup. On the domain of a subject's `profileUrl`,
+     * `verily-verifier=<this verifier's host>` names this verifier as the site's own, and
+     * the record's local side then carries that lookup as its proof. That one is read when a
+     * link is approved and again by `recheck()`, and is not looked for where this verifier
+     * is on the site's domain or a subdomain of it. Unset reads nothing.
+     */
+    dns?: boolean | DnsOptions;
     now?: () => number;
 }
 export declare class VerilyService {
@@ -58,6 +70,42 @@ export declare class VerilyService {
     private signer;
     /** Every key a record of this instance may be signed by: the current one first. */
     keys(): Promise<VerifierKey[]>;
+    /**
+     * What this verifier's domain publishes to name its keys: one TXT record for each, all
+     * under the one name. Nothing where it signs nothing, or is not on a domain at all.
+     */
+    keyRecords(): Promise<{
+        name: string;
+        values: string[];
+    } | undefined>;
+    /**
+     * Where a reader can see this verifier's domain name a key, if it was read doing so, and
+     * which domain that was. It is always the domain this instance is on now: a record it
+     * signed while on another names that one, and nothing here was asked about it. The
+     * answer is kept for ten minutes, so a page that asks on every view costs one lookup.
+     */
+    keyNamed(id: string): Promise<(Pick<Published, 'lookup' | 'dnssec'> & {
+        domain: string;
+    }) | undefined>;
+    /** What each domain was last read publishing, and when. Nothing found is a failed read. */
+    private readonly lookups;
+    /**
+     * What a domain publishes for Verily, read again once the last read is older than
+     * `maxAgeMs`. Nothing where it could not be read, which is never the same as nothing
+     * published.
+     */
+    private lookedUp;
+    /**
+     * The domain whose DNS can say a subject's site chose this verifier, or nothing where
+     * there is nothing to ask: no address, or a site this verifier shares a domain with,
+     * since whoever holds a domain already holds every name beneath it.
+     */
+    private siteDomain;
+    /**
+     * The local side as a site's DNS bears it out: the site's word, with the lookup that
+     * found the site naming this verifier. Nothing where it does not, or could not be read.
+     */
+    private stated;
     /** The same keys as one armored text, which is what `gpg --import` takes. */
     armoredKeys(): Promise<string>;
     /**
@@ -275,7 +323,10 @@ export declare class VerilyService {
      * subject, and holds whatever the subject's address becomes.
      */
     private names;
-    /** The site is the only authority on its own namespace, so it declares the local subject. */
+    /**
+     * The site is the only authority on its own namespace, so it declares the local subject.
+     * Where the flow read the site's DNS naming this verifier, that goes with it.
+     */
     private declared;
     /** How the provider established the external account, by whatever method the flow ran. */
     private attestation;
@@ -295,6 +346,12 @@ export declare class VerilyService {
      * never included: they must not appear in any directory listing.
      */
     published(): Promise<Evidence[]>;
+    /**
+     * Every record this instance holds, public and unlisted, for whoever runs it. No route
+     * of the library serves this: a deployment that shows it must first know the reader is
+     * its operator, who can read the storage it comes from anyway. Earliest connected first.
+     */
+    all(): Promise<Evidence[]>;
     mine(local: LocalAccount): Promise<Evidence[]>;
     private owned;
     revoke(id: string, local: LocalAccount): Promise<void>;
@@ -372,6 +429,20 @@ export declare class VerilyService {
      * Returns how many were confirmed. A connection revoked here is not one of them.
      */
     recheck(budget?: number): Promise<number>;
+    /**
+     * Asks each site's DNS again whether it names this verifier, and writes the answer to
+     * every record of that site. One lookup answers for all of a site's records, and
+     * `budget` bounds the sites asked in a run, longest unread first. A site that could not
+     * be read is left as it was: its records lose the proof only once it has gone unread
+     * past `freshnessMs`, or once an answer comes back without the statement.
+     *
+     * When each site was last asked is kept in storage, as a record of its own that `prune()`
+     * removes only with the site's last record. It is apart from the lookups a flow makes
+     * and from anything that expires: an instance restarted or pruned between runs must not
+     * start again from the same few sites, and a site whose holders connect often must
+     * still have its older records rewritten.
+     */
+    private restate;
     /**
      * The configured method that can ask again about one attestation, or nothing when there
      * is nothing to ask: no published proof, a method this instance no longer runs, or a

package/dist/server/service.js

@@ -1,5 +1,6 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { fresh, freshnessMs, isArtifactProvider, isCodeProvider, isRedirectProvider, providerMethod, Refused, status, verifySigned, } from '../core/index.js';
+import { domainOf, keyRecord, namedKeys, namedVerifiers, published, } from './domain.js';
 import { signer } from './signing.js';
 export const secret = () => randomBytes(32).toString('base64url');
 export const hash = (value) => createHash('sha256').update(value).digest('base64url');
@@ -64,6 +65,78 @@ export class VerilyService {
         const current = await this.signer();
         return [...(current ? [current.key] : []), ...(this.options.retiredKeys ?? [])];
     }
+    /**
+     * What this verifier's domain publishes to name its keys: one TXT record for each, all
+     * under the one name. Nothing where it signs nothing, or is not on a domain at all.
+     */
+    async keyRecords() {
+        const domain = domainOf(this.baseUrl);
+        const keys = await this.keys();
+        return domain && keys.length
+            ? { name: `_verily.${domain}`, values: keys.map((key) => keyRecord(key.id)) }
+            : undefined;
+    }
+    /**
+     * Where a reader can see this verifier's domain name a key, if it was read doing so, and
+     * which domain that was. It is always the domain this instance is on now: a record it
+     * signed while on another names that one, and nothing here was asked about it. The
+     * answer is kept for ten minutes, so a page that asks on every view costs one lookup.
+     */
+    async keyNamed(id) {
+        const domain = domainOf(this.baseUrl);
+        const found = domain && this.options.dns ? await this.lookedUp(domain, 600000) : undefined;
+        // Read as `dnsKeys()` reads it, so a fingerprint published in lower case counts here too.
+        return found && namedKeys(found.values).includes(id.toUpperCase())
+            ? { domain: domain, lookup: found.lookup, dnssec: found.dnssec }
+            : undefined;
+    }
+    /** What each domain was last read publishing, and when. Nothing found is a failed read. */
+    lookups = new Map();
+    /**
+     * What a domain publishes for Verily, read again once the last read is older than
+     * `maxAgeMs`. Nothing where it could not be read, which is never the same as nothing
+     * published.
+     */
+    async lookedUp(domain, maxAgeMs) {
+        const held = this.lookups.get(domain);
+        if (held && this.now() - held.at < maxAgeMs)
+            return held.found;
+        const found = await this.deadline(published(domain, this.options.dns === true ? {} : this.options.dns || {})).catch(() => undefined);
+        this.lookups.set(domain, { at: this.now(), found });
+        return found;
+    }
+    /**
+     * The domain whose DNS can say a subject's site chose this verifier, or nothing where
+     * there is nothing to ask: no address, or a site this verifier shares a domain with,
+     * since whoever holds a domain already holds every name beneath it.
+     */
+    siteDomain(local) {
+        const site = this.options.dns && local.profileUrl ? domainOf(local.profileUrl) : undefined;
+        const own = new URL(this.baseUrl).hostname.toLowerCase();
+        return site && site !== own && !own.endsWith(`.${site}`) && !site.endsWith(`.${own}`)
+            ? site
+            : undefined;
+    }
+    /**
+     * The local side as a site's DNS bears it out: the site's word, with the lookup that
+     * found the site naming this verifier. Nothing where it does not, or could not be read.
+     */
+    stated(found) {
+        const own = new URL(this.baseUrl).host.toLowerCase();
+        // Read as `dnsVerifiers()` reads it: a host is the same host in any case. What is kept
+        // is the record as published, since that is what a reader finds at the lookup.
+        const named = found && namedVerifiers(found.values).find(({ host }) => host === own);
+        return found && named
+            ? {
+                by: 'backend',
+                method: 'declared',
+                confirmedAt: this.now(),
+                artifactUrl: found.lookup,
+                expect: named.record,
+                ...(found.dnssec ? { dnssec: true } : {}),
+            }
+            : undefined;
+    }
     /** The same keys as one armored text, which is what `gpg --import` takes. */
     async armoredKeys() {
         return (await this.keys()).map((key) => key.publicKey.trim()).join('\n\n') + '\n';
@@ -208,10 +281,28 @@ export class VerilyService {
             // freedom: the subject's address is the whole claim, so that method states it here
             // and gives up per-flow uniqueness for a standing link that is read again on a
             // schedule instead.
-            if (artifact)
-                flow.expect = artifact.expect
-                    ? artifact.expect(subject)
-                    : `Verily proof for ${this.siteOf(subject)}: ${secret()}`;
+            //
+            // Where such a method has nothing of the subject's to state, it publishes a minted
+            // string like any other, and then keeps the one it has: a flow the local holder runs
+            // on their own record asks for the string already standing, as it would ask for the
+            // same address, and not for a new record in DNS every time the link is renewed.
+            //
+            // Only a minted string is kept this way. A record that published an address the
+            // subject no longer has is a proof of that address, and is not asked for again.
+            if (artifact) {
+                const stated = artifact.expect?.(subject);
+                const standing = artifact.expect && connection && ['renew', 'visibility'].includes(kind)
+                    ? connection.attestations?.external.find((a) => a.method === artifact.method && a.minted)?.expect
+                    : undefined;
+                flow.expect =
+                    stated ??
+                        standing ??
+                        (artifact.mint
+                            ? artifact.mint(secret())
+                            : `Verily proof for ${this.siteOf(subject)}: ${secret()}`);
+                if (artifact.expect && stated === undefined)
+                    flow.minted = true;
+            }
             // These kinds are all started by the local holder, whose own record this is. Removal
             // from the external side is started by anyone, and is told nothing.
             if (artifact?.known && ['connect', 'renew', 'visibility'].includes(kind)) {
@@ -277,13 +368,13 @@ export class VerilyService {
     async offered(id, binding, provider, expect, suggested) {
         try {
             const handed = provider.resolve?.(suggested) ?? suggested;
-            const external = await this.deadline(provider.verify({ artifact: handed, expect }));
+            const found = await this.deadline(read(provider, { artifact: handed, expect }));
             await this.transaction(async (tx) => {
                 const flow = await this.bound(tx, id, binding);
                 flow.phase = 'exchanging';
                 await tx.put('flows', id, flow);
             });
-            await this.established(id, binding, external, handed);
+            await this.established(id, binding, found.account, handed, found.dnssec);
         }
         catch {
             await this.transaction(async (tx) => {
@@ -352,8 +443,8 @@ export class VerilyService {
             // Kept as the address that was read, never as the shorthand that named it: it is
             // where a reader is sent, and what is read again later.
             const handed = provider.resolve?.(artifact) ?? artifact;
-            const external = await provider.verify({ artifact: handed, expect });
-            await this.established(id, binding, external, handed);
+            const found = await read(provider, { artifact: handed, expect });
+            await this.established(id, binding, found.account, handed, found.dnssec);
         }
         catch (error) {
             await this.refused(id, error, artifact);
@@ -587,7 +678,7 @@ export class VerilyService {
      * existing connection must still be the same account on the same provider. No binding
      * means a confirmation link got here, which is held to the link and not to a browser.
      */
-    async established(id, binding, external, artifact) {
+    async established(id, binding, external, artifact, dnssec = false) {
         if (typeof external.id !== 'string' ||
             !external.id ||
             typeof external.handle !== 'string' ||
@@ -619,12 +710,19 @@ export class VerilyService {
         // without the holder choosing that method or handing anything back. Read while the
         // flow is still exchanging: approval is shown once, and must show all it will record.
         const shown = await this.transaction(accepted);
-        const standing = ['connect', 'renew'].includes(shown.kind) ? await this.standing(shown) : [];
+        const recorded = ['connect', 'renew'].includes(shown.kind);
+        const standing = recorded ? await this.standing(shown) : [];
+        // The site's own DNS is read here for the same reason: outside a transaction, and
+        // before the approval that records what it said. A read a few minutes old will do.
+        const site = recorded ? this.siteDomain(shown.local) : undefined;
+        const stated = site ? this.stated(await this.lookedUp(site, 300000)) : undefined;
         await this.transaction(async (tx) => {
             const flow = await accepted(tx);
             flow.artifact = artifact;
             flow.reason = undefined;
             flow.authenticatedAt = this.now();
+            flow.dnssec = dnssec || undefined;
+            flow.stated = stated;
             if (standing.length)
                 flow.standing = standing;
             flow.phase = 'approval';
@@ -656,10 +754,11 @@ export class VerilyService {
             try {
                 const expect = provider.expect(flow.local);
                 const known = provider.known(flow.external);
-                if (!known)
+                // A minted string is found nowhere the holder was not asked to put it.
+                if (!known || expect === undefined)
                     continue;
                 const handed = provider.resolve?.(known) ?? known;
-                const external = await this.deadline(provider.verify({ artifact: handed, expect }));
+                const { account: external, dnssec } = await this.deadline(read(provider, { artifact: handed, expect }));
                 if (!sameAccount(flow.external, external))
                     continue;
                 found.push({
@@ -668,6 +767,7 @@ export class VerilyService {
                     confirmedAt: this.now(),
                     artifactUrl: handed,
                     expect,
+                    ...(dnssec ? { dnssec } : {}),
                 });
             }
             catch {
@@ -780,7 +880,7 @@ export class VerilyService {
                     connectedAt: this.now(),
                     expiresAt: this.now() + (this.options.validityMs ?? 30 * 86400000),
                     attestations: {
-                        local: this.declared(),
+                        local: this.declared(flow),
                         external: [this.attestation(flow, provider, connectionId)],
                     },
                     proof: hosted(provider) ? flow.artifact : undefined,
@@ -876,8 +976,12 @@ export class VerilyService {
         const [main, ...rest] = connection.attestations.external;
         // A retired record is as it stood when it was retired, and nothing is read after that.
         const at = connection.retiredAt ?? this.now();
+        const { local } = connection.attestations;
         return {
-            ...connection.attestations,
+            // A site's DNS that has gone unread no longer bears its word out, and the word stands.
+            local: fresh(local, at, this.freshness)
+                ? local
+                : { by: local.by, method: local.method, confirmedAt: local.confirmedAt },
             external: [main, ...rest.filter((a) => fresh(a, at, this.freshness))],
         };
     }
@@ -967,7 +1071,7 @@ export class VerilyService {
             // about the new proof and compares ids exactly, and an address read with different
             // case names the same profile under a different id.
             connection.external = flow.external;
-            connection.attestations = { local: this.declared(), external: [attestation, ...rest] };
+            connection.attestations = { local: this.declared(flow), external: [attestation, ...rest] };
         }
         else {
             // A proof that named the subject's old address proves nothing about its new one,
@@ -979,7 +1083,7 @@ export class VerilyService {
                 others.push(attestation);
             else
                 others[at] = attestation;
-            connection.attestations = { local: this.declared(), external: [main, ...others] };
+            connection.attestations = { local: this.declared(flow), external: [main, ...others] };
         }
         if (hosted(provider))
             connection.proof = flow.artifact;
@@ -994,8 +1098,10 @@ export class VerilyService {
         const provider = this.providers.find((p) => p.id === connection.provider && providerMethod(p) === attestation.method);
         if (attestation.expect === undefined || !provider || !isArtifactProvider(provider))
             return true;
-        if (!provider.expect)
+        if (!provider.expect || attestation.minted)
             return true;
+        // A subject with nothing to state gives nothing back, which no published address
+        // equals: a proof of the address it used to have does not name it now.
         try {
             return provider.expect(local) === attestation.expect;
         }
@@ -1003,9 +1109,12 @@ export class VerilyService {
             return false;
         }
     }
-    /** The site is the only authority on its own namespace, so it declares the local subject. */
-    declared() {
-        return { by: 'backend', method: 'declared', confirmedAt: this.now() };
+    /**
+     * The site is the only authority on its own namespace, so it declares the local subject.
+     * Where the flow read the site's DNS naming this verifier, that goes with it.
+     */
+    declared(flow) {
+        return flow.stated ?? { by: 'backend', method: 'declared', confirmedAt: this.now() };
     }
     /** How the provider established the external account, by whatever method the flow ran. */
     attestation(flow, provider, connectionId) {
@@ -1024,6 +1133,10 @@ export class VerilyService {
                 ? `${this.baseUrl}/connections/${connectionId}/proof`
                 : flow.artifact;
             external.expect = flow.expect;
+            if (flow.minted)
+                external.minted = true;
+            if (flow.dnssec)
+                external.dnssec = true;
             if (hosted)
                 external.hosted = true;
         }
@@ -1067,6 +1180,16 @@ export class VerilyService {
             .map((c) => this.evidence(c))
             .filter((e) => e.status === 'verified'));
     }
+    /**
+     * Every record this instance holds, public and unlisted, for whoever runs it. No route
+     * of the library serves this: a deployment that shows it must first know the reader is
+     * its operator, who can read the storage it comes from anyway. Earliest connected first.
+     */
+    async all() {
+        return this.transaction(async (tx) => (await tx.list('connections'))
+            .map((c) => this.evidence(c))
+            .sort((a, b) => a.connectedAt - b.connectedAt));
+    }
     async mine(local) {
         return this.transaction(async (tx) => (await tx.list('connections'))
             .filter((c) => c.local.id === local.id)
@@ -1253,8 +1376,72 @@ export class VerilyService {
         // open across a fetch would stall every other request behind the slowest provider.
         for (const item of due)
             confirmed += await this.reread(item);
+        await this.restate(budget);
         return confirmed;
     }
+    /**
+     * Asks each site's DNS again whether it names this verifier, and writes the answer to
+     * every record of that site. One lookup answers for all of a site's records, and
+     * `budget` bounds the sites asked in a run, longest unread first. A site that could not
+     * be read is left as it was: its records lose the proof only once it has gone unread
+     * past `freshnessMs`, or once an answer comes back without the statement.
+     *
+     * When each site was last asked is kept in storage, as a record of its own that `prune()`
+     * removes only with the site's last record. It is apart from the lookups a flow makes
+     * and from anything that expires: an instance restarted or pruned between runs must not
+     * start again from the same few sites, and a site whose holders connect often must
+     * still have its older records rewritten.
+     */
+    async restate(budget) {
+        if (!this.options.dns)
+            return;
+        const interval = this.options.recheckMs ?? 86400000;
+        const now = this.now();
+        const live = (c) => !!c?.attestations &&
+            c.revokedAt === undefined &&
+            c.retiredAt === undefined &&
+            c.expiresAt > this.now();
+        const due = await this.transaction(async (tx) => {
+            const sites = new Set((await tx.list('connections'))
+                .filter(live)
+                .map((c) => this.siteDomain(c.local))
+                .filter((site) => site !== undefined));
+            const reads = new Map((await tx.list('sites')).map((read) => [read.id, read]));
+            // A site never asked about goes first, then the rest by how long ago they were. A
+            // site that gave no answer is due again sooner, and still waits behind every site
+            // asked before it, so a zone that never answers cannot hold up the others.
+            const at = (site) => reads.get(site)?.readAt ?? -Infinity;
+            const wait = (site) => reads.get(site)?.answered === false ? Math.ceil(interval / 4) : interval;
+            return [...sites]
+                .filter((site) => at(site) + wait(site) <= now)
+                .sort((a, b) => at(a) - at(b))
+                .slice(0, budget);
+        });
+        for (const site of due) {
+            // Always asked afresh: a read some flow made says nothing of the records before it.
+            const found = await this.lookedUp(site, 0);
+            await this.transaction((tx) => tx.put('sites', site, { id: site, readAt: this.now(), answered: !!found }));
+            if (!found)
+                continue;
+            const stated = this.stated(found);
+            await this.transaction(async (tx) => {
+                for (const connection of await tx.list('connections')) {
+                    if (!live(connection) || this.siteDomain(connection.local) !== site)
+                        continue;
+                    const { local } = connection.attestations;
+                    // Nothing was stated before and nothing is now, so there is nothing to write.
+                    if (!stated && !local.artifactUrl)
+                        continue;
+                    connection.attestations.local = stated ?? {
+                        by: local.by,
+                        method: local.method,
+                        confirmedAt: local.confirmedAt,
+                    };
+                    await tx.put('connections', connection.id, connection);
+                }
+            });
+        }
+    }
     /**
      * The configured method that can ask again about one attestation, or nothing when there
      * is nothing to ask: no published proof, a method this instance no longer runs, or a
@@ -1275,11 +1462,14 @@ export class VerilyService {
         const { artifactUrl, expect, method } = attestation;
         const main = attestation === connection.attestations.external[0];
         let withdrawn = false;
+        let dnssec = false;
         try {
             if (provider.artifact === 'document')
                 withdrawn = await this.deadline(provider.withdrawn(connection.external, connection.proof));
             else {
-                const external = await this.deadline(provider.verify({ artifact: artifactUrl, expect: expect }));
+                const found = await this.deadline(read(provider, { artifact: artifactUrl, expect: expect }));
+                const external = found.account;
+                dnssec = found.dnssec === true;
                 // The proof must still be the same holder's. An account that changed hands has
                 // not reproved anything, whatever is published at the old address.
                 if (main
@@ -1314,6 +1504,11 @@ export class VerilyService {
                 return 0;
             }
             held.confirmedAt = this.now();
+            // A zone can start or stop being signed, so the flag is as the last read found it.
+            if (dnssec)
+                held.dnssec = true;
+            else
+                delete held.dnssec;
             await tx.put('connections', connection.id, current);
             return 1;
         });
@@ -1345,14 +1540,20 @@ export class VerilyService {
                 if (limit.expiresAt <= now)
                     await tx.delete('limits', limit.id);
             const audit = await tx.list('audit');
+            // The sites that still have a record here, whose place in the recheck order is kept.
+            const sites = new Set();
             for (const connection of await tx.list('connections')) {
                 const ended = connection.revokedAt ??
                     (connection.retiredAt === undefined ? connection.expiresAt : Infinity);
                 if (ended + retentionMs <= now) {
                     await tx.delete('connections', connection.id);
                     await tx.delete('shares', connection.id);
+                    continue;
                 }
-                else if (connection.connectedAt === undefined) {
+                const site = this.siteDomain(connection.local);
+                if (site)
+                    sites.add(site);
+                if (connection.connectedAt === undefined) {
                     // A record from before its first connection was kept. The audit trail still has
                     // the moment, for as long as it retains it, and that is the answer. Only past
                     // that is the earliest time left on the record used, which is a guess: a sign-in
@@ -1365,6 +1566,11 @@ export class VerilyService {
                     await tx.put('connections', connection.id, connection);
                 }
             }
+            // When a site was last asked goes only with its last record, never by age: it is
+            // what orders the sites `recheck()` asks, and losing it would put the site first again.
+            for (const read of await tx.list('sites'))
+                if (!sites.has(read.id))
+                    await tx.delete('sites', read.id);
             for (const event of audit)
                 if (event.at + retentionMs <= now)
                     await tx.delete('audit', event.id);
@@ -1408,6 +1614,11 @@ function revives(connection, provider) {
     return (connection.retiredAt === undefined ||
         (connection.attestations?.external[0].method ?? 'oauth') === providerMethod(provider));
 }
+/** One proof waiting to be read again, and the method that reads it. */
+/** Whose a proof is and what else its method learned, whichever of the two it offers. */
+async function read(provider, input) {
+    return provider.prove ? provider.prove(input) : { account: await provider.verify(input) };
+}
 /**
  * Whether two methods named the same account. Where both carry an id their provider
  * issued, that id settles it. A method that learns only an address, as a link back does,

package/dist/site/index.js

@@ -78,7 +78,7 @@ export function createSiteClient(options) {
          * have. The instance sends them on to this site's authorize endpoint with a `state`.
          */
         beginUrl(purpose = 'connect') {
-            return `${instance.origin}/begin?${new URLSearchParams({ site: options.site, purpose })}`;
+            return `${instance.origin}/handoff/request?${new URLSearchParams({ site: options.site, purpose })}`;
         },
         /**
          * For the authorize endpoint: where to redirect a signed-in user, with a handoff that
@@ -98,7 +98,7 @@ export function createSiteClient(options) {
                 // Under the five minutes the instance allows, so a slow clock does not overrun it.
                 exp: seconds() + 240,
             });
-            return { url: `${instance.origin}/start?${new URLSearchParams({ token })}`, txn };
+            return { url: `${instance.origin}/handoff/accept?${new URLSearchParams({ token })}`, txn };
         },
         /**
          * For a page that shows the connect pill with `handoff-url`: a token that vouches for