@absolutejs/sync-capacitor 0.6.0 → 0.7.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
 	}
 });
@@ -86,6 +89,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 +149,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);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;