@gjermundgaraba/effect-actions 0.20.0 → 0.21.0

package/dist/Event.mjs

@@ -0,0 +1,103 @@
+import { Anyone, assertCaller } from "./contract/caller.mjs";
+import { assertEventName, assertOnce } from "./contract/names.mjs";
+import { codecOf } from "./contract/codec.mjs";
+import { authorizerOf } from "./contract/authorizer.mjs";
+import { Events, layerMemory, makeEvents } from "./contract/hub.mjs";
+import { Gap } from "./contract/occurrence.mjs";
+import { EventImplementation, sourcesOf } from "./contract/feed.mjs";
+import { Array as Array$1, Data, Effect, Match, Predicate, Schema } from "effect";
+// src/contract/Event.ts
+const TypeId = "~@gjermundgaraba/effect-actions/Event";
+/** Whether `u` is an event type `make` defined: a binding's list tells events from actions by it. */
+const isEvent = (u) => Predicate.hasProperty(u, TypeId);
+function make(name, options) {
+	assertEventName(name);
+	const { caller } = options;
+	assertCaller(caller);
+	if (options.payload === void 0) throw new Error(`Missing payload: event "${name}" (declare what each occurrence carries)`);
+	return {
+		[TypeId]: TypeId,
+		caller,
+		name,
+		description: options.description,
+		input: codecOf(options.input ?? {}),
+		payload: codecOf(options.payload)
+	};
+}
+/** The server serves no event type of that name, or no longer does. */
+var NotServed = class extends Schema.TaggedError()("NotServed", {}) {};
+/**
+* The server serves the event type, but not as asked: `feature` names what it does not offer,
+* such as `deliveryMode`, and `value` which one, such as `push`.
+*/
+var Unsupported = class extends Schema.TaggedError()("Unsupported", {
+	feature: Schema.String,
+	value: Schema.optional(Schema.String)
+}) {};
+/**
+* Why a webhook's callback endpoint failed, in SEP-3415's categories: it refused the connection
+* or was unreachable, timed out, failed TLS, answered a status from 300 to 499 (`http_4xx`, as
+* the categories name no 3xx) or a 5xx, or did not echo the verification challenge.
+*/
+const CallbackCategory = Schema.Literals([
+	"connection_refused",
+	"timeout",
+	"tls_error",
+	"http_4xx",
+	"http_5xx",
+	"challenge_failed"
+]);
+/** A webhook subscription's callback endpoint failed its verification, or was unreachable. */
+var CallbackFailed = class extends Schema.TaggedError()("CallbackFailed", { category: CallbackCategory }) {};
+/** No webhook subscription matches the one an unsubscribe names. */
+var NotSubscribed = class extends Schema.TaggedError()("NotSubscribed", {}) {};
+const Reason = Schema.Union([
+	NotServed,
+	Unsupported,
+	CallbackFailed,
+	NotSubscribed
+]);
+const sentenceOf = Match.typeTags()({
+	NotServed: () => "is not served",
+	Unsupported: ({ feature, value }) => `is not served with this ${feature}${value === void 0 ? "" : `: ${value}`}`,
+	CallbackFailed: ({ category }) => `could not reach its webhook's callback: ${category}`,
+	NotSubscribed: () => "has no such webhook subscription"
+});
+/**
+* A subscription that cannot start or go on: `reason` says why, so a subscriber branches on it
+* with `Effect.catchReason("SubscriptionError", "NotServed", ...)`; `message` names the event and
+* the reason. A refusal is `Action.Unauthenticated` or `Action.Forbidden`, and input that does not
+* decode `Action.InvalidInput`, as for an action.
+*/
+var SubscriptionError = class SubscriptionError extends Schema.TaggedError()("SubscriptionError", {
+	event: Schema.String,
+	reason: Reason,
+	message: Schema.String
+}, { httpApiStatus: 409 }) {
+	/** The error for `event` failing with `reason`, its message built from both. */
+	static of(event, reason) {
+		return new SubscriptionError({
+			event,
+			reason,
+			message: `Event "${event}" ${sentenceOf(reason)}`
+		});
+	}
+};
+/**
+* A watch delivered by webhook, which `Webhook.delivery` makes: the server POSTs each occurrence
+* to the route `Webhook.layerReceiver` serves in the watching process, reached under `baseUrl`,
+* for as long as the watch is read, each grant asking for `ttl`.
+*/
+var WebhookDelivery = class extends Data.TaggedClass("WebhookDelivery") {};
+/** Every authenticated subscriber may subscribe to a protected event type. */
+const allowAll = () => Effect.void;
+function implement(events, sources, options) {
+	const listed = Array$1.ensure(events);
+	assertOnce("event", listed);
+	const authorizer = authorizerOf({
+		singular: "event",
+		module: "Event"
+	}, listed.some((event) => event.caller !== Anyone), options?.authorize);
+	return new EventImplementation(listed, sourcesOf(listed, !Array.isArray(events), sources), authorizer);
+}
+export { CallbackCategory, CallbackFailed, Events, Gap, NotServed, NotSubscribed, SubscriptionError, Unsupported, WebhookDelivery, allowAll, implement, isEvent, layerMemory, make, makeEvents };

package/dist/Testing.mjs

@@ -2,6 +2,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";
 // src/testing/Testing.ts
+const isReported = (cause) => cause.reasons.some((reason) => Cause.isFailReason(reason) && !ErrorReporter.isIgnored(reason.error) || Cause.isDieReason(reason) && !ErrorReporter.isIgnored(reason.defect));
 function layer(routes) {
 	if (!Layer.isLayer(routes)) return clientOf(routes);
 	return Layer.unwrap(Effect.gen(function* () {
@@ -12,5 +13,4 @@ function layer(routes) {
 		return clientOf(HttpEffect.toWebHandlerWith(context)(Effect.tapCause(app, (cause) => isReported(cause) ? Effect.logError(cause).pipe(Effect.provideService(Console.Console, globalThis.console)) : Effect.void)));
 	}));
 }
-const isReported = (cause) => cause.reasons.some((reason) => Cause.isFailReason(reason) && !ErrorReporter.isIgnored(reason.error) || Cause.isDieReason(reason) && !ErrorReporter.isIgnored(reason.defect));
 export { layer };

package/dist/Webhook.d.mts

@@ -0,0 +1,146 @@
+import { WebhookDelivery } from "./Event.mjs";
+import { Receiving } from "./contract/receiving.mjs";
+import { Webhooks } from "./contract/webhooks.mjs";
+import { Duration, Layer } from "effect";
+import { HttpClient, HttpRouter } from "effect/http";
+import { Dns } from "effect/net";
+import { KeyValueStore } from "effect/persistence";
+/** How `layer` grants, verifies and retries webhook subscriptions. */
+export interface Options {
+  /**
+   * The longest lifetime a subscription is granted, and what one that suggests none, or asks for
+   * no expiry with `ttlMs: null`, is granted. Defaults to 1 hour; a suggestion under 1 minute is
+   * granted 1 minute. Finite, as every grant expires: `Duration.infinity` is refused as the layer
+   * is made.
+   */
+  readonly maxTtl?: Duration.Input | undefined;
+  /**
+   * Callbacks trusted without the verification handshake or the address check, each an https
+   * URL whose origin a callback has exactly and whose path it starts with, segment by segment:
+   * `["https://hooks.example.com/"]`. A callback on a private network is delivered to only when
+   * one of them trusts it.
+   */
+  readonly allowedCallbacks?: readonly string[] | undefined;
+  /**
+   * How long a subscription's deliveries are retried from its first failure, each wait as long as
+   * it has been failing, from 1 second to 5 minutes, before it suspends until its next refresh,
+   * which delivers it again with a fresh `retryFor`. Defaults to 1 hour.
+   *
+   * **Gotchas**
+   *
+   * - The failures are timed from the subscription's `failedSince`, which `persist` keeps: a restart goes on with the waits and the budget it reached, and a refresh of a subscription still delivering does not extend it.
+   */
+  readonly retryFor?: Duration.Input | undefined;
+  /**
+   * Keep each subscription in the application's `KeyValueStore`, which the layer then needs, so
+   * a restart goes on delivering from where it reached: each surface restores the subscriptions
+   * of the events it serves as it builds.
+   *
+   * **Gotchas**
+   *
+   * - Each subscriber's identity is kept by its authentication's `schema`, encoded at each grant: a surface offering a protected event by webhook refuses to start without it, or where two authentications with different schemas serve one event.
+   * - A restored delivery runs in the layer's context and that identity alone, until the subscriber's next refresh: an authorizer or a source reading a service middleware or the surface's layer provides fails, each read reported and retried every 5 seconds.
+   * - A subscriber refused as its subscription is restored is POSTed `terminated`; an authorizer or a source failing its first read with no refusal is retried, as later.
+   * - A subscription suspended stays suspended when restored, until its subscriber's refresh delivers again.
+   * - Secrets and identities are kept as JSON, as given, so give the layer a store only the server reads.
+   * - A kept subscription whose input or identity no longer decodes, as after a schema change, is reported at each build and never restored, until its subscriber unsubscribes it.
+   * - A store whose index cannot be read as the layer builds fails the build; a write that fails later is reported and tried again with the next, and pending writes get 5 seconds when the layer closes.
+   * - A callback's verification is not kept: a restored subscription delivers on, and a new one to the same callback after a restart is verified again.
+   */
+  readonly persist?: boolean | undefined;
+  /**
+   * Whether a callback's name is resolved through `Dns` for its address check. `false` checks a
+   * literal address alone and leaves a name to the platform's egress, and the layer then needs no
+   * `Dns`: for a host with no resolver of its own, such as Cloudflare Workers. Defaults to `true`.
+   *
+   * **Gotchas**
+   *
+   * - With `false`, a callback named for a private or loopback address is POSTed to wherever the platform's egress reaches: give it only where that egress reaches no network of yours.
+   */
+  readonly resolveCallbacks?: boolean | undefined;
+}
+/**
+ * Webhook delivery for the MCP endpoints and HTTP routes it is provided to, as SEP-3415 defines
+ * it: a subscriber names a callback URL and a secret, and each occurrence of a protected event
+ * it may see is POSTed there, signed as Standard Webhooks signs, until the subscription expires,
+ * is unsubscribed, or is refused. One layer holds the subscriptions of every surface it is
+ * provided to, so a subscription made over MCP is the one HTTP refreshes. It needs an
+ * `HttpClient` for the deliveries, `Dns` for the address check unless `resolveCallbacks` is
+ * `false`, and with `persist` a `KeyValueStore`. Each POST carries the
+ * headers `webhook-id`, `webhook-timestamp`, `webhook-signature` and `x-mcp-subscription-id`, and
+ * one JSON body: an occurrence `{ eventId, name, timestamp, data, cursor }`, whose `webhook-id`
+ * is its `eventId`, or an envelope, `{ type: "verification", challenge }` to echo,
+ * `{ type: "gap", cursor }` where occurrences were missed, or `{ type: "terminated", error }`
+ * where the subscription ended. Guide: `docs/Webhook.md` in this package.
+ *
+ * **Gotchas**
+ *
+ * - Only a protected event whose descriptor has `principal` is offered webhook delivery: elsewhere `events/list` lists no `webhook`, and a subscribe is `Unsupported`.
+ * - A `requestScoped` MCP endpoint offers it too, its subscriptions built once with the endpoint: on a host with no lasting process, leave this layer out, as `ActionHttp.layer` says, since each instance keeps its own subscriptions, lost as it ends.
+ * - A callback resolving to an address that is not globally reachable, a loopback or a private one included, is never POSTed to unless `allowedCallbacks` trusts it: a local receiver needs a public name, a trusted URL, or a test's `Dns.layerStatic`; an IPv6-only server behind NAT64 cannot deliver to an IPv4-only callback.
+ * - Each POST is checked against the address it resolves to, but fetch connects to the name again, so a name rebinding between the check and the connection is not caught: front the server with an egress proxy that refuses private addresses where that matters.
+ * - Deliveries run with fetch's `redirect: "manual"`, and a 3xx answer is a failed attempt; an `HttpClient` that is not fetch's follows redirects as it does.
+ * - A failed attempt's category is `connection_refused` for any transport failure, never `tls_error`, which no platform client reports apart.
+ * - A delivery's 2xx answer is a success, its body never read; a verification's answer is read as far as 4 KiB, and one longer fails its challenge.
+ * - A callback verified for a subscriber is not challenged again for that subscriber's other subscriptions to it while one is granted, as SEP-3415's soft state allows.
+ * - Deliveries are one at a time, in order: one failing holds back those after it, for `retryFor`, then the subscription suspends until a refresh, which delivers it again.
+ * - An occurrence given up, its body over 256 KiB or its POST answered `410` or `413`, is POSTed as a `gap` at its cursor; one whose admission fails with no refusal is reported and read again, from before it, every 5 seconds.
+ * - A refresh restarts its subscription's reading under the refreshed subscriber, from where delivery reached: the subscription hook set up again once the old one is released, and a delivery in flight sent again, which the subscriber drops by its `eventId`.
+ * - A refresh its authorizer refuses ends the subscription it names, POSTing `terminated`, though each delivery, admitted as the subscriber of the last grant, would still pass.
+ * - A refresh with a new secret signs each POST with both secrets for 5 minutes, `webhook-signature` holding two, so a receiver may switch over; after that, with the new one alone.
+ * - A delivery runs in the subscribe request's context without the request: an authorizer or a source reading `HttpServerRequest` fails in a delivery, so read what it needs in middleware, which provides it as a service.
+ * - `allowedCallbacks` throws when `layer` is called for an entry that is not an https URL.
+ */
+export declare function layer(options: Options & {
+  readonly persist?: false | undefined;
+  readonly resolveCallbacks: false;
+}): Layer.Layer<Webhooks, never, HttpClient.HttpClient>;
+export declare function layer(options: Options & {
+  readonly resolveCallbacks: false;
+}): Layer.Layer<Webhooks, never, HttpClient.HttpClient | KeyValueStore.KeyValueStore>;
+export declare function layer(options?: Options & {
+  readonly persist?: false | undefined;
+}): Layer.Layer<Webhooks, never, HttpClient.HttpClient | Dns.Dns>;
+export declare function layer(options: Options): Layer.Layer<Webhooks, never, HttpClient.HttpClient | Dns.Dns | KeyValueStore.KeyValueStore>;
+/** Where a watch by webhook asks the server to POST, and the lifetime each grant asks for. */
+export type DeliveryOptions = ConstructorParameters<typeof WebhookDelivery>[0];
+/**
+ * A watch's `mode` delivering by webhook: `client.watch(event, input, { mode:
+ * Webhook.delivery({ baseUrl }) })` requires this process's `layerReceiver`, keeps a place there,
+ * subscribes the receiver's `path` under `baseUrl` with that place's id and secret, reads what
+ * the server POSTs there, refreshes the subscription when half its grant is left, also through a
+ * reconnect, and unsubscribes when the watch ends. Over MCP and HTTP; elsewhere the watch fails
+ * with `Event.SubscriptionError`, reason `Unsupported`.
+ *
+ * **Gotchas**
+ *
+ * - The receiver's route must be reached at `baseUrl` and its `path`: served elsewhere, or by another `layerReceiver` than the one the watch is given, the subscribe fails with `CallbackFailed`.
+ * - A `baseUrl` that is not an absolute https URL fails the watch with a `SchemaError` before it takes a place at the receiver.
+ * - A server refuses a callback that is not globally reachable, so `baseUrl` is a public name of this process, such as a tunnel's in development.
+ * - The URL subscribed carries a `watch` query parameter, one per watch, so watches never share a subscription: a proxy in front of the route must pass the query on.
+ * - A restarted process subscribes afresh from the cursor `resume` kept, so the server sends again what the last process accepted and never handed on; the old subscription lapses at its grant, each delivery to it answered 410.
+ */
+export declare const delivery: (options: DeliveryOptions) => WebhookDelivery;
+/** Where `layerReceiver` serves its route. */
+export interface ReceiverOptions {
+  /** The route's path, `/hooks/builds`, which each watch's `delivery` appends to its `baseUrl`. */
+  readonly path: `/${string}`;
+}
+/**
+ * The receiving end of watches by webhook in this process: a `POST` route at `path`, and the
+ * registry each watch keeps its place in, under an id its delivery URL names and a secret of its
+ * own. Each POST is verified as Standard Webhooks signs it, against the secret of the watch it
+ * names, its timestamp within 5 minutes, and handed to that watch; a verification is answered
+ * with its challenge, and a `webhook-id` among the watch's last 1,000 is acknowledged and dropped. Build it once,
+ * the watches given it as the route's layer is (`Layer.provideMerge`).
+ * Guide: `docs/Webhook.md` in this package.
+ *
+ * **Gotchas**
+ *
+ * - A POST naming no watch of this receiver is a 410, which the server abandons without retrying: what is in flight to a watch that ended is not delivered, and its subscription lapses at its grant.
+ * - A POST its watch's secret did not sign, or out of the timestamp window, is a 401; a signed body that is not a JSON object, a 400.
+ * - A watch reads at its consumer's pace: 16 deliveries wait for it, and the next is answered 503, which the server retries.
+ * - Two `layerReceiver` layers are two registries: a watch given one, its route served by the other, has its subscribe fail with `CallbackFailed`, every POST a 410.
+ * - A body is read whole: limit it with `HttpServerRequest.MaxBodySize` where the route is served, as `ActionHttp.layer`'s gotcha says.
+ */
+export declare const layerReceiver: ({ path }: ReceiverOptions) => Layer.Layer<Receiving, never, HttpRouter.HttpRouter>;

package/dist/Webhook.mjs

@@ -0,0 +1,72 @@
+import { WebhookDelivery } from "./Event.mjs";
+import { Receiving } from "./contract/receiving.mjs";
+import { Webhooks } from "./contract/webhooks.mjs";
+import { makeReceiver } from "./webhook/receiver.mjs";
+import { makeStorage } from "./webhook/stored.mjs";
+import { makeWebhooks } from "./webhook/subscriptions.mjs";
+import { Duration, Effect, Layer } from "effect";
+import { HttpRouter } from "effect/http";
+import { Dns } from "effect/net";
+import { KeyValueStore } from "effect/persistence";
+// src/webhook/Webhook.ts
+const trustedOf = (prefix) => {
+	const url = URL.parse(prefix);
+	if (url?.protocol !== "https:") throw new Error(`Invalid allowedCallbacks entry: ${prefix} (give an https URL, such as https://hooks.example.com/)`);
+	return url;
+};
+const maxTtlOf = (input) => {
+	const maxTtl = Duration.fromInputUnsafe(input);
+	if (!Duration.isFinite(maxTtl)) throw new Error(`Invalid maxTtl: ${Duration.format(maxTtl)} (every grant expires: give a finite duration, such as "1 hour")`);
+	return maxTtl;
+};
+function layer(options = {}) {
+	const allowedCallbacks = (options.allowedCallbacks ?? []).map(trustedOf);
+	const maxTtl = maxTtlOf(options.maxTtl ?? "1 hour");
+	return Layer.effect(Webhooks, Effect.gen(function* () {
+		const dns = options.resolveCallbacks === false ? void 0 : yield* Dns.Dns;
+		const storage = options.persist === true ? yield* Effect.flatMap(KeyValueStore.KeyValueStore, makeStorage) : void 0;
+		return yield* makeWebhooks({
+			maxTtl,
+			allowedCallbacks,
+			retryFor: Duration.fromInputUnsafe(options.retryFor ?? "1 hour"),
+			storage,
+			dns
+		});
+	}));
+}
+/**
+* A watch's `mode` delivering by webhook: `client.watch(event, input, { mode:
+* Webhook.delivery({ baseUrl }) })` requires this process's `layerReceiver`, keeps a place there,
+* subscribes the receiver's `path` under `baseUrl` with that place's id and secret, reads what
+* the server POSTs there, refreshes the subscription when half its grant is left, also through a
+* reconnect, and unsubscribes when the watch ends. Over MCP and HTTP; elsewhere the watch fails
+* with `Event.SubscriptionError`, reason `Unsupported`.
+*
+* **Gotchas**
+*
+* - The receiver's route must be reached at `baseUrl` and its `path`: served elsewhere, or by another `layerReceiver` than the one the watch is given, the subscribe fails with `CallbackFailed`.
+* - A `baseUrl` that is not an absolute https URL fails the watch with a `SchemaError` before it takes a place at the receiver.
+* - A server refuses a callback that is not globally reachable, so `baseUrl` is a public name of this process, such as a tunnel's in development.
+* - The URL subscribed carries a `watch` query parameter, one per watch, so watches never share a subscription: a proxy in front of the route must pass the query on.
+* - A restarted process subscribes afresh from the cursor `resume` kept, so the server sends again what the last process accepted and never handed on; the old subscription lapses at its grant, each delivery to it answered 410.
+*/
+const delivery = (options) => new WebhookDelivery(options);
+/**
+* The receiving end of watches by webhook in this process: a `POST` route at `path`, and the
+* registry each watch keeps its place in, under an id its delivery URL names and a secret of its
+* own. Each POST is verified as Standard Webhooks signs it, against the secret of the watch it
+* names, its timestamp within 5 minutes, and handed to that watch; a verification is answered
+* with its challenge, and a `webhook-id` among the watch's last 1,000 is acknowledged and dropped. Build it once,
+* the watches given it as the route's layer is (`Layer.provideMerge`).
+* Guide: `docs/Webhook.md` in this package.
+*
+* **Gotchas**
+*
+* - A POST naming no watch of this receiver is a 410, which the server abandons without retrying: what is in flight to a watch that ended is not delivered, and its subscription lapses at its grant.
+* - A POST its watch's secret did not sign, or out of the timestamp window, is a 401; a signed body that is not a JSON object, a 400.
+* - A watch reads at its consumer's pace: 16 deliveries wait for it, and the next is answered 503, which the server retries.
+* - Two `layerReceiver` layers are two registries: a watch given one, its route served by the other, has its subscribe fail with `CallbackFailed`, every POST a 410.
+* - A body is read whole: limit it with `HttpServerRequest.MaxBodySize` where the route is served, as `ActionHttp.layer`'s gotcha says.
+*/
+const layerReceiver = ({ path }) => Layer.unwrap(Effect.map(makeReceiver(path), ({ receiving, handler }) => Layer.merge(Layer.succeed(Receiving, receiving), HttpRouter.add("POST", path, handler))));
+export { delivery, layer, layerReceiver };

package/dist/authentication/provider.d.mts

@@ -1,7 +1,10 @@
+import { Codec } from "../contract/codec.mjs";
 import { Anyone } from "../contract/caller.mjs";
 import { Refusal } from "../contract/errors.mjs";
+import { EventOf, ServingEvents } from "../contract/feed.mjs";
+import { Any as Any$1 } from "../Event.mjs";
 import { BuildServices, Protected, ServedRequest, Serving } from "../contract/implementation.mjs";
-import { Any as Any$1, Errors } from "../Action.mjs";
+import { Any as Any$2, Errors } from "../Action.mjs";
 import { Context, Effect } from "effect";
 import { HttpRouter, HttpServerResponse } from "effect/http";
 import { HttpApiMiddleware, HttpApiSecurity } from "effect/http-api";
@@ -30,6 +33,7 @@ export interface SecurityMiddleware<I, Name extends string = string> {
   };
 }
 type Response = Effect.Effect<HttpServerResponse.HttpServerResponse, unknown, unknown>;
+/** What a provider holds for the surfaces serving its descriptor, beside its identity. */
 interface Runtime$1 {
   /** The descriptor the provider was built from, the one a binding naming it must hold. */
   readonly descriptor: unknown;
@@ -71,6 +75,10 @@ export interface Descriptor<I, A, S extends Security, Name extends string = stri
   readonly security: S;
   /** `Options.error` of `make`, as a list. */
   readonly error: E;
+  /** `Options.principal` of `make`, the stable id of an identity, where given. */
+  principal?(identity: A): string;
+  /** `Options.schema` of `make`, how an identity is kept, where given. */
+  readonly schema?: Codec | undefined;
   readonly "~provider": Context.Key<Provider<I, Name>, Runtime$1>;
   readonly "~middleware": Context.Key<SecurityMiddleware<I, Name>, unknown>;
   /** An MCP request's verified identity, which a protected tool's call promotes. */
@@ -81,16 +89,19 @@ export interface Descriptor<I, A, S extends Security, Name extends string = stri
  * binding name one.
  */
 export type Any = Descriptor<unknown, unknown, Security, string, Errors>;
-export type Identity<A extends Any$1> = [A] extends [never] ? never : A["caller"] extends Context.Key<infer I, unknown> ? I : never;
-type Covered<A extends Any$1> = Exclude<A["caller"], typeof Anyone> extends Context.Key<infer I, unknown> ? I : never;
-export type Required<A extends Any$1> = [Protected<A>] extends [never] ? {
+/** The identity an action's `caller` names, or `never` for none. */
+export type Identity<A extends Pick<Any$2, "caller">> = [A] extends [never] ? never : A["caller"] extends Context.Key<infer I, unknown> ? I : never;
+type Covered<A extends Pick<Any$2, "caller">> = Exclude<A["caller"], typeof Anyone> extends Context.Key<infer I, unknown> ? I : never;
+/** The `authentication` a binding of these actions takes: required once one is protected. */
+export type Required<A extends Pick<Any$2, "caller">> = [Protected<A>] extends [never] ? {
   readonly authentication?: Any;
 } : {
   readonly authentication: Descriptor<Covered<Protected<A>>, unknown, Security, string, Errors>;
 };
+/** The provider `Authentication.layer` builds for the descriptor `D`. */
 export type ProviderOf<D> = D extends Descriptor<infer I, unknown, Security, infer Name, Errors> ? Provider<I, Name> : never;
 /** Actions a binding takes without options: public ones, as a protected one names its descriptor. */
-export type PublicOnly<Actions extends ReadonlyArray<Any$1>> = [Exclude<Actions[number], {
+export type PublicOnly<Actions extends ReadonlyArray<Pick<Any$2, "caller">>> = [Exclude<Actions[number], {
   readonly caller: typeof Anyone;
 }>] extends [never] ? unknown : {
   readonly "Protected actions take options naming their authentication": never;
@@ -100,19 +111,29 @@ export type DescriptorOf<O> = [O] extends [{
   readonly authentication: infer D extends Any;
 }] ? D : undefined;
 /** All protected actions on a surface use the descriptor's single identity key. */
-export type Matching<A extends Any$1, D> = unknown extends Covered<Protected<A>> ? unknown : [Exclude<Covered<Protected<A>>, D extends Descriptor<infer I, unknown, Security, string, Errors> ? I : never>] extends [never] ? unknown : {
+export type Matching<A extends Pick<Any$2, "caller">, D> = unknown extends Covered<Protected<A>> ? unknown : [Exclude<Covered<Protected<A>>, D extends Descriptor<infer I, unknown, Security, string, Errors> ? I : never>] extends [never] ? unknown : {
   readonly "Authentication descriptor does not cover every protected action": never;
 };
 /** Keep public requirements separate, without rescanning all handlers for every action. */
-export type RemoteRequest<App, A extends Any$1> = ServedRequest<App, Extract<A, {
+export type RemoteRequest<App, A extends Any$2> = ServedRequest<App, Extract<A, {
   readonly caller: typeof Anyone;
 }>> | Exclude<ServedRequest<App, Protected<A>>, Identity<Protected<A>>>;
+/**
+ * The identity a remote layer's authentication provides every request, where `App` serves only
+ * protected actions of `A` and event types of `E`: its middleware reading it then owes nothing.
+ * None where one served is public, whose requests authenticate no one.
+ */
+export type LayerIdentity<App, A extends Any$2, E extends Any$1> = [Extract<Serving<App, A>, {
+  readonly caller: typeof Anyone;
+}> | Extract<ServingEvents<App, E>, {
+  readonly caller: typeof Anyone;
+}>] extends [never] ? Identity<Protected<Serving<App, A>> | Protected<ServingEvents<App, E>>> : never;
 /**
  * What a server of the actions `A` of the implementations `App` reads at startup, as
  * `BuildServices` states it, with the caller a builder yields named as the mistake it is: a server
  * has its caller per request.
  */
-export type ServerBuildServices<App, A extends Any$1> = App extends unknown ? BuildServices<App, A> extends (infer R) ? R extends Identity<Protected<A>> ? {
+export type ServerBuildServices<App, A extends Any$2> = App extends unknown ? BuildServices<App, A> extends (infer R) ? R extends Identity<Protected<A>> ? {
   readonly "A builder yields the caller, which a server has per request: yield it in a handler or an authorizer": {
     readonly caller: R;
     readonly builderOf: Serving<App, A>["name"];
@@ -122,8 +143,12 @@ export type ServerBuildServices<App, A extends Any$1> = App extends unknown ? Bu
  * What a call of `A` under the descriptor `D` may fail with from its verifier: the errors `D`
  * declares, for a protected action; none for a public one, which nothing verifies.
  */
-export type VerifierError<A extends Any$1, D> = A["caller"] extends typeof Anyone ? never : D extends {
+export type VerifierError<A extends Pick<Any$2, "caller">, D> = A["caller"] extends typeof Anyone ? never : D extends {
   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>;
+/**
+ * The provider a surface's startup reads under the descriptor `D`, where the implementations
+ * `App` serve a protected action of `A` or a protected event type of `E`.
+ */
+export type ServedProvider<App, A extends Any$2, D, E extends Any$1 = EventOf<App>> = [Protected<Serving<App, A>> | Protected<E>] extends [never] ? never : ProviderOf<D>;
 export { Runtime$1 as Runtime };

package/dist/authentication/provider.mjs

@@ -1,6 +1,6 @@
 import { Unauthenticated } from "../contract/errors.mjs";
 import { Effect, Option } from "effect";
 // 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 providerOf = (auth) => Effect.filterOrElse(Effect.service(auth["~provider"]), (provider) => provider.descriptor === auth, () => 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()));
 export { promote, providerOf };

package/dist/authentication/refusal.mjs

@@ -10,9 +10,9 @@ const declaredResponse = (errors, 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]+$/;
+const rfc6750ErrorDescriptionCharacters = /^[\u0020\u0021\u0023-\u005B\u005D-\u007E]+$/u;
 const challenge = (scheme, parameters) => {
-	const given = parameters.flatMap(([name, value]) => value === void 0 ? [] : [`${name}="${value.replace(/["\\]/g, "\\$&")}"`]);
+	const given = parameters.flatMap(([name, value]) => value === void 0 ? [] : [`${name}="${value.replaceAll(/["\\]/gu, "\\$&")}"`]);
 	return given.length === 0 ? scheme : `${scheme} ${given.join(", ")}`;
 };
 const bearer = (parameters) => challenge("Bearer", parameters);

package/dist/cli/commands.d.mts

@@ -1,8 +1,12 @@
 import "../contract/errors.mjs";
+import "../Event.mjs";
+import "../contract/progress.mjs";
+import "../contract/implementation.mjs";
+import { Each } from "../contract/stream.mjs";
 import { Any } from "../Action.mjs";
-import { Effect, Option, Runtime, Types } from "effect";
+import { Effect, Option, Runtime, Stream, Types } from "effect";
 import { CliError, Command } from "effect/cli";
-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 Field<A extends Any> = A["input"]["Encoded"] extends (infer E) ? true extends Types.IsUnion<E> ? never : E extends readonly 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> {
@@ -16,10 +20,10 @@ export interface Options<A extends Any> {
    */
   readonly description?: string;
   /**
-   * Human output: the decoded success to text for a person. Adds a `--json` flag to the
-   * command that selects JSON instead.
+   * Human output: the decoded success to text for a person, or of an action answering a stream
+   * each element to its line. Adds a `--json` flag to the command that selects JSON instead.
    */
-  readonly render?: (output: A["success"]["Type"]) => string;
+  render?(this: void, output: Each<A["success"]>): string;
   /**
    * 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