@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@smarthome.exchange/integrations',
-  version: '0.2.0',
+  version: '2.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,398 @@
 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;
+}
+
+interface IConfigStoreOperationState {
+  keyLookups: Set<Promise<void>>;
+  settled: boolean;
+  providerFailed: boolean;
+}
+
+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>>();
+  readonly #keyLookups = new Set<Promise<void>>();
+  readonly #retainedOperations = new Set<IConfigStoreOperationState>();
+  readonly #keyProviderFailures = new Set<Error>();
+  #operationTail: Promise<void> = Promise.resolve();
+  #pendingOperations = 0;
+  #closePromise?: Promise<void>;
+  #retryPromise?: 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.#keyLookups,
+        ]);
+        if (this.#keyProviderFailures.size) {
+          throw new AggregateError([...this.#keyProviderFailures], 'NoSqlConfigStore key-provider cleanup failed.');
+        }
+      });
+      this.#lifetime.abort(new Error('NoSqlConfigStore is closed.'));
+    }
+    return this.#closePromise;
+  }
+
+  /** Acknowledges settled provider cleanup failures without repeating callbacks or reopening the store. */
+  public retryCleanup(): Promise<void> {
+    if (!this.#closePromise) return Promise.reject(new Error('NoSqlConfigStore cleanup requires terminal close.'));
+    this.#retryPromise ??= Promise.resolve().then(async () => {
+      await this.#closePromise!.catch(() => undefined);
+      this.#keyProviderFailures.clear();
+      this.#retainedOperations.clear();
+    });
+    return this.#retryPromise;
+  }
+
+  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 (operationArg) => {
+      const record = await this.#records.getInstance(this.#selector(key), databaseOptions);
+      return record ? this.#decrypt<TValue>(key, record.encryptedValue, operationArg) : 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 (operationArg) => {
+      const encryptedValue = await this.#encrypt(key, serialized, operationArg);
+      this.#assertOpen();
+      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 (operationArg) => {
+      const record = Object.assign(new this.#records(), this.#selector(key), {
+        encryptedValue: await this.#encrypt(key, serialized, operationArg),
+      });
+      this.#assertOpen();
+      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, operationArg: IConfigStoreOperationState): Promise<IEncryptedConfigValue> {
+    const encryptionKey = await this.#lookupKey((signalArg) => this.#keyProvider.currentKey(signalArg), operationArg);
+    this.#assertOpen();
+    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, operationArg: IConfigStoreOperationState): 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 decryptionKey = await this.#lookupKey((signalArg) => this.#keyProvider.keyForId(keyId, signalArg), operationArg);
+    this.#assertOpen();
+    const key = copyKey(decryptionKey);
+    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>, operationArg: IConfigStoreOperationState): Promise<TResult> {
+    this.#assertOpen();
+    const controller = new AbortController();
+    const signal = AbortSignal.any([controller.signal, this.#lifetime.signal]);
+    let resolveProvider!: (valueArg: TResult | PromiseLike<TResult>) => void;
+    let rejectProvider!: (errorArg: unknown) => void;
+    const provider = new Promise<TResult>((resolveArg, rejectArg) => {
+      resolveProvider = resolveArg;
+      rejectProvider = rejectArg;
+    });
+    let abortLookup!: () => void;
+    const settlement = provider.then(() => undefined, (errorArg: unknown) => {
+      if (signal.aborted && errorArg !== signal.reason) {
+        operationArg.providerFailed = true;
+        this.#keyProviderFailures.add(new Error('Config encryption key provider rejected after cancellation.'));
+      }
+    }).finally(() => {
+      this.#keyLookups.delete(settlement);
+      operationArg.keyLookups.delete(settlement);
+      if (operationArg.settled && !operationArg.keyLookups.size && !operationArg.providerFailed) {
+        this.#retainedOperations.delete(operationArg);
+      }
+      signal.removeEventListener('abort', abortLookup);
+    });
+    // Own the actual callback promise before invoking foreign code, including synchronous close reentry.
+    this.#keyLookups.add(settlement);
+    operationArg.keyLookups.add(settlement);
+    const cancellation = new Promise<never>((resolveArg, rejectArg) => {
+      void resolveArg;
+      abortLookup = () => {
+        rejectArg(signal.reason);
+      };
+      signal.addEventListener('abort', abortLookup, { once: true });
+    });
+    const timer = setTimeout(() => controller.abort(new Error('Config encryption key lookup timed out.')), this.#timeoutMs);
+    timer.unref();
+    try {
+      try { resolveProvider(lookupArg(signal)); } catch (errorArg) { rejectProvider(errorArg); }
+      const result = await Promise.race([provider, cancellation]);
+      signal.throwIfAborted();
+      this.#assertOpen();
+      return result;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  #runOperation<TResult>(operationArg: (stateArg: IConfigStoreOperationState) => Promise<TResult>): Promise<TResult> {
+    if (this.#lifetime.signal.aborted) {
+      return Promise.reject(this.#lifetime.signal.reason);
+    }
+    if (this.#pendingOperations + this.#retainedOperations.size >= this.#maxPendingOperations) {
+      return Promise.reject(new Error(`NoSqlConfigStore operation capacity reached: ${this.#maxPendingOperations}.`));
     }
+    this.#pendingOperations += 1;
+    const state: IConfigStoreOperationState = { keyLookups: new Set(), settled: false, providerFailed: false };
+    const operation = this.#operationTail.then(() => {
+      this.#assertOpen();
+      return operationArg(state);
+    }).finally(() => {
+      state.settled = true;
+      this.#pendingOperations -= 1;
+      if (state.keyLookups.size || state.providerFailed) this.#retainedOperations.add(state);
+    });
+    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,

package/ts/core/classes.nativehomeadmission.ts

@@ -0,0 +1,96 @@
+import { NoSqlConfigStore } from './classes.configstore.js';
+import type { IConfigFlowContext, IIntegrationSetupContext, ILogger } from './types.js';
+
+export interface INativeHomeAdmissionOptions {
+  readonly homeId?: string;
+}
+
+/** A captured host selection, not an authentication credential. Persistence resources are borrowed. */
+export interface INativeAdmissionContext {
+  readonly homeId: string;
+  readonly configStore?: NoSqlConfigStore;
+  readonly logger?: ILogger;
+  readonly abortSignal?: AbortSignal;
+}
+
+const identifier = (valueArg: unknown, nameArg: string, maximumArg: number): string => {
+  if (typeof valueArg !== 'string' || !valueArg || valueArg.length > maximumArg
+    || valueArg.trim() !== valueArg || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError(`${nameArg} must be a non-empty identifier without surrounding whitespace or control characters, at most ${maximumArg} characters.`);
+  }
+  return valueArg;
+};
+
+const dataFields = (valueArg: unknown, allowedArg: readonly string[], nameArg: string): Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object'
+    || (Object.getPrototypeOf(valueArg) !== Object.prototype && Object.getPrototypeOf(valueArg) !== null)) {
+    throw new TypeError(`${nameArg} must be a plain data object.`);
+  }
+  const captured: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+  for (const key of Reflect.ownKeys(valueArg)) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (typeof key !== 'string' || !allowedArg.includes(key) || !descriptor
+      || !descriptor.enumerable || !('value' in descriptor)) {
+      throw new TypeError(`${nameArg} contains an unsupported field or accessor.`);
+    }
+    captured[key] = descriptor.value as unknown;
+  }
+  return captured;
+};
+
+const logger = (valueArg: unknown): ILogger | undefined => {
+  if (valueArg === undefined) return undefined;
+  if (!valueArg || typeof valueArg !== 'object') throw new TypeError('Native logger must expose a log method.');
+  let target: object | null = valueArg;
+  for (let depth = 0; target && depth < 16; depth += 1) {
+    const descriptor = Object.getOwnPropertyDescriptor(target, 'log');
+    if (descriptor) {
+      if ('value' in descriptor && typeof descriptor.value === 'function') return valueArg as ILogger;
+      break;
+    }
+    target = Object.getPrototypeOf(target) as object | null;
+  }
+  throw new TypeError('Native logger must expose a data-method log function.');
+};
+
+/** Binds to independently selected host context only after all synchronous checks pass. */
+export class NativeHomeAdmission {
+  readonly #domain: string;
+  #homeId?: string;
+
+  constructor(domainArg: string, optionsArg: INativeHomeAdmissionOptions = {}) {
+    this.#domain = identifier(domainArg, 'integrationDomain', 128);
+    const options = dataFields(optionsArg, ['homeId'], 'Native home options');
+    if (options.homeId !== undefined) this.#homeId = identifier(options.homeId, 'homeId', 256);
+  }
+
+  public get homeId(): string | undefined { return this.#homeId; }
+
+  public admit(contextArg: IIntegrationSetupContext | IConfigFlowContext, configHomeIdArg?: string): INativeAdmissionContext {
+    const context = dataFields(contextArg, ['homeId', 'configStore', 'logger', 'abortSignal'], 'Native context');
+    const homeId = identifier(context.homeId, 'Host-selected homeId', 256);
+    if (this.#homeId !== undefined && this.#homeId !== homeId) throw new Error('Native owning home does not match the selected host home.');
+    if (configHomeIdArg !== undefined && identifier(configHomeIdArg, 'Configuration homeId', 256) !== homeId) {
+      throw new Error('Native configuration home does not match the selected host home.');
+    }
+    const configStore = context.configStore;
+    if (configStore !== undefined) {
+      if (!(configStore instanceof NoSqlConfigStore)) throw new TypeError('Native configStore must be an actual NoSqlConfigStore.');
+      // Call the owning implementation: a structural or overridden getScope cannot grant admission.
+      const scope = NoSqlConfigStore.prototype.getScope.call(configStore);
+      if (scope.homeId !== homeId || scope.integrationDomain !== this.#domain) {
+        throw new Error('Native configStore home/domain does not match the admitted owner.');
+      }
+    }
+    const capturedLogger = logger(context.logger);
+    const abortSignal = context.abortSignal;
+    if (abortSignal !== undefined) {
+      if (!(abortSignal instanceof AbortSignal)) throw new TypeError('Native abortSignal must be an AbortSignal.');
+      AbortSignal.prototype.throwIfAborted.call(abortSignal);
+    }
+    const captured = Object.freeze({ homeId, configStore: configStore as NoSqlConfigStore | undefined,
+      logger: capturedLogger, abortSignal: abortSignal as AbortSignal | undefined });
+    this.#homeId = homeId;
+    return captured;
+  }
+}