@alteriom/mqtt-schema 0.6.0 → 0.7.0

package/README.md

@@ -33,6 +33,7 @@ Firmware emits structured MQTT payloads that must remain tightly aligned with we
 - Helpful error paths (JSON Pointer style)
 - Lightweight (Ajv peer dependency, schemas embedded)
 - Ships original schema JSON files (optional consumption)
+- **NEW in v0.7.0**: Best-in-class OTA management with security, rollback, and delta updates
 - **NEW in v0.6.0**: Enhanced location/geolocation support for asset tracking
 - **NEW in v0.6.0**: Extended sensor metadata (accuracy, calibration, operational range)
 - **NEW in v0.6.0**: Comprehensive gateway health metrics (storage, network, errors)
@@ -292,9 +293,13 @@ if (result.valid && isGatewayMetricsMessage(metrics)) {
 - Restart tracking with reason codes
 - All metrics are optional for gradual firmware adoption
 
-## OTA Firmware Manifest Schema (v0.3.1+)
+## OTA Firmware Management (v0.7.0+)
 
-The package includes OTA firmware manifest schema with both rich and minimal formats.
+Comprehensive best-in-class OTA solution based on 2024 industry standards.
+
+### OTA Manifest Schema
+
+The package includes OTA firmware manifest schema with both rich and minimal formats, enhanced with enterprise-grade features.
 
 **Preferred: Stable alias import** (v0.3.1+):
 ```ts
@@ -329,6 +334,104 @@ Supported formats:
 - **Minimal environment map**: environment → channels mapping  
 - **Chunk variants**: structured objects or SHA256 array
 
+### Enhanced OTA Features (v0.7.0+)
+
+**Security & Authenticity:**
+```ts
+const manifest = {
+  environment: "universal-sensor",
+  branch: "main",
+  manifests: {
+    prod: {
+      build_type: "prod",
+      file: "firmware-v2.0.0.bin",
+      size: 456789,
+      sha256: "a1b2c3...",
+      firmware_version: "2.0.0",
+      built: "2025-10-19T12:00:00Z",
+      ota_url: "https://firmware.example.com/v2.0.0.bin",
+      
+      // Digital signature for authenticity
+      signature: "MEUCIQDx...",
+      signature_algorithm: "ECDSA-SHA256",
+      signing_key_id: "prod-signing-key-2025",
+      
+      // Version constraints
+      min_version: "1.5.0",        // Minimum version to upgrade from
+      max_version: "1.9.99",       // Prevent downgrades
+      
+      // Release management
+      release_notes_url: "https://docs.example.com/v2.0.0",
+      criticality: "high",          // low | medium | high | critical
+      mandatory: true,              // Must be installed
+      
+      // Staged rollout
+      rollout_percentage: 25,       // Start with 25% of fleet
+      rollout_target_groups: ["beta-testers", "early-adopters"],
+      
+      // Delta updates (60-90% bandwidth reduction)
+      delta_from_version: "1.9.0",
+      delta_patch_url: "https://firmware.example.com/patches/1.9.0-to-2.0.0.patch",
+      delta_patch_size: 45678,
+      delta_patch_sha256: "c3d4e5..."
+    }
+  }
+};
+```
+
+**Firmware Update Status Tracking:**
+```ts
+import { validators, isFirmwareStatusMessage } from '@alteriom/mqtt-schema';
+
+// Enhanced status tracking
+const status = {
+  schema_version: 1,
+  device_id: "SN789",
+  device_type: "sensor",
+  timestamp: new Date().toISOString(),
+  firmware_version: "2.0.0",
+  
+  status: "downloading",           // New: rolled_back, rollback_pending, rollback_failed
+  progress_pct: 42,
+  
+  // Progress details
+  download_speed_kbps: 125.5,
+  bytes_downloaded: 196608,
+  bytes_total: 456789,
+  eta_seconds: 28,
+  
+  // Rollback support
+  rollback_available: true,
+  previous_version: "1.9.0",
+  
+  // Security verification
+  update_type: "delta",            // full | delta | patch
+  signature_verified: true,
+  checksum_verified: true,
+  
+  // Operational context
+  battery_level_pct: 85,
+  free_space_kb: 2048,
+  retry_count: 0
+};
+
+const result = validators.firmwareStatus(status);
+if (result.valid) {
+  console.log(`Download progress: ${status.progress_pct}% at ${status.download_speed_kbps} kbps`);
+  console.log(`ETA: ${status.eta_seconds} seconds`);
+}
+```
+
+**OTA Best Practices:**
+- **Security**: Always use digital signatures for production firmware
+- **Rollback**: Maintain backup partition for automatic rollback on failures
+- **Delta Updates**: Use delta patches for bandwidth-constrained deployments (60-90% reduction)
+- **Staged Rollout**: Start with 5-10% rollout, monitor, then expand gradually
+- **Version Control**: Use min_version to prevent upgrades from incompatible versions
+- **Criticality**: Mark security patches as "critical" with mandatory: true
+
+See `docs/OTA_MANIFEST.md` for comprehensive guide and best practices.
+
 ## API Surface
 
 ```ts

package/dist/cjs/schema_data.d.ts

@@ -408,7 +408,7 @@ export declare const firmware_status_schema: {
         };
         readonly status: {
             readonly type: "string";
-            readonly enum: readonly ["pending", "downloading", "flashing", "verifying", "rebooting", "completed", "failed"];
+            readonly enum: readonly ["pending", "downloading", "flashing", "verifying", "rebooting", "completed", "failed", "rolled_back", "rollback_pending", "rollback_failed"];
         };
         readonly progress_pct: {
             readonly type: "number";
@@ -418,6 +418,77 @@ export declare const firmware_status_schema: {
         readonly error: {
             readonly type: readonly ["string", "null"];
         };
+        readonly error_code: {
+            readonly type: "string";
+            readonly description: "Machine-readable error code for diagnostics";
+        };
+        readonly retry_count: {
+            readonly type: "integer";
+            readonly minimum: 0;
+            readonly description: "Number of retry attempts for this update";
+        };
+        readonly download_speed_kbps: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly description: "Current download speed in kilobits per second";
+        };
+        readonly bytes_downloaded: {
+            readonly type: "integer";
+            readonly minimum: 0;
+            readonly description: "Number of bytes downloaded so far";
+        };
+        readonly bytes_total: {
+            readonly type: "integer";
+            readonly minimum: 0;
+            readonly description: "Total bytes to download";
+        };
+        readonly eta_seconds: {
+            readonly type: "integer";
+            readonly minimum: 0;
+            readonly description: "Estimated time remaining in seconds";
+        };
+        readonly update_started_at: {
+            readonly type: "string";
+            readonly format: "date-time";
+            readonly description: "ISO8601 timestamp when update began";
+        };
+        readonly update_completed_at: {
+            readonly type: "string";
+            readonly format: "date-time";
+            readonly description: "ISO8601 timestamp when update completed or failed";
+        };
+        readonly rollback_available: {
+            readonly type: "boolean";
+            readonly description: "Whether rollback to previous version is available";
+        };
+        readonly previous_version: {
+            readonly type: "string";
+            readonly description: "Version to rollback to if update fails";
+        };
+        readonly update_type: {
+            readonly type: "string";
+            readonly enum: readonly ["full", "delta", "patch"];
+            readonly description: "Type of update being applied";
+        };
+        readonly signature_verified: {
+            readonly type: "boolean";
+            readonly description: "Whether firmware signature was successfully verified";
+        };
+        readonly checksum_verified: {
+            readonly type: "boolean";
+            readonly description: "Whether firmware checksum was successfully verified";
+        };
+        readonly free_space_kb: {
+            readonly type: "integer";
+            readonly minimum: 0;
+            readonly description: "Available storage space in kilobytes before update";
+        };
+        readonly battery_level_pct: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 100;
+            readonly description: "Battery level during update (critical for battery-powered devices)";
+        };
     };
     readonly additionalProperties: true;
 };
@@ -862,6 +933,82 @@ export declare const ota_ota_manifest_schema: {
                         readonly description: "Array of SHA256 strings for chunks";
                     }];
                 };
+                readonly signature: {
+                    readonly type: "string";
+                    readonly description: "Digital signature of the firmware for authenticity verification (base64 encoded)";
+                };
+                readonly signature_algorithm: {
+                    readonly type: "string";
+                    readonly enum: readonly ["RSA-SHA256", "ECDSA-SHA256", "Ed25519"];
+                    readonly description: "Algorithm used for digital signature";
+                };
+                readonly signing_key_id: {
+                    readonly type: "string";
+                    readonly description: "Identifier of the signing key for key rotation support";
+                };
+                readonly release_notes_url: {
+                    readonly type: "string";
+                    readonly format: "uri";
+                    readonly description: "URL to release notes or changelog for this version";
+                };
+                readonly min_version: {
+                    readonly type: "string";
+                    readonly description: "Minimum firmware version required to upgrade to this version";
+                };
+                readonly max_version: {
+                    readonly type: "string";
+                    readonly description: "Maximum firmware version that can upgrade to this version (for preventing downgrades)";
+                };
+                readonly criticality: {
+                    readonly type: "string";
+                    readonly enum: readonly ["low", "medium", "high", "critical"];
+                    readonly description: "Update criticality level for prioritization";
+                };
+                readonly mandatory: {
+                    readonly type: "boolean";
+                    readonly description: "Whether this update must be installed (cannot be skipped)";
+                };
+                readonly rollout_percentage: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                    readonly maximum: 100;
+                    readonly description: "Percentage of fleet to receive this update (staged rollout)";
+                };
+                readonly rollout_target_groups: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Specific device groups targeted for this update (A/B testing)";
+                };
+                readonly delta_from_version: {
+                    readonly type: "string";
+                    readonly description: "Source version for delta/patch update";
+                };
+                readonly delta_patch_url: {
+                    readonly type: "string";
+                    readonly format: "uri";
+                    readonly description: "URL to download delta patch instead of full firmware";
+                };
+                readonly delta_patch_size: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly description: "Size of delta patch in bytes";
+                };
+                readonly delta_patch_sha256: {
+                    readonly type: "string";
+                    readonly pattern: "^[a-f0-9]{64}$";
+                    readonly description: "SHA256 hash of the delta patch file";
+                };
+                readonly deprecated: {
+                    readonly type: "boolean";
+                    readonly description: "Mark this version as deprecated (not recommended for new installs)";
+                };
+                readonly expiry_date: {
+                    readonly type: "string";
+                    readonly format: "date-time";
+                    readonly description: "ISO8601 timestamp when this firmware version expires and should no longer be installed";
+                };
             };
             readonly required: readonly ["build_type", "file", "size", "sha256", "firmware_version", "built", "ota_url"];
             readonly additionalProperties: true;
@@ -923,6 +1070,28 @@ export declare const ota_ota_manifest_schema: {
                     readonly format: "date-time";
                     readonly description: "ISO8601 timestamp";
                 };
+                readonly signature: {
+                    readonly type: "string";
+                    readonly description: "Digital signature of the firmware (base64 encoded)";
+                };
+                readonly signature_algorithm: {
+                    readonly type: "string";
+                    readonly enum: readonly ["RSA-SHA256", "ECDSA-SHA256", "Ed25519"];
+                    readonly description: "Algorithm used for digital signature";
+                };
+                readonly min_version: {
+                    readonly type: "string";
+                    readonly description: "Minimum firmware version required to upgrade";
+                };
+                readonly criticality: {
+                    readonly type: "string";
+                    readonly enum: readonly ["low", "medium", "high", "critical"];
+                    readonly description: "Update criticality level";
+                };
+                readonly mandatory: {
+                    readonly type: "boolean";
+                    readonly description: "Whether this update must be installed";
+                };
             };
             readonly required: readonly ["file", "size", "sha256", "version", "timestamp"];
             readonly additionalProperties: true;

package/dist/cjs/schema_data.js

@@ -487,7 +487,10 @@ exports.firmware_status_schema = {
                 "verifying",
                 "rebooting",
                 "completed",
-                "failed"
+                "failed",
+                "rolled_back",
+                "rollback_pending",
+                "rollback_failed"
             ]
         },
         "progress_pct": {
@@ -500,6 +503,81 @@ exports.firmware_status_schema = {
                 "string",
                 "null"
             ]
+        },
+        "error_code": {
+            "type": "string",
+            "description": "Machine-readable error code for diagnostics"
+        },
+        "retry_count": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Number of retry attempts for this update"
+        },
+        "download_speed_kbps": {
+            "type": "number",
+            "minimum": 0,
+            "description": "Current download speed in kilobits per second"
+        },
+        "bytes_downloaded": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Number of bytes downloaded so far"
+        },
+        "bytes_total": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Total bytes to download"
+        },
+        "eta_seconds": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Estimated time remaining in seconds"
+        },
+        "update_started_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO8601 timestamp when update began"
+        },
+        "update_completed_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO8601 timestamp when update completed or failed"
+        },
+        "rollback_available": {
+            "type": "boolean",
+            "description": "Whether rollback to previous version is available"
+        },
+        "previous_version": {
+            "type": "string",
+            "description": "Version to rollback to if update fails"
+        },
+        "update_type": {
+            "type": "string",
+            "enum": [
+                "full",
+                "delta",
+                "patch"
+            ],
+            "description": "Type of update being applied"
+        },
+        "signature_verified": {
+            "type": "boolean",
+            "description": "Whether firmware signature was successfully verified"
+        },
+        "checksum_verified": {
+            "type": "boolean",
+            "description": "Whether firmware checksum was successfully verified"
+        },
+        "free_space_kb": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Available storage space in kilobytes before update"
+        },
+        "battery_level_pct": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 100,
+            "description": "Battery level during update (critical for battery-powered devices)"
         }
     },
     "additionalProperties": true
@@ -1046,6 +1124,91 @@ exports.ota_ota_manifest_schema = {
                             "description": "Array of SHA256 strings for chunks"
                         }
                     ]
+                },
+                "signature": {
+                    "type": "string",
+                    "description": "Digital signature of the firmware for authenticity verification (base64 encoded)"
+                },
+                "signature_algorithm": {
+                    "type": "string",
+                    "enum": [
+                        "RSA-SHA256",
+                        "ECDSA-SHA256",
+                        "Ed25519"
+                    ],
+                    "description": "Algorithm used for digital signature"
+                },
+                "signing_key_id": {
+                    "type": "string",
+                    "description": "Identifier of the signing key for key rotation support"
+                },
+                "release_notes_url": {
+                    "type": "string",
+                    "format": "uri",
+                    "description": "URL to release notes or changelog for this version"
+                },
+                "min_version": {
+                    "type": "string",
+                    "description": "Minimum firmware version required to upgrade to this version"
+                },
+                "max_version": {
+                    "type": "string",
+                    "description": "Maximum firmware version that can upgrade to this version (for preventing downgrades)"
+                },
+                "criticality": {
+                    "type": "string",
+                    "enum": [
+                        "low",
+                        "medium",
+                        "high",
+                        "critical"
+                    ],
+                    "description": "Update criticality level for prioritization"
+                },
+                "mandatory": {
+                    "type": "boolean",
+                    "description": "Whether this update must be installed (cannot be skipped)"
+                },
+                "rollout_percentage": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 100,
+                    "description": "Percentage of fleet to receive this update (staged rollout)"
+                },
+                "rollout_target_groups": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Specific device groups targeted for this update (A/B testing)"
+                },
+                "delta_from_version": {
+                    "type": "string",
+                    "description": "Source version for delta/patch update"
+                },
+                "delta_patch_url": {
+                    "type": "string",
+                    "format": "uri",
+                    "description": "URL to download delta patch instead of full firmware"
+                },
+                "delta_patch_size": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "description": "Size of delta patch in bytes"
+                },
+                "delta_patch_sha256": {
+                    "type": "string",
+                    "pattern": "^[a-f0-9]{64}$",
+                    "description": "SHA256 hash of the delta patch file"
+                },
+                "deprecated": {
+                    "type": "boolean",
+                    "description": "Mark this version as deprecated (not recommended for new installs)"
+                },
+                "expiry_date": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "ISO8601 timestamp when this firmware version expires and should no longer be installed"
                 }
             },
             "required": [
@@ -1120,6 +1283,37 @@ exports.ota_ota_manifest_schema = {
                     "type": "string",
                     "format": "date-time",
                     "description": "ISO8601 timestamp"
+                },
+                "signature": {
+                    "type": "string",
+                    "description": "Digital signature of the firmware (base64 encoded)"
+                },
+                "signature_algorithm": {
+                    "type": "string",
+                    "enum": [
+                        "RSA-SHA256",
+                        "ECDSA-SHA256",
+                        "Ed25519"
+                    ],
+                    "description": "Algorithm used for digital signature"
+                },
+                "min_version": {
+                    "type": "string",
+                    "description": "Minimum firmware version required to upgrade"
+                },
+                "criticality": {
+                    "type": "string",
+                    "enum": [
+                        "low",
+                        "medium",
+                        "high",
+                        "critical"
+                    ],
+                    "description": "Update criticality level"
+                },
+                "mandatory": {
+                    "type": "boolean",
+                    "description": "Whether this update must be installed"
                 }
             },
             "required": [

package/dist/cjs/schemas/firmware_status.schema.json

@@ -9,9 +9,24 @@
     "event": {"type": "string"},
     "from_version": {"type": "string"},
     "to_version": {"type": "string"},
-    "status": {"type": "string", "enum": ["pending", "downloading", "flashing", "verifying", "rebooting", "completed", "failed"]},
+    "status": {"type": "string", "enum": ["pending", "downloading", "flashing", "verifying", "rebooting", "completed", "failed", "rolled_back", "rollback_pending", "rollback_failed"]},
     "progress_pct": {"type": "number", "minimum": 0, "maximum": 100},
-    "error": {"type": ["string", "null"]}
+    "error": {"type": ["string", "null"]},
+    "error_code": {"type": "string", "description": "Machine-readable error code for diagnostics"},
+    "retry_count": {"type": "integer", "minimum": 0, "description": "Number of retry attempts for this update"},
+    "download_speed_kbps": {"type": "number", "minimum": 0, "description": "Current download speed in kilobits per second"},
+    "bytes_downloaded": {"type": "integer", "minimum": 0, "description": "Number of bytes downloaded so far"},
+    "bytes_total": {"type": "integer", "minimum": 0, "description": "Total bytes to download"},
+    "eta_seconds": {"type": "integer", "minimum": 0, "description": "Estimated time remaining in seconds"},
+    "update_started_at": {"type": "string", "format": "date-time", "description": "ISO8601 timestamp when update began"},
+    "update_completed_at": {"type": "string", "format": "date-time", "description": "ISO8601 timestamp when update completed or failed"},
+    "rollback_available": {"type": "boolean", "description": "Whether rollback to previous version is available"},
+    "previous_version": {"type": "string", "description": "Version to rollback to if update fails"},
+    "update_type": {"type": "string", "enum": ["full", "delta", "patch"], "description": "Type of update being applied"},
+    "signature_verified": {"type": "boolean", "description": "Whether firmware signature was successfully verified"},
+    "checksum_verified": {"type": "boolean", "description": "Whether firmware checksum was successfully verified"},
+    "free_space_kb": {"type": "integer", "minimum": 0, "description": "Available storage space in kilobytes before update"},
+    "battery_level_pct": {"type": "number", "minimum": 0, "maximum": 100, "description": "Battery level during update (critical for battery-powered devices)"}
   },
   "additionalProperties": true
 }

package/dist/cjs/schemas/ota/ota-manifest.schema.json

@@ -117,6 +117,82 @@
               "description": "Array of SHA256 strings for chunks"
             }
           ]
+        },
+        "signature": {
+          "type": "string",
+          "description": "Digital signature of the firmware for authenticity verification (base64 encoded)"
+        },
+        "signature_algorithm": {
+          "type": "string",
+          "enum": ["RSA-SHA256", "ECDSA-SHA256", "Ed25519"],
+          "description": "Algorithm used for digital signature"
+        },
+        "signing_key_id": {
+          "type": "string",
+          "description": "Identifier of the signing key for key rotation support"
+        },
+        "release_notes_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to release notes or changelog for this version"
+        },
+        "min_version": {
+          "type": "string",
+          "description": "Minimum firmware version required to upgrade to this version"
+        },
+        "max_version": {
+          "type": "string",
+          "description": "Maximum firmware version that can upgrade to this version (for preventing downgrades)"
+        },
+        "criticality": {
+          "type": "string",
+          "enum": ["low", "medium", "high", "critical"],
+          "description": "Update criticality level for prioritization"
+        },
+        "mandatory": {
+          "type": "boolean",
+          "description": "Whether this update must be installed (cannot be skipped)"
+        },
+        "rollout_percentage": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 100,
+          "description": "Percentage of fleet to receive this update (staged rollout)"
+        },
+        "rollout_target_groups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Specific device groups targeted for this update (A/B testing)"
+        },
+        "delta_from_version": {
+          "type": "string",
+          "description": "Source version for delta/patch update"
+        },
+        "delta_patch_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to download delta patch instead of full firmware"
+        },
+        "delta_patch_size": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Size of delta patch in bytes"
+        },
+        "delta_patch_sha256": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$",
+          "description": "SHA256 hash of the delta patch file"
+        },
+        "deprecated": {
+          "type": "boolean",
+          "description": "Mark this version as deprecated (not recommended for new installs)"
+        },
+        "expiry_date": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO8601 timestamp when this firmware version expires and should no longer be installed"
         }
       },
       "required": ["build_type", "file", "size", "sha256", "firmware_version", "built", "ota_url"],
@@ -178,6 +254,28 @@
           "type": "string",
           "format": "date-time",
           "description": "ISO8601 timestamp"
+        },
+        "signature": {
+          "type": "string",
+          "description": "Digital signature of the firmware (base64 encoded)"
+        },
+        "signature_algorithm": {
+          "type": "string",
+          "enum": ["RSA-SHA256", "ECDSA-SHA256", "Ed25519"],
+          "description": "Algorithm used for digital signature"
+        },
+        "min_version": {
+          "type": "string",
+          "description": "Minimum firmware version required to upgrade"
+        },
+        "criticality": {
+          "type": "string",
+          "enum": ["low", "medium", "high", "critical"],
+          "description": "Update criticality level"
+        },
+        "mandatory": {
+          "type": "boolean",
+          "description": "Whether this update must be installed"
         }
       },
       "required": ["file", "size", "sha256", "version", "timestamp"],

package/dist/cjs/schemas/validation_rules.md

@@ -48,8 +48,17 @@ This file captures dynamic / contextual validation that is OUTSIDE pure structur
 - All count metrics must be >= 0.
 
 ## Firmware Update Status
-- `status` must be one of: pending, downloading, flashing, verifying, rebooting, completed, failed.
+- `status` must be one of: pending, downloading, flashing, verifying, rebooting, completed, failed, rolled_back, rollback_pending, rollback_failed.
 - `progress_pct` (if present) must be 0–100.
+- **NEW (OTA Enhancement)**: 
+  - `retry_count` must be >= 0 (tracks update retry attempts).
+  - `download_speed_kbps`, `bytes_downloaded`, `bytes_total`, `eta_seconds` must be >= 0.
+  - `battery_level_pct` must be 0-100 (critical for battery-powered devices).
+  - `error_code` provides machine-readable error classification (e.g., VERIFY_CHECKSUM_MISMATCH).
+  - `update_type` must be one of: full, delta, patch.
+  - `signature_verified` and `checksum_verified` booleans indicate security verification status.
+  - `rollback_available` indicates whether automatic rollback is supported.
+  - `previous_version` stores the version to rollback to if update fails.
 
 ## Extensibility
 - Unknown top-level keys tolerated (future evolution) except if they collide with any deprecated alias or reserved future keys announced in CHANGELOG.

package/dist/esm/schema_data.js

@@ -484,7 +484,10 @@ export const firmware_status_schema = {
                 "verifying",
                 "rebooting",
                 "completed",
-                "failed"
+                "failed",
+                "rolled_back",
+                "rollback_pending",
+                "rollback_failed"
             ]
         },
         "progress_pct": {
@@ -497,6 +500,81 @@ export const firmware_status_schema = {
                 "string",
                 "null"
             ]
+        },
+        "error_code": {
+            "type": "string",
+            "description": "Machine-readable error code for diagnostics"
+        },
+        "retry_count": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Number of retry attempts for this update"
+        },
+        "download_speed_kbps": {
+            "type": "number",
+            "minimum": 0,
+            "description": "Current download speed in kilobits per second"
+        },
+        "bytes_downloaded": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Number of bytes downloaded so far"
+        },
+        "bytes_total": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Total bytes to download"
+        },
+        "eta_seconds": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Estimated time remaining in seconds"
+        },
+        "update_started_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO8601 timestamp when update began"
+        },
+        "update_completed_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO8601 timestamp when update completed or failed"
+        },
+        "rollback_available": {
+            "type": "boolean",
+            "description": "Whether rollback to previous version is available"
+        },
+        "previous_version": {
+            "type": "string",
+            "description": "Version to rollback to if update fails"
+        },
+        "update_type": {
+            "type": "string",
+            "enum": [
+                "full",
+                "delta",
+                "patch"
+            ],
+            "description": "Type of update being applied"
+        },
+        "signature_verified": {
+            "type": "boolean",
+            "description": "Whether firmware signature was successfully verified"
+        },
+        "checksum_verified": {
+            "type": "boolean",
+            "description": "Whether firmware checksum was successfully verified"
+        },
+        "free_space_kb": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Available storage space in kilobytes before update"
+        },
+        "battery_level_pct": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 100,
+            "description": "Battery level during update (critical for battery-powered devices)"
         }
     },
     "additionalProperties": true
@@ -1043,6 +1121,91 @@ export const ota_ota_manifest_schema = {
                             "description": "Array of SHA256 strings for chunks"
                         }
                     ]
+                },
+                "signature": {
+                    "type": "string",
+                    "description": "Digital signature of the firmware for authenticity verification (base64 encoded)"
+                },
+                "signature_algorithm": {
+                    "type": "string",
+                    "enum": [
+                        "RSA-SHA256",
+                        "ECDSA-SHA256",
+                        "Ed25519"
+                    ],
+                    "description": "Algorithm used for digital signature"
+                },
+                "signing_key_id": {
+                    "type": "string",
+                    "description": "Identifier of the signing key for key rotation support"
+                },
+                "release_notes_url": {
+                    "type": "string",
+                    "format": "uri",
+                    "description": "URL to release notes or changelog for this version"
+                },
+                "min_version": {
+                    "type": "string",
+                    "description": "Minimum firmware version required to upgrade to this version"
+                },
+                "max_version": {
+                    "type": "string",
+                    "description": "Maximum firmware version that can upgrade to this version (for preventing downgrades)"
+                },
+                "criticality": {
+                    "type": "string",
+                    "enum": [
+                        "low",
+                        "medium",
+                        "high",
+                        "critical"
+                    ],
+                    "description": "Update criticality level for prioritization"
+                },
+                "mandatory": {
+                    "type": "boolean",
+                    "description": "Whether this update must be installed (cannot be skipped)"
+                },
+                "rollout_percentage": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 100,
+                    "description": "Percentage of fleet to receive this update (staged rollout)"
+                },
+                "rollout_target_groups": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Specific device groups targeted for this update (A/B testing)"
+                },
+                "delta_from_version": {
+                    "type": "string",
+                    "description": "Source version for delta/patch update"
+                },
+                "delta_patch_url": {
+                    "type": "string",
+                    "format": "uri",
+                    "description": "URL to download delta patch instead of full firmware"
+                },
+                "delta_patch_size": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "description": "Size of delta patch in bytes"
+                },
+                "delta_patch_sha256": {
+                    "type": "string",
+                    "pattern": "^[a-f0-9]{64}$",
+                    "description": "SHA256 hash of the delta patch file"
+                },
+                "deprecated": {
+                    "type": "boolean",
+                    "description": "Mark this version as deprecated (not recommended for new installs)"
+                },
+                "expiry_date": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "ISO8601 timestamp when this firmware version expires and should no longer be installed"
                 }
             },
             "required": [
@@ -1117,6 +1280,37 @@ export const ota_ota_manifest_schema = {
                     "type": "string",
                     "format": "date-time",
                     "description": "ISO8601 timestamp"
+                },
+                "signature": {
+                    "type": "string",
+                    "description": "Digital signature of the firmware (base64 encoded)"
+                },
+                "signature_algorithm": {
+                    "type": "string",
+                    "enum": [
+                        "RSA-SHA256",
+                        "ECDSA-SHA256",
+                        "Ed25519"
+                    ],
+                    "description": "Algorithm used for digital signature"
+                },
+                "min_version": {
+                    "type": "string",
+                    "description": "Minimum firmware version required to upgrade"
+                },
+                "criticality": {
+                    "type": "string",
+                    "enum": [
+                        "low",
+                        "medium",
+                        "high",
+                        "critical"
+                    ],
+                    "description": "Update criticality level"
+                },
+                "mandatory": {
+                    "type": "boolean",
+                    "description": "Whether this update must be installed"
                 }
             },
             "required": [

package/dist/esm/schemas/firmware_status.schema.json

@@ -9,9 +9,24 @@
     "event": {"type": "string"},
     "from_version": {"type": "string"},
     "to_version": {"type": "string"},
-    "status": {"type": "string", "enum": ["pending", "downloading", "flashing", "verifying", "rebooting", "completed", "failed"]},
+    "status": {"type": "string", "enum": ["pending", "downloading", "flashing", "verifying", "rebooting", "completed", "failed", "rolled_back", "rollback_pending", "rollback_failed"]},
     "progress_pct": {"type": "number", "minimum": 0, "maximum": 100},
-    "error": {"type": ["string", "null"]}
+    "error": {"type": ["string", "null"]},
+    "error_code": {"type": "string", "description": "Machine-readable error code for diagnostics"},
+    "retry_count": {"type": "integer", "minimum": 0, "description": "Number of retry attempts for this update"},
+    "download_speed_kbps": {"type": "number", "minimum": 0, "description": "Current download speed in kilobits per second"},
+    "bytes_downloaded": {"type": "integer", "minimum": 0, "description": "Number of bytes downloaded so far"},
+    "bytes_total": {"type": "integer", "minimum": 0, "description": "Total bytes to download"},
+    "eta_seconds": {"type": "integer", "minimum": 0, "description": "Estimated time remaining in seconds"},
+    "update_started_at": {"type": "string", "format": "date-time", "description": "ISO8601 timestamp when update began"},
+    "update_completed_at": {"type": "string", "format": "date-time", "description": "ISO8601 timestamp when update completed or failed"},
+    "rollback_available": {"type": "boolean", "description": "Whether rollback to previous version is available"},
+    "previous_version": {"type": "string", "description": "Version to rollback to if update fails"},
+    "update_type": {"type": "string", "enum": ["full", "delta", "patch"], "description": "Type of update being applied"},
+    "signature_verified": {"type": "boolean", "description": "Whether firmware signature was successfully verified"},
+    "checksum_verified": {"type": "boolean", "description": "Whether firmware checksum was successfully verified"},
+    "free_space_kb": {"type": "integer", "minimum": 0, "description": "Available storage space in kilobytes before update"},
+    "battery_level_pct": {"type": "number", "minimum": 0, "maximum": 100, "description": "Battery level during update (critical for battery-powered devices)"}
   },
   "additionalProperties": true
 }

package/dist/esm/schemas/ota/ota-manifest.schema.json

@@ -117,6 +117,82 @@
               "description": "Array of SHA256 strings for chunks"
             }
           ]
+        },
+        "signature": {
+          "type": "string",
+          "description": "Digital signature of the firmware for authenticity verification (base64 encoded)"
+        },
+        "signature_algorithm": {
+          "type": "string",
+          "enum": ["RSA-SHA256", "ECDSA-SHA256", "Ed25519"],
+          "description": "Algorithm used for digital signature"
+        },
+        "signing_key_id": {
+          "type": "string",
+          "description": "Identifier of the signing key for key rotation support"
+        },
+        "release_notes_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to release notes or changelog for this version"
+        },
+        "min_version": {
+          "type": "string",
+          "description": "Minimum firmware version required to upgrade to this version"
+        },
+        "max_version": {
+          "type": "string",
+          "description": "Maximum firmware version that can upgrade to this version (for preventing downgrades)"
+        },
+        "criticality": {
+          "type": "string",
+          "enum": ["low", "medium", "high", "critical"],
+          "description": "Update criticality level for prioritization"
+        },
+        "mandatory": {
+          "type": "boolean",
+          "description": "Whether this update must be installed (cannot be skipped)"
+        },
+        "rollout_percentage": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 100,
+          "description": "Percentage of fleet to receive this update (staged rollout)"
+        },
+        "rollout_target_groups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Specific device groups targeted for this update (A/B testing)"
+        },
+        "delta_from_version": {
+          "type": "string",
+          "description": "Source version for delta/patch update"
+        },
+        "delta_patch_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to download delta patch instead of full firmware"
+        },
+        "delta_patch_size": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Size of delta patch in bytes"
+        },
+        "delta_patch_sha256": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$",
+          "description": "SHA256 hash of the delta patch file"
+        },
+        "deprecated": {
+          "type": "boolean",
+          "description": "Mark this version as deprecated (not recommended for new installs)"
+        },
+        "expiry_date": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO8601 timestamp when this firmware version expires and should no longer be installed"
         }
       },
       "required": ["build_type", "file", "size", "sha256", "firmware_version", "built", "ota_url"],
@@ -178,6 +254,28 @@
           "type": "string",
           "format": "date-time",
           "description": "ISO8601 timestamp"
+        },
+        "signature": {
+          "type": "string",
+          "description": "Digital signature of the firmware (base64 encoded)"
+        },
+        "signature_algorithm": {
+          "type": "string",
+          "enum": ["RSA-SHA256", "ECDSA-SHA256", "Ed25519"],
+          "description": "Algorithm used for digital signature"
+        },
+        "min_version": {
+          "type": "string",
+          "description": "Minimum firmware version required to upgrade"
+        },
+        "criticality": {
+          "type": "string",
+          "enum": ["low", "medium", "high", "critical"],
+          "description": "Update criticality level"
+        },
+        "mandatory": {
+          "type": "boolean",
+          "description": "Whether this update must be installed"
         }
       },
       "required": ["file", "size", "sha256", "version", "timestamp"],

package/dist/esm/schemas/validation_rules.md

@@ -48,8 +48,17 @@ This file captures dynamic / contextual validation that is OUTSIDE pure structur
 - All count metrics must be >= 0.
 
 ## Firmware Update Status
-- `status` must be one of: pending, downloading, flashing, verifying, rebooting, completed, failed.
+- `status` must be one of: pending, downloading, flashing, verifying, rebooting, completed, failed, rolled_back, rollback_pending, rollback_failed.
 - `progress_pct` (if present) must be 0–100.
+- **NEW (OTA Enhancement)**: 
+  - `retry_count` must be >= 0 (tracks update retry attempts).
+  - `download_speed_kbps`, `bytes_downloaded`, `bytes_total`, `eta_seconds` must be >= 0.
+  - `battery_level_pct` must be 0-100 (critical for battery-powered devices).
+  - `error_code` provides machine-readable error classification (e.g., VERIFY_CHECKSUM_MISMATCH).
+  - `update_type` must be one of: full, delta, patch.
+  - `signature_verified` and `checksum_verified` booleans indicate security verification status.
+  - `rollback_available` indicates whether automatic rollback is supported.
+  - `previous_version` stores the version to rollback to if update fails.
 
 ## Extensibility
 - Unknown top-level keys tolerated (future evolution) except if they collide with any deprecated alias or reserved future keys announced in CHANGELOG.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alteriom/mqtt-schema",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Alteriom MQTT v1 schemas, TypeScript types, and validation helpers for web integration",
   "license": "MIT",
   "author": "Alteriom Development Team",

package/schemas/firmware_status.schema.json

@@ -9,9 +9,24 @@
     "event": {"type": "string"},
     "from_version": {"type": "string"},
     "to_version": {"type": "string"},
-    "status": {"type": "string", "enum": ["pending", "downloading", "flashing", "verifying", "rebooting", "completed", "failed"]},
+    "status": {"type": "string", "enum": ["pending", "downloading", "flashing", "verifying", "rebooting", "completed", "failed", "rolled_back", "rollback_pending", "rollback_failed"]},
     "progress_pct": {"type": "number", "minimum": 0, "maximum": 100},
-    "error": {"type": ["string", "null"]}
+    "error": {"type": ["string", "null"]},
+    "error_code": {"type": "string", "description": "Machine-readable error code for diagnostics"},
+    "retry_count": {"type": "integer", "minimum": 0, "description": "Number of retry attempts for this update"},
+    "download_speed_kbps": {"type": "number", "minimum": 0, "description": "Current download speed in kilobits per second"},
+    "bytes_downloaded": {"type": "integer", "minimum": 0, "description": "Number of bytes downloaded so far"},
+    "bytes_total": {"type": "integer", "minimum": 0, "description": "Total bytes to download"},
+    "eta_seconds": {"type": "integer", "minimum": 0, "description": "Estimated time remaining in seconds"},
+    "update_started_at": {"type": "string", "format": "date-time", "description": "ISO8601 timestamp when update began"},
+    "update_completed_at": {"type": "string", "format": "date-time", "description": "ISO8601 timestamp when update completed or failed"},
+    "rollback_available": {"type": "boolean", "description": "Whether rollback to previous version is available"},
+    "previous_version": {"type": "string", "description": "Version to rollback to if update fails"},
+    "update_type": {"type": "string", "enum": ["full", "delta", "patch"], "description": "Type of update being applied"},
+    "signature_verified": {"type": "boolean", "description": "Whether firmware signature was successfully verified"},
+    "checksum_verified": {"type": "boolean", "description": "Whether firmware checksum was successfully verified"},
+    "free_space_kb": {"type": "integer", "minimum": 0, "description": "Available storage space in kilobytes before update"},
+    "battery_level_pct": {"type": "number", "minimum": 0, "maximum": 100, "description": "Battery level during update (critical for battery-powered devices)"}
   },
   "additionalProperties": true
 }

package/schemas/ota/ota-manifest.schema.json

@@ -117,6 +117,82 @@
               "description": "Array of SHA256 strings for chunks"
             }
           ]
+        },
+        "signature": {
+          "type": "string",
+          "description": "Digital signature of the firmware for authenticity verification (base64 encoded)"
+        },
+        "signature_algorithm": {
+          "type": "string",
+          "enum": ["RSA-SHA256", "ECDSA-SHA256", "Ed25519"],
+          "description": "Algorithm used for digital signature"
+        },
+        "signing_key_id": {
+          "type": "string",
+          "description": "Identifier of the signing key for key rotation support"
+        },
+        "release_notes_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to release notes or changelog for this version"
+        },
+        "min_version": {
+          "type": "string",
+          "description": "Minimum firmware version required to upgrade to this version"
+        },
+        "max_version": {
+          "type": "string",
+          "description": "Maximum firmware version that can upgrade to this version (for preventing downgrades)"
+        },
+        "criticality": {
+          "type": "string",
+          "enum": ["low", "medium", "high", "critical"],
+          "description": "Update criticality level for prioritization"
+        },
+        "mandatory": {
+          "type": "boolean",
+          "description": "Whether this update must be installed (cannot be skipped)"
+        },
+        "rollout_percentage": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 100,
+          "description": "Percentage of fleet to receive this update (staged rollout)"
+        },
+        "rollout_target_groups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Specific device groups targeted for this update (A/B testing)"
+        },
+        "delta_from_version": {
+          "type": "string",
+          "description": "Source version for delta/patch update"
+        },
+        "delta_patch_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to download delta patch instead of full firmware"
+        },
+        "delta_patch_size": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Size of delta patch in bytes"
+        },
+        "delta_patch_sha256": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$",
+          "description": "SHA256 hash of the delta patch file"
+        },
+        "deprecated": {
+          "type": "boolean",
+          "description": "Mark this version as deprecated (not recommended for new installs)"
+        },
+        "expiry_date": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO8601 timestamp when this firmware version expires and should no longer be installed"
         }
       },
       "required": ["build_type", "file", "size", "sha256", "firmware_version", "built", "ota_url"],
@@ -178,6 +254,28 @@
           "type": "string",
           "format": "date-time",
           "description": "ISO8601 timestamp"
+        },
+        "signature": {
+          "type": "string",
+          "description": "Digital signature of the firmware (base64 encoded)"
+        },
+        "signature_algorithm": {
+          "type": "string",
+          "enum": ["RSA-SHA256", "ECDSA-SHA256", "Ed25519"],
+          "description": "Algorithm used for digital signature"
+        },
+        "min_version": {
+          "type": "string",
+          "description": "Minimum firmware version required to upgrade"
+        },
+        "criticality": {
+          "type": "string",
+          "enum": ["low", "medium", "high", "critical"],
+          "description": "Update criticality level"
+        },
+        "mandatory": {
+          "type": "boolean",
+          "description": "Whether this update must be installed"
         }
       },
       "required": ["file", "size", "sha256", "version", "timestamp"],

package/schemas/validation_rules.md

@@ -48,8 +48,17 @@ This file captures dynamic / contextual validation that is OUTSIDE pure structur
 - All count metrics must be >= 0.
 
 ## Firmware Update Status
-- `status` must be one of: pending, downloading, flashing, verifying, rebooting, completed, failed.
+- `status` must be one of: pending, downloading, flashing, verifying, rebooting, completed, failed, rolled_back, rollback_pending, rollback_failed.
 - `progress_pct` (if present) must be 0–100.
+- **NEW (OTA Enhancement)**: 
+  - `retry_count` must be >= 0 (tracks update retry attempts).
+  - `download_speed_kbps`, `bytes_downloaded`, `bytes_total`, `eta_seconds` must be >= 0.
+  - `battery_level_pct` must be 0-100 (critical for battery-powered devices).
+  - `error_code` provides machine-readable error classification (e.g., VERIFY_CHECKSUM_MISMATCH).
+  - `update_type` must be one of: full, delta, patch.
+  - `signature_verified` and `checksum_verified` booleans indicate security verification status.
+  - `rollback_available` indicates whether automatic rollback is supported.
+  - `previous_version` stores the version to rollback to if update fails.
 
 ## Extensibility
 - Unknown top-level keys tolerated (future evolution) except if they collide with any deprecated alias or reserved future keys announced in CHANGELOG.