@appium/coresim 1.13.0 → 1.13.2

package/src/commands/permissions.ts

@@ -1,26 +1,8 @@
-import {execFile} from 'node:child_process';
-import {randomUUID} from 'node:crypto';
-import {once} from 'node:events';
-import path from 'node:path';
-import {promisify} from 'node:util';
-
-import {fs, plist} from '@appium/support';
-import {waitForCondition} from 'asyncbox';
-
 import type {NativeSimctl} from '../native-simctl.js';
 import {SimDeviceState, type SimPermissionService, type SimPermissionStatus} from '../types.js';
-import {runCatchingAsync} from '../utils/index.js';
-
-const execFileAsync = promisify(execFile);
+import {BulletinBoardStore, runCatchingAsync, SpringBoard, type NotificationsStatus} from '../utils/index.js';
 
 const NOTIFICATIONS_SERVICE = 'notifications';
-const SPRINGBOARD_SERVICE = 'com.apple.SpringBoard';
-// The `sectionInfoVersionNumber` of the BulletinBoard stores SpringBoard writes (iOS 18 and 26).
-const BULLETIN_BOARD_STORE_VERSION = 2;
-const SPRINGBOARD_RESTART_TIMEOUT_MS = 30000;
-
-// The last pending notifications update of each BulletinBoard store, see withStoreLock.
-const storeUpdates = new Map<string, Promise<void>>();
 
 declare module '../native-simctl.js' {
   interface NativeSimctl {
@@ -178,27 +160,27 @@ function toTCCIdentifier(service: Exclude<SimPermissionService, 'notifications'>
 }
 
 /**
- * `notifications` isn't a TCC row: SpringBoard keeps it per app in its BulletinBoard store
- * (`Library/BulletinBoard/VersionedSectionInfo.plist`), reads that file only on its own start and
- * rewrites it from memory from time to time (e.g. a few seconds after it starts). So SpringBoard of
- * a booted device is paused while the app's section is written, then restarted with the store kept
- * immutable until the old process is gone. The new SpringBoard loads the change and terminates
- * every running app. A shut down device only gets the file, SpringBoard loads it on boot.
+ * `notifications` isn't a TCC row: SpringBoard keeps it per app in its BulletinBoard store, reads
+ * that file only on its own start and rewrites it from memory from time to time (e.g. a few seconds
+ * after it starts). So SpringBoard of a booted device is paused while the app's section is written,
+ * then restarted with the store kept immutable until the old process is gone. The new SpringBoard
+ * loads the change and terminates every running app. A shut down device only gets the file,
+ * SpringBoard loads it on boot.
  */
 async function setNotificationsAccess(
   this: NativeSimctl,
   udid: string,
   bundleId: string,
-  status: 'granted' | 'denied' | 'critical' | 'unset',
+  status: NotificationsStatus,
 ): Promise<void> {
   const device = await this._findDevice(udid);
-  const storePath = path.join(device.dataPath(), 'Library', 'BulletinBoard', 'VersionedSectionInfo.plist');
-  await withStoreLock(storePath, async () => {
+  const store = new BulletinBoardStore(device.dataPath(), this._options.bulletinBoardVersions);
+  await store.withLock(async () => {
     const springBoard = device.state() === SimDeviceState.Booted ? new SpringBoard(this, udid) : undefined;
     await springBoard?.pause();
     let written = false;
     try {
-      written = await writeNotificationsSection(storePath, bundleId, status);
+      written = await store.setNotificationsStatus(bundleId, status);
     } finally {
       if (!written) {
         springBoard?.resume();
@@ -207,243 +189,11 @@ async function setNotificationsAccess(
     if (!springBoard || !written) {
       return;
     }
-    await setImmutable(storePath, true);
+    await store.setImmutable(true);
     try {
       await springBoard.restart();
     } finally {
-      await setImmutable(storePath, false);
-    }
-  });
-}
-
-/**
- * Runs `update` once every earlier update of the same store has settled: concurrent updates for
- * different apps would otherwise read the same store, and the last write would drop the other app's
- * section. Only the calls made by this process are serialized.
- */
-async function withStoreLock(storePath: string, update: () => Promise<void>): Promise<void> {
-  const result = (storeUpdates.get(storePath) ?? Promise.resolve()).then(update);
-  const settled = result.catch(() => {});
-  storeUpdates.set(storePath, settled);
-  try {
-    await result;
-  } finally {
-    if (storeUpdates.get(storePath) === settled) {
-      storeUpdates.delete(storePath);
+      await store.setImmutable(false);
     }
-  }
-}
-
-/**
- * Adds, replaces or (`unset`) removes the app's section. The store is replaced atomically, so a
- * failed write leaves the previous one intact. A device that has never been booted has no store yet:
- * it is created with just this section, and SpringBoard adds the rest on boot.
- *
- * @returns `false` if there was nothing to write (`unset` without a store)
- */
-async function writeNotificationsSection(
-  storePath: string,
-  bundleId: string,
-  status: 'granted' | 'denied' | 'critical' | 'unset',
-): Promise<boolean> {
-  let store: {sectionInfoVersionNumber?: number; sectionInfo?: Record<string, Uint8Array>};
-  if (await fs.exists(storePath)) {
-    store = (await plist.parsePlistFile(storePath)) as typeof store;
-  } else if (status === 'unset') {
-    return false;
-  } else {
-    await fs.mkdir(path.dirname(storePath), {recursive: true});
-    store = {sectionInfoVersionNumber: BULLETIN_BOARD_STORE_VERSION};
-  }
-  const sectionInfo = store.sectionInfo ?? {};
-  if (status === 'unset') {
-    delete sectionInfo[bundleId];
-  } else {
-    sectionInfo[bundleId] = buildNotificationsSectionInfo(bundleId, status);
-  }
-  store.sectionInfo = sectionInfo;
-  // In the same directory, so that the rename is atomic.
-  const tmpPath = `${storePath}.${randomUUID()}.tmp`;
-  try {
-    await fs.writeFile(tmpPath, plist.createPlist(store, false), {flag: 'wx'});
-    await fs.rename(tmpPath, storePath);
-  } catch (err) {
-    await fs.unlink(tmpPath).catch(() => {});
-    throw err;
-  }
-  return true;
-}
-
-/**
- * Builds the NSKeyedArchiver-encoded `BBSectionInfo` of `bundleId`, the same archive
- * AppleSimulatorUtils writes (SetNotificationsPermission.m). SpringBoard migrates its
- * `allowsNotifications` flag to the current `authorizationStatus` when it loads the section.
- */
-function buildNotificationsSectionInfo(bundleId: string, status: 'granted' | 'denied' | 'critical'): Buffer {
-  const nil = {UID: 0};
-  return plist.createBinaryPlist({
-    $version: 100000,
-    $objects: [
-      '$null',
-      {
-        suppressFromSettings: false,
-        suppressedSettings: 0,
-        hideWeeApp: false,
-        sectionID: {UID: 2},
-        displayName: {UID: 5},
-        icon: nil,
-        displaysCriticalBulletins: false,
-        subsections: nil,
-        sectionInfoSettings: {UID: 3},
-        $class: {UID: 7},
-        sectionCategory: 0,
-        subsectionPriority: 0,
-        version: {UID: 6},
-        managedSectionInfoSettings: nil,
-        appName: {UID: 5},
-        sectionType: 0,
-        factorySectionID: nil,
-        dataProviderIDs: nil,
-        subsectionID: nil,
-        filters: nil,
-        pathToWeeAppPluginBundle: nil,
-      },
-      bundleId,
-      {
-        pushSettings: 63,
-        showsInNotificationCenter: true,
-        allowsNotifications: status !== 'denied',
-        showsOnExternalDevices: true,
-        contentPreviewSetting: 0,
-        carPlaySetting: 0,
-        $class: {UID: 4},
-        showsInLockScreen: true,
-        alertType: 1,
-        criticalAlertSetting: status === 'critical' ? 2 : 0,
-      },
-      {$classname: 'BBSectionInfoSettings', $classes: ['BBSectionInfoSettings', 'NSObject']},
-      bundleId,
-      0,
-      {$classname: 'BBSectionInfo', $classes: ['BBSectionInfo', 'NSObject']},
-    ],
-    $archiver: 'NSKeyedArchiver',
-    $top: {root: {UID: 1}},
   });
 }
-
-async function setImmutable(filePath: string, immutable: boolean): Promise<void> {
-  try {
-    await execFileAsync('chflags', [immutable ? 'uchg' : 'nouchg', filePath]);
-  } catch {}
-}
-
-/**
- * SpringBoard of a booted device: the process that owns the BulletinBoard store, see
- * setNotificationsAccess. The simulator shares the host kernel, so it is signalled directly.
- */
-class SpringBoard {
-  private pausedPid: number | undefined;
-
-  constructor(
-    private readonly simctl: NativeSimctl,
-    private readonly udid: string,
-  ) {}
-
-  /**
-   * Pauses the running SpringBoard so that it cannot rewrite the BulletinBoard store. It can be in
-   * the middle of a restart, hence the retries.
-   */
-  async pause(): Promise<void> {
-    try {
-      await waitForCondition(
-        async () => {
-          const pid = await this.pid().catch(() => undefined);
-          if (pid && sendSignal(pid, 'SIGSTOP')) {
-            this.pausedPid = pid;
-          }
-          return Boolean(this.pausedPid);
-        },
-        {waitMs: SPRINGBOARD_RESTART_TIMEOUT_MS, intervalMs: 300},
-      );
-    } catch {}
-    if (!this.pausedPid) {
-      throw new Error(`${SPRINGBOARD_SERVICE} is not running`);
-    }
-  }
-
-  /** Lets the paused SpringBoard run again. */
-  resume(): void {
-    if (this.pausedPid) {
-      sendSignal(this.pausedPid, 'SIGCONT');
-    }
-  }
-
-  /**
-   * Replaces the paused SpringBoard with a new one: asks launchd to stop it (launchd starts a new
-   * one right away), resumes it so that it can exit, then waits for the new process.
-   */
-  async restart(): Promise<void> {
-    const previousPid = this.pausedPid;
-    try {
-      await this.stop();
-    } finally {
-      this.resume();
-      this.pausedPid = undefined;
-    }
-    try {
-      await waitForCondition(
-        async () => {
-          const pid = await this.pid().catch(() => undefined);
-          return Number.isInteger(pid) && pid !== previousPid;
-        },
-        {waitMs: SPRINGBOARD_RESTART_TIMEOUT_MS, intervalMs: 300},
-      );
-    } catch {
-      throw new Error(`${SPRINGBOARD_SERVICE} did not restart within ${SPRINGBOARD_RESTART_TIMEOUT_MS}ms`);
-    }
-  }
-
-  private async pid(): Promise<number | undefined> {
-    return (await this.simctl.listProcesses(this.udid)).find(({name}) => name === SPRINGBOARD_SERVICE)?.pid;
-  }
-
-  private async stop(): Promise<void> {
-    // Bare name: resolved against the guest runtime's own bin dirs, like in listProcesses.
-    const proc = await this.simctl.spawnProcess(this.udid, 'launchctl', {
-      arguments: ['launchctl', 'stop', SPRINGBOARD_SERVICE],
-    });
-    let stderr = '';
-    proc.stdout.resume();
-    proc.stderr.on('data', (chunk: Buffer) => {
-      stderr += chunk;
-    });
-    const streamError = Promise.race([once(proc.stdout, 'error'), once(proc.stderr, 'error')]).then(([err]) => {
-      throw err;
-    });
-    const [[code, signal]] = await Promise.race([
-      Promise.all([once(proc, 'exit'), once(proc.stderr, 'end')]),
-      streamError,
-    ]);
-    if (code !== 0) {
-      const reason = signal ? `signal ${signal}` : `exit code ${code}`;
-      throw new Error(
-        `'launchctl stop ${SPRINGBOARD_SERVICE}' failed with ${reason}${stderr.trim() ? `: ${stderr.trim()}` : ''}`,
-      );
-    }
-  }
-}
-
-/**
- * @returns `false` if the process no longer exists
- */
-function sendSignal(pid: number, name: NodeJS.Signals): boolean {
-  try {
-    process.kill(pid, name);
-    return true;
-  } catch (err: any) {
-    if (err?.code === 'ESRCH') {
-      return false;
-    }
-    throw err;
-  }
-}

package/src/index.ts

@@ -1,5 +1,5 @@
 export {NativeSimError, NativeSimUnavailableError, NativeSimDispatchError, NativeSimOperationError} from './errors.js';
-export {NativeSimctl} from './native-simctl.js';
+export {NativeSimctl, type NativeSimctlOptions} from './native-simctl.js';
 export {SpawnedProcess} from './commands/spawn.js';
 export {VideoStream} from './commands/video-stream.js';
 export {JpegStream} from './commands/jpeg-stream.js';

package/src/native-simctl.ts

@@ -56,6 +56,13 @@ import {
 import {isVideoRecording, startVideoRecording, stopVideoRecording} from './commands/video-recording.js';
 import {startVideoStream} from './commands/video-stream.js';
 import {getWebInspectorSocket} from './commands/webinspector.js';
+import {NativeSimUnavailableError} from './errors.js';
+import type {
+  NativeCoreSimModule,
+  NativeDeviceHandle,
+  NativeDeviceSetHandle,
+  NativeServiceContextHandle,
+} from './types.js';
 // Bare re-imports so `declare module './native-simctl.js'` augmentations in the command modules
 // (which add their methods to NativeSimctl's type) reach downstream consumers' emitted .d.ts
 // import graph — the named imports above alone aren't part of NativeSimctl's emitted type
@@ -78,17 +85,26 @@ import './commands/ui.js';
 import './commands/video-recording.js';
 import './commands/video-stream.js';
 import './commands/webinspector.js';
-import {NativeSimUnavailableError} from './errors.js';
-import type {
-  NativeCoreSimModule,
-  NativeDeviceHandle,
-  NativeDeviceSetHandle,
-  NativeServiceContextHandle,
-} from './types.js';
 import {getPkgRoot, PACKAGE_NAME, runCatchingAsync} from './utils/index.js';
 
 const require = createRequire(import.meta.url);
 
+export interface NativeSimctlOptions {
+  /** Defaults to `xcode-select -p` (the active Xcode's Developer dir). */
+  developerDir?: string;
+  /**
+   * Defaults to the default device set (`~/Library/Developer/CoreSimulator/Devices`), same as
+   * `simctl --set <path>`.
+   */
+  deviceSetPath?: string;
+  /**
+   * The versions of SpringBoard's notifications store (`sectionInfoVersionNumber`) the runtimes in
+   * use may have, the oldest first. Defaults to all the known ones; callers that know their Xcode
+   * narrow it. A store of any other version is refused.
+   */
+  bulletinBoardVersions?: readonly number[];
+}
+
 /**
  * Drives `CoreSimulator.framework` directly — no `simctl`/`xcrun` subprocess — for the operations
  * `node-simctl`'s `Simctl` class exposes over the CLI. Devices are addressed by UDID; each call
@@ -110,18 +126,28 @@ const require = createRequire(import.meta.url);
 export class NativeSimctl {
   private cachedServiceContext: Promise<NativeServiceContextHandle> | undefined;
 
+  /** @internal Read by the command mixins. */
+  readonly _options: Readonly<NativeSimctlOptions>;
+
   /**
-   * @param developerDir — defaults to `xcode-select -p` (the active Xcode's Developer dir).
-   * @param deviceSetPath — defaults to the default device set
-   * (`~/Library/Developer/CoreSimulator/Devices`), same as `simctl --set <path>`. Constructing a
-   * NativeSimctl must never throw — the platform check and the native sharedServiceContext call
-   * both happen lazily in the `_serviceContext` getter below, so only a method that actually needs
-   * the simulator (getDevices(), createDevice(), ...) can raise.
+   * Constructing a NativeSimctl must never throw — the platform check and the native
+   * sharedServiceContext call both happen lazily in the `_serviceContext` getter below, so only a
+   * method that actually needs the simulator (getDevices(), createDevice(), ...) can raise.
+   *
+   * @param options — see {@link NativeSimctlOptions}.
    */
-  constructor(
-    private readonly developerDir?: string,
-    private readonly deviceSetPath?: string,
-  ) {}
+  constructor(options?: NativeSimctlOptions);
+  /**
+   * @deprecated Pass {@link NativeSimctlOptions} instead.
+   * @param developerDir — see {@link NativeSimctlOptions.developerDir}.
+   * @param deviceSetPath — see {@link NativeSimctlOptions.deviceSetPath}.
+   */
+  constructor(developerDir?: string, deviceSetPath?: string);
+  constructor(optionsOrDeveloperDir?: NativeSimctlOptions | string, deviceSetPath?: string) {
+    this._options = util.isPlainObject(optionsOrDeveloperDir)
+      ? {...(optionsOrDeveloperDir as NativeSimctlOptions)}
+      : {developerDir: optionsOrDeveloperDir as string | undefined, deviceSetPath};
+  }
 
   /** @returns `CFBundleVersion` of the loaded `CoreSimulator.framework` (e.g. `"1171.6"`). */
   static async frameworkVersion(): Promise<string> {
@@ -143,7 +169,7 @@ export class NativeSimctl {
   async _serviceContext(): Promise<NativeServiceContextHandle> {
     if (!this.cachedServiceContext) {
       this.cachedServiceContext = runCatchingAsync(() =>
-        loadNative().sharedServiceContext(this.developerDir ?? defaultDeveloperDir()),
+        loadNative().sharedServiceContext(this._options.developerDir ?? defaultDeveloperDir()),
       ).catch((err: unknown) => {
         this.cachedServiceContext = undefined;
         throw err;
@@ -155,7 +181,7 @@ export class NativeSimctl {
   /** @internal Not part of the public API — exposed only so `src/commands/*.ts` mixins can call it. */
   async _deviceSet(): Promise<NativeDeviceSetHandle> {
     const context = await this._serviceContext();
-    const deviceSetPath = this.deviceSetPath;
+    const deviceSetPath = this._options.deviceSetPath;
     return runCatchingAsync(() =>
       deviceSetPath ? context.deviceSetWithPath(deviceSetPath) : context.defaultDeviceSet(),
     );

package/src/utils/bulletin-board-model-v2.ts

@@ -0,0 +1,79 @@
+import {plist} from '@appium/support';
+
+import type {BulletinBoardModel, NotificationsStatus} from './bulletin-board-model.js';
+
+/** The format used by SpringBoard since iOS 18. */
+export const bulletinBoardModelV2: BulletinBoardModel = {
+  version: 2,
+  createStore: () => ({sectionInfoVersionNumber: 2}),
+  setNotificationsStatus(store, bundleId, status) {
+    const sectionInfo = (store.sectionInfo ??= {});
+    if (status === 'unset') {
+      delete sectionInfo[bundleId];
+    } else {
+      sectionInfo[bundleId] = buildSectionInfo(bundleId, status);
+    }
+  },
+};
+
+/**
+ * Builds the NSKeyedArchiver-encoded `BBSectionInfo` of `bundleId`, the same archive
+ * AppleSimulatorUtils writes (SetNotificationsPermission.m). SpringBoard migrates its
+ * `allowsNotifications` flag to the current `authorizationStatus` when it loads the section.
+ */
+export function buildSectionInfo(
+  bundleId: string,
+  status: Exclude<NotificationsStatus, 'unset'>,
+  extraSectionKeys: Record<string, unknown> = {},
+): Buffer {
+  const nil = {UID: 0};
+  return plist.createBinaryPlist({
+    $version: 100000,
+    $objects: [
+      '$null',
+      {
+        suppressFromSettings: false,
+        suppressedSettings: 0,
+        hideWeeApp: false,
+        sectionID: {UID: 2},
+        displayName: {UID: 5},
+        icon: nil,
+        displaysCriticalBulletins: false,
+        subsections: nil,
+        sectionInfoSettings: {UID: 3},
+        $class: {UID: 7},
+        sectionCategory: 0,
+        subsectionPriority: 0,
+        version: {UID: 6},
+        managedSectionInfoSettings: nil,
+        appName: {UID: 5},
+        sectionType: 0,
+        factorySectionID: nil,
+        dataProviderIDs: nil,
+        subsectionID: nil,
+        filters: nil,
+        pathToWeeAppPluginBundle: nil,
+        ...extraSectionKeys,
+      },
+      bundleId,
+      {
+        pushSettings: 63,
+        showsInNotificationCenter: true,
+        allowsNotifications: status !== 'denied',
+        showsOnExternalDevices: true,
+        contentPreviewSetting: 0,
+        carPlaySetting: 0,
+        $class: {UID: 4},
+        showsInLockScreen: true,
+        alertType: 1,
+        criticalAlertSetting: status === 'critical' ? 2 : 0,
+      },
+      {$classname: 'BBSectionInfoSettings', $classes: ['BBSectionInfoSettings', 'NSObject']},
+      bundleId,
+      0,
+      {$classname: 'BBSectionInfo', $classes: ['BBSectionInfo', 'NSObject']},
+    ],
+    $archiver: 'NSKeyedArchiver',
+    $top: {root: {UID: 1}},
+  });
+}

package/src/utils/bulletin-board-model-v3.ts

@@ -0,0 +1,16 @@
+import {buildSectionInfo} from './bulletin-board-model-v2.js';
+import type {BulletinBoardModel} from './bulletin-board-model.js';
+
+/** The format used by SpringBoard since iOS 27: v2 with `isLocked` in the `BBSectionInfo`. */
+export const bulletinBoardModelV3: BulletinBoardModel = {
+  version: 3,
+  createStore: () => ({sectionInfoVersionNumber: 3}),
+  setNotificationsStatus(store, bundleId, status) {
+    const sectionInfo = (store.sectionInfo ??= {});
+    if (status === 'unset') {
+      delete sectionInfo[bundleId];
+    } else {
+      sectionInfo[bundleId] = buildSectionInfo(bundleId, status, {isLocked: false});
+    }
+  },
+};

package/src/utils/bulletin-board-model.ts

@@ -0,0 +1,20 @@
+export type NotificationsStatus = 'granted' | 'denied' | 'critical' | 'unset';
+
+/** Content of `VersionedSectionInfo.plist`. */
+export interface BulletinBoardStoreContent {
+  sectionInfoVersionNumber?: number;
+  sectionInfo?: Record<string, Uint8Array>;
+}
+
+/**
+ * The data model of one `sectionInfoVersionNumber` of the BulletinBoard store. The store operations
+ * (locking, atomic replace, ...) don't depend on it, so a new format version only needs a new model.
+ */
+export interface BulletinBoardModel {
+  /** The `sectionInfoVersionNumber` this model reads and writes. */
+  readonly version: number;
+  /** An empty store, as SpringBoard of this version would start it. */
+  createStore(): BulletinBoardStoreContent;
+  /** Adds, replaces or (`unset`) removes the app's notifications section in place. */
+  setNotificationsStatus(store: BulletinBoardStoreContent, bundleId: string, status: NotificationsStatus): void;
+}

package/src/utils/bulletin-board-store.ts

@@ -0,0 +1,126 @@
+import {execFile} from 'node:child_process';
+import {randomUUID} from 'node:crypto';
+import path from 'node:path';
+import {promisify} from 'node:util';
+
+import {fs, plist} from '@appium/support';
+
+import {bulletinBoardModelV2} from './bulletin-board-model-v2.js';
+import {bulletinBoardModelV3} from './bulletin-board-model-v3.js';
+import type {BulletinBoardModel, BulletinBoardStoreContent, NotificationsStatus} from './bulletin-board-model.js';
+
+const execFileAsync = promisify(execFile);
+
+// All the known data models, the oldest first.
+const KNOWN_MODELS: readonly BulletinBoardModel[] = [bulletinBoardModelV2, bulletinBoardModelV3];
+
+// The last pending update of each store, see BulletinBoardStore.withLock.
+const pendingUpdates = new Map<string, Promise<void>>();
+
+/**
+ * SpringBoard's BulletinBoard store of a device (`Library/BulletinBoard/VersionedSectionInfo.plist`),
+ * which keeps the notifications settings of every app as one archived `BBSectionInfo` per bundle id.
+ */
+export class BulletinBoardStore {
+  readonly path: string;
+  private readonly models: readonly BulletinBoardModel[];
+
+  /**
+   * @param dataPath — data directory of the device
+   * @param versions — the `sectionInfoVersionNumber`s supported by the runtime, the oldest first
+   * (all the known ones by default). A store of any other version is refused, as the format may
+   * change in a future runtime. A missing store (a never-booted device) is created in the first
+   * one, as SpringBoard migrates older versions but not newer ones.
+   * @throws {Error} if a version is unknown
+   */
+  constructor(dataPath: string, versions: readonly number[] = KNOWN_MODELS.map(({version}) => version)) {
+    this.models = versions.map((version) => {
+      const model = KNOWN_MODELS.find((m) => m.version === version);
+      if (!model) {
+        throw new Error(`Unknown BulletinBoard store version ${version}`);
+      }
+      return model;
+    });
+    this.path = path.join(dataPath, 'Library', 'BulletinBoard', 'VersionedSectionInfo.plist');
+  }
+
+  /**
+   * Runs `update` once every earlier update of the same store has settled: concurrent updates for
+   * different apps would otherwise read the same store, and the last write would drop the other app's
+   * section. Only the calls made by this process are serialized.
+   */
+  async withLock<T>(update: () => Promise<T>): Promise<T> {
+    const result = (pendingUpdates.get(this.path) ?? Promise.resolve()).then(update);
+    const settled = result.then(
+      () => {},
+      () => {},
+    );
+    pendingUpdates.set(this.path, settled);
+    try {
+      return await result;
+    } finally {
+      if (pendingUpdates.get(this.path) === settled) {
+        pendingUpdates.delete(this.path);
+      }
+    }
+  }
+
+  /**
+   * Adds, replaces or (`unset`) removes the app's section. The store is replaced atomically, so a
+   * failed write leaves the previous one intact. A device that has never been booted has no store
+   * yet: it is created with just this section, and SpringBoard adds the rest on boot.
+   *
+   * @returns `false` if there was nothing to write (`unset` without a store)
+   * @throws {Error} if the existing store is of an unsupported format version
+   */
+  async setNotificationsStatus(bundleId: string, status: NotificationsStatus): Promise<boolean> {
+    let store: BulletinBoardStoreContent;
+    let model: BulletinBoardModel;
+    if (await fs.exists(this.path)) {
+      store = (await plist.parsePlistFile(this.path)) as BulletinBoardStoreContent;
+      model = this.modelOf(store);
+    } else if (status === 'unset') {
+      return false;
+    } else {
+      await fs.mkdir(path.dirname(this.path), {recursive: true});
+      model = this.models[0];
+      store = model.createStore();
+    }
+    model.setNotificationsStatus(store, bundleId, status);
+    await this.replace(store);
+    return true;
+  }
+
+  /**
+   * Makes the store immutable (`uchg`) so that nothing, including a dying SpringBoard, can rewrite it.
+   * Best effort.
+   */
+  async setImmutable(immutable: boolean): Promise<void> {
+    try {
+      await execFileAsync('chflags', [immutable ? 'uchg' : 'nouchg', this.path]);
+    } catch {}
+  }
+
+  private modelOf(store: BulletinBoardStoreContent): BulletinBoardModel {
+    const model = this.models.find(({version}) => version === store.sectionInfoVersionNumber);
+    if (!model) {
+      throw new Error(
+        `Unsupported version of ${this.path}: sectionInfoVersionNumber is ${store.sectionInfoVersionNumber}, ` +
+          `supported: ${this.models.map(({version}) => version).join(', ')}`,
+      );
+    }
+    return model;
+  }
+
+  private async replace(store: BulletinBoardStoreContent): Promise<void> {
+    // In the same directory, so that the rename is atomic.
+    const tmpPath = `${this.path}.${randomUUID()}.tmp`;
+    try {
+      await fs.writeFile(tmpPath, plist.createPlist(store, false), {flag: 'wx'});
+      await fs.rename(tmpPath, this.path);
+    } catch (err) {
+      await fs.unlink(tmpPath).catch(() => {});
+      throw err;
+    }
+  }
+}

package/src/utils/index.ts

@@ -1,3 +1,6 @@
 export {getPkgRoot, PACKAGE_NAME} from './pkg-root.js';
 export {runCatchingAsync, toTypedError} from './run-catching.js';
 export {resolveDisplayPortId, validateDisplayId} from './display.js';
+export {BulletinBoardStore} from './bulletin-board-store.js';
+export type {NotificationsStatus} from './bulletin-board-model.js';
+export {SpringBoard} from './springboard.js';