@gjermundgaraba/effect-actions 0.9.0 → 0.11.0

package/dist/Authentication.d.mts

@@ -1,46 +1,142 @@
-import { Context, Effect } from "effect";
+import { Refusal } from "./internal/errors.mjs";
+import { Known, OptionalUnless } from "./internal/implementation.mjs";
+import { Errors } from "./Action.mjs";
+import { Any, Descriptor, Provider, Security } from "./internal/authentication.mjs";
+import { ErrorsOf } from "./internal/declared.mjs";
+import { Array, Context, Effect, Layer, Option, Redacted, Scope } from "effect";
 import { HttpRouter, HttpServerResponse } from "effect/http";
-import { NonEmptyReadonlyArray } from "effect/Array";
+import { HttpApiSecurity } from "effect/http-api";
 //#region src/Authentication.d.ts
 /**
- * Authenticate each request and provide its identity to the downstream handler.
- * `authenticate` fails with the response to send instead, so the host owns its
- * status, body and challenge headers. Dependencies remain native router request
- * requirements. Acquired resources live until the request scope closes, including
- * while the handler is running. Every response is marked `Cache-Control: no-store`,
- * including private failures serialized by enclosing middleware.
+ * The bearer token of an `Authorization` header, `authorization`, or none, read as Effect's
+ * `HttpApiSecurity.bearer` reads it for routes and MCP, which a test holds equal. It is for a
+ * caller the router never routes, which holds the header and no request; a route of the host's
+ * own is authenticated by `protect`. The scheme is matched case-insensitively, as RFC 9110
+ * requires, and the token is `Redacted`, as Effect's own decoder gives it.
  */
-export declare const middleware: <I, A, R>(service: Context.Key<I, A>, authenticate: Effect.Effect<NoInfer<A>, HttpServerResponse.HttpServerResponse, R>) => HttpRouter.Middleware<{
-  provides: I;
-  handles: never;
-  error: never;
-  requires: Exclude<R, HttpRouter.Provided> | Exclude<Exclude<import("effect/Types").NoInfer<I>, I>, HttpRouter.Provided>;
-  layerError: never;
-  layerRequires: never;
-}>;
-/** RFC 9728 metadata to publish; the host is responsible for these being valid OAuth URLs. */
-export interface ProtectedResourceOptions {
+export declare const bearerTokenOf: (authorization: string | null | undefined) => Option.Option<Redacted.Redacted<string>>;
+/** An OAuth protected resource (RFC 9728), as `layer` publishes it. */
+export interface ProtectedResource {
   /** Exact OAuth resource identifier; its path and query select the discovery path. */
   readonly resource: string;
-  readonly authorizationServers: NonEmptyReadonlyArray<string>;
+  /** Where clients get tokens: nonempty. */
+  readonly authorizationServers: Array.NonEmptyReadonlyArray<string>;
+  /**
+   * Every scope the resource accepts, each an OAuth scope token, which a client requests when a
+   * 401 names none.
+   */
   readonly scopesSupported?: ReadonlyArray<string>;
+  /**
+   * The scopes every 401 names, each an OAuth scope token: what a client requests when it
+   * authenticates, rather than every scope supported. A `Forbidden` naming scopes asks for
+   * more when a call needs them.
+   */
+  readonly scopesRequired?: Array.NonEmptyReadonlyArray<string>;
   readonly resourceName?: string;
 }
-/** Parameters of one `WWW-Authenticate: Bearer` challenge, RFC 6750 §3. */
-export interface BearerChallengeOptions {
-  readonly error?: "invalid_token" | "insufficient_scope";
-  readonly errorDescription?: string;
-  /** Space-separated scopes needed for this request, not all supported scopes. */
-  readonly scope?: string;
+/** What `refusalResponse` answers about. */
+export interface RefusalResponseOptions<D extends Any = Any> {
+  /**
+   * The descriptor refusing, whose scheme decides the challenge: Bearer's, below, when left
+   * out; another scheme's 401 names that scheme, and nothing steps up under it. An error it
+   * declares is sent as its endpoints declare it.
+   */
+  readonly authentication?: D | undefined;
+  /** The OAuth protected resource refusing: the one given to `layer`. */
+  readonly protectedResource?: ProtectedResource | undefined;
+  /**
+   * The request's `Authorization` header, as the web `Headers.get` gives it, which decides whether a
+   * 401 names `invalid_token`.
+   */
+  readonly authorization?: string | null | undefined;
+}
+/** What the descriptor `D` declares its verifier fails with besides a refusal. */
+type DeclaredOf<D> = D extends {
+  readonly error: infer E extends Errors;
+} ? E[number]["Type"] : never;
+/**
+ * The response `layer` answers a refusal with, for a caller the router never routes, such as
+ * a Node `upgrade` handler admitting a socket: its status, its JSON, `Cache-Control: no-store`
+ * and its challenge, an `Unauthenticated`'s `Bearer`, naming `invalid_token` when
+ * `authorization` presented a bearer token, or the `insufficient_scope` of a `Forbidden`
+ * naming scopes. Given the protected resource `layer` was, every challenge names its metadata
+ * URL and a 401's its `scopesRequired`. Under a descriptor of another scheme, it is the JSON
+ * and status alone, a 401 naming that scheme. An error `authentication` declares is sent as
+ * its endpoints declare it, its JSON with its status. `HttpServerResponse.toWeb` gives it as a
+ * web `Response`.
+ */
+export declare const refusalResponse: <D extends Any = never>(error: Refusal | DeclaredOf<D>, options?: RefusalResponseOptions<D>) => HttpServerResponse.HttpServerResponse;
+/** What `make` takes besides the name and the identity. */
+export interface Options {
+  /** The one native scheme a caller proves the identity by: Bearer when left out. */
+  readonly security?: Security;
+  /**
+   * What the verifier may fail with besides a refusal, such as its provider being unreachable:
+   * one schema, or a list. Every protected endpoint declares it, so clients decode it.
+   */
+  readonly error?: Errors | Errors[number];
+}
+/** The scheme options `O` give: Bearer too wherever they may leave it out, as at run time. */
+type SecurityOf<O> = O extends {
+  readonly security: infer S extends Security;
+} ? S : "security" extends keyof O ? NonNullable<O["security" & keyof O]> | HttpApiSecurity.Http : HttpApiSecurity.Http;
+/**
+ * Browser-safe declaration shared by clients and remote surfaces: the `identity` it
+ * authenticates, by the one native scheme `security`, Bearer unless it names another, such
+ * as `HttpApiSecurity.apiKey({ in: "cookie", key: "session" })`. The literal name
+ * identifies the provider, like a native Context.Key name, and the scheme's OpenAPI key, so it
+ * holds only letters, digits, `_`, `.` and `-`; reuse one name only for one declaration.
+ */
+export declare const make: <const Name extends string, I, A, const O extends Options = {}>(name: Name, identity: Context.Key<I, A>, ...options: OptionalUnless<O, O & NoInfer<Known<O, Options>>>) => Descriptor<I, A, SecurityOf<O>, Name, ErrorsOf<O>>;
+/**
+ * A descriptor's verifier: the credential its scheme decodes, as Effect's own decoder gives
+ * it, to the identity, or a refusal, or an error the descriptor declares, `E`. Its services
+ * belong to the request.
+ */
+export type Verify<A, S extends Security, R, E = never> = (credential: HttpApiSecurity.HttpApiSecurity.Type<S>) => Effect.Effect<A, Refusal | E, R>;
+export interface LayerOptions<EP = never, RP = never> {
+  readonly protectedResource?: ProtectedResource | Effect.Effect<ProtectedResource | undefined, EP, RP>;
 }
 /**
- * Publish RFC 9728 discovery independently from the authenticated routes.
- * This supplies metadata and challenges; the host still verifies access tokens.
+ * Only a Bearer scheme publishes an OAuth protected resource. The types tell only an `Http`
+ * scheme from the others, as its scheme is a `string`: `layer` refuses another `Http` one.
  */
-export declare const protectedResource: (options: ProtectedResourceOptions) => {
-  layer: import("effect/Layer").Layer<never, never, HttpRouter.HttpRouter>;
-  metadataUrl: string;
-  /** The `WWW-Authenticate` value; parameter values are quoted and escaped. */
-  challenge: (challenge?: BearerChallengeOptions) => string;
+type ResourceOf<S> = [S] extends [HttpApiSecurity.Http] ? unknown : {
+  readonly protectedResource?: undefined;
 };
-//#endregion
+/**
+ * The provider of `authentication`: `verify`, or an Effect building it once per layer graph, run on
+ * each remote request a protected action receives, with the credential the descriptor's
+ * scheme decodes. A Bearer scheme answers each 401 with its challenge, and may publish the
+ * OAuth protected resource `protectedResource`.
+ */
+export declare function layer<const Name extends string, I, A, const S extends Security, E extends Errors, R, EX = never, RX = never, EP = never, RP = never>(authentication: Descriptor<I, A, S, Name, E>, verify: Verify<NoInfer<A>, NoInfer<S>, R, NoInfer<E[number]["Type"]>> | Effect.Effect<Verify<NoInfer<A>, NoInfer<S>, R, NoInfer<E[number]["Type"]>>, EX, RX>, options?: LayerOptions<EP, RP> & ResourceOf<S>): Layer.Layer<Provider<I, Name>, EX | EP, HttpRouter.HttpRouter | Exclude<RX | RP, Scope.Scope> | HttpRouter.Request.From<"Requires", Exclude<R, HttpRouter.Provided>>>;
+/** The identity `I`, or none where it is erased to `unknown`. */
+type Provides<I> = unknown extends I ? never : I;
+/**
+ * What `protect` returns for a descriptor named `Name` authenticating the identity `I`: router
+ * middleware providing it, answering a refusal its routes fail with, and requiring the
+ * descriptor's provider. Named so a package emitting declarations can export one.
+ */
+export type Protection<I, Name extends string> = HttpRouter.Middleware<{
+  provides: Provides<I>;
+  handles: Refusal;
+  error: never;
+  requires: never;
+  layerError: never;
+  layerRequires: Provider<I, Name>;
+}>;
+/**
+ * Native router middleware authenticating a route of the host's own, such as an export, a
+ * page frame or a WebSocket upgrade, with `authentication`'s provider, as its actions' routes
+ * are: the credential its scheme decodes, verified by the same verifier, and the identity
+ * provided to the route. It answers as an action route: a missing or invalid credential with
+ * the refusal, every response to the request it authenticates `no-store` unless it states its
+ * own caching, and a refusal the route fails with, such as a scope check's `Forbidden`, as its
+ * status, JSON and challenge, stepping up under Bearer. The layer requires the provider,
+ * `layer(authentication, ...)`. An erased descriptor, `Any`, provides no service the types can
+ * name: its identity is `unknown`, which would discharge every request service the route owes.
+ */
+export declare const protect: <I, A, S extends Security, Name extends string, E extends Errors>(authentication: Descriptor<I, A, S, Name, E>) => Protection<I, Name>;
+//#endregion
+export type { Any, Descriptor, Provider };

package/dist/Authentication.mjs

@@ -1,55 +1,248 @@
-import { Effect } from "effect";
+import { Unauthenticated, scopeToken } from "./internal/errors.mjs";
+import { assertOwnTags, errorList } from "./internal/actions.mjs";
+import { declaredResponse } from "./internal/declared.mjs";
+import { answer, answerStepUp, bearer, challenge, isRefusal, isStepUp, plain } from "./internal/refusal.mjs";
+import { Context, Effect, Layer, Match, Option, Predicate, Redacted } from "effect";
 import { HttpEffect, HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
+import { HttpApiBuilder, HttpApiMiddleware, HttpApiSecurity } from "effect/http-api";
 //#region src/Authentication.ts
 /**
-* Authenticate each request and provide its identity to the downstream handler.
-* `authenticate` fails with the response to send instead, so the host owns its
-* status, body and challenge headers. Dependencies remain native router request
-* requirements. Acquired resources live until the request scope closes, including
-* while the handler is running. Every response is marked `Cache-Control: no-store`,
-* including private failures serialized by enclosing middleware.
+* An `Authorization` header of the `Bearer` scheme, and its token, as Effect's own
+* `HttpApiSecurity.bearer` decodes a request's: the scheme, matched case-insensitively, one or
+* more spaces, then the rest of the header, whatever it holds, a tab included. The whitespace
+* around a header value is no part of it, and an HTTP parser strips it before any route reads it.
 */
-const middleware = (service, authenticate) => HttpRouter.middleware()((httpEffect) => authenticate.pipe(Effect.matchEffect({
-	onFailure: Effect.succeed,
-	onSuccess: (identity) => Effect.provideService(httpEffect, service, identity)
-}), HttpEffect.withPreResponseHandler((_request, response) => Effect.succeed(HttpServerResponse.setHeader(response, "cache-control", "no-store")))));
-const quoted = (value) => `"${value.replace(/["\\]/g, "\\$&")}"`;
+const bearerScheme = /^[ \t]*Bearer +(.*[^ \t])[ \t]*$/i;
 /**
-* Publish RFC 9728 discovery independently from the authenticated routes.
-* This supplies metadata and challenges; the host still verifies access tokens.
+* The bearer token of an `Authorization` header, `authorization`, or none, read as Effect's
+* `HttpApiSecurity.bearer` reads it for routes and MCP, which a test holds equal. It is for a
+* caller the router never routes, which holds the header and no request; a route of the host's
+* own is authenticated by `protect`. The scheme is matched case-insensitively, as RFC 9110
+* requires, and the token is `Redacted`, as Effect's own decoder gives it.
 */
-const protectedResource = (options) => {
+const bearerTokenOf = (authorization) => Option.map(Option.fromNullishOr(bearerScheme.exec(authorization ?? "")?.[1]), (token) => Redacted.make(token));
+/**
+* The RFC 9728 metadata URL of `options`: `/.well-known/oauth-protected-resource` followed
+* by the resource's path, where MCP clients look when a 401 names no metadata URL.
+*/
+const metadataUrl = (options) => {
 	const resource = new URL(options.resource);
-	const path = `/.well-known/oauth-protected-resource${resource.pathname === "/" ? "" : resource.pathname}`;
-	const discoveryUrl = new URL(resource);
-	discoveryUrl.pathname = path;
-	const metadataUrl = discoveryUrl.href;
-	const target = metadataUrl.slice(discoveryUrl.origin.length);
-	const response = HttpServerResponse.jsonUnsafe({
+	const url = new URL(resource);
+	url.pathname = `/.well-known/oauth-protected-resource${resource.pathname === "/" ? "" : resource.pathname}`;
+	return url;
+};
+/** What challenges about `options` name. */
+const namedOf = (options) => ({
+	scope: options?.scopesRequired?.join(" "),
+	metadataUrl: options === void 0 ? void 0 : metadataUrl(options).href
+});
+/** Whether a request whose `Authorization` header is `authorization` presented a bearer token. */
+const tokenPresented = (authorization) => Option.isSome(bearerTokenOf(authorization));
+/**
+* The challenge of a 401: `Bearer`, naming the scopes a client requests and the metadata URL
+* where it finds its authorization server. A request that presented a bearer token is told
+* it is invalid, RFC 6750's `invalid_token`, on which a client may refresh its token before
+* it signs in again; one that presented none names no error code.
+*/
+const challengeOf = (named, presented) => bearer([
+	["error", presented ? "invalid_token" : void 0],
+	["scope", named.scope],
+	["resource_metadata", named.metadataUrl]
+]);
+/**
+* Refuse a protected resource that cannot be published, as `layer` and `refusalResponse` both
+* do: one under a scheme other than Bearer (`oauth` false), a `scopesSupported` or
+* `scopesRequired` that is no list of OAuth scope tokens, as `Forbidden` refuses, and a
+* resource with a fragment, which no request URL carries, so its discovery would never answer
+* (RFC 9728). A resource an Effect builds is checked for its scheme alone, and for the rest
+* once built.
+*/
+const assertResource = (oauth, options) => {
+	if (options === void 0) return;
+	if (!oauth) throw new Error("A protected resource is published only for a Bearer scheme");
+	if (Effect.isEffect(options)) return;
+	for (const key of ["scopesSupported", "scopesRequired"]) {
+		const invalid = options[key]?.find((scope) => !scopeToken.test(scope));
+		if (invalid !== void 0) throw new Error(`Invalid scope in ${key}: "${invalid}"`);
+	}
+	if (new URL(options.resource).href.includes("#")) throw new Error(`A protected resource has no fragment: ${options.resource}`);
+};
+/**
+* `response` as the routes of the authentication answer: `no-store` unless it states its
+* own caching, and a 401 challenged with `challenge` unless it names its own.
+*/
+const settle = (response, challenge) => HttpServerResponse.setHeaders(response, {
+	...response.headers["cache-control"] === void 0 ? { "cache-control": "no-store" } : {},
+	...challenge !== void 0 && response.status === 401 && response.headers["www-authenticate"] === void 0 ? { "www-authenticate": challenge } : {}
+});
+/**
+* The response `layer` answers a refusal with, for a caller the router never routes, such as
+* a Node `upgrade` handler admitting a socket: its status, its JSON, `Cache-Control: no-store`
+* and its challenge, an `Unauthenticated`'s `Bearer`, naming `invalid_token` when
+* `authorization` presented a bearer token, or the `insufficient_scope` of a `Forbidden`
+* naming scopes. Given the protected resource `layer` was, every challenge names its metadata
+* URL and a 401's its `scopesRequired`. Under a descriptor of another scheme, it is the JSON
+* and status alone, a 401 naming that scheme. An error `authentication` declares is sent as
+* its endpoints declare it, its JSON with its status. `HttpServerResponse.toWeb` gives it as a
+* web `Response`.
+*/
+const refusalResponse = (error, options) => {
+	const authentication = options?.authentication;
+	const oauth = authentication === void 0 || isBearer(authentication.security);
+	assertResource(oauth, options?.protectedResource);
+	const named = namedOf(options?.protectedResource);
+	const challenge = authentication !== void 0 && !oauth ? schemeChallenge(authentication.security, authentication.name) : challengeOf(named, tokenPresented(options?.authorization));
+	if (!isRefusal(error)) {
+		const response = declaredResponse(authentication?.error ?? [], error);
+		if (response === void 0) throw new Error("Not a refusal, nor an error the authentication declares");
+		return settle(response, challenge);
+	}
+	return settle(oauth ? answer(error, named.metadataUrl) : plain(error), challenge);
+};
+/**
+* Whether a request URL may resolve to a discovery path, which every other request skips
+* parsing: the URL parser copies `.well-known` as it is, removing only a tab or a newline. Node
+* refuses a target holding those before routing; a platform passing one through still parses.
+*/
+const mayDiscover = /\.well-known|[\t\n\r]/;
+/**
+* RFC 9728 discovery of `options` at its metadata URL, as global router middleware: it
+* answers before routing, so no route middleware, authentication included, ever covers it.
+* The metadata is public to every origin, as a browser client needs it after a 401: it
+* carries `Access-Control-Allow-Origin: *`, and discovery answers its own CORS preflight.
+* Where the host's CORS middleware runs before it, that policy answers the preflight and
+* adds its headers to reads, which keep the `*` where it sets no origin.
+*/
+const discovery = (options) => {
+	const discoveryUrl = metadataUrl(options);
+	const target = discoveryUrl.href.slice(discoveryUrl.origin.length);
+	const metadata = HttpServerResponse.jsonUnsafe({
 		resource: options.resource,
 		authorization_servers: options.authorizationServers,
 		bearer_methods_supported: ["header"],
 		scopes_supported: options.scopesSupported,
 		resource_name: options.resourceName
+	}, { headers: { "access-control-allow-origin": "*" } });
+	/** The preflight of a cross-origin read, allowing the headers it asks for. */
+	const preflight = (request) => {
+		const requested = request.headers["access-control-request-headers"];
+		return HttpServerResponse.empty({
+			status: 204,
+			headers: {
+				"access-control-allow-origin": "*",
+				"access-control-allow-methods": "GET, HEAD, OPTIONS",
+				...requested === void 0 ? {} : {
+					"access-control-allow-headers": requested,
+					vary: "Access-Control-Request-Headers"
+				}
+			}
+		});
+	};
+	return (next) => Effect.flatMap(HttpServerRequest.HttpServerRequest, (request) => {
+		const targeted = mayDiscover.test(request.url) && URL.canParse(request.url, discoveryUrl.origin) && new URL(request.url, discoveryUrl.origin).href.slice(discoveryUrl.origin.length) === target;
+		if (targeted && (request.method === "GET" || request.method === "HEAD")) return Effect.succeed(metadata);
+		if (targeted && request.method === "OPTIONS") return Effect.succeed(preflight(request));
+		return next;
 	});
+};
+/**
+* What `layer` answers about the protected resource `options`, written once: its metadata
+* URL, each 401's challenge, to a request that presented a bearer token and to one that did
+* not, and its discovery, none without a resource.
+*/
+const answersOf = (options) => {
+	const named = namedOf(options);
 	return {
-		layer: HttpRouter.middleware((next) => Effect.gen(function* () {
-			const request = yield* HttpServerRequest.HttpServerRequest;
-			const url = new URL(request.url, resource.origin);
-			if ((request.method === "GET" || request.method === "HEAD") && url.href.slice(url.origin.length) === target) return response;
-			return yield* next;
-		}), { global: true }),
-		metadataUrl,
-		/** The `WWW-Authenticate` value; parameter values are quoted and escaped. */
-		challenge: (challenge = {}) => {
-			return `Bearer ${[
-				["resource_metadata", metadataUrl],
-				["error", challenge.error],
-				["error_description", challenge.errorDescription],
-				["scope", challenge.scope]
-			].flatMap(([name, value]) => value === void 0 ? [] : [`${name}=${quoted(value)}`]).join(", ")}`;
-		}
+		metadataUrl: named.metadataUrl,
+		invalid: challengeOf(named, true),
+		anonymous: challengeOf(named, false),
+		published: options === void 0 ? void 0 : discovery(options)
 	};
 };
+/** Whether `security` is the Bearer scheme, the one OAuth challenges and discovery name. */
+const isBearer = (security) => Predicate.isTagged(security, "Http") && security.scheme.toLowerCase() === "bearer";
+/** What an OpenAPI component key may hold, and so a descriptor's name, which is its key. */
+const componentKey = /^[\w.-]+$/;
+/**
+* The challenge of a 401 under a scheme other than Bearer: the scheme an `Http` one names,
+* Basic with its realm, the descriptor's name; an API key has no scheme to name.
+*/
+const schemeChallenge = (security, name) => Match.value(security).pipe(Match.tag("Http", ({ scheme }) => challenge(scheme, [])), Match.tag("Basic", () => challenge("Basic", [["realm", name]])), Match.tag("ApiKey", () => void 0), Match.exhaustive);
+/**
+* Browser-safe declaration shared by clients and remote surfaces: the `identity` it
+* authenticates, by the one native scheme `security`, Bearer unless it names another, such
+* as `HttpApiSecurity.apiKey({ in: "cookie", key: "session" })`. The literal name
+* identifies the provider, like a native Context.Key name, and the scheme's OpenAPI key, so it
+* holds only letters, digits, `_`, `.` and `-`; reuse one name only for one declaration.
+*/
+const make = (name, identity, ...options) => {
+	const security = options[0]?.security ?? HttpApiSecurity.bearer;
+	const error = errorList(options[0]?.error);
+	if (!componentKey.test(name)) throw new Error(`Invalid authentication name: ${JSON.stringify(name)}, not an OpenAPI key`);
+	assertOwnTags(`Authentication "${name}"`, error);
+	if (!Predicate.isTagged(security, "Http") && !Predicate.isTagged(security, "ApiKey") && !Predicate.isTagged(security, "Basic")) throw new Error("Authentication takes one native HttpApiSecurity scheme");
+	return {
+		name,
+		identity,
+		security,
+		error,
+		"~provider": Context.Service(`effect-actions/Authentication/Provider/${name}`),
+		"~middleware": HttpApiMiddleware.Service()(`effect-actions/Authentication/Security/${name}`, { security: { [name]: security } }),
+		"~verified": Context.Service(`effect-actions/Authentication/Verified/${name}`)
+	};
+};
+/** Whether `credential`, as a native scheme decodes it, holds anything: an absent one is empty. */
+const presented = (credential) => Redacted.isRedacted(credential) ? Redacted.value(credential) !== "" : credential.username !== "" || Redacted.value(credential.password) !== "";
+function layer(authentication, verify, options = {}) {
+	const { security } = authentication;
+	const oauth = isBearer(security);
+	const protectedResource = options.protectedResource;
+	assertResource(oauth, protectedResource);
+	const resource = Effect.isEffect(protectedResource) ? Effect.map(protectedResource, (built) => {
+		assertResource(oauth, built);
+		return answersOf(built);
+	}) : Effect.succeed(answersOf(protectedResource));
+	const missing = new Unauthenticated({ message: oauth ? "A bearer token is required." : "A credential is required." });
+	return Layer.effect(authentication["~provider"], Effect.gen(function* () {
+		const router = yield* HttpRouter.HttpRouter;
+		const { metadataUrl, invalid, anonymous, published } = yield* resource;
+		if (published !== void 0) yield* router.addGlobalMiddleware(published);
+		const verifier = Effect.isEffect(verify) ? yield* verify : verify;
+		if (!Predicate.isFunction(verifier)) return yield* Effect.die(/* @__PURE__ */ new Error("Missing verify: pass a verify function, or an Effect building one"));
+		const authenticate = (credential) => presented(credential) ? verifier(credential) : Effect.fail(missing);
+		const failed = HttpEffect.appendPreResponseHandler((_request, response) => Effect.succeed(HttpServerResponse.setHeader(response, "cache-control", "no-store")));
+		const challengeOf = (credential) => !oauth ? schemeChallenge(security, authentication.name) : presented(credential) ? invalid : anonymous;
+		const refuse = (error) => isRefusal(error) ? Effect.succeed(oauth ? answer(error, metadataUrl) : plain(error)) : Effect.suspend(() => {
+			const response = declaredResponse(authentication.error, error);
+			return response === void 0 ? Effect.die(error) : Effect.succeed(response);
+		});
+		const verified = (credential, route, slot) => {
+			const challenge = challengeOf(credential);
+			return Effect.matchEffect(authenticate(credential), {
+				onFailure: refuse,
+				onSuccess: (actor) => Effect.provideService(route, slot, actor)
+			}).pipe(Effect.onError(() => failed), HttpEffect.withPreResponseHandler((_request, response) => Effect.succeed(settle(response, challenge))));
+		};
+		return {
+			descriptor: authentication,
+			middleware: { [authentication.name]: (route, { credential }) => verified(credential, route, authentication.identity) },
+			stepUp: (route) => oauth ? Effect.catchIf(route, isStepUp, (error) => Effect.succeed(answer(error, metadataUrl))) : route,
+			http: ((route, optional) => Effect.flatMap(HttpApiBuilder.securityDecode(security), (credential) => optional && !presented(credential) ? route : verified(credential, oauth ? answerStepUp(route, metadataUrl) : route, authentication["~verified"]))),
+			route: ((route) => Effect.flatMap(HttpApiBuilder.securityDecode(security), (credential) => verified(credential, Effect.catchIf(route, isRefusal, refuse), authentication.identity)))
+		};
+	}));
+}
+/**
+* Native router middleware authenticating a route of the host's own, such as an export, a
+* page frame or a WebSocket upgrade, with `authentication`'s provider, as its actions' routes
+* are: the credential its scheme decodes, verified by the same verifier, and the identity
+* provided to the route. It answers as an action route: a missing or invalid credential with
+* the refusal, every response to the request it authenticates `no-store` unless it states its
+* own caching, and a refusal the route fails with, such as a scope check's `Forbidden`, as its
+* status, JSON and challenge, stepping up under Bearer. The layer requires the provider,
+* `layer(authentication, ...)`. An erased descriptor, `Any`, provides no service the types can
+* name: its identity is `unknown`, which would discharge every request service the route owes.
+*/
+const protect = (authentication) => HttpRouter.middleware()(Effect.map(Effect.service(authentication["~provider"]), (runtime) => (route) => runtime.route(route)));
 //#endregion
-export { middleware, protectedResource };
+export { bearerTokenOf, layer, make, protect, refusalResponse };

package/dist/Testing.d.mts

@@ -1,68 +1,95 @@
-import { ClientOptions } from "./internal/fetchClient.mjs";
-import { Schema } from "effect";
-import { HttpApi, HttpApiGroup } from "effect/http-api";
+import { BuiltIn } from "./internal/errors.mjs";
+import { Call } from "./internal/call.mjs";
+import { Action_d_exports, Any } from "./Action.mjs";
+import { Params } from "./internal/mcp.mjs";
+import { Served } from "./internal/memory.mjs";
+import { Effect, Layer, Schema } from "effect";
+import { Headers, HttpClient, HttpClientError, HttpClientRequest, HttpRouter } from "effect/http";
 //#region src/Testing.d.ts
-/** A web handler, such as `HttpRouter.toWebHandler(routes).handler`. */
-export type Handler = (request: Request) => Promise<Response>;
 /**
- * The native grouped HTTP client, calling `handler` in memory instead of the network.
- * `baseUrl` defaults to `http://localhost`.
+ * The native `HttpClient`, answered by `handler` instead of the network: a web handler the
+ * test serves, which other tests may share, such as
+ * `HttpRouter.toWebHandler(routes.pipe(Layer.provide(HttpServer.layerServices))).handler`,
+ * the routes' platform services provided, as `layer(routes)` provides them itself. It is the
+ * client `layer(routes)` gives, without building anything: the test owns the handler, and
+ * disposes of it.
  */
-export declare const httpClient: <Id extends string, Groups extends HttpApiGroup.Constraint>(api: HttpApi.HttpApi<Id, Groups>, handler: Handler, options?: ClientOptions) => import("effect/Effect").Effect<import("effect/Types").Simplify<{ readonly [Group in Extract<Groups, {
-  readonly topLevel: false;
-}> as HttpApiGroup.Identifier<Group>]: import("effect/http-api/HttpApiClient").Client.GroupByEndpoint<Group, never, never>; } & import("effect/http-api/HttpApiClient").Client.TopLevelMethods<Groups, never, never>>, never, Exclude<Exclude<import("effect/http-api/HttpApiMiddleware").MiddlewareClient<import("effect/http-api/HttpApiEndpoint").Middleware<HttpApiGroup.Endpoints<Groups>>>, import("effect/http/HttpClient").HttpClient>, never>>;
-/** A stateless 2026-07-28 request. */
-export interface McpRequestOptions {
-  readonly url: string | URL;
-  readonly method: string;
-  readonly params?: McpRequestParams;
-  readonly headers?: ConstructorParameters<typeof Headers>[0];
-}
+export declare function layer(handler: (request: Request) => Promise<Response>): Layer.Layer<HttpClient.HttpClient>;
 /**
- * What `JSON.stringify` accepts, not only valid JSON: `undefined` fields are
- * dropped, and tests send malformed arguments on purpose.
+ * The native `HttpClient`, answered in memory by `routes` instead of the network: provide
+ * it to `ActionHttp.client` and to `mcpClient`. The routes are built with this layer and
+ * released with its scope, without request logs. What they still require is this layer's, as
+ * under `HttpRouter.serve`: a builder's services, and a per-request service no middleware of
+ * theirs provides, including one a global middleware reads. The routes keep their real
+ * authentication: a client sends its caller's credential. Provided around it, the test
+ * program shares them. It never requires
+ * the platform services, `FileSystem`, `Path`, `HttpPlatform` and `Etag.Generator`: one
+ * provided around it is the routes' too, and `HttpServer.layerServices`' defaults stand in for
+ * the rest, whose `FileSystem` is a no-op. A relative URL resolves against `http://localhost`.
+ * The client is the layer's own: the program's other HTTP clients get none of its requests,
+ * and it none of theirs.
  */
-export type McpRequestValue = string | number | boolean | null | undefined | ReadonlyArray<McpRequestValue> | {
-  readonly [key: string]: McpRequestValue;
-};
-/** JSON-RPC `params`; `_meta` is merged shallowly over the defaults `mcpRequest` supplies. */
-export interface McpRequestParams {
-  readonly _meta?: {
-    readonly [key: string]: McpRequestValue;
-  };
-  readonly [key: string]: McpRequestValue;
+export declare function layer<A, E, R>(routes: Layer.Layer<A, E, R>): Layer.Layer<HttpClient.HttpClient, E, Exclude<HttpRouter.Request.Without<R> | HttpRouter.Request.Only<"Requires", R> | HttpRouter.Request.Only<"GlobalRequires", R>, Served>>;
+/** Where `mcpClient` sends, and through what client. */
+export interface McpClientOptions {
+  /**
+   * The endpoint, resolved by the `HttpClient`: relative under `layer`. Defaults to `/mcp`,
+   * the default `ActionMcp.layerHttp` path.
+   */
+  readonly url?: string;
+  /** Wraps the native `HttpClient`, as `ActionHttp.client` takes it: a bearer token, say. */
+  readonly transformClient?: (client: HttpClient.HttpClient) => HttpClient.HttpClient;
 }
-/** Build one stateless 2026-07-28 JSON-RPC request, with client metadata defaulted. */
-export declare const mcpRequest: ({ url, method, params, headers: init }: McpRequestOptions) => Request;
-/** One `tools/call` for `mcpCall`: the endpoint, the tool and its arguments. */
-export interface McpCallOptions {
-  readonly url: string | URL;
-  /** The tool name, `mcp.name` of its action. */
-  readonly name: string;
-  /** Defaults to `{}`. Like `params`, it may be malformed on purpose. */
-  readonly arguments?: {
-    readonly [key: string]: McpRequestValue;
-  };
-  readonly headers?: ConstructorParameters<typeof Headers>[0];
+/** Where an `mcpRequest` goes, and with what headers. */
+export interface McpRequestOptions {
+  /**
+   * The endpoint, resolved by the `HttpClient` that sends the request: relative under `layer`.
+   * Defaults to `/mcp`, as `mcpClient`'s does; converting to a web `Request` needs an absolute
+   * one.
+   */
+  readonly url?: string;
+  readonly headers?: Headers.Input;
 }
+declare const McpCallError_base: Schema.Class<McpCallError, Schema.TaggedStruct<"McpCallError", {
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * An answer a client method cannot decode as the action's success or a declared error,
+ * such as the native server's message for invalid arguments or an unknown tool. Its message
+ * holds the answer.
+ */
+export declare class McpCallError extends McpCallError_base {}
+/**
+ * What one call of `A` fails with: a declared error value (the action's own or a built-in one
+ * from the tool, or a refusal from the endpoint's authentication), a `SchemaError` when the
+ * input does not encode or the success does not decode, an `HttpClientError` when the
+ * endpoint could not be reached, or an `McpCallError` for any other answer.
+ */
+type CallError<A extends Any> = A["error"][number]["Type"] | BuiltIn | Schema.SchemaError | HttpClientError.HttpClientError | McpCallError;
+/** Every action of `Actions` as `client.<action>(input)`, calling its tool. */
+export type McpClient<Actions extends ReadonlyArray<Any>> = { readonly [A in Actions[number] as A["name"]]: Call<A, Effect.Effect<A["success"]["Type"], CallError<A>>>; };
 /**
- * A tool call's outcome: the success from `structuredContent`, with the text an action's
- * `mcp.text` field sent before it; or the error text of an `isError` result, parsed as
- * JSON when it is JSON (a declared error, whatever its shape) and kept as the text
- * otherwise (the native server's own message, such as for invalid arguments).
+ * A client of an MCP endpoint served by `ActionMcp.layerHttp`, one method per action calling
+ * its tool with one stateless request, as `ActionHttp.client` calls routes: the input is
+ * encoded with the action's schema, and the success decoded from its structured content, each
+ * media field from the blocks whose `_meta` names it, and a success that is media, or whose
+ * every field is, from its blocks alone. A declared error the tool returns, the action's own
+ * or a refusal, is its decoded value, and so is a refusal the endpoint's authentication
+ * answers with. The argument may be omitted when `{}` is a valid input. Requires the native
+ * `HttpClient`, such as the one `layer` provides.
  */
-export type McpCallResult = {
-  readonly isError: false;
-  readonly value: Schema.Json;
-  readonly text?: string;
-} | {
-  readonly isError: true;
-  readonly error: Schema.Json;
-};
+export declare function mcpClient<const Actions extends ReadonlyArray<Any>>(actions: Actions, options?: McpClientOptions): Effect.Effect<McpClient<Actions>, never, HttpClient.HttpClient>;
 /**
- * Call one tool through `handler` with a stateless 2026-07-28 request and return its
- * outcome. A response that is not an HTTP 200 carrying a tool result, such as an
- * authentication refusal or a JSON-RPC error, throws; use `mcpRequest` to inspect one.
+ * One stateless MCP request of `method` with `params`, as `ActionMcp.layerHttp` serves it,
+ * as the native request value: the JSON-RPC envelope, the 2026-07-28 headers, `mcp-name` from
+ * `params.uri` for `resources/read` and `params.name` otherwise, and the client metadata in
+ * `_meta` are filled in, under any `_meta` given, such as a `progressToken`; the protocol
+ * version is always the request's own. The test sends it: `HttpClient.execute` answers the
+ * response as the endpoint sent it, whatever its status, and `HttpClientRequest.toWebResult`
+ * gives the web `Request` a web handler or `fetch` takes, once `url` is absolute. It is for a test
+ * asserting on what `mcpClient` decodes away, such as `tools/list`, a refusal's challenge, or
+ * a call its types would not send.
  */
-export declare const mcpCall: (handler: Handler, { url, name, headers, arguments: args }: McpCallOptions) => Promise<McpCallResult>;
-//#endregion
+export declare const mcpRequest: (method: string, params?: Params, { headers, url }?: McpRequestOptions) => HttpClientRequest.HttpClientRequest;
+//#endregion
+export type { Params as McpParams };