![](\"example/graphs/full.svg\" "\\"Files")
\n\nWe add an edge from `\"./package.json\"` to the module's main file.\nThen we filter edges ([code][graph-filter]) to include only those\nreachable from `\"./package.json\"`. This lets us distinguish files\nloaded by the test runner and tests from those loaded after control\nhas entered an API in a production file.\n\nThe resulting graph is much simpler:\n\n\n\nNote that the production file list includes dynamically and lazily\nloaded files. It does include `./lib/opt2.js` but not `./lib/opt1.js`.\nThe former file does not exist, so the loop which picks the first\navailable alternative tries and finds the latter.\n\nOur production source list should include all the files we need\nin production if\n\n* The unit tests `require` the main file\n* The unit tests have enough coverage to load all modules required\n in production via APIs defined in the main file or in APIs\n transitively loaded from there.\n\nIt is definitely possible to miss some files. If the unit test did\nnot call `app.lazyLoad` then there would be no edge to\n`./lib/lazy.js`. To address this, developers can\n\n* Expand test coverage to exercise code paths that load the\n missing source files.\n* Or add an explicit whitelist like\n ```js\n // production-source-whitelist.js\n require('./index.js');\n require('./lib/lazy.js');\n ```\n and explicitly pass this as the main file to the filter\n instead of defaulting to the one specified in `package.json`.\n\nDynamic analysis is not perfect, but a missing source file is\nreadily apparent, so this replaces\n\n* hard-to-detect bugs with potentially severe security consequences,\n\nwith\n\n* easy-to-detect bugs with negligible security consequences.\n\n[extract-script]: https://github.com/google/node-sec-roadmap/blob/master/chapter-2/example/make_dep_graph.sh\n[graph-filter]: https://github.com/google/node-sec-roadmap/blob/6130b76446ff4efbb276d8128c12e41ea2fffbc9/chapter-2/example/make_dep_graph.sh#L39-L73\n"
},
{
"path": "chapter-2/dynamism.md",
"content": "# Dynamism when you need it\n\n## Background\n\nNode.js code is composed of CommonJS modules that are linked together\nby the builtin `require` function, or [`import`][import-js] statements\n(used by [TypeScript][import-ts]) that typically transpile to\n`require` (modulo [experimental features][esm]).\n\n`require` itself calls `Module._load` ([code][Module._load]) to\nresolve and load code. [\"The Node.js Way\"][FKS] explains this flow\nwell.\n\nUnlike `import`, `require` is dynamic: a runtime value can specify the\nname of a module to load. (The EcmaScript committee is considering a\n[dynamic `import` operator][import-op-strawman], but we have\nnot included that in this analysis.)\n\n\nThis dynamism is powerful and flexible and enables varied use cases\nlike the following:\n\n* Lazy loading. Waiting to load a dependency until it is definitely needed.\n ```js\n const infrequentlyUsedAPI = (function () {\n const dependency = require('dependency');\n return function infrequentlyUsedAPI() {\n // Use dependency\n };\n }());\n ```\n* Loading plugins based on a configuration object.\n ```js\n function Service(config) {\n (config.plugins || []).forEach(\n (pluginName) => {\n require(pluginName).initPlugin(this);\n });\n }\n ```\n* Falling back to an alternate service provider if the first choice\n isn't available:\n ```js\n const KNOWN_SERVICE_PROVIDERS = ['foo-widget', 'bar-widget'];\n const serviceProviderName = KNOWN_SERVICE_PROVIDERS.find(\n (name) => {\n try {\n require.resolve(name);\n return true;\n } catch (_) {\n return false;\n }\n });\n const serviceProvider = require(serviceProviderName);\n ```\n* Taking advantage of an optional dependency when it is available.\n ```js\n let optionalDependency = null;\n try {\n optionalDependency = require('optionalDependency');\n } catch (_) {\n // Oh well.\n }\n ```\n* Loading a handler for a runtime value based on a naming convention.\n ```js\n function handle(request) {\n const handlerName = request.type + '-handler'; // Documented convention\n let handler;\n try {\n handler = require(handlerName);\n } catch (e) {\n throw new Error(\n 'Expected handler ' + handlerName\n + ' for requests with type ' + request.type);\n }\n return handler.handle(request);\n }\n ```\n* Introspecting over module metadata.\n ```js\n const version = require('./package.json').version;\n ```\n\nDuring rapid development, [file-system monitors][nodemon] can restart\na node project when source files change, and the application stitches\nitself together without the complex compiler and build system\nintegration that statically compiled languages use to do incremental\nrecompilation.\n\n\n## Problem\n\nThreats: [DEX][] [RCE][] [UIR][]\n\nThe `node_modules` directory does not keep production code separate\nfrom test code. If test code can be `require`d in production, then\nan attacker may find it far easier to execute a wide variety of other\nattacks. See [UIR][] for more details on this.\n\nNode applications rely on dynamic uses of `require` and changes that\nbreak any of these use cases would require coordinating large scale\nchanges to existing code, tools, and development practices threatening\n[developer experience][DEX].\n\nRequiring developers to pick and choose which source files are\nproduction and which are test would either:\n\n* Require them to scrutinize source files not only for their project\n but also for deep dependencies with which they are unfamiliar\n leading to poor developer experience.\n* Whitelist without scrutiny leading to the original security problem.\n* Lead them to not use available modules to solve problems and instead\n roll their own leading to poor developer experience, and possibly\n [LQC][] problems.\n\nWe need to ensure that only source code written with production\nconstraints in mind loads in production without increasing the burden\non developers.\n\nWhen the behavior of code in production is markedly different from that\non a developer's workstation, developers lose confidence that they\ncan avoid bugs in production by testing locally which may lead\nto poor developer experience and lower quality code.\n\n\n## Success Criteria\n\nWe would have prevented abuse of `require` if:\n\n* Untrusted inputs could not cause `require` to load a\n non-production source file,\n* and/or no non-production source files are reachable by\n `require`,\n* and/or loading a non-production source file has no adverse effect.\n\nWe would have successfully prevented abuse of `eval`, `new Function`\nand related operators if:\n\n* Untrusted inputs cannot reach an `eval` operator,\n* and/or untrusted inputs that reach them cause no adverse affects,\n* and/or security specialists could whitelist uses of `eval` operators\n that are necessary for the functioning of the larger\n system and compatible with the system's security goals.\n\nIn both cases, converting dynamic operators to static before untrusted\ninputs reach the system reduces the attack surface. Requiring\nlarge-scale changes to existing npm modules or requiring large scale\nrewrites of code that uses using them constitutes compromises [DEX][].\n\n\n## Current practices\n\nSome development teams use [webpack][] or similar tools to statically\nbundle server-side modules, and provide flexible transpilation\npipelines. That's a great way to do things, but solving security\nproblems only for teams with development practices mature enough to\ndeploy via webpack risks preaching to the choir.\n\nWebpack, in its minimal configuration, does not attempt to skip\ntest files ([code][webpack-experiment]).\nTeams with an experienced webpack user can use it to great effect, but\nit is not an out-of-the-box solution.\n\nWebpacking does not prevent calls to `require(...)` with unintended\narguments, but greatly reduces the chance that they will load\nnon-production code. As long as the server process cannot read\nJS files other than those in the bundle, then a webpacked server\nis safe from [UIR][]. This may not be the case if the production\nmachine has npm modules globally installed, and the server process\nis not running in a [chroot jail][].\n\n\n## A Possible Solution\n\nWe present one possible solution to demonstrate that tackling this\nproblem is feasible.\n\nIf we can compute the entire set of `require`-able sources when\ndealing only with inputs from trusted sources, then we can\nensure that the node runtime only loads those sources even when\nexposed to untrusted inputs.\n\nWe propose these changes:\n\n* A two phase approach to prevent abuse of `require`.\n 1. Tweaks to the node module loader that make it easy to\n [dynamically bundle](bundling.md) a release candidate.\n 2. Tweaks to the node module loader in production to restrict\n code loads based on [source content hashes](source-contents.md)\n from the bundling phase.\n* Two different strategies for preventing abuse of\n [`eval`](what-about-eval.md).\n * JavaScript idioms that can allow many uses of `eval` to\n [load as modules](synthetic-modules.md) and to bundle as above.\n * Using JavaScript engine callbacks to\n [allow uses of `eval`](bounded-eval.md) by approved modules.\n\n[DEX]: ../chapter-1/threat-DEX.md\n[LQC]: ../chapter-1/threat-LQC.md\n[RCE]: ../chapter-1/threat-RCE.md\n[UIR]: ../chapter-1/threat-UIR.md\n[webpack]: https://webpack.js.org/\n[Symbol]: (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol)\n[import-js]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import\n[import-ts]: https://www.typescriptlang.org/docs/handbook/modules.html#import\n[Module._load]: https://github.com/nodejs/node/blob/0fdd88a374e23e1dd4a05d93afd5eb0c3b080fd5/lib/module.js#L449\n[FKS]: http://fredkschott.com/post/2014/06/require-and-the-module-system/\n[esm]: https://nodejs.org/api/esm.html#esm_ecmascript_modules\n[nodemon]: https://nodemon.io/\n[import-op-strawman]: https://github.com/tc39/proposal-dynamic-import\n[chroot jail]: https://help.ubuntu.com/community/BasicChroot\n[webpack-experiment]: https://github.com/google/node-sec-roadmap/tree/master/chapter-2/experiments/webpack-compat\n"
},
{
"path": "chapter-2/example/.gitignore",
"content": "node_modules\n"
},
{
"path": "chapter-2/example/graphs/filtered.dot",
"content": "digraph Modules {\n \"./package.json\" [fillcolor=black,fontcolor=white,style=filled];\n \"./index.js\" -> \"./lib/static.js\";\n \"./index.js\" -> \"./lib/dynamic.js\";\n \"./index.js\" -> \"./lib/opt2.js\";\n \"./index.js\" -> \"./lib/lazy.js\";\n \"./package.json\" -> \"./index.js\";\n}\n"
},
{
"path": "chapter-2/example/graphs/full.dot",
"content": "digraph Modules {\n \"./node_modules/mocha/bin/mocha\" -> \"./node_modules/mocha/bin/options.js\";\n \"./node_modules/mocha/bin/_mocha\" -> \"./node_modules/commander/index.js\";\n \"./node_modules/mocha/bin/_mocha\" -> \"./node_modules/mocha/index.js\";\n \"./node_modules/mocha/index.js\" -> \"./node_modules/mocha/lib/mocha.js\";\n \"./node_modules/mocha/lib/mocha.js\" -> \"./node_modules/escape-string-regexp/index.js\";\n \"./node_modules/mocha/lib/mocha.js\" -> \"./node_modules/mocha/lib/reporters/index.js\";\n \"./node_modules/mocha/lib/reporters/index.js\" -> \"./node_modules/mocha/lib/reporters/base.js\";\n \"./node_modules/mocha/lib/reporters/base.js\" -> \"./node_modules/diff/lib/index.js\";\n \"./node_modules/diff/lib/index.js\" -> \"./node_modules/diff/lib/diff/base.js\";\n \"./node_modules/diff/lib/index.js\" -> \"./node_modules/diff/lib/diff/character.js\";\n \"./node_modules/diff/lib/diff/character.js\" -> \"./node_modules/diff/lib/diff/base.js\";\n \"./node_modules/diff/lib/index.js\" -> \"./node_modules/diff/lib/diff/word.js\";\n \"./node_modules/diff/lib/diff/word.js\" -> \"./node_modules/diff/lib/diff/base.js\";\n \"./node_modules/diff/lib/diff/word.js\" -> \"./node_modules/diff/lib/util/params.js\";\n \"./node_modules/diff/lib/index.js\" -> \"./node_modules/diff/lib/diff/line.js\";\n \"./node_modules/diff/lib/diff/line.js\" -> \"./node_modules/diff/lib/diff/base.js\";\n \"./node_modules/diff/lib/diff/line.js\" -> \"./node_modules/diff/lib/util/params.js\";\n \"./node_modules/diff/lib/index.js\" -> \"./node_modules/diff/lib/diff/sentence.js\";\n \"./node_modules/diff/lib/diff/sentence.js\" -> \"./node_modules/diff/lib/diff/base.js\";\n \"./node_modules/diff/lib/index.js\" -> \"./node_modules/diff/lib/diff/css.js\";\n \"./node_modules/diff/lib/diff/css.js\" -> \"./node_modules/diff/lib/diff/base.js\";\n \"./node_modules/diff/lib/index.js\" -> \"./node_modules/diff/lib/diff/json.js\";\n \"./node_modules/diff/lib/diff/json.js\" -> \"./node_modules/diff/lib/diff/base.js\";\n \"./node_modules/diff/lib/diff/json.js\" -> \"./node_modules/diff/lib/diff/line.js\";\n \"./node_modules/diff/lib/index.js\" -> \"./node_modules/diff/lib/diff/array.js\";\n \"./node_modules/diff/lib/diff/array.js\" -> \"./node_modules/diff/lib/diff/base.js\";\n \"./node_modules/diff/lib/index.js\" -> \"./node_modules/diff/lib/patch/apply.js\";\n \"./node_modules/diff/lib/patch/apply.js\" -> \"./node_modules/diff/lib/patch/parse.js\";\n \"./node_modules/diff/lib/patch/apply.js\" -> \"./node_modules/diff/lib/util/distance-iterator.js\";\n \"./node_modules/diff/lib/index.js\" -> \"./node_modules/diff/lib/patch/parse.js\";\n \"./node_modules/diff/lib/index.js\" -> \"./node_modules/diff/lib/patch/merge.js\";\n \"./node_modules/diff/lib/patch/merge.js\" -> \"./node_modules/diff/lib/patch/create.js\";\n \"./node_modules/diff/lib/patch/create.js\" -> \"./node_modules/diff/lib/diff/line.js\";\n \"./node_modules/diff/lib/patch/merge.js\" -> \"./node_modules/diff/lib/patch/parse.js\";\n \"./node_modules/diff/lib/patch/merge.js\" -> \"./node_modules/diff/lib/util/array.js\";\n \"./node_modules/diff/lib/index.js\" -> \"./node_modules/diff/lib/patch/create.js\";\n \"./node_modules/diff/lib/index.js\" -> \"./node_modules/diff/lib/convert/dmp.js\";\n \"./node_modules/diff/lib/index.js\" -> \"./node_modules/diff/lib/convert/xml.js\";\n \"./node_modules/mocha/lib/reporters/base.js\" -> \"./node_modules/mocha/lib/ms.js\";\n \"./node_modules/mocha/lib/reporters/base.js\" -> \"./node_modules/mocha/lib/utils.js\";\n \"./node_modules/mocha/lib/utils.js\" -> \"./node_modules/debug/src/index.js\";\n \"./node_modules/debug/src/index.js\" -> \"./node_modules/debug/src/node.js\";\n \"./node_modules/debug/src/node.js\" -> \"./node_modules/debug/src/debug.js\";\n \"./node_modules/debug/src/debug.js\" -> \"./node_modules/ms/index.js\";\n \"./node_modules/debug/src/node.js\" -> \"./node_modules/supports-color/index.js\";\n \"./node_modules/supports-color/index.js\" -> \"./node_modules/has-flag/index.js\";\n \"./node_modules/mocha/lib/utils.js\" -> \"./node_modules/glob/glob.js\";\n \"./node_modules/glob/glob.js\" -> \"./node_modules/fs.realpath/index.js\";\n \"./node_modules/fs.realpath/index.js\" -> \"./node_modules/fs.realpath/old.js\";\n \"./node_modules/glob/glob.js\" -> \"./node_modules/minimatch/minimatch.js\";\n \"./node_modules/minimatch/minimatch.js\" -> \"./node_modules/brace-expansion/index.js\";\n \"./node_modules/brace-expansion/index.js\" -> \"./node_modules/concat-map/index.js\";\n \"./node_modules/brace-expansion/index.js\" -> \"./node_modules/balanced-match/index.js\";\n \"./node_modules/glob/glob.js\" -> \"./node_modules/inherits/inherits.js\";\n \"./node_modules/glob/glob.js\" -> \"./node_modules/path-is-absolute/index.js\";\n \"./node_modules/glob/glob.js\" -> \"./node_modules/glob/sync.js\";\n \"./node_modules/glob/sync.js\" -> \"./node_modules/fs.realpath/index.js\";\n \"./node_modules/glob/sync.js\" -> \"./node_modules/minimatch/minimatch.js\";\n \"./node_modules/glob/sync.js\" -> \"./node_modules/glob/glob.js\";\n \"./node_modules/glob/sync.js\" -> \"./node_modules/path-is-absolute/index.js\";\n \"./node_modules/glob/sync.js\" -> \"./node_modules/glob/common.js\";\n \"./node_modules/glob/common.js\" -> \"./node_modules/minimatch/minimatch.js\";\n \"./node_modules/glob/common.js\" -> \"./node_modules/path-is-absolute/index.js\";\n \"./node_modules/glob/glob.js\" -> \"./node_modules/glob/common.js\";\n \"./node_modules/glob/glob.js\" -> \"./node_modules/inflight/inflight.js\";\n \"./node_modules/inflight/inflight.js\" -> \"./node_modules/wrappy/wrappy.js\";\n \"./node_modules/inflight/inflight.js\" -> \"./node_modules/once/once.js\";\n \"./node_modules/once/once.js\" -> \"./node_modules/wrappy/wrappy.js\";\n \"./node_modules/glob/glob.js\" -> \"./node_modules/once/once.js\";\n \"./node_modules/mocha/lib/utils.js\" -> \"./node_modules/he/he.js\";\n \"./node_modules/mocha/lib/reporters/base.js\" -> \"./node_modules/supports-color/index.js\";\n \"./node_modules/mocha/lib/reporters/index.js\" -> \"./node_modules/mocha/lib/reporters/dot.js\";\n \"./node_modules/mocha/lib/reporters/dot.js\" -> \"./node_modules/mocha/lib/reporters/base.js\";\n \"./node_modules/mocha/lib/reporters/dot.js\" -> \"./node_modules/mocha/lib/utils.js\";\n \"./node_modules/mocha/lib/reporters/index.js\" -> \"./node_modules/mocha/lib/reporters/doc.js\";\n \"./node_modules/mocha/lib/reporters/doc.js\" -> \"./node_modules/mocha/lib/reporters/base.js\";\n \"./node_modules/mocha/lib/reporters/doc.js\" -> \"./node_modules/mocha/lib/utils.js\";\n \"./node_modules/mocha/lib/reporters/index.js\" -> \"./node_modules/mocha/lib/reporters/tap.js\";\n \"./node_modules/mocha/lib/reporters/tap.js\" -> \"./node_modules/mocha/lib/reporters/base.js\";\n \"./node_modules/mocha/lib/reporters/index.js\" -> \"./node_modules/mocha/lib/reporters/json.js\";\n \"./node_modules/mocha/lib/reporters/json.js\" -> \"./node_modules/mocha/lib/reporters/base.js\";\n \"./node_modules/mocha/lib/reporters/index.js\" -> \"./node_modules/mocha/lib/reporters/html.js\";\n \"./node_modules/mocha/lib/reporters/html.js\" -> \"./node_modules/mocha/lib/reporters/base.js\";\n \"./node_modules/mocha/lib/reporters/html.js\" -> \"./node_modules/mocha/lib/utils.js\";\n \"./node_modules/mocha/lib/reporters/html.js\" -> \"./node_modules/mocha/lib/browser/progress.js\";\n \"./node_modules/mocha/lib/reporters/html.js\" -> \"./node_modules/escape-string-regexp/index.js\";\n \"./node_modules/mocha/lib/reporters/index.js\" -> \"./node_modules/mocha/lib/reporters/list.js\";\n \"./node_modules/mocha/lib/reporters/list.js\" -> \"./node_modules/mocha/lib/reporters/base.js\";\n \"./node_modules/mocha/lib/reporters/list.js\" -> \"./node_modules/mocha/lib/utils.js\";\n \"./node_modules/mocha/lib/reporters/index.js\" -> \"./node_modules/mocha/lib/reporters/min.js\";\n \"./node_modules/mocha/lib/reporters/min.js\" -> \"./node_modules/mocha/lib/reporters/base.js\";\n \"./node_modules/mocha/lib/reporters/min.js\" -> \"./node_modules/mocha/lib/utils.js\";\n \"./node_modules/mocha/lib/reporters/index.js\" -> \"./node_modules/mocha/lib/reporters/spec.js\";\n \"./node_modules/mocha/lib/reporters/spec.js\" -> \"./node_modules/mocha/lib/reporters/base.js\";\n \"./node_modules/mocha/lib/reporters/spec.js\" -> \"./node_modules/mocha/lib/utils.js\";\n \"./node_modules/mocha/lib/reporters/index.js\" -> \"./node_modules/mocha/lib/reporters/nyan.js\";\n \"./node_modules/mocha/lib/reporters/nyan.js\" -> \"./node_modules/mocha/lib/reporters/base.js\";\n \"./node_modules/mocha/lib/reporters/nyan.js\" -> \"./node_modules/mocha/lib/utils.js\";\n \"./node_modules/mocha/lib/reporters/index.js\" -> \"./node_modules/mocha/lib/reporters/xunit.js\";\n \"./node_modules/mocha/lib/reporters/xunit.js\" -> \"./node_modules/mocha/lib/reporters/base.js\";\n \"./node_modules/mocha/lib/reporters/xunit.js\" -> \"./node_modules/mocha/lib/utils.js\";\n \"./node_modules/mocha/lib/reporters/xunit.js\" -> \"./node_modules/mkdirp/index.js\";\n \"./node_modules/mocha/lib/reporters/index.js\" -> \"./node_modules/mocha/lib/reporters/markdown.js\";\n \"./node_modules/mocha/lib/reporters/markdown.js\" -> \"./node_modules/mocha/lib/reporters/base.js\";\n \"./node_modules/mocha/lib/reporters/markdown.js\" -> \"./node_modules/mocha/lib/utils.js\";\n \"./node_modules/mocha/lib/reporters/index.js\" -> \"./node_modules/mocha/lib/reporters/progress.js\";\n \"./node_modules/mocha/lib/reporters/progress.js\" -> \"./node_modules/mocha/lib/reporters/base.js\";\n \"./node_modules/mocha/lib/reporters/progress.js\" -> \"./node_modules/mocha/lib/utils.js\";\n \"./node_modules/mocha/lib/reporters/index.js\" -> \"./node_modules/mocha/lib/reporters/landing.js\";\n \"./node_modules/mocha/lib/reporters/landing.js\" -> \"./node_modules/mocha/lib/reporters/base.js\";\n \"./node_modules/mocha/lib/reporters/landing.js\" -> \"./node_modules/mocha/lib/utils.js\";\n \"./node_modules/mocha/lib/reporters/index.js\" -> \"./node_modules/mocha/lib/reporters/json-stream.js\";\n \"./node_modules/mocha/lib/reporters/json-stream.js\" -> \"./node_modules/mocha/lib/reporters/base.js\";\n \"./node_modules/mocha/lib/mocha.js\" -> \"./node_modules/mocha/lib/utils.js\";\n \"./node_modules/mocha/lib/mocha.js\" -> \"./node_modules/mocha/lib/interfaces/index.js\";\n \"./node_modules/mocha/lib/interfaces/index.js\" -> \"./node_modules/mocha/lib/interfaces/bdd.js\";\n \"./node_modules/mocha/lib/interfaces/bdd.js\" -> \"./node_modules/mocha/lib/test.js\";\n \"./node_modules/mocha/lib/test.js\" -> \"./node_modules/mocha/lib/runnable.js\";\n \"./node_modules/mocha/lib/runnable.js\" -> \"./node_modules/mocha/lib/pending.js\";\n \"./node_modules/mocha/lib/runnable.js\" -> \"./node_modules/debug/src/index.js\";\n \"./node_modules/mocha/lib/runnable.js\" -> \"./node_modules/mocha/lib/ms.js\";\n \"./node_modules/mocha/lib/runnable.js\" -> \"./node_modules/mocha/lib/utils.js\";\n \"./node_modules/mocha/lib/test.js\" -> \"./node_modules/mocha/lib/utils.js\";\n \"./node_modules/mocha/lib/interfaces/index.js\" -> \"./node_modules/mocha/lib/interfaces/tdd.js\";\n \"./node_modules/mocha/lib/interfaces/tdd.js\" -> \"./node_modules/mocha/lib/test.js\";\n \"./node_modules/mocha/lib/interfaces/index.js\" -> \"./node_modules/mocha/lib/interfaces/qunit.js\";\n \"./node_modules/mocha/lib/interfaces/qunit.js\" -> \"./node_modules/mocha/lib/test.js\";\n \"./node_modules/mocha/lib/interfaces/index.js\" -> \"./node_modules/mocha/lib/interfaces/exports.js\";\n \"./node_modules/mocha/lib/interfaces/exports.js\" -> \"./node_modules/mocha/lib/suite.js\";\n \"./node_modules/mocha/lib/suite.js\" -> \"./node_modules/mocha/lib/hook.js\";\n \"./node_modules/mocha/lib/hook.js\" -> \"./node_modules/mocha/lib/runnable.js\";\n \"./node_modules/mocha/lib/hook.js\" -> \"./node_modules/mocha/lib/utils.js\";\n \"./node_modules/mocha/lib/suite.js\" -> \"./node_modules/mocha/lib/utils.js\";\n \"./node_modules/mocha/lib/suite.js\" -> \"./node_modules/debug/src/index.js\";\n \"./node_modules/mocha/lib/suite.js\" -> \"./node_modules/mocha/lib/ms.js\";\n \"./node_modules/mocha/lib/interfaces/exports.js\" -> \"./node_modules/mocha/lib/test.js\";\n \"./node_modules/mocha/lib/mocha.js\" -> \"./node_modules/mocha/lib/runnable.js\";\n \"./node_modules/mocha/lib/mocha.js\" -> \"./node_modules/mocha/lib/context.js\";\n \"./node_modules/mocha/lib/mocha.js\" -> \"./node_modules/mocha/lib/runner.js\";\n \"./node_modules/mocha/lib/runner.js\" -> \"./node_modules/mocha/lib/pending.js\";\n \"./node_modules/mocha/lib/runner.js\" -> \"./node_modules/mocha/lib/utils.js\";\n \"./node_modules/mocha/lib/runner.js\" -> \"./node_modules/debug/src/index.js\";\n \"./node_modules/mocha/lib/runner.js\" -> \"./node_modules/mocha/lib/runnable.js\";\n \"./node_modules/mocha/lib/mocha.js\" -> \"./node_modules/mocha/lib/suite.js\";\n \"./node_modules/mocha/lib/mocha.js\" -> \"./node_modules/mocha/lib/hook.js\";\n \"./node_modules/mocha/lib/mocha.js\" -> \"./node_modules/mocha/lib/test.js\";\n \"./node_modules/mocha/bin/_mocha\" -> \"./node_modules/mocha/bin/options.js\";\n \"./node_modules/mocha/bin/_mocha\" -> \"./node_modules/mocha/lib/reporters/spec.js\";\n \"./node_modules/mocha/lib/interfaces/bdd.js\" -> \"./node_modules/mocha/lib/interfaces/common.js\";\n \"./node_modules/mocha/lib/interfaces/common.js\" -> \"./node_modules/mocha/lib/suite.js\";\n \"./node_modules/mocha/lib/mocha.js\" -> \"./test/test.js\";\n \"./test/test.js\" -> \"./node_modules/chai/index.js\";\n \"./node_modules/chai/index.js\" -> \"./node_modules/chai/lib/chai.js\";\n \"./node_modules/chai/lib/chai.js\" -> \"./node_modules/assertion-error/index.js\";\n \"./node_modules/chai/lib/chai.js\" -> \"./node_modules/chai/lib/chai/utils/index.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/pathval/index.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/test.js\";\n \"./node_modules/chai/lib/chai/utils/test.js\" -> \"./node_modules/chai/lib/chai/utils/flag.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/type-detect/type-detect.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/expectTypes.js\";\n \"./node_modules/chai/lib/chai/utils/expectTypes.js\" -> \"./node_modules/assertion-error/index.js\";\n \"./node_modules/chai/lib/chai/utils/expectTypes.js\" -> \"./node_modules/chai/lib/chai/utils/flag.js\";\n \"./node_modules/chai/lib/chai/utils/expectTypes.js\" -> \"./node_modules/type-detect/type-detect.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/getMessage.js\";\n \"./node_modules/chai/lib/chai/utils/getMessage.js\" -> \"./node_modules/chai/lib/chai/utils/flag.js\";\n \"./node_modules/chai/lib/chai/utils/getMessage.js\" -> \"./node_modules/chai/lib/chai/utils/getActual.js\";\n \"./node_modules/chai/lib/chai/utils/getMessage.js\" -> \"./node_modules/chai/lib/chai/utils/inspect.js\";\n \"./node_modules/chai/lib/chai/utils/inspect.js\" -> \"./node_modules/get-func-name/index.js\";\n \"./node_modules/chai/lib/chai/utils/inspect.js\" -> \"./node_modules/chai/lib/chai/utils/getProperties.js\";\n \"./node_modules/chai/lib/chai/utils/inspect.js\" -> \"./node_modules/chai/lib/chai/utils/getEnumerableProperties.js\";\n \"./node_modules/chai/lib/chai/utils/inspect.js\" -> \"./node_modules/chai/lib/chai/config.js\";\n \"./node_modules/chai/lib/chai/utils/getMessage.js\" -> \"./node_modules/chai/lib/chai/utils/objDisplay.js\";\n \"./node_modules/chai/lib/chai/utils/objDisplay.js\" -> \"./node_modules/chai/lib/chai/utils/inspect.js\";\n \"./node_modules/chai/lib/chai/utils/objDisplay.js\" -> \"./node_modules/chai/lib/chai/config.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/getActual.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/inspect.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/objDisplay.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/flag.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/transferFlags.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/deep-eql/index.js\";\n \"./node_modules/deep-eql/index.js\" -> \"./node_modules/type-detect/type-detect.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/get-func-name/index.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/addProperty.js\";\n \"./node_modules/chai/lib/chai/utils/addProperty.js\" -> \"./node_modules/chai/lib/chai.js\";\n \"./node_modules/chai/lib/chai/utils/addProperty.js\" -> \"./node_modules/chai/lib/chai/utils/flag.js\";\n \"./node_modules/chai/lib/chai/utils/addProperty.js\" -> \"./node_modules/chai/lib/chai/utils/isProxyEnabled.js\";\n \"./node_modules/chai/lib/chai/utils/isProxyEnabled.js\" -> \"./node_modules/chai/lib/chai/config.js\";\n \"./node_modules/chai/lib/chai/utils/addProperty.js\" -> \"./node_modules/chai/lib/chai/utils/transferFlags.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/addMethod.js\";\n \"./node_modules/chai/lib/chai/utils/addMethod.js\" -> \"./node_modules/chai/lib/chai/utils/addLengthGuard.js\";\n \"./node_modules/chai/lib/chai/utils/addLengthGuard.js\" -> \"./node_modules/chai/lib/chai/config.js\";\n \"./node_modules/chai/lib/chai/utils/addMethod.js\" -> \"./node_modules/chai/lib/chai.js\";\n \"./node_modules/chai/lib/chai/utils/addMethod.js\" -> \"./node_modules/chai/lib/chai/utils/flag.js\";\n \"./node_modules/chai/lib/chai/utils/addMethod.js\" -> \"./node_modules/chai/lib/chai/utils/proxify.js\";\n \"./node_modules/chai/lib/chai/utils/proxify.js\" -> \"./node_modules/chai/lib/chai/config.js\";\n \"./node_modules/chai/lib/chai/utils/proxify.js\" -> \"./node_modules/chai/lib/chai/utils/flag.js\";\n \"./node_modules/chai/lib/chai/utils/proxify.js\" -> \"./node_modules/chai/lib/chai/utils/getProperties.js\";\n \"./node_modules/chai/lib/chai/utils/proxify.js\" -> \"./node_modules/chai/lib/chai/utils/isProxyEnabled.js\";\n \"./node_modules/chai/lib/chai/utils/addMethod.js\" -> \"./node_modules/chai/lib/chai/utils/transferFlags.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/overwriteProperty.js\";\n \"./node_modules/chai/lib/chai/utils/overwriteProperty.js\" -> \"./node_modules/chai/lib/chai.js\";\n \"./node_modules/chai/lib/chai/utils/overwriteProperty.js\" -> \"./node_modules/chai/lib/chai/utils/flag.js\";\n \"./node_modules/chai/lib/chai/utils/overwriteProperty.js\" -> \"./node_modules/chai/lib/chai/utils/isProxyEnabled.js\";\n \"./node_modules/chai/lib/chai/utils/overwriteProperty.js\" -> \"./node_modules/chai/lib/chai/utils/transferFlags.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/overwriteMethod.js\";\n \"./node_modules/chai/lib/chai/utils/overwriteMethod.js\" -> \"./node_modules/chai/lib/chai/utils/addLengthGuard.js\";\n \"./node_modules/chai/lib/chai/utils/overwriteMethod.js\" -> \"./node_modules/chai/lib/chai.js\";\n \"./node_modules/chai/lib/chai/utils/overwriteMethod.js\" -> \"./node_modules/chai/lib/chai/utils/flag.js\";\n \"./node_modules/chai/lib/chai/utils/overwriteMethod.js\" -> \"./node_modules/chai/lib/chai/utils/proxify.js\";\n \"./node_modules/chai/lib/chai/utils/overwriteMethod.js\" -> \"./node_modules/chai/lib/chai/utils/transferFlags.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/addChainableMethod.js\";\n \"./node_modules/chai/lib/chai/utils/addChainableMethod.js\" -> \"./node_modules/chai/lib/chai/utils/addLengthGuard.js\";\n \"./node_modules/chai/lib/chai/utils/addChainableMethod.js\" -> \"./node_modules/chai/lib/chai.js\";\n \"./node_modules/chai/lib/chai/utils/addChainableMethod.js\" -> \"./node_modules/chai/lib/chai/utils/flag.js\";\n \"./node_modules/chai/lib/chai/utils/addChainableMethod.js\" -> \"./node_modules/chai/lib/chai/utils/proxify.js\";\n \"./node_modules/chai/lib/chai/utils/addChainableMethod.js\" -> \"./node_modules/chai/lib/chai/utils/transferFlags.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/overwriteChainableMethod.js\";\n \"./node_modules/chai/lib/chai/utils/overwriteChainableMethod.js\" -> \"./node_modules/chai/lib/chai.js\";\n \"./node_modules/chai/lib/chai/utils/overwriteChainableMethod.js\" -> \"./node_modules/chai/lib/chai/utils/transferFlags.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/compareByInspect.js\";\n \"./node_modules/chai/lib/chai/utils/compareByInspect.js\" -> \"./node_modules/chai/lib/chai/utils/inspect.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/getOwnEnumerablePropertySymbols.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/getOwnEnumerableProperties.js\";\n \"./node_modules/chai/lib/chai/utils/getOwnEnumerableProperties.js\" -> \"./node_modules/chai/lib/chai/utils/getOwnEnumerablePropertySymbols.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/check-error/index.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/proxify.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/addLengthGuard.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/isProxyEnabled.js\";\n \"./node_modules/chai/lib/chai/utils/index.js\" -> \"./node_modules/chai/lib/chai/utils/isNaN.js\";\n \"./node_modules/chai/lib/chai.js\" -> \"./node_modules/chai/lib/chai/config.js\";\n \"./node_modules/chai/lib/chai.js\" -> \"./node_modules/chai/lib/chai/assertion.js\";\n \"./node_modules/chai/lib/chai/assertion.js\" -> \"./node_modules/chai/lib/chai/config.js\";\n \"./node_modules/chai/lib/chai.js\" -> \"./node_modules/chai/lib/chai/core/assertions.js\";\n \"./node_modules/chai/lib/chai.js\" -> \"./node_modules/chai/lib/chai/interface/expect.js\";\n \"./node_modules/chai/lib/chai.js\" -> \"./node_modules/chai/lib/chai/interface/should.js\";\n \"./node_modules/chai/lib/chai.js\" -> \"./node_modules/chai/lib/chai/interface/assert.js\";\n \"./test/test.js\" -> \"./index.js\";\n \"./index.js\" -> \"./lib/static.js\";\n \"./index.js\" -> \"./lib/dynamic.js\";\n \"./index.js\" -> \"./lib/opt2.js\";\n \"./index.js\" -> \"./lib/lazy.js\";\n \"./package.json\" -> \"./index.js\";\n \"./package.json\" [fillcolor=black,fontcolor=white,style=filled];\n}\n"
},
{
"path": "chapter-2/example/index.js",
"content": "/**\n * @license\n * Copyright 2017 Google LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n// index.js\n// Example that tests various kinds of loads.\n\nlet staticLoad = require('./lib/static');\nfunction dynamicLoad(f, x) {\n return f('./lib/' + x);\n}\ndynamicLoad(require, Math.random() < 2 ? 'dynamic' : 'bogus');\nexports.lazyLoad = () => require('./lib/lazy');\n\n// Fallback to alternatives\nrequire(['./lib/opt1', './lib/opt2'].find(\n (name) => {\n try {\n require.resolve(name);\n return true;\n } catch (_) {\n return false;\n }\n }));\n"
},
{
"path": "chapter-2/example/lib/dynamic.js",
"content": "/**\n * @license\n * Copyright 2017 Google LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n// lib/dynamic.js\n\nexports.x = 'dynamic';\n"
},
{
"path": "chapter-2/example/lib/lazy.js",
"content": "/**\n * @license\n * Copyright 2017 Google LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n// lib/lazy.js\n\nexports.x = 'lazy';\n"
},
{
"path": "chapter-2/example/lib/opt2.js",
"content": "/**\n * @license\n * Copyright 2017 Google LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n// lib/opt2.js\n\nexports.x = 'opt2';\n"
},
{
"path": "chapter-2/example/lib/static.js",
"content": "/**\n * @license\n * Copyright 2017 Google LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n// lib/static.js\n\nexports.x = 'static';\n"
},
{
"path": "chapter-2/example/make_dep_graph.sh",
"content": "#!/bin/bash\n\n# Copyright 2017 Google LLC\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# https://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nset -e\n\ncd \"$(dirname \"$0\")\"\n\nmkdir -p graphs\n(\n echo 'digraph Modules {'\n\n # Run the tests and filter the logs for log entries from our\n # hacked Module._load.\n # Also relativize source file paths.\n NODE=/Users/msamuel/work/node/out/Release/node \\\n PATH=\"/Users/msamuel/work/node/out/Release/:$PATH\" \\\n ./node_modules/.bin/mocha 2>&1 \\\n | perl -ne 's/\"$ENV{PWD}/\"./g; if (s/^REQUIRE_LOG_DOT://) { print $_; } else { print STDERR $_; }'\n\n # Add an edge from package.json to the main module.\n echo ' \"./package.json\" -> \"./index.js\";'\n echo ' \"./package.json\" [fillcolor=black,fontcolor=white,style=filled];'\n echo '}'\n) > graphs/full.dot\n\npython -c '\nimport re\nimport sys\n\nEDGE_RE = re.compile(r\"\"\"^ *(\\\"(?:[^\\\"\\\\]|\\\\.)*\\\") -> (\\\"(?:[^\\\"\\\\]|\\\\.)*\\\");$\"\"\")\nGRAPH_END_RE = re.compile(r\"^ *\\}\")\n\nedges = {}\ndef add_edge(src, tgt):\n tgts = edges.get(src)\n if tgts is None:\n tgts = []\n edges[src] = tgts\n tgts.append(tgt)\n\nfor line in sys.stdin:\n edges_match = EDGE_RE.match(line)\n if edges_match is not None:\n add_edge(edges_match.group(1), edges_match.group(2))\n continue\n elif GRAPH_END_RE.match(line):\n reachable = set()\n def find_reachable(src):\n if src not in reachable:\n reachable.add(src)\n for tgt in edges.get(src, ()):\n find_reachable(tgt)\n find_reachable(\"\\\"./package.json\\\"\")\n reachable = list(reachable)\n reachable.sort()\n for src in reachable:\n for tgt in edges.get(src, ()):\n print \" %s -> %s;\" % (src, tgt)\n print line,\n' < graphs/full.dot > graphs/filtered.dot\n\nfor graph in full filtered; do\n dot -Tsvg graphs/\"$graph\".dot > graphs/\"$graph\".svg\ndone\n\n# Start walking from package.json\n\n"
},
{
"path": "chapter-2/example/package.json",
"content": "{\n \"name\": \"dynamism-example\",\n \"private\": true,\n \"description\": \"Example code that shows dynamically walking the test graph\",\n \"main\": \"index.js\",\n \"scripts\": {\n \"test\": \"echo $NODE; ./node_modules/.bin/mocha\"\n },\n \"author\": \"Mike Samuel\",\n \"license\": \"Apache-2.0\",\n \"devDependencies\": {\n \"chai\": \">=4.1.2\",\n \"mocha\": \">=4.0.1\"\n }\n}\n"
},
{
"path": "chapter-2/example/test/test.js",
"content": "/**\n * @license\n * Copyright 2017 Google LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n// test/test.js\n\nvar expect = require(\"chai\").expect;\nvar app = require(\"../index\");\n\ndescribe(\"My TestSuite\", () => {\n describe(\"A test\", () => {\n it(\"A unittest\", () => {\n // Exercise the API\n app.lazyLoad();\n });\n });\n});\n"
},
{
"path": "chapter-2/experiments/webpack-compat/.gitignore",
"content": "dist\nnode_modules"
},
{
"path": "chapter-2/experiments/webpack-compat/goodbye.js",
"content": "/**\n * @license\n * Copyright 2017 Google LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexports.say = x => console.log(`Goodbye, ${x}!`);\n"
},
{
"path": "chapter-2/experiments/webpack-compat/hello.js",
"content": "/**\n * @license\n * Copyright 2017 Google LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexports.say = x => console.log(`Hello, ${x}!`);\n"
},
{
"path": "chapter-2/experiments/webpack-compat/index.js",
"content": "/**\n * @license\n * Copyright 2017 Google LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nvar metadata = require('./package.json');\nvar greeting = require('./' + metadata.greeting);\n\ngreeting.say('World');\n"
},
{
"path": "chapter-2/experiments/webpack-compat/package.json",
"content": "{\n \"name\": \"webpack-compat-experiment\",\n \"description\": \"Figuring out how well webpack deals with dynamic loads\",\n \"version\": \"0.0.0\",\n \"main\": \"index.js\",\n \"dependencies\": {},\n \"scripts\": {},\n \"author\": \"Mike Samuel\",\n \"license\": \"Apache-2.0\",\n \"greeting\": \"hello\",\n \"devDependencies\": {\n \"webpack\": \"^3.10.0\"\n }\n}\n"
},
{
"path": "chapter-2/experiments/webpack-compat/test/test.js",
"content": "/**\n * @license\n * Copyright 2017 Google LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nconsole.log('test/test.js: NOT PRODUCTION CODE');\n"
},
{
"path": "chapter-2/experiments/webpack-compat/test-utils.js",
"content": "/**\n * @license\n * Copyright 2017 Google LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexports.doSomethingScaryButItsOkInTest = function() {\n throw new Error('test-utils.js: NOT PRODUCTION CODE');\n};\n"
},
{
"path": "chapter-2/experiments/webpack-compat/test.sh",
"content": "echo <`...` it would find a resolved module ready but not\nloaded. If a module is already in the cache, `Module` skips the\nadditional content checks.\n\nThe Node runtime function, `makeRequireFunction`\n([code][makeRequireFunction]), defines a `require` for each module\nthat loads modules with the current module as the parent. That would\nalso have to define a module specific `require.synthesize` that does\nsomething like:\n\n```js\n function synthesize(content) {\n content = String(content);\n // Hashing gives us a stable identifier so that we can associate\n // code inlined during bundling with that loaded in production.\n const hash = crypto\n .createHash('sha512')\n .update(content, 'utf8')\n .digest();\n // A name that communicates the source while being\n // unambiguous with any actual file.\n const filename = '/dev/null/synthetic/' + hash;\n // We scope the identifier so that it is clear in\n // debugging trace that the module is synthetic and\n // to avoid leading existing tools to conclude that\n // it is available via registry.npmjs.org.\n const id = '@node-internal-synthetic/' + hash;\n const cache = Module._cache;\n let syntheticModule = cache[filename];\n if (syntheticModule) {\n // TODO: updateChildren(mod, syntheticModule, true);\n } else {\n cache[filename] = syntheticModule = new Module(id, mod);\n syntheticModule.loaded = true;\n syntheticModule._compile(content, filename);\n }\n // TODO: dump the module if the command line flags specify\n // a synthetic_node_modules/ output directory.\n return syntheticModule;\n }\n\n require.synthesize = synthesize;\n```\n\nStatic analysis tools often benefit from having a whole program\navailable. Humans can reason about external files, like `.pug` files,\nbut static analysis tools often have to be unsound, or assume the\nworst. Synthetic modules may provide a way to move a large chunk of\npreviously unanalyzable code into the domain of what static analysis\ntools can check.\n\nThis scheme, might be more discoverable if code generator authors\nadopted some conventions:\n\n* If a module defines `exports.lang` it should be usable as a\n template tag.\n* If that same function is called with an option map instead\n of as a template tag function, then it should return a function\n to enable usages like\n ```js\n pug.lang(myPugOptionMap)`\n doctype html\n ...`\n ```\n* If the first line starts with some whitespace, all subsequent\n lines have that same whitespace as a prefix, and the language\n is whitespace-sensitive, then strip it before processing.\n This would allow indenting inline DSLs within a larger\n JavaScript program.\n\nWe discuss template tag usability concerns in more detail later when\ndiscussing [library tweaks][library].\n\nThis proposal has one major drawback: we still have to trust the code\ngenerator. Pug's code generator looks well structured, but reasoning\nabout all the code produced by a code generator is harder than\nreasoning about one hand-written module. The [frozen realms][] proposal\nrestricts code to a provided API like\n`vm.runInNewContext` aimed to. If Pug, for example, chose to load its\ncode in a sandbox, then checking just the provided context would give\nus confidence about what generated code could do. In some cases, we\nmight be able to move code generator outside the\n[*trusted computing base*][TCB].\n\n[tagged template literal]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals\n[pug-eval]: https://github.com/pugjs/pug/blob/926f7c720112cac76cfedb003e25e9f43d3a1767/packages/pug/lib/index.js#L261-L263\n[library]: ../chapter-7/libraries.md\n[makeRequireFunction]: https://github.com/nodejs/node/blob/8f5040771475ca5435b6cb78ab2ebce7447afcc1/lib/internal/module.js#L5\n[frozen realms]: https://github.com/tc39/proposal-frozen-realms\n[TCB]: https://en.wikipedia.org/wiki/Trusted_computing_base\n"
},
{
"path": "chapter-2/what-about-eval.md",
"content": "# What about `eval`?\n\nPreviously we've talked about how to control what code loads\nfrom the file system, but not what code loads from strings.\n\nThe rest of this discussion uses the term \"`eval`\" to refer to any of\nthe `eval` operator, the `eval` function, `new Function`,\n`vm.runIn*Context`, `vm.Script.run*`, [`WebAssembly.compile`][]\nand other operators that convert strings or bytes into code.\n\nRecall that it is difficult to prove that code\n[does not `eval`](../chapter-1/threat-RCE.md):\n\n```js\nvar x = {},\n a = 'constructor',\n b = 'constructor',\n s = 'console.log(s)';\nx[a][b](s)();\n```\n\nSome node projects deploy with a tweaked node runtime that turns off\nsome `eval` operators, but there are widely used npm modules that use\nthem carefully. For example:\n\n* [Pug][] generates HTML from templates.\n* [Mathjs][] evaluates closed-form mathematical expressions.\n\nBoth generate JavaScript code under the hood, which is dynamically\nparsed. Let's consider two use cases:\n\n* Pug's code generator is usually called with trusted inputs, e.g.\n `.pug` files authored by trusted developers.\n* Mathjs is often called with untrusted inputs. If a developer\n wanted to let a user generate an ad-hoc report without having to\n download data into a spreadsheet, they might use Mathjs to parse\n user-supplied arithmetic expressions ([docs][more_secure_eval])\n instead of trying to check that an input is safe to `eval` via\n `RegExp`s. It is not without risk ([advisory][adv552])\n though [^1].\n\nThese two uses of code generators fall at either end of a spectrum.\nThe uses of Pug seem static, all the information is available before\nwe deploy. Our Mathjs use case is necessarily dynamic since the\ninput is not available until a user is in the loop.\n\nNext we discuss ways to recognize and simplify the former, while\ndouble-checking the latter. On the client, we have no options between\nallowing implicit `eval` and banning all uses of `eval`. There are\nfewer compelling use cases on the client since it is harder to\namortize code generation over multiple requests. On the server, use\nof `eval` in the presence of untrusted inputs still needs to be\ncarefully vetted. We explore ways to programatically enforce vetting\ndecisions short of a blanket ban, but turning off `eval` before\naccepting untrusted inputs is still the most reliable way to prevent\nattackers from using `eval` against you.\n\n[^1]: Since this writing, [Mathjs got rid of all uses of `eval`][no-eval-issue]\n\n\n[`WebAssembly.compile`]: http://webassembly.org/docs/js/#webassemblycompile\n[Pug]: https://pugjs.org/\n[Mathjs]: http://mathjs.org/\n[more_secure_eval]: http://mathjs.org/examples/advanced/more_secure_eval.js.html\n[adv552]: https://nodesecurity.io/advisories/552\n[no-eval-issue]: https://github.com/josdejong/mathjs/issues/1019#issuecomment-367289278\n"
},
{
"path": "chapter-3/knowing_dependencies.md",
"content": "# Knowing your dependencies\n\n## Background\n\n[`npmjs` search results][npmjs/node] have stats on download count and\nopen issues and PRs.\n\n![\"npmjs.com](\"../images/npmjs-node.png\")
\n\nEach package page also links to the corresponding GitHub project\nwhich has links to the project's [pulse][github-pulse].\n\nBoth of these give an idea of how popular the project is, and\nwhether it's actively developed.\n\nOn their Github pages, many projects proudly display\n[badges and shields][] indicating their continuous integration status,\nand other vital statistics.\n\nThe Linux Core Infrastructure project espouses a set of\n[best practices badges][bpb] and define tiers for mature infrastructure\nprojects. We get some of the basic items for free by distributing via\n`npm`, but other items bear on how responsive the project might be to\nvulnerability reports and how it might respond to attempts to inject\nmalicious code:\n\n* Another will have the necessary access rights if someone dies\n* Monitor external dependencies to detect/fix known vulnerabilities\n* At least 2 unassociated significant contributors\n* Use 2FA\n* At least 50% of all modifications are reviewed by another\n* Have a security review (internal or external)\n\n\"Use 2FA\" is possible with npm but it is not clear that it is widely\npracticed. [MTP][] discusses the support already built into Github\nand `npm profile`.\n\n\n## Problem\n\nThreats: [LQC][] [MTP][]\n\nThe npm repository, like other open-source code repositories,\ncontains mature and well-maintained modules, but also plenty of\nbleeding-edge code that has not yet had bugs ironed out.\n\nA wise technical lead might decide that they can use third-party\ndependencies that have been widely used in production for several\nyears by projects with similar needs since gross errors are likely\nto have been fixed.\n\nThat technical lead might also decide that they can use bleeding edge\ncode when they have enough local expertise to vet it, identify\ncorner-cases they need to check, and fix any gross errors they\nencounter.\n\nEither way, that decision to use bleeding-edge code or code that might\nnot be maintained over the long term should be a conscious one.\n\n\n## Success Criteria\n\nDevelopment teams are rarely surprised when code that they had built a\nprototype on later turns out not to be ready for production use, and\nthey do not have to pore over others' code to vet many dependencies.\n\n## A Possible Solution\n\nThe building blocks of a solution probably already exist.\n\n### Aggregate more signals\n\n`npmjs.com` may or may not be the right place to do this, but we\nshould, as a community, aggregate signals about modules and make\nthem readily available.\n\n`npmjs.com/package` already aggregates some useful signals, but\nit or another forum could aggregate more including\n\n- More of the GitHub pulse information including\n closed issues, PRs over time.\n- Relevant badges & shields for the project itself.\n- Relevant badges & shields by percentage of transitive\n dependencies and peer dependencies that have them.\n- Support channels, e.g. slack & discord.\n- Vulnerability reports and the version they affect.\n See sources in [\"When all else fails\"][failing]\n- Weighted mean of age of production dependencies transitively.\n- Results of linters (see [oversight][]) run without respecting\n [inline ignore comments][eslint-ignore-line] and\n [file ignore directives][eslint-ignore-file].\n\nUsers deciding whether to buy something from an online store or\ndownload a cellphone app from an app store have reviews\nand comments from other users. That members of the community take\ntime to weigh in can be a useful signal, and the details can help\nclarify whether this module or an alternative might be better for a\nspecific use.\n\nLarge organizations who host [internal replicas][] may already have a\nlot of the opinion available internally, but aggregating that across\nclients can help smaller organizations and large organizations\nthat are debating whether to dip their toe in.\n\n\n### Leadership & Developer outreach\n\nThe node runtime already [passes][CI-node] the Linux Foundation's best\npractices criteria, but could lead the way by explaining how a project\nthat pushes from GitHub to `registry.npmjs.org` can pass more of these\ncriteria.\n\n\n[npmjs/node]: https://www.npmjs.com/package/node\n[github-pulse]: https://github.com/blog/1476-get-up-to-speed-with-pulse\n[badges and shields]: https://github.com/badges/shields\n[bpb]: https://github.com/coreinfrastructure/best-practices-badge\n[internal replicas]: ../chapter-4/close_dependencies.md\n[failing]: ../chapter-6/failing.md\n[CRY]: ../chapter-1/threat-CRY.md\n[LQC]: ../chapter-1/threat-LQC.md\n[MTP]: ../chapter-1/threat-MTP.md\n[oversight]: ../chapter-5/oversight.md\n[eslint-ignore-line]: https://eslint.org/docs/user-guide/configuring#disabling-rules-with-inline-comments\n[eslint-ignore-file]: https://eslint.org/docs/user-guide/configuring#ignoring-files-and-directories\n[CI-node]: https://bestpractices.coreinfrastructure.org/projects?gteq=50&q=Node.js\n"
},
{
"path": "chapter-4/close_dependencies.md",
"content": "# Keeping your dependencies close\n\n## Background\n\nWhen deploying an application or service, many projects run `npm\ninstall` which can cause problems. [James Shore][] discusses the\nproblem and several solutions, none of which are ideal.\n\n* Network trouble reaching `registry.npmjs.org` becomes a single\n point of failure.\n* An extra `npm shrinkwrap` step is necessary to ensure that\n the versions used during testing are the same as the versions\n deployed (Shore's analysis predates [package locks][]), or\n* Developers check `node_modules` into revision control which\n may include architecture-specific binaries.\n* Local changes may be silently lost when re-installed on a dev\n machine or on upgrade.\n\nMany organizations use tools to manage a local replica.\n\n* [npm Enterprise][] is a full-featured single-tenant implementation\n of the npm registry and website, created by npm, Inc.\n* npm can be [configured to use a different registry][] by setting\n the `registry` npm configuration option. Once dependencies have\n been cached locally the first time, the `--offline` npm option will\n prevent fetching anything new from the network.\n* [Artifactory][] is a language agnostic dependency manager that\n supports Node.\n* [Sinopia][] is a Node specific repository server.\n* [Verdaccio][] is fork of Sinopia.\n* [Yarn][] is a package manager backed by the same\n \n * If it does, rewrites content on the buffer to use non-conflicting\n * start and end words.\n *
\n * If this functions fails to avoid a collision, it will fail with an\n * exception, but this should not reliably occur unless an attacker\n * can generate hash collisions.\n */\nfunction fixupHeredoc (buf, heredocContext) {\n const [ delim, contextStart, contextOffset, delimLength ] = heredocContext\n let chunkLeft = 0\n let startChunkIndex = -1\n for (let i = 0, len = buf.length; i < len; ++i) {\n chunkLeft += buf[i].length\n if (chunkLeft >= contextStart) {\n startChunkIndex = i\n break\n }\n }\n if (startChunkIndex < 0) {\n throw fail`Cannot find heredoc start for ${heredocContext}`\n }\n const label = heredocLabel(delim)\n const endChunkIndex = buf.length - 1\n\n // Figure out how much of the last chunk is part of the body.\n const bodyRe = heredocBodyRegExp(label)\n const endChunk = buf[endChunkIndex]\n const lastBodyMatch = bodyRe.exec(endChunk)\n if (lastBodyMatch[0].length === endChunk.length) {\n throw fail`Could not find end of ${delim}`\n }\n\n const startChunk = buf[startChunkIndex]\n let body = startChunk.substring(contextOffset + delimLength)\n for (let i = startChunkIndex + 1; i < endChunkIndex; ++i) {\n body += buf[i]\n }\n body += lastBodyMatch[0]\n\n // Look for a premature end delimiter by looking at newline followed by body.\n const testBody = `\\n${body}`\n if (bodyRe.exec(testBody)[0].length !== testBody.length) {\n // There is an embedded delimiter.\n // Choose a suffix that an attacker cannot predict.\n // An attacker would need to be able to generate sha256\n // collisions to embed both NL