Guides the agent through migrating Capacitor apps from Ionic Enterprise SDK plugins to Capgo and Capacitor alternatives. Covers dependency detection, API replacement, local storage changes, and platform cleanup. Do not use for generic Capacitor version upgrades or Capgo live updates.

Ionic Enterprise SDK Migration Replace Ionic Enterprise plugins with open Capgo plugins one at a time, preserving login sessions and stored data. Context: Ionic stopped selling its commercial products (including the Enterprise SDK) in February 2025 and is winding down maintenance; plan migrations before the license or support window ends. When to Use TRIGGER when: package.json contains @ionic enterprise/auth , @ionic enterprise/identity vault , or @ionic enterprise/secure storage . Code imports AuthConnect , ProviderOptions , Vault , BrowserVault , VaultType , DeviceSecurityType , or Secure Storage's SQLite / KeyValueStorage . The user asks how to replace Auth Connect, Identity Vault, or Secure Storage without forcing re login. Do not use for: Appflow Live Updates / builds ionic appflow migration . Community or other SQLite plugins sqlite to fast sql . Biometric UX or general security review capacitor security . Live Project Snapshot Detected Ionic Enterprise and replacement packages: ! node e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section] {})){if(name.startsWith('@ionic enterprise/') name.startsWith('@capgo/') name==='@capacitor/preferences' name==='@capacitor/core')out.push(section+'.'+name+'='+version)}}console.log(out.sort().join('\n'))" Replacement Map Ionic Enterprise Replacement Covers Not covered (rebuild in app) Auth Connect @capgo/capacitor social login ( provider: 'oauth2' for OIDC/OAuth2 IdPs; google , apple , facebook , etc.) Authorization code + PKCE, token refresh ( refreshToken ), logout, native Apple/Google sign in Token storage policy (store tokens with Native Biometric or encrypted SQL) Identity Vault @capgo/capacitor native biometric Save/read/delete credentials in Keychain/Keystore; accessControl: BIOMETRY CURRENT SET or BIOMETRY ANY makes reads require biometrics; verifyIdentity with passcode fallback on iOS; biometryChange listener Inactivity lock timeout, privacy screen on background ( @capacitor/privacy screen ), custom passcode vaults, in memory vaults Secure Storage (SQLite) @capgo/capacitor fast sql with encrypted: true + encryptionKey Encrypted SQLite (SQLCipher), transactions, batch, KeyValueStore Key management keep the DB key in Native Biometric, not in JS constants Secure Storage (key value) @capgo/capacitor data storage sqlite or Fast SQL KeyValueStore Simple encrypted key value Non sensitive settings can go to @capacitor/preferences . Never move tokens or secrets there. Procedure Step 1: Detect and plan List each enterprise package, every call site, and what is stored (keys, DB names, vault config: type , deviceSecurityType , lockAfterBackgrounded , unlockVaultOnLoad ). Migrate one plugin per release when more than one is present. Report the plan before editing. Step 2: Plan data carry over (two release rule) Old plugin data can only be read while the old plugin is still installed. For tokens, vault values, or encrypted DBs: 1. Release N: install the Capgo replacement alongside the enterprise plugin. On first launch, read from the old store, write to the new one, set a migrated flag, then clear the old store. 2. Release N+1 (after most users have opened release N): remove the enterprise plugin. If the user accepts a forced re login for everyone, a single release is fine; confirm this explicitly. Step 3: Auth Connect Social Login Keep the same client IDs, scopes, and redirect URIs; register any new native redirect (custom scheme or universal link) with the IdP before shipping. Map each Auth Connect provider (Azure, Auth0, Okta, Cognito, generic OIDC) to an oauth2 entry in SocialLogin.initialize({ oauth2: { <providerId : { ... } } }) with clientId / appId , issuerUrl or authorizationBaseUrl + accessTokenEndpoint , redirectUrl , and scopes. Check the plugin's OAuth2 docs for the exact fields of the installed version. Replace AuthConnect.login/logout/refreshSession/isAccessTokenExpired with SocialLogin.login({ provider: 'oauth2', options: { providerId } }) , logout , refreshToken , and your own expiry check on the returned token. Compare the before/after authorization request (scopes, prompt , audience) and token response in a test tenant. Step 4: Identity Vault Native Biometric lockAfterBackgrounded on App resume , if elapsed time exceeds the timeout, show a lock screen and call getSecureCredentials again. DeviceSecurityType.Both / passcode fallback verifyIdentity supports device passcode fallback on iOS; protected credential reads stay biometric only. BIOMETRY CURRENT SET invalidates the item when biometrics change (like Identity Vault's strict mode); BIOMETRY ANY survives enrollment changes. Privacy screen in app switcher @capacitor/privacy screen . iOS: add NSFaceIDUsageDescription to Info.plist . Step 5: Secure Storage Fast SQL or Data Storage SQLite Keep the same schema; port queries ( executeSql db.query / db.run / db.executeBatch / db.transaction ). Encryption requires SQLCipher: Android implementation 'net.zetetic:sqlcipher android:<version ' in android/app/build.gradle ; iOS CocoaPods subspec CapgoCapacitorFastSql/SQLCipher . Without it, encrypted: true fails with Encryption is not available in this build on iOS. Fast SQL runs a localhost HTTP server: add NSAppTransportSecurity NSAllowsLocalNetworking (iOS) and a localhost cleartext network security config.xml (Android). See sqlite to fast sql for the full setup. Store encryptionKey with Native Biometric (Step 4) or derive it server side; never hard code it. Step 6: Clean up Remove the Ionic Enterprise registry/token lines from .npmrc only after no enterprise package remains (CI installs fail otherwise). Verification Upgrade test: install the current store build, log in, store data; install the new build over it; user stays logged in and data is present. Fresh install: login, token refresh, logout, and biometric unlock work on real iOS and Android devices (simulators cannot fully test biometrics). Change device biometrics: BIOMETRY CURRENT SET items become unreadable and the app falls back to login. rg n "@ionic enterprise" g '!node modules' . returns nothing after the final release. npm ci succeeds in CI without Ionic Enterprise registry credentials. Error Handling Problem Fix npm error 401 Unauthorized / 404 for @ionic enterprise/ in CI Enterprise registry token expired; finish removal or keep the token until release N+1 Users logged out after update Data not carried over; ship the dual plugin release N first redirect uri mismatch / IdP error after switching Register the new redirect URL with the IdP; keep scopes identical Encryption is not available in this build Add the SQLCipher dependency/subspec, rebuild Fast SQL calls fail with network errors Missing ATS local networking / Android cleartext config for localhost Biometric read fails after enrollment change Expected with BIOMETRY CURRENT SET ; re authenticate and save again

ionic-enterprise-sdk-migration