@upx-us/shield 0.7.13 → 0.8.0

package/dist/src/config.js

@@ -163,7 +163,7 @@ function loadConfig(overrides) {
         sessionDirs = discoverSessionDirs();
     }
     if (sessionDirs.length === 0) {
-        log.warn('config', 'No OpenClaw session directories found. Run: npx shield-setup');
+        log.warn('config', `No OpenClaw session directories found under ${OPENCLAW_AGENTS_DIR}. Shield is loaded but has no event sources. Set OPENCLAW_AGENTS_DIR or SESSION_DIR if your gateway stores sessions elsewhere.`);
     }
     const credentials = overrides?.credentials ?? loadCredentials();
     return {

package/dist/src/sender.d.ts

@@ -8,6 +8,7 @@ export interface SendResult {
     statusCode?: number;
     body?: string;
     eventCount: number;
+    failureKind?: 'missing_credentials' | 'pending_namespace' | 'needs_registration' | 'quota_exceeded' | 'http_error' | 'network_error' | 'circuit_breaker';
     pendingNamespace?: boolean;
     retryAfterMs?: number;
     needsRegistration?: boolean;
@@ -22,6 +23,9 @@ export interface InstanceScore {
 export interface ReportInstanceResult {
     ok: boolean;
     score?: InstanceScore;
+    statusCode?: number;
+    error?: string;
+    needsRegistration?: boolean;
 }
 export declare function reportInstance(payload: Record<string, unknown>, credentials: ShieldCredentials): Promise<ReportInstanceResult>;
 export declare function reportLifecycleEvent(type: 'plugin_started' | 'update_restart_failed' | 'plugin_integrity_drift' | 'update_check_failing' | 'update_integrity_failed', data: Record<string, unknown>, credentials: ShieldCredentials): Promise<void>;

package/dist/src/sender.js

@@ -95,7 +95,7 @@ async function sendEvents(events, config) {
     const { apiUrl, instanceId, hmacSecret, shieldEnv } = config.credentials;
     if (!apiUrl || !instanceId || !hmacSecret) {
         log.error('sender', 'Missing credentials (apiUrl, instanceId, or hmacSecret). Run: npx shield-setup');
-        return [{ success: false, statusCode: 0, body: 'missing credentials', eventCount: events.length }];
+        return [{ success: false, statusCode: 0, body: 'missing credentials', eventCount: events.length, failureKind: 'missing_credentials' }];
     }
     const results = [];
     let consecutiveBatchFailures = 0;
@@ -103,7 +103,7 @@ async function sendEvents(events, config) {
         if (consecutiveBatchFailures >= exports.CIRCUIT_BREAKER_THRESHOLD) {
             const remaining = events.slice(i);
             log.warn('sender', `Circuit breaker: ${consecutiveBatchFailures} consecutive failures — skipping ${remaining.length} remaining events`);
-            results.push({ success: false, statusCode: 0, body: 'circuit breaker', eventCount: remaining.length });
+            results.push({ success: false, statusCode: 0, body: 'circuit breaker', eventCount: remaining.length, failureKind: 'circuit_breaker' });
             break;
         }
         if (i > 0)
@@ -144,7 +144,7 @@ async function sendEvents(events, config) {
                     catch { }
                     log.warn('sender', `Batch ${batchNum} — namespace pending (202). Holding events, retry in ${retryAfterMs / 1000}s`);
                     results.push({ success: false, statusCode: 202, body: data, eventCount: batch.length,
-                        pendingNamespace: true, retryAfterMs });
+                        pendingNamespace: true, retryAfterMs, failureKind: 'pending_namespace' });
                     break;
                 }
                 if (res.status === 403) {
@@ -156,7 +156,7 @@ async function sendEvents(events, config) {
                     if (needsReg) {
                         log.error('sender', `Batch ${batchNum} — instance not registered (403). Shield deactivated — re-run wizard.`);
                         results.push({ success: false, statusCode: 403, body: data, eventCount: batch.length,
-                            needsRegistration: true });
+                            needsRegistration: true, failureKind: 'needs_registration' });
                         break;
                     }
                 }
@@ -170,21 +170,21 @@ async function sendEvents(events, config) {
                 }
                 catch { }
                 if (res.status === 402 || (res.status === 429 && parsedData?.error === 'quota_exceeded')) {
-                    log.warn('sender', `⚠ Event quota exhausted or subscription inactive — events are being dropped. Renew your subscription to resume delivery.`);
-                    results.push({ success: false, statusCode: res.status, body: data, eventCount: batch.length });
+                    log.warn('sender', '⚠ Event quota exhausted or subscription inactive — delivery is paused. Shield will retain cursor position and retry after service is restored.');
+                    results.push({ success: false, statusCode: res.status, body: data, eventCount: batch.length, failureKind: 'quota_exceeded' });
                     break;
                 }
                 const safeBody = sanitizeResponseBodyForLog(data);
                 log.error('sender', `Batch ${batchNum} — HTTP ${res.status}: ${safeBody}`);
                 consecutiveBatchFailures++;
-                results.push({ success: false, statusCode: res.status, body: data, eventCount: batch.length });
+                results.push({ success: false, statusCode: res.status, body: data, eventCount: batch.length, failureKind: 'http_error' });
                 break;
             }
             catch (err) {
                 log.error('sender', `Batch ${batchNum} attempt ${attempt + 1} — ${errMsg(err)}`);
                 if (attempt === 1) {
                     consecutiveBatchFailures++;
-                    results.push({ success: false, statusCode: 0, body: errMsg(err), eventCount: batch.length });
+                    results.push({ success: false, statusCode: 0, body: errMsg(err), eventCount: batch.length, failureKind: 'network_error' });
                 }
             }
         }
@@ -195,7 +195,7 @@ async function reportInstance(payload, credentials) {
     const { apiUrl, instanceId, hmacSecret, shieldEnv } = credentials;
     if (!apiUrl || !instanceId || !hmacSecret) {
         log.warn('sender', 'reportInstance: missing credentials, skipping');
-        return { ok: false };
+        return { ok: false, statusCode: 0, error: 'missing credentials' };
     }
     const nonce = generateNonce();
     const signature = signRequest(instanceId, nonce, hmacSecret);
@@ -217,7 +217,12 @@ async function reportInstance(payload, credentials) {
         if (!res.ok) {
             const body = await res.text();
             log.warn('sender', `reportInstance HTTP ${res.status}: ${sanitizeResponseBodyForLog(body)}`);
-            return { ok: false };
+            let needsRegistration = false;
+            try {
+                needsRegistration = JSON.parse(body).needs_registration === true;
+            }
+            catch { }
+            return { ok: false, statusCode: res.status, error: body, needsRegistration };
         }
         let score;
         try {
@@ -227,11 +232,11 @@ async function reportInstance(payload, credentials) {
         }
         catch {
         }
-        return { ok: true, score };
+        return { ok: true, score, statusCode: res.status };
     }
     catch (err) {
         log.warn('sender', `reportInstance error: ${errMsg(err)}`);
-        return { ok: false };
+        return { ok: false, statusCode: 0, error: errMsg(err) };
     }
 }
 async function reportLifecycleEvent(type, data, credentials) {

package/dist/src/updater.d.ts

@@ -10,6 +10,9 @@ export interface UpdateState {
     consecutiveFailures: number;
     pendingRestart: boolean;
     restartAttempts: number;
+    lastFailureStage: string | null;
+    lastFailureAt: number;
+    rollbackPending: boolean;
 }
 export interface UpdateCheckResult {
     updateAvailable: boolean;
@@ -33,6 +36,10 @@ export declare function classifyUpdate(current: string, candidate: string): {
     isMajor: boolean;
 };
 export declare function loadUpdateState(): UpdateState;
+export declare function preflightAutoUpdateEnvironment(): {
+    ok: boolean;
+    missing: string[];
+};
 export declare function saveUpdateState(state: UpdateState): void;
 export declare function checkNpmVersion(): string | null;
 export declare function checkForUpdate(overrideInterval?: number): UpdateCheckResult | null;

package/dist/src/updater.js

@@ -37,6 +37,7 @@ exports.parseSemVer = parseSemVer;
 exports.isNewerVersion = isNewerVersion;
 exports.classifyUpdate = classifyUpdate;
 exports.loadUpdateState = loadUpdateState;
+exports.preflightAutoUpdateEnvironment = preflightAutoUpdateEnvironment;
 exports.saveUpdateState = saveUpdateState;
 exports.checkNpmVersion = checkNpmVersion;
 exports.checkForUpdate = checkForUpdate;
@@ -117,12 +118,43 @@ function loadUpdateState() {
         consecutiveFailures: 0,
         pendingRestart: false,
         restartAttempts: 0,
+        lastFailureStage: null,
+        lastFailureAt: 0,
+        rollbackPending: false,
     };
     if (!(0, fs_1.existsSync)(UPDATE_STATE_FILE))
         return defaults;
     const loaded = (0, safe_io_1.readJsonSafe)(UPDATE_STATE_FILE, {}, 'update-state');
     return { ...defaults, ...loaded };
 }
+function recordUpdateFailure(state, stage, error, extra) {
+    state.lastFailureStage = stage;
+    state.lastFailureAt = Date.now();
+    state.lastError = error;
+    Object.assign(state, extra ?? {});
+    saveUpdateState(state);
+}
+function preflightAutoUpdateEnvironment() {
+    const checks = [
+        { name: 'npm', command: 'npm --version' },
+        { name: 'tar', command: 'tar --version' },
+        { name: 'openclaw', command: 'openclaw --version' },
+    ];
+    const missing = [];
+    for (const check of checks) {
+        try {
+            (0, child_process_1.execSync)(check.command, {
+                encoding: 'utf-8',
+                timeout: 10_000,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        catch {
+            missing.push(check.name);
+        }
+    }
+    return { ok: missing.length === 0, missing };
+}
 function saveUpdateState(state) {
     ensureDir((0, path_1.dirname)(UPDATE_STATE_FILE));
     (0, safe_io_1.writeJsonSafe)(UPDATE_STATE_FILE, state);
@@ -166,9 +198,8 @@ function checkForUpdate(overrideInterval) {
     state.lastCheckAt = now;
     state.currentVersion = version_1.VERSION;
     if (!latestVersion) {
-        state.lastError = 'Failed to query npm registry';
         state.consecutiveFailures = (state.consecutiveFailures ?? 0) + 1;
-        saveUpdateState(state);
+        recordUpdateFailure(state, 'check', 'Failed to query npm registry');
         const FAILURE_THRESHOLD = 3;
         if (state.consecutiveFailures >= FAILURE_THRESHOLD) {
             const nextRetryAt = new Date(now + CHECK_INTERVAL_MS).toISOString();
@@ -189,6 +220,8 @@ function checkForUpdate(overrideInterval) {
         state.updateAvailable = true;
         state.lastError = null;
         state.consecutiveFailures = 0;
+        state.lastFailureStage = null;
+        state.lastFailureAt = 0;
         saveUpdateState(state);
         const classification = classifyUpdate(version_1.VERSION, latestVersion);
         log.info('updater', `Update available: ${version_1.VERSION} → ${latestVersion} (${classification.isPatch ? 'patch' : classification.isMinor ? 'minor' : 'major'})`);
@@ -202,6 +235,8 @@ function checkForUpdate(overrideInterval) {
     state.updateAvailable = false;
     state.lastError = null;
     state.consecutiveFailures = 0;
+    state.lastFailureStage = null;
+    state.lastFailureAt = 0;
     saveUpdateState(state);
     return null;
 }
@@ -472,6 +507,8 @@ function performAutoUpdate(mode, checkIntervalMs) {
             log.info('updater', `Clearing stale pendingRestart — running version matches stored currentVersion (${version_1.VERSION})`);
             st.pendingRestart = false;
             st.restartAttempts = 0;
+            st.rollbackPending = false;
+            st.lastFailureStage = null;
             saveUpdateState(st);
         }
     }
@@ -499,6 +536,7 @@ function performAutoUpdate(mode, checkIntervalMs) {
                 }
                 state.pendingRestart = false;
                 state.restartAttempts = 0;
+                state.rollbackPending = false;
                 saveUpdateState(state);
             }
             else {
@@ -507,10 +545,14 @@ function performAutoUpdate(mode, checkIntervalMs) {
                 if (restarted) {
                     state.pendingRestart = false;
                     state.restartAttempts = 0;
+                    state.rollbackPending = false;
+                    state.lastFailureStage = null;
                     saveUpdateState(state);
                 }
                 else {
                     state.restartAttempts = (state.restartAttempts ?? 0) + 1;
+                    state.lastFailureStage = 'restart';
+                    state.lastFailureAt = Date.now();
                     saveUpdateState(state);
                 }
             }
@@ -550,11 +592,22 @@ function performAutoUpdate(mode, checkIntervalMs) {
     }
     const state = loadUpdateState();
     log.info('updater', `Auto-updating: ${version_1.VERSION} → ${check.latestVersion}`);
+    const preflight = preflightAutoUpdateEnvironment();
+    if (!preflight.ok) {
+        state.consecutiveFailures++;
+        recordUpdateFailure(state, 'preflight', `Missing required commands for auto-update: ${preflight.missing.join(', ')}`);
+        return {
+            action: 'error',
+            fromVersion: version_1.VERSION,
+            toVersion: check.latestVersion,
+            message: `Auto-update aborted: missing required commands (${preflight.missing.join(', ')})`,
+            requiresRestart: false,
+        };
+    }
     const backupPath = backupCurrentVersion();
     if (!backupPath) {
         state.consecutiveFailures++;
-        state.lastError = 'Backup failed — update aborted';
-        saveUpdateState(state);
+        recordUpdateFailure(state, 'backup', 'Backup failed — update aborted');
         return {
             action: 'error',
             fromVersion: version_1.VERSION,
@@ -568,8 +621,7 @@ function performAutoUpdate(mode, checkIntervalMs) {
         log.warn('updater', 'Install failed — rolling back...');
         const restored = restoreFromBackup(backupPath);
         state.consecutiveFailures++;
-        state.lastError = 'Install failed — rolled back';
-        saveUpdateState(state);
+        recordUpdateFailure(state, restored ? 'install' : 'rollback', restored ? 'Install failed — rolled back' : 'Install failed and rollback failed', { rollbackPending: !restored });
         return {
             action: restored ? 'rollback' : 'error',
             fromVersion: version_1.VERSION,
@@ -591,8 +643,7 @@ function performAutoUpdate(mode, checkIntervalMs) {
         log.warn('updater', 'Rolling back...');
         restoreFromBackup(backupPath);
         state.consecutiveFailures++;
-        state.lastError = 'Post-install validation failed — rolled back';
-        saveUpdateState(state);
+        recordUpdateFailure(state, 'validation', 'Post-install validation failed — rolled back');
         return {
             action: 'rollback',
             fromVersion: version_1.VERSION,
@@ -614,8 +665,7 @@ function performAutoUpdate(mode, checkIntervalMs) {
         }
         catch { }
         state.consecutiveFailures++;
-        state.lastError = 'Integrity check failed — rolled back';
-        saveUpdateState(state);
+        recordUpdateFailure(state, 'integrity', 'Integrity check failed — rolled back');
         return noOp;
     }
     const restarted = requestGatewayRestart();
@@ -626,6 +676,9 @@ function performAutoUpdate(mode, checkIntervalMs) {
         state.lastUpdateAt = Date.now();
         state.consecutiveFailures = 0;
         state.lastError = null;
+        state.lastFailureStage = 'restart';
+        state.lastFailureAt = Date.now();
+        state.rollbackPending = false;
         saveUpdateState(state);
         log.warn('updater', `Gateway restart failed after update to ${check.latestVersion} — will retry on next poll cycle.`);
         return {
@@ -644,6 +697,9 @@ function performAutoUpdate(mode, checkIntervalMs) {
     state.currentVersion = check.latestVersion;
     state.consecutiveFailures = 0;
     state.lastError = null;
+    state.lastFailureStage = null;
+    state.lastFailureAt = 0;
+    state.rollbackPending = false;
     saveUpdateState(state);
     log.info('updater', `✅ Auto-updated: ${version_1.VERSION} → ${check.latestVersion}. Gateway restart initiated.`);
     return {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "shield",
   "name": "OpenClaw Shield",
   "description": "Real-time security monitoring — streams enriched, redacted security events to the Shield detection platform.",
-  "version": "0.7.13",
+  "version": "0.8.0",
   "skills": [
     "./skills"
   ],
@@ -47,7 +47,7 @@
           }
         ],
         "default": true,
-        "description": "Auto-update mode: true (auto-update patch versions), false (disabled), or 'notify-only' (log available updates without installing)."
+        "description": "Auto-update mode: true (auto-update patch and minor versions with rollback safety), false (disabled), or 'notify-only' (log available updates without installing)."
       },
       "debugLog": {
         "type": "boolean",
@@ -78,7 +78,7 @@
     },
     "autoUpdate": {
       "label": "Auto-update mode",
-      "description": "true = auto-install patch updates, 'notify-only' = log only, false = disabled"
+      "description": "true = auto-install patch and minor updates, 'notify-only' = log only, false = disabled"
     },
     "debugLog": {
       "label": "Debug logging",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upx-us/shield",
-  "version": "0.7.13",
+  "version": "0.8.0",
   "description": "Security monitoring plugin for OpenClaw agents — streams enriched security events to the Shield detection platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",