@smarthome.exchange/integrations 0.1.0 → 1.0.0

package/readme.md

@@ -30,11 +30,13 @@ const candidates = await engine.runActiveDiscovery({});
 console.log(candidates);
 ```
 
+Pass `abortSignal` to `runActiveDiscovery()` to cancel discovery. Cancellation rejects with the caller's original reason even when an admitted probe reports its own error after abort, admits no further probes, and does not return a partial candidate list. An uncancelled probe failure preserves the probe's original error. Each admitted probe remains responsible for closing its owned resources.
+
 ## Public Surface
 
 | Export group | What it gives you |
 | --- | --- |
-| Core classes | `BaseIntegration`, `DescriptorOnlyIntegration`, `DiscoveryDescriptor`, `DiscoveryEngine`, `IntegrationRegistry`, `IntegrationRuntimeManager`, `ConsoleLogger`, `JsonFileConfigStore`. |
+| Core classes | `BaseIntegration`, `DescriptorOnlyIntegration`, `DiscoveryDescriptor`, `DiscoveryEngine`, `IntegrationRegistry`, `IntegrationRuntimeManager`, `ConsoleLogger`, `NoSqlConfigStore`. |
 | Core errors | `IntegrationError`, `DiscoveryError`, `AuthenticationError`, `DeviceCommunicationError`. |
 | Core types | Discovery, config-flow, runtime, service-call, entity, logging, and integration status contracts. |
 | Protocol namespaces | `mdns`, `ssdp`, `http`, `mqtt`, `bluetooth`, and `usb` descriptor helpers. |
@@ -42,6 +44,43 @@ console.log(candidates);
 | Generated metadata | `generatedHomeAssistantPortIntegrations`, `generatedHomeAssistantPortCount`, and `handwrittenHomeAssistantPortDomains`. |
 | Handwritten modules | All handwritten integration folders are re-exported from `ts/integrations/index.ts`. |
 
+## Durable Integration Config
+
+`NoSqlConfigStore` implements `IConfigStore` through the public document-model APIs of `@lossless.org/client/nosqldb`. It replaces `JsonFileConfigStore`; application config is no longer persisted on the filesystem. Supply a connected, caller-owned `SmartdataDb`, an authenticated home ID, an integration domain and an external key provider:
+
+This is a breaking API change: remove the `JsonFileConfigStore` import and replace `new JsonFileConfigStore(filePath)` with the options-based constructor below. Await `initialize()` before passing the store to integration contexts. Existing `IConfigStore` calls to `get()`, `set()`, `delete()` and `list()` remain valid; each also accepts optional transaction options. Existing JSON files are not read automatically; import them explicitly with the migration described below before switching the application to the new store. The database and encryption-key provider are required to keep config durable, scoped and encrypted.
+
+```ts
+import { NoSqlConfigStore } from '@smarthome.exchange/integrations';
+
+const store = new NoSqlConfigStore({
+  db,
+  homeId: authenticatedHome.id,
+  integrationDomain: 'hue',
+  keyProvider: {
+    currentKey: (signal) => secretProvider.currentEncryptionKey(signal),
+    keyForId: (keyId, signal) => secretProvider.encryptionKeyById(keyId, signal),
+  },
+});
+await store.initialize();
+await store.set('bridge', bridgeConfig);
+const restoredConfig = await store.get('bridge');
+```
+
+`db`, `authenticatedHome`, `bridgeConfig` and `secretProvider` are application-owned collaborators. The store neither creates nor closes the database. Initialize it before opening a transaction so its indexes are ready. Choose its immutable home/domain scope from authorized server context. `IConfigStore` injection remains available in discovery, config-flow and setup contexts.
+
+`getScope()` returns a new frozen `IConfigStoreScope` containing the immutable `homeId` and `integrationDomain` captured at construction. The snapshot remains available after close and contains no database or encryption credentials. `IConfigStore` exposes this capability optionally; integrations requiring scoped storage must reject a missing or mismatched scope before accessing config. A scope declaration does not grant home access: compare it against verified server context.
+
+`initialize({ signal })` prepares the declared collection and indexes through the client's public `prepareCollection()` API. The configured `timeoutMs` bounds the entire preparation, including waiting for another preparation and cleanup; an optional caller signal cancels that caller's attempt. Failed or cancelled preparation can be retried on the same open store. Await `close()` during shutdown: it stops admission, cancels this store's preparation and key lookups, refuses queued operations and joins admitted work before resolving. In-flight database operations and caller-owned transactions retain their client deadlines and ownership; close does not close the database, session or key provider. A closed store cannot be reopened.
+
+Every config value, including credentials, is encrypted with AES-256-GCM and a fresh 12-byte nonce. `currentKey(signal)` returns `{ id, key }`, where `key` contains exactly 32 bytes; `keyForId(id, signal)` resolves an older key or returns `undefined`. Keep keys in an external secret provider, preserve old keys while records still reference them, and honor cancellation. The store binds the ciphertext to its schema version, key ID, home ID, integration domain and config key. A missing key, corrupt envelope or failed authentication rejects the read. Normal writes use the current key, so rewriting a value rotates its encryption without changing its scope.
+
+The database stores one document per config key with unique scope indexes. Atomic writes preserve unrelated keys across independent instances; `get()` does not cache values. Operations on one store execute in invocation order, including read-after-write ordering. Admission defaults to 1,000 active/queued operations and rejects at capacity; failures release admission. `timeoutMs` defaults to 5,000 and bounds each key-provider lookup and each database call outside a transaction. Values must be finite JSON data, with dense arrays and plain objects, at most 32 levels deep and 64 KiB by default. Optional object fields whose value is `undefined` are omitted; `undefined` array elements and top-level values reject. `maxValueBytes` can raise that limit to 1 MiB; large payloads belong in object storage. `create()` inserts without replacing an existing key.
+
+All config operations accept `IConfigStoreOperationOptions` with a public `SmartdataSession` from the same database. Call `initialize()` before starting a transaction, then sequentially await `get(key, { session })`, `set(key, value, { session })`, `create(key, value, { session })`, `delete(key, { session })` and `list(prefix, { session })` inside `session.withTransaction(callback, { timeoutMS, signal })`. Reads and lists see that transaction's writes, and config writes can commit or roll back with another model's ownership-lease update. The caller owns commit, rollback and session close. Session-carrying operations omit their database timeout because the caller's transaction supplies it; always provide a transaction deadline. Key lookup keeps its separate store deadline, so cancellation during a lookup waits for that lookup to settle or time out before the transaction rejects. No database operation is detached on timeout; the client settles its operation and rollback cleanup before rejecting. Do not retry an unknown commit outcome: inspect `SmartdataSession.getCommitOutcome(error)` and reconcile durable state first.
+
+Existing JSON files can be imported explicitly through `importLegacyJsonConfig()` from `@smarthome.exchange/integrations/migration`. Pass the same store options plus `sourcePath`. The versioned module under `ts_migration/` reads at most 1 MiB, requires an object root, and uses one transaction to insert all values and record completion. Any existing config key refuses the entire import. Re-running the same completed source returns `{ applied: false, importedKeys }` without replacing subsequent edits; a changed source rejects. The source file is never written, renamed or removed, and no file import runs implicitly during normal store initialization. Migration requires a database supporting transactions.
+
 ## Integration Lifecycle
 
 ```ts
@@ -52,33 +91,31 @@ if (!integration) {
 }
 
 const matches = await engine.validateCandidate({
-  id: 'hue:bridge:office',
+  id: '001788fffe123456',
   source: 'manual',
   integrationDomain: 'hue',
   host: '192.168.1.20',
   name: 'Office Hue Bridge',
-  metadata: {
-    baseUrl: 'https://192.168.1.20',
-  },
 });
 
 console.log(matches);
 ```
 
-The hub uses the same primitives through `discoverIntegrationCandidates()` and `setupIntegration(...)`, then reconciles each runtime's complete normalized device snapshot into the canonical registry. Devices absent from a later snapshot are removed.
+The hub uses the same primitives through `discoverIntegrationCandidates()` and `setupIntegration(...)`, then reconciles each runtime's complete normalized device snapshot into the canonical registry. Devices absent from a later snapshot are removed. `IntegrationRuntimeManager.createRuntime()` and `setupIntegration()` retry retained cleanup for the requested domain before invoking integration setup and fail closed with an `AggregateError` while cleanup still fails. Replacement setup destroys the previous runtime before constructing its successor, and overlapping same-domain setup calls are rejected. Failed replacement and mismatched-runtime cleanup remains retained under the requested domain; `retryPendingCleanup(domain)` is the explicit no-timeout retry entry point, while `hasPendingCleanup(domain)` exposes whether that gate remains closed.
 
 Runtime setup receives an optional abort signal. Device snapshots, subscriptions, and feature writes can also accept abort signals, allowing the hub to bound setup, synchronization, and writes. A control runtime may implement `writeFeature(...)`, `callService(...)`, or both; authoritative readable state still comes from a later `devices()` snapshot rather than an optimistic write. Every runtime implements `destroy()` for explicit cleanup.
 
 ## Home Assistant Runtime
 
-The handwritten `homeassistant` integration connects to `/api/websocket` with a long-lived access token held only in runtime configuration. Setup does not become ready until Home Assistant has delivered the first complete entity snapshot. The official connection owns socket reconnection and subscription restoration; disconnects mark normalized devices offline immediately. Each reconnect remains unready until an authoritative state refresh and, when enabled, a fresh entity-registry provenance check both succeed. Failed reconnect refreshes use adapter-owned exponential backoff from 1 through 30 seconds. If the socket reconnects during strict startup, validation restarts against the current connection generation before setup may succeed. While an authoritative snapshot or registry refresh is pending, only selected state events are retained, coalesced by entity ID, and replayed onto the snapshot.
+The handwritten `homeassistant` integration connects to `/api/websocket` with a long-lived access token held only in runtime configuration. Setup does not become ready until Home Assistant has delivered the first complete entity snapshot. The official connection owns socket reconnection and subscription restoration; disconnects mark normalized devices offline immediately. Each reconnect remains unready until an authoritative state refresh, a fresh service catalogue, and a fresh entity-registry provenance check all succeed. Failed reconnect refreshes use adapter-owned exponential backoff from 1 through 30 seconds. If the socket reconnects during strict startup, validation restarts against the current connection generation before setup may succeed. While an authoritative snapshot or registry refresh is pending, only selected state events are retained, coalesced by entity ID, and replayed onto the snapshot.
 
-Optional `entityIds` and `entityDomains` are allowlists with intersection semantics when both are present. Set `requireEntityIds: true` to fail setup when any configured entity is absent. Set `requireEntityRegistry: true` together with `requireEntityIds` to require Home Assistant's `config/entity_registry/list_for_display` response and record each entity's integration platform in `metadata.homeAssistantPlatform`. The runtime exposes read-only state for all selected entities, controlled power and percentage brightness for supported lights, power for switches and input booleans, energy telemetry for power and energy sensors, and supported write-only vacuum commands. It does not expose unrestricted Home Assistant service calls.
+Optional `entityIds` and `entityDomains` are allowlists with intersection semantics when both are present. Set `requireEntityIds: true` to fail setup when any configured entity is absent. Set `requireEntityRegistry: true` together with `requireEntityIds` to require an entry for every selected entity in Home Assistant's `config/entity_registry/list_for_display` response. Every setup records available entity integration platforms in `metadata.homeAssistantPlatform`. The runtime exposes read-only state for all selected entities, controlled power and percentage brightness for supported lights, power for switches and input booleans, energy telemetry for power and energy sensors, and supported write-only vacuum commands. It does not expose unrestricted Home Assistant service calls.
 
 ```ts
 import { HomeAssistantHomeassistantIntegration } from "@smarthome.exchange/integrations";
 
 const runtime = await new HomeAssistantHomeassistantIntegration().setup({
+  homeId: "house-a",
   baseUrl: "http://homeassistant.local:8123",
   accessToken: homeAssistantToken,
   entityDomains: ["light", "sensor", "switch", "vacuum"],
@@ -96,7 +133,7 @@ try {
 }
 ```
 
-`baseUrl` and `accessToken` are required. `entityIds` and `entityDomains` are optional intersecting allowlists. Required-entity and registry checks need a non-empty `entityIds` allowlist; registry enforcement also requires required-entity enforcement, and every required entity's domain must be allowed by `entityDomains` when that filter is present. `setupRetry` must be a finite non-negative integer and controls the adapter-owned, abortable retry loop; each official websocket connection/socket call receives `setupRetry: 0` so it cannot start an unbounded nested retry. `initialSnapshotTimeoutMs` is a timer-safe integer from 1 through 2,147,483,647 and provides one shared deadline for socket creation and authentication, initial subscription acknowledgement, the first complete entity snapshot, and optional registry verification. `serviceCallTimeoutMs` has the same range, defaults to 15 seconds, and bounds every write even when the caller does not supply an abort signal. Aborted or timed-out writes cancel the pending command by forcing the owned connection through its normal reconnect lifecycle. Required-entity loss blocks health and writes; recreation remains unready until registry provenance is revalidated. Among Home Assistant entity state values, `unknown` remains present and online with an unknown value while `unavailable` marks an entity offline; socket disconnection also marks normalized devices offline immediately.
+`homeId`, `baseUrl` and `accessToken` are required. Device and entity IDs include the configured home and a stable hash of the endpoint origin; writes validate that immutable scope and the current canonical device/feature before dispatch. The integration always fetches real service and entity-registry catalogues before readiness, and only currently advertised service controls are writable. Catalogue-change events and reconnects refresh all three authoritative snapshots. See the [Home Assistant runtime](ts/integrations/homeassistant/readme.md) for the configuration migration and exact boundaries. `entityIds` and `entityDomains` are optional intersecting allowlists. Required-entity and registry checks need a non-empty `entityIds` allowlist; registry enforcement also requires required-entity enforcement, and every required entity's domain must be allowed by `entityDomains` when that filter is present. `setupRetry` must be a finite non-negative integer and controls the adapter-owned, abortable retry loop; each official websocket connection/socket call receives `setupRetry: 0` so it cannot start an unbounded nested retry. `initialSnapshotTimeoutMs` is a timer-safe integer from 1 through 2,147,483,647 and provides one shared deadline for socket creation and authentication, initial subscription acknowledgement, the first complete entity snapshot, live service catalogue and entity-registry provenance. `serviceCallTimeoutMs` has the same range, defaults to 15 seconds, and bounds every write even when the caller does not supply an abort signal. Aborted or timed-out writes cancel the pending command by forcing the owned connection through its normal reconnect lifecycle. Required-entity loss blocks health and writes; recreation remains unready until registry provenance is revalidated. Among Home Assistant entity state values, `unknown` remains present and online with an unknown value while `unavailable` marks an entity offline; socket disconnection also marks normalized devices offline immediately.
 
 The runtime requires native WebSocket support from Node.js 22.4 or newer. Production packaging must verify that runtime version. Hue, ZHA/SkyConnect, Roborock, Huawei SUN2000, and FHEM/MQTT entities remain subject to live-device acceptance testing; SUN2000 settings are not writable through this generic allowlist, and the adapter itself does not claim that those upstream integrations are configured.
 
@@ -110,7 +147,9 @@ Current generated metadata is exposed through `generatedHomeAssistantPortCount`
 
 The default `integrations` array registers handwritten integrations tracked by `handwrittenHomeAssistantPortDomains` plus custom integrations such as Wolf Smartset. These handwritten folders are exported as named modules and registered before generated descriptors, so handwritten code wins whenever a generated Home Assistant descriptor has the same domain.
 
-Examples include Home Assistant, Hue, AdGuard, AirGradient, Amcrest, Android TV, APC UPSD, ASUSWRT, Axis, BleBox, Bosch SHC, Broadlink, deCONZ, Denon AVR, DSMR, ESPHome, Fritz, HomeKit Controller, Homematic, KNX, Kodi, Matter, MQTT, Nanoleaf, ONVIF, Pi-hole, Plex, Roku, Shelly, Sonos, Synology DSM, TP-Link, Tradfri, UniFi, Wolf Smartset, Xiaomi Miio, Yeelight, ZHA, and Z-Wave JS.
+Examples include Home Assistant, Hue, AdGuard, AirGradient, Amcrest, Android TV, APC UPSD, ASUSWRT, Axis, BleBox, Bosch SHC, Broadlink, deCONZ, Denon AVR, DSMR, ESPHome, Fritz, HomeKit Controller, Homematic, KNX, Kodi, Matter, MQTT, Nanoleaf, ONVIF, Pi-hole, Plex, Roku, Shelly, Sonos, Synology DSM, Tasmota, TP-Link, Tradfri, UniFi, Wolf Smartset, Xiaomi Miio, Yeelight, ZHA, and Z-Wave JS.
+
+The native [Tasmota runtime](./ts/integrations/tasmota/readme.md) connects selected devices directly through MQTT. It provides relay and single-channel brightness controls plus read-only sensor telemetry, requires fresh device state before writes, and is registered as `control-runtime` rather than a generated descriptor.
 
 The generator updates the barrel export file during `pnpm generate:ha`, so the named export surface stays aligned with preserved handwritten folders instead of drifting back to a short manual list.
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@smarthome.exchange/integrations',
-  version: '0.1.0',
+  version: '1.0.0',
   description: 'TypeScript-native device integrations for smarthome.exchange.'
 }

package/ts/core/classes.configrecord.ts

@@ -0,0 +1,23 @@
+import * as plugins from '../plugins.js';
+
+export interface IEncryptedConfigValue {
+  version: 1;
+  keyId: string;
+  nonce: string;
+  ciphertext: string;
+  tag: string;
+}
+
+@plugins.nosqldb.managed({ collectionName: 'shx_integration_config' })
+@plugins.nosqldb.namedIndex({
+  name: 'integration_config_scope',
+  key: { homeId: 1, integrationDomain: 1, key: 1 },
+  options: { unique: true },
+})
+export class IntegrationConfigRecord extends plugins.nosqldb.SmartDataDbDoc<IntegrationConfigRecord, IntegrationConfigRecord> {
+  @plugins.nosqldb.unI({ indexName: 'integration_config_identity' }) public id!: string;
+  @plugins.nosqldb.svDb() public homeId!: string;
+  @plugins.nosqldb.svDb() public integrationDomain!: string;
+  @plugins.nosqldb.svDb() public key!: string;
+  @plugins.nosqldb.svDb() public encryptedValue!: IEncryptedConfigValue;
+}

package/ts/core/classes.configstore.ts

@@ -1,42 +1,341 @@
 import * as plugins from '../plugins.js';
-import type { IConfigStore } from './types.js';
+import { IntegrationConfigRecord, type IEncryptedConfigValue } from './classes.configrecord.js';
+import type { IConfigStore, IConfigStoreOperationOptions, IConfigStoreScope } from './types.js';
 
-export class JsonFileConfigStore implements IConfigStore {
-  constructor(private readonly filePath: string) {}
+export interface IConfigEncryptionKey {
+  id: string;
+  key: Uint8Array;
+}
+
+export interface IConfigEncryptionKeyProvider {
+  currentKey(signalArg: AbortSignal): Promise<IConfigEncryptionKey>;
+  keyForId(keyIdArg: string, signalArg: AbortSignal): Promise<Uint8Array | undefined>;
+}
+
+export interface INoSqlConfigStoreOptions {
+  db: plugins.nosqldb.SmartdataDb;
+  homeId: string;
+  integrationDomain: string;
+  keyProvider: IConfigEncryptionKeyProvider;
+  timeoutMs?: number;
+  maxPendingOperations?: number;
+  maxValueBytes?: number;
+}
+
+export interface IConfigCreateOptions extends IConfigStoreOperationOptions {}
+
+export interface IConfigStoreInitializationOptions {
+  signal?: AbortSignal;
+}
+
+const validateName = (valueArg: string, nameArg: string, maxLengthArg: number): string => {
+  if (typeof valueArg !== 'string' || valueArg.length === 0 || valueArg.length > maxLengthArg || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError(`${nameArg} must be a non-empty string without control characters, at most ${maxLengthArg} characters.`);
+  }
+  return valueArg;
+};
+
+const boundedInteger = (valueArg: number, nameArg: string, maximumArg: number): number => {
+  if (!Number.isSafeInteger(valueArg) || valueArg < 1 || valueArg > maximumArg) {
+    throw new RangeError(`${nameArg} must be an integer from 1 through ${maximumArg}.`);
+  }
+  return valueArg;
+};
+
+const assertJsonValue = (valueArg: unknown, ancestorsArg = new Set<object>(), depthArg = 0): void => {
+  if (valueArg === null || typeof valueArg === 'string' || typeof valueArg === 'boolean') return;
+  if (typeof valueArg === 'number' && Number.isFinite(valueArg)) return;
+  if (typeof valueArg !== 'object' || depthArg >= 32 || ancestorsArg.has(valueArg)) {
+    throw new TypeError('Config values must be finite JSON data without cycles and at most 32 levels deep.');
+  }
+  if (!Array.isArray(valueArg) && Object.getPrototypeOf(valueArg) !== Object.prototype && Object.getPrototypeOf(valueArg) !== null) {
+    throw new TypeError('Config values must contain only arrays and plain objects.');
+  }
+  ancestorsArg.add(valueArg);
+  try {
+    for (const key of Reflect.ownKeys(valueArg)) {
+      if (Array.isArray(valueArg) && key === 'length') continue;
+      const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+      if (typeof key !== 'string' || !descriptor || !('value' in descriptor) || !descriptor.enumerable) {
+        throw new TypeError('Config values may not contain symbols, accessors or hidden fields.');
+      }
+      if (Array.isArray(valueArg) && (!/^(0|[1-9]\d*)$/.test(key) || Number(key) >= valueArg.length)) {
+        throw new TypeError('Config arrays may not have additional properties.');
+      }
+      if (!Array.isArray(valueArg) && descriptor.value === undefined) continue;
+      assertJsonValue(descriptor.value, ancestorsArg, depthArg + 1);
+    }
+    if (Array.isArray(valueArg) && Object.keys(valueArg).length !== valueArg.length) {
+      throw new TypeError('Config arrays must be dense and may not have additional properties.');
+    }
+  } finally {
+    ancestorsArg.delete(valueArg);
+  }
+};
 
-  public async get<TValue>(keyArg: string): Promise<TValue | undefined> {
-    const data = await this.readFile();
-    return data[keyArg] as TValue | undefined;
+const copyKey = (valueArg: Uint8Array | undefined): Buffer => {
+  if (!(valueArg instanceof Uint8Array) || valueArg.byteLength !== 32) {
+    throw new TypeError('Config encryption requires an external 32-byte key.');
   }
+  return Buffer.from(valueArg);
+};
 
-  public async set<TValue>(keyArg: string, valueArg: TValue): Promise<void> {
-    const data = await this.readFile();
-    data[keyArg] = valueArg;
-    await this.writeFile(data);
+const decodeBase64 = (valueArg: string, maximumBytesArg: number, exactBytesArg?: number): Buffer => {
+  if (typeof valueArg !== 'string' || valueArg.length > Math.ceil(maximumBytesArg / 3) * 4) {
+    throw new Error('Stored config encryption envelope is invalid.');
   }
+  const decoded = Buffer.from(valueArg, 'base64');
+  if (decoded.toString('base64') !== valueArg || decoded.byteLength > maximumBytesArg || (exactBytesArg !== undefined && decoded.byteLength !== exactBytesArg)) {
+    throw new Error('Stored config encryption envelope is invalid.');
+  }
+  return decoded;
+};
+
+/** The caller owns the database and key provider; this store owns neither resource. */
+export class NoSqlConfigStore implements IConfigStore {
+  readonly #records: typeof IntegrationConfigRecord;
+  readonly #homeId: string;
+  readonly #integrationDomain: string;
+  readonly #keyProvider: IConfigEncryptionKeyProvider;
+  readonly #timeoutMs: number;
+  readonly #maxPendingOperations: number;
+  readonly #maxValueBytes: number;
+  readonly #lifetime = new AbortController();
+  readonly #preparations = new Set<Promise<void>>();
+  #operationTail: Promise<void> = Promise.resolve();
+  #pendingOperations = 0;
+  #closePromise?: Promise<void>;
 
-  public async delete(keyArg: string): Promise<void> {
-    const data = await this.readFile();
-    delete data[keyArg];
-    await this.writeFile(data);
+  constructor(optionsArg: INoSqlConfigStoreOptions) {
+    this.#homeId = validateName(optionsArg.homeId, 'homeId', 256);
+    this.#integrationDomain = validateName(optionsArg.integrationDomain, 'integrationDomain', 128);
+    this.#keyProvider = optionsArg.keyProvider;
+    this.#timeoutMs = boundedInteger(optionsArg.timeoutMs ?? 5000, 'timeoutMs', 120000);
+    this.#maxPendingOperations = boundedInteger(optionsArg.maxPendingOperations ?? 1000, 'maxPendingOperations', 10000);
+    this.#maxValueBytes = boundedInteger(optionsArg.maxValueBytes ?? 65536, 'maxValueBytes', 1048576);
+    if (!this.#keyProvider || typeof this.#keyProvider.currentKey !== 'function' || typeof this.#keyProvider.keyForId !== 'function') {
+      throw new TypeError('Config encryption requires a currentKey/keyForId provider.');
+    }
+    this.#records = plugins.nosqldb.bindDocToManager({ db: optionsArg.db }, IntegrationConfigRecord);
   }
 
-  public async list(prefixArg = ''): Promise<string[]> {
-    const data = await this.readFile();
-    return Object.keys(data).filter((keyArg) => keyArg.startsWith(prefixArg));
+  public getScope(): IConfigStoreScope {
+    return Object.freeze({ homeId: this.#homeId, integrationDomain: this.#integrationDomain });
   }
 
-  private async readFile(): Promise<Record<string, unknown>> {
+  public async initialize(optionsArg: IConfigStoreInitializationOptions = {}): Promise<void> {
+    this.#assertOpen();
+    if (!optionsArg || Object.getPrototypeOf(optionsArg) !== Object.prototype ||
+      Reflect.ownKeys(optionsArg).some((keyArg) => keyArg !== 'signal' ||
+        !('value' in Object.getOwnPropertyDescriptor(optionsArg, keyArg)!))) {
+      throw new TypeError('Config initialization options accept only an AbortSignal.');
+    }
+    const signal = Object.getOwnPropertyDescriptor(optionsArg, 'signal')?.value as AbortSignal | undefined;
+    if (signal !== undefined && !(signal instanceof AbortSignal)) {
+      throw new TypeError('Config initialization signal must be an AbortSignal.');
+    }
+    signal?.throwIfAborted();
+    const preparation = this.#records.prepareCollection({
+      mode: 'ensureCompatible',
+      timeoutMs: this.#timeoutMs,
+      signal: signal ? AbortSignal.any([signal, this.#lifetime.signal]) : this.#lifetime.signal,
+    });
+    this.#preparations.add(preparation);
     try {
-      const fileString = await plugins.fs.readFile(this.filePath, 'utf8');
-      return JSON.parse(fileString) as Record<string, unknown>;
-    } catch (error) {
-      return {};
+      await preparation;
+      this.#assertOpen();
+    } finally {
+      this.#preparations.delete(preparation);
+    }
+  }
+
+  /** Stops this store without closing its caller-owned database or sessions. */
+  public close(): Promise<void> {
+    if (!this.#closePromise) {
+      this.#closePromise = Promise.resolve().then(async () => {
+        await Promise.allSettled([
+          ...this.#preparations,
+          this.#operationTail,
+        ]);
+      });
+      this.#lifetime.abort(new Error('NoSqlConfigStore is closed.'));
+    }
+    return this.#closePromise;
+  }
+
+  public get<TValue>(keyArg: string, optionsArg: IConfigStoreOperationOptions = {}): Promise<TValue | undefined> {
+    const key = validateName(keyArg, 'config key', 1024);
+    const databaseOptions = this.#databaseOptions(optionsArg);
+    return this.#runOperation(async () => {
+      const record = await this.#records.getInstance(this.#selector(key), databaseOptions);
+      return record ? this.#decrypt<TValue>(key, record.encryptedValue) : undefined;
+    });
+  }
+
+  public set<TValue>(keyArg: string, valueArg: TValue, optionsArg: IConfigStoreOperationOptions = {}): Promise<void> {
+    const key = validateName(keyArg, 'config key', 1024);
+    const serialized = this.#serialize(valueArg);
+    const databaseOptions = this.#databaseOptions(optionsArg);
+    return this.#runOperation(async () => {
+      const encryptedValue = await this.#encrypt(key, serialized);
+      await this.#records.atomicUpdate({ id: this.#selector(key).id }, {
+        $set: { homeId: this.#homeId, integrationDomain: this.#integrationDomain, key, encryptedValue },
+      }, { upsert: true, ...databaseOptions });
+    });
+  }
+
+  /** Insert-only persistence for callers that must never replace an existing key. */
+  public create<TValue>(keyArg: string, valueArg: TValue, optionsArg: IConfigCreateOptions = {}): Promise<void> {
+    const key = validateName(keyArg, 'config key', 1024);
+    const serialized = this.#serialize(valueArg);
+    const databaseOptions = this.#databaseOptions(optionsArg);
+    return this.#runOperation(async () => {
+      const record = Object.assign(new this.#records(), this.#selector(key), {
+        encryptedValue: await this.#encrypt(key, serialized),
+      });
+      await this.#records.insert(record, databaseOptions);
+    });
+  }
+
+  public delete(keyArg: string, optionsArg: IConfigStoreOperationOptions = {}): Promise<void> {
+    const key = validateName(keyArg, 'config key', 1024);
+    const databaseOptions = this.#databaseOptions(optionsArg);
+    return this.#runOperation(async () => {
+      await this.#records.atomicDelete(this.#selector(key), databaseOptions);
+    });
+  }
+
+  public list(prefixArg = '', optionsArg: IConfigStoreOperationOptions = {}): Promise<string[]> {
+    if (prefixArg !== '') validateName(prefixArg, 'config key prefix', 1024);
+    const databaseOptions = this.#databaseOptions(optionsArg);
+    return this.#runOperation(async () => {
+      const records = await this.#records.getInstances({
+        homeId: this.#homeId,
+        integrationDomain: this.#integrationDomain,
+      }, databaseOptions);
+      return records.map((recordArg) => recordArg.key).filter((keyArg) => keyArg.startsWith(prefixArg)).sort();
+    });
+  }
+
+  #databaseOptions(optionsArg: IConfigStoreOperationOptions): { session: plugins.nosqldb.SmartdataSession } | { timeoutMS: number } {
+    if (!optionsArg || Object.getPrototypeOf(optionsArg) !== Object.prototype ||
+      Reflect.ownKeys(optionsArg).some((keyArg) => keyArg !== 'session' ||
+        !('value' in Object.getOwnPropertyDescriptor(optionsArg, keyArg)!))) {
+      throw new TypeError('Config operation options accept only a caller-owned SmartdataSession.');
+    }
+    const session = Object.getOwnPropertyDescriptor(optionsArg, 'session')?.value as plugins.nosqldb.SmartdataSession | undefined;
+    if (session === undefined) return { timeoutMS: this.#timeoutMs };
+    if (!(session instanceof plugins.nosqldb.SmartdataSession)) {
+      throw new TypeError('Config operation session must be a caller-owned SmartdataSession.');
+    }
+    return { session };
+  }
+
+  #selector(keyArg: string) {
+    return {
+      id: JSON.stringify([this.#homeId, this.#integrationDomain, keyArg]),
+      homeId: this.#homeId,
+      integrationDomain: this.#integrationDomain,
+      key: keyArg,
+    };
+  }
+
+  #aad(keyArg: string, keyIdArg: string): Buffer {
+    return Buffer.from(JSON.stringify([1, this.#homeId, this.#integrationDomain, keyArg, keyIdArg]), 'utf8');
+  }
+
+  #serialize(valueArg: unknown): string {
+    assertJsonValue(valueArg);
+    const serialized = JSON.stringify(valueArg);
+    if (Buffer.byteLength(serialized, 'utf8') > this.#maxValueBytes) {
+      throw new RangeError(`Config value exceeds the ${this.#maxValueBytes}-byte limit; large payloads require object storage.`);
+    }
+    return serialized;
+  }
+
+  async #encrypt(keyArg: string, serializedArg: string): Promise<IEncryptedConfigValue> {
+    const encryptionKey = await this.#lookupKey((signalArg) => this.#keyProvider.currentKey(signalArg));
+    const keyId = validateName(encryptionKey.id, 'encryption key ID', 128);
+    const key = copyKey(encryptionKey.key);
+    try {
+      const nonce = plugins.crypto.randomBytes(12);
+      const cipher = plugins.crypto.createCipheriv('aes-256-gcm', key, nonce);
+      cipher.setAAD(this.#aad(keyArg, keyId));
+      const ciphertext = Buffer.concat([cipher.update(serializedArg, 'utf8'), cipher.final()]);
+      return { version: 1, keyId, nonce: nonce.toString('base64'), ciphertext: ciphertext.toString('base64'), tag: cipher.getAuthTag().toString('base64') };
+    } finally {
+      key.fill(0);
+    }
+  }
+
+  async #decrypt<TValue>(keyArg: string, valueArg: IEncryptedConfigValue): Promise<TValue> {
+    if (!valueArg || valueArg.version !== 1) throw new Error('Stored config encryption envelope is invalid.');
+    const keyId = validateName(valueArg.keyId, 'stored encryption key ID', 128);
+    const nonce = decodeBase64(valueArg.nonce, 12, 12);
+    const tag = decodeBase64(valueArg.tag, 16, 16);
+    const ciphertext = decodeBase64(valueArg.ciphertext, this.#maxValueBytes);
+    const key = copyKey(await this.#lookupKey((signalArg) => this.#keyProvider.keyForId(keyId, signalArg)));
+    try {
+      const decipher = plugins.crypto.createDecipheriv('aes-256-gcm', key, nonce);
+      decipher.setAAD(this.#aad(keyArg, keyId));
+      decipher.setAuthTag(tag);
+      const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+      try {
+        const value: unknown = JSON.parse(plaintext.toString('utf8'));
+        assertJsonValue(value);
+        return value as TValue;
+      } finally {
+        plaintext.fill(0);
+      }
+    } catch {
+      throw new Error('Stored config failed authentication or JSON validation.');
+    } finally {
+      key.fill(0);
+    }
+  }
+
+  async #lookupKey<TResult>(lookupArg: (signalArg: AbortSignal) => Promise<TResult>): Promise<TResult> {
+    this.#assertOpen();
+    const controller = new AbortController();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const deadline = new Promise<never>((resolveArg, rejectArg) => {
+      void resolveArg;
+      timer = setTimeout(() => {
+        const error = new Error('Config encryption key lookup timed out.');
+        controller.abort(error);
+        rejectArg(error);
+      }, this.#timeoutMs);
+      timer.unref();
+    });
+    try {
+      const result = await Promise.race([
+        lookupArg(AbortSignal.any([controller.signal, this.#lifetime.signal])),
+        deadline,
+      ]);
+      this.#assertOpen();
+      return result;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  #runOperation<TResult>(operationArg: () => Promise<TResult>): Promise<TResult> {
+    if (this.#lifetime.signal.aborted) {
+      return Promise.reject(this.#lifetime.signal.reason);
+    }
+    if (this.#pendingOperations >= this.#maxPendingOperations) {
+      return Promise.reject(new Error(`NoSqlConfigStore operation capacity reached: ${this.#maxPendingOperations}.`));
     }
+    this.#pendingOperations += 1;
+    const operation = this.#operationTail.then(() => {
+      this.#assertOpen();
+      return operationArg();
+    }).finally(() => { this.#pendingOperations -= 1; });
+    this.#operationTail = operation.then(() => undefined, () => undefined);
+    return operation;
   }
 
-  private async writeFile(dataArg: Record<string, unknown>): Promise<void> {
-    await plugins.fs.mkdir(plugins.path.dirname(this.filePath), { recursive: true });
-    await plugins.fs.writeFile(this.filePath, `${JSON.stringify(dataArg, null, 2)}\n`);
+  #assertOpen(): void {
+    this.#lifetime.signal.throwIfAborted();
   }
 }

package/ts/core/classes.discoveryengine.ts

@@ -3,6 +3,7 @@ import type {
   IDiscoveryCandidate,
   IDiscoveryContext,
   IDiscoveryMatch,
+  IDiscoveryProbeResult,
   TDiscoverySource,
 } from './types.js';
 
@@ -10,12 +11,21 @@ export class DiscoveryEngine {
   constructor(private readonly integrationRegistry: IntegrationRegistry) {}
 
   public async runActiveDiscovery(contextArg: IDiscoveryContext = {}): Promise<IDiscoveryCandidate[]> {
+    contextArg.abortSignal?.throwIfAborted();
     const candidates: IDiscoveryCandidate[] = [];
 
     for (const integration of this.integrationRegistry.list()) {
       const descriptor = integration.discoveryDescriptor;
       for (const probe of descriptor.getProbes()) {
-        const result = await probe.probe(contextArg);
+        contextArg.abortSignal?.throwIfAborted();
+        let result: IDiscoveryProbeResult;
+        try {
+          result = await probe.probe(contextArg);
+        } catch (error) {
+          contextArg.abortSignal?.throwIfAborted();
+          throw error;
+        }
+        contextArg.abortSignal?.throwIfAborted();
         for (const candidate of result.candidates) {
           candidates.push({
             ...candidate,