NerveSynapse

NerveSynapse is the intake layer for connecting external systems to a NerveOS System.

Why It Exists

Most systems do not speak NCP yet. Firebase Cloud Monitoring alerts, GitHub security alerts, Stripe billing events, and custom webhooks all have their own payload shapes. NerveSynapse receives those events and NerveBridge converts them into NCP triggers.

If a system already speaks NCP, it can send a valid trigger through NerveSynapse for validation, audit, and routing without conversion.

Firebase Example

A Firebase project can send a raw Cloud Monitoring alert to a tenant-specific NerveSynapse endpoint. The Firebase adapter maps alerts to signals such as firebase.hosting.traffic_spike, firebase.billing.cost_overrun, and ncplabs.signup.created.

POST /api/synapse/{workspaceId}/firebase/monitoring

Modern integrations should use a scoped NCP connection token:

POST /api/synapse/{workspaceId}/custom/webhook
Authorization: Bearer ncp_live_...
X-NCP-Timestamp: 2026-05-31T18:00:00Z
X-NCP-Signature: sha256=base64url(hmac_sha256(token, timestamp + "." + raw_body))
X-NCP-Event-Id: evt_summitos_rainier_window_001
Content-Type: application/json

NCP Auth v0.1 uses bearer tokens as the base profile and signed payload headers as the recommended production profile. Basic auth remains available for older webhook providers, but NCP-native apps should use scoped bearer tokens that can be rotated and revoked per app, expedition, project, or workflow.

NCP Auth v0.1

• Authorization: required bearer token for NCP-native apps.
• X-NCP-Timestamp: ISO timestamp used in the signature base string.
• X-NCP-Signature: HMAC-SHA256 over timestamp.raw_body, encoded base64url and prefixed with sha256=.
• X-NCP-Event-Id: stable event ID for replay protection and idempotency.
• Receivers should reject stale timestamps, invalid signatures, inactive tokens, and duplicate event IDs.

Connection UX

A NerveOS System should show connections in human terms: app name, source system, audience, environment, allowed event types, last used time, and a clear disconnect control.

Example: SummitOS Rainier Expedition can send expedition.weather_window and expedition.readiness_changed from summitos.com to the Rainier expedition audience. Disconnecting the token stops that app from firing future signals.

{
  "project_id": "ncplabs",
  "site": "ncplabs.com",
  "signal_type": "firebase.billing.cost_overrun",
  "summary": "Firebase spend crossed the configured NCP Labs budget threshold.",
  "current_spend": 128,
  "threshold": 100,
  "currency": "USD",
  "incident_url": "https://console.firebase.google.com/project/ncplabs/usage"
}

Receiver Responsibilities

• Verify the source using a signing secret, token, or platform identity.
• Resolve the destination workspace and NerveOS System.
• Redact sensitive raw payload fields before audit logging.
• Convert raw alerts into valid NCP triggers when needed.
• Persist the event, trigger, validation result, and audit entry.
• Hand the trigger to NerveOS System for policy and routing.