@bkazemi/verily 0.1.0 → 0.3.0

package/dist/server/index.js

@@ -1,6 +1,6 @@
-import { attestationLabel, externalLink, externalName, isArtifactProvider, isCodeProvider, isRedirectProvider, localSide, proofTitle, providerMethod, statusLabel, signedBy, } from '../core/index.js';
-import { codeAttempts, VerilyService, Unavailable } from './service.js';
-import { copyScript } from './copy.js';
+import { attestationLabel, 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';
 import { logo } from '../logo.js';
 import { stylesheet, styleVersion } from './style.js';
@@ -26,7 +26,7 @@ const headers = {
     'Referrer-Policy': 'same-origin',
     'X-Robots-Tag': 'noindex, nofollow',
     'X-Content-Type-Options': 'nosniff',
-    'Content-Security-Policy': "default-src 'none'; script-src 'self'; style-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'self'",
+    'Content-Security-Policy': "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'self'",
 };
 const html = (body, status = 200) => new Response(body, {
     status,
@@ -105,12 +105,33 @@ function methodAction(provider) {
 }
 /** What the holder hands back for an artifact method, named for what it is. */
 function artifactField(provider) {
+    if (provider.field)
+        return provider.field;
     if (provider.artifact === 'document')
         return 'Your proof';
     return provider.method === 'backlink'
         ? 'Address of the page carrying your link'
         : 'Address of your published proof';
 }
+/**
+ * Said before the holder approves, where the method they used found another proof already
+ * 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;
+}
+/**
+ * Said above a proof that was handed back and refused, while the flow still waits for it:
+ * why, where the provider said why in words meant for the holder, and how many tries remain.
+ */
+function refusedNote(flow) {
+    if (!flow.tries)
+        return undefined;
+    const left = artifactAttempts - flow.tries;
+    return `${flow.reason ? `That did not check out: ${flow.reason}.` : 'That could not be checked.'} ${left === 1 ? 'One try is' : `${left} tries are`} left.`;
+}
 /** Said beside every artifact method: what the holder publishes is public by design. */
 function artifactNote(provider) {
     return provider.method === 'backlink'
@@ -224,20 +245,32 @@ function evidencePage(e, base, report, keyId) {
         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],
-        ]) +
+        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>
@@ -254,14 +287,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],
-        ]) +
+        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>`);
 }
@@ -353,13 +395,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();
@@ -407,8 +460,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);
@@ -424,16 +477,23 @@ export function createVerily(options) {
                 instructions: provider.instructions(flow.expect),
                 artifact: provider.artifact,
                 field: artifactField(provider),
+                input: provider.input ?? 'url',
+                ...((flow.artifact ?? flow.suggested)
+                    ? { suggested: flow.artifact ?? flow.suggested }
+                    : {}),
+                ...(flow.tries ? { refused: refusedNote(flow) } : {}),
                 note: artifactNote(provider),
             });
         if (flow.phase === 'pending' && isCodeProvider(provider))
             Object.assign(view, { code: codeStep(provider, flow), note: codeNote });
         if (flow.phase === 'approval') {
             const joined = await service.joining(flow);
+            const found = standingNote(flow, service.siteOf(flow.local));
             Object.assign(view, {
                 local: subject(flow.local),
                 external: flow.external,
                 ...(joined ? { joined: { visibility: joined.visibility } } : {}),
+                ...(found ? { standingNote: found } : {}),
                 visibilities: visibilities(flow.local),
                 ...(signs ? { signedNote } : {}),
             });
@@ -444,13 +504,21 @@ 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;
     }
+    /**
+     * What the tab a confirmation was pressed in says. It is the end of that tab's part: the
+     * page that asked is waiting on the flow and carries on from there, so this one offers
+     * nowhere to go.
+     */
+    const confirmed = (flow) => html(page(prefix, flow.phase === 'failed' ? 'Address not confirmed' : 'Address confirmed', flow.phase === 'failed'
+        ? `<p>${escape(flow.reason ?? 'This address could not be confirmed')}.</p>`
+        : '<p>You can close this tab now.</p>'));
     async function handle(request) {
         const url = new URL(request.url);
         if (url.origin !== base.origin ||
@@ -481,6 +549,14 @@ export function createVerily(options) {
                     return new Response(copyScript, {
                         headers: { ...headers, 'Content-Type': 'text/javascript' },
                     });
+                if (path === '/wait.js')
+                    return new Response(waitScript, {
+                        headers: { ...headers, 'Content-Type': 'text/javascript' },
+                    });
+                const phase = path.match(/^\/flows\/([^/]+)\/phase$/);
+                // All a waiting page needs to know, and only the browser that started the flow.
+                if (phase)
+                    return json({ phase: (await service.flow(phase[1], binding(request))).phase });
                 if (path === '/result.js')
                     return new Response(`const e=document.getElementById('verily-result');if(window.opener&&e){window.opener.postMessage({type:'verily-result',outcome:e.dataset.outcome,connectionId:e.dataset.id},location.origin);window.close()}`, { headers: { ...headers, 'Content-Type': 'text/javascript' } });
                 if (path === '/verify' ||
@@ -564,10 +640,11 @@ export function createVerily(options) {
                             if ((await local(request)).id !== flow.local?.id)
                                 throw new Unavailable();
                         return html(page(prefix, `Verify with ${provider.name}`, `${instructions(provider.instructions(flow.expect))}
+            ${flow.tries ? `<p>${escape(refusedNote(flow))}</p>` : ''}
             <form method="post" action="${escape(prefix)}/flows/${escape(flow.id)}/submit">
             <label>${escape(artifactField(provider))} ${provider.artifact === 'document'
-                            ? '<textarea name="artifact" rows="14" cols="72" required></textarea>'
-                            : '<input name="artifact" type="url" required>'}</label>
+                            ? `<textarea name="artifact" rows="14" cols="72" required>${escape(flow.artifact ?? '')}</textarea>`
+                            : `<input name="artifact" type="${provider.input ?? 'url'}" value="${escape(flow.artifact ?? flow.suggested ?? '')}" autocapitalize="none" spellcheck="false" required>`}</label>
             <button>Check my proof</button></form>
             <p class="fine">${escape(artifactNote(provider))}</p>
             <script src="${escape(prefix)}/copy.js" defer></script>`));
@@ -580,7 +657,7 @@ export function createVerily(options) {
                         const step = codeStep(provider, flow);
                         return html(page(prefix, `Verify with ${provider.name}`, `${step.sentTo === undefined
                             ? ''
-                            : `<p>A message was sent to ${escape(step.sentTo)}. Press the button in it, then come back to this page.</p><p><a href="${escape(prefix)}/flows/${escape(flow.id)}">I pressed the button</a></p><p>Or enter the code from the message here.</p>${step.wrong
+                            : `<p>A message was sent to ${escape(step.sentTo)}. Press the button in it, and this page carries on.</p><noscript><p><a href="${escape(prefix)}/flows/${escape(flow.id)}">I pressed the button</a></p></noscript><p>Or enter the code from the message here.</p>${step.wrong
                                 ? `<p>That code did not match. ${step.triesLeft === 1 ? 'One try is' : `${step.triesLeft} tries are`} left.</p>`
                                 : ''}`}
             <form method="post" action="${escape(prefix)}/flows/${escape(flow.id)}/submit">
@@ -588,7 +665,7 @@ export function createVerily(options) {
                             ? `<input name="artifact" type="${step.input}" autocomplete="${step.input}" required>`
                             : '<input name="artifact" autocomplete="one-time-code" autocapitalize="characters" spellcheck="false" required>'}</label>
             <button>${step.sentTo === undefined ? `Send the ${escape(provider.name.toLowerCase())}` : 'Check my code'}</button></form>
-            ${step.sentTo === undefined ? `<p class="fine">${escape(codeNote)}</p>` : ''}`));
+            ${step.sentTo === undefined ? `<p class="fine">${escape(codeNote)}</p>` : `<script src="${escape(prefix)}/wait.js" defer></script>`}`));
                     }
                     if (flow.phase !== 'approval')
                         return await ended(flow);
@@ -599,6 +676,7 @@ export function createVerily(options) {
                     // visibility was chosen when it was made and is not the holder's to rechoose here.
                     const joined = await service.joining(flow);
                     const kept = ['revoke', 'share-revoke', 'renew'].includes(flow.kind) || joined;
+                    const found = standingNote(flow, service.siteOf(flow.local));
                     return html(page(prefix, ['revoke', 'share-revoke'].includes(flow.kind)
                         ? 'Remove connection'
                         : flow.kind === 'renew'
@@ -609,6 +687,7 @@ export function createVerily(options) {
             ${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)}
             ${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>
             <form method="post" action="${escape(prefix)}/flows/${escape(flow.id)}/approve">
             ${kept ? '<input type="hidden" name="visibility" value="unlisted">' : visibilityChoice(flow.local, visibilities(flow.local), signs)}
@@ -617,11 +696,16 @@ export function createVerily(options) {
                 }
                 const confirmation = path.match(/^\/confirm\/([^/]+)$/);
                 // Where the button in a message leads, in whatever browser the holder reads mail
-                // in. Arriving confirms nothing: a scanner that opens every link in a message gets
-                // this page and stops, and the holder is shown what they are confirming first.
+                // in. In the browser that started the flow, arriving is the confirmation: its
+                // cookie shows the one who asked is the one who opened the message. Anywhere else
+                // arriving confirms nothing: a scanner that opens every link in a message carries
+                // no cookie, gets this page and stops, and a holder on another device is shown
+                // what they are confirming first.
                 if (confirmation) {
                     const token = url.searchParams.get('token') ?? '';
                     const asked = await service.confirming(confirmation[1], token);
+                    if (await service.flow(confirmation[1], binding(request)).catch(() => undefined))
+                        return confirmed(await service.confirm(confirmation[1], token));
                     const next = {
                         connect: `link it to this ${subjectNoun(asked.local?.kind) ?? 'site'}`,
                         renew: 'renew its link',
@@ -720,22 +804,16 @@ export function createVerily(options) {
                     const flow = await service.start(user, data.connectionId || undefined, kind, await choose(user, data.connectionId || undefined, {
                         provider: data.provider || undefined,
                         method: data.method || undefined,
-                    }), await context(request, kind));
-                    if (asJson && kind === 'connect')
+                    }), await context(request, kind), 
+                    // Posted from this origin, which the check on every POST has already held it to.
+                    true);
+                    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));
                 }
                 const confirmation = path.match(/^\/confirm\/([^/]+)$/);
                 if (confirmation) {
-                    const flow = await service.confirm(confirmation[1], data.token ?? '');
-                    // The flow is still the browser's that started it. This one may be that browser,
-                    // and then it can carry on from here; any other is sent back to where it began.
-                    const here = await service.flow(flow.id, binding(request)).catch(() => undefined);
-                    return html(page(prefix, flow.phase === 'failed' ? 'Address not confirmed' : 'Address confirmed', flow.phase === 'failed'
-                        ? `<p>${escape(flow.reason ?? 'This address could not be confirmed')}.</p>`
-                        : `<p>Go back to the page where you started. It carries on from here.</p>${here
-                            ? `<p><a href="${escape(prefix)}/flows/${escape(flow.id)}">Or carry on in this window</a></p>`
-                            : '<p>You can close this window.</p>'}`));
+                    return confirmed(await service.confirm(confirmation[1], data.token ?? ''));
                 }
                 const submission = path.match(/^\/flows\/([^/]+)\/submit$/);
                 if (submission) {
@@ -769,15 +847,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

@@ -86,6 +86,9 @@ export function linkProvider(options) {
             }
             return account(page, profile);
         },
+        // A page that carries the link is at the address it is named by, so a record of one
+        // already says where to look.
+        known: (account) => account.profileUrl,
     };
 }
 /**
@@ -216,18 +219,32 @@ export function githubLinkProvider(options = {}) {
         id: 'github',
         name: 'GitHub',
         hosts: ['github.com'],
-        // GitHub's own rule: alphanumerics and single hyphens, never leading or trailing, 39 max.
-        profile: /^\/([A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38})$/,
+        profile: new RegExp(`^/(${username})$`),
     });
+    // A profile is at its username, so the username is all the holder needs to give. A
+    // leading @ is how one is written, and is not part of it.
+    const named = new RegExp(`^@?(${username})$`);
     return {
         ...provider,
         // GitHub writes the rel="me" itself, so the holder only fills in one field.
         instructions: (expect) => [
-            'Put this address in the website field of your GitHub profile, then paste your profile’s address below.',
+            'Put this address in the website field of your GitHub profile, then enter your GitHub username below.',
             { code: expect },
         ],
+        field: 'Your GitHub username',
+        input: 'text',
+        resolve(artifact) {
+            const name = named.exec(artifact.trim())?.[1];
+            return name ? `https://github.com/${name}` : artifact;
+        },
+        // Only an account has a username. The handle of anything else is not one.
+        known: (account) => (account.kind ?? 'account') === 'account' && named.test(account.handle)
+            ? account.handle.replace(/^@/, '')
+            : undefined,
     };
 }
+/** GitHub's own rule: alphanumerics and single hyphens, never leading or trailing, 39 max. */
+const username = '[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}';
 /**
  * Whether a link points at the subject. Every key in the subject's query must carry the
  * same values in the same order on the link, since a site whose profiles differ only by a
@@ -244,7 +261,10 @@ function points(href, base, subject) {
     }
     // A subject with a fragment is one of the views a hash-routed page serves, so the
     // fragment names it and must match. A fragment on the link alone is a spot on the page.
-    if (target.protocol !== subject.protocol ||
+    // A site reached over http is the same site as over https, and a profile field given a
+    // bare domain is often written as the former. Any other scheme is some other resource.
+    const scheme = target.protocol === 'http:' && subject.protocol === 'https:' ? 'https:' : target.protocol;
+    if (scheme !== subject.protocol ||
         target.host.toLowerCase() !== subject.host.toLowerCase() ||
         trim(target.pathname) !== trim(subject.pathname) ||
         (subject.hash !== '' && target.hash !== subject.hash))

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. */
@@ -84,7 +88,13 @@ export declare class VerilyService {
     start(local?: LocalAccount, connectionId?: string, kind?: Flow['kind'], choice?: {
         provider?: string;
         method?: string;
-    }, context?: Record<string, string>): Promise<{
+    }, context?: Record<string, string>, 
+    /**
+     * Whether the caller has shown the holder asked for this themselves, as a form posted
+     * from their own page shows and following a link does not. Without it the flow reads
+     * nothing at its start and ends on an approval, however little there is to approve.
+     */
+    attended?: boolean): Promise<{
         flowId: string;
         binding: string;
         expect: string;
@@ -103,6 +113,19 @@ export declare class VerilyService {
         instructions?: undefined;
         authorizationUrl?: undefined;
     }>;
+    /**
+     * What a new flow can offer the holder to hand back: the one account this subject has
+     * already shown some other way, which is the record the flow would join. With several,
+     * which one they mean is theirs to say.
+     */
+    private known;
+    /**
+     * Reads the proof at the account a record already names, before the holder is asked for
+     * anything. Found, the flow goes straight to approval, as if they had handed it back.
+     * Not found is no failure: they have not been told what to publish yet, so the flow
+     * stays where it was and tells them.
+     */
+    private offered;
     /**
      * Which method a flow runs. A flow on an existing record stays in that record's
      * namespace, and without a choice it uses the method the record was first shown by.
@@ -110,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;
     /**
@@ -119,6 +146,13 @@ export declare class VerilyService {
      * code that arrived there.
      */
     submit(id: string, binding: string, artifact: string): Promise<string>;
+    /**
+     * Takes a refused proof as something the holder can put right, and leaves the flow
+     * waiting for it. What they must publish is minted per flow, so a flow ended here would
+     * have them publish or sign all over again for a mistyped address. The tries are counted
+     * all the same: each one is a fetch somewhere the holder chose.
+     */
+    private refused;
     /**
      * One step of a mailed code. The first answer is an address: a code is minted, sent
      * there, and only its hash kept. The second is the code, which the holder could only
@@ -168,8 +202,18 @@ export declare class VerilyService {
      */
     private established;
     /**
-     * A failed check leaves the flow dead rather than retryable in place. Only a `Refused`
-     * reason is kept: any other error may describe this backend rather than the proof.
+     * The proofs already standing for the account a flow just showed, by the other methods
+     * configured for its provider that can tell where to look from the account alone. One
+     * that is not there, or cannot be read, is simply not found: the holder asked for none
+     * of them, so none of them can fail the flow.
+     */
+    private standing;
+    /** Adds the proofs a flow found standing beneath the method the record was first shown by. */
+    private recordStanding;
+    /**
+     * A sign-in or a mailed code that fails leaves the flow dead: there is nothing in it to
+     * put right, and starting again costs the holder nothing. Only a `Refused` reason is
+     * kept: any other error may describe this backend rather than the proof.
      */
     private failed;
     approve(id: string, binding: string, local: LocalAccount | undefined, visibility: Visibility, cancel?: boolean, 
@@ -179,6 +223,15 @@ export declare class VerilyService {
      * this approval makes a record or joins one, so no change in between gets past it.
      */
     allowed?: Visibility[]): Promise<string | undefined>;
+    /**
+     * Whether approving a flow would decide anything. A renewal, or another way of showing
+     * an account the subject is already linked to, changes neither who is linked nor who
+     * can read it: the holder asked for exactly this and the account has been checked
+     * against the record, so it is recorded without asking them to say so again.
+     */
+    private settled;
+    /** Records what an approved flow does, and ends it. The caller has checked who approves. */
+    private conclude;
     /**
      * Ends a flow and records how, inside the transaction that ends it: the connection as it
      * stands now, since whatever later reports this result must not read a record that has
@@ -198,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;
     /**
@@ -244,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;
@@ -267,6 +343,8 @@ export declare class VerilyService {
         visibilityApprovedAt: number;
         expiresAt: number;
         revokedAt?: number;
+        mark?: Mark;
+        retiredAt?: number;
         signedUrl?: string;
     }>;
     /**
@@ -289,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>;
@@ -302,10 +382,16 @@ 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;
 }
 /** How many wrong codes a flow takes before it is dead. */
 export declare const codeAttempts = 5;
+/** How many times a published proof may be refused before its flow is dead. */
+export declare const artifactAttempts = 5;