@gjermundgaraba/effect-actions 0.19.0 → 0.21.0

package/dist/Authentication.d.mts

@@ -1,12 +1,12 @@
+import { Codec } from "./contract/codec.mjs";
 import { Refusal } from "./contract/errors.mjs";
 import { Known, OptionalUnless } from "./contract/implementation.mjs";
 import { Errors } from "./Action.mjs";
-import { Any, Descriptor, Provider, Security } from "./authentication/provider.mjs";
 import { ErrorsOf } from "./contract/declared.mjs";
-import { Array, Context, Effect, Layer, Option, Redacted, Scope } from "effect";
+import { Any, Descriptor, Provider, Security } from "./authentication/provider.mjs";
+import { Array, Context, Effect, Layer, Option, Redacted, Schema, 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: the scheme matched case-insensitively,
@@ -14,16 +14,18 @@ import { HttpApiSecurity } from "effect/http-api";
  * 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>>;
+export declare const bearerTokenOf: (authorization: string | null | undefined) => Option.Option<Redacted.Redacted>;
 /** An OAuth protected resource (RFC 9728), as `layer` publishes it. */
 export interface ProtectedResource {
   /**
-   * 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.
+   * OAuth resource identifier: the public URL of the endpoint clients connect to, such as
+   * `${url}/mcp`, or its origin, such as `https://api.example.com`, which MCP allows to name one
+   * resource for every endpoint it serves. Discovery is served at
+   * `/.well-known/oauth-protected-resource` followed by its path and query.
    *
    * **Gotchas**
    *
+   * - A client applying RFC 9728 §3.3 strictly finds no authorization server for an origin, since metadata reached from a challenge must name the URL it requested; the official MCP client accepts it, and the endpoint's URL works with both.
    * - 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.
    */
@@ -34,7 +36,7 @@ export interface ProtectedResource {
    * Every scope the resource accepts, each an OAuth scope token, which a client requests when a
    * 401 names none.
    */
-  readonly scopesSupported?: ReadonlyArray<string>;
+  readonly scopesSupported?: readonly string[];
   /**
    * The scopes every 401 names, each an OAuth scope token: what a client requests when it
    * authenticates, rather than every scope supported.
@@ -79,8 +81,8 @@ type DeclaredOf<D> = D extends {
  * 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 {
+/** What `make` takes besides the name and the identity `A`. */
+export interface Options<A = unknown> {
   /**
    * 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" })`,
@@ -101,7 +103,35 @@ export interface Options {
    * - 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];
+  /**
+   * The stable id of an identity, such as its user id: what tells subscribers apart where a
+   * surface keeps a subscription between requests, such as an MCP poll subscription's lease.
+   *
+   * **Gotchas**
+   *
+   * - A surface serving a protected event type whose source has a `subscription` hook refuses to start without it, its message naming this option.
+   * - Two identities with one principal share those subscriptions, so give each its own: a tenant's id alone merges its users.
+   * - Without it no surface offers a protected event by webhook, which a subscription keys by its principal: the listing names no webhook, and a webhook subscription fails with `Event.SubscriptionError`, reason `Unsupported`.
+   * - Without it every caller shares one idempotency key space: another caller sending a key with the same input is given the first call's answer, as `Action.Options.idempotencyKey` says.
+   */
+  readonly principal?: ((identity: A) => string) | undefined;
+  /**
+   * The identity's schema, its `Type` the identity: how a surface keeps an identity past a
+   * restart, as `Webhook.layer` with `persist` keeps each webhook subscriber's, its JSON in the
+   * store.
+   *
+   * **Gotchas**
+   *
+   * - `Webhook.layer` with `persist` refuses to serve a protected event by webhook without it, its message naming this option.
+   */
+  readonly schema?: Codec | undefined;
 }
+type PrincipalOf<A> = NoInfer<Pick<Options<A>, "principal">>;
+type SchemaOf<O, A> = O extends {
+  readonly schema: infer S extends Schema.Top;
+} ? [S["Type"], A] extends [A, S["Type"]] ? unknown : {
+  readonly schema: "a schema whose Type is the identity's";
+} : unknown;
 type SecurityOf<O> = O extends {
   readonly security: infer S extends Security;
 } ? S : "security" extends keyof O ? NonNullable<O["security" & keyof O]> | HttpApiSecurity.Http : HttpApiSecurity.Http;
@@ -112,7 +142,7 @@ type SecurityOf<O> = O extends {
  * 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>>;
+export declare const make: <const Name extends string, I, A, const O extends Options<never> = {}>(name: Name, identity: Context.Key<I, A>, ...options: OptionalUnless<O, O & NoInfer<Known<O, Options>> & PrincipalOf<A> & SchemaOf<O, A>>) => 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
@@ -155,6 +185,7 @@ type Resource = ProtectedResource | Effect.Effect<ProtectedResource | undefined,
  * **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.
+ * - Over `ActionRpc` a verifier reading `HttpServerRequest` reads one holding the message's headers alone, a socket's upgrade headers before its own, at `/` with no query or body, on every protocol: one judging the URL or query sees none of the client's.
  */
 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`. */
@@ -190,5 +221,4 @@ export type Protection<I, Name extends string> = HttpRouter.Middleware<{
  * - 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

@@ -2,11 +2,11 @@ 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 { Context, Effect, Function, 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
-const bearerAuthorizationHeader = /^[ \t]*Bearer +(.*[^ \t])[ \t]*$/i;
+// src/authentication/Authentication.ts
+const bearerAuthorizationHeader = /^[ \t]*Bearer +(?<token>.*[^ \t])[ \t]*$/iu;
 /**
 * The bearer token of an `Authorization` header, `authorization`, or none, read as Effect's
 * `HttpApiSecurity.bearer` reads it for routes and MCP: the scheme matched case-insensitively,
@@ -14,7 +14,7 @@ const bearerAuthorizationHeader = /^[ \t]*Bearer +(.*[^ \t])[ \t]*$/i;
 * 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 bearerTokenOf = (authorization) => Option.map(Option.fromNullishOr(bearerAuthorizationHeader.exec(authorization ?? "")?.groups?.["token"]), (token) => Redacted.make(token));
 const metadataUrlOf = (options) => {
 	const resource = new URL(options.resource);
 	const url = new URL(resource);
@@ -43,10 +43,13 @@ const assertPublishableResource = (oauth, options) => {
 	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, {
+const withNoStoreAndChallenge = (response, wwwAuthenticate) => 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 } : {}
+	...wwwAuthenticate !== void 0 && response.status === 401 && response.headers["www-authenticate"] === void 0 ? { "www-authenticate": wwwAuthenticate } : {}
 });
+const isBearer = (security) => Predicate.isTagged(security, "Http") && security.scheme.toLowerCase() === "bearer";
+const openApiComponentKey = /^[\w.-]+$/u;
+const nonBearerChallengeOf = (security, name) => Match.value(security).pipe(Match.tag("Http", ({ scheme }) => challenge(scheme, [])), Match.tag("Basic", () => challenge("Basic", [["realm", name]])), Match.tag("ApiKey", Function.constUndefined), Match.exhaustive);
 /**
 * 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
@@ -60,15 +63,29 @@ const refusalResponse = (error, options) => {
 	const oauth = authentication === void 0 || isBearer(authentication.security);
 	assertPublishableResource(oauth, options?.protectedResource);
 	const named = namedOf(options?.protectedResource);
-	const challenge = authentication !== void 0 && !oauth ? nonBearerChallengeOf(authentication.security, authentication.name) : bearerChallengeOf(named, presentsBearerToken(options?.authorization));
+	const wwwAuthenticate = 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: pass the descriptor declaring it as `authentication`, or answer the error yourself");
-		return withNoStoreAndChallenge(response, challenge);
+		return withNoStoreAndChallenge(response, wwwAuthenticate);
 	}
-	return withNoStoreAndChallenge(oauth ? answer(error, named.metadataUrl) : plain(error), challenge);
+	return withNoStoreAndChallenge(oauth ? answer(error, named.metadataUrl) : plain(error), wwwAuthenticate);
+};
+const mayResolveToDiscoveryPath = /\.well-known|[\t\n\r]/u;
+const corsPreflight = (request) => {
+	const requested = request.headers["access-control-request-headers"];
+	return HttpServerResponse.empty({
+		status: 204,
+		headers: {
+			"access-control-allow-origin": "*",
+			"access-control-allow-methods": "GET, HEAD, OPTIONS",
+			...requested === void 0 ? {} : {
+				"access-control-allow-headers": requested,
+				vary: "Access-Control-Request-Headers"
+			}
+		}
+	});
 };
-const mayResolveToDiscoveryPath = /\.well-known|[\t\n\r]/;
 const discoveryMiddleware = (options) => {
 	const discoveryUrl = metadataUrlOf(options);
 	const target = discoveryUrl.href.slice(discoveryUrl.origin.length);
@@ -79,20 +96,6 @@ const discoveryMiddleware = (options) => {
 		scopes_supported: options.scopesSupported,
 		resource_name: options.resourceName
 	}, { headers: { "access-control-allow-origin": "*" } });
-	const corsPreflight = (request) => {
-		const requested = request.headers["access-control-request-headers"];
-		return HttpServerResponse.empty({
-			status: 204,
-			headers: {
-				"access-control-allow-origin": "*",
-				"access-control-allow-methods": "GET, HEAD, OPTIONS",
-				...requested === void 0 ? {} : {
-					"access-control-allow-headers": requested,
-					vary: "Access-Control-Request-Headers"
-				}
-			}
-		});
-	};
 	return (next) => Effect.flatMap(HttpServerRequest.HttpServerRequest, (request) => {
 		const targeted = mayResolveToDiscoveryPath.test(request.url) && URL.canParse(request.url, discoveryUrl.origin) && new URL(request.url, discoveryUrl.origin).href.slice(discoveryUrl.origin.length) === target;
 		if (targeted && (request.method === "GET" || request.method === "HEAD")) return Effect.succeed(metadata);
@@ -109,9 +112,6 @@ const resourceAnswersOf = (options) => {
 		published: options === void 0 ? void 0 : discoveryMiddleware(options)
 	};
 };
-const isBearer = (security) => Predicate.isTagged(security, "Http") && security.scheme.toLowerCase() === "bearer";
-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, and the scheme a caller proves it by, `Options.security`. The literal name
@@ -122,6 +122,8 @@ const nonBearerChallengeOf = (security, name) => Match.value(security).pipe(Matc
 const make = (name, identity, ...options) => {
 	const security = options[0]?.security ?? HttpApiSecurity.bearer;
 	const error = errorList(options[0]?.error);
+	const principal = options[0]?.principal;
+	const schema = options[0]?.schema;
 	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");
@@ -130,6 +132,8 @@ const make = (name, identity, ...options) => {
 		identity,
 		security,
 		error,
+		...principal === void 0 ? {} : { principal },
+		...schema === void 0 ? {} : { schema },
 		"~provider": Context.Service(`effect-actions/Authentication/Provider/${name}`),
 		"~middleware": HttpApiMiddleware.Service()(`effect-actions/Authentication/Security/${name}`, { security: { [name]: security } }),
 		"~verified": Context.Service(`effect-actions/Authentication/Verified/${name}`)
@@ -139,7 +143,7 @@ const presented = (credential) => Redacted.isRedacted(credential) ? Redacted.val
 function layer(authentication, verify, options = {}) {
 	const { security } = authentication;
 	const oauth = isBearer(security);
-	const protectedResource = options.protectedResource;
+	const { protectedResource } = options;
 	assertPublishableResource(oauth, protectedResource);
 	const resource = Effect.isEffect(protectedResource) ? Effect.map(protectedResource, (built) => {
 		assertPublishableResource(oauth, built);
@@ -153,17 +157,20 @@ function layer(authentication, verify, options = {}) {
 		if (!Predicate.isFunction(verifier)) return yield* Effect.die(/* @__PURE__ */ new Error("Missing verify: pass a verify function, or an Effect building one"));
 		const authenticate = (credential) => presented(credential) ? verifier(credential) : Effect.fail(missing);
 		const noStoreOnFailure = HttpEffect.appendPreResponseHandler((_request, response) => Effect.succeed(HttpServerResponse.setHeader(response, "cache-control", "no-store")));
-		const challengeOf = (credential) => !oauth ? nonBearerChallengeOf(security, authentication.name) : presented(credential) ? invalid : anonymous;
+		const challengeOf = (credential) => {
+			if (!oauth) return nonBearerChallengeOf(security, authentication.name);
+			return presented(credential) ? invalid : anonymous;
+		};
 		const refuse = (error) => isRefusal(error) ? Effect.succeed(oauth ? answer(error, metadataUrl) : plain(error)) : Effect.suspend(() => {
 			const response = declaredResponse(authentication.error, error);
 			return response === void 0 ? Effect.die(error) : Effect.succeed(response);
 		});
 		const verified = (credential, route, slot) => {
-			const challenge = challengeOf(credential);
+			const wwwAuthenticate = challengeOf(credential);
 			return Effect.matchEffect(authenticate(credential), {
 				onFailure: refuse,
 				onSuccess: (actor) => Effect.provideService(route, slot, actor)
-			}).pipe(Effect.onError(() => noStoreOnFailure), HttpEffect.withPreResponseHandler((_request, response) => Effect.succeed(withNoStoreAndChallenge(response, challenge))));
+			}).pipe(Effect.onError(() => noStoreOnFailure), HttpEffect.withPreResponseHandler((_request, response) => Effect.succeed(withNoStoreAndChallenge(response, wwwAuthenticate))));
 		};
 		return {
 			descriptor: authentication,
@@ -191,5 +198,4 @@ function layer(authentication, verify, options = {}) {
 * - 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 };