@rs-native-kit/version-check 0.1.2

package/src/platform/native/NativePlatformBridge.ts

@@ -0,0 +1,179 @@
+import { AppState, Platform } from 'react-native';
+import {
+  OfflineException,
+  RequestTimeoutException,
+} from '../../domain/errors/VersionManagerException';
+import type { PlatformId } from '../../domain/models/PlatformId';
+import type {
+  BackgroundTaskDescriptor,
+  HttpRequest,
+  HttpResponse,
+  IAppInfoProvider,
+  IAppLifecycleObserver,
+  IBackgroundScheduler,
+  ICryptoProvider,
+  IDeviceInfoProvider,
+  IHttpClient,
+  IKeyValueStorage,
+  IPlatformBridge,
+  ISecureStorage,
+  Unsubscribe,
+} from '../../domain/ports/IPlatformBridge';
+import NativeVersionCheck from './NativeVersionCheck';
+
+class RnHttpClient implements IHttpClient {
+  async request(req: HttpRequest): Promise<HttpResponse> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), req.timeoutMs);
+    try {
+      const response = await fetch(req.url, {
+        method: req.method,
+        headers: req.headers,
+        body: req.body,
+        signal: controller.signal,
+      });
+      const headers: Record<string, string> = {};
+      response.headers.forEach((value, key) => {
+        headers[key] = value;
+      });
+      const body = await response.text();
+      return { status: response.status, headers, body };
+    } catch (error) {
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new RequestTimeoutException({
+          message: `Request to "${req.url}" timed out after ${req.timeoutMs}ms`,
+          cause: error,
+        });
+      }
+      throw new OfflineException({
+        message: `Request to "${req.url}" failed`,
+        cause: error,
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+}
+
+class RnKeyValueStorage implements IKeyValueStorage {
+  async get(key: string): Promise<string | null> {
+    return NativeVersionCheck().storageGet(key);
+  }
+  async set(key: string, value: string): Promise<void> {
+    await NativeVersionCheck().storageSet(key, value);
+  }
+  async remove(key: string): Promise<void> {
+    await NativeVersionCheck().storageRemove(key);
+  }
+}
+
+class RnSecureStorage implements ISecureStorage {
+  async getItem(key: string): Promise<string | null> {
+    return NativeVersionCheck().secureStorageGet(key);
+  }
+  async setItem(key: string, value: string): Promise<void> {
+    await NativeVersionCheck().secureStorageSet(key, value);
+  }
+  async removeItem(key: string): Promise<void> {
+    await NativeVersionCheck().secureStorageRemove(key);
+  }
+}
+
+class RnAppInfoProvider implements IAppInfoProvider {
+  async getCurrentVersion(): Promise<string> {
+    return NativeVersionCheck().getCurrentAppVersion();
+  }
+  async getBuildNumber(): Promise<string> {
+    return NativeVersionCheck().getBuildNumber();
+  }
+  async getBundleId(): Promise<string> {
+    return NativeVersionCheck().getBundleId();
+  }
+}
+
+class RnDeviceInfoProvider implements IDeviceInfoProvider {
+  async getOsVersion(): Promise<string> {
+    return NativeVersionCheck().getOsVersion();
+  }
+  async getDeviceModel(): Promise<string> {
+    return NativeVersionCheck().getDeviceModel();
+  }
+  async getLocale(): Promise<string> {
+    return NativeVersionCheck().getLocale();
+  }
+}
+
+/**
+ * True OS-scheduled background execution (BGTaskScheduler/WorkManager, Prompt 26) is
+ * not implemented in this pass. schedule()/cancel() log a warning rather than silently
+ * pretending to work — see the equivalent, identically-scoped note on WebBackgroundScheduler.
+ */
+class RnBackgroundScheduler implements IBackgroundScheduler {
+  async schedule(task: BackgroundTaskDescriptor): Promise<void> {
+    console.warn(
+      `[VersionManager] Background scheduling ("${task.taskId}") is not implemented on ${Platform.OS} yet (Prompt 26).`
+    );
+  }
+  async cancel(_taskId: string): Promise<void> {
+    // no-op — nothing was ever scheduled, see schedule() above.
+  }
+}
+
+class RnAppLifecycleObserver implements IAppLifecycleObserver {
+  onForeground(cb: () => void): Unsubscribe {
+    const sub = AppState.addEventListener('change', (state) => {
+      if (state === 'active') cb();
+    });
+    return () => sub.remove();
+  }
+
+  onBackground(cb: () => void): Unsubscribe {
+    const sub = AppState.addEventListener('change', (state) => {
+      if (state === 'background') cb();
+    });
+    return () => sub.remove();
+  }
+}
+
+/**
+ * Doc 03 §3.4 — delegates to the native TurboModule, which resolves `keyId` to
+ * build-time-embedded key material (iOS CommonCrypto/CryptoKit, Android
+ * java.security/javax.crypto) and never exposes key material to JS.
+ */
+class RnCryptoProvider implements ICryptoProvider {
+  async verifyEd25519(
+    keyId: string,
+    messageBase64: string,
+    signatureBase64: string
+  ): Promise<boolean> {
+    return NativeVersionCheck().verifyEd25519(
+      keyId,
+      messageBase64,
+      signatureBase64
+    );
+  }
+  async verifyHmacSha256(
+    keyId: string,
+    messageBase64: string,
+    macBase64: string
+  ): Promise<boolean> {
+    return NativeVersionCheck().verifyHmacSha256(
+      keyId,
+      messageBase64,
+      macBase64
+    );
+  }
+}
+
+export class NativePlatformBridge implements IPlatformBridge {
+  readonly platform: PlatformId = Platform.OS === 'ios' ? 'ios' : 'android';
+  readonly http: IHttpClient = new RnHttpClient();
+  readonly storage: IKeyValueStorage = new RnKeyValueStorage();
+  readonly secureStorage: ISecureStorage = new RnSecureStorage();
+  readonly appInfo: IAppInfoProvider = new RnAppInfoProvider();
+  readonly deviceInfo: IDeviceInfoProvider = new RnDeviceInfoProvider();
+  readonly scheduler: IBackgroundScheduler = new RnBackgroundScheduler();
+  readonly clock = { now: (): number => Date.now() };
+  readonly lifecycle: IAppLifecycleObserver = new RnAppLifecycleObserver();
+  readonly crypto: ICryptoProvider = new RnCryptoProvider();
+}

package/src/platform/native/NativeVersionCheck.ts

@@ -0,0 +1,64 @@
+import { TurboModuleRegistry, type TurboModule } from 'react-native';
+
+/**
+ * TurboModule Codegen spec. Deliberately small: HTTP (global `fetch`), the clock
+ * (`Date.now()`), and app-lifecycle (`AppState`) are already available in pure JS via
+ * React Native itself and do not need a custom native surface (Prompt 1 §4.1 revised
+ * during implementation — the design doc's per-target table listed a native `http`
+ * bridge conceptually, but RN's own Networking module already satisfies IHttpClient
+ * without new native code). What genuinely requires native code — reading the app's
+ * own version/bundle id and persisting key-value pairs via UserDefaults/Keychain or
+ * SharedPreferences/Keystore — is exactly what's declared here.
+ */
+export interface Spec extends TurboModule {
+  getCurrentAppVersion(): Promise<string>;
+  getBuildNumber(): Promise<string>;
+  getBundleId(): Promise<string>;
+  getOsVersion(): Promise<string>;
+  getDeviceModel(): Promise<string>;
+  getLocale(): Promise<string>;
+
+  storageGet(key: string): Promise<string | null>;
+  storageSet(key: string, value: string): Promise<void>;
+  storageRemove(key: string): Promise<void>;
+
+  secureStorageGet(key: string): Promise<string | null>;
+  secureStorageSet(key: string, value: string): Promise<void>;
+  secureStorageRemove(key: string): Promise<void>;
+
+  /**
+   * Doc 03 §3.4 — signature verification over OS-provided cryptography. `keyId` is
+   * resolved to build-time-embedded key material natively (Info.plist/BuildConfig);
+   * only the keyId, not the key itself, crosses this bridge. Android implements both
+   * via java.security/javax.crypto; iOS implements HMAC-SHA256 via CommonCrypto and
+   * Ed25519 via a small CryptoKit-backed Swift wrapper (ios/PlatformBridge/Ed25519Verifier.swift).
+   */
+  verifyEd25519(
+    keyId: string,
+    messageBase64: string,
+    signatureBase64: string
+  ): Promise<boolean>;
+  verifyHmacSha256(
+    keyId: string,
+    messageBase64: string,
+    macBase64: string
+  ): Promise<boolean>;
+}
+
+let cachedModule: Spec | null = null;
+
+/**
+ * Lazily resolved rather than the usual top-level
+ * `TurboModuleRegistry.getEnforcing<Spec>(...)` pattern, so importing this module (or
+ * anything that transitively imports it, e.g. src/di/container.ts) never throws in
+ * environments where the native module isn't registered — Jest's simulated native
+ * platform resolution, or a caller who supplies VersionManagerOptions.platformBridge
+ * and therefore never actually needs it. The registry lookup only happens the first
+ * time a method is actually called.
+ */
+export default function getNativeVersionCheck(): Spec {
+  if (!cachedModule) {
+    cachedModule = TurboModuleRegistry.getEnforcing<Spec>('VersionCheck');
+  }
+  return cachedModule;
+}

package/src/platform/web/WebPlatformBridge.ts

@@ -0,0 +1,347 @@
+import {
+  OfflineException,
+  RequestTimeoutException,
+} from '../../domain/errors/VersionManagerException';
+import type { PlatformId } from '../../domain/models/PlatformId';
+import type {
+  HttpRequest,
+  HttpResponse,
+  IAppInfoProvider,
+  IAppLifecycleObserver,
+  IBackgroundScheduler,
+  ICryptoProvider,
+  IDeviceInfoProvider,
+  IHttpClient,
+  IKeyValueStorage,
+  IPlatformBridge,
+  ISecureStorage,
+  Unsubscribe,
+  BackgroundTaskDescriptor,
+} from '../../domain/ports/IPlatformBridge';
+
+/**
+ * This project's tsconfig deliberately omits the "DOM" lib (it collides with React
+ * Native's own global fetch/console typings — Prompt 1 constraint). The small subset
+ * of browser globals this bridge needs is declared locally instead of pulling in the
+ * full lib.dom.d.ts surface, and accessed through a single typed cast of globalThis.
+ */
+interface WebFetchResponseLike {
+  readonly status: number;
+  readonly headers: { forEach(cb: (value: string, key: string) => void): void };
+  text(): Promise<string>;
+}
+type WebFetchInit = {
+  method?: string;
+  headers?: Record<string, string>;
+  body?: string;
+  signal?: unknown;
+};
+type WebFetchLike = (
+  url: string,
+  init?: WebFetchInit
+) => Promise<WebFetchResponseLike>;
+
+interface WebStorageLike {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+interface WebNavigatorLike {
+  readonly language: string;
+  readonly userAgent: string;
+}
+
+interface WebDocumentLike {
+  readonly visibilityState: string;
+  addEventListener(type: string, cb: () => void): void;
+  removeEventListener(type: string, cb: () => void): void;
+}
+
+interface WebAbortControllerLike {
+  readonly signal: unknown;
+  abort(): void;
+}
+
+interface WebSubtleCryptoLike {
+  importKey(
+    format: string,
+    keyData: unknown,
+    algorithm: unknown,
+    extractable: boolean,
+    keyUsages: string[]
+  ): Promise<unknown>;
+  verify(
+    algorithm: unknown,
+    key: unknown,
+    signature: unknown,
+    data: unknown
+  ): Promise<boolean>;
+  sign(algorithm: unknown, key: unknown, data: unknown): Promise<unknown>;
+}
+
+interface WebGlobals {
+  fetch: WebFetchLike;
+  localStorage: WebStorageLike;
+  navigator: WebNavigatorLike;
+  document: WebDocumentLike;
+  AbortController: new () => WebAbortControllerLike;
+  crypto?: { subtle: WebSubtleCryptoLike };
+  window?: {
+    addEventListener(type: string, cb: () => void): void;
+    removeEventListener(type: string, cb: () => void): void;
+  };
+  /**
+   * Doc 03 §3.4's "embedded at build time" tier, for Web: since there is no OS
+   * keychain/BuildConfig equivalent in a browser, the Web-target convention is a
+   * build-time `define` (Vite/webpack) injecting this global with keyId -> base64 key
+   * material — analogous to how §5.1 treats "Cache-Control: immutable" as the Web
+   * equivalent of native mmap. Absent this global, ed25519/hmac-sha256 verification on
+   * Web fails closed (returns false) rather than silently trusting an unverifiable doc.
+   */
+  __VM_TRUSTED_KEYS__?: Record<string, string>;
+}
+
+const webGlobal = globalThis as unknown as WebGlobals;
+
+function base64ToBytes(base64: string): Uint8Array {
+  if (typeof atob === 'function') {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return bytes;
+  }
+  throw new Error('No base64 decoder available in this environment');
+}
+
+/**
+ * Doc 03 §3.4 crypto port, Web target — uses browser-native SubtleCrypto exclusively
+ * (Prompt 1 §9.3: no third-party crypto library). HMAC-SHA256 has broad browser
+ * support; Ed25519 support via WebCrypto is newer (Chrome 129+/Safari 17+) and this
+ * method throws a clear, caught error on unsupported browsers rather than silently
+ * failing — SignatureVerifier surfaces that as a normal SignatureVerificationException.
+ */
+class WebCryptoProvider implements ICryptoProvider {
+  async verifyEd25519(
+    keyId: string,
+    messageBase64: string,
+    signatureBase64: string
+  ): Promise<boolean> {
+    const subtle = webGlobal.crypto?.subtle;
+    const keyMaterial = webGlobal.__VM_TRUSTED_KEYS__?.[keyId];
+    if (!subtle || !keyMaterial) return false;
+    const key = await subtle.importKey(
+      'raw',
+      base64ToBytes(keyMaterial),
+      { name: 'Ed25519' },
+      false,
+      ['verify']
+    );
+    return subtle.verify(
+      { name: 'Ed25519' },
+      key,
+      base64ToBytes(signatureBase64),
+      base64ToBytes(messageBase64)
+    );
+  }
+
+  async verifyHmacSha256(
+    keyId: string,
+    messageBase64: string,
+    macBase64: string
+  ): Promise<boolean> {
+    const subtle = webGlobal.crypto?.subtle;
+    const keyMaterial = webGlobal.__VM_TRUSTED_KEYS__?.[keyId];
+    if (!subtle || !keyMaterial) return false;
+    const key = await subtle.importKey(
+      'raw',
+      base64ToBytes(keyMaterial),
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['sign']
+    );
+    const computed = await subtle.sign(
+      { name: 'HMAC' },
+      key,
+      base64ToBytes(messageBase64)
+    );
+    const computedBytes = new Uint8Array(computed as ArrayBuffer);
+    const expectedBytes = base64ToBytes(macBase64);
+    if (computedBytes.length !== expectedBytes.length) return false;
+    let diff = 0;
+    for (let i = 0; i < computedBytes.length; i++) {
+      diff |= (computedBytes[i] as number) ^ (expectedBytes[i] as number);
+    }
+    return diff === 0;
+  }
+}
+
+class WebHttpClient implements IHttpClient {
+  async request(req: HttpRequest): Promise<HttpResponse> {
+    const controller = new webGlobal.AbortController();
+    const timeout = setTimeout(() => controller.abort(), req.timeoutMs);
+    try {
+      const response = await webGlobal.fetch(req.url, {
+        method: req.method,
+        headers: req.headers as Record<string, string> | undefined,
+        body: req.body,
+        signal: controller.signal,
+      });
+      const headers: Record<string, string> = {};
+      response.headers.forEach((value, key) => {
+        headers[key] = value;
+      });
+      const body = await response.text();
+      return { status: response.status, headers, body };
+    } catch (error) {
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new RequestTimeoutException({
+          message: `Request to "${req.url}" timed out after ${req.timeoutMs}ms`,
+          cause: error,
+        });
+      }
+      throw new OfflineException({
+        message: `Request to "${req.url}" failed`,
+        cause: error,
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+}
+
+class WebKeyValueStorage implements IKeyValueStorage {
+  async get(key: string): Promise<string | null> {
+    return webGlobal.localStorage.getItem(key);
+  }
+  async set(key: string, value: string): Promise<void> {
+    webGlobal.localStorage.setItem(key, value);
+  }
+  async remove(key: string): Promise<void> {
+    webGlobal.localStorage.removeItem(key);
+  }
+}
+
+/**
+ * Backed by localStorage under a distinct key prefix. This is functionally complete
+ * (satisfies ISecureStorage) but is NOT encrypted at rest — true SubtleCrypto-based
+ * encryption-at-rest for the Web target (Prompt 1 §4.1's documented design) is a
+ * follow-up hardening item, not implemented in this pass.
+ */
+class WebSecureStorage implements ISecureStorage {
+  private static readonly PREFIX = 'vm_secure_';
+  async getItem(key: string): Promise<string | null> {
+    return webGlobal.localStorage.getItem(WebSecureStorage.PREFIX + key);
+  }
+  async setItem(key: string, value: string): Promise<void> {
+    webGlobal.localStorage.setItem(WebSecureStorage.PREFIX + key, value);
+  }
+  async removeItem(key: string): Promise<void> {
+    webGlobal.localStorage.removeItem(WebSecureStorage.PREFIX + key);
+  }
+}
+
+/**
+ * The Web target has no OS bundle to read a version/build number from. These should be
+ * injected at build time (e.g. a Vite `define`); absent that, callers are expected to
+ * supply `VersionManagerOptions.appVersion` explicitly, which Core prefers over this
+ * bridge (see VersionManagerCore.resolveCurrentVersion()).
+ */
+class WebAppInfoProvider implements IAppInfoProvider {
+  async getCurrentVersion(): Promise<string> {
+    return '0.0.0';
+  }
+  async getBuildNumber(): Promise<string> {
+    return '0';
+  }
+  async getBundleId(): Promise<string> {
+    return 'web';
+  }
+}
+
+class WebDeviceInfoProvider implements IDeviceInfoProvider {
+  async getOsVersion(): Promise<string> {
+    return webGlobal.navigator.userAgent;
+  }
+  async getDeviceModel(): Promise<string> {
+    return 'web';
+  }
+  async getLocale(): Promise<string> {
+    return webGlobal.navigator.language;
+  }
+}
+
+/**
+ * True Service Worker `periodicSync` requires a registered service worker the host app
+ * controls (feature-detected, narrow browser support) and is out of this pass's scope —
+ * see the class-level fallback doc 01 §4.1 explicitly names: "visibility-change
+ * fallback." This implements exactly that fallback for real: a `setInterval` gated so
+ * the callback only actually fires while the tab is visible (`document.visibilityState
+ * === 'visible'`), which is the best a page can do without its own registered SW.
+ * `minIntervalMs` is honored as a floor, not a guarantee — like all browser timers, it
+ * is throttled/paused while backgrounded, which is the whole reason for the visibility
+ * gate (avoid firing a burst of missed intervals the instant the tab regains focus).
+ */
+class WebBackgroundScheduler implements IBackgroundScheduler {
+  private readonly timers = new Map<string, ReturnType<typeof setInterval>>();
+  private readonly callbacks = new Map<string, () => void>();
+
+  async schedule(task: BackgroundTaskDescriptor): Promise<void> {
+    this.cancelInternal(task.taskId);
+    const timer = setInterval(() => {
+      if (webGlobal.document.visibilityState !== 'visible') return;
+      this.callbacks.get(task.taskId)?.();
+    }, task.minIntervalMs);
+    this.timers.set(task.taskId, timer);
+  }
+
+  async cancel(taskId: string): Promise<void> {
+    this.cancelInternal(taskId);
+  }
+
+  /** Registers the function a scheduled task actually invokes when it fires (wired by src/di/container.ts, not part of IBackgroundScheduler's public port shape). */
+  setCallback(taskId: string, cb: () => void): void {
+    this.callbacks.set(taskId, cb);
+  }
+
+  private cancelInternal(taskId: string): void {
+    const existing = this.timers.get(taskId);
+    if (existing !== undefined) {
+      clearInterval(existing);
+      this.timers.delete(taskId);
+    }
+  }
+}
+
+class WebAppLifecycleObserver implements IAppLifecycleObserver {
+  onForeground(cb: () => void): Unsubscribe {
+    const handler = (): void => {
+      if (webGlobal.document.visibilityState === 'visible') cb();
+    };
+    webGlobal.document.addEventListener('visibilitychange', handler);
+    return () =>
+      webGlobal.document.removeEventListener('visibilitychange', handler);
+  }
+
+  onBackground(cb: () => void): Unsubscribe {
+    const handler = (): void => {
+      if (webGlobal.document.visibilityState === 'hidden') cb();
+    };
+    webGlobal.document.addEventListener('visibilitychange', handler);
+    return () =>
+      webGlobal.document.removeEventListener('visibilitychange', handler);
+  }
+}
+
+export class WebPlatformBridge implements IPlatformBridge {
+  readonly platform: PlatformId = 'web';
+  readonly http: IHttpClient = new WebHttpClient();
+  readonly storage: IKeyValueStorage = new WebKeyValueStorage();
+  readonly secureStorage: ISecureStorage = new WebSecureStorage();
+  readonly appInfo: IAppInfoProvider = new WebAppInfoProvider();
+  readonly deviceInfo: IDeviceInfoProvider = new WebDeviceInfoProvider();
+  readonly scheduler: IBackgroundScheduler = new WebBackgroundScheduler();
+  readonly clock = { now: (): number => Date.now() };
+  readonly lifecycle: IAppLifecycleObserver = new WebAppLifecycleObserver();
+  readonly crypto: ICryptoProvider = new WebCryptoProvider();
+}

package/src/presentation/components/ForceUpdateScreen.tsx

@@ -0,0 +1,64 @@
+import { Modal, Pressable, StyleSheet, Text, View } from 'react-native';
+import type { ReactElement } from 'react';
+import type { UpdateInfo } from '../../domain/models/UpdateInfo';
+
+export interface ForceUpdateScreenProps {
+  updateInfo: UpdateInfo;
+  onUpdatePress: () => void;
+  title?: string;
+  message?: string;
+  updateButtonLabel?: string;
+}
+
+/** Full-screen, non-dismissible lockout (Prompt 1 §5.3; UI copy detail is Prompt 19). */
+export function ForceUpdateScreen({
+  updateInfo,
+  onUpdatePress,
+  title = 'Update Required',
+  message = `Version ${updateInfo.latestVersion} is available. You must update to continue.`,
+  updateButtonLabel = 'Update Now',
+}: ForceUpdateScreenProps): ReactElement {
+  return (
+    <Modal
+      visible
+      animationType="fade"
+      transparent={false}
+      onRequestClose={() => undefined}
+    >
+      <View style={styles.container}>
+        <Text style={styles.title}>{title}</Text>
+        <Text style={styles.message}>{message}</Text>
+        <Pressable
+          style={styles.button}
+          onPress={onUpdatePress}
+          accessibilityRole="button"
+        >
+          <Text style={styles.buttonLabel}>{updateButtonLabel}</Text>
+        </Pressable>
+      </View>
+    </Modal>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 24,
+  },
+  title: {
+    fontSize: 20,
+    fontWeight: '700',
+    marginBottom: 12,
+    textAlign: 'center',
+  },
+  message: { fontSize: 15, textAlign: 'center', marginBottom: 24 },
+  button: {
+    paddingVertical: 12,
+    paddingHorizontal: 24,
+    borderRadius: 8,
+    backgroundColor: '#2563eb',
+  },
+  buttonLabel: { color: '#ffffff', fontSize: 16, fontWeight: '600' },
+});