Sandboxed, permissioned execution for emitters

[timotheeguerin]

Summary

Introduces an opt-in OS-level sandbox for running TypeSpec emitters, where users authorize exactly which system capabilities each emitter may use. By default an emitter is granted no access to any system API.

Enabled via compile({ sandbox: true }). Each emitter runs in its own isolated child process with only the permissions the user approved in tspconfig.yaml.

How it works

• Permission manifest — libraries/emitters declare needed capabilities in $lib:

  export const $lib = createTypeSpecLibrary({
    name: "@typespec/openapi3",
    diagnostics: {},
    permissions: [
      { permission: { kind: "fs-read", paths: ["./schemas"] }, reason: "Read shared JSON schemas" },
      { permission: { kind: "network", hosts: ["*.example.com"] }, reason: "Resolve remote refs" },
    ],
  });

• User authorization — approved per emitter in tspconfig.yaml:

  permissions:
    "@typespec/openapi3":
      fs-read:
        - ./schemas
      network:
        - "*.example.com"

• Effective permissions = requested ∩ granted, plus the emitter's always-writable output dir. Ungranted requests yield a permission-not-granted diagnostic with a pasteable tspconfig snippet.
• OS isolation — child processes use Node's permission model (--allow-fs-read/write, --allow-child-process), a curated environment, and a privileged broker that re-validates every request. Each $onEmit runs in a child that recompiles to rebuild the live Program; emit diagnostics are serialized and re-targeted against the parent's source files.

Permission categories

fs-read, fs-write, network, env, exec — covering both emitters and (in a later phase) libraries.

Scope of this PR

• ✅ Permission types, set algebra, manifest API
• ✅ tspconfig grants + resolution + diagnostics
• ✅ Sandbox runtime (child-process spawner, broker, bootstrap)
• ✅ Per-emitter sandboxed execution (emitSandboxed)
• ⏳ Follow-ups (not in this PR): full library/decorator sandboxing, --no-sandbox CLI escape hatch + default-rollout decision, security-model docs

Tests

Unit coverage for permission-set / resolve / permissioned-host / node-args, plus a runtime integration test and an end-to-end emit test (denied / granted / plain emitter). All 45 permissions tests pass.

Note

Draft — opening for early feedback on the design and the OS-isolation approach. sandbox defaults to false (opt-in), so existing behavior is unchanged.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/compiler@11102

commit: 71a558e

[github-actions]

All changed packages have been documented.

• ✅ @typespec/compiler

Show changes

@typespec/compiler - feature ✏️

Add the foundation for sandboxed, permissioned execution of libraries and emitters. Libraries/emitters can declare the system capabilities they need via a permission manifest, and users approve them per emitter in tspconfig.yaml. By default an emitter/library is granted no access to any system API.,> ,> ts,> // In a library/emitter's `$lib`,> export const $lib = createTypeSpecLibrary({,> name: "@typespec/openapi3",,> diagnostics: {},,> permissions: [,> { permission: { kind: "fs-read", paths: ["./schemas"] }, reason: "Read shared JSON schemas" },,> { permission: { kind: "network", hosts: ["*.example.com"] }, reason: "Resolve remote refs" },,> ],,> });,> ,> ,> yaml,> # tspconfig.yaml — the user authorizes what the emitter requested,> permissions:,> "@typespec/openapi3":,> fs-read:,> - ./schemas,> network:,> - "*.example.com",>

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension