Access control for file access and generator execution

[mshima]

Problem

A Yeoman environment runs third-party code: the generators it composes. Today the environment has no
way to define or enforce a policy over what that code does — neither which generators may execute, nor
which parts of the filesystem they may read and write.

This matters because a generator's configuration is frequently not authored by the person running it.
Configuration is generator input, and it can reach paths and packages far outside the project being
generated. There is currently no boundary between "this generator was asked to scaffold a project here"
and "this generator read or wrote something elsewhere on the machine".

What this is, and what it is not

This is an access-control model for code that uses the official APIs. It is an accident-containment and
untrusted-data boundary, plus an audit point — not a sandbox.

Generator code can call node:fs directly and bypass any of this. Containing genuinely hostile code is
the job of OS-level isolation (Node's permission model, a container). Untrusted code is handled by the
other half of this proposal: the environment refusing to admit the generator in the first place.

Stating this plainly matters, because the model should not be advertised as something it cannot deliver.

Requirements

• A single access-control policy per execution, shared across multiple environments (some consumers
  run several environments against one shared adapter).
• A global configuration persisting previously granted permissions, remembered between runs.
• Session-only permissions, in addition to persisted ones.
• An asynchronous API supporting prompts, so a decision can be escalated to the user.
• Denial is either a throw or a prompt.
• Must work in non-interactive execution (CI, servers), where the answer is a defined deny rather
  than an accident of how a prompt library behaves without a TTY.

High-level decisions

• Two halves, enforced in different places. Generator execution is admission control, decided by the
  environment at compose time (asynchronous, so it can prompt). File access is decided by a policy and
  enforced at the point the process actually touches the filesystem.
• The boundary is real filesystem access. In-memory operations on the file store touch neither disk
  reads nor disk writes and are not gated by default. This is a deliberate trade: the store is a shared
  cache, so a file read by one generator can be retrieved by another without any disk access. Under a
  single per-execution policy this is harmless, since anything in the store was authorized by the same
  policy that governs the reader. It only becomes limiting if per-generator scoping is wanted later.
• Synchronous enforcement over pre-resolved decisions. Some file access happens through synchronous
  APIs, so the enforcement check cannot prompt. Permissions are therefore resolved ahead of time — from
  the implicit roots, from the persisted configuration, or at an asynchronous boundary where the user can
  be prompted — and the synchronous check is a pure lookup that throws when a path is not covered.
• Permissions live in their own configuration file, not in the existing global generator config.
  That file is written by generators themselves, so storing permissions there would let a generator grant
  itself access. The permissions file is additionally on an absolute deny-list.
• Deny always wins over grant, and persisted decisions are versioned per package so that grants can be
  invalidated when a package changes major version.
• The generic file-access interception point belongs in the file-store layer, where every read and write
  already converges. The policy, its configuration and its prompts belong to the adapter, which is already
  the shared, per-execution object and already owns user interaction.

Scope

• @yeoman/adapter — the interfaces, the policy implementation, global configuration and prompting.
• yeoman-environment — wiring, generator admission control, enforcement on commit.
• yeoman-generator — boundary validation and runtime access requests.
• mem-fs / mem-fs-editor — a small, generic interception hook (tracked separately, linked below).

Future work

Allowing a generator to declare the access it needs, so the environment can resolve permissions during
lookup, is a follow-up. It is worth designing for deliberately: importing a module already executes its
code, so a declaration that can only be read after the import is of limited use, whereas a package manifest
is readable beforehand. The first iteration does not need it — permissions come from the implicit roots, the
persisted configuration, and prompting at asynchronous boundaries.

Implementation details follow in the first comment.

[mshima]

The hook

A generic access hook, called when a file is about to be accessed:

// undefined by default — zero cost when unset
store.access = (path, operation) => {
  // throw to deny
};

• Synchronous. It is reached from synchronous APIs (exists, read, and copy via globSync), so
  it cannot be async. See Authorization below.
• Denies by throwing. An observer-only hook is not usable as a boundary — the existing change event
  is emit-only and post-hoc.
• Receives the operation, not just the path: policies want the read/write split, and recursive delete
  deserves to be distinguishable from write.
• Receives the resolved real path. Store.get() already resolves before the cache lookup; the hook
  should also see the realpath, otherwise a symlink inside an allowed root that points outside it passes a
  check made on the logical path.

The hook is a bare function type, so mem-fs and mem-fs-editor import nothing from @yeoman/*.

Interception points

Call site	Operation	Why
Store.get(), cache-miss branch, before the file is loaded	read	The read boundary. It stats even for missing files, so this covers existence probing too. Cache hits stay free.
Commit (commit-file-async)	write / delete	The write boundary: it iterates the store and calls writeFile, mkdir, chmod, rm(…, { recursive: true }) on file.path. Gating here means a path that entered the store by any route is checked before it reaches disk.
Glob helpers (getCommonPath, globify)	read	They stat the raw caller-supplied pattern before globbing. Gating only the resolved glob root would still leave an existence/type oracle for arbitrary absolute paths.
Glob enumeration (globSync, glob cwd)	read	Real directory reads, and followSymbolicLinks can leave the allowed roots.
Binary detection	read	Reads the first bytes of a file to classify it.

Deliberately not intercepted

• Store.add() — in-memory only. A file added to the store reaches disk only through commit, which is
  gated, so gating add() adds no disk safety. It would only make a bad path fail earlier.
• In-memory reads (get() on a cache hit, each, all, stream, pipeline) — see the shared-cache
  trade-off in the description. Making get() fire on every call is the switch to flip if per-generator
  scoping is ever required.
• destinationPath() / templatePath() — pure string joins, trivially sidestepped by passing an
  absolute path, and anything derived from them is checked at the store gate anyway.
• destinationRoot() / sourceRoot() / environment cwd — not access, but policy-scope events. They
  widen what is reachable, so the environment should control them and re-evaluate policy.

Authorization: reconciling sync enforcement with async prompting

// @yeoman/adapter/types
export interface FileAccessControl {
  /** async: may prompt the user and persist the decision */
  request(scope: AccessScope, options?: { remember?: 'session' | 'always' }): Promise<AccessDecision>;
  /** async: resolves whatever is missing via request(); used at boundaries */
  check(request: AccessRequest): Promise<void>;
  /** sync: consults already-resolved decisions only; throws when not covered */
  assert(request: AccessRequest): void;
  grantSession(scope: AccessScope): Disposable;
}

1. Environment, async, at admission time — resolve policy: prompt through the adapter if needed, and
   build the reachable set (destination root, source roots, glob cwds, temp dir).
2. assert(), sync — a pure predicate over resolved decisions. No I/O, no prompting. On failure it
   throws FileAccessDeniedError naming the generator, the path, and how to grant it.
3. check() / request(), async — used at asynchronous boundaries and in the commit pipeline, where
   prompting is possible.

Generator execution control follows the same shape: admission decisions are async at compose time, file
decisions are sync at the gate.

Attribution — which generator is asking — is not available at the store gate, which only receives a path.
Since generators run inside the run loop, an AsyncLocalStorage maintained by the environment carries the
current generator through awaits without threading context through parameters.

Package split

Package	Responsibility
@yeoman/adapter	Types in @yeoman/adapter/types: FileAccessControl, AccessRequest / AccessScope / AccessDecision, FileAccessDeniedError, and the fileAccess slot on InputOutputAdapter. Runtime: policy, path matching, global permissions config, escalation prompt, propagation through newAdapter().
yeoman-environment	Creates the store and installs the hook, AsyncLocalStorage for the current generator, access transform in the commit pipeline, generator admission control.
yeoman-generator	requestAccess() and boundary validation. Declaring required access in the package manifest is deferred to a follow-up.
yeoman-test	A permissive default policy, otherwise every existing generator test that reads a fixture outside the cwd starts failing.

Two packaging notes:

• @yeoman/types needs no change. It already does export * from '@yeoman/adapter/types', so the new
  types reach every consumer automatically. Nothing has to be added to the highest-coupling package in the
  tree, and no version of it has to be coordinated.
• Consumers must raise their @yeoman/adapter floor. @yeoman/types declares the adapter as an
  optional peer with a wide range (^1.6.0 || … || ^5.0.0), so a consumer can resolve an adapter old
  enough to lack FileAccessControl while still importing it through @yeoman/types. yeoman-environment
  and yeoman-generator need an explicit floor at the version that introduces it.

The commit-side check belongs in the environment's pipeline, placed before the conflicter — there is no
point asking about a conflict on a file that is going to be denied.

Path matching

No globbing in the policy itself; glob in a security rule is a bypass source. Containment by directory plus
exact path only:

• path.relative comparison, which is segment-wise and therefore does not confuse /app with /app-evil.
• realpath of the nearest existing ancestor, memoized per directory, which resolves symlinks and yields
  canonical casing on case-insensitive filesystems.

Global permissions configuration

• Its own file (XDG config directory), not the existing global generator config, which generators write
  themselves and could use to self-grant.
• The permissions file itself is on an absolute deny-list, for both read and write.
• Layered decisions, deny always winning: persisted deny > session deny > session grant > persisted grant >
  implicit roots (destination root, the package's own template directory, the temp directory).
• Grants are versioned per package and invalidated on a major version change; revocation via CLI and API.
• Non-interactive mode applies persisted decisions and denies the rest.

Risks and costs

• TOCTOU between the path check and the actual read: a symlink can be swapped in between. Out of scope
  for this threat model (untrusted data, not a local attacker racing the process); real isolation is the
  Node permission model.
• Performance: the check runs on first touch of each file. With per-directory realpath and decision
  caches this is a path resolution plus a map lookup, but it is worth benchmarking against a generator that
  writes thousands of files.
• Ecosystem breakage: an aggressive default will break existing generators that read outside the
  destination root. Shipping an audit mode first — log instead of throw — gives the data needed to choose
  a sane default.
• Cross-package release cadence: the hook lands in mem-fs / mem-fs-editor, which release on their
  own schedule. Keeping the hook generic and free of @yeoman/* coupling is what keeps that from becoming
  a roadmap dependency.

Suggested first PR

Path matcher, the store hook, and the commit transform, in audit mode only. That measures how much of the
existing generator ecosystem reaches outside the destination root today, which is the number that should
determine how strict the default can be.