@appium/coresim 1.0.0

package/src/native/sim_screenshot.mm

@@ -0,0 +1,226 @@
+#include "sim_screenshot.h"
+
+#import <CoreImage/CoreImage.h>
+#import <IOSurface/IOSurface.h>
+#import <ImageIO/ImageIO.h>
+#import <objc/message.h>
+
+#include "objc_runtime.h"
+#include "safe_dispatch.h"
+
+namespace coresim {
+
+namespace {
+
+NSString* const kScreenshotErrorDomain = @"com.appium.coresim.Screenshot";
+
+NSError* MakeError(NSInteger code, NSString* message) {
+  return [NSError errorWithDomain:kScreenshotErrorDomain code:code userInfo:@{NSLocalizedDescriptionKey : message}];
+}
+
+id IdGetter(id target, const std::string& selectorName) {
+  RequireSelector(target, selectorName);
+  SEL selector = SelectorNamed(selectorName);
+  return SafeInvoke([&] {
+    using Fn = id (*)(id, SEL);
+    return ((Fn)objc_msgSend)(target, selector);
+  });
+}
+
+// -[<SimDisplayDescriptorState> displayClass] — iOS's main display is class 0; tvOS renders only
+// on the (non-zero) TVOut class.
+unsigned short DisplayClass(id descriptorState) {
+  static const std::string kSelectorName = "displayClass";
+  RequireSelector(descriptorState, kSelectorName);
+  SEL selector = SelectorNamed(kSelectorName);
+  return SafeInvoke([&] {
+    using Fn = unsigned short (*)(id, SEL);
+    return ((Fn)objc_msgSend)(descriptorState, selector);
+  });
+}
+
+// One renderable display IO port found among -[SimDeviceIOClient ioPorts]. Keeps "descriptor"
+// alongside the JS-facing "id"/"displayClass" fields so CaptureScreenshot can resolve a requested
+// displayId against the same list ListDisplays reports, without walking ioPorts twice.
+NSString* const kCandidateUUIDKey = @"id";
+NSString* const kCandidateDisplayClassKey = @"displayClass";
+NSString* const kCandidateDescriptorKey = @"descriptor";
+
+// Every IO port that actually renders a screen, in -[SimDeviceIOClient ioPorts]'s own order. Only
+// a port conforming to the (private, headerless) SimDisplayIOSurfaceRenderable/SimDisplayRenderable
+// protocols carries a "displayClass" or either surface accessor — other ports (audio, the
+// screenshot mach service itself) don't, so the respondsToSelector: checks below are the actual
+// filter, not defensive leftovers. Returns nil (and sets *error) only if the device has no IO
+// client at all (e.g. not booted); no renderable port is an empty array, not an error — the caller
+// decides whether that's fatal.
+NSArray<NSDictionary*>* RenderableDisplayCandidates(id device, NSError** error) {
+  id ioClient = IdGetter(device, "io");
+  if (ioClient == nil) {
+    *error = MakeError(1, @"Device has no IO client available — is it booted?");
+    return nil;
+  }
+
+  NSArray* ports = IdGetter(ioClient, "ioPorts");
+  NSMutableArray<NSDictionary*>* candidates = [NSMutableArray array];
+  for (id port in ports) {
+    id descriptor = IdGetter(port, "descriptor");
+    if (descriptor == nil) continue;
+    if (![descriptor respondsToSelector:NSSelectorFromString(@"framebufferSurface")] &&
+        ![descriptor respondsToSelector:NSSelectorFromString(@"ioSurface")]) {
+      continue;
+    }
+    if (![descriptor respondsToSelector:NSSelectorFromString(@"state")]) {
+      continue;
+    }
+    id state = IdGetter(descriptor, "state");
+    if (state == nil || ![state respondsToSelector:NSSelectorFromString(@"displayClass")]) {
+      continue;
+    }
+    NSUUID* uuid = IdGetter(port, "uuid");
+    [candidates addObject:@{
+      kCandidateUUIDKey : uuid ? uuid.UUIDString : @"",
+      kCandidateDisplayClassKey : @(DisplayClass(state)),
+      kCandidateDescriptorKey : descriptor,
+    }];
+  }
+  return candidates;
+}
+
+// Picks which candidate CaptureScreenshot should read from: the one matching `displayId` if given
+// (an error if none match), else the primary display (displayClass 0), falling back to the first
+// renderable display found so a target with no class-0 display (e.g. tvOS) still gets a
+// screenshot instead of an outright failure.
+id ResolveDisplayDescriptor(NSArray<NSDictionary*>* candidates, NSString* displayId, NSError** error) {
+  if (displayId != nil) {
+    for (NSDictionary* candidate in candidates) {
+      if ([candidate[kCandidateUUIDKey] isEqualToString:displayId]) {
+        return candidate[kCandidateDescriptorKey];
+      }
+    }
+    *error = MakeError(2, [NSString stringWithFormat:@"No display with id '%@' was found on this device", displayId]);
+    return nil;
+  }
+  id fallback = nil;
+  for (NSDictionary* candidate in candidates) {
+    if ([candidate[kCandidateDisplayClassKey] unsignedShortValue] == 0) {
+      return candidate[kCandidateDescriptorKey];
+    }
+    if (fallback == nil) {
+      fallback = candidate[kCandidateDescriptorKey];
+    }
+  }
+  if (fallback == nil) {
+    *error = MakeError(3, @"No renderable display port was found on this device");
+  }
+  return fallback;
+}
+
+// Unlike IdGetter, doesn't RequireSelector: a display proxy that has lost its connection (e.g. the
+// device just shut down) can legitimately stop responding to a selector it answered a moment ago —
+// that's "no surface right now", not "unsupported on this CoreSimulator", so it must not raise
+// NativeSimUnavailableError the way a genuinely missing selector should.
+id OptionalIdGetter(id target, NSString* selectorName) {
+  SEL selector = NSSelectorFromString(selectorName);
+  if (![target respondsToSelector:selector]) {
+    return nil;
+  }
+  return SafeInvoke([&] {
+    using Fn = id (*)(id, SEL);
+    return ((Fn)objc_msgSend)(target, selector);
+  });
+}
+
+// `framebufferSurface` is the primary surface since Xcode 13.2 split what used to be a single
+// `ioSurface`; both are real (non-optional) members of the descriptor's protocol once it's passed
+// RenderableDisplayCandidates' filter above, but the underlying remote proxy can still legitimately
+// vend nil for either — or stop responding entirely if the connection just dropped — so both are
+// tried before giving up.
+id RenderableSurface(id descriptor) {
+  return OptionalIdGetter(descriptor, @"framebufferSurface") ?: OptionalIdGetter(descriptor, @"ioSurface");
+}
+
+NSString* const kPNGUTI = @"public.png";
+NSString* const kJPEGUTI = @"public.jpeg";
+
+}  // namespace
+
+NSArray<NSDictionary*>* ListDisplays(id device, NSError** error) {
+  NSArray<NSDictionary*>* candidates = RenderableDisplayCandidates(device, error);
+  if (candidates == nil) {
+    return nil;
+  }
+  NSMutableArray<NSDictionary*>* result = [NSMutableArray arrayWithCapacity:candidates.count];
+  for (NSDictionary* candidate in candidates) {
+    unsigned short displayClass = [candidate[kCandidateDisplayClassKey] unsignedShortValue];
+    [result addObject:@{
+      @"id" : candidate[kCandidateUUIDKey],
+      @"displayClass" : candidate[kCandidateDisplayClassKey],
+      @"isMain" : @(displayClass == 0),
+    }];
+  }
+  return result;
+}
+
+NSData* CaptureScreenshot(id device, NSString* displayId, ScreenshotFormat format, NSNumber* jpegQualityPercent,
+                          NSError** error) {
+  NSArray<NSDictionary*>* candidates = RenderableDisplayCandidates(device, error);
+  if (candidates == nil) {
+    return nil;
+  }
+
+  id descriptor = ResolveDisplayDescriptor(candidates, displayId, error);
+  if (descriptor == nil) {
+    return nil;
+  }
+
+  id surfaceObj = RenderableSurface(descriptor);
+  if (surfaceObj == nil) {
+    *error = MakeError(4, @"The device's display surface is not available yet");
+    return nil;
+  }
+
+  IOSurfaceRef surfaceRef = (__bridge IOSurfaceRef)surfaceObj;
+  CIImage* ciImage = [CIImage imageWithIOSurface:surfaceRef];
+  if (ciImage == nil) {
+    *error = MakeError(5, @"Failed to wrap the device's display surface as an image");
+    return nil;
+  }
+
+  // A fresh CIContext per call, matching this operation's one-shot semantics (mirrors
+  // simctl's own screenshot command) rather than the persistent, reused context a
+  // continuous video/streaming path would want.
+  CIContext* context = [CIContext contextWithOptions:nil];
+  CGImageRef cgImage = [context createCGImage:ciImage fromRect:ciImage.extent];
+  if (cgImage == nil) {
+    *error = MakeError(6, @"Failed to render the device's display surface");
+    return nil;
+  }
+
+  NSString* uti = format == ScreenshotFormat::kJPEG ? kJPEGUTI : kPNGUTI;
+  NSMutableData* imageData = [NSMutableData data];
+  CGImageDestinationRef destination =
+      CGImageDestinationCreateWithData((__bridge CFMutableDataRef)imageData, (__bridge CFStringRef)uti, 1, NULL);
+  if (destination == nullptr) {
+    CGImageRelease(cgImage);
+    *error = MakeError(7, @"Failed to create an image encoder for the captured screenshot");
+    return nil;
+  }
+  // kCGImageDestinationLossyCompressionQuality is meaningless for PNG (always lossless) — ImageIO
+  // silently ignores properties a format doesn't use, so this is only gated on jpegQualityPercent
+  // being present, not on `format` too.
+  NSDictionary* properties =
+      jpegQualityPercent != nil
+          ? @{(NSString*)kCGImageDestinationLossyCompressionQuality : @(jpegQualityPercent.doubleValue / 100.0)}
+          : nil;
+  CGImageDestinationAddImage(destination, cgImage, (__bridge CFDictionaryRef)properties);
+  BOOL ok = CGImageDestinationFinalize(destination);
+  CFRelease(destination);
+  CGImageRelease(cgImage);
+  if (!ok) {
+    *error = MakeError(8, @"Failed to encode the captured screenshot");
+    return nil;
+  }
+  return imageData;
+}
+
+}  // namespace coresim

package/src/native/sim_service_context.h

@@ -0,0 +1,42 @@
+#pragma once
+
+#import <Foundation/Foundation.h>
+
+namespace coresim {
+
+// +[SimServiceContext sharedServiceContextForDeveloperDir:error:]. Returns nil (with *error set)
+// on failure. `developerDir` is the "which Xcode" selector — the actual physical CoreSimulator
+// binary loaded is always the one shared system-wide copy; this only picks which runtimes/device
+// types/behaviors that shared framework resolves against.
+id SharedServiceContext(NSString* developerDir, NSError** error);
+
+// -[SimServiceContext defaultDeviceSetWithError:]
+id DefaultDeviceSet(id serviceContext, NSError** error);
+
+// -[SimServiceContext supportedDeviceTypes] -> NSArray<SimDeviceType*>
+NSArray* SupportedDeviceTypes(id serviceContext);
+
+// -[SimServiceContext supportedRuntimes] -> NSArray<SimRuntime*>
+NSArray* SupportedRuntimes(id serviceContext);
+
+// -[SimServiceContext supportedDeviceTypesByIdentifier] -> NSDictionary<NSString*, SimDeviceType*>
+NSDictionary* SupportedDeviceTypesByIdentifier(id serviceContext);
+
+// -[SimServiceContext supportedRuntimesByIdentifier] -> NSDictionary<NSString*, SimRuntime*>
+NSDictionary* SupportedRuntimesByIdentifier(id serviceContext);
+
+// -[SimDeviceType identifier] / -[SimDeviceType name]
+NSString* DeviceTypeIdentifier(id deviceType);
+NSString* DeviceTypeName(id deviceType);
+
+// -[SimRuntime identifier] / -[SimRuntime name] / -[SimRuntime versionString]
+NSString* RuntimeIdentifier(id runtime);
+NSString* RuntimeName(id runtime);
+NSString* RuntimeVersionString(id runtime);
+
+// -[SimRuntime root] -> the runtime bundle's `RuntimeRoot` directory, same as a spawned process's
+// own `$SIMULATOR_ROOT`. Used to resolve guest-OS-specific executables (e.g. `launchctl` — see
+// CLAUDE.md) before spawning them, since SimDevice's spawn API takes a literal path, no PATH search.
+NSString* RuntimeRootPath(id runtime);
+
+}  // namespace coresim

package/src/native/sim_service_context.mm

@@ -0,0 +1,92 @@
+#include "sim_service_context.h"
+
+#import <objc/message.h>
+
+#include "objc_runtime.h"
+#include "safe_dispatch.h"
+
+namespace coresim {
+
+id SharedServiceContext(NSString* developerDir, NSError** error) {
+  Class cls = RequireClass("SimServiceContext");
+  static const std::string kSelectorName = "sharedServiceContextForDeveloperDir:error:";
+  RequireClassSelector(cls, kSelectorName);
+  SEL selector = SelectorNamed(kSelectorName);
+  return SafeInvoke([&] {
+    using Fn = id (*)(Class, SEL, NSString*, NSError**);
+    return ((Fn)objc_msgSend)(cls, selector, developerDir, error);
+  });
+}
+
+id DefaultDeviceSet(id serviceContext, NSError** error) {
+  static const std::string kSelectorName = "defaultDeviceSetWithError:";
+  RequireSelector(serviceContext, kSelectorName);
+  SEL selector = SelectorNamed(kSelectorName);
+  return SafeInvoke([&] {
+    using Fn = id (*)(id, SEL, NSError**);
+    return ((Fn)objc_msgSend)(serviceContext, selector, error);
+  });
+}
+
+NSArray* SupportedDeviceTypes(id serviceContext) {
+  static const std::string kSelectorName = "supportedDeviceTypes";
+  RequireSelector(serviceContext, kSelectorName);
+  SEL selector = SelectorNamed(kSelectorName);
+  return SafeInvoke([&] {
+    using Fn = NSArray* (*)(id, SEL);
+    return ((Fn)objc_msgSend)(serviceContext, selector);
+  });
+}
+
+NSArray* SupportedRuntimes(id serviceContext) {
+  static const std::string kSelectorName = "supportedRuntimes";
+  RequireSelector(serviceContext, kSelectorName);
+  SEL selector = SelectorNamed(kSelectorName);
+  return SafeInvoke([&] {
+    using Fn = NSArray* (*)(id, SEL);
+    return ((Fn)objc_msgSend)(serviceContext, selector);
+  });
+}
+
+namespace {
+
+// Shared shape for every zero-arg id-returning getter used below (identifier/name/versionString).
+NSString* StringGetter(id target, const std::string& selectorName) {
+  RequireSelector(target, selectorName);
+  SEL selector = SelectorNamed(selectorName);
+  return SafeInvoke([&] {
+    using Fn = NSString* (*)(id, SEL);
+    return ((Fn)objc_msgSend)(target, selector);
+  });
+}
+
+}  // namespace
+
+NSDictionary* SupportedDeviceTypesByIdentifier(id serviceContext) {
+  static const std::string kSelectorName = "supportedDeviceTypesByIdentifier";
+  RequireSelector(serviceContext, kSelectorName);
+  SEL selector = SelectorNamed(kSelectorName);
+  return SafeInvoke([&] {
+    using Fn = NSDictionary* (*)(id, SEL);
+    return ((Fn)objc_msgSend)(serviceContext, selector);
+  });
+}
+
+NSDictionary* SupportedRuntimesByIdentifier(id serviceContext) {
+  static const std::string kSelectorName = "supportedRuntimesByIdentifier";
+  RequireSelector(serviceContext, kSelectorName);
+  SEL selector = SelectorNamed(kSelectorName);
+  return SafeInvoke([&] {
+    using Fn = NSDictionary* (*)(id, SEL);
+    return ((Fn)objc_msgSend)(serviceContext, selector);
+  });
+}
+
+NSString* DeviceTypeIdentifier(id deviceType) { return StringGetter(deviceType, "identifier"); }
+NSString* DeviceTypeName(id deviceType) { return StringGetter(deviceType, "name"); }
+NSString* RuntimeIdentifier(id runtime) { return StringGetter(runtime, "identifier"); }
+NSString* RuntimeName(id runtime) { return StringGetter(runtime, "name"); }
+NSString* RuntimeVersionString(id runtime) { return StringGetter(runtime, "versionString"); }
+NSString* RuntimeRootPath(id runtime) { return StringGetter(runtime, "root"); }
+
+}  // namespace coresim

package/src/native/tcc_privacy.h

@@ -0,0 +1,35 @@
+#pragma once
+
+#import <Foundation/Foundation.h>
+
+namespace coresim {
+
+// Grants or revokes a privacy permission for `bundleId` in the simulator's own TCC (privacy)
+// database, located under the device's data directory (see DeviceDataPath, sim_device.h) at
+// `Library/TCC/TCC.db`. `service` is the raw TCC service identifier (e.g. "kTCCServiceCamera"),
+// not a friendly name — callers map friendly names to these before calling in (see
+// commands/permissions.ts). Fails with a descriptive NSError if the device has never been booted
+// (TCC.db doesn't exist yet) or the database can't be written to.
+BOOL SetTCCAccess(NSString* dataPath, NSString* service, NSString* bundleId, BOOL granted, NSError** error);
+
+// Resets a previously granted/revoked permission back to its default (unprompted, "unset") state
+// by deleting its row from TCC.db, if one exists.
+BOOL ResetTCCAccess(NSString* dataPath, NSString* service, NSString* bundleId, NSError** error);
+
+// Own status codes GetTCCAccess reports through `outStatus` — deliberately not TCC's own raw wire
+// values (which reuse 0 for "denied", not "no row"), so a missing row and an explicit denial are
+// never confusable. `kTCCAuthLimited` only ever occurs for kTCCServicePhotos's "selected photos"
+// grant — SetTCCAccess never writes it, but a row can still carry it if something else did.
+enum TCCAuthStatus {
+  kTCCAuthNotDetermined = 0,
+  kTCCAuthDenied,
+  kTCCAuthGranted,
+  kTCCAuthLimited,
+};
+
+// Reads TCC.db for the current authorization status of (service, bundleId), translating either
+// schema (see HasAuthValueColumn in the .mm) into the TCCAuthStatus values above. Fails with the
+// same descriptive NSError as SetTCCAccess if the device has never been booted (no TCC.db yet).
+BOOL GetTCCAccess(NSString* dataPath, NSString* service, NSString* bundleId, TCCAuthStatus* outStatus, NSError** error);
+
+}  // namespace coresim

package/src/native/tcc_privacy.mm

@@ -0,0 +1,256 @@
+#include "tcc_privacy.h"
+
+#include <sqlite3.h>
+
+#include <cstring>
+#include <string>
+
+namespace coresim {
+
+namespace {
+
+NSString* const kTCCErrorDomain = @"com.appium.coresim.TCCPrivacy";
+
+NSError* MakeError(int code, NSString* message) {
+  return [NSError errorWithDomain:kTCCErrorDomain code:code userInfo:@{NSLocalizedDescriptionKey : message}];
+}
+
+NSString* TCCDatabasePath(NSString* dataPath) {
+  return [dataPath stringByAppendingPathComponent:@"Library/TCC/TCC.db"];
+}
+
+// SQLITE_OPEN_READWRITE only (no _CREATE): fails with SQLITE_CANTOPEN instead of silently
+// creating an empty, schema-less database when the simulator has never been booted.
+sqlite3* OpenDatabase(NSString* dataPath, NSError** error) {
+  NSString* path = TCCDatabasePath(dataPath);
+  sqlite3* db = nullptr;
+  int rc = sqlite3_open_v2(path.UTF8String, &db, SQLITE_OPEN_READWRITE, nullptr);
+  if (rc != SQLITE_OK) {
+    if (error) {
+      *error = MakeError(rc, [NSString stringWithFormat:@"Could not open TCC database at '%@' — the device may "
+                                                        @"need to be booted at least once first: %s",
+                                                        path, sqlite3_errstr(rc)]);
+    }
+    if (db) {
+      sqlite3_close(db);
+    }
+    return nullptr;
+  }
+  // Waits (rather than immediately failing) if the simulator's own tccd process has the database
+  // locked, instead of a manual sleep/retry loop.
+  sqlite3_busy_timeout(db, 5000);
+  return db;
+}
+
+// TCC schema gained `auth_value` (replacing the older boolean `allowed` column) in iOS 14; checked
+// against the actual database rather than an OS version threshold, since the schema version tracks
+// the *simulator's* iOS release, not the host's.
+bool HasAuthValueColumn(sqlite3* db) {
+  sqlite3_stmt* stmt = nullptr;
+  if (sqlite3_prepare_v2(db, "PRAGMA table_info(access)", -1, &stmt, nullptr) != SQLITE_OK) {
+    return false;
+  }
+  bool found = false;
+  while (sqlite3_step(stmt) == SQLITE_ROW) {
+    const unsigned char* name = sqlite3_column_text(stmt, 1);
+    if (name && std::strcmp(reinterpret_cast<const char*>(name), "auth_value") == 0) {
+      found = true;
+      break;
+    }
+  }
+  sqlite3_finalize(stmt);
+  return found;
+}
+
+void BindText(sqlite3_stmt* stmt, int index, NSString* value) {
+  sqlite3_bind_text(stmt, index, value.UTF8String, -1, SQLITE_TRANSIENT);
+}
+
+// Runs one parameterized statement to completion. `bind` receives the prepared statement to bind
+// its own parameters onto.
+template <typename BindFn>
+bool ExecuteStatement(sqlite3* db, const char* sql, BindFn bind, NSError** error) {
+  sqlite3_stmt* stmt = nullptr;
+  if (sqlite3_prepare_v2(db, sql, -1, &stmt, nullptr) != SQLITE_OK) {
+    if (error) {
+      *error =
+          MakeError(sqlite3_errcode(db),
+                    [NSString stringWithFormat:@"Failed to prepare TCC database statement: %s", sqlite3_errmsg(db)]);
+    }
+    return false;
+  }
+  bind(stmt);
+  int rc = sqlite3_step(stmt);
+  sqlite3_finalize(stmt);
+  if (rc != SQLITE_DONE) {
+    if (error) {
+      *error = MakeError(rc, [NSString stringWithFormat:@"Failed to update TCC database: %s", sqlite3_errmsg(db)]);
+    }
+    return false;
+  }
+  return true;
+}
+
+bool DeleteAccessRow(sqlite3* db, NSString* service, NSString* bundleId, NSError** error) {
+  return ExecuteStatement(
+      db, "DELETE FROM access WHERE service = ? AND client = ? AND client_type = 0",
+      [&](sqlite3_stmt* stmt) {
+        BindText(stmt, 1, service);
+        BindText(stmt, 2, bundleId);
+      },
+      error);
+}
+
+// The delete+insert pair below must not be allowed to commit independently — a failure between
+// them would otherwise permanently drop the prior row instead of leaving it unchanged.
+bool BeginTransaction(sqlite3* db, NSError** error) {
+  if (sqlite3_exec(db, "BEGIN IMMEDIATE TRANSACTION", nullptr, nullptr, nullptr) == SQLITE_OK) {
+    return true;
+  }
+  if (error) {
+    *error = MakeError(sqlite3_errcode(db),
+                       [NSString stringWithFormat:@"Failed to begin TCC database transaction: %s", sqlite3_errmsg(db)]);
+  }
+  return false;
+}
+
+// Returns whether the transaction actually ended up committed. On a COMMIT failure (e.g.
+// SQLITE_BUSY from a concurrent reader — SQLite documents that a busy COMMIT leaves the
+// transaction still active, not rolled back automatically) the transaction is explicitly rolled
+// back here rather than left for sqlite3_close to implicitly discard, so the caller gets an
+// accurate failure instead of the `true` that the statements before COMMIT itself had reported.
+bool CommitOrRollback(sqlite3* db, bool commit, NSError** error) {
+  if (commit) {
+    if (sqlite3_exec(db, "COMMIT", nullptr, nullptr, nullptr) == SQLITE_OK) {
+      return true;
+    }
+    if (error) {
+      *error =
+          MakeError(sqlite3_errcode(db),
+                    [NSString stringWithFormat:@"Failed to commit TCC database transaction: %s", sqlite3_errmsg(db)]);
+    }
+  }
+  sqlite3_exec(db, "ROLLBACK", nullptr, nullptr, nullptr);
+  return false;
+}
+
+}  // namespace
+
+BOOL SetTCCAccess(NSString* dataPath, NSString* service, NSString* bundleId, BOOL granted, NSError** error) {
+  sqlite3* db = OpenDatabase(dataPath, error);
+  if (!db) {
+    return NO;
+  }
+
+  BOOL success = BeginTransaction(db, error);
+  if (success) {
+    success = DeleteAccessRow(db, service, bundleId, error);
+  }
+  if (success) {
+    if (HasAuthValueColumn(db)) {
+      // `kTCCServicePhotos` rows use auth_version 2 (supports the "limited" library access
+      // introduced alongside it); every other service uses version 1. Not exposing "limited"
+      // as a grantable status here — only plain granted/denied, matching grantPermission's BOOL.
+      BOOL isPhotos = [service isEqualToString:@"kTCCServicePhotos"];
+      success = ExecuteStatement(
+          db,
+          "INSERT INTO access (service, client, client_type, auth_value, auth_reason, auth_version, flags) "
+          "VALUES (?, ?, 0, ?, 2, ?, 0)",
+          [&](sqlite3_stmt* stmt) {
+            BindText(stmt, 1, service);
+            BindText(stmt, 2, bundleId);
+            sqlite3_bind_int(stmt, 3, granted ? 2 : 0);
+            sqlite3_bind_int(stmt, 4, isPhotos ? 2 : 1);
+          },
+          error);
+    } else {
+      success = ExecuteStatement(
+          db, "REPLACE INTO access (service, client, client_type, allowed, prompt_count) VALUES (?, ?, 0, ?, 1)",
+          [&](sqlite3_stmt* stmt) {
+            BindText(stmt, 1, service);
+            BindText(stmt, 2, bundleId);
+            sqlite3_bind_int(stmt, 3, granted ? 1 : 0);
+          },
+          error);
+    }
+  }
+
+  success = CommitOrRollback(db, success, error);
+  sqlite3_close(db);
+  return success;
+}
+
+BOOL ResetTCCAccess(NSString* dataPath, NSString* service, NSString* bundleId, NSError** error) {
+  sqlite3* db = OpenDatabase(dataPath, error);
+  if (!db) {
+    return NO;
+  }
+  BOOL success = DeleteAccessRow(db, service, bundleId, error);
+  sqlite3_close(db);
+  return success;
+}
+
+BOOL GetTCCAccess(NSString* dataPath, NSString* service, NSString* bundleId, TCCAuthStatus* outStatus,
+                  NSError** error) {
+  sqlite3* db = OpenDatabase(dataPath, error);
+  if (!db) {
+    return NO;
+  }
+
+  bool hasAuthValue = HasAuthValueColumn(db);
+  const char* sql = hasAuthValue ? "SELECT auth_value FROM access WHERE service = ? AND client = ? AND client_type = 0"
+                                 : "SELECT allowed FROM access WHERE service = ? AND client = ? AND client_type = 0";
+  sqlite3_stmt* stmt = nullptr;
+  if (sqlite3_prepare_v2(db, sql, -1, &stmt, nullptr) != SQLITE_OK) {
+    if (error) {
+      *error =
+          MakeError(sqlite3_errcode(db),
+                    [NSString stringWithFormat:@"Failed to prepare TCC database statement: %s", sqlite3_errmsg(db)]);
+    }
+    sqlite3_close(db);
+    return NO;
+  }
+  BindText(stmt, 1, service);
+  BindText(stmt, 2, bundleId);
+
+  BOOL success = YES;
+  TCCAuthStatus status = kTCCAuthNotDetermined;
+  int rc = sqlite3_step(stmt);
+  if (rc == SQLITE_ROW) {
+    int raw = sqlite3_column_int(stmt, 0);
+    if (hasAuthValue) {
+      // 0/2/3 per the schema comment in SetTCCAccess above; any other raw value (a reserved/future
+      // one this addon doesn't know about) is reported as not-determined rather than guessed at.
+      switch (raw) {
+        case 0:
+          status = kTCCAuthDenied;
+          break;
+        case 2:
+          status = kTCCAuthGranted;
+          break;
+        case 3:
+          status = kTCCAuthLimited;
+          break;
+        default:
+          status = kTCCAuthNotDetermined;
+          break;
+      }
+    } else {
+      status = raw ? kTCCAuthGranted : kTCCAuthDenied;
+    }
+  } else if (rc != SQLITE_DONE) {
+    success = NO;
+    if (error) {
+      *error = MakeError(rc, [NSString stringWithFormat:@"Failed to read TCC database: %s", sqlite3_errmsg(db)]);
+    }
+  }
+  sqlite3_finalize(stmt);
+  sqlite3_close(db);
+
+  if (success && outStatus) {
+    *outStatus = status;
+  }
+  return success;
+}
+
+}  // namespace coresim

package/src/native/value_bridge.h

@@ -0,0 +1,18 @@
+#pragma once
+
+#import <Foundation/Foundation.h>
+
+#include <napi.h>
+
+namespace coresim {
+
+// Converts a JS value (string/number/boolean/null/undefined/Array/plain Object/Buffer) into the
+// corresponding Foundation object (NSString/NSNumber/NSNull/NSArray/NSDictionary/NSData).
+// Used for option dictionaries (boot/install/uninstall options) and JSON payloads (push).
+NSObject* JsValueToNSObject(Napi::Env env, Napi::Value value);
+
+// Converts a Foundation object back into a JS value. Used for propertiesOfApplication/
+// installedApps/getenv results. NSNull -> null; unrecognized types -> their -description string.
+Napi::Value NSObjectToJsValue(Napi::Env env, id object);
+
+}  // namespace coresim