@upx-us/shield 0.2.16-beta → 0.3.4

package/dist/index.js

@@ -1,19 +1,4 @@
 "use strict";
-/**
- * OpenClaw Shield — Plugin Entry Point
- *
- * This file is the OpenClaw plugin entry point, declared in package.json
- * under `openclaw.extensions`. It registers the Shield plugin with the
- * OpenClaw Gateway and starts the monitoring bridge as a managed service.
- *
- * The monitoring bridge runs as a background service within the Gateway
- * process, polling session files and forwarding enriched security events
- * to the Shield detection platform.
- *
- * Dual-mode design:
- *   - Plugin mode: this file, registered via api.registerService()
- *   - Standalone mode: src/index.ts, runs directly via `shield-bridge`
- */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -48,6 +33,11 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.performAutoRegistration = performAutoRegistration;
+exports.resolveInstallationKey = resolveInstallationKey;
+exports.maskPluginConfigForLogs = maskPluginConfigForLogs;
+exports.createSingleflightRunner = createSingleflightRunner;
+exports.createStartGuard = createStartGuard;
 const config_1 = require("./src/config");
 const log_1 = require("./src/log");
 const log = __importStar(require("./src/log"));
@@ -55,22 +45,208 @@ const version_1 = require("./src/version");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const os_1 = require("os");
-// ─── Persistent status file ──────────────────────────────────────────────────
-// Written by the daemon after each poll; read by the CLI status command.
+const crypto_1 = require("crypto");
+const counters_1 = require("./src/counters");
+const SHIELD_API_URL = 'https://openclaw-shield.upx.com';
+async function performAutoRegistration(installationKey) {
+    try {
+        const fingerprint = (0, crypto_1.createHash)('sha256')
+            .update(`${(0, os_1.hostname)()}-${(0, os_1.userInfo)().username}-${Date.now()}`)
+            .digest('hex');
+        const payload = {
+            installation_code: installationKey,
+            fingerprint,
+            machine: {
+                hostname: (0, os_1.hostname)(),
+                user: (0, os_1.userInfo)().username,
+                os: process.platform,
+                arch: process.arch,
+                node_version: process.version,
+            },
+            software: {
+                plugin_version: version_1.VERSION,
+                instance_name: `openclaw-${(0, os_1.hostname)()}`,
+            },
+        };
+        const response = await fetch(`${SHIELD_API_URL}/v1/register`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'User-Agent': 'OpenClaw-Shield-Plugin/auto-register' },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => '');
+            let msg = `HTTP ${response.status}`;
+            try {
+                const p = JSON.parse(body);
+                msg = p.message || p.error || msg;
+            }
+            catch { }
+            log.error('shield', `Auto-registration failed: ${msg}`);
+            return null;
+        }
+        const data = await response.json();
+        const hmacSecret = data.hmacSecret;
+        if (!hmacSecret) {
+            log.error('shield', 'Auto-registration failed: no credentials returned from platform');
+            return null;
+        }
+        const configDir = (0, path_1.join)(config_1.SHIELD_CONFIG_PATH, '..');
+        if (!(0, fs_1.existsSync)(configDir))
+            (0, fs_1.mkdirSync)(configDir, { recursive: true });
+        const envContent = [
+            `# Shield API Configuration — auto-generated by OpenClaw plugin on ${new Date().toISOString()}`,
+            `SHIELD_API_URL=${SHIELD_API_URL}`,
+            `SHIELD_INSTANCE_ID=${fingerprint}`,
+            `SHIELD_HMAC_SECRET=${hmacSecret}`,
+            `INSTANCE_NAME=openclaw-${(0, os_1.hostname)()}`,
+        ].join('\n') + '\n';
+        (0, fs_1.writeFileSync)(config_1.SHIELD_CONFIG_PATH, envContent, { encoding: 'utf-8', mode: 0o600 });
+        return { apiUrl: SHIELD_API_URL, instanceId: fingerprint, hmacSecret, shieldEnv: '' };
+    }
+    catch (err) {
+        log.error('shield', `Auto-registration error: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+function resolveInstallationKey(pluginConfig) {
+    if (typeof pluginConfig.installationKey !== 'string')
+        return null;
+    const key = pluginConfig.installationKey.trim();
+    log.debug('shield', `installationKey lookup: found=${!!key}`);
+    return key || null;
+}
+const PLACEHOLDER_VALUES = new Set(['saved-secret-123', 'placeholder', 'replace_me', '']);
+function hasValidCredentials(creds) {
+    const isPlaceholder = (v) => !v || PLACEHOLDER_VALUES.has(v.trim().toLowerCase());
+    return !isPlaceholder(creds.apiUrl) && !isPlaceholder(creds.instanceId) && !isPlaceholder(creds.hmacSecret);
+}
+const SENSITIVE_KEY_RE = /(installationkey|secret|token|password|apikey|api_key|hmac)/i;
+function sanitizeConfigValue(value) {
+    if (Array.isArray(value))
+        return value.map(sanitizeConfigValue);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = SENSITIVE_KEY_RE.test(k) ? '[REDACTED]' : sanitizeConfigValue(v);
+        }
+        return out;
+    }
+    return value;
+}
+function maskPluginConfigForLogs(pluginConfig) {
+    return sanitizeConfigValue(pluginConfig);
+}
+function createSingleflightRunner(task) {
+    let inFlight = null;
+    return async () => {
+        if (inFlight)
+            return inFlight;
+        inFlight = (async () => {
+            try {
+                await task();
+            }
+            finally {
+                inFlight = null;
+            }
+        })();
+        return inFlight;
+    };
+}
+function createStartGuard() {
+    let started = false;
+    let starting = false;
+    return {
+        begin() {
+            if (started || starting)
+                return false;
+            starting = true;
+            return true;
+        },
+        endSuccess() {
+            starting = false;
+            started = true;
+        },
+        endFailure() {
+            starting = false;
+        },
+        reset() {
+            started = false;
+            starting = false;
+        },
+    };
+}
 const STATUS_FILE = (0, path_1.join)((0, os_1.homedir)(), '.openclaw', 'shield', 'data', 'status.json');
+const STATS_FILE = (0, path_1.join)((0, os_1.homedir)(), '.openclaw', 'shield', 'data', 'stats.json');
+let _allTimeStats = null;
+let _allTimeStatsDirty = false;
+function readAllTimeStats() {
+    if (_allTimeStats)
+        return _allTimeStats;
+    try {
+        if (!(0, fs_1.existsSync)(STATS_FILE)) {
+            _allTimeStats = { eventsProcessed: 0, quarantineCount: 0 };
+            return _allTimeStats;
+        }
+        _allTimeStats = JSON.parse((0, fs_1.readFileSync)(STATS_FILE, 'utf8'));
+        return _allTimeStats;
+    }
+    catch {
+        _allTimeStats = { eventsProcessed: 0, quarantineCount: 0 };
+        return _allTimeStats;
+    }
+}
+function writeAllTimeStats(delta) {
+    const current = readAllTimeStats();
+    if (delta.eventsProcessed)
+        current.eventsProcessed += delta.eventsProcessed;
+    if (delta.quarantineCount)
+        current.quarantineCount += delta.quarantineCount;
+    _allTimeStatsDirty = true;
+}
+function flushAllTimeStats() {
+    if (!_allTimeStatsDirty || !_allTimeStats)
+        return;
+    try {
+        const dir = (0, path_1.join)((0, os_1.homedir)(), '.openclaw', 'shield', 'data');
+        if (!(0, fs_1.existsSync)(dir))
+            (0, fs_1.mkdirSync)(dir, { recursive: true });
+        (0, fs_1.writeFileSync)(STATS_FILE, JSON.stringify(_allTimeStats, null, 2));
+        _allTimeStatsDirty = false;
+    }
+    catch { }
+}
+let _stateDirty = true;
+function markStateDirty() { _stateDirty = true; }
 function persistState(extra = {}) {
+    flushAllTimeStats();
+    if (!_stateDirty)
+        return;
     try {
         const dir = (0, path_1.join)((0, os_1.homedir)(), '.openclaw', 'shield', 'data');
         if (!(0, fs_1.existsSync)(dir))
             (0, fs_1.mkdirSync)(dir, { recursive: true });
+        let countersSnapshot = {};
+        try {
+            countersSnapshot = {
+                totalEvents: (0, counters_1.getTotalEventCount)(),
+                eventTypes: Object.fromEntries((0, counters_1.getEventTypeCounts)().map(({ type, count }) => [type, count])),
+                totalRedactions: (0, counters_1.getTotalRedactionCount)(),
+                redactionCategories: Object.fromEntries((0, counters_1.getRedactionCounts)().map(({ category, count }) => [category, count])),
+            };
+        }
+        catch { }
         (0, fs_1.writeFileSync)(STATUS_FILE, JSON.stringify({
             ...state, ...extra,
             version: version_1.VERSION,
             updatedAt: Date.now(),
             pid: process.pid,
+            counters: countersSnapshot,
+            allTime: readAllTimeStats(),
         }, null, 2));
+        _stateDirty = false;
     }
-    catch { /* non-fatal */ }
+    catch { }
 }
 function readPersistedState() {
     try {
@@ -79,22 +255,23 @@ function readPersistedState() {
         const d = JSON.parse((0, fs_1.readFileSync)(STATUS_FILE, 'utf8'));
         const age = Date.now() - (d.updatedAt || 0);
         if (age > 10 * 60 * 1000)
-            return null; // stale if >10min
+            return null;
         return d;
     }
     catch {
         return null;
     }
 }
-// ---------------------------------------------------------------------------
-// Bridge state — shared between service lifecycle, RPC, and CLI
-// ---------------------------------------------------------------------------
 const state = {
+    activated: false,
     running: false,
+    startedAt: 0,
     lastPollAt: 0,
     eventsProcessed: 0,
     quarantineCount: 0,
     consecutiveFailures: 0,
+    instanceId: '',
+    lastSync: null,
 };
 const MAX_BACKOFF_MS = 5 * 60 * 1000;
 const TELEMETRY_INTERVAL_MS = 5 * 60 * 1000;
@@ -104,14 +281,122 @@ function getBackoffInterval(baseMs) {
     const backoff = baseMs * Math.pow(2, Math.min(state.consecutiveFailures, 10));
     return Math.min(backoff, MAX_BACKOFF_MS);
 }
-// ---------------------------------------------------------------------------
-// Plugin export
-// ---------------------------------------------------------------------------
+function printNotActivatedStatus() {
+    console.log(`OpenClaw Shield — v${version_1.VERSION}`);
+    console.log('');
+    console.log('  Status: Loaded (not activated)');
+    console.log('');
+    console.log('  To activate, provide your Installation Key:');
+    console.log('    1. openclaw shield activate <YOUR_KEY>');
+    console.log('    2. Add to openclaw.json:');
+    console.log('         plugins.entries.shield.config.installationKey = "<YOUR_KEY>"');
+    console.log('       Then: openclaw gateway restart');
+    console.log('');
+    console.log('  Get your key at: https://uss.upx.com → APPS → OpenClaw Shield');
+}
+function printActivatedStatus() {
+    const s = readPersistedState() ?? state;
+    const isRunning = Boolean(s.running);
+    const ageMs = s.updatedAt ? Date.now() - s.updatedAt : null;
+    const ageLabel = ageMs != null
+        ? (ageMs < 60_000 ? `${Math.round(ageMs / 1000)}s ago`
+            : ageMs < 3_600_000 ? `${Math.floor(ageMs / 60_000)}m ago`
+                : `${(ageMs / 3_600_000).toFixed(1)}h ago`)
+        : '';
+    const lastPollMs = s.lastPollAt ? Date.now() - s.lastPollAt : null;
+    const lastPollLabel = s.lastPollAt
+        ? (lastPollMs < 60_000 ? `${Math.round(lastPollMs / 1000)}s ago`
+            : lastPollMs < 3_600_000 ? `${Math.floor(lastPollMs / 60_000)}m ago`
+                : `${(lastPollMs / 3_600_000).toFixed(1)}h ago`)
+        : 'never';
+    const instanceId = s.instanceId;
+    const shortId = instanceId ? `${instanceId.slice(0, 8)}…` : '';
+    console.log(`OpenClaw Shield — v${s.version ?? version_1.VERSION}${ageLabel ? `  (${ageLabel})` : ''}`);
+    console.log('');
+    console.log('── Plugin Health ─────────────────────────────');
+    console.log(`  Connection:   ${isRunning ? '✅ Connected' : '❌ Disconnected'}`);
+    console.log(`  Version:      ${s.version ?? version_1.VERSION}`);
+    if (shortId)
+        console.log(`  Instance:     ${shortId}`);
+    console.log(`  Last poll:    ${lastPollLabel}`);
+    const allTime = (s.allTime ?? readAllTimeStats());
+    console.log(`  Events sent:  ${allTime.eventsProcessed.toLocaleString()}  (all-time)`);
+    console.log(`  Quarantine:   ${allTime.quarantineCount.toLocaleString()}  (all-time)`);
+    console.log(`  Failures:     ${s.consecutiveFailures ?? 0}  (consecutive)`);
+    if (s.pid)
+        console.log(`  Daemon PID:   ${s.pid}`);
+    const startedAt = s.startedAt;
+    if (startedAt) {
+        const uptimeMs = Date.now() - startedAt;
+        const uptimeLabel = uptimeMs < 3_600_000
+            ? `${Math.floor(uptimeMs / 60_000)}m`
+            : `${(uptimeMs / 3_600_000).toFixed(1)}h`;
+        console.log(`  Session:      ${uptimeLabel}`);
+    }
+    console.log('');
+    console.log('── Activity ──────────────────────────────────');
+    const BAR_CHARS = '████████████████████';
+    const BAR_MAX = 8;
+    const bar = (count, max) => {
+        if (max === 0)
+            return '';
+        const filled = Math.max(1, Math.round((count / max) * BAR_MAX));
+        return BAR_CHARS.slice(0, filled);
+    };
+    const fmtTime = (ms) => ms < 60_000 ? `${Math.round(ms / 1000)}s ago`
+        : ms < 3_600_000 ? `${Math.floor(ms / 60_000)}m ago`
+            : `${(ms / 3_600_000).toFixed(1)}h ago`;
+    const lastSync = s.lastSync;
+    console.log('');
+    if (lastSync && lastSync.at) {
+        const syncRows = Object.entries(lastSync.eventTypes).sort(([, a], [, b]) => b - a);
+        const syncMax = syncRows[0]?.[1] ?? 0;
+        console.log(`📡 Last sync  (${fmtTime(Date.now() - lastSync.at)} — ${lastSync.eventCount} event${lastSync.eventCount !== 1 ? 's' : ''})`);
+        for (const [type, count] of syncRows) {
+            console.log(`  ${type.padEnd(20)} ${bar(count, syncMax).padEnd(BAR_MAX + 1)} ${count}`);
+        }
+    }
+    else {
+        console.log('📡 Last sync');
+        console.log('  No sync yet. Bridge will send on the next poll cycle.');
+    }
+    const counters = (s.counters ?? {});
+    const sessionEvents = counters.totalEvents ?? 0;
+    const sessionTypes = (counters.eventTypes ?? {});
+    const sessionRows = Object.entries(sessionTypes).sort(([, a], [, b]) => b - a);
+    const sessionMax = sessionRows[0]?.[1] ?? 0;
+    console.log('');
+    const sessionLabel = startedAt
+        ? `since restart ${fmtTime(Date.now() - startedAt)}`
+        : 'this session';
+    console.log(`📊 This session  (${sessionLabel} — ${sessionEvents} event${sessionEvents !== 1 ? 's' : ''})`);
+    if (sessionRows.length === 0) {
+        console.log('  No events recorded yet.');
+    }
+    else {
+        for (const [type, count] of sessionRows) {
+            console.log(`  ${type.padEnd(20)} ${bar(count, sessionMax).padEnd(BAR_MAX + 1)} ${count}`);
+        }
+    }
+    const totalRedactions = counters.totalRedactions ?? 0;
+    const redactionCategories = (counters.redactionCategories ?? {});
+    const redactionRows = Object.entries(redactionCategories).sort(([, a], [, b]) => b - a);
+    console.log('');
+    console.log(`🔒 Redactions  (${totalRedactions > 0 ? `${totalRedactions}x this session` : 'none this session'})`);
+    if (redactionRows.length === 0) {
+        console.log('  (none)');
+    }
+    else {
+        for (const [category, count] of redactionRows) {
+            console.log(`  ${`${category.toLowerCase()} data`.padEnd(24)} redacted ${count}x`);
+        }
+        console.log('  (original values never stored or transmitted)');
+    }
+}
 exports.default = {
     id: 'shield',
     name: 'OpenClaw Shield',
     register(api) {
-        // Wire up the Gateway logger as the log backend
         const gatewayAdapter = {
             debug(tag, msg, data) {
                 api.logger.debug(`[${tag}] ${msg}${data !== undefined ? ' ' + JSON.stringify(data) : ''}`);
@@ -123,250 +408,238 @@ exports.default = {
             },
         };
         (0, log_1.setAdapter)(gatewayAdapter);
-        const pluginConfig = (api.config ?? {});
-        const enabled = pluginConfig.enabled !== false;
-        if (!enabled) {
+        const pluginConfig = (api.pluginConfig ?? {});
+        log.debug('shield', 'Plugin config received', maskPluginConfigForLogs(pluginConfig));
+        if (pluginConfig.enabled === false) {
             log.info('shield', 'Monitoring disabled via config (enabled: false)');
             return;
         }
-        // Build credentials from plugin config + config.env fallback (no process.env mutation)
-        const credentials = (0, config_1.loadCredentialsFromPluginConfig)(pluginConfig);
-        if (!credentials.apiUrl || !credentials.hmacSecret) {
-            log.warn('shield', 'Not configured. Credentials can come from:');
-            log.warn('shield', '  1. Run setup wizard: npx shield-setup');
-            log.warn('shield', '  2. Set in plugins.entries.shield.config (openclaw.json)');
-            log.warn('shield', '  3. Set env vars: SHIELD_API_URL + SHIELD_HMAC_SECRET');
-            return;
-        }
-        const config = (0, config_1.loadConfig)({
-            credentials,
-            dryRun: typeof pluginConfig.dryRun === 'boolean' ? pluginConfig.dryRun : undefined,
-            redactionEnabled: typeof pluginConfig.redactionEnabled === 'boolean' ? pluginConfig.redactionEnabled : undefined,
-            pollIntervalMs: typeof pluginConfig.pollIntervalMs === 'number' ? pluginConfig.pollIntervalMs : undefined,
-            collectHostMetrics: typeof pluginConfig.collectHostMetrics === 'boolean' ? pluginConfig.collectHostMetrics : undefined,
-        });
-        log.info('shield', `Starting monitoring bridge v${version_1.VERSION} (poll: ${config.pollIntervalMs}ms, dryRun: ${config.dryRun})`);
-        // -----------------------------------------------------------------------
-        // RPC methods
-        // -----------------------------------------------------------------------
+        const installationKey = resolveInstallationKey(pluginConfig);
+        const dryRunVal = typeof pluginConfig.dryRun === 'boolean' ? pluginConfig.dryRun : undefined;
+        const redactionVal = typeof pluginConfig.redactionEnabled === 'boolean' ? pluginConfig.redactionEnabled : undefined;
+        const pollVal = typeof pluginConfig.pollIntervalMs === 'number' ? pluginConfig.pollIntervalMs : undefined;
+        const hostMetricsVal = typeof pluginConfig.collectHostMetrics === 'boolean' ? pluginConfig.collectHostMetrics : undefined;
         let pollFn = null;
-        api.registerGatewayMethod('shield.status', ({ respond }) => {
-            respond(true, {
-                running: state.running,
-                lastPollAt: state.lastPollAt,
-                eventsProcessed: state.eventsProcessed,
-                quarantineCount: state.quarantineCount,
-                consecutiveFailures: state.consecutiveFailures,
-                version: version_1.VERSION,
-            });
-        });
-        api.registerGatewayMethod('shield.flush', ({ respond }) => {
-            if (!pollFn) {
-                respond(false, { error: 'Bridge not started' });
-                return;
-            }
-            pollFn()
-                .then(() => respond(true, { flushed: true }))
-                .catch((err) => respond(false, { error: err instanceof Error ? err.message : String(err) }));
-        });
-        // -----------------------------------------------------------------------
-        // CLI commands
-        // -----------------------------------------------------------------------
-        api.registerCli(({ program }) => {
-            const shield = program.command('shield');
-            shield.command('status')
-                .description('Show Shield monitoring status')
-                .action(async () => {
-                // Prefer persisted state written by the daemon; fall back to local state
-                const s = readPersistedState() ?? state;
-                const lastPoll = s.lastPollAt ? new Date(s.lastPollAt).toISOString() : 'never';
-                const updatedAt = s.updatedAt ? `  (${Math.round((Date.now() - s.updatedAt) / 1000)}s ago)` : '';
-                console.log(`Shield v${s.version ?? version_1.VERSION}${updatedAt}`);
-                console.log(`  Running:    ${s.running}`);
-                console.log(`  Last poll:  ${lastPoll}`);
-                console.log(`  Events:     ${s.eventsProcessed}`);
-                console.log(`  Quarantine: ${s.quarantineCount}`);
-                console.log(`  Failures:   ${s.consecutiveFailures}`);
-                if (s.pid)
-                    console.log(`  Daemon PID: ${s.pid}`);
-            });
-            shield.command('flush')
-                .description('Trigger an immediate poll cycle')
-                .action(async () => {
-                if (!pollFn) {
-                    console.error('Bridge not started');
-                    return;
-                }
-                console.log('Flushing...');
-                await pollFn();
-                console.log('Done');
-            });
-        }, { commands: ['shield'] });
-        // -----------------------------------------------------------------------
-        // Register background service
-        // -----------------------------------------------------------------------
         let pollHandle = null;
         let telemetryHandle = null;
+        const startGuard = createStartGuard();
+        let onSignalHandler = null;
         api.registerService({
             id: 'shield-monitor',
             async start() {
-                const { fetchNewEntries, commitCursors } = await Promise.resolve().then(() => __importStar(require('./src/fetcher')));
-                const { transformEntries, generateHostTelemetry, resolveOpenClawVersion, resolveAgentLabel } = await Promise.resolve().then(() => __importStar(require('./src/transformer')));
-                const { sendEvents, reportInstance } = await Promise.resolve().then(() => __importStar(require('./src/sender')));
-                const { init: initRedactor, flush: flushRedactor, redactEvent } = await Promise.resolve().then(() => __importStar(require('./src/redactor')));
-                const { validate } = await Promise.resolve().then(() => __importStar(require('./src/validator')));
-                if (config.redactionEnabled)
-                    initRedactor();
-                state.running = true;
-                persistState(); // mark daemon as running immediately
-                // -- Telemetry --------------------------------------------------
-                const runTelemetry = async () => {
-                    if (!state.running)
-                        return;
-                    if (config.collectHostMetrics) {
-                        const hostEvent = generateHostTelemetry();
-                        if (hostEvent) {
-                            const batch = config.redactionEnabled
-                                ? [redactEvent(hostEvent)]
-                                : [hostEvent];
-                            const results = await sendEvents(batch, config);
-                            const ok = results.every(r => r.success);
-                            log.info('shield', `Host telemetry → Chronicle: success=${ok}`);
+                if (!startGuard.begin()) {
+                    log.debug('shield', 'Start requested while service is already started or in progress');
+                    return;
+                }
+                try {
+                    let credentials = (0, config_1.loadCredentials)();
+                    let validCreds = hasValidCredentials(credentials);
+                    if (!validCreds && installationKey) {
+                        log.info('shield', 'Installation key found — activating Shield (first-time setup)...');
+                        const autoCreds = await performAutoRegistration(installationKey);
+                        if (!autoCreds) {
+                            log.error('shield', 'Activation failed. Verify your Installation Key and try again.');
+                            startGuard.endFailure();
+                            return;
                         }
+                        log.info('shield', '✅ Shield activated! Starting monitoring bridge...');
+                        log.info('shield', `   Credentials saved to ${config_1.SHIELD_CONFIG_PATH}`);
+                        log.info('shield', '   Tip: you can remove installationKey from config after first activation.');
+                        credentials = autoCreds;
+                        validCreds = true;
                     }
-                    const instancePayload = {
-                        machine: {
-                            hostname: config.hostname,
-                            os: process.platform,
-                            arch: process.arch,
-                            node_version: process.version,
-                        },
-                        software: {
-                            plugin_version: version_1.VERSION,
-                            openclaw_version: resolveOpenClawVersion(),
-                            agent_label: resolveAgentLabel('main'),
-                        },
-                    };
-                    const ok = await reportInstance(instancePayload, config.credentials);
-                    log.info('shield', `Instance report → Platform: success=${ok}`);
-                };
-                runTelemetry().catch((err) => log.error('shield', `Telemetry error: ${err instanceof Error ? err.message : String(err)}`));
-                telemetryHandle = setInterval(() => {
-                    runTelemetry().catch((err) => log.error('shield', `Telemetry error: ${err instanceof Error ? err.message : String(err)}`));
-                }, TELEMETRY_INTERVAL_MS);
-                // -- Poll -------------------------------------------------------
-                const poll = async () => {
-                    if (!state.running)
+                    if (!validCreds) {
+                        log.warn('shield', 'Shield is not activated.');
+                        log.warn('shield', '  Activate via CLI:  openclaw shield activate <YOUR_KEY>');
+                        log.warn('shield', '  Or set plugins.entries.shield.config.installationKey in openclaw.json and restart.');
+                        log.warn('shield', '  Get your key at: https://uss.upx.com → APPS → OpenClaw Shield');
+                        startGuard.endFailure();
                         return;
-                    try {
-                        const entries = await fetchNewEntries(config);
-                        if (entries.length === 0) {
-                            // Still commit cursors so initCursorsForDir positions
-                            // (set to current file sizes) are persisted on disk.
-                            // Without this, each poll re-initialises cursors to the
-                            // NEW file size and silently skips events between polls.
-                            commitCursors(config, []);
-                            state.consecutiveFailures = 0;
+                    }
+                    state.activated = true;
+                    state.startedAt = Date.now();
+                    const config = (0, config_1.loadConfig)({
+                        credentials,
+                        dryRun: dryRunVal,
+                        redactionEnabled: redactionVal,
+                        pollIntervalMs: pollVal,
+                        collectHostMetrics: hostMetricsVal,
+                    });
+                    state.instanceId = config.credentials.instanceId ?? '';
+                    const persistedStats = readAllTimeStats();
+                    if (persistedStats.lastSync)
+                        state.lastSync = persistedStats.lastSync;
+                    log.info('shield', `Starting monitoring bridge v${version_1.VERSION} (poll: ${config.pollIntervalMs}ms, dryRun: ${config.dryRun})`);
+                    const { fetchNewEntries, commitCursors } = await Promise.resolve().then(() => __importStar(require('./src/fetcher')));
+                    const { transformEntries, generateHostTelemetry, resolveOpenClawVersion, resolveAgentLabel } = await Promise.resolve().then(() => __importStar(require('./src/transformer')));
+                    const { sendEvents, reportInstance } = await Promise.resolve().then(() => __importStar(require('./src/sender')));
+                    const { init: initRedactor, flush: flushRedactor, redactEvent } = await Promise.resolve().then(() => __importStar(require('./src/redactor')));
+                    const { validate } = await Promise.resolve().then(() => __importStar(require('./src/validator')));
+                    if (config.redactionEnabled)
+                        initRedactor();
+                    state.running = true;
+                    persistState();
+                    const runTelemetry = async () => {
+                        if (!state.running)
+                            return;
+                        const hostSnapshot = config.collectHostMetrics ? generateHostTelemetry() : null;
+                        const hostMeta = hostSnapshot?.event?.tool_metadata;
+                        const instancePayload = {
+                            machine: {
+                                hostname: config.hostname,
+                                os: process.platform,
+                                arch: process.arch,
+                                node_version: process.version,
+                            },
+                            software: {
+                                plugin_version: version_1.VERSION,
+                                openclaw_version: resolveOpenClawVersion(),
+                                agent_label: resolveAgentLabel('main'),
+                                ...(hostMeta && {
+                                    gateway_bind: hostMeta['openclaw.gateway_bind'],
+                                    webhook_configured: hostMeta['openclaw.webhook_configured'],
+                                    browser_auth_required: hostMeta['openclaw.browser_auth_required'],
+                                }),
+                            },
+                        };
+                        const result = await reportInstance(instancePayload, config.credentials);
+                        log.info('shield', `Instance report → Platform: success=${result.ok}`);
+                    };
+                    const runTelemetrySingleflight = createSingleflightRunner(runTelemetry);
+                    runTelemetrySingleflight().catch((err) => log.error('shield', `Telemetry error: ${err instanceof Error ? err.message : String(err)}`));
+                    telemetryHandle = setInterval(() => {
+                        runTelemetrySingleflight().catch((err) => log.error('shield', `Telemetry error: ${err instanceof Error ? err.message : String(err)}`));
+                    }, TELEMETRY_INTERVAL_MS);
+                    const poll = async () => {
+                        if (!state.running)
+                            return;
+                        try {
+                            const entries = await fetchNewEntries(config);
+                            if (entries.length === 0) {
+                                commitCursors(config, []);
+                                state.consecutiveFailures = 0;
+                                state.lastPollAt = Date.now();
+                                markStateDirty();
+                                persistState();
+                                return;
+                            }
+                            let envelopes = transformEntries(entries);
+                            const { valid: validEvents, quarantined } = validate(envelopes.map(e => e.event));
+                            if (quarantined > 0) {
+                                state.quarantineCount += quarantined;
+                                markStateDirty();
+                                writeAllTimeStats({ quarantineCount: quarantined });
+                                log.warn('shield', `${quarantined} events quarantined (see ~/.openclaw/shield/data/quarantine.jsonl)`);
+                            }
+                            envelopes = envelopes.filter(e => validEvents.includes(e.event));
+                            if (config.redactionEnabled) {
+                                envelopes = envelopes.map(e => redactEvent(e));
+                            }
+                            const results = await sendEvents(envelopes, config);
+                            const needsReg = results.some(r => r.needsRegistration);
+                            if (needsReg) {
+                                log.error('shield', 'Instance not registered on platform — Shield deactivated.');
+                                state.running = false;
+                                markStateDirty();
+                                return;
+                            }
+                            const pending = results.find(r => r.pendingNamespace);
+                            if (pending) {
+                                const waitMs = Math.min(pending.retryAfterMs ?? 300_000, MAX_BACKOFF_MS);
+                                log.warn('shield', `Namespace allocation in progress — holding events, backing off ${Math.round(waitMs / 1000)}s`);
+                                state.lastPollAt = Date.now();
+                                markStateDirty();
+                                persistState();
+                                await new Promise(r => setTimeout(r, waitMs));
+                                return;
+                            }
+                            const accepted = results.reduce((sum, r) => sum + (r.success ? r.eventCount : 0), 0);
+                            if (accepted > 0) {
+                                commitCursors(config, entries);
+                                flushRedactor();
+                                state.eventsProcessed += accepted;
+                                state.consecutiveFailures = 0;
+                                markStateDirty();
+                                const syncEventTypes = {};
+                                for (const env of envelopes) {
+                                    const t = env.event.tool_category ?? 'UNKNOWN';
+                                    syncEventTypes[t] = (syncEventTypes[t] ?? 0) + 1;
+                                }
+                                const lastSync = { at: Date.now(), eventCount: accepted, eventTypes: syncEventTypes };
+                                state.lastSync = lastSync;
+                                writeAllTimeStats({ eventsProcessed: accepted, lastSync });
+                            }
+                            else {
+                                state.consecutiveFailures++;
+                                markStateDirty();
+                            }
                             state.lastPollAt = Date.now();
+                            markStateDirty();
                             persistState();
-                            return;
                         }
-                        let envelopes = transformEntries(entries);
-                        const { valid: validEvents, quarantined } = validate(envelopes.map(e => e.event));
-                        if (quarantined > 0) {
-                            state.quarantineCount += quarantined;
-                            log.warn('shield', `${quarantined} events quarantined (see ~/.openclaw/shield/data/quarantine.jsonl)`);
-                        }
-                        envelopes = envelopes.filter(e => validEvents.includes(e.event));
-                        if (config.redactionEnabled) {
-                            envelopes = envelopes.map(e => redactEvent(e));
+                        catch (err) {
+                            state.consecutiveFailures++;
+                            markStateDirty();
+                            log.error('shield', `Poll error: ${err instanceof Error ? err.message : String(err)}`);
                         }
-                        const results = await sendEvents(envelopes, config);
-                        // 403 needs_registration → self-halt cleanly (no point retrying)
-                        const needsReg = results.some(r => r.needsRegistration);
-                        if (needsReg) {
-                            log.error('shield', 'Instance not registered on platform — Shield deactivated. Re-run: npx shield-setup');
-                            state.running = false;
+                    };
+                    const runPollSingleflight = createSingleflightRunner(poll);
+                    pollFn = runPollSingleflight;
+                    await runPollSingleflight();
+                    const schedulePoll = () => {
+                        if (!state.running)
                             return;
+                        const interval = getBackoffInterval(config.pollIntervalMs);
+                        if (interval !== config.pollIntervalMs) {
+                            log.warn('shield', `Backing off: next poll in ${Math.round(interval / 1000)}s (${state.consecutiveFailures} consecutive failures)`);
                         }
-                        // 202 pending_namespace → hold cursors, don't count as failure, use retry_after
-                        const pending = results.find(r => r.pendingNamespace);
-                        if (pending) {
-                            const waitMs = pending.retryAfterMs ?? 300_000;
-                            log.warn('shield', `Namespace allocation in progress — holding events, backing off ${Math.round(waitMs / 1000)}s`);
-                            state.lastPollAt = Date.now();
-                            persistState();
-                            // Override next poll interval by sleeping here (schedulePoll will use normal backoff after)
-                            await new Promise(r => setTimeout(r, waitMs));
+                        pollHandle = setTimeout(() => {
+                            runPollSingleflight().catch((err) => {
+                                state.consecutiveFailures++;
+                                log.error('shield', `Poll error (unhandled): ${err instanceof Error ? err.message : String(err)}`);
+                            }).finally(() => {
+                                schedulePoll();
+                            });
+                        }, interval);
+                    };
+                    schedulePoll();
+                    onSignalHandler = async () => {
+                        if (!state.running)
                             return;
+                        state.running = false;
+                        startGuard.reset();
+                        markStateDirty();
+                        persistState();
+                        if (pollHandle) {
+                            clearTimeout(pollHandle);
+                            pollHandle = null;
                         }
-                        const accepted = results.reduce((sum, r) => sum + (r.success ? r.eventCount : 0), 0);
-                        if (accepted > 0) {
-                            commitCursors(config, entries);
-                            flushRedactor();
-                            state.eventsProcessed += accepted;
-                            state.consecutiveFailures = 0;
+                        if (telemetryHandle) {
+                            clearInterval(telemetryHandle);
+                            telemetryHandle = null;
                         }
-                        else {
-                            state.consecutiveFailures++;
+                        try {
+                            const { flush: fr } = await Promise.resolve().then(() => __importStar(require('./src/redactor')));
+                            fr();
                         }
-                        state.lastPollAt = Date.now();
-                        persistState();
-                    }
-                    catch (err) {
-                        state.consecutiveFailures++;
-                        log.error('shield', `Poll error: ${err instanceof Error ? err.message : String(err)}`);
-                    }
-                };
-                pollFn = poll;
-                await poll();
-                const schedulePoll = () => {
-                    if (!state.running)
-                        return;
-                    const interval = getBackoffInterval(config.pollIntervalMs);
-                    if (interval !== config.pollIntervalMs) {
-                        log.warn('shield', `Backing off: next poll in ${Math.round(interval / 1000)}s (${state.consecutiveFailures} consecutive failures)`);
-                    }
-                    pollHandle = setTimeout(() => {
-                        poll().catch((err) => {
-                            state.consecutiveFailures++;
-                            log.error('shield', `Poll error (unhandled): ${err instanceof Error ? err.message : String(err)}`);
-                        }).finally(() => {
-                            schedulePoll();
-                        });
-                    }, interval);
-                };
-                schedulePoll();
-                // ── Graceful shutdown on process signals ──────────────────────────
-                // Handles SIGTERM (gateway graceful stop) and SIGINT (Ctrl-C / dev).
-                // Uses once() so the handler self-removes after first signal.
-                const onSignal = async () => {
-                    if (!state.running)
-                        return; // already stopped
-                    state.running = false;
-                    persistState();
-                    if (pollHandle) {
-                        clearTimeout(pollHandle);
-                        pollHandle = null;
-                    }
-                    if (telemetryHandle) {
-                        clearInterval(telemetryHandle);
-                        telemetryHandle = null;
-                    }
-                    try {
-                        const { flush: fr } = await Promise.resolve().then(() => __importStar(require('./src/redactor')));
-                        fr();
-                    }
-                    catch { }
-                    log.info('shield', 'Service stopped (signal)');
-                };
-                process.once('SIGTERM', onSignal);
-                process.once('SIGINT', onSignal);
+                        catch { }
+                        log.info('shield', 'Service stopped (signal)');
+                    };
+                    process.once('SIGTERM', onSignalHandler);
+                    process.once('SIGINT', onSignalHandler);
+                    startGuard.endSuccess();
+                }
+                catch (err) {
+                    startGuard.endFailure();
+                    throw err;
+                }
             },
             async stop() {
                 if (!state.running)
-                    return; // already stopped by signal handler
+                    return;
                 state.running = false;
+                startGuard.reset();
+                markStateDirty();
                 persistState();
                 if (pollHandle) {
                     clearTimeout(pollHandle);
@@ -376,13 +649,88 @@ exports.default = {
                     clearInterval(telemetryHandle);
                     telemetryHandle = null;
                 }
+                if (onSignalHandler) {
+                    process.off('SIGTERM', onSignalHandler);
+                    process.off('SIGINT', onSignalHandler);
+                    onSignalHandler = null;
+                }
                 try {
                     const { flush: flushRedactor } = await Promise.resolve().then(() => __importStar(require('./src/redactor')));
                     flushRedactor();
                 }
-                catch { /* ignore if module not loaded */ }
+                catch { }
                 log.info('shield', 'Service stopped');
             },
         });
+        api.registerGatewayMethod('shield.status', ({ respond }) => {
+            const creds = (0, config_1.loadCredentials)();
+            const activated = state.activated || hasValidCredentials(creds);
+            respond(true, {
+                activated,
+                running: state.running,
+                lastPollAt: state.lastPollAt,
+                eventsProcessed: state.eventsProcessed,
+                quarantineCount: state.quarantineCount,
+                consecutiveFailures: state.consecutiveFailures,
+                version: version_1.VERSION,
+            });
+        });
+        api.registerGatewayMethod('shield.flush', ({ respond }) => {
+            if (!pollFn) {
+                respond(false, { error: 'Bridge not started' });
+                return;
+            }
+            pollFn()
+                .then(() => respond(true, { flushed: true }))
+                .catch((err) => respond(false, { error: err instanceof Error ? err.message : String(err) }));
+        });
+        api.registerCli(({ program }) => {
+            const shield = program.command('shield');
+            shield.command('status')
+                .description('Show Shield monitoring status and activity')
+                .action(async () => {
+                const creds = (0, config_1.loadCredentials)();
+                const activated = hasValidCredentials(creds);
+                if (!activated) {
+                    printNotActivatedStatus();
+                }
+                else {
+                    printActivatedStatus();
+                }
+            });
+            shield.command('flush')
+                .description('Trigger an immediate poll cycle')
+                .action(async () => {
+                if (!pollFn) {
+                    console.error('Bridge not started');
+                    return;
+                }
+                console.log('Flushing...');
+                await pollFn();
+                console.log('Done');
+            });
+            shield.command('activate')
+                .description('Activate Shield with an Installation Key')
+                .argument('<key>', 'Installation Key from the Shield portal')
+                .action(async (key) => {
+                if (state.activated) {
+                    console.log('Shield is already activated.');
+                    return;
+                }
+                console.log('Activating Shield...');
+                const creds = await performAutoRegistration(key.trim());
+                if (creds) {
+                    console.log('');
+                    console.log('✅ Shield activated! Credentials saved.');
+                    console.log('   Restart the gateway to start monitoring:');
+                    console.log('     openclaw gateway restart');
+                }
+                else {
+                    console.error('');
+                    console.error('❌ Activation failed. Verify your Installation Key and try again.');
+                    console.error('   Get your key at: https://uss.upx.com → APPS → OpenClaw Shield');
+                }
+            });
+        }, { commands: ['shield'] });
     },
 };