@iobroker/socket-classes 2.6.2 → 2.7.1

package/README.md

@@ -1043,6 +1043,13 @@ Unsubscribe from file changes in ioBroker DB
 	Placeholder for the next version (at the beginning of the line):
 	### **WORK IN PROGRESS**
 -->
+### 2.7.1 (2026-10-07)
+- (@GermanBluefox) Added: an event only reaches a connection whose user may read what it is about. A subscription says which ids a client is interested in, never which ids it may see - `subscribe` asks whether the user may read states *at all*, so whoever subscribed to `*` was told about every state of the system, the ACL of the single objects notwithstanding, and the same went for objects and for files. The fan-out asks that question now, for state, object and file events alike. Members of the administrator group are not restricted, as everywhere else, and with authentication switched off every connection is the configured default user - so for most installations nothing changes at all. **Where restricted users exist, they will see less than before: that is the point, but it is the kind of change that comes back as "my user stopped getting updates".** The database decides, not this package: `mayRead` of js-controller 8.0 and newer is asked where it exists, which knows the ACL of a state rather than that of its object and the mode of a single file rather than that of the adapter; an older controller is asked for the object instead, which is coarser but refuses in the same direction. One question per user and thing, remembered until the object - or the rights themselves - change, and the objects are watched from the first decision on, so an installation whose connections are all administrators never asks anything
+- (@GermanBluefox) Changed: `publish` and `publishFile` answer `true` where the event is on its way to the client, which now includes the moment it waits for the decision described above; `false` means the client is not subscribed to it, or may not see it. Only the first event of a thing ever waits, and only the newest one of it, so nothing can overtake it
+
+### 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 js-controller 7.2.5 and newer pass on to the message as `obj.user`; an older one ignores it, so nothing breaks, and a receiving adapter treats 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 js-controller 7.2.5 and newer 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;
@@ -61,8 +74,51 @@ export declare class SocketCommands {
      */
     static _fixCallback(callback: SocketCallback | null | undefined, error: string | Error | null | undefined, ...args: any[]): void;
     _checkPermissions(socket: WebSocketClient, command: PermissionCommands, callback: ((error: string | null, ...args: any[]) => void) | undefined, ...args: any[]): boolean;
+    /**
+     * Give one event to one connection, if it is subscribed to it and may see it.
+     *
+     * Returns whether the event is on its way to this client: `true` where it was sent, and also
+     * where it is waiting for the database to decide whether this user may read the object - the
+     * answer to that is not worth holding up every other connection for. `false` means the client is
+     * not subscribed to it, or may not see it.
+     *
+     * @param socket the connection
+     * @param type what kind of event it is
+     * @param id the object it is about
+     * @param obj the state or object as it is sent to the client
+     */
     publish(socket: WebSocketClient, type: SocketSubscribeTypes, id: string, obj: ioBroker.Object | ioBroker.State | null | undefined): boolean;
+    /**
+     * Give one file event to one connection, if it is subscribed to it and may see it.
+     *
+     * The decision is taken per file and user. Where the controller has `mayRead`, it answers for the
+     * single file, with its own owner and mode as `chownFile` and `chmodFile` set them. An older
+     * controller cannot be asked about a file, so the meta object the files belong to - `vis.0` for
+     * every file of vis - stands in for it: still one question per file, but every one of them about
+     * the adapter. That also works where the file the event is about has just been deleted.
+     *
+     * The answer means the same as in {@link publish}: `true` where the event is on its way.
+     *
+     * @param socket the connection
+     * @param id the adapter the file belongs to, e.g. `vis.0`
+     * @param fileName the path of the file inside it
+     * @param size how big it is now, or null where it is gone
+     */
     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: js-controller
+     * 7.2.5 and newer put it into the message as `obj.user`, older ones ignore the option, so nothing
+     * breaks. A receiver treats the field as optional - where nobody was named there is nothing to
+     * check against, which is how every message looked before.
+     *
+     * @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 +146,4 @@ export declare class SocketCommands {
     disableEventThreshold(): void;
     destroy(): void;
 }
+export {};