@bkazemi/verily 0.5.0 → 0.7.0

package/dist/server/index.js

@@ -1,4 +1,4 @@
-import { attestationLabel, externalId, externalLink, externalName, isArtifactProvider, isCodeProvider, isRedirectProvider, lastProved, localSide, proofTitle, providerMethod, statusLabel, signedBy, } from '../core/index.js';
+import { attestationLabel, externalId, externalIdGroups, externalLink, externalName, externalSince, isArtifactProvider, isCodeProvider, isRedirectProvider, lastProved, accountsOf, 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';
@@ -84,8 +84,24 @@ const redirect = (url, cookie) => new Response(null, {
  * Both sides render as the same card, so the pair reads as a pair.
  */
 function card(heading, name, url, reference, ...extra) {
+    return side(heading, name, url, reference, undefined, extra);
+}
+/**
+ * The card for an external account: its name, link and id, with the "Joined <date>" text
+ * on the name's line when the creation date is known.
+ */
+function externalCard(heading, external, ...extra) {
+    return side(heading, externalName(external), externalLink(external), 
+    // A mailbox's address or a domain is its name already, so there is no second identifier.
+    externalIdGroups(external) ?? externalId(external), externalSince(external, (time) => new Date(time).toISOString().slice(0, 10)), extra);
+}
+function side(heading, name, url, reference, since, extra) {
     const profile = url && safeUrl(url);
-    return `<div class="side"><p class="who">${escape(heading)}</p><p class="name">${profile ? `<a href="${escape(profile)}" rel="noreferrer">${escape(name)}</a>` : escape(name)}</p>${reference ? `<p class="reference">${escape(reference)}</p>` : ''}${extra.join('')}</div>`;
+    return `<div class="side"><p class="who">${escape(heading)}</p><p class="name">${profile ? `<a href="${escape(profile)}" rel="noreferrer">${escape(name)}</a>` : escape(name)}${since ? `<span class="since">${escape(since)}</span>` : ''}</p>${typeof reference === 'string'
+        ? `<p class="reference">${escape(reference)}</p>`
+        : reference
+            ? `<p class="reference fingerprint">${reference.map((group) => `<span>${escape(group)}</span>`).join('')}</p>`
+            : ''}${extra.join('')}</div>`;
 }
 /**
  * Names how one side was established, inside that side's card. Where the method published
@@ -224,6 +240,17 @@ function times(rows) {
         .map(([label, time]) => `<dt>${escape(label)}</dt><dd>${escape(moment(time))}</dd>`)
         .join('')}</dl>`;
 }
+/** Provider setup with the flow’s return instructions, shared by HTML and the dialog. */
+function proofInstructions(provider, flow) {
+    return [
+        ...provider.instructions(flow.expect, flow.artifact ?? flow.suggested),
+        ...(flow.dnsDraftId
+            ? [
+                'Your DNS setup is saved for seven days from when you started. To continue later, sign in and choose the DNS method again. For a renewal, reopen the same connection’s renewal. The proof must pass a fresh check; keep this TXT value while you wait.',
+            ]
+            : []),
+    ];
+}
 /**
  * What the holder is told, as the provider wrote it. A command is set as a block and never
  * reflowed: it is copied character for character, and one wrapped line is a broken command.
@@ -293,9 +320,7 @@ function evidencePage(e, base, report, keyId, named) {
     // site's own reference would be a third line saying the same thing. The provider's
     // 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 or a domain is its name already, so there is no second identifier.
-        externalId(e.external), externalNotes(e.attestations, names)) +
+        externalCard(names.provider, e.external, externalNotes(e.attestations, names)) +
         times(e.status === 'retired'
             ? [
                 ['Approved', e.approvedAt],
@@ -329,6 +354,66 @@ function evidencePage(e, base, report, keyId, named) {
     ${e.visibility === 'unlisted' ? `<p class="fine"><a href="${escape(base)}/external-share-revoke/${escape(e.id)}">Revoke only this sharing link using your external account</a></p>` : ''}
     <p class="fine"><a href="${escape(report)}" rel="noreferrer">Report an incorrect record</a></p>`);
 }
+/** Joins a subject's card to its accounts: the link itself, drawn as the dialog draws it. */
+const joiner = '<svg class="joiner" viewBox="0 0 24 24" fill="none" aria-hidden="true" focusable="false">' +
+    [
+        'M10.5 7.5 13 5a4.95 4.95 0 0 1 7 7l-2.5 2.5',
+        'M13.5 16.5 11 19a4.95 4.95 0 0 1-7-7l2.5-2.5',
+        'M9 15l6-6',
+    ]
+        .map((d) => `<path d="${d}" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>`)
+        .join('') +
+    '</svg>';
+/**
+ * One account as a badge's dialog draws it: what it is and how it stands, the verifier's
+ * own page for it, how it was shown, how its holder lists it, and its times.
+ */
+function accountCard(e, external, now) {
+    const retired = e.status === 'retired';
+    const record = escape(safeUrl(e.evidenceUrl));
+    return externalCard(e.providerName, e.external, `<p class="how">${escape(statusLabel(e, now))} · via: <a href="${record}">${escape(e.verifierName)}</a>${e.signedUrl ? `<a class="signed-mark" href="${record}#signed">signed</a>` : ''}</p>`, externalNotes({ ...e.attestations, external }, { site: e.siteName, provider: e.providerName }), times(retired
+        ? [
+            ['Approved', e.approvedAt],
+            ['Last verified', lastProved(e)],
+            ['Retired', e.retiredAt],
+        ]
+        : [
+            ['Approved', e.approvedAt],
+            [e.expiresAt > now ? 'Valid until' : 'Expired on', e.expiresAt],
+            ['Last checked', external[0].artifactUrl ? external[0].confirmedAt : undefined],
+        ]), 
+    // The holder's own word on the account, which nothing checked, so it sits apart from
+    // the methods, in the card's corner as the dialog has it.
+    retired || !e.mark
+        ? ''
+        : e.mark === 'preferred'
+            ? '<div class="listing preferred">Preferred</div>'
+            : '<div class="listing">No longer used</div>');
+}
+/**
+ * The public records given, as a page that shows what a badge's dialog does: a card to a
+ * subject, then one to each of its accounts in the badge's own order.
+ */
+function publishedPage(records, base) {
+    const now = Date.now();
+    const subjects = new Map();
+    for (const e of records) {
+        const key = JSON.stringify([e.siteName, e.local.reference]);
+        subjects.set(key, [...(subjects.get(key) ?? []), e]);
+    }
+    return page(base, 'Public connections', records.length
+        ? [...subjects.values()]
+            .map((held) => {
+            const local = localSide(held[0].local, held[0].siteName);
+            return (card(local.heading, local.value, held[0].local.profileUrl) +
+                joiner +
+                `<div class="accounts">${accountsOf(held, now)
+                    .map(({ lead, external }) => accountCard(lead, external, now))
+                    .join('')}</div>`);
+        })
+            .join('')
+        : '<p>No public connections.</p>');
+}
 /**
  * Names a signing key on one line: its last sixteen digits, linked to the key itself with
  * the whole fingerprint on hover, then whether a domain's DNS was read naming it. That is a
@@ -355,7 +440,7 @@ function checkedPage(d, keyId, base, named) {
     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), externalId(d.external), externalNotes(d.attestations, names)) +
+        externalCard(names.provider, d.external, externalNotes(d.attestations, names)) +
         times(retired
             ? [
                 ['Signed', d.issuedAt],
@@ -538,7 +623,7 @@ export function createVerily(options) {
             view.authorizationUrl = authorizationUrl;
         if (flow.phase === 'pending' && flow.expect && isArtifactProvider(provider))
             Object.assign(view, {
-                instructions: provider.instructions(flow.expect),
+                instructions: proofInstructions(provider, flow),
                 artifact: provider.artifact,
                 field: artifactField(provider),
                 input: provider.input ?? 'url',
@@ -644,6 +729,8 @@ export function createVerily(options) {
                     // With one visibility there is nothing for the holder to change it to.
                     if (kind === 'visibility' && visibilities(user).length < 2)
                         throw new Unavailable();
+                    // Several providers are named by their buttons, not strung together in the heading.
+                    const several = new Set(offered.map((p) => p.name)).size > 1;
                     // One form per method. With one on offer the provider is all there is to name.
                     // A new link started from this page always ends on its approval, as it did when
                     // this form was a GET, so it says so: `/verify` is an address any site can send a
@@ -655,7 +742,9 @@ export function createVerily(options) {
                         ? 'Remove a connection'
                         : kind === 'renew'
                             ? 'Renew this connection'
-                            : `Verify with ${providerNames(offered)}`, `
+                            : several
+                                ? 'Verify an account'
+                                : `Verify with ${providerNames(offered)}`, `
             ${user
                         ? card(subject(user).heading, subject(user).value, user.profileUrl)
                         : '<p>Authenticate with the matching external account to review and remove this link.</p>'}
@@ -698,7 +787,7 @@ export function createVerily(options) {
                         if (!['revoke', 'share-revoke'].includes(flow.kind))
                             if ((await local(request)).id !== flow.local?.id)
                                 throw new Unavailable();
-                        return html(page(prefix, `Verify with ${provider.name}`, `${instructions(provider.instructions(flow.expect))}
+                        return html(page(prefix, `Verify with ${provider.name}`, `${instructions(proofInstructions(provider, flow))}
             ${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'
@@ -744,7 +833,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), externalId(flow.external))}
+            ${externalCard(provider.name, 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>
@@ -782,7 +871,15 @@ export function createVerily(options) {
                 }
                 // Lets a static embed track current connections without hardcoding an id.
                 if (path === '/published') {
-                    const response = json(await service.published());
+                    const site = url.searchParams.get('site');
+                    const reference = url.searchParams.get('reference') ?? undefined;
+                    const subject = site === null ? undefined : { site, reference };
+                    // A page only where one is asked for by name. An embed published before `Accept`
+                    // was sent asks for nothing, and must go on getting the list.
+                    if (url.searchParams.get('format') !== 'json' &&
+                        /\btext\/html\b/i.test(request.headers.get('accept') ?? ''))
+                        return html(publishedPage(await service.listed(subject), prefix));
+                    const response = json(await service.published(subject));
                     response.headers.set('Access-Control-Allow-Origin', '*');
                     return response;
                 }

package/dist/server/link.js

@@ -1,8 +1,8 @@
 import { legacyHookDecode } from '@exodus/bytes/encoding.js';
 import htmlEncodingSniffer from 'html-encoding-sniffer';
-import { MIMEType } from 'node:util';
+import { isDeepStrictEqual, MIMEType } from 'node:util';
 import { html, parse } from 'parse5';
-import { Refused, } from '../core/index.js';
+import { Absent, Refused, } from '../core/index.js';
 import { discard, readBounded } from './body.js';
 import { transport } from './public-fetch.js';
 /**
@@ -99,6 +99,9 @@ async function backlinked(response, page, subject, maxBytes) {
     // The holder named this address, so a redirect would take the check somewhere else.
     if (response.type === 'opaqueredirect' || (response.status >= 300 && response.status < 400))
         throw new Refused('Page redirects, and a redirect is not followed');
+    // The page is gone. Any other failure is a failed read.
+    if (response.status === 404 || response.status === 410)
+        throw new Absent('Page unavailable');
     if (!response.ok)
         throw new Refused('Page unavailable');
     // A link relation is a link relation wherever it is declared, and a page with no
@@ -132,7 +135,9 @@ async function backlinked(response, page, subject, maxBytes) {
             return;
     }
     // 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');
+    if (truncated)
+        throw new Refused('Page is too large to read');
+    throw new Absent('Page has no rel="me" link to this subject');
 }
 /**
  * The address the holder handed back, once it is one this may fetch. They choose it, so
@@ -259,7 +264,7 @@ function points(href, base, subject) {
     for (const key of new Set(subject.searchParams.keys())) {
         const wanted = subject.searchParams.getAll(key);
         const found = target.searchParams.getAll(key);
-        if (found.length !== wanted.length || found.some((value, at) => value !== wanted[at]))
+        if (!isDeepStrictEqual(found, wanted))
             return false;
     }
     return true;

package/dist/server/openpgp.d.ts

@@ -10,6 +10,10 @@ import { Refused } from '../core/index.js';
 export declare class Malformed extends Refused {
     constructor(what: string, options?: ErrorOptions);
 }
+/** The block is not there at all: a holder who pasted half is told which half is missing. */
+export declare class Missing extends Malformed {
+    constructor(what: string);
+}
 export type Certificate = Key;
 export type Cleartext = CleartextMessage;
 /** The public key in armored text, wherever in the text its block is. */

package/dist/server/openpgp.js

@@ -34,6 +34,13 @@ export class Malformed extends Refused {
         super(`Malformed OpenPGP ${what}`, options);
     }
 }
+/** The block is not there at all: a holder who pasted half is told which half is missing. */
+export class Missing extends Malformed {
+    constructor(what) {
+        super(what);
+        this.message = `No OpenPGP ${what} found`;
+    }
+}
 /**
  * The one armored block of the named kind out of text that may hold others: a holder
  * pastes the signed message and the key together, and the library reads only the first
@@ -43,8 +50,10 @@ function block(text, begin, end, what) {
     if (text.length > maxArmorBytes)
         throw new Malformed(what);
     const start = text.indexOf(`-----BEGIN PGP ${begin}-----`);
+    if (start < 0)
+        throw new Missing(what);
     const stop = text.indexOf(`-----END PGP ${end}-----`, start);
-    if (start < 0 || stop < 0)
+    if (stop < 0)
         throw new Malformed(what);
     return text.slice(start, stop + `-----END PGP ${end}-----`.length);
 }

package/dist/server/service.d.ts

@@ -1,7 +1,15 @@
-import { type Attestations, type Connection, type Evidence, type ExternalAccount, type Flow, type LocalAccount, type Mark, type Provider, type SignedDocument, type SignedEvidence, type Storage, type VerifierKey, type Visibility } from '../core/index.js';
+import { type Change, type Attestations, type Connection, type Evidence, type ExternalAccount, type Flow, type LocalAccount, type Mark, type Provider, type SignedDocument, type SignedEvidence, type Storage, type VerifierKey, type Visibility } from '../core/index.js';
 import { type DnsOptions, type Published } from './domain.js';
 export declare const secret: () => string;
 export declare const hash: (value: string) => string;
+/**
+ * A subject as its public records name it: the site it belongs to and its reference there.
+ * A reference means nothing outside its site, so with none this is everyone on the site.
+ */
+export interface Subject {
+    site: string;
+    reference?: string;
+}
 export declare class Unavailable extends Error {
     constructor();
 }
@@ -57,6 +65,18 @@ export interface ServiceOptions {
      * is on the site's domain or a subdomain of it. Unset reads nothing.
      */
     dns?: boolean | DnsOptions;
+    /**
+     * Called when a record's status, visibility, expiry or mark changes, with the record as
+     * it stands now. Changes made by a request are delivered before that request returns.
+     * Expiry and a proof going unconfirmed happen with time alone, so those are delivered by
+     * `recheck()` or `announce()`.
+     *
+     * Delivery is at least once: a call that throws, or takes longer than `recheckTimeoutMs`,
+     * is retried on the next `recheck()` or `announce()`. A call that timed out is not
+     * cancelled and may finish after a newer one, so apply a change only if its `revision`
+     * is higher than the last one applied for that record.
+     */
+    onChange?: (change: Change) => void | Promise<void>;
     now?: () => number;
 }
 export declare class VerilyService {
@@ -288,6 +308,37 @@ export declare class VerilyService {
     private ended;
     /** Every read of a connection goes through here, so a record in an older shape is upgraded. */
     private transaction;
+    /** The parts of a record that `onChange` reports, as they are at `now`. */
+    private reportable;
+    /**
+     * Delivers every record whose state differs from the one last reported to `onChange`,
+     * up to `budget` records. `ids` limits it to those records. Returns how many were
+     * delivered. Does nothing without `onChange`.
+     *
+     * Records whose last delivery failed are tried after the others, oldest attempt first,
+     * so a record that keeps failing does not hold up the rest.
+     */
+    announce(ids?: string[], budget?: number): Promise<number>;
+    /** A storage transaction whose writes are not themselves announced. */
+    private unreported;
+    /** The last delivery started. Each delivery waits for the one before it. */
+    private delivering;
+    /**
+     * Whether a record still has something to deliver: its state differs from the one last
+     * reported, or its last delivery started and was never confirmed. An unconfirmed
+     * delivery may have reached the receiver, so it is sent again even if the state has
+     * since gone back to the one reported.
+     */
+    private unsettled;
+    /**
+     * Delivers one record to `onChange` if it has something to deliver. Returns 1 if the
+     * delivery was confirmed.
+     *
+     * Each delivery reads the record and takes the next revision in one storage
+     * transaction, so a higher revision always carries a later state, whichever process or
+     * callback finishes first. Within this process deliveries also run one at a time.
+     */
+    private deliver;
     /**
      * The methods a reader is shown. An additional method whose proof has gone unread no
      * longer shows anything, so it is left out until it reads again; the main one is
@@ -345,7 +396,13 @@ export declare class VerilyService {
      * hardcoding an id that dies whenever one is revoked and replaced. Unlisted records are
      * never included: they must not appear in any directory listing.
      */
-    published(): Promise<Evidence[]>;
+    published(subject?: Subject): Promise<Evidence[]>;
+    /**
+     * Every public record a badge could show, for the page a person reads: one that has lapsed
+     * or been retired is there to be marked, and one removed is not. `subject` narrows it to
+     * one site or one subject, named by what its records already publish. Earliest connected first.
+     */
+    listed(subject?: Subject): Promise<Evidence[]>;
     /**
      * Every record this instance holds, public and unlisted, for whoever runs it. No route
      * of the library serves this: a deployment that shows it must first know the reader is