# @bellona/remote-gateway

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 /health`
- `GET /v1/health`
- `GET /ready`
- `GET /v1/ready`
- `GET /v1/artifacts`
- `POST /v1/artifacts`
- `GET /v1/approvals`
- `POST /v1/approvals/:requestId/decisions`
- `GET /v1/devices`
- `GET /v1/timeline`
- `POST /v1/pairing/exchange`
- `WS /v1/hosts/connect`

Host WebSocket clients must send a first message shaped as this abridged
example:

```json
{
  "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`](../../../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_HOST` or `HOST`, default `127.0.0.1`
- `BELLONA_REMOTE_GATEWAY_APPROVAL_REQUEST_TTL_MS`, default `60000`
- `BELLONA_REMOTE_GATEWAY_HOST_HEARTBEAT_INTERVAL_MS`, default `30000`
- `BELLONA_REMOTE_GATEWAY_HOST_HEARTBEAT_TIMEOUT_MS`, default `90000`
- `BELLONA_REMOTE_GATEWAY_HOST_TOKEN_SIGNING_SECRET`, default development-only
  local secret; production deployments must override this
- `BELLONA_REMOTE_GATEWAY_HOST_TOKEN_TTL_MS`, default `7776000000` (90 days)
- `BELLONA_REMOTE_GATEWAY_PORT` or `PORT`, default `4070`
- `BELLONA_REMOTE_GATEWAY_LOG_LEVEL`, default `info`
- `BELLONA_REMOTE_GATEWAY_PAIRING_CODE_TTL_MS`, default `600000`
- `BELLONA_REMOTE_GATEWAY_STORE_FILE`, optional path to the first-stage gateway
  JSON store
- `BELLONA_REMOTE_GATEWAY_SHUTDOWN_GRACE_MS`, default `5000`
- `NODE_ENV`, default `development`

## First-Stage Store

Set `BELLONA_REMOTE_GATEWAY_STORE_FILE` to enable durable gateway state:

```bash
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 as `expired`
- `redeemPairingCode()` currently records the redeemed device id when supplied;
  issuing/storing device credentials is the next checklist item
- `POST /v1/pairing/exchange` is the development host-facing exchange path for
  `180.C.07.03`

## Verification

- `pnpm nx build @bellona/remote-gateway`
- `pnpm nx typecheck @bellona/remote-gateway`
- `pnpm nx lint @bellona/remote-gateway`
- `pnpm nx test @bellona/remote-gateway`

## Local Startup

```bash
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:

```json
{
  "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:

```json
{
  "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`:

1. Start `createRemoteGatewayApp()` on an ephemeral port.
2. Connect a local `ws` client to `/v1/hosts/connect`.
3. Send a protocol-valid host handshake using `remoteDeviceFixture`.
4. Call
   `app.commandDispatcher.dispatchCommand(remoteCommandEnvelopeFixtures[0])`.
5. Assert the fake host receives this abridged message:

```json
{
  "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:

```json
{
  "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 listening`
- `remote host handshake accepted`
- `remote gateway command received`
- `remote gateway command dispatched`
- `remote 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:

```bash
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
```