@scp-dev/hub 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,617 @@
+import { Envelope, RelayCore, CoreOptions, EndpointRow, PolicySubject, ScopeSubject, ScopeNode, ScopeDirection, Admission, MessageRow, EndpointView, ScopeCap, ScopeEntry, Claim, SendParams, SendResult, EndpointKind, Presence, StatusState, Sql, CrossAccountLink, XDelivered, XListed, ActivityRow, XRelease } from '@scp-dev/core';
+
+type RelayAuth = Envelope["from"]["auth"];
+/** a machine name: one relay host of an account */
+declare const MACHINE_NAME: RegExp;
+interface FederatedOptions extends CoreOptions {
+    /** this host's own machine name; addresses naming it stay local */
+    machine?: string;
+    /** other names of the local user, such as the account handle once known */
+    aliases?: string[];
+    /** `from.auth` of senders whose row records none (default local-uid) */
+    auth?: RelayAuth;
+    /** at most this many live endpoints, mirrored and claimed together */
+    endpointCap?: number;
+    /** at most this many refusal audit rows a minute for each refusal code; the next one written counts those left out */
+    refusalsPerMinute?: number;
+    /** the hosted relay's cross-account tables: messages from other accounts in xinbox, in one seq space with deliveries */
+    xinbox?: boolean;
+}
+/** own rules as they cross machines: selector lists per direction */
+interface MirrorRules {
+    in?: string[];
+    out?: string[];
+}
+/** caps and allowances as they cross machines: `by` and `via` name an endpoint of the same machine as `ep:<handle>`, else human, policy, inherited or gone */
+interface MirrorCaps {
+    caps: ScopeCap[];
+    allow?: Record<string, ScopeEntry[]>;
+}
+/** an agent endpoint's place in its machine's tree, its rules and its caps; a field left out is unknown, or unchanged once known */
+interface MirrorScope {
+    /** the root's handle on the same machine (a root's own) */
+    tree?: string | null;
+    /** the parent's handle on the same machine; null for a root */
+    parent_ep?: string | null;
+    /** 0 for a root; null when not known */
+    depth?: number | null;
+    rules?: MirrorRules | null;
+    caps?: MirrorCaps | null;
+    /**
+     * changes when its machine released the endpoint and another took the handle, a new spawn took it over, or its caps loosened: the caps
+     * seen before lapse. The part before the first "." names the holder: a change there also drops what a hub queued for the endpoint
+     */
+    incarnation?: string | null;
+}
+/** an endpoint as another machine reports it: EndpointView-like, only the address's last segment is used as the handle */
+interface MirrorView extends MirrorScope {
+    address: string;
+    kind: EndpointKind;
+    harness?: string | null;
+    model?: string | null;
+    cwd?: string | null;
+    labels?: Record<string, string>;
+    status?: {
+        state: StatusState;
+        note: string;
+    } | null;
+    presence?: Presence;
+    last_seen?: string | null;
+    title?: string | null;
+}
+interface RemoteView extends Omit<EndpointView, "depth">, MirrorScope {
+    machine: string;
+}
+/** a row of xinbox: a message from another account, its envelope as JSON */
+interface XInboxRow {
+    seq: number;
+    id: string;
+    from_account: string;
+    client_id: string;
+    endpoint: string;
+    /** the sender's address in its account */
+    sender: string;
+    message: string;
+    thread: string;
+    grant: string | null;
+    expires_at: number;
+    /** when it was received */
+    at: number;
+}
+/** a mirrored endpoint of this account as the cross-account checks see it */
+interface XEndpoint {
+    id: string;
+    /** `<machine>/<handle>`, handle empty for a machine's human */
+    remote: string;
+    machine: string;
+    handle: string;
+    kind: EndpointKind;
+    depth: number | null;
+    harness: string | null;
+    presence: Presence;
+}
+interface MirrorChange {
+    view: RemoteView;
+    added: boolean;
+    presence: boolean;
+    status: boolean;
+}
+interface Delivery {
+    seq: number;
+    /** `<machine>/<handle>` of the recipient, or null for a row of no machine */
+    endpoint: string | null;
+    /** the recipient's endpoint id */
+    recipient: string;
+    /** whether the recipient is a row its machine's bridge mirrors, not one a direct client claimed */
+    mirrored: boolean;
+    message: Envelope;
+}
+/** RelayCore with endpoints of other machines: qualified addresses, mirrored and proxy rows, injection and forwarding records */
+declare class FederatedCore extends RelayCore {
+    readonly machine: string | null;
+    private aliases;
+    private scope;
+    private readonly defaultAuth;
+    private readonly endpointCap;
+    private readonly refusalsPerMinute;
+    private readonly refusals;
+    private readonly xinbox;
+    private xfrom;
+    constructor(sql: ConstructorParameters<typeof RelayCore>[0], options: FederatedOptions);
+    migrate(): void;
+    /** with xinbox, a delivery takes the next seq past xinbox's too, so a bridge's replay and ack cursor stay one space */
+    protected insertDelivery(messageId: string, endpoint: string, expiresAt: number): number;
+    setAliases(aliases: string[]): void;
+    /** runs `fn` with unqualified handles resolving on `machine`: a direct client's own namespace on the hub */
+    within<T>(machine: string | null, fn: () => T): T;
+    /** the hub-side address (`<machine>/<handle>`) an address names, another account's as it is, or null when it is on this machine */
+    route(address: unknown): string | null;
+    /** whether an address names an endpoint on another machine or of another account; malformed addresses are not remote */
+    isRemote(address: unknown): boolean;
+    /** the local endpoint id a hub delivery for `<machine>/<handle>` is for */
+    localTarget(target: unknown): string;
+    /** the live row of `<machine>/<handle>`, for a bridge acting on its own machine's endpoints */
+    remoteEndpoint(machine: string, handle: unknown): string;
+    /** the machine an endpoint row belongs to, or null for a row of this host */
+    machineOf(endpoint: string): string | null;
+    /** `<account>/<machine>/<handle>` of another account (handle empty for its machine's human, `me`), or null for any other address */
+    foreignAccount(address: unknown): {
+        account: string;
+        machine: string;
+        handle: string;
+    } | null;
+    private isLocalUser;
+    /** whether an endpoint of another account `part` ever reached this relay, so `<part>/me` is that account's human */
+    private knownAccount;
+    private locate;
+    protected resolve(address: unknown): EndpointRow;
+    protected addressUsers(): string[];
+    protected localRow(row: EndpointRow): boolean;
+    protected address(row: EndpointRow): string;
+    protected subject(row: EndpointRow): PolicySubject;
+    /** a stand-in for another account's sender is no endpoint of this relay: list, peers and snapshots leave it out */
+    protected listable(row: EndpointRow): boolean;
+    /** an address of another account (a sender's stand-in, or a target with none) is checked as that account's endpoint */
+    protected policySubject(address: string): PolicySubject;
+    /**
+     * another machine's row sits in no local tree: a fleet of its own on its machine, so a scoped local endpoint reaches it only by a leaving
+     * selector; its mirrored ancestors are kept so a cap widened by one of them is clipped as on its machine
+     */
+    protected scopeSubject(row: EndpointRow): ScopeSubject;
+    /** another machine's row has the rules and caps its machine mirrored; only the hub's own human (a full login on the hub) is the account's human */
+    protected scopeNode(row: EndpointRow): ScopeNode;
+    /**
+     * throws not_found, as send() does, when the scope refuses a local endpoint's message to an address on another machine, a reply
+     * (`replyTo`, its parent) to a message it got from that address passing as a solicited one; to another account, the cross-account rule on
+     * the sender's out lists, unless it replies to a message it got from exactly that address
+     */
+    scopeCheck(from: string, to: unknown, replyTo?: string): void;
+    /** whether direction `dir` of `endpoint` admits an endpoint of another account: only an `acct:` selector in each list, or no list at all */
+    crossAdmission(endpoint: string, dir: ScopeDirection, peer: ScopeNode | {
+        account: string;
+        machine: string;
+        handle: string;
+    }): Admission;
+    protected envelope(row: MessageRow, seq?: number, recipient?: string): Envelope;
+    /**
+     * upserts a machine's endpoints from its views, never over a direct client's claimed row; `full` marks its mirrored rows missing from the
+     * list offline. An agent's place is worked out here from its mirrored parent, and a cap seen once stays until the endpoint is released
+     * (a new `incarnation`). A row is written only when something in it changed. `seen` gathers the remotes of a full mirror sent in several
+     * frames: each frame adds its own, and the closing `full` one counts every remote in it as listed.
+     */
+    mirror(machine: string, views: unknown, options?: {
+        full?: boolean;
+        auth?: RelayAuth;
+        seen?: Set<string>;
+    }): MirrorChange[];
+    /**
+     * a local agent's place, rules and caps as its machine's bridge mirrors them (MirrorScope), with its title; nothing for another row. Caps
+     * looser than the ones mirrored last move the endpoint's scope epoch and so its incarnation: a hub keeps the caps it has seen until that changes
+     */
+    mirrorScope(endpoint: string): MirrorScope & {
+        title?: string | null;
+    };
+    private scopeEpoch;
+    /**
+     * a direct client's claim of `<machine>/<handle>`, with claim()'s takeover and suffix rules, and its `exact`, `scope`, `allow`, `in` and
+     * `out`: a new row takes the claim's own rules, a taken-over one keeps its own. An exact claim is never suffixed: it joins a live claimed
+     * row of the same harness no process or session holds, with no new token, and is refused as claim() refuses one otherwise
+     */
+    claimOn(machine: string, claim: Claim, auth?: RelayAuth): {
+        endpoint: EndpointView;
+        token?: string;
+    };
+    /**
+     * resume() for a direct client of `machine`, its labels replaced by what `relabel` makes of them, held to the label limits: a token of
+     * another machine's endpoint is refused
+     */
+    resumeOn(machine: string, token: string, relabel?: (labels: Record<string, string>) => unknown): EndpointView;
+    /** every live row of other machines (or of one machine), as views with their machine */
+    remoteViews(filter?: {
+        except?: string;
+        machine?: string;
+    }): RemoteView[];
+    remoteRowsOf(machine: string): RemoteView[];
+    /** a bridge went away: its mirrored rows show offline */
+    markOffline(machine: string): MirrorChange[];
+    /**
+     * a released machine: its rows are retired like a gone handle and can't be resolved or resumed again; with `queue`,
+     * their unread deliveries go too, and each message they leave delivered to no one, unless it is a request or has
+     * replies, which askers still look up
+     */
+    dropMachine(machine: string, options?: {
+        queue?: boolean;
+    }): number;
+    /**
+     * hands a machine's direct-client rows with no connection (or only `endpoint`) to its bridge: their resume tokens are
+     * dropped, so the bridge mirrors them, and their unread deliveries get fresh seqs past any bridge's replay cursor;
+     * returns those deliveries
+     */
+    adoptClaimed(machine: string, endpoint?: string): {
+        seq: number;
+        endpoint: string;
+    }[];
+    /** the hop a message from this endpoint would get from what it received lately */
+    causalHop(endpoint: string): number;
+    /** records that an endpoint received a message of `hop`, as reading its inbox does */
+    markReceived(endpoint: string, hop: number): void;
+    /**
+     * why the local policy refuses a hub delivery to the local `endpoint`, or null; checks the message as admit() does and creates its sender's
+     * proxy row; relay notices always pass. A scope refusal throws not_found, as send() does; a redelivery of an admitted message skips it.
+     */
+    inboundRefusal(endpoint: string, message: Envelope): string | null;
+    /**
+     * a message the hub delivered to a local endpoint, stored under the hub's id from a proxy of its sender; idempotent.
+     * Throws inbox_full past the inbox cap, which a redelivery, the first reply to the endpoint's own message (as in
+     * send()) and relay notices skip.
+     */
+    admit(endpoint: string, message: Envelope): {
+        seq: number;
+        duplicate: boolean;
+    };
+    /** inject() for the hooks of a local endpoint; another machine's row (mirrored, claimed on the hub, or a sender's proxy) has none and gets nothing */
+    inject(endpoint: string, options?: Parameters<RelayCore["inject"]>[1]): ReturnType<RelayCore["inject"]>;
+    /** offer() for a local endpoint's channel; another machine's row is offered nothing */
+    offer(endpoint: string, options?: Parameters<RelayCore["offer"]>[1]): ReturnType<RelayCore["offer"]>;
+    /** stopHeld() for a local endpoint; another machine's row has no hooks */
+    stopHeld(endpoint: string, options?: Parameters<RelayCore["stopHeld"]>[1]): boolean;
+    /** the endpoint's unacked count when a new delivery from `sender` would pass the inbox cap, else null */
+    private inboxFull;
+    /** a send the hub accepted for a local endpoint, stored under the hub's id with no deliveries, so replyTo() and a retried client_id work */
+    recordForward(from: string, params: SendParams, result: SendResult, origin?: {
+        tty?: boolean;
+    }): void;
+    /** the earlier result of a forwarded send with this client_id, or null; a different message under the same client_id is refused */
+    forwarded(from: string, params: SendParams): SendResult | null;
+    /** one delivery as the hub pushes it, or null when it is gone, acked or expired */
+    delivery(seq: number): Delivery | null;
+    /** the unacked deliveries to `machine`'s mirrored rows after `after` (xinbox rows after `xafter`), oldest first */
+    pending(machine: string, after: number, limit?: number, xafter?: number): Delivery[];
+    /**
+     * acks deliveries of `machine`'s mirrored rows only; each counts as received for the causal hop. A seq of xinbox moves its endpoint's
+     * cursor instead: one row per endpoint for the whole batch, no audit
+     */
+    ackOn(machine: string, seqs: unknown): number;
+    /** a delivery `machine`'s local policy refused: acked, and a status notice from the relay to the sender */
+    rejectOn(machine: string, seq: unknown, code: unknown): {
+        notice: {
+            seq: number;
+            endpoint: string;
+        } | null;
+    };
+    protected audit(event: string, endpoint: string | null, ref: string | null, detail: Record<string, unknown>): void;
+    /** an audit row from outside the core (hub events: machine binds, releases, revocations) */
+    record(event: string, endpoint: string | null, ref: string | null, detail: Record<string, unknown>): void;
+    /**
+     * drops what expired, and with xinbox the rows received over XINBOX_KEEP_MS ago that expired or were acked that long ago, keeping
+     * the highest seq they held as the floor of the next one
+     */
+    sweep(): void;
+    /** the mirrored row of `<machine>/<handle>` (a bridge's, never a direct client's), or null */
+    xendpoint(remote: string): XEndpoint | null;
+    /** the mirrored row an endpoint id is, or null for anything else */
+    xsender(endpoint: string): XEndpoint | null;
+    /** every mirrored row, for discovery */
+    xendpoints(): XEndpoint[];
+    /** the xinbox row `id` delivered to `<machine>/<handle>`, or null */
+    xreceived(endpoint: string, id: string): XInboxRow | null;
+    /** the earlier row of a message from `fromAccount` under `clientId`, or null */
+    xduplicate(fromAccount: string, clientId: string): {
+        id: string;
+        acked: boolean;
+    } | null;
+    /** what `fromAccount` sent here: from `sender` to `endpoint` in the last minute and hour (each with its oldest), and since `since` */
+    xcounts(fromAccount: string, sender: string, endpoint: string, since: number): {
+        minute: number;
+        minuteAt: number | null;
+        hour: number;
+        hourAt: number | null;
+        day: number;
+    };
+    /** an endpoint's unread messages: its unacked, unexpired xinbox rows and deliveries */
+    xunread(endpoint: XEndpoint): number;
+    /** the accounts whose xinbox rows may be read out now; null (unknown) reads none */
+    xsenders(accounts: Set<string> | null): void;
+    /** deletes the xinbox rows of every account but `keep`; how many it deleted */
+    xprune(keep: Set<string>): number;
+    xthreadCount(endpoint: string, thread: string): number;
+    /** one xinbox row under the next seq; null when a row of the same sender and client_id is there already */
+    xinsert(row: Omit<XInboxRow, "seq">): number | null;
+    /** a value of the cross-account state, written once */
+    xstate(key: string, init: () => string): string;
+    private xview;
+    /** unacked, unexpired xinbox rows of mirrored endpoints from the accounts xsenders() named, as deliveries, by `where` over `x` */
+    private xinboxPage;
+    /** the endpoint of an unacked xinbox seq of `machine`, or null */
+    private ownXinbox;
+    /**
+     * moves an endpoint's cursor over the leading run of its unacked, unexpired rows that `batch` names, in one write or none; a seq past
+     * a row it does not name stays unacked and replays. How many rows it moved over
+     */
+    private advanceCursor;
+    /** when the holder part of a mirrored agent's incarnation moved, drops its xinbox rows and deliveries: they were the earlier holder's */
+    private dropEarlierHolder;
+    /** keeps the highest xinbox seq as the floor of the next one, before rows are deleted */
+    private xfloor;
+    private ownDelivery;
+    private noticeTo;
+    private forwardHash;
+    /** a message from another account passes the recipient's in lists by `acct:`, or as a reply to the recipient's own message to that sender */
+    private checkForeignIn;
+    /** the stand-in row of another account's sender: `@<account>/<machine>/<handle>`, or `@<account>/me` for its human at a terminal */
+    private foreignProxy;
+    private proxyFor;
+    private checkEnvelope;
+    private parseView;
+    private diff;
+    private remoteView;
+    /**
+     * the place each agent of a mirror batch gets, worked out here: a root is a view with no parent and depth 0; a child sits one below its
+     * parent, which must be an agent this machine mirrors; anything else (a parent on another machine or not mirrored, a cycle, a root
+     * claiming depth) is unknown. Undefined when the view says nothing about its place.
+     */
+    private placer;
+    /** an agent row's place, rules, caps, title and incarnation after a view: what it left out stays, unless the endpoint is a new incarnation */
+    private scopeColumns;
+    /** wire caps of `machine` with their `ep:<handle>` references as this core's row ids; an endpoint the machine does not mirror is `gone`, which admits nothing */
+    private localCaps;
+    /** caps with this core's row ids named as `ep:<handle>`, as they cross machines */
+    private wireCaps;
+    private insertRemote;
+    private retire;
+    /** a new proxy row, within the endpoint cap */
+    private insertProxy;
+    private checkCap;
+    private checkMachine;
+    private byRemote;
+    /** a judge status notice to `endpoint` from the relay; its delivery seq */
+    judgeNoticeTo(endpoint: string, text: string): number;
+}
+
+type HubAuth = "account" | "account+bridge";
+type HubRole = "owner" | "admin" | "member";
+/** what the host proved about the token, plus its privilege */
+interface HubGrant {
+    tokenId: string;
+    userId: string;
+    actorId: string | null;
+    expiresAt: number;
+    /** a scoped token, not a full login; a grant that doesn't say false counts as scoped */
+    scoped: boolean;
+    /** the actor's org role; null on a personal account */
+    role: HubRole | null;
+    /** labels set on every endpoint the token claims or mirrors, over the client's own for the same keys */
+    labels?: Record<string, string>;
+}
+/** per-socket state; JSON-serialisable, so the host can persist it with the socket */
+interface HubConn {
+    id: string;
+    grant: HubGrant;
+    role: "new" | "client" | "bridge" | "observer";
+    /** the machine a bridge or agent client is bound to; a human's or observer's namespace for unqualified handles */
+    machine: string | null;
+    /** the hub endpoint id a client connection acts as */
+    endpoint: string | null;
+    watching: boolean;
+    subscribed: boolean;
+    /** whether a human client said a terminal is attached */
+    tty?: boolean;
+}
+/** a bound machine, or a revoked token's name kept as a tombstone */
+interface MachineRow {
+    name: string;
+    kind: string;
+    online: boolean;
+    bridge: boolean;
+    created_at: string | null;
+    last_seen: string | null;
+}
+interface HubSocket {
+    conn: HubConn;
+    send(text: string): void;
+    close(code: number, reason: string): void;
+}
+interface HubDeps {
+    sql: Sql;
+    /** synchronous sha256 hex */
+    hash: (value: string) => string;
+    /** runs fn in one synchronous storage transaction */
+    transaction?: <T>(fn: () => T) => T;
+    now?: () => number;
+    /** every live socket of this account (rebuilt from persisted state when the host restarts) */
+    sockets(): HubSocket[];
+    /** persist socket.conn after the hub changed it */
+    save(socket: HubSocket): void;
+    /** structured log line, e.g. relay_action; never bodies or tokens */
+    log?: (event: string, fields: Record<string, unknown>) => void;
+    /** overrides of {@link HUB_LIMITS}; `Infinity` disables a cap, count or byte limit, durations stay finite */
+    limits?: Partial<HubLimits>;
+    /** the link to other accounts' relays; without it an address of another account is not found */
+    crossAccount?: CrossAccountLink;
+}
+declare const HUB_LIMITS: {
+    readonly machines: 16;
+    readonly endpoints: 512;
+    readonly sockets: 64;
+    readonly frameBytes: 262144;
+    readonly callsPerMinute: 120;
+    readonly bridgeCallsPerMinute: 600;
+    readonly accountCallsPerMinute: 1200;
+    readonly acksPerMinute: 1200;
+    readonly accountAcksPerMinute: 4800;
+    readonly storedBytes: number;
+    readonly clientMachineIdleS: number;
+    readonly idlePurgeS: number;
+    readonly httpWaitS: 25;
+    readonly revalidateMs: 300000;
+    readonly deniedS: 3600;
+    readonly refusalsPerMinute: 10;
+};
+type HubLimits = {
+    [K in keyof typeof HUB_LIMITS]: number;
+};
+/** the hosted relay of one account: machines, bridges, direct clients, push and replay over a FederatedCore; pure, sockets are injected */
+declare class RelayHub {
+    private readonly deps;
+    private core;
+    private account;
+    private readonly now;
+    private readonly waiters;
+    private readonly buckets;
+    private readonly transient;
+    private readonly gone;
+    /** per machine, the full mirror its bridge is sending in several frames; lost on eviction, which only skips that sync's offline sweep */
+    private readonly syncs;
+    private stored;
+    private denied;
+    private xcounters;
+    private xkey;
+    private readonly limits;
+    constructor(deps: HubDeps);
+    /** idempotent: migrates and records the account handle (the address user part, e.g. "ada"); call before handling each request */
+    init(account: {
+        user: string;
+    }): void;
+    /** forgets the core and in-memory state after the object's storage was deleted; the next init migrates afresh */
+    reset(): void;
+    /** a fresh connection state for an accepted socket */
+    static connection(grant: HubGrant): HubConn;
+    /** a socket would exceed the `sockets` limit: the host refuses it (429) instead of accepting */
+    full(): boolean;
+    /** one JSON-RPC text frame from a socket; replies and pushes go out through socket.send */
+    message(socket: HubSocket, text: string): Promise<void>;
+    /** the socket closed (any reason) */
+    closed(socket: HubSocket): void;
+    /** POST /v1/relay/rpc: a JSON-RPC request or batch run in order on a short-lived connection; returns the response(s) */
+    batch(grant: HubGrant, body: unknown): Promise<unknown>;
+    /**
+     * closes every socket (and in-flight /rpc call) whose grant matches with 1008, audits it, and unbinds the machines
+     * the matching grants bound behind a tombstone of their member, keeping their endpoint rows and queued messages;
+     * returns how many closed
+     */
+    revoke(match: {
+        tokenId?: string;
+        userId?: string;
+        actorId?: string;
+    }): number;
+    /**
+     * the host's alarm: revalidates each socket's grant and sweeps; returns the next alarm time in ms, or null. A failed
+     * check closes with 1008, an expired grant with 4001 (reconnect for a new one). A check that throws keeps the
+     * sockets and retries in 30 s; once a token's checks kept throwing for the `revalidateMs` limit its sockets close
+     * with the retryable 1013.
+     */
+    alarm(validate: (grant: HubGrant) => Promise<boolean>): Promise<number | null>;
+    /** when the next alarm should fire (earliest grant expiry, revalidation or its retry after an error, sweep, retention), or null when the hub holds nothing */
+    nextAlarm(): number | null;
+    /** the account held no machines, tombstones, sockets or queued messages for the `idlePurgeS` limit: the object may delete its storage */
+    purgeDue(): boolean;
+    /** while the hub holds rows: the earliest unacked delivery's expiry, at most a day and at least a minute away */
+    private retentionAlarm;
+    /** no machine bound or tombstoned, no live socket and nothing queued */
+    private idle;
+    private get relay();
+    private handle;
+    /**
+     * one call from the token's bucket for the connection's role (a bridge, or a bridge hello, has its own, larger one)
+     * and from the account's; acks (one token per seq) and rejects spend from separate ack buckets of the token and the
+     * account instead, so they never starve calls, and an activity event is refused once either call bucket is below a
+     * quarter, so sends keep the rest
+     */
+    private spend;
+    private bucket;
+    private dispatch;
+    private hello;
+    /** refuses a machine bound to another token, a revoked token's machine to anyone but its member or an admin, or one past the machine cap; returns whether this token already holds it */
+    private bindable;
+    /** binds the machine to the token once its hello succeeded; `held` is what bindable() returned */
+    private bind;
+    private clientMethod;
+    private bridgeMethod;
+    /**
+     * A bridge's forward to another account's endpoint, writing no row here: shape, the contact, the sender on this account's allowlist,
+     * its scope (or the reply grant of the message it answers), the caps, the scrubber, the egress gate, then the peer relay. Anything
+     * unresolvable is not_found, as for a missing endpoint.
+     */
+    private xsend;
+    /**
+     * A message from the account `fromAccountId`'s relay (the host's internal route, never a client): the contact, the target on this
+     * account's allowlist, its scope (or the reply grant), shape, a retry's earlier answer, the scrubber, the ingress gate, then one xinbox
+     * row pushed to the target's bridge. Anything unresolvable is not_found, as for a missing endpoint.
+     */
+    xreceive(fromAccountId: string, raw: unknown, judged?: boolean): Promise<XDelivered>;
+    /** this account's endpoints the account `fromAccountId` may reach under its contact's allowlist: address, harness and presence only */
+    xlist(fromAccountId: string): Promise<XListed[]>;
+    /**
+     * throws when one more message from `fromAccountId` would pass a cap of this side: the pair a minute and an hour and the contact a
+     * day (the lower of this account's limits for the contact and the sender's declared ones), the thread, the account's stored bytes or
+     * the target's unread messages; counted from xinbox itself, so a wake keeps them
+     */
+    private xadmit;
+    /**
+     * deletes the queued messages of every account that is no longer an active contact allowed to message this one, after the
+     * contacts changed; nothing when the contacts cannot be loaded
+     */
+    xprune(): Promise<void>;
+    /** the accounts whose messages this account takes now: active contacts with dir in or both; null when they cannot be loaded */
+    private xinbound;
+    /** what every contact this account may message lets it reach */
+    private contactList;
+    private delivered;
+    /** the body's bytes when the account can hold them; refuses a send past the `storedBytes` limit */
+    private room;
+    /** bytes of message bodies held, and of the messages from other accounts */
+    private storedNow;
+    private stash;
+    /** wakes direct waiters and pushes a delivery for a mirrored row to the subscribed bridge of its machine */
+    private route;
+    /** a machine's endpoint changes: `endpoints` to the other bridges, presence and status to watchers */
+    private announce;
+    /** a direct client's endpoint changed: the other bridges mirror it */
+    private announceEndpoint;
+    private toBridges;
+    private fleet;
+    private write;
+    private save;
+    private waitMs;
+    private wake;
+    private waitFor;
+    private awaitReply;
+    private kick;
+    private release;
+    /** the machine a bridge or agent client connection holds; a human's or observer's machine is only a namespace */
+    private boundMachine;
+    /** machines a live connection holds */
+    private liveMachines;
+    /** bindings, then names a revoke left behind (kind `revoked`) */
+    /** a read-only view of the account for a dashboard: its machines, listed endpoints and latest activity */
+    overview(activity?: number): {
+        machines: MachineRow[];
+        endpoints: EndpointView[];
+        activity: ActivityRow[];
+    };
+    private machineList;
+    /** only the token the machine is bound to, a full login of the member who bound it, or an admin may release it (or a revoked token's name) */
+    private releaseMachine;
+    /** releases client bindings with no live connection, idle for the `clientMachineIdleS` limit, with nothing queued and no unanswered ask open; bridge bindings never expire */
+    private expireMachines;
+    /** drops the tombstones past their age with nothing queued for their machine, and retires the rows and xinbox of each name still unbound */
+    private forgetTombstones;
+    /** the hub_state keys (`denied:<tokenId>`) of tokens revoked lately, to when; loaded once per object lifetime */
+    private deniedGrants;
+    /** a token revoked lately is refused even when the host accepted its grant before the revoke reached the object */
+    private refuseDenied;
+    private tx;
+    private state;
+    private setState;
+    /**
+     * a held cross-account message its account's human released (the host claimed the hold first): the rest of that side's path, with
+     * every check run again and only the gate skipped. Egress sends as the stored sender with the time left, under the hold id its sender
+     * got, and with the message's own client id, so the peer answers both a retried release and the sender's retry of the original as the
+     * duplicate. Ingress runs xreceive again
+     */
+    xrelease(hold: XRelease): Promise<SendResult | XDelivered>;
+    /** a status message from the relay to one of this account's endpoints (a held message's sender), pushed to its bridge */
+    xnotice(endpoint: string, text: string): void;
+}
+
+export { type Delivery, FederatedCore, type FederatedOptions, HUB_LIMITS, type HubAuth, type HubConn, type HubDeps, type HubGrant, type HubLimits, type HubRole, type HubSocket, MACHINE_NAME, type MachineRow, type MirrorCaps, type MirrorChange, type MirrorRules, type MirrorScope, type MirrorView, type RelayAuth, RelayHub, type RemoteView, type XEndpoint };