Bellona remote gateway walking skeleton for Phase 180.
This walking skeleton exposes process and HTTP readiness primitives, host WebSocket registration, a protocol-valid device registry, an internal command dispatcher, session lifecycle manager, hash-chained audit log, approval store, one-time pairing code manager, timeline query service, and in-memory telemetry recorder. The default runtime remains ephemeral for tests and development, but the gateway can opt into a first-stage atomic JSON store for devices, sessions, command dispatches/events, pairing codes, artifact metadata, approval requests and decisions, and audit entries.
The gateway owns a remote device registry for early host/session work. Every
registry write is validated with @bellona/remote-protocol
RemoteDeviceSchema; when first-stage persistence is configured, the same
validated snapshots are written through the gateway persistent store.
Endpoints#
GET /healthGET /v1/healthGET /readyGET /v1/readyGET /v1/artifactsPOST /v1/artifactsGET /v1/approvalsPOST /v1/approvals/:requestId/decisionsGET /v1/devicesGET /v1/timelinePOST /v1/pairing/exchangeWS /v1/hosts/connect
Host WebSocket clients must send a first message shaped as this abridged example:
{
"type": "host.handshake",
"authentication": {
"scheme": "bellona-host-token-v1",
"deviceKeyId": "device-key:example-development",
"token": "bellona-host-token-v1.<payload>.<signature>"
},
"protocolVersion": "0.1.0",
"supportedProtocolVersions": ["0.1.0"],
"device": {
"id": "device:example"
}
}
The device payload must be a complete RemoteDevice report from
@bellona/remote-protocol. The authentication payload must contain a
gateway-signed host token issued during pairing. Invalid handshakes, missing
tokens, expired tokens, mismatched device ids, and invalid signatures are closed
with WebSocket policy code 1008.
Device inventory is available through GET /v1/devices. The endpoint returns
the validated device registry snapshots currently known to the gateway,
including host-sourced permission diagnostics such as macOS Screen Recording and
Accessibility state. Those permission records are also the policy input used to
deny or require approval before desktop fallback commands reach a host.
Gateway-dispatched commands are sent to the connected host as command.dispatch
messages containing a protocol-valid RemoteCommandEnvelope. Duplicate
idempotency keys replay the first gateway dispatch record and do not send
another host message.
Before dispatch, the gateway evaluates the command with the shared
@bellona/remote-protocol permission policy. The evaluator combines the
advertised device capability scopes with inferred high-risk scopes for
observe-only streaming, project writes, desktop control, real or isolated
browser profiles, arbitrary code, shell execution, destructive commands,
publishing, and financial actions. Commands that are not advertised by the host,
target blocked adapters or capabilities, miss required permissions, have denied
or expired permissions, or require approval are rejected before any host message
is sent. Rejections emit policy.denied audit entries and
remote_gateway.command.failed telemetry.
After dispatch, connected hosts can send command.progress, command.result,
and command.error messages back over the same WebSocket. The gateway validates
those messages with @bellona/remote-protocol result schemas and routes them to
the dispatching client id recorded by the internal command dispatcher.
Session lifecycle state is managed through internal service methods on
app.sessionLifecycle. The in-memory manager validates every returned
RemoteSession, supports start, pause, resume, stop, takeover request, and
takeover grant transitions, and records protocol-valid lifecycle events for each
transition.
Basic audit emission is available through app.auditLog. The gateway emits
hash-chained RemoteAuditEntry records for pairing completion, device
revocation, command receipt, command dispatch with policy decision metadata,
policy denial, approval request/decision, host command results or errors, and
session stop events. Command-related audit metadata is normalized with
correlationId, sessionId, commandId, actorParticipantId, deviceId,
stable commandHash and resultHash values, and policy decision fields where
available. Every audit entry must carry a protocol-valid RemoteActorChain;
audit metadata also records the chain id, root actor id, terminal actor id,
actor ids, stable actor ids, and actor kinds so delegated human, orchestrator,
specialist, and adapter attribution remains queryable after export. For
dispatched commands, the gateway reserves the target host connection and writes
the command.dispatched audit entry before sending the host WebSocket message,
so a dispatch-audit store failure blocks mutating adapter work before it reaches
the host.
Audit-store outages are fail-closed for command execution. If the gateway cannot
write the initial command.received audit entry, it blocks every command except
explicitly safe host diagnostics advertised through the diagnostic adapter:
agent.readiness and state.snapshot. Those diagnostics must remain read-only,
require no approval or dry-run, use only device.read, adapter.inspect, and
command.execute.readonly scopes, and be backed by an available diagnostic
adapter/capability. Repeated audit write failures during that degraded
diagnostic path are logged and counted, but do not prevent the diagnostic result
from routing back to the client.
Ordered timeline reads are available through app.timeline.queryTimeline() and
GET /v1/timeline. The query service merges session lifecycle events, command
progress/result/error client events, approval requests and decisions, registered
artifact metadata, and audit-backed stream events into a single
timestamp-ordered result. The HTTP endpoint accepts sessionId, commandId,
deviceId, actorParticipantId, streamId, artifactId, approvalRequestId,
repeated or comma-separated kind and type filters, after, before,
limit, and offset query parameters. Timeline events are returned with
kind, type, source, occurredAt, correlation identifiers,
evidence/artifact references, and normalized metadata. Until a dedicated stream
store is added in later tasks, stream events are derived from
evidence.captured audit entries that carry streamId metadata.
Artifact metadata registration is available through app.artifactRegistry and
POST /v1/artifacts. The registry validates RemoteArtifact metadata for
screenshots, renders, logs, browser traces, exports, and diagnostic bundles,
stores the artifact metadata in the gateway persistent store, and emits a
hash-chained artifact.registered audit entry. Export registrations currently
map to the protocol audit-export artifact kind; diagnostic bundles map to the
protocol file kind with artifactPurpose: "diagnostic-bundle" metadata.
GET /v1/artifacts lists registered artifacts and accepts sessionId,
commandId, deviceId, kind, and redactionStatus filters.
Host command results can also register artifacts without a separate HTTP call.
When a browser.screenshot or desktop.screenshot result includes
artifact/artifacts plus artifactIds and evidenceIds, the command
dispatcher stores those screenshot artifacts through the same registry and makes
them visible in audit and timeline queries.
Desktop window fallback commands do not register artifacts by themselves.
desktop.window.list and desktop.window.focus return structured command
outputs with selected-window identity, app/title, bounds, display metadata, and
focus verification so later screenshot/click commands can reference the same
window id through the audited command timeline.
The operator runbook for reading session timelines and exporting the current
store-backed audit bundle is
docs/domains/bellona/extras/remote-control/session-timeline-and-audit-bundle.md.
The current bundle path uses GET /v1/timeline, the first-stage JSON store,
local checksums, and POST /v1/artifacts registration; a dedicated public audit
export endpoint remains a later Phase 180 task.
Redaction utilities are exported from app package entrypoints for gateway and
host call sites that need to scrub retained metadata, logs, traces, window
titles, or future screenshot OCR text before audit/artifact retention. The
utilities redact bearer/JWT/gateway tokens, API keys, passwords, browser cookie
headers or cookie-valued metadata, macOS/Linux/Windows personal file paths, and
operator-denied window titles. They return both the redacted value and
structured findings so later audit/export code can preserve redaction evidence
without retaining the sensitive source text.
Gateway runtime logs use the shared Bellona remote structured logging fields
from @bellona/remote-protocol. Command, host-connection, HTTP, and lifecycle
logs include serviceRole, eventType, and the available correlation fields:
correlationId, sessionId, commandId, deviceId, connectionId,
actorParticipantId, idempotencyKey, and command target fields. These logs
are intended for operational triage and metrics correlation; audit remains the
append-only security record.
Basic gateway metrics are available through app.telemetry. The in-memory
recorder emits typed counter/timer/state metric events for command count,
command duration, command failures, host online/offline state, host reconnects,
approval decision latency, and audit write failures. Metrics use the same
correlation fields as structured logs so local tests, future exporters, and
diagnostic bundles can join them with timeline and audit records.
Approval request and decision storage is available through app.approvalStore.
Approval request creation, decision handling, timeout, deny-by-default behavior,
and approved command continuation are available through app.approvalService.
When command policy returns requires-approval, the dispatcher stores a pending
RemoteApprovalRequest, emits approval.requested, and withholds the host
message. An approved response records RemoteApprovalDecision, emits
approval.decided, and automatically continues the original command. Denied,
cancelled, and expired requests clear their pending continuation without
dispatch. Expiry is deny-by-default and records an expired approval decision
from participant:gateway-policy; the running gateway sweeps pending approvals
on a bounded interval derived from
BELLONA_REMOTE_GATEWAY_APPROVAL_REQUEST_TTL_MS. The Control Room-facing HTTP
surface can list approval requests with GET /v1/approvals?status=pending and
can record operator decisions with POST /v1/approvals/:requestId/decisions.
Denied decisions require a reason, approved decisions continue the withheld
command through the same gateway approval continuation handler, and closed or
missing requests fail without dispatching.
One-time pairing code creation is available through app.pairingCodes. Pairing
codes are generated with Node CSPRNG bytes, normalized to an eight-character
operator-friendly code, stored only as SHA-256 hashes, expire after a bounded
TTL, and can be redeemed once.
Pairing exchange is available at POST /v1/pairing/exchange. The request
contains a one-time pairing code and a complete RemoteDevice report. The
gateway redeems the code, stores the device as an offline paired device, and
returns gateway-signed host credentials. The Remote Host persists those
credentials in macOS Keychain by default; mTLS remains later transport hardening
work.
Device revocation is available through app.deviceRevocation. Revocation marks
the device blocked, records revocation metadata on the device snapshot,
disconnects any active host connection with WebSocket policy code 1008,
rejects future handshakes for that device id, and prevents command dispatch to
the blocked device.
Metrics and structured command/session logs include the same correlation fields:
correlationId, sessionId, deviceId, commandId, actorId, and
adapterTarget when command context is available. The current walking skeleton
stores metric events in app.telemetry.
Configuration#
BELLONA_REMOTE_GATEWAY_HOSTorHOST, default127.0.0.1BELLONA_REMOTE_GATEWAY_APPROVAL_REQUEST_TTL_MS, default60000BELLONA_REMOTE_GATEWAY_HOST_HEARTBEAT_INTERVAL_MS, default30000BELLONA_REMOTE_GATEWAY_HOST_HEARTBEAT_TIMEOUT_MS, default90000BELLONA_REMOTE_GATEWAY_HOST_TOKEN_SIGNING_SECRET, default development-only local secret; production deployments must override thisBELLONA_REMOTE_GATEWAY_HOST_TOKEN_TTL_MS, default7776000000(90 days)BELLONA_REMOTE_GATEWAY_PORTorPORT, default4070BELLONA_REMOTE_GATEWAY_LOG_LEVEL, defaultinfoBELLONA_REMOTE_GATEWAY_PAIRING_CODE_TTL_MS, default600000BELLONA_REMOTE_GATEWAY_STORE_FILE, optional path to the first-stage gateway JSON storeBELLONA_REMOTE_GATEWAY_SHUTDOWN_GRACE_MS, default5000NODE_ENV, defaultdevelopment
First-Stage Store#
Set BELLONA_REMOTE_GATEWAY_STORE_FILE to enable durable gateway state:
BELLONA_REMOTE_GATEWAY_STORE_FILE=.local/bellona/remote-gateway.store.json pnpm nx start @bellona/remote-gateway
The file is an explicitly documented first-stage store, not the final production
database. It uses schema version 3, kind gateway-first-stage-json-file, and
atomic temp-file rename writes. On load, the gateway validates every stored
RemoteDevice, RemoteSession, RemoteCommandEnvelope,
RemoteApprovalRequest, RemoteApprovalDecision, and RemoteAuditEntry; it
also rejects duplicate primary ids and broken audit sequence/hash links before
the server starts using that state.
Legacy schema version 1 and 2 snapshots are forward-migrated on load and
rewritten to the current schema after validation. Current snapshots include
version stamps for device, session, command, approval, and audit record sets,
plus migration history entries that capture schema and protocol transitions. The
exported migrateRemoteGatewayPersistentStoreSnapshot helper can also downgrade
current snapshots to schema version 2 or 1 for rollback fixtures and
compatibility tests.
The store currently persists:
- device snapshots from host handshake and disconnect updates
- session snapshots and lifecycle events
- command dispatch records keyed by command id and idempotency key
- routed command progress, result, and error events
- artifact metadata records and redaction status
- hashed one-time pairing code records
- approval requests and approval decisions
- hash-chained audit entries
Pairing Codes#
Pairing code methods are currently internal service APIs. A caller creates a
code with app.pairingCodes.createPairingCode(), shows the returned code to
the operator or host setup flow once, and only stores the returned
record.codeHash.
Important behavior:
- default code TTL is ten minutes and can be overridden by config or create input within the bounded 30-second to 60-minute range
- redemption accepts hyphenated or lowercase input after normalization
- expired, cancelled, and already redeemed codes cannot be reused
expirePairingCodes()marks stale pending records asexpiredredeemPairingCode()currently records the redeemed device id when supplied; issuing/storing device credentials is the next checklist itemPOST /v1/pairing/exchangeis the development host-facing exchange path for180.C.07.03
Verification#
pnpm nx build @bellona/remote-gatewaypnpm nx typecheck @bellona/remote-gatewaypnpm nx lint @bellona/remote-gatewaypnpm nx test @bellona/remote-gateway
Local Startup#
BELLONA_REMOTE_GATEWAY_PORT=4097 BELLONA_REMOTE_GATEWAY_LOG_LEVEL=debug pnpm nx start @bellona/remote-gateway
curl -fsS http://127.0.0.1:4097/health
curl -fsS http://127.0.0.1:4097/ready
Expected health output is a JSON payload with status: "healthy". Expected
readiness output is a JSON payload with status: "ready" and checks.config,
checks.deviceRegistry, and checks.shuttingDown.
Fake Host Connection#
The host connection flow is WebSocket-first. A fake host connects to
ws://127.0.0.1:4097/v1/hosts/connect and sends the handshake before any
command messages:
{
"type": "host.handshake",
"protocolVersion": "0.1.0",
"supportedProtocolVersions": ["0.1.0"],
"device": {
"id": "device:studio-macbook-air",
"displayName": "Studio MacBook Air"
}
}
The device object above is abridged for readability. In tests and real hosts
it must be a complete RemoteDevice report. A valid fake host receives:
{
"type": "host.handshake.accepted",
"connectionId": "host-connection:000001",
"heartbeatIntervalMs": 30000,
"selectedProtocolVersion": "0.1.0"
}
Invalid handshakes close with WebSocket policy code 1008.
Fake Command Dispatch#
The walking skeleton does not expose the client command API over HTTP yet.
Dispatch is intentionally internal through app.commandDispatcher, which lets
tests exercise the gateway-to-host route without adding premature public API
surface.
The executable fake-host flow is covered in src/command-dispatcher.test.ts:
- Start
createRemoteGatewayApp()on an ephemeral port. - Connect a local
wsclient to/v1/hosts/connect. - Send a protocol-valid host handshake using
remoteDeviceFixture. - Call
app.commandDispatcher.dispatchCommand(remoteCommandEnvelopeFixtures[0]). - Assert the fake host receives this abridged message:
{
"type": "command.dispatch",
"command": {
"id": "command:blender-scene-query-001"
},
"sentAt": "2026-04-22T00:00:00.000Z"
}
The fake host can then respond on the same WebSocket with this abridged message:
{
"type": "command.result",
"result": {
"id": "result:blender-scene-query-001",
"commandId": "command:blender-scene-query-001",
"status": "succeeded"
}
}
The full command and result payloads must satisfy RemoteCommandEnvelope
and RemoteCommandResult. Progress and error responses use the same route with
command.progress and command.error message types. The gateway validates all
host responses against @bellona/remote-protocol, routes them to the
dispatching client id, emits audit entries, and records telemetry.
180.C.15.06 extends the same fake-host coverage to the Unreal read-only
commands unreal.project.info and unreal.world.query. The tests register an
Unreal-capable device snapshot, dispatch both commands through the generic
gateway command dispatcher, return protocol-valid Unreal outputs, and assert
that command.received, command.dispatched, command.progress,
command.result, and command.completed are visible through audit and timeline
queries.
180.C.15.07 extends the route to unreal.actor.spawn. The gateway fake-host
test registers an Unreal capability with command.execute.safe-mutation and
project.write, dispatches the command only when policy allows those scopes,
rejects it before host dispatch when project.write is denied, and validates
the returned actor-spawn result object, undo-stack transaction metadata, and
screenshot evidence placeholder through the normal client/audit/timeline path.
Expected Logs And Tests#
With BELLONA_REMOTE_GATEWAY_LOG_LEVEL=debug, the local flow should include
structured log entries named:
remote gateway listeningremote host handshake acceptedremote gateway command receivedremote gateway command dispatchedremote gateway command result received
Command log and metric records include correlationId, sessionId, deviceId,
commandId, actorId, and adapterTarget. Session stop records include
correlationId, sessionId, deviceId, and actorId.
Run the gateway checks before relying on the fake flow:
pnpm nx test @bellona/remote-gateway --verbose
pnpm nx typecheck @bellona/remote-gateway --verbose
pnpm nx lint @bellona/remote-gateway --verbose
pnpm nx build @bellona/remote-gateway --skip-nx-cache --verbose