@bkazemi/verily 0.8.0 → 0.9.0

package/dist/instance/owner-sites.js

@@ -0,0 +1,130 @@
+import { html } from '../server/html.js';
+import { date } from '../server/render.js';
+import { limits } from './limits.js';
+import { respond, see, unavailable } from './page.js';
+import { dnsPrefix } from './sites.js';
+/** The highest limit the owner may give a site, in requests a minute. */
+const maxLimit = 100000;
+/**
+ * Where the instance owner oversees the sites registered here: suspends one by hand, sets
+ * its request limit, and approves it for YouTube. Sites in `SITES` are the host's, and are
+ * not listed.
+ */
+export class OwnerSites {
+    store;
+    sites;
+    constructor(store, sites) {
+        this.store = store;
+        this.sites = sites;
+    }
+    /** Every stored site, with how it stands and the owner's controls over it. */
+    async page() {
+        const stored = this.sites.stored();
+        const rows = await Promise.all(stored.map(async (site) => {
+            const check = await this.store.get(`${dnsPrefix}${site.id}`);
+            const registered = (await this.sites.operators(site.id))[0]?.addedAt;
+            return this.row(site, check, registered);
+        }));
+        return respond('Registered sites', html `
+        ${stored.length
+            ? html `
+                <p class="fine">
+                  A site registered here gets ${limits.registered} requests a minute and no
+                  YouTube until you change either. A suspended site starts nothing new, but its
+                  backend can still read its connections.
+                </p>
+                ${rows}
+              `
+            : html `<p>No sites are registered here.</p>`}
+        <p><a href="/">Back to owner settings</a></p>
+      `);
+    }
+    /** One of the page's forms, sent to `path`. Every one returns to the page. */
+    async change(path, request) {
+        const fields = new URLSearchParams(await request.text());
+        const id = fields.get('id') ?? '';
+        if (!this.sites.stored().some((site) => site.id === id))
+            return unavailable();
+        if (path === '/sites/suspend') {
+            const suspend = fields.get('suspend') === 'yes';
+            await this.sites.control(id, ({ suspendedAt, ...rest }) => suspend ? { ...rest, suspendedAt: suspendedAt ?? Date.now() } : rest);
+        }
+        else if (path === '/sites/youtube') {
+            const approve = fields.get('approve') === 'yes';
+            await this.sites.control(id, ({ youtubeApprovedAt, ...rest }) => approve ? { ...rest, youtubeApprovedAt: youtubeApprovedAt ?? Date.now() } : rest);
+        }
+        else if (path === '/sites/limit') {
+            const given = fields.get('limit')?.trim() ?? '';
+            const limit = Number(given);
+            // Left empty, the site goes back to the default.
+            if (given && !(Number.isInteger(limit) && limit >= 1 && limit <= maxLimit))
+                return respond('Limit not changed', html `
+            <p>A limit is a whole number of requests a minute, from 1 to ${maxLimit}.</p>
+            <p><a href="/sites">Back to registered sites</a></p>
+          `, 400, 'single');
+            await this.sites.control(id, ({ limit: _, ...rest }) => (given ? { ...rest, limit } : rest));
+        }
+        else
+            return unavailable();
+        return see('/sites');
+    }
+    row(site, check, registered) {
+        const controls = this.sites.controls.get(site.id) ?? {};
+        const standing = controls.suspendedAt !== undefined
+            ? `Suspended by you since ${date(controls.suspendedAt)}`
+            : check?.absentSince !== undefined
+                ? `Suspended since ${date(check.absentSince)}: DNS record missing`
+                : check?.checkedAt !== undefined
+                    ? `Served · DNS record found ${date(check.checkedAt)}`
+                    : 'Served · DNS record not checked yet';
+        const hidden = html `<input type="hidden" name="id" value="${site.id}">`;
+        return html `
+      <section>
+        <h2>${site.name}</h2>
+        <dl>
+          <dt>Site id</dt>
+          <dd>${site.id}</dd>
+          <dt>Origin</dt>
+          <dd><a href="${site.origin}">${site.origin}</a></dd>
+          ${registered !== undefined && html `<dt>Registered</dt><dd>${date(registered)}</dd>`}
+          <dt>Status</dt>
+          <dd>${standing}</dd>
+          <dt>YouTube</dt>
+          <dd>
+            ${controls.youtubeApprovedAt !== undefined
+            ? `Approved ${date(controls.youtubeApprovedAt)}`
+            : 'Withheld'}
+          </dd>
+        </dl>
+        <form action="/sites/limit" method="post">
+          ${hidden}
+          <label>
+            Requests a minute
+            <input
+              name="limit"
+              type="number"
+              min="1"
+              max="${maxLimit}"
+              value="${controls.limit ?? ''}"
+              placeholder="${limits.registered}">
+          </label>
+          <button>Save</button>
+        </form>
+        <div class="actions">
+          <form action="/sites/youtube" method="post">
+            ${hidden}
+            ${controls.youtubeApprovedAt === undefined
+            ? html `<button name="approve" value="yes">Approve YouTube</button>`
+            : html `<button name="approve" value="no">Withhold YouTube</button>`}
+          </form>
+          <form action="/sites/suspend" method="post">
+            ${hidden}
+            ${controls.suspendedAt === undefined
+            ? html `<button name="suspend" value="yes" class="danger">Suspend</button>`
+            : html `<button name="suspend" value="no">Unsuspend</button>`}
+          </form>
+        </div>
+      </section>
+    `;
+    }
+}

package/dist/instance/page.d.ts

@@ -1,3 +1,4 @@
+import { type Html } from '../server/html.js';
 export declare const safeHeaders: {
     'Cache-Control': string;
     'Referrer-Policy': string;
@@ -5,12 +6,21 @@ export declare const safeHeaders: {
     'X-Content-Type-Options': string;
     'Content-Security-Policy': string;
 };
+/** A cookie's value as the request carries it, or undefined. */
+export declare const readCookie: (request: Request, name: string) => string | undefined;
+/**
+ * A Set-Cookie value for every cookie the instance sets: never readable by script, sent
+ * only over HTTPS, and kept off cross-site requests. A lifetime of 0 clears it.
+ */
+export declare const setCookie: (name: string, value: string, ms: number, path?: string) => string;
+/** A 303 to `location`, setting each of `cookies`. */
+export declare function see(location: string, cookies?: string[]): Response;
 /**
  * Every page here says in its heading what it is, the way the library's pages do. The
  * logotype above already says whose it is, so the heading never has to repeat that.
  * `script` is the path of one script the page runs, which its policy then allows.
  */
-export declare const html: (heading: string, body: string, status?: number, variant?: string, script?: string) => Response;
+export declare const respond: (heading: string, body: Html, status?: number, variant?: string, script?: string) => Response;
 /**
  * Every refusal reads the same, so the page says nothing about which check failed. The
  * link goes to the root, which shows whoever asks the page that is theirs.

package/dist/instance/page.js

@@ -1,3 +1,4 @@
+import { html } from '../server/html.js';
 import { page } from '../server/render.js';
 export const safeHeaders = {
     'Cache-Control': 'no-store',
@@ -6,12 +7,31 @@ export const safeHeaders = {
     'X-Content-Type-Options': 'nosniff',
     'Content-Security-Policy': "default-src 'none'; style-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'self'",
 };
+/** A cookie's value as the request carries it, or undefined. */
+export const readCookie = (request, name) => request.headers
+    .get('cookie')
+    ?.split(';')
+    .map((part) => part.trim())
+    .find((part) => part.startsWith(`${name}=`))
+    ?.slice(name.length + 1);
+/**
+ * A Set-Cookie value for every cookie the instance sets: never readable by script, sent
+ * only over HTTPS, and kept off cross-site requests. A lifetime of 0 clears it.
+ */
+export const setCookie = (name, value, ms, path = '/') => `${name}=${value}; HttpOnly; Secure; SameSite=Lax; Path=${path}; Max-Age=${ms / 1000}`;
+/** A 303 to `location`, setting each of `cookies`. */
+export function see(location, cookies = []) {
+    const headers = new Headers({ ...safeHeaders, Location: location });
+    for (const cookie of cookies)
+        headers.append('Set-Cookie', cookie);
+    return new Response(null, { status: 303, headers });
+}
 /**
  * Every page here says in its heading what it is, the way the library's pages do. The
  * logotype above already says whose it is, so the heading never has to repeat that.
  * `script` is the path of one script the page runs, which its policy then allows.
  */
-export const html = (heading, body, status = 200, variant = '', script = '') => new Response(page('', heading, body, variant, script), {
+export const respond = (heading, body, status = 200, variant = '', script = '') => new Response(page('', heading, body, variant, script), {
     status,
     headers: {
         ...safeHeaders,
@@ -27,4 +47,4 @@ export const html = (heading, body, status = 200, variant = '', script = '') =>
  * Every refusal reads the same, so the page says nothing about which check failed. The
  * link goes to the root, which shows whoever asks the page that is theirs.
  */
-export const unavailable = (status = 404) => html('Unavailable', '<p>This resource is unavailable. <a href="/">Go to the start page</a>.</p>', status, 'single');
+export const unavailable = (status = 404) => respond('Unavailable', html `<p>This resource is unavailable. <a href="/">Go to the start page</a>.</p>`, status, 'single');

package/dist/instance/register.d.ts

@@ -0,0 +1,44 @@
+import { type DnsOptions } from '../server/domain.js';
+import { type Sites } from './sites.js';
+import type { Store } from './store.js';
+/** Whether anyone may register a site here. `open` serves a site once its DNS checks out. */
+export type Registration = 'off' | 'open';
+/**
+ * Sites asking to be served here. A claim is held in the requester's browser, signed, and
+ * nothing is stored until the domain's DNS shows they control it: a `verily-claim` record
+ * with the claim's code, and the `verily-verifier` record naming this instance, which
+ * stays up for as long as the site is served.
+ */
+export declare class Registrations {
+    private readonly store;
+    private readonly sites;
+    private readonly dns;
+    private readonly host;
+    constructor(store: Store, sites: Sites, origin: string, dns?: DnsOptions);
+    /** The secret claims are signed with, made the first time one is. */
+    private key;
+    private claim;
+    /** The form, or the records to publish for a claim this browser holds. */
+    page(request: Request): Promise<Response>;
+    /** Checks the form and gives this browser a claim for it. */
+    request(request: Request): Promise<Response>;
+    /** What to publish for a claim, and the button that checks it. */
+    private records;
+    /** Looks the records up and, if both are there, registers the site and shows its keys. */
+    check(request: Request): Promise<Response>;
+    /** Drops this browser's claim. */
+    cancel(): Response;
+}
+/**
+ * Reads each stored site's DNS again when it is due, and suspends a site whose DNS no
+ * longer names this instance, or lifts the suspension once it does again. A lookup that
+ * could not be made changes nothing: only an answer without the record suspends a site.
+ * A site whose record is still missing when it is checked `lapseMs` after it went is
+ * deleted.
+ * Sites in `SITES` are the host's to configure, and are not checked.
+ *
+ * Every attempt is recorded, answered or not, and the due sites asked longest ago go
+ * first. So sites that are always due, suspended or failing, cannot use up every run's
+ * budget and leave the rest unchecked.
+ */
+export declare function recheckSites(store: Store, sites: Sites, origin: string, dns?: DnsOptions): Promise<void>;

package/dist/instance/register.js

@@ -0,0 +1,254 @@
+import { html } from '../server/html.js';
+import { domainOf, namedVerifiers, published } from '../server/domain.js';
+import { hash, secret } from '../server/service.js';
+import { respond, readCookie, see, setCookie } from './page.js';
+import { checked, dnsPrefix, lapseMs, open, sign, } from './sites.js';
+/** How long a claim lasts. DNS changes can take up to 72 hours to appear. */
+const claimMs = 72 * 3600000;
+const claimCookie = 'verily_claim';
+const claimPrefix = 'verily-claim=';
+/** The claim cookie, sent only to the registration pages. */
+const claimed = (value, ms) => setCookie(claimCookie, value, ms, '/register');
+const field = (form, name) => (form.get(name) ?? '').trim();
+const form = (message, values = {}) => respond('Register a site', html `
+      ${message}
+      <p>
+        Register your site to send its users here to verify their accounts. You will need to add
+        two DNS records to your domain.
+      </p>
+      <form action="/register" method="post">
+        <label>
+          Domain
+          <input name="domain" value="${values.domain ?? ''}" placeholder="example.com" required>
+        </label>
+        <label>
+          Site id
+          <input
+            name="id"
+            value="${values.id ?? ''}"
+            pattern="[a-z0-9-]{1,32}"
+            placeholder="example"
+            required>
+        </label>
+        <label>
+          Authorize URL
+          <input
+            name="authorizeUrl"
+            type="url"
+            value="${values.authorizeUrl ?? ''}"
+            placeholder="https://example.com/api/verily/authorize"
+            required>
+        </label>
+        <label>
+          Return URL
+          <input
+            name="returnUrl"
+            type="url"
+            value="${values.returnUrl ?? ''}"
+            placeholder="https://example.com/api/verily/return"
+            required>
+        </label>
+        <button>Continue</button>
+      </form>
+    `, message ? 400 : 200);
+/**
+ * Sites asking to be served here. A claim is held in the requester's browser, signed, and
+ * nothing is stored until the domain's DNS shows they control it: a `verily-claim` record
+ * with the claim's code, and the `verily-verifier` record naming this instance, which
+ * stays up for as long as the site is served.
+ */
+export class Registrations {
+    store;
+    sites;
+    dns;
+    host;
+    constructor(store, sites, origin, dns = {}) {
+        this.store = store;
+        this.sites = sites;
+        this.dns = dns;
+        this.host = new URL(origin).host.toLowerCase();
+    }
+    /** The secret claims are signed with, made the first time one is. */
+    async key() {
+        return this.store.transaction(async (tx) => {
+            const kept = await tx.get('site/claim-key');
+            if (kept)
+                return kept;
+            const made = secret();
+            await tx.put('site/claim-key', made);
+            return made;
+        });
+    }
+    async claim(request) {
+        const token = readCookie(request, claimCookie);
+        const payload = token ? open(await this.key(), token) : undefined;
+        return payload && typeof payload.exp === 'number' && payload.exp * 1000 > Date.now()
+            ? payload
+            : undefined;
+    }
+    /** The form, or the records to publish for a claim this browser holds. */
+    async page(request) {
+        const claim = await this.claim(request);
+        return claim ? this.records(claim) : form();
+    }
+    /** Checks the form and gives this browser a claim for it. */
+    async request(request) {
+        const values = new URLSearchParams(await request.text());
+        const domain = field(values, 'domain').toLowerCase().replace(/\.$/, '');
+        const shown = Object.fromEntries([...values].map(([name, value]) => [name, value.trim()]));
+        if (!domainOf(`https://${domain}`))
+            return form(html `<p>Enter a public domain name, such as example.com.</p>`, shown);
+        let site;
+        try {
+            site = checked({
+                id: field(values, 'id'),
+                name: domain,
+                origin: `https://${domain}`,
+                authorizeUrl: field(values, 'authorizeUrl'),
+                returnUrl: field(values, 'returnUrl'),
+            });
+        }
+        catch {
+            return form(html `<p>Use an id of lowercase letters, digits and hyphens, and URLs on your domain.</p>`, shown);
+        }
+        if (this.sites.sites.has(site.id))
+            return form(html `<p>That id is taken. Choose another.</p>`, shown);
+        const exp = Math.floor((Date.now() + claimMs) / 1000);
+        const token = sign(await this.key(), { site, code: secret(), exp });
+        return see('/register', [claimed(token, claimMs)]);
+    }
+    /** What to publish for a claim, and the button that checks it. */
+    records(claim, message, status = 200) {
+        const name = `_verily.${new URL(claim.site.origin).hostname}`;
+        return respond('Add the DNS records', html `
+        ${message}
+        <p>Add two TXT records named <code>${name}</code>:</p>
+        <pre><code>${`${claimPrefix}${claim.code}`}</code></pre>
+        <pre><code>${`verily-verifier=${this.host}`}</code></pre>
+        <p>
+          The first proves you control ${claim.site.name}, and can be removed once the site is
+          registered. The second says this instance verifies for your site. Keep it: if it is
+          removed, the site stops being served within a day, and is deleted 30 days later.
+        </p>
+        <p>DNS changes can take up to 72 hours to appear.</p>
+        <form action="/register/check" method="post"><button>Check the records</button></form>
+        <form action="/register/cancel" method="post"><button>Start over</button></form>
+      `, status);
+    }
+    /** Looks the records up and, if both are there, registers the site and shows its keys. */
+    async check(request) {
+        const claim = await this.claim(request);
+        if (!claim)
+            return form(html `<p>That registration expired. Start again.</p>`);
+        const domain = new URL(claim.site.origin).hostname;
+        const values = await published(domain, this.dns)
+            .then((found) => found.values)
+            .catch(() => undefined);
+        if (!values)
+            return this.records(claim, html `<p>DNS could not be read. Try again shortly.</p>`, 503);
+        // The code is public once published, so a plain comparison gives nothing away.
+        const proved = values.some((value) => value.startsWith(claimPrefix) && value.slice(claimPrefix.length).trim() === claim.code);
+        const named = namedVerifiers(values).some(({ host }) => host === this.host);
+        if (!proved || !named)
+            return this.records(claim, html `
+          <p>
+            ${!proved && !named
+                ? 'Neither record was'
+                : !proved
+                    ? 'The verily-claim record was not'
+                    : 'The verily-verifier record was not'} found yet.
+          </p>
+        `, 409);
+        const siteKey = secret();
+        const dashboardKey = secret();
+        try {
+            await this.sites.register({ ...claim.site, key: siteKey }, { kind: 'key', hash: hash(dashboardKey), addedAt: Date.now() });
+        }
+        catch {
+            return respond('Not registered', html `
+          <p>That id or domain was registered by someone else first.</p>
+          <form action="/register/cancel" method="post"><button>Start over</button></form>
+        `, 409);
+        }
+        const response = respond('Site registered', html `
+        <p>
+          ${claim.site.name} is registered as <code>${claim.site.id}</code>. These keys are shown
+          once and cannot be shown again.
+        </p>
+        <p>Site key, for your backend only. It signs handoffs and reads your users' connections.</p>
+        <pre><code>${siteKey}</code></pre>
+        <p>Dashboard key, for whoever manages the site here. Keep it in a password manager.</p>
+        <pre><code>${dashboardKey}</code></pre>
+        <p>
+          If both keys are lost, the site cannot be recovered. Registering the domain again makes a
+          new site, and your users have to connect their accounts again.
+        </p>
+      `);
+        response.headers.append('Set-Cookie', claimed('', 0));
+        return response;
+    }
+    /** Drops this browser's claim. */
+    cancel() {
+        return see('/register', [claimed('', 0)]);
+    }
+}
+/**
+ * How often a stored site's DNS is read again: daily, and hourly while it is suspended or
+ * after a lookup that got no answer.
+ */
+const recheckMs = 24 * 3600000;
+const retryMs = 3600000;
+/** How many sites one `recheckSites()` looks up, so upkeep stays short. */
+const recheckBudget = 20;
+/**
+ * Reads each stored site's DNS again when it is due, and suspends a site whose DNS no
+ * longer names this instance, or lifts the suspension once it does again. A lookup that
+ * could not be made changes nothing: only an answer without the record suspends a site.
+ * A site whose record is still missing when it is checked `lapseMs` after it went is
+ * deleted.
+ * Sites in `SITES` are the host's to configure, and are not checked.
+ *
+ * Every attempt is recorded, answered or not, and the due sites asked longest ago go
+ * first. So sites that are always due, suspended or failing, cannot use up every run's
+ * budget and leave the rest unchecked.
+ */
+export async function recheckSites(store, sites, origin, dns = {}) {
+    const host = new URL(origin).host.toLowerCase();
+    const now = Date.now();
+    await sites.refresh();
+    const checks = new Map((await store.list(dnsPrefix)).map(([key, check]) => [
+        key.slice(dnsPrefix.length),
+        check,
+    ]));
+    const due = sites
+        .stored()
+        .map((site) => ({ site, last: checks.get(site.id) }))
+        .filter(({ last }) => {
+        if (!last)
+            return true;
+        const answered = last.checkedAt !== undefined && last.checkedAt >= last.attemptedAt;
+        const every = answered && last.absentSince === undefined ? recheckMs : retryMs;
+        return now - last.attemptedAt >= every;
+    })
+        .sort((a, b) => (a.last?.attemptedAt ?? 0) - (b.last?.attemptedAt ?? 0))
+        .slice(0, recheckBudget);
+    for (const { site, last } of due) {
+        const values = await published(new URL(site.origin).hostname, dns)
+            .then((found) => found.values)
+            .catch(() => undefined);
+        const named = values && namedVerifiers(values).some((found) => found.host === host);
+        const check = values
+            ? {
+                attemptedAt: now,
+                checkedAt: now,
+                ...(named ? {} : { absentSince: last?.absentSince ?? now }),
+            }
+            : { ...last, attemptedAt: now };
+        await store.put(`${dnsPrefix}${site.id}`, check);
+        // A site suspended for a month is deleted, and its id is never used again. Only an
+        // answer just given can do it: a failed lookup, or one from an earlier run, may be stale.
+        if (values && !named && now - check.absentSince >= lapseMs)
+            await sites.retire(site.id, 'lapsed');
+    }
+    await sites.refresh();
+}

package/dist/instance/routes.js

@@ -12,6 +12,20 @@ export const own = new Set([
     '/mark',
     '/confirm',
     '/records',
+    '/register',
+    '/register/check',
+    '/register/cancel',
+    '/site/dashboard',
+    '/site/dashboard/login',
+    '/site/dashboard/logout',
+    '/site/dashboard/settings',
+    '/site/dashboard/rotate',
+    '/site/dashboard/previous-key',
+    '/site/dashboard/delete',
+    '/sites',
+    '/sites/suspend',
+    '/sites/limit',
+    '/sites/youtube',
     '/handoff/request',
     '/handoff/accept',
     '/site/connections',