@onlyne/lib 3.1.0 → 3.2.0

package/dist/transport.js

@@ -0,0 +1,175 @@
+import { OnlyneError } from "./core.js";
+// 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 = { '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) {
+    let base;
+    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) {
+    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) {
+    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 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.
+ *
+ * A pending exchange is not a task for the reader: the invitation is already recorded on the
+ * side that owes the approval, and the acquisition policy there submits the approval on the
+ * next attempt, or that node's holder confirms it (RFC 0018 §4). The text says that instead of
+ * prescribing a menu step, because with policy `all` or `segment` no one has to act. The
+ * `no_record` and `revoked` cases keep the host's `guidance` menu, since nothing records them
+ * yet and only a holder can start or restore the exchange.
+ */
+function missingTrust(self, target, peer, guidance) {
+    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 = peer === undefined ? 'no_record' : peer.state === 'revoked' ? 'revoked' : 'pending';
+    const 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') {
+        // The exchange has a sanctioned start that is not a human step: `trust_begin` on this
+        // node, judged by this node's acquisition policy, and the peer's policy judges the
+        // statement that arrives. Naming only the panel hid that path (tern host report).
+        return new OnlyneError('unavailable', `${here} holds no trust record for ${target}, so this request cannot be signed. Start the exchange with trust_begin, which the acquisition policy on ${here} judges; ${target} can also start one, and this node's policy judges the arriving statement. A holder can complete 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. The invitation is recorded at ${target} as pending; the acquisition policy on that node submits the approval on the next attempt, or its holder confirms it${surface}. ${retry}`
+        : `${target} requested an exchange with ${here} and this node has not approved it, so this request cannot be signed yet. The invitation is recorded here as pending; this node's acquisition policy submits the approval on the next attempt, or its holder confirms it${surface}. ${retry}`;
+    return new OnlyneError('unavailable', message, failure);
+}
+export class FetchTransport {
+    resolve;
+    fetcher;
+    signing;
+    constructor(resolve, fetcher = fetch, signing) {
+        this.resolve = resolve;
+        this.fetcher = fetcher;
+        this.signing = signing;
+    }
+    async request(target, method, path, body, signal) {
+        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;
+        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;
+        try {
+            text = await response.text();
+        }
+        catch {
+            throw new OnlyneError('unavailable', 'The response body could not be read.');
+        }
+        let parsed;
+        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;
+        }
+        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, 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.`);
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}