Endo Framework

The endo-daemon package provides two primary components:

1. Endo Daemon: A persistent host that manages guest programs within hardened JavaScript worker processes. It manages per-user storage and compute access.
2. Controller: A component that manages the lifecycle of the Endo daemon.

Communication occurs via a Unix domain socket or a named pipe associated with the user. The communication protocol uses CapTP (Capability Transport Protocol) encapsulated within netstring message envelopes. The bootstrap process provides a user agent API, which serves as the foundation for deriving facets for other agents.

OCapN Noise provides cryptographic support for an OCapN netlayer using the Noise Protocol. It is designed for use in web browsers and Node.js environments where WebAssembly is available. It implements the XX-x25519-ChaCha20Poly1305-Blake2 protocol variant with Ed25519 signature verification.

Key capabilities include:

• Generating keys.
• Performing 3-way handshakes as either an initiator or a responder.
• Encrypting and decrypting consecutive messages between parties.

The implementation is highly efficient, performing no heap allocations on the Rust side of the FFI boundary.

Note: This specific repository contains the Rust/Wasm implementation. For the JavaScript bindings and a demo, use the @endo/ocapn-noise package.

The @endo/ocapn-noise package provides a Noise Protocol netlayer specifically designed for @endo/ocapn. It implements the XX-x25519-ChaCha20Poly1305-Blake2 variant with Ed25519 signature verification.

Key features include:

• Cryptographic Proof: Each party signs their ephemeral X25519 encryption public key with their Ed25519 signing key during the handshake, proving ownership of both key pairs.
• Performance: The underlying cryptography is implemented in Rust and compiled to WebAssembly (Wasm).
• Transport Agnostic: While designed to work particularly well with WebSockets, the netlayer is intended to stand atop multiple transport layers to preserve message target identities across different platforms (client, server, cloud, edge).

The @endo/where package is a utility used to find the Endo user directory and the communication endpoint (Unix domain socket on Unix-like systems or Windows named pipe on Windows) for the Endo daemon.

Path Resolution Logic

Endo follows these conventions to locate files and sockets:

• Unix/Linux/macOS: Attempts to use or infer XDG Base Directory Specification paths. The user directory stores per-user runtime data, including logs and application storage.
• Windows: Falls back to native Windows conventions. Note that on Windows, Endo does not currently use separate state and cache directories, and it does not yet sync state between different home directories. Windows communication is handled via named pipes.

The @endo/cache-map package provides bounded-size caches that implement WeakMap-compatible methods: has, get, set, and delete.

Key characteristics:

• Bounded Size: You specify a maximum size for the cache.
• Referential Strength Control: You can control whether keys are held weakly or strongly by providing a makeMap option. By default, it behaves like a WeakMap (keys must be objects/symbols and are held weakly). Providing Map as the makeMap option allows for arbitrary keys (like strings) which will be strongly held.
• Eviction Policy: The cache uses an internal eviction policy (such as CLOCK or SIEVE) designed to match or exceed LRU hit ratios.

import { makeCacheMapKit } from '@endo/cache-map';

// Create a cache with a capacity of 100
const { cache, getMetrics } = makeCacheMapKit(100);

The stream-node package provides adapters to bridge Node.js streams with Endo's async iterable stream interface.

• Use makeNodeReader to convert a Node.js Readable stream into an Endo-compatible async iterable reader.
• Use makeNodeWriter to convert an Endo-compatible async iterable writer into a Node.js Writable stream.

The SES package and associated Endo packages are under active development and security review.

• Version Support: Security fixes are only provided for the most recent branch.
• Recommendation: Users are strongly encouraged to always use the latest available version to ensure they have the most recent security updates.
• Response Times:
  • Acknowledgment via email is expected within one business day (subject to Pacific Time business hours).
  • Vulnerability validation may take up to 72 hours.
  • For Critical or High Severity issues, a security advisory will be released to notify impacted parties to prepare for an emergency patch.

The @endo/errors package provides utilities to construct errors with redacted messages. This is used to prevent guest programs (or untrusted code) from accessing sensitive internal state information when a host function throws an exception.

When used in coordination with ses (Secure EcmaScript) in the host realm, the full, unredacted error information is sent to the realm's console for debugging purposes, but remains invisible to any code that catches the error. This ensures that while developers can still debug issues, the untrusted code only sees a redacted version of the error.