@bkazemi/verily 0.1.0 → 0.3.0

package/dist/core/index.d.ts

@@ -2,9 +2,16 @@ export type Visibility = 'public' | 'unlisted';
 /**
  * `unconfirmed` is a published proof that has not been read lately. It is not disproved,
  * and turns back to `verified` the moment the proof reads again. `expired` is an approval
- * that ran out, which only the holder renewing it undoes.
+ * that ran out, which only the holder renewing it undoes. `retired` is an account its
+ * holder said is finished: the record is kept as it stood at its last proof and never
+ * reads as verified again, unless that proof is made afresh.
  */
-export type Status = 'verified' | 'unconfirmed' | 'expired' | 'revoked';
+export type Status = 'verified' | 'unconfirmed' | 'expired' | 'retired' | 'revoked';
+/**
+ * How the holder would have an account listed: the one to lead with, or one they still
+ * control and no longer use. The holder's own statement, and no part of what was verified.
+ */
+export type Mark = 'preferred' | 'unused';
 /** What a site links: one of its accounts, a single page, or the site itself. */
 export type LocalKind = 'account' | 'page' | 'site';
 /** id is private and must never be reassigned. reference is durable and public-safe. */
@@ -106,6 +113,13 @@ export interface Connection {
     attestations?: Attestations;
     /** The proof itself, for a method whose artifact this backend publishes rather than reads. */
     proof?: string;
+    /** Set and cleared by the holder. Absent is an ordinary current account. */
+    mark?: Mark;
+    /**
+     * When the holder said the account is finished. From then the record is frozen at its
+     * last proof: never renewed by another method, never reread, never verified.
+     */
+    retiredAt?: number;
 }
 export interface Flow {
     id: string;
@@ -127,8 +141,30 @@ export interface Flow {
      * unguessable and per-flow, so an artifact made for one flow cannot complete another.
      */
     expect?: string;
-    /** What the holder handed back: an address to read, or the proof itself. */
+    /**
+     * What the holder handed back: an address to read, or the proof itself. On a flow still
+     * waiting it is what they last handed back and had refused, kept so they can put it right.
+     */
     artifact?: string;
+    /** How many times what the holder handed back has been refused. */
+    tries?: number;
+    /**
+     * Whether the flow was started by a request shown to come from the holder's own page,
+     * and not by an address anyone could have sent their browser to. Only such a flow may
+     * be recorded without an approval, which is otherwise the one step a link cannot press.
+     */
+    attended?: boolean;
+    /**
+     * What the holder is offered to hand back, where a record of theirs already names the
+     * account. Only an offer: what is verified is whatever they then submit.
+     */
+    suggested?: string;
+    /**
+     * Proofs found already standing when another method named the account, such as a link
+     * back on the profile of an account that just signed in. Recorded with the method that
+     * found them once the holder approves.
+     */
+    standing?: Attestation[];
     /**
      * A message on its way to the address the holder named, carrying a link to press and a
      * code to type. The account is only a claim until one of them comes back, which is why
@@ -224,6 +260,11 @@ export interface RedirectProvider {
         state: string;
         challenge: string;
         redirectUri: string;
+        /**
+         * The account the flow must show, on a flow the holder of its record started. There is
+         * no account to choose then, so the provider need not be made to offer the choice.
+         */
+        account?: ExternalAccount;
     }): string;
     authenticate(input: {
         code: string;
@@ -261,6 +302,25 @@ export interface ArtifactProvider {
      * character, and prose that reflows is prose a holder cannot safely copy.
      */
     instructions(expect: string): Instruction[];
+    /**
+     * What the holder is asked to hand back, where the method takes something a holder knows
+     * by a better name than "an address". `input` says how to ask for it: `text` where it
+     * need not be an address at all, such as a username.
+     */
+    field?: string;
+    input?: 'url' | 'text';
+    /**
+     * Turns what the holder typed into the address to read, for a method that takes something
+     * shorter. What it returns is what is verified and kept as the proof's location, so it
+     * must be the whole address. Anything it does not recognise is returned as it came.
+     */
+    resolve?(artifact: string): string;
+    /**
+     * What to hand back for an account the subject is already linked to, where the account
+     * alone says so: a profile that carries the link is at the account's own address. The
+     * holder is offered it instead of being asked, and may still hand back something else.
+     */
+    known?(account: ExternalAccount): string | undefined;
     /**
      * Reads what the holder handed back and returns whose it is. Must confirm it contains
      * `expect`. A `location` provider must also refuse any address outside itself, since
@@ -380,10 +440,17 @@ export interface Evidence {
     visibilityApprovedAt: number;
     expiresAt: number;
     revokedAt?: number;
+    /**
+     * What the holder says of the account, and when they said it was finished. Both are the
+     * holder's statements, beside the attestations and never among them: nothing checked them.
+     */
+    mark?: Mark;
+    retiredAt?: number;
     evidenceUrl: string;
     /**
      * Where this record can be had signed, on a verifier that signs. Only a public record
-     * that stands has a signed form: once saved, a signed record cannot be taken back.
+     * that stands, or one retired, has a signed form: once saved, a signed record cannot be
+     * taken back.
      */
     signedUrl?: string;
 }
@@ -406,6 +473,11 @@ export declare function status(connection: Connection, now: number, freshness?:
  * reverses the moment it reads again.
  */
 export declare function fresh(attestation: Attestation, now: number, freshness?: number): boolean;
+/**
+ * The date a retired record stands on: when its account was last proved. A sign-in was
+ * proved when it happened, and a published proof when it was last read.
+ */
+export declare function lastProved(evidence: Pick<Evidence, 'authenticatedAt' | 'attestations'>): number;
 /**
  * The word for a record's state. Evidence can be read after it was issued, so an approval
  * that has run out since reads as expired whatever status it was issued with.

package/dist/core/index.js

@@ -35,6 +35,9 @@ export const freshnessMs = 7 * 86400000;
 export function status(connection, now, freshness = freshnessMs) {
     if (connection.revokedAt !== undefined)
         return 'revoked';
+    // Frozen at its last proof, so neither its expiry nor its freshness is read again.
+    if (connection.retiredAt !== undefined)
+        return 'retired';
     if (now >= connection.expiresAt)
         return 'expired';
     const main = connection.attestations?.external[0];
@@ -53,6 +56,14 @@ export function fresh(attestation, now, freshness = freshnessMs) {
         freshness === Infinity ||
         now < attestation.confirmedAt + freshness);
 }
+/**
+ * The date a retired record stands on: when its account was last proved. A sign-in was
+ * proved when it happened, and a published proof when it was last read.
+ */
+export function lastProved(evidence) {
+    const main = evidence.attestations.external[0];
+    return main.artifactUrl ? main.confirmedAt : evidence.authenticatedAt;
+}
 /**
  * The word for a record's state. Evidence can be read after it was issued, so an approval
  * that has run out since reads as expired whatever status it was issued with.
@@ -60,6 +71,9 @@ export function fresh(attestation, now, freshness = freshnessMs) {
 export function statusLabel(evidence, now) {
     if (evidence.status === 'revoked')
         return 'Revoked';
+    // Before expiry: a retired record's approval has long run out, and that is not its state.
+    if (evidence.status === 'retired')
+        return 'Retired';
     if (evidence.status === 'expired' || evidence.expiresAt <= now)
         return 'Expired';
     return evidence.status === 'unconfirmed' ? 'Unconfirmed' : 'Verified';

package/dist/core/signed.d.ts

@@ -11,15 +11,29 @@ export interface VerifierKey {
     publicKey: string;
 }
 /**
- * What a signature covers: the record as it stood at `issuedAt`. Whether it still stands
- * is a live fact no signature holds, so its status is left out and `evidenceUrl` is where
- * to ask.
+ * What either version says of a record. The holder's mark is left out: it is about how
+ * their accounts are listed, and no part of what was verified.
  */
-export type SignedDocument = Omit<Evidence, 'status' | 'revokedAt' | 'signedUrl'> & {
+type Signable = Omit<Evidence, 'status' | 'revokedAt' | 'signedUrl' | 'mark' | 'retiredAt'> & {
     type: 'verily-evidence';
-    version: 1;
     issuedAt: number;
 };
+/**
+ * What a signature covers: the record as it stood at `issuedAt`. Whether it still stands
+ * is a live fact no signature holds, so version 1 leaves its status out, means the record
+ * stood when it was signed, and gives `evidenceUrl` as where to ask.
+ *
+ * Version 2 is a retired record, which did not stand when it was signed and says so. It is
+ * a version of its own because a reader of version 1 ignores fields it does not know, and
+ * would read a retired record signed as version 1 as one that stood.
+ */
+export type SignedDocument = (Signable & {
+    version: 1;
+}) | (Signable & {
+    version: 2;
+    status: 'retired';
+    retiredAt: number;
+});
 /**
  * A record that can be checked away from the verifier that served it: the document as
  * text under an OpenPGP cleartext signature, which `gpg --verify` reads as it is.
@@ -47,3 +61,4 @@ export declare function signedBy(signed: unknown): Promise<string | undefined>;
  * of it, so the fingerprint a record names is the one a list holds.
  */
 export declare function verifySigned(signed: unknown, keys: VerifierKey[]): Promise<SignedDocument | undefined>;
+export {};

package/dist/core/signed.js

@@ -100,8 +100,11 @@ export async function verifySigned(signed, keys) {
             await signatures[0].verified;
             const document = JSON.parse(data);
             return document?.type === 'verily-evidence' &&
-                document.version === 1 &&
-                typeof document.issuedAt === 'number'
+                typeof document.issuedAt === 'number' &&
+                (document.version === 1 ||
+                    (document.version === 2 &&
+                        document.status === 'retired' &&
+                        typeof document.retiredAt === 'number'))
                 ? document
                 : undefined;
         }

package/dist/server/copy.d.ts

@@ -6,3 +6,9 @@
  * Served as a file because these pages allow no inline scripts.
  */
 export declare const copyScript = "for (const block of document.querySelectorAll('pre')) {\n  const code = block.querySelector('code');\n\n  if (!code) continue;\n\n  const button = document.createElement('button');\n\n  button.type = 'button';\n  button.className = 'copy';\n  button.textContent = 'Copy';\n  button.setAttribute('aria-live', 'polite');\n\n  button.addEventListener('click', async () => {\n    try {\n      await navigator.clipboard.writeText(code.textContent);\n      button.textContent = 'Copied';\n    } catch {\n      // No clipboard permission, or an insecure origin. Select it instead, which leaves\n      // the holder one keystroke away rather than telling them it worked when it did not.\n      // The label stays short so the button never grows over the line it sits on.\n      const range = document.createRange();\n      const selection = getSelection();\n\n      range.selectNodeContents(code);\n      selection.removeAllRanges();\n      selection.addRange(range);\n      button.textContent = 'Selected';\n    }\n\n    setTimeout(() => (button.textContent = 'Copy'), 2000);\n  });\n\n  block.prepend(button);\n}\n";
+/**
+ * Moves a page that is waiting on a mailed link along once the link has been pressed,
+ * wherever it was pressed. Nothing is redrawn until then, so a code half typed is left
+ * alone. Without this the page still has its own link to press.
+ */
+export declare const waitScript = "const timer = setInterval(async () => {\n  try {\n    const response = await fetch(location.pathname + '/phase', { credentials: 'same-origin' });\n\n    // Still exchanging means the link was pressed and is being recorded: the page that\n    // loaded now would show neither the step before nor the one after.\n    if (response.ok && !['pending', 'exchanging'].includes((await response.json()).phase)) {\n      clearInterval(timer);\n      location.reload();\n    }\n  } catch {\n    // A read that fails says nothing about the flow, which the next one may.\n  }\n}, 2000);\n";

package/dist/server/copy.js

@@ -40,3 +40,23 @@ export const copyScript = `for (const block of document.querySelectorAll('pre'))
   block.prepend(button);
 }
 `;
+/**
+ * Moves a page that is waiting on a mailed link along once the link has been pressed,
+ * wherever it was pressed. Nothing is redrawn until then, so a code half typed is left
+ * alone. Without this the page still has its own link to press.
+ */
+export const waitScript = `const timer = setInterval(async () => {
+  try {
+    const response = await fetch(location.pathname + '/phase', { credentials: 'same-origin' });
+
+    // Still exchanging means the link was pressed and is being recorded: the page that
+    // loaded now would show neither the step before nor the one after.
+    if (response.ok && !['pending', 'exchanging'].includes((await response.json()).phase)) {
+      clearInterval(timer);
+      location.reload();
+    }
+  } catch {
+    // A read that fails says nothing about the flow, which the next one may.
+  }
+}, 2000);
+`;

package/dist/server/discord.js

@@ -10,7 +10,9 @@ export function discordProvider(options) {
         authorizationUrl({ state, challenge, redirectUri }) {
             const url = new URL('https://discord.com/oauth2/authorize');
             // Discord has no account chooser. Forcing the consent screen at least shows the holder
-            // which account they are signed in as before it is linked.
+            // which account they are signed in as before it is linked. It is forced on a flow on
+            // a record too: the holder may have withdrawn the grant since, and asking silently
+            // for one that is gone fails with no way for them to give it again.
             url.search = new URLSearchParams({
                 response_type: 'code',
                 client_id: options.clientId,

package/dist/server/github.js

@@ -7,8 +7,10 @@ export function githubProvider(options) {
         id: 'github',
         name: 'GitHub',
         method: 'oauth',
-        authorizationUrl({ state, challenge, redirectUri }) {
+        authorizationUrl({ state, challenge, redirectUri, account }) {
             const url = new URL('https://github.com/login/oauth/authorize');
+            // A new link is to whichever account the holder picks. A flow on a record already
+            // names its account, so GitHub is asked for that one and not made to offer a choice.
             url.search = new URLSearchParams({
                 client_id: options.clientId,
                 redirect_uri: redirectUri,
@@ -16,7 +18,7 @@ export function githubProvider(options) {
                 code_challenge: challenge,
                 code_challenge_method: 'S256',
                 scope: '',
-                prompt: 'select_account',
+                ...(account ? { login: account.handle } : { prompt: 'select_account' }),
             }).toString();
             return url.href;
         },