@gjermundgaraba/effect-actions 0.9.0 → 0.10.0

package/dist/ActionHttp.d.mts

@@ -1,62 +1,181 @@
-import { Action_d_exports, Any, Codec } from "./Action.mjs";
-import { Actions, PolicyError } from "./internal/actions.mjs";
-import { AnyImplementation, BuildContext, BuildError, RequestContext } from "./internal/implementation.mjs";
-import { Effect, Layer, Schema } from "effect";
-import { Etag, HttpPlatform, HttpRouter } from "effect/http";
-import { HttpApi, HttpApiEndpoint, HttpApiGroup } from "effect/http-api";
-import { FileSystem } from "effect/FileSystem";
-import { Path } from "effect/Path";
-declare namespace ActionHttp_d_exports {
-  export { Api, Http, LayerOptions, Options, make };
-}
-/** Contract-level configuration: servers and clients must agree on it. */
-export interface Options<Errors extends ReadonlyArray<Codec> = []> {
-  readonly apiPath: `/${string}`;
-  /**
-   * Failures the surface around these endpoints answers with instead of a
-   * handler: authentication, authorization, rate limits. Declared on every
-   * endpoint, so `HttpApiClient` and `ActionCliClient` decode them as typed
-   * failures rather than reporting a decode error. Each schema keeps its own
-   * `httpApiStatus`, and their `_tag`s must be distinct.
-   */
-  readonly errors?: Errors;
-}
-/** What `Http.layer` binds around the implementations it serves. */
-export interface LayerOptions<Errors extends ReadonlyArray<Codec>, R> {
+import { Anyone } from "./internal/actions.mjs";
+import { BuiltIn, BuiltIns } from "./internal/errors.mjs";
+import { BuildError, BuildServices, Holding, Known, Member, Protected, Selected, Served, Serving } from "./internal/implementation.mjs";
+import { Action_d_exports, Any, Errors } from "./Action.mjs";
+import { Any as Any$1, Identity, Matching, RemoteRequest, Required, ServedProvider, VerifierError } from "./internal/authentication.mjs";
+import { AnyHttp, Client, MethodError, Options } from "./internal/client.mjs";
+import { ErrorsOf } from "./internal/declared.mjs";
+import { Context, Effect, FileSystem, Layer, Path, Schema, Types } from "effect";
+import { Etag, HttpClient, HttpPlatform, HttpRouter } from "effect/http";
+import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware } from "effect/http-api";
+//#region src/ActionHttp.d.ts
+/** What `fetchClient` takes: `client`'s options, and the `fetch` its calls send with. */
+export interface FetchClientOptions extends Options {
   /**
-   * Runs once after successful payload decoding, before the selected handler,
-   * with its action contract. It fails with the binding's own `errors`, encoded
-   * exactly like a declared error. Its services are request-time
-   * requirements, like a handler's.
+   * What each call sends with. Omitted: the global `fetch`, looked up on every call, so one
+   * installed after the client is built, such as a test's stub, is used.
    */
-  readonly before?: (action: Any) => Effect.Effect<void, Errors[number]["Type"], R>;
+  readonly fetch?: typeof globalThis.fetch | undefined;
 }
-type Endpoint<A extends Any, E extends Codec> = A extends Any ? HttpApiEndpoint.HttpApiEndpoint<A["name"], "POST", `/${string}`, never, never, Schema.toCodecJson<A["input"]>, never, Schema.toCodecJson<A["success"]>, Schema.toCodecJson<A["errors"][number] | E>, never> : never;
-type ApiGroup<G extends Actions, E extends Codec> = G extends Actions ? [Endpoint<G["actions"][number], never>] extends [never] ? never : HttpApiGroup.HttpApiGroup<G["name"], Endpoint<G["actions"][number], PolicyError<G> | E>> : never;
-/** The native `HttpApi` of every action of `G`, one group per action group. */
-export type Api<G extends Actions, E extends Codec = never> = HttpApi.HttpApi<"actions", ApiGroup<G, E>>;
-/** A namespaced HTTP binding. */
-export interface Http<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec> = []> {
-  /** The exact contracts bound to this HTTP adapter, in declaration order. */
-  readonly groups: Groups;
-  readonly api: Api<Groups[number], Errors[number]>;
+/** Native endpoint middleware, as `HttpApiMiddleware.Service` declares it. */
+type Middleware = ReadonlyArray<Context.Key<HttpApiMiddleware.AnyId, unknown>>;
+/** The identifier a middleware's service key declares. */
+type IdOf<K> = K extends Context.Key<infer I extends HttpApiMiddleware.AnyId, unknown> ? I : never;
+/**
+ * What the request owes past the middleware `M`, the first innermost, around what `R` owes:
+ * each removes what it provides and adds what it requires, as native endpoints apply them.
+ * An array of unknown length, which may hold none of them, provides nothing and owes what
+ * any of them requires; so does a slot that may hold one of several, as only one runs.
+ */
+type Through<M extends Middleware, R> = number extends M["length"] ? R | HttpApiMiddleware.Requires<IdOf<M[number]>> : M extends readonly [infer K, ...infer Rest extends Middleware] ? Through<Rest, true extends Types.IsUnion<IdOf<K>> ? R | HttpApiMiddleware.Requires<IdOf<K>> : HttpApiMiddleware.ApplyServices<IdOf<K>, R>> : R;
+/**
+ * The middleware options `O` install: its `middleware` when always given, an array of unknown
+ * length when it may be absent, which installs none or all of them, and none otherwise.
+ */
+type MiddlewareOf<O> = O extends {
+  readonly middleware: infer M extends Middleware;
+} ? M : O extends {
+  readonly middleware?: infer M extends Middleware | undefined;
+} ? "middleware" extends keyof O ? ReadonlyArray<NonNullable<M>[number]> : [] : [];
+/**
+ * The layer's middleware, refused when one fails with an error neither the binding, `E`, nor
+ * every endpoint declares, or needs a client counterpart: neither reaches the binding's
+ * clients, which decode only what the binding and the built-ins declare. A failure an
+ * action's callers see after decoding is its handler's, declared on the contract and decoded
+ * by every client.
+ */
+type ServerOnly<M extends Middleware, E extends Errors> = [Exclude<HttpApiMiddleware.Error<IdOf<M[number]>>, Extract<Certain<E>, Errors[number]>["Type"] | BuiltIn> | HttpApiMiddleware.MiddlewareClient<IdOf<M[number]>>] extends [never] ? unknown : {
+  readonly "Layer middleware fails only with the binding's errors and needs no client": never;
+};
+/** `T` where it is one type, not a union: what a list's slot of type `T` surely holds. */
+type Single<T> = true extends Types.IsUnion<T> ? never : T;
+/**
+ * The errors a binding of errors `E` surely declares: each slot of one error in a list of
+ * fixed length, never one of an array of unknown length, which may be empty, nor of a list
+ * `E` may be one of several.
+ */
+type Certain<E extends Errors> = true extends Types.IsUnion<E> ? never : number extends E["length"] ? never : { readonly [K in keyof E]: Single<E[K]>; }[number];
+/**
+ * The layer serving the actions `A` of `Apps` through the binding `H`, behind the middleware
+ * `M`: an implementation holding none of them is not built.
+ */
+type HttpLayer<H extends AnyHttp, Apps extends Served, M extends Middleware, A extends Any = H["actions"][number]> = Layer.Layer<never, BuildError<Holding<Member<Apps>, A>, A>, BuildServices<Holding<Member<Apps>, A>, A> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", LayerRequest<Member<Apps>, A, M>> | ServedProvider<Member<Apps>, A, H extends {
+  readonly authentication: infer D;
+} ? D : never> | IdOf<M[number]> | Etag.Generator | FileSystem.FileSystem | HttpPlatform.HttpPlatform | Path.Path>;
+/** `ActionHttp.layer`'s options. */
+export interface LayerOptions<M extends Middleware = [], A extends Any = never> {
   /**
-   * Serve any number of implementations in one layer, with one pre-handler hook
-   * around every request they answer. Build failures, build services and request
-   * services are unions over precisely those apps and that hook.
+   * The actions it serves, among the binding's actions the implementations hold: `[GetUser]`.
+   * Defaults to every one of them. A layer whose middleware requires the identity lists
+   * protected actions only.
    */
-  readonly layer: <const Apps extends ReadonlyArray<AnyImplementation<Groups[number]>>, RB = never>(apps: readonly [...Apps], options?: LayerOptions<Errors, RB>) => Layer.Layer<never, BuildError<Apps[number]>, BuildContext<Apps[number]> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", RequestContext<Apps[number]> | RB> | Etag.Generator | FileSystem | HttpPlatform.HttpPlatform | Path>;
+  readonly actions?: ReadonlyArray<A> | undefined;
   /**
-   * Serve the OpenAPI document of `api` with `GET path`, by default
-   * `<apiPath>/openapi.json`. It is a plain route: middleware provided to this layer
-   * covers it, and none is applied otherwise.
+   * Native endpoint middleware every served route runs, the first innermost: inside the
+   * authentication of a protected route, outside its decoding. A middleware requiring the
+   * identity needs a layer serving only protected actions.
    */
-  readonly openApi: (path?: HttpRouter.PathInput) => Layer.Layer<never, never, HttpRouter.HttpRouter>;
+  readonly middleware?: M;
+}
+/** What the layer serving `A` of `App` behind middleware `M` owes per request. */
+type LayerRequest<App, A extends Any, M extends Middleware> = Exclude<Through<M, RemoteRequest<App, A>>, HttpRouter.Provided | ([Extract<Serving<App, A>, {
+  readonly caller: typeof Anyone;
+}>] extends [never] ? Identity<Protected<Serving<App, A>>> : never)>;
+/** Actions a binding takes without options: public ones, as a protected one names its descriptor. */
+type PublicOnly<Actions extends ReadonlyArray<Any>> = [Exclude<Actions[number], {
+  readonly caller: typeof Anyone;
+}>] extends [never] ? unknown : {
+  readonly "Protected actions take options naming their authentication": never;
+};
+/** The descriptor options `O` name, where they always name one. */
+type DescriptorOf<O> = [O] extends [{
+  readonly authentication: infer D extends Any$1;
+}] ? D : undefined;
+/** Contract-level configuration shared by servers and clients. */
+interface Options$1<E extends Errors = Errors> {
+  readonly prefix?: `/${string}`;
+  /** Router middleware's errors, which every endpoint declares: one schema, or a list. */
+  readonly error?: E | E[number];
+  readonly authentication?: Any$1;
+}
+type Endpoint<A extends Any, E extends Errors, D> = A extends Any ? HttpApiEndpoint.HttpApiEndpoint<A["name"], "POST", `/${string}`, never, never, Schema.toCodecJson<A["input"]>, never, Schema.toCodecJson<A["success"]>, Schema.toCodecJson<A["error"][number] | E[number] | VerifierError<A, D> | BuiltIns>, never> : never;
+/**
+ * The native `HttpApi` of `Actions`: one top-level group, so native client methods are
+ * not nested, named after the binding's mount path, `/` at the root, so bindings composed
+ * into one host API keep their own groups.
+ */
+type Api<Actions extends ReadonlyArray<Any>, E extends Errors, D> = HttpApi.HttpApi<"actions", HttpApiGroup.HttpApiGroup<string, Endpoint<Actions[number], E, D>, true>>;
+/**
+ * An HTTP binding: actions, the errors every endpoint declares, and where they are mounted.
+ * Plain data, so a copy of it, or one made by another installed copy of this package,
+ * serves the same; `layer` serves it and `client` calls it.
+ */
+export interface Binding<Actions extends ReadonlyArray<Any>, E extends Errors = [], D extends Any$1 | undefined = undefined> {
+  readonly authentication: D;
+  /** The exact actions bound to this binding. */
+  readonly actions: Actions;
+  /** The errors every endpoint declares besides its action's own, as a list. */
+  readonly error: E;
+  /** Where its routes mount: `/api` by default, `/` at the root, without a trailing slash. */
+  readonly prefix: `/${string}`;
+  readonly api: Api<Actions, E, D>;
 }
 /**
- * Bind the contract-level configuration once. Every route is `POST
- * <apiPath>/<group>/<action>`, so action names may repeat across groups.
+ * Bind actions once, for servers and clients alike, each at `POST <prefix>/<action>`.
+ * Every endpoint declares its action's errors, the binding's `errors`, and the built-in
+ * `InvalidInput`, `Unauthenticated` and `Forbidden`, so clients decode each as a typed
+ * failure. A union's own `httpApiStatus` applies to every member; otherwise, each member
+ * uses its own status, or 422 without one. Protected contracts receive native endpoint
+ * security middleware: the same descriptor documents their credentials and enforces them.
+ */
+export declare function make<const Actions extends ReadonlyArray<Any & {
+  readonly caller: typeof Anyone;
+}>>(actions: Actions): Binding<Actions, [], undefined>;
+export declare function make<const Actions extends ReadonlyArray<Any>, const O extends Options$1 = {}>(actions: Actions, options: O & Required<Actions[number]> & Matching<Actions[number], NoInfer<DescriptorOf<O>>> & NoInfer<Known<O, Options$1>>): Binding<Actions, ErrorsOf<O>, DescriptorOf<O>>;
+export declare function make<const Actions extends ReadonlyArray<Any>>(actions: Actions & PublicOnly<Actions>): Binding<Actions, [], undefined>;
+/**
+ * Serve the binding's actions among `implementations` in one layer, or those its `actions` lists,
+ * authenticating a protected action's request before decoding it, then running its implementation's
+ * `authorize` before each handler. The binding decides what may be served:
+ * an implementation's actions the binding leaves out have no route here, and one holding none of
+ * those served is not built; implementations holding none of the binding's actions at all are
+ * refused when `layer` is called. It mounts only the routes of the actions it serves, so one
+ * binding may be served by several layers, each with its own `actions` and `middleware`, which
+ * covers its routes only. Each implementation's builder runs once per layer graph however many
+ * layers serve it.
+ *
+ * The layer fails as the builders do, needs at startup what they need, and per request what
+ * each implementation's authorization and the handlers of the actions it serves
+ * need, until its `middleware` or middleware provided around it provides them, the identity
+ * of a protected action excepted, which its authentication provides; the router provides
+ * its own, such as the request, to every route. Its routes take only requests typed as JSON,
+ * and what middleware provides per request wins over what the layer was built with.
+ */
+export declare function layer<const H extends AnyHttp, const Apps extends Served>(binding: H, implementations: Apps): HttpLayer<H, Apps, []>;
+export declare function layer<const H extends AnyHttp, const Apps extends Served, const O extends LayerOptions<Middleware, H["actions"][number]>>(binding: H, implementations: Apps, options: O & ServerOnly<MiddlewareOf<O>, H["error"]> & NoInfer<Known<O, LayerOptions<Middleware>>>): HttpLayer<H, Apps, MiddlewareOf<O>, Selected<O, H["actions"][number]>>;
+/**
+ * Effect's native `HttpApiClient` for a binding, one method per action taking the
+ * action's input directly: `client.greet({ name })`. The argument may be omitted when `{}`
+ * is a valid input. Requires the native `HttpClient`, as `HttpApiClient.make` does.
+ * The options are the native ones, `baseUrl` and `transformClient`. The native client
+ * itself stays available: `HttpApiClient.make(Http.api)`.
+ *
+ * A call fails with a declared error value (the action's own, or a built-in
+ * `InvalidInput`, `Unauthenticated` or `Forbidden`), a native `HttpClientError` when the
+ * server could not be reached or answered with a status or body the contract does not
+ * declare, or a `SchemaError` when the input does not encode or the success does not
+ * decode.
+ */
+export declare function client<const H extends AnyHttp>(binding: H, options?: Options): Effect.Effect<Client<H>, never, HttpClient.HttpClient>;
+/**
+ * `client` built once over `fetch`, for code that holds a client outside an Effect, such as
+ * a browser app: its methods are the same Effects and require nothing, so each call runs
+ * alone, as `Effect.runPromise(api.greet({ name }))`. The options are `client`'s, and
+ * `fetch`.
+ *
+ * Each call sends with `options.fetch`, or with the global `fetch` as it is when the call
+ * runs.
  */
-export declare function make<const G extends ReadonlyArray<Actions>, const E extends ReadonlyArray<Codec> = []>(options: Options<E>, ...groups: G): Http<G, E>;
+export declare function fetchClient<const H extends AnyHttp>(binding: H, options?: FetchClientOptions): Client<H>;
 //#endregion
-export { ActionHttp_d_exports };
+export { type AnyHttp as Any, type Client, type Options as ClientOptions, type MethodError, Options$1 as Options };

package/dist/ActionHttp.mjs

@@ -1,90 +1,141 @@
-import { answerSchemaError, assertDistinct, policyErrors, projectedErrors } from "./internal/actions.mjs";
-import { dispatch } from "./internal/implementation.mjs";
-import { Effect, Layer } from "effect";
-import { HttpRouter, HttpServerResponse } from "effect/http";
-import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, OpenApi } from "effect/http-api";
+import { Anyone, assertDistinct, assertOnce, assertOwnTags, errorList, projectedErrors } from "./internal/actions.mjs";
+import { acquire, assertHeld, provideHandlers, select, toList } from "./internal/implementation.mjs";
+import { assertAuthentication } from "./internal/authentication.mjs";
+import { declared } from "./internal/declared.mjs";
+import { methods } from "./internal/client.mjs";
+import { SchemaErrors, schemaErrors } from "./internal/schema-errors.mjs";
+import { Context, Effect, Layer, Scope } from "effect";
+import { FetchHttpClient, HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
+import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiSchema, OpenApi } from "effect/http-api";
 //#region src/ActionHttp.ts
-const endpoint = (options, group, action) => HttpApiEndpoint.post(action.name, `${options.apiPath}/${group.name}/${action.name}`, {
-	payload: action.input,
-	success: action.success,
-	error: projectedErrors(action, options.errors)
-}).annotate(OpenApi.Description, action.description);
-/** The native middleware declares the policy's errors on every endpoint it wraps. */
-const schemaErrorMiddleware = (name, policy) => {
-	class SchemaErrors extends HttpApiMiddleware.Service()(`effect-actions/http/SchemaErrors/${name}`, { error: policyErrors(policy) }) {}
-	return {
-		SchemaErrors,
-		layer: HttpApiMiddleware.layerSchemaErrorTransform(SchemaErrors, (failure) => Effect.fail(answerSchemaError(policy, failure)))
-	};
+/** The mount path's segments: `api` by default; none for `/`. */
+const mountSegments = (prefix) => (prefix ?? "/api").split("/").filter((segment) => segment !== "");
+/** An absolute route from path segments. */
+const route = (segments) => `/${segments.join("/")}`;
+/**
+* The name of a binding's one native group: its OpenAPI tag, by which the native `addHttpApi`
+* keys groups. It is the mount path, `/` at the root, which no segment contains.
+*/
+const groupName = (mount) => mount.join("/") || "/";
+/** A native API of one top-level group of `endpoints`. */
+const apiOf = (group, endpoints) => {
+	const empty = HttpApiGroup.make(group, { topLevel: true });
+	const [first, ...rest] = endpoints;
+	return HttpApi.make("actions").annotate(HttpApi.ParseOptions, { errors: "all" }).add(first === void 0 ? empty : empty.add(first, ...rest));
 };
-function bind(options, group) {
-	const [first, ...rest] = group.actions.map((action) => endpoint(options, group, action));
-	if (first === void 0) return void 0;
-	const bound = HttpApiGroup.make(group.name).add(first, ...rest);
-	if (group.schemaError === void 0) return {
-		native: bound,
-		middleware: Layer.empty
-	};
-	const policy = schemaErrorMiddleware(group.name, group.schemaError);
+/**
+* `apps` narrowed to the actions the layer serves, matched by identity: those `listed`, which
+* the binding must hold, or every one of the binding's they hold, each once. An
+* implementation holding none of them is left out, and not built. Implementations holding
+* none of the binding's actions are refused, as the wrong implementations or the wrong
+* binding; a name the binding holds is marked as another contract's, as a second copy of the
+* contracts module makes one.
+*/
+const servedBy = (binding, apps, listed) => {
+	if (listed !== void 0) assertHeld("the binding does not hold it", listed, binding.actions);
+	const held = apps.flatMap((app) => app.actions);
+	const served = select(apps, listed ?? binding.actions.filter((action) => held.includes(action)));
+	const actions = served.flatMap((app) => app.actions);
+	if (actions.length === 0 && listed === void 0 && apps.length > 0) {
+		const bound = new Set(binding.actions.map(({ name }) => name));
+		throw new Error(`No action of these implementations is in this HTTP binding: ${held.map(({ name }) => bound.has(name) ? `${name} (another contract)` : name).join(", ") || "none"}`);
+	}
+	assertOnce("served action", actions);
+	return served;
+};
+/**
+* The native endpoint of `action` at `path`, declaring its action's errors, the binding's
+* `errors` and the built-in ones: what `make` documents and `layer` serves. Its payload is
+* JSON whatever encoding the input is annotated with, which no other surface reads either:
+* `HttpApi` would take a form or text body for it, which a page sends without a preflight.
+*/
+const endpointOf = (action, path, errors) => HttpApiEndpoint.post(action.name, path, {
+	payload: action.input.pipe(HttpApiSchema.asJson()),
+	success: action.success,
+	error: projectedErrors(action, errors).flatMap(declared)
+});
+/** An endpoint wrapped in a layer's middleware, the first innermost. */
+const within = (endpoint, middleware = []) => middleware.reduce((inner, key) => inner.middleware(key), endpoint);
+function make(actions, options = {}) {
+	assertOnce("action", actions);
+	const errors = errorList(options.error);
+	assertOwnTags("ActionHttp binding", errors);
+	assertAuthentication(actions, options.authentication);
+	const mount = mountSegments(options.prefix);
+	const security = options.authentication?.["~middleware"];
+	const verifierErrors = options.authentication?.error ?? [];
+	const endpoints = actions.map((action) => {
+		const isPublic = security === void 0 || action.caller === Anyone;
+		const endpoint = endpointOf(action, route([...mount, action.name]), isPublic ? errors : [...errors, ...verifierErrors]).annotate(OpenApi.Description, action.description);
+		return isPublic ? endpoint : endpoint.middleware(security);
+	});
+	const api = apiOf(groupName(mount), endpoints);
 	return {
-		native: bound.middleware(policy.SchemaErrors),
-		middleware: policy.layer
+		actions,
+		error: errors,
+		prefix: route(mount),
+		api,
+		authentication: options.authentication
 	};
 }
-function apiOf(groups) {
-	const [first, ...rest] = groups;
-	const empty = HttpApi.make("actions").annotate(HttpApi.PayloadParseOptions, {
+/**
+* `group`, built in an empty context rather than the one around it: `HttpApiBuilder` lays
+* the context a group is built in over every request's, where a startup value would replace
+* what middleware provides for the request. `entry` puts that context beneath it instead.
+*/
+const buildAlone = (group) => Layer.fromBuild((memoMap, scope) => Effect.setContext(Layer.buildWithMemoMap(group, memoMap, scope), Context.empty()));
+/**
+* Restore startup dependencies beneath request context, so a caller's services win.
+*/
+const entry = () => HttpRouter.middleware(Effect.map(Effect.context(), (built) => {
+	const startup = Context.omit(Scope.Scope)(built);
+	return (route) => Effect.updateContext(route, (current) => Context.merge(startup, current));
+})).layer;
+/**
+* Answers a protected route's step-up refusal, as it leaves the layer's middleware, with its
+* challenge: the provider's `stepUp`, inside the authentication.
+*/
+var StepUp = class extends HttpApiMiddleware.Service()("effect-actions/ActionHttp/StepUp") {};
+/** Require JSON media typing after endpoint authentication, before payload decoding. */
+var JsonContentType = class extends HttpApiMiddleware.Service()("effect-actions/ActionHttp/JsonContentType") {};
+/** `JsonContentType`'s server side, built by `layer` alone, so a client's bundle leaves it out. */
+const jsonContentType = () => Layer.succeed(JsonContentType, (route) => Effect.flatMap(HttpServerRequest.HttpServerRequest, (request) => request.headers["content-type"] === void 0 ? Effect.succeed(HttpServerResponse.text("Unsupported content-type: none", { status: 415 })) : route));
+function layer(binding, served, options = {}) {
+	const apps = servedBy(binding, toList(served), options.actions);
+	const actions = apps.flatMap((app) => app.actions);
+	assertAuthentication(actions, binding.authentication);
+	assertDistinct("middleware", options.middleware ?? [], (key) => key.key);
+	const mount = mountSegments(binding.prefix);
+	const name = groupName(mount);
+	const api = apiOf(name, actions.map((action) => {
+		const endpoint = within(endpointOf(action, route([...mount, action.name]), binding.error).middleware(JsonContentType).middleware(SchemaErrors), options.middleware);
+		return action.caller === Anyone || binding.authentication === void 0 ? endpoint : endpoint.middleware(StepUp).middleware(binding.authentication["~middleware"]);
+	})).annotate(HttpApi.PayloadParseOptions, {
 		errors: "all",
 		onExcessProperty: "error"
 	});
-	return first === void 0 ? empty : empty.add(first, ...rest);
+	const handlers = Layer.unwrap(Effect.gen(function* () {
+		const bound = yield* acquire(apps);
+		const auth = actions.some((action) => action.caller !== Anyone) ? binding.authentication : void 0;
+		const authentication = auth === void 0 ? Layer.empty : yield* Effect.flatMap(auth["~provider"], (provider) => provider.descriptor === auth ? Effect.succeed(Layer.mergeAll(Layer.succeed(auth["~middleware"], provider.middleware), Layer.succeed(StepUp, provider.stepUp))) : Effect.die(/* @__PURE__ */ new Error(`Authentication "${auth.name}": the binding's descriptor is not its provider's; build both from one descriptor`)));
+		const middleware = yield* Effect.forEach(options.middleware ?? [], (key) => Effect.map(Effect.service(key), (service) => Layer.succeed(key, service)));
+		const byName = Object.fromEntries(bound.map(([action, run]) => [action.name, (request) => run(request.payload)]));
+		return HttpApiBuilder.group(api, name, (builder) => builder.handleAll(byName)).pipe(Layer.provide([
+			schemaErrors(),
+			jsonContentType(),
+			authentication,
+			...middleware
+		]), buildAlone);
+	})).pipe(provideHandlers(apps));
+	return HttpApiBuilder.layer(api).pipe(Layer.provide(handlers), Layer.provide(entry()));
 }
-/**
-* `HttpApiBuilder.handleAll` registers a dynamically assembled record. The
-* action selected by the native router determines the input before `dispatch`
-* calls its handler, so this is the one adapter boundary where exact handlers
-* are viewed as an erased record. `HandlersContext` remains on the dispatch
-* effect and is restored by `Http.layer`'s public signature.
-*/
-const erasedHandlers = (handlers) => {
-	return handlers;
-};
-/** Register one group's handlers. Handler erasure is limited to native dynamic endpoint registration. */
-const groupHandlers = (api, app, middleware, before) => {
-	const entries = (record) => Object.fromEntries(app.group.actions.map((action) => {
-		const run = dispatch(app.group, action, record, before);
-		return [action.name, (request) => run(request.payload)];
-	}));
-	return Layer.unwrap(Effect.map(app.build, (record) => HttpApiBuilder.group(api, app.group.name, (builder) => builder.handleAll(entries(erasedHandlers(record)))))).pipe(Layer.provide(middleware));
-};
-function make(options, ...groups) {
-	assertDistinct("action group", groups.map((group) => group.name));
-	const bound = new Map(groups.flatMap((group) => {
-		const binding = bind(options, group);
-		return binding === void 0 ? [] : [[group, binding]];
-	}));
-	const layer = (apps, layerOptions = {}) => {
-		assertDistinct("implementation group", apps.map((app) => app.group.name));
-		for (const app of apps) if (!groups.includes(app.group)) throw new Error(`Implementation of group "${app.group.name}" is not served by this adapter`);
-		const served = apps.flatMap((app) => {
-			const binding = bound.get(app.group);
-			return binding === void 0 ? [] : [{
-				app,
-				...binding
-			}];
-		});
-		const api = apiOf(served.map(({ native }) => native));
-		const [first, ...rest] = served.map(({ app, middleware }) => groupHandlers(api, app, middleware, layerOptions.before));
-		return first === void 0 ? HttpApiBuilder.layer(api) : HttpApiBuilder.layer(api).pipe(Layer.provide([first, ...rest]));
-	};
-	const api = apiOf([...bound.values()].map(({ native }) => native));
-	const openApi = (path = `${options.apiPath}/openapi.json`) => HttpRouter.add("GET", path, HttpServerResponse.jsonUnsafe(OpenApi.fromApi(api)));
-	return {
-		groups,
-		api,
-		layer,
-		openApi
-	};
+/** A binding's client, erased: `client` and `fetchClient` restore its exact type. */
+const erasedClient = (binding, options) => Effect.map(methods(binding, options), (methodOf) => Object.fromEntries(binding.actions.map((action) => [action.name, methodOf(action)])));
+function client(binding, options) {
+	return erasedClient(binding, options);
+}
+function fetchClient(binding, { fetch, ...options } = {}) {
+	return erasedClient(binding, options).pipe(Effect.provide(FetchHttpClient.layer), Effect.provideService(FetchHttpClient.Fetch, fetch ?? ((input, init) => globalThis.fetch(input, init))), Effect.runSync);
 }
 //#endregion
-export { make };
+export { client, fetchClient, layer, make };

package/dist/ActionMcp.d.mts

@@ -1,35 +1,85 @@
-import { Action_d_exports, Codec } from "./Action.mjs";
-import { AnyImplementation, BuildContext, BuildError, HiddenFromMcp, RequestContext } from "./internal/implementation.mjs";
-import { SurfaceOptions } from "./internal/tools.mjs";
-import { Cause, Layer } from "effect";
+import { ActionOf, BuildError, BuildServices, Holding, Known, Member, Protected, SelectedOf, Selection, Served, ServedRequest } from "./internal/implementation.mjs";
+import { Action_d_exports, Any } from "./Action.mjs";
+import { Any as Any$1, Matching, ProviderOf, RemoteRequest, Required } from "./internal/authentication.mjs";
+import { Cause, Effect, Layer, Stdio } from "effect";
 import { HttpRouter } from "effect/http";
 import { McpSchema, McpServer } from "effect/ai";
-import { Stdio } from "effect/Stdio";
 //#region src/ActionMcp.d.ts
 /**
- * One Streamable HTTP MCP endpoint: every native `McpServer.layerHttp` option except
- * `protocols` (server information, `path`, `allowedOrigins`, `instructions`,
- * `extensions`, ...), plus the surface's `errors` and `before`.
+ * An MCP server, over HTTP or stdio: every native `McpServer.layerStdio` option except
+ * `protocols`, the server information, `instructions` and `extensions`, the actions `A` that
+ * are its tools, and the native features it serves beside them.
  */
-export interface Options<Errors extends ReadonlyArray<Codec> = [], R = never> extends Omit<Parameters<typeof McpServer.layerHttp>[0], "protocols">, SurfaceOptions<Errors, R> {}
-/** An MCP subprocess on standard I/O: every native `McpServer.layerStdio` option except `protocols`. */
-export interface StdioOptions<Errors extends ReadonlyArray<Codec> = [], R = never> extends Omit<Parameters<typeof McpServer.layerStdio>[0], "protocols">, SurfaceOptions<Errors, R> {}
-/** The native server supplies its own request context to every tool call. */
-type ToolRequestContext<App, RB> = Exclude<RequestContext<App, HiddenFromMcp> | RB, McpSchema.McpRequestContext>;
+export interface Options<E = never, R = never, A extends Any = Any> extends Omit<Parameters<typeof McpServer.layerStdio>[0], "protocols"> {
+  /**
+   * The actions that are tools, among the implementations' actions: `[GetUser, RenameUser]`.
+   * Each keeps its implementation's authorization and builder. Defaults to every action of them.
+   */
+  readonly actions?: ReadonlyArray<A> | undefined;
+  /**
+   * Native MCP features served beside the actions' tools, such as `McpServer.resource`,
+   * `McpServer.prompt` and `McpServer.toolkit` layers merged into one. They register on this
+   * server's registry; merged beside it instead, they register on another and are not served.
+   */
+  readonly features?: Layer.Layer<never, E, R> | undefined;
+}
+/**
+ * One Streamable HTTP MCP endpoint: `Options`, and every native `McpServer.layerHttp` option
+ * except `protocols`, `allowedOrigins` among them, with `path` defaulting to `/mcp`.
+ */
+export interface LayerHttpOptions<E = never, R = never, A extends Any = Any> extends Options<E, R, A>, Omit<Parameters<typeof McpServer.layerHttp>[0], "protocols" | "path"> {
+  /** The endpoint's route; defaults to `/mcp`. */
+  readonly path?: HttpRouter.PathInput;
+  readonly authentication?: Any$1;
+}
+/**
+ * The native server supplies its own request context to every tool call, and the registry
+ * it registers the tools on, the endpoint's own; over HTTP the router its own, such as the
+ * request.
+ */
+type ToolRequestContext<R> = Exclude<R, McpSchema.McpRequestContext | McpServer.McpServer>;
+type HttpToolRequestContext<R> = Exclude<ToolRequestContext<R>, HttpRouter.Provided>;
+/**
+ * What the native features owe, `R`, beside the registry, which the endpoint provides them,
+ * so one registering through `McpServer.registerResource` owes it no host.
+ */
+type Features<R> = Exclude<R, McpServer.McpServer>;
+/**
+ * Where `D`, the descriptor given, is inferred, so the provider owed is that descriptor's.
+ * Without one, tools `A` all public take none, even past a `D` given explicitly; protected
+ * ones state theirs in `RequiredAuthentication` alone, as an absent `authentication` and the
+ * one they require would intersect to `never`, reading as every option being wrong.
+ */
+type Inferring<D, A extends Any> = [D] extends [undefined] ? [Protected<A>] extends [never] ? {
+  readonly authentication?: undefined;
+} : unknown : {
+  readonly authentication?: D;
+};
 /**
  * Serve MCP tools over one Streamable HTTP endpoint, speaking MCP 2026-07-28 only.
  *
- * Middleware provided around this layer has the normal HTTP lifetime. Native
- * context capture applies: never provide request-identity tags at startup.
+ * Protected tools need the `authentication` descriptor their contracts name, and the
+ * provider `Authentication.layer` builds from it. On an endpoint of protected tools only,
+ * every request authenticates before it is decoded. On a mixed endpoint, anyone may discover
+ * the server, list its tools, cancel, and call a public tool; everything else authenticates
+ * first, so a protected tool's description is listed to anyone but run only for its caller.
+ * A call refused with `Unauthenticated`, or with `Forbidden` naming scopes, is answered with
+ * its HTTP status and challenge, 401 or 403, as MCP authorization requires; any other
+ * failure is a tool result. In a tool call, what middleware provides per request wins over
+ * what the endpoint was built with; native `features` read only what they were built with,
+ * never a request's. Never provide an identity at startup: a tool call takes its identity
+ * only from the request it authenticated.
  */
-export declare function layerHttp<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(apps: readonly [...Apps], options: Options<Errors, RB>): Layer.Layer<never, BuildError<Apps[number], HiddenFromMcp> | Cause.IllegalArgumentError, BuildContext<Apps[number], HiddenFromMcp> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", ToolRequestContext<Apps[number], RB>>>;
+export declare function layerHttp<const Apps extends Served, const O extends Selection<ActionOf<Member<Apps>>> = {}, E = never, R = never, const D extends Any$1 | undefined = undefined>(implementations: Apps, options: LayerHttpOptions<E, R, ActionOf<Member<Apps>>> & O & NoInfer<Known<O, LayerHttpOptions<E, R, Any>>> & NoInfer<Required<SelectedOf<O, Apps>>> & Matching<NoInfer<SelectedOf<O, Apps>>, NoInfer<D>> & Inferring<D, NoInfer<SelectedOf<O, Apps>>>): Layer.Layer<never, BuildError<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | Cause.IllegalArgumentError | E, BuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", HttpToolRequestContext<RemoteRequest<Member<Apps>, SelectedOf<O, Apps>>>> | ProviderOf<D> | Features<R>>;
 /**
  * Serve MCP tools through newline-delimited JSON-RPC on standard I/O, speaking MCP
- * 2026-07-28 only. An older host is refused deliberately, for uniformity with HTTP,
- * even though stdio has no sessions.
+ * 2026-07-28, 2025-11-25 or 2025-06-18, as the host negotiates: the whole
+ * program of an MCP subprocess, which succeeds once the host closes its side and the calls in
+ * flight, which that interrupts, have stopped. A signal interrupts it.
  *
- * The host supplies the `Stdio` service. Arguments are tool input only and
- * never establish request identity or authority.
+ * Effect logs go to stderr, since stdout carries the protocol. The host supplies the
+ * `Stdio` service and the identity. Arguments are tool input only and never establish
+ * request identity or authority; each implementation's `authorize` runs for its protected actions.
  */
-export declare function layerStdio<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(apps: readonly [...Apps], options: StdioOptions<Errors, RB>): Layer.Layer<never, BuildError<Apps[number], HiddenFromMcp> | Cause.IllegalArgumentError, BuildContext<Apps[number], HiddenFromMcp> | Stdio | ToolRequestContext<Apps[number], RB>>;
+export declare function runStdio<const Apps extends Served, const O extends Selection<ActionOf<Member<Apps>>> = {}, E = never, R = never>(implementations: Apps, options: Options<E, R, ActionOf<Member<Apps>>> & O & NoInfer<Known<O, Options<E, R, Any>>>): Effect.Effect<void, BuildError<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | Cause.IllegalArgumentError | E, BuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | Stdio.Stdio | ToolRequestContext<ServedRequest<Member<Apps>, SelectedOf<O, Apps>>> | Features<R>>;
 //#endregion