@iobroker/socket-classes 2.6.2 → 2.7.0

package/README.md

@@ -1043,6 +1043,9 @@ Unsubscribe from file changes in ioBroker DB
 	Placeholder for the next version (at the beginning of the line):
 	### **WORK IN PROGRESS**
 -->
+### 2.7.0 (2026-10-05)
+- (@GermanBluefox) Added: every command that sends a message now names the user of the connection - `sendTo`, `sendToHost`, `cmdExec`, `clientSubscribe`, `clientUnsubscribe` and the "nobody subscribed" notice. Objects, states and files have always been read and written with `{ user }` so the database applies the ACLs of the logged-in user; a message had no such channel, so the receiving instance saw `from` and nothing else and had to act with its own rights - a GUI user who may use `sendTo` could have an adapter do things their own ACL forbids. It travels as a send option, which a js-controller that reports `ADAPTER_MESSAGE_USER_CONTEXT` passes on to the message as `obj.user`; an older one ignores it, so nothing breaks, and a receiving adapter has to treat the field as optional
+
 ### 2.6.2 (2026-10-02)
 - (@GermanBluefox) Fixed: a websocket whose access token was not accepted stayed open without a single command handler. The client was asked to re-authenticate, fetched a new token within milliseconds and announced it with `updateTokenExpiration` - the one command that is exempt from the session check exactly for this - but nobody was listening. The client waited for an answer that could not come until its own three second timeout closed the connection, burnt its single-use refresh token for nothing and had to start over, which is why the GUI took seconds to come up with authentication enabled and sometimes did not come up at all. The handlers are installed now, with an empty ACL: every command that needs a permission is still refused, only the announcement of a token gets through
 - (@GermanBluefox) Fixed: an announced access token now finishes the authentication of such a socket instead of only moving its expiration date. The connection carries on with the user of the token, so no reconnect and no second refresh is needed

package/build/lib/socketCommands.d.ts

@@ -1,5 +1,18 @@
 import type { Socket as WebSocketClient } from '@iobroker/ws-server';
 import { type PermissionCommands, type SocketSubscribeTypes, type SocketOperation, type SocketCallback } from '../types';
+/**
+ * The options of an outbound message, as far as this package needs them.
+ *
+ * `timeout` has always been there. `user` is read by the controllers that report
+ * `ADAPTER_MESSAGE_USER_CONTEXT` and silently ignored by older ones, and it is not in the older
+ * `@iobroker/types` this package builds against - hence the own declaration.
+ */
+interface MessageSendOptions {
+    /** Reject/err-callback if no answer arrives in time (single targets only) */
+    timeout?: number;
+    /** The user the message is sent on behalf of */
+    user?: `system.user.${string}`;
+}
 export declare const COMMANDS_PERMISSIONS: Record<PermissionCommands, {
     type: 'object' | 'state' | 'users' | 'other' | 'file' | '';
     operation: SocketOperation;
@@ -63,6 +76,19 @@ export declare class SocketCommands {
     _checkPermissions(socket: WebSocketClient, command: PermissionCommands, callback: ((error: string | null, ...args: any[]) => void) | undefined, ...args: any[]): boolean;
     publish(socket: WebSocketClient, type: SocketSubscribeTypes, id: string, obj: ioBroker.Object | ioBroker.State | null | undefined): boolean;
     publishFile(socket: WebSocketClient, id: string, fileName: string, size: number | null): boolean;
+    /**
+     * The send options for a message triggered by this socket: the user it is sent on behalf of.
+     *
+     * Objects, states and files have always been read and written with `{ user }` so the database
+     * applies the ACLs of the logged-in user. A message had no such channel: the receiving instance saw
+     * `from` and nothing else, so every adapter reachable over `sendTo` had to act with its own rights,
+     * and could not tell one caller from another. The user travels with the message now, for the
+     * controller versions that support it - older ones ignore the option, so nothing breaks, but a
+     * receiver must treat `obj.user` as optional (`adapter.supportsFeature('ADAPTER_MESSAGE_USER_CONTEXT')`).
+     *
+     * @param socket the socket the command came in on
+     */
+    protected static sendOptionsOf(socket: WebSocketClient): MessageSendOptions | undefined;
     publishInstanceMessage(socket: WebSocketClient, sourceInstance: string, messageType: string, data: any): boolean;
     _showSubscribes(socket: WebSocketClient, type: SocketSubscribeTypes): void;
     isLogEnabled(): boolean;
@@ -90,3 +116,4 @@ export declare class SocketCommands {
     disableEventThreshold(): void;
     destroy(): void;
 }
+export {};