@cruba/crubal-host 0.0.0-stage → 0.3.0

package/dist/src/host.d.ts

@@ -0,0 +1,308 @@
+import { type SecretStore } from "./secrets.ts";
+import type { Json, JsonObject } from "@cruba/crubal";
+import { type Contract, type Keys } from "@cruba/crubal";
+import { type Adapter, PgBorder } from "@cruba/crubal-postgres";
+import { type Pool } from "@cruba/crubal-postgres";
+import { PgStore } from "@cruba/crubal-postgres";
+import { type Connection, Credentials, type OAuthProvider } from "./credentials.ts";
+import type { EmergencyTerms } from "./emergency.ts";
+/**
+ * Who is calling, as the host proved it: an owner's caller, and how (`key`: an API key the host issued, a
+ * system; `identity`: a token the identity provider issued, a person; `signature`: another owner's domain
+ * key). A person proven by identity is vouched for across every owner this host holds (14.8).
+ */
+export type Caller = {
+    owner: string;
+    caller: string;
+    via?: "key" | "identity" | "signature";
+};
+/** A system acting for a hosted person (14.9): what the person allowed, as the host keeps it. */
+export type ActingFor = {
+    id: number;
+    systemOwner: string;
+    system: string;
+    person: string;
+    items: string[];
+    until?: string;
+    gated: boolean;
+    created: string;
+    revoked?: string;
+};
+export type HostOptions = {
+    /** The host's own domain, for its well-known file. */
+    domain: string;
+    /** A key the loops' routes (`/project`, `/tick`) require. */
+    hostKey?: string;
+    /** Verifiers for bearer tokens that aren't API keys (an OIDC-shaped adapter); each answers a caller or null. */
+    verifiers?: ((token: string) => Promise<Caller | null> | Caller | null)[];
+    /** Secrets by (owner, name); the environment (`CRUBAL_SECRET_<OWNER>_<NAME>`) otherwise. */
+    secrets?: (owner: string, name: string) => string | undefined;
+    /** Where credentials' secrets live beyond the connected table: a vault, a file; the environment otherwise. */
+    secretStore?: SecretStore;
+    /** Request bodies larger than this are refused with 413 (default 1 MiB). */
+    bodyLimit?: number;
+    /** Origins allowed to call from a browser; none otherwise. */
+    cors?: string[];
+    /** One structured line per request; the console as JSON otherwise, nothing when `false`. */
+    log?: ((line: JsonObject) => void) | false;
+    /** Adapters by contract name, beyond the built-in `http` one. */
+    adapters?: {
+        [contract: string]: Adapter;
+    };
+    /** A publisher's keys from its well-known file; `fetch` of `https://<domain>/.well-known/crubal.json` otherwise. */
+    resolveKeys?: (domain: string) => Promise<Keys>;
+    /** The clock (6.3). */
+    now?: () => string;
+    /** `write` publishes views right after each commit; else the loops do. */
+    fresh?: "write" | "asked";
+    /** Install unsigned bundles (development only). */
+    allowUnsigned?: boolean;
+    /** Whether a store may load an owner's whole state on a request path; the default refuses (brief 18, the scale rule). */
+    wholeState?: "allow" | "refuse";
+    /** How many owners' stores the host keeps at once (least recently used go); 256 by default. */
+    storeCache?: number;
+    /** Emergency terms (14.13), published in the well-known file, when the platform has them. */
+    emergency?: EmergencyTerms;
+    /** OAuth providers by credential name, for the connect flow and refresh. */
+    oauth?: {
+        [name: string]: OAuthProvider;
+    };
+    /** The owner's notice of an emergency edge or a dead run; the console otherwise. */
+    notify?: (owner: string, notice: JsonObject) => void | Promise<void>;
+    /** Another owner's host by domain: its base URL; `https://<domain>` otherwise. */
+    hostOf?: (domain: string) => string;
+    /** A JSON document by URL (a well-known file, a bundle); `fetch` otherwise. */
+    fetchJson?: (url: string) => Promise<JsonObject>;
+    /** The public base URL this host serves its well-known file and published packages from; `https://<domain>` otherwise. */
+    publicBase?: string;
+    /** The id prefix an arrival takes per level (`organization: "Z"`, `location: "K"`); the level's first letter otherwise. */
+    idPrefixes?: {
+        [level: string]: string;
+    };
+    /** The key connection material is sealed with at rest; `CRUBAL_SECRETS_KEY` in the environment otherwise. Without one no secret is stored. */
+    secretsKey?: string;
+    /** The id of an owner's root record, which connections sit within and whose admin manages them; `ROOT` otherwise. */
+    rootRecord?: string;
+};
+export declare const hashKey: (key: string) => string;
+export declare class Host {
+    readonly pool: Pool;
+    readonly o: HostOptions;
+    readonly credentials: Credentials;
+    constructor(pool: Pool, o: HostOptions);
+    now(): string;
+    /** The store's tables and the host's. */
+    migrate(): Promise<void>;
+    /**
+     * Connect a service for an owner: the material sealed in the credentials store, and a `system` record of
+     * the fact within the owner's root record, written as the host's action naming the person. The person,
+     * when given, must hold admin on the root or the `connections` item; the owner's own key needs none.
+     */
+    connect(owner: string, name: string, c: {
+        scheme: string;
+        material: JsonObject;
+        scopes?: string[];
+        expires?: string;
+        person?: string;
+        values?: JsonObject;
+    }): Promise<{
+        connection: Connection;
+        record: string;
+    }>;
+    /** Revoke a connection: the material gone, the record marked revoked. */
+    disconnect(owner: string, name: string, person?: string): Promise<{
+        record?: string;
+    }>;
+    /** Is a service connected for the owner: material held and not expired, and the record not revoked? */
+    connected(owner: string, name: string): Promise<boolean>;
+    private requireConnections;
+    private systemFor;
+    /** The system record for a service, within ROOT, made or updated; the host's action names the person. */
+    private writeSystem;
+    /** Make an owner: a domain or a hosted person, with an Ed25519 key the host signs its chain with. */
+    createOwner(owner: string): Promise<{
+        owner: string;
+        public: string;
+    }>;
+    /**
+     * Rotate an owner's key (8.5, 11.7): a new key signs from now; the well-known file lists the old with
+     * `until` and the new with `from`, so the chain verifies across the rotation.
+     */
+    rotateKey(owner: string, now?: string): Promise<{
+        owner: string;
+        public: string;
+        retired: string;
+    }>;
+    /** The signer for a hosted person (14.1): their key, made on first use. */
+    private hostedSigner;
+    owners(): Promise<{
+        owner: string;
+        public: string;
+    }[]>;
+    /** The owners a page at a time, for the loops: a host of thousands never holds them all at once. */
+    private eachOwner;
+    private keyOf;
+    /** Issue an API key for a caller of an owner; the raw key is returned once and only its hash is kept. */
+    issueKey(owner: string, caller: string, label?: string): Promise<string>;
+    revokeKey(raw: string): Promise<void>;
+    /** Link an identity provider's subject to a caller, for the OIDC verifier. */
+    linkIdentity(provider: string, subject: string, owner: string, caller: string): Promise<void>;
+    /** Remove an identity link (a person deleting themselves): the subject signs in as nobody from now on. */
+    unlinkIdentity(provider: string, subject: string): Promise<boolean>;
+    /** Every identity link that names a caller, for export and delete. */
+    identitiesOf(owner: string, caller: string): Promise<{
+        provider: string;
+        subject: string;
+    }[]>;
+    identity(provider: string, subject: string): Promise<Caller | null>;
+    /**
+     * Who is calling when the request is signed by another owner (RFC 9421 with its domain key): the signer's
+     * domain, as a caller of the owner addressed. The signer's key comes from its well-known file.
+     */
+    whoSigned(owner: string, req: {
+        method: string;
+        url: string;
+        body?: string;
+        headers: {
+            [h: string]: string | string[] | undefined;
+        };
+    }): Promise<Caller | null>;
+    /** Who is calling: an API key, a token a verifier knows, or nobody. The store sees only the caller ID. */
+    whoIs(authorization: string | undefined): Promise<Caller | null>;
+    /** Does this host hold the owner (a domain, or a hosted person `domain:id`)? */
+    hosts(owner: string): Promise<boolean>;
+    /**
+     * The caller as an owner on this host sees them (14.8): their own ID at the owner that hosts them, or
+     * themselves as that owner when they address their own chain; elsewhere on the host, a person proven by
+     * identity is `person:<domain:id>`, vouched for without a signature; a system or a stranger is nobody.
+     */
+    callerFor(owner: string, who: Caller | null): Promise<string | undefined>;
+    /** A person lets a system act for them: narrowed to items, until a moment, gated until they lift it. */
+    allowActing(person: string, systemOwner: string, system: string, o?: {
+        items?: string[];
+        until?: string;
+        gated?: boolean;
+    }): Promise<ActingFor>;
+    /** The person revokes it: nothing is deleted, the row keeps when. */
+    revokeActing(person: string, id: number): Promise<boolean>;
+    actingFor(person: string): Promise<ActingFor[]>;
+    /** The live permission for this system to act for this person now, or none. */
+    mayActFor(who: Caller, person: string, now?: string): Promise<ActingFor | null>;
+    /**
+     * Every live edge a caller holds across every owner on this host, grouped by owner: who they are to
+     * each. A hosted person is named by their bare ID at home and `person:<domain:id>` elsewhere.
+     */
+    whoami(who: Caller, now?: string): Promise<JsonObject>;
+    /**
+     * The rows the caller stands in a relation to, across every owner on this host (14.10, 12.6): the index
+     * rows whose record, or an ancestor, is a live edge of theirs with that relation. The feed's primitive.
+     */
+    rowsFor(who: Caller, relation: string, o?: {
+        view?: string;
+        limit?: number;
+        now?: string;
+    }): Promise<JsonObject[]>;
+    /** A credential's secret: connected under the name (refreshed when OAuth and expired), a configured source, or the environment. */
+    secret(owner: string, name: string): Promise<string | undefined>;
+    /** Health (docs/design/completion.md O): the database reachable, and every owner's chain head. */
+    health(): Promise<JsonObject>;
+    /** An owner's store, signing with the owner's key when the host holds one. */
+    /** One store per owner for the life of the host, so its definitions and state caches outlive a call (G6). */
+    storeFor(owner: string): Promise<PgStore>;
+    private readonly stores;
+    /** Drop an owner's kept store: after a key rotation (its signer changes) or a rewrite of its history. */
+    forgetStore(owner: string): void;
+    /**
+     * The built-in `http` adapter: a contract with the host's part `host:url` is POSTed its payload as JSON,
+     * with the credential the contract names resolved to a secret and sent as its `auth` scheme says.
+     */
+    httpAdapter(owner: string): Adapter;
+    /** Another owner's host, by domain. */
+    hostOf(domain: string): string;
+    /** A request to another owner's host, signed with this owner's domain key (RFC 9421). */
+    signedFetch(owner: string, method: string, url: string, body?: string): Promise<Response>;
+    /** May this caller read an offer (7.8 `to`)? Public to anyone; link by token; followers and named parties by edge or signature. */
+    mayTake(owner: string, c: Contract, callerId: string | undefined, link: string | undefined): Promise<boolean>;
+    /** Publish an offer by link (7.8): the token, minted once and kept across republishing. */
+    offerLink(owner: string, contract: string): Promise<string>;
+    /** Unpublish a link offer: the token stops working, nothing is deleted. */
+    unpublishOffer(owner: string, contract: string): Promise<void>;
+    /**
+     * A take across hosts (7.8, 8.5.1): fetch the presenter's offer with a signed request, verify the wrapper
+     * against the presenter's keys, then take each offered record into ours: the one bound to it, or a new
+     * record bound from now on. Each take is one entry naming the presenter's.
+     */
+    take(owner: string, takeName: string, at?: string): Promise<JsonObject>;
+    /**
+     * Push streams (12.6.2): every stream contract with `when: entry` sends its entries since the cursor to
+     * the party it names (its adapter, else a signed POST to that host's inbox), and the acknowledgement
+     * moves the cursor.
+     */
+    push(now?: string, owner?: string): Promise<JsonObject[]>;
+    /** Taken values past their terms (7.8), for every owner or one. */
+    expire(now?: string, owner?: string): Promise<JsonObject[]>;
+    /** An owner's border over its own definitions, with the adapters. */
+    borderFor(owner: string, store?: PgStore): Promise<PgBorder>;
+    resolveKeys(domain: string): Promise<Keys>;
+    /**
+     * Install into one owner what another owner on this host already holds (brief 1: a person's chain takes
+     * the person package from the platform's own log): the bundle and what it extends, in order, each skipped
+     * when the target already has that version. The source's bundles were verified when it installed them.
+     */
+    installFromOwner(target: string, source: string, pkg: string, version?: string, at?: string): Promise<JsonObject[]>;
+    /** Install a published version for an owner: the publisher's keys from its well-known file, then the store. */
+    install(owner: string, bundle: JsonObject): Promise<JsonObject>;
+    /** A JSON document by URL. */
+    fetchJson(url: string): Promise<JsonObject>;
+    /** A publisher's well-known file (11.7), by its domain. */
+    wellKnownOf(domain: string): Promise<JsonObject>;
+    /**
+     * Install a package by name from its publisher's well-known file (11.7, release.md): the version asked
+     * for or the latest, its bundle fetched from where the file says, what it extends installed first
+     * (from their own publishers), every bundle verified against its publisher's published keys.
+     */
+    installFrom(owner: string, pkg: string, version?: string, seen?: Set<string>): Promise<JsonObject[]>;
+    /** Where this host serves what it publishes: the public base URL (`https://<domain>` otherwise). */
+    publicBase(): string;
+    /** The URL of a published version's bundle; the text sits beside it as package.crubal. */
+    bundleUrl(owner: string, pkg: string, version: string): string;
+    /**
+     * Publish a package version for an owner this host holds the key of: the text becomes a bundle signed
+     * with that key, versioned against the owner's last published version of the package (so unchanged
+     * members keep their versions and a breaking change needs its recipe), kept here and listed in the
+     * well-known file. A version already published is returned as it is; a published version never changes.
+     */
+    publishPackage(owner: string, source: string, o?: {
+        date?: string;
+        records?: Json[];
+    }): Promise<{
+        bundle: JsonObject;
+        changes: {
+            member: string;
+            kind: string;
+        }[];
+        already: boolean;
+    }>;
+    /** One published version: its signed bundle and its text, or null. */
+    publishedBundle(owner: string, pkg: string, version: string): Promise<{
+        bundle: JsonObject;
+        text: string;
+    } | null>;
+    /** What the well-known file lists: every published package with its versions and where each bundle is. */
+    publishedPackages(owner?: string): Promise<JsonObject[]>;
+    wellKnown(): Promise<JsonObject>;
+    notice(owner: string, notice: JsonObject): Promise<void>;
+    /** Publish every owner's stale rows. */
+    project(owner?: string, now?: string): Promise<{
+        [owner: string]: number;
+    }>;
+    /** Drain pending instructions (completion.md P) for every owner or one, at a rate per owner. */
+    drain(rate?: number, owner?: string, now?: string): Promise<JsonObject[]>;
+    /**
+     * Try failed runs again when their contract's retry interval has passed (7.5): a run still open after a
+     * failure, whose last attempt is `every` behind `now`. A run dead after its last attempt is noticed.
+     */
+    retry(now?: string, owner?: string): Promise<JsonObject[]>;
+    /** Run every scheduled contract's due ticks, for one owner or all. */
+    tick(now?: string, owner?: string): Promise<JsonObject[]>;
+}