@gjermundgaraba/effect-actions 0.18.2 → 0.20.0

package/docs/Authentication-failures.md

@@ -1,99 +1,19 @@
 # Authentication failure modes
 
-What you see when something is wrong, and the fix. Search for a fragment of the message.
-Tasks: [Authentication.md](Authentication.md),
+What you see when something is wrong, and the fix: compiler diagnostics and errors the library
+does not word. Search for a fragment of the message. A message the library throws says its
+fix itself. Tasks: [Authentication.md](Authentication.md),
 [Authentication-advanced.md](Authentication-advanced.md).
 
 ## Types and startup
 
-- `Provider<CurrentUser, "notes-service.Login">` among a layer's requirements,
-  `Type 'Provider<...>' is not assignable to type 'never'` at `Layer.launch` or
-  `NodeRuntime.runMain`, or `Expected 2 arguments, but got 1` at a web handler's
-  `handler(request)`: a layer serving protected actions requires the provider of the descriptor
-  it names. Provide it, `Layer.provide(authenticate)`. Nothing else satisfies it: not the
-  identity itself, nor the provider of another descriptor, of the same identity or not
-  ([Verify credentials](Authentication.md#verify-credentials)).
-- `Authentication "<name>": the binding's descriptor is not its provider's`, a defect when
-  `ActionHttp.layer`, `ActionRpc.layer`, `ActionMcp.layerHttp` or `Authentication.protect`
-  builds: it names a descriptor built apart from the one `Authentication.layer` was given, such
-  as the same options passed to `make` twice, or a browser's static cookie descriptor served
-  with a provider built at startup. Build the server's surfaces and its provider from one
-  descriptor value.
-- `Protected action '<name>' requires its matching authentication descriptor` thrown by `make`
-  or `layer` of `ActionHttp` or `ActionRpc`, or by `ActionMcp.layerHttp`, or a type error there,
-  such as `No overload matches this call`, naming `authentication`,
-  `"Protected actions take options naming their authentication"` or
-  `"Authentication descriptor does not cover every protected action"`: a protected action is
-  served and no descriptor is named, or one of another identity than the action declares. Give
-  `{ authentication: Login }`.
-- `Invalid authentication name: "<name>", not an OpenAPI key` thrown by `make`: the name holds a
-  character such as `/` or `:`. Use letters, digits, `_`, `.` and `-`.
-- `Authentication takes one native HttpApiSecurity scheme` thrown by `make`, or a type error on
-  its `security`: `security` is a record of schemes, or no native scheme. Omit `security` for
-  Bearer, or give one scheme.
-- `A protected resource is published only for a Bearer scheme` thrown by `layer` or
-  `refusalResponse`, or a type error on `protectedResource` at `layer`: the descriptor names a
-  scheme other than Bearer. Drop `protectedResource`, or authenticate with a Bearer descriptor.
-- Type error at `layer` on `verify`: the verifier fails with an error that is neither a refusal
-  nor one its descriptor declares, or succeeds with a value that is not the identity. Declare
-  the error in the descriptor's `error`, or map it to a refusal where it is the caller's.
-- `Authentication "<name>": error _tag "<tag>" is built in, and declared on every surface` thrown
-  by `make`: an `error` entry has the `_tag` of `InvalidInput`, `Unauthenticated` or `Forbidden`.
-  Fail with the built-in refusal itself, or give the error a `_tag` of its own.
-- A startup service that the Effect building a verifier yields is unsatisfied where the server
-  launches: provide it to the provider's layer,
-  `Authentication.layer(Login, build).pipe(Layer.provide(Directory.layer))`, or above it.
-- `Request<"Requires", Tenant>` still owed although the tenant middleware's layer is provided:
-  the middleware's layer is in one `Layer.provide([...])` array with the provider, whose
-  members do not provide to one another. Provide it in a later `Layer.provide` of its own
-  ([Read request context in a verifier](Authentication-advanced.md#read-request-context-in-a-verifier)).
+- `Provider<CurrentUser, "notes-service.Login">` among a layer's requirements, `Type 'Provider<...>' is not assignable to type 'never'` at `Layer.launch` or `NodeRuntime.runMain`, or `Expected 2 arguments, but got 1` at a web handler's `handler(request)`: a layer serving protected actions requires the provider of the descriptor it names, and nothing else satisfies it, neither the identity nor another descriptor's provider. Provide it, `Layer.provide(authenticate)` ([Verify credentials](Authentication.md#verify-credentials)).
+- `Property 'authentication' is missing`, or `No overload matches this call` with `"Protected actions take options naming their authentication"` or `"Authentication descriptor does not cover every protected action"`, at `ActionHttp.make`, `ActionRpc.make` or `ActionMcp.layerHttp`: a protected action is served and no descriptor is named. Give `{ authentication: Login }` ([Declare how callers sign in](Authentication.md#declare-how-callers-sign-in)).
+- `Type 'Other' is not assignable to type 'CurrentUser'` under `Descriptor<…>`, at `authentication`: the descriptor authenticates another identity than the action's `caller`. Name the descriptor made for the caller's identity service.
+- `is not assignable to type 'Forbidden | Unauthenticated'`, or `Property '…' is missing in type`, at `layer`'s verifier: it fails with an error that is neither a refusal nor one its descriptor declares, or succeeds with a value that is not the identity. Declare the error in the descriptor's `error`, or map it to a refusal where it is the caller's.
+- `Request<"Requires", Tenant>` still owed although the tenant middleware's layer is provided: it is in one `Layer.provide([...])` array with the provider, and an array's layers provide to the routes, not to one another. Provide it in a later `Layer.provide` of its own ([Read request context in a verifier](Authentication-advanced.md#read-request-context-in-a-verifier)).
 
-## Requests
+## Scopes
 
-- An action that must be authenticated answers without credentials: its contract states
-  `caller: Action.Anyone`. Make it protected; the surfaces then authenticate it, whatever its
-  handler reads.
-- A request the `Host` or `Origin` check should refuse gets a 401 and a challenge: the check is
-  the layer's own `middleware`, which runs inside authentication. Make it global router
-  middleware
-  ([Run a request policy before authentication](Authentication-advanced.md#run-a-request-policy-before-authentication)).
-- An MCP host asks for sign-in when it connects: every tool of the endpoint is protected, or
-  the host opens a session with `initialize`, as a client of MCP 2025 does, and a session's
-  every request authenticates wherever a protected tool is served. Only a 2026-07-28 request
-  lists the tools and calls a public one signed out, on an endpoint that serves public tools
-  too ([ActionMcp.md](ActionMcp.md#protect-tools)).
-- A verifier's declared error arrives as 422: the error states no `httpApiStatus`. Give it the
-  status it means, such as `{ httpApiStatus: 503 }`.
-- `ActionMcp.client` fails with an `McpCallError` whose `reason` is a `StatusError`, not a typed error, when the verifier fails
-  with an error its descriptor declares: over MCP that failure is the endpoint's HTTP answer,
-  before any tool runs. Pass the endpoint's descriptor as the client's `authentication`.
-- A route's `Cache-Control` is replaced by `no-store`: only a route's own answer keeps its
-  caching, and this response is a failure that enclosing middleware serialized.
-
-## Discovery and scopes
-
-- OAuth discovery returns 404, or an MCP client does not find the authorization server: the
-  request's path and query do not match `resource`'s exactly, or the provider is provided to no
-  served layer. Set `resource` to the endpoint's exact public URL, and provide the provider to
-  the routes served.
-- A request the `Host` or `Origin` policy refuses elsewhere still reads the OAuth discovery
-  document: the policy registered after the provider. Provide the policy in the last
-  `Layer.provide`
-  ([Run a request policy before authentication](Authentication-advanced.md#run-a-request-policy-before-authentication)).
-- An MCP client asks a user who only reads to consent to writes on first login: the 401 names no
-  scope, so the client requests every one of `scopesSupported`. Give `scopesRequired`.
-- An MCP client reports `InsufficientScopeError` instead of re-authorizing: it has no OAuth
-  provider configured. Configure one, or grant the scope up front.
-- `new Action.Forbidden({ scopes })` throws a schema validation error, or
-  `Invalid scope in scopesRequired: "<scope>"`, or `in scopesSupported`, is thrown by `layer` or
-  `refusalResponse`, or is a defect when a resource an Effect builds is built: a scope is no
-  OAuth scope token (it is empty, or holds a space, `"` or `\`). Give each scope as its own
-  element.
-- `A protected resource has no fragment: <resource>` thrown by `layer` or `refusalResponse`, or
-  a defect when a resource an Effect builds is built: `resource` has a `#fragment`, which no
-  request URL carries. Drop the fragment.
-
-## Refusing outside the router
-
-- `Not a refusal, nor an error the authentication declares` thrown by `refusalResponse`: the
-  error is neither, or the descriptor declaring it was not given. Pass `authentication`.
+- `Schema validation failed` thrown by `new Action.Forbidden({ scopes })`: a scope is no OAuth scope token, being empty or holding a space, `"`, `\` or a character outside printable ASCII. Give each scope as its own element.
+- An MCP client reports `InsufficientScopeError` instead of re-authorizing: it has no OAuth provider configured. Configure one, or grant the scope up front.

package/docs/Authentication.md

@@ -4,158 +4,137 @@ How a remote caller proves the identity a protected action declares. `Authentica
 declares it, as a browser-safe descriptor; `Authentication.layer` is that descriptor's provider,
 running the verifier you write. Verifying a token, login and consent stay in the application.
 
-Read this page alone, in one tool call; if its output says it was truncated, read it again alone.
-When something fails, search [Authentication-failures.md](Authentication-failures.md). Reading
-order: [README.md](README.md).
-
-## API
-
-Import `@gjermundgaraba/effect-actions/Authentication`.
-
-| API                                           | Purpose                                                                                               |
-| --------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `make(name, identity, { security, error }?)`  | A browser-safe authentication descriptor: how a caller proves `identity`, by one native scheme.       |
-| `layer(descriptor, verify, options?)`         | Its provider: the server-only verifier, or an Effect building it once per layer graph, and discovery. |
-| `Any`                                         | Any descriptor, erased: what a binding's and an MCP endpoint's `authentication` take.                 |
-| `Descriptor`, `Provider`                      | What `make` and `layer` return, to name in a package that emits declarations.                         |
-| `Verify`, `Options`, `LayerOptions`           | The verifier's type, and `make`'s and `layer`'s options.                                              |
-| `ProtectedResource`                           | An OAuth protected resource.                                                                          |
-| `protect`, `bearerTokenOf`, `refusalResponse` | In [Authentication-advanced.md](Authentication-advanced.md#api), with their types and options.        |
-
-| Option              | Of      | Meaning                                                                                 |
-| ------------------- | ------- | --------------------------------------------------------------------------------------- |
-| `security`          | `make`  | One native `HttpApiSecurity` scheme; `HttpApiSecurity.bearer` when omitted.             |
-| `error`             | `make`  | What the verifier may fail with besides a refusal: one schema, or a list.               |
-| `protectedResource` | `layer` | Bearer only: an OAuth protected resource to publish, or an Effect building one or none. |
-
-| Protected resource field | Meaning                                                                                |
-| ------------------------ | -------------------------------------------------------------------------------------- |
-| `resource`               | Required exact OAuth resource identifier; its path and query select the discovery URL. |
-| `authorizationServers`   | Required, nonempty: where clients get tokens.                                          |
-| `scopesSupported`        | Optional OAuth scope tokens: every scope the resource accepts.                         |
-| `scopesRequired`         | Optional, nonempty OAuth scope tokens: every 401 names them.                           |
-| `resourceName`           | Optional human-readable name.                                                          |
+A message the library throws says its fix; for a compiler diagnostic or Effect's own error,
+search [Authentication-failures.md](Authentication-failures.md). For one symbol,
+`grep -rn <symbol> node_modules/@gjermundgaraba/effect-actions/dist/`: each declaration's JSDoc
+carries its rules and gotchas, and this page only what an example cannot show.
 
 ## Declare how callers sign in
 
 A protected action declares its identity service, `caller: CurrentUser`
 ([Action.md](Action.md#say-who-may-call-an-action)). Declare the descriptor beside that
-service, and name it in every binding and MCP endpoint that serves a protected action:
+service, in the contract file every client of the binding imports:
 
-```ts
-// identity/Identity.ts
+```ts example=notes-service/src/identity/Identity.ts
+import { Context, Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+
+export const scopes = { read: "notes:read", write: "notes:write" } as const;
+
+export const Scope = Schema.Literals([scopes.read, scopes.write]);
+
+export interface User {
+  readonly id: string;
+  readonly scopes: ReadonlyArray<typeof Scope.Type>;
+}
+
+/**
+ * Who is calling. A protected action declares it, `caller: CurrentUser`; authentication
+ * provides it per request, and a local host, such as the stdio server, provides it itself.
+ */
+export class CurrentUser extends Context.Service<CurrentUser, User>()(
+  "notes-service/CurrentUser",
+) {}
+
+// How a remote caller proves it is CurrentUser: a bearer token, the default scheme. Clients
+// import this descriptor with the binding; its verifier, in verifier.ts, stays on the server.
 export const Login = Authentication.make("notes-service.Login", CurrentUser);
 
-// Api.ts
-export const Http = ActionHttp.make([GetStatus, ...Notes, WhoAmI], {
-  prefix: "/api",
-  authentication: Login,
+export const WhoAmI = Action.make("whoAmI", {
+  description: "Show who the credential identifies and which scopes it holds.",
+  success: { id: Schema.String, scopes: Schema.Array(Scope) },
+  readOnly: true,
+  caller: CurrentUser,
 });
 ```
 
-See [notes-service/src/identity/Identity.ts](../examples/notes-service/src/identity/Identity.ts)
-and [notes-service/src/Api.ts](../examples/notes-service/src/Api.ts). An MCP endpoint names it
-the same way ([notes-service/src/routes.ts](../examples/notes-service/src/routes.ts)), and so
-does an RPC binding ([live-rpc/src/Rpc.ts](../examples/live-rpc/src/Rpc.ts)).
-
-- Every client of the binding imports the descriptor: keep it in the contract file. Keep
-  `layer`, and what its verifier imports, in server-only modules.
-- The name is the descriptor's type identity: use one name for one declaration. It holds only
-  letters, digits, `_`, `.` and `-`.
-- A descriptor names one scheme, and a binding or an endpoint names one descriptor. There is no
-  fallback between schemes: a host accepting two credentials for one identity declares two
-  descriptors and serves them on two bindings or endpoints
-  ([kitchen-sink/src/identity/Identity.ts](../examples/kitchen-sink/src/identity/Identity.ts)).
-- Build a server's surfaces and its provider from one descriptor value. `ActionHttp.layer`,
-  `ActionRpc.layer`, `ActionMcp.layerHttp` and `Authentication.protect` refuse, when they build,
-  a descriptor that is another object than the one the provider was given, equal name and
-  options or not.
-- Protecting an action that tests already call breaks them. An `Action.client` call then owes
-  `Type 'CurrentUser' is missing … from type 'Scope'`: provide the caller around each call
-  ([Testing-failures.md](Testing-failures.md)). A test that builds `ActionMcp.layerHttp` itself
-  gets `Property 'authentication' is missing`: serve `routes` with `Testing.layer`
-  ([ActionMcp-failures.md](ActionMcp-failures.md)). A call over HTTP without a credential gets
-  `Unauthenticated` at run time.
-- A local surface has no remote caller and takes no descriptor: the host provides the identity
-  itself, for a CLI ([ActionCli.md](ActionCli.md#name-the-caller)), a Toolkit
-  ([ActionToolkit.md](ActionToolkit.md#name-the-caller)) and an MCP server over stdio
-  ([ActionMcp.md](ActionMcp.md#serve-tools-over-stdio)).
+Name it in every binding and MCP endpoint that serves a protected action: an HTTP binding
+([notes-service/src/Api.ts](../examples/notes-service/src/Api.ts)), an MCP endpoint
+([notes-service/src/routes.ts](../examples/notes-service/src/routes.ts)) and an RPC binding
+([live-rpc/src/Rpc.ts](../examples/live-rpc/src/Rpc.ts)); a local surface takes none
+([Action.md](Action.md#say-who-may-call-an-action)). The name's rules are on
+`Authentication.make`, the scheme's on `Authentication.Options.security`; a second credential
+for one identity is in
+[kitchen-sink/src/identity/Identity.ts](../examples/kitchen-sink/src/identity/Identity.ts).
+
+- **Protecting an action that tests already call breaks them**, at compile time
+  ([Testing-failures.md](Testing-failures.md),
+  [Authentication-failures.md](Authentication-failures.md#types-and-startup)), and a call over
+  HTTP without a credential gets `Unauthenticated` at run time.
 
 ## Verify credentials
 
-Write the verifier in a server-only module, give it to `Authentication.layer`, and provide that
-layer to every layer serving a protected action: `routes.pipe(Layer.provide(authenticate))`. The
-verifier takes the credential and succeeds with the identity, or fails with
-`Action.Unauthenticated`, `Action.Forbidden` or an error the descriptor declares. See
-[notes-service/src/identity/verifier.ts](../examples/notes-service/src/identity/verifier.ts) and
-[notes-service/src/routes.ts](../examples/notes-service/src/routes.ts).
-
-- **The library reads no token.** Everything that makes a credential valid is the verifier's to
-  check, with your authorization server's library: its signature, its expiry, and its audience.
-  A token issued for another resource fails with `Unauthenticated`. Only a missing or empty
-  credential is refused before the verifier runs.
-- **Never provide the identity service, or a tenant, at startup**, in a layer or around
-  `HttpRouter.serve` or the program. It does not satisfy the provider a protected route
-  requires, and a public handler or a route of your own reading it would serve every caller as
-  that identity. A test sends a credential instead
-  ([Testing.md](Testing.md#test-as-a-signed-in-caller)).
-- A verifier that needs startup services, such as a user directory, is passed as an Effect that
-  yields them and returns the verifier: a builder ([Action.md](Action.md#implement-actions)),
-  run once per layer graph
-  ([kitchen-sink/src/identity/authenticate.ts](../examples/kitchen-sink/src/identity/authenticate.ts)).
-- Call `Authentication.layer` once per descriptor and provide that one value wherever a
-  provider is required.
-- A failure that is not the caller's, such as an issuer the verifier cannot reach, is an error
-  the descriptor declares, with `{ httpApiStatus: 503 }`: an `Unauthenticated` would have the
-  caller sign in again
-  ([kitchen-sink/src/identity/Identity.ts](../examples/kitchen-sink/src/identity/Identity.ts),
-  [kitchen-sink/test/identity/identity.test.ts](../examples/kitchen-sink/test/identity/identity.test.ts)).
-- Over RPC the verifier runs for each message of a protected rpc, not once per connection
-  ([live-rpc/src/identity/verifier.ts](../examples/live-rpc/src/identity/verifier.ts),
-  [kitchen-sink/test/identity/session.test.ts](../examples/kitchen-sink/test/identity/session.test.ts)).
-
-What each surface answers a missing or refused credential with:
-[guarantees.md](guarantees.md#wire-behavior), as
-[notes-service/test/routes.test.ts](../examples/notes-service/test/routes.test.ts) asserts.
+Write the verifier in a server-only module, give it to `Authentication.layer` and provide that
+layer as [notes-service/src/routes.ts](../examples/notes-service/src/routes.ts) does. What the
+verifier takes, fails with and must check itself is on `Authentication.Verify`; where its layer
+goes, on `Authentication.layer`.
+
+```ts example=notes-service/src/identity/verifier.ts
+import { Config, Effect, Redacted } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import { Login, scopes } from "./Identity.js";
+import { users } from "./users.js";
+
+const isToken = (token: string): token is keyof typeof users => Object.hasOwn(users, token);
+
+// DEMO ONLY: a token is a user's name. A real verifier checks a signed token with your
+// authorization server's library, its audience included. An unknown token is the built-in
+// `Unauthenticated`: a 401 every client decodes.
+const verify = (token: Redacted.Redacted<string>) => {
+  const name = Redacted.value(token);
+
+  return isToken(name)
+    ? Effect.succeed(users[name])
+    : Effect.fail(new Action.Unauthenticated({ message: "Unknown demo token." }));
+};
+
+// Server only: `Login`'s provider. As an OAuth protected resource it also publishes discovery,
+// so an MCP client that gets a 401 finds where to sign in, asking for read first. The resource
+// is the server's public URL, known only at startup, so it is read from config.
+export const authenticate = Authentication.layer(Login, verify, {
+  protectedResource: Effect.map(
+    Config.String("PUBLIC_URL").pipe(Config.withDefault("http://localhost:3000")),
+    (url) =>
+      ({
+        resource: `${url}/mcp`,
+        // DEMO ONLY: no server is there. Yours is your authorization server's issuer.
+        authorizationServers: ["https://auth.example.com"],
+        scopesSupported: [scopes.read, scopes.write],
+        scopesRequired: [scopes.read],
+      }) satisfies Authentication.ProtectedResource,
+  ),
+});
+```
+
+For a verifier built from startup services, see `authenticateBearer` in
+[kitchen-sink/src/identity/authenticate.ts](../examples/kitchen-sink/src/identity/authenticate.ts);
+for a failure that is not the caller's, `Authentication.Options.error` and `IssuerUnavailable` in
+[kitchen-sink/src/identity/Identity.ts](../examples/kitchen-sink/src/identity/Identity.ts); to
+test as a signed-in caller, [Testing.md](Testing.md#test-as-a-signed-in-caller). What each
+surface answers a missing or refused credential with is on `Action.Unauthenticated` and
+`Action.Forbidden`, as
+[kitchen-sink/test/identity/identity.test.ts](../examples/kitchen-sink/test/identity/identity.test.ts)
+asserts, status and challenge included.
 
 ## Publish OAuth discovery
 
-Give a Bearer descriptor's `layer` a `protectedResource`. The provider then publishes OAuth
-protected-resource discovery (RFC 9728) and names it in every challenge, so an MCP client that
-gets a 401 finds the authorization server. Without it the challenge names nowhere to sign in,
-so an MCP endpoint whose users sign in through OAuth publishes it. See
-[notes-service/src/identity/verifier.ts](../examples/notes-service/src/identity/verifier.ts)
-and [kitchen-sink/test/identity/identity.test.ts](../examples/kitchen-sink/test/identity/identity.test.ts).
-
-- `resource` is the exact public URL of the endpoint clients connect to: discovery is served at
-  `/.well-known/oauth-protected-resource` followed by its path. Only the deployment knows that
-  URL, so give the resource as an Effect reading configuration; succeeding with `undefined`
-  publishes nothing.
-- That `resource` and `authorizationServers` are HTTPS, or loopback HTTP in development, is the
-  deployment's to ensure: the provider does not check it.
-- Give `scopesRequired` whenever some actions need scopes others do not. An MCP client requests
-  the scopes a 401 names, or every one of `scopesSupported` when it names none.
-- Discovery is public. It answers before routing, to any origin, so no authentication and no
-  route middleware covers it: to restrict who reads it, see
-  [Run a request policy before authentication](Authentication-advanced.md#run-a-request-policy-before-authentication).
+For an MCP endpoint whose users sign in through OAuth, give the Bearer descriptor's `layer` a
+`protectedResource`, as the verifier above does. Its rules are on
+`Authentication.LayerOptions.protectedResource` and on each field of
+`Authentication.ProtectedResource`;
+[kitchen-sink/test/identity/identity.test.ts](../examples/kitchen-sink/test/identity/identity.test.ts)
+asserts the discovery it serves. To restrict who reads it, see
+[Run a request policy before authentication](Authentication-advanced.md#run-a-request-policy-before-authentication).
 
 ### Step up for a scope
 
-A step-up refusal is one an OAuth client acts on: `Action.Unauthenticated`, which it signs in
-on, or an `Action.Forbidden` naming `scopes`, which it re-authorizes on with those scopes
-added. The authorizer, a handler or the verifier may fail with one:
-[notes-service/src/identity/authorize.ts](../examples/notes-service/src/identity/authorize.ts).
-
-- Step-up is a Bearer descriptor's, for protected actions and routes under `protect`: the
-  refusal answers the request with 401 or 403 and its challenge, over MCP in place of the tool
-  result unless the response has started ([guarantees.md](guarantees.md#wire-behavior)).
-- On a public action or under another scheme, an authorizer's or a handler's refusal is
-  answered like a declared error, and RPC never steps up: a refusal is the call's typed failure
-  ([guarantees.md](guarantees.md#wire-behavior)).
-- Name scopes only when re-authorizing can grant them: a server with fixed tokens, such as API
-  keys, leaves `scopes` out. A `Forbidden` without them prompts no login
-  ([kitchen-sink/src/identity/authenticate.ts](../examples/kitchen-sink/src/identity/authenticate.ts));
-  what it answers on each surface is in [guarantees.md](guarantees.md#wire-behavior).
-- Map another service's refusals before failing with them
-  ([Action.md](Action.md#fail-with-declared-and-built-in-errors)): passed on, a `Forbidden`
-  naming that service's scopes sends this server's caller to re-authorize for them.
+To have an OAuth client sign in again, or re-authorize with more scopes, fail the authorizer, a
+handler or the verifier with `Action.Unauthenticated`, or with `Action.Forbidden` naming
+`scopes`
+([notes-service/src/identity/authorize.ts](../examples/notes-service/src/identity/authorize.ts));
+`inService` in
+[kitchen-sink/src/identity/authenticate.ts](../examples/kitchen-sink/src/identity/authenticate.ts)
+refuses with none. What each answers on each surface, and when to name scopes, are on those two
+classes.

package/docs/README.md

@@ -7,8 +7,7 @@ same schemas, handler and authorization.
 
 ## How to read these pages
 
-**Arriving with an error?** Search the `*-failures.md` pages for a fragment of its message
-first (step 5), before the examples and the pages.
+**Arriving with an error?** A message the library throws says its fix; for any other, step 5.
 
 1. **Open one page per tool call, with your file-reading tool.** Pages are kept small to reduce
    truncation. Several in one call, however many commands it runs, can be cut by its output
@@ -17,13 +16,13 @@ first (step 5), before the examples and the pages.
 2. **Start from the example closest to what you are building** ([Examples](#examples)). Its
    README has a layout tree, and all but quickstart's a "Where to look" table naming the file
    for each thing. Copy its layout and idioms: the examples are the reference for how code is
-   written. An example shows one way, not the rules, the alternatives or the traps: read steps
-   3 and 4 even when it fits.
+   written, and its comments carry the traps it shows. An example shows one way, not the rules
+   or the alternatives: read steps 3 and 4 even when it fits.
 3. **Read [Action.md](Action.md) completely.** Every surface builds on it.
 4. **Read the page of each surface you serve** ([Pages](#pages)), and the example files its task
    sections link.
-5. **When something fails, search the `*-failures.md` pages** for a fragment of the message
-   without quotes, your own code's first compile error included, before reasoning it out:
+5. **For a compiler diagnostic or Effect's own error, search the `*-failures.md` pages** for a
+   fragment of the message without quotes, your own code's first compile error included:
    `grep -rnF "<fragment>" node_modules/@gjermundgaraba/effect-actions/docs/*-failures.md`. Each
    module page has one beside it, such as [Action-failures.md](Action-failures.md).
 
@@ -33,28 +32,23 @@ A service others call is [notes-service](../examples/notes-service/) plus
 
 Where things are, in a project that installs the package: these pages in
 `node_modules/@gjermundgaraba/effect-actions/docs/`, the examples in `examples/` beside them, and
-the declarations with their JSDoc, the reference for signatures, in `dist/<Module>.d.mts`, all at
-the installed version. Install first ([setup.md](setup.md#install)): it needs TypeScript 7 and
-one Effect release. Every module is a subpath import, `@gjermundgaraba/effect-actions/Action`;
-there is no package root.
+the declarations with their JSDoc, the reference for signatures, under `dist/`, all at
+the installed version. Install first ([setup.md](setup.md#install)).
 
 ## Pages
 
-| Read                                                     | When you need to                                                                                                                            |
-| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| [setup.md](setup.md)                                     | install, write `tsconfig.json`, import the modules, write the minimal program, lay out an application, bundle a browser client              |
-| [Action.md](Action.md)                                   | define a contract and who may call it, implement it, authorize calls, fail with declared and built-in errors                                |
-| [Action-in-process.md](Action-in-process.md)             | call actions from your own code, such as a job; share one build of the implementations across servers and jobs                              |
-| [ActionHttp.md](ActionHttp.md)                           | bind actions to JSON routes, serve them, limit request bodies, publish OpenAPI, call them from Effect or a browser                          |
-| [ActionMcp.md](ActionMcp.md)                             | serve MCP tools over HTTP or stdio, describe them to a model, return images, protect them, allow browser clients, add prompts and resources |
-| [ActionRpc.md](ActionRpc.md)                             | bind actions to Effect rpcs, serve them on a protocol, call them, send request context with a call                                          |
-| [ActionToolkit.md](ActionToolkit.md)                     | give a model actions as a native Effect AI `Toolkit`, name the caller, ask for approval                                                     |
-| [ActionCli.md](ActionCli.md)                             | run actions as local commands, or call a server from commands; shape flags, input and output; add a command of your own                     |
-| [Authentication.md](Authentication.md)                   | declare how callers sign in, verify credentials, publish OAuth discovery, step up for a scope                                               |
-| [Authentication-advanced.md](Authentication-advanced.md) | use an API key or a cookie, read the request in a verifier, protect a route of your own, run a request policy before authentication         |
-| [Testing.md](Testing.md)                                 | test an implementation in process, and routes, tools and rpcs in memory, as a signed-in caller; assert on errors                            |
-| [guarantees.md](guarantees.md)                           | see the status and body of one case, such as bad input, a declared error or a refusal, on each surface; what the library leaves to you      |
-| [CONTEXT.md](CONTEXT.md)                                 | look up a term the pages use                                                                                                                |
+| Read                                                     | When you need to                                                                                                                                                      |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [setup.md](setup.md)                                     | install, write `tsconfig.json`, import the modules, write the minimal program, lay out an application, bundle a browser client                                        |
+| [Action.md](Action.md)                                   | define a contract and who may call it, implement it, authorize calls, fail with declared and built-in errors, call actions from a job, share one build across servers |
+| [ActionHttp.md](ActionHttp.md)                           | bind actions to JSON routes, serve them, limit request bodies, split a binding across layers and add middleware, publish OpenAPI, call them from Effect or a browser  |
+| [ActionMcp.md](ActionMcp.md)                             | serve MCP tools over HTTP or stdio, describe them to a model, return images, protect them, allow browser clients, add prompts and resources, send notifications       |
+| [ActionRpc.md](ActionRpc.md)                             | bind actions to Effect rpcs, serve them on a protocol, call them, send request context with a call                                                                    |
+| [ActionToolkit.md](ActionToolkit.md)                     | give a model actions as a native Effect AI `Toolkit`, name the caller, ask for approval                                                                               |
+| [ActionCli.md](ActionCli.md)                             | run actions as local commands, or call a server from commands; shape flags, input and output; name the caller; add a command of your own                              |
+| [Authentication.md](Authentication.md)                   | declare how callers sign in, verify credentials, publish OAuth discovery, step up for a scope                                                                         |
+| [Authentication-advanced.md](Authentication-advanced.md) | use an API key or a cookie, read the request in a verifier, protect a route of your own, run a request policy before authentication                                   |
+| [Testing.md](Testing.md)                                 | test an implementation in process, and routes, tools and rpcs in memory, as a signed-in caller; assert on errors                                                      |
 
 ## Examples
 
@@ -67,10 +61,8 @@ there is no package root.
 | [live-rpc](../examples/live-rpc/)           | Effect RPC over a WebSocket with a browser-shaped client, each message carrying its own token.                   | A client keeps a connection open, or the application speaks Effect RPC. |
 | [kitchen-sink](../examples/kitchen-sink/)   | The reference: a multi-tenant issue tracker using every module and nearly every option, with an index.           | You need a working use of one specific feature.                         |
 
-Each example's README says where to look for what. The index in
-[kitchen-sink](../examples/kitchen-sink/README.md#index) maps every export and option it uses to
-a file. Every token, user and store in the examples is a demo, marked `DEMO ONLY` where it must
-change before a deployment.
+The index in [kitchen-sink](../examples/kitchen-sink/README.md#index) maps every export and
+option it uses to a file.
 
 ## Choose a surface
 
@@ -85,4 +77,27 @@ change before a deployment.
 
 Surfaces combine: every one that runs handlers takes the same implementations, one or a list,
 and enforces each contract's `caller` and its implementation's `authorize`
-([Action.md](Action.md#authorize-calls)).
+([Action.md](Action.md#authorize-calls)). What a call answers on each surface, a success, bad
+input, a declared error, a refusal or a defect, is on `ActionHttp.layer`, `ActionMcp.layerHttp`
+and `runStdio`, `ActionRpc.layer`, `ActionToolkit.make`, `ActionCli.command`, each typed client,
+and each built-in error: grep the symbol.
+
+## What the library leaves to you
+
+- **Verify credentials or issue them.** The application writes the verifier
+  ([Authentication.md](Authentication.md#verify-credentials)), and login, consent and token
+  issuance are its own. The library defines no scopes: a `Forbidden` names the scopes a call
+  needs, and the library answers with the OAuth challenge
+  ([Authentication.md](Authentication.md#step-up-for-a-scope)); which scheme speaks OAuth is on
+  `Authentication.Options`'s `security`.
+- **Decide who may do what.** It runs the `authorize` an implementation states and writes no rule
+  of its own ([Action.md](Action.md#authorize-calls)).
+- **Filter tool discovery by caller.** What `tools/list` shows a signed-out caller, and the
+  endpoint split that hides protected tools, are on `ActionMcp.LayerHttpOptions`'s
+  `authentication`.
+- **Limit requests.** A rate limit is the handler's, failing with an error its action declares, or
+  middleware's ([Action.md](Action.md#authorize-calls)); the request body limit is the host's
+  ([ActionHttp.md](ActionHttp.md#serve-the-routes)).
+- **Allow browsers across origins.** CORS for JSON routes is the host's, with `HttpRouter.cors`;
+  an MCP endpoint refuses a browser `Origin` it does not list
+  ([ActionMcp.md](ActionMcp.md#allow-browser-clients)).

package/docs/Testing-failures.md

@@ -6,16 +6,12 @@ A missing service's error can start
 beneath it, `is missing the following properties from type 'Scope'`, instead.
 The tasks are in [Testing.md](Testing.md).
 
-- A route answers an empty 500, which a client method reports as `HttpClientError: Decode error (500 …)`: a defect, or a result that does not encode. `Testing.layer` logs the cause as an error on the process console, under `it.effect` too, and nothing for a request that succeeds or is refused: read the test's output, or collect it with a `Logger` or an `ErrorReporter` provided around the layer.
-- A client method fails with `Action.Unauthenticated`: routes under `Testing.layer` keep their real authentication. Give the client a credential in `transformClient` ([Test as a signed-in caller](Testing.md#test-as-a-signed-in-caller)).
-- A protected route answers 401 where the test expects 415 or 400: authentication runs before the body is read. Send a valid credential.
+- A route answers an empty 500, which a client method reports as `HttpClientError: Decode error (500 …)`: a defect, or a result that does not encode. `Testing.layer(routes)` logs its cause on the process console, under `it.effect` too: read the test's output, or collect it with a `Logger` provided around the layer.
 - `Type 'Provider<CurrentUser, "notes-service.Login">' is missing the following properties from type 'Scope'` at `it.effect`, or `… is not assignable to type 'never'` at `Effect.runPromise`: the routes serve a protected action without a provider of its descriptor. Provide the real one or a test verifier to the routes; a caller provided around `Testing.layer` does not satisfy them.
 - `Type 'CurrentUser' is missing the following properties from type 'Scope'` at `it.effect`, or `… is not assignable to type 'never'` at `Effect.runPromise`: the test still owes the identity. An `Action.client` call of a protected action takes its caller per call: provide it around the call. Or a public action's handler reads the identity, which no route provides to it: make the action protected. Or, where the caller is provided already, a builder yields it: move that `yield*` into the handler ([Action-failures.md](Action-failures.md#where-an-implementation-is-served)).
 - `Type '<Service>' is missing the following properties from type 'Scope'` at every `it.effect`, for a service that is no identity, such as a store, a limiter or a `LanguageModel`: a builder now yields it, and the routes require it. Provide its layer to `Testing.layer(routes)`, as the entrypoint provides it to the server.
 - `Type 'unknown' is not assignable to type 'Scope'` at `it.effect`, or `Argument of type 'Effect<…>' is not assignable` at an `Effect.flip` or `Effect.exit`, around a loop over an array of calls to different actions: their successes and errors differ, so the array has no one element type. Annotate it, `ReadonlyArray<Effect.Effect<unknown, unknown>>`, with the caller as a third parameter for `Action.client` calls of protected actions, or assert each call on its own.
-- An rpc call never answers under `Testing.layer`, and nothing is logged: the layer holds the rpc layer twice, under two protocols, and built it for the other one, a WebSocket. Give the rpc layer its WebSocket in the entrypoint, so the routes a test serves hold it once, under the test's protocol ([Serve the rpcs](ActionRpc.md#serve-the-rpcs)).
 - `Property '<field>' does not exist on type 'MethodError<Action<…>>'`, or on a built-in error, after `expect(error).toBeInstanceOf(…)`: `toBeInstanceOf` does not narrow the union of the action's errors. Compare with `toEqual(new X({ … }))`, or narrow with `instanceof` ([Assert on errors](Testing.md#assert-on-errors)).
-- A test passes whatever message an error carries: `toEqual` never compares a tagged error's `message`. Assert it separately ([Assert on errors](Testing.md#assert-on-errors)).
-- The test reads a service the handlers never changed: it was provided inside the routes and again to the test, two instances. Provide it once, around `Testing.layer`, with `Layer.provideMerge`.
+- `Type 'Handler<"<rpc>">' is missing the following properties from type 'Scope'` at `it.effect`, after `RpcTest.makeClient(binding.group)`: Effect's `RpcTest` asks for handlers of the group, which `ActionRpc.layer` does not provide. Serve the rpc layer under `Testing.layer` with Effect's HTTP protocol and call it with `ActionRpc.client` ([Test rpcs](Testing.md#test-rpcs)).
 - A builder or handler fails with `NotFound: FileSystem.<method> (<path>)` for a file that exists, or a file route answers 500: with no `FileSystem` provided around `Testing.layer`, the routes read a no-op one. Provide `NodeFileSystem.layer` or `NodeServices.layer`. In a command test, the nearer of two provided is read: provide a fake `FileSystem` on the command, inside `NodeServices.layer`.
 - `Argument of type 'Layer<…, FileSystem | Generator | HttpPlatform | HttpRouter | Path>' is not assignable` at `HttpRouter.toWebHandler(routes)`: a web handler's routes need the platform services `Testing.layer(routes)` supplies itself. Provide `HttpServer.layerServices` to them.