@scp-dev/hub 0.2.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scp-dev/hub",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Swarm Communication Protocol federation and account hub: mirrored endpoints across machines, bridges, direct clients and cross-account delivery.",
   "license": "Apache-2.0",
   "homepage": "https://scp.dev",
@@ -29,7 +29,7 @@
     "typecheck": "tsc -p ."
   },
   "dependencies": {
-    "@scp-dev/core": "0.1.2"
+    "@scp-dev/core": "0.1.4"
   },
   "devDependencies": {
     "tsup": "^8.5.1"

package/src/federation.ts

@@ -43,6 +43,8 @@ import {
   validHandle,
   validHarness,
   validSelector,
+  type Wake,
+  WAKES,
 } from "@scp-dev/core"
 
 export type RelayAuth = Envelope["from"]["auth"]
@@ -121,6 +123,8 @@ export 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
 }
@@ -142,6 +146,7 @@ interface ParsedScope {
   rules?: MirrorRules | null
   caps?: ScopeCaps | null
   title?: string | null
+  wake?: Wake | null
   incarnation?: string | null
 }
 
@@ -1038,6 +1043,22 @@ export class FederatedCore extends RelayCore {
     })
   }
 
+  /**
+   * 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 {
+    this.tx(() => {
+      const message = one<{ expires_at: number }>(this.sql, `SELECT expires_at FROM messages WHERE id = ?`, messageId)
+      if (!message) return
+      for (const endpoint of endpoints) {
+        if (this.machineOf(endpoint) === null) continue
+        if (one(this.sql, `SELECT 1 FROM deliveries WHERE message_id = ? AND endpoint = ?`, messageId, endpoint)) continue
+        this.insertDelivery(messageId, endpoint, message.expires_at)
+      }
+    })
+  }
+
   /** 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 {
     const clientId = cleanText(params.client_id, "client_id", 128)
@@ -1593,7 +1614,7 @@ export class FederatedCore extends RelayCore {
     const was = this.view(before)
     const presence = was.presence !== view.presence
     const status = before.status_state !== after.status_state || before.status_note !== after.status_note
-    const other = (["kind", "harness", "model", "cwd", "labels", "title", "tree", "parent_ep", "depth", "rules", "caps", "incarnation"] as const).some(
+    const other = (["kind", "harness", "model", "cwd", "labels", "title", "wake", "tree", "parent_ep", "depth", "rules", "caps", "incarnation"] as const).some(
       (field) => before[field] !== (after as FederatedRow)[field],
     )
     return presence || status || other ? { view, added: false, presence, status } : null
@@ -1666,6 +1687,7 @@ export class FederatedCore extends RelayCore {
       rules: rules === undefined ? row.rules : rules && (rules.in || rules.out) ? JSON.stringify(rules) : null,
       caps,
       title: scope.title !== undefined ? scope.title : fresh ? null : row.title,
+      wake: scope.wake !== undefined ? scope.wake : fresh ? null : row.wake,
       incarnation: scope.incarnation ?? row.incarnation,
     }
   }
@@ -1844,6 +1866,7 @@ function parseScope(view: Partial<MirrorView>): ParsedScope {
     throw new RelayError("too_large", `an endpoint's rules and caps are more than ${SCOPE_BYTES} bytes`)
   if (given("title"))
     out.title = view.title === null ? null : cleanText(typeof view.title === "string" ? view.title.replace(/\s+/g, " ") : view.title, "title", 64) || null
+  if (given("wake")) out.wake = typeof view.wake === "string" && view.wake !== "none" && WAKES.includes(view.wake as Wake) ? (view.wake as Wake) : null
   if (given("incarnation")) {
     if (view.incarnation !== null && (typeof view.incarnation !== "string" || !INCARNATION.test(view.incarnation))) throw bad("incarnation")
     out.incarnation = view.incarnation ?? null

package/src/hub.ts

@@ -18,6 +18,7 @@ import {
   honestSender,
   joinRedacted,
   judgeDetailForAgents,
+  type JudgePolicy,
   LIMITS,
   MESSAGE_KINDS,
   type MessageKind,
@@ -37,6 +38,7 @@ import {
   SYSTEM_HANDLE,
   sameSecret,
   untilTomorrow,
+  type Wake,
   type XContact,
   XCounters,
   type XDelivered,
@@ -48,6 +50,7 @@ import {
   xlimits,
 } from "@scp-dev/core"
 import { FederatedCore, MACHINE_NAME, type MirrorChange, type XEndpoint } from "./federation"
+import { type Deliver, type HoldView, type JudgeClientFactory, JudgeGate, type JudgeLimits } from "./judge-gate"
 
 export type HubAuth = "account" | "account+bridge"
 
@@ -102,7 +105,7 @@ export 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 */
@@ -145,6 +148,16 @@ export interface HubDeps {
   crossAccount?: CrossAccountLink
 }
 
+/** what a configured judge needs besides its policy */
+export 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
+}
+
 export const HUB_LIMITS = {
   machines: 16,
   endpoints: 512,
@@ -276,6 +289,8 @@ export class RelayHub {
   private xcounters: XCounters | null = null
   private xkey: string | null = null
   private readonly limits: Readonly<HubLimits>
+  private judgeConfig: { policy: JudgePolicy; options: HubJudgeOptions } | null = null
+  private gate: JudgeGate | null = null
 
   constructor(private readonly deps: HubDeps) {
     this.now = deps.now ?? Date.now
@@ -303,6 +318,7 @@ export class RelayHub {
     })
     core.migrate()
     this.core = core
+    this.gate = null
     this.account = account.user
     if (this.deps.crossAccount) {
       this.xkey = core.xstate("key", () => randomHex(32))
@@ -318,10 +334,40 @@ export class RelayHub {
     this.denied = null
     this.xcounters = null
     this.xkey = null
+    this.gate = null
     this.buckets.clear()
     this.gone.clear()
   }
 
+  /**
+   * 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 = { env: {} }): void {
+    this.gate = null
+    this.judgeConfig = policy && policy.mode !== "off" ? { policy, options } : null
+  }
+
+  /** the held messages, newest first, without bodies */
+  holds(state?: string): HoldView[] {
+    return this.judged().holds(state)
+  }
+
+  /** one hold with its body while it waits */
+  holdShow(id: string): ReturnType<JudgeGate["show"]> {
+    return this.judged().show(id)
+  }
+
+  /** delivers a held message as its sender, every send check run again */
+  holdRelease(id: string, options: { redacted?: boolean; by: string }): Promise<SendResult> {
+    return this.judged().release(id, options, this.deliverJudged)
+  }
+
+  /** refuses a held message: never delivered, its sender told why */
+  holdRefuse(id: string, reason: string, by: string): HoldView {
+    return this.judged().refuse(id, reason, by)
+  }
+
   /** a fresh connection state for an accepted socket */
   static connection(grant: HubGrant): HubConn {
     return { id: newId("conn"), grant, role: "new", machine: null, endpoint: null, watching: false, subscribed: false }
@@ -483,6 +529,7 @@ export class RelayHub {
       this.gone.clear()
       for (const [key, bucket] of this.buckets) if (bucket.tokens + ((now - bucket.at) * bucket.rate) / 60_000 >= bucket.rate) this.buckets.delete(key)
       this.xcounters?.prune()
+      this.judgeGate()?.sweep()
       this.setState("last_sweep", now)
     }
     if (this.idle(now)) {
@@ -835,11 +882,12 @@ export class RelayHub {
         const send = { ...(params as unknown as SendParams) }
         delete (send as Params).wait_s
         if (method === "ask") send.kind = "request"
-        const bytes = this.room(me, send.body)
-        const result = core.within(conn.machine, () => core.send(me, send, conn.tty === undefined ? {} : { tty: conn.tty }))
-        if (!result.duplicate) this.stash(bytes)
-        if (!result.duplicate) this.delivered(me, result, send.kind ?? "message")
-        if (method === "send") return result
+        const origin = conn.tty === undefined ? {} : { tty: conn.tty }
+        const gate = this.judgeGate()
+        const result = gate
+          ? await gate.send(me, send, { ...origin, machine: conn.machine }, this.deliverJudged)
+          : this.deliverOn(conn.machine, me, send, origin)
+        if (method === "send" || result.held) return result
         return this.awaitReply(socket, me, result.id, this.waitMs(socket, params.wait_s), result)
       }
       case "ask_wait": {
@@ -915,11 +963,10 @@ export class RelayHub {
         delete send.attachments
         const floor = Math.min(asked as number, LIMITS.hopMax + 1)
         if (floor > 0) core.markReceived(sender, floor - 1)
-        const bytes = this.room(sender, send.body)
-        const result = core.within(machine, () => core.send(sender, send as unknown as SendParams, { tty: params.tty === true }))
-        if (!result.duplicate) this.stash(bytes)
-        if (!result.duplicate) this.delivered(sender, result, (send.kind as string | undefined) ?? "message")
-        return result
+        const gate = this.judgeGate()
+        const origin = { tty: params.tty === true }
+        if (gate) return gate.send(sender, send as unknown as SendParams, { ...origin, machine }, this.deliverJudged)
+        return this.deliverOn(machine, sender, send as unknown as SendParams, origin)
       }
       case "subscribe": {
         const after = params.after ?? 0
@@ -1273,6 +1320,49 @@ export class RelayHub {
     )
   }
 
+  // judge
+
+  /** the judge, made on first use once configured; null when it is not */
+  private judgeGate(): JudgeGate | null {
+    if (!this.judgeConfig) return null
+    if (this.gate) return this.gate
+    const core = this.relay
+    const { policy, options } = this.judgeConfig
+    const gate = new JudgeGate({
+      sql: this.deps.sql,
+      core,
+      now: this.now,
+      env: options.env,
+      client: options.client,
+      limits: options.limits,
+      log: (line) => this.deps.log?.("relay_judge", { account: this.account, line }),
+      wake: (endpoint) => this.wake(endpoint),
+      notice: (endpoint, text) => this.xnotice(endpoint, text),
+      within: (origin, fn) => core.within(origin.machine ?? null, fn),
+    })
+    gate.configure(policy)
+    this.gate = gate
+    return gate
+  }
+
+  private judged(): JudgeGate {
+    const gate = this.judgeGate()
+    if (!gate) throw new RelayError("not_found", "this relay has no judge")
+    return gate
+  }
+
+  /** 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(machine: string | null, from: string, send: SendParams, origin: { tty?: boolean }): SendResult {
+    const core = this.relay
+    const bytes = this.room(from, send.body)
+    const result = core.within(machine, () => core.send(from, send, origin))
+    if (!result.duplicate) this.stash(bytes)
+    if (!result.duplicate) this.delivered(from, result, send.kind ?? "message")
+    return result
+  }
+
+  private readonly deliverJudged: Deliver = async (from, send, { machine, ...origin }) => this.deliverOn(machine ?? null, from, send, origin)
+
   // push and wait
 
   private delivered(from: string, result: SendResult, kind: string): void {
@@ -1504,7 +1594,7 @@ export class RelayHub {
   /** a read-only graph for a dashboard: listed endpoints, spawn edges among them, and message counts per sender and recipient; never a body */
   graph(minutes = GRAPH_MINUTES): HubGraph {
     const window = Math.min(Math.max(1, Math.floor(Number.isFinite(minutes) ? minutes : GRAPH_MINUTES)), GRAPH_MINUTES_MAX)
-    const endpoints = this.relay.list() as (EndpointView & { wake?: string | null })[]
+    const endpoints = this.relay.list()
     const byId = new Map(endpoints.map((e) => [e.id, e.address]))
     const listed = new Set(byId.values())
     const nodes: GraphNode[] = endpoints.map((e) => ({

package/src/index.ts

@@ -23,9 +23,20 @@ export {
   type HubAuth,
   type HubConn,
   type HubDeps,
+  type HubJudgeOptions,
   type HubGrant,
   type HubLimits,
   type HubRole,
   type HubSocket,
   type MachineRow,
 } from "./hub"
+export {
+  type Deliver,
+  type HoldView,
+  JUDGE_LIMITS,
+  type JudgeClientFactory,
+  JudgeGate,
+  type JudgeGateOptions,
+  type JudgeLimits,
+  type Origin as JudgeOrigin,
+} from "./judge-gate"