@upx-us/shield 0.2.15-beta → 0.2.16-beta

package/dist/index.js

@@ -282,6 +282,24 @@ exports.default = {
                             envelopes = envelopes.map(e => redactEvent(e));
                         }
                         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;
+                            return;
+                        }
+                        // 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));
+                            return;
+                        }
                         const accepted = results.reduce((sum, r) => sum + (r.success ? r.eventCount : 0), 0);
                         if (accepted > 0) {
                             commitCursors(config, entries);

package/dist/src/sender.d.ts

@@ -15,6 +15,11 @@ export interface SendResult {
     statusCode?: number;
     body?: string;
     eventCount: number;
+    /** True when Cloud Run returns 202 pending_namespace — hold cursors, backoff retry_after */
+    pendingNamespace?: boolean;
+    retryAfterMs?: number;
+    /** True when Cloud Run returns 403 needs_registration — plugin must self-halt */
+    needsRegistration?: boolean;
 }
 export declare function sendEvents(events: EnvelopeEvent[], config: Config): Promise<SendResult[]>;
 /**

package/dist/src/sender.js

@@ -115,7 +115,8 @@ async function sendEvents(events, config) {
                     method: 'POST',
                     headers: {
                         'Content-Type': 'application/json',
-                        'X-Shield-Instance-Id': instanceId,
+                        'X-Shield-Instance-Id': instanceId, // legacy name
+                        'X-Shield-Fingerprint': instanceId, // canonical name
                         'X-Shield-Nonce': nonce,
                         'X-Shield-Signature': signature,
                         'X-Shield-Version': version_1.VERSION,
@@ -125,10 +126,37 @@ async function sendEvents(events, config) {
                 });
                 const data = await res.text();
                 log.info('sender', `Batch ${batchNum}: ${batch.length} events (HTTP ${res.status})`);
-                if (res.ok) {
+                if (res.ok && res.status === 200) {
                     results.push({ success: true, statusCode: res.status, body: data, eventCount: batch.length });
                     break;
                 }
+                // 202 pending_namespace — namespace not yet allocated by SIEM.
+                // Events must NOT be committed; plugin should hold and retry after retry_after.
+                if (res.status === 202) {
+                    let retryAfterMs = 300_000; // default 5 min
+                    try {
+                        retryAfterMs = (JSON.parse(data).retry_after ?? 300) * 1000;
+                    }
+                    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 });
+                    break;
+                }
+                // 403 needs_registration — instance unknown or inactive, plugin must self-halt.
+                if (res.status === 403) {
+                    let needsReg = false;
+                    try {
+                        needsReg = JSON.parse(data).needs_registration === true;
+                    }
+                    catch { }
+                    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 });
+                        break;
+                    }
+                }
                 if (res.status >= 500 && attempt === 0) {
                     log.warn('sender', `Batch ${batchNum} attempt ${attempt + 1} — HTTP ${res.status}, retrying...`);
                     continue;
@@ -170,7 +198,8 @@ async function reportInstance(payload, credentials) {
             method: 'PUT',
             headers: {
                 'Content-Type': 'application/json',
-                'X-Shield-Instance-Id': instanceId,
+                'X-Shield-Instance-Id': instanceId, // legacy
+                'X-Shield-Fingerprint': instanceId, // canonical
                 'X-Shield-Nonce': nonce,
                 'X-Shield-Signature': signature,
                 'X-Shield-Version': version_1.VERSION,

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.2.15-beta",
+  "version": "0.2.16-beta",
   "skills": [
     "./skills"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upx-us/shield",
-  "version": "0.2.15-beta",
+  "version": "0.2.16-beta",
   "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",