@onlyne/lib 0.0.0-stage → 3.0.0

package/src/threads.ts

@@ -0,0 +1,350 @@
+import { admissionView, fail, key, page, requireValue, utc } from './core.js';
+import type { Context } from './core.js';
+import type { Auth, Entry, Event, Grant, Json, Member, MessageRef, Mutation, Page, PageOptions, ReadScope, ReplyPermit, Thread, ThreadRef, Transaction } from './types.js';
+
+/** One reserved default-thread id per owner: omitted targets land here, and the id is never reused. */
+export const DEFAULT_THREAD = 'thr-default';
+
+const DEFAULT_ACCESS: Member['access'] = ['post', 'read'];
+
+function requireThreadRef(ref: ThreadRef): void {
+  if (ref == null || typeof ref !== 'object' || typeof ref.owner !== 'string' || typeof ref.id !== 'string' || ref.id.length === 0) {
+    fail('invalid_request', 'Expected a ThreadRef with an owner and a non-empty id.');
+  }
+}
+
+async function loadThread(tx: Transaction, ctx: Context, ref: ThreadRef): Promise<Thread> {
+  requireThreadRef(ref);
+  ctx.owner(ref.owner);
+  return requireValue(await tx.get<Thread>(key('thread', ref.owner, ref.id)));
+}
+
+function requireAccess(access: Array<'read' | 'post'>): Member['access'] {
+  if (!Array.isArray(access) || access.length === 0) fail('invalid_request', 'access must list at least one of post and read.');
+  for (const item of access) if (item !== 'post' && item !== 'read') fail('invalid_request', 'Unknown access member; expected post or read.');
+  return [...new Set(access)];
+}
+
+function requireScope(scope: ReadScope): ReadScope {
+  if (scope == null || typeof scope !== 'object' || Array.isArray(scope)) fail('invalid_request', 'read_scope must be an object.');
+  for (const name of Object.keys(scope)) {
+    if (name !== 'peers' && name !== 'since_seq' && name !== 'related_to') fail('invalid_request', `Unknown read_scope key ${name}.`);
+  }
+  const { peers, since_seq, related_to } = scope;
+  if (peers !== undefined && (!Array.isArray(peers) || peers.length === 0 || peers.some(peer => typeof peer !== 'string' || peer.length === 0))) {
+    fail('invalid_request', 'read_scope.peers must be a non-empty array of node ids.');
+  }
+  if (since_seq !== undefined && (typeof since_seq !== 'string' || !/^(0|[1-9][0-9]*)$/.test(since_seq))) {
+    fail('invalid_request', 'read_scope.since_seq must be a decimal sequence string.');
+  }
+  if (related_to !== undefined && (typeof related_to?.sender !== 'string' || !related_to.sender || typeof related_to.id !== 'string' || !related_to.id)) {
+    fail('invalid_request', 'read_scope.related_to must be a complete MessageRef.');
+  }
+  return { ...(peers === undefined ? {} : { peers: [...new Set(peers)] }), ...(since_seq === undefined ? {} : { since_seq }), ...(related_to === undefined ? {} : { related_to: { sender: related_to.sender, id: related_to.id } }) };
+}
+
+function inScope(entry: Entry, scope: ReadScope): boolean {
+  if (scope.peers !== undefined && !scope.peers.includes(entry.authenticated_author)) return false;
+  if (scope.since_seq !== undefined && BigInt(entry.seq) < BigInt(scope.since_seq)) return false;
+  if (scope.related_to !== undefined) {
+    const related = entry.message.meta?.in_reply_to;
+    if (!related || related.sender !== scope.related_to.sender || related.id !== scope.related_to.id) return false;
+  }
+  return true;
+}
+
+function freshThread(ref: ThreadRef, title: string, at: string): Thread {
+  return { thread_ref: ref, title, state: 'open', next_seq: '1', event_seq: '0', created_at: at, closed_at: null };
+}
+
+async function recordEvent(tx: Transaction, thread: Thread, type: Event['type'], data: Json): Promise<Thread> {
+  const seq = (BigInt(thread.event_seq) + 1n).toString();
+  const next: Thread = { ...thread, event_seq: seq };
+  await tx.put(key('thread', thread.thread_ref.owner, thread.thread_ref.id), next);
+  const event: Event = { id: seq, type, thread_ref: thread.thread_ref, data };
+  await tx.put(key('event', thread.thread_ref.owner, thread.thread_ref.id, seq), event);
+  return next;
+}
+
+/** Ascending by a unique string position, which is what core.page resumes on. */
+function sortedBy<T>(items: T[], position: (item: T) => string): T[] {
+  return items.sort((left, right) => {
+    const a = position(left);
+    const b = position(right);
+    return a < b ? -1 : a > b ? 1 : 0;
+  });
+}
+
+/** Reads a thread record under the caller's authority over its owner. */
+export async function getThread(tx: Transaction, ctx: Context, ref: ThreadRef): Promise<Thread> {
+  return loadThread(tx, ctx, ref);
+}
+
+/**
+ * Read authority for a thread: the owner reads everything; any other actor reads
+ * only as an active member holding read whose current read_scope admits the entry.
+ * The scope is evaluated at read time, never stored on the entry.
+ */
+export async function canRead(tx: Transaction, actor: string, ref: ThreadRef, entry?: Entry): Promise<boolean> {
+  const thread = await tx.get<Thread>(key('thread', ref.owner, ref.id));
+  if (actor === thread?.thread_ref.owner) return true;
+  if (entry !== undefined && (entry.thread_ref.owner !== ref.owner || entry.thread_ref.id !== ref.id)) return false;
+  const member = await tx.get<Member>(key('member', ref.owner, ref.id, actor));
+  if (member?.state !== 'active' || !member.access.includes('read')) return false;
+  return entry === undefined || inScope(entry, member.read_scope);
+}
+
+/**
+ * Issues the persistent grant notice an owner keeps until the recipient confirms it.
+ * The notice id is the member revision, so one revision maps to one notice and a
+ * retried membership change cannot queue a second delivery.
+ */
+async function issueGrant(tx: Transaction, ref: ThreadRef, peer: string, revision: string): Promise<Grant> {
+  const grant: Grant = { id: revision, recipient: peer, thread_ref: ref, revision, acked: false };
+  await tx.put(key('notice', grant.id), grant);
+  return grant;
+}
+
+/** What a recipient keeps once an owner grants access, independent of the notice ack. */
+interface Known {
+  owner: string;
+  thread_ref: ThreadRef;
+  revision: string;
+}
+
+export class ThreadService {
+  constructor(private readonly ctx: Context) {}
+
+  async create(auth: Auth, mutation: Mutation & { title: string; id?: string; default?: boolean }): Promise<Thread> {
+    if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
+    const owner = auth.actor;
+    this.ctx.owner(owner);
+    if (typeof mutation.title !== 'string' || mutation.title.length === 0) fail('invalid_request', 'A thread needs a title.');
+    if (mutation.id !== undefined && (typeof mutation.id !== 'string' || mutation.id.length === 0)) fail('invalid_request', 'Thread id must be a non-empty string.');
+    const wantsDefault = mutation.default === true || mutation.id === DEFAULT_THREAD;
+    const body = { title: mutation.title, id: mutation.id ?? null, default: wantsDefault };
+    return this.ctx.mutate(auth, 'thread.create', mutation, body, async tx => {
+      const at = new Date(this.ctx.now()).toISOString();
+      const existingDefault = await tx.get<Thread>(key('thread', owner, DEFAULT_THREAD));
+      if (wantsDefault) {
+        if (existingDefault) {
+          if (existingDefault.title === mutation.title || mutation.id === undefined) return existingDefault;
+          const retitled = { ...existingDefault, title: mutation.title };
+          await tx.put(key('thread', owner, DEFAULT_THREAD), retitled);
+          return retitled;
+        }
+        const thread = freshThread({ owner, id: DEFAULT_THREAD }, mutation.title, at);
+        await tx.put(key('thread', owner, DEFAULT_THREAD), thread);
+        await tx.put(key('default', owner), thread.thread_ref);
+        return thread;
+      }
+      let ref: ThreadRef;
+      if (mutation.id === undefined) {
+        ref = { owner, id: crypto.randomUUID() };
+        while (await tx.get(key('thread', owner, ref.id))) ref = { owner, id: crypto.randomUUID() };
+      } else {
+        ref = { owner, id: mutation.id };
+        if (await tx.get(key('thread', owner, ref.id)) || ref.id === DEFAULT_THREAD) fail('id_conflict', 'This thread id is already allocated for the owner.');
+      }
+      const thread = freshThread(ref, mutation.title, at);
+      await tx.put(key('thread', owner, ref.id), thread);
+      // An ordinary thread does not plant the landing slot: a default exists only when the
+      // owner asks for one, so opening a conversation never turns later first contacts into
+      // `not_a_member` refusals against a thread nobody joined.
+      return thread;
+    });
+  }
+
+  async close(auth: Auth, ref: ThreadRef, mutation: Mutation): Promise<Thread> {
+    if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
+    requireThreadRef(ref);
+    this.ctx.owner(ref.owner);
+    if (auth.actor !== ref.owner) fail('forbidden', 'Only the owner may close a thread.');
+    const body = { ref };
+    return this.ctx.mutate(auth, `thread.close/${ref.owner}/${ref.id}`, mutation, body, async tx => {
+      const thread = await loadThread(tx, this.ctx, ref);
+      if (thread.state === 'closed') fail('thread_closed', 'The thread is already closed.');
+      return recordEvent(tx, { ...thread, state: 'closed', closed_at: new Date(this.ctx.now()).toISOString() }, 'thread_closed', {});
+    });
+  }
+
+  async list(auth: Auth, options: PageOptions = {}): Promise<Page<Thread>> {
+    if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
+    this.ctx.owner(auth.actor);
+    return this.ctx.storage.transaction(async tx => {
+      const threads = sortedBy((await tx.scan<Thread>(key('thread', auth.actor) + '/')).map(row => row.value), thread => thread.thread_ref.id);
+      return page(threads, options, { kind: 'threads', owner: auth.actor }, thread => thread.thread_ref.id);
+    });
+  }
+
+  async describe(auth: Auth, ref: ThreadRef): Promise<{ thread: Thread; members: Member[] }> {
+    if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
+    return this.ctx.storage.transaction(async tx => {
+      const thread = await loadThread(tx, this.ctx, ref);
+      if (!await canRead(tx, auth.actor, ref)) fail('forbidden', 'The caller does not hold read access to this thread.');
+      const members = (await tx.scan<Member>(key('member', ref.owner, ref.id) + '/')).map(row => row.value);
+      return { thread, members };
+    });
+  }
+
+  async member(auth: Auth, ref: ThreadRef, peer: string, patch: Partial<Member>, mutation: Mutation): Promise<Member> {
+    if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
+    requireThreadRef(ref);
+    if (typeof peer !== 'string' || peer.length === 0) fail('invalid_request', 'A membership names its peer.');
+    const isOwner = auth.actor === ref.owner;
+    if (!isOwner && auth.actor !== peer) fail('forbidden', 'Only the owner manages other peers.');
+    if (patch.revision !== undefined) fail('invalid_request', 'The revision is issued by the owner.');
+    if (!isOwner && (patch.access !== undefined || patch.read_scope !== undefined || (patch.state !== undefined && patch.state !== 'revoked' && patch.state !== 'active'))) {
+      fail('forbidden', 'A peer may only join or withdraw itself.');
+    }
+    const body = { ref, peer, patch };
+    return this.ctx.mutate(auth, `thread.member/${ref.owner}/${ref.id}/${peer}`, mutation, body, async tx => {
+      const thread = await loadThread(tx, this.ctx, ref);
+      const current = await tx.get<Member>(key('member', ref.owner, ref.id, peer));
+      let next: Member;
+      if (!isOwner) {
+        if (current === undefined) {
+          if (patch.state === 'revoked') fail('not_found', 'No membership record to withdraw.');
+          if (thread.state === 'closed') fail('thread_closed', 'A closed thread does not accept joins.');
+          const admitted = (await this.ctx.options.plugins.mayAdmit?.(auth.actor, ref, admissionView(tx))) === true;
+          next = { peer, state: admitted ? 'active' : 'requested', access: [...DEFAULT_ACCESS], read_scope: {}, revision: this.ctx.id() };
+        } else if (patch.state === 'revoked') {
+          if (current.state !== 'active' && current.state !== 'requested') fail('conflict', 'This membership is already stopped.');
+          next = { ...current, state: 'revoked', access: [], revision: this.ctx.id() };
+        } else {
+          fail('conflict', 'This peer already holds a membership record; only the owner changes it.');
+        }
+      } else {
+        const state = patch.state ?? 'active';
+        if (state !== 'requested' && state !== 'active' && state !== 'revoked' && state !== 'denied') fail('invalid_request', 'Unknown member state.');
+        const stopping = state === 'revoked' || state === 'denied';
+        const access = stopping ? [] : patch.access === undefined ? (current?.state === 'active' ? current.access : [...DEFAULT_ACCESS]) : requireAccess(patch.access);
+        next = { peer, state, access: [...access], read_scope: patch.read_scope === undefined ? (current?.read_scope ?? {}) : requireScope(patch.read_scope), revision: this.ctx.id() };
+      }
+      await tx.put(key('member', ref.owner, ref.id, peer), next);
+      if (next.state === 'active' && current?.state !== 'active' && peer !== ref.owner) await issueGrant(tx, ref, peer, next.revision);
+      await recordEvent(tx, thread, 'membership', JSON.parse(JSON.stringify(next)) as Json);
+      return next;
+    });
+  }
+
+  async members(auth: Auth, ref: ThreadRef, options: PageOptions = {}): Promise<Page<Member>> {
+    if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
+    return this.ctx.storage.transaction(async tx => {
+      await loadThread(tx, this.ctx, ref);
+      if (!await canRead(tx, auth.actor, ref)) fail('forbidden', 'The caller does not hold read access to this thread.');
+      const members = sortedBy((await tx.scan<Member>(key('member', ref.owner, ref.id) + '/')).map(row => row.value), member => member.peer);
+      return page(members, options, { kind: 'members', ref }, member => member.peer);
+    });
+  }
+
+  async defaultThread(auth: Auth): Promise<ThreadRef> {
+    if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
+    this.ctx.owner(auth.actor);
+    return this.ctx.storage.transaction(async tx => requireValue(await tx.get<ThreadRef>(key('default', auth.actor))));
+  }
+
+  /**
+   * Owner-side notice outbox: every grant notice this node issued that has no ack yet.
+   * Only the owner calling as ctx.node may read this list; each item carries recipient
+   * so the client knows where to POST the full notice.
+   */
+  async notices(auth: Auth, options: PageOptions = {}): Promise<Page<Grant>> {
+    if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
+    this.ctx.owner(auth.actor);
+    return this.ctx.storage.transaction(async tx => {
+      const held = sortedBy((await tx.scan<Grant>(key('notice') + '/')).map(row => row.value).filter(grant => !grant.acked), grant => grant.id);
+      return page(held, options, { kind: 'notices', owner: auth.actor }, grant => grant.id);
+    });
+  }
+
+  /**
+   * Recipient view: the grants this node accepted from owners, until it confirms each one.
+   * A missed push is fetched over HTTP and processed with acceptGrant; this list is what
+   * the confirmation pass walks to close the owner's notice.
+   */
+  async grants(auth: Auth, options: PageOptions = {}): Promise<Page<Grant>> {
+    if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
+    return this.ctx.storage.transaction(async tx => {
+      const held = sortedBy((await tx.scan<Grant>(key('grant') + '/')).map(row => row.value).filter(grant => !grant.acked), grant => grant.id);
+      return page(held, options, { kind: 'grants', recipient: auth.actor }, grant => grant.id);
+    });
+  }
+
+  /** Recipient side: records that the owner confirmed this grant, so it is not confirmed twice. */
+  async ackGrantLocally(auth: Auth, ref: ThreadRef, id: string): Promise<void> {
+    if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
+    await this.ctx.storage.transaction(async tx => {
+      const slot = key('grant', ref.owner, id);
+      const stored = await tx.get<Grant>(slot);
+      if (stored !== undefined && !stored.acked) await tx.put(slot, { ...stored, acked: true });
+    });
+  }
+
+  /**
+   * Recipient side of grant acceptance: an owner pushes us a notice we received during
+   * a prior join. We store both the notice and the known-owner record keyed owner+threadid.
+   * Caller is the owner the notice names, notice is addressed to our node, thread stays on owner.
+   */
+  async acceptGrant(auth: Auth, grant: Grant): Promise<Grant> {
+    if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
+    if (grant == null || typeof grant !== 'object' || typeof grant.id !== 'string' || grant.id.length === 0 || typeof grant.revision !== 'string' || grant.revision.length === 0) {
+      fail('invalid_request', 'Expected a grant notice with an id and a revision.');
+    }
+    requireThreadRef(grant.thread_ref);
+    if (grant.thread_ref.owner !== auth.actor) fail('forbidden', 'A grant notice must come from the thread owner it names.');
+    if (grant.recipient !== this.ctx.node) fail('forbidden', 'The grant notice is addressed to another node.');
+    const ref: ThreadRef = { owner: grant.thread_ref.owner, id: grant.thread_ref.id };
+    return this.ctx.storage.transaction(async tx => {
+      const slot = key('grant', ref.owner, grant.id);
+      const stored = await tx.get<Grant>(slot);
+      if (stored !== undefined && (stored.recipient !== this.ctx.node || stored.revision !== grant.revision || stored.thread_ref.id !== ref.id)) {
+        fail('id_conflict', 'The grant id is bound to another notice.');
+      }
+      const known: Known = { owner: ref.owner, thread_ref: ref, revision: grant.revision };
+      await tx.put(key('known', ref.owner, ref.id), known);
+      if (stored !== undefined) return stored;
+      const next: Grant = { id: grant.id, recipient: this.ctx.node, thread_ref: ref, revision: grant.revision, acked: false };
+      await tx.put(slot, next);
+      return next;
+    });
+  }
+
+  /**
+   * Acknowledge a notice on the owner node: owner receives our confirmation, updates
+   * the owner-issued notice to acked:true, stops retries. Caller must be recipient of the notice.
+   */
+  async ackGrant(auth: Auth, id: string, mutation: Mutation): Promise<Grant> {
+    if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
+    if (typeof id !== 'string' || id.length === 0) fail('invalid_request', 'A grant id is required.');
+    const body = { id };
+    return this.ctx.mutate(auth, `thread.grant.ack/${id}`, mutation, body, async tx => {
+      const grant = requireValue(await tx.get<Grant>(key('notice', id)));
+      if (grant.recipient !== auth.actor) fail('forbidden', 'The grant notice is addressed to another recipient.');
+      if (grant.acked) return grant;
+      const acked: Grant = { ...grant, acked: true };
+      await tx.put(key('notice', id), acked);
+      return acked;
+    });
+  }
+
+  async permits(auth: Auth, permit: ReplyPermit, mutation: Mutation): Promise<ReplyPermit> {
+    if (!auth.actor) fail('unauthenticated', 'Authentication is required.');
+    const original: MessageRef | undefined = permit?.message_ref;
+    if (typeof original?.sender !== 'string' || !original.sender || typeof original.id !== 'string' || !original.id) fail('invalid_request', 'A permit binds a complete MessageRef.');
+    if (original.sender !== auth.actor) fail('forbidden', 'Only the original message sender may issue a reply permit.');
+    if (typeof permit.grantee !== 'string' || !permit.grantee || permit.grantee === auth.actor) fail('invalid_request', 'A permit names one grantee other than its issuer.');
+    requireThreadRef(permit.landing);
+    this.ctx.owner(permit.landing.owner);
+    if (!Number.isInteger(permit.remaining) || permit.remaining < 1) fail('invalid_request', 'A permit needs a bounded positive reply count.');
+    if (utc(permit.expires_at) <= this.ctx.now()) fail('invalid_request', 'A permit needs a future expiry.');
+    const body = { message_ref: { sender: original.sender, id: original.id }, grantee: permit.grantee, landing: permit.landing, expires_at: permit.expires_at, remaining: permit.remaining, followup: permit.followup === true };
+    return this.ctx.mutate(auth, `thread.permit/${original.sender}/${original.id}/${permit.grantee}`, mutation, body, async tx => {
+      const thread = await loadThread(tx, this.ctx, permit.landing);
+      if (thread.state === 'closed') fail('thread_closed', 'A permit cannot land on a closed thread.');
+      const stored: ReplyPermit = { ...body, revoked: permit.revoked === true };
+      await tx.put(key('permit', original.sender, original.id, permit.grantee), stored);
+      return stored;
+    });
+  }
+}

package/src/transport.ts

@@ -0,0 +1,204 @@
+import { OnlyneError } from './core.js';
+import type { ErrorCode, Failure, NodeId, Target, Transport, TrustEntry } from './types.js';
+import type { TrustService } from './keys.js';
+
+/** The trust reads and signing steps a transport performs; a host that builds its own node wraps the real service. */
+export type SigningTrust = Pick<TrustService, 'entry' | 'signRequest' | 'verifyResponse'>;
+
+/**
+ * RFC 0017 §3: the pairing act a missing-trust failure names, before any host surface is
+ * known. `responsible_node` is the holder who still owes the act — this node when it never
+ * asked or must approve, the peer when it owes the answer — and `required_action` is what
+ * that holder does. A transport that cannot name its own node leaves `self` and the local
+ * cases' `responsible_node` null rather than guessing an identity.
+ */
+export interface TrustFailure {
+  self: NodeId | null;
+  peer: NodeId;
+  reason: 'no_record' | 'pending' | 'revoked';
+  responsible_node: NodeId | null;
+  required_action: 'request_exchange' | 'confirm_exchange' | 'restore_trust';
+}
+
+/** RFC 0017 request signing: transcripts, response verification, trust-state gating. */
+export interface SigningTransportOptions {
+  trust: SigningTrust;
+  /**
+   * Where this host's holder reaches the act a missing-trust failure names. The library knows
+   * which node owes the act and what it is; only the host knows its own menu, so the failure
+   * carries the host's path instead of one this file would have to invent. The path describes
+   * the responsible node's surface: the peer's own menu when that holder owes the answer.
+   */
+  guidance?(details: TrustFailure): { entry: string[] } | undefined;
+}
+
+// Loopback hosts may speak plain HTTP. Everything else reached by a resolver
+// could be a remote peer, so it must be HTTPS: a cleartext binding would put
+// bearer credentials on the wire.
+const LOOPBACK: Record<string, true> = { '127.0.0.1': true, localhost: true, '[::1]': true };
+
+/**
+ * The base URL a service request may use: HTTPS anywhere, plain HTTP on loopback only.
+ * Public reads (a candidate's service description) use the same rule, so one host cannot
+ * downgrade the other.
+ */
+export function serviceBase(value: string): URL {
+  let base: URL;
+  try { base = new URL(value); } catch { throw new OnlyneError('unavailable', 'The endpoint is not an absolute URL.'); }
+  if (base.protocol !== 'https:' && !(base.protocol === 'http:' && LOOPBACK[base.hostname] === true)) {
+    throw new OnlyneError('unavailable', 'Plain HTTP is limited to loopback; cross-host peers must use HTTPS.');
+  }
+  return base;
+}
+
+function isFailure(value: unknown): value is Failure {
+  return typeof value === 'object' && value !== null && 'code' in value && 'message' in value && typeof value.code === 'string' && typeof value.message === 'string';
+}
+
+// Some bindings answer errors without the envelope when the request never
+// reached service code; a bare failure record is still preserved.
+function failureRecord(parsed: unknown): unknown {
+  return typeof parsed === 'object' && parsed !== null && 'error' in parsed ? parsed.error : parsed;
+}
+
+/**
+ * RFC 0017 §3: what a signed request hits when this node holds no trusted key for the peer.
+ * Both node ids travel in the text and in `details`, because a missing key here says nothing
+ * about whether the peer runs. The agent cannot pair the nodes — only the node's holder can,
+ * through the host surface — and the runtime re-sends the record that stays open, so the code
+ * is `unavailable` and the message keeps that retry apart from an agent repeating the send.
+ * The failure names the responsible holder and the act; the host's `guidance` adds the menu
+ * entry, so every trust case ends at one concrete surface instead of a search.
+ */
+function missingTrust(
+  self: NodeId | null, target: NodeId, peer: TrustEntry | undefined,
+  guidance: SigningTransportOptions['guidance'],
+): OnlyneError {
+  const here = self ?? 'this node';
+  const retry = 'The runtime re-sends the open record once the pairing exists; do not re-send it yourself.';
+  const reason: TrustFailure['reason'] = peer === undefined ? 'no_record' : peer.state === 'revoked' ? 'revoked' : 'pending';
+  const required_action: TrustFailure['required_action'] = reason === 'pending' ? 'confirm_exchange' : reason === 'revoked' ? 'restore_trust' : 'request_exchange';
+  // A pending row says which holder still owes the act: ours when the peer asked, theirs when we did.
+  const responsible_node = reason === 'pending' && peer?.local_approved === true ? target : self;
+  const details = { self, peer: target, reason, responsible_node, required_action };
+  const guide = guidance?.(details);
+  const surface = guide === undefined ? '' : `: ${guide.entry.join(' → ')}`;
+  const failure = guide === undefined ? details : { ...details, entry: guide.entry };
+  if (reason === 'no_record') {
+    return new OnlyneError('unavailable',
+      `${here} holds no trust record for ${target}, so this request cannot be signed. This agent cannot grant trust; the holder of ${here} completes the pairing through this node's Onlyne surface${surface}. ${retry}`,
+      failure);
+  }
+  if (reason === 'revoked') {
+    return new OnlyneError('unavailable',
+      `${here} revoked ${target}, so this request cannot be signed. This agent cannot restore trust; the holder of ${here} pairs the two nodes again through this node's Onlyne surface${surface}. ${retry}`,
+      failure);
+  }
+  const message = peer!.local_approved
+    ? `${target} has not answered the exchange ${here} requested, so this request cannot be signed yet. This agent cannot complete the pairing; the holder of ${target} confirms it through that node's Onlyne surface${surface}. ${retry}`
+    : `${target} requested an exchange with ${here} and this node has not approved it, so this request cannot be signed yet. This agent cannot approve it; the holder of ${here} confirms the fingerprint through this node's Onlyne surface${surface}. ${retry}`;
+  return new OnlyneError('unavailable', message, failure);
+}
+
+export class FetchTransport implements Transport {
+  private readonly resolve: (node: NodeId) => Promise<Target>;
+  private readonly fetcher: typeof fetch;
+  private readonly signing: SigningTransportOptions | undefined;
+
+  constructor(resolve: (node: NodeId) => Promise<Target>, fetcher: typeof fetch = fetch, signing?: SigningTransportOptions) {
+    this.resolve = resolve;
+    this.fetcher = fetcher;
+    this.signing = signing;
+  }
+
+  async request<T>(target: NodeId, method: string, path: string, body?: unknown, signal?: AbortSignal): Promise<T> {
+    const endpoint = await this.resolve(target);
+    if (endpoint.node_id !== target) {
+      throw new OnlyneError('unavailable', 'The resolver returned a target for another identity.');
+    }
+    const base = serviceBase(endpoint.base_url);
+    // The route is relative to base_url, which already carries the service
+    // prefix; a leading slash would silently drop that prefix.
+    const url = new URL('./' + path.replace(/^\/+/, ''), base.pathname.endsWith('/') ? base : base.href + '/');
+    if (url.origin !== base.origin) {
+      throw new OnlyneError('invalid_request', 'The request path leaves the endpoint origin.');
+    }
+
+    const headers = new Headers(endpoint.headers);
+    const serialized = body === undefined ? '' : JSON.stringify(body);
+    if (body !== undefined) {
+      headers.set('Content-Type', 'application/json');
+      // A server rejects the whole request when this header contradicts the
+      // body, so the key travels as a header only from the top-level field the
+      // body already carries; the body keeps its own copy.
+      if (typeof body === 'object' && body !== null && 'idempotency_key' in body && typeof body.idempotency_key === 'string' && body.idempotency_key !== '') {
+        headers.set('Idempotency-Key', body.idempotency_key);
+      }
+    }
+    if (this.signing !== undefined) {
+      const peer = await this.signing.trust.entry(target);
+      // No trusted key for this peer: the request cannot be signed, and sending it unsigned
+      // would be refused anyway. Report a retryable outage so the record stays open while the
+      // node holder completes the pairing, instead of recording a permanent refusal. The
+      // resolver supplies `Onlyne-Actor`, so the outbound request already names this node.
+      if (peer?.state !== 'trusted') {
+        throw missingTrust(headers.get('Onlyne-Actor'), target, peer, this.signing.guidance);
+      }
+      {
+        const signer = new Request(url.href, { method, headers });
+        await this.signing.trust.signRequest(signer, target, serialized);
+        for (const [name, value] of signer.headers) headers.set(name, value);
+      }
+    }
+
+    let response: Response;
+    const request = new Request(url.href, { method, headers });
+    try {
+      response = await this.fetcher(url, {
+        method,
+        headers,
+        body: body === undefined ? undefined : serialized,
+        signal,
+      });
+    } catch (error) {
+      // A consumer's cancellation is not a reachability fault; the caller sees
+      // its own abort reason instead of a retryable outage.
+      if (signal?.aborted) throw signal.reason;
+      throw new OnlyneError('unavailable', 'The target could not be reached.');
+    }
+
+    let text: string;
+    try {
+      text = await response.text();
+    } catch {
+      throw new OnlyneError('unavailable', 'The response body could not be read.');
+    }
+    let parsed: unknown;
+    try {
+      parsed = text === '' ? undefined : JSON.parse(text);
+    } catch {
+      parsed = undefined;
+    }
+
+    if (response.ok) {
+      if (parsed === undefined) throw new OnlyneError('unavailable', 'The target returned a malformed response.');
+      // A signed request is only ever sent to a trusted peer, so its answer must prove that
+      // identity; `verifyResponse` fails when the row is missing, untrusted or the signature
+      // does not cover this request's nonce.
+      if (this.signing !== undefined) await this.signing.trust.verifyResponse(target, request, response, text);
+      return parsed as T;
+    }
+
+    const record = failureRecord(parsed);
+    // A signed request is answered by a signed response even when it fails; an unsigned or
+    // forged error must not be read as the peer's refusal.
+    if (this.signing !== undefined) await this.signing.trust.verifyResponse(target, request, response, text);
+    if (isFailure(record)) {
+      const rejection = new OnlyneError(record.code as ErrorCode, record.message);
+      if (typeof record.retryable === 'boolean') rejection.error.retryable = record.retryable;
+      if (record.details !== undefined) rejection.error.details = record.details;
+      throw rejection;
+    }
+    throw new OnlyneError(response.status >= 500 ? 'unavailable' : 'internal', `The target answered HTTP ${response.status} without a failure record.`);
+  }
+}