@bkazemi/verily 0.8.0 → 0.9.0

package/README.md

@@ -112,7 +112,7 @@ const verily = createVerily({
 | `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.                                               |
+| `profileOrigins` | The origins a local `profileUrl` may be on, or a function returning them.                 |
 | `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. |
 
@@ -168,7 +168,7 @@ import { init } from '@bkazemi/verily';
 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.8.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.9.0/dist/verily.js`. The script defines a global `Verily`.
 
 Then place the badge wherever the account appears:
 
@@ -370,7 +370,7 @@ A static site only needs the script and the badge markup; the backend runs somew
 
 ```html
 <script
-  src="https://cdn.jsdelivr.net/npm/@bkazemi/verily@0.8.0/dist/verily.js"
+  src="https://cdn.jsdelivr.net/npm/@bkazemi/verily@0.9.0/dist/verily.js"
   defer
 ></script>
 <verily-badge
@@ -399,6 +399,8 @@ const verily = createSiteClient({
 
 The client has no dependencies and uses only Web Crypto and `fetch`, so it runs on Node, Next.js, Workers, Deno and Bun. Use it only on your backend: the key is what the instance believes.
 
+When your key is replaced and the old one is kept for 24 hours, deploy with the new key as `key` and the old one as `previousKey`. A user who began before the switch comes back with a result signed with the old key, and `result()` accepts either. Nothing is signed with `previousKey`. Remove it on a later deploy, once the 24 hours are over.
+
 **1. Mount the handler.** It serves the endpoints the instance and the pill need. Give it your own session lookup, and mount it on every path under one prefix:
 
 ```ts

package/dist/instance/auth.js

@@ -1,6 +1,8 @@
 import { timingSafeEqual } from 'node:crypto';
 import { expired } from '../core/index.js';
 import { hash, secret } from '../server/service.js';
+import { readCookie, setCookie } from './page.js';
+import { validKey } from './sites.js';
 const sessionMs = 8 * 3600000;
 // Use a normal host-only cookie name. Secure, HttpOnly, SameSite and Path=/
 // provide the relevant protections while avoiding __Host-prefix rejection by
@@ -12,16 +14,11 @@ export class OwnerAuth {
     constructor(storage, ownerKey) {
         this.storage = storage;
         this.ownerKey = ownerKey;
-        if (!/^[A-Za-z0-9_-]{43,}$/.test(ownerKey))
+        if (!validKey(ownerKey))
             throw new Error('OWNER_KEY must be a randomly generated base64url secret of at least 32 bytes');
     }
     token(request) {
-        return request.headers
-            .get('cookie')
-            ?.split(';')
-            .map((part) => part.trim())
-            .find((part) => part.startsWith(`${cookieName}=`))
-            ?.slice(cookieName.length + 1);
+        return readCookie(request, cookieName);
     }
     async authenticated(request) {
         return (await this.session(request)) !== undefined;
@@ -45,13 +42,13 @@ export class OwnerAuth {
             expiresAt: Date.now() + sessionMs,
             keyHash: hash(this.ownerKey),
         });
-        return `${cookieName}=${token}; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=${sessionMs / 1000}`;
+        return setCookie(cookieName, token, sessionMs);
     }
     async logout(request) {
         const token = this.token(request);
         if (token)
             await this.storage.delete(`owner/session/${hash(token)}`);
-        return `${cookieName}=; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=0`;
+        return setCookie(cookieName, '', 0);
     }
     async allow(bucket, limit, windowMs) {
         return this.storage.transaction(async (tx) => {

package/dist/instance/cloudflare.js

@@ -1,6 +1,7 @@
 import { admit, createInstance } from './index.js';
 import { fromEnv } from './env.js';
-import { html } from './page.js';
+import { respond } from './page.js';
+import { html } from '../server/html.js';
 import { recordStorage } from './store.js';
 /** Values are copied on the way in and out, so a caller never shares one with storage. */
 const keyValue = (storage) => ({
@@ -44,7 +45,7 @@ export default {
             });
         }
         catch {
-            return html('Temporarily unavailable', '', 503);
+            return respond('Temporarily unavailable', html ``, 503);
         }
     },
 };

package/dist/instance/dashboard.d.ts

@@ -0,0 +1,41 @@
+import { type Provider } from '../core/index.js';
+import { type Sites } from './sites.js';
+import type { Store } from './store.js';
+/**
+ * Where the operators of a site registered here change its settings and replace its key.
+ * An operator signs in with the site's id and a dashboard key, which is kept only as a
+ * hash. Sites in `SITES` have no operators, and are changed by the host.
+ */
+export declare class Dashboard {
+    private readonly store;
+    private readonly sites;
+    private readonly providers;
+    private readonly host;
+    private readonly reportUrl;
+    constructor(store: Store, sites: Sites, providers: Provider[], host: string, reportUrl: string);
+    /** The signed-in operator's site, if the session and the key it was opened with still hold. */
+    private session;
+    /** The dashboard for a signed-in operator, or the sign-in form. */
+    page(request: Request): Promise<Response>;
+    login(request: Request): Promise<Response>;
+    logout(request: Request): Promise<Response>;
+    /** Saves the site's URLs, providers and visibility. */
+    settings(request: Request): Promise<Response>;
+    /**
+     * Replaces the site key and shows the new one, once, on a page of its own. The operator
+     * chooses whether the old key keeps working for a day, for a routine change, or stops at
+     * once, for a leak. The form names the key it replaces, so sending it again, from a
+     * reload or a second tab, replaces nothing.
+     */
+    rotate(request: Request): Promise<Response>;
+    /** Stops accepting the previous site key before its 24 hours are up, once confirmed. */
+    retirePreviousKey(request: Request): Promise<Response>;
+    /**
+     * Deletes the site, once the operator has typed its id to confirm. Its id is never used
+     * again, so the same domain can only come back as a new site.
+     */
+    delete(request: Request): Promise<Response>;
+    /** The provider ids this instance offers, each once, with a name to show. */
+    private offered;
+    private render;
+}

package/dist/instance/dashboard.js

@@ -0,0 +1,334 @@
+import { timingSafeEqual } from 'node:crypto';
+import { expired } from '../core/index.js';
+import { html, raw } from '../server/html.js';
+import { date, minute } from '../server/render.js';
+import { hash, secret } from '../server/service.js';
+import { allow } from './limits.js';
+import { respond, readCookie, see, setCookie, unavailable } from './page.js';
+import { dnsPrefix, lapseMs, validId } from './sites.js';
+const cookieName = 'verily_dashboard';
+const sessionMs = 8 * 3600000;
+/** Sign-in attempts a minute for one site, whoever makes them. */
+const loginLimit = 10;
+const sessionPrefix = 'site/dashboard/';
+/** The session cookie, sent only to the dashboard's pages. */
+const sessionSet = (value, ms) => setCookie(cookieName, value, ms, '/site/dashboard');
+const signIn = (message, status = 200) => respond('Site dashboard', html `
+      ${message}
+      <form action="/site/dashboard/login" method="post">
+        <label>Site id <input name="id" autocomplete="username" required></label>
+        <label>
+          Dashboard key
+          <input name="key" type="password" autocomplete="current-password" required>
+        </label>
+        <button>Sign in</button>
+      </form>
+    `, status, 'single');
+const back = html `<p><a href="/site/dashboard">Back to the dashboard</a></p>`;
+/**
+ * Asks before a key change goes ahead, on a page of its own. Its button sends `fields` to
+ * `action` again, with `confirm=yes`.
+ */
+const ask = (heading, text, action, fields, button, danger) => respond(heading, html `
+      <p>${text}</p>
+      <form action="${action}" method="post">
+        ${Object.entries(fields).map(([name, value]) => html `<input type="hidden" name="${name}" value="${value}">`)}
+        <input type="hidden" name="confirm" value="yes">
+        <button${danger && raw(' class="danger"')}>${button}</button>
+      </form>
+      ${back}
+    `, 200, 'single');
+const checkbox = (name, value, label, checked) => html `
+    <label>
+      <input type="checkbox" name="${name}" value="${value}"${checked && raw(' checked')}> ${label}
+    </label>
+  `;
+/**
+ * Where the operators of a site registered here change its settings and replace its key.
+ * An operator signs in with the site's id and a dashboard key, which is kept only as a
+ * hash. Sites in `SITES` have no operators, and are changed by the host.
+ */
+export class Dashboard {
+    store;
+    sites;
+    providers;
+    host;
+    reportUrl;
+    constructor(store, sites, providers, host, reportUrl) {
+        this.store = store;
+        this.sites = sites;
+        this.providers = providers;
+        this.host = host;
+        this.reportUrl = reportUrl;
+    }
+    /** The signed-in operator's site, if the session and the key it was opened with still hold. */
+    async session(request) {
+        const value = readCookie(request, cookieName);
+        if (!value)
+            return undefined;
+        const key = `${sessionPrefix}${hash(value)}`;
+        const session = await this.store.get(key);
+        if (!session || expired(session, Date.now()))
+            return undefined;
+        const site = this.sites.stored().find((stored) => stored.id === session.site);
+        const operators = site ? await this.sites.operators(site.id) : [];
+        if (!site || !operators.some((operator) => operator.hash === session.operator))
+            return undefined;
+        return { key, site };
+    }
+    /** The dashboard for a signed-in operator, or the sign-in form. */
+    async page(request) {
+        const found = await this.session(request);
+        return found ? this.render(found.site) : signIn();
+    }
+    async login(request) {
+        const fields = new URLSearchParams(await request.text());
+        const id = fields.get('id')?.trim() ?? '';
+        const given = fields.get('key') ?? '';
+        if (!validId(id))
+            return signIn(html `<p>Incorrect site id or key.</p>`, 403);
+        if (!(await allow(this.store, [{ key: `dashboard/${id}`, limit: loginLimit }])))
+            return signIn(html `<p>Too many attempts. Try again in a minute.</p>`, 429);
+        const operator = (await this.sites.operators(id)).find((candidate) => timingSafeEqual(Buffer.from(candidate.hash), Buffer.from(hash(given))));
+        if (!operator || !this.sites.stored().some((site) => site.id === id))
+            return signIn(html `<p>Incorrect site id or key.</p>`, 403);
+        const session = secret();
+        await this.store.put(`${sessionPrefix}${hash(session)}`, {
+            site: id,
+            operator: operator.hash,
+            expiresAt: Date.now() + sessionMs,
+        });
+        return see('/site/dashboard', [sessionSet(session, sessionMs)]);
+    }
+    async logout(request) {
+        const value = readCookie(request, cookieName);
+        if (value)
+            await this.store.delete(`${sessionPrefix}${hash(value)}`);
+        return see('/site/dashboard', [sessionSet('', 0)]);
+    }
+    /** Saves the site's URLs, providers and visibility. */
+    async settings(request) {
+        const found = await this.session(request);
+        if (!found)
+            return unavailable(403);
+        const fields = new URLSearchParams(await request.text());
+        const offered = this.offered();
+        const providers = fields.getAll('provider').filter((id) => offered.has(id));
+        const visibility = fields
+            .getAll('visibility')
+            .filter((v) => v === 'public' || v === 'unlisted');
+        if (!providers.length || !visibility.length)
+            return this.render(found.site, html `<p>Choose at least one provider and one visibility.</p>`, 400);
+        try {
+            await this.sites.update(found.site.id, {
+                authorizeUrl: fields.get('authorizeUrl')?.trim() ?? '',
+                returnUrl: fields.get('returnUrl')?.trim() ?? '',
+                // Every provider chosen is saved as no list, so the site also gets any added later.
+                providers: providers.length === offered.size ? undefined : providers,
+                visibility: visibility.length === 2 ? undefined : visibility,
+            });
+        }
+        catch {
+            return this.render(found.site, html `<p>The authorize and return URLs must be on ${found.site.origin}.</p>`, 400);
+        }
+        return see('/site/dashboard');
+    }
+    /**
+     * Replaces the site key and shows the new one, once, on a page of its own. The operator
+     * chooses whether the old key keeps working for a day, for a routine change, or stops at
+     * once, for a leak. The form names the key it replaces, so sending it again, from a
+     * reload or a second tab, replaces nothing.
+     */
+    async rotate(request) {
+        const found = await this.session(request);
+        if (!found)
+            return unavailable(403);
+        const fields = new URLSearchParams(await request.text());
+        const keep = fields.get('keep') === 'day';
+        const from = fields.get('from') ?? '';
+        const replaced = () => respond('Key already replaced', html `
+          <p>
+            The site key was already replaced since this form was loaded, so nothing changed.
+            The new key was shown when it was made.
+          </p>
+          ${back}
+        `, 409, 'single');
+        if (from !== hash(found.site.key))
+            return replaced();
+        const overlapping = !!found.site.previousKey && (found.site.previousUntil ?? 0) > Date.now();
+        if (fields.get('confirm') !== 'yes')
+            return keep
+                ? ask('Replace the key?', `Deploy the new key to your backend within 24 hours. After that the old key stops working, and so does your site until it has the new one.${overlapping ? ' The older key still accepted from the last replacement stops working now.' : ''}`, '/site/dashboard/rotate', { keep: 'day', from }, 'Replace, keep the old key for 24 hours', false)
+                : ask('Replace the key now?', 'Your site stops sending users here and reading their connections until you deploy the new key. To change keys without interruption, keep the old key for 24 hours instead.', '/site/dashboard/rotate', { keep: 'none', from }, 'Replace now', true);
+        const key = await this.sites.rotate(found.site.id, keep, from);
+        if (!key)
+            return replaced();
+        const until = this.sites.sites.get(found.site.id)?.previousUntil;
+        return respond('New site key', html `
+        <p>This key is shown once. Copy it now.</p>
+        <pre><code>${key}</code></pre>
+        <p>
+          ${keep && until
+            ? `The old key keeps working until ${minute(until)}. Deploy the new key to your backend, then stop accepting the old one from the dashboard.`
+            : 'The old key no longer works. Deploy the new key to your backend now: until you do, your site cannot send users here or read their connections.'}
+        </p>
+        ${back}
+      `);
+    }
+    /** Stops accepting the previous site key before its 24 hours are up, once confirmed. */
+    async retirePreviousKey(request) {
+        const found = await this.session(request);
+        if (!found)
+            return unavailable(403);
+        if (new URLSearchParams(await request.text()).get('confirm') !== 'yes')
+            return ask('Stop accepting the old key?', 'Any backend still using the old key stops working at once: it cannot send users here or read their connections. Do this only once the new key is deployed everywhere.', '/site/dashboard/previous-key', {}, 'Stop accepting the old key', true);
+        await this.sites.retirePreviousKey(found.site.id);
+        return see('/site/dashboard');
+    }
+    /**
+     * Deletes the site, once the operator has typed its id to confirm. Its id is never used
+     * again, so the same domain can only come back as a new site.
+     */
+    async delete(request) {
+        const found = await this.session(request);
+        if (!found)
+            return unavailable(403);
+        const typed = new URLSearchParams(await request.text()).get('confirm')?.trim();
+        if (typed !== found.site.id)
+            return this.render(found.site, html `<p>Type the site id to delete the site.</p>`, 400);
+        await this.sites.retire(found.site.id, 'deleted');
+        await this.store.delete(found.key);
+        const response = respond('Site deleted', html `
+        <p>
+          ${found.site.name} is deleted and no longer served here.
+          Its id, <code>${found.site.id}</code>, cannot be registered again.
+        </p>
+      `, 200, 'single');
+        response.headers.append('Set-Cookie', sessionSet('', 0));
+        return response;
+    }
+    /** The provider ids this instance offers, each once, with a name to show. */
+    offered() {
+        return new Map(this.providers.map((provider) => [provider.id, provider.name]));
+    }
+    async render(site, message, status = 200) {
+        const check = await this.store.get(`${dnsPrefix}${site.id}`);
+        const record = `_verily.${new URL(site.origin).hostname}`;
+        const suspended = check?.absentSince !== undefined;
+        const controls = this.sites.controls.get(site.id) ?? {};
+        const standing = controls.suspendedAt !== undefined
+            ? `Suspended by the instance owner since ${date(controls.suspendedAt)}`
+            : suspended
+                ? `Suspended since ${date(check.absentSince)}`
+                : check?.checkedAt !== undefined
+                    ? `Served · DNS record found ${date(check.checkedAt)}`
+                    : 'Served · DNS record not checked yet';
+        // The one thing on the page the operator has to act on, so the one sentence.
+        const restore = suspended &&
+            html `
+        <p>
+          <code>${record}</code> no longer has <code>verily-verifier=${this.host}</code>.
+          Add it back and the site is served again within an hour.
+          Otherwise the site is deleted on ${date(check.absentSince + lapseMs)}.
+        </p>
+      `;
+        const appeal = controls.suspendedAt !== undefined &&
+            html `
+        <p>
+          The instance owner suspended this site. Your site cannot send users here, but your
+          backend can still read their connections. To ask why or appeal,
+          <a href="${this.reportUrl}">contact the instance owner</a>.
+        </p>
+      `;
+        const overlapping = !!site.previousKey && (site.previousUntil ?? 0) > Date.now();
+        // A provider the owner has not approved this site for stays chosen, and is offered once
+        // it is approved.
+        const held = this.sites.withheld(site.id);
+        const providers = [...this.offered()].map(([id, name]) => checkbox('provider', id, held.includes(id) ? `${name} · awaiting the instance owner's approval` : name, !site.providers || site.providers.includes(id)));
+        const visibility = ['public', 'unlisted'].map((v) => checkbox('visibility', v, v[0].toUpperCase() + v.slice(1), !site.visibility || site.visibility.includes(v)));
+        return respond('Site dashboard', html `
+        ${message}
+        <dl>
+          <dt>Site</dt>
+          <dd>${site.name}</dd>
+          <dt>Site id</dt>
+          <dd>${site.id}</dd>
+          <dt>Status</dt>
+          <dd>${standing}</dd>
+          <dt>Request limit</dt>
+          <dd>${this.sites.limit(site.id)} a minute</dd>
+        </dl>
+        ${appeal}
+        ${restore}
+        <h2>Settings</h2>
+        <form action="/site/dashboard/settings" method="post">
+          <label>
+            Authorize URL
+            <input name="authorizeUrl" type="url" value="${site.authorizeUrl}" required>
+          </label>
+          <label>
+            Return URL
+            <input name="returnUrl" type="url" value="${site.returnUrl}" required>
+          </label>
+          <fieldset>
+            <legend>Providers your users may verify with</legend>
+            ${providers}
+          </fieldset>
+          <fieldset>
+            <legend>Visibility your users may choose</legend>
+            ${visibility}
+          </fieldset>
+          <button>Save</button>
+        </form>
+        <section class="caution">
+          <h2>Site key</h2>
+          <p class="fine">
+            Your backend signs handoffs and reads connections with this key. A new key is shown
+            once. Keep the old key working for 24 hours to deploy the new one without
+            interruption, or stop it at once if it may have leaked.
+          </p>
+          ${overlapping &&
+            html `
+              <section>
+                <p>
+                  The old key is accepted until ${minute(site.previousUntil)}.
+                  Stop accepting it once the new key is deployed.
+                </p>
+                <div class="actions">
+                  <form action="/site/dashboard/previous-key" method="post">
+                    <button>Stop accepting the old key</button>
+                  </form>
+                </div>
+              </section>
+            `}
+          <div class="actions">
+            <form action="/site/dashboard/rotate" method="post">
+              <input type="hidden" name="from" value="${hash(site.key)}">
+              <button name="keep" value="day">Replace, keep the old key for 24 hours</button>
+              <button name="keep" value="none">Replace now</button>
+            </form>
+          </div>
+        </section>
+        <section class="danger">
+          <h2>Delete the site</h2>
+          <p class="fine">
+            The site stops being served here at once, and its id can never be registered again.
+            To come back, register the domain as a new site. Your users then connect their
+            accounts again.
+          </p>
+          <form action="/site/dashboard/delete" method="post">
+            <label>
+              Type <code>${site.id}</code> to confirm
+              <input name="confirm" autocomplete="off" required>
+            </label>
+            <button class="danger">Delete the site</button>
+          </form>
+        </section>
+        <footer>
+          <div class="actions">
+            <form action="/site/dashboard/logout" method="post"><button>Sign out</button></form>
+          </div>
+        </footer>
+      `, status);
+    }
+}

package/dist/instance/env.d.ts

@@ -43,6 +43,8 @@ export interface InstanceEnv {
      */
     SITES?: string | unknown[];
     [key: `SITE_${string}_KEY`]: string | undefined;
+    /** `open` lets anyone register a site at `/register`. Off unless set. */
+    REGISTRATION?: string;
 }
 /**
  * An instance's options from its settings. Every host builds them here, so two hosts given

package/dist/instance/env.js

@@ -80,5 +80,6 @@ export function fromEnv(env) {
         sites: registry(env.SITES, env),
         signingKey: env.SIGNING === 'off' ? false : env.SIGNING_KEY || undefined,
         mailPerDay: dailyMail(env.EMAIL_DAILY_LIMIT),
+        registration: env.REGISTRATION === 'open' ? 'open' : 'off',
     };
 }

package/dist/instance/index.d.ts

@@ -1,6 +1,8 @@
 import { type LocalAccount, type Provider } from '../core/index.js';
 import { type Store } from './store.js';
 import { type Site } from './sites.js';
+import { type Registration } from './register.js';
+import type { DnsOptions } from '../server/domain.js';
 export { fromEnv, type InstanceEnv } from './env.js';
 export { registry, type Site } from './sites.js';
 export { recordStorage, type KeyValue, type Store } from './store.js';
@@ -20,7 +22,10 @@ export interface InstanceOptions {
     reportUrl: string;
     /** The methods offered. A registered site may narrow these for its own holders. */
     providers: Provider[];
-    /** The sites that send their users here instead of hosting Verily, as `registry()` reads them. */
+    /**
+     * The sites the host configures, as `registry()` reads them. Sites registered on the
+     * instance itself are kept in the store and served alongside these.
+     */
     sites?: Map<string, Site>;
     /**
      * The key public records are signed by, armored. Left out, a key is made on first use and
@@ -29,6 +34,13 @@ export interface InstanceOptions {
     signingKey?: string | false;
     /** How many codes may be mailed in a day, where the mail allowance is not the default. */
     mailPerDay?: number;
+    /**
+     * Whether anyone may register a site at `/register`. With `open`, a site is served once
+     * its domain's DNS shows the requester controls it. `off` by default.
+     */
+    registration?: Registration;
+    /** Replaces how DNS is read, for a host behind an egress proxy, or for tests. */
+    dns?: DnsOptions;
     /** How often each published proof is re-read. Six hours by default. */
     recheckMs?: number;
     /** How many proofs one `upkeep()` re-reads per provider. 10 by default. */
@@ -51,6 +63,9 @@ declare class Server {
     private readonly origin;
     private readonly auth;
     private readonly sites;
+    private readonly registrations?;
+    private readonly dashboard;
+    private readonly ownerSites;
     private readonly local;
     constructor(options: InstanceOptions);
     /** The library's service, for a host that needs more than requests and upkeep. */