kasy-cli 1.32.0 → 1.35.0

package/lib/scaffold/backends/supabase/patch/lib/features/authentication/api/authentication_api.dart

@@ -1,3 +1,4 @@
+import 'dart:async';
 import 'dart:convert';
 import 'package:crypto/crypto.dart';
 import 'package:firebase_auth/firebase_auth.dart' as fb_auth;
@@ -11,6 +12,8 @@ import 'package:kasy_kit/core/data/api/base_api_exceptions.dart';
 import 'package:kasy_kit/core/data/entities/user_entity.dart';
 import 'package:kasy_kit/environments.dart';
 import 'package:kasy_kit/google_auth_options.dart';
+import 'package:kasy_kit/features/authentication/api/auth_web_support.dart'
+    if (dart.library.js_interop) 'package:kasy_kit/features/authentication/api/auth_web_support_web.dart';
 import 'package:kasy_kit/features/authentication/api/authentication_api_interface.dart';
 import 'package:kasy_kit/features/authentication/repositories/exceptions/authentication_exceptions.dart';
 import 'package:sign_in_with_apple/sign_in_with_apple.dart';
@@ -34,7 +37,41 @@ class SupabaseAuthenticationApi implements AuthenticationApi {
   });
 
   @override
-  Future<void> init() async {}
+  Future<void> init() async {
+    if (!kIsWeb) return;
+    // Complete a pending mobile-web Google redirect sign-in. Firebase handled the
+    // full-page redirect (we reuse its web OAuth client to mint the Google ID
+    // token — see [signinWithGoogle]), so on return we exchange that token for a
+    // Supabase session. No-op when no redirect is pending or a session already
+    // exists.
+    try {
+      final result = await fb_auth.FirebaseAuth.instance.getRedirectResult();
+      final idToken = (result.credential as fb_auth.OAuthCredential?)?.idToken;
+      if (idToken != null && client.auth.currentUser == null) {
+        await client.auth.signInWithIdToken(
+          provider: OAuthProvider.google,
+          idToken: idToken,
+        );
+      }
+    } catch (e) {
+      _logger.w('Google redirect sign-in completion failed: $e');
+    }
+  }
+
+  /// Mobile-web Google sign-in: start a full-page Firebase redirect instead of a
+  /// popup. Mobile browsers handle popups unreliably (the result is often lost
+  /// when the browser reclaims the backgrounded opener tab), leaving the app
+  /// stuck "signing in". The Supabase session is established at startup by [init]
+  /// via getRedirectResult. The page is navigating away as soon as
+  /// [signInWithRedirect] resolves, so this future intentionally never completes
+  /// — the caller stays in its loading state until the browser leaves.
+  /// See [isMobileWebBrowser].
+  Future<Credentials> _googleSignInWithRedirectWeb() async {
+    await fb_auth.FirebaseAuth.instance.signInWithRedirect(
+      fb_auth.GoogleAuthProvider(),
+    );
+    return Completer<Credentials>().future;
+  }
 
   @override
   Future<void> recoverPassword(String email) {
@@ -192,6 +229,11 @@ Note: wait a minute after enabling anonymous sign-in before trying again. It tak
 
   @override
   Future<Credentials> signinWithFacebook() async {
+    // Facebook on web for Supabase is not wired yet (roadmap); the button is hidden
+    // on web, so this is a defensive guard.
+    if (kIsWeb) {
+      throw ApiError(code: 501, message: 'Facebook sign-in on web is not supported on Supabase.');
+    }
     final loginResult = await FacebookAuth.instance.login(
       permissions: ['email', 'public_profile'],
     );
@@ -220,6 +262,7 @@ Note: wait a minute after enabling anonymous sign-in before trying again. It tak
   @override
   Future<Credentials> signinWithGoogle() async {
     if (kIsWeb) {
+      if (isMobileWebBrowser()) return _googleSignInWithRedirectWeb();
       // google_sign_in v7 can't do imperative auth on web. Get the Google ID token
       // via Firebase's popup (zero manual config — reuses the Firebase web OAuth
       // client + authorized domains, which the kit already sets up) and sign into
@@ -363,9 +406,21 @@ Note: wait a minute after enabling anonymous sign-in before trying again. It tak
   @override
   Future<Credentials> signupFromAnonymousWithGoogle() async {
     if (kIsWeb) {
-      // Web: get the Google ID token via Firebase's popup (see signinWithGoogle) and
-      // link it to the current anonymous Supabase user.
+      if (isMobileWebBrowser()) return _googleSignInWithRedirectWeb();
+      // Web: get the Google ID token via Firebase's popup (see signinWithGoogle).
       final idToken = await _googleIdTokenFromWebPopup();
+      // On web the app runs in authRequired mode, so there is usually no anonymous
+      // Supabase session to link to (the user state is just a local placeholder).
+      // Linking without a session sends the anon key, which has no `sub`, and Supabase
+      // rejects it with "missing sub claim". When there's no session, sign in normally
+      // — it creates the account from the Google id_token. Mirrors the Firebase backend.
+      if (client.auth.currentUser == null) {
+        final res = await client.auth.signInWithIdToken(
+          provider: OAuthProvider.google,
+          idToken: idToken,
+        );
+        return Credentials(id: res.user!.id, token: res.session?.accessToken ?? '');
+      }
       try {
         final response = await client.auth.linkIdentityWithIdToken(
           provider: OAuthProvider.google,
@@ -439,6 +494,11 @@ Note: wait a minute after enabling anonymous sign-in before trying again. It tak
 
   @override
   Future<Credentials> signupFromAnonymousWithFacebook() async {
+    // Facebook on web for Supabase is not wired yet (roadmap); the button is hidden
+    // on web, so this is a defensive guard.
+    if (kIsWeb) {
+      throw ApiError(code: 501, message: 'Facebook sign-in on web is not supported on Supabase.');
+    }
     final loginResult = await FacebookAuth.instance.login(
       permissions: ['email', 'public_profile'],
     );
@@ -595,6 +655,35 @@ Note: wait a minute after enabling anonymous sign-in before trying again. It tak
   Future<String?> getCurrentUserDisplayName() async =>
       client.auth.currentUser?.userMetadata?['full_name'] as String?;
 
+  @override
+  Future<String?> getCurrentUserPhotoUrl() async {
+    final meta = client.auth.currentUser?.userMetadata;
+    return (meta?['avatar_url'] ?? meta?['picture']) as String?;
+  }
+
+  @override
+  Future<List<String>> getLinkedProviders() async {
+    // Supabase exposes the linked identities in app_metadata['providers'].
+    final raw = client.auth.currentUser?.appMetadata['providers'];
+    if (raw is! List) return const [];
+    return raw.map((p) => p.toString()).toList();
+  }
+
+  @override
+  Future<void> setPassword(String password) async {
+    // Supabase keeps the same user; sets/updates the password so a social-only
+    // account can also sign in with email + password.
+    await client.auth.updateUser(UserAttributes(password: password));
+  }
+
+  // Supabase auto-links identities with the same (confirmed) email on sign-in,
+  // so there is no manual-link step: nothing to offer and nothing to do.
+  @override
+  Future<List<String>> linkableSocialProviders() async => const [];
+
+  @override
+  Future<void> linkSocialProvider(String provider) => Future.value();
+
   String _normalizePhoneNumber(String phoneNumber) {
     String normalized = phoneNumber.replaceAll(RegExp(r'\D'), '');
     if (!normalized.startsWith('+')) {

package/lib/scaffold/backends/supabase/patch/lib/features/authentication/repositories/authentication_repository.dart

@@ -68,6 +68,22 @@ abstract class AuthenticationRepository {
   /// Returns the display name of the authenticated user.
   Future<String?> getCurrentUserDisplayName();
 
+  /// Returns the photo URL of the current user (e.g. Google picture), or null.
+  Future<String?> getCurrentUserPhotoUrl();
+
+  /// Returns all sign-in providers linked to the current account.
+  Future<List<String>> getLinkedProviders();
+
+  /// Sets or updates an email/password credential for the current user, so a
+  /// social-only account can also sign in with email + password.
+  Future<void> setPassword(String password);
+
+  /// Social providers the current user can still link to their account.
+  Future<List<String>> linkableSocialProviders();
+
+  /// Links a social provider to the current account.
+  Future<void> linkSocialProvider(String provider);
+
   /// Signin with Google Play Games account on Android
   Future<void> signinWithGooglePlayGames();
 
@@ -268,6 +284,26 @@ class HttpAuthenticationRepository implements AuthenticationRepository {
   Future<String?> getCurrentUserDisplayName() =>
       _authenticationApi.getCurrentUserDisplayName();
 
+  @override
+  Future<String?> getCurrentUserPhotoUrl() =>
+      _authenticationApi.getCurrentUserPhotoUrl();
+
+  @override
+  Future<List<String>> getLinkedProviders() =>
+      _authenticationApi.getLinkedProviders();
+
+  @override
+  Future<void> setPassword(String password) =>
+      _authenticationApi.setPassword(password);
+
+  @override
+  Future<List<String>> linkableSocialProviders() =>
+      _authenticationApi.linkableSocialProviders();
+
+  @override
+  Future<void> linkSocialProvider(String provider) =>
+      _authenticationApi.linkSocialProvider(provider);
+
   @override
   Future<void> signinWithGooglePlayGames() async {
     try {

package/lib/scaffold/backends/supabase/patch/lib/features/subscriptions/api/entities/subscription_entity.dart

@@ -37,6 +37,7 @@ sealed class SubscriptionEntity with _$SubscriptionEntity {
     @JsonKey(name: 'creation_date') DateTime? creationDate,
     @JsonKey(name: 'last_update_date') DateTime? lastUpdateDate,
     @JsonKey(name: 'period_end_date') DateTime? periodEndDate,
+    @JsonKey(name: 'trial_end') DateTime? trialEnd,
     @JsonKey(name: 'status') required SubscriptionStatus status,
     @JsonKey(name: 'store', unknownEnumValue: SubscriptionStore.unknown)
     SubscriptionStore? store,

package/lib/scaffold/generate.js

@@ -86,11 +86,50 @@ const { FIREBASE_SOURCE_DIR } = require('./shared/backend-config');
  * @param {object}   [options.moduleAnswers={}]
  * @param {Function} [options.onProgress]  - Callback to update the spinner in the CLI.
  * @param {object}   [options.deploy]      - Used by the Firebase postBuild hook.
+ * @param {boolean}  [options.offline=false] - Validation mode: never touch the
+ *   network or the live Firebase project. Skips flutterfire configure, the Google
+ *   auth/iOS/SW patches it feeds, and the Firestore rules deploy; writes a
+ *   compilable stub for firebase_options_dev.dart so `flutter analyze` still works.
  * @param {object}   [hooks={}]
  * @param {Function|null} [hooks.applyBackendSetup]
  * @param {Function|null} [hooks.postBuild]
  * @returns {Promise<{steps: object[], packageName: string, appName: string, bundleId: string, firebaseProjectId: string}>}
  */
+
+/**
+ * Writes a compilable placeholder for lib/firebase_options_dev.dart, the file
+ * `flutterfire configure` normally generates from the real Firebase project.
+ *
+ * Used only by offline validation (`npm run validate:backends`): every backend's
+ * main.dart imports this file (Firebase powers FCM/remote config everywhere), so
+ * without it `flutter analyze` fails with "uri doesn't exist". The stub exposes
+ * the single member main.dart uses — DefaultFirebaseOptions.currentPlatform — with
+ * dummy values, so the analyzer type-checks the whole project without any network.
+ */
+async function writeFirebaseOptionsDevStub(targetDir) {
+  const stub = `// Offline validation stub written by \`npm run validate:backends\`.
+// NOT shipped to clients: \`kasy new\` runs \`flutterfire configure\`, which
+// generates the real file from their Firebase project. Present only so
+// \`flutter analyze\` can type-check without touching the network.
+// ignore_for_file: type=lint
+import 'package:firebase_core/firebase_core.dart' show FirebaseOptions;
+
+class DefaultFirebaseOptions {
+  static FirebaseOptions get currentPlatform => const FirebaseOptions(
+        apiKey: 'offline-validation-stub',
+        appId: 'offline-validation-stub',
+        messagingSenderId: 'offline-validation-stub',
+        projectId: 'offline-validation-stub',
+      );
+}
+`;
+  await fs.outputFile(
+    path.join(targetDir, 'lib', 'firebase_options_dev.dart'),
+    stub,
+    'utf8',
+  );
+}
+
 async function generateProject(targetDir, backend, options, hooks = {}) {
   const {
     appName,
@@ -102,6 +141,7 @@ async function generateProject(targetDir, backend, options, hooks = {}) {
     includeWeb = true,
     language = 'en',
     deferGoogleAuthPatches = false,
+    offline = false,
   } = options;
 
   const { applyBackendSetup = null, postBuild = null } = hooks;
@@ -361,9 +401,18 @@ async function generateProject(targetDir, backend, options, hooks = {}) {
     steps.push({ name: 'build-runner', skipped: true });
   }
 
-  onProgress('flutterfire');
-  const ffResult = await flutterfireConfigure(targetDir, firebaseProjectId, { includeWeb });
-  steps.push({ name: 'flutterfire', ok: ffResult.ok, detail: ffResult.ok ? null : ffResult.error });
+  // Offline validation never touches the network or the live Firebase project, so
+  // skip flutterfire and write a compilable stub for the file it would generate.
+  // ffResult.ok stays false → the flutterfire-dependent patches below are skipped.
+  let ffResult = { ok: false };
+  if (offline) {
+    await writeFirebaseOptionsDevStub(targetDir);
+    steps.push({ name: 'flutterfire', skipped: true, detail: 'offline (stub written)' });
+  } else {
+    onProgress('flutterfire');
+    ffResult = await flutterfireConfigure(targetDir, firebaseProjectId, { includeWeb });
+    steps.push({ name: 'flutterfire', ok: ffResult.ok, detail: ffResult.ok ? null : ffResult.error });
+  }
 
   // After flutterfire: patch Android, iOS and Web config files.
   if (ffResult.ok) {
@@ -421,7 +470,7 @@ async function generateProject(targetDir, backend, options, hooks = {}) {
   // ONLY for FCM push — there is no Firestore there, so deploying firestore:rules
   // is incoherent (it targets a database that doesn't exist) and just hangs for
   // minutes. The data layer for those backends is Supabase/the REST API.
-  if (backend === 'firebase' && firebaseProjectId) {
+  if (!offline && backend === 'firebase' && firebaseProjectId) {
     onProgress('firestore-rules');
     const rulesResult = await deployFirestoreRules(targetDir, firebaseProjectId);
     steps.push({ name: 'firestore-rules', ok: rulesResult.ok, detail: rulesResult.ok ? null : rulesResult.error });

package/lib/scaffold/shared/generator-utils.js

@@ -340,6 +340,7 @@ async function writeRouter(projectDir, modules, packageName, defaultPaywall = 'b
   lines.push(`import 'package:flutter_riverpod/flutter_riverpod.dart';`);
   lines.push(`import 'package:go_router/go_router.dart';`);
   lines.push(`import 'package:${pkg}/core/bottom_menu/bottom_menu.dart';`);
+  lines.push(`import 'package:${pkg}/core/chrome/chrome_visibility.dart';`);
   if (withAnalytics) {
     lines.push(`import 'package:${pkg}/core/data/api/analytics_api.dart';`);
   }
@@ -417,6 +418,7 @@ async function writeRouter(projectDir, modules, packageName, defaultPaywall = 'b
   if (withAnalytics) {
     lines.push(`      AnalyticsObserver(analyticsApi: MixpanelAnalyticsApi.instance()),`);
   }
+  lines.push(`      KasyChromeVisibilityObserver(),`);
   lines.push(`      ...?observers,`);
   lines.push(`    ],`);
   lines.push(`    routes: [`);
@@ -624,10 +626,15 @@ async function writeFeaturesConfig(projectDir, modules, answers = {}, language =
   const withStripe              = modules.includes('stripe');
   const withLocalReminders  = modules.includes('local_reminders');
   const withWeb                 = modules.includes('web');
-  // Apple sign-in on web only works on Firebase (signInWithPopup). Supabase/API
-  // throw on web (no Service ID + token exchange), so they must ship this false
-  // and hide the Apple button on web. Native always shows it.
-  const withAppleWebSignin = backend === 'firebase';
+  // Apple sign-in on web needs a Service ID + signed secret that don't exist until
+  // the developer configures it (`kasy apple-web`). Until then, showing the button
+  // means a dead button on web, so it ships false on every backend and the command
+  // flips it to true once web Apple actually works. Native always shows it.
+  const withAppleWebSignin = false;
+  // Facebook sign-in on web works on the Firebase backend (signInWithPopup) after
+  // `kasy facebook`; on Supabase the web flow isn't wired yet (roadmap). Ships false
+  // on every backend (the command flips it to true on Firebase). Native always shows.
+  const withFacebookWebSignin = false;
 
   const f = getStrings(language).features;
   const content = `${f.comment1}
@@ -644,9 +651,14 @@ const bool withStripePromoCodes = true;
 // When true, the Stripe Customer Portal lets subscribers switch plans (upgrade / downgrade).
 const bool withStripePlanSwitching = true;
 const bool withLocalReminders  = ${withLocalReminders};
-// Apple sign-in on web: Firebase supports it (signInWithPopup); Supabase/API throw
-// on web, so they ship false. Native always shows the Apple button.
+// Apple sign-in on web: ships false until configured with \`kasy apple-web\` (needs a
+// paid Apple Service ID + signed secret). The command flips this to true once web
+// Apple actually works, so the button never appears dead. Native always shows it.
 const bool withAppleWebSignin = ${withAppleWebSignin};
+// Facebook sign-in on web: ships false until configured with \`kasy facebook\` on the
+// Firebase backend (signInWithPopup). On Supabase the web flow is roadmap, so it stays
+// false there. Native (iOS/Android) always shows the Facebook button.
+const bool withFacebookWebSignin = ${withFacebookWebSignin};
 ${f.comment3}
 ${f.comment4}
 ${f.comment5}

package/lib/utils/apple-web.js

@@ -0,0 +1,147 @@
+/**
+ * Apple "Sign in with Apple" WEB support helpers.
+ *
+ * The native iOS/macOS flow needs no secret — the CLI already enables it on both
+ * backends at project creation. The WEB (and Android, which we hide) flow uses
+ * Apple's OAuth, which requires a Service ID + a client secret that is a short-lived
+ * JWT signed with the developer's `.p8` private key.
+ *
+ * Apple offers NO API to create the Service ID or the `.p8` key — those stay manual
+ * on developer.apple.com (done once per Apple account). What we CAN automate is
+ * taking the four inputs the developer already created and pushing them to the
+ * backend:
+ *   - Firebase: store Service ID + Team ID + Key ID + `.p8` in the Apple provider
+ *     (Firebase re-signs the JWT itself, so it never expires).
+ *   - Supabase: sign the JWT here and store it as external_apple_secret (Supabase
+ *     cannot re-sign, so this expires every 6 months and must be regenerated).
+ *
+ * This module: (1) signs the Apple client-secret JWT with node:crypto (no extra
+ * dependency), and (2) caches the four inputs in ~/.kasy/apple-web.json so future
+ * projects (and the 6-month Supabase renewal) configure web Apple without re-asking.
+ */
+
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const fs = require('fs-extra');
+
+// Apple caps the client-secret JWT lifetime at 6 months. We sign for 180 days to
+// stay safely under the limit. Firebase ignores this (it re-signs); Supabase stores
+// the JWT verbatim, so this is the value behind its "expires every 6 months" notice.
+const APPLE_SECRET_MAX_SECONDS = 180 * 24 * 60 * 60;
+
+const CONFIG_DIR = path.join(os.homedir(), '.kasy');
+const APPLE_WEB_CONFIG_PATH = path.join(CONFIG_DIR, 'apple-web.json');
+
+/** base64url-encode a string or Buffer (no padding, URL-safe alphabet). */
+function base64url(input) {
+  return Buffer.from(input)
+    .toString('base64')
+    .replace(/=+$/g, '')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_');
+}
+
+/**
+ * Normalize a `.p8` private key that may arrive with literal "\n" sequences
+ * (common when pasted from a one-line env var) into real newlines so
+ * crypto.createPrivateKey can parse the PEM.
+ */
+function normalizePrivateKey(privateKey) {
+  const key = String(privateKey || '').trim();
+  if (key.includes('-----BEGIN') && !key.includes('\n') && key.includes('\\n')) {
+    return key.replace(/\\n/g, '\n');
+  }
+  return key;
+}
+
+/**
+ * Sign the Apple "Sign in with Apple" client secret (an ES256 JWT).
+ *
+ * @param {object} opts
+ * @param {string} opts.serviceId   - Apple Service ID (the OAuth client_id), e.g. com.acme.app.signin
+ * @param {string} opts.teamId      - Apple Developer Team ID
+ * @param {string} opts.keyId       - Key ID of the .p8
+ * @param {string} opts.privateKey  - PEM contents of the .p8 (PKCS#8 EC P-256)
+ * @param {number} [opts.expiresInSeconds] - lifetime; clamped to Apple's 6-month max
+ * @returns {{ token: string, issuedAt: number, expiresAt: number }}
+ */
+function signAppleClientSecret({ serviceId, teamId, keyId, privateKey, expiresInSeconds = APPLE_SECRET_MAX_SECONDS } = {}) {
+  if (!serviceId) throw new Error('serviceId (Apple Service ID) is required');
+  if (!teamId) throw new Error('teamId (Apple Team ID) is required');
+  if (!keyId) throw new Error('keyId is required');
+  if (!privateKey) throw new Error('privateKey (.p8 contents) is required');
+
+  const issuedAt = Math.floor(Date.now() / 1000);
+  const expiresAt = issuedAt + Math.min(expiresInSeconds, APPLE_SECRET_MAX_SECONDS);
+
+  const header = { alg: 'ES256', kid: keyId };
+  const payload = {
+    iss: teamId,
+    iat: issuedAt,
+    exp: expiresAt,
+    aud: 'https://appleid.apple.com',
+    sub: serviceId,
+  };
+
+  const signingInput = `${base64url(JSON.stringify(header))}.${base64url(JSON.stringify(payload))}`;
+
+  let keyObject;
+  try {
+    keyObject = crypto.createPrivateKey(normalizePrivateKey(privateKey));
+  } catch (err) {
+    throw new Error(`Invalid Apple .p8 private key: ${err.message}`);
+  }
+
+  // ES256 JWTs need the raw r||s signature (IEEE P1363), not DER.
+  const signature = crypto.sign('sha256', Buffer.from(signingInput), {
+    key: keyObject,
+    dsaEncoding: 'ieee-p1363',
+  });
+
+  return { token: `${signingInput}.${base64url(signature)}`, issuedAt, expiresAt };
+}
+
+/**
+ * Load cached Apple web credentials from ~/.kasy/apple-web.json.
+ * Returns null if absent or incomplete.
+ */
+async function loadAppleWebCreds() {
+  try {
+    if (!(await fs.pathExists(APPLE_WEB_CONFIG_PATH))) return null;
+    const data = await fs.readJson(APPLE_WEB_CONFIG_PATH);
+    if (!data || !data.serviceId || !data.teamId || !data.keyId || !data.privateKey) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persist Apple web credentials to ~/.kasy/apple-web.json with 0600 perms so the
+ * 6-month Supabase renewal and future projects can reuse them without re-asking.
+ */
+async function saveAppleWebCreds({ serviceId, teamId, keyId, privateKey }) {
+  await fs.ensureDir(CONFIG_DIR);
+  await fs.writeJson(
+    APPLE_WEB_CONFIG_PATH,
+    { serviceId, teamId, keyId, privateKey: normalizePrivateKey(privateKey) },
+    { spaces: 2 },
+  );
+  // Best effort: restrict to the owner (no-op / unsupported on some Windows setups).
+  try {
+    await fs.chmod(APPLE_WEB_CONFIG_PATH, 0o600);
+  } catch {
+    /* ignore */
+  }
+}
+
+module.exports = {
+  APPLE_SECRET_MAX_SECONDS,
+  APPLE_WEB_CONFIG_PATH,
+  base64url,
+  normalizePrivateKey,
+  signAppleClientSecret,
+  loadAppleWebCreds,
+  saveAppleWebCreds,
+};

package/lib/utils/facebook.js

@@ -0,0 +1,162 @@
+/**
+ * Facebook Login helpers, shared by `kasy facebook` and `kasy configure`.
+ *
+ * Facebook needs values in two places:
+ *   - Client side (the app): App ID + Client Token in iOS Info.plist and Android
+ *     strings.xml (build-time). Same for every backend.
+ *   - Backend provider (server side): App ID + App Secret on Firebase (Identity
+ *     Toolkit) or Supabase (Management API). Configured by the backend writers.
+ *
+ * The Meta-side work (create the app, get App ID / Client Token / App Secret, set
+ * OAuth redirect URIs and JS domains) has no automation API — it stays manual and
+ * is guided by `kasy facebook`. This module owns the native-file read/write and the
+ * ~/.kasy/facebook.json credential cache so future projects reuse the values.
+ */
+
+const os = require('node:os');
+const path = require('node:path');
+const fs = require('fs-extra');
+
+const CONFIG_DIR = path.join(os.homedir(), '.kasy');
+const FACEBOOK_CONFIG_PATH = path.join(CONFIG_DIR, 'facebook.json');
+
+// ── Native build-time files (Info.plist + strings.xml) ──────────────────────
+
+function readFacebookCurrent(content, kind) {
+  if (kind === 'plist') {
+    const appId = content.match(/<key>FacebookAppID<\/key>\s*<string>([^<]*)<\/string>/);
+    const token = content.match(/<key>FacebookClientToken<\/key>\s*<string>([^<]*)<\/string>/);
+    return { appId: (appId?.[1] || '').trim(), token: (token?.[1] || '').trim() };
+  }
+  // strings.xml
+  const appId = content.match(/<string name="facebook_app_id"[^>]*>([^<]*)<\/string>/);
+  const token = content.match(/<string name="facebook_client_token"[^>]*>([^<]*)<\/string>/);
+  return { appId: (appId?.[1] || '').trim(), token: (token?.[1] || '').trim() };
+}
+
+function isFacebookPlaceholder(value) {
+  return !value || /^0+$/.test(value);
+}
+
+async function readFacebookState(projectDir) {
+  const plistPath = path.join(projectDir, 'ios', 'Runner', 'Info.plist');
+  const stringsPath = path.join(projectDir, 'android', 'app', 'src', 'main', 'res', 'values', 'strings.xml');
+  const state = { appId: '', token: '', plistExists: false, stringsExists: false };
+  if (await fs.pathExists(plistPath)) {
+    state.plistExists = true;
+    const plistRead = readFacebookCurrent(await fs.readFile(plistPath, 'utf8'), 'plist');
+    if (!isFacebookPlaceholder(plistRead.appId)) state.appId = plistRead.appId;
+    if (!isFacebookPlaceholder(plistRead.token)) state.token = plistRead.token;
+  }
+  if (await fs.pathExists(stringsPath)) {
+    state.stringsExists = true;
+    const stringsRead = readFacebookCurrent(await fs.readFile(stringsPath, 'utf8'), 'strings');
+    // Prefer plist value when both exist; only fall back if plist was placeholder.
+    if (!state.appId && !isFacebookPlaceholder(stringsRead.appId)) state.appId = stringsRead.appId;
+    if (!state.token && !isFacebookPlaceholder(stringsRead.token)) state.token = stringsRead.token;
+  }
+  return state;
+}
+
+async function writeFacebookCredentials(projectDir, appId, clientToken) {
+  const plistPath = path.join(projectDir, 'ios', 'Runner', 'Info.plist');
+  const stringsPath = path.join(projectDir, 'android', 'app', 'src', 'main', 'res', 'values', 'strings.xml');
+  const results = { plist: 'skipped', strings: 'skipped' };
+
+  if (appId && (await fs.pathExists(plistPath))) {
+    let plist = await fs.readFile(plistPath, 'utf8');
+    plist = plist.replace(
+      /(<key>FacebookAppID<\/key>\s*<string>)[^<]*(<\/string>)/,
+      `$1${appId}$2`,
+    );
+    if (clientToken) {
+      plist = plist.replace(
+        /(<key>FacebookClientToken<\/key>\s*<string>)[^<]*(<\/string>)/,
+        `$1${clientToken}$2`,
+      );
+    }
+    // CFBundleURLSchemes — replace `fb<zeros>` with `fb<appId>` so deep links work.
+    plist = plist.replace(/<string>fb0+<\/string>/, `<string>fb${appId}</string>`);
+    await fs.outputFile(plistPath, plist, 'utf8');
+    results.plist = 'ok';
+  } else if (appId) {
+    results.plist = 'missing_file';
+  }
+
+  if (appId && (await fs.pathExists(stringsPath))) {
+    let xml = await fs.readFile(stringsPath, 'utf8');
+    xml = xml.replace(
+      /(<string name="facebook_app_id"[^>]*>)[^<]*(<\/string>)/,
+      `$1${appId}$2`,
+    );
+    if (clientToken) {
+      xml = xml.replace(
+        /(<string name="facebook_client_token"[^>]*>)[^<]*(<\/string>)/,
+        `$1${clientToken}$2`,
+      );
+    }
+    // fb_login_protocol_scheme — set if present.
+    xml = xml.replace(
+      /(<string name="fb_login_protocol_scheme"[^>]*>)[^<]*(<\/string>)/,
+      `$1fb${appId}$2`,
+    );
+    await fs.outputFile(stringsPath, xml, 'utf8');
+    results.strings = 'ok';
+  } else if (appId) {
+    results.strings = 'missing_file';
+  }
+
+  return results;
+}
+
+// ── Credential cache (~/.kasy/facebook.json) ────────────────────────────────
+
+/** Load cached Facebook credentials. Returns null if absent or without an App ID. */
+async function loadFacebookCreds() {
+  try {
+    if (!(await fs.pathExists(FACEBOOK_CONFIG_PATH))) return null;
+    const data = await fs.readJson(FACEBOOK_CONFIG_PATH);
+    if (!data || !data.appId) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+/** Persist Facebook credentials (App ID + Client Token + App Secret) with 0600. */
+async function saveFacebookCreds({ appId, clientToken, appSecret }) {
+  await fs.ensureDir(CONFIG_DIR);
+  await fs.writeJson(
+    FACEBOOK_CONFIG_PATH,
+    { appId, clientToken: clientToken || '', appSecret: appSecret || '' },
+    { spaces: 2 },
+  );
+  try {
+    await fs.chmod(FACEBOOK_CONFIG_PATH, 0o600);
+  } catch {
+    /* ignore */
+  }
+}
+
+/** Set `withFacebookWebSignin` to the given boolean in the project's features.dart. */
+async function setFacebookWebFlag(projectDir, value) {
+  const file = path.join(projectDir, 'lib', 'core', 'config', 'features.dart');
+  if (!(await fs.pathExists(file))) return { ok: false, missing: true };
+  let content = await fs.readFile(file, 'utf8');
+  const re = /const bool withFacebookWebSignin\s*=\s*(?:true|false)\s*;/;
+  if (!re.test(content)) return { ok: false, missing: true };
+  content = content.replace(re, `const bool withFacebookWebSignin = ${value};`);
+  await fs.writeFile(file, content, 'utf8');
+  return { ok: true };
+}
+
+module.exports = {
+  FACEBOOK_CONFIG_PATH,
+  readFacebookCurrent,
+  isFacebookPlaceholder,
+  readFacebookState,
+  writeFacebookCredentials,
+  loadFacebookCreds,
+  saveFacebookCreds,
+  setFacebookWebFlag,
+};