@bkazemi/verily 0.2.0 → 0.4.0

package/dist/server/index.js

@@ -1,4 +1,4 @@
-import { attestationLabel, externalLink, externalName, isArtifactProvider, isCodeProvider, isRedirectProvider, localSide, proofTitle, providerMethod, statusLabel, signedBy, } from '../core/index.js';
+import { attestationLabel, externalId, externalLink, externalName, isArtifactProvider, isCodeProvider, isRedirectProvider, lastProved, localSide, proofTitle, providerMethod, statusLabel, signedBy, } from '../core/index.js';
 import { artifactAttempts, codeAttempts, VerilyService, Unavailable, } from './service.js';
 import { copyScript, waitScript } from './copy.js';
 import { escape } from './escape.js';
@@ -10,6 +10,7 @@ export { discordProvider } from './discord.js';
 export { youtubeProvider } from './youtube.js';
 export { githubGistProvider } from './github-gist.js';
 export { linkProvider, githubLinkProvider } from './link.js';
+export { dnsProvider, wellKnownProvider, } from './domain.js';
 export { pgpProvider } from './pgp.js';
 export { generateSigningKey, signer } from './signing.js';
 export { emailProvider, } from './email.js';
@@ -98,6 +99,8 @@ function methodAction(provider) {
         oauth: `Sign in with ${provider.name}`,
         gist: `Publish a proof on ${provider.name}`,
         backlink: `Link back from ${provider.name}`,
+        dns: 'Add a DNS record',
+        wellknown: 'Serve a file',
         signature: `Sign with ${provider.name}`,
         code: `Confirm by ${provider.name.toLowerCase()}`,
     };
@@ -118,9 +121,13 @@ function artifactField(provider) {
  * standing: it goes on the record with this one, and they did not ask for it by name.
  */
 function standingNote(flow, site) {
-    return flow.standing?.some((a) => a.method === 'backlink')
-        ? `This account already links back to ${site}. Confirming records that too.`
-        : undefined;
+    const found = {
+        backlink: `This account already links back to ${site}.`,
+        dns: `This domain already names ${site} in a DNS record.`,
+        wellknown: `This domain already names ${site} in a file it serves.`,
+    };
+    const note = flow.standing?.map((a) => found[a.method]).find((said) => said !== undefined);
+    return note ? `${note} Confirming records that too.` : undefined;
 }
 /**
  * Said above a proof that was handed back and refused, while the flow still waits for it:
@@ -134,9 +141,13 @@ function refusedNote(flow) {
 }
 /** Said beside every artifact method: what the holder publishes is public by design. */
 function artifactNote(provider) {
-    return provider.method === 'backlink'
-        ? 'This link is public, as is the page you point at. Anyone reading either one can follow it here.'
-        : 'This line is public, as is whatever published it. Publish nothing else alongside it.';
+    const notes = {
+        backlink: 'This link is public, as is the page you point at. Anyone reading either one can follow it here.',
+        dns: 'This record is public, as is the page it names. Anyone reading either one can follow it here.',
+        wellknown: 'This file is public, as is the page it names. Anyone reading either one can follow it here.',
+    };
+    return (notes[provider.method] ??
+        'This line is public, as is whatever published it. Publish nothing else alongside it.');
 }
 /**
  * Where a mailed code stands, for whichever renderer asks the holder for the next thing:
@@ -161,6 +172,21 @@ const codeNote = "We'll email this address to confirm it's yours. The address is
 function providerNames(providers) {
     return [...new Set(providers.map((p) => p.name))].join(' or ');
 }
+/**
+ * What the holder would be linking, for the sentence that asks them to: an account with a
+ * sign-in provider, a key, an address, a domain. Each is named once, however many ways it
+ * can be shown.
+ */
+function heldNames(providers) {
+    const held = (p) => ({
+        signature: `${p.name} key`,
+        code: `${p.name.toLowerCase()} address`,
+        dns: 'domain',
+        wellknown: 'domain',
+    })[providerMethod(p)] ?? `${p.name} account`;
+    const names = [...new Set(providers.map(held))];
+    return names.length > 1 ? `${names.slice(0, -1).join(', ')} or ${names.at(-1)}` : names[0];
+}
 /** Seconds are the finest thing a record measured in days can mean; milliseconds are noise. */
 const moment = (time) => new Date(time).toISOString().replace(/\.\d{3}Z$/, 'Z');
 /**
@@ -243,22 +269,34 @@ function evidencePage(e, base, report, keyId) {
     // identifier stays: that one is the provider's word, not the site's own wording.
     card(local.heading, local.value, e.local.profileUrl, undefined, attestationNote(e.attestations.local, names)) +
         card(names.provider, externalName(e.external), externalLink(e.external), 
-        // A mailbox's address is its name already, so there is no second identifier.
-        e.external.kind === 'mailbox' ? undefined : e.external.id, externalNotes(e.attestations, names)) +
-        times([
-            ['Approved', e.approvedAt],
-            ['Authenticated', e.authenticatedAt],
-            [current ? 'Valid until' : 'Expired on', e.status === 'revoked' ? undefined : e.expiresAt],
-            ['Revoked on', e.revokedAt],
-            // Only a method that publishes an artifact drifts; a sign-in does not go stale.
-            [
-                'Last checked',
-                e.attestations.external[0].artifactUrl
-                    ? e.attestations.external[0].confirmedAt
-                    : undefined,
-            ],
-            ['Sharing link expires', e.linkExpiresAt],
-        ]) +
+        // A mailbox's address or a domain is its name already, so there is no second identifier.
+        externalId(e.external), externalNotes(e.attestations, names)) +
+        times(e.status === 'retired'
+            ? [
+                ['Approved', e.approvedAt],
+                // Two rows, always, so a reader sees any gap between them: an account retired
+                // weeks after it was last proved went unproved for those weeks.
+                ['Last verified', lastProved(e)],
+                ['Retired', e.retiredAt],
+                ['Sharing link expires', e.linkExpiresAt],
+            ]
+            : [
+                ['Approved', e.approvedAt],
+                ['Authenticated', e.authenticatedAt],
+                [
+                    current ? 'Valid until' : 'Expired on',
+                    e.status === 'revoked' ? undefined : e.expiresAt,
+                ],
+                ['Revoked on', e.revokedAt],
+                // Only a method that publishes an artifact drifts; a sign-in does not go stale.
+                [
+                    'Last checked',
+                    e.attestations.external[0].artifactUrl
+                        ? e.attestations.external[0].confirmedAt
+                        : undefined,
+                ],
+                ['Sharing link expires', e.linkExpiresAt],
+            ]) +
         `${e.linkExpiresAt ? '<p class="fine">Anyone with this link can view and forward it.</p>' : ''}
     ${e.signedUrl ? `<p class="signed" id="signed"><strong>Signed by ${escape(e.verifierName)}</strong>${keyId ? ` with OpenPGP key <a href="${escape(base)}/keys.asc">${escape(keyId)}</a>` : ''}. <a href="${escape(safeUrl(e.signedUrl))}">Download the signed record</a>, which <a href="${escape(base)}/check">can be checked</a> without this page.</p>` : ''}
     <p class="fine">This connection does not establish legal identity, trustworthiness, content authorship, or permanent ownership.</p>
@@ -275,14 +313,23 @@ const checkForm = '<form method="post"><label>Signed record <textarea name="reco
 function checkedPage(d, keyId, base) {
     const names = { site: d.siteName, provider: d.providerName };
     const local = localSide(d.local, d.siteName);
-    return page(base, 'Signed record', `<p>${escape(d.verifierName)} signed this record. It shows what stood when it was signed, not what stands now.</p>` +
+    // A retired record did not stand when it was signed, and its heading says so first.
+    const retired = d.version === 2;
+    return page(base, retired ? 'Retired connection' : 'Signed record', `<p>${escape(d.verifierName)} signed this record. It shows what stood when it was signed, not what stands now.</p>` +
         card(local.heading, local.value, d.local.profileUrl, undefined, attestationNote(d.attestations.local, names)) +
-        card(names.provider, externalName(d.external), externalLink(d.external), d.external.kind === 'mailbox' ? undefined : d.external.id, externalNotes(d.attestations, names)) +
-        times([
-            ['Signed', d.issuedAt],
-            ['Approved', d.approvedAt],
-            ['Valid until', d.expiresAt],
-        ]) +
+        card(names.provider, externalName(d.external), externalLink(d.external), externalId(d.external), externalNotes(d.attestations, names)) +
+        times(retired
+            ? [
+                ['Signed', d.issuedAt],
+                ['Approved', d.approvedAt],
+                ['Last verified', lastProved(d)],
+                ['Retired', d.retiredAt],
+            ]
+            : [
+                ['Signed', d.issuedAt],
+                ['Approved', d.approvedAt],
+                ['Valid until', d.expiresAt],
+            ]) +
         `<p class="fine">Signing key <a href="${escape(base)}/keys.asc">${escape(keyId)}</a>.</p>
     <p class="fine"><a href="${escape(safeUrl(d.evidenceUrl))}">See whether this connection still stands</a></p>`);
 }
@@ -374,13 +421,24 @@ export function createVerily(options) {
     /**
      * The methods a page offers. A flow on an existing record stays in its namespace, so
      * where the holder is signed in that record narrows the list; removing a link from the
-     * external side refuses a standing proof, which anybody can hand back.
+     * external side refuses a standing proof, which anybody can hand back. A retired record
+     * is renewed by the method it was first shown by, so that one is offered alone.
      */
     async function offer(kind, id, user, requested) {
         let namespace = requested ?? undefined;
-        if (user && id)
-            namespace = (await service.read(id, user)).provider;
+        let only;
+        if (user && id) {
+            const held = await service.read(id, user);
+            namespace = held.provider;
+            if (held.status === 'retired') {
+                // Who can read a retired record is frozen with the rest of it.
+                if (kind === 'visibility')
+                    throw new Unavailable();
+                only = held.attestations.external[0].method;
+            }
+        }
         const offered = (user ? permitted(user) : service.providers).filter((p) => (namespace === undefined || p.id === namespace) &&
+            (only === undefined || providerMethod(p) === only) &&
             !(['revoke', 'share-revoke'].includes(kind) && isArtifactProvider(p) && p.expect));
         if (!offered.length)
             throw new Unavailable();
@@ -428,8 +486,8 @@ export function createVerily(options) {
         profileUrl: user.profileUrl,
     });
     /**
-     * A connect flow as the in-page dialog draws it: the same steps the flow pages walk
-     * through, as data, so the holder never has to leave the page they started on.
+     * A connect or renew flow as the in-page dialog draws it: the same steps the flow pages
+     * walk through, as data, so the holder never has to leave the page they started on.
      */
     async function flowView(flow, authorizationUrl) {
         const provider = service.providerOf(flow);
@@ -472,10 +530,10 @@ export function createVerily(options) {
             view.connectionId = flow.resultId;
         return view;
     }
-    /** A flow the dialog may read: one this holder started, to connect an account. */
+    /** A flow the dialog may read: one this holder started, to connect an account or renew one. */
     async function ownFlow(request, id) {
         const flow = await service.flow(id, binding(request));
-        if (flow.kind !== 'connect' || (await local(request)).id !== flow.local?.id)
+        if (!['connect', 'renew'].includes(flow.kind) || (await local(request)).id !== flow.local?.id)
             throw new Unavailable();
         return flow;
     }
@@ -560,7 +618,7 @@ export function createVerily(options) {
             ${user
                         ? card(subject(user).heading, subject(user).value, user.profileUrl)
                         : '<p>Authenticate with the matching external account to review and remove this link.</p>'}
-            <p>Confirm the connection between this ${escape(subjectNoun(user?.kind) ?? 'site')} and your ${escape(providerNames(offered))} account.</p>
+            <p>Confirm the connection between this ${escape(subjectNoun(user?.kind) ?? 'site')} and your ${escape(heldNames(offered))}.</p>
             ${kind === 'renew' && offered.length > 1 ? '<p class="fine">Renewing another way adds that method beneath the one this connection was first shown by.</p>' : ''}
             ${forms}`));
                 }
@@ -653,7 +711,7 @@ export function createVerily(options) {
                                 ? 'Add to connection'
                                 : 'Confirm connection', `
             ${card(subject(flow.local).heading, subject(flow.local).value, flow.local.profileUrl)}
-            ${card(provider.name, externalName(flow.external), externalLink(flow.external), flow.external.kind === 'mailbox' ? undefined : flow.external.id)}
+            ${card(provider.name, externalName(flow.external), externalLink(flow.external), externalId(flow.external))}
             ${joined ? `<p>This account is already linked here. Confirming adds this method to that connection, beneath the one it was first shown by, and it stays ${escape(joined.visibility)}.</p>` : ''}
             ${found ? `<p>${escape(found)}</p>` : ''}
             <p class="fine">${escape(service.siteOf(flow.local))} receives the result. Verified via ${escape(options.verifierName)}.</p>
@@ -775,7 +833,7 @@ export function createVerily(options) {
                     }), await context(request, kind), 
                     // Posted from this origin, which the check on every POST has already held it to.
                     true);
-                    if (asJson && kind === 'connect')
+                    if (asJson && ['connect', 'renew'].includes(kind))
                         return json(await flowView(await service.flow(flow.flowId, flow.binding), flow.authorizationUrl), flowCookie(flow.binding));
                     return redirect(entry(flow), flowCookie(flow.binding));
                 }
@@ -815,15 +873,21 @@ export function createVerily(options) {
                         return json(id ? { outcome: 'complete', connectionId: id } : { outcome: 'cancelled' });
                     return await ended(await service.flow(flow.id, binding(request)));
                 }
-                const management = path.match(/^\/connections\/([^/]+)\/(disconnect|share|share-revoke|visibility)$/);
+                const management = path.match(/^\/connections\/([^/]+)\/(disconnect|mark|share|share-revoke|visibility)$/);
                 if (management) {
                     const user = await local(request), id = management[1];
                     if (management[2] === 'disconnect') {
                         await service.revoke(id, user);
                         return json({ ok: true });
                     }
+                    // Acts on the account the record names: every record of it this holder has.
+                    if (management[2] === 'mark') {
+                        await service.mark(id, user, data.as);
+                        return json({ ok: true });
+                    }
                     if (management[2] === 'visibility') {
-                        await service.read(id, user);
+                        if ((await service.read(id, user)).status === 'retired')
+                            throw new Unavailable();
                         return json({ url: `${service.baseUrl}/visibility/${id}` });
                     }
                     return json((await service.share(id, user, management[2] === 'share-revoke')) ?? { ok: true });

package/dist/server/link.js

@@ -4,7 +4,7 @@ import { MIMEType } from 'node:util';
 import { html, parse } from 'parse5';
 import { Refused, } from '../core/index.js';
 import { discard, readBounded } from './body.js';
-import { pinnable, publicFetch } from './public-fetch.js';
+import { transport } from './public-fetch.js';
 /**
  * Domain suffixes that must never be fetched. The holder names the address, so it names
  * the host, and these are the names that can resolve to something inside the network
@@ -134,21 +134,6 @@ async function backlinked(response, page, subject, maxBytes) {
     // Not finding it in part of a page is not the same as it not being there.
     throw new Refused(truncated ? 'Page is too large to read' : 'Page has no rel="me" link to this subject');
 }
-/**
- * How pages are fetched. A deployment that named its hosts has vouched for where they
- * resolve, so the platform's own fetch will do. One that reads any host has vouched for
- * nothing, and the holder picks the name: every address it resolves to is checked, on the
- * connection that uses it, which only Node lets this do.
- */
-function transport(options) {
-    if (options.fetch)
-        return options.fetch;
-    if (options.hosts)
-        return (url, init) => fetch(url, init);
-    if (!pinnable())
-        throw new Error('Reading any host needs Node, which lets it check where a name resolves; name the hosts to read instead');
-    return publicFetch();
-}
 /**
  * The address the holder handed back, once it is one this may fetch. They choose it, so
  * an unguarded fetch here is an open proxy: HTTPS only, a public-looking name rather than

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

@@ -19,5 +19,15 @@ export type Fetch = (url: string, init: RequestInit) => Promise<Response>;
  * `allowed` decides which addresses may be connected to, and is only for tests.
  */
 export declare function publicFetch(resolve?: Resolve, allowed?: (address: string) => boolean): Fetch;
+/**
+ * How an address the holder named is fetched. A deployment that named its hosts has
+ * vouched for where they resolve, so the platform's own fetch will do. One that reads any
+ * host has vouched for nothing, and the holder picks the name: every address it resolves
+ * to is checked, on the connection that uses it, which only Node lets this do.
+ */
+export declare function transport(options: {
+    fetch?: typeof fetch;
+    hosts?: string[];
+}): Fetch;
 /** Whether this runtime is Node, the only one that lets `publicFetch()` pin its lookup. */
 export declare function pinnable(): boolean;

package/dist/server/public-fetch.js

@@ -37,6 +37,21 @@ export function publicFetch(resolve = system, allowed) {
         }
     };
 }
+/**
+ * How an address the holder named is fetched. A deployment that named its hosts has
+ * vouched for where they resolve, so the platform's own fetch will do. One that reads any
+ * host has vouched for nothing, and the holder picks the name: every address it resolves
+ * to is checked, on the connection that uses it, which only Node lets this do.
+ */
+export function transport(options) {
+    if (options.fetch)
+        return options.fetch;
+    if (options.hosts)
+        return (url, init) => fetch(url, init);
+    if (!pinnable())
+        throw new Error('Reading any host needs Node, which lets it check where a name resolves; name the hosts to read instead');
+    return publicFetch();
+}
 /** A lookup that answers only with addresses that are all permitted, or not at all. */
 function pinned(resolve, permitted) {
     return (hostname, options, callback) => {

package/dist/server/service.d.ts

@@ -1,4 +1,4 @@
-import { type Attestations, type Connection, type Evidence, type ExternalAccount, type Flow, type LocalAccount, type Provider, type SignedDocument, type SignedEvidence, type Storage, type VerifierKey, type Visibility } from '../core/index.js';
+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';
 export declare const secret: () => string;
 export declare const hash: (value: string) => string;
 export declare class Unavailable extends Error {
@@ -64,6 +64,10 @@ export declare class VerilyService {
      * A public record that stands, signed as of now. Signed when asked for, not when
      * approved, so a signed record says the record stood on the day it was taken and none can be
      * made once it is removed.
+     *
+     * A retired record is signed too, as what it is: the durable form of the claim that the
+     * account was the holder's when it was last proved. It did not stand when it was signed,
+     * so it is a version of its own that says so, which a reader of the first refuses.
      */
     signed(id: string): Promise<SignedEvidence>;
     /** What a signed record says, if this instance signed it. */
@@ -129,6 +133,10 @@ export declare class VerilyService {
      * Removing a link from the external side takes a method whose proof is fresh. A standing
      * proof, such as a link back, is there for anyone to point at: handing one back shows
      * the link exists, not that whoever handed it back holds the account.
+     *
+     * A retired record is renewed by the method it was first shown by and no other. Another
+     * would be listed beneath a main proof nobody has read since, and the record would come
+     * back unconfirmed.
      */
     private chosen;
     /**
@@ -243,7 +251,8 @@ export declare class VerilyService {
      * The live record a connect flow reproves by another method, if there is one: the same
      * subject linked to the same account on the same provider, first shown some other way.
      * The same method again is a second record, as it always was; renewing is how that
-     * one is extended.
+     * one is extended. A retired record is never joined: it is frozen, so proving its account
+     * another way makes a new record and leaves that one as history behind it.
      */
     private joins;
     /**
@@ -289,6 +298,28 @@ export declare class VerilyService {
     mine(local: LocalAccount): Promise<Evidence[]>;
     private owned;
     revoke(id: string, local: LocalAccount): Promise<void>;
+    /**
+     * The holder's records of one account that are not revoked. A mark belongs to an account,
+     * and an account can stand on several records: shown a second way on a record of its own,
+     * or removed once and connected again. They are told apart as a badge tells them, by
+     * provider and the id the provider gave.
+     */
+    private account;
+    /**
+     * The mark an account's records carry, for a record about to stand beside them: every
+     * one neither revoked nor retired, lapsed ones included, since those hold a mark that
+     * must survive their own renewal.
+     */
+    private accountMark;
+    /**
+     * Marks an account as the holder would have it listed, or retires it. Names one record
+     * and acts on the account, or a mark on one record could vanish behind a sibling, and
+     * retiring one could leave the account reading as verified through another.
+     *
+     * No fresh proof is asked for. A mark never widens who can read a record or makes one
+     * read as verified, and a holder retiring an account often can no longer prove it.
+     */
+    mark(id: string, local: LocalAccount, as: 'preferred' | 'current' | 'unused' | 'retired'): Promise<void>;
     share(id: string, local: LocalAccount, revoke?: boolean): Promise<{
         url: string;
         expiresAt: number;
@@ -312,6 +343,8 @@ export declare class VerilyService {
         visibilityApprovedAt: number;
         expiresAt: number;
         revokedAt?: number;
+        mark?: Mark;
+        retiredAt?: number;
         signedUrl?: string;
     }>;
     /**
@@ -334,6 +367,8 @@ export declare class VerilyService {
      * `budget` bounds the reads per run, since providers rate-limit and the alarm this runs
      * on is shared. Oldest first, so nothing starves however many connections are waiting.
      *
+     * A retired record is never asked about: its proof is no longer expected to be there.
+     *
      * Returns how many were confirmed. A connection revoked here is not one of them.
      */
     recheck(budget?: number): Promise<number>;
@@ -347,7 +382,11 @@ export declare class VerilyService {
     private reread;
     /** A provider that never answers must not hold up the maintenance run behind it. */
     private deadline;
-    /** Run periodically. Pending secrets expire immediately; historical evidence defaults to 90 days. */
+    /**
+     * Run periodically. Pending secrets expire immediately; historical evidence defaults to 90
+     * days. A retired record is history its holder asked to keep, so it stays for as long as
+     * it is not revoked, and once revoked goes like any other.
+     */
     prune(retentionMs?: number): Promise<void>;
     private invalidateShare;
     private audit;