iobroker.javascript 10.1.0 → 10.1.2

package/build/lib/secrets.js

@@ -0,0 +1,220 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecretsManager = exports.SECRETS_PREFIX = void 0;
+exports.isSecretId = isSecretId;
+exports.getSecretName = getSecretName;
+/**
+ * Access to the central ioBroker credential store (`system.credentials.*`) from scripts.
+ *
+ * The admin UI manages the credentials under "Basic settings" → "Credentials". Every credential
+ * has an ID like `system.credentials.CameraPassword` and holds either a single `key` (API keys)
+ * or a `login`/`password` pair. The secret fields are stored encrypted with the system secret.
+ *
+ * This manager keeps all credentials decrypted in memory and exposes them to the scripts as the
+ * global `SECRETS` object, so a script can simply write:
+ *
+ * ```js
+ * const password = SECRETS.CameraPassword.key;
+ * ```
+ *
+ * The cache is kept up to date while the adapter is running, so editing a credential in the admin
+ * UI takes effect immediately - without restarting the adapter or the scripts.
+ */
+// Imported from its own entry point on purpose: the package index of `@iobroker/adapter-core`
+// looks for js-controller while it is being loaded and terminates the process with exit code 10
+// when it is missing. This module is required by the unit tests, which run without a controller,
+// so it must stay clear of that side effect. `@iobroker/adapter-core/credentials` is free of it -
+// it is written to be usable in browser builds as well.
+const Credentials = __importStar(require("@iobroker/adapter-core/credentials"));
+/** Prefix of all credential object IDs */
+exports.SECRETS_PREFIX = 'system.credentials.';
+/**
+ * Checks if the given object ID belongs to the central credential store.
+ *
+ * @param id Object ID, e.g. `system.credentials.CameraPassword`
+ */
+function isSecretId(id) {
+    return id.startsWith(exports.SECRETS_PREFIX) && id.length > exports.SECRETS_PREFIX.length;
+}
+/**
+ * Extracts the name a credential is exposed under in `SECRETS`.
+ *
+ * @param id Object ID, e.g. `system.credentials.CameraPassword`
+ */
+function getSecretName(id) {
+    return id.substring(exports.SECRETS_PREFIX.length);
+}
+class SecretsManager {
+    adapter;
+    /** Decrypted credentials, keyed by name (the credential ID without the `system.credentials.` prefix) */
+    cache = new Map();
+    /** If the scripts may read the credentials at all (adapter option `enableSecrets`) */
+    enabled = false;
+    /** Warn only once per script run that the feature is disabled */
+    disabledWarningShown = false;
+    /**
+     * The object handed to the scripts as the global `SECRETS`.
+     *
+     * It is a read-only view on the cache, so the values stay up to date without the scripts
+     * having to re-read anything, and a script cannot modify the credentials of another script.
+     */
+    secrets;
+    constructor(adapter) {
+        this.adapter = adapter;
+        this.secrets = new Proxy(Object.create(null), {
+            get: (_target, prop) => typeof prop === 'string' ? this.get(prop) : undefined,
+            has: (_target, prop) => typeof prop === 'string' && this.cache.has(prop),
+            ownKeys: () => (this.enabled ? Array.from(this.cache.keys()) : []),
+            getOwnPropertyDescriptor: (_target, prop) => {
+                const value = typeof prop === 'string' ? this.get(prop) : undefined;
+                return value === undefined
+                    ? undefined
+                    : { value, enumerable: true, configurable: true, writable: false };
+            },
+            // The credentials belong to the system - scripts may read them, but never change them
+            set: () => false,
+            defineProperty: () => false,
+            deleteProperty: () => false,
+        });
+    }
+    /** Reads one credential from the cache and warns if the whole feature is switched off */
+    get(name) {
+        if (!this.enabled) {
+            if (!this.disabledWarningShown) {
+                this.disabledWarningShown = true;
+                this.adapter.log.warn(`A script tried to read the secret "${name}", but the access to the credentials is disabled. Enable "Allow scripts to read the credentials" in the instance settings.`);
+            }
+            return undefined;
+        }
+        return this.cache.get(name);
+    }
+    /**
+     * Reads all credentials of the central store and decrypts them.
+     *
+     * @param enabled Value of the adapter option `enableSecrets`
+     */
+    async load(enabled) {
+        this.cache.clear();
+        this.disabledWarningShown = false;
+        this.enabled = enabled;
+        if (!enabled) {
+            return;
+        }
+        if (!Credentials?.listCredentials) {
+            this.adapter.log.warn('Cannot read the credentials for "SECRETS": the credentials API is only available with js-controller 7.2 or newer');
+            this.enabled = false;
+            return;
+        }
+        try {
+            const list = await Credentials.listCredentials(this.adapter);
+            for (const entry of list) {
+                await this.update(entry.id);
+            }
+            this.adapter.log.debug(`${this.cache.size} secret(s) available in the scripts as "SECRETS"`);
+        }
+        catch (e) {
+            this.adapter.log.warn(`Cannot read the credentials: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    /**
+     * Reads one credential and decrypts it. Called for every change of a `system.credentials.*`
+     * object, so edits in the admin UI are visible in the scripts immediately.
+     *
+     * @param id Object ID, e.g. `system.credentials.CameraPassword`
+     */
+    async update(id) {
+        if (!this.enabled || !isSecretId(id)) {
+            return;
+        }
+        const name = getSecretName(id);
+        try {
+            const credentials = await Credentials.getCredentials(this.adapter, id);
+            this.cache.set(name, Object.freeze({ ...credentials.values }));
+        }
+        catch (e) {
+            this.cache.delete(name);
+            this.adapter.log.warn(`Cannot read the secret "${name}": ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    /**
+     * Forgets one credential because its object was deleted.
+     *
+     * @param id Object ID, e.g. `system.credentials.CameraPassword`
+     */
+    remove(id) {
+        if (isSecretId(id) && this.cache.delete(getSecretName(id))) {
+            this.adapter.log.debug(`Secret "${getSecretName(id)}" was deleted`);
+        }
+    }
+    /**
+     * The structure of the credential store without any secret value: which credentials exist and
+     * which fields each of them has. Used by the instance settings and the Blockly editor to show
+     * the user what `SECRETS.<name>.<field>` expressions are available.
+     */
+    getStructure() {
+        return Array.from(this.cache.entries())
+            .map(([name, values]) => ({ name, fields: Object.keys(values).sort() }))
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    /**
+     * Builds the ambient TypeScript declarations for the credentials that currently exist, so the
+     * editor can suggest their names after typing `SECRETS.` and their fields after the next dot.
+     * The names are merged into the `iobJS.Secrets` interface, which has an index signature for
+     * all other names.
+     */
+    getDeclarations() {
+        const lines = [
+            '// Generated by ioBroker.javascript from the central credential store - do not edit',
+            'declare namespace iobJS {',
+            '    interface Secrets {',
+        ];
+        for (const { name, fields } of this.getStructure()) {
+            const values = this.cache.get(name);
+            // Declare the fields this credential really has, so the editor suggests exactly those
+            const members = fields.map(field => `${JSON.stringify(field)}: ${typeof values[field]}`).join('; ');
+            lines.push(`        ${JSON.stringify(name)}: { ${members} };`);
+        }
+        lines.push('    }', '}', '');
+        return lines.join('\n');
+    }
+    /** Forgets all decrypted credentials */
+    destroy() {
+        this.cache.clear();
+        this.enabled = false;
+    }
+}
+exports.SecretsManager = SecretsManager;
+//# sourceMappingURL=secrets.js.map

package/build/lib/secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../../src/lib/secrets.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Access to the central ioBroker credential store (`system.credentials.*`) from scripts.\n *\n * The admin UI manages the credentials under \"Basic settings\" → \"Credentials\". Every credential\n * has an ID like `system.credentials.CameraPassword` and holds either a single `key` (API keys)\n * or a `login`/`password` pair. The secret fields are stored encrypted with the system secret.\n *\n * This manager keeps all credentials decrypted in memory and exposes them to the scripts as the\n * global `SECRETS` object, so a script can simply write:\n *\n * ```js\n * const password = SECRETS.CameraPassword.key;\n * ```\n *\n * The cache is kept up to date while the adapter is running, so editing a credential in the admin\n * UI takes effect immediately - without restarting the adapter or the scripts.\n */\n// Imported from its own entry point on purpose: the package index of `@iobroker/adapter-core`\n// looks for js-controller while it is being loaded and terminates the process with exit code 10\n// when it is missing. This module is required by the unit tests, which run without a controller,\n// so it must stay clear of that side effect. `@iobroker/adapter-core/credentials` is free of it -\n// it is written to be usable in browser builds as well.\nimport * as Credentials from '@iobroker/adapter-core/credentials';\n\n/** Prefix of all credential object IDs */\nexport const SECRETS_PREFIX = 'system.credentials.';\n\n/** Decrypted fields of one credential, e.g. `{ key: 'abc' }` or `{ login: 'user', password: 'pass' }` */\nexport type SecretValues = Record<string, string | number | boolean>;\n\n/** The global `SECRETS` object: credential name (ID without the prefix) => decrypted fields */\nexport type Secrets = Record<string, SecretValues>;\n\n/** One credential without its values: only the name and the names of its fields */\nexport interface SecretStructure {\n    /** Credential name, i.e. the object ID without the `system.credentials.` prefix */\n    name: string;\n    /** Names of the fields this credential has, e.g. `['key']` or `['login', 'password']` */\n    fields: string[];\n}\n\n/**\n * Checks if the given object ID belongs to the central credential store.\n *\n * @param id Object ID, e.g. `system.credentials.CameraPassword`\n */\nexport function isSecretId(id: string): boolean {\n    return id.startsWith(SECRETS_PREFIX) && id.length > SECRETS_PREFIX.length;\n}\n\n/**\n * Extracts the name a credential is exposed under in `SECRETS`.\n *\n * @param id Object ID, e.g. `system.credentials.CameraPassword`\n */\nexport function getSecretName(id: string): string {\n    return id.substring(SECRETS_PREFIX.length);\n}\n\nexport class SecretsManager {\n    private readonly adapter: ioBroker.Adapter;\n\n    /** Decrypted credentials, keyed by name (the credential ID without the `system.credentials.` prefix) */\n    private readonly cache: Map<string, Readonly<SecretValues>> = new Map();\n\n    /** If the scripts may read the credentials at all (adapter option `enableSecrets`) */\n    private enabled = false;\n\n    /** Warn only once per script run that the feature is disabled */\n    private disabledWarningShown = false;\n\n    /**\n     * The object handed to the scripts as the global `SECRETS`.\n     *\n     * It is a read-only view on the cache, so the values stay up to date without the scripts\n     * having to re-read anything, and a script cannot modify the credentials of another script.\n     */\n    public readonly secrets: Secrets;\n\n    constructor(adapter: ioBroker.Adapter) {\n        this.adapter = adapter;\n\n        this.secrets = new Proxy(Object.create(null) as Secrets, {\n            get: (_target: Secrets, prop: string | symbol): SecretValues | undefined =>\n                typeof prop === 'string' ? this.get(prop) : undefined,\n            has: (_target: Secrets, prop: string | symbol): boolean => typeof prop === 'string' && this.cache.has(prop),\n            ownKeys: (): string[] => (this.enabled ? Array.from(this.cache.keys()) : []),\n            getOwnPropertyDescriptor: (_target: Secrets, prop: string | symbol): PropertyDescriptor | undefined => {\n                const value = typeof prop === 'string' ? this.get(prop) : undefined;\n                return value === undefined\n                    ? undefined\n                    : { value, enumerable: true, configurable: true, writable: false };\n            },\n            // The credentials belong to the system - scripts may read them, but never change them\n            set: (): boolean => false,\n            defineProperty: (): boolean => false,\n            deleteProperty: (): boolean => false,\n        });\n    }\n\n    /** Reads one credential from the cache and warns if the whole feature is switched off */\n    private get(name: string): SecretValues | undefined {\n        if (!this.enabled) {\n            if (!this.disabledWarningShown) {\n                this.disabledWarningShown = true;\n                this.adapter.log.warn(\n                    `A script tried to read the secret \"${name}\", but the access to the credentials is disabled. Enable \"Allow scripts to read the credentials\" in the instance settings.`,\n                );\n            }\n            return undefined;\n        }\n        return this.cache.get(name);\n    }\n\n    /**\n     * Reads all credentials of the central store and decrypts them.\n     *\n     * @param enabled Value of the adapter option `enableSecrets`\n     */\n    async load(enabled: boolean): Promise<void> {\n        this.cache.clear();\n        this.disabledWarningShown = false;\n        this.enabled = enabled;\n\n        if (!enabled) {\n            return;\n        }\n\n        if (!Credentials?.listCredentials) {\n            this.adapter.log.warn(\n                'Cannot read the credentials for \"SECRETS\": the credentials API is only available with js-controller 7.2 or newer',\n            );\n            this.enabled = false;\n            return;\n        }\n\n        try {\n            const list = await Credentials.listCredentials(this.adapter);\n            for (const entry of list) {\n                await this.update(entry.id);\n            }\n            this.adapter.log.debug(`${this.cache.size} secret(s) available in the scripts as \"SECRETS\"`);\n        } catch (e: unknown) {\n            this.adapter.log.warn(`Cannot read the credentials: ${e instanceof Error ? e.message : String(e)}`);\n        }\n    }\n\n    /**\n     * Reads one credential and decrypts it. Called for every change of a `system.credentials.*`\n     * object, so edits in the admin UI are visible in the scripts immediately.\n     *\n     * @param id Object ID, e.g. `system.credentials.CameraPassword`\n     */\n    async update(id: string): Promise<void> {\n        if (!this.enabled || !isSecretId(id)) {\n            return;\n        }\n        const name = getSecretName(id);\n\n        try {\n            const credentials = await Credentials.getCredentials(this.adapter, id);\n            this.cache.set(name, Object.freeze({ ...credentials.values }));\n        } catch (e: unknown) {\n            this.cache.delete(name);\n            this.adapter.log.warn(`Cannot read the secret \"${name}\": ${e instanceof Error ? e.message : String(e)}`);\n        }\n    }\n\n    /**\n     * Forgets one credential because its object was deleted.\n     *\n     * @param id Object ID, e.g. `system.credentials.CameraPassword`\n     */\n    remove(id: string): void {\n        if (isSecretId(id) && this.cache.delete(getSecretName(id))) {\n            this.adapter.log.debug(`Secret \"${getSecretName(id)}\" was deleted`);\n        }\n    }\n\n    /**\n     * The structure of the credential store without any secret value: which credentials exist and\n     * which fields each of them has. Used by the instance settings and the Blockly editor to show\n     * the user what `SECRETS.<name>.<field>` expressions are available.\n     */\n    getStructure(): SecretStructure[] {\n        return Array.from(this.cache.entries())\n            .map(([name, values]) => ({ name, fields: Object.keys(values).sort() }))\n            .sort((a, b) => a.name.localeCompare(b.name));\n    }\n\n    /**\n     * Builds the ambient TypeScript declarations for the credentials that currently exist, so the\n     * editor can suggest their names after typing `SECRETS.` and their fields after the next dot.\n     * The names are merged into the `iobJS.Secrets` interface, which has an index signature for\n     * all other names.\n     */\n    getDeclarations(): string {\n        const lines = [\n            '// Generated by ioBroker.javascript from the central credential store - do not edit',\n            'declare namespace iobJS {',\n            '    interface Secrets {',\n        ];\n        for (const { name, fields } of this.getStructure()) {\n            const values = this.cache.get(name)!;\n            // Declare the fields this credential really has, so the editor suggests exactly those\n            const members = fields.map(field => `${JSON.stringify(field)}: ${typeof values[field]}`).join('; ');\n            lines.push(`        ${JSON.stringify(name)}: { ${members} };`);\n        }\n        lines.push('    }', '}', '');\n        return lines.join('\\n');\n    }\n\n    /** Forgets all decrypted credentials */\n    destroy(): void {\n        this.cache.clear();\n        this.enabled = false;\n    }\n}\n"]}

package/build/main.js

@@ -78,6 +78,7 @@ const protectFs_1 = __importDefault(require("./lib/protectFs"));
 const words_1 = require("./lib/words");
 const sandbox_1 = require("./lib/sandbox");
 const nodeModulesManagement_1 = require("./lib/nodeModulesManagement");
+const secrets_1 = require("./lib/secrets");
 const aiProviderResolver_1 = require("./lib/aiProviderResolver");
 const anthropicAdapter_1 = require("./lib/anthropicAdapter");
 const eventObj_1 = require("./lib/eventObj");
@@ -328,6 +329,11 @@ class JavaScript extends adapter_core_1.Adapter {
     aiCredentialCache = new Map();
     /** Unsubscribe callbacks for the AI credential subscriptions (manager mode). */
     aiCredentialUnsubscribers = [];
+    /**
+     * Decrypted credentials of the central ioBroker credential store (`system.credentials.*`),
+     * exposed to the scripts as the global `SECRETS` object. Kept up to date by `onObjectChange`.
+     */
+    secretsManager = new secrets_1.SecretsManager(this);
     globalScript = '';
     /** Generated declarations for global TypeScripts */
     globalDeclarations = '';
@@ -479,6 +485,7 @@ class JavaScript extends adapter_core_1.Adapter {
             adapter: this,
             logError: this.logError.bind(this),
             allowSelfSignedCerts: false,
+            secrets: this.secretsManager.secrets,
         };
         this.tsServer = new virtual_tsc_1.Server(typescriptSettings_1.tsCompilerOptions, this.tsLog);
     }
@@ -509,6 +516,16 @@ class JavaScript extends adapter_core_1.Adapter {
                 this._enums.delete(id);
             }
         }
+        // Keep the decrypted credentials (global `SECRETS`) in sync with the central credential store
+        if ((0, secrets_1.isSecretId)(id)) {
+            if (obj) {
+                await this.secretsManager.update(id);
+            }
+            else {
+                this.secretsManager.remove(id);
+            }
+            this.updateSecretsDeclarations();
+        }
         // IO-9: Invalidate sendTo instance-cache when adapter instances change
         if (id.startsWith('system.adapter.')) {
             const parts = id.split('.');
@@ -777,6 +794,7 @@ class JavaScript extends adapter_core_1.Adapter {
                 this.setStateCountCheckInterval = null;
             }
             await this.unsubscribeAiCredentials();
+            this.secretsManager.destroy();
             await this.stopAllScripts();
         }
         catch (err) {
@@ -1401,6 +1419,18 @@ class JavaScript extends adapter_core_1.Adapter {
                 }
                 break;
             }
+            case 'getSecrets': {
+                // Reports which credentials exist and which fields they have, so the instance
+                // settings and the Blockly editor can show the available `SECRETS.<name>.<field>`
+                // expressions. The decrypted values never leave the backend.
+                if (obj.callback) {
+                    this.sendTo(obj.from, obj.command, {
+                        enabled: this.config.enableSecrets !== false,
+                        secrets: this.secretsManager.getStructure(),
+                    }, obj.callback);
+                }
+                break;
+            }
             case 'prettier': {
                 // Format the code with Prettier
                 if (obj.message && typeof obj.message.code === 'string') {
@@ -1588,6 +1618,10 @@ class JavaScript extends adapter_core_1.Adapter {
         // In `manager` credential mode, subscribe to the configured AI credentials so changes in the
         // central credential store are picked up live (the keys are cached for the AI sendTo handlers).
         await this.subscribeAiCredentials();
+        // Read the central credential store, so the scripts can use `SECRETS.<name>.<field>`.
+        // Later changes are picked up in `onObjectChange`.
+        await this.secretsManager.load(this.config.enableSecrets !== false);
+        this.updateSecretsDeclarations();
         const doc = await this.getObjectViewAsync('script', 'javascript', {});
         if (doc?.rows?.length) {
             // sort global scripts if configured
@@ -1759,6 +1793,23 @@ class JavaScript extends adapter_core_1.Adapter {
             }
         }, 60_000).unref();
     }
+    /**
+     * Publishes the names of the existing credentials as ambient declarations, so the editor can
+     * suggest them after typing `SECRETS.` and the TypeScript compiler knows them.
+     */
+    updateSecretsDeclarations() {
+        if (!tsAmbient) {
+            return;
+        }
+        const declarationPath = 'secrets.d.ts';
+        const declarations = this.secretsManager.getDeclarations();
+        if (tsAmbient[declarationPath] === declarations) {
+            return;
+        }
+        tsAmbient[declarationPath] = declarations;
+        this.tsServer.provideAmbientDeclarations({ [declarationPath]: declarations });
+        jsDeclarationServer.provideAmbientDeclarations({ [declarationPath]: declarations });
+    }
     loadTypeScriptDeclarations() {
         // try to load the typings on disk for all 3rd party modules
         const packages = [