Skip to content

feat: add runtime package with IPC admin layer, grant revocation, and process management#43

Draft
Kahtaf wants to merge 1 commit intomainfrom
feat/runtime-ipc-admin-layer
Draft

feat: add runtime package with IPC admin layer, grant revocation, and process management#43
Kahtaf wants to merge 1 commit intomainfrom
feat/runtime-ipc-admin-layer

Conversation

@Kahtaf
Copy link
Member

@Kahtaf Kahtaf commented Feb 17, 2026

Summary

This PR introduces a new runtime package and an IPC-based admin layer to support the DataBridge desktop wrapper integration. It also adds grant revocation, a lightweight status endpoint, local-only middleware for data ingestion, and tunnel proxy improvements.

New packages/runtime package

Adds process management primitives needed for the DataBridge wrapper to manage the personal server as a background process:

  • PID file management (pid.ts) — Write, read, and remove PID files containing server metadata (port, socket path, version, start time)
  • IPC server (ipc-server.ts) — Unix domain socket listener that delegates to a Hono fetch handler, enabling admin routes accessible only from the local machine
  • IPC client (ipc-client.ts) — Client for communicating with the IPC server over the Unix socket
  • Supervisor (supervisor.ts) — Process supervisor for spawning and managing the server as a child process
  • Daemon (daemon.ts) — Utilities for daemonizing the server process
  • Socket path resolution (ipc-path.ts) — Deterministic socket path derivation from storage root

New packages/core/src/lifecycle module

  • RuntimeStateMachine — Typed state machine for tracking server lifecycle states and transitions
  • Endpoint ownership — Utilities for endpoint ownership management

Admin app and local-only middleware

  • admin-app.ts — Separate Hono app for admin routes, served exclusively over the IPC Unix socket. This keeps admin operations (index management, sync control) off the public HTTP surface.
  • local-only.ts middleware — Restricts the POST /v1/data/:scope ingestion endpoint to local-only requests, preventing remote data writes through the tunnel.

Grant revocation

  • DELETE /v1/grants/:grantId — New owner-only endpoint to revoke grants. Signs the revocation with the server signer and forwards it to the gateway. Includes validation for 0x-prefixed grant IDs and proper error responses when signer is not configured.

Health and status

  • GET /status — New lightweight endpoint returning { status, owner, port } for the DataBridge wrapper to poll server readiness without the overhead of the full /health response.
  • port is now threaded through AppDepsHealthDeps so the status endpoint can report it.

Tunnel improvements

  • Unique proxy namesderiveProxyName(runId) generates ps-{first8chars} proxy names, avoiding FRP proxy name collisions between concurrent or stale sessions (previously hardcoded as "personal-server").
  • Transport header — Adds x-ps-transport = "tunnel" request header via [proxies.requestHeaders.set], allowing the server to distinguish tunneled vs direct requests.

Server config

  • server.address — New optional field in ServerConfigSchema for the owner wallet address, set by the DataBridge wrapper.

CLI re-exports

  • The CLI package now re-exports all runtime utilities (writePidFile, readPidFile, Supervisor, daemonize, IpcClient, etc.) and lifecycle types (RuntimeStateMachine, RuntimeState, StateTransitionEvent).

Shutdown improvements

  • shutdown() is now async and properly cleans up the PID file, IPC server, and server context (tunnel, sync, db) before closing the HTTP server.

Test plan

  • Verify deriveProxyName tests pass (short IDs, UUID format, prefix)
  • Verify generateFrpcConfig tests pass (unique proxy name, x-ps-transport header)
  • Verify GET /status returns correct status, owner, and port
  • Verify DELETE /:grantId revokes grants, validates input, and handles missing signer
  • Verify server.address config schema accepts 0x-prefixed strings and defaults to undefined
  • Verify local-only middleware tests pass
  • Verify RuntimeStateMachine lifecycle state tests pass
  • Verify PID file and IPC path unit tests pass
  • Verify supervisor unit tests pass
  • Verify existing createApp tests still pass with new port dependency

@github-actions github-actions bot added dependencies Pull requests that update a dependency file core server docs cli labels Feb 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cli core dependencies Pull requests that update a dependency file docs server

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

Comments