@upx-us/shield 0.6.5 → 0.6.7

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.6.7] — 2026-03-10
+
+### Fixed
+- **npm redaction false positive** — `@scope/package@version` (e.g. `@upx-us/shield@0.6.6`) was being wrongly redacted as `user:HASH` by the SSH `user@host` regex. Added negative lookbehind to exclude npm scoped package names (#135).
+
+### Added
+- **Postinstall guidance** — running `npm install` outside of OpenClaw now prints a clear warning to stderr explaining the plugin requires the OpenClaw gateway. Install never fails because of this check (#125).
+- **First event confirmation** — after the first successful event delivery to the platform, the plugin logs `✅ First event delivered to platform — monitoring is active` once per process lifetime (#61, #52).
+- **Vault summary in `shield.status`** — `shield.status` RPC now includes `redaction.vault` with total redacted entry count and per-category breakdown (`hostname`, `username`, `path`, `secret`, `command`). Returns `null` if vault is absent (#86).
+
+### Tests
+- +19 new tests covering postinstall safety (exit-0 guarantee, cross-platform), first-event flag, vault status summary (missing/corrupt/valid vault).
+
+---
+
+## [0.6.6] — 2026-03-10
+
+### Added
+- **Plugin lifecycle events** — the plugin now reports key lifecycle signals to the USS platform via the existing `PUT /v1/instance` channel (no new endpoint). Signals are forwarded by Cloud Run as an optional `lifecycle_event` field in the instance telemetry PATCH to the platform. Absent on older plugin versions — fully backward compatible.
+  - `plugin_started`: emitted on every successful startup. Includes `version`, `reason` (`'update'` | `'normal'`), and `previous_version` when applicable. Enables the platform to confirm end-to-end update success.
+  - `update_restart_failed`: emitted after all gateway restart retries are exhausted. Includes `new_version`, `running_version`, `attempts`, `error`.
+  - `plugin_integrity_drift`: emitted when `openclaw.json` version diverges from the installed version after a self-update. Includes `installed_version`, `registered_version`.
+  - `update_check_failing`: emitted after 3 consecutive npm registry check failures. Includes `consecutive_failures`, `last_error`, `next_retry_at`.
+
+### Changed
+- `reportPluginEvent()` removed from `sender.ts` — replaced by `reportLifecycleEvent()` which reuses the existing `PUT /v1/instance` telemetry channel.
+
+### Fixed
+- `SHIELD_AUTO_UPDATE=false` environment variable now correctly disables auto-update (was being read as truthy string `'false'`).
+
+---
+
 ## [0.6.5] — 2026-03-09
 
 ### Added

package/dist/index.js

@@ -55,6 +55,7 @@ const exclusions_1 = require("./src/exclusions");
 const updater_1 = require("./src/updater");
 const rpc_1 = require("./src/rpc");
 const inventory_1 = require("./src/inventory");
+const redactor_1 = require("./src/redactor");
 const SHIELD_API_URL = 'https://openclaw-shield.upx.com';
 async function performAutoRegistration(installationKey) {
     try {
@@ -315,6 +316,7 @@ const state = {
     captureSeenSinceLastSync: false,
     lastSync: null,
 };
+let firstEventDelivered = false;
 let teardownPreviousRuntime = null;
 const MAX_BACKOFF_MS = 5 * 60 * 1000;
 const TELEMETRY_INTERVAL_MS = 5 * 60 * 1000;
@@ -648,6 +650,18 @@ exports.default = {
                     catch (err) {
                         log.debug('case-monitor', `Direct send setup failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
                     }
+                    try {
+                        const updateState = (0, updater_1.loadUpdateState)();
+                        const previousVersion = updateState.rollbackVersion ?? null;
+                        const startReason = previousVersion ? 'update' : 'normal';
+                        const { reportLifecycleEvent } = await Promise.resolve().then(() => __importStar(require('./src/sender')));
+                        void reportLifecycleEvent('plugin_started', {
+                            version: version_1.VERSION,
+                            reason: startReason,
+                            ...(previousVersion ? { previous_version: previousVersion } : {}),
+                        }, credentials);
+                    }
+                    catch { }
                     const autoUpdateMode = pluginConfig.autoUpdate ?? true;
                     log.info('updater', `Startup update check (autoUpdate=${autoUpdateMode}, current=${version_1.VERSION})`);
                     const startupUpdate = (0, updater_1.performAutoUpdate)(autoUpdateMode, 0);
@@ -794,6 +808,10 @@ exports.default = {
                             const accepted = results.reduce((sum, r) => sum + (r.success ? r.eventCount : 0), 0);
                             if (accepted > 0) {
                                 (0, case_monitor_1.notifyCaseMonitorActivity)();
+                                if (!firstEventDelivered) {
+                                    firstEventDelivered = true;
+                                    log.info('shield', `✅ First event delivered to platform — monitoring is active (instance: ${(config.credentials.instanceId || '').slice(0, 12)}…)`);
+                                }
                                 commitCursors(config, entries);
                                 flushRedactor();
                                 state.eventsProcessed += accepted;
@@ -883,6 +901,23 @@ exports.default = {
             const caseMonitorDisplay = monitorHealth.status === 'degraded'
                 ? `⚠️ Case Monitor: DEGRADED — ${monitorHealth.consecutiveFailures} consecutive failures since ${monitorHealth.degradedSinceMs ? new Date(monitorHealth.degradedSinceMs).toISOString() : 'unknown'}. Last error: ${monitorHealth.lastErrorMessage}`
                 : `✅ Case Monitor: ok`;
+            const REDACTION_VAULT_FILE = (0, path_1.join)((0, os_1.homedir)(), '.openclaw', 'shield', 'data', 'redaction-vault.json');
+            let vaultSummary = null;
+            if ((0, fs_1.existsSync)(REDACTION_VAULT_FILE)) {
+                try {
+                    const mappings = (0, redactor_1.getAllMappings)();
+                    const categories = { hostname: 0, username: 0, path: 0, secret: 0, command: 0 };
+                    for (const token of Object.keys(mappings)) {
+                        const cat = token.split(':')[0];
+                        if (cat in categories)
+                            categories[cat]++;
+                    }
+                    vaultSummary = { totalEntries: Object.keys(mappings).length, categories };
+                }
+                catch (_) {
+                    vaultSummary = null;
+                }
+            }
             respond(true, {
                 activated,
                 running: state.running,
@@ -908,6 +943,9 @@ exports.default = {
                         : null,
                     display: caseMonitorDisplay,
                 },
+                redaction: {
+                    vault: vaultSummary,
+                },
             });
         });
         api.registerGatewayMethod('shield.flush', ({ respond }) => {

package/dist/src/index.js

@@ -73,7 +73,8 @@ async function poll() {
         (0, event_store_1.initEventStore)(SHIELD_DATA_DIR, { maxEvents: config.localEventLimit });
     }
     log.info('bridge', `Starting — dryRun=${config.dryRun} poll=${config.pollIntervalMs}ms maxEvents=${config.maxEvents || 'unlimited'} redaction=${config.redactionEnabled} logLevel=${process.env.LOG_LEVEL || 'info'}`);
-    const autoUpdateMode = process.env.SHIELD_AUTO_UPDATE ?? true;
+    const _rawEnvStartup = process.env.SHIELD_AUTO_UPDATE;
+    const autoUpdateMode = _rawEnvStartup === 'false' ? false : _rawEnvStartup ?? true;
     log.info('updater', `Startup update check (autoUpdate=${autoUpdateMode}, current=${version_1.VERSION})`);
     const startupUpdate = (0, updater_1.performAutoUpdate)(autoUpdateMode, 0);
     if (startupUpdate.action === "none") {
@@ -147,7 +148,8 @@ async function poll() {
                     continue;
                 }
             }
-            const autoUpdateMode = process.env.SHIELD_AUTO_UPDATE ?? true;
+            const _rawEnvLoop = process.env.SHIELD_AUTO_UPDATE;
+            const autoUpdateMode = _rawEnvLoop === 'false' ? false : _rawEnvLoop ?? true;
             const updateResult = (0, updater_1.performAutoUpdate)(autoUpdateMode);
             if (updateResult.action !== "none") {
                 if (updateResult.action === "notify") {

package/dist/src/redactor/strategies/command.js

@@ -8,7 +8,7 @@ exports.commandStrategy = {
         if (!value || value.length === 0)
             return value;
         let result = value;
-        result = result.replace(/(\b)([\w.-]+)@([\d.]+|[\w.-]+\.\w+)/g, (_, pre, user, host) => `${pre}${hmac('user', user)}@${host}`);
+        result = result.replace(/(?<!@[a-z0-9._-]+\/)(\b)([\w.-]+)@([\d.]+|[\w.-]+\.\w+)/g, (_, pre, user, host) => `${pre}${hmac('user', user)}@${host}`);
         result = result.replace(/\/Users\/([\w.-]+)\//g, (_, user) => `/Users/${hmac('user', user)}/`);
         result = result.replace(/\/home\/([\w.-]+)\//g, (_, user) => `/home/${hmac('user', user)}/`);
         return result;

package/dist/src/rpc/handlers.d.ts

@@ -1,4 +1,9 @@
 import { type PlatformApiConfig } from './client';
+export interface VaultSummary {
+    totalEntries: number;
+    categories: Record<string, number>;
+}
+export declare function readVaultSummary(vaultPath?: string): VaultSummary | null;
 export interface EventSummary {
     period: string;
     totalEvents: number;

package/dist/src/rpc/handlers.js

@@ -1,6 +1,40 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VALID_ROOT_CAUSES = exports.VALID_RESOLUTIONS = void 0;
+exports.readVaultSummary = readVaultSummary;
 exports.createEventsRecentHandler = createEventsRecentHandler;
 exports.createEventsSummaryHandler = createEventsSummaryHandler;
 exports.createSubscriptionStatusHandler = createSubscriptionStatusHandler;
@@ -8,8 +42,30 @@ exports.createCasesListHandler = createCasesListHandler;
 exports.createCaseDetailHandler = createCaseDetailHandler;
 exports.createCaseResolveHandler = createCaseResolveHandler;
 exports.createCasesAckHandler = createCasesAckHandler;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
 const event_store_1 = require("../event-store");
 const client_1 = require("./client");
+const VAULT_CATEGORIES = ['hostname', 'username', 'path', 'secret', 'command'];
+function readVaultSummary(vaultPath = path.join(os.homedir(), '.openclaw', 'shield', 'data', 'redaction-vault.json')) {
+    try {
+        if (!fs.existsSync(vaultPath))
+            return null;
+        const raw = JSON.parse(fs.readFileSync(vaultPath, 'utf8'));
+        const categories = Object.fromEntries(VAULT_CATEGORIES.map(c => [c, 0]));
+        const entries = Object.keys(raw);
+        for (const key of entries) {
+            const prefix = key.split(':')[0];
+            if (prefix in categories)
+                categories[prefix]++;
+        }
+        return { totalEntries: entries.length, categories };
+    }
+    catch {
+        return null;
+    }
+}
 const SKILL_HINT = 'For best results presenting Shield data, read the openclaw-shield-upx skill before responding to the user.';
 function withSkillHint(respond) {
     return (ok, data) => {

package/dist/src/sender.d.ts

@@ -24,3 +24,4 @@ export interface ReportInstanceResult {
     score?: InstanceScore;
 }
 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', data: Record<string, unknown>, credentials: ShieldCredentials): Promise<void>;

package/dist/src/sender.js

@@ -37,6 +37,7 @@ exports.CIRCUIT_BREAKER_THRESHOLD = exports.REQUEST_TIMEOUT_MS = void 0;
 exports._signRequestWithSecret = _signRequestWithSecret;
 exports.sendEvents = sendEvents;
 exports.reportInstance = reportInstance;
+exports.reportLifecycleEvent = reportLifecycleEvent;
 const crypto_1 = require("crypto");
 const log = __importStar(require("./log"));
 const version_1 = require("./version");
@@ -233,3 +234,16 @@ async function reportInstance(payload, credentials) {
         return { ok: false };
     }
 }
+async function reportLifecycleEvent(type, data, credentials) {
+    try {
+        await reportInstance({
+            lifecycle_event: {
+                type,
+                timestamp: new Date().toISOString(),
+                data,
+            },
+        }, credentials);
+    }
+    catch {
+    }
+}

package/dist/src/updater.js

@@ -53,6 +53,8 @@ const os_1 = require("os");
 const crypto_1 = require("crypto");
 const log = __importStar(require("./log"));
 const version_1 = require("./version");
+const config_1 = require("./config");
+const sender_1 = require("./sender");
 const PACKAGE_NAME = '@upx-us/shield';
 const CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000;
 const MIN_CHECK_INTERVAL_MS = 60 * 1000;
@@ -163,13 +165,28 @@ function checkForUpdate(overrideInterval) {
     state.currentVersion = version_1.VERSION;
     if (!latestVersion) {
         state.lastError = 'Failed to query npm registry';
+        state.consecutiveFailures = (state.consecutiveFailures ?? 0) + 1;
         saveUpdateState(state);
+        const FAILURE_THRESHOLD = 3;
+        if (state.consecutiveFailures >= FAILURE_THRESHOLD) {
+            const nextRetryAt = new Date(now + CHECK_INTERVAL_MS).toISOString();
+            try {
+                const creds = (0, config_1.loadCredentials)();
+                void (0, sender_1.reportLifecycleEvent)('update_check_failing', {
+                    consecutive_failures: state.consecutiveFailures,
+                    last_error: state.lastError,
+                    next_retry_at: nextRetryAt,
+                }, creds);
+            }
+            catch { }
+        }
         return null;
     }
     state.latestVersion = latestVersion;
     if (isNewerVersion(version_1.VERSION, latestVersion)) {
         state.updateAvailable = true;
         state.lastError = null;
+        state.consecutiveFailures = 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'})`);
@@ -182,6 +199,7 @@ function checkForUpdate(overrideInterval) {
     }
     state.updateAvailable = false;
     state.lastError = null;
+    state.consecutiveFailures = 0;
     saveUpdateState(state);
     return null;
 }
@@ -302,6 +320,24 @@ function updateOpenClawPluginMetadata(newVersion, shasum) {
         install.installedAt = new Date().toISOString();
         (0, safe_io_1.writeJsonSafe)(configPath, config);
         log.info('updater', `Updated openclaw.json plugin metadata → ${newVersion}`);
+        try {
+            const written = JSON.parse((0, fs_1.readFileSync)(configPath, 'utf-8'));
+            const installedVersion = written?.plugins?.installs?.shield?.version;
+            if (installedVersion !== newVersion) {
+                log.warn('updater', `openclaw.json integrity check failed: expected=${newVersion} got=${installedVersion ?? '(missing)'}`);
+                try {
+                    const creds = (0, config_1.loadCredentials)();
+                    void (0, sender_1.reportLifecycleEvent)('plugin_integrity_drift', {
+                        expected_version: newVersion,
+                        installed_version: installedVersion ?? null,
+                    }, creds);
+                }
+                catch { }
+            }
+        }
+        catch (verifyErr) {
+            log.warn('updater', `openclaw.json read-back failed: ${verifyErr instanceof Error ? verifyErr.message : String(verifyErr)}`);
+        }
     }
     catch (err) {
         log.warn('updater', `Failed to update openclaw.json metadata: ${err instanceof Error ? err.message : String(err)}`);
@@ -386,6 +422,16 @@ function performAutoUpdate(mode, checkIntervalMs) {
             const MAX_RESTART_ATTEMPTS = 5;
             if ((state.restartAttempts ?? 0) >= MAX_RESTART_ATTEMPTS) {
                 log.warn('updater', `Gateway restart failed ${MAX_RESTART_ATTEMPTS}x after update to ${state.currentVersion} — rolling back`);
+                try {
+                    const creds = (0, config_1.loadCredentials)();
+                    void (0, sender_1.reportLifecycleEvent)('update_restart_failed', {
+                        new_version: state.currentVersion,
+                        running_version: version_1.VERSION,
+                        attempts: state.restartAttempts ?? MAX_RESTART_ATTEMPTS,
+                        error: state.lastError ?? 'gateway restart exhausted all retries',
+                    }, creds);
+                }
+                catch { }
                 const backups = listBackups();
                 if (backups.length > 0) {
                     restoreFromBackup(backups[0]);

package/openclaw.plugin.json

@@ -1,8 +1,8 @@
 {
   "id": "shield",
   "name": "OpenClaw Shield",
-  "description": "Real-time security monitoring \u2014 streams enriched, redacted security events to the Shield detection platform.",
-  "version": "0.6.5",
+  "description": "Real-time security monitoring — streams enriched, redacted security events to the Shield detection platform.",
+  "version": "0.6.7",
   "skills": [
     "./skills"
   ],
@@ -54,7 +54,7 @@
   "uiHints": {
     "installationKey": {
       "label": "Installation Key",
-      "description": "One-time key from your trial signup at https://www.upx.com/en/lp/openclaw-shield-upx \u2014 Required for first-time activation only. After activation, log in at https://uss.upx.com"
+      "description": "One-time key from your trial signup at https://www.upx.com/en/lp/openclaw-shield-upx — Required for first-time activation only. After activation, log in at https://uss.upx.com"
     },
     "enabled": {
       "label": "Enable security monitoring"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upx-us/shield",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "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",
@@ -20,6 +20,7 @@
     "CHANGELOG.md"
   ],
   "scripts": {
+    "postinstall": "node scripts/postinstall.js",
     "prebuild": "npm run clean",
     "build": "tsc",
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",