@bkazemi/verily 0.1.0

package/dist/server/signing.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Making a verifier's key and signing with it. Checking what was signed is in
+ * `core/signed.ts`, which a page runs too.
+ */
+import { type Signer } from '../core/index.js';
+/**
+ * A new signing key for a verifier of this name: an armored OpenPGP private key. Keep it
+ * secret and keep it backed up.
+ *
+ * It is an Ed25519 key in the form GnuPG reads, with no subkeys, so `gpg --verify` checks
+ * what it signs. The name is the key's own word for whose it is, and more can be added to
+ * the same key later without changing its fingerprint.
+ */
+export declare function generateSigningKey(name: string): Promise<string>;
+/** Reads a signing key made by `generateSigningKey`, giving its public half and a way to sign. */
+export declare function signer(signingKey: string): Promise<Signer>;

package/dist/server/signing.js

@@ -0,0 +1,56 @@
+/**
+ * Making a verifier's key and signing with it. Checking what was signed is in
+ * `core/signed.ts`, which a page runs too.
+ */
+import { config as defaults, createCleartextMessage, enums, generateKey, readPrivateKey, sign, } from 'openpgp';
+import { verifySigned } from '../core/index.js';
+const config = { ...defaults, preferredHashAlgorithm: enums.hash.sha512 };
+/**
+ * A new signing key for a verifier of this name: an armored OpenPGP private key. Keep it
+ * secret and keep it backed up.
+ *
+ * It is an Ed25519 key in the form GnuPG reads, with no subkeys, so `gpg --verify` checks
+ * what it signs. The name is the key's own word for whose it is, and more can be added to
+ * the same key later without changing its fingerprint.
+ */
+export async function generateSigningKey(name) {
+    const { privateKey } = await generateKey({
+        type: 'ecc',
+        curve: 'ed25519Legacy',
+        userIDs: [{ name }],
+        subkeys: [],
+        format: 'armored',
+        config,
+    });
+    return privateKey;
+}
+/** Reads a signing key made by `generateSigningKey`, giving its public half and a way to sign. */
+export async function signer(signingKey) {
+    const secret = await readPrivateKey({ armoredKey: signingKey, config }).catch(() => undefined);
+    if (!secret?.isDecrypted())
+        throw new Error('Invalid signing key');
+    const key = {
+        id: secret.getFingerprint().toUpperCase(),
+        alg: 'OpenPGP',
+        publicKey: secret.toPublic().armor(),
+    };
+    const made = {
+        key,
+        async sign(document) {
+            const signed = await sign({
+                message: await createCleartextMessage({ text: JSON.stringify(document, null, 2) }),
+                signingKeys: secret,
+                config,
+            });
+            // Line endings are no part of what is signed, so the file is given one kind of them.
+            return signed.replace(/\r\n/g, '\n');
+        },
+    };
+    // A key that has run out or been revoked, or one that signs with a subkey, would sign
+    // records that do not check. That is found out now and not by whoever saved one.
+    const probe = { type: 'verily-evidence', version: 1, issuedAt: 0 };
+    const checks = await made.sign(probe).then((signed) => verifySigned(signed, [key]), () => undefined);
+    if (!checks)
+        throw new Error('Invalid signing key');
+    return made;
+}

package/dist/server/style.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The one stylesheet for every page this library serves, and for the owner page of a
+ * deployment that mounts it. Served as a file rather than inlined so the pages can keep a
+ * content security policy with no inline styles at all, which is also why nothing here is
+ * set through a style attribute.
+ *
+ * These pages are records: a reader arrives at one to check a claim, reads it once, and
+ * leaves. So the styling does the two things that helps with, a measured column and a
+ * legible hierarchy, and nothing that would make a record look like a product.
+ */
+export declare const stylesheet = ":root {\n  --ink: #23312b;\n  --muted: #6b786f;\n  --line: #dce2de;\n  --surface: #fff;\n  --raised: #f7f9f7;\n  --accent: #245f43;\n  color-scheme: light dark;\n  accent-color: var(--accent);\n}\n\n@media (prefers-color-scheme: dark) {\n  :root {\n    --ink: #dde5e0;\n    --muted: #96a39b;\n    --line: #2f3b35;\n    --surface: #161a18;\n    --raised: #1d2220;\n    --accent: #7fc4a2;\n  }\n}\n\n* { box-sizing: border-box; }\n\nbody {\n  margin: 0;\n  padding: 0 1rem 4rem;\n  background: var(--surface);\n  color: var(--ink);\n  font: 16px/1.65 system-ui, -apple-system, 'Segoe UI', sans-serif;\n  text-rendering: optimizeLegibility;\n}\n\nmain {\n  max-width: 34rem;\n  margin: 0 auto;\n  padding-top: 3rem;\n}\n\n/*\n * The logotype, above the page's own heading, on its own dark plate. Sized so the word is\n * the height it was without the plate, whose margin makes the box that much taller. The\n * word is white in either scheme: the plate is what it is read against, not the page.\n */\n.logo {\n  display: block;\n  height: 2.5rem;\n  margin-bottom: 1.5rem;\n}\n\nh1 {\n  margin: 0 0 1.75rem;\n  padding-bottom: 1rem;\n  border-bottom: 1px solid var(--line);\n  font-size: 1.5rem;\n  font-weight: 620;\n  letter-spacing: -.02em;\n  line-height: 1.25;\n}\n\n/*\n * A page holding one thing needs no rule under its heading. The rule divides a heading\n * from the record beneath it, and a page that only asks for a key has no record to divide.\n */\nmain.single h1 { margin-bottom: 1.25rem; padding-bottom: 0; border-bottom: none; }\n\nh2 { margin: 2rem 0 .75rem; font-size: 1.125rem; font-weight: 620; letter-spacing: -.01em; }\n\nh3 { margin: 0 0 .5rem; font-size: 1rem; font-weight: 620; }\n\np { margin: 0 0 1rem; overflow-wrap: break-word; }\n\na { color: var(--accent); text-underline-offset: 3px; overflow-wrap: anywhere; }\n\na:hover { text-decoration-thickness: 2px; }\n\n/*\n * Something to be run or published exactly as written. Its own line breaks are kept and a\n * long line is soft-wrapped rather than cut off: a soft wrap is drawn, not inserted, so\n * what is copied is still character for character what was written. Selecting inside the\n * block takes all of it, since half a command is worse than none.\n */\npre {\n  position: relative;\n  margin: 0 0 1rem;\n  /* Room along the top line for the copy button, which sits over the block rather than in it. */\n  padding: .75rem 5.25rem .75rem .875rem;\n  border: 1px solid var(--line);\n  border-radius: 6px;\n  background: var(--raised);\n  white-space: pre-wrap;\n  overflow-wrap: anywhere;\n  user-select: all;\n}\n\ncode { font: .8125rem/1.6 ui-monospace, SFMono-Regular, Menlo, monospace; }\n\n/* Made by a script, so it exists only where it works. Quiet: the block is the point. */\n.copy {\n  position: absolute;\n  top: .5rem;\n  right: .5rem;\n  padding: .1875rem .5rem;\n  border: 1px solid var(--line);\n  border-radius: 5px;\n  background: var(--surface);\n  color: var(--muted);\n  font: 500 .75rem/1.5 system-ui, sans-serif;\n  user-select: none;\n}\n\n.copy:hover { color: var(--ink); border-color: var(--muted); }\n\n/*\n * The two sides of the link, which is what a reader came to read. Each fact about a side\n * gets its own line: what it is, what it is called, the identifier behind that, and how it\n * was shown. Everything else on the page qualifies the pair, so it is set quieter.\n */\n.side {\n  margin-bottom: .75rem;\n  padding: .875rem 1rem;\n  border: 1px solid var(--line);\n  border-radius: 8px;\n  background: var(--raised);\n}\n\n.who {\n  margin: 0 0 .125rem;\n  color: var(--muted);\n  font-size: .75rem;\n  font-weight: 550;\n  letter-spacing: .02em;\n}\n\n.name { margin: 0; font-size: 1.0625rem; font-weight: 620; letter-spacing: -.01em; }\n\n/* The name is the card's subject before it is a link, so the rule is drawn on hover. */\n.name a { text-decoration: none; }\n\n.name a:hover { text-decoration: underline; }\n\n.reference, .how { margin: 0; color: var(--muted); font-size: .8125rem; line-height: 1.5; }\n\n.name + .how, .reference + .how { margin-top: .5rem; }\n.how.additional { padding-left: .75rem; }\n\n.fine { color: var(--muted); font-size: .8125rem; line-height: 1.55; margin-bottom: .625rem; }\n\n/* That the record is signed is a fact about it, so it is set as one and not as fine print. */\n.signed { font-size: .875rem; line-height: 1.55; margin-bottom: .875rem; }\n/* Arrived at from a badge's \"signed\" link, so the reader is shown where they landed. */\n.signed:target { margin-inline: -.75rem; padding: .625rem .75rem; border-radius: 8px; background: var(--raised); }\n\n/* Every time on the record in one column, so they can be compared rather than hunted for. */\ndl {\n  display: grid;\n  grid-template-columns: auto 1fr;\n  gap: .3rem 1.5rem;\n  margin: 1.25rem 0;\n  padding-top: 1rem;\n  border-top: 1px solid var(--line);\n  font-size: .8125rem;\n}\n\ndt { color: var(--muted); }\n\ndd { margin: 0; font-variant-numeric: tabular-nums; }\n\n/* Inside a card the rule above it is the card's own edge, so the list needs none. */\nsection dl { margin: .5rem 0 1rem; padding-top: 0; border-top: 0; }\n\nsection {\n  margin: 0 0 1.25rem;\n  padding: 1.25rem 1.375rem;\n  border: 1px solid var(--line);\n  border-radius: 10px;\n}\n\nsection > :last-child { margin-bottom: 0; }\n\nform { margin: 0 0 1.5rem; }\n\nlabel { display: block; margin: 0 0 .75rem; color: var(--muted); font-size: .8125rem; }\n\ninput, textarea {\n  display: block;\n  width: 100%;\n  margin-top: .375rem;\n  padding: .5rem .625rem;\n  border: 1px solid var(--line);\n  border-radius: 6px;\n  background: var(--surface);\n  color: var(--ink);\n  font: .875rem/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;\n}\n\n/* Height comes from the rows attribute, which differs per box. */\ntextarea { resize: vertical; }\n\ninput:focus-visible, textarea:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }\n\nbutton {\n  padding: .5rem 1rem;\n  border: 1px solid var(--accent);\n  border-radius: 6px;\n  background: var(--accent);\n  color: var(--surface);\n  font: 500 .9375rem/1.4 inherit;\n  cursor: pointer;\n}\n\nbutton + button { margin-left: .5rem; border-color: var(--line); background: none; color: var(--ink); }\n\nfieldset { margin: 0 0 1.25rem; padding: 1rem 1.125rem .25rem; border: 1px solid var(--line); border-radius: 8px; }\n\nlegend { padding: 0 .375rem; color: var(--muted); font-size: .8125rem; }\n\nfieldset label { display: flex; align-items: baseline; gap: .5rem; color: var(--ink); font-size: .9375rem; }\n\nfieldset input { width: auto; margin: 0; }\n\nfieldset p { margin: .25rem 0 .875rem 1.5rem; color: var(--muted); font-size: .8125rem; }\n";
+/**
+ * A short digest of the sheet above, put in the link's query so a release that changes the
+ * styling changes its address. Without that the only safe cache is no cache: a reader who
+ * once loaded a page holds the sheet it came with, and the next release renders inside it.
+ */
+export declare const styleVersion: string;

package/dist/server/style.js

@@ -0,0 +1,244 @@
+/**
+ * The one stylesheet for every page this library serves, and for the owner page of a
+ * deployment that mounts it. Served as a file rather than inlined so the pages can keep a
+ * content security policy with no inline styles at all, which is also why nothing here is
+ * set through a style attribute.
+ *
+ * These pages are records: a reader arrives at one to check a claim, reads it once, and
+ * leaves. So the styling does the two things that helps with, a measured column and a
+ * legible hierarchy, and nothing that would make a record look like a product.
+ */
+export const stylesheet = `:root {
+  --ink: #23312b;
+  --muted: #6b786f;
+  --line: #dce2de;
+  --surface: #fff;
+  --raised: #f7f9f7;
+  --accent: #245f43;
+  color-scheme: light dark;
+  accent-color: var(--accent);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --ink: #dde5e0;
+    --muted: #96a39b;
+    --line: #2f3b35;
+    --surface: #161a18;
+    --raised: #1d2220;
+    --accent: #7fc4a2;
+  }
+}
+
+* { box-sizing: border-box; }
+
+body {
+  margin: 0;
+  padding: 0 1rem 4rem;
+  background: var(--surface);
+  color: var(--ink);
+  font: 16px/1.65 system-ui, -apple-system, 'Segoe UI', sans-serif;
+  text-rendering: optimizeLegibility;
+}
+
+main {
+  max-width: 34rem;
+  margin: 0 auto;
+  padding-top: 3rem;
+}
+
+/*
+ * The logotype, above the page's own heading, on its own dark plate. Sized so the word is
+ * the height it was without the plate, whose margin makes the box that much taller. The
+ * word is white in either scheme: the plate is what it is read against, not the page.
+ */
+.logo {
+  display: block;
+  height: 2.5rem;
+  margin-bottom: 1.5rem;
+}
+
+h1 {
+  margin: 0 0 1.75rem;
+  padding-bottom: 1rem;
+  border-bottom: 1px solid var(--line);
+  font-size: 1.5rem;
+  font-weight: 620;
+  letter-spacing: -.02em;
+  line-height: 1.25;
+}
+
+/*
+ * A page holding one thing needs no rule under its heading. The rule divides a heading
+ * from the record beneath it, and a page that only asks for a key has no record to divide.
+ */
+main.single h1 { margin-bottom: 1.25rem; padding-bottom: 0; border-bottom: none; }
+
+h2 { margin: 2rem 0 .75rem; font-size: 1.125rem; font-weight: 620; letter-spacing: -.01em; }
+
+h3 { margin: 0 0 .5rem; font-size: 1rem; font-weight: 620; }
+
+p { margin: 0 0 1rem; overflow-wrap: break-word; }
+
+a { color: var(--accent); text-underline-offset: 3px; overflow-wrap: anywhere; }
+
+a:hover { text-decoration-thickness: 2px; }
+
+/*
+ * Something to be run or published exactly as written. Its own line breaks are kept and a
+ * long line is soft-wrapped rather than cut off: a soft wrap is drawn, not inserted, so
+ * what is copied is still character for character what was written. Selecting inside the
+ * block takes all of it, since half a command is worse than none.
+ */
+pre {
+  position: relative;
+  margin: 0 0 1rem;
+  /* Room along the top line for the copy button, which sits over the block rather than in it. */
+  padding: .75rem 5.25rem .75rem .875rem;
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  background: var(--raised);
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  user-select: all;
+}
+
+code { font: .8125rem/1.6 ui-monospace, SFMono-Regular, Menlo, monospace; }
+
+/* Made by a script, so it exists only where it works. Quiet: the block is the point. */
+.copy {
+  position: absolute;
+  top: .5rem;
+  right: .5rem;
+  padding: .1875rem .5rem;
+  border: 1px solid var(--line);
+  border-radius: 5px;
+  background: var(--surface);
+  color: var(--muted);
+  font: 500 .75rem/1.5 system-ui, sans-serif;
+  user-select: none;
+}
+
+.copy:hover { color: var(--ink); border-color: var(--muted); }
+
+/*
+ * The two sides of the link, which is what a reader came to read. Each fact about a side
+ * gets its own line: what it is, what it is called, the identifier behind that, and how it
+ * was shown. Everything else on the page qualifies the pair, so it is set quieter.
+ */
+.side {
+  margin-bottom: .75rem;
+  padding: .875rem 1rem;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--raised);
+}
+
+.who {
+  margin: 0 0 .125rem;
+  color: var(--muted);
+  font-size: .75rem;
+  font-weight: 550;
+  letter-spacing: .02em;
+}
+
+.name { margin: 0; font-size: 1.0625rem; font-weight: 620; letter-spacing: -.01em; }
+
+/* The name is the card's subject before it is a link, so the rule is drawn on hover. */
+.name a { text-decoration: none; }
+
+.name a:hover { text-decoration: underline; }
+
+.reference, .how { margin: 0; color: var(--muted); font-size: .8125rem; line-height: 1.5; }
+
+.name + .how, .reference + .how { margin-top: .5rem; }
+.how.additional { padding-left: .75rem; }
+
+.fine { color: var(--muted); font-size: .8125rem; line-height: 1.55; margin-bottom: .625rem; }
+
+/* That the record is signed is a fact about it, so it is set as one and not as fine print. */
+.signed { font-size: .875rem; line-height: 1.55; margin-bottom: .875rem; }
+/* Arrived at from a badge's "signed" link, so the reader is shown where they landed. */
+.signed:target { margin-inline: -.75rem; padding: .625rem .75rem; border-radius: 8px; background: var(--raised); }
+
+/* Every time on the record in one column, so they can be compared rather than hunted for. */
+dl {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: .3rem 1.5rem;
+  margin: 1.25rem 0;
+  padding-top: 1rem;
+  border-top: 1px solid var(--line);
+  font-size: .8125rem;
+}
+
+dt { color: var(--muted); }
+
+dd { margin: 0; font-variant-numeric: tabular-nums; }
+
+/* Inside a card the rule above it is the card's own edge, so the list needs none. */
+section dl { margin: .5rem 0 1rem; padding-top: 0; border-top: 0; }
+
+section {
+  margin: 0 0 1.25rem;
+  padding: 1.25rem 1.375rem;
+  border: 1px solid var(--line);
+  border-radius: 10px;
+}
+
+section > :last-child { margin-bottom: 0; }
+
+form { margin: 0 0 1.5rem; }
+
+label { display: block; margin: 0 0 .75rem; color: var(--muted); font-size: .8125rem; }
+
+input, textarea {
+  display: block;
+  width: 100%;
+  margin-top: .375rem;
+  padding: .5rem .625rem;
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  background: var(--surface);
+  color: var(--ink);
+  font: .875rem/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+
+/* Height comes from the rows attribute, which differs per box. */
+textarea { resize: vertical; }
+
+input:focus-visible, textarea:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
+
+button {
+  padding: .5rem 1rem;
+  border: 1px solid var(--accent);
+  border-radius: 6px;
+  background: var(--accent);
+  color: var(--surface);
+  font: 500 .9375rem/1.4 inherit;
+  cursor: pointer;
+}
+
+button + button { margin-left: .5rem; border-color: var(--line); background: none; color: var(--ink); }
+
+fieldset { margin: 0 0 1.25rem; padding: 1rem 1.125rem .25rem; border: 1px solid var(--line); border-radius: 8px; }
+
+legend { padding: 0 .375rem; color: var(--muted); font-size: .8125rem; }
+
+fieldset label { display: flex; align-items: baseline; gap: .5rem; color: var(--ink); font-size: .9375rem; }
+
+fieldset input { width: auto; margin: 0; }
+
+fieldset p { margin: .25rem 0 .875rem 1.5rem; color: var(--muted); font-size: .8125rem; }
+`;
+/**
+ * A short digest of the sheet above, put in the link's query so a release that changes the
+ * styling changes its address. Without that the only safe cache is no cache: a reader who
+ * once loaded a page holds the sheet it came with, and the next release renders inside it.
+ */
+export const styleVersion = (() => {
+    let hash = 0x811c9dc5;
+    for (const char of stylesheet)
+        hash = Math.imul(hash ^ char.charCodeAt(0), 0x01000193) >>> 0;
+    return hash.toString(36);
+})();

package/dist/server/wkd.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Where a domain would publish the key for one of its addresses, most specific first. The
+ * advanced form lives on a subdomain a mail operator can delegate without touching the
+ * main site; the direct form is on the domain itself. Both are tried because both are in
+ * use, and either one answering is the domain answering.
+ */
+export declare function wkdUrls(address: string): string[];

package/dist/server/wkd.js

@@ -0,0 +1,65 @@
+import { createHash } from 'node:crypto';
+/** Z-Base-32, which is not RFC 4648's alphabet: the spec picked this one for legibility. */
+const alphabet = 'ybndrfg8ejkmcpqxot1uwisza345h769';
+/**
+ * Domain suffixes that must never be fetched. The address comes off a key a stranger
+ * pasted, so it names the host, and these are the names that can resolve to something
+ * inside the network running this. Reserved suffixes that resolve nowhere are left alone:
+ * asking about them is pointless rather than dangerous, and they are what tests use.
+ */
+const reserved = ['local', 'internal', 'localhost', 'home', 'lan', 'corp', 'intranet'];
+function zbase32(data) {
+    let bits = 0;
+    let value = 0;
+    let out = '';
+    for (const byte of data) {
+        value = (value << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            out += alphabet[(value >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+    }
+    // A twenty byte digest is exactly thirty two characters, so nothing is ever left over.
+    if (bits > 0)
+        out += alphabet[(value << (5 - bits)) & 31];
+    return out;
+}
+/**
+ * Splits an address into the parts the directory is addressed by. The local part is
+ * lowercased and hashed rather than sent, which is the point of the scheme: a domain can
+ * answer for an address without publishing a list of the addresses it has.
+ */
+function parts(address) {
+    const at = address.lastIndexOf('@');
+    if (at < 1 || at === address.length - 1)
+        return undefined;
+    const local = address.slice(0, at);
+    const domain = address.slice(at + 1).toLowerCase();
+    // A host, not an address literal and not a suffix that resolves inside the network.
+    // Where the name really resolves is checked when it is fetched.
+    if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/.test(domain))
+        return undefined;
+    if (/^[\d.]+$/.test(domain) || reserved.includes(domain.split('.').pop()))
+        return undefined;
+    if (local.length > 100 || domain.length > 253)
+        return undefined;
+    return { local, domain };
+}
+/**
+ * Where a domain would publish the key for one of its addresses, most specific first. The
+ * advanced form lives on a subdomain a mail operator can delegate without touching the
+ * main site; the direct form is on the domain itself. Both are tried because both are in
+ * use, and either one answering is the domain answering.
+ */
+export function wkdUrls(address) {
+    const split = parts(address);
+    if (!split)
+        return [];
+    const hashed = zbase32(Uint8Array.from(createHash('sha1').update(split.local.toLowerCase(), 'utf8').digest()));
+    const query = `?l=${encodeURIComponent(split.local)}`;
+    return [
+        `https://openpgpkey.${split.domain}/.well-known/openpgpkey/${split.domain}/hu/${hashed}${query}`,
+        `https://${split.domain}/.well-known/openpgpkey/hu/${hashed}${query}`,
+    ];
+}

package/dist/server/youtube.d.ts

@@ -0,0 +1,11 @@
+import { type RedirectProvider } from '../core/index.js';
+/**
+ * Google OAuth client, PKCE S256, `youtube.readonly` scope only. The account proved is the
+ * YouTube channel chosen at consent, not the Google account behind it. Tokens are revoked
+ * as soon as the channel is read and are never persisted.
+ */
+export declare function youtubeProvider(options: {
+    clientId: string;
+    clientSecret: string;
+    fetch?: typeof fetch;
+}): RedirectProvider;

package/dist/server/youtube.js

@@ -0,0 +1,99 @@
+import { Refused } from '../core/index.js';
+/**
+ * Google OAuth client, PKCE S256, `youtube.readonly` scope only. The account proved is the
+ * YouTube channel chosen at consent, not the Google account behind it. Tokens are revoked
+ * as soon as the channel is read and are never persisted.
+ */
+export function youtubeProvider(options) {
+    if (!options.clientId || !options.clientSecret)
+        throw new Error('Google credentials required');
+    const request = options.fetch ?? fetch;
+    return {
+        id: 'youtube',
+        name: 'YouTube',
+        method: 'oauth',
+        authorizationUrl({ state, challenge, redirectUri }) {
+            const url = new URL('https://accounts.google.com/o/oauth2/v2/auth');
+            // select_account lets a holder with several Google accounts, or a channel under a
+            // brand account, pick the one they mean rather than whichever is signed in.
+            url.search = new URLSearchParams({
+                response_type: 'code',
+                client_id: options.clientId,
+                redirect_uri: redirectUri,
+                state,
+                code_challenge: challenge,
+                code_challenge_method: 'S256',
+                scope: 'https://www.googleapis.com/auth/youtube.readonly',
+                access_type: 'online',
+                prompt: 'select_account',
+            }).toString();
+            return url.href;
+        },
+        async authenticate({ code, verifier, redirectUri }) {
+            const response = await request('https://oauth2.googleapis.com/token', {
+                method: 'POST',
+                headers: { Accept: 'application/json' },
+                signal: AbortSignal.timeout(15000),
+                body: new URLSearchParams({
+                    grant_type: 'authorization_code',
+                    client_id: options.clientId,
+                    client_secret: options.clientSecret,
+                    code,
+                    code_verifier: verifier,
+                    redirect_uri: redirectUri,
+                }),
+            });
+            const token = await response.json();
+            if (!response.ok || !isRecord(token) || typeof token.access_token !== 'string' || token.error)
+                throw new Error('Provider authentication failed');
+            const accessToken = token.access_token;
+            try {
+                const identity = await request('https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true', {
+                    headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/json' },
+                    signal: AbortSignal.timeout(15000),
+                });
+                const body = await identity.json();
+                if (!identity.ok || !isRecord(body))
+                    throw new Error('Invalid provider identity');
+                // A Google account that has never created a channel signs in fine but has nothing
+                // to link, which is the holder's to fix, so it is said rather than hidden.
+                if (!Array.isArray(body.items) || body.items.length === 0)
+                    throw new Refused('This Google account has no YouTube channel');
+                const channel = body.items[0];
+                if (body.items.length !== 1 ||
+                    !isRecord(channel) ||
+                    typeof channel.id !== 'string' ||
+                    !/^UC[A-Za-z0-9_-]{22}$/.test(channel.id) ||
+                    !isRecord(channel.snippet))
+                    throw new Error('Invalid provider identity');
+                // The handle is the @name. The channel id is the stable identity: handles can be
+                // changed and then claimed by another channel.
+                const customUrl = channel.snippet.customUrl;
+                if (customUrl === undefined)
+                    throw new Refused('This YouTube channel has no handle');
+                const handle = typeof customUrl === 'string'
+                    ? /^@?([\p{L}\p{M}\p{N}._·-]{3,30})$/u.exec(customUrl)?.[1]
+                    : undefined;
+                if (!handle)
+                    throw new Error('Invalid provider identity');
+                return {
+                    id: channel.id,
+                    handle,
+                    profileUrl: `https://www.youtube.com/channel/${channel.id}`,
+                };
+            }
+            finally {
+                // The scope reads the whole YouTube account for an hour. Nothing more is needed
+                // from it, so it is given back now rather than left to expire.
+                await request('https://oauth2.googleapis.com/revoke', {
+                    method: 'POST',
+                    signal: AbortSignal.timeout(5000),
+                    body: new URLSearchParams({ token: accessToken }),
+                }).catch(() => undefined);
+            }
+        },
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}

package/dist/site/index.d.ts

@@ -0,0 +1,139 @@
+import type { Evidence, LocalKind, Visibility } from '../core/index.js';
+/**
+ * For a site that uses a hosted Verily instance instead of running its own. The site's
+ * backend does three things, and this is all of them: it vouches to the instance for its
+ * signed-in user; it reads its users' connections back; and, if it wants, it checks the
+ * result a user returns with. `handler()` serves the endpoints the first of those needs,
+ * so a site mounts it and writes none of them.
+ *
+ * Nothing here needs Node. It uses Web Crypto and `fetch`, so it runs wherever a backend
+ * does. It must only ever run on a backend: the key is what the instance believes.
+ */
+export interface SiteClientOptions {
+    /** The instance's origin, such as `https://verily.shirkadeh.org`. */
+    instance: string;
+    /** This site's id in the instance's registry. */
+    site: string;
+    /** The key the instance holds for this site. Never sent to a browser. */
+    key: string;
+    /**
+     * Set this and the site's user ids never leave it: every id this client is given is this
+     * site's own, and the instance is sent a stand-in made with `pseudonym()`. A subject
+     * given no `reference` gets one made the same way. At least 32 characters, kept for this
+     * alone, and never changed: a different secret makes every user a different user to the
+     * instance, and they lose their links.
+     */
+    idSecret?: string;
+    /** How long `connections()` reuses an answer, in milliseconds. Absent, every call reads. */
+    cacheMs?: number;
+    /** Replaces the global `fetch`, for a runtime or a test that needs its own. */
+    fetch?: typeof fetch;
+}
+/** What `handler()` needs from the site: who is signed in, and where its own pages are. */
+export interface SiteHandlerOptions {
+    /**
+     * This site's signed-in user for a request, by the site's own session, or undefined if
+     * nobody is signed in. Nothing in a request to the handler names a user.
+     */
+    authenticate(request: Request): Promise<SiteSubject | undefined> | SiteSubject | undefined;
+    /** Where a signed-out user who arrives from the instance goes to sign in. Absent, a 401. */
+    signInUrl?: string;
+    /** Where a user goes when they come back from the instance. Absent, the site's root. */
+    returnUrl?: string;
+}
+/** The signed-in user a handoff vouches for, as the instance will record them. */
+export interface SiteSubject {
+    /** Private, stable, and never reassigned. The instance never shows it. */
+    id: string;
+    /** Display text for the subject. */
+    label: string;
+    /**
+     * Durable and safe to show publicly. Never an email address. Optional only for a client
+     * with an `idSecret`, which makes one when it is absent.
+     */
+    reference?: string;
+    /** Absent means the site did not say. */
+    kind?: LocalKind;
+    /** Must be on this site's registered origin. */
+    profileUrl?: string;
+}
+/** How a flow a user was sent into ended, as the instance signed it. */
+export interface SiteResult {
+    site: string;
+    id: string;
+    operation: 'connect' | 'renew' | 'visibility' | 'disconnect';
+    outcome: 'complete' | 'cancelled' | 'failed';
+    /** Present when the outcome is complete. */
+    connection?: string;
+    visibility?: Visibility;
+    /** The transaction of the handoff this result answers. */
+    txn: string;
+    exp: number;
+}
+/**
+ * A stable stand-in for one of a site's own user ids, for a site that would rather its ids
+ * never left it. The same secret and value always give the same result, so nothing has to
+ * be stored. The secret must never change: a different one gives every user a different
+ * stand-in, which the instance takes for a different user. Use a secret kept for this alone,
+ * and not the site's key, which is meant to be replaceable.
+ *
+ * `purpose` separates stand-ins made from one secret, so a private id and a public
+ * reference made from the same user id tell nobody they belong together.
+ */
+export declare function pseudonym(secret: string, value: string, purpose?: string): Promise<string>;
+export declare function createSiteClient(options: SiteClientOptions): {
+    /**
+     * Where to link a signed-in user: to verify an account, or to manage the ones they
+     * have. The instance sends them on to this site's authorize endpoint with a `state`.
+     */
+    beginUrl(purpose?: "connect" | "manage"): string;
+    /**
+     * For the authorize endpoint: where to redirect a signed-in user, with a handoff that
+     * vouches for them. Call it only once this site has itself established who they are,
+     * with the `state` the instance sent. `txn` names this handoff in the result that
+     * comes back; a site that reads its connections from the instance can ignore it.
+     */
+    authorize(state: string, subject: SiteSubject): Promise<{
+        url: string;
+        txn: string;
+    }>;
+    /**
+     * For a page that shows the connect pill with `handoff-url`: a token that vouches for
+     * the signed-in user to the dialog on that page. Serve it from an endpoint on this
+     * site, to its signed-in user only and to a POST from this site's own pages, and call
+     * it only once this site has itself established who they are. It works once, within
+     * four minutes, and only from a page on this site's registered origin.
+     */
+    handoff(subject: SiteSubject): Promise<{
+        token: string;
+        txn: string;
+    }>;
+    /**
+     * Each subject's connections, unlisted ones included, by the id this site vouched for
+     * them with. Only this site can read them. Every id asked for is in the answer, with an
+     * empty list for a subject who has none. Revoked and expired records are included, so
+     * show one only when its `status` is `verified`. With `cacheMs` set, an answer read
+     * within it is reused unless `fresh` asks for a new one.
+     */
+    connections(ids: string[], { fresh }?: {
+        fresh?: boolean;
+    }): Promise<Record<string, Evidence[]>>;
+    /**
+     * For the return endpoint: the result a user came back with, if the instance signed it
+     * for this site and it has not expired. Undefined otherwise. A site that reads its
+     * connections from the instance has no need of it and can send the user straight on.
+     *
+     * A site that stores what a result says must also check that `id` is the signed-in
+     * user and that `txn` is the handoff it is waiting on, since a user's own older result
+     * is validly signed too. With an `idSecret`, `id` is the user's stand-in.
+     */
+    result(token: string): Promise<SiteResult | undefined>;
+    /**
+     * The endpoints a site needs, as one function from a `Request` to a `Response`. Mount
+     * it on every path under one prefix, such as `/api/verily/*`. The authorize and return
+     * URLs registered with the instance are `<prefix>/authorize` and `<prefix>/return`,
+     * and the connect pill's `handoff-url` is `<prefix>/handoff`.
+     */
+    handler(site: SiteHandlerOptions): (request: Request) => Promise<Response>;
+};
+export type SiteClient = ReturnType<typeof createSiteClient>;