bunite-core 0.8.0 → 0.9.0

package/src/rpc/encrypt.ts

@@ -0,0 +1,74 @@
+import type { BytesPipe } from "./transport";
+
+const VERSION = 1;
+const IV_LENGTH = 12;
+const HEADER_LENGTH = 1 + IV_LENGTH;
+
+function toBufferSource(view: Uint8Array): ArrayBuffer {
+  const out = new ArrayBuffer(view.byteLength);
+  new Uint8Array(out).set(view);
+  return out;
+}
+
+async function importAesGcmKey(rawKey: Uint8Array): Promise<CryptoKey> {
+  return crypto.subtle.importKey("raw", toBufferSource(rawKey), "AES-GCM", false, ["encrypt", "decrypt"]);
+}
+
+// WebCrypto AES-256-GCM (browser / preload). For Bun-side use `host/encryptedPipe.ts` (node:crypto).
+export async function createEncryptedPipe(base: BytesPipe, rawKey: Uint8Array): Promise<BytesPipe> {
+  const key = await importAesGcmKey(rawKey);
+  let downstream: ((bytes: Uint8Array) => void) | undefined;
+  let sendChain: Promise<void> = Promise.resolve();
+  let recvChain: Promise<void> = Promise.resolve();
+  let closed = false;
+  const closeOnce = () => { if (!closed) { closed = true; base.close(); } };
+
+  base.setReceive((frame) => {
+    if (closed) return;
+    if (frame.length < HEADER_LENGTH || frame[0] !== VERSION) {
+      closeOnce();
+      return;
+    }
+    const iv = toBufferSource(frame.subarray(1, HEADER_LENGTH));
+    const payload = toBufferSource(frame.subarray(HEADER_LENGTH));
+    recvChain = recvChain.then(async () => {
+      if (closed) return;
+      try {
+        const buf = await crypto.subtle.decrypt({ name: "AES-GCM", iv }, key, payload);
+        downstream?.(new Uint8Array(buf));
+      } catch {
+        closeOnce();
+      }
+    });
+  });
+
+  return {
+    send(bytes) {
+      if (closed) return;
+      const payload = toBufferSource(bytes);
+      sendChain = sendChain.then(async () => {
+        if (closed) return;
+        try {
+          const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+          const ivBuf = toBufferSource(iv);
+          const encrypted = await crypto.subtle.encrypt({ name: "AES-GCM", iv: ivBuf }, key, payload);
+          const encArr = new Uint8Array(encrypted);
+          const out = new Uint8Array(HEADER_LENGTH + encArr.byteLength);
+          out[0] = VERSION;
+          out.set(iv, 1);
+          out.set(encArr, HEADER_LENGTH);
+          base.send(out);
+        } catch {
+          closeOnce();
+        }
+      });
+    },
+    setReceive(handler) {
+      downstream = handler;
+    },
+    close() {
+      closeOnce();
+    },
+  };
+}
+

package/src/rpc/error.ts

@@ -0,0 +1,58 @@
+export type IpcCode =
+  | "ok"
+  | "cancelled"
+  | "unknown"
+  | "invalid_argument"
+  | "deadline_exceeded"
+  | "not_found"
+  | "not_supported"
+  | "already_exists"
+  | "permission_denied"
+  | "unauthenticated"
+  | "resource_exhausted"
+  | "failed_precondition"
+  | "unavailable"
+  | "protocol_error";
+
+export type FailedPreconditionReason =
+  | "cap_disposed"
+  | "cap_revoked"
+  | "owner_disconnect"
+  | "protocol_violation";
+
+export type RetrySpec =
+  | { kind: "never" }
+  | { kind: "transparent" }
+  | { kind: "after-cooldown"; minMs: number }
+  | { kind: "after-resync" };
+
+export interface IpcStatus {
+  code: IpcCode;
+  message?: string;
+  details?: unknown;
+  retry?: RetrySpec;
+}
+
+export class IpcError extends Error {
+  readonly code: IpcCode;
+  readonly details: unknown;
+  readonly retry?: RetrySpec;
+
+  constructor(status: IpcStatus) {
+    super(status.message ?? status.code);
+    this.name = "IpcError";
+    this.code = status.code;
+    this.details = status.details;
+    this.retry = status.retry;
+  }
+
+  toStatus(): IpcStatus {
+    return {
+      code: this.code,
+      message: this.message,
+      details: this.details,
+      retry: this.retry,
+    };
+  }
+}
+

package/src/rpc/framework.ts

@@ -0,0 +1,132 @@
+import { call, defineCap, stream, cap } from "./schema";
+
+export const BrowserWindowCap = defineCap({
+  focus: call<void, void>(),
+  close: call<void, void>(),
+  setBounds: call<{ x: number; y: number; w: number; h: number }, void>(),
+  setTitle: call<{ title: string }, void>(),
+  id: call<void, number>({ idempotent: true }),
+  label: call<void, string>({ idempotent: true }),
+});
+
+export const WindowCap = defineCap({
+  create: call<WindowCreateOpts, typeof BrowserWindowCap>({ returns: cap(BrowserWindowCap) }),
+  list: call<void, typeof BrowserWindowCap>({ returns: cap.array(BrowserWindowCap), idempotent: true }),
+  focus: call<{ id?: number; label?: string }, void>(),
+  close: call<{ id?: number; label?: string }, void>(),
+});
+
+export interface WindowCreateOpts {
+  url: string;
+  title?: string;
+  bounds?: { x?: number; y?: number; w?: number; h?: number };
+  label?: string;
+}
+
+export const FileRefCap = defineCap({
+  text: call<void, string>({ idempotent: true }),
+  bytes: call<void, Uint8Array>({ idempotent: true }),
+  path: call<void, string>({ idempotent: true }),
+  revoke: call<void, void>(),
+}, { disposal: { method: "revoke", async: true } });
+
+export const DialogsCap = defineCap({
+  openFile: call<DialogOpenFileOpts, typeof FileRefCap>({ returns: cap.array(FileRefCap) }),
+  saveFile: call<DialogSaveFileOpts, typeof FileRefCap>({ returns: cap(FileRefCap) }),
+  showMessage: call<DialogMessageOpts, "primary" | "secondary" | "tertiary">(),
+});
+
+export interface DialogOpenFileOpts {
+  title?: string;
+  filters?: { name: string; extensions: string[] }[];
+  multiple?: boolean;
+  startDir?: string;
+}
+
+export interface DialogSaveFileOpts {
+  title?: string;
+  defaultName?: string;
+  filters?: { name: string; extensions: string[] }[];
+}
+
+export interface DialogMessageOpts {
+  title?: string;
+  body: string;
+  primary?: string;
+  secondary?: string;
+  tertiary?: string;
+}
+
+export const ClipboardCap = defineCap({
+  readText: call<void, string>({ idempotent: true }),
+  writeText: call<{ text: string }, void>(),
+  readBytes: call<{ mime: string }, Uint8Array>({ idempotent: true }),
+  writeBytes: call<{ mime: string; data: Uint8Array }, void>(),
+});
+
+export const ShellCap = defineCap({
+  openExternal: call<{ url: string }, boolean>(),
+  showItemInFolder: call<{ path: string }, void>(),
+});
+
+export type SurfaceMask = { x: number; y: number; w: number; h: number };
+
+export const SurfaceCap = defineCap({
+  init: call<{
+    src: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    hidden?: boolean;
+  }, { surfaceId: number }>(),
+  resize: call<{ surfaceId: number; x: number; y: number; w: number; h: number }, void>(),
+  remove: call<{ surfaceId: number }, void>(),
+  setHidden: call<{ surfaceId: number; hidden: boolean }, void>(),
+  setMasks: call<{ surfaceId: number; masks: SurfaceMask[] }, void>(),
+  setAllPassthrough: call<{ passthrough: boolean }, void>(),
+  bringAllVisiblesToFront: call<void, void>(),
+  navigate: call<{ surfaceId: number; url: string }, void>(),
+  goBack: call<{ surfaceId: number }, void>(),
+  reload: call<{ surfaceId: number }, void>(),
+  didNavigate: stream<void, { surfaceId: number; url: string }>(),
+});
+
+export const RuntimeCap = defineCap({
+  window: call<void, typeof WindowCap>({ returns: cap(WindowCap), idempotent: true }),
+  dialogs: call<void, typeof DialogsCap>({ returns: cap(DialogsCap), idempotent: true }),
+  clipboard: call<void, typeof ClipboardCap>({ returns: cap(ClipboardCap), idempotent: true }),
+  shell: call<void, typeof ShellCap>({ returns: cap(ShellCap), idempotent: true }),
+  appName: call<void, string>({ idempotent: true }),
+  appVersion: call<void, string>({ idempotent: true }),
+  theme: call<void, "light" | "dark">({ idempotent: true }),
+  themeWatch: stream<void, "light" | "dark">(),
+  surface: call<void, typeof SurfaceCap>({ returns: cap(SurfaceCap), idempotent: true }),
+});
+
+export const FRAMEWORK_TYPE_IDS = {
+  Runtime: 1,
+  Window: 2,
+  Dialogs: 3,
+  FileRef: 4,
+  Clipboard: 5,
+  Shell: 6,
+  BrowserWindow: 7,
+} as const;
+
+import type { CapDef } from "./schema";
+
+const FRAMEWORK_CAP_TYPE_IDS = new Map<CapDef<any, any>, number>([
+  [RuntimeCap, FRAMEWORK_TYPE_IDS.Runtime],
+  [WindowCap, FRAMEWORK_TYPE_IDS.Window],
+  [DialogsCap, FRAMEWORK_TYPE_IDS.Dialogs],
+  [FileRefCap, FRAMEWORK_TYPE_IDS.FileRef],
+  [ClipboardCap, FRAMEWORK_TYPE_IDS.Clipboard],
+  [ShellCap, FRAMEWORK_TYPE_IDS.Shell],
+  [BrowserWindowCap, FRAMEWORK_TYPE_IDS.BrowserWindow],
+  [SurfaceCap, 8],
+]);
+
+export function frameworkTypeIdOf(cap: CapDef<any, any>): number | undefined {
+  return FRAMEWORK_CAP_TYPE_IDS.get(cap);
+}

package/src/rpc/hash.ts

@@ -0,0 +1,142 @@
+import {
+  type Schema,
+  type CapDef,
+  type MethodDef,
+  type DisposalSpec,
+  type AnyCapToken,
+  type ReturnsKind,
+  isCallDef,
+  isStreamDef,
+  isCapRef,
+  isCapArray,
+  isCapRecord,
+  _bindTopologyHash,
+} from "./schema";
+
+type CanonicalReturns =
+  | { kind: "type" }
+  | { kind: "cap" | "capArray" | "capRecord"; capIndex: number };
+
+type CanonicalMethod =
+  | { name: string; kind: "call"; idempotent: boolean; returns: CanonicalReturns }
+  | { name: string; kind: "stream" };
+
+type CanonicalCap = {
+  methods: CanonicalMethod[];
+  disposal?: { method: string; async: boolean };
+};
+
+type CanonicalRoot = {
+  name: string;
+  capIndex: number;
+};
+
+type CanonicalSchema = {
+  v: 1;
+  roots: CanonicalRoot[];
+  caps: CanonicalCap[];
+};
+
+export function canonicalize(schema: Schema<any>): CanonicalSchema {
+  const capIndex = new Map<CapDef<any, any>, number>();
+  const caps: CanonicalCap[] = [];
+
+  for (const declared of schema.caps) {
+    if (capIndex.has(declared)) continue;
+    capIndex.set(declared, caps.length);
+    caps.push(null as unknown as CanonicalCap);
+  }
+
+  const intern = (c: CapDef<any, any>): number => {
+    const existing = capIndex.get(c);
+    if (existing !== undefined) return existing;
+    const idx = caps.length;
+    capIndex.set(c, idx);
+    caps.push(null as unknown as CanonicalCap);
+    return idx;
+  };
+
+  for (let i = 0; i < caps.length; i++) {
+    if (caps[i] !== null) continue;
+    const declared = schema.caps[i];
+    caps[i] = capToCanonical(declared, intern);
+  }
+
+  const roots: CanonicalRoot[] = Object.keys(schema.roots).map((name) => ({
+    name,
+    capIndex: intern(schema.roots[name]),
+  }));
+
+  for (let i = 0; i < caps.length; i++) {
+    if (caps[i] !== null) continue;
+    const cap = [...capIndex.keys()][i];
+    caps[i] = capToCanonical(cap, intern);
+  }
+
+  return { v: 1, roots, caps };
+}
+
+function capToCanonical(c: CapDef<any, any>, intern: (c: CapDef<any, any>) => number): CanonicalCap {
+  const methods: CanonicalMethod[] = Object.keys(c.methods).map((name) => {
+    const m = c.methods[name] as MethodDef;
+    if (isCallDef(m)) {
+      return {
+        name,
+        kind: "call",
+        idempotent: m.idempotent,
+        returns: returnsToCanonical(m.returns, intern),
+      };
+    }
+    if (isStreamDef(m)) {
+      return { name, kind: "stream" };
+    }
+    throw new Error(`Unknown method def for "${name}"`);
+  });
+
+  const result: CanonicalCap = { methods };
+  const disposal = c.disposal as DisposalSpec | undefined;
+  if (disposal) {
+    result.disposal = { method: disposal.method, async: !!disposal.async };
+  }
+  return result;
+}
+
+function returnsToCanonical(
+  ret: AnyCapToken | undefined,
+  intern: (c: CapDef<any, any>) => number
+): CanonicalReturns {
+  if (!ret) return { kind: "type" };
+  if (isCapRef(ret)) return { kind: "cap", capIndex: intern(ret.cap) };
+  if (isCapArray(ret)) return { kind: "capArray", capIndex: intern(ret.cap) };
+  if (isCapRecord(ret)) return { kind: "capRecord", capIndex: intern(ret.cap) };
+  return { kind: "type" };
+}
+
+function canonicalJSON(value: unknown): string {
+  if (Array.isArray(value)) {
+    return "[" + value.map(canonicalJSON).join(",") + "]";
+  }
+  if (value && typeof value === "object") {
+    const keys = Object.keys(value as object).sort();
+    return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalJSON((value as Record<string, unknown>)[k])).join(",") + "}";
+  }
+  return JSON.stringify(value);
+}
+
+export async function topologyHash(schema: Schema<any>): Promise<string> {
+  const canonical = canonicalize(schema);
+  const json = canonicalJSON(canonical);
+  const bytes = new TextEncoder().encode(json);
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return toHex(new Uint8Array(digest));
+}
+
+function toHex(bytes: Uint8Array): string {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    out += bytes[i].toString(16).padStart(2, "0");
+  }
+  return out;
+}
+
+_bindTopologyHash(topologyHash);

package/src/rpc/index.ts

@@ -0,0 +1,129 @@
+export {
+  call,
+  stream,
+  cap,
+  defineCap,
+  defineSchema,
+  isCallDef,
+  isStreamDef,
+  isCapDef,
+  isSchema,
+  isCapRef,
+  isCapArray,
+  isCapRecord,
+  returnsKindOf,
+} from "./schema";
+
+export type {
+  CallDef,
+  StreamDef,
+  CapDef,
+  CapRefToken,
+  CapArrayToken,
+  CapRecordToken,
+  AnyCapToken,
+  MethodDef,
+  MethodsRecord,
+  DisposalSpec,
+  Schema,
+  SchemaShape,
+  ImplsOf,
+  ServerDescriptor,
+  ReturnsKind,
+  CallCtx,
+  Attestation,
+  ExportedCap,
+  ClientOf,
+  ImplOf,
+  ClientReturn,
+} from "./schema";
+
+export { topologyHash, canonicalize } from "./hash";
+
+export {
+  CapRef,
+  CAP_REF_EXT,
+  createCodec,
+  isFrame,
+  DEFAULT_MAX_BYTES,
+  PROTOCOL_VERSION,
+} from "./wire";
+
+export type {
+  Frame,
+  CallFrame,
+  ResultFrame,
+  StreamFrame,
+  CancelFrame,
+  DropFrame,
+  HelloFrame,
+  GoAwayFrame,
+  StreamEvent,
+  Target,
+  CallMeta,
+  CodecPair,
+  u32,
+  u53,
+} from "./wire";
+
+export { IpcError } from "./error";
+
+export type {
+  IpcCode,
+  IpcStatus,
+  RetrySpec,
+  FailedPreconditionReason,
+} from "./error";
+
+export {
+  CapTable,
+  USER_ROOTS_CAP_ID,
+  RUNTIME_CAP_ID,
+  USER_ROOTS_TYPE_ID,
+  RUNTIME_TYPE_ID,
+  FIRST_USER_CAP_ID,
+  FIRST_USER_TYPE_ID,
+  MAX_CAPS_PER_CONNECTION,
+  createConnection,
+} from "./peer";
+
+export {
+  RuntimeCap,
+  WindowCap,
+  BrowserWindowCap,
+  DialogsCap,
+  FileRefCap,
+  ClipboardCap,
+  ShellCap,
+  SurfaceCap,
+  FRAMEWORK_TYPE_IDS,
+} from "./framework";
+
+export type {
+  WindowCreateOpts,
+  DialogOpenFileOpts,
+  DialogSaveFileOpts,
+  DialogMessageOpts,
+} from "./framework";
+
+export type {
+  Transport,
+  Connection,
+  ConnectionOptions,
+  CapTableEntry,
+  PendingCall,
+} from "./peer";
+
+export {
+  createFrameTransport,
+  createWebSocketPipe,
+} from "./transport";
+
+export type {
+  BytesPipe,
+  WebSocketLike,
+} from "./transport";
+
+export { createEncryptedPipe } from "./encrypt";
+
+export { Stream } from "./stream";