@bkazemi/verily 0.6.0 → 0.7.0

package/dist/server/github-gist.js

@@ -1,4 +1,4 @@
-import { Refused } from '../core/index.js';
+import { Absent, Refused } from '../core/index.js';
 /**
  * Proves control of a GitHub account by having its holder publish a given line in a public
  * gist. No app registration, no client secret, and no token: the proof is a public document
@@ -34,11 +34,14 @@ export function githubGistProvider(options = {}) {
                 signal: AbortSignal.timeout(15000),
             });
             const gist = await response.json();
+            // GitHub answers 404 for a gist that was deleted. Any other failure is a failed read.
+            if (response.status === 404)
+                throw new Absent('Gist unavailable');
             if (!response.ok || !isRecord(gist))
                 throw new Refused('Gist unavailable');
             // A secret gist proves nothing a reader could check for themselves.
             if (gist.public !== true)
-                throw new Refused('Gist is not public');
+                throw new Absent('Gist is not public');
             const owner = gist.owner;
             if (!isRecord(owner) ||
                 !Number.isSafeInteger(owner.id) ||
@@ -46,8 +49,13 @@ export function githubGistProvider(options = {}) {
                 typeof owner.login !== 'string' ||
                 !/^[a-zA-Z0-9-]+$/.test(owner.login))
                 throw new Refused('Invalid gist owner');
-            if (!isRecord(gist.files) || !contains(gist.files, expect))
-                throw new Refused('Gist does not contain the expected line');
+            if (!isRecord(gist.files) || !contains(gist.files, expect)) {
+                // Part of the gist was left out of the answer, and the line may be in that part.
+                // That is a failed read, so the proof keeps counting.
+                if (!isRecord(gist.files) || gist.truncated === true || partial(gist.files))
+                    throw new Refused('Gist is too large to read');
+                throw new Absent('Gist does not contain the expected line');
+            }
             return {
                 id: String(owner.id),
                 handle: owner.login,
@@ -63,6 +71,10 @@ function contains(files, expect) {
         typeof file.content === 'string' &&
         file.content.includes(expect));
 }
+/** Whether any file came back cut short or without its content. */
+function partial(files) {
+    return Object.values(files).some((file) => !isRecord(file) || file.truncated === true || typeof file.content !== 'string');
+}
 function isRecord(value) {
     return value !== null && typeof value === 'object';
 }

package/dist/server/github.js

@@ -54,10 +54,13 @@ export function githubProvider(options) {
                 typeof user.login !== 'string' ||
                 !/^[a-zA-Z0-9-]+$/.test(user.login))
                 throw new Error('Invalid provider identity');
+            // Optional: a missing or unparseable date is left off and the sign-in still succeeds.
+            const createdAt = typeof user.created_at === 'string' ? Date.parse(user.created_at) : NaN;
             return {
                 id: String(user.id),
                 handle: user.login,
                 profileUrl: `https://github.com/${user.login}`,
+                ...(Number.isFinite(createdAt) ? { createdAt } : {}),
             };
         },
     };

package/dist/server/index.js

@@ -1,4 +1,4 @@
-import { attestationLabel, externalId, externalIdGroups, externalLink, externalName, isArtifactProvider, isCodeProvider, isRedirectProvider, lastProved, accountsOf, 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,20 @@ 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>${typeof reference === 'string'
+    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>`
@@ -228,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.
@@ -297,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.
-        externalIdGroups(e.external) ?? externalId(e.external), externalNotes(e.attestations, names)) +
+        externalCard(names.provider, e.external, externalNotes(e.attestations, names)) +
         times(e.status === 'retired'
             ? [
                 ['Approved', e.approvedAt],
@@ -350,7 +371,7 @@ const joiner = '<svg class="joiner" viewBox="0 0 24 24" fill="none" aria-hidden=
 function accountCard(e, external, now) {
     const retired = e.status === 'retired';
     const record = escape(safeUrl(e.evidenceUrl));
-    return card(e.providerName, externalName(e.external), externalLink(e.external), externalIdGroups(e.external) ?? externalId(e.external), `<p class="how">${escape(statusLabel(e, now))} · via: <a href="${record}">${escape(e.verifierName)}</a>${e.signedUrl ? ` · <a href="${record}#signed">signed</a>` : ''}</p>`, externalNotes({ ...e.attestations, external }, { site: e.siteName, provider: e.providerName }), times(retired
+    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)],
@@ -419,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), externalIdGroups(d.external) ?? externalId(d.external), externalNotes(d.attestations, names)) +
+        externalCard(names.provider, d.external, externalNotes(d.attestations, names)) +
         times(retired
             ? [
                 ['Signed', d.issuedAt],
@@ -602,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',
@@ -766,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'
@@ -812,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), externalIdGroups(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>

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/service.d.ts

@@ -1,4 +1,4 @@
-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;
@@ -65,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 {
@@ -296,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