@viloris/vela-host-core

Portable privileged Host call router: register vela.call handlers, enforce capability grants, optional call middleware, return structured deny / RPC envelopes.

Status: pure TypeScript policy + dispatch. No OS I/O, no Bun process split.
Contracts: @viloris/vela-api (CapabilityHost, checkCapability, AppManifest).
Decisions: ADR 0002, ADR 0006, ADR 0007.
DX research: Hono Host DX notes (middleware/context inspiration; Hono is not a dependency).

Role

App TS  --window.vela.call-->  (preload / Shell)  --RPC-->  Host
                                                          ▲
                                                   @viloris/vela-host-core
                                                   handle + require
                                                          │
                                                   injected HostAPI.sys

| Owns | Does not own | |------|----------------| | Method registry (handle) | Page / WebView / window.vela | | Global use + chain / requirePermission | HTTP routing or embedding Hono | | ctx.require / grant checks / ctx.vars | Real clipboard / notify / tray / fs / dialogs | | invoke / invokeRpc | Zig Shell interop / UDS | | createHostEventBus (optional inject) | Preload wiring of window.vela.events | | Profile isolation | Material paint / hit routing |

Pair with @viloris/vela-shell-core for composition policy. Desktop Bun process wiring lives in @viloris/vela-host (Shell UDS client + session lifecycle + createDesktopHost).

Usage

import {
  createCapabilityHost,
  createHostEventBus,
  chain,
  requirePermission,
} from "@viloris/vela-host-core";
import { BuiltinPermissions } from "@viloris/vela-api";

const events = createHostEventBus();
const host = createCapabilityHost({
  api: {
    platform: "linux",
    sys: { /* inject facades: clipboard, notify, tray, … */ },
    events,
  },
  capabilities: {
    default: { permissions: [BuiltinPermissions.ClipboardWrite] },
  },
});

// Optional global onion (audit / timing). Runtime host concern.
host.use(async (_args, ctx, next) => {
  ctx.vars.set("t0", performance.now());
  return await next();
});

// Per-method: chain middleware + handler (still a single CallHandler).
host.handle(
  "clipboard.write",
  chain(
    requirePermission(BuiltinPermissions.ClipboardWrite),
    async (args, ctx) => {
      // … use host.api.sys after require
      void ctx;
      return { ok: true, text: String((args as { text?: string }).text ?? "") };
    },
  ),
);

// Plain handlers still work:
// host.handle("clipboard.write", async (args, ctx) => {
//   ctx.require(BuiltinPermissions.ClipboardWrite);
//   return { ok: true };
// });

const rpc = await host.invokeRpc({
  requestId: "1",
  method: "clipboard.write",
  args: { text: "hi" },
});

Verify

bun test packages/host-core
bun run --filter @viloris/vela-host-core typecheck

Related

• @viloris/vela-api capability + manifest modules
• Capabilities and plugins
• Hono Host DX notes
• Design gaps G-P1-6, G-P1-9, G-P1-11