endo

KO | EN

gitlite — search

#python #kotlin #react #javascript #android #jetpack-compose #api #swift #redis #golang #nodejs #typescript

★ 1,045 Open GitHub ↗

Endo is a distributed secure JavaScript sandbox, based on SES

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

---
title: readme
group: Documents
category: Guides
---

# Endo

[![contributing][contributing-svg]][contributing-url]
[![license][license-image]][license-url]
[![CI status](https://github.com/endojs/endo/actions/workflows/ci.yml/badge.svg)](https://github.com/endojs/endo/actions/workflows/ci.yml)
[![Mutable.ai Auto Wiki](https://img.shields.io/badge/Auto_Wiki-Mutable.ai-blue)](https://wiki.mutable.ai/endojs/endo)

Endo is a framework for powerful JavaScript plugin systems and supply chain
attack resistance.
Endo includes tools for _confinement_, _communication_, and _concurrency_.
With Endo’s [SES][] implementation of [HardenedJS][], we can opt-in to a more
tamper-resistant mode of JavaScript.
With Endo’s [Eventual Send][E], we have a safe, transport-agnostic abstraction
for pipelining messages to remote procedures, and concrete transports like
[Endo CapTP][CapTP] and, soon, [OCapN](https://ocapn.org).

[Agoric][] and [MetaMask][] rely on Hardened JavaScript and the [SES shim][SES]
as part of systems that sandbox third-party plugins or smart contracts and
mitigate supply chain attacks for production web applications, web extensions,
and build systems.

[![Agoric Logo](https://github.com/endojs/endo/raw/master/packages/ses/docs/agoric-x100.png)][Agoric]
[![MetaMask Logo](https://github.com/endojs/endo/raw/master/packages/ses/docs/metamask-x100.png)][MetaMask]

[Agoric]: https://agoric.com/
[MetaMask]: https://metamask.io/

Endo protects program integrity both in-process and in distributed systems.
Hardened JavaScript protects local integrity, defending an application against
[supply chain attacks][]: hacks that enter through upgrades to third-party
dependencies.
Endo does this by encouraging the [Principle of Least Authority][] and
providing foundations for the [Object-capability Model][].

The _Principle of Least Authority_ states that a software component should only
have access to data and resources that enable it to do its legitimate work.
The _Object-capability Model_ gives programmers a place to reason, by
construction, about how permission flows through a program using
well-understood mechanisms like [Encapsulation][].

For distributed systems, Endo stretches object oriented programming over
networks using asynchronous message passing to remote objects with
_Capability Transport Protocols_ like [OCapN][] and a portable abstraction
for safely sending messages to remote objects called _Eventual Send_.

**Security:** Security-conscious JavaScript applications can use these
components to improve the integrity and auditability of their own applications,
improve the economics of vetting third-party dependencies, and mitigate runtime
prototype pollution attacks.

**Workers and Networks:** Performance-conscious JavaScript applications can use
these components to improve the ergonomics of message-passing between
components in separate workers.
Endo's _Eventual Send_ and _Capability Transport Protocols_ stretch
asynchronous method invocation acrosses processes and networks.

**Plugins:** JavaScript platforms on the web and blockchains can rely on Endo to safely
enable third-party plugins or smart contracts.
Endo provides tooling for bundling and safely executing arbitrary programs in
the presence of hardened platform objects.

Since most JavaScript libraries receive powerful capabilities from global
objects like `fetch` or modules like `net`, [LavaMoat][] generates reviewable
policies that determine what capabilities will be distributed to third party
dependencies according to evident need, and enforces those policies at runtime
with Endo.

For distributed systems, Endo stretches object oriented programming over
networks using asynchronous message passing to remote objects with the
[Handled Promise][] API and a [Capability Transfer Protocol][CapTP].

Between remote objects and Hardened JavaScript compartments, Endo makes
distributed programs easy to program, and easy to reason about integrity.
CapTP frees the programmer from needing to create bespoke communication
protocols over message ports or byte streams.

Endo combines these components to demonstrate their use for a confined plugin
system in the [Endo Pet-name Dæmon](packages/daemon) and its
[CLI](packages/cli).

Please join the conversation on our [Mailing List][SES Strategy Group] and
[Matrix][Endo Matrix].
Reach out if you would like an ivitation to our **meetings**:

- We record a weekly [Endo Sync video call][Endo Sync] .
- We recorded a weekly [SES video call][SES Strategy Recordings] with the
  Hardened JavaScript engineering community.
- We now meet weekly with [ECMA TC-39 ECMAScript Technical Committee TG-3
  Security Working Group][TG3].

## Core Concepts

[HardenedJS][] introduces three components to the base JavaScript:

- Lockdown
- Harden
- Compartment

The _Shared Intrinsics_ are a subset of the JavaScript intrinsics like the
`Array` and `Object` prototypes that, after _locking down_, are safe to share
between programs running in _compartments_.
After _lockdown_, programs can use _harden_ to make other objects safe
to share between compartments.

With these three components, we can begin to rely on certain guarantees:

- Hardened objects can represent _capabilities_.
  That is, holding a reference to an object means you can use that object.
- JavaScript itself guarantees that _capabilities_ cannot be forged.
  That is, a useful reference cannot be obtained by guessing its address.
- JavaScript also enforces certain structures like closures and `WeakMap`
  can guard capabilities. 
- The only way to obtain a _capability_ is to have received it as an argument,
  return, global, or module of the surrounding compartmnet.
- Once hardened, an object and its methods cannot be altered.

This gives us the foundation of the _Object-capability_ security paradigm,
or simply "OCaps".
From this point forward, any interesting policy can be created with code.

We can then use Endo to stretch references to Object-capabliities between
processes and over networks.
Instead of relying on the memory-safety of JavaScript, we then rely on
cryptography to preserve confidentiality and unforgeability of references.  A
suitably large, signed, cryptographically random number, reachable over a
network over an encrypted connection, may safely designate a capability.

Then, Endo puts ocaps directly into the hands of users with an example [Petname
system][] called the _Pet Dæmon_, so user's can send, receive, and use
_Object-capabilities_ with human-meaningful names.

## Ruminations on the Name

* In Greek, "endo-" means "internal" or "within".
  This is fitting because Endo runs Node _within_ a safe sandbox.
  This is fitting in turn because Endo is built on the legacy of Google Caja.
  In Spanish, "caja" means "box" and is related to the Latin word "capsum" and
  English "capsule", as in "encapsulate".
* Endo is an anagram of Node and Deno.
  That is to say, we are not Done yet.
* The `endo` command, like the `sudo` command, is a "do" command.
  However, instead of escalating privilege, it attenuates privilege.
* Endo lets applications endow packages with limited powerful objects and
  modules.  As they say, you can't spell "endow" without "endo"!
* So, "E.N.Do" forms the acronym "Encapsulated Node Do".

So, just as "soo-doo" (super user do) and "soo-doh" (like "pseudo") are valid
pronunciations of `sudo`, "en-doh" and "en-doo" are both valid pronunciations of
`endo`.

<a name="§pola"></a>
### Principle of Least Authority

The Principle of Least Authority [(Wikipedia)][Principle of Least Authority]
states that a software component should only have access to data and resources
that enable it to do its legitimate work.

**PoLA explained in 3 minutes:**
_Opening Statement on SOSP 50th Anniversary Panel_, Mark Miller:

[![Video presentation explaining PoLA in 3 minutes](https://img.youtube.com/vi/br9DwtjqmVI/0.jpg)](https://www.youtube.com/watch?v=br9DwtjqmVI)

**PoLA explained in 15 minutes:**
_Navigating the Attack Surface to achieve a multiplicative reduction in risk_,
Mark Miller:

[![Video presentation explaining PoLA in 15 minutes](https://img.youtube.com/vi/wW9-KuezPp8/0.jpg)](https://www.youtube.com/watch?v=wW9-KuezPp8&t=664s)

### Bug Disclosure

Please help us practice coordinated security bug disclosure, by using the
instructions in our [security guide](./packages/ses/SECURITY.md) to report
security-sensitive bugs privately.

For non-security bugs, please use the [regular Issues
page](https://github.com/Agoric/SES-shim/issues).

### License

Endo and its components are [Apache 2.0 licensed][license-url].

[CapTP]: packages/captp/README.md#endocaptp
[E]: https://github.com/endojs/endo/tree/master/packages/eventual-send#eventual-send
[Encapsulation]: https://en.wikipedia.org/wiki/Encapsulation_(computer_programming)
[Endo Matrix]: https://matrix.to/#/#endojs:matrix.org
[Endo Sync]: https://www.youtube.com/watch?v=tM5NyB7xxYM&list=PLzDw4TTug5O0eUj81Vnkp-mFuI4O0rBnc
[Handled Promise]: packages/eventual-send/README.md
[HardenedJS]: https://hardenedjs.org
[LavaMoat]: https://github.com/LavaMoat/LavaMoat
[OCapN]: https://ocapn.org
[Object-capability Model]: https://en.wikipedia.org/wiki/Object-capability_model
[Petname system]: https://en.wikipedia.org/wiki/Petname
[Principle of Least Authority]: https://en.wikipedia.org/wiki/Principle_of_least_privilege
[SES Proposal]: https://github.com/tc39/proposal-ses
[SES Strategy Group]: https://groups.google.com/g/ses-strategy
[SES Strategy Recordings]: https://www.youtube.com/playlist?list=PLzDw4TTug5O1jzKodRDp3qec8zl88oxGd
[SES]: packages/ses/README.md
[TG3]: https://github.com/tc39/tg3
[contributing-svg]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg
[contributing-url]: ./CONTRIBUTING.md
[license-image]: https://img.shields.io/badge/License-Apache%202.0-blue.svg
[license-url]: ./LICENSE
[supply chain attacks]: https://en.wikipedia.org/wiki/Supply_chain_attack

endo

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README