{"_id":"@amail/plugin-host","name":"@amail/plugin-host","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@amail/plugin-host","version":"0.1.0","description":"Worker-thread sandbox host for AMail plugins. Enforces manifest-declared permissions at the worker boundary.","license":"MIT","homepage":"https://github.com/sobingt/email-tool/tree/main/packages/plugin-host","repository":{"type":"git","url":"git+https://github.com/sobingt/email-tool.git","directory":"packages/plugin-host"},"bugs":{"url":"https://github.com/sobingt/email-tool/issues"},"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./worker-entry":"./dist/worker-entry.mjs","./testing":{"types":"./dist/testing.d.ts","import":"./dist/testing.js"}},"publishConfig":{"access":"public"},"dependencies":{"js-yaml":"^4.1.1","@amail/plugin-sdk":"0.1.0"},"devDependencies":{"@types/js-yaml":"^4.0.9","@types/node":"^20","typescript":"^5.7"},"scripts":{"build":"tsc -p tsconfig.build.json && cp src/worker-entry.mjs dist/worker-entry.mjs","clean":"rm -rf dist","test":"node --test --test-reporter spec --experimental-strip-types --import ./tests/register.mjs tests/*.test.ts"},"_id":"@amail/plugin-host@0.1.0","_integrity":"sha512-xkr8H+y51WGaCJnr71/Y5q3nI8hQjg5IV4paoU2B38tlJH506pa5ZGD1ZiXAMF+kEBqpAO1MXpzZZNDKG2VJRg==","_resolved":"/private/var/folders/s0/gzzhqcjn6f1d4mh9wq6y2mp40000gn/T/bf989d0d311bd28800b50f9fb9bba52e/amail-plugin-host-0.1.0.tgz","_from":"file:amail-plugin-host-0.1.0.tgz","_nodeVersion":"22.22.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-xkr8H+y51WGaCJnr71/Y5q3nI8hQjg5IV4paoU2B38tlJH506pa5ZGD1ZiXAMF+kEBqpAO1MXpzZZNDKG2VJRg==","shasum":"694d1b21570c0ca1f148b7baeca2e35419d25833","tarball":"https://registry.npmjs.org/@amail/plugin-host/-/plugin-host-0.1.0.tgz","fileCount":32,"unpackedSize":85506,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEdZgxqIuEwVBG5gAGq/gIYKoiazi3p1Xn7HkB6QESIpAiEA47bdvI3VfxdtD/yWv/RcJPUL3fjzh8lOl8PZPNWKH7c="}]},"_npmUser":{"name":"sgthomas","email":"sobingt@bitbrothers.in"},"directories":{},"maintainers":[{"name":"sgthomas","email":"sobingt@bitbrothers.in"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/plugin-host_0.1.0_1779086419302_0.5552771469094853"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-18T06:40:19.224Z","0.1.0":"2026-05-18T06:40:19.433Z","modified":"2026-05-18T06:40:19.677Z"},"maintainers":[{"name":"sgthomas","email":"sobingt@bitbrothers.in"}],"description":"Worker-thread sandbox host for AMail plugins. Enforces manifest-declared permissions at the worker boundary.","homepage":"https://github.com/sobingt/email-tool/tree/main/packages/plugin-host","repository":{"type":"git","url":"git+https://github.com/sobingt/email-tool.git","directory":"packages/plugin-host"},"bugs":{"url":"https://github.com/sobingt/email-tool/issues"},"license":"MIT","readme":"# @amail/plugin-host\n\nWorker-thread sandbox host for [AMail](https://github.com/sobingt/email-tool)\nplugins. Enforces manifest-declared permissions at the worker boundary using\nNode 24's `--permission` flag and an in-process `ctx_request`/`ctx_response`\nprotocol over `MessagePort`.\n\nEnd users rarely import this directly — it's loaded by the AMail runtime to\ndispatch plugin tools. Plugin authors do import it via the\n[`./testing`](#testing-helpers) subpath to drive their integration tests.\n\n## Installation\n\n```bash\npnpm add -D @amail/plugin-host\n```\n\nRequires Node ≥ 24 (the `--permission` flag is stable from 24.x).\n\n## What's in `dist/`\n\n- `index.js` / `index.d.ts` — `PluginHost`, `bootPlugin`, errors\n- `worker-entry.mjs` — the worker entrypoint that `Worker` spawns; not a\n  user-facing API\n- `testing.js` / `testing.d.ts` — the `boot({ pkgRoot, fixtures? })` helper\n\n## Testing helpers\n\n```ts\nimport { boot } from \"@amail/plugin-host/testing\";\n\nconst host = await boot({\n  pkgRoot: new URL(\"..\", import.meta.url),\n  fixtures: { /* AttachmentRef stubs etc. */ },\n});\n\nconst result = await host.callTool(\"parse_compliance_csv\", { /* ... */ });\nawait host.shutdown();\n```\n\nThe helper hides the ~50 lines of boot boilerplate that Phase 4 flagged as a\npapercut. It loads `plugin.manifest.yaml` from `pkgRoot`, spawns the worker\nwith the declared permissions, and provides an in-process implementation of\n`ctx.attachments`, `ctx.s3`, `ctx.llm`, and `ctx.logger` against the\nfixtures.\n\n## Permission enforcement\n\n| Surface | Enforcer | Where |\n|---|---|---|\n| Filesystem read/write | Node `--permission --allow-fs-read/--allow-fs-write` flags computed from manifest paths | Host process spawn args |\n| Network outbound | `fetch` wrapped inside the worker; `networkAllowsHost` check on every URL | Worker process |\n| Child process spawn | Not granted (`--allow-child-process` is never set) | Node permission model |\n| Worker spawn | Granted (workers can spawn nested workers only via Node's API; AMail's plugins are single-worker) | `--allow-worker` |\n| Env vars | Only `INSTANCE_ID`, `AMAIL_AGENT_EMAIL`, plus `permissions.env.required` are forwarded | Host filters the spawn env |\n| S3 / attachments / LLM | No raw SDKs reachable; everything goes through `ctx_request` round-trip | `ctx-server.ts` |\n\nThe defense in depth is intentional: the SDK shim is the only surface plugin\ncode sees, **and** the Node permission model blocks the syscalls that would\nlet a plugin escape the shim.\n\n## Versioning + breaking changes\n\nReleased via Changesets alongside `@amail/plugin-sdk`. Major bumps follow a\n6-month deprecation window with two preview releases (per plan.md #14). Pin\nto a major in production; the SDK is the contract, the host is the\nenforcement.\n\n## License\n\nMIT — see `LICENSE`.\n","readmeFilename":"README.md","_rev":"1-b462e3d8e3938edd0f3859ff8e917b63"}