@livx.cc/appwrap 0.59.0 → 0.60.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.59.0",
+  "version": "0.60.0",
   "description": "Wrap any PWA into a native app with native capabilities (appwrap runtime + @livx.cc/native-kit).",
   "license": "MIT",
   "author": "Elya Livshitz",

package/runtime/app/main-page.ts

@@ -86,7 +86,7 @@ function armNativeSurfaceRecovery(webView: CustomWebView): void {
 
 export function onPageLoaded(args: EventData): void {
   const page = args.object as Page;
-  page.bindingContext = { backgroundColor: SHELL_CONFIG.backgroundColor };
+  page.bindingContext = { backgroundColor: SHELL_CONFIG.backgroundColor, appName: SHELL_CONFIG.name };
   bindStatusBarPage(page);
   if (isAndroid) enableAndroidEdgeToEdge();
   applyThemeColor(SHELL_CONFIG.themeColor); // manifest/config theme_color → native chrome at boot

package/runtime/app/main-page.xml

@@ -9,7 +9,7 @@
     <!-- loader:'server' load-failure fallback (App Review 2.1a): shown by main-page.ts when the
          server navigation fails (offline / server down) so the reviewer never sees a white screen. -->
     <StackLayout id="loadFallback" row="0" visibility="collapse" backgroundColor="#ffffff" verticalAlignment="center" padding="32">
-      <Label text="Blank" fontSize="34" fontWeight="700" color="#000000" textAlignment="center" />
+      <Label text="{{ appName }}" fontSize="34" fontWeight="700" color="#000000" textAlignment="center" />
       <Label text="Can't connect" fontSize="17" fontWeight="600" color="#333333" textAlignment="center" marginTop="18" />
       <Label text="Check your internet connection — we'll keep trying." fontSize="14" color="#777777" textAlignment="center" textWrap="true" marginTop="6" />
       <Button id="loadRetryBtn" text="Retry" fontSize="16" fontWeight="600" color="#ffffff" backgroundColor="#000000" borderRadius="22" height="44" width="160" marginTop="24" />

package/runtime/app/shell/config.ts

@@ -74,4 +74,11 @@ export const SHELL_CONFIG = {
    * inert. `envs` = declared presets; `allowPattern` = anchored regex gating "Other" (default-deny
    * when ''). Stamped by `appwrap init`/`sync` — see `stampShellConfig`. */
   envSwitcher: { enabled: false, envs: [] as { label: string; url: string }[], allowPattern: '' },
+  /** TCC-gated web APIs this build DECLARED (active modules + the config's `permissions{}`) — what the
+   * document-start capability guard exposes to the page. NOT the same question as "is the Info.plist
+   * usage string present": the plist also carries the webview baseline (NSCameraUsageDescription is
+   * stamped in every build so WKWebView's `<input type="file">` "Take Photo" can't TCC-kill the
+   * process), and an app that never asked for the camera must still not be handing `getUserMedia` to
+   * whatever page it renders. Stamped by `appwrap init`/`sync` — see `stampShellConfig`. */
+  webCaps: { camera: false, microphone: false, geolocation: false },
 };

package/runtime/app/shell/custom-webview.ios.ts

@@ -332,11 +332,15 @@ export class CustomWebView extends WebView {
     // (reject camera/mic/geolocation in JS before WebKit's native path — see capabilityGuardJs) +
     // native-feel suppression, all injected before the page's own scripts run. Globals first so the page
     // can read __APPWRAP__ / __APPWRAP_BACKEND_ORIGIN__.
-    const hasPlistKey = (k: string) => !!NSBundle.mainBundle.objectForInfoDictionaryKey(k);
+    // Driven by the STAMPED declaration, not by sniffing Info.plist: NSCameraUsageDescription is now
+    // present in every build (the webview baseline — so WKWebView's file-input "Take Photo" can't
+    // TCC-kill us), and reading presence would therefore open getUserMedia({video}) to every page an
+    // app renders, including ones a loader:'server' shell doesn't control. SHELL_CONFIG.webCaps is
+    // what the app actually declared (modules + `permissions{}`).
     const capabilityGuard = capabilityGuardJs({
-      camera: hasPlistKey('NSCameraUsageDescription'),
-      microphone: hasPlistKey('NSMicrophoneUsageDescription'),
-      geolocation: hasPlistKey('NSLocationWhenInUseUsageDescription'),
+      camera: SHELL_CONFIG.webCaps.camera,
+      microphone: SHELL_CONFIG.webCaps.microphone,
+      geolocation: SHELL_CONFIG.webCaps.geolocation,
     });
     const swGuard = serviceWorkerGuardJs(SHELL_CONFIG.neutralizeServiceWorker);
     const extNavGuard = externalNavGuardJs(SHELL_CONFIG.openNewWindowsInBrowser);

package/src/cli.ts

@@ -86,6 +86,12 @@ const IOS_PERMISSION_KEYS: Record<string, string[]> = {
   calendar: ['NSCalendarsFullAccessUsageDescription', 'NSCalendarsUsageDescription'],
 };
 
+/** Default copy for the always-stamped NSCameraUsageDescription (see "the webview baseline" in
+ * nativeReqs). Written for an App Review reader: it describes the ONLY way a plain appwrap app reaches
+ * the camera — choosing "Take Photo" from a file upload. An app that calls the camera directly (the
+ * `camera`/`scanner` modules, or its own `permissions.camera`) replaces this with its own copy. */
+const WEBVIEW_BASELINE_CAMERA_USAGE = 'Take a photo when you choose “Take Photo” while attaching a file.';
+
 /** Runtime permissions stamped into AndroidManifest.xml per declared domain.
  * photos/faceid need none: system picker / USE_BIOMETRIC is baseline. */
 const ANDROID_PERMISSION_KEYS: Record<string, string[]> = {
@@ -232,6 +238,11 @@ interface NativeReqs {
   activeOptIn: string[];           // opt-in capability names that are active (for the handshake map)
   activeOptionalGroups: string[];  // strippable handler groups (own file) that are active
   iosPlist: Array<{ key: string; usage: string }>;
+  /** What the app DECLARED it wants the web layer to be able to use — modules + `permissions{}`, and
+   * deliberately NOT the webview baseline. Drives the shell's document-start capability guard.
+   * Kept separate from `iosPlist` because the two answer different questions: the plist must cover
+   * everything the OS can kill us for REACHING, the guard must expose only what the app ASKED for. */
+  webCaps: { camera: boolean; microphone: boolean; geolocation: boolean };
   iosEntitlements: Record<string, boolean | string | string[]>;
   androidPerms: string[];
   androidGradleDeps: string[];
@@ -277,7 +288,11 @@ function nativeReqs(cfg: AppwrapConfig): NativeReqs {
       for (const p of m.ios?.permissions ?? []) {
         if (seenKeys.has(p.key)) continue;
         seenKeys.add(p.key);
-        iosPlist.push({ key: p.key, usage: cfg.permissions?.[p.domain as keyof typeof cfg.permissions] ?? p.defaultUsage });
+        // `permissions{}` overrides the module's default COPY. A `false` there is an opt-out of the
+        // webview baseline (below), never of a module's own key — the module ships native code that
+        // touches the class, so the string is mandatory; fall back to the default copy.
+        const override = cfg.permissions?.[p.domain as keyof typeof cfg.permissions];
+        iosPlist.push({ key: p.key, usage: typeof override === 'string' && override ? override : p.defaultUsage });
       }
       for (const ap of m.android?.permissions ?? []) androidPerms.add(ap);
       for (const g of m.android?.gradleDeps ?? []) gradle.add(g);
@@ -289,14 +304,52 @@ function nativeReqs(cfg: AppwrapConfig): NativeReqs {
       // resolves under the pack's own dir, so it must not be conflated with the built-in dir names.
       if (m.nativeSrc && !packInfo(m.name)) nativeSrc.push(m.nativeSrc);
     }
-  } else {
-    // legacy: only what `permissions{}` declares (via the key maps) — no behavior change
-    for (const [domain, text] of Object.entries(cfg.permissions ?? {})) {
-      for (const key of IOS_PERMISSION_KEYS[domain] ?? []) {
-        if (text && !seenKeys.has(key)) { seenKeys.add(key); iosPlist.push({ key, usage: text }); }
-      }
-      for (const p of ANDROID_PERMISSION_KEYS[domain] ?? []) androidPerms.add(p);
+  }
+
+  // A DECLARED permission is always stamped — in BOTH modes. Before, `permissions{}` was read only in
+  // legacy mode; with `modules` present it merely overrode a module's usage copy, so declaring a domain
+  // no module owned stamped NOTHING. That silent inertness shipped a store rejection (Copy Bin,
+  // Guideline 2.1(a): TCC killed the app for a missing NSCameraUsageDescription). Module-derived keys are
+  // collected FIRST and win the dedupe, so an app whose declared domains its modules already own stamps
+  // byte-identically. `false` = an explicit opt-out (see the webview baseline below), never a usage string.
+  for (const [domain, text] of Object.entries(cfg.permissions ?? {})) {
+    if (text === false) continue;
+    for (const key of IOS_PERMISSION_KEYS[domain] ?? []) {
+      if (text && !seenKeys.has(key)) { seenKeys.add(key); iosPlist.push({ key, usage: text }); }
     }
+    for (const p of ANDROID_PERMISSION_KEYS[domain] ?? []) androidPerms.add(p);
+  }
+
+  // Snapshot the DECLARED capabilities before the baseline widens the plist — see NativeReqs.webCaps.
+  const webCaps = {
+    camera: seenKeys.has('NSCameraUsageDescription'),
+    microphone: seenKeys.has('NSMicrophoneUsageDescription'),
+    geolocation: seenKeys.has('NSLocationWhenInUseUsageDescription'),
+  };
+
+  // ── The webview baseline ───────────────────────────────────────────────────────────────────────
+  // The shell's invariant is that every TCC-gated capability a WEB PAGE can reach is either DECLARED
+  // (usage string present) or BLOCKED before WebKit enters its native path — see mediaCaptureGuardJs /
+  // geolocationGuardJs, which reject getUserMedia + geolocation in JS at document-start.
+  //
+  // `<input type="file">` is the one reachable path with no such seam: WKWebView's own picker is native
+  // and internal, it offers "Take Photo" for an image accept, and TCC hard-kills the HOST process for a
+  // camera access with no usage string. There is no JS hook to suppress that menu item and no config in
+  // which it is absent — EVERY appwrap iOS build can reach it. When the answer is unconditional the
+  // correct mechanism is a default, not a warning the developer has no way to act on: an app author
+  // reads `modules` as "features we call", and nothing about a file input reads as "camera".
+  //
+  // So the key is stamped by default, with honest copy, overridable via `permissions.camera` and
+  // opt-out-able with `permissions: { camera: false }`. An unused iOS usage string is inert (it is only
+  // ever surfaced when the class is actually requested) — it is not an App Review flag, unlike an
+  // entitlement or a background mode.
+  //
+  // iOS only: the Android chooser's capture path already handles an UNDECLARED CAMERA permission (it
+  // checks `declares()` and falls back to the plain picker — file-chooser.android.ts), so Android needs
+  // nothing and stays opt-in; adding a runtime permission there would change the Play listing.
+  if (cfg.permissions?.camera !== false && !seenKeys.has('NSCameraUsageDescription')) {
+    seenKeys.add('NSCameraUsageDescription');
+    iosPlist.push({ key: 'NSCameraUsageDescription', usage: WEBVIEW_BASELINE_CAMERA_USAGE });
   }
 
   // Active PACK modules (from the config's modulePacks) — their native source + register handler
@@ -316,6 +369,7 @@ function nativeReqs(cfg: AppwrapConfig): NativeReqs {
     activeOptIn: optIn.filter((m) => active.has(m.name)).map((m) => m.name),
     activeOptionalGroups: OPTIONAL_GROUPS.filter((g) => activeMods.some((m) => m.group === g)),
     iosPlist,
+    webCaps,
     iosEntitlements,
     androidPerms: [...androidPerms],
     androidGradleDeps: [...gradle],
@@ -859,6 +913,12 @@ export async function loadConfig(cwd: string, flags: Record<string, string>): Pr
 export function stampShellConfig(outDir: string, cfg: AppwrapConfig): void {
   // Resolve the env-switcher block. Absent block OR `enabled:false` → the whole feature is inert
   // (the shell reads `envSwitcher.enabled`). `allowPattern`/`envs` default to empty (default-deny).
+  // Which TCC-gated web APIs this build DECLARED (modules + `permissions{}`). The shell's guard used to
+  // sniff Info.plist for the usage strings, but the plist now also carries the webview baseline
+  // (an always-present NSCameraUsageDescription so the file-input picker can't kill the process) —
+  // sniffing it would silently hand getUserMedia({video}) to every app, including a loader:'server'
+  // shell showing pages the author doesn't control. Intent and plist are now stamped separately.
+  const webCaps = nativeReqs(cfg).webCaps;
   const es = cfg.envSwitcher;
   const envSwitcher = {
     enabled: !!es && es.enabled !== false,
@@ -893,6 +953,7 @@ export const SHELL_CONFIG = {
   pushRegistrationUrl: ${JSON.stringify(cfg.push?.registrationUrl ?? '')},
   iosKeyboardExtraLift: ${JSON.stringify(cfg.iosKeyboardExtraLift ?? 82)},
   envSwitcher: ${JSON.stringify(envSwitcher)} as { enabled: boolean; envs: { label: string; url: string }[]; allowPattern: string },
+  webCaps: ${JSON.stringify(webCaps)} as { camera: boolean; microphone: boolean; geolocation: boolean },
 };
 `;
   writeFileSync(join(outDir, 'app/shell/config.ts'), content);
@@ -3148,7 +3209,29 @@ function buildInputStats(cwd: string, cfg: { pwaDist?: string; overrides?: strin
    }
   }
   stats.push({ sum: runtime, newest: runtimeNewest });
-  return { parts: stats.map((s) => s.sum), newest: Math.max(...stats.map((s) => s.newest)) };
+  const parts = stats.map((s) => s.sum);
+  // The STAMPED shell config (native/app/shell/config.ts) — compiled into bundle.js, and the ONLY
+  // input that carries values which never touch a fingerprinted file. `dev --url` / `deploy` stamp it
+  // from the EFFECTIVE cfg (serverUrl, loader, debug), so with `--url` every other input is byte-identical
+  // and the fingerprint matched → "inputs unchanged" → the previous .ipa (carrying the PREVIOUS
+  // serverUrl) was reinstalled while the on-disk config said the new one. Silent stale deploy.
+  // CONTENT, not mtime: sync/stamp rewrites this file unconditionally on every run, so its mtime is
+  // pure noise (it would bust the cache always). Deliberately excluded from `newest` for the same
+  // reason — an always-now mtime would make the `--resume` gate unusable, and the fingerprint is the
+  // real gate; --resume is the evidence-relaxed first-run path by construction.
+  parts.push(stringHash(readFileIfExists(join(resolve(cwd, flags.out ?? 'native'), 'app/shell/config.ts'))));
+  return { parts, newest: Math.max(...stats.map((s) => s.newest)) };
+}
+
+function readFileIfExists(p: string): string {
+  try { return readFileSync(p, 'utf8'); } catch { return ''; }
+}
+
+/** djb2 over a string — same family as the fingerprint hash; only needs to change when content does. */
+function stringHash(s: string): number {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) h = (((h << 5) + h) ^ s.charCodeAt(i)) >>> 0;
+  return h;
 }
 
 /** Newest mtime across every build input — the evidence the `--resume` gate needs when no build cache
@@ -3662,6 +3745,11 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
   // ungated. (A fingerprintMatch skip already has an identical cache; nothing to write.)
   if (!canSkipBuild || adoptCache) writeBuildCache(outDir, 'ios', { fingerprint: fp, artifactPath: ipaPath, builtAt: new Date().toISOString() });
 
+  // Prove the .ipa we're about to install actually carries the serverUrl we just stamped — the CLI used
+  // to print "✓ Deployed" while shipping an artifact built from a PREVIOUS URL (a build-skip whose cache
+  // key ignored the stamped shell config). Cheap, and it fails BEFORE the install rather than silently.
+  assertShippedServerUrl(ipaPath, cfg);
+
   console.log(`▶ installing ${ipa} → ${device.name} [${device.transport}]`);
   let installedViaUsbmux = false;
   let installed = false;
@@ -3755,6 +3843,31 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
     : `✓ Deployed to ${device.name}.`);
 }
 
+/** Deploy-time verification for `loader:'server'`: the .ipa's compiled bundle must contain the exact
+ * `serverUrl` we stamped. Reads the bundle straight out of the zip (no extraction). Exits on mismatch —
+ * shipping a shell pointed at the WRONG origin looks like a working deploy and is the hardest class of
+ * bug to see from the outside. Unverifiable (no unzip / bundle not found) → warn, never block. */
+function assertShippedServerUrl(ipaPath: string, cfg: AppwrapConfig): void {
+  if ((cfg.loader ?? 'app') !== 'server' || !cfg.serverUrl) return;
+  let bundle = '';
+  try {
+    bundle = execFileSync('sh', ['-c', `unzip -p ${JSON.stringify(ipaPath)} 'Payload/*.app/app/bundle.js'`], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+  } catch { /* no unzip / unexpected layout → fall through to the unverifiable warning */ }
+  if (!bundle) return void console.warn(`  ⚠ could not read the bundle out of ${ipaPath.split('/').pop()} — shipped serverUrl NOT verified.`);
+  if (bundle.includes(JSON.stringify(cfg.serverUrl))) {
+    console.log(`✓ verified shipped serverUrl → ${cfg.serverUrl}`);
+    return;
+  }
+  const shipped = [...bundle.matchAll(/serverUrl:\s*("(?:[^"\\]|\\.)*")/g)].map((m) => m[1]);
+  console.error(
+    `\n✖ The .ipa does NOT carry the serverUrl that was just stamped.\n` +
+      `  stamped: ${cfg.serverUrl}\n` +
+      (shipped.length ? `  in .ipa: ${shipped.join(', ')}\n` : '') +
+      `  → a stale artifact was about to be installed. Re-run with --force to rebuild.\n`
+  );
+  process.exit(1);
+}
+
 /** Install an .ipa over usbmux via ideviceinstaller — a separate stack from devicectl/CoreDevice, so it
  * works when the CoreDevice tunnel is stuck. Returns false if ideviceinstaller is absent or the install
  * fails (the caller then prints the re-plug / brew-install remedy). */

package/src/config.ts

@@ -245,11 +245,17 @@ export interface AppwrapConfig {
    * testing — products resolve without App Store Connect. Only applies when launched from
    * Xcode (simulator or device-from-Xcode), not a standalone devicectl sideload. */
   storekitConfig?: string;
-  /** Permission usage strings, keyed by domain. Only listed ones are stamped
-   * (iOS: Info.plist usage string; Android: <uses-permission>). 'contacts' has no
-   * iOS key (CNContactPicker needs none) — it only stamps Android READ_CONTACTS. */
+  /** Permission usage strings, keyed by domain. A listed domain is ALWAYS stamped (iOS: Info.plist
+   * usage string; Android: <uses-permission>) — with or without `modules`; when a module already owns
+   * the same key, the string here overrides its default copy. 'contacts' has no iOS key
+   * (CNContactPicker needs none) — it only stamps Android READ_CONTACTS.
+   *
+   * `camera` is stamped by DEFAULT in every iOS build: WKWebView's `<input type="file">` picker offers
+   * "Take Photo", and iOS hard-kills the app for a camera access with no usage string. Pass
+   * `camera: false` to opt out (only for an app with no file inputs at all), or your own string to
+   * replace the default copy. */
   permissions?: Partial<
-    Record<'location' | 'photos' | 'camera' | 'microphone' | 'faceid' | 'calendar' | 'contacts' | 'motion' | 'tracking', string>
+    Record<'location' | 'photos' | 'camera' | 'microphone' | 'faceid' | 'calendar' | 'contacts' | 'motion' | 'tracking', string | false>
   >;
   /** App Tracking Transparency tracking domains (iOS, `tracking` module). When the module is active
    * the CLI sets the privacy manifest's `NSPrivacyTracking` → true and fills `NSPrivacyTrackingDomains`