@bkazemi/verily 0.7.0 → 0.8.0

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;
+}