docs say lockdown() freezes globalThis

[dckc]

https://github.com/endojs/endo/blob/f891df0cb180d2296ae9f671af10fcdc8b24b209/packages/ses/docs/reference.md?plain=1#L85-L87

cc @tgrecojs @erights

[mhofman]

My understanding is that because this content used to live in the agoric-sdk documentation, and that we (used to?) freeze the global object of the Compartment into which contracts are evaluated, the docs simply said globalThis was frozen.

@kriskowal since we want to clarify what guarantees SES does or does not provide in term of Ocaps, in particular in terms of what kind of communication 2 conspiring parties may achieve, it might be good to holistically review these related parts of the docs.

To be clear, the intent is to not freeze the globalThis by default since it isn't shared between Compartments, but that the compartment creator is free to do so for their program, at least for any created child Compartment's global object as the global object of the start compartment in some environments is exotic and does not support freezing.

[kriskowal]

Right, lockdown() does not freeze the Realm’s globalThis (so that the host has the option of scuttling[^1] among other things) and Compartment() does not freeze its newly created compartment.globalThis (so the host has the option of endowing it with other properties and to freeze or not freeze depending on tenancy).

• Guest code cannot safely run in the Realm, so leaving the globalThis mutable is safe (unless there is a confinement defect in SES).
• A single guest’s code can safely run in a Compartment with a mutable globalThis (unless there is a defect a confinement defect in SES or the endowments granted to the guest by the host.)
• A compartment that has a frozen globalThis and no powerful endowments and no import hooks can be safely shared by multiple guests.

In the former two cases, the value of freezing globalThis of a realm or Compartment is usually that it provides a modicum of defense-in-depth in the face of defects in SES or the orchestration of endowments into compartments.

Endo’s Compartment Mapper does freeze every compartment’s globalThis by default, so the Agoric Contract environment has a frozen globalThis.

This issue tracks the inclusion of these clarifications in the ses documentation.

[^1]: Scuttling is moving all powerful capabilities of the realm globalThis to a main Compartment, such that a guest that escapes their compartment to the surrounding realm gains no additional power.

[tgrecojs]

@dckc thank you for opening this.

I was able to ask @kriskowal about this near the close of today's meeting, and he swiftly cleared up my uncertainty (by informing me that 'globalThis' is not hardened by calling 'lockdown'). That being said, knowing the context behind why this information was added to the documentation is quite helpful, so thank you for the additional feedback @mhofman!