@rs-native-kit/version-check 0.1.2

package/src/data/config/ConfigResolutionPipeline.ts

@@ -0,0 +1,424 @@
+import { ConsoleLogSink } from '../../shared/logging/Logger';
+import { resolveConfigSync } from './ConfigLoader';
+import { CONFIG_ENVELOPE_MAX_BYTES } from './ConfigDocumentValidator';
+import type {
+  ConfigTier,
+  RawConfigDocument,
+  SignedConfigEnvelope,
+  TrustedKeySet,
+  VersionManagerConfigDocument,
+} from '../../domain/models/ConfigDocument';
+import {
+  BoundaryValidationException,
+  ConfigSizeLimitExceededException,
+  SchemaValidationException,
+  SignatureVerificationException,
+  UntrustedKeyIdException,
+  toVersionManagerException,
+} from '../../domain/errors/VersionManagerException';
+import type { VersionManagerException } from '../../domain/errors/VersionManagerException';
+import type {
+  IConfigCache,
+  IConfigValidator,
+  IEnvironmentOverrideSource,
+  ILocalConfigSource,
+  IRemoteConfigSource,
+  ISignatureVerifier,
+} from '../../domain/ports/IConfigSources';
+import type { IClock } from '../../domain/ports/IClock';
+import type {
+  ResolvedVersionManagerConfig,
+  VersionManagerOptions,
+} from '../../domain/models/VersionManagerOptions';
+
+export interface ConfigResolutionPipelineDeps {
+  readonly local: ILocalConfigSource;
+  readonly remote: IRemoteConfigSource;
+  readonly envOverrides: IEnvironmentOverrideSource;
+  readonly cache: IConfigCache;
+  readonly validator: IConfigValidator;
+  readonly signatureVerifier: ISignatureVerifier;
+  readonly clock: IClock;
+  /** §7.4 — default 5, configurable. */
+  readonly circuitBreakerThreshold?: number;
+  /** §7.4 cool-down window once the breaker trips. */
+  readonly circuitBreakerCooldownMs?: number;
+  readonly onError?: (error: VersionManagerException) => void;
+}
+
+export interface ConfigResolutionResult {
+  readonly config: ResolvedVersionManagerConfig;
+  readonly tier: ConfigTier;
+}
+
+/**
+ * Doc 03's ConfigResolutionPipeline — orchestrates §3.2 (schema -> boundary -> signature
+ * validation), §4.2 (per-field precedence merge, env > remote > local > default), §4.3
+ * (access path), §7.2 (cascading fallback), §7.3 (field vs whole-document fallback), and
+ * §7.4 (quarantine + circuit breaker). Lives in src/data/config/ per doc 03 §0.
+ */
+export class ConfigResolutionPipeline {
+  private readonly quarantinedFingerprints = new Set<string>();
+  private consecutiveRemoteFailures = 0;
+  private circuitOpenUntil = 0;
+
+  constructor(private readonly deps: ConfigResolutionPipelineDeps) {}
+
+  async resolve(
+    defaults: VersionManagerOptions
+  ): Promise<ConfigResolutionResult> {
+    // Tier 4 — always present, validated synchronously at configure()-time already by
+    // ConfigLoader.resolveConfigSync (doc 02 §1.3 fail-fast); re-run here defensively so
+    // this pipeline is safe to call standalone (e.g. from tests).
+    const tier4 = resolveConfigSync(defaults);
+    const trustedKeys: TrustedKeySet = {
+      algorithm: tier4.security.signatureAlgorithm,
+      keys: new Set(tier4.security.trustedKeyIds),
+    };
+
+    const [envelopeTier1, envelopeTier3] = await Promise.all([
+      this.deps.envOverrides.read().catch(() => ({})),
+      this.readLocal(trustedKeys),
+    ]);
+
+    const remoteResult = await this.readRemote(defaults, trustedKeys);
+
+    // §7.2 whole-tier cascade: if the remote tier failed outright, prefer the last known
+    // valid *fully resolved* config over recomputing fresh from local+default, so a
+    // network hiccup doesn't regress an app back to weaker settings every single check.
+    if (remoteResult.status === 'failed') {
+      const cached = await this.deps.cache.getLastValid().catch(() => null);
+      if (cached) {
+        return {
+          config: cached,
+          tier: 'remote' /* cache reflects a prior remote win */,
+        };
+      }
+    }
+
+    const tier2 = remoteResult.status === 'ok' ? remoteResult.payload : null;
+    const tier3 = envelopeTier3;
+
+    const merged = mergeConfig(tier4, tier3, tier2, envelopeTier1);
+    const tier: ConfigTier = tier2
+      ? 'remote'
+      : tier3
+        ? 'local'
+        : envelopeTier1 && Object.keys(envelopeTier1).length > 0
+          ? 'env'
+          : 'default';
+
+    await this.deps.cache.setLastValid(merged).catch(() => {
+      // Cache-write failures never block resolution (§7.2's guarantee is about read
+      // fallback; a write failure here just means the *next* remote outage won't have a
+      // warm cache to fall back to — already surfaced via CacheWriteException elsewhere).
+    });
+
+    return { config: merged, tier };
+  }
+
+  private async readLocal(
+    trustedKeys: TrustedKeySet
+  ): Promise<VersionManagerConfigDocument | null> {
+    const raw = await this.deps.local.read().catch(() => null);
+    if (raw === null || raw === undefined) return null;
+
+    const verified = await this.validateAndVerify(raw, 'local', trustedKeys);
+    return verified;
+  }
+
+  private async readRemote(
+    defaults: VersionManagerOptions,
+    trustedKeys: TrustedKeySet
+  ): Promise<
+    | { status: 'ok'; payload: VersionManagerConfigDocument }
+    | { status: 'absent' }
+    | { status: 'failed' }
+  > {
+    const url = defaults.remoteConfigUrl;
+    if (!url) return { status: 'absent' };
+
+    if (this.deps.clock.now() < this.circuitOpenUntil) {
+      // §7.4 circuit breaker: skip attempting remote fetch entirely during the cooldown.
+      return { status: 'failed' };
+    }
+
+    let raw: RawConfigDocument;
+    try {
+      raw = await this.deps.remote.fetch(url, {
+        timeoutMs: defaults.fallback?.requestTimeoutMs ?? 8_000,
+        headers: defaults.configSources?.remoteFetchHeaders,
+      });
+    } catch (error) {
+      this.recordRemoteFailure();
+      this.report(toVersionManagerException(error));
+      return { status: 'failed' };
+    }
+
+    const fingerprint = fingerprintOf(raw);
+    if (this.quarantinedFingerprints.has(fingerprint)) {
+      // §7.4: same bad bytes seen again within the session — fail silently (no
+      // re-validation, no re-logging) but still counts as a circuit-breaker failure.
+      this.recordRemoteFailure();
+      return { status: 'failed' };
+    }
+
+    const verified = await this.validateAndVerify(
+      raw,
+      'remote',
+      trustedKeys,
+      fingerprint
+    );
+    if (verified === null) {
+      this.recordRemoteFailure();
+      return { status: 'failed' };
+    }
+
+    this.consecutiveRemoteFailures = 0;
+    this.circuitOpenUntil = 0;
+    return { status: 'ok', payload: verified };
+  }
+
+  private recordRemoteFailure(): void {
+    this.consecutiveRemoteFailures++;
+    const threshold = this.deps.circuitBreakerThreshold ?? 5;
+    if (this.consecutiveRemoteFailures >= threshold) {
+      const cooldown = this.deps.circuitBreakerCooldownMs ?? 5 * 60_000;
+      this.circuitOpenUntil = this.deps.clock.now() + cooldown;
+    }
+  }
+
+  /**
+   * §3.2 sequence: schema -> boundary -> canonicalize -> verify signature. Returns the
+   * validated payload (with any boundary-failed fields stripped per §7.3's field-level
+   * fallback) or null if the whole document must be rejected (schema failure or
+   * signature failure — §7.3's whole-document fallback).
+   */
+  private async validateAndVerify(
+    raw: RawConfigDocument,
+    tier: 'local' | 'remote',
+    trustedKeys: TrustedKeySet,
+    fingerprint?: string
+  ): Promise<VersionManagerConfigDocument | null> {
+    const sizeCheck =
+      typeof raw === 'string' ? raw.length : JSON.stringify(raw).length;
+    if (sizeCheck > CONFIG_ENVELOPE_MAX_BYTES) {
+      this.report(
+        new ConfigSizeLimitExceededException({
+          message: `${tier} config envelope exceeds ${CONFIG_ENVELOPE_MAX_BYTES} bytes`,
+        })
+      );
+      return null;
+    }
+
+    const schemaResult = this.deps.validator.validateSchema(raw);
+    if (!schemaResult.valid) {
+      this.report(
+        new SchemaValidationException({
+          message: `${tier} config document failed schema validation: ${schemaResult.errors.join('; ')}`,
+          metadata: { tier, errors: schemaResult.errors },
+        })
+      );
+      return null; // whole-document fallback (§7.3)
+    }
+
+    const envelope = (
+      typeof raw === 'string' ? JSON.parse(raw) : raw
+    ) as SignedConfigEnvelope;
+
+    // Signature verification — required for remote always, required for local unless
+    // algorithm is "none" in a dev build (enforced inside SignatureVerifier, §3.1).
+    if (
+      envelope.signature.algorithm !== 'none' &&
+      !trustedKeys.keys.has(envelope.signature.keyId)
+    ) {
+      this.report(
+        new UntrustedKeyIdException({
+          message: `${tier} config signature.keyId "${envelope.signature.keyId}" is not in security.trustedKeyIds`,
+          metadata: { tier },
+        })
+      );
+      if (fingerprint) this.quarantinedFingerprints.add(fingerprint);
+      return null;
+    }
+
+    const sigResult = await this.deps.signatureVerifier.verify(
+      envelope,
+      trustedKeys
+    );
+    if (!sigResult.valid) {
+      this.report(
+        new SignatureVerificationException({
+          message: `${tier} config signature verification failed: ${sigResult.reason ?? 'unknown reason'}`,
+          metadata: { tier },
+        })
+      );
+      if (fingerprint) this.quarantinedFingerprints.add(fingerprint);
+      return null; // whole-document fallback (§7.3) — an untrusted signature taints every field
+    }
+
+    // §7.3 field-level fallback: only the offending fields are dropped, not the whole doc.
+    const boundaryResult = this.deps.validator.validateBoundaries(raw);
+    if (!boundaryResult.valid) {
+      this.report(
+        new BoundaryValidationException({
+          message: `${tier} config document failed boundary validation on: ${Array.from(boundaryResult.fieldErrors.keys()).join(', ')}`,
+          metadata: {
+            tier,
+            fields: Array.from(boundaryResult.fieldErrors.entries()),
+          },
+        })
+      );
+      return stripFields(envelope.payload, boundaryResult.fieldErrors);
+    }
+
+    return envelope.payload;
+  }
+
+  private report(error: VersionManagerException): void {
+    if (this.deps.onError) {
+      this.deps.onError(error);
+    } else {
+      new ConsoleLogSink().write({
+        level: 'error',
+        message: error.message,
+        timestamp: this.deps.clock.now(),
+        metadata: { code: error.code },
+      });
+    }
+  }
+}
+
+function fingerprintOf(raw: RawConfigDocument): string {
+  const str = typeof raw === 'string' ? raw : JSON.stringify(raw);
+  // Cheap non-cryptographic fingerprint — this is a quarantine dedupe key, not a
+  // security boundary (signature verification is what actually protects integrity).
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    hash = (Math.imul(31, hash) + str.charCodeAt(i)) | 0;
+  }
+  return `${str.length}:${hash}`;
+}
+
+function stripFields(
+  payload: VersionManagerConfigDocument,
+  fieldErrors: ReadonlyMap<string, string>
+): VersionManagerConfigDocument {
+  const clone: Record<string, unknown> = JSON.parse(JSON.stringify(payload));
+  for (const path of fieldErrors.keys()) {
+    const segments = path.split('.');
+    let cursor: Record<string, unknown> = clone;
+    for (let i = 0; i < segments.length - 1; i++) {
+      const next = cursor[segments[i] as string];
+      if (typeof next !== 'object' || next === null) break;
+      cursor = next as Record<string, unknown>;
+    }
+    delete cursor[segments[segments.length - 1] as string];
+  }
+  return clone as VersionManagerConfigDocument;
+}
+
+function firstDefined<T>(...values: (T | undefined | null)[]): T | undefined {
+  for (const v of values) {
+    if (v !== undefined && v !== null) return v;
+  }
+  return undefined;
+}
+
+/**
+ * Doc 03 §4.2 precedence matrix — per-field deep merge, honoring which tiers each field
+ * group is eligible to appear in (not every field accepts every tier; e.g. env never
+ * overrides cache.storage or stores.*, and security.* is tier-4-only).
+ */
+function mergeConfig(
+  tier4: ResolvedVersionManagerConfig,
+  tier3: VersionManagerConfigDocument | null,
+  tier2: VersionManagerConfigDocument | null,
+  tier1: Partial<VersionManagerConfigDocument>
+): ResolvedVersionManagerConfig {
+  return {
+    appVersion:
+      firstDefined(tier1.localVersionIdentifier, tier4.appVersion) ?? null,
+    logging: tier4.logging,
+    cache: {
+      ttlMs:
+        firstDefined(
+          tier1.cache?.ttlMs,
+          tier2?.cache?.ttlMs,
+          tier3?.cache?.ttlMs,
+          tier4.cache.ttlMs
+        ) ?? 21_600_000,
+      storage:
+        firstDefined(
+          tier2?.cache?.storage,
+          tier3?.cache?.storage,
+          tier4.cache.storage
+        ) ?? 'persistent',
+      bustOnManualCheck: tier4.cache.bustOnManualCheck,
+    },
+    fallback: {
+      onNetworkError: tier4.fallback.onNetworkError,
+      defaultConfig: tier4.fallback.defaultConfig,
+      requestTimeoutMs:
+        firstDefined(
+          tier1.network?.requestTimeoutMs,
+          tier2?.network?.requestTimeoutMs,
+          tier3?.network?.requestTimeoutMs,
+          tier4.fallback.requestTimeoutMs
+        ) ?? 8_000,
+      retry: {
+        maxAttempts:
+          firstDefined(
+            tier1.network?.retry?.maxAttempts,
+            tier2?.network?.retry?.maxAttempts,
+            tier3?.network?.retry?.maxAttempts,
+            tier4.fallback.retry.maxAttempts
+          ) ?? 3,
+        backoff:
+          firstDefined(
+            tier2?.network?.retry?.backoff,
+            tier3?.network?.retry?.backoff,
+            tier4.fallback.retry.backoff
+          ) ?? 'exponential-jitter',
+        baseDelayMs:
+          firstDefined(
+            tier1.network?.retry?.baseDelayMs,
+            tier2?.network?.retry?.baseDelayMs,
+            tier3?.network?.retry?.baseDelayMs,
+            tier4.fallback.retry.baseDelayMs
+          ) ?? 500,
+      },
+    },
+    stores: firstDefined(tier2?.stores, tier3?.stores) ?? tier4.stores,
+    policy: {
+      forceUpdateBelow:
+        firstDefined(
+          tier1.alerts?.forceUpdateBelow,
+          tier2?.alerts?.forceUpdateBelow,
+          tier3?.alerts?.forceUpdateBelow,
+          tier4.policy.forceUpdateBelow ?? undefined
+        ) ?? null,
+      reminderIntervalMs:
+        firstDefined(
+          tier1.alerts?.reminderDelayMs,
+          tier2?.alerts?.reminderDelayMs,
+          tier3?.alerts?.reminderDelayMs,
+          tier4.policy.reminderIntervalMs
+        ) ?? 259_200_000,
+      rolloutPercentage: tier4.policy.rolloutPercentage,
+    },
+    strictReadiness: tier4.strictReadiness,
+    remoteConfigUrl:
+      firstDefined(tier1.remoteConfigUrl, tier4.remoteConfigUrl ?? undefined) ??
+      null,
+    // security.* is tier-4-only, never overridden by a loaded document (§4.2).
+    security: tier4.security,
+    schemaVersion:
+      firstDefined(
+        tier1.schemaVersion,
+        tier2?.schemaVersion,
+        tier3?.schemaVersion,
+        tier4.schemaVersion
+      ) ?? '1.0',
+  };
+}

package/src/data/config/ConfigValidator.ts

@@ -0,0 +1,79 @@
+import { parseVersion } from '../../domain/engines/semver/SemVerEngine';
+import { InvalidConfigException } from '../../domain/errors/VersionManagerException';
+import type { VersionManagerOptions } from '../../domain/models/VersionManagerOptions';
+
+/**
+ * Boundary validation (Prompt 3 §2.2) for the "default fallback" config tier — the
+ * VersionManagerOptions object passed to configure(). Full JSON-Schema structural
+ * validation and signature verification for local/remote config documents (Prompt 3
+ * §2.1, §3) are scoped to the not-yet-built config-document pipeline; see
+ * docs/architecture/03-configuration-system.md.
+ */
+export function validateOptions(options: VersionManagerOptions): void {
+  if (!options.stores || Object.keys(options.stores).length === 0) {
+    throw new InvalidConfigException({
+      message:
+        'VersionManagerOptions.stores must configure at least one store (ios/android/huawei/amazon/custom)',
+    });
+  }
+
+  if (options.appVersion !== undefined) {
+    try {
+      parseVersion(options.appVersion);
+    } catch (error) {
+      throw new InvalidConfigException({
+        message: `options.appVersion "${options.appVersion}" is not a valid SemVer string`,
+        cause: error,
+      });
+    }
+  }
+
+  if (options.policy?.forceUpdateBelow !== undefined) {
+    try {
+      parseVersion(options.policy.forceUpdateBelow);
+    } catch (error) {
+      throw new InvalidConfigException({
+        message: `options.policy.forceUpdateBelow "${options.policy.forceUpdateBelow}" is not a valid SemVer string`,
+        cause: error,
+      });
+    }
+  }
+
+  const timeoutMs = options.fallback?.requestTimeoutMs;
+  if (timeoutMs !== undefined && timeoutMs <= 0) {
+    throw new InvalidConfigException({
+      message: 'options.fallback.requestTimeoutMs must be greater than 0',
+    });
+  }
+
+  const ttlMs = options.cache?.ttlMs;
+  if (ttlMs !== undefined && ttlMs < 0) {
+    throw new InvalidConfigException({
+      message: 'options.cache.ttlMs must be >= 0',
+    });
+  }
+
+  const maxAttempts = options.fallback?.retry?.maxAttempts;
+  if (maxAttempts !== undefined && (maxAttempts < 0 || maxAttempts > 10)) {
+    throw new InvalidConfigException({
+      message: 'options.fallback.retry.maxAttempts must be between 0 and 10',
+    });
+  }
+
+  const baseDelayMs = options.fallback?.retry?.baseDelayMs;
+  if (baseDelayMs !== undefined && baseDelayMs <= 0) {
+    throw new InvalidConfigException({
+      message: 'options.fallback.retry.baseDelayMs must be greater than 0',
+    });
+  }
+
+  const rolloutPercentage = options.policy?.rolloutPercentage;
+  if (
+    rolloutPercentage !== undefined &&
+    (rolloutPercentage < 0 || rolloutPercentage > 100)
+  ) {
+    throw new InvalidConfigException({
+      message: 'options.policy.rolloutPercentage must be between 0 and 100',
+    });
+  }
+}

package/src/data/config/SignatureVerifier.ts

@@ -0,0 +1,90 @@
+import { canonicalize, utf8ToBase64 } from './canonicalize';
+import type {
+  SignatureVerificationResult,
+  SignedConfigEnvelope,
+  TrustedKeySet,
+} from '../../domain/models/ConfigDocument';
+import type { ICryptoProvider } from '../../domain/ports/IPlatformBridge';
+import type { ISignatureVerifier } from '../../domain/ports/IConfigSources';
+
+declare const __DEV__: boolean | undefined;
+
+function isDev(): boolean {
+  return typeof __DEV__ !== 'undefined' && __DEV__ === true;
+}
+
+/**
+ * Doc 03 §3.2/§3.4 — verification calls are implemented using OS-provided cryptography
+ * exclusively (iOS CryptoKit/Security.framework, Android java.security), reached through
+ * IPlatformBridge.crypto (ICryptoProvider) so this class never itself hand-rolls
+ * cryptographic primitives (Prompt 1 §9.3's zero-external-dependency constraint extends
+ * to "don't implement crypto in JS either" — only OS APIs are trusted for this).
+ */
+export class SignatureVerifier implements ISignatureVerifier {
+  constructor(private readonly crypto?: ICryptoProvider) {}
+
+  async verify(
+    envelope: SignedConfigEnvelope,
+    trustedKeys: TrustedKeySet
+  ): Promise<SignatureVerificationResult> {
+    const { algorithm, keyId, value } = envelope.signature;
+
+    // §3.1: algorithm "none" is permitted only for the local bundled document in
+    // development builds — rejected for any remote fetch and for release builds,
+    // enforced here regardless of what security.signatureAlgorithm claims (a
+    // compromised document cannot downgrade its own algorithm to "none" and be
+    // believed). The pipeline is responsible for only calling verify() with a "none"
+    // envelope on the local-dev path in the first place; this is a defense-in-depth
+    // second check.
+    if (algorithm === 'none') {
+      if (!isDev()) {
+        return {
+          valid: false,
+          reason:
+            'signature.algorithm "none" is rejected outside development builds',
+        };
+      }
+      return { valid: true };
+    }
+
+    if (trustedKeys.algorithm !== algorithm) {
+      return {
+        valid: false,
+        reason: `Envelope algorithm "${algorithm}" does not match configured security.signatureAlgorithm "${trustedKeys.algorithm}"`,
+      };
+    }
+
+    if (!trustedKeys.keys.has(keyId)) {
+      return {
+        valid: false,
+        reason: `keyId "${keyId}" is not present in security.trustedKeyIds`,
+      };
+    }
+
+    if (!this.crypto) {
+      return {
+        valid: false,
+        reason:
+          'No ICryptoProvider available on the active IPlatformBridge — cannot verify signatures on this target',
+      };
+    }
+
+    const canonicalPayload = canonicalize(envelope.payload);
+    const messageBase64 = utf8ToBase64(canonicalPayload);
+
+    try {
+      const valid =
+        algorithm === 'ed25519'
+          ? await this.crypto.verifyEd25519(keyId, messageBase64, value)
+          : await this.crypto.verifyHmacSha256(keyId, messageBase64, value);
+      return valid
+        ? { valid: true }
+        : { valid: false, reason: 'Signature mismatch' };
+    } catch (error) {
+      return {
+        valid: false,
+        reason: `Native signature verification threw: ${String(error)}`,
+      };
+    }
+  }
+}

package/src/data/config/canonicalize.ts

@@ -0,0 +1,111 @@
+/**
+ * Hand-rolled canonicalizer (Prompt 1 §9.3 zero-dependency constraint), implementing the
+ * same principles as RFC 8785 (JSON Canonicalization Scheme) that doc 03 §3.3 calls for:
+ * recursive key sorting by UTF-16 code unit order, fixed number formatting, no
+ * insignificant whitespace. Signatures are computed/verified over this canonical byte
+ * form so that whitespace/key-order differences in transit never invalidate a
+ * legitimately signed document.
+ */
+
+type JsonValue =
+  null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+
+function canonicalizeValue(value: JsonValue): string {
+  if (value === null) return 'null';
+
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+
+  if (typeof value === 'number') return canonicalizeNumber(value);
+
+  if (typeof value === 'string') return JSON.stringify(value);
+
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalizeValue).join(',')}]`;
+  }
+
+  // Recursive key sorting, UTF-16 code unit order (default JS string `<` comparison).
+  const keys = Object.keys(value).sort();
+  const members = keys.map(
+    (key) =>
+      `${JSON.stringify(key)}:${canonicalizeValue(value[key] as JsonValue)}`
+  );
+  return `{${members.join(',')}}`;
+}
+
+/**
+ * Fixed number formatting per RFC 8785 §3.2.2.3 (simplified): integers render without a
+ * decimal point/exponent; this codebase's config schema (doc 03 §6) only ever contains
+ * integers and no fractional/exponential numeric fields, so the full ECMA-262
+ * Number::toString algorithm RFC 8785 mandates is unnecessary here.
+ */
+function canonicalizeNumber(value: number): string {
+  if (!Number.isFinite(value)) {
+    throw new Error('Cannot canonicalize a non-finite number');
+  }
+  if (Number.isInteger(value)) return String(value);
+  return String(value);
+}
+
+/** Canonical byte sequence (as a UTF-8 string) for the given JSON-compatible value. */
+export function canonicalize(value: unknown): string {
+  return canonicalizeValue(value as JsonValue);
+}
+
+/** Base64 encoding of the UTF-8 bytes of a string, without relying on Node's Buffer. */
+export function utf8ToBase64(input: string): string {
+  if (typeof btoa === 'function' && typeof TextEncoder !== 'undefined') {
+    const bytes = new TextEncoder().encode(input);
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i] as number);
+    }
+    return btoa(binary);
+  }
+  // React Native's Hermes engine provides global Buffer via a polyfill in most RN
+  // setups, but not guaranteed — fall back to a minimal hand-rolled base64 encoder.
+  return manualUtf8ToBase64(input);
+}
+
+const BASE64_CHARS =
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+function manualUtf8ToBase64(input: string): string {
+  const bytes: number[] = [];
+  for (let i = 0; i < input.length; i++) {
+    let code = input.codePointAt(i) as number;
+    if (code > 0xffff) i++; // consumed a surrogate pair
+    if (code < 0x80) {
+      bytes.push(code);
+    } else if (code < 0x800) {
+      bytes.push(0xc0 | (code >> 6), 0x80 | (code & 0x3f));
+    } else if (code < 0x10000) {
+      bytes.push(
+        0xe0 | (code >> 12),
+        0x80 | ((code >> 6) & 0x3f),
+        0x80 | (code & 0x3f)
+      );
+    } else {
+      bytes.push(
+        0xf0 | (code >> 18),
+        0x80 | ((code >> 12) & 0x3f),
+        0x80 | ((code >> 6) & 0x3f),
+        0x80 | (code & 0x3f)
+      );
+    }
+  }
+
+  let output = '';
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i] as number;
+    const b1 = bytes[i + 1];
+    const b2 = bytes[i + 2];
+    output += BASE64_CHARS[b0 >> 2];
+    output += BASE64_CHARS[((b0 & 0x03) << 4) | ((b1 ?? 0) >> 4)];
+    output +=
+      b1 === undefined
+        ? '='
+        : BASE64_CHARS[((b1 & 0x0f) << 2) | ((b2 ?? 0) >> 6)];
+    output += b2 === undefined ? '=' : BASE64_CHARS[b2 & 0x3f];
+  }
+  return output;
+}