kasy-cli 1.31.14 → 1.34.0

package/lib/scaffold/backends/supabase/edge-functions/send-push-notification/README.md

@@ -1,35 +1,39 @@
 # send-push-notification
 
-Edge Function que envia push notifications via Firebase Cloud Messaging (FCM) quando uma notificação é inserida na tabela `notifications`.
+Edge Function que envia push notifications via Firebase Cloud Messaging (FCM)
+quando uma notificação é inserida na tabela `notifications`.
 
-## Setup (1x por projeto)
+## Tudo isto é automático
 
-### 1. Configurar secrets no Supabase
+O `kasy new` e o `kasy deploy` já deixam o push funcionando no Supabase, sem passo
+manual:
 
-```bash
-supabase secrets set FIREBASE_PROJECT_ID=your-firebase-project-id
-supabase secrets set FIREBASE_SERVICE_ACCOUNT_JSON='{"type":"service_account","project_id":"..."}'
-```
+- **Secrets** `FIREBASE_PROJECT_ID` e `FIREBASE_SERVICE_ACCOUNT_JSON` são definidos
+  automaticamente (a chave de Service Account é gerada pela CLI).
+- **A chamada automática** da função quando uma notificação é inserida vem de um
+  **trigger no banco** (`pg_net`), criado pela migration
+  `20240101000006_notification_webhook.sql`. **Não é** um Database Webhook do painel.
+- O trigger só dispara quando `notify_user IS DISTINCT FROM false` (ex.: a notificação
+  de boas-vindas usa `notify_user = false` porque o usuário já está dentro do app).
+
+> ⚠️ **Não crie um Database Webhook no painel** apontando para esta função. O trigger
+> `pg_net` já faz isso; um webhook duplicado faria o push **disparar duas vezes**.
 
-O JSON do service account: Firebase Console → Project Settings → Service Accounts → **Generate new private key**.
+## Fallback manual (só se a automação falhar)
 
-### 2. Deploy da Edge Function
+Se por algum motivo os secrets não tiverem sido definidos, rode:
 
 ```bash
+supabase secrets set FIREBASE_PROJECT_ID=your-firebase-project-id
+supabase secrets set FIREBASE_SERVICE_ACCOUNT_JSON='{"type":"service_account","project_id":"..."}'
 supabase functions deploy send-push-notification --project-ref YOUR_PROJECT_REF
 ```
 
-### 3. Configurar Database Webhook
-
-No Supabase Dashboard → **Database → Webhooks → Create webhook**:
-
-| Campo | Valor |
-|-------|-------|
-| Name | `on_notification_inserted` |
-| Table | `notifications` |
-| Events | `INSERT` |
-| Method | POST |
-| URL | `https://YOUR_PROJECT_REF.supabase.co/functions/v1/send-push-notification` |
-| Headers | `Authorization: Bearer YOUR_SUPABASE_ANON_KEY` |
+O JSON do service account: Firebase Console → Project Settings → Service Accounts →
+**Generate new private key**.
 
-Sem este webhook, a edge function não é chamada automaticamente.
+Se preferir o trigger via painel em vez do `pg_net` (não recomendado, e nunca os dois
+ao mesmo tempo), use Database → Webhooks → Create webhook na tabela `notifications`,
+evento `INSERT`, POST para
+`https://YOUR_PROJECT_REF.supabase.co/functions/v1/send-push-notification`,
+header `Authorization: Bearer YOUR_SUPABASE_ANON_KEY`.

package/lib/scaffold/backends/supabase/edge-functions/send-push-notification/index.ts

@@ -1,22 +1,19 @@
 /**
  * Supabase Edge Function: Send Push Notification via FCM
  *
- * Triggered by a Supabase Database Webhook when a row is inserted
- * into the `notifications` table. Reads device FCM tokens for the
- * target user and sends a push notification via Firebase Cloud Messaging
- * HTTP v1 API.
+ * Triggered automatically by a database trigger (pg_net) when a row is inserted
+ * into the `notifications` table with notify_user != false (migration
+ * 20240101000006_notification_webhook.sql) — NOT by a Dashboard Database Webhook.
+ * Reads device FCM tokens for the target user and sends a push notification via
+ * Firebase Cloud Messaging HTTP v1 API.
  *
- * Secrets required (set via `supabase secrets set`):
+ * Secrets (set automatically by `kasy new` / `kasy deploy`):
  *   - FIREBASE_PROJECT_ID: Your Firebase project ID (e.g. my-app-12345)
  *   - FIREBASE_SERVICE_ACCOUNT_JSON: Full JSON of your Firebase service account key
  *       (Firebase Console → Project Settings → Service Accounts → Generate new private key)
  *
- * Database Webhook setup (Supabase Dashboard → Database → Webhooks):
- *   - Table: notifications
- *   - Event: INSERT
- *   - Method: POST
- *   - URL: https://<PROJECT_REF>.supabase.co/functions/v1/send-push-notification
- *   - HTTP Headers: Authorization: Bearer <SUPABASE_ANON_KEY>
+ * Do NOT also create a Dashboard Database Webhook for this function — the pg_net
+ * trigger already calls it; a second webhook would double-fire push. See README.md.
  *
  * @see https://firebase.google.com/docs/cloud-messaging/send-message
  */

package/lib/scaffold/backends/supabase/edge-functions/stripe-create-checkout-session/index.ts

@@ -97,7 +97,7 @@ Deno.serve(async (req: Request) => {
   }
   const uid = user.id;
 
-  let body: { priceId?: string; successUrl?: string; cancelUrl?: string; locale?: string };
+  let body: { priceId?: string; successUrl?: string; cancelUrl?: string; locale?: string; allowPromoCodes?: boolean };
   try {
     body = await req.json();
   } catch {
@@ -110,6 +110,7 @@ Deno.serve(async (req: Request) => {
   const successUrl = body.successUrl ?? "";
   const cancelUrl = body.cancelUrl ?? successUrl;
   const locale = body.locale?.substring(0, 2).toLowerCase();
+  const allowPromoCodes = body.allowPromoCodes === true;
 
   try {
     const stripe = new Stripe(secretKey);
@@ -136,6 +137,7 @@ Deno.serve(async (req: Request) => {
         metadata: { supabaseUID: uid },
         ...(trialDays ? { trial_period_days: trialDays } : {}),
       },
+      ...(allowPromoCodes ? { allow_promotion_codes: true } : {}),
     });
     return Response.json({ url: session.url }, { headers: corsHeaders });
   } catch (err) {

package/lib/scaffold/backends/supabase/edge-functions/stripe-create-portal-session/index.ts

@@ -1,8 +1,8 @@
 /**
  * Supabase Edge Function: Stripe — Create Customer Portal Session
  *
- * Creates a Stripe Customer Portal session (manage / cancel) for the
- * authenticated user and returns its URL. The user is identified by the
+ * Creates a Stripe Customer Portal session (manage / cancel / switch plan) for
+ * the authenticated user and returns its URL. The user is identified by the
  * verified JWT and the Stripe customer is looked up server-side.
  *
  * Deployed WITHOUT the platform JWT gate (verify_jwt = false in config.toml) so the
@@ -13,7 +13,10 @@
  *   - STRIPE_SECRET_KEY
  *   - SUPABASE_URL / SUPABASE_ANON_KEY / SUPABASE_SERVICE_ROLE_KEY (auto-provided)
  *
- * Body: { returnUrl?: string }
+ * Optional env var:
+ *   - STRIPE_PRODUCT_ID: narrows plan-switching to a single product's prices.
+ *
+ * Body: { returnUrl?: string, planSwitching?: boolean }
  */
 
 import Stripe from "npm:stripe@18";
@@ -39,6 +42,52 @@ async function getUid(req: Request, supabaseUrl: string, anonKey: string): Promi
   return user.id;
 }
 
+// Creates (once) a Customer Portal configuration with subscription_update
+// (plan switching) enabled, then reuses it on every subsequent call.
+// Uses the Stripe list API to find an existing config — no extra DB table needed.
+// deno-lint-ignore no-explicit-any
+async function getOrCreatePortalConfig(stripe: Stripe): Promise<string | undefined> {
+  // Reuse an existing active config with plan switching already enabled
+  const configs = await stripe.billingPortal.configurations.list({ active: true, limit: 20 });
+  // deno-lint-ignore no-explicit-any
+  const existing = configs.data.find((c: any) => c.features?.subscription_update?.enabled);
+  if (existing) return existing.id;
+
+  // Build the price list grouped by product so Stripe knows what to switch between
+  const productId = Deno.env.get("STRIPE_PRODUCT_ID") ?? "";
+  // deno-lint-ignore no-explicit-any
+  const priceListParams: any = { active: true, type: "recurring", limit: 100 };
+  if (productId) priceListParams.product = productId;
+  const { data: prices } = await stripe.prices.list(priceListParams);
+
+  if (prices.length === 0) return undefined;
+
+  const byProduct: Record<string, string[]> = {};
+  for (const p of prices) {
+    // deno-lint-ignore no-explicit-any
+    const pid = typeof p.product === "string" ? p.product : (p.product as any).id;
+    if (!byProduct[pid]) byProduct[pid] = [];
+    byProduct[pid].push(p.id);
+  }
+  const products = Object.entries(byProduct).map(([prod, priceIds]) => ({
+    product: prod,
+    prices: priceIds,
+  }));
+
+  const config = await stripe.billingPortal.configurations.create({
+    features: {
+      subscription_update: {
+        enabled: true,
+        default_allowed_updates: ["price"],
+        products,
+      },
+      subscription_cancel: { enabled: true, mode: "at_period_end" },
+      payment_method_update: { enabled: true },
+    },
+  });
+  return config.id;
+}
+
 Deno.serve(async (req: Request) => {
   if (req.method === "OPTIONS") {
     return new Response(null, { status: 204, headers: corsHeaders });
@@ -61,9 +110,11 @@ Deno.serve(async (req: Request) => {
   }
 
   let returnUrl = "";
+  let planSwitching = false;
   try {
     const body = await req.json();
     returnUrl = (body?.returnUrl as string | undefined) ?? "";
+    planSwitching = body?.planSwitching === true;
   } catch {
     // body is optional
   }
@@ -84,9 +135,15 @@ Deno.serve(async (req: Request) => {
     }
 
     const stripe = new Stripe(secretKey);
+
+    // When plan switching is requested, resolve (or create) a portal configuration
+    // with subscription_update enabled — no manual Stripe dashboard setup needed.
+    const configId = planSwitching ? await getOrCreatePortalConfig(stripe) : undefined;
+
     const session = await stripe.billingPortal.sessions.create({
       customer: customerId,
       return_url: returnUrl,
+      ...(configId ? { configuration: configId } : {}),
     });
     return Response.json({ url: session.url }, { headers: corsHeaders });
   } catch (err) {

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

@@ -150,6 +150,13 @@ Note: wait a minute after enabling anonymous sign-in before trying again. It tak
 
   @override
   Future<Credentials> signinWithApple() async {
+    // Apple on web needs a paid Apple Service ID + secret (not configured here);
+    // getAppleIDCredential force-unwraps webAuthenticationOptions and crashes on
+    // web. The UI hides the Apple button on web; guard here too so a programmatic
+    // call fails with a clear error instead of a null-check crash.
+    if (kIsWeb) {
+      throw ApiError(code: 501, message: 'Apple sign-in on web is not supported.');
+    }
     final rawNonce = client.auth.generateRawNonce();
     final hashedNonce = sha256.convert(utf8.encode(rawNonce)).toString();
 
@@ -185,6 +192,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'],
     );
@@ -309,6 +321,11 @@ Note: wait a minute after enabling anonymous sign-in before trying again. It tak
   
   @override
   Future<Credentials> signupFromAnonymousWithApple() async {
+    // See signinWithApple: Apple on web is unsupported here; the UI hides the button
+    // on web, and this guard prevents a null-check crash on a programmatic call.
+    if (kIsWeb) {
+      throw ApiError(code: 501, message: 'Apple sign-in on web is not supported.');
+    }
     final rawNonce = client.auth.generateRawNonce();
     final hashedNonce = sha256.convert(utf8.encode(rawNonce)).toString();
 
@@ -427,6 +444,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'],
     );

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

@@ -30,6 +30,7 @@ class StripeBackendApi {
     String? successUrl,
     String? cancelUrl,
     String? locale,
+    bool? allowPromoCodes,
   }) async {
     final res = await _client.functions.invoke(
       'stripe-create-checkout-session',
@@ -38,16 +39,25 @@ class StripeBackendApi {
         if (successUrl != null) 'successUrl': successUrl,
         if (cancelUrl != null) 'cancelUrl': cancelUrl,
         if (locale != null) 'locale': locale,
+        if (allowPromoCodes != null) 'allowPromoCodes': allowPromoCodes,
       },
     );
     return (res.data as Map)['url'] as String;
   }
 
   /// Create a Customer Portal session (manage / cancel) and return its URL.
-  Future<String> createPortalSession({String? returnUrl}) async {
+  /// Pass [planSwitching] = true to auto-configure the portal with
+  /// upgrade/downgrade support (no manual Stripe dashboard setup needed).
+  Future<String> createPortalSession({
+    String? returnUrl,
+    bool? planSwitching,
+  }) async {
     final res = await _client.functions.invoke(
       'stripe-create-portal-session',
-      body: {if (returnUrl != null) 'returnUrl': returnUrl},
+      body: {
+        if (returnUrl != null) 'returnUrl': returnUrl,
+        if (planSwitching != null) 'planSwitching': planSwitching,
+      },
     );
     return (res.data as Map)['url'] as String;
   }

package/lib/scaffold/backends/supabase/pubspec.yaml.tpl

@@ -25,12 +25,13 @@ dependencies:
   dio: ^5.9.2
   facebook_app_events: ^0.24.0
   firebase_app_installations: ^0.4.0+7
-  firebase_core: ^4.5.0
   # Web-only Google sign-in: on web, google_sign_in v7 can't do imperative auth, so we
-  # get the Google ID token via Firebase's popup (zero manual config — reuses the
+  # get the Google ID token via Firebase's popup (zero manual config, reuses the
   # Firebase web client + authorized domains) and hand it to Supabase signInWithIdToken.
   # Supabase stays the auth backend; mobile keeps the native google_sign_in flow.
+  # Kept before firebase_core so the deps stay alphabetical (sort_pub_dependencies).
   firebase_auth: ^6.1.4
+  firebase_core: ^4.5.0
   firebase_messaging: ^16.1.2
   firebase_remote_config: ^6.2.0
   flutter:

package/lib/scaffold/generate.js

@@ -219,7 +219,7 @@ async function generateProject(targetDir, backend, options, hooks = {}) {
     await writeVsCodeLaunch(targetDir, appName, backend, modules, answers, language);
     await writeEnvExample(targetDir, modules, answers, language);
     await writeEnvFileIfMissing(targetDir);
-    await writeFeaturesConfig(targetDir, modules, answers, language);
+    await writeFeaturesConfig(targetDir, modules, answers, language, backend);
     await writeRouter(targetDir, modules, packageName, moduleAnswers.defaultPaywall || 'basic');
     await writeMakefile(targetDir, language, backend, modules, answers);
     await writeKitSetup(targetDir, {

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: [`);
@@ -616,7 +618,7 @@ async function writeRouter(projectDir, modules, packageName, defaultPaywall = 'b
  * @param {object} [answers={}] - moduleAnswers (rcTestKey, stripe keys, etc.)
  * @param {string} [language='en'] - User's CLI language (en, pt, es)
  */
-async function writeFeaturesConfig(projectDir, modules, answers = {}, language = 'en') {
+async function writeFeaturesConfig(projectDir, modules, answers = {}, language = 'en', backend = 'firebase') {
   const withOnboarding = modules.includes('onboarding');
   const withAiChat   = modules.includes('ai_chat');
   const withFeedback            = modules.includes('feedback');
@@ -624,6 +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 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}
@@ -635,7 +646,19 @@ const bool withFeedback            = ${withFeedback};
 const bool withRevenuecat          = ${withRevenuecat};
 // Stripe web subscriptions module (independent from RevenueCat mobile IAP).
 const bool withStripe              = ${withStripe};
+// When true, Stripe Checkout shows a promo-code / coupon field.
+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: 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}
@@ -1347,10 +1370,18 @@ async function removeFacebookSigninFromAuthPages(projectDir) {
   for (const p of pages) {
     if (!(await fs.pathExists(p))) continue;
     let content = await fs.readFile(p, 'utf8');
-    // Remove import line
+    // Legacy: remove the standalone FacebookSigninComponent + its import, if present.
     content = content.replace(/^import 'package:[^']+\/features\/authentication\/ui\/components\/facebook_signin\.dart';\n/m, '');
-    // Remove component line (any leading whitespace)
     content = content.replace(/[ \t]*const FacebookSigninComponent\(\),\n/g, '');
+    // Current UI: the Facebook button is an inline _SocialSigninTile/_SocialSignupTile
+    // in the social row (label: t.auth.signin.facebook ... signinWithFacebook()). Strip
+    // the whole tile plus the SizedBox spacer that precedes it, anchored on the facebook
+    // label so the Google/Apple tiles are never touched. Runs before dartFix/format, so
+    // it matches the kit's raw formatting verbatim.
+    content = content.replace(
+      /\n[ \t]*const SizedBox\(width: KasySpacing\.sm\),\n[ \t]*Expanded\(\n[ \t]*child: _Social(?:Signin|Signup)Tile\(\n[ \t]*label: t\.auth\.signin\.facebook,[\s\S]*?\.signinWithFacebook\(\),\n[ \t]*\),\n[ \t]*\),/,
+      '',
+    );
     await fs.writeFile(p, content, 'utf8');
   }
 }

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,
+};