@livx.cc/appwrap 0.35.0 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.35.0",
+  "version": "0.37.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/shell/capabilities.manifest.ts

@@ -270,6 +270,21 @@ export const MODULES: ModuleManifest[] = [
     ios: { permissions: [{ key: 'NSUserTrackingUsageDescription', domain: 'tracking', defaultUsage: 'Allow tracking to deliver a more personalized experience and measure ad performance.' }] },
   },
 
+  // ── appleSignIn — native Sign in with Apple (iOS ASAuthorization) — opt-in, STRIPPABLE ──
+  // The native account-sheet alternative to the web-OAuth path: ASAuthorizationAppleIDProvider uses the
+  // App ID (bundle) and returns the identityToken + nonce DIRECTLY — no Services ID, no https Return URL,
+  // no browser redirect (which Apple rejects for custom-scheme redirect_uris). The PWA feeds the result
+  // to Firebase signInWithCredential('apple.com', { idToken, rawNonce }). iOS-only (`ios:true`/
+  // `android:false`) — Sign in with Apple has NO native Android SDK (the kit reports 'none' there and the
+  // app falls back to its web Apple auth). Stamps the `com.apple.developer.applesignin` entitlement ONLY
+  // when active (gated, like push's aps-environment) — a non-Apple-SignIn build signs without it. No
+  // permission string. Strippable own handler `handlers-apple-signin.ts` (in OPTIONAL_GROUPS).
+  {
+    name: 'appleSignIn', group: 'appleSignIn',
+    capabilities: { appleSignIn: { ios: true, android: false } },
+    ios: { entitlements: { 'com.apple.developer.applesignin': ['Default'] } },
+  },
+
   // ── backgroundTask — headless background execution (HEADLESS JS HANDLER) — opt-in, STRIPPABLE ──
   // The OS wakes the app (possibly cold, no visible WebView) for a permitted task id; the shell builds
   // an OFFSCREEN WebView, loads the app conveying the id (the handshake reports it), awaits the JS
@@ -289,7 +304,7 @@ export const MODULES: ModuleManifest[] = [
 
 /** Opt-in registration groups that own their own NS handler file (strippable when inactive). Core
  * groups (core/extended/parity/system/media/billing) are always bundled; only these are CLI-gated. */
-export const OPTIONAL_GROUPS = ['health', 'oauth', 'reviews', 'scanner', 'speech', 'tracking', 'backgroundTask'] as const;
+export const OPTIONAL_GROUPS = ['health', 'oauth', 'reviews', 'scanner', 'speech', 'tracking', 'appleSignIn', 'backgroundTask'] as const;
 
 /** Resolve the active capability map for the handshake from a set of active capability names. */
 export function buildCapabilityMap(

package/runtime/app/shell/devmenu.ts

@@ -17,30 +17,54 @@ export function startDevMenu(): void {
   else if (isAndroid) startAndroidShake();
 }
 
-// ── shake detection (total acceleration magnitude in g incl. gravity, debounced) ──
-const SHAKE_G = 1.8; // spike vs. ~1g rest
+// ── shake detection — deliberate, robust against incidental motion (walking, bumps) ──
+// A real "shake to open" is a sustained back-and-forth: several HARD spikes, close together, that
+// REVERSE direction each time. Walking/jostle produces occasional same-direction spikes with gaps —
+// so we require (a) a high threshold, (b) direction reversal between consecutive spikes, and (c) a
+// short inter-spike gap that RESETS the count if you pause. The bar is a firm wrist-shake, not a step.
+const SHAKE_G = 2.3; // hard spike vs. ~1g rest (was 1.8 — too low, walking cleared it)
+const SHAKE_SPIKES = 4; // direction-reversing spikes needed (≈2 full back-and-forth shakes)
+const SHAKE_GAP_MS = 400; // max gap between spikes; a longer pause resets the streak
+const MENU_DEBOUNCE_MS = 1500; // don't re-open right after a menu
 let shakeMm: CMMotionManager | null = null; // hold a ref so CoreMotion isn't GC'd
-let firstSpikeAt = 0;
 let spikes = 0;
+let lastSpikeAt = 0;
+let lastSpikeDir = 0; // sign of the dominant axis at the last spike; reversal = real shake
 let lastMenuAt = 0;
 
-function onAccelMagnitude(g: number): void {
+/** @param g total accel magnitude in g (rest ≈ 1)
+ *  @param dir sign (+1/-1) of the dominant-axis acceleration — used to detect back-and-forth reversal */
+function onAccelMagnitude(g: number, dir: number): void {
   if (g < SHAKE_G) return;
   const now = Date.now();
-  if (now - lastMenuAt < 1500) return; // don't re-open right after a menu
-  if (now - firstSpikeAt > 800) {
-    firstSpikeAt = now; // start a fresh window
+  if (now - lastMenuAt < MENU_DEBOUNCE_MS) return;
+  // A spike that's too soon after the last counts as the SAME thrust, not a new one — ignore it so a
+  // single hard jolt's ringing doesn't rack up the count.
+  if (now - lastSpikeAt < 80) return;
+  // Reset the streak unless this spike continues a fast, direction-reversing sequence.
+  if (now - lastSpikeAt > SHAKE_GAP_MS || dir === lastSpikeDir) {
     spikes = 1;
-    return;
+  } else {
+    spikes++;
   }
-  if (++spikes >= 2) {
+  lastSpikeAt = now;
+  lastSpikeDir = dir;
+  if (spikes >= SHAKE_SPIKES) {
     spikes = 0;
-    firstSpikeAt = 0;
+    lastSpikeAt = 0;
+    lastSpikeDir = 0;
     lastMenuAt = now;
     void showDevMenu();
   }
 }
 
+/** Sign of the largest-magnitude component — the axis the shake is thrusting along. */
+function dominantDir(x: number, y: number, z: number): number {
+  const ax = Math.abs(x), ay = Math.abs(y), az = Math.abs(z);
+  const v = ax >= ay && ax >= az ? x : ay >= az ? y : z;
+  return v >= 0 ? 1 : -1;
+}
+
 function startIOSShake(): void {
   // Poll `mm.deviceMotion` on a JS timer — CoreMotion's queue-handler block is fragile under
   // NativeScript (can silently stop firing on-device); mirrors the motion.start handler.
@@ -52,10 +76,12 @@ function startIOSShake(): void {
   setInterval(() => {
     const m = mm.deviceMotion;
     if (!m) return; // first sample not ready
-    const x = m.userAcceleration.x + m.gravity.x; // total accel in g (rest ≈ 1)
-    const y = m.userAcceleration.y + m.gravity.y;
-    const z = m.userAcceleration.z + m.gravity.z;
-    onAccelMagnitude(Math.sqrt(x * x + y * y + z * z));
+    const ux = m.userAcceleration.x, uy = m.userAcceleration.y, uz = m.userAcceleration.z;
+    const x = ux + m.gravity.x; // total accel in g (rest ≈ 1) — magnitude includes gravity
+    const y = uy + m.gravity.y;
+    const z = uz + m.gravity.z;
+    // Direction from gravity-free userAcceleration (gravity is constant → would mask the back-and-forth).
+    onAccelMagnitude(Math.sqrt(x * x + y * y + z * z), dominantDir(ux, uy, uz));
   }, 100);
 }
 
@@ -66,11 +92,19 @@ function startAndroidShake(): void {
   const accel = sm.getDefaultSensor(android.hardware.Sensor.TYPE_ACCELEROMETER);
   if (!accel) return;
   const G = 9.80665;
+  // Low-pass gravity estimate so we can derive gravity-free direction (mirrors iOS userAcceleration);
+  // the raw accelerometer includes gravity, which is constant and would mask the back-and-forth.
+  const grav = [0, 0, 0];
+  const alpha = 0.8;
   const listener = new android.hardware.SensorEventListener({
     onAccuracyChanged() {},
     onSensorChanged(e: android.hardware.SensorEvent) {
       const v = e.values;
-      onAccelMagnitude(Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]) / G);
+      grav[0] = alpha * grav[0] + (1 - alpha) * v[0];
+      grav[1] = alpha * grav[1] + (1 - alpha) * v[1];
+      grav[2] = alpha * grav[2] + (1 - alpha) * v[2];
+      const lx = v[0] - grav[0], ly = v[1] - grav[1], lz = v[2] - grav[2]; // linear (gravity-free)
+      onAccelMagnitude(Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]) / G, dominantDir(lx, ly, lz));
     },
   });
   sm.registerListener(listener, accel, android.hardware.SensorManager.SENSOR_DELAY_UI);

package/runtime/app/shell/handlers-apple-signin.ts

@@ -0,0 +1,169 @@
+import { Utils, isIOS } from '@nativescript/core';
+import { bridge } from './bridge';
+import { sha256Hex } from './sha256';
+
+const err = (code: string, message: string) => Object.assign(new Error(message), { code });
+
+// Keep strong refs while the system sheet is up — ARC frees the controller + its delegate + context
+// provider the moment the JS locals fall out of scope, which silently cancels the flow mid-handshake
+// (same lesson as handlers-oauth.ts `activeSession`/`activeProvider`).
+let activeController: ASAuthorizationController | null = null;
+let activeDelegate: AppleSignInDelegate | null = null;
+let activeProvider: AppleSignInContextProvider | null = null;
+
+@NativeClass()
+class AppleSignInContextProvider extends NSObject implements ASAuthorizationControllerPresentationContextProviding {
+  static ObjCProtocols = [ASAuthorizationControllerPresentationContextProviding];
+  static new(): AppleSignInContextProvider {
+    return <AppleSignInContextProvider>super.new();
+  }
+  presentationAnchorForAuthorizationController(_controller: ASAuthorizationController): UIWindow {
+    return (
+      Utils.ios.getRootViewController()?.view?.window ??
+      UIApplication.sharedApplication.keyWindow
+    );
+  }
+}
+
+/** Decode an Apple-returned NSData JWT/code blob into a UTF-8 string (identityToken/authorizationCode). */
+function dataToUtf8(data: NSData | null): string | undefined {
+  if (!data) return undefined;
+  const s = NSString.alloc().initWithDataEncoding(data, NSUTF8StringEncoding);
+  return s ? String(s) : undefined;
+}
+
+@NativeClass()
+class AppleSignInDelegate extends NSObject implements ASAuthorizationControllerDelegate {
+  static ObjCProtocols = [ASAuthorizationControllerDelegate];
+  // Per-call settlement (set right after `.new()`). The shared `settle` clears the ARC refs + recovers
+  // the WebView before resolving/rejecting, so it runs exactly once per flow.
+  rawNonce = '';
+  settle!: (fn: () => void) => void;
+  resolve!: (v: unknown) => void;
+  reject!: (e: unknown) => void;
+  static new(): AppleSignInDelegate {
+    return <AppleSignInDelegate>super.new();
+  }
+
+  authorizationControllerDidCompleteWithAuthorization(
+    _controller: ASAuthorizationController,
+    authorization: ASAuthorization
+  ): void {
+    const cred = authorization.credential as ASAuthorizationAppleIDCredential;
+    const identityToken = dataToUtf8(cred.identityToken ?? null);
+    if (!identityToken) {
+      this.settle(() => this.reject(err('NATIVE_ERROR', 'appleSignIn: Apple returned no identityToken')));
+      return;
+    }
+    const authorizationCode = dataToUtf8(cred.authorizationCode ?? null);
+
+    // First-authorization-only profile. Apple omits name/email on subsequent sign-ins per Apple ID.
+    let name: { givenName?: string; familyName?: string; displayName?: string } | undefined;
+    if (cred.fullName) {
+      const givenName = cred.fullName.givenName || undefined;
+      const familyName = cred.fullName.familyName || undefined;
+      // OS-composed display name (locale-aware) — convenience; the consumer can also build its own.
+      const composed = NSPersonNameComponentsFormatter.localizedStringFromPersonNameComponentsStyleOptions(
+        cred.fullName,
+        NSPersonNameComponentsFormatterStyle.Default,
+        0 as NSPersonNameComponentsFormatterOptions
+      );
+      const displayName = (composed && String(composed)) || undefined;
+      if (givenName || familyName || displayName) name = { givenName, familyName, displayName };
+    }
+    const email = cred.email || undefined;
+    const user = name || email ? { ...(name ? { name } : {}), ...(email ? { email } : {}) } : undefined;
+
+    this.settle(() =>
+      this.resolve({ identityToken, authorizationCode, nonce: this.rawNonce, ...(user ? { user } : {}) })
+    );
+  }
+
+  authorizationControllerDidCompleteWithError(_controller: ASAuthorizationController, error: NSError): void {
+    // ASAuthorizationError.Canceled === 1001 (user dismissed the sheet) → resolve cancelled, never throw.
+    if (error.code === ASAuthorizationError.Canceled) {
+      this.settle(() => this.resolve({ cancelled: true }));
+      return;
+    }
+    this.settle(() => this.reject(err('NATIVE_ERROR', error.localizedDescription ?? 'appleSignIn failed')));
+  }
+}
+
+/**
+ * Native Sign in with Apple (iOS, `appleSignIn` module). Strippable own-handler file (registered only
+ * when the module is active) — a build without it compiles NO ASAuthorization code and stamps no
+ * entitlement. Presents `ASAuthorizationController` (the system account sheet) and returns the Apple
+ * `identityToken` + raw nonce DIRECTLY to JS, so the PWA can do `signInWithCredential` on Firebase.
+ *
+ * The caller passes a RAW nonce; we send SHA256(nonce) to Apple (Apple binds the id_token to the hash)
+ * and return the raw nonce unchanged so the web app hands `rawNonce` to Firebase.
+ *
+ * Name/email come back ONLY on the first authorization per Apple ID — we relay them when present.
+ * Cancel resolves `{ cancelled: true }` (never throws), matching the scanner/oauth contract.
+ *
+ * iOS-only: the capability is gated `ios:true`/`android:false`, so the kit short-circuits off iOS
+ * before reaching the bridge. The isIOS guard is defence-in-depth.
+ *
+ * DEVICE-VERIFIED (iPhone 13 Pro Max, 2026-06-24, hello-pwa under paid team RDYDSWE9RB): the native
+ * ASAuthorization sheet presented, returned a real Apple-signed identityToken (JWT) + the raw nonce +
+ * first-auth user email, and dismissed without freezing (recoverAfterNativeSurface held). The
+ * com.apple.developer.applesignin entitlement signs only on a paid team — the free personal team can't
+ * hold the Sign-in-with-Apple capability (same class as push aps-environment).
+ */
+export function registerAppleSignInHandlers(): void {
+  if (!isIOS) return;
+
+  bridge.register(
+    'appleSignIn.signIn',
+    ({ nonce, scopes }: { nonce: string; scopes?: Array<'name' | 'email'> }) =>
+      new Promise((resolve, reject) => {
+        const rawNonce = String(nonce ?? '');
+        if (!rawNonce) { reject(err('NATIVE_ERROR', 'appleSignIn.signIn: empty nonce')); return; }
+        const want = new Set(scopes ?? ['name', 'email']);
+
+        Utils.dispatchToMainThread(() => {
+          try {
+            const provider = ASAuthorizationAppleIDProvider.alloc().init();
+            const request = provider.createRequest();
+            // Apple binds the returned id_token to SHA256(nonce); we hand back the RAW nonce to JS.
+            request.nonce = sha256Hex(rawNonce);
+            const scopeList: string[] = [];
+            if (want.has('name')) scopeList.push(ASAuthorizationScopeFullName);
+            if (want.has('email')) scopeList.push(ASAuthorizationScopeEmail);
+            request.requestedScopes = NSArray.arrayWithArray<string>(scopeList as any);
+
+            const settle = (fn: () => void) => {
+              activeController = null;
+              activeDelegate = null;
+              activeProvider = null;
+              // An ASAuthorization sheet can leave the WebView frozen on dismiss like the other native
+              // surfaces — recover from its completion (shared framework fix).
+              bridge.getWebView()?.recoverAfterNativeSurface();
+              fn();
+            };
+
+            const delegate = AppleSignInDelegate.new();
+            delegate.rawNonce = rawNonce;
+            delegate.settle = settle;
+            delegate.resolve = resolve;
+            delegate.reject = reject;
+
+            const controller = ASAuthorizationController.alloc().initWithAuthorizationRequests(
+              NSArray.arrayWithObject<ASAuthorizationRequest>(request)
+            );
+            activeDelegate = delegate;
+            activeProvider = AppleSignInContextProvider.new();
+            controller.delegate = delegate;
+            controller.presentationContextProvider = activeProvider;
+            activeController = controller;
+            controller.performRequests();
+          } catch (e: any) {
+            activeController = null;
+            activeDelegate = null;
+            activeProvider = null;
+            reject(err('NATIVE_ERROR', e?.message ?? 'appleSignIn failed to start'));
+          }
+        });
+      })
+  );
+}

package/runtime/app/shell/handlers.ts

@@ -10,7 +10,7 @@ import { ACTIVE_MODULE_NAMES } from './active-modules.generated';
 import { consumePendingBackgroundTaskId } from './background-context';
 
 /** Build identifier for the native shell bundle — bump per deploy to spot stale bundles. */
-export const SHELL_BUILD = 'global-observer-1';
+export const SHELL_BUILD = 'apple-signin-1';
 
 /** Version status the web side (native-kit `kit.updates`) reports via `app.reportWebVersion`. */
 export interface WebVersionInfo { current?: string; latest?: string; build?: string | number; updateAvailable?: boolean; }

package/runtime/app/shell/sha256.ts

@@ -0,0 +1,78 @@
+/**
+ * Minimal, dependency-free SHA-256 → lowercase hex. Used by the `appleSignIn` handler to hash the raw
+ * nonce before sending it to Apple (Apple binds the returned id_token to SHA256(nonce); the raw nonce
+ * goes back to JS for Firebase). NativeScript ships no WebCrypto, and a pointer-juggling CommonCrypto
+ * FFI call is exactly the fragile any-typed interop the project avoids — a small pure-JS hash is
+ * deterministic and unit-testable without a device. Input is treated as a UTF-8 string.
+ */
+
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+function utf8Bytes(str: string): number[] {
+  const out: number[] = [];
+  for (let i = 0; i < str.length; i++) {
+    let c = str.charCodeAt(i);
+    if (c < 0x80) out.push(c);
+    else if (c < 0x800) out.push(0xc0 | (c >> 6), 0x80 | (c & 0x3f));
+    else if (c >= 0xd800 && c <= 0xdbff) {
+      // Surrogate pair → full code point.
+      const lo = str.charCodeAt(++i);
+      c = 0x10000 + ((c & 0x3ff) << 10) + (lo & 0x3ff);
+      out.push(0xf0 | (c >> 18), 0x80 | ((c >> 12) & 0x3f), 0x80 | ((c >> 6) & 0x3f), 0x80 | (c & 0x3f));
+    } else out.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 0x3f), 0x80 | (c & 0x3f));
+  }
+  return out;
+}
+
+const rotr = (x: number, n: number) => (x >>> n) | (x << (32 - n));
+
+/** SHA-256 of a UTF-8 string, lowercase hex (64 chars). */
+export function sha256Hex(message: string): string {
+  const bytes = utf8Bytes(message);
+  const bitLen = bytes.length * 8;
+  bytes.push(0x80);
+  while (bytes.length % 64 !== 56) bytes.push(0);
+  // 64-bit big-endian length (high word is 0 for any realistic nonce).
+  for (let i = 7; i >= 0; i--) bytes.push((bitLen / 2 ** (8 * i)) & 0xff);
+
+  const h = new Uint32Array([
+    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+  ]);
+  const w = new Uint32Array(64);
+
+  for (let i = 0; i < bytes.length; i += 64) {
+    for (let t = 0; t < 16; t++) {
+      w[t] = (bytes[i + 4 * t] << 24) | (bytes[i + 4 * t + 1] << 16) | (bytes[i + 4 * t + 2] << 8) | bytes[i + 4 * t + 3];
+    }
+    for (let t = 16; t < 64; t++) {
+      const s0 = rotr(w[t - 15], 7) ^ rotr(w[t - 15], 18) ^ (w[t - 15] >>> 3);
+      const s1 = rotr(w[t - 2], 17) ^ rotr(w[t - 2], 19) ^ (w[t - 2] >>> 10);
+      w[t] = (w[t - 16] + s0 + w[t - 7] + s1) | 0;
+    }
+    let [a, b, c, d, e, f, g, hh] = [h[0], h[1], h[2], h[3], h[4], h[5], h[6], h[7]];
+    for (let t = 0; t < 64; t++) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const t1 = (hh + S1 + ch + K[t] + w[t]) | 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (S0 + maj) | 0;
+      hh = g; g = f; f = e; e = (d + t1) | 0; d = c; c = b; b = a; a = (t1 + t2) | 0;
+    }
+    h[0] = (h[0] + a) | 0; h[1] = (h[1] + b) | 0; h[2] = (h[2] + c) | 0; h[3] = (h[3] + d) | 0;
+    h[4] = (h[4] + e) | 0; h[5] = (h[5] + f) | 0; h[6] = (h[6] + g) | 0; h[7] = (h[7] + hh) | 0;
+  }
+
+  let hex = '';
+  for (let i = 0; i < 8; i++) hex += (h[i] >>> 0).toString(16).padStart(8, '0');
+  return hex;
+}

package/src/cli.ts

@@ -87,6 +87,12 @@ function resolveAssetRoot(rel: string): string {
 const TEMPLATE_DIR = resolveAssetRoot('runtime');
 const CI_TEMPLATE_DIR = resolveAssetRoot('templates/ci');
 
+/** This CLI's own published version — used to pin the `bunx @livx.cc/appwrap@^x.y.z` invocations the
+ * emitted workflow runs. Pinning to THIS version's floor means CI fails LOUDLY ("version not found")
+ * until that version is published, instead of bunx silently resolving an older published build that
+ * lacks `release`/`init` flags. package.json sits one level above src/ (published) or the monorepo dir. */
+const CLI_VERSION: string = (await import(resolve(import.meta.dir, '..', 'package.json'), { with: { type: 'json' } })).default.version;
+
 // Load the capability manifest VALUES from the resolved runtime (pure data — safe outside NativeScript).
 // Top-level await resolves before any command dispatches at the bottom of this file.
 const { MODULES, OPTIONAL_GROUPS } = (await import(
@@ -179,6 +185,7 @@ const OPTIONAL_GROUP_HANDLERS: Record<string, { file: string; fn: string }> = {
   scanner: { file: './handlers-scanner', fn: 'registerScannerHandlers' },
   speech: { file: './handlers-speech', fn: 'registerSpeechHandlers' },
   tracking: { file: './handlers-tracking', fn: 'registerTrackingHandlers' },
+  appleSignIn: { file: './handlers-apple-signin', fn: 'registerAppleSignInHandlers' },
   backgroundTask: { file: './handlers-background', fn: 'registerBackgroundTaskHandlers' },
 };
 
@@ -958,23 +965,34 @@ export function isFrameworkRepo(root: string): boolean {
   return existsSync(join(root, 'packages/appwrap-cli/src/cli.ts'));
 }
 
-/** Emit CI scaffolding (GH Actions → git repo root, fastlane → native/). Never overwrites. */
-function copyCiTemplates(cwd: string, outDir: string, cfg: AppwrapConfig): void {
+/** Emit CI scaffolding (GH Actions → git repo root, fastlane → native/).
+ * GH workflows are never overwritten (users may customize them). The fastlane lane IS appwrap-managed
+ * (the release recipe, not for hand-editing — see AGENTS.md), so it is RE-EMITTED on `--force` to keep
+ * the recipe current after a framework upgrade; without --force it's still first-time-only. */
+function copyCiTemplates(cwd: string, outDir: string, cfg: AppwrapConfig, force = false): void {
   if (!existsSync(CI_TEMPLATE_DIR)) return;
   const repoRoot = gitRoot(cwd);
   // GitHub only reads `.github/workflows` at the REPO ROOT — in a monorepo, writing it under the
   // package cwd (e.g. packages/app/.github) is dead config and regenerates a stray workflow each init.
-  const targets: Array<[string, string]> = [[join(CI_TEMPLATE_DIR, 'fastlane'), join(outDir, 'fastlane')]];
+  // [from, to, overwritable]
+  const targets: Array<[string, string, boolean]> = [[join(CI_TEMPLATE_DIR, 'fastlane'), join(outDir, 'fastlane'), force]];
   // …but if the repo root IS the appwrap framework itself (in-repo example), DON'T scaffold consumer
   // workflows into the framework's .github — that's the stray-workflow-each-init bug.
   if (isFrameworkRepo(repoRoot)) {
     console.log('  ci   ← GH Actions scaffold skipped (inside the appwrap framework repo — manages its own CI)');
   } else {
-    targets.unshift([join(CI_TEMPLATE_DIR, 'github/workflows'), join(repoRoot, '.github/workflows')]);
+    targets.unshift([join(CI_TEMPLATE_DIR, 'github/workflows'), join(repoRoot, '.github/workflows'), false]);
   }
-  for (const [from, to] of targets) {
+  for (const [from, to, overwrite] of targets) {
     mkdirSync(to, { recursive: true });
-    cpSync(from, to, { recursive: true, force: false, errorOnExist: false });
+    cpSync(from, to, { recursive: true, force: overwrite, errorOnExist: false });
+  }
+  // Pin the emitted workflow's `bunx @livx.cc/appwrap@^x.y.z` to THIS CLI's version floor, so a CI run
+  // using a freshly-emitted workflow can't silently resolve an older published build that lacks the
+  // `init`/`release` commands (it would 404 loudly instead). Idempotent: re-init finds no placeholder.
+  if (!isFrameworkRepo(repoRoot)) {
+    const wf = join(repoRoot, '.github/workflows/appwrap-release-ios.yml');
+    if (existsSync(wf)) writeFileSync(wf, readFileSync(wf, 'utf8').replaceAll('__APPWRAP_VERSION__', CLI_VERSION));
   }
   // Stamp the app id + team into the emitted fastlane (signing needs them; the templates ship
   // `__APP_ID__`/`__TEAM_ID__` placeholders). Idempotent: re-init finds no placeholders → no-op.
@@ -1059,7 +1077,7 @@ async function init(cwd: string, flags: Record<string, string>): Promise<void> {
   console.log(`🎁 appwrap init → ${outDir}`);
   mkdirSync(outDir, { recursive: true });
   regenerateCore(cwd, outDir, cfg, { firstRun: true, flags });
-  copyCiTemplates(cwd, outDir, cfg); // first-time scaffold (never overwrites)
+  copyCiTemplates(cwd, outDir, cfg, 'force' in flags); // GH workflows: first-time only; fastlane lane: re-emit on --force
   writeFileSync(join(outDir, '.gitignore'), 'node_modules/\nplatforms/\nhooks/\n');
   applyOverrides(cwd, outDir, cfg); // escape hatch — last, so custom native code wins
   stampVersionManifest(outDir, cfg); // provenance — also marks the dir appwrap-managed
@@ -1175,6 +1193,84 @@ async function build(cwd: string, flags: Record<string, string>, positionals: st
   }
 }
 
+/** `appwrap release ios` — the ONE build+sign+upload-to-TestFlight command, identical locally and in CI.
+ *
+ * It re-stamps the config + PWA (`sync`) and then delegates the full archive/sign/upload to the emitted
+ * fastlane lane (`native/fastlane` `:beta`) — the SINGLE source of truth for the iOS release recipe (the
+ * lane runs `ns prepare ios --release` → match signing → build_app → upload_to_testflight). CI is a thin
+ * wrapper that just calls this. Keeping the recipe in fastlane (not duplicated in TS) means local and CI
+ * run byte-identical steps.
+ *
+ * Knobs (all optional; mirror the workflow):
+ *   --server-url <url>   override loader:'server' serverUrl for this release (lab vs prod backend)
+ *   --env <name>         convenience: resolve serverUrl from cfg.envs[name] when present (see config)
+ *   --build-number <n>   set the store CFBundleVersion (sets APPWRAP_BUILD_NUMBER for the lane)
+ *
+ * Signing/ASC config is read from env by the lane (ASC_KEY_ID / ASC_ISSUER_ID / ASC_KEY_P8 /
+ * MATCH_GIT_URL / MATCH_PASSWORD) — secrets never live in appwrap.config. */
+async function release(cwd: string, flags: Record<string, string>, positionals: string[]): Promise<void> {
+  const platform = positionals[0];
+  if (platform !== 'ios') {
+    console.error('Usage: appwrap release ios [--server-url <url>] [--env <name>] [--build-number <n>] [--config <path>] [--out native]\n' +
+      '  (Android: `appwrap build android --release --aab` then `fastlane android beta`.)');
+    process.exit(1);
+  }
+  const cfg = await loadConfig(cwd, flags);
+  const outDir = resolve(cwd, flags.out ?? 'native');
+  if (!existsSync(outDir)) {
+    console.error(`✖ Wrapper not found at ${outDir} — run \`appwrap init\` first (CI must \`init\`, native/ is gitignored).`);
+    process.exit(1);
+  }
+  const fastfile = join(outDir, 'fastlane', 'Fastfile');
+  if (!existsSync(fastfile)) {
+    console.error(`✖ No fastlane lane at ${fastfile} — run \`appwrap init\` to emit it (it carries the release recipe).`);
+    process.exit(1);
+  }
+
+  // Optional backend-url override for loader:'server' apps (lab vs prod). --server-url wins; else
+  // --env resolves from cfg.envs[name] when the consumer config declares it.
+  let serverUrl = flags['server-url'] || undefined;
+  if (!serverUrl && flags.env) {
+    serverUrl = (cfg as { envs?: Record<string, string> }).envs?.[flags.env];
+    if (!serverUrl) {
+      console.error(`✖ --env ${flags.env} given but cfg.envs[${flags.env}] is not set in the config.`);
+      process.exit(1);
+    }
+  }
+  const stampCfg = serverUrl ? { ...cfg, loader: 'server' as const, serverUrl } : cfg;
+
+  // Build number: explicit flag → APPWRAP_BUILD_NUMBER (which the CLI's stamping already honors and
+  // wins over the derived default). In CI the workflow sets APPWRAP_BUILD_NUMBER itself.
+  const env = { ...process.env };
+  if (flags['build-number']) {
+    if (!/^\d+$/.test(flags['build-number'])) {
+      console.error(`✖ --build-number must be a positive integer (got "${flags['build-number']}").`);
+      process.exit(1);
+    }
+    env.APPWRAP_BUILD_NUMBER = flags['build-number'];
+  }
+
+  // Re-stamp config + copy the latest PWA into native/ so the lane archives current sources. (The lane
+  // also runs `ns prepare ios --release`; sync here makes the wrapper config/PWA authoritative first.)
+  await sync(cwd, flags);
+  if (serverUrl) {
+    stampShellConfig(outDir, stampCfg);
+    console.log(`✓ Release loader → ${serverUrl}${flags.env ? ` (env: ${flags.env})` : ''}`);
+  }
+
+  console.log(`▶ fastlane ios beta  (cwd: ${outDir}/fastlane → native/)${env.APPWRAP_BUILD_NUMBER ? `  build #${env.APPWRAP_BUILD_NUMBER}` : ''}`);
+  try {
+    execFileSync('fastlane', ['ios', 'beta'], { cwd: outDir, stdio: 'inherit', env });
+  } catch {
+    console.error('\n✖ TestFlight release failed. Common causes:\n' +
+      '  • Missing ASC/match env: ASC_KEY_ID, ASC_ISSUER_ID, ASC_KEY_P8 (base64), MATCH_GIT_URL, MATCH_PASSWORD.\n' +
+      '  • Certs/profiles not seeded — run `fastlane match appstore` once against MATCH_GIT_URL.\n' +
+      '  • CFBundleVersion already used for this marketing version → pass a higher --build-number.');
+    process.exit(1);
+  }
+  console.log('✓ Uploaded to TestFlight (App Store Connect processing — check the build list / wait for the email).');
+}
+
 interface AppleTeam { teamId: string; name: string; email?: string; paid: boolean }
 interface DeviceInfo { id: string; name: string; model: string; transport: string }
 
@@ -1711,13 +1807,17 @@ async function main(): Promise<void> {
     case 'deploy':
       await deploy(cwd, flags, positionals);
       break;
+    case 'release':
+      await release(cwd, flags, positionals);
+      break;
     case 'logs':
       await logs(cwd, flags, positionals);
       break;
     default:
-      console.log('Usage: appwrap <init|sync|dev|build|deploy|logs> [--config <path>] [--out native]\n' +
+      console.log('Usage: appwrap <init|sync|dev|build|deploy|release|logs> [--config <path>] [--out native]\n' +
         '  config: appwrap.config.ts (preferred) → .js → appwrap.json\n' +
         '  build <ios|android> [--release] [--aab]   deploy ios [--device <id|name>] [--no-launch]\n' +
+        '  release ios [--server-url <url>] [--env <name>] [--build-number <n>]  (build+sign+upload to TestFlight)\n' +
         '  logs ios [--once] [--native]   dev [--url <url> | --port <p>]');
       process.exit(command ? 1 : 0);
   }

package/templates/ci/fastlane/Fastfile

@@ -6,6 +6,36 @@ default_platform(:ios)
 APP_ID = '__APP_ID__'.freeze
 TEAM_ID = '__TEAM_ID__'.freeze
 
+# Run `ns prepare` (which shells out to `pod install`) with a SANITIZED gem env.
+#
+# Why: fastlane runs under its own Ruby and exports GEM_HOME/GEM_PATH into every child process. On a
+# Mac, NativeScript's `pod` is the system one (`/usr/local/bin/pod`, shebang-pinned to Ruby 2.6, whose
+# CocoaPods lives in /Library/Ruby/Gems/2.6.0). The inherited GEM_HOME redirects its gem lookup to
+# fastlane's Ruby dir → `can't find gem cocoapods (Gem::GemNotFoundException)` → NS prints
+# `'arch install' command failed` (exit 127). Interactively `pod` works because no GEM_HOME is set.
+#
+# Fix: only when the active `pod` is that system-Ruby-2.6 binary, drop the leaked GEM_* vars so it
+# falls back to its own default gem dir. CI runners use a self-managed Ruby (setup-ruby) whose `pod`
+# is NOT the system 2.6 one, so the env is left untouched there — no behavior change on CI.
+def appwrap_prepare_ios
+  prepare = "cd '#{File.expand_path('..', __dir__)}' && ns prepare ios --release"
+  pod = `command -v pod`.strip
+  system_pod = !pod.empty? && File.exist?(pod) &&
+               File.read(pod, 256).include?('Ruby.framework/Versions/2.6')
+  unless system_pod
+    sh(prepare)
+    return
+  end
+  leaked = %w[GEM_HOME GEM_PATH RUBYLIB RUBYOPT BUNDLE_GEMFILE BUNDLE_BIN_PATH]
+  saved = {}
+  leaked.each { |k| saved[k] = ENV[k]; ENV.delete(k) }
+  begin
+    sh(prepare)
+  ensure
+    saved.each { |k, v| ENV[k] = v unless v.nil? }
+  end
+end
+
 platform :ios do
   desc 'Build the NativeScript wrapper and upload to TestFlight'
   lane :beta do
@@ -23,7 +53,8 @@ platform :ios do
           git_url: ENV['MATCH_GIT_URL'], api_key: api_key)
 
     # NativeScript prepares the Xcode project inside the wrapper dir (native/ = parent of fastlane/).
-    sh("cd '#{File.expand_path('..', __dir__)}' && ns prepare ios --release")
+    # Wrapped to sanitize the gem env so the system `pod` can find CocoaPods (see appwrap_prepare_ios).
+    appwrap_prepare_ios
 
     # NS defaults the project to automatic signing → archive can't find a profile. Pin manual signing
     # to the match-provided App Store profile (name exported by match into ENV).

package/templates/ci/github/workflows/appwrap-release-ios.yml

@@ -34,7 +34,13 @@ jobs:
       - run: bun install && bun run build
       # Pin global tools — unpinned installs can grab a breaking release mid-flight. Bump deliberately.
       - run: npm i -g nativescript@9.0.6
-      - run: bunx @livx.cc/appwrap init # native/ is generated (gitignored) — regenerate it fresh in CI
+      # bunx is PINNED to the appwrap version that emitted this workflow (stamped at `init`). Pinning is
+      # load-bearing: an UNPINNED `bunx @livx.cc/appwrap` resolves to whatever is currently published,
+      # which may pre-date the `init`/`release` commands and would silently run old code + exit 1 with a
+      # confusing usage dump. With the pin, CI fails LOUDLY ("No matching version") until that version is
+      # published to the @livx.cc registry. PUBLISH-ORDERING: publish the appwrap CLI BEFORE the first CI
+      # run that uses a freshly-emitted workflow.
+      - run: bunx @livx.cc/appwrap@^__APPWRAP_VERSION__ init # native/ is generated (gitignored) — regenerate it fresh in CI
       - working-directory: native
         run: npm install
       - uses: ruby/setup-ruby@v1
@@ -47,14 +53,15 @@ jobs:
           chmod 600 ~/.ssh/match_deploy_key
           printf 'Host github.com\n  IdentityFile ~/.ssh/match_deploy_key\n  IdentitiesOnly yes\n' >> ~/.ssh/config
           ssh-keyscan github.com >> ~/.ssh/known_hosts 2>/dev/null
+      # Single source of truth: the SAME command a developer runs locally. It re-stamps native/ and
+      # delegates the full archive/sign/upload to the emitted fastlane lane — no fastlane logic here.
       - name: Build & upload to TestFlight
-        working-directory: native
         env:
           MATCH_GIT_URL: ${{ secrets.MATCH_GIT_URL }}
           MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}
           ASC_KEY_ID: ${{ secrets.ASC_KEY_ID }}
           ASC_ISSUER_ID: ${{ secrets.ASC_ISSUER_ID }}
           ASC_KEY_P8: ${{ secrets.ASC_KEY_P8 }}
-        run: fastlane ios beta
+        run: bunx @livx.cc/appwrap@^__APPWRAP_VERSION__ release ios
 
   # Production promotion is a manual gate: promote the TestFlight build in App Store Connect.