@north-light/cli 0.3.456 → 0.3.457

package/dist/builtin-memory/crouter-plugin/INDEX.md

@@ -10,3 +10,8 @@ surfaces:
 # `@north-light/plugin`
 
 Read `crouter-plugin/README` for the authoring overview and the directory pages for the specific plugin surface. The directory listing names every page. Use the directory only to choose a focused page; the reference pages hold the authoring details.
+
+Two things a provider registered in the directory must get right, both in `docs/plugin/deploying`:
+
+- A third-party app passes `auth: {issuer, audience, providerId: <its client id>}` to `createFetchHandler`. The directory mints scopes as `<provider id>:<group>`; without `providerId` the kit expects `<plugin name>:<group>` and answers every call 403 `scope_missing`.
+- On Node, Express or Nest, mount the handler with `createNodeHandler(handler, {bodyLimit?, origin?})` instead of hand-writing a request/response adapter. It bounds the body (413 before the handler), streams the response with backpressure, and keeps repeated headers.

package/dist/builtin-memory/crouter-plugin/README.md

@@ -19,4 +19,4 @@ Start with the `node_modules/@north-light/plugin/README.md` for a complete plugi
 - [[crouter-plugin/deploying]] — Fetch frameworks, mount paths, proxies, authentication, and archive compression.
 - [[crouter-plugin/bundles-and-memory]] — generating an archive and shipping agent-facing documents.
 
-The package exports only `LeafError`, `ManifestInvalidError`, `PluginDefinitionError`, `buildBundle`, `buildCommandManifest`, `createFetchHandler`, `defineBranch`, `defineLeaf`, `definePlugin`, `defineStreamingLeaf`, `field`, `kebab`, and `param`. Those are the complete authoring surface.
+The primary authoring surface is `LeafError`, `ManifestInvalidError`, `PluginDefinitionError`, `buildBundle`, `buildCommandManifest`, `createFetchHandler`, `createNodeHandler`, `defineBranch`, `defineLeaf`, `definePlugin`, `defineStreamingLeaf`, `field`, `kebab`, and `param`. The package also exports `compareManifests`, `createCallerVerifier`, `postReceipt`, `ReceiptPostError` and the structural types `createNodeHandler` takes.

package/dist/builtin-memory/crouter-plugin/deploying.md

@@ -7,7 +7,7 @@ when-and-why-to-read: When you need Deployment, this knowledge should be read
 
 # Deployment
 
-`createFetchHandler(plugin, options)` returns `(request: Request) => Promise<Response>`. Use it directly in Cloudflare Workers, Bun, Deno, and any framework route that accepts Fetch `Request` and `Response` objects. A framework with different request types needs only an adapter at its boundary; the package itself has no framework dependency.
+`createFetchHandler(plugin, options)` returns `(request: Request) => Promise<Response>`. Use it directly in Cloudflare Workers, Bun, Deno, and any framework route that accepts Fetch `Request` and `Response` objects. For Node's `http`, Express and Nest, mount it with `createNodeHandler` (see [Node, Express and Nest](#node-express-and-nest)); the package itself has no framework dependency.
 
 The handler serves the archive for every `GET` request and runs a command for a matching `POST` request. It routes a command from the longest matching suffix of the request path, so the same handler works at the origin root, under `/crtr`, and behind a proxy that preserves that path.
 
@@ -23,7 +23,33 @@ Set `baseUrl` only when `request.url` is not the public URL, such as a proxy tha
 
 Pass `token` to require `Authorization: Bearer <token>` on archive and command requests. `--auth-env NAME` tells crtr which environment variable of the calling process holds that value. It does not configure the server. For a command an agent runs, the calling process is its broker, which reads the profile env store (`crtr profile env set <profile> --name NAME`) rather than your shell's exports. Omitting `token` serves without authentication and logs a warning when the handler is created.
 
-A capability provider registered in the directory passes `auth: {issuer, audience}` instead of `token`; passing both throws. `issuer` is the directory's issuer URL and `audience` is the provider's endpoint URL exactly as registered. Every command request's bearer must be an outbound token the directory minted. The handler verifies it with `@north-light/identity`: it fetches the JWKS from `<issuer>/.well-known/jwks.json`, caches it, and refetches once when a token names an unknown `kid`. It checks the signature, `iss`, `aud` (exact match, so a trailing slash differs) and `exp`. A failed check answers 401 `unauthorized`. Next the called leaf's `<plugin>:<group>` must be in the token's `scope`. If it is not, the handler answers 403 `scope_missing` with that string in both `field` and `received`. A command request under `auth` must also carry `Crtr-Request-Id`. Every leaf then gets `ctx.caller`: `{sub, grantee, clientId, scope, initiatingApp, act, jti, requestId, runId?}`. `act` and `initiatingApp` are for your audit; the kit authorizes nothing on them. The archive and `GET /versions` stay public under `auth`. For local development, point `issuer` at a test issuer that serves `/.well-known/jwks.json`.
+A capability provider registered in the directory passes `auth: {issuer, audience, providerId}` instead of `token`; passing both throws. `providerId` is the provider's directory principal id — for a third-party app, its OAuth client id, bare or as `app:<id>`; 1–64 characters of `A-Z a-z 0-9 _ -`, validated when the handler is created. `issuer` is the directory's issuer URL and `audience` is the provider's endpoint URL exactly as registered. Every command request's bearer must be an outbound token the directory minted. The handler verifies it with `@north-light/identity`: it fetches the JWKS from `<issuer>/.well-known/jwks.json`, caches it, and refetches once when a token names an unknown `kid`. It checks the signature, `iss`, `aud` (exact match, so a trailing slash differs) and `exp`. A failed check answers 401 `unauthorized`. Next the called leaf's `<providerId>:<group>` must be in the token's `scope` (`<plugin name>:<group>` when `providerId` is not set, which is right only for a first-party provider whose name is its id; the directory always mints `<provider id>:<group>`, so a third-party app that omits `providerId` gets 403 on every call). If the scope is missing, the handler answers 403 `scope_missing` with that string in both `field` and `received`; when `providerId` is unset and the token carries the leaf's group under another id, `next` reads `Set auth.providerId to your app's client id (<that id>).` A command request under `auth` must also carry `Crtr-Request-Id`. Every leaf then gets `ctx.caller`: `{sub, grantee, clientId, scope, initiatingApp, act, jti, requestId, runId?}`. `act` and `initiatingApp` are for your audit; the kit authorizes nothing on them. The archive and `GET /versions` stay public under `auth`. For local development, point `issuer` at a test issuer that serves `/.well-known/jwks.json`.
+
+## Node, Express and Nest
+
+`createNodeHandler(handler, { bodyLimit?, origin? })` adapts the Fetch handler to `(req, res) => Promise<void>` for Node's `http`, Express and Nest. It imports nothing from `node:`, and its request and response types are structural, so it needs none of those frameworks' types.
+
+```ts
+import { createFetchHandler, createNodeHandler } from '@north-light/plugin';
+
+const handler = createFetchHandler(plugin, {
+  auth: { issuer: ISSUER, audience: `${APP_ORIGIN}/plugin`, providerId: CLIENT_ID },
+  baseUrl: `${APP_ORIGIN}/plugin`,
+  requests,
+});
+const node = createNodeHandler(handler, { bodyLimit: 65536 });
+
+// Express / Nest controller method:
+//   @All(['', '*path']) serve(@Req() req, @Res() res) { return node(req, res); }
+// node:http:
+//   createServer((req, res) => void node(req, res));
+```
+
+- **URL.** `originalUrl ?? url` resolved against `origin`, or against `http://<Host header>` when `origin` is not set. Pass `origin` when the public origin differs from the Host the app sees.
+- **Body.** For a non-`GET`/`HEAD` request, `req.rawBody` (Nest with `rawBody: true`) is used when present; otherwise the stream is read. A `content-length` above `bodyLimit` (default 65536 bytes), or more bytes than that, answers 413 `invalid_request` before the handler runs, so before the token is checked.
+- **Headers.** Every request header is passed on; a header Node delivers as an array is appended value by value. The response keeps repeated headers, `set-cookie` included.
+- **Response.** The body is streamed chunk by chunk, waiting for `drain` when the socket is full. When the client disconnects, the request's `signal` aborts and the response stream is cancelled.
+- **Failure.** A handler that throws answers 500 `handler_failed` in the kit's error shape; the adapter never rejects.
 
 ## Major versions
 

package/docs/plugin/README.md

@@ -17,4 +17,4 @@ Start with the [package README](../../packages/crouter-plugin/README.md) for a c
 - [Deployment](deploying.md) — Fetch frameworks, mount paths, proxies, authentication, and archive compression.
 - [Bundles and documents](bundles-and-memory.md) — generating an archive and shipping agent-facing documents.
 
-The package exports only `LeafError`, `ManifestInvalidError`, `PluginDefinitionError`, `buildBundle`, `buildCommandManifest`, `createFetchHandler`, `defineBranch`, `defineLeaf`, `definePlugin`, `defineStreamingLeaf`, `field`, `kebab`, and `param`. Those are the complete authoring surface.
+The primary authoring surface is `LeafError`, `ManifestInvalidError`, `PluginDefinitionError`, `buildBundle`, `buildCommandManifest`, `createFetchHandler`, `createNodeHandler`, `defineBranch`, `defineLeaf`, `definePlugin`, `defineStreamingLeaf`, `field`, `kebab`, and `param`. The package also exports `compareManifests`, `createCallerVerifier`, `postReceipt`, `ReceiptPostError` and the structural types `createNodeHandler` takes.

package/docs/plugin/deploying.md

@@ -5,7 +5,7 @@ description: Serve plugin Fetch handlers with authentication, mount paths, and a
 
 # Deployment
 
-`createFetchHandler(plugin, options)` returns `(request: Request) => Promise<Response>`. Use it directly in Cloudflare Workers, Bun, Deno, and any framework route that accepts Fetch `Request` and `Response` objects. A framework with different request types needs only an adapter at its boundary; the package itself has no framework dependency.
+`createFetchHandler(plugin, options)` returns `(request: Request) => Promise<Response>`. Use it directly in Cloudflare Workers, Bun, Deno, and any framework route that accepts Fetch `Request` and `Response` objects. For Node's `http`, Express and Nest, mount it with `createNodeHandler` (see [Node, Express and Nest](#node-express-and-nest)); the package itself has no framework dependency.
 
 The handler serves the archive for every `GET` request and runs a command for a matching `POST` request. It routes a command from the longest matching suffix of the request path, so the same handler works at the origin root, under `/crtr`, and behind a proxy that preserves that path.
 
@@ -21,7 +21,33 @@ Set `baseUrl` only when `request.url` is not the public URL, such as a proxy tha
 
 Pass `token` to require `Authorization: Bearer <token>` on archive and command requests. `--auth-env NAME` tells crtr which environment variable of the calling process holds that value. It does not configure the server. For a command an agent runs, the calling process is its broker, which reads the profile env store (`crtr profile env set <profile> --name NAME`) rather than your shell's exports. Omitting `token` serves without authentication and logs a warning when the handler is created.
 
-A capability provider registered in the directory passes `auth: {issuer, audience}` instead of `token`; passing both throws. `issuer` is the directory's issuer URL and `audience` is the provider's endpoint URL exactly as registered. Every command request's bearer must be an outbound token the directory minted. The handler verifies it with `@north-light/identity`: it fetches the JWKS from `<issuer>/.well-known/jwks.json`, caches it, and refetches once when a token names an unknown `kid`. It checks the signature, `iss`, `aud` (exact match, so a trailing slash differs) and `exp`. A failed check answers 401 `unauthorized`. Next the called leaf's `<plugin>:<group>` must be in the token's `scope`. If it is not, the handler answers 403 `scope_missing` with that string in both `field` and `received`. A command request under `auth` must also carry `Crtr-Request-Id`. Every leaf then gets `ctx.caller`: `{sub, grantee, clientId, scope, initiatingApp, act, jti, requestId, runId?}`. `act` and `initiatingApp` are for your audit; the kit authorizes nothing on them. The archive and `GET /versions` stay public under `auth`. For local development, point `issuer` at a test issuer that serves `/.well-known/jwks.json`.
+A capability provider registered in the directory passes `auth: {issuer, audience, providerId}` instead of `token`; passing both throws. `providerId` is the provider's directory principal id — for a third-party app, its OAuth client id, bare or as `app:<id>`; 1–64 characters of `A-Z a-z 0-9 _ -`, validated when the handler is created. `issuer` is the directory's issuer URL and `audience` is the provider's endpoint URL exactly as registered. Every command request's bearer must be an outbound token the directory minted. The handler verifies it with `@north-light/identity`: it fetches the JWKS from `<issuer>/.well-known/jwks.json`, caches it, and refetches once when a token names an unknown `kid`. It checks the signature, `iss`, `aud` (exact match, so a trailing slash differs) and `exp`. A failed check answers 401 `unauthorized`. Next the called leaf's `<providerId>:<group>` must be in the token's `scope` (`<plugin name>:<group>` when `providerId` is not set, which is right only for a first-party provider whose name is its id; the directory always mints `<provider id>:<group>`, so a third-party app that omits `providerId` gets 403 on every call). If the scope is missing, the handler answers 403 `scope_missing` with that string in both `field` and `received`; when `providerId` is unset and the token carries the leaf's group under another id, `next` reads `Set auth.providerId to your app's client id (<that id>).` A command request under `auth` must also carry `Crtr-Request-Id`. Every leaf then gets `ctx.caller`: `{sub, grantee, clientId, scope, initiatingApp, act, jti, requestId, runId?}`. `act` and `initiatingApp` are for your audit; the kit authorizes nothing on them. The archive and `GET /versions` stay public under `auth`. For local development, point `issuer` at a test issuer that serves `/.well-known/jwks.json`.
+
+## Node, Express and Nest
+
+`createNodeHandler(handler, { bodyLimit?, origin? })` adapts the Fetch handler to `(req, res) => Promise<void>` for Node's `http`, Express and Nest. It imports nothing from `node:`, and its request and response types are structural, so it needs none of those frameworks' types.
+
+```ts
+import { createFetchHandler, createNodeHandler } from '@north-light/plugin';
+
+const handler = createFetchHandler(plugin, {
+  auth: { issuer: ISSUER, audience: `${APP_ORIGIN}/plugin`, providerId: CLIENT_ID },
+  baseUrl: `${APP_ORIGIN}/plugin`,
+  requests,
+});
+const node = createNodeHandler(handler, { bodyLimit: 65536 });
+
+// Express / Nest controller method:
+//   @All(['', '*path']) serve(@Req() req, @Res() res) { return node(req, res); }
+// node:http:
+//   createServer((req, res) => void node(req, res));
+```
+
+- **URL.** `originalUrl ?? url` resolved against `origin`, or against `http://<Host header>` when `origin` is not set. Pass `origin` when the public origin differs from the Host the app sees.
+- **Body.** For a non-`GET`/`HEAD` request, `req.rawBody` (Nest with `rawBody: true`) is used when present; otherwise the stream is read. A `content-length` above `bodyLimit` (default 65536 bytes), or more bytes than that, answers 413 `invalid_request` before the handler runs, so before the token is checked.
+- **Headers.** Every request header is passed on; a header Node delivers as an array is appended value by value. The response keeps repeated headers, `set-cookie` included.
+- **Response.** The body is streamed chunk by chunk, waiting for `drain` when the socket is full. When the client disconnects, the request's `signal` aborts and the response stream is cancelled.
+- **Failure.** A handler that throws answers 500 `handler_failed` in the kit's error shape; the adapter never rejects.
 
 ## Major versions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/cli",
-  "version": "0.3.456",
+  "version": "0.3.457",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -137,7 +137,7 @@
   },
   "license": "UNLICENSED",
   "dependencies": {
-    "@north-light/identity": "0.3.456",
+    "@north-light/identity": "0.3.457",
     "@earendil-works/pi-agent-core": "1.1.0",
     "@earendil-works/pi-ai": "1.1.0",
     "@earendil-works/pi-coding-agent": "1.1.0",

package/packages/crouter-identity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/identity",
-  "version": "0.3.456",
+  "version": "0.3.457",
   "description": "Northlight access-token verification and scope rules",
   "type": "module",
   "main": "./dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/cli",
-  "version": "0.3.456",
+  "version": "0.3.457",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/cli",
-      "version": "0.3.456",
+      "version": "0.3.457",
       "hasInstallScript": true,
       "license": "UNLICENSED",
       "workspaces": [
@@ -18,7 +18,7 @@
         "@earendil-works/pi-ai": "1.1.0",
         "@earendil-works/pi-coding-agent": "1.1.0",
         "@earendil-works/pi-tui": "1.1.0",
-        "@north-light/identity": "0.3.456",
+        "@north-light/identity": "0.3.457",
         "cron-parser": "^5.6.0",
         "esbuild": "^0.27.7",
         "jose": "^6.2.12",
@@ -12095,17 +12095,17 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/api",
-      "version": "0.3.456",
+      "version": "0.3.457",
       "license": "UNLICENSED"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/env-docker",
-      "version": "0.3.456",
+      "version": "0.3.457",
       "license": "UNLICENSED"
     },
     "packages/crouter-identity": {
       "name": "@north-light/identity",
-      "version": "0.3.456",
+      "version": "0.3.457",
       "license": "UNLICENSED",
       "dependencies": {
         "jose": "^6.2.1"
@@ -12113,20 +12113,20 @@
     },
     "packages/crouter-plugin": {
       "name": "@north-light/plugin",
-      "version": "0.3.456",
+      "version": "0.3.457",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/api": "0.3.456",
-        "@north-light/identity": "0.3.456"
+        "@north-light/api": "0.3.457",
+        "@north-light/identity": "0.3.457"
       }
     },
     "packages/crouter-sdk": {
       "name": "@north-light/sdk",
-      "version": "0.3.456",
+      "version": "0.3.457",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/api": "0.3.456",
-        "@north-light/identity": "0.3.456",
+        "@north-light/api": "0.3.457",
+        "@north-light/identity": "0.3.457",
         "jose": "^6.2.1"
       },
       "bin": {