@scp-dev/hub 0.2.0 → 0.3.1

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-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';
+import * as _scp_dev_core from '@scp-dev/core';
+import { Envelope, RelayCore, CoreOptions, EndpointRow, PolicySubject, ScopeSubject, ScopeNode, ScopeDirection, Admission, MessageRow, EndpointView, ScopeCap, ScopeEntry, Claim, SendParams, SendResult, EndpointKind, Presence, StatusState, Verdict, JudgeModelConfig, JudgeClient, Sql, JudgePolicy, Wake, CrossAccountLink, XDelivered, XListed, ActivityRow, XRelease } from '@scp-dev/core';
 
 type RelayAuth = Envelope["from"]["auth"];
 /** a machine name: one relay host of an account */
@@ -58,6 +59,8 @@ interface MirrorView extends MirrorScope {
     presence?: Presence;
     last_seen?: string | null;
     title?: string | null;
+    /** an agent's {@link Wake}; a value this hub does not know is kept as none */
+    wake?: string | null;
     /** the handle the endpoint had before a rename: its mirror is renamed in place */
     was?: string;
 }
@@ -273,6 +276,11 @@ declare class FederatedCore extends RelayCore {
     recordForward(from: string, params: SendParams, result: SendResult, origin?: {
         tty?: boolean;
     }): void;
+    /**
+     * records that a forwarded message reached mirrored endpoints of other machines, unacknowledged, as a hub's delivery rows would: their
+     * replies then join its thread here. For links that deliver machine to machine; a hub bridge never needs it
+     */
+    recordRemoteDelivery(messageId: string, endpoints: string[]): 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 */
@@ -380,6 +388,139 @@ declare class FederatedCore extends RelayCore {
     judgeNoticeTo(endpoint: string, text: string): number;
 }
 
+type JudgeClientFactory = (model: JudgeModelConfig, key: () => Promise<string>) => JudgeClient;
+/** `machine`: the hub machine a direct client's unqualified addresses resolve on */
+type Origin = {
+    tty?: boolean;
+    unverified?: boolean;
+    machine?: string | null;
+};
+/** sends as `from` through the same path an unjudged send takes, waking recipients */
+type Deliver = (from: string, params: SendParams, origin: Origin) => Promise<SendResult>;
+interface JudgeGateOptions {
+    sql: Sql;
+    core: FederatedCore;
+    now: () => number;
+    /** where key_env is read */
+    env: Record<string, string | undefined>;
+    client?: JudgeClientFactory | undefined;
+    log: (line: string) => void;
+    /** an endpoint got a notice */
+    wake: (endpoint: string) => void;
+    /** a status notice to a hold's sender; default core.judgeNotice, then wake */
+    notice?: ((endpoint: string, text: string) => void) | undefined;
+    /** runs fn where the sender's unqualified addresses resolve (default: as it is) */
+    within?: (<T>(origin: Origin, fn: () => T) => T) | undefined;
+    /** the reader of a model's key_file; without one a key_file model judges with the prefilter only */
+    keyFile?: ((path: string) => (() => Promise<string>) | null) | undefined;
+    /** overrides of {@link JUDGE_LIMITS}; `Infinity` disables a cap */
+    limits?: Partial<JudgeLimits> | undefined;
+}
+/** judged sends per sender and lineage tree, and a sender's waiting holds */
+interface JudgeLimits {
+    endpointPerMinute: number;
+    endpointPerHour: number;
+    treePerMinute: number;
+    treePerHour: number;
+    heldPerSender: number;
+}
+/** held sends never reach the send's rate limits, so they are capped here */
+declare const JUDGE_LIMITS: Readonly<JudgeLimits>;
+interface HoldRow {
+    id: string;
+    from_ep: string;
+    params: string;
+    origin: string;
+    verdict: string;
+    created_at: number;
+    expires_at: number;
+    state: "held" | "releasing" | "released" | "refused" | "expired";
+    by: string | null;
+    resolved_at: number | null;
+}
+/** a hold as the human's review lists it: never the body */
+interface HoldView {
+    id: string;
+    from: string;
+    to: string[];
+    state: HoldRow["state"];
+    created_at: string;
+    expires_at: string;
+    categories: string[];
+    reason: string;
+    boundary: string;
+    source: Verdict["source"];
+    bytes: number;
+    by: string | null;
+    resolved_at: string | null;
+}
+/**
+ * a judge in front of a relay's sends (the broker's policy `judge`, or a hosted hub's) (policy `judge`): shadow judges after delivery and only audits; enforce judges before delivery and passes,
+ * redacts, refuses or holds. Holds wait in `judge_holds` for the human at a terminal; their body is purged once resolved or expired
+ */
+declare class JudgeGate {
+    private readonly o;
+    readonly stats: _scp_dev_core.JudgeStats;
+    private policy;
+    private version;
+    private client;
+    private readonly cache;
+    private readonly shadows;
+    /** judged sends in the last hour per budget: `ep:<id>`, `tree:<root id>` and `*` for the whole broker */
+    private readonly spent;
+    private readonly limits;
+    constructor(o: JudgeGateOptions);
+    /** the policy's judge section; a model client only when its key is readable, else the prefilter alone */
+    configure(policy: JudgePolicy | undefined): void;
+    private keyReader;
+    /** resolves once every shadow judgement started so far finished */
+    settled(): Promise<void>;
+    /** a send or ask through the judge; an unjudged one goes straight to `deliver` */
+    send(from: string, params: SendParams, origin: Origin, deliver: Deliver): Promise<SendResult>;
+    /** an earlier judged send or waiting hold under the send's client_id: the same message is answered as before, another one refused as core refuses it */
+    private seen;
+    private remember;
+    /**
+     * a judged send counts before any model call against its sender's, its lineage tree's and the whole broker's budget, since refused and
+     * held sends never reach the send's own limits, and a new handle or a helper process must not bring a fresh budget
+     */
+    private spend;
+    /** how many budgets are tracked (idle ones are evicted by the sweep) */
+    budgetKeys(): number;
+    /** the held messages, newest first, without bodies */
+    holds(state?: string): HoldView[];
+    /** one hold with its body and the judge's redactions while it waits */
+    show(id: string): HoldView & {
+        body?: string;
+        redactions?: {
+            quote?: string;
+            kind: string;
+        }[];
+    };
+    /** delivers a held message as its sender, as stored or redacted: scope, policy and limits are checked again by the send itself */
+    release(id: string, options: {
+        redacted?: boolean;
+        by: string;
+    }, deliver: Deliver): Promise<SendResult>;
+    /** refuses a held message: it is never delivered, and its sender hears the human's reason */
+    refuse(id: string, reason: string, by: string): HoldView;
+    /** expires holds past their message TTL (body purged, sender told) and drops resolved ones past the audit window */
+    sweep(): void;
+    private expire;
+    /** the recipients by the boundary their message crosses; throws as send does for a target the sender cannot reach */
+    private boundaries;
+    private judge;
+    private shadow;
+    private hold;
+    private detail;
+    private storedDetail;
+    /** marks a hold resolved and purges its body and the judge's quotes of it */
+    private resolve;
+    private tell;
+    private row;
+    private view;
+}
+
 type HubAuth = "account" | "account+bridge";
 type HubRole = "owner" | "admin" | "member";
 /** what the host proved about the token, plus its privilege */
@@ -428,7 +569,7 @@ interface GraphNode {
     status: EndpointView["status"];
     last_seen: string | null;
     parent: string | null;
-    wake?: string | null;
+    wake?: Wake | null;
 }
 /** `spawn`: parent to child; `message`: sender to recipient, with the count and newest send in the graph's window */
 type GraphEdge = {
@@ -475,6 +616,15 @@ interface HubDeps {
     /** the link to other accounts' relays; without it an address of another account is not found */
     crossAccount?: CrossAccountLink;
 }
+/** what a configured judge needs besides its policy */
+interface HubJudgeOptions {
+    /** where the model's key_env is read */
+    env: Record<string, string | undefined>;
+    /** the model client (default the provider's HTTP API) */
+    client?: JudgeClientFactory | undefined;
+    /** overrides of the judge's own caps; `Infinity` disables one */
+    limits?: Partial<JudgeLimits> | undefined;
+}
 declare const HUB_LIMITS: {
     readonly machines: 16;
     readonly endpoints: 512;
@@ -513,6 +663,8 @@ declare class RelayHub {
     private xcounters;
     private xkey;
     private readonly limits;
+    private judgeConfig;
+    private gate;
     constructor(deps: HubDeps);
     /** idempotent: migrates and records the account handle (the address user part, e.g. "ada"); call before handling each request */
     init(account: {
@@ -520,6 +672,22 @@ declare class RelayHub {
     }): void;
     /** forgets the core and in-memory state after the object's storage was deleted; the next init migrates afresh */
     reset(): void;
+    /**
+     * judges this account's own sends (client send and ask, bridge forward) before delivery; sends to other accounts are left to the
+     * cross-account gate. Without a policy, or with mode off, the hub holds no judge and creates no judge tables
+     */
+    configureJudge(policy: JudgePolicy | undefined, options?: HubJudgeOptions): void;
+    /** the held messages, newest first, without bodies */
+    holds(state?: string): HoldView[];
+    /** one hold with its body while it waits */
+    holdShow(id: string): ReturnType<JudgeGate["show"]>;
+    /** delivers a held message as its sender, every send check run again */
+    holdRelease(id: string, options: {
+        redacted?: boolean;
+        by: string;
+    }): Promise<SendResult>;
+    /** refuses a held message: never delivered, its sender told why */
+    holdRefuse(id: string, reason: string, by: string): HoldView;
     /** 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 */
@@ -602,6 +770,12 @@ declare class RelayHub {
     private xinbound;
     /** what every contact this account may message lets it reach */
     private contactList;
+    /** the judge, made on first use once configured; null when it is not */
+    private judgeGate;
+    private judged;
+    /** a send of this account as it runs unjudged: room for the body, the core send on the sender's machine, then push */
+    private deliverOn;
+    private readonly deliverJudged;
     private delivered;
     /** the body's bytes when the account can hold them; refuses a send past the `storedBytes` limit */
     private room;
@@ -668,4 +842,4 @@ declare class RelayHub {
     xnotice(endpoint: string, text: string): void;
 }
 
-export { type Delivery, FederatedCore, type FederatedOptions, GRAPH_MINUTES, GRAPH_MINUTES_MAX, type GraphEdge, type GraphNode, HUB_LIMITS, type HubAuth, type HubConn, type HubDeps, type HubGrant, type HubGraph, 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 };
+export { type Deliver, type Delivery, FederatedCore, type FederatedOptions, GRAPH_MINUTES, GRAPH_MINUTES_MAX, type GraphEdge, type GraphNode, HUB_LIMITS, type HoldView, type HubAuth, type HubConn, type HubDeps, type HubGrant, type HubGraph, type HubJudgeOptions, type HubLimits, type HubRole, type HubSocket, JUDGE_LIMITS, type JudgeClientFactory, JudgeGate, type JudgeGateOptions, type JudgeLimits, type Origin as JudgeOrigin, MACHINE_NAME, type MachineRow, type MirrorCaps, type MirrorChange, type MirrorRules, type MirrorScope, type MirrorView, type RelayAuth, RelayHub, type RemoteView, type XEndpoint };