@gjermundgaraba/effect-actions 0.18.2 → 0.20.0

package/dist/Authentication.d.mts

@@ -6,23 +6,28 @@ import { ErrorsOf } from "./contract/declared.mjs";
 import { Array, Context, Effect, Layer, Option, Redacted, Scope } from "effect";
 import { HttpRouter, HttpServerResponse } from "effect/http";
 import { HttpApiSecurity } from "effect/http-api";
-//#region src/authentication/Authentication.d.ts
 /**
  * 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.
+ * `HttpApiSecurity.bearer` reads it for routes and MCP: the scheme matched case-insensitively,
+ * as RFC 9110 requires, and the token `Redacted`. 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`.
  */
 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. It has no
-   * fragment, which no request URL carries, so its discovery would never answer (RFC 9728).
+   * Exact OAuth resource identifier: the public URL of the endpoint clients connect to, such as
+   * `${url}/mcp`. Discovery is served at `/.well-known/oauth-protected-resource` followed by its
+   * path and query.
+   *
+   * **Gotchas**
+   *
+   * - Discovery answers 404, and an MCP client finds no authorization server, when a request's path and query differ from this URL's, or when the provider is provided to no served layer.
+   * - That it and `authorizationServers` are HTTPS, or loopback HTTP in development, is the deployment's to ensure: nothing checks it.
    */
   readonly resource: string;
-  /** Where clients get tokens: nonempty. */
+  /** Where clients get tokens, your authorization servers' issuers: nonempty. */
   readonly authorizationServers: Array.NonEmptyReadonlyArray<string>;
   /**
    * Every scope the resource accepts, each an OAuth scope token, which a client requests when a
@@ -31,21 +36,29 @@ export interface ProtectedResource {
   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.
+   * authenticates, rather than every scope supported.
+   *
+   * **Gotchas**
+   *
+   * - Give it whenever some actions need scopes others do not, or a user who only reads is asked to consent to writes on first login.
    */
   readonly scopesRequired?: Array.NonEmptyReadonlyArray<string>;
+  /** A human-readable name of the resource, published as `resource_name`. */
   readonly resourceName?: 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 HTTP scheme's or Basic's 401 names that scheme, an API key's none, and nothing
-   * steps up under it. An error it declares is sent as its endpoints declare it.
+   * The descriptor refusing, whose scheme decides the challenge as on its routes: Bearer's when
+   * left out, as `protectedResource` and `authorization` shape it; what another scheme gives up
+   * is on `Options.security`. 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`. */
+  /**
+   * The OAuth protected resource refusing, the one given to `layer`: every challenge then names
+   * its metadata URL, and a 401's its `scopesRequired`. Where `layer` builds the resource from
+   * configuration, build this one from the same configuration.
+   */
   readonly protectedResource?: ProtectedResource | undefined;
   /**
    * The request's `Authorization` header, as the web `Headers.get` gives it, which decides whether a
@@ -57,24 +70,34 @@ 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, or none for an API key. An error
- * `authentication` declares is sent as its endpoints declare it, its JSON with its status.
- * `HttpServerResponse.toWeb` gives it as a web `Response`.
+ * The response `layer` answers a refusal with, for a caller the router never routes, such as a
+ * Node `upgrade` handler admitting a socket, which holds a header and no request: read its token
+ * with `bearerTokenOf`, verify it with the routes' verifier, and answer a failure with this. It
+ * holds the refusal's status and JSON, `Cache-Control: no-store` and the challenge `options`
+ * decide: under Bearer an `Unauthenticated`'s, or the `insufficient_scope` of a `Forbidden`
+ * naming scopes. `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. */
+  /**
+   * The one native scheme a caller proves the identity by, Bearer when left out: an API key in a
+   * cookie, a header or the query, such as `HttpApiSecurity.apiKey({ in: "cookie", key: "session" })`,
+   * or `HttpApiSecurity.basic`. Only Bearer speaks OAuth: discovery, challenges naming scopes, and
+   * step-up.
+   *
+   * **Gotchas**
+   *
+   * - One scheme per descriptor, with no fallback: a host accepting two credentials for one identity declares two descriptors and serves them on two bindings or endpoints.
+   */
   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.
+   *
+   * **Gotchas**
+   *
+   * - A failure that is not the caller's, such as an issuer the verifier cannot reach, belongs here with `{ httpApiStatus: 503 }`: an `Unauthenticated` would have the caller sign in again.
    */
   readonly error?: Errors | Errors[number];
 }
@@ -83,20 +106,38 @@ type SecurityOf<O> = O extends {
 } ? 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.
+ * authenticates, and the scheme a caller proves it by, `Options.security`. The literal name
+ * identifies the provider, like a native Context.Key name, and the scheme's OpenAPI key; reuse
+ * one name only for one declaration, whose values a server and a client may hold as `layer` says.
  * Guide: `docs/Authentication.md` in this package; in an application: `examples/notes-service/src/identity/`.
  */
 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.
+ * belong to the request; one it needs at startup, such as a user directory, is yielded by an
+ * Effect that builds the verifier, given to `layer` in its place.
+ *
+ * **Gotchas**
+ *
+ * - The library reads no token: its signature, expiry and audience are the verifier's to check, with your authorization server's library; fail a token issued for another resource with `Unauthenticated`.
+ * - Only a missing or empty credential is refused before it runs; Basic's reaches it when its username or its password is non-empty, so it may receive an empty username.
  */
 export type Verify<A, S extends Security, R, E = never> = (credential: HttpApiSecurity.HttpApiSecurity.Type<S>) => Effect.Effect<A, Refusal | E, R>;
+/** What `layer` takes besides the descriptor and the verifier. */
 export interface LayerOptions<EP = never, RP = never> {
+  /**
+   * Bearer only: the OAuth protected resource (RFC 9728) to publish, or an Effect building it
+   * when the provider is built; left out, or built as `undefined`, nothing is published. The
+   * provider then serves its discovery and names it in every challenge, so an MCP client given a
+   * 401 finds the authorization server; without it the challenge names nowhere to sign in.
+   *
+   * **Gotchas**
+   *
+   * - Under another scheme it is a type error, or, for an `Http` scheme the types cannot tell from Bearer, a throw at `layer`.
+   * - A literal URL is right in one deployment only: in every other, the published `resource` and each challenge's metadata URL name another server, where an MCP client then looks for its authorization server; give an Effect reading configuration.
+   * - Discovery is public: it answers before routing, to any origin, so no authentication and no route middleware covers it; global middleware covers it only when provided after the provider, as `examples/kitchen-sink/src/routes.ts` shows.
+   */
   readonly protectedResource?: ProtectedResource | Effect.Effect<ProtectedResource | undefined, EP, RP>;
 }
 type ResourceOf<S> = [S] extends [HttpApiSecurity.Http] ? unknown : {
@@ -105,11 +146,17 @@ type ResourceOf<S> = [S] extends [HttpApiSecurity.Http] ? unknown : {
 type Resource = ProtectedResource | Effect.Effect<ProtectedResource | undefined, unknown, unknown> | undefined;
 /**
  * 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`, on the `HttpRouter` it then requires.
+ * each remote request a protected action receives, and on every request presenting a credential
+ * to an MCP endpoint that serves one, with the credential the descriptor's scheme decodes. A
+ * Bearer scheme may publish the OAuth protected resource `protectedResource`, on the
+ * `HttpRouter` it then requires.
+ *
+ * **Gotchas**
+ *
+ * - Call it once per descriptor, and provide that value to every layer serving a protected action: nothing else satisfies the provider they require, neither the identity nor another descriptor's provider, which type-checks under the same name and identity, then dies when the layer builds; only a client may hold another descriptor of the name, such as one of a cookie name the server decides at startup.
  */
 export declare function layer<const Name extends string, I, A, const S extends Security, E extends Errors, R, EX = never, RX = never, P extends Resource = undefined>(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?: {
+  /** The OAuth protected resource to publish: its rules are on `LayerOptions.protectedResource`. */
   readonly protectedResource?: P;
 } & ResourceOf<S>): Layer.Layer<Provider<I, Name>, EX | Effect.Error<P>, ([P] extends [undefined] ? never : HttpRouter.HttpRouter) | Exclude<RX | Effect.Services<P>, Scope.Scope> | HttpRouter.Request.From<"Requires", Exclude<R, HttpRouter.Provided>>>;
 type Provides<I> = unknown extends I ? never : I;
@@ -127,16 +174,19 @@ export type Protection<I, Name extends string> = HttpRouter.Middleware<{
   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.
+ * Native router middleware authenticating a route of the host's own, such as an export, a page
+ * frame or a WebSocket upgrade, as its actions' routes are: the credential its scheme decodes,
+ * verified by `authentication`'s provider, which its layer requires, and the identity provided
+ * to the route. A missing or invalid credential, and a refusal the route fails with, such as a
+ * scope check's `Forbidden`, are answered as on an action route: status, JSON and challenge,
+ * stepping up under Bearer.
+ *
+ * **Gotchas**
+ *
+ * - No authorizer runs for its routes: each states its own authorization, such as by running the `authorize` of the action it mirrors.
+ * - Every response to a request it covers is `Cache-Control: no-store` unless the route states its own caching; a route that does says `private` unless its answer is the same for every caller, or a cache in front of the server may serve it to anyone.
+ * - A failure that enclosing middleware serializes is `no-store` whatever the route set: only a response the route itself returns keeps its caching.
+ * - 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,18 +1,18 @@
-import { Unauthenticated, scopeToken } from "./contract/errors.mjs";
-import { assertOwnTags, errorList } from "./contract/declared.mjs";
+import { Unauthenticated, builtIns, scopeToken } from "./contract/errors.mjs";
+import { assertDistinctTags, errorList } from "./contract/declared.mjs";
 import { providerOf } from "./authentication/provider.mjs";
 import { answer, answerStepUp, bearer, challenge, declaredResponse, isRefusal, isStepUp, plain } from "./authentication/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/Authentication.ts
+// src/authentication/Authentication.ts
 const bearerAuthorizationHeader = /^[ \t]*Bearer +(.*[^ \t])[ \t]*$/i;
 /**
 * 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.
+* `HttpApiSecurity.bearer` reads it for routes and MCP: the scheme matched case-insensitively,
+* as RFC 9110 requires, and the token `Redacted`. 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`.
 */
 const bearerTokenOf = (authorization) => Option.map(Option.fromNullishOr(bearerAuthorizationHeader.exec(authorization ?? "")?.[1]), (token) => Redacted.make(token));
 const metadataUrlOf = (options) => {
@@ -33,28 +33,27 @@ const bearerChallengeOf = (named, presented) => bearer([
 ]);
 const assertPublishableResource = (oauth, options) => {
 	if (options === void 0) return;
-	if (!oauth) throw new Error("A protected resource is published only for a Bearer scheme");
+	if (!oauth) throw new Error("A protected resource is published only for a Bearer scheme: drop `protectedResource`, or authenticate with a Bearer descriptor");
 	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 (invalid !== void 0) throw new Error(`Invalid scope in ${key}: "${invalid}", not an OAuth scope token: give each scope as its own element, of printable ASCII without a space, '"' or '\\'`);
 	}
-	if (new URL(options.resource).href.includes("#")) throw new Error(`A protected resource has no fragment: ${options.resource}`);
+	const resource = URL.parse(options.resource);
+	if (resource === null) throw new Error(`A protected resource is an absolute URL: ${JSON.stringify(options.resource)} is not one; give the public URL of the endpoint clients connect to, such as https://api.example.com/mcp, read from configuration`);
+	if (resource.href.includes("#")) throw new Error(`A protected resource has no fragment: ${options.resource}; drop the "#", which no request URL carries, so its discovery would never answer`);
 };
 const withNoStoreAndChallenge = (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, or none for an API key. An error
-* `authentication` declares is sent as its endpoints declare it, its JSON with its status.
-* `HttpServerResponse.toWeb` gives it as a web `Response`.
+* The response `layer` answers a refusal with, for a caller the router never routes, such as a
+* Node `upgrade` handler admitting a socket, which holds a header and no request: read its token
+* with `bearerTokenOf`, verify it with the routes' verifier, and answer a failure with this. It
+* holds the refusal's status and JSON, `Cache-Control: no-store` and the challenge `options`
+* decide: under Bearer an `Unauthenticated`'s, or the `insufficient_scope` of a `Forbidden`
+* naming scopes. `HttpServerResponse.toWeb` gives it as a web `Response`.
 */
 const refusalResponse = (error, options) => {
 	const authentication = options?.authentication;
@@ -64,7 +63,7 @@ const refusalResponse = (error, options) => {
 	const challenge = authentication !== void 0 && !oauth ? nonBearerChallengeOf(authentication.security, authentication.name) : bearerChallengeOf(named, presentsBearerToken(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");
+		if (response === void 0) throw new Error("Not a refusal, nor an error the authentication declares: pass the descriptor declaring it as `authentication`, or answer the error yourself");
 		return withNoStoreAndChallenge(response, challenge);
 	}
 	return withNoStoreAndChallenge(oauth ? answer(error, named.metadataUrl) : plain(error), challenge);
@@ -115,18 +114,17 @@ const openApiComponentKey = /^[\w.-]+$/;
 const nonBearerChallengeOf = (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.
+* authenticates, and the scheme a caller proves it by, `Options.security`. The literal name
+* identifies the provider, like a native Context.Key name, and the scheme's OpenAPI key; reuse
+* one name only for one declaration, whose values a server and a client may hold as `layer` says.
 * Guide: `docs/Authentication.md` in this package; in an application: `examples/notes-service/src/identity/`.
 */
 const make = (name, identity, ...options) => {
 	const security = options[0]?.security ?? HttpApiSecurity.bearer;
 	const error = errorList(options[0]?.error);
-	if (!openApiComponentKey.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");
+	if (!openApiComponentKey.test(name)) throw new Error(`Invalid authentication name: ${JSON.stringify(name)}, not an OpenAPI key: use only letters, digits, "_", "." and "-"`);
+	assertDistinctTags(`Authentication "${name}"`, [...builtIns, ...error]);
+	if (!Predicate.isTagged(security, "Http") && !Predicate.isTagged(security, "ApiKey") && !Predicate.isTagged(security, "Basic")) throw new Error("Authentication takes one native HttpApiSecurity scheme as `security`: omit it for Bearer, or give one scheme, such as `HttpApiSecurity.basic`, never a record of them");
 	return {
 		name,
 		identity,
@@ -178,16 +176,19 @@ function layer(authentication, verify, options = {}) {
 	}));
 }
 /**
-* 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.
+* Native router middleware authenticating a route of the host's own, such as an export, a page
+* frame or a WebSocket upgrade, as its actions' routes are: the credential its scheme decodes,
+* verified by `authentication`'s provider, which its layer requires, and the identity provided
+* to the route. A missing or invalid credential, and a refusal the route fails with, such as a
+* scope check's `Forbidden`, are answered as on an action route: status, JSON and challenge,
+* stepping up under Bearer.
+*
+* **Gotchas**
+*
+* - No authorizer runs for its routes: each states its own authorization, such as by running the `authorize` of the action it mirrors.
+* - Every response to a request it covers is `Cache-Control: no-store` unless the route states its own caching; a route that does says `private` unless its answer is the same for every caller, or a cache in front of the server may serve it to anyone.
+* - A failure that enclosing middleware serializes is `no-store` whatever the route set: only a response the route itself returns keeps its caching.
+* - 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(providerOf(authentication), (runtime) => (route) => runtime.route(route)));
-//#endregion
 export { bearerTokenOf, layer, make, protect, refusalResponse };

package/dist/Testing.d.mts

@@ -1,35 +1,31 @@
 import { Served } from "./testing/memory.mjs";
 import { Layer } from "effect";
 import { HttpClient, HttpRouter } from "effect/http";
-//#region src/testing/Testing.d.ts
 /**
- * For a web handler the test already owns; most tests want `layer(routes)`, below, with
- * `ActionHttp.client` and `ActionMcp.client`. 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.
+ * The native `HttpClient`, answered by `handler` instead of the network: a web handler the test
+ * serves and disposes of, which other tests and raw web `Request`s may share, such as
+ * `HttpRouter.toWebHandler(routes.pipe(Layer.provide(HttpServer.layerServices))).handler`. It is
+ * the client `layer(routes)` gives, building nothing; most tests want that one, below.
  */
 export declare function layer(handler: (request: Request) => Promise<Response>): Layer.Layer<HttpClient.HttpClient>;
 /**
- * The native `HttpClient`, answered in memory by `routes` instead of the network: provide
- * it to `ActionHttp.client` and to `ActionMcp.client`. The routes are built with this layer and
- * released with its scope, without request logs: only the cause of a defect, of a result that
- * does not encode or of a failure a route of your own leaves unhandled is logged, as an error,
- * where a server's request logger would show it, on the process console even under `it.effect`
- * and its `TestConsole`. 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.
- * Guide: `docs/Testing.md` in this package; in an application: `examples/notes-service/test/`.
- * A type error at `it.effect`, such as one naming `Scope`: `docs/Testing-failures.md`.
+ * The native `HttpClient`, answered in memory by `routes` instead of the network, for
+ * `ActionHttp.client`, `ActionMcp.client` and `HttpClient.execute`. The routes are built with this
+ * layer and released with its scope, keep their real authentication, so a client sends its
+ * caller's credential, and require what they require under `HttpRouter.serve`: a builder's
+ * services, and a per-request service no middleware of theirs provides, a global middleware's
+ * included. Guide: `docs/Testing.md` in this package; in an application:
+ * `examples/notes-service/test/`. A type error at `it.effect`, such as one naming `Scope`:
+ * `docs/Testing-failures.md`.
+ *
+ * **Gotchas**
+ *
+ * - Every request on its client reaches the routes, whatever its host: a relative URL resolves against `http://localhost`, and a client given a `baseUrl`, a remote `ActionCli` command's included, runs unchanged.
+ * - The client is the layer's own: the program's other HTTP clients get none of its requests, so a fake upstream is another `HttpClient`, provided to the service that calls out.
+ * - A service the test reads too is provided around it once, with `Layer.provideMerge`: provided to the routes and again to the test, it is two instances, and the test reads one the handlers never changed.
+ * - Requests run in the context it is built in: a `ConfigProvider` or the test clock provided around the test reaches middleware and handlers.
+ * - No request is logged: only the cause of a defect, of a result that does not encode or of a failure a route leaves unhandled, as an error on the process console, even under `it.effect`'s `TestConsole`; a client reads it as an empty 500.
+ * - It never requires `FileSystem`, `Path`, `HttpPlatform` or `Etag.Generator`: one provided around it is the routes', and `HttpServer.layerServices`' defaults stand in for the rest, whose `FileSystem` is a no-op, so a file the routes read is `NotFound` until `NodeFileSystem.layer` is provided around it.
+ * - It answers HTTP requests and cannot upgrade a WebSocket: give an rpc layer `RpcServer.layerProtocolHttp` in the test, and its client `RpcClient.layerProtocolHttp` over this layer.
  */
-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>>;
-//#endregion
+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>>;

package/dist/Testing.mjs

@@ -1,7 +1,7 @@
 import { clientOf } from "./testing/memory.mjs";
 import { Cause, Console, Context, Effect, ErrorReporter, FileSystem, Layer, Option, Path } from "effect";
 import { Etag, HttpEffect, HttpPlatform, HttpRouter } from "effect/http";
-//#region src/testing/Testing.ts
+// src/testing/Testing.ts
 function layer(routes) {
 	if (!Layer.isLayer(routes)) return clientOf(routes);
 	return Layer.unwrap(Effect.gen(function* () {
@@ -13,5 +13,4 @@ function layer(routes) {
 	}));
 }
 const isReported = (cause) => cause.reasons.some((reason) => Cause.isFailReason(reason) && !ErrorReporter.isIgnored(reason.error) || Cause.isDieReason(reason) && !ErrorReporter.isIgnored(reason.defect));
-//#endregion
 export { layer };

package/dist/authentication/provider.d.mts

@@ -5,7 +5,6 @@ import { Any as Any$1, Errors } from "../Action.mjs";
 import { Context, Effect } from "effect";
 import { HttpRouter, HttpServerResponse } from "effect/http";
 import { HttpApiMiddleware, HttpApiSecurity } from "effect/http-api";
-//#region src/authentication/provider.d.ts
 /** One native security scheme: Bearer unless a descriptor names another. */
 export type Security = HttpApiSecurity.HttpApiSecurity;
 /** What a native scheme decodes: a `Redacted` token or key, or Basic credentials. */
@@ -70,10 +69,7 @@ export interface Descriptor<I, A, S extends Security, Name extends string = stri
   readonly name: Name;
   readonly identity: Context.Key<I, A>;
   readonly security: S;
-  /**
-   * What its verifier may fail with besides a refusal, as a list: every protected endpoint
-   * declares it, and every remote surface sends it, over HTTP with its status.
-   */
+  /** `Options.error` of `make`, as a list. */
   readonly error: E;
   readonly "~provider": Context.Key<Provider<I, Name>, Runtime$1>;
   readonly "~middleware": Context.Key<SecurityMiddleware<I, Name>, unknown>;
@@ -130,5 +126,4 @@ export type VerifierError<A extends Any$1, D> = A["caller"] extends typeof Anyon
   readonly error: infer E extends Errors;
 } ? E[number] : never;
 export type ServedProvider<App, A extends Any$1, D> = [Protected<Serving<App, A>>] extends [never] ? never : ProviderOf<D>;
-//#endregion
 export { Runtime$1 as Runtime };

package/dist/authentication/provider.mjs

@@ -1,7 +1,6 @@
 import { Unauthenticated } from "../contract/errors.mjs";
 import { Effect, Option } from "effect";
-//#region src/authentication/provider.ts
-const providerOf = (auth) => Effect.flatMap(Effect.service(auth["~provider"]), (provider) => provider.descriptor === auth ? Effect.succeed(provider) : Effect.die(/* @__PURE__ */ new Error(`Authentication "${auth.name}": the binding's descriptor is not its provider's; build both from one descriptor`)));
+// src/authentication/provider.ts
+const providerOf = (auth) => Effect.flatMap(Effect.service(auth["~provider"]), (provider) => provider.descriptor === auth ? Effect.succeed(provider) : Effect.die(/* @__PURE__ */ new Error(`Authentication "${auth.name}": the descriptor named here is not the one its provider was built from (build both from one descriptor)`)));
 const promote = (auth, run) => Effect.flatMap(Effect.serviceOption(auth["~verified"]), (actor) => Option.isSome(actor) ? Effect.provideService(run, auth.identity, actor.value) : Effect.fail(new Unauthenticated()));
-//#endregion
 export { promote, providerOf };

package/dist/authentication/refusal.mjs

@@ -1,12 +1,13 @@
 import { Forbidden, Refusal, Unauthenticated } from "../contract/errors.mjs";
 import { declared, httpApiStatusOf } from "../contract/status.mjs";
+import { errorSchemas } from "../contract/declared.mjs";
 import { Cause, Context, Effect, Exit, Option, Predicate, Ref, Schema } from "effect";
 import { HttpServerResponse } from "effect/http";
-//#region src/authentication/refusal.ts
+// src/authentication/refusal.ts
 const responseOf = (schema, error) => HttpServerResponse.jsonUnsafe(Schema.encodeUnknownSync(Schema.toCodecJson(schema))(error), { status: httpApiStatusOf(schema.ast) ?? 422 });
 /** `error` answered as an endpoint declaring `errors` answers it, if one of them declares it. */
 const declaredResponse = (errors, error) => {
-	const schema = errors.flatMap(declared).find((each) => Schema.is(each)(error));
+	const schema = errorSchemas(errors).map(declared).find((each) => Schema.is(each)(error));
 	return schema === void 0 ? void 0 : responseOf(schema, error);
 };
 const rfc6750ErrorDescriptionCharacters = /^[\x20\x21\x23-\x5B\x5D-\x7E]+$/;
@@ -42,5 +43,4 @@ const answerStepUp = (route, metadataUrl) => Effect.gen(function* () {
 	const diedOrInterruptedAfterRefusal = Exit.isFailure(exit) && (Cause.hasDies(exit.cause) || Cause.hasInterrupts(exit.cause));
 	return Option.isSome(refused) && !diedOrInterruptedAfterRefusal ? answer(refused.value, metadataUrl) : yield* exit;
 });
-//#endregion
 export { answer, answerStepUp, bearer, challenge, declaredResponse, isRefusal, isStepUp, plain, recordStepUp };

package/dist/cli/commands.d.mts

@@ -2,38 +2,60 @@ import "../contract/errors.mjs";
 import { Any } from "../Action.mjs";
 import { Effect, Option, Runtime, Types } from "effect";
 import { CliError, Command } from "effect/cli";
-//#region src/cli/commands.d.ts
 type Field<A extends Any> = A["input"]["Encoded"] extends (infer E) ? true extends Types.IsUnion<E> ? never : E extends ReadonlyArray<unknown> ? never : E extends object ? string extends keyof E ? never : Extract<keyof E, string> : never : never;
 type StdinField<A extends Any> = A["input"]["Encoded"] extends (infer E) ? Exclude<Field<A>, { [K in keyof E]-?: {} extends Pick<E, K> ? K : never; }[keyof E]> : never;
 /** How one command of `A` is named, takes its input and prints its result. */
 export interface Options<A extends Any> {
   /** Override the command name. The action name, in kebab case, is used by default. */
   readonly name?: string;
-  /** Human output. Adds a `--json` flag to the command that selects JSON instead. */
+  /**
+   * The command's help, where the CLI's command differs from the action, such as one rendering
+   * a summary: `"List the open issues, one per line."`. The action's `description` is used by
+   * default, and stays what HTTP, MCP and RPC describe. With `stdin`, the paragraph naming the
+   * field stdin fills follows it.
+   */
+  readonly description?: string;
+  /**
+   * Human output: the decoded success to text for a person. Adds a `--json` flag to the
+   * command that selects JSON instead.
+   */
   readonly render?: (output: A["success"]["Type"]) => string;
   /**
-   * Input fields taken as positional arguments instead of flags, in this order. An
-   * optional field is an optional argument, so it follows every required one.
+   * Input fields taken as positional arguments instead of flags, in this order: `["id"]` takes
+   * `get-note 7` for `--id 7`. An optional field is an optional argument, and an array field
+   * takes every argument left, one element each.
+   *
+   * **Gotchas**
+   *
+   * - A field listed here has no flag: `--<field>` is `Unrecognized flag`, so pass its value as an argument.
    */
   readonly positional?: ReadonlyArray<Field<A>>;
   /**
-   * A short name per input field's flag, such as `{ limit: "n" }` for `-n`, given as
-   * `Param.withAlias` takes it.
+   * A short name per input field's flag, such as `{ limit: "n" }` for `-n 5` beside
+   * `--limit 5`, given as `Param.withAlias` takes it.
    */
   readonly aliases?: { readonly [K in Field<A>]?: string; };
   /**
    * A required field read from stdin instead of a flag, such as a secret, which a flag would
-   * leave in the process list and the shell's history.
+   * leave in the process list and the shell's history, or a document. The value is all of
+   * stdin until it closes, without the line endings that end it.
+   *
+   * **Gotchas**
+   *
+   * - A terminal is never read: run interactively, the command fails with `InvalidInput`.
+   * - The command waits without output until stdin closes: a parent process holding the pipe, or `ssh` without `-n`, keeps it open, so redirect stdin from a file or `/dev/null`.
    */
   readonly stdin?: StdinField<A>;
 }
 /**
  * What a command fails with when its action fails: Effect CLI's `UserError`, typed with the
- * action's failure as its `cause` and `reason`, and whose message is its JSON, which `Command.run`
- * prints on stderr and marks reported, so `runMain` does not print it again. The process exits with
- * the cause's `Runtime.errorExitCode`, 1 by default. A type only: after `Command.run`, match the
- * reason by its tag, `Effect.catchReason("UserError", "UserNotFound", f)`. A command of your own
- * fails with one through `toUserError`; any other failure is reported as a crash, `ERROR (#n)`.
+ * action's failure as its `cause` and `reason`, and whose `userMessage` is its JSON, or for a
+ * failure no schema encodes, as `command` says. A type only.
+ *
+ * **Gotchas**
+ *
+ * - `Command.run` has printed it before a recovery runs, so a recovery decides what follows, such as the exit code, not the text: for text of your own, provide `CliOutput.layer(Object.assign({}, CliOutput.defaultFormatter(), { formatError }))`, or pass `renderErrors: false` to `Command.run` and print every failure, the parser's too.
+ * - A run also fails with Effect CLI's own errors, such as a flag that does not parse, and only a `UserError` has a `userMessage`: match `Effect.catchTag("UserError", …)` before reading one.
  */
 export declare class UserError<out E = unknown> extends CliError.UserError {
   readonly cause: E;
@@ -44,5 +66,4 @@ export declare class UserError<out E = unknown> extends CliError.UserError {
   get reason(): E;
   get [Runtime.errorExitCode](): number;
 }
-//#endregion
 export {};