Universal Coverage Gateway

Customer-owned Gateway quickstart

The default Hosted path installs and starts the reference Gateway beside the Agent, inside the customer environment. One browser approval creates a bounded project credential and stores it in the user's Witnora credential directory, not in the Agent repository.

npx witnora@latest onboard --project <project-id>

After onboarding, run the Agent's normal sandbox workflow. The managed Gateway stays in the background. Inspect or control it with gateway status, logs, restart, and stop. The foreground gateway run command is reserved for Advanced debugging and manual deployments.

The generated .witnora/gateway/gateway.json is metadata-only. Local secrets.json, the durable queue, and source-signing keys are gitignored. Route one sandbox event path to the local Gateway only after gateway doctor reports READY_TO_RECORD.

Onboarding also writes .witnora/gateway/client.mjs. Import that client at one meaningful sandbox workflow boundary:

import { randomUUID } from "node:crypto";
import { witnoraGateway } from "./.witnora/gateway/client.mjs";

const runId = randomUUID();
await witnoraGateway.start(runId, { workflow: "sandbox-workflow" });
try {
  const result = await runExistingSandboxWorkflow();
  await witnoraGateway.event(runId, "workflow.step.completed", { step: "meaningful-boundary" });
  await witnoraGateway.complete(runId, { status: "completed" });
  return result;
} catch (error) {
  await witnoraGateway.event(runId, "workflow.failed", { errorType: error?.name ?? "Error" });
  await witnoraGateway.complete(runId, { status: "failed" });
  throw error;
}

This client sends only metadata the customer explicitly supplies. It reads the local Gateway token from the gitignored setup directory. It never receives the Hosted credential, source-signing private key, sandbox write credential, or outcome-probe credential.

This reference path establishes RECORDED evidence: durable queueing, strict sequence and hash links, customer source signatures, replay, heartbeat, and Hosted reconciliation. It does not by itself establish complete mediation. To reach ENFORCED, remove the target write credential from the Agent and place it behind a controlled execution adapter. To reach OUTCOME VERIFIED, give a separate read-only credential to an independent outcome probe. Neither credential is sent to Witnora Hosted.

The Universal Coverage Gateway is the long-running integration boundary for Witnora. It sits around tool execution, discovers capabilities locally, applies fail-closed policy to new side effects, and emits bounded semantic evidence. It does not require product-specific code in Witnora.

agent or workflow
       |
       v
universal gateway ---- unknown capability ----> pending review (denied)
       |
       +---- read-only capability ------------> execute + observe
       |
       +---- side effect ----------------------> Hosted action decision
                                                    |
                                  allow / approval required / deny

Supported boundaries

ordinary TypeScript tool calls with wrapTool();
MCP tools with wrapMcpTool() or WitnoraMcpCoverageMiddleware;
HTTP/tool-calling clients with wrapFetch();
browser actions with wrapBrowserAction();
coding actions with wrapCodingAction().

These wrappers share one capability registry and one decision contract. A customer-specific adapter may translate a framework callback into this contract, but it must not add customer-specific policy to Witnora.

Runtime context registration

Witnora clients and generated adapters declare Agent ID, observed version, framework, and canonical environment with each run. Hosted creates the Agent record on first observation and associates subsequent runs by stable ID. The version can advance automatically; allowed capabilities and permissions cannot.

The Workspace context bar is therefore derived from received evidence. Agent and Environment selectors filter the four assurance surfaces without requiring a parallel manually maintained inventory. Missing deployment signals default to sandbox; a client must provide an explicit or recognized production signal before evidence is labeled production.

Discovery and review

Discovery uses, in order:

an explicit versioned capability manifest;
an exact capability ID or known tool alias;
a bounded multi-word signal from the local description or input schema;
transport metadata, for example HTTP method semantics.

Ambiguous tools remain unknown. New unknown capabilities are pending and execution is denied. An approval must bind the discovered key to a full capability manifest and include a reason. A tool-name allowlist is not an approval mechanism.

Recognized reads may run in observe-only mode. Recognized writes, sends, submissions, payments, destructive commands, and other side effects require a Hosted action decision or an explicit local policy. Runtime approval and policy decisions keep the Hosted action ID in the event chain.

Privacy modes

metadata_only is the default:

raw arguments and results are never uploaded;
resource IDs and HTTP query strings are omitted;
dynamic HTTP path segments are replaced by :id;
events retain tool name, transport, schema presence, shape, size, decision, capability, and timing metadata.

redacted_digest additionally hashes locally redacted arguments, results, resource IDs, and input schemas. Keys resembling credentials, tokens, authorization headers, cookies, passwords, or API keys are removed before hashing. Digests support equality and reconciliation; they do not reveal the source values.

Evidence strength and coverage

The Gateway never treats every event as equally trustworthy:

in_process wrappers establish reported evidence;
a customer-owned signed collector can establish recorded evidence;
a credential-isolated adapter backed by a Hosted action decision can establish enforced evidence;
an independent outcome probe is required for outcome_verified evidence;
independent review remains a separate human or institutional claim.

Hosted computes:

observed coverage: received invocations relative to received plus declared dropped events;
understood coverage: invocations mapped to a reviewed manifest;
enforced coverage: side effects correlated to controlled Action records;
verified coverage: side effects with independently observed outcomes.

Denied and pending proposals are visible policy attempts, not successful executions. Uninstrumented or bypassed paths remain outside measured coverage.

Integration contract

Use the generated .witnora/gateway/client.mjs shown above at one meaningful sandbox boundary. The managed Gateway polls the project registry with a bounded cache and records human capability corrections before later calls can execute. Classification does not authorize a side effect: the reviewed capability still follows the normal action policy and approval path.

Generic dogfood fixture

examples/universal-coverage-gateway/sellershield-tool-schema.json is a customer-shaped compatibility fixture. It proves that commerce workflow tool schemas pass through the generic discovery and fail-closed policy path. There are no SellerShield conditionals in the SDK, MCP middleware, Hosted API, or dashboard.

Non-claims

Installing an in-process wrapper does not prove complete mediation.
Auto-discovery does not authorize an action.
Metadata-only evidence does not prove the business outcome.
A capability manifest does not prove least privilege.
Coverage applies only to declared and instrumented action paths.

For stronger boundaries, use the customer-owned collector gateway, Action Assurance Protocol, and an independent outcome probe.