feat: add regenerator runtime taming

[Jack-Works]

Closes: #621
Refs: #1950

Description

regenerator-runtime is a widely used package in the ecosystem. It is used to support generators and async functions transpiled to ES5.

This PR adds an option legacyRegeneratorRuntimeTaming to fix regenerator-runtime from 0.10.5 to 0.13.7. Although the newer version of the regenerator runtime package is compatible with lockdown, some libraries bundle old (hence "legacy") regenerator runtime in their code and it's not practical to get them all to upgrade.

• legacyRegeneratorRuntimeTaming: 'safe' do nothing.
• legacyRegeneratorRuntimeTaming: 'unsafe-ignore' turns Iterator.prototype[@@iterator] to a funky accessor that drops all assignments to it.

Note: regenerator-runtime is doing this:

Gp[iteratorSymbol] = function () {
    return this;
}

which is effectively

IteratorPrototype[Symbol.iterator] = function () {
    return this;
}

Security Considerations

The replacement function from legacy regenerator runtime is the same as the native code, so it is "safe" to drop this assignment, in the sense that it does not cause any bad effects. However, this option drops the assignment by dropping any assignment to IteratorPrototype[Symbol.iterator], since we have no practical way to ensure that the assignment it drops is exactly the one above. Thus, this option is not actual safe since it causes any other such assignment to be ignored silently. This echoes the unsafety of ES3 and of sloppy mode, where failed assignments were silently ignored. Such behavior is unsafe because it allows control flow to proceed into code that assumes the assignment succeeded. That's why ES5 strict mode changed failed assignments to throw.

To emphasize the hazard, we have named this setting of the option 'unsafe-ignore'.

Scaling Considerations

Nothing

Documentation Considerations

If you're hitting problems with an old version of regenerator-runtime (or any package that bundles it), you might need this.

Testing Considerations

Tests added for the specific effect of this PR. However, to avoid introducing even a devDependency on a legacy version of regenerator runtime, no automated test has been added to test that compatibility. Instead, this PR can be tested like this:

import './lockdown.umd.js'
lockdown({ legacyRegeneratorRuntimeTaming: 'unsafe-ignore', errorTaming: 'unsafe', consoleTaming: 'unsafe' })
const script = document.createElement('script')
script.src = 'https://cdn.jsdelivr.net/npm/regenerator-runtime@0.13.7/runtime.js'
document.head.appendChild(script)

Compatibility Considerations

Note: Some version of regenerator-runtime requires to be run in the sloppy mode. Thus, these are incompat with the ses-shim independent of this option.

Upgrade Considerations

No

Update NEWS.md for user-facing changes.

TODO.

[kriskowal]

I’d like to get @erights opinion. Given that the option is safe, I also want to consider automatically detecting the regenerator runtime and applying this mitigation without a feature flag.

[Jack-Works]

hi, @erights I have updated the option name with a legacy prefix and changed none to safe, and safe to unsafe-ignore. I also changed how the setter behaves. I'd like to add a test after the design is OK.

[erights]

Hi Jack, everything here looks good to me (modulo minor suggestions). Once there's a test case, I'll be happy to approve. Thanks!

[Jack-Works]

Hi Jack, everything here looks good to me (modulo minor suggestions). Once there's a test case, I'll be happy to approve. Thanks!

Hi! I added tests!

[Jack-Works]

thanks for the review! I think I fixed everything you have mentioned.

[erights]

LGTM, thanks!

[erights]

Hi @Jack-Works , I've LGTMed and am about to squash-and-merge. But before I do, I'm going to make some minor edits to the PR comment, which will then also be in the commit comment.

Thanks!

[erights]

Hi @Jack-Works , I notice you wrote

Update NEWS.md for user-facing changes.

TODO.

Quite right. This reminds me that https://github.com/endojs/endo/blob/master/packages/ses/docs/lockdown.md will also need updating. I'm going to go ahead and merge this without either, but please do take a look at these. (attn @kriskowal )

[kriskowal]

Yes, please circle back and update lockdown.md and NEWS.md.