way for modules to declare expecting Lockdown or Endo

[turadg]

What is the Problem Being Solved?

Two problems.

1. Developers sometimes encounter SES_ALREADY_LOCKED_DOWN and have a hard time finding where it was locked down. Sometimes two modules both attempt lockdown, so the second fails. With transitive dependencies it can be hard to track down.

2. Declaring the available global environment for TypeScript is currently done with triple-slash directives which aren't validated at runtime. E.g., /// <reference types="ses" />

Description of the Design

Principle: programs should perform lockdown, not modules. That is, only an entry-point module should be doing import '@endo/init' or however lockdown happens.

The change is to let a module declare that it expects to run in a locked-down program. Perhaps by way of an import that:

• checks if the environment is already locked down
• if it isn't, log loudly about the expectation and teach a remedy
• as a side-effect updates the TS global env with what lockdown provides in the global env(e.g. harden)

Similarly for Endo, with TextEncoder, TextDecoder, URL, HandledPromise, etc

Security Considerations

Scaling Considerations

Test Plan

Compatibility Considerations

Upgrade Considerations

[warner]

I have vague memories of a long-ago conversation about this, and one thing that came out of it was: programs should perform lockdown, not modules. That is, only an entry-point module should be doing import '@endo/init' or however lockdown happens. "lockdown if not already locked down" feels dangerous to me, and encourages confusion between which code is the host and which code is the guest. And, as we've seen before, doesn't play well with lockdown() taking options, which might differ from one module to the next.

I really like the idea of some kind of annotation, so when you look at a module, you can tell that it needs to be run in a HardenedJS environment, but it would be sort of like the package.json engine annotation that says "I need to be run with Node >= 20.x", or something like "I need to be run in an engine that has Promise.race" (or some other feature that may or may not be present).

Hm, maybe a module which, upon importing, merely asserts that we are in a locked-down environment, and throws otherwise, with a message pointing the user to modify their entry-point module to import '@endo/init'? Maybe such a module could also update the TS stuff to let tsc realize what new globals will be available?

[turadg]

Agreed. That is what I had in mind at first but forgot that constraint when I was sketching the design here. I've changed,
"if it isn't, lock it down" to "if it isn't, loudly log about the situation and teach what to do.