@gjermundgaraba/effect-actions 0.4.0 → 0.5.0

package/docs/Authentication.md

@@ -2,46 +2,28 @@
 
 Two helpers for hosts that own identity: router middleware that provides a request-scoped
 identity service, and RFC 9728 protected-resource discovery with bearer challenges. Token
-verification, login, and consent stay in the application. Authorization is a group's
-pre-handler hook ([ActionGroup.md](ActionGroup.md)), not part of this module.
+verification, login, and consent stay in the application. Authorization belongs in each adapter's
+`before` hook ([guarantees.md](guarantees.md)), not in this module or the group.
 
 ## API
 
-```ts
-import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+Import `@gjermundgaraba/effect-actions/Authentication`.
 
-/** Provide `service` on every request, or send the response `authenticate` fails with. */
-const middleware: <I, A, R>(
-  service: Context.Key<I, A>,
-  authenticate: Effect.Effect<A, HttpServerResponse.HttpServerResponse, R>,
-) => HttpRouter.Middleware<{
-  provides: I;
-  handles: never;
-  error: never;
-  requires: Exclude<R, HttpRouter.Provided>;
-  layerError: never;
-  layerRequires: never;
-}>;
-
-const protectedResource: (options: ProtectedResourceOptions) => {
-  layer: Layer.Layer<never, never, HttpRouter.HttpRouter>; // GET/HEAD /.well-known/oauth-protected-resource<path>
-  metadataUrl: string;
-  challenge: (challenge?: BearerChallengeOptions) => string; // WWW-Authenticate value
-};
-
-interface ProtectedResourceOptions {
-  readonly resource: string; // exact OAuth resource identifier; its path and query select the discovery path
-  readonly authorizationServers: NonEmptyReadonlyArray<string>;
-  readonly scopesSupported?: ReadonlyArray<string>;
-  readonly resourceName?: string;
-}
+| API                                        | Purpose                                                                                                              |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `middleware(service, authenticate)`        | Native router middleware: provide an identity service per request, or return the response authentication fails with. |
+| `protectedResource(options)`               | Public RFC 9728 discovery routes, metadata URL and bearer challenge builder.                                         |
+| `discovery.layer`, `discovery.metadataUrl` | Router layer and public discovery URL.                                                                               |
+| `discovery.challenge(options?)`            | Escaped `WWW-Authenticate` header value.                                                                             |
 
-interface BearerChallengeOptions {
-  readonly error?: "invalid_token" | "insufficient_scope";
-  readonly errorDescription?: string;
-  readonly scope?: string; // scopes needed for this request, space-separated
-}
-```
+`authenticate` is an Effect producing the identity or failing with `HttpServerResponse`.
+Its dependencies remain request requirements. Provide the returned middleware's `.layer`
+to routes requiring that identity.
+
+| Option type                | Fields                                                                                                       |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `ProtectedResourceOptions` | Required `resource` and nonempty `authorizationServers`; optional `scopesSupported`, `resourceName`.         |
+| `BearerChallengeOptions`   | Optional `error` (`invalid_token` or `insufficient_scope`), `errorDescription`, and space-separated `scope`. |
 
 ## Canonical
 
@@ -88,7 +70,7 @@ export const authentication = Authentication.middleware(
 
 export const routes = Layer.mergeAll(
   discovery.layer, // public
-  Http.layer(UserApp).pipe(Layer.provide(authentication.layer)),
+  Http.layer([UserApp]).pipe(Layer.provide(authentication.layer)),
   mcp.pipe(Layer.provide(authentication.layer)),
 );
 ```

package/docs/CONTEXT.md

@@ -12,13 +12,13 @@ use these words with these meanings.
 - **Handler**: a function from decoded input to an Effect of decoded success, failing only with the action's declared errors, possibly requiring services.
 - **Implementation**: a nominal binding of a complete handler record to a group, made by `group.implement`. Carries build-time error and requirement channels. Adapters accept implementations; `ActionCatalog` accepts contracts.
 - **Builder**: the record or Effect passed to `implement`. Runs once per adapter layer that serves the implementation.
-- **Pre-handler hook**: the `before` function an adapter binds. Runs once per invocation of that surface, with the selected action contract, before its handler. Fails with the surface's own errors. Its services are request-time requirements.
+- **Pre-handler hook**: the `before` function an adapter binds. Runs once after successful input decoding, with the selected action contract, before its handler. Invalid input skips the hook. Fails with the surface's own errors. Its services are request-time requirements.
 - **Build-time requirement**: a service yielded in the builder. Resolved when an adapter layer is built.
 - **Request-time requirement**: a service yielded inside a handler. Supplied per invocation: by router middleware for HTTP-hosted adapters, by the host for Toolkit, CLI, and stdio.
 - **Adapter** (also **projection**): a module that maps implementations or contracts onto one surface: `ActionHttp`, `ActionMcp`, `ActionToolkit`, `ActionCli`, `ActionCliClient`, `ActionCatalog`. Each adapter reads only what it serves and validates only its own namespace.
 - **Binding**: the value an adapter returns before anything runs. `ActionHttp.make` returns the HTTP binding (`groups`, `api`, `layer`); `ActionToolkit.make` returns the Toolkit binding (`toolkit`, `layer`).
 - **Contract map**: the record `ActionGroup.contracts` returns, keyed `<group>.<action>`, with each action's exact type. The shared identity of an action across routes, tools and commands.
-- **Declared error**: an error schema listed on an action or inherited from its group. Handlers may fail with it. Encoded on every transport with its `httpApiStatus`.
+- **Declared error**: an error schema listed on an action or inherited from its group. Handlers may fail with it. HTTP encodes it with its `httpApiStatus`; MCP returns encoded error text in an `isError` result. Toolkit returns a native failure result, and CLI fails its command Effect without serializing the error.
 - **Schema-error policy**: a group option mapping Effect's `HttpApiSchemaError` (decode or encode failure) to a declared policy error with a status. HTTP only.
 - **Policy error**: an error a schema-error policy may answer with. Part of the transport contract, never returnable by a handler.
 - **Surface error**: an error declared on an adapter binding rather than on an action. Produced by middleware around the surface or by its pre-handler hook, never by a handler; declared so typed callers decode it.
@@ -26,7 +26,7 @@ use these words with these meanings.
 - **Tool**: the MCP or Toolkit projection of an MCP-enabled action, named by `mcp.name` and carrying its hints.
 - **Endpoint**: one `ActionMcp.layerHttp` mount. One route, one middleware set, one tool registry.
 - **Document**: the OpenAPI output of `Http.api`, produced by Effect (`OpenApi.fromApi`).
-- **Catalog**: the offline JSON description of groups produced by `ActionCatalog.make`. Descriptive only.
+- **Catalog**: the offline JSON description of groups produced by `ActionCatalog.make`, with standalone JSON Schemas for encoded values. Descriptive only.
 - **Identity**: the per-request principal, provided by `Authentication.middleware` under an application-owned tag. Never provided at startup.
 
 ## Seams

package/docs/README.md

@@ -1,9 +1,9 @@
 # effect-actions reference
 
 Reference for `@gjermundgaraba/effect-actions`, written for coding agents. Every page is a
-card with the same sections: **API** (signatures), **Canonical** (the one right way to write
+card with the same sections: **API** (inventory and options), **Canonical** (the one right way to write
 it), **Rules** (must and never), **Failure modes** (what you see when it is wrong, and the fix).
-Read the card for a module before writing code that uses it. Vocabulary is defined in
+Read the card for a module before writing code that uses it. Exported TypeScript declarations are the exact signature reference. Vocabulary is defined in
 [CONTEXT.md](CONTEXT.md); the pages use those terms exactly.
 
 Package facts that apply everywhere:
@@ -66,11 +66,13 @@ const app = Actions.implement({
 });
 
 export const routes = Layer.mergeAll(
-  Http.layer({}, app),
-  ActionMcp.layerHttp(
-    { protocols: [McpProtocol.v2026_07_28], name: "greetings", version: "1.0.0", path: "/mcp" },
-    app,
-  ),
+  Http.layer([app]),
+  ActionMcp.layerHttp([app], {
+    protocols: [McpProtocol.v2026_07_28],
+    name: "greetings",
+    version: "1.0.0",
+    path: "/mcp",
+  }),
 );
 ```
 
@@ -83,3 +85,7 @@ Repository directory `examples/` ([on GitHub](https://github.com/gjermundgaraba/
 - `quickstart.ts`, `quickstart-client.ts`: the minimal program and its typed client.
 - `contracts.ts`, `handlers.ts`, `app.ts`, `server.ts`: an authenticated application with three groups, per-group middleware, two MCP endpoints, OpenAPI and Swagger.
 - `toolkit.ts`, `catalog.ts`, `cli.ts`, `cli-client.ts`, `mcp-stdio.ts`: one file per other projection.
+
+- `mcp-browser.ts`: a stateless MCP endpoint with a separate browser CORS policy.
+- `toolkit-authorized.ts`: native Toolkit invocation with authorization and correctly scoped identity.
+- `testing.ts`: in-memory HTTP and MCP calls with cleanup.

package/docs/Testing.md

@@ -5,43 +5,28 @@ loads the optional `@modelcontextprotocol/client` peer and nothing else does.
 
 ## API
 
-```ts
-import * as Testing from "@gjermundgaraba/effect-actions/Testing";
-import * as TestingClient from "@gjermundgaraba/effect-actions/TestingClient";
+Import `@gjermundgaraba/effect-actions/Testing`; official-client helpers are in the separate
+`@gjermundgaraba/effect-actions/TestingClient` subpath.
 
-type Handler = (request: Request) => Promise<Response>; // HttpRouter.toWebHandler(routes).handler
+| API                                          | Purpose                                                                                               |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `Testing.httpClient(api, handler, options?)` | Native grouped `HttpApiClient` over an in-memory web handler; retains client middleware requirements. |
+| `Testing.mcpRequest(options)`                | Build a stateless MCP JSON-RPC `Request`.                                                             |
+| `TestingClient.withMcpClient(options, run)`  | Connect the official client, run an asynchronous callback, then close it.                             |
 
-/** Native grouped HttpApiClient calling `handler` in memory. baseUrl defaults to http://localhost. */
-const httpClient: <Api extends HttpApi.HttpApi<any, any>>(
-  api: Api,
-  handler: Handler,
-  options?: Parameters<typeof HttpApiClient.make>[1],
-) => Effect.Effect<HttpApiClient.Client<Api>>;
+`httpClient` takes native client options; `baseUrl` defaults to `http://localhost`.
+Its exported `Handler` type is a web request to response Promise.
 
-/** One stateless 2026-07-28 JSON-RPC request with client metadata defaulted. */
-const mcpRequest: (options: McpRequestOptions) => Request;
+| MCP option                            | Meaning                                                                             |
+| ------------------------------------- | ----------------------------------------------------------------------------------- |
+| `mcpRequest`: `url`, `method`         | Required destination and JSON-RPC method.                                           |
+| `mcpRequest`: `params`, `headers`     | Optional parameters and request headers.                                            |
+| `withMcpClient`: `fetch`, `path`      | Required in-memory request handler and endpoint path.                               |
+| `withMcpClient`: `baseUrl`, `headers` | Optional base URL (default `http://localhost`) and headers.                         |
+| `withMcpClient`: `versionNegotiation` | Optional native client negotiation configuration; omitted means its native default. |
 
-interface McpRequestOptions {
-  readonly url: string | URL;
-  readonly method: string; // "tools/list", "tools/call", ...
-  readonly params?: McpRequestParams; // anything JSON.stringify accepts, undefined fields included
-  readonly headers?: HeadersInit;
-}
-
-/** Connect the official client, run the callback, always close the transport. */
-const withMcpClient: <A>(
-  options: McpClientOptions,
-  run: (client: Client) => Promise<A>,
-) => Promise<A>;
-
-interface McpClientOptions {
-  readonly fetch: (request: Request) => Promise<Response>; // the web handler
-  readonly path: string;
-  readonly versionNegotiation?: ClientOptions["versionNegotiation"]; // official client default is legacy
-  readonly baseUrl?: string | URL; // http://localhost
-  readonly headers?: HeadersInit;
-}
-```
+Exported option/value types: `McpRequestOptions`, `McpRequestParams`, `McpRequestValue`
+from `Testing`, and `McpClientOptions` from `TestingClient`.
 
 ## Canonical
 
@@ -53,25 +38,31 @@ import * as TestingClient from "@gjermundgaraba/effect-actions/TestingClient";
 import { Http, routes } from "./quickstart.js";
 
 const web = HttpRouter.toWebHandler(routes.pipe(Layer.provide(HttpServer.layerServices)));
-// call web.dispose() when the test finishes
-
-// HTTP, typed, in memory.
-const greeting = Effect.gen(function* () {
-  const client = yield* Testing.httpClient(Http.api, web.handler);
-
-  return yield* client.greetings.greet({ payload: { name: "Ada" } });
-});
 
-// MCP, raw request, no handshake (2026-07-28 is stateless).
-const listed = await web.handler(
-  Testing.mcpRequest({ url: "http://localhost/mcp", method: "tools/list" }),
-);
-
-// MCP, official client.
-const result = await TestingClient.withMcpClient(
-  { fetch: web.handler, path: "/mcp", versionNegotiation: { mode: { pin: "2026-07-28" } } },
-  (client) => client.callTool({ name: "greet", arguments: { name: "Ada" } }),
-);
+try {
+  const greeting = await Effect.runPromise(
+    Effect.gen(function* () {
+      const client = yield* Testing.httpClient(Http.api, web.handler);
+
+      return yield* client.greetings.greet({ payload: { name: "Ada" } });
+    }),
+  );
+
+  // Raw MCP request; this stateless revision needs no initialize handshake.
+  const listed = await web.handler(
+    Testing.mcpRequest({ url: "http://localhost/mcp", method: "tools/list" }),
+  );
+
+  // The official client uses the same in-memory handler.
+  const result = await TestingClient.withMcpClient(
+    { fetch: web.handler, path: "/mcp", versionNegotiation: { mode: { pin: "2026-07-28" } } },
+    (client) => client.callTool({ name: "greet", arguments: { name: "Ada" } }),
+  );
+
+  console.log({ greeting, listStatus: listed.status, result });
+} finally {
+  await web.dispose();
+}
 ```
 
 ## Rules
@@ -88,4 +79,5 @@ const result = await TestingClient.withMcpClient(
 - `@modelcontextprotocol/client` not found: only `TestingClient` needs it. Install the peer in devDependencies, or use `Testing.mcpRequest` instead.
 - Official client fails negotiation against a stateless endpoint: set `versionNegotiation: { mode: { pin: "2026-07-28" } }`.
 - Handler leaks between tests: `web.dispose()` was not called. Register it with the test runner's cleanup hook.
-- 404 from `httpClient`: `routes` did not include `Http.layer({}, app)`, or `HttpServer.layerServices` was not provided to `toWebHandler`.
+- 404 from `httpClient`: the requested route was not mounted, or the path/base URL is wrong. Include `Http.layer([app])` in the served routes.
+- Missing platform-service requirements when constructing the web handler: provide `HttpServer.layerServices` to the routes before `toWebHandler`.

package/docs/guarantees.md

@@ -5,17 +5,17 @@ Rules that hold across every adapter. Module pages link here rather than repeati
 ## Dependency lifetimes
 
 - Handlers receive decoded input, return decoded results, and may fail only with declared errors. Anything else is a defect.
-- Each surface binds its own pre-handler hook: `Http.layer({ before }, ...)`, `ActionMcp.layerHttp`/`layerStdio`, `ActionToolkit.make`, `ActionCli.command`/`group`. A bound hook runs once per invocation, before the selected handler and outside its span, for every action that surface serves. There is no per-action opt-out and no group that escapes it; only calling `build` directly does, and that is not dispatch.
+- Each surface binds its own pre-handler hook: `Http.layer(apps, { before })`, `ActionMcp.layerHttp`/`layerStdio`, `ActionToolkit.make`, `ActionCli.command`/`group`. After successful input decoding, a bound hook runs once before the selected handler and outside its span. There is no per-action opt-out; direct `build` calls bypass dispatch.
 - The hook receives the selected action contract (`Action.Any`), so a policy reads `action.access`, `action.name` or `action.mcp` instead of a hand-maintained list. It is not authentication: establish identity in middleware, then let the hook authorize what that identity may do.
-- It fails with the surface's own `errors`, the same list that declares what the surface answers instead of a handler, so a refusal is encoded exactly like a declared error: the schema's `httpApiStatus` on HTTP, an `isError` tool result on MCP, a returned failure on the Toolkit. `ActionCli` declares no errors because it encodes nothing; there a refusal is a typed failure of the command effect.
+- It fails with the surface's own `errors`, the same list that declares what the surface answers instead of a handler, so a refusal is encoded exactly like a declared error: the schema's `httpApiStatus` on HTTP, an `isError` tool result on MCP, a returned failure on the Toolkit. `ActionCli` declares no surface errors because it does not serialize failures; there a refusal is a typed failure of the command effect.
 - Its services are request-time requirements, like a handler's, and they join the adapter's request context. A local caller (`ActionCli`, `ActionToolkit`, stdio) supplies them itself.
-- Ordering differs by surface, because each hooks into its own transport: HTTP runs the hook **before** the request payload is decoded, so an unauthorized caller learns nothing about the input schema. MCP, the Toolkit and the CLI run it after the native transport has decoded the arguments, since decoding is the transport's own first step there.
+- All surfaces decode input before dispatch. Invalid input skips the hook and handler, so unauthorized callers can receive schema errors. Use outer native HTTP middleware for admission that must run before decoding; a pre-handler hook does not provide that guarantee.
 - Build-time services are those yielded in the `implement` builder Effect. They resolve once per adapter layer, in that layer's scope. An implementation served by two adapters is built twice. Share state through a Layer provided to the adapters, never through the builder.
 - Request-time services are those yielded inside a handler. For HTTP-hosted adapters (`ActionHttp`, `ActionMcp.layerHttp`) they appear as `HttpRouter.Request.From<"Requires", R>` and are supplied by router middleware, `HttpRouter.provideRequest`, or request context. For `ActionToolkit`, `ActionCli`, and `ActionMcp.layerStdio` the host supplies them at invocation.
 - Use distinct tags for build-time capabilities and request-scoped identity. Never provide an identity or tenant tag in a startup layer or root context. The adapters use native Effect context capture and merging: a startup value under a tag can shadow a request value or satisfy a missing one. Types verify presence, not provenance.
-- Authentication must establish identity on every protected request. Types cannot verify that a handler performed authorization; the `before` hook is the one place the library guarantees runs first, so put the check there rather than in each handler.
-- `access` is contract metadata, required on every action and kept as a literal type. Nothing in the library reads it: adapters ignore it and the catalog omits it. It exists so a hook can switch on what an action does instead of on its name.
-- `ActionCli` acquires the implementation per invocation and releases it after the call. `ActionToolkit.layer` acquires it once for the layer's lifetime.
+- Authentication must establish identity on every protected request. Types cannot verify that a handler performed authorization; the `before` hook is the one place the library guarantees runs before the handler, so put the check there rather than in each handler.
+- `access` is contract metadata, required on every action and kept as a literal type. It supplies the default MCP `readOnly` hint and the `action.access` span/log annotation, but enforces no authorization. A hook can switch on what an action does instead of on its name. The catalog omits it.
+- `ActionCli` acquires the implementation per invocation and releases it after the call. `ActionToolkit.make(...).layer` acquires it once for the layer's lifetime.
 
 ## Wire behavior
 
@@ -26,14 +26,14 @@ Defaults without a schema-error policy. HTTP is a native `HttpApi`; MCP is a nat
 | Input                       | decoded with the schema's JSON codec; failure is an empty **400**                                     | decoded with the schema's JSON codec; failure is `InvalidParams`, presented as an `isError` result     |
 | Success                     | the success codec's encoding as the body: `{"id":"1","name":"Ada"}`, `42`                             | `structuredContent: { value: <encoded> }`                                                              |
 | Declared error              | encoded by its schema with its `httpApiStatus` (unannotated: 500): `{"_tag":"UserNotFound","id":"x"}` | `isError: true`; text content is the same JSON; no `structuredContent`                                 |
-| Pre-handler hook failure    | the same, using the hook's error schema, before the payload is decoded; the handler never runs        | the same `isError` result, after arguments are decoded; the handler never runs                         |
+| Pre-handler hook failure    | the same, using the hook's error schema, after input decoding; the handler never runs                 | the same `isError` result, after arguments are decoded; the handler never runs                         |
 | Invalid output encoding     | empty **400** (`HttpApiSchemaError`)                                                                  | `isError: true`, text `Tool execution failed due to an internal server error.`; cause logged, not sent |
 | Defect                      | empty **500**                                                                                         | same generic `isError` result; cause logged, not sent                                                  |
 | Unknown path or method      | 404                                                                                                   | n/a                                                                                                    |
 | Invalid JSON / content type | 400 / 415                                                                                             | n/a                                                                                                    |
 
 - A group `schemaError` policy replaces the empty 400s on HTTP with a declared error and status. It never affects MCP. Details in [ActionGroup.md](ActionGroup.md).
-- Every HTTP response with a status of 400 or more carries `cache-control: no-store`. Successful responses are left to the host. An error response has no other added headers: a hook refusal and a handler error are plain declared errors, and challenge headers such as `WWW-Authenticate` belong to the admission middleware that answers before the router reaches these routes.
+- `ActionHttp` sets no headers of its own. The host owns cache and challenge headers; `Authentication.middleware` marks its responses `cache-control: no-store`. Hook refusals and handler failures are ordinary declared error responses.
 - Routes are `POST <apiPath>/<group>/<action>`. Operation IDs are `<group>.<action>`. Effect generates OpenAPI component names and references.
 - `ActionHttp.make`'s `errors` are declared on every endpoint so clients decode the surface's own failures (401, 403, 429, 503). They are produced by middleware or by the binding's hook, never by a handler. `ActionMcp` and `ActionToolkit` declare their own `errors` the same way, joined into every tool's failure schema. Two errors may share an HTTP status; their `_tag`s must differ, because the client decodes a status by trying the schemas declared for it.
 - HTTP strips undeclared input fields. MCP tools are strict (`Tool.Strict`): undeclared arguments are an invalid-arguments result and input schemas publish `additionalProperties: false`. HTTP is not strict, and cannot be made strict without a hack: Effect merges one `HttpApi.ParseOptions` per endpoint and uses it for payload decoding _and_ error encoding, so `onExcessProperty: "error"` also rejects a `TaggedError` instance's own `message` and `stack`, turning a declared 409 into an empty 500. Making the payload schema itself strict would require wrapping it in an open schema, which erases its OpenAPI shape. Declare the fields you accept and treat extra HTTP fields as ignored.
@@ -46,7 +46,7 @@ Defaults without a schema-error policy. HTTP is a native `HttpApi`; MCP is a nat
 
 ## Observability
 
-- Each handler runs in a span named `<group>.<action>`, a child of the transport's request span. The pre-handler hook, decoding and encoding happen outside the handler span.
+- Each handler runs in a span named `<group>.<action>`, a child of the transport's request span, with attributes `action.group`, `action.name` and `action.access`. Every log line the handler writes carries the same three annotations. The pre-handler hook, decoding and encoding happen outside the handler span.
 - MCP defects and encoding failures are logged with their cause and answered generically.
 
 ## MCP transport

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/effect-actions",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Define Effect action contracts once and project them onto HTTP, MCP, native Toolkits, catalogs, and CLIs.",
   "homepage": "https://github.com/gjermundgaraba/effect-actions#readme",
   "bugs": {