witnora

Customer-owned Remote Collector and Gateway v0.2

The customer-owned collector gateway runs beside an agent, not inside the Witnora hosted service. It owns the source signing key, local append-only queue, and Hosted API credential. The agent receives only a local gateway token.

Trust boundary

agent process
  | local authenticated event intent
  v
customer-owned gateway
  | fsync -> sequence -> hash link -> Ed25519 source signature
  | durable retry + signed heartbeat
  v
Witnora hosted control plane
  | verify source key -> replay check -> reconcile receipt
  v
Witnora server attestation

The source private key and WITNORA_API_KEY never appear in an event, receipt, ACK, or gateway response. The hosted service stores only the public source key and its SHA-256 fingerprint. Key rotation retires the previous key; existing runs may finish and replay with their original key, but a retired key cannot start a new run.

Install the managed Gateway

npx witnora@latest onboard --project your-project-id

Onboarding creates the restricted credential, installs and starts the Gateway, and keeps its queue, source-signing key, and local token under the gitignored .witnora directory. The Agent receives only the generated local Gateway client; it never receives the Hosted credential or signing key.

The local protocol is intentionally small:

POST /v1/runs/{runId}/start
POST /v1/runs/{runId}/events
POST /v1/runs/{runId}/drops
POST /v1/runs/{runId}/complete
POST /v1/flush
GET  /healthz

Every mutating request requires Authorization: Bearer $WITNORA_GATEWAY_TOKEN. Event requests require an idempotency key. Reusing the key with identical content returns the original signed record; different content returns HTTP 409.

Failure and recovery

• A local request succeeds only after the signed record is appended and fsynced.
• Hosted delivery is at least once. The local ACK advances only after the server accepts the exact sequence and event hash.
• Network failures leave records pending. Startup discovers existing journals, replays them, and then retries receipt reconciliation.
• A known local loss is represented by EVENTS_DROPPED plus an explicit sequence gap. The server opens a deduplicated incident.
• Heartbeats report pending count and last ACK. A stale heartbeat is observable through GET /v1/projects/{projectId}/collector-status.

Check the installed Gateway before routing a real sandbox workflow through it:

npx witnora@latest gateway doctor

Evidence strength and non-claims

A source-signed gateway journal can support recorded: Witnora can prove which bytes the customer collector signed, their order, and whether the hosted copy reconciles. It cannot prove that every real-world action passed through the collector.

For enforced, keep target-system write credentials outside the agent and use the Onegent controlled action adapter plus an immutable mandate. For outcome_verified, use an independent read credential and outcome probe. A network policy should prevent the agent container from reaching the target write API directly. Hash linking detects mutation and omission in the collected chain; it cannot detect an action performed entirely outside the gateway.

The stable remote-collector schema remains the interoperability contract for independent Gateway implementations.

This site is open source. Improve this page.