@inglorious/capacitor 0.2.0 → 0.3.0

package/README.md

@@ -65,20 +65,37 @@ The `native` key of `package.json` holds them all. Every key is optional; the ap
 
 ### What `configure` does
 
-| Setting                                   | iOS                                                                                                        | Android                                                        |
-| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| `appLinks`                                | Associated Domains entitlement                                                                             | Verified intent filter for `paths`                             |
-| `appLinks` + `teamId`                     | `public/.well-known/apple-app-site-association`                                                            |                                                                |
-| `appLinks` + `sha256`                     |                                                                                                            | `public/.well-known/assetlinks.json`                           |
-| `ios.teamId`                              | `DEVELOPMENT_TEAM`, so Xcode signs without asking                                                          |                                                                |
-| `ios.swipeBack`                           | A swipe from the left edge goes back: WebKit's back gesture, turned on in a generated `MainViewController` |                                                                |
-| `ios.infoPlist`                           | Info.plist entries                                                                                         |                                                                |
-| `android.permissions`                     |                                                                                                            | `<uses-permission>` entries                                    |
-| `@capacitor-firebase/messaging` installed | Push entitlement, background mode, AppDelegate methods                                                     |                                                                |
-| `@capacitor-firebase/analytics` installed | Collection off until consent                                                                               | Collection off until consent, and no advertising ID permission |
-| `GoogleService-Info.plist` in the root    | Copied into the app target                                                                                 |                                                                |
-| `google-services.json` in the root        |                                                                                                            | Copied to `android/app/`                                       |
-| always                                    |                                                                                                            | Keystores kept out of git                                      |
+| Setting                                       | iOS                                                                                                        | Android                                                        |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `appLinks`                                    | Associated Domains entitlement                                                                             | Verified intent filter for `paths`                             |
+| `appLinks` + `teamId`                         | `public/.well-known/apple-app-site-association`                                                            |                                                                |
+| `appLinks` + `sha256`                         |                                                                                                            | `public/.well-known/assetlinks.json`                           |
+| `ios.teamId`                                  | `DEVELOPMENT_TEAM`, so Xcode signs without asking                                                          |                                                                |
+| `ios.swipeBack`                               | A swipe from the left edge goes back: WebKit's back gesture, turned on in a generated `MainViewController` |                                                                |
+| `ios.infoPlist`                               | Info.plist entries                                                                                         |                                                                |
+| `ios.privacyManifest`                         | `PrivacyInfo.xcprivacy` entries, with Apple's keys                                                         |                                                                |
+| `@capawesome/capacitor-live-update` installed | `PrivacyInfo.xcprivacy` declaring its use of `UserDefaults`, which it doesn't declare itself               |                                                                |
+| `android.permissions`                         |                                                                                                            | `<uses-permission>` entries                                    |
+| `@capacitor-firebase/messaging` installed     | Push entitlement, background mode, AppDelegate methods                                                     |                                                                |
+| `@capacitor-firebase/analytics` installed     | Collection off until consent                                                                               | Collection off until consent, and no advertising ID permission |
+| `GoogleService-Info.plist` in the root        | Copied into the app target                                                                                 |                                                                |
+| `google-services.json` in the root            |                                                                                                            | Copied to `android/app/`                                       |
+| always                                        |                                                                                                            | Keystores kept out of git                                      |
+
+The privacy manifest is merged with the one already in the project, so entries added by hand stay. Apple refuses a build that calls a required-reason API without a declared reason; `configure` declares the ones of known plugins that ship no manifest of their own, and `ios.privacyManifest` adds the app's:
+
+```json
+"privacyManifest": {
+  "NSPrivacyAccessedAPITypes": [
+    {
+      "NSPrivacyAccessedAPIType": "NSPrivacyAccessedAPICategoryUserDefaults",
+      "NSPrivacyAccessedAPITypeReasons": ["CA92.1"]
+    }
+  ]
+}
+```
+
+A file input that takes images (a `Button` with `accept="image/*"`) offers the camera on iOS, which closes the app unless `ios.infoPlist` has an `NSCameraUsageDescription`.
 
 Path patterns end in `*` to match a prefix: `/jobs*` is every path that starts with `/jobs`. `exclude` takes paths and, starting with `#`, fragments; only iOS can exclude, so on Android list in `paths` only what opens the app. Serve both `.well-known` files as `application/json`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/capacitor",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Configures Capacitor's native projects from package.json, makes their icons and splash screens from one logo, and the screenshots and graphics the stores ask for.",
   "author": "Matteo Antony Mistretta <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",

package/src/config.js

@@ -10,6 +10,15 @@ const CAPACITOR_CONFIG_FILES = [
 ]
 const PUSH_PLUGIN = "@capacitor-firebase/messaging"
 const ANALYTICS_PLUGIN = "@capacitor-firebase/analytics"
+const USER_DEFAULTS = {
+  NSPrivacyAccessedAPIType: "NSPrivacyAccessedAPICategoryUserDefaults",
+  NSPrivacyAccessedAPITypeReasons: ["CA92.1"],
+}
+// Plugins that call Apple's required-reason APIs without a privacy manifest of
+// their own, so the app has to declare them.
+const PLUGIN_API_TYPES = {
+  "@capawesome/capacitor-live-update": [USER_DEFAULTS],
+}
 
 /**
  * Everything `configure` and `assets` act on: the app's id and name from the
@@ -35,11 +44,14 @@ export async function readSettings(root, env = process.env) {
     appLinks: native.appLinks?.domain
       ? normalizeAppLinks(native.appLinks)
       : null,
-    ios: { teamId: null, infoPlist: {}, ...native.ios },
+    ios: { teamId: null, infoPlist: {}, privacyManifest: null, ...native.ios },
     android: { sha256: [], permissions: [], ...native.android },
     assets: native.assets ?? {},
     hasPush: PUSH_PLUGIN in dependencies,
     hasAnalytics: ANALYTICS_PLUGIN in dependencies,
+    accessedApiTypes: Object.entries(PLUGIN_API_TYPES)
+      .filter(([plugin]) => plugin in dependencies)
+      .flatMap(([, types]) => types),
   }
 }
 

package/src/configure/configure.test.js

@@ -10,6 +10,7 @@ import { tmpdir } from "node:os"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
 
+import plist from "plist"
 import { afterEach, beforeEach, describe, expect, it } from "vitest"
 
 import { configure } from "./index.js"
@@ -43,6 +44,7 @@ describe("configure", () => {
     expect(after.manifest).not.toContain("autoVerify")
     expect(after.plist).not.toContain("UIBackgroundModes")
     expect(after.appDelegate).toBe(before.appDelegate)
+    expect(after.privacyManifest).toBeNull()
     expect(after.gitignore).toMatch(/^\*\.jks$/m)
     expect(existsSync(path.join(root, "public"))).toBe(false)
   })
@@ -186,6 +188,90 @@ function writePackage(root, pkg) {
   writeFileSync(path.join(root, "package.json"), JSON.stringify(pkg))
 }
 
+describe("configure, privacy manifest", () => {
+  let root
+
+  beforeEach(() => {
+    root = mkdtempSync(path.join(tmpdir(), "inglorious-capacitor-"))
+    cpSync(FIXTURES, root, { recursive: true })
+  })
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true })
+  })
+
+  it("declares what plugins use without saying so, once, as a resource", async () => {
+    writePackage(root, {
+      dependencies: { "@capawesome/capacitor-live-update": "^8.0.0" },
+    })
+
+    await configure({ root, env: { CAPACITOR_CONFIG } })
+    const first = snapshot(root)
+    await configure({ root, env: { CAPACITOR_CONFIG } })
+
+    expect(snapshot(root)).toEqual(first)
+    expect(plist.parse(first.privacyManifest)).toEqual({
+      NSPrivacyTracking: false,
+      NSPrivacyTrackingDomains: [],
+      NSPrivacyCollectedDataTypes: [],
+      NSPrivacyAccessedAPITypes: [
+        {
+          NSPrivacyAccessedAPIType: "NSPrivacyAccessedAPICategoryUserDefaults",
+          NSPrivacyAccessedAPITypeReasons: ["CA92.1"],
+        },
+      ],
+    })
+    expect(first.pbxproj).toContain("PrivacyInfo.xcprivacy in Resources")
+    expect(first.pbxproj).not.toContain("PrivacyInfo.xcprivacy in Sources")
+  })
+
+  it("merges the declared entries with the manifest already there", async () => {
+    writeFileSync(
+      path.join(root, "ios", "App", "App", "PrivacyInfo.xcprivacy"),
+      plist.build({
+        NSPrivacyAccessedAPITypes: [
+          {
+            NSPrivacyAccessedAPIType:
+              "NSPrivacyAccessedAPICategoryUserDefaults",
+            NSPrivacyAccessedAPITypeReasons: ["1C8F.1"],
+          },
+        ],
+      }),
+    )
+    writePackage(root, {
+      dependencies: { "@capawesome/capacitor-live-update": "^8.0.0" },
+      native: {
+        ios: {
+          privacyManifest: {
+            NSPrivacyAccessedAPITypes: [
+              {
+                NSPrivacyAccessedAPIType:
+                  "NSPrivacyAccessedAPICategoryFileTimestamp",
+                NSPrivacyAccessedAPITypeReasons: ["C617.1"],
+              },
+            ],
+          },
+        },
+      },
+    })
+
+    await configure({ root, env: { CAPACITOR_CONFIG } })
+
+    expect(
+      plist.parse(snapshot(root).privacyManifest).NSPrivacyAccessedAPITypes,
+    ).toEqual([
+      {
+        NSPrivacyAccessedAPIType: "NSPrivacyAccessedAPICategoryUserDefaults",
+        NSPrivacyAccessedAPITypeReasons: ["1C8F.1", "CA92.1"],
+      },
+      {
+        NSPrivacyAccessedAPIType: "NSPrivacyAccessedAPICategoryFileTimestamp",
+        NSPrivacyAccessedAPITypeReasons: ["C617.1"],
+      },
+    ])
+  })
+})
+
 function snapshot(root) {
   const read = (...segments) => {
     const file = path.join(root, ...segments)
@@ -201,6 +287,7 @@ function snapshot(root) {
     entitlements: read("ios", "App", "App", "App.entitlements"),
     appDelegate: read("ios", "App", "App", "AppDelegate.swift"),
     viewController: read("ios", "App", "App", "MainViewController.swift"),
+    privacyManifest: read("ios", "App", "App", "PrivacyInfo.xcprivacy"),
     storyboard: read("ios", "App", "App", "Base.lproj", "Main.storyboard"),
     association: read("public", ".well-known", "apple-app-site-association"),
     assetLinks: read("public", ".well-known", "assetlinks.json"),

package/src/configure/ios.js

@@ -14,6 +14,8 @@ const ANALYTICS_OFF = {
   GOOGLE_ANALYTICS_IDFV_COLLECTION_ENABLED: false,
 }
 const GOOGLE_SERVICE_INFO = "GoogleService-Info.plist"
+const PRIVACY_MANIFEST = "PrivacyInfo.xcprivacy"
+const APP_GROUP = "App"
 const APP_DELEGATE = "AppDelegate.swift"
 const MAIN_VIEW_CONTROLLER = "MainViewController.swift"
 const MAIN_STORYBOARD = path.join("Base.lproj", "Main.storyboard")
@@ -113,11 +115,96 @@ export async function configureIos(project, settings) {
     addPushMethods(path.join(appRoot, APP_DELEGATE))
   }
 
+  if (settings.ios.privacyManifest || settings.accessedApiTypes.length) {
+    writePrivacyManifest(path.join(appRoot, PRIVACY_MANIFEST), settings)
+    if (
+      !readFileSync(pbxprojPath(settings.root), "utf8").includes(
+        PRIVACY_MANIFEST,
+      )
+    ) {
+      addResource(ios, PRIVACY_MANIFEST)
+    }
+  }
+
   if (settings.ios.swipeBack) {
     await enableSwipeBack(ios, settings.root, appRoot)
   }
 }
 
+/**
+ * Writes the app's privacy manifest: what is already in it, what the app
+ * declares in `ios.privacyManifest`, and the required-reason APIs its plugins
+ * use without declaring them.
+ */
+function writePrivacyManifest(file, settings) {
+  const current = existsSync(file)
+    ? plist.parse(readFileSync(file, "utf8"))
+    : {}
+  const declared = settings.ios.privacyManifest ?? {}
+  const next = {
+    ...current,
+    ...declared,
+    NSPrivacyTracking:
+      declared.NSPrivacyTracking ?? current.NSPrivacyTracking ?? false,
+    NSPrivacyTrackingDomains: union(
+      current.NSPrivacyTrackingDomains,
+      declared.NSPrivacyTrackingDomains,
+    ),
+    NSPrivacyCollectedDataTypes:
+      declared.NSPrivacyCollectedDataTypes ??
+      current.NSPrivacyCollectedDataTypes ??
+      [],
+    NSPrivacyAccessedAPITypes: mergeApiTypes([
+      ...(current.NSPrivacyAccessedAPITypes ?? []),
+      ...(declared.NSPrivacyAccessedAPITypes ?? []),
+      ...settings.accessedApiTypes,
+    ]),
+  }
+  if (JSON.stringify(next) === JSON.stringify(current)) return
+  writeFileSync(file, plist.build(next))
+}
+
+function mergeApiTypes(types) {
+  const byType = new Map()
+  for (const type of types) {
+    const name = type.NSPrivacyAccessedAPIType
+    byType.set(name, {
+      NSPrivacyAccessedAPIType: name,
+      NSPrivacyAccessedAPITypeReasons: union(
+        byType.get(name)?.NSPrivacyAccessedAPITypeReasons,
+        type.NSPrivacyAccessedAPITypeReasons,
+      ),
+    })
+  }
+  return [...byType.values()]
+}
+
+function union(first = [], second = []) {
+  return [...new Set([...first, ...second])]
+}
+
+// Trapeze's addFile compiles any file that is not a .plist or .strings, and a
+// privacy manifest has to be copied into the bundle instead.
+function addResource(ios, fileName) {
+  const groups = ios.pbxProject?.hash.project.objects.PBXGroup ?? {}
+  const appGroup = Object.entries(groups).find(
+    ([, group]) =>
+      group.isa === "PBXGroup" &&
+      (group.name === APP_GROUP || group.path === APP_GROUP),
+  )
+  const [appGroupId] = appGroup ?? []
+  ios.addResourceFile(fileName, appGroupId)
+  const references = ios.pbxProject?.hash.project.objects.PBXFileReference ?? {}
+  for (const reference of Object.values(references)) {
+    if (reference?.path !== `"${fileName}"`) continue
+    reference.lastKnownFileType = "text.xml"
+    for (const [key, value] of Object.entries(reference)) {
+      if (value === undefined) delete reference[key]
+    }
+  }
+  ios.markPbxModified()
+}
+
 async function enableSwipeBack(ios, root, appRoot) {
   const controller = path.join(appRoot, MAIN_VIEW_CONTROLLER)
   if (!existsSync(controller)) {

package/types/index.d.ts

@@ -24,6 +24,12 @@ export interface NativeConfig {
      * WebKit's back gesture in a generated `MainViewController`.
      */
     swipeBack?: boolean
+    /**
+     * Entries of the app's `PrivacyInfo.xcprivacy`, with Apple's keys. Merged
+     * with the manifest already there and with the required-reason APIs of
+     * known plugins that do not declare their own.
+     */
+    privacyManifest?: PrivacyManifest
   }
   android?: {
     /** SHA-256 fingerprints of the keys that sign the app, for App Links. */
@@ -45,6 +51,20 @@ export interface NativeConfig {
   }
 }
 
+/** An app's privacy manifest, with Apple's keys. */
+export interface PrivacyManifest {
+  NSPrivacyTracking?: boolean
+  NSPrivacyTrackingDomains?: string[]
+  NSPrivacyCollectedDataTypes?: Record<string, unknown>[]
+  NSPrivacyAccessedAPITypes?: AccessedApiType[]
+}
+
+/** A required-reason API and why the app calls it. */
+export interface AccessedApiType {
+  NSPrivacyAccessedAPIType: string
+  NSPrivacyAccessedAPITypeReasons: string[]
+}
+
 export interface ProjectSettings {
   root: string
   appId: string
@@ -54,11 +74,14 @@ export interface ProjectSettings {
     teamId: string | null
     infoPlist: Record<string, unknown>
     swipeBack?: boolean
+    privacyManifest: PrivacyManifest | null
   }
   android: { sha256: string[]; permissions: string[] }
   assets: NonNullable<NativeConfig["assets"]>
   hasPush: boolean
   hasAnalytics: boolean
+  /** Required-reason APIs the app's plugins use without declaring them. */
+  accessedApiTypes: AccessedApiType[]
 }
 
 /**