wire-mesh-core 1.25.0 → 1.26.0

package/dist/domain/mesh-session.cjs

@@ -475,7 +475,67 @@ async function acceptMeshSession(connection, identity, localDomains, options = {
 		peerDeviceId
 	};
 }
+/** Reads exactly one frame off a freshly-accepted, bare connection and, if it's a manage-request, returns an IncomingManageRequest ready to hand to the same application-level dispatch logic session.incomingManageRequests already feeds elsewhere -- no handshake or gossip is ever read or sent on this connection (wire-mesh#38: the manage-request/manage-response exchange has no dependency on handshake state at the dispatch layer, confirmed against applyManageRequest/applyFrame above). respond() sends the manage-response directly and closes the connection, since a one-off request/response is this connection's entire purpose -- unlike a real MeshSession, there is nothing further to do with it afterwards. Resolves null, without closing the connection (that's the caller's call), for any other first frame or if the connection ends before one arrives: interpreting either case is a Transport.listen() caller's own business, e.g. peeking the first frame to route between this path and acceptMeshSession's own handshake path. */
+async function acceptDirectManageRequest(connection) {
+	const result = await connection.receive()[Symbol.asyncIterator]().next();
+	if (result.done === true || result.value.type !== "manage-request") return null;
+	const frame = result.value;
+	return {
+		requestId: frame["request-id"],
+		command: frame.command,
+		scope: frame.scope,
+		...frame.token !== void 0 ? { token: frame.token } : {},
+		respond: async (outcome) => {
+			const response = {
+				type: "manage-response",
+				"request-id": frame["request-id"],
+				outcome
+			};
+			await connection.send(response);
+			await connection.close();
+		}
+	};
+}
+async function waitForDirectManageResponse(link, requestId) {
+	for await (const frame of link.receive()) if (frame.type === "manage-response" && frame["request-id"] === requestId) return frame.outcome;
+	throw new Error("connection closed before a response arrived");
+}
+/** Sends exactly one manage-request over a fresh, bare connection with no handshake, negotiation, or gossip exchanged, and no session left behind afterwards -- the connection closes once the correlated response arrives, the wait times out, or the peer-device-id check below refuses it. For attempting a direct connection to a peer whose reachable address is already known (wire-mesh#38), as an alternative to routing the same request through a relay via an established MeshSession's own sendManageRequest(targetDevice, ...). Resolves the same ManageOutcome shape sendManageRequest does -- including `{ result: "error", code: "timeout" }` on a timeout, never a rejection -- so a caller can fall back to the relay path uniformly regardless of which kind of failure this returns for the non-spoofing cases; a peer-device-id mismatch is the one case that rejects outright, since it is not an ordinary reachability failure a relay fallback should silently paper over. */
+async function sendDirectManageRequest(transport, address, command, scope, options = {}) {
+	const link = await transport.connect(address);
+	if (options.expectedPeerDeviceId !== void 0 && link.peerDeviceId !== void 0 && require_domain_device_id.deviceIdToHex(link.peerDeviceId) !== require_domain_device_id.deviceIdToHex(options.expectedPeerDeviceId)) {
+		await link.close();
+		throw new Error("direct connection's authenticated peer-device-id does not match the expected target -- refusing as a possible spoofing attempt");
+	}
+	const requestId = 0;
+	const frame = {
+		type: "manage-request",
+		"request-id": requestId,
+		command,
+		scope,
+		...options.token !== void 0 ? { token: options.token } : {}
+	};
+	await link.send(frame);
+	const responsePromise = waitForDirectManageResponse(link, requestId);
+	let outcome;
+	if (options.timeoutMs === void 0) outcome = await responsePromise;
+	else {
+		outcome = await Promise.race([responsePromise, new Promise((resolve) => {
+			setTimeout(() => {
+				resolve({
+					result: "error",
+					code: "timeout"
+				});
+			}, options.timeoutMs);
+		})]);
+		responsePromise.catch(() => void 0);
+	}
+	await link.close();
+	return outcome;
+}
 //#endregion
 exports.HANDSHAKE_TIMEOUT_MS = HANDSHAKE_TIMEOUT_MS;
+exports.acceptDirectManageRequest = acceptDirectManageRequest;
 exports.acceptMeshSession = acceptMeshSession;
 exports.createMeshSession = createMeshSession;
+exports.sendDirectManageRequest = sendDirectManageRequest;

package/dist/domain/mesh-session.d.cts

@@ -108,4 +108,15 @@ export interface AcceptedMeshSessionOptions {
 }
 /** Wires an already-accepted Connection up as a full MeshSession, mirroring exactly what createMeshSession's own dial path does once a connection exists (send handshake, send self-advert, negotiate, consume frames) -- the wire-mesh#45 prerequisite agent-comms needs, since its peers both listen and dial rather than only ever dialing the way web-console's own console UI does. Reconnect does not apply here: if this connection drops, only the remote redialing and being accepted again produces a new connection, and therefore a new session -- there is nothing on this side to retry. */
 export declare function acceptMeshSession(connection: Readonly<Connection>, identity: Readonly<IdentityPort>, localDomains: readonly string[], options?: Readonly<AcceptedMeshSessionOptions>): Promise<AcceptedMeshSession>;
+/** Reads exactly one frame off a freshly-accepted, bare connection and, if it's a manage-request, returns an IncomingManageRequest ready to hand to the same application-level dispatch logic session.incomingManageRequests already feeds elsewhere -- no handshake or gossip is ever read or sent on this connection (wire-mesh#38: the manage-request/manage-response exchange has no dependency on handshake state at the dispatch layer, confirmed against applyManageRequest/applyFrame above). respond() sends the manage-response directly and closes the connection, since a one-off request/response is this connection's entire purpose -- unlike a real MeshSession, there is nothing further to do with it afterwards. Resolves null, without closing the connection (that's the caller's call), for any other first frame or if the connection ends before one arrives: interpreting either case is a Transport.listen() caller's own business, e.g. peeking the first frame to route between this path and acceptMeshSession's own handshake path. */
+export declare function acceptDirectManageRequest(connection: Readonly<Connection>): Promise<IncomingManageRequest | null>;
+export interface DirectManageRequestOptions {
+  /** Refuse the connection as a possible spoofing attempt if the transport's own authenticated Connection.peerDeviceId (never a value read off the wire -- see the Transport port's own doc comment) doesn't match this. Left unchecked when the transport gives no authenticated peerDeviceId at all (an unauthenticated transport, or a peer that presented no credential) -- the caller proceeds at its own risk in that case, exactly the same trust boundary Connection.peerDeviceId already documents for every other consumer of it. */
+  expectedPeerDeviceId?: DeviceId;
+  token?: CapabilityToken;
+  /** Omit to wait indefinitely, matching sendManageRequest's own default. */
+  timeoutMs?: number;
+}
+/** Sends exactly one manage-request over a fresh, bare connection with no handshake, negotiation, or gossip exchanged, and no session left behind afterwards -- the connection closes once the correlated response arrives, the wait times out, or the peer-device-id check below refuses it. For attempting a direct connection to a peer whose reachable address is already known (wire-mesh#38), as an alternative to routing the same request through a relay via an established MeshSession's own sendManageRequest(targetDevice, ...). Resolves the same ManageOutcome shape sendManageRequest does -- including `{ result: "error", code: "timeout" }` on a timeout, never a rejection -- so a caller can fall back to the relay path uniformly regardless of which kind of failure this returns for the non-spoofing cases; a peer-device-id mismatch is the one case that rejects outright, since it is not an ordinary reachability failure a relay fallback should silently paper over. */
+export declare function sendDirectManageRequest(transport: Readonly<Pick<Transport, "connect">>, address: string, command: ManageCommand, scope: Readonly<CapabilityScope>, options?: Readonly<DirectManageRequestOptions>): Promise<ManageOutcome>;
 //#endregion

package/dist/domain/mesh-session.d.mts

@@ -108,4 +108,15 @@ export interface AcceptedMeshSessionOptions {
 }
 /** Wires an already-accepted Connection up as a full MeshSession, mirroring exactly what createMeshSession's own dial path does once a connection exists (send handshake, send self-advert, negotiate, consume frames) -- the wire-mesh#45 prerequisite agent-comms needs, since its peers both listen and dial rather than only ever dialing the way web-console's own console UI does. Reconnect does not apply here: if this connection drops, only the remote redialing and being accepted again produces a new connection, and therefore a new session -- there is nothing on this side to retry. */
 export declare function acceptMeshSession(connection: Readonly<Connection>, identity: Readonly<IdentityPort>, localDomains: readonly string[], options?: Readonly<AcceptedMeshSessionOptions>): Promise<AcceptedMeshSession>;
+/** Reads exactly one frame off a freshly-accepted, bare connection and, if it's a manage-request, returns an IncomingManageRequest ready to hand to the same application-level dispatch logic session.incomingManageRequests already feeds elsewhere -- no handshake or gossip is ever read or sent on this connection (wire-mesh#38: the manage-request/manage-response exchange has no dependency on handshake state at the dispatch layer, confirmed against applyManageRequest/applyFrame above). respond() sends the manage-response directly and closes the connection, since a one-off request/response is this connection's entire purpose -- unlike a real MeshSession, there is nothing further to do with it afterwards. Resolves null, without closing the connection (that's the caller's call), for any other first frame or if the connection ends before one arrives: interpreting either case is a Transport.listen() caller's own business, e.g. peeking the first frame to route between this path and acceptMeshSession's own handshake path. */
+export declare function acceptDirectManageRequest(connection: Readonly<Connection>): Promise<IncomingManageRequest | null>;
+export interface DirectManageRequestOptions {
+  /** Refuse the connection as a possible spoofing attempt if the transport's own authenticated Connection.peerDeviceId (never a value read off the wire -- see the Transport port's own doc comment) doesn't match this. Left unchecked when the transport gives no authenticated peerDeviceId at all (an unauthenticated transport, or a peer that presented no credential) -- the caller proceeds at its own risk in that case, exactly the same trust boundary Connection.peerDeviceId already documents for every other consumer of it. */
+  expectedPeerDeviceId?: DeviceId;
+  token?: CapabilityToken;
+  /** Omit to wait indefinitely, matching sendManageRequest's own default. */
+  timeoutMs?: number;
+}
+/** Sends exactly one manage-request over a fresh, bare connection with no handshake, negotiation, or gossip exchanged, and no session left behind afterwards -- the connection closes once the correlated response arrives, the wait times out, or the peer-device-id check below refuses it. For attempting a direct connection to a peer whose reachable address is already known (wire-mesh#38), as an alternative to routing the same request through a relay via an established MeshSession's own sendManageRequest(targetDevice, ...). Resolves the same ManageOutcome shape sendManageRequest does -- including `{ result: "error", code: "timeout" }` on a timeout, never a rejection -- so a caller can fall back to the relay path uniformly regardless of which kind of failure this returns for the non-spoofing cases; a peer-device-id mismatch is the one case that rejects outright, since it is not an ordinary reachability failure a relay fallback should silently paper over. */
+export declare function sendDirectManageRequest(transport: Readonly<Pick<Transport, "connect">>, address: string, command: ManageCommand, scope: Readonly<CapabilityScope>, options?: Readonly<DirectManageRequestOptions>): Promise<ManageOutcome>;
 //#endregion

package/dist/domain/mesh-session.mjs

@@ -474,5 +474,63 @@ async function acceptMeshSession(connection, identity, localDomains, options = {
 		peerDeviceId
 	};
 }
+/** Reads exactly one frame off a freshly-accepted, bare connection and, if it's a manage-request, returns an IncomingManageRequest ready to hand to the same application-level dispatch logic session.incomingManageRequests already feeds elsewhere -- no handshake or gossip is ever read or sent on this connection (wire-mesh#38: the manage-request/manage-response exchange has no dependency on handshake state at the dispatch layer, confirmed against applyManageRequest/applyFrame above). respond() sends the manage-response directly and closes the connection, since a one-off request/response is this connection's entire purpose -- unlike a real MeshSession, there is nothing further to do with it afterwards. Resolves null, without closing the connection (that's the caller's call), for any other first frame or if the connection ends before one arrives: interpreting either case is a Transport.listen() caller's own business, e.g. peeking the first frame to route between this path and acceptMeshSession's own handshake path. */
+async function acceptDirectManageRequest(connection) {
+	const result = await connection.receive()[Symbol.asyncIterator]().next();
+	if (result.done === true || result.value.type !== "manage-request") return null;
+	const frame = result.value;
+	return {
+		requestId: frame["request-id"],
+		command: frame.command,
+		scope: frame.scope,
+		...frame.token !== void 0 ? { token: frame.token } : {},
+		respond: async (outcome) => {
+			const response = {
+				type: "manage-response",
+				"request-id": frame["request-id"],
+				outcome
+			};
+			await connection.send(response);
+			await connection.close();
+		}
+	};
+}
+async function waitForDirectManageResponse(link, requestId) {
+	for await (const frame of link.receive()) if (frame.type === "manage-response" && frame["request-id"] === requestId) return frame.outcome;
+	throw new Error("connection closed before a response arrived");
+}
+/** Sends exactly one manage-request over a fresh, bare connection with no handshake, negotiation, or gossip exchanged, and no session left behind afterwards -- the connection closes once the correlated response arrives, the wait times out, or the peer-device-id check below refuses it. For attempting a direct connection to a peer whose reachable address is already known (wire-mesh#38), as an alternative to routing the same request through a relay via an established MeshSession's own sendManageRequest(targetDevice, ...). Resolves the same ManageOutcome shape sendManageRequest does -- including `{ result: "error", code: "timeout" }` on a timeout, never a rejection -- so a caller can fall back to the relay path uniformly regardless of which kind of failure this returns for the non-spoofing cases; a peer-device-id mismatch is the one case that rejects outright, since it is not an ordinary reachability failure a relay fallback should silently paper over. */
+async function sendDirectManageRequest(transport, address, command, scope, options = {}) {
+	const link = await transport.connect(address);
+	if (options.expectedPeerDeviceId !== void 0 && link.peerDeviceId !== void 0 && deviceIdToHex(link.peerDeviceId) !== deviceIdToHex(options.expectedPeerDeviceId)) {
+		await link.close();
+		throw new Error("direct connection's authenticated peer-device-id does not match the expected target -- refusing as a possible spoofing attempt");
+	}
+	const requestId = 0;
+	const frame = {
+		type: "manage-request",
+		"request-id": requestId,
+		command,
+		scope,
+		...options.token !== void 0 ? { token: options.token } : {}
+	};
+	await link.send(frame);
+	const responsePromise = waitForDirectManageResponse(link, requestId);
+	let outcome;
+	if (options.timeoutMs === void 0) outcome = await responsePromise;
+	else {
+		outcome = await Promise.race([responsePromise, new Promise((resolve) => {
+			setTimeout(() => {
+				resolve({
+					result: "error",
+					code: "timeout"
+				});
+			}, options.timeoutMs);
+		})]);
+		responsePromise.catch(() => void 0);
+	}
+	await link.close();
+	return outcome;
+}
 //#endregion
-export { HANDSHAKE_TIMEOUT_MS, acceptMeshSession, createMeshSession };
+export { HANDSHAKE_TIMEOUT_MS, acceptDirectManageRequest, acceptMeshSession, createMeshSession, sendDirectManageRequest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wire-mesh-core",
-  "version": "1.25.0",
+  "version": "1.26.0",
   "type": "module",
   "packageManager": "pnpm@12.4.1+sha512.2e81e399d73fe8390dab25e06aa788ab7a5908248d2f5a370f82b481147a6a7a367bf8048f9a6fdb6460f21a66f0542dedb8b94ca2c8723596741920b1656d4c",
   "repository": {