Skip to content

Commit

Permalink
chore(webpack): refresh README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@naugtur
naugtur committed Mar 13, 2024
1 parent cfad0e1 commit 5119a84
Show file tree
Hide file tree
Showing 2 changed files with 28 additions and 31 deletions.
50 changes: 24 additions & 26 deletions packages/webpack/README.md
View file
Expand Up @@ -14,15 +14,20 @@ LavaMoat Webpack Plugin wraps each module in the bundle in a [Compartment](https

> The plugin is emitting lockdown without the `.js` extension because that's the only way to prevent it from getting minified, which is likely to break it.
The LavaMoat plugin takes an options object with the following properties:

- policy: the LavaMoat policy object. (unstable. This will surely change before v1 or a policy loader export will be provided from the main package to incorporate policy-override files)
- runChecks: Optional boolean property to indicate whether to check resulting code with wrapping for correctness. Default is false.
- diagnosticsVerbosity: Optional number property to represent diagnostics output verbosity. A larger number means more overwhelming diagnostics output. Default is 0.
Setting positive verbosity will enable runChecks.
- readableResourceIds: Decide whether to keep resource IDs human readable (regardless of production/development mode). If false, they are replaced with a sequence of numbers. Keeping them readable may be useful for debugging when a policy violation error is thrown.
- lockdown: set configuration for [SES lockdown](). Setting the option replaces defaults from LavaMoat.
- HtmlWebpackPluginInterop: add a script tag to the html output for ./lockdown file if HtmlWebpackPlugin is in use
The LavaMoat plugin takes an options object with the following properties (all optional):

| property | description | default |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ |
| policyLocation | Folder to store policy files in. | `./lavamoat/webpack` |
| generatePolicy | Whether to generate the policy.json file. Generated policy is used in the build immediately. `policy-override.json` is applied before bundling, if present. | `false` |
| emitPolicySnapshot | If enabled, emits the result of merging policy with overrides into the output folder of webpack build for inspection. The file is not used by the bundle. | `false` |
| readableResourceIds | Boolean to decide whether to keep resource IDs human readable (possibly regardless of production/development mode). If false, they are replaced with a sequence of numbers. Keeping them readable may be useful for debugging when a policy violation error is thrown. By default follows the webpack config mode. | `(mode==='development')` |
| lockdown | set configuration for [SES lockdown][]. Setting the option replaces defaults from LavaMoat. | reasonable defaults |
| HtmlWebpackPluginInterop | Boolean to add a script tag to the html output for ./lockdown file if HtmlWebpackPlugin is in use. | `false` |
| inlineLockdown | array of output filenames to inline lockdown into instead of adding it as a file to the output folder. |
| runChecks | boolean property to indicate whether to check resulting code with wrapping for correctness. | `false` |
| diagnosticsVerbosity | number property to represent diagnostics output verbosity. A larger number means more overwhelming diagnostics output. Setting positive verbosity will enable runChecks. | `0` |
| policy | the LavaMoat policy object. (by default policy is loaded from files, this is an override) | `undefined` |

```js
const LavaMoatPlugin = require('@lavamoat/webpack')
Expand All @@ -31,18 +36,8 @@ module.exports = {
// ... other webpack configuration properties
plugins: [
new LavaMoatPlugin({
// policy generated by lavamoat
policy: require('./lavamoat/policy.json'),
// runChecks: true, // enables checking each wrapped module source if it's still proper JavaScript (in case mismatching braces somehow survived Webpack loaders processing)
// readableResourceIds: true, // explicitly decide if resourceIds from policy should be readable in the bundle or turned into numbers. You might want to bundle in production mode but keep the ids for debugging
// diagnosticsVerbosity: 2, // level of output verbosity from the plugin
// SES lockdown options to use at runtime
// lockdown: {
// errorTaming: "unsafe",
// consoleTaming: "unsafe",
// overrideTaming: "severe"
// },
// HtmlWebpackPluginInterop: false, // set it to true if you want a script tag for ./lockdown file to automatically be added to your HTML template
generatePolicy: true,
// ... settings from above, optionally
}),
],
// ... other webpack configuration properties
Expand Down Expand Up @@ -74,7 +69,7 @@ Example: avoid wrapping CSS modules:
'css-loader',
LavaMoatPlugin.exclude,
],
sideEffects: true,
// ...
},
],
},
Expand Down Expand Up @@ -107,12 +102,13 @@ Sadly, even treeshaking doesn't eliminate that module. It's left there and faili

This plugin will skip policy enforcement for such ignored modules.

# Security Claims
# Security

**This is a _beta_ release and does not provide any guarantees; even those listed below. Use at your own risk!**
**This is an experimental technology. Use at your own risk!**

- SES must be added to the page without any bundling or transforming for any security guarantees to be sustained.
- The plugin is attempting to add it as an asset to the compilation for the sake of Developer Experience. Feedback welcome.
- [SES lockdown][] must be added to the page without any bundling or transforming for any security guarantees to be sustained.
- The plugin is attempting to add it as an asset to the compilation for the sake of Developer Experience. `.js` extension is omitted to prevent minification.
- Optionally lockdown can be inlined into the bundle files. It's hard to determine which files are loaded when, so providing filenames for scripts that get to load as the first script on the page to apply lockdown only once is how one uses inlining.
- Each javascript module resulting from the webpack build is scoped to its package's policy

## Threat Model
Expand All @@ -137,3 +133,5 @@ Run `npm test` to start the automated tests.
- Navigate to `example/`
- Run `npm ci` and `npm test`
- Open `dist/index.html` in your browser and inspect the console

[SES lockdown]: https://github.com/endojs/endo/tree/master/packages/ses#lockdown
9 changes: 4 additions & 5 deletions packages/webpack/src/types.js
View file
Expand Up @@ -12,19 +12,18 @@
* defaults to './lavamoat/webpack'
* @property {boolean} [emitPolicySnapshot] - Additionally put policy in dist of
* webpack compilation
* @property {boolean} [runChecks] - Check resulting code with wrapping for
* correctness
* @property {boolean} [readableResourceIds] - Should resourceIds be readable or
* turned into numbers - defaults to (mode==='development')
* @property {boolean} [HtmlWebpackPluginInterop] - Add a script tag to the html
* output for lockdown.js if HtmlWebpackPlugin is in use
* @property {string[]} [inlineLockdown] - Prefix the listed files with lockdown
* @property {number} [diagnosticsVerbosity] - A number representing diagnostics
* output verbosity, the larger the more overwhelming
* @property {Object} [lockdown] - Options to pass to lockdown
* @property {Policy} [policy] - LavaMoat policy object - if programmaticly
* created
* @property {Object} [lockdown] - Options to pass to lockdown
* @property {string[]} [inlineLockdown] - Prefix the listed files with lockdown
* code
* @property {boolean} [runChecks] - Check resulting code with wrapping for
* correctness
*/

/**
Expand Down

0 comments on commit 5119a84

Please sign in to comment.