@scp-dev/hub 0.6.2 → 0.7.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _scp_dev_core from '@scp-dev/core';
-import { Envelope, RelayCore, CoreOptions, EndpointRow, EndpointView, PolicySubject, ScopeSubject, ScopeNode, ScopeDirection, Admission, MessageRow, ScopeCap, ScopeEntry, Claim, SendParams, SendResult, EndpointKind, Presence, StatusState, Verdict, JudgeModelConfig, JudgeClient, Sql, JudgePolicy, Wake, CrossAccountLink, XDelivered, XListed, ActivityRow, XRelease } from '@scp-dev/core';
+import { Envelope, RelayCore, CoreOptions, EndpointRow, EndpointView, PolicySubject, ScopeSubject, ScopeNode, ScopeDirection, Admission, MessageRow, ScopeCap, ScopeEntry, Claim, SendParams, SendResult, EndpointKind, Presence, StatusState, Verdict, JudgeModelConfig, JudgeClient, Sql, JudgePolicy, Wake, CrossAccountLink, WakeDecline, XDelivered, XListed, ActivityRow, XRelease } from '@scp-dev/core';
 
 type RelayAuth = Envelope["from"]["auth"];
 /** a machine name: one relay host of an account */
@@ -175,8 +175,12 @@ declare class FederatedCore extends RelayCore {
     protected renamedHandle(from: string, to: string): void;
     protected linkedAcross(a: EndpointRow, b: EndpointRow): boolean;
     protected linkedParent(row: EndpointRow, shown?: Set<string>): string | null;
-    /** a live mirrored row shows the presence its machine mirrored, not one its last_seen decays to here */
+    /**
+     * a live mirrored row shows the presence its machine mirrored, not one its last_seen decays to here; a hibernated one stays hibernated with
+     * its hook wake after its bridge closed
+     */
     protected view(row: EndpointRow, shown?: Set<string>): EndpointView;
+    protected hibernated(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 */
@@ -575,6 +579,8 @@ interface MachineRow {
     bridge: boolean;
     created_at: string | null;
     last_seen: string | null;
+    /** a machine waker URL is set; the URL and its secret are never shown */
+    wake?: boolean;
 }
 /** an endpoint as the dashboard graph draws it */
 interface GraphNode {
@@ -640,6 +646,24 @@ interface HubSocket {
     send(text: string): void;
     close(code: number, reason: string): void;
 }
+/** what a machine waker gets: who to wake and the message's metadata, never its body */
+interface MachineWakeEvent {
+    scp: 1;
+    event: "machine_wake";
+    account: string;
+    machine: string;
+    endpoints: string[];
+    message: {
+        id: string;
+        from: string;
+        kind: string;
+        thread: string;
+        created_at: string;
+    };
+    /** the sender's account handle; another account's sender never chooses the credentials a wake uses */
+    from_account: string;
+    same_account: boolean;
+}
 interface HubDeps {
     sql: Sql;
     /** synchronous sha256 hex */
@@ -659,6 +683,22 @@ interface HubDeps {
     limits?: Partial<HubLimits>;
     /** the link to other accounts' relays; without it an address of another account is not found */
     crossAccount?: CrossAccountLink;
+    /** an HTTP client for machine waker URLs; without it (and without `machineWake`) no machine waker is called */
+    fetch?: (url: string, init: {
+        method: string;
+        headers: Record<string, string>;
+        body: string;
+        signal?: AbortSignal;
+    }) => Promise<{
+        status: number;
+        text?: () => Promise<string>;
+    }>;
+    /** the embedder's own machine waker, called in-process for any machine in place of a registered URL; metadata only, never a body or secret */
+    machineWake?: (event: MachineWakeEvent) => Promise<{
+        ok: boolean;
+        status?: number;
+        declined?: WakeDecline;
+    }>;
 }
 /** what a configured judge needs besides its policy */
 interface HubJudgeOptions {
@@ -717,6 +757,8 @@ declare class RelayHub {
     private readonly limits;
     private judgeConfig;
     private gate;
+    /** per machine, when its waker may be called next and the calls that failed in a row */
+    private readonly machineWakes;
     constructor(deps: HubDeps);
     /** idempotent: migrates and records the account handle (the address user part, e.g. "ada"); call before handling each request */
     init(account: {
@@ -839,8 +881,18 @@ declare class RelayHub {
     /** 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 */
+    /**
+     * wakes direct waiters and pushes a delivery for a mirrored row to the subscribed bridge of its machine; with none subscribed, a hibernated
+     * row's machine waker is called
+     */
     private route;
+    /** sets or (with a null url) clears the bridge's own machine waker: an https URL (http only to this host) and the secret that signs its calls */
+    private setMachineWake;
+    /**
+     * calls `machine`'s waker for its hibernated `recipient`: the embedder's `machineWake`, else the registered URL, signed. At most once per
+     * debounce window (doubling after failures); a decline counts toward nothing and holds calls for that message and its sender. Metadata only
+     */
+    private machineWake;
     /** 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 */
@@ -900,4 +952,4 @@ declare class RelayHub {
     xnotice(endpoint: string, text: string): void;
 }
 
-export { type DashboardEvent, type Deliver, type Delivery, FederatedCore, type FederatedOptions, GRAPH_MINUTES, GRAPH_MINUTES_MAX, type GraphEdge, type GraphMachine, 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, LOCAL_EVENTS, LOCAL_EVENT_KINDS, MACHINE_NAME, type MachineRow, type MirrorCaps, type MirrorChange, type MirrorRules, type MirrorScope, type MirrorView, type RelayAuth, RelayHub, type RemoteView, type XEndpoint, dashboardEvent };
+export { type DashboardEvent, type Deliver, type Delivery, FederatedCore, type FederatedOptions, GRAPH_MINUTES, GRAPH_MINUTES_MAX, type GraphEdge, type GraphMachine, 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, LOCAL_EVENTS, LOCAL_EVENT_KINDS, MACHINE_NAME, type MachineRow, type MachineWakeEvent, type MirrorCaps, type MirrorChange, type MirrorRules, type MirrorScope, type MirrorView, type RelayAuth, RelayHub, type RemoteView, type XEndpoint, dashboardEvent };

package/dist/index.js

@@ -13,6 +13,7 @@ import {
   MESSAGE_KINDS,
   newId,
   one,
+  PRESENCES,
   randomHex,
   RelayCore,
   RelayError,
@@ -31,7 +32,7 @@ var MACHINE_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/;
 var REMOTE = /^[a-z0-9][a-z0-9._-]{0,63}\/([a-z0-9][a-z0-9._-]{0,62})?$/;
 var MESSAGE_ID = /^[a-z]{2,8}_[a-z0-9]{8,64}$/;
 var AUTHS = ["local-uid", "account", "account+bridge", "contact"];
-var PRESENCES = ["online", "idle", "offline"];
+var HOOK_WAKE = /^hook:[a-z0-9][a-z0-9-]{0,31}$/;
 var UNKNOWN = { tree: null, parent_ep: null, depth: null };
 var REFS = /* @__PURE__ */ new Set(["human", "policy", "inherited", "gone"]);
 var INCARNATION = /^[A-Za-z0-9._:-]{1,128}$/;
@@ -274,12 +275,20 @@ var FederatedCore = class extends RelayCore {
     if (parent) return shown && !shown.has(parent.id) ? null : this.address(parent);
     return shown ? null : this.remoteAddress(key);
   }
-  /** a live mirrored row shows the presence its machine mirrored, not one its last_seen decays to here */
+  /**
+   * a live mirrored row shows the presence its machine mirrored, not one its last_seen decays to here; a hibernated one stays hibernated with
+   * its hook wake after its bridge closed
+   */
   view(row, shown) {
     const view = super.view(row, shown);
     const { remote, mirrored_presence: mirrored } = row;
+    if (remote && mirrored === "hibernated")
+      return { ...view, presence: "hibernated", ...view.kind === "agent" && row.wake && HOOK_WAKE.test(row.wake) ? { wake: row.wake } : {} };
     return remote && row.connections > 0 && (mirrored === "online" || mirrored === "idle") ? { ...view, presence: mirrored } : view;
   }
+  hibernated(row) {
+    return super.hibernated(row) || row.remote !== null && row.mirrored_presence === "hibernated";
+  }
   address(row) {
     const remote = row.remote;
     if (remote && isForeign(remote)) return remote.slice(1);
@@ -439,7 +448,7 @@ var FederatedCore = class extends RelayCore {
       for (const { view, id, before } of batch) {
         const row = before ?? this.byId(id);
         if (before && view.kind === "agent") this.dropEarlierHolder(before, view.scope.incarnation);
-        const live = view.presence !== "offline";
+        const live = view.presence !== "offline" && view.presence !== "hibernated";
         const next = {
           kind: view.kind,
           harness: view.harness,
@@ -1322,7 +1331,7 @@ var FederatedCore = class extends RelayCore {
       status = { state: view.status.state, note: cleanText(view.status.note, "note", LIMITS.noteChars) ?? "" };
     }
     const presence = view.presence ?? "offline";
-    if (!PRESENCES.includes(presence)) throw new RelayError("invalid_params", "presence is online, idle or offline");
+    if (!PRESENCES.includes(presence)) throw new RelayError("invalid_params", "presence is online, idle, offline or hibernated");
     const parsedSeen = typeof view.last_seen === "string" ? Date.parse(view.last_seen) : Number.NaN;
     const out = {
       handle,
@@ -1582,7 +1591,8 @@ function parseScope(view) {
     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) ? view.wake : null;
+  if (given("wake"))
+    out.wake = typeof view.wake === "string" && view.wake !== "none" && (WAKES.includes(view.wake) || HOOK_WAKE.test(view.wake)) ? view.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;
@@ -1618,6 +1628,7 @@ import {
   SYSTEM_HANDLE as SYSTEM_HANDLE2,
   sameSecret,
   untilTomorrow,
+  wakeDeclineOf,
   XCounters,
   XLIMITS,
   xlimits
@@ -2210,6 +2221,8 @@ var RelayHub = class _RelayHub {
   limits;
   judgeConfig = null;
   gate = null;
+  /** per machine, when its waker may be called next and the calls that failed in a row */
+  machineWakes = /* @__PURE__ */ new Map();
   /** idempotent: migrates and records the account handle (the address user part, e.g. "ada"); call before handling each request */
   init(account) {
     if (this.core && this.account === account.user) return;
@@ -2217,6 +2230,8 @@ var RelayHub = class _RelayHub {
     const columns = this.deps.sql.all(`PRAGMA table_info(machines)`).map((c) => c.name);
     if (!columns.includes("user_id")) this.deps.sql.all(`ALTER TABLE machines ADD COLUMN user_id TEXT`);
     if (!columns.includes("actor_id")) this.deps.sql.all(`ALTER TABLE machines ADD COLUMN actor_id TEXT`);
+    if (!columns.includes("wake_url")) this.deps.sql.all(`ALTER TABLE machines ADD COLUMN wake_url TEXT`);
+    if (!columns.includes("wake_secret")) this.deps.sql.all(`ALTER TABLE machines ADD COLUMN wake_secret TEXT`);
     const core = new FederatedCore(this.deps.sql, {
       user: account.user,
       now: this.now,
@@ -2883,6 +2898,8 @@ var RelayHub = class _RelayHub {
         conn.watching = true;
         this.save(socket);
         return core.snapshot({ activity: 20 });
+      case "machine_wake":
+        return this.setMachineWake(machine, params.url, params.secret);
     }
     throw new RelayError3("method_not_found", `no method ${method} on a bridge`);
   }
@@ -3287,20 +3304,117 @@ var RelayHub = class _RelayHub {
   stash(bytes) {
     if (this.stored !== null) this.stored += bytes;
   }
-  /** wakes direct waiters and pushes a delivery for a mirrored row to the subscribed bridge of its machine */
+  /**
+   * wakes direct waiters and pushes a delivery for a mirrored row to the subscribed bridge of its machine; with none subscribed, a hibernated
+   * row's machine waker is called
+   */
   route(seq, endpoint) {
     this.wake(endpoint);
     const delivery = this.relay.delivery(seq);
     if (!delivery?.endpoint || !delivery.mirrored) return;
     const machine = delivery.endpoint.slice(0, delivery.endpoint.indexOf("/"));
+    let pushed = false;
     for (const socket of this.deps.sockets()) {
       if (socket.conn.role === "bridge" && socket.conn.subscribed && socket.conn.machine === machine) {
         this.write(socket, { jsonrpc: "2.0", method: "deliver", params: { seq, endpoint: delivery.endpoint, message: delivery.message } });
+        pushed = true;
       }
     }
+    if (!pushed && delivery.recipient) this.machineWake(machine, delivery.recipient, delivery.message);
+  }
+  /** sets or (with a null url) clears the bridge's own machine waker: an https URL (http only to this host) and the secret that signs its calls */
+  setMachineWake(machine, url, secret) {
+    if (url === null || url === void 0) {
+      this.deps.sql.all(`UPDATE machines SET wake_url = NULL, wake_secret = NULL WHERE name = ?`, machine);
+      this.machineWakes.delete(machine);
+      this.relay.record("machine_wake_set", null, machine, { machine, set: false });
+      return { set: false };
+    }
+    if (typeof url !== "string" || url.length > MACHINE_WAKE_URL_CHARS || !wakeUrl(url))
+      throw new RelayError3("invalid_params", `url is an https URL of at most ${MACHINE_WAKE_URL_CHARS} characters (http only to localhost)`);
+    if (typeof secret !== "string" || secret.length < 16 || secret.length > 256)
+      throw new RelayError3("invalid_params", "secret is 16 to 256 characters, and a url needs one");
+    this.deps.sql.all(`UPDATE machines SET wake_url = ?, wake_secret = ? WHERE name = ?`, url, secret, machine);
+    this.machineWakes.delete(machine);
+    this.relay.record("machine_wake_set", null, machine, { machine, set: true });
+    return { set: true };
+  }
+  /**
+   * calls `machine`'s waker for its hibernated `recipient`: the embedder's `machineWake`, else the registered URL, signed. At most once per
+   * debounce window (doubling after failures); a decline counts toward nothing and holds calls for that message and its sender. Metadata only
+   */
+  machineWake(machine, recipient, message) {
+    const embedded = this.deps.machineWake;
+    if (!embedded && !this.deps.fetch) return;
+    const now = this.now();
+    const state = this.machineWakes.get(machine);
+    if (state && state.next > now) return;
+    if (state?.declined && (state.declined.message === message.id || state.declined.from === message.from.address)) return;
+    let view;
+    try {
+      view = this.relay.whoami(recipient);
+    } catch {
+      return;
+    }
+    if (view.presence !== "hibernated") return;
+    const waker = embedded ? null : one3(this.deps.sql, `SELECT wake_url, wake_secret FROM machines WHERE name = ?`, machine);
+    if (!embedded && (!waker?.wake_url || !waker.wake_secret)) return;
+    const fails = state?.fails ?? 0;
+    this.machineWakes.set(machine, { next: now + LIMITS3.wakeDebounceS * 1e3, fails });
+    const fromAccount = message.from.account ?? this.account;
+    const event = {
+      scp: 1,
+      event: "machine_wake",
+      account: this.account,
+      machine,
+      endpoints: [view.address],
+      message: { id: message.id, from: message.from.address, kind: message.kind, thread: message.thread, created_at: message.created_at },
+      from_account: fromAccount,
+      same_account: fromAccount === this.account
+    };
+    const done = (ok, detail) => {
+      if (detail.declined)
+        this.machineWakes.set(machine, { next: now, fails, declined: { reason: detail.declined, message: message.id, from: message.from.address } });
+      else {
+        const next = ok ? 0 : fails + 1;
+        const backoff = ok ? LIMITS3.wakeDebounceS : Math.min(LIMITS3.wakeDebounceS * 2 ** next, LIMITS3.wakeBackoffMaxS);
+        this.machineWakes.set(machine, { next: now + backoff * 1e3, fails: next });
+      }
+      try {
+        this.relay.record("machine_wake", null, machine, { machine, ok, ...detail });
+      } catch {
+      }
+      this.deps.log?.("relay_action", {
+        account: this.account,
+        machine,
+        method: "machine_wake",
+        code: ok ? "ok" : detail.declined ? "declined" : "failed",
+        ...detail
+      });
+    };
+    void (async () => {
+      if (embedded) {
+        const result = await embedded(event);
+        const declined2 = result.ok ? void 0 : wakeDeclineOf(result.declined) ?? void 0;
+        return done(result.ok, { ...result.status !== void 0 ? { status: result.status } : {}, ...declined2 ? { declined: declined2 } : {} });
+      }
+      const body = JSON.stringify(event);
+      const timestamp = String(now);
+      const signature = await hmacHex(waker.wake_secret, `${timestamp}.${body}`);
+      const response = await this.deps.fetch(waker.wake_url, {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-scp-timestamp": timestamp, "x-scp-signature": `sha256=${signature}` },
+        body,
+        signal: AbortSignal.timeout(MACHINE_WAKE_TIMEOUT_MS)
+      });
+      const declined = response.status === 403 ? await declineOf(response) : null;
+      done(response.status >= 200 && response.status < 300, { status: response.status, ...declined ? { declined } : {} });
+    })().catch((error) => done(false, { error: error instanceof Error ? error.name : "error" }));
   }
   /** a machine's endpoint changes: `endpoints` to the other bridges, presence and status to watchers */
   announce(machine, changes, full) {
+    const waking = this.machineWakes.get(machine);
+    if (waking?.declined && changes.some((c) => c.presence && c.view.presence === "hibernated")) delete waking.declined;
     if (full || changes.length) {
       const endpoints = full ? this.relay.remoteRowsOf(machine) : changes.map((c) => c.was === void 0 ? c.view : { ...c.view, was: c.was });
       this.toBridges(machine, { machine, endpoints, full });
@@ -3501,13 +3615,16 @@ var RelayHub = class _RelayHub {
   }
   machineList() {
     const sockets = this.deps.sockets().filter((s) => !this.gone.has(s.conn.id));
-    const bound = this.deps.sql.all(`SELECT name, kind, created_at, last_seen FROM machines ORDER BY name`).map((row) => ({
+    const bound = this.deps.sql.all(
+      `SELECT name, kind, created_at, last_seen, wake_url FROM machines ORDER BY name`
+    ).map((row) => ({
       name: row.name,
       kind: row.kind,
       online: sockets.some((s) => this.boundMachine(s.conn) === row.name),
       bridge: sockets.some((s) => s.conn.role === "bridge" && s.conn.machine === row.name),
       created_at: iso2(row.created_at),
-      last_seen: iso2(row.last_seen)
+      last_seen: iso2(row.last_seen),
+      wake: row.wake_url !== null
     }));
     const revoked = this.deps.sql.all(`SELECT name, at FROM machine_tombstones WHERE name NOT IN (SELECT name FROM machines) ORDER BY name`).map((row) => ({ name: row.name, kind: "revoked", online: false, bridge: false, created_at: null, last_seen: iso2(row.at) }));
     return [...bound, ...revoked];
@@ -3648,6 +3765,32 @@ var RelayHub = class _RelayHub {
     this.route(this.relay.judgeNoticeTo(endpoint, text), endpoint);
   }
 };
+var MACHINE_WAKE_URL_CHARS = 2048;
+var MACHINE_WAKE_TIMEOUT_MS = 1e4;
+function wakeUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.username || url.password) return false;
+  if (url.protocol === "https:") return true;
+  return url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]");
+}
+async function hmacHex(secret, text) {
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const signature = new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(text)));
+  return Array.from(signature, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function declineOf(response) {
+  try {
+    return wakeDeclineOf(JSON.parse(await response.text?.() ?? "").declined);
+  } catch {
+    return null;
+  }
+}
 export {
   FederatedCore,
   GRAPH_MINUTES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scp-dev/hub",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "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.3.1"
+    "@scp-dev/core": "0.5.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1"

package/src/federation.ts

@@ -21,6 +21,7 @@ import {
   newId,
   one,
   type PolicySubject,
+  PRESENCES,
   type Presence,
   randomHex,
   RelayCore,
@@ -57,7 +58,8 @@ export const MACHINE_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/
 const REMOTE = /^[a-z0-9][a-z0-9._-]{0,63}\/([a-z0-9][a-z0-9._-]{0,62})?$/
 const MESSAGE_ID = /^[a-z]{2,8}_[a-z0-9]{8,64}$/
 const AUTHS: readonly RelayAuth[] = ["local-uid", "account", "account+bridge", "contact"]
-const PRESENCES: readonly Presence[] = ["online", "idle", "offline"]
+/** a hibernated agent's shown wake, its provider's hook */
+const HOOK_WAKE = /^hook:[a-z0-9][a-z0-9-]{0,31}$/
 
 export interface FederatedOptions extends CoreOptions {
   /** this host's own machine name; addresses naming it stay local */
@@ -510,13 +512,22 @@ export class FederatedCore extends RelayCore {
     return shown ? null : this.remoteAddress(key)
   }
 
-  /** a live mirrored row shows the presence its machine mirrored, not one its last_seen decays to here */
+  /**
+   * a live mirrored row shows the presence its machine mirrored, not one its last_seen decays to here; a hibernated one stays hibernated with
+   * its hook wake after its bridge closed
+   */
   protected override view(row: EndpointRow, shown?: Set<string>): EndpointView {
     const view = super.view(row, shown)
     const { remote, mirrored_presence: mirrored } = row as FederatedRow
+    if (remote && mirrored === "hibernated")
+      return { ...view, presence: "hibernated", ...(view.kind === "agent" && row.wake && HOOK_WAKE.test(row.wake) ? { wake: row.wake as Wake } : {}) }
     return remote && row.connections > 0 && (mirrored === "online" || mirrored === "idle") ? { ...view, presence: mirrored } : view
   }
 
+  protected override hibernated(row: EndpointRow): boolean {
+    return super.hibernated(row) || ((row as FederatedRow).remote !== null && (row as FederatedRow).mirrored_presence === "hibernated")
+  }
+
   protected override address(row: EndpointRow): string {
     const remote = (row as FederatedRow).remote
     if (remote && isForeign(remote)) return remote.slice(1)
@@ -686,7 +697,7 @@ export class FederatedCore extends RelayCore {
       for (const { view, id, before } of batch) {
         const row = before ?? (this.byId(id) as FederatedRow)
         if (before && view.kind === "agent") this.dropEarlierHolder(before, view.scope.incarnation)
-        const live = view.presence !== "offline"
+        const live = view.presence !== "offline" && view.presence !== "hibernated"
         const next: Partial<FederatedRow> = {
           kind: view.kind,
           harness: view.harness,
@@ -1664,7 +1675,7 @@ export class FederatedCore extends RelayCore {
       status = { state: view.status.state, note: cleanText(view.status.note, "note", LIMITS.noteChars) ?? "" }
     }
     const presence = view.presence ?? "offline"
-    if (!PRESENCES.includes(presence)) throw new RelayError("invalid_params", "presence is online, idle or offline")
+    if (!PRESENCES.includes(presence)) throw new RelayError("invalid_params", "presence is online, idle, offline or hibernated")
     const parsedSeen = typeof view.last_seen === "string" ? Date.parse(view.last_seen) : Number.NaN
     const out = {
       handle,
@@ -1958,7 +1969,9 @@ 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("wake"))
+    out.wake =
+      typeof view.wake === "string" && view.wake !== "none" && (WAKES.includes(view.wake as Wake) || HOOK_WAKE.test(view.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

@@ -39,6 +39,8 @@ import {
   sameSecret,
   untilTomorrow,
   type Wake,
+  type WakeDecline,
+  wakeDeclineOf,
   type XContact,
   XCounters,
   type XDelivered,
@@ -93,6 +95,8 @@ export interface MachineRow {
   bridge: boolean
   created_at: string | null
   last_seen: string | null
+  /** a machine waker URL is set; the URL and its secret are never shown */
+  wake?: boolean
 }
 
 /** an endpoint as the dashboard graph draws it */
@@ -158,6 +162,19 @@ export interface HubSocket {
   close(code: number, reason: string): void
 }
 
+/** what a machine waker gets: who to wake and the message's metadata, never its body */
+export interface MachineWakeEvent {
+  scp: 1
+  event: "machine_wake"
+  account: string
+  machine: string
+  endpoints: string[]
+  message: { id: string; from: string; kind: string; thread: string; created_at: string }
+  /** the sender's account handle; another account's sender never chooses the credentials a wake uses */
+  from_account: string
+  same_account: boolean
+}
+
 export interface HubDeps {
   sql: Sql
   /** synchronous sha256 hex */
@@ -177,6 +194,13 @@ export interface HubDeps {
   limits?: Partial<HubLimits>
   /** the link to other accounts' relays; without it an address of another account is not found */
   crossAccount?: CrossAccountLink
+  /** an HTTP client for machine waker URLs; without it (and without `machineWake`) no machine waker is called */
+  fetch?: (
+    url: string,
+    init: { method: string; headers: Record<string, string>; body: string; signal?: AbortSignal },
+  ) => Promise<{ status: number; text?: () => Promise<string> }>
+  /** the embedder's own machine waker, called in-process for any machine in place of a registered URL; metadata only, never a body or secret */
+  machineWake?: (event: MachineWakeEvent) => Promise<{ ok: boolean; status?: number; declined?: WakeDecline }>
 }
 
 /** what a configured judge needs besides its policy */
@@ -331,6 +355,8 @@ export class RelayHub {
   private readonly limits: Readonly<HubLimits>
   private judgeConfig: { policy: JudgePolicy; options: HubJudgeOptions } | null = null
   private gate: JudgeGate | null = null
+  /** per machine, when its waker may be called next and the calls that failed in a row */
+  private readonly machineWakes = new Map<string, { next: number; fails: number; declined?: { reason: WakeDecline; message: string; from: string } }>()
 
   constructor(private readonly deps: HubDeps) {
     this.now = deps.now ?? Date.now
@@ -345,6 +371,8 @@ export class RelayHub {
     const columns = this.deps.sql.all<{ name: string }>(`PRAGMA table_info(machines)`).map((c) => c.name)
     if (!columns.includes("user_id")) this.deps.sql.all(`ALTER TABLE machines ADD COLUMN user_id TEXT`)
     if (!columns.includes("actor_id")) this.deps.sql.all(`ALTER TABLE machines ADD COLUMN actor_id TEXT`)
+    if (!columns.includes("wake_url")) this.deps.sql.all(`ALTER TABLE machines ADD COLUMN wake_url TEXT`)
+    if (!columns.includes("wake_secret")) this.deps.sql.all(`ALTER TABLE machines ADD COLUMN wake_secret TEXT`)
     const core = new FederatedCore(this.deps.sql, {
       user: account.user,
       now: this.now,
@@ -1049,6 +1077,8 @@ export class RelayHub {
         conn.watching = true
         this.save(socket)
         return core.snapshot({ activity: 20 })
+      case "machine_wake":
+        return this.setMachineWake(machine, params.url, params.secret)
     }
     throw new RelayError("method_not_found", `no method ${method} on a bridge`)
   }
@@ -1491,21 +1521,121 @@ export class RelayHub {
     if (this.stored !== null) this.stored += bytes
   }
 
-  /** wakes direct waiters and pushes a delivery for a mirrored row to the subscribed bridge of its machine */
+  /**
+   * wakes direct waiters and pushes a delivery for a mirrored row to the subscribed bridge of its machine; with none subscribed, a hibernated
+   * row's machine waker is called
+   */
   private route(seq: number, endpoint: string): void {
     this.wake(endpoint)
     const delivery = this.relay.delivery(seq)
     if (!delivery?.endpoint || !delivery.mirrored) return
     const machine = delivery.endpoint.slice(0, delivery.endpoint.indexOf("/"))
+    let pushed = false
     for (const socket of this.deps.sockets()) {
       if (socket.conn.role === "bridge" && socket.conn.subscribed && socket.conn.machine === machine) {
         this.write(socket, { jsonrpc: "2.0", method: "deliver", params: { seq, endpoint: delivery.endpoint, message: delivery.message } })
+        pushed = true
+      }
+    }
+    if (!pushed && delivery.recipient) this.machineWake(machine, delivery.recipient, delivery.message)
+  }
+
+  /** sets or (with a null url) clears the bridge's own machine waker: an https URL (http only to this host) and the secret that signs its calls */
+  private setMachineWake(machine: string, url: unknown, secret: unknown): { set: boolean } {
+    if (url === null || url === undefined) {
+      this.deps.sql.all(`UPDATE machines SET wake_url = NULL, wake_secret = NULL WHERE name = ?`, machine)
+      this.machineWakes.delete(machine)
+      this.relay.record("machine_wake_set", null, machine, { machine, set: false })
+      return { set: false }
+    }
+    if (typeof url !== "string" || url.length > MACHINE_WAKE_URL_CHARS || !wakeUrl(url))
+      throw new RelayError("invalid_params", `url is an https URL of at most ${MACHINE_WAKE_URL_CHARS} characters (http only to localhost)`)
+    if (typeof secret !== "string" || secret.length < 16 || secret.length > 256)
+      throw new RelayError("invalid_params", "secret is 16 to 256 characters, and a url needs one")
+    this.deps.sql.all(`UPDATE machines SET wake_url = ?, wake_secret = ? WHERE name = ?`, url, secret, machine)
+    this.machineWakes.delete(machine)
+    this.relay.record("machine_wake_set", null, machine, { machine, set: true })
+    return { set: true }
+  }
+
+  /**
+   * calls `machine`'s waker for its hibernated `recipient`: the embedder's `machineWake`, else the registered URL, signed. At most once per
+   * debounce window (doubling after failures); a decline counts toward nothing and holds calls for that message and its sender. Metadata only
+   */
+  private machineWake(machine: string, recipient: string, message: Envelope): void {
+    const embedded = this.deps.machineWake
+    if (!embedded && !this.deps.fetch) return
+    const now = this.now()
+    const state = this.machineWakes.get(machine)
+    if (state && state.next > now) return
+    if (state?.declined && (state.declined.message === message.id || state.declined.from === message.from.address)) return
+    let view: EndpointView
+    try {
+      view = this.relay.whoami(recipient)
+    } catch {
+      return
+    }
+    if (view.presence !== "hibernated") return
+    const waker = embedded
+      ? null
+      : one<{ wake_url: string | null; wake_secret: string | null }>(this.deps.sql, `SELECT wake_url, wake_secret FROM machines WHERE name = ?`, machine)
+    if (!embedded && (!waker?.wake_url || !waker.wake_secret)) return
+    const fails = state?.fails ?? 0
+    this.machineWakes.set(machine, { next: now + LIMITS.wakeDebounceS * 1000, fails })
+    const fromAccount = message.from.account ?? this.account
+    const event: MachineWakeEvent = {
+      scp: 1,
+      event: "machine_wake",
+      account: this.account,
+      machine,
+      endpoints: [view.address],
+      message: { id: message.id, from: message.from.address, kind: message.kind, thread: message.thread, created_at: message.created_at },
+      from_account: fromAccount,
+      same_account: fromAccount === this.account,
+    }
+    const done = (ok: boolean, detail: { status?: number; error?: string; declined?: WakeDecline }) => {
+      if (detail.declined)
+        this.machineWakes.set(machine, { next: now, fails, declined: { reason: detail.declined, message: message.id, from: message.from.address } })
+      else {
+        const next = ok ? 0 : fails + 1
+        const backoff = ok ? LIMITS.wakeDebounceS : Math.min(LIMITS.wakeDebounceS * 2 ** next, LIMITS.wakeBackoffMaxS)
+        this.machineWakes.set(machine, { next: now + backoff * 1000, fails: next })
       }
+      try {
+        this.relay.record("machine_wake", null, machine, { machine, ok, ...detail })
+      } catch {}
+      this.deps.log?.("relay_action", {
+        account: this.account,
+        machine,
+        method: "machine_wake",
+        code: ok ? "ok" : detail.declined ? "declined" : "failed",
+        ...detail,
+      })
     }
+    void (async () => {
+      if (embedded) {
+        const result = await embedded(event)
+        const declined = result.ok ? undefined : (wakeDeclineOf(result.declined) ?? undefined)
+        return done(result.ok, { ...(result.status !== undefined ? { status: result.status } : {}), ...(declined ? { declined } : {}) })
+      }
+      const body = JSON.stringify(event)
+      const timestamp = String(now)
+      const signature = await hmacHex(waker!.wake_secret!, `${timestamp}.${body}`)
+      const response = await this.deps.fetch!(waker!.wake_url!, {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-scp-timestamp": timestamp, "x-scp-signature": `sha256=${signature}` },
+        body,
+        signal: AbortSignal.timeout(MACHINE_WAKE_TIMEOUT_MS),
+      })
+      const declined = response.status === 403 ? await declineOf(response) : null
+      done(response.status >= 200 && response.status < 300, { status: response.status, ...(declined ? { declined } : {}) })
+    })().catch((error: unknown) => done(false, { error: error instanceof Error ? error.name : "error" }))
   }
 
   /** a machine's endpoint changes: `endpoints` to the other bridges, presence and status to watchers */
   private announce(machine: string, changes: MirrorChange[], full: boolean): void {
+    const waking = this.machineWakes.get(machine)
+    if (waking?.declined && changes.some((c) => c.presence && c.view.presence === "hibernated")) delete waking.declined
     if (full || changes.length) {
       const endpoints = full ? this.relay.remoteRowsOf(machine) : changes.map((c) => (c.was === undefined ? c.view : { ...c.view, was: c.was }))
       this.toBridges(machine, { machine, endpoints, full })
@@ -1729,7 +1859,9 @@ export class RelayHub {
   private machineList(): MachineRow[] {
     const sockets = this.deps.sockets().filter((s) => !this.gone.has(s.conn.id))
     const bound = this.deps.sql
-      .all<{ name: string; kind: string; created_at: number; last_seen: number | null }>(`SELECT name, kind, created_at, last_seen FROM machines ORDER BY name`)
+      .all<{ name: string; kind: string; created_at: number; last_seen: number | null; wake_url: string | null }>(
+        `SELECT name, kind, created_at, last_seen, wake_url FROM machines ORDER BY name`,
+      )
       .map((row) => ({
         name: row.name,
         kind: row.kind,
@@ -1737,6 +1869,7 @@ export class RelayHub {
         bridge: sockets.some((s) => s.conn.role === "bridge" && s.conn.machine === row.name),
         created_at: iso(row.created_at),
         last_seen: iso(row.last_seen),
+        wake: row.wake_url !== null,
       }))
     const revoked = this.deps.sql
       .all<{ name: string; at: number }>(`SELECT name, at FROM machine_tombstones WHERE name NOT IN (SELECT name FROM machines) ORDER BY name`)
@@ -1889,3 +2022,36 @@ export class RelayHub {
     this.route(this.relay.judgeNoticeTo(endpoint, text), endpoint)
   }
 }
+
+const MACHINE_WAKE_URL_CHARS = 2048
+const MACHINE_WAKE_TIMEOUT_MS = 10_000
+
+/** an https URL, or http to this host, with no credentials in it */
+function wakeUrl(value: string): boolean {
+  let url: URL
+  try {
+    url = new URL(value)
+  } catch {
+    return false
+  }
+  if (url.username || url.password) return false
+  if (url.protocol === "https:") return true
+  return url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]")
+}
+
+/** HMAC-SHA256 of `text` under `secret`, hex, with WebCrypto (Bun and Workers both have it) */
+async function hmacHex(secret: string, text: string): Promise<string> {
+  const encoder = new TextEncoder()
+  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"])
+  const signature = new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(text)))
+  return Array.from(signature, (byte) => byte.toString(16).padStart(2, "0")).join("")
+}
+
+/** a 403 answer's `{"declined": "<reason>"}`, or null */
+async function declineOf(response: { text?: () => Promise<string> }): Promise<WakeDecline | null> {
+  try {
+    return wakeDeclineOf((JSON.parse((await response.text?.()) ?? "") as { declined?: unknown }).declined)
+  } catch {
+    return null
+  }
+}

package/src/index.ts

@@ -34,6 +34,7 @@ export {
   type HubRole,
   type HubSocket,
   type MachineRow,
+  type MachineWakeEvent,
 } from "./hub"
 export {
   type Deliver,