@bkazemi/verily 0.6.0 → 0.8.0

package/dist/instance/auth.d.ts

@@ -0,0 +1,14 @@
+import type { Store } from './store.js';
+export declare class OwnerAuth {
+    private readonly storage;
+    private readonly ownerKey;
+    constructor(storage: Store, ownerKey: string);
+    private token;
+    authenticated(request: Request): Promise<boolean>;
+    /** Which owner session a request belongs to, by the hash its record is stored under. */
+    session(request: Request): Promise<string | undefined>;
+    login(key: string): Promise<string | undefined>;
+    logout(request: Request): Promise<string>;
+    allow(bucket: 'login', limit: number, windowMs: number): Promise<boolean>;
+    prune(): Promise<void>;
+}

package/dist/instance/auth.js

@@ -0,0 +1,80 @@
+import { timingSafeEqual } from 'node:crypto';
+import { expired } from '../core/index.js';
+import { hash, secret } from '../server/service.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
+// browsers or privacy extensions on workers.dev.
+const cookieName = 'verily_owner';
+export class OwnerAuth {
+    storage;
+    ownerKey;
+    constructor(storage, ownerKey) {
+        this.storage = storage;
+        this.ownerKey = ownerKey;
+        if (!/^[A-Za-z0-9_-]{43,}$/.test(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);
+    }
+    async authenticated(request) {
+        return (await this.session(request)) !== undefined;
+    }
+    /** Which owner session a request belongs to, by the hash its record is stored under. */
+    async session(request) {
+        const token = this.token(request);
+        if (!token)
+            return undefined;
+        const session = await this.storage.get(`owner/session/${hash(token)}`);
+        return !!session && session.expiresAt > Date.now() && session.keyHash === hash(this.ownerKey)
+            ? hash(token)
+            : undefined;
+    }
+    async login(key) {
+        if (!timingSafeEqual(Buffer.from(hash(key)), Buffer.from(hash(this.ownerKey))))
+            return;
+        const token = secret();
+        await this.storage.delete('owner/rate/v2/login');
+        await this.storage.put(`owner/session/${hash(token)}`, {
+            expiresAt: Date.now() + sessionMs,
+            keyHash: hash(this.ownerKey),
+        });
+        return `${cookieName}=${token}; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=${sessionMs / 1000}`;
+    }
+    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`;
+    }
+    async allow(bucket, limit, windowMs) {
+        return this.storage.transaction(async (tx) => {
+            const key = `owner/rate/v2/${bucket}`;
+            const previous = await tx.get(key);
+            const next = previous && previous.until > Date.now()
+                ? previous
+                : { count: 0, until: Date.now() + windowMs };
+            if (next.count >= limit)
+                return false;
+            next.count++;
+            await tx.put(key, next);
+            return true;
+        });
+    }
+    async prune() {
+        // One counter for every POST, from before requests were limited per session and client.
+        await this.storage.delete('owner/rate/v2/mutation');
+        await this.storage.transaction(async (tx) => {
+            for (const [key, session] of await tx.list('owner/session/')) {
+                if (expired(session, Date.now()) || session.keyHash !== hash(this.ownerKey))
+                    await tx.delete(key);
+            }
+        });
+    }
+}

package/dist/instance/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/instance/bin.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { serve } from './serve.js';
+import { init } from './init.js';
+const usage = `Usage:
+  verily serve                    Run an instance on Node, from the environment.
+  verily init cloudflare [dir]    Write a Cloudflare project into dir.`;
+/** Writes the starter, then says what to do with it. */
+async function start(directory) {
+    await init(directory);
+    console.log(`Wrote a Cloudflare project to ${directory}
+
+Next, in that directory:
+  1. npm install
+  2. Fill in account_id and the vars in wrangler.jsonc.
+  3. npx wrangler secret put OWNER_KEY
+  4. npm run deploy`);
+}
+const [command, target, directory] = process.argv.slice(2);
+try {
+    if (command === 'serve') {
+        const { server } = await serve(process.env);
+        const { address, port } = server.address();
+        console.log(`Verily instance for ${process.env.PUBLIC_ORIGIN} listening on ${address}:${port}`);
+    }
+    else if (command === 'init' && target === 'cloudflare') {
+        await start(directory ?? '.');
+    }
+    else {
+        console.error(usage);
+        process.exit(command === undefined || command === '--help' || command === '-h' ? 0 : 2);
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+}

package/dist/instance/cloudflare.d.ts

@@ -0,0 +1,57 @@
+import type { Storage } from '../core/index.js';
+import { type Instance } from './index.js';
+import { type InstanceEnv } from './env.js';
+import { type Store } from './store.js';
+/**
+ * The parts of Cloudflare's own types this file uses, written out here so the package
+ * needs none of Cloudflare's to be installed. A Durable Object's real storage, state and
+ * namespace each fit the one below.
+ */
+interface ObjectKeyValue {
+    get<T>(key: string): Promise<T | undefined>;
+    put<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    list<T>(options: {
+        prefix: string;
+    }): Promise<Map<string, T>>;
+}
+export interface ObjectStorage extends ObjectKeyValue {
+    transaction<T>(work: (tx: ObjectKeyValue) => Promise<T>): Promise<T>;
+    getAlarm(): Promise<number | null>;
+    setAlarm(time: number): Promise<void>;
+}
+export interface ObjectState {
+    storage: ObjectStorage;
+    blockConcurrencyWhile<T>(work: () => Promise<T>): Promise<T>;
+}
+interface ObjectNamespace {
+    idFromName(name: string): unknown;
+    get(id: never): {
+        fetch(url: string, init: RequestInit): Promise<Response>;
+    };
+}
+/** The instance's settings, as vars and secrets, and the binding of the object that runs it. */
+export interface Env extends InstanceEnv {
+    VERILY: ObjectNamespace;
+}
+/** A Durable Object's storage as an instance store. It is SQLite-backed, not Workers KV. */
+export declare function cloudflareStore(storage: ObjectStorage): Store;
+/** The library's record storage on a Durable Object, for a Worker that embeds the backend. */
+export declare class CloudflareStorage implements Storage {
+    private readonly records;
+    constructor(storage: ObjectStorage);
+    transaction: Storage['transaction'];
+}
+/** The Worker: turns away what needs no storage, and passes the rest to the one object. */
+declare const _default: {
+    fetch(request: Request, env: Env): Promise<Response>;
+};
+export default _default;
+/** The instance on a Durable Object: its storage, an hourly alarm, and settings from `env`. */
+export declare class VerilyStore {
+    private readonly ctx;
+    protected readonly instance: Instance;
+    constructor(ctx: ObjectState, env: Env);
+    alarm(): Promise<void>;
+    fetch(request: Request): Promise<Response>;
+}

package/dist/instance/cloudflare.js

@@ -0,0 +1,71 @@
+import { admit, createInstance } from './index.js';
+import { fromEnv } from './env.js';
+import { html } from './page.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) => ({
+    get: async (key) => structuredClone(await storage.get(key)),
+    put: (key, value) => storage.put(key, structuredClone(value)),
+    delete: async (key) => {
+        await storage.delete(key);
+    },
+    list: async (prefix) => [...(await storage.list({ prefix })).entries()].map(([key, value]) => [key, structuredClone(value)]),
+});
+/** A Durable Object's storage as an instance store. It is SQLite-backed, not Workers KV. */
+export function cloudflareStore(storage) {
+    return {
+        ...keyValue(storage),
+        transaction: (work) => storage.transaction((tx) => work(keyValue(tx))),
+    };
+}
+/** The library's record storage on a Durable Object, for a Worker that embeds the backend. */
+export class CloudflareStorage {
+    records;
+    constructor(storage) {
+        this.records = recordStorage(cloudflareStore(storage));
+    }
+    transaction = (work) => this.records.transaction(work);
+}
+const hour = 3600000;
+/** The Worker: turns away what needs no storage, and passes the rest to the one object. */
+export default {
+    async fetch(request, env) {
+        // Turned away here, a request never wakes the object.
+        const admitted = await admit(request, env.PUBLIC_ORIGIN);
+        if (admitted instanceof Response)
+            return admitted;
+        try {
+            // One installation, with an identity that survives deployments and hostname changes.
+            return await env.VERILY.get(env.VERILY.idFromName('site-owner')).fetch(admitted.url, {
+                method: admitted.method,
+                headers: Object.fromEntries(admitted.headers),
+                body: admitted.method === 'POST' ? await admitted.arrayBuffer() : undefined,
+                redirect: 'manual',
+            });
+        }
+        catch {
+            return html('Temporarily unavailable', '', 503);
+        }
+    },
+};
+/** The instance on a Durable Object: its storage, an hourly alarm, and settings from `env`. */
+export class VerilyStore {
+    ctx;
+    instance;
+    constructor(ctx, env) {
+        this.ctx = ctx;
+        this.instance = createInstance({ ...fromEnv(env), store: cloudflareStore(ctx.storage) });
+        ctx.blockConcurrencyWhile(async () => {
+            if ((await ctx.storage.getAlarm()) === null)
+                await ctx.storage.setAlarm(Date.now() + hour);
+        });
+    }
+    async alarm() {
+        // Schedule first so transient cleanup failures never permanently stop maintenance.
+        await this.ctx.storage.setAlarm(Date.now() + hour);
+        await this.instance.upkeep();
+    }
+    fetch(request) {
+        return this.instance.handle(request, request.headers.get('cf-connecting-ip'));
+    }
+}

package/dist/instance/env.d.ts

@@ -0,0 +1,51 @@
+import type { LocalKind } from '../core/index.js';
+import type { InstanceOptions } from './index.js';
+/** The settings an instance reads, under the same names on every host. */
+export interface InstanceEnv {
+    /** The origin the instance is served from. HTTPS, with no trailing slash. */
+    PUBLIC_ORIGIN: string;
+    SITE_NAME: string;
+    /** What the owner links: one of their accounts, a page, or the site. Defaults to account. */
+    OWNER_KIND?: LocalKind;
+    OWNER_LABEL: string;
+    OWNER_REFERENCE: string;
+    OWNER_PROFILE_URL: string;
+    /** The secret the owner signs in with: at least 32 random bytes, base64url. */
+    OWNER_KEY: string;
+    REPORT_URL: string;
+    /** GitHub sign-in is offered only when both are set. */
+    GITHUB_CLIENT_ID?: string;
+    GITHUB_CLIENT_SECRET?: string;
+    /** Discord sign-in is offered only when both are set. */
+    DISCORD_CLIENT_ID?: string;
+    DISCORD_CLIENT_SECRET?: string;
+    /** YouTube sign-in is offered only when both are set. */
+    GOOGLE_CLIENT_ID?: string;
+    GOOGLE_CLIENT_SECRET?: string;
+    /**
+     * Email is offered only when both are set: a Resend API key, and the sender its codes
+     * come from, as `Name <address>` or an address on a domain verified with Resend.
+     */
+    RESEND_API_KEY?: string;
+    EMAIL_FROM?: string;
+    /** How many codes may be mailed in a day, where the mail allowance is not the default. */
+    EMAIL_DAILY_LIMIT?: string | number;
+    /**
+     * Public records are signed unless this is `off`. The key is `SIGNING_KEY` where one is
+     * set, armored. Otherwise one is made on first use and kept in the store.
+     */
+    SIGNING?: string;
+    SIGNING_KEY?: string;
+    /**
+     * The sites that send their users here instead of hosting Verily, as a JSON list of
+     * `{ id, name, origin, authorizeUrl, returnUrl }`. Each needs its key in
+     * `SITE_<ID>_KEY`, such as `SITE_PARTNER_KEY`.
+     */
+    SITES?: string | unknown[];
+    [key: `SITE_${string}_KEY`]: string | undefined;
+}
+/**
+ * An instance's options from its settings. Every host builds them here, so two hosts given
+ * the same settings offer the same methods and behave the same. The host adds the store.
+ */
+export declare function fromEnv(env: InstanceEnv): Omit<InstanceOptions, 'store'>;

package/dist/instance/env.js

@@ -0,0 +1,84 @@
+import { discordProvider, dnsProvider, emailProvider, githubLinkProvider, githubProvider, pgpProvider, resendSender, youtubeProvider, } from '../server/index.js';
+import { registry } from './sites.js';
+/** The configured count of mailed messages a day, if it is a count at all. */
+function dailyMail(configured) {
+    const count = Number(configured);
+    return Number.isSafeInteger(count) && count > 0 ? count : undefined;
+}
+/**
+ * An instance's options from its settings. Every host builds them here, so two hosts given
+ * the same settings offer the same methods and behave the same. The host adds the store.
+ */
+export function fromEnv(env) {
+    for (const name of [
+        'PUBLIC_ORIGIN',
+        'SITE_NAME',
+        'OWNER_LABEL',
+        'OWNER_REFERENCE',
+        'OWNER_PROFILE_URL',
+        'OWNER_KEY',
+        'REPORT_URL',
+    ])
+        if (!env[name])
+            throw new Error(`${name} must be set`);
+    return {
+        origin: env.PUBLIC_ORIGIN,
+        siteName: env.SITE_NAME,
+        owner: {
+            // A site with no user accounts must not have its subject described as one.
+            kind: env.OWNER_KIND || undefined,
+            label: env.OWNER_LABEL,
+            reference: env.OWNER_REFERENCE,
+            profileUrl: env.OWNER_PROFILE_URL,
+        },
+        ownerKey: env.OWNER_KEY,
+        reportUrl: env.REPORT_URL,
+        // The same methods on every host, so only ones every host can run safely. The file
+        // method and a web key directory read a host the holder names, and a Cloudflare Worker
+        // cannot check where that resolves, so neither is offered.
+        providers: [
+            // Two ways of showing one GitHub account. Whichever is used first is the record's
+            // main method, and the other is listed beneath it once used.
+            ...(env.GITHUB_CLIENT_ID && env.GITHUB_CLIENT_SECRET
+                ? [
+                    githubProvider({
+                        clientId: env.GITHUB_CLIENT_ID,
+                        clientSecret: env.GITHUB_CLIENT_SECRET,
+                    }),
+                ]
+                : []),
+            githubLinkProvider(),
+            // A domain shown by a record in its DNS, which is one fetch to a fixed resolver.
+            dnsProvider(),
+            // A key needs no registration and no secret. An address on a key is shown only when
+            // the keyserver confirms it.
+            pgpProvider(),
+            ...(env.DISCORD_CLIENT_ID && env.DISCORD_CLIENT_SECRET
+                ? [
+                    discordProvider({
+                        clientId: env.DISCORD_CLIENT_ID,
+                        clientSecret: env.DISCORD_CLIENT_SECRET,
+                    }),
+                ]
+                : []),
+            ...(env.GOOGLE_CLIENT_ID && env.GOOGLE_CLIENT_SECRET
+                ? [
+                    youtubeProvider({
+                        clientId: env.GOOGLE_CLIENT_ID,
+                        clientSecret: env.GOOGLE_CLIENT_SECRET,
+                    }),
+                ]
+                : []),
+            ...(env.RESEND_API_KEY && env.EMAIL_FROM
+                ? [
+                    emailProvider({
+                        send: resendSender({ apiKey: env.RESEND_API_KEY, from: env.EMAIL_FROM }),
+                    }),
+                ]
+                : []),
+        ],
+        sites: registry(env.SITES, env),
+        signingKey: env.SIGNING === 'off' ? false : env.SIGNING_KEY || undefined,
+        mailPerDay: dailyMail(env.EMAIL_DAILY_LIMIT),
+    };
+}

package/dist/instance/index.d.ts

@@ -0,0 +1,136 @@
+import { type LocalAccount, type Provider } from '../core/index.js';
+import { type Store } from './store.js';
+import { type Site } from './sites.js';
+export { fromEnv, type InstanceEnv } from './env.js';
+export { registry, type Site } from './sites.js';
+export { recordStorage, type KeyValue, type Store } from './store.js';
+export interface InstanceOptions {
+    /** Everything the instance keeps: the records, and its own sessions, handoffs and counts. */
+    store: Store;
+    /** The origin the instance is served from. HTTPS, with no trailing slash. */
+    origin: string;
+    /** The owner's own site. A registered site's subjects carry their site's name instead. */
+    siteName: string;
+    /** What the owner links here: one of their accounts, a page, or the site. */
+    owner: Omit<LocalAccount, 'id' | 'siteName'> & {
+        profileUrl: string;
+    };
+    /** The secret the owner signs in with. */
+    ownerKey: string;
+    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. */
+    sites?: Map<string, Site>;
+    /**
+     * The key public records are signed by, armored. Left out, a key is made on first use and
+     * kept in the store. `false` turns signing off.
+     */
+    signingKey?: string | false;
+    /** How many codes may be mailed in a day, where the mail allowance is not the default. */
+    mailPerDay?: number;
+    /** 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. */
+    recheckBudget?: number;
+}
+/**
+ * The checks that need nothing stored: the origin, the method, and a bound on the body.
+ * Gives back the response to send, or the request with its body read. `handle` runs this
+ * itself. A host that passes requests on to another process can run it first, so that
+ * process is not woken for a request this turns away.
+ */
+export declare function admit(request: Request, origin: string): Promise<Request | Response>;
+/** A multi-site Verily server: a request handler, and the upkeep its host runs on a timer. */
+export type Instance = ReturnType<typeof createInstance>;
+export declare function createInstance(options: InstanceOptions): Server;
+declare class Server {
+    private readonly options;
+    private readonly app;
+    private readonly store;
+    private readonly origin;
+    private readonly auth;
+    private readonly sites;
+    private readonly local;
+    constructor(options: InstanceOptions);
+    /** The library's service, for a host that needs more than requests and upkeep. */
+    get service(): import("../server/service.js").VerilyService;
+    /**
+     * What a host runs on a timer, about hourly: drops what has expired, and re-reads the
+     * published proofs that are due. The default of 10 per provider each hour stays inside
+     * the rate limit a provider gives an unauthenticated caller.
+     */
+    upkeep(): Promise<void>;
+    /**
+     * Answers one request. `address` is the client's address as the host knows it, which
+     * rate limits count by. The instance reads no forwarding header itself, since which one
+     * can be trusted depends on what the host sits behind.
+     */
+    handle(request: Request, address?: string | null): Promise<Response>;
+    private route;
+    /**
+     * One request from the connect dialog on a site's own page. The page holds the session
+     * and the flow's binding and sends them as headers, because this instance's cookies are
+     * another site's on that page and a browser may not send them. Here they are put where
+     * the library looks for them, and a binding the library sets comes back as a header. The
+     * session works only from its own site's origin, and only for the dialog's requests.
+     */
+    private dialog;
+    /**
+     * Gives the sign-in window the binding of a flow a site's dialog started, as the cookie
+     * the provider's callback checks. `origin` is where the page that sent the binding is,
+     * as the window's own script saw it. It must be the site the flow's subject belongs to.
+     */
+    private enter;
+    /** The site a subject belongs to, by its id's prefix. The owner's id has none. */
+    private siteOf;
+    /**
+     * A site's backend reading its own subjects' connections, unlisted ones included, which
+     * nobody else can read. This is what lets a site show a link to its own users without the
+     * link being public. A refused request counts against the caller's address, and a good
+     * one against the site's own allowance, apart from the one its holders' handoffs share.
+     */
+    private read;
+    /** This installation's own signing key, made the first time a record is signed. */
+    private signingKey;
+    private site;
+    /**
+     * Counts a request that creates state: every POST, and the GETs that start a handoff, a
+     * session or a flow. A signed-in holder has a bucket of their own and anyone else is
+     * counted by address, so one visitor cannot lock everyone else out. A site's requests
+     * also share a ceiling, so one site cannot starve another.
+     */
+    private allowed;
+    /**
+     * Removes a link from a site session and reports it back to the site. There is no flow to
+     * hold the result, so the session holds it, and success is reported only once the
+     * revocation has committed: pending first, then revoked, then complete. A retry resumes
+     * wherever the last attempt stopped, and one already complete reads what it stored.
+     */
+    private disconnect;
+    /**
+     * Lists an account another way, or retires it, from a site session, and reports it back
+     * to the site as a disconnect is reported: pending on the session first, then changed,
+     * then complete. Asking again for what already holds changes nothing, so a retry is safe.
+     */
+    private mark;
+    /**
+     * The settings page for whoever is signed in: the owner, or a holder a site sent here.
+     * The owner's page carries the embed for their own site; a site's holder has the site to
+     * show their badge, and removes a link through a route that tells the site so.
+     */
+    private settings;
+    /**
+     * Every record the instance holds, for its operator: each site's subjects, public and
+     * unlisted alike, with what each is linked to and how it stands. Read-only. A public
+     * record links to its evidence; an unlisted one has no page that is the operator's to open.
+     */
+    private records;
+    /**
+     * Asks before an account is retired or a connection is removed, since neither can be
+     * undone. The page's one button posts to the route that does it.
+     */
+    private confirm;
+    /** One connection: the account's card, its state, and what can be done with it. */
+    private connection;
+}