{"_id":"@caprail/transport-http","_rev":"3-a1c00105576e27b91d6858cdfa4fcd62","name":"@caprail/transport-http","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@caprail/transport-http","version":"0.1.0","_id":"@caprail/transport-http@0.1.0","maintainers":[{"name":"denifia","email":"mr.l.wale@gmail.com"}],"dist":{"shasum":"8cfba2dbf5c66021009a051a47241bd5af67c554","tarball":"https://registry.npmjs.org/@caprail/transport-http/-/transport-http-0.1.0.tgz","fileCount":7,"integrity":"sha512-Jv/lZVWX2/r4ijpgjKBC2S0TvQo0UUIS322akVlIorYLM9AP0OGxVjOQAuTynU2bSBXYwiRrm/zkYLj5trbJhw==","signatures":[{"sig":"MEYCIQCevV0TWuEd7Rf7FVQioYWoKE1QcKtvc/r7YPGXDsLEjQIhAMxcbqV6+4KoQEm62kC7lklWzmlvlEDXguG0aAewSawf","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":29086},"main":"./src/index.js","type":"module","engines":{"node":">=18"},"exports":{".":"./src/index.js"},"gitHead":"5297aaffedba0f130f1531923ccd777d47e00cca","scripts":{"test":"node --test ./test/*.test.js"},"_npmUser":{"name":"denifia","email":"mr.l.wale@gmail.com"},"_npmVersion":"11.10.1","description":"HTTP transport for command-token guards in the Caprail family","directories":{},"_nodeVersion":"25.7.0","dependencies":{"@caprail/config-runtime":"0.1.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/transport-http_0.1.0_1777106780014_0.18544543802811875","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@caprail/transport-http","version":"0.2.0","_id":"@caprail/transport-http@0.2.0","maintainers":[{"name":"denifia","email":"mr.l.wale@gmail.com"}],"homepage":"https://github.com/caprail/caprail/tree/main/packages/transports/http#readme","bugs":{"url":"https://github.com/caprail/caprail/issues"},"dist":{"shasum":"a62fcaca138baef610ef0c7202d52bcb0731917d","tarball":"https://registry.npmjs.org/@caprail/transport-http/-/transport-http-0.2.0.tgz","fileCount":7,"integrity":"sha512-eMCOAhRwGAUh43/GylqMRKMo0+nGI26FYNtV0JqF3qWHARsr1uKbPoQXOK5td/f9vmHNcX7h/AKJAClxg6dv7A==","signatures":[{"sig":"MEUCIQC0qisXgryeLq2ubAvq18vWqHR8Ras6rNlKk8A10xGEPgIgdLx+yL4paVTGMfLQ6s66xK1wp2frun6Pl2zmr3RIlds=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@caprail%2ftransport-http@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":29315},"main":"./src/index.js","type":"module","engines":{"node":">=18"},"exports":{".":"./src/index.js"},"gitHead":"3fcf5bb3c3697a6f34248f9018521e2dfe6b413b","scripts":{"test":"node --test ./test/*.test.js"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:00045e87-8d3e-4685-89db-c8e4470a8ee3"}},"repository":{"url":"git+https://github.com/caprail/caprail.git","type":"git","directory":"packages/transports/http"},"_npmVersion":"11.11.0","description":"HTTP transport for command-token guards in the Caprail family","directories":{},"_nodeVersion":"24.14.1","dependencies":{"@caprail/config-runtime":"0.2.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/transport-http_0.2.0_1777109914722_0.8087784537690386","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@caprail/transport-http","version":"0.3.0","description":"HTTP transport for command-token guards in the Caprail family","type":"module","main":"./src/index.js","exports":{".":"./src/index.js"},"engines":{"node":">=18"},"scripts":{"test":"node --test ./test/*.test.js"},"dependencies":{"@caprail/config-runtime":"0.3.0"},"repository":{"type":"git","url":"git+https://github.com/caprail/caprail.git","directory":"packages/transports/http"},"homepage":"https://github.com/caprail/caprail/tree/main/packages/transports/http#readme","gitHead":"4db945323405a9e92c50d78db622065f9d750d2f","_id":"@caprail/transport-http@0.3.0","bugs":{"url":"https://github.com/caprail/caprail/issues"},"_nodeVersion":"24.14.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-a6bfVqmua6och0spP9fLhh2zz/+UBUkv8OqScf2Fw3l8JvPdTqmYDwyagKINDObVN/Ahn5BwLFjA0JJtmhY2lg==","shasum":"61a31c7f1c378ec3be5d5145ceb98c11cb54ca3a","tarball":"https://registry.npmjs.org/@caprail/transport-http/-/transport-http-0.3.0.tgz","fileCount":7,"unpackedSize":29315,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@caprail%2ftransport-http@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHpPJApJTxS1nttpdBd6N5XB+ZqiHaJvLNylIKK+VD+ZAiEAvPXND6Y4Tdn6DkjK0IptR4cb/o8Gbg28FGVLCTmjeDw="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:00045e87-8d3e-4685-89db-c8e4470a8ee3"}},"directories":{},"maintainers":[{"name":"denifia","email":"mr.l.wale@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/transport-http_0.3.0_1777353507204_0.5493701166874647"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-25T08:46:19.871Z","modified":"2026-04-28T05:18:27.673Z","0.1.0":"2026-04-25T08:46:20.176Z","0.2.0":"2026-04-25T09:38:34.872Z","0.3.0":"2026-04-28T05:18:27.406Z"},"bugs":{"url":"https://github.com/caprail/caprail/issues"},"homepage":"https://github.com/caprail/caprail/tree/main/packages/transports/http#readme","repository":{"type":"git","url":"git+https://github.com/caprail/caprail.git","directory":"packages/transports/http"},"description":"HTTP transport for command-token guards in the Caprail family","maintainers":[{"name":"denifia","email":"mr.l.wale@gmail.com"}],"readme":"# `@caprail/transport-http`\n\nHTTP transport for command-token guards in the Caprail family.\n\nThis package is a **transport library** — it provides a reusable HTTP server runtime\nthat binds a Caprail guard to `/exec`, `/discover`, and `/health` endpoints. It does not\nship a binary or CLI entrypoint; that is the responsibility of a product package such as\n`@caprail/cli-http`.\n\nSee [`docs/api.md`](./docs/api.md) for endpoint contracts and\n[`docs/auth.md`](./docs/auth.md) for authentication modes.\n\n---\n\n## Usage\n\n```js\nimport * as guardCli from '@caprail/guard-cli';\nimport { startHttpTransportServer } from '@caprail/transport-http';\n\nconst server = await startHttpTransportServer({\n  guard: guardCli,\n  configPath: '/etc/caprail-cli/config.yaml',\n  auth: { token: process.env.CAPRAIL_TOKEN },\n  host: '0.0.0.0',\n  port: 8100,\n});\n\nconsole.log(`Listening on port ${server.address().port}`);\n```\n\n---\n\n## API\n\n### `createHttpTransportServer(options)` → `Promise<http.Server>`\n\nValidates the guard contract, auth configuration, and policy config via\n`guard.loadAndValidateConfig`, then returns a configured `http.Server` that is **not\nyet listening**. Throws if any startup step fails (fail-closed).\n\nAfter startup, `/discover` and `/exec` hot-reload the policy file when its on-disk\nfingerprint changes. Reload failures are also fail-closed: protected routes return 500\nuntil the config becomes valid again. `/health` stays public and does not depend on\nsuccessful reloads.\n\n### `startHttpTransportServer(options)` → `Promise<http.Server>`\n\nSame as `createHttpTransportServer`, but also starts listening on the configured\n`host`/`port`. Resolves with the listening `http.Server`.\n\n### Options\n\n| Option | Type | Default | Description |\n|---|---|---|---|\n| `guard` | object | **required** | Guard adapter — see [Guard contract](#guard-contract) |\n| `configPath` | string | | Explicit config path passed to `guard.loadAndValidateConfig` |\n| `auth` | object | **required** | `{ token: string }` or `{ noAuth: true }` — see [docs/auth.md](./docs/auth.md) |\n| `timeoutMs` | number | `30000` | Child process timeout in ms. Returns 504 on breach. |\n| `maxOutputBytes` | number | `1048576` | Max combined stdout+stderr bytes. Returns 413 on breach. |\n| `host` | string | `'127.0.0.1'` | Bind host (`startHttpTransportServer` only) |\n| `port` | number | `8100` | Bind port (`startHttpTransportServer` only). Use `0` for OS-assigned. |\n| `env` | object | `process.env` | Environment passed to child processes |\n\n---\n\n## Guard contract\n\nThe injected `guard` object must implement these three methods. All other guard\ninternals are invisible to the transport.\n\n```js\n{\n  // Load and validate the policy config from disk.\n  // Returns { ok, configPath, config, report, error }.\n  loadAndValidateConfig(options),\n\n  // Return serialised tool definitions for /discover.\n  // Returns { ok, payload: { tools } }.\n  buildListPayload(config, options),\n\n  // Evaluate policy and execute the command.\n  // Returns Promise<{ status, ... }>.\n  // Supports optional `signal` (AbortSignal) for transport-level timeout/cap.\n  executeGuardedCommand(config, toolName, args, options),\n}\n```\n\nThe transport depends **only on this public contract**. It never imports guard\ninternals. This means the same `@caprail/transport-http` can be paired with any future\nguard (e.g. `@caprail/guard-files`) without modification.\n\n---\n\n## Endpoints\n\n| Method | Path | Auth | Description |\n|---|---|---|---|\n| `GET` | `/health` | None | Container health check — always 200 |\n| `GET` | `/discover` | Required | Tool manifest + execution metadata |\n| `POST` | `/exec` | Required | Execute a command through the guard |\n\nSee [`docs/api.md`](./docs/api.md) for full request/response contracts.\n\n---\n\n## Execution controls\n\nAll commands run in **non-interactive mode**:\n\n- `stdin` is never forwarded.\n- `stdout` and `stderr` are captured separately and returned in the response body.\n- Timeout enforcement: if the child exceeds `timeoutMs`, it is sent SIGTERM then SIGKILL\n  (after 200 ms) and the transport returns **504 Gateway Timeout**.\n- Output cap enforcement: once combined stdout+stderr reaches `maxOutputBytes`, the child\n  is terminated and the transport returns **413 Payload Too Large**.\n\nOutput capture happens byte-by-byte during execution — large outputs are never fully\nbuffered before the cap is enforced.\n\n---\n\n## Composition boundary\n\n```text\nguard package:     policy model + config + evaluation + execution + audit\nshared package:    config runtime + hot-reload state/fingerprinting\ntransport package: HTTP protocol + auth + timeout/output limits + process lifecycle\nproduct package:   thin wiring + CLI flags + binary entry point\n```\n\n`@caprail/transport-http` is intentionally guard-agnostic. A future product like\n`@caprail/files-http` can reuse this transport with a different guard without changing\nany HTTP runtime code, while sharing the same config-runtime helpers.\n\n---\n\n## Reusable runtime core\n\nThe HTTP primitives in `src/server.js` are guard-agnostic and can be imported directly:\n\n```js\nimport { parseJsonBody, writeJson, writeError, checkAuth } from '@caprail/transport-http/src/server.js';\n```\n\nThese are used internally by the CLI route adapter (`/exec`, `/discover`) but are\navailable as building blocks for future guard adapters.\n","readmeFilename":"README.md"}