@rs-native-kit/version-check 0.1.2

package/src/data/config/ConfigDocumentValidator.ts

@@ -0,0 +1,309 @@
+import { parseVersion } from '../../domain/engines/semver/SemVerEngine';
+import type {
+  BoundaryValidationResult,
+  RawConfigDocument,
+  SchemaValidationResult,
+} from '../../domain/models/ConfigDocument';
+import type { IConfigValidator } from '../../domain/ports/IConfigSources';
+
+/** Doc 03 §2.2 — serialized document size cap, enforced before parsing even begins. */
+export const CONFIG_ENVELOPE_MAX_BYTES = 64 * 1024;
+
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/;
+const HTTPS_URL_PATTERN = /^https:\/\//;
+const APP_STORE_ID_PATTERN = /^[0-9]{6,12}$/;
+const ANDROID_PACKAGE_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/;
+const AMAZON_ASIN_PATTERN = /^[A-Z0-9]{10}$/;
+const HUAWEI_APP_ID_PATTERN = /^[0-9]{6,12}$/;
+const SCHEMA_VERSION_PATTERN = /^\d+\.\d+$/;
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Hand-rolled, zero-dependency structural validator (Prompt 1 §9.3 — no ajv) that walks
+ * a SignedConfigEnvelope against the JSON Schema in doc 03 §6: required-field presence,
+ * type checks, enum membership, and additionalProperties:false at every level (unknown
+ * fields are rejected, not silently ignored — §2.1's downgrade-attack rationale).
+ */
+export class ConfigDocumentValidator implements IConfigValidator {
+  validateSchema(doc: RawConfigDocument): SchemaValidationResult {
+    const errors: string[] = [];
+
+    if (typeof doc === 'string' && doc.length > CONFIG_ENVELOPE_MAX_BYTES) {
+      // Cheap byte-length check that short-circuits pathological payloads (§2.2, VM-1007
+      // is raised by the caller — this method only reports the schema-shape verdict).
+      errors.push(
+        `Envelope exceeds ${CONFIG_ENVELOPE_MAX_BYTES} bytes before parsing`
+      );
+      return { valid: false, errors };
+    }
+
+    let envelope: unknown = doc;
+    if (typeof doc === 'string') {
+      try {
+        envelope = JSON.parse(doc);
+      } catch (error) {
+        return {
+          valid: false,
+          errors: [`Envelope is not valid JSON: ${String(error)}`],
+        };
+      }
+    }
+
+    if (!isPlainObject(envelope)) {
+      return { valid: false, errors: ['Envelope must be a JSON object'] };
+    }
+
+    this.checkAdditionalProperties(
+      envelope,
+      ['schemaVersion', 'payload', 'signature'],
+      'envelope',
+      errors
+    );
+    this.requireField(envelope, 'schemaVersion', 'string', errors, 'envelope');
+    this.requireField(envelope, 'payload', 'object', errors, 'envelope');
+    this.requireField(envelope, 'signature', 'object', errors, 'envelope');
+
+    if (
+      typeof envelope.schemaVersion === 'string' &&
+      !SCHEMA_VERSION_PATTERN.test(envelope.schemaVersion)
+    ) {
+      errors.push('envelope.schemaVersion must match ^\\d+\\.\\d+$');
+    }
+
+    if (isPlainObject(envelope.signature)) {
+      const sig = envelope.signature;
+      this.checkAdditionalProperties(
+        sig,
+        ['algorithm', 'keyId', 'value', 'signedAt'],
+        'signature',
+        errors
+      );
+      this.requireField(sig, 'algorithm', 'string', errors, 'signature');
+      this.requireField(sig, 'keyId', 'string', errors, 'signature');
+      this.requireField(sig, 'value', 'string', errors, 'signature');
+      this.requireField(sig, 'signedAt', 'string', errors, 'signature');
+      if (
+        typeof sig.algorithm === 'string' &&
+        !['ed25519', 'hmac-sha256', 'none'].includes(sig.algorithm)
+      ) {
+        errors.push(
+          'signature.algorithm must be one of ed25519 | hmac-sha256 | none'
+        );
+      }
+    }
+
+    if (isPlainObject(envelope.payload)) {
+      this.validatePayloadShape(envelope.payload, errors);
+    }
+
+    return { valid: errors.length === 0, errors };
+  }
+
+  validateBoundaries(doc: RawConfigDocument): BoundaryValidationResult {
+    const fieldErrors = new Map<string, string>();
+    const envelope =
+      typeof doc === 'string'
+        ? safeParse(doc)
+        : (doc as Record<string, unknown>);
+    const payload = isPlainObject(envelope)
+      ? (envelope.payload as Record<string, unknown> | undefined)
+      : undefined;
+
+    if (!isPlainObject(payload)) {
+      return { valid: true, fieldErrors };
+    }
+
+    const network = payload.network as Record<string, unknown> | undefined;
+    if (isPlainObject(network)) {
+      const timeout = network.requestTimeoutMs;
+      if (typeof timeout === 'number' && timeout <= 0) {
+        fieldErrors.set('network.requestTimeoutMs', 'must be > 0');
+      }
+      const retry = network.retry as Record<string, unknown> | undefined;
+      if (isPlainObject(retry)) {
+        const maxAttempts = retry.maxAttempts;
+        if (
+          typeof maxAttempts === 'number' &&
+          (maxAttempts < 0 || maxAttempts > 10)
+        ) {
+          fieldErrors.set(
+            'network.retry.maxAttempts',
+            'must be between 0 and 10'
+          );
+        }
+        const baseDelayMs = retry.baseDelayMs;
+        if (typeof baseDelayMs === 'number' && baseDelayMs <= 0) {
+          fieldErrors.set('network.retry.baseDelayMs', 'must be > 0');
+        }
+      }
+    }
+
+    const cache = payload.cache as Record<string, unknown> | undefined;
+    if (
+      isPlainObject(cache) &&
+      typeof cache.ttlMs === 'number' &&
+      cache.ttlMs < 0
+    ) {
+      fieldErrors.set('cache.ttlMs', 'must be >= 0');
+    }
+
+    if (
+      typeof payload.localVersionIdentifier === 'string' &&
+      !this.isValidSemVer(payload.localVersionIdentifier)
+    ) {
+      fieldErrors.set('localVersionIdentifier', 'not a valid SemVer string');
+    }
+
+    const alerts = payload.alerts as Record<string, unknown> | undefined;
+    if (
+      isPlainObject(alerts) &&
+      typeof alerts.forceUpdateBelow === 'string' &&
+      !this.isValidSemVer(alerts.forceUpdateBelow)
+    ) {
+      fieldErrors.set('alerts.forceUpdateBelow', 'not a valid SemVer string');
+    }
+
+    if (
+      typeof payload.remoteConfigUrl === 'string' &&
+      !HTTPS_URL_PATTERN.test(payload.remoteConfigUrl)
+    ) {
+      fieldErrors.set('remoteConfigUrl', 'must use https://');
+    }
+
+    const stores = payload.stores as Record<string, unknown> | undefined;
+    if (isPlainObject(stores)) {
+      this.checkStoreShape(
+        stores,
+        'ios',
+        'appStoreId',
+        APP_STORE_ID_PATTERN,
+        fieldErrors
+      );
+      this.checkStoreShape(
+        stores,
+        'android',
+        'packageName',
+        ANDROID_PACKAGE_PATTERN,
+        fieldErrors
+      );
+      this.checkStoreShape(
+        stores,
+        'huawei',
+        'appId',
+        HUAWEI_APP_ID_PATTERN,
+        fieldErrors
+      );
+      this.checkStoreShape(
+        stores,
+        'amazon',
+        'asin',
+        AMAZON_ASIN_PATTERN,
+        fieldErrors
+      );
+      const custom = stores.custom as Record<string, unknown> | undefined;
+      if (
+        isPlainObject(custom) &&
+        typeof custom.url === 'string' &&
+        !HTTPS_URL_PATTERN.test(custom.url)
+      ) {
+        fieldErrors.set('stores.custom.url', 'must use https://');
+      }
+    }
+
+    return { valid: fieldErrors.size === 0, fieldErrors };
+  }
+
+  private isValidSemVer(v: string): boolean {
+    if (!SEMVER_PATTERN.test(v)) return false;
+    try {
+      parseVersion(v);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private checkStoreShape(
+    stores: Record<string, unknown>,
+    key: string,
+    field: string,
+    pattern: RegExp,
+    fieldErrors: Map<string, string>
+  ): void {
+    const entry = stores[key] as Record<string, unknown> | undefined;
+    if (isPlainObject(entry) && typeof entry[field] === 'string') {
+      const value = entry[field] as string;
+      if (!pattern.test(value)) {
+        fieldErrors.set(
+          `stores.${key}.${field}`,
+          `"${value}" has invalid shape`
+        );
+      }
+    }
+  }
+
+  private validatePayloadShape(
+    payload: Record<string, unknown>,
+    errors: string[]
+  ): void {
+    this.checkAdditionalProperties(
+      payload,
+      [
+        'localVersionIdentifier',
+        'remoteConfigUrl',
+        'cache',
+        'network',
+        'alerts',
+        'stores',
+        'security',
+        'schemaVersion',
+      ],
+      'payload',
+      errors
+    );
+  }
+
+  private requireField(
+    obj: Record<string, unknown>,
+    field: string,
+    type: 'string' | 'object',
+    errors: string[],
+    context: string
+  ): void {
+    const value = obj[field];
+    if (value === undefined) {
+      errors.push(`${context}.${field} is required`);
+      return;
+    }
+    if (type === 'string' && typeof value !== 'string') {
+      errors.push(`${context}.${field} must be a string`);
+    }
+    if (type === 'object' && !isPlainObject(value)) {
+      errors.push(`${context}.${field} must be an object`);
+    }
+  }
+
+  private checkAdditionalProperties(
+    obj: Record<string, unknown>,
+    allowed: string[],
+    context: string,
+    errors: string[]
+  ): void {
+    for (const key of Object.keys(obj)) {
+      if (!allowed.includes(key)) {
+        errors.push(`${context}.${key} is not a recognized field`);
+      }
+    }
+  }
+}
+
+function safeParse(input: string): unknown {
+  try {
+    return JSON.parse(input);
+  } catch {
+    return null;
+  }
+}

package/src/data/config/ConfigLoader.ts

@@ -0,0 +1,105 @@
+import type { ConfigLoadRequest } from '../../domain/models/ConfigDocument';
+import type { IConfigProvider } from '../../domain/ports/IConfigProvider';
+import type { Unsubscribe } from '../../domain/models/Unsubscribe';
+import type {
+  ResolvedVersionManagerConfig,
+  VersionManagerOptions,
+} from '../../domain/models/VersionManagerOptions';
+import { ConsoleLogSink } from '../../shared/logging/Logger';
+import type { ConfigResolutionPipeline } from './ConfigResolutionPipeline';
+import { validateOptions } from './ConfigValidator';
+
+/**
+ * Synchronous default-merge (doc 03 §4.2 tier 4 only). Kept as a plain function, not
+ * just a method on ConfigLoader, so the DI composition root (src/di/container.ts) can
+ * validate + resolve synchronously at configure()-time (doc 02 §1.3's fail-fast
+ * requirement) without awaiting a Promise, and so ConfigResolutionPipeline can call it
+ * as its always-valid tier-4 floor (doc 03 §7.2's termination guarantee).
+ */
+export function resolveConfigSync(
+  defaults: VersionManagerOptions
+): ResolvedVersionManagerConfig {
+  validateOptions(defaults);
+
+  return {
+    appVersion: defaults.appVersion ?? null,
+    logging: {
+      level: defaults.logging?.level ?? 'warn',
+      sink: defaults.logging?.sink ?? new ConsoleLogSink(),
+    },
+    cache: {
+      ttlMs: defaults.cache?.ttlMs ?? 21_600_000,
+      storage: defaults.cache?.storage ?? 'persistent',
+      bustOnManualCheck: defaults.cache?.bustOnManualCheck ?? true,
+    },
+    fallback: {
+      onNetworkError: defaults.fallback?.onNetworkError ?? 'useCache',
+      defaultConfig: defaults.fallback?.defaultConfig ?? null,
+      requestTimeoutMs: defaults.fallback?.requestTimeoutMs ?? 8_000,
+      retry: {
+        maxAttempts: defaults.fallback?.retry?.maxAttempts ?? 3,
+        backoff: defaults.fallback?.retry?.backoff ?? 'exponential-jitter',
+        baseDelayMs: defaults.fallback?.retry?.baseDelayMs ?? 500,
+      },
+    },
+    stores: defaults.stores,
+    policy: {
+      forceUpdateBelow: defaults.policy?.forceUpdateBelow ?? null,
+      reminderIntervalMs: defaults.policy?.reminderIntervalMs ?? 259_200_000,
+      rolloutPercentage: defaults.policy?.rolloutPercentage ?? 100,
+    },
+    strictReadiness: defaults.strictReadiness ?? false,
+    remoteConfigUrl: defaults.remoteConfigUrl ?? null,
+    security: {
+      signatureAlgorithm: defaults.security?.signatureAlgorithm ?? 'none',
+      trustedKeyIds: defaults.security?.trustedKeyIds ?? [],
+    },
+    schemaVersion: '1.0',
+  };
+}
+
+/**
+ * Doc 03 §0's IConfigProvider implementation — thin wrapper around
+ * ConfigResolutionPipeline that adds change-detection so subscribe() only fires when a
+ * later resolution actually differs from the last one (§4.4 hot-update contract).
+ */
+export class ConfigLoader implements IConfigProvider {
+  private readonly listeners = new Set<
+    (config: ResolvedVersionManagerConfig) => void
+  >();
+  private lastResolved: ResolvedVersionManagerConfig | null = null;
+
+  constructor(private readonly pipeline?: ConfigResolutionPipeline) {}
+
+  async resolve(
+    defaults: VersionManagerOptions
+  ): Promise<ResolvedVersionManagerConfig> {
+    const config = this.pipeline
+      ? (await this.pipeline.resolve(defaults)).config
+      : resolveConfigSync(defaults);
+
+    const changed =
+      this.lastResolved !== null &&
+      JSON.stringify(this.lastResolved) !== JSON.stringify(config);
+    this.lastResolved = config;
+    if (changed) {
+      for (const listener of Array.from(this.listeners)) listener(config);
+    }
+    return config;
+  }
+
+  async load(
+    request: ConfigLoadRequest
+  ): Promise<ResolvedVersionManagerConfig> {
+    return this.resolve(request.defaults);
+  }
+
+  subscribe(
+    listener: (config: ResolvedVersionManagerConfig) => void
+  ): Unsubscribe {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+}

package/src/data/config/ConfigProvider.ts

@@ -0,0 +1,84 @@
+import { ConfigResolutionPipeline } from './ConfigResolutionPipeline';
+import type { ConfigResolutionPipelineDeps } from './ConfigResolutionPipeline';
+import type { ConfigLoadRequest } from '../../domain/models/ConfigDocument';
+import type { IConfigProvider } from '../../domain/ports/IConfigProvider';
+import type { Unsubscribe } from '../../domain/ports/IPlatformBridge';
+import type {
+  ResolvedVersionManagerConfig,
+  VersionManagerOptions,
+} from '../../domain/models/VersionManagerOptions';
+
+export interface ConfigProviderDeps extends ConfigResolutionPipelineDeps {
+  /** Background remote-refresh cadence for subscribe() (doc 03 §4.4). 0/undefined disables polling — resolve() still works. */
+  readonly refreshIntervalMs?: number;
+}
+
+/**
+ * IConfigProvider adapter around ConfigResolutionPipeline — resolve()/load() delegate
+ * straight through, and subscribe() adds the doc 03 §4.4 "hot-update" behavior the raw
+ * pipeline doesn't provide on its own: a background poll that re-runs resolution and
+ * notifies listeners only when the resolved config actually changed.
+ */
+export class ConfigProvider implements IConfigProvider {
+  private readonly pipeline: ConfigResolutionPipeline;
+  private readonly refreshIntervalMs: number;
+  private readonly listeners = new Set<
+    (config: ResolvedVersionManagerConfig) => void
+  >();
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private lastConfig: ResolvedVersionManagerConfig | null = null;
+  private lastOptions: VersionManagerOptions | null = null;
+
+  constructor(deps: ConfigProviderDeps) {
+    this.pipeline = new ConfigResolutionPipeline(deps);
+    this.refreshIntervalMs = deps.refreshIntervalMs ?? 0;
+  }
+
+  async resolve(
+    defaults: VersionManagerOptions
+  ): Promise<ResolvedVersionManagerConfig> {
+    this.lastOptions = defaults;
+    const { config } = await this.pipeline.resolve(defaults);
+    this.lastConfig = config;
+    return config;
+  }
+
+  load(request: ConfigLoadRequest): Promise<ResolvedVersionManagerConfig> {
+    return this.resolve(request.defaults);
+  }
+
+  subscribe(
+    listener: (config: ResolvedVersionManagerConfig) => void
+  ): Unsubscribe {
+    this.listeners.add(listener);
+    this.ensurePolling();
+    return () => {
+      this.listeners.delete(listener);
+      if (this.listeners.size === 0 && this.timer) {
+        clearInterval(this.timer);
+        this.timer = null;
+      }
+    };
+  }
+
+  private ensurePolling(): void {
+    if (this.timer || this.refreshIntervalMs <= 0 || !this.lastOptions) return;
+    this.timer = setInterval(() => {
+      void this.refresh();
+    }, this.refreshIntervalMs);
+  }
+
+  private async refresh(): Promise<void> {
+    if (!this.lastOptions) return;
+    // A background poll tick must never surface as an unhandled rejection — the
+    // pipeline already reports validation/network failures via its own onError hook.
+    const result = await this.pipeline
+      .resolve(this.lastOptions)
+      .catch(() => null);
+    if (!result) return;
+    if (JSON.stringify(result.config) === JSON.stringify(this.lastConfig))
+      return;
+    this.lastConfig = result.config;
+    for (const listener of this.listeners) listener(result.config);
+  }
+}