@bkazemi/verily 0.1.0

package/dist/server/service.d.ts

@@ -0,0 +1,311 @@
+import { type Attestations, type Connection, type Evidence, type ExternalAccount, type Flow, type LocalAccount, type Provider, type SignedDocument, type SignedEvidence, type Storage, type VerifierKey, type Visibility } from '../core/index.js';
+export declare const secret: () => string;
+export declare const hash: (value: string) => string;
+export declare class Unavailable extends Error {
+    constructor();
+}
+export interface ServiceOptions {
+    storage: Storage;
+    /**
+     * The methods this instance offers. Several may share a provider id: `githubProvider()`,
+     * `githubGistProvider()` and `githubLinkProvider()` are three ways to show one GitHub
+     * account, and a record shown by more than one keeps them all. The first is the default.
+     */
+    providers: Provider[];
+    baseUrl: string;
+    siteName: string;
+    verifierName: string;
+    profileOrigins: string[];
+    validityMs?: number;
+    flowTtlMs?: number;
+    shareTtlMs?: number;
+    /** How stale a published proof may be before it stops counting. Infinity never expires. */
+    freshnessMs?: number;
+    /** How often recheck() reads a given proof again. Must be well under freshnessMs. */
+    recheckMs?: number;
+    recheckTimeoutMs?: number;
+    /**
+     * How many messages a code provider may send in any twenty-four hours: in all, and to
+     * any one address. A visitor chooses where a message goes, so the first bounds what one
+     * of them can spend of the deployment's mail allowance and the second what an address
+     * whose holder never asked can be sent. A hundred and five unless set; `Infinity` lifts
+     * one. Each provider is counted on its own.
+     */
+    sendLimits?: {
+        day?: number;
+        address?: number;
+    };
+    /**
+     * Signs public records, so a saved signed record can be checked away from this
+     * instance, with `gpg` or anything else that reads OpenPGP. A key from
+     * `generateSigningKey()`, or a function giving one where it is read from storage.
+     * Unset signs nothing. Losing the key puts every record it signed out of reach of a
+     * check, so keep it wherever the instance's other secrets are kept.
+     */
+    signingKey?: string | (() => Promise<string>);
+    /** Public keys this instance signed with before, so what they signed still checks. */
+    retiredKeys?: VerifierKey[];
+    now?: () => number;
+}
+export declare class VerilyService {
+    readonly options: ServiceOptions;
+    readonly now: () => number;
+    readonly baseUrl: string;
+    readonly providers: Provider[];
+    constructor(options: ServiceOptions);
+    private signing?;
+    /** The key this instance signs with, read once. */
+    private signer;
+    /** Every key a record of this instance may be signed by: the current one first. */
+    keys(): Promise<VerifierKey[]>;
+    /** The same keys as one armored text, which is what `gpg --import` takes. */
+    armoredKeys(): Promise<string>;
+    /**
+     * A public record that stands, signed as of now. Signed when asked for, not when
+     * approved, so a signed record says the record stood on the day it was taken and none can be
+     * made once it is removed.
+     */
+    signed(id: string): Promise<SignedEvidence>;
+    /** What a signed record says, if this instance signed it. */
+    checked(signed: unknown): Promise<SignedDocument | undefined>;
+    private get sendLimits();
+    /** A proof is only as fresh as the schedule that reads it, so both live together. */
+    private get freshness();
+    validateLocal(local: LocalAccount): LocalAccount;
+    /** The site a subject belongs to: its own name where it has one, else this instance's. */
+    siteOf(local: Pick<LocalAccount, 'siteName'>): string;
+    /**
+     * The configured method a caller asked for: a provider id and, where that provider is
+     * shown more than one way, which way. Nothing asked for means the first configured.
+     */
+    resolve(provider?: string, method?: string): Provider;
+    /** The method a flow was started with. A flow from before methods were recorded ran the first. */
+    providerOf(flow: Flow): Provider;
+    start(local?: LocalAccount, connectionId?: string, kind?: Flow['kind'], choice?: {
+        provider?: string;
+        method?: string;
+    }, context?: Record<string, string>): Promise<{
+        flowId: string;
+        binding: string;
+        expect: string;
+        instructions: import("../core/index.js").Instruction[];
+        authorizationUrl?: undefined;
+    } | {
+        flowId: string;
+        binding: string;
+        authorizationUrl: string;
+        expect?: undefined;
+        instructions?: undefined;
+    } | {
+        flowId: string;
+        binding: string;
+        expect?: undefined;
+        instructions?: undefined;
+        authorizationUrl?: undefined;
+    }>;
+    /**
+     * Which method a flow runs. A flow on an existing record stays in that record's
+     * namespace, and without a choice it uses the method the record was first shown by.
+     *
+     * Removing a link from the external side takes a method whose proof is fresh. A standing
+     * proof, such as a link back, is there for anyone to point at: handing one back shows
+     * the link exists, not that whoever handed it back holds the account.
+     */
+    private chosen;
+    /**
+     * Accepts what the holder hands back: the address they published the flow's string at,
+     * or the proof itself. Both are holder-supplied, so the provider decides what counts.
+     * A code provider is handed two things in turn, the address to send to and then the
+     * code that arrived there.
+     */
+    submit(id: string, binding: string, artifact: string): Promise<string>;
+    /**
+     * One step of a mailed code. The first answer is an address: a code is minted, sent
+     * there, and only its hash kept. The second is the code, which the holder could only
+     * have read at that address. The code is the whole proof and short enough to type, so
+     * the guesses are counted and a flow that runs out of them is dead.
+     */
+    private answer;
+    /**
+     * Counts one message against the day's ceiling and the address's, and says whether both
+     * had room. All or nothing, so a message refused by one spends nothing from the other.
+     * Counted before the message goes, so one that fails to send is still spent: a sender
+     * that is failing is not a reason to try it more often. The address is kept as a hash.
+     */
+    private spend;
+    /**
+     * The flow a confirmation link belongs to, while the link is still good. The link is
+     * the whole credential and is used from wherever the holder reads their mail, so no
+     * binding is asked for: it proves the mailbox and nothing else, and what happens to the
+     * flow next is still up to the browser that started it.
+     */
+    private linked;
+    /**
+     * What a confirmation link would confirm, to show its holder before they press anything.
+     * The subject is named only for a new link, where the one who started the flow is the
+     * one who named it. A flow on an existing record is started by anybody, and its subject
+     * is nobody's to read until the matching account has been shown.
+     */
+    confirming(id: string, token: string): Promise<{
+        kind: "visibility" | "connect" | "renew" | "revoke" | "share-revoke";
+        provider: Provider;
+        account: ExternalAccount;
+        local: LocalAccount | undefined;
+    }>;
+    /**
+     * Takes a pressed confirmation link as the proof a typed code would have been, and
+     * returns the flow as that left it. The link is spent either way.
+     */
+    confirm(id: string, token: string): Promise<Flow>;
+    private bound;
+    flow(id: string, binding: string): Promise<Flow>;
+    callback(state: string, binding: string, code?: string): Promise<string>;
+    /**
+     * The identity is established the same way whichever method produced it, so both paths
+     * land here: a provider result is never trusted for its shape, and a flow against an
+     * existing connection must still be the same account on the same provider. No binding
+     * means a confirmation link got here, which is held to the link and not to a browser.
+     */
+    private established;
+    /**
+     * A failed check leaves the flow dead rather than retryable in place. Only a `Refused`
+     * reason is kept: any other error may describe this backend rather than the proof.
+     */
+    private failed;
+    approve(id: string, binding: string, local: LocalAccount | undefined, visibility: Visibility, cancel?: boolean, 
+    /**
+     * The visibilities this subject may choose, where it may not choose either. Checked at
+     * the point the record's visibility is set, inside the transaction that decides whether
+     * this approval makes a record or joins one, so no change in between gets past it.
+     */
+    allowed?: Visibility[]): Promise<string | undefined>;
+    /**
+     * Ends a flow and records how, inside the transaction that ends it: the connection as it
+     * stands now, since whatever later reports this result must not read a record that has
+     * changed since. The caller puts the flow.
+     */
+    private ended;
+    /** Every read of a connection goes through here, so a record in an older shape is upgraded. */
+    private transaction;
+    /**
+     * The methods a reader is shown. An additional method whose proof has gone unread no
+     * longer shows anything, so it is left out until it reads again; the main one is
+     * never left out, because the record's status already says what became of it.
+     */
+    private shown;
+    evidence(connection: Connection): Evidence;
+    /**
+     * The live record a connect flow reproves by another method, if there is one: the same
+     * subject linked to the same account on the same provider, first shown some other way.
+     * The same method again is a second record, as it always was; renewing is how that
+     * one is extended.
+     */
+    private joins;
+    /**
+     * The record a connect flow awaiting approval would add its method to, so the approval
+     * page can say so: the holder is not creating a link but reproving one, and the
+     * visibility already chosen for it stands.
+     */
+    joining(flow: Flow): Promise<Connection | undefined>;
+    /**
+     * Records that a flow just showed the record's account again. Shown by the method the
+     * record was first shown by, it replaces that one; shown another way, it takes that
+     * method's place after it, or joins the end. Either way the holder approved it and the
+     * site reasserted its subject, so the record is extended and its subject refreshed.
+     */
+    private recordMethod;
+    /**
+     * Whether a proof still names the subject as it is now. A method that has the holder
+     * publish something derived from the subject, as a link back publishes its address,
+     * proved the subject as it was then; one whose proof is a token minted per flow names no
+     * subject, and holds whatever the subject's address becomes.
+     */
+    private names;
+    /** The site is the only authority on its own namespace, so it declares the local subject. */
+    private declared;
+    /** How the provider established the external account, by whatever method the flow ran. */
+    private attestation;
+    /**
+     * The proof itself, for a method whose artifact this backend publishes. It is as public
+     * as the evidence it belongs to and no more: an unlisted record's proof is the holder's
+     * to hand out, exactly like the evidence page it is linked from.
+     */
+    proof(id: string, local?: LocalAccount): Promise<string>;
+    /** A record from a provider this instance no longer configures keeps its raw id. */
+    private providerName;
+    read(id: string, local?: LocalAccount): Promise<Evidence>;
+    /**
+     * Every connection this site has published. Public evidence is already world-readable
+     * one id at a time; listing it lets an embed follow the current connections instead of
+     * hardcoding an id that dies whenever one is revoked and replaced. Unlisted records are
+     * never included: they must not appear in any directory listing.
+     */
+    published(): Promise<Evidence[]>;
+    mine(local: LocalAccount): Promise<Evidence[]>;
+    private owned;
+    revoke(id: string, local: LocalAccount): Promise<void>;
+    share(id: string, local: LocalAccount, revoke?: boolean): Promise<{
+        url: string;
+        expiresAt: number;
+    } | undefined>;
+    shared(token: string): Promise<{
+        evidenceUrl: string;
+        linkExpiresAt: number;
+        id: string;
+        local: Omit<LocalAccount, "id" | "siteName">;
+        external: ExternalAccount;
+        provider: string;
+        providerName: string;
+        attestations: Attestations;
+        siteName: string;
+        verifierName: string;
+        visibility: Visibility;
+        status: import("../core/index.js").Status;
+        connectedAt: number;
+        authenticatedAt: number;
+        approvedAt: number;
+        visibilityApprovedAt: number;
+        expiresAt: number;
+        revokedAt?: number;
+        signedUrl?: string;
+    }>;
+    /**
+     * Asks again about proofs, because unlike a sign-in they can stop being true with nobody
+     * told. What that means depends on who holds the proof:
+     *
+     * A proof published elsewhere is reread. The holder deletes the gist and this record
+     * would otherwise go on claiming it, so continued silence ages the connection out.
+     *
+     * A proof this backend hosts cannot go missing, so there is nothing to reread. What can
+     * still change is the identity behind it, and a method that has somewhere to say so is
+     * asked. A holder who publishes a revocation for their key has withdrawn it, which is a
+     * revocation of the connection rather than a proof gone stale.
+     *
+     * A failed read writes nothing. One refusal is not evidence the proof is gone, and a
+     * provider being down must not revoke anyone; it is continued silence that ages a
+     * connection out through `status`, and a single later success undoes that. Revocation
+     * stays what it is, something a party chose.
+     *
+     * `budget` bounds the reads per run, since providers rate-limit and the alarm this runs
+     * on is shared. Oldest first, so nothing starves however many connections are waiting.
+     *
+     * Returns how many were confirmed. A connection revoked here is not one of them.
+     */
+    recheck(budget?: number): Promise<number>;
+    /**
+     * The configured method that can ask again about one attestation, or nothing when there
+     * is nothing to ask: no published proof, a method this instance no longer runs, or a
+     * hosted proof whose method has nowhere to hear of a withdrawal.
+     */
+    private rereads;
+    /** Asks about one proof and records the answer. Returns 1 when it confirmed. */
+    private reread;
+    /** A provider that never answers must not hold up the maintenance run behind it. */
+    private deadline;
+    /** Run periodically. Pending secrets expire immediately; historical evidence defaults to 90 days. */
+    prune(retentionMs?: number): Promise<void>;
+    private invalidateShare;
+    private audit;
+}
+/** How many wrong codes a flow takes before it is dead. */
+export declare const codeAttempts = 5;