capos (JavaScript / TypeScript)

Host-side JavaScript/TypeScript client for capOS, a research capability operating system where every resource is a typed Cap'n Proto capability.

This package is the working base for the host-side capOS SDK in JS/TS: a pure, dependency-free Node client that speaks the same loopback HTTP protocol capOS serves to its own browser remote-session UI. Today it covers connecting, authenticating, listing the forwarded CapSet, and reading session metadata; more of the typed capability surface follows.

Install

npm install capos

Pure TypeScript compiled to ESM with bundled type declarations. Requires Node 20 or newer (uses the built-in global fetch); zero runtime dependencies.

Quickstart against a live capOS

Boot a live capOS from the repo root. make run-cloud-prod-remote-session-web-ui-l4 builds the Phase C userspace network-stack image and serves the remote-session web UI from inside the guest, reached on a host-forwarded port (guest :8080). That self-served UI keeps all authority server-side and requires a password login; the L4 proof provisions operator / capos. Point the client at the forwarded port:

import { Client } from "capos";

const client = new Client({ baseUrl: "http://127.0.0.1:<PORT>" });
await client.connect();

const { capCount, profile } = await client.loginPassword({
  account: "operator",
  password: "capos",
});
console.log(`logged in as ${profile} (${capCount} caps)`);

for (const cap of await client.listCapset()) {
  console.log(cap.name, cap.interfaceIdHex, cap.transferPolicy);
}

console.log(await client.sessionInfo());
console.log(await client.systemMotd());

Running examples/hello.mjs against that live capOS:

capos 0.1.2
logged in as operator — profile operator (4 caps)

--- MOTD ---
backend SystemInfo call returned 2215 MOTD bytes (kept server-side)

--- session ---
principal: operator (operator)
profile:   operator   auth: password

--- CapSet (4) ---
  session            0x80b87169c39aaf1c  backend-held
  system_info        0xfbbdc602980cb986  backend-held
  adventure          0xd5dc40d973e75b84  backend-held
  chat               0xd5dc40d973e75b84  backend-held

Using the client

import { Client } from "capos";

const client = new Client({ baseUrl: "http://127.0.0.1:8080" });
await client.connect();               // GET; picks up any minted cookies

await client.loginPassword({ account: "operator", password: "capos" });
// Some deployments (the host-side bridge) also allow anonymous login:
// await client.loginAnonymous({ profile: "operator" });

const caps = await client.listCapset();     // Cap[] from the authoritative view
const session = await client.sessionInfo();  // redacted SessionInfo
const motd = await client.systemMotd();      // { text } or redacted { motdBytes }

Behavior notes

loginAnonymous() defaults its profile to anonymous (least privilege, matching the server's own default). Pass { profile: "operator" } explicitly when you want the operator console.

Protocol notes

capOS's remote-session web surface is a loopback-only, same-origin HTTP API. Every state-changing POST is guarded by an Origin allowlist and a CSRF double-submit token that mirrors the capos_csrf_token cookie. Browsers satisfy these implicitly; this client reproduces them for a headless caller — it keeps a cookie jar of whatever the server mints (the session cookie is capos_remote_session on the self-served capOS UI and capos_browser_session on the host bridge) and attaches the Origin, Cookie, and X-CSRF-Token header to each POST.

All authority stays server-side. The response envelope's view is the authoritative browser-safe snapshot, so caps and session metadata are read from it; per-route payloads are redacted (a CapSet list carries no interface owners, and the self-served MOTD call returns only the banner's byte length, not its contents). The client only exchanges DTOs and never holds an invokable capability. Why that boundary holds — capability forwarding versus this data bridge — is documented in the capOS capability model.

Links

• Project: https://cap-os.dev
• Source: https://github.com/ei-grad/capos

Licensed under either of MIT or Apache-2.0 at your option.