@absolutejs/sync-capacitor 0.6.1 → 0.8.0

package/README.md

@@ -14,13 +14,16 @@ import { createSyncClient } from '@absolutejs/sync/client';
 import { lifecycle, network } from '@absolutejs/devices';
 import {
 	createCapacitorSyncLocalStore,
+	createCapacitorSyncProtection,
 	installCapacitorSyncLifecycle
 } from '@absolutejs/sync-capacitor';
 
 const client = createSyncClient({
 	url: 'wss://app.example.com/sync/ws',
 	durable: {
-		store: createCapacitorSyncLocalStore(),
+		store: createCapacitorSyncLocalStore({
+			protection: createCapacitorSyncProtection()
+		}),
 		namespace: authenticatedPrincipalNamespace
 	}
 });
@@ -38,6 +41,14 @@ failures obey the client's delivery ceiling; conflicts and permanent failures
 remain in the principal's dead-letter partition for explicit remediation rather
 than replaying forever.
 
+Generated mutation conflict policies are captured inside each encrypted outbox
+record. The TypeScript foreground/headless runner and the Android WorkManager or
+iOS BGProcessingTask runner therefore make the same bounded decision: manual
+conflicts become dead letters, `server-wins` discards the rejected local intent,
+and `client-wins` retries the unchanged operation ID up to its declared ceiling.
+An explicit argument-changing rebase is left to the foreground remediation API
+and creates a new traceable intent.
+
 The namespace must come from a verified Auth principal, never from an untrusted
 route or form value. AbsoluteJS derives an opaque namespace from the verified
 issuer, public client ID, and subject. Signing out locks that partition by
@@ -86,6 +97,22 @@ deterministic component bundle. SQLite tracks each component independently,
 keeps removed-pack ledgers as orphan diagnostics, and migrates all records and
 ledger updates in one transaction.
 
+## Protected local data and quotas
+
+AbsoluteJS automatically installs `createCapacitorSyncProtection()`. It creates
+one random AES-256-GCM data key, seals that key in the existing iOS Keychain or
+Android Keystore vault, and writes only authenticated ciphertext envelopes to
+SQLite. Namespace, record kind, and collection/mutation name are authenticated
+as associated data. The foreground adapter and both finite native workers use
+the same versioned format; a missing key, changed identity, or modified record
+fails closed. Direct Capacitor integrations opt in as shown above.
+
+The generated `localData` policy also enforces memory-only records,
+whole-projection expiry, deterministic eviction priority, and a logical
+per-principal byte ceiling. Pending mutations are never evicted. When protected
+data declares a memory-only fallback, browsers without an audited key provider
+remain usable without writing that data to disk.
+
 ## Managed native background Sync
 
 AbsoluteJS also configures `AbsoluteBackgroundSync` when the application uses
@@ -130,9 +157,10 @@ generated regions. Android scheduling is registered by the plugin.
 
 ## Platform notes
 
-- Native Android and iOS use SQLCipher through
-  `@capacitor-community/sqlite`, including for unencrypted databases. Review the
-  plugin's encryption-export compliance notice before shipping.
+- AbsoluteJS protects record payloads with AES-256-GCM rather than claiming the
+  default SQLite connection is SQLCipher-encrypted. SQLite keys, namespaces,
+  and ordering columns remain metadata; sensitive row and mutation payloads are
+  ciphertext. Review platform encryption-export requirements before shipping.
 - Web/PWA builds should use `createIndexedDbSyncLocalStore` from
   `@absolutejs/sync/client`; they do not need the plugin's WASM/web component.
 - The adapter serializes transactions so an app cannot overlap two explicit

package/android/src/main/java/js/absolute/sync/AbsoluteBackgroundSyncEngine.java

@@ -16,6 +16,12 @@ import java.nio.charset.StandardCharsets;
 import java.util.HashMap;
 import java.util.LinkedHashMap;
 import java.util.Map;
+import java.util.Arrays;
+import java.security.SecureRandom;
+import javax.crypto.Cipher;
+import javax.crypto.spec.GCMParameterSpec;
+import javax.crypto.spec.SecretKeySpec;
+import android.util.Base64;
 import js.absolute.devices.AbsoluteSecureStorageVault;
 import org.json.JSONArray;
 import org.json.JSONObject;
@@ -23,6 +29,7 @@ import org.json.JSONObject;
 final class AbsoluteBackgroundSyncEngine {
     static final class NoSession extends Exception {}
     private static final int MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+    private static final String DATA_KEY="absolutejs.sync.data-key.v1";
     private static final String RUNNING="running", LAST_RUN="lastRunAt", LAST_ERROR="lastError", LAST_ACK="lastAcknowledged", LAST_PULL="lastPulled";
     private static final class Mutation { final String id; final int attempts; Mutation(String i,int a){id=i;attempts=a;} }
     private static final class Batch { final JSONObject request=new JSONObject(); final Map<String,Mutation> mutations=new LinkedHashMap<>(); final Map<String,JSONObject> pulls=new LinkedHashMap<>(); }
@@ -38,7 +45,7 @@ final class AbsoluteBackgroundSyncEngine {
         AbsoluteBackgroundSyncConfig.preferences(context).edit().putBoolean(RUNNING,true).remove(LAST_ERROR).apply();
         try{
             String access=refresh(context,config); SQLiteDatabase db=SQLiteDatabase.openDatabase(context.getDatabasePath(config.databaseName+"SQLite.db").getPath(),null,SQLiteDatabase.OPEN_READWRITE);
-            try{db.execSQL("PRAGMA busy_timeout=5000"); Batch batch=prepare(db,config); JSONObject response=request(config.endpoint,"POST",batch.request.toString().getBytes(StandardCharsets.UTF_8),"application/json","Bearer "+access,config.issuer); int[] counts=settle(db,config,batch,response);
+            try{db.execSQL("PRAGMA busy_timeout=5000"); Batch batch=prepare(context,db,config); JSONObject response=request(config.endpoint,"POST",batch.request.toString().getBytes(StandardCharsets.UTF_8),"application/json","Bearer "+access,config.issuer); int[] counts=settle(context,db,config,batch,response);
                 AbsoluteBackgroundSyncConfig.preferences(context).edit().putBoolean(RUNNING,false).putLong(LAST_RUN,System.currentTimeMillis()).putInt(LAST_ACK,counts[0]).putInt(LAST_PULL,counts[1]).remove(LAST_ERROR).apply();
             }finally{db.close();}
         }catch(NoSession e){AbsoluteBackgroundSyncConfig.preferences(context).edit().putBoolean(RUNNING,false).remove(LAST_ERROR).apply();throw e;}
@@ -56,24 +63,24 @@ final class AbsoluteBackgroundSyncEngine {
     }
     private static String form(String n,String v)throws Exception{return URLEncoder.encode(n,"UTF-8")+"="+URLEncoder.encode(v,"UTF-8");}
 
-    private static Batch prepare(SQLiteDatabase db,AbsoluteBackgroundSyncConfig config)throws Exception{
+    private static Batch prepare(Context context,SQLiteDatabase db,AbsoluteBackgroundSyncConfig config)throws Exception{
         Batch b=new Batch(); JSONArray mutations=new JSONArray(),pulls=new JSONArray(); long now=System.currentTimeMillis(); db.beginTransaction();
         try{
             try(Cursor c=db.rawQuery("SELECT operation_id,record_json FROM absolute_sync_mutations WHERE namespace=? ORDER BY created_at,operation_id",new String[]{config.namespace})){
-                while(c.moveToNext()&&mutations.length()<config.maxMutations){String id=c.getString(0);JSONObject r=new JSONObject(c.getString(1));if("dead-letter".equals(r.optString("state"))||r.optLong("nextAttemptAt",0)>now)continue;int attempts=r.optInt("attempts",0)+1;r.put("attempts",attempts).remove("nextAttemptAt");updateMutation(db,config.namespace,id,r);JSONObject m=new JSONObject().put("operationId",id).put("name",r.getString("name"));if(r.has("args"))m.put("args",r.get("args"));mutations.put(m);b.mutations.put(id,new Mutation(id,attempts));}
+                while(c.moveToNext()&&mutations.length()<config.maxMutations){String id=c.getString(0);JSONObject r=decodeRecord(context,c.getString(1),"mutation",config.namespace);if("dead-letter".equals(r.optString("state"))||r.optLong("nextAttemptAt",0)>now)continue;int attempts=r.optInt("attempts",0)+1;r.put("attempts",attempts).remove("nextAttemptAt");updateMutation(context,db,config.namespace,id,r);JSONObject m=new JSONObject().put("operationId",id).put("name",r.getString("name"));if(r.has("args"))m.put("args",r.get("args"));mutations.put(m);b.mutations.put(id,new Mutation(id,attempts));}
             }
             try(Cursor c=db.rawQuery("SELECT collection_key,record_json FROM absolute_sync_collections WHERE namespace=? ORDER BY collection_key",new String[]{config.namespace})){
-                while(c.moveToNext()&&pulls.length()<config.maxPulls){String key=c.getString(0);JSONObject r=new JSONObject(c.getString(1));String collection=r.optString("collection");if(collection.isEmpty())continue;JSONObject p=new JSONObject().put("id",key).put("collection",collection);if(r.has("params"))p.put("params",r.get("params"));if("id".equals(r.optString("headlessKey"))){if(r.has("cursor"))p.put("since",r.get("cursor"));else if(r.optInt("version",0)>0)p.put("since",r.getInt("version"));}pulls.put(p);b.pulls.put(key,r);}
+                while(c.moveToNext()&&pulls.length()<config.maxPulls){String key=c.getString(0);JSONObject r=decodeRecord(context,c.getString(1),"collection",config.namespace);String collection=r.optString("collection");if(collection.isEmpty())continue;JSONObject p=new JSONObject().put("id",key).put("collection",collection);if(r.has("params"))p.put("params",r.get("params"));if("id".equals(r.optString("headlessKey"))){if(r.has("cursor"))p.put("since",r.get("cursor"));else if(r.optInt("version",0)>0)p.put("since",r.getInt("version"));}pulls.put(p);b.pulls.put(key,r);}
             }
             db.setTransactionSuccessful();
         }finally{db.endTransaction();}
         b.request.put("version",1).put("mutations",mutations).put("pulls",pulls);return b;
     }
-    private static int[] settle(SQLiteDatabase db,AbsoluteBackgroundSyncConfig config,Batch b,JSONObject response)throws Exception{
+    private static int[] settle(Context context,SQLiteDatabase db,AbsoluteBackgroundSyncConfig config,Batch b,JSONObject response)throws Exception{
         if(response.getInt("version")!=1)throw new IllegalStateException("Unsupported Headless Sync response.");Map<String,JSONObject> mutationResults=index(response.getJSONArray("mutations"),"operationId"),pullResults=index(response.getJSONArray("pulls"),"id");int ack=0,pulled=0;db.beginTransaction();
         try{
-            for(Mutation sent:b.mutations.values()){JSONObject current=record(db,"absolute_sync_mutations","operation_id",config.namespace,sent.id);if(current==null||current.optInt("attempts",-1)!=sent.attempts)continue;JSONObject outcome=mutationResults.get(sent.id);if(outcome!=null&&"ack".equals(outcome.optString("status"))){db.delete("absolute_sync_mutations","namespace=? AND operation_id=?",new String[]{config.namespace,sent.id});ack++;continue;}JSONObject rejection=outcome==null?new JSONObject().put("kind","retryable").put("message","Missing mutation response."):outcome.getJSONObject("rejection");current.put("lastError",rejection.optString("message","Mutation rejected.")).put("rejection",rejection);if(!"retryable".equals(rejection.optString("kind"))||sent.attempts>=config.maxAttempts)current.put("state","dead-letter").put("deadLetteredAt",System.currentTimeMillis()).remove("nextAttemptAt");else current.put("state","pending").put("nextAttemptAt",System.currentTimeMillis()+Math.max(0,rejection.optLong("retryAfterMs",Math.min(30000,500L<<Math.min(20,sent.attempts-1)))));updateMutation(db,config.namespace,sent.id,current);}
-            for(Map.Entry<String,JSONObject> requested:b.pulls.entrySet()){JSONObject result=pullResults.get(requested.getKey());if(result==null||"error".equals(result.optString("type")))continue;JSONObject current=record(db,"absolute_sync_collections","collection_key",config.namespace,requested.getKey());if(!same(current,requested.getValue()))continue;ContentValues values=new ContentValues();values.put("record_json",applyPull(current,result).toString());db.update("absolute_sync_collections",values,"namespace=? AND collection_key=?",new String[]{config.namespace,requested.getKey()});pulled++;}
+            for(Mutation sent:b.mutations.values()){JSONObject current=record(context,db,"absolute_sync_mutations","operation_id","mutation",config.namespace,sent.id);if(current==null||current.optInt("attempts",-1)!=sent.attempts)continue;JSONObject outcome=mutationResults.get(sent.id);if(outcome!=null&&"ack".equals(outcome.optString("status"))){db.delete("absolute_sync_mutations","namespace=? AND operation_id=?",new String[]{config.namespace,sent.id});ack++;continue;}JSONObject rejection=outcome==null?new JSONObject().put("kind","retryable").put("message","Missing mutation response."):outcome.getJSONObject("rejection");current.put("lastError",rejection.optString("message","Mutation rejected.")).put("rejection",rejection);JSONObject conflictPolicy=current.optJSONObject("conflictPolicy");String conflictStrategy=conflictPolicy==null?"manual":conflictPolicy.optString("strategy","manual");if("conflict".equals(rejection.optString("kind"))&&"server-wins".equals(conflictStrategy)){db.delete("absolute_sync_mutations","namespace=? AND operation_id=?",new String[]{config.namespace,sent.id});continue;}if("conflict".equals(rejection.optString("kind"))&&"client-wins".equals(conflictStrategy)&&current.optInt("conflictAttempts",0)<conflictPolicy.optInt("maxAttempts",1)){current.put("conflictAttempts",current.optInt("conflictAttempts",0)+1).put("state","pending").remove("nextAttemptAt");updateMutation(context,db,config.namespace,sent.id,current);continue;}if(!"retryable".equals(rejection.optString("kind"))||sent.attempts>=config.maxAttempts)current.put("state","dead-letter").put("deadLetteredAt",System.currentTimeMillis()).remove("nextAttemptAt");else current.put("state","pending").put("nextAttemptAt",System.currentTimeMillis()+Math.max(0,rejection.optLong("retryAfterMs",Math.min(30000,500L<<Math.min(20,sent.attempts-1)))));updateMutation(context,db,config.namespace,sent.id,current);}
+            for(Map.Entry<String,JSONObject> requested:b.pulls.entrySet()){JSONObject result=pullResults.get(requested.getKey());if(result==null||"error".equals(result.optString("type")))continue;JSONObject current=record(context,db,"absolute_sync_collections","collection_key","collection",config.namespace,requested.getKey());if(!same(current,requested.getValue()))continue;ContentValues values=new ContentValues();JSONObject next=applyPull(current,result);values.put("record_json",encodeRecord(context,next,"collection",config.namespace,next.optString("collection",requested.getKey())));db.update("absolute_sync_collections",values,"namespace=? AND collection_key=?",new String[]{config.namespace,requested.getKey()});pulled++;}
             db.setTransactionSuccessful();
         }finally{db.endTransaction();}return new int[]{ack,pulled};
     }
@@ -83,8 +90,12 @@ final class AbsoluteBackgroundSyncEngine {
     private static void remove(Map<String,JSONObject> rows,JSONArray values)throws Exception{for(int i=0;i<values.length();i++)rows.remove(key(values.getJSONObject(i)));}
     private static boolean same(JSONObject a,JSONObject b){return a!=null&&a.optInt("version")==b.optInt("version")&&a.optString("cursor").equals(b.optString("cursor"));}
     private static Map<String,JSONObject> index(JSONArray values,String field)throws Exception{Map<String,JSONObject> result=new HashMap<>();for(int i=0;i<values.length();i++){JSONObject value=values.getJSONObject(i);result.put(value.getString(field),value);}return result;}
-    private static JSONObject record(SQLiteDatabase db,String table,String field,String namespace,String id)throws Exception{try(Cursor c=db.rawQuery("SELECT record_json FROM "+table+" WHERE namespace=? AND "+field+"=? LIMIT 1",new String[]{namespace,id})){return c.moveToFirst()?new JSONObject(c.getString(0)):null;}}
-    private static void updateMutation(SQLiteDatabase db,String namespace,String id,JSONObject record){ContentValues values=new ContentValues();values.put("record_json",record.toString());db.update("absolute_sync_mutations",values,"namespace=? AND operation_id=?",new String[]{namespace,id});}
+    private static JSONObject record(Context context,SQLiteDatabase db,String table,String field,String kind,String namespace,String id)throws Exception{try(Cursor c=db.rawQuery("SELECT record_json FROM "+table+" WHERE namespace=? AND "+field+"=? LIMIT 1",new String[]{namespace,id})){return c.moveToFirst()?decodeRecord(context,c.getString(0),kind,namespace):null;}}
+    private static void updateMutation(Context context,SQLiteDatabase db,String namespace,String id,JSONObject record)throws Exception{ContentValues values=new ContentValues();values.put("record_json",encodeRecord(context,record,"mutation",namespace,record.getString("name")));db.update("absolute_sync_mutations",values,"namespace=? AND operation_id=?",new String[]{namespace,id});}
+    private static byte[] dataKey(Context context)throws Exception{String value=AbsoluteSecureStorageVault.get(context,DATA_KEY);if(value==null)return null;byte[] key=Base64.decode(value,Base64.NO_WRAP);if(key.length!=32)throw new IllegalStateException("Protected Sync data key is invalid.");return key;}
+    private static String aad(String kind,String namespace,String name){return "absolute-sync-v1\u0000"+kind+"\u0000"+namespace+"\u0000"+name;}
+    private static JSONObject decodeRecord(Context context,String stored,String kind,String namespace)throws Exception{JSONObject outer=new JSONObject(stored);if(!outer.has("__absoluteSyncProtected"))return outer;JSONObject envelope=outer.getJSONObject("__absoluteSyncProtected");if(!"aes-256-gcm-v1".equals(envelope.getString("protector")))throw new IllegalStateException("Unsupported Sync data protector.");byte[] key=dataKey(context);if(key==null)throw new IllegalStateException("Protected Sync data key is unavailable.");byte[] packed=Base64.decode(envelope.getString("value"),Base64.NO_WRAP),nonce=Arrays.copyOfRange(packed,0,12),ciphertext=Arrays.copyOfRange(packed,12,packed.length);Cipher cipher=Cipher.getInstance("AES/GCM/NoPadding");cipher.init(Cipher.DECRYPT_MODE,new SecretKeySpec(key,"AES"),new GCMParameterSpec(128,nonce));cipher.updateAAD(aad(kind,namespace,envelope.getString("name")).getBytes(StandardCharsets.UTF_8));return new JSONObject(new String(cipher.doFinal(ciphertext),StandardCharsets.UTF_8));}
+    private static String encodeRecord(Context context,JSONObject record,String kind,String namespace,String name)throws Exception{byte[] key=dataKey(context);if(key==null)return record.toString();byte[] nonce=new byte[12];new SecureRandom().nextBytes(nonce);Cipher cipher=Cipher.getInstance("AES/GCM/NoPadding");cipher.init(Cipher.ENCRYPT_MODE,new SecretKeySpec(key,"AES"),new GCMParameterSpec(128,nonce));cipher.updateAAD(aad(kind,namespace,name).getBytes(StandardCharsets.UTF_8));byte[] ciphertext=cipher.doFinal(record.toString().getBytes(StandardCharsets.UTF_8)),packed=new byte[nonce.length+ciphertext.length];System.arraycopy(nonce,0,packed,0,nonce.length);System.arraycopy(ciphertext,0,packed,nonce.length,ciphertext.length);return new JSONObject().put("__absoluteSyncProtected",new JSONObject().put("name",name).put("protector","aes-256-gcm-v1").put("value",Base64.encodeToString(packed,Base64.NO_WRAP))).toString();}
 
     private static JSONObject request(String address,String method,byte[] body,String type,String auth,String trustedOrigin)throws Exception{return request(address,method,body,type,auth,trustedOrigin,false);}
     private static JSONObject request(String address,String method,byte[] body,String type,String auth,String trustedOrigin,boolean advertisedTokenEndpoint)throws Exception{

package/dist/index.d.ts

@@ -1,7 +1,13 @@
 import { type SQLiteDBConnection } from '@capacitor-community/sqlite';
-import type { SyncLocalStore, SyncLocalStoreSchemaInput } from '@absolutejs/sync/client';
+import type { SyncLocalStore, SyncLocalStoreSchemaInput, SyncLocalProtectionProvider } from '@absolutejs/sync/client';
 import type { DeviceLifecycleCapability, DeviceNetworkCapability, DeviceSubscription } from '@absolutejs/devices';
 import type { SyncClient } from '@absolutejs/sync/client';
+import type { DeviceSecureStorageCapability } from '@absolutejs/devices';
+export type CapacitorSyncProtectionOptions = {
+    secureStorage?: DeviceSecureStorageCapability;
+};
+/** AES-256-GCM record protection whose key is sealed by Keychain/Keystore. */
+export declare const createCapacitorSyncProtection: (options?: CapacitorSyncProtectionOptions) => SyncLocalProtectionProvider;
 export type CapacitorBackgroundSyncConfig = {
     endpoint: string;
     issuer: string;
@@ -39,13 +45,15 @@ export type CapacitorSyncLocalStoreOptions = {
     connection?: CapacitorSyncSqliteFactory;
     /** Same generated logical migration plan used by web IndexedDB. */
     storageSchema?: SyncLocalStoreSchemaInput;
+    protection?: SyncLocalProtectionProvider;
+    now?: () => number;
 };
 /**
  * Native SQLite implementation of Sync's principal-partitioned atomic cache
  * and mutation outbox. All calls are serialized because a Capacitor database
  * connection owns one explicit transaction at a time.
  */
-export declare const createCapacitorSyncLocalStore: ({ databaseName, connection: createConnection, storageSchema }?: CapacitorSyncLocalStoreOptions) => SyncLocalStore;
+export declare const createCapacitorSyncLocalStore: ({ databaseName, connection: createConnection, storageSchema, protection, now }?: CapacitorSyncLocalStoreOptions) => SyncLocalStore;
 export type CapacitorSyncLifecycleOptions = {
     client: Pick<SyncClient, 'reconnect'> & Partial<Pick<SyncClient, 'flush'>>;
     lifecycle: DeviceLifecycleCapability;