@bkazemi/verily 0.2.0 → 0.3.0

package/README.md

@@ -16,7 +16,7 @@
   <img src="docs/images/badge.png" alt="A profile card with a Verily badge showing a GitHub account" width="480" />
 </p>
 
-Verily is a self-hosted library for Node.js. A signed-in user of your site proves they control an external account, by signing in with GitHub, publishing a gist, linking back with `rel="me"`, or signing with an OpenPGP key. They approve the connection, and Verily publishes it as a record anyone can inspect, with a badge for their profile.
+Verily is a self-hosted library for Node.js. A signed-in user of your site proves they control an external account, by signing in with GitHub, Discord or YouTube, publishing a gist, linking back with `rel="me"`, signing with an OpenPGP key, or answering a mailed link. They approve the connection, and Verily publishes it as a record anyone can inspect, with a badge for their profile.
 
 It doesn't sign anyone into your site, and it doesn't establish legal identity.
 
@@ -86,15 +86,15 @@ const verily = createVerily({
 });
 ```
 
-| Option           | Meaning                                                                                             |
-| ---------------- | --------------------------------------------------------------------------------------------------- |
-| `provider`       | How users prove an external account. One provider or an array; see [Proof methods](#proof-methods). |
-| `baseUrl`        | The public URL you mount Verily at. Every route it serves is under this path.                       |
-| `siteName`       | Your site's name, shown on evidence.                                                                |
-| `verifierName`   | Who vouches for the record, shown on evidence. Usually the backend's domain.                        |
-| `profileOrigins` | The origins a local `profileUrl` may be on.                                                         |
-| `reportUrl`      | Where readers report a bad record (`https:` or `mailto:`).                                          |
-| `authenticate`   | Returns the signed-in local account for a request, or `undefined` if nobody is signed in.           |
+| Option           | Meaning                                                                                   |
+| ---------------- | ----------------------------------------------------------------------------------------- |
+| `providers`      | How users prove an external account, as a list; see [Proof methods](#proof-methods).      |
+| `baseUrl`        | The public URL you mount Verily at. Every route it serves is under this path.             |
+| `siteName`       | Your site's name, shown on evidence.                                                      |
+| `verifierName`   | Who vouches for the record, shown on evidence. Usually the backend's domain.              |
+| `profileOrigins` | The origins a local `profileUrl` may be on.                                               |
+| `reportUrl`      | Where readers report a bad record (`https:` or `mailto:`).                                |
+| `authenticate`   | Returns the signed-in local account for a request, or `undefined` if nobody is signed in. |
 
 Sign-in methods need an app registered with the provider, and each site running Verily registers its own. The callback URL is always `<baseUrl>/callback`, so for `baseUrl: 'https://example.com/api/verily'` it is `https://example.com/api/verily/callback`. The provider redirects only to URLs registered in advance, so each place you run Verily, a local one for development included, needs its callback registered.
 
@@ -145,7 +145,7 @@ import { init } from '@bkazemi/verily'; // also registers <verily-badge>
 const client = init({ backendUrl: '/api/verily' });
 ```
 
-Without one, serve `node_modules/@bkazemi/verily/dist/verily.js` yourself, or load it from a CDN such as `https://cdn.jsdelivr.net/npm/@bkazemi/verily@0.2.0/dist/verily.js`. The script defines a global `Verily`.
+Without one, serve `node_modules/@bkazemi/verily/dist/verily.js` yourself, or load it from a CDN such as `https://cdn.jsdelivr.net/npm/@bkazemi/verily@0.3.0/dist/verily.js`. The script defines a global `Verily`.
 
 Then place the badge wherever the account appears:
 
@@ -168,6 +168,8 @@ A user with several accounts gets one badge for all of them. Give it every conne
 
 It shows the account that was connected first, then how many more there are, such as `+2`. Clicking it opens the same details, with each account on its own card in the order they were connected. Only accounts that are verified now are counted, and one of those leads if the first has lapsed. An account that appears on more than one record, because it was shown a second way or removed and connected again, is shown once. The ids must all belong to the same user.
 
+A holder can change that order. The account they mark as preferred comes first and leads the badge, and the ones they mark as unused come after the rest; an unused account is still verified and still counted. An account they retire is kept as history: it is never counted, sits in a group of its own at the foot of the details, and reads as retired with the date it was last verified. A badge with nothing but retired accounts is a quiet pill that names the first and opens the same details. If you would rather show nothing, leave retired records out of what you give the badge.
+
 On a desktop, resting the pointer on that badge, or reaching it with the keyboard, opens a small panel beside it naming the accounts the number stands for: up to eight, then the rest as a count. The panel floats over the page, so nothing moves, and clicking still opens the details. It needs a browser with the Popover API; without one the badge simply has no panel. Add `peek="off"` to the badge to leave it out.
 
 Add `stacked` to name the accounts in the badge itself, one to a row:
@@ -189,8 +191,11 @@ await client.openConnect(); // the connect dialog; call from a click
 await client.connect({ provider: 'github' }); // opens <baseUrl>/verify in a popup; call from a click
 await client.mountBadge(element, { connectionId }); // draws once; call again to refresh
 await client.disconnect(connectionId);
+await client.mark(connectionId, 'preferred'); // or 'unused', 'current', 'retired'
 ```
 
+`mark` names one record and acts on the account, on every record of it the user has. Preferring one account takes the mark from whichever had it. Retiring freezes the records at their last proof: they are never rechecked, never read as verified, cannot change visibility, and are kept until removed. Only a renewal by the method a record was first shown by brings it back.
+
 To match your site's look, set any of these CSS variables on an ancestor: `--verily-surface`, `--verily-text`, `--verily-border`, `--verily-muted`, `--verily-hover`, `--verily-font-family`, `--verily-font-size`.
 
 ## Proof methods
@@ -216,7 +221,7 @@ import {
 | `linkProvider()`       | adding a `rel="me"` link to their profile on a page they control.                                            | The local account needs a `profileUrl`. |
 | `githubLinkProvider()` | putting their profile URL in the website field of their GitHub profile, then entering their GitHub username. | The local account needs a `profileUrl`. |
 | `pgpProvider()`        | signing a line Verily gives them with their OpenPGP key, then pasting it and the key.                        | None.                                   |
-| `emailProvider()`      | entering a code Verily mails to their address.                                                               | A function that sends one message.      |
+| `emailProvider()`      | pressing a button, or entering a code, that Verily mails to their address.                                   | A function that sends one message.      |
 
 All methods except the sign-ins and the mailed code let the user publish the proof in their own time and come back. A proof that does not check out can be put right and handed back on the same step, up to five times, so a mistyped address never means publishing or signing again. Gists and link-backs can be taken down later, so Verily re-reads them on a schedule. A PGP signature is kept by Verily and published at `<baseUrl>/connections/<id>/proof`.
 
@@ -288,7 +293,7 @@ A static site only needs the script and the badge markup; the backend runs somew
 4. Add the script and the badge to your site:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@bkazemi/verily@0.2.0/dist/verily.js" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/@bkazemi/verily@0.3.0/dist/verily.js" defer></script>
 <verily-badge
   backend-url="https://your-backend.example/api/verily"
   connection-id="CONNECTION_ID"
@@ -361,7 +366,7 @@ Once a user has a link, show their badge in place of the pill, and give it the s
 ></verily-badge>
 ```
 
-The badge's dialog then has Renew and Remove under each account, and Add account below them, which opens the verify flow in the dialog's place with a way back. It fires `verily-result` on each change. `verily.beginUrl('manage')` still opens a user's links on the instance, for a site that would rather link there.
+The badge's dialog then has Renew and Remove under each account, the controls that mark it as preferred or unused or retire it, and Add account below them, which opens the verify flow in the dialog's place with a way back. Renew shows the same account again and extends that record under its id, so an embed that names it keeps working. A retired account is renewed by the method it was first shown by. It fires `verily-result` on each change. `verily.beginUrl('manage')` still opens a user's links on the instance, for a site that would rather link there.
 
 **3. Read connections where you show them.**
 
@@ -370,6 +375,8 @@ const { [user.id]: connections } = await verily.connections([user.id]);
 const verified = connections.filter((c) => c.status === 'verified');
 ```
 
+Show only `verified` records as verified. A `retired` record is an account the user said is finished: it carries `retiredAt` and can be shown as history, never as a current account. `mark` is `preferred` or `unused` where the user set one, which is their word on how to order their accounts and nothing that was checked.
+
 To show them, hand the records to the badge. It draws them as given and fetches nothing, so it works for unlisted links, which a browser cannot read for itself:
 
 ```html
@@ -427,7 +434,7 @@ createVerily({
 
 With a key set:
 
-- **`GET <baseUrl>/connections/<id>?format=signed`** returns the signed file for a public record that is currently verified: the record as JSON under an OpenPGP cleartext signature. It is signed when asked for, so it says the record stood at that moment. An unlisted, revoked or expired record has no signed form.
+- **`GET <baseUrl>/connections/<id>?format=signed`** returns the signed file for a public record that is currently verified: the record as JSON under an OpenPGP cleartext signature. It is signed when asked for, so it says the record stood at that moment. An unlisted, revoked or expired record has no signed form. A public retired record has one, signed as `version: 2` with `status: "retired"` and `retiredAt`, so a reader that knows only version 1 refuses it and never takes it for a record that stood.
 - **`GET <baseUrl>/keys.asc`** is the public key as `gpg --import` reads it. **`GET <baseUrl>/keys`** lists the same keys as JSON, each with its fingerprint. The Cloudflare Worker also serves that list at `/.well-known/verily-keys.json`.
 - **`<baseUrl>/check`** is a page where a saved file can be pasted and read back.
 - The evidence page says the record is signed and links to the signed record. The badge's dialog checks the signature in the browser with OpenPGP.js, which it starts only when a record is signed, marks the record `signed ✓`, and links to that page. A record whose signature fails is shown as unconfirmed.
@@ -475,7 +482,7 @@ setInterval(
 );
 ```
 
-- **`prune()`** deletes expired flows, and deletes expired or revoked records after 90 days.
+- **`prune()`** deletes expired flows, and deletes expired or revoked records after 90 days. A retired record is kept until it is removed.
 - **`recheck()`** re-reads gists and link-backs that are due, up to 5 per run (its `budget` argument). Each proof is re-read every 24 hours (`recheckMs`) and stays current for 7 days after its last successful read (`freshnessMs`); after that it shows as unconfirmed until a read succeeds. A failed read changes nothing. For PGP, it asks the keyserver whether the key has been revoked, and revokes the connection if so.
 
 **If you never call `recheck()`, set `freshnessMs: Infinity`.** Otherwise connections proved by gist, link-back or PGP lapse after a week.

package/dist/browser/badge.js

@@ -1,5 +1,5 @@
 import { externalName, statusLabel } from '../core/index.js';
-import { clockMark, dashMark, markStyles, paintMark, verificationMark } from './mark.js';
+import { boxMark, clockMark, dashMark, markStyles, paintMark, verificationMark } from './mark.js';
 import { providerMark } from './provider-mark.js';
 const styles = `
   :host { display: inline-block; max-width: 100%; vertical-align: middle; }
@@ -53,7 +53,9 @@ const styles = `
   .peek .via { display: block; margin-top: 6px; font-size: 11px; color: var(--verily-muted, #65726c); }
   .provider { display: block; flex-shrink: 0; width: 14px; height: 14px; }
   .expired .icon { color: #815a12; background: #fbefce; }
-  .revoked .icon, .message .icon { color: #626d69; background: #edf0ee; }
+  .revoked .icon, .retired .icon, .message .icon { color: #626d69; background: #edf0ee; }
+  /* Nothing ran out and nothing wants attention: the holder chose this, so it is only quiet. */
+  .retired .name { color: var(--verily-muted, #65726c); }
   .message { color: var(--verily-muted, #65726c); }
   .add { font-weight: 600; }
   @media (prefers-reduced-motion: no-preference) {
@@ -227,7 +229,14 @@ export function renderBadgeMessage(element, message) {
 export function renderBadge(element, evidence, { more = 0, linked = true, rows = [], peek = false, } = {}) {
     const provider = evidence.providerName;
     const current = evidence.status === 'verified' && evidence.expiresAt > Date.now();
-    const state = current ? 'verified' : evidence.status === 'revoked' ? 'revoked' : 'expired';
+    const retired = evidence.status === 'retired';
+    const state = current
+        ? 'verified'
+        : retired
+            ? 'retired'
+            : evidence.status === 'revoked'
+                ? 'revoked'
+                : 'expired';
     const label = statusLabel(evidence, Date.now());
     const key = renderKey(evidence, current, label, more, linked, rows, peek);
     if (intact(element) && shown.get(element) === key)
@@ -237,7 +246,9 @@ export function renderBadge(element, evidence, { more = 0, linked = true, rows =
     const unnamed = Math.max(more - rows.length, 0);
     const named = rows.map((row) => `, ${row.providerName} ${externalName(row.external)}`).join('');
     const others = `${named}${unnamed ? ` and ${unnamed} more` : ''}`;
-    paintMark(mark, current ? 'current' : 'inactive');
+    // A retired account claims nothing now, so its mark is drawn as one waiting to be read
+    // is: in the page's text colour, and not as a verification that failed.
+    paintMark(mark, current ? 'current' : retired ? 'pending' : 'inactive');
     if (linked) {
         badge.href = evidence.evidenceUrl;
         badge.rel = 'noreferrer';
@@ -282,7 +293,7 @@ export function renderBadge(element, evidence, { more = 0, linked = true, rows =
     }
     if (!current) {
         const icon = span('icon', '');
-        icon.append(state === 'expired' ? clockMark() : dashMark());
+        icon.append(retired ? boxMark() : state === 'expired' ? clockMark() : dashMark());
         icon.setAttribute('aria-hidden', 'true');
         badge.append(span('label', label), icon);
     }

package/dist/browser/connect-dialog.d.ts

@@ -64,7 +64,8 @@ export interface FlowView {
 }
 export interface ConnectApi {
     methods(): Promise<Methods>;
-    start(provider: string, method: string): Promise<FlowView>;
+    /** Starts a flow by one method: a new link, or a renewal of the record `renew` names. */
+    start(provider: string, method: string, renew?: string): Promise<FlowView>;
     read(id: string): Promise<FlowView>;
     submit(id: string, artifact: string): Promise<FlowView>;
     approve(id: string, visibility: 'public' | 'unlisted', cancel: boolean): Promise<Result>;
@@ -87,5 +88,15 @@ export declare function openConnectDialog(opener: HTMLElement, api: ConnectApi,
  */
 back?: () => void, 
 /** The provider to start on, where the holder already said which account they mean. */
-provider?: string): Promise<Result>;
+provider?: string, 
+/**
+ * The record to renew, where the holder asked to show one of their accounts again: each
+ * flow started then extends that record under its id. `method` is the one method that
+ * may, for a retired record. Where the holder is not offered it, a new link is the way
+ * back, and the dialog connects as it would with no record named.
+ */
+renew?: {
+    id: string;
+    method?: string;
+}): Promise<Result>;
 export {};

package/dist/browser/connect-dialog.js

@@ -1,7 +1,6 @@
 import { externalLink, externalName } from '../core/index.js';
-import { accountCard, linkMark, node, outward, styles } from './evidence-dialog.js';
+import { accountCard, linkMark, node, outward, stampLink, styles } from './evidence-dialog.js';
 import { providerMark } from './provider-mark.js';
-import { verilyLogo } from './logo.js';
 import { version } from '../version.js';
 const connectStyles = `
   ${styles}
@@ -91,7 +90,14 @@ export function openConnectDialog(opener, api,
  */
 back, 
 /** The provider to start on, where the holder already said which account they mean. */
-provider) {
+provider, 
+/**
+ * The record to renew, where the holder asked to show one of their accounts again: each
+ * flow started then extends that record under its id. `method` is the one method that
+ * may, for a retired record. Where the holder is not offered it, a new link is the way
+ * back, and the dialog connects as it would with no record named.
+ */
+renew) {
     const existing = openDialogs.get(opener);
     if (existing?.open) {
         existing.focus();
@@ -113,7 +119,7 @@ provider) {
     close.type = 'button';
     close.setAttribute('aria-label', 'Close');
     content.setAttribute('aria-live', 'polite');
-    stamp.append(verilyLogo(), node('span', version));
+    stamp.append(stampLink(), node('span', version));
     header.append(heading, close);
     dialog.append(header, content, stamp);
     root.append(dialog);
@@ -208,7 +214,11 @@ provider) {
         }
         if (!current(asked))
             return;
-        const all = methods.methods;
+        // A record's renewal stays on its provider, by the one method named where one is.
+        const renewing = methods.methods.filter((m) => m.provider === provider && (renew?.method === undefined || m.method === renew.method));
+        if (renew && !renewing.length)
+            renew = undefined;
+        const all = renew ? renewing : methods.methods;
         // A provider asked for that this holder is not offered leaves every option open.
         if (group !== undefined && !all.some((m) => m.provider === group))
             group = undefined;
@@ -243,7 +253,7 @@ provider) {
                         return;
                     }
                 }
-                void busy(control, () => api.start(choice.provider, choice.method), show);
+                void busy(control, () => api.start(choice.provider, choice.method, renew?.id), show);
             };
             list.append(control);
         }
@@ -255,7 +265,7 @@ provider) {
                 : 'Choose how to show you control the other account.', 'explanation'),
             list,
         ];
-        if (group !== undefined) {
+        if (group !== undefined && !renew) {
             const back = button('‹ All options');
             back.onclick = () => {
                 group = undefined;

package/dist/browser/evidence-dialog.d.ts

@@ -1,5 +1,7 @@
 import { type Evidence } from '../core/index.js';
-export declare const styles = "\n  * { box-sizing: border-box; }\n  dialog { width: min(460px, calc(100vw - 32px)); max-height: calc(100dvh - 40px); margin: auto; padding: 24px; border: 1px solid #dce2de; border-radius: 16px; background: #fff; color: #23312b; box-shadow: 0 24px 90px #10201935; font: 13px/1.6 system-ui, sans-serif; }\n  dialog::backdrop { background: #15271f66; }\n  header { display: flex; align-items: center; justify-content: space-between; gap: 16px; margin-bottom: 20px; }\n  h2 { margin: 0; font-size: 18px; font-weight: 650; letter-spacing: -.3px; }\n  button { width: 32px; height: 32px; border: 1px solid #dce2de; border-radius: 8px; background: #fff; color: #52645a; font: 20px system-ui, sans-serif; cursor: pointer; }\n  button:hover { background: #f2f5f1; }\n  a { color: #245f43; text-underline-offset: 3px; overflow-wrap: anywhere; }\n  a:focus-visible, button:focus-visible { outline: 2px solid #357ce5; outline-offset: 3px; }\n  .summary { display: flex; align-items: center; gap: 8px; margin-top: 16px; }\n  .mark { width: 36px; height: 36px; flex-shrink: 0; }\n  .provider { width: 14px; height: 14px; }\n  .state { font-size: 14px; font-weight: 650; line-height: 1.4; }\n  .muted { color: #6b786f; font-size: 12px; }\n  .account { position: relative; }\n  .veiled > :not(.checking) { filter: blur(4px); opacity: .55; user-select: none; }\n  .checking { position: absolute; inset: 0; display: flex; align-items: center; justify-content: center; gap: 8px; color: #23312b; font-size: 13px; font-weight: 600; }\n  .spinner { width: 14px; height: 14px; border: 2px solid currentColor; border-right-color: transparent; border-radius: 50%; animation: spin .7s linear infinite; }\n  @keyframes spin { to { transform: rotate(360deg); } }\n  @media (prefers-reduced-motion: reduce) { .spinner { animation: none; } }\n  .caution { display: inline-block; margin-left: 4px; color: #a15c00; cursor: help; vertical-align: middle; }\n  .caution svg { display: block; width: 12px; height: 12px; }\n  .bad { color: #b3261e; font-weight: 650; text-decoration: underline dotted; text-underline-offset: 3px; cursor: help; }\n  .account { padding: 14px 16px; border: 1px solid #e0e6df; border-radius: 10px; margin-top: 12px; }\n  .account h3 { display: flex; align-items: center; gap: 6px; margin: 0 0 3px; color: #6b786f; font-size: 11px; font-weight: 550; }\n  .account a, .account strong { font-weight: 650; font-size: 14px; }\n  /* The account's own name carries that weight; a link inside a line of prose does not. */\n  .summary a, .method a, .additional a { font: inherit; }\n  .reference { margin-top: 2px; }\n  .method { margin-top: 8px; }\n  .additional { margin-top: 2px; padding-left: 12px; }\n  .joiner { display: block; width: 20px; height: 20px; margin: 8px auto -4px; color: #90a096; }\n  dl { margin: 16px 0 0; padding-top: 12px; border-top: 1px solid #e5e9e3; display: grid; grid-template-columns: auto 1fr; gap: 5px 16px; font-size: 11px; }\n  dt { color: #6b786f; }\n  dd { margin: 0; text-align: right; overflow-wrap: anywhere; }\n  .explanation { margin-top: 16px; }\n  .action { width: auto; height: auto; padding: 9px 14px; font: 600 13px/1.3 system-ui, sans-serif; color: #23312b; text-align: left; }\n  .action.primary { border-color: #245f43; background: #245f43; color: #fff; }\n  .action.primary:hover { background: #1d4f37; }\n  .action:disabled { opacity: .6; cursor: progress; }\n  .action.danger:hover { border-color: #b3261e; background: #fdecea; color: #b3261e; }\n  .row { display: flex; justify-content: end; gap: 8px; margin-top: 16px; }\n  .account .row { align-items: center; justify-content: start; margin-top: 12px; }\n  .account .action { padding: 5px 10px; font-size: 12px; }\n  footer { display: flex; align-items: center; justify-content: start; gap: 6px; margin-top: 14px; color: #9aa9a0; font-size: 11px; }\n  .logo { display: block; height: 13px; }\n  \n  @media (prefers-reduced-motion: no-preference) {\n    .mark.current path:last-child { animation: verily-draw .8s cubic-bezier(.65, 0, .35, 1) .1s backwards; }\n  }\n  @keyframes verily-draw { from { stroke-dasharray: 0 176; } to { stroke-dasharray: 108 176; } }\n\n";
+/** The logotype as a link to the project, as both dialogs carry it in their footer. */
+export declare function stampLink(): HTMLAnchorElement;
+export declare const styles = "\n  * { box-sizing: border-box; }\n  dialog { width: min(460px, calc(100vw - 32px)); max-height: calc(100dvh - 40px); margin: auto; padding: 24px; border: 1px solid #dce2de; border-radius: 16px; background: #fff; color: #23312b; box-shadow: 0 24px 90px #10201935; font: 13px/1.6 system-ui, sans-serif; }\n  dialog::backdrop { background: #15271f66; }\n  header { display: flex; align-items: center; justify-content: space-between; gap: 16px; margin-bottom: 20px; }\n  h2 { margin: 0; font-size: 18px; font-weight: 650; letter-spacing: -.3px; }\n  button { width: 32px; height: 32px; border: 1px solid #dce2de; border-radius: 8px; background: #fff; color: #52645a; font: 20px system-ui, sans-serif; cursor: pointer; }\n  button:hover { background: #f2f5f1; }\n  a { color: #245f43; text-underline-offset: 3px; overflow-wrap: anywhere; }\n  a:focus-visible, button:focus-visible { outline: 2px solid #357ce5; outline-offset: 3px; }\n  .summary { display: flex; align-items: center; gap: 8px; margin-top: 16px; }\n  .mark { width: 36px; height: 36px; flex-shrink: 0; }\n  .provider { width: 14px; height: 14px; }\n  .state { font-size: 14px; font-weight: 650; line-height: 1.4; }\n  .muted { color: #6b786f; font-size: 12px; }\n  .account { position: relative; }\n  .veiled > :not(.checking) { filter: blur(4px); opacity: .55; user-select: none; }\n  .checking { position: absolute; inset: 0; display: flex; align-items: center; justify-content: center; gap: 8px; color: #23312b; font-size: 13px; font-weight: 600; }\n  .spinner { width: 14px; height: 14px; border: 2px solid currentColor; border-right-color: transparent; border-radius: 50%; animation: spin .7s linear infinite; }\n  @keyframes spin { to { transform: rotate(360deg); } }\n  @media (prefers-reduced-motion: reduce) { .spinner { animation: none; } }\n  .caution { display: inline-block; margin-left: 4px; color: #a15c00; cursor: help; vertical-align: middle; }\n  .caution svg { display: block; width: 12px; height: 12px; }\n  .bad { color: #b3261e; font-weight: 650; text-decoration: underline dotted; text-underline-offset: 3px; cursor: help; }\n  .account { padding: 14px 16px; border: 1px solid #e0e6df; border-radius: 10px; margin-top: 12px; }\n  .account h3 { display: flex; align-items: center; gap: 6px; margin: 0 0 3px; color: #6b786f; font-size: 11px; font-weight: 550; }\n  .account a, .account strong { font-weight: 650; font-size: 14px; }\n  /* The account's own name carries that weight; a link inside a line of prose does not. */\n  .summary a, .method a, .additional a { font: inherit; }\n  .reference { margin-top: 2px; }\n  .method { margin-top: 8px; }\n  /* In the corner the heading leaves empty, apart from everything that was checked. */\n  .listing { position: absolute; top: 12px; right: 14px; padding: 1px 8px; border: 1px solid #e0e6df; border-radius: 999px; color: #6b786f; font-size: 11px; font-weight: 550; }\n  .listing.preferred { border-color: #245f43; color: #245f43; }\n  /* Quiet, as its pill is: the surface and the name step back, and the controls do not. */\n  .account.retired { background: #f6f8f5; }\n  .account.retired > a, .account.retired > strong { color: #6b786f; }\n  .account.retired .mark { opacity: .45; }\n  .group { margin: 20px 0 0; color: #6b786f; font-size: 11px; font-weight: 550; }\n  .additional { margin-top: 2px; padding-left: 12px; }\n  .joiner { display: block; width: 20px; height: 20px; margin: 8px auto -4px; color: #90a096; }\n  dl { margin: 16px 0 0; padding-top: 12px; border-top: 1px solid #e5e9e3; display: grid; grid-template-columns: auto 1fr; gap: 5px 16px; font-size: 11px; }\n  dt { color: #6b786f; }\n  dd { margin: 0; text-align: right; overflow-wrap: anywhere; }\n  .explanation { margin-top: 16px; }\n  .action { width: auto; height: auto; padding: 9px 14px; font: 600 13px/1.3 system-ui, sans-serif; color: #23312b; text-align: left; }\n  .action.primary { border-color: #245f43; background: #245f43; color: #fff; }\n  .action.primary:hover { background: #1d4f37; }\n  .action:disabled { opacity: .6; cursor: progress; }\n  .action.danger:hover { border-color: #b3261e; background: #fdecea; color: #b3261e; }\n  .row { display: flex; justify-content: end; gap: 8px; margin-top: 16px; }\n  .account .row { align-items: center; justify-content: start; flex-wrap: wrap; margin-top: 12px; }\n  .account .action { padding: 5px 10px; font-size: 12px; }\n  footer { display: flex; align-items: center; justify-content: start; gap: 6px; margin: 20px 0 -8px; color: #9aa9a0; font-size: 11px; }\n  footer a { display: flex; color: inherit; }\n  .logo { display: block; height: 13px; }\n  \n  @media (prefers-reduced-motion: no-preference) {\n    .mark.current path:last-child { animation: verily-draw .8s cubic-bezier(.65, 0, .35, 1) .1s backwards; }\n  }\n  @keyframes verily-draw { from { stroke-dasharray: 0 176; } to { stroke-dasharray: 108 176; } }\n\n";
 export declare function node<K extends keyof HTMLElementTagNameMap>(tag: K, text?: string, className?: string): HTMLElementTagNameMap[K];
 /**
  * Points an anchor out of the dialog. Every link here opens in a new tab: the dialog is
@@ -28,6 +30,11 @@ export type Account = Evidence & {
      */
     sources?: Evidence[];
 };
+/**
+ * How a holder may have an account listed: the one to lead with, an ordinary one, one they
+ * no longer use, or one that is finished and kept only as history.
+ */
+export type Listing = 'preferred' | 'current' | 'unused' | 'retired';
 /**
  * What the holder of the accounts shown may do from the dialog, where the page that drew
  * the badge said its reader is that holder.
@@ -35,8 +42,19 @@ export type Account = Evidence & {
 export interface Manage {
     /** Opens what connects an account, in this dialog's place. Given a provider, starts on it. */
     connect(provider?: string): void;
+    /**
+     * Opens what renews the record named, in this dialog's place: the same account shown
+     * again, which extends that record under its id. `method` is the one method that may.
+     * Absent where the page gave no way to, and Renew then connects on the provider.
+     */
+    renew?(id: string, provider: string, method?: string): void;
     /** Removes the links named. Rejects if any could not be removed. */
     remove(ids: string[]): Promise<void>;
+    /**
+     * Lists the account one link names as asked, every record of it at once. Rejects if it
+     * could not be. Absent where the page gave no way to, and the card then offers none.
+     */
+    mark?(id: string, as: Listing): Promise<void>;
 }
 /**
  * Fetch fresh, permitted evidence; native dialog supplies focus containment and Escape

package/dist/browser/evidence-dialog.js

@@ -1,9 +1,15 @@
-import { attestationLabel, externalLink, externalName, localSide, proofTitle, statusLabel, } from '../core/index.js';
+import { attestationLabel, externalLink, externalName, lastProved, localSide, proofTitle, statusLabel, } from '../core/index.js';
 import { markStyles, verificationMark } from './mark.js';
 import { providerMark } from './provider-mark.js';
 import { onSignatureResult, signature, standing } from './signed.js';
-import { verilyLogo } from './logo.js';
+import { projectUrl, verilyLogo } from './logo.js';
 import { version } from '../version.js';
+/** The logotype as a link to the project, as both dialogs carry it in their footer. */
+export function stampLink() {
+    const link = outward(node('a'), projectUrl);
+    link.append(verilyLogo());
+    return link;
+}
 const openDialogs = new WeakMap();
 export const styles = `
   * { box-sizing: border-box; }
@@ -36,6 +42,14 @@ export const styles = `
   .summary a, .method a, .additional a { font: inherit; }
   .reference { margin-top: 2px; }
   .method { margin-top: 8px; }
+  /* In the corner the heading leaves empty, apart from everything that was checked. */
+  .listing { position: absolute; top: 12px; right: 14px; padding: 1px 8px; border: 1px solid #e0e6df; border-radius: 999px; color: #6b786f; font-size: 11px; font-weight: 550; }
+  .listing.preferred { border-color: #245f43; color: #245f43; }
+  /* Quiet, as its pill is: the surface and the name step back, and the controls do not. */
+  .account.retired { background: #f6f8f5; }
+  .account.retired > a, .account.retired > strong { color: #6b786f; }
+  .account.retired .mark { opacity: .45; }
+  .group { margin: 20px 0 0; color: #6b786f; font-size: 11px; font-weight: 550; }
   .additional { margin-top: 2px; padding-left: 12px; }
   .joiner { display: block; width: 20px; height: 20px; margin: 8px auto -4px; color: #90a096; }
   dl { margin: 16px 0 0; padding-top: 12px; border-top: 1px solid #e5e9e3; display: grid; grid-template-columns: auto 1fr; gap: 5px 16px; font-size: 11px; }
@@ -48,9 +62,10 @@ export const styles = `
   .action:disabled { opacity: .6; cursor: progress; }
   .action.danger:hover { border-color: #b3261e; background: #fdecea; color: #b3261e; }
   .row { display: flex; justify-content: end; gap: 8px; margin-top: 16px; }
-  .account .row { align-items: center; justify-content: start; margin-top: 12px; }
+  .account .row { align-items: center; justify-content: start; flex-wrap: wrap; margin-top: 12px; }
   .account .action { padding: 5px 10px; font-size: 12px; }
-  footer { display: flex; align-items: center; justify-content: start; gap: 6px; margin-top: 14px; color: #9aa9a0; font-size: 11px; }
+  footer { display: flex; align-items: center; justify-content: start; gap: 6px; margin: 20px 0 -8px; color: #9aa9a0; font-size: 11px; }
+  footer a { display: flex; color: inherit; }
   .logo { display: block; height: 13px; }
   ${markStyles}
 `;
@@ -138,6 +153,8 @@ export function accountCard(heading, name, reference, url, ...extra) {
     card.append(...extra);
     return card;
 }
+/** What the holder is told before an account is retired, since it cannot be undone from here. */
+const retiringNote = 'Retiring keeps this record as history. It will no longer read as verified, and who can read it cannot be changed afterwards.';
 /**
  * The links removing an account would remove. The record shown may itself be revoked while
  * older ones of the account are not, and those must stay removable, so this is not read
@@ -147,6 +164,9 @@ const removable = (evidence) => evidence.links ?? (evidence.status === 'revoked'
 /**
  * Under a holder's own account: renewing it, which is showing the same account again, and
  * removing it, which asks once more before it does. A removed link has nothing left to do.
+ *
+ * An account still in use can also be listed another way, or retired, which asks first as
+ * removing does. A retired one is renewed or removed and nothing else.
  */
 function manageRow(evidence, manage) {
     const row = node('div', '', 'row');
@@ -155,12 +175,49 @@ function manageRow(evidence, manage) {
         control.type = 'button';
         return control;
     };
+    const [named] = removable(evidence);
+    const { mark } = manage;
+    // A mark is the account's, set through any one of its links that still stands.
+    const listable = mark !== undefined && named !== undefined && !['revoked', 'retired'].includes(evidence.status);
+    /** A control that lists the account one way, and says so if that did not go through. */
+    const list = (label, as) => {
+        const control = act(label);
+        control.onclick = async () => {
+            for (const other of row.children)
+                other.disabled = true;
+            try {
+                await mark(named, as);
+            }
+            catch {
+                offer('That did not go through.');
+            }
+        };
+        return control;
+    };
     const offer = (note = '') => {
         const renew = act('Renew');
         const remove = act('Remove', true);
-        renew.onclick = () => manage.connect(evidence.provider);
+        // The record the card is drawn from is the one renewed. A retired one comes back by the
+        // method it was first shown by alone, and a removed one cannot be renewed at all, so
+        // the account behind it is connected again.
+        renew.onclick = () => manage.renew && evidence.status !== 'revoked'
+            ? manage.renew(evidence.id, evidence.provider, evidence.status === 'retired' ? evidence.attestations.external[0].method : undefined)
+            : manage.connect(evidence.provider);
         remove.onclick = confirm;
-        row.replaceChildren(renew, remove, ...(note ? [node('span', note, 'muted')] : []));
+        const listing = [];
+        if (listable) {
+            const retire = act('Retire');
+            retire.onclick = retiring;
+            listing.push(...(evidence.mark === 'preferred' ? [] : [list('Mark as preferred', 'preferred')]), ...(evidence.mark === 'unused' ? [] : [list('Mark as unused', 'unused')]), ...(evidence.mark === undefined ? [] : [list('Mark as current', 'current')]), retire);
+        }
+        row.replaceChildren(renew, ...listing, remove, ...(note ? [node('span', note, 'muted')] : []));
+    };
+    const retiring = () => {
+        const cancel = act('Cancel');
+        const sure = list('Retire', 'retired');
+        cancel.onclick = () => offer();
+        row.replaceChildren(node('span', retiringNote, 'muted'), cancel, sure);
+        cancel.focus();
     };
     const confirm = () => {
         const cancel = act('Cancel');
@@ -290,13 +347,22 @@ function externalCard(evidence, manage, later = () => { }) {
     if (evidence.signedUrl)
         attribution.append(signedMark(evidence, later));
     copy.append(node('div', status, 'state'), attribution);
-    summary.append(verificationMark(current ? 'current' : 'inactive'), copy);
+    const retired = evidence.status === 'retired';
+    // A retired account claims nothing now, which is not the same as a claim that failed.
+    summary.append(verificationMark(current ? 'current' : retired ? 'pending' : 'inactive'), copy);
     const dates = node('dl');
     const dateRows = [['Approved', evidence.approvedAt]];
     if (evidence.status === 'revoked') {
         if (evidence.revokedAt !== undefined)
             dateRows.push(['Revoked on', evidence.revokedAt]);
     }
+    else if (retired) {
+        // 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.
+        dateRows.push(['Last verified', lastProved(evidence)]);
+        if (evidence.retiredAt !== undefined)
+            dateRows.push(['Retired', evidence.retiredAt]);
+    }
     else {
         // A proof that has gone unread has not reached its expiry, so it still reads forward.
         dateRows.push([
@@ -307,7 +373,7 @@ function externalCard(evidence, manage, later = () => { }) {
     // When an artifact was last read belongs with the other times, not inside a sentence.
     // Only artifact methods drift: a sign-in is established once and does not go stale.
     const main = evidence.attestations.external[0];
-    if (main.artifactUrl)
+    if (main.artifactUrl && !retired)
         dateRows.push(['Last checked', main.confirmedAt]);
     for (const [label, time] of dateRows) {
         dates.append(node('dt', label), node('dd', moment(time)));
@@ -322,7 +388,18 @@ function externalCard(evidence, manage, later = () => { }) {
     evidence.external.kind === 'mailbox' ? undefined : evidence.external.id, externalLink(evidence.external), 
     // Status first, then how it was shown, then when. The proof explains the state
     // above it, so it cannot sit before that state has been given.
-    summary, ...attestationNote(main, names), ...evidence.attestations.external.slice(1).flatMap((a) => attestationNote(a, names, true)), dates, ...(manage && removable(evidence).length ? [manageRow(evidence, manage)] : []));
+    summary, ...attestationNote(main, names), ...evidence.attestations.external.slice(1).flatMap((a) => attestationNote(a, names, true)), 
+    // How the holder lists the account, in their words and apart from how it was shown:
+    // nothing checked it, so it is never among the methods above it.
+    ...(evidence.status === 'revoked' || retired
+        ? []
+        : evidence.mark === 'preferred'
+            ? [node('div', 'Preferred', 'listing preferred')]
+            : evidence.mark === 'unused'
+                ? [node('div', 'No longer used', 'listing')]
+                : []), dates, ...(manage && removable(evidence).length ? [manageRow(evidence, manage)] : []));
+    const surface = retired ? 'account retired' : 'account';
+    card.className = surface;
     // A signed record is not read, or acted on, before its signature has been checked: until
     // the check comes back the whole card is veiled and out of reach, with a word over it
     // saying why. A record handed over altered is then never read as it was handed over.
@@ -331,12 +408,12 @@ function externalCard(evidence, manage, later = () => { }) {
         const checking = node('div', '', 'checking');
         checking.setAttribute('role', 'status');
         checking.append(node('span', '', 'spinner'), document.createTextNode('Checking signature…'));
-        card.className = 'account veiled';
+        card.className = `${surface} veiled`;
         for (const part of veiled)
             part.inert = true;
         card.append(checking);
         void signatures(evidence).then(() => {
-            card.className = 'account';
+            card.className = surface;
             for (const part of veiled)
                 part.inert = false;
             checking.remove();
@@ -354,8 +431,9 @@ function addRow(manage) {
     return row;
 }
 /**
- * The subject once, then each account linked to it on its own card, in the order they
- * were connected. Every record given is of the one subject, which the caller has checked.
+ * The subject once, then each account linked to it on its own card, in the order given.
+ * Retired accounts sit in a group of their own at the foot, under what says they are.
+ * Every record given is of the one subject, which the caller has checked.
  */
 function render(content, records, manage, later) {
     const [first] = records;
@@ -369,7 +447,15 @@ function render(content, records, manage, later) {
         site: first.siteName,
         provider: first.providerName,
     }));
-    content.replaceChildren(localCard, linkMark(), ...records.map((record) => externalCard(record, manage, later)), ...(manage ? [addRow(manage)] : []), 
+    const retired = records.filter((record) => record.status === 'retired');
+    content.replaceChildren(localCard, linkMark(), ...records
+        .filter((record) => record.status !== 'retired')
+        .map((record) => externalCard(record, manage, later)), ...(manage ? [addRow(manage)] : []), ...(retired.length
+        ? [
+            node('h3', 'Retired accounts', 'group'),
+            ...retired.map((record) => externalCard(record, manage, later)),
+        ]
+        : []), 
     // Nothing below the cards may name a provider. Approval, method and dates belong to
     // the card they came from, and a second provider on this subject gets its own card.
     node('p', 'Verification does not guarantee legal identity, trustworthiness, or permanent ownership.', 'muted explanation'));
@@ -415,12 +501,44 @@ manage) {
     close.type = 'button';
     close.setAttribute('aria-label', 'Close verification details');
     content.setAttribute('aria-live', 'polite');
-    stamp.append(verilyLogo(), node('span', version));
+    stamp.append(stampLink(), node('span', version));
     header.append(heading, close);
     dialog.append(header, content, stamp);
     /** Links removed from this dialog, shown as removed before the page hands over new records. */
     const removed = new Map();
+    /**
+     * How accounts were listed from this dialog, in the order it was asked, shown as asked
+     * before the page hands over new records: each names every link of its account, and
+     * holds how those links read when it was asked. Once any of them reads differently the
+     * backend has spoken, for this change or a later one made elsewhere, and what it says
+     * is shown from then on.
+     */
+    const listed = [];
+    /** What of a record a listing, a retirement or a renewal changes. */
+    const listing = (record) => JSON.stringify([record.status, record.mark, record.retiredAt, record.approvedAt]);
+    /** How each record given reads now, by its id. */
+    const listings = (given) => new Map([given].flat().map((record) => [record.id, listing(record)]));
     let held;
+    /** A record as the listings made here leave it, each applied as the backend applies it. */
+    const relisted = (evidence) => {
+        let record = evidence;
+        for (const { ids, as, at } of listed) {
+            if (['revoked', 'retired'].includes(record.status))
+                break;
+            if (!ids.includes(record.id)) {
+                // One preferred account for a holder: picking another moves the mark.
+                if (as === 'preferred' && record.mark === 'preferred')
+                    record = { ...record, mark: undefined };
+                continue;
+            }
+            record =
+                as === 'retired'
+                    ? // Its signed form is another document now, to be read with the records to come.
+                        { ...record, status: 'retired', retiredAt: at, mark: undefined, signedUrl: undefined }
+                    : { ...record, mark: as === 'current' ? undefined : as };
+        }
+        return record;
+    };
     const actions = manage && {
         // The other dialog opens over this one before this one goes, so the page behind is
         // never uncovered between the two.
@@ -428,6 +546,14 @@ manage) {
             manage.connect(provider);
             dialog.close();
         },
+        ...(manage.renew
+            ? {
+                renew(id, provider, method) {
+                    manage.renew(id, provider, method);
+                    dialog.close();
+                },
+            }
+            : {}),
         async remove(ids) {
             await manage.remove(ids);
             for (const id of ids)
@@ -435,6 +561,23 @@ manage) {
             if (held && dialog.open)
                 draw(held);
         },
+        ...(manage.mark
+            ? {
+                async mark(id, as) {
+                    await manage.mark(id, as);
+                    // Every link of the account the one named belongs to, as the cards group them.
+                    const account = arrange([held ?? []].flat()).find((card) => removable(card).includes(id));
+                    listed.push({
+                        ids: account ? removable(account) : [id],
+                        as,
+                        at: Date.now(),
+                        before: listings(held ?? []),
+                    });
+                    if (held && dialog.open)
+                        draw(held);
+                },
+            }
+            : {}),
     };
     root.append(dialog);
     document.body.append(host);
@@ -447,11 +590,15 @@ manage) {
     /** Redraws only for a record that reads differently from the one already on screen. */
     const draw = (given) => {
         held = given;
+        const now = listings(given);
+        for (const change of [...listed])
+            if (change.ids.some((id) => now.get(id) !== change.before.get(id)))
+                listed.splice(listed.indexOf(change), 1);
         const records = arrange([given]
             .flat()
             .map((e) => removed.has(e.id) && e.status !== 'revoked'
             ? { ...e, status: 'revoked', revokedAt: removed.get(e.id) }
-            : standing(e)));
+            : relisted(standing(e))));
         const key = JSON.stringify(records.map((e) => [e, statusLabel(e, Date.now())]));
         if (key === drawn)
             return;