@bkazemi/verily 0.8.1 → 0.9.1

package/dist/instance/sites.js

@@ -1,5 +1,7 @@
 import { createHmac, timingSafeEqual } from 'node:crypto';
 import { expired, } from '../core/index.js';
+import { limits } from './limits.js';
+import { readCookie, setCookie } from './page.js';
 import { hash, secret } from '../server/service.js';
 /** How long a handoff may take, from `/handoff/request` to `/handoff/accept`, and how far ahead a token may run. */
 export const handoffMs = 5 * 60000;
@@ -18,6 +20,56 @@ function secureOrigin(value) {
         (url.protocol === 'https:' ||
             (url.protocol === 'http:' && ['localhost', '127.0.0.1'].includes(url.hostname))));
 }
+/** Where a site registered on the instance itself is kept, under its id. */
+const registeredPrefix = 'site/registered/';
+/** Where a site's operators are kept, under its id. */
+const operatorsPrefix = 'site/operators/';
+/** Where an id that has been used is kept once its site is gone, so it is never reused. */
+const retiredPrefix = 'site/retired/';
+/** How long a stored site stays suspended before it is deleted. */
+export const lapseMs = 30 * 24 * 3600000;
+/** Where the instance owner's controls over a stored site are kept, under its id. */
+const controlsPrefix = 'site/controls/';
+/** Providers a stored site's holders get only once the owner approves the site. */
+const approvalNeeded = ['youtube'];
+/** Where the last DNS check of a stored site is kept, under its id. */
+export const dnsPrefix = 'site/dns/';
+/** A site's id: what prefixes its subjects and names it in every token. */
+export const validId = (id) => typeof id === 'string' && /^[a-z0-9-]{1,32}$/.test(id);
+/** A key: base64url, of at least 32 bytes. */
+export const validKey = (key) => typeof key === 'string' && /^[A-Za-z0-9_-]{43,}$/.test(key);
+/** A site entry checked field by field, without its key. Throws on the first thing wrong. */
+export function checked(entry) {
+    const { id, name, origin, authorizeUrl, returnUrl, providers, visibility } = entry ?? {};
+    if (!validId(id))
+        throw new Error('Each site needs an id of lowercase letters, digits and hyphens');
+    if (typeof name !== 'string' || !name || name.length > 100)
+        throw new Error(`Site ${id} needs a name`);
+    if (typeof origin !== 'string' || !secureOrigin(origin))
+        throw new Error(`Site ${id} needs an HTTPS origin without a trailing slash`);
+    for (const url of [authorizeUrl, returnUrl])
+        if (typeof url !== 'string' || new URL(url).origin !== origin)
+            throw new Error(`Site ${id} must authorize and return on its own origin`);
+    if (providers !== undefined &&
+        (!Array.isArray(providers) ||
+            !providers.length ||
+            providers.some((p) => typeof p !== 'string' || !p)))
+        throw new Error(`Site ${id} must list at least one provider id, or none at all`);
+    if (visibility !== undefined &&
+        (!Array.isArray(visibility) ||
+            !visibility.length ||
+            visibility.some((v) => v !== 'public' && v !== 'unlisted')))
+        throw new Error(`Site ${id} must list "public", "unlisted" or both, or no visibility at all`);
+    return {
+        id,
+        name,
+        origin,
+        authorizeUrl: authorizeUrl,
+        returnUrl: returnUrl,
+        ...(providers ? { providers: providers } : {}),
+        ...(visibility ? { visibility: visibility } : {}),
+    };
+}
 /**
  * The registered sites, from the `SITES` variable, each with its key from the secret
  * `SITE_<ID>_KEY`. Anything wrong in the list refuses to start rather than serving a site
@@ -29,43 +81,17 @@ export function registry(config, secrets) {
         throw new Error('SITES must be a list');
     const sites = new Map();
     for (const entry of list) {
-        const { id, name, origin, authorizeUrl, returnUrl, providers, visibility } = entry ?? {};
-        if (typeof id !== 'string' || !/^[a-z0-9-]{1,32}$/.test(id) || sites.has(id))
-            throw new Error('Each site needs a unique id of lowercase letters, digits and hyphens');
-        const key = secrets[`SITE_${id.toUpperCase().replace(/-/g, '_')}_KEY`];
-        if (typeof name !== 'string' || !name || name.length > 100)
-            throw new Error(`Site ${id} needs a name`);
-        if (typeof origin !== 'string' || !secureOrigin(origin))
-            throw new Error(`Site ${id} needs an HTTPS origin without a trailing slash`);
-        for (const url of [authorizeUrl, returnUrl])
-            if (typeof url !== 'string' || new URL(url).origin !== origin)
-                throw new Error(`Site ${id} must authorize and return on its own origin`);
-        if (providers !== undefined &&
-            (!Array.isArray(providers) ||
-                !providers.length ||
-                providers.some((p) => typeof p !== 'string' || !p)))
-            throw new Error(`Site ${id} must list at least one provider id, or none at all`);
-        if (visibility !== undefined &&
-            (!Array.isArray(visibility) ||
-                !visibility.length ||
-                visibility.some((v) => v !== 'public' && v !== 'unlisted')))
-            throw new Error(`Site ${id} must list "public", "unlisted" or both, or no visibility at all`);
+        const site = checked(entry);
+        if (sites.has(site.id))
+            throw new Error(`Site ${site.id} is listed twice`);
+        const key = secrets[`SITE_${site.id.toUpperCase().replace(/-/g, '_')}_KEY`];
         // A secret is set apart from a deployment and cannot be checked before one. A wrong
         // one leaves its own site unserved, and never takes the rest of the instance with it.
-        if (typeof key !== 'string' || !/^[A-Za-z0-9_-]{43,}$/.test(key)) {
-            console.error(`Site ${id} is not served: it needs a base64url key of at least 32 bytes`);
+        if (!validKey(key)) {
+            console.error(`Site ${site.id} is not served: it needs a base64url key of at least 32 bytes`);
             continue;
         }
-        sites.set(id, {
-            id,
-            name,
-            origin,
-            authorizeUrl: authorizeUrl,
-            returnUrl: returnUrl,
-            key,
-            ...(providers ? { providers: providers } : {}),
-            ...(visibility ? { visibility: visibility } : {}),
-        });
+        sites.set(site.id, { ...site, key });
     }
     return sites;
 }
@@ -99,13 +125,32 @@ export function open(key, token) {
         return undefined;
     return peek(token);
 }
-const cookie = (request, name) => request.headers
-    .get('cookie')
-    ?.split(';')
-    .map((part) => part.trim())
-    .find((part) => part.startsWith(`${name}=`))
-    ?.slice(name.length + 1);
-const setCookie = (name, value, ms) => `${name}=${value}; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=${ms / 1000}`;
+/** How long a replaced site key is still accepted, so the site has time to deploy the new one. */
+export const rotationMs = 24 * 3600000;
+/** The site's keys that are accepted now: its key, and its previous key while in date. */
+const accepted = (site) => [
+    site.key,
+    ...(site.previousKey && (site.previousUntil ?? 0) > Date.now() ? [site.previousKey] : []),
+];
+/**
+ * Whether the key a session was opened with is still accepted. A key replaced at once, or
+ * whose 24 hours are over or were ended early, takes its sessions with it, so a leaked key
+ * is no use to whoever already opened a session with it. A session from before sessions
+ * named their key has none, and lasts its hour.
+ */
+const keyAccepted = (site, session) => session.signer === undefined || accepted(site).some((key) => hash(key) === session.signer);
+/**
+ * The payload of a token signed by one of the site's accepted keys, and the hash of the
+ * key that signed it.
+ */
+function verified(site, token) {
+    for (const key of accepted(site)) {
+        const payload = open(key, token);
+        if (payload)
+            return { payload, signer: hash(key) };
+    }
+    return undefined;
+}
 const string = (value, max = 500) => typeof value === 'string' && value.length > 0 && value.length <= max;
 /**
  * The subject a handoff vouches for, as the library will hold it, or undefined if the
@@ -143,17 +188,228 @@ function subject(site, payload, validate) {
  */
 export class Sites {
     storage;
+    pinned;
+    /**
+     * Every site served: the pinned ones, then the ones kept in the store, as `refresh()`
+     * last read them.
+     */
     sites;
-    constructor(storage, sites) {
+    /**
+     * Stored sites whose DNS no longer names this instance, or that the owner suspended. They
+     * start nothing new, but their backends can still read their connections, so they can
+     * move elsewhere.
+     */
+    suspended = new Set();
+    /** What the instance owner has set for each stored site, as `refresh()` last read it. */
+    controls = new Map();
+    /**
+     * `pinned` are the sites the host configures, from `SITES`. They cannot be changed here,
+     * and a stored site with the same id or origin is not served.
+     */
+    constructor(storage, pinned) {
         this.storage = storage;
+        this.pinned = pinned;
+        this.sites = new Map(pinned);
+    }
+    /**
+     * Reads the stored sites again. The instance does this on every request, so a site
+     * registered, changed or removed by another process is served as it now is.
+     */
+    async refresh() {
+        const sites = new Map(this.pinned);
+        const origins = new Set([...this.pinned.values()].map((site) => site.origin));
+        for (const [, site] of await this.storage.list(registeredPrefix)) {
+            if (sites.has(site.id) || origins.has(site.origin))
+                continue;
+            sites.set(site.id, site);
+            origins.add(site.origin);
+        }
+        const suspended = new Set();
+        const controls = new Map();
+        for (const [key, set] of await this.storage.list(controlsPrefix)) {
+            const id = key.slice(controlsPrefix.length);
+            controls.set(id, set);
+            if (set.suspendedAt !== undefined && !this.pinned.has(id))
+                suspended.add(id);
+        }
+        for (const [key, check] of await this.storage.list(dnsPrefix)) {
+            const id = key.slice(dnsPrefix.length);
+            if (check.absentSince !== undefined && !this.pinned.has(id))
+                suspended.add(id);
+        }
         this.sites = sites;
+        this.suspended = suspended;
+        this.controls = controls;
+    }
+    /** The sites the host configures in `SITES`. */
+    configured() {
+        return [...this.pinned.values()];
+    }
+    /** The sites kept in the store and served, which are the ones whose DNS is checked. */
+    stored() {
+        return [...this.sites.values()].filter((site) => !this.pinned.has(site.id));
+    }
+    /**
+     * Requests a minute for a site, counted once for its holders and once for its backend's
+     * reads. Undefined for a pinned site, which gets the instance's default.
+     */
+    limit(id) {
+        if (this.pinned.has(id))
+            return undefined;
+        return this.controls.get(id)?.limit ?? limits.registered;
+    }
+    /**
+     * The provider ids a site's holders may use, from those the instance `offers`. A stored
+     * site goes without YouTube until the owner approves it. Undefined means every one.
+     */
+    providers(site, offers) {
+        const held = this.withheld(site.id);
+        return held.length
+            ? (site.providers ?? offers).filter((id) => !held.includes(id))
+            : site.providers;
+    }
+    /**
+     * The provider ids the owner has not approved a site for, whichever its operators chose.
+     * None for a pinned site.
+     */
+    withheld(id) {
+        return this.pinned.has(id) || this.controls.get(id)?.youtubeApprovedAt ? [] : approvalNeeded;
+    }
+    /** Changes what the instance owner has set for a stored site. */
+    async control(id, change) {
+        if (this.pinned.has(id))
+            throw new Error(`Site ${id} is set by the host`);
+        await this.storage.transaction(async (tx) => {
+            if (!(await tx.get(`${registeredPrefix}${id}`)))
+                throw new Error(`Site ${id} is not registered`);
+            const key = `${controlsPrefix}${id}`;
+            await tx.put(key, change((await tx.get(key)) ?? {}));
+        });
+        await this.refresh();
+    }
+    /** A site that may start something new: served, and not suspended. */
+    active(id) {
+        return this.suspended.has(id) ? undefined : this.sites.get(id);
+    }
+    /**
+     * Keeps a new site in the store with its first operator. Refused if the entry is
+     * malformed, or its origin belongs to another site, or its id is in use or has ever been.
+     */
+    async register(site, first) {
+        const entry = { ...checked(site), key: site.key };
+        if (!validKey(entry.key))
+            throw new Error(`Site ${entry.id} needs a base64url key`);
+        if (this.pinned.has(entry.id))
+            throw new Error(`Site ${entry.id} is set by the host`);
+        await this.storage.transaction(async (tx) => {
+            if ((await tx.get(`${registeredPrefix}${entry.id}`)) ||
+                (await tx.get(`${retiredPrefix}${entry.id}`)))
+                throw new Error(`The id ${entry.id} is taken`);
+            for (const [, other] of [
+                ...this.pinned.entries(),
+                ...(await tx.list(registeredPrefix)),
+            ])
+                if (other.origin === entry.origin)
+                    throw new Error(`${entry.origin} is already registered`);
+            await tx.put(`${registeredPrefix}${entry.id}`, entry);
+            await tx.put(`${operatorsPrefix}${entry.id}`, [first]);
+        });
+        await this.refresh();
+    }
+    /**
+     * Changes a stored site's settings. The rest of the site, its keys above all, is read in
+     * the same transaction and kept as it is, so a change made from a page loaded before a
+     * key was replaced cannot bring the old key back. Refused if the result is malformed.
+     */
+    async update(id, settings) {
+        if (this.pinned.has(id))
+            throw new Error(`Site ${id} is set by the host`);
+        await this.storage.transaction(async (tx) => {
+            const stored = await tx.get(`${registeredPrefix}${id}`);
+            if (!stored)
+                throw new Error(`Site ${id} is not registered`);
+            const { key, previousKey, previousUntil, providers, visibility, ...rest } = stored;
+            const changed = checked({
+                ...rest,
+                authorizeUrl: settings.authorizeUrl,
+                returnUrl: settings.returnUrl,
+                ...(settings.providers ? { providers: settings.providers } : {}),
+                ...(settings.visibility ? { visibility: settings.visibility } : {}),
+            });
+            await tx.put(`${registeredPrefix}${id}`, {
+                ...changed,
+                key,
+                ...(previousKey && previousUntil ? { previousKey, previousUntil } : {}),
+            });
+        });
+        await this.refresh();
+    }
+    /**
+     * Gives a stored site a new key and returns it. With `keep`, the old key is still
+     * accepted for `rotationMs`, for a routine change. Without it, the old key stops working
+     * at once, for a key that may have leaked. Any key before the old one stops either way.
+     *
+     * With `from`, the hash of the key the caller saw, nothing changes unless that is still
+     * the site's key, so a form sent twice replaces the key once. Returns undefined then.
+     */
+    async rotate(id, keep, from) {
+        const key = secret();
+        const replaced = await this.storage.transaction(async (tx) => {
+            const stored = await tx.get(`${registeredPrefix}${id}`);
+            if (!stored)
+                throw new Error(`Site ${id} is not registered`);
+            if (from !== undefined && hash(stored.key) !== from)
+                return false;
+            const { previousKey, previousUntil, ...site } = stored;
+            await tx.put(`${registeredPrefix}${id}`, {
+                ...site,
+                key,
+                ...(keep ? { previousKey: stored.key, previousUntil: Date.now() + rotationMs } : {}),
+            });
+            return true;
+        });
+        await this.refresh();
+        return replaced ? key : undefined;
+    }
+    /** Stops accepting a stored site's previous key, once the new one is deployed. */
+    async retirePreviousKey(id) {
+        await this.storage.transaction(async (tx) => {
+            const stored = await tx.get(`${registeredPrefix}${id}`);
+            if (!stored)
+                throw new Error(`Site ${id} is not registered`);
+            const { previousKey, previousUntil, ...site } = stored;
+            await tx.put(`${registeredPrefix}${id}`, site);
+        });
+        await this.refresh();
+    }
+    /**
+     * Removes a stored site with its operators, DNS state and owner's controls, and keeps its
+     * id so no other site is ever given it. Its users' records stay, but their site starts nothing new.
+     */
+    async retire(id, reason) {
+        if (this.pinned.has(id))
+            throw new Error(`Site ${id} is set by the host`);
+        await this.storage.transaction(async (tx) => {
+            if (!(await tx.get(`${registeredPrefix}${id}`)))
+                throw new Error(`Site ${id} is not registered`);
+            await tx.put(`${retiredPrefix}${id}`, { retiredAt: Date.now(), reason });
+            await tx.delete(`${registeredPrefix}${id}`);
+            await tx.delete(`${operatorsPrefix}${id}`);
+            await tx.delete(`${dnsPrefix}${id}`);
+            await tx.delete(`${controlsPrefix}${id}`);
+        });
+        await this.refresh();
+    }
+    /** The operators of a stored site. */
+    async operators(id) {
+        return (await this.storage.get(`${operatorsPrefix}${id}`)) ?? [];
     }
     /**
      * Starts a handoff: a state stored with the site and purpose, set in this browser, and
      * sent to the site to sign into its token. Returns where to go and the cookie to set.
      */
     async begin(site, purpose) {
-        const registered = this.sites.get(site ?? '');
+        const registered = this.active(site ?? '');
         if (!registered || !['connect', 'manage'].includes(purpose ?? ''))
             return undefined;
         const state = secret();
@@ -172,12 +428,12 @@ export class Sites {
      * check of the subject, which the union of every site's origin would not make alone.
      */
     async start(request, token, validate) {
-        const site = this.sites.get(String(peek(token)?.site ?? ''));
+        const site = this.active(String(peek(token)?.site ?? ''));
         if (!site)
             return undefined;
-        const payload = open(site.key, token);
+        const { payload, signer } = verified(site, token) ?? {};
         const now = Date.now();
-        const held = cookie(request, stateCookie);
+        const held = readCookie(request, stateCookie);
         if (!payload ||
             payload.site !== site.id ||
             typeof payload.exp !== 'number' ||
@@ -207,6 +463,7 @@ export class Sites {
                 txn,
                 local,
                 expiresAt: now + sessionMs,
+                signer,
             });
             return state.purpose;
         });
@@ -231,10 +488,10 @@ export class Sites {
      * not admitted is 'limited', and is not used up.
      */
     async dialog(token, origin, validate, admit) {
-        const site = this.sites.get(String(peek(token)?.site ?? ''));
+        const site = this.active(String(peek(token)?.site ?? ''));
         if (!site || origin !== site.origin)
             return undefined;
-        const payload = open(site.key, token);
+        const { payload, signer } = verified(site, token) ?? {};
         const now = Date.now();
         if (!payload ||
             payload.site !== site.id ||
@@ -264,6 +521,7 @@ export class Sites {
                 local,
                 expiresAt: now + sessionMs,
                 dialog: true,
+                signer,
             });
             return true;
         });
@@ -279,7 +537,7 @@ export class Sites {
         const site = this.sites.get(String(peek(token)?.site ?? ''));
         if (!site)
             return undefined;
-        const payload = open(site.key, token);
+        const payload = verified(site, token)?.payload;
         const now = Date.now();
         if (!payload ||
             payload.site !== site.id ||
@@ -296,12 +554,13 @@ export class Sites {
     }
     /** This browser's site session, whether or not it has returned yet. */
     async session(request) {
-        const token = cookie(request, sessionCookie);
+        const token = readCookie(request, sessionCookie);
         if (!token)
             return undefined;
         const key = `site/session/${hash(token)}`;
         const session = await this.storage.get(key);
-        if (!session || expired(session, Date.now()) || !this.sites.has(session.site))
+        const site = session && this.sites.get(session.site);
+        if (!session || !site || expired(session, Date.now()) || !keyAccepted(site, session))
             return undefined;
         return { key, session };
     }
@@ -312,7 +571,12 @@ export class Sites {
      */
     async open(request) {
         const found = await this.session(request);
-        return found && !found.session.closed && !found.session.operation ? found : undefined;
+        return found &&
+            !found.session.closed &&
+            !found.session.operation &&
+            !this.suspended.has(found.session.site)
+            ? found
+            : undefined;
     }
     /**
      * Where a flow that ended goes, as a function of the stored result alone: the same
@@ -326,9 +590,14 @@ export class Sites {
             return undefined;
         if (!['connect', 'renew', 'visibility'].includes(result.kind))
             return undefined;
+        const session = context.session?.startsWith('site/session/')
+            ? await this.storage.get(context.session)
+            : undefined;
         // The sign-in window of a dialog shows the flow's own result page and goes nowhere.
-        if (context.session?.startsWith('site/session/') &&
-            (await this.storage.get(context.session))?.dialog)
+        if (session?.dialog)
+            return undefined;
+        // Nothing is signed for a session whose key has since been withdrawn.
+        if (session && !keyAccepted(site, session))
             return undefined;
         // Another flow's return, or a disconnect, already speaks for this transaction. This
         // flow ended all the same, however it ended, and its holder sees the result page.
@@ -340,7 +609,7 @@ export class Sites {
             connection: result.connectionId,
             visibility: result.visibility,
             finishedAt: result.finishedAt,
-        });
+        }, session?.signer);
     }
     /**
      * Takes the session's one return for a flow, and closes the session with it. A site
@@ -362,12 +631,16 @@ export class Sites {
             return true;
         });
     }
-    /** The signed result a holder carries back to their site. */
-    returnUrl(site, local, txn, result) {
+    /**
+     * The signed result a holder carries back to their site, under the key that opened its
+     * session while that key is still accepted, and under the site's key otherwise.
+     */
+    returnUrl(site, local, txn, result, signer) {
         if (!local.id.startsWith(`${site.id}:`))
             throw new Error('Subject from another site');
         const complete = result.outcome === 'complete';
-        const token = sign(site.key, {
+        const key = accepted(site).find((candidate) => hash(candidate) === signer) ?? site.key;
+        const token = sign(key, {
             site: site.id,
             id: local.id.slice(site.id.length + 1),
             operation: result.operation,