@bkazemi/verily 0.7.0 → 0.8.0

package/dist/instance/init.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Writes the Cloudflare starter into a directory, all of it or none. If any of its files
+ * is already there, nothing is written. If a write fails partway, the files this call
+ * made are removed, so a second try starts from the same place.
+ */
+export declare function init(directory: string): Promise<void>;

package/dist/instance/init.js

@@ -0,0 +1,28 @@
+import { mkdir, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { cloudflareStarter } from './starter.js';
+/**
+ * Writes the Cloudflare starter into a directory, all of it or none. If any of its files
+ * is already there, nothing is written. If a write fails partway, the files this call
+ * made are removed, so a second try starts from the same place.
+ */
+export async function init(directory) {
+    const files = Object.entries(cloudflareStarter).map(([name, text]) => [join(directory, name), text]);
+    await mkdir(directory, { recursive: true });
+    for (const [path] of files)
+        if (await stat(path).catch(() => undefined))
+            throw new Error(`${path} already exists. Nothing was written.`);
+    const made = [];
+    try {
+        for (const [path, text] of files) {
+            // `wx` fails on a file that appeared since the check, so it is never overwritten.
+            await writeFile(path, text, { flag: 'wx' });
+            made.push(path);
+        }
+    }
+    catch (error) {
+        for (const path of made)
+            await rm(path, { force: true });
+        throw error;
+    }
+}

package/dist/instance/limits.d.ts

@@ -0,0 +1,30 @@
+import type { Store } from './store.js';
+/**
+ * Requests a minute for one signed-in holder, one client without a session, one site's
+ * holders, and one site's backend reading its subjects' connections.
+ */
+export declare const limits: {
+    session: number;
+    client: number;
+    site: number;
+    read: number;
+};
+/**
+ * Counts a request against every bucket it falls in, and refuses it if any is full. All or
+ * nothing, in one transaction, so a refused request spends nothing from the others.
+ */
+export declare function allow(storage: Store, buckets: {
+    key: string;
+    limit: number;
+}[]): Promise<boolean>;
+/**
+ * The bucket for a client with no session, by the address the host says the request came
+ * from. The address is hashed, never stored as it is.
+ */
+export declare const client: (address: string | null) => string;
+/**
+ * Deletes every record the handoff and the limits leave behind once it has expired:
+ * handoffs that never reached `/handoff/accept`, site sessions, and idle buckets. Each is written
+ * with its expiry under its own prefix for exactly this.
+ */
+export declare function prune(storage: Store): Promise<void>;

package/dist/instance/limits.js

@@ -0,0 +1,45 @@
+import { hash } from '../server/service.js';
+/**
+ * Requests a minute for one signed-in holder, one client without a session, one site's
+ * holders, and one site's backend reading its subjects' connections.
+ */
+export const limits = { session: 60, client: 30, site: 600, read: 600 };
+const windowMs = 60000;
+/**
+ * Counts a request against every bucket it falls in, and refuses it if any is full. All or
+ * nothing, in one transaction, so a refused request spends nothing from the others.
+ */
+export async function allow(storage, buckets) {
+    return storage.transaction(async (tx) => {
+        const now = Date.now();
+        const next = [];
+        for (const { key, limit } of buckets) {
+            const previous = await tx.get(`rate/${key}`);
+            const bucket = previous && previous.expiresAt > now ? previous : { count: 0, expiresAt: now + windowMs };
+            if (bucket.count >= limit)
+                return false;
+            next.push([`rate/${key}`, { ...bucket, count: bucket.count + 1 }]);
+        }
+        for (const [key, bucket] of next)
+            await tx.put(key, bucket);
+        return true;
+    });
+}
+/**
+ * The bucket for a client with no session, by the address the host says the request came
+ * from. The address is hashed, never stored as it is.
+ */
+export const client = (address) => `client/${hash(address ?? 'unknown')}`;
+/**
+ * Deletes every record the handoff and the limits leave behind once it has expired:
+ * handoffs that never reached `/handoff/accept`, site sessions, and idle buckets. Each is written
+ * with its expiry under its own prefix for exactly this.
+ */
+export async function prune(storage) {
+    const now = Date.now();
+    for (const prefix of ['site/state/', 'site/session/', 'rate/']) {
+        for (const [key, value] of await storage.list(prefix))
+            if (!(value.expiresAt > now))
+                await storage.delete(key);
+    }
+}

package/dist/instance/node.d.ts

@@ -0,0 +1,13 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Instance } from './index.js';
+export interface ListenerOptions {
+    /** The origin the instance is served from, as given to `createInstance`. */
+    origin: string;
+    /**
+     * The client's address, which rate limits count by. The socket's by default. Behind a
+     * proxy every request comes from the proxy, so read the header that proxy sets instead.
+     */
+    address?(request: IncomingMessage): string | null;
+}
+/** Serves an instance from `node:http`: `createServer(nodeListener(instance, { origin }))`. */
+export declare function nodeListener(instance: Pick<Instance, 'handle'>, options: ListenerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/dist/instance/node.js

@@ -0,0 +1,43 @@
+/** The instance's own bound on a body. A larger one is refused before it is buffered. */
+const maxBodyBytes = 65536;
+/** Serves an instance from `node:http`: `createServer(nodeListener(instance, { origin }))`. */
+export function nodeListener(instance, options) {
+    const address = options.address ?? ((request) => request.socket.remoteAddress ?? null);
+    return async (req, res) => {
+        try {
+            const chunks = [];
+            let length = 0;
+            for await (const chunk of req) {
+                length += chunk.length;
+                if (length > maxBodyBytes) {
+                    res.writeHead(413, { 'Cache-Control': 'no-store' });
+                    res.end();
+                    return;
+                }
+                chunks.push(Buffer.from(chunk));
+            }
+            const headers = new Headers();
+            for (const [key, value] of Object.entries(req.headers))
+                if (value)
+                    headers.set(key, Array.isArray(value) ? value.join(', ') : value);
+            const response = await instance.handle(new Request(new URL(req.url ?? '/', options.origin), {
+                method: req.method,
+                headers,
+                ...(chunks.length ? { body: Buffer.concat(chunks) } : {}),
+            }), address(req));
+            // Each cookie is a header of its own: joined into one, a browser keeps only the first.
+            const cookies = response.headers.getSetCookie();
+            response.headers.delete('Set-Cookie');
+            res.writeHead(response.status, {
+                ...Object.fromEntries(response.headers),
+                ...(cookies.length ? { 'Set-Cookie': cookies } : {}),
+            });
+            res.end(Buffer.from(await response.arrayBuffer()));
+        }
+        catch {
+            if (!res.headersSent)
+                res.writeHead(500, { 'Cache-Control': 'no-store' });
+            res.end('Request failed');
+        }
+    };
+}

package/dist/instance/page.d.ts

@@ -0,0 +1,18 @@
+export declare const safeHeaders: {
+    'Cache-Control': string;
+    'Referrer-Policy': string;
+    'X-Robots-Tag': string;
+    'X-Content-Type-Options': string;
+    'Content-Security-Policy': string;
+};
+/**
+ * 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;
+/**
+ * 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 declare const unavailable: (status?: number) => Response;

package/dist/instance/page.js

@@ -0,0 +1,30 @@
+import { page } from '../server/render.js';
+export const safeHeaders = {
+    'Cache-Control': 'no-store',
+    'Referrer-Policy': 'same-origin',
+    'X-Robots-Tag': 'noindex, nofollow',
+    'X-Content-Type-Options': 'nosniff',
+    'Content-Security-Policy': "default-src 'none'; style-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'self'",
+};
+/**
+ * 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), {
+    status,
+    headers: {
+        ...safeHeaders,
+        'Content-Type': 'text/html; charset=utf-8',
+        ...(script
+            ? {
+                'Content-Security-Policy': safeHeaders['Content-Security-Policy'].replace("style-src 'self';", "style-src 'self'; script-src 'self';"),
+            }
+            : {}),
+    },
+});
+/**
+ * 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');

package/dist/instance/postgres.d.ts

@@ -0,0 +1,19 @@
+import type { Pool } from 'pg';
+import type { KeyValue, Store } from './store.js';
+/**
+ * An instance store on Postgres, in one table of its own. Several installations can share
+ * a database, each under its own namespace.
+ */
+export declare class PostgresStore implements Store {
+    readonly pool: Pool;
+    readonly namespace: string;
+    constructor(pool: Pool, namespace?: string);
+    /** Creates the table. Safe to run on every start, and from several processes at once. */
+    migrate(): Promise<void>;
+    get: KeyValue['get'];
+    put: KeyValue['put'];
+    delete: KeyValue['delete'];
+    list: KeyValue['list'];
+    transaction<T>(work: (tx: KeyValue) => Promise<T>): Promise<T>;
+    private operations;
+}

package/dist/instance/postgres.js

@@ -0,0 +1,83 @@
+/**
+ * An instance store on Postgres, in one table of its own. Several installations can share
+ * a database, each under its own namespace.
+ */
+export class PostgresStore {
+    pool;
+    namespace;
+    constructor(pool, namespace = 'verily') {
+        this.pool = pool;
+        this.namespace = namespace;
+        if (!namespace)
+            throw new Error('Store namespace required');
+    }
+    /** Creates the table. Safe to run on every start, and from several processes at once. */
+    async migrate() {
+        const client = await this.pool.connect();
+        try {
+            await client.query('BEGIN');
+            // IF NOT EXISTS does not make CREATE TABLE safe to race, so one process at a time.
+            await client.query("SELECT pg_advisory_xact_lock(hashtextextended('verily migrate', 0))");
+            await client.query(`CREATE TABLE IF NOT EXISTS verily_instance (
+        namespace text NOT NULL, key text NOT NULL, value jsonb NOT NULL,
+        PRIMARY KEY (namespace, key)
+      )`);
+            await client.query('COMMIT');
+        }
+        catch (error) {
+            await client.query('ROLLBACK');
+            throw error;
+        }
+        finally {
+            client.release();
+        }
+    }
+    get = (key) => this.operations(this.pool).get(key);
+    put = (key, value) => this.operations(this.pool).put(key, value);
+    delete = (key) => this.operations(this.pool).delete(key);
+    list = (prefix) => this.operations(this.pool).list(prefix);
+    async transaction(work) {
+        const client = await this.pool.connect();
+        try {
+            await client.query('BEGIN');
+            // One transaction at a time for this installation, across every process serving it.
+            await client.query('SELECT pg_advisory_xact_lock(hashtextextended($1, 0))', [
+                `instance ${this.namespace}`,
+            ]);
+            const result = await work(this.operations(client));
+            await client.query('COMMIT');
+            return result;
+        }
+        catch (error) {
+            await client.query('ROLLBACK');
+            throw error;
+        }
+        finally {
+            client.release();
+        }
+    }
+    operations(db) {
+        const namespace = this.namespace;
+        return {
+            async get(key) {
+                const result = await db.query('SELECT value FROM verily_instance WHERE namespace=$1 AND key=$2', [namespace, key]);
+                return result.rows[0]?.value;
+            },
+            async put(key, value) {
+                await db.query(`INSERT INTO verily_instance(namespace,key,value) VALUES($1,$2,$3)
+          ON CONFLICT(namespace,key) DO UPDATE SET value=EXCLUDED.value`, [namespace, key, JSON.stringify(value)]);
+            },
+            async delete(key) {
+                await db.query('DELETE FROM verily_instance WHERE namespace=$1 AND key=$2', [
+                    namespace,
+                    key,
+                ]);
+            },
+            async list(prefix) {
+                const result = await db.query(`SELECT key, value FROM verily_instance
+          WHERE namespace=$1 AND starts_with(key, $2) ORDER BY key COLLATE "C"`, [namespace, prefix]);
+                return result.rows.map((row) => [row.key, row.value]);
+            },
+        };
+    }
+}

package/dist/instance/routes.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The paths the instance answers itself. The library is mounted at the root of the origin
+ * and answers every other path, so a path listed here must be one the library does not
+ * serve: the instance looks here first, and a library route of the same name would never be
+ * reached.
+ */
+export declare const own: Set<string>;

package/dist/instance/routes.js

@@ -0,0 +1,22 @@
+/**
+ * The paths the instance answers itself. The library is mounted at the root of the origin
+ * and answers every other path, so a path listed here must be one the library does not
+ * serve: the instance looks here first, and a library route of the same name would never be
+ * reached.
+ */
+export const own = new Set([
+    '/',
+    '/login',
+    '/logout',
+    '/disconnect',
+    '/mark',
+    '/confirm',
+    '/records',
+    '/handoff/request',
+    '/handoff/accept',
+    '/site/connections',
+    '/site/enter',
+    '/site/enter.js',
+    '/site/session',
+    '/.well-known/verily-keys.json',
+]);

package/dist/instance/serve.d.ts

@@ -0,0 +1,31 @@
+import { type Server } from 'node:http';
+import { type InstanceEnv } from './env.js';
+import type { Store } from './store.js';
+/** What the Node server reads besides the instance's own settings. */
+export interface ServeEnv extends InstanceEnv {
+    /** A Postgres connection string. The instance keeps everything in one table there. */
+    DATABASE_URL?: string;
+    /** Separates installations sharing a database. `verily` by default. */
+    VERILY_NAMESPACE?: string;
+    /** 3000 by default. */
+    PORT?: string;
+    /** 127.0.0.1 by default, for a proxy on the same machine that terminates TLS. */
+    HOST?: string;
+    /**
+     * The header a proxy in front sets to the client's address, such as `X-Real-IP`. Rate
+     * limits count by it. It must be one the proxy sets outright: a header a client can add
+     * to, as `X-Forwarded-For` usually is, lets a client pick the address it is counted as.
+     * Left out, the address is the connection's, which behind a proxy is the proxy's.
+     */
+    CLIENT_ADDRESS_HEADER?: string;
+}
+/**
+ * Runs an instance on Node from its settings: Postgres for the store, plain HTTP for a
+ * proxy to sit in front of, and upkeep once an hour. Resolves once it is listening.
+ */
+export declare function serve(env: ServeEnv, 
+/** A store to use instead of Postgres. */
+given?: Store): Promise<{
+    server: Server;
+    close(): Promise<void>;
+}>;

package/dist/instance/serve.js

@@ -0,0 +1,49 @@
+import { createServer } from 'node:http';
+import { Pool } from 'pg';
+import { createInstance } from './index.js';
+import { fromEnv } from './env.js';
+import { nodeListener } from './node.js';
+import { PostgresStore } from './postgres.js';
+const hour = 3600000;
+/**
+ * Runs an instance on Node from its settings: Postgres for the store, plain HTTP for a
+ * proxy to sit in front of, and upkeep once an hour. Resolves once it is listening.
+ */
+export async function serve(env, 
+/** A store to use instead of Postgres. */
+given) {
+    const options = fromEnv(env);
+    let store = given;
+    let pool;
+    if (!store) {
+        if (!env.DATABASE_URL)
+            throw new Error('DATABASE_URL must be set');
+        pool = new Pool({ connectionString: env.DATABASE_URL });
+        const postgres = new PostgresStore(pool, env.VERILY_NAMESPACE || 'verily');
+        await postgres.migrate();
+        store = postgres;
+    }
+    const instance = createInstance({ ...options, store });
+    const header = env.CLIENT_ADDRESS_HEADER?.toLowerCase();
+    const server = createServer(nodeListener(instance, {
+        origin: options.origin,
+        ...(header
+            ? { address: (request) => String(request.headers[header] ?? '').trim() || null }
+            : {}),
+    }));
+    const upkeep = () => void instance.upkeep().catch(() => console.error('Verily upkeep failed'));
+    const timer = setInterval(upkeep, hour);
+    upkeep();
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(Number(env.PORT || 3000), env.HOST || '127.0.0.1', resolve);
+    });
+    return {
+        server,
+        async close() {
+            clearInterval(timer);
+            await new Promise((resolve) => server.close(resolve));
+            await pool?.end();
+        },
+    };
+}

package/dist/instance/sites.d.ts

@@ -0,0 +1,169 @@
+import { type FlowResult, type LocalAccount, type Visibility } from '../core/index.js';
+import type { Store } from './store.js';
+/** How long a handoff may take, from `/handoff/request` to `/handoff/accept`, and how far ahead a token may run. */
+export declare const handoffMs: number;
+/** How long a site session lasts once the handoff lands. */
+export declare const sessionMs = 3600000;
+export declare const sessionCookie = "verily_site";
+/** A site that sends its users here instead of hosting Verily itself. */
+export interface Site {
+    /** Prefixes its subjects' ids, and names it in every token. */
+    id: string;
+    /** The site name stamped on its subjects. */
+    name: string;
+    origin: string;
+    /** The site's endpoint that signs a handoff for its signed-in user. */
+    authorizeUrl: string;
+    /** Where a holder is sent back to when a flow ends. */
+    returnUrl: string;
+    /** Shared with the site's backend. Signs handoffs one way and results the other. */
+    key: string;
+    /** The provider ids its holders may use. Absent means every one this instance offers. */
+    providers?: string[];
+    /** The visibilities its holders may choose. Absent means both. */
+    visibility?: Visibility[];
+}
+export type Purpose = 'connect' | 'manage';
+/** How a holder may have an account listed, as the library's mark route takes it. */
+export type Listing = 'preferred' | 'current' | 'unused' | 'retired';
+/**
+ * What the instance holds for a disconnect or a mark, which have no flow of their own to
+ * hold it.
+ */
+interface Operation {
+    connection: string;
+    visibility?: Visibility;
+    /** How the account is to be listed, for a mark. Absent, the operation is a disconnect. */
+    mark?: Listing;
+    /** Set once the change has committed. Until then the operation is pending. */
+    finishedAt?: number;
+}
+export interface SiteSession {
+    site: string;
+    purpose: Purpose;
+    txn: string;
+    local: LocalAccount;
+    expiresAt: number;
+    /** Set by the first return. Nothing new can start after it, but a retry still resolves. */
+    closed?: boolean;
+    /** The flow whose result this session returned with. No other flow's result is signed. */
+    returned?: string;
+    operation?: Operation;
+    /**
+     * Opened for the dialog on the site's own page, which reads how each flow ended for
+     * itself. No flow returns to the site from it, so no flow's end closes it, and the
+     * holder can try again in the same dialog.
+     */
+    dialog?: true;
+}
+/**
+ * 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
+ * half set up. A site whose key is missing or malformed is left out instead.
+ */
+export declare function registry(config: unknown, secrets: Record<string, unknown>): Map<string, Site>;
+/** `base64url(payload) + "." + base64url(HMAC-SHA256(key, payload))`, the payload being JSON. */
+export declare function sign(key: string, payload: object): string;
+/** The payload of a token, without checking it. Only good for choosing which key checks it. */
+export declare function peek(token: string): Record<string, unknown> | undefined;
+/** The payload of a token whose MAC verifies under `key`, compared in constant time. */
+export declare function open(key: string, token: string): Record<string, unknown> | undefined;
+/**
+ * Handoffs from registered sites, the sessions they open, and the results sent back. The
+ * site vouches for its signed-in user; this is where that is checked, and a handoff is
+ * bound to the browser that asked for it, the way OAuth binds a callback with `state`.
+ */
+export declare class Sites {
+    private readonly storage;
+    readonly sites: Map<string, Site>;
+    constructor(storage: Store, sites: Map<string, Site>);
+    /**
+     * 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.
+     */
+    begin(site: string | null, purpose: string | null): Promise<{
+        location: string;
+        cookie: string;
+    } | undefined>;
+    /**
+     * Redeems a signed handoff for a session, or refuses it. Every refusal is the same
+     * undefined, so a caller cannot tell which check failed. `validate` is the library's own
+     * check of the subject, which the union of every site's origin would not make alone.
+     */
+    start(request: Request, token: string, validate: (local: LocalAccount) => LocalAccount): Promise<{
+        purpose: Purpose;
+        cookies: string[];
+    } | undefined>;
+    /**
+     * Redeems a handoff a site's own page presents, for the connect dialog on that page, and
+     * returns the session it opens. There is no redirect to bind with a state. The site's
+     * backend gave the token to its signed-in user's page, and a browser sends that page's
+     * origin with the request, so the token is marked for this use, taken only from the
+     * site's origin, and works once. The session is the same as a redirect opens, carried by
+     * the page in a header because the cookie would be another site's on that page.
+     *
+     * `admit` counts the handoff against the site that signed it, and is asked only once it
+     * has verified, before anything is stored: the request has no cookie to say whose it is,
+     * and a token that does not verify must spend nothing of the site it names. A handoff
+     * not admitted is 'limited', and is not used up.
+     */
+    dialog(token: string, origin: string | null, validate: (local: LocalAccount) => LocalAccount, admit: (site: Site) => Promise<boolean>): Promise<{
+        site: Site;
+        session: string;
+    } | 'limited' | undefined>;
+    /**
+     * Checks a site backend's request to read its own subjects' connections: a token under
+     * that site's key, marked as a read so that a handoff token, which passes through a
+     * browser, is never one. The ids are the site's own, as it sends them in a handoff, and
+     * are only ever looked up under its prefix, so no site reaches another's subjects.
+     */
+    read(token: string): {
+        site: Site;
+        ids: string[];
+    } | undefined;
+    /** This browser's site session, whether or not it has returned yet. */
+    session(request: Request): Promise<{
+        key: string;
+        session: SiteSession;
+    } | undefined>;
+    /**
+     * A session that can still start something: not yet returned, and not partway through a
+     * disconnect. A pending disconnect holds the session's one result, so nothing else may
+     * start that could end with another; only retrying that disconnect goes on.
+     */
+    open(request: Request): Promise<{
+        key: string;
+        session: SiteSession;
+    } | undefined>;
+    /**
+     * Where a flow that ended goes, as a function of the stored result alone: the same
+     * result signs the same token, since its expiry is counted from when the flow ended.
+     * Only the registry says where a site's holders return, and the first return closes the
+     * session to anything new.
+     */
+    finish(flow: string, context: Record<string, string> | undefined, local: LocalAccount | undefined, result: FlowResult): Promise<string | undefined>;
+    /**
+     * Takes the session's one return for a flow, and closes the session with it. A site
+     * accepts one result for a transaction, so only one is ever signed: the first flow to end
+     * holds the return, every load of that flow holds it again, and no flow gets it once a
+     * disconnect is recorded, pending or done. Decided in one transaction, as `pending` is,
+     * so of a flow ending and a disconnect starting exactly one goes on.
+     */
+    private claim;
+    /** The signed result a holder carries back to their site. */
+    returnUrl(site: Site, local: LocalAccount, txn: string, result: {
+        operation: string;
+        outcome: string;
+        connection?: string;
+        visibility?: Visibility;
+        finishedAt: number;
+    }): string;
+    /**
+     * Records a disconnect or a mark as pending on the session before anything is changed, so
+     * a retry knows what it is finishing. A session already carrying one only resumes that one.
+     */
+    pending(key: string, connection: string, visibility: Visibility, mark?: Listing): Promise<SiteSession | undefined>;
+    /** Records an operation as done once its change has committed, and closes the session. */
+    completed(key: string): Promise<SiteSession>;
+}
+export {};