@gjermundgaraba/effect-actions 0.8.0 → 0.10.0

package/dist/ActionMcp.mjs

@@ -1,98 +1,125 @@
-import "./internal/implementation.mjs";
-import { TextField, bindTools } from "./internal/tools.mjs";
-import { Context, Effect, Layer, Option, Predicate, Schema } from "effect";
-import { McpProtocol, McpSchema, McpServer } from "effect/ai";
+import { Anyone } from "./internal/actions.mjs";
+import { provideHandlers, select, toList } from "./internal/implementation.mjs";
+import { assertAuthentication, promote } from "./internal/authentication.mjs";
+import { httpProtocol } from "./internal/mcp.mjs";
+import { recordStepUp } from "./internal/refusal.mjs";
+import { logToStderr } from "./internal/console.mjs";
+import { bindTools } from "./internal/tools.mjs";
+import { Cause, Context, Effect, Exit, Fiber, JsonPointer, Layer, Predicate, Schema } from "effect";
+import { HttpRouter, HttpServerRequest } from "effect/http";
+import { McpProtocol, McpSchema, McpServer, Tool } from "effect/ai";
 //#region src/ActionMcp.ts
 /**
-* The one protocol revision served. 2026-07-28 is stateless over HTTP: no
-* initialize handshake and no session, so every request stands alone.
+* The revisions served over stdio: 2026-07-28 and the stateful revisions hosts open stdio
+* with, newest first; a host asking for another is offered 2025-11-25. A success is sent as it
+* is on each. 2026-07-28 carries any success as `structuredContent`; the adapters of 2025-11-25
+* and 2025-06-18 carry only an object there, and list only an object-rooted `outputSchema`. A
+* success they do not structure is text alone, a string as itself.
 */
-const protocols = [McpProtocol.v2026_07_28];
-/** The parts of a listed output schema a text field is removed from. */
-const decodeOutput = Schema.decodeUnknownOption(Schema.Struct({
-	properties: Schema.Record(Schema.String, Schema.Json),
-	required: Schema.optionalKey(Schema.Array(Schema.String))
-}));
-/** A JSON value that is an object: neither null, a scalar nor an array. */
-const isJsonObject = (value) => Predicate.isObject(value);
-/** Split a JSON object into one field and the rest. */
-const detach = (value, field) => {
-	const { [field]: detached, ...rest } = value;
-	return {
-		detached,
-		rest
-	};
+const stdioProtocols = [
+	McpProtocol.v2026_07_28,
+	McpProtocol.v2025_11_25,
+	McpProtocol.v2025_06_18
+];
+/**
+* MCP has a JSON-only wire contract. Success is the encoded success as structured content,
+* and its JSON as text; declared failures are returned as JSON text. The native server
+* refuses undeclared arguments and publishes closed input schemas.
+*/
+const projection = {
+	label: "MCP tool",
+	tool: (tool) => tool.annotate(Tool.Strict, true)
 };
+/** Whether a JSON Schema is one the native server takes for a tool's arguments. */
+const isToolJson = Schema.is(McpSchema.ToolJson);
 /**
-* The listed output schema without the text field. Only a top-level property can be
-* detached; anything else fails the layer build rather than publish a schema the
-* structured content would not satisfy.
+* The JSON Schema root of `schema` as the native server lists it for a tool, a `$ref` at its
+* root resolved.
 */
-const outputWithout = (tool, field) => {
-	const { properties: _, required: __, ...output } = tool.outputSchema ?? {};
-	const listed = Option.getOrUndefined(decodeOutput(tool.outputSchema));
-	if (listed === void 0 || !Object.hasOwn(listed.properties, field)) return Effect.die(`MCP tool '${tool.name}' cannot send '${field}' as text: it is not a top-level property of its success`);
-	const required = (listed.required ?? []).filter((key) => key !== field);
-	return Effect.succeed({
-		...output,
-		properties: detach(listed.properties, field).rest,
-		...required.length === 0 ? {} : { required }
-	});
+const rootOf = (schema) => {
+	const document = Schema.toJsonSchemaDocument(Schema.toCodecJson(schema));
+	const [scope, key] = Predicate.isString(document.schema.$ref) ? JsonPointer.parseUriFragment(document.schema.$ref) ?? [] : [];
+	return scope === "$defs" && key !== void 0 ? document.definitions[key] : document.schema;
 };
 /**
-* A successful result with a string text field sent once, raw, before the structured
-* rest and its JSON copy. Any other result, such as a failure or a success without
-* the field, is the native one.
+* Refuse, when the server is made, the actions of `apps` whose input is not one object, as the
+* root of a tool's arguments must be, naming every one, reading the JSON Schema the native
+* server reads: not a union, an array, a scalar, nor `Schema.Struct({})`, which takes any value
+* but `null`, where the native server dies when the layer builds, suggesting
+* `Tool.EmptyParams`.
 */
-const textResult = (result, field) => {
-	const structured = result.structuredContent;
-	if (result.isError === true || !isJsonObject(structured)) return result;
-	const { detached, rest } = detach(structured, field);
-	if (!Predicate.isString(detached)) return result;
-	return new McpSchema.CallToolResult({
-		...result,
-		structuredContent: rest,
-		content: [{
-			type: "text",
-			text: detached
-		}, {
-			type: "text",
-			text: JSON.stringify(rest)
-		}]
+const assertShapes = (apps) => {
+	const inputs = apps.flatMap((app) => app.actions).filter((action) => !isToolJson(rootOf(action.input))).map(({ name }) => name);
+	if (inputs.length > 0) throw new Error(`MCP tool input must be one object with keys, such as a struct: ${inputs.join(", ")}`);
+};
+const server = (apps, transport, features = Layer.empty, authentication) => {
+	const binding = bindTools(apps, authentication === void 0 ? projection : {
+		...projection,
+		handler: (run, action) => (input) => action.caller === Anyone ? run(input) : recordStepUp(promote(authentication, run(input)))
+	});
+	assertShapes(apps);
+	const names = new Set(apps.flatMap((app) => app.actions.map(({ name }) => name)));
+	const register = Effect.gen(function* () {
+		const registry = yield* McpServer.McpServer;
+		const claimed = registry.tools.flatMap(({ tool }) => names.has(tool.name) ? [tool.name] : []);
+		if (claimed.length > 0) return yield* Effect.die(/* @__PURE__ */ new Error(`Duplicate MCP tool: ${claimed.join(", ")}, claimed by an action and a native feature`));
+		const handlers = yield* Layer.build(binding.layer);
+		yield* McpServer.registerToolkit(binding.toolkit).pipe(Effect.setContext(Context.add(handlers, McpServer.McpServer, registry)));
 	});
+	return Layer.effectDiscard(register).pipe(Layer.provide(features), Layer.provide(transport), Layer.fresh, provideHandlers(apps));
 };
-/** A native registration whose success sends `field` as text. */
-const withText = (registration, field) => Effect.map(outputWithout(registration.tool, field), (outputSchema) => ({
-	...registration,
-	tool: new McpSchema.Tool({
-		...registration.tool,
-		outputSchema
-	}),
-	handle: (payload) => Effect.map(registration.handle(payload), (result) => Predicate.isTagged(result, "InputRequired") ? result : textResult(result, field))
-}));
-const registration = (apps, options) => {
-	const binding = bindTools(apps, "mcp", options);
-	const registered = McpServer.registerToolkit(binding.toolkit).pipe(Effect.updateService(McpServer.McpServer, (server) => ({
-		...server,
-		addTool: (tool) => {
-			const field = Context.get(tool.annotations, TextField);
-			return field === void 0 ? server.addTool(tool) : Effect.flatMap(withText(tool, field), server.addTool);
-		}
-	})));
-	return Layer.effectDiscard(registered).pipe(Layer.provide(binding.layer));
+/**
+* What an anonymous caller of a mixed endpoint may send besides a public tool's call:
+* discovering the server and its tools, which the contracts describe, and cancelling.
+* Everything else, a native feature's listing, completion or subscription among them, and
+* any method a later revision adds, authenticates.
+*/
+const anonymous = /* @__PURE__ */ new Set([
+	"server/discover",
+	"tools/list",
+	"notifications/cancelled"
+]);
+/**
+* Whether a request to an endpoint serving `actions` must authenticate before the native
+* server reads its body. An endpoint whose every tool is protected authenticates every
+* request, so a host signs in when it connects. Otherwise the request's routing headers
+* decide, which the native server refuses when they disagree with the body: discovery and a
+* call of a public tool authenticate only a caller presenting credentials, and everything
+* else authenticates, so native features are protected too. A request whose headers name
+* no public tool as it is authenticates: it fails closed.
+*/
+const requiresAuthentication = (actions) => {
+	const open = new Set(actions.filter(({ caller }) => caller === Anyone).map(({ name }) => name));
+	return (headers) => {
+		if (open.size === 0) return true;
+		const method = headers["mcp-method"];
+		if (method === void 0) return true;
+		if (anonymous.has(method)) return false;
+		if (method !== "tools/call") return true;
+		const name = headers["mcp-name"];
+		return name === void 0 || !open.has(name);
+	};
 };
-const server = (apps, options, transport) => registration(apps, options).pipe(Layer.provide(transport), Layer.fresh);
-function layerHttp(apps, options) {
-	return server(apps, options, McpServer.layerHttp({
+function layerHttp(apps, { actions, features, path, authentication, ...options }) {
+	const selected = select(toList(apps), actions);
+	const served = selected.flatMap((app) => app.actions);
+	assertAuthentication(served, authentication);
+	const transport = server(selected, McpServer.layerHttp({
 		...options,
-		protocols
-	}));
+		path: path ?? "/mcp",
+		protocols: [httpProtocol]
+	}), features, authentication);
+	if (authentication === void 0) return transport;
+	const required = requiresAuthentication(served);
+	const middleware = HttpRouter.middleware(Effect.map(authentication["~provider"], (runtime) => (route) => Effect.flatMap(HttpServerRequest.HttpServerRequest, (request) => runtime.http(route, !required(request.headers)))));
+	return transport.pipe(Layer.provide(middleware.layer));
 }
-function layerStdio(apps, options) {
-	return server(apps, options, McpServer.layerStdio({
+function runStdio(apps, { actions, features, ...options }) {
+	const transport = server(select(toList(apps), actions), McpServer.layerStdio({
 		...options,
-		protocols
-	}));
+		protocols: stdioProtocols
+	}), features);
+	return Layer.launch(transport).pipe(logToStderr, Effect.forkChild, Effect.flatMap(Fiber.await), Effect.flatMap((exit) => Exit.isFailure(exit) && !Cause.hasInterruptsOnly(exit.cause) ? Effect.failCause(exit.cause) : Effect.void));
 }
 //#endregion
-export { layerHttp, layerStdio };
+export { layerHttp, runStdio };

package/dist/ActionToolkit.d.mts

@@ -1,40 +1,69 @@
-import { Action_d_exports, Any, Codec } from "./Action.mjs";
-import { AnyImplementation, BuildContext, BuildError, HandlerContext, HiddenFromMcp, Implementation } from "./internal/implementation.mjs";
-import { SurfaceOptions } from "./internal/tools.mjs";
-import { Layer, Schema } from "effect";
+import { BuiltIns } from "./internal/errors.mjs";
+import { ActionOf, BuildError, BuildServices, Holding, Known, Member, Offered, OptionalUnless, RequestOf, SelectedOf, Served, Serving } from "./internal/implementation.mjs";
+import { Action_d_exports, Any } from "./Action.mjs";
+import { Effect, Layer, Schema } from "effect";
 import { Tool, Toolkit } from "effect/ai";
 //#region src/ActionToolkit.d.ts
-/** What the in-process caller binds around the implementations it projects. */
-export type Options<Errors extends ReadonlyArray<Codec> = [], R = never> = SurfaceOptions<Errors, R>;
-/** A native tool corresponding to an action MCP may serve, named by its tool metadata. */
-type NativeTool<A extends Any, E extends Codec, R> = Extract<A["mcp"], object> extends {
-  readonly name: infer Name extends string;
-} ? Tool.Tool<Name, {
-  readonly parameters: A["input"];
-  readonly success: A["success"];
-  readonly failure: Schema.Union<ReadonlyArray<A["errors"][number] | E>>;
+/** A native tool named after its action, taking and giving JSON. */
+type NativeTool<A extends Any, R> = Tool.Tool<A["name"], {
+  readonly parameters: Schema.toCodecJson<A["input"]>;
+  readonly success: Schema.toCodecJson<A["success"]>;
+  readonly failure: Schema.toCodecJson<Schema.Union<ReadonlyArray<A["error"][number] | BuiltIns>>>;
   readonly failureMode: "return";
-}, R> : never;
-type HandlersOf<App extends AnyImplementation> = App extends Implementation<any, infer H, any, any> ? H : never;
+}, R>;
 /**
- * A tool needs what its handler needs, plus what the binding's `before` hook needs. The
- * rule is `ActionMcp`'s: only an action certainly hidden from MCP has no tool.
+ * The tool of each action of `App` among `Listed`. A tool needs what its handler and its
+ * implementation's authorization need.
  */
-type ToolForAction<App extends AnyImplementation, A extends Any, E extends Codec, RB> = A extends HiddenFromMcp ? never : NativeTool<A, E, HandlerContext<HandlersOf<App>, Extract<A["name"], keyof HandlersOf<App>>> | RB>;
-type ToolsFor<App extends AnyImplementation, E extends Codec, RB> = App extends AnyImplementation ? ToolForAction<App, App["group"]["actions"][number], E, RB> : never;
-type ToolkitTools<Apps extends ReadonlyArray<AnyImplementation>, E extends Codec, RB> = { readonly [T in ToolsFor<Apps[number], E, RB> as T["name"]]: T; };
-/** Native tools and the layer that binds their action implementations. */
-export interface Binding<Tools extends Record<string, Tool.Any>, E = never, R = never> {
-  readonly toolkit: Toolkit.Toolkit<Tools>;
+type ToolFor<App, Listed extends Any> = App extends unknown ? Serving<App, Listed> extends (infer A extends Any) ? A extends Any ? NativeTool<A, RequestOf<App, A>> : never : never : never;
+/**
+ * Native tools bound to their action implementations: a native `Toolkit` and the layer of
+ * its handlers, for `LanguageModel`, `Toolkit.merge` or `handle`. Tools belong to their
+ * implementations: the `layer` of a `make` call serves the tools it selected in any `toolkit`
+ * of the same implementations, while two implementations never run each other's handlers,
+ * even with tools of one name.
+ */
+export interface Tools<T extends Record<string, Tool.Any>, E, R> {
+  /**
+   * The native toolkit: its `tools` are the definitions, by name, with schemas, hints and approval.
+   */
+  readonly toolkit: Toolkit.Toolkit<T>;
   /** Acquires handlers once in the layer scope; handler requirements remain at invocation. */
-  readonly layer: Layer.Layer<Tool.HandlersFor<Tools>, E, R>;
+  readonly layer: Layer.Layer<Tool.HandlersFor<T>, E, R>;
+}
+/**
+ * One call of a tool, as `needsApproval` receives it: its action's name, the action, and
+ * the call's decoded input. Checking `name` narrows the other two to that action's.
+ */
+export type ToolCall<A extends Any = Any> = A extends Any ? {
+  readonly name: A["name"];
+  readonly action: A;
+  readonly input: A["input"]["Type"];
+} : never;
+/** How `make` projects its tools, the actions `A`. */
+export interface Options<A extends Any> {
+  /**
+   * 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;
+  /**
+   * Whether a model's call needs approval before it runs: a boolean, or an Effect of one, for
+   * each call, with Effect's native approval context. `LanguageModel` asks for approval
+   * instead of calling the tool when it is `true`. The Effect runs in the caller's context and
+   * requires nothing, so it reads the caller with `Effect.serviceOption`. Defaults to none.
+   */
+  readonly needsApproval?: (call: ToolCall<A>, context: Tool.NeedsApprovalContext) => boolean | Effect.Effect<boolean>;
 }
 /**
- * Project implementations into Effect's native AI toolkit.
+ * Project implementations into Effect's native AI toolkit: one tool per action, keyed by its
+ * name, of the listed `actions` or, without them, of every action of the implementations.
  *
  * Unlike MCP, calls return the action's native success/failure values directly.
  * Build services are needed to construct `layer`; request services are needed
- * when the resulting toolkit handles a call.
+ * when the resulting toolkit handles a call, the identity an implementation's `authorize`
+ * reads included: the caller provides it. `needsApproval` marks the calls a model must have
+ * approved; it authorizes nothing, which stays `authorize`'s.
  */
-export declare function make<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(apps: readonly [...Apps], options?: Options<Errors, RB>): Binding<ToolkitTools<Apps, Errors[number], RB>, BuildError<Apps[number], HiddenFromMcp>, BuildContext<Apps[number], HiddenFromMcp>>;
+export declare function make<const Apps extends Served, const O extends Options<ActionOf<Member<Apps>>> = {}>(implementations: Apps, ...options: OptionalUnless<O, Options<ActionOf<Member<Apps>>> & O & NoInfer<Known<O, Options<Any>>>>): Tools<{ readonly [T in ToolFor<Member<Apps>, Offered<O, ActionOf<Member<Apps>>>> as T["name"]]: T; }, BuildError<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>, BuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>>;
 //#endregion

package/dist/ActionToolkit.mjs

@@ -1,10 +1,21 @@
-import "./internal/implementation.mjs";
+import { Implementation, provideHandlers, select, toList } from "./internal/implementation.mjs";
 import { bindTools } from "./internal/tools.mjs";
-import "effect";
-import "effect/ai";
 //#region src/ActionToolkit.ts
-function make(apps, options = {}) {
-	return bindTools(apps, "native", options);
+function make(apps, options) {
+	const served = select(toList(apps), options?.actions);
+	const needsApproval = options?.needsApproval;
+	const { toolkit, layer } = bindTools(served, {
+		label: "tool",
+		tool: (tool, action, app) => Object.assign(needsApproval === void 0 ? tool : tool.setNeedsApproval((input, context) => needsApproval({
+			name: action.name,
+			action,
+			input
+		}, context)), { id: `${Implementation.runKey(app)}/${action.name}` })
+	});
+	return {
+		toolkit,
+		layer: layer.pipe(provideHandlers(served))
+	};
 }
 //#endregion
 export { make };

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 };