@bkazemi/verily 0.8.1 → 0.9.0

package/dist/instance/sites.d.ts

@@ -5,6 +5,8 @@ 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";
+/** What an operator may change about a stored site. Absent lists mean every one. */
+export type Settings = Pick<Site, 'authorizeUrl' | 'returnUrl' | 'providers' | 'visibility'>;
 /** 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. */
@@ -18,6 +20,9 @@ export interface Site {
     returnUrl: string;
     /** Shared with the site's backend. Signs handoffs one way and results the other. */
     key: string;
+    /** The key before the last rotation, still accepted until `previousUntil`. */
+    previousKey?: string;
+    previousUntil?: number;
     /** 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. */
@@ -49,6 +54,12 @@ export interface SiteSession {
     /** The flow whose result this session returned with. No other flow's result is signed. */
     returned?: string;
     operation?: Operation;
+    /**
+     * The hash of the site key that signed the token this session was opened with. Its result
+     * is signed with that same key while the key is accepted, even if it has been replaced
+     * since, because the backend that started the handoff may not have the new key yet.
+     */
+    signer?: string;
     /**
      * 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
@@ -56,6 +67,49 @@ export interface SiteSession {
      */
     dialog?: true;
 }
+/** What is kept of a stored site once it is gone: that its id was used, when, and why. */
+export interface Retired {
+    retiredAt: number;
+    /** `deleted` by an operator, or `lapsed` after a month suspended. */
+    reason: 'deleted' | 'lapsed';
+}
+/** How long a stored site stays suspended before it is deleted. */
+export declare const lapseMs: number;
+/**
+ * What the instance owner has set for a stored site. Kept apart from the site itself, so
+ * nothing its operators change can reach it.
+ */
+export interface Controls {
+    /** When the owner suspended the site. Absent while the owner has not. */
+    suspendedAt?: number;
+    /** Requests a minute for the site, in place of `limits.registered`. */
+    limit?: number;
+    /** When the owner let the site's holders use YouTube. Absent while it is withheld. */
+    youtubeApprovedAt?: number;
+}
+/** Where the last DNS check of a stored site is kept, under its id. */
+export declare const dnsPrefix = "site/dns/";
+/** What the last DNS check of a stored site found. */
+export interface DnsCheck {
+    /** When the DNS was last asked, whether or not it answered. */
+    attemptedAt: number;
+    /** When the DNS last answered. Absent if it never has. */
+    checkedAt?: number;
+    /** When the site's `verily-verifier` record was first found missing. Absent while it is there. */
+    absentSince?: number;
+}
+/** Someone who may manage a stored site. Only a dashboard key, for now, kept hashed. */
+export interface Operator {
+    kind: 'key';
+    hash: string;
+    addedAt: number;
+}
+/** A site's id: what prefixes its subjects and names it in every token. */
+export declare const validId: (id: unknown) => id is string;
+/** A key: base64url, of at least 32 bytes. */
+export declare const validKey: (key: unknown) => key is string;
+/** A site entry checked field by field, without its key. Throws on the first thing wrong. */
+export declare function checked(entry: Record<string, unknown>): Omit<Site, 'key'>;
 /**
  * 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
@@ -68,6 +122,8 @@ export declare function sign(key: string, payload: object): string;
 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;
+/** How long a replaced site key is still accepted, so the site has time to deploy the new one. */
+export declare const rotationMs: number;
 /**
  * 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
@@ -75,8 +131,80 @@ export declare function open(key: string, token: string): Record<string, unknown
  */
 export declare class Sites {
     private readonly storage;
-    readonly sites: Map<string, Site>;
-    constructor(storage: Store, sites: Map<string, Site>);
+    private readonly pinned;
+    /**
+     * Every site served: the pinned ones, then the ones kept in the store, as `refresh()`
+     * last read them.
+     */
+    sites: Map<string, Site>;
+    /**
+     * 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: Set<string>;
+    /** What the instance owner has set for each stored site, as `refresh()` last read it. */
+    controls: Map<string, Controls>;
+    /**
+     * `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: Store, pinned: Map<string, Site>);
+    /**
+     * 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.
+     */
+    refresh(): Promise<void>;
+    /** The sites kept in the store and served, which are the ones whose DNS is checked. */
+    stored(): Site[];
+    /**
+     * 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: string): number | undefined;
+    /**
+     * 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: Site, offers: string[]): string[] | undefined;
+    /**
+     * The provider ids the owner has not approved a site for, whichever its operators chose.
+     * None for a pinned site.
+     */
+    withheld(id: string): string[];
+    /** Changes what the instance owner has set for a stored site. */
+    control(id: string, change: (controls: Controls) => Controls): Promise<void>;
+    /** A site that may start something new: served, and not suspended. */
+    private active;
+    /**
+     * 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.
+     */
+    register(site: Site, first: Operator): Promise<void>;
+    /**
+     * 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.
+     */
+    update(id: string, settings: Settings): Promise<void>;
+    /**
+     * 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.
+     */
+    rotate(id: string, keep: boolean, from?: string): Promise<string | undefined>;
+    /** Stops accepting a stored site's previous key, once the new one is deployed. */
+    retirePreviousKey(id: string): Promise<void>;
+    /**
+     * 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.
+     */
+    retire(id: string, reason: Retired['reason']): Promise<void>;
+    /** The operators of a stored site. */
+    operators(id: string): Promise<Operator[]>;
     /**
      * 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.
@@ -150,14 +278,17 @@ export declare class Sites {
      * 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. */
+    /**
+     * 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: Site, local: LocalAccount, txn: string, result: {
         operation: string;
         outcome: string;
         connection?: string;
         visibility?: Visibility;
         finishedAt: number;
-    }): string;
+    }, signer?: string): 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.