feat(backup): introduce new schema to minimize backup length

src/domain/backup/index.ts

@@ -1,10 +1,17 @@
 import { Schema as v0_0_1 } from "./v0_0_1";
+import { Schema as v0_0_2 } from "./v0_0_2";
 
 /**
  * All supported backup schemas
  */
-export type Schema = v0_0_1;
+export type Schema = v0_0_1 | v0_0_2;
+export type Version = "0.0.1" | "0.0.2";
 
 export const defaultVersion = "0.0.1";
 
-export { v0_0_1 };
+export const versions: Version[] = [
+  "0.0.1",
+  "0.0.2",
+];
+
+export { v0_0_1, v0_0_2 };

src/domain/backup/v0_0_2.ts

@@ -0,0 +1,45 @@
+/**
+ * Schema definition for Backup V0.0.2
+ */
+import * as TB from "@sinclair/typebox";
+
+const credential = TB.Object({
+  recovery_id: TB.String(),
+  data: TB.String(),
+});
+
+const did = TB.Object({
+  did: TB.String(),
+  alias: TB.Optional(TB.String()),
+});
+
+const didpair = TB.Object({
+  holder: TB.String(),
+  recipient: TB.String(),
+  alias: TB.String(),
+});
+
+const key = TB.Object({
+  recovery_id: TB.String(),
+  key: TB.String(),
+  did: TB.Optional(TB.String()),
+  index: TB.Optional(TB.Number()),
+});
+
+
+export const Schema = TB.Object({
+  version: TB.Optional(TB.Literal("0.0.2")),
+  credentials: TB.Array(credential),
+  dids: TB.Array(did),
+  did_pairs: TB.Array(didpair),
+  keys: TB.Array(key),
+});
+
+export type Schema = TB.Static<typeof Schema>;
+
+export namespace Schema {
+  export type Credential = TB.Static<typeof credential>;
+  export type DID = TB.Static<typeof did>;
+  export type DIDPair = TB.Static<typeof didpair>;
+  export type Key = TB.Static<typeof key>;
+}

src/domain/buildingBlocks/Pluto.ts

@@ -41,7 +41,7 @@ export interface Pluto {
   /**
    * create a Backup object from the stored data
    */
-  backup(): Promise<Backup.Schema>;
+  backup(version?: Backup.Version): Promise<Backup.Schema>;
 
   /**
    * load the given data into the store

src/edge-agent/Agent.Backup.ts

@@ -1,57 +1,94 @@
+import Pako from "pako";
 import * as Domain from "../domain";
 import Agent from "./Agent";
+import { Version } from "../domain/backup";
 import { isObject, validateSafe } from "../utils";
 
+
 /**
  * define Agent requirements for Backup
  */
 type BackupAgent = Pick<Agent, "apollo" | "pluto" | "pollux" | "seed">;
 
+type MasterKey = Domain.PrivateKey & Domain.ExportableKey.Common & Domain.ExportableKey.JWK & Domain.ExportableKey.PEM
+
+export type BackupOptions = {
+  version?: Version
+  key?: MasterKey
+  compress?: boolean
+}
+
 export class AgentBackup {
   constructor(
     public readonly Agent: BackupAgent
   ) {}
 
   /**
-   * create JWE of data stored in Pluto
+   * Creates a JWE (JSON Web Encryption) containing the backup data stored in Pluto.
+   * The data can optionally be encrypted using a custom master key and can be compressed.
+   * 
+   * @param {BackupOptions} [options] - Optional settings for the backup.
+   * @param {Version} [options.version] - Specifies the version of the backup data.
+   * @param {MasterKey} [options.key] - Custom master key used for encrypting the backup.
+   * @param {boolean} [options.compress] - If true, compresses the JWE using DEFLATE.
+   * 
+   * @returns {Promise<string>} - A promise that resolves to the JWE string.
    * 
-   * @returns {string}
-   * @see restore
+   * @see restore - Method to restore data from a JWE string.
    */
-  async createJWE(): Promise<string> {
+  async createJWE(options?: BackupOptions): Promise<string> {
     await this.Agent.pollux.start();
-    const backup = await this.Agent.pluto.backup();
-    const masterSk = await this.masterSk();
+
+    const backup = await this.Agent.pluto.backup(options?.version);
+    const backupStr = options?.compress ? this.compress(JSON.stringify(backup)) : JSON.stringify(backup);
+    const masterSk = options?.key ?? await this.masterSk();
     const jwk = masterSk.to.JWK();
-    const jwe = this.Agent.pollux.jwe.JWE.encrypt(
-      JSON.stringify(backup),
+
+    return this.Agent.pollux.jwe.JWE.encrypt(
+      backupStr,
       JSON.stringify(jwk),
-      'backup'
+      'backup',
     );
-    return jwe;
   }
 
   /**
-   * decode JWE and save data to store
+   * Decodes a JWE (JSON Web Encryption) string and restores the backup data to the store.
+   * If the JWE is compressed (Base64-encoded), it will attempt to decompress it first.
+   * 
+   * @param {string} jwe - The JWE string containing the encrypted backup data.
+   * @param {MasterKey} [key] - Optional custom master key used for decrypting the JWE. 
+   *                            If not provided, the default master key is used.
+   * 
+   * @returns {Promise<void>} - A promise that resolves when the data is successfully restored.
    * 
-   * @param jwe 
-   * @see backup
+   * @see createJWE - Method to create a JWE from the stored backup data.
    */
-  async restore(jwe: string) {
+  async restore(jwe: string, key?: MasterKey) {
     await this.Agent.pollux.start();
-    const masterSk = await this.masterSk();
+    const masterSk = key ?? await this.masterSk();
+
     const jwk = masterSk.to.JWK();
     const decoded = this.Agent.pollux.jwe.JWE.decrypt(
       jwe,
       'backup',
-      JSON.stringify(jwk)
+      JSON.stringify(jwk),
     );
-    const jsonStr = Buffer.from(decoded).toString();
-    const json = JSON.parse(jsonStr);
-    const backup = this.parseBackupJson(json);
+    let jsonStr: string;
+    try {
+      jsonStr = this.decopress(new TextDecoder().decode(decoded));
+    } catch {
+      jsonStr = Buffer.from(decoded).toString();
+    }    
+    const json = JSON.parse(jsonStr);    
+    const backup = this.parseBackupJson(json);    
     await this.Agent.pluto.restore(backup);
   }
 
+  getStringByteLength(str: string) {
+    const encoder = new TextEncoder();
+    return encoder.encode(str).length;
+  }
+
   private parseBackupJson(json: unknown): Domain.Backup.Schema {
     if (isObject(json)) {
       const version = json.version ?? Domain.Backup.defaultVersion;
@@ -60,12 +97,47 @@ export class AgentBackup {
           if (validateSafe(json, Domain.Backup.v0_0_1)) {
             return json;
           }
+          break;
+        case "0.0.2":
+          if (validateSafe(json, Domain.Backup.v0_0_2)) {
+            return json;
+          }
       }
     }
 
     throw new Domain.AgentError.BackupVersionError();
   }
 
+  /**
+ * Compresses a JSON object into a Base64-encoded string using DEFLATE.
+ * 
+ * - Uses `level: 9` for maximum compression and `strategy: Z_FILTERED` 
+ *   (optimized for repetitive patterns, common in JSON data).
+ * - Converts the JSON to a string, compresses it, and encodes it in Base64.
+ * 
+ * @param {unknown} json - The JSON object to compress.
+ * @returns {string} - The Base64-encoded compressed string.
+ */
+  private compress(json: unknown): string {
+    // Strategy 1 is 
+    return Buffer.from(Pako.deflate(JSON.stringify(json), {level: 9, strategy: 1})).toString('base64');
+  }
+
+  /**
+ * Decompresses a Base64-encoded string into its original JSON representation.
+ * 
+ * - Decodes the Base64 string to a binary buffer.
+ * - Uses DEFLATE to decompress the data and converts it back to a JSON string.
+ * - Parses and returns the JSON object.
+ * 
+ * @param {string} data - The Base64-encoded compressed string.
+ * @returns {string} - The decompressed JSON string.
+ */
+  private decopress(data: string): string {
+    const compressedData = Buffer.from(data, 'base64');
+    return JSON.parse(Pako.inflate(compressedData, {to: 'string'}));
+  }
+
   /**
    * create a JWK for the MasterKey (X25519)
    * @returns JWK

src/pluto/Pluto.ts

@@ -5,6 +5,7 @@ import { PeerDID } from "../peer-did/PeerDID";
 import { BackupManager } from "./backup/BackupManager";
 import { PlutoRepositories, repositoryFactory } from "./repositories";
 import { Arrayable, asArray } from "../utils";
+import { Version } from "../domain/backup";
 
 
 /**
@@ -121,8 +122,8 @@ export class Pluto implements Domain.Pluto {
   }
 
   /** Backups **/
-  backup() {
-    return this.BackupMgr.backup();
+  backup(version?: Version) {
+    return this.BackupMgr.backup(version);
   }
 
   restore(backup: Domain.Backup.Schema) {

src/pluto/backup/BackupManager.ts

@@ -4,6 +4,7 @@ import { Pluto } from "../Pluto";
 import { PlutoRepositories } from "../repositories";
 import { isEmpty } from "../../utils";
 import { IBackupTask, IRestoreTask } from "./versions/interfaces";
+import { Version } from "../../domain/backup";
 
 /**
  * BackupManager
@@ -21,7 +22,7 @@ export class BackupManager {
    * @param version - backup schema version
    * @returns {Promise<Domain.Backup.Schema>}
    */
-  backup(version?: string) {
+  backup(version?: Version) {
     const task = this.getBackupTask(version);
     return task.run();
   }
@@ -37,21 +38,24 @@ export class BackupManager {
     await task.run();
   }
 
-  private getBackupTask(version: string = Domain.Backup.defaultVersion): IBackupTask {
+  private getBackupTask(version: Version = Domain.Backup.defaultVersion): IBackupTask {
     switch (version) {
       case "0.0.1":
         return new Versions.v0_0_1.BackupTask(this.Pluto, this.Repositories);
+      case "0.0.2":
+        return new Versions.v0_0_2.BackupTask(this.Pluto, this.Repositories);
     }
 
     throw new Domain.PlutoError.BackupNotFoundError();
   }
 
   private getRestoreTask(backup: Domain.Backup.Schema): IRestoreTask {
-    const version = backup.version ?? Domain.Backup.defaultVersion;
-
-    switch (version) {
+    backup.version = backup.version ?? Domain.Backup.defaultVersion;
+    switch (backup.version) {
       case "0.0.1":
         return new Versions.v0_0_1.RestoreTask(this.Pluto, backup);
+      case "0.0.2":
+        return new Versions.v0_0_2.RestoreTask(this.Pluto, backup);
     }
 
     throw new Domain.PlutoError.RestoreNotFoundError();

src/pluto/backup/versions/0_0_1/Backup.ts

@@ -68,7 +68,6 @@ export class BackupTask implements IBackupTask {
           index: key.index,
           did: did?.uuid,
         };
-
         return acc.concat(backup);
       }