@oar-sh/oar 0.9.2 → 0.9.4

package/server/services/remote-relay-inbound.mjs

@@ -0,0 +1,187 @@
+'use strict';
+
+// The inbound side of remote relays, shared by the message, conversation and
+// question routes: which requests come from another relay's agent, the
+// inbound switch, provenance ("origin") for API payloads, and the mentions in
+// a human message that unlock a remote relay for its conversation (plus the
+// hint the agent gets with that turn).
+//
+// `inbound` is the runtime's `remoteRelayInbound` dep:
+//   { listRelays, selfNames, inboundEnabled, recordUnlock, describeRelay, repository }
+// Every helper treats a missing one as "feature absent": nothing is remote,
+// nothing unlocks, and the routes behave exactly as before.
+
+import {
+  REMOTE_RELAY_ERROR_CODES,
+  REMOTE_RELAY_HEADERS,
+  REMOTE_RELAY_TOOL_NAME,
+  normalizeRemoteRelayOrigin,
+  stripRemotePromptHeader,
+} from '../../shared/remote-relay-contract.mjs';
+import { findRemoteRelayMentions } from '../../shared/remote-relay-mentions.mjs';
+
+export const REMOTE_INBOUND_DISABLED_RESPONSE = Object.freeze({
+  error: 'This relay does not accept prompts from other relays\' agents',
+  code: REMOTE_RELAY_ERROR_CODES.inboundDisabled,
+});
+
+function headerValue(req, name) {
+  const value = req?.headers?.[name];
+  return String((Array.isArray(value) ? value[0] : value) ?? '').trim();
+}
+
+function headerHops(req) {
+  const text = headerValue(req, REMOTE_RELAY_HEADERS.hops);
+  if (!/^\d+$/.test(text)) return null;
+  return Number(text);
+}
+
+/**
+ * What a request says about coming from another relay's agent.
+ * `remote` is true for the X-OAR-Remote-Origin header or any `origin` in the
+ * body, even a malformed one, so such a request can never unlock a relay.
+ * `origin` is the sanitised provenance to store: the body's, or a minimal one
+ * built from the header (its value is the sender's relay id), so a turn an
+ * agent started is always recognisable as one. The hop count is the larger of
+ * the body's and the X-OAR-Remote-Hops header's.
+ */
+export function readRemoteRelayRequest(req, inbound, { body = req?.body } = {}) {
+  if (!inbound) return { remote: false, origin: null };
+  const rawOrigin = body && typeof body === 'object' ? body.origin : undefined;
+  const senderRelayId = headerValue(req, REMOTE_RELAY_HEADERS.origin);
+  const remote = !!senderRelayId || (rawOrigin !== undefined && rawOrigin !== null);
+  if (!remote) return { remote: false, origin: null };
+  const hops = headerHops(req);
+  let origin = normalizeRemoteRelayOrigin(rawOrigin)
+    || normalizeRemoteRelayOrigin(senderRelayId ? { relayId: senderRelayId, hops: hops ?? 1 } : null);
+  if (origin && hops !== null && hops > origin.hops) {
+    origin = normalizeRemoteRelayOrigin({ ...origin, hops });
+  }
+  return { remote: true, origin };
+}
+
+/** The inbound switch; on by default, closed when it cannot be read. */
+export function remoteRelayInboundEnabled(inbound) {
+  if (!inbound || typeof inbound.inboundEnabled !== 'function') return true;
+  try {
+    return inbound.inboundEnabled() !== false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Applies the inbound switch to a write route. Returns the request's
+ * remote-relay facts (see readRemoteRelayRequest), or null after answering
+ * 403 REMOTE_INBOUND_DISABLED because the request came from another relay's
+ * agent and this relay does not accept those.
+ */
+export function admitRemoteRelayRequest(req, res, inbound) {
+  const request = readRemoteRelayRequest(req, inbound);
+  if (!request.remote || remoteRelayInboundEnabled(inbound)) return request;
+  res.status(403).json({ ...REMOTE_INBOUND_DISABLED_RESPONSE });
+  return null;
+}
+
+/**
+ * The origin a public share may show: the facts the prompt's header line
+ * already states, without the other relay's address or ids.
+ */
+export function publicRemoteRelayOrigin(origin) {
+  if (!origin || typeof origin !== 'object') return null;
+  return { ...origin, relayId: '', relayUrl: '', conversationId: '' };
+}
+
+// ─── Mentions ────────────────────────────────────────────────────────────────
+
+// A remote relay names itself (pairing, health checks), so its name is
+// untrusted inside a prompt block: no quotes, tags or line breaks.
+function hintText(value, max = 60) {
+  return String(value ?? '').replace(/[\r\n"<>]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, max);
+}
+
+/**
+ * The remote relays a human message mentions, in order of appearance:
+ * `[{ relayId, name, online, version }]`. `text` is what the user typed; a
+ * remote-prompt header line (a Resend of an agent's message) is not the user's
+ * and is ignored. Empty without the feature or when the registry cannot be
+ * read — a mention never breaks a send.
+ */
+export function findMentionedRemoteRelays(inbound, text) {
+  if (!inbound || typeof inbound.listRelays !== 'function') return [];
+  try {
+    const listedRelays = inbound.listRelays();
+    const relays = Array.isArray(listedRelays) ? listedRelays : [];
+    const selfNames = typeof inbound.selfNames === 'function' ? (inbound.selfNames() || []) : [];
+    const mentions = findRemoteRelayMentions(stripRemotePromptHeader(text), relays, {
+      selfNames: Array.isArray(selfNames) ? selfNames : [],
+    });
+    return mentions.map(({ relayId }) => {
+      const listed = relays.find((relay) => String(relay?.id || '').trim() === relayId) || {};
+      let described = null;
+      try {
+        described = typeof inbound.describeRelay === 'function' ? inbound.describeRelay(relayId) : null;
+      } catch {
+        described = null;
+      }
+      return {
+        relayId,
+        name: String(described?.name || listed.name || relayId),
+        online: typeof described?.online === 'boolean'
+          ? described.online
+          : String(listed.lastStatus || '').trim().toLowerCase() === 'online',
+        version: String(described?.version || listed.version || '').trim(),
+      };
+    });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The one reminder block the agent gets with a turn whose message mentions
+ * remote relays ('' for none). It rides in the queued prompt only, never in
+ * the stored message, and the prompt sanitizers strip <system_reminder>
+ * blocks from anything displayed.
+ */
+export function formatRemoteRelayMentionHint(relays = []) {
+  const described = (Array.isArray(relays) ? relays : [])
+    .map((relay) => {
+      const name = hintText(relay?.name) || hintText(relay?.relayId);
+      if (!name) return '';
+      const version = hintText(relay?.version, 40);
+      const status = relay?.online ? 'online' : 'offline';
+      return `"${name}" (${version ? `${status}, OAR ${version}` : status})`;
+    })
+    .filter(Boolean);
+  if (!described.length) return '';
+  const subject = described.length === 1
+    ? `the remote OAR relay ${described[0]}`
+    : `the remote OAR relays ${described.join(', ')}`;
+  return `<system_reminder>The user mentioned ${subject}. The ${REMOTE_RELAY_TOOL_NAME} tool can list, read, prompt and create sessions there.</system_reminder>`;
+}
+
+/** The queued prompt with the mention hint after the user's text. */
+export function withRemoteRelayMentionHint(promptText, hint) {
+  const text = String(promptText ?? '');
+  if (!hint) return text;
+  return text ? `${text}\n\n${hint}` : hint;
+}
+
+/**
+ * Persists the unlocks for a stored human message. Returns how many were new.
+ * Failures are swallowed: the message is already accepted, and the agent
+ * learns about a missing unlock from the tool's LOCKED answer.
+ */
+export function recordRemoteRelayUnlocks(inbound, { conversationId, messageId, relays = [] } = {}) {
+  if (!inbound || typeof inbound.recordUnlock !== 'function') return 0;
+  let created = 0;
+  for (const relay of Array.isArray(relays) ? relays : []) {
+    try {
+      if (inbound.recordUnlock(conversationId, relay?.relayId, messageId)) created += 1;
+    } catch {
+      // Keep going: one relay's failure must not cost the others their unlock.
+    }
+  }
+  return created;
+}

package/server/services/remote-relay-pairing.mjs

@@ -0,0 +1,189 @@
+'use strict';
+
+import {
+  REMOTE_RELAY_ERROR_CODES,
+  REMOTE_RELAY_PROTOCOL,
+  checkRemoteRelayUrlPolicy,
+  normalizeRemoteRelayLink,
+} from '../../shared/remote-relay-contract.mjs';
+
+// Adding a remote relay and the mutual introduction that follows (plan §5.4).
+//
+// Outbound (`addFromLink`, behind POST /api/remote-relays): the user pastes
+// the other relay's web address. We probe it with the best token we have,
+// save it, and — when both sides speak protocol 1 and we know our own public
+// URL — introduce ourselves so the other relay lists us too.
+//
+// Inbound (`acceptPairing`, behind POST /api/remote-relays/pair): another
+// relay introduces itself. For a relay not listed yet, the token it may carry
+// is the one to use for it; it is stored for that remote only, never echoed
+// and never logged. A relay already listed keeps its stored address and token.
+
+// The inbound check must finish well inside the caller's own request budget,
+// or the caller reports "not paired back" although we saved the entry.
+const PAIR_CHECK_TIMEOUT_MS = 5_000;
+export const REMOTE_RELAY_SELF_CODE = 'SELF';
+
+function toText(value) {
+  return String(value ?? '').trim();
+}
+
+function failure(status, code, error, extra = {}) {
+  return { ok: false, status, code, error, ...extra };
+}
+
+export function createRemoteRelayPairing({
+  registry,
+  client,
+  getOwnToken = () => '',
+  now = () => new Date(),
+} = {}) {
+  function ownToken() {
+    return toText(getOwnToken?.());
+  }
+
+  /** Stores the browser-derived address as our public URL, once, if none is set. */
+  function adoptSelfUrl(selfUrl) {
+    const raw = toText(selfUrl);
+    if (!raw || registry.getSelfSettings().publicUrl) return;
+    const link = normalizeRemoteRelayLink(raw);
+    if (!link.ok || !checkRemoteRelayUrlPolicy(link.baseUrl).ok) return;
+    registry.setSelfSettings({ publicUrl: link.baseUrl });
+  }
+
+  function findExisting(identity, baseUrl) {
+    const entries = registry.list();
+    if (identity.relayId) {
+      const byId = entries.find((entry) => entry.relayId === identity.relayId);
+      if (byId) return byId;
+    }
+    const url = baseUrl.toLowerCase();
+    return entries.find((entry) => entry.url.toLowerCase() === url) || null;
+  }
+
+  async function pairBackTo(relay, workingToken) {
+    const publicUrl = registry.getSelfSettings().publicUrl;
+    if (!publicUrl) {
+      return { pairedBack: false, pairBackError: 'This relay\'s public URL is not set, so the other relay cannot reach it' };
+    }
+    if (!(Number(relay.protocol) >= 1)) {
+      return { pairedBack: false, pairBackError: 'The other relay runs an older OAR without pairing; add this relay there by hand' };
+    }
+    const own = ownToken();
+    const body = {
+      relayId: registry.instanceId(),
+      name: registry.selfName(),
+      url: publicUrl,
+      protocol: REMOTE_RELAY_PROTOCOL,
+      // Only when the other relay needs a different token to call us back.
+      ...(own && own !== workingToken ? { token: own } : {}),
+    };
+    try {
+      await client.request(relay, 'POST', '/api/remote-relays/pair', { body });
+      return { pairedBack: true };
+    } catch (error) {
+      return { pairedBack: false, pairBackError: toText(error?.message) || 'Pairing back failed' };
+    }
+  }
+
+  /**
+   * POST /api/remote-relays `{ url, token?, pairBack = true, selfUrl? }`.
+   * Failures carry the intended HTTP `status`; a 401 is `{ ok:false,
+   * needsToken:true }` so the UI can show the token field.
+   */
+  async function addFromLink({ url, token, pairBack = true, selfUrl } = {}) {
+    const link = normalizeRemoteRelayLink(url);
+    if (!link.ok) return failure(400, REMOTE_RELAY_ERROR_CODES.invalidInput, link.error);
+
+    // Explicit field, then the link's ?token=, then this relay's own token.
+    const workingToken = toText(token) || toText(link.token) || ownToken();
+
+    let identity;
+    try {
+      identity = await client.probe(link.baseUrl, workingToken);
+    } catch (error) {
+      if (error?.code === REMOTE_RELAY_ERROR_CODES.unauthorized) {
+        return failure(200, error.code, 'The other relay rejected the token. Enter its token.', { needsToken: true });
+      }
+      const status = error?.code === REMOTE_RELAY_ERROR_CODES.invalidInput ? 400 : 502;
+      return failure(status, error?.code || REMOTE_RELAY_ERROR_CODES.offline, toText(error?.message) || 'The other relay could not be reached');
+    }
+
+    if (identity.relayId && identity.relayId === registry.instanceId()) {
+      return failure(400, REMOTE_RELAY_SELF_CODE, 'That address is this relay itself');
+    }
+
+    adoptSelfUrl(selfUrl);
+
+    const tokenFields = workingToken === ownToken()
+      ? { tokenMode: 'own' }
+      : { tokenMode: 'custom', token: workingToken };
+    const existing = findExisting(identity, link.baseUrl);
+    let saved;
+    if (existing) {
+      const updated = registry.update(existing.id, { url: link.baseUrl, ...tokenFields });
+      if (!updated.ok) return failure(updated.status || 400, REMOTE_RELAY_ERROR_CODES.invalidInput, updated.error);
+      saved = registry.recordIdentity(existing.id, identity);
+    } else {
+      saved = registry.add({
+        relayId: identity.relayId,
+        name: identity.name,
+        url: link.baseUrl,
+        ...tokenFields,
+        addedBy: 'user',
+        version: identity.version,
+        platform: identity.platform,
+        protocol: identity.protocol,
+        lastStatus: 'online',
+        lastSeenAt: now().toISOString(),
+      });
+    }
+    if (!saved) return failure(409, REMOTE_RELAY_ERROR_CODES.unknown, 'The remote relay was removed while it was being added');
+
+    const pairing = pairBack === false
+      ? { pairedBack: false }
+      : await pairBackTo(registry.get(saved.id) || saved, workingToken);
+
+    const relay = registry.listPublic().find((entry) => entry.id === saved.id) || null;
+    return {
+      ok: true,
+      relay,
+      updated: !!existing,
+      ...pairing,
+      ...(link.warning ? { warning: link.warning } : {}),
+    };
+  }
+
+  /**
+   * POST /api/remote-relays/pair: another relay introduces itself as
+   * `{ relayId, name, url, protocol, token? }`. The entry is kept even when
+   * that URL is not reachable from here yet (a tunnel that is not up).
+   */
+  async function acceptPairing(body = {}) {
+    const input = body && typeof body === 'object' ? body : {};
+    const relayId = toText(input.relayId).slice(0, 100);
+    if (!relayId) return failure(400, REMOTE_RELAY_ERROR_CODES.invalidInput, 'relayId is required');
+    if (relayId === registry.instanceId()) {
+      return failure(400, REMOTE_RELAY_SELF_CODE, 'A relay cannot pair with itself');
+    }
+    const link = normalizeRemoteRelayLink(input.url);
+    if (!link.ok) return failure(400, REMOTE_RELAY_ERROR_CODES.invalidInput, link.error);
+
+    // A relay already listed here keeps the address and token stored for it;
+    // only a new one takes the offered ones (see upsertFromPairing).
+    const protocol = Number(input.protocol);
+    const entry = registry.upsertFromPairing({
+      relayId,
+      name: toText(input.name).slice(0, 60),
+      url: link.baseUrl,
+      token: typeof input.token === 'string' ? input.token : '',
+      ...(Number.isInteger(protocol) && protocol >= 0 ? { protocol } : {}),
+    });
+    try {
+      await registry.check(entry.id, { timeoutMs: PAIR_CHECK_TIMEOUT_MS });
+    } catch {}
+    return { ok: true, relayId: registry.instanceId(), name: registry.selfName() };
+  }
+
+  return { addFromLink, acceptPairing };
+}