@flowscripter/dynamic-cli-framework 12.0.1 → 12.2.0

package/dist/src/service/configuration/DefaultConfigurationService.d.ts

@@ -0,0 +1,78 @@
+import { type CommandRegistry, type ConfigurationService, type SingleValueType, type ValueNode, type Values } from "@flowscripter/dynamic-cli-framework-api";
+import { type ConfigTarget } from "./configTargets.ts";
+import type DefaultSecretService from "./DefaultSecretService.ts";
+import type ConfigFormat from "./format/ConfigFormat.ts";
+export type KeyValueServiceScopeType = "command" | "service";
+/**
+ * Owns the configuration data read from (and written back to) the configuration file: the default
+ * command argument values and the raw per-scope key-value data.
+ *
+ * The `config` group commands are constructed with this instance. It must never be registered in the
+ * {@link Context}: it exposes every command's defaults, the raw key-value data of every scope and secret
+ * resolution. Only a location-only view is registered under {@link CONFIGURATION_SERVICE_ID}.
+ */
+export default class DefaultConfigurationService implements ConfigurationService {
+    #private;
+    readonly envVarsEnabled: boolean;
+    readonly configFormat: ConfigFormat;
+    configLocation: string | undefined;
+    defaultsData: Map<string, Values | SingleValueType>;
+    /**
+     * @param envVarsEnabled whether environment variables may override stored default values.
+     * @param configFormat the syntax of the configuration file.
+     * @param commandRegistry optional registry of all commands, required for {@link getConfigTargets}.
+     */
+    constructor(envVarsEnabled: boolean, configFormat: ConfigFormat, commandRegistry?: CommandRegistry);
+    setConfigLocation(location: string): void;
+    setDefaultsSecretService(secretService: DefaultSecretService): void;
+    /**
+     * Resolve any secret sentinels within the value using the OS secret store (if enabled).
+     *
+     * @param commandKey the key of the command under `defaults` the value belongs to: a sentinel
+     * may only refer to a secret stored for this command.
+     */
+    resolveDefaultSecrets<T>(value: T, commandKey: string): Promise<T>;
+    /**
+     * Get-or-create the underlying, raw {@link ValueNode} `Map` for the given scope.
+     *
+     * @param scopeType whether `scopeKey` is a command name or a service/task ID.
+     * @param scopeKey the command name or service/task ID to scope the key-value data to.
+     */
+    getKeyValueData(scopeType: KeyValueServiceScopeType, scopeKey: string): Map<string, ValueNode>;
+    /**
+     * Write the configuration file, if `isDirty` is true.
+     *
+     * @param isDirty whether any scoped KeyValueService has unwritten changes.
+     */
+    flushIfDirty(isDirty: boolean): Promise<void>;
+    /**
+     * Determine the configuration location (defaulting to `$HOME/.<application_name>.<format extension>`)
+     * and read the configuration from it if it exists.
+     *
+     * @param applicationName the name of the CLI.
+     */
+    init(applicationName: string): Promise<void>;
+    getConfigString(): string;
+    /**
+     * The configuration text with secret sentinels and the values of SECRET typed arguments of
+     * known commands masked.
+     */
+    getMaskedConfigString(): string;
+    /**
+     * The commands whose defaults can be managed via the `config` group commands.
+     */
+    getConfigTargets(): Map<string, ConfigTarget>;
+    /**
+     * Replace (or remove, if `build` returns `undefined`) the stored defaults of a command and write the
+     * configuration file immediately. Memory, file and secret store are left unchanged if anything fails.
+     *
+     * @param commandKey the key of the command under `defaults`.
+     * @param secrets plain text secrets to store in the OS secret store, keyed to be used for naming.
+     * @param build creates the new value given the sentinels (one per secret) to reference the stored secrets.
+     */
+    commitDefault(commandKey: string, secrets: ReadonlyArray<{
+        key: ReadonlyArray<string>;
+        value: string;
+    }>, build: (sentinels: ReadonlyArray<string>) => Values | SingleValueType | undefined): Promise<void>;
+}
+//# sourceMappingURL=DefaultConfigurationService.d.ts.map

package/dist/src/service/configuration/DefaultConfigurationService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DefaultConfigurationService.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/DefaultConfigurationService.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,KAAK,MAAM,EACZ,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,oBAAoB,MAAM,2BAA2B,CAAC;AAClE,OAAO,KAAK,YAAY,MAAM,0BAA0B,CAAC;AAMzD,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG,SAAS,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,CAAC,OAAO,OAAO,2BAA4B,YAAW,oBAAoB;;IAC9E,SAAgB,cAAc,EAAE,OAAO,CAAC;IACxC,SAAgB,YAAY,EAAE,YAAY,CAAC;IAGpC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAInC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAAC,CAAa;IAcvE;;;;OAIG;IACH,YACE,cAAc,EAAE,OAAO,EACvB,YAAY,EAAE,YAAY,EAC1B,eAAe,CAAC,EAAE,eAAe,EAKlC;IAEM,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE/C;IAEM,wBAAwB,CAAC,aAAa,EAAE,oBAAoB,GAAG,IAAI,CAEzE;IAED;;;;;OAKG;IACU,qBAAqB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAmB9E;IAED;;;;;OAKG;IACI,eAAe,CACpB,SAAS,EAAE,wBAAwB,EACnC,QAAQ,EAAE,MAAM,GACf,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAOxB;IAED;;;;OAIG;IACU,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAQzD;IAED;;;;;OAKG;IACU,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCxD;IAiEM,eAAe,IAAI,MAAM,CAE/B;IAED;;;OAGG;IACI,qBAAqB,IAAI,MAAM,CAarC;IAED;;OAEG;IACI,gBAAgB,IAAI,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAInD;IAED;;;;;;;OAOG;IACU,aAAa,CACxB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,aAAa,CAAC;QAAE,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,EACrE,KAAK,EAAE,CAAC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,KAAK,MAAM,GAAG,eAAe,GAAG,SAAS,GAChF,OAAO,CAAC,IAAI,CAAC,CA6Cf;CAmCF"}

package/dist/src/service/configuration/DefaultConfigurationService.js

@@ -0,0 +1,296 @@
+import process from "node:process";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { SECRET_SENTINEL_PREFIX, } from "@flowscripter/dynamic-cli-framework-api";
+import getLogger from "../../util/logger.js";
+import { collectSentinels, getConfigTargets, maskDefault, } from "./configTargets.js";
+import resolveSecrets from "./resolveSecrets.js";
+const logger = getLogger("DefaultConfigurationService");
+/**
+ * Owns the configuration data read from (and written back to) the configuration file: the default
+ * command argument values and the raw per-scope key-value data.
+ *
+ * The `config` group commands are constructed with this instance. It must never be registered in the
+ * {@link Context}: it exposes every command's defaults, the raw key-value data of every scope and secret
+ * resolution. Only a location-only view is registered under {@link CONFIGURATION_SERVICE_ID}.
+ */
+export default class DefaultConfigurationService {
+    envVarsEnabled;
+    configFormat;
+    // the location of the currently managed configuration data
+    configLocation;
+    // the configuration data used when setting command defaults. SingleValueType is for
+    // GlobalCommandArgument values, Values is for SubCommandArgument values.
+    defaultsData = new Map();
+    // the format specific handle for the text last read or written, used to preserve comments and layout on write
+    #configHandle;
+    #commandKeyValueData = new Map();
+    #serviceKeyValueData = new Map();
+    // used only to resolve secret sentinels embedded in default command argument values and to store
+    // SECRET values set via the `config` group commands
+    #defaultsSecretService;
+    #commandRegistry;
+    /**
+     * @param envVarsEnabled whether environment variables may override stored default values.
+     * @param configFormat the syntax of the configuration file.
+     * @param commandRegistry optional registry of all commands, required for {@link getConfigTargets}.
+     */
+    constructor(envVarsEnabled, configFormat, commandRegistry) {
+        this.envVarsEnabled = envVarsEnabled;
+        this.configFormat = configFormat;
+        this.#commandRegistry = commandRegistry;
+    }
+    setConfigLocation(location) {
+        this.configLocation = location;
+    }
+    setDefaultsSecretService(secretService) {
+        this.#defaultsSecretService = secretService;
+    }
+    /**
+     * Resolve any secret sentinels within the value using the OS secret store (if enabled).
+     *
+     * @param commandKey the key of the command under `defaults` the value belongs to: a sentinel
+     * may only refer to a secret stored for this command.
+     */
+    async resolveDefaultSecrets(value, commandKey) {
+        if (this.#defaultsSecretService === undefined) {
+            return value;
+        }
+        const secretService = this.#defaultsSecretService;
+        return await resolveSecrets(value, async (bunSecretName) => {
+            if (!secretService.ownsSecretName(bunSecretName, commandKey)) {
+                throw new Error(`Secret sentinel '${SECRET_SENTINEL_PREFIX}${bunSecretName}' does not refer to a secret stored for command: '${commandKey}'`);
+            }
+            const secretValue = await secretService.getSecret(bunSecretName);
+            if (secretValue === null) {
+                throw new Error(`Secret not found in OS secret store for sentinel: '${SECRET_SENTINEL_PREFIX}${bunSecretName}'`);
+            }
+            return secretValue;
+        });
+    }
+    /**
+     * Get-or-create the underlying, raw {@link ValueNode} `Map` for the given scope.
+     *
+     * @param scopeType whether `scopeKey` is a command name or a service/task ID.
+     * @param scopeKey the command name or service/task ID to scope the key-value data to.
+     */
+    getKeyValueData(scopeType, scopeKey) {
+        const keyValueData = scopeType === "command" ? this.#commandKeyValueData : this.#serviceKeyValueData;
+        if (!keyValueData.has(scopeKey)) {
+            keyValueData.set(scopeKey, new Map());
+        }
+        return keyValueData.get(scopeKey);
+    }
+    /**
+     * Write the configuration file, if `isDirty` is true.
+     *
+     * @param isDirty whether any scoped KeyValueService has unwritten changes.
+     */
+    async flushIfDirty(isDirty) {
+        if (!isDirty) {
+            return;
+        }
+        if (this.configLocation === undefined) {
+            throw new Error("Attempt to write updated config with no configLocation set");
+        }
+        await this.#writeConfig(this.configLocation);
+    }
+    /**
+     * Determine the configuration location (defaulting to `$HOME/.<application_name>.<format extension>`)
+     * and read the configuration from it if it exists.
+     *
+     * @param applicationName the name of the CLI.
+     */
+    async init(applicationName) {
+        let isDefault = false;
+        if (this.configLocation === undefined) {
+            isDefault = true;
+            const home = process.env["HOME"];
+            if (home) {
+                this.configLocation = path.join(home, `.${applicationName.replace(/\W/g, "")}.${this.configFormat.fileExtension}`);
+            }
+        }
+        if (this.configLocation === undefined) {
+            return;
+        }
+        let fileInfo;
+        try {
+            fileInfo = await fs.lstat(this.configLocation);
+        }
+        catch (err) {
+            const error = err;
+            if (isDefault) {
+                logger.debug("Default config file location: %s does not exist or is not visible - ignoring: %s", this.configLocation, error.message);
+                return;
+            }
+            else {
+                throw new Error(`Config file location: '${this.configLocation}' doesn't exist or not visible: ${error.message}`);
+            }
+        }
+        if (fileInfo.isDirectory()) {
+            throw new Error(`Config file location: '${this.configLocation}' is a directory and not a file!`);
+        }
+        await this.#readConfig(this.configLocation);
+    }
+    async #readConfig(location) {
+        try {
+            logger.debug("Reading config from: %s", location);
+            const data = await fs.readFile(location);
+            const { data: config, handle } = this.configFormat.parse(data.toString());
+            this.#configHandle = handle;
+            this.defaultsData.clear();
+            this.#commandKeyValueData.clear();
+            this.#serviceKeyValueData.clear();
+            if (config.defaults !== undefined) {
+                const defaults = config.defaults;
+                Object.keys(defaults).forEach((commandName) => {
+                    this.defaultsData.set(commandName, defaults[commandName]);
+                    logger.debug("Set default argument values for command name: %s", commandName);
+                });
+            }
+            if (config["key-values"] !== undefined) {
+                const keyValues = config["key-values"];
+                if (keyValues.commands !== undefined) {
+                    const commandKeyValues = keyValues.commands;
+                    Object.keys(commandKeyValues).forEach((commandName) => {
+                        this.#commandKeyValueData.set(commandName, new Map(Object.entries(commandKeyValues[commandName])));
+                        logger.debug("Set default argument values for command name: %s", commandName);
+                    });
+                }
+                if (keyValues.services !== undefined) {
+                    const serviceKeyValues = keyValues.services;
+                    Object.keys(serviceKeyValues).forEach((serviceId) => {
+                        this.#serviceKeyValueData.set(serviceId, new Map(Object.entries(serviceKeyValues[serviceId])));
+                        logger.debug("Set default argument values for service ID: %s", serviceId);
+                    });
+                }
+            }
+        }
+        catch (err) {
+            throw new Error(`Failed to read config at location: '${this.configLocation}': ${err}`);
+        }
+    }
+    async #writeConfig(location) {
+        logger.debug("Writing config to: %s", location);
+        try {
+            const config = this.#getConfigData();
+            const text = this.#configHandle === undefined
+                ? this.configFormat.serialize(config)
+                : this.configFormat.apply(this.#configHandle, config);
+            // owner-only when the file is created; an existing file keeps its mode
+            await fs.writeFile(location, text, { mode: 0o600 });
+            this.#configHandle = this.configFormat.parse(text).handle;
+        }
+        catch (err) {
+            throw new Error(`Failed to write config at location: '${this.configLocation}': ${err}`);
+        }
+    }
+    getConfigString() {
+        return this.configFormat.serialize(this.#getConfigData());
+    }
+    /**
+     * The configuration text with secret sentinels and the values of SECRET typed arguments of
+     * known commands masked.
+     */
+    getMaskedConfigString() {
+        const data = this.#getConfigData();
+        const targets = this.getConfigTargets();
+        const masked = maskDefault(undefined, data);
+        if (data.defaults !== undefined) {
+            masked.defaults = Object.fromEntries(Object.entries(data.defaults).map(([key, value]) => [
+                key,
+                maskDefault(targets.get(key), value),
+            ]));
+        }
+        return this.configFormat.serialize(masked);
+    }
+    /**
+     * The commands whose defaults can be managed via the `config` group commands.
+     */
+    getConfigTargets() {
+        return this.#commandRegistry === undefined
+            ? new Map()
+            : getConfigTargets(this.#commandRegistry);
+    }
+    /**
+     * Replace (or remove, if `build` returns `undefined`) the stored defaults of a command and write the
+     * configuration file immediately. Memory, file and secret store are left unchanged if anything fails.
+     *
+     * @param commandKey the key of the command under `defaults`.
+     * @param secrets plain text secrets to store in the OS secret store, keyed to be used for naming.
+     * @param build creates the new value given the sentinels (one per secret) to reference the stored secrets.
+     */
+    async commitDefault(commandKey, secrets, build) {
+        if (this.configLocation === undefined) {
+            throw new Error("Unable to write config: no config location is set and $HOME is not defined");
+        }
+        if (secrets.length > 0 && this.#defaultsSecretService === undefined) {
+            throw new Error("Unable to store a SECRET value: the secret service is not enabled");
+        }
+        const secretService = this.#defaultsSecretService;
+        const previous = this.defaultsData.get(commandKey);
+        const restores = [];
+        const sentinels = [];
+        try {
+            for (const { key, value } of secrets) {
+                const name = secretService.secretName(key);
+                const old = await secretService.getSecret(name);
+                await secretService.setSecret(key, value);
+                restores.push(() => old === null ? secretService.deleteSecret(name) : secretService.setSecret(key, old));
+                sentinels.push(`${SECRET_SENTINEL_PREFIX}${name}`);
+            }
+            const next = build(sentinels);
+            if (next === undefined) {
+                this.defaultsData.delete(commandKey);
+            }
+            else {
+                this.defaultsData.set(commandKey, next);
+            }
+            await this.#writeConfig(this.configLocation);
+            const kept = new Set(collectSentinels(next));
+            for (const sentinel of collectSentinels(previous)) {
+                if (!kept.has(sentinel) && secretService !== undefined) {
+                    await secretService.deleteSecret(sentinel.slice(SECRET_SENTINEL_PREFIX.length));
+                }
+            }
+        }
+        catch (err) {
+            if (previous === undefined) {
+                this.defaultsData.delete(commandKey);
+            }
+            else {
+                this.defaultsData.set(commandKey, previous);
+            }
+            for (const restore of restores.reverse()) {
+                await restore().catch(() => undefined);
+            }
+            throw err;
+        }
+    }
+    #getConfigData() {
+        const config = {};
+        if (this.defaultsData.size > 0) {
+            config.defaults = Object.fromEntries(this.defaultsData);
+        }
+        if (this.#commandKeyValueData.size > 0 || this.#serviceKeyValueData.size > 0) {
+            config["key-values"] = {};
+            if (this.#commandKeyValueData.size > 0) {
+                config["key-values"].commands = {};
+                for (const [commandName, keyValueData] of this.#commandKeyValueData.entries()) {
+                    if (keyValueData.size > 0) {
+                        config["key-values"].commands[commandName] = Object.fromEntries(keyValueData);
+                    }
+                }
+            }
+            if (this.#serviceKeyValueData.size > 0) {
+                config["key-values"].services = {};
+                for (const [serviceId, keyValueData] of this.#serviceKeyValueData.entries()) {
+                    if (keyValueData.size > 0) {
+                        config["key-values"].services[serviceId] = Object.fromEntries(keyValueData);
+                    }
+                }
+            }
+        }
+        return config;
+    }
+}

package/dist/src/service/configuration/DefaultKeyValueService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DefaultKeyValueService.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/DefaultKeyValueService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EACf,iBAAiB,EAClB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,KAAK,oBAAoB,MAAM,2BAA2B,CAAC;AAGlE;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,sBAAuB,YAAW,eAAe;;IAMpE;;;;;OAKG;IACH,YACE,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EACpC,aAAa,CAAC,EAAE,oBAAoB,EACpC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAKrC;IAEM,OAAO,IAAI,OAAO,CAExB;IAEM,SAAS,IAAI,IAAI,CAEvB;IAEY,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAGlC;IAEY,GAAG,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAsBzE;IAEM,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAExC;IAEY,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGrE;IAsCY,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO9C;CAsBF"}
+{"version":3,"file":"DefaultKeyValueService.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/DefaultKeyValueService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EACf,iBAAiB,EAClB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,KAAK,oBAAoB,MAAM,2BAA2B,CAAC;AAGlE;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,sBAAuB,YAAW,eAAe;;IAMpE;;;;;OAKG;IACH,YACE,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EACpC,aAAa,CAAC,EAAE,oBAAoB,EACpC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAKrC;IAEM,OAAO,IAAI,OAAO,CAExB;IAEM,SAAS,IAAI,IAAI,CAEvB;IAEY,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAGlC;IAEY,GAAG,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CA2BzE;IAEM,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAExC;IAEY,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGrE;IAqCY,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO9C;CAwBF"}

package/dist/src/service/configuration/DefaultKeyValueService.js

@@ -40,6 +40,9 @@ export default class DefaultKeyValueService {
             if (!this.#secretService) {
                 throw new Error("Secret sentinel found but no secret service is available");
             }
+            if (!this.#secretService.ownsSecretName(bunSecretName)) {
+                throw new Error(`Secret sentinel for key: '${key}' refers to a secret outside of this scope`);
+            }
             const secretValue = await this.#secretService.getSecret(bunSecretName);
             if (secretValue === null) {
                 throw new Error(`Secret not found in OS secret store for key: '${key}'`);
@@ -65,8 +68,7 @@ export default class DefaultKeyValueService {
             if (!this.#secretService) {
                 throw new Error("Attempt to set a secret but no secret service is available");
             }
-            const secretName = [key, ...path].join("_");
-            const bunSecretName = await this.#secretService.setSecret(secretName, JSON.stringify(value.value));
+            const bunSecretName = await this.#secretService.setSecret([key, ...path], JSON.stringify(value.value));
             return SECRET_SENTINEL_PREFIX + bunSecretName;
         }
         if (Array.isArray(value)) {
@@ -100,7 +102,9 @@ export default class DefaultKeyValueService {
         if (typeof value === "string" && value.startsWith(SECRET_SENTINEL_PREFIX)) {
             if (this.#secretService) {
                 const bunSecretName = value.slice(SECRET_SENTINEL_PREFIX.length);
-                await this.#secretService.deleteSecret(bunSecretName);
+                if (this.#secretService.ownsSecretName(bunSecretName)) {
+                    await this.#secretService.deleteSecret(bunSecretName);
+                }
             }
             return;
         }

package/dist/src/service/configuration/DefaultSecretService.d.ts

@@ -16,8 +16,23 @@ export interface SecretsApi {
 }
 export default class DefaultSecretService implements SecretService {
     #private;
-    constructor(serviceName: string, scope: string, secretsApi?: SecretsApi);
-    setSecret(key: string, value: string): Promise<string>;
+    /**
+     * @param scope the components identifying the scope, e.g. `["command", "a"]`.
+     */
+    constructor(serviceName: string, scope: ReadonlyArray<string>, secretsApi?: SecretsApi);
+    /**
+     * The name under which a secret with the provided key is stored. The scope and key components
+     * are escaped and delimited so that distinct (scope, key) pairs never produce the same name.
+     *
+     * @param key a single key or the components of a key, e.g. a key and a path within its value.
+     */
+    secretName(key: string | ReadonlyArray<string>): string;
+    /**
+     * Whether the stored secret name was created by this scope, and, if `firstKeyComponent` is
+     * provided, with that value as the first component of its key.
+     */
+    ownsSecretName(bunSecretName: string, firstKeyComponent?: string): boolean;
+    setSecret(key: string | ReadonlyArray<string>, value: string): Promise<string>;
     getSecret(bunSecretName: string): Promise<string | null>;
     deleteSecret(bunSecretName: string): Promise<boolean>;
     hasSecret(bunSecretName: string): Promise<boolean>;

package/dist/src/service/configuration/DefaultSecretService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DefaultSecretService.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/DefaultSecretService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAM7E,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxE,GAAG,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,MAAM,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtE;AAED,MAAM,CAAC,OAAO,OAAO,oBAAqB,YAAW,aAAa;;IAKhE,YAAY,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,EAStE;IAMY,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAclE;IAEY,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKpE;IAEY,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAKjE;IAEY,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO9D;CACF"}
+{"version":3,"file":"DefaultSecretService.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/DefaultSecretService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAM7E,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxE,GAAG,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,MAAM,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtE;AAmBD,MAAM,CAAC,OAAO,OAAO,oBAAqB,YAAW,aAAa;;IAKhE;;OAEG;IACH,YAAY,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,EAAE,UAAU,EASrF;IAMD;;;;;OAKG;IACI,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAG7D;IAED;;;OAGG;IACI,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,OAAO,CAMhF;IAEY,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAc1F;IAEY,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKpE;IAEY,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAKjE;IAEY,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO9D;CACF"}

package/dist/src/service/configuration/DefaultSecretService.js

@@ -1,23 +1,62 @@
 import { secrets as bunSecrets } from "bun";
 const MAX_NAME_LENGTH = 255;
 const MAX_VALUE_BYTES = 2047;
+/**
+ * Injective escape of a name component to [A-Za-z0-9_]: alphanumerics are kept and every other
+ * character (including `_`) becomes `_<UPPERCASE HEX CODE POINT>_`.
+ */
+function escapeComponent(value) {
+    let result = "";
+    for (const char of value) {
+        result += /[a-zA-Z0-9]/.test(char)
+            ? char
+            : `_${char.codePointAt(0).toString(16).toUpperCase()}_`;
+    }
+    return result;
+}
+// `Z` is not a hex digit so `_Z` can never be mistaken for the start of an escape.
+const SEPARATOR = "_Z";
 export default class DefaultSecretService {
     #serviceName;
     #secrets;
     #scope;
+    /**
+     * @param scope the components identifying the scope, e.g. `["command", "a"]`.
+     */
     constructor(serviceName, scope, secretsApi) {
-        this.#serviceName = DefaultSecretService.#sanitize(serviceName);
+        this.#serviceName = serviceName.replace(/[^a-zA-Z0-9_]/g, "_");
         if (this.#serviceName.length > MAX_NAME_LENGTH) {
             throw new Error(`Service name exceeds ${MAX_NAME_LENGTH} characters after sanitization: '${this.#serviceName}'`);
         }
-        this.#scope = DefaultSecretService.#sanitize(scope);
+        this.#scope = scope;
         this.#secrets = secretsApi ?? bunSecrets;
     }
-    static #sanitize(value) {
-        return value.replace(/[^a-zA-Z0-9_]/g, "_");
+    #scopePrefix() {
+        return this.#scope.map((c) => escapeComponent(c) + SEPARATOR).join("");
+    }
+    /**
+     * The name under which a secret with the provided key is stored. The scope and key components
+     * are escaped and delimited so that distinct (scope, key) pairs never produce the same name.
+     *
+     * @param key a single key or the components of a key, e.g. a key and a path within its value.
+     */
+    secretName(key) {
+        const parts = typeof key === "string" ? [key] : key;
+        return this.#scopePrefix() + parts.map(escapeComponent).join(SEPARATOR);
+    }
+    /**
+     * Whether the stored secret name was created by this scope, and, if `firstKeyComponent` is
+     * provided, with that value as the first component of its key.
+     */
+    ownsSecretName(bunSecretName, firstKeyComponent) {
+        if (firstKeyComponent === undefined) {
+            return bunSecretName.startsWith(this.#scopePrefix());
+        }
+        const base = this.#scopePrefix() + escapeComponent(firstKeyComponent);
+        return bunSecretName === base || bunSecretName.startsWith(base + SEPARATOR);
     }
     async setSecret(key, value) {
-        const name = this.#scope + "_" + DefaultSecretService.#sanitize(key);
+        const name = this.secretName(key);
         if (name.length > MAX_NAME_LENGTH) {
             throw new Error(`Secret name exceeds ${MAX_NAME_LENGTH} characters: '${name}'`);
         }

package/dist/src/service/configuration/KeyValueServiceProvider.d.ts

@@ -2,6 +2,7 @@ import type { ServiceInfo, ServiceProvider } from "@flowscripter/dynamic-cli-fra
 import type { Context } from "@flowscripter/dynamic-cli-framework-api";
 import type { CLIConfig } from "@flowscripter/dynamic-cli-framework-api";
 import type { KeyValueService } from "@flowscripter/dynamic-cli-framework-api";
+import { type SecretsApi } from "./DefaultSecretService.ts";
 import type ConfigurationServiceProvider from "./ConfigurationServiceProvider.ts";
 import type { KeyValueServiceScopeType } from "./ConfigurationServiceProvider.ts";
 /**
@@ -75,8 +76,9 @@ export default class KeyValueServiceProvider implements ServiceProvider {
      * backs this provider's data - an internal wiring reference, never exposed further.
      * @param keyValueServiceEnabled optionally provide a {@link KeyValueService} implementation: `configurationServiceProvider.configEnabled` must be true in this case
      * @param secretServiceEnabled optionally enable OS-native secret storage via Bun.secrets: `configurationServiceProvider.configEnabled` must be true in this case
+     * @param secretsApi optionally override the OS secret store.
      */
-    constructor(servicePriority: number, configurationServiceProvider: ConfigurationServiceProvider, keyValueServiceEnabled?: boolean, secretServiceEnabled?: boolean);
+    constructor(servicePriority: number, configurationServiceProvider: ConfigurationServiceProvider, keyValueServiceEnabled?: boolean, secretServiceEnabled?: boolean, secretsApi?: SecretsApi);
     getServiceInfo(cliConfig: CLIConfig): Promise<ServiceInfo>;
     /**
      * Return the {@link KeyValueService} bound to the given scope, creating (and caching) it on

package/dist/src/service/configuration/KeyValueServiceProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"KeyValueServiceProvider.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/KeyValueServiceProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,yCAAyC,CAAC;AAIjD,OAAO,KAAK,4BAA4B,MAAM,mCAAmC,CAAC;AAClF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AAoClF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,MAAM,CAAC,OAAO,OAAO,uBAAwB,YAAW,eAAe;;IACrE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAwB;IAClD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAIjC,SAAgB,sBAAsB,EAAE,OAAO,CAAC;IAChD,SAAgB,oBAAoB,EAAE,OAAO,CAAC;IAW9C;;;;;;;;OAQG;IACH,YACE,eAAe,EAAE,MAAM,EACvB,4BAA4B,EAAE,4BAA4B,EAC1D,sBAAsB,UAAQ,EAC9B,oBAAoB,UAAQ,EAY7B;IAEM,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAUhE;IAED;;;;;;;;;;OAUG;IACI,wBAAwB,CAC7B,SAAS,EAAE,wBAAwB,EACnC,QAAQ,EAAE,MAAM,GACf,eAAe,CAwBjB;IAED;;;;;;;;;;;;;;OAcG;IACI,kBAAkB,CACvB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,wBAAwB,EACnC,QAAQ,EAAE,MAAM,GACf,OAAO,CAcT;IAqBY,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CASxD;CACF"}
+{"version":3,"file":"KeyValueServiceProvider.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/KeyValueServiceProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,yCAAyC,CAAC;AAGjD,OAA6B,EAAE,KAAK,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAClF,OAAO,KAAK,4BAA4B,MAAM,mCAAmC,CAAC;AAClF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AAoClF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,MAAM,CAAC,OAAO,OAAO,uBAAwB,YAAW,eAAe;;IACrE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAwB;IAClD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAIjC,SAAgB,sBAAsB,EAAE,OAAO,CAAC;IAChD,SAAgB,oBAAoB,EAAE,OAAO,CAAC;IAa9C;;;;;;;;;OASG;IACH,YACE,eAAe,EAAE,MAAM,EACvB,4BAA4B,EAAE,4BAA4B,EAC1D,sBAAsB,UAAQ,EAC9B,oBAAoB,UAAQ,EAC5B,UAAU,CAAC,EAAE,UAAU,EAaxB;IAEM,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAUhE;IAED;;;;;;;;;;OAUG;IACI,wBAAwB,CAC7B,SAAS,EAAE,wBAAwB,EACnC,QAAQ,EAAE,MAAM,GACf,eAAe,CAwBjB;IAED;;;;;;;;;;;;;;OAcG;IACI,kBAAkB,CACvB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,wBAAwB,EACnC,QAAQ,EAAE,MAAM,GACf,OAAO,CAcT;IAqBY,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CASxD;CACF"}

package/dist/src/service/configuration/KeyValueServiceProvider.js

@@ -1,6 +1,6 @@
 import { KEY_VALUE_SERVICE_ID, SHUTDOWN_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
 import DefaultKeyValueService from "./DefaultKeyValueService.js";
-import DefaultSecretService from "./DefaultSecretService.js";
+import DefaultSecretService, {} from "./DefaultSecretService.js";
 import { KEY_VALUE_FLUSH_SHUTDOWN_TASK_PRIORITY } from "../../runtime/lifecycle/priorities.js";
 /**
  * Registered under {@link KEY_VALUE_SERVICE_ID} in the plain, undecorated {@link Context} purely
@@ -95,6 +95,7 @@ export default class KeyValueServiceProvider {
     // re-pointed. See getScopedKeyValueService().
     #commandScopedKeyValueServices = new Map();
     #serviceScopedKeyValueServices = new Map();
+    #secretsApi;
     // used to construct scoped DefaultSecretService instances on demand.
     #cliConfigName;
     /**
@@ -105,8 +106,9 @@ export default class KeyValueServiceProvider {
      * backs this provider's data - an internal wiring reference, never exposed further.
      * @param keyValueServiceEnabled optionally provide a {@link KeyValueService} implementation: `configurationServiceProvider.configEnabled` must be true in this case
      * @param secretServiceEnabled optionally enable OS-native secret storage via Bun.secrets: `configurationServiceProvider.configEnabled` must be true in this case
+     * @param secretsApi optionally override the OS secret store.
      */
-    constructor(servicePriority, configurationServiceProvider, keyValueServiceEnabled = false, secretServiceEnabled = false) {
+    constructor(servicePriority, configurationServiceProvider, keyValueServiceEnabled = false, secretServiceEnabled = false, secretsApi) {
         if (!configurationServiceProvider.configEnabled && keyValueServiceEnabled) {
             throw new Error("configEnabled must be true if keyValueServiceEnabled is true");
         }
@@ -116,6 +118,7 @@ export default class KeyValueServiceProvider {
         this.servicePriority = servicePriority;
         this.#configurationServiceProvider = configurationServiceProvider;
         this.keyValueServiceEnabled = keyValueServiceEnabled;
+        this.#secretsApi = secretsApi;
         this.secretServiceEnabled = secretServiceEnabled;
     }
     getServiceInfo(cliConfig) {
@@ -152,7 +155,7 @@ export default class KeyValueServiceProvider {
         }
         const keyValueData = this.#configurationServiceProvider.getKeyValueData(scopeType, scopeKey);
         const secretService = this.secretServiceEnabled
-            ? new DefaultSecretService(this.#cliConfigName, `${scopeType}_${scopeKey}`)
+            ? new DefaultSecretService(this.#cliConfigName, [scopeType, scopeKey], this.#secretsApi)
             : undefined;
         const scopedService = new DefaultKeyValueService(keyValueData, secretService, () => this.#flushDirtyScopes());
         scopedServices.set(scopeKey, scopedService);

package/dist/src/service/configuration/command/ConfigDumpSubCommand.d.ts

@@ -1,15 +1,11 @@
+import type DefaultConfigurationService from "../DefaultConfigurationService.ts";
 import type { Context } from "@flowscripter/dynamic-cli-framework-api";
 import type { Option } from "@flowscripter/dynamic-cli-framework-api";
 import type { Positional } from "@flowscripter/dynamic-cli-framework-api";
 import type { SubCommand } from "@flowscripter/dynamic-cli-framework-api";
 /**
  * Member of the `config` group which dumps the configuration loaded by
- * {@link ConfigurationServiceProvider}.
- *
- * Takes a direct reference to {@link ConfigurationServiceProvider.getConfigString}, wired by the
- * provider that constructs this command, rather than looking it up via {@link Context} -
- * deliberately, since a full config dump is not something every command/task should be able to
- * reach through a general lookup (see {@link ConfigurationService}'s doc comment).
+ * {@link DefaultConfigurationService}, with secrets masked.
  */
 export default class ConfigDumpSubCommand implements SubCommand {
     #private;
@@ -17,7 +13,7 @@ export default class ConfigDumpSubCommand implements SubCommand {
     readonly description = "Dump configuration values";
     readonly options: ReadonlyArray<Option>;
     readonly positionals: ReadonlyArray<Positional>;
-    constructor(getConfigString: () => string);
+    constructor(configurationService: DefaultConfigurationService);
     execute(context: Context): Promise<void>;
 }
 //# sourceMappingURL=ConfigDumpSubCommand.d.ts.map

package/dist/src/service/configuration/command/ConfigDumpSubCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConfigDumpSubCommand.d.ts","sourceRoot":"","sources":["../../../../../src/service/configuration/command/ConfigDumpSubCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yCAAyC,CAAC;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yCAAyC,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yCAAyC,CAAC;AAM1E;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,OAAO,oBAAqB,YAAW,UAAU;;IAC7D,QAAQ,CAAC,IAAI,UAAU;IACvB,QAAQ,CAAC,WAAW,+BAA+B;IACnD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAM;IAC7C,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,CAAM;IAIrD,YAAmB,eAAe,EAAE,MAAM,MAAM,EAE/C;IAEY,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CASpD;CACF"}
+{"version":3,"file":"ConfigDumpSubCommand.d.ts","sourceRoot":"","sources":["../../../../../src/service/configuration/command/ConfigDumpSubCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,2BAA2B,MAAM,mCAAmC,CAAC;AACjF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yCAAyC,CAAC;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yCAAyC,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yCAAyC,CAAC;AAM1E;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,oBAAqB,YAAW,UAAU;;IAC7D,QAAQ,CAAC,IAAI,UAAU;IACvB,QAAQ,CAAC,WAAW,+BAA+B;IACnD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAM;IAC7C,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,CAAM;IAIrD,YAAmB,oBAAoB,EAAE,2BAA2B,EAEnE;IAEY,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CASpD;CACF"}